@quereus/quereus 4.3.2 → 4.4.0

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

@@ -6,13 +6,14 @@
  * the sole caller in the manager is `registerMaterializedView` → {@link buildMaintenancePlan}.
  */
 import { BlockNode } from '../planner/nodes/block.js';
+import { type ScalarPlanNode } from '../planner/nodes/plan-node.js';
 import { TableReferenceNode } from '../planner/nodes/reference.js';
 import { Scheduler } from '../runtime/scheduler.js';
 import { type MaintenanceSourceStats } from '../planner/cost/index.js';
 import type { MaintainedTableSchema } from '../schema/derivation.js';
 import type { TableSchema } from '../schema/table.js';
 import { type AggregateLike } from './database-materialized-views-analysis.js';
-import type { MaterializedViewManagerContext, MaintenancePlan, FullRebuildPlan } from './database-materialized-views-plans.js';
+import type { MaterializedViewManagerContext, MaintenancePlan, FullRebuildPlan, BackingPkColumn, DeltaAggregateDescriptor } from './database-materialized-views-plans.js';
 /**
  * Build the row-time maintenance plan for an MV — **cost-gated, with a floor, never a
  * shape allowlist**. The builder tries to match a bounded-delta arm by shape
@@ -86,6 +87,69 @@ export declare function buildInverseProjectionPlan(ctx: MaterializedViewManagerC
  * the backing is keyed by the group key regardless of whether it is a source key.
  */
 export declare function buildAggregateResidualPlan(ctx: MaterializedViewManagerContext, mv: MaintainedTableSchema, analyzed: BlockNode, tableRef: TableReferenceNode, sourceBase: string, aggregate: AggregateLike): MaintenancePlan | null;
