# Native Road Compiler Workbench Design

## Architecture

The native compiler is an additive pipeline path. It owns a separate output
directory under an area and never writes into `osm2streets_web_out/`.

```text
OSM XML + native-road-overrides.json
          |
          v
      Canonical Road Model
      roads / endpoints / junction candidates / provenance
          |
          v
      Native Geometry Compiler
      road surfaces / initial junction surfaces / diagnostics
          |
          +--> native-road/compiled.json
          +--> native-road/layers/*.geojson
          +--> native-road/diagnostics.json
          +--> native-road/comparison.json
          |
          v
      Road Workbench HTTP service
      browser map + inspect/edit/save API
```

The canonical model is the authority. Render layers, browser display data, and
future Blender compatibility adapters are derived from it.

## Commands And Ownership

- `npm run road:compile -- --config <area-config>` performs no browser work.
  It reads OSM plus the persisted override file, writes a staged native-road
  result, validates it, and atomically promotes the result directory.
- `npm run road:workbench -- --config <area-config>` compiles first unless
  `--no-compile` is supplied, then starts a local HTTP server scoped to that
  one area.
- The server exposes read-only compiler artifacts and one explicit save API
  for validated overrides. It does not expose arbitrary filesystem paths.
- Existing `build:area`, `intermediates`, QGIS, Blender, Cesium, and package
  paths remain unchanged in the first iteration.

## Data Contracts

### Canonical road model

Each road direction carries a stable ID derived from OSM identifiers, source
way IDs, endpoint node IDs, centerline, explicit/inferred attributes, applied
override IDs, and diagnostics. Junction candidates likewise use their OSM node
ID when available. Values include provenance such as `tag:lanes:forward`,
`inferred:highway-default`, or `override:<id>`.

Each `Movement` is a stable semantic record joining a connection, source and
target road/lane, turn class, provenance, and an optional connector geometry.
`geometryStatus="connector"` publishes a connector curve;
`geometryStatus="continuous"` means the lane centerlines meet at the node and
does not invent a zero-length curve; `deferred-too-long` retains the movement
while withholding unsafe geometry.

### Override file

`<area>/native-road-overrides.json` is versioned and human-reviewable. It
contains an array of uniquely identified changes whose targets are stable road
or endpoint IDs. Supported v1 records are `road` parameter overrides and
`junction-connection` decisions. The save endpoint validates schema, target
existence, finite values, and duplicate/conflicting edits before atomic write.

### Compiler artifacts

`<area>/native-road/compiled.json` is the workbench's single read model and
contains the canonical `movements` list.
`layers/` contains generated GeoJSON with source/provenance properties.
`diagnostics.json` contains severity, stable subject ID, source IDs, rule,
message, and optional geometry. `comparison.json` reports counts and coverage
against available osm2streets layers; it does not claim quality solely from
visual differences.

## Browser Workbench

The browser uses OpenLayers as its sole GIS runtime, served directly from the
local allowlisted `node_modules` packages with a browser import map. The map
renders fit-to-data OSM centerlines, native surfaces, optional osm2streets
reference layers, diagnostics, selected-object provenance, movements, and
overrides. This provides mature map selection and hit detection without a
framework or bundler.

The user can select a road or endpoint, edit only v1 fields, inspect the
resulting override record, explicitly save it, and recompile/reload. Saved
state is visibly differentiated from unsaved state. The workbench must not
offer freehand final-polygon editing, since that would break reproducibility.

## Geometry And Validation

V1 produces road segments from projected centerline offsets and terminal
cross-sections. It only generates a junction surface when endpoints satisfy
the supported ordinary T/cross shape and geometry checks; otherwise it emits a
diagnostic rather than inventing an invalid polygon. Validation detects
dangling endpoints, unclosed/self-intersecting rings, non-finite coordinates,
unsupported multi-level intersections, and source/topology ambiguity. Small
numerical cleanup may be explicit and recorded; semantic failures are never
silently repaired.

## Compatibility And Rollout

The first compiler's layers use existing render-layer names where meaningful,
but are stored separately. A later, explicitly enabled Blender provider option
may consume native layers after comparison gates pass. Delete/replace behavior
is out of scope; rollback is selecting the existing osm2streets pipeline.