# P2a — graph domain: nodes, edges, terminals, run evidence and stage visits ## What changed New, app-only, pure-Dart files. No server, web client, legacy client, shell, `main.dart`, pubspec, other feature or platform source was edited. | File | Lines | Responsibility | | --- | --- | --- | | `lib/features/graph/domain/graph_protocol.dart` | 43 | terminal constants, `resolveTarget`, terminal labels | | `lib/features/graph/domain/graph_definition.dart` | 152 | outcome/edge order, definition edges, definition nodes | | `lib/features/graph/domain/run_graph_state.dart` | 124 | recorded visited stages/routes, current-stage fallback, live start | | `lib/features/graph/domain/stage_visits.dart` | 107 | sequence-ordered visits, display visit, clamped visit selection | | `test/features/graph/domain/graph_fixtures.dart` | 96 | linear/diamond/self-loop/incomplete definitions and step fixtures | | `test/features/graph/domain/graph_protocol_test.dart` | 56 | shorthand and terminal-label regressions | | `test/features/graph/domain/graph_definition_test.dart` | 229 | edge order/ids, loops, duplicate keys, missing/unknown targets | | `test/features/graph/domain/run_graph_state_test.dart` | 170 | linear/diamond/self-loop/repeated visits/outcomes/terminals/no evidence | | `test/features/graph/domain/run_graph_state_live_test.dart` | 91 | current/last-stage fallback, live start, finished run | | `test/features/graph/domain/stage_visits_test.dart` | 150 | repeated visits by sequence, latest default, clamping, absent visit | No layout, coordinates, widgets, styles or rendering were added. ## Behavior copied from the current web client - **Terminals and `#`** (`web/src/protocol.js`): `#success`, `#failure`, `isTerminal` only for the explicit keys, and `resolveTarget`: a bare `#` becomes `#failure` for the `error` outcome and `#success` for every other outcome. All other values are preserved verbatim, including `""` and unknown stage keys. A missing target stays `null`, never a fabricated terminal. - **Labels** (`web/src/graph.js`): `nodeDisplayLabel` gives `Success` / `Failure` for graph nodes; `nodeLabel` gives the TUI-mirroring `SUCCESS` / `FAILURE`. Stage keys are unchanged. - **Definition edges** (`web/src/graph.js`): outcomes are success first, other outcomes alphabetical, `error` last; stages keep declaration order; ids are contiguous in that order; the label carries `error*` only when `fallback_error` is true. A `null` edge value declares no edge and is skipped. Empty/unknown targets are kept, with `knownTarget == false`. - **Definition nodes** (`web/src/graph.js` `layoutGraph`): stage nodes keep declaration order and one identity per key; terminal nodes are appended failure then success once any declared edge resolves to a terminal. These are definition nodes only, never run evidence. - **Run evidence** (`web/src/runDetail.js` `runGraphState`): visited stages in first-appearance order without duplicates; routes keyed `source\0outcome\0resolvedTarget` without duplicates; only a resolved terminal is visited by its target; a non-terminal target is not visited until a step lands there. Current stage is `current_stage` when non-blank, else the last recorded step's stage, else `null`. A start timestamp is read only while executing, for a `running` visit of the current stage. - **Visits** (`web/src/runDetail.js` `runTimeline`, `clampVisitIndex`, `displayVisit`, and `web/src/app.js` stage routing): visits are grouped by stage and ordered by recorded sequence with stable ties; the display visit is a positive `control.visit`, else position + 1; no requested visit selects the stage's most recent visit; an explicit index clamps to `[0, count)`; a stage with no recorded visit yields `step == null`. The run map is the same detail the runs feature already holds; this slice only reads `steps`, so it adds no second event fold. Live-event merging remains in `lib/features/runs/domain/run_step_evidence.dart` and `run_events.dart`. ## Honest edge handling - A missing/`null` definition edge produces no edge and no node. - An empty or unknown target is returned as recorded, flagged `knownTarget: false`; it never becomes a stage node or terminal and never produces a visited stage. - A blank recorded stage key is not turned into an empty visited identity. A step with a blank outcome or target records no route and no terminal visit. - Self edges and loops record one route and one node identity; nothing recurses. - A stage with no recorded visits cannot be presented as visited: selection exposes a null step rather than synthesizing one. ## Checks actually run ``` flutter pub get dart format lib/features/graph test/features/graph # 10 files, 0 changed after formatting flutter test test/features/graph/domain # 41 passed flutter analyze # No issues found! (0.8s) flutter test # 139 passed ``` Focused coverage is the requested matrix: - **Linear**: plan -> build -> ship, contiguous ids, implicit `error*` fallback, terminals. - **Diamond**: fan-out/fan-in edges stay distinct and ordered; converging routes do not merge. - **Self loop**: `a/retry -> a` is one edge and one node identity; one run self-loop is one route and one visited stage. - **Repeated stage**: repeated visits remain separate ordered entries; visited stage identity is not duplicated; repeated identical routes collapse. - **Different outcomes**: success/approved/rejected routes to the same target remain distinct. - **Terminals**: bare `#` resolves by outcome, explicit terminals normalize, labels are `SUCCESS`/`FAILURE`, mid-run targets do not fabricate visits. - **Missing evidence**: null/absent/malformed steps and graphs yield empty evidence, no terminals and no fabricated visits. ## Honest limits - **No UI, layout or wiring.** This is deliberately the nonvisual foundation slice; the native graph screen, layout, highlighting and interaction are later work and are not claimed here. - **No browser evidence.** A nonvisual pure-Dart change has no rendered behavior to capture; no browser or screenshot check applies. - **No live server or device used.** All tests use local fixtures. No run, pipeline, schedule, workflow or service was created, changed or restarted. - **Mobile unverified.** Only web-targeted Flutter tests and analysis ran; no Android/iOS build, emulator, ADB or device. - **Committed, not deployed.** The reviewed slice is commit `2c10507` on `flutter/p2-model`; current `main` was merged in after review (final merge `f07ada0`, which includes `main` `e8bde4f`). No push, install, preview server or canonical-URL change was made by this landing stage; server-side checks and the actual land follow.