@quereus/isolation 4.4.0 → 4.5.0

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, validateCollationForType, formatKeyValue } from '@quereus/quereus';
 import { IsolatedTable } from './isolated-table.js';
 import { applyOverlayToUnderlying } from './flush.js';
 import { makeFullScanFilterInfo } from './filter-info.js';
@@ -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,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,72 +770,28 @@ 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) {
+    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.`;
     }
@@ -896,9 +867,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 +881,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,35 +901,71 @@ 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;
-        const updatedSchema = this.assertIndexPresent(state.underlyingTable, schemaName, tableName, indexSchema.name);
-        await this.rebuildOverlaysForIndexChange(db, schemaName, tableName, updatedSchema, `create index '${indexSchema.name}'`);
+        // 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 { 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));
+    }
+    /**
+     * 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
-     * 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?.indexes?.some(idx => idx.name.toLowerCase() === indexName.toLowerCase());
-        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 };
+    }
+    /** `schema`'s index named `indexName` (case-insensitively), if it declares one. */
+    findSchemaIndex(schema, indexName) {
+        const lower = indexName.toLowerCase();
+        return schema.indexes?.find(idx => idx.name.toLowerCase() === lower);
+    }
+    /** Case-insensitive "does `schema` declare an index named `indexName`". */
+    schemaHasIndex(schema, indexName) {
+        return this.findSchemaIndex(schema, indexName) !== undefined;
     }
     /**
-     * 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
@@ -966,17 +973,10 @@ export class IsolationModule {
      * 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.
+     * 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);
@@ -986,78 +986,133 @@ 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)
+        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));
+    }
+    /**
+     * 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;
+        if (!this.schemaHasIndex(overlaySchema, indexName))
             return;
-        await this.rebuildOverlaysForIndexChange(db, schemaName, tableName, updatedSchema, `drop index '${indexName}'`);
+        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 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
+     * 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;
+            // 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) {
+                // 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.buildInPlaceAdoptPoisonMessage(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 through the overlay's `alterSchema` (the overlay module
+     *   converts / re-keys its open layers itself), with one preparation step: a `set collate`
+     *   that re-keys the PRIMARY KEY first discards any deletion markers the new key collapses
+     *   onto another staged row ({@link dropCollapsedPkRekeyMarkers}). `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,17 +1153,22 @@ 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);
         }
+        this.assertColumnNameNotTombstone(schemaName, tableName, change);
         // 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
@@ -1117,24 +1177,82 @@ 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);
+        // Build the primary-key re-key context (undefined unless this is a collation change on a
+        // PK member with overlays to carry). Read from the same PRE-alter overlay schema as above.
+        const pkRekeyCtx = this.derivePkRekey(change, db, tableName, 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, pkRekeyCtx);
         }
         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 (pkRekeyCtx && ownEntry && ownEntry[1].hasChanges && ownEntry[1].overlayTable.alterSchema) {
+            const ownOverlayState = ownEntry[1];
+            const plan = await this.planPkRekeyMarkerDrops(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 this.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 this.reinsertPkRekeyMarkers(ownOverlayState, droppedMarkerRows);
+                throw e;
+            }
+        }
+        let updated;
+        try {
+            updated = await this.underlying.alterTable(db, schemaName, tableName, change, rowSource);
+        }
+        catch (e) {
+            if (ownEntry)
+                await this.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
@@ -1144,51 +1262,126 @@ 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, pkRekeyCtx));
+                    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, pkRekeyCtx);
             }
             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;
     }
