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

6.8 KiB

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

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.