115 lines
6.7 KiB
Markdown
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.
|