@quereus/quereus 3.2.1 → 4.0.0

package/dist/src/runtime/emit/dml-executor.js

@@ -5,10 +5,11 @@ import { getVTable, disconnectVTable } from '../utils.js';
 import { ConflictResolution } from '../../common/constants.js';
 import { extractOldRowFromFlat, extractNewRowFromFlat } from '../../util/row-descriptor.js';
 import { buildInsertStatement, buildUpdateStatement, buildDeleteStatement } from '../../util/mutation-statement.js';
+import { isMaintainedTable } from '../../schema/derivation.js';
 import { hasNativeEventSupport } from '../../util/event-support.js';
 import { sqlValuesEqual } from '../../util/comparison.js';
 import { withAsyncRowContext } from '../context-helpers.js';
-import { executeForeignKeyActions, assertTransitiveRestrictsForParentMutation } from '../foreign-key-actions.js';
+import { executeForeignKeyActionsAndLens, assertTransitiveRestrictsForParentMutation } from '../foreign-key-actions.js';
 /**
  * Module-scope counter producing unique statement-savepoint names across
  * concurrent emissions. Names must be unique within the TransactionManager's
@@ -16,6 +17,19 @@ import { executeForeignKeyActions, assertTransitiveRestrictsForParentMutation }
  * (e.g. FK cascade during the parent insert).
  */
 let stmtSavepointCounter = 0;
+/**
+ * Returns true when the table's owning *module* natively emits data events.
+ * The gate must consult the MODULE, not the vtab instance: StoreModule exposes
+ * getEventEmitter only at the module level — its table instances do not — so an
+ * instance check spuriously reports "no native support" and the engine double-emits
+ * alongside the module's native emitter. Mirrors the schema-event gate in
+ * schema/manager.ts (emitAutoSchemaEventIfNeeded).
+ */
+function moduleHasNativeDataEvents(ctx, tableSchema) {
+    const moduleName = tableSchema.vtabModuleName;
+    const moduleReg = moduleName ? ctx.db._getVtabModule(moduleName) : undefined;
+    return hasNativeEventSupport(moduleReg?.module);
+}
 /**
  * Emit an automatic data change event for modules without native event support.
  */
@@ -31,8 +45,82 @@ function emitAutoDataEvent(ctx, tableSchema, type, key, oldRow, newRow, changedC
         remote: false, // Auto-emitted events are always local
     });
 }
+/**
+ * Synchronously drive row-time (write-through) materialized-view maintenance for
+ * one source row-write, immediately after the change is recorded. A no-op fast
+ * path (one synchronous map lookup) when no `row-time` MV depends on `tableKey`,
+ * so non-covered tables pay effectively nothing. The maintenance writes the
+ * covering MV's backing table within the same transaction (visible mid-statement;
+ * committed/rolled-back in lockstep with this write) — see
+ * `core/database-materialized-views.ts` § row-time write-through.
+ *
+ * `cache` is the per-statement {@link BackingConnectionCache} the generator owns: it
+ * amortizes the backing-connection resolution over the whole statement (one scan per
+ * backing instead of one per source row) while still applying each bounded-delta arm's
+ * ops immediately, so within-statement enforcement visibility is unchanged.
+ *
+ * `deferred` is the per-statement deferred-rebuild set the generator owns: a full-rebuild
+ * covering MV is marked dirty here (not applied per row) and rebuilt once at the
+ * end-of-statement flush ({@link runWithStatementSavepoints}). Bounded-delta arms stay
+ * per-row-immediate.
+ */
+async function maintainRowTimeStructures(ctx, tableKey, change, cache, deferred) {
+    if (!ctx.db._hasRowTimeCoveringStructures(tableKey))
+        return;
+    await ctx.db._maintainRowTimeCoveringStructures(tableKey, change, cache, deferred);
+}
+/**
+ * Evaluate the per-statement mutation-context evaluators once, producing the
+ * context row passed to the mutation-statement builders (or undefined when
+ * there are no context evaluators). Shared by all three DML generators.
+ */
+async function evaluateContextRow(ctx, contextEvaluators) {
+    if (contextEvaluators.length === 0)
+        return undefined;
+    const contextRow = [];
+    for (const evaluator of contextEvaluators) {
+        contextRow.push(await evaluator(ctx));
+    }
+    return contextRow;
+}
+/**
+ * Engine-level READONLY backstop for maintained tables — the defense-in-depth
+ * second net behind plan-time write-through dispatch.
+ *
+ * A maintained table's rows are *derived* (it carries a {@link TableDerivation};
+ * `schema/derivation.ts`). The only engine surfaces permitted to write them are
+ * the privileged backing-host paths (`applyMaintenance` / `replaceContents`, the
+ * attach/refresh reconcile, the store rehydrate-refill, the isolation flush
+ * `trustedWrite`) — none of which route through the DML executor. User DML naming
+ * a maintained table is rewritten to **write-through** against the body's base
+ * source at plan time (the three DML builders' view-mutation dispatch + the
+ * resolved-schema backstop), so a `DmlExecutorNode` whose target still carries a
+ * derivation can only be a plan-time mis-dispatch — a direct-write plan that
+ * would silently diverge the derived contents from the source. This converts that
+ * whole bug class into a loud READONLY error at emit time.
+ *
+ * Keyed structurally on `derivation` presence ({@link isMaintainedTable}) — never
+ * on the table name. Emit-time (a single prepare-time check), not per-row: zero
+ * runtime cost, and re-checked on every re-plan because `set / drop maintained`
+ * invalidate the `'table'` statement-cache dependency. Exported so a spec test can
+ * exercise it directly with a derivation-bearing schema: the backstop is
+ * deliberately unreachable from SQL (plan-time dispatch routes every reachable
+ * spelling away from it), so the exported guard plus the one wiring call site is
+ * the honest pin.
+ */
+export function assertNotMaintainedTableTarget(tableSchema) {
+    if (isMaintainedTable(tableSchema)) {
+        throw new QuereusError(`table '${tableSchema.schemaName}.${tableSchema.name}' is a maintained table — its contents are derived `
+            + `and may not be written directly (user DML routes through write-through; this plan bypassed the dispatch — engine bug)`, StatusCode.READONLY);
+    }
+}
 export function emitDmlExecutor(plan, ctx) {
     const tableSchema = plan.table.tableSchema;
+    // READONLY backstop: a DmlExecutorNode targeting a maintained table is a
+    // plan-time mis-dispatch (user DML should have been rewritten to write-through
+    // against the base source). Reject loudly rather than letting a direct write
+    // silently diverge the derived contents — see assertNotMaintainedTableTarget.
+    assertNotMaintainedTableTarget(tableSchema);
     // Pre-calculate primary key column indices from schema (needed for update/delete)
     const pkColumnIndicesInSchema = tableSchema.primaryKeyDefinition.map(pkColDef => pkColDef.index);
     // Emit mutation context evaluators if present
@@ -179,39 +267,43 @@ export function emitDmlExecutor(plan, ctx) {
         }
         return err;
     }
