@quereus/quereus 4.3.2 → 4.4.0

package/dist/src/core/database-materialized-views.d.ts

@@ -42,8 +42,8 @@ import { type SqlValue, type Row } from '../common/types.js';
 import type { BackingRowChange } from '../vtab/backing-host.js';
 import type { MaintainedTableSchema } from '../schema/derivation.js';
 import type { UniqueConstraintSchema } from '../schema/table.js';
-import type { MaterializedViewManagerContext, BackingConnectionCache } from './database-materialized-views-plans.js';
-export type { BackingConnectionCache } from './database-materialized-views-plans.js';
+import type { MaterializedViewManagerContext, ResidualKeyBatch, BackingConnectionCache } from './database-materialized-views-plans.js';
+export type { BackingConnectionCache, ResidualKeyBatch } from './database-materialized-views-plans.js';
 export declare class MaterializedViewManager {
     private readonly ctx;
     private unsubscribeSchemaChanges;
@@ -237,48 +237,95 @@ export declare class MaterializedViewManager {
      * too. Omitted by the cold enforcement/eviction callers, which re-resolve the same
      * connection deterministically.
      *
-     * `deferred` is the optional per-statement deferred-rebuild set (MV keys). A
-     * `'full-rebuild'` plan re-evaluates the WHOLE body, so applying it per source row is
-     * O(rows × body) — pathological. When the DML boundary supplies a `deferred` set, a
-     * full-rebuild plan is instead marked dirty here (no per-row apply) and rebuilt exactly
-     * once at the end-of-statement {@link flushDeferredRebuilds} boundary. The bounded-delta
-     * arms stay per-row-immediate (cheap, and the covering-UNIQUE enforcement scan depends on
-     * their per-row backing visibility; a full-rebuild MV is never a covering structure, so
-     * deferring it cannot starve that scan). A cold caller without a `deferred` set falls
-     * through to an inline rebuild — a safe, unamortized fallback that the
-     * enforcement/eviction callers never actually reach (they never name a full-rebuild MV).
+     * `deferred` is the optional per-statement deferred-rebuild set (MV keys) and
+     * `residualBatch` the optional per-statement residual key batch. A `'full-rebuild'`
+     * plan re-evaluates the WHOLE body, so applying it per source row is O(rows × body) —
+     * pathological; when the DML boundary supplies a `deferred` set it is instead marked
+     * dirty here (no per-row apply) and rebuilt exactly once at the end-of-statement
+     * {@link flushDeferredMaintenance} boundary. The three **residual** arms
+     * (`'residual-recompute'`, `'prefix-delete'`, `'join-residual'`) are likewise per-key
+     * recomputes whose per-row apply costs a scheduler run each; when the DML boundary
+     * supplies a `residualBatch`, they accumulate their affected binding keys (deduped
+     * across the statement) and recompute once per distinct key at the same flush.
+     * `'inverse-projection'` alone stays per-row-immediate: its delta is a cheap pure
+     * projection AND the covering-UNIQUE enforcement scan depends on its per-row backing
+     * visibility ({@link lookupCoveringConflicts} reads only inverse-projection backings,
+     * so deferring the other arms cannot starve that scan —
+     * {@link findRowTimeCoveringStructure} declines them). A cold caller without the
+     * per-statement structures falls through to the inline per-change apply — a safe,
+     * unamortized fallback (the enforcement/eviction callers only ever name
+     * inverse-projection MVs, but the fallback stays correct for every arm).
      */
-    maintainRowTime(sourceBase: string, change: BackingRowChange, cache?: BackingConnectionCache, deferred?: Set<string>, depth?: number): Promise<void>;
+    maintainRowTime(sourceBase: string, change: BackingRowChange, cache?: BackingConnectionCache, deferred?: Set<string>, residualBatch?: ResidualKeyBatch, depth?: number): Promise<void>;
     /**
-     * Flush the per-statement deferred full-rebuild set at the end-of-statement boundary:
-     * rebuild every dirtied full-rebuild MV exactly once (not once per source row) and
-     * cascade each rebuild's effective {@link BackingRowChange}(s) onward so MV-over-MV
-     * consumers converge.
+     * The invariant pipeline every realized maintenance delta runs, in order: coarsening
+     * collision telemetry (observe-only; gated on `coarseningWatch`), the NOT-NULL
+     * ordering-seeded-PK guard (no-op unless the MV carries the skew), derived-row
+     * CHECK/FK validation (no-op for a constraint-less table; BEFORE the cascade so a
+     * consumer never consumes an invalid producer row), parent-side referential
+     * enforcement (RESTRICT-walk then declared actions, after `M`'s own image is
+     * validated), then the MV-over-MV cascade — each effective {@link BackingRowChange}
+     * routed back through {@link maintainRowTime} with the SAME per-statement structures,
+     * so a residual consumer accumulates into the batch and a full-rebuild consumer
+     * re-dirties the deferred set. Shared verbatim by the per-row inline path and the
+     * end-of-statement flush ({@link flushDeferredMaintenance}, which calls with
+     * `depth = 0` — its own round bound {@link assertFlushRounds} replaces the recursion
+     * bound {@link assertCascadeDepth} there).
+     */
+    private postApplyBackingChanges;
+    /**
+     * Flush the per-statement deferred maintenance at the end-of-statement boundary:
+     * recompute every accumulated residual key exactly once per distinct key
+     * ({@link applyResidualBatch}) and rebuild every dirtied full-rebuild MV exactly once
+     * (not once per source row), cascading each apply's effective
+     * {@link BackingRowChange}(s) onward so MV-over-MV consumers converge.
      *
-     * Drained as a worklist over the producer→consumer DAG. Each rebuild calls
-     * {@link applyFullRebuild} (re-run the whole body against live mid-transaction source
-     * state → a `'replace-all'` diff) and routes the realized delta back through
-     * {@link maintainRowTime} with the SAME `deferred` set: an incremental consumer applies
-     * inline; a full-rebuild consumer re-dirties into the drain (rebuilt in a later round,
-     * after its producer's delta has landed). The drain proceeds in **rounds** — each round
-     * snapshots the current dirty set, clears it, and rebuilds each member, collecting the
-     * next round's re-dirties — so a consumer is never permanently stale (a producer rebuilt
-     * in the same round re-dirties it for the next), and convergence takes at most one round
-     * per level of the full-rebuild sub-DAG.
+     * Drained as a worklist over the producer→consumer DAG. Each apply routes its realized
+     * delta back through {@link maintainRowTime} with the SAME `deferred` set and
+     * `residualBatch`: an inverse-projection consumer applies inline; a residual consumer
+     * accumulates its keys into the batch and a full-rebuild consumer re-dirties into the
+     * drain (recomputed in a later round, after its producer's delta has landed). The drain
+     * proceeds in **rounds** — each round snapshots both structures, clears them, and
+     * applies each member, collecting the next round's re-accumulations — so a consumer is
+     * never permanently stale (a producer flushed in the same round re-accumulates it for
+     * the next), and convergence takes at most one round per level of the deferred sub-DAG.
+     * Residual entries drain before rebuilds within a round (arbitrary for correctness —
+     * every apply reads live state — but it lets a same-round rebuild read its residual
+     * producers' already-flushed backings, saving a round in mixed chains).
      *
      * Termination: the dependency DAG is acyclic (a consumer MV requires its producer to
-     * pre-exist), so the longest full-rebuild chain — hence the round count — is bounded by
+     * pre-exist), so the longest deferred chain — hence the round count — is bounded by
      * the registered-row-time-MV count. Exceeding it signals a structurally-impossible cycle
      * and fails loud ({@link assertFlushRounds}) — the worklist analogue of
      * {@link assertCascadeDepth}. This should never fire.
      *
      * The DML executor calls this INSIDE the statement-atomicity savepoint (after the row
-     * loop, before the savepoint release), so a failed rebuild rolls the whole statement
-     * back. An empty set is a no-op (no overhead on statements touching no full-rebuild MV).
+     * loop, before the savepoint release), so a failed recompute/rebuild — including a
+     * derived-row validation failure or parent-side RESTRICT over the flushed delta — rolls
+     * the whole statement back with the same attribution as the per-row path. Empty
+     * structures are a no-op (no overhead on statements touching no deferred MV).
      */
-    flushDeferredRebuilds(deferred: Set<string>, cache?: BackingConnectionCache): Promise<void>;
+    flushDeferredMaintenance(deferred: Set<string>, residualBatch: ResidualKeyBatch, cache?: BackingConnectionCache): Promise<void>;
     /**
-     * Round backstop for {@link flushDeferredRebuilds}. The full-rebuild sub-DAG is acyclic,
+     * Flush one residual-arm MV's accumulated statement keys: run the residual variant
+     * once per distinct key against live post-statement state and apply all resulting ops
+     * in one {@link BackingHost.applyMaintenance} call (upsert recomputed slices, delete
+     * emptied keys — the same keyed diff the per-row path applies, evaluated once per key
+     * instead of once per touching row).
+     *
+     * **Per-statement rebuild demotion** ({@link shouldDegradeToRebuild}, re-costed here
+     * against the statement's ACTUAL distinct-key count and the plan's create-time
+     * {@link MaintenancePlanCommon.sourceStats}): when k residual runs cost more than one
+     * whole-body rebuild — a statement touching most groups — run the plan's
+     * {@link ResidualArmCommon.fullRebuildScheduler} and apply a single `'replace-all'`
+     * keyed diff instead. Stateless: the stored strategy is unchanged, so a later
+     * low-cardinality statement reverts to per-key residuals. Kept on the manager
+     * (delegating op computation to the apply-module free helpers) so the statement-flush
+     * suites can instrument it alongside {@link applyFullRebuild}.
+     */
+    private applyResidualBatch;
+    /**
+     * Round backstop for {@link flushDeferredMaintenance}. The full-rebuild sub-DAG is acyclic,
      * so the drain converges in at most one round per chain level — bounded by the row-time
      * MV count. A round count beyond that (`+1` slack for an initial dirty set already
      * spanning multiple levels) signals a structural impossibility (a cycle) — fail loud
@@ -323,13 +370,20 @@ export declare class MaterializedViewManager {
      *
      * Unlike the bounded-delta arms this ignores the specific changed row — the floor
      * rebuilds wholesale. It is therefore deferred to a single end-of-statement flush
-     * ({@link flushDeferredRebuilds}) rather than run per source row, so a bulk statement
+     * ({@link flushDeferredMaintenance}) rather than run per source row, so a bulk statement
      * rebuilds exactly once; this is that one rebuild. An empty body (zero rows) yields a
      * `'replace-all' []`, which empties the backing. Kept on the manager (delegating the
      * scan / backing write to the apply-module free helpers) so the per-statement-flush
      * deferral suite can instrument it to count rebuilds.
      */
     private applyFullRebuild;
+    /**
+     * Run a whole-body scheduler to completion against live mid-transaction source state
+     * and apply the single `'replace-all'` keyed diff. The shared kernel of the
+     * full-rebuild floor ({@link applyFullRebuild}) and the residual arms' per-statement
+     * rebuild demotion ({@link applyResidualBatch}).
+     */
+    private applyReplaceAll;
     /**
      * Resolve the linked, enforcement-ready covering MV for a UNIQUE constraint on
      * `schema.table`, or `undefined`. The constraint's `coveringStructureName`
@@ -337,13 +391,15 @@ export declare class MaterializedViewManager {
      * this confirms a live row-time plan exists for the source, the MV is not
      * `stale` (structural breakage), and the plan is **per-row maintained** — only
      * then is its backing table row-time consistent enough to answer conflict
-     * resolution. A `'full-rebuild'` plan is deferred to the end-of-statement flush
-     * (its backing lags the source mid-statement), so it can never serve as a
-     * covering structure for a synchronous per-row UNIQUE probe — it is skipped here
-     * regardless of any (informational) `coveringStructureName` link, which keeps the
-     * eligibility flip from opening a stale-read enforcement path. O(1) negative fast
-     * path off {@link rowTimeBySource} so a source table with no row-time covering MV
-     * pays a single map lookup and stays on the synchronous index/scan path.
+     * resolution. Only the `'inverse-projection'` arm qualifies: every other arm —
+     * the `'full-rebuild'` floor and the residual arms — is deferred to the
+     * end-of-statement flush (its backing lags the source mid-statement), so it can
+     * never serve as a covering structure for a synchronous per-row UNIQUE probe —
+     * all are skipped here regardless of any (informational) `coveringStructureName`
+     * link, which keeps an eligibility flip from opening a stale-read enforcement
+     * path. O(1) negative fast path off {@link rowTimeBySource} so a source table
+     * with no row-time covering MV pays a single map lookup and stays on the
+     * synchronous index/scan path.
      *
      * **Collation eligibility gate.** A covering MV generates its conflict candidates
      * by re-comparing each backing row under the SOURCE column's DECLARED collation

package/dist/src/core/database-materialized-views.d.ts.map

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

package/dist/src/core/database-materialized-views.js

@@ -48,8 +48,9 @@ import { compareSqlValuesFast, resolveCollationFunctions } from '../util/compari
 import { coveringMvHonorsIndexCollation } from '../schema/unique-enforcement.js';
 import { splitBaseKey } from '../util/qualified-name.js';
 import { mvKey, planSourceBases, isBinaryCollation, } from './database-materialized-views-analysis.js';
+import { shouldDegradeToRebuild } from '../planner/cost/index.js';
 import { buildMaintenancePlan } from './database-materialized-views-plan-builders.js';
-import { applyInverseProjection, applyForwardResidual, applyJoinResidual, applyPrefixDelete, runScheduler, validateDerivedChanges, assertNoNullInNotNullSeededPkRowTime, enforceParentSideReferentialActions, backingHost, getBackingConnection, } from './database-materialized-views-apply.js';
+import { applyInverseProjection, applyForwardResidual, applyJoinResidual, applyPrefixDelete, accumulateResidualKeys, computeResidualBatchOps, computeDeltaAggregateOps, resolveBackingApplyTarget, runScheduler, validateDerivedChanges, assertNoNullInNotNullSeededPkRowTime, enforceParentSideReferentialActions, } from './database-materialized-views-apply.js';
 const log = createLogger('core:materialized-views');
 export class MaterializedViewManager {
     ctx;
@@ -552,18 +553,26 @@ export class MaterializedViewManager {
      * too. Omitted by the cold enforcement/eviction callers, which re-resolve the same
      * connection deterministically.
      *
-     * `deferred` is the optional per-statement deferred-rebuild set (MV keys). A
-     * `'full-rebuild'` plan re-evaluates the WHOLE body, so applying it per source row is
-     * O(rows × body) — pathological. When the DML boundary supplies a `deferred` set, a
-     * full-rebuild plan is instead marked dirty here (no per-row apply) and rebuilt exactly
-     * once at the end-of-statement {@link flushDeferredRebuilds} boundary. The bounded-delta
-     * arms stay per-row-immediate (cheap, and the covering-UNIQUE enforcement scan depends on
-     * their per-row backing visibility; a full-rebuild MV is never a covering structure, so
-     * deferring it cannot starve that scan). A cold caller without a `deferred` set falls
-     * through to an inline rebuild — a safe, unamortized fallback that the
-     * enforcement/eviction callers never actually reach (they never name a full-rebuild MV).
+     * `deferred` is the optional per-statement deferred-rebuild set (MV keys) and
+     * `residualBatch` the optional per-statement residual key batch. A `'full-rebuild'`
+     * plan re-evaluates the WHOLE body, so applying it per source row is O(rows × body) —
+     * pathological; when the DML boundary supplies a `deferred` set it is instead marked
+     * dirty here (no per-row apply) and rebuilt exactly once at the end-of-statement
+     * {@link flushDeferredMaintenance} boundary. The three **residual** arms
+     * (`'residual-recompute'`, `'prefix-delete'`, `'join-residual'`) are likewise per-key
+     * recomputes whose per-row apply costs a scheduler run each; when the DML boundary
+     * supplies a `residualBatch`, they accumulate their affected binding keys (deduped
+     * across the statement) and recompute once per distinct key at the same flush.
+     * `'inverse-projection'` alone stays per-row-immediate: its delta is a cheap pure
+     * projection AND the covering-UNIQUE enforcement scan depends on its per-row backing
+     * visibility ({@link lookupCoveringConflicts} reads only inverse-projection backings,
+     * so deferring the other arms cannot starve that scan —
+     * {@link findRowTimeCoveringStructure} declines them). A cold caller without the
+     * per-statement structures falls through to the inline per-change apply — a safe,
+     * unamortized fallback (the enforcement/eviction callers only ever name
+     * inverse-projection MVs, but the fallback stays correct for every arm).
      */
-    async maintainRowTime(sourceBase, change, cache, deferred, depth = 0) {
+    async maintainRowTime(sourceBase, change, cache, deferred, residualBatch, depth = 0) {
         const changedBase = sourceBase.toLowerCase();
         const keys = this.rowTimeBySource.get(changedBase);
         if (!keys || keys.size === 0)
@@ -572,80 +581,103 @@ export class MaterializedViewManager {
             const plan = this.rowTime.get(key);
             if (!plan)
                 continue;
-            // Full-rebuild is the one deferred arm — mark dirty and drain at flush.
+            // Full-rebuild defers as a dirty mark; the residual arms defer as accumulated
+            // binding keys. Both drain at the end-of-statement flush.
             if (plan.kind === 'full-rebuild' && deferred) {
                 deferred.add(key);
                 continue;
             }
-            const backingChanges = await this.applyMaintenancePlan(plan, change, changedBase, cache);
-            if (backingChanges.length === 0)
+            if (residualBatch && plan.kind !== 'inverse-projection' && plan.kind !== 'full-rebuild') {
+                accumulateResidualKeys(plan, change, changedBase, residualBatch, key);
                 continue;
-            // Row-time coarsening collision telemetry: observe-only over the realized
-            // delta (gated on `coarseningWatch` — a no-op for a non-coarsened MV). Runs
-            // independently of the cascade below; it neither consumes nor reorders the
-            // backing changes routed onward.
-            this.detectAndReportCoarseningCollisions(plan, backingChanges);
-            // Reject a NULL stored into a NOT-NULL ordering-seeded physical-PK backing
-            // column whose source loosened — BEFORE the cascade, so the corruption never
-            // reaches a consumer. No-op (`undefined`) unless this MV carries the skew.
-            assertNoNullInNotNullSeededPkRowTime(plan, backingChanges);
-            // Declared CHECK / child-side FK over the rows this delta wrote — BEFORE
-            // cascading, so a consumer never consumes an invalid producer row. Every
-            // row already in the backing was validated when it entered (the bulk
-            // validation at create/attach seeds the induction), so only the delta is
-            // validated. No-op (`undefined`) for a constraint-less table.
-            if (plan.derivedRowValidator) {
-                await validateDerivedChanges(this.ctx, plan, plan.derivedRowValidator, backingChanges, cache);
-            }
-            // Parent-side referential enforcement: this maintenance delete/key-update of an
-            // `M` row may orphan rows in an ordinary table `C` whose FK references `M`. Fire
-            // the shared engine over the backing delta — RESTRICT-walk then declared actions —
-            // after `M`'s own image is validated, before the MV-over-MV cascade. Runs whether
-            // or not `M` has MV consumers (placed before the leaf fast-path).
-            await enforceParentSideReferentialActions(this.ctx, plan, backingChanges);
-            const backingBase = `${plan.backingSchema}.${plan.backingTableName}`.toLowerCase();
-            if (!this.rowTimeBySource.has(backingBase))
-                continue; // leaf — no dependents
-            this.assertCascadeDepth(depth + 1, backingBase);
-            for (const bc of backingChanges) {
-                await this.maintainRowTime(backingBase, bc, cache, deferred, depth + 1);
             }
+            const backingChanges = await this.applyMaintenancePlan(plan, change, changedBase, cache);
+            await this.postApplyBackingChanges(plan, backingChanges, cache, deferred, residualBatch, depth + 1);
         }
     }
     /**
-     * Flush the per-statement deferred full-rebuild set at the end-of-statement boundary:
-     * rebuild every dirtied full-rebuild MV exactly once (not once per source row) and
-     * cascade each rebuild's effective {@link BackingRowChange}(s) onward so MV-over-MV
-     * consumers converge.
+     * The invariant pipeline every realized maintenance delta runs, in order: coarsening
+     * collision telemetry (observe-only; gated on `coarseningWatch`), the NOT-NULL
+     * ordering-seeded-PK guard (no-op unless the MV carries the skew), derived-row
+     * CHECK/FK validation (no-op for a constraint-less table; BEFORE the cascade so a
+     * consumer never consumes an invalid producer row), parent-side referential
+     * enforcement (RESTRICT-walk then declared actions, after `M`'s own image is
+     * validated), then the MV-over-MV cascade — each effective {@link BackingRowChange}
+     * routed back through {@link maintainRowTime} with the SAME per-statement structures,
+     * so a residual consumer accumulates into the batch and a full-rebuild consumer
+     * re-dirties the deferred set. Shared verbatim by the per-row inline path and the
+     * end-of-statement flush ({@link flushDeferredMaintenance}, which calls with
+     * `depth = 0` — its own round bound {@link assertFlushRounds} replaces the recursion
+     * bound {@link assertCascadeDepth} there).
+     */
+    async postApplyBackingChanges(plan, backingChanges, cache, deferred, residualBatch, depth) {
+        if (backingChanges.length === 0)
+            return;
+        this.detectAndReportCoarseningCollisions(plan, backingChanges);
+        assertNoNullInNotNullSeededPkRowTime(plan, backingChanges);
+        if (plan.derivedRowValidator) {
+            await validateDerivedChanges(this.ctx, plan, plan.derivedRowValidator, backingChanges, cache);
+        }
+        await enforceParentSideReferentialActions(this.ctx, plan, backingChanges);
+        const backingBase = `${plan.backingSchema}.${plan.backingTableName}`.toLowerCase();
+        if (!this.rowTimeBySource.has(backingBase))
+            return; // leaf — no dependents
+        if (depth > 0)
+            this.assertCascadeDepth(depth, backingBase);
+        for (const bc of backingChanges) {
+            await this.maintainRowTime(backingBase, bc, cache, deferred, residualBatch, depth);
+        }
+    }
+    /**
+     * Flush the per-statement deferred maintenance at the end-of-statement boundary:
+     * recompute every accumulated residual key exactly once per distinct key
+     * ({@link applyResidualBatch}) and rebuild every dirtied full-rebuild MV exactly once
+     * (not once per source row), cascading each apply's effective
+     * {@link BackingRowChange}(s) onward so MV-over-MV consumers converge.
      *
-     * Drained as a worklist over the producer→consumer DAG. Each rebuild calls
-     * {@link applyFullRebuild} (re-run the whole body against live mid-transaction source
-     * state → a `'replace-all'` diff) and routes the realized delta back through
-     * {@link maintainRowTime} with the SAME `deferred` set: an incremental consumer applies
-     * inline; a full-rebuild consumer re-dirties into the drain (rebuilt in a later round,
-     * after its producer's delta has landed). The drain proceeds in **rounds** — each round
-     * snapshots the current dirty set, clears it, and rebuilds each member, collecting the
-     * next round's re-dirties — so a consumer is never permanently stale (a producer rebuilt
-     * in the same round re-dirties it for the next), and convergence takes at most one round
-     * per level of the full-rebuild sub-DAG.
+     * Drained as a worklist over the producer→consumer DAG. Each apply routes its realized
+     * delta back through {@link maintainRowTime} with the SAME `deferred` set and
+     * `residualBatch`: an inverse-projection consumer applies inline; a residual consumer
+     * accumulates its keys into the batch and a full-rebuild consumer re-dirties into the
+     * drain (recomputed in a later round, after its producer's delta has landed). The drain
+     * proceeds in **rounds** — each round snapshots both structures, clears them, and
+     * applies each member, collecting the next round's re-accumulations — so a consumer is
+     * never permanently stale (a producer flushed in the same round re-accumulates it for
+     * the next), and convergence takes at most one round per level of the deferred sub-DAG.
+     * Residual entries drain before rebuilds within a round (arbitrary for correctness —
+     * every apply reads live state — but it lets a same-round rebuild read its residual
+     * producers' already-flushed backings, saving a round in mixed chains).
      *
      * Termination: the dependency DAG is acyclic (a consumer MV requires its producer to
-     * pre-exist), so the longest full-rebuild chain — hence the round count — is bounded by
+     * pre-exist), so the longest deferred chain — hence the round count — is bounded by
      * the registered-row-time-MV count. Exceeding it signals a structurally-impossible cycle
      * and fails loud ({@link assertFlushRounds}) — the worklist analogue of
      * {@link assertCascadeDepth}. This should never fire.
      *
      * The DML executor calls this INSIDE the statement-atomicity savepoint (after the row
-     * loop, before the savepoint release), so a failed rebuild rolls the whole statement
-     * back. An empty set is a no-op (no overhead on statements touching no full-rebuild MV).
+     * loop, before the savepoint release), so a failed recompute/rebuild — including a
+     * derived-row validation failure or parent-side RESTRICT over the flushed delta — rolls
+     * the whole statement back with the same attribution as the per-row path. Empty
+     * structures are a no-op (no overhead on statements touching no deferred MV).
      */
-    async flushDeferredRebuilds(deferred, cache) {
+    async flushDeferredMaintenance(deferred, residualBatch, cache) {
         let round = 0;
-        while (deferred.size > 0) {
+        while (deferred.size > 0 || residualBatch.size > 0) {
             this.assertFlushRounds(++round);
-            const batch = [...deferred];
+            const residuals = [...residualBatch.entries()];
+            residualBatch.clear();
+            const rebuilds = [...deferred];
             deferred.clear();
-            for (const key of batch) {
+            for (const [key, entry] of residuals) {
+                const plan = this.rowTime.get(key);
+                // Only residual-arm plans ever accumulate keys; a plan released (or
+                // re-registered as a different arm) mid-statement is a no-op here.
+                if (!plan || plan.kind === 'inverse-projection' || plan.kind === 'full-rebuild')
+                    continue;
+                const backingChanges = await this.applyResidualBatch(plan, entry, cache);
+                await this.postApplyBackingChanges(plan, backingChanges, cache, deferred, residualBatch, 0);
+            }
+            for (const key of rebuilds) {
                 const plan = this.rowTime.get(key);
                 // Only full-rebuild plans are ever deferred; a non-full-rebuild key (or a
                 // plan released mid-flush) is a no-op. Defensive — `maintainRowTime` only
@@ -653,41 +685,58 @@ export class MaterializedViewManager {
                 if (!plan || plan.kind !== 'full-rebuild')
                     continue;
                 const backingChanges = await this.applyFullRebuild(plan, cache);
-                if (backingChanges.length === 0)
-                    continue;
-                // Coarsening collision telemetry over the rebuild diff — the full-rebuild
-                // floor's collation-keyed `replace-all` realizes the same LWW merge as the
-                // bounded-delta arms (observe-only; gated on `coarseningWatch`).
-                this.detectAndReportCoarseningCollisions(plan, backingChanges);
-                // NOT-NULL ordering-seeded PK guard over the rebuild diff — the
-                // full-rebuild-floor analogue of the per-row guard in {@link maintainRowTime}.
-                // No-op (`undefined`) unless this MV carries the skew.
-                assertNoNullInNotNullSeededPkRowTime(plan, backingChanges);
-                // Validate the rebuild diff's written images at the flush boundary —
-                // the full-rebuild analogue of the per-row validation in
-                // {@link maintainRowTime} (deferred-rebuild semantics preserved: a bulk
-                // source write fails once at end-of-statement, not per source row).
-                if (plan.derivedRowValidator) {
-                    await validateDerivedChanges(this.ctx, plan, plan.derivedRowValidator, backingChanges, cache);
-                }
-                // Parent-side referential enforcement for the rebuild diff's deletes/key-updates,
-                // fired inside the statement-atomicity savepoint (the flush runs before its
-                // release) so a RESTRICT failure or cascade error unwinds the whole statement.
-                await enforceParentSideReferentialActions(this.ctx, plan, backingChanges);
-                const backingBase = `${plan.backingSchema}.${plan.backingTableName}`.toLowerCase();
-                if (!this.rowTimeBySource.has(backingBase))
-                    continue; // leaf — no dependents
-                for (const bc of backingChanges) {
-                    // Cascade at depth 0: an incremental consumer applies inline (its own
-                    // `assertCascadeDepth` backstops that recursion); a full-rebuild consumer
-                    // re-dirties `deferred` for the next round.
-                    await this.maintainRowTime(backingBase, bc, cache, deferred);
-                }
+                await this.postApplyBackingChanges(plan, backingChanges, cache, deferred, residualBatch, 0);
             }
         }
     }
     /**
-     * Round backstop for {@link flushDeferredRebuilds}. The full-rebuild sub-DAG is acyclic,
+     * Flush one residual-arm MV's accumulated statement keys: run the residual variant
+     * once per distinct key against live post-statement state and apply all resulting ops
+     * in one {@link BackingHost.applyMaintenance} call (upsert recomputed slices, delete
+     * emptied keys — the same keyed diff the per-row path applies, evaluated once per key
+     * instead of once per touching row).
+     *
+     * **Per-statement rebuild demotion** ({@link shouldDegradeToRebuild}, re-costed here
+     * against the statement's ACTUAL distinct-key count and the plan's create-time
+     * {@link MaintenancePlanCommon.sourceStats}): when k residual runs cost more than one
+     * whole-body rebuild — a statement touching most groups — run the plan's
+     * {@link ResidualArmCommon.fullRebuildScheduler} and apply a single `'replace-all'`
+     * keyed diff instead. Stateless: the stored strategy is unchanged, so a later
+     * low-cardinality statement reverts to per-key residuals. Kept on the manager
+     * (delegating op computation to the apply-module free helpers) so the statement-flush
+     * suites can instrument it alongside {@link applyFullRebuild}.
+     */
+    async applyResidualBatch(plan, entry, cache) {
+        const distinctKeys = entry.forward.size + entry.lookup.size + entry.prefix.size;
+        if (distinctKeys === 0)
+            return [];
+        // Delta-aggregate fast path: an eligible aggregate MV's accumulated per-group
+        // deltas are applied by arithmetic read-modify-write on the stored group rows
+        // (computeDeltaAggregateOps) — zero source reads. It BYPASSES the
+        // degrade-to-rebuild crossover below: that crossover trades k residual
+        // re-executions against one whole-body rebuild, and the delta path already
+        // costs O(affected groups) with no residual runs, so the rebuild can never win.
+        // A poisoned accumulation (OR FAIL per-row revert — see
+        // poisonResidualDeltaAccumulations) has `delta` dropped and falls through to
+        // the plain residual over the always-accumulated forward keys.
+        if (plan.kind === 'residual-recompute' && plan.delta && entry.delta && !entry.deltaPoisoned) {
+            const { host, connection } = await resolveBackingApplyTarget(this.ctx, plan, cache);
+            const ops = await computeDeltaAggregateOps(this.ctx, plan, entry, host, connection);
+            if (ops.length === 0)
+                return [];
+            return host.applyMaintenance(connection, ops);
+        }
+        if (plan.fullRebuildScheduler && shouldDegradeToRebuild(distinctKeys, plan.sourceStats)) {
+            return this.applyReplaceAll(plan, plan.fullRebuildScheduler, cache);
+        }
+        const { host, connection } = await resolveBackingApplyTarget(this.ctx, plan, cache);
+        const ops = await computeResidualBatchOps(this.ctx, plan, entry, host, connection);
+        if (ops.length === 0)
+            return [];
+        return host.applyMaintenance(connection, ops);
+    }
+    /**
+     * Round backstop for {@link flushDeferredMaintenance}. The full-rebuild sub-DAG is acyclic,
      * so the drain converges in at most one round per chain level — bounded by the row-time
      * MV count. A round count beyond that (`+1` slack for an initial dirty set already
      * spanning multiple levels) signals a structural impossibility (a cycle) — fail loud
@@ -763,20 +812,24 @@ export class MaterializedViewManager {
      *
      * Unlike the bounded-delta arms this ignores the specific changed row — the floor
      * rebuilds wholesale. It is therefore deferred to a single end-of-statement flush
-     * ({@link flushDeferredRebuilds}) rather than run per source row, so a bulk statement
+     * ({@link flushDeferredMaintenance}) rather than run per source row, so a bulk statement
      * rebuilds exactly once; this is that one rebuild. An empty body (zero rows) yields a
      * `'replace-all' []`, which empties the backing. Kept on the manager (delegating the
      * scan / backing write to the apply-module free helpers) so the per-statement-flush
      * deferral suite can instrument it to count rebuilds.
      */
     async applyFullRebuild(plan, cache) {
-        const rows = await runScheduler(this.ctx, plan.bodyScheduler, {});
-        const backing = this.ctx.schemaManager.getTable(plan.backingSchema, plan.backingTableName);
-        if (!backing) {
-            throw new QuereusError(`Internal error: backing table '${plan.backingTableName}' for materialized view '${plan.mv.name}' not found`, StatusCode.INTERNAL);
-        }
-        const host = backingHost(this.ctx, backing);
-        const connection = await getBackingConnection(this.ctx, host, `${plan.backingSchema}.${plan.backingTableName}`, cache);
+        return this.applyReplaceAll(plan, plan.bodyScheduler, cache);
+    }
+    /**
+     * Run a whole-body scheduler to completion against live mid-transaction source state
+     * and apply the single `'replace-all'` keyed diff. The shared kernel of the
+     * full-rebuild floor ({@link applyFullRebuild}) and the residual arms' per-statement
+     * rebuild demotion ({@link applyResidualBatch}).
+     */
+    async applyReplaceAll(plan, bodyScheduler, cache) {
+        const rows = await runScheduler(this.ctx, bodyScheduler, {});
+        const { host, connection } = await resolveBackingApplyTarget(this.ctx, plan, cache);
         return host.applyMaintenance(connection, [{ kind: 'replace-all', rows }]);
     }
     /* ──────────────── row-time covering enforcement ──────────────── */
@@ -787,13 +840,15 @@ export class MaterializedViewManager {
      * this confirms a live row-time plan exists for the source, the MV is not
      * `stale` (structural breakage), and the plan is **per-row maintained** — only
      * then is its backing table row-time consistent enough to answer conflict
-     * resolution. A `'full-rebuild'` plan is deferred to the end-of-statement flush
-     * (its backing lags the source mid-statement), so it can never serve as a
-     * covering structure for a synchronous per-row UNIQUE probe — it is skipped here
-     * regardless of any (informational) `coveringStructureName` link, which keeps the
-     * eligibility flip from opening a stale-read enforcement path. O(1) negative fast
-     * path off {@link rowTimeBySource} so a source table with no row-time covering MV
-     * pays a single map lookup and stays on the synchronous index/scan path.
+     * resolution. Only the `'inverse-projection'` arm qualifies: every other arm —
+     * the `'full-rebuild'` floor and the residual arms — is deferred to the
+     * end-of-statement flush (its backing lags the source mid-statement), so it can
+     * never serve as a covering structure for a synchronous per-row UNIQUE probe —
+     * all are skipped here regardless of any (informational) `coveringStructureName`
+     * link, which keeps an eligibility flip from opening a stale-read enforcement
+     * path. O(1) negative fast path off {@link rowTimeBySource} so a source table
+     * with no row-time covering MV pays a single map lookup and stays on the
+     * synchronous index/scan path.
      *
      * **Collation eligibility gate.** A covering MV generates its conflict candidates
      * by re-comparing each backing row under the SOURCE column's DECLARED collation
@@ -829,9 +884,11 @@ export class MaterializedViewManager {
             const mv = plan.mv;
             if (mv.name !== mvName)
                 continue; // must be THE linked covering MV
-            // A deferred full-rebuild MV is not per-row consistent (reconciled only at
-            // the end-of-statement flush), so it cannot answer a synchronous probe.
-            if (plan.chosenStrategy === 'full-rebuild')
+            // Only the inverse-projection arm is per-row maintained; every other arm —
+            // the full-rebuild floor AND the residual arms — is reconciled at the
+            // end-of-statement flush, so its backing lags the source mid-statement and
+            // cannot answer a synchronous per-row UNIQUE probe.
+            if (plan.kind !== 'inverse-projection')
                 return undefined;
             if (mv.derivation.stale)
                 return undefined; // not row-time consistent
@@ -937,8 +994,7 @@ export class MaterializedViewManager {
         const backing = this.ctx.schemaManager.getTable(plan.backingSchema, plan.backingTableName);
         if (!backing)
             return [];
-        const host = backingHost(this.ctx, backing);
-        const connection = await getBackingConnection(this.ctx, host, `${plan.backingSchema}.${plan.backingTableName}`);
+        const { host, connection } = await resolveBackingApplyTarget(this.ctx, plan);
         // Both comparisons below run per scanned backing row, so resolve their collations
         // once here, against this database (a redefined NOCASE must be honored).
         //