@quereus/store 3.3.0 → 4.0.0

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

@@ -9,24 +9,24 @@
  *   - 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, validateAndParse, compilePredicate, } from '@quereus/quereus';
+import { VirtualTable, IndexConstraintOp, ConflictResolution, QuereusError, StatusCode, compareSqlValues, rowsValueIdentical, validateAndParse, compilePredicate, maintainedTableUniqueViolationError, uniqueEnforcementCollations, } from '@quereus/quereus';
+import { bytesEqual, bytesToHex, compareBytes } from './bytes.js';
 import { StoreConnection } from './store-connection.js';
-import { buildDataKey, buildIndexKey, buildFullScanBounds, buildStatsKey, } from './key-builder.js';
+import { buildDataKey, buildIndexKey, 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;
-/** Hex-encode a key for use as a Map/Set lookup. */
-function bytesToHex(key) {
-    return Array.from(key).map(b => b.toString(16).padStart(2, '0')).join('');
-}
-/** Byte-wise equality check for Uint8Arrays. */
-function bytesEqual(a, b) {
-    if (a.length !== b.length)
+/** True when `key` falls within the (gte/gt/lte/lt) window of `bounds`. */
+function keyWithinBounds(key, bounds) {
+    if (bounds.gte && compareBytes(key, bounds.gte) < 0)
+        return false;
+    if (bounds.gt && compareBytes(key, bounds.gt) <= 0)
+        return false;
+    if (bounds.lte && compareBytes(key, bounds.lte) > 0)
+        return false;
+    if (bounds.lt && compareBytes(key, bounds.lt) >= 0)
         return false;
-    for (let i = 0; i < a.length; i++) {
-        if (a[i] !== b[i])
-            return false;
-    }
     return true;
 }
 /**
@@ -49,6 +49,34 @@ function resolvePkDefaultConflict(schema) {
     }
     return undefined;
 }
+/**
+ * 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
+ *     `fallback` (the table key collation K) when the column carries none.
+ *   - non-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
+ * `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();
+    });
+}
 /**
  * Generic KVStore-backed virtual table.
  *
@@ -64,10 +92,25 @@ export class StoreTable extends VirtualTable {
     indexStores = new Map();
     statsStore = null;
     coordinator = null;
+    /**
+     * Disposer returned by the coordinator's `registerCallbacks`, captured on the
+     * first {@link attachCoordinator}. Run by {@link dispose} at hard eviction to
+     * deregister this instance's {stats apply/discard} pair from the module-wide
+     * coordinator; null until attached, and nulled again after dispose.
+     */
+    coordinatorDisposer = null;
     connection = null;
     eventEmitter;
     encodeOptions;
     pkDirections;
+    /**
+     * Per-PK-column KEY collation (see {@link resolvePkKeyCollations}). Drives the
+     * physical encoding of every data key and the PK suffix of every secondary-index
+     * key, so a text PK column declared BINARY/NOCASE/RTRIM is keyed under its own
+     * collation rather than one fixed table-level collation. Recomputed on every
+     * {@link updateSchema} (an ALTER COLUMN SET COLLATE on a PK member changes it).
+     */
+    pkKeyCollations;
     ddlSaved = false;
     // Statistics tracking
     cachedStats = null;
@@ -79,6 +122,11 @@ export class StoreTable extends VirtualTable {
     // new constraint object after CREATE/DROP INDEX produces a fresh compile;
     // the WeakMap lets the GC reclaim entries for retired constraints.
     predicateCache = new WeakMap();
+    // Lazy cache of compiled partial-index predicates, keyed on the IndexSchema
+    // object identity (frozen; a CREATE/DROP INDEX or reopen produces a fresh
+    // object, so the WeakMap reclaims retired entries). Mirrors predicateCache but
+    // for secondary-index maintenance rather than UNIQUE enforcement.
+    indexPredicateCache = new WeakMap();
     constructor(db, storeModule, tableSchema, config, eventEmitter, isConnected = false) {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         super(db, storeModule, tableSchema.schemaName, tableSchema.name);
@@ -88,6 +136,7 @@ export class StoreTable extends VirtualTable {
         this.eventEmitter = eventEmitter;
         this.encodeOptions = { collation: config.collation || 'NOCASE' };
         this.pkDirections = tableSchema.primaryKeyDefinition.map(pk => !!pk.desc);
+        this.pkKeyCollations = resolvePkKeyCollations(tableSchema.primaryKeyDefinition, tableSchema.columns, this.encodeOptions.collation ?? 'NOCASE');
         this.ddlSaved = isConnected;
     }
     /** Get the table configuration. */
@@ -102,6 +151,16 @@ export class StoreTable extends VirtualTable {
     updateSchema(newSchema) {
         this.tableSchema = newSchema;
         this.pkDirections = newSchema.primaryKeyDefinition.map(pk => !!pk.desc);
+        this.pkKeyCollations = resolvePkKeyCollations(newSchema.primaryKeyDefinition, newSchema.columns, this.encodeOptions.collation ?? 'NOCASE');
+    }
+    /**
+     * Mark the table's DDL as already persisted to the catalog, so the lazy
+     * first-store-access save in {@link initializeStore} is skipped. Called by
+     * `StoreModule.createIndex` / `dropIndex` after they eagerly write the catalog
+     * bundle, so a subsequent INSERT does not redundantly re-persist identical DDL.
+     */
+    markDdlSaved() {
+        this.ddlSaved = true;
     }
     /** Close and forget a cached index-store handle, if any. */
     async releaseIndexStore(indexName) {
@@ -171,16 +230,27 @@ export class StoreTable extends VirtualTable {
      * 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
      * the PK changes).
+     *
+     * The new key for each row is encoded under `newColumns`'s per-column PK
+     * collations, so this drives BOTH:
+     *   - `ALTER PRIMARY KEY` — the PK *columns* change; `newColumns` defaults to the
+     *     current column set (their collations are unchanged), and
+     *   - `ALTER COLUMN … SET COLLATE` on a PK member — the PK columns stay the same
+     *     but one column's collation changes; the caller passes the post-ALTER
+     *     `updatedSchema.columns` so the new key bytes follow the new collation.
+     * The OLD key is taken verbatim from the stored entry (never re-encoded), so the
+     * old collation is implicit in the existing bytes and need not be supplied.
      */
-    async rekeyRows(newPkDef) {
+    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');
         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);
+            const newKey = buildDataKey(newPkValues, this.encodeOptions, newPkDirections, newPkCollations);
             const hex = bytesToHex(newKey);
             if (pending.has(hex)) {
                 throw new QuereusError(`UNIQUE constraint failed: duplicate primary key on rekey of '${this.schemaName}.${this.tableName}'`, StatusCode.CONSTRAINT);
@@ -200,16 +270,29 @@ export class StoreTable extends VirtualTable {
      * Migrate all stored rows from the old column layout to a new one.
      * The remap array maps newColumnIndex -> oldColumnIndex | -1.
      * -1 means the column is new (fill with defaultValue).
+     *
+     * `backfill`, when supplied (ADD COLUMN with a non-foldable DEFAULT such as
+     * `new.<col>`), derives the new column's value from each existing row instead of the
+     * single `defaultValue`, and rejects a NULL it produces for a NOT NULL column. The
+     * batch is only written once every row migrates, so a throwing evaluator / NOT NULL
+     * violation leaves the store untouched for the caller's rollback.
      */
-    async migrateRows(remap, defaultValue) {
+    async migrateRows(remap, defaultValue, backfill) {
         const store = await this.ensureStore();
         const bounds = buildFullScanBounds();
         const batch = store.batch();
         for await (const entry of store.iterate(bounds)) {
             const oldRow = deserializeRow(entry.value);
+            let newColumnValue = defaultValue;
+            if (backfill) {
+                newColumnValue = await backfill.evaluator(oldRow);
+                if (backfill.notNull && newColumnValue === null) {
+                    throw new QuereusError(`NOT NULL constraint failed: backfilling column '${this.schemaName}.${this.tableName}.${backfill.columnName}' produced NULL for an existing row`, StatusCode.CONSTRAINT);
+                }
+            }
             const newRow = new Array(remap.length);
             for (let i = 0; i < remap.length; i++) {
-                newRow[i] = remap[i] === -1 ? defaultValue : oldRow[remap[i]];
+                newRow[i] = remap[i] === -1 ? newColumnValue : oldRow[remap[i]];
             }
             batch.put(entry.key, serializeRow(newRow));
         }
@@ -274,22 +357,47 @@ export class StoreTable extends VirtualTable {
         return this.statsStore;
     }
     /**
-     * Ensure the coordinator is available and connection is registered.
+     * Resolve + cache the module's shared TransactionCoordinator and hook the
+     * stats lifecycle callbacks, WITHOUT creating or registering a connection.
+     * Synchronous (the coordinator is handle-addressed, never store-opening — see
+     * `StoreTableModule.getCoordinator`), so the backing host's resolution path can
+     * call it eagerly. Attaching matters for reads: `iterateEffective` /
+     * `readEffectiveRowByKey` consult `this.coordinator` for the pending merge, so a
+     * table whose only writer is the privileged backing host (which queues ops on the
+     * module coordinator, never through `update()`) must still hold the
+     * reference for its read paths to be reads-own-writes.
+     *
+     * The coordinator is module-wide, so its commit/rollback callback array holds
+     * one {stats apply/discard} pair per PARTICIPATING table; each table's
+     * `applyPendingStats` early-returns when its own `pendingStatsDelta` is 0, so a
+     * table that did no work contributes nothing. Registers only on first call per
+     * StoreTable instance (the `if (!this.coordinator)` guard); a fresh instance
+     * after drop+recreate re-registers against the shared coordinator. The OLD
+     * instance is not GC'd on its own — its callback closures capture `this` and
+     * stay pinned on the module-wide coordinator until {@link dispose} runs the
+     * captured disposer (called at the genuine eviction sites, see
+     * `StoreModule.tearDownTableStorage` / `renameTable`).
      */
-    async ensureCoordinator() {
+    attachCoordinator() {
         if (!this.coordinator) {
-            const tableKey = `${this.schemaName}.${this.tableName}`.toLowerCase();
-            this.coordinator = await this.storeModule.getCoordinator(tableKey, this.config);
-            this.coordinator.registerCallbacks({
+            this.coordinator = this.storeModule.getCoordinator();
+            this.coordinatorDisposer = this.coordinator.registerCallbacks({
                 onCommit: () => this.applyPendingStats(),
                 onRollback: () => this.discardPendingStats(),
             });
         }
+        return this.coordinator;
+    }
+    /**
+     * Ensure the coordinator is available and connection is registered.
+     */
+    async ensureCoordinator() {
+        const coordinator = this.attachCoordinator();
         if (!this.connection) {
-            this.connection = new StoreConnection(this.tableName, this.coordinator);
+            this.connection = new StoreConnection(`${this.schemaName}.${this.tableName}`, coordinator);
             await this.db.registerConnection(this.connection);
         }
-        return this.coordinator;
+        return coordinator;
     }
     /** Apply pending stats on commit. */
     applyPendingStats() {
@@ -349,18 +457,22 @@ export class StoreTable extends VirtualTable {
         }
         return row.map((v, i) => validateAndParse(v, cols[i].logicalType, cols[i].name));
     }
-    /** Query the table with optional filters. */
+    /**
+     * Query the table with optional filters.
+     *
+     * All three access arms read the EFFECTIVE row state: the committed store
+     * merged with this table's coordinator's pending ops when a transaction is
+     * active (read-your-own-writes — see {@link iterateEffective} /
+     * {@link readLiveRowByPk}). Merged emission stays in encoded-PK-key order,
+     * preserving the module's `providesOrdering` / `monotonicOn` advertisements.
+     */
     async *query(filterInfo) {
         const store = await this.ensureStore();
         const pkAccess = this.analyzePKAccess(filterInfo);
         if (pkAccess.type === 'point') {
-            const key = buildDataKey(pkAccess.values, this.encodeOptions, this.pkDirections);
-            const value = await store.get(key);
-            if (value) {
-                const row = deserializeRow(value);
-                if (this.matchesFilters(row, filterInfo)) {
-                    yield row;
-                }
+            const row = await this.readLiveRowByPk(pkAccess.values);
+            if (row && this.matchesFilters(row, filterInfo)) {
+                yield row;
             }
             return;
         }
@@ -370,13 +482,63 @@ export class StoreTable extends VirtualTable {
         }
         // Full table scan
         const bounds = buildFullScanBounds();
-        for await (const entry of store.iterate(bounds)) {
+        for await (const entry of this.iterateEffective(store, bounds)) {
             const row = deserializeRow(entry.value);
             if (this.matchesFilters(row, filterInfo)) {
                 yield row;
             }
         }
     }
+    /**
+     * Iterate the effective entry state of this table's data store within
+     * `bounds`: the committed `store.iterate` stream merged with the
+     * coordinator's pending ops for the data store (read-your-own-writes).
+     *
+     * Both inputs are sorted by encoded key bytes, so this is an
+     * order-preserving two-way merge: a pending put wins over a committed entry
+     * at the same key, a pending delete suppresses its committed entry, and
+     * pending puts outside `bounds` are excluded. With no active transaction
+     * (or an empty pending bucket) it degrades to the bare committed iterate.
+     *
+     * The pending side is the module coordinator's bucket for THIS table's data
+     * store handle (`store`) — every data op is queued under that exact handle, so
+     * a sibling table's pending ops (a different data-store handle) never bleed in.
+     */
+    async *iterateEffective(store, bounds, reverse = false) {
+        const pending = this.coordinator?.isInTransaction()
+            ? this.coordinator.getOrderedPendingOps(store)
+            : null;
+        const iterOptions = reverse ? { ...bounds, reverse } : bounds;
+        if (!pending || (pending.puts.length === 0 && pending.deletes.size === 0)) {
+            yield* store.iterate(iterOptions);
+            return;
+        }
+        const puts = pending.puts.filter(p => keyWithinBounds(p.key, bounds));
+        if (reverse)
+            puts.reverse();
+        // In iteration order, "before" means byte-less for forward and byte-greater
+        // for reverse; sign folds the direction into one comparison.
+        const sign = reverse ? -1 : 1;
+        let putIdx = 0;
+        for await (const entry of store.iterate(iterOptions)) {
+            // Emit pending puts that precede this committed entry in iteration order.
+            while (putIdx < puts.length && sign * compareBytes(puts[putIdx].key, entry.key) < 0) {
+                yield puts[putIdx++];
+            }
+            // Equal keys: the pending put shadows the committed entry.
+            if (putIdx < puts.length && compareBytes(puts[putIdx].key, entry.key) === 0) {
+                yield puts[putIdx++];
+                continue;
+            }
+            if (pending.deletes.has(bytesToHex(entry.key)))
+                continue;
+            yield entry;
+        }
+        // Pending puts beyond the last committed entry.
+        while (putIdx < puts.length) {
+            yield puts[putIdx++];
+        }
+    }
     /** Analyze filter info to determine PK access pattern. */
     analyzePKAccess(filterInfo) {
         const schema = this.tableSchema;
@@ -418,11 +580,85 @@ export class StoreTable extends VirtualTable {
         }
         return { type: 'scan' };
     }
-    /** Scan a range of PK values. */
-    async *scanPKRange(store, _access, filterInfo) {
-        const bounds = buildFullScanBounds();
-        // TODO: Refine bounds based on range constraints
-        for await (const entry of store.iterate(bounds)) {
+    /**
+     * Convert a leading-PK-column range access into one seek + early-terminate
+     * iterate window.
+     *
+     * Each LT/LE/GT/GE constraint's bound value is encoded under the SAME
+     * per-column DESC direction and key collation as the data keys (via
+     * {@link encodePkPrefixBounds}), giving the byte region `[lo, hi)` whose
+     * leading column equals that value (`lo = encode([x])`,
+     * `hi = incrementLastByte(lo)`). The op maps that region's endpoints onto a
+     * `gte`/`lt` window; because a DESC column bit-inverts its bytes (larger value
+     * ⇒ smaller bytes), the lower/upper assignment swaps with direction:
+     *
+     *   | 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 (BETWEEN ⇒ one lower + one upper; a redundant same-side
+     * pair ⇒ the tighter wins) we keep the MAX lower candidate for `gte` and the
+     * MIN upper candidate for `lt`. A candidate that resolves to `undefined` (an
+     * `hi` whose increment overflowed all-0xff) leaves that side unbounded — a safe
+     * SUPERSET, since {@link matchesFilters} stays the authoritative collation-aware
+     * 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.
+     */
+    buildPKRangeBounds(access) {
+        const full = buildFullScanBounds();
+        const constraints = access.constraints;
+        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) {
+            if (c.value === undefined || c.value === null)
+                continue;
+            const { gte: lo, lt: hi } = this.encodePkPrefixBounds([c.value]);
+            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 leading-PK-column range, seeking to the window start and
+     * early-terminating at its end.
+     *
+     * {@link buildPKRangeBounds} converts the LT/LE/GT/GE constraints into one
+     * encoded-byte `gte`/`lt` window under the same per-column DESC directions and
+     * key collations the data keys use, so the iterate visits a SUPERSET of the
+     * qualifying rows (a collation widening or the bound-byte increment can
+     * over-fetch, never under-fetch). {@link matchesFilters} stays the authoritative
+     * collation-aware row filter. {@link iterateEffective} restricts the pending
+     * merge to the same `bounds`, so read-your-own-writes holds on the narrowed window.
+     */
+    async *scanPKRange(store, access, 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)) {
                 yield row;
@@ -441,26 +677,40 @@ export class StoreTable extends VirtualTable {
             }
             const rowValue = row[constraint.iColumn];
             const filterValue = filterInfo.args[argvIndex - 1];
-            if (!this.compareValues(rowValue, constraint.op, filterValue)) {
+            // 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;
+            if (!this.compareValues(rowValue, constraint.op, filterValue, collation)) {
                 return false;
             }
         }
         return true;
     }
-    /** Compare two values according to an operator. */
-    compareValues(a, op, b) {
+    /**
+     * 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
+     * `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) {
         if (a === null || b === null) {
             return op === IndexConstraintOp.EQ ? a === b : false;
         }
+        const cmp = compareSqlValues(a, b, collation);
         switch (op) {
-            case IndexConstraintOp.EQ:
-                return a === b || (typeof a === 'string' && typeof b === 'string' &&
-                    this.config.collation === 'NOCASE' && a.toLowerCase() === b.toLowerCase());
-            case IndexConstraintOp.NE: return a !== b;
-            case IndexConstraintOp.LT: return a < b;
-            case IndexConstraintOp.LE: return a <= b;
-            case IndexConstraintOp.GT: return a > b;
-            case IndexConstraintOp.GE: return a >= b;
+            case IndexConstraintOp.EQ: return cmp === 0;
+            case IndexConstraintOp.NE: return cmp !== 0;
+            case IndexConstraintOp.LT: return cmp < 0;
+            case IndexConstraintOp.LE: return cmp <= 0;
+            case IndexConstraintOp.GT: return cmp > 0;
+            case IndexConstraintOp.GE: return cmp >= 0;
             default: return true;
         }
     }
@@ -477,17 +727,47 @@ export class StoreTable extends VirtualTable {
                     throw new QuereusError('INSERT requires values', StatusCode.MISUSE);
                 const coerced = args.preCoerced ? values : this.coerceRow(values);
                 const pk = this.extractPK(coerced);
-                const key = buildDataKey(pk, this.encodeOptions, this.pkDirections);
+                const key = buildDataKey(pk, this.encodeOptions, this.pkDirections, this.pkKeyCollations);
                 // Check for existing row (for conflict handling).
                 // Resolve PK-conflict action: statement OR > per-constraint default > ABORT.
                 const pkEffective = args.onConflict ?? resolvePkDefaultConflict(schema) ?? ConflictResolution.ABORT;
-                const existing = await store.get(key);
-                if (existing) {
+                // Trusted-flush safety analysis — why this arm diverges from the others.
+                // The insert arm's probe stays committed-only on the trusted-flush path,
+                // while the update/delete arms below read the effective
+                // (pending-over-committed) image UNCONDITIONALLY. That divergence is
+                // safe: `flushOverlayToUnderlying` (isolation, isolated-table.ts) wraps
+                // the flush in its own coordinator mini-transaction, the overlay holds
+                // at most ONE entry per PK, and tombstone deletes are ordered before
+                // inserts/updates — so when any flush write probes its own key, no
+                // pending op exists at that key yet in the mini-transaction and the
+                // effective read equals the committed read on every trusted probe. The
+                // committed-only read kept here is therefore NOT a read-correctness
+                // requirement but a pinned INTERNAL invariant: the flush routes existing
+                // PKs to update, so a row present here is an isolation-layer violation we
+                // must surface loudly (store-backing-host-substrate analysis).
+                let existingRow;
+                if (args.trustedWrite) {
+                    const committed = await store.get(key);
+                    existingRow = committed ? deserializeRow(committed) : null;
+                }
+                else {
+                    existingRow = await this.readEffectiveRowByKey(key);
+                }
+                if (args.trustedWrite) {
+                    // Trusted flush insert: the overlay flush routes existing PKs to
+                    // update (via rowExistsInUnderlying), so a row already present here
+                    // is an isolation-layer invariant violation. Fail loudly rather than
+                    // silently overwrite — the flush try/catch rolls back and rethrows
+                    // (isolation-merged-unique-stale-underlying-false-positive).
+                    if (existingRow) {
+                        throw new QuereusError(`Trusted flush insert on '${this.tableName}' hit an existing PK; the overlay flush should route existing PKs to update. This indicates an isolation-layer invariant violation.`, StatusCode.INTERNAL);
+                    }
+                }
+                else if (existingRow) {
                     if (pkEffective === ConflictResolution.IGNORE) {
                         return { status: 'ok', row: undefined };
                     }
                     if (pkEffective !== ConflictResolution.REPLACE) {
-                        const existingRow = deserializeRow(existing);
                         return {
                             status: 'constraint',
                             constraint: 'unique',
@@ -498,22 +778,30 @@ export class StoreTable extends VirtualTable {
                 }
                 // Enforce non-PK UNIQUE constraints. Pass the original statement-level
                 // onConflict so checkUniqueConstraints can resolve each UC's own
-                // defaultConflict independently of the PK's default.
-                const ucResult = await this.checkUniqueConstraints(inTransaction, coerced, [pk], args.onConflict);
-                if (ucResult)
-                    return ucResult;
-                const oldRow = existing ? deserializeRow(existing) : null;
+                // defaultConflict independently of the PK's default. Secondary-UNIQUE
+                // REPLACE evictions accumulate in `evicted` for the executor pipeline.
+                // Skipped for trusted flush writes: the overlay already validated the
+                // final state and a value-swap cycle cannot pass a row-by-row re-check.
+                const evicted = [];
+                if (!args.trustedWrite) {
+                    const ucResult = await this.checkUniqueConstraints(inTransaction, coerced, [pk], args.onConflict, evicted);
+                    if (ucResult)
+                        return ucResult;
+                }
+                const oldRow = existingRow;
                 const serializedRow = serializeRow(coerced);
                 if (inTransaction) {
-                    coordinator.put(key, serializedRow);
+                    coordinator.put(key, serializedRow, store);
                 }
                 else {
                     await store.put(key, serializedRow);
                 }
-                // Update secondary indexes
+                // Update secondary indexes. An effective `oldRow` (a pending row at the
+                // same PK, evicted under REPLACE) cancels the earlier pending index-put;
+                // a commit-batch delete of a never-committed index key is a harmless no-op.
                 await this.updateSecondaryIndexes(inTransaction, oldRow, coerced, pk);
                 // Track statistics (only count as new if not replacing)
-                if (!existing) {
+                if (!existingRow) {
                     this.trackMutation(+1, inTransaction);
                 }
                 // Queue or emit event
@@ -549,7 +837,7 @@ export class StoreTable extends VirtualTable {
                         this.eventEmitter?.emitDataChange(insertEvent);
                     }
                 }
-                return { status: 'ok', row: coerced, replacedRow: oldRow ?? undefined };
+                return { status: 'ok', row: coerced, replacedRow: oldRow ?? undefined, evictedRows: evicted.length > 0 ? evicted : undefined };
             }
             case 'update': {
                 if (!values || !oldKeyValues)
@@ -557,23 +845,39 @@ export class StoreTable extends VirtualTable {
                 const coerced = args.preCoerced ? values : this.coerceRow(values);
                 const oldPk = this.extractPK(oldKeyValues);
                 const newPk = this.extractPK(coerced);
-                const oldKey = buildDataKey(oldPk, this.encodeOptions, this.pkDirections);
-                const newKey = buildDataKey(newPk, this.encodeOptions, this.pkDirections);
-                // Get old row for index updates
-                const oldRowData = await store.get(oldKey);
-                const oldRow = oldRowData ? deserializeRow(oldRowData) : null;
-                const pkChanged = !this.keysEqual(oldPk, newPk);
+                const oldKey = buildDataKey(oldPk, this.encodeOptions, this.pkDirections, this.pkKeyCollations);
+                const newKey = buildDataKey(newPk, this.encodeOptions, this.pkDirections, this.pkKeyCollations);
+                // Get old row for index updates. Read the effective
+                // (pending-over-committed) image UNCONDITIONALLY — including the trusted
+                // flush path — so an old image written earlier in the same transaction is
+                // visible. This fixes index cleanup, the `uniqueColumnsChanged` gate, and
+                // the event's `oldRow`. Trusted is safe here (see the insert-arm comment):
+                // deletes-first ordering + one-entry-per-PK ⇒ effective ≡ committed on a
+                // flush write probing its own key.
+                const oldRow = await this.readEffectiveRowByKey(oldKey);
+                // A PK "change" only relocates the row when the ENCODED key differs.
+                // Under a non-binary PK collation (e.g. NOCASE) a case-only rewrite
+                // ('apple' → 'APPLE') keeps the same physical key, so it is an in-place
+                // update, not a relocation. Comparing raw values via keysEqual would
+                // mis-classify it as a move and then false-detect a PK conflict against
+                // the row's own existing entry at newKey (== oldKey). The encoded keys
+                // are the storage layer's source of truth (mirrors the rekey path above).
+                const pkChanged = !bytesEqual(oldKey, newKey);
                 // Resolve PK-conflict action: statement OR > per-constraint default > ABORT.
                 const pkEffective = args.onConflict ?? resolvePkDefaultConflict(schema) ?? ConflictResolution.ABORT;
                 // PK-change UPDATE collides like an INSERT at the new key.
                 // Capture the evicted row so it can be reported via `replacedRow`
                 // (consumed by the executor for ON DELETE cascade/SET NULL of the
-                // row at the new PK). Read through the coordinator so an evictee
-                // written earlier in the same transaction is visible.
+                // row at the new PK). Read the effective (pending-over-committed) image
+                // so an evictee written earlier in the same transaction conflicts/evicts
+                // rather than being silently overwritten.
+                // Skipped for trusted flush writes — the overlay flush never changes a
+                // row's PK (oldKeyValues and the row's PK columns are the same overlay
+                // entry), so pkChanged is false there; the guard makes the intent explicit.
                 let replacedAtNewPk = null;
-                if (pkChanged) {
-                    const existingAtNew = await store.get(newKey);
-                    if (existingAtNew) {
+                if (pkChanged && !args.trustedWrite) {
+                    const existingAtNewRow = await this.readEffectiveRowByKey(newKey);
+                    if (existingAtNewRow) {
                         if (pkEffective === ConflictResolution.IGNORE) {
                             return { status: 'ok', row: undefined };
                         }
@@ -582,10 +886,10 @@ export class StoreTable extends VirtualTable {
                                 status: 'constraint',
                                 constraint: 'unique',
                                 message: `UNIQUE constraint failed: ${this.tableName} PK.`,
-                                existingRow: deserializeRow(existingAtNew),
+                                existingRow: existingAtNewRow,
                             };
                         }
-                        replacedAtNewPk = deserializeRow(existingAtNew);
+                        replacedAtNewPk = existingAtNewRow;
                     }
                 }
                 // Enforce non-PK UNIQUE constraints. For same-PK UPDATE, only check
@@ -595,10 +899,16 @@ export class StoreTable extends VirtualTable {
                 // row we're moving. Pass the original statement-level onConflict so
                 // each UC's own defaultConflict can be resolved independently.
                 const selfPks = pkChanged ? [oldPk, newPk] : [oldPk];
-                const shouldCheckUniques = pkChanged
-                    || (oldRow ? this.uniqueColumnsChanged(oldRow, coerced) : true);
+                // Skip the UNIQUE re-check for trusted flush writes: the overlay
+                // merged-view check already validated the final state, and a value-swap
+                // cycle cannot pass a row-by-row logical-UNIQUE re-check
+                // (isolation-merged-unique-stale-underlying-false-positive).
+                const shouldCheckUniques = !args.trustedWrite
+                    && (pkChanged || (oldRow ? this.uniqueColumnsChanged(oldRow, coerced) : true));
+                // Secondary-UNIQUE REPLACE evictions accumulate for the executor pipeline.
+                const evicted = [];
                 if (shouldCheckUniques) {
-                    const ucResult = await this.checkUniqueConstraints(inTransaction, coerced, selfPks, args.onConflict);
+                    const ucResult = await this.checkUniqueConstraints(inTransaction, coerced, selfPks, args.onConflict, evicted);
                     if (ucResult)
                         return ucResult;
                 }
@@ -613,7 +923,7 @@ export class StoreTable extends VirtualTable {
                 // Delete old key if PK changed
                 if (pkChanged) {
                     if (inTransaction) {
-                        coordinator.delete(oldKey);
+                        coordinator.delete(oldKey, store);
                     }
                     else {
                         await store.delete(oldKey);
@@ -621,7 +931,7 @@ export class StoreTable extends VirtualTable {
                 }
                 const serializedRow = serializeRow(coerced);
                 if (inTransaction) {
-                    coordinator.put(newKey, serializedRow);
+                    coordinator.put(newKey, serializedRow, store);
                 }
                 else {
                     await store.put(newKey, serializedRow);
@@ -645,18 +955,24 @@ export class StoreTable extends VirtualTable {
                 else {
                     this.eventEmitter?.emitDataChange(updateEvent);
                 }
-                return { status: 'ok', row: coerced, replacedRow: replacedAtNewPk ?? undefined };
+                return { status: 'ok', row: coerced, replacedRow: replacedAtNewPk ?? undefined, evictedRows: evicted.length > 0 ? evicted : undefined };
             }
             case 'delete': {
                 if (!oldKeyValues)
                     throw new QuereusError('DELETE requires oldKeyValues', StatusCode.MISUSE);
                 const pk = this.extractPK(oldKeyValues);
-                const key = buildDataKey(pk, this.encodeOptions, this.pkDirections);
-                // Get old row for index cleanup
-                const oldRowData = await store.get(key);
-                const oldRow = oldRowData ? deserializeRow(oldRowData) : null;
+                const key = buildDataKey(pk, this.encodeOptions, this.pkDirections, this.pkKeyCollations);
+                // Get old row for index cleanup. Read the effective
+                // (pending-over-committed) image so a row inserted earlier in the same
+                // transaction is seen: this fixes index cleanup, the `-1` stats delta
+                // (netting an insert+delete to zero), and the event's `oldRow`.
+                // `coordinator.delete(key)` cancels a pending put; a commit-batch delete
+                // of a never-committed key is a harmless no-op. The trusted flush delete
+                // arm does NOT pass `trustedWrite`, but deletes-first ordering +
+                // one-entry-per-PK keep effective ≡ committed there too (see insert arm).
+                const oldRow = await this.readEffectiveRowByKey(key);
                 if (inTransaction) {
-                    coordinator.delete(key);
+                    coordinator.delete(key, store);
                 }
                 else {
                     await store.delete(key);
@@ -700,10 +1016,17 @@ export class StoreTable extends VirtualTable {
             const indexStore = await this.ensureIndexStore(index.name);
             const indexCols = index.columns.map(c => c.index);
             const indexDirections = index.columns.map(c => !!c.desc);
-            // Remove old index entry
-            if (oldRow) {
+            // Partial index: only rows the predicate unambiguously accepts are
+            // indexed (mirrors buildIndexEntries' build-time filtering). Guarding both
+            // halves keeps a row that transitions across the predicate scope on UPDATE
+            // correct — an in-scope→out-of-scope edit removes the old entry and adds
+            // none; the reverse adds without a stale delete. A full index (no
+            // predicate) always maintains its entry.
+            const predicate = this.compileIndexFor(index);
+            // Remove old index entry (only if the old row was within scope).
+            if (oldRow && (!predicate || predicate.evaluate(oldRow) === true)) {
                 const oldIndexValues = indexCols.map(i => oldRow[i]);
-                const oldIndexKey = buildIndexKey(oldIndexValues, oldPk, this.encodeOptions, indexDirections, this.pkDirections);
+                const oldIndexKey = buildIndexKey(oldIndexValues, oldPk, this.encodeOptions, indexDirections, this.pkDirections, this.pkKeyCollations);
                 if (inTransaction && this.coordinator) {
                     this.coordinator.delete(oldIndexKey, indexStore);
                 }
@@ -711,10 +1034,10 @@ export class StoreTable extends VirtualTable {
                     await indexStore.delete(oldIndexKey);
                 }
             }
-            // Add new index entry
-            if (newRow) {
+            // Add new index entry (only if the new row is within scope).
+            if (newRow && (!predicate || predicate.evaluate(newRow) === true)) {
                 const newIndexValues = indexCols.map(i => newRow[i]);
-                const newIndexKey = buildIndexKey(newIndexValues, newPk, this.encodeOptions, indexDirections, this.pkDirections);
+                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);
                 if (inTransaction && this.coordinator) {
@@ -741,6 +1064,21 @@ export class StoreTable extends VirtualTable {
         }
         return compiled;
     }
+    /**
+     * Returns the compiled predicate for a partial secondary index, or undefined
+     * for a full index. Compilation is memoized per IndexSchema instance so the hot
+     * DML index-maintenance path doesn't recompile.
+     */
+    compileIndexFor(index) {
+        if (!index.predicate)
+            return undefined;
+        let compiled = this.indexPredicateCache.get(index);
+        if (!compiled) {
+            compiled = compilePredicate(index.predicate, this.tableSchema.columns);
+            this.indexPredicateCache.set(index, compiled);
+        }
+        return compiled;
+    }
     /** Check if two PK arrays are equal. */
     keysEqual(a, b) {
         if (a.length !== b.length)
@@ -790,8 +1128,12 @@ export class StoreTable extends VirtualTable {
      *
      * Reads through the transaction coordinator's pending writes when active so
      * intra-transaction duplicates are detected.
+     *
+     * REPLACE evictions (rows at OTHER PKs) are deleted from storage and pushed onto
+     * `evicted` so the DML executor runs the full delete pipeline for each
+     * (change-tracking, row-time MV maintenance, FK cascade, auto-events).
      */
-    async checkUniqueConstraints(inTransaction, newRow, selfPks, onConflict) {
+    async checkUniqueConstraints(inTransaction, newRow, selfPks, onConflict, evicted) {
         const schema = this.tableSchema;
         const uniqueConstraints = schema.uniqueConstraints;
         if (!uniqueConstraints || uniqueConstraints.length === 0)
@@ -804,7 +1146,15 @@ export class StoreTable extends VirtualTable {
             const predicate = this.compileFor(uc);
             if (predicate && predicate.evaluate(newRow) !== true)
                 continue;
-            const conflict = await this.findUniqueConflict(uc, predicate, newRow, selfPks);
+            // 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);
             if (!conflict)
                 continue;
             // Resolve action per-constraint: statement OR > per-UC default > ABORT.
@@ -814,6 +1164,13 @@ export class StoreTable extends VirtualTable {
             }
             if (effective === ConflictResolution.REPLACE) {
                 await this.deleteRowAt(inTransaction, conflict.pk, conflict.row);
+                // Report the eviction so the executor runs its full delete pipeline —
+                // including the row-time covering-structure maintenance that drops the
+                // evicted source row's backing entry within this statement (else a later
+                // same-UC row sees a phantom). The executor processes the eviction before
+                // the writing row's own bookkeeping, so the backing delete still lands
+                // mid-statement.
+                evicted.push(conflict.row);
                 continue;
             }
             const colNames = uc.columns.map(i => schema.columns[i].name).join(', ');
@@ -834,18 +1191,25 @@ export class StoreTable extends VirtualTable {
      */
     async findUniqueConflict(uc, predicate, newRow, selfPks) {
         const store = await this.ensureStore();
+        // Pending ops for THIS table's data store handle — the same handle the
+        // write path queues data ops under, so the merge sees only this table's
+        // pending state, never a sibling table's on the shared module coordinator.
         const pending = this.coordinator?.isInTransaction()
             ? this.coordinator.getPendingOpsForStore(store)
             : null;
         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);
         const matches = (candidate) => {
             const pk = this.extractPK(candidate);
             for (const skip of selfPks) {
                 if (this.keysEqual(pk, skip))
                     return null;
             }
-            for (const idx of constrainedCols) {
-                if (compareSqlValues(newRow[idx], candidate[idx]) !== 0)
+            for (let i = 0; i < constrainedCols.length; i++) {
+                const idx = constrainedCols[i];
+                if (compareSqlValues(newRow[idx], candidate[idx], collations[i]) !== 0)
                     return null;
             }
             // Partial UNIQUE: candidate must also be in the predicate's scope to conflict.
@@ -877,6 +1241,269 @@ export class StoreTable extends VirtualTable {
         }
         return null;
     }
+    /**
+     * Find a UNIQUE conflict through a linked row-time covering MV's backing table
+     * (the store analogue of the memory `checkUniqueViaMaterializedView`). The
+     * backing scan yields candidate conflicting **source** PKs (reads-own-writes via
+     * the backing's coordinated connection); each is validated against the *live*
+     * store row (committed + this transaction's pending overlay) so a backing entry
+     * that lags a row deleted/updated internally this statement is skipped rather
+     * than raised as a false conflict. Returns the first real conflict or null.
+     */
+    async findUniqueConflictViaCoveringMv(mv, uc, predicate, newRow, selfPks) {
+        const newSourcePk = this.extractPK(newRow);
+        const collations = uniqueEnforcementCollations(this.tableSchema, uc);
+        const candidates = await this.db._lookupCoveringConflicts(mv, uc, newRow, newSourcePk);
+        for (const cand of candidates) {
+            const liveRow = await this.readLiveRowByPk(cand.pk);
+            if (!liveRow)
+                continue; // stale backing candidate (source row gone)
+            if (selfPks.some(pk => this.keysEqual(pk, cand.pk)))
+                continue;
+            // Re-validate under each column's enforcement collation (the index's
+            // per-column COLLATE for an index-derived UNIQUE, else declared) — see
+            // uniqueEnforcementCollations. The candidate generation
+            // (_lookupCoveringConflicts) narrows under the SOURCE column's declared
+            // collation, so for a FINER index (BINARY over a NOCASE column) it returns a
+            // superset this filters down correctly. A finer/incomparable index-derived
+            // UNIQUE whose declared candidate set could be a SUBSET (e.g. a coarser NOCASE
+            // 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))
+                continue;
+            if (predicate && predicate.evaluate(liveRow) !== true)
+                continue;
+            return { pk: cand.pk, row: liveRow };
+        }
+        return null;
+    }
+    /**
+     * Read the live row at `pk` — this transaction's pending overlay (a pending
+     * delete ⇒ gone; a pending put ⇒ its value) shadowing the committed store.
+     * Backs `query()`'s point-lookup arm and validates covering-MV conflict
+     * candidates against the source of truth.
+     */
+    async readLiveRowByPk(pk) {
+        return this.readEffectiveRowByKey(this.encodeDataKey(pk));
+    }
+    // ── Backing-host surface ──────────────────────────────────────────────
+    // Narrow public surface `StoreBackingHost` (backing-host.ts) drives. Each
+    // method addresses the table's CURRENT schema/encoding state, so a host
+    // resolved fresh per engine call always keys and merges consistently with
+    // the table's own read/write paths.
+    /** Encode `pkValues` (in PK-definition order) exactly as the data store keys rows. */
+    encodeDataKey(pkValues) {
+        return buildDataKey(pkValues, this.encodeOptions, this.pkDirections, this.pkKeyCollations);
+    }
+    /**
+     * Byte bounds covering every data key whose leading PK columns equal
+     * `prefixValues` — encoded under the same per-column DESC directions and key
+     * collations as {@link encodeDataKey}, so seek + early-terminate addresses the
+     * exact slice. An empty prefix yields full-scan bounds.
+     */
+    encodePkPrefixBounds(prefixValues) {
+        return buildPkPrefixBounds(prefixValues, this.encodeOptions, this.pkDirections.slice(0, prefixValues.length), this.pkKeyCollations.slice(0, prefixValues.length));
+    }
+    /**
+     * Effective (pending-over-committed) point read by encoded data key: a pending
+     * delete ⇒ null, a pending put ⇒ its value, else the committed store entry.
+     */
+    async readEffectiveRowByKey(key) {
+        const store = await this.ensureStore();
+        // Pending ops for THIS table's data store handle — see findUniqueConflict.
+        const pending = this.coordinator?.isInTransaction()
+            ? this.coordinator.getPendingOpsForStore(store)
+            : null;
+        if (pending) {
+            const hex = bytesToHex(key);
+            if (pending.deletes.has(hex))
+                return null;
+            const overlay = pending.puts.get(hex);
+            if (overlay)
+                return deserializeRow(overlay.value);
+        }
+        const value = await store.get(key);
+        return value ? deserializeRow(value) : null;
+    }
+    /**
+     * Effective ordered entry scan within `bounds` (see {@link iterateEffective}).
+     * Opens the data store first — which fires the lazy first-access `saveTableDDL`
+     * for a freshly created table, the catalog write a store-backed MV backing
+     * relies on to survive reopen.
+     */
+    async *iterateEffectiveEntries(bounds, reverse = false) {
+        const store = await this.ensureStore();
+        yield* this.iterateEffective(store, bounds, reverse);
+    }
+    /** Buffer a privileged row-count delta, applied at coordinator commit (host writes). */
+    trackPrivilegedMutation(delta) {
+        this.trackMutation(delta, true);
+    }
+    /**
+     * 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
+     * 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
+     * false-positive when the derived set moves a unique value between primary
+     * keys), and checking only the WRITTEN images is complete (pre-existing
+     * contents already satisfied the constraint).
+     *
+     * Reuses {@link findUniqueConflict} — pending-overlay reads, per-column
+     * collations, NULL-pass, partial-predicate scope, self-PK exclusion — with
+     * the covering-MV route deliberately bypassed: a covering MV over THIS table
+     * is cascade-maintained only after the batch returns, so it lags the batch
+     * 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.
+     *
+     * Zero overhead when the table declares no secondary UNIQUE (every MV-sugar
+     * backing, and most maintained tables): one empty-array check.
+     */
+    async enforceSecondaryUniqueForMaintenance(changes) {
+        const schema = this.tableSchema;
+        const ucs = schema?.uniqueConstraints;
+        if (!schema || !ucs || ucs.length === 0 || changes.length === 0)
+            return;
+        for (const change of changes) {
+            if (change.op === 'delete')
+                continue;
+            const newRow = change.newRow;
+            const selfPks = [this.extractPK(newRow)];
+            for (const uc of ucs) {
+                // SQL semantics: UNIQUE allows multiple NULLs.
+                if (uc.columns.some(idx => newRow[idx] === null))
+                    continue;
+                // Partial UNIQUE: an out-of-scope image contributes nothing.
+                const predicate = this.compileFor(uc);
+                if (predicate && predicate.evaluate(newRow) !== true)
+                    continue;
+                const conflict = await this.findUniqueConflict(uc, predicate, newRow, selfPks);
+                if (conflict) {
+                    const colNames = uc.columns.map(i => schema.columns[i]?.name ?? String(i));
+                    throw maintainedTableUniqueViolationError(schema.schemaName, schema.name, uc.name ?? `_uc_${colNames.join('_')}`, colNames, uc.columns.map(i => newRow[i]));
+                }
+            }
+        }
+    }
+    /**
+     * Reset statistics to an absolute committed row count and flush immediately.
+     * Used by the host's `replaceContents` (create-fill / refresh), where the new
+     * count is exact, replacing any drifted delta-tracked estimate.
+     */
+    async resetStats(rowCount) {
+        this.cachedStats = { rowCount, updatedAt: Date.now() };
+        this.pendingStatsDelta = 0;
+        this.mutationCount = 0;
+        await this.flushStats();
+    }
+    /**
+     * Open (and cache) the data store, firing the lazy first-access `saveTableDDL`.
+     * Public for the host's `replaceContents`, which writes the store directly.
+     */
+    openDataStore() {
+        return this.ensureStore();
+    }
+    // ── External row-write surface ────────────────────────────────────────
+    // Module-side entry point for externally-applied writes to a SOURCE table
+    // (the index-maintaining sibling of `StoreBackingHost`, which is for MV
+    // BACKING tables and deliberately keeps no indexes). Resolved per call via
+    // `StoreModule.getTableForExternalWrite`; addresses the table's CURRENT
+    // schema/encoding state so keys and index entries match its own DML paths.
+    /**
+     * Effective (pending-over-committed) point read by PK values — the public
+     * read an external writer issues before an upsert to learn the row's current
+     * image. Thin wrapper over the same private point-lookup that backs
+     * {@link query}'s point arm, so an external read merges pending-over-committed
+     * exactly like an engine read does.
+     */
+    readRowByPk(pk) {
+        return this.readLiveRowByPk(pk);
+    }
+    /**
+     * Apply externally-originated row ops directly to this source table's
+     * COMMITTED storage: table-owned data-key put/delete, secondary-index
+     * maintenance, and stats tracking. The index-maintaining counterpart of
+     * `StoreBackingHost.applyMaintenance` (which targets index-less MV backings),
+     * built for trusted replication-style writes.
+     *
+     * Deliberately:
+     *   - emits NO module {@link DataChangeEvent}s — the external writer owns
+     *     emission and the `remote` flag;
+     *   - opens NO coordinator transaction — writes land in committed state
+     *     immediately (`store.put`/`store.delete`, never the coordinator);
+     *   - runs NO constraint validation (PK/UNIQUE/CHECK/FK) — the origin is
+     *     trusted, mirroring the backing-host posture.
+     *
+     * Returns the EFFECTIVE per-op {@link BackingRowChange}s with accurate
+     * before-images (the shape `Database.ingestExternalRowChanges` consumes),
+     * suppressing no-ops to match the normative upsert-suppression contract in
+     * `vtab/backing-host.ts`: a delete of an absent key, and a value-identical
+     * upsert (`rowsValueIdentical` — byte-faithful, collation-UNAWARE, against the
+     * effective existing row) write nothing and report nothing. A collation-equal /
+     * byte-different upsert (e.g. a case-only rewrite under a NOCASE PK) keeps the
+     * SAME data key (key identity is collation-aware) but IS a real update that
+     * replaces the stored bytes and reports `update`.
+     *
+     * Last-writer-wins against any concurrently pending local transaction on this
+     * table: the external write commits to storage at once, and that transaction's
+     * pending batch may overwrite these keys when it commits. This is the same
+     * posture the prior raw-KV sync adapter took — not a regression, now stated.
+     */
+    async applyExternalRowChanges(ops) {
+        const changes = [];
+        if (ops.length === 0)
+            return changes;
+        // Route through the lazy store-open path so the first external write to a
+        // freshly created table persists its DDL exactly like a first vtab write.
+        const store = await this.ensureStore();
+        for (const op of ops) {
+            switch (op.op) {
+                case 'delete': {
+                    const key = this.encodeDataKey(op.pk);
+                    const existing = await this.readEffectiveRowByKey(key);
+                    if (!existing)
+                        break; // absent key → no storage/index/stats op, nothing reported
+                    await store.delete(key);
+                    await this.updateSecondaryIndexes(false, existing, null, op.pk);
+                    this.trackMutation(-1, false);
+                    changes.push({ op: 'delete', oldRow: existing });
+                    break;
+                }
+                case 'upsert': {
+                    const pk = this.extractPK(op.row);
+                    const key = this.encodeDataKey(pk);
+                    const existing = await this.readEffectiveRowByKey(key);
+                    if (existing && rowsValueIdentical(existing, op.row)) {
+                        // Byte-identical to the effective row → a true no-op: no write, no
+                        // index touch, no stats delta, nothing reported (echo-prevention seam).
+                        break;
+                    }
+                    await store.put(key, serializeRow(op.row));
+                    // PK derives from the row, so the key never relocates: oldPk == newPk.
+                    await this.updateSecondaryIndexes(false, existing, op.row, pk);
+                    if (!existing)
+                        this.trackMutation(+1, false);
+                    changes.push(existing
+                        ? { op: 'update', oldRow: existing, newRow: op.row }
+                        : { op: 'insert', newRow: op.row });
+                    break;
+                }
+                default: {
+                    // A new ExternalRowOp variant must extend this switch; never-assignment
+                    // makes that a compile error rather than a silent no-op.
+                    const exhaustiveCheck = op;
+                    throw new QuereusError(`Unknown external row op: ${JSON.stringify(exhaustiveCheck)}`, StatusCode.INTERNAL);
+                }
+            }
+        }
+        return changes;
+    }
     /**
      * Fully delete the row at `pk` (data + secondary indexes + stats + delete event).
      * Used by REPLACE conflict resolution to evict a conflicting unique row before
@@ -884,9 +1511,9 @@ export class StoreTable extends VirtualTable {
      */
     async deleteRowAt(inTransaction, pk, oldRow) {
         const store = await this.ensureStore();
-        const key = buildDataKey(pk, this.encodeOptions, this.pkDirections);
+        const key = buildDataKey(pk, this.encodeOptions, this.pkDirections, this.pkKeyCollations);
         if (inTransaction && this.coordinator) {
-            this.coordinator.delete(key);
+            this.coordinator.delete(key, store);
         }
         else {
             await store.delete(key);
@@ -949,6 +1576,32 @@ export class StoreTable extends VirtualTable {
         // Store remains available for subsequent queries.
         // Use destroy() to fully clean up the table.
     }
+    /**
+     * Hard teardown: fully detach this instance from the module-wide coordinator.
+     *
+     * Distinct from the per-scan {@link disconnect} (which only flushes stats and
+     * deliberately keeps the table hooked mid-life). Called ONLY at the genuine
+     * eviction sites — `StoreModule.tearDownTableStorage` (drop / reclaim) and
+     * `renameTable` — where this instance is removed from the module's `tables` map
+     * and will never be used again. It best-effort flushes any buffered stats (the
+     * backing store is about to be deleted / relocated, so this is the last chance,
+     * same posture as the teardown-time `disconnect` it replaces), then runs the
+     * coordinator disposer so this instance's {stats apply/discard} callback pair —
+     * and the `this` its closures capture — is spliced off the shared coordinator's
+     * array rather than pinned for the module's lifetime.
+     *
+     * Idempotent: the disposer is run at most once and both it and the coordinator
+     * reference are nulled, so a double-dispose is a no-op and a re-`attachCoordinator`
+     * after dispose registers a fresh pair instead of double-registering.
+     */
+    async dispose() {
+        if (this.mutationCount > 0 && this.store) {
+            await this.flushStats();
+        }
+        this.coordinatorDisposer?.();
+        this.coordinatorDisposer = null;
+        this.coordinator = null;
+    }
     /** Get the current estimated row count. */
     async getEstimatedRowCount() {
         if (this.cachedStats) {