epic #470 C11: migration handoff — seed the plugin ledger on witnesses, not trust

[Weegy]

Epic #470 C11 — the migration handoff. Stacked on #804 (C10); retarget to main once that lands.

Core's migrations 0022–0030 stay in core's ledger and core keeps shipping them. This PR lets the extracted plugin adopt them on an existing installation instead of re-applying them — and makes it prove it may.

The failure this exists to prevent

The naive handoff copies the donor ledger's rows into the plugin's ledger and skips those files. On a healthy database that is correct. On one specific database it destroys the installation silently:

donor rows present, schema objects ABSENT — a restore from a snapshot taken before they existed, a version-skewed rollback, an operator who dropped a table during an incident.

The naive seed writes nine rows, the runner applies nothing, the plugin activates green, and every request 500s — nine steps and one deploy behind the cause.

So the donor ledger is corroboration, never authority. Each file carries a witness: a catalog query true only when the schema object that file creates is actually there.

	witness true	witness false
donor row present	seed	do not seed — the runner applies the (idempotent) file; that is the repair
no donor row	seed anyway — the schema is there, the ledger is what was lost	do not seed (ordinary fresh install)

Read down that table and the rule collapses to "the witness decides". That is deliberate, and it is why the donor read is reported rather than obeyed: the interesting number is the disagreement between the two, and dryRun against production surfaces it before anything is written.

A file with no witness is never seeded. Absence of proof is not proof, and the fallback costs one idempotent statement.

What ships

