Skip to content

Latest commit

 

History

History
588 lines (485 loc) · 37.1 KB

architecture.md

File metadata and controls

588 lines (485 loc) · 37.1 KB

Canonical Road Authoring Architecture

Decision

RoadNetworkCompilation is the canonical compiled product, not the editor's source document. The editor authors a higher-level, persistent RoadAuthoringDocument; a deterministic compiler derives both an road-network RoadNetwork and its RoadPhysicalTopology. No UI tool or scenario may mutate compiled roads, lanes, junctions, boundaries, surfaces, or markings directly.

This keeps a Cities: Skylines-like workflow simple at the interaction layer while the compiled result remains precise enough for simulation, SVG inspection, terrain, and 3D surface generation.

road-network concepts belong in the compiled network: reference lines, lane sections, lane links, elevation, superelevation, road marks, and connecting roads. The authoring document owns intent: templates, drawn alignments, graph connectivity, maneuvers, and regulations.

Ownership

RoadAuthoringDocument                    RoadNetworkCompilation
----------------------                   --------------------------------
RoadTemplate                         ->  Road / ReferenceLine
RoadStroke + profile                 ->  LaneSection / Lane / width records
Stroke endpoint links + JunctionIntent -> Junction / connector Road
Maneuver + regulation                ->  Lane links / boundary markings
Lane bands and junction intent       ->  Shared boundaries / surface ownership
Island, crossing, platform intent    ->  RoadObject / pavement holes
Roadside feature intent              ->  Ditch / retaining-wall cross-sections
Junction surface and marking intent  ->  Elevation metadata / control-bound markings

                      compiler
                           |
                           v
        RoadNetwork + RoadPhysicalTopology + diagnostics
                           |
                           v
                 3D surface, terrain, traffic, and export consumers

The flow is one-way. Derived IDs and diagnostics point back to source IDs, but consumers do not edit the RoadNetwork in place. A precise edit is represented as a source-level constraint or override and then recompiled.

Junction marking plans

Junction movement topology, physical pavement ownership, and regulatory paint are three separate compiler products. A permitted maneuver never becomes a painted trajectory, and the outline of a paved junction never becomes an edge marking.

Every common junction resolves a JunctionMarkingPlanIntent. The German rule plan may derive approach control lines from the junction control plan, lane-use arrows from distinct multi-lane movement assignments, and broken separators only between lanes of one physical multi-lane connector corridor. Single-lane connector roads receive no inferred longitudinal marking. Curved guides, channelization lines, and exceptional edge treatments must be explicit connector marking intent. explicit-only and none generation modes allow a template or precision editor to suppress each derived class independently.

At direct split and merge terminals, an edge marking is additionally constrained by physical pavement exposure. The compiler intersects each marked lane boundary with the other terminal-member lane surfaces and clips the marking at the first covered point. A template edge therefore cannot continue through an entering ramp merely because its source lane reaches the road endpoint. The operation is geometric, applies to every direct terminal, preserves exposed boundaries, and is idempotent.

Source Authoring Model

Road template

A RoadTemplate is a reusable cross-section and behavioral policy, not prebuilt geometry. It defines:

  • ordered lane roles for both travel directions and non-motorized space;
  • default widths, width limits, lane types, direction, access, and surface level;
  • boundary and curb rules;
  • default lane-bound markings and regulatory defaults;
  • design limits such as nominal/minimum curve radius, grade, crossfall, and taper length;
  • junction compatibility, including which lane roles may enter, leave, merge, or diverge.

A template may be applied over station ranges. Template transitions are explicit source operations, so a lane addition, parking-to-bike conversion, or shoulder opening has a named reason and a valid transition policy.

The compiled lane retains its stable source role across every section. Lane IDs may change when a cross-section grows or shrinks, but physical-band contacts and lane-graph continuations match the role first and use lateral overlap only for legacy roleless data. When a disappearing lane temporarily occupies a continuing lane's target ID, the continuing lane keeps its upstream ID through the taper and renumbers only at the completed static section boundary.

Road stroke

A RoadStroke is what the user draws. It owns an alignment, direct endpoint continuity, optional horizontal/vertical constraints, and template spans. It is not a compiled road ID.

The initial alignment vocabulary is line, arc, spiral, and parametric cubic. A user may draw freely, then constrain tangents, radii, stations, grades, and vertical curves. The compiler either resolves a valid alignment or returns an actionable diagnostic; it never silently approximates invalid geometry into a different topology.

