diff --git a/BUILDER.md b/BUILDER.md index 44d3316..bdb7780 100644 --- a/BUILDER.md +++ b/BUILDER.md @@ -252,14 +252,47 @@ CONTRIBUTING; the shared flow lives here and is not restated there.) explicitly and names the evidence (e.g. "the same job fails identically on `origin/main` at ``"). Silence about a red check is what is prohibited; an argued exception shifts the burden to the author. - *Green* is a ruled term (operator, 2026-07-27), and it is read from - each check's **`conclusion`**, never its `status`: a check carrying a - terminal conclusion is green or not-green by that conclusion whatever - its `status` field still reports — the two can disagree, and on #259 a - finished job's `status` lagged its own `conclusion: success` at the - head. A check with no conclusion at all is neither class: a configured - run still in progress is not green, and waiting for it is compliance, - not a stall. A **cancelled or stale** check is not a green head — + *Green* is a ruled term (operator, 2026-07-27), and it is read in two + steps, because a head carries more rollup entries than it has checks: + first pick the entry that is a check's word at this head, then + classify that entry. **A check's word at a head is its newest entry + by start time, and a `CANCELLED` entry is not that word while the + same check carries a non-cancelled entry at the same head.** The + survivor is the verdict about these bytes; the entry it displaced + reported nothing about them. That shape is routine rather than + exotic: a job in a `cancel-in-progress` concurrency group displaces + *itself* whenever two events land inside one of its runs, so one job + appears twice on one sha — #275's head at `806e99e1` carried + `labels / scope` `CANCELLED` started at 23:45:19Z beside + `labels / scope` `SUCCESS` started at 23:45:31Z, and that head is + green, with no argued exception owed. Say **start** time and mean it: + a cancelled run does not stop the moment its replacement begins, so + the dead run's completion routinely postdates the live run's start, + and a reader who dates entries by completion picks the corpse. When + *every* entry a check has at the head is cancelled, nothing survives + to be its word: that check has not reported at all, and it stays + not-green by the classes below — the all-cancelled context is the + case this leaves exactly where it was. Nor is any of this a new + class. The 2026-07-27 gloss that what survives at a head is same-head + cancellation was written against supersession by a newer push, not + against a job displacing itself inside its own concurrency group, and + `checks_state`'s #139 carve-out has read it that way in the machine's + voice ever since — cancelled entries dropped only where the context + keeps a non-cancelled survivor, an all-cancelled context left intact + and still blocking — so doctrine and gate partition alike on a mixed + context. What the *machine* drops from the rollup before it grades + anything is a different question, and crew's to describe rather than + this file's. + Then classify that entry, and classify it from its **`conclusion`**, + never its `status`: a check carrying a terminal conclusion is green or + not-green by that conclusion whatever its `status` field still + reports — the two can disagree, and on #259 a finished job's `status` + lagged its own `conclusion: success` at the head. A check with no + conclusion at all is neither class: a configured run still in progress + is not green, and waiting for it is compliance, not a stall. Picking + the newest entry never settles a live one: where the survivor is the + run still going, the head is not green and you wait on it exactly as + you would have. A **cancelled or stale** check is not a green head — *stale* means a check belonging to a superseded head, which the head-scoped rollup does not show anyway, so what survives there is same-head cancellation, never a same-head node whose `status` lags its diff --git a/changelog.d/276.md b/changelog.d/276.md new file mode 100644 index 0000000..7d2dcdc --- /dev/null +++ b/changelog.d/276.md @@ -0,0 +1,10 @@ +### Changed + +- BUILDER.md's green ruled term now says which entry to read before it says + what an entry means: a check's word at a head is its newest entry by start + time, and a cancelled entry is not that word while the same check carries a + non-cancelled one at that head (#276). +- A check whose every entry at the head is cancelled is unchanged — nothing + survived to be its word, so it never reported and is not green — and the + collapse mirrors `checks_state`'s carve-out rather than adding a class + (#276).