Documentation
¶
Overview ¶
Command factory-plan-census makes a factory-corpus plan-shape drift READABLE, and fails loudly on the drift classes that are regressions.
The committed corpus records a plan-shape DIGEST, not a plan. That is enough to detect that something moved and useless for deciding whether the movement was an improvement, so a drift arrives as two hex strings and the only cheap response is to re-bless it. RETIREMENT_LEDGER.md states the cost of doing that ("a re-bless erases its own motive"), and this command is what makes the expensive response cheap instead.
It was written after a re-bless that would have absorbed 183 scenarios losing a correlated equality index probe on the inner side of a nested-loop join — an O(N)-per-outer-row regression that every row-based test passes, because the rows are unchanged. Nothing in the suite could see it, and the digest drift looked exactly like the 3521 benign movements around it.
TWO MODES.
dump — one `<scenario>\t<plan>` line per committed scenario. Run it in a
worktree at the base commit and again on the branch.
classify — read two dumps, partition the movement, and report NAMED COUNTS.
go run ./cmd/factory-plan-census dump -corpus <dir> > before.txt
go run ./cmd/factory-plan-census classify before.txt after.txt
classify EXITS NON-ZERO when a scenario loses an equality index probe. That is the regression class: an unbounded-range index scan replaced by a full scan reads the same rows with less indirection and is a legitimate cost choice, while an equality probe replaced by a full scan is not — and inside a join inner it is quadratic. Fetch-wrapper removal and COVERING acquisition are reported but never fail, being representation changes.
Source Files