# Phase 1 Technical Design

## Boundary

`packages/road-compiler/` becomes the single implementation owner for native
road compilation. It is a CommonJS workspace package with explicit public
entrypoints for compiler APIs, traffic-signal schema, turn-lane helpers, OSM
parsing, reference conversion, and CLIs. It never imports `area-config`, reads
`config/areas`, or derives host paths.

The host owns `scripts/lib/area-config.js` and maps normalized configuration to
the v1 `RoadCompilerInput` shape using `toRoadCompilerInput(area)`. During P1,
`build-area.js` calls the package in-process; P2 is the only phase that changes
that call to a child process.

## Source Ownership and Compatibility

The following current `scripts/lib` implementations move into package `src`:
`native-road`, `complex-junction`, `turn-lane-arrows`, `lane-geometry`,
`gaode-junction-reference`, `native-traffic-signals`, and `osm`.

Some moved modules also serve legacy host paths: QGIS uses turn-lane arrows,
vehicle preview and reimport use OSM parsing, and preview tests use lane
geometry. Those consumers import the package entrypoints after the move. This
preserves one implementation while allowing host -> package dependency.

Traffic signal ownership follows the matrix in
`research/traffic-signals-split-matrix.md`: schema, geometry, validation, and
runtime construction move to the package. The host retains only two file-I/O
adapters, `readTrafficSignalFeatures()` and `readTrafficSignals()`, both
delegating to package exports. No duplicated schema code remains.

## Input and Path Handling

The package compiler API accepts only `RoadCompilerInput` from
`docs/native-road-package-v1.md`. Package CLI commands accept an explicit JSON
input file (`--input`) and never load area configuration. The compatibility
host CLI still accepts `--config`, but immediately maps it through
`toRoadCompilerInput()` before entering the package.

`junctionTemplates.*.referenceFile` changes to a path relative to its area
configuration. `readAreaConfig()` resolves it while normalizing configuration;
the package receives an absolute path and does no path resolution.

## Tests and Rollout

The package receives the required Fengshu OSM fixture plus migrated unit tests.
Its `npm test` must run from the package directory without reading host inputs
or outputs. After each source batch, run the two Phase 0 parity baselines. The
existing host command names remain compatibility wrappers through P1.

Rollback is a normal Git revert of the latest batch commit. No module has a
parallel host copy after its batch lands, preventing divergence.