• middleware/src/platform/pluginMigrationHandoff.ts — seedPluginLedgerFromDonor(). One transaction under C7's advisory lock (PLUGIN_MIGRATION_LOCK_NS, keyed on the ledger), so a seed serialises against a migrate and against a second seed. lock_timeout and statement_timeout are C7's, because a plugin-supplied witness must not hold the ledger lock forever. dryRun rolls the whole transaction back — the ledger DDL and any side effect a witness had included.
• ctx.sql.seedLedger({ entries, dryRun }) — the plugin supplies its filenames and its witness SQL; core supplies the donor ledger (_multi_orchestrator_migrations). A plugin has no field for the donor table, which is what keeps one plugin out of another plugin's migration history. A plg_-prefixed donor is refused outright.
• Stem matching. The plugin ships 0022_dev_platform.js (codegen'd); core recorded 0022_dev_platform.sql. Full-name matching would find nothing and report "no donor rows", which looks exactly like a fresh install.
• Witness SQL, not a callback. A callback cannot be printed, and the entire value of dryRun is an operator reading which query proved which file. The shape is enforced, not coerced: exactly one row, one column, a real boolean. (SELECT count(*) is the tempting wrong witness — 1 for a table that exists, 0 for one that exists and is empty, a throw for one that does not.)
• One definition of the ledger row. pluginLedgerDdl, migrationChecksum and listMigrationFiles are now exported from pluginMigrations.ts and used by the seeder. A seeded row is byte-identical to one the runner would have written; a checksum computed differently would trip the drift guard and turn a successful handoff into a hard activation failure one boot later.
• @omadia/plugin-api 1.2.0 → 1.3.0 (additive: SqlAccessor.seedLedger is optional, LedgerSeedEntry, SeedLedgerOptions, LedgerSeedReport). Snapshot regenerated; the diff is +21 lines, all additions. A plugin built against 1.3.0 still activates on a 1.2.0 core, where the accessor is undefined and the idempotent files simply run.
• Operator CLI — node middleware/scripts/plugin-ledger-handoff.mjs --plan <plan.json>. Dry run by default; --apply is the only way to write. It prints the plan against $DATABASE_URL and highlights the disagreement list.

Rollback

Uninstalling the plugin and reverting C10 leaves core's migrator consistent, because nothing here writes to core's ledger:

1. Donor rows are never deleted. The module contains no DELETE at all, and a test asserts the donor table is byte-for-byte identical (ids and applied_at) after a seed. Revert C10 and core's migrator finds its ledger exactly as it left it, applies nothing, and boots.
2. The plugin's ledger (plg_omadia_dev_platform_migrations) is a table only the plugin reads. Uninstall may orphan or drop it (D3: orphan by default); core never looks at it.
3. The dev_* tables are never dropped by the handoff. C10 kept the migrations in core for exactly this reason: for one release both sides can apply them, and the files are idempotent.

The one irreversible act in this area would be deleting the donor rows — with them gone and core still shipping the files, core's own migrator would re-run all nine on the next boot. That is why the delete does not exist rather than being merely unused.

Tests

27 new tests, 25 of them pg-gated (skip cleanly without a test database, per #572). Fixture names are neutral throughout — the mechanism is generic, and core's ratchet counts the extracted plugin's identifiers in middleware/test.

#	Scenario	Result
a	donor rows present + objects present	9 seeded, runner then applies 0, skips 9
b	donor rows present + objects absent (restore)	0 seeded, skippedNoWitness = 9, runner applies 9 and repairs the schema
c	no donor rows + objects present	seeded on the witness alone; donorRecorded empty
—	no donor rows + objects absent	0 seeded, skippedNoWitness empty (no disagreement to report)
—	a file with no witness	never seeded, even with a donor row
d	dryRun	plan returned; the ledger table does not even exist afterwards; a later real run still has all 9 to do
d′	dryRun over an existing ledger	row count unchanged, alreadySeeded reported
e	donor rows after seeding	ids and applied_at byte-for-byte identical
f	two concurrent seeders	one seeds 9, the other reports alreadySeeded 9; no duplicate rows
—	counter-proof	a donor-row-only seed is written out inline: the runner then applies 0 while to_regclass on the table returns NULL — the green activation whose every request 500s
—	guards	plg_-namespaced donor refused; non-allowlisted identifier refused; a claimed file the package does not ship refused; a missing donor table reads as "no donor rows", not an error

Plus a wiring suite through createPluginContext (the accessor is absent without the grant; a .js file adopts a .sql donor row; non-boolean witness, empty entries, blank witness and duplicate filename all rejected) and a non-pg test asserting CORE_MIGRATION_DONOR_LEDGER still matches the migrator that creates that table — a rename there would otherwise make the handoff silently report "no donor rows" forever.

Mutation check

Replacing the decision with const proven = donorHasIt || (witness ? await witness(client) : false) — i.e. trusting the donor row — fails exactly three tests and no others:

• seeds NOTHING when the donor recorded the files but the schema objects are absent (case b)
• never seeds a file that has no witness at all
• does not seed when the witness is false, and the runner then applies the file (accessor)

The witness gate is load-bearing, not decorative.

One real bug the tests found

The first implementation validated the donor column name with the ledger-table charset rule, whose minimum length is three characters. The column is id. Every pg case failed identically on the first run; the rule is now split into a charset check for any donor identifier and the plg_-namespace check for the table only.

Gates

Gate	Result
npm run build	✅
npm run typecheck	✅
npm run typecheck:test	✅ 371 known, no regressions (baseline 371)
npm run lint	✅
npm test	✅ 6931 pass / 0 fail / 12 skipped (6943 total)
npm run test:pg	✅ 242 pass / 0 fail / 0 skipped
node scripts/check-core-decoupling.mjs	✅ held at 214 (unchanged from C10)

The ratchet cost one round of rewording: the first draft of the test-file headers explained the ratchet using the literal identifiers it counts, which pushed the test zone from 62 to 65. Reworded, not raised.

Note on naming

The working title for the CLI was scripts/dev-platform-handoff.mjs. It ships as middleware/scripts/plugin-ledger-handoff.mjs instead, for two reasons: a core script named after the plugin is the coupling this epic removes (and C13 pins the ratchet at 0), and the tool is genuinely generic — the plan file carries the plugin id, ledger, directory and entries, so the next subsystem to leave core uses it unchanged. It also lives under middleware/scripts/ rather than the repo root because that is where the other database-touching operator scripts live and where pg and dist/ resolve. Say the word and I will rename it.

---

One extra commit: the Postgres coverage floor

PG_TEST_FLOOR was 269 and describing a tree that no longer exists. C10 (#804) is red on this check today, at ran=243: it deleted the Dev Platform and its 26 pg tests left with the code they measured. A coverage floor that outlives its suites is not protecting anything — it is just failing, and a permanently-red guard is one nobody reads.

Re-pinned to 264, which is arithmetic and not a guess:

243  C10's measured run (269 − 26 deleted pg tests)
+21  C11: pluginMigrationHandoff.pg.test.ts (14) + …Accessor.pg.test.ts (7)
────
264  ← exactly what CI reports on this branch

That the two agree is itself the check that nothing else went quiet on the way. The comment in ci.yml now states the only legitimate reason to lower this floor — the covered code was deliberately removed — so the next drop still reads as the #565 silent skip this guard exists to catch.

If #804 lowers it independently, take the higher of the two; 264 is the correct value for C10 + C11 combined.

---

Cross-family review (Forge)

GPT-5.4 at reasoning_effort=high, reviewing against the code rather than the prose. Seven checks were asked for; six passed as written. One did not, and it is the one the design leans hardest on.

Verdict per check

#	Check	Result
1	donor rows never deleted/updated	✅ no DELETE/UPDATE/TRUNCATE against the donor anywhere in the module — but see the defect, which reintroduced the delete through the witness
2	witness SQL runs read-only	❌ failed — fixed in 20bc6563
3	seeded row shape identical to the runner's	✅ same pluginLedgerDdl, same migrationChecksum, same INSERT … (filename, checksum). The runner will not re-apply and will not trip drift
4	advisory lock namespace	✅ PLUGIN_MIGRATION_LOCK_NS = 4_420, same as C7, keyed on the ledger; concurrent-seed test passes
5	dryRun writes nothing	✅ asserted on database state (ledgerExists() false, ledgerRowCount() unchanged), not on the return value
6	CLI + ratchet	✅ dry run is the default, --apply is the only writer, DATABASE_URL (or explicit --database-url); check-core-decoupling.mjs held at 214
7	PG_TEST_FLOOR lowering	✅ justified, and re-raised — see below

The defect: witnesses could leave the transaction

A witness is SQL the plugin writes and core executes, on the connection holding the handoff transaction and its advisory lock. Both call sites ran it as await client.query(witnessSql) — a bare string, no bind values. In node-postgres 8.22 that takes the simple query protocol (Query.requiresPreparation() returns this.values.length > 0; an empty array is not enough), and the simple protocol accepts multiple commands per message.

Measured against the real PostgreSQL 16.13 test database, not reasoned about:

witness	observed
SELECT true AS ok; COMMIT; DROP TABLE victim	all three ran. The COMMIT ended the seeder's transaction; the DROP committed; the closing ROLLBACK was a no-op. Table gone.
DELETE FROM _multi_orchestrator_migrations RETURNING true	one row, one column, one real boolean — passes the shape check and is accepted as a witness
SELECT pg_advisory_lock(424242) IS NOT NULL	session-level lock survives ROLLBACK on the pooled connection

Three claims this PR makes in writing did not hold:

1. "dryRun rolls the whole transaction back … nothing survives it." A COMMIT inside a witness makes the final ROLLBACK a no-op. The operator CLI defaults to dry run and is documented as costing "one read-only transaction" — it was neither read-only nor reliably rolled back.
2. "a seed serialises against a migrate." The COMMIT released pg_advisory_xact_lock mid-seed.
3. "the delete does not exist rather than being merely unused." True of the module; not true of the witness path. The PR names deleting the donor rows as the one irreversible act in this area — and a witness could do it.

The fix (20bc6563)

Two guards, both enforced by PostgreSQL rather than by scanning the string — a semicolon inside a legal string literal is still a valid witness, and a test pins that:

• Read-only subtransaction. SAVEPOINT → SET LOCAL transaction_read_only = on → witness → ROLLBACK TO SAVEPOINT → RELEASE. DELETE is refused with cannot execute DELETE in a read-only transaction. Rolling back the savepoint is the only route back: PostgreSQL refuses to clear the GUC once a statement has taken a snapshot.
• Extended query protocol. queryMode: 'extended' → the server refuses multi-command strings with cannot insert multiple commands into a prepared statement, before any part executes. (@types/pg 8.21 predates the option that pg 8.22 implements, so it reaches the driver through one documented cast; a pg test pins the behaviour against a real server, so a driver or types change that dropped it fails loudly.)

MigrationWitness is now SQL text, not a callback. A callback cannot be fenced — it receives the privileged client. This also removed a real duplication: the shape check existed twice, in makeSqlWitness (accessor) and witnessFor (CLI), each carrying the same hole. Both are deleted; the seeder owns execution, so neither caller can get it wrong, and the CLI inherits the guarantee rather than re-implementing it.

Two further defects found while verifying the fix:

• throw inside finally in the teardown (caught by no-unsafe-finally) would have discarded the witness error that caused the cleanup failure — the exact error an operator most needs. Teardown moved out of finally; both errors are now carried out and reported together.
• A shape failure was double-wrapped, burying its precise, file-named message inside a second envelope and JSON-quoting it. SqlMigrationError now passes through unwrapped.

Mutation check

Reverting the fence to await client.query(sql) fails exactly five tests and no others:

✖ refuses a multi-command witness and leaves both the canary and plugin ledger untouched
✖ refuses a genuine multi-command witness but still allows a semicolon inside a legal string literal
✖ refuses a witness that tries to write and leaves donor rows unchanged
✖ dryRun with a hostile witness leaves nothing behind
✖ refuses a multi-command witness through ctx.sql.seedLedger and leaves the canary intact

Every one asserts on database state — canary table still present, donor row count unchanged, ledger row count zero — not merely on the thrown error.

One of these tests initially failed for a reason worth recording: a non-dryRun seed commits its ledger DDL even when every witness is false, so ledgerExists() is true with zero rows. The assertion was wrong, not the code; it is now a row-count assertion, which is the stronger claim anyway.

PG_TEST_FLOOR: 264 → 270

The lowering to 264 was justified (C10 removed 26 pg tests) and the guard still catches a silent skip — it fails on skipped != 0 independently of the floor. Re-raised for the six new tests, measured per file rather than inferred:

243  C10's measured run
+19  pluginMigrationHandoff.pg.test.ts        (was 14)
 +8  pluginMigrationHandoffAccessor.pg.test.ts (was 7)
────
270  ← exactly what this branch reports

⚠️ Merge-order gate — plugin-api is now 1.4.0

#802 merged while this review was running (d0a64696, 19:46 UTC) and took 1.3.0. main now carries plugin-api 1.3.0, so this PR's 1.3.0 would have been a duplicate version — indistinguishable from a silently-changed contract to anything resolving by version. Re-cut as 1.4.0, with the reason recorded in the CHANGELOG.

Two things still need a human:

• This branch has not merged main. Its base is chore(#470): C10 — the flip: delete the Dev Platform from core (~49k LOC) #804 (C10), which is itself behind main. fix(#470): three core gaps the P5 acceptance run hit — optional_requires, core migration ledger, scoped plugin nav (C9) #802 touched the same four plugin-api files (package.json, CHANGELOG.md, api-snapshot/, src/pluginContext.ts), so conflicts in all four are expected when C10 and then C11 catch up. Resolving them here first would have made the diff against C10 unreviewable.
• The API snapshot was regenerated and is purely additive (0 deleted lines vs. the C10 base), but it does not yet contain fix(#470): three core gaps the P5 acceptance run hit — optional_requires, core migration ledger, scoped plugin nav (C9) #802's 8-line change — that arrives with the merge.

Gates (all re-run after the fix)

Gate	Result
npm run build	✅ 0 errors
npm run typecheck	✅ 0 errors
npm run typecheck:test	✅ 371 known, no regressions (baseline 371)
npm run lint	✅ clean (was 2 errors — the finally defect above)
npm test	✅ 6931 pass / 0 fail / 12 skipped (6943)
npm run test:pg	✅ 270 pass / 0 fail / 0 skipped
node scripts/check-core-decoupling.mjs	✅ held at 214
TODO/FIXME/XXX in touched files	✅ 0

Residual, not fixed

A witness can still call pg_advisory_lock(), which is read-only-safe and survives the rollback, leaving a session lock on a pooled connection. Not a new capability — a plugin granted permissions.sql already runs arbitrary SQL through runMigrations — and the seeder's statement_timeout/lock_timeout bound the blocking, so it is recorded here rather than papered over. Fixing it properly means running witnesses on a connection that is discarded afterwards, which is a larger change than this PR should carry.

Verdict: MERGE, once #804 lands and the plugin-api conflicts against main are resolved.