# Phase 0：冻结契约与 parity 基线

父任务：`.trellis/tasks/08-25-road-compiler-extraction/`
契约权威定义：父任务 `design.md` §1

## Goal

在任何代码移动之前，把 `native-road-package/v1` 契约落成仓库内文档，
并为两个有效区域建立可复跑的逐文件 parity 基线，作为全案唯一 oracle。

**本阶段不移动、不重构任何生产代码。** 只新增文档、基线数据和一个校验脚本。

## Requirements

### R0.1 契约文档

- 把父任务 `design.md` §1（输入契约 / 输出契约 / 消费方式）落成
  `docs/native-road-package-v1.md`。
- 文档必须列全 12 个图层名、`compiled.json` 顶层结构、`diagnostics.json` 记录形状、
  stdout 标记格式。
- Phase 2 会把该文档搬进编译器仓库，此处先落在宿主。

### R0.2 确定性前置核查 🔴

**基线只有在编译器确定性的前提下才有意义。** 必须先证明这一点。

- 对同一输入连续跑两次 `road:compile`，比较全部输出文件。
- 识别并记录所有 volatile 字段（时间戳、绝对路径、staging 目录名、
  任何来自 `mkdtemp` 的随机名、Map/Set 迭代顺序敏感的输出）。
- 校验脚本必须归一化或排除这些字段。
- 若发现真实的非确定性（相同输入产出不同几何），**必须先修掉再继续**，
  否则整个拆分没有 oracle。

### R0.3 parity 校验脚本

- 新增 `scripts/road-parity.js`（宿主侧，Phase 2 随编译器搬走）。
- 能力：
  - `--snapshot <out.json>` 遍历指定区域的 `native-road/` 全部文件 +
    `native-traffic-signals.json`，归一化后输出排序稳定的 checksum 清单
  - `--compare <baseline.json>` 与基线比对，差异逐文件报告
  - 非零退出码表示不一致
- GeoJSON 需按稳定键排序后再 hash（避免 feature 顺序抖动造成假阳性），
  但**顺序本身若变化必须被报告**——用两个 hash：`contentHash`（排序后）
  与 `orderHash`（原序），分别报告。

### R0.4 两区域基线

- 区域：`fengshu-er-road`、`nantaizi-lake-innovation-valley`
- 从干净状态跑 `npm run road:compile`，产出基线 JSON 提交进版本控制
- 基线文件位置：`.trellis/tasks/08-25-road-compiler-extraction/baseline/<area>.json`
  （Phase 2 搬进编译器仓库当测试语料，见父任务 R4）

`hanyang-block` 是废案，不纳入编译、快照或后续 parity 兼容范围。

### R0.5 K2 决策定档

`comparison.json` 依赖宿主 osm2streets 产物（`compile-native-roads.js:87` 读
`area.outputs.geojsonDir`），拆出后不可达。本阶段必须做出决策并写入契约文档：

- 方案 A：移除 `comparison.json`（osm2streets 已 legacy）
- 方案 B：保留，`comparisonDir` 作为可选输入注入
- 倾向 A。决策写入 `docs/native-road-package-v1.md` 的「已移除能力」一节。

## Acceptance Criteria

- [x] AC0.1 `docs/native-road-package-v1.md` 存在，覆盖输入契约、输出契约、
      12 图层清单、stdout 标记、已移除能力
- [x] AC0.2 连续两次编译的 parity 比对通过（确定性已证明），volatile 字段清单已记录在文档内
- [x] AC0.3 `scripts/road-parity.js` 可用，`--snapshot` / `--compare` 均工作，
      不一致时非零退出
- [x] AC0.4 两个区域基线 JSON 已提交，且每个都能用 `--compare` 自比对通过
- [x] AC0.5 K2 决策已定档并写入契约文档
- [x] AC0.6 未修改任何生产代码（`git diff` 只含新增文档 / 脚本 / 基线）

## 依赖与顺序

- 无前置依赖，本阶段是全案入口
- **阻塞** Phase 1、2、3、4 —— 没有基线就没有 oracle

## Out of Scope

- 任何生产代码改动（含"顺手修一下"）
- 目录结构调整
- `compiled.json` 结构变更