@quereus/quereus 4.3.1 → 4.4.0

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

@@ -0,0 +1,422 @@
+/**
+ * Materialized-view maintenance — **delta apply**. The per-row / per-flush appliers that
+ * take a compiled {@link MaintenancePlan} plus a source {@link BackingRowChange}, compute the
+ * bounded backing delta (or the full-rebuild diff), and write it through the backing table's
+ * coordinated transaction connection — plus the residual runners, backing-host / connection
+ * resolvers, derived-row and parent-side referential enforcement, and the small key-compare
+ * helpers they share. Extracted from database-materialized-views.ts as free functions over
+ * {@link MaterializedViewManagerContext}; the manager's orchestration methods
+ * (`maintainRowTime`, `flushDeferredMaintenance`, `lookupCoveringConflicts`) call in.
+ */
+import { type SqlValue, type Row } from '../common/types.js';
+import { Scheduler } from '../runtime/scheduler.js';
+import { type DerivedRowConstraintValidator } from './derived-row-validator.js';
+import type { BackingHost, BackingRowChange, MaintenanceOp } from '../vtab/backing-host.js';
+import type { VirtualTableConnection } from '../vtab/connection.js';
+import type { TableSchema } from '../schema/table.js';
+import type { MaterializedViewManagerContext, MaintenancePlan, InverseProjectionPlan, ForwardResidualPlan, JoinResidualPlan, PrefixDeletePlan, ResidualMaintenancePlan, ResidualRecomputePlan, ForwardResidualKey, PrefixDeleteKey, ResidualKeyBatch, ResidualKeyBatchEntry, BackingConnectionCache, BackingPkColumn } from './database-materialized-views-plans.js';
+/**
+ * Resolve a plan's backing table to its {@link BackingHost} + coordinated
+ * {@link VirtualTableConnection} — the two handles every apply path writes through.
+ * Shared by the per-row appliers, the batched residual flush, and the full-rebuild
+ * `'replace-all'` diff; throws INTERNAL when the backing table has vanished (an MV in a
+ * broken state).
+ */
+export declare function resolveBackingApplyTarget(ctx: MaterializedViewManagerContext, plan: Pick<MaintenancePlan, 'mv' | 'backingSchema' | 'backingTableName'>, cache?: BackingConnectionCache): Promise<{
+    host: BackingHost;
+    connection: VirtualTableConnection;
+}>;
+/**
+ * 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.
+ */
+export declare function applyInverseProjection(ctx: MaterializedViewManagerContext, plan: InverseProjectionPlan, change: BackingRowChange, cache?: BackingConnectionCache): Promise<BackingRowChange[]>;
+/**
+ * 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.
+ */
+export declare function validateDerivedChanges(ctx: MaterializedViewManagerContext, plan: MaintenancePlan, validator: DerivedRowConstraintValidator, changes: readonly BackingRowChange[], cache?: BackingConnectionCache): Promise<void>;
+/**
+ * Row-time guard: reject a maintenance write that would store a NULL into a backing column
+ * the schema declares NOT NULL *and* that is a physical-PK member whose re-derived body
+ * output turned nullable — the row-time analogue of the refresh-path
+ * `assertNoNullInNotNullSeededPk` (runtime/emit/materialized-view-helpers.ts). Row-time
+ * maintenance is the PRIMARY silent-corruption vector: it fires at the source
+ * insert/update, before any refresh, so without this guard a NULL lands in a
+ * declared-NOT-NULL PK column with no error.
+ *
+ * The offending skew (a NOT-NULL ordering-seeded PK column over a loosened source) is
+ * precomputed once at plan build into {@link MaintenancePlanCommon.nullGuardColumns}
+ * (`undefined` for nearly every MV — the zero-overhead gate), so the common path pays a
+ * single boolean check per maintained write and only the rare skewed MV scans its guarded
+ * columns per change. A `delete` writes no image and is skipped. The throw unwinds the source
+ * statement with nothing committed — the backing write rides the pending layer, discarded on
+ * a throw before commit, exactly like {@link validateDerivedChanges}. Called BEFORE the
+ * MV-over-MV cascade so a NULL row never reaches a consumer. See
+ * fix/bug-mv-rowtime-null-into-notnull-seeded-pk.
+ */
+export declare function assertNoNullInNotNullSeededPkRowTime(plan: MaintenancePlan, changes: readonly BackingRowChange[]): void;
+/**
+ * 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.
+ */
+export declare function enforceParentSideReferentialActions(ctx: MaterializedViewManagerContext, plan: MaintenancePlan, changes: readonly BackingRowChange[]): Promise<void>;
+/**
+ * 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.
+ */
+export declare function backingHost(ctx: MaterializedViewManagerContext, backing: TableSchema): 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.
+ */
+export declare function getBackingConnection(ctx: MaterializedViewManagerContext, host: BackingHost, qualifiedName: string, cache?: BackingConnectionCache): Promise<VirtualTableConnection>;
+/**
+ * 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.
+ */
+export declare function runResidual(ctx: MaterializedViewManagerContext, residualScheduler: Scheduler, bindParamPrefix: 'gk' | 'pk', keyTuple: readonly SqlValue[]): Promise<Row[]>;
+/**
+ * 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).
+ */
+export declare function runScheduler(ctx: MaterializedViewManagerContext, scheduler: Scheduler, params: Record<string, SqlValue>): Promise<Row[]>;
+/**
+ * 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).
+ *
+ * This is the **cold** (no statement batch in scope) inline path. A statement-batched
+ * caller instead accumulates the same deduped keys via
+ * {@link collectForwardResidualKeys} and recomputes each distinct key once at the
+ * end-of-statement flush ({@link computeForwardResidualOps}) — sound for the same
+ * last-write-wins reason: every recompute reads live (reads-own-writes) state, so
+ * running it once at flush produces exactly what the last per-row run would have.
+ */
+export declare function applyForwardResidual(ctx: MaterializedViewManagerContext, plan: ForwardResidualPlan, change: BackingRowChange, cache?: BackingConnectionCache): Promise<BackingRowChange[]>;
+/**
+ * Derive one changed source row's affected forward binding key(s) (OLD ∪ NEW) and add
+ * them to `into`, deduped on the canonical backing-key values: a non-key-changing update
+ * recomputes the group once; a key-changing update recomputes both the old and the new
+ * group. `into` may span a whole statement (the per-statement {@link ResidualKeyBatch})
+ * or a single change (the cold inline path) — the dedup is identical either way.
+ */
+export declare function collectForwardResidualKeys(plan: ForwardResidualPlan, change: BackingRowChange, into: Map<string, ForwardResidualKey>): void;
+/**
+ * Run the forward key-filtered residual once per affected key and build the keyed-diff
+ * ops: upsert the recomputed slice, or point-delete an emptied key. Pure op computation —
+ * the caller owns connection resolution and the single {@link BackingHost.applyMaintenance}
+ * call, so a statement flush can batch many keys' ops into one host call.
+ */
+export declare function computeForwardResidualOps(ctx: MaterializedViewManagerContext, plan: ForwardResidualPlan, keys: Iterable<ForwardResidualKey>): Promise<MaintenanceOp[]>;
+/**
+ * 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}.
+ */
+export declare function residualRowMatchesKey(plan: ForwardResidualPlan, row: Row, keyVals: readonly SqlValue[]): boolean;
+/**
+ * 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}.
+ */
+export declare function applyJoinResidual(ctx: MaterializedViewManagerContext, plan: JoinResidualPlan, change: BackingRowChange, changedBase: string, cache?: BackingConnectionCache): Promise<BackingRowChange[]>;
+/**
+ * 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. This is the cold inline path; a statement-batched caller accumulates via
+ * {@link collectLookupResidualKeys} and recomputes at flush ({@link computeLookupResidualOps})
+ * — sound for the same last-write-wins-against-live-state reason as
+ * {@link applyForwardResidual}.
+ */
+export declare function applyLookupResidual(ctx: MaterializedViewManagerContext, plan: JoinResidualPlan, change: BackingRowChange, cache?: BackingConnectionCache): Promise<BackingRowChange[]>;
+/**
+ * Derive one changed lookup-side (`P`) row's affected lookup key(s) (OLD ∪ NEW) and add
+ * them to `into`, deduped on `P`'s canonical PK values. The statement-batch counterpart
+ * of the derivation inside {@link applyLookupResidual}.
+ */
+export declare function collectLookupResidualKeys(plan: JoinResidualPlan, change: BackingRowChange, into: Map<string, SqlValue[]>): void;
+/**
+ * Run the lookup-keyed residual variant once per affected `P` key and build the ops —
+ * the delete-capable membership diff when the plan carries
+ * `lookupMembershipResidualScheduler`, upsert-only otherwise (see
+ * {@link applyLookupResidual} for the soundness argument). Pure op computation; the
+ * caller owns connection resolution and the single applyMaintenance call.
+ */
+export declare function computeLookupResidualOps(ctx: MaterializedViewManagerContext, plan: JoinResidualPlan, keys: Iterable<SqlValue[]>): Promise<MaintenanceOp[]>;
+/**
+ * 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. This is the cold inline path; a statement-batched caller
+ * accumulates the same deduped base keys via {@link collectPrefixDeleteKeys} and diffs
+ * each distinct key once at flush ({@link computePrefixDeleteOps}) — sound because the
+ * residual and the effective-slice read both see live (reads-own-writes) state, so the
+ * flush-time diff is exactly what the last per-row diff would have produced.
+ */
+export declare function applyPrefixDelete(ctx: MaterializedViewManagerContext, plan: PrefixDeletePlan, change: BackingRowChange, cache?: BackingConnectionCache): Promise<BackingRowChange[]>;
+/**
+ * Derive one changed base row's affected base key(s) (OLD ∪ NEW) and add them to
+ * `into`, deduped on the canonical base-PK values. `keyTuple` binds the residual
+ * (`pk{i}`); `prefix` is the slice's leading-PK equality key (the base-PK values in
+ * backing-PK order — identical here since the base PK leads the backing PK, but kept
+ * distinct for clarity). The statement-batch counterpart of the derivation inside
+ * {@link applyPrefixDelete}.
+ */
+export declare function collectPrefixDeleteKeys(plan: PrefixDeletePlan, change: BackingRowChange, into: Map<string, PrefixDeleteKey>): void;
+/**
+ * Per affected base key: run the fan-out residual, read the existing effective slice for
+ * the base prefix, and build the keyed-diff ops (delete disappeared keys, upsert the
+ * recomputed rows). Pure op computation over the supplied host/connection; the caller
+ * owns the single applyMaintenance call, so a statement flush batches many base keys'
+ * ops into one host call.
+ */
+export declare function computePrefixDeleteOps(ctx: MaterializedViewManagerContext, plan: PrefixDeletePlan, keys: Iterable<PrefixDeleteKey>, host: BackingHost, connection: VirtualTableConnection): Promise<MaintenanceOp[]>;
+/**
+ * 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.
+ */
+export declare function backingPkEqual(pkDef: ReadonlyArray<BackingPkColumn>, a: Row, b: Row): boolean;
+/**
+ * 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}.
+ */
+export declare function residualRowMatchesBasePrefix(plan: PrefixDeletePlan, row: Row, prefixVals: readonly SqlValue[]): boolean;
+/**
+ * Accumulate one source change's affected binding key(s) for a residual-arm plan into
+ * the per-statement {@link ResidualKeyBatch}, deduped across the whole statement —
+ * the deferred-accumulate counterpart of the cold per-row appliers above. Which
+ * variant map receives the keys follows the plan kind; a `'join-residual'` change
+ * routes on **which source changed** (forward for the driving `T`, lookup for `P`),
+ * exactly as {@link applyJoinResidual} dispatches. `planKey` is the MV key
+ * (lowercased `schema.name`) the manager indexes the plan under.
+ */
+export declare function accumulateResidualKeys(plan: ResidualMaintenancePlan, change: BackingRowChange, changedBase: string, batch: ResidualKeyBatch, planKey: string): void;
+/**
+ * Compute the flush-time ops for one residual-arm MV's accumulated statement keys: run
+ * the appropriate residual variant once per distinct key against live post-statement
+ * state and concatenate the keyed-diff ops. Distinct keys touch disjoint backing slices
+ * — except a `'join-residual'` statement that accumulated both forward and lookup keys,
+ * where an overlapping backing row is recomputed twice from the SAME live state, so the
+ * duplicate upsert is value-identical and the host suppresses it. The caller owns the
+ * single {@link BackingHost.applyMaintenance} call over the combined array — one host
+ * round-trip per (MV, flush round) instead of one per source row.
+ */
+export declare function computeResidualBatchOps(ctx: MaterializedViewManagerContext, plan: ResidualMaintenancePlan, entry: ResidualKeyBatchEntry, host: BackingHost, connection: VirtualTableConnection): Promise<MaintenanceOp[]>;
+/**
+ * Fold one source change's per-column aggregate contributions into the statement's
+ * delta accumulation ({@link ResidualKeyBatchEntry.delta}) — the delta-aggregate
+ * counterpart of {@link collectForwardResidualKeys}, called right after it (the
+ * residual keys remain the fallback record). Per contributing row image:
+ * `step(identity, row[arg])` (zero-arg → `step(identity)`) is the row's contribution;
+ * an insert `merge`s it in, a delete `merge`s its `negate`, an update retracts the OLD
+ * image into its group and inserts the NEW into its (possibly different) group. A row
+ * whose body-WHERE predicate is not unambiguously TRUE contributes nothing — but the
+ * raw column value (including NULL) IS fed to `step`, never pre-filtered: NULL-handling
+ * is the aggregate's own (law 2), and the row still counts toward the zero-arg
+ * multiplicity witness.
+ */
+export declare function accumulateDeltaAggregates(plan: ResidualRecomputePlan, change: BackingRowChange, entry: ResidualKeyBatchEntry): void;
+/**
+ * Flush-time op computation for a delta-aggregate MV's accumulated statement deltas —
+ * the arithmetic read-modify-write that replaces the per-group residual re-execution.
+ * Per affected group:
+ *  1. read the group's current EFFECTIVE backing row by its full PK (the host's
+ *     `scanEffective` equality-prefix point read — pending over committed, so a group
+ *     written by an earlier statement of this transaction folds correctly);
+ *  2. per aggregate column: base = stored ? `decode(stored[col])` : a fresh identity
+ *     accumulator; finalized = `finalize(merge(base, delta))`;
+ *  3. the multiplicity witness finalizing to 0 ⇔ the group emptied → `delete-key`
+ *     (skipped when no row was stored); otherwise upsert the rebuilt row (group-key
+ *     values + finalized aggregates) — the host's value-identical skip suppresses a
+ *     net-identity delta (MV-016).
+ *
+ * **Retraction fallback.** A group that accumulated a retraction re-derives from its
+ * residual key (always accumulated alongside, same canonical map key) instead of the
+ * arithmetic, in two cases:
+ *  - the descriptor has a **tighten** column (min/max — merge, no negate): a retraction
+ *    cannot be undone by merge, so the whole group re-derives from live source state
+ *    **whether or not a row is stored** (an intra-statement delete of the extreme poisons
+ *    even a from-identity net-fold). The residual recomputes every column of the row
+ *    (count/sum included), so a mixed group+tighten row is maintained by ONE path — no
+ *    double-maintenance;
+ *  - otherwise the descriptor is not retraction-safe (an abelian column whose decode is
+ *    only an insert-observational witness — a nullable-argument sum) AND a stored row
+ *    exists: the stored value cannot prove the true contribution count survives the
+ *    retraction, so decoding it is unsound. A group with no stored row needs no fallback
+ *    here — a pure abelian net-fold from identity is exact.
+ *
+ * Zero source reads, no residual execution on the arithmetic path — this is why the
+ * delta path also BYPASSES the per-statement degrade-to-rebuild crossover (it is
+ * already O(affected groups)).
+ */
+export declare function computeDeltaAggregateOps(ctx: MaterializedViewManagerContext, plan: ResidualRecomputePlan, entry: ResidualKeyBatchEntry, host: BackingHost, connection: VirtualTableConnection): Promise<MaintenanceOp[]>;
+/**
+ * Invalidate every accumulated delta in the per-statement batch — called by the DML
+ * executor when an OR FAIL per-row savepoint ROLLS BACK: the savepoint undoes the
+ * failing row's source (and backing) writes, but the JS-side accumulation cannot be
+ * unwound, so the folded deltas may carry the reverted row's contribution. The residual
+ * keys are unaffected (a reverted key's recompute reads surviving live state and is
+ * value-identical → suppressed), so poisoning simply drops the fast path: the flush in
+ * the executor's catch routes those entries through the plain residual. One-way for the
+ * statement — `deltaPoisoned` also stops later (cascade-driven) delta re-accumulation
+ * into the same entry from mixing with an already-flushed-around state.
+ */
+export declare function poisonResidualDeltaAccumulations(batch: ResidualKeyBatch): void;
+//# sourceMappingURL=database-materialized-views-apply.d.ts.map

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

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