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

8.3 KiB

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.

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, EntrySections (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.