@quereus/store 4.3.1 → 4.3.2

package/dist/src/common/store-module.js

@@ -12,13 +12,107 @@
  *   - {prefix}.__stats__ - Unified stats store (row counts for all tables)
  *   - Catalog store: __catalog__ - DDL metadata keyed by {schema}.{table}
  */
-import { AccessPlanBuilder, QuereusError, StatusCode, buildColumnIndexMap, columnDefToSchema, compilePredicate, inferType, tryFoldLiteral, validateAndParse, buildAdvertisementsFromTags, resolveNamedConstraintClass, validateCollationForType, buildUniqueConstraintSchema, buildForeignKeyConstraintSchema, buildCheckConstraintSchema, validateForeignKeyOverExistingRows, extractColumnLevelCheckConstraints, extractColumnLevelForeignKeys, appendIndexToTableSchema, resolveKeyNormalizer, serializeRowKey, isMaintainedTable } from '@quereus/quereus';
+import { AccessPlanBuilder, QuereusError, StatusCode, buildColumnIndexMap, columnDefToSchema, compilePredicate, inferType, tryFoldLiteral, validateAndParse, buildAdvertisementsFromTags, resolveNamedConstraintClass, validateCollationForType, buildUniqueConstraintSchema, buildForeignKeyConstraintSchema, buildCheckConstraintSchema, validateForeignKeyOverExistingRows, extractColumnLevelCheckConstraints, extractColumnLevelForeignKeys, appendIndexToTableSchema, logicalTypeCanHoldText, serializeRowKey, isMaintainedTable, renameColumnInIndexPredicates, renameTableInIndexPredicates, renameColumnInCheckConstraints, renameTableInCheckConstraints } from '@quereus/quereus';
 import { TransactionCoordinator } from './transaction.js';
+import { StoreConnection } from './store-connection.js';
 import { StoreBackingHost } from './backing-host.js';
-import { StoreTable, resolvePkKeyCollations } from './store-table.js';
-import { buildCatalogKey, buildCatalogScanBounds, buildDataStoreName, buildIndexKey, buildIndexStoreName, buildFullScanBounds, buildStatsKey, buildViewCatalogKey, buildMaterializedViewCatalogKey, parseMaterializedViewCatalogKey, buildMetaCatalogKey, CLEAN_SHUTDOWN_META_NAME, STALE_MVS_META_NAME, classifyCatalogKey, } from './key-builder.js';
+import { StoreTable, resolvePkKeyCollations, columnCanHoldText, keyOrderMatchesCollation, pkOrderPreservingPrefixLength, withImplicitUniqueIndexes, implicitUniqueIndexName } from './store-table.js';
+import { buildCatalogKey, buildCatalogScanBounds, buildDataKey, buildDataStoreName, buildIndexKey, buildIndexStoreName, buildFullScanBounds, buildStatsKey, buildViewCatalogKey, buildMaterializedViewCatalogKey, parseMaterializedViewCatalogKey, buildMetaCatalogKey, CLEAN_SHUTDOWN_META_NAME, STALE_MVS_META_NAME, classifyCatalogKey, } from './key-builder.js';
+import { assertNoUnpairedSurrogate } from './encoding.js';
 import { deserializeRow } from './serialization.js';
 import { generateTableDDL, generateIndexDDL, generateViewDDL, generateMaintainedTableDDL, generateIndexTagsDDL, isHiddenImplicitIndex, exposedImplicitIndexes } from '@quereus/quereus';
+/**
+ * Default serialized-byte budget for a single index-build write batch. Bounds
+ * heap directly: {@link StoreModule.buildIndexEntries} flushes and starts a fresh
+ * batch whenever the accumulated key bytes cross this, so a table larger than
+ * memory never buffers its whole index in one batch. A byte budget (rather than a
+ * fixed entry count) is used because index entries vary in size, so bytes bound
+ * memory more tightly. 8 MiB trades a modest number of extra flushes against peak
+ * memory; override per store with `using store (max_batch_bytes = …)`.
+ */
+const DEFAULT_MAX_BATCH_BYTES = 8 * 1024 * 1024; // 8 MiB
+/**
+ * Map of `lowercased implicit index name → actual name` for every NON-DERIVED
+ * UNIQUE constraint of `schema` — the set of `_uc_*` stores that SHOULD exist for
+ * that constraint set. Derived from `uniqueConstraints` (not `.indexes`), so it is
+ * correct whether or not `schema` is materialized; the diff of two such maps drives
+ * {@link StoreModule.reconcileImplicitUniqueIndexStores}.
+ */
+function implicitUniqueIndexNameMap(schema) {
+    const map = new Map();
+    for (const uc of schema.uniqueConstraints ?? []) {
+        if (uc.derivedFromIndex)
+            continue;
+        const name = implicitUniqueIndexName(schema, uc);
+        map.set(name.toLowerCase(), name);
+    }
+    return map;
+}
+/**
+ * Resolve the index-build batch byte budget from a `max_batch_bytes` module arg.
+ * A missing, non-numeric, or non-positive value falls back to
+ * {@link DEFAULT_MAX_BATCH_BYTES} — a zero or negative budget must NEVER disable
+ * flushing, which would restore the unbounded single-batch behavior this guards
+ * against.
+ */
+function resolveMaxBatchBytes(raw) {
+    let n;
+    if (typeof raw === 'number')
+        n = raw;
+    else if (typeof raw === 'bigint')
+        n = Number(raw);
+    else if (typeof raw === 'string' && raw.trim() !== '')
+        n = Number(raw);
+    else
+        return DEFAULT_MAX_BATCH_BYTES;
+    if (!Number.isFinite(n) || n <= 0)
+        return DEFAULT_MAX_BATCH_BYTES;
+    return Math.floor(n);
+}
+/**
+ * Planner-side constraint operator groups, as `BestAccessPlanRequest.filters` spells
+ * them. Kept as one source of truth for the access-plan code below: `getBestAccessPlan`
+ * classifies each pushed filter with these, and `tryIndexAccessPlan` claims a filter as
+ * handled only when it falls in the group the engine's access-path rule will consume.
+ */
+const EQ_OPS = ['='];
+const LOWER_BOUND_OPS = ['>', '>='];
+const UPPER_BOUND_OPS = ['<', '<='];
+const RANGE_OPS = [...LOWER_BOUND_OPS, ...UPPER_BOUND_OPS];
+/**
+ * Build `handledFilters` by claiming ONLY the constraints `rule-select-access-path`
+ * actually consumes: per seek column the FIRST '=' (equality seek), or the FIRST lower
+ * ('>'/'>=') plus the FIRST upper ('<'/'<=') bound, selected by `colConstraints.find(...)`
+ * in `request.filters` order.
+ *
+ * That rule collapses `handledFilters` into a per-COLUMN set, so a redundant same-column,
+ * same-role constraint marked handled is neither turned into a seek bound nor kept by
+ * `ruleGrowRetrieve` as a residual — its predicate would be LOST (`where v > 10 and v > 30`
+ * would wrongly return the `v > 10` rows; `where v = 20 and v = 30` would wrongly return
+ * the `v = 20` row). The engine now reattaches such orphans defensively, but a module that
+ * over-claims still pays a redundant predicate evaluation per fetched row.
+ *
+ * Claiming must therefore be POSITIONAL and match the rule's first-match pick: claiming the
+ * tighter-but-later duplicate instead would be actively wrong (the rule would still seek on
+ * the earlier one). Any later duplicate stays unhandled so it survives in the residual Filter.
+ */
+function claimFirstPerRole(filters, roles) {
+    const claimed = new Set();
+    for (const { colIdx, ops } of roles) {
+        const i = filters.findIndex(f => f.columnIndex === colIdx && ops.includes(f.op));
+        if (i >= 0)
+            claimed.add(i);
+    }
+    return filters.map((_f, i) => claimed.has(i));
+}
+/** The lower-bound + upper-bound roles a single-column range seek on `colIdx` fills. */
+function rangeRoles(colIdx) {
+    return [{ colIdx, ops: LOWER_BOUND_OPS }, { colIdx, ops: UPPER_BOUND_OPS }];
+}
+/** The one equality role each seek column of an equality/prefix seek fills. */
+function equalityRoles(colIdxs) {
+    return colIdxs.map(colIdx => ({ colIdx, ops: EQ_OPS }));
+}
 /**
  * Generic store module that works with any KVStoreProvider.
  *
@@ -124,6 +218,13 @@ export class StoreModule {
             persistent: true,
             secondaryIndexes: true,
             rangeScans: true,
+            // Worst-case summary across this module's DDL. The row-rewriting ALTER arms
+            // and renameTable call ddlCommitPendingOps(), which commits the WHOLE module
+            // transaction (schema change + every buffered write) at DDL time — a later
+            // rollback undoes nothing. Non-committing DDL (create index, add constraint,
+            // schema-only arms) is merely non-transactional, but the declared value is
+            // the worst case. See docs/store.md § "DDL that implicitly commits".
+            ddlTransactionality: 'auto-commit',
         };
     }
     /**
@@ -383,6 +484,13 @@ export class StoreModule {
         const vtabArgs = {};
         if (options?.collation !== undefined)
             vtabArgs.collation = options.collation;
+        // `options` is the raw DDL arg record (snake_case keys), so read `max_batch_bytes`,
+        // not the parsed `maxBatchBytes` field — the latter is never populated here, which
+        // silently dropped a configured budget across reopen. `?? maxBatchBytes` still honors
+        // a caller that hands in an already-parsed config.
+        const rawMaxBatchBytes = options?.max_batch_bytes ?? options?.maxBatchBytes;
+        if (rawMaxBatchBytes !== undefined)
+            vtabArgs.max_batch_bytes = rawMaxBatchBytes;
         // Resolve the table schema:
         // 1. Use importedTableSchema if provided (from catalog import or runtime)
         // 2. Look up from schemaManager (most common case during runtime queries)
@@ -449,7 +557,9 @@ export class StoreModule {
         // no-sibling case and strictly safer for the sibling case.
         const table = this.tables.get(tableKey);
         const currentSchema = table?.getSchema() ?? db.schemaManager.getTable(schemaName, tableName);
-        const indexNames = (currentSchema?.indexes ?? []).map(i => i.name);
+        // Materialized index list, so the hidden `_uc_*` stores backing plain UNIQUEs are
+        // torn down too — the engine-facing `.indexes` omits them and would leak them.
+        const indexNames = this.materializedIndexNames(table, currentSchema);
         await this.tearDownTableStorage(schemaName, tableName, indexNames);
         // Emit schema change event for table drop
         this.eventEmitter?.emitSchemaChange({
@@ -546,9 +656,17 @@ export class StoreModule {
     }
     /**
      * Creates an index on a store-backed table.
+     *
+     * `rows` — an {@link EffectiveRowSource} supplied by a wrapper module (the isolation
+     * layer) — replaces this module's own rows as the set the UNIQUE duplicate check judges.
+     * When present the check runs UP FRONT, before `getIndexStore` opens the index-store
+     * directory, so a rejection leaves no directory behind; and `buildIndexEntries` then
+     * populates the physical index from this module's own (committed) rows with its in-pass
+     * dup check disabled. Those two row sets legitimately differ — the wrapper's transaction
+     * may have deleted a committed duplicate — and an index entry with no live row behind it
+     * is harmless (see the entry-resolution note in `buildIndexEntries`).
      */
