# P2c — deterministic orthogonal edge and label routing ## What changed New app-only, pure-Dart files. No existing file, server, web client, legacy client, shell, `main.dart`, pubspec, domain, layout, other feature or platform source was edited. | File | Lines | Responsibility | | --- | --- | --- | | `lib/features/graph/routing/route_models.dart` | 261 | public route, port, label, diagnostic and bounds types | | `lib/features/graph/routing/routing_inputs.dart` | 64 | measured label extents and caller clearances | | `lib/features/graph/routing/route_geometry.dart` | 175 | axis track allocator and column-gap bands | | `lib/features/graph/routing/corridor_plan.dart` | 105 | vertical corridor allocation per column gap | | `lib/features/graph/routing/edge_route_planner.dart` | 265 | forward/back/same-rank/self-loop polyline planning | | `lib/features/graph/routing/edge_label_placement.dart` | 175 | measured label boxes clear of nodes and other labels | | `lib/features/graph/routing/graph_edge_routing.dart` | 135 | validation, skipped diagnostics, labels, total bounds | | `test/features/graph/routing/routing_fixtures.dart` | 143 | chain/diamond/parallel/cycle/self-loop/disconnected fixtures | | `test/features/graph/routing/routing_assertions.dart` | 215 | orthogonality, borders, node interiors, corridors, labels, bounds | | `test/features/graph/routing/graph_edge_routing_test.dart` | 191 | chain, diamond, parallel, cycle, loop, disconnected, expanded text, unknown targets | | `test/features/graph/routing/graph_routing_geometry_test.dart` | 161 | wide labels, tight gaps, 3-stage SCC, backward layout, loop + forwards | | `test/features/graph/routing/graph_routing_validation_test.dart` | 222 | empty input, missing measurements, duplicate ids, invalid config, determinism/immutability | No painting, widgets, styling, shell wiring or font/CSS/device constants were added. ## Public API ```dart GraphRouting routeGraphEdges({ required GraphLayout layout, required List edges, required Map labelExtents, required RoutingConfig config, }); ``` `RoutingConfig` takes `nodeClearance`, `laneSpacing`, `corridorSpacing`, `portSpacing`, `labelGap` and optional `boundsPadding`. `LabelExtent` is the caller's measured label width/height. The node boxes and ranks are the landed `GraphLayout` values; the router never moves or resizes a node. `GraphRouting` exposes unmodifiable `routes`, `labels`, `skipped`, `width` and `height`, plus `routeFor(id)` / `labelFor(id)`. Each `EdgeRoute` keeps the definition `id`, `source`, `outcome`, `target`, `label` and `fallback` flag, and returns `sourcePort`, `targetPort`, a `RouteKind` and an orthogonal `points` list. Each `EdgeLabelBox` carries the measured box for its edge id. ## Deterministic guarantees (and what is not claimed) - **Identity:** routed edges copy the definition identity unchanged; skipped edges keep it in `RouteDiagnostic` with `unknownSource`/`unknownTarget`. No node, route or visit is invented for an empty, missing or unknown target. - **Order and stability:** routes, labels and diagnostics are ordered by edge id regardless of input order. Equal input produces equal, immutable results. - **Orthogonality and ports:** every consecutive point pair shares one coordinate. Endpoints are exactly on the source/target border with the recorded side: forward routes leave right and enter left; same-rank, backward and self-loop routes leave/enter the right side. - **Node avoidance:** a forward one-rank route is a straight horizontal run only when the boxes share a port band and leave room for label-aware track spacing. Every other route drops into a unique horizontal lane below the node grid, travels vertically only inside column gaps (or the free space right of the last column), and returns to a port through its own stub. Vertical corridors and lanes never enter a node column, and every horizontal stub stays on a row that is clear of unrelated node boxes. - **Distinguishable runs:** vertical tracks are spread across each gap, one slot per corridor request; horizontal stubs and straight routes share one interval-aware allocator; every wrapping route owns its own lane. Two edges cannot share a collinear run in the tested fixtures. - **Labels:** each routed edge needs a measured `LabelExtent`; a missing one is an `ArgumentError`. The box is placed at a deterministic route run, clear of node interiors and earlier labels. If a run is too narrow (for example a wide label between close columns), the label moves to a free shelf below the drawing and the returned bounds grow instead of covering a node. - **Bounds:** `width`/`height` include the landed node layout, all route points and all label boxes, plus `boundsPadding`. A self loop or an edge into the right-free gap expands the box; nothing is clipped. - **Not claimed:** perfect general crossing minimization or minimal bend counts. Corridors and lanes are deterministic and locally separated, not a globally optimal routing. ## Checks actually run ``` flutter pub get dart format lib/features/graph/routing test/features/graph/routing # 0 changed flutter test test/features/graph/routing # 20 passed flutter analyze # No issues found! flutter test # 193 passed ``` Focused coverage includes chain, diamond fan-out/fan-in, three outcomes to one target, a two-stage and a three-stage SCC, a self loop alone and beside forward routes, disconnected stages, heterogeneous widths, 2.6x expanded text, tight gaps, wide labels, a caller-supplied backward rank, missing/empty/unknown targets, immutability, stable ordering and finite bounds. ## Honest limits - **No rendering.** This is a nonvisual geometry slice: no painter, widgets, native controls, screenshots or browser behavior. Rendered parity belongs to the next renderer task. - **Layout is an input.** The router does not widen columns for labels or move nodes. Very wide labels may sit on the free shelf below the drawing; callers that want labels beside an edge should reserve enough column gap when laying out nodes. A zero-width column gap leaves no space for distinct vertical corridors, so callers should supply a positive gap (the landed layout keeps whatever gap it is given). - **No general crossing optimum.** Only deterministic corridor/lane separation is guaranteed, as described above. - **No server or device.** Tests use local fixtures only; no run, pipeline, schedule, service, emulator, ADB, Android/iOS build or live chat was touched. - **Mobile unverified.** Only web-targeted Flutter test/analyze ran. - **Uncommitted candidate.** Per this stage's instruction the slice is left in the worktree; no commit, push or deployment was made.