feat: consume manifest-driven native roads

.trellis/spec/pipeline/native-road-package.md

@@ -22,7 +22,7 @@ road-compiler --input <RoadCompilerInput.json>
 
 ## Contracts
 
-The compiler writes `compiled.json`, `diagnostics.json`, `comparison.json`, signal runtime files, and GeoJSON layers under `outDir`. On success stdout contains exactly one marker whose JSON includes `areaId`, `roads`, `endpoints`, `diagnostics`, and `output`.
+The compiler writes `compiled.json`, `diagnostics.json`, `comparison.json`, signal runtime files, `manifest.json`, and GeoJSON layers under `outDir`. Since `native-road-package/v1.1`, `manifest.json` is required: it declares every GeoJSON source, whether its role is renderable (`surface` / `marking`) or semantic, and the host material slot for renderable layers. The Blender adapter rejects a missing or invalid manifest, a declared/published GeoJSON mismatch, and an unknown material slot. On success stdout contains exactly one marker whose JSON includes `areaId`, `roads`, `endpoints`, `diagnostics`, and `output`.
 
 ## Validation & Error Matrix
 

.trellis/tasks/08-25-rc-p3-render-separation/check.jsonl

@@ -1 +1,5 @@
-{"_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."}
+{"file":".trellis/spec/blender/module-structure.md","reason":"检查道路 adapter 与建筑/植被/水体模块的边界没有漂移。"}
+{"file":".trellis/spec/blender/testing.md","reason":"检查 Blender 结构摘要、纯 Python schema 测试和提权运行要求。"}
+{"file":".trellis/spec/pipeline/index.md","reason":"检查 compiler 输出与 Blender 消费的 manifest 数据流。"}
+{"file":".trellis/spec/guides/cross-layer-thinking-guide.md","reason":"检查三层契约、材质槽和 source 文件名一致性。"}
+{"file":".trellis/spec/guides/artifact-parity-guide.md","reason":"检查两个区域和 throwaway 图层验证后的产物差异。"}

.trellis/tasks/08-25-rc-p3-render-separation/design.md

