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

每项字段：

{
  "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。

3.3 KiB Raw Blame History Unescape Escape