Templates compile design speed metadata and station-scoped limits for horizontal radius, grade, superelevation, curvature continuity/rate, and spiral length. These are validated against the analytic alignment and cubic profiles, not against SVG samples. Consecutive geometry records must also meet in both position and heading even when their s values are numerically consecutive.

Direct continuity and junction intent

A direct stroke endpoint link represents exactly one non-junction continuation. A JunctionIntent owns the participating approach ports, junction kind, permitted maneuvers, priority/control, crossings, islands, and localized overrides. Junctions are not inferred solely from overlapping polygons.

Each allowed maneuver names a source lane role or source lane and a target lane role or target lane. The compiler creates a connector road for common-junction movements. Direct junctions are limited to true continuous split/merge cases; crossing junctions model a crossing without inventing vehicle turning paths.

Source maneuver IDs survive connector materialization and physical-topology compilation. Every unordered maneuver pair has one compiled interaction (merge, diverge, crossing, or compatible). A JunctionControlPlan compiles priority approaches, German right-before-left and opposing-turn rules, roundabout yield, signals, all-way stops, or zipper merges into an executable control for each pair. Pair-specific priority is reserved for genuinely exceptional regulation. An unresolved physical conflict is a compilation error.

Conflict detection intersects fixed-width operational occupancy envelopes around movement centerlines, not full paved lane polygons. Paved connector bands may overlap inside an unmarked junction even when two trajectories are operationally compatible, as with opposing tangential left turns. The resulting conflict polygon is only the footprint owned by the semantic interaction; it never defines the maneuver relationship or right-of-way by itself. Exact tangent circular contacts compile to analytic arcs before the general cubic connector fallback, keeping ordinary orthogonal turns out of the junction center.

Coupled movements are solved as one geometric problem. For example, a roundabout arm uses one paired throat solution for its entry edge, exit edge, and splitter island. The island is derived from the clearance between those solved lane edges and the circulating lane; it is not positioned independently from percentages of the roundabout radius.

A crossing junction owns shared pavement without owning a turning movement. Its participating roads remain uninterrupted, its trafficStreams describe lane-local through participants, and its physical topology uses the overlap surface policy. Tessellation intersects the participating road envelopes into positive-area overlap patches owned by the junction's stable surfaceOwnerId; conflict zones and stream interactions remain operational semantics and do not double as pavement ownership. No connector road or direct lane link is invented for the crossing.

A raised table is source intent on a common junction. surfaceElevation retains the raised-table kind, positive height, and positive ramp length in both the compiled junction and physical topology. The approach strokes still own their analytic cubic elevation transitions; canonical raised-table documents use them to arrive at the stated common contact height. The junction metadata is the surface/renderer contract, not a request for a consumer to synthesize ramps.

Canonical basic turbo roundabout

The basic turbo roundabout is authored as a RoadAuthoringDocument and follows the same compiler path into RoadNetwork and RoadPhysicalTopology as every other canonical scenario. Its circulating carriageway is defined by two translated spiral centers rather than concentric circular lanes. At the north and south contacts, the incoming inner lane remaps to the outgoing outer lane, the incoming outer lane is forced to exit, and the entry creates the new inner circulating lane. The east and west contacts retain two-lane circulation through junction-owned connector corridors.

Each arm throat is solved from exact circulation and approach endpoints. Entry, exit, and splitter-island geometry therefore share the same contact constraints instead of relying on visual offsets. Connector-owned marking intents carry edge and lane-divider semantics through connector bands. All four contacts belong to one roundabout control group, with entry traffic yielding to circulating traffic.

Canonical acceptance requires every permitted arm-entry route to reach an arm exit, with no ring-only cycle; every source maneuver to own exactly one physical movement; all movement, throat, and island surfaces to be simple and mutually disjoint where required; and both document and compiled-network validation to complete without diagnostics.

Lane changes and routability

Longitudinal lane topology alone is insufficient for ordinary multilane roads and roundabouts. A lane boundary marking may therefore declare road-network laneChange permission (increase, decrease, both, or none). The lane graph compiles that intent into directed lateral edges only between adjacent compatible lanes, over the marking's station range. Connector roads never infer lane changes: a junction connector represents one committed movement and must be left before another lateral choice is made.