+    /**
+     * Rejects an ADD / RENAME COLUMN that would give a base column the same name as the
+     * overlay's private tombstone flag, BEFORE `underlying.alterTable` runs.
+     *
+     * Every overlay carries one extra column named {@link tombstoneColumn}, so a base column
+     * of that name collides with it. Forwarding the change to an open overlay makes the
+     * overlay module raise a duplicate-name `ERROR`, which is not a data condition and so
+     * rethrows out of {@link applyInPlaceOverlayChange} — after the underlying has already
+     * (irreversibly) applied. The catalog then keeps the pre-alter column set while the base
+     * holds the new one, and the next write to the table lands values against the wrong
+     * columns. Rejecting up front keeps the atomic-abort guarantee this method documents.
+     *
+     * NOTE: the check is unconditional — not gated on an overlay existing — so the answer
+     * does not depend on whether some connection happens to have a transaction open. That
+     * also stops a table from acquiring the colliding name while idle and hitting
+     * {@link createOverlaySchema}'s (silent) duplicate at the next BEGIN. A CREATE TABLE
+     * declaring the name still gets that duplicate — tracked separately.
+     */
+    assertColumnNameNotTombstone(schemaName, tableName, change) {
+        const newName = change.type === 'addColumn' ? change.columnDef.name
+            : change.type === 'renameColumn' ? change.newName
+                : undefined;
+        if (newName?.toLowerCase() !== this.tombstoneColumn.toLowerCase())
+            return;
+        throw new QuereusError(`Cannot name a column of '${schemaName}.${tableName}' '${newName}': the transaction-isolation layer reserves that name for its per-connection overlay's deletion marker.`, StatusCode.UNSUPPORTED);
+    }
     /**
      * 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) and the `set not null` tightening
-     * path (a staged NULL with no usable default); other change types never reach here but
-     * are handled defensively.
+     * path (a new NOT-NULL column with no usable default), the `set not null` tightening
+     * path (a staged NULL with no usable default), the `set data type` path (a staged value
+     * that cannot be converted to the new type), and the primary-key `set collate` path (two
+     * staged live rows colliding under the new collation); 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.`;
+            }
+            if (change.setCollation !== undefined) {
+                return `ALTER on '${schemaName}.${tableName}' changed the collation of primary-key column '${change.columnName}', under which this connection's uncommitted rows collide; 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 +1500,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 +1549,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,9 +1575,126 @@ export class IsolationModule {
             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);
+                }
+            },
+        };
+    }
+    /**
+     * Precomputes the per-ALTER constants a primary-key re-keying `alter column … set collate`
+     * overlay migration needs: the PK column positions and a key serializer built over the
+     * POST-change collation — the PRE-alter overlay schema with the named column's collation
+     * replaced. The overlay's PK definition mirrors the base's (the tombstone flag is appended
+     * after the data columns), so the synthesized schema keys exactly as the re-keyed base will.
+     *
+     * Returns undefined unless the named column is a PRIMARY KEY member and the normalized
+     * collation actually differs from the column's current one — mirroring the underlying's
+     * metadata-only gate (`MemoryTableManager.alterColumn`'s `nameMatches`), so overlay and
+     * committed rows re-key together or not at all. `validateCollationForType` can throw for an
+     * unknown collation, but the engine already validated the name before dispatching the ALTER,
+     * and a direct module caller gets the same pre-mutation rejection the underlying would give.
+     */
+    derivePkRekey(change, db, tableName, toMigrate) {
+        if (change.type !== 'alterColumn' || change.setCollation === 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;
+        if (!overlaySchema.primaryKeyDefinition.some(def => def.index === colIndex))
+            return undefined;
+        const oldCol = overlaySchema.columns[colIndex];
+        if (!oldCol)
+            return undefined;
+        const normalized = validateCollationForType(change.setCollation, oldCol.logicalType, change.columnName, (n) => db.isCollationRegistered(n));
+        if (normalized === (oldCol.collation || 'BINARY'))
+            return undefined; // metadata-only — the underlying re-keys nothing
+        const postChangeSchema = {
+            ...overlaySchema,
+            columns: overlaySchema.columns.map((c, i) => (i === colIndex ? { ...c, collation: normalized } : c)),
+        };
+        return {
+            pkIndices: overlaySchema.primaryKeyDefinition.map(def => def.index),
+            keyOf: makePkKeySerializer(db, postChangeSchema),
             tableName,
         };
     }
+    /**
+     * Buckets an overlay's staged rows by their PRIMARY KEY as the pending `set collate` will
+     * re-key it: one {@link PkRekeyGroup} per post-change key. Shared by the validation dry run
+     * (which refuses a group holding two live rows) and the migrate-step marker drop (which
+     * discards collapsed markers), so the two passes cannot disagree about what collapses.
+     *
+     * NOTE: materializes one serialized key + one PK tuple per staged row (plus the marker rows
+     * themselves), once per pass of one ALTER. If an overlay with very many staged rows ever
+     * makes this ALTER slow, group lazily or reuse the merge `effectiveRowsFor` already builds.
+     */
+    async collectPkRekeyGroups(overlay, tombstoneIdx, ctx) {
+        const groups = new Map();
+        for await (const row of overlay.query(makeFullScanFilterInfo())) {
+            const pk = ctx.pkIndices.map(i => row[i]);
+            const key = ctx.keyOf(pk);
+            let group = groups.get(key);
+            if (!group) {
+                group = { livePks: [], markerRows: [] };
+                groups.set(key, group);
+            }
+            if (row[tombstoneIdx] === 1)
+                group.markerRows.push(row);
+            else
+                group.livePks.push(pk);
+        }
+        return groups;
+    }
     /**
      * 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
@@ -1439,24 +1712,38 @@ 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.
+     *
+     * For a primary-key re-keying `set collate` (`pkRekeyCtx`), the staged rows are grouped by
+     * their POST-change key: a deletion marker sharing a key with one live row is that row's
+     * before-image (the migrate step discards it — {@link dropCollapsedPkRekeyMarkers}), and
+     * markers alone on one key are one deletion — neither is a duplicate. Two LIVE rows on one
+     * key ARE, so that throws CONSTRAINT here, mirroring the underlying's own collision message.
+     * For the ISSUER this is belt-and-braces (the underlying's pre-mutation pass judges the same
+     * staged rows via {@link issuerEffectiveRows}, though this check fires first); for a FOREIGN
+     * overlay it is the only pass that sees those rows, and its throw becomes poison.
+     *
+     * Non-addColumn / non-tightening / non-retype / non-re-key changes (`addColumnCtx ===
+     * undefined`, no reject-mode `setNotNullCtx`, no `setDataTypeCtx`, no `pkRekeyCtx`) 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, pkRekeyCtx) {
         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);
-        }
+        const oldTombstoneIdx = this.requireTombstoneIndex(oldOverlaySchema);
         if (addColumnCtx) {
             for await (const oldRow of oldOverlay.query(makeFullScanFilterInfo())) {
                 // Discard the result — this is validation only. A NOT NULL violation throws here.
@@ -1464,16 +1751,48 @@ 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
+            }
+            return;
+        }
+        // SET COLLATE re-keying the PRIMARY KEY: two staged LIVE rows landing on one post-change
+        // key are a real duplicate — refuse before the underlying re-keys (atomic for the issuer,
+        // poison for a foreign overlay via the caller). Marker/live and marker/marker groups
+        // collapse cleanly and are handled by the migrate step, not rejected here.
+        if (pkRekeyCtx) {
+            for (const group of (await this.collectPkRekeyGroups(oldOverlay, oldTombstoneIdx, pkRekeyCtx)).values()) {
+                if (group.livePks.length < 2)
+                    continue;
+                const keyDesc = group.livePks[1].map(formatKeyValue).join(', ');
+                throw new QuereusError(`UNIQUE constraint failed: ${pkRekeyCtx.tableName} primary key collides under new collation (key: ${keyDesc})`, StatusCode.CONSTRAINT);
+            }
+        }
+    }
+    /**
+     * 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 +1822,427 @@ 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.
+     *   A caller that named its own position keeps it: the overlay's data columns mirror
+     *   the base's one-for-one below the flag, so the base's index is the overlay's too.
+     *   (SQL always appends, so today the caller never names one — but silently ignoring
+     *   it would diverge the two layouts.)
+     * - 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: change.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. One preparation
+     * step precedes a PRIMARY-KEY re-keying `set collate` (`pkRekeyCtx`): deletion markers the
+     * re-key collapses onto another staged row are discarded first
+     * ({@link dropCollapsedPkRekeyMarkers}) — the overlay's PK deliberately covers markers, so
+     * without the drop its own `alterSchema` would reject the collapsed pair as a PK collision.
+     *
+     * Neither NOT NULL direction forwards, and the overlay's `notNull` flag is left where it
+     * stood when the overlay was created:
+     *
+     * - **Tightening (`set not null`).** Forwarding would have the overlay module tighten a
+     *   column whose tombstone rows carry NULL at every non-PK data column, so it would either
+     *   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}.
+     * - **Relaxing (`drop not null`).** Nothing to do: the overlay never enforced the flag, and
+     *   the rows it stages are written with `preCoerced: true` through the overlay module's own
+     *   write path, which does not consult column nullability at all.
+     *
+     * NOTE: both directions therefore leave the overlay's `notNull` flag drifted from the base
+     * for the rest of the transaction. Inert today — nothing on the overlay path reads it. The
+     * one consumer that would, `MemoryTableModule.getBestAccessPlan` (which prunes `IS NULL` on
+     * a NOT NULL column to an empty result), is unreachable because the isolation layer builds
+     * the overlay's `FilterInfo` itself (see `filter-info.ts`) instead of planning against the
+     * overlay module. If overlay scans ever route through the overlay module's planner hook, or
+     * its write path starts enforcing nullability, this has to become a real forward that
+     * excludes tombstones.
+     *
+     * 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, pkRekeyCtx) {
+        if (change.setNotNull !== undefined) {
+            if (change.setNotNull === true && setNotNullCtx?.hasDefault) {
+                await this.backfillStagedNotNull(overlayState, setNotNullCtx);
             }
+            return;
         }
-        return [...newData, tombstoneValue];
+        if (!overlayState.overlayTable.alterSchema)
+            return;
+        if (pkRekeyCtx)
+            await this.dropCollapsedPkRekeyMarkers(overlayState, pkRekeyCtx);
+        await overlayState.overlayTable.alterSchema(change);
+    }
+    /**
+     * Discards the deletion markers a pending PRIMARY-KEY re-key collapses onto another staged
+     * row, through the overlay's ordinary write path so its layer chain and savepoint snapshots
+     * stay intact. Two shapes collapse (see {@link PkRekeyContext}): a marker sharing its
+     * post-change key with a live row is that row's before-image — the live row's flush upsert
+     * is the complete net effect, so the marker is dropped; markers alone together on one key
+     * are one deletion, so all but the first are dropped. A group holding two live rows was
+     * already refused by {@link validateOverlayMigration} before the underlying mutated.
+     *
+     * Runs BEFORE the re-key is forwarded to the overlay, and deletes by each marker's OLD
+     * primary key — the overlay is still keyed under the old collation at that moment.
+     *
+     * NOTE: like {@link backfillStagedNotNull}'s rewrites, the drops land in the overlay's
+     * CURRENT savepoint frame. A later `rollback to savepoint` taken BEFORE this ALTER restores
+     * the marker while the table stays re-keyed — the same divergence class that method's NOTE
+     * documents (`bug-rolled-back-rows-violate-surviving-ddl`), not a new hole opened here.
+     */
+    async dropCollapsedPkRekeyMarkers(overlayState, ctx) {
+        const plan = await this.planPkRekeyMarkerDrops(overlayState, ctx);
+        await this.applyPkRekeyMarkerDrops(overlayState, ctx, plan);
+    }
+    /**
+     * The whole overlay rows of every deletion marker {@link dropCollapsedPkRekeyMarkers} will
+     * discard, computed without mutating anything. Re-planning after the drops finds nothing
+     * (each group then holds at most one marker and no marker beside a live row), so the
+     * issuer path — which drops in tier 2 for the pre-flight — can safely run the shared
+     * migrate-step drop again as a no-op.
+     */
+    async planPkRekeyMarkerDrops(overlayState, ctx) {
+        const overlay = overlayState.overlayTable;
+        const overlaySchema = overlay.tableSchema;
+        if (!overlaySchema || !overlay.query)
+            return [];
+        const tombstoneIdx = this.requireTombstoneIndex(overlaySchema);
+        const toDrop = [];
+        for (const group of (await this.collectPkRekeyGroups(overlay, tombstoneIdx, ctx)).values()) {
+            // NOTE: the marker-only arm (`slice(1)`) is defensive — no marker-only collapse can
+            // currently SURVIVE the ALTER. Two markers share a post-change key only if the rows
+            // they shadow did too, and such a pair is refused one level down: by the underlying's
+            // re-key (a committed pair) or by the overlay's own (a staged-then-deleted pair). It
+            // still runs, and is still undone, on the way to those refusals.
+            toDrop.push(...(group.livePks.length > 0 ? group.markerRows : group.markerRows.slice(1)));
+        }
+        return toDrop;
+    }
+    /** Deletes each planned marker by its OLD primary key through the overlay's ordinary write path. */
+    async applyPkRekeyMarkerDrops(overlayState, ctx, toDrop) {
+        const overlay = overlayState.overlayTable;
+        const overlaySchema = overlay.tableSchema;
+        if (!overlaySchema || toDrop.length === 0)
+            return;
+        for (const markerRow of toDrop) {
+            const pk = ctx.pkIndices.map(i => markerRow[i]);
+            const result = await overlay.update({
+                operation: 'delete',
+                values: undefined,
+                oldKeyValues: pk,
+            });
+            // A bare delete of a staged marker has no data condition to hit, so a non-ok result
+            // is a layer-invariant violation — raise INTERNAL (which applyInPlaceOverlayChange
+            // rethrows loud for issuer and foreign alike), never poison.
+            if (isConstraintViolation(result)) {
+                throw new QuereusError(`Dropping a collapsed deletion marker (pk=[${pk.join(', ')}]) from overlay '${overlaySchema.name}' hit a ${result.constraint} constraint: ${result.message ?? 'no message'}`, StatusCode.INTERNAL);
+            }
+        }
+    }
+    /**
+     * Undoes {@link applyPkRekeyMarkerDrops} after a refusal that aborts the whole ALTER —
+     * the overlay pre-flight's or the underlying's (see the tier-2 re-key block in
+     * {@link alterTable}). Reinserts each marker row verbatim: a marker minted for a committed
+     * row carries NULL at every non-key data column, but one made by deleting a row this
+     * transaction had already staged keeps that row's values (the convert-to-tombstone branch
+     * of `IsolatedTable.update`), so a reconstructed-from-PK row would not restore what was
+     * dropped. The reinserts land in the same savepoint frame the drops did, so the pair nets
+     * to nothing.
+     */
+    async reinsertPkRekeyMarkers(overlayState, droppedRows) {
+        if (droppedRows.length === 0)
+            return;
+        const overlay = overlayState.overlayTable;
+        const overlaySchema = overlay.tableSchema;
+        if (!overlaySchema)
+            return;
+        for (const markerRow of droppedRows) {
+            const result = await overlay.update({ operation: 'insert', values: [...markerRow] });
+            if (isConstraintViolation(result)) {
+                throw new QuereusError(`Restoring a deletion marker (row=[${markerRow.join(', ')}]) to overlay '${overlaySchema.name}' after a refused ALTER hit a ${result.constraint} constraint: ${result.message ?? 'no message'}`, StatusCode.INTERNAL);
+            }
+        }
+    }
+    /** The overlay's tombstone-flag column index, or INTERNAL if the schema lost it. */
+    requireTombstoneIndex(overlaySchema) {
+        const tombstoneIdx = overlaySchema.columnIndexMap.get(this.tombstoneColumn.toLowerCase());
+        if (tombstoneIdx === undefined) {
+            throw new QuereusError(`Tombstone column '${this.tombstoneColumn}' missing from overlay schema`, StatusCode.INTERNAL);
+        }
+        return tombstoneIdx;
+    }
+    /**
+     * 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;
+        }
+        // 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);
     }
     /**
      * 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
@@ -1573,6 +2256,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 = {
@@ -1594,25 +2287,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