@quereus/isolation 4.3.1 → 4.3.2

package/dist/src/isolated-table.js

@@ -1,6 +1,9 @@
-import { VirtualTable, compareSqlValues, isUpdateOk, isConstraintViolation, IndexConstraintOp, ConflictResolution, compilePredicate, QuereusError, StatusCode, uniqueEnforcementCollations } from '@quereus/quereus';
+import { VirtualTable, compareSqlValues, compareSqlValuesFast, resolveCollationFunctions, BINARY_COLLATION, isUpdateOk, ConflictResolution, compilePredicate, QuereusError, StatusCode, resolveUniqueEnforcementCollations, uniqueEnforcementCollations, normalizeCollationName, serializeRowKey, pkKeyCollationName, retargetFilterInfoIndex, PRIMARY_INDEX_NAME, validateAndParse, IndexConstraintOp, decodeIdxStr } from '@quereus/quereus';
 import { IsolatedConnection } from './isolated-connection.js';
 import { mergeStreams, createMergeEntry, createTombstone } from './merge-iterator.js';
+import { makeFullScanFilterInfo, makePkPointLookupFilter, makeSecondaryIndexEqSeekFilter } from './filter-info.js';
+/** Returned when the schema has not been populated yet; never mutated. */
+const EMPTY_PK_KEY_SHAPE = { functions: [], directions: [] };
 /**
  * A table wrapper that provides transaction isolation via an overlay.
  *
@@ -28,22 +31,68 @@ export class IsolatedTable extends VirtualTable {
      * lets the GC reclaim entries for retired constraints.
      */
     predicateCache = new WeakMap();
+    /**
+     * `db.getCollationResolver()`, bound once at connect. Both the overlay/underlying
+     * merge comparators and the UNIQUE conflict checks resolve collation names through
+     * it, so a collation registered with `db.registerCollation` participates instead of
+     * silently degrading to BINARY.
+     *
+     * The overlay's key comparator and the underlying table's must agree, or a staged
+     * row fails to shadow the base row it replaces; both now derive from this one
+     * database registry.
+     */
+    collationResolver;
+    /**
+     * `db.getKeyNormalizerResolver()`, bound once at connect beside {@link collationResolver}
+     * for the same reason: the modified-PK set's key encoding and the comparators above must
+     * agree on which rows are equal, or a staged row fails to shadow the base row it replaces.
+     */
+    keyNormalizerResolver;
+    /**
+     * Per-PK-column comparison functions and sort directions, resolved from the PK
+     * columns' declared collations and memoized against the `TableSchema` object
+     * identity — an `alter table` hands this instance a fresh (frozen) schema object,
+     * which invalidates the entry.
+     */
+    pkCollationCache;
     /**
      * Returns the connection-scoped set of savepoint depths that pre-date the overlay.
      * Stored in IsolationModule (keyed by db+schema+table) so all IsolatedTable instances
      * for the same connection see the same set — important because each statement creates
      * a fresh IsolatedTable instance via module.connect(), so instance-local state would
      * be lost between the createSavepoint callback and the ensureOverlay() call.
+     *
+     * NOTE: keyed by the name this IsolatedTable was *constructed* with, which after a
+     * mid-transaction `alter table … rename to …` is the pre-rename name. Deliberate:
+     * this same instance stays the registered connection's callback object for the rest
+     * of the transaction and clears the set at commit/rollback, so the key must not move
+     * out from under it. A statement after the rename connects a fresh IsolatedTable under
+     * the new name, which builds its own set from `Database.registerConnection`'s savepoint
+     * replay. See `IsolationModule.renameTable`.
      */
     get savepointsBeforeOverlay() {
         return this.isolationModule.getPreOverlaySavepoints(this.db, this.schemaName, this.tableName);
     }