+/**
+ * Build the {@link DeltaAggregateDescriptor} for a single-source aggregate body, or
+ * return `undefined` when any column fails the delta eligibility gate (the arm then
+ * stays a plain residual — a gate failure is never an error). Function-generic by
+ * construction: every judgment reads the aggregate call node's registry-resolved
+ * schema and its DECLARED {@link AggregateAlgebra} — never an aggregate-name list.
+ *
+ * The gate, per stored backing column:
+ *  - a **group-key passthrough** column must resolve (transitively) to a GROUP BY
+ *    source column that also backs a backing-PK position (so its flush value is the
+ *    group key itself);
+ *  - a directly **delta-maintainable aggregate** column must be a plain call (`agg(x)` /
+ *    `agg()` — no DISTINCT, FILTER, ORDER BY, multi-arg) whose declared algebra has
+ *    `merge` + `negate` + `decode`, with a **bare source column** argument (the delta
+ *    steps the raw value);
+ *  - **exact value domain**: the aggregate's declared return type is INTEGER-physical
+ *    (count-shaped — exact regardless of argument), OR its argument column's static
+ *    type is INTEGER-physical (integer sum). A REAL/NUMERIC/TEXT sum drifts under
+ *    repeated add/subtract and would diverge byte-exactly from the live re-evaluation
+ *    the oracle compares against — such a column disqualifies the whole MV (residual);
+ *  - a **tighten-only** column (min/max, and any UDAF whose merge is a join-semilattice
+ *    like `bit_or`/`bool_or`) — a plain call declaring `merge` + `decode` but NO `negate`
+ *    — is admitted with `deltaClass: 'tighten'`. It needs no exact-value-domain gate
+ *    (merge is idempotent selection, not accumulating arithmetic → no drift) and is never
+ *    retraction-safe: an insert `merge`s the new value in cheaply, but a retracted group
+ *    re-derives wholesale from the residual (via the descriptor's `hasTighten`) rather
+ *    than trusting the arithmetic;
+ *  - a **decomposition-maintained** column (the avg class) — a plain call whose algebra
+ *    declares `decompose` (a scalar formula over sibling partials, e.g. avg ≡ sum/count)
+ *    but is not itself directly maintainable — is admitted only when EVERY partial it
+ *    names ({@link resolveDecomposePartial}) is also stored as a sibling column of this
+ *    same body and is itself delta-maintainable. It carries no independent accumulation;
+ *    at flush its value is `combine([finalized(partial) …])`. If any partial is missing
+ *    or not delta-maintainable the whole MV falls to residual (avg is the first client of
+ *    this class, not a special case);
+ *  - any other column shape (a constant, an expression over the group key, …) fails.
+ *
+ * Whole-body requirements:
+ *  - **no post-aggregate filter** (HAVING, or an outer WHERE over the aggregate
+ *    output): such a filter breaks the arithmetic invariant "stored row == the
+ *    group's full accumulator" — a filtered-out group has contributions but no
+ *    stored row, so a later delta would rebuild it from the identity and understate
+ *    the aggregate. The residual re-evaluates the filter per group and stays exact;
+ *  - a **count(*) multiplicity witness** — a zero-arg delta-maintainable column with
+ *    `decodeExact` (its stored value must reconstruct exactly, since it decides group
+ *    emptiness under retraction). Without it, emptiness cannot be told from an
+ *    all-NULL sum;
+ *  - **BINARY collations** on every backing-PK (group key) column: the flush's stored-
+ *    row read is the host's `scanEffective` equality-prefix seek, whose prefix compare
+ *    is binary (scan-layer.ts). Unlike the prefix-delete arm there is no source-PK
+ *    uniqueness collapsing collation classes to one byte form here, so a non-BINARY
+ *    group key could miss a collation-equal / byte-different stored row — residual
+ *    instead;
+ *  - a body WHERE (if any) must compile to a single-source-row predicate
+ *    (`compilePredicate`) so per-row contributions can be scoped exactly.
+ *
+ * Per-column `retractionSafe` (see {@link DeltaAggregateColumn}) is recorded rather
+ * than gated: a not-retraction-safe descriptor still serves the bulk-insert fast path,
+ * and the flush re-derives only the retracted groups through the residual.
+ */
+export declare function buildDeltaAggregateDescriptor(mv: MaintainedTableSchema, analyzed: BlockNode, tableRef: TableReferenceNode, groupColumns: readonly number[], backingPkDefinition: ReadonlyArray<BackingPkColumn>, backingPkSourceCols: readonly number[], rootAttrs: ReadonlyArray<{
+    id: number;
+} | undefined>, sourceAttrToCol: Map<number, number>, producingByAttrId: Map<number, ScalarPlanNode>): DeltaAggregateDescriptor | undefined;
 /**
  * Build a `'join-residual'` plan for a provably-1:1 row-preserving **inner/cross join**
  * body (`select … from T join P on T.fk = P.id`), or return `null` on a shape mismatch

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

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

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

@@ -8,6 +8,9 @@
 import { QuereusError } from '../common/errors.js';
 import { StatusCode } from '../common/types.js';
 import { ColumnReferenceNode } from '../planner/nodes/reference.js';
+import { AggregateFunctionCallNode } from '../planner/nodes/aggregate-function.js';
+import { isAggregateFunctionSchema } from '../schema/function.js';
+import { PhysicalType } from '../types/logical-type.js';
 import { checkDeterministic } from '../planner/validation/determinism-validator.js';
 import { emitPlanNode } from '../runtime/emitters.js';
 import { EmissionContext } from '../runtime/emission-context.js';
@@ -21,11 +24,17 @@ import { CapabilityDetectors } from '../planner/framework/characteristics.js';
 import { selectMaintenanceStrategy, isFullRebuildPathological, seqScanCost, filterCost, projectCost, } from '../planner/cost/index.js';
 import { tryResolveBackingHost } from '../runtime/emit/materialized-view-helpers.js';
 import { compilePredicate } from '../vtab/memory/utils/predicate.js';
-import { findNonReplicableFunction, findNonReplicableCollation, findNonDeterministic, normalizeCollation, findAggregate, containsNodeType, containsAnyJoin, countNodeType, countJoins, findTableFunctionCall, collectTableRefs, collectProducingExprs, resolveTransitiveSourceCol, bodyWhereReferencesLookup, bodyWhereIsNonDeterministic, relationalAttributes, rootRelationalNode, cannotMaterialize, nonReplicableDerivationError, nonReplicableCollationDerivationError, isSingleRowEvaluable, compileSourceRowEvaluator, } from './database-materialized-views-analysis.js';
+import { findNonReplicableFunction, findNonReplicableCollation, findNonDeterministic, normalizeCollation, isBinaryCollation, findAggregate, containsNodeType, containsAnyJoin, countNodeType, countJoins, findTableFunctionCall, collectTableRefs, collectProducingExprs, resolveTransitiveSourceCol, bodyWhereReferencesLookup, bodyWhereIsNonDeterministic, relationalAttributes, rootRelationalNode, cannotMaterialize, nonReplicableDerivationError, nonReplicableCollationDerivationError, isSingleRowEvaluable, compileSourceRowEvaluator, } from './database-materialized-views-analysis.js';
 import { BINARY_COLLATION } from '../util/comparison.js';
 /** Fallback source row estimate when the StatsProvider has no count (mirrors the
  *  optimizer's naive default). Only feeds the create-time maintenance cost gate. */
 const DEFAULT_SOURCE_ROWS = 1000;
