Skip to content

Commit f9c0e48

Browse files
jitokimoh-my-graph
andcommitted
docs: the summary line, before and after, verbatim
The CHANGELOG entry quotes both forms of the line — the zero case and the mixed corpus — so a reader sees exactly which bytes changed rather than a description of them, plus `show`'s and `watch`'s status lines on both sides. DESIGN.md is the spec, so it moves with the code: the coverage-line paragraph now names the in-flight clause, says why it is stated at zero (the same argument that already makes the skipped count unconditional), records that `show` and `watch` carry the same wording, and points the count at runstatus.InFlightCount over statuses those surfaces already derived — Derive stays the one place the ADR 0015 rule lives. Signed-off-by: jitokim <pigberger70@gmail.com> Co-Authored-By: oh-my-graph <graphs@oh-my-graph.dev>
1 parent fab8919 commit f9c0e48

2 files changed

Lines changed: 74 additions & 2 deletions

File tree

CHANGELOG.md

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,68 @@ oh-my-graph is **alpha software**. The graph YAML schema, the CLI, and the
1212

1313
### Changed
1414

15+
- **`runs list`, `show` and `watch` now state how many runs are IN FLIGHT,
16+
including when the answer is zero.** Asked how many graphs were running, an
17+
operator could only run `oh-my-graph runs list | grep -c RUNNING` and read
18+
`0` — an inference from ABSENCE, indistinguishable from a table that failed
19+
to render, a mis-filter, or broken status logic. The summary line counted
20+
what was HIDDEN and never counted what was ALIVE.
21+
22+
Before, on a run home with one settled run and nothing running:
23+
24+
```
25+
1 of 1 run(s) shown; 0 skipped.
26+
```
27+
28+
After, the same corpus:
29+
30+
```
31+
1 of 1 run(s) shown; 0 in flight; 0 skipped.
32+
```
33+
34+
With two live runs, one abandoned one and one directory this build cannot
35+
read, before:
36+
37+
```
38+
3 of 4 run(s) shown; 1 skipped (1 written by an incompatible snapshot schema) — pass --show-skipped to name them.
39+
```
40+
41+
After:
42+
43+
```
44+
3 of 4 run(s) shown; 2 in flight, 1 abandoned; 1 skipped (1 written by an incompatible snapshot schema) — pass --show-skipped to name them.
45+
```
46+
47+
It is the SAME line, not a second one: one line is one read, while a second
48+
line can be scrolled past, cropped by a pager, or emitted only
49+
conditionally — the exact failure mode this change exists to kill. An
50+
abandoned run is named in the same sentence when there is one, and is never
51+
added into the in-flight number: a reader asking "is anything running" is
52+
answered wrongly by a count that folds in dead runs, and badly served by
53+
silence about a run whose process died holding a lock.
54+
55+
The two single-run surfaces say the same sentence, so an operator learns one
56+
wording rather than three. `show`, before and after:
57+
58+
```
59+
Run run-done — PASS, 1 node(s)
60+
Run run-done — PASS, 1 node(s); 0 in flight.
61+
```
62+
63+
`watch`, before and after:
64+
65+
```
66+
run run-done is PASS
67+
run run-done is PASS; 0 in flight.
68+
```
69+
70+
The count is `runstatus.InFlightCount` over statuses the surfaces already
71+
derived, so nothing re-decides what in-flight means (ADR 0015 §4's open leg
72+
AND held lock stays the one rule, in `runstatus.Derive`). The machine-readable
73+
surfaces are unchanged: `/api/cards`, `/api/graph` and `events.jsonl` keep
74+
their shapes and gain no prose — a consumer counts live runs itself from the
75+
state token, as the dashboard's own page already does.
76+
1577
- **An unresolvable `{{ inputs.x }}` or `{{ artifacts.id }}` now says that a
1678
merely-quoted placeholder is resolved too, and how to quote one.** The two
1779
reasons were written as if the graph had meant the token — the artifact one

DESIGN.md

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1792,11 +1792,21 @@ oh-my-graph resume <run-id> (--approve <gate-id> | --reject <gate-id> | --retry-
17921792
`VERDICT`, which would have kept the very conflation the enumeration
17931793
removes) and, under its total, one line saying how much of the run home the
17941794
table covers: how many runs are shown out of how many directories were found,
1795-
how many were skipped and under which reason. It is printed whether or not
1795+
**how many of them are in flight**, and how many were skipped and under which
1796+
reason (`3 of 4 run(s) shown; 2 in flight, 1 abandoned; 1 skipped (…)`). It is
1797+
printed whether or not
17961798
anything was skipped, because a reader must be able to tell "nothing was
17971799
hidden from me" apart from "64 of 325 runs are shown" — a summary that
17981800
appeared only when there was something to report renders those two cases
1799-
identically. `--show-skipped` names each skipped directory and quotes the
1801+
identically. The in-flight clause is there for the same reason and is stated
1802+
AT ZERO: "no run is running" and "the status column is broken" are what an
1803+
empty `RUNNING` column renders identically, and only the first is the
1804+
conclusion an operator draws from it. `show` and `watch` append the same
1805+
clause to their own status lines (`run run-x is PASS; 0 in flight.`) so one
1806+
wording answers the question on every surface. The count is
1807+
`runstatus.InFlightCount` over statuses those surfaces already derived —
1808+
`Derive` remains the only place the open-leg-AND-held-lock rule lives, and no
1809+
surface re-decides it. `--show-skipped` names each skipped directory and quotes the
18001810
reader's own reason, one line each on stderr; that per-run detail used to be
18011811
unconditional and was four fifths of the command's output on a long-lived run
18021812
home. That per-run sentence is `runstatus.Unreadable` and is the ONE wording

0 commit comments

Comments
 (0)