chore: record ZIP artifact task completion

2026-08-26 12:59:31 +08:00
parent eaa7c08f6a
commit 7e8fcd82ed
18 changed files with 338 additions and 3 deletions
--- a/.trellis/tasks/08-25-road-compiler-extraction/task.json
+++ b/.trellis/tasks/08-25-road-compiler-extraction/task.json
@@ -22,12 +22,13 @@
    "08-25-rc-p0-contract-baseline",
    "08-25-rc-p1-package-boundary",
    "08-25-rc-p2-repo-split",
-    "08-25-rc-p3-render-separation"
+    "08-25-rc-p3-render-separation",
+    "08-26-rc-p5-artifact-consumption"
  ],
  "parent": null,
  "relatedFiles": [],
-  "notes": "",
+  "notes": "P3 已完成。P5 artifact-only parent 已建立，P5A ZIP export 已在 road-compiler v0.3.0 完成；P5B 宿主 ZIP import 待实施。",
  "meta": {
    "next_task": "08-25-rc-p4-drawtonomy-ext"
  }
-}
+}
--- a/.trellis/tasks/08-26-rc-p5-artifact-consumption/check.jsonl
+++ b/.trellis/tasks/08-26-rc-p5-artifact-consumption/check.jsonl
@@ -0,0 +1,3 @@
+{"file":".trellis/spec/blender/testing.md","reason":"P3 scene digest parity 是消费迁移的回归门槛。"}
+{"file":".trellis/spec/pipeline/native-road-package.md","reason":"验证 ZIP 解压后的 v1.1 contract、areaId 和 source 集合。"}
+{"file":".trellis/spec/guides/artifact-parity-guide.md","reason":"验证导入迁移不改变 Blender 产物结构。"}
--- a/.trellis/tasks/08-26-rc-p5-artifact-consumption/design.md
+++ b/.trellis/tasks/08-26-rc-p5-artifact-consumption/design.md
@@ -0,0 +1,23 @@
+# P5 Artifact-Only Road Package Design
+
+P5 replaces the current runtime dependency boundary with a file-only boundary:
+
+```text
+road-compiler Web editor
+  -> deterministic root-flat native-road-package/v1.1 ZIP
+  -> osmWorkflow config nativeRoadPackage
+  -> private verified extraction cache
+  -> Blender / Cesium / preview
+```
+
+The road-compiler repository owns export and all editing/compiler internals. osmWorkflow owns ZIP safety,
+contract validation, Blender materials and downstream scene construction. Neither repository reads the
+other's source, configuration, overrides or runtime implementation.
+
+The ZIP is immutable input and the host's `_pipeline/native-road-import/<sha256>` is disposable cache.
+The host rejects unsafe archive topology before writing files, then validates v1.1 `manifest.json` and
+area identity before starting Blender. Stage manifests record the ZIP hash and resolved package records.
+
+P5A publishes a fixture/exporter first. P5B uses that fixture to remove compiler CLI installation and
+invocation from the host. The migration is intentionally a contract-preserving transport change: rendered
+geometry and material behavior must remain at the P3 baseline.
--- a/.trellis/tasks/08-26-rc-p5-artifact-consumption/implement.jsonl
+++ b/.trellis/tasks/08-26-rc-p5-artifact-consumption/implement.jsonl
@@ -0,0 +1,3 @@
+{"file":".trellis/spec/pipeline/native-road-package.md","reason":"宿主与编译器之间的现有文件契约。"}
+{"file":".trellis/spec/pipeline/external-tools.md","reason":"ZIP 导入必须在 Blender 副作用前完成安全校验。"}
+{"file":".trellis/spec/guides/cross-layer-thinking-guide.md","reason":"导出、Node 导入、Blender 和 preview 的跨层数据流。"}
--- a/.trellis/tasks/08-26-rc-p5-artifact-consumption/implement.md
+++ b/.trellis/tasks/08-26-rc-p5-artifact-consumption/implement.md
@@ -0,0 +1,14 @@
+# P5 Integration Plan
+
+1. Complete P5A in `road-compiler`: deterministic Web/CLI ZIP export plus supported-area fixtures and a
+   tagged compiler release.
+2. Complete P5B in `osmWorkflow`: safe importer, config migration, CLI/dependency removal and downstream
+   descriptor migration.
+3. Run the shared end-to-end gate on `fengshu-er-road` and `nantaizi-lake-innovation-valley`:
+   import ZIP -> Blender -> Cesium -> package -> preview -> area checks.
+4. Compare Blender scene digests to P3 control; run negative ZIP tests and legacy provider tests.
+5. Record contract docs in both repositories, commit each repository independently, then archive both
+   children and this integration parent.
+
+Integration rollback: restore the host's previous tagged compiler dependency and compile adapter. ZIP export
+is additive and its generated files remain valid standalone artifacts.
--- a/.trellis/tasks/08-26-rc-p5-artifact-consumption/prd.md
+++ b/.trellis/tasks/08-26-rc-p5-artifact-consumption/prd.md
@@ -0,0 +1,95 @@
+# 道路包导入与纯消费管线
+
+父任务：`.trellis/tasks/08-25-road-compiler-extraction/`
+
+本任务是集成 parent：导出与导入分别在 road-compiler 和宿主仓库实现，只有两个子任务的
+端到端 ZIP 契约都通过后才完成。
+
+## Goal
+
+让 road-compiler Web 导出的 `native-road-package/v1.1` 成为 Blender 管线的唯一
+native-road 输入。宿主只校验并消费完整道路包，不再安装、调用或理解道路编译器。
+
+用户价值：人工在 road-compiler Web 编辑后，导出道路包即可稳定交给 Blender / Cesium
+构建；编辑成果不再通过发布新的编译器代码版本传播。
+
+## Confirmed Facts
+
+- P3 已使 Blender 通过 `manifest.json` 消费 `layers/*.geojson`，并拒绝无效 manifest、
+  source/file 不一致和未知宿主材质槽。
+- 宿主当前仍通过 `scripts/build-area.js` 调用 `scripts/lib/road-compiler-cli.js`；后者安装并
+  运行 `@osm-asset/road-compiler`，将 `RoadCompilerInput` 写入 `_pipeline/`。
+- native Blender 构建当前强制使用 `outputs/<area>/native-road/`，并在每次构建前重新编译；
+  宿主还持有 `nativeRoad.edgeLines`、`junctionTemplates`、overrides 和 compiler runtime
+  路径等编译器内部概念。
+- `osm2streets` 是显式 legacy/debug provider，应保持现有行为。
+- 有效验证区域只有 `fengshu-er-road` 与 `nantaizi-lake-innovation-valley`；
+  `hanyang-block` 不参与。
+
+## Requirements
+
+### R1 纯产物边界
+
+- native provider 只接收一个完整 `native-road-package/v1.1` 目录。
+- 宿主不得依赖 `@osm-asset/road-compiler`，不得调用 compiler CLI，不得写
+  `RoadCompilerInput`，不得读取或解释 compiler overrides / junction templates。
+- 宿主以 manifest 作为道路图层事实源，Blender 不增加 compiler 专用图层表。
+
+### R2 ZIP 导入配置和校验
+
+- 每个 native 区域配置一个道路包 ZIP 路径；路径相对于区域配置文件解析并可指向工作区外的
+  road-compiler Web 导出文件。
+- ZIP 根目录必须直接包含 `manifest.json` 和契约定义的文件；不得接受多余顶层目录、绝对路径、
+  `..` 路径或符号链接。
+- 在启动 Blender 前，宿主将 ZIP 安全解压到其私有 pipeline staging 目录，校验 manifest
+  契约版本、`areaId` 和当前区域一致，并记录 ZIP hash 和展开文件记录到 stage manifest。
+- ZIP 永远只读：宿主不复制、覆盖或修改 road-compiler Web 的导出文件；成功或失败后仅清理
+  自己的临时解压目录。
+- Blender 继续校验 manifest 的图层、source、semantic 角色、材质槽和 splitBy 规则。
+
+### R3 后续阶段
+
+- Cesium、package、preview 和区域诊断从导入道路包读取原生车道中心线、signals 和
+  其他既有 native-road 输入；不重新编译或复制道路包。
+- build stage manifest 将道路包作为外部输入记录，而非宿主输出。
+
+### R4 清理和迁移
+
+- 删除宿主对 compiler npm 包、CLI 封装和编译脚本的生产依赖。
+- 删除或替换只测试宿主编译行为的测试；保留 package-contract、Blender 和下游消费测试。
+- 更新示例配置、README、pipeline spec 和道路包契约，明确 Web export -> host consume
+  的单向关系。
+
+## Acceptance Criteria
+
+- [ ] AC1 `package.json` / lockfile 和生产脚本不再引用 `@osm-asset/road-compiler` 或其 CLI。
+- [ ] AC2 两个有效区域均可从配置指定的已导出 ZIP 道路包运行 Blender、Cesium、package 和 preview，
+      构建期间没有 compiler 子进程。
+- [ ] AC3 宿主在 Blender 前拒绝缺失包、错误 contract、错误 areaId 和无效 manifest；错误说明
+      指向导入包和契约，而非 compiler 内部。
+- [ ] AC4 Blender scene digest 与 P3 control 基线一致；native semantic 层仍不生成几何。
+- [ ] AC5 stage manifest / diagnose / check area 将导入道路包记录为输入并能识别缺失或变更。
+- [ ] AC6 `osm2streets` legacy provider 行为未变。
+- [ ] AC7 文档和配置将人工编辑传播路径表述为 road-compiler Web export -> host consume。
+
+## Out of Scope
+
+- road-compiler Web 的编辑器功能、认证、部署或 UI 改造。
+- 修改道路几何、材质、Blender 建筑/植被/水体渲染。
+- 新的 manifest 破坏性版本或 lane graph IR。
+- 将道路包上传到远程制品库或实现同步服务。
+
+## Key Decision
+
+- Web 导出的是标准 ZIP；宿主配置直接指向 ZIP 而不是目录。ZIP 是跨仓库的不可变交付物，
+  宿主只在私有 staging 目录中解压和消费，因而没有导出目录 ownership 或覆盖歧义。
+
+## Subtask Map
+
+| 子任务 | 仓库 | 交付物 | 依赖 |
+|---|---|---|---|
+| `rc-p5a-zip-export` | road-compiler | Web / CLI 可导出的 root-flat `native-road-package/v1.1` ZIP | 无 |
+| `rc-p5b-zip-import` | osmWorkflow | 配置、受控解压、校验和纯消费管线 | p5a 的 ZIP fixture |
+
+跨任务验收：同一个 ZIP fixture 必须被 p5b 的两个有效区域构建消费；宿主不得保留
+compiler npm 或 CLI 耦合。
--- a/.trellis/tasks/08-26-rc-p5-artifact-consumption/task.json
+++ b/.trellis/tasks/08-26-rc-p5-artifact-consumption/task.json
@@ -0,0 +1,29 @@
+{
+  "id": "rc-p5-artifact-consumption",
+  "name": "rc-p5-artifact-consumption",
+  "title": "道路包导入与纯消费管线",
+  "description": "让宿主通过配置指向 road-compiler Web 导出的 ZIP 道路包，只校验和消费该版本化文件契约，不再安装或调用编译器。",
+  "status": "planning",
+  "dev_type": null,
+  "scope": null,
+  "package": null,
+  "priority": "P2",
+  "creator": "dingkang",
+  "assignee": "dingkang",
+  "createdAt": "2026-08-26",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "experiment/road-compiler-rethink",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [
+    "08-26-rc-p5b-zip-import",
+    "08-26-rc-p5a-zip-export"
+  ],
+  "parent": "08-25-road-compiler-extraction",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
--- a/.trellis/tasks/08-26-rc-p5a-zip-export/check.jsonl
+++ b/.trellis/tasks/08-26-rc-p5a-zip-export/check.jsonl
@@ -0,0 +1 @@
+{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
--- a/.trellis/tasks/08-26-rc-p5a-zip-export/design.md
+++ b/.trellis/tasks/08-26-rc-p5a-zip-export/design.md
@@ -0,0 +1,22 @@
+# P5A ZIP Export Design
+
+The compiler owns a pure `exportNativeRoadPackage(result, destination)` function. It writes a
+temporary root-flat directory from the already compiled Web/CLI state, validates it with the same
+manifest/source validator used by compiler output, then writes a deterministic ZIP. The Web download
+handler and CLI are thin callers of this function.
+
+ZIP layout:
+
+```text
+manifest.json
+compiled.json
+diagnostics.json
+comparison.json
+traffic-signal-assemblies.json
+traffic-signals.json
+layers/<12 declared sources>.geojson
+```
+
+`manifest.generator` is informational only. The host accepts solely the `contract`, `areaId`, and
+declared files. ZIP creation normalizes entry order and timestamps so the export is hash-stable.
+Failure never replaces a chosen output file.
--- a/.trellis/tasks/08-26-rc-p5a-zip-export/implement.jsonl
+++ b/.trellis/tasks/08-26-rc-p5a-zip-export/implement.jsonl
@@ -0,0 +1 @@
+{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
--- a/.trellis/tasks/08-26-rc-p5a-zip-export/implement.md
+++ b/.trellis/tasks/08-26-rc-p5a-zip-export/implement.md
@@ -0,0 +1,10 @@
+# P5A Execution Plan
+
+1. Inspect workbench state ownership and compiler output writer; keep export sourced from the current
+   compiled state, not host paths.
+2. Add deterministic root-flat ZIP writer plus validation and CLI entry point.
+3. Add Web download action using the same writer.
+4. Add fixtures for root layout, content determinism, manifest/source parity and edited-state export.
+5. Export both supported-area fixtures for P5B, run compiler tests, then publish a compiler release.
+
+Rollback: remove the export entry point; no host behavior changes in this subtask.
--- a/.trellis/tasks/08-26-rc-p5a-zip-export/prd.md
+++ b/.trellis/tasks/08-26-rc-p5a-zip-export/prd.md
@@ -0,0 +1,34 @@
+# Web 导出原生道路 ZIP 包
+
+## Goal
+
+让 road-compiler Web/CLI 以 root-flat native-road-package/v1.1 ZIP 导出人工编辑后的道路包。
+
+## Requirements
+
+- 从 Web 当前编辑状态导出完整道路包，而不是源代码、npm 包或仅 overrides。
+- ZIP 根直接包含 `manifest.json`，并包含全部 manifest 声明的 `layers/<source>.geojson`、
+  `compiled.json`、`traffic-signals.json` 和 preview 所需的 signal / diagnostics 文档。
+- `manifest.json` 的 `contract` 保持 `native-road-package/v1.1`；新增可选 `generator` 元数据
+  记录应用版本和 revision，但不得让宿主依赖该版本。
+- Web 提供用户可见的下载操作；CLI 提供等价、可测试的 ZIP 导出入口。
+- ZIP 条目顺序、JSON 序列化和压缩时间戳必须确定性，重复导出未编辑内容的文件 hash 一致。
+
+## Acceptance Criteria
+
+- [x] 从 Web 编辑后的区域可下载一个 root-flat ZIP，且无需宿主或 npm 发布。
+- [x] CLI fixture 导出 ZIP 后，解压内容通过 compiler 的 `validatePublishedLayers()`。
+- [x] ZIP 具有恰好一份 manifest 声明的 layer source，无额外 compiler source / overrides 文件。
+- [ ] 两个有效区域导出的 ZIP 可被 p5b 导入并完成 Blender/Cesium/preview 构建。
+- [x] 不修改 `compiled.json` 与 v1.1 manifest 的既有渲染语义。
+
+## Out of Scope
+
+- 远程存储、上传、项目历史或多用户协作。
+- 修改道路编辑器交互、几何算法或 manifest 主版本。
+
+## Key Decisions
+
+- ZIP 是单个标准交付物，根目录平铺 package 文件，不包裹 area-id 顶层目录。
+- ZIP 面向宿主消费，只携带已编译渲染/预览数据；编辑源、OSM 与 overrides 留在 road-compiler
+  项目中，不泄露为宿主依赖。
--- a/.trellis/tasks/08-26-rc-p5a-zip-export/task.json
+++ b/.trellis/tasks/08-26-rc-p5a-zip-export/task.json
@@ -0,0 +1,26 @@
+{
+  "id": "rc-p5a-zip-export",
+  "name": "rc-p5a-zip-export",
+  "title": "Web 导出原生道路 ZIP 包",
+  "description": "让 road-compiler Web/CLI 以 root-flat native-road-package/v1.1 ZIP 导出人工编辑后的道路包。",
+  "status": "in_progress",
+  "dev_type": null,
+  "scope": null,
+  "package": null,
+  "priority": "P2",
+  "creator": "dingkang",
+  "assignee": "dingkang",
+  "createdAt": "2026-08-26",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "experiment/road-compiler-rethink",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "08-26-rc-p5-artifact-consumption",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
--- a/.trellis/tasks/08-26-rc-p5b-zip-import/check.jsonl
+++ b/.trellis/tasks/08-26-rc-p5b-zip-import/check.jsonl
@@ -0,0 +1 @@
+{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
--- a/.trellis/tasks/08-26-rc-p5b-zip-import/design.md
+++ b/.trellis/tasks/08-26-rc-p5b-zip-import/design.md
@@ -0,0 +1,19 @@
+# P5B ZIP Import Design
+
+`scripts/lib/native-road-package.js` becomes the single host adapter. It resolves the config-relative
+ZIP path, hashes it, validates central-directory entry names and metadata, and extracts only accepted
+regular files to `_pipeline/native-road-import/<sha256>/`. It validates the unpacked manifest and
+returns an immutable package descriptor:
+
+```text
+{ zipFile, zipRecord, rootDir, manifest, records }
+```
+
+The descriptor replaces `area.outputs.nativeRoadDir` as native input for Blender, native preview traffic,
+diagnostics and stage manifests. The configured ZIP and unpacked cache are inputs, never published area
+outputs. Cache invalidation is by ZIP SHA-256; cleanup only deletes importer-owned hash directories.
+
+The importer rejects any non-root-flat layout, duplicate path, symlink, unsupported compression/error,
+path traversal, invalid manifest, area mismatch or declared/published mismatch before Blender starts.
+The native compiler CLI dependency and host-owned `nativeRoad` compilation options are removed. Legacy
+`osm2streets` remains an explicit separate provider.
--- a/.trellis/tasks/08-26-rc-p5b-zip-import/implement.jsonl
+++ b/.trellis/tasks/08-26-rc-p5b-zip-import/implement.jsonl
@@ -0,0 +1 @@
+{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
--- a/.trellis/tasks/08-26-rc-p5b-zip-import/implement.md
+++ b/.trellis/tasks/08-26-rc-p5b-zip-import/implement.md
@@ -0,0 +1,12 @@
+# P5B Execution Plan
+
+1. Add config normalization for `nativeRoadPackage`, migrate two supported configs and the template.
+2. Add the tested ZIP importer with bounded extraction, root-flat/path/symlink validation, SHA cache and
+   manifest/area validation.
+3. Route Blender, preview traffic, stage manifests and diagnostics through the imported descriptor.
+4. Delete compiler CLI/compile production paths and package dependency; replace their tests with ZIP fixture
+   and negative importer tests.
+5. Update docs/specs, run native/legacy unit suites, build two exported packages, then run Blender parity.
+
+Rollback: restore the old compiler dependency and native compile path in one revert; ZIP exports remain
+non-destructive standalone files.
--- a/.trellis/tasks/08-26-rc-p5b-zip-import/prd.md
+++ b/.trellis/tasks/08-26-rc-p5b-zip-import/prd.md
@@ -0,0 +1,40 @@
+# ZIP 道路包安全导入与纯消费
+
+## Goal
+
+让 osmWorkflow 配置、校验、解压并消费 road-compiler Web 导出的 ZIP 道路包，移除 compiler runtime 耦合。
+
+## Requirements
+
+- 区域配置以 `nativeRoadPackage` 指向 ZIP，路径相对于该区域配置文件；native provider 不再
+  接受 compiler options、overrides 或输出目录作为输入。
+- 宿主在任何 Blender / Cesium 副作用前，验证 ZIP 文件、条目数量/大小、root-flat 文件路径、
+  无重复路径、无符号链接、无绝对路径与 `..` 路径。
+- 仅将已验证的文件解压至 `<area>/_pipeline/native-road-import/<zip-sha256>/`；解压目录是宿主
+  私有缓存，绝不写回 ZIP 或 road-compiler 导出目录。
+- 共享 importer 为 Blender、preview traffic、diagnose/check 和 stage manifest 提供同一包路径与
+  文件记录；不能让下游自行按字符串拼接另一份 native-road 目录。
+- 移除 compiler package、CLI wrapper、compile script、编译器输入配置、以及只覆盖旧调用链的测试。
+
+## Acceptance Criteria
+
+- [ ] 两个有效区域均从 ZIP 完成 `blender,cesium,package,preview`，构建日志没有 compiler CLI。
+- [ ] 缺 ZIP、错误 ZIP、nested root、path traversal、symbolic link、错误 contract、错误 areaId 和
+      manifest/source 不匹配均在启动 Blender 前失败。
+- [ ] stage manifest、`diagnose:area` 与 `check:area` 记录 ZIP hash 和已验证的导入目录；ZIP
+      修改后会被判 stale。
+- [ ] `package.json`、lockfile、生产脚本与宿主测试不再引用 `@osm-asset/road-compiler`。
+- [ ] Blender digest 对 P3 control 基线一致；legacy `osm2streets` 路径的单元测试不变。
+
+## Out of Scope
+
+- p5a 的 ZIP 生成与 Web 下载实现。
+- ZIP 远程下载、解密、签名验证或制品库管理。
+- 改道路内容、材质或 legacy QGIS 行为。
+
+## Key Decisions
+
+- ZIP 是只读输入；宿主缓存的生命周期和目录 ownership 完全属于 `_pipeline/`。
+- ZIP 解码由明确声明的 Node ZIP 库完成，而不是依赖系统 `unzip`；这使路径/符号链接校验可控并
+  可在单元测试中覆盖。
+- 只有 `native-road-package/v1.1` 可被导入；契约升级必须另开兼容任务。
				`@@ -0,0 +1 @@`
				{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}