Epic P4: Junctions & Signals

[JArmandoAnaya]

Pillar P4 of the Road to Parity roadmap · Milestone P4 — Junctions & Signals · P4 discovery.

Status (2026-07-21): restructured by the 2026-07 realignment — the remaining scope is cut into three behavior areas in this order: junction control (p4-s3/s4) → junction interior surface control (p4-s5) → maneuvers + signalization + signs (p4-s6…s9). 9/9 sprints done — all P4 sprints merged. p4-s7 (#228) shipped its own single-part rm:signalmount linkage (signal odr_id → object odr_ids, already list-shaped) rather than waiting on p6-s9 (assemblies, #323); when #323 lands it swaps a model id for an assembly id with no schema change.
Explicit deliverable — DONE: the stopline entity was designed once (P4 discovery §3) and landed in p4-s3 (#318): records sparse on Junction keyed by RoadEnd, one pure junction_stoplines() query shared by the mesher, the writer, the editor and the bindings, and rm:stopline persistence per ADR-0008 (materialized signalLines object = Layer 0, userData = Layer 1). The P3 crosswalk companion migrated onto it; p4-s6 maneuver termination reuses it. The #318 GUI hand-check (drag/flip/save/reload/third-party viewer) is still pending the maintainer — recorded as GW-5 step 5b.
Every new non-ASAM carrier in this pillar (rm:stopline, locked-state/span extensions, span records, rm:maneuver, rm:phases) follows ADR-0008.
Follow-ups: #311 (pre-existing write_xodr segfault on a junction with a dangling arm road) RESOLVED 2026-07-20 in PR #330 — p4-s4 is no longer gated, #313 (USD compliance wrapper migration; CI pins usd-core<26.8 meanwhile).
GW-3 steps 6–11 are implementable — the hand-run gates this epic together with GW-4.
Update (2026-07-23, field triage batch 2 — #397): the pillar was sprint-complete; it reopens for one release-blocking item — bug #402 (junction-floor sidewalk band segmentation: jagged seams + zero-band collapse; not a #385 regression, lands before #356). Gates v0.1.0 per the batch-2 decision. GW-3/GW-4 hand-run status is unaffected until it lands.
Update (2026-07-25): #402 landed (PR #441, main 408266a). The pillar's remaining open item is #356 (curved-approach corner solver, still DEFERRED pending a field repro), plus the GW-3/GW-4 hand-runs — so this epic stays open.

Update (2026-07-27): two changes. #356's deferral premise is gone — it reproduces in the headless harness (PR #445, main dd593d7; the missing ingredient was the sidewalk profile, no field file needed), so the solver redesign is unblocked. And #440 (junction floors + ground surfaces are untextured — no UVs; split out of #360) is homed here per maintainer decision, release-blocking under the amended gate rule (PR #458: follow-ups of gated issues inherit blocking status).

Update (2026-08-02): #356 is fixed (PR #559, main d41052f) — the solver redesign the 2026-07-22 findings called for, verified headlessly rather than visually as that comment predicted would be necessary. The pillar's remaining open items are #440, #480, #534, #537 and the GW-3/GW-4 hand-runs, so this epic stays open.

Scope

Corner tool (done: control-vertex/extent reshape, radius, materials); junction control: stopline entity + per-road default stoplines, locked/custom junctions (manual create, convert auto↔locked, add/remove roads, merge, parallel-road s-span and single-road junctions, corner re-derivation); junction interior surface control: per-span visualization, Include Samples, Sort Index; maneuvers + signalization + signs: maneuver roads with Lock Geometry and Turn Type; Signal tool with auto-signalize templates and <controller> export; Signal Phase Editor in the 2D Editor pane; Sign tool with editable text.

Feeds

GW-3, GW-4.

Sprints

• p4-s1: Corner tool — selection, control vertices, extents, radius #225 — Corner tool — selection, control vertices, extents, radius (PR feat(junctions): Corner tool — selection, control vertices, extents, radius (p4-s1) (#225) #310, main 4195e27)
• p4-s2: per-corner + junction-wide materials #226 — per-corner + junction-wide materials (PR feat(junctions): per-corner + junction-wide materials (p4-s2) (#226) #312, main 577b0d3)
• p4-s3: stopline entity + per-road default stoplines #318 — p4-s3: stopline entity + per-road default stoplines (PR feat(junctions): stopline entity + per-road default stoplines (p4-s3) (#318) #331, main 317c216)
• p4-s4: junction control — locked junctions, membership, merge, span junctions #319 — p4-s4: junction control — locked junctions, membership, merge, span junctions (PR feat(junctions): locked junctions, membership, merge, span junctions (p4-s4) (#319) #341, main 5dbe66d)
• p4-s5: junction interior surface control — spans, Include Samples, Sort Index #320 — p4-s5: junction interior surface control — spans, Include Samples, Sort Index (PR feat(junctions): interior surface control — spans, include samples, sort index (p4-s5) (#320) #343, main 1b7a054)
• p4-s6: maneuver roads — derivation, editing, Turn Type #227 — p4-s6: maneuver roads — derivation, editing, Turn Type (PR feat(junctions): maneuver roads — derivation, editing, Turn Type (p4-s6) (#227) #350, main 950939c)
• p4-s7: Signal tool — auto-signalize templates + linked assemblies #228 — p4-s7: Signal tool — auto-signalize templates + linked assemblies (PR feat(signals): Signal tool — auto-signalize templates, controllers (p4-s7) (#228) #362, main 853974c)
• p4-s8: Signal Phase Editor in the 2D Editor pane #229 — p4-s8: Signal Phase Editor in the 2D Editor pane (PR feat(signals): Signal Phase Editor — timeline, scrubbing, rm:phases (p4-s8) (#229) #363, main 561d663)
• p4-s9: Sign tool with editable text #230 — p4-s9: Sign tool with editable text (PR feat(signals): Sign tool — editable text, text-to-texture faces (p4-s9) (#230) #365, main f0d1882)

Follow-ups

2026-07-31 (roadmap review): filed #534/#537 — junction-side xodr fidelity findings in modeled scopes (the preservation sweep #453 will not repair them).

• write_xodr segfaults on a junction with a dangling arm road #311 — write_xodr segfault on a junction with a dangling arm road (PR fix(xodr): never dereference a stale road link when writing (#311) #330, main ce06d84) — the writer now resolves road links before dereferencing; unblocks p4-s4
• junction corners: curved approaches produce colliding corner geometry (straight-ray solver) #356 — junction corners: curved approaches produce colliding corner geometry (straight-ray solver; field triage roadmap: triage 2026-07 field reports #351) — FIXED (PR fix(mesh): pave the arc a road curving through a junction actually describes (#356) #559, main d41052f). All four causes the instrumentation plan named were wrong: every corner solved valid=true and nothing early-returned. The real fault was that a road curving THROUGH the junction had its two halves treated as a 112° street corner, so the straight rays met at a fabricated apex 7.18 m beyond the true pavement edge. Detected now the way the straight case always was (parallel_edges's curved analogue) and paved as the arc corridor the edge describes. Straight approaches bit-identical; ASan/UBSan clean
• render: junction floors and ground surfaces are untextured (no UVs), so the asphalt/concrete texture never reaches them #440 — render: junction floors and ground surfaces are untextured (no UVs), so the asphalt/concrete texture never reaches them (split out of ci: junction floor renders black in the visual-artifacts job (software GL), misleading the human-review artifact #360; homed to P4 2026-07-27; release-blocking per the amended gate rule, PR docs(roadmap): release gate covers follow-ups split out of gated issues #458)
• kernel+editor: signal/object <validity> lane restrictions are preserved but invisible and unauthorable (§14.2/§13.6) #480 — signal/object <validity> lane restrictions are preserved but invisible and unauthorable (§14.2/§13.6; 2026-07-28 roadmap review; awaiting triage — not release-blocking unless triaged in)
• xodr: direct and crossing junctions are corrupted on round-trip — @type dropped, connections skipped as 'unknown road' #534 — xodr: direct and crossing junctions corrupted on round-trip — @type dropped, every connection skipped as "unknown road", saved back as an empty common junction (2026-07-31 roadmap review; awaiting triage)
• xodr: virtual-junction fidelity — link @elementS/@elementDir dropped, foreign connections deleted, connection children dropped #537 — xodr: virtual-junction fidelity — link @elementS/@elementDir dropped, foreign virtual-junction connections deleted, connection children beyond <laneLink> dropped (2026-07-31 roadmap review; awaiting triage)
• junction corners: continuous sidewalk wrap + mixed sidewalk/no-sidewalk boundary #357 — junction corners: continuous sidewalk wrap + mixed sidewalk/no-sidewalk boundary (PR feat(mesh): carry a continuous sidewalk band around junction corners (#357) #385, main d8f6cdc)
• junction floor: sidewalk band segmentation — jagged seams, and zero-band collapse on tight/single-sided/non-outermost cases #402 — junction floor: sidewalk band segmentation — jagged seams + zero-band collapse (PR fix(mesh): cut junction floors along the sidewalk seam, not near it (#402) #441, main 408266a) — the floor is now cut ALONG the sidewalk seam (the band's interior outline becomes constrained CDT edges before triangulation) instead of classified near it; all four numeric criteria met with margin (mid-band misclassification 0.000 % vs a < 1 % ceiling, seam deviation ≤ 0.0006 m vs < 1.0 m, zero collapses), measured by the triage's probe oracles now living in core/tests/test_junction_sidewalk_bands.cpp

Supersedes

(none)