Section-continuation edges follow the lane's actual travel sign, not increasing reference station by default. Reversed lanes therefore traverse section records from higher to lower s; bidirectional lanes expose both traversals; a direction flip has no continuation; and opposing adjacent lanes can never receive a lane-change edge even when a marking is malformed.

Lane-graph nodes retain the compiled lane access set. A route query may select one participant class; the start, target, and every entered node must either be unrestricted or explicitly admit that participant. This makes the same graph usable for cars, buses, emergency vehicles, bicycles, pedestrians, and trams without cloning topology. Lateral edges are emitted only when the adjacent lanes have overlapping access sets, compatible traffic roles and lane types, and a common travel direction. Participant filtering composes with destination-only zones and the option to disable lane changes, so access-restricted facilities cannot become accidental shortcuts.

Roadside terrain features

Roadside ditches and retaining walls are first-class RoadsideFeatureIntent values, not road objects or renderer polygons. Each feature binds an exact station range to a stable source lane role that must remain the outermost lane on one side through every covered template and transition. Compilation resolves that role to the physical left/right side while preserving the source identity in RoadNetwork, RoadPhysicalTopology, and the source map.

A ditch carries pavement gap, depth, bottom width, and horizontal-to-vertical bank slope. A retaining wall carries pavement gap, thickness, linearly varying start/end height, and cut or fill face semantics. Both cross-sections are evaluated from the current compiled outer lane boundary at station, so widening, tapers, curves, and lane-ID changes move the terrain feature without changing its source binding. Invalid dimensions, ranges, bindings, non-outermost roles, side changes, and pavement overlap are compilation errors.

Dense multimodal common junctions

Irregular N-arm intersections use the same source-to-physical pipeline as ordinary three- and four-arm junctions. T046 is the canonical scalability case: five street ports and two tram ports share one common junction, producing twenty vehicle maneuvers, two tram-through maneuvers, and ten typed curb/sidewalk continuations. Tram paths are maneuvers rather than a second overlapping crossing junction, so every vehicle/tram conflict belongs to the same complete signal interaction table and every occupied band has one physical owner. The tram lane type represents the reserved track corridor; individual rail-gauge geometry remains a later rendering/topology layer.

Typed non-traffic bands use separate laneContinuations rather than pretending to be vehicle maneuvers. Bidirectional sidewalk and curb continuations compile into ordinary junction-owned connector roads, retain level/access/height metadata in physical topology, and are excluded from vehicle conflict and control tables. Lane-height records interpolate linearly by station; raised curb shape remains lane-local instead of becoming road superelevation.

Lane-surface projection follows the road-network level contract. Once a lane on one side is level, every lane farther outward is level. Its inner edge is anchored to the outer surface of the inward lane, its plan-view width is projected horizontally, and its explicit lane height is applied in world z. This keeps a sidewalk flat beside a banked carriageway while preserving a shared curb boundary. Connector contact roll is derived from the projected cross-section, so banked driving lanes and level perimeter bands each retain their actual surface orientation through a junction.

Grade-separated interchanges

Grade separation is explicit source intent, not an inference from two centerline heights. A GradeSeparationIntent names the upper and lower stations, crossing kind, deck thickness and extent, and required clearance. Compilation evaluates the complete 3D lane cross-sections and records the actual pavement clearance in both RoadNetwork and RoadPhysicalTopology.

T073 composes four exact G2 motorway terminals, four C2 graded one-way ramps, two controlled six-movement arterial terminals, and two bridge-over-carriageway relations in one highway-interchange group. It has no crossing junction or cross-level lane edge. The SVG renderer draws an opaque upper deck and clips lower surfaces, markings, reference lines, and diagnostics while preserving semantic clearance data.

T074 adds a reusable signed-deflection clothoid-arc-clothoid builder and a generic direct ramp-terminal intent. Its 270-degree loop is authored as a C2 spiral-arc-spiral alignment with smooth cubic elevation and banking profiles, exact split and merge lane contacts, and explicit bridge relations between two paired motorway facilities. T072, T073, and T074 all use the same role-mapped direct-terminal builder; catalogue cases do not inject compiled lane links.

