Files
pipelines/app/notes/P2a.md
T

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, 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.