@quereus/isolation 4.4.0 → 4.5.0

package/dist/src/isolation-module.d.ts

@@ -1,4 +1,4 @@
-import type { Database, VirtualTableModule, BaseModuleConfig, TableSchema, TableIndexSchema as IndexSchema, ModuleCapabilities, VirtualTable, BestAccessPlanRequest, BestAccessPlanResult, SchemaChangeInfo, Schema, MappingAdvertisement, LensDeploymentSnapshot, VtabConcurrencyMode, VirtualTableConnection, BackingHost, EffectiveRowSource } from '@quereus/quereus';
+import type { Database, VirtualTableModule, BaseModuleConfig, TableSchema, TableIndexSchema as IndexSchema, ModuleCapabilities, VirtualTable, BestAccessPlanRequest, BestAccessPlanResult, SchemaChangeInfo, Schema, MappingAdvertisement, LensDeploymentSnapshot, VtabConcurrencyMode, VirtualTableConnection, BackingHost, EffectiveRowSource, CatalogObjectKind, ViewSchema } from '@quereus/quereus';
 import type { IsolationModuleConfig } from './isolation-types.js';
 import { IsolatedTable } from './isolated-table.js';
 /**
@@ -40,9 +40,10 @@ export interface ConnectionOverlayState {
      * table on ANY discard path, including {@link IsolationModule.destroy} and
      * {@link IsolationModule.closeAll}, which sweep overlays across multiple db ids
      * and so have no single ambient `db` to hand the overlay module's `destroy`.
-     * Set at every real creation site (`ensureOverlay`, the two rebuild builders);
-     * the default `MemoryTableModule` overlay ignores it, but a host-injected
-     * `config.overlay` keyed per-db needs the overlay's OWN db, not the sweeper's.
+     * Set at every real creation site (`ensureOverlay`, and the ALTER PRIMARY KEY
+     * clean-overlay swap in `replaceOverlayForPrimaryKeyChange`); the default
+     * `MemoryTableModule` overlay ignores it, but a host-injected `config.overlay`
+     * keyed per-db needs the overlay's OWN db, not the sweeper's.
      */
     db: Database;
     /**
@@ -226,7 +227,8 @@ export declare class IsolationModule implements VirtualTableModule<IsolatedTable
      * 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`
@@ -408,6 +410,18 @@ export declare class IsolationModule implements VirtualTableModule<IsolatedTable
      * basis module would silently never hear the deployment.
      */
     notifyLensDeployment(db: Database, logicalSchemaName: string, snapshot: LensDeploymentSnapshot): Promise<void>;
+    /**
+     * 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: Database, kind: CatalogObjectKind, object: ViewSchema | TableSchema): void;
     /**
      * Delegates access plan selection to the underlying module.
      * This ensures the query planner knows about indexes and can generate
@@ -484,42 +498,24 @@ export declare class IsolationModule implements VirtualTableModule<IsolatedTable
      */
     destroy(db: Database, pAux: unknown, moduleName: string, schemaName: string, tableName: string): Promise<void>;
     /**
-     * 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).
-     */
-    private insertIntoRebuiltOverlay;
-    /**
-     * 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.
      */
-    private adoptRebuiltOverlay;
+    private issuerOverlayDriftError;
     /**
-     * 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.
      */
-    private buildRebuildPoisonMessage;
+    private buildInPlaceAdoptPoisonMessage;
     /**
      * 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
@@ -561,9 +557,9 @@ export declare class IsolationModule implements VirtualTableModule<IsolatedTable
      */
     private issuerEffectiveRows;
     /**
-     * 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:
      *
@@ -575,8 +571,8 @@ export declare class IsolationModule implements VirtualTableModule<IsolatedTable
      * 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
@@ -584,18 +580,38 @@ export declare class IsolationModule implements VirtualTableModule<IsolatedTable
      */
     createIndex(db: Database, schemaName: string, tableName: string, indexSchema: IndexSchema, rows?: EffectiveRowSource): Promise<void>;
     /**
-     * Reads back the underlying table instance's post-`createIndex` schema, asserting it now
-     * carries the new index.
+     * 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}).
+     */
+    private createOverlayIndex;
+    /**
+     * 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.
      */
     private assertIndexPresent;
+    /** `schema`'s index named `indexName` (case-insensitively), if it declares one. */
+    private findSchemaIndex;
+    /** Case-insensitive "does `schema` declare an index named `indexName`". */
+    private schemaHasIndex;
     /**
-     * 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
@@ -603,55 +619,94 @@ export declare class IsolationModule implements VirtualTableModule<IsolatedTable
      * 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.
      */
     dropIndex(db: Database, schemaName: string, tableName: string, indexName: string): Promise<void>;
     /**
-     * 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.
+     * 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.
      */
