# Native Preview Traffic Simulation

This document defines the portable preview contract for native road traffic demonstrations. It is
not a legal navigation format or a full microscopic traffic simulator.

## Data Flow

```text
native-road/compiled.json + layers/
  -> native-preview-traffic-simulation/v1 descriptor
package/runtime/traffic-signals.json
  -> signal phase clock and stop constraints
descriptor + package/manifest.json
  -> Cesium preview vehicles, signals, queues, diagnostics
```

The descriptor is generated from native artifacts and is independent of QGIS/osm2streets. Copying
the descriptor, package, and preview runtime to another platform is sufficient to reproduce the
visual simulation.

## Existing Signal Contract

Signal identity is `signal_uid`; it must not be renamed when `display_id` changes. `phase_group`
selects the existing signal phase. `mast_heading_deg`, `face_heading_deg`, `pose.*`, stop-line
coordinates, and `enabled` are consumed from `package/runtime/traffic-signals.json`. Disabled signals
are absent from runtime control. Consumers must not recalculate lamp or pole geometry.

## Vehicle Rules

Each vehicle advances along a route distance. Its target speed is the minimum of desired speed,
signal-safe speed, and leader-safe speed. Red/yellow signals create a stop target before the native
stop line. Following vehicles apply the configured minimum gap and decelerate behind the leader.
The simulation is deterministic for a fixed descriptor, clock start, and settings.

The descriptor records WGS84 route coordinates. The static package remains local ENU and is placed by
the package manifest. Consumers must use the package placement/model matrix for GLB assets and WGS84
coordinates for route entities; do not mix a fixed meters-per-degree approximation into either path.

Route geometry is taken from `native-road/layers/lane_centerlines.geojson` when that native layer is
available, keyed by `road_id`; the compiled road centerline is only a compatibility fallback for old
native outputs. Each road/connector boundary is checked in meters. Candidates with a missing
connector or an endpoint gap over 35 m are omitted from `routes` and retained in `rejectedRoutes`
with structured diagnostics. This prevents a malformed movement from becoming a visible diagonal
track across an intersection.

`diagnostics` contains the route-generation warnings, while `rejectedRoutes` preserves the candidate
id and the specific movement checks that failed. A consumer should display these as data-quality
warnings rather than silently reconstructing a route from legacy QGIS files.

## Migration Checklist

1. Load `package/manifest.json` and resolve all package-relative assets.
2. Load the traffic-signal runtime and preserve `signal_uid`/`phase_group` values.
3. Load the versioned simulation descriptor and verify its source hashes if reproducibility matters.
4. Implement the update loop using the descriptor settings and stop/leader constraints.
5. Place route coordinates in the same WGS84 scene as the package placement and preserve ENU model
   placement for static assets.
6. Expose route count, signal count, stopped vehicles, and queue length as diagnostics.

## Rollback

Deleting or ignoring the optional simulation descriptor returns the native preview to a usable static
scene with signal visualization but no vehicle cruise. The QGIS baseline remains available through
`qgis-original-baseline-20260818`; it is not required by this contract.