T075 adds a general non-parallel G2 turn solver, a direct lane-fork/merge intent, and exact reference-line intersection solving. The trumpet contains twelve source roads, six direct terminals, twenty-eight role-mapped physical links, one 270-degree loop, three semi-directional ramps, and five explicitly declared structures. Every transverse non-contact crossing is found from source geometry and matched by one grade-separation relation; the two-level loop bridges and three-level semi-directional flyover are validated from full lane-surface clearance.

T076 composes sixteen travel-oriented source strokes, two 270-degree loops, two 90-degree direct ramps, eight G2 split/merge terminals, and forty role-mapped physical links. A reusable station-aware plan-crossing audit enumerates each crossing instance, including repeated crossings between one road pair, and requires exactly one topological or grade-separation owner. The renderer keeps all four crossing relations while coalescing their overlapping extents into the two continuous physical bridge decks, preventing duplicate outlines and internal deck seams. Marked lane changes between through, entry, exit, and ramp lane types remain routable when their access policies agree.

T077 introduces a first-class weaving-section intent over ordinary road-owned pavement. It binds one adjacent through/weaving lane pair to exact entry and exit maneuvers across a bounded station interval. Compilation resolves every covered lane section into stable lane IDs and physical corridor band/boundary IDs; it does not invent a junction surface or a conflict polygon. Lane-graph exchange edges preserve their complete legal station range and carry the weaving-section identity. The SVG topology and conflict presets render the same compiled operational band, while the base preset remains ordinary opaque pavement.

T078 composes that operation into a collector-distributor system instead of adding a scenario-specific facility primitive. A persistent three-lane mainline and a separated collector carriageway are connected by two source-owned G2 transfer roads and four direct terminals grouped as one highway interchange. Each transfer changes from off-ramp to on-ramp semantics, and the collector's inner exchange lane owns the bounded weaving interval. Weaving validation and SVG evidence are lateral-order agnostic: the exchange lane may be inside or outside the through lane, with the shared physical boundary derived from actual lane bands. No connector road, conflict polygon, or cross-carriageway shortcut is inferred.

T079 introduces a first-class longitudinal road structure for bridge and tunnel intervals. The structure owns one road, station range, structural thickness, lateral deck envelope, and required edge clearance. Compilation evaluates exact piecewise-cubic outer road-boundary extrema over the complete interval; a lane taper that remains inside the structure range is therefore a hard error rather than a sampled mesh artifact. A grade-separation relation may reference the same structure and must match its road, kind, thickness, and station range, so lateral deck fit and vertical under-deck clearance cannot drift into separate bridge models. The physical topology and SVG renderer retain one structure owner and one crossing relation, without duplicate deck polygons.

T080 makes curved lane transitions a travelled-path contract rather than a reference-line approximation. Lane births and deaths compile to three piecewise cubic width records with continuous value, slope, and second derivative. Variable-offset kinematics include t(s), t'(s), t''(s), reference curvature rate, lane offset, and projected superelevation when evaluating lane-center heading and curvature. Templates may therefore constrain both the reference-line radius and the minimum usable traffic-lane-center radius. A banked direct ramp terminal starts at the exact 3D lane-surface offset pose and preserves G2 contact before its ramp reference line unwinds through a spiral. Newly appearing traffic lanes require a legal lane-change entry just as disappearing traffic lanes require an escape.

T081 models a motorway service area as a destination-only routing zone rather than a disconnected visual branch. Two direct G2 terminals connect the mainline to an off-ramp, service road, and on-ramp whose ordinary road links preserve complete endpoint lane-role coverage. Policy-aware routing may enter the shared facility zone only when the route starts or ends there, preventing it from becoming a through-traffic shortcut while still proving ingress, internal continuity, and egress. The service road owns its parking-lane transitions and parking objects as ordinary compiled lane geometry; no special service-area pavement is inferred by the renderer.

T082 treats an emergency lay-by as a local width change of one persistent shoulder lane, not as a branch, junction, or newly appearing traffic lane. The narrow/wide/narrow template sequence compiles C2 width records while retaining stable lane roles, IDs, travel directions, and driving routes. Lane-bound road objects preserve their source role, boundary anchor, inward inset, allowed lane types, and containment policy in the compiled model. Oriented and repeated footprints use exact per-instance lateral offsets and are validated against the piecewise-cubic lane envelope. Cubic lane-width minima are solved analytically rather than accepted from coarse samples.

