Files
pipelines/app/notes/P2c.md
T
alan b381290f34 feat(app): add deterministic orthogonal graph edge routing
Pure-Dart P2c slice: interval-aware ports and corridors, label-aware lane spacing, measured label placement with fallback shelf, skipped diagnostics and routing bounds. 20 focused tests plus existing suite and web build pass.
2026-10-21 16:51:38 +01:00

117 lines
6.8 KiB
Markdown

# 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<GraphEdge> edges,
required Map<int, LabelExtent> 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.