Native Road Package Contract

The native-road package is maintained in the private road-compiler repository:

https://git.app.que01.top/que01/road-compiler

The host consumes a read-only ZIP exported by the private road-compiler repository. The host never installs or invokes the compiler. nativeRoadPackage is resolved relative to the area config, hashed, validated, and extracted into _pipeline/native-road-import/<sha256>/ before native consumers start.

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 consumption from scripts/build-area.js, diagnostics, parity, Blender, and native preview generation.

Signatures

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, 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

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:

require("../packages/road-compiler/src/compile/compiler");

Correct:

spawnSync(process.execPath, [compilerCli(), "--input", inputFile]);

2.9 KiB Raw Blame History