+/** Create-time estimate of the fraction of changes to a **tighten-only** (min/max) delta
+ *  aggregate that retract (a delete / update-old-image) and so re-derive their group from
+ *  the key-filtered residual instead of pure arithmetic. Feeds the `'delta-aggregate'` cost
+ *  blend ({@link maintenanceCost}); kept well below 1 so an insert-dominated body still
+ *  prefers the delta arm, yet non-zero so a tighten body costs more than a pure-group one. */
+const DELTA_TIGHTEN_FALLBACK_RATIO = 0.25;
 /**
  * Snapshot a backing table's physical primary key as the maintenance plans consume it: the
  * declared `(index, desc, collation)` triple plus the collation comparator that name resolves
@@ -123,6 +132,18 @@ export function buildMaintenancePlan(ctx, mv) {
     }
     // Try a bounded-delta arm; a shape that fits none falls through to the floor.
     const boundedDelta = tryBuildBoundedDeltaArm(ctx, mv, analyzed);
+    // A residual arm additionally carries the whole-body scheduler — the per-statement
+    // degrade-to-rebuild escape: when a statement's distinct affected-key count makes k
+    // residual runs cost more than one rebuild (`shouldDegradeToRebuild`), the flush runs
+    // this and applies a single `'replace-all'` diff instead. Compiled here (not per arm
+    // builder) so the three residual arms share one compilation site; inverse-projection
+    // never degrades (always the cheapest arm) and the floor has its own bodyScheduler.
+    // NOTE: adds one whole-body optimize+emit per residual-MV (re)registration; if
+    // registration latency ever matters (e.g. bulk catalog import), compile this lazily
+    // on the first degrade instead.
+    if (boundedDelta && boundedDelta.kind !== 'inverse-projection' && boundedDelta.kind !== 'full-rebuild') {
+        boundedDelta.fullRebuildScheduler = compileWholeBodyScheduler(ctx, analyzed);
+    }
     const plan = boundedDelta ?? buildFullRebuildPlan(ctx, mv, analyzed);
     // Precompute the NOT-NULL ordering-seeded PK skew guard once, here at plan build —
     // which `alter … drop not null` re-runs (it recompiles the row-time plan live), so the
@@ -471,17 +492,33 @@ export function buildAggregateResidualPlan(ctx, mv, analyzed, tableRef, sourceBa
     const residualScheduler = compileResidual(ctx, analyzed, relKey, groupColumns, 'gk');
     if (!residualScheduler)
         return null; // could not parameterize the residual → floor
+    // Delta-aggregate fast path: build the descriptor when EVERY stored aggregate
+    // column is delta-maintainable by its declared algebra (see the builder below).
+    // `undefined` on any gate failure — the arm then stays a plain residual, unchanged.
+    const delta = buildDeltaAggregateDescriptor(mv, analyzed, tableRef, groupColumns, backingPkDefinition, backingPkSourceCols, rootAttrs, sourceAttrToCol, producingByAttrId);
     // ── Cost gate ──
     // The residual is the structurally-sound incremental arm for an aggregate body;
     // 'full-rebuild' is the always-correct floor for shapes where the residual is NOT
-    // sound, so (as with inverse-projection) it is not a competitor here. We still
-    // record the chosen strategy + cost inputs for parity with the substrate.
-    const soundStrategies = ['residual-recompute'];
+    // sound, so (as with inverse-projection) it is not a competitor here. When the delta
+    // descriptor built, 'delta-aggregate' joins the sound set — an O(1)-per-change
+    // arithmetic RMW, strictly cheaper than the per-group residual under the cost model,
+    // so the argmin picks it. The descriptor is attached only when the gate chose it
+    // (cost-strategy decoupling: `kind` stays 'residual-recompute' either way).
+    const soundStrategies = delta
+        ? ['delta-aggregate', 'residual-recompute']
+        : ['residual-recompute'];
     const hasPredicate = mv.derivation.selectAst.type === 'select' && mv.derivation.selectAst.where !== undefined;
     const sourceStats = estimateMaintenanceStats(ctx, tableRef.tableSchema, backing.columns.length, hasPredicate);
+    // A tighten-only (min/max) column re-derives a retracted group from the residual, so the
+    // delta arm's cost is no longer pure arithmetic — feed the create-time expected-rescan
+    // fraction into the `'delta-aggregate'` cost blend (maintenanceCost). A tighten body then
+    // costs strictly more than a pure-group body but, for this insert-dominated estimate, still
+    // below the always-residual arm, so the argmin keeps the delta arm.
+    if (delta?.hasTighten)
+        sourceStats.deltaTightenFallbackRatio = DELTA_TIGHTEN_FALLBACK_RATIO;
     const estimatedChangeCardinality = Math.max(1, sourceStats.tableRows * 0.01);
     const chosenStrategy = selectMaintenanceStrategy(soundStrategies, estimatedChangeCardinality, sourceStats);
-    if (chosenStrategy !== 'residual-recompute') {
+    if (!soundStrategies.includes(chosenStrategy)) {
         throw new QuereusError(`Internal error: cost gate selected unwired strategy '${chosenStrategy}' for materialized view '${mv.name}'`, StatusCode.INTERNAL);
     }
     return {
@@ -493,14 +530,306 @@ export function buildAggregateResidualPlan(ctx, mv, analyzed, tableRef, sourceBa
         chosenStrategy,
         sourceStats,
         binding: { kind: 'group', groupColumns: [...groupColumns] },
-        degradeToRebuild: false,
         residualScheduler,
         bindParamPrefix: 'gk',
         bindColumns: groupColumns,
         backingPkDefinition,
         backingPkSourceCols,
+        delta: chosenStrategy === 'delta-aggregate' ? delta : undefined,
     };
 }
+/**
+ * Build the {@link DeltaAggregateDescriptor} for a single-source aggregate body, or
+ * return `undefined` when any column fails the delta eligibility gate (the arm then
+ * stays a plain residual — a gate failure is never an error). Function-generic by
+ * construction: every judgment reads the aggregate call node's registry-resolved
+ * schema and its DECLARED {@link AggregateAlgebra} — never an aggregate-name list.
+ *
+ * The gate, per stored backing column:
+ *  - a **group-key passthrough** column must resolve (transitively) to a GROUP BY
+ *    source column that also backs a backing-PK position (so its flush value is the
+ *    group key itself);
+ *  - a directly **delta-maintainable aggregate** column must be a plain call (`agg(x)` /
+ *    `agg()` — no DISTINCT, FILTER, ORDER BY, multi-arg) whose declared algebra has
+ *    `merge` + `negate` + `decode`, with a **bare source column** argument (the delta
+ *    steps the raw value);
+ *  - **exact value domain**: the aggregate's declared return type is INTEGER-physical
+ *    (count-shaped — exact regardless of argument), OR its argument column's static
+ *    type is INTEGER-physical (integer sum). A REAL/NUMERIC/TEXT sum drifts under
+ *    repeated add/subtract and would diverge byte-exactly from the live re-evaluation
+ *    the oracle compares against — such a column disqualifies the whole MV (residual);
+ *  - a **tighten-only** column (min/max, and any UDAF whose merge is a join-semilattice
+ *    like `bit_or`/`bool_or`) — a plain call declaring `merge` + `decode` but NO `negate`
+ *    — is admitted with `deltaClass: 'tighten'`. It needs no exact-value-domain gate
+ *    (merge is idempotent selection, not accumulating arithmetic → no drift) and is never
+ *    retraction-safe: an insert `merge`s the new value in cheaply, but a retracted group
+ *    re-derives wholesale from the residual (via the descriptor's `hasTighten`) rather
+ *    than trusting the arithmetic;
+ *  - a **decomposition-maintained** column (the avg class) — a plain call whose algebra
+ *    declares `decompose` (a scalar formula over sibling partials, e.g. avg ≡ sum/count)
+ *    but is not itself directly maintainable — is admitted only when EVERY partial it
+ *    names ({@link resolveDecomposePartial}) is also stored as a sibling column of this
+ *    same body and is itself delta-maintainable. It carries no independent accumulation;
+ *    at flush its value is `combine([finalized(partial) …])`. If any partial is missing
+ *    or not delta-maintainable the whole MV falls to residual (avg is the first client of
+ *    this class, not a special case);
+ *  - any other column shape (a constant, an expression over the group key, …) fails.
+ *
+ * Whole-body requirements:
+ *  - **no post-aggregate filter** (HAVING, or an outer WHERE over the aggregate
+ *    output): such a filter breaks the arithmetic invariant "stored row == the
+ *    group's full accumulator" — a filtered-out group has contributions but no
+ *    stored row, so a later delta would rebuild it from the identity and understate
+ *    the aggregate. The residual re-evaluates the filter per group and stays exact;
+ *  - a **count(*) multiplicity witness** — a zero-arg delta-maintainable column with
+ *    `decodeExact` (its stored value must reconstruct exactly, since it decides group
+ *    emptiness under retraction). Without it, emptiness cannot be told from an
+ *    all-NULL sum;
+ *  - **BINARY collations** on every backing-PK (group key) column: the flush's stored-
+ *    row read is the host's `scanEffective` equality-prefix seek, whose prefix compare
+ *    is binary (scan-layer.ts). Unlike the prefix-delete arm there is no source-PK
+ *    uniqueness collapsing collation classes to one byte form here, so a non-BINARY
+ *    group key could miss a collation-equal / byte-different stored row — residual
+ *    instead;
+ *  - a body WHERE (if any) must compile to a single-source-row predicate
+ *    (`compilePredicate`) so per-row contributions can be scoped exactly.
+ *
+ * Per-column `retractionSafe` (see {@link DeltaAggregateColumn}) is recorded rather
+ * than gated: a not-retraction-safe descriptor still serves the bulk-insert fast path,
+ * and the flush re-derives only the retracted groups through the residual.
+ */
+export function buildDeltaAggregateDescriptor(mv, analyzed, tableRef, groupColumns, backingPkDefinition, backingPkSourceCols, rootAttrs, sourceAttrToCol, producingByAttrId) {
+    const sourceSchema = tableRef.tableSchema;
+    const groupColumnSet = new Set(groupColumns);
+    // Post-aggregate filter gate: a Filter whose subtree contains the aggregate is a
+    // HAVING (or an outer WHERE over the aggregate output). It breaks the arithmetic
+    // invariant "stored row == the group's full accumulator" — a filtered-out group has
+    // contributions but no stored row, so a later delta would rebuild it from the
+    // identity and understate the aggregate. (The body WHERE sits BELOW the aggregate —
+    // its Filter subtree contains no aggregate node — and stays delta-eligible via the
+    // compiled scope predicate below.)
+    if (hasFilterAboveAggregate(analyzed))
+        return undefined;
+    // Binary-collation gate on the backing PK (the flush's binary equality-prefix read).
+    for (const d of backingPkDefinition) {
+        if (!isBinaryCollation(d.collation))
+            return undefined;
+    }
+    // Body WHERE → single-row scope predicate (contributions outside it are dropped,
+    // mirroring the residual's own WHERE). An uncompilable WHERE shape → residual.
+    let predicate;
+    const bodyWhere = mv.derivation.selectAst.type === 'select' ? mv.derivation.selectAst.where : undefined;
+    if (bodyWhere) {
+        try {
+            predicate = compilePredicate(bodyWhere, sourceSchema.columns);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    // Chase an output attr's producing chain to its terminal (non-ColumnReference)
+    // expression — the aggregate call node for an aggregate output column.
+    const resolveTerminalProducing = (attrId) => {
+        const seen = new Set();
+        let cur = attrId;
+        while (!seen.has(cur)) {
+            seen.add(cur);
+            const expr = producingByAttrId.get(cur);
+            if (expr instanceof ColumnReferenceNode) {
+                cur = expr.attributeId;
+                continue;
+            }
+            return expr;
+        }
+        return undefined;
+    };
+    const aggColumns = [];
+    const groupOut = [];
+    // Decomposition-maintained columns (the avg class), collected raw here and bound to
+    // their sibling stored partials in a second pass below — the partials may project
+    // before OR after the decompose column, so they cannot be resolved inline.
+    const pendingDecompose = [];
+    for (let outCol = 0; outCol < rootAttrs.length; outCol++) {
+        const attr = rootAttrs[outCol];
+        if (!attr)
+            return undefined;
+        const sourceCol = resolveTransitiveSourceCol(attr.id, sourceAttrToCol, producingByAttrId);
+        if (sourceCol !== undefined) {
+            // Group-key passthrough: its flush value is the group key at the matching
+            // backing-PK position (covers duplicate projections of a group column).
+            if (!groupColumnSet.has(sourceCol))
+                return undefined;
+            const pkPos = backingPkSourceCols.indexOf(sourceCol);
+            if (pkPos < 0)
+                return undefined;
+            groupOut.push({ backingCol: outCol, pkPos });
+            continue;
+        }
+        const producing = resolveTerminalProducing(attr.id);
+        if (!(producing instanceof AggregateFunctionCallNode))
+            return undefined;
+        // Plain call only: DISTINCT folds duplicates (delta cannot), FILTER/ORDER BY
+        // change the contribution set, multi-arg has no single raw value to step.
+        if (producing.isDistinct || producing.filter || (producing.orderBy && producing.orderBy.length > 0))
+            return undefined;
+        if (producing.args.length > 1)
+            return undefined;
+        const schema = producing.functionSchema;
+        if (!isAggregateFunctionSchema(schema))
+            return undefined;
+        const algebra = schema.algebra;
+        // A bare source column argument (both classes below step / decompose over the raw
+        // value); a zero-arg (count(*)-shaped) call carries none.
+        let argSourceCol;
+        if (producing.args.length === 1) {
+            const arg = producing.args[0];
+            if (!(arg instanceof ColumnReferenceNode))
+                return undefined; // bare column args only
+            argSourceCol = resolveTransitiveSourceCol(arg.attributeId, sourceAttrToCol, producingByAttrId);
+            if (argSourceCol === undefined)
+                return undefined;
+        }
+        // Class routing — declaration-driven, never an aggregate-name list:
+        //  - **directly delta-maintainable** (`merge` + `negate` (retraction) + `decode` —
+        //    the backing stores finalized values, not accumulators): accumulate it as an
+        //    ordinary partial;
+        //  - else a **decomposition-maintained** column whose value is a formula over
+        //    sibling partials (`algebra.decompose`, e.g. avg ≡ sum/count) — deferred to the
+        //    pass below that binds each partial to a stored sibling; it accumulates nothing;
+        //  - anything else disqualifies the whole MV → residual.
+        if (algebra?.negate && algebra.decode) {
+            // Exact numeric domain: an INTEGER-physical declared result (count-shaped — the
+            // accumulator never holds a float) or an INTEGER-physical argument column
+            // (integer sum). Anything else may drift under repeated add/subtract.
+            // NOTE: if a REAL-domain sum ever needs the fast path, it needs compensated
+            // (Kahan) accumulation or a periodic-rescan discipline — a design change, not a
+            // relaxation of this gate.
+            const resultExact = schema.returnType.logicalType.physicalType === PhysicalType.INTEGER;
+            const argExact = argSourceCol !== undefined
+                && sourceSchema.columns[argSourceCol]?.logicalType.physicalType === PhysicalType.INTEGER;
+            if (!resultExact && !argExact)
+                return undefined;
+            const retractionSafe = algebra.decodeExact === true
+                || (argSourceCol !== undefined && sourceSchema.columns[argSourceCol]?.notNull === true);
+            aggColumns.push({
+                backingCol: outCol,
+                schema,
+                algebra,
+                deltaClass: 'group',
+                argSourceCol,
+                isMultiplicity: producing.args.length === 0,
+                retractionSafe,
+            });
+            continue;
+        }
+        // Tighten-only (join-semilattice): `merge` + `decode` but NO `negate` — min/max, and
+        // any UDAF whose merge is idempotent selection (bit_or/bool_or). An insert `merge`s the
+        // new value in cheaply (min/max tighten toward the new extreme); a retraction cannot be
+        // undone arithmetically, so a retracted group falls back to the residual
+        // (retractionSafe:false, and the descriptor's hasTighten routes the whole group there
+        // whether or not a row is stored). NO exact-numeric-domain gate: merge is idempotent
+        // selection, not accumulating arithmetic, so there is no float drift to guard — a tighten
+        // column over any comparable domain (REAL/TEXT included) stays byte-exact vs the live
+        // re-evaluation. A negate+decode column that failed the exact-domain gate above already
+        // returned undefined, so only a decode-without-negate aggregate reaches here.
+        if (algebra?.decode && !algebra.negate) {
+            aggColumns.push({
+                backingCol: outCol,
+                schema,
+                algebra,
+                deltaClass: 'tighten',
+                argSourceCol,
+                isMultiplicity: producing.args.length === 0,
+                retractionSafe: false,
+            });
+            continue;
+        }
+        if (algebra?.decompose) {
+            pendingDecompose.push({ backingCol: outCol, argSourceCol, decomposition: algebra.decompose });
+            continue;
+        }
+        return undefined; // neither directly maintainable, tighten-only, nor decomposable → residual
+    }
+    // Multiplicity witness: a zero-arg delta-maintainable column whose decode is exact
+    // (its merged value decides group emptiness, so the reconstruction must survive
+    // retraction). Structural — not name-based. A decompose column is never the witness
+    // (it accumulates nothing — the requirement is a real stored count(*)).
+    const multiplicityIndex = aggColumns.findIndex(c => c.isMultiplicity && c.algebra.decodeExact === true);
+    if (multiplicityIndex < 0)
+        return undefined;
+    if (aggColumns.length === 0)
+        return undefined; // defensive — findAggregate implies ≥1
+    // Bind each decomposition column's partials to sibling STORED, delta-maintained columns
+    // (every `aggColumns` entry already passed the accumulator gate, so it is itself delta-
+    // maintainable). A partial that maps to no such sibling disqualifies the whole MV →
+    // residual (honest and visible: the user wrote a body without the partials the formula
+    // names). The decompose column's `combine` recomputes exactly per group at flush.
+    const decomposeColumns = [];
+    for (const pd of pendingDecompose) {
+        const partialIndices = [];
+        for (const p of pd.decomposition.partials) {
+            const idx = resolveDecomposePartial(p, pd.argSourceCol, aggColumns, sourceSchema);
+            if (idx === undefined)
+                return undefined;
+            partialIndices.push(idx);
+        }
+        decomposeColumns.push({ backingCol: pd.backingCol, partialIndices, combine: pd.decomposition.combine });
+    }
+    return {
+        aggColumns,
+        decomposeColumns,
+        groupColumns: groupOut,
+        multiplicityIndex,
+        backingColumnCount: rootAttrs.length,
+        retractionSafe: aggColumns.every(c => c.retractionSafe),
+        hasTighten: aggColumns.some(c => c.deltaClass === 'tighten'),
+        predicate,
+    };
+}
+/**
+ * Resolve one {@link AggregateDecomposition} partial (e.g. avg's `sum` / `count`) to the
+ * index of a sibling stored, delta-maintainable aggregate column — an `aggColumns` entry
+ * matching the partial's function name and argument. Returns `undefined` when no such
+ * sibling is stored (the decompose column is then not maintainable → the MV falls to the
+ * residual). The write-side twin of `query-rewrite-matcher.resolveMergeablePartial`.
+ *
+ * `'same-arg'` targets a sibling over the decompose column's own argument (`f(thisArg)`);
+ * `'star'` targets a zero-arg (`count(*)`-shaped) sibling. The **count(*) fallback** mirrors
+ * the read-side relaxation from `feat-mv-agg-rollup-retarget`: a stored `count(*)` substitutes
+ * for a `count(x)` divisor only when `x` is declared **NOT NULL** — then `count(*)` excludes
+ * the same (zero) NULLs `count(x)` would, so the recombine stays exact.
+ */
+function resolveDecomposePartial(p, ownerArgSourceCol, aggColumns, sourceSchema) {
+    // NOTE: a partial resolves only to an `aggColumns` entry, which already passed the
+    // accumulator gate — a BARE source column argument plus the INTEGER-exact-domain check.
+    // That is what keeps the decomposed value byte-exact: a partial like `sum(log x)` (a
+    // non-bare, float-producing argument) can never be a stored delta-maintainable sibling,
+    // so a true geometric mean is NOT delta-decomposable and correctly falls to the residual.
+    const targetArg = p.arg === 'star' ? undefined : ownerArgSourceCol;
+    const funcName = p.func.toLowerCase();
+    const find = (name, argCol) => aggColumns.findIndex(c => c.schema.name.toLowerCase() === name && c.argSourceCol === argCol);
+    let idx = find(funcName, targetArg);
+    if (idx < 0 && funcName === 'count' && targetArg !== undefined
+        && sourceSchema.columns[targetArg]?.notNull === true) {
+        idx = find('count', undefined); // count(*) qualifies as the count(x) divisor when x is NOT NULL
+    }
+    return idx < 0 ? undefined : idx;
+}
+/**
+ * True when any Filter node's subtree contains an aggregate node — i.e. the plan
+ * filters the AGGREGATE OUTPUT (HAVING, or an outer WHERE over a grouped subquery).
+ * The body WHERE is the complement case: its Filter sits below the aggregate, so its
+ * subtree contains none. Used by {@link buildDeltaAggregateDescriptor}'s gate.
+ */
+function hasFilterAboveAggregate(node) {
+    if (node.nodeType === PlanNodeType.Filter && findAggregate(node) !== undefined)
+        return true;
+    for (const child of node.getChildren()) {
+        if (hasFilterAboveAggregate(child))
+            return true;
+    }
+    return false;
+}
 /**
  * Build a `'join-residual'` plan for a provably-1:1 row-preserving **inner/cross join**
  * body (`select … from T join P on T.fk = P.id`), or return `null` on a shape mismatch
@@ -679,7 +1008,6 @@ export function buildJoinResidualPlan(ctx, mv, analyzed, tableRefs) {
         chosenStrategy,
         sourceStats,
         binding: { kind: 'row', keyColumns: [...tPkCols] },
-        degradeToRebuild: false,
         residualScheduler: forwardResidual,
         bindParamPrefix: 'pk',
         bindColumns: tPkCols,
@@ -866,6 +1194,18 @@ export function compileResidual(ctx, analyzed, relKey, bindColumns, paramPrefix)
     const instruction = emitPlanNode(optimized, new EmissionContext(db));
     return new Scheduler(instruction);
 }
+/**
+ * Compile the WHOLE optimized body (no key filter, read-side rewrite suppressed) into a
+ * reusable {@link Scheduler} — the residual arms' per-statement degrade-to-rebuild
+ * escape ({@link ResidualArmCommon.fullRebuildScheduler}). Mirrors the floor's own
+ * `bodyScheduler` compilation in {@link buildFullRebuildPlan}: run to completion against
+ * live mid-transaction source state, its rows feed a single `'replace-all'` keyed diff.
+ */
+function compileWholeBodyScheduler(ctx, analyzed) {
+    const db = ctx;
+    const optimized = db.schemaManager.withSuppressedMaterializedViewRewrite(() => ctx.optimizer.optimize(analyzed, db));
+    return new Scheduler(emitPlanNode(optimized, new EmissionContext(db)));
+}
 /**
  * Build a `'prefix-delete'` plan for a single-source lateral-TVF fan-out body
  * (`select T.pk…, …, f.* from T cross join lateral tvf(<args over T>) f`), or return
@@ -1025,7 +1365,6 @@ export function buildLateralTvfPrefixDeletePlan(ctx, mv, analyzed, tableRef, sou
         chosenStrategy,
         sourceStats,
         binding: { kind: 'row', keyColumns: [...sourcePkCols] },
-        degradeToRebuild: false,
         residualScheduler,
         bindParamPrefix: 'pk',
         bindColumns: sourcePkCols,