fix(spec): refuse an unrecognized liveness status, and make the fold preserve the walk's total (#13183)

A ledger `status` was free text. `classify()` accepted any truthy string and
counted it; `foldStateCounts` then read four names and nothing else, so a row
written `"status": "planed"` was classified, counted, and dropped — and
`state-counts.md` published a `classified` total short by exactly that
population while the gate stayed green, because the artifact computes that
column as the sum of the four columns beside it and the freshness leg compares
it against a re-render of the same understated fold.

Disposition 1 — the data-side half of the #13041 partition. `KNOWN_STATUSES` is
read from `STATUS_COLUMNS`, never restated, so the guard and the fold that drops
the value cannot disagree about the four names. An unrecognized value is still
COUNTED, deliberately: dropping it would keep `classified` and the `byStatus`
buckets in agreement and hide the row from the arithmetic below.

Disposition 2 — `reconcileStateCountTotals` binds the artifact's total to
`cat.classified`, which the walk counts with its own `++` and never through
`byStatus`. That is the one comparison here whose two sides are not the same
measurement twice. Not an "other" column: that would change what the artifact
publishes, and the defect is that the gate cannot SEE a dropped status. The
generator refuses to write rather than publish an understated total.

Population measured across all 31 ledgers on this commit: live 819, planned 10,
dead 80, experimental 5 — 914 classified, no fifth value. Both guards start
green and only a new typo can red them.


Claude-Session: https://claude.ai/code/session_01LpRNHxWZgSUgVnFT9mQQo4

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-trump

packages/spec/scripts/liveness/build-state-counts.mts

@@ -61,8 +61,10 @@ import { fileURLToPath } from 'node:url';
 import {
   STATE_COUNTS_FILE,
   STATE_COUNTS_PATH,
+  STATE_COUNTS_TOTALS_GUIDANCE,
   foldStateCounts,
   parseStateTable,
+  reconcileStateCountTotals,
   renderStateCounts,
 } from './readme-table.mts';
 
