@quereus/isolation 4.4.1 → 4.6.0

package/dist/src/isolation-module.js

@@ -1,8 +1,8 @@
-import { MemoryTableModule, PhysicalType, QuereusError, StatusCode, tryFoldLiteral, columnDefToSchema, isConstraintViolation, inferType, validateAndParse } from '@quereus/quereus';
+import { MemoryTableModule, PhysicalType, QuereusError, StatusCode } from '@quereus/quereus';
 import { IsolatedTable } from './isolated-table.js';
 import { applyOverlayToUnderlying } from './flush.js';
-import { makeFullScanFilterInfo } from './filter-info.js';
 import { iterateEffectiveRows, makePkKeySerializer } from './overlay-rows.js';
+import { applyPkRekeyMarkerDrops, assertColumnNameNotTombstone, buildAlterPoisonMessage, deriveAlterMigrationPlan, migrateOverlayForward, planPkRekeyMarkerDrops, reinsertPkRekeyMarkers, validateOverlayMigration, } from './alter-migration.js';
 let overlayIdCounter = 0;
 /**
  * Generates a unique overlay ID for each overlay table instance.
@@ -286,7 +286,8 @@ export class IsolationModule {
      * overlay module's table registry rather than leaking there for the life of the
      * `Database`. This is the single sink every overlay-discard path funnels through —
      * without it, `MemoryTableModule.tables` accumulates one dead `_overlay_<table>_<id>`
-     * entry per writing transaction (and one more per rebuild), unbounded.
+     * entry per writing transaction (and one more per `alterPrimaryKey` overlay swap — the
+     * only DDL path left that replaces an overlay rather than adopting in place), unbounded.
      *
      * `MemoryTableManager.destroy` rolls back the overlay's own pending layer and clears its
      * connections; a later db-side teardown of the (now-detached) `MemoryVirtualTableConnection`
@@ -616,6 +617,21 @@ export class IsolationModule {
     async notifyLensDeployment(db, logicalSchemaName, snapshot) {
         await this.underlying.notifyLensDeployment?.(db, logicalSchemaName, snapshot);
     }
+    /**
+     * Forwards module registration to the underlying module.
+     *
+     * `Database.registerModule` calls `onRegister` on the REGISTERED module, which is this
+     * wrapper when a store is isolated. The underlying module uses it to subscribe to the
+     * database's schema-change notifier before any statement runs; without this forward an
+     * isolation-wrapped store would fall back to subscribing lazily at its first table
+     * hook and would silently drop a view created ahead of that.
+     *
+     * Which `Database` the module serves is isolation-transparent, so a straight delegate
+     * is correct; a throw must propagate (it fails the registration by contract).
+     */
+    onRegister(db, moduleName) {
+        this.underlying.onRegister?.(db, moduleName);
+    }
     /**
      * Forwards the view / materialized-view catalog-persistability veto to the underlying
      * module.
@@ -790,7 +806,7 @@ export class IsolationModule {
      * covers the data conditions the pre-validation pass rejects before any overlay is touched;
      * this one covers a UNIQUE (or any other) violation raised by the in-place adoption itself.
      */