T083 keeps both motorway driving lanes topologically continuous while the persistent inner and outer shoulder roles narrow through a C2 approach profile into a tunnel. The tunnel is an explicit longitudinal road structure with an analytically checked lateral envelope, not a dark renderer effect. Portal pillars remain lane-contained, structure-bound road objects, and the SVG derives the transverse portal diagnostic from the exact structure start frame. The reference surface simultaneously follows a smooth cubic elevation profile, preserving the same lane and object ownership contract for later 3D tunnel meshing.

Junction ports have stable identities and an exact road station. A road may therefore participate more than once in one junction without an ambiguous road-ID lookup. This is required for virtual junctions, where one uninterrupted main road owns a flat sStart to sEnd range and branch movements name the relevant main-road port explicitly.

For a common-junction movement at an internal station, contactPoint describes the side of the station used by travel: end approaches the station along increasing s, while start departs it along increasing s (reversed lanes invert those meanings). The materialized connector stores the exact target station on its lane link. It does not invent a road-level predecessor or successor at the nearest physical road endpoint.

Continuous and branch lanes participate through stable JunctionTrafficStream identities. A crossing therefore compiles exact lane bands, travel headings, operational occupancy windows, pairwise stream interactions, and fixed or signal control without inventing a connector road. Virtual-junction entry and exit participants also carry a contact-group identity, so merge and diverge relationships are tied to one physical contact rather than inferred from nearby overlap. Repeated station records for the same continuous lane are intrinsically compatible. The same source participant IDs survive into physical topology and SVG diagnostics.

Marking and regulation intent

Road marks must be lane-bound or maneuver-bound. A free floating tOffset arrow is a rendering placement detail, not source truth.

For example, an ending lane has a merge-left maneuver intent; a lane approaching a junction has a set of permitted turn maneuvers; a zebra crossing is attached to an approach/crossing intent. The compiler places and orients the resulting marks from the compiled lane frame.

Transverse and area marking intents may retain controlIds that name a signal controller or one of its signal groups. Source validation rejects unknown IDs, and compilation copies the association to RoadMarking. Multiple stop lines on different participant lanes can therefore remain independently associated with car, bicycle, or tram groups under one controller.

For a non-merge arrow on a lane that feeds a common junction, source validation derives the complete permitted movement set from that road and lane role. It classifies each maneuver as straight, left, or right from the source and target lane travel headings, then requires exact set equality with the single or combined arrow symbol. An arrow that omits a permitted turn or advertises a forbidden turn fails with arrow-maneuver-mismatch; raw lateral placement cannot override the maneuver matrix. Merge arrows and arrows outside a common-junction movement set retain their separate lane-transition semantics.

Compiler Stages

The compiler is pure and deterministic. Given one document revision, it emits the same network IDs, geometry, diagnostics, and SVG output.

  1. Validate document references, templates, graph endpoints, and semantic maneuvers.
  2. Resolve stroke alignments and vertical profiles into analytic reference lines.
  3. Expand template spans into lane sections, width transitions, boundaries, and profiles.
  4. Compile direct endpoint links and explicit connector roads for every allowed maneuver.
  5. Derive movement occupancy conflicts and compile pairwise traffic controls.
  6. Derive lane/road links, crossing ownership, islands, and markings.
  7. Resolve bounded operational areas and longitudinal road structures into physical evidence.
  8. Run topology, geometric-continuity, regulatory, and surface-readiness validation.
  9. Publish RoadNetwork, source-to-derived ID mapping, diagnostics, and SVG debug data.

The compiled physical topology assigns one surface policy to each junction:

  • connector-bands for common junctions: every movement owns explicit connector bands;
  • none for direct junctions: exact lane contacts join corridor surfaces without a patch;
  • overlap for crossings: the shared crossing area has one junction owner and no turns;
  • overlap for virtual junctions: branch overlap is owned while the ranged main road stays uninterrupted.

For a crossing, roadIds names the roads whose envelopes participate in the overlap and surfaceOwnerId names the single junction owner. The overlap tessellation may contain multiple connected components, but every component remains a patch of that same semantic owner. Traffic streams and their pairwise conflict zones may share the footprint; they never become additional surface claims.

These policies are semantic, non-sampled data. SVG and future 3D consumers independently tessellate the same parametric bands. Compilation rejects missing surface owners, duplicate band claims, discontinuous section envelopes, overlapping junction owners, and direct lane contacts that miss position, heading, grade, roll, or required G2 curvature tolerances. Connector contacts additionally compare both three-dimensional lane boundaries and the unclamped lane width. Generated connector contacts use metre/radian tolerances at 1e-5 for position and 1e-6 for heading, curvature, grade, roll, and width.

