@quereus/quereus 4.4.1 → 4.6.0

package/dist/src/vtab/memory/layer/manager.js

@@ -1,6 +1,7 @@
-import { buildColumnIndexMap, columnDefToSchema, resolvePkDefaultConflict, resolveNamedConstraintClass, validateCollationForType } from '../../../schema/table.js';
+import { buildColumnIndexMap, columnDefToSchema, resolvePkDefaultConflict, resolveNamedConstraintClass, shiftSchemaIndicesForDrop, rekeySchemaPrimaryKey } from '../../../schema/table.js';
 import { keyParts } from '../types.js';
 import { BTree } from 'inheritree';
+import { createValueSet } from '../../../util/value-set.js';
 import { StatusCode } from '../../../common/types.js';
 import { BaseLayer, iteratePrimaryRows, populateIndexFromRows, populateIndexFromRowsAsync } from './base.js';
 import { TransactionLayer } from './transaction.js';
@@ -8,22 +9,35 @@ import { MemoryTableConnection } from './connection.js';
 import { MemoryVirtualTableConnection } from '../connection.js';
 import { QuereusError } from '../../../common/errors.js';
 import { ConflictResolution } from '../../../common/constants.js';
-import { buildUniqueConstraintSchema, buildForeignKeyConstraintSchema, buildCheckConstraintSchema, validateForeignKeyOverExistingRows, maintainedTableUniqueViolationError } from '../../../schema/constraint-builder.js';
+import { buildUniqueConstraintSchema, buildForeignKeyConstraintSchema, buildCheckConstraintSchema, validateForeignKeyOverExistingRows, maintainedTableUniqueViolationError, formatKeyValue } from '../../../schema/constraint-builder.js';
 import { indexEnforcesUnique, uniqueEnforcementCollations, uniqueEnforcementComparators } from '../../../schema/unique-enforcement.js';
 import { generateIndexDDL, generateDropIndexDDL } from '../../../schema/ddl-generator.js';
-import { compareSqlValues, rowsValueIdentical, normalizeCollationName, comparisonSemanticsDiffer } from '../../../util/comparison.js';
+import { compareSqlValues, rowsValueIdentical, normalizeCollationName } from '../../../util/comparison.js';
 import { scanLayer as scanLayerImpl } from './scan-layer.js';
 import { createPrimaryKeyFunctions, buildPrimaryKeyFromValues, primaryKeyArity } from '../utils/primary-key.js';
 import { createMemoryTableLoggers } from '../utils/logging.js';
-import { tryFoldLiteral } from '../../../parser/utils.js';
-import { validateAndParse, coerceRowToSchema } from '../../../types/validation.js';
-import { inferType } from '../../../types/registry.js';
+import { coerceRowToSchema, foldDefaultToType } from '../../../types/validation.js';
 import { compilePredicate } from '../utils/predicate.js';
 import { renameColumnInIndexPredicates } from '../../../schema/rename-rewriter.js';
 import { MemoryIndex } from '../index.js';
 import { convertRowAtIndex, mapRows, mapRowsAsync } from './row-convert.js';
+import { buildAlterColumnPlan, planColumnAttributeChange } from './alter-column.js';
 let tableManagerCounter = 0;
 const logger = createMemoryTableLoggers('layer:manager');
