@quereus/isolation 4.4.0 → 4.5.0

package/README.md

@@ -1,5 +1,9 @@
 # @quereus/isolation
 
+> **Stability: Beta** — complete and tested, but the surface is still being shaped; a
+> breaking change may land in a minor release. See
+> [Stability Tiers](../../docs/stability.md#tiers).
+
 Generic transaction isolation layer for Quereus virtual table modules.
 
 ## Overview
@@ -80,6 +84,30 @@ The isolation layer operates at the **row level**, merging query results from tw
 └─────────────────────────────────────────────────────────┘
 ```
 
+### Reading a pushed index window
+
+When the underlying serves a read through an index seek, the overlay must be narrowed to
+the same window — otherwise a staged row outside it would leak into the answer. The
+overlay is full-scanned (it cannot resolve an index name the underlying minted for its own
+plan), and `IsolatedTable`'s constraint matcher re-applies the pushed window itself. Several
+equality constraints on the *same* column are read as an **IN set**, not as an AND: that is
+how an `IN`-list seek is encoded — one equality per seek value — so an AND reading would
+match nothing and silently drop every staged row.
+
+This holds for a set of values that only exists at run time (`where v in (select …)`,
+which the engine may materialize and push down as a seek) exactly as it does for a literal
+`in (1, 2, 3)`: the pushed window has the same shape either way, and this layer cannot —
+and need not — tell them apart.
+
+One ordering caveat. The **primary-key** merge walks both streams in the primary key's own
+declared order — ascending, or descending for a `primary key (… desc)`. The engine sorts a
+run-time key set into that same order before pushing it, so that path arrives in order. A
+**literal** list does not: `where pk in (3, 1, 2)` is visited in list order, and with rows
+staged in the transaction the merge mis-pairs them — a staged update can surface alongside
+the stale stored row, and a staged delete can reappear. That is tracked as
+`backlog/bug-isolation-multiseek-merge-order`; the secondary-index merge is unaffected
+(it sorts the overlay itself and excludes shadowed rows by primary key).
+
 ## Isolation Level
 
 The guarantee this layer actually provides is closer to **read-committed with
@@ -106,11 +134,13 @@ read-your-own-writes** than to snapshot isolation:
 
 **Lazy overlay creation** — No memory overhead until the first write in a transaction.
 
-**Transparent hook forwarding** — `IsolationModule` is a wrapper, so the engine/planner/lens machinery reaches *it* (the registered module) rather than the underlying. Optional `VirtualTableModule` hooks whose behavior is isolation-transparent are forwarded straight through to the underlying: `getMappingAdvertisements` (decomposition shape), `getBestAccessPlan` (index awareness), the `beginSchemaBatch` / `endSchemaBatch` APPLY SCHEMA batch hooks (single-substrate-commit batching of migration DDL), and `getBackingHost` (the materialized-view backing-host capability — assigned in the constructor only when the underlying implements it, so method *presence* mirrors the underlying; backing writes are privileged and bypass the per-connection overlay entirely, making the underlying host's pending state the right surface). Hooks whose underlying value would *misdescribe* the wrapped behavior are intentionally **not** forwarded: `getCapabilities` is augmented with `isolation`/`savepoints` rather than passed through verbatim; `supports` (full-query push-down) is suppressed so the overlay always sees every row to merge; and `concurrencyMode` / `expectedLatencyMs` are derived rather than passed through verbatim: `concurrencyMode` is the weaker of the underlying and overlay modes, capped at `reentrant-reads` (the wrapper's own write path mutates shared overlay-merge state non-atomically, so it is never `fully-reentrant`), while `expectedLatencyMs` forwards the underlying's hint (defaulting to `0` when the underlying declares none).
+**Transparent hook forwarding** — `IsolationModule` is a wrapper, so the engine/planner/lens machinery reaches *it* (the registered module) rather than the underlying. Optional `VirtualTableModule` hooks whose behavior is isolation-transparent are forwarded straight through to the underlying: `getMappingAdvertisements` (decomposition shape), `getBestAccessPlan` (index awareness), the `beginSchemaBatch` / `endSchemaBatch` APPLY SCHEMA batch hooks (single-substrate-commit batching of migration DDL), `assertCatalogObjectPersistable` (the pre-flight veto that lets a persisting module refuse a view / materialized view whose catalog entry it could not durably write — whether a definition is encodable is a property of the definition text, not of the overlay, and without the forward a wrapped store would silently keep dropping such views on reopen), and `getBackingHost` (the materialized-view backing-host capability — assigned in the constructor only when the underlying implements it, so method *presence* mirrors the underlying; backing writes are privileged and bypass the per-connection overlay entirely, making the underlying host's pending state the right surface). Hooks whose underlying value would *misdescribe* the wrapped behavior are intentionally **not** forwarded: `getCapabilities` is augmented with `isolation`/`savepoints` rather than passed through verbatim; `supports` (full-query push-down) is suppressed so the overlay always sees every row to merge; and `concurrencyMode` / `expectedLatencyMs` are derived rather than passed through verbatim: `concurrencyMode` is the weaker of the underlying and overlay modes, capped at `reentrant-reads` (the wrapper's own write path mutates shared overlay-merge state non-atomically, so it is never `fully-reentrant`), while `expectedLatencyMs` forwards the underlying's hint (defaulting to `0` when the underlying declares none).
 
 **Atomic ALTER (issuer-faithful) + cross-connection poison** — DDL through Quereus is not transaction-scoped and the shared underlying base auto-commits its mutation immediately, so a half-applied ALTER cannot be rolled back. The blast radius is isolation-faithful — an ALTER never depends on another connection's uncommitted data:
 
 - **Issuer's own overlay** — `IsolationModule.alterTable` dry-run **validates the issuing connection's own affected overlay's backfill** (per-row `NOT NULL` checks — for a new `ADD COLUMN ... NOT NULL` and for tightening an existing column with `ALTER COLUMN ... SET NOT NULL` — and the tombstone-present guard) *before* mutating the underlying. A rejection fires while the underlying, the schema catalog, and every overlay are still untouched, so for the issuer the ALTER either fails clean or fully applies — base and catalog never diverge. (The issuer staged both the data and the DDL, so rejecting up front is the least-surprising behavior.)
+- **`ALTER TABLE ... ALTER COLUMN ... SET COLLATE` on a primary-key column** — the change re-keys the table, so two staged rows can land on one new key. A deletion marker sharing its new key with a staged live row is that row's before-image (delete `'A'`, insert `'a'`, then switch to `NOCASE`), so the marker is discarded and the ALTER succeeds; two staged **live** rows on one key are a real duplicate and are refused. A shape the re-keyed overlay cannot physically hold — a savepoint that could restore both a marker and its replacement at one key — is refused as retryable (`BUSY`), the same answer a plain non-isolated table gives. Every refusal is surfaced *before* the shared underlying is touched, so the transaction survives intact.
+- **`ALTER TABLE ... ALTER PRIMARY KEY`** — the one change no overlay can follow: an overlay's staged rows (and its deletion markers) are keyed by the *old* primary key. A connection that has uncommitted changes staged for the table is therefore rejected with `UNSUPPORTED` *before* the underlying is touched — commit or roll back first, then retry. Another connection's overlay holding staged rows is poisoned; one holding nothing is swapped for an empty overlay under the new key. (The bundled `MemoryTableModule` rejects `ALTER PRIMARY KEY` outright, so this only arises under a store-backed underlying.)
 - **Another connection's overlay** — the shared underlying and the catalog change regardless of any *other* connection's uncommitted state. A foreign overlay that *can* migrate is carried forward as usual (a staged `NULL` is backfilled when a usable literal `DEFAULT` exists); one that *cannot* (its staged row can't satisfy the new or newly-`NOT NULL` column) is left in place and marked **poisoned**. Its owning connection then raises a `CONSTRAINT` error the next time it reads (merged), writes, or commits that table, and recovers by rolling back (which discards the overlay and its poison). A committed-snapshot (`committed.<table>`) read bypasses the overlay and keeps working. A layer-invariant violation (e.g. a missing tombstone column, `INTERNAL`) still rethrows loud for everyone rather than poisoning.
 
 **Configurable overlay module** — Use memory for fast transactions, or persistent storage for large transactions:

package/dist/src/flush.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flush.d.ts","sourceRoot":"","sources":["../../src/flush.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAKpF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,wBAAwB,CAC7C,eAAe,EAAE,YAAY,EAC7B,YAAY,EAAE,YAAY,EAC1B,eAAe,EAAE,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CA2Df;AAkBD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAOlH"}
+{"version":3,"file":"flush.d.ts","sourceRoot":"","sources":["../../src/flush.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAKpF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,wBAAwB,CAC7C,eAAe,EAAE,YAAY,EAC7B,YAAY,EAAE,YAAY,EAC1B,eAAe,EAAE,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAwEf;AAkBD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAOlH"}

package/dist/src/flush.js

@@ -47,6 +47,20 @@ export async function applyOverlayToUnderlying(underlyingTable, overlayTable, to
         return;
     // Deletes before inserts/updates (see doc comment above).
     const ordered = [...overlayEntries].sort((a, b) => (a.isTombstone === b.isTombstone ? 0 : a.isTombstone ? -1 : 1));
+    // Resolve insert-vs-update for every live row BEFORE any write of this flush
+    // lands. `rowExistsInUnderlying` drives the underlying's PK index, and a
+    // module whose read path cannot serve an index-driven scan over its own
+    // uncommitted writes fails every probe after the first (lamina's
+    // staged-overlay wrapper refuses a compound-index scan once the episode holds
+    // staged drafts). Each PK appears at most once in the overlay, so no write in
+    // this flush can change another entry's existence answer — hoisting the
+    // probes is answer-preserving as well as one fewer read per written row.
+    const existsInUnderlying = new Map();
+    for (const entry of ordered) {
+        if (entry.isTombstone)
+            continue;
+        existsInUnderlying.set(entry, await rowExistsInUnderlying(underlyingTable, pkIndices, entry.pk));
+    }
     for (const entry of ordered) {
         if (entry.isTombstone) {
             const result = await underlyingTable.update({
@@ -57,9 +71,8 @@ export async function applyOverlayToUnderlying(underlyingTable, overlayTable, to
             assertFlushWriteOk(result, 'delete', entry.pk, tableName);
         }
         else {
-            // Insert vs update decided by whether the row already exists underlying.
-            const existsInUnderlying = await rowExistsInUnderlying(underlyingTable, pkIndices, entry.pk);
-            if (existsInUnderlying) {
+            // Insert vs update decided by the pre-write probe above.
+            if (existsInUnderlying.get(entry) === true) {
                 const result = await underlyingTable.update({
                     operation: 'update',
                     values: entry.dataRow,

package/dist/src/flush.js.map

@@ -1 +1 @@
-{"version":3,"file":"flush.js","sourceRoot":"","sources":["../../src/flush.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"flush.js","sourceRoot":"","sources":["../../src/flush.ts"],"names":[],"mappings":"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"}

package/dist/src/isolated-table.d.ts

@@ -54,6 +54,16 @@ export declare class IsolatedTable extends VirtualTable implements IsolatedTable
      * which invalidates the entry.
      */
     private pkCollationCache?;
+    /**
+     * Per-PK-column typed EQUALITY comparators for semantic-ordering members (TIMESPAN,
+     * JSON — see the engine's `hasSemanticOrdering`), `undefined` elsewhere. The
+     * underlying backends collapse semantically-equal PK spellings onto one row (the
+     * memory table's typed BTree; the store's `groupKey`-transformed key bytes), so
+     * shadowing and self-PK questions here must call 'PT1H' and 'PT60M' the same key
+     * too. Memoized against the schema object like {@link pkCollationCache}.
+     */
+    private pkSemanticCache?;
+    private getPkSemanticComparators;
     /**
      * 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
@@ -492,12 +502,14 @@ export declare class IsolatedTable extends VirtualTable implements IsolatedTable
     /**
      * 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
+     * comparison function (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
+     * `compares` carries one function per constrained column, resolved once in
+     * {@link findMergedUniqueConflict}: the type's `compare` for a semantic-ordering
+     * column, else the enforcement collation (the index's per-column COLLATE for an
+     * index-derived UNIQUE, else the declared column collation) — the latter enforces
+     * a UNIQUE over a collated column against merged rows through the isolation path
      * (unique-constraint-honors-column-collation / store-index-derived-unique).
      */
     private rowMatchesUniqueConstraint;
@@ -550,11 +562,13 @@ export declare class IsolatedTable extends VirtualTable implements IsolatedTable
     /**
      * 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.
+     * connection's effective rows, then adopting the change IN PLACE into every affected
+     * overlay (narrowed to live rows, and with a foreign overlay's rejection poisoning it
+     * rather than losing its staged rows) — 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.
      */
     createIndex(indexInfo: IndexSchema, rows?: EffectiveRowSource): Promise<void>;
     dropIndex(indexName: string): Promise<void>;

package/dist/src/isolated-table.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"isolated-table.d.ts","sourceRoot":"","sources":["../../src/isolated-table.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"isolated-table.d.ts","sourceRoot":"","sources":["../../src/isolated-table.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAwC,QAAQ,EAAoB,YAAY,EAAE,GAAG,EAAY,gBAAgB,IAAI,WAAW,EAAE,UAAU,EAAE,gBAAgB,EAA0D,UAAU,EAAE,sBAAsB,EAAE,YAAY,EAA+C,MAAM,kBAAkB,CAAC;AAC5V,OAAO,EAAE,YAAY,EAA+d,MAAM,kBAAkB,CAAC;AAC7gB,OAAO,KAAK,EAAE,kBAAkB,EAAyB,MAAM,kBAAkB,CAAC;AAClF,OAAO,KAAK,EAAE,eAAe,EAA0B,MAAM,uBAAuB,CAAC;AACrF,OAAO,EAAsB,KAAK,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAe1F;;;;;;;;;;;;;;GAcG;AACH,qBAAa,aAAc,SAAQ,YAAa,YAAW,qBAAqB;IAC/E,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAe;IAC/C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAU;IAExC,OAAO,CAAC,oBAAoB,CAAmC;IAE/D;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqE;IAEpG;;;;;;;;;OASG;IACH,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAoB;IAEtD;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAwB;IAE9D;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB,CAAC,CAAiF;IAE1G;;;;;;;OAOG;IACH,OAAO,CAAC,eAAe,CAAC,CAA+F;IAEvH,OAAO,CAAC,wBAAwB;IAehC;;;;;;;;;;;;;;OAcG;IACH,OAAO,KAAK,uBAAuB,GAElC;IAED;;;;;;;;;;;OAWG;gBAEF,EAAE,EAAE,QAAQ,EACZ,MAAM,EAAE,eAAe,EACvB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,YAAY,EAC7B,aAAa,GAAE,OAAe;IAa/B;;OAEG;IACH,OAAO,KAAK,eAAe,GAE1B;IAED;;OAEG;IACH,OAAO,CAAC,eAAe;IAIvB;;;;;;;;;OASG;IACH,OAAO,CAAC,mBAAmB;IAO3B;;OAEG;IACH,OAAO,KAAK,YAAY,GAEvB;IAED;;OAEG;IACH,OAAO,KAAK,UAAU,GAErB;IAED;;OAEG;IACH,OAAO,CAAC,aAAa;IAOrB;;;;;;;;OAQG;YACW,aAAa;IAoD3B;;;;;;;;;;;;;;;;;;;;OAoBG;YACW,gBAAgB;IAY9B;;;;;;;;;;;;OAYG;YACW,eAAe;IAsC7B;;;;OAIG;IACH,gBAAgB,IAAI,YAAY,CAAC,sBAAsB,CAAC;YAkB1C,qBAAqB;IAanC;;;;;;;;OAQG;IACH,KAAK,CAAC,UAAU,EAAE,UAAU,GAAG,aAAa,CAAC,GAAG,CAAC;IAqBjD;;OAEG;YACY,yBAAyB;IAKxC;;;;;;;;;OASG;YACY,WAAW;IAsB1B;;;;;;;;;;;;;;;;;;OAkBG;YACY,yBAAyB;IA+GxC;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,gBAAgB;IA6CxB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,yBAAyB;IAQjC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,OAAO,CAAC,sBAAsB;IAiE9B;;;;;OAKG;IACH,OAAO,CAAC,4BAA4B;IA6CpC;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAM3B;;;;;OAKG;YACY,0BAA0B;IA8BzC;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IAWpB;;;;;;;OAOG;IACH,OAAO,CAAC,gBAAgB;IAgDxB;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,eAAe;IAIvB;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,aAAa;IAcrB;;OAEG;IACH,OAAO,CAAC,YAAY;IA+BpB;;;;;;OAMG;IACH,OAAO,CAAC,0BAA0B;IAgBlC;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAqB3B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAY/B;;OAEG;IACH,oBAAoB,IAAI,MAAM,EAAE;IAMhC;;;;;;;OAOG;IACH,OAAO,CAAC,SAAS;IAMjB;;;;;OAKG;IACG,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,CAAC;IA8QrD;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAsBhC;;;;;OAKG;IACH,OAAO,CAAC,wBAAwB;IAMhC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,aAAa;IAQrB;;OAEG;YACW,aAAa;IAS3B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAIhC;;;OAGG;IACH,OAAO,CAAC,wBAAwB;IAMhC;;;;OAIG;IACH,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,SAAS;YAoBH,gBAAgB;IAQ9B;;;;;;;;;;;;;;;;OAgBG;YACW,iBAAiB;YA0BjB,oBAAoB;IAiBlC;;;;;;;;;;;OAWG;YACW,qBAAqB;IA0BnC;;;;;;;;;;;;;;;;;;;;OAoBG;YACW,wBAAwB;IAyBtC;;;;;;;OAOG;YACW,yBAAyB;IAyBvC;;;;;;;OAOG;YACW,4BAA4B;IAiC1C;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,0BAA0B;IAiBlC;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,oBAAoB;IAW5B;;;;;;;;;OASG;YACW,4BAA4B;IA+CpC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAKrB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAQvB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAK/B;;;;;;OAMG;YACW,YAAY;IASpB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvC,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrC,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMxC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAItC,WAAW,CAAC,UAAU,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAS9D;;;;;;;;;;OAUG;IACG,WAAW,CAAC,SAAS,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAK7E,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwBjD;;OAEG;IACH,iBAAiB,IAAI,OAAO;IAc5B;;;OAGG;IACG,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC;IAczC;;;OAGG;IACG,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC;IAK3C;;;;;;;;;;;OAWG;IACG,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOzD;;OAEG;IACG,4BAA4B,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKhE;;;;;;OAMG;IACG,+BAA+B,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAanE"}

package/dist/src/isolated-table.js

@@ -1,4 +1,4 @@
-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 { VirtualTable, compareSqlValues, compareSqlValuesFast, resolveCollationFunctions, BINARY_COLLATION, isUpdateOk, ConflictResolution, compilePredicate, QuereusError, StatusCode, resolveUniqueEnforcementCollations, uniqueEnforcementCollations, uniqueEnforcementComparators, normalizeCollationName, serializeKey, pkKeyCollationName, retargetFilterInfoIndex, PRIMARY_INDEX_NAME, coerceRowToSchema, IndexConstraintOp, decodeIdxStr, createTypedComparator, hasSemanticOrdering, semanticKeyTransform } 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';
@@ -55,6 +55,30 @@ export class IsolatedTable extends VirtualTable {
      * which invalidates the entry.
      */
     pkCollationCache;
+    /**
+     * Per-PK-column typed EQUALITY comparators for semantic-ordering members (TIMESPAN,
+     * JSON — see the engine's `hasSemanticOrdering`), `undefined` elsewhere. The
+     * underlying backends collapse semantically-equal PK spellings onto one row (the
+     * memory table's typed BTree; the store's `groupKey`-transformed key bytes), so
+     * shadowing and self-PK questions here must call 'PT1H' and 'PT60M' the same key
+     * too. Memoized against the schema object like {@link pkCollationCache}.
+     */
+    pkSemanticCache;
+    getPkSemanticComparators() {
+        const schema = this.tableSchema;
+        if (!schema)
+            return [];
+        if (this.pkSemanticCache?.schema !== schema) {
+            this.pkSemanticCache = {
+                schema,
+                comparators: (schema.primaryKeyDefinition ?? []).map(pk => {
+                    const logicalType = schema.columns[pk.index]?.logicalType;
+                    return hasSemanticOrdering(logicalType) ? createTypedComparator(logicalType) : undefined;
+                }),
+            };
+        }
+        return this.pkSemanticCache.comparators;
+    }
     /**
      * 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
@@ -386,7 +410,7 @@ export class IsolatedTable extends VirtualTable {
         // 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
+        // normalizer regardless of its collation: the key serializer 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
@@ -398,6 +422,18 @@ export class IsolatedTable extends VirtualTable {
             const column = this.tableSchema.columns[i];
             return this.keyNormalizerResolver(pkKeyCollationName(column));
         });
+        // Key-identity transforms for semantic-ordering PK members (TIMESPAN's total-seconds
+        // groupKey): the underlying backends key 'PT1H' and 'PT60M' as ONE row, so the
+        // modified-PK shadow set must bucket them identically or a staged rewrite fails to
+        // shadow the committed spelling and both rows surface. `!` on the serialized key is
+        // safe: PK columns are NOT NULL, so serializeKey never returns null; both the build
+        // and probe below use this one encoder so they stay consistent.
+        const pkTransforms = pkIndices.map(i => semanticKeyTransform(this.tableSchema.columns[i]?.logicalType));
+        const pkShadowKey = (row) => serializeKey(pkIndices.map((idx, i) => {
+            const v = row[idx];
+            const transform = pkTransforms[i];
+            return transform && v !== null ? transform(v) : v;
+        }), pkNormalizers);
         // 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
@@ -411,9 +447,7 @@ export class IsolatedTable extends VirtualTable {
         const modifiedPKs = new Set();
         const overlayRows = [];
         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));
+            modifiedPKs.add(pkShadowKey(row));
             if (row[tombstoneIndex] !== 1) {
                 const dataRow = row.slice(0, tombstoneIndex);
                 if (matchesWindow(dataRow)) {
@@ -433,8 +467,7 @@ export class IsolatedTable extends VirtualTable {
         // Merge two sorted, disjoint streams
         let oi = 0;
         for await (const underlyingRow of this.underlyingTable.query(filterInfo)) {
-            // `!` is safe for the same reason as the build loop above (PK NOT NULL).
-            if (modifiedPKs.has(serializeRowKey(underlyingRow, pkIndices, pkNormalizers))) {
+            if (modifiedPKs.has(pkShadowKey(underlyingRow))) {
                 continue; // Skip rows modified in overlay
             }
             // Yield any overlay rows that sort before this underlying row
@@ -827,11 +860,17 @@ export class IsolatedTable extends VirtualTable {
         // 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.
+        // A semantic-ordering member compares through its type's `compare` — both the
+        // memory table's typed BTree and the store's groupKey-transformed key bytes
+        // emit in that order, and its equality is what shadowing needs ('PT1H' ≡ 'PT60M').
         const collations = this.getPkCollations();
         const directions = this.getPkDirections();
+        const semantic = this.getPkSemanticComparators();
         return (a, b) => {
             for (let i = 0; i < a.length; i++) {
-                const cmp = compareSqlValuesFast(a[i], b[i], collations[i] ?? BINARY_COLLATION);
+                const cmp = semantic[i]
+                    ? semantic[i](a[i], b[i])
+                    : compareSqlValuesFast(a[i], b[i], collations[i] ?? BINARY_COLLATION);
                 if (cmp !== 0)
                     return directions[i] ? -cmp : cmp;
             }
@@ -847,9 +886,15 @@ export class IsolatedTable extends VirtualTable {
      */
     buildDescriptorComparators(keyColumns) {
         return keyColumns.map(kc => {
+            // A semantic-ordering key column merges by the type's `compare` — the order
+            // both backends emit such a column in (typed BTree / groupKey key bytes).
+            const logicalType = this.tableSchema?.columns[kc.columnIndex]?.logicalType;
             const collation = kc.collation ? this.collationResolver(kc.collation) : BINARY_COLLATION;
+            const compare = hasSemanticOrdering(logicalType)
+                ? createTypedComparator(logicalType, collation)
+                : (a, b) => compareSqlValuesFast(a, b, collation);
             return (a, b) => {
-                const cmp = compareSqlValuesFast(a, b, collation);
+                const cmp = compare(a, b);
                 return kc.desc ? -cmp : cmp;
             };
         });
@@ -908,11 +953,7 @@ export class IsolatedTable extends VirtualTable {
      * 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));
+        return coerceRowToSchema(row, this.tableSchema.columns, `${this.schemaName}.${this.tableName}`);
     }
     // ==================== Write Operations ====================
     /**
@@ -933,21 +974,22 @@ 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;
+        // The DML executor converts every row to declared column types at the top of
+        // the pipeline and says so via `preCoerced` — then `values` is already in
+        // declared form, must NOT be converted again (JSON's `parse` is not
+        // idempotent for a JSON-string scalar: `'"hello"'` parses to the native JS
+        // string `"hello"`, and re-parsing that bare string throws), and the flag is
+        // forwarded on every overlay data write below so the overlay's own memory
+        // module skips its pass too.
+        //
+        // A direct API caller that leaves the flag unset still hands us raw values:
+        // convert them here — conflict detection needs the declared 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) — but keep the OVERLAY
+        // write raw in that case (the overlay converts on its own write, and
+        // handing it the converted row without `preCoerced` would convert twice).
+        const coercedValues = values ? (args.preCoerced ? 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.
@@ -983,6 +1025,7 @@ export class IsolatedTable extends VirtualTable {
                             values: overlayRow,
                             oldKeyValues: pk,
                             onConflict: effectiveOR,
+                            preCoerced: args.preCoerced,
                         });
                         const stripped = this.stripTombstoneFromResult(result, tombstoneIndex);
                         return this.attachEvicted(stripped, evicted, tombstoneIndex);
@@ -1059,7 +1102,7 @@ export class IsolatedTable extends VirtualTable {
                         await this.insertTombstoneForPK(overlay, targetPK, tombstoneIndex);
                         // Reuse a tombstone already at newPK (a PK freed earlier in this txn)
                         // instead of colliding with it — see writeRelocatedRow.
-                        const result = await this.writeRelocatedRow(overlay, newPK, overlayRow, tombstoneIndex, effectiveOR);
+                        const result = await this.writeRelocatedRow(overlay, newPK, overlayRow, tombstoneIndex, effectiveOR, args.preCoerced);
                         const stripped = this.stripTombstoneFromResult(result, tombstoneIndex);
                         return this.attachEvicted(this.attachReplacedUnderlying(stripped, pkOutcome.replacedUnderlyingRow), evicted, tombstoneIndex);
                     }
@@ -1095,8 +1138,8 @@ export class IsolatedTable extends VirtualTable {
                     // A same-PK update has no overlay row at newPK (=== targetPK), so the
                     // helper's insert path matches the prior behavior.
                     const result = pkChanged
-                        ? await this.writeRelocatedRow(overlay, newPK, overlayRow, tombstoneIndex, effectiveOR)
-                        : await overlay.update({ operation: 'insert', values: overlayRow, onConflict: effectiveOR });
+                        ? await this.writeRelocatedRow(overlay, newPK, overlayRow, tombstoneIndex, effectiveOR, args.preCoerced)
+                        : await overlay.update({ operation: 'insert', values: overlayRow, onConflict: effectiveOR, preCoerced: args.preCoerced });
                     const stripped = this.stripTombstoneFromResult(result, tombstoneIndex);
                     return this.attachEvicted(this.attachReplacedUnderlying(stripped, replacedUnderlyingRow), evicted, tombstoneIndex);
                 }
@@ -1115,13 +1158,16 @@ export class IsolatedTable extends VirtualTable {
                         // (e.g. dml-executor auto-event path) know no actual row was removed.
                         return { status: 'ok' };
                     }
-                    // Convert to tombstone by updating the tombstone flag
+                    // Convert to tombstone by updating the tombstone flag. The row is sliced
+                    // from a row the overlay itself already wrote/coerced — mark preCoerced
+                    // so the overlay doesn't re-run (non-idempotent) JSON coercion on it.
                     const tombstoneRow = [...existingOverlayRow.slice(0, tombstoneIndex), 1];
                     await overlay.update({
                         operation: 'update',
                         values: tombstoneRow,
                         oldKeyValues: targetPK,
                         onConflict: args.onConflict,
+                        preCoerced: true,
                     });
                     // Return the pre-deletion row so dml-executor emits the auto change event.
                     const deletedRow = existingOverlayRow.slice(0, tombstoneIndex);
@@ -1138,10 +1184,14 @@ export class IsolatedTable extends VirtualTable {
                         tombstoneRow[colIdx] = targetPK[i];
                     });
                     tombstoneRow[tombstoneIndex] = 1; // Set tombstone flag
+                    // targetPK cells come from oldKeyValues (already coerced, read from the
+                    // source scan) — mark preCoerced so the overlay doesn't re-run (non-idempotent)
+                    // JSON coercion on them.
                     await overlay.update({
                         operation: 'insert',
                         values: tombstoneRow,
                         onConflict: args.onConflict,
+                        preCoerced: true,
                     });
                     // Return a minimal placeholder row (PK columns only) so dml-executor
                     // recognises the delete as successful and emits the auto change event.
@@ -1261,10 +1311,16 @@ export class IsolatedTable extends VirtualTable {
         // store keys rows collation-aware (e.g. a NOCASE text PK), so a case-only PK
         // 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.
+        // same physical underlying row and raise a false UNIQUE PK conflict. A
+        // semantic-ordering member compares through its type's `compare` for the same
+        // reason: both backends key 'PT1H' and 'PT60M' as one row.
         const collations = this.getPkCollations();
+        const semantic = this.getPkSemanticComparators();
         for (let i = 0; i < a.length; i++) {
-            if (compareSqlValuesFast(a[i], b[i], collations[i] ?? BINARY_COLLATION) !== 0)
+            const cmp = semantic[i]
+                ? semantic[i](a[i], b[i])
+                : compareSqlValuesFast(a[i], b[i], collations[i] ?? BINARY_COLLATION);
+            if (cmp !== 0)
                 return false;
         }
         return true;
@@ -1294,7 +1350,7 @@ export class IsolatedTable extends VirtualTable {
      * with a non-tombstone overlay row should not happen; if it ever does, fall
      * through to insert and let the overlay enforce the genuine conflict.
      */
-    async writeRelocatedRow(overlay, newPK, overlayRow, tombstoneIndex, effectiveOR) {
+    async writeRelocatedRow(overlay, newPK, overlayRow, tombstoneIndex, effectiveOR, preCoerced) {
         const existingAtNewPK = await this.getOverlayRow(overlay, newPK);
         if (existingAtNewPK && existingAtNewPK[tombstoneIndex] === 1) {
             return overlay.update({
@@ -1302,12 +1358,14 @@ export class IsolatedTable extends VirtualTable {
                 values: overlayRow,
                 oldKeyValues: newPK,
                 onConflict: effectiveOR,
+                preCoerced,
             });
         }
         return overlay.update({
             operation: 'insert',
             values: overlayRow,
             onConflict: effectiveOR,
+            preCoerced,
         });
     }
     async insertTombstoneForPK(overlay, pk, tombstoneIndex) {
@@ -1319,11 +1377,13 @@ export class IsolatedTable extends VirtualTable {
         pkIndices.forEach((colIdx, i) => { tombstoneRow[colIdx] = pk[i]; });
         tombstoneRow[tombstoneIndex] = 1;
         const existing = await this.getOverlayRow(overlay, pk);
+        // `pk` is already coerced (callers pass targetPK/coercedValues cells) — mark
+        // preCoerced so the overlay doesn't re-run (non-idempotent) JSON coercion on it.
         if (existing) {
-            await overlay.update({ operation: 'update', values: tombstoneRow, oldKeyValues: pk });
+            await overlay.update({ operation: 'update', values: tombstoneRow, oldKeyValues: pk, preCoerced: true });
         }
         else {
-            await overlay.update({ operation: 'insert', values: tombstoneRow });
+            await overlay.update({ operation: 'insert', values: tombstoneRow, preCoerced: true });
         }
     }
     /**
@@ -1382,14 +1442,20 @@ export class IsolatedTable extends VirtualTable {
      * 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.
+        // One comparison function per constrained column — the type's `compare` for a
+        // semantic-ordering column ('PT1H' conflicts with 'PT60M', matching both
+        // backends' typed enforcement), else the enforcement collation (the index's
+        // per-column COLLATE for an index-derived UNIQUE, else the declared column
+        // collation) through `compareSqlValuesFast`. Resolved once, above both
+        // candidate scans; both phases compare identically. The construction is the
+        // engine's `uniqueEnforcementComparators`, shared with the store and memory
+        // re-validators so the three backends cannot drift.
         const collations = resolveUniqueEnforcementCollations(this.tableSchema, uc, this.collationResolver);
-        const overlayConflict = await this.findOverlayUniqueConflict(overlay, predicate, newRow, selfPks, tombstoneIndex, uc.columns, collations);
+        const compares = uniqueEnforcementComparators(this.tableSchema.columns, uc.columns, collations);
+        const overlayConflict = await this.findOverlayUniqueConflict(overlay, predicate, newRow, selfPks, tombstoneIndex, uc.columns, compares);
         if (overlayConflict)
             return overlayConflict;
-        return this.findUnderlyingUniqueConflict(overlay, uc, predicate, newRow, selfPks, tombstoneIndex, collations);
+        return this.findUnderlyingUniqueConflict(overlay, uc, predicate, newRow, selfPks, tombstoneIndex, compares);
     }
     /**
      * Phase 1 — scan the overlay (this connection's uncommitted write set, small and
@@ -1399,7 +1465,7 @@ export class IsolatedTable extends VirtualTable {
      * what the merged view holds for that PK
      * (isolation-merged-unique-stale-underlying-false-positive).
      */
-    async findOverlayUniqueConflict(overlay, predicate, newRow, selfPks, tombstoneIndex, constrainedCols, collations) {
+    async findOverlayUniqueConflict(overlay, predicate, newRow, selfPks, tombstoneIndex, constrainedCols, compares) {
         if (!overlay.query)
             return null;
         const pkIndices = this.getPrimaryKeyIndices();
@@ -1410,7 +1476,7 @@ export class IsolatedTable extends VirtualTable {
             if (selfPks.some(self => this.keysEqual(pk, self)))
                 continue;
             const mergedRow = overlayRow.slice(0, tombstoneIndex);
-            if (this.rowMatchesUniqueConstraint(mergedRow, newRow, constrainedCols, collations, predicate)) {
+            if (this.rowMatchesUniqueConstraint(mergedRow, newRow, constrainedCols, compares, predicate)) {
                 return { pk, row: mergedRow };
             }
         }
@@ -1424,7 +1490,7 @@ export class IsolatedTable extends VirtualTable {
      * 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) {
+    async findUnderlyingUniqueConflict(overlay, uc, predicate, newRow, selfPks, tombstoneIndex, compares) {
         if (!this.underlyingTable.query)
             return null;
         const pkIndices = this.getPrimaryKeyIndices();
@@ -1441,7 +1507,7 @@ export class IsolatedTable extends VirtualTable {
             const overlayRow = await this.getOverlayRow(overlay, pk);
             if (overlayRow)
                 continue;
-            if (this.rowMatchesUniqueConstraint(underlyingRow, newRow, uc.columns, collations, predicate)) {
+            if (this.rowMatchesUniqueConstraint(underlyingRow, newRow, uc.columns, compares, predicate)) {
                 return { pk, row: underlyingRow };
             }
         }
@@ -1450,19 +1516,21 @@ export class IsolatedTable extends VirtualTable {
     /**
      * 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
+     * comparison function (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
+     * `compares` carries one function per constrained column, resolved once in
+     * {@link findMergedUniqueConflict}: the type's `compare` for a semantic-ordering
+     * column, else the enforcement collation (the index's per-column COLLATE for an
+     * index-derived UNIQUE, else the declared column collation) — the latter 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) {
+    rowMatchesUniqueConstraint(candidate, newRow, constrainedCols, compares, 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;
+            return compares[i](newRow[idx], candidate[idx]) === 0;
         });
         if (!matches)
             return false;
@@ -1608,11 +1676,13 @@ export class IsolatedTable extends VirtualTable {
     /**
      * 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.
+     * connection's effective rows, then adopting the change IN PLACE into every affected
+     * overlay (narrowed to live rows, and with a foreign overlay's rejection poisoning it
+     * rather than losing its staged rows) — 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);