row-gen

Overview ¶

row-gen turns registry evidence into pastable, ratifiable admission rows (issue #44, #40's phase 4, #37's increment 2). For every TF type in live/mapping.json with a cfn_type (via name or alias), it classifies the type from live/registry.json's evidence - primaryIdentifier against the read-only and create-only property sets - into one of four buckets: proposed server-assigned, proposed client-named, needs a hand-chosen composite separator, or evidence-only. For via:fold rows (TF types mapping-gen decided are property-children of a CFN parent) it prints the property-child evidence and, when the parent is itself proposed, a parent-derived admission note.

Every mode but -emit only prints: the maintainer stance from #37 is that a wrong row touches live infrastructure, so a human pastes, edits and ratifies every block this tool proposes. -emit is the exception issue #96 added, and it writes the two generated tables outright - see emit.go for why that is a fixed point over already-ratified rows rather than a fresh derivation.

One consequence of that is worth stating where the modes are listed, since it is not what a generator usually behaves like (issue #263): a row that leaves the table cannot be brought back by re-running -emit, because the table it reads is the table it wrote last time. -emit therefore refuses to write a smaller table unless -allow-retraction says so. retraction.go is the whole of that gate and states the measurement behind it.

go run ./tools/row-gen              # every service batch, full report
go run ./tools/row-gen -service Lambda

-convergence switches to a second mode entirely (rowgen-convergence): for every type -emit would admit, it diffs a fresh proposal against the ratified entry and writes live/rowgen-convergence.json, the one artifact this tool does write - a measurement of its own proposals against ground truth, not a row for live infrastructure. See convergence.go's own doc comment.

go run ./tools/row-gen -convergence

-propose switches to a third mode (issue #65's PROPOSE stage): only the proposals whose classification rule has a spotless, large-enough historical record - see propose.go's own doc comment for the exact bar and the report's own printed contract for what a human approving those proposals is and is not trusting. Still prints only; still writes nothing.

go run ./tools/row-gen -propose