Files

8.5 KiB

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

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.