@@ -85,7 +87,10 @@ const run = spawnSync(process.execPath, [tsxCli, gate, '--json'], {
 
 // A crash is fatal; a red verdict is not. See the header — the gate is red
 // precisely when this artifact needs rewriting.
-let report: { types?: Record<string, { byStatus?: Record<string, number> }>; readmeMissingRows?: string[] };
+let report: {
+  types?: Record<string, { byStatus?: Record<string, number>; classified?: number }>;
+  readmeMissingRows?: string[];
+};
 try {
   report = JSON.parse(run.stdout || '');
 } catch {
@@ -104,6 +109,28 @@ const rows = foldStateCounts(Object.keys(types), Object.fromEntries(
   Object.entries(types).map(([t, v]) => [t, v.byStatus ?? {}]),
 ));
 
+// ── refuse to publish a total the fold under-counted (#13083) ──
+// The header's rule is that a RED gate is not fatal here — the gate is red
+// precisely when this artifact needs rewriting. This failure is the exception,
+// and it is the same exception the unparseable report above already carves out:
+// there is nothing to rewrite. The fold that produced `rows` reads four status
+// names and drops everything else, so writing now would publish an understated
+// `classified` — and the gate's freshness leg would then compare those bytes
+// against a re-render of the SAME understated fold and call it current. A stale
+// artifact is the safer state; a fresh wrong one is unfalsifiable.
+const totalErrors = reconcileStateCountTotals({
+  governed: Object.keys(types),
+  byStatus: Object.fromEntries(Object.entries(types).map(([t, v]) => [t, v.byStatus ?? {}])),
+  classified: Object.fromEntries(Object.entries(types).map(([t, v]) => [t, v.classified])),
+});
+if (totalErrors.length) {
+  console.error(`✗ refusing to write ${STATE_COUNTS_FILE} — the fold does not preserve the walk's total:\n`);
+  totalErrors.forEach((s) => console.error(`    ${s}`));
+  console.error('');
+  STATE_COUNTS_TOTALS_GUIDANCE.forEach((line) => console.error(line ? `   ${line}` : ''));
+  process.exit(1);
+}
+
 const rendered = renderStateCounts(rows);
 writeFileSync(join(ledgerRoot, STATE_COUNTS_FILE), rendered);
 

packages/spec/scripts/liveness/check-liveness.mts

@@ -186,10 +186,12 @@ import {
   STATE_COUNTS_FILE,
   STATE_COUNTS_GUIDANCE,
   STATE_COUNTS_PATH,
+  STATE_COUNTS_TOTALS_GUIDANCE,
   STATUS_COLUMNS,
   foldStateCounts,
   parseStateTable,
   reconcileReadmeTable,
+  reconcileStateCountTotals,
   reconcileStateCounts,
   renderStateCounts,
 } from './readme-table.mts';
@@ -393,6 +395,36 @@ for (const s of STATUS_COLUMNS) {
   }
 }
 
+// ── THE SAME PARTITION, ASKED OF THE DATA (#13083) ──
+//
+// The loop above holds the CODE to the published vocabulary. Nothing held the
+// LEDGERS to it. `classify()` accepts any truthy string and counts it, so a row
+// written `"status": "planed"` is classified (the forward pass is satisfied, no
+// UNCLASSIFIED finding), counted into a `byStatus` bucket named after the typo,
+// and then dropped by `foldStateCounts` — which reads four names and nothing
+// else. The artifact publishes a `classified` total short by exactly the typo'd
+// population, and every reconciliation in this gate compares that number against
+// itself, so it stays green.
+//
+// After #13041 the same unvalidated string carries a second consequence: a
+// status in neither evidence-scan set has its `evidence` pointer counted by the
+// census and read by no check. A typo lands in neither set BY CONSTRUCTION,
+// which is the defect that loop exists to prevent — reachable through the data
+// instead of through the code.
+//
+// So the vocabulary is read from `STATUS_COLUMNS` rather than written out again:
+// the guard and the fold that drops the value must not be able to disagree about
+// what the four names are. That is the same reason `EVIDENCE_SCANNED_LABEL`
+// below is derived from its set rather than restated.
+//
+// Population measured before switching this on, across all 31 ledgers on this
+// commit: live 819, planned 10, dead 80, experimental 5 — 914 classified, no
+// fifth value. So it starts GREEN and only a NEW typo can red it, which is the
+// zero-census argument the orphan-proof and key-mention flips were switched on
+// under. A check that starts at zero can be red; that is why the census came
+// first.
+const KNOWN_STATUSES = new Set<string>(STATUS_COLUMNS);
+
 /**
  * The scanned population, rendered for the gate's own output. Derived from the
  * set rather than written out again, so the numbers and the population they
@@ -523,6 +555,8 @@ const report: any = {
   countsArtifactErrors: [] as string[], // state-counts.md is missing, or its bytes are not what the gate measures (#7377)
   countsRowSetErrors: [] as string[], // the README's row set and the artifact's disagree
   countsHandEdited: [] as string[], // a count column is back in the README — a hand-maintained number in the merge path
+  countsTotalErrors: [] as string[], // the four columns and the walk's own `classified` disagree — the fold dropped a status (#13083)
+  unknownStatus: [] as string[], // a ledger `status` outside STATUS_COLUMNS — counted by the walk, dropped by the fold (#13083)
   verification: null as VerificationReport | null, // `verifiedAt` ages — the re-verification worklist
   producers: null as ProducerReport | null, // `producer` / `evidenceScope` — the #4837 / #4895 worklists
   producerMissing: [] as string[], // a `producer` pointer into thin air — FAILS, like a rotted `evidence`
@@ -635,6 +669,13 @@ function classify(type: string, path: string, status: string, led: any, cat: any
   cat.classified++;
   cat.byStatus[status] = (cat.byStatus[status] || 0) + 1;
   report.totals.byStatus[status] = (report.totals.byStatus[status] || 0) + 1;
+  // #13083 — an unrecognized value is still COUNTED here, deliberately. Dropping
+  // it would keep `cat.classified` and the `byStatus` buckets in agreement and
+  // hide the row from the totals reconciliation downstream, which is the very
+  // silence this names. It is counted, and it is reported.
+  if (!KNOWN_STATUSES.has(status)) {
+    report.unknownStatus.push(`${type}/${path} → "${status}"`);
+  }
   // Framework-auto entries (`led === null`) have no ledger row to date-stamp.
   if (led !== null) {
     verificationEntries.push({ key: `${type}/${path}`, status, verifiedAt: led?.verifiedAt });
@@ -897,6 +938,19 @@ if (!existsSync(readmeFile)) {
   report.countsHandEdited = counts.handCountErrors;
 }
 
+// ── the fold's arithmetic (#13083) ──
+// Outside the README block above on purpose: the three legs there all read the
+// README or the artifact, and every one of them is satisfied by a fold that
+// silently dropped a status. This one reads the WALK — `types.<type>.classified`,
+// counted by its own `++` and never through `byStatus` — so it is the only
+// comparison here whose two sides are not the same measurement twice. It must
+// therefore run even when the README is gone, which is why it is not nested.
+report.countsTotalErrors = reconcileStateCountTotals({
+  governed: GOVERNED,
+  byStatus: Object.fromEntries(Object.entries<any>(report.types).map(([t, v]) => [t, v.byStatus])),
+  classified: Object.fromEntries(Object.entries<any>(report.types).map(([t, v]) => [t, v.classified])),
+});
+
 // ── verifiedAt: how old is each claim? ──
 // Age never fails the gate — re-verification is a worklist, not a merge gate.
 // A MALFORMED value does fail: it silently disables the staleness check for
@@ -981,7 +1035,14 @@ const failed =
   report.readmeMalformedRows.length > 0 ||
   report.countsArtifactErrors.length > 0 ||
   report.countsRowSetErrors.length > 0 ||
-  report.countsHandEdited.length > 0;
+  report.countsHandEdited.length > 0 ||
+  // A ledger `status` outside the published vocabulary, and the arithmetic that
+  // proves the artifact under-counted because of it (#13083). Red rather than ⚠
+  // on the zero-census argument stated at KNOWN_STATUSES: measured across all 31
+  // ledgers on the commit that switched this on, every value was one of the
+  // four, so the gate starts green and only a NEW typo can red it.
+  report.unknownStatus.length > 0 ||
+  report.countsTotalErrors.length > 0;
 if (asJson) {
   process.stdout.write(JSON.stringify(report, null, 2) + '\n');
 } else {
@@ -1169,6 +1230,29 @@ if (asJson) {
     console.log(`\n✗ ${totalUnclassified} UNCLASSIFIED — classify in packages/spec/liveness/<type>.json:`);
     report.unclassified.forEach((s: string) => console.log(`    ${s}`));
   }
+  if (report.unknownStatus.length) {
+    console.log(
+      `\n✗ ${report.unknownStatus.length} ledger row(s) whose \`status\` is not one of ` +
+      `${STATUS_COLUMNS.join(' / ')}:`,
+    );
+    report.unknownStatus.forEach((s: string) => console.log(`    ${s}`));
+    console.log(
+      '\n   This is the shape UNCLASSIFIED above cannot catch, and it is worse than\n' +
+      '   UNCLASSIFIED because it looks DONE: the row has a verdict, the forward pass is\n' +
+      `   satisfied, the walk counts it — and then ${STATE_COUNTS_FILE} drops it, because\n` +
+      `   the fold reads ${STATUS_COLUMNS.join(' / ')} and nothing else. The published\n` +
+      '   total comes out short by exactly these rows, and every other check in this gate\n' +
+      '   compares that total against itself and agrees (#13083).\n\n' +
+      '   Since #13041 the same value costs a second check: the evidence scan reads a\n' +
+      '   declared population, and a status in neither the scanned nor the unscanned set\n' +
+      "   has its `evidence` pointer counted by the census and READ BY NOTHING. A typo is\n" +
+      '   in neither set by construction.\n\n' +
+      '   Fix the VALUE in packages/spec/liveness/<type>.json — it is almost always a\n' +
+      "   misspelling of the verdict the author meant. ⛔ Never widen STATUS_COLUMNS to\n" +
+      '   accept it: that vocabulary is what the generated artifact publishes as columns,\n' +
+      '   and a fifth name there changes the artifact (see the totals failure below).',
+    );
+  }
   if (report.ungoverned.length) {
     console.log(`\n✗ ${report.ungoverned.length} REGISTERED metadata type(s) governed by nothing:`);
     report.ungoverned.forEach((t: string) => console.log(`    ${t}`));
@@ -1288,6 +1372,15 @@ if (asJson) {
       '   cell; the Notes prose is what this table is for.',
     );
   }
+  if (report.countsTotalErrors.length) {
+    console.log(
+      `\n✗ ${report.countsTotalErrors.length} governed type(s) where ${STATE_COUNTS_FILE}'s columns ` +
+      "do not add up to the walk's own count:",
+    );
+    report.countsTotalErrors.forEach((s: string) => console.log(`    ${s}`));
+    console.log('');
+    STATE_COUNTS_TOTALS_GUIDANCE.forEach((line) => console.log(line ? `   ${line}` : ''));
+  }
   // ── re-verification clock ──
   // Annotated at the boundary: `report` is deliberately `any` (see its
   // declaration), so without this every `v.*` below is `any` too — which is how

packages/spec/scripts/liveness/check-liveness.test.ts

@@ -702,3 +702,99 @@ describe('check:liveness — the manifest is inside the governed universe (#1072
     expect(src).toContain("const schema = SPEC_ONLY_SCHEMAS[type] ?? getMetadataTypeSchema(type);");
   });
 });
+
+// A ledger `status` was free text: any truthy string was classified and counted,
+// then dropped by `foldStateCounts`, which reads four names and nothing else. The
+// gate stayed GREEN over an understated total, because `state-counts.md` computes
+// its `classified` column as the sum of those four columns and the freshness leg
+// compares it against a re-render of the same fold — every reconciliation in the
+// gate comparing that number against itself.
+//
+// Measured across all 31 ledgers on the commit that switched this on: live 819,
+// planned 10, dead 80, experimental 5 — 914 classified, no fifth value. So the
+// population is ZERO and a green `pnpm check:liveness` proves nothing about
+// whether either guard can fire. `--ledger-root` is what answers that, for the
+// #5623 reason every block above states: the REAL gate, a COPY with one status
+// misspelled, and a real exit code.
+describe('check:liveness — an unrecognized ledger `status` (#13083)', () => {
+  let tmp: string;
+
+  beforeAll(() => {
+    tmp = mkdtempSync(path.join(tmpdir(), 'os-liveness-status-'));
+  });
+  afterAll(() => rmSync(tmp, { recursive: true, force: true }));
+
+  /** Rewrite one property's `status` in a copied ledger. */
+  function setStatus(root: string, type: string, prop: string, status: string): void {
+    const file = path.join(root, `${type}.json`);
+    const ledger = JSON.parse(readFileSync(file, 'utf8'));
+    ledger.props[prop].status = status;
+    writeFileSync(file, `${JSON.stringify(ledger, null, 2)}\n`);
+  }
+
+  /** A copy of the real ledger root with `field.useGrouping` misspelled. */
+  function typodRoot(name: string): string {
+    const root = path.join(tmp, name);
+    cpSync(LEDGERS, root, { recursive: true });
+    // `field.useGrouping` is `planned` and carries no evidence, so the misspelling
+    // is the only thing in the copy that can move a verdict — no evidence-scan
+    // finding can be confused for it.
+    setStatus(root, 'field', 'useGrouping', 'planed');
+    return root;
+  }
+
+  // DISPOSITION 1. The row is named, with its coordinate and the offending value.
+  it("FAILS and names the row when a ledger `status` is misspelled", () => {
+    const { status, output } = runGate(typodRoot('d1-names-the-row'));
+    expect(status, output).toBe(1);
+    expect(output).toContain('whose `status` is not one of live / experimental / dead / planned');
+    expect(output).toContain('field/useGrouping → "planed"');
+  });
+
+  // The misspelled row is still COUNTED, deliberately. Dropping it would keep
+  // `classified` and the `byStatus` buckets in agreement and hide the row from
+  // the arithmetic below — silencing the second guard with the first.
+  it('still counts the misspelled row, under its own bucket name', () => {
+    const { output } = runGate(typodRoot('d1-still-counted'));
+    expect(output).toMatch(/^ {2}field {2,}\d+ classified \(.*\bplaned 1\b/m);
+  });
+
+  // DISPOSITION 2, through the real gate. The walk counted the row; the four
+  // columns did not; the artifact would have published the smaller number. This
+  // is the leg that fires even if the vocabulary itself grows — see
+  // readme-table.test.ts for that case, which no ledger typo can produce.
+  it('FAILS the totals arithmetic, because the fold cannot name that bucket', () => {
+    const { status, output } = runGate(typodRoot('d2-arithmetic'));
+    expect(status, output).toBe(1);
+    expect(output).toContain("do not add up to the walk's own count");
+    expect(output).toContain('1 in `planed`');
+    expect(output).toContain('is not the repair');
+  });
+
+  // The two are not one check reported twice: disposition 1 is the only one that
+  // can say WHICH row, and disposition 2 is the only one that reads a number the
+  // artifact actually publishes. A repair that satisfied one and not the other
+  // would leave the class open, so the split is pinned rather than assumed.
+  it('reports the two failures separately — one names the row, one names the number', () => {
+    const { output } = runGate(typodRoot('d1-d2-separate'));
+    const rowLine = output.split('\n').find((l) => l.includes('field/useGrouping → "planed"'));
+    const sumLine = output.split('\n').find((l) => l.includes("publishes") && l.includes('the walk counted'));
+    expect(rowLine, output).toBeTruthy();
+    expect(sumLine, output).toBeTruthy();
+    // The arithmetic is per TYPE — it cannot name the property, which is exactly
+    // why disposition 1 is not redundant with it.
+    expect(sumLine).not.toContain('useGrouping');
+    expect(sumLine).toContain('field');
+  });
+
+  // The quiet half, and the reason the whole thing could be switched on: the four
+  // real statuses are the entire population today, so an unmutated run must be
+  // green AND must show neither heading. "Exits 0" alone would also be satisfied
+  // by a guard wired to nothing.
+  it('stays GREEN on the real ledgers, where every status is one of the four', () => {
+    const { status, output } = runGate();
+    expect(status, output).toBe(0);
+    expect(output).not.toContain('whose `status` is not one of');
+    expect(output).not.toContain("do not add up to the walk's own count");
+  });
+});