+/**
+ * The `_uc_<cols>` auto-name of the implicit covering structure realizing an UNNAMED
+ * UNIQUE constraint, resolved over an EXPLICIT column list rather than the manager's
+ * live one — `renameColumn` needs the name under the POST-rename columns, which
+ * `this.tableSchema` does not carry yet.
+ *
+ * The name is derived, never recorded, so it MOVES when a covered column is renamed.
+ * Every consumer re-derives it (see the catalog's `implicitIndexNameForColumns`, which
+ * this mirrors and must stay equal to, and `quereus-store`'s `implicitUniqueIndexName`);
+ * keep this the only spelling of the rule inside this file.
+ */
+function implicitIndexNameOver(uc, columns) {
+    return `_uc_${uc.columns.map(i => columns[i]?.name ?? String(i)).join('_')}`;
+}
 /** A copy of `items` with `value` inserted at `at` (`at === items.length` ⇒ append). */
 function insertValueAt(items, at, value) {
     const out = items.slice();
@@ -178,16 +192,36 @@ export class MemoryTableManager {
             // it would enforce this non-derived UC under the index's collation rather
             // than the declared one. A collation-mismatched index falls through to a
             // distinct `_uc_*` covering index and coexists as its own constraint.
-            const matchingIndex = existingIndexes.find(idx => idx.columns.length === uc.columns.length &&
+            // A filtered (partial) index only covers rows matching its own predicate, so
+            // it's never valid backing for an unfiltered UNIQUE — and a filtered UNIQUE
+            // already owns its index, so it isn't part of this search either (mirrors
+            // `findReusableIndexForUnique` in quereus-store's implicit-unique-index.ts).
+            const matchingIndex = uc.predicate ? undefined : existingIndexes.find(idx => !idx.predicate &&
+                idx.columns.length === uc.columns.length &&
                 idx.columns.every((col, i) => col.index === uc.columns[i]) &&
                 this.indexCollationsMatchDeclared(idx, uc));
+            // The name this constraint's own structure would take, and whoever already holds
+            // it in `newIndexes` — a pre-existing index, or the structure an EARLIER
+            // constraint in this same loop just pushed. A held name is ADOPTED, never pushed
+            // a second time: two entries under one name is the state `importDDL` warns about
+            // (see `SchemaManager.importCatalog`) — `index_info()` then reports neither,
+            // `DROP INDEX` answers `no such index`, and a predicate over the covered column
+            // stops filtering. No write path can produce a duplicate unnamed UNIQUE any more
+            // (`assertNoDuplicateUniqueConstraints` / `assertUniqueConstraintNotDuplicated`
+            // refuse it at every declaration site), so this arm is defence in depth for a
+            // catalog written before those guards: it degrades to one shared structure and
+            // double enforcement rather than to a corrupt index list.
+            const wantedName = uc.name ?? this.implicitIndexNameFor(uc);
+            const claimedIndex = newIndexes.find(idx => idx.name.toLowerCase() === wantedName.toLowerCase());
             let indexName;
             if (matchingIndex) {
                 indexName = matchingIndex.name;
             }
+            else if (claimedIndex) {
+                indexName = claimedIndex.name;
+            }
             else {
-                const colNames = uc.columns.map(i => this.tableSchema.columns[i]?.name ?? String(i));
-                indexName = uc.name ?? `_uc_${colNames.join('_')}`;
+                indexName = wantedName;
                 newIndexes.push({
                     name: indexName,
                     // Carry each column's declared collation so the auto-index — and the
@@ -220,10 +254,70 @@ export class MemoryTableManager {
         const indexName = uc.name ?? this.implicitIndexNameFor(uc);
         return this.implicitCoveringStructures.get(indexName);
     }
-    /** Conventional auto-index name for an unnamed UNIQUE constraint (mirrors {@link ensureUniqueConstraintIndexes}). */
+    /** Conventional auto-index name for an unnamed UNIQUE constraint, over the LIVE columns. */
     implicitIndexNameFor(uc) {
-        const colNames = uc.columns.map(i => this.tableSchema.columns[i]?.name ?? String(i));
-        return `_uc_${colNames.join('_')}`;
+        return implicitIndexNameOver(uc, this.tableSchema.columns);
+    }
+    /**
+     * The materialized covering-index renames a column rename forces: one per UNNAMED
+     * UNIQUE constraint covering the renamed column, from its `_uc_<old cols>` name to
+     * its `_uc_<new cols>` one.
+     *
+     * The auto-name is derived from the live column names and recomputed by every
+     * consumer ({@link implicitIndexNameFor} here, the catalog's exposure map behind
+     * `schema()` / `index_info()`), so leaving the entry under its pre-rename name
+     * severs the constraint↔structure link: the structure stops being recognized as
+     * hidden (it surfaces as a user index and becomes droppable, taking the
+     * constraint's enforcement structure with it) and
+     * {@link getImplicitCoveringStructure} falls through to its column-set fallback.
+     *
+     * Skipped for constraints that do not move: a NAMED one's structure takes the
+     * constraint's name, a `derivedFromIndex` one IS the user's index, and one realized
+     * by a REUSED user index has no `_uc_*` entry to rename (that index keeps its own
+     * name).
+     *
+     * A case-only column rename DOES produce a rename here, even though every name
+     * comparison folds case: the covering-structure map is keyed by the exact derived
+     * string, so leaving `_uc_a` in place while consumers derive `_uc_A` would break
+     * {@link getImplicitCoveringStructure} the same way. It cannot collide — an index
+     * named `_uc_A` could never have been created alongside `_uc_a` in the first place.
+     *
+     * Pure — the caller applies the result to the new index list and, once the schema
+     * swap has succeeded, to {@link implicitCoveringStructures}.
+     */
+    planImplicitCoveringIndexRenames(updatedCols, renamedColIndex) {
+        const renames = [];
+        const indexes = this.tableSchema.indexes ?? [];
+        for (const uc of this.tableSchema.uniqueConstraints ?? []) {
+            if (uc.name !== undefined || uc.derivedFromIndex !== undefined)
+                continue;
+            if (!uc.columns.includes(renamedColIndex))
+                continue;
+            const oldName = implicitIndexNameOver(uc, this.tableSchema.columns);
+            const newName = implicitIndexNameOver(uc, updatedCols);
+            if (oldName === newName)
+                continue;
+            if (!indexes.some(idx => idx.name.toLowerCase() === oldName.toLowerCase()))
+                continue;
+            renames.push({ oldName, newName });
+        }
+        return renames;
+    }
+    /**
+     * Re-keys {@link implicitCoveringStructures} for the renames
+     * {@link planImplicitCoveringIndexRenames} produced — the map is keyed by
+     * constraint identity, which for an unnamed constraint IS the derived index name.
+     * Runs only after the schema swap succeeded, so a failed rename leaves the map
+     * agreeing with the restored schema.
+     */
+    applyImplicitCoveringStructureRenames(renames) {
+        for (const { oldName, newName } of renames) {
+            const rec = this.implicitCoveringStructures.get(oldName);
+            if (!rec)
+                continue;
+            this.implicitCoveringStructures.delete(oldName);
+            this.implicitCoveringStructures.set(newName, { ...rec, indexName: newName });
+        }
     }
     /**
      * True when a same-column-set index's per-column collations are
@@ -504,21 +598,23 @@ export class MemoryTableManager {
             connection.clearSavepoints();
             // Emit data change events after successful commit
             if (changes.length > 0 && this.eventEmitter?.emitDataChange) {
-                // The event contract carries the PK as a component array. Derive the stored
-                // key's shape from the PK arity, never from `Array.isArray` — a JSON PK whose
-                // value is a document like `[1]` is a SCALAR key that happens to be a JS
-                // array, and sniffing it would emit `[1]` where the contract wants `[[1]]`.
-                // NOTE: on the tuple path this hands listeners the STORED key array itself
-                // (`VTableDataChangeEvent.key` is mutable `SqlValue[]`, as it always was).
-                // If a listener is ever seen mutating `event.key`, copy here — an in-place
-                // edit would re-order the primary tree under the comparator.
-                const eventKeyIsTuple = primaryKeyArity(this.tableSchema) !== 1;
+                // The contract's `key` is the primary key projected out of the event's OWN row
+                // image — `newRow` for an insert or an update, `oldRow` for a delete — under the
+                // schema current at DELIVERY (docs/usage.md § Subscribing to Data Changes).
+                // Projecting here rather than replaying the key each write recorded is what
+                // makes an in-place rewrite that changes the key's VALUE but not the row's
+                // identity (a NOCASE 'apple' → 'APPLE', which `recordUpsert` files under the
+                // pre-image key) hand listeners the post-image the table actually holds. It also
+                // re-derives the key across a mid-transaction ALTER PRIMARY KEY for free: the
+                // pending-change images are already reshaped to the delivered schema, so
+                // projecting them through THAT schema's key is the re-key.
+                const pkIndices = this.tableSchema.primaryKeyDefinition.map(def => def.index);
                 for (const change of changes) {
                     const event = {
                         type: change.type,
                         schemaName: this.schemaName,
                         tableName: this._tableName,
-                        key: keyParts(change.pk, eventKeyIsTuple),
+                        key: this.eventKeyFromImage(change, pkIndices),
                         oldRow: change.oldRow,
                         newRow: change.newRow,
                     };
@@ -535,6 +631,25 @@ export class MemoryTableManager {
             logger.debugLog(`[Commit ${connection.connectionId}] Released lock for ${this._tableName}`);
         }
     }
+    /**
+     * The delivered `key` of one pending change: the primary key projected out of the change's
+     * own row image (`newRow` for an insert or an update, `oldRow` for a delete) through
+     * `pkIndices`, the key columns of the schema current at delivery.
+     *
+     * Best-effort, exactly like the pending-change image reshape it consumes: an image the
+     * reshape had to leave at the retired arity cannot be projected, so the event ships with no
+     * key and logs rather than emitting an `undefined` key slot a listener would file a row
+     * under. (A `PendingChange` always carries at least one image — `recordUpsert` sets
+     * `newRow`, `recordDelete` sets `oldRow` — so a missing image means only that.)
+     */
+    eventKeyFromImage(change, pkIndices) {
+        const image = change.newRow ?? change.oldRow;
+        if (image && pkIndices.every(i => i >= 0 && i < image.length)) {
+            return pkIndices.map(i => image[i]);
+        }
+        logger.warn('Commit Transaction', this._tableName, `${change.type} event has no image the delivered primary key can be projected from; delivering it with no key`);
+        return undefined;
+    }
     /** All layers in `layer`'s parent chain, including `layer` itself. */
     layerChainSet(layer) {
         const chain = new Set();
@@ -1057,8 +1172,8 @@ export class MemoryTableManager {
         //    finer index (e.g. BINARY over a NOCASE column) no longer collapses onto
         //    the constraint; resolving by name is robust to `schema.indexes` order
         //    (the finer index may be listed earlier, having been created first).
-        // Both fall through to the column-set scan only when the name does not
-        // resolve (defensive).
+        // Both fall through to the column-set scan below when the name does not
+        // resolve — see there for when that actually happens.
         if (uc.derivedFromIndex) {
             const index = targetLayer.getSecondaryIndex?.(uc.derivedFromIndex);
             if (index)
@@ -1072,14 +1187,40 @@ export class MemoryTableManager {
                     return { kind: 'memory-index', index };
             }
         }
-        // Defensive fallback: match the auto-built `_uc_*` covering index by
-        // column-set when the by-name resolution above did not land.
+        // Fallback: match the covering index by column-set when the by-name
+        // resolution above did not land. Reached more often than "defensive"
+        // suggests — the reuse arms of `ensureUniqueConstraintIndexes` /
+        // `addUniqueConstraint` register an UNNAMED constraint's structure under the
+        // REUSED index's name, which `getImplicitCoveringStructure` (keyed
+        // `_uc_<cols>`) then cannot find; and a reused index that is later dropped
+        // leaves the recorded name unresolvable.
+        //
+        // So this scan must apply the SAME admissibility rule as those two reuse
+        // searches, or it re-opens the hole they close: a FILTERED index holds only
+        // the rows its predicate admits, and `checkSingleUniqueConstraint` skips the
+        // check outright for a row outside the covering index's predicate — adopting
+        // one for an unfiltered UNIQUE silently narrows enforcement to the
+        // predicate's scope. A collation-mismatched index enforces under ITS
+        // collation rather than the declared one, the same way.
+        //
+        // Returning undefined is always SAFE: the caller falls back to the
+        // predicate- and collation-aware full scan, which is slower but exact. So a
+        // filtered constraint does not guess here at all — its own structure is
+        // resolved by name above.
+        if (uc.predicate)
+            return undefined;
         for (const idx of schema.indexes) {
-            if (idx.columns.length === uc.columns.length &&
-                idx.columns.every((col, i) => col.index === uc.columns[i])) {
-                const index = targetLayer.getSecondaryIndex?.(idx.name);
-                return index ? { kind: 'memory-index', index } : undefined;
-            }
+            if (idx.predicate)
+                continue;
+            if (idx.columns.length !== uc.columns.length)
+                continue;
+            if (!idx.columns.every((col, i) => col.index === uc.columns[i]))
+                continue;
+            if (!this.indexCollationsMatchDeclared(idx, uc))
+                continue;
+            const index = targetLayer.getSecondaryIndex?.(idx.name);
+            if (index)
+                return { kind: 'memory-index', index };
         }
         return undefined;
     }
@@ -1315,27 +1456,6 @@ export class MemoryTableManager {
             objectName: newName,
         });
     }
-    /** Iterates all committed rows from the current committed layer (for rebuild). */
-    scanAllRows() {
-        const tree = this._currentCommittedLayer.getModificationTree('primary');
-        if (!tree)
-            return [];
-        const rows = [];
-        for (const path of tree.ascending(tree.first())) {
-            rows.push(tree.at(path));
-        }
-        return rows;
-    }
-    /** Inserts a row directly into the base layer (for rebuild, bypasses transaction).
-     *  Throws on duplicate primary key. */
-    insertRow(row) {
-        const key = this.primaryKeyFunctions.extractFromRow(row);
-        const path = this.baseLayer.primaryTree.find(key);
-        if (path.on) {
-            throw new QuereusError(`UNIQUE constraint failed: ${this._tableName} PK.`, StatusCode.CONSTRAINT);
-        }
-        this.baseLayer.primaryTree.insert(row);
-    }
     /**
      * Atomically replaces the entire committed contents with `rows` by building a
      * fresh {@link BaseLayer} and swapping it in under the SchemaChange latch.
@@ -1504,7 +1624,9 @@ export class MemoryTableManager {
                         oldByKey.insert({ key: this.primaryKeyFunctions.extractFromRow(row), row });
                     }
                     // New-row keys (same PK comparator) for the delete pass's membership test.
-                    const newKeys = new BTree(k => k, this.comparePrimaryKeys);
+                    // Entry is the bare PK value, so it must be a non-freezing set: a
+                    // single-column BLOB PK is a `Uint8Array`, which `Object.freeze` rejects.
+                    const newKeys = createValueSet(this.comparePrimaryKeys);
                     // Insert/update/skip-identical pass, in new-row order.
                     for (const newRow of op.rows) {
                         const key = this.primaryKeyFunctions.extractFromRow(newRow);
@@ -1594,7 +1716,7 @@ export class MemoryTableManager {
                 const result = await this.checkSingleUniqueConstraint(layer, schema, uc, change.newRow, newPrimaryKey, ConflictResolution.ABORT, noEvict, /*allowMvCovering*/ false);
                 if (result) {
                     const colNames = uc.columns.map(i => schema.columns[i]?.name ?? String(i));
-                    throw maintainedTableUniqueViolationError(this.schemaName, this._tableName, uc.name ?? `_uc_${colNames.join('_')}`, colNames, uc.columns.map(i => change.newRow[i]));
+                    throw maintainedTableUniqueViolationError(this.schemaName, this._tableName, uc.name ?? implicitIndexNameOver(uc, schema.columns), colNames, uc.columns.map(i => change.newRow[i]));
                 }
             }
         }
@@ -1628,13 +1750,14 @@ export class MemoryTableManager {
                 throw new QuereusError(`Duplicate column name: ${newColumnSchema.name}`, StatusCode.ERROR);
             }
             let defaultValue = null;
-            let defaultIsLiteral = false;
             const defaultConstraint = columnDefAst.constraints.find(c => c.type === 'default');
             if (defaultConstraint && defaultConstraint.expr) {
-                const folded = tryFoldLiteral(defaultConstraint.expr);
+                // Fold AND convert to the new column's declared type, so the backfilled cell
+                // is the value a fresh INSERT under the same DEFAULT would store. An
+                // unconvertible literal (`integer default 'abc'`) throws MISMATCH here.
+                const folded = foldDefaultToType(defaultConstraint.expr, newColumnSchema.logicalType, newColumnSchema.name);
                 if (folded !== undefined) {
                     defaultValue = folded;
-                    defaultIsLiteral = true;
                 }
                 else {
                     // A non-literal expression default (e.g. `new.<col>`) is written as NULL
@@ -1643,13 +1766,27 @@ export class MemoryTableManager {
                 }
             }
             // Check for NOT NULL constraint (could be explicit or from default behavior).
-            // Allow NOT NULL without DEFAULT if the table is empty (SQLite-compatible).
-            // A non-literal *expression* default (e.g. `new.<col>`) is backfilled per-row by
-            // the engine right after this returns, which then enforces NOT NULL on the
-            // backfilled values — so don't reject it here as "without a DEFAULT".
+            // Allow NOT NULL without a value source if the table is empty (SQLite-compatible).
+            //
+            // `!backfillEvaluator` is the load-bearing clause, and mirrors
+            // `StoreModuleBase.alterAddColumn`: an engine-supplied evaluator — a non-foldable
+            // expression default (`new.<col>`) OR a `generated always as` expression — fills
+            // each existing row right after this returns, and NOT NULL is then enforced on the
+            // computed values (`BaseLayer.recreatePrimaryTreeWithNewColumn`, plus the
+            // pending-row pass below). Asking only which KIND of DEFAULT was written used to
+            // reject a NOT NULL generated column on a non-empty table the evaluator could fill,
+            // and (in the other direction) to admit `default null` on a column that is NOT NULL
+            // only by the session `default_column_nullability`. The gate is value-based now, so
+            // it matches `StoreModuleBase.alterAddColumn` word for word.
+            //
+            // NOTE: that agreement — here, in the store module, and in the engine's own
+            // pre-check in `runAddColumn` — is held together only by section 8 of
+            // `test/logic/41.4-alter-add-column-constraints.sqllogic` running under both
+            // `yarn test` and `yarn test:store`. Nothing enforces it mechanically. If a
+            // fourth site ever needs the same rule, hoist it to one shared predicate
+            // rather than adding another copy.
             const tableHasRows = this.baseLayer.primaryTree.at(this.baseLayer.primaryTree.first()) !== undefined;
-            const hasDefaultExpr = !!(defaultConstraint && defaultConstraint.expr);
-            if (newColumnSchema.notNull && defaultValue === null && !defaultIsLiteral && !hasDefaultExpr && tableHasRows) {
+            if (newColumnSchema.notNull && defaultValue === null && !backfillEvaluator && tableHasRows) {
                 throw new QuereusError(`Cannot add NOT NULL column '${newColumnSchema.name}' to non-empty table `
                     + `'${this.schemaName}.${this._tableName}' without a DEFAULT value`, StatusCode.CONSTRAINT);
             }
@@ -1709,9 +1846,10 @@ export class MemoryTableManager {
                 return insertValueAt(row, targetIndex, value);
             });
             this.baseLayer.updateSchema(finalNewTableSchema);
-            // A non-foldable DEFAULT (e.g. `new.<col>`) backfills each existing row from
-            // its own value via the engine-supplied evaluator; a literal/NULL default
-            // uses the single folded `defaultValue` for every row.
+            // A per-row value source — a non-foldable DEFAULT (e.g. `new.<col>`) or a
+            // `generated always as` expression — backfills each existing row from its own
+            // value via the engine-supplied evaluator; a literal/NULL default uses the
+            // single folded `defaultValue` for every row.
             await this.baseLayer.addColumnToBase(newColumnSchema, defaultValue, backfillEvaluator, targetIndex);
             this.tableSchema = finalNewTableSchema;
             this.initializePrimaryKeyFunctions();
@@ -1758,57 +1896,23 @@ export class MemoryTableManager {
             if (this.tableSchema.primaryKeyDefinition.some(def => def.index === colIndex)) {
                 throw new QuereusError(`Cannot drop PK column "${columnName}".`, StatusCode.CONSTRAINT);
             }
-            const updatedColumnsSchema = this.tableSchema.columns.filter((_, idx) => idx !== colIndex);
-            const updatedPkDefinition = this.tableSchema.primaryKeyDefinition.map(def => ({
-                ...def, index: def.index > colIndex ? def.index - 1 : def.index
-            }));
-            const updatedPrimaryKeyNames = updatedPkDefinition.map(def => updatedColumnsSchema[def.index]?.name).filter(Boolean);
-            // Prune any UNIQUE constraint over the dropped column. A UNIQUE that includes the
-            // dropped column is removed outright (a UNIQUE missing one of its columns is a
-            // different, stronger constraint, not a silently-narrowed one); the auto-built
-            // covering index it backed is torn down with it (see the index exclusion below).
-            // Remaining constraints have their column indices shifted to track the removed slot.
-            // Without this, dropping a uniquely-constrained column (including the ADD COLUMN +
-            // inline-UNIQUE revert path) would strand a constraint whose column index dangles
-            // past the end of the column array.
-            const oldUniqueConstraints = this.tableSchema.uniqueConstraints ?? [];
-            const droppedUcKeys = oldUniqueConstraints
-                .filter(uc => uc.columns.includes(colIndex))
-                .map(uc => uc.name ?? this.implicitIndexNameFor(uc));
-            const remainingUniqueConstraints = oldUniqueConstraints
-                .filter(uc => !uc.columns.includes(colIndex))
-                .map(uc => ({ ...uc, columns: Object.freeze(uc.columns.map(i => i > colIndex ? i - 1 : i)) }));
+            // Renumber every position-bearing field over the removed slot — shared with the
+            // store module's `alterDropColumn`, the mirror of `shiftSchemaIndicesForInsert`.
+            const shifted = shiftSchemaIndicesForDrop(this.tableSchema, colIndex);
+            const updatedPrimaryKeyNames = shifted.primaryKeyDefinition.map(def => shifted.columns[def.index]?.name).filter(Boolean);
             // Drop the implicit covering index of each removed constraint outright (matched by
             // the same `uc.name ?? '_uc_<cols>'` convention DROP CONSTRAINT uses, so a user
-            // index that merely shares columns is left untouched), then shift/prune the rest
-            // over the removed slot. A *single*-column covering index collapses to empty and is
-            // filtered by the trailing `length > 0` regardless; the explicit name exclusion is
-            // what tears down a *multi*-column covering index, which would otherwise survive
-            // orphaned — narrowed to its surviving columns — in `index_info` and on every write.
+            // index that merely shares columns is left untouched). Only this backend needs the
+            // pass: the covering index deliberately carries no `unique: true` flag (enforcement
+            // routes through `uniqueConstraints`), so `shiftSchemaIndicesForDrop`'s own
+            // drop-unique-indexes-outright rule does not see it. A *single*-column covering index
+            // collapses to empty and is dropped by the helper's `length > 0` filter regardless;
+            // this exclusion is what tears down a *multi*-column one, which would otherwise
+            // survive orphaned — narrowed to its surviving columns — in `index_info` and on every
+            // write.
+            const droppedUcKeys = shifted.removedUniqueConstraints.map(uc => uc.name ?? this.implicitIndexNameFor(uc));
             const droppedCoveringIndexNames = new Set(droppedUcKeys.map(k => k.toLowerCase()));
-            const updatedIndexes = (this.tableSchema.indexes || [])
-                .filter(idx => !droppedCoveringIndexNames.has(idx.name.toLowerCase()))
-                .map(idx => ({
-                ...idx,
-                columns: idx.columns
-                    .filter(ic => ic.index !== colIndex)
-                    .map(ic => ({ ...ic, index: ic.index > colIndex ? ic.index - 1 : ic.index }))
-            })).filter(idx => idx.columns.length > 0);
-            // Shift or prune the table's own foreign keys. `foreignKeys[].columns` are indices
-            // into THIS table, so they renumber over the removed slot exactly as the PK and the
-            // UNIQUE constraints above do. A foreign key that loses ANY of its child columns is
-            // removed outright, the same call the UNIQUE pruning makes: a key missing one of its
-            // child columns is a different constraint against the parent's key, not a narrowed
-            // one. Both halves matter — left unshifted, a surviving key's index either dangles
-            // past the end of the column array or, worse, silently slides onto an unrelated
-            // column and starts enforcing against the parent there.
-            //
-            // `referencedColumns` is not touched: enforcement resolves the parent indices on
-            // demand from `referencedColumnNames` against the parent's current schema. See
-            // `shiftSchemaIndicesForInsert`, the ADD-COLUMN-at-a-position mirror of this block.
-            const remainingForeignKeys = (this.tableSchema.foreignKeys ?? [])
-                .filter(fk => !fk.columns.includes(colIndex))
-                .map(fk => ({ ...fk, columns: Object.freeze(fk.columns.map(i => i > colIndex ? i - 1 : i)) }));
+            const updatedIndexes = shifted.indexes.filter(idx => !droppedCoveringIndexNames.has(idx.name.toLowerCase()));
             // NOTE: the generated-column bookkeeping (`generatedColumnDependencies` /
             // `generatedColumnTopoOrder`, also index-keyed) is likewise unshifted, but the
             // engine recomputes it from column names right after this returns
@@ -1818,17 +1922,13 @@ export class MemoryTableManager {
             // `primaryKey` below is not a TableSchema field at all — nothing reads it.
             const finalNewTableSchema = Object.freeze({
                 ...this.tableSchema,
-                columns: Object.freeze(updatedColumnsSchema),
-                columnIndexMap: buildColumnIndexMap(updatedColumnsSchema),
-                primaryKeyDefinition: Object.freeze(updatedPkDefinition),
+                columns: shifted.columns,
+                columnIndexMap: buildColumnIndexMap(shifted.columns),
+                primaryKeyDefinition: shifted.primaryKeyDefinition,
                 primaryKey: Object.freeze(updatedPrimaryKeyNames),
                 indexes: Object.freeze(updatedIndexes),
-                uniqueConstraints: remainingUniqueConstraints.length > 0
-                    ? Object.freeze(remainingUniqueConstraints)
-                    : undefined,
-                foreignKeys: remainingForeignKeys.length > 0
-                    ? Object.freeze(remainingForeignKeys)
-                    : undefined,
+                uniqueConstraints: shifted.uniqueConstraints,
+                foreignKeys: shifted.foreignKeys,
             });
             // Phase 1 of reaching the open transaction's own pending rows. The rewrite here is
             // a pure filter and cannot throw — the split exists for ADD COLUMN's fallible
@@ -1891,8 +1991,17 @@ export class MemoryTableManager {
             const defaultNotNull = defaultNullability === 'not_null';
             const newColumnSchemaAtIndex = columnDefToSchema(newColumnDefAst, defaultNotNull, 'BINARY', (n) => this.db.isCollationRegistered(n));
             const updatedCols = this.tableSchema.columns.map((c, i) => i === colIndex ? newColumnSchemaAtIndex : c);
+            // An unnamed UNIQUE's covering index is named `_uc_<column names>`, so renaming a
+            // covered column moves that name — rewrite the materialized ENTRY, not just its
+            // column references, or the structure is orphaned under the old name (see
+            // {@link planImplicitCoveringIndexRenames}). The engine refuses the statement up
+            // front when the post-rename name is already an index here, so no rename below can
+            // collide with a sibling entry.
+            const coveringRenames = this.planImplicitCoveringIndexRenames(updatedCols, colIndex);
+            const renamedTo = new Map(coveringRenames.map(r => [r.oldName.toLowerCase(), r.newName]));
             const updatedIndexes = (this.tableSchema.indexes || []).map(idx => ({
                 ...idx,
+                name: renamedTo.get(idx.name.toLowerCase()) ?? idx.name,
                 columns: idx.columns.map(ic => ic.index === colIndex ? { ...ic, name: newColumnName } : ic)
             }));
             const finalNewTableSchema = Object.freeze({
@@ -1925,8 +2034,13 @@ export class MemoryTableManager {
             predicatesRewritten = true;
             renameColumnInIndexPredicates(finalNewTableSchema.indexes, this._tableName, oldName, newColumnName, this.schemaName, resolveColumnInSource);
             this.baseLayer.updateSchema(finalNewTableSchema);
+            // Rebuilds every secondary index from the new schema, so a renamed covering index
+            // lands under its new key in the base's index map with no extra rebuild here.
             await this.baseLayer.handleColumnRename();
             this.tableSchema = finalNewTableSchema;
+            // Only now that the swap has succeeded — the catch below restores the old schema
+            // and the map must keep agreeing with it.
+            this.applyImplicitCoveringStructureRenames(coveringRenames);
             this.initializePrimaryKeyFunctions();
             // The DDL transaction's own layers froze their schema at creation; hand them the
             // renamed one, mirroring `handleColumnRename`'s base-side secondary rebuild —
@@ -1971,18 +2085,31 @@ export class MemoryTableManager {
         }
     }
     /**
-     * Apply a single-attribute ALTER COLUMN change (NOT NULL, DEFAULT, DATA TYPE).
+     * Apply a single-attribute ALTER COLUMN change (NOT NULL, DEFAULT, DATA TYPE, COLLATE).
      * The caller supplies exactly one populated change; multi-attribute combinations
      * are rejected by the runtime before reaching this method.
+     *
+     * The body is the ordering contract, and only that: resolve the column → decide the change
+     * and pre-validate it (`alter-column.ts`, which mutates nothing) → probe the re-keyed
+     * structures ({@link validateAlterColumnPlan}) → rebuild the base
+     * ({@link applyAlterColumnToBase}, the first write) → swap this manager's schema →
+     * propagate to open layers ({@link propagateAlterColumnToOpenLayers}) → emit. Each step's
+     * own reasoning lives on the step.
+     *
+     * `validateOnly` runs everything up to (and including) the pre-mutation validation
+     * passes — the effective-row NULL / conversion scans, the re-keyed UNIQUE probe, and
+     * the primary-key re-key legality/representability passes — and returns before the
+     * first mutation, throwing exactly what the real application would throw. The
+     * isolation layer uses it to pre-flight an overlay's migration before the shared
+     * underlying table mutates irreversibly (see `VirtualTable.alterSchema`).
      */
-    async alterColumn(change, rows) {
+    async alterColumn(change, rows, validateOnly = false) {
         if (this.isReadOnly)
             throw new QuereusError(`Table '${this._tableName}' is read-only`, StatusCode.READONLY);
         const lockKey = `MemoryTable.SchemaChange:${this.schemaName}.${this._tableName}`;
         const release = await this.db.latches.acquire(lockKey);
         const originalManagerSchema = this.tableSchema;
-        /** The base primary tree `rebuildPrimaryTreeStrict` replaced, for the catch's rollback. */
-        let basePrimaryTreeBeforeRekey = null;
+        const undo = { basePrimaryTree: null };
         try {
             await this.ensureSchemaChangeSafety();
             const colNameLower = change.columnName.toLowerCase();
@@ -1990,355 +2117,32 @@ export class MemoryTableManager {
             if (colIndex === -1) {
                 throw new QuereusError(`Column '${change.columnName}' not found.`, StatusCode.ERROR);
             }
-            const oldCol = this.tableSchema.columns[colIndex];
-            let newCol = oldCol;
-            // A collation change re-keys any PK / UNIQUE / index that orders by this
-            // column, so it needs the structure re-sort + uniqueness re-validation below.
-            let collationChanged = false;
-            // Set when a SET DATA TYPE moves to a type that ORDERS values differently
-            // (comparisonSemanticsDiffer). Same consequence as a collation change — every
-            // structure keyed by the column has to be re-sorted and its uniqueness re-judged —
-            // but a separate flag, because the index-column collation propagation and the
-            // `pkColumnRekeyed` primary-tree path below belong to SET COLLATE alone. Usually
-            // coincides with `valueConvert` (every non-alias retype sets that); the rebuild
-            // chains below test `valueConvert` FIRST, whose full-rebuild path subsumes the
-            // comparator-only re-sort.
-            let comparatorChanged = false;
-            // Set to the per-value conversion function when a physical value rewrite is needed:
-            // SET DATA TYPE (every non-alias retype — values normalize to the new type's
-            // canonical spelling even when the storage class is unchanged) or SET NOT NULL
-            // backfill (map null → DEFAULT). Both REPLACE the base primary tree with a
-            // freshly-built one (never an in-place mutation, which inheritree forbids while the
-            // open transaction's layers derive from it) and convert the transaction's
-            // own-written rows in every open layer, after `updateSchema` (see the rebuild
-            // section and convertColumnOnOpenLayers).
-            let valueConvert = null;
-            // SET NOT NULL backfill also routes NULL values through `valueConvert`; SET DATA TYPE
-            // leaves nulls untouched. Selects the null-including path in convertBaseRows/convertColumn.
-            let convertNulls = false;
-            if (change.setCollation !== undefined) {
-                const normalized = validateCollationForType(change.setCollation, oldCol.logicalType, change.columnName, (n) => this.db.isCollationRegistered(n));
-                const nameMatches = normalized === (oldCol.collation || 'BINARY');
-                if (nameMatches && oldCol.collationExplicit) {
-                    return; // already explicit in the desired collation — nothing to do
-                }
-                // SET COLLATE is a user declaration with the same standing as a
-                // CREATE-time COLLATE clause, so mark the collation explicit (rank 2 in
-                // the comparison lattice) regardless of the column's creation history —
-                // including SET COLLATE binary. When only the name matches but the column
-                // was not yet explicit (a defaulted collation, or one inherited from
-                // session default_collation), flip the flag as a METADATA-ONLY change:
-                // the collation bytes are unchanged, so keep collationChanged false and
-                // skip the physical re-sort / re-key / UNIQUE re-validation below. A
-                // different name takes the full path AND sets the flag.
-                newCol = { ...oldCol, collation: normalized, collationExplicit: true };
-                collationChanged = !nameMatches;
-            }
-            else if (change.setNotNull !== undefined) {
-                if (change.setNotNull === true && !oldCol.notNull) {
-                    // Tightening: scan the DDL transaction's EFFECTIVE rows for NULLs — committed rows
-                    // overlaid with this transaction's own pending writes — exactly as the setDataType
-                    // arm does. A pending NULL the transaction can SEE rejects the ALTER; one only in a
-                    // row it has DELETED does not block it. `rows` is the wrapper-supplied effective set
-                    // (the isolation overlay); when absent, effectiveDdlRows() is the layered view.
-                    const defaultExpr = oldCol.defaultValue;
-                    const defaultLiteral = defaultExpr ? tryFoldLiteral(defaultExpr) : undefined;
-                    let anyNull = false;
-                    if (rows) {
-                        for await (const row of rows()) {
-                            if (row[colIndex] === null) {
-                                anyNull = true;
-                                break;
-                            }
-                        }
-                    }
-                    else {
-                        for (const row of this.effectiveDdlRows()) {
-                            if (row[colIndex] === null) {
-                                anyNull = true;
-                                break;
-                            }
-                        }
-                    }
-                    if (anyNull) {
-                        if (defaultLiteral === undefined || defaultLiteral === null) {
-                            throw new QuereusError(`column ${change.columnName} contains NULL values`, StatusCode.CONSTRAINT);
-                        }
-                        // Backfill: map null → the folded DEFAULT literal, routed through the SAME
-                        // base-replacement + open-layer conversion machinery setDataType uses — no
-                        // logical-type change, no PK re-key, no in-place base mutation. The old in-place
-                        // `tree.upsert` backfill could not fill the transaction's pending rows (they live
-                        // in the pending layer, not the base) and mutated a base the open layers derive
-                        // from — both fixed by the unified path.
-                        const literal = defaultLiteral;
-                        valueConvert = (v) => (v === null ? literal : v);
-                        convertNulls = true;
-                    }
-                    newCol = { ...oldCol, notNull: true };
-                }
-                else if (change.setNotNull === false && oldCol.notNull) {
-                    if (this.tableSchema.primaryKeyDefinition.some(def => def.index === colIndex)) {
-                        throw new QuereusError(`Cannot DROP NOT NULL on PRIMARY KEY column '${change.columnName}'`, StatusCode.CONSTRAINT);
-                    }
-                    newCol = { ...oldCol, notNull: false };
-                }
-                else {
-                    // No-op (already in desired state).
-                    return;
-                }
-            }
-            else if (change.setDataType !== undefined) {
-                const newLogicalType = inferType(change.setDataType);
-                // Gate on logical-type IDENTITY, not the physical storage class: `inferType`
-                // flattens aliases to the shared type object (`varchar(50)` IS `TEXT_TYPE`,
-                // `bigint` IS `INTEGER_TYPE`), so an alias retype is schema-only — no scan, no
-                // rewrite, no re-key. Every OTHER retype validates AND normalizes every value,
-                // whether or not the storage class changes: a same-class move (text → date)
-                // must reject values the new type refuses ('hello') and rewrite the rest to
-                // the new type's canonical spelling ('2024-06-05T00:00:00Z' → '2024-06-05'),
-                // or the column holds values no INSERT could have produced — unfindable by
-                // equality (DATE compares BINARY over the stored text) and invisible to UNIQUE.
-                // NOTE: the rewrite is unconditional once the types differ, even when every
-                // converted value comes back byte-identical (already-canonical ISO durations on a
-                // text → timespan). That costs a full base-tree + secondary-index rebuild here, and
-                // a physical rewrite of every row on the store leg. If ALTER on large tables ever
-                // shows up as slow, have the convert pre-pass record whether any value actually
-                // moved and, when none did, fall through to the comparator-only re-key.
-                if (newLogicalType !== oldCol.logicalType) {
-                    // Retyping a PRIMARY KEY column moves the key bytes (a class change), the
-                    // tree's ordering (a comparator move), or at minimum the key values'
-                    // canonical spelling — and neither the base rewrite below nor the
-                    // transaction-layer conversion re-keys the primary tree. The engine already
-                    // refuses SET DATA TYPE on any PK column (runtime/emit/alter-table.ts);
-                    // this guards direct module calls. Reject rather than corrupt — the
-                    // type-change analogue of the SET COLLATE primary-key carve-out
-                    // (`alter-collate-pk-in-transaction`).
-                    if (this.tableSchema.primaryKeyDefinition.some(def => def.index === colIndex)) {
-                        throw new QuereusError(`Cannot change the data type of primary key column '${change.columnName}' of table '${this._tableName}'.`, StatusCode.CONSTRAINT);
-                    }
-                    // Every MemoryIndex builds its comparator from the column's LOGICAL type
-                    // (`createTypedComparator(columnSchema.logicalType, …)` in vtab/memory/index.ts),
-                    // so a move to a differently-ordering type (text ↔ timespan: 'PT1H' ≡ 'PT60M';
-                    // text ↔ date/time/datetime: binary, ignoring the column's collation) re-sorts
-                    // every structure keyed by the column. Tracked separately from the value rewrite
-                    // because SET COLLATE shares the re-key machinery without rewriting values.
-                    comparatorChanged = comparisonSemanticsDiffer(oldCol.logicalType, newLogicalType);
-                    const convert = (v) => {
-                        try {
-                            return validateAndParse(v, newLogicalType, change.columnName);
-                        }
-                        catch {
-                            throw new QuereusError(`Cannot convert value in '${change.columnName}' to ${change.setDataType}`, StatusCode.MISMATCH);
-                        }
-                    };
-                    // Validate BEFORE any mutation, over the DDL transaction's EFFECTIVE rows
-                    // (committed rows overlaid with this transaction's own pending writes): an
-                    // unconvertible value the transaction can SEE rejects the ALTER, and one only in
-                    // a row it has DELETED does not block it. A throw here leaves the schema, the base
-                    // and the transaction untouched. `rows` is the wrapper-supplied effective set (the
-                    // isolation overlay); when absent, `effectiveDdlRows()` is the layered view.
-                    if (rows) {
-                        for await (const row of rows()) {
-                            const val = row[colIndex];
-                            if (val !== null)
-                                convert(val);
-                        }
-                    }
-                    else {
-                        for (const row of this.effectiveDdlRows()) {
-                            const val = row[colIndex];
-                            if (val !== null)
-                                convert(val);
-                        }
-                    }
-                    // The base rows are converted below, AFTER `updateSchema`, by REPLACING the base
-                    // primary tree with a fresh one (see the `valueConvert` branch) — never by an
-                    // in-place mutation, which inheritree forbids while the open transaction's layers
-                    // derive from that tree (`MutatedBaseError`). `valueConvert` drives both the base
-                    // replacement and the transaction-layer conversion.
-                    valueConvert = convert;
-                }
-                newCol = { ...oldCol, logicalType: newLogicalType };
-            }
-            else if (change.setDefault !== undefined) {
-                newCol = { ...oldCol, defaultValue: change.setDefault };
-            }
-            else {
-                throw new QuereusError('ALTER COLUMN requires an attribute to change', StatusCode.INTERNAL);
-            }
-            const updatedCols = this.tableSchema.columns.map((c, i) => i === colIndex ? newCol : c);
-            // The changes that move the COMPARATOR the structures are keyed by: SET COLLATE
-            // (values untouched) and a retype into a differently-ordering type (which, unless it
-            // is an alias retype, ALSO rewrites values — `valueConvert` — and its full-rebuild
-            // path below subsumes the comparator-only re-sort). Both need fresh IndexSchema
-            // objects and, when no rewrite runs, the re-validate / re-sort / adopt sequence.
-            const structuresRekeyed = collationChanged || comparatorChanged;
-            // Propagate a collation change into every PK-definition entry and index
-            // column that orders by this column, so their comparators re-key under it.
-            const updatedPkDef = collationChanged
-                ? this.tableSchema.primaryKeyDefinition.map(def => def.index === colIndex ? { ...def, collation: newCol.collation } : def)
-                : this.tableSchema.primaryKeyDefinition;
-            // Every re-keying change also REBUILDS the IndexSchema objects, because their identity is
-            // the discriminator `TransactionLayer.adoptSchema` uses to decide an open layer's
-            // MemoryIndex must be replaced rather than kept (an index it holds under an object the new
-            // schema still carries is left alone). SET COLLATE has a field to write — the index
-            // column's own collation. A comparator-only retype has none: an index column carries no
-            // logical type, it reads the column's from `newSchema.columns`, so the fresh object IS the
-            // whole signal. Without it the base rebuilt its trees under the new comparator while the
-            // DDL transaction's own layers went on comparing the old way — and shadowed the base's
-            // rebuilt trees once the pending layer became the committed head.
-            const updatedIndexes = (structuresRekeyed && this.tableSchema.indexes)
-                ? this.tableSchema.indexes.map(idx => ({
-                    ...idx,
-                    columns: idx.columns.map(ic => (ic.index === colIndex && collationChanged) ? { ...ic, collation: newCol.collation } : ic),
-                }))
-                : this.tableSchema.indexes;
-            const finalNewTableSchema = Object.freeze({
-                ...this.tableSchema,
-                columns: Object.freeze(updatedCols),
-                columnIndexMap: buildColumnIndexMap(updatedCols),
-                primaryKeyDefinition: Object.freeze(updatedPkDef),
-                indexes: updatedIndexes ? Object.freeze(updatedIndexes) : updatedIndexes,
-            });
-            const pkColumnRekeyed = collationChanged && updatedPkDef.some(def => def.index === colIndex);
-            // Validate BEFORE any mutation, over the DDL transaction's EFFECTIVE rows: a pair
-            // the transaction inserted that collides under the NEW schema must reject the
-            // change, and one it has deleted must not block it. A throw here leaves the schema,
-            // the base layer and the index map exactly as they were.
-            //
-            // A value-REWRITING change (`valueConvert`: SET DATA TYPE, or a SET NOT NULL null →
-            // DEFAULT backfill) probes the CONVERTED rows — the same per-row conversion the base
-            // rewrite below applies — under the NEW schema's comparators, so one call covers both
-            // ways an ALTER can collapse two previously-distinct rows: the VALUES converge
-            // (`'1'`/`'01'` → 1; two NULLs → one DEFAULT; '2024-06-05T00:00:00Z' → '2024-06-05')
-            // and/or the COMPARATOR moves (text → timespan makes 'PT1H'/'PT60M' one value). A
-            // same-storage-class retype sets `valueConvert` AND `structuresRekeyed`, so the
-            // rewrite arm is tested FIRST — its converted-row probe subsumes the comparator-only
-            // one. The rebuild that follows is deliberately non-enforcing, so this is the only
-            // guard.
-            //
-            // The comparator-MOVING arm without a rewrite has one trigger left: SET COLLATE. The
-            // values are untouched — hence no `mapRow` — and only the comparator the structures
-            // are keyed by moves. `newSchema` carries the new collations, so the probe indexes
-            // compare as the rebuilt ones will.
-            //
-            // The primary key: SET COLLATE on a PK member gets a stricter pre-pass
-            // (`validateRekeyedPrimaryKey`): no layer in the chain, base included, may hold a
-            // collision. That is what lets every step below succeed unconditionally, and what
-            // `TransactionLayer.rekeyPrimaryKey` relies on. The rewrite arm needs no PK pre-pass
-            // and cannot shadow one: a retype of a PK column is rejected upstream, the backfill
-            // only fires on a column holding NULLs (which a PK member cannot — the engine
-            // enforces NOT NULL on every PK member regardless of the declared nullability), and
-            // `pkColumnRekeyed` is set only by SET COLLATE, which never sets `valueConvert` — so
-            // whenever `pkColumnRekeyed` is true, the `structuresRekeyed` arm still runs.
-            // NOTE: if PK members ever become genuinely nullable, the backfill arm gains a PK
-            // collision path (two NULL keys → one DEFAULT) and needs `validateRekeyedPrimaryKey`
-            // plus a primary-tree re-key of its own.
-            if (valueConvert) {
-                const convert = valueConvert;
-                const nulls = convertNulls;
-                await this.validateRekeyedUniqueStructures(finalNewTableSchema, colIndex, rows, 
-                // Unlike `convertBaseRows`, a conversion failure here is NOT swallowed. Every row
-                // the probe sees is visible to the transaction, and the setDataType pre-pass above
-                // already proved each one convertible, so a throw is unreachable; surfacing it as
-                // MISMATCH still beats probing a stale value that could mask a collision.
-                row => convertRowAtIndex(row, colIndex, convert, nulls));
-            }
-            else if (structuresRekeyed) {
-                await this.validateRekeyedUniqueStructures(finalNewTableSchema, colIndex, rows);
-                // NOTE: `validateRekeyedPrimaryKey` deliberately ignores `rows`. It asserts that no
-                // LAYER of this manager's own chain holds a PK collision under the new comparator —
-                // a physical property of the structures it is about to re-key, which a wrapper's
-                // merged row stream cannot speak to. A wrapper's staged rows live in the wrapper's
-                // own overlay, which enforces the PK itself, so the pair "one staged row + one
-                // committed row that collide only under the new collation" is checked by neither
-                // side. Rejecting it here would need the wrapper to expose its overlay's PK set, not
-                // just its merged rows.
-                if (pkColumnRekeyed)
-                    this.validateRekeyedPrimaryKey(finalNewTableSchema);
-            }
-            this.baseLayer.updateSchema(finalNewTableSchema);
-            // Both arms rebuild the base's structures under the schema `updateSchema` above just
-            // swapped in — each MemoryIndex rebuilds its comparator from the CURRENT schema's
-            // collation and logical type. The secondary rebuilds are NON-enforcing (the pre-pass
-            // above owns uniqueness, and the base's rows are not a subset of the effective rows);
-            // the SET COLLATE PK rebuild is strict, since a PK collision cannot be represented at
-            // all — the pre-pass has already proved the base collision-free, so the strict
-            // rebuild is a live invariant check, not the enforcement path. It runs LAST so its
-            // throw leaves the live tree intact for the catch's rollback.
-            if (valueConvert) {
-                // SET DATA TYPE / SET NOT NULL backfill: convert the committed base rows and REPLACE
-                // the primary tree with a fresh one holding them (not an in-place upsert — inheritree
-                // forbids mutating a base while the open transaction's layers derive from it).
-                // `rebuildPrimaryTreeFromRows` also rebuilds every secondary index from the converted
-                // rows under the new comparators, so index-backed lookups see the new values — which
-                // is why this arm runs first and subsumes `rebuildAllSecondaryIndexes` when a
-                // same-storage-class retype sets `structuresRekeyed` too. The old tree is saved for
-                // the catch's rollback, exactly as the PK-rekey path does.
-                // NOTE: rebuilds EVERY secondary index, not only those covering the altered column;
-                // if a wide-index table ever shows this as slow, filter to indexes whose columns
-                // include colIndex. Mirrors the collationChanged path's unconditional rebuild.
-                //
-                // SET DATA TYPE: a base value that fails to convert is kept as-is — validation over
-                // the effective view already rejected any unconvertible value the transaction can SEE,
-                // so a surviving one is shadowed by a pending delete/overwrite and is never read back
-                // (a ROLLBACK re-exposes it under the new type — DDL is not undone by rollback, the
-                // known behavior of `feat-ddl-transaction-capability`).
-                // SET NOT NULL (`convertNulls`): null base values are mapped to the DEFAULT literal.
-                const convertedBaseRows = this.convertBaseRows(colIndex, valueConvert, convertNulls);
-                basePrimaryTreeBeforeRekey = this.baseLayer.primaryTree;
-                this.baseLayer.rebuildPrimaryTreeFromRows(convertedBaseRows);
-            }
-            else if (structuresRekeyed) {
-                this.baseLayer.rebuildAllSecondaryIndexes();
-                if (pkColumnRekeyed) {
-                    basePrimaryTreeBeforeRekey = this.baseLayer.primaryTree;
-                    this.baseLayer.rebuildPrimaryTreeStrict();
-                }
-            }
-            this.tableSchema = finalNewTableSchema;
+            // Decide + validate, in that order and both before any mutation: `planColumnAttributeChange`
+            // runs the attribute's own pre-validation (the NULL scan, the convertibility scan, the
+            // primary-key carve-outs) over the effective rows, and `validateAlterColumnPlan` runs the
+            // re-keyed UNIQUE / primary-key probes over the schema it produced. Nothing above
+            // `applyAlterColumnToBase` writes, so a throw from either leaves the table as it was.
+            const attributeChange = await planColumnAttributeChange({
+                schema: this.tableSchema,
+                tableName: this._tableName,
+                columnName: change.columnName,
+                colIndex,
+                effectiveRows: this.effectiveRowSource(rows),
+                isCollationRegistered: (n) => this.db.isCollationRegistered(n),
+            }, change);
+            if (attributeChange === null)
+                return; // already in the requested state — nothing to do
+            const plan = buildAlterColumnPlan(this.tableSchema, colIndex, attributeChange);
+            await this.validateAlterColumnPlan(plan, rows);
+            // Dry run ends here: everything above validates without mutating (the one earlier
+            // side effect, ensureSchemaChangeSafety's committed-layer drain, is semantically
+            // neutral bookkeeping), and everything below mutates. See the method doc.
+            if (validateOnly)
+                return;
+            this.applyAlterColumnToBase(plan, undo);
+            this.tableSchema = plan.newSchema;
             this.initializePrimaryKeyFunctions();
-            // The base rebuild handed every secondary index a fresh tree under the new
-            // comparator; the DDL transaction's own layers still inherit the old ones and froze
-            // the old schema at construction. Re-key them, or the rest of the transaction — and
-            // everything after the pending layer becomes the committed head at commit — keeps
-            // comparing under the old collation / old logical type.
-            //
-            // When the altered column is part of the primary key, `rebuildPrimaryTreeStrict` also
-            // swapped the base primary tree object out from under those layers' copy-on-write
-            // bases and invalidated their `pkFunctions`; `rekeyPrimaryKey` rebuilds both, plus
-            // every secondary index (each derives its PK comparator/encoder from the PK
-            // definition). Outside a transaction there are no open layers and both are no-ops.
-            if (valueConvert) {
-                // SET DATA TYPE / SET NOT NULL backfill converted the base above; the DDL
-                // transaction's own open layers still froze the old schema and hold their own-written
-                // rows unconverted. Swap the schema and convert those values so the rest of the
-                // transaction — and the committed head at commit — read the new value. For SET NOT
-                // NULL this fills the transaction's OWN pending NULL rows (which live in the pending
-                // layer, never reached by the old in-place base upsert). `convertColumn` installs the
-                // new schema and rebuilds every one of the layer's secondary indexes from it, so it
-                // subsumes `adoptSchema` when a same-storage-class retype moved the comparators too.
-                // No-op in autocommit.
-                this.convertColumnOnOpenLayers(finalNewTableSchema, colIndex, valueConvert, convertNulls);
-            }
-            else if (structuresRekeyed) {
-                this.adoptSchemaOnOpenLayers(finalNewTableSchema, pkColumnRekeyed);
-            }
-            else {
-                // The remaining changes (SET DEFAULT, DROP NOT NULL, a SET NOT NULL that needed no
-                // backfill, a retype between aliases of one logical type) touch nothing a layer
-                // DERIVES — its index set, its `uniqueConstraints` enforcement and its MemoryIndex
-                // comparators all stay put, and DEFAULT application / NOT NULL enforcement happen
-                // above the module, off the catalog schema. But the frozen schema OBJECT is itself
-                // observable: `commitTransaction` only wraps a swapped-in savepoint snapshot back
-                // into the committed chain when `readLayer.getSchema() === this.tableSchema`. Left
-                // stale, a `rollback to savepoint` taken across one of these ALTERs restores a
-                // snapshot the wrap then skips, and the transaction's staged rows are silently
-                // dropped at COMMIT. Adoption is cheap here — every IndexSchema object is carried
-                // over unchanged, so `adoptSchema` keeps each layer's MemoryIndex and only swaps
-                // the schema reference.
-                this.adoptSchemaOnOpenLayers(finalNewTableSchema);
-            }
+            this.propagateAlterColumnToOpenLayers(plan);
             this.eventEmitter?.emitSchemaChange?.({
                 type: 'alter',
                 objectType: 'column',
@@ -2350,20 +2154,20 @@ export class MemoryTableManager {
         }
         catch (e) {
             // Restore the prior schema and primary tree, then re-key the secondary indexes back
-            // to it. Both pre-passes now run before any mutation, so nothing below `updateSchema`
-            // is expected to throw; the restores are the safety net for an unexpected one (and
-            // for `rebuildPrimaryTreeStrict`'s invariant check, whose precondition
-            // `validateRekeyedPrimaryKey` has already established).
+            // to it. Both pre-passes run before any mutation, so nothing inside
+            // `applyAlterColumnToBase` is expected to throw; the restores are the safety net for
+            // an unexpected one (and for `rebuildPrimaryTreeStrict`'s invariant check, whose
+            // precondition `validateRekeyedPrimaryKey` has already established).
             //
-            // NOTE: a throw from a pre-pass (or from `setNotNull`'s NULL scan) mutated nothing,
+            // NOTE: a throw from a pre-pass (or from `set not null`'s NULL scan) mutated nothing,
             // so this rebuild only swaps the base's index trees for fresh, content-identical
             // ones — an O(rows) cost on a pure rejection. Harmless (a pending layer keeps
             // reading its orphaned but content-correct copy-on-write base), but if a rejected
             // ALTER on a large table ever shows up as slow, gate the rebuild on a "mutation
-            // started" flag set just before `updateSchema`.
+            // started" flag set just before `applyAlterColumnToBase`.
             this.baseLayer.updateSchema(originalManagerSchema);
-            if (basePrimaryTreeBeforeRekey)
-                this.baseLayer.primaryTree = basePrimaryTreeBeforeRekey;
+            if (undo.basePrimaryTree)
+                this.baseLayer.primaryTree = undo.basePrimaryTree;
             this.baseLayer.rebuildAllSecondaryIndexes();
             this.tableSchema = originalManagerSchema;
             this.initializePrimaryKeyFunctions();
@@ -2374,6 +2178,278 @@ export class MemoryTableManager {
             release();
         }
     }
+    /**
+     * Apply `alter table … alter primary key` in place — the table's rows, the open
+     * transaction's pending writes, and its pending change events all survive under the new
+     * key. Follows {@link alterColumn}'s ordering contract: resolve and pre-validate the new
+     * definition (mutating nothing) → probe the re-keyed primary structures
+     * ({@link validateRekeyedPrimaryKey}, the same pass the `set collate` re-key runs) →
+     * rebuild the base → swap this manager's schema → propagate to the open transaction's
+     * layers → emit. What differs from the `set collate` re-key is WHAT moves: the key's
+     * columns rather than its comparator, so each open layer's net deletions and its pending
+     * event log must be re-derived from row images — a two-phase prepare/install pair
+     * ({@link TransactionLayer.prepareRekeyedPrimaryKeyColumns}), with every prepare running
+     * BEFORE the first mutation because a deletion's image resolves only through the intact
+     * old layer chain.
+     *
+     * `validateOnly` runs everything up to (and including) the pre-mutation validation and
+     * returns before the first mutation, throwing exactly what the real application would
+     * throw — the same dry-run contract as {@link alterColumn}'s, for a wrapper (the
+     * isolation layer) that must pre-flight before a shared underlying mutates irreversibly.
+     */
+    async alterPrimaryKey(newPkColumns, rows, validateOnly = false) {
+        if (this.isReadOnly)
+            throw new QuereusError(`Table '${this._tableName}' is read-only`, StatusCode.READONLY);
+        const lockKey = `MemoryTable.SchemaChange:${this.schemaName}.${this._tableName}`;
+        const release = await this.db.latches.acquire(lockKey);
+        const originalManagerSchema = this.tableSchema;
+        const undo = { basePrimaryTree: null };
+        try {
+            await this.ensureSchemaChangeSafety();
+            // NOTE: no early return for a definition equal to the current one (unlike
+            // `alterColumn`'s already-in-the-requested-state exit) — the statement is rare and
+            // its only producer, the declarative differ, emits it solely on a genuine change.
+            // If a caller ever re-issues an unchanged key, add the comparison here: the work
+            // below is a full O(rows × layers) rebuild.
+            const newSchema = this.buildRekeyedPrimaryKeySchema(newPkColumns);
+            // Pre-validate before any mutation: the effective rows decide whether the change
+            // is LEGAL (CONSTRAINT on a visible collision), the manager's own layer chain
+            // whether the re-keyed trees can PHYSICALLY carry it (BUSY when only rows a
+            // rollback must restore collide). A throw leaves everything as it was.
+            await this.validateRekeyedPrimaryKey(newSchema, rows);
+            // Dry run ends here: everything above validates without mutating, everything
+            // below mutates. See the method doc.
+            if (validateOnly)
+                return;
+            // Compute every open layer's re-derived net writes and event log BEFORE the
+            // first mutation: a net deletion's new key comes from the parent's row image at
+            // the old key, which only the intact old chain can still resolve.
+            const newPkFunctions = createPrimaryKeyFunctions(newSchema, this.collationResolver);
+            const plans = this.openTransactionLayersOldestFirst().map(layer => ({
+                layer,
+                prepared: layer.prepareRekeyedPrimaryKeyColumns(newPkFunctions),
+            }));
+            // Base rebuild, mirroring alterColumn's `set collate` arm: secondary indexes
+            // first (each entry's key encoding embeds the primary key), then the strict
+            // primary rebuild LAST so its throw — a live invariant check; the pre-pass has
+            // already proven the base collision-free — leaves the live tree intact for the
+            // rollback below.
+            this.baseLayer.updateSchema(newSchema);
+            this.baseLayer.rebuildAllSecondaryIndexes();
+            undo.basePrimaryTree = this.baseLayer.primaryTree;
+            this.baseLayer.rebuildPrimaryTreeStrict();
+            this.tableSchema = newSchema;
+            this.initializePrimaryKeyFunctions();
+            // Oldest-first (the plans were gathered in that order): each layer's rebuilt tree
+            // inherits copy-on-write from its parent's NEW one. Synchronous and mutation-only.
+            for (const { layer, prepared } of plans) {
+                layer.installRekeyedPrimaryKeyColumns(newSchema, prepared);
+            }
+            this.eventEmitter?.emitSchemaChange?.({
+                type: 'alter',
+                objectType: 'table',
+                schemaName: this.schemaName,
+                objectName: this._tableName,
+            });
+            logger.operation('Alter Primary Key', this._tableName, {
+                columns: newSchema.primaryKeyDefinition.map(def => def.index),
+            });
+        }
+        catch (e) {
+            // Restore the prior schema and primary tree, then re-key the secondary indexes
+            // back to it — the same safety net as alterColumn's catch: both pre-passes run
+            // before any mutation, so nothing in the apply steps is expected to throw.
+            this.baseLayer.updateSchema(originalManagerSchema);
+            if (undo.basePrimaryTree)
+                this.baseLayer.primaryTree = undo.basePrimaryTree;
+            this.baseLayer.rebuildAllSecondaryIndexes();
+            this.tableSchema = originalManagerSchema;
+            this.initializePrimaryKeyFunctions();
+            logger.error('Alter Primary Key', this._tableName, e);
+            throw e;
+        }
+        finally {
+            release();
+        }
+    }
+    /**
+     * Resolve `alter primary key`'s column list against the current schema — bounds, no
+     * duplicates, every member NOT NULL — and return the re-keyed schema. The engine's
+     * emitter validates the same three by column NAME before dispatch; re-checking by index
+     * here keeps a wrapper driving the module API directly (the isolation layer) from
+     * installing an unkeyable definition. The schema construction itself (definition +
+     * per-column flag rebuild, member collations carried) is delegated to the shared
+     * {@link rekeySchemaPrimaryKey}, which the store's native arm uses too.
+     */
+    buildRekeyedPrimaryKeySchema(newPkColumns) {
+        const columns = this.tableSchema.columns;
+        const seen = new Set();
+        for (const pk of newPkColumns) {
+            if (pk.index < 0 || pk.index >= columns.length) {
+                throw new QuereusError(`Primary key column index ${pk.index} is out of bounds for table '${this._tableName}'.`, StatusCode.ERROR);
+            }
+            if (seen.has(pk.index)) {
+                throw new QuereusError(`Duplicate column '${columns[pk.index].name}' in PRIMARY KEY definition`, StatusCode.ERROR);
+            }
+            seen.add(pk.index);
+            if (!columns[pk.index].notNull) {
+                throw new QuereusError(`Column '${columns[pk.index].name}' must be NOT NULL to participate in PRIMARY KEY`, StatusCode.CONSTRAINT);
+            }
+        }
+        return rekeySchemaPrimaryKey(this.tableSchema, newPkColumns);
+    }
+    /**
+     * The re-keyed-structure pre-pass for {@link alterColumn}, over the DDL transaction's EFFECTIVE
+     * rows: a pair the transaction inserted that collides under the NEW schema must reject the
+     * change, and one it has deleted must not block it. Runs before any mutation, so a throw leaves
+     * the schema, the base layer and the index map exactly as they were.
+     *
+     * A value-REWRITING change (`set data type`, or a `set not null` null → DEFAULT backfill) probes
+     * the CONVERTED rows — the same per-row conversion the base rewrite applies — under the NEW
+     * schema's comparators, so one call covers both ways an ALTER can collapse two previously-distinct
+     * rows: the VALUES converge (`'1'`/`'01'` → 1; two NULLs → one DEFAULT;
+     * '2024-06-05T00:00:00Z' → '2024-06-05') and/or the COMPARATOR moves (text → timespan makes
+     * 'PT1H'/'PT60M' one value). A same-storage-class retype sets both `rewrite` and
+     * `structuresRekeyed`, so the rewrite arm is tested FIRST — its converted-row probe subsumes the
+     * comparator-only one. The rebuild that follows is deliberately non-enforcing, so this is the
+     * only guard.
+     *
+     * The comparator-MOVING arm without a rewrite has one trigger left: `set collate`. The values are
+     * untouched — hence no `mapRow` — and only the comparator the structures are keyed by moves.
+     * `newSchema` carries the new collations, so the probe indexes compare as the rebuilt ones will.
+     *
+     * The primary key: `set collate` on a PK member gets a stricter pre-pass
+     * ({@link validateRekeyedPrimaryKey}): no layer in the chain, base included, may hold a collision.
+     * That is what lets every apply step succeed unconditionally, and what
+     * `TransactionLayer.rekeyPrimaryKey` relies on. The rewrite arm needs no PK pre-pass and cannot
+     * shadow one: a retype of a PK column is rejected upstream, the backfill only fires on a column
+     * holding NULLs (which a PK member cannot — the engine enforces NOT NULL on every PK member
+     * regardless of the declared nullability), and `pkColumnRekeyed` is set only by `set collate`,
+     * which never sets `rewrite` — so whenever `pkColumnRekeyed` is true, the `structuresRekeyed` arm
+     * still runs.
+     * NOTE: if PK members ever become genuinely nullable, the backfill arm gains a PK collision path
+     * (two NULL keys → one DEFAULT) and needs `validateRekeyedPrimaryKey` plus a primary-tree re-key
+     * of its own.
+     */
+    async validateAlterColumnPlan(plan, rows) {
+        if (plan.rewrite) {
+            const { convert, convertNulls } = plan.rewrite;
+            await this.validateRekeyedUniqueStructures(plan.newSchema, plan.colIndex, rows, 
+            // Unlike `convertBaseRows`, a conversion failure here is NOT swallowed. Every row
+            // the probe sees is visible to the transaction, and the `set data type` pre-pass
+            // already proved each one convertible, so a throw is unreachable; surfacing it as
+            // MISMATCH still beats probing a stale value that could mask a collision.
+            row => convertRowAtIndex(row, plan.colIndex, convert, convertNulls));
+        }
+        else if (plan.structuresRekeyed) {
+            await this.validateRekeyedUniqueStructures(plan.newSchema, plan.colIndex, rows);
+            // Unlike the secondary-structure pass above — which only ever judges the effective
+            // rows — the PK pass judges TWO row sets: the effective rows (`rows` when a wrapper
+            // supplies them) decide whether the change is LEGAL, and this manager's own layer
+            // chain decides whether the re-keyed trees can PHYSICALLY carry it. See
+            // `validateRekeyedPrimaryKey` for why the sets differ and which status each raises.
+            if (plan.pkColumnRekeyed)
+                await this.validateRekeyedPrimaryKey(plan.newSchema, rows);
+        }
+    }
+    /**
+     * First mutation of {@link alterColumn}: install the new schema on the base layer and rebuild its
+     * structures under it — each MemoryIndex rebuilds its comparator from the CURRENT schema's
+     * collation and logical type. The secondary rebuilds are NON-enforcing ({@link validateAlterColumnPlan}
+     * owns uniqueness, and the base's rows are not a subset of the effective rows); the `set collate`
+     * PK rebuild is strict, since a PK collision cannot be represented at all — the pre-pass has
+     * already proved the base collision-free, so the strict rebuild is a live invariant check, not
+     * the enforcement path. It runs LAST so its throw leaves the live tree intact for the rollback.
+     *
+     * Records the primary tree it is about to REPLACE in `undo` *before* replacing it, so a throw
+     * from either rebuild still leaves the caller's `catch` a tree to restore.
+     */
+    applyAlterColumnToBase(plan, undo) {
+        this.baseLayer.updateSchema(plan.newSchema);
+        if (plan.rewrite) {
+            // `set data type` / `set not null` backfill: convert the committed base rows and REPLACE
+            // the primary tree with a fresh one holding them (not an in-place upsert — inheritree
+            // forbids mutating a base while the open transaction's layers derive from it).
+            // `rebuildPrimaryTreeFromRows` also rebuilds every secondary index from the converted
+            // rows under the new comparators, so index-backed lookups see the new values — which
+            // is why this arm runs first and subsumes `rebuildAllSecondaryIndexes` when a
+            // same-storage-class retype sets `structuresRekeyed` too.
+            // NOTE: rebuilds EVERY secondary index, not only those covering the altered column;
+            // if a wide-index table ever shows this as slow, filter to indexes whose columns
+            // include colIndex. Mirrors the `set collate` path's unconditional rebuild.
+            //
+            // `set data type`: a base value that fails to convert is kept as-is — validation over
+            // the effective view already rejected any unconvertible value the transaction can SEE,
+            // so a surviving one is shadowed by a pending delete/overwrite and is never read back
+            // (a ROLLBACK re-exposes it under the new type — DDL is not undone by rollback, the
+            // known behavior of `feat-ddl-transaction-capability`).
+            // `set not null` (`convertNulls`): null base values are mapped to the DEFAULT literal.
+            const convertedBaseRows = this.convertBaseRows(plan.colIndex, plan.rewrite.convert, plan.rewrite.convertNulls);
+            undo.basePrimaryTree = this.baseLayer.primaryTree;
+            this.baseLayer.rebuildPrimaryTreeFromRows(convertedBaseRows);
+        }
+        else if (plan.structuresRekeyed) {
+            this.baseLayer.rebuildAllSecondaryIndexes();
+            if (plan.pkColumnRekeyed) {
+                undo.basePrimaryTree = this.baseLayer.primaryTree;
+                this.baseLayer.rebuildPrimaryTreeStrict();
+            }
+        }
+    }
+    /**
+     * Hand the post-{@link alterColumn} schema to the DDL transaction's own open layers.
+     *
+     * The base rebuild handed every secondary index a fresh tree under the new comparator; those
+     * layers still inherit the old ones and froze the old schema at construction. Re-key them, or
+     * the rest of the transaction — and everything after the pending layer becomes the committed
+     * head at commit — keeps comparing under the old collation / old logical type.
+     *
+     * When the altered column is part of the primary key, `rebuildPrimaryTreeStrict` also swapped the
+     * base primary tree object out from under those layers' copy-on-write bases and invalidated their
+     * `pkFunctions`; `rekeyPrimaryKey` rebuilds both, plus every secondary index (each derives its PK
+     * comparator/encoder from the PK definition). Outside a transaction there are no open layers and
+     * every arm is a no-op.
+     */
+    propagateAlterColumnToOpenLayers(plan) {
+        if (plan.rewrite) {
+            // `set data type` / `set not null` backfill converted the base; the open layers still hold
+            // their own-written rows unconverted. Swap the schema and convert those values so the rest
+            // of the transaction — and the committed head at commit — read the new value. For
+            // `set not null` this fills the transaction's OWN pending NULL rows (which live in the
+            // pending layer, never reached by an in-place base upsert). `convertColumn` installs the
+            // new schema and rebuilds every one of the layer's secondary indexes from it, so it
+            // subsumes `adoptSchema` when a same-storage-class retype moved the comparators too.
+            this.convertColumnOnOpenLayers(plan.newSchema, plan.colIndex, plan.rewrite.convert, plan.rewrite.convertNulls);
+        }
+        else if (plan.structuresRekeyed) {
+            this.adoptSchemaOnOpenLayers(plan.newSchema, plan.pkColumnRekeyed);
+        }
+        else {
+            // The remaining changes (`set default`, `drop not null`, a `set not null` that needed no
+            // backfill, a retype between aliases of one logical type) touch nothing a layer
+            // DERIVES — its index set, its `uniqueConstraints` enforcement and its MemoryIndex
+            // comparators all stay put, and DEFAULT application / NOT NULL enforcement happen
+            // above the module, off the catalog schema. But the frozen schema OBJECT is itself
+            // observable: `commitTransaction` only wraps a swapped-in savepoint snapshot back
+            // into the committed chain when `readLayer.getSchema() === this.tableSchema`. Left
+            // stale, a `rollback to savepoint` taken across one of these ALTERs restores a
+            // snapshot the wrap then skips, and the transaction's staged rows are silently
+            // dropped at COMMIT. Adoption is cheap here — every IndexSchema object is carried
+            // over unchanged, so `adoptSchema` keeps each layer's MemoryIndex and only swaps
+            // the schema reference.
+            this.adoptSchemaOnOpenLayers(plan.newSchema);
+        }
+    }
+    /**
+     * The rows the `alter column` pre-validation scans judge: `rows` when a wrapper module supplies
+     * them (the isolation overlay holds the transaction's pending rows outside this manager, so only
+     * it can name the rows the issuing connection actually sees), else this manager's own layered
+     * view ({@link effectiveDdlRows}) — which stays a SYNC iterable on purpose, so a scan over it
+     * cannot be interleaved with another connection's write. See `scanEffectiveRows`.
+     */
+    effectiveRowSource(rows) {
+        return rows ?? (() => this.effectiveDdlRows());
+    }
     async createIndex(newIndexSchemaEntry, ifNotExistsFromAst, rows) {
         if (this.isReadOnly)
             throw new QuereusError(`Table '${this._tableName}' is read-only`, StatusCode.READONLY);
@@ -2774,7 +2850,11 @@ export class MemoryTableManager {
         // would under-enforce this non-derived UNIQUE. A collation mismatch falls
         // through to build the distinct `_uc_*` covering index; the user index keeps
         // enforcing its own (stricter) uniqueness independently (matches SQLite).
-        const matchingUniqueIndex = existingIndexes.find(idx => idx.unique &&
+        // A FILTERED (partial) unique index only guarantees uniqueness among the rows
+        // its own predicate admits, so it can't back a full (unfiltered) UNIQUE either —
+        // same reasoning as `ensureUniqueConstraintIndexes` above.
+        const matchingUniqueIndex = uc.predicate ? undefined : existingIndexes.find(idx => idx.unique &&
+            !idx.predicate &&
             idx.columns.length === uc.columns.length &&
             idx.columns.every((col, i) => col.index === uc.columns[i]) &&
             this.indexCollationsMatchDeclared(idx, uc));
@@ -2794,8 +2874,7 @@ export class MemoryTableManager {
             this.adoptSchemaOnOpenLayers(newSchema);
             return;
         }
-        const colNames = uc.columns.map(i => columns[i]?.name ?? String(i));
-        const indexName = uc.name ?? `_uc_${colNames.join('_')}`;
+        const indexName = uc.name ?? implicitIndexNameOver(uc, columns);
         const indexSchema = {
             name: indexName,
             // Carry per-column collation so enforcement honors e.g. NOCASE (mirrors
@@ -3113,24 +3192,41 @@ export class MemoryTableManager {
         }
     }
     /**
-     * PRIMARY KEY arm of the `alter column … set collate` pre-pass. Runs before anything is
-     * mutated, so a rejection leaves the table, the schema and the transaction untouched.
+     * The primary-key re-key pre-pass, shared by both statements that move the key:
+     * `alter column … set collate` on a PK member (the comparator moves) and
+     * `alter table … alter primary key` (the key columns move — {@link alterPrimaryKey}).
+     * Runs before anything is mutated, so a rejection leaves the table, the schema and the
+     * transaction untouched.
      *
-     * The primary tree is a map, not a multi-map, so — unlike a secondary index — it cannot
-     * physically hold two rows whose keys collapse under the new comparator. Every layer the
-     * DDL connection still reads through therefore has to be collision-free, not just the
-     * transaction's effective view:
+     * Asks two questions, in order, over two DIFFERENT row sets:
      *
-     *  1. **The effective view collides** → `CONSTRAINT`. The duplicate is visible to a `select`
-     *     in this transaction; the change is simply illegal.
-     *  2. **A layer beneath it collides** → `BUSY`. Those rows are not visible now, but every
-     *     such layer is the copy-on-write base the view reads through, and one of them may be a
-     *     savepoint snapshot a `rollback to savepoint` must restore. A re-keyed tree could not
-     *     represent the pair at all. Committing (or rolling back) settles the transaction and
-     *     the ALTER can be retried — the same "commit/rollback and retry" posture as
-     *     {@link ensureSchemaChangeSafety}.
+     *  1. **Is the change legal at all?** — probes the rows the DDL transaction can SEE: the
+     *     wrapper-supplied `rows` when a wrapper module (the isolation layer) holds the
+     *     transaction's pending rows outside this manager, otherwise this manager's own
+     *     layered view ({@link effectiveDdlRows}). A duplicate here is visible to a `select`
+     *     in this transaction, so the change is simply illegal → `CONSTRAINT`, naming the
+     *     colliding key.
+     *  2. **Can the structures physically carry it?** — probes every layer of this manager's
+     *     own chain. The primary tree is a map, not a multi-map, so — unlike a secondary
+     *     index — no tree that a `rollback` / `rollback to savepoint` could restore may hold
+     *     two rows whose keys collapse under the new comparator. A collision confined to
+     *     committed rows the transaction has DELETED is therefore refused by physical
+     *     necessity, not because the data is invalid: the base must keep both rows for a
+     *     rollback, and a base re-keyed under the new collation could not represent the pair
+     *     at all → `BUSY` with the same "commit/rollback and retry" posture as
+     *     {@link ensureSchemaChangeSafety}. The persistent store backend asks the same two
+     *     questions with the same statuses (`StoreTable.validateRekeyedPrimaryKey` in
+     *     quereus-store — its committed rows equally survive a rollback); accepting the
+     *     deleted-collider shape instead would take transaction-scoped DDL
+     *     (`backlog/feat-transactional-ddl-native-backends`), which Quereus does not have.
      *
-     * Case 2 is deliberately conservative. The chain holds one immutable layer per statement
+     * The passes judge different sets because a wrapper's effective stream and this manager's
+     * layers genuinely diverge: staged inserts exist only in the stream, deleted committed
+     * rows only in the layers. When `rows` is supplied, the view layer holds the COMMITTED
+     * rows — not a subset of what pass 1 judged — so pass 2 starts AT the view; when `rows`
+     * is absent, pass 1 judged exactly the view's rows and pass 2 starts at its parent.
+     *
+     * Pass 2 is deliberately conservative. The chain holds one immutable layer per statement
      * boundary (see `MemoryTableConnection.createSavepoint`'s eager path), so it rejects any
      * transaction that has held a colliding pair at ANY statement boundary — even one whose
      * final view is clean and whose intermediate layer no savepoint can reach. Narrowing that
@@ -3138,44 +3234,86 @@ export class MemoryTableManager {
      * rebase that savepoint snapshots exist to avoid. The tradeoff is a rare false BUSY on a
      * statement sequence the user can retry after committing, versus losing a row on rollback.
      *
-     * This precondition is also what makes `TransactionLayer.rekeyPrimaryKey`'s replay sound:
-     * with no collisions anywhere in the chain, every primary key resolves to at most one row
-     * in each layer under the new comparator.
+     * This precondition is also what makes the open-layer replays sound — both
+     * `TransactionLayer.rekeyPrimaryKey`'s and `installRekeyedPrimaryKeyColumns`'s: with no
+     * collisions anywhere in the chain, every primary key resolves to at most one row in
+     * each layer under the new definition.
      */
-    validateRekeyedPrimaryKey(newSchema) {
+    async validateRekeyedPrimaryKey(newSchema, rows) {
         const newPkFunctions = createPrimaryKeyFunctions(newSchema, this.collationResolver);
         const connection = this.ddlConnection();
         const view = connection
             ? (connection.pendingTransactionLayer ?? connection.readLayer)
             : this.baseLayer;
-        this.assertNoPrimaryKeyCollision(view, newPkFunctions, StatusCode.CONSTRAINT, `UNIQUE constraint failed: ${this._tableName} primary key collides under new collation`);
+        await this.assertNoPrimaryKeyCollisionInRows(rows ? rows() : this.effectiveDdlRows(), newPkFunctions, primaryKeyArity(newSchema) !== 1);
         // `ensureSchemaChangeSafety` has already drained every committed layer into the base and
-        // rejected sibling connections with open work, so the chain below the view holds only
-        // this transaction's own layers.
-        for (let layer = view.getParent(); layer; layer = layer.getParent()) {
-            this.assertNoPrimaryKeyCollision(layer, newPkFunctions, StatusCode.BUSY, `Cannot change the collation of a primary key column of table ${this._tableName}: `
-                + `rows this transaction has removed still collide under the new collation and must survive a rollback. `
-                + `Commit/rollback and retry.`);
+        // rejected sibling connections with open work, so this walk covers the transaction's own
+        // layers plus the base — every tree a rollback could restore.
+        for (let layer = rows ? view : view.getParent(); layer; layer = layer.getParent()) {
+            this.assertNoPrimaryKeyCollisionInLayer(layer, newPkFunctions);
+        }
+    }
+    /**
+     * A duplicate-key detector over the new primary key functions: feed it rows, and it returns
+     * the key the moment one repeats. Shared by both arms of {@link validateRekeyedPrimaryKey}
+     * so the async (effective-row) arm and the sync (layer-tree) arm cannot disagree about what
+     * counts as a collision.
+     *
+     * NOTE: the probe holds every row it has seen, because the BTree derives its key from the
+     * stored value — so an ALTER over a large table transiently doubles that table's row
+     * references. If a wide table ever makes this the memory peak, key the probe by the PK
+     * encoding (`primaryKeyFunctions.encode`) into a `Set` instead of by the row.
+     */
+    makePrimaryKeyProbe(pkFunctions) {
+        const probe = new BTree((row) => pkFunctions.extractFromRow(row), pkFunctions.compare);
+        return (row) => {
+            const key = pkFunctions.extractFromRow(row);
+            if (probe.get(key) !== undefined)
+                return key;
+            probe.insert(row);
+            return undefined;
+        };
+    }
+    /**
+     * Legality arm of {@link validateRekeyedPrimaryKey}: raises `CONSTRAINT`, naming the key,
+     * when two of the rows the DDL transaction can SEE share a primary key under `pkFunctions`.
+     * Takes a wrapper's merged async stream or this manager's own synchronous layered view.
+     */
+    async assertNoPrimaryKeyCollisionInRows(rows, pkFunctions, keyIsTuple) {
+        const seen = this.makePrimaryKeyProbe(pkFunctions);
+        for await (const row of rows) {
+            const key = seen(row);
+            if (key === undefined)
+                continue;
+            // An empty new key (`alter primary key ()`, the singleton table) has no components
+            // to name: every row IS the one key, so say that rather than render "(key: )".
+            const parts = keyParts(key, keyIsTuple).map(formatKeyValue);
+            const keyDesc = parts.length > 0 ? `(key: ${parts.join(', ')})` : '(the empty key admits one row)';
+            throw new QuereusError(`UNIQUE constraint failed: ${this._tableName} primary key collides under the new key definition ${keyDesc}`, StatusCode.CONSTRAINT);
         }
     }
     /**
-     * Raises `code` when two of `layer`'s rows share a primary key under `pkFunctions`.
+     * Representability arm of {@link validateRekeyedPrimaryKey}: raises `BUSY` when two of
+     * `layer`'s physical rows share a primary key under `pkFunctions`. Its rows are ones a
+     * rollback could restore, not ones the transaction can see, so this is never a statement
+     * about the data's validity — hence the retryable status and wording.
      *
      * NOTE: O(rows) per layer, so O(layers × rows) for a whole chain — one more full pass than
      * the base rebuild the caller is about to do anyway. Fine for a statement this rare; if a
      * deep savepoint stack over a large table ever makes an ALTER slow, note that a layer's rows
      * differ from its parent's only at the keys it wrote, so the walk can be narrowed to those.
      */
-    assertNoPrimaryKeyCollision(layer, pkFunctions, code, message) {
+    assertNoPrimaryKeyCollisionInLayer(layer, pkFunctions) {
         const tree = layer.getModificationTree('primary');
         if (!tree)
             return;
-        const probe = new BTree((row) => pkFunctions.extractFromRow(row), pkFunctions.compare);
+        const seen = this.makePrimaryKeyProbe(pkFunctions);
         for (const row of iteratePrimaryRows(tree)) {
-            const key = pkFunctions.extractFromRow(row);
-            if (probe.get(key) !== undefined)
-                throw new QuereusError(message, code);
-            probe.insert(row);
+            if (seen(row) !== undefined) {
+                throw new QuereusError(`Cannot re-key the primary key of table ${this._tableName}: `
+                    + `rows this transaction has removed still collide under the new key definition and must survive a rollback. `
+                    + `Commit/rollback and retry.`, StatusCode.BUSY);
+            }
         }
     }
     /**