From 7d4b3b566a6416e5788429e4912bdd8e38f8156d Mon Sep 17 00:00:00 2001
From: que01 <que01@foxmail.com>
Date: Wed, 26 Aug 2026 09:27:09 +0800
Subject: [PATCH] docs: specify external road compiler contract

---
 .trellis/spec/pipeline/native-road-package.md | 53 +++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/.trellis/spec/pipeline/native-road-package.md b/.trellis/spec/pipeline/native-road-package.md
index 3d90d5a..5f5b6f0 100644
--- a/.trellis/spec/pipeline/native-road-package.md
+++ b/.trellis/spec/pipeline/native-road-package.md
@@ -7,3 +7,56 @@ The native-road package is maintained in the private `road-compiler` repository:
 This host consumes the exact git tag recorded in `package.json` and lockfile. The host owns area configuration normalization and writes `RoadCompilerInput`; the compiler owns the `native-road-package/v1` file contract and CLI. Production code must invoke the installed compiler CLI through `scripts/lib/road-compiler-cli.js`, not import compiler source files or read `packages/road-compiler`.
 
 The completion marker is `NATIVE_ROAD_COMPILE_DONE <json>`. `build-area.js` validates the marker's count, JSON payload, area id, output path, process status, and signal before starting Blender.
+
+## Scope / Trigger
+
+This contract applies to native-road compilation from `scripts/build-area.js`, `scripts/compile-native-roads.js`, and the road workbench fresh-compile callback.
+
+## Signatures
+
+```text
+road-compiler --input <RoadCompilerInput.json>
+```
+
+`RoadCompilerInput` contains `areaId`, absolute `osmFile`, `outDir`, `stagingDir`, `overridesFile`, `trafficSignalsFile`, optional `comparisonDir`, and `options`.
+
+## 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`.
+
+## Validation & Error Matrix
+
+| Condition | Required result |
+|---|---|
+| CLI cannot start | throw the spawn error |
+| non-zero exit or signal | fail with status/signal |
+| zero completion markers | fail |
+| multiple completion markers | fail |
+| malformed marker JSON | fail |
+| marker `areaId` or `output` mismatch | fail |
+
+## Good / Base / Bad Cases
+
+- Good: host writes an absolute input JSON, runs the installed exact-tag CLI, validates one marker, then starts Blender.
+- Base: compiler emits deterministic files and no optional comparison source exists.
+- Bad: host imports compiler source, reads `config/areas` inside the package, or accepts a missing/duplicate marker.
+
+## Tests Required
+
+- `scripts/test-road-compiler-cli.js` asserts marker success, missing, duplicate, malformed, area mismatch, and output mismatch cases.
+- `scripts/road-parity.js` compares `contentHash`, `orderHash`, feature counts, and byte counts for both supported areas.
+- `npm run test:road-workbench` asserts the workbench is loaded from the installed package.
+
+## Wrong vs Correct
+
+Wrong:
+
+```js
+require("../packages/road-compiler/src/compile/compiler");
+```
+
+Correct:
+
+```js
+spawnSync(process.execPath, [compilerCli(), "--input", inputFile]);
+```