@quereus/quereus 3.2.1 → 4.0.0

package/dist/src/planner/analysis/query-rewrite-matcher.js

@@ -0,0 +1,1081 @@
+/**
+ * Query-rewrite matcher — the read-side dual of the coverage prover. It
+ * recognizes when an *arbitrary* scan-projection-filter query fragment (one that
+ * never names a materialized view) is **answered from** a covering MV, so the
+ * optimizer can scan the MV's backing table with a bounded residual instead of
+ * recomputing the body against the base tables.
+ *
+ * Distinct from `coverage-prover.ts` (which proves a *base-table UNIQUE
+ * constraint* is covered, on the write/enforcement path) but sharing its
+ * entailment vocabulary: `recognizeConjunctiveClauses` / `guardClausesEntail`
+ * (`partial-unique-extraction.ts`). The question answered here is **output-relation
+ * subsumption**: does the MV's stored output relation contain a superset (re-
+ * coverable via a bounded residual) of the rows the fragment produces, keyed so
+ * the residual recovers exactly the fragment's output?
+ *
+ * Soundness contract (mirrors the coverage prover exactly): **a false NotMatch
+ * only forgoes a speedup; a false Match returns wrong rows.** Every check forgoes
+ * the rewrite on doubt. The pre-existing recompute-over-base path is correct by
+ * construction; the rule only ever replaces it with a provably row-equivalent
+ * plan, so the rewrite is non-regressing.
+ *
+ * This phase delivers the **projection + filter subsumption** shape only.
+ * Aggregate rollup (`mv-query-rewrite-aggregate-rollup`) and join subsumption
+ * (`mv-query-rewrite-join-subsumption`) are pure additions to this matcher.
+ *
+ * ## Where the predicates come from (the pristine-fragment requirement)
+ *
+ * The fragment's WHERE is read from the live plan's `FilterNode` predicate (its
+ * `.expression` AST), and the MV's WHERE from `mv.derivation.selectAst.where`. Reading the
+ * fragment WHERE from the plan is only sound while the predicate is still an
+ * explicit `FilterNode` above the table access — *before* predicate-pushdown
+ * absorbs it into a range-bounded scan (where the matcher could no longer see it
+ * and would falsely treat the fragment as unfiltered). The rule that drives this
+ * matcher therefore fires in the **Structural rewrite pass, before grow-retrieve /
+ * predicate-pushdown**, where the fragment is the pristine
+ * `Project(Filter?(Retrieve(TableReference)))`. The shape walk additionally
+ * rejects any range-bounded physical scan (`SeqScan`/`IndexScan` with
+ * `rangeBoundedOn`, or an `IndexSeek`/`TableSeek`) as `'shape'` — defense in depth
+ * should an absorbed predicate ever reach the walk by another path.
+ *
+ * ## Why `.expression` recognition is sound under constant folding
+ *
+ * A scalar plan node retains its originating AST in `.expression`. Constant
+ * folding (which runs before the Structural pass) may make the *plan* more
+ * specific than its `.expression` (e.g. folding `1+1` → `2` while `.expression`
+ * still reads `amt > 1+1`). Such a divergence only ever makes a clause
+ * *unrecognized* (`literalValue` of a non-literal AST returns undefined), which is
+ * a conservative NotMatch — it never fabricates a recognized clause weaker than
+ * what the plan computes, so it cannot produce a false Match.
+ */
+import { isRelationalNode } from '../nodes/plan-node.js';
+import { ProjectNode } from '../nodes/project-node.js';
+import { FilterNode } from '../nodes/filter.js';
+import { RetrieveNode } from '../nodes/retrieve-node.js';
+import { AliasNode } from '../nodes/alias-node.js';
+import { TableReferenceNode, ColumnReferenceNode } from '../nodes/reference.js';
+import { SeqScanNode, IndexScanNode } from '../nodes/table-access-nodes.js';
+import { BinaryOpNode } from '../nodes/scalar.js';
+import { AggregateNode } from '../nodes/aggregate-node.js';
+import { AggregateFunctionCallNode } from '../nodes/aggregate-function.js';
+import { JoinNode } from '../nodes/join-node.js';
+import { CapabilityDetectors } from '../framework/characteristics.js';
+import { recognizeConjunctiveClauses, guardClausesEntail } from './partial-unique-extraction.js';
+import { proveOneToOneJoin, pureJoinEquiAttrPairs } from './coverage-prover.js';
+import { containsNonDeterministicCall } from './check-extraction.js';
+function fail(reason) {
+    return { match: undefined, reason };
+}
+/**
+ * Recognize a query fragment rooted at a `ProjectNode` as a single-source
+ * scan-project-filter chain. Walks `Project → Filter? → {Retrieve|Alias|full
+ * SeqScan/IndexScan}* → TableReference`. Any other node (Sort/Limit/Distinct/
+ * Aggregate/Join/SetOp, or a row-reducing seek / range-bounded scan) ⇒ `'shape'`.
+ */
+export function analyzeQueryFragment(root) {
+    if (!(root instanceof ProjectNode))
+        return { ok: false, reason: 'shape' };
+    // Descend the source chain, collecting WHERE conjuncts, down to the base table.
+    const walk = walkScanFilterChain(root.source);
+    if (!walk)
+        return { ok: false, reason: 'shape' };
+    const { tableRef, conjuncts } = walk;
+    // Each output column must be a bare column reference into the base table; a
+    // computed output is unrecoverable from the backing in v1 (missing-column).
+    const outputs = root.projections.map((proj, i) => ({
+        attrId: root.getAttributes()[i].id,
+        baseCol: proj.node instanceof ColumnReferenceNode ? proj.node.columnIndex : undefined,
+    }));
+    return {
+        ok: true,
+        shape: { project: root, tableRef, baseTable: tableRef.tableSchema, outputs, conjuncts },
+    };
+}
+/**
+ * Walk a single-source scan-project-filter source chain `Filter? → {Retrieve|Alias|
+ * full SeqScan/IndexScan}* → TableReference`, collecting top-level AND-split WHERE
+ * conjuncts (plan-node level). Returns the leaf `TableReferenceNode` and conjuncts,
+ * or `undefined` for any other node (a row-reducing seek / range-bounded scan,
+ * Sort/Limit/Distinct/Aggregate/Join/SetOp). Shared by the projection-filter and
+ * aggregate arms so the recognized source shape is identical.
+ */
+function walkScanFilterChain(start) {
+    const conjuncts = [];
+    let node = start;
+    let tableRef;
+    while (node) {
+        if (node instanceof TableReferenceNode) {
+            tableRef = node;
+            break;
+        }
+        if (node instanceof FilterNode) {
+            splitConjuncts(node.predicate, conjuncts);
+            node = node.source;
+            continue;
+        }
+        if (node instanceof RetrieveNode || node instanceof AliasNode) {
+            node = singleRelation(node);
+            if (!node)
+                return undefined;
+            continue;
+        }
+        // A full (non-range-bounded) physical scan is a row-preserving pass-through;
+        // a range-bounded scan has absorbed a predicate we can no longer see (sound
+        // only because the rule fires before access selection — this is defensive).
+        if (node instanceof SeqScanNode || node instanceof IndexScanNode) {
+            if (node.rangeBoundedOn)
+                return undefined;
+            node = node.source;
+            continue;
+        }
+        return undefined;
+    }
+    if (!tableRef)
+        return undefined;
+    return { tableRef, conjuncts };
+}
+/**
+ * Decide whether `mv` (backed by `backing`) answers the fragment `shape`. See the
+ * module doc for the soundness contract. `isDeterministic` probes the function
+ * registry for the determinism gate (a registered MV is already deterministic by
+ * construction — the create gate rejects non-deterministic bodies — so this is
+ * defense in depth).
+ */
+export function matchFragmentToMv(shape, mv, backing, isDeterministic) {
+    const baseTable = shape.baseTable;
+    // ---- Candidate gates (a false-positive here only forgoes a speedup). ----
+    // Stale: the backing is an unmaintained snapshot — never read it.
+    if (mv.derivation.stale === true)
+        return fail('no-candidate');
+    // Registered + has a live backing table.
+    if (!backing)
+        return fail('no-candidate');
+    // Deterministic body: a random()/now()/volatile-UDF body cannot substitute for
+    // live recomputation. Reuses the function-registry determinism metadata.
+    if (mvBodyHasNonDeterminism(mv.derivation.selectAst, isDeterministic))
+        return fail('no-candidate');
+    // Source-schema sanity: the MV must read exactly the one base table the
+    // fragment reads (single-source v1). `sourceTables` dedups, so a self-join
+    // collapses to one entry — the AST single-`table` FROM check below rejects it.
+    const qualified = `${baseTable.schemaName}.${baseTable.name}`.toLowerCase();
+    if (mv.derivation.sourceTables.length !== 1 || mv.derivation.sourceTables[0] !== qualified) {
+        return fail('source-mismatch');
+    }
+    // ---- MV body shape (AST): single-source projection + optional filter. ----
+    if (mv.derivation.selectAst.type !== 'select')
+        return fail('shape');
+    const sel = mv.derivation.selectAst;
+    if ((sel.groupBy && sel.groupBy.length > 0) || sel.having || sel.distinct
+        || sel.limit !== undefined || sel.offset !== undefined
+        || sel.union || sel.compound) {
+        return fail('shape');
+    }
+    if (!sel.from || sel.from.length !== 1 || sel.from[0].type !== 'table')
+        return fail('shape');
+    // ---- MV projection → base-column mapping (which backing column holds which
+    //      base column). A computed select item leaves that backing column unmapped
+    //      (it cannot answer a passthrough need). ----
+    const baseColOfBackingCol = mvProjectionBaseCols(sel.columns, baseTable);
+    if (!baseColOfBackingCol)
+        return fail('shape');
+    const backingColOfBaseCol = new Map();
+    baseColOfBackingCol.forEach((baseCol, backingCol) => {
+        if (baseCol !== undefined && !backingColOfBaseCol.has(baseCol)) {
+            backingColOfBaseCol.set(baseCol, backingCol);
+        }
+    });
+    // ---- Predicate entailment (containment): the fragment's row set must be a
+    //      subset of the MV's, i.e. the MV's WHERE `P_mv` is entailed by the
+    //      fragment's WHERE `P_q` (every MV-required clause is implied by the
+    //      query). The residual is the conjunction of `P_q` clauses not already
+    //      entailed by `P_mv`. ----
+    const mvClauses = sel.where ? recognizeConjunctiveClauses(sel.where, baseTable) : [];
+    if (mvClauses === undefined)
+        return fail('predicate-not-entailed');
+    const queryClauses = [];
+    const residualConjuncts = [];
+    const residualClauses = [];
+    for (const conjunct of shape.conjuncts) {
+        const expr = conjunctExpression(conjunct);
+        const clauses = expr ? recognizeConjunctiveClauses(expr, baseTable) : undefined;
+        if (!clauses)
+            return fail('predicate-not-entailed');
+        queryClauses.push(...clauses);
+        // A conjunct already entailed by `P_mv` holds for every backing row, so it
+        // is dropped from the residual; the rest become the residual filter.
+        if (!guardClausesEntail(mvClauses, clauses)) {
+            residualConjuncts.push(conjunct);
+            residualClauses.push(...clauses);
+        }
+    }
+    if (!guardClausesEntail(queryClauses, mvClauses))
+        return fail('predicate-not-entailed');
+    // ---- Projection coverage: every fragment output column must be a base column
+    //      the MV projects. ----
+    const outputColumnMap = [];
+    for (const out of shape.outputs) {
+        if (out.baseCol === undefined)
+            return fail('missing-column');
+        const backingCol = backingColOfBaseCol.get(out.baseCol);
+        if (backingCol === undefined)
+            return fail('missing-column');
+        outputColumnMap.push({ attrId: out.attrId, backingCol });
+    }
+    // ---- Residual coverage: every base column the residual references must also be
+    //      a backing column (so the residual filter can be applied on the scan). ----
+    for (const clause of residualClauses) {
+        for (const col of clauseColumns(clause)) {
+            if (!backingColOfBaseCol.has(col))
+                return fail('missing-column');
+        }
+    }
+    return {
+        match: {
+            mv,
+            backing,
+            residualClauses,
+            residualConjuncts,
+            outputColumnMap,
+            backingColOfBaseCol,
+        },
+    };
+}
+/**
+ * Convenience entry point (used by the unit tests): analyze `root` as a fragment
+ * and, on success, match it against `mv`. Returns the fragment-analysis failure
+ * reason when `root` is not a recognizable scan-project-filter chain.
+ */
+export function matchMaterializedViewRewrite(root, mv, backing, isDeterministic) {
+    const frag = analyzeQueryFragment(root);
+    if (!frag.ok)
+        return fail(frag.reason);
+    return matchFragmentToMv(frag.shape, mv, backing, isDeterministic);
+}
+/**
+ * Recognize a query fragment rooted at a logical {@link AggregateNode} (the shape
+ * the optimizer presents in the Structural pass, before physical aggregate
+ * selection) as a single-source aggregate over a scan-filter chain. Requires
+ * **bare-column** GROUP BY expressions and aggregate arguments — a computed group
+ * key or aggregate argument (`group by d+1`, `sum(amt*2)`, `group_concat(x, ',')`)
+ * is unrecoverable from a stored MV column in v1 ⇒ `aggregate-shape`. Mirrors the
+ * row-time aggregate eligibility gate, which likewise requires bare group columns.
+ */
+export function analyzeAggregateFragment(root) {
+    if (!(root instanceof AggregateNode))
+        return { ok: false, reason: 'aggregate-shape' };
+    const walk = walkScanFilterChain(root.source);
+    if (!walk)
+        return { ok: false, reason: 'aggregate-shape' };
+    const { tableRef, conjuncts } = walk;
+    const attrs = root.getAttributes();
+    const groupCount = root.groupBy.length;
+    // GROUP BY key: every expression must be a bare column reference into the base table.
+    const groupBaseCols = [];
+    for (const gb of root.groupBy) {
+        if (!(gb instanceof ColumnReferenceNode))
+            return { ok: false, reason: 'aggregate-shape' };
+        groupBaseCols.push(gb.columnIndex);
+    }
+    // Aggregates: each must be an aggregate function over `count(*)` (no arg) or a
+    // single bare base column.
+    const aggregates = [];
+    for (let i = 0; i < root.aggregates.length; i++) {
+        const expr = root.aggregates[i].expression;
+        if (!(expr instanceof AggregateFunctionCallNode))
+            return { ok: false, reason: 'aggregate-shape' };
+        let argBaseCol;
+        if (expr.args.length === 0) {
+            argBaseCol = undefined; // count(*)
+        }
+        else if (expr.args.length === 1 && expr.args[0] instanceof ColumnReferenceNode) {
+            argBaseCol = expr.args[0].columnIndex;
+        }
+        else {
+            return { ok: false, reason: 'aggregate-shape' }; // computed / multi-arg argument
+        }
+        aggregates.push({
+            funcName: expr.functionName.toLowerCase(),
+            argBaseCol,
+            isDistinct: expr.isDistinct,
+            outAttr: attrs[groupCount + i],
+        });
+    }
+    return {
+        ok: true,
+        shape: {
+            aggregateNode: root,
+            tableRef,
+            baseTable: tableRef.tableSchema,
+            groupBaseCols,
+            groupOutAttrs: attrs.slice(0, groupCount),
+            aggregates,
+            conjuncts,
+        },
+    };
+}
+/**
+ * Decide whether the grouped MV `mv` (backed by `backing`) answers the aggregate
+ * fragment `shape`. See the arm doc above for the two sub-cases and the soundness
+ * contract; every check forgoes on doubt (a false NotMatch only forgoes a speedup).
+ */
+export function matchAggregateFragmentToMv(shape, mv, backing, isDeterministic) {
+    const baseTable = shape.baseTable;
+    // ---- Candidate gates (a false-positive here only forgoes a speedup). ----
+    if (mv.derivation.stale === true)
+        return fail('no-candidate');
+    if (!backing)
+        return fail('no-candidate');
+    if (mvBodyHasNonDeterminism(mv.derivation.selectAst, isDeterministic))
+        return fail('no-candidate');
+    const qualified = `${baseTable.schemaName}.${baseTable.name}`.toLowerCase();
+    if (mv.derivation.sourceTables.length !== 1 || mv.derivation.sourceTables[0] !== qualified) {
+        return fail('source-mismatch');
+    }
+    // ---- MV body shape: a single-source grouped aggregate, no HAVING/DISTINCT/cap. ----
+    if (mv.derivation.selectAst.type !== 'select')
+        return fail('aggregate-shape');
+    const sel = mv.derivation.selectAst;
+    if (!sel.groupBy || sel.groupBy.length === 0)
+        return fail('aggregate-shape'); // not a grouped MV
+    if (sel.having || sel.distinct || sel.limit !== undefined || sel.offset !== undefined
+        || sel.union || sel.compound) {
+        return fail('aggregate-shape');
+    }
+    if (!sel.from || sel.from.length !== 1 || sel.from[0].type !== 'table')
+        return fail('aggregate-shape');
+    // ---- MV group key (base columns) — every GROUP BY expr must be a bare column. ----
+    const mvGroupBaseCols = [];
+    for (const gb of sel.groupBy) {
+        const col = baseColumnOfExpr(gb, baseTable);
+        if (col === undefined)
+            return fail('aggregate-shape'); // computed MV group key
+        mvGroupBaseCols.push(col);
+    }
+    const mvGroupSet = new Set(mvGroupBaseCols);
+    // ---- MV stored columns: group-key passthroughs + stored aggregates. ----
+    const stored = analyzeMvStoredColumns(sel.columns, baseTable);
+    if (!stored)
+        return fail('aggregate-shape');
+    // Every MV group-key column must be stored as a backing column (so the backing is
+    // addressable by the group key — needed for re-grouping and residual filtering).
+    for (const gc of mvGroupBaseCols) {
+        if (!stored.groupBackingOfBaseCol.has(gc))
+            return fail('missing-column');
+    }
+    // ---- One-row-per-MV-group witness: the backing's primary key must be exactly the
+    //      MV group key (as backing columns). This is the schema-level form of
+    //      `coverage-prover.ts`'s `proveEffectiveKeyUnique` — it certifies the backing
+    //      is a *set* keyed by the group columns, so the exact-key direct scan returns
+    //      one row per query group and the rollup re-aggregates a set (not a bag). The
+    //      backing of a grouped MV is maintained keyed on its group columns, so this
+    //      holds by construction; the check forgoes if a future shape ever diverges. ----
+    if (!backingPkIsGroupKey(backing, mvGroupBaseCols, stored.groupBackingOfBaseCol)) {
+        return fail('aggregate-shape');
+    }
+    // ---- Group-key alignment: query key must be a subset of the MV key. ----
+    const queryGroupSet = new Set(shape.groupBaseCols);
+    for (const gc of queryGroupSet) {
+        if (!mvGroupSet.has(gc))
+            return fail('group-key-mismatch');
+    }
+    const exact = queryGroupSet.size === mvGroupSet.size;
+    // Query group-key columns must be stored (to re-group / output them).
+    const groupKeyBackingCols = [];
+    for (const gc of shape.groupBaseCols) {
+        const bc = stored.groupBackingOfBaseCol.get(gc);
+        if (bc === undefined)
+            return fail('missing-column');
+        groupKeyBackingCols.push(bc);
+    }
+    // `backingColOfBaseCol` exposes only the stored group-key columns. The residual
+    // coverage check (below) then forgoes any residual conjunct on a non-group column
+    // — exactly the columns the MV has already aggregated away.
+    const backingColOfBaseCol = new Map(stored.groupBackingOfBaseCol);
+    // ---- Aggregate decomposition: a recipe per fragment aggregate. ----
+    const recipes = [];
+    const outputColumnMap = [];
+    for (const qa of shape.aggregates) {
+        const recipe = exact
+            ? recipeForExact(qa, stored.storedAggs)
+            : recipeForRollup(qa, stored.storedAggs, baseTable);
+        if (!recipe)
+            return fail('aggregate-not-decomposable');
+        recipes.push(recipe);
+        if (exact)
+            outputColumnMap.push({ attrId: qa.outAttr.id, backingCol: recipe.backingCols[0] });
+    }
+    // ---- Predicate alignment (identical containment logic to the foundation), with
+    //      the aggregate-specific gate that every residual conjunct references only
+    //      MV group-key columns (so it partitions whole MV groups and commutes with
+    //      the rollup). A residual on a non-group column resolves to a base column
+    //      absent from `backingColOfBaseCol` ⇒ `missing-column`. ----
+    const mvClauses = sel.where ? recognizeConjunctiveClauses(sel.where, baseTable) : [];
+    if (mvClauses === undefined)
+        return fail('predicate-not-entailed');
+    const queryClauses = [];
+    const residualConjuncts = [];
+    const residualClauses = [];
+    for (const conjunct of shape.conjuncts) {
+        const expr = conjunctExpression(conjunct);
+        const clauses = expr ? recognizeConjunctiveClauses(expr, baseTable) : undefined;
+        if (!clauses)
+            return fail('predicate-not-entailed');
+        queryClauses.push(...clauses);
+        if (!guardClausesEntail(mvClauses, clauses)) {
+            residualConjuncts.push(conjunct);
+            residualClauses.push(...clauses);
+        }
+    }
+    if (!guardClausesEntail(queryClauses, mvClauses))
+        return fail('predicate-not-entailed');
+    for (const clause of residualClauses) {
+        for (const col of clauseColumns(clause)) {
+            if (!backingColOfBaseCol.has(col))
+                return fail('missing-column');
+        }
+    }
+    // Group-key reorder guard. When the query WHERE constant-pins (`g = 1`, `g is
+    // null`) or equates (`g1 = g2`) a group-key column AND there are ≥2 group keys,
+    // the base's `rule-groupby-fd-simplification` drops the functionally-determined
+    // group column and re-emits it as a picker `min` at a *shifted* output position,
+    // changing the result's column ORDER. The rewrite preserves the pristine column
+    // order, so the two would diverge — forgo to remain a faithful drop-in. (A single
+    // group key is never dropped — the rule keeps ≥1 — and range/IN residuals create
+    // no determining FD, so both stay eligible. Checks the full query WHERE, not just
+    // the residual: a pin entailed by the MV still drives the base's simplification.)
+    if (queryGroupSet.size >= 2 && queryClauses.some(c => clausePinsOrEquatesGroupCol(c, queryGroupSet))) {
+        return fail('group-key-pinned');
+    }
+    // A rollup with a residual is sound: the residual coverage check above admits only
+    // conjuncts over MV group-key columns, which partition whole MV groups — so the
+    // residual `Filter` on the backing scan keeps or drops each backing group entire,
+    // and the re-aggregate over the survivors commutes with it (filtering whole groups
+    // pre- vs post-rollup is identical). The rule builds that residual `Filter` on the
+    // backing scan before the re-aggregate (the same `buildBackingSource` the exact-key
+    // and projection-filter arms use). This shape — `group by k` re-aggregating a
+    // composite-PK backing with a `WHERE` on a non-grouped PK column — previously
+    // tripped a base streaming-aggregate filter-drop bug, which is now fixed
+    // (`streaming-aggregate-stale-group-context-shadows-child-filter`); the equivalence
+    // harness covers the rollup+residual shapes as the soundness backstop.
+    // ---- Exact-key: assemble the output column map for the group-key passthroughs so
+    //      the foundation's `buildReplacement` can re-emit the whole row directly. ----
+    if (exact) {
+        const groupOut = [];
+        shape.groupBaseCols.forEach((_gc, i) => {
+            groupOut.push({ attrId: shape.groupOutAttrs[i].id, backingCol: groupKeyBackingCols[i] });
+        });
+        // outputColumnMap currently holds the aggregate outputs; prepend the group outputs
+        // so the order matches the fragment's [group…, aggregate…] output order.
+        outputColumnMap.unshift(...groupOut);
+    }
+    const rollup = {
+        exact,
+        groupKeyBackingCols,
+        groupOutAttrs: shape.groupOutAttrs,
+        aggregates: recipes,
+    };
+    return {
+        match: {
+            mv,
+            backing,
+            residualClauses,
+            residualConjuncts,
+            outputColumnMap,
+            backingColOfBaseCol,
+            rollup,
+        },
+    };
+}
+/**
+ * Convenience entry point (used by the unit tests): analyze `root` as an aggregate
+ * fragment and, on success, match it against `mv`.
+ */
+export function matchAggregateMaterializedViewRewrite(root, mv, backing, isDeterministic) {
+    const frag = analyzeAggregateFragment(root);
+    if (!frag.ok)
+        return fail(frag.reason);
+    return matchAggregateFragmentToMv(frag.shape, mv, backing, isDeterministic);
+}
+/**
+ * Recognize a query fragment rooted at a `ProjectNode` whose source descends —
+ * through an optional `Filter` (post-join WHERE) and single-source pass-throughs —
+ * into a single binary {@link JoinNode} over exactly two distinct base tables. Any
+ * other shape (no join, a multi-way join, a non-passthrough node, a row-reducing
+ * scan) ⇒ `'shape'`. The fragment is pristine (the rule fires before
+ * predicate-pushdown / grow-retrieve), so the join's `ON` condition and the WHERE
+ * `Filter` are still explicit.
+ */
+export function analyzeJoinQueryFragment(root) {
+    if (!(root instanceof ProjectNode))
+        return { ok: false, reason: 'shape' };
+    const walk = walkToFragmentJoin(root.source);
+    if (!walk)
+        return { ok: false, reason: 'shape' };
+    const { joinNode, conjuncts } = walk;
+    // Exactly two distinct base tables under the join (a self-join or a 3-way join
+    // is out of scope — the latter is partial-join matching, deferred).
+    const tableRefs = collectBaseTableRefs(joinNode);
+    if (tableRefs.length !== 2)
+        return { ok: false, reason: 'shape' };
+    if (qualifiedOf(tableRefs[0].tableSchema) === qualifiedOf(tableRefs[1].tableSchema)) {
+        return { ok: false, reason: 'shape' }; // self-join
+    }
+    return { ok: true, shape: { project: root, joinNode, tableRefs: [tableRefs[0], tableRefs[1]], conjuncts } };
+}
+/**
+ * Walk a fragment's `Project.source` down to its single binary join, collecting the
+ * post-join WHERE conjuncts. Passes through `Filter` (splitting its predicate),
+ * `Retrieve`, and `Alias`; returns `undefined` for any other node (so a Distinct /
+ * Aggregate / second join above the first ⇒ NotMatch).
+ */
+function walkToFragmentJoin(start) {
+    const conjuncts = [];
+    let node = start;
+    while (node) {
+        if (node instanceof JoinNode)
+            return { joinNode: node, conjuncts };
+        if (node instanceof FilterNode) {
+            splitConjuncts(node.predicate, conjuncts);
+            node = node.source;
+            continue;
+        }
+        if (node instanceof RetrieveNode || node instanceof AliasNode) {
+            node = singleRelation(node);
+            if (!node)
+                return undefined;
+            continue;
+        }
+        return undefined;
+    }
+    return undefined;
+}
+/**
+ * Decide whether the 1:1-join MV `mv` (optimized body `mvBodyRoot`, backed by
+ * `backing`) answers the join fragment `shape`. See the arm doc above for the
+ * soundness contract; every check forgoes on doubt.
+ *
+ * `mvBodyRoot` is the MV body's optimized relational root (the rule plans it
+ * suppressed and caches it). When the rule could not plan it, pass `undefined` ⇒
+ * `no-candidate`.
+ */
+export function matchJoinFragmentToMv(shape, mv, mvBodyRoot, backing, isDeterministic) {
+    // ---- Candidate gates (a false-positive here only forgoes a speedup). ----
+    if (mv.derivation.stale === true)
+        return fail('no-candidate');
+    if (!backing)
+        return fail('no-candidate');
+    if (!mvBodyRoot)
+        return fail('no-candidate'); // body did not plan
+    if (mvBodyHasNonDeterminism(mv.derivation.selectAst, isDeterministic))
+        return fail('no-candidate');
+    // ---- Backing alignment: the stored-column map keys each backing column by the
+    //      MV body's output *position*, which is only sound while the backing columns
+    //      correspond positionally to the body output (the invariant established when
+    //      the backing is built from the body). A source `alter` can desynchronize
+    //      them — `refresh` does not reorder the backing to match a re-planned
+    //      `select *` body, which interleaves the new column — so a stale mapping would
+    //      read the wrong backing column or run off its end. Verify positional name
+    //      alignment up front and forgo (→ correct base recompute) on any mismatch. ----
+    if (!backingAlignsWithBody(mvBodyRoot, backing))
+        return fail('no-candidate');
+    // ---- Source-set match: the MV must read exactly the fragment's two tables. ----
+    const qualA = qualifiedOf(shape.tableRefs[0].tableSchema);
+    const qualB = qualifiedOf(shape.tableRefs[1].tableSchema);
+    const mvSources = new Set(mv.derivation.sourceTables);
+    if (mvSources.size !== 2 || !mvSources.has(qualA) || !mvSources.has(qualB)) {
+        return fail('source-mismatch');
+    }
+    // ---- Join equivalence: find a (T, lookup) assignment over which BOTH the
+    //      fragment and the MV body are provably 1:1, with the same inner/cross join
+    //      type and the same equi-pairs. A mismatch on any ⇒ NotMatch (shape). ----
+    const assignment = findJoinAssignment(shape, mvBodyRoot);
+    if (!assignment)
+        return fail('shape');
+    const { drivingRef, lookupRef, mvDrivingRef, mvLookupRef } = assignment;
+    // ---- Stored-column map: each MV backing column (by output position) → the
+    //      (side, base column) it passes through. A computed MV column is unmapped. ----
+    const stored = mvStoredJoinColumns(mvBodyRoot, mvDrivingRef, mvLookupRef);
+    // Fragment source attribute id → (side, base column).
+    const fragDriving = attrToBaseCol(drivingRef);
+    const fragLookup = attrToBaseCol(lookupRef);
+    // ---- Projection coverage: every fragment output column must be a bare
+    //      passthrough of a `T`/`P` column the MV stores. ----
+    const outputColumnMap = [];
+    const outAttrs = shape.project.getAttributes();
+    const projections = shape.project.projections;
+    for (let i = 0; i < projections.length; i++) {
+        const proj = projections[i];
+        if (!(proj.node instanceof ColumnReferenceNode))
+            return fail('missing-column'); // computed output
+        const backingCol = backingColForAttr(proj.node.attributeId, fragDriving, fragLookup, stored);
+        if (backingCol === undefined)
+            return fail('missing-column');
+        outputColumnMap.push({ attrId: outAttrs[i].id, backingCol });
+    }
+    // ---- Residual: the MV body has no WHERE (the row-time gate forbids it), so the
+    //      whole fragment WHERE is residual. Every conjunct must be a subquery-free
+    //      predicate over stored `T`/`P` columns so it re-binds onto the backing. ----
+    const backingColOfSourceAttrId = storedSourceAttrIds(fragDriving, fragLookup, stored);
+    for (const conjunct of shape.conjuncts) {
+        if (conjunctHasSubquery(conjunct))
+            return fail('predicate-not-entailed');
+        for (const attrId of conjunctColumnAttrIds(conjunct)) {
+            if (!backingColOfSourceAttrId.has(attrId))
+                return fail('missing-column');
+        }
+    }
+    return {
+        match: {
+            mv,
+            backing,
+            residualClauses: [],
+            residualConjuncts: shape.conjuncts,
+            outputColumnMap,
+            backingColOfBaseCol: new Map(),
+            backingColOfSourceAttrId,
+            joinInfo: { drivingTable: drivingRef.tableSchema, lookupTable: lookupRef.tableSchema },
+        },
+    };
+}
+/**
+ * Convenience entry point (used by the unit tests): analyze `root` as a join
+ * fragment and, on success, match it against `mv` (whose optimized body root is
+ * `mvBodyRoot`).
+ */
+export function matchJoinMaterializedViewRewrite(root, mv, mvBodyRoot, backing, isDeterministic) {
+    const frag = analyzeJoinQueryFragment(root);
+    if (!frag.ok)
+        return fail(frag.reason);
+    return matchJoinFragmentToMv(frag.shape, mv, mvBodyRoot, backing, isDeterministic);
+}
+/**
+ * Find a (driving, lookup) assignment of the fragment's two tables over which the
+ * fragment join *and* the MV body join are both provably 1:1 (inner/cross),
+ * carrying the same equi-pairs in `(driving-col, lookup-col)` terms. Tries each
+ * table as the driver; returns the first that discharges every obligation, else
+ * `undefined` (⇒ a `shape` NotMatch). A 1:1 FK join determines the driver uniquely,
+ * so at most one assignment ever succeeds.
+ */
+function findJoinAssignment(shape, mvBodyRoot) {
+    const [a, b] = shape.tableRefs;
+    for (const [drivingRef, lookupRef] of [[a, b], [b, a]]) {
+        const driving = drivingRef.tableSchema;
+        // Both joins must be 1:1 over this driver, via an inner/cross top join.
+        const fragProof = proveOneToOneJoin(shape.joinNode, driving);
+        if (!fragProof.ok || !fragProof.topJoin || !isInnerOrCross(fragProof.topJoin))
+            continue;
+        const mvProof = proveOneToOneJoin(mvBodyRoot, driving);
+        if (!mvProof.ok || !mvProof.topJoin || !isInnerOrCross(mvProof.topJoin))
+            continue;
+        // Locate the MV body's matching table references (by qualified name).
+        const mvDrivingRef = findTableRef(mvBodyRoot, qualifiedOf(driving));
+        const mvLookupRef = findTableRef(mvBodyRoot, qualifiedOf(lookupRef.tableSchema));
+        if (!mvDrivingRef || !mvLookupRef)
+            continue;
+        // Same equi-pairs (as a set, in driving→lookup base-column terms).
+        const fragPairs = equiPairsByBaseCol(fragProof.topJoin, drivingRef, lookupRef);
+        const mvPairs = equiPairsByBaseCol(mvProof.topJoin, mvDrivingRef, mvLookupRef);
+        if (!fragPairs || !mvPairs || !sameStringSet(fragPairs, mvPairs))
+            continue;
+        return { drivingRef, lookupRef, mvDrivingRef, mvLookupRef };
+    }
+    return undefined;
+}
+/** True when `join` is an inner or cross join (an outer join is deferred — its
+ *  null-extended rows make the stored relation differ from an inner-join query). */
+function isInnerOrCross(join) {
+    if (!CapabilityDetectors.isJoin(join))
+        return false;
+    const t = join.getJoinType();
+    return t === 'inner' || t === 'cross';
+}
+/**
+ * The join's equi-pairs as a set of `"drivingCol:lookupCol"` base-column keys, or
+ * `undefined` when the join is not a pure equi-join or a pair does not connect the
+ * driving and lookup tables cleanly. Shared shape for fragment and MV comparison.
+ */
+function equiPairsByBaseCol(topJoin, drivingRef, lookupRef) {
+    const pairs = pureJoinEquiAttrPairs(topJoin);
+    if (!pairs || pairs.length === 0)
+        return undefined;
+    const dCol = attrToBaseCol(drivingRef);
+    const lCol = attrToBaseCol(lookupRef);
+    const out = new Set();
+    for (const p of pairs) {
+        let d = dCol.get(p.leftAttrId);
+        let l = lCol.get(p.rightAttrId);
+        if (d === undefined || l === undefined) {
+            d = dCol.get(p.rightAttrId);
+            l = lCol.get(p.leftAttrId);
+        }
+        if (d === undefined || l === undefined)
+            return undefined; // not a clean driving↔lookup pair
+        out.add(`${d}:${l}`);
+    }
+    return out;
+}
+function mvStoredJoinColumns(mvBodyRoot, mvDrivingRef, mvLookupRef) {
+    const dAttr = attrToBaseCol(mvDrivingRef);
+    const lAttr = attrToBaseCol(mvLookupRef);
+    const driving = new Map();
+    const lookup = new Map();
+    // A bare passthrough output column preserves its source attribute id, so the MV
+    // output attribute id resolves back to a driving/lookup base column (cf. the
+    // projection-coverage technique in `coverage-prover.ts`). A computed column gets
+    // a fresh id absent from both maps and is left unmapped.
+    mvBodyRoot.getAttributes().forEach((attr, backingCol) => {
+        const d = dAttr.get(attr.id);
+        if (d !== undefined) {
+            if (!driving.has(d))
+                driving.set(d, backingCol);
+            return;
+        }
+        const l = lAttr.get(attr.id);
+        if (l !== undefined && !lookup.has(l))
+            lookup.set(l, backingCol);
+    });
+    return { driving, lookup };
+}
+/** The backing column storing the fragment source attribute `attrId` (resolved to a
+ *  driving/lookup base column), or `undefined` when the MV does not store it. */
+function backingColForAttr(attrId, fragDriving, fragLookup, stored) {
+    const d = fragDriving.get(attrId);
+    if (d !== undefined)
+        return stored.driving.get(d);
+    const l = fragLookup.get(attrId);
+    if (l !== undefined)
+        return stored.lookup.get(l);
+    return undefined;
+}
+/** Fragment source attribute id → backing column, for every `T`/`P` column the MV
+ *  stores — the residual re-bind map (`backingColOfSourceAttrId`). */
+function storedSourceAttrIds(fragDriving, fragLookup, stored) {
+    const out = new Map();
+    fragDriving.forEach((baseCol, attrId) => {
+        const bc = stored.driving.get(baseCol);
+        if (bc !== undefined)
+            out.set(attrId, bc);
+    });
+    fragLookup.forEach((baseCol, attrId) => {
+        const bc = stored.lookup.get(baseCol);
+        if (bc !== undefined)
+            out.set(attrId, bc);
+    });
+    return out;
+}
+/** Stable attribute id → base column index for a table reference. */
+function attrToBaseCol(ref) {
+    const out = new Map();
+    ref.getAttributes().forEach((attr, i) => out.set(attr.id, i));
+    return out;
+}
+/** All `TableReferenceNode`s in `node`'s subtree (depth-first, left-to-right). */
+function collectBaseTableRefs(node) {
+    if (node instanceof TableReferenceNode)
+        return [node];
+    const out = [];
+    for (const rel of node.getRelations())
+        out.push(...collectBaseTableRefs(rel));
+    return out;
+}
+/** The first `TableReferenceNode` in `node`'s subtree over the qualified table, or
+ *  `undefined`. The fragment rejects self-joins upstream, so the first match is
+ *  unambiguous. */
+function findTableRef(node, qualified) {
+    if (node instanceof TableReferenceNode) {
+        return qualifiedOf(node.tableSchema) === qualified ? node : undefined;
+    }
+    for (const rel of node.getRelations()) {
+        const found = findTableRef(rel, qualified);
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+/** True iff `conjunct` embeds a relational subquery (an Exists/In/scalar-subquery
+ *  whose child is a relation). Such a predicate is not re-bindable onto a flat
+ *  backing scan, so the join arm forgoes it (matching the foundation's no-subquery
+ *  invariant that licenses `sideEffectMode: 'safe'`). */
+function conjunctHasSubquery(node) {
+    for (const child of node.getChildren()) {
+        if (isRelationalNode(child))
+            return true;
+        if (conjunctHasSubquery(child))
+            return true;
+    }
+    return false;
+}
+/** Every `ColumnReferenceNode` attribute id referenced (transitively) by a
+ *  subquery-free conjunct. */
+function conjunctColumnAttrIds(node) {
+    const out = [];
+    const visit = (n) => {
+        if (n instanceof ColumnReferenceNode)
+            out.push(n.attributeId);
+        for (const child of n.getChildren())
+            visit(child);
+    };
+    visit(node);
+    return out;
+}
+/**
+ * True iff the backing table's columns correspond positionally — same count, same
+ * names in order — to the MV body root's output attributes. This is the invariant
+ * the position-keyed stored-column map relies on (the backing is built column-for-
+ * column from the body output). A source `alter` followed by `refresh` can break it
+ * without marking the MV permanently unusable: the backing's column order and a
+ * re-planned `select *` body's output order diverge (a new source column appends to
+ * the backing but interleaves in the body). The join arm verifies the invariant
+ * here rather than trusting position, so a desynchronized MV forgoes the rewrite
+ * (the base recompute stays correct) instead of reading the wrong column.
+ */
+function backingAlignsWithBody(mvBodyRoot, backing) {
+    const attrs = mvBodyRoot.getAttributes();
+    if (attrs.length !== backing.columns.length)
+        return false;
+    for (let i = 0; i < attrs.length; i++) {
+        if (attrs[i].name.toLowerCase() !== backing.columns[i].name.toLowerCase())
+            return false;
+    }
+    return true;
+}
+/** `schema.table` lowercased — the canonical qualified key matching `sourceTables`. */
+function qualifiedOf(table) {
+    return `${table.schemaName}.${table.name}`.toLowerCase();
+}
+/** Set equality over two string sets. */
+function sameStringSet(a, b) {
+    if (a.size !== b.size)
+        return false;
+    for (const x of a)
+        if (!b.has(x))
+            return false;
+    return true;
+}
+/** Decomposable rollup aggregates that re-aggregate as plain `sum`/`min`/`max`. */
+const ROLLUP_SUM_LIKE = new Map([
+    ['sum', 'sum'], ['min', 'min'], ['max', 'max'],
+]);
+/**
+ * Exact-key recipe: the query aggregate must be *exactly* a stored MV aggregate
+ * (same function, same argument column, same DISTINCT flag). The stored value is
+ * the answer, so this admits any aggregate — including `count(distinct)` /
+ * `group_concat` — as a passthrough. Returns a `sum`-kind passthrough recipe whose
+ * `backingCols[0]` is the stored column (the kind is unused for exact-key, which the
+ * rule answers via `outputColumnMap`).
+ */
+function recipeForExact(qa, stored) {
+    const match = stored.find(sa => sa.funcName === qa.funcName && sa.argBaseCol === qa.argBaseCol && sa.isDistinct === qa.isDistinct);
+    if (!match)
+        return undefined;
+    return { outAttr: qa.outAttr, kind: 'sum', backingCols: [match.backingCol] };
+}
+/**
+ * Rollup recipe: reconstruct `qa` by re-aggregating the MV's stored partials. Only
+ * the decomposable allowlist is admitted; a DISTINCT aggregate never composes.
+ */
+function recipeForRollup(qa, stored, baseTable) {
+    if (qa.isDistinct)
+        return undefined; // count(distinct …) and friends never compose under rollup.
+    const sumLike = ROLLUP_SUM_LIKE.get(qa.funcName);
+    if (sumLike) {
+        // sum(x) ← sum(stored sum(x)); min/max(x) ← min/max(stored min/max(x)).
+        const col = findStored(stored, qa.funcName, qa.argBaseCol);
+        return col === undefined ? undefined : { outAttr: qa.outAttr, kind: sumLike, backingCols: [col] };
+    }
+    if (qa.funcName === 'count') {
+        // count(*) ← sum(stored count(*)); count(x) ← sum(stored count(x)). The 'count'
+        // kind adds the coalesce-to-0 the rule emits (count over zero rows is 0, not NULL).
+        const col = findStored(stored, 'count', qa.argBaseCol);
+        return col === undefined ? undefined : { outAttr: qa.outAttr, kind: 'count', backingCols: [col] };
+    }
+    if (qa.funcName === 'avg') {
+        // avg(x) ← sum(stored sum(x)) / sum(stored count). Requires both partials; the
+        // count must exclude the same NULLs `avg` does — a stored `count(x)` always
+        // qualifies, and a stored `count(*)` only when `x` is declared NOT NULL.
+        const sumCol = findStored(stored, 'sum', qa.argBaseCol);
+        if (sumCol === undefined)
+            return undefined;
+        let countCol = findStored(stored, 'count', qa.argBaseCol);
+        if (countCol === undefined && qa.argBaseCol !== undefined && baseTable.columns[qa.argBaseCol]?.notNull === true) {
+            countCol = findStored(stored, 'count', undefined); // count(*) is sound when x is NOT NULL.
+        }
+        if (countCol === undefined)
+            return undefined;
+        return { outAttr: qa.outAttr, kind: 'avg', backingCols: [sumCol, countCol] };
+    }
+    return undefined; // total / group_concat / unknown ⇒ not decomposable.
+}
+/** The backing column of a stored, non-distinct aggregate `f(argBaseCol)`, or undefined. */
+function findStored(stored, funcName, argBaseCol) {
+    const match = stored.find(sa => sa.funcName === funcName && sa.argBaseCol === argBaseCol && !sa.isDistinct);
+    return match?.backingCol;
+}
+/**
+ * Parse a grouped MV's select list into its group-key passthrough columns and its
+ * stored aggregate columns, by backing-column position. A bare column is a group
+ * key; an aggregate function call (`count(*)`, or `f(col)`) is a stored aggregate;
+ * a `*` or any other computed item is ignored (it answers no group key or aggregate).
+ * Returns undefined only for a `table.*` naming a non-base table (defensive).
+ */
+function analyzeMvStoredColumns(columns, baseTable) {
+    const groupBackingOfBaseCol = new Map();
+    const storedAggs = [];
+    for (let backingCol = 0; backingCol < columns.length; backingCol++) {
+        const col = columns[backingCol];
+        if (col.type === 'all') {
+            if (col.table && col.table.toLowerCase() !== baseTable.name.toLowerCase())
+                return undefined;
+            // A `*` in a grouped body would be an error at create time; ignore defensively.
+            continue;
+        }
+        const expr = col.expr;
+        if (expr.type === 'function') {
+            const fn = expr;
+            const argBaseCol = mvAggregateArgBaseCol(fn, baseTable);
+            if (argBaseCol === 'unrecognized')
+                continue; // computed/multi-arg ⇒ unusable
+            storedAggs.push({
+                funcName: fn.name.toLowerCase(),
+                argBaseCol,
+                isDistinct: fn.distinct === true,
+                backingCol,
+            });
+            continue;
+        }
+        const baseCol = baseColumnOfExpr(expr, baseTable);
+        if (baseCol !== undefined && !groupBackingOfBaseCol.has(baseCol)) {
+            groupBackingOfBaseCol.set(baseCol, backingCol);
+        }
+        // A computed non-aggregate select item is left unmapped (unusable).
+    }
+    return { groupBackingOfBaseCol, storedAggs };
+}
+/**
+ * The base-table column index of an MV aggregate's argument: `undefined` for
+ * `count(*)` (no argument), a base column index for a single bare-column argument,
+ * or `'unrecognized'` for a computed / multi-argument call (which no fragment
+ * aggregate — itself required to be bare — can match).
+ */
+function mvAggregateArgBaseCol(fn, baseTable) {
+    if (fn.args.length === 0)
+        return undefined;
+    if (fn.args.length === 1) {
+        const col = baseColumnOfExpr(fn.args[0], baseTable);
+        return col === undefined ? 'unrecognized' : col;
+    }
+    return 'unrecognized';
+}
+/**
+ * True iff the backing table's primary key is exactly the MV's group key (mapped to
+ * backing columns). The witness that the backing is one row per MV group.
+ */
+function backingPkIsGroupKey(backing, mvGroupBaseCols, groupBackingOfBaseCol) {
+    const pk = backing.primaryKeyDefinition;
+    if (pk.length !== mvGroupBaseCols.length)
+        return false;
+    const pkSet = new Set(pk.map(c => c.index));
+    if (pkSet.size !== pk.length)
+        return false;
+    for (const gc of mvGroupBaseCols) {
+        const bc = groupBackingOfBaseCol.get(gc);
+        if (bc === undefined || !pkSet.has(bc))
+            return false;
+    }
+    return true;
+}
+/** The sole relational child of a single-source pass-through, or undefined. */
+function singleRelation(node) {
+    const rels = node.getRelations();
+    return rels.length === 1 ? rels[0] : undefined;
+}
+/** Flatten a predicate into its top-level AND conjuncts (plan-node level). */
+function splitConjuncts(predicate, out) {
+    if (predicate instanceof BinaryOpNode && predicate.expression.operator === 'AND') {
+        splitConjuncts(predicate.left, out);
+        splitConjuncts(predicate.right, out);
+        return;
+    }
+    out.push(predicate);
+}
+/** The originating AST of a scalar plan node, or undefined when it has none. */
+function conjunctExpression(node) {
+    const expr = node.expression;
+    return expr && typeof expr === 'object' && 'type' in expr
+        ? expr
+        : undefined;
+}
+/**
+ * Map each MV backing column (by output position) to the base-table column it
+ * passes through, reading the MV's select list. A `*` expands to every base
+ * column in order; a bare column resolves by name; a computed item leaves that
+ * position `undefined` (unmapped). Returns undefined when a `table.*` form names a
+ * table other than the base (cannot happen for a single-source body, but rejected
+ * defensively).
+ */
+function mvProjectionBaseCols(columns, baseTable) {
+    const out = [];
+    for (const col of columns) {
+        if (col.type === 'all') {
+            if (col.table && col.table.toLowerCase() !== baseTable.name.toLowerCase())
+                return undefined;
+            for (let i = 0; i < baseTable.columns.length; i++)
+                out.push(i);
+            continue;
+        }
+        out.push(baseColumnOfExpr(col.expr, baseTable));
+    }
+    return out;
+}
+/** Resolve a bare column / identifier expression to a base-table column index. */
+function baseColumnOfExpr(expr, baseTable) {
+    if (expr.type === 'column') {
+        return baseTable.columnIndexMap.get(expr.name.toLowerCase());
+    }
+    if (expr.type === 'identifier') {
+        const id = expr;
+        if (id.schema)
+            return undefined;
+        return baseTable.columnIndexMap.get(id.name.toLowerCase());
+    }
+    return undefined;
+}
+/**
+ * True when `clause` constant-pins (`g = literal`, `g is null`) or equates
+ * (`g1 = g2`) a column in `groupSet` — the predicate shapes that give a group-key
+ * column a determining FD and so drive `rule-groupby-fd-simplification` to drop and
+ * reposition it. Range / IN (`or-of`) clauses create no such FD and return false.
+ */
+function clausePinsOrEquatesGroupCol(clause, groupSet) {
+    switch (clause.kind) {
+        case 'eq-literal': return groupSet.has(clause.column);
+        case 'is-null': return groupSet.has(clause.column);
+        case 'eq-column': return groupSet.has(clause.left) || groupSet.has(clause.right);
+        default: return false; // range / or-of: no constant-determining FD
+    }
+}
+/** The base-table column indices a recognized guard clause references. */
+function clauseColumns(clause) {
+    switch (clause.kind) {
+        case 'eq-literal': return [clause.column];
+        case 'eq-column': return [clause.left, clause.right];
+        case 'is-null': return [clause.column];
+        case 'range': return [clause.column];
+        case 'or-of': return clause.clauses.flatMap(clauseColumns);
+        default: return [];
+    }
+}
+/** True when the MV body's WHERE or any projection expression calls a
+ *  non-deterministic function (or embeds a subquery). */
+function mvBodyHasNonDeterminism(selectAst, isDeterministic) {
+    if (selectAst.type !== 'select')
+        return false;
+    if (selectAst.where && containsNonDeterministicCall(selectAst.where, isDeterministic))
+        return true;
+    for (const col of selectAst.columns) {
+        if (col.type === 'column' && containsNonDeterministicCall(col.expr, isDeterministic))
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=query-rewrite-matcher.js.map