Files
pipelines/app/notes/P2-run-graph.md
T

147 lines
8.5 KiB
Markdown

# P2-run-graph — executed vs unexecuted run evidence
## Scope
App-only, new files. No existing source, `main.dart`, shell, pubspec, server, web
client, platform directory or other feature lane was edited. The slice renders a
run definition with recorded execution evidence and reports a visited stage key
to its caller; it does not open the visit pane itself and is not wired into the
run tab (that integration belongs to the runs lane).
| File | Lines | Responsibility |
| --- | --- | --- |
| `lib/features/graph/widgets/run_graph_view.dart` | 331 | bounded widget, geometry, recorded evidence, legend/elapsed header |
| `lib/features/graph/widgets/run_graph_canvas.dart` | 367 | split edge layer/painter, canvas composition, native node wrapper, measurement |
| `test/features/graph/widgets/run_graph_view_test.dart` | 460 | evidence, route classes, terminal truth, click/semantics, empty state, order, 320/2x, dark Cupertino, status remeasure |
| `test/features/graph/widgets/run_graph_edge_layer_test.dart` | 147 | solid/arrowed taken strokes, dashed untaken strokes, passive hit test, repaint |
| `tool/run_graph_probe.dart` | 200 | isolated browser fixture (not app/shell registration) |
| `tool/run_graph_probe.mjs` | 265 | real-Chrome assertions and captures |
Both source files are cohesive units and slightly over the 250-line aim because
the view owns evidence/geometry while the helper owns painting/measurement and
the native node wrapper. Splitting further would either duplicate measurement or
create arbitrary fragments.
## Public API
```dart
RunGraphView(
graph: JsonMap?, // omitted run graph -> exact missing wording
run: JsonMap, // recorded steps are the only evidence
onStageSelected: ValueChanged<String>,
selectedStage: String?, // caller-owned graph selection
now: DateTime Function()?, // deterministic elapsed tests
)
```
`runGraphMissing` is the exact web sentence: `This server did not include the
run graph.` `runGraphExecuted` / `runGraphNotExecuted` are `Executed` and
`Not executed`.
## Behavior
- **Visited stages only:** `RunGraphState` decides visits and routes. A visited
stage's native node receives its latest recorded step status (sequence order,
via `visitsByStage`). An unvisited stage gets no status, no tap target and no
button semantics; it is a plain graph label. No visit, session, status or
elapsed value is fabricated.
- **Terminals:** only `RunGraphState.visitedStages` terminals (a recorded route
resolved there) show evidence, using the recorded route outcome
(`success`/`error`). An untaken terminal stays plain. Terminals own no recorded
step, so they are never presented as an openable visit.
- **Routes:** taken definition routes are solid and arrowed using the landed
`GraphEdgePainter` geometry; untaken routes are dashed, arrowless and use the
host's outline/separator role. Only taken routes get outcome labels, as in the
web run tab. Untaken routes keep their definition order and identifiers.
- **Order:** routing preserves `graphEdges` order, so a stage's outcomes are
success first, other alphabetical, error last. The run filter does not reorder
them.
- **Legend:** a native `Wrap` of two stock-icon entries, `Executed` and
`Not executed`, labelled `Route kinds` for assistive technology. No bespoke
palette or swatch painting.
- **Elapsed:** a static `Current stage <key> · elapsed <duration>` line appears
only while `RunGraphState.activeStage` exists (run executing). It is computed
once per build from `currentStageStartedAt`; there is no timer, pulse or
invented progress. With no parseable start it says only `Current stage <key>`.
- **Node styling:** Material uses the landed `Card`/`Card.filled` node and
Cupertino its tinted/filled buttons; the recorded-status line is the execution
affordance. Status changes drop only that node's stale measured extent, and the
measurement key includes the status so even a same-size status change reports
a fresh extent; a taller node is never placed in the old box.
- **Viewport:** the caller must supply bounded constraints; the view fills them
with stock `InteractiveViewer` pan/zoom (`minScale: 0.3`, `maxScale: 3`).
Node and label extents are measured from the exact widgets placed. At 320px
and 2x text the graph pans instead of shrinking or clipping content.
- **Empty:** null/absent graph or a graph with no stages shows the exact
`This server did not include the run graph.` sentence and no viewer.
## Checks actually run
```
dart format lib/features/graph/widgets test/features/graph/widgets tool/run_graph_probe.dart
flutter test test/features/graph/widgets/run_graph_view_test.dart \
test/features/graph/widgets/run_graph_edge_layer_test.dart # 13 passed
flutter test test/features/graph # 153 passed
flutter test # 844 passed
flutter analyze # No issues found!
flutter build web # ✓ Built build/web
flutter build web -t tool/run_graph_probe.dart -o build/run_graph_probe
```
The full-app `flutter analyze`, `flutter test` and `flutter build web` also pass;
integrated run-tab registration was not performed because the shell/runs wiring
belongs to another lane.
## Rendered evidence
Fresh real Chrome (headless, throwaway profile, loopback server on an
OS-assigned port). The fixture records a running `plan -> build` path and a
finished `plan -> build -> audit -> Success` path. Captures are in shared
`public/run-graph-captures/`:
| File | Shows |
| --- | --- |
| `run-graph-material-light-1x-running-initial.png` | visited plan/build with `completed`/`running`, solid arrowed taken route, dashed untaken routes, legend, live elapsed line |
| `run-graph-material-light-1x-running-final.png` | plan selected after a real node click; selection reported by key |
| `run-graph-material-light-1x-running-phone.png` | 320px material viewport |
| `run-graph-material-light-1x-finished-initial.png` | finished run: executed path through `Success success`, no live line, untaken failure route dashed |
| `run-graph-material-light-1x-finished-final.png` / `-phone.png` | final/phone variants after pan and terminal safety check |
| `run-graph-cupertino-dark-2x-running-initial.png` | dark Cupertino host at 320px/2x, wrapped native legend, visited statuses |
| `run-graph-cupertino-dark-2x-running-final.png` | real pan exposes the running build node |
| `run-graph-cupertino-dark-2x-finished-initial.png` / `-final.png` | dark Cupertino finished path and terminal evidence |
The probe asserts legend wording, visible recorded statuses, the live line only
for the running fixture, click-by-key selection, unvisited `audit` leaving
selection unchanged, a finished terminal click not creating a visit, and real
drag panning at 320/2x. Earlier `*-desktop.png` captures from the first probe
run were removed as superseded by the `initial`/`final` set.
## Honest limits
- **Not wired.** No run-tab, shell or application edit; the caller must supply
the graph/run maps and open the reported stage's latest recorded visit.
- **Terminal clicks do nothing.** Terminals have no recorded step, so the view
refuses to invent a visit for them; they remain evidence-only.
- **No live ticking.** The elapsed line is intentionally static per build; a
live ticking badge/timer remains for the integrating lane.
- **No browser keyboard/fit toolbar.** Standard node focus semantics come from
the native controls, but a fit/expand toolbar was not added (not in this
slice).
- **Mobile unverified.** Only Chrome/Flutter web was built and driven. Android
and iOS were not built, installed or tested.
- **Not committed.** The stage instruction forbids commit/push/deploy, so the
candidate remains uncommitted working-tree files; no main merge or push. The
task input's "commit the candidate" is superseded by the stage policy.
## Manager completion after an infrastructure failure
The run ended with the server's `UNIQUE constraint failed:
step_file_changes.run_id, step_file_changes.sequence (1555)` persistence bug, not
an app fault; the parallel search slice failed the same way. The retained work is
complete: the manager ran the graph widget suite (43 tests pass) and inspected the
run-mode canvas, then merged it. No retry of this slice was started. The server
defect is tracked in WORK.md and fixed separately with a regression.
This slice is the run-mode COMPONENT only: it is not yet the run detail's Graph
tab and does not open visit panes. Those remain wiring work.