-    buildRebuildPoisonMessage(schemaName, tableName, ddlDescription, cause) {
+    buildInPlaceAdoptPoisonMessage(schemaName, tableName, ddlDescription, cause) {
         return `Another connection's ${ddlDescription} on '${schemaName}.${tableName}' declared a constraint this connection's `
             + `uncommitted rows violate (${cause}); roll back this transaction.`;
     }
@@ -907,8 +923,7 @@ export class IsolationModule {
         // Take the index back off the underlying's refreshed schema rather than reusing the
         // caller's object: that is the canonical post-create form (resolved column indices,
         // any normalization the underlying applied), and the overlay's copy is derived from it.
-        const updatedSchema = this.assertIndexPresent(state.underlyingTable, schemaName, tableName, indexSchema.name);
-        const created = updatedSchema.indexes.find(idx => idx.name.toLowerCase() === indexSchema.name.toLowerCase());
+        const { schema: updatedSchema, index: created } = this.assertIndexPresent(state.underlyingTable, schemaName, tableName, indexSchema.name);
         await this.applyIndexChangeToOverlays(db, schemaName, tableName, `create index '${indexSchema.name}'`, overlayState => this.createOverlayIndex(overlayState, updatedSchema.name, created));
     }
     /**
@@ -935,29 +950,34 @@ export class IsolationModule {
         await overlayTable.createIndex(this.createOverlayIndexSchema(indexSchema, baseName, overlaySchema.name));
     }
     /**
-     * Reads back the underlying table instance's post-`createIndex` schema, asserting it now
-     * carries the new index.
+     * Reads back the underlying table instance's post-`createIndex` schema plus the entry it now
+     * carries for the new index — the canonical post-create form each overlay's copy is derived
+     * from ({@link createOverlayIndex}).
      *
      * Both bundled underlyings refresh the instance's cached `tableSchema` (memory through
-     * `MemoryTable.createIndex`, the store through `StoreTable.updateSchema`), and the overlay
-     * rebuild below copies its index/constraint set from it. A third-party underlying that
-     * refreshed only its module-level schema would silently rebuild overlays under the PRE-index
-     * schema, re-opening the very hole this method exists to close — so assert rather than assume.
+     * `MemoryTable.createIndex`, the store through `StoreTable.updateSchema`). A third-party
+     * underlying that refreshed only its module-level schema would leave every overlay without
+     * the index — silently re-opening the very hole `createIndex`'s forward exists to close — so
+     * assert rather than assume.
      */
     assertIndexPresent(underlyingTable, schemaName, tableName, indexName) {
-        const updatedSchema = underlyingTable.tableSchema;
-        const present = updatedSchema && this.schemaHasIndex(updatedSchema, indexName);
-        if (!updatedSchema || !present) {
+        const schema = underlyingTable.tableSchema;
+        const index = schema && this.findSchemaIndex(schema, indexName);
+        if (!schema || !index) {
             throw new QuereusError(`Isolation layer: underlying table '${schemaName}.${tableName}' did not refresh its cached tableSchema after `
                 + `creating index '${indexName}'. The per-connection overlays cannot adopt an index the underlying does not `
                 + `report; the underlying module must refresh VirtualTable.tableSchema in createIndex.`, StatusCode.INTERNAL);
         }
-        return updatedSchema;
+        return { schema, index };
     }
-    /** Case-insensitive "does `schema` declare an index named `indexName`". */
-    schemaHasIndex(schema, indexName) {
+    /** `schema`'s index named `indexName` (case-insensitively), if it declares one. */
+    findSchemaIndex(schema, indexName) {
         const lower = indexName.toLowerCase();
-        return schema.indexes?.some(idx => idx.name.toLowerCase() === lower) ?? false;
+        return schema.indexes?.find(idx => idx.name.toLowerCase() === lower);
+    }
+    /** Case-insensitive "does `schema` declare an index named `indexName`". Part of {@link AlterMigrationHost}. */
+    schemaHasIndex(schema, indexName) {
+        return this.findSchemaIndex(schema, indexName) !== undefined;
     }
     /**
      * Drops an index on the underlying table, then drops it from every per-connection overlay.
@@ -967,6 +987,11 @@ export class IsolationModule {
      * so MemoryTable.tableSchema stays fresh), prefer that. Otherwise fall back
      * to the module-level dropIndex (e.g. StoreModule, which refreshes the
      * StoreTable's cached tableSchema and tears down the index store).
+     *
+     * Mirrors createIndex's early return when neither hook exists too: an underlying that
+     * declares indexes at CREATE TABLE time but cannot drop one still has them, and dropping
+     * from the overlays alone would leave each overlay enforcing LESS than the base it flushes
+     * into — a silent divergence surfacing only as a commit-time rejection.
      */
     async dropIndex(db, schemaName, tableName, indexName) {
         const state = this.getUnderlyingState(schemaName, tableName);
@@ -976,6 +1001,9 @@ export class IsolationModule {
         else if (this.underlying.dropIndex) {
             await this.underlying.dropIndex(db, schemaName, tableName, indexName);
         }
+        else {
+            return; // underlying cannot drop indexes; nothing was dropped, nothing to forward
+        }
         await this.applyIndexChangeToOverlays(db, schemaName, tableName, `drop index '${indexName}'`, overlayState => this.dropOverlayIndex(overlayState, indexName));
     }
     /**
@@ -1032,7 +1060,7 @@ export class IsolationModule {
      * judged by the DDL's own validation pass, so a rejection here means validation and
      * migration have drifted — {@link issuerOverlayDriftError}); a foreign overlay →
      * poison and leave it untouched so its owner errors and rolls back
-     * ({@link buildRebuildPoisonMessage}). Any non-CONSTRAINT failure is a layer-invariant
+     * ({@link buildInPlaceAdoptPoisonMessage}). Any non-CONSTRAINT failure is a layer-invariant
      * violation, not a data condition, and rethrows for everyone.
      *
      * Shared by the index paths ({@link applyIndexChangeToOverlays}) and the ALTER TABLE
@@ -1043,39 +1071,50 @@ export class IsolationModule {
             await apply();
         }
         catch (e) {
-            if (!(e instanceof QuereusError) || e.code !== StatusCode.CONSTRAINT)
+            // NOTE: a rethrow here abandons the rest of the caller's overlay walk, and the DDL has
+            // already landed on the shared underlying — so overlays not yet visited neither adopt
+            // the change nor get poisoned. Safe today: every rethrown source is a layer-invariant
+            // violation (INTERNAL), which no overlay could have satisfied anyway. The two
+            // per-overlay DATA conditions — CONSTRAINT, and the BUSY the overlay module's own
+            // primary-key re-key representability check raises — are routed below instead.
+            if (!(e instanceof QuereusError) || (e.code !== StatusCode.CONSTRAINT && e.code !== StatusCode.BUSY))
                 throw e;
-            if (isIssuer)
+            if (isIssuer) {
+                // A BUSY out of the issuer's own overlay is a representability refusal its
+                // validation pass never claimed to judge — not drift. The tier-2 pre-flight
+                // surfaces it before the underlying mutates for the bundled overlay module, so
+                // this rethrow is reachable only through a host-injected overlay module.
+                if (e.code === StatusCode.BUSY)
+                    throw e;
                 throw this.issuerOverlayDriftError(schemaName, tableName, ddlDescription, e);
-            overlayState.poison = { message: this.buildRebuildPoisonMessage(schemaName, tableName, ddlDescription, e.message) };
+            }
+            // NOTE: preparation the failed `apply()` already performed is NOT undone here — the
+            // PK-re-key arm drops collapsed deletion markers before forwarding the re-key
+            // (`dropCollapsedPkRekeyMarkers`), and a refusal after that leaves them dropped.
+            // Inert while poison is terminal: the only exit is a rollback that discards the
+            // overlay whole. If poison ever becomes recoverable, this overlay must be restored
+            // the way the issuer's is (`reinsertPkRekeyMarkers`) before it can be un-poisoned.
+            overlayState.poison = { message: this.buildInPlaceAdoptPoisonMessage(schemaName, tableName, ddlDescription, e.message) };
         }
     }
     /**
      * Delegates ALTER TABLE to the underlying module and carries any per-connection
      * overlays to the post-alter schema without discarding staged rows.
      *
-     * Every change type forwards to each overlay IN PLACE — through the overlay's own
+     * The migration machinery itself — deriving the per-change-type constants, dry-running
+     * one overlay against them, and reshaping it forward — lives in `alter-migration.ts`;
+     * this method owns the surrounding lifecycle. Every change type but one forwards to each
+     * overlay IN PLACE via {@link migrateOverlayForward} — through the overlay's own
      * `alterSchema` / `createIndex` / ordinary writes — so the overlay's layer chain and
      * savepoint snapshots survive the ALTER and `rollback to savepoint` keeps
      * distinguishing rows staged before the savepoint from rows staged after it (see
      * {@link applyIndexChangeToOverlays} for why the old rebuild — copying staged rows
-     * into a fresh staging table — destroyed that distinction). Per change type:
-     *
-     * - ADD / DROP / RENAME COLUMN: {@link forwardColumnShapeToOverlay}. ADD COLUMN
-     *   backfills each staged row exactly as the committed path does (literal default,
-     *   per-row `new.<col>` evaluator, or NULL); tombstone rows get NULL.
-     * - ALTER COLUMN: {@link forwardAlterColumnToOverlay}. `set data type` / `set collate`
-     *   / `set default` forward straight through (the overlay module converts / re-keys its
-     *   open layers itself); `set not null` is withheld from the overlay and the staged
-     *   live rows' NULLs are backfilled via ordinary overlay writes instead.
-     * - ADD / DROP / RENAME CONSTRAINT: {@link forwardAddConstraintToOverlay} /
-     *   {@link forwardConstraintNameChangeToOverlay}. A UNIQUE lands as a
-     *   tombstone-narrowed unique index; CHECK forwards verbatim; FOREIGN KEY does not
-     *   forward at all.
-     * - ALTER PRIMARY KEY: no overlay can follow (its layer trees are keyed by the old
-     *   primary key) — the issuer with staged rows is rejected before the underlying
-     *   mutates, a foreign overlay with staged rows is poisoned, and a clean overlay is
-     *   swapped for a fresh staging table ({@link replaceOverlayForPrimaryKeyChange}).
+     * into a fresh staging table — destroyed that distinction).
+     *
+     * ALTER PRIMARY KEY is the exception: no overlay can follow it (its layer trees are keyed
+     * by the old primary key), so the issuer with staged rows is rejected before the underlying
+     * mutates, a foreign overlay with staged rows is poisoned, and a clean overlay is swapped
+     * for a fresh staging table ({@link replaceOverlayForPrimaryKeyChange}).
      *
      * **Atomicity guarantee.** DDL through Quereus is not transaction-scoped and the
      * underlying (shared, committed) base auto-commits its mutation immediately —
@@ -1129,46 +1168,103 @@ export class IsolationModule {
         // poisoned overlay whose schema may be a stale pre-alter layout.
         const toMigrate = ownEntry ? [ownEntry, ...foreign] : foreign;
         // ALTER PRIMARY KEY cannot be carried by any overlay: the staging table's layer
-        // trees are keyed by the OLD primary key, a staged tombstone identifies the row it
-        // deletes BY that key, and the (memory) overlay module rejects in-place PK
-        // alteration. When the ISSUER's own transaction has staged rows, reject up front —
+        // trees are keyed by the OLD primary key, and a staged tombstone identifies the row
+        // it deletes BY that key — under a new key its identity columns may be placeholder
+        // NULLs. (The memory overlay module can now re-key its OWN trees in place, but that
+        // does not repair the tombstone representation, so the refusal stands.) When the
+        // ISSUER's own transaction has staged rows, reject up front —
         // before the underlying mutates — so the ALTER fails atomically rather than
         // stranding rows it cannot re-key. Foreign overlays with staged rows are poisoned
         // after the underlying applies, and clean overlays are swapped for a fresh staging
         // table (see replaceOverlayForPrimaryKeyChange).
+        //
+        // BUSY, not UNSUPPORTED: this is retryable pending state, not a missing capability.
+        // The engine treats an UNSUPPORTED `alterTable` refusal as "use the shadow-table
+        // rebuild fallback" (see runAlterPrimaryKey in runtime/emit/alter-table.ts), which
+        // copies committed rows only — it would silently drop this transaction's staged
+        // writes. See docs/module-authoring.md § alterPrimaryKey.
+        //
+        // NOTE: an already-poisoned own overlay leaves `ownEntry` undefined (skipped above), so this
+        // refusal never fires for it — harmless while poison is terminal (rollback is the only exit,
+        // and it discards those old-key rows). If poison ever becomes recoverable, this check has to
+        // consult the poisoned own overlay too.
         if (change.type === 'alterPrimaryKey' && ownEntry?.[1].hasChanges) {
-            throw new QuereusError(`Cannot alter the primary key of '${schemaName}.${tableName}' while this transaction has uncommitted changes staged for it; commit or roll back first.`, StatusCode.UNSUPPORTED);
+            throw new QuereusError(`Cannot alter the primary key of '${schemaName}.${tableName}' while this transaction has uncommitted changes staged for it; commit or roll back first.`, StatusCode.BUSY);
         }
-        // Build the addColumn backfill context up front (undefined for other change types).
-        // Derived purely from `change` + the session nullability option — no post-alter
-        // schema needed — so it is valid here, before the underlying is mutated, and the
-        // same context drives the post-mutation migration.
-        const addColumnCtx = this.deriveAddColumnBackfill(change, db, tableName);
-        // Build the setNotNull backfill context (undefined unless this is a NOT NULL tightening
-        // with overlays to migrate). The now-NOT-NULL column's index and folded DEFAULT are read
-        // from a to-be-migrated overlay's PRE-alter schema — the same layout every migrated overlay
-        // shares.
-        const setNotNullCtx = this.deriveSetNotNullBackfill(change, toMigrate);
-        // Build the setDataType conversion context (undefined unless this is a value-rewriting
-        // retype with overlays to convert). Read from the same PRE-alter overlay schema as above;
-        // `inferType` cannot throw, so deriving it before the underlying mutation is safe.
-        const setDataTypeCtx = this.deriveSetDataTypeConvert(change, toMigrate);
+        assertColumnNameNotTombstone(this, schemaName, tableName, change);
+        // Precompute every per-change-type migration constant, from the PRE-alter schema — so the
+        // whole plan is valid here, before the underlying is mutated, and the same plan drives the
+        // post-mutation migration. The attribute arms read a to-be-migrated overlay's schema, never
+        // a skipped poisoned overlay's (possibly stale pre-alter) one.
+        const migration = deriveAlterMigrationPlan(change, db, tableName, toMigrate);
         // Tier 2: validate the ISSUER's own overlay BEFORE mutating the shared underlying.
         // Any throw here (CONSTRAINT backfill, MISMATCH conversion, or INTERNAL tombstone guard)
         // propagates while underlying + catalog + every overlay are still untouched — the companion
         // ticket's atomic-abort guarantee, preserved unchanged for the issuer.
         if (ownEntry) {
-            await this.validateOverlayMigration(ownEntry[1], addColumnCtx, setNotNullCtx, setDataTypeCtx);
+            await validateOverlayMigration(this, ownEntry[1], migration);
         }
         const underlyingState = this.getUnderlyingState(schemaName, tableName);
         // Hand the underlying the issuer's effective rows so its own row-content checks
         // (`add constraint … unique`, `alter column … set collate`) see the transaction's
         // pending rows and skip the ones it has deleted. An outer wrapper's source wins if
         // one was supplied.
-        const rowSource = rows ?? (underlyingState
+        let rowSource = rows ?? (underlyingState
             ? this.issuerEffectiveRows(db, schemaName, tableName, underlyingState.underlyingTable)
             : undefined);
-        const updated = await this.underlying.alterTable(db, schemaName, tableName, change, rowSource);
+        // Tier 2, PRIMARY-KEY re-key arm: the overlay's own `alterSchema` is itself fallible —
+        // its module re-validates the re-key against the overlay's layer chain (e.g. the memory
+        // module's representability BUSY when a savepoint could restore rows that collide under
+        // the new collation) — and it runs in the migrate step, AFTER the underlying has
+        // irreversibly re-keyed. So dry-run it here, against the exact state the migrate step
+        // will see: drop the collapsed markers first (saving them), pre-flight the overlay's
+        // `alterSchema` in validate-only mode, and on ANY later refusal — the pre-flight's or
+        // the underlying's — reinsert the markers and rethrow with everything net-untouched.
+        //
+        // The drops happen BEFORE `underlying.alterTable`, and a dropped marker un-shadows the
+        // committed row it deletes in `issuerEffectiveRows`'s merged stream — so the effective
+        // rows are SNAPSHOTTED first, and the underlying judges the pre-drop view.
+        let droppedMarkerRows = [];
+        if (migration.pkRekey && ownEntry && ownEntry[1].hasChanges && ownEntry[1].overlayTable.alterSchema) {
+            const ownOverlayState = ownEntry[1];
+            const pkRekeyCtx = migration.pkRekey;
+            const plan = await planPkRekeyMarkerDrops(this, ownOverlayState, pkRekeyCtx);
+            if (plan.length > 0) {
+                if (rowSource) {
+                    // NOTE: materializes the issuer's whole effective row set for this one ALTER.
+                    // The underlying's own re-key probe already holds every row it sees (see
+                    // MemoryTableManager.makePrimaryKeyProbe's NOTE), so this does not change the
+                    // peak's order of magnitude.
+                    const snapshot = [];
+                    for await (const row of rowSource())
+                        snapshot.push(row);
+                    rowSource = () => (async function* () { yield* snapshot; })();
+                }
+                droppedMarkerRows = plan;
+                await applyPkRekeyMarkerDrops(ownOverlayState, pkRekeyCtx, plan);
+            }
+            try {
+                // NOTE: unenforced contract — an overlay module that ignores `validateOnly` (see
+                // VirtualTable.alterSchema / IsolationModuleConfig.overlay) applies the re-key
+                // here for real, and a later refusal would then reinsert the markers into an
+                // already-re-keyed overlay. If host-injected overlay modules ever become common,
+                // gate this call on a module capability rather than on the documented contract.
+                await ownOverlayState.overlayTable.alterSchema(change, true);
+            }
+            catch (e) {
+                await reinsertPkRekeyMarkers(ownOverlayState, droppedMarkerRows);
+                throw e;
+            }
+        }
+        let updated;
+        try {
+            updated = await this.underlying.alterTable(db, schemaName, tableName, change, rowSource);
+        }
+        catch (e) {
+            if (ownEntry)
+                await reinsertPkRekeyMarkers(ownEntry[1], droppedMarkerRows);
+            throw e;
+        }
         // The cached underlying VirtualTable's `tableSchema` is a construction-time
         // snapshot (e.g. MemoryTable.tableSchema); module-level alterTable rotates the
         // underlying manager's schema but not this instance's field. Refresh it so a
@@ -1178,40 +1274,17 @@ export class IsolationModule {
         if (underlyingState)
             underlyingState.underlyingTable.tableSchema = updated;
         const ddlDescription = `alter table (${change.type})`;
-        // Carry one overlay to the post-alter schema, IN PLACE, so the overlay's layer
-        // chain and savepoint snapshots stay intact (see the method doc for the per-type
-        // routes). The `const` re-captures pin each case's narrowed change type for the
-        // apply closure.
+        // Carry one overlay to the post-alter schema. ALTER PRIMARY KEY swaps the overlay
+        // outright; every other change type adopts IN PLACE via `alter-migration.ts`, so the
+        // overlay's layer chain and savepoint snapshots stay intact. The `const` re-capture
+        // pins the narrowed (non-PK) change type for the apply closure.
         const migrateOverlay = async (key, state, isIssuer) => {
-            switch (change.type) {
-                case 'addColumn':
-                case 'dropColumn':
-                case 'renameColumn':
-                    await this.applyInPlaceOverlayChange(isIssuer, state, schemaName, tableName, ddlDescription, () => this.forwardColumnShapeToOverlay(state, change, addColumnCtx));
-                    break;
-                case 'alterColumn': {
-                    const alterColumnChange = change;
-                    await this.applyInPlaceOverlayChange(isIssuer, state, schemaName, tableName, ddlDescription, () => this.forwardAlterColumnToOverlay(state, alterColumnChange, setNotNullCtx));
-                    break;
-                }
-                case 'addConstraint': {
-                    const addConstraintChange = change;
-                    await this.applyInPlaceOverlayChange(isIssuer, state, schemaName, tableName, ddlDescription, () => this.forwardAddConstraintToOverlay(state, addConstraintChange, updated));
-                    break;
-                }
-                case 'dropConstraint':
-                case 'renameConstraint': {
-                    const nameChange = change;
-                    await this.applyInPlaceOverlayChange(isIssuer, state, schemaName, tableName, ddlDescription, () => this.forwardConstraintNameChangeToOverlay(state, nameChange));
-                    break;
-                }
-                case 'alterPrimaryKey':
-                    await this.replaceOverlayForPrimaryKeyChange(key, state, isIssuer, schemaName, tableName, updated, change);
-                    break;
-                default: {
-                    const _exhaustive = change;
-                }
+            if (change.type === 'alterPrimaryKey') {
+                await this.replaceOverlayForPrimaryKeyChange(key, state, isIssuer, schemaName, tableName, updated, change);
+                return;
             }
+            const inPlaceChange = change;
+            await this.applyInPlaceOverlayChange(isIssuer, state, schemaName, tableName, ddlDescription, () => migrateOverlayForward(this, state, inPlaceChange, migration, updated));
         };
         // Migrate the issuer's own overlay (already validated above). Its NOT NULL /
         // tombstone throw sites are unreachable after pre-validation; so is a UNIQUE
@@ -1232,11 +1305,11 @@ export class IsolationModule {
         // overlay, so one bad foreign overlay poisons only itself; healthy peers still migrate.
         for (const [key, oldState] of foreign) {
             try {
-                await this.validateOverlayMigration(oldState, addColumnCtx, setNotNullCtx, setDataTypeCtx);
+                await validateOverlayMigration(this, oldState, migration);
             }
             catch (e) {
                 if (e instanceof QuereusError && (e.code === StatusCode.CONSTRAINT || e.code === StatusCode.MISMATCH)) {
-                    oldState.poison = { message: this.buildAlterPoisonMessage(schemaName, tableName, change) };
+                    oldState.poison = { message: buildAlterPoisonMessage(schemaName, tableName, change) };
                     continue; // poisoned — do NOT migrate; leave pre-alter rows in place
                 }
                 throw e;
@@ -1245,31 +1318,6 @@ export class IsolationModule {
         }
         return updated;
     }
-    /**
-     * Builds the poison message stamped onto a foreign overlay whose backfill could not
-     * satisfy a cross-connection ALTER (see {@link alterTable} tier 3). Names the
-     * schema.table and the offending column so the owning connection's eventual
-     * read/write/commit error is self-explanatory. Poison arises on the addColumn NOT NULL
-     * path (a new NOT-NULL column with no usable default), the `set not null` tightening
-     * path (a staged NULL with no usable default), and the `set data type` path (a staged value
-     * that cannot be converted to the new type); other change types never reach here but
-     * are handled defensively.
-     */
-    buildAlterPoisonMessage(schemaName, tableName, change) {
-        if (change.type === 'addColumn') {
-            return `ALTER on '${schemaName}.${tableName}' added column '${change.columnDef.name}' (NOT NULL) that this connection's uncommitted row cannot satisfy; roll back this transaction.`;
-        }
-        if (change.type === 'alterColumn') {
-            if (change.setDataType !== undefined) {
-                return `ALTER on '${schemaName}.${tableName}' changed the data type of column '${change.columnName}' to ${change.setDataType}, which this connection's uncommitted row cannot be converted to; roll back this transaction.`;
-            }
-            return `ALTER on '${schemaName}.${tableName}' tightened column '${change.columnName}' to NOT NULL, which this connection's uncommitted row violates; roll back this transaction.`;
-        }
-        if (change.type === 'alterPrimaryKey') {
-            return `ALTER on '${schemaName}.${tableName}' changed the table's primary key, which this connection's uncommitted rows cannot follow; roll back this transaction.`;
-        }
-        return `ALTER on '${schemaName}.${tableName}' cannot migrate this connection's uncommitted rows; roll back this transaction.`;
-    }
     /**
      * Renames a table through the isolation layer.
      *
@@ -1386,493 +1434,6 @@ export class IsolationModule {
         }
         return oldKeys.length;
     }
-    // NOTE: the ALTER overlay pre-validation machinery (the three derive* helpers,
-    // validateOverlayMigration, buildAlterPoisonMessage, and the per-type forward* helpers below)
-    // threads one context parameter per value-rewriting attribute. If a fourth attribute ever
-    // needs a context, extract the cluster into its own module and pass a single context object
-    // instead of a widening parameter list.
-    /**
-     * Precomputes the per-ALTER constants an `addColumn` overlay backfill needs:
-     * the folded literal DEFAULT (the `tryFoldLiteral` of the DEFAULT expr, or `null`
-     * when there is no DEFAULT or it folds to NULL), the engine-supplied per-row
-     * evaluator (present only for a non-foldable `new.<col>` default), and whether
-     * the new column is NOT NULL. Returns undefined for every non-`addColumn` change
-     * so the row loop appends nothing.
-     *
-     * The new column's nullability is resolved exactly as both underlyings resolve it
-     * (`columnDefToSchema(columnDef, default_column_nullability === 'not_null')`) so the
-     * pre-validation cannot drift from what the underlying will enforce. Because it is
-     * derived purely from `change` + the session option — not the post-alter schema,
-     * which does not exist until `underlying.alterTable` runs — this can be built
-     * BEFORE the irreversible underlying mutation and reused by the migration after.
-     */
-    deriveAddColumnBackfill(change, db, tableName) {
-        if (change.type !== 'addColumn')
-            return undefined;
-        const defaultExpr = change.columnDef.constraints?.find(c => c.type === 'default')?.expr;
-        // tryFoldLiteral returns undefined for a non-foldable expr and null for one that
-        // folds to NULL; collapse both to null (the no-usable-literal default).
-        const foldedDefault = defaultExpr ? (tryFoldLiteral(defaultExpr) ?? null) : null;
-        const defaultNotNull = db.options.getStringOption('default_column_nullability') === 'not_null';
-        // Thread the session `default_collation` for symmetry with the underlying memory/store
-        // ADD COLUMN sites. This site only reads `.notNull`/`.name` off the result (the
-        // underlying materializes the real column), so it does not affect collation here — but
-        // keeping the call signature identical avoids drift and is correct for any future reader.
-        const newColumn = columnDefToSchema(change.columnDef, defaultNotNull, db.options.getStringOption('default_collation'), (n) => db.isCollationRegistered(n));
-        return {
-            foldedDefault,
-            evaluator: change.backfillEvaluator,
-            newColNotNull: newColumn.notNull,
-            newColName: newColumn.name,
-            tableName,
-        };
-    }
-    /**
-     * Precomputes the per-ALTER constants an `alter column … set not null` overlay migration needs:
-     * the now-NOT-NULL column's index and the folded literal DEFAULT (with `hasDefault` gating
-     * backfill vs reject). Returns undefined unless this is a NOT NULL *tightening*
-     * (`setNotNull: true`) with at least one overlay to migrate — a DROP NOT NULL loosens and
-     * needs no staged-row work, and with no overlays there is nothing to backfill or reject.
-     *
-     * `change` for `set not null` carries no default expression, so the DEFAULT is read from the
-     * column's PRE-alter schema (via a to-be-migrated overlay — the same layout every migrated
-     * overlay shares). Folded exactly as
-     * {@link deriveAddColumnBackfill} folds its DEFAULT, so backfill and reject decisions here
-     * cannot drift from what the underlying enforces over its committed rows.
-     */
-    deriveSetNotNullBackfill(change, toMigrate) {
-        if (change.type !== 'alterColumn' || change.setNotNull !== true)
-            return undefined;
-        if (toMigrate.length === 0)
-            return undefined;
-        const overlaySchema = toMigrate[0][1].overlayTable.tableSchema;
-        if (!overlaySchema)
-            return undefined;
-        const colIndex = overlaySchema.columnIndexMap.get(change.columnName.toLowerCase());
-        if (colIndex === undefined)
-            return undefined;
-        const defaultExpr = overlaySchema.columns[colIndex]?.defaultValue;
-        // tryFoldLiteral returns undefined for a non-foldable expr and null for one that folds to
-        // NULL; both mean "no usable literal default" — the staged NULL must reject, not backfill.
-        const folded = defaultExpr ? tryFoldLiteral(defaultExpr) : undefined;
-        const hasDefault = folded !== undefined && folded !== null;
-        return {
-            colIndex,
-            foldedDefault: hasDefault ? folded : null,
-            hasDefault,
-            colName: change.columnName,
-        };
-    }
-    /**
-     * Precomputes the per-ALTER constants an `alter column … set data type` overlay conversion
-     * needs: the retyped column's index and a per-value `convert`. Returns undefined unless this
-     * is a retype with at least one overlay to convert, and undefined for an ALIAS retype (the
-     * new logical type IS the old type object — `inferType` flattens `varchar(50)` to
-     * `TEXT_TYPE`) — both underlyings gate their value rewrite on that exact identity
-     * comparison, so mirroring it here keeps overlay and committed rows moving together should
-     * "what counts as a value-rewriting retype" ever change. A same-storage-class retype between
-     * different types (text → date) DOES convert: staged values are validated and normalized to
-     * the new type's canonical spelling, exactly as the underlyings treat their committed rows.
-     *
-     * `inferType` never throws (an unknown type name falls through SQLite-style affinity rules),
-     * so deriving this BEFORE the underlying mutation is safe. `convert` is the literal mirror of
-     * `MemoryTableManager.alterColumn` / `StoreModule.alterColumnSetDataType`: `validateAndParse`,
-     * rethrowing failure as the same MISMATCH message, so the two legs cannot drift.
-     */
-    deriveSetDataTypeConvert(change, toMigrate) {
-        if (change.type !== 'alterColumn' || change.setDataType === undefined)
-            return undefined;
-        if (toMigrate.length === 0)
-            return undefined;
-        const overlaySchema = toMigrate[0][1].overlayTable.tableSchema;
-        if (!overlaySchema)
-            return undefined;
-        const colIndex = overlaySchema.columnIndexMap.get(change.columnName.toLowerCase());
-        if (colIndex === undefined)
-            return undefined;
-        const oldCol = overlaySchema.columns[colIndex];
-        if (!oldCol)
-            return undefined;
-        const newLogicalType = inferType(change.setDataType);
-        // Alias retype (same logical type object): the underlying rewrites nothing, so neither do we.
-        if (newLogicalType === oldCol.logicalType)
-            return undefined;
-        const setDataType = change.setDataType;
-        const columnName = change.columnName;
-        return {
-            colIndex,
-            convert: (v) => {
-                try {
-                    return validateAndParse(v, newLogicalType, columnName);
-                }
-                catch {
-                    throw new QuereusError(`Cannot convert value in '${columnName}' to ${setDataType}`, StatusCode.MISMATCH);
-                }
-            },
-        };
-    }
-    /**
-     * Dry-runs an overlay's ALTER migration-fallible work without mutating anything,
-     * so the caller can run it for every affected overlay BEFORE the irreversible
-     * `underlying.alterTable` (see {@link alterTable}). It exercises the EXACT code
-     * paths the real migration uses — the tombstone-present guard and, for addColumn,
-     * `computeAddColumnValue` per staged row — so a dry-run pass and the subsequent
-     * migrate pass cannot diverge:
-     *
-     * - A clean overlay (`!hasChanges`) stages no rows, so there is nothing to validate.
-     * - A missing tombstone column throws INTERNAL here, before the underlying is touched.
-     * - For addColumn, each staged row runs through `computeAddColumnValue`: tombstone
-     *   rows short-circuit to `null` (the evaluator never runs), and a NOT-NULL-violating
-     *   evaluated row throws CONSTRAINT here, atomically. Computed values are discarded.
-     *
-     * For `set not null` with NO usable DEFAULT (`setNotNullCtx.hasDefault === false`), a staged
-     * non-tombstone NULL at the now-NOT-NULL column throws CONSTRAINT here — for the issuer this
-     * aborts atomically before the underlying mutates; for a foreign overlay the caller maps it to
-     * poison. With a usable DEFAULT the staged NULLs are backfilled by
-     * {@link backfillStagedNotNull}, so nothing is rejected here.
-     *
-     * For `set data type` (`setDataTypeCtx`), every staged non-NULL value is run through the
-     * conversion and the result discarded, so an unconvertible one throws MISMATCH here. For the
-     * ISSUER this is belt-and-braces — the underlying's own pre-mutation pass walks the same rows
-     * via {@link issuerEffectiveRows} — EXCEPT when an outer wrapper supplied `rows`, in which case
-     * this is the only check. For a FOREIGN overlay it is the only pass that ever sees those rows,
-     * and it must run before the migration so a failure becomes poison rather than a half-migrated
-     * overlay.
-     *
-     * Non-addColumn / non-tightening / non-retype changes (`addColumnCtx === undefined`, no
-     * reject-mode `setNotNullCtx`, no `setDataTypeCtx`) only run the tombstone guard; their row
-     * translation appends/removes nothing fallible on data grounds.
-     */
-    async validateOverlayMigration(oldState, addColumnCtx, setNotNullCtx, setDataTypeCtx) {
-        const oldOverlay = oldState.overlayTable;
-        const oldOverlaySchema = oldOverlay.tableSchema;
-        // Mirror the migrate-loop guard exactly: a clean overlay or one without a queryable
-        // schema stages nothing and runs none of the fallible checks.
-        if (!(oldState.hasChanges && oldOverlaySchema && oldOverlay.query))
-            return;
-        const oldTombstoneIdx = oldOverlaySchema.columnIndexMap.get(this.tombstoneColumn.toLowerCase());
-        if (oldTombstoneIdx === undefined) {
-            throw new QuereusError(`Tombstone column '${this.tombstoneColumn}' missing from overlay schema`, StatusCode.INTERNAL);
-        }
-        if (addColumnCtx) {
-            for await (const oldRow of oldOverlay.query(makeFullScanFilterInfo())) {
-                // Discard the result — this is validation only. A NOT NULL violation throws here.
-                await this.computeAddColumnValue(addColumnCtx, oldRow, oldTombstoneIdx);
-            }
-            return;
-        }
-        // SET NOT NULL with no usable DEFAULT: reject a staged NULL the forward could not fill.
-        // (With a DEFAULT there is nothing to reject — backfillStagedNotNull fills instead.)
-        if (setNotNullCtx && !setNotNullCtx.hasDefault) {
-            for await (const oldRow of this.stagedLiveRows(oldOverlay, oldTombstoneIdx)) {
-                if (oldRow[setNotNullCtx.colIndex] === null) {
-                    throw new QuereusError(`column ${setNotNullCtx.colName} contains NULL values`, StatusCode.CONSTRAINT);
-                }
-            }
-            return;
-        }
-        // SET DATA TYPE: prove every staged value convertible before anything is rewritten. NULLs
-        // are left untouched by the conversion (the underlying's `convertNulls` is false for a retype).
-        if (setDataTypeCtx) {
-            for await (const oldRow of this.stagedLiveRows(oldOverlay, oldTombstoneIdx)) {
-                const value = oldRow[setDataTypeCtx.colIndex];
-                if (value !== null)
-                    setDataTypeCtx.convert(value); // discard — validation only
-            }
-        }
-    }
-    /**
-     * The staged rows an overlay holds that represent LIVE data, i.e. every row except the
-     * tombstones — those carry placeholder NULLs at every data column and must never be fed to a
-     * per-value check, which would read a NULL that is not the row's real value.
-     */
-    async *stagedLiveRows(overlay, tombstoneIdx) {
-        for await (const row of overlay.query(makeFullScanFilterInfo())) {
-            if (row[tombstoneIdx] !== 1)
-                yield row;
-        }
-    }
-    /**
-     * Computes one staged row's value for a freshly added column, mirroring the
-     * committed-row backfill (see `base.ts` `recreatePrimaryTreeWithNewColumn` and
-     * `store-module.ts` `migrateRows`):
-     *
-     * - Tombstone rows carry NULL placeholders and their appended value is never read,
-     *   so append `null` and never run the evaluator against them (it could reference
-     *   NULL siblings or spuriously trip the NOT NULL check).
-     * - With a per-row evaluator, derive the value from the existing-columns slice and
-     *   enforce NOT NULL on that path only (a literal/NULL default's nullability is gated
-     *   up-front by the engine, exactly as `base.ts` does).
-     * - Otherwise use the folded literal default.
-     */
-    async computeAddColumnValue(ctx, oldRow, oldTombstoneIdx) {
-        if (oldRow[oldTombstoneIdx] === 1)
-            return null;
-        if (ctx.evaluator) {
-            const data = Array.from(oldRow.slice(0, oldTombstoneIdx));
-            const value = await ctx.evaluator(data);
-            if (ctx.newColNotNull && value === null) {
-                throw new QuereusError(`NOT NULL constraint failed: backfilling column '${ctx.tableName}.${ctx.newColName}' produced NULL for a staged row`, StatusCode.CONSTRAINT);
-            }
-            return value;
-        }
-        return ctx.foldedDefault;
-    }
-    /**
-     * Forwards one column-shape change (ADD / DROP / RENAME COLUMN) to an already-open
-     * overlay IN PLACE via the overlay's optional `alterSchema`. The overlay module (the
-     * memory module by default) reshapes its open transaction layers with their savepoint
-     * snapshots intact, so `rollback to savepoint` keeps distinguishing rows staged before
-     * the savepoint from rows staged after it — the rebuild path destroyed that
-     * distinction in both directions (see {@link applyIndexChangeToOverlays}).
-     *
-     * A missing `alterSchema` is treated as a no-op, the way the index paths treat a
-     * missing `createIndex` / `dropIndex`.
-     *
-     * `dropColumn` / `renameColumn` forward the caller's change unchanged. `addColumn`
-     * forwards an overlay-flavoured copy — see {@link buildOverlayAddColumnChange}.
-     */
-    async forwardColumnShapeToOverlay(overlayState, change, addColumnCtx) {
-        const overlayTable = overlayState.overlayTable;
-        if (!overlayTable.alterSchema)
-            return;
-        // `deriveAddColumnBackfill` returns a context for every addColumn, so the assertion
-        // cannot fire when the change type matches.
-        const overlayChange = change.type === 'addColumn'
-            ? this.buildOverlayAddColumnChange(change, addColumnCtx, overlayTable)
-            : change;
-        await overlayTable.alterSchema(overlayChange);
-    }
-    /**
-     * The overlay-flavoured form of one `addColumn` change:
-     *
-     * - `insertAtIndex` = the overlay's current tombstone column index, so the new data
-     *   column lands ahead of the tombstone flag and the flag stays LAST — the layout
-     *   every read/write path of this package assumes. A bare forward would append after
-     *   the flag and every value written to the new column would be dropped on read.
-     * - The column definition is made NULLABLE. The overlay's ADD re-runs the overlay
-     *   module's own NOT NULL validation against a different row population than the
-     *   base's: tombstone rows carry placeholder NULL in every non-PK column, so a
-     *   NOT NULL column the base already accepted would be rejected here. The base's
-     *   NOT NULL is still enforced where it belongs — by the engine's pre-mutation
-     *   `validateNotNullBackfill` and the underlying's own ADD (both judged the issuer's
-     *   effective rows), and per staged row by {@link computeAddColumnValue}'s
-     *   evaluator-path check.
-     * - `backfillEvaluator` receives an OVERLAY row (data columns plus the flag) and
-     *   routes through {@link computeAddColumnValue} — the same helper
-     *   {@link validateOverlayMigration} dry-runs, so validation and forward cannot
-     *   drift: NULL for a tombstone row, else the engine's per-row `new.<col>` evaluator
-     *   over the flag-stripped row, or the folded literal default.
-     */
-    buildOverlayAddColumnChange(change, addColumnCtx, overlayTable) {
-        const tombstoneIdx = overlayTable.tableSchema?.columnIndexMap.get(this.tombstoneColumn.toLowerCase());
-        if (tombstoneIdx === undefined) {
-            throw new QuereusError(`Tombstone column '${this.tombstoneColumn}' missing from overlay schema`, StatusCode.INTERNAL);
-        }
-        const constraints = (change.columnDef.constraints ?? []).filter(c => c.type !== 'notNull');
-        if (!constraints.some(c => c.type === 'null'))
-            constraints.push({ type: 'null' });
-        return {
-            ...change,
-            columnDef: { ...change.columnDef, constraints },
-            insertAtIndex: tombstoneIdx,
-            backfillEvaluator: (overlayRow) => this.computeAddColumnValue(addColumnCtx, overlayRow, tombstoneIdx),
-        };
-    }
-    /**
-     * Forwards one ALTER COLUMN attribute change to an already-open overlay IN PLACE, with the
-     * NOT NULL attribute deliberately withheld.
-     *
-     * `set data type` / `set collate` / `set default` forward through the overlay's own
-     * `alterSchema`: the overlay module converts / re-keys its open transaction layers with
-     * their savepoint snapshots intact, and NULLs pass a retype untouched, so tombstone rows —
-     * placeholder NULLs at every non-key data column — ride through unharmed.
-     *
-     * `set not null` must NOT forward: the overlay's copy of the column stays nullable.
-     * Tombstone rows carry NULL at every non-PK data column, so the overlay module's own
-     * tightening would backfill a deletion marker's placeholder NULL from the DEFAULT
-     * (corrupting a row that is not a row) or reject it outright when no usable DEFAULT
-     * exists. The base's NOT NULL is enforced where it belongs — by the underlying over the
-     * issuer's effective rows, and per overlay by {@link validateOverlayMigration} — and the
-     * staged LIVE rows' NULLs are filled here via {@link backfillStagedNotNull}. The runtime
-     * admits exactly one attribute per ALTER COLUMN, so a `setNotNull` change carries nothing
-     * else to forward. A missing overlay `alterSchema` is a no-op, as in
-     * {@link forwardColumnShapeToOverlay}.
-     */
-    async forwardAlterColumnToOverlay(overlayState, change, setNotNullCtx) {
-        if (change.setNotNull !== undefined) {
-            if (change.setNotNull === true && setNotNullCtx?.hasDefault) {
-                await this.backfillStagedNotNull(overlayState, setNotNullCtx);
-            }
-            return;
-        }
-        if (!overlayState.overlayTable.alterSchema)
-            return;
-        await overlayState.overlayTable.alterSchema(change);
-    }
-    /**
-     * Backfills a `set not null` tightening into an overlay's staged LIVE rows: every
-     * non-tombstone row holding NULL at the tightened column is rewritten with the column's
-     * folded literal DEFAULT through the overlay's ordinary write path, so the overlay's layer
-     * chain and savepoint snapshots stay intact — the overlay-side mirror of the value rewrite
-     * the underlying applies to its committed rows. Tombstone rows are never touched
-     * ({@link stagedLiveRows}).
-     *
-     * Only called with a usable DEFAULT ({@link SetNotNullBackfillContext.hasDefault}); the
-     * no-DEFAULT case rejects (issuer) or poisons (foreign) in {@link validateOverlayMigration}
-     * before any overlay is touched.
-     *
-     * NOTE: these rewrites land in the overlay's CURRENT savepoint frame — each is a normal
-     * staged write. A later `rollback to savepoint` taken BEFORE this ALTER therefore restores
-     * the pre-backfill NULL while the column stays NOT NULL (DDL is not transactional here).
-     * That is the same class of divergence as any rolled-back row violating surviving DDL — a
-     * row un-inserted past an ADD CONSTRAINT, say — tracked by the backlog ticket
-     * `bug-rolled-back-rows-violate-surviving-ddl`, not a new hole opened by this forward.
-     */
-    async backfillStagedNotNull(overlayState, ctx) {
-        const overlay = overlayState.overlayTable;
-        const overlaySchema = overlay.tableSchema;
-        if (!overlaySchema || !overlay.query)
-            return;
-        const tombstoneIdx = overlaySchema.columnIndexMap.get(this.tombstoneColumn.toLowerCase());
-        if (tombstoneIdx === undefined) {
-            throw new QuereusError(`Tombstone column '${this.tombstoneColumn}' missing from overlay schema`, StatusCode.INTERNAL);
-        }
-        const pkIndices = overlaySchema.primaryKeyDefinition.map(def => def.index);
-        // Materialize before writing: the rewrites mutate the overlay's pending layer the
-        // scan is reading through.
-        const toFill = [];
-        for await (const row of this.stagedLiveRows(overlay, tombstoneIdx)) {
-            if (row[ctx.colIndex] === null)
-                toFill.push(row);
-        }
-        for (const row of toFill) {
-            const values = row.map((v, i) => (i === ctx.colIndex ? ctx.foldedDefault : v));
-            // No `onConflict`, so `UpdateResult` is exactly `ok | constraint`. A constraint here
-            // (the filled value colliding under a UNIQUE) is a data condition of this overlay's
-            // staged rows — thrown as CONSTRAINT for applyInPlaceOverlayChange to route to
-            // INTERNAL (issuer, whose merged rows the underlying's own converted-row UNIQUE
-            // re-validation already judged) or poison (foreign).
-            const result = await overlay.update({
-                operation: 'update',
-                values,
-                oldKeyValues: pkIndices.map(i => row[i]),
-                preCoerced: true,
-            });
-            if (isConstraintViolation(result)) {
-                throw new QuereusError(`Backfilling column '${ctx.colName}' in overlay '${overlaySchema.name}' hit a ${result.constraint} constraint: ${result.message ?? 'no message'}`, StatusCode.CONSTRAINT);
-            }
-        }
-    }
-    /**
-     * Forwards one ADD CONSTRAINT to an already-open overlay, per constraint class:
-     *
-     * - **UNIQUE** is NOT forwarded as a constraint. The AST `TableConstraint` carries no
-     *   partial-predicate field, so a bare forward would enforce uniqueness over tombstone rows
-     *   too — a UNIQUE whose columns sit inside the primary key would see two deleted rows
-     *   (each carrying its PK and placeholder NULLs elsewhere) as duplicates of each other.
-     *   Instead it lands as a tombstone-narrowed **unique index** through the same route CREATE
-     *   INDEX takes ({@link installOverlayUniqueConstraint}).
-     * - **CHECK** forwards verbatim: the overlay module appends it schema-only (no row scan, no
-     *   physical structure). Enforcement is engine-side at DML plan time against the user
-     *   table; the overlay's copy exists so a later DROP / RENAME CONSTRAINT resolves it.
-     * - **FOREIGN KEY** is deliberately NOT forwarded. FK enforcement is engine-side
-     *   (planner-synthesized EXISTS checks) — the overlay never enforces it — and the overlay
-     *   module's ADD arm validates existing child rows through a catalog query by table name,
-     *   which the unregistered `_overlay_*` staging table cannot serve. The presence guard in
-     *   {@link forwardConstraintNameChangeToOverlay} keeps a later DROP / RENAME of the
-     *   unforwarded FK a clean no-op on the overlay.
-     * - **PRIMARY KEY** cannot reach here — both bundled underlyings reject
-     *   `add constraint … primary key` with UNSUPPORTED before any overlay work — so it asserts
-     *   INTERNAL rather than leaving a silent gap for a third-party underlying that accepts it
-     *   (the overlay could not follow; see the alterPrimaryKey handling in {@link alterTable}).
-     */
-    async forwardAddConstraintToOverlay(overlayState, change, updatedSchema) {
-        switch (change.constraint.type) {
-            case 'unique':
-                await this.installOverlayUniqueConstraint(overlayState, change.constraint, updatedSchema);
-                return;
-            case 'check':
-                if (overlayState.overlayTable.alterSchema)
-                    await overlayState.overlayTable.alterSchema(change);
-                return;
-            case 'foreignKey':
-                return;
-            case 'primaryKey':
-                throw new QuereusError(`Isolation layer: the underlying accepted 'add constraint … primary key' on '${updatedSchema.schemaName}.${updatedSchema.name}', which the per-connection overlays cannot follow.`, StatusCode.INTERNAL);
-        }
-    }
-    /**
-     * Installs one runtime-added UNIQUE constraint on an overlay as a tombstone-narrowed unique
-     * index (see {@link forwardAddConstraintToOverlay} for why a bare constraint forward is
-     * wrong). Column indices and per-column collations are read from the post-alter underlying
-     * schema — the canonical form, positionally identical to the overlay's data columns (the
-     * tombstone flag is appended last). The index is named `constraint name ?? '_uc_<cols>'`,
-     * the memory module's own covering-index naming rule (`implicitIndexNameFor`), so the
-     * derived UNIQUE the overlay module synthesizes from it resolves under the SAME name a
-     * later DROP / RENAME CONSTRAINT forward carries.
-     *
-     * `MemoryTableManager.createIndex` pre-validates the overlay's effective rows against the
-     * narrowed predicate before any mutation, so a staged duplicate raises CONSTRAINT with the
-     * overlay untouched — routed by the caller to INTERNAL (the issuer, whose merged rows the
-     * underlying already judged via {@link issuerEffectiveRows}) or poison (a foreign overlay).
-     * A missing overlay `createIndex` is a no-op, as in the index paths.
-     */
-    async installOverlayUniqueConstraint(overlayState, constraint, updatedSchema) {
-        const overlayTable = overlayState.overlayTable;
-        const overlaySchema = overlayTable.tableSchema;
-        if (!overlayTable.createIndex || !overlaySchema)
-            return;
-        const columns = (constraint.columns ?? []).map(col => {
-            const idx = updatedSchema.columnIndexMap.get(col.name.toLowerCase());
-            if (idx === undefined) {
-                throw new QuereusError(`Isolation layer: UNIQUE constraint column '${col.name}' not found on '${updatedSchema.schemaName}.${updatedSchema.name}' after the underlying accepted the constraint.`, StatusCode.INTERNAL);
-            }
-            return idx;
-        });
-        const indexName = constraint.name ?? `_uc_${columns.map(i => updatedSchema.columns[i].name).join('_')}`;
-        if (this.schemaHasIndex(overlaySchema, indexName))
-            return;
-        // A runtime-added UNIQUE carries no partial predicate of its own (the AST has no field
-        // for one), so the overlay predicate is exactly the live-rows narrowing.
-        await overlayTable.createIndex({
-            name: indexName,
-            columns: columns.map(i => ({ index: i, collation: updatedSchema.columns[i]?.collation })),
-            unique: true,
-            predicate: this.overlayPredicate(undefined, updatedSchema.name, overlaySchema.name),
-        });
-    }
-    /**
-     * Forwards DROP / RENAME CONSTRAINT to an already-open overlay, presence-guarded: a
-     * constraint the overlay never carried is skipped silently rather than letting the overlay
-     * module's NOTFOUND abort the issuer's already-applied ALTER. The guard is what makes the
-     * unforwarded classes safe ({@link forwardAddConstraintToOverlay}: FOREIGN KEY always, and
-     * UNIQUE under an overlay module without `createIndex`) — their DROP / RENAME is simply a
-     * no-op on the overlay.
-     *
-     * For a UNIQUE the overlay module drops/renames the constraint AND its covering index in
-     * lock-step — both live under the constraint's name (or the `_uc_<cols>` implicit-name
-     * rule), whether copied at overlay creation ({@link createOverlaySchema}) or installed by
-     * {@link installOverlayUniqueConstraint} — so the base and overlay representations stay
-     * resolvable by one name across the whole constraint lifecycle.
-     */
-    async forwardConstraintNameChangeToOverlay(overlayState, change) {
-        const overlayTable = overlayState.overlayTable;
-        const overlaySchema = overlayTable.tableSchema;
-        if (!overlayTable.alterSchema || !overlaySchema)
-            return;
-        const name = change.type === 'dropConstraint' ? change.constraintName : change.oldName;
-        if (!this.schemaHasNamedConstraint(overlaySchema, name))
-            return;
-        await overlayTable.alterSchema(change);
-    }
-    /** Case-insensitive "does `schema` declare a named constraint of ANY class (CHECK / UNIQUE / FOREIGN KEY)". */
-    schemaHasNamedConstraint(schema, constraintName) {
-        const lower = constraintName.toLowerCase();
-        return (schema.checkConstraints ?? []).some(c => c.name?.toLowerCase() === lower)
-            || (schema.uniqueConstraints ?? []).some(c => c.name?.toLowerCase() === lower)
-            || (schema.foreignKeys ?? []).some(c => c.name?.toLowerCase() === lower);
-    }
     /**
      * Carries one overlay across an ALTER PRIMARY KEY, which no overlay can follow in place:
      * its layer BTrees are keyed by the OLD primary key, and a staged tombstone identifies the
@@ -1893,9 +1454,17 @@ export class IsolationModule {
             if (isIssuer) {
                 throw new QuereusError(`Isolation layer: the issuer's overlay for '${schemaName}.${tableName}' reached alterPrimaryKey migration with staged rows; the pre-mutation guard in alterTable must reject this first.`, StatusCode.INTERNAL);
             }
-            state.poison = { message: this.buildAlterPoisonMessage(schemaName, tableName, change) };
+            state.poison = { message: buildAlterPoisonMessage(schemaName, tableName, change) };
             return;
         }
+        // NOTE: this is the only remaining path that swaps an overlay table rather than adopting
+        // the change in place, so a registered `IsolatedConnection` keeps the OLD overlay's
+        // connection (captured at construction, isolated-connection.ts) and forwards its
+        // savepoint/rollback calls to a released table. Benign today: the swapped overlay is
+        // clean, so nothing staged is lost, and the fresh overlay registers its own connection
+        // with the `Database` on its first write and receives the broadcasts directly. If this
+        // swap ever becomes reachable with staged rows, or per-connection state moves onto
+        // `IsolatedConnection`, retarget the connection here.
         const fresh = await this.overlayModule.create(state.db, this.createOverlaySchema(updatedSchema));
         this.connectionOverlays.set(key, { overlayTable: fresh, hasChanges: false, db: state.db });
         await this.releaseOverlayTable(state);
@@ -1921,6 +1490,16 @@ export class IsolationModule {
      *
      * `IsolatedTable.mergedSecondaryIndexQuery` wants exactly the live overlay rows out of
      * these indexes, so narrowing them is what it already expects.
+     *
+     * NOTE: a base column already named {@link tombstoneColumn} lands here as a SECOND column
+     * of that name, and `columnIndexMap` resolves the name to the appended flag. Harmless
+     * today — every consumer reaches the flag by index, and reads, merged scans, a unique
+     * secondary index over that column and a staged deletion all behave exactly as they do
+     * for a non-colliding name. If anything ever resolves the overlay's columns BY NAME (a
+     * hand-built overlay predicate, a module that re-derives its own index map from the
+     * column list), give the overlay a collision-free flag name here instead. ALTER into the
+     * name is rejected outright — see {@link assertColumnNameNotTombstone} for why that one
+     * cannot be tolerated.
      */
     createOverlaySchema(baseSchema) {
         const tombstoneColumn = {
@@ -1979,6 +1558,9 @@ export class IsolationModule {
      * self-qualifier to the overlay name so it stays a self-reference. A foreign qualifier
      * cannot occur here: `compilePredicate` already rejected one when the base index/UNIQUE
      * was created, so every qualifier present is the base name.
+     *
+     * Part of {@link AlterMigrationHost} — `alter-migration.ts` builds an overlay UNIQUE index
+     * through this same seam.
      */
     overlayPredicate(base, baseName, overlayName) {
         const rescoped = base ? rescopePredicateQualifier(base, baseName, overlayName) : undefined;