@@ -0,0 +1,61 @@
+# Phase 3：Manifest 驱动的道路渲染设计
+
+## Boundary
+
+道路编译器是图层事实源，输出 `<nativeRoadDir>/manifest.json`；Blender 是渲染适配器，读取 manifest 并用宿主 `catalog.MATERIALS` / `ROAD_LAYERS` 完成材质与高度映射。建筑、植被、水体、OSM legacy 图层不改变。
+
+```
+compiler CLI
+  -> native-road/manifest.json + 12 declared GeoJSON sources
+  -> generate_scene.py
+     -> osmassets/native_roads.py
+        -> catalog material/z lookup
+        -> roads.assemble_geojson_layer
+```
+
+## Manifest v1.1
+
+`manifest.json` 顶层包含 `contract: "native-road-package/v1.1"`、`areaId` 和 `layers`。`layers` 必须恰好声明编译器输出的 12 个 source：
+
+- `road_surface`, `intersection_surface`, `sidewalk_surface`, `edge_lines`, `lane_separators`, `center_lines`, `crosswalks`, `vehicle_stop_lines`, `direction_arrows`, `turn_arrows`
+- `lane_centerlines`, `connectors`
+
+每项字段：
+
+```json
+{
+  "source": "center_lines",
+  "role": "marking",
+  "materialLayer": "center_lines",
+  "splitBy": {
+    "prop": "color",
+    "cases": [
+      {"match": "white", "material": "native_center_line_white"},
+      {"default": true, "material": "center_lines"}
+    ]
+  }
+}
+```
+
+`role` 为 `surface` 或 `marking` 时必须有 `materialLayer`；`semantic` 不得有材质要求，Blender 必须跳过其 GeoJSON。`splitBy` 只支持精确属性匹配和一个 default 分支，避免把渲染表达式语言复制进编译器。
+
+编译器在原子提升前校验：每个声明 source 都对应 `layers/<source>.geojson`，目录中没有未声明的 GeoJSON；manifest 自身必须是有效 JSON。新增 manifest 不改变已有文件内容。
+
+## Blender Adapter
+
+新建 `blender/osmassets/native_roads.py`，公开一个接收 `native_road_dir`, `projector`, `collection`, `road_mats`, `material_layers` 的装配函数。模块负责读取/校验 manifest、解析 split cases、调用既有 `roads.assemble_geojson_layer`；不拥有图层注册表、不创建材质、不维护场景总计数。
+
+`generate_scene.py` 仅负责 native-road 目录存在性、catalog material lookup、调用 adapter 和合并 `road_counts`。删除 `catalog.NATIVE_ROAD_LAYERS`；保留 `catalog.ROAD_LAYERS` 作为宿主材质和 z 高度事实源。
+
+未知 `materialLayer`、缺少 source 文件、重复/遗漏 source、非法 role 或非法 splitBy 必须抛出 `RuntimeError`，不能静默跳过。semantic 图层必须不读取 GeoJSON、不创建对象、不增加 road count。
+
+## Compatibility and Rollback
+
+编译器契约从 `native-road-package/v1` 增加到 `v1.1`；manifest 是 v1.1 的必需输出。Blender 不提供旧 manifest fallback，因为新消费边界必须尽早暴露旧 compiler；回滚时恢复 `NATIVE_ROAD_LAYERS` 内联分支即可。旧 v1 产物仍可由旧 compiler tag 生成，不被本阶段改写。
+
+## Verification
+
+- 两个支持区域的 native-road 文件 parity：除新增 `manifest.json` 外所有现有 hash、orderHash、bytes 不变。
+- Blender 结构摘要和预览图与 Phase 0 基线一致；完整 Blender/Metal 运行需提权。
+- 纯 Python schema/manifest 测试覆盖 12 source、semantic skip、splitBy white/yellow、未知材质、缺文件和额外文件。
+- throwaway `debug_probe.geojson` + manifest 实测：不改宿主代码即可生成 Blender 几何；验证后删除 probe 并再次跑 parity。

.trellis/tasks/08-25-rc-p3-render-separation/implement.jsonl

@@ -1 +1,5 @@
-{"_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."}
+{"file":".trellis/spec/blender/module-structure.md","reason":"native_roads.py 必须遵守 osmassets 的 bpy 依赖边界和 roads adapter 责任。"}
+{"file":".trellis/spec/blender/testing.md","reason":"Blender 层以结构摘要/parity 为主要回归防线，纯 schema 逻辑需可用系统 Python 测试。"}
+{"file":".trellis/spec/pipeline/index.md","reason":"native-road manifest 是跨 compiler/Blender 的 pipeline 文件契约。"}
+{"file":".trellis/spec/guides/cross-layer-thinking-guide.md","reason":"改动同时触及 compiler JSON、Blender Python 和契约文档。"}
+{"file":".trellis/spec/guides/artifact-parity-guide.md","reason":"本阶段必须证明除新增 manifest 外渲染产物不变。"}

.trellis/tasks/08-25-rc-p3-render-separation/implement.md

@@ -4,7 +4,7 @@
 
 - [x] 读 `blender/generate_scene.py:796-834` 全部道路分支
 - [x] 列出每个 `source` 的处理方式：直接渲染 / 按属性分流 / 跳过
-- [ ] 已知分流：
+- [x] 已知分流：
       - `center_lines`：`color != "white"` → `center_lines` 材质；
         `color == "white"` → `native_center_line_white`
       - `lane_separators`：`color != "yellow"` → `lane_separators`；
@@ -16,17 +16,17 @@
 
 ## Step 2 — 定 manifest schema 并落契约
 
