@quereus/store 4.3.1 → 4.4.0

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

@@ -9,12 +9,11 @@
  *   - Index stores: {schema}.{table}_idx_{name} - one per secondary index
  *   - Stats store: __stats__ - unified store for all table statistics, keyed by {schema}.{table}
  */
-import { VirtualTable, IndexConstraintOp, ConflictResolution, QuereusError, StatusCode, compareSqlValues, rowsValueIdentical, validateAndParse, compilePredicate, maintainedTableUniqueViolationError, uniqueEnforcementCollations, } from '@quereus/quereus';
+import { VirtualTable, IndexConstraintOp, ConflictResolution, QuereusError, StatusCode, compareSqlValues, compareSqlValuesFast, resolveUniqueEnforcementCollations, BINARY_COLLATION, rowsValueIdentical, validateAndParse, compilePredicate, decodeIdxStr, maintainedTableUniqueViolationError, uniqueEnforcementCollations, logicalTypeCanHoldText, pkKeyCollationName, } from '@quereus/quereus';
 import { bytesEqual, bytesToHex, compareBytes } from './bytes.js';
 import { StoreConnection } from './store-connection.js';
-import { buildDataKey, buildIndexKey, buildFullScanBounds, buildPkPrefixBounds, buildStatsKey, } from './key-builder.js';
+import { buildDataKey, buildIndexKey, buildIndexPrefixBounds, buildFullScanBounds, buildPkPrefixBounds, buildStatsKey, } from './key-builder.js';
 import { serializeRow, deserializeRow, serializeStats, deserializeStats, } from './serialization.js';
-import { getCollationEncoder } from './encoding.js';
 /** Number of mutations before persisting statistics. */
 const STATS_FLUSH_INTERVAL = 100;
 /** True when `key` falls within the (gte/gt/lte/lt) window of `bounds`. */
