@quereus/isolation 4.3.2 → 4.4.1

package/dist/src/isolation-module.js

@@ -1,4 +1,4 @@
-import { MemoryTableModule, PhysicalType, QuereusError, StatusCode, tryFoldLiteral, columnDefToSchema, isConstraintViolation } from '@quereus/quereus';
+import { MemoryTableModule, PhysicalType, QuereusError, StatusCode, tryFoldLiteral, columnDefToSchema, isConstraintViolation, inferType, validateAndParse } from '@quereus/quereus';
 import { IsolatedTable } from './isolated-table.js';
 import { applyOverlayToUnderlying } from './flush.js';
 import { makeFullScanFilterInfo } from './filter-info.js';
@@ -616,6 +616,20 @@ export class IsolationModule {
     async notifyLensDeployment(db, logicalSchemaName, snapshot) {
         await this.underlying.notifyLensDeployment?.(db, logicalSchemaName, snapshot);
     }
+    /**
+     * Forwards the view / materialized-view catalog-persistability veto to the underlying
+     * module.
+     *
+     * `allModules()` yields the REGISTERED module, which is this wrapper when a store is
+     * isolated — so without this forward an isolation-wrapped store would never be
+     * consulted and would keep the silent-drop bug (a view it cannot persist creates
+     * "successfully" and vanishes on reopen). Whether a catalog entry is encodable is a
+     * property of the definition text, not of the overlay, so a straight delegate is
+     * correct; the throw must propagate (that is the entire point of the hook).
+     */
+    assertCatalogObjectPersistable(db, kind, object) {
+        this.underlying.assertCatalogObjectPersistable?.(db, kind, object);
+    }
     /**
      * Delegates access plan selection to the underlying module.
      * This ensures the query planner knows about indexes and can generate
@@ -755,70 +769,26 @@ export class IsolationModule {
         }
     }
     /**
-     * Inserts one staged row into a freshly built overlay, raising on anything but success.
-     *
-     * `MemoryTable.update` RETURNS a `constraint` status rather than throwing it. Every overlay
-     * rebuild loop ignored that return, so a row the new schema forbids was dropped on the floor
-     * and the transaction committed without it — silent data loss, reachable today by
-     * `alter table … add constraint … unique` over pending duplicate rows. Convert it into a
-     * throw; {@link adoptRebuiltOverlay} decides whether that means INTERNAL (the issuer, whose
-     * rows the DDL's own validation pass already accepted) or poison (a foreign connection,
-     * which must roll back).
-     */
-    async insertIntoRebuiltOverlay(newOverlayTable, values, tableName) {
-        // No `onConflict` is passed, so the overlay's memory module cannot answer `ignore`;
-        // `UpdateResult` is then exactly `ok | constraint`.
-        const result = await newOverlayTable.update({ operation: 'insert', values, preCoerced: true });
-        if (isConstraintViolation(result)) {
-            throw new QuereusError(`Overlay rebuild on '${tableName}' hit a ${result.constraint} constraint: ${result.message ?? 'no message'}`, StatusCode.CONSTRAINT);
-        }
-    }
-    /**
-     * Runs one overlay's rebuild and installs the result, routing a CONSTRAINT failure by who
-     * owns the overlay:
-     *
-     * - **The DDL-issuing connection.** Unreachable: the row source handed to the underlying
-     *   (see {@link issuerEffectiveRows}) judged a superset of exactly these rows and accepted
-     *   them, so a rejection here means validation and migration have drifted. Raise INTERNAL —
-     *   loudly, because the alternative is the silent row loss this guard exists to end.
-     * - **A foreign connection.** Reachable and legitimate: its staged rows may violate a
-     *   constraint another connection just declared. Poison that overlay and leave it
-     *   unmigrated, so its owner errors on its next read/write/commit and rolls back. The
-     *   issuer's DDL proceeds. Mirrors the tier-3 NOT NULL handling in {@link alterTable}.
-     *
-     * A rebuild that throws leaves the OLD overlay installed either way — the new table is
-     * simply discarded.
+     * The INTERNAL raised when the DDL-ISSUING connection's own overlay rejects the change the
+     * DDL just made (routed through {@link applyInPlaceOverlayChange} by the index paths and
+     * every ALTER TABLE forward).
+     *
+     * Unreachable by construction: the row source handed to the underlying (see
+     * {@link issuerEffectiveRows}) judged a superset of exactly these rows and accepted them,
+     * so a rejection here means validation and migration have drifted. Raise loudly — the
+     * alternative is the silent row loss these guards exist to end.
      */
-    async adoptRebuiltOverlay(key, oldState, isIssuer, schemaName, tableName, ddlDescription, rebuild) {
-        let rebuilt;
-        try {
-            rebuilt = await rebuild();
-        }
-        catch (e) {
-            if (!(e instanceof QuereusError) || e.code !== StatusCode.CONSTRAINT)
-                throw e;
-            if (isIssuer) {
-                throw new QuereusError(`Isolation layer: rebuilding the issuing connection's overlay for '${schemaName}.${tableName}' after `
-                    + `${ddlDescription} raised: ${e.message}. That DDL's validation pass already judged a superset of these `
-                    + `rows and accepted them, so validation and migration have drifted.`, StatusCode.INTERNAL, e);
-            }
-            // Poisoned: the OLD overlay stays installed under `key` (unmigrated, unreleased) so
-            // its owner errors and rolls back — do NOT release it here.
-            oldState.poison = { message: this.buildRebuildPoisonMessage(schemaName, tableName, ddlDescription, e.message) };
-            return;
-        }
-        // Rebuild succeeded: the NEW overlay replaces the OLD one under `key`, so the OLD
-        // staging table is abandoned — free it (leak sink). The builders already freed a
-        // HALF-built new overlay on their own throw path, so nothing is double-released.
-        this.connectionOverlays.set(key, rebuilt);
-        await this.releaseOverlayTable(oldState);
+    issuerOverlayDriftError(schemaName, tableName, ddlDescription, cause) {
+        return new QuereusError(`Isolation layer: applying ${ddlDescription} to the issuing connection's overlay for `
+            + `'${schemaName}.${tableName}' raised: ${cause.message}. That DDL's validation pass already judged a `
+            + `superset of these rows and accepted them, so validation and migration have drifted.`, StatusCode.INTERNAL, cause);
     }
     /**
-     * Builds the poison message stamped onto a foreign overlay whose staged rows cannot be
-     * migrated under a constraint another connection's DDL just declared (see
-     * {@link adoptRebuiltOverlay}). Companion to {@link buildAlterPoisonMessage}, which covers
-     * the `addColumn` NOT NULL backfill rejected before the underlying is touched; this one
-     * covers a UNIQUE (or any other) violation raised by the rebuild itself.
+     * Builds the poison message stamped onto a foreign overlay whose staged rows cannot adopt
+     * a constraint another connection's DDL just declared (see
+     * {@link applyInPlaceOverlayChange}). Companion to {@link buildAlterPoisonMessage}, which
+     * 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) {
         return `Another connection's ${ddlDescription} on '${schemaName}.${tableName}' declared a constraint this connection's `
@@ -896,9 +866,9 @@ export class IsolationModule {
         return this.effectiveRowsFor(db, underlyingTable, overlayState);
     }
     /**
-     * Creates an index on the underlying table, then rebuilds every per-connection overlay so
-     * the new index (and, for a UNIQUE index, the constraint derived from it) is enforced for
-     * the rest of each open transaction.
+     * Creates an index on the underlying table, then hands the same index to every
+     * per-connection overlay so it (and, for a UNIQUE index, the constraint derived from it)
+     * is enforced for the rest of each open transaction.
      *
      * Two things the underlying cannot do for itself:
      *
@@ -910,8 +880,8 @@ export class IsolationModule {
      * 2. **Enforce the new constraint.** An overlay built before the index knows nothing of it,
      *    and `IsolatedTable.findMergedUniqueConflict` only scans the underlying — so a pending
      *    row colliding with another pending row is nobody's job until the overlay itself carries
-     *    the index. Hence the rebuild, which is also what gives a merged secondary-index scan
-     *    later in the transaction an overlay that can serve it.
+     *    the index. Forwarding is also what gives a merged secondary-index scan later in the
+     *    transaction an overlay that can serve it.
      *
      * We use the stored table instance's createIndex() rather than the module-level method so
      * that the MemoryTable's local tableSchema property stays in sync. That property is what
@@ -930,12 +900,39 @@ export class IsolationModule {
             await this.underlying.createIndex(db, schemaName, tableName, indexSchema, rowSource);
         }
         else {
-            return; // underlying does not support indexes; nothing was created, nothing to rebuild
+            return; // underlying does not support indexes; nothing was created, nothing to forward
         }
         if (!state)
             return;
+        // 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);
-        await this.rebuildOverlaysForIndexChange(db, schemaName, tableName, updatedSchema, `create index '${indexSchema.name}'`);
+        const created = updatedSchema.indexes.find(idx => idx.name.toLowerCase() === indexSchema.name.toLowerCase());
+        await this.applyIndexChangeToOverlays(db, schemaName, tableName, `create index '${indexSchema.name}'`, overlayState => this.createOverlayIndex(overlayState, updatedSchema.name, created));
+    }
+    /**
+     * Adds one index to an already-open overlay, in the overlay's own flavor (predicate
+     * narrowed to live rows and rescoped onto the overlay's table name — see
+     * {@link createOverlayIndexSchema}).
+     *
+     * A UNIQUE index the overlay's staged rows violate raises `CONSTRAINT` out of
+     * `MemoryTableManager.createIndex`'s pre-validation pass, which
+     * {@link applyIndexChangeToOverlays} routes to INTERNAL (issuer) or poison (foreign).
+     * The pass runs before any mutation, so a rejected overlay is left exactly as it was.
+     *
+     * No-ops when the overlay module has no index support, or when the overlay already
+     * carries an index of that name (an overlay built after the underlying's create already
+     * copied it in through {@link createOverlaySchema}).
+     */
+    async createOverlayIndex(overlayState, baseName, indexSchema) {
+        const overlayTable = overlayState.overlayTable;
+        const overlaySchema = overlayTable.tableSchema;
+        if (!overlayTable.createIndex || !overlaySchema)
+            return;
+        if (this.schemaHasIndex(overlaySchema, indexSchema.name))
+            return;
+        await overlayTable.createIndex(this.createOverlayIndexSchema(indexSchema, baseName, overlaySchema.name));
     }
     /**
      * Reads back the underlying table instance's post-`createIndex` schema, asserting it now
@@ -949,7 +946,7 @@ export class IsolationModule {
      */
     assertIndexPresent(underlyingTable, schemaName, tableName, indexName) {
         const updatedSchema = underlyingTable.tableSchema;
-        const present = updatedSchema?.indexes?.some(idx => idx.name.toLowerCase() === indexName.toLowerCase());
+        const present = updatedSchema && this.schemaHasIndex(updatedSchema, indexName);
         if (!updatedSchema || !present) {
             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 `
@@ -957,26 +954,19 @@ export class IsolationModule {
         }
         return updatedSchema;
     }
+    /** Case-insensitive "does `schema` declare an index named `indexName`". */
+    schemaHasIndex(schema, indexName) {
+        const lower = indexName.toLowerCase();
+        return schema.indexes?.some(idx => idx.name.toLowerCase() === lower) ?? false;
+    }
     /**
-     * Drops an index on the underlying table.
+     * Drops an index on the underlying table, then drops it from every per-connection overlay.
      *
      * Mirrors createIndex: when the underlying VirtualTable exposes an
      * instance-level dropIndex (e.g. MemoryTable, which forwards to its manager
      * 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).
-     *
-     * Any per-connection overlay that already exists for this table is
-     * rebuilt under the post-drop schema, preserving staged rows. A bare
-     * forward to `overlay.dropIndex` is insufficient: when the overlay's
-     * MemoryTable has an active write `TransactionLayer`, its
-     * `tableSchemaAtCreation` is frozen at layer-creation time, so the
-     * synthesized UNIQUE constraint keeps firing inside the overlay's
-     * own UC check on the next write even after the manager's schema is
-     * refreshed. Rebuilding gives the new MemoryTable a fresh
-     * transaction layer that captures the post-drop schema. Overlays
-     * created AFTER this point inherit the post-drop schema from the
-     * underlying at ensureOverlay time.
      */
     async dropIndex(db, schemaName, tableName, indexName) {
         const state = this.getUnderlyingState(schemaName, tableName);
@@ -986,78 +976,114 @@ export class IsolationModule {
         else if (this.underlying.dropIndex) {
             await this.underlying.dropIndex(db, schemaName, tableName, indexName);
         }
-        // After the underlying drop, state.underlyingTable.tableSchema reflects the
-        // post-drop schema. Rebuild every affected overlay against that schema so
-        // the synthesized UC is fully gone from the overlay's transaction layer.
-        const updatedSchema = state?.underlyingTable.tableSchema;
-        if (!updatedSchema)
+        await this.applyIndexChangeToOverlays(db, schemaName, tableName, `drop index '${indexName}'`, overlayState => this.dropOverlayIndex(overlayState, indexName));
+    }
+    /**
+     * Drops one index (and the UNIQUE constraint derived from it) from an already-open
+     * overlay. No-ops when the overlay module has no index support, or when the overlay never
+     * carried the index.
+     */
+    async dropOverlayIndex(overlayState, indexName) {
+        const overlayTable = overlayState.overlayTable;
+        const overlaySchema = overlayTable.tableSchema;
+        if (!overlayTable.dropIndex || !overlaySchema)
             return;
-        await this.rebuildOverlaysForIndexChange(db, schemaName, tableName, updatedSchema, `drop index '${indexName}'`);
+        if (!this.schemaHasIndex(overlaySchema, indexName))
+            return;
+        await overlayTable.dropIndex(indexName);
     }
     /**
-     * Rebuilds every non-poisoned per-connection overlay of one table under a schema whose
-     * index / constraint set just changed (CREATE INDEX or DROP INDEX). Shared because the two
-     * directions differ only in which structures the new schema carries — the column layout is
-     * identical either way, so staged rows copy verbatim.
-     *
-     * A poisoned overlay (from a cross-connection ALTER, or a DROP TABLE) holds rows in the
-     * pre-alter column layout, narrower/wider than `updatedSchema`. Rebuilding it would copy
-     * layout-mismatched rows AND drop the poison flag (the new state carries none), silently
-     * un-poisoning a connection that must still roll back. Leave it as-is.
+     * Applies an index change (CREATE INDEX or DROP INDEX) IN PLACE to every non-poisoned
+     * per-connection overlay of one table.
+     *
+     * In place, not by rebuild. Both paths used to discard the overlay and copy its staged
+     * rows into a fresh `MemoryTable`, which silently destroyed the overlay's savepoint chain:
+     * the copy's first write lazily registers the new overlay's connection, and
+     * `Database.registerConnection` replays `begin()` plus the whole active savepoint stack
+     * BEFORE the copy runs — so every copied row landed ABOVE the replayed savepoint and the
+     * next `rollback to savepoint` discarded rows staged long before that savepoint was taken
+     * (`bug-isolation-index-ddl-rebuild-drops-savepoint-writes`).
+     *
+     * The rebuild was originally forced by a memory-module limitation — an open write
+     * `TransactionLayer` froze its schema at creation, so a bare `overlay.dropIndex` left the
+     * synthesized UNIQUE constraint firing inside the layer. `TransactionLayer.adoptSchema`
+     * now has both an additive and a removal branch, and `MemoryTableManager` calls it for
+     * both index directions, so an open layer adopts the change with its savepoint snapshots
+     * intact.
+     *
+     * CONSTRAINT is routed by who owns the overlay via {@link applyInPlaceOverlayChange},
+     * shared with every ALTER TABLE forward.
+     *
+     * A poisoned overlay is skipped: it holds rows in a pre-ALTER column layout and its owner
+     * must roll back regardless, so there is nothing to keep enforcing for it.
      */
-    async rebuildOverlaysForIndexChange(db, schemaName, tableName, updatedSchema, ddlDescription) {
+    async applyIndexChangeToOverlays(db, schemaName, tableName, ddlDescription, apply) {
         const ownKey = this.makeConnectionOverlayKey(db, schemaName, tableName);
         for (const key of this.connectionScopedKeys(this.connectionOverlays, schemaName, tableName)) {
             const overlayState = this.connectionOverlays.get(key);
             if (overlayState.poison)
                 continue;
-            await this.adoptRebuiltOverlay(key, overlayState, key === ownKey, schemaName, tableName, ddlDescription, () => this.rebuildOverlayForIndexChange(db, overlayState, updatedSchema));
+            await this.applyInPlaceOverlayChange(key === ownKey, overlayState, schemaName, tableName, ddlDescription, () => apply(overlayState));
         }
     }
     /**
-     * Rebuilds an overlay table under a post-CREATE/DROP-INDEX schema, preserving staged rows
-     * (including tombstones). Column layout is unchanged by either, so rows copy verbatim — but
-     * the new overlay's index/constraint set is not, so an insert here can legitimately raise
-     * UNIQUE (a foreign connection staged two rows the new index forbids).
+     * Applies one in-place DDL mutation to a single overlay, routing a CONSTRAINT failure
+     * by who owns the overlay: the issuer's own overlay → INTERNAL (its rows were already
+     * 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
+     * violation, not a data condition, and rethrows for everyone.
+     *
+     * Shared by the index paths ({@link applyIndexChangeToOverlays}) and the ALTER TABLE
+     * column-shape forwards ({@link alterTable}), so the two cannot drift on error routing.
      */
-    async rebuildOverlayForIndexChange(db, oldState, updatedSchema) {
-        const oldOverlay = oldState.overlayTable;
-        const newOverlaySchema = this.createOverlaySchema(updatedSchema);
-        const newOverlayTable = await this.overlayModule.create(db, newOverlaySchema);
-        const newState = { overlayTable: newOverlayTable, hasChanges: oldState.hasChanges, db };
+    async applyInPlaceOverlayChange(isIssuer, overlayState, schemaName, tableName, ddlDescription, apply) {
         try {
-            if (oldState.hasChanges && oldOverlay.query) {
-                for await (const oldRow of oldOverlay.query(makeFullScanFilterInfo())) {
-                    await this.insertIntoRebuiltOverlay(newOverlayTable, oldRow, updatedSchema.name);
-                }
-            }
+            await apply();
         }
         catch (e) {
-            // A mid-copy throw (e.g. a UNIQUE the new index forbids) abandons this freshly
-            // built overlay: adoptRebuiltOverlay keeps the OLD overlay installed on its throw
-            // path and never sees this handle, so free it here or it leaks.
-            await this.releaseOverlayTable(newState);
-            throw e;
+            if (!(e instanceof QuereusError) || e.code !== StatusCode.CONSTRAINT)
+                throw e;
+            if (isIssuer)
+                throw this.issuerOverlayDriftError(schemaName, tableName, ddlDescription, e);
+            overlayState.poison = { message: this.buildRebuildPoisonMessage(schemaName, tableName, ddlDescription, e.message) };
         }
-        return newState;
     }
     /**
-     * Delegates ALTER TABLE to the underlying module and migrates any per-connection
+     * Delegates ALTER TABLE to the underlying module and carries any per-connection
      * overlays to the post-alter schema without discarding staged rows.
      *
-     * ADD COLUMN  — appends the new column's value to each overlay row's data columns,
-     *               backfilled per row exactly as the committed path does (literal default,
-     *               per-row `new.<col>` evaluator, or NULL); tombstone rows get NULL.
-     * DROP COLUMN — removes the dropped column from each overlay row.
-     * RENAME / ALTER COLUMN — data column indices are unchanged; only schema metadata rotates.
+     * Every change type forwards to each overlay IN PLACE — 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}).
      *
      * **Atomicity guarantee.** DDL through Quereus is not transaction-scoped and the
      * underlying (shared, committed) base auto-commits its mutation immediately —
      * there is no frame to unwind, and `dropColumn` / type-converting `alterColumn`
      * are lossy and not invertible, so "revert the underlying on overlay-migration
      * failure" is not viable. Instead this method **pre-validates** every affected
-     * overlay's backfill (the per-row NOT NULL check and the tombstone-present guard)
-     * BEFORE calling `underlying.alterTable`. A rejection therefore fires while the
+     * overlay's migration (the per-row NOT NULL check, the per-value retype conversion, and
+     * the tombstone-present guard) BEFORE calling `underlying.alterTable`. A rejection therefore fires while the
      * underlying, the schema catalog, and every overlay are still untouched, so the
      * ALTER either fails clean or fully applies — base/catalog can no longer diverge.
      * This mirrors the engine's pre-mutation `validateNotNullBackfill` in
@@ -1098,16 +1124,20 @@ export class IsolationModule {
                 foreign.push([key, state]);
             }
         }
-        // Overlays we will actually migrate forward (issuer-own first). The shared
-        // dropColumn index is probed from one of these, never from a skipped poisoned
-        // overlay whose schema may be a stale pre-alter layout.
+        // Overlays we will actually migrate forward (issuer-own first). The setNotNull /
+        // setDataType contexts below are probed from one of these, never from a skipped
+        // poisoned overlay whose schema may be a stale pre-alter layout.
         const toMigrate = ownEntry ? [ownEntry, ...foreign] : foreign;
-        // For dropColumn we need the pre-alter column index, readable from any
-        // to-be-migrated overlay's schema.
-        let dropColumnIdx;
-        if (change.type === 'dropColumn' && toMigrate.length > 0) {
-            const overlaySchema = toMigrate[0][1].overlayTable.tableSchema;
-            dropColumnIdx = overlaySchema?.columnIndexMap.get(change.columnName.toLowerCase());
+        // 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 —
+        // 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).
+        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);
         }
         // Build the addColumn backfill context up front (undefined for other change types).
         // Derived purely from `change` + the session nullability option — no post-alter
@@ -1117,14 +1147,18 @@ export class IsolationModule {
         // 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, and the same source `dropColumnIdx` uses above.
-        const setNotNullCtx = this.deriveSetNotNullBackfill(change, toMigrate, tableName);
+        // 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);
         // Tier 2: validate the ISSUER's own overlay BEFORE mutating the shared underlying.
-        // Any throw here (CONSTRAINT backfill 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.
+        // 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);
+            await this.validateOverlayMigration(ownEntry[1], addColumnCtx, setNotNullCtx, setDataTypeCtx);
         }
         const underlyingState = this.getUnderlyingState(schemaName, tableName);
         // Hand the underlying the issuer's effective rows so its own row-content checks
@@ -1144,32 +1178,70 @@ 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.
+        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;
+                }
+            }
+        };
         // Migrate the issuer's own overlay (already validated above). Its NOT NULL /
         // tombstone throw sites are unreachable after pre-validation; so is a UNIQUE
-        // rejection, which `rowSource` already judged — {@link adoptRebuiltOverlay} raises
+        // rejection, which `rowSource` already judged — the CONSTRAINT routing raises
         // INTERNAL if one fires anyway rather than dropping the row.
         if (ownEntry) {
-            await this.adoptRebuiltOverlay(ownEntry[0], ownEntry[1], true, schemaName, tableName, ddlDescription, () => this.migrateOverlayForAlter(db, ownEntry[1], updated, change, dropColumnIdx, addColumnCtx, setNotNullCtx));
+            await migrateOverlay(ownEntry[0], ownEntry[1], true);
         }
         // Tier 3: per FOREIGN overlay, validate then migrate — but a per-row NOT NULL
         // (CONSTRAINT) failure poisons that one overlay instead of aborting the issuer's
         // ALTER, as does a UNIQUE the migration itself raises (its staged rows may violate a
-        // constraint the issuer just declared). An INTERNAL failure (e.g. missing tombstone
-        // column) is a layer-invariant violation, not a data condition, so it rethrows loud
-        // for everyone. Both phases run per overlay, so one bad foreign overlay poisons only
-        // itself; healthy peers still migrate.
+        // constraint the issuer just declared) and an unconvertible staged value under a retype
+        // (MISMATCH). Those three are data conditions of ONE connection's uncommitted rows, and
+        // the underlying has already been mutated by this point, so rethrowing any of them would
+        // abort the issuer's ALTER after the fact — exactly the divergence this tiering exists to
+        // prevent. An INTERNAL failure (e.g. missing tombstone column) is a layer-invariant
+        // violation, not a data condition, so it rethrows loud for everyone. Both phases run per
+        // 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);
+                await this.validateOverlayMigration(oldState, addColumnCtx, setNotNullCtx, setDataTypeCtx);
             }
             catch (e) {
-                if (e instanceof QuereusError && e.code === StatusCode.CONSTRAINT) {
+                if (e instanceof QuereusError && (e.code === StatusCode.CONSTRAINT || e.code === StatusCode.MISMATCH)) {
                     oldState.poison = { message: this.buildAlterPoisonMessage(schemaName, tableName, change) };
                     continue; // poisoned — do NOT migrate; leave pre-alter rows in place
                 }
                 throw e;
             }
-            await this.adoptRebuiltOverlay(key, oldState, false, schemaName, tableName, ddlDescription, () => this.migrateOverlayForAlter(db, oldState, updated, change, dropColumnIdx, addColumnCtx, setNotNullCtx));
+            await migrateOverlay(key, oldState, false);
         }
         return updated;
     }
@@ -1178,8 +1250,9 @@ export class IsolationModule {
      * 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) and the `set not null` tightening
-     * path (a staged NULL with no usable default); other change types never reach here but
+     * 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) {
@@ -1187,8 +1260,14 @@ export class IsolationModule {
             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.`;
     }
     /**
@@ -1307,48 +1386,11 @@ export class IsolationModule {
         }
         return oldKeys.length;
     }
-    /**
-     * Rebuilds an overlay table under the post-alter schema, translating each
-     * staged row to the new column layout.
-     *
-     * A row the post-alter schema's constraints reject throws CONSTRAINT out of
-     * {@link insertIntoRebuiltOverlay} rather than being silently discarded; the caller
-     * ({@link adoptRebuiltOverlay}) maps that to INTERNAL or poison.
-     */
-    async migrateOverlayForAlter(db, oldState, updatedSchema, change, dropColumnIdx, addColumnCtx, setNotNullCtx) {
-        const oldOverlay = oldState.overlayTable;
-        const oldOverlaySchema = oldOverlay.tableSchema;
-        const newOverlaySchema = this.createOverlaySchema(updatedSchema);
-        const newOverlayTable = await this.overlayModule.create(db, newOverlaySchema);
-        const newState = { overlayTable: newOverlayTable, hasChanges: oldState.hasChanges, db };
-        try {
-            if (oldState.hasChanges && oldOverlaySchema && oldOverlay.query) {
-                const oldTombstoneIdx = oldOverlaySchema.columnIndexMap.get(this.tombstoneColumn.toLowerCase());
-                if (oldTombstoneIdx === undefined) {
-                    throw new QuereusError(`Tombstone column '${this.tombstoneColumn}' missing from overlay schema`, StatusCode.INTERNAL);
-                }
-                // `addColumnCtx` (folded literal default, the per-row evaluator, and the new
-                // column's NOT NULL flag) was precomputed once per ALTER by the caller and already
-                // dry-run validated against these same staged rows; undefined for non-addColumn
-                // change types, which append nothing to staged rows.
-                for await (const oldRow of oldOverlay.query(makeFullScanFilterInfo())) {
-                    const addColumnValue = addColumnCtx
-                        ? await this.computeAddColumnValue(addColumnCtx, oldRow, oldTombstoneIdx)
-                        : undefined;
-                    const newRow = this.translateOverlayRow(oldRow, oldTombstoneIdx, change, dropColumnIdx, addColumnValue, setNotNullCtx);
-                    await this.insertIntoRebuiltOverlay(newOverlayTable, newRow, updatedSchema.name);
-                }
-            }
-        }
-        catch (e) {
-            // Any throw after create abandons this freshly built overlay (adoptRebuiltOverlay
-            // keeps the OLD one installed on its throw path and never holds this handle), so
-            // free it here or it leaks.
-            await this.releaseOverlayTable(newState);
-            throw e;
-        }
-        return newState;
-    }
+    // 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`
@@ -1393,12 +1435,12 @@ export class IsolationModule {
      * 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 source `dropColumnIdx`
-     * uses, and the same layout every migrated overlay shares). Folded exactly as
+     * 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, tableName) {
+    deriveSetNotNullBackfill(change, toMigrate) {
         if (change.type !== 'alterColumn' || change.setNotNull !== true)
             return undefined;
         if (toMigrate.length === 0)
@@ -1419,7 +1461,54 @@ export class IsolationModule {
             foldedDefault: hasDefault ? folded : null,
             hasDefault,
             colName: change.columnName,
-            tableName,
+        };
+    }
+    /**
+     * 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);
+                }
+            },
         };
     }
     /**
@@ -1439,14 +1528,22 @@ export class IsolationModule {
      * 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 translateOverlayRow},
-     * so nothing is rejected here.
-     *
-     * Non-addColumn / non-tightening changes (`addColumnCtx === undefined` and no reject-mode
-     * `setNotNullCtx`) only run the tombstone guard; their row translation appends/removes nothing
-     * fallible on data grounds.
+     * 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) {
+    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
@@ -1464,16 +1561,35 @@ export class IsolationModule {
             }
             return;
         }
-        // SET NOT NULL with no usable DEFAULT: reject a staged NULL the migration could not fill.
-        // (With a DEFAULT there is nothing to reject — translateOverlayRow backfills instead.)
+        // 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 oldOverlay.query(makeFullScanFilterInfo())) {
-                if (oldRow[oldTombstoneIdx] === 1)
-                    continue; // tombstone: placeholder NULLs, not a row
+            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;
         }
     }
     /**
@@ -1503,63 +1619,295 @@ export class IsolationModule {
         return ctx.foldedDefault;
     }
     /**
-     * Translates a single overlay row from the pre-alter to the post-alter column layout.
-     * The tombstone value is preserved in the last position.
-     *
-     * `addColumnValue` is the per-row value the caller computed for an `addColumn`
-     * (via {@link computeAddColumnValue}); it is `undefined` for every other change
-     * type. Keeping the (async) backfill in the caller's loop lets this stay synchronous.
-     *
-     * `setNotNullCtx` (present only for a `set not null` tightening WITH a usable DEFAULT) maps a
-     * staged NULL at the now-NOT-NULL column to that DEFAULT — filling the issuer's own pending
-     * rows, which the underlying's committed-row backfill never touches. Reject-mode contexts (no
-     * DEFAULT) never reach here: {@link validateOverlayMigration} aborts/poisons first.
-     */
-    translateOverlayRow(oldRow, oldTombstoneIdx, change, dropColumnIdx, addColumnValue, setNotNullCtx) {
-        const tombstoneValue = oldRow[oldTombstoneIdx];
-        const data = Array.from(oldRow.slice(0, oldTombstoneIdx));
-        let newData;
-        switch (change.type) {
-            case 'addColumn':
-                // New column is always appended after existing data columns, backfilled per
-                // row by the caller (literal default, per-row evaluator, or NULL).
-                newData = [...data, addColumnValue ?? null];
-                break;
-            case 'dropColumn':
-                newData = dropColumnIdx !== undefined
-                    ? [...data.slice(0, dropColumnIdx), ...data.slice(dropColumnIdx + 1)]
-                    : data;
-                break;
-            case 'alterColumn':
-                // SET NOT NULL backfill (WITH a usable DEFAULT): fill a staged NULL at the
-                // now-NOT-NULL column. Tombstones carry placeholder NULLs never read, so leave them.
-                // Every other alterColumn attribute (and the no-DEFAULT reject case) leaves data as-is.
-                // NOTE: SET DATA TYPE also alters existing values but is NOT converted here — its
-                // overlay gap is deferred (see SetNotNullBackfillContext doc).
-                newData = (setNotNullCtx && tombstoneValue !== 1)
-                    ? data.map((v, i) => (i === setNotNullCtx.colIndex && v === null ? setNotNullCtx.foldedDefault : v))
-                    : data;
-                break;
-            case 'renameColumn':
-            case 'alterPrimaryKey':
-            case 'addConstraint':
-            case 'dropConstraint':
-            case 'renameConstraint':
-                newData = data;
-                break;
-            default: {
-                const _exhaustive = change;
-                newData = data;
+     * 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
+     * row it deletes BY that key — under a new key a tombstone's identity columns may be
+     * placeholder NULLs, i.e. garbage. So:
+     *
+     * - An overlay WITH staged rows is either the ISSUER's — unreachable, {@link alterTable}
+     *   rejected it before the underlying mutated, so assert INTERNAL — or FOREIGN, which is
+     *   poisoned exactly like a foreign overlay whose staged values a retype cannot convert.
+     * - A CLEAN overlay stages nothing; it is swapped for a fresh empty staging table built
+     *   from the post-alter schema, so later writes in this transaction key by the new primary
+     *   key. The fresh table's connection registers lazily at its first write, replaying the
+     *   active savepoint stack — correct for a table with no pre-existing staged rows (the
+     *   replay hazard is only ever about rows copied beneath it, and there are none).
+     */
+    async replaceOverlayForPrimaryKeyChange(key, state, isIssuer, schemaName, tableName, updatedSchema, change) {
+        if (state.hasChanges) {
+            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) };
+            return;
         }
-        return [...newData, tombstoneValue];
+        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);
     }
     /**
      * Creates overlay schema from underlying schema.
      * Adds tombstone column and uses unique name to avoid conflicts.
      *
-     * Called by IsolatedTable when lazily creating its overlay, and by the two overlay-rebuild
-     * paths (`rebuildOverlayForIndexChange`, `migrateOverlayForAlter`).
+     * Called by IsolatedTable when lazily creating its overlay, and by the ALTER PRIMARY KEY
+     * clean-overlay swap (`replaceOverlayForPrimaryKeyChange`). Index DDL and every other ALTER
+     * adopt in place — a new UNIQUE arrives through {@link createOverlayIndexSchema} /
+     * {@link overlayPredicate}, which this method shares.
      *
      * Every copied secondary index — and every copied UNIQUE constraint, including the ones
      * a UNIQUE index derives — is narrowed to a PARTIAL structure over live rows only
@@ -1594,25 +1942,48 @@ export class IsolationModule {
         // Use unique ID to avoid conflicts when multiple overlays exist
         const overlayId = generateOverlayId();
         const overlayName = `_overlay_${baseSchema.name}_${overlayId}`;
-        const liveOnly = this.liveRowPredicate();
-        // A partial-index / UNIQUE predicate copied from the base carries a self-qualifier
-        // bound to the base table's name (e.g. `where t.v > 0`). The overlay renames the table
-        // to `overlayName`, so that qualifier now names a DIFFERENT table than the overlay's
-        // MemoryIndex is scoped to — and `compilePredicate` rejects a foreign qualifier at
-        // index-build time (see partial-index-predicate table-qualifier rejection). Rescope the
-        // 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.
-        const rescope = (p) => p ? rescopePredicateQualifier(p, baseSchema.name, overlayName) : undefined;
         return {
             ...baseSchema,
             name: overlayName,
             columns: newColumns,
             columnIndexMap: newColumnIndexMap,
-            indexes: baseSchema.indexes?.map(idx => ({ ...idx, predicate: andPredicate(rescope(idx.predicate), liveOnly) })),
-            uniqueConstraints: baseSchema.uniqueConstraints?.map(uc => ({ ...uc, predicate: andPredicate(rescope(uc.predicate), liveOnly) })),
+            indexes: baseSchema.indexes?.map(idx => this.createOverlayIndexSchema(idx, baseSchema.name, overlayName)),
+            uniqueConstraints: baseSchema.uniqueConstraints?.map(uc => ({
+                ...uc,
+                predicate: this.overlayPredicate(uc.predicate, baseSchema.name, overlayName),
+            })),
         };
     }
+    /**
+     * The overlay-flavored form of one base `IndexSchema`: same name and columns, predicate
+     * narrowed to live rows and rescoped onto the overlay's table name (see
+     * {@link overlayPredicate}).
+     *
+     * Shared by {@link createOverlaySchema}, which maps the whole index set when an overlay is
+     * first created, and {@link createIndex}, which hands a single index to an overlay that is
+     * already open — so both produce structurally identical entries, and the UNIQUE constraint
+     * `MemoryTableManager.createIndex` synthesizes from a unique index inherits the same
+     * predicate either way.
+     */
+    createOverlayIndexSchema(idx, baseName, overlayName) {
+        return { ...idx, predicate: this.overlayPredicate(idx.predicate, baseName, overlayName) };
+    }
+    /**
+     * `<base predicate, rescoped to the overlay> AND <tombstone> = 0`.
+     *
+     * A partial-index / UNIQUE predicate copied from the base carries a self-qualifier bound to
+     * the base table's name (e.g. `where t.v > 0`). The overlay renames the table to
+     * `overlayName`, so that qualifier now names a DIFFERENT table than the overlay's
+     * MemoryIndex is scoped to — and `compilePredicate` rejects a foreign qualifier at
+     * index-build time (see partial-index-predicate table-qualifier rejection). Rescope the
+     * 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.
+     */
+    overlayPredicate(base, baseName, overlayName) {
+        const rescoped = base ? rescopePredicateQualifier(base, baseName, overlayName) : undefined;
+        return andPredicate(rescoped, this.liveRowPredicate());
+    }
     /**
      * `<tombstoneColumn> = 0` — the partial-structure predicate that scopes an overlay index
      * or UNIQUE constraint to live rows. Built as an AST rather than parsed from text because