# 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.