Files
road-compiler/.trellis/tasks/09-08-junction-reference-fidelity/research/phase-0-audit.md
T

143 lines
8.3 KiB
Markdown

# Phase 0 Audit: Current Complex-Junction Construction
Date: 2026-09-08
## Scope and evidence
This audit uses source-independent synthetic fixtures in
`test/junction-build-plan-counterexamples.js`. They deliberately do not contain
the reference image names, OSM object IDs, place names, or fixed real-world
coordinates. The file records the old behaviour as a baseline; phase 1 must
replace its absence assertions with positive `JunctionBuildPlan` assertions.
## Findings
### 1. Source identity survives, but grouping and geometry have separate rules
- `src/compile/native-road.js:2823-2841` groups ordinary junction approaches by
`segmentId`, sums both directions into one width, and selects the first road
for the approach line.
- `src/compile/complex-junction.js:17-89` creates one complex carriageway per
existing approach, then groups them into an arm when heading differs by less
than 20 degrees (`:60-71`). The direct-edit solver repeats that independently
in `src/compile/direct-edit-solver.js:210-297`, including its own line and
tangent sampling (`:254-258`, `:277-296`).
- Stable keys use source identity (`complex-junction.js:47-88` and
`junction-topology.js:3-9`), which is reusable. But an arm becomes the
operative geometry unit: the core uses one envelope per arm
(`complex-junction.js:551-566`), and arm crossings start from the
representative (`:244-247`). That does not provide a distinct EntrySection
or shared curb for each separated carriageway.
Result: directional/source identity is a good starting point, but no single
pure structure resolver is authoritative for compiler and solver. Do not make
the 20-degree threshold the `JunctionBuildPlan` grouping rule.
### 2. Distance semantics mix along-line and radial projection
- Ordinary cutback uses `pointAlongLine()` and a tangent at that cutback
(`native-road.js:2844-2859`, `:2900-2918`), which is the correct local basis
for a bent ordinary approach.
- Complex geometry takes the first-segment heading at the node
(`complex-junction.js:42-44`) and maps a radius to an along-line station by a
scalar projection (`:857-861`). For a curve, that is not the intersection of
the centre-radius boundary and the line. `armEnvelopeAtRadius()` and corner
calculations reuse it (`:862-878`, `:919-934`).
- External road surface has a late per-road radial correction
(`native-road.js:656-699`, `:3215-3236`), but the other consumers do not all
receive that same per-road radius.
Result: `EntrySection` must name a fixed far section and a station measured on
the source polyline. It may derive a boundary intersection from the actual
polyline, but may not equate that with a centre projection.
### 3. Existing surfaces have no shared-boundary authority
- Complex geometry independently emits a core polygon (`complex-junction.js:551-602`), one rectangular polygon per carriageway (`:603-631`), corner fills
(`:450-490`), pedestrian corner bands (`:492-549`), and automatic corner
islands/crossings (`:319-449`). Their overlap is intentional in places; it is
not a referenced seam contract.
- Ordinary boundaries merge parallel approaches into a single face
(`native-road.js:2861-2897`) and then independently round corners
(`:2900-2955`). This avoids one failure mode but loses separate-corridor
semantics.
- `roadRing()` and `sidewalkRing()` only offset independent centre lines
(`native-road.js:3364-3396`); neither receives a shared boundary reference.
- Validation is local: complex pedestrian corners check self-intersection
(`complex-junction.js:519-530`) and the core checks one ring (`:565-566`).
There is no validation of road/core seams, connected required pavement, holes,
or exclusion zones.
Result: phase 2 needs `BoundaryGraph` ownership before adding more controls.
Core, approach, corner, sidewalk, marking, and facility producers must consume
edge references rather than reconstructing offset rectangles.
### 4. Layer trimming is inconsistent
| Consumer | Complex-cluster trim path | Per-carriageway boundary radius |
| --- | --- | --- |
| Road surface | `native-road.js:688-699` | Yes, from `complexApproachBoundaryRadii()` |
| Edge lines | `native-road.js:1098-1120` | No |
| Centre/lane separators | `native-road.js:1171-1192` | No |
| Sidewalk strips | `native-road.js:1850-1855` | No |
| Lane centre lines | `native-road.js:2109-2140` | No |
| Complex carriageway, core, corners, facilities | `complex-junction.js:149-667` | Separate radial/core rules |
The shared helper falls back to `approachOuterRadius` when no radius is passed
(`native-road.js:3201-3212`). Thus the earlier road-surface continuity repair
does not establish a cross-layer contract. Every listed consumer must eventually
take its termination from the same `EntrySection`/BoundaryGraph plan.
### 5. Solver purity is currently violated indirectly
`direct-edit-solver.js:17` imports `complexJunctionMetrics()`. That function
calls `readReferenceCalibration()` (`complex-junction.js:740-757`), which uses
`fs.existsSync` and `fs.readFileSync` (`:723-737`). This conflicts with the
direct-edit resolver purity requirement in `.trellis/spec/backend/direct-edit-api.md`.
Preload reference-derived metrics in the compile/service boundary, then pass
plain values into a pure topology/plan resolver.
## Minimal counterexamples and required future invariants
| Fixture | Current baseline | Required plan invariant |
| --- | --- | --- |
| `divided` | Two 10 m-separated, same-heading carriageways become one 20-degree arm. | Two stable carriageways and EntrySections remain distinct; an arm may group them for presentation only. Their boundaries cannot collapse into a single solid approach unless an explicit traversable connection says so. |
| `tee` | Shape is `t-junction`; no closure or boundary object exists. | The blocked side is represented by explicit boundary edges, with no invented through pavement or facility. |
| `offset-unequal` | Label is `offset-cross`; widths remain approach metadata without boundary references. | Each section keeps its own position, tangent, left/right edge, and far anchor; generated rings have shared seams within 1 cm. |
| `curved-short` | Heading samples the first segment and core/radius code uses a projection-derived station; length is below the minimum core radius. | Resolve against actual polyline length and local tangent. Return an object-scoped unsupported diagnostic when a required transition cannot fit; never extend or silently disconnect geometry. |
## Recommended first implementation slice
Implement a pure `junction-build-plan` module before touching rendering or UI.
It should receive already-loaded model/config data and return either:
1. `JunctionBuildPlan` with version, source topology, stable carriageway keys,
`EntrySection`s (source polyline, far station, entry station, tangent,
left/right boundary endpoints), grouping provenance, and diagnostics; or
2. an object-scoped unsupported/ambiguous result with no geometry claim.
The module must be the sole source for both `resolveComplexJunctionTopology()`
and solver cluster handle anchors. First tests should make all four fixtures
positive: input order and rotation stable, separated carriageways retained,
curved stations bounded by actual length, and T closure explicit. Do not add a
new user control until phase 2 verifies shared seams and all layer consumers use
the plan.
## Compatibility matrix for the first slice
| Existing concept | First-slice treatment |
| --- | --- |
| Stable carriageway/arm/corner keys | Preserve source-derived keys; add plan-local keys without coordinate ordering. |
| `cluster-carriageway-width` and cutback | Read existing constraints through an adapter; retain values only when the resolved EntrySection has a feasible range, otherwise mark recheck/stale. |
| Corner radius | Preserve as a compatibility request, but do not derive a final curve until BoundaryGraph feasibility exists. |
| Crossing and stop-line offsets | Keep document readability; mark as dependent on an arm/section plan and do not create a facility from angle alone. |
| Ordinary junction output | No behavior change in the first slice. |
| Reference-file calibration | Move I/O outside the pure resolver and inject resolved metrics. |
## Checks run
`node test/junction-build-plan-counterexamples.js`
This is a planning-stage baseline and is intentionally not added to `npm test`
until phase 1 replaces its current-state assertions with the new plan contract.