@quereus/quereus 4.3.1 → 4.4.0

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

@@ -38,399 +38,12 @@
  *     (reads-own-writes) and is committed/rolled-back in lockstep with the source write by
  *     the coordinated commit (see {@link MaterializedViewManager.buildMaintenancePlan}).
  */
-import type { SchemaManager } from '../schema/manager.js';
 import { type SqlValue, type Row } from '../common/types.js';
-import { Scheduler } from '../runtime/scheduler.js';
-import type { BindingMode } from '../planner/analysis/binding-extractor.js';
-import { type MaintenanceSourceStats, type MaintenanceStrategy } from '../planner/cost/index.js';
-import { type DerivedRowConstraintValidator } from './derived-row-validator.js';
 import type { BackingRowChange } from '../vtab/backing-host.js';
-import type { VirtualTableConnection } from '../vtab/connection.js';
-import { type CompiledPredicate } from '../vtab/memory/utils/predicate.js';
 import type { MaintainedTableSchema } from '../schema/derivation.js';
 import type { UniqueConstraintSchema } from '../schema/table.js';
-import type { Database } from './database.js';
-import type { DatabaseEventEmitter } from './database-events.js';
-import type * as AST from '../parser/ast.js';
-/**
- * Database internals the materialized-view manager needs. Mirrors
- * `AssertionEvaluatorContext` / `WatcherManagerContext` — keeps the manager
- * decoupled from the full `Database`.
- */
-export interface MaterializedViewManagerContext {
-    readonly schemaManager: SchemaManager;
-    readonly optimizer: Database['optimizer'];
-    /** Database event emitter — the row-time collision telemetry channel
-     *  ({@link MaterializedViewManager.detectAndReportCoarseningCollisions}) queues
-     *  {@link MaintenanceCollisionEvent}s here. Already exposed for the transaction
-     *  manager; reused narrowly. */
-    getEventEmitter(): DatabaseEventEmitter;
-    _buildPlan(statements: AST.Statement[]): import('./database.js').BuildPlanResult;
-    _findTable(tableName: string, schemaName?: string): ReturnType<Database['_findTable']>;
-    /** Backing-connection resolution for row-time write-through (see {@link MaterializedViewManager.getBackingConnection}). */
-    getConnectionsForTable(tableName: string): VirtualTableConnection[];
-    registerConnection(connection: VirtualTableConnection): Promise<void>;
-}
-/**
- * A compiled per-MV maintenance plan — how {@link MaterializedViewManager.applyMaintenancePlan}
- * keeps an MV's backing table consistent with a source row-write. A tagged union over
- * the maintenance strategies the incremental substrate names (the spike's
- * `incremental-maintenance-substrate-spike` design). The builder
- * ({@link MaterializedViewManager.buildMaintenancePlan}) produces four bounded-delta arms:
- * `'inverse-projection'` (the covering-index shape), `'residual-recompute'` (single-source
- * aggregates), `'prefix-delete'` (single-source lateral-TVF fan-out), and `'join-residual'`
- * (the provably-1:1 inner join) — each applied **per source row, immediately**. The
- * `'full-rebuild'` floor (the always-correct convergence point for bodies no bounded-delta
- * arm fits) is the fall-through the builder routes to whenever no bounded-delta arm matches;
- * it is the one **deferred** arm — marked dirty per row and rebuilt once per statement at
- * {@link MaterializedViewManager.flushDeferredRebuilds}.
- */
-export type MaintenancePlan = InverseProjectionPlan | FullRebuildPlan | ResidualRecomputePlan | PrefixDeletePlan | JoinResidualPlan;
-/**
- * Structural subset of the fields the forward (driving-source) residual-recompute
- * apply path reads — shared by the aggregate {@link ResidualRecomputePlan} and the
- * 1:1-join {@link JoinResidualPlan} so both drive {@link MaterializedViewManager.applyForwardResidual}
- * unchanged. For an aggregate the forward key is the group key (`'gk'`); for a join
- * it is the driving table `T`'s PK (`'pk'`).
- */
-interface ForwardResidualPlan {
-    mv: MaintainedTableSchema;
-    backingSchema: string;
-    backingTableName: string;
-    /** Cached scheduler for the key-filtered residual (the body with `injectKeyFilter`
-     *  applied on the driving source). Re-run per affected key, bound through the live txn. */
-    residualScheduler: Scheduler;
-    bindParamPrefix: 'gk' | 'pk';
-    /** Source-column indices of the forward binding key (group columns / `T`'s PK columns). */
-    bindColumns: number[];
-    backingPkDefinition: ReadonlyArray<{
-        index: number;
-        desc?: boolean;
-        collation?: string;
-    }>;
-    backingPkSourceCols: number[];
-}
-/**
- * The shipped covering-index maintenance arm (the former `RowTimeMaintenancePlan`,
- * verbatim). Per source row-write the backing delta is a pure projection of the
- * changed row: project the source row to a backing row (a per-column projector —
- * passthrough columns *and* deterministic scalar expressions over the source row),
- * key it by the backing physical PK, and (if the partial predicate admits it) delete
- * the old image / upsert the new image. No body re-execution, no scan — see
- * `docs/materialized-views.md` § Row-time refresh.
- */
-/**
- * How a single backing output column is derived from the changed source row — a pure
- * per-row (per-statement) function. `'passthrough'` copies a source column (the column
- * permutation that *every* PK / UNIQUE-covered column must use, so the backing key and
- * the inverse-projection conflict map are recoverable); `'expr'` evaluates a
- * deterministic scalar expression over the source row (a non-key derived column —
- * `materialized-view-rowtime-expression-projections`). `eval` is the runtime-compiled
- * evaluator (see {@link compileSourceRowEvaluator}), so a computed backing value is
- * exactly what `select <body>` would produce.
- */
-export type BackingProjector = {
-    readonly kind: 'passthrough';
-    readonly sourceCol: number;
-} | {
-    readonly kind: 'expr';
-    readonly eval: (sourceRow: Row) => SqlValue;
-};
-/**
- * One **weakened** column of a coarsened backing key K′, precomputed once at
- * registration for the row-time collision telemetry
- * ({@link MaterializedViewManager.detectAndReportCoarseningCollisions}). Carries the
- * backing column index to read from each {@link BackingRowChange} image, the
- * **source** (pre-coarsening, stricter) collation the divergence test compares
- * under, the **output** (coarsened) collation the backing key enforces, and the
- * column name for the {@link MaintenanceCollisionEvent} payload. Derived from
- * `mv.derivation.coarsenedKey.weakened` (column names) via `mv.columnIndexMap`.
- */
-interface CoarseningWatchColumn {
-    /** Backing column index (= body output column index) the weakened K′ column lands at. */
-    readonly index: number;
-    /** Source key enforcement collation (pre-coarsening); the divergence test compares under it. */
-    readonly sourceCollation: string;
-    /** Output (coarsened) collation the backing key enforces. */
-    readonly outputCollation: string;
-    /** Backing/output column name (for the event payload's `weakenedColumns`). */
-    readonly column: string;
-}
-/**
- * Common identity + cost-gate fields shared by every {@link MaintenancePlan} arm.
- * `chosenStrategy` / `sourceStats` are set once by the create-time cost gate
- * ({@link MaterializedViewManager.buildMaintenancePlan}, via `selectMaintenanceStrategy`)
- * and are not re-evaluated per write, except for the residual → rebuild demotion
- * (`shouldDegradeToRebuild`; dormant until the residual arm is reachable).
- */
-interface MaintenancePlanCommon {
-    /** The MV this plan maintains. */
-    mv: MaintainedTableSchema;
-    /** Lowercased `schema.table` of the single source `T`. */
-    sourceBase: string;
-    backingSchema: string;
-    backingTableName: string;
-    /** Strategy the cost gate chose: argmin `maintenanceCost` over the body's sound strategies. */
-    chosenStrategy: MaintenanceStrategy;
-    /** Create-time cost inputs (StatsProvider + forward optimizer), retained so the DML
-     *  boundary can re-cost residual vs. rebuild against the actual changeCardinality. */
-    sourceStats: MaintenanceSourceStats;
-    /** Compiled declared-CHECK/FK validator over derived row images — present ONLY
-     *  when the maintained table declares ≥1 applicable CHECK or ≥1 FK (the
-     *  zero-overhead gate: MV-sugar backings and constraint-less maintained tables
-     *  carry `undefined` and pay nothing per write). Built once at registration
-     *  ({@link MaterializedViewManager.registerMaterializedView}); applied to each
-     *  insert/update {@link BackingRowChange} before the cascade. */
-    derivedRowValidator?: DerivedRowConstraintValidator;
-    /** Precomputed weakened-K′-column watch list for row-time collision telemetry —
-     *  present ONLY when `mv.derivation.coarsenedKey` is stamped (the zero-overhead
-     *  gate: a provable-key / refining-lineage-key MV carries `undefined` and pays
-     *  nothing per write — detection short-circuits on this field). Built once at
-     *  registration ({@link MaterializedViewManager.registerMaterializedView} →
-     *  {@link MaterializedViewManager.buildCoarseningWatch}); read by
-     *  {@link MaterializedViewManager.detectAndReportCoarseningCollisions} from both
-     *  the bounded-delta and full-rebuild maintenance arms. */
-    coarseningWatch?: ReadonlyArray<CoarseningWatchColumn>;
-}
-export interface InverseProjectionPlan extends MaintenancePlanCommon {
-    readonly kind: 'inverse-projection';
-    /** Backing-table physical primary-key definition (the column order the btree keys on). */
-    backingPkDefinition: ReadonlyArray<{
-        index: number;
-        desc?: boolean;
-        collation?: string;
-    }>;
-    /** `projectors[j]` derives backing output column `j` from the changed source row —
-     *  either a passthrough copy of a source column or a deterministic scalar expression
-     *  over the source row. Every PK / backing-key column is `'passthrough'` (eligibility
-     *  rejects a computed column that lands in the backing key); non-key columns may be
-     *  `'expr'`. {@link MaterializedViewManager.lookupCoveringConflicts} reads only the
-     *  passthrough projectors for its inverse (source↔backing) map. */
-    projectors: BackingProjector[];
-    /** Partial-WHERE predicate evaluated on a single source row; absent ⇒ every row
-     *  is in scope. A source row contributes a backing row only when this is
-     *  unambiguously TRUE (mirrors partial-UNIQUE / partial-index semantics). */
-    predicate?: CompiledPredicate;
-}
-/**
- * The always-correct **floor**: a body for which no bounded-delta arm is sound is
- * maintained by re-evaluating it in full per writing statement and replacing the backing
- * transactionally (a single `'replace-all'` {@link MaintenanceOp} — a keyed diff against
- * the backing's pending layer, so the delta still commits/rolls-back with the source
- * write and still drives the MV-over-MV cascade). The whole optimized body is compiled
- * once at registration into {@link bodyScheduler}; {@link MaterializedViewManager.applyFullRebuild}
- * runs it to completion against live source state and diffs the result into the backing.
- *
- * Reachability: `buildMaintenancePlan` routes a body here whenever no bounded-delta arm
- * fits ({@link MaterializedViewManager.tryBuildBoundedDeltaArm} returns `null`). It is the
- * one **deferred** arm — marked dirty per source row and rebuilt exactly once at the
- * end-of-statement flush ({@link MaterializedViewManager.flushDeferredRebuilds}), so a bulk
- * write is O(body) not O(rows × body). See `docs/materialized-views.md` § Full-rebuild floor.
- */
-export interface FullRebuildPlan extends MaintenancePlanCommon {
-    readonly kind: 'full-rebuild';
-    /** The optimized body compiled once at registration — the **whole** body (no
-     *  `injectKeyFilter`), with the read-side MV rewrite suppressed so it reads its sources,
-     *  not the backing it populates. Re-run to completion per writing statement, bound
-     *  through the live transaction (reads-own-writes), to recompute every backing row. */
-    bodyScheduler: Scheduler;
-    /** Every source base (lowercased `schema.table`) the body reads — set-op legs, every
-     *  join source, etc. The plan is indexed under each in `rowTimeBySource` (via
-     *  {@link planSourceBases}), so a write to **any** of them triggers a rebuild; missing
-     *  one would leave the MV stale on that source's writes. `sourceBase` (the
-     *  {@link MaintenancePlanCommon} field) holds the first of these for parity. */
-    sourceBases: string[];
-}
-/**
- * The general-body residual-recompute arm: per source change, derive the affected
- * binding key(s) from the changed row, run a key-filtered residual of the body against
- * **live mid-transaction source state**, and apply the keyed diff — upsert the recomputed
- * slice (replacing the old row at the same backing key; a value-identical recompute is
- * suppressed by the host, see vtab/backing-host.ts) or, when the residual returns
- * nothing, delete the emptied key. Wired for the **single-source aggregate** shape
- * (`select g1,… , agg(…) from T [where P] group by g1,…` over bare group columns) by
- * `materialized-view-rowtime-residual-recompute`; the 1:1 row-preserving join shape
- * (`'row'` binding) reuses the same kernel in a follow-on ticket.
- *
- * The residual is the body with a key-equality filter injected on `T`'s
- * `TableReferenceNode` via {@link injectKeyFilter} (parameterized `gk0…` for a group
- * binding, `pk0…` for a row binding), compiled + cached once at registration and run
- * synchronously through the live transaction so the source read is reads-own-writes —
- * the synchronous analogue of `database-assertions.ts`'s residual path.
- *
- * It carries the {@link BindingMode} the spike names as the convergence point (built
- * directly from the body's shape — for an aggregate, the bare GROUP BY columns; NOT
- * via `extractBindings`, whose `'group'` classification additionally requires the group
- * key to cover a source unique key and so reports `'global'` for the common
- * `group by <non-key>` body). `degradeToRebuild` is the cost gate's full-rebuild escape
- * flag — dormant in v1 (the per-row recompute is correct without batching, and the
- * full-rebuild arm is unwired).
- */
-export interface ResidualRecomputePlan extends MaintenancePlanCommon {
-    readonly kind: 'residual-recompute';
-    binding: BindingMode;
-    degradeToRebuild: boolean;
-    /** Cached scheduler for the key-filtered residual (the body with `injectKeyFilter`
-     *  applied on `T`). Re-run per affected key tuple, bound through the live transaction. */
-    residualScheduler: Scheduler;
-    /** Bind-parameter prefix the residual was compiled with: `'gk'` (group) / `'pk'` (row). */
-    bindParamPrefix: 'gk' | 'pk';
-    /** Source-column indices of the binding key (group columns / row key columns). The
-     *  affected key tuple is `bindColumns.map(c => changedRow[c])`, bound to `${prefix}{i}`. */
-    bindColumns: number[];
-    /** Backing-table physical primary-key definition (the column order the btree keys on). */
-    backingPkDefinition: ReadonlyArray<{
-        index: number;
-        desc?: boolean;
-        collation?: string;
-    }>;
-    /** Source column projected (passthrough) into each backing-PK column, in
-     *  `backingPkDefinition` order. The old backing slice's delete key for a changed row
-     *  `R` is `buildPrimaryKeyFromValues(backingPkSourceCols.map(sc => R[sc]), backingPkDefinition)`. */
-    backingPkSourceCols: number[];
-}
-/**
- * The single-source lateral-TVF fan-out arm: a body of the shape
- * `select T.pk…, …, f.* from T cross join lateral tvf(<args over T>) f`, where each base
- * row of `T` fans out to **N** backing rows (one per row the TVF emits for it). The
- * backing PK is the **composite product key** `(T.pk ∪ tvf-key)` that
- * `optimizer-keyed-cross-product-join-keys` advertises through `keysOf` over the lateral
- * join, with the base PK as its **leading prefix** (asserted at build).
- *
- * Per changed base row, maintenance is a **keyed diff of the recomputed fan-out against
- * the existing effective slice for the base-PK prefix** (read via the host's
- * `scanEffective`, since one base row owns many backing rows sharing the prefix): re-run
- * the TVF fan-out **residual** for that base row, delete only the existing keys the
- * recompute no longer produces, and **upsert** each recomputed row (value-identical
- * upserts are suppressed by the host). An UPDATE diffs both the OLD and NEW base keys
- * (the base PK may move); a DELETE diffs the old slice to all-deletes; an INSERT diffs
- * against an empty slice. This reuses the residual kernel of {@link ResidualRecomputePlan}
- * unchanged — the affected-key derivation, the `injectKeyFilter` residual (pinned to the
- * base `TableReferenceNode` with the `'pk'` prefix), reads-own-writes execution, the cost
- * gate — and differs only in the **prefix-slice** diff (vs point-key) and the **N-row**
- * residual (vs ≤1). The body's WHERE, if any, is part of the residual (so an out-of-scope
- * base row fans out to zero rows), exactly as in the aggregate arm.
- *
- * `chosenStrategy` is `'residual-recompute'` (the shared key-filtered re-execution cost
- * shape — the fan-out factor is unknown at create); `kind` is `'prefix-delete'` (the
- * apply-arm dispatcher). `degradeToRebuild` is dormant (as in the aggregate arm).
- */
-export interface PrefixDeletePlan extends MaintenancePlanCommon {
-    readonly kind: 'prefix-delete';
-    /** Substrate parity (the base-PK 'row' binding); unread by the apply path, which uses
-     *  `bindColumns` / `backingPrefixSourceCols`. */
-    binding: BindingMode;
-    degradeToRebuild: boolean;
-    /** Cached scheduler for the base-PK-keyed residual (the body with `injectKeyFilter`
-     *  applied on `T`, `'pk'` prefix). Re-run per affected base key; fans out to N rows. */
-    residualScheduler: Scheduler;
-    bindParamPrefix: 'pk';
-    /** Source-`T` PK column indices (the base key). The affected key tuple is
-     *  `bindColumns.map(c => changedRow[c])`, bound to `pk{i}`. */
-    bindColumns: number[];
-    /** Full backing-table physical primary key (base-PK prefix ++ TVF-key tail). */
-    backingPkDefinition: ReadonlyArray<{
-        index: number;
-        desc?: boolean;
-        collation?: string;
-    }>;
-    /** Number of leading backing-PK columns that form the base-PK prefix (= `bindColumns.length`). */
-    basePrefixLength: number;
-    /** Source-`T` column projected into each leading (base-prefix) backing-PK column, in
-     *  backing-PK order. The by-prefix delete key for a changed row `R` is
-     *  `backingPrefixSourceCols.map(sc => R[sc])`. */
-    backingPrefixSourceCols: number[];
-}
-/**
- * The 1:1 row-preserving **inner/cross join** arm: a body
- * `select … from T join P on T.fk = P.id` where `T` contributes **exactly one** MV row
- * per governed `T` row (proven by {@link proveOneToOneJoin} — no row loss via NOT-NULL
- * FK→PK referential integrity, no fan-out via `isUnique(T.pk)` at the join frame). The
- * backing is keyed on `T`'s PK (the composite product key `keysOf` advertises across the
- * 1:1 join collapses to `T`'s PK), so each changed `T` row maps to one backing row.
- *
- * Reuses the residual kernel of {@link ResidualRecomputePlan} on its **driving (`T`)**
- * side via {@link ForwardResidualPlan}: a `T`-keyed (`'pk'`) residual recomputes the one
- * joined row for a changed `T` row (run residual → upsert the recomputed row, or delete
- * the key when it returns nothing), identical to a `'row'`-binding aggregate of size 1.
- * `applyForwardResidual` drives it.
- *
- * The **lookup (`P`)** side is the join arm's distinct problem: the MV's `sourceTables`
- * includes `P`, so a write to `P` also fires maintenance, but the forward residual is
- * keyed on `T`'s PK and a `P` row joins *many* `T` rows. This plan therefore carries a
- * **second residual keyed on `P`'s PK** (`lookupResidualScheduler`): for a `P` change it
- * runs `… where P.pk = :pk0` (the body **including** its WHERE) against live state,
- * returning every currently in-scope joined row (each carrying its `T.pk` backing key), and
- * **upserts** each.
- *
- * **WHERE handling — bounded-delta over a partial-WHERE 1:1 join.** A body WHERE is
- * classified at build by which base table(s) its columns reference
- * ({@link MaterializedViewManager.buildJoinResidualPlan}):
- *  - **`T`-only predicate** — no extra machinery. The forward (`T`) residual already injects
- *    + applies the WHERE (an out-of-scope `T` row recomputes to zero residual rows ⇒ its
- *    delete-without-upsert removes the backing row), and a `T`-column predicate cannot move
- *    the membership set `{ T : T.fk = P.pk }`, so the lookup side stays **upsert-only**
- *    (`lookupMembershipResidualScheduler` absent) — sound for the same reason the no-WHERE
- *    arm is.
- *  - **`P`-referencing predicate** (or both sides) — a `P` write can flip a row's WHERE truth
- *    and so add/remove a backing row, which upsert-only could never delete. The lookup side
- *    becomes **delete-capable**: `lookupMembershipResidualScheduler` is the body with
- *    `injectKeyFilter` on `P` but the WHERE **stripped** (membership only). Per affected `P`
- *    key {@link MaterializedViewManager.applyLookupResidual} diffs it against the in-scope
- *    `lookupResidualScheduler` (WHERE retained): membership keys the in-scope recompute no
- *    longer produces are deleted, the in-scope rows are upserted — a keyed diff that converges
- *    the membership both ways without churning the unchanged rows.
- *
- * Still inner/cross only; outer joins and **fanning** (non-1:1) joins continue to fall to the
- * full-rebuild floor. See `docs/incremental-maintenance.md` § join-residual and the soundness
- * note in {@link MaterializedViewManager.applyLookupResidual}.
- */
-export interface JoinResidualPlan extends MaintenancePlanCommon, ForwardResidualPlan {
-    readonly kind: 'join-residual';
-    /** Substrate parity: the driving `T`'s `'row'`/PK binding. */
-    binding: BindingMode;
-    degradeToRebuild: boolean;
-    bindParamPrefix: 'pk';
-    /** Lowercased `schema.table` of the lookup source `P` (distinct from `sourceBase` = `T`). */
-    lookupBase: string;
-    /** Cached scheduler for the in-scope lookup-keyed residual (the body — WHERE **retained** —
-     *  with `injectKeyFilter` applied on `P`, `'pk'` prefix). Re-run per affected `P` key;
-     *  returns the currently in-scope joined rows to upsert. */
-    lookupResidualScheduler: Scheduler;
-    /** Delete-capable lookup membership residual (the body with the WHERE **stripped** and
-     *  `injectKeyFilter` on `P`). Present **iff** the body WHERE references `P`: the lookup side
-     *  must then delete the backing key of every currently-referencing `T` row (regardless of
-     *  scope) before re-upserting the in-scope survivors, so a `P` write that flips a row's WHERE
-     *  membership adds/removes its backing row. Absent for a no-WHERE or `T`-only-WHERE body
-     *  (the lookup side is sound upsert-only — membership cannot move on a `P` write). */
-    lookupMembershipResidualScheduler?: Scheduler;
-    /** Source-`P` PK column indices (the lookup key). The affected key tuple for a `P`
-     *  change is `lookupBindColumns.map(c => changedRow[c])`, bound to `pk{i}`. */
-    lookupBindColumns: number[];
-    lookupBindParamPrefix: 'pk';
-}
-/**
- * Per-statement cache of resolved backing {@link VirtualTableConnection}s, keyed by the
- * lowercased backing `schema.table`. Created **once per DML generator run** (one
- * statement) and threaded through the maintenance path so the backing-connection
- * resolution — a scan over *all* the Database's active connections in
- * {@link MaterializedViewManager.getBackingConnection} — is paid once per
- * (statement, backing) instead of once per source row. This amortizes the dominant
- * per-row overhead of a bulk `insert`/`update`/`delete` over a covered table.
- *
- * It is purely a resolution cache: each **bounded-delta** arm's per-row ops are still
- * applied **immediately** to the cached connection's pending transaction layer, so a later
- * same-statement row's enforcement scan (`lookupCoveringConflicts`) still observes every
- * earlier row's backing write. The one exception is the **full-rebuild** arm, which the DML
- * boundary defers to a single end-of-statement {@link MaterializedViewManager.flushDeferredRebuilds}
- * (tracked in a separate per-statement dirty set, not this cache) — sound because a
- * full-rebuild MV is never a covering structure, so no enforcement scan depends on its
- * per-row visibility. See `docs/materialized-views.md` § Synchronous, transactional,
- * per-statement. Because the cache is scoped to one generator run, the connection it holds
- * cannot be torn down mid-statement; the cold enforcement/eviction paths that omit the cache
- * re-resolve the *same* connection deterministically, so reads-own-writes is unaffected.
- */
-export type BackingConnectionCache = Map<string, VirtualTableConnection>;
+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;
@@ -624,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).
-     */
-    maintainRowTime(sourceBase: string, change: BackingRowChange, cache?: BackingConnectionCache, deferred?: Set<string>, 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.
-     *
-     * 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.
+     * `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>, residualBatch?: ResidualKeyBatch, depth?: number): Promise<void>;
+    /**
+     * 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 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).
-     */
-    flushDeferredRebuilds(deferred: Set<string>, cache?: BackingConnectionCache): Promise<void>;
-    /**
-     * Round backstop for {@link flushDeferredRebuilds}. The full-rebuild sub-DAG is acyclic,
+     * 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).
+     */
+    flushDeferredMaintenance(deferred: Set<string>, residualBatch: ResidualKeyBatch, cache?: BackingConnectionCache): Promise<void>;
+    /**
+     * 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
@@ -690,276 +350,19 @@ export declare class MaterializedViewManager {
      * `'full-rebuild'` (the floor — re-evaluate the whole body and replace the backing). The
      * floor ignores the specific `change` (it rebuilds wholesale); the others derive a
      * bounded per-row delta from it.
-     */
-    private applyMaintenancePlan;
-    /**
-     * Compute an `'inverse-projection'` plan's per-row backing delta, apply it, and
-     * return the **effective** {@link BackingRowChange}(s) the backing layer realized.
-     * An out-of-scope row (or a delete of an absent backing key) yields no change. This
-     * body is the shipped covering-index maintenance, lifted verbatim from the former
-     * `applyRowTimeChange`, plus the equal-image short-circuit: an UPDATE whose old and
-     * new projected images are value-identical (both in scope) projects to NO backing
-     * delta — the dominant no-op echo (a source update touching only unprojected columns,
-     * or rewriting a projected column to its existing value) is suppressed before any
-     * backing-connection work. Accurate by the maintenance invariant (the backing row IS
-     * the old image's projection), so nothing would have changed; the host's
-     * value-identical upsert skip (vtab/backing-host.ts) remains the effective-state
-     * backstop for the paths that do emit ops.
-     */
-    private applyInverseProjection;
-    /**
-     * Validate the row images a maintenance apply WROTE (insert/update
-     * {@link BackingRowChange}s — a delete writes no image) against the plan's
-     * compiled {@link DerivedRowConstraintValidator}. Inline checks abort the
-     * writing statement with the maintained-table-attributed CONSTRAINT error;
-     * auto-deferred checks (subquery CHECK, every child-side FK) queue to the
-     * deferred-constraint queue and validate at commit. Deferred entries are
-     * pinned to the backing connection the maintenance write used (resolved from
-     * the per-statement cache, or re-resolved deterministically — the same
-     * connection either way) so commit-time evaluation reads the same pending
-     * state, mirroring the DML pipeline's active-connection capture.
-     */
-    private validateDerivedChanges;
-    /**
-     * Fire **parent-side** referential enforcement over the backing rows a maintenance
-     * apply REMOVED or re-keyed (delete / key-update {@link BackingRowChange}s — an insert
-     * has no parent-side action). When the maintained table `M` is the PARENT (FK target)
-     * of an FK declared on an ordinary table `C` (`create table C (… references M(col) …)`),
-     * a maintenance-driven delete/key-update of the referenced `M` row would silently orphan
-     * `C`'s rows, bypassing the declared RESTRICT / referential action. This is the
-     * **dual** of {@link validateDerivedChanges} (constraints declared *on* `M`); the FK here
-     * lives on `C` and references `M`, so it is invisible to `M`'s own plan/validator.
-     *
-     * It reuses the SAME shared referential-action engine the DML executor and the
-     * external-change ingestion seam use — no third copy — applying its two functions over
-     * each backing change exactly as `database-external-changes.ts` does:
-     *  - {@link assertTransitiveRestrictsForParentMutation} — pre-walk the transitive cascade
-     *    closure and throw a CONSTRAINT error naming `M` on any surviving RESTRICT child;
-     *  - {@link executeForeignKeyActionsAndLens} — run declared CASCADE / SET NULL / SET DEFAULT,
-     *    re-entering the DML executor (the already-holding-the-mutex variant) for each cascaded
-     *    child write, so `C`'s own constraints, watches, nested cascades, and (if `C` is itself
-     *    an MV source) its own maintenance all fire.
      *
-     * Ordering: called AFTER the backing delta has landed in the pending layer (the RESTRICT
-     * walk runs POST-application — the child rows it keys off still exist because the cascade
-     * has not run yet) and AFTER `M`'s own image is validated, matching the DML executor's
-     * per-change order (capture → MV maintenance → FK actions) and the external-changes seam.
-     * `lensRouted = false`: a maintenance backing write is a physical basis write (maintained
-     * tables are not lens basis spines). A surviving RESTRICT throws up through
-     * {@link maintainRowTime} → the DML executor → the statement, rolling back the source write
-     * attributed to `M`.
-     *
-     * Gate: a cheap `foreign_keys`-pragma early-return keeps the pragma-off path free (the
-     * engine also early-returns, but skipping the `getTable` + loop avoids all per-change work).
-     * NOT gated on `plan.derivedRowValidator` — that gate is child-side (constraints *on* `M`);
-     * an inbound FK lives on `C` and leaves `M`'s plan untouched. Beyond the gate it fires
-     * unconditionally per delete/update change, but the engine no longer pays an `O(catalog)`
-     * scan: both calls route through `SchemaManager.getReferencingForeignKeys`, the precomputed
-     * reverse-FK index, so an `M` that nothing references resolves to the shared empty bucket and
-     * each call early-returns in O(1) — a maintained table with no inbound FK (the common case)
-     * pays only the pragma check plus one map lookup per delete/key-update change.
-     */
-    private enforceParentSideReferentialActions;
-    /**
-     * Resolve the {@link BackingHost} capability surface for a backing table —
-     * see `vtab/backing-host.ts` for the contract. The host is resolved fresh per
-     * use (a map lookup on the owning module), so a drop+recreate of the backing
-     * always yields the new incarnation's host.
+     * The dispatch stays on the manager (the per-arm appliers live in
+     * database-materialized-views-apply.ts as free functions over the manager context); it
+     * is the seam the row-time equivalence suite instruments to observe the effective
+     * changes a maintenance apply realizes.
      */
-    private backingHost;
-    /**
-     * Obtain (lazily create + register) the backing table's
-     * {@link VirtualTableConnection} for the current transaction. Reuses the same
-     * connection a `select` from the MV resolves to (so reads-own-writes holds) —
-     * matched among the Database's registered connections by
-     * {@link BackingHost.ownsConnection}, which is pinned to the live backing
-     * incarnation; a freshly created connection is registered with the Database so
-     * the coordinated commit/rollback covers its pending state in lockstep with the
-     * source write.
-     *
-     * When an optional per-statement {@link BackingConnectionCache} is supplied, the
-     * scan over the Database's active connections (the dominant per-row cost on a bulk
-     * write) is paid once per (statement, backing): a hit returns the cached connection
-     * directly, and a miss caches whichever connection the scan resolves — or the one it
-     * lazily creates + registers. Caching the resolved/created connection is sound
-     * because the scan is deterministic within a statement (nothing interleaves between
-     * a statement's rows to change which connection a `select` from the MV picks), so the
-     * cache holds exactly what an uncached re-resolution would return.
-     */
-    private getBackingConnection;
-    /**
-     * 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
-     * ({@link tryBuildBoundedDeltaArm}); a body that matches **none** falls through to the
-     * always-correct {@link buildFullRebuildPlan} floor (re-evaluate the whole body, replace
-     * the backing transactionally). **No body is rejected for its shape.** Only four
-     * create-time rejections remain, all non-shape:
-     *  - a **non-deterministic** body without `pragma nondeterministic_schema` — a hard reject
-     *    in the matched arm (so the arm-specific determinism diagnostic survives) or, for a
-     *    body matching no arm, in the floor's whole-body determinism check;
-     *  - a **bag** (no provable unique key) — the floor's `keysOf` reject (a duplicate-producing
-     *    body usually fails the set contract earlier, at create-fill);
-     *  - a body with **no relational output**;
-     *  - a **full-rebuild-only body over a source past the size threshold**
-     *    ({@link isFullRebuildPathological}, the `materialized_view_rebuild_row_threshold` option).
-     *
-     * The single source may itself be another MV's backing table (an MV-over-MV body):
-     * `building/select.ts` rewrites a reference to `mv1` into a `TableReference` against
-     * `mv1`'s backing table, so the source base is `mv1`'s backing base and the same checks
-     * evaluate against the (keyed `memory`) backing schema unchanged. A write to `mv1` then
-     * drives `mv2` via the cascade in {@link maintainRowTime}.
-     *
-     * Eligibility is a *cost choice* among the body's structurally-sound strategies
-     * ({@link selectMaintenanceStrategy}): the bounded-delta arms are preferred by the argmin
-     * cost gate, and full-rebuild is selected exactly when no bounded-delta arm is sound (an
-     * empty sound set resolves to the floor) — so an existing eligible shape is unaffected.
-     */
-    private buildMaintenancePlan;
-    /**
-     * Route the analyzed body to the matching bounded-delta arm, or return `null` when its
-     * shape fits **no** bounded-delta arm (the caller then builds the full-rebuild floor).
-     * Each arm builder likewise returns `null` on a sub-shape mismatch and falls through
-     * here. The arms keep only **determinism** as a hard reject (so their arm-specific
-     * determinism diagnostic survives — see the individual builders); every other mismatch
-     * is a `null` fall-through. Bag / no-output / size rejects live in the floor.
-     */
-    private tryBuildBoundedDeltaArm;
-    /**
-     * Build an `'inverse-projection'` plan for the covering-index shape: a single
-     * row-preserving source `T` with a primary key, a linear
-     * `TableReference → optional Filter → Project → optional Sort` body, a projection that
-     * resolves every source PK column (and every backing-key column) to a **passthrough**
-     * source column — non-key columns may instead be a **deterministic scalar expression**
-     * over the source row — and a partial WHERE evaluable on a single source row. Returns
-     * `null` on any **shape** mismatch (the caller falls through to the full-rebuild floor);
-     * a **non-deterministic** computed column is the one hard reject (its arm-specific
-     * determinism diagnostic must survive rather than fall through to the floor's generic one).
-     */
-    private buildInverseProjectionPlan;
-    /**
-     * Build a `'residual-recompute'` plan for a single-source aggregate body
-     * (`select g1,…, agg(…) from T [where P] group by g1,…` over **bare** group columns),
-     * or return `null` on a shape mismatch (the caller falls through to the full-rebuild
-     * floor). Each changed source row belongs to exactly one group `(g1,…)`; maintaining the
-     * MV means recomputing that group's backing row from live state — delete the old slice,
-     * run the group-keyed residual, upsert the recomputed slice (zero rows when the group
-     * emptied). See {@link ResidualRecomputePlan} and `docs/incremental-maintenance.md`
-     * § residual-recompute.
-     *
-     * A **non-deterministic** group/aggregate expression is the one hard reject (the
-     * arm-specific determinism diagnostic must survive); every other mismatch — a scalar
-     * aggregate, a computed group key, a backing key that is not the group key — returns
-     * `null` → the floor.
-     *
-     * NOTE: the group binding is derived **directly** from the aggregate node's bare GROUP
-     * BY columns, not via `extractBindings`. `analyzeRowSpecific`'s `'group'` classification
-     * additionally requires the group key to cover a *source* unique key (so it reports
-     * `'global'` for the common `group by <non-key>` body), which is the wrong test here —
-     * the backing is keyed by the group key regardless of whether it is a source key.
-     */
-    private buildAggregateResidualPlan;
-    /**
-     * 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
-     * (the caller falls through to the full-rebuild floor). The driving table `T` is the one
-     * whose PK the optimizer surfaced as the backing key (the 1:1 join collapses the composite
-     * product key to `T`'s PK); the other base ref is the lookup `P`. See {@link JoinResidualPlan}
-     * and `docs/incremental-maintenance.md` § join-residual.
-     *
-     * Soundness gates (a mismatch on any returns `null` → floor): exactly two base tables; no
-     * aggregate over the join; the backing PK is exactly `T`'s PK projected as passthrough
-     * columns (so each changed `T` row maps to one backing row and the reverse residual's rows
-     * carry the backing key); the join is provably 1:1 on `T` ({@link proveOneToOneJoin} — no
-     * row loss via NOT-NULL FK→PK RI, no fan-out via the join-frame `isUnique(T.pk)`); and the
-     * join is **inner/cross** (an outer join would make the lookup-side reverse residual unsound
-     * — filtering `P` drops the null-extended rows). A **non-deterministic** projection is the
-     * one hard reject (its arm-specific determinism diagnostic must survive).
-     *
-     * **A body WHERE is now accepted** (it is no longer a blanket reject): the predicate is
-     * classified by which base table(s) its columns reference (reusing the per-base-ref
-     * attribute→source-column maps below). A `T`-only predicate needs nothing extra — the
-     * forward residual already carries it and the membership set `{ T : T.fk = P.pk }` cannot
-     * move on a `P` write, so the lookup side stays upsert-only. A predicate referencing `P` (or
-     * both sides) switches the lookup side to a **delete-capable** reverse residual by building
-     * `lookupMembershipResidualScheduler` (the body with the WHERE stripped, keyed on `P`). See
-     * {@link JoinResidualPlan}'s "WHERE handling" note and {@link applyLookupResidual}.
-     */
-    private buildJoinResidualPlan;
-    /**
-     * Compile the **lookup membership** residual for the join-residual arm's delete-capable
-     * lookup side: the MV body with its top-level WHERE **stripped** (membership only) and a
-     * key-equality filter injected on the lookup `P`, keyed `pk0…`. The WHERE is stripped at the
-     * AST level (a shallow clone dropping `where`) and the body re-built + re-analyzed, so only
-     * the WHERE is removed — the join, its `ON` condition, and any projection sub-expressions are
-     * preserved. Re-analysis assigns fresh node ids, so `P`'s reference is re-located by base name
-     * to compute the injection target. Returns `null` if the lookup ref or the key-filter
-     * injection could not be resolved (the caller then falls to the full-rebuild floor).
-     *
-     * Run per affected `P` key, this residual returns **every** `T` row currently joined to `P`
-     * via the join's `ON` condition — irrespective of the WHERE — so {@link applyLookupResidual}
-     * can delete each one's `T.pk` backing key before the in-scope residual re-upserts the
-     * survivors (the membership set the WHERE-bearing reverse residual would otherwise never
-     * shrink).
-     */
-    private compileLookupMembershipResidual;
-    /**
-     * Build a `'full-rebuild'` plan — the always-correct floor — for an MV whose body matches
-     * no bounded-delta arm, or throw with a non-shape diagnostic. This is the fall-through
-     * builder {@link tryBuildBoundedDeltaArm} routes to on a `null` (no bounded-delta arm fits).
-     * See {@link FullRebuildPlan} and `docs/materialized-views.md` § Full-rebuild floor /
-     * § Primary key inference.
-     *
-     * Create-time rejections (none shape-based — the floor accepts general bodies):
-     * - **bag** body with no provable unique key (`keysOf` over the optimized body root is
-     *   empty) — there is no row identity to materialize on. `keysOf` already gates its
-     *   all-columns fallback on `isSet`, so a non-empty result is a real key (a true column
-     *   key OR the all-columns key of a provable set) and an empty result is exactly a bag.
-     *   (A duplicate-producing body usually fails the set contract earlier, at create-fill.)
-     * - **non-deterministic** body (any `random()`/`now()`/volatile UDF anywhere in the plan)
-     *   without `pragma nondeterministic_schema` — no maintenance could keep it equal to its
-     *   plain view (mirrors the per-arm determinism rejects and the DDL determinism gate);
-     * - body with **no relational output** (degenerate);
-     * - **size**: full-rebuild is the only sound strategy *and* the **largest** participating
-     *   source exceeds the `materialized_view_rebuild_row_threshold` option
-     *   ({@link isFullRebuildPathological}) — every DML write would re-scan that source.
-     *   `0` disables the size reject (accept any size).
-     */
-    private buildFullRebuildPlan;
-    /**
-     * Compile the key-filtered residual for a binding into a reusable {@link Scheduler}:
-     * the analyzed body with a key-equality filter injected on `T`'s `TableReferenceNode`
-     * (parameterized `${paramPrefix}0…`), then optimized + emitted. Mirrors the assertion
-     * evaluator's residual compilation (`database-assertions.ts`) so the two cannot drift.
-     * Returns `null` if `injectKeyFilter` could not target `T` (the arm builder then falls
-     * through to the full-rebuild floor).
-     */
-    private compileResidual;
-    /**
-     * Execute a cached key-filtered residual for one affected key tuple, returning its
-     * result rows (0 or 1 for the aggregate shape; 0..N for the lateral-TVF fan-out shape).
-     * Bound through a fresh {@link RuntimeContext} on the live `db` so the residual's source
-     * scan reuses `T`'s transaction connection and reads this statement's pending writes
-     * (reads-own-writes) — the synchronous analogue of
-     * `database-assertions.ts:executeResidualPerTuple`. Shared by the residual-recompute
-     * (`'gk'`) and prefix-delete (`'pk'`) arms.
-     */
-    private runResidual;
-    /**
-     * Run a cached maintenance scheduler to completion against **live mid-transaction source
-     * state** and collect its result rows. Bound through a fresh strict {@link RuntimeContext}
-     * on the live `db` so the scan reuses the source's transaction connection and reads this
-     * statement's pending writes (reads-own-writes). The no-`stmt`, fresh-context shape is the
-     * synchronous analogue of `database-assertions.ts:executeResidualPerTuple`. Shared by the
-     * key-filtered residual arms ({@link runResidual}, parameterized) and the whole-body
-     * full-rebuild arm ({@link applyFullRebuild}, no params).
-     */
-    private runScheduler;
+    private applyMaintenancePlan;
     /**
      * Maintain a `'full-rebuild'` MV: re-evaluate the **whole** body against live
      * mid-transaction source state and replace the backing transactionally. Run the cached
      * {@link FullRebuildPlan.bodyScheduler} to completion (no params — reads-own-writes via
      * the same fresh-context path the residual arms use), collect every recomputed row, and
-     * apply a single `'replace-all'` {@link MaintenanceOp}: a keyed diff (by backing PK) of
+     * apply a single `'replace-all'` MaintenanceOp: a keyed diff (by backing PK) of
      * the recomputed rows against the backing's current pending-layer contents (insert/
      * update/delete, identical rows skipped). The diff rides the backing's **pending**
      * `TransactionLayer`, so it commits/rolls-back in lockstep with the source write, and the
@@ -967,176 +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.
+     * `'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;
     /**
-     * Compute a **forward** key-filtered residual plan's per-row backing delta and apply it:
-     * derive the affected binding key(s) from the changed row (OLD ∪ NEW, deduped), re-run
-     * the key-filtered residual against live source state for each, and apply the **keyed
-     * diff**: a non-empty recomputed slice is upserted (the backing key IS the affected key,
-     * so the upsert replaces the old row wholesale — no delete-first — and the host's
-     * value-identical upsert skip turns a no-op recompute into ZERO effective changes
-     * instead of delete+insert churn); an emptied slice (residual returns nothing) emits the
-     * point delete, removing the stale backing row (nothing reported if it was already
-     * absent). Returns the effective {@link BackingRowChange}(s) the backing layer realized,
-     * for the MV-over-MV cascade — a real same-key change now reports one `update`.
-     *
-     * Shared by the single-source aggregate (`'residual-recompute'`, group key, ≤1 row per
-     * key) and the 1:1-join (`'join-residual'`, the driving table `T`'s PK, exactly the one
-     * joined row per key) arms — both bind on the forward driving source via
-     * {@link ForwardResidualPlan}; the only difference is the binding (group vs PK).
-     *
-     * Per-row recompute is correct without per-statement batching: every change to a key
-     * triggers a full recompute of that key's slice from live (reads-own-writes) state, so
-     * the last change to touch a key writes the authoritative backing row. Batching/dedup
-     * across a whole statement is an affordability optimization deferred with the
-     * statement-flush boundary (see the ticket handoff).
-     */
-    private applyForwardResidual;
-    /**
-     * True iff `row`'s backing primary-key columns equal `keyVals` (the affected binding
-     * key, in `backingPkDefinition` order), under each column's collation. Used to keep
-     * only the residual row(s) belonging to the recomputed key — see
-     * {@link applyForwardResidual}.
-     */
-    private residualRowMatchesKey;
-    /**
-     * Dispatch a `'join-residual'` plan on **which source changed**. A write to the driving
-     * table `T` (`changedBase === plan.sourceBase`) is the forward case — recompute the one
-     * joined row keyed on `T`'s PK, identical to a size-1 `'row'`-binding residual — so it
-     * delegates straight to {@link applyForwardResidual} (delete old backing slice → run the
-     * `T`-keyed residual → upsert). A write to the lookup table `P` is the reverse case,
-     * handled by {@link applyLookupResidual}.
-     */
-    private applyJoinResidual;
-    /**
-     * Maintain a `'join-residual'` MV for a **lookup-side (`P`)** change: refresh the joined
-     * rows referencing each affected `P` key. Derive the affected `P` key(s) from the changed
-     * row (OLD ∪ NEW, deduped on `P`'s PK), and for each run the in-scope lookup-keyed residual
-     * (`… where P.pk = :pk0`, the body's WHERE retained) against live source state — returning
-     * every currently in-scope joined row, each carrying its `T.pk` backing key — and **upsert**
-     * each.
-     *
-     * **Upsert-only is sound for a no-WHERE / `T`-only-WHERE body.** For an inner/cross join with
-     * enforced RI and a predicate that cannot reference `P`, the *set* of backing rows referencing
-     * a given `P` row is `{ T : T.fk = P.pk }`, determined entirely by `T.fk` (a `T` column the
-     * `P` write cannot change), and the WHERE — over `T` only — cannot flip on a `P` write. So a
-     * `P` change can only re-derive the lookup-projected columns of those existing backing rows
-     * (an upsert at the unchanged `T.pk` key), never add or remove one: a `P` insert with no
-     * referencing `T` rows yields an empty residual (no-op); a `P` delete is only admissible (RI)
-     * when no `T` references it (empty residual); a `P` payload update upserts the affected rows
-     * with the new value.
-     *
-     * **A `P`-referencing WHERE needs the delete-capable pass.** When the body WHERE references
-     * `P`, a `P` write can flip a joined row's WHERE truth and so add or remove its backing row —
-     * which the in-scope upsert above (it returns *only* in-scope rows) could never delete. The
-     * builder then supplies `lookupMembershipResidualScheduler` (the body with the WHERE stripped,
-     * keyed on `P`). Per affected `P` key this runs both residuals against the same live state and
-     * applies the **keyed diff**: it **deletes** only the membership keys the in-scope recompute no
-     * longer produces (rows that left scope — the delete keys come from live `T` via the join, so
-     * they match existing backing keys and touch nothing belonging to another `P`; membership and
-     * in-scope rows read the same live state, so their key bytes match exactly), and **upserts**
-     * every in-scope row. A row leaving scope is deleted (removed); a row entering scope is
-     * upserted (added); an unchanged in-scope row's upsert is suppressed by the host's
-     * value-identical skip (vtab/backing-host.ts) — ZERO effective changes instead of the former
-     * delete+insert refresh churn; a changed in-scope row reports one `update`. The membership
-     * residual MUST ignore the WHERE — else a row leaving scope would never be deleted.
-     *
-     * A `T`-side membership change (insert/delete/FK-move) is the *forward* path's job and fires
-     * its own maintenance. Returns the effective {@link BackingRowChange}(s) for the MV-over-MV
-     * cascade. Per-row recompute is correct without batching for the same
-     * last-write-wins-against-live-state reason as {@link applyForwardResidual}.
-     */
-    private applyLookupResidual;
-    /**
-     * 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
-     * `null` on a shape mismatch (the caller falls through to the full-rebuild floor). The
-     * backing PK is the composite product key `(T.pk ∪ tvf-key)` that `keysOf` advertises
-     * through the lateral join; the base PK is its leading prefix. See {@link PrefixDeletePlan}
-     * and `docs/incremental-maintenance.md` § prefix-delete.
-     *
-     * Soundness gates (a mismatch on any returns `null` → floor): exactly one lateral TVF and
-     * one join (no nested/multi TVF, no aggregate over the fan-out); the TVF advertises a
-     * per-call key; the base PK projected and forming the **leading prefix** of the backing PK
-     * with a non-empty TVF-key tail (so each base row's fan-out rows are individually
-     * addressable and a by-prefix delete selects exactly one base row's slice). An `order by`
-     * over the fan-out that reorders the composite key so the base PK no longer leads is a
-     * `null` fall-through (the floor maintains it wholesale). The body's WHERE, if any, is part
-     * of the residual (so an out-of-scope base row fans out to zero rows), exactly as in the
-     * aggregate arm. A **non-deterministic** TVF / argument is the one hard reject (its
-     * arm-specific determinism diagnostic must survive).
-     */
-    private buildLateralTvfPrefixDeletePlan;
-    /**
-     * Compute a `'prefix-delete'` plan's per-row backing delta and apply it: derive the
-     * affected base key(s) from the changed row (OLD ∪ NEW, deduped on the base key), and
-     * for each — re-run the base-PK-keyed residual against live source state and apply the
-     * **keyed diff against the existing effective fan-out slice** (read via the host's
-     * `scanEffective` with the base prefix, pending over committed — the same contiguous
-     * range the former wholesale `'delete-by-prefix'` removed): delete ONLY the existing
-     * keys the recompute no longer produces, upsert every recomputed row (the host's
-     * value-identical skip suppresses the unchanged ones). A base-PK-changing UPDATE
-     * recomputes both the OLD base key (slice diffs to all-deletes; the residual returns
-     * nothing for the now-absent old PK) and the NEW base key (new fan-out upserted); a
-     * DELETE diffs the old slice to all-deletes; an INSERT diffs against an empty slice
-     * (all upserts). An emptied/shrunk fan-out keeps the delete-without-upsert exactly —
-     * a disappearance is never "skipped". Returns the effective
-     * {@link BackingRowChange}(s) the backing layer realized, for the MV-over-MV cascade.
-     *
-     * Prefix-scan soundness is unchanged from the wholesale arm: the diff's slice read
-     * uses the same binary `equalityPrefix` scan `'delete-by-prefix'` used, sound under
-     * the build-time collation gate (the backing base-PK prefix inherits the source PK
-     * collation, and source-PK uniqueness collapses each collation class to one binary
-     * value). The stored slice's prefix bytes always equal the OLD image's (the slice was
-     * projected from that very source row), and OLD ∪ NEW both iterate, so a case-only
-     * base-PK rewrite still converges: the OLD-prefix pass pairs the slice with the
-     * recomputed rows (key pairing is collation-aware — the btree's identity — so a
-     * collation-equal key is REPLACED by its upsert, never also deleted) and the byte
-     * change surfaces as `update`s that re-key the stored bytes.
-     *
-     * Structurally the same as {@link applyForwardResidual}, differing only in the
-     * **prefix-slice** diff (one base row owns N backing rows sharing the prefix) and the
-     * **N-row** residual. Per-row recompute is correct without per-statement batching: the
-     * residual reads live (reads-own-writes) state, so the last write to a base key produces
-     * the authoritative slice. (Statement-level dedup of distinct base keys is the same
-     * affordability optimization deferred for the aggregate arm.)
-     */
-    private applyPrefixDelete;
-    /**
-     * True iff two backing rows agree on every backing-PK column under that column's
-     * collation — the btree's key identity. Pairs an existing slice row with the
-     * recomputed row that replaces it in {@link applyPrefixDelete}'s keyed diff.
-     */
-    private backingPkEqual;
-    /**
-     * True iff `row`'s **leading** (base-prefix) backing-PK columns equal `prefixVals` (the
-     * affected base key, in backing-PK order), under each column's collation. Keeps only the
-     * residual fan-out row(s) belonging to the recomputed base key — see
-     * {@link applyPrefixDelete}.
-     */
-    private residualRowMatchesBasePrefix;
-    /**
-     * Assemble {@link MaintenanceSourceStats} for the cost gate from the optimizer's
-     * StatsProvider and tuning. `tableRows` / `distinctGroupsEstimate` come from the
-     * provider (heuristic defaults when absent); `forwardBodyCost` is estimated from the
-     * forward cost helpers (a scan + optional filter + projection of the source — the
-     * covering-index body shape); `fallbackRatio` carries the detection kernel's
-     * `deltaPerRowFallbackRatio` for the no-stats residual path.
-     */
-    /**
-     * The CURRENT `TableSchema` of a source `TableReferenceNode`, re-resolved through the
-     * schema manager. A plan node captures the schema as of plan-build; a later `analyze`
-     * replaces the catalog entry with one carrying fresh `statistics`, so the stale captured
-     * schema would report pre-`analyze` row counts. Re-resolving keeps the floor's size gate
-     * on the live source size. Falls back to the node's captured schema if the name no longer
-     * resolves (it always should — the body planned).
+     * 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 liveSourceSchema;
-    private estimateMaintenanceStats;
+    private applyReplaceAll;
     /**
      * Resolve the linked, enforcement-ready covering MV for a UNIQUE constraint on
      * `schema.table`, or `undefined`. The constraint's `coveringStructureName`
@@ -1144,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
@@ -1249,5 +498,4 @@ export declare class MaterializedViewManager {
      */
     private tryBuildCoveringPrefix;
 }
-export {};
 //# sourceMappingURL=database-materialized-views.d.ts.map