The current geometry kernel, lane evaluator, connector solver, RoadNetwork, physical topology, validation, and SVG renderer belong below this compiler boundary. They are retained and strengthened; they are not the public authoring surface.

Required Invariants

Compilation fails, rather than producing a plausible-looking network, when any of these are false:

  • every compiled road has one continuous analytic reference line with ordered stations;
  • every non-center lane has valid width/border coverage and no offset-envelope cusp;
  • lane IDs and travel direction follow the canonical lane-section convention;
  • every common-junction maneuver is an explicit connector road with source and target lane continuity at both ends;
  • every common-junction maneuver pair has one stable interaction and every maneuver-bound conflict zone has exactly one interaction owner;
  • every physical conflict has fixed or dynamic control semantics; no connector ordering or polygon iteration order decides priority;
  • every entering or leaving traffic stream resolves a complete, contact-specific merge or diverge group, while repeated records of one continuous lane never conflict with itself;
  • every typed junction lane continuation remains bidirectional, junction-owned, and distinct from the traffic interaction graph;
  • every connector has G0/G1 continuity, bounded curvature/grade/bank, and a simple lane surface envelope; authored high-speed movements may require G2 and a minimum radius;
  • every turbo-roundabout entry route reaches an exit, no circulation-only lane cycle exists, and each source maneuver owns exactly one compiled physical movement;
  • turbo-roundabout connector, throat, and splitter-island surfaces are simple and satisfy their required disjointness and clearance relationships;
  • no ordinary road has ambiguous links outside a declared junction;
  • every directional marking resolves to an existing compiled lane;
  • every non-merge arrow associated with common-junction movements exactly matches that lane's complete straight/left/right maneuver set;
  • every lane-bound marking is contained by its owning lane section;
  • every marking control association resolves to an authored signal controller or signal group and survives in the compiled marking;
  • every participant-aware route enters only unrestricted lanes or lanes whose access set admits that participant, and every lane-change edge joins lanes with overlapping access;
  • every crossing junction has one overlap surface owner and no connector movement, while its operational traffic-stream interactions remain distinct from surface ownership;
  • every raised-table elevation belongs to a common junction, has positive height and ramp length, and is retained by semantic and physical topology;
  • every roadside feature remains bound to an outermost stable lane role on one side for its complete station range, has a valid cross-section, and stays outside pavement;
  • every weaving section has one continuous adjacent lane pair, bidirectional exchange permission over its full range, and exact entry/exit maneuver ownership;
  • every road structure contains the exact analytic lateral road envelope with its required edge clearance, and linked grade separations match the same physical structure;
  • paired roundabout entry/exit envelopes and their splitter island are mutually disjoint;
  • geometry that crosses in plan is either junction-connected or explicitly grade-separated;
  • every transverse plan-crossing instance has exactly one station-matched topology or grade-separation owner, even when a road pair intersects more than once;
  • 3D pavement boundaries remain continuous across compiled road and connector contacts.

Warnings are for non-blocking design quality, such as a radius below a template's preferred value. Missing topology, invalid geometry, or unbound regulation is always an error.

3D and Terrain Contract

The 3D system is a consumer of the complete compilation. It must not invent topology.

For every lane and road surface the compiler provides a station/lateral frame, elevation, bank/crossfall, canonical shared boundary IDs, and ownership of junction pavement. The mesh builder adaptively samples these parametric records to generate watertight road surfaces; sampled SVG polygons are never source geometry. Terrain consumes an explicit road-corridor boundary and surface height field for cut/fill, retaining walls, bridges, and tunnels. Props, markings, traffic, and navigation all resolve against the same derived IDs.

Roadside drainage and retention are canonical terrain geometry rather than road objects or renderer-only polygons. Ditch banks/bottoms and retaining-wall faces are derived from their compiled road-frame cross-sections. SVG and future terrain tessellators consume the same definitions retained in physical topology; they do not re-infer offsets from sampled pavement.

Lane-change topology represents physical permission between lanes whose participant access sets overlap. Route queries then enforce one selected participant over the complete path; a bus can enter a bus-only stop bay or modal filter while the same target is unavailable to a car route.

Scenario and Test Policy

