Files
pipelines/app/notes/P2a.md
T

115 lines
6.7 KiB
Markdown

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