@quereus/isolation 3.3.0 → 4.1.0

package/dist/src/isolated-table.js

@@ -1,4 +1,4 @@
-import { VirtualTable, compareSqlValues, isUpdateOk, IndexConstraintOp, ConflictResolution, compilePredicate } from '@quereus/quereus';
+import { VirtualTable, compareSqlValues, isUpdateOk, isConstraintViolation, IndexConstraintOp, ConflictResolution, compilePredicate, QuereusError, StatusCode, uniqueEnforcementCollations } from '@quereus/quereus';
 import { IsolatedConnection } from './isolated-connection.js';
 import { mergeStreams, createMergeEntry, createTombstone } from './merge-iterator.js';
 /**
@@ -59,6 +59,21 @@ export class IsolatedTable extends VirtualTable {
     getOverlayState() {
         return this.isolationModule.getConnectionOverlay(this.db, this.schemaName, this.tableName);
     }
+    /**
+     * Throws if this connection's overlay was poisoned by a cross-connection ALTER
+     * (see `IsolationModule.alterTable`). A poisoned overlay still holds rows in the
+     * PRE-alter column layout, so it can neither be merged into a read nor flushed to
+     * the now-altered underlying. Called at the data-op chokepoints (write, the merged
+     * read branch, and the commit flush) — never on the committed-snapshot read path,
+     * which bypasses the overlay entirely and stays safe. The connection recovers by
+     * rolling back, which discards the overlay (and its poison).
+     */
+    assertOverlayUsable() {
+        const state = this.getOverlayState();
+        if (state?.poison) {
+            throw new QuereusError(state.poison.message, StatusCode.CONSTRAINT);
+        }
+    }
     /**
      * Gets the overlay table, or undefined if no overlay exists yet.
      */
