# 道路包导入与纯消费管线

父任务：`.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 耦合。