docs(devx): measure-durability-swallow-family's usage header names its seven control families and the six gated runs (#15754)

[claude]

Fixes #15754

Comments only in scripts/measure-durability-swallow-family.mjs. No behaviour
change: the non-comment diff is empty, proved below.

The reading, MEASURED on the branch base

The header claimed the instrument has four control families and that
--self-test=gated runs three. Measured at base 66e68adc6, it declares
seven and gated asserts six.

Seven declarations, each with the line that introduces it:

scripts/measure-durability-swallow-family.mjs:367   const POSITIVE_CONTROLS = [
scripts/measure-durability-swallow-family.mjs:432   const NEGATIVE_CONTROLS = [
scripts/measure-durability-swallow-family.mjs:458   const REGRESSION_CONTROLS = [
scripts/measure-durability-swallow-family.mjs:510   const RESOLUTION_CONTROLS = [
scripts/measure-durability-swallow-family.mjs:640   const WORKLIST_READING_CONTROLS = [
scripts/measure-durability-swallow-family.mjs:759   const DETERMINED = new Map([

and the two cross-checks, which are families of the self-test rather than tables
of controls, marked as such by the self-test body's own section rules:

scripts/measure-durability-swallow-family.mjs:1964    // ── The DETERMINED register (#13886), asserted in BOTH modes ─────
scripts/measure-durability-swallow-family.mjs:2025    // ── The COPIED gate vocabulary (#15459), asserted in BOTH modes ──
scripts/measure-durability-swallow-family.mjs:2063    // ── What the WORKLIST PRINTS (#15503), asserted in BOTH modes ────

gated drops exactly one of the seven, and the drop is a single expression:

scripts/measure-durability-swallow-family.mjs:1922    for (const control of gated ? [] : POSITIVE_CONTROLS) {

That it is the ONLY drop is not an impression: every occurrence of the
identifier gated in the file is at :11, :22, :26 (prose), :965,
:973, :984, :991, :1006 (prose), :1011 (SELF_TEST_MODES), :1914
(the assignment const gated = mode === 'gated'), :1922 (the drop above),
:1966, :2027, :2068 (prose), and :2098, :2102, :2105 (the verdict
lines). The four remaining control loops -- REGRESSION_CONTROLS:1938,
NEGATIVE_CONTROLS:1944, RESOLUTION_CONTROLS:1950,
WORKLIST_READING_CONTROLS:2081 -- and the two cross-check sections carry no
gated guard at all.

The verdict line the gated mode prints (:2102-2117) names six and says why the
seventh is absent -- and unlike the card, this is a RUN, not a source reading:

✓ measure-durability-swallow-family self-test, gated families (#13919): 3 negative control(s) yield none,
2 regression control(s) stay clear, 6 resolution control(s) resolve as declared, 3 DETERMINED register
row(s) cross-check clean, 20 copied gate-vocabulary name(s) match the gate's own declaration, 3 worklist
reading(s) print as declared over a fixture population, 56 member site(s) total
   4 positive control(s) are NOT asserted here, permanently: they pin members of the #12981 worklist, which
   that programme exists to remove — a control the repair is designed to destroy cannot hold a CI gate.

The bare mode's verdict names all seven (4 positive, 3 negative, 2 regression, 6 resolution, 3 DETERMINED, 20 copied gate-vocabulary, 3 worklist reading).

PR #15756 was verified, not copied. It carries the same "seven declared /
six in gated" reading into lint.yml for #15569, but it is still OPEN at the
time of writing, so this branch's base still has lint.yml:4134 saying "declares
four control families" and :4146 saying "runs RESOLUTION + NEGATIVE +
REGRESSION". That file is #15569's scope and is untouched here; the reading above
is derived from this instrument's own declarations and from running it.

Before / after

Before (:10-12):

//   node scripts/measure-durability-swallow-family.mjs --self-test # all 4 control families
//   node scripts/measure-durability-swallow-family.mjs --self-test=gated
//                                                      # the 3 families CI runs

After (:10-32):

//   node scripts/measure-durability-swallow-family.mjs --self-test # every control family
//   node scripts/measure-durability-swallow-family.mjs --self-test=gated
//                                                      # every family but POSITIVE_CONTROLS
//
// THE CONTROL FAMILIES, NAMED rather than counted, so that the next one added
// contradicts a LIST and not an integer -- which is exactly how the two bare integers
// that stood here before went stale, unread, as further families landed:
// `POSITIVE_CONTROLS`, `NEGATIVE_CONTROLS`, `REGRESSION_CONTROLS`, `RESOLUTION_CONTROLS`,
// the `DETERMINED` register cross-check (#13886), the copied gate-vocabulary cross-check
// (#15459), and `WORKLIST_READING_CONTROLS` (#15503).
//
// `--self-test=gated` asserts every one of them EXCEPT `POSITIVE_CONTROLS`, and that
// asymmetry is the point of the split rather than a convenience: the single expression
// `gated ? [] : POSITIVE_CONTROLS` is the ONLY thing either mode drops, and it drops
// those controls because they pin MEMBERS of the #12981 worklist that the repair
// programme exists to REMOVE -- a control a successful repair destroys cannot hold a
// CI gate.
//
// ⛔ THIS PARAGRAPH IS NOT THE AUTHORITY: `SELF_TEST_MODES` is (with the next block,
// for what CI runs and why), together with the verdict line each mode prints, which
// NAMES the families it just asserted. A reader who finds either of them disagreeing
// with this list should trust them and repair this list.

The card left one question open -- whether the header should point at
SELF_TEST_MODES and carry no list at all. It does BOTH: it names the families
(so a reader choosing a mode gets the answer where they look for it) and it
demotes itself explicitly, naming SELF_TEST_MODES and the verdict lines as the
authority. The gated-vs-bare asymmetry argument is kept in substance rather than
deleted: POSITIVE_CONTROLS pin members the repair programme exists to remove.

The stale integers are NOT quoted verbatim in the replacement. Leaving the
strings all 4 control families / the 3 families CI runs in the file, even
inside a historical aside, would leave the next re-measure's grep hitting live
text; the lesson is kept, the grep-bait is not.

The other three stale counts of the same list

Grepped for four, 4 control, three, 3 famil and the rest across the
file's comments. Three more hits were the same defect, and all three are fixed
here by naming rather than recounting:

line (base)	was	now
:487	The other three families all read MEMBERSHIP	The other membership-reading families -- POSITIVE, NEGATIVE, REGRESSION -- all read MEMBERSHIP
:946	All four families were green only while somebody remembered to run them by hand	The families that existed then (POSITIVE, NEGATIVE, REGRESSION, RESOLUTION) were green only while somebody remembered to run them by hand
:965	So `gated` is the families the repair programme CANNOT destroy — three at #13919, joined by the `DETERMINED` register at #13886 (last section)	... — NEGATIVE, REGRESSION and RESOLUTION at #13919, joined by the `DETERMINED` register (#13886, last sections), the copied gate vocabulary (#15459) and the worklist readings (#15503, whose case is made at `WORKLIST_READING_CONTROLS`)

:946 is dated rather than recounted on purpose: four families really were all
there was when #13919 was filed, so the fix is to say when, not to bump a
number that would go stale again.

Two hits were examined and deliberately left alone, because neither is stale:

• :982 ## The FIFTH family (#13886) is in BOTH modes -- an ordinal at the
  point of introduction, and DETERMINED is still the fifth family declared.
• :2074 const WORKLIST_READING_CONTROL_COUNT = 3 -- code, not a comment, and
  it pins the number of worklist READINGS, a different list from the families.

Verification

Exit codes captured by redirecting first (cmd > log 2>&1; EXIT=$?), never read
through a pipe.

check	exit	reading
non-comment diff vs origin/main	—	0 lines: git diff -U0 origin/main -- scripts/measure-durability-swallow-family.mjs filtered to non-comment +/- lines prints nothing
node --check scripts/measure-durability-swallow-family.mjs	0	parses
node scripts/measure-durability-swallow-family.mjs --self-test=gated	0	verdict line quoted above, naming six families
node scripts/measure-durability-swallow-family.mjs --self-test	0	verdict line naming all seven
pnpm check:swallow-census-controls	0	the gated self-test as CI spells it
pnpm check:nul-bytes	0	clean
node scripts/pm/check-governed-merges.mjs --test scripts/measure-durability-swallow-family.mjs	0	✅ NOT governed — ordinary queue landing applies
node scripts/pm/dispatch-gates.mjs --changed --commands --repo objectstack-ai/objectstack	0	29 commands derived from the committed change set; all run, results below

How the self-test was made runnable. A fresh worktree has no pnpm install,
and this instrument's only external import is typescript (:259; its sibling
./ts-parse.mjs imports nothing external). Rather than report the run as NOT
MEASURED, typescript@6.0.3 was copied into the worktree's node_modules and
both modes were then run for real. Nothing else was installed, and the copy is
outside the diff.

Derived gate family: 29 commands, all run

25 exited 0. The four non-zero exits are all NOT MEASURED -- each died before
running a single check, on a dependency a fresh worktree does not have:

command	exit	why it is not a red
node scripts/check-ci-filter-parity.mjs	3	PREREQUISITE NOT MET — the dependency \yaml` is not installed`
node scripts/check-closing-keyword-parity.mjs	3	same, yaml
node scripts/check-closing-keyword-parity.mjs --self-test	3	same, yaml
node scripts/check-comment-mask-corpus.mjs	1	ERR_MODULE_NOT_FOUND: Cannot find package '@typescript-eslint/parser'

Each of those gates prints "Nothing was measured: this gate exited before running
a single check" itself. CI installs and runs all four.

Changeset

skip-changeset. AGENTS.md, Post-Task Checklist item 3: the label "is for a diff
that publishes nothing from any released package." This diff is one repo-root
tooling script -- scripts/measure-durability-swallow-family.mjs, a measure-*
instrument deliberately outside the check:*/gen:* ledger -- and no published
package contains it.

🤖 Generated with Claude Code

https://claude.ai/code/session_012zGPuVVX3deAx9LdjK8jCk

---

Generated by Claude Code

[claude]

ACCEPT — PR #15764 (head 6ff38c132, scripts/measure-durability-swallow-family.mjs +31/−9) reviewed against the GitHub three-dot diff, not the report.

Comments only: the non-comment diff is 0 lines (re-run by this seat: empty). The usage header now names the seven families and says --self-test=gated asserts every one except POSITIVE_CONTROLS, with the single dropping expression cited and the gated-vs-bare asymmetry kept in substance; it explicitly demotes itself to SELF_TEST_MODES and each mode's verdict line as the authority — the card's open question answered both ways. Three further stale counts (:487, :946, :965) fixed the same way; two count-shaped hits correctly left alone (## The FIFTH family is an ordinal at introduction; WORKLIST_READING_CONTROL_COUNT = 3 is code pinning readings, not families). Verified, not copied: the dev measured seven/six by RUNNING both modes (typescript copied into the worktree's node_modules, outside the diff) — the gated verdict names six, the bare one seven.

Measured by this seat: git merge-tree --write-tree origin/main <branch> → EXIT=0; non-comment diff empty; governed test per the report NOT governed. NOT MEASURED here: the yaml / @typescript-eslint/parser gates by name and the two self-test modes (no typescript in this checkout; the dev's run is the record).

The unfiled finding (SELF_TEST_MODES argues the 5th and 6th families into gated but never the 7th) is filed by this seat — see the card note.

Flip + arm when both required jobs report success on 6ff38c132.

---

Generated by Claude Code

[claude]

Flipped ready + auto-merge enabled (07:09Z, method: MERGE). Required jobs on 6ff38c132: Lint & Repo Gates = success, TypeScript Type Check = success; git merge-tree --write-tree origin/main <branch> → EXIT=0 against the current main. Watched; on landing #15754 closes.

---

Generated by Claude Code