@@ -138,27 +153,57 @@ export class IsolatedTable extends VirtualTable {
      * IsolatedConnection, causing DeferredConstraintQueue.findConnection() to find multiple
      * covering candidates and throw. We therefore reuse the first covering connection
      * already registered for this table.
+     *
+     * Concurrent first-reads coalesce through the module-level in-flight memo
+     * (`IsolationModule.coalesceConnectionBuild`, keyed per db+table) rather than a
+     * per-instance one: the runtime connects a FRESH `IsolatedTable` per scan, so
+     * two concurrent scans of one table land on distinct instances and only a memo
+     * that spans all wrappers for the (db, table) can collapse them onto one
+     * registered covering connection. The resolved connection is cached in
+     * `registeredConnection` so subsequent reads on THIS instance fast-path — this
+     * is the only place that field is set when the build was coalesced onto another
+     * instance's in-flight promise (that instance's `buildConnection` ran, ours did
+     * not).
      */
     async ensureConnection() {
-        if (!this.registeredConnection) {
-            // Reuse an existing covering (IsolatedConnection) if one is already registered
-            // for this table — avoids accumulating one IsolatedConnection per statement.
-            const qualifiedName = `${this.schemaName}.${this.tableName}`;
-            const existing = this.db.getConnectionsForTable(qualifiedName);
-            const existingCovering = existing.find((c) => c.isCovering);
-            if (existingCovering) {
-                this.registeredConnection = existingCovering;
-                return this.registeredConnection;
-            }
-            // Create connection - overlay connection created lazily if needed
-            const overlayConn = this.overlayTable
-                ? await Promise.resolve(this.overlayTable.createConnection?.())
-                : undefined;
-            this.registeredConnection = new IsolatedConnection(`${this.schemaName}.${this.tableName}`, undefined, overlayConn, this);
-            // Register connection with the database for transaction management
-            await this.db.registerConnection(this.registeredConnection);
+        if (this.registeredConnection)
+            return this.registeredConnection;
+        const conn = await this.isolationModule.coalesceConnectionBuild(this.db, this.schemaName, this.tableName, () => this.buildConnection());
+        this.registeredConnection = conn;
+        return conn;
+    }
+    /**
+     * Builds (or reuses) the registered connection for this table. Always called
+     * through `IsolationModule.coalesceConnectionBuild` so concurrent callers —
+     * across all `IsolatedTable` instances for this (db, table) — share one build.
+     *
+     * The covering-reuse check stays INSIDE this coalesced body so a connection
+     * registered by another instance between calls (e.g. after the memo cleared on
+     * settle) is still picked up by the next read.
+     * `registeredConnection` is assigned only on the success paths (covering reuse
+     * or a completed `registerConnection`); a thrown `registerConnection` /
+     * overlay `createConnection` leaves it null and rejects the in-flight promise,
+     * which `coalesceConnectionBuild` clears so a later read rebuilds.
+     */
+    async buildConnection() {
+        // Reuse an existing covering (IsolatedConnection) if one is already registered
+        // for this table — avoids accumulating one IsolatedConnection per statement.
+        const qualifiedName = `${this.schemaName}.${this.tableName}`;
+        const existing = this.db.getConnectionsForTable(qualifiedName);
+        const existingCovering = existing.find((c) => c.isCovering);
+        if (existingCovering) {
+            this.registeredConnection = existingCovering;
+            return existingCovering;
         }
-        return this.registeredConnection;
+        // Create connection - overlay connection created lazily if needed
+        const overlayConn = this.overlayTable
+            ? await Promise.resolve(this.overlayTable.createConnection?.())
+            : undefined;
+        const connection = new IsolatedConnection(`${this.schemaName}.${this.tableName}`, undefined, overlayConn, this);
+        // Register connection with the database for transaction management
+        await this.db.registerConnection(connection);
+        this.registeredConnection = connection;
+        return connection;
     }
     // ==================== Connection Management ====================
     /**
@@ -198,10 +243,16 @@ export class IsolatedTable extends VirtualTable {
         if (!this.underlyingTable.query) {
             throw new Error('Underlying table does not support query');
         }
-        // Fast path: no overlay or no changes, or a committed-snapshot read — skip overlay
+        // Fast path: no overlay or no changes, or a committed-snapshot read — skip overlay.
+        // A poisoned overlay always has hasChanges === true, so this path never serves it;
+        // a committed.<table> (readCommitted) read reaches here and stays safe — it reads
+        // only the underlying and never merges the poisoned overlay.
         if (this.readCommitted || !this.overlayTable || !this.hasChanges) {
             return this.underlyingTable.query(filterInfo);
         }
+        // Merged branch: a poisoned overlay cannot be merged (its rows are in the
+        // pre-alter layout) — error before touching it.
+        this.assertOverlayUsable();
         // Merge overlay with underlying (with connection ensured)
         return this.mergedQueryWithConnection(filterInfo);
     }
@@ -441,10 +492,17 @@ export class IsolatedTable extends VirtualTable {
         if (this.underlyingTable.comparePrimaryKey) {
             return this.underlyingTable.comparePrimaryKey.bind(this.underlyingTable);
         }
-        // Fallback to default comparator
+        // Fallback to default comparator. Compare under each PK column's declared
+        // collation (e.g. NOCASE), not BINARY: the merge aligns overlay and underlying
+        // entries by this comparator to decide shadowing, and the underlying store keys
+        // rows collation-aware. A binary comparator would treat a case-only-updated
+        // overlay row ('APPLE') and the underlying row it shadows ('apple') as distinct
+        // keys, surfacing BOTH in a scan instead of the overlay shadowing the underlying.
+        const pkDef = this.tableSchema?.primaryKeyDefinition;
         return (a, b) => {
             for (let i = 0; i < a.length; i++) {
-                const cmp = compareSqlValues(a[i], b[i]);
+                const collation = pkDef ? this.tableSchema.columns[pkDef[i].index].collation : undefined;
+                const cmp = compareSqlValues(a[i], b[i], collation);
                 if (cmp !== 0)
                     return cmp;
             }
@@ -504,6 +562,9 @@ export class IsolatedTable extends VirtualTable {
      * The overlay is created lazily on first write, using schema from the underlying table.
      */
     async update(args) {
+        // A poisoned overlay (cross-connection ALTER) cannot accept further writes — its
+        // staged rows are in the pre-alter layout. Error before staging anything.
+        this.assertOverlayUsable();
         // Ensure connection is registered for transaction coordination
         await this.ensureConnection();
         // Lazily create overlay on first write
@@ -523,6 +584,8 @@ export class IsolatedTable extends VirtualTable {
             case 'insert': {
                 const pkIndices = this.getPrimaryKeyIndices();
                 const pk = values ? pkIndices.map(i => values[i]) : undefined;
+                // Secondary-UNIQUE REPLACE evictions surfaced via `evictedRows`.
+                const evicted = [];
                 // Captured when OR REPLACE displaces a row that lives only in the
                 // underlying store — surfaced as `replacedRow` so the DML executor
                 // fires ON DELETE cascades for the displaced parent.
@@ -563,7 +626,7 @@ export class IsolatedTable extends VirtualTable {
                             return pkOutcome.terminating;
                         replacedUnderlyingRow = pkOutcome.replacedUnderlyingRow;
                         // Check non-PK UNIQUE constraints against merged view
-                        const ucResult = await this.checkMergedUniqueConstraints(overlay, values, [pk], tombstoneIndex, args.onConflict);
+                        const ucResult = await this.checkMergedUniqueConstraints(overlay, values, [pk], tombstoneIndex, args.onConflict, evicted);
                         if (ucResult !== null)
                             return ucResult;
                     }
@@ -575,7 +638,7 @@ export class IsolatedTable extends VirtualTable {
                     values: overlayRow,
                 });
                 const stripped = this.stripTombstoneFromResult(result, tombstoneIndex);
-                return this.attachReplacedUnderlying(stripped, replacedUnderlyingRow);
+                return this.attachEvicted(this.attachReplacedUnderlying(stripped, replacedUnderlyingRow), evicted, tombstoneIndex);
             }
             case 'update': {
                 // For updates, we need to handle the case where the row exists in:
@@ -589,6 +652,8 @@ export class IsolatedTable extends VirtualTable {
                 }
                 const existingOverlayRow = await this.getOverlayRow(overlay, targetPK);
                 const overlayRow = [...values, 0]; // tombstone = 0
+                // Secondary-UNIQUE REPLACE evictions surfaced via `evictedRows`.
+                const evicted = [];
                 if (existingOverlayRow) {
                     const newPK = pkIndices.map(i => values[i]);
                     const pkChanged = !this.keysEqual(targetPK, newPK);
@@ -599,7 +664,7 @@ export class IsolatedTable extends VirtualTable {
                         const pkOutcome = await this.checkMergedPKConflict(overlay, newPK, tombstoneIndex, args.onConflict);
                         if (pkOutcome.terminating)
                             return pkOutcome.terminating;
-                        const ucResult = await this.checkMergedUniqueConstraints(overlay, values, [targetPK, newPK], tombstoneIndex, args.onConflict);
+                        const ucResult = await this.checkMergedUniqueConstraints(overlay, values, [targetPK, newPK], tombstoneIndex, args.onConflict, evicted);
                         if (ucResult !== null)
                             return ucResult;
                         // Remove existing overlay row then insert a tombstone so the underlying
@@ -608,13 +673,11 @@ export class IsolatedTable extends VirtualTable {
                         // correctly when updating a value inserted in the same transaction.
                         await overlay.update({ operation: 'delete', values: undefined, oldKeyValues: targetPK });
                         await this.insertTombstoneForPK(overlay, targetPK, tombstoneIndex);
-                        const result = await overlay.update({
-                            operation: 'insert',
-                            values: overlayRow,
-                            onConflict: effectiveOR,
-                        });
+                        // 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 stripped = this.stripTombstoneFromResult(result, tombstoneIndex);
-                        return this.attachReplacedUnderlying(stripped, pkOutcome.replacedUnderlyingRow);
+                        return this.attachEvicted(this.attachReplacedUnderlying(stripped, pkOutcome.replacedUnderlyingRow), evicted, tombstoneIndex);
                     }
                     // Same PK — update the overlay row in place
                     const result = await overlay.update({
@@ -636,20 +699,22 @@ export class IsolatedTable extends VirtualTable {
                         replacedUnderlyingRow = pkOutcome.replacedUnderlyingRow;
                     }
                     const selfPks = pkChanged ? [targetPK, newPK] : [targetPK];
-                    const ucResult = await this.checkMergedUniqueConstraints(overlay, values, selfPks, tombstoneIndex, args.onConflict);
+                    const ucResult = await this.checkMergedUniqueConstraints(overlay, values, selfPks, tombstoneIndex, args.onConflict, evicted);
                     if (ucResult !== null)
                         return ucResult;
                     // For PK-change updates, tombstone the old PK so the underlying row is deleted at flush
                     if (pkChanged) {
                         await this.insertTombstoneForPK(overlay, targetPK, tombstoneIndex);
                     }
-                    const result = await overlay.update({
-                        operation: 'insert',
-                        values: overlayRow,
-                        onConflict: effectiveOR,
-                    });
+                    // On a PK-change, reuse a tombstone already at newPK (a PK freed earlier
+                    // in this txn) instead of colliding with it — see writeRelocatedRow.
+                    // 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 });
                     const stripped = this.stripTombstoneFromResult(result, tombstoneIndex);
-                    return this.attachReplacedUnderlying(stripped, replacedUnderlyingRow);
+                    return this.attachEvicted(this.attachReplacedUnderlying(stripped, replacedUnderlyingRow), evicted, tombstoneIndex);
                 }
             }
             case 'delete': {
@@ -712,13 +777,22 @@ export class IsolatedTable extends VirtualTable {
      */
     stripTombstoneFromResult(result, tombstoneIndex) {
         if (isUpdateOk(result) && result.row) {
-            // `replacedRow` from the overlay's memory module also carries the trailing
-            // tombstone column (overlay schema appends it).  Slice it off so consumers
-            // see rows that match the user-facing schema.
+            // `replacedRow` / `evictedRows` from the overlay's memory module also carry
+            // the trailing tombstone column (the overlay schema appends it). Slice it off
+            // so consumers see rows that match the user-facing schema.
+            //
+            // `evictedRows` here are evictions the overlay's OWN memory module performed —
+            // an intra-statement secondary-UNIQUE REPLACE against a row written earlier in
+            // the same statement (it lives in the overlay, not the underlying, so the
+            // isolation layer's own `findMergedUniqueConflict` does not see it). They must
+            // flow through to the DML executor's eviction pipeline like any other.
             const replacedRow = result.replacedRow
                 ? result.replacedRow.slice(0, tombstoneIndex)
                 : undefined;
-            return { status: 'ok', row: result.row.slice(0, tombstoneIndex), replacedRow };
+            const evictedRows = result.evictedRows
+                ? result.evictedRows.map(r => r.slice(0, tombstoneIndex))
+                : undefined;
+            return { status: 'ok', row: result.row.slice(0, tombstoneIndex), replacedRow, evictedRows };
         }
         return result;
     }
@@ -733,7 +807,28 @@ export class IsolatedTable extends VirtualTable {
             return result;
         if (!isUpdateOk(result) || !result.row)
             return result;
-        return { status: 'ok', row: result.row, replacedRow: replacedUnderlyingRow };
+        return { ...result, row: result.row, replacedRow: replacedUnderlyingRow };
+    }
+    /**
+     * Surface internal REPLACE evictions of **underlying** rows (rows at OTHER PKs the
+     * isolation layer's own merged-view detection displaced via a tombstone) as
+     * `evictedRows`, so the DML executor runs the full delete pipeline for each. The
+     * passed rows come from `findMergedUniqueConflict`, which yields live underlying
+     * rows already in user-facing schema, so the tombstone-column slice is a defensive
+     * no-op. Preserves any `replacedRow` already attached and **merges** with any
+     * `evictedRows` already present (overlay-internal evictions propagated by
+     * {@link stripTombstoneFromResult}) — the two eviction sources are disjoint per
+     * write today (the conflicting row lives in the overlay XOR the underlying) but
+     * merging keeps both correct if that ever changes.
+     */
+    attachEvicted(result, evicted, tombstoneIndex) {
+        if (evicted.length === 0)
+            return result;
+        if (!isUpdateOk(result) || !result.row)
+            return result;
+        const stripped = evicted.map(r => r.slice(0, tombstoneIndex));
+        const evictedRows = result.evictedRows ? [...result.evictedRows, ...stripped] : stripped;
+        return { ...result, evictedRows };
     }
     /**
      * Gets a row from the overlay by primary key using O(log n) point lookup.
@@ -821,8 +916,15 @@ export class IsolatedTable extends VirtualTable {
     keysEqual(a, b) {
         if (a.length !== b.length)
             return false;
+        // Compare under each PK column's declared collation, not BINARY. The underlying
+        // 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.
+        const pkDef = this.tableSchema?.primaryKeyDefinition;
         for (let i = 0; i < a.length; i++) {
-            if (compareSqlValues(a[i], b[i]) !== 0)
+            const collation = pkDef ? this.tableSchema.columns[pkDef[i].index].collation : undefined;
+            if (compareSqlValues(a[i], b[i], collation) !== 0)
                 return false;
         }
         return true;
@@ -835,6 +937,39 @@ export class IsolatedTable extends VirtualTable {
         }
         return undefined;
     }
+    /**
+     * Writes a relocated row at `newPK` in the overlay for a PK-changing UPDATE.
+     *
+     * If the overlay already holds a **tombstone** at newPK (a PK that was freed
+     * earlier in this same transaction), overwrite it via `operation: 'update'`
+     * rather than `operation: 'insert'` — the overlay is itself a StoreTable whose
+     * insert path treats a tombstone row at the target key as a live PK conflict
+     * and would throw `_overlay_<table> PK`. Overwriting the tombstone is the
+     * logical reuse of the freed PK. This mirrors the plain-INSERT tombstone
+     * conversion (~the `existingRow[tombstoneIndex] === 1` branch in `update`).
+     *
+     * A **live** overlay row at newPK is already rejected upstream by
+     * {@link checkMergedPKConflict} (which returns its terminating constraint
+     * result) and by the existing-overlay-row PK-conflict branch, so reaching here
+     * 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) {
+        const existingAtNewPK = await this.getOverlayRow(overlay, newPK);
+        if (existingAtNewPK && existingAtNewPK[tombstoneIndex] === 1) {
+            return overlay.update({
+                operation: 'update',
+                values: overlayRow,
+                oldKeyValues: newPK,
+                onConflict: effectiveOR,
+            });
+        }
+        return overlay.update({
+            operation: 'insert',
+            values: overlayRow,
+            onConflict: effectiveOR,
+        });
+    }
     async insertTombstoneForPK(overlay, pk, tombstoneIndex) {
         const schema = this.tableSchema;
         if (!schema)
@@ -895,6 +1030,9 @@ export class IsolatedTable extends VirtualTable {
             return null;
         const pkIndices = this.getPrimaryKeyIndices();
         const constrainedCols = uc.columns;
+        // One comparison collation per constrained column — the index's per-column
+        // COLLATE for an index-derived UNIQUE, else the declared column collation.
+        const collations = uniqueEnforcementCollations(this.tableSchema, uc);
         for await (const underlyingRow of this.underlyingTable.query(this.createFullScanFilterInfo())) {
             const pk = pkIndices.map(i => underlyingRow[i]);
             if (selfPks.some(self => this.keysEqual(pk, self)))
@@ -902,25 +1040,44 @@ export class IsolatedTable extends VirtualTable {
             const overlayRow = await this.getOverlayRow(overlay, pk);
             if (overlayRow && overlayRow[tombstoneIndex] === 1)
                 continue;
-            const matches = constrainedCols.every(idx => {
-                if (newRow[idx] === null || underlyingRow[idx] === null)
+            // When a non-tombstone overlay entry supersedes this committed row, the
+            // row's current merged-view value is the overlay's — not the stale
+            // underlying value. Evaluate the UNIQUE columns (and any partial
+            // predicate) against the merged row so a candidate that was moved off
+            // the value earlier in this txn no longer counts as a conflict
+            // (isolation-merged-unique-stale-underlying-false-positive). The overlay
+            // row carries the appended tombstone column; strip it back to schema shape.
+            const mergedRow = overlayRow ? overlayRow.slice(0, tombstoneIndex) : underlyingRow;
+            const matches = constrainedCols.every((idx, i) => {
+                if (newRow[idx] === null || mergedRow[idx] === null)
                     return false;
-                return compareSqlValues(newRow[idx], underlyingRow[idx]) === 0;
+                // Compare under each column's enforcement collation (the index's
+                // per-column COLLATE for an index-derived UNIQUE, else the declared
+                // column collation), so a UNIQUE over a collated column is enforced
+                // against committed rows through the isolation merge path
+                // (unique-constraint-honors-column-collation / store-index-derived-unique).
+                return compareSqlValues(newRow[idx], mergedRow[idx], collations[i]) === 0;
             });
             if (!matches)
                 continue;
             // Partial UNIQUE: candidate must also be in the predicate's scope to conflict.
-            if (predicate && predicate.evaluate(underlyingRow) !== true)
+            if (predicate && predicate.evaluate(mergedRow) !== true)
                 continue;
-            return { pk, row: underlyingRow };
+            return { pk, row: mergedRow };
         }
         return null;
     }
     /**
      * Checks all non-PK UNIQUE constraints against the merged view.
      * Returns null when all pass or REPLACE evictions succeed.
+     *
+     * A REPLACE eviction tombstones the conflicting live merged row in the overlay
+     * (so the underlying row is deleted at flush) and pushes that row onto `evicted`
+     * — surfaced to the DML executor via `evictedRows` so it runs the full delete
+     * pipeline (change-tracking, FK cascade, auto-events, and the row-time
+     * covering-MV backing maintenance the isolation layer otherwise never drives).
      */
-    async checkMergedUniqueConstraints(overlay, newRow, selfPks, tombstoneIndex, onConflict) {
+    async checkMergedUniqueConstraints(overlay, newRow, selfPks, tombstoneIndex, onConflict, evicted) {
         const schema = this.tableSchema;
         const uniqueConstraints = schema?.uniqueConstraints;
         if (!uniqueConstraints || uniqueConstraints.length === 0)
@@ -942,6 +1099,9 @@ export class IsolatedTable extends VirtualTable {
                 return { status: 'ok', row: undefined };
             if (effective === ConflictResolution.REPLACE) {
                 await this.insertTombstoneForPK(overlay, conflict.pk, tombstoneIndex);
+                // Report the eviction (the conflicting row is the live underlying row,
+                // already user-facing). The executor maintains the covering backing.
+                evicted.push(conflict.row);
                 continue;
             }
             const colNames = uc.columns.map(i => schema.columns[i].name).join(', ');
@@ -972,6 +1132,12 @@ export class IsolatedTable extends VirtualTable {
      * Shared by commit() and onConnectionCommit().
      */
     async flushAndClearOverlay() {
+        // A poisoned overlay must never be flushed to the (already-altered) underlying:
+        // its rows are in the pre-alter layout. Throwing here is how a connection that
+        // never touches the poisoned table again still errors at commit, failing the
+        // whole transaction. The overlay is left intact so a subsequent rollback clears
+        // it (and the poison).
+        this.assertOverlayUsable();
         const overlay = this.overlayTable;
         if (this.hasChanges && overlay) {
             await this.flushOverlayToUnderlying(overlay);
@@ -1001,36 +1167,49 @@ export class IsolatedTable extends VirtualTable {
         }
         if (overlayEntries.length === 0)
             return;
+        // Apply deletes (tombstones) before inserts/updates so a write that collides
+        // on a secondary UNIQUE with a row being deleted in this same flush sees the
+        // slot freed first (e.g. INSERT OR REPLACE that both replaces a PK-colliding
+        // row AND evicts a different row on a secondary UNIQUE). Each PK appears at
+        // most once in the overlay, so there is no same-PK delete-then-insert pair
+        // this reordering could invert; sort() is stable in V8/Node, preserving the
+        // original PK order within each group.
+        const ordered = [...overlayEntries].sort((a, b) => (a.isTombstone === b.isTombstone ? 0 : a.isTombstone ? -1 : 1));
         // Begin a transaction on the underlying table for the flush
         await this.underlyingTable.begin?.();
         try {
             // Apply all overlay entries to underlying
-            for (const entry of overlayEntries) {
+            for (const entry of ordered) {
                 if (entry.isTombstone) {
                     // Delete from underlying
-                    await this.underlyingTable.update({
+                    const result = await this.underlyingTable.update({
                         operation: 'delete',
                         values: undefined,
                         oldKeyValues: entry.pk,
                     });
+                    this.assertFlushWriteOk(result, 'delete', entry.pk);
                 }
                 else {
                     // Check if row exists in underlying to decide insert vs update
                     const existsInUnderlying = await this.rowExistsInUnderlying(entry.pk);
                     if (existsInUnderlying) {
-                        await this.underlyingTable.update({
+                        const result = await this.underlyingTable.update({
                             operation: 'update',
                             values: entry.dataRow,
                             oldKeyValues: entry.pk,
                             preCoerced: true,
+                            trustedWrite: true,
                         });
+                        this.assertFlushWriteOk(result, 'update', entry.pk);
                     }
                     else {
-                        await this.underlyingTable.update({
+                        const result = await this.underlyingTable.update({
                             operation: 'insert',
                             values: entry.dataRow,
                             preCoerced: true,
+                            trustedWrite: true,
                         });
+                        this.assertFlushWriteOk(result, 'insert', entry.pk);
                     }
                 }
             }
@@ -1043,6 +1222,21 @@ export class IsolatedTable extends VirtualTable {
             throw error;
         }
     }
+    /**
+     * Asserts that an underlying write performed during the commit flush succeeded.
+     *
+     * The overlay's merged-view pre-checks ({@link checkMergedPKConflict} /
+     * {@link checkMergedUniqueConstraints}) resolve every constraint before commit, so a
+     * `constraint` result returned here means a real invariant was violated *after* those
+     * checks. Historically this result was discarded, silently dropping the colliding
+     * write and surfacing as data corruption. Convert it into a loud INTERNAL error; the
+     * caller's try/catch rolls back the underlying flush transaction and rethrows.
+     */
+    assertFlushWriteOk(result, operation, pk) {
+        if (isConstraintViolation(result)) {
+            throw new QuereusError(`Isolation flush ${operation} on '${this.tableName}' (pk=[${pk.join(', ')}]) hit a ${result.constraint} constraint: ${result.message ?? 'no message'}. The overlay merged-view pre-checks should have resolved this before commit; this indicates an isolation-layer invariant violation.`, StatusCode.INTERNAL);
+        }
+    }
     /**
      * Checks if a row with the given primary key exists in the underlying table.
      * Uses O(log n) point lookup via the PK index.