@quereus/quereus 3.3.0 → 4.1.0

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

@@ -0,0 +1,1253 @@
+/**
+ * Materialized-view maintenance: schema-change staleness tracking plus row-time
+ * write-through maintenance.
+ *
+ * Two responsibilities:
+ *
+ *  1. **Staleness** — a *schema* change to a source table (drop / alter) can break
+ *     an MV's body. This manager subscribes to schema-change events and marks any
+ *     MV whose body reads a modified/removed source `stale`. The next reference
+ *     re-validates the body (erroring with the staleness diagnostic on an
+ *     incompatible change); the next successful refresh clears the flag. One
+ *     carve-out: a **body-irrelevant** `table_modified` (constraint/stats/tags-only —
+ *     columns and physical PK identical, see `isBodyIrrelevantTableChange`) instead
+ *     RECOMPILES each live dependent's row-time plan in place
+ *     (`tryRecompileMaterializedViewLive`, gated by shape re-derivation), falling
+ *     back to mark-stale on any failure — so DROP/ADD/RENAME CONSTRAINT and ANALYZE
+ *     no longer de-liven dependents whose backing shape is unaffected. The SAME
+ *     subscription also rebuilds a maintained table's compiled **derived-row
+ *     constraint validator** when a *constraint-only* dependency — an FK parent or a
+ *     subquery-CHECK target, neither a derivation source — is renamed/dropped/re-created
+ *     (see {@link MaterializedViewManager.rebuildConstraintValidatorsFor}); without
+ *     this the validator, compiled once at registration, would keep resolving against
+ *     the dead/renamed incarnation and fail maintenance writes with an internal
+ *     module-connect error.
+ *
+ *  2. **Row-time write-through** (`maintainRowTime`) — the backing table is kept
+ *     consistent *synchronously* with each source row-write, driven from the
+ *     runtime DML boundary (not at COMMIT). Each MV's maintenance is **cost-gated with a
+ *     floor**: the builder matches the body to a bounded-delta arm (the covering-index
+ *     inverse projection, an aggregate / lateral-TVF / 1:1-join residual) when one fits —
+ *     each source row then maps to a bounded backing delta, no full scan — and otherwise
+ *     falls through to the always-correct **full-rebuild floor** (re-evaluate the whole
+ *     body, replace the backing). **No body is rejected for its shape;** the only
+ *     create-time rejections are non-shape (non-determinism, bag/no-key, no relational
+ *     output, and a full-rebuild-only body over a source past the size threshold). The
+ *     write targets the backing table's *pending* transaction layer through the same
+ *     connection a `select` from the MV uses, so the change is visible mid-transaction
+ *     (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>;
+export declare class MaterializedViewManager {
+    private readonly ctx;
+    private unsubscribeSchemaChanges;
+    /** Compiled maintenance plans keyed by MV `schema.name` (lowercase). */
+    private readonly rowTime;
+    /** Source base (lowercased `schema.table`) → set of MV keys with a row-time plan
+     *  reading it. The per-row DML maintenance hook looks plans up by source base. */
+    private readonly rowTimeBySource;
+    constructor(ctx: MaterializedViewManagerContext);
+    private subscribeToSchemaChanges;
+    /**
+     * Rebuild the derived-row constraint validator of every registered plan whose
+     * validator depends on `changed` (lowercased `schema.table`): it names `changed`
+     * in {@link DerivedRowConstraintValidator.dependencyTables} (FK parent /
+     * subquery-CHECK target), or — when `matchOwnName` — `changed` IS the maintained
+     * table itself (the rename signal; see {@link subscribeToSchemaChanges}).
+     *
+     * The derivation is unaffected by a constraint-only dependency's DDL, so this
+     * rebuilds the validator ONLY — no {@link releaseRowTime}, no staleness, no
+     * maintenance interruption. The rebuild reads the CURRENT catalog record
+     * (`getMaintainedTable`) so a rename re-resolves against the new name, and
+     * replacing the validator also refreshes its `dependencyTables` (a rename re-keys
+     * `{main.parent}` → `{main.parent2}`, so a later drop of `parent2` is caught too).
+     *
+     * Rebuild-failure handling: a rebuild THROWS when the subquery-CHECK target was
+     * dropped (`buildConstraintChecks` → optimize raises a sited "table not found").
+     * The throw is caught and a {@link makePoisonedDerivedRowValidator} installed, so
+     * (a) this listener never propagates an exception — a schema-change event must not
+     * fail the unrelated DDL that triggered it — and (b) the next derivation write
+     * surfaces the clear sited planning error instead of the stale validator's internal
+     * module-connect failure. The FK-parent-dropped case does NOT throw: the
+     * absent-parent null-guards-only fallback (`buildChildSideFKChecks`) builds cleanly,
+     * so the rebuilt validator is healthy (a non-NULL ref fails with the maintained-table
+     * FK attribution; a NULL ref is admitted under MATCH SIMPLE).
+     */
+    private rebuildConstraintValidatorsFor;
+    /**
+     * Emit a synthetic `table_modified` event for `mv`'s backing table so any cached
+     * prepared-statement plan that reads the backing table directly invalidates →
+     * recompiles → re-hits the build-time `stale` guard in `building/select.ts`.
+     *
+     * A `select … from mv` compiled while the MV was NOT stale resolves to a
+     * `TableReference` against the maintained table itself, so its only schema
+     * dependency is that table. The *source* change event that marks the MV stale never
+     * names the maintained table, so without this emit the cached plan would re-run the
+     * scan and serve stale rows against a structurally-changed source — bypassing the
+     * guard a fresh prepare would hit. (A plan compiled while the MV is *already* stale
+     * is separately safe: the while-stale build-time re-validation resolves the body's
+     * source tables and records them as direct statement dependencies, so a later source
+     * change invalidates it without this emit — verified by the regression suite, which
+     * stays green even with the emit removed for that case.) The `Statement` listener
+     * maps `table_*` → `'table'` and matches on type + objectName (+ optional schemaName)
+     * only, ignoring the payload, so the maintained `TableSchema` is passed as both old/new.
+     *
+     * **Same-object payload contract (load-bearing coupling).** Passing the SAME object
+     * as `oldObject` and `newObject` is what keeps this synthetic event body-RELEVANT to
+     * `isBodyIrrelevantTableChange` (its reference-equality guard) — so it cascades
+     * staleness down an MV-over-MV chain instead of triggering the consumers'
+     * recompile-in-place path. Every genuine `table_modified` emitter passes distinct
+     * old/new objects. If this payload ever changes, change the classifier's guard with
+     * it (see the matching comment in runtime/emit/materialized-view-helpers.ts).
+     *
+     * Safety: the event names the maintained table itself, which is never in its OWN
+     * `sourceTables` (self-reference is rejected at create), so this manager's listener
+     * treats it as a no-op for a plain MV; for an MV-over-MV chain it conservatively
+     * cascades staleness down the producer→consumer DAG (acyclic — a consumer requires
+     * its producer to pre-exist), so the nested notification terminates. If the table
+     * lookup unexpectedly fails the MV is already in a broken state — skip the emit
+     * rather than fabricate a partial event.
+     */
+    private emitBackingInvalidation;
+    /**
+     * Compile + register an MV for row-time write-through maintenance. Always
+     * builds the maintenance plan via {@link buildMaintenancePlan}, which throws on a
+     * body that is not row-time maintainable — the create emitter rolls the MV back on
+     * throw, so an ineligible body errors cleanly at create time.
+     */
+    registerMaterializedView(mv: MaintainedTableSchema): void;
+    /** Detach an MV's row-time plan + its source-base index entry (DROP path). */
+    unregisterMaterializedView(schemaName: string, name: string): void;
+    /**
+     * Force-mark an MV stale: set the flag, detach its row-time plan, and invalidate
+     * cached prepared-statement plans reading its backing so the next reference
+     * re-hits the build-time stale guard. Mirrors the schema-change listener's stale
+     * transition exactly; exposed for the ALTER … RENAME propagation failure path
+     * (a dependent MV whose in-place body rewrite / backing rename / re-registration
+     * failed mid-way must not keep serving its backing as if live).
+     */
+    markMaterializedViewStale(mv: MaintainedTableSchema): void;
+    dispose(): void;
+    /** Drop a row-time plan and its source-base index entry (DROP / schema-change / re-register). */
+    private releaseRowTime;
+    /**
+     * The source bases (lowercased `schema.table`) an MV's body reads — the
+     * dependency edges {@link Database.refreshAllMaterializedViews} orders the
+     * convergence sweep on. A registered (live) MV reports its compiled plan's
+     * bases ({@link planSourceBases} — the same set `rowTimeBySource` indexes it
+     * under). A **stale** MV has no live plan (a body-relevant source change
+     * released it), so its bases come from the recorded
+     * {@link import('../schema/derivation.js').TableDerivation.sourceTables} — the
+     * body's source-table set captured at (re)registration and kept current
+     * through every reshape. That recorded set is identical to what re-planning
+     * the body would derive (the create/refresh path fills it from the same
+     * analysis), but never re-plans a stale body that may no longer plan — so the
+     * ordering pass cannot throw a planning error before the per-MV refresh
+     * surfaces the real staleness diagnostic.
+     */
+    sourceBasesFor(mv: MaintainedTableSchema): readonly string[];
+    /**
+     * All maintained tables in **source-dependency order**: a base MV precedes
+     * every MV whose body reads it (MV-over-MV — in the unified model a base MV's
+     * backing is a table under its own name, so a dependent's
+     * {@link sourceBasesFor} contains that qualified name). A sequential refresh
+     * sweep over this order is correct because refresh is commit-first per MV: a
+     * base MV's backing commits before a dependent's body re-reads it
+     * ({@link Database.refreshAllMaterializedViews}).
+     *
+     * Edges are `sourceBasesFor(mv)` intersected with the MV-key set (a non-MV
+     * source is no ordering constraint); Kahn's algorithm produces the order.
+     * Throws {@link StatusCode.INTERNAL} on a cycle — the create-time gates
+     * (`assertNoSelfReference` / `assertNoDerivationCycle`) reject recursive MVs,
+     * so a cycle here is an impossible-state backstop, never a silently dropped MV.
+     */
+    materializedViewRefreshOrder(): MaintainedTableSchema[];
+    /**
+     * Precompute the weakened-K′-column watch list for row-time collision telemetry —
+     * one entry per coarsening column of the MV's coarsened backing key. Returns
+     * `undefined` (the zero-overhead gate) unless `mv.derivation.coarsenedKey` is
+     * stamped with ≥1 weakened column: a provable-key or refining-lineage-key MV builds
+     * no watch, so {@link detectAndReportCoarseningCollisions} short-circuits and the
+     * maintenance path is untouched. Each weakened column name resolves to its backing
+     * column index via `mv.columnIndexMap` (the maintained table IS the backing table),
+     * carrying the source → output collations the divergence test needs.
+     */
+    private buildCoarseningWatch;
+    /**
+     * Observe-only row-time collision telemetry: scan the **realized**
+     * {@link BackingRowChange}s a maintenance apply produced and queue a
+     * {@link MaintenanceCollisionEvent} for each one that is a key-coarsening collision —
+     * an `update` whose replaced backing row came from a **distinct source identity**
+     * than the incoming row's, merged under the coarsened backing key K′ (last-writer-win).
+     *
+     * **Zero-overhead gate.** Returns immediately unless `plan.coarseningWatch` is present
+     * (only a coarsened-key MV builds one). A non-coarsened MV never scans `backingChanges`.
+     *
+     * **Criterion.** For each `'update'` change, a weakened K′ column is *diverged* when its
+     * old/new backing values differ under the **source** (pre-coarsening, stricter) collation.
+     * An `update` here means the incoming row landed on an existing backing row sharing K′
+     * under the **output** collation (that is what made the upsert replacing, not inserting);
+     * if those rows are equal under the source collation it is the same source row's value
+     * being updated (e.g. an `email` change — not reported), and if they differ under the
+     * source collation two distinct source identities (`'Bob'`/`'bob'`) collapsed onto one
+     * backing key (reported). `insert`/`delete` changes are never collisions (new key / removal).
+     *
+     * Runs **independently** of the cascade — it neither consumes nor reorders the
+     * `backingChanges` routed onward (observe-only), so an MV-over-MV chain is unperturbed.
+     * The queued event rides the emitter's transaction batching, so a collision inside a
+     * rolled-back transaction reports nothing and does not increment the counter.
+     */
+    private detectAndReportCoarseningCollisions;
+    /**
+     * True iff a row-time covering structure reads `sourceBase` (lowercased
+     * `schema.table`). The DML write boundary consults this synchronously so the
+     * per-row maintenance hook is a zero-allocation no-op when nothing depends on
+     * the written table.
+     */
+    hasRowTimePlanFor(sourceBase: string): boolean;
+    /**
+     * Synchronously maintain every row-time covering structure on `sourceBase` for
+     * one source row-write. Each plan computes the per-row backing delta (a pure
+     * projection of the changed row) and applies it to the backing table's pending
+     * transaction layer through the connection a `select` from the MV would use —
+     * so the write is visible mid-transaction and rides the coordinated commit.
+     *
+     * **MV-over-MV cascade.** A backing write is itself a row-write that every MV
+     * reading *that backing table* must see. When a plan's backing base has its own
+     * dependents (`rowTimeBySource[backingBase]` non-empty), each effective
+     * {@link BackingRowChange} the write produced is routed back through this method,
+     * recursively. The dependency graph is acyclic (a consumer MV requires its
+     * producer MV to already exist at create time), so this synchronous depth-first
+     * recursion is DAG-ordered — a producer's backing is fully written before its
+     * consumers run — and the whole chain commits/rolls-back atomically on the live
+     * transaction. The leaf fast path (`!rowTimeBySource.has(backingBase)`) keeps a
+     * non-chained MV at exactly today's cost (one map lookup, no recursion). `depth`
+     * feeds the structural-cycle backstop in {@link assertCascadeDepth}.
+     *
+     * `cache` is the optional per-statement {@link BackingConnectionCache}: when the
+     * DML boundary supplies one, every backing (this plan's and each cascade level's)
+     * resolves its connection at most once for the whole statement. The cascade threads
+     * the same cache through, so a multi-level chain amortizes each level's resolution
+     * 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.
+     *
+     * 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
+     * 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,
+     * 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
+     * rather than spin. This should never fire.
+     */
+    private assertFlushRounds;
+    /**
+     * Defense-in-depth backstop for the cascade. Cycles are structurally impossible
+     * (a consumer MV can only be created once its producer exists, and an MV's source
+     * set is fixed at create), so a valid chain descends at most once per registered
+     * row-time MV. A depth beyond that count signals a structural impossibility (a
+     * cycle) — fail loud with `INTERNAL` naming the backing base rather than overflow
+     * the stack. This should never fire.
+     */
+    private assertCascadeDepth;
+    /**
+     * Dispatch a maintenance plan on its `kind`, compute the per-row backing delta,
+     * apply it, and return the **effective** {@link BackingRowChange}(s) the backing
+     * layer realized (so the cascade can drive this plan's own dependents). The builder
+     * yields `'inverse-projection'` (covering-index shape), `'residual-recompute'`
+     * (single-source aggregate), `'prefix-delete'` (single-source lateral-TVF fan-out), and
+     * `'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.
+     */
+    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;
+    /**
+     * 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
+     * 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
+     * returned effective {@link BackingRowChange}(s) drive the MV-over-MV cascade unchanged.
+     *
+     * 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
+     * rebuilds exactly once; this is that one rebuild. An empty body (zero rows) yields a
+     * `'replace-all' []`, which empties the backing.
+     */
+    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).
+     */
+    private liveSourceSchema;
+    private estimateMaintenanceStats;
+    /**
+     * Resolve the linked, enforcement-ready covering MV for a UNIQUE constraint on
+     * `schema.table`, or `undefined`. The constraint's `coveringStructureName`
+     * forward pointer (set by the eager prove-and-link) is the source of truth;
+     * 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.
+     *
+     * **Collation eligibility gate.** A covering MV generates its conflict candidates
+     * by re-comparing each backing row under the SOURCE column's DECLARED collation
+     * ({@link lookupCoveringConflicts} / {@link tryBuildCoveringPrefix}), while the
+     * re-validators (store `findUniqueConflictViaCoveringMv`, memory
+     * `checkUniqueViaMaterializedView`) filter under the index per-column collation. The
+     * candidate set is a sound *superset* of the index-collation matches — safe to filter
+     * down — only when the index collation is coarser-or-equal to the declared collation
+     * per constrained column (see {@link coveringMvHonorsIndexCollation}). For a
+     * finer/incomparable index-derived UNIQUE (e.g. a coarser NOCASE index over a BINARY
+     * column) the candidate set may be a *subset* that silently misses conflicts, so the
+     * MV is declined here and enforcement falls back to the per-scan / auto-index path
+     * (already correct under the index collation). All three callers (store, memory,
+     * lens-prover) consult this resolver, so they decline the same MV in lockstep and
+     * candidate generation never runs for a declined MV. This gate is load-bearing, not
+     * mere defense-in-depth: the covering-link prover's own collation gate compares the
+     * OUTPUT column collation against the DECLARED base-column collation (not the index
+     * collation), so it DOES link a coarser-index covering MV — confirmed by the
+     * premise-check test in `covering-structure.spec.ts`.
+     */
+    findRowTimeCoveringStructure(schemaName: string, tableName: string, uc: UniqueConstraintSchema): MaintainedTableSchema | undefined;
+    /**
+     * Resolve a constraint's `coveringStructureName` forward pointer. Prefers the
+     * pointer already on the passed `uc` (the memory source shares the
+     * schema-manager's frozen constraint, so the eager link's mutation is visible).
+     * A store source holds a *copied* schema whose constraint never received the
+     * mutation, so fall back to the authoritative schema-manager constraint matched
+     * by column set — keeping the covering-structure lookup module-agnostic.
+     */
+    private resolveCoveringStructureName;
+    /**
+     * Point-look up the covering MV's backing table for rows whose backing columns
+     * equal `newRow`'s UNIQUE-constraint values, recover each conflicting **source**
+     * PK from the projected PK columns, and exclude the row being written
+     * (`newSourcePk`). Returns the conflicting source PK(s) — the caller resolves
+     * IGNORE/ABORT/REPLACE against its own source storage (recovering the live
+     * source row and validating the candidate against it, since the backing entry
+     * for an internally-deleted/updated source row can lag within a statement).
+     *
+     * Reads-own-writes: the scan resolves to the backing table's coordinated
+     * connection (the same one {@link maintainRowTime} writes), so the backing
+     * reflects all prior rows of the statement. The backing is hosted by whatever
+     * backing-host-capable module the MV declared (`memory` by default, the store
+     * module under `using store`), independent of the source module — the host's
+     * `scanEffective` abstracts the storage.
+     *
+     * The conflict check is a **backing-PK prefix scan** keyed on `newRow`'s UC
+     * values — O(log n + matches) rather than the former O(n) full backing scan.
+     * Soundness rests on the covering-index shape: the body's `order by` columns are
+     * a permutation of the UC columns ({@link buildMaintenancePlan} eligibility +
+     * the coverage prover), and they seed the leading backing-PK columns
+     * (`computeBackingPrimaryKey`), so the leading `k = uc.columns.length` backing-PK
+     * columns are exactly the UC columns. {@link tryBuildCoveringPrefix} builds the
+     * equality prefix in backing-PK column order; the scan seeks to it and
+     * early-terminates when the leading columns stop matching. It falls back to a
+     * full scan whenever the fast-path gate fails (non-BINARY collation, or a
+     * leading-prefix shape that does not lead with exactly the UC columns) — the
+     * full scan re-compares with the source collation, so the fallback is
+     * collation-correct. Either way the result is only a *candidate* set: the caller
+     * validates each against the live source row.
+     */
+    lookupCoveringConflicts(mv: MaintainedTableSchema, uc: UniqueConstraintSchema, newRow: Row, newSourcePk: readonly SqlValue[]): Promise<Array<{
+        pk: SqlValue[];
+        row?: Row;
+    }>>;
+    /**
+     * Build the backing-PK equality prefix for a covering-conflict scan, or
+     * `undefined` to fall back to the full backing scan.
+     *
+     * The covering-index shape guarantees the body's `order by` columns are a
+     * permutation of the UC columns and that they seed the leading backing-PK columns
+     * (`computeBackingPrimaryKey`). So the leading `k = uc.columns.length` backing-PK
+     * columns are exactly the UC columns (as a set, possibly reordered by `order by`).
+     * The returned prefix is keyed in **backing-PK column order** (not `uc.columns`
+     * order), so a permuting `order by` still seeks to the right block:
+     * `prefix[i] = newRow[ sourceCol(backingPkDefinition[i]) ]`.
+     *
+     * Returns `undefined` (full-scan fallback) when any holds:
+     *  - fewer than `k` backing-PK columns, or a leading column is not a passthrough
+     *    of a source column (defensive — the covering shape guarantees passthrough);
+     *  - the leading `k` backing-PK columns do not map to **exactly** the UC
+     *    source-column set (defensive guard against a non-UC-leading structure);
+     *  - any leading backing-PK column, or its source UC column, has a **non-BINARY**
+     *    collation. This is a *soundness* gate, not a perf choice: the prefix seek's
+     *    early-termination compares with plain `compareSqlValues` (binary), while the
+     *    backing btree orders the PK by its declared collation and the UNIQUE
+     *    constraint conflicts by the source collation. Under a non-binary collation
+     *    the binary early-termination could `break` before a collated-equal /
+     *    binary-different conflict, missing it. The full-scan fallback re-compares
+     *    with the source collation, so it stays collation-correct.
+     *
+     * DESC-leading prefixes are admitted: equality on a column makes its order
+     * direction irrelevant to *grouping* (the binary-equal rows stay contiguous), and
+     * `scanLayer`'s `equalityPrefix` seek + ascending walk lands at the group start
+     * for either direction (verified by the `order by … desc` enforcement test).
+     */
+    private tryBuildCoveringPrefix;
+}
+export {};
+//# sourceMappingURL=database-materialized-views.d.ts.map