factory-rebless

Overview ¶

factory-rebless re-derives the PLAN-SHAPE and DEDUP-KEY headers of the committed RFC-201 factory corpus after a deliberate planner change, and rewrites the census baseline to match.

It exists because RFC-201 §5.3 requires a behaviour-changing fix to re-bless the affected expectations in the fixing PR, and the only re-emission tool the repo had (cmd/factory-migrate) reads the retired v1 `fc_*.yaml` layout. This one works on the committed `.yamsql` family files.

WHAT IT WILL AND WILL NOT TOUCH ¶

It rewrites two header fields and nothing else. Both are PURE COMPUTATION over the committed reproduction recipe — the same computation TestFactoryDeterminism performs to decide the headers have drifted — so re-deriving them is not an edit of an expectation, it is recomputing a derived value whose input changed.

The frozen RESULT ROWS are never touched, and that is the line that matters: rows are oracle output, and rewriting them is how a proof silently becomes an opinion. A planner change that alters rows is therefore OUT OF SCOPE here — it needs the oracle pipeline, not this tool. The corpus's own row-level gate (//pkg/relational/conformance/factorycorpus/full:full_test, which executes every scenario against a real cluster) is what proves the rows still hold, and it must be green BEFORE this tool is run and after.

"Never touched" is ENFORCED, not merely intended — see verifyRowsSurvived. Intent alone is worth nothing here, because the tool does not edit two lines: it RE-RENDERS the whole family file through the writer, rows included. The re-emission is therefore parsed back and its rows compared cell by cell against the rows that went in, so a writer defect cannot restate a frozen expectation inside a diff that reads as a header change.

Everything else the determinism gate checks — the candidate name, the feature vector, all four TLP renderings, the schema template, the setup INSERT — is VERIFIED, never rewritten. Any drift there means the change was not a pure plan flip and the run aborts, because the committed reproduction recipes would be lying about something this tool cannot honestly repair.

go run ./cmd/factory-rebless \
  -corpus pkg/relational/conformance/factorycorpus/testdata \
  -census pkg/relational/conformance/factorycorpus/census_baseline.json

-dry-run reports what would change and writes nothing.

ALL-OR-NOTHING ¶

The run is TWO-PASS: every file is verified and its replacement bytes computed in pass one, and nothing reaches the tree until pass one has cleared every file. A single-pass tool writes file N and then aborts on file N+1's drift, leaving a tree that is half re-blessed with a census describing neither half — a state whose diff looks like a deliberate partial re-bless and which no gate distinguishes from one. The abort must leave the corpus exactly as it found it, so the abort happens before the first write.

(Two-pass rather than write-temp-then-rename: rename gives per-file atomicity, which is not the property at risk. The corpus plus its census baseline is ONE consistent unit, so the transaction boundary is the whole run, not a file.)

Exit codes: 0 = done (or, under -dry-run, inspected); 1 = a drift this tool must not paper over; 2 = infra failure.