-    constructor(db, module, underlyingTable, readCommitted = false) {
+    /**
+     * @param schemaName Schema name as supplied to `IsolationModule.create()`/`.connect()` — the
+     *   same identity `IsolationModule.underlyingTables` is keyed by.
+     * @param tableName Bare table name from the same source. These MUST NOT be read off
+     *   `underlyingTable.schemaName` / `.tableName`: `VirtualTable.tableName` is contracted bare,
+     *   but an underlying module that reports a schema-qualified name there (lamina-quereus does,
+     *   using the field as a catalogue key) would key this table's overlay as
+     *   `<dbId>:store.store.widget` while `underlyingTables` holds `store.widget`. The commit
+     *   flush looks the overlay's key up in `underlyingTables`, misses, and silently discards
+     *   every staged row. Keying off the connect-time pair keeps both maps on one identity by
+     *   construction, whatever the underlying self-reports.
+     */
+    constructor(db, module, schemaName, tableName, underlyingTable, readCommitted = false) {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        super(db, module, underlyingTable.schemaName, underlyingTable.tableName);
+        super(db, module, schemaName, tableName);
         this.isolationModule = module;
         this.underlyingTable = underlyingTable;
         this.readCommitted = readCommitted;
+        this.collationResolver = db.getCollationResolver();
+        this.keyNormalizerResolver = db.getKeyNormalizerResolver();
         // Schema comes from underlying - may be populated lazily by the underlying module
         this.tableSchema = underlyingTable.tableSchema;
     }
@@ -60,13 +109,14 @@ export class IsolatedTable extends VirtualTable {
         return this.isolationModule.getConnectionOverlay(this.db, this.schemaName, this.tableName);
     }
     /**
-     * Throws if this connection's overlay was poisoned by a cross-connection ALTER
-     * (see `IsolationModule.alterTable`). A poisoned overlay still holds rows in the
-     * PRE-alter column layout, so it can neither be merged into a read nor flushed to
-     * the now-altered underlying. Called at the data-op chokepoints (write, the merged
-     * read branch, and the commit flush) — never on the committed-snapshot read path,
-     * which bypasses the overlay entirely and stays safe. The connection recovers by
-     * rolling back, which discards the overlay (and its poison).
+     * Throws if this connection's overlay was poisoned by a cross-connection DDL: an ALTER
+     * that could not migrate it (see `IsolationModule.alterTable`), leaving its rows in the
+     * PRE-alter column layout, or a DROP TABLE that removed the table underneath it (see
+     * `IsolationModule.destroy`). Either way it can neither be merged into a read nor
+     * flushed. Called at the data-op chokepoints (write, the merged read branch, and the
+     * commit flush) — never on the committed-snapshot read path, which bypasses the overlay
+     * entirely and stays safe. The connection recovers by rolling back, which discards the
+     * overlay (and its poison).
      */
     assertOverlayUsable() {
         const state = this.getOverlayState();
@@ -136,10 +186,12 @@ export class IsolatedTable extends VirtualTable {
             const preAlignedConn = await overlayTable.createConnection();
             await this.db.registerConnection(preAlignedConn);
         }
-        // Store in connection-scoped storage
+        // Store in connection-scoped storage. `db` rides along so the module can free this
+        // overlay's staging table on any discard path (see IsolationModule.releaseOverlayTable).
         const state = {
             overlayTable,
             hasChanges: false,
+            db: this.db,
         };
         this.isolationModule.setConnectionOverlay(this.db, this.schemaName, this.tableName, state);
         return overlayTable;
@@ -188,6 +240,13 @@ export class IsolatedTable extends VirtualTable {
     async buildConnection() {
         // Reuse an existing covering (IsolatedConnection) if one is already registered
         // for this table — avoids accumulating one IsolatedConnection per statement.
+        //
+        // NOTE: a rename leaves the covering connection registered under the OLD name
+        // (StoreModule.renameTable evicts only its own StoreConnections), so a table later
+        // created under that freed name adopts that stale connection here. Sound today only
+        // because the overlay and underlying maps are keyed by table name rather than by
+        // connection, so each table still resolves its own state. If per-connection state
+        // ever moves onto IsolatedConnection, retarget the connection across the rename.
         const qualifiedName = `${this.schemaName}.${this.tableName}`;
         const existing = this.db.getConnectionsForTable(qualifiedName);
         const existingCovering = existing.find((c) => c.isCovering);
@@ -250,8 +309,8 @@ export class IsolatedTable extends VirtualTable {
         if (this.readCommitted || !this.overlayTable || !this.hasChanges) {
             return this.underlyingTable.query(filterInfo);
         }
-        // Merged branch: a poisoned overlay cannot be merged (its rows are in the
-        // pre-alter layout) — error before touching it.
+        // Merged branch: a poisoned overlay cannot be merged (pre-alter row layout, or the
+        // table itself is gone) — error before touching it.
         this.assertOverlayUsable();
         // Merge overlay with underlying (with connection ensured)
         return this.mergedQueryWithConnection(filterInfo);
@@ -279,7 +338,7 @@ export class IsolatedTable extends VirtualTable {
             yield* this.underlyingTable.query(filterInfo);
             return;
         }
-        const indexInfo = this.parseIndexFromFilterInfo(filterInfo);
+        const indexInfo = this.resolveScanIndex(filterInfo);
         if (indexInfo.type === 'secondary') {
             yield* this.mergedSecondaryIndexQuery(overlay, filterInfo, indexInfo);
             return;
@@ -296,10 +355,19 @@ export class IsolatedTable extends VirtualTable {
      *
      * Instead of position-based merging (which fails when overlay entries have
      * different index key values than the underlying rows they shadow), this:
-     * 1. Collects all PKs modified in the overlay (full scan)
-     * 2. Queries underlying via secondary index, excluding modified PKs
-     * 3. Queries overlay via secondary index for non-tombstone data rows
-     * 4. Merges the two disjoint, sorted streams by sort key
+     * 1. Full-scans the overlay ONCE, collecting all modified PKs and the non-tombstone
+     *    data rows that fall inside the query's constraint window
+     * 2. Sorts the collected overlay rows by the scan's (indexKey, PK) sort key
+     * 3. Queries underlying via secondary index, excluding modified PKs, and merges the
+     *    sorted overlay rows in by sort key
+     *
+     * The overlay is deliberately never asked to resolve the query's index name. The
+     * underlying module may drive this scan under an index it minted itself (lamina
+     * mints `_column_<id>_`, `_compound_<name>_`, `_nd_<name>_`, `_intersect_<ids>_`
+     * per plan) — a name no table schema, and therefore no overlay, declares — so
+     * re-issuing the index-named FilterInfo against the overlay would throw
+     * "Secondary index not found". The isolation layer filters and sorts the overlay
+     * delta itself instead.
      */
     async *mergedSecondaryIndexQuery(overlay, filterInfo, indexInfo) {
         if (!overlay.query) {
@@ -308,29 +376,65 @@ export class IsolatedTable extends VirtualTable {
         }
         const pkIndices = this.getPrimaryKeyIndices();
         const tombstoneIndex = this.getTombstoneColumnIndex(overlay);
-        // Step 1: Collect all PKs modified in overlay (full scan)
+        // Key the modified-PK set with the engine's canonical, bigint-safe,
+        // collation-aware encoder — NOT JSON.stringify, which throws on a bigint PK
+        // value and ignores collation (a NOCASE PK rewritten 'abc' -> 'ABC' would fail
+        // to shadow the underlying 'abc', surfacing both rows). One normalizer per PK
+        // column, drawn from `pkKeyCollationName` (the same decision `resolvePkKeyCollations`
+        // makes for the store's on-disk PK encoding) via the connection's own resolver, so
+        // equal keys under the PK collation encode to identical strings — matching
+        // getComparePK/keysEqual and agreeing with `db.registerCollation`.
+        //
+        // A PK column whose declared type can never hold text takes the identity
+        // normalizer regardless of its collation: `serializeRowKey` normalizes only
+        // string values, so the collation cannot affect how such a key buckets. Asking
+        // the resolver for it would reject `n integer collate mycoll` under a
+        // comparator-only collation, which the engine's own hash sites accept (they gate
+        // through `hashKeyCollationName`, the same predicate). A text-capable-but-not-
+        // `isTextual` column (`any`, `json`, the temporal types) is keyed under `'BINARY'`
+        // regardless of its declared collation, since PK equality compares those types
+        // through `logicalType.compare`, which ignores collation entirely.
+        const pkNormalizers = pkIndices.map(i => {
+            const column = this.tableSchema.columns[i];
+            return this.keyNormalizerResolver(pkKeyCollationName(column));
+        });
+        // Step 1: one full overlay scan collects the modified PKs AND the in-window
+        // non-tombstone data rows. The window filter is applied here, unconditionally —
+        // whether the engine adds a residual Filter above the isolation scan depends on
+        // the underlying's handledFilters, which the isolation layer does not control.
+        // NOTE: full-scans the overlay on every merged secondary read. Fine while an
+        // overlay holds a single transaction's writes (small); if isolation-write volume
+        // ever makes overlays large and this shows up hot, retarget to an overlay index
+        // with the same key columns when one exists, keeping this full scan as the
+        // fallback for underlying-minted index names no overlay index matches.
+        const matchesWindow = this.buildConstraintMatcher(filterInfo);
         const modifiedPKs = new Set();
-        for await (const row of overlay.query(this.createFullScanFilterInfo())) {
-            const pk = pkIndices.map(i => row[i]);
-            modifiedPKs.add(JSON.stringify(pk));
-        }
-        // Step 2: Query overlay via secondary index for non-tombstone data rows
-        const overlayFilterInfo = this.adaptFilterInfoForOverlay(filterInfo);
         const overlayRows = [];
-        for await (const row of overlay.query(overlayFilterInfo)) {
+        for await (const row of overlay.query(this.createFullScanFilterInfo())) {
+            // `!` is safe: PK columns are NOT NULL, so serializeRowKey never returns
+            // null here; both sides use the same encoder so they stay consistent.
+            modifiedPKs.add(serializeRowKey(row, pkIndices, pkNormalizers));
             if (row[tombstoneIndex] !== 1) {
-                overlayRows.push(row.slice(0, tombstoneIndex));
+                const dataRow = row.slice(0, tombstoneIndex);
+                if (matchesWindow(dataRow)) {
+                    overlayRows.push(dataRow);
+                }
             }
         }
-        // Step 3: Query underlying via secondary index, filter out modified PKs
+        // Step 2: sort the collected overlay rows by the merge's sort key. The full scan
+        // emits in PK order, and the step-3 merge walks overlayRows expecting
+        // (indexKey, PK) order — sorting here decouples merge correctness from whatever
+        // order the overlay happens to emit.
         const mergeConfig = this.buildMergeConfig(indexInfo);
         const compareSortKey = mergeConfig.compareSortKey ?? mergeConfig.comparePK;
         const extractSortKey = mergeConfig.extractSortKey ?? mergeConfig.extractPK;
+        overlayRows.sort((a, b) => compareSortKey(extractSortKey(a), extractSortKey(b)));
+        // Step 3: query underlying via secondary index, filter out modified PKs
         // Merge two sorted, disjoint streams
         let oi = 0;
         for await (const underlyingRow of this.underlyingTable.query(filterInfo)) {
-            const pk = pkIndices.map(i => underlyingRow[i]);
-            if (modifiedPKs.has(JSON.stringify(pk))) {
+            // `!` is safe for the same reason as the build loop above (PK NOT NULL).
+            if (modifiedPKs.has(serializeRowKey(underlyingRow, pkIndices, pkNormalizers))) {
                 continue; // Skip rows modified in overlay
             }
             // Yield any overlay rows that sort before this underlying row
@@ -352,57 +456,224 @@ export class IsolatedTable extends VirtualTable {
         }
     }
     /**
-     * Parses FilterInfo to determine which index is being used.
-     * Returns null for full table scan or primary key scan, index name for secondary indexes.
+     * Determine the order the underlying scan emits, from the planner's typed access path.
+     *
+     * A `fullScan` (or a provably-empty plan) merges by primary key: every underlying module
+     * the isolation layer wraps emits an unbounded scan in primary-key order. That is a
+     * contract on the underlying, not an inference from any string — see
+     * docs/design-isolation-layer.md.
+     *
+     * `role` is authoritative over `name`: a descriptor with `role: 'primary'` IS the table's
+     * primary key however the module named it (an alias like `_primary_1`), so it merges by PK.
+     * An `unresolvedIndex` — a name the engine could not resolve to any index, with no
+     * module-supplied descriptor — cannot yield a comparator, so we fail loudly rather than
+     * silently merge by the wrong sort key.
      */
-    parseIndexFromFilterInfo(filterInfo) {
-        const { idxStr } = filterInfo;
-        if (!idxStr) {
-            return { type: 'primary' };
+    resolveScanIndex(filterInfo) {
+        const path = filterInfo.accessPath;
+        if (!path) {
+            throw new QuereusError(`IsolatedTable '${this.tableName}': FilterInfo carries no accessPath, so the ` +
+                `underlying scan's sort order is unknown and the overlay cannot be merged. ` +
+                `Build FilterInfo with the engine's makeFullScanFilterInfo/makeIndexEqSeekFilterInfo helpers.`, StatusCode.INTERNAL);
         }
-        // Parse idxStr format: "idx=indexName(n);plan=2;..."
-        const params = new Map();
-        idxStr.split(';').forEach(part => {
-            const [key, value] = part.split('=', 2);
-            if (key && value !== undefined)
-                params.set(key, value);
-        });
-        const idxMatch = params.get('idx')?.match(/^(.*?)\((\d+)\)$/);
-        if (!idxMatch) {
-            return { type: 'primary' };
+        switch (path.kind) {
+            case 'fullScan':
+            case 'empty':
+                return { type: 'primary' };
+            case 'index':
+                return path.index.role === 'primary'
+                    ? { type: 'primary' }
+                    : {
+                        type: 'secondary',
+                        indexName: path.index.name,
+                        columnIndices: path.index.keyColumns.map(c => c.columnIndex),
+                        keyColumns: path.index.keyColumns,
+                        // A reversed scan (ORDER BY … DESC) emits the underlying stream in
+                        // reverse of the descriptor's declared key order; the merge must walk
+                        // its sort key reversed to interleave overlay rows correctly.
+                        reverse: path.index.reverse === true,
+                    };
+            case 'unresolvedIndex':
+                throw new QuereusError(`IsolatedTable '${this.tableName}': the underlying module chose index ` +
+                    `'${path.indexName}', which the engine could not resolve against the table schema. ` +
+                    `A module that names an index anything other than '_primary_' or a schema index ` +
+                    `must return an 'indexDescriptor' from getBestAccessPlan (see docs/module-authoring.md).`, StatusCode.INTERNAL);
+            default: {
+                // A new AccessPath kind must extend this switch; never-assignment makes that a
+                // compile error rather than a silent `undefined` return that would crash at the
+                // `indexInfo.type` read in mergedQuery (noImplicitReturns is off in this package).
+                const _exhaustive = path;
+                throw new QuereusError(`IsolatedTable '${this.tableName}': unhandled accessPath kind '${path.kind}'`, StatusCode.INTERNAL);
+            }
+        }
+    }
+    /**
+     * Adapts FilterInfo for the overlay table schema (which has an extra tombstone column).
+     * The constraints and index references remain the same since the overlay has matching indexes.
+     *
+     * The one mismatch is the index NAME. The underlying may drive its PK plan under a per-plan
+     * alias (e.g. `_primary_1`) that the overlay MemoryTable does not know — the overlay always
+     * names its PK index `_primary_`. When the access path is the primary key under such an
+     * alias, retarget the FilterInfo's index name to `_primary_` so the overlay re-plans it as a
+     * primary-key scan instead of failing to resolve a non-existent secondary index of that name.
+     * A genuine secondary scan (or the bare `_primary_`) is returned unchanged.
+     */
+    adaptFilterInfoForOverlay(filterInfo) {
+        const path = filterInfo.accessPath;
+        if (path?.kind === 'index' && path.index.role === 'primary' && path.index.name !== PRIMARY_INDEX_NAME) {
+            return retargetFilterInfoIndex(filterInfo, PRIMARY_INDEX_NAME);
         }
-        const indexName = idxMatch[1];
-        if (indexName === '_primary_') {
-            return { type: 'primary' };
+        return filterInfo;
+    }
+    /**
+     * Builds the window predicate for the overlay side of a merged secondary-index read.
+     *
+     * The overlay is full-scanned there (it cannot resolve an underlying-minted index
+     * name), so every staged row surfaces — including rows outside the query's window.
+     * This predicate re-applies the pushed constraints that the underlying's index seek
+     * enforces on its own stream.
+     *
+     * Interpretation follows the plan kind:
+     * - `scan` pushes no window — everything matches.
+     * - `eqSeek` / `rangeSeek` / `prefixRangeSeek` / `multiSeek` carry one genuine
+     *   (column, op, value) triple per constraint entry. Per-column EQ values form an
+     *   IN set — the planner encodes an IN multi-seek as one EQ constraint per seek
+     *   value on the same column, and a composite IN as its full per-column
+     *   cross-product — so EQ matches when the row equals ANY of the column's values,
+     *   while range bounds all AND together.
+     * - `multiRangeSeek` constraint entries are positional placeholders (every arg is
+     *   stamped GE); the real OR-of-ranges lives in the idxStr `rangeOps` parameters,
+     *   decoded by {@link buildMultiRangeWindowMatcher}.
+     *
+     * Comparisons run under the index key column's collation (falling back to the table
+     * column's, then BINARY) with seek semantics for NULL: a NULL operand or a NULL row
+     * value never matches, mirroring what an index seek returns. Operators the matcher
+     * does not interpret (LIKE, MATCH, ...) are ignored — that can only let through
+     * rows a residual Filter above still removes, never drop rows.
+     */
+    buildConstraintMatcher(filterInfo) {
+        const path = filterInfo.accessPath;
+        // Only 'index' paths reach the merged secondary read (resolveScanIndex gates on
+        // the access path first); an ordering-only walk pushes no window.
+        if (path?.kind !== 'index' || path.plan === 'scan') {
+            return () => true;
         }
-        // Secondary index scan
-        return {
-            type: 'secondary',
-            indexName,
-            columnIndices: this.getIndexColumnIndices(indexName),
+        if (path.plan === 'multiRangeSeek') {
+            return this.buildMultiRangeWindowMatcher(filterInfo, path.index);
+        }
+        const windows = new Map();
+        const windowFor = (columnIndex) => {
+            let window = windows.get(columnIndex);
+            if (!window) {
+                window = { collation: this.constraintCollation(columnIndex, path.index), eqValues: [], ranges: [] };
+                windows.set(columnIndex, window);
+            }
+            return window;
+        };
+        for (const { constraint, argvIndex } of filterInfo.constraints) {
+            if (argvIndex <= 0)
+                continue;
+            const value = filterInfo.args[argvIndex - 1];
+            switch (constraint.op) {
+                case IndexConstraintOp.EQ:
+                    windowFor(constraint.iColumn).eqValues.push(value);
+                    break;
+                case IndexConstraintOp.GT:
+                case IndexConstraintOp.GE:
+                case IndexConstraintOp.LT:
+                case IndexConstraintOp.LE:
+                    windowFor(constraint.iColumn).ranges.push({ op: constraint.op, value });
+                    break;
+                default:
+                    break; // uninterpreted op — see doc comment
+            }
+        }
+        if (windows.size === 0)
+            return () => true;
+        const entries = [...windows.entries()];
+        return (row) => {
+            for (const [columnIndex, window] of entries) {
+                const rowValue = row[columnIndex];
+                if (rowValue === null)
+                    return false;
+                if (window.eqValues.length > 0
+                    && !window.eqValues.some(v => v !== null && compareSqlValuesFast(rowValue, v, window.collation) === 0)) {
+                    return false;
+                }
+                for (const { op, value } of window.ranges) {
+                    if (value === null || !satisfiesBound(compareSqlValuesFast(rowValue, value, window.collation), op)) {
+                        return false;
+                    }
+                }
+            }
+            return true;
         };
     }
     /**
-     * Gets the column indices for a secondary index.
+     * Window matcher for a `multiRangeSeek` — an OR of ranges over the index's leading
+     * key column. The FilterInfo's constraint entries are positional placeholders for
+     * this plan kind, so the ranges are decoded from the idxStr `rangeCount`/`rangeOps`
+     * parameters exactly as the memory module's scan-plan builder does.
      */
-    getIndexColumnIndices(indexName) {
-        const schema = this.tableSchema;
-        if (!schema?.indexes)
-            return [];
-        const index = schema.indexes.find(idx => idx.name.toLowerCase() === indexName.toLowerCase());
-        if (!index)
-            return [];
-        return index.columns.map(col => col.index);
+    buildMultiRangeWindowMatcher(filterInfo, index) {
+        const keyColumn = index.keyColumns[0];
+        const spec = decodeIdxStr(filterInfo.idxStr);
+        if (!keyColumn || !spec)
+            return () => true;
+        const rangeCount = parseInt(spec.params.get('rangeCount') ?? '0', 10);
+        const rangeOpsList = (spec.params.get('rangeOps') ?? '').split(',');
+        const { args } = filterInfo;
+        const ranges = [];
+        let argIdx = 0;
+        for (let i = 0; i < rangeCount; i++) {
+            const range = {};
+            for (const op of (rangeOpsList[i] ?? '').split(':')) {
+                if (op === 'gt' || op === 'ge') {
+                    range.lower = { strict: op === 'gt', value: args[argIdx++] };
+                }
+                else if (op === 'lt' || op === 'le') {
+                    range.upper = { strict: op === 'lt', value: args[argIdx++] };
+                }
+            }
+            ranges.push(range);
+        }
+        if (ranges.length === 0)
+            return () => true;
+        const columnIndex = keyColumn.columnIndex;
+        const collation = this.constraintCollation(columnIndex, index);
+        return (row) => {
+            const rowValue = row[columnIndex];
+            if (rowValue === null)
+                return false;
+            return ranges.some(({ lower, upper }) => {
+                if (lower) {
+                    if (lower.value === null)
+                        return false;
+                    const cmp = compareSqlValuesFast(rowValue, lower.value, collation);
+                    if (lower.strict ? cmp <= 0 : cmp < 0)
+                        return false;
+                }
+                if (upper) {
+                    if (upper.value === null)
+                        return false;
+                    const cmp = compareSqlValuesFast(rowValue, upper.value, collation);
+                    if (upper.strict ? cmp >= 0 : cmp > 0)
+                        return false;
+                }
+                return true;
+            });
+        };
     }
     /**
-     * Adapts FilterInfo for the overlay table schema (which has an extra tombstone column).
-     * The constraints and index references remain the same since the overlay has matching indexes.
+     * Comparison collation for a window-matcher column: the index key column's declared
+     * collation when the column is part of the scanned index (the seek's own window
+     * follows the index collation), else the table column's declared collation, else
+     * BINARY.
      */
-    adaptFilterInfoForOverlay(filterInfo) {
-        // The overlay table has the same schema plus a tombstone column at the end.
-        // Column indices for data columns are the same, so FilterInfo constraints work as-is.
-        // The overlay module will interpret the constraints correctly.
-        return filterInfo;
+    constraintCollation(columnIndex, index) {
+        const name = index.keyColumns.find(kc => kc.columnIndex === columnIndex)?.collation
+            ?? this.tableSchema?.columns[columnIndex]?.collation;
+        return name ? this.collationResolver(name) : BINARY_COLLATION;
     }
     /**
      * Queries the overlay table and converts rows to MergeEntry format.
@@ -474,9 +745,22 @@ export class IsolatedTable extends VirtualTable {
             const pk = pkIndices.map(i => row[i]);
             return [...indexKey, ...pk];
         };
-        // Try to use the underlying table's per-column index comparators if available
-        const indexComparators = this.underlyingTable.getIndexComparator?.(indexInfo.indexName);
-        const compareSortKey = this.buildCompareSortKey(indexColIndices.length, comparePK, indexComparators);
+        // Prefer the underlying table's per-column index comparators; when it exposes
+        // none for this index (always the case for a module-minted synthetic name),
+        // derive them from the descriptor's key columns so a DESC or collated key
+        // column still merges in the underlying's emission order rather than a
+        // BINARY-ascending guess.
+        const indexComparators = this.underlyingTable.getIndexComparator?.(indexInfo.indexName)
+            ?? this.buildDescriptorComparators(indexInfo.keyColumns);
+        const forwardCompareSortKey = this.buildCompareSortKey(indexColIndices.length, comparePK, indexComparators);
+        // A reversed scan emits the whole (indexKey, PK) sort key in reverse — including
+        // the PK tie-break within an equal index-key group — so negate the entire
+        // comparator. That makes the step-2 overlay sort descend and the step-3 merge's
+        // `compareSortKey(oKey, uKey) <= 0` walk yield overlay rows while they sort at or
+        // before the underlying row under the reversed order.
+        const compareSortKey = indexInfo.reverse
+            ? (a, b) => -forwardCompareSortKey(a, b)
+            : forwardCompareSortKey;
         return {
             extractPK,
             comparePK,
@@ -484,6 +768,49 @@ export class IsolatedTable extends VirtualTable {
             compareSortKey,
         };
     }
+    /**
+     * Per-PK-column comparison functions for this table's current schema, resolved
+     * against THIS database's collation registry (so `db.registerCollation` names
+     * participate) rather than the process-global built-in trio.
+     *
+     * A PK column with no declared `COLLATE` resolves to BINARY; a PK definition
+     * shorter than the key being compared (or absent entirely) yields BINARY for the
+     * trailing positions, matching the prior `collation === undefined` behaviour.
+     *
+     * Memoized on the schema object so comparator construction — and the per-call
+     * {@link keysEqual} — never re-resolves per row. Resolution is not retroactive: a
+     * collation registered *after* a comparator was built is not picked up, the same
+     * contract `Database.registerCollation` documents engine-wide.
+     *
+     * NOTE: this is the *comparison* collation only. The store's physical key bytes come
+     * from a separate encoder registry that does not consult the database — see
+     * `fix/bug-store-key-encoder-ignores-database-collations`.
+     */
+    getPkCollations() {
+        return this.getPkKeyShape().functions;
+    }
+    /**
+     * Per-PK-column sort directions (`true` ⇒ DESC), positionally aligned with
+     * {@link getPkCollations}. Only the ordering comparator needs them; `keysEqual`
+     * asks about equality, which direction cannot change.
+     */
+    getPkDirections() {
+        return this.getPkKeyShape().directions;
+    }
+    getPkKeyShape() {
+        const schema = this.tableSchema;
+        if (!schema)
+            return EMPTY_PK_KEY_SHAPE;
+        if (this.pkCollationCache?.schema !== schema) {
+            const pkDef = schema.primaryKeyDefinition ?? [];
+            this.pkCollationCache = {
+                schema,
+                functions: resolveCollationFunctions(this.collationResolver, pkDef.map(pk => schema.columns[pk.index]?.collation)),
+                directions: pkDef.map(pk => !!pk.desc),
+            };
+        }
+        return this.pkCollationCache;
+    }
     /**
      * Gets the primary key comparator, preferring the underlying table's comparator.
      */
@@ -493,22 +820,40 @@ export class IsolatedTable extends VirtualTable {
             return this.underlyingTable.comparePrimaryKey.bind(this.underlyingTable);
         }
         // Fallback to default comparator. Compare under each PK column's declared
-        // collation (e.g. NOCASE), not BINARY: the merge aligns overlay and underlying
-        // entries by this comparator to decide shadowing, and the underlying store keys
-        // rows collation-aware. A binary comparator would treat a case-only-updated
-        // overlay row ('APPLE') and the underlying row it shadows ('apple') as distinct
-        // keys, surfacing BOTH in a scan instead of the overlay shadowing the underlying.
-        const pkDef = this.tableSchema?.primaryKeyDefinition;
+        // collation (e.g. NOCASE), not BINARY, and in its declared direction: the merge
+        // aligns overlay and underlying entries by this comparator to decide shadowing,
+        // and the underlying store keys rows both collation-aware and DESC-aware. A
+        // binary comparator would treat a case-only-updated overlay row ('APPLE') and
+        // the underlying row it shadows ('apple') as distinct keys; an ascending one
+        // walks a `primary key (k desc)` table against its scan order. Either way both
+        // rows surface in a scan instead of the overlay shadowing the underlying.
+        const collations = this.getPkCollations();
+        const directions = this.getPkDirections();
         return (a, b) => {
             for (let i = 0; i < a.length; i++) {
-                const collation = pkDef ? this.tableSchema.columns[pkDef[i].index].collation : undefined;
-                const cmp = compareSqlValues(a[i], b[i], collation);
+                const cmp = compareSqlValuesFast(a[i], b[i], collations[i] ?? BINARY_COLLATION);
                 if (cmp !== 0)
-                    return cmp;
+                    return directions[i] ? -cmp : cmp;
             }
             return 0;
         };
     }
+    /**
+     * Per-column comparators derived from an index descriptor's key columns — the
+     * fallback when the underlying exposes no `getIndexComparator` for the index
+     * (always the case for a module-minted synthetic name). Honors each key column's
+     * declared direction and collation so the merge walks the underlying's emission
+     * order.
+     */
+    buildDescriptorComparators(keyColumns) {
+        return keyColumns.map(kc => {
+            const collation = kc.collation ? this.collationResolver(kc.collation) : BINARY_COLLATION;
+            return (a, b) => {
+                const cmp = compareSqlValuesFast(a, b, collation);
+                return kc.desc ? -cmp : cmp;
+            };
+        });
+    }
     /**
      * Builds a sort key comparator for secondary index scans.
      *
@@ -554,6 +899,21 @@ export class IsolatedTable extends VirtualTable {
             return [];
         return schema.primaryKeyDefinition.map(pkDef => pkDef.index);
     }
+    /**
+     * Coerce each cell to its declared column logical type before PK extraction and
+     * conflict detection — the same step StoreTable.coerceRow / MemoryTableManager.performInsert
+     * run. Without it, an ON CONFLICT insert whose proposed key is a different storage class than
+     * the stored key (TEXT '1' into an INTEGER key holding 1) probes the underlying with the
+     * un-coerced key, misses the committed row, and stages the proposed row instead of updating
+     * the existing one (bug-store-isolation-upsert-affinity-coerced-pk).
+     */
+    coerceRow(row) {
+        const cols = this.tableSchema.columns;
+        if (row.length > cols.length) {
+            throw new QuereusError(`Too many values for ${this.schemaName}.${this.tableName}: expected ${cols.length}, got ${row.length}`, StatusCode.ERROR);
+        }
+        return row.map((v, i) => validateAndParse(v, cols[i].logicalType, cols[i].name));
+    }
     // ==================== Write Operations ====================
     /**
      * Performs INSERT, UPDATE, or DELETE on the overlay.
@@ -562,8 +922,8 @@ export class IsolatedTable extends VirtualTable {
      * The overlay is created lazily on first write, using schema from the underlying table.
      */
     async update(args) {
-        // A poisoned overlay (cross-connection ALTER) cannot accept further writes — its
-        // staged rows are in the pre-alter layout. Error before staging anything.
+        // A poisoned overlay (cross-connection ALTER or DROP TABLE) cannot accept further
+        // writes — it can never be flushed. Error before staging anything.
         this.assertOverlayUsable();
         // Ensure connection is registered for transaction coordination
         await this.ensureConnection();
@@ -573,6 +933,21 @@ export class IsolatedTable extends VirtualTable {
         this.setHasChanges(true);
         const { operation, values, oldKeyValues } = args;
         const tombstoneIndex = this.getTombstoneColumnIndex(overlay);
+        // Coerced only for PK extraction / merged-view conflict detection below — NOT
+        // for the overlay write. The overlay (a memory-module table) always re-coerces
+        // every cell on its own insert/update unconditionally, so writing the coerced
+        // row through would coerce twice. That is a no-op for most logical types, but
+        // JSON's `parse` is not idempotent for a JSON-string scalar (`'"hello"'` parses
+        // to the native JS string `"hello"`; re-parsing that bare string as JSON throws,
+        // since it lacks its own quotes) — double coercion would break any JSON column.
+        // Detection instead needs the coerced form: probing the overlay/underlying by an
+        // un-coerced PK (e.g. TEXT '1' against a stored INTEGER 1) misses the existing
+        // row entirely (bug-store-isolation-upsert-affinity-coerced-pk).
+        // NOTE: this coerces the full row on every isolation-layer write, and the overlay
+        // coerces it again on its own insert/update — two validateAndParse passes per write
+        // (two JSON.parse for JSON columns). Negligible now; if isolation-write throughput or
+        // large-JSON rows ever show as hot, thread the coerced row through as pre-coerced.
+        const coercedValues = values ? this.coerceRow(values) : values;
         // Resolve the effective PK-level action once so the wrapped overlay vtab
         // agrees with the overlay's decision. Per-UC defaults are applied inside
         // checkMergedUniqueConstraints, since each UC may declare its own action.
@@ -583,7 +958,7 @@ export class IsolatedTable extends VirtualTable {
         switch (operation) {
             case 'insert': {
                 const pkIndices = this.getPrimaryKeyIndices();
-                const pk = values ? pkIndices.map(i => values[i]) : undefined;
+                const pk = coercedValues ? pkIndices.map(i => coercedValues[i]) : undefined;
                 // Secondary-UNIQUE REPLACE evictions surfaced via `evictedRows`.
                 const evicted = [];
                 // Captured when OR REPLACE displaces a row that lives only in the
@@ -593,7 +968,15 @@ export class IsolatedTable extends VirtualTable {
                 if (pk) {
                     const existingRow = await this.getOverlayRow(overlay, pk);
                     if (existingRow && existingRow[tombstoneIndex] === 1) {
-                        // Convert tombstone to regular row (delete then re-insert same PK)
+                        // Convert tombstone to regular row (delete then re-insert same PK).
+                        // Run the same merged non-PK UNIQUE check the normal insert path runs
+                        // (~below) before writing — otherwise a revived row that collides on a
+                        // secondary UNIQUE is flushed with trustedWrite (store skips its re-check),
+                        // yielding an opaque INTERNAL error at commit or silent corruption.
+                        // selfPks = [pk] excludes this row's own PK from conflict detection.
+                        const ucResult = await this.checkMergedUniqueConstraints(overlay, coercedValues, [pk], tombstoneIndex, args.onConflict, evicted);
+                        if (ucResult !== null)
+                            return ucResult;
                         const overlayRow = [...(values ?? []), 0];
                         const result = await overlay.update({
                             operation: 'update',
@@ -601,7 +984,8 @@ export class IsolatedTable extends VirtualTable {
                             oldKeyValues: pk,
                             onConflict: effectiveOR,
                         });
-                        return this.stripTombstoneFromResult(result, tombstoneIndex);
+                        const stripped = this.stripTombstoneFromResult(result, tombstoneIndex);
+                        return this.attachEvicted(stripped, evicted, tombstoneIndex);
                     }
                     if (existingRow) {
                         // Live row already in overlay for this PK. Resolve against any column-level
@@ -626,7 +1010,7 @@ export class IsolatedTable extends VirtualTable {
                             return pkOutcome.terminating;
                         replacedUnderlyingRow = pkOutcome.replacedUnderlyingRow;
                         // Check non-PK UNIQUE constraints against merged view
-                        const ucResult = await this.checkMergedUniqueConstraints(overlay, values, [pk], tombstoneIndex, args.onConflict, evicted);
+                        const ucResult = await this.checkMergedUniqueConstraints(overlay, coercedValues, [pk], tombstoneIndex, args.onConflict, evicted);
                         if (ucResult !== null)
                             return ucResult;
                     }
@@ -646,7 +1030,7 @@ export class IsolatedTable extends VirtualTable {
                 // 2. Underlying only - insert into overlay with new values
                 // 3. Both (previous update) - update the overlay row
                 const pkIndices = this.getPrimaryKeyIndices();
-                const targetPK = oldKeyValues ?? (values ? pkIndices.map(i => values[i]) : undefined);
+                const targetPK = oldKeyValues ?? (coercedValues ? pkIndices.map(i => coercedValues[i]) : undefined);
                 if (!targetPK || !values) {
                     throw new Error('UPDATE requires oldKeyValues or values with primary key');
                 }
@@ -655,7 +1039,7 @@ export class IsolatedTable extends VirtualTable {
                 // Secondary-UNIQUE REPLACE evictions surfaced via `evictedRows`.
                 const evicted = [];
                 if (existingOverlayRow) {
-                    const newPK = pkIndices.map(i => values[i]);
+                    const newPK = pkIndices.map(i => coercedValues[i]);
                     const pkChanged = !this.keysEqual(targetPK, newPK);
                     if (pkChanged) {
                         // PK is changing: check for conflicts at the new PK, then tombstone the old
@@ -664,7 +1048,7 @@ export class IsolatedTable extends VirtualTable {
                         const pkOutcome = await this.checkMergedPKConflict(overlay, newPK, tombstoneIndex, args.onConflict);
                         if (pkOutcome.terminating)
                             return pkOutcome.terminating;
-                        const ucResult = await this.checkMergedUniqueConstraints(overlay, values, [targetPK, newPK], tombstoneIndex, args.onConflict, evicted);
+                        const ucResult = await this.checkMergedUniqueConstraints(overlay, coercedValues, [targetPK, newPK], tombstoneIndex, args.onConflict, evicted);
                         if (ucResult !== null)
                             return ucResult;
                         // Remove existing overlay row then insert a tombstone so the underlying
@@ -689,7 +1073,7 @@ export class IsolatedTable extends VirtualTable {
                 }
                 else {
                     // Insert new overlay row (shadows underlying) — check underlying conflicts first
-                    const newPK = pkIndices.map(i => values[i]);
+                    const newPK = pkIndices.map(i => coercedValues[i]);
                     const pkChanged = !this.keysEqual(targetPK, newPK);
                     let replacedUnderlyingRow;
                     if (pkChanged) {
@@ -699,7 +1083,7 @@ export class IsolatedTable extends VirtualTable {
                         replacedUnderlyingRow = pkOutcome.replacedUnderlyingRow;
                     }
                     const selfPks = pkChanged ? [targetPK, newPK] : [targetPK];
-                    const ucResult = await this.checkMergedUniqueConstraints(overlay, values, selfPks, tombstoneIndex, args.onConflict, evicted);
+                    const ucResult = await this.checkMergedUniqueConstraints(overlay, coercedValues, selfPks, tombstoneIndex, args.onConflict, evicted);
                     if (ucResult !== null)
                         return ucResult;
                     // For PK-change updates, tombstone the old PK so the underlying row is deleted at flush
@@ -720,7 +1104,7 @@ export class IsolatedTable extends VirtualTable {
             case 'delete': {
                 // For deletes, insert a tombstone into overlay
                 const pkIndices = this.getPrimaryKeyIndices();
-                const targetPK = oldKeyValues ?? (values ? pkIndices.map(i => values[i]) : undefined);
+                const targetPK = oldKeyValues ?? (coercedValues ? pkIndices.map(i => coercedValues[i]) : undefined);
                 if (!targetPK) {
                     throw new Error('DELETE requires oldKeyValues or values with primary key');
                 }
@@ -845,57 +1229,14 @@ export class IsolatedTable extends VirtualTable {
      * Creates a FilterInfo for a full table scan (no constraints).
      */
     createFullScanFilterInfo() {
-        return {
-            idxNum: 0,
-            idxStr: null,
-            constraints: [],
-            args: [],
-            indexInfoOutput: {
-                nConstraint: 0,
-                aConstraint: [],
-                nOrderBy: 0,
-                aOrderBy: [],
-                colUsed: 0n,
-                aConstraintUsage: [],
-                idxNum: 0,
-                idxStr: null,
-                orderByConsumed: false,
-                estimatedCost: 1000000,
-                estimatedRows: 1000000n,
-                idxFlags: 0,
-            },
-        };
+        return makeFullScanFilterInfo();
     }
     /**
      * Creates a FilterInfo for a primary key point lookup (equality on all PK columns).
      * This produces O(log n) lookups instead of O(n) full scans.
      */
     buildPKPointLookupFilter(pk) {
-        const pkIndices = this.getPrimaryKeyIndices();
-        const constraints = pkIndices.map((colIdx, i) => ({
-            constraint: { iColumn: colIdx, op: IndexConstraintOp.EQ, usable: true },
-            argvIndex: i + 1,
-        }));
-        return {
-            idxNum: 0,
-            idxStr: 'idx=_primary_(0);plan=2',
-            constraints,
-            args: pk,
-            indexInfoOutput: {
-                nConstraint: constraints.length,
-                aConstraint: constraints.map(c => c.constraint),
-                nOrderBy: 0,
-                aOrderBy: [],
-                colUsed: 0n,
-                aConstraintUsage: constraints.map(c => ({ argvIndex: c.argvIndex, omit: true })),
-                idxNum: 0,
-                idxStr: 'idx=_primary_(0);plan=2',
-                orderByConsumed: false,
-                estimatedCost: 1,
-                estimatedRows: 1n,
-                idxFlags: 0,
-            },
-        };
+        return makePkPointLookupFilter(this.getPrimaryKeyIndices(), pk);
     }
     // ==================== Merged-View Conflict Detection ====================
     /**
@@ -908,7 +1249,7 @@ export class IsolatedTable 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;
@@ -921,10 +1262,9 @@ export class IsolatedTable extends VirtualTable {
         // rewrite ('apple' → 'APPLE') is the SAME logical key. A binary comparison here
         // would mis-classify it as a PK relocation, then resolve the "new" key back to the
         // same physical underlying row and raise a false UNIQUE PK conflict.
-        const pkDef = this.tableSchema?.primaryKeyDefinition;
+        const collations = this.getPkCollations();
         for (let i = 0; i < a.length; i++) {
-            const collation = pkDef ? this.tableSchema.columns[pkDef[i].index].collation : undefined;
-            if (compareSqlValues(a[i], b[i], collation) !== 0)
+            if (compareSqlValuesFast(a[i], b[i], collations[i] ?? BINARY_COLLATION) !== 0)
                 return false;
         }
         return true;
@@ -1021,52 +1361,144 @@ export class IsolatedTable extends VirtualTable {
         };
     }
     /**
-     * Scans the underlying table for a row conflicting with newRow on `uc.columns`,
-     * excluding selfPks and rows tombstoned in the overlay. For partial UNIQUE,
-     * candidates whose row does not satisfy the predicate are skipped.
+     * Finds a row conflicting with `newRow` on `uc.columns` across the MERGED view —
+     * this connection's overlay superimposed on the underlying committed rows —
+     * excluding `selfPks`. For partial UNIQUE, candidates outside the predicate's scope
+     * are skipped.
+     *
+     * The merged view splits cleanly into two disjoint halves, each searched the way it
+     * is cheap to search:
+     *
+     *     merged view  =  (overlay rows)  ∪  (underlying rows with no overlay entry)
+     *
+     * Phase 1 scans the small in-memory overlay; Phase 2 seeks/scans the large
+     * underlying, skipping any candidate whose PK the overlay already owns (Phase 1's
+     * territory, whatever the underlying still says). Together they cover the merged
+     * view exactly once with no row visited twice.
+     *
+     * Phase 1 runs first, so when the constraint was ALREADY violated an overlay-side
+     * conflict is reported in preference to an underlying one. Under a satisfied
+     * constraint at most one conflicting row can exist, so this tie-break only changes
+     * WHICH row is named in that pre-violated case.
      */
     async findMergedUniqueConflict(overlay, uc, predicate, newRow, selfPks, tombstoneIndex) {
+        // One comparison collation per constrained column — the index's per-column
+        // COLLATE for an index-derived UNIQUE, else the declared column collation.
+        // Resolved once, above both candidate scans; both phases compare identically.
+        const collations = resolveUniqueEnforcementCollations(this.tableSchema, uc, this.collationResolver);
+        const overlayConflict = await this.findOverlayUniqueConflict(overlay, predicate, newRow, selfPks, tombstoneIndex, uc.columns, collations);
+        if (overlayConflict)
+            return overlayConflict;
+        return this.findUnderlyingUniqueConflict(overlay, uc, predicate, newRow, selfPks, tombstoneIndex, collations);
+    }
+    /**
+     * Phase 1 — scan the overlay (this connection's uncommitted write set, small and
+     * in-memory) for a live row conflicting with `newRow`. Tombstones and `selfPks` are
+     * skipped; a matching live overlay row IS the merged row (stripped of the trailing
+     * tombstone column), and its overlay value — not any stale underlying value — is
+     * what the merged view holds for that PK
+     * (isolation-merged-unique-stale-underlying-false-positive).
+     */
+    async findOverlayUniqueConflict(overlay, predicate, newRow, selfPks, tombstoneIndex, constrainedCols, collations) {
+        if (!overlay.query)
+            return null;
+        const pkIndices = this.getPrimaryKeyIndices();
+        for await (const overlayRow of overlay.query(this.createFullScanFilterInfo())) {
+            if (overlayRow[tombstoneIndex] === 1)
+                continue; // deletion marker — not a live row
+            const pk = pkIndices.map(i => overlayRow[i]);
+            if (selfPks.some(self => this.keysEqual(pk, self)))
+                continue;
+            const mergedRow = overlayRow.slice(0, tombstoneIndex);
+            if (this.rowMatchesUniqueConstraint(mergedRow, newRow, constrainedCols, collations, predicate)) {
+                return { pk, row: mergedRow };
+            }
+        }
+        return null;
+    }
+    /**
+     * Phase 2 — find an underlying committed row conflicting with `newRow`, skipping
+     * `selfPks` and any PK the overlay already owns (Phase 1's territory). The lookup is
+     * an index seek when {@link canSeekForConstraint} allows it, else the full scan —
+     * either way the per-column match runs, so a module that ignores the index hint and
+     * returns extra rows stays correct. `getOverlayRow` fires only for the candidates the
+     * seek actually returned, so it no longer costs one lookup per underlying row.
+     */
+    async findUnderlyingUniqueConflict(overlay, uc, predicate, newRow, selfPks, tombstoneIndex, collations) {
         if (!this.underlyingTable.query)
             return null;
         const pkIndices = this.getPrimaryKeyIndices();
-        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);
-        for await (const underlyingRow of this.underlyingTable.query(this.createFullScanFilterInfo())) {
+        const seekIndex = this.canSeekForConstraint(uc);
+        const filterInfo = seekIndex
+            ? makeSecondaryIndexEqSeekFilter(seekIndex, newRow)
+            : this.createFullScanFilterInfo();
+        for await (const underlyingRow of this.underlyingTable.query(filterInfo)) {
             const pk = pkIndices.map(i => underlyingRow[i]);
             if (selfPks.some(self => this.keysEqual(pk, self)))
                 continue;
+            // A PK with any overlay entry (live OR tombstone) belongs to Phase 1, which
+            // evaluated the overlay's value for it. Skip here whatever the underlying holds.
             const overlayRow = await this.getOverlayRow(overlay, pk);
-            if (overlayRow && overlayRow[tombstoneIndex] === 1)
-                continue;
-            // When a non-tombstone overlay entry supersedes this committed row, the
-            // row's current merged-view value is the overlay's — not the stale
-            // underlying value. Evaluate the UNIQUE columns (and any partial
-            // predicate) against the merged row so a candidate that was moved off
-            // the value earlier in this txn no longer counts as a conflict
-            // (isolation-merged-unique-stale-underlying-false-positive). The overlay
-            // row carries the appended tombstone column; strip it back to schema shape.
-            const mergedRow = overlayRow ? overlayRow.slice(0, tombstoneIndex) : underlyingRow;
-            const matches = constrainedCols.every((idx, i) => {
-                if (newRow[idx] === null || mergedRow[idx] === null)
-                    return false;
-                // Compare under each column's enforcement collation (the index's
-                // per-column COLLATE for an index-derived UNIQUE, else the declared
-                // column collation), so a UNIQUE over a collated column is enforced
-                // against committed rows through the isolation merge path
-                // (unique-constraint-honors-column-collation / store-index-derived-unique).
-                return compareSqlValues(newRow[idx], mergedRow[idx], collations[i]) === 0;
-            });
-            if (!matches)
-                continue;
-            // Partial UNIQUE: candidate must also be in the predicate's scope to conflict.
-            if (predicate && predicate.evaluate(mergedRow) !== true)
+            if (overlayRow)
                 continue;
-            return { pk, row: mergedRow };
+            if (this.rowMatchesUniqueConstraint(underlyingRow, newRow, uc.columns, collations, predicate)) {
+                return { pk, row: underlyingRow };
+            }
         }
         return null;
     }
+    /**
+     * True-match test shared by both merged-check phases so they compare identically:
+     * `candidate` matches `newRow` on every constrained column under that column's
+     * enforcement collation (NULLs never match), and — for a partial UNIQUE — the
+     * predicate holds for `candidate`.
+     *
+     * The per-column collation (the index's per-column COLLATE for an index-derived
+     * UNIQUE, else the declared column collation) enforces a UNIQUE over a collated
+     * column against merged rows through the isolation path
+     * (unique-constraint-honors-column-collation / store-index-derived-unique).
+     */
+    rowMatchesUniqueConstraint(candidate, newRow, constrainedCols, collations, predicate) {
+        const matches = constrainedCols.every((idx, i) => {
+            if (newRow[idx] === null || candidate[idx] === null)
+                return false;
+            return compareSqlValuesFast(newRow[idx], candidate[idx], collations[i]) === 0;
+        });
+        if (!matches)
+            return false;
+        // Partial UNIQUE: candidate must also be in the predicate's scope to conflict.
+        if (predicate && predicate.evaluate(candidate) !== true)
+            return false;
+        return true;
+    }
+    /**
+     * The secondary index Phase 2 may seek for `uc`, or null to fall back to a full scan.
+     *
+     * Seek only when the constraint was synthesized from a `CREATE UNIQUE INDEX`
+     * (`derivedFromIndex` names a live entry in `tableSchema.indexes`) AND every key
+     * column's effective enforcement collation is BINARY.
+     *
+     * NOTE: the BINARY gate is load-bearing, not an optimisation choice. The store's
+     * physical index key bytes come from a separate encoder registry that does NOT
+     * consult the database's collation registry
+     * (backlog/debt-store-index-keys-use-column-collation, see the comment at
+     * getPkKeyShape above). Seeking a NOCASE index for 'B@X' would miss the committed
+     * 'b@x' that the full scan catches, turning this perf fix into a LOST UNIQUE
+     * violation. Widen this gate (to per-column enforcement collations generally) only
+     * once that encoder defect is fixed.
+     */
+    canSeekForConstraint(uc) {
+        if (!uc.derivedFromIndex)
+            return null;
+        const index = this.tableSchema?.indexes?.find(i => i.name === uc.derivedFromIndex);
+        if (!index)
+            return null; // DROP INDEX may have retired it before a stale UC object is retired
+        // Enforcement collation per constrained column, positionally aligned with the
+        // index key columns (appendIndexToTableSchema guarantees the alignment).
+        const enforcement = uniqueEnforcementCollations(this.tableSchema, uc);
+        const allBinary = enforcement.every(c => normalizeCollationName(c ?? 'BINARY') === 'BINARY');
+        return allBinary ? index : null;
+    }
     /**
      * Checks all non-PK UNIQUE constraints against the merged view.
      * Returns null when all pass or REPLACE evictions succeed.
@@ -1099,8 +1531,9 @@ export class IsolatedTable extends VirtualTable {
                 return { status: 'ok', row: undefined };
             if (effective === ConflictResolution.REPLACE) {
                 await this.insertTombstoneForPK(overlay, conflict.pk, tombstoneIndex);
-                // Report the eviction (the conflicting row is the live underlying row,
-                // already user-facing). The executor maintains the covering backing.
+                // Report the eviction. `conflict.row` is the merged row in user-facing
+                // schema shape whether it was found overlay-side (Phase 1) or
+                // underlying-side (Phase 2). The executor maintains the covering backing.
                 evicted.push(conflict.row);
                 continue;
             }
@@ -1124,143 +1557,25 @@ export class IsolatedTable extends VirtualTable {
         await this.overlayTable?.sync?.();
     }
     async commit() {
-        await this.flushAndClearOverlay();
-        await this.underlyingTable.commit?.();
-    }
-    /**
-     * Flushes overlay changes to underlying (if any) and discards the overlay.
-     * Shared by commit() and onConnectionCommit().
-     */
-    async flushAndClearOverlay() {
-        // A poisoned overlay must never be flushed to the (already-altered) underlying:
-        // its rows are in the pre-alter layout. Throwing here is how a connection that
-        // never touches the poisoned table again still errors at commit, failing the
-        // whole transaction. The overlay is left intact so a subsequent rollback clears
-        // it (and the poison).
-        this.assertOverlayUsable();
-        const overlay = this.overlayTable;
-        if (this.hasChanges && overlay) {
-            await this.flushOverlayToUnderlying(overlay);
-        }
-        this.clearOverlay();
-    }
-    /**
-     * Flushes all overlay changes to the underlying table.
-     * Called during commit to persist changes.
-     *
-     * This method manages the underlying table's transaction lifecycle independently
-     * to ensure that flushed data is committed and won't be rolled back by subsequent
-     * transaction rollbacks.
-     */
-    async flushOverlayToUnderlying(overlay) {
-        if (!overlay.query)
-            return;
-        const tombstoneIndex = this.getTombstoneColumnIndex(overlay);
-        const pkIndices = this.getPrimaryKeyIndices();
-        // Collect all overlay entries first
-        const overlayEntries = [];
-        for await (const overlayRow of overlay.query(this.createFullScanFilterInfo())) {
-            const isTombstone = overlayRow[tombstoneIndex] === 1;
-            const pk = pkIndices.map(i => overlayRow[i]);
-            const dataRow = overlayRow.slice(0, tombstoneIndex);
-            overlayEntries.push({ row: overlayRow, isTombstone, pk, dataRow });
-        }
-        if (overlayEntries.length === 0)
-            return;
-        // Apply deletes (tombstones) before inserts/updates so a write that collides
-        // on a secondary UNIQUE with a row being deleted in this same flush sees the
-        // slot freed first (e.g. INSERT OR REPLACE that both replaces a PK-colliding
-        // row AND evicts a different row on a secondary UNIQUE). Each PK appears at
-        // most once in the overlay, so there is no same-PK delete-then-insert pair
-        // this reordering could invert; sort() is stable in V8/Node, preserving the
-        // original PK order within each group.
-        const ordered = [...overlayEntries].sort((a, b) => (a.isTombstone === b.isTombstone ? 0 : a.isTombstone ? -1 : 1));
-        // Begin a transaction on the underlying table for the flush
-        await this.underlyingTable.begin?.();
-        try {
-            // Apply all overlay entries to underlying
-            for (const entry of ordered) {
-                if (entry.isTombstone) {
-                    // Delete from underlying
-                    const result = await this.underlyingTable.update({
-                        operation: 'delete',
-                        values: undefined,
-                        oldKeyValues: entry.pk,
-                    });
-                    this.assertFlushWriteOk(result, 'delete', entry.pk);
-                }
-                else {
-                    // Check if row exists in underlying to decide insert vs update
-                    const existsInUnderlying = await this.rowExistsInUnderlying(entry.pk);
-                    if (existsInUnderlying) {
-                        const result = await this.underlyingTable.update({
-                            operation: 'update',
-                            values: entry.dataRow,
-                            oldKeyValues: entry.pk,
-                            preCoerced: true,
-                            trustedWrite: true,
-                        });
-                        this.assertFlushWriteOk(result, 'update', entry.pk);
-                    }
-                    else {
-                        const result = await this.underlyingTable.update({
-                            operation: 'insert',
-                            values: entry.dataRow,
-                            preCoerced: true,
-                            trustedWrite: true,
-                        });
-                        this.assertFlushWriteOk(result, 'insert', entry.pk);
-                    }
-                }
-            }
-            // Commit the underlying table's transaction
-            await this.underlyingTable.commit?.();
-        }
-        catch (error) {
-            // Rollback underlying on error
-            await this.underlyingTable.rollback?.();
-            throw error;
-        }
-    }
-    /**
-     * Asserts that an underlying write performed during the commit flush succeeded.
-     *
-     * The overlay's merged-view pre-checks ({@link checkMergedPKConflict} /
-     * {@link checkMergedUniqueConstraints}) resolve every constraint before commit, so a
-     * `constraint` result returned here means a real invariant was violated *after* those
-     * checks. Historically this result was discarded, silently dropping the colliding
-     * write and surfacing as data corruption. Convert it into a loud INTERNAL error; the
-     * caller's try/catch rolls back the underlying flush transaction and rethrows.
-     */
-    assertFlushWriteOk(result, operation, pk) {
-        if (isConstraintViolation(result)) {
-            throw new QuereusError(`Isolation flush ${operation} on '${this.tableName}' (pk=[${pk.join(', ')}]) hit a ${result.constraint} constraint: ${result.message ?? 'no message'}. The overlay merged-view pre-checks should have resolved this before commit; this indicates an isolation-layer invariant violation.`, StatusCode.INTERNAL);
-        }
-    }
-    /**
-     * Checks if a row with the given primary key exists in the underlying table.
-     * Uses O(log n) point lookup via the PK index.
-     */
-    async rowExistsInUnderlying(pk) {
-        if (!this.underlyingTable.query)
-            return false;
-        for await (const _row of this.underlyingTable.query(this.buildPKPointLookupFilter(pk))) {
-            return true;
-        }
-        return false;
+        // Route through the module coordinator (see onConnectionCommit) so even the
+        // table-level commit path performs the atomic apply-all-then-commit-all flush
+        // across the whole db-transaction's overlays, rather than committing this
+        // table's underlying in isolation (which tears a multi-table commit).
+        await this.isolationModule.commitConnectionOverlays(this.db);
     }
     async rollback() {
         await this.underlyingTable.rollback?.();
-        this.clearOverlay();
+        await this.clearOverlay();
     }
     /**
-     * Discards the connection-scoped overlay entirely.
-     * The overlay table is per-connection and ephemeral, so simply removing
-     * the reference allows GC to reclaim it. A fresh overlay will be created
+     * Discards the connection-scoped overlay entirely. The module frees the overlay's
+     * staging table (see IsolationModule.clearConnectionOverlay → releaseOverlayTable) rather
+     * than merely dropping the reference — the overlay module's registry pins the manager, so
+     * a bare reference-drop leaked it for the life of the Database. A fresh overlay is created
      * lazily via ensureOverlay() on the next write.
      */
-    clearOverlay() {
-        this.isolationModule.clearConnectionOverlay(this.db, this.schemaName, this.tableName);
+    async clearOverlay() {
+        await this.isolationModule.clearConnectionOverlay(this.db, this.schemaName, this.tableName);
     }
     // ==================== Savepoints ====================
     // Overlay savepoints are managed by IsolatedConnection (which forwards
@@ -1288,20 +1603,24 @@ export class IsolatedTable extends VirtualTable {
         // Update our schema reference
         this.tableSchema = this.underlyingTable.tableSchema;
         // Clear any existing overlay - it will be recreated with new schema on next write
-        this.isolationModule.clearConnectionOverlay(this.db, this.schemaName, this.tableName);
+        await this.isolationModule.clearConnectionOverlay(this.db, this.schemaName, this.tableName);
     }
-    async createIndex(indexInfo) {
-        await this.underlyingTable.createIndex?.(indexInfo);
-        // Update schema reference
+    /**
+     * Index DDL delegates to the module rather than driving the underlying and the overlay
+     * directly. The module owns the full protocol — validating against the issuing
+     * connection's effective rows, then REBUILDING every affected overlay under the new
+     * schema — and a bare `underlying.createIndex()` + `overlay.createIndex()` pair silently
+     * skips both halves. The engine only ever reaches the module-level hook, so these
+     * instance methods exist for a module that wraps `IsolationModule` in turn; routing them
+     * through the module keeps that path on the same protocol.
+     */
+    async createIndex(indexInfo, rows) {
+        await this.isolationModule.createIndex(this.db, this.schemaName, this.tableName, indexInfo, rows);
         this.tableSchema = this.underlyingTable.tableSchema;
-        // If overlay exists, add index to it too
-        await this.overlayTable?.createIndex?.(indexInfo);
     }
     async dropIndex(indexName) {
-        await this.underlyingTable.dropIndex?.(indexName);
-        // Update schema reference
+        await this.isolationModule.dropIndex(this.db, this.schemaName, this.tableName, indexName);
         this.tableSchema = this.underlyingTable.tableSchema;
-        await this.overlayTable?.dropIndex?.(indexName);
     }
     // ==================== Internal Helpers ====================
     /**
@@ -1338,7 +1657,16 @@ export class IsolatedTable extends VirtualTable {
      * Flushes overlay to underlying and clears overlay.
      */
     async onConnectionCommit() {
-        await this.flushAndClearOverlay();
+        // Delegate to the module coordinator, which flushes EVERY overlay this
+        // db-transaction staged (not just this table's) in one apply-all-then-commit-all
+        // pass and clears them — so a multi-table commit is atomic. The first connection
+        // in the database's commit loop performs the whole flush; later connections find
+        // their overlay already cleared and this is a no-op. Poison is enforced inside
+        // the coordinator (it aborts before any table commits).
+        await this.isolationModule.commitConnectionOverlays(this.db);
+        // Clear this table's pre-overlay savepoint set. Kept per-connection (rather than
+        // inside the coordinator) so a table that took a savepoint before its first write
+        // but never got an overlay still has its set cleared here.
         this.isolationModule.clearPreOverlaySavepoints(this.db, this.schemaName, this.tableName);
     }
     /**
@@ -1346,7 +1674,7 @@ export class IsolatedTable extends VirtualTable {
      * Clears overlay without flushing.
      */
     async onConnectionRollback() {
-        this.clearOverlay();
+        await this.clearOverlay();
         this.isolationModule.clearPreOverlaySavepoints(this.db, this.schemaName, this.tableName);
     }
     /**
@@ -1384,7 +1712,7 @@ export class IsolatedTable extends VirtualTable {
     async onConnectionRollbackToSavepoint(index) {
         if (this.savepointsBeforeOverlay.has(index)) {
             // Rolling back to before the overlay existed — discard all overlay changes
-            this.clearOverlay();
+            await this.clearOverlay();
             // Remove savepoints above the target (they're implicitly gone)
             for (const depth of [...this.savepointsBeforeOverlay]) {
                 if (depth > index) {
@@ -1395,6 +1723,16 @@ export class IsolatedTable extends VirtualTable {
         // If overlay's registered connection has this savepoint, it handles rollback
     }
 }
+/** True when a comparator result `cmp` (row value vs bound value) satisfies the range op. */
+function satisfiesBound(cmp, op) {
+    switch (op) {
+        case IndexConstraintOp.GT: return cmp > 0;
+        case IndexConstraintOp.GE: return cmp >= 0;
+        case IndexConstraintOp.LT: return cmp < 0;
+        case IndexConstraintOp.LE: return cmp <= 0;
+        default: return true;
+    }
+}
 /**
  * Resolves the per-constraint default conflict action for PK conflicts.
  * Prefers the table-level `PRIMARY KEY (...) ON CONFLICT <action>` clause