@@ -52,31 +51,200 @@ function resolvePkDefaultConflict(schema) {
 /**
  * Resolve the per-column KEY collation for each primary-key column.
  *
- * The store encodes PRIMARY KEY uniqueness/ordering PHYSICALLY in the key bytes,
- * so each text PK column's key must be encoded under that column's declared
- * collation (BINARY / NOCASE / RTRIM — the registered encoders). Returns one
- * entry per PK member, in `pkDef` order:
- *   - text member → its declared `collation` (normalized upper-case), or
+ * The store encodes PRIMARY KEY uniqueness/ordering PHYSICALLY in the key bytes, so each
+ * text-capable PK column's key must be encoded under the collation the engine actually
+ * COMPARES that column under. Returns one entry per PK member, in `pkDef` order:
+ *   - `isTextual` member (`text`) → its declared `collation` (normalized upper-case), or
  *     `fallback` (the table key collation K) when the column carries none.
- *   - non-text member → `undefined`: collation is meaningless for
+ *   - text-capable but not `isTextual` member — `any`, `json`, and the temporal types
+ *     (`date` / `time` / `datetime` / `timespan`) → hard-coded `'BINARY'`, see below.
+ *   - never-text member → `undefined`: collation is meaningless for
  *     integer/real/blob keys (they encode type-natively), so the encoder ignores
  *     it and the data/index key bytes are identical regardless.
  *
- * A custom comparator-only collation with no registered byte encoder still maps
- * to NOCASE bytes inside `encodeText` (its `?? NOCASE_ENCODER` fallback); that
- * residual is the same one documented for store UNIQUE enforcement and is out of
- * scope here. Shared by {@link StoreTable} (data-key + index-maintenance) and
+ * Note that `undefined` does NOT mean "encode type-natively" to `encodeValue` — it means
+ * "fall back to `options.collation`", the table key collation K. Only a never-text column
+ * may be left `undefined`, because only it never reaches the collation branch.
+ *
+ * Every name returned here is encoded through the key-normalizer resolver carried
+ * in `EncodeOptions.normalizers` (`db.getKeyNormalizerResolver()`), so a collation
+ * registered or overridden with `db.registerCollation` produces key bytes that agree
+ * with the comparator the store's UNIQUE enforcement uses. A collation that cannot
+ * key — unregistered, or registered with a comparator but no normalizer — is rejected
+ * at DDL time by {@link StoreTable.validateKeyCollations}, so no encode call ever has
+ * to fall back. Shared by {@link StoreTable} (data-key + index-maintenance) and
  * `StoreModule.buildIndexEntries` (index rebuild) so the PK suffix encoding can
  * never drift between the two.
  */
 export function resolvePkKeyCollations(pkDef, columns, fallback) {
     return pkDef.map(def => {
         const col = columns[def.index];
-        if (!col || !col.logicalType.isTextual)
-            return undefined;
-        return (col.collation || fallback).toUpperCase();
+        // Delegates the isTextual/text-capable/never-text branch to the engine's
+        // `pkKeyCollationName` — the same decision `quereus-isolation`'s modified-PK set
+        // makes for its own key normalizers, so the two can never drift apart again. Only
+        // the fallback-to-K and uppercase-normalization are store-specific.
+        const name = pkKeyCollationName(col);
+        return name === undefined ? undefined : (name || fallback).toUpperCase();
     });
 }
+/**
+ * True when `col` can produce a TEXT value at runtime, and so when its physical
+ * key bytes are produced by a collation normalizer rather than a type-native
+ * encoding. The `ColumnSchema`-shaped wrapper over the engine's
+ * {@link logicalTypeCanHoldText}; both collation-safety guards over the store's
+ * secondary indexes — the write-side {@link StoreTable.indexSeekHonorsEnforcementCollation}
+ * and the read-side `StoreModule.tryIndexAccessPlan` — exempt a never-text column
+ * from their K-vs-C comparison, so a false "non-text" answer is a silent
+ * wrong-result (a seek under the wrong collation, with the residual dropped).
+ */
+export function columnCanHoldText(col) {
+    return logicalTypeCanHoldText(col?.logicalType);
+}
+/**
+ * True when a byte window — or a byte-order advertisement — over `column` is SOUND.
+ *
+ * The store physically orders rows by memcmp of each column's key bytes, which for a
+ * text-capable column are produced by `keyCollation`'s normalizer. A range seek (and the
+ * `providesOrdering` / `monotonicOn` advertisement) equates that byte order with the order
+ * `compareCollation`'s comparator defines. Two things must hold for that equation:
+ *
+ *  - **Same collation on both sides** (`compareCollation === keyCollation`). A `keyCollation`
+ *    merely COARSER than `compareCollation` — the relaxation the EQUALITY seek is allowed to
+ *    make, see `StoreModule.tryIndexAccessPlan` — is not enough here: it would need the key
+ *    normalizer to be monotone with respect to the OTHER collation's order. It generally is
+ *    not, even for built-ins: with `keyCollation = NOCASE` and `compareCollation = BINARY`,
+ *    'K' (U+212A KELVIN SIGN) is `> 'z'` under BINARY, yet its key bytes are
+ *    `toLowerCase('K') = 'k'`, which sorts BEFORE 'z' — the row falls outside a `> 'z'`
+ *    window and is silently dropped.
+ *  - **The normalizer preserves order** (`db._isCollationOrderPreserving`). `registerCollation`
+ *    promises only that a normalizer partitions strings the way the comparator calls them
+ *    equal; a custom pair may agree on equality and disagree on order.
+ *
+ * A never-text column is exempt: its key bytes are type-native and collation-independent.
+ *
+ * Returning `false` costs an optimization (the caller full-scans and lets the
+ * collation-aware `matchesFilters` residual decide); returning `true` wrongly is a silent
+ * wrong-result. Shared by `StoreTable`'s read arms and `StoreModule`'s access planner so the
+ * "mark handled" and "build a window" decisions can never disagree.
+ */
+export function keyOrderMatchesCollation(db, column, keyCollation, compareCollation) {
+    if (!columnCanHoldText(column))
+        return true;
+    if (compareCollation.toUpperCase() !== keyCollation.toUpperCase())
+        return false;
+    return db._isCollationOrderPreserving(keyCollation);
+}
+/**
+ * How many LEADING primary-key members have key bytes whose memcmp order matches their
+ * declared collation's comparator order, per {@link keyOrderMatchesCollation}.
+ *
+ * `pkKeyCollations` is {@link resolvePkKeyCollations}' output for this table; an `undefined`
+ * entry belongs to a never-text member, which {@link keyOrderMatchesCollation} exempts
+ * outright — `tableKeyCollation` is passed only so the exempt branch has a name to ignore.
+ * The comparison collation is the column's declared one, which `reconcilePkCollations` has
+ * already aligned with the key collation for every *textual* PK member.
+ *
+ * What the advertisement is measured against is the order the planner's `Sort` would have
+ * produced, and `Sort` (like every scalar comparison) orders under the operand's COLLATION via
+ * `compareSqlValuesFast` — never through `logicalType.compare`. So a collation match is the
+ * whole question, even for a member whose type declares a `compare` that orders differently
+ * (`TIMESPAN.compare` ranks by `Temporal.Duration` total, `JSON_TYPE.compare` structurally).
+ * `MemoryTable`, whose primary-key BTree *is* keyed by `createTypedComparator`, advertises the
+ * type's order instead and so disagrees with its own `Sort` — tracked as
+ * `bug-memory-pk-btree-orders-by-logical-type-compare`, not something the store should copy.
+ *
+ * `0` ⇒ even the leading member is unsafe: no range seek, no PK-order advertisement.
+ * A prefix shorter than the PK truncates the ordering advertisement rather than voiding it.
+ */
+export function pkOrderPreservingPrefixLength(db, schema, pkKeyCollations, tableKeyCollation) {
+    const pk = schema.primaryKeyDefinition;
+    let n = 0;
+    while (n < pk.length) {
+        const col = schema.columns[pk[n].index];
+        const keyCollation = pkKeyCollations[n] ?? tableKeyCollation;
+        // NOTE: an explicit `k any collate nocase` PK declines its seek here — the key
+        // collation is BINARY (what ANY_TYPE.compare actually uses) while `col.collation` is
+        // the declared-but-ignored NOCASE, so the two sides differ and the gate closes. Both
+        // sides genuinely compare under BINARY, so the decline is conservative: it costs the
+        // seek, never a row. If that declaration ever shows up in practice, resolve the
+        // comparison collation the way `resolvePkKeyCollations` resolves the key collation
+        // rather than widening the gate.
+        if (!keyOrderMatchesCollation(db, col, keyCollation, col?.collation ?? 'BINARY'))
+            break;
+        n++;
+    }
+    return n;
+}
+/**
+ * Deterministic name of the implicit covering index materialized for a
+ * NON-DERIVED UNIQUE constraint `uc`: the constraint's own name when it has one,
+ * else the auto-name `_uc_<colNames>`. This MUST equal the engine's
+ * `catalog.ts` `implicitIndexName`, so a name that ever reaches the catalog
+ * bundle generator is recognized as hidden / exposed-implicit rather than a user
+ * index.
+ */
+export function implicitUniqueIndexName(schema, uc) {
+    return uc.name ?? `_uc_${uc.columns.map(i => schema.columns[i]?.name ?? String(i)).join('_')}`;
+}
+/**
+ * Return `schema` with a synthetic secondary index materialized into
+ * `schema.indexes` for every NON-DERIVED UNIQUE constraint that lacks one — the
+ * store analogue of `MemoryTableManager.ensureUniqueConstraintIndexes`.
+ *
+ * This is what lets a plain column- or table-level `UNIQUE` be enforced by a
+ * bounded index point-seek ({@link StoreTable.findUniqueConflictViaIndex})
+ * instead of an O(rows) full scan: DML maintenance
+ * ({@link StoreTable.updateSecondaryIndexes}) and the UNIQUE check both iterate
+ * `schema.indexes`, so once the `_uc_*` entry is present the physical index is
+ * maintained and seeked with no new code path.
+ *
+ * The result is held ONLY in {@link StoreTable.materializedSchema} (the
+ * enforcement copy), never in the engine-facing `tableSchema` the store returns
+ * from `getSchema()` / registers with the engine. So the read-query planner and
+ * the catalog bundle never see `_uc_*` (it is fully derived on open from
+ * `uniqueConstraints`); like the memory backend, a plain UNIQUE gets no read-side
+ * plan from `_uc_*`, only enforcement / maintenance.
+ *
+ * Idempotent — a name already present is left untouched — and returns a frozen
+ * schema (or the input unchanged when there is nothing to add). A
+ * `derivedFromIndex` UC is skipped (its `CREATE UNIQUE INDEX` is already in
+ * `schema.indexes`). A partial UNIQUE's synthetic index carries the SAME
+ * `uc.predicate` object reference, which
+ * {@link StoreTable.findIndexForUniqueConstraint} matches on identity.
+ */
+export function withImplicitUniqueIndexes(schema) {
+    const ucs = schema.uniqueConstraints;
+    if (!ucs || ucs.length === 0)
+        return schema;
+    const existing = schema.indexes ?? [];
+    const present = new Set(existing.map(idx => idx.name.toLowerCase()));
+    const additions = [];
+    for (const uc of ucs) {
+        if (uc.derivedFromIndex)
+            continue;
+        const name = implicitUniqueIndexName(schema, uc);
+        if (present.has(name.toLowerCase()))
+            continue;
+        present.add(name.toLowerCase());
+        additions.push({
+            name,
+            columns: uc.columns.map(idx => ({ index: idx, collation: schema.columns[idx]?.collation })),
+            // SAME reference as `uc.predicate` (undefined for a full UNIQUE) — load-bearing:
+            // findIndexForUniqueConstraint admits a partial `_uc_*` by `ix.predicate === uc.predicate`.
+            predicate: uc.predicate,
+        });
+    }
+    if (additions.length === 0)
+        return schema;
+    return Object.freeze({ ...schema, indexes: Object.freeze([...existing, ...additions]) });
+}
+/**
+ * Returned by {@link StoreTable.findUniqueConflictViaIndex} when the index
+ * cannot soundly answer the check and the caller must fall back to the full
+ * data-store scan. Distinct from `null`, which means "the index answered: no
+ * conflict".
+ */
+const INDEX_UNUSABLE = Symbol('store.uniqueIndexUnusable');
 /**
  * Generic KVStore-backed virtual table.
  *
@@ -111,6 +279,22 @@ export class StoreTable extends VirtualTable {
      * {@link updateSchema} (an ALTER COLUMN SET COLLATE on a PK member changes it).
      */
     pkKeyCollations;
+    /**
+     * `db.getCollationResolver()`, bound once at construction. Every collation-aware
+     * VALUE comparison this table makes — pushed-constraint re-check, UNIQUE conflict
+     * detection — resolves names through it, so a collation registered with
+     * `db.registerCollation` on *this* connection is honored rather than silently
+     * degraded to BINARY by the process-global built-in registry.
+     *
+     * Only the resolver closure is cached: it reads the live registry, so a collation
+     * registered after connect is still visible. Resolved *functions* are hoisted no
+     * further than the comparator or constraint check that resolved them.
+     *
+     * Its key-bytes counterpart, `db.getKeyNormalizerResolver()`, is bound into
+     * {@link encodeOptions} so the names in {@link pkKeyCollations} resolve to the same
+     * per-connection registry.
+     */
+    collationResolver;
     ddlSaved = false;
     // Statistics tracking
     cachedStats = null;
@@ -127,31 +311,126 @@ export class StoreTable extends VirtualTable {
     // object, so the WeakMap reclaims retired entries). Mirrors predicateCache but
     // for secondary-index maintenance rather than UNIQUE enforcement.
     indexPredicateCache = new WeakMap();
+    /**
+     * {@link tableSchema} with a hidden `_uc_*` secondary index materialized per
+     * non-derived UNIQUE constraint (see {@link withImplicitUniqueIndexes}) — the
+     * schema that drives UNIQUE ENFORCEMENT ({@link findIndexForUniqueConstraint})
+     * and physical index MAINTENANCE ({@link updateSecondaryIndexes}).
+     *
+     * Deliberately SEPARATE from the engine-facing {@link tableSchema}: the engine
+     * reads `tableInstance.tableSchema` at CREATE (`SchemaManager.finalizeCreatedTableSchema`)
+     * and the read-query planner reads the registered schema, and NEITHER may see
+     * `_uc_*` (mirrors the memory backend keeping its materialized schema
+     * manager-local; a plain UNIQUE gets no read-side plan from `_uc_*`, only
+     * enforcement). Recomputed alongside `tableSchema` in the constructor and
+     * {@link updateSchema}.
+     */
+    materializedSchema;
     constructor(db, storeModule, tableSchema, config, eventEmitter, isConnected = false) {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         super(db, storeModule, tableSchema.schemaName, tableSchema.name);
         this.storeModule = storeModule;
+        // The engine-facing schema stays NON-materialized (the engine registers it and the
+        // read-query planner reads it — neither may see `_uc_*`); the hidden `_uc_*`
+        // per-UNIQUE index that lets plain UNIQUE enforce via a point-seek lives only in
+        // {@link materializedSchema}.
         this.tableSchema = tableSchema;
+        this.materializedSchema = withImplicitUniqueIndexes(tableSchema);
         this.config = config;
         this.eventEmitter = eventEmitter;
-        this.encodeOptions = { collation: config.collation || 'NOCASE' };
+        this.collationResolver = db.getCollationResolver();
+        this.encodeOptions = {
+            collation: config.collation || 'NOCASE',
+            normalizers: db.getKeyNormalizerResolver(),
+        };
         this.pkDirections = tableSchema.primaryKeyDefinition.map(pk => !!pk.desc);
         this.pkKeyCollations = resolvePkKeyCollations(tableSchema.primaryKeyDefinition, tableSchema.columns, this.encodeOptions.collation ?? 'NOCASE');
+        // Validate the MATERIALIZED schema, so a `_uc_*` over a text column that needs the
+        // table key collation K is rejected up front just like an explicit index would be.
+        this.validateKeyCollations(this.materializedSchema, this.pkKeyCollations);
         this.ddlSaved = isConnected;
     }
+    /**
+     * Reject, at DDL time, any collation this table's key encoding would need but cannot
+     * use — before a single row is written under bytes the connection cannot reproduce.
+     *
+     * A collation keys a persisted structure only if it carries a KEY NORMALIZER (the
+     * `(s) => string` whose output equality partitions strings exactly as its comparator
+     * does). `db.registerCollation(name, cmp)` with no `{ normalizer }` gives a collation
+     * that can order rows but not key them; an unregistered name gives nothing at all.
+     * Both raise here rather than at the first insert.
+     *
+     * Checked over exactly the collations the key encoding actually uses:
+     *   - every defined `pkKeyCollations` entry (text-capable PK columns);
+     *   - the table key collation K, but only when it is reachable — a secondary index
+     *     encodes a TEXT-CAPABLE index column's bytes under K (`buildIndexKey`).
+     *
+     * So neither a table with an integer PK and no secondary index, nor one whose every
+     * index column is type-natively keyed, is made unopenable by a K it never encodes with.
+     *
+     * Blast radius: this also fires on catalog rehydration. Reopening a persisted database
+     * from a connection that has not re-registered its custom collation now throws at
+     * CREATE-TABLE-from-catalog rather than silently reading rows under a key layout it
+     * cannot reproduce. See `docs/plugins.md`.
+     *
+     * Takes `pkKeyCollations` rather than reading the field so `updateSchema` can validate
+     * the incoming schema BEFORE it overwrites its own state with it.
+     */
+    validateKeyCollations(schema, pkKeyCollations) {
+        const names = new Set();
+        for (const collation of pkKeyCollations) {
+            if (collation !== undefined)
+                names.add(collation);
+        }
+        const indexKeysText = (schema.indexes ?? []).some(index => index.columns.some(col => columnCanHoldText(schema.columns[col.index])));
+        if (indexKeysText) {
+            names.add((this.encodeOptions.collation ?? 'NOCASE').toUpperCase());
+        }
+        const dbInternal = this.db;
+        for (const name of names) {
+            if (dbInternal._getCollationNormalizer(name))
+                continue;
+            // Unregistered names raise `no such collation sequence: X` from the resolver;
+            // reaching past it means the collation exists but is comparator-only.
+            this.collationResolver(name);
+            throw new QuereusError(`collation ${name} cannot key a persisted structure: no key normalizer registered `
+                + `— pass { normalizer } to registerCollation`, StatusCode.ERROR);
+        }
+    }
     /** Get the table configuration. */
     getConfig() {
         return this.config;
     }
-    /** Get the table schema. */
+    /** Get the table schema (engine-facing, WITHOUT the hidden `_uc_*` indexes). */
     getSchema() {
         return this.tableSchema;
     }
-    /** Update the table schema after an ALTER TABLE operation. */
+    /**
+     * Get the enforcement schema — {@link getSchema} plus the hidden `_uc_*`
+     * index materialized per non-derived UNIQUE. Used by the module to resolve the
+     * physical index store to build/tear down during ALTER; never registered with
+     * the engine.
+     */
+    getMaterializedSchema() {
+        return this.materializedSchema;
+    }
+    /**
+     * Update the table schema after an ALTER TABLE / CREATE INDEX operation.
+     *
+     * Validates the incoming schema's key collations before adopting any of it, so a
+     * rejection leaves this table on its previous, consistent schema.
+     */
     updateSchema(newSchema) {
+        // `newSchema` is the engine-facing (non-materialized) schema; recompute the
+        // enforcement copy alongside it. Validate the MATERIALIZED copy so a `_uc_*` over a
+        // text column that needs the table key collation K is caught before adoption.
+        const materialized = withImplicitUniqueIndexes(newSchema);
+        const pkKeyCollations = resolvePkKeyCollations(newSchema.primaryKeyDefinition, newSchema.columns, this.encodeOptions.collation ?? 'NOCASE');
+        this.validateKeyCollations(materialized, pkKeyCollations);
         this.tableSchema = newSchema;
+        this.materializedSchema = materialized;
         this.pkDirections = newSchema.primaryKeyDefinition.map(pk => !!pk.desc);
-        this.pkKeyCollations = resolvePkKeyCollations(newSchema.primaryKeyDefinition, newSchema.columns, this.encodeOptions.collation ?? 'NOCASE');
+        this.pkKeyCollations = pkKeyCollations;
     }
     /**
      * Mark the table's DDL as already persisted to the catalog, so the lazy
@@ -174,34 +453,59 @@ export class StoreTable extends VirtualTable {
         catch { /* close is best-effort */ }
     }
     /**
-     * Returns true if the table has at least one stored row. Stops after the first hit.
+     * Returns true if the table has at least one LIVE row — the open transaction's
+     * pending overlay over the committed store. Stops after the first hit.
+     *
+     * Effective (not committed-only) because its one caller, `ADD COLUMN`'s NOT
+     * NULL-without-DEFAULT rejection, must see rows the same transaction inserted:
+     * they are migrated too (the arm DDL-commits before `migrateRows`), and a
+     * committed-only probe would wave them through only to give them a NULL in a
+     * NOT NULL column. Conversely, a pending delete of the last row makes the table
+     * legitimately empty. Reading effectively keeps the check throw-only and
+     * BEFORE the DDL-commit, so a rejection leaves the transaction intact.
      */
     async hasAnyRows() {
-        const store = await this.ensureStore();
-        const bounds = buildFullScanBounds();
-        for await (const _entry of store.iterate(bounds)) {
+        for await (const _entry of this.iterateEffectiveEntries(buildFullScanBounds())) {
             return true;
         }
         return false;
     }
     /**
-     * Scan every row, checking whether the column at `colIndex` ever holds NULL.
+     * Yield the LIVE value of `colIndex` for every row — the open transaction's
+     * pending overlay over the committed store. For throw-only ALTER COLUMN probes
+     * that must run BEFORE the arm's DDL-commit (see `StoreModule.ddlCommitPendingOps`):
+     * they have to see rows this transaction wrote, because those rows are rewritten
+     * too, and a rejection here must leave the transaction intact.
+     */
+    async *iterateEffectiveValuesAtIndex(colIndex) {
+        for await (const entry of this.iterateEffectiveEntries(buildFullScanBounds())) {
+            yield deserializeRow(entry.value)[colIndex];
+        }
+    }
+    /**
+     * Count the LIVE rows whose column at `colIndex` holds NULL (see
+     * {@link iterateEffectiveValuesAtIndex} for why this reads effectively).
      * Used by ALTER COLUMN SET NOT NULL to decide whether the tightening is safe.
      */
     async rowsWithNullAtIndex(colIndex) {
-        const store = await this.ensureStore();
-        const bounds = buildFullScanBounds();
         let count = 0;
-        for await (const entry of store.iterate(bounds)) {
-            const row = deserializeRow(entry.value);
-            if (row[colIndex] === null)
+        for await (const value of this.iterateEffectiveValuesAtIndex(colIndex)) {
+            if (value === null)
                 count++;
         }
         return count;
     }
     /**
      * Apply a per-row mapping function to every stored row, in place (re-writing
-     * the same key). The mapper may throw QuereusError — propagated to the caller.
+     * the same key). The mapper may throw QuereusError — propagated to the caller;
+     * the batch is written only after every row maps, so a throw leaves the store
+     * untouched.
+     *
+     * NOTE: reads and writes the COMMITTED store, outside the coordinator. Sound
+     * only because every caller calls `StoreModule.ddlCommitPendingOps` first, so
+     * "committed" is "everything live". A caller that skips that flush would leave
+     * its transaction's pending rows unmapped, and they would replay unconverted
+     * over the rewritten store at commit.
      */
     async mapRowsAtIndex(colIndex, mapper) {
         const store = await this.ensureStore();
@@ -222,10 +526,26 @@ export class StoreTable extends VirtualTable {
     /**
      * Re-key every stored row under a new primary-key definition.
      *
-     * Two-pass: the first pass reads every row and computes the new data keys,
-     * tracking duplicates. On collision we throw `CONSTRAINT` without touching
-     * the store. The second pass batches deletes of displaced old keys and puts
-     * of new (key, row) pairs. Rows whose new key matches the old key are no-ops.
+     * Two-pass, signatures-only pass 1: the first pass computes each row's new data
+     * key and retains only a `Set` of key SIGNATURES (hex of the key bytes) to detect
+     * collisions — two distinct old keys collapsing to one new key under a coarser
+     * collation or a narrower PK. On collision we throw `CONSTRAINT` without touching
+     * the store. The second pass RE-SCANS the same committed store, recomputes each
+     * new key, and batches deletes of displaced old keys + puts of new (key, row)
+     * pairs into ONE atomic batch. Rows whose new key matches the old key are no-ops.
+     *
+     * Holding signatures instead of whole rows halves peak memory: the prior design
+     * retained the entire table in a map AND again in the batch. The re-scan trades
+     * O(rows) CPU (a second iterate + newKey recompute) for not buffering the table
+     * twice. Pass 1 and pass 2 iterate the SAME bounds over the SAME committed store
+     * and see identical rows: nothing writes between them — we are single-threaded
+     * within the ALTER, outside the coordinator, and every caller ran
+     * `StoreModule.ddlCommitPendingOps` first so "committed" is "everything live".
+     *
+     * The final single `batch.write()` is the ONLY thing making the re-key
+     * all-or-nothing — do not chunk-flush it. Its residual peak (the batch still holds
+     * every changed row) is irreducible without breaking atomicity; tracked separately
+     * in `debt-store-atomic-batch-bounded-memory`.
      *
      * Only the data store is rewritten — secondary indexes are rebuilt by the
      * caller (the keys embed the PK suffix, so they must be rebuilt whenever
@@ -244,23 +564,35 @@ export class StoreTable extends VirtualTable {
     async rekeyRows(newPkDef, newColumns = this.tableSchema.columns) {
         const store = await this.ensureStore();
         const bounds = buildFullScanBounds();
-        const pending = new Map();
         const newPkDirections = newPkDef.map(pk => !!pk.desc);
         const newPkCollations = resolvePkKeyCollations(newPkDef, newColumns, this.encodeOptions.collation ?? 'NOCASE');
+        // Both passes key rows through this one helper, so a collision judged in pass 1
+        // is byte-identical to the key pass 2 writes.
+        const computeNewKey = (row) => buildDataKey(newPkDef.map(pk => row[pk.index]), this.encodeOptions, newPkDirections, newPkCollations);
+        // Pass 1 — collision detection only. Hold one hex signature per new key, never
+        // the row or old key. On a repeat, reject before any write; the store is
+        // untouched on rejection.
+        const seen = new Set();
         for await (const entry of store.iterate(bounds)) {
-            const row = deserializeRow(entry.value);
-            const newPkValues = newPkDef.map(pk => row[pk.index]);
-            const newKey = buildDataKey(newPkValues, this.encodeOptions, newPkDirections, newPkCollations);
-            const hex = bytesToHex(newKey);
-            if (pending.has(hex)) {
+            const hex = bytesToHex(computeNewKey(deserializeRow(entry.value)));
+            if (seen.has(hex)) {
                 throw new QuereusError(`UNIQUE constraint failed: duplicate primary key on rekey of '${this.schemaName}.${this.tableName}'`, StatusCode.CONSTRAINT);
             }
-            pending.set(hex, { newKey, oldKey: entry.key, row });
+            seen.add(hex);
         }
+        // Pass 2 — re-scan and build the single atomic batch. Recompute each new key and
+        // only rewrite rows whose key actually moves (`newKey !== oldKey`).
         const batch = store.batch();
-        for (const { newKey, oldKey, row } of pending.values()) {
-            if (!bytesEqual(oldKey, newKey)) {
-                batch.delete(oldKey);
+        for await (const entry of store.iterate(bounds)) {
+            const row = deserializeRow(entry.value);
+            const newKey = computeNewKey(row);
+            if (!bytesEqual(entry.key, newKey)) {
+                batch.delete(entry.key);
+                // NOTE: the row VALUE is unchanged, so `serializeRow(row)` reproduces
+                // `entry.value` byte-for-byte. We re-serialize rather than reuse
+                // `entry.value` to avoid retaining an iterator-owned buffer in the batch.
+                // If re-key CPU ever shows up hot, reuse `entry.value` where the backend
+                // guarantees the buffer is not reused across iteration.
                 batch.put(newKey, serializeRow(row));
             }
         }
@@ -320,7 +652,7 @@ export class StoreTable extends VirtualTable {
     async initializeStore() {
         const tableKey = `${this.schemaName}.${this.tableName}`.toLowerCase();
         try {
-            this.store = await this.storeModule.getStore(tableKey, this.config);
+            this.store = await this.storeModule.getStore(this.schemaName, this.tableName, this.config);
             if (!this.store) {
                 throw new Error(`getStore returned null/undefined for ${tableKey}`);
             }
@@ -471,7 +803,7 @@ export class StoreTable extends VirtualTable {
         const pkAccess = this.analyzePKAccess(filterInfo);
         if (pkAccess.type === 'point') {
             const row = await this.readLiveRowByPk(pkAccess.values);
-            if (row && this.matchesFilters(row, filterInfo)) {
+            if (row && this.matchesFilters(row, filterInfo, this.resolveFilterCollations(filterInfo))) {
                 yield row;
             }
             return;
@@ -480,11 +812,22 @@ export class StoreTable extends VirtualTable {
             yield* this.scanPKRange(store, pkAccess, filterInfo);
             return;
         }
+        // Secondary-index scan arm — reached only when the predicate did NOT resolve
+        // to a PK point/range (PK access is cheaper and already handled above). When
+        // the planner chose a secondary index (idxStr carries `idx=<name>(…)`), derive
+        // its byte window and iterate it instead of full-scanning.
+        const indexAccess = this.analyzeIndexAccess(filterInfo);
+        if (indexAccess) {
+            const indexStore = await this.ensureIndexStore(indexAccess.index.name);
+            yield* this.scanIndex(indexStore, indexAccess, filterInfo);
+            return;
+        }
         // Full table scan
+        const collations = this.resolveFilterCollations(filterInfo);
         const bounds = buildFullScanBounds();
         for await (const entry of this.iterateEffective(store, bounds)) {
             const row = deserializeRow(entry.value);
-            if (this.matchesFilters(row, filterInfo)) {
+            if (this.matchesFilters(row, filterInfo, collations)) {
                 yield row;
             }
         }
@@ -539,6 +882,15 @@ export class StoreTable extends VirtualTable {
             yield puts[putIdx++];
         }
     }
+    /**
+     * True when a byte window over the LEADING PK column reproduces the comparator's order
+     * — the precondition {@link buildPKRangeBounds} needs, and the exact condition
+     * `StoreModule.computeBestAccessPlan` uses before claiming the range filters handled.
+     * When false, the range arm degrades to a full scan + `matchesFilters` residual.
+     */
+    leadingPkRangeIsOrderSafe() {
+        return pkOrderPreservingPrefixLength(this.db, this.tableSchema, this.pkKeyCollations, this.encodeOptions.collation ?? 'NOCASE') >= 1;
+    }
     /** Analyze filter info to determine PK access pattern. */
     analyzePKAccess(filterInfo) {
         const schema = this.tableSchema;
@@ -567,7 +919,10 @@ export class StoreTable extends VirtualTable {
         const firstPkCol = pkColumns[0];
         const rangeOps = [IndexConstraintOp.LT, IndexConstraintOp.LE, IndexConstraintOp.GT, IndexConstraintOp.GE];
         const rangeConstraints = filterInfo.constraints?.filter(c => c.constraint.iColumn === firstPkCol && rangeOps.includes(c.constraint.op)) || [];
-        if (rangeConstraints.length > 0) {
+        // A range window is only sound when the leading PK column's key bytes order the way
+        // its comparator does; otherwise fall through to the full scan, where matchesFilters
+        // applies the range under the real comparator.
+        if (rangeConstraints.length > 0 && this.leadingPkRangeIsOrderSafe()) {
             return {
                 type: 'range',
                 columnIndex: firstPkCol,
@@ -607,11 +962,16 @@ export class StoreTable extends VirtualTable {
      * row filter. A NULL/missing bound value is likewise skipped (the planner never
      * pushes `= NULL`, and a range op against NULL rejects every row in matchesFilters).
      *
-     * Falls back to a full scan when the leading text PK column declares a
-     * comparator-only collation with no registered byte encoder: `encodeText` would
-     * silently key it under NOCASE bytes that do not track the column's logical
-     * order, so a derived window could UNDER-fetch. A non-text leading column has
-     * `pkKeyCollations[0] === undefined` and encodes type-natively — always safe.
+     * NOTE: a range window over a text PK column is sound only when the column's key
+     * normalizer is ORDER-preserving with respect to its comparator — i.e. the comparator
+     * orders two strings the way memcmp orders their normalized bytes. That is NOT implied
+     * by `db.registerCollation`'s normalizer contract, which promises only an equality
+     * partition, and a built-in NAME may be re-registered with a comparator + normalizer
+     * pair that preserves equality while inverting order. This method is therefore only
+     * ever reached under {@link leadingPkRangeIsOrderSafe} — enforced by
+     * {@link analyzePKAccess} here and mirrored by `StoreModule.computeBestAccessPlan`
+     * before it claims the range filters handled. A collation without the
+     * `orderPreserving` assertion costs the seek, never a row.
      */
     buildPKRangeBounds(access) {
         const full = buildFullScanBounds();
@@ -619,12 +979,6 @@ export class StoreTable extends VirtualTable {
         if (!constraints || constraints.length === 0)
             return full;
         const dir = this.pkDirections[0];
-        const coll = this.pkKeyCollations[0];
-        // A comparator-only collation (declared on the column, but with no registered
-        // byte encoder) is not seekable: its key bytes fall back to NOCASE and do not
-        // track the column's logical order. Stay full-scan; matchesFilters is authoritative.
-        if (coll !== undefined && getCollationEncoder(coll) === undefined)
-            return full;
         let gte = full.gte;
         let lt;
         for (const c of constraints) {
@@ -657,16 +1011,209 @@ export class StoreTable extends VirtualTable {
      * merge to the same `bounds`, so read-your-own-writes holds on the narrowed window.
      */
     async *scanPKRange(store, access, filterInfo) {
+        const collations = this.resolveFilterCollations(filterInfo);
         const bounds = this.buildPKRangeBounds(access);
         for await (const entry of this.iterateEffective(store, bounds)) {
             const row = deserializeRow(entry.value);
-            if (this.matchesFilters(row, filterInfo)) {
+            if (this.matchesFilters(row, filterInfo, collations)) {
+                yield row;
+            }
+        }
+    }
+    /**
+     * Resolve the secondary index chosen by the planner from `filterInfo.idxStr`.
+     *
+     * The planner emits `idx=<name>(<n>);plan=…` when its access plan set both an
+     * `indexName` and `seekColumnIndexes` (see `getBestAccessPlan` and
+     * rule-select-access-path.ts). Decoding goes through the engine's shared
+     * `decodeIdxStr`, so the store, the in-memory vtab, and the isolation overlay all
+     * read one format. Returns null for the PK/scan sentinels (`_primary_`, `fullscan`,
+     * `empty`), an idxStr that names no index, or a name absent from `schema.indexes` —
+     * every one of which routes back to a PK/full-scan arm.
+     */
+    resolveIndexFromIdxStr(idxStr) {
+        const spec = decodeIdxStr(idxStr);
+        if (!spec)
+            return null;
+        const name = spec.indexName;
+        if (!name || name === '_primary_')
+            return null;
+        const indexes = this.tableSchema?.indexes ?? [];
+        return indexes.find(i => i.name.toLowerCase() === name.toLowerCase()) ?? null;
+    }
+    /**
+     * Analyze filter info to determine a secondary-index access pattern, mirroring
+     * {@link analyzePKAccess} but over the index chosen in `idxStr`.
+     *
+     * A contiguous leading-prefix EQ on the index columns yields a `point` window
+     * (the prefix covers every entry sharing those leading values — an index seek
+     * is a PREFIX scan, not a single row, since the index need not be unique and
+     * the PK suffix varies); otherwise a range (LT/LE/GT/GE) on the LEADING index
+     * column yields a `range` window. Returns null when neither applies or when the
+     * index is unresolved. {@link matchesFilters} stays the authoritative row filter,
+     * so the window need only be a SUPERSET.
+     *
+     * Index-column bytes are encoded under the table key collation K (NOT the index's
+     * per-column declared collation — see `buildIndexKey`), while `matchesFilters` compares
+     * under the index column's effective collation C. The EQ/prefix window is a superset
+     * whenever K is coarser-or-equal to C, which `StoreModule.tryIndexAccessPlan` checked
+     * before it named this index. The RANGE window additionally needs byte order to BE
+     * comparator order, so it is gated on {@link keyOrderMatchesCollation} (which demands
+     * `C === K` plus K's `orderPreserving` assertion); when that fails we return null and
+     * the caller full-scans.
+     */
+    analyzeIndexAccess(filterInfo) {
+        const index = this.resolveIndexFromIdxStr(filterInfo.idxStr);
+        if (!index)
+            return null;
+        const indexCols = index.columns.map(c => c.index);
+        const indexDirections = index.columns.map(c => !!c.desc);
+        // Contiguous leading-prefix EQ → point/prefix window.
+        const eqValues = [];
+        for (let i = 0; i < indexCols.length; i++) {
+            const eq = filterInfo.constraints?.find(c => c.constraint.iColumn === indexCols[i]
+                && c.constraint.op === IndexConstraintOp.EQ
+                && c.argvIndex > 0);
+            if (!eq)
+                break;
+            eqValues.push(filterInfo.args[eq.argvIndex - 1]);
+        }
+        if (eqValues.length > 0) {
+            const bounds = buildIndexPrefixBounds(eqValues, this.encodeOptions, indexDirections.slice(0, eqValues.length));
+            return { index, type: 'point', bounds };
+        }
+        // Else a range on the LEADING index column.
+        const leadingCol = indexCols[0];
+        const rangeOps = [IndexConstraintOp.LT, IndexConstraintOp.LE, IndexConstraintOp.GT, IndexConstraintOp.GE];
+        const rangeConstraints = (filterInfo.constraints ?? []).filter(c => c.constraint.iColumn === leadingCol && rangeOps.includes(c.constraint.op));
+        if (rangeConstraints.length > 0 && this.indexRangeIsOrderSafe(index, leadingCol)) {
+            const bounds = this.buildIndexRangeBounds(rangeConstraints.map(c => ({
+                op: c.constraint.op,
+                value: c.argvIndex > 0 ? filterInfo.args[c.argvIndex - 1] : undefined,
+            })), indexDirections[0]);
+            return { index, type: 'range', bounds };
+        }
+        return null;
+    }
+    /**
+     * True when a byte window over `leadingCol` of `index` reproduces the comparator's
+     * order. Mirrors the range arm of `StoreModule.tryIndexAccessPlan`: the window's bytes
+     * come from the table key collation K, the residual compares under the index column's
+     * effective collation C, so both must be the same order-preserving collation.
+     */
+    indexRangeIsOrderSafe(index, leadingCol) {
+        const schema = this.tableSchema;
+        const K = this.encodeOptions.collation ?? 'NOCASE';
+        const col = schema.columns[leadingCol];
+        const indexCol = index.columns.find(c => c.index === leadingCol);
+        const C = indexCol?.collation ?? col?.collation ?? 'BINARY';
+        return keyOrderMatchesCollation(this.db, col, K, C);
+    }
+    /**
+     * Convert leading-index-column LT/LE/GT/GE constraints into one encoded-byte
+     * `gte`/`lt` window — the secondary-index analogue of {@link buildPKRangeBounds}.
+     *
+     * Each bound value is encoded under {@link encodeOptions} (the table key collation K
+     * and its normalizer resolver) and the leading index column's DESC `dir` — exactly as
+     * {@link buildIndexKey} encodes
+     * that column — via {@link buildIndexPrefixBounds}, giving the byte region
+     * `[lo, hi)` whose leading column equals that value. The op maps that region's
+     * endpoints onto `gte`/`lt`, with the same DESC lower/upper SWAP as the PK path:
+     *
+     *   | op | ASC      | DESC     |
+     *   |----|----------|----------|
+     *   | GE | gte = lo | lt  = hi |
+     *   | GT | gte = hi | lt  = lo |
+     *   | LE | lt  = hi | gte = lo |
+     *   | LT | lt  = lo | gte = hi |
+     *
+     * Across constraints keep the MAX lower and MIN upper. An `undefined` upper (an
+     * `hi` whose increment overflowed all-0xff) leaves that side unbounded — a safe
+     * SUPERSET. A NULL/missing bound value is skipped (the planner never pushes
+     * `= NULL`, and a range op against NULL rejects every row in matchesFilters).
+     */
+    buildIndexRangeBounds(constraints, dir) {
+        const full = buildFullScanBounds();
+        let gte = full.gte;
+        let lt;
+        for (const c of constraints) {
+            if (c.value === undefined || c.value === null)
+                continue;
+            const { gte: lo, lt: hi } = buildIndexPrefixBounds([c.value], this.encodeOptions, [dir]);
+            const lower = !dir
+                ? (c.op === IndexConstraintOp.GE ? lo : c.op === IndexConstraintOp.GT ? hi : undefined)
+                : (c.op === IndexConstraintOp.LE ? lo : c.op === IndexConstraintOp.LT ? hi : undefined);
+            const upper = !dir
+                ? (c.op === IndexConstraintOp.LE ? hi : c.op === IndexConstraintOp.LT ? lo : undefined)
+                : (c.op === IndexConstraintOp.GE ? hi : c.op === IndexConstraintOp.GT ? lo : undefined);
+            if (lower && compareBytes(lower, gte) > 0)
+                gte = lower;
+            if (upper && (lt === undefined || compareBytes(upper, lt) < 0))
+                lt = upper;
+        }
+        return lt === undefined ? { gte } : { gte, lt };
+    }
+    /**
+     * Scan a secondary index over `access.bounds`, resolving each index entry to its
+     * base row and re-filtering.
+     *
+     * {@link iterateEffective} yields the committed index entries merged with this
+     * transaction's pending index puts/deletes (read-your-own-writes over the
+     * index), in index-key byte order — the order the isolation overlay merge relies
+     * on (`isolated-table.ts` § buildSortKey). We resolve each entry to its row via
+     * its stored data-key value WITHOUT reordering, so index-key order is preserved.
+     *
+     * Defense in depth mirroring the memory layer's live-recheck: a resolved-null
+     * row (the entry's row was deleted — a pending index delete would normally
+     * suppress the entry, but a committed entry can lag) is skipped, and every
+     * resolved row is re-checked by {@link matchesFilters} (the byte window is only
+     * a superset, and a stale entry whose indexed column no longer matches is
+     * dropped).
+     */
+    async *scanIndex(indexStore, access, filterInfo) {
+        // Re-check each resolved row under the INDEX's per-column collation (see
+        // matchesFilters): the planner dropped the residual based on the index
+        // column's collation, which an explicit index `COLLATE` can make differ from
+        // the table column's declared collation.
+        const indexCollations = this.resolveFilterCollations(filterInfo, this.indexColumnCollations(access.index));
+        for await (const entry of this.iterateEffective(indexStore, access.bounds)) {
+            // NOTE: a legacy index store (written before index values carried the data
+            // key) holds EMPTY values; a zero-length data key is not a row key, so skip
+            // it rather than resolve it to the wrong row. Because the access plan marked
+            // the filter handled and dropped the residual, an indexed query over such a
+            // store returns NOTHING rather than the matching rows — a silent wrong
+            // result, not an error. Backwards compatibility is waived project-wide
+            // (AGENTS.md) and no test provider carries on-disk data, so nothing exercises
+            // this today. If real persisted stores predating this format come into play,
+            // their indexes must be dropped + recreated (or the table rebuilt); the
+            // durable fix is to version-stamp the index store and rebuild on open, or to
+            // fall back to a full scan the first time an empty value is seen.
+            if (entry.value.length === 0)
+                continue;
+            // NOTE: one extra data-store `get` per matched index entry — the row lives
+            // in the data store, not the index (the index value carries only the data
+            // key, no covering payload). Fine now; if index-covered scans ever dominate
+            // a profile, consider storing the serialized row as a covering index value,
+            // at the cost of an index rewrite on EVERY column change (not just indexed
+            // columns) — deliberately not done here.
+            const row = await this.readEffectiveRowByKey(entry.value);
+            if (row && this.matchesFilters(row, filterInfo, indexCollations)) {
                 yield row;
             }
         }
     }
-    /** Check if a row matches the filter constraints. */
-    matchesFilters(row, filterInfo) {
+    /**
+     * Check if a row matches the filter constraints.
+     *
+     * `collations` maps a constrained column index to the comparison function that
+     * column must be re-checked under; every caller builds it once per scan with
+     * {@link resolveFilterCollations}, whose doc comment explains how the name is
+     * chosen. A column absent from the map compares BINARY — the same result
+     * {@link resolveFilterCollations} produces for an undeclared collation, and the
+     * only reachable absence, since both walk the constraint list under identical
+     * skip conditions.
+     */
+    matchesFilters(row, filterInfo, collations) {
         if (!filterInfo.constraints || filterInfo.constraints.length === 0) {
             return true;
         }
@@ -677,13 +1224,7 @@ export class StoreTable extends VirtualTable {
             }
             const rowValue = row[constraint.iColumn];
             const filterValue = filterInfo.args[argvIndex - 1];
-            // Compare under the column's DECLARED collation (undefined ⇒ BINARY) — the
-            // same resolution the access path's collation-cover analysis uses
-            // (indexColumnCollationLookup / primaryKeyCollationLookup) when it decides
-            // a pushed constraint is fully covered, and the same source this file's
-            // UNIQUE checks compare under. On a collation MATCH the planner drops the
-            // residual Filter, so this filter alone must reproduce the predicate.
-            const collation = this.tableSchema.columns[constraint.iColumn]?.collation;
+            const collation = collations.get(constraint.iColumn) ?? BINARY_COLLATION;
             if (!this.compareValues(rowValue, constraint.op, filterValue, collation)) {
                 return false;
             }
@@ -691,19 +1232,75 @@ export class StoreTable extends VirtualTable {
         return true;
     }
     /**
-     * Compare two values according to an operator, under `collation` (the column's
-     * declared collation; undefined ⇒ BINARY). Delegates to the engine's
-     * `compareSqlValues`, so the LT/LE/GT/GE range bounds honour a NOCASE/RTRIM
-     * column collation rather than a raw BINARY JS comparison — the capability
+     * Resolve, ONCE per scan, the comparison collation function for every pushed
+     * constraint column, keyed by column index.
+     *
+     * The name for a column is its DECLARED collation (absent ⇒ BINARY) — the same
+     * resolution the access path's collation-cover analysis uses
+     * (indexColumnCollationLookup / primaryKeyCollationLookup) when it decides a
+     * pushed constraint is fully covered, and the same source this file's UNIQUE
+     * checks compare under. On a collation MATCH the planner drops the residual
+     * Filter, so {@link matchesFilters} alone must reproduce the predicate.
+     *
+     * `indexCollationNames` (from {@link indexColumnCollations}) overrides the
+     * declared name for the secondary-index scan arm: the planner's MATCH there is
+     * against the INDEX column's collation, which an explicit `COLLATE` on the index
+     * can make differ from the table column's.
+     *
+     * Names resolve against {@link collationResolver}, so an unregistered collation
+     * raises `no such collation sequence` at scan setup rather than byte-ordering
+     * every row.
+     *
+     * NOTE: rebuilt on every `query()` / `scanPKRange()` / `scanIndex()` call — one
+     * registry lookup per distinct constrained column, dwarfed by the scan's I/O. If a
+     * point-lookup-heavy profile ever shows it, memoize on the `FilterInfo`.
+     */
+    resolveFilterCollations(filterInfo, indexCollationNames) {
+        const resolved = new Map();
+        if (!filterInfo.constraints)
+            return resolved;
+        for (const { constraint, argvIndex } of filterInfo.constraints) {
+            if (constraint.iColumn < 0 || argvIndex <= 0)
+                continue;
+            if (resolved.has(constraint.iColumn))
+                continue;
+            const name = indexCollationNames?.has(constraint.iColumn)
+                ? indexCollationNames.get(constraint.iColumn)
+                : this.tableSchema.columns[constraint.iColumn]?.collation;
+            resolved.set(constraint.iColumn, name ? this.collationResolver(name) : BINARY_COLLATION);
+        }
+        return resolved;
+    }
+    /**
+     * Effective per-column comparison collation for a secondary index's columns:
+     * the index column's own `COLLATE` when present, else the underlying table
+     * column's declared collation. Mirrors the resolution `StoreModule`'s
+     * index-maintenance UNIQUE dedup uses (`indexCol.collation ?? tableColumn`), so
+     * a re-checked index-scan row compares under the same collation the planner used
+     * to justify dropping (or keeping) the residual Filter.
+     */
+    indexColumnCollations(index) {
+        const cols = this.tableSchema.columns;
+        const map = new Map();
+        for (const c of index.columns) {
+            map.set(c.index, c.collation ?? cols[c.index]?.collation);
+        }
+        return map;
+    }
+    /**
+     * Compare two values according to an operator, under `collationFunc` (already
+     * resolved by {@link resolveFilterCollations} against this database's collation
+     * registry). So the LT/LE/GT/GE range bounds honour a NOCASE/RTRIM/custom column
+     * collation rather than a raw BINARY JS comparison — the capability
      * `StoreModule.getBestAccessPlan` advertises via `honorsCollatedRangeBounds`.
      * NULL on either side fails every operator except EQ-with-both-NULL (the
      * internal point-lookup convention; the planner never pushes `= NULL`).
      */
-    compareValues(a, op, b, collation) {
+    compareValues(a, op, b, collationFunc) {
         if (a === null || b === null) {
             return op === IndexConstraintOp.EQ ? a === b : false;
         }
-        const cmp = compareSqlValues(a, b, collation);
+        const cmp = compareSqlValuesFast(a, b, collationFunc);
         switch (op) {
             case IndexConstraintOp.EQ: return cmp === 0;
             case IndexConstraintOp.NE: return cmp !== 0;
@@ -1010,8 +1607,9 @@ export class StoreTable extends VirtualTable {
      * sides leaks the old entry. Other paths pass the same pk for both.
      */
     async updateSecondaryIndexes(inTransaction, oldRow, newRow, oldPk, newPk = oldPk) {
-        const schema = this.tableSchema;
-        const indexes = schema.indexes || [];
+        // Maintain the MATERIALIZED index set: the hidden `_uc_*` per-UNIQUE index must be
+        // kept in step with DML so the enforcement seek finds every live row.
+        const indexes = this.materializedSchema.indexes || [];
         for (const index of indexes) {
             const indexStore = await this.ensureIndexStore(index.name);
             const indexCols = index.columns.map(c => c.index);
@@ -1038,13 +1636,20 @@ export class StoreTable extends VirtualTable {
             if (newRow && (!predicate || predicate.evaluate(newRow) === true)) {
                 const newIndexValues = indexCols.map(i => newRow[i]);
                 const newIndexKey = buildIndexKey(newIndexValues, newPk, this.encodeOptions, indexDirections, this.pkDirections, this.pkKeyCollations);
-                // Index value is empty - we just need the key for lookups
-                const emptyValue = new Uint8Array(0);
+                // Index value = the row's encoded DATA key. The index-entry key can
+                // locate a row's byte window, but its PK suffix is not losslessly
+                // recoverable to SqlValues (a NOCASE/RTRIM PK column encodes lossily)
+                // and its length varies per entry in a range scan — so a scan resolves
+                // each entry back to its base row via this stored data key
+                // (`scanIndex` → `readEffectiveRowByKey(entry.value)`), never by
+                // decoding the suffix. `newPk` is the PK the entry is keyed under, so
+                // its data key byte-matches the data store's key for this row.
+                const dataKeyValue = this.encodeDataKey(newPk);
                 if (inTransaction && this.coordinator) {
-                    this.coordinator.put(newIndexKey, emptyValue, indexStore);
+                    this.coordinator.put(newIndexKey, dataKeyValue, indexStore);
                 }
                 else {
-                    await indexStore.put(newIndexKey, emptyValue);
+                    await indexStore.put(newIndexKey, dataKeyValue);
                 }
             }
         }
@@ -1059,7 +1664,7 @@ export class StoreTable extends VirtualTable {
             return undefined;
         let compiled = this.predicateCache.get(uc);
         if (!compiled) {
-            compiled = compilePredicate(uc.predicate, this.tableSchema.columns);
+            compiled = compilePredicate(uc.predicate, this.tableSchema.columns, this.tableSchema.name);
             this.predicateCache.set(uc, compiled);
         }
         return compiled;
@@ -1074,7 +1679,7 @@ export class StoreTable extends VirtualTable {
             return undefined;
         let compiled = this.indexPredicateCache.get(index);
         if (!compiled) {
-            compiled = compilePredicate(index.predicate, this.tableSchema.columns);
+            compiled = compilePredicate(index.predicate, this.tableSchema.columns, this.tableSchema.name);
             this.indexPredicateCache.set(index, compiled);
         }
         return compiled;
@@ -1146,15 +1751,7 @@ export class StoreTable extends VirtualTable {
             const predicate = this.compileFor(uc);
             if (predicate && predicate.evaluate(newRow) !== true)
                 continue;
-            // Prefer a linked row-time covering MV: its backing table (hosted by any
-            // backing-host-capable module — memory by default, this store module under
-            // `using store` — queried through the db with reads-own-writes) answers
-            // the uniqueness question, mirroring the memory enforcement path. Falls
-            // back to the per-scan source search when no row-time covering MV exists.
-            const coveringMv = this.db._findRowTimeCoveringStructure(schema.schemaName, schema.name, uc);
-            const conflict = coveringMv
-                ? await this.findUniqueConflictViaCoveringMv(coveringMv, uc, predicate, newRow, selfPks)
-                : await this.findUniqueConflict(uc, predicate, newRow, selfPks);
+            const conflict = await this.findUniqueConflictFor(uc, predicate, newRow, selfPks);
             if (!conflict)
                 continue;
             // Resolve action per-constraint: statement OR > per-UC default > ABORT.
@@ -1183,6 +1780,178 @@ export class StoreTable extends VirtualTable {
         }
         return null;
     }
+    /**
+     * Route one UNIQUE constraint's conflict search to the cheapest SOUND finder,
+     * in descending preference:
+     *
+     *  1. A linked row-time covering MV — its backing table (hosted by any
+     *     backing-host-capable module — memory by default, this store module under
+     *     `using store` — queried through the db with reads-own-writes) answers the
+     *     uniqueness question, mirroring the memory enforcement path.
+     *  2. A physical secondary index realizing the constraint — one prefix seek
+     *     instead of a full table scan (see {@link findIndexForUniqueConstraint}).
+     *  3. The full data-store scan ({@link findUniqueConflict}) — always correct,
+     *     O(rows) per checked row.
+     *
+     * Every finder returns the SAME `{pk, row}` shape, so the caller's conflict
+     * action (ABORT / IGNORE / REPLACE eviction) is finder-independent.
+     */
+    async findUniqueConflictFor(uc, predicate, newRow, selfPks) {
+        const schema = this.tableSchema;
+        const coveringMv = this.db._findRowTimeCoveringStructure(schema.schemaName, schema.name, uc);
+        if (coveringMv)
+            return this.findUniqueConflictViaCoveringMv(coveringMv, uc, predicate, newRow, selfPks);
+        const index = this.findIndexForUniqueConstraint(uc);
+        if (index) {
+            const viaIndex = await this.findUniqueConflictViaIndex(index, uc, predicate, newRow, selfPks);
+            if (viaIndex !== INDEX_UNUSABLE)
+                return viaIndex;
+        }
+        return this.findUniqueConflict(uc, predicate, newRow, selfPks);
+    }
+    /**
+     * The `schema.indexes` entry whose physical index store can serve `uc`'s
+     * conflict search as a point seek, or undefined when none can.
+     *
+     * Every non-derived UNIQUE now carries a materialized implicit index
+     * (`_uc_*`, see {@link withImplicitUniqueIndexes}), so — like the memory
+     * backend — a plain column- or table-level `UNIQUE` is index-servable, not
+     * only an explicit `CREATE INDEX`. A UC is index-servable when:
+     *
+     *  - it is index-derived (`derivedFromIndex`, from `CREATE UNIQUE INDEX`) and
+     *    its named index is still present — the index's partial predicate then
+     *    equals the constraint's by construction (`appendIndexToTableSchema`); or
+     *  - some index's columns equal `uc.columns` positionally AND whose predicate
+     *    is the SAME object as `uc.predicate` (reference identity — the implicit
+     *    materializer sets it that way). For a FULL UNIQUE that is
+     *    `undefined === undefined`, which also admits any user full index over the
+     *    same columns. For a PARTIAL `unique(...) where p` it admits only the
+     *    co-scoped `_uc_*` (which holds exactly the in-scope rows); an arbitrary
+     *    user partial index with a DIFFERENT predicate object stays conservative
+     *    (declined → full scan), because it physically omits rows the constraint
+     *    still covers. The serving index need not be UNIQUE — a plain index over
+     *    the constrained columns still holds every in-scope row.
+     *
+     * Collation guard (see {@link indexSeekHonorsEnforcementCollation}) may still
+     * reject the found index, which routes the check back to the full scan.
+     */
+    findIndexForUniqueConstraint(uc) {
+        // NOTE: re-resolved for every constrained ROW written, and the collation guard
+        // below re-derives `uniqueEnforcementCollations` each time. Both are linear in
+        // `schema.indexes` / `uc.columns` and dwarfed by the seek's I/O, so this is fine
+        // now. If a table with many indexes ever shows up on an insert-heavy profile,
+        // memoize the (uc → index | undefined) resolution in a WeakMap keyed on the
+        // frozen UniqueConstraintSchema, as `predicateCache` above does — a CREATE/DROP
+        // INDEX yields fresh constraint objects, so such a cache invalidates itself.
+        // Reads the MATERIALIZED index set so the hidden `_uc_*` realizing a plain UNIQUE
+        // is visible (the engine-facing `tableSchema` carries only explicit/derived indexes).
+        const indexes = this.materializedSchema.indexes;
+        if (!indexes || indexes.length === 0)
+            return undefined;
+        const index = uc.derivedFromIndex
+            ? indexes.find(ix => ix.name === uc.derivedFromIndex)
+            : indexes.find(ix => ix.predicate === uc.predicate
+                && ix.columns.length === uc.columns.length
+                && ix.columns.every((c, i) => c.index === uc.columns[i]));
+        if (!index)
+            return undefined;
+        return this.indexSeekHonorsEnforcementCollation(uc) ? index : undefined;
+    }
+    /**
+     * True when a point seek into the index realizing `uc` returns a SUPERSET of
+     * the constraint's true conflict set — the only condition under which the
+     * seek may replace the full scan.
+     *
+     * An index key's leading (index-column) bytes are encoded under the TABLE KEY
+     * collation K (`buildIndexKey` passes `this.encodeOptions`), NOT the index's
+     * declared per-column COLLATE and NOT the constraint's enforcement collation
+     * C (`uniqueEnforcementCollations` — the index's per-column COLLATE for an
+     * index-derived UC, else the declared column collation). A seek therefore
+     * fetches exactly `{rows K-equal to newRow}` while the re-validation keeps
+     * `{rows C-equal to newRow}`. Soundness needs
+     * `{C-equal} ⊆ {K-equal}`, i.e. K must be COARSER-OR-EQUAL to C per column:
+     *
+     *  - non-text column → its bytes are type-native, collation-independent: safe.
+     *  - C == K → the sets coincide: safe.
+     *  - K = NOCASE, C = BINARY → K strictly coarser: safe superset.
+     *  - otherwise (K = BINARY over C = NOCASE/RTRIM; K = NOCASE over C = RTRIM)
+     *    the seek UNDER-fetches and a real duplicate would be silently accepted:
+     *    reject, so the caller full-scans.
+     *
+     * Same direction and same admitted cases as the read-side guard in
+     * `StoreModule.tryIndexAccessPlan`; conservative rather than exhaustive
+     * (K = RTRIM over C = BINARY is provably safe but declined), which costs an
+     * optimization, never correctness. The coarseness test is only sound for the
+     * built-in names: a custom K equals a custom C only when the index column names
+     * that same collation, and otherwise falls through to the full scan.
+     */
+    indexSeekHonorsEnforcementCollation(uc) {
+        const schema = this.tableSchema;
+        const K = (this.encodeOptions.collation ?? 'NOCASE').toUpperCase();
+        const collations = uniqueEnforcementCollations(schema, uc);
+        return uc.columns.every((colIdx, i) => {
+            if (!columnCanHoldText(schema.columns[colIdx]))
+                return true;
+            const C = (collations[i] ?? 'BINARY').toUpperCase();
+            return C === K || (K === 'NOCASE' && C === 'BINARY');
+        });
+    }
+    /**
+     * The index analogue of {@link findUniqueConflict}: seek the index realizing
+     * `uc` at the point formed by `newRow`'s constrained-column values, and
+     * re-validate each resolved candidate exactly as the full scan does.
+     *
+     * The seek encodes ALL of `uc.columns` (positionally aligned with the index's
+     * columns, guaranteed by `appendIndexToTableSchema` / the column-set match in
+     * {@link findIndexForUniqueConstraint}) as a leading prefix of the index key,
+     * under the same key collation and per-column DESC directions
+     * {@link updateSecondaryIndexes} used to write it. The remaining suffix is the
+     * row's PK, so the window spans every entry sharing those column values.
+     * {@link iterateEffective} merges this transaction's pending index puts/deletes
+     * over the committed entries, giving read-your-own-writes; each entry resolves
+     * to its LIVE row through the data key stored as the entry's value.
+     *
+     * The seek only narrows the CANDIDATE set to a superset (guaranteed by
+     * {@link indexSeekHonorsEnforcementCollation}); the authoritative comparison is
+     * the identical self-PK exclusion, per-column enforcement-collation compare,
+     * and partial-predicate scope check the full scan performs. A partial index
+     * already excludes out-of-scope rows physically — the predicate re-check is
+     * kept as defense in depth.
+     *
+     * Returns {@link INDEX_UNUSABLE} rather than a (possibly wrong) answer when an
+     * entry carries a legacy empty value.
+     */
+    async findUniqueConflictViaIndex(index, uc, predicate, newRow, selfPks) {
+        const indexStore = await this.ensureIndexStore(index.name);
+        // Resolved once, above the candidate loop: the resolver throws on an
+        // unregistered name and cannot be inlined, so a per-candidate call would be
+        // pure overhead.
+        const collations = resolveUniqueEnforcementCollations(this.tableSchema, uc, this.collationResolver);
+        const bounds = buildIndexPrefixBounds(uc.columns.map(c => newRow[c]), this.encodeOptions, index.columns.map(c => !!c.desc));
+        for await (const entry of this.iterateEffective(indexStore, bounds)) {
+            // A legacy index store (written before index values carried the data key)
+            // holds EMPTY values. `scanIndex` may skip such an entry — a read that
+            // returns too few rows. Skipping here would instead ACCEPT a duplicate, so
+            // abandon the index and let the caller full-scan. See the NOTE in
+            // `scanIndex` for the durable fix.
+            if (entry.value.length === 0)
+                return INDEX_UNUSABLE;
+            // Resolve to the LIVE row: a pending index delete normally suppresses the
+            // entry, but a committed entry can lag a row deleted this transaction.
+            const candidate = await this.readEffectiveRowByKey(entry.value);
+            if (!candidate)
+                continue;
+            const pk = this.extractPK(candidate);
+            if (selfPks.some(skip => this.keysEqual(pk, skip)))
+                continue;
+            if (uc.columns.some((c, i) => compareSqlValuesFast(newRow[c], candidate[c], collations[i]) !== 0))
+                continue;
+            if (predicate && predicate.evaluate(candidate) !== true)
+                continue;
+            return { pk, row: candidate };
+        }
+        return null;
+    }
     /**
      * Scan committed + pending data rows for a row matching `newRow` on
      * `uc.columns` whose PK is not in `selfPks`. For partial UNIQUE, candidates
@@ -1200,7 +1969,8 @@ export class StoreTable extends VirtualTable {
         const constrainedCols = uc.columns;
         // One comparison collation per constrained column — the index's per-column
         // COLLATE for an index-derived UNIQUE, else the declared column collation.
-        const collations = uniqueEnforcementCollations(this.tableSchema, uc);
+        // Resolved once here, not per candidate row.
+        const collations = resolveUniqueEnforcementCollations(this.tableSchema, uc, this.collationResolver);
         const matches = (candidate) => {
             const pk = this.extractPK(candidate);
             for (const skip of selfPks) {
@@ -1209,7 +1979,7 @@ export class StoreTable extends VirtualTable {
             }
             for (let i = 0; i < constrainedCols.length; i++) {
                 const idx = constrainedCols[i];
-                if (compareSqlValues(newRow[idx], candidate[idx], collations[i]) !== 0)
+                if (compareSqlValuesFast(newRow[idx], candidate[idx], collations[i]) !== 0)
                     return null;
             }
             // Partial UNIQUE: candidate must also be in the predicate's scope to conflict.
@@ -1252,7 +2022,8 @@ export class StoreTable extends VirtualTable {
      */
     async findUniqueConflictViaCoveringMv(mv, uc, predicate, newRow, selfPks) {
         const newSourcePk = this.extractPK(newRow);
-        const collations = uniqueEnforcementCollations(this.tableSchema, uc);
+        // Resolved once, above the candidate loop.
+        const collations = resolveUniqueEnforcementCollations(this.tableSchema, uc, this.collationResolver);
         const candidates = await this.db._lookupCoveringConflicts(mv, uc, newRow, newSourcePk);
         for (const cand of candidates) {
             const liveRow = await this.readLiveRowByPk(cand.pk);
@@ -1270,7 +2041,7 @@ export class StoreTable extends VirtualTable {
             // index over a BINARY column) is declined upstream by the collation gate in
             // findRowTimeCoveringStructure, so only BINARY-floor or equal-collation MVs
             // reach here — the superset this re-validation can soundly filter.
-            if (uc.columns.some((c, i) => compareSqlValues(newRow[c], liveRow[c], collations[i]) !== 0))
+            if (uc.columns.some((c, i) => compareSqlValuesFast(newRow[c], liveRow[c], collations[i]) !== 0))
                 continue;
             if (predicate && predicate.evaluate(liveRow) !== true)
                 continue;
@@ -1344,7 +2115,7 @@ export class StoreTable extends VirtualTable {
      * Declared secondary-UNIQUE enforcement for maintenance writes — the store
      * mirror of the memory manager's `enforceSecondaryUniqueOnMaintenance` (see
      * `vtab/backing-host.ts` § Constraint validation for the contract and
-     * docs/materialized-views.md § Derived-row constraint validation for the
+     * docs/mv-constraints.md § Derived-row constraint validation for the
      * semantics). Called by `StoreBackingHost.applyMaintenance` AFTER the op
      * batch lands in the coordinator's pending state: post-batch is load-bearing
      * (a `replace-all` diff applies puts before deletes, so a per-op check would
@@ -1359,8 +2130,10 @@ export class StoreTable extends VirtualTable {
      * and would miss a same-batch colliding pair. The conflict action is a hard
      * abort (a derivation write carries no user OR clause, and a declared
      * `on conflict replace`/`ignore` default must not evict or drop derived
-     * rows). Per-image cost is one effective scan — the same full-scan posture
-     * the store's DML UNIQUE enforcement already takes.
+     * rows). Per-image cost is one effective full scan: unlike the DML path
+     * ({@link findUniqueConflictFor}), this one is NOT routed through
+     * {@link findUniqueConflictViaIndex}, because a backing table keeps no
+     * secondary indexes by design — there is never an index store to seek.
      *
      * Zero overhead when the table declares no secondary UNIQUE (every MV-sugar
      * backing, and most maintained tables): one empty-array check.