The 100 German cases are acceptance scenarios, not a parallel hand-authored system.

  • Kernel tests may construct a RoadNetwork directly to test reference-line math, lane evaluation, polygon operations, and validators.
  • Compiler tests construct RoadAuthoringDocument input and assert its compiled network.
  • New catalogue scenarios construct only source authoring documents through public authoring builders and verify compiled topology, diagnostics, and SVG layers. Existing canonical literals are migration targets, not an additional runtime path.
  • A scenario may carry explicit source constraints for an unusual real-world design, but it may not inject a raw connector, lane link, or directional mark to force an expected image.

The existing raw scenarios are legacy visual fixtures until migrated. Passing them does not prove authoring-system correctness. Canonical acceptance scenarios have their own gate: every source document must compile with zero diagnostics, every common movement must materialize one connector road, and base/topology SVG layers must remain finite and structurally distinct.

Traffic Management Phases

Temporary traffic layouts are source-owned variants, not permanent roads with decorative overlays. A TrafficManagementPlanIntent selects one phase at compilation time. Activated roads, direct contacts, markings, objects, lane operations, and regulations are excluded from the base network and retain plan/phase/source provenance when selected. Lane operations align to lane-section boundaries and may close, reverse, restrict, or assign a traffic role to a lane. Closed lanes are omitted from the lane graph; continuations and lane changes require compatible travel directions and traffic roles. Replacement markings remove the overlapping base marking before the phase-owned marking is compiled, so temporary yellow guidance cannot coexist with superseded white guidance. Regulatory signs reference compiled regulation IDs, and both references are validated against the selected phase.

Signal control is authored against stable junction port and maneuver IDs. The reusable approach-group builder assigns every entering maneuver to exactly one signal group and requires every group to be released by a phase; derived conflict interactions retain that controller ownership. Road-template design limits compile into explicit station ranges independently of the cross-section taper. This permits a deliberate design-speed boundary before an urban gateway while lane widths, shoulders, curbs, and sidewalks continue through their longer physical transition.

Alternating 2+1 allocations retain stable lane identities on both sides of lane zero. An inactive passing allocation becomes a narrow non-traffic separator band; it never renumbers a base lane or flips one lane's direction at a section boundary. Each active passing lane must have a legal merge before its allocation ends, and lane-center curvature is validated through the complete taper rather than only on the reference line. Junction maneuver lane roles are validated at source ports before compilation, including minor rural accesses.

First Vertical Slice

The first implementation slice is intentionally narrow but complete:

  1. Define one urban two-way template with sidewalk, driving lanes, and an allowed outer-lane addition/removal policy.
  2. Author one line/arc road stroke with a template transition.
  3. Compile its lane sections, taper, lane graph, and lane-bound transition mark.
  4. Author one three-approach T node with explicit permitted maneuvers and priority.
  5. Compile its portal geometry, connector roads, lane links, markings, and conflict data.
  6. Prove the result with structural tests and SVG review at multiple resolutions.

T011/T012, the priority-T scenario, and the initial modal-transition scenarios now use this slice. The remaining catalogue migrates by family: ordinary profiles, lane transitions, common junctions, roundabouts, grade-separated ramps, and modal/crossing cases.

Package Boundaries

The target package layout is:

src/
  authoring-document/  source model, commands, templates, constraints
  compiler/            alignment, corridor, junction, marking compilation
  network/             canonical compiled model and low-level builders
  geometry/            analytic evaluation and frames
  topology/            lane graph, pavement ownership, robust planar operations
  validation/          document, network, geometry, regulation, surface checks
  svg/                 compiled-network debug renderer
  scenarios/           source-document acceptance scenarios
  test-support/        raw network fixtures for kernel tests only

No code from the existing editor or its road systems is a dependency of this package.

Migration Gates

Work moves to the next stage only when all of the following are true:

  • the vertical slice has no raw compiled-network construction outside kernel tests;
  • every compiled connector has an explicit source maneuver and valid lane endpoints;
  • SVG review shows no inferred junction blobs, connector strips, or unbound directional markings;
  • document and network validation are both clean for the slice;
  • the compiler produces stable IDs across an unrelated source edit;
  • the 3D contract can be consumed without adding topology rules in the mesh layer.

road-network import/export is deferred until the compiled network has these invariants. It is an adapter around RoadNetwork, never the editor's persistence format.