6.7 KiB
6.7 KiB
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,isTerminalonly for the explicit keys, andresolveTarget: a bare#becomes#failurefor theerroroutcome and#successfor every other outcome. All other values are preserved verbatim, including""and unknown stage keys. A missing target staysnull, never a fabricated terminal. - Labels (
web/src/graph.js):nodeDisplayLabelgivesSuccess/Failurefor graph nodes;nodeLabelgives the TUI-mirroringSUCCESS/FAILURE. Stage keys are unchanged. - Definition edges (
web/src/graph.js): outcomes are success first, other outcomes alphabetical,errorlast; stages keep declaration order; ids are contiguous in that order; the label carrieserror*only whenfallback_erroris true. Anulledge value declares no edge and is skipped. Empty/unknown targets are kept, withknownTarget == false. - Definition nodes (
web/src/graph.jslayoutGraph): 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.jsrunGraphState): visited stages in first-appearance order without duplicates; routes keyedsource\0outcome\0resolvedTargetwithout duplicates; only a resolved terminal is visited by its target; a non-terminal target is not visited until a step lands there. Current stage iscurrent_stagewhen non-blank, else the last recorded step's stage, elsenull. A start timestamp is read only while executing, for arunningvisit of the current stage. - Visits (
web/src/runDetail.jsrunTimeline,clampVisitIndex,displayVisit, andweb/src/app.jsstage routing): visits are grouped by stage and ordered by recorded sequence with stable ties; the display visit is a positivecontrol.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 yieldsstep == 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/
nulldefinition 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 -> ais 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 areSUCCESS/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
2c10507onflutter/p2-model; currentmainwas merged in after review (final mergef07ada0, which includesmaine8bde4f). No push, install, preview server or canonical-URL change was made by this landing stage; server-side checks and the actual land follow.