-    // INSERT ----------------------------------------------------
-    // Number of context evaluators (used to split params in runInsert)
-    const numContextEvaluators = contextEvaluatorInstructions.length;
-    async function* runInsert(ctx, rows, ...allEvaluators) {
-        // Split evaluators: first numContextEvaluators are context, rest are upsert
-        const contextEvaluators = allEvaluators.slice(0, numContextEvaluators);
-        const upsertEvaluators = allEvaluators.slice(numContextEvaluators);
-        // Ensure we're in a transaction before any mutations (lazy/JIT transaction start)
-        await ctx.db._ensureTransaction();
-        const vtab = await getVTable(ctx, tableSchema);
-        const needsAutoEvents = ctx.db.hasDataListeners() && !hasNativeEventSupport(vtab);
-        // Evaluate mutation context once per statement
-        let contextRow;
-        if (contextEvaluators.length > 0) {
-            contextRow = [];
-            for (const evaluator of contextEvaluators) {
-                const value = await evaluator(ctx);
-                contextRow.push(value);
-            }
-        }
-        // OR FAIL needs per-row rollback so a later row's failure doesn't undo prior rows.
-        // We open a savepoint, do the row's work, release on success, rollback on error.
-        const isFailMode = plan.onConflict === ConflictResolution.FAIL;
+    /**
+     * Shared statement-/row-level savepoint scaffold for multi-row DML, used by
+     * all three generators. Owns the savepoint lifecycle that makes a multi-row
+     * mutation atomic inside an explicit transaction, plus the per-row OR FAIL
+     * savepoint that keeps prior rows while undoing only the failing row.
+     * INSERT/UPDATE/DELETE reduce to a `processRow` closure carrying the
+     * operation-specific body (vtab.update + bookkeeping + FK actions + events).
+     *
+     * - non-FAIL (ABORT default / IGNORE / REPLACE / ROLLBACK): one
+     *   statement-scope savepoint, released after the loop completes and
+     *   rolled-back-and-released on ANY throw escaping the loop — whether from
+     *   the source iterator (e.g. a ConstraintCheckNode above the executor
+     *   raising NOT NULL / CHECK before a row is yielded) or from `processRow`
+     *   (a vtab-returned constraint, or a RESTRICT pre-check). This is the
+     *   statement-atomicity guarantee, mirroring SQLite's implicit
+     *   per-statement savepoint: all of a statement's row effects apply or none.
+     * - OR FAIL: per-row savepoint, released on success, rolled back on throw,
+     *   so the failing row's partial work (incl. a row-time backing write that
+     *   lands before a later maintenance throw) is undone while earlier rows
+     *   survive. FAIL deliberately skips the statement-scope wrap.
+     *
+     * Always uses the broadcast savepoint helpers so per-connection savepoint
+     * stacks stay in lockstep with the TransactionManager's stack — including a
+     * connection registered lazily mid-statement (the row-time backing
+     * connection registers on the first maintenance call; Database.registerConnection
+     * replays the active savepoint depth onto it, which already includes the
+     * statement savepoint created before the row loop).
+     */
+    async function* runWithStatementSavepoints(ctx, vtab, rows, isFailMode, processRow, deferredRebuilds, backingConnCache) {
         let failSavepointCounter = 0;
-        // For non-FAIL modes (ABORT default / IGNORE / REPLACE / ROLLBACK) we wrap
-        // the whole statement in a savepoint so a mid-statement constraint failure
-        // unwinds partial writes from earlier rows. Use the broadcast helper so
-        // per-connection savepoint stacks stay in lockstep with the
-        // TransactionManager's stack (otherwise an outer user-level SAVEPOINT
-        // could index into a stale placeholder).
-        const wrapStatementSavepoint = !isFailMode;
-        const stmtSavepointName = wrapStatementSavepoint
-            ? `__or_abort_${stmtSavepointCounter++}`
+        // For non-FAIL modes wrap the whole statement so a mid-statement failure
+        // unwinds partial writes from earlier rows. FAIL keeps prior rows, so it
+        // uses the per-row savepoint (opened inside the loop) instead. Share the
+        // module-scope counter so a cascade-nested savepoint name (e.g. an FK
+        // cascade UPDATE during a parent UPDATE) can't collide with the parent's.
+        const stmtSavepointName = !isFailMode
+            ? `__stmt_atomic_${stmtSavepointCounter++}`
             : undefined;
         if (stmtSavepointName) {
             await ctx.db._createSavepointBroadcast(stmtSavepointName);
@@ -219,14 +311,9 @@ export function emitDmlExecutor(plan, ctx) {
         try {
             try {
                 for await (const flatRow of rows) {
-                    // OR FAIL per-row savepoint. Like the statement-scope wrap above,
-                    // we use the broadcast helper so per-connection savepoint stacks
-                    // stay in lockstep with TransactionManager's. If a new connection
-                    // registers mid-row (e.g. via CTE materialization that
-                    // instantiates a new memory-backed table), Database.registerConnection
-                    // replays the active depth onto it — without broadcasting our
-                    // create here, that replay would offset its stack by one and a
-                    // subsequent user-level ROLLBACK TO would restore the wrong layer.
+                    // OR FAIL per-row savepoint. Broadcast (not the bare variant)
+                    // so a connection registering mid-row keeps its stack in
+                    // lockstep — see the doc comment above.
                     let savepointName;
                     if (isFailMode) {
                         savepointName = `__or_fail_${failSavepointCounter++}`;
@@ -235,7 +322,7 @@ export function emitDmlExecutor(plan, ctx) {
                     let rowToYield;
                     let succeeded = false;
                     try {
-                        rowToYield = await processInsertRow(ctx, vtab, needsAutoEvents, flatRow, contextRow, runtimeUpsertClauses, upsertEvaluators);
+                        rowToYield = await processRow(flatRow);
                         succeeded = true;
                     }
                     catch (e) {
@@ -243,8 +330,9 @@ export function emitDmlExecutor(plan, ctx) {
                             await ctx.db._rollbackAndReleaseSavepointBroadcast(savepointName);
                             savepointName = undefined;
                         }
-                        // Translate plain constraint violations to FAIL/ROLLBACK error subclasses
-                        // so the iterator-level cleanup picks the right finalization branch.
+                        // Translate plain constraint violations to FAIL/ROLLBACK error
+                        // subclasses so the iterator-level cleanup picks the right
+                        // finalization branch.
                         throw translateConflictError(e, plan.onConflict);
                     }
                     if (succeeded && savepointName) {
@@ -254,6 +342,14 @@ export function emitDmlExecutor(plan, ctx) {
                         yield rowToYield;
                     }
                 }
+                // End-of-statement boundary: drain the deferred full-rebuild set NOW — after
+                // every source row has been applied (so each rebuild reads all this
+                // statement's writes) and BEFORE the statement savepoint releases (so a
+                // failed rebuild rolls the whole statement back). Inside the try, so a flush
+                // error routes to the rollback branch below. A no-op when nothing deferred.
+                if (deferredRebuilds.size > 0) {
+                    await ctx.db._flushDeferredRebuilds(deferredRebuilds, backingConnCache);
+                }
                 if (stmtSavepointName) {
                     await ctx.db._releaseSavepointBroadcast(stmtSavepointName);
                 }
@@ -262,6 +358,19 @@ export function emitDmlExecutor(plan, ctx) {
                 if (stmtSavepointName) {
                     await ctx.db._rollbackAndReleaseSavepointBroadcast(stmtSavepointName);
                 }
+                else if (deferredRebuilds.size > 0) {
+                    // OR FAIL keeps the rows that already succeeded (it runs with no
+                    // statement-scope savepoint), so a mid-statement abort does NOT unwind
+                    // them. Their deferred full-rebuild MVs must therefore still be flushed
+                    // before the conflict error propagates — otherwise the backing would lag
+                    // the surviving source rows mid-transaction (read(MV) != evaluate(body)).
+                    // The failing row's own per-row savepoint already reverted its writes, so
+                    // the rebuild re-evaluates over exactly the surviving rows. The original
+                    // conflict error is re-thrown after the flush. (A flush failure here is a
+                    // genuine maintenance error and supersedes the conflict error, matching
+                    // "a maintenance error fails the source write".)
+                    await ctx.db._flushDeferredRebuilds(deferredRebuilds, backingConnCache);
+                }
                 throw e;
             }
         }
@@ -269,6 +378,62 @@ export function emitDmlExecutor(plan, ctx) {
             await disconnectVTable(ctx, vtab);
         }
     }
+    // INSERT ----------------------------------------------------
+    // Number of context evaluators (used to split params in runInsert)
+    const numContextEvaluators = contextEvaluatorInstructions.length;
+    async function* runInsert(ctx, rows, ...allEvaluators) {
+        // Split evaluators: first numContextEvaluators are context, rest are upsert
+        const contextEvaluators = allEvaluators.slice(0, numContextEvaluators);
+        const upsertEvaluators = allEvaluators.slice(numContextEvaluators);
+        // Ensure we're in a transaction before any mutations (lazy/JIT transaction start)
+        await ctx.db._ensureTransaction();
+        const vtab = await getVTable(ctx, tableSchema);
+        const needsAutoEvents = ctx.db._needsDataEvents() && !moduleHasNativeDataEvents(ctx, tableSchema);
+        const contextRow = await evaluateContextRow(ctx, contextEvaluators);
+        // Per-statement backing-connection cache: resolve each covering MV's backing
+        // connection once for the whole statement rather than once per source row.
+        const backingConnCache = new Map();
+        // Per-statement deferred full-rebuild set (MV keys): full-rebuild covering MVs
+        // are marked dirty during the row loop and rebuilt once at the end-of-statement
+        // flush in runWithStatementSavepoints.
+        const deferredRebuilds = new Set();
+        const isFailMode = plan.onConflict === ConflictResolution.FAIL;
+        // Stamp the per-row mutation ordinal so a column `default` referencing
+        // `mutation_ordinal()` (a per-row surrogate allocator) resolves to the 1-based
+        // position of the row being produced. The defaults are evaluated upstream as
+        // each row is *pulled*, so the ordinal is set BEFORE pulling — see
+        // `stampMutationOrdinal`.
+        yield* runWithStatementSavepoints(ctx, vtab, stampMutationOrdinal(ctx, rows), isFailMode, (flatRow) => processInsertRow(ctx, vtab, needsAutoEvents, flatRow, contextRow, runtimeUpsertClauses, upsertEvaluators, backingConnCache, deferredRebuilds), deferredRebuilds, backingConnCache);
+    }
+    /**
+     * Wrap the INSERT source so `rctx.mutationOrdinal` holds the 1-based ordinal of the
+     * row about to be produced. The column-default projection runs upstream when each
+     * row is *pulled*, so the ordinal is set immediately before `it.next()` — that pull
+     * drives the default evaluation for exactly that row, and `mutation_ordinal()` reads
+     * the just-set value. Saved/restored so a nested mutation (an FK cascade, a
+     * row-time backing write) does not see a stale ordinal, and cleared in `finally` so
+     * it never leaks past the statement.
+     */
+    async function* stampMutationOrdinal(rctx, rows) {
+        const saved = rctx.mutationOrdinal;
+        const it = rows[Symbol.asyncIterator]();
+        let ordinal = 0;
+        try {
+            while (true) {
+                rctx.mutationOrdinal = ordinal + 1;
+                const next = await it.next();
+                if (next.done)
+                    break;
+                ordinal += 1;
+                yield next.value;
+            }
+        }
+        finally {
+            rctx.mutationOrdinal = saved;
+            if (it.return)
+                await it.return();
+        }
+    }
     /**
      * Performs a single row's INSERT side-effects (vtab.update + bookkeeping +
      * UPSERT handling + REPLACE handling). Returns the row to yield downstream,
@@ -276,8 +441,9 @@ export function emitDmlExecutor(plan, ctx) {
      *
      * Throws ConstraintError on violations the executor cannot recover from.
      */
-    async function processInsertRow(ctx, vtab, needsAutoEvents, flatRow, contextRow, runtimeUpsertClauses, upsertEvaluators) {
+    async function processInsertRow(ctx, vtab, needsAutoEvents, flatRow, contextRow, runtimeUpsertClauses, upsertEvaluators, backingConnCache, deferredRebuilds) {
         const newRow = extractNewRowFromFlat(flatRow, tableSchema.columns.length);
+        const tableKey = `${tableSchema.schemaName}.${tableSchema.name}`;
         let mutationStatement;
         if (vtab.wantStatements) {
             mutationStatement = buildInsertStatement(tableSchema, newRow, contextRow);
@@ -304,8 +470,9 @@ export function emitDmlExecutor(plan, ctx) {
                     if (!updateResult)
                         return undefined;
                     const existingKeyValues = pkColumnIndicesInSchema.map(idx => result.existingRow[idx]);
-                    ctx.db._recordUpdate(`${tableSchema.schemaName}.${tableSchema.name}`, result.existingRow, updateResult.updatedRow, pkColumnIndicesInSchema);
-                    await executeForeignKeyActions(ctx.db, tableSchema, 'update', result.existingRow, updateResult.updatedRow);
+                    ctx.db._recordUpdate(tableKey, result.existingRow, updateResult.updatedRow, pkColumnIndicesInSchema);
+                    await maintainRowTimeStructures(ctx, tableKey, { op: 'update', oldRow: result.existingRow, newRow: updateResult.updatedRow }, backingConnCache, deferredRebuilds);
+                    await executeForeignKeyActionsAndLens(ctx.db, tableSchema, 'update', result.existingRow, updateResult.updatedRow, plan.lensRouted);
                     if (needsAutoEvents) {
                         const changedColumns = [];
                         for (let i = 0; i < tableSchema.columns.length; i++) {
@@ -325,12 +492,16 @@ export function emitDmlExecutor(plan, ctx) {
         if (!result.row) {
             return undefined;
         }
-        const tableKey = `${tableSchema.schemaName}.${tableSchema.name}`;
+        // Internal REPLACE evictions (rows at OTHER PKs removed to resolve a non-PK
+        // UNIQUE conflict) run the full delete pipeline here, before the new row's
+        // own bookkeeping — evict-then-write, matching the substrate journal order.
+        await processEvictions(ctx, needsAutoEvents, tableKey, result.evictedRows, backingConnCache, deferredRebuilds);
         const replacedRow = result.replacedRow;
         if (replacedRow) {
             const newKeyValues = pkColumnIndicesInSchema.map(idx => newRow[idx]);
             ctx.db._recordUpdate(tableKey, replacedRow, newRow, pkColumnIndicesInSchema);
-            await executeForeignKeyActions(ctx.db, tableSchema, 'delete', replacedRow);
+            await maintainRowTimeStructures(ctx, tableKey, { op: 'update', oldRow: replacedRow, newRow }, backingConnCache, deferredRebuilds);
+            await executeForeignKeyActionsAndLens(ctx.db, tableSchema, 'delete', replacedRow, undefined, plan.lensRouted);
             if (needsAutoEvents) {
                 const changedColumns = [];
                 for (let i = 0; i < tableSchema.columns.length; i++) {
@@ -344,176 +515,225 @@ export function emitDmlExecutor(plan, ctx) {
         else {
             const pkValues = pkColumnIndicesInSchema.map(idx => newRow[idx]);
             ctx.db._recordInsert(tableKey, newRow, pkColumnIndicesInSchema);
+            await maintainRowTimeStructures(ctx, tableKey, { op: 'insert', newRow }, backingConnCache, deferredRebuilds);
             if (needsAutoEvents) {
                 emitAutoDataEvent(ctx, tableSchema, 'insert', pkValues, undefined, [...newRow]);
             }
         }
         return flatRow;
     }
+    /**
+     * Drive the full delete pipeline for every internal REPLACE eviction reported
+     * in `evictedRows` — rows at *other PKs* a substrate removed to resolve a non-PK
+     * UNIQUE conflict for this same `vtab.update()` call. The substrate deletes the
+     * row from its own storage but cannot run the cross-cutting post-write steps
+     * (change-tracking, row-time MV maintenance, FK cascade, auto-events) — those
+     * live solely here. So each evicted row is processed as a full DELETE, exactly
+     * like {@link processDeleteRow}'s own bookkeeping.
+     *
+     * Called *before* the writing row's own insert/update bookkeeping so the
+     * eviction's row-time maintenance and FK cascade land in the substrate's
+     * evict-then-write order (a later same-key backing write must not be undone by
+     * an earlier-PK eviction's delete).
+     */
+    async function processEvictions(ctx, needsAutoEvents, tableKey, evictedRows, backingConnCache, deferredRebuilds) {
+        if (!evictedRows || evictedRows.length === 0)
+            return;
+        for (const evicted of evictedRows) {
+            // RESTRICT / NO ACTION enforcement for the eviction's would-be delete.
+            // The substrate already physically removed the evicted row inside
+            // vtab.update(), so there is no pre-mutation point. Run the transitive
+            // RESTRICT scan post-eviction (the child rows it keys off remain) and,
+            // on a violation, throw — runWithStatementSavepoints rolls back the
+            // statement savepoint, unwinding both the eviction and the writing row.
+            // Mirrors the pre-check processDeleteRow runs for a plain DELETE.
+            //
+            // lensRouted = false (the default) on both FK calls: an internal REPLACE
+            // eviction is a physical basis effect (a row at another PK the substrate
+            // removed to resolve a non-PK UNIQUE conflict), not a write through the
+            // lens, so it bears only physical (basis-declared) FK semantics.
+            await assertTransitiveRestrictsForParentMutation(ctx.db, tableSchema, 'delete', evicted);
+            const evictedKeyValues = pkColumnIndicesInSchema.map(idx => evicted[idx]);
+            ctx.db._recordDelete(tableKey, evicted, pkColumnIndicesInSchema);
+            await maintainRowTimeStructures(ctx, tableKey, { op: 'delete', oldRow: evicted }, backingConnCache, deferredRebuilds);
+            await executeForeignKeyActionsAndLens(ctx.db, tableSchema, 'delete', evicted);
+            if (needsAutoEvents) {
+                emitAutoDataEvent(ctx, tableSchema, 'delete', evictedKeyValues, [...evicted]);
+            }
+        }
+    }
     // UPDATE ----------------------------------------------------
     async function* runUpdate(ctx, rows, ...contextEvaluators) {
         // Ensure we're in a transaction before any mutations (lazy/JIT transaction start)
         await ctx.db._ensureTransaction();
         const vtab = await getVTable(ctx, tableSchema);
-        const needsAutoEvents = ctx.db.hasDataListeners() && !hasNativeEventSupport(vtab);
-        // Evaluate mutation context once per statement
-        let contextRow;
-        if (contextEvaluators.length > 0) {
-            contextRow = [];
-            for (const evaluator of contextEvaluators) {
-                const value = await evaluator(ctx);
-                contextRow.push(value);
+        const needsAutoEvents = ctx.db._needsDataEvents() && !moduleHasNativeDataEvents(ctx, tableSchema);
+        const contextRow = await evaluateContextRow(ctx, contextEvaluators);
+        // Per-statement backing-connection cache + deferred full-rebuild set (see runInsert).
+        const backingConnCache = new Map();
+        const deferredRebuilds = new Set();
+        const isFailMode = plan.onConflict === ConflictResolution.FAIL;
+        yield* runWithStatementSavepoints(ctx, vtab, rows, isFailMode, (flatRow) => processUpdateRow(ctx, vtab, needsAutoEvents, flatRow, contextRow, backingConnCache, deferredRebuilds), deferredRebuilds, backingConnCache);
+    }
+    /**
+     * Performs a single row's UPDATE side-effects (RESTRICT pre-check +
+     * vtab.update + REPLACE eviction + bookkeeping + FK actions + events).
+     * Returns the row to yield downstream, or undefined if the row was not
+     * updated (row not found). Throws ConstraintError on violations the executor
+     * cannot recover from; the caller (runWithStatementSavepoints) translates it
+     * for FAIL/ROLLBACK modes.
+     */
+    async function processUpdateRow(ctx, vtab, needsAutoEvents, flatRow, contextRow, backingConnCache, deferredRebuilds) {
+        const oldRow = extractOldRowFromFlat(flatRow, tableSchema.columns.length);
+        const newRow = extractNewRowFromFlat(flatRow, tableSchema.columns.length);
+        const tableKey = `${tableSchema.schemaName}.${tableSchema.name}`;
+        // Extract primary key values from the OLD row (these identify which row to update)
+        const keyValues = pkColumnIndicesInSchema.map(pkColIdx => {
+            if (pkColIdx >= oldRow.length) {
+                throw new QuereusError(`PK column index ${pkColIdx} out of bounds for OLD row length ${oldRow.length} in UPDATE on '${tableSchema.name}'.`, StatusCode.INTERNAL);
             }
+            return oldRow[pkColIdx];
+        });
+        // Build mutation statement if logging is enabled
+        let mutationStatement;
+        if (vtab.wantStatements) {
+            mutationStatement = buildUpdateStatement(tableSchema, newRow, keyValues, contextRow);
         }
-        try {
-            for await (const flatRow of rows) {
-                const oldRow = extractOldRowFromFlat(flatRow, tableSchema.columns.length);
-                const newRow = extractNewRowFromFlat(flatRow, tableSchema.columns.length);
-                // Extract primary key values from the OLD row (these identify which row to update)
-                const keyValues = pkColumnIndicesInSchema.map(pkColIdx => {
-                    if (pkColIdx >= oldRow.length) {
-                        throw new QuereusError(`PK column index ${pkColIdx} out of bounds for OLD row length ${oldRow.length} in UPDATE on '${tableSchema.name}'.`, StatusCode.INTERNAL);
-                    }
-                    return oldRow[pkColIdx];
-                });
-                // Build mutation statement if logging is enabled
-                let mutationStatement;
-                if (vtab.wantStatements) {
-                    mutationStatement = buildUpdateStatement(tableSchema, newRow, keyValues, contextRow);
-                }
-                // Defense-in-depth RESTRICT enforcement: the plan-time `NOT EXISTS`
-                // check is the primary path, but some vtab modules evaluate the
-                // embedded subquery differently from a plain row scan. Pre-walk
-                // the transitive cascade closure so RESTRICTs at any depth fire
-                // BEFORE vtab.update — needed for rowid-mode backends (lamina)
-                // where post-mutation OLD-value scans dereference through the
-                // just-mutated parent and find zero rows.
-                await assertTransitiveRestrictsForParentMutation(ctx.db, tableSchema, 'update', oldRow, newRow);
-                const args = {
-                    operation: 'update',
-                    values: newRow,
-                    oldKeyValues: keyValues,
-                    // Pass undefined when there's no statement-level OR clause so the vtab
-                    // can fall back to per-constraint defaultConflict directives. The memory
-                    // module treats undefined as ABORT when no constraint default is set.
-                    onConflict: plan.onConflict,
-                    mutationStatement
-                };
-                const result = await vtab.update(args);
-                // Handle constraint violations
-                if (isConstraintViolation(result)) {
-                    const baseErr = new ConstraintError(result.message ?? `${result.constraint} constraint failed`, StatusCode.CONSTRAINT);
-                    throw translateConflictError(baseErr, plan.onConflict);
-                }
-                // Skip if row was not updated (row not found returns ok with no row)
-                if (!result.row) {
-                    continue;
-                }
-                // If the UPDATE moved this row onto an occupied PK under REPLACE,
-                // the vtab returns the displaced row. Surface its deletion BEFORE
-                // the move bookkeeping so change tracking, FK cascade, and auto-events
-                // see the same evict-then-move sequence the vtab journals (manager.ts
-                // records delete(newPk, evicted) before the move). Running the
-                // eviction's FK cascade first also avoids ON UPDATE CASCADE pulling
-                // children onto PK_new and then having an unrelated ON DELETE CASCADE
-                // for the evicted row wipe them out.
-                if (result.replacedRow) {
-                    const evictedKeyValues = pkColumnIndicesInSchema.map(idx => result.replacedRow[idx]);
-                    ctx.db._recordDelete(`${tableSchema.schemaName}.${tableSchema.name}`, result.replacedRow, pkColumnIndicesInSchema);
-                    await executeForeignKeyActions(ctx.db, tableSchema, 'delete', result.replacedRow);
-                    if (needsAutoEvents) {
-                        emitAutoDataEvent(ctx, tableSchema, 'delete', evictedKeyValues, [...result.replacedRow]);
-                    }
-                }
-                // Track change (UPDATE): pass full rows so the change capture can
-                // project the columns any active subscription cares about.
-                ctx.db._recordUpdate(`${tableSchema.schemaName}.${tableSchema.name}`, oldRow, newRow, pkColumnIndicesInSchema);
-                // Execute FK cascading actions (CASCADE, SET NULL, SET DEFAULT)
-                await executeForeignKeyActions(ctx.db, tableSchema, 'update', oldRow, newRow);
-                // Emit auto event for modules without native event support
-                if (needsAutoEvents) {
-                    // Compute changed columns
-                    const changedColumns = [];
-                    for (let i = 0; i < tableSchema.columns.length; i++) {
-                        const oldVal = oldRow[i];
-                        const newVal = newRow[i];
-                        if (!sqlValuesEqual(oldVal, newVal)) {
-                            changedColumns.push(tableSchema.columns[i].name);
-                        }
-                    }
-                    emitAutoDataEvent(ctx, tableSchema, 'update', keyValues, [...oldRow], [...newRow], changedColumns);
-                }
-                yield flatRow;
+        // Defense-in-depth RESTRICT enforcement: the plan-time `NOT EXISTS`
+        // check is the primary path, but some vtab modules evaluate the
+        // embedded subquery differently from a plain row scan. Pre-walk
+        // the transitive cascade closure so RESTRICTs at any depth fire
+        // BEFORE vtab.update — needed for rowid-mode backends (lamina)
+        // where post-mutation OLD-value scans dereference through the
+        // just-mutated parent and find zero rows.
+        await assertTransitiveRestrictsForParentMutation(ctx.db, tableSchema, 'update', oldRow, newRow, plan.lensRouted);
+        const args = {
+            operation: 'update',
+            values: newRow,
+            oldKeyValues: keyValues,
+            // Pass undefined when there's no statement-level OR clause so the vtab
+            // can fall back to per-constraint defaultConflict directives. The memory
+            // module treats undefined as ABORT when no constraint default is set.
+            onConflict: plan.onConflict,
+            mutationStatement
+        };
+        const result = await vtab.update(args);
+        // Handle constraint violations — caller translates for FAIL/ROLLBACK.
+        if (isConstraintViolation(result)) {
+            throw new ConstraintError(result.message ?? `${result.constraint} constraint failed`, StatusCode.CONSTRAINT);
+        }
+        // Skip if row was not updated (row not found returns ok with no row)
+        if (!result.row) {
+            return undefined;
+        }
+        // If the UPDATE moved this row onto an occupied PK under REPLACE,
+        // the vtab returns the displaced row. Surface its deletion BEFORE
+        // the move bookkeeping so change tracking, FK cascade, and auto-events
+        // see the same evict-then-move sequence the vtab journals (manager.ts
+        // records delete(newPk, evicted) before the move). Running the
+        // eviction's FK cascade first also avoids ON UPDATE CASCADE pulling
+        // children onto PK_new and then having an unrelated ON DELETE CASCADE
+        // for the evicted row wipe them out.
+        if (result.replacedRow) {
+            const evictedKeyValues = pkColumnIndicesInSchema.map(idx => result.replacedRow[idx]);
+            ctx.db._recordDelete(tableKey, result.replacedRow, pkColumnIndicesInSchema);
+            await maintainRowTimeStructures(ctx, tableKey, { op: 'delete', oldRow: result.replacedRow }, backingConnCache, deferredRebuilds);
+            await executeForeignKeyActionsAndLens(ctx.db, tableSchema, 'delete', result.replacedRow, undefined, plan.lensRouted);
+            if (needsAutoEvents) {
+                emitAutoDataEvent(ctx, tableSchema, 'delete', evictedKeyValues, [...result.replacedRow]);
             }
         }
-        finally {
-            await disconnectVTable(ctx, vtab);
+        // Internal REPLACE evictions (rows at OTHER PKs removed to resolve a non-PK
+        // UNIQUE conflict for this same update) run the full delete pipeline here,
+        // after any same-PK replacedRow handling and before the moved row's own
+        // bookkeeping — evict-then-write, matching the substrate journal order.
+        await processEvictions(ctx, needsAutoEvents, tableKey, result.evictedRows, backingConnCache, deferredRebuilds);
+        // Track change (UPDATE): pass full rows so the change capture can
+        // project the columns any active subscription cares about.
+        ctx.db._recordUpdate(tableKey, oldRow, newRow, pkColumnIndicesInSchema);
+        await maintainRowTimeStructures(ctx, tableKey, { op: 'update', oldRow, newRow }, backingConnCache, deferredRebuilds);
+        // Execute FK cascading actions (CASCADE, SET NULL, SET DEFAULT)
+        await executeForeignKeyActionsAndLens(ctx.db, tableSchema, 'update', oldRow, newRow, plan.lensRouted);
+        // Emit auto event for modules without native event support
+        if (needsAutoEvents) {
+            // Compute changed columns
+            const changedColumns = [];
+            for (let i = 0; i < tableSchema.columns.length; i++) {
+                const oldVal = oldRow[i];
+                const newVal = newRow[i];
+                if (!sqlValuesEqual(oldVal, newVal)) {
+                    changedColumns.push(tableSchema.columns[i].name);
+                }
+            }
+            emitAutoDataEvent(ctx, tableSchema, 'update', keyValues, [...oldRow], [...newRow], changedColumns);
         }
+        return flatRow;
     }
     // DELETE ----------------------------------------------------
     async function* runDelete(ctx, rows, ...contextEvaluators) {
         // Ensure we're in a transaction before any mutations (lazy/JIT transaction start)
         await ctx.db._ensureTransaction();
         const vtab = await getVTable(ctx, tableSchema);
-        const needsAutoEvents = ctx.db.hasDataListeners() && !hasNativeEventSupport(vtab);
-        // Evaluate mutation context once per statement
-        let contextRow;
-        if (contextEvaluators.length > 0) {
-            contextRow = [];
-            for (const evaluator of contextEvaluators) {
-                const value = await evaluator(ctx);
-                contextRow.push(value);
+        const needsAutoEvents = ctx.db._needsDataEvents() && !moduleHasNativeDataEvents(ctx, tableSchema);
+        const contextRow = await evaluateContextRow(ctx, contextEvaluators);
+        // Per-statement backing-connection cache + deferred full-rebuild set (see runInsert).
+        const backingConnCache = new Map();
+        const deferredRebuilds = new Set();
+        const isFailMode = plan.onConflict === ConflictResolution.FAIL;
+        yield* runWithStatementSavepoints(ctx, vtab, rows, isFailMode, (flatRow) => processDeleteRow(ctx, vtab, needsAutoEvents, flatRow, contextRow, backingConnCache, deferredRebuilds), deferredRebuilds, backingConnCache);
+    }
+    /**
+     * Performs a single row's DELETE side-effects (RESTRICT pre-check +
+     * vtab.update + bookkeeping + FK actions + events). Returns the row to yield
+     * downstream, or undefined if the row was not deleted (row not found).
+     * Throws ConstraintError / RESTRICT errors; the caller
+     * (runWithStatementSavepoints) translates constraint violations for
+     * FAIL/ROLLBACK modes.
+     */
+    async function processDeleteRow(ctx, vtab, needsAutoEvents, flatRow, contextRow, backingConnCache, deferredRebuilds) {
+        const oldRow = extractOldRowFromFlat(flatRow, tableSchema.columns.length);
+        const tableKey = `${tableSchema.schemaName}.${tableSchema.name}`;
+        const keyValues = pkColumnIndicesInSchema.map(pkColIdx => {
+            if (pkColIdx >= oldRow.length) {
+                throw new QuereusError(`PK column index ${pkColIdx} out of bounds for OLD row length ${oldRow.length} in DELETE on '${tableSchema.name}'.`, StatusCode.INTERNAL);
             }
+            return oldRow[pkColIdx];
+        });
+        // Build mutation statement if logging is enabled
+        let mutationStatement;
+        if (vtab.wantStatements) {
+            mutationStatement = buildDeleteStatement(tableSchema, keyValues, contextRow);
         }
-        try {
-            for await (const flatRow of rows) {
-                const oldRow = extractOldRowFromFlat(flatRow, tableSchema.columns.length);
-                const keyValues = pkColumnIndicesInSchema.map(pkColIdx => {
-                    if (pkColIdx >= oldRow.length) {
-                        throw new QuereusError(`PK column index ${pkColIdx} out of bounds for OLD row length ${oldRow.length} in DELETE on '${tableSchema.name}'.`, StatusCode.INTERNAL);
-                    }
-                    return oldRow[pkColIdx];
-                });
-                // Build mutation statement if logging is enabled
-                let mutationStatement;
-                if (vtab.wantStatements) {
-                    mutationStatement = buildDeleteStatement(tableSchema, keyValues, contextRow);
-                }
-                // Defense-in-depth RESTRICT enforcement — see comment on the UPDATE
-                // path above.
-                await assertTransitiveRestrictsForParentMutation(ctx.db, tableSchema, 'delete', oldRow);
-                const args = {
-                    operation: 'delete',
-                    values: undefined,
-                    oldKeyValues: keyValues,
-                    onConflict: plan.onConflict ?? ConflictResolution.ABORT,
-                    mutationStatement
-                };
-                const result = await vtab.update(args);
-                // Handle constraint violations (unlikely for DELETE, but be consistent)
-                if (isConstraintViolation(result)) {
-                    const baseErr = new ConstraintError(result.message ?? `${result.constraint} constraint failed`, StatusCode.CONSTRAINT);
-                    throw translateConflictError(baseErr, plan.onConflict);
-                }
-                // Skip if row was not deleted (row not found returns ok with no row)
-                if (!result.row) {
-                    continue;
-                }
-                // Track change (DELETE): record OLD row + PK indices so capture
-                // can project the columns subscribers care about.
-                ctx.db._recordDelete(`${tableSchema.schemaName}.${tableSchema.name}`, oldRow, pkColumnIndicesInSchema);
-                // Execute FK cascading actions (CASCADE, SET NULL, SET DEFAULT)
-                await executeForeignKeyActions(ctx.db, tableSchema, 'delete', oldRow);
-                // Emit auto event for modules without native event support
-                if (needsAutoEvents) {
-                    emitAutoDataEvent(ctx, tableSchema, 'delete', keyValues, [...oldRow]);
-                }
-                yield flatRow;
-            }
+        // Defense-in-depth RESTRICT enforcement — see comment on the UPDATE
+        // path above.
+        await assertTransitiveRestrictsForParentMutation(ctx.db, tableSchema, 'delete', oldRow, undefined, plan.lensRouted);
+        const args = {
+            operation: 'delete',
+            values: undefined,
+            oldKeyValues: keyValues,
+            onConflict: plan.onConflict ?? ConflictResolution.ABORT,
+            mutationStatement
+        };
+        const result = await vtab.update(args);
+        // Handle constraint violations (unlikely for DELETE, but be consistent).
+        if (isConstraintViolation(result)) {
+            throw new ConstraintError(result.message ?? `${result.constraint} constraint failed`, StatusCode.CONSTRAINT);
         }
-        finally {
-            await disconnectVTable(ctx, vtab);
+        // Skip if row was not deleted (row not found returns ok with no row)
+        if (!result.row) {
+            return undefined;
         }
+        // Track change (DELETE): record OLD row + PK indices so capture
+        // can project the columns subscribers care about.
+        ctx.db._recordDelete(tableKey, oldRow, pkColumnIndicesInSchema);
+        await maintainRowTimeStructures(ctx, tableKey, { op: 'delete', oldRow }, backingConnCache, deferredRebuilds);
+        // Execute FK cascading actions (CASCADE, SET NULL, SET DEFAULT)
+        await executeForeignKeyActionsAndLens(ctx.db, tableSchema, 'delete', oldRow, undefined, plan.lensRouted);
+        // Emit auto event for modules without native event support
+        if (needsAutoEvents) {
+            emitAutoDataEvent(ctx, tableSchema, 'delete', keyValues, [...oldRow]);
+        }
+        return flatRow;
     }
     // Select the correct generator based on operation
     let run;