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-2841groups ordinary junction approaches bysegmentId, sums both directions into one width, and selects the first road for the approach line.src/compile/complex-junction.js:17-89creates 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 insrc/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-88andjunction-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()andsidewalkRing()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:
JunctionBuildPlanwith version, source topology, stable carriageway keys,EntrySections (source polyline, far station, entry station, tangent, left/right boundary endpoints), grouping provenance, and diagnostics; or- 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.