143 lines
8.3 KiB
Markdown
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.
|