@quereus/isolation 4.3.1 → 4.4.0

package/dist/src/isolation-module.js

@@ -1,5 +1,8 @@
-import { MemoryTableModule, PhysicalType, QuereusError, StatusCode, tryFoldLiteral, columnDefToSchema } from '@quereus/quereus';
+import { MemoryTableModule, PhysicalType, QuereusError, StatusCode, tryFoldLiteral, columnDefToSchema, isConstraintViolation } from '@quereus/quereus';
 import { IsolatedTable } from './isolated-table.js';
+import { applyOverlayToUnderlying } from './flush.js';
+import { makeFullScanFilterInfo } from './filter-info.js';
+import { iterateEffectiveRows, makePkKeySerializer } from './overlay-rows.js';
 let overlayIdCounter = 0;
 /**
  * Generates a unique overlay ID for each overlay table instance.
@@ -54,7 +57,10 @@ export function clampToReentrantReads(mode) {
  *
  * This provides ACID semantics including:
  * - Read-your-own-writes within a transaction
- * - Snapshot isolation (reads see consistent state)
+ * - Read-committed reads of shared state (the underlying table is live and shared
+ *   across connections — this is NOT snapshot isolation; another connection's commit
+ *   can become visible mid-transaction, and there is no write-write conflict
+ *   detection). A stable snapshot, if needed, is the underlying module's job.
  * - Savepoint support via overlay module's transaction support
  */
 export class IsolationModule {
@@ -155,7 +161,7 @@ export class IsolationModule {
                 const underlyingTable = await underlyingCreateBacking.call(this.underlying, db, tableSchema);
                 const state = { underlyingTable };
                 this.setUnderlyingState(tableSchema.schemaName, tableSchema.name, state);
-                return new IsolatedTable(db, this, underlyingTable);
+                return new IsolatedTable(db, this, tableSchema.schemaName, tableSchema.name, underlyingTable);
             };
         }
         // The attach seams swap the underlying storage flavor in place (ordinary ⇄
