test(engine): record what the zero-backlog early return stops testing (#3228)

## A green case that stopped testing what its name says

#3226 fixed a red `main` correctly: `fileWithGuards()` now returns
`null` at zero backlog, and with nothing to inflate there is no rise to
manufacture. Asserting `totals.column === 0` and returning is the honest
response.

What went unrecorded is the cost. At zero, these two cases:

- *"exits 0 and REWRITES the baseline under `--update-baseline`, even
when the count rose"*
- *"exits 1 and LEAVES the baseline alone on a rise without
`--update-baseline`"*

no longer exercise the CLI's ordering or exit codes. They assert the
backlog is empty and return. **If the write-before-exit ordering
regressed — the exact bug those cases were written for — both would
still pass.**

That matters more than it would elsewhere, because **zero is not a state
to wait out.** It is this program's terminal state: the backlog went 126
→ 0 and is meant to stay there. So the vacuity is permanent, not
transitional.

This file already legislates against precisely this, two hundred lines
down:

> `/* Anti-vacuity: an empty exclusion list would make the assertion
below trivially true. */`

## What this PR does

Adds a comment on `fileWithGuards()` recording (a) which cases go
vacuous at zero and why, (b) that zero is terminal so it will not
resolve itself, and (c) the durable fix.

**Comment only. No behaviour change — suite stays 53/53.**

## The durable fix, recorded rather than done

Point the scan at a synthetic tree so the fixture stops being a function
of the real backlog — the same seam `FUSION_CENSUS_BASELINE_PATH`
already provides for the baseline, applied to the file list.

It needs one CLI correction to work, and that is a genuine bug in my own
code regardless of this suite: `triageFindings` and the sync-resolver
check read files via `join(REPO_ROOT, f.file)`, where `REPO_ROOT` is
derived from the **script's** location. An overridden file list
therefore changes which paths are *listed* without changing where they
are *read from*, and every read misses with `ENOENT`.

I verified that approach works (a three-file fixture yields a stable `1
backlog / 1 deliberate / 1 sync-resolved`) and got two of the six
failing cases green with it, then stopped rather than keep guessing in a
file being actively revised. Left as a comment so whoever takes it does
not re-derive the diagnosis.

## Why this is worth a PR at all

This program's recurring failure is instruments that report green while
measuring nothing — an inert conversion the census scored as a win, a
ratchet wired to nothing, a gate that could not fail. A test asserting
`0 === 0` under a name promising ordering coverage is the same shape at
the test layer. The suite cannot be fixed in this PR without re-opening
work someone else owns, but it can at least stop being silent about it.

## Census before / after

```
before:  COLUMN guards (the backlog):   0
after:   COLUMN guards (the backlog):   0
```

## Verification

`test:gate` exit 0 · `lifecycle-column-census.test.ts` **53 passed** ·
`fnxc-future-dates`, `lifecycle-columns`, `inert-sync-lanes`,
`quarantine-ledger`, `inert-flag-seams`, `lane-wiring`,
`sql-column-literals` — all exit 0.
This commit is contained in:
gsxdsm
2026-07-31 12:28:09 -07:00
committed by GitHub
parent 6646c1b95d
commit d4c25384ae

View File

@@ -486,6 +486,28 @@ describe("the baseline can always be re-recorded", () => {
a proxy for it. Same discipline as the self-syncing fixture below — a test about control flow must
not depend on how much work the fleet has finished.
*/
/*
FNXC:LifecycleColumnCensus 2026-07-31-20:40 (what `null` costs, recorded so a green run is not misread):
Returns null when the census reports NO file with guards — the state the tree is in now that the
backlog reached 0. The two cases below then assert `totals.column === 0` and return early, which is
the honest thing to do: with nothing to inflate there is no rise to manufacture.
But it means those two cases **stop exercising what their names say** at zero backlog. "exits 0 and
REWRITES the baseline even when the count rose" and "exits 1 and LEAVES the baseline alone on a
rise" are about the CLI's ordering and exit codes; at zero they assert the backlog is empty. If the
write-before-exit ordering regressed — the exact bug those cases were written for — both would
still pass.
Worth stating because zero is not a state to wait out. It is the terminal state of this program, so
the vacuity is permanent, and this file already legislates against exactly that ("Anti-vacuity: an
empty exclusion list would make the assertion below trivially true").
The durable fix is to stop deriving the fixture from production state — point the scan at a
synthetic tree via a file-list override, the way `FUSION_CENSUS_BASELINE_PATH` already lets the
baseline be faked. Recorded rather than done here: it needs a content-root correction in the CLI
too (`triageFindings` and the sync-resolver check read via `join(REPO_ROOT, …)`, the SCRIPT's
location, so an overridden list changes which paths are listed and not where they are read).
*/
function fileWithGuards(): { file: string; count: number } | null {
const out = execFileSync("node", [cliPath, "--json"], { encoding: "utf8", cwd: repoRoot }) as string;
const parsed = JSON.parse(out) as { byFile: [string, number][] };