-    async createIndex(db, schemaName, tableName, indexSchema) {
-        const tableKey = `${schemaName}.${tableName}`.toLowerCase();
+    async createIndex(db, schemaName, tableName, indexSchema, rows) {
         const table = this.getOrReconnectTable(db, schemaName, tableName);
         if (!table) {
             throw new QuereusError(`Store table '${tableName}' not found in schema '${schemaName}'`, StatusCode.NOTFOUND);
@@ -562,13 +680,52 @@ export class StoreModule {
         // which opens/creates the directory that `buildIndexEntries` then writes into.
         const indexStoreName = buildIndexStoreName(schemaName, tableName, indexSchema.name);
         this.assertStoreNameFree(db, schemaName, indexStoreName, `index store of new index '${indexSchema.name}' on table '${schemaName}.${tableName}'`);
-        // Create the index store
-        const indexStore = await this.provider.getIndexStore(schemaName, tableName, indexSchema.name);
-        // Build index entries for existing rows
-        const dataStore = await this.getStore(tableKey, table.getConfig());
         const tableSchema = table.getSchema();
         const keyCollation = (table.getConfig().collation || 'NOCASE').toUpperCase();
-        await this.buildIndexEntries(dataStore, indexStore, tableSchema, indexSchema, keyCollation);
+        // Wrapper-supplied rows are the judged set. Validate BEFORE `getIndexStore` so a
+        // rejection leaves no index-store directory behind, and disable the in-pass dup
+        // check below (which would judge this module's committed rows instead).
+        if (rows && indexSchema.unique) {
+            await this.validateUniqueIndexOverRows(rows(), tableSchema, indexSchema, db.getKeyNormalizerResolver());
+        }
+        // Create the index store
+        const indexStore = await this.provider.getIndexStore(schemaName, tableName, indexSchema.name);
+        // Build index entries for every row the table can currently SEE — committed
+        // rows merged with this transaction's pending writes (`iterateEffectiveEntries`).
+        // The committed-only stream would leave a row inserted earlier in an open
+        // transaction unindexed, and `StoreTable.findUniqueConflictViaIndex` trusts the
+        // index to hold every live row: a `CREATE UNIQUE INDEX` would miss a pending
+        // duplicate, and a later insert colliding with that pending row would be
+        // silently ACCEPTED. Entries written here for rows that a subsequent ROLLBACK
+        // discards are harmless: both readers resolve each entry to its live row and
+        // drop it when the row is gone or no longer matches (see `scanIndex`).
+        //
+        // The store is FRESHLY created above, so any build failure — a UNIQUE violation,
+        // an IO error, or a mid-stream flush failure now that the build is chunked — must
+        // tear the whole store down. Nothing else reclaims it: SchemaManager.createIndex
+        // wraps the error but does no teardown, so without this a rejected build leaks a
+        // partial/empty index-store directory. Mirrors dropIndex's teardown.
+        try {
+            await this.buildIndexEntries(table.iterateEffectiveEntries(buildFullScanBounds()), indexStore, tableSchema, indexSchema, keyCollation, db.getKeyNormalizerResolver(), rows !== undefined, table.getConfig().maxBatchBytes ?? DEFAULT_MAX_BATCH_BYTES);
+        }
+        catch (buildError) {
+            // Best-effort teardown: guard it against its own throw so a teardown failure
+            // never masks the original build error the caller must see.
+            try {
+                await table.releaseIndexStore(indexSchema.name);
+                if (this.provider.deleteIndexStore) {
+                    await this.provider.deleteIndexStore(schemaName, tableName, indexSchema.name);
+                }
+                else {
+                    await this.provider.closeIndexStore(schemaName, tableName, indexSchema.name);
+                }
+            }
+            catch (teardownError) {
+                console.warn(`[StoreModule] failed to tear down index store '${indexSchema.name}' on `
+                    + `table '${schemaName}.${tableName}' after a failed CREATE INDEX: ${String(teardownError)}`);
+            }
+            throw buildError;
+        }
         // Refresh the connected table's cached schema so subsequent DML
         // maintains the new index (the engine's schema registry is updated
         // separately by SchemaManager.createIndex, but the StoreTable instance
@@ -656,36 +813,52 @@ export class StoreModule {
     /**
      * Build index entries for all existing rows in a table.
      *
+     * `dataEntries` is the row stream to index. Callers choose its visibility:
+     * `createIndex` passes the table's EFFECTIVE stream (committed + pending, so
+     * an open transaction's rows are indexed too), while `rebuildSecondaryIndexes`
+     * passes the raw committed stream — it runs immediately after an ALTER has
+     * re-encoded the data store in place, and any pending ops still address the
+     * pre-ALTER key bytes.
+     *
      * For UNIQUE indexes, performs an in-pass duplicate check (honoring partial
      * predicates and SQL NULL semantics: multiple NULLs are allowed) and throws
      * CONSTRAINT before any entries are written. Mirrors the memory module's
      * populateNewIndex so `CREATE UNIQUE INDEX` over duplicated data fails
-     * atomically.
+     * atomically. `skipDuplicateCheck` suppresses it: `createIndex` sets it when a
+     * wrapper module supplied the rows to judge, having already validated them (see
+     * {@link validateUniqueIndexOverRows}). Judging `dataEntries` too would reject a
+     * committed duplicate the wrapper's transaction has already deleted.
+     *
+     * `normalizers` MUST be the owning connection's `db.getKeyNormalizerResolver()` —
+     * the same resolver `StoreTable.encodeOptions` carries. A rebuild that resolved
+     * collations any other way would re-encode the PK suffix under different bytes than
+     * the table writes at maintenance time, silently corrupting the index.
      */
-    async buildIndexEntries(dataStore, indexStore, tableSchema, indexSchema, keyCollation) {
+    async buildIndexEntries(dataEntries, indexStore, tableSchema, indexSchema, keyCollation, normalizers, skipDuplicateCheck = false, maxBatchBytes = DEFAULT_MAX_BATCH_BYTES) {
         // Index COLUMN values use the table-level key collation K; the PK SUFFIX uses
         // each PK column's own key collation, so the suffix bytes match the data-store
         // keys (and `StoreTable.updateSecondaryIndexes`' maintenance writes) exactly.
-        const encodeOptions = { collation: keyCollation };
+        const encodeOptions = { collation: keyCollation, normalizers };
         const pkDirections = tableSchema.primaryKeyDefinition.map(pk => !!pk.desc);
         const pkCollations = resolvePkKeyCollations(tableSchema.primaryKeyDefinition, tableSchema.columns, keyCollation);
         const indexDirections = indexSchema.columns.map(col => !!col.desc);
         const predicate = indexSchema.predicate
-            ? compilePredicate(indexSchema.predicate, tableSchema.columns)
+            ? compilePredicate(indexSchema.predicate, tableSchema.columns, tableSchema.name)
             : undefined;
-        const seen = indexSchema.unique ? new Set() : undefined;
-        // Per-column normalizers for the in-pass UNIQUE dup check, drawing each
-        // column's collation from the index column (if it carries one) else the
-        // underlying table column — so the dedup signature honors a per-column
-        // NOCASE/RTRIM collation, matching write-time enforcement.
+        // NOTE: `seen` holds one signature per DISTINCT indexed key for the WHOLE build and
+        // is NOT bounded by the maxBatchBytes chunking below (that bounds only the write
+        // batch). A very large UNIQUE index still spikes memory on this set. Bounding it
+        // needs a sort- or store-probe-based dedup (a separate design), not a batch knob.
+        const seen = (indexSchema.unique && !skipDuplicateCheck) ? new Set() : undefined;
         const indexColIndices = indexSchema.columns.map(col => col.index);
         const indexNormalizers = seen
-            ? indexSchema.columns.map(col => resolveKeyNormalizer(col.collation ?? tableSchema.columns[col.index].collation))
+            ? indexDedupeNormalizers(tableSchema, indexSchema, normalizers)
             : undefined;
-        // Scan all data rows
-        const bounds = buildFullScanBounds();
-        const batch = indexStore.batch();
-        for await (const entry of dataStore.iterate(bounds)) {
+        let batch = indexStore.batch();
+        // Serialized key bytes accumulated in the CURRENT batch. Flushed and reset once it
+        // crosses maxBatchBytes so a table larger than memory never buffers its whole index.
+        let batchBytes = 0;
+        for await (const entry of dataEntries) {
             const row = deserializeRow(entry.value);
             // Partial index: skip rows whose predicate is not unambiguously TRUE.
             if (predicate && predicate.evaluate(row) !== true)
@@ -710,8 +883,29 @@ export class StoreModule {
             }
             // Build and store index key
             const indexKey = buildIndexKey(indexValues, pkValues, encodeOptions, indexDirections, pkDirections, pkCollations);
-            batch.put(indexKey, new Uint8Array(0)); // Index value is empty
+            // Index value = the row's encoded DATA key, so an index scan resolves each
+            // entry back to its base row via a direct data-store read (see
+            // `StoreTable.scanIndex`). Encoded under the same PK directions + per-column
+            // PK collations as `buildDataKey` / `updateSecondaryIndexes`, so the value
+            // byte-matches the data store's key for this row.
+            const dataKey = buildDataKey(pkValues, encodeOptions, pkDirections, pkCollations);
+            batch.put(indexKey, dataKey);
+            // Bound heap: once the accumulated serialized key bytes cross the budget, flush
+            // the batch and start a fresh one. Both callers ITERATE the data store and WRITE
+            // the index store — different stores — so a mid-stream flush never mutates the
+            // stream being read, and this is safe on every provider. A mid-stream flush
+            // failure in `createIndex` is torn down by its try/catch (the whole fresh index
+            // store is deleted); in `rebuildSecondaryIndexes` it leaves a partial-but-
+            // recoverable index (re-run the rebuild — clear + rebuild is idempotent).
+            batchBytes += indexKey.length + dataKey.length;
+            if (batchBytes >= maxBatchBytes) {
+                await batch.write();
+                batch = indexStore.batch();
+                batchBytes = 0;
+            }
         }
+        // Final flush of the residual. May be empty (an empty table, or a build whose last
+        // row exactly hit the budget and flushed) — providers accept an empty write.
         await batch.write();
     }
     /**
@@ -722,549 +916,923 @@ export class StoreModule {
      * COLLATE` on a PK member (a PK column's key collation changes). Shared by both
      * arms so the clear-then-rebuild stays identical. `schema` must already be the
      * post-ALTER schema (its `primaryKeyDefinition` + column collations drive the new
-     * PK-suffix encoding via {@link buildIndexEntries}).
+     * PK-suffix encoding via {@link buildIndexEntries}). `normalizers` is the owning
+     * connection's `db.getKeyNormalizerResolver()` — see {@link buildIndexEntries}.
+     *
+     * NOTE: reads the data store committed-only and writes the index stores outside the
+     * coordinator. Sound only because both callers (the two re-key arms) call
+     * {@link ddlCommitPendingOps} first, so "committed" is "everything live". A caller
+     * that skips that flush would rebuild an index missing its transaction's pending rows.
      */
-    async rebuildSecondaryIndexes(schemaName, tableName, tableKey, table, schema) {
+    async rebuildSecondaryIndexes(schemaName, tableName, table, schema, normalizers) {
         const keyCollation = (table.getConfig().collation || 'NOCASE').toUpperCase();
-        const dataStore = await this.getStore(tableKey, table.getConfig());
+        const dataStore = await this.getStore(schemaName, tableName, table.getConfig());
+        const maxBatchBytes = table.getConfig().maxBatchBytes ?? DEFAULT_MAX_BATCH_BYTES;
         for (const indexSchema of schema.indexes ?? []) {
             const indexStore = await this.getIndexStore(schemaName, tableName, indexSchema.name);
+            // NOTE: this clear pass buffers EVERY existing index key into one batch. It holds
+            // only KEYS (no values), so its peak is far below the value-bearing build pass and
+            // is left unbounded for now. Chunking it is harder than the build: it deletes from
+            // the SAME store it iterates, so a mid-iteration flush risks iterate-while-mutate
+            // semantics that differ per provider (LevelDB snapshots its iterator; IndexedDB may
+            // not). If the index key set ever dominates memory, chunk this with a snapshot-safe
+            // re-seek, not a naive mid-iteration flush.
             const clearBatch = indexStore.batch();
             for await (const entry of indexStore.iterate(buildFullScanBounds())) {
                 clearBatch.delete(entry.key);
             }
             await clearBatch.write();
-            await this.buildIndexEntries(dataStore, indexStore, schema, indexSchema, keyCollation);
+            await this.buildIndexEntries(dataStore.iterate(buildFullScanBounds()), indexStore, schema, indexSchema, keyCollation, normalizers, false, maxBatchBytes);
         }
     }
     /**
-     * Validates the existing rows in `dataStore` against a UNIQUE constraint,
-     * throwing `CONSTRAINT` on the first duplicate before any schema mutation.
-     * Used by `ADD CONSTRAINT UNIQUE` (validate against the current collation) and
-     * by `SET COLLATE` (pass an `updatedSchema` whose altered column carries the
-     * NEW collation, so the dedup is performed under it). Mirrors the duplicate
-     * detection in {@link buildIndexEntries}: a `seen` Set keyed on a per-column
-     * collation-aware signature of the constrained values, with SQL NULL semantics
-     * (a row with any NULL constrained value never counts as a duplicate) and the
-     * partial `predicate` honored.
+     * Validates `rows` against a UNIQUE constraint, throwing `CONSTRAINT` on the first
+     * duplicate before any schema mutation. Used by `ADD CONSTRAINT UNIQUE` (validate
+     * against the current collation) and by `SET COLLATE` (pass an `updatedSchema` whose
+     * altered column carries the NEW collation, so the dedup is performed under it).
+     * Mirrors the duplicate detection in {@link buildIndexEntries}: a `seen` Set keyed on
+     * a per-column collation-aware signature of the constrained values, with SQL NULL
+     * semantics (a row with any NULL constrained value never counts as a duplicate) and
+     * the partial `predicate` honored.
+     *
+     * `rows` MUST be the rows the DDL-issuing connection can SEE. Ordinarily that is this
+     * table's EFFECTIVE stream (committed rows merged with the open transaction's own
+     * pending puts/deletes — `StoreTable.iterateEffectiveEntries`, adapted by
+     * {@link rowsFromEntries}); when a wrapper module holds the pending rows outside this
+     * module it hands them down as an `EffectiveRowSource` instead. Either way, a
+     * committed-only stream would let a duplicate inserted earlier in the same transaction
+     * slip past validation and land in the table once the transaction commits.
      *
      * No index store is written — store UNIQUE enforcement is a full-scan over
      * `uniqueConstraints` at write time. The signature is built by
-     * {@link serializeRowKey} with one normalizer per constrained column drawn from
-     * `tableSchema.columns[idx].collation`, so a per-column NOCASE/RTRIM collation
-     * is honored (matching write-time `compareSqlValues` enforcement). Residual: a
-     * custom comparator-only collation has no string normalizer and falls back to
-     * BINARY for the dedup (see docs/schema.md store-collation note).
-     */
-    async validateUniqueOverExistingRows(dataStore, tableSchema, uc) {
-        const predicate = uc.predicate
-            ? compilePredicate(uc.predicate, tableSchema.columns)
-            : undefined;
-        const normalizers = uc.columns.map(idx => resolveKeyNormalizer(tableSchema.columns[idx].collation));
-        const seen = new Set();
-        for await (const entry of dataStore.iterate(buildFullScanBounds())) {
-            const row = deserializeRow(entry.value);
-            // Partial constraint: only rows the predicate unambiguously accepts count.
-            if (predicate && predicate.evaluate(row) !== true)
-                continue;
-            // serializeRowKey returns null when any constrained column is NULL —
-            // SQL UNIQUE allows multiple NULLs, so those rows never collide.
-            const keySig = serializeRowKey(row, uc.columns, normalizers);
-            if (keySig === null)
-                continue;
-            if (seen.has(keySig)) {
-                const colNames = uc.columns.map(i => tableSchema.columns[i]?.name ?? String(i)).join(', ');
-                throw new QuereusError(`UNIQUE constraint failed: ${tableSchema.name} (${colNames})`, StatusCode.CONSTRAINT);
-            }
-            seen.add(keySig);
+     * {@link serializeRowKey} with one normalizer per constrained column, resolved from
+     * `tableSchema.columns[idx].collation` through the connection's
+     * `db.getKeyNormalizerResolver()`, so a per-column collation registered with
+     * `db.registerCollation` is honored (matching write-time `compareSqlValues`
+     * enforcement). A comparator-only collation raises: rows that cannot be bucketed
+     * cannot be deduped. Columns whose declared type can never hold text take the
+     * identity normalizer and so never raise.
+     */
+    async validateUniqueOverExistingRows(rows, tableSchema, uc, keyNormalizers) {
+        await assertNoDuplicateRows(rows, tableSchema, uc.columns, uc.columns.map(idx => {
+            const column = tableSchema.columns[idx];
+            return keyNormalizers(logicalTypeCanHoldText(column.logicalType) ? column.collation : undefined);
+        }), uc.predicate ? compilePredicate(uc.predicate, tableSchema.columns, tableSchema.name) : undefined);
+    }
+    /**
+     * Index-shaped twin of {@link validateUniqueOverExistingRows}, used by
+     * {@link createIndex} when a wrapper module supplies the rows to judge. Dedupes on the
+     * index's own columns under the index column's COLLATE (falling back to the table
+     * column's), so it enforces exactly what `buildIndexEntries`' suppressed in-pass check
+     * would have — over the wrapper's rows instead of this module's committed ones.
+     */
+    async validateUniqueIndexOverRows(rows, tableSchema, indexSchema, keyNormalizers) {
+        await assertNoDuplicateRows(rows, tableSchema, indexSchema.columns.map(col => col.index), indexDedupeNormalizers(tableSchema, indexSchema, keyNormalizers), indexSchema.predicate ? compilePredicate(indexSchema.predicate, tableSchema.columns, tableSchema.name) : undefined);
+    }
+    /**
+     * Flush the module's buffered writes before a DDL operation that physically
+     * rewrites or relocates storage.
+     *
+     * Such a DDL cannot honor the coordinator's buffer: pending ops are
+     * `(keyBytes, valueBytes, store)` triples computed at DML time under the
+     * PRE-DDL schema, and every physical rewrite (`StoreTable.rekeyRows` /
+     * `migrateRows`, the provider's directory move) reads and writes the COMMITTED
+     * store directly. Replaying stale-schema ops over the rewritten store on the
+     * eventual commit corrupts, loses, or misfiles those rows. So an `ALTER TABLE`
+     * that touches storage is effectively DDL-committing on a store-backed table:
+     * flush NOW, before the first physical read, so the rewrite sees every live row
+     * and there is nothing left to replay afterwards.
+     *
+     * Consequences, both deliberate:
+     * - The coordinator is module-wide, so this commits the WHOLE module
+     *   transaction — every table's pending ops, not just the altered/renamed
+     *   table's — in one all-or-nothing batch. An ALTER cannot half-commit some
+     *   sibling tables.
+     * - Validation running AFTER this point (e.g. `rekeyRows`' duplicate-key pass,
+     *   which must see pending rows because a pending insert can itself be the
+     *   duplicate) throws with the enclosing transaction already flushed. The store
+     *   stays unmutated — only the transaction is gone. Validation that does NOT
+     *   need pending rows belongs before the call, so the transaction survives it.
+     *
+     * Subsequent `commit()` calls on the same coordinator are no-ops
+     * (`inTransaction` is cleared), which keeps the enclosing transaction safe.
+     * The savepoint stack is cleared too, so a later `ROLLBACK TO` / `RELEASE` that
+     * the engine still broadcasts warns and degrades rather than throwing — see
+     * `TransactionCoordinator.rollbackToSavepoint`, which mirrors the memory
+     * module's identical posture.
+     */
+    async ddlCommitPendingOps() {
+        if (this.moduleCoordinator?.isInTransaction()) {
+            await this.moduleCoordinator.commit();
         }
     }
     /**
-     * Alters an existing store table's structure (ADD/DROP/RENAME COLUMN).
-     * Performs eager row migration for ADD and DROP, schema-only update for RENAME.
-     * Returns the updated TableSchema for the engine to register.
+     * Alters an existing store table's structure. Resolves the table, captures the
+     * pre-alter schema, and dispatches to the per-change-type `alter*` helper below;
+     * the helper does the arm's work (row migration, physical re-key, constraint
+     * validation, DDL persist) and returns the updated TableSchema for the engine to
+     * register. The shared preamble (schema subscription, reconnect, not-found throw,
+     * `defaultNotNull`) lives here so every arm sees the same resolved state.
      */
-    async alterTable(db, schemaName, tableName, change) {
+    async alterTable(db, schemaName, tableName, change, rows) {
         this.ensureSchemaSubscription(db);
-        const tableKey = `${schemaName}.${tableName}`.toLowerCase();
         const table = this.getOrReconnectTable(db, schemaName, tableName);
         if (!table) {
             throw new QuereusError(`Store table '${tableName}' not found in schema '${schemaName}'. Cannot alter.`, StatusCode.ERROR);
         }
+        // The engine-facing schema carries no `_uc_*` (the store keeps the materialized
+        // enforcement copy internal), so the arms build `updatedSchema` off a clean schema
+        // exactly as before this feature; `table.updateSchema` recomputes the enforcement
+        // copy, and {@link reconcileImplicitUniqueIndexStores} (below) moves the physical
+        // stores for any constraint-set change.
         const oldSchema = table.getSchema();
         const defaultNotNull = db.options.getStringOption('default_column_nullability') === 'not_null';
+        let updated;
         switch (change.type) {
-            case 'addColumn': {
-                // Honor the session `default_collation` for an ADD COLUMN that omits an
-                // explicit COLLATE, matching the CREATE path so an ADD-COLUMN-ed text column
-                // gets the same collation a CREATE-d one would. The persisted DDL re-emits an
-                // explicit COLLATE for any non-BINARY collation, so reopen stays stable.
-                const newColSchema = columnDefToSchema(change.columnDef, defaultNotNull, db.options.getStringOption('default_collation'));
-                // Extract default value from column def constraints. Use the shared
-                // `tryFoldLiteral` helper so signed numerics like `-123.0`
-                // (a UnaryExpr in the AST) are recognized — matching the
-                // memory-mode path and the engine-level ALTER validation.
-                let defaultValue = null;
-                const defaultConstraint = change.columnDef.constraints?.find(c => c.type === 'default');
-                if (defaultConstraint?.expr) {
-                    const folded = tryFoldLiteral(defaultConstraint.expr);
-                    if (folded !== undefined) {
-                        defaultValue = folded;
-                    }
-                }
-                // A non-foldable DEFAULT (e.g. `new.<col>`) backfills each existing row from
-                // its own value via the engine-supplied evaluator (mirrors the memory path).
-                const backfillEvaluator = change.backfillEvaluator;
-                // Refuse NOT NULL without a usable DEFAULT on a non-empty table
-                // (SQLite-compatible). A per-row evaluator IS usable — its NOT NULL is enforced
-                // per row during migration — so it is exempt from this no-default rejection.
-                if (newColSchema.notNull && defaultValue === null && !backfillEvaluator) {
-                    if (await table.hasAnyRows()) {
-                        throw new QuereusError(`Cannot add NOT NULL column '${newColSchema.name}' to non-empty table `
-                            + `'${schemaName}.${tableName}' without a DEFAULT value`, StatusCode.CONSTRAINT);
-                    }
-                }
-                // Build updated schema: append new column
-                const updatedColumns = Object.freeze([...oldSchema.columns, newColSchema]);
-                const updatedSchema = {
-                    ...oldSchema,
-                    columns: updatedColumns,
-                    columnIndexMap: buildColumnIndexMap(updatedColumns),
-                };
-                // Extract any column-level CHECK / FK to persist (see the persist block below).
-                // Hoisted above the row migration so a malformed constraint (e.g. a multi-column
-                // FK on a single ADD COLUMN, which `extractColumnLevelForeignKeys` rejects) throws
-                // BEFORE any rows are migrated or the in-memory schema is swapped — validate-before-
-                // mutate, matching the engine's ordering in `runAddColumn`.
-                const newCheckConstraints = extractColumnLevelCheckConstraints(change.columnDef);
-                const newForeignKeys = extractColumnLevelForeignKeys(change.columnDef, schemaName);
-                // Migrate rows: append the new column's value — a single literal default, or a
-                // per-row value derived from the existing row when a backfill evaluator is set.
-                const remap = buildColumnRemap(oldSchema.columns.map(c => c.name), updatedColumns.map(c => c.name));
-                await table.migrateRows(remap, defaultValue, backfillEvaluator
-                    ? { evaluator: backfillEvaluator, notNull: newColSchema.notNull, columnName: newColSchema.name }
-                    : undefined);
-                // Update table schema (column-only) and persist DDL.
-                //
-                // The engine's `runAddColumn` re-merges the column-level FK/CHECK extracted
-                // from `columnDef.constraints` into the LIVE in-memory schema AFTER this hook
-                // returns, so the schema handed back to it must stay column-only — returning a
-                // constrained schema would double the constraint in the live SchemaManager (and,
-                // on the next persist, in the DDL). But that engine-side merge is in-memory only:
-                // it never reaches the catalog, so persistence must carry the column-level
-                // CHECK/FK itself or they vanish on `rehydrateCatalog`. Build a separate
-                // `persistedSchema` for `saveTableDDL` when (and only when) the column declares
-                // such a constraint; the common path persists `updatedSchema` unchanged. This is
-                // unconditional on the default kind — a per-row (evaluator) DEFAULT extracts the
-                // same AST constraints as a literal one.
-                table.updateSchema(updatedSchema);
-                let persistedSchema = updatedSchema;
-                if (newCheckConstraints.length > 0 || newForeignKeys.length > 0) {
-                    // The new column is appended last; resolve each FK's child column to its index
-                    // (matching how the engine resolves `resolvedForeignKeys` via columnIndexMap).
-                    const newColIdx = updatedColumns.length - 1;
-                    const resolvedForeignKeys = newForeignKeys.map(fk => ({ ...fk, columns: Object.freeze([newColIdx]) }));
-                    persistedSchema = {
-                        ...updatedSchema,
-                        checkConstraints: Object.freeze([...updatedSchema.checkConstraints, ...newCheckConstraints]),
-                        foreignKeys: Object.freeze([...(updatedSchema.foreignKeys ?? []), ...resolvedForeignKeys]),
-                    };
-                }
-                await this.saveTableDDL(persistedSchema);
-                this.eventEmitter?.emitSchemaChange({
-                    type: 'alter',
-                    objectType: 'table',
-                    schemaName,
-                    objectName: tableName,
-                });
-                return updatedSchema;
-            }
-            case 'dropColumn': {
-                const colNameLower = change.columnName.toLowerCase();
-                const colIndex = oldSchema.columns.findIndex(c => c.name.toLowerCase() === colNameLower);
-                if (colIndex === -1) {
-                    throw new QuereusError(`Column '${change.columnName}' not found.`, StatusCode.ERROR);
-                }
-                // Build updated schema: remove column and reindex PK/indexes
-                // Filter by original index BEFORE remapping to avoid incorrectly
-                // removing columns that remap to the dropped column's position.
-                const updatedColumns = oldSchema.columns.filter((_, idx) => idx !== colIndex);
-                const updatedPkDef = oldSchema.primaryKeyDefinition
-                    .filter(def => def.index !== colIndex)
-                    .map(def => ({
-                    ...def,
-                    index: def.index > colIndex ? def.index - 1 : def.index,
-                }));
-                const updatedIndexes = (oldSchema.indexes || [])
-                    .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);
-                // Prune any UNIQUE constraint over the dropped column, mirroring the index
-                // filtering above. Store-backed UNIQUE is enforced by a full scan over
-                // `uniqueConstraints`, so a stranded constraint whose column index dangles past
-                // the column array would break the next insert's validation (and the persisted
-                // DDL). A UNIQUE that includes the dropped column is removed outright; remaining
-                // constraints have their column indices shifted to track the removed slot. This
-                // also covers the engine's ADD COLUMN + inline-UNIQUE revert, which drops the
-                // just-added (uniquely-constrained) column.
-                const updatedUniqueConstraints = (oldSchema.uniqueConstraints ?? [])
-                    .filter(uc => !uc.columns.includes(colIndex))
-                    .map(uc => ({ ...uc, columns: Object.freeze(uc.columns.map(i => i > colIndex ? i - 1 : i)) }));
-                const updatedSchema = {
-                    ...oldSchema,
-                    columns: Object.freeze(updatedColumns),
-                    columnIndexMap: buildColumnIndexMap(updatedColumns),
-                    primaryKeyDefinition: Object.freeze(updatedPkDef),
-                    indexes: Object.freeze(updatedIndexes),
-                    uniqueConstraints: updatedUniqueConstraints.length > 0
-                        ? Object.freeze(updatedUniqueConstraints)
-                        : undefined,
-                };
-                // Migrate rows: remove the dropped column slot
-                const remap = buildColumnRemap(oldSchema.columns.map(c => c.name), updatedColumns.map(c => c.name));
-                await table.migrateRows(remap, null);
-                // Update table schema and persist DDL
-                table.updateSchema(updatedSchema);
-                await this.saveTableDDL(updatedSchema);
-                this.eventEmitter?.emitSchemaChange({
-                    type: 'alter',
-                    objectType: 'table',
-                    schemaName,
-                    objectName: tableName,
-                });
-                return updatedSchema;
+            case 'addColumn':
+                updated = await this.alterAddColumn(db, schemaName, tableName, table, oldSchema, change, defaultNotNull);
+                break;
+            case 'dropColumn':
+                updated = await this.alterDropColumn(schemaName, tableName, table, oldSchema, change);
+                break;
+            case 'renameColumn':
+                updated = await this.alterRenameColumn(db, schemaName, tableName, table, oldSchema, change, defaultNotNull);
+                break;
+            case 'alterPrimaryKey':
+                updated = await this.alterPrimaryKeyChange(db, schemaName, tableName, table, oldSchema, change);
+                break;
+            case 'addConstraint':
+                updated = await this.alterAddConstraint(db, schemaName, tableName, table, oldSchema, change, rows);
+                break;
+            case 'dropConstraint':
+                updated = await this.alterDropConstraint(schemaName, tableName, table, oldSchema, change);
+                break;
+            case 'renameConstraint':
+                updated = await this.alterRenameConstraint(schemaName, tableName, table, oldSchema, change);
+                break;
+            case 'alterColumn':
+                updated = await this.alterColumnChange(db, schemaName, tableName, table, oldSchema, change, rows);
+                break;
+            default: {
+                const _exhaustive = change;
+                void _exhaustive;
+                throw new QuereusError(`Unhandled ALTER TABLE change type '${change.type}'`, StatusCode.INTERNAL);
             }
-            case 'renameColumn': {
-                if (!change.newColumnDefAst) {
-                    throw new QuereusError('RENAME COLUMN requires a new column definition AST', StatusCode.INTERNAL);
-                }
-                const oldNameLower = change.oldName.toLowerCase();
-                const colIndex = oldSchema.columns.findIndex(c => c.name.toLowerCase() === oldNameLower);
-                if (colIndex === -1) {
-                    throw new QuereusError(`Column '${change.oldName}' not found.`, StatusCode.ERROR);
-                }
-                const newColSchema = columnDefToSchema(change.newColumnDefAst, defaultNotNull);
-                const updatedColumns = oldSchema.columns.map((c, i) => i === colIndex ? newColSchema : c);
-                const updatedIndexes = (oldSchema.indexes || []).map(idx => ({
-                    ...idx,
-                    columns: idx.columns.map(ic => ic.index === colIndex ? { ...ic, name: change.newName } : ic),
-                }));
-                const updatedSchema = {
-                    ...oldSchema,
-                    columns: Object.freeze(updatedColumns),
-                    columnIndexMap: buildColumnIndexMap(updatedColumns),
-                    indexes: Object.freeze(updatedIndexes),
-                };
-                // Rename is schema-only — no row migration needed
-                table.updateSchema(updatedSchema);
-                await this.saveTableDDL(updatedSchema);
-                this.eventEmitter?.emitSchemaChange({
-                    type: 'alter',
-                    objectType: 'table',
-                    schemaName,
-                    objectName: tableName,
-                });
-                return updatedSchema;
+        }
+        // Move the physical `_uc_*` index stores to match the post-ALTER constraint set:
+        // the SCHEMA entries were re-materialized by the arm's `table.updateSchema`, but a
+        // newly-added constraint's store must be BUILT and a dropped/renamed one's TORN
+        // DOWN. `oldSchema` carries the pre-ALTER `uniqueConstraints`; `table.getSchema()`
+        // the post-ALTER set. A no-op when the implicit-index name set is unchanged (the
+        // common case, incl. PK/collation/type ALTERs whose physical re-encode is already
+        // handled by `rebuildSecondaryIndexes`).
+        await this.reconcileImplicitUniqueIndexStores(db, schemaName, tableName, table, oldSchema);
+        return updated;
+    }
+    /**
+     * Build / tear down the physical index stores backing implicit UNIQUE indexes
+     * (`_uc_*`) after an ALTER, by diffing the implicit-index NAMES of the old vs new
+     * constraint sets:
+     *   - a name newly PRESENT (ADD CONSTRAINT UNIQUE, or the target half of a
+     *     RENAME CONSTRAINT / rename of an unnamed UC's column) has its physical store
+     *     populated from this module's effective rows;
+     *   - a name newly ABSENT (DROP CONSTRAINT UNIQUE, or the source half of a rename)
+     *     has its store torn down, so a later re-ADD does not reopen stale entries.
+     *
+     * The SCHEMA entry itself is materialized/removed by `withImplicitUniqueIndexes`
+     * on the arm's `table.updateSchema`; only the physical store needs this. Runs after
+     * every ALTER but is a no-op whenever the implicit-index name set is unchanged
+     * (incl. PK / collation / data-type ALTERs, whose same-name physical re-encode is
+     * already done by {@link rebuildSecondaryIndexes}).
+     *
+     * `oldSchema` carries the pre-ALTER `uniqueConstraints` (its `.indexes` may be
+     * de-materialized — the diff reads `uniqueConstraints`, not `.indexes`).
+     *
+     * NOTE: the build populates from THIS module's own effective rows (committed + this
+     * transaction's pending), never a wrapper's — mirroring `createIndex`. Under the
+     * isolation layer the wrapper's rows are what ADD CONSTRAINT's validation judged;
+     * the physical index legitimately fills from this module's committed rows and an
+     * entry with no live row behind it is harmless (both readers resolve to the live
+     * row). Duplicates were already rejected by `validateUniqueOverExistingRows` (ADD)
+     * or cannot exist (RENAME leaves data unchanged), so the in-pass check is skipped.
+     */
+    async reconcileImplicitUniqueIndexStores(db, schemaName, tableName, table, oldSchema) {
+        // Diff the constraint sets by implicit-index NAME (derived from `uniqueConstraints`,
+        // so the engine-facing schemas work directly); resolve the index SHAPE to build from
+        // the materialized enforcement schema.
+        const newSchema = table.getSchema();
+        const newMaterialized = table.getMaterializedSchema();
+        const oldNames = implicitUniqueIndexNameMap(oldSchema);
+        const newNames = implicitUniqueIndexNameMap(newSchema);
+        // Tear down each store whose implicit index no longer exists.
+        for (const [lower, name] of oldNames) {
+            if (!newNames.has(lower)) {
+                await this.tearDownImplicitUniqueIndexStore(schemaName, tableName, table, name);
             }
-            case 'alterPrimaryKey': {
-                const newPkColumns = change.newPkColumns;
-                const updatedSchema = {
-                    ...oldSchema,
-                    primaryKeyDefinition: Object.freeze(newPkColumns.map(pk => ({ index: pk.index, desc: pk.desc }))),
-                };
-                // Re-key the data store. Throws CONSTRAINT on duplicates without
-                // mutating the store, giving us all-or-nothing semantics for the
-                // validation phase.
-                await table.rekeyRows(newPkColumns);
-                // Secondary index keys embed the PK suffix — clear + rebuild every
-                // index against the now-rekeyed data store.
-                await this.rebuildSecondaryIndexes(schemaName, tableName, tableKey, table, updatedSchema);
-                table.updateSchema(updatedSchema);
-                await this.saveTableDDL(updatedSchema);
-                this.eventEmitter?.emitSchemaChange({
-                    type: 'alter',
-                    objectType: 'table',
-                    schemaName,
-                    objectName: tableName,
-                });
-                return updatedSchema;
+        }
+        // Build each newly-materialized implicit index's store from effective rows.
+        for (const [lower, name] of newNames) {
+            if (oldNames.has(lower))
+                continue;
+            const indexSchema = (newMaterialized.indexes ?? []).find(ix => ix.name === name);
+            if (!indexSchema)
+                continue; // defensive — name is derived from the same UC set
+            // NOTE: no `assertStoreNameFree` here (unlike explicit `createIndex`): the name
+            // is engine-derived and deterministic, and the lazy first-write build path in
+            // `updateSecondaryIndexes` does not assert either — keep the two consistent.
+            // NOTE: no teardown-on-failure wrapper (unlike `createIndex`): an IO error mid-build
+            // leaves a partial `_uc_*` store while the constraint schema is already committed, so
+            // enforcement could under-report until the store is rebuilt. Tolerated because the
+            // build has no in-pass dup check (skipDuplicateCheck below) so the only failure is a
+            // genuine IO error — the same non-atomicity `rebuildSecondaryIndexes` documents; a
+            // re-run / reopen rebuilds. Add a try/catch teardown if this ever bites.
+            const keyCollation = (table.getConfig().collation || 'NOCASE').toUpperCase();
+            const indexStore = await this.provider.getIndexStore(schemaName, tableName, name);
+            await this.buildIndexEntries(table.iterateEffectiveEntries(buildFullScanBounds()), indexStore, newSchema, indexSchema, keyCollation, db.getKeyNormalizerResolver(), true, // dup rejection already owned by the arm (ADD validates; RENAME is data-preserving)
+            table.getConfig().maxBatchBytes ?? DEFAULT_MAX_BATCH_BYTES);
+        }
+    }
+    /**
+     * The physical index-store names a table owns for DROP / RENAME TABLE to relocate
+     * or reclaim: the MATERIALIZED index set — every explicit `CREATE INDEX` PLUS the
+     * hidden `_uc_*` realizing each plain UNIQUE. Reading only `getSchema().indexes`
+     * (the engine-facing schema, which carries no `_uc_*`) would strand a `_uc_*` store
+     * on disk after DROP TABLE, and — worse — after RENAME TABLE leave the renamed
+     * table seeking a freshly-created EMPTY `_uc_*` store, silently accepting a
+     * duplicate of a pre-rename row. Prefers the cached StoreTable's own materialized
+     * schema; falls back to materializing the schema-manager copy when the instance is
+     * already gone.
+     */
+    materializedIndexNames(table, fallback) {
+        const schema = table
+            ? table.getMaterializedSchema()
+            : (fallback ? withImplicitUniqueIndexes(fallback) : undefined);
+        return (schema?.indexes ?? []).map(i => i.name);
+    }
+    /** Close + delete the physical store of an implicit UNIQUE index. Mirrors `dropIndex`. */
+    async tearDownImplicitUniqueIndexStore(schemaName, tableName, table, indexName) {
+        await table.releaseIndexStore(indexName);
+        if (this.provider.deleteIndexStore) {
+            await this.provider.deleteIndexStore(schemaName, tableName, indexName);
+        }
+        else {
+            await this.provider.closeIndexStore(schemaName, tableName, indexName);
+        }
+    }
+    /**
+     * ADD COLUMN arm of {@link alterTable}: append the new column, eagerly migrate
+     * each row (literal or per-row backfill), and persist. Behavior-preserving
+     * extraction of the former `switch` arm.
+     */
+    async alterAddColumn(db, schemaName, tableName, table, oldSchema, change, defaultNotNull) {
+        // Honor the session `default_collation` for an ADD COLUMN that omits an
+        // explicit COLLATE, matching the CREATE path so an ADD-COLUMN-ed text column
+        // gets the same collation a CREATE-d one would. The persisted DDL re-emits an
+        // explicit COLLATE for any non-BINARY collation, so reopen stays stable.
+        const newColSchema = columnDefToSchema(change.columnDef, defaultNotNull, db.options.getStringOption('default_collation'), (n) => db.isCollationRegistered(n));
+        // Extract default value from column def constraints. Use the shared
+        // `tryFoldLiteral` helper so signed numerics like `-123.0`
+        // (a UnaryExpr in the AST) are recognized — matching the
+        // memory-mode path and the engine-level ALTER validation.
+        let defaultValue = null;
+        const defaultConstraint = change.columnDef.constraints?.find(c => c.type === 'default');
+        if (defaultConstraint?.expr) {
+            const folded = tryFoldLiteral(defaultConstraint.expr);
+            if (folded !== undefined) {
+                defaultValue = folded;
             }
-            case 'addConstraint': {
-                const constraint = change.constraint;
-                let updatedSchema;
-                if (constraint.type === 'unique') {
-                    // Store enforces inline UNIQUE by full-scan over `uniqueConstraints`
-                    // (no separate index store), so there is nothing physical to build —
-                    // but we must validate the existing rows before persisting.
-                    const uc = buildUniqueConstraintSchema(constraint, oldSchema.columnIndexMap);
-                    const dataStore = await this.getStore(tableKey, table.getConfig());
-                    await this.validateUniqueOverExistingRows(dataStore, oldSchema, uc);
-                    updatedSchema = {
-                        ...oldSchema,
-                        uniqueConstraints: Object.freeze([...(oldSchema.uniqueConstraints ?? []), uc]),
-                    };
-                }
-                else if (constraint.type === 'foreignKey') {
-                    const fk = buildForeignKeyConstraintSchema(constraint, oldSchema.columnIndexMap, oldSchema.name, oldSchema.schemaName);
-                    updatedSchema = {
-                        ...oldSchema,
-                        foreignKeys: Object.freeze([...(oldSchema.foreignKeys ?? []), fk]),
-                    };
-                    // Pragma-gated existing-row validation; throws before persistence on an orphan.
-                    await validateForeignKeyOverExistingRows(db, updatedSchema, fk);
-                }
-                else if (constraint.type === 'check') {
-                    // Schema-only: a CHECK has no physical structure and (matching the
-                    // engine's prior in-emitter behavior) no existing-row scan. Routing it
-                    // here — rather than catalog-only — keeps the persisted DDL and the
-                    // connected-table schema in lock-step so DROP/RENAME CONSTRAINT resolve it.
-                    const check = buildCheckConstraintSchema(constraint, oldSchema.checkConstraints.length);
-                    updatedSchema = {
-                        ...oldSchema,
-                        checkConstraints: Object.freeze([...oldSchema.checkConstraints, check]),
-                    };
-                }
-                else {
-                    throw new QuereusError(`Store table ADD CONSTRAINT does not support constraint type '${constraint.type}'`, StatusCode.UNSUPPORTED);
-                }
-                table.updateSchema(updatedSchema);
-                await this.saveTableDDL(updatedSchema);
-                this.eventEmitter?.emitSchemaChange({
-                    type: 'alter',
-                    objectType: 'table',
-                    schemaName,
-                    objectName: tableName,
-                });
-                return updatedSchema;
+        }
+        // A non-foldable DEFAULT (e.g. `new.<col>`) backfills each existing row from
+        // its own value via the engine-supplied evaluator (mirrors the memory path).
+        const backfillEvaluator = change.backfillEvaluator;
+        // Refuse NOT NULL without a usable DEFAULT on a non-empty table
+        // (SQLite-compatible). A per-row evaluator IS usable — its NOT NULL is enforced
+        // per row during migration — so it is exempt from this no-default rejection.
+        if (newColSchema.notNull && defaultValue === null && !backfillEvaluator) {
+            if (await table.hasAnyRows()) {
+                throw new QuereusError(`Cannot add NOT NULL column '${newColSchema.name}' to non-empty table `
+                    + `'${schemaName}.${tableName}' without a DEFAULT value`, StatusCode.CONSTRAINT);
             }
-            case 'dropConstraint': {
-                // Schema-only catalog rewrite: store-backed UNIQUE enforcement is a
-                // full-scan over `uniqueConstraints` (no separate index store for an
-                // inline UNIQUE), so dropping the constraint stops enforcement with no
-                // physical teardown. A UNIQUE derived from a CREATE UNIQUE INDEX is
-                // rejected upstream (drop the index instead), so we never strand a store.
-                const constraintClass = resolveNamedConstraintClass(oldSchema, change.constraintName);
-                const lower = change.constraintName.toLowerCase();
-                let updatedSchema;
-                if (constraintClass === 'check') {
-                    updatedSchema = {
-                        ...oldSchema,
-                        checkConstraints: Object.freeze(oldSchema.checkConstraints.filter(c => c.name?.toLowerCase() !== lower)),
-                    };
-                }
-                else if (constraintClass === 'foreignKey') {
-                    const remaining = (oldSchema.foreignKeys ?? []).filter(c => c.name?.toLowerCase() !== lower);
-                    updatedSchema = { ...oldSchema, foreignKeys: remaining.length > 0 ? Object.freeze(remaining) : undefined };
-                }
-                else {
-                    const remaining = (oldSchema.uniqueConstraints ?? []).filter(c => c.name?.toLowerCase() !== lower);
-                    updatedSchema = { ...oldSchema, uniqueConstraints: remaining.length > 0 ? Object.freeze(remaining) : undefined };
-                }
-                table.updateSchema(updatedSchema);
-                await this.saveTableDDL(updatedSchema);
-                this.eventEmitter?.emitSchemaChange({
-                    type: 'alter',
-                    objectType: 'table',
-                    schemaName,
-                    objectName: tableName,
-                });
-                return updatedSchema;
+        }
+        // Build updated schema: append new column
+        const updatedColumns = Object.freeze([...oldSchema.columns, newColSchema]);
+        const updatedSchema = {
+            ...oldSchema,
+            columns: updatedColumns,
+            columnIndexMap: buildColumnIndexMap(updatedColumns),
+        };
+        // Extract any column-level CHECK / FK to persist (see the persist block below).
+        // Hoisted above the row migration so a malformed constraint (e.g. a multi-column
+        // FK on a single ADD COLUMN, which `extractColumnLevelForeignKeys` rejects) throws
+        // BEFORE any rows are migrated or the in-memory schema is swapped — validate-before-
+        // mutate, matching the engine's ordering in `runAddColumn`.
+        const newCheckConstraints = extractColumnLevelCheckConstraints(change.columnDef);
+        const newForeignKeys = extractColumnLevelForeignKeys(change.columnDef, schemaName);
+        // Physical rewrite ahead: flush the module's buffered writes so `migrateRows`
+        // (a committed-store scan + batch) sees this transaction's rows and re-encodes
+        // them under the new column layout. See {@link ddlCommitPendingOps}. Placed
+        // after every throw-only check above — the NOT NULL rejection reads effectively
+        // (`hasAnyRows`) and `extractColumnLevel*` reads no rows — so a rejected ALTER
+        // leaves the enclosing transaction intact.
+        await this.ddlCommitPendingOps();
+        // Migrate rows: append the new column's value — a single literal default, or a
+        // per-row value derived from the existing row when a backfill evaluator is set.
+        const remap = buildColumnRemap(oldSchema.columns.map(c => c.name), updatedColumns.map(c => c.name));
+        await table.migrateRows(remap, defaultValue, backfillEvaluator
+            ? { evaluator: backfillEvaluator, notNull: newColSchema.notNull, columnName: newColSchema.name }
+            : undefined);
+        // Update table schema (column-only) and persist DDL.
+        //
+        // The engine's `runAddColumn` re-merges the column-level FK/CHECK extracted
+        // from `columnDef.constraints` into the LIVE in-memory schema AFTER this hook
+        // returns, so the schema handed back to it must stay column-only — returning a
+        // constrained schema would double the constraint in the live SchemaManager (and,
+        // on the next persist, in the DDL). But that engine-side merge is in-memory only:
+        // it never reaches the catalog, so persistence must carry the column-level
+        // CHECK/FK itself or they vanish on `rehydrateCatalog`. Build a separate
+        // `persistedSchema` for `saveTableDDL` when (and only when) the column declares
+        // such a constraint; the common path persists `updatedSchema` unchanged. This is
+        // unconditional on the default kind — a per-row (evaluator) DEFAULT extracts the
+        // same AST constraints as a literal one.
+        table.updateSchema(updatedSchema);
+        let persistedSchema = updatedSchema;
+        if (newCheckConstraints.length > 0 || newForeignKeys.length > 0) {
+            // The new column is appended last; resolve each FK's child column to its index
+            // (matching how the engine resolves `resolvedForeignKeys` via columnIndexMap).
+            const newColIdx = updatedColumns.length - 1;
+            const resolvedForeignKeys = newForeignKeys.map(fk => ({ ...fk, columns: Object.freeze([newColIdx]) }));
+            persistedSchema = {
+                ...updatedSchema,
+                checkConstraints: Object.freeze([...updatedSchema.checkConstraints, ...newCheckConstraints]),
+                foreignKeys: Object.freeze([...(updatedSchema.foreignKeys ?? []), ...resolvedForeignKeys]),
+            };
+        }
+        await this.saveTableDDL(persistedSchema);
+        this.eventEmitter?.emitSchemaChange({
+            type: 'alter',
+            objectType: 'table',
+            schemaName,
+            objectName: tableName,
+        });
+        return updatedSchema;
+    }
+    /** DROP COLUMN arm of {@link alterTable}: drop the column slot, reindex PK / indexes /
+     *  UNIQUE, migrate rows, and persist. Behavior-preserving extraction. */
+    async alterDropColumn(schemaName, tableName, table, oldSchema, change) {
+        const colNameLower = change.columnName.toLowerCase();
+        const colIndex = oldSchema.columns.findIndex(c => c.name.toLowerCase() === colNameLower);
+        if (colIndex === -1) {
+            throw new QuereusError(`Column '${change.columnName}' not found.`, StatusCode.ERROR);
+        }
+        // Build updated schema: remove column and reindex PK/indexes
+        // Filter by original index BEFORE remapping to avoid incorrectly
+        // removing columns that remap to the dropped column's position.
+        const updatedColumns = oldSchema.columns.filter((_, idx) => idx !== colIndex);
+        const updatedPkDef = oldSchema.primaryKeyDefinition
+            .filter(def => def.index !== colIndex)
+            .map(def => ({
+            ...def,
+            index: def.index > colIndex ? def.index - 1 : def.index,
+        }));
+        const updatedIndexes = (oldSchema.indexes || [])
+            .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);
+        // Prune any UNIQUE constraint over the dropped column, mirroring the index
+        // filtering above. Store-backed UNIQUE is enforced by a full scan over
+        // `uniqueConstraints`, so a stranded constraint whose column index dangles past
+        // the column array would break the next insert's validation (and the persisted
+        // DDL). A UNIQUE that includes the dropped column is removed outright; remaining
+        // constraints have their column indices shifted to track the removed slot. This
+        // also covers the engine's ADD COLUMN + inline-UNIQUE revert, which drops the
+        // just-added (uniquely-constrained) column.
+        const updatedUniqueConstraints = (oldSchema.uniqueConstraints ?? [])
+            .filter(uc => !uc.columns.includes(colIndex))
+            .map(uc => ({ ...uc, columns: Object.freeze(uc.columns.map(i => i > colIndex ? i - 1 : i)) }));
+        const updatedSchema = {
+            ...oldSchema,
+            columns: Object.freeze(updatedColumns),
+            columnIndexMap: buildColumnIndexMap(updatedColumns),
+            primaryKeyDefinition: Object.freeze(updatedPkDef),
+            indexes: Object.freeze(updatedIndexes),
+            uniqueConstraints: updatedUniqueConstraints.length > 0
+                ? Object.freeze(updatedUniqueConstraints)
+                : undefined,
+        };
+        // Physical rewrite ahead — flush buffered writes so `migrateRows` re-encodes
+        // this transaction's rows too. See {@link ddlCommitPendingOps}.
+        await this.ddlCommitPendingOps();
+        // Migrate rows: remove the dropped column slot
+        const remap = buildColumnRemap(oldSchema.columns.map(c => c.name), updatedColumns.map(c => c.name));
+        await table.migrateRows(remap, null);
+        // Update table schema and persist DDL
+        table.updateSchema(updatedSchema);
+        await this.saveTableDDL(updatedSchema);
+        this.eventEmitter?.emitSchemaChange({
+            type: 'alter',
+            objectType: 'table',
+            schemaName,
+            objectName: tableName,
+        });
+        return updatedSchema;
+    }
+    /** RENAME COLUMN arm of {@link alterTable}: schema-only rewrite (columns, indexes, self-FK,
+     *  in-place predicate / CHECK AST rewrite) and persist. Behavior-preserving extraction. */
+    async alterRenameColumn(db, schemaName, tableName, table, oldSchema, change, defaultNotNull) {
+        if (!change.newColumnDefAst) {
+            throw new QuereusError('RENAME COLUMN requires a new column definition AST', StatusCode.INTERNAL);
+        }
+        const oldNameLower = change.oldName.toLowerCase();
+        const colIndex = oldSchema.columns.findIndex(c => c.name.toLowerCase() === oldNameLower);
+        if (colIndex === -1) {
+            throw new QuereusError(`Column '${change.oldName}' not found.`, StatusCode.ERROR);
+        }
+        const newColSchema = columnDefToSchema(change.newColumnDefAst, defaultNotNull, 'BINARY', (n) => db.isCollationRegistered(n));
+        const updatedColumns = oldSchema.columns.map((c, i) => i === colIndex ? newColSchema : c);
+        const updatedIndexes = (oldSchema.indexes || []).map(idx => ({
+            ...idx,
+            columns: idx.columns.map(ic => ic.index === colIndex ? { ...ic, name: change.newName } : ic),
+        }));
+        const updatedSchema = {
+            ...oldSchema,
+            columns: Object.freeze(updatedColumns),
+            columnIndexMap: buildColumnIndexMap(updatedColumns),
+            indexes: Object.freeze(updatedIndexes),
+            // A self-referencing FK names the renamed column in `referencedColumnNames`
+            // and is persisted by name; the engine rewrites it only in the post-hook
+            // pass. Pure copy — no rollback needed, this schema is only adopted on the
+            // success path.
+            foreignKeys: renameColumnInSelfForeignKeys(oldSchema.foreignKeys, schemaName, tableName, change.oldName, change.newName),
+        };
+        // A partial index's WHERE clause and a CHECK constraint's expression both
+        // still name the OLD column: the engine's `propagateColumnRename` pass runs
+        // only after this hook returns. Persisting now would durably write a bundle
+        // naming a column the table no longer has, and only the later propagation's
+        // `table_modified` event would correct it — a crash in between leaves the
+        // catalog un-rehydratable. So rewrite first, in place: each `Expression` is
+        // shared by reference with the catalog's `TableSchema` and, for a unique
+        // partial index, with the `derivedFromIndex` UNIQUE constraint, so one
+        // rewrite covers all holders and makes the later propagation pass a no-op.
+        //
+        // The rewrites are the first statements in the `try`, and each walks its
+        // collection one item at a time, so a throw anywhere — including partway
+        // through a walk — must reverse them: restoring `oldSchema` cannot, since the
+        // ASTs are shared. Reversing is a no-op wherever nothing names the new column,
+        // and the engine has already rejected a rename onto an existing column name,
+        // so the reverse pass cannot collide with an expression that legitimately
+        // named it.
+        const resolveColumnInSource = (s, t, col) => db.schemaManager.getSchema(s)?.getTable(t)?.columnIndexMap.has(col.toLowerCase()) ?? false;
+        const rewriteColumn = (from, to) => {
+            renameColumnInIndexPredicates(updatedIndexes, tableName, from, to, schemaName, resolveColumnInSource);
+            renameColumnInCheckConstraints(oldSchema.checkConstraints, tableName, from, to, schemaName, resolveColumnInSource);
+        };
+        try {
+            rewriteColumn(change.oldName, change.newName);
+            // Rename is schema-only — no row migration needed
+            table.updateSchema(updatedSchema);
+            await this.saveTableDDL(updatedSchema);
+        }
+        catch (e) {
+            rewriteColumn(change.newName, change.oldName);
+            throw e;
+        }
+        this.eventEmitter?.emitSchemaChange({
+            type: 'alter',
+            objectType: 'table',
+            schemaName,
+            objectName: tableName,
+        });
+        return updatedSchema;
+    }
+    /** ALTER PRIMARY KEY arm of {@link alterTable}: physically re-key the data store, rebuild
+     *  secondary indexes, and persist. Behavior-preserving extraction. */
+    async alterPrimaryKeyChange(db, schemaName, tableName, table, oldSchema, change) {
+        const newPkColumns = change.newPkColumns;
+        const updatedSchema = {
+            ...oldSchema,
+            primaryKeyDefinition: Object.freeze(newPkColumns.map(pk => ({ index: pk.index, desc: pk.desc }))),
+        };
+        // Physical re-key ahead — flush buffered writes so every live row is
+        // re-keyed and no stale-schema op replays over the rewritten store.
+        // `rekeyRows`' duplicate-key pass runs against the flushed store, so a
+        // pending insert that collides under the new PK is caught. See
+        // {@link ddlCommitPendingOps} for the transaction consequences.
+        await this.ddlCommitPendingOps();
+        // Re-key the data store. Throws CONSTRAINT on duplicates without
+        // mutating the store, giving us all-or-nothing semantics for the
+        // validation phase.
+        await table.rekeyRows(newPkColumns);
+        // Secondary index keys embed the PK suffix — clear + rebuild every
+        // index against the now-rekeyed data store. Rebuild the MATERIALIZED index list
+        // so each implicit `_uc_*` PK suffix is re-encoded too (`updatedSchema` is built
+        // off the de-materialized `oldSchema`, so it carries no `_uc_*` on its own).
+        await this.rebuildSecondaryIndexes(schemaName, tableName, table, withImplicitUniqueIndexes(updatedSchema), db.getKeyNormalizerResolver());
+        table.updateSchema(updatedSchema);
+        await this.saveTableDDL(updatedSchema);
+        this.eventEmitter?.emitSchemaChange({
+            type: 'alter',
+            objectType: 'table',
+            schemaName,
+            objectName: tableName,
+        });
+        return updatedSchema;
+    }
+    /** ADD CONSTRAINT arm of {@link alterTable}: validate existing rows as the constraint kind
+     *  (UNIQUE / FOREIGN KEY / CHECK) requires, then persist. Behavior-preserving extraction. */
+    async alterAddConstraint(db, schemaName, tableName, table, oldSchema, change, rows) {
+        const constraint = change.constraint;
+        let updatedSchema;
+        if (constraint.type === 'unique') {
+            // Validate the existing rows against the new UNIQUE before persisting. The
+            // implicit `_uc_*` index that backs enforcement is materialized into the
+            // StoreTable schema by `table.updateSchema` below, and its PHYSICAL store is
+            // built by `reconcileImplicitUniqueIndexStores` after this arm returns — the
+            // validation here runs first, so a CONSTRAINT rejection never leaves a store
+            // behind.
+            //
+            // No `ddlCommitPendingOps()` here (unlike the row-rewriting arms): this
+            // writes no rows, and the validation scan already reads effectively, so
+            // the transaction survives a CONSTRAINT rejection.
+            const uc = buildUniqueConstraintSchema(constraint, oldSchema.columnIndexMap);
+            await this.validateUniqueOverExistingRows(rows ? rows() : rowsFromEntries(table.iterateEffectiveEntries(buildFullScanBounds())), oldSchema, uc, db.getKeyNormalizerResolver());
+            updatedSchema = {
+                ...oldSchema,
+                uniqueConstraints: Object.freeze([...(oldSchema.uniqueConstraints ?? []), uc]),
+            };
+        }
+        else if (constraint.type === 'foreignKey') {
+            const fk = buildForeignKeyConstraintSchema(constraint, oldSchema.columnIndexMap, oldSchema.name, oldSchema.schemaName);
+            updatedSchema = {
+                ...oldSchema,
+                foreignKeys: Object.freeze([...(oldSchema.foreignKeys ?? []), fk]),
+            };
+            // Pragma-gated existing-row validation; throws before persistence on an orphan.
+            await validateForeignKeyOverExistingRows(db, updatedSchema, fk);
+        }
+        else if (constraint.type === 'check') {
+            // Schema-only: a CHECK has no physical structure and (matching the
+            // engine's prior in-emitter behavior) no existing-row scan. Routing it
+            // here — rather than catalog-only — keeps the persisted DDL and the
+            // connected-table schema in lock-step so DROP/RENAME CONSTRAINT resolve it.
+            const check = buildCheckConstraintSchema(constraint, oldSchema.checkConstraints.length);
+            updatedSchema = {
+                ...oldSchema,
+                checkConstraints: Object.freeze([...oldSchema.checkConstraints, check]),
+            };
+        }
+        else {
+            throw new QuereusError(`Store table ADD CONSTRAINT does not support constraint type '${constraint.type}'`, StatusCode.UNSUPPORTED);
+        }
+        table.updateSchema(updatedSchema);
+        await this.saveTableDDL(updatedSchema);
+        this.eventEmitter?.emitSchemaChange({
+            type: 'alter',
+            objectType: 'table',
+            schemaName,
+            objectName: tableName,
+        });
+        return updatedSchema;
+    }
+    /** DROP CONSTRAINT arm of {@link alterTable}: schema-only catalog rewrite dropping a named
+     *  constraint, then persist. Behavior-preserving extraction. */
+    async alterDropConstraint(schemaName, tableName, table, oldSchema, change) {
+        // Schema-only catalog rewrite. Dropping a UNIQUE removes it from
+        // `uniqueConstraints`, so `table.updateSchema` below de-materializes its implicit
+        // `_uc_*` index and `reconcileImplicitUniqueIndexStores` (after this arm returns)
+        // tears down the now-orphaned physical store — without which a later re-ADD would
+        // reopen stale entries. A UNIQUE derived from a CREATE UNIQUE INDEX is rejected
+        // upstream (drop the index instead), and has no `_uc_*` anyway.
+        const constraintClass = resolveNamedConstraintClass(oldSchema, change.constraintName);
+        const lower = change.constraintName.toLowerCase();
+        let updatedSchema;
+        if (constraintClass === 'check') {
+            updatedSchema = {
+                ...oldSchema,
+                checkConstraints: Object.freeze(oldSchema.checkConstraints.filter(c => c.name?.toLowerCase() !== lower)),
+            };
+        }
+        else if (constraintClass === 'foreignKey') {
+            const remaining = (oldSchema.foreignKeys ?? []).filter(c => c.name?.toLowerCase() !== lower);
+            updatedSchema = { ...oldSchema, foreignKeys: remaining.length > 0 ? Object.freeze(remaining) : undefined };
+        }
+        else {
+            const remaining = (oldSchema.uniqueConstraints ?? []).filter(c => c.name?.toLowerCase() !== lower);
+            updatedSchema = { ...oldSchema, uniqueConstraints: remaining.length > 0 ? Object.freeze(remaining) : undefined };
+        }
+        table.updateSchema(updatedSchema);
+        await this.saveTableDDL(updatedSchema);
+        this.eventEmitter?.emitSchemaChange({
+            type: 'alter',
+            objectType: 'table',
+            schemaName,
+            objectName: tableName,
+        });
+        return updatedSchema;
+    }
+    /** RENAME CONSTRAINT arm of {@link alterTable}: schema-only rename of a named constraint,
+     *  then persist. A renamed named-UNIQUE changes its implicit `_uc_*` index name, so
+     *  `reconcileImplicitUniqueIndexStores` (run after this arm) MOVES the physical store —
+     *  tears down the old-named store and rebuilds the new-named one from effective rows. */
+    async alterRenameConstraint(schemaName, tableName, table, oldSchema, change) {
+        const constraintClass = resolveNamedConstraintClass(oldSchema, change.oldName);
+        const oldLower = change.oldName.toLowerCase();
+        let updatedSchema;
+        if (constraintClass === 'check') {
+            updatedSchema = {
+                ...oldSchema,
+                checkConstraints: Object.freeze(oldSchema.checkConstraints.map(c => (c.name?.toLowerCase() === oldLower ? { ...c, name: change.newName } : c))),
+            };
+        }
+        else if (constraintClass === 'foreignKey') {
+            updatedSchema = {
+                ...oldSchema,
+                foreignKeys: Object.freeze(oldSchema.foreignKeys.map(c => (c.name?.toLowerCase() === oldLower ? { ...c, name: change.newName } : c))),
+            };
+        }
+        else {
+            updatedSchema = {
+                ...oldSchema,
+                uniqueConstraints: Object.freeze(oldSchema.uniqueConstraints.map(c => (c.name?.toLowerCase() === oldLower ? { ...c, name: change.newName } : c))),
+            };
+        }
+        table.updateSchema(updatedSchema);
+        await this.saveTableDDL(updatedSchema);
+        this.eventEmitter?.emitSchemaChange({
+            type: 'alter',
+            objectType: 'table',
+            schemaName,
+            objectName: tableName,
+        });
+        return updatedSchema;
+    }
+    /** ALTER COLUMN arm of {@link alterTable}: change one attribute (NOT NULL / data type /
+     *  default / collation), running the physical re-key + existing-row re-validation the
+     *  collation / PK paths require, then persist. Behavior-preserving extraction. */
+    async alterColumnChange(db, schemaName, tableName, table, oldSchema, change, rows) {
+        const colNameLower = change.columnName.toLowerCase();
+        const colIndex = oldSchema.columns.findIndex(c => c.name.toLowerCase() === colNameLower);
+        if (colIndex === -1) {
+            throw new QuereusError(`Column '${change.columnName}' not found.`, StatusCode.ERROR);
+        }
+        const oldCol = oldSchema.columns[colIndex];
+        // Pull exactly one attribute from the change. Each sub-helper returns the new
+        // column schema plus whether the collation bytes changed (`collationChanged` gates
+        // the existing-row UNIQUE re-validation and PK re-key below), or null when the column
+        // is already in the desired state — preserving the pre-refactor early exits
+        // (SET NOT NULL no-op, SET COLLATE already-explicit) that leave the table and any
+        // open transaction untouched.
+        let attr;
+        if (change.setNotNull !== undefined) {
+            attr = await this.alterColumnSetNotNull(table, oldSchema, oldCol, colIndex, change, rows);
+        }
+        else if (change.setDataType !== undefined) {
+            attr = await this.alterColumnSetDataType(table, oldCol, colIndex, change);
+        }
+        else if (change.setDefault !== undefined) {
+            attr = { newCol: { ...oldCol, defaultValue: change.setDefault }, collationChanged: false };
+        }
+        else if (change.setCollation !== undefined) {
+            attr = this.alterColumnSetCollation(oldCol, change, (n) => db.isCollationRegistered(n));
+        }
+        else {
+            throw new QuereusError('ALTER COLUMN requires an attribute to change', StatusCode.INTERNAL);
+        }
+        if (attr === null) {
+            return oldSchema;
+        }
+        const { newCol, collationChanged, valuesRewritten } = attr;
+        const updatedColumns = oldSchema.columns.map((c, i) => i === colIndex ? newCol : c);
+        // Mirror the memory module (MemoryTableManager.alterColumn): a per-column
+        // collation change propagates into every index column ordering by this
+        // column, so a `derivedFromIndex` UNIQUE re-keys its enforcement under the
+        // new collation. StoreTable.uniqueEnforcementCollations reads the index's
+        // per-column collation, so without this the index entry would stay stale
+        // and the derived UNIQUE would keep enforcing the OLD collation after the
+        // ALTER. Metadata-only: the store's index KEY bytes use the table-level key
+        // collation K (see buildIndexEntries / updateSecondaryIndexes), so no index
+        // entry re-encode is required for a non-PK column. An index column with an
+        // explicit COLLATE is re-collated too — matching memory, which clobbers it
+        // the same way (no surface preserves a differing index COLLATE across an
+        // ALTER COLUMN SET COLLATE on its column).
+        const updatedIndexes = (collationChanged && oldSchema.indexes)
+            ? oldSchema.indexes.map(idx => ({
+                ...idx,
+                columns: idx.columns.map(ic => ic.index === colIndex ? { ...ic, collation: newCol.collation } : ic),
+            }))
+            : oldSchema.indexes;
+        const updatedSchema = {
+            ...oldSchema,
+            columns: Object.freeze(updatedColumns),
+            columnIndexMap: buildColumnIndexMap(updatedColumns),
+            indexes: updatedIndexes ? Object.freeze(updatedIndexes) : updatedIndexes,
+        };
+        // SET COLLATE existing-row re-validation (Option A, non-PK UNIQUE): a new
+        // per-column collation can make rows that were distinct under the old
+        // collation collide. Re-scan every UNIQUE constraint covering the altered
+        // column under the NEW collation (`updatedSchema` carries it). The first
+        // collision throws CONSTRAINT BEFORE any mutation/persist, so the table is
+        // left unchanged and writable (matches the ADD CONSTRAINT rollback shape).
+        // The PK is intentionally excluded — it never appears in `uniqueConstraints`;
+        // its physical re-key/re-validation is the `isPkColumn` block below.
+        if (collationChanged) {
+            const coveringConstraints = (updatedSchema.uniqueConstraints ?? [])
+                .filter(uc => uc.columns.includes(colIndex));
+            for (const uc of coveringConstraints) {
+                // Fresh generator per constraint — an async generator is single-shot. An
+                // `EffectiveRowSource` is re-callable for exactly this reason.
+                await this.validateUniqueOverExistingRows(rows ? rows() : rowsFromEntries(table.iterateEffectiveEntries(buildFullScanBounds())), updatedSchema, uc, db.getKeyNormalizerResolver());
             }
-            case 'renameConstraint': {
-                const constraintClass = resolveNamedConstraintClass(oldSchema, change.oldName);
-                const oldLower = change.oldName.toLowerCase();
-                let updatedSchema;
-                if (constraintClass === 'check') {
-                    updatedSchema = {
-                        ...oldSchema,
-                        checkConstraints: Object.freeze(oldSchema.checkConstraints.map(c => (c.name?.toLowerCase() === oldLower ? { ...c, name: change.newName } : c))),
-                    };
-                }
-                else if (constraintClass === 'foreignKey') {
-                    updatedSchema = {
-                        ...oldSchema,
-                        foreignKeys: Object.freeze(oldSchema.foreignKeys.map(c => (c.name?.toLowerCase() === oldLower ? { ...c, name: change.newName } : c))),
-                    };
-                }
-                else {
-                    updatedSchema = {
-                        ...oldSchema,
-                        uniqueConstraints: Object.freeze(oldSchema.uniqueConstraints.map(c => (c.name?.toLowerCase() === oldLower ? { ...c, name: change.newName } : c))),
-                    };
-                }
-                table.updateSchema(updatedSchema);
-                await this.saveTableDDL(updatedSchema);
-                this.eventEmitter?.emitSchemaChange({
-                    type: 'alter',
-                    objectType: 'table',
-                    schemaName,
-                    objectName: tableName,
-                });
-                return updatedSchema;
+        }
+        // SET COLLATE on a PRIMARY KEY member (Option B physical re-key): re-encode
+        // every data-store key under the column's new key collation, then rebuild every
+        // secondary index (its keys embed the PK suffix). `rekeyRows` validates in a
+        // first pass and throws CONSTRAINT on a collision under the new collation WITHOUT
+        // mutating the store — so a coarser collation that collapses two distinct PKs
+        // (e.g. 'a'/'A' under BINARY→NOCASE) is rejected all-or-nothing, mirroring
+        // ALTER PRIMARY KEY. Runs AFTER the non-PK UNIQUE re-validation above so both
+        // throw-only checks precede the first store mutation. `updatedSchema.columns`
+        // carries the new collation, so the new key bytes follow it.
+        if (collationChanged && oldSchema.primaryKeyDefinition.some(def => def.index === colIndex)) {
+            // Physical re-key ahead — flush buffered writes (see
+            // {@link ddlCommitPendingOps}). Deliberately AFTER the non-PK UNIQUE
+            // re-validation above: that check reads effectively and throws without
+            // needing the flush, so it must keep the transaction alive.
+            //
+            // NOTE: `rekeyRows` detects PK collisions among THIS module's rows only. When a
+            // wrapper module supplied `rows`, its staged rows are not in this store, so a
+            // pending row that collides with a committed one under the new collation is
+            // caught by neither side — the wrapper's overlay enforces the PK among its own
+            // rows, this store among its own. Closing it needs a PK-dedupe pass over `rows`
+            // under the new collation here, before the re-key.
+            await this.ddlCommitPendingOps();
+            await table.rekeyRows(oldSchema.primaryKeyDefinition, updatedSchema.columns);
+            // Materialize so the implicit `_uc_*` PK suffix is re-encoded under the new
+            // key collation too (`updatedSchema` carries none on its own).
+            await this.rebuildSecondaryIndexes(schemaName, tableName, table, withImplicitUniqueIndexes(updatedSchema), db.getKeyNormalizerResolver());
+        }
+        // SET DATA TYPE physical conversion / SET NOT NULL DEFAULT backfill rewrote stored
+        // column values in place (same PK, new value) via mapRowsAtIndex. Secondary index KEY
+        // bytes encode the indexed column VALUES, so any index covering this column still points
+        // at the OLD value bytes until rebuilt — an index-backed lookup for the new value finds
+        // nothing (mirrors the memory module's `valuesRewritten` rebuild in MemoryTableManager.
+        // alterColumn). The sub-helper already ran ddlCommitPendingOps before its rewrite, so the
+        // committed data store rebuildSecondaryIndexes reads is "everything live". Mutually
+        // exclusive with the collation re-key above (distinct attributes), so no double rebuild.
+        // Materialize so an implicit `_uc_*` over the rewritten column is rebuilt against the
+        // new value bytes too.
+        if (valuesRewritten) {
+            await this.rebuildSecondaryIndexes(schemaName, tableName, table, withImplicitUniqueIndexes(updatedSchema), db.getKeyNormalizerResolver());
+        }
+        table.updateSchema(updatedSchema);
+        await this.saveTableDDL(updatedSchema);
+        this.eventEmitter?.emitSchemaChange({
+            type: 'alter',
+            objectType: 'table',
+            schemaName,
+            objectName: tableName,
+        });
+        return updatedSchema;
+    }
+    /**
+     * SET NOT NULL / DROP NOT NULL sub-branch of {@link alterColumnChange}. Returns the
+     * new column schema, or null when the column is already in the desired nullability
+     * (the pre-refactor `return oldSchema` no-op). The NULL-backfill probe and rewrite
+     * order (throw-only probe before {@link ddlCommitPendingOps}) is unchanged.
+     *
+     * `rows` is the wrapper-supplied effective row source (the isolation overlay). When present,
+     * the reject-vs-backfill decision scans it instead of `table.rowsWithNullAtIndex`: behind the
+     * isolation layer the issuer's pending inserts live in the wrapper's overlay, not this store,
+     * so the store's own count would miss them and wrongly accept the ALTER. The committed-store
+     * `mapRowsAtIndex` backfill is unchanged — the overlay-resident pending rows are the isolation
+     * layer's job (its overlay migration), this store only owns its committed rows.
+     */
+    async alterColumnSetNotNull(table, oldSchema, oldCol, colIndex, change, rows) {
+        let newCol;
+        let valuesRewritten = false;
+        if (change.setNotNull === true && !oldCol.notNull) {
+            // Backfill NULLs from a literal DEFAULT, or throw.
+            let defaultLiteral;
+            const expr = oldCol.defaultValue;
+            if (expr && expr.type === 'literal') {
+                defaultLiteral = expr.value ?? null;
             }
-            case 'alterColumn': {
-                const colNameLower = change.columnName.toLowerCase();
-                const colIndex = oldSchema.columns.findIndex(c => c.name.toLowerCase() === colNameLower);
-                if (colIndex === -1) {
-                    throw new QuereusError(`Column '${change.columnName}' not found.`, StatusCode.ERROR);
-                }
-                const oldCol = oldSchema.columns[colIndex];
-                let newCol = oldCol;
-                // A collation change needs existing-row UNIQUE re-validation below
-                // (non-PK, Option A); the other attribute changes do not.
-                let collationChanged = false;
-                // Pull exactly one of the three attributes from the change.
-                if (change.setNotNull !== undefined) {
-                    if (change.setNotNull === true && !oldCol.notNull) {
-                        // Backfill NULLs from a literal DEFAULT, or throw.
-                        let defaultLiteral;
-                        const expr = oldCol.defaultValue;
-                        if (expr && expr.type === 'literal') {
-                            defaultLiteral = expr.value ?? null;
-                        }
-                        const nullCount = await table.rowsWithNullAtIndex(colIndex);
-                        if (nullCount > 0) {
-                            if (defaultLiteral === undefined || defaultLiteral === null) {
-                                throw new QuereusError(`column ${change.columnName} contains NULL values`, StatusCode.CONSTRAINT);
-                            }
-                            const fill = defaultLiteral;
-                            await table.mapRowsAtIndex(colIndex, (v) => v === null ? fill : v);
-                        }
-                        newCol = { ...oldCol, notNull: true };
-                    }
-                    else if (change.setNotNull === false && oldCol.notNull) {
-                        if (oldSchema.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 {
-                        return oldSchema; // already in desired state
-                    }
-                }
-                else if (change.setDataType !== undefined) {
-                    const newLogicalType = inferType(change.setDataType);
-                    if (newLogicalType.physicalType !== oldCol.logicalType.physicalType) {
-                        // Physical conversion required — walk every row and attempt parse.
-                        await table.mapRowsAtIndex(colIndex, (v) => {
-                            if (v === null)
-                                return v;
-                            try {
-                                return validateAndParse(v, newLogicalType, change.columnName);
-                            }
-                            catch {
-                                throw new QuereusError(`Cannot convert value in '${change.columnName}' to ${change.setDataType}`, StatusCode.MISMATCH);
-                            }
-                        });
+            // Decide reject-vs-backfill over the DDL transaction's EFFECTIVE rows. `rows()` (the
+            // isolation overlay) sees the issuer's pending inserts; `rowsWithNullAtIndex` (run
+            // directly, no wrapper) sees the store's own effective rows. Either way a NULL the
+            // transaction can see is backfilled, or rejects the ALTER, like any other row.
+            let anyNull;
+            if (rows) {
+                anyNull = false;
+                for await (const row of rows()) {
+                    if (row[colIndex] === null) {
+                        anyNull = true;
+                        break;
                     }
-                    newCol = { ...oldCol, logicalType: newLogicalType };
                 }
-                else if (change.setDefault !== undefined) {
-                    newCol = { ...oldCol, defaultValue: change.setDefault };
-                }
-                else if (change.setCollation !== undefined) {
-                    // Per-column collation update. PRIMARY KEY uniqueness/ordering is enforced
-                    // PHYSICALLY in the key bytes under a PER-COLUMN key collation
-                    // (`StoreTable.pkKeyCollations`), so a PK-column SET COLLATE is honored
-                    // natively by physically re-keying the data store + rebuilding every
-                    // secondary index under the new collation (the `isPkColumn` block below),
-                    // mirroring the memory module's primary re-key. A re-key that would collide
-                    // under the new collation throws CONSTRAINT before any mutation. For non-PK
-                    // UNIQUE constraints we re-validate existing rows under the new collation
-                    // (Option A). Query-layer ORDER BY / `=` / `table_info().collation` pick the
-                    // new collation up from the column schema once this updated schema re-registers.
-                    const normalized = validateCollationForType(change.setCollation, oldCol.logicalType, change.columnName);
-                    const nameMatches = normalized === (oldCol.collation || 'BINARY');
-                    if (nameMatches && oldCol.collationExplicit) {
-                        return oldSchema; // already explicit in the desired collation — no scan, no re-key, no re-persist
-                    }
-                    // 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 to skip rekeyRows / validateUniqueOverExistingRows
-                    // below while still re-registering the schema and re-persisting DDL.
-                    // A different name takes the full physical re-key path AND sets the flag.
-                    newCol = { ...oldCol, collation: normalized, collationExplicit: true };
-                    collationChanged = !nameMatches;
-                }
-                else {
-                    throw new QuereusError('ALTER COLUMN requires an attribute to change', StatusCode.INTERNAL);
+            }
+            else {
+                anyNull = (await table.rowsWithNullAtIndex(colIndex)) > 0;
+            }
+            if (anyNull) {
+                if (defaultLiteral === undefined || defaultLiteral === null) {
+                    // Throw-only, and before the DDL-commit below: the transaction survives.
+                    throw new QuereusError(`column ${change.columnName} contains NULL values`, StatusCode.CONSTRAINT);
                 }
-                const updatedColumns = oldSchema.columns.map((c, i) => i === colIndex ? newCol : c);
-                // Mirror the memory module (MemoryTableManager.alterColumn): a per-column
-                // collation change propagates into every index column ordering by this
-                // column, so a `derivedFromIndex` UNIQUE re-keys its enforcement under the
-                // new collation. StoreTable.uniqueEnforcementCollations reads the index's
-                // per-column collation, so without this the index entry would stay stale
-                // and the derived UNIQUE would keep enforcing the OLD collation after the
-                // ALTER. Metadata-only: the store's index KEY bytes use the table-level key
-                // collation K (see buildIndexEntries / updateSecondaryIndexes), so no index
-                // entry re-encode is required for a non-PK column. An index column with an
-                // explicit COLLATE is re-collated too — matching memory, which clobbers it
-                // the same way (no surface preserves a differing index COLLATE across an
-                // ALTER COLUMN SET COLLATE on its column).
-                const updatedIndexes = (collationChanged && oldSchema.indexes)
-                    ? oldSchema.indexes.map(idx => ({
-                        ...idx,
-                        columns: idx.columns.map(ic => ic.index === colIndex ? { ...ic, collation: newCol.collation } : ic),
-                    }))
-                    : oldSchema.indexes;
-                const updatedSchema = {
-                    ...oldSchema,
-                    columns: Object.freeze(updatedColumns),
-                    columnIndexMap: buildColumnIndexMap(updatedColumns),
-                    indexes: updatedIndexes ? Object.freeze(updatedIndexes) : updatedIndexes,
-                };
-                // SET COLLATE existing-row re-validation (Option A, non-PK UNIQUE): a new
-                // per-column collation can make rows that were distinct under the old
-                // collation collide. Re-scan every UNIQUE constraint covering the altered
-                // column under the NEW collation (`updatedSchema` carries it). The first
-                // collision throws CONSTRAINT BEFORE any mutation/persist, so the table is
-                // left unchanged and writable (matches the ADD CONSTRAINT rollback shape).
-                // The PK is intentionally excluded — it never appears in `uniqueConstraints`;
-                // its physical re-key/re-validation is the `isPkColumn` block below.
-                if (collationChanged) {
-                    const coveringConstraints = (updatedSchema.uniqueConstraints ?? [])
-                        .filter(uc => uc.columns.includes(colIndex));
-                    if (coveringConstraints.length > 0) {
-                        const dataStore = await this.getStore(tableKey, table.getConfig());
-                        for (const uc of coveringConstraints) {
-                            await this.validateUniqueOverExistingRows(dataStore, updatedSchema, uc);
-                        }
-                    }
+                const fill = defaultLiteral;
+                // Physical rewrite ahead — flush buffered writes so `mapRowsAtIndex` backfills this
+                // store's own NULL rows. Run directly, that also fills the transaction's rows (the
+                // probe saw them). Behind isolation the issuer's overlay-resident NULL rows are
+                // filled by the isolation layer's overlay migration, not here — this store never
+                // holds them. See {@link ddlCommitPendingOps}.
+                await this.ddlCommitPendingOps();
+                await table.mapRowsAtIndex(colIndex, (v) => v === null ? fill : v);
+                valuesRewritten = true;
+            }
+            newCol = { ...oldCol, notNull: true };
+        }
+        else if (change.setNotNull === false && oldCol.notNull) {
+            if (oldSchema.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 {
+            return null; // already in desired state
+        }
+        return { newCol, collationChanged: false, valuesRewritten };
+    }
+    /**
+     * SET DATA TYPE sub-branch of {@link alterColumnChange}. Returns the retyped column
+     * schema. When the physical type changes, a throw-only convert pass over the live
+     * rows precedes {@link ddlCommitPendingOps} and the rewrite — order unchanged.
+     */
+    async alterColumnSetDataType(table, oldCol, colIndex, change) {
+        const newLogicalType = inferType(change.setDataType);
+        let valuesRewritten = false;
+        if (newLogicalType.physicalType !== oldCol.logicalType.physicalType) {
+            // Physical conversion required — walk every row and attempt parse.
+            const convert = (v) => {
+                try {
+                    return validateAndParse(v, newLogicalType, change.columnName);
                 }
-                // SET COLLATE on a PRIMARY KEY member (Option B physical re-key): re-encode
-                // every data-store key under the column's new key collation, then rebuild every
-                // secondary index (its keys embed the PK suffix). `rekeyRows` validates in a
-                // first pass and throws CONSTRAINT on a collision under the new collation WITHOUT
-                // mutating the store — so a coarser collation that collapses two distinct PKs
-                // (e.g. 'a'/'A' under BINARY→NOCASE) is rejected all-or-nothing, mirroring
-                // ALTER PRIMARY KEY. Runs AFTER the non-PK UNIQUE re-validation above so both
-                // throw-only checks precede the first store mutation. `updatedSchema.columns`
-                // carries the new collation, so the new key bytes follow it.
-                if (collationChanged && oldSchema.primaryKeyDefinition.some(def => def.index === colIndex)) {
-                    await table.rekeyRows(oldSchema.primaryKeyDefinition, updatedSchema.columns);
-                    await this.rebuildSecondaryIndexes(schemaName, tableName, tableKey, table, updatedSchema);
+                catch {
+                    throw new QuereusError(`Cannot convert value in '${change.columnName}' to ${change.setDataType}`, StatusCode.MISMATCH);
                 }
-                table.updateSchema(updatedSchema);
-                await this.saveTableDDL(updatedSchema);
-                this.eventEmitter?.emitSchemaChange({
-                    type: 'alter',
-                    objectType: 'table',
-                    schemaName,
-                    objectName: tableName,
-                });
-                return updatedSchema;
+            };
+            // Throw-only pass over the LIVE rows first, so an unconvertible value
+            // this transaction inserted rejects the ALTER with the transaction still
+            // intact. The rewrite below reads only committed rows.
+            for await (const value of table.iterateEffectiveValuesAtIndex(colIndex)) {
+                if (value !== null)
+                    convert(value);
             }
+            // Physical rewrite ahead — flush buffered writes so `mapRowsAtIndex`
+            // converts this transaction's rows too; unflushed, they would replay
+            // under the OLD physical type. See {@link ddlCommitPendingOps}.
+            await this.ddlCommitPendingOps();
+            await table.mapRowsAtIndex(colIndex, (v) => v === null ? v : convert(v));
+            valuesRewritten = true;
         }
+        return { newCol: { ...oldCol, logicalType: newLogicalType }, collationChanged: false, valuesRewritten };
+    }
+    /**
+     * SET COLLATE sub-branch of {@link alterColumnChange}. Returns the recollated column
+     * schema with `collationChanged` set when the collation bytes actually change (a bare
+     * metadata flip keeps it false), or null when the column is already explicit in the
+     * desired collation (the pre-refactor `return oldSchema` no-op). Synchronous — no
+     * row scan happens here; the caller runs the re-validation / re-key the flag gates.
+     */
+    alterColumnSetCollation(oldCol, change, isCollationRegistered) {
+        // Per-column collation update. PRIMARY KEY uniqueness/ordering is enforced
+        // PHYSICALLY in the key bytes under a PER-COLUMN key collation
+        // (`StoreTable.pkKeyCollations`), so a PK-column SET COLLATE is honored
+        // natively by physically re-keying the data store + rebuilding every
+        // secondary index under the new collation (the `isPkColumn` block below),
+        // mirroring the memory module's primary re-key. A re-key that would collide
+        // under the new collation throws CONSTRAINT before any mutation. For non-PK
+        // UNIQUE constraints we re-validate existing rows under the new collation
+        // (Option A). Query-layer ORDER BY / `=` / `table_info().collation` pick the
+        // new collation up from the column schema once this updated schema re-registers.
+        const normalized = validateCollationForType(change.setCollation, oldCol.logicalType, change.columnName, isCollationRegistered);
+        const nameMatches = normalized === (oldCol.collation || 'BINARY');
+        if (nameMatches && oldCol.collationExplicit) {
+            return null; // already explicit in the desired collation — no scan, no re-key, no re-persist
+        }
+        // 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 to skip rekeyRows / validateUniqueOverExistingRows
+        // below while still re-registering the schema and re-persisting DDL.
+        // A different name takes the full physical re-key path AND sets the flag.
+        return { newCol: { ...oldCol, collation: normalized, collationExplicit: true }, collationChanged: !nameMatches };
     }
     /**
      * Rename a store-backed table.
@@ -1290,7 +1858,11 @@ export class StoreModule {
         // Authoritative index list (exact store names): the provider relocates
         // exactly these index stores instead of prefix-scanning `{oldName}_idx_`,
         // which would also catch a sibling table named `{oldName}_idx_<x>`.
-        const indexNames = (currentSchema?.indexes ?? []).map(i => i.name);
+        // MATERIALIZED, so the hidden `_uc_*` store realizing a plain UNIQUE moves with
+        // the table — otherwise the renamed table seeks a fresh EMPTY `_uc_*` and silently
+        // accepts a duplicate of a pre-rename row. `currentSchema` itself stays
+        // non-materialized: the catalog DDL rewritten below must carry no `_uc_*`.
+        const indexNames = this.materializedIndexNames(existing, currentSchema);
         // Reject when ANY physical name the rename introduces — the new data store
         // AND each relocated index store `{schema}.{newName}_idx_{x}` — already
         // names an existing store. E.g. rename some table to `q_idx_archive` while
@@ -1308,20 +1880,10 @@ export class StoreModule {
         for (const indexName of indexNames) {
             this.assertStoreNameFree(db, schemaName, buildIndexStoreName(schemaName, newName, indexName), `index store of index '${indexName}' on table '${schemaName}.${newName}' (rename target)`, occupied);
         }
-        // ALTER TABLE is effectively DDL-committing on a store-backed table:
-        // once we move the on-disk directory, prior buffered writes can no
-        // longer be rolled back through the coordinator. Flush any pending
-        // ops NOW, before the old store's handle is closed. Subsequent
-        // commit() calls on the same coordinator are no-ops (inTransaction
-        // is cleared), which keeps the enclosing transaction safe.
-        //
-        // The coordinator is module-wide, so this DDL-commits the WHOLE module
-        // transaction — every table's pending ops, not just the renamed table's —
-        // in one all-or-nothing batch. That is the correct, consistent posture
-        // for a store DDL-commit: an ALTER cannot half-commit some sibling tables.
-        if (this.moduleCoordinator?.isInTransaction()) {
-            await this.moduleCoordinator.commit();
-        }
+        // Flush buffered writes before the old store's handle is closed: once the
+        // on-disk directory moves, prior buffered ops address stores that no longer
+        // exist under those names. See {@link ddlCommitPendingOps}.
+        await this.ddlCommitPendingOps();
         // Hard-dispose the evicted handle: flush any lazy stats it was buffering AND
         // deregister its coordinator stats-callback pair (the renamed instance is
         // gone after this — the next connect()/getOrReconnectTable mints a fresh one
@@ -1339,15 +1901,32 @@ export class StoreModule {
         this.stores.delete(oldKey);
         // The coordinator is module-wide (flushed above); it is not per-table, so
         // it is not evicted here.
-        // Evict the disposed instance's registered engine connection. It is bound to
-        // the OLD qualified name and its owning StoreTable is now disposed, so it is
-        // definitively stale. Unlike drop — where the engine's schema manager calls
-        // `removeConnectionsForTable` for us — the generic rename path
-        // (`alter-table.ts` renameTableImpl) does NOT, so the store must evict it
-        // here or the connection leaks one per rename. Safe because the module
-        // DDL-commit above already flushed its pending ops (no uncommitted writes to
-        // lose).
-        db.removeConnectionsForTable(schemaName, oldName);
+        // Evict the disposed instance's registered engine connections — but ONLY the
+        // ones this module created. Unlike drop — where the engine's schema manager
+        // calls `removeConnectionsForTable` for us — the generic rename path
+        // (`alter-table.ts` renameTableImpl) does NOT, so the store must evict here or
+        // a StoreConnection leaks one per rename. Safe for `StoreConnection`s (both the
+        // StoreTable-owned DML connection and the StoreBackingHost-owned one): they hold
+        // no state of their own, delegating to the module-wide coordinator that the
+        // DDL-commit above already flushed, and their owning StoreTable is now disposed.
+        //
+        // A blanket name-keyed sweep is NOT safe: a wrapping module (the isolation layer)
+        // registers its own connection under the same qualified name, and that connection
+        // is the only thing that drives its staged overlay to storage at COMMIT. Evicting
+        // it silently drops the transaction's writes.
+        //
+        // NOTE: a rename onto a never-before-used name leaves the wrapper's connection
+        // registered under the stale old name (it is not retargeted here). Benign — the
+        // commit flush resolves overlays db-wide by their re-keyed names — but a workload
+        // that renames one table through many distinct names in a single process
+        // accumulates one such connection per name. If that ever matters, retarget the
+        // connection's `tableName` across the rename instead of leaving it stale.
+        const oldQualified = `${schemaName}.${oldName}`.toLowerCase();
+        for (const conn of db.getAllConnections()) {
+            if (conn instanceof StoreConnection && conn.tableName.toLowerCase() === oldQualified) {
+                db.removeConnection(conn.connectionId);
+            }
+        }
         // Move physical storage (data directory + index directories).
         if (this.provider.renameTableStores) {
             await this.provider.renameTableStores(schemaName, oldName, newName, indexNames);
@@ -1356,18 +1935,85 @@ export class StoreModule {
         // so a crash mid-rename leaves the table discoverable under at least one
         // name rather than neither.
         if (currentSchema) {
-            const renamedSchema = { ...currentSchema, name: newName };
-            await this.saveTableDDL(renamedSchema);
+            const renamedSchema = {
+                ...currentSchema,
+                name: newName,
+                // A self-referencing FK is persisted as `references <oldName>(...)`; after
+                // `removeTableDDL` below, that names a table no longer in the catalog. Pure
+                // copy — no rollback needed, `renamedSchema` is local to the write.
+                foreignKeys: retargetSelfForeignKeys(currentSchema.foreignKeys, schemaName, oldName, newName),
+            };
+            // A partial index's WHERE clause and a CHECK constraint's expression can each
+            // carry a table-qualified self-reference (`where t.b > 0`) still naming the OLD
+            // table: `propagateTableRename` runs only after this hook returns, so — exactly
+            // as in the `renameColumn` arm of `alterTable` — persisting now would durably
+            // write a stale qualifier that only the later propagation event corrects.
+            // Rewrite first, in place (each `Expression` is shared with the catalog
+            // `TableSchema` and, for a unique partial index, with its derived UNIQUE
+            // constraint), which also makes that later pass a no-op for these fields. A
+            // throw anywhere in the `try` — including partway through a walk — reverses the
+            // rewrites; reversing is a no-op wherever nothing names `newName`. The physical
+            // stores have already moved by this point, so the reverse restores only the AST,
+            // not the on-disk layout.
+            //
+            // NOTE: the reverse assumes no expression legitimately named `newName` before
+            // the rename. The rename-target guard above makes that true for a real table,
+            // and `compilePredicate` now rejects a foreign `table` qualifier at create time,
+            // so a live partial-index predicate can only carry a self-qualifier (`where
+            // <thisTable>.b > 0`) or a bare reference — never `where <newName>.b > 0` for a
+            // different table. The mis-reversal path is therefore unreachable for a live
+            // predicate.
+            const rewriteTable = (from, to) => {
+                renameTableInIndexPredicates(currentSchema.indexes, from, to, schemaName);
+                renameTableInCheckConstraints(currentSchema.checkConstraints, from, to, schemaName);
+            };
+            try {
+                rewriteTable(oldName, newName);
+                await this.saveTableDDL(renamedSchema);
+            }
+            catch (e) {
+                rewriteTable(newName, oldName);
+                throw e;
+            }
         }
-        await this.removeTableDDL(schemaName, oldName);
-        // Relocate the stats entry (unified __stats__ store, keyed by schema.table).
+        // NOTE: the OLD name's catalog entry is deliberately NOT removed here. Deleting it
+        // synchronously would drop `oldName` from the catalog BEFORE the engine's post-hook
+        // `propagateTableRename` has rewritten — let alone persisted — the OTHER tables /
+        // views / MVs that still name `oldName` (a cross-schema FK, a CHECK expression, a
+        // dependent view/MV body). A crash in that gap would strand a durable catalog set
+        // naming a vanished table, which reopens as a healthy-looking database whose
+        // dependents cannot be written to. The removal is deferred to `finalizeRename`,
+        // which the engine calls AFTER propagation has made the dependents durable.
+        // Migrate the stats entry (unified __stats__ store, keyed by schema.table).
+        // The entry is RE-KEYED, not physically moved with the directory: a unified
+        // store keys every table's stats under `schema.table` in one store, so the
+        // value must be copied from the old key to the new key and the old key
+        // dropped. `dispose()` above already flushed any buffered delta to disk under
+        // the old key, so the read here sees the current row-count estimate; deleting
+        // without copying (the prior behavior) blinded the planner — a freshly-renamed
+        // table reported getEstimatedRowCount() === 0 until stats were re-gathered.
+        //
+        // NOTE: this re-key reaches the old value only when getStatsStore(newName)
+        // returns a store that CONTAINS the old key — true for the shipped providers,
+        // which all share one unified __stats__ store, and for any provider whose
+        // renameTableStores physically relocates a per-table stats store. A provider
+        // that kept per-table stats stores and did NOT relocate them in
+        // renameTableStores would orphan the old-keyed value out of reach here (the
+        // prior delete-only code lost it just the same — no regression). No shipped
+        // provider does this; revisit if one ever keeps per-table, non-relocated stats.
         try {
             const statsStore = await this.provider.getStatsStore(schemaName, newName);
             const oldStatsKey = buildStatsKey(schemaName, oldName);
+            const statsValue = await statsStore.get(oldStatsKey);
+            if (statsValue) {
+                // A table with no stats yet (never flushed) returns undefined here —
+                // skip the copy so no spurious zero-count entry lands under the new key.
+                await statsStore.put(buildStatsKey(schemaName, newName), statsValue);
+            }
             await statsStore.delete(oldStatsKey);
         }
         catch {
-            /* stats are advisory — a stale entry under the old key is harmless */
+            /* stats are advisory — a stats hiccup must never block the rename */
         }
         this.eventEmitter?.emitSchemaChange({
             type: 'alter',
@@ -1376,6 +2022,32 @@ export class StoreModule {
             objectName: newName,
         });
     }
+    /**
+     * Second phase of a two-phase RENAME TABLE (see {@link renameTable}). The engine calls
+     * this at the END of ALTER TABLE ... RENAME TO — AFTER its `propagateTableRename` has
+     * rewritten every dependent object that named `oldName` and enqueued their corrective
+     * catalog writes onto {@link persistQueue}. `renameTable` deliberately left `oldName`'s
+     * catalog entry in place; here we drain those dependent writes to durability and only
+     * THEN drop the old entry. During the window both entries coexist on disk, so every
+     * dependent resolves against one of them and every intermediate catalog set rehydrates
+     * into a working database.
+     *
+     * The old-entry delete rides `persistQueue` behind the dependents' already-enqueued
+     * writes (FIFO), so it can only run after them, and the drain below awaits the whole
+     * chain. Errors are swallowed+logged (the {@link enqueuePersist} contract): a failed
+     * delete leaves the old entry present — a visible, droppable orphan, strictly safer
+     * than a dependent stranded against a vanished table.
+     *
+     * NOTE: full cross-table atomicity — bundling this old-entry delete together with every
+     * dependent rewrite into one `provider.beginAtomicBatch` commit — would eliminate even
+     * the transient two-entry window (and the physical-move orphan `renameTableStores`
+     * leaves), but only on atomic providers, and the dependent set is known only to the
+     * engine post-propagate. That is the atomic-provider hardening path; out of scope here.
+     */
+    async finalizeRename(_db, schemaName, oldName, _newName) {
+        this.enqueuePersist(() => this.removeTableDDL(schemaName, oldName));
+        await this.whenCatalogPersisted();
+    }
     /**
      * Modern access planning interface.
      *
@@ -1389,26 +2061,41 @@ export class StoreModule {
      * (via `StoreTable.buildPKRangeBounds`) encodes the LT/LE/GT/GE bounds under the
      * same per-column key collations the data keys use and iterates that
      * seek-start/early-termination window. The window is a SUPERSET, so the post-fetch
-     * row filter still reproduces the exact collation semantics — and a comparator-only
-     * collation with no byte encoder safely falls back to a full scan. Mirrors the
-     * memory module's advertisement.
+     * row filter still reproduces the exact collation semantics. (A collation that cannot
+     * key at all never reaches a PK column: `StoreTable`'s constructor rejects it at DDL
+     * time.) Mirrors the memory module's advertisement.
+     *
+     * The seek/ordering claims are additionally gated on the key collation being
+     * ORDER-PRESERVING — byte order and comparator order must coincide, or the seek would
+     * under-fetch and the ordering advertisement would elide a Sort it must not. That gate
+     * needs the connection's collation registry, hence `db` is threaded down.
      */
-    getBestAccessPlan(_db, tableInfo, request) {
-        return { ...this.computeBestAccessPlan(tableInfo, request), honorsCollatedRangeBounds: true };
+    getBestAccessPlan(db, tableInfo, request) {
+        return { ...this.computeBestAccessPlan(db, tableInfo, request), honorsCollatedRangeBounds: true };
     }
-    computeBestAccessPlan(tableInfo, request) {
+    computeBestAccessPlan(db, tableInfo, request) {
         const estimatedRows = request.estimatedRows ?? 1000;
-        // Check for primary key equality constraints
+        // Table key collation K (default NOCASE). Any K reaching here has a key normalizer:
+        // `StoreTable`'s constructor rejects one that cannot key, and a name we cannot resolve
+        // to a table falls back to the built-in NOCASE. `||`, not `??`, so an empty-string
+        // `config.collation` reads as the default here exactly as it does in
+        // `StoreTable.encodeOptions` — the two must agree or `analyzePKAccess` would decline a
+        // window `computeBestAccessPlan` already marked handled.
+        const tableKeyCollation = (this.getTable(tableInfo.schemaName, tableInfo.name)?.getConfig().collation || 'NOCASE').toUpperCase();
+        // Check for primary key equality constraints. Count DISTINCT pinned PK columns:
+        // counting raw '=' filters would read `a = 1 and a = 2` on a composite PK (a, b)
+        // as "both PK columns pinned", claim both filters handled, then — with no
+        // complete PK equality set to seek — degrade to a sequential scan whose residual
+        // has already been discarded, returning the whole table.
         const pkColumns = tableInfo.primaryKeyDefinition.map(pk => pk.index);
-        const pkFilters = request.filters.filter(f => f.columnIndex !== undefined &&
-            pkColumns.includes(f.columnIndex) &&
-            f.op === '=');
-        if (pkFilters.length === pkColumns.length && pkColumns.length > 0) {
+        const pinnedPkColumns = new Set(request.filters
+            .filter(f => f.columnIndex !== undefined && pkColumns.includes(f.columnIndex) && f.op === '=')
+            .map(f => f.columnIndex));
+        if (pinnedPkColumns.size === pkColumns.length && pkColumns.length > 0) {
             // Full PK match - point lookup (single row; no monotonic advertisement)
-            const handledFilters = request.filters.map(f => pkFilters.some(pf => pf.columnIndex === f.columnIndex && pf.op === f.op));
             return AccessPlanBuilder
                 .eqMatch(1, 0.1)
-                .setHandledFilters(handledFilters)
+                .setHandledFilters(claimFirstPerRole(request.filters, equalityRoles(pkColumns)))
                 .setIsSet(true)
                 .setIndexName('_primary_')
                 .setExplanation('Store primary key lookup')
@@ -1419,50 +2106,61 @@ export class StoreModule {
         // range bounds for primaryKeyDefinition[0]; ranges on later PK columns
         // are silently dropped if marked handled. So only claim handled=true
         // when the range is on the first PK column.
-        const rangeOps = ['<', '<=', '>', '>='];
+        //
+        // The seek is also declined when the leading PK column's key bytes do not order the
+        // way its comparator does (`pkOrderPreservingPrefix === 0`): `StoreTable.analyzePKAccess`
+        // declines the byte window under exactly that condition, so claiming the range filters
+        // handled here would drop the residual Filter and return the whole table.
+        const pkOrderPreservingPrefix = pkOrderPreservingPrefixLength(db, tableInfo, resolvePkKeyCollations(tableInfo.primaryKeyDefinition, tableInfo.columns, tableKeyCollation), tableKeyCollation);
         const firstPkColumn = tableInfo.primaryKeyDefinition[0]?.index;
-        const rangeFilters = firstPkColumn !== undefined
-            ? request.filters.filter(f => f.columnIndex === firstPkColumn &&
-                rangeOps.includes(f.op))
-            : [];
-        if (rangeFilters.length > 0) {
+        const hasLeadingPkRange = firstPkColumn !== undefined
+            && pkOrderPreservingPrefix >= 1
+            && request.filters.some(f => f.columnIndex === firstPkColumn && RANGE_OPS.includes(f.op));
+        if (hasLeadingPkRange) {
             // Range scan on first PK column. Iteration is by PK key order (see
             // StoreTable.scanPKRange), so we can advertise monotonic emission on
             // the leading PK column. The scan seeks to the window start and
             // early-terminates (StoreTable.buildPKRangeBounds derives the encoded
             // bounds), and the leading-PK order guarantee holds throughout.
-            const handledFilters = request.filters.map(f => rangeFilters.some(rf => rf.columnIndex === f.columnIndex && rf.op === f.op));
             const rangeRows = Math.max(1, Math.floor(estimatedRows * 0.3));
             const plan = AccessPlanBuilder
                 .rangeScan(rangeRows, 0.2)
-                .setHandledFilters(handledFilters)
+                .setHandledFilters(claimFirstPerRole(request.filters, rangeRoles(firstPkColumn)))
                 .setIndexName('_primary_')
                 .setSeekColumns([firstPkColumn])
                 .setExplanation('Store primary key range scan')
                 .build();
-            return { ...plan, ...this.buildPkOrderingAdvertisement(tableInfo, request) };
-        }
-        // Check for secondary index usage
-        // Note: query() does not yet implement secondary index scans — it falls
-        // back to a full table scan + matchesFilters.  We still advertise better
-        // cost estimates when a usable index exists (so the planner prefers this
-        // table access) but we must NOT mark filters as handled, otherwise the
-        // engine won't supply them to matchesFilters and rows pass unfiltered.
+            return { ...plan, ...this.buildPkOrderingAdvertisement(tableInfo, request, pkOrderPreservingPrefix) };
+        }
+        // Check for secondary index usage. `StoreTable.query` now implements the
+        // secondary-index scan arm (leading-prefix EQ point / leading-column range),
+        // so we advertise the index with `indexName` + `seekColumns` and mark the
+        // covered filters handled — subject to the collation-safety guard in
+        // {@link tryIndexAccessPlan}. A cost-only plan (no seek) is kept as a fallback
+        // when no index yields a collation-safe seek, preserving the prior "cheaper
+        // cost, filters unhandled, residual retained" behavior.
         const indexes = tableInfo.indexes || [];
+        let costOnlyFallback = null;
         for (const index of indexes) {
-            const indexColumns = index.columns.map(c => c.index);
-            const indexFilters = request.filters.filter(f => f.columnIndex !== undefined &&
-                indexColumns.includes(f.columnIndex) &&
-                f.op === '=');
-            if (indexFilters.length > 0) {
-                const matchedRows = Math.max(1, Math.floor(estimatedRows * 0.1));
-                return AccessPlanBuilder
-                    .eqMatch(matchedRows, 0.3)
-                    .setHandledFilters(new Array(request.filters.length).fill(false))
-                    .setExplanation(`Store index scan on ${index.name}`)
-                    .build();
-            }
+            if (index.columns.length === 0)
+                continue;
+            const plan = this.tryIndexAccessPlan(db, tableKeyCollation, tableInfo, request, index, estimatedRows);
+            if (!plan)
+                continue;
+            // A fully-handled seek (indexName + seekColumns set) wins immediately.
+            if (plan.seekColumnIndexes && plan.seekColumnIndexes.length > 0)
+                return plan;
+            // Otherwise remember the first cost-only advertisement as a fallback.
+            if (!costOnlyFallback)
+                costOnlyFallback = plan;
         }
+        // NOTE: a cost-only plan carries no PK-order advertisement even though the store still
+        // iterates in PK key order for it (`StoreTable.query` full-scans). The range gate makes
+        // this arm fire more often — an index range on a BINARY text column of a default-K table
+        // now lands here — so `... where v > 'x' order by <pk>` picks up a Sort it did not need.
+        // If that shows up as slow, merge `buildPkOrderingAdvertisement(...)` into this return.
+        if (costOnlyFallback)
+            return costOnlyFallback;
         // Fallback to full scan. The store iterates rows in PK key order
         // (see StoreTable.query / store.iterate over buildFullScanBounds), so
         // the scan is monotonic on the leading PK column. Advertise that so
@@ -1473,7 +2171,115 @@ export class StoreModule {
             .setHandledFilters(new Array(request.filters.length).fill(false))
             .setExplanation('Store full table scan')
             .build();
-        return { ...plan, ...this.buildPkOrderingAdvertisement(tableInfo, request) };
+        return { ...plan, ...this.buildPkOrderingAdvertisement(tableInfo, request, pkOrderPreservingPrefix) };
+    }
+    /**
+     * Build the access plan for one secondary index against `request`, or null when
+     * the index is not usable for this predicate.
+     *
+     * Usable = a contiguous leading-prefix EQ on the index columns (an index seek /
+     * point), or a LT/LE/GT/GE range on the LEADING index column. These mirror the
+     * two windows {@link StoreTable.analyzeIndexAccess} can build.
+     *
+     * **Collation-safety guard against under-fetch.** The store's index-column
+     * window is encoded under the table key collation K, but `matchesFilters`
+     * compares under the COLUMN's declared collation. Marking a filter handled drops
+     * the residual Filter, so the K-window must be a guaranteed SUPERSET of the
+     * qualifying rows. That holds only when K is coarser-or-equal to the column's
+     * declared collation. To stay provably safe with minimal logic we mark the
+     * covered filters handled — setting `indexName` + `seekColumns` — only when every
+     * seek column is non-text, OR its declared collation equals K, OR (K = NOCASE
+     * while the column is BINARY, i.e. K strictly coarser). Otherwise we return a
+     * cost-only plan (cheaper cost, filters unhandled, residual retained — correct,
+     * just not sped up). K itself always keys: `StoreTable`'s constructor rejects a
+     * table whose key encoding would need a collation it cannot resolve to a normalizer.
+     *
+     * NOTE: the coarser-K relaxation is sound for EQUALITY only. A RANGE window equates
+     * memcmp of K-normalized bytes with C's comparator order, which a merely coarser K does
+     * not give — under K = NOCASE and C = BINARY, 'K' (U+212A) is `> 'z'` yet keys as 'k',
+     * before 'z'. So the range arm demands `C === K` *and* K's `orderPreserving` assertion,
+     * via the shared {@link keyOrderMatchesCollation}; `StoreTable.analyzeIndexAccess`
+     * declines the same windows, so the two decisions cannot disagree. The cost is that a
+     * default-K (NOCASE) table with an index on a plain BINARY text column loses its index
+     * RANGE seek and falls back to the cost-only plan; EQ seeks are unchanged.
+     */
+    tryIndexAccessPlan(db, tableKeyCollation, tableInfo, request, index, estimatedRows) {
+        // Exclude PARTIAL indexes from access planning: neither the engine nor this
+        // module checks that the query's WHERE implies the index predicate, so seeking
+        // a partial index for a query it doesn't cover would silently drop the rows the
+        // index omits (an out-of-scope predicate returns nothing). Treat partial indexes
+        // purely as uniqueness enforcers — the query full-scans + residual instead.
+        // Mirrors MemoryTableModule.getAvailableIndexes (`if (idx.predicate) continue`).
+        if (index.predicate)
+            return null;
+        const indexColIndexes = index.columns.map(c => c.index);
+        // Contiguous leading-prefix EQ → point/prefix seek.
+        const eqCols = [];
+        for (const colIdx of indexColIndexes) {
+            if (!request.filters.some(f => f.columnIndex === colIdx && f.op === '='))
+                break;
+            eqCols.push(colIdx);
+        }
+        const leadingCol = indexColIndexes[0];
+        const hasLeadingRange = request.filters.some(f => f.columnIndex === leadingCol && RANGE_OPS.includes(f.op));
+        let seekCols;
+        let isRange;
+        if (eqCols.length > 0) {
+            seekCols = eqCols;
+            isRange = false;
+        }
+        else if (hasLeadingRange) {
+            seekCols = [leadingCol];
+            isRange = true;
+        }
+        else {
+            return null; // this index cannot serve this predicate
+        }
+        const rows = isRange
+            ? Math.max(1, Math.floor(estimatedRows * 0.3))
+            : Math.max(1, Math.floor(estimatedRows * 0.1));
+        const costOnly = (why) => (isRange ? AccessPlanBuilder.rangeScan(rows, 0.2) : AccessPlanBuilder.eqMatch(rows, 0.3))
+            .setHandledFilters(new Array(request.filters.length).fill(false))
+            .setExplanation(`Store index scan on ${index.name} (${why})`)
+            .build();
+        // The INDEX column's effective comparison collation C — the index column's own
+        // COLLATE, else the table column's declared collation. C, not the table column's
+        // declared collation, is what matchesFilters compares an index-scan row under and
+        // what the planner matched to drop the residual, so the K-window must be a superset
+        // relative to C.
+        const K = tableKeyCollation;
+        const effectiveCollation = (colIdx) => {
+            const indexCol = index.columns.find(c => c.index === colIdx);
+            return (indexCol?.collation ?? tableInfo.columns[colIdx]?.collation ?? 'BINARY').toUpperCase();
+        };
+        // EQUALITY: safe to mark handled iff K is coarser-or-equal to C. Exempt only columns
+        // that can NEVER hold text — their key bytes are type-native and collation-independent.
+        // A bare `isTextual` test wrongly exempts an `ANY` column (no marker, but it stores
+        // text as text), which would seek under K, drop the residual, and lose rows.
+        const eqSafeToHandle = (colIdx) => {
+            const col = tableInfo.columns[colIdx];
+            if (!columnCanHoldText(col))
+                return true;
+            const C = effectiveCollation(colIdx);
+            if (C === K)
+                return true; // equal
+            if (K === 'NOCASE' && C === 'BINARY')
+                return true; // K strictly coarser
+            return false;
+        };
+        // RANGE: coarser is not enough — byte order must BE comparator order. See the doc above.
+        const rangeSafeToHandle = (colIdx) => keyOrderMatchesCollation(db, tableInfo.columns[colIdx], K, effectiveCollation(colIdx));
+        if (!seekCols.every(isRange ? rangeSafeToHandle : eqSafeToHandle)) {
+            return costOnly('cost-only; key collation may under-fetch');
+        }
+        // Claim positionally — see {@link claimFirstPerRole}.
+        const handledFilters = claimFirstPerRole(request.filters, isRange ? rangeRoles(leadingCol) : equalityRoles(eqCols));
+        return (isRange ? AccessPlanBuilder.rangeScan(rows, 0.2) : AccessPlanBuilder.eqMatch(rows, 0.3))
+            .setHandledFilters(handledFilters)
+            .setIndexName(index.name)
+            .setSeekColumns(seekCols)
+            .setExplanation(`Store index ${isRange ? 'range scan' : 'seek'} on ${index.name}`)
+            .build();
     }
     /**
      * Compute the PK-ordering advertisement for a scan-style plan. Returns the
@@ -1498,10 +2304,17 @@ export class StoreModule {
      *
      * Returns an empty object when there is no PK (heap-only table) — without a
      * leading key column there is no natural emit order.
+     *
+     * Every claim here is about the PHYSICAL key-byte order the store iterates in, but the
+     * consumers of `providesOrdering` / `monotonicOn` reason in the columns' COLLATION order.
+     * `orderPreservingPrefix` (from {@link pkOrderPreservingPrefixLength}) is how many leading
+     * PK members those two orders provably agree on: the advertisement is truncated to that
+     * prefix, and voided entirely when even the leading member disagrees — otherwise the
+     * absorb-Sort rule would elide a Sort and hand the caller byte-ordered rows.
      */
-    buildPkOrderingAdvertisement(tableInfo, request) {
+    buildPkOrderingAdvertisement(tableInfo, request, orderPreservingPrefix) {
         const pk = tableInfo.primaryKeyDefinition;
-        if (pk.length === 0)
+        if (pk.length === 0 || orderPreservingPrefix === 0)
             return {};
         const leading = pk[0];
         const monotonicOn = {
@@ -1509,7 +2322,7 @@ export class StoreModule {
             direction: leading.desc ? 'desc' : 'asc',
             strict: pk.length === 1,
         };
-        const pkOrdering = pk.map(col => ({
+        const pkOrdering = pk.slice(0, orderPreservingPrefix).map(col => ({
             columnIndex: col.index,
             desc: !!col.desc,
         }));
@@ -1522,7 +2335,7 @@ export class StoreModule {
             // matched here — if the request specifies an explicit NULLS
             // FIRST/LAST, leave the Sort in place rather than assume the PK
             // scan's natural NULL placement matches.
-            if (required.length > pk.length)
+            if (required.length > pkOrdering.length)
                 return { monotonicOn, supportsAsofRight: true };
             for (let i = 0; i < required.length; i++) {
                 if (required[i].columnIndex !== pkOrdering[i].columnIndex)
@@ -1548,10 +2361,10 @@ export class StoreModule {
     /**
      * Get or create a data store for a table.
      */
-    async getStore(tableKey, _config) {
+    async getStore(schemaName, tableName, _config) {
+        const tableKey = `${schemaName}.${tableName}`.toLowerCase();
         let store = this.stores.get(tableKey);
         if (!store) {
-            const [schemaName, tableName] = tableKey.split('.');
             store = await this.provider.getStore(schemaName, tableName);
             if (!store) {
                 throw new Error(`Provider.getStore returned null/undefined for ${tableKey}`);
@@ -1631,6 +2444,10 @@ export class StoreModule {
      * the compare-write in `persistCatalogIfChanged` relies on.
      */
     buildCatalogEntry(tableSchema) {
+        // `tableSchema` is always the engine-facing schema (no `_uc_*`; the store keeps the
+        // materialized enforcement copy internal), so hidden implicit indexes reach here
+        // only through the `uniqueConstraints`-driven `isHiddenImplicitIndex` /
+        // `exposedImplicitIndexes` paths — never as a materialized `CREATE INDEX`.
         const parts = [generateTableDDL(tableSchema)];
         for (const idx of tableSchema.indexes ?? []) {
             if (isHiddenImplicitIndex(tableSchema, idx.name))
@@ -1644,14 +2461,26 @@ export class StoreModule {
         }
         return parts.join('\n');
     }
+    /**
+     * Encode a bundle of persisted schema text (DDL) for the catalog store.
+     *
+     * Guards the FULL text, not just the object's name: a lone surrogate anywhere in it — a
+     * quoted column name, a `default '…'` string literal, a `check` constraint's string
+     * constant — would otherwise fold to U+FFFD under `TextEncoder` and read back as
+     * different schema text than what was created. This does not rely on the catalog-key
+     * builders' identifier guard having already caught it; it catches it independently.
+     */
+    encodeCatalogDDL(ddl) {
+        assertNoUnpairedSurrogate(ddl, 'persisted schema text');
+        return new TextEncoder().encode(ddl);
+    }
     /**
      * Save table DDL (bundled with its secondary index DDL) to the catalog store.
      */
     async saveTableDDL(tableSchema) {
         const ddl = this.buildCatalogEntry(tableSchema);
         const catalogKey = buildCatalogKey(tableSchema.schemaName, tableSchema.name);
-        const encoder = new TextEncoder();
-        const encodedDDL = encoder.encode(ddl);
+        const encodedDDL = this.encodeCatalogDDL(ddl);
         const catalogStore = await this.provider.getCatalogStore();
         await catalogStore.put(catalogKey, encodedDDL);
     }
@@ -1934,7 +2763,7 @@ export class StoreModule {
         // data writes can land closes the power-loss window where a persisted data write
         // outlives a lost marker-delete and resurrects a consumed marker. (Backends
         // without a durability knob no-op the hint — losing it is conservative there, and
-        // memory has no crash.) See docs/materialized-views.md § Cross-module atomicity.
+        // memory has no crash.) See docs/mv-backing-host.md § Cross-module atomicity.
         await catalogStore.delete(markerKey, { sync: true }); // single-use, regardless of parse outcome
         try {
             const parsed = JSON.parse(new TextDecoder().decode(raw));
@@ -1999,7 +2828,7 @@ export class StoreModule {
         const existing = await catalogStore.get(key);
         if (existing !== undefined && new TextDecoder().decode(existing) === newDDL)
             return;
-        await catalogStore.put(key, new TextEncoder().encode(newDDL));
+        await catalogStore.put(key, this.encodeCatalogDDL(newDDL));
     }
     /**
      * Parse module configuration from vtab args.
@@ -2007,6 +2836,9 @@ export class StoreModule {
     parseConfig(args) {
         return {
             collation: args?.collation || 'NOCASE',
+            // Index-build batch budget; malformed / non-positive clamps to the default
+            // so a bad arg can never disable the bounded-memory flush (see resolveMaxBatchBytes).
+            maxBatchBytes: resolveMaxBatchBytes(args?.max_batch_bytes),
         };
     }
     // --- Engine schema-change subscription (catalog-only tag persistence) ---
@@ -2076,7 +2908,7 @@ export class StoreModule {
         // rename-restore fires one too — so recompute on each event keeps the durable set
         // current. Enqueued on `persistQueue` AFTER the dispatch above, so the `sync` lands
         // after the event's own source-DDL write is queued (the durability ordering the
-        // adopt soundness argument relies on — see `docs/materialized-views.md`).
+        // adopt soundness argument relies on — see `docs/mv-backing-host.md` § Cross-module atomicity).
         this.persistStaleMvSetIfChanged();
     };
     /** Dispatch a single engine schema-change event to its catalog-persistence arm. */
@@ -2287,7 +3119,7 @@ export class StoreModule {
         const existingDDL = new TextDecoder().decode(existing);
         if (existingDDL === newDDL)
             return; // identical — no redundant write
-        await catalogStore.put(key, new TextEncoder().encode(newDDL));
+        await catalogStore.put(key, this.encodeCatalogDDL(newDDL));
     }
     /**
      * Resolve once all catalog writes queued by async schema-change listeners
@@ -2365,6 +3197,54 @@ export class StoreModule {
         return this.tables.get(tableKey);
     }
 }
+/** Adapts a raw KV entry stream into the row stream the uniqueness validators consume. */
+async function* rowsFromEntries(entries) {
+    for await (const entry of entries) {
+        yield deserializeRow(entry.value);
+    }
+}
+/**
+ * Per-column key normalizers for a UNIQUE INDEX dedupe signature, drawing each column's
+ * collation from the index column (if it carries one) else the underlying table column —
+ * so the signature honors a per-column collation registered on this connection, matching
+ * write-time enforcement.
+ *
+ * A column whose declared type can never hold text takes the identity normalizer regardless
+ * of its collation (`serializeRowKey` normalizes only string values), so a comparator-only
+ * collation named on an integer column is not rejected here when the engine's own hash sites
+ * would accept it.
+ */
+function indexDedupeNormalizers(tableSchema, indexSchema, keyNormalizers) {
+    return indexSchema.columns.map(col => {
+        const column = tableSchema.columns[col.index];
+        return keyNormalizers(logicalTypeCanHoldText(column.logicalType)
+            ? (col.collation ?? column.collation)
+            : undefined);
+    });
+}
+/**
+ * Throws CONSTRAINT on the first pair of `rows` that share a signature over `columnIndices`.
+ *
+ * SQL NULL semantics: `serializeRowKey` returns null when any constrained column is NULL, and
+ * such rows never collide. A partial `predicate` restricts the judged set to rows it accepts
+ * unambiguously. Shared by {@link StoreModule.validateUniqueOverExistingRows} (constraint
+ * columns) and {@link StoreModule.validateUniqueIndexOverRows} (index columns).
+ */
+async function assertNoDuplicateRows(rows, tableSchema, columnIndices, normalizers, predicate) {
+    const seen = new Set();
+    for await (const row of rows) {
+        if (predicate && predicate.evaluate(row) !== true)
+            continue;
+        const keySig = serializeRowKey(row, columnIndices, normalizers);
+        if (keySig === null)
+            continue;
+        if (seen.has(keySig)) {
+            const colNames = columnIndices.map(i => tableSchema.columns[i]?.name ?? String(i)).join(', ');
+            throw new QuereusError(`UNIQUE constraint failed: ${tableSchema.name} (${colNames})`, StatusCode.CONSTRAINT);
+        }
+        seen.add(keySig);
+    }
+}
 /**
  * Reconcile each text PRIMARY KEY column's declared collation at CREATE time.
  *
@@ -2435,4 +3315,55 @@ function buildColumnRemap(oldColumnNames, newColumnNames) {
         return oldIdx !== undefined ? oldIdx : -1;
     });
 }
+/** Whether `fk` points back at the table that owns it. */
+function isSelfForeignKey(fk, schemaLower, tableLower) {
+    return (fk.referencedSchema ?? schemaLower).toLowerCase() === schemaLower
+        && fk.referencedTable.toLowerCase() === tableLower;
+}
+/**
+ * Retarget a self-referencing foreign key's `referencedTable` across a rename of
+ * the owning table. A pure copy — unlike the CHECK / partial-index rewrites this
+ * touches a name field, not a shared AST, so the caller needs no rollback.
+ * Returns the input array when nothing self-references.
+ */
+function retargetSelfForeignKeys(fks, schemaName, oldName, newName) {
+    if (!fks)
+        return fks;
+    const schemaLower = schemaName.toLowerCase();
+    const oldLower = oldName.toLowerCase();
+    let changed = false;
+    const next = fks.map(fk => {
+        if (!isSelfForeignKey(fk, schemaLower, oldLower))
+            return fk;
+        changed = true;
+        return { ...fk, referencedTable: newName };
+    });
+    return changed ? Object.freeze(next) : fks;
+}
+/**
+ * Rename a column inside a self-referencing foreign key's `referencedColumnNames`
+ * (the names the FK resolves to parent-column indices at enforcement time). Pure
+ * copy, as in {@link retargetSelfForeignKeys}. The child-side `columns` are
+ * indices, unaffected by a rename.
+ */
+function renameColumnInSelfForeignKeys(fks, schemaName, tableName, oldCol, newCol) {
+    if (!fks)
+        return fks;
+    const schemaLower = schemaName.toLowerCase();
+    const tableLower = tableName.toLowerCase();
+    const oldColLower = oldCol.toLowerCase();
+    let changed = false;
+    const next = fks.map(fk => {
+        if (!isSelfForeignKey(fk, schemaLower, tableLower))
+            return fk;
+        if (!fk.referencedColumnNames?.some(n => n.toLowerCase() === oldColLower))
+            return fk;
+        changed = true;
+        return {
+            ...fk,
+            referencedColumnNames: Object.freeze(fk.referencedColumnNames.map(n => n.toLowerCase() === oldColLower ? newCol : n)),
+        };
+    });
+    return changed ? Object.freeze(next) : fks;
+}
 //# sourceMappingURL=store-module.js.map