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, with one opt-in exception: -rederive-setup re-derives the setup INSERT from the recipe (Case.InsertSQL) when the generator changed how it SPELLS the same data — a FLOAT value written through CAST(… AS FLOAT) once a bare DOUBLE literal stopped being admitted to a FLOAT column. That is the same pure computation over the recipe as the two headers. What this tool cannot see is whether the new spelling stores the same values, and it does not claim to: full_test, which executes every scenario against a real cluster, is the proof that the frozen rows still hold over the re-spelled setup, and it is required green after such a run. 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.