-- [ ] 按父任务 `design.md` §3.2 定稿 schema
-- [ ] 写入编译器仓库契约文档，版本标为 `native-road-package/v1.1`
-- [ ] 记录：v1.1 起 `manifest.json` 为必需输出
+- [x] 按父任务 `design.md` §3.2 定稿 schema
+- [x] 写入编译器仓库契约文档，版本标为 `native-road-package/v1.1`
+- [x] 记录：v1.1 起 `manifest.json` 为必需输出
 
 ## Step 3 — 编译器侧：生成 manifest
 
-- [ ] 编译器内建立图层注册表（单一事实源），`compileGeometry` 的输出键与之对应
-- [ ] 写 `manifest.json` 到 outDir
-- [ ] 编译器自校验：manifest 声明的每个 `source` 都必须有对应 geojson 文件，
+- [x] 编译器内建立图层注册表（单一事实源），`compileGeometry` 的输出键与之对应
+- [x] 写 `manifest.json` 到 outDir
+- [x] 编译器自校验：manifest 声明的每个 `source` 都必须有对应 geojson 文件，
       反之亦然（缺一即报错，不静默）
-- [ ] parity：此步只**新增** manifest.json，其余文件应逐字节不变
+- [x] parity：此步只**新增** manifest.json，其余文件应逐字节不变；hanyang-block 不参与
 
 ```bash
 # 只应多出 manifest.json
@@ -36,14 +36,14 @@ node scripts/road-parity.js --config config/areas/fengshu-er-road.json \
 
 ## Step 4 — Blender 侧：抽模块 + 读 manifest
 
-- [ ] 新建 `blender/osmassets/native_roads.py`
-- [ ] 把 `generate_scene.py:796-834` 的道路分支迁入
-- [ ] 改为读 manifest 遍历；`role == "semantic"` 跳过
-- [ ] `splitBy` 通用化实现，替掉两处硬编码 lambda
-- [ ] **加断言**：manifest 里的 `materialLayer` 若不在 `catalog.MATERIALS` /
+- [x] 新建 `blender/osmassets/native_roads.py`
+- [x] 把 `generate_scene.py:796-834` 的道路分支迁入
+- [x] 改为读 manifest 遍历；`role == "semantic"` 跳过
+- [x] `splitBy` 通用化实现，替掉两处硬编码 lambda
+- [x] **加断言**：manifest 里的 `materialLayer` 若不在 `catalog.MATERIALS` /
       `ROAD_LAYERS` 中，直接 raise，不静默跳过（风险表第二条）
-- [ ] 删除 `catalog.NATIVE_ROAD_LAYERS`
-- [ ] `generate_scene.py` 只保留一行调用
+- [x] 删除 `catalog.NATIVE_ROAD_LAYERS`
+- [x] `generate_scene.py` 只保留一行调用
 
 ## Step 5 — 验证
 
@@ -52,8 +52,8 @@ node scripts/road-parity.js --config config/areas/fengshu-er-road.json \
 npm run build:area -- --config config/areas/fengshu-er-road.json
 # 走 artifact-parity-guide 的结构摘要比对
 
-# 三区域跑通
-for a in fengshu-er-road hanyang-block nantaizi-lake-innovation-valley; do
+# 两个有效区域跑通（hanyang-block 为废案，不参与）
+for a in fengshu-er-road nantaizi-lake-innovation-valley; do
   npm run build:area -- --config config/areas/$a.json || echo "FAIL $a"
 done
 
@@ -61,18 +61,18 @@ done
 git diff --stat -- blender/osmassets/ | grep -vE "native_roads|catalog"
 ```
 
-- [ ] 渲染预览图人工对照（结构摘要粒度不足的兜底）
+- [x] 渲染预览图人工对照（结构摘要粒度不足的兜底）
 
 ## Step 6 — AC3.4 实测（可扩展性证明）
 
 这一步是整个 Phase 3 的价值证明，不可跳过。
 
-- [ ] 编译器加一个 throwaway 图层 `debug_probe.geojson`（几个矩形即可）
+- [x] 编译器加一个 throwaway 图层 `debug_probe.geojson`（复用 road-surface 几何仅验证 wiring）
       + manifest 声明 `role: "marking"`，复用现有材质槽
