Native Road Package v1.1

native-road-package/v1.1 adds a required manifest.json to the v1 output. Consumers may ignore this file when reading legacy v1 packages, but v1.1 consumers must validate and consume it.

native-road-package/v1 defines the boundary between the host area pipeline and the native road compiler. The compiler accepts only the input below; it does not read config/areas/*.json or derive host paths.

Input

{
  areaId: string,
  osmFile: string,
  outDir: string,
  stagingDir: string,
  overridesFile: string,
  trafficSignalsFile: string,
  comparisonDir?: string,
  options: {
    edgeLines: boolean,
    junctionTemplates: {
      enabled: boolean,
      references: [],
      clusters: []
    }
  }
}

All paths are absolute at the process boundary. stagingDir is the parent for the compiler's temporary output and outDir is promoted atomically only after all files are written. The host maps normalized area configuration to this shape and owns all path derivation.

Output

outDir contains these JSON documents:

manifest.json: { contract: "native-road-package/v1.1", areaId, layers }. layers declares exactly the twelve GeoJSON sources. Renderable entries have role (surface or marking) and materialLayer; semantic entries have role: "semantic" and no material. Optional splitBy contains one property and exact-match cases plus one default case.
compiled.json: top-level keys are schema, areaId, source, model, movements, trafficSignals, diagnostics, and layers. source has osm, overrides, and trafficSignals paths.
diagnostics.json: { schema: "native-road-diagnostics/v1", diagnostics: [] }. Each diagnostic has id, severity, subjectId, sourceIds, rule, message, and geometry (a GeoJSON geometry or null).
comparison.json: coverage counts for the road workbench.
traffic-signal-assemblies.json and traffic-signals.json: compiler-owned signal assembly and runtime views.

layers/ always contains these twelve GeoJSON FeatureCollections:

road_surface.geojson
intersection_surface.geojson
sidewalk_surface.geojson
edge_lines.geojson
lane_separators.geojson
center_lines.geojson
crosswalks.geojson
vehicle_stop_lines.geojson
direction_arrows.geojson
turn_arrows.geojson
lane_centerlines.geojson (semantic, not rendered)
connectors.geojson (semantic, not rendered)

The editable signal source at trafficSignalsFile is a sibling of outDir. It is included in the parity baseline because regeneration must be stable.

ZIP Export

The Web workbench's 导出道路包 action and the CLI's optional --export-zip <output.zip> emit the portable package form. The ZIP root is flat: it contains the six JSON documents above and layers/*.geojson, without an enclosing area directory. It contains no OSM input, overrides, or compiler workspace paths. compiled.json retains only model and movement data needed by the downstream preview; its internal source paths are removed.

The ZIP manifest adds informational generator: { name, version }. Consumers must select compatibility only from contract, areaId, and declared files. Entry order and timestamp are fixed, so unchanged compiled output exports to the same ZIP hash.

Successful CLI execution prints exactly one completion marker:

NATIVE_ROAD_COMPILE_DONE {"areaId":...,"roads":N,"endpoints":N,"diagnostics":N,"output":...,"comparison":...}

Consumers use the CLI process plus files in outDir and parse this marker. An in-process import may be an optimization, never the sole contract.

Comparison Input Decision

comparison.json remains part of v1. The road workbench currently reads it, so removing it would break a real consumer. comparisonDir is therefore an optional compiler input for a future standalone package: when absent, the compiler emits native-only counts and marks osm2streets coverage unavailable.

Parity Rules

scripts/road-parity.js snapshots every file below outDir plus the sibling editable signal document. JSON object keys are recursively sorted before hashing. GeoJSON records both a sorted-feature contentHash and original-order orderHash; either difference is reported.

The only normalization is intentional volatility removal:

absolute paths below this repository become <repo>/...;
other absolute paths become <external>/<basename>;
native-road-* temporary directory names become <staging>.

No coordinates are rounded and no feature order changes are ignored. Control experiments on 2026-08-25 compiled fengshu-er-road and nantaizi-lake-innovation-valley twice, then regenerated their editable signal documents. All 18 tracked files per area matched.

4.7 KiB Raw Blame History