-    private rebuildOverlaysForIndexChange;
+    private dropOverlayIndex;
     /**
-     * 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 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.
      */
-    private rebuildOverlayForIndexChange;
+    private applyIndexChangeToOverlays;
     /**
-     * Delegates ALTER TABLE to the underlying module and migrates any per-connection
+     * 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.
+     */
+    private applyInPlaceOverlayChange;
+    /**
+     * 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
@@ -663,14 +718,35 @@ export declare class IsolationModule implements VirtualTableModule<IsolatedTable
      * check before it mutates anything, so the atomic-abort guarantee above still holds.
      */
     alterTable(db: Database, schemaName: string, tableName: string, change: SchemaChangeInfo, rows?: EffectiveRowSource): Promise<TableSchema>;
+    /**
+     * 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.
+     */
+    private assertColumnNameNotTombstone;
     /**
      * 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.
      */
     private buildAlterPoisonMessage;
     /**
@@ -731,15 +807,6 @@ export declare class IsolationModule implements VirtualTableModule<IsolatedTable
      * Returns how many entries moved.
      */
     private rekeyConnectionScopedMap;
-    /**
-     * 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.
-     */
-    private migrateOverlayForAlter;
     /**
      * Precomputes the per-ALTER constants an `addColumn` overlay backfill needs:
      * the folded literal DEFAULT (the `tryFoldLiteral` of the DEFAULT expr, or `null`
@@ -764,12 +831,55 @@ export declare class IsolationModule implements VirtualTableModule<IsolatedTable
      * 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.
      */
     private deriveSetNotNullBackfill;
+    /**
+     * 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.
+     */
+    private deriveSetDataTypeConvert;
+    /**
+     * 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.
+     */
+    private derivePkRekey;
+    /**
+     * 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.
+     */
+    private collectPkRekeyGroups;
     /**
      * 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
@@ -787,14 +897,37 @@ export declare class IsolationModule implements VirtualTableModule<IsolatedTable
      * 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.
      */
     private validateOverlayMigration;
+    /**
+     * 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.
+     */
+    private stagedLiveRows;
     /**
      * Computes one staged row's value for a freshly added column, mirroring the
      * committed-row backfill (see `base.ts` `recreatePrimaryTreeWithNewColumn` and
@@ -810,25 +943,230 @@ export declare class IsolationModule implements VirtualTableModule<IsolatedTable
      */
     private computeAddColumnValue;
     /**
-     * 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.
+     * 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}.
+     */
+    private forwardColumnShapeToOverlay;
+    /**
+     * 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.
+     */
+    private buildOverlayAddColumnChange;
+    /**
+     * 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}.
+     */
+    private forwardAlterColumnToOverlay;
+    /**
+     * 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.
+     */
+    private dropCollapsedPkRekeyMarkers;
+    /**
+     * 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.
+     */
+    private planPkRekeyMarkerDrops;
+    /** Deletes each planned marker by its OLD primary key through the overlay's ordinary write path. */
+    private applyPkRekeyMarkerDrops;
+    /**
+     * 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.
+     */
+    private reinsertPkRekeyMarkers;
+    /** The overlay's tombstone-flag column index, or INTERNAL if the schema lost it. */
+    private requireTombstoneIndex;
+    /**
+     * 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.
      */
-    private translateOverlayRow;
+    private backfillStagedNotNull;
+    /**
+     * 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}).
+     */
+    private forwardAddConstraintToOverlay;
+    /**
+     * 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.
+     */
+    private installOverlayUniqueConstraint;
+    /**
+     * 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.
+     */
+    private forwardConstraintNameChangeToOverlay;
+    /** Case-insensitive "does `schema` declare a named constraint of ANY class (CHECK / UNIQUE / FOREIGN KEY)". */
+    private schemaHasNamedConstraint;
+    /**
+     * 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).
+     */
+    private replaceOverlayForPrimaryKeyChange;
     /**
      * 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
@@ -842,8 +1180,43 @@ export declare class IsolationModule implements VirtualTableModule<IsolatedTable
      *
      * `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: TableSchema): TableSchema;
+    /**
+     * 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.
+     */
+    private createOverlayIndexSchema;
+    /**
+     * `<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.
+     */
+    private overlayPredicate;
     /**
      * `<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