@@ -168,6 +174,14 @@ export class IsolationModule {
         // from the underlying. Evict only on success: a thrown attach leaves the
         // prior flavor (and its still-valid cache) intact, and the failure-cleanup
         // path is `discardBackingForAttach`, which evicts in its own right.
+        //
+        // NOTE: these three seams evict `underlyingTables` without touching
+        // `connectionOverlays`, unlike `destroy()`. That is safe only because writes to a
+        // materialized-view backing table are privileged and bypass the overlay, so no
+        // overlay is ever staged against a table that crosses a seam. If a seam ever runs
+        // on a table an open transaction has staged writes for, `commitConnectionOverlays`
+        // will raise its INTERNAL invariant error — give the seams the same overlay sweep
+        // `destroy()` performs.
         const underlyingEnsure = this.underlying.ensureBackingForAttach;
         if (underlyingEnsure) {
             this.ensureBackingForAttach = async (db, schemaName, tableName, backingSchema) => {
@@ -267,11 +281,40 @@ export class IsolationModule {
         this.connectionOverlays.set(key, state);
     }
     /**
-     * Removes the overlay state for a specific connection and table.
-     * Called after commit/rollback to clean up.
+     * Frees the in-memory staging (overlay) table backing `state` by calling the overlay
+     * module's `destroy`, so its manager entry (and the rows it holds) is removed from the
+     * 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.
+     *
+     * `MemoryTableManager.destroy` rolls back the overlay's own pending layer and clears its
+     * connections; a later db-side teardown of the (now-detached) `MemoryVirtualTableConnection`
+     * is tolerated by `MemoryTableManager.disconnect` (`!connection` → no-op), so destroying
+     * here mid-commit/rollback does not throw when the connection is torn down afterwards.
+     *
+     * Defensive on a missing schema: real overlays always carry one (`createOverlaySchema`),
+     * so a schemaless state can only be a malformed/test-fabricated one — skip rather than throw.
+     */
+    async releaseOverlayTable(state) {
+        const overlaySchema = state.overlayTable.tableSchema;
+        if (!overlaySchema)
+            return;
+        await this.overlayModule.destroy(state.db, undefined, overlaySchema.vtabModuleName, overlaySchema.schemaName, overlaySchema.name);
+    }
+    /**
+     * Removes the overlay state for a specific connection and table, first releasing its
+     * staging table so it does not leak (see {@link releaseOverlayTable}). Async because the
+     * release drives the overlay module's `destroy`; all callers (`clearOverlay`, `alterSchema`)
+     * are already async and `await` it. Called on the rollback / alter-schema / rollback-to-
+     * pre-overlay-savepoint discard paths.
      */
-    clearConnectionOverlay(db, schemaName, tableName) {
+    async clearConnectionOverlay(db, schemaName, tableName) {
         const key = this.makeConnectionOverlayKey(db, schemaName, tableName);
+        const state = this.connectionOverlays.get(key);
+        if (!state)
+            return;
+        await this.releaseOverlayTable(state);
         this.connectionOverlays.delete(key);
     }
     /**
@@ -293,6 +336,155 @@ export class IsolationModule {
         const key = this.makeConnectionOverlayKey(db, schemaName, tableName);
         this.preOverlaySavepoints.delete(key);
     }
+    /**
+     * Returns every key of a connection-scoped map (`<dbId>:<schema>.<table>`, the
+     * shape of {@link connectionOverlays} / {@link preOverlaySavepoints} /
+     * {@link connectionInFlight}) that belongs to `schemaName.tableName`, across ALL
+     * db ids. Those maps embed the db id as a prefix, so a per-table sweep is a suffix
+     * match on `:<schema>.<table>`. Keys are stored lowercased, so the suffix is too.
+     *
+     * The keys are materialized into an array rather than yielded, so callers may
+     * delete or re-key entries while walking the result.
+     */
+    connectionScopedKeys(map, schemaName, tableName) {
+        const suffix = `:${schemaName}.${tableName}`.toLowerCase();
+        const keys = [];
+        for (const key of map.keys()) {
+            if (key.endsWith(suffix))
+                keys.push(key);
+        }
+        return keys;
+    }
+    /**
+     * Commits every overlay this db-transaction staged as ONE coordinated two-phase
+     * flush, instead of each table flushing+committing its own underlying
+     * independently. The per-table approach tears a multi-table commit: table A's
+     * underlying `commit()` durably lands (and, for a shared-coordinator
+     * `quereus-store`, flushes *every* pending table) before table B has even
+     * applied, so a failure in B leaves A committed. See the fix ticket and
+     * `quereus-store/README` § "Atomic multi-store commit".
+     *
+     * Phase 1 (apply): for every staged overlay, begin its underlying table and
+     * apply the overlay's rows WITHOUT committing (see {@link applyOverlayToUnderlying}).
+     * For a `quereus-store` underlying, every table's writes accumulate in the
+     * module's single shared coordinator (the first `begin()` opens it; the rest are
+     * idempotent no-ops).
+     *
+     * Phase 2 (commit): once ALL overlays have applied, commit the affected
+     * underlying tables. For `quereus-store` the first `commit()` flushes every
+     * table's ops in one atomic coordinator commit — a single `AtomicBatch.write()`
+     * on a provider that exposes `beginAtomicBatch` — and the rest no-op. For an
+     * underlying with per-table transaction domains (the memory vtab), each table
+     * commits independently.
+     *
+     * On any Phase-1 error, roll back every underlying begun so far and rethrow;
+     * nothing was committed, so the transaction aborts atomically. Because all the
+     * fallible data work (constraint re-checks, injected/IO write errors) happens in
+     * Phase 1 before any commit, a data-driven abort is always clean. Full
+     * crash-atomicity across the commit phase itself is contingent on the underlying
+     * exposing a shared atomic commit domain (see docs/design-isolation-layer.md
+     * § "Commit Failure Recovery").
+     *
+     * A poisoned overlay aborts the whole commit before any apply — mirroring the
+     * per-connection `assertOverlayUsable` check, now with the added benefit that no earlier
+     * table is left committed. The overlay is left intact so the ensuing rollback discards
+     * it. Two DDLs poison: a cross-connection ALTER (rows left in the pre-alter layout) and
+     * a cross-connection DROP TABLE (the table is gone; see {@link destroy}).
+     *
+     * Driven once per db-transaction: the first `IsolatedConnection.commit()` in the
+     * database's commit loop runs this whole flush and clears every overlay, so the
+     * remaining connections find no overlay for their table and this is a no-op — no
+     * explicit "already flushed" latch is needed, the cleared-overlay state guards
+     * itself.
+     *
+     * **Invariant: every staged overlay resolves to an underlying table here, or is
+     * poisoned.** The table-lifecycle hooks are what keep that true — {@link destroy}
+     * discards or poisons the overlays of a dropped table across every connection, and
+     * {@link renameTable} re-connects the underlying under the new name whenever it re-keys
+     * an overlay onto it. The poison check above is the enforcement point: it runs BEFORE
+     * the `underlyingTables` lookup, so a dropped table's surviving foreign overlay raises
+     * its poison message rather than the orphan error below. A miss that is neither resolved
+     * nor poisoned is therefore a layer-invariant violation, not a routine condition, and is
+     * raised as `StatusCode.INTERNAL`: the alternative — dropping the staged rows and letting
+     * the commit report success — is silent data loss. Only a CLEAN overlay
+     * (`hasChanges === false`) may miss harmlessly; it staged nothing, so it is discarded.
+     */
+    async commitConnectionOverlays(db) {
+        const prefix = `${this.getDbId(db)}:`;
+        const entries = [];
+        /** Clean overlays with no underlying — never applied, but must still be cleared. */
+        const orphanedCleanKeys = [];
+        for (const [key, state] of this.connectionOverlays.entries()) {
+            if (!key.startsWith(prefix))
+                continue;
+            // A poisoned overlay can neither be flushed nor merged (its rows are in the
+            // pre-alter column layout). Abort the whole commit before applying anything;
+            // the overlay is left intact so the ensuing rollback discards it (and its
+            // poison). A poisoned overlay always has hasChanges === true.
+            if (state.poison) {
+                throw new QuereusError(state.poison.message, StatusCode.CONSTRAINT);
+            }
+            // The overlay key is `<dbId>:<schema>.<table>`; the suffix after the dbId is
+            // exactly the `underlyingTables` key (both lowercased).
+            const underlyingKey = key.slice(prefix.length);
+            const underlyingState = this.underlyingTables.get(underlyingKey);
+            if (!underlyingState) {
+                if (state.hasChanges) {
+                    throw new QuereusError(`Isolation layer: staged overlay '${key}' has no underlying table '${underlyingKey}' to flush. `
+                        + `A table-lifecycle hook (destroy / renameTable) failed to keep the overlay and underlying maps in step.`, StatusCode.INTERNAL);
+                }
+                // Staged nothing, so nothing is lost. It never reaches `entries`, so the
+                // clear-loop below would not see it — collect it explicitly or it leaks.
+                orphanedCleanKeys.push(key);
+                continue;
+            }
+            entries.push({ key, state, underlyingTable: underlyingState.underlyingTable });
+        }
+        // Phase 1: apply every staged overlay to its underlying WITHOUT committing.
+        const applied = [];
+        try {
+            for (const { state, underlyingTable } of entries) {
+                if (!state.hasChanges)
+                    continue;
+                // Track BEFORE applying: applyOverlayToUnderlying begins the underlying up
+                // front, so a mid-apply throw still needs this table in the rollback set.
+                applied.push(underlyingTable);
+                await applyOverlayToUnderlying(underlyingTable, state.overlayTable, this.tombstoneColumn);
+            }
+        }
+        catch (error) {
+            // Nothing committed yet — roll back every underlying we began so no table is
+            // left half-applied, then propagate (the transaction aborts atomically). For a
+            // shared-coordinator store the first rollback discards all pending ops and the
+            // rest no-op. allSettled mirrors the engine's own rollback-during-abort posture
+            // in database-transaction.ts (rollback failures must not mask the original error).
+            await Promise.allSettled(applied.map(underlyingTable => underlyingTable.rollback?.()));
+            throw error;
+        }
+        // Phase 2: commit the affected underlyings. For a shared-coordinator store the
+        // first commit flushes all tables in one atomic batch and the rest no-op; for
+        // per-table domains (memory) each commits independently.
+        for (const underlyingTable of applied) {
+            await underlyingTable.commit?.();
+        }
+        // Clear every overlay for this db — the transaction's staged state is now
+        // durable (or was empty). Every key cleared here was either applied above
+        // (`hasChanges`) or staged nothing; a staged overlay that could not be applied
+        // threw INTERNAL before Phase 1 and never reaches this point. Subsequent
+        // IsolatedConnection.commit()s in the loop find no overlay and no-op. Pre-overlay
+        // savepoint sets are cleared per table by each connection's onConnectionCommit
+        // (which also covers a table that has savepoints but never got an overlay).
+        for (const { key, state } of entries) {
+            await this.releaseOverlayTable(state);
+            this.connectionOverlays.delete(key);
+        }
+        for (const key of orphanedCleanKeys) {
+            const state = this.connectionOverlays.get(key);
+            if (state)
+                await this.releaseOverlayTable(state);
+            this.connectionOverlays.delete(key);
+        }
+    }
     /**
      * Coalesces concurrent covering-connection builds for one (db, table) onto a
      * single in-flight promise, keyed identically to {@link connectionOverlays}
@@ -350,6 +542,13 @@ export class IsolationModule {
     }
     /**
      * Returns capabilities combining underlying module with isolation guarantees.
+     *
+     * `ddlTransactionality` is forwarded verbatim through the spread — the wrapper
+     * NEVER upgrades it. The overlay stages DML outside the underlying module, so an
+     * underlying DDL-commit flushes only module-side ops, leaving overlay writes
+     * behind (the `bug-store-savepoint-ddl-drop-lost-insert` asymmetry). Forwarding
+     * the underlying's (pessimistic) value is the honest choice; only `isolation` /
+     * `savepoints` are augmented, since the wrapper genuinely adds those.
      */
     getCapabilities() {
         const underlyingCaps = this.underlying.getCapabilities?.() ?? {};
@@ -446,8 +645,10 @@ export class IsolationModule {
         // 2. Store underlying state (overlay is per-connection, created lazily)
         const state = { underlyingTable };
         this.setUnderlyingState(tableSchema.schemaName, tableSchema.name, state);
-        // 3. Return wrapped table (overlay will be created lazily on first write)
-        return new IsolatedTable(db, this, underlyingTable);
+        // 3. Return wrapped table (overlay will be created lazily on first write).
+        //    Keyed off the schema's own (schemaName, name) — the pair `underlyingTables` uses —
+        //    never off the underlying table's self-reported names (see IsolatedTable's ctor doc).
+        return new IsolatedTable(db, this, tableSchema.schemaName, tableSchema.name, underlyingTable);
     }
     /**
      * Connects to an existing isolated table.
@@ -471,21 +672,180 @@ export class IsolationModule {
         // the per-connection overlay so reads reflect only persisted underlying state.
         const readCommitted = options?._readCommitted === true;
         // Return a fresh IsolatedTable instance that will look up its overlay
-        // from connection-scoped storage (shared with other instances in same transaction)
-        return new IsolatedTable(db, this, state.underlyingTable, readCommitted);
+        // from connection-scoped storage (shared with other instances in same transaction).
+        // Pass the connect-time (schemaName, tableName) — the pair `underlyingTables` is keyed
+        // by — never the underlying's self-reported names (see IsolatedTable's ctor doc).
+        return new IsolatedTable(db, this, schemaName, tableName, state.underlyingTable, readCommitted);
     }
     /**
-     * Destroys the underlying table.
+     * Destroys the underlying table, then resolves every connection's staged state for it.
+     *
+     * DROP TABLE is not transaction-scoped: the table is gone for *every* connection the
+     * moment this returns, so no overlay staging writes against it can ever be flushed.
+     * What differs is who gets told. Per overlay key matching the dropped table (both maps
+     * are keyed `<dbId>:<schema>.<table>`, so the sweep spans all db ids):
+     *
+     * - **The dropping connection's own overlay** is discarded silently. It issued the DROP;
+     *   there is nobody to notify.
+     * - **A foreign overlay with staged rows** (`hasChanges`) is **poisoned**, not swept.
+     *   Sweeping it let that connection commit against an empty overlay set and report
+     *   success after its rows were thrown away — silent cross-connection data loss. Poison
+     *   makes its next read/write/commit throw `CONSTRAINT` (see
+     *   {@link IsolatedTable.assertOverlayUsable} and the poison check at the head of
+     *   {@link commitConnectionOverlays}, which precedes the `underlyingTables` lookup and so
+     *   raises the poison message rather than the orphan INTERNAL error). An already-poisoned
+     *   overlay keeps its original message — the first cause is the one worth reporting.
+     * - **A foreign overlay with no staged rows** is discarded: it staged nothing, so nothing
+     *   is lost.
+     *
+     * `preOverlaySavepoints` is swept for every matching key whose overlay did NOT survive.
+     * A surviving poisoned overlay keeps its set: `ensureOverlay` padding still consults it,
+     * and the owning connection's `onConnectionRollback` reaps it when its failed commit
+     * rolls back. Without the sweep, an abandoned set outlived the table for the lifetime of
+     * the `Database` (nothing else is keyed to reap it once the table is gone).
+     *
+     * Nothing is discarded or poisoned until the underlying destroy SUCCEEDS. A throwing
+     * `underlying.destroy` means the table still exists, so every connection's staged
+     * writes are still flushable and every map entry must survive untouched — the same
+     * reason {@link renameTable} delegates before mutating its maps.
+     *
+     * NOTE: poison rides on the `ConnectionOverlayState`, not on its rows, so a foreign
+     * connection that later unwinds every staged row past the drop (rollback to a savepoint
+     * taken after the overlay existed) still fails its commit. Deliberately over-strict —
+     * the table is gone either way. If a caller ever needs the clean-unwind case to commit,
+     * re-evaluate the poison on `onConnectionRollbackToSavepoint` rather than special-casing
+     * here.
+     *
+     * NOTE: a connection whose own overlay was already poisoned (by another connection's
+     * ALTER) escapes that poison for this table by dropping it — the own-overlay branch
+     * deletes the state, poison and all. Correct as written: the rows it discards belong to
+     * a table this connection just asked to remove. If poison ever carries a cause that
+     * outlives the table, gate the own-overlay delete on it.
+     *
+     * NOTE: this mutates `connectionOverlays` while a foreign connection may be mid-scan in
+     * `IsolatedTable.query`'s merged branch — that scan will keep merging against an overlay
+     * whose underlying is now destroyed. The module clamps to `'reentrant-reads'`, so no
+     * in-tree host reaches it. If a host ever runs a DROP concurrently with a foreign scan,
+     * the merged iterator needs a per-scan snapshot of the overlay + underlying pair.
      */
     async destroy(db, pAux, moduleName, schemaName, tableName) {
-        this.removeUnderlyingState(schemaName, tableName);
         await this.underlying.destroy(db, pAux, moduleName, schemaName, tableName);
+        this.removeUnderlyingState(schemaName, tableName);
+        const ownKey = this.makeConnectionOverlayKey(db, schemaName, tableName);
+        const survivingKeys = new Set();
+        for (const key of this.connectionScopedKeys(this.connectionOverlays, schemaName, tableName)) {
+            const state = this.connectionOverlays.get(key);
+            if (key !== ownKey && state.hasChanges) {
+                if (!state.poison) {
+                    state.poison = { message: this.buildDropPoisonMessage(schemaName, tableName) };
+                }
+                survivingKeys.add(key);
+                continue;
+            }
+            // Own overlay, or a foreign CLEAN one — abandoned here, so free its staging table.
+            // A surviving poisoned foreign overlay is intentionally NOT released: it stays
+            // installed and is freed later when its owning connection rolls back (which routes
+            // through clearConnectionOverlay → releaseOverlayTable).
+            await this.releaseOverlayTable(state);
+            this.connectionOverlays.delete(key);
+        }
+        for (const key of this.connectionScopedKeys(this.preOverlaySavepoints, schemaName, tableName)) {
+            if (!survivingKeys.has(key))
+                this.preOverlaySavepoints.delete(key);
+        }
+    }
+    /**
+     * 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.
+     */
+    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);
+    }
+    /**
+     * 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.
+     */
+    buildRebuildPoisonMessage(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.`;
+    }
+    /**
+     * Builds the poison message stamped onto a foreign overlay whose table was dropped out
+     * from under it (see {@link destroy}). Names the schema.table so the owning connection's
+     * eventual read/write/commit error is self-explanatory. Companion to
+     * {@link buildAlterPoisonMessage}: both poison sources raise the same
+     * `StatusCode.CONSTRAINT` and are told apart by their message, not their code.
+     */
+    buildDropPoisonMessage(schemaName, tableName) {
+        return `Table '${schemaName}.${tableName}' was dropped by another connection while this connection had uncommitted changes staged for it; roll back this transaction.`;
     }
     /**
      * Closes all resources held by the underlying module (if it supports closeAll).
      * Also clears connection overlay state.
      */
     async closeAll() {
+        // Free every overlay's staging table before dropping the map. The default
+        // MemoryTableModule overlay is discarded with this wrapper, but a host-injected
+        // SHARED config.overlay would otherwise retain one dead entry per open overlay —
+        // each state carries its own db so the release targets the right one.
+        for (const state of this.connectionOverlays.values()) {
+            await this.releaseOverlayTable(state);
+        }
         this.connectionOverlays.clear();
         this.preOverlaySavepoints.clear();
         this.underlyingTables.clear();
@@ -495,24 +855,107 @@ export class IsolationModule {
         }
     }
     /**
-     * Creates an index on the underlying table.
+     * The rows the connection owning `overlayState` can SEE — the underlying's committed rows
+     * merged with that overlay's staged writes. Re-callable, as `EffectiveRowSource` requires.
      *
-     * Note: Indexes on per-connection overlays are created lazily when the
-     * overlay is created, by copying from the underlying table's schema.
+     * This is the seam the whole fix turns on: the underlying module validates row-content DDL
+     * (UNIQUE duplicate detection, collation-rekey collisions) against its OWN rows, which under
+     * isolation are the committed rows only. The transaction's pending rows live here, in the
+     * overlay, where the underlying cannot reach them — so we hand them down.
      *
-     * 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 ensureOverlay() reads when building the overlay schema.
+     * NOTE: each call re-materializes the overlay and re-scans the underlying. `alter column …
+     * set collate` calls once per UNIQUE constraint covering the altered column, so a table with
+     * many such constraints pays that many scans. If it ever shows up as slow, materialize the
+     * overlay's PK map once per DDL and share it across the calls.
      */
-    async createIndex(db, schemaName, tableName, indexSchema) {
+    effectiveRowsFor(db, underlyingTable, overlayState) {
+        const schema = underlyingTable.tableSchema;
+        if (!schema) {
+            throw new QuereusError('Isolation layer: underlying table has no schema', StatusCode.INTERNAL);
+        }
+        const pkIndices = schema.primaryKeyDefinition.map(pkDef => pkDef.index);
+        const pkKeyOf = makePkKeySerializer(db, schema);
+        const overlayTable = overlayState.overlayTable;
+        return () => iterateEffectiveRows(underlyingTable, overlayTable, this.tombstoneColumn, pkIndices, pkKeyOf);
+    }
+    /**
+     * The row source to hand a row-validating DDL on behalf of the connection issuing it, or
+     * undefined when that connection has nothing staged and the underlying's own rows already
+     * ARE its effective rows.
+     *
+     * **Only the issuing connection's overlay feeds validation.** A foreign connection's
+     * overlay may hold rows that collide with the new constraint; that is its problem when it
+     * commits, exactly as an ordinary concurrent duplicate insert would be. A poisoned issuer
+     * overlay is likewise skipped — its rows are structurally stale, and the connection can
+     * only recover by rolling back.
+     */
+    issuerEffectiveRows(db, schemaName, tableName, underlyingTable) {
+        const overlayState = this.getConnectionOverlay(db, schemaName, tableName);
+        if (!overlayState || overlayState.poison || !overlayState.hasChanges)
+            return undefined;
+        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.
+     *
+     * Two things the underlying cannot do for itself:
+     *
+     * 1. **Judge the right rows.** The issuing connection's pending rows are in its overlay,
+     *    invisible to the underlying, so a duplicate it staged would slip past the build and a
+     *    duplicate it deleted would spuriously reject it. {@link issuerEffectiveRows} supplies
+     *    the merged view; the underlying builds its physical structure from its own committed
+     *    rows, which is sound because every reader resolves an index entry back to its live row.
+     * 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.
+     *
+     * 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
+     * ensureOverlay() reads when building the overlay schema.
+     */
+    async createIndex(db, schemaName, tableName, indexSchema, rows) {
         const state = this.getUnderlyingState(schemaName, tableName);
+        // An outer wrapper's row source, if any, already names the effective rows; otherwise
+        // build our own from the issuing connection's overlay.
+        const rowSource = rows ?? (state ? this.issuerEffectiveRows(db, schemaName, tableName, state.underlyingTable) : undefined);
         if (state?.underlyingTable.createIndex) {
             // Instance-level createIndex keeps MemoryTable.tableSchema fresh
-            await state.underlyingTable.createIndex(indexSchema);
+            await state.underlyingTable.createIndex(indexSchema, rowSource);
         }
         else if (this.underlying.createIndex) {
-            await this.underlying.createIndex(db, schemaName, tableName, indexSchema);
+            await this.underlying.createIndex(db, schemaName, tableName, indexSchema, rowSource);
+        }
+        else {
+            return; // underlying does not support indexes; nothing was created, nothing to rebuild
         }
+        if (!state)
+            return;
+        const updatedSchema = this.assertIndexPresent(state.underlyingTable, schemaName, tableName, indexSchema.name);
+        await this.rebuildOverlaysForIndexChange(db, schemaName, tableName, updatedSchema, `create index '${indexSchema.name}'`);
+    }
+    /**
+     * Reads back the underlying table instance's post-`createIndex` schema, asserting it now
+     * carries the new index.
+     *
+     * 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.
+     */
+    assertIndexPresent(underlyingTable, schemaName, tableName, indexName) {
+        const updatedSchema = underlyingTable.tableSchema;
+        const present = updatedSchema?.indexes?.some(idx => idx.name.toLowerCase() === indexName.toLowerCase());
+        if (!updatedSchema || !present) {
+            throw new QuereusError(`Isolation layer: underlying table '${schemaName}.${tableName}' did not refresh its cached tableSchema after `
+                + `creating index '${indexName}'. The per-connection overlays cannot adopt an index the underlying does not `
+                + `report; the underlying module must refresh VirtualTable.tableSchema in createIndex.`, StatusCode.INTERNAL);
+        }
+        return updatedSchema;
     }
     /**
      * Drops an index on the underlying table.
@@ -549,35 +992,54 @@ export class IsolationModule {
         const updatedSchema = state?.underlyingTable.tableSchema;
         if (!updatedSchema)
             return;
-        const suffix = `:${schemaName}.${tableName}`.toLowerCase();
-        for (const [key, overlayState] of this.connectionOverlays.entries()) {
-            if (key.endsWith(suffix)) {
-                // A poisoned overlay (cross-connection ALTER) holds rows in the pre-alter column
-                // layout, narrower/wider than `updatedSchema`. Rebuilding it here 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.
-                if (overlayState.poison)
-                    continue;
-                const newState = await this.migrateOverlayForDropIndex(db, overlayState, updatedSchema);
-                this.connectionOverlays.set(key, newState);
-            }
+        await this.rebuildOverlaysForIndexChange(db, schemaName, tableName, updatedSchema, `drop index '${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.
+     */
+    async rebuildOverlaysForIndexChange(db, schemaName, tableName, updatedSchema, ddlDescription) {
+        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));
         }
     }
     /**
-     * Rebuilds an overlay table under the post-drop-index schema, preserving
-     * staged rows (including tombstones). Column layout is unchanged by
-     * DROP INDEX, so rows can be copied verbatim.
+     * 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).
      */
-    async migrateOverlayForDropIndex(db, oldState, updatedSchema) {
+    async rebuildOverlayForIndexChange(db, oldState, updatedSchema) {
         const oldOverlay = oldState.overlayTable;
         const newOverlaySchema = this.createOverlaySchema(updatedSchema);
         const newOverlayTable = await this.overlayModule.create(db, newOverlaySchema);
-        if (oldState.hasChanges && oldOverlay.query) {
-            for await (const oldRow of oldOverlay.query(this.makeFullScanFilterInfo())) {
-                await newOverlayTable.update({ operation: 'insert', values: oldRow, preCoerced: true });
+        const newState = { overlayTable: newOverlayTable, hasChanges: oldState.hasChanges, db };
+        try {
+            if (oldState.hasChanges && oldOverlay.query) {
+                for await (const oldRow of oldOverlay.query(makeFullScanFilterInfo())) {
+                    await this.insertIntoRebuiltOverlay(newOverlayTable, oldRow, updatedSchema.name);
+                }
             }
         }
-        return { overlayTable: newOverlayTable, hasChanges: oldState.hasChanges };
+        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;
+        }
+        return newState;
     }
     /**
      * Delegates ALTER TABLE to the underlying module and migrates any per-connection
@@ -600,8 +1062,13 @@ export class IsolationModule {
      * ALTER either fails clean or fully applies — base/catalog can no longer diverge.
      * This mirrors the engine's pre-mutation `validateNotNullBackfill` in
      * `runtime/emit/alter-table.ts`.
+     *
+     * **Row-content validation.** The row-validating arms (`add constraint … unique`,
+     * `alter column … set collate`) judge the ISSUING connection's effective rows, not the
+     * underlying's committed ones — see {@link issuerEffectiveRows}. The underlying runs that
+     * check before it mutates anything, so the atomic-abort guarantee above still holds.
      */
-    async alterTable(db, schemaName, tableName, change) {
+    async alterTable(db, schemaName, tableName, change, rows) {
         if (!this.underlying.alterTable) {
             throw new QuereusError(`Underlying module does not support ALTER TABLE for '${schemaName}.${tableName}'`, StatusCode.UNSUPPORTED);
         }
@@ -612,13 +1079,11 @@ export class IsolationModule {
         // left for its owning connection to error on, while the issuer's ALTER proceeds.
         // Already-poisoned overlays (own or foreign) are skipped entirely: they hold rows
         // from before an earlier ALTER, stay poisoned, and must not be re-read/migrated.
-        const suffix = `:${schemaName}.${tableName}`.toLowerCase();
         const ownKey = this.makeConnectionOverlayKey(db, schemaName, tableName);
         let ownEntry;
         const foreign = [];
-        for (const [key, state] of this.connectionOverlays.entries()) {
-            if (!key.endsWith(suffix))
-                continue;
+        for (const key of this.connectionScopedKeys(this.connectionOverlays, schemaName, tableName)) {
+            const state = this.connectionOverlays.get(key);
             // An already-poisoned overlay (from an earlier ALTER) holds pre-alter rows and must
             // never be re-read or migrated — checked BEFORE the ownKey split so the poisoned
             // connection's OWN later ALTER cannot route its overlay through migration, which
@@ -649,38 +1114,53 @@ export class IsolationModule {
         // schema needed — so it is valid here, before the underlying is mutated, and the
         // same context drives the post-mutation migration.
         const addColumnCtx = this.deriveAddColumnBackfill(change, db, tableName);
+        // Build the setNotNull backfill context (undefined unless this is a NOT NULL tightening
+        // with overlays to migrate). The now-NOT-NULL column's index and folded DEFAULT are read
+        // from a to-be-migrated overlay's PRE-alter schema — the same layout every migrated overlay
+        // shares, and the same source `dropColumnIdx` uses above.
+        const setNotNullCtx = this.deriveSetNotNullBackfill(change, toMigrate, tableName);
         // 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.
         if (ownEntry) {
-            await this.validateOverlayMigration(ownEntry[1], addColumnCtx);
+            await this.validateOverlayMigration(ownEntry[1], addColumnCtx, setNotNullCtx);
         }
-        const updated = await this.underlying.alterTable(db, schemaName, tableName, change);
+        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
+            ? this.issuerEffectiveRows(db, schemaName, tableName, underlyingState.underlyingTable)
+            : undefined);
+        const updated = await this.underlying.alterTable(db, schemaName, tableName, change, rowSource);
         // 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
         // freshly-connected IsolatedTable's merged-view UNIQUE check (which reads
         // this.tableSchema.uniqueConstraints / per-column collation) sees the post-alter
         // constraint set. Mirrors the implicit instance refresh dropIndex already gets.
-        const underlyingState = this.getUnderlyingState(schemaName, tableName);
         if (underlyingState)
             underlyingState.underlyingTable.tableSchema = updated;
+        const ddlDescription = `alter table (${change.type})`;
         // Migrate the issuer's own overlay (already validated above). Its NOT NULL /
-        // tombstone throw sites are unreachable after pre-validation.
+        // tombstone throw sites are unreachable after pre-validation; so is a UNIQUE
+        // rejection, which `rowSource` already judged — {@link adoptRebuiltOverlay} raises
+        // INTERNAL if one fires anyway rather than dropping the row.
         if (ownEntry) {
-            const newState = await this.migrateOverlayForAlter(db, ownEntry[1], updated, change, dropColumnIdx, addColumnCtx);
-            this.connectionOverlays.set(ownEntry[0], newState);
+            await this.adoptRebuiltOverlay(ownEntry[0], ownEntry[1], true, schemaName, tableName, ddlDescription, () => this.migrateOverlayForAlter(db, ownEntry[1], updated, change, dropColumnIdx, addColumnCtx, setNotNullCtx));
         }
         // 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. An INTERNAL failure (e.g. missing tombstone column) is a layer-invariant
-        // violation, not a data condition, so it rethrows loud for everyone. Validation
-        // runs per overlay, so one bad foreign overlay poisons only itself; healthy peers
-        // still migrate.
+        // 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.
         for (const [key, oldState] of foreign) {
             try {
-                await this.validateOverlayMigration(oldState, addColumnCtx);
+                await this.validateOverlayMigration(oldState, addColumnCtx, setNotNullCtx);
             }
             catch (e) {
                 if (e instanceof QuereusError && e.code === StatusCode.CONSTRAINT) {
@@ -689,8 +1169,7 @@ export class IsolationModule {
                 }
                 throw e;
             }
-            const newState = await this.migrateOverlayForAlter(db, oldState, updated, change, dropColumnIdx, addColumnCtx);
-            this.connectionOverlays.set(key, newState);
+            await this.adoptRebuiltOverlay(key, oldState, false, schemaName, tableName, ddlDescription, () => this.migrateOverlayForAlter(db, oldState, updated, change, dropColumnIdx, addColumnCtx, setNotNullCtx));
         }
         return updated;
     }
@@ -698,13 +1177,19 @@ export class IsolationModule {
      * 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 only arises on the addColumn
-     * NOT NULL path, so the column name is taken from the addColumn change; other change
-     * types never reach here but are handled defensively.
+     * 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.
      */
     buildAlterPoisonMessage(schemaName, tableName, change) {
-        const col = change.type === 'addColumn' ? change.columnDef.name : '<column>';
-        return `ALTER on '${schemaName}.${tableName}' added column '${col}' (NOT NULL) that this connection's uncommitted row cannot satisfy; roll back this transaction.`;
+        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') {
+            return `ALTER on '${schemaName}.${tableName}' tightened column '${change.columnName}' to NOT NULL, which this connection's uncommitted row violates; roll back this transaction.`;
+        }
+        return `ALTER on '${schemaName}.${tableName}' cannot migrate this connection's uncommitted rows; roll back this transaction.`;
     }
     /**
      * Renames a table through the isolation layer.
@@ -717,69 +1202,152 @@ export class IsolationModule {
      * Done in this order so a failure in the underlying rename leaves our
      * internal maps untouched (the engine will not update the schema catalog
      * if this method throws).
+     *
+     * **Why the underlying is re-connected, not re-keyed.** A rename mid-transaction
+     * moves any staged overlay onto the new name, and `commitConnectionOverlays`
+     * resolves an overlay's underlying by that name. Simply re-keying
+     * `underlyingTables` old→new would be cheaper, but the cached `VirtualTable` may
+     * be dead: `StoreModule.renameTable` closes and re-opens the store, so the stale
+     * handle yields "store is closed". So we evict it and, when an overlay was
+     * carried onto the new name, immediately connect a fresh underlying under that
+     * name — otherwise the transaction commits against a table that is in neither
+     * map, and the overlay's rows vanish (see {@link commitConnectionOverlays}'s
+     * invariant). With no overlay carried over there is nothing to flush, so the
+     * eviction alone is enough and the next `connect()` re-resolves lazily.
      */
     async renameTable(db, schemaName, oldName, newName) {
+        // Read the catalog entry BEFORE anything mutates: `runtime/emit/alter-table.ts`
+        // calls this hook ahead of the catalog swap, so the table is still registered
+        // under `oldName` here. It carries the vtab module name / args that
+        // `reconnectUnderlyingAfterRename` needs — the hook's own signature has neither.
+        const preRenameSchema = db.schemaManager.getTable(schemaName, oldName);
         if (this.underlying.renameTable) {
             await this.underlying.renameTable(db, schemaName, oldName, newName);
         }
         // Drop our cached underlying VirtualTable for the old name. It may have
         // been disconnected by the underlying module (e.g. StoreModule closes
         // and re-opens stores during rename), so reusing it would yield "store
-        // is closed" errors. The next connect() under the new name will fetch a
-        // fresh underlying table from the underlying module.
+        // is closed" errors.
         this.removeUnderlyingState(schemaName, oldName);
-        // Re-key per-connection overlay and savepoint state, preserving the
-        // connection-id prefix so overlays created earlier in an open
-        // transaction remain visible under the new name.
-        this.rekeyConnectionScopedMap(this.connectionOverlays, schemaName, oldName, newName);
-        this.rekeyConnectionScopedMap(this.preOverlaySavepoints, schemaName, oldName, newName);
+        // Re-key per-connection overlay state, preserving the connection-id prefix so
+        // overlays created earlier in an open transaction remain visible under the new
+        // name — the commit flush resolves an overlay's underlying by current name.
+        const movedOverlays = this.rekeyConnectionScopedMap(this.connectionOverlays, schemaName, oldName, newName);
+        // `preOverlaySavepoints` is deliberately NOT re-keyed. The set's own maintainers —
+        // the savepoint/commit/rollback callbacks on the already-registered
+        // IsolatedConnection — resolve the name the IsolatedTable was constructed with,
+        // which stays `oldName` for the life of the transaction. Moving the set to
+        // `newName` would strand it: the old-name instance clears a key that no longer
+        // exists and the moved set survives into the next transaction, where a matching
+        // `rollback to savepoint` depth would wrongly discard the whole overlay.
+        // Nothing needs carrying over: the first statement after the rename connects a
+        // fresh IsolatedTable under `newName`, whose ensureConnection() registers a new
+        // IsolatedConnection, and `Database.registerConnection` replays the active
+        // savepoint stack onto it. If no overlay was carried across, that replay rebuilds
+        // the depth set under the new name from scratch; if one was, the replay adds
+        // nothing (the depths no longer pre-date an overlay) and the overlay's own
+        // registered connection already holds a snapshot per active depth, taken when
+        // `ensureOverlay` pre-registered it.
+        if (movedOverlays > 0) {
+            await this.reconnectUnderlyingAfterRename(db, schemaName, newName, preRenameSchema);
+        }
+    }
+    /**
+     * Forward the engine's post-propagation rename finalize to the underlying (see
+     * {@link renameTable} for the two-phase split). The underlying (e.g. `StoreModule`)
+     * uses it to drop the old name's catalog entry only after the cross-table rewrites
+     * `propagateTableRename` enqueued are durable. `IsolationModule` owns no persistent
+     * catalog of its own and already evicted every old-name state in `renameTable`, so
+     * it simply delegates.
+     */
+    async finalizeRename(db, schemaName, oldName, newName) {
+        await this.underlying.finalizeRename?.(db, schemaName, oldName, newName);
+    }
+    /**
+     * Connects a fresh underlying table under the post-rename name and records it in
+     * `underlyingTables`, restoring the "every staged overlay resolves to an underlying"
+     * invariant that {@link renameTable}'s eviction would otherwise break.
+     *
+     * `preRenameSchema` is the catalog's pre-rename `TableSchema`; it is cloned under the
+     * new name so the underlying module sees the same column layout, PK, and vtab args it
+     * was created with.
+     *
+     * NOTE: `pAux` is passed as `undefined`: the aux data the engine hands
+     * `IsolationModule.connect()` belongs to *this* wrapper's registration, not the
+     * underlying's, and both bundled underlyings (`MemoryTableModule`, `StoreModule`)
+     * ignore the parameter — the same assumption `connect()` already relies on when it
+     * forwards its own caller's `pAux` straight through. If a third-party underlying ever
+     * reads `pAux` in `connect()`, `IsolationModule` must capture the underlying's own aux
+     * data at registration and hand it back here.
+     */
+    async reconnectUnderlyingAfterRename(db, schemaName, newName, preRenameSchema) {
+        if (!preRenameSchema) {
+            throw new QuereusError(`Isolation layer: cannot re-resolve underlying table for renamed '${schemaName}.${newName}' — `
+                + `no catalog entry for the pre-rename name, and a staged overlay depends on it.`, StatusCode.INTERNAL);
+        }
+        const renamedSchema = { ...preRenameSchema, name: newName };
+        const underlyingTable = await this.underlying.connect(db, undefined, preRenameSchema.vtabModuleName, schemaName, newName, preRenameSchema.vtabArgs ?? {}, renamedSchema);
+        this.setUnderlyingState(schemaName, newName, { underlyingTable });
     }
     /**
      * Re-keys all entries of a connection-scoped map (`<dbId>:<schema>.<table>`)
      * from oldName to newName, leaving entries for other tables untouched.
+     * Returns how many entries moved.
      */
     rekeyConnectionScopedMap(map, schemaName, oldName, newName) {
-        const oldSuffix = `:${schemaName}.${oldName}`.toLowerCase();
+        // Length of the LOWERCASED suffix: keys are stored lowercased, and case folding is
+        // not always length-preserving (`'İ'.toLowerCase()` is two code units).
+        const oldSuffixLength = `:${schemaName}.${oldName}`.toLowerCase().length;
         const newSuffix = `:${schemaName}.${newName}`.toLowerCase();
-        const moved = [];
-        for (const [key, value] of map.entries()) {
-            if (key.endsWith(oldSuffix)) {
-                const prefix = key.substring(0, key.length - oldSuffix.length);
-                moved.push([`${prefix}${newSuffix}`, value]);
-                map.delete(key);
-            }
-        }
-        for (const [newKey, value] of moved) {
-            map.set(newKey, value);
+        const oldKeys = this.connectionScopedKeys(map, schemaName, oldName);
+        for (const oldKey of oldKeys) {
+            const value = map.get(oldKey);
+            map.delete(oldKey);
+            map.set(`${oldKey.substring(0, oldKey.length - oldSuffixLength)}${newSuffix}`, value);
         }
+        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) {
+    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);
-        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(this.makeFullScanFilterInfo())) {
-                const addColumnValue = addColumnCtx
-                    ? await this.computeAddColumnValue(addColumnCtx, oldRow, oldTombstoneIdx)
-                    : undefined;
-                const newRow = this.translateOverlayRow(oldRow, oldTombstoneIdx, change, dropColumnIdx, addColumnValue);
-                await newOverlayTable.update({ operation: 'insert', values: newRow, preCoerced: true });
+        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);
+                }
             }
         }
-        return { overlayTable: newOverlayTable, hasChanges: oldState.hasChanges };
+        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;
     }
     /**
      * Precomputes the per-ALTER constants an `addColumn` overlay backfill needs:
@@ -808,7 +1376,7 @@ export class IsolationModule {
         // ADD COLUMN sites. This site only reads `.notNull`/`.name` off the result (the
         // underlying materializes the real column), so it does not affect collation here — but
         // keeping the call signature identical avoids drift and is correct for any future reader.
-        const newColumn = columnDefToSchema(change.columnDef, defaultNotNull, db.options.getStringOption('default_collation'));
+        const newColumn = columnDefToSchema(change.columnDef, defaultNotNull, db.options.getStringOption('default_collation'), (n) => db.isCollationRegistered(n));
         return {
             foldedDefault,
             evaluator: change.backfillEvaluator,
@@ -817,6 +1385,43 @@ export class IsolationModule {
             tableName,
         };
     }
+    /**
+     * Precomputes the per-ALTER constants an `alter column … set not null` overlay migration needs:
+     * the now-NOT-NULL column's index and the folded literal DEFAULT (with `hasDefault` gating
+     * backfill vs reject). Returns undefined unless this is a NOT NULL *tightening*
+     * (`setNotNull: true`) with at least one overlay to migrate — a DROP NOT NULL loosens and
+     * needs no staged-row work, and with no overlays there is nothing to backfill or reject.
+     *
+     * `change` for `set not null` carries no default expression, so the DEFAULT is read from the
+     * column's PRE-alter schema (via a to-be-migrated overlay — the same source `dropColumnIdx`
+     * uses, and 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) {
+        if (change.type !== 'alterColumn' || change.setNotNull !== true)
+            return undefined;
+        if (toMigrate.length === 0)
+            return undefined;
+        const overlaySchema = toMigrate[0][1].overlayTable.tableSchema;
+        if (!overlaySchema)
+            return undefined;
+        const colIndex = overlaySchema.columnIndexMap.get(change.columnName.toLowerCase());
+        if (colIndex === undefined)
+            return undefined;
+        const defaultExpr = overlaySchema.columns[colIndex]?.defaultValue;
+        // tryFoldLiteral returns undefined for a non-foldable expr and null for one that folds to
+        // NULL; both mean "no usable literal default" — the staged NULL must reject, not backfill.
+        const folded = defaultExpr ? tryFoldLiteral(defaultExpr) : undefined;
+        const hasDefault = folded !== undefined && folded !== null;
+        return {
+            colIndex,
+            foldedDefault: hasDefault ? folded : null,
+            hasDefault,
+            colName: change.columnName,
+            tableName,
+        };
+    }
     /**
      * 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
@@ -831,10 +1436,17 @@ export class IsolationModule {
      *   rows short-circuit to `null` (the evaluator never runs), and a NOT-NULL-violating
      *   evaluated row throws CONSTRAINT here, atomically. Computed values are discarded.
      *
-     * Non-addColumn changes (`addColumnCtx === undefined`) only run the tombstone guard;
-     * their row translation appends/removes nothing fallible on data grounds.
+     * 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.
      */
-    async validateOverlayMigration(oldState, addColumnCtx) {
+    async validateOverlayMigration(oldState, addColumnCtx, setNotNullCtx) {
         const oldOverlay = oldState.overlayTable;
         const oldOverlaySchema = oldOverlay.tableSchema;
         // Mirror the migrate-loop guard exactly: a clean overlay or one without a queryable
@@ -845,11 +1457,23 @@ export class IsolationModule {
         if (oldTombstoneIdx === undefined) {
             throw new QuereusError(`Tombstone column '${this.tombstoneColumn}' missing from overlay schema`, StatusCode.INTERNAL);
         }
-        if (!addColumnCtx)
+        if (addColumnCtx) {
+            for await (const oldRow of oldOverlay.query(makeFullScanFilterInfo())) {
+                // Discard the result — this is validation only. A NOT NULL violation throws here.
+                await this.computeAddColumnValue(addColumnCtx, oldRow, oldTombstoneIdx);
+            }
             return;
-        for await (const oldRow of oldOverlay.query(this.makeFullScanFilterInfo())) {
-            // Discard the result — this is validation only. A NOT NULL violation throws here.
-            await this.computeAddColumnValue(addColumnCtx, oldRow, oldTombstoneIdx);
+        }
+        // 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.)
+        if (setNotNullCtx && !setNotNullCtx.hasDefault) {
+            for await (const oldRow of oldOverlay.query(makeFullScanFilterInfo())) {
+                if (oldRow[oldTombstoneIdx] === 1)
+                    continue; // tombstone: placeholder NULLs, not a row
+                if (oldRow[setNotNullCtx.colIndex] === null) {
+                    throw new QuereusError(`column ${setNotNullCtx.colName} contains NULL values`, StatusCode.CONSTRAINT);
+                }
+            }
         }
     }
     /**
@@ -885,8 +1509,13 @@ export class IsolationModule {
      * `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) {
+    translateOverlayRow(oldRow, oldTombstoneIdx, change, dropColumnIdx, addColumnValue, setNotNullCtx) {
         const tombstoneValue = oldRow[oldTombstoneIdx];
         const data = Array.from(oldRow.slice(0, oldTombstoneIdx));
         let newData;
@@ -901,8 +1530,17 @@ export class IsolationModule {
                     ? [...data.slice(0, dropColumnIdx), ...data.slice(dropColumnIdx + 1)]
                     : data;
                 break;
-            case 'renameColumn':
             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':
@@ -916,34 +1554,25 @@ export class IsolationModule {
         }
         return [...newData, tombstoneValue];
     }
-    /** Creates a FilterInfo for a full table scan (no constraints). */
-    makeFullScanFilterInfo() {
-        return {
-            idxNum: 0,
-            idxStr: null,
-            constraints: [],
-            args: [],
-            indexInfoOutput: {
-                nConstraint: 0,
-                aConstraint: [],
-                nOrderBy: 0,
-                aOrderBy: [],
-                colUsed: 0n,
-                aConstraintUsage: [],
-                idxNum: 0,
-                idxStr: null,
-                orderByConsumed: false,
-                estimatedCost: 1000000,
-                estimatedRows: 1000000n,
-                idxFlags: 0,
-            },
-        };
-    }
     /**
      * Creates overlay schema from underlying schema.
      * Adds tombstone column and uses unique name to avoid conflicts.
      *
-     * Called by IsolatedTable when lazily creating its overlay.
+     * Called by IsolatedTable when lazily creating its overlay, and by the two overlay-rebuild
+     * paths (`rebuildOverlayForIndexChange`, `migrateOverlayForAlter`).
+     *
+     * 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
+     * (`<tombstone> = 0`), AND-ed onto whatever partial predicate it already carried. A
+     * tombstone is a deletion marker, not a row, so no uniqueness rule may be evaluated over
+     * it: it carries its row's PK and NULL everywhere else, so a UNIQUE structure whose
+     * columns all sit inside the PK would otherwise see two deleted rows as duplicates.
+     * (Non-PK unique columns escaped only because their tombstone key is NULL and SQL treats
+     * NULLs as distinct.) The overlay's PRIMARY KEY uniqueness is NOT narrowed — it must keep
+     * covering tombstones so a re-insert at a tombstoned PK is detected and converted.
+     *
+     * `IsolatedTable.mergedSecondaryIndexQuery` wants exactly the live overlay rows out of
+     * these indexes, so narrowing them is what it already expects.
      */
     createOverlaySchema(baseSchema) {
         const tombstoneColumn = {
@@ -964,14 +1593,70 @@ export class IsolationModule {
         newColumnIndexMap.set(this.tombstoneColumn.toLowerCase(), newColumns.length - 1);
         // 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: `_overlay_${baseSchema.name}_${overlayId}`,
+            name: overlayName,
             columns: newColumns,
             columnIndexMap: newColumnIndexMap,
-            // Copy indexes - they'll be created on the overlay table
-            indexes: baseSchema.indexes,
+            indexes: baseSchema.indexes?.map(idx => ({ ...idx, predicate: andPredicate(rescope(idx.predicate), liveOnly) })),
+            uniqueConstraints: baseSchema.uniqueConstraints?.map(uc => ({ ...uc, predicate: andPredicate(rescope(uc.predicate), liveOnly) })),
         };
     }
+    /**
+     * `<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
+     * the tombstone column name is host-configurable.
+     *
+     * NOTE: the default overlay is a `MemoryTableModule`, which honors `IndexSchema.predicate`
+     * and `UniqueConstraintSchema.predicate`. A host that injects its own `config.overlay`
+     * module must honor them too, or its overlay will re-enforce uniqueness over tombstones.
+     */
+    liveRowPredicate() {
+        return {
+            type: 'binary',
+            operator: '=',
+            left: { type: 'column', name: this.tombstoneColumn },
+            right: { type: 'literal', value: 0 },
+        };
+    }
+}
+function andPredicate(base, extra) {
+    return base ? { type: 'binary', operator: 'AND', left: base, right: extra } : extra;
+}
+/**
+ * Deep-clone `pred`, rewriting every column reference whose `table` qualifier names
+ * `fromName` (case-insensitive) to `toName`. Depth-blind structural walk — a `column`
+ * node is identified by `type === 'column'`; every other node is cloned verbatim. Used
+ * to re-anchor a base table's partial-predicate self-qualifier onto the renamed overlay
+ * table (see {@link IsolationModule.createOverlaySchema}).
+ */
+function rescopePredicateQualifier(pred, fromName, toName) {
+    const fromLower = fromName.toLowerCase();
+    const clone = (v) => {
+        if (v === null || typeof v !== 'object')
+            return v;
+        if (Array.isArray(v))
+            return v.map(clone);
+        const out = {};
+        for (const [k, val] of Object.entries(v)) {
+            out[k] = clone(val);
+        }
+        if (out.type === 'column' && typeof out.table === 'string' && out.table.toLowerCase() === fromLower) {
+            out.table = toName;
+        }
+        return out;
+    };
+    return clone(pred);
 }
 //# sourceMappingURL=isolation-module.js.map