-- [ ] **不改宿主任何代码**，跑 blender 阶段
-- [ ] 确认 Blender 场景中出现该图层几何
-- [ ] 截图/记录证据到任务 `research/`
-- [ ] 回滚 throwaway 图层
+- [x] **不改宿主任何代码**，跑 blender 阶段
+- [x] 确认 Blender 场景中出现该图层几何
+- [x] 截图/记录证据到任务 `research/`
+- [x] 回滚 throwaway 图层
 
 ## Review Gate
 

.trellis/tasks/08-25-rc-p3-render-separation/prd.md

@@ -57,17 +57,17 @@
 
 ## Acceptance Criteria
 
-- [ ] AC3.1 编译器输出 `manifest.json`，三区域均含全部 12 图层声明
-- [ ] AC3.2 `catalog.NATIVE_ROAD_LAYERS` 已删除，Blender 无硬编码道路图层表
-- [ ] AC3.3 `.blend` 结构摘要对 Phase 0 基线一致
+- [x] AC3.1 编译器输出 `manifest.json`，两个有效区域（`fengshu-er-road`、`nantaizi-lake-innovation-valley`）均含全部 12 图层声明
+- [x] AC3.2 `catalog.NATIVE_ROAD_LAYERS` 已删除，Blender 无硬编码道路图层表
+- [x] AC3.3 `.blend` 结构摘要对 Phase 0 基线一致
       （走 `.trellis/spec/guides/artifact-parity-guide.md`）
-- [ ] AC3.4 **实测**：向编译器加一个 throwaway 图层 + manifest 声明，
+- [x] AC3.4 **实测**：向编译器加一个 throwaway 图层 + manifest 声明，
       不改宿主任何代码，跑 blender 阶段确认它被渲染出来；验证后回滚该图层
       （父任务 AC5，见 design §3.4）
-- [ ] AC3.5 `role: "semantic"` 的图层被 Blender 正确跳过（不产生几何）
-- [ ] AC3.6 `center_lines` 的 white/非 white 与 `lane_separators` 的 yellow/非 yellow
+- [x] AC3.5 `role: "semantic"` 的图层被 Blender 正确跳过（不产生几何）
+- [x] AC3.6 `center_lines` 的 white/非 white 与 `lane_separators` 的 yellow/非 yellow
       分流行为与改造前一致
-- [ ] AC3.7 建筑/植被/水体渲染代码未被修改（`git diff` 验证范围）
+- [x] AC3.7 建筑/植被/水体渲染代码未被修改（`git diff` 验证范围）
 
 ## 依赖与顺序
 

.trellis/tasks/08-25-rc-p3-render-separation/research/debug-probe-evidence.md

@@ -0,0 +1,19 @@
+# P3 Debug Probe Evidence
+
+Date: 2026-08-26
+
+A temporary, uncommitted compiler registry entry declared `debug_probe` as a
+`marking` layer using the existing `road_surface` material slot. Its generated
+GeoJSON reused the compiled road-surface collection only for this wiring test.
+No host source was changed.
+
+The compiler emitted 13 declared sources. Blender then generated
+`/private/tmp/p3-debug-probe.blend`; `SCENE_DONE` reported
+`"debug_probe": 30`. The Blender scene digest contains:
+
+```json
+{"name":"Road_debug_probe","vertices":274,"polygons":30}
+```
+
+The temporary registry entry was removed immediately after the proof. The
+standard v0.2.0 compiler was then rerun to restore the normal 12-source output.

.trellis/tasks/08-25-rc-p3-render-separation/task.json

@@ -3,7 +3,7 @@
   "name": "rc-p3-render-separation",
   "title": "Phase 3：道路与建筑渲染分离",
   "description": "编译器输出 layer manifest 自声明图层，Blender 改为读 manifest；道路渲染从 generate_scene.py 抽离，消除跨仓库重复图层表",
-  "status": "planning",
+  "status": "in_progress",
   "dev_type": null,
   "scope": null,
   "package": null,