@quereus/quereus 3.3.0 → 4.0.0

package/dist/src/planner/mutation/propagate.js

@@ -0,0 +1,220 @@
+import { PlanNodeType } from '../nodes/plan-node-type.js';
+import { isRelationalNode } from '../nodes/plan-node.js';
+import { TableReferenceNode } from '../nodes/reference.js';
+import { buildTableReference } from '../building/table.js';
+import { raiseMutationDiagnostic } from './mutation-diagnostic.js';
+import { rewriteViewInsert, rewriteViewUpdate, rewriteViewDelete } from './single-source.js';
+import { isJoinBody, propagateMultiSource } from './multi-source.js';
+import { propagateDecomposition } from './decomposition.js';
+/**
+ * Mutation propagation classifier — the dual of `binding-extractor` /
+ * `change-scope`, walking a planned view body from the user-visible relation
+ * down to base-table references to decide whether a deterministic decomposition
+ * exists at plan time (see `docs/view-updateability.md` § Mutation Propagation).
+ *
+ * **Phase 1 scope.** Only the *single-source projection-and-filter* shape is
+ * decomposable: the relational spine from the body root to a base table may
+ * contain only pass-through operators (Project / Filter / Sort / Limit /
+ * Distinct / Alias / Retrieve) and must terminate at exactly one
+ * `TableReferenceNode`. Joins, aggregates, set-ops, windows, recursive CTEs and
+ * VALUES bodies are rejected with a structured reason; the broader FD/EC-driven
+ * fan-out is Phase 2+.
+ *
+ * `Sort` / `Limit` / `Distinct` are tolerated *here* only so the walk can reach
+ * the base table through them; the single-source rewrite layer
+ * (`mutation/single-source.ts`) separately rejects `LIMIT`/`OFFSET`/`DISTINCT`
+ * bodies, since a predicate-conjoin cannot faithfully reproduce a row-count
+ * window or duplicate-collapse (a mutation would otherwise escape the window).
+ *
+ * The walk descends only *relational* children (`getRelations()`), so scalar
+ * subqueries embedded in predicates/projections never pollute the base-table
+ * count.
+ */
+/** Pass-through relational operators that a phase-1 decomposition tolerates. */
+const PASSTHROUGH_NODES = new Set([
+    PlanNodeType.Retrieve,
+    PlanNodeType.Filter,
+    PlanNodeType.Project,
+    PlanNodeType.Distinct,
+    PlanNodeType.Sort,
+    PlanNodeType.LimitOffset,
+    PlanNodeType.Alias,
+    // A lens-boundary FD marker is row-preserving and single-source; tolerated so
+    // a lens-over-lens body walk can reach the base table through it. (The
+    // standard lens mutation walks the compiled body over basis tables, where
+    // this node never appears — see docs/lens.md § FD contribution.)
+    PlanNodeType.AssertedKeys,
+]);
+/** Map a disallowed body operator to a structured rejection reason. */
+function reasonForOperator(nodeType) {
+    switch (nodeType) {
+        case PlanNodeType.Join:
+        case PlanNodeType.NestedLoopJoin:
+        case PlanNodeType.HashJoin:
+        case PlanNodeType.MergeJoin:
+        case PlanNodeType.AsofScan:
+        case PlanNodeType.FanOutLookupJoin:
+            return 'unsupported-join';
+        case PlanNodeType.Aggregate:
+        case PlanNodeType.StreamAggregate:
+        case PlanNodeType.HashAggregate:
+            return 'unsupported-aggregate';
+        case PlanNodeType.SetOperation:
+            return 'unsupported-set-op';
+        case PlanNodeType.Window:
+            return 'unsupported-window';
+        case PlanNodeType.RecursiveCTE:
+        case PlanNodeType.InternalRecursiveCTERef:
+            return 'recursive-cte';
+        default:
+            return 'no-base-lineage';
+    }
+}
+/**
+ * Classify a planned view body for phase-1 mutability. Returns the single base
+ * table when the body is a single-source projection-and-filter, or a structured
+ * rejection naming the obstructing operator.
+ */
+export function classifyViewBody(body) {
+    const tableRefs = [];
+    let rejection;
+    const visit = (node) => {
+        if (rejection)
+            return;
+        if (node instanceof TableReferenceNode) {
+            tableRefs.push(node);
+            return;
+        }
+        if (isRelationalNode(node) && !PASSTHROUGH_NODES.has(node.nodeType)) {
+            rejection = {
+                kind: 'rejected',
+                reason: reasonForOperator(node.nodeType),
+                detail: `view body operator '${node.nodeType}' is not updateable in phase 1`,
+            };
+            return;
+        }
+        for (const child of node.getRelations()) {
+            visit(child);
+        }
+    };
+    visit(body);
+    if (rejection)
+        return rejection;
+    if (tableRefs.length === 0) {
+        return {
+            kind: 'rejected',
+            reason: 'no-base-lineage',
+            detail: 'view body reaches no base table (e.g. a VALUES body); no recoverable base operation',
+        };
+    }
+    if (tableRefs.length > 1) {
+        return {
+            kind: 'rejected',
+            reason: 'unsupported-join',
+            detail: `view body references ${tableRefs.length} base tables; multi-source decomposition is phase 2`,
+        };
+    }
+    return { kind: 'single-source', baseTable: tableRefs[0] };
+}
+/**
+ * The decomposition storage shape to fan a mutation out across, or `undefined`
+ * when the target is not a decomposition-backed logical table.
+ *
+ * Gated to the **synthesized** get body: a `primary-storage` advertisement with
+ * no `declare lens` override means the registered body is exactly the
+ * `compileDecompositionBody` join (`schema/lens-compiler.ts`), so the
+ * advertisement faithfully describes its members. A plain view / MV / name-match
+ * lens has no slot or no storage advertisement ⇒ `undefined` (unchanged path); an
+ * overridden lens carries a hand-authored body the advertisement does not
+ * describe, so it stays on the generic path too.
+ */
+export function decompositionStorage(ctx, view) {
+    const slot = ctx.schemaManager.getSchema(view.schemaName)?.getLensSlot(view.name);
+    if (!slot || slot.override || slot.advertisement?.role !== 'primary-storage')
+        return undefined;
+    return slot.advertisement.storage;
+}
+/** Resolve the base table named by a rewritten base-table DML statement. */
+function resolveBaseTable(ctx, statement) {
+    return buildTableReference({ type: 'table', table: statement.table }, ctx).tableRef;
+}
+/**
+ * Decompose a view-/MV-mediated mutation into an ordered list of base-table
+ * operations — the single propagation path for all view mutations.
+ *
+ * - A **single-source** projection-and-filter spine reuses the relocated rewrite
+ *   (`single-source.ts`) to produce exactly one `BaseOp`.
+ * - A **two-table key-preserving inner join** body routes to the planned-body
+ *   walk (`multi-source.ts`), which reads `updateLineage` to emit an ordered
+ *   multi-element `BaseOp[]` for `update` / `delete` (insert is a later phase).
+ *
+ * Broader shapes (outer joins, set-ops, aggregates, > 2 tables) stay
+ * diagnosed-and-rejected with a structured reason.
+ */
+export function propagate(ctx, view, req, 
+/**
+ * A CTE-name DML target's `ctxSelfRead` (the body context with the target name
+ * re-added to `cteNodes`, resolving to the eager self-read capture), threaded into
+ * the single-source UPDATE/DELETE rewrite so a user-clause self-read `from t`
+ * resolves to the frozen capture (docs/view-updateability.md § Common Table
+ * Expressions — self-reference). Ignored for insert and for the join / decomposition
+ * / set-op paths (none of which take the single-source self-read capture path). The
+ * BODY is still analysed under `ctx` (target-excluded), so its own `from base`
+ * reaches the real table.
+ */
+descendCtx) {
+    // A logical table backed by a decomposition advertisement is registered as a
+    // view whose body is the synthesized `anchor ⋈ members` join. Routing it
+    // through the generic two-table join path below would be unsound (that path
+    // picks a single delete side, caps at two tables, and rejects the outer joins
+    // optional members ride). Intercept it and fan out off the advertisement.
+    const storage = decompositionStorage(ctx, view);
+    if (storage) {
+        return propagateDecomposition(ctx, view, storage, req);
+    }
+    // A binary set-operation body carrying membership flags is written through the
+    // per-branch fan-out, which needs a plan-level capture (the affected rows + their
+    // runtime membership probe) the AST `BaseOp[]` model cannot carry — so it is built
+    // directly by `building/view-mutation-builder.ts` (`buildSetOpMutation`), which
+    // intercepts before `propagate` runs. Reaching here means a direct/recursive
+    // `propagate` call on such a body (e.g. a nested set-op branch — `set-op-membership-nested`);
+    // guard it explicitly rather than mis-routing it into the single-source rewrite (which
+    // would reject `unsupported-set-op` with a misleading message). A plain (flag-less)
+    // set-op body is NOT intercepted here — a directly-reached *flag-less writable* body is
+    // handled in `view-mutation-builder.ts` (`set-op-flagless-predicate-honest-writes`, gated
+    // to real views); any other flag-less compound (a non-writable shape, or an ephemeral
+    // CTE / inline target) falls through to the single-source spine below and rejects
+    // `unsupported-set-op` via `classifyViewBody`'s established "not updateable in phase 1"
+    // diagnostic, unchanged. The AST peek is inlined (not imported from `set-op.ts`) to keep
+    // the dependency one-directional — `set-op.ts` imports `propagate`, never the reverse.
+    const so = view.selectAst;
+    if (so.type === 'select' && so.compound && so.compound.op !== 'diff'
+        && so.compound.existence && so.compound.existence.length > 0) {
+        raiseMutationDiagnostic({
+            reason: 'unsupported-set-op',
+            table: view.name,
+            message: `cannot write through view '${view.name}': a nested / recursively-reached set-operation membership body is not yet decomposable (binary, non-nested set-op writes are built via buildSetOpMutation; nested subtree writes are set-op-membership-nested)`,
+        });
+    }
+    // A join body decomposes through the multi-source planned-body walk; a
+    // single-table body through the single-source spine. The peek is a cheap AST
+    // check that builds no plan, so the single-source path is unchanged in cost.
+    if (isJoinBody(view.selectAst)) {
+        return propagateMultiSource(ctx, view, req);
+    }
+    switch (req.op) {
+        case 'insert': {
+            const statement = rewriteViewInsert(ctx, req.stmt, view);
+            return [{ table: resolveBaseTable(ctx, statement), op: 'insert', statement }];
+        }
+        case 'update': {
+            const statement = rewriteViewUpdate(ctx, req.stmt, view, descendCtx);
+            return [{ table: resolveBaseTable(ctx, statement), op: 'update', statement }];
+        }
+        case 'delete': {
+            const statement = rewriteViewDelete(ctx, req.stmt, view, descendCtx);
+            return [{ table: resolveBaseTable(ctx, statement), op: 'delete', statement }];
+        }
+    }
+}
+//# sourceMappingURL=propagate.js.map

package/dist/src/planner/mutation/propagate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"propagate.js","sourceRoot":"","sources":["../../../../src/planner/mutation/propagate.ts"],"names":[],"mappings":"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"}

package/dist/src/planner/mutation/scope-transform.d.ts

@@ -0,0 +1,181 @@
+import type * as AST from '../../parser/ast.js';
+import type { PlanningContext } from '../planning-context.js';
+/**
+ * The one scope-aware column-substitution primitive the view-mutation backward
+ * path shares (`docs/view-updateability.md` § Selection).
+ *
+ * Three callers used to each carry a near-parallel copy of "rewrite column
+ * references X→Y in an expression / query, scope-aware (shadowing, taint, deep
+ * subquery descent)":
+ *  - `single-source.ts` — the view-column → base-term descent and the
+ *    correlation-qualifier of a substituted base term (both DEEP / scope-aware),
+ *  - `multi-source.ts` — view-column → alias-qualified base term,
+ *  - `lens-enforcement.ts` — logical → basis column rewriting.
+ *
+ * They share a shadowing/taint model and differ only in the substitution map and
+ * the qualification rule. This module owns the structural tree-walker
+ * ({@link transformExpr} and the clones built on it), the FROM-source column-name
+ * resolution that drives the shadow set ({@link collectFromColumnNames}), and the
+ * scope-aware descent ({@link transformScopedExpr} / {@link transformScopedQuery})
+ * parameterized by a {@link ScopeContext} value object. Each caller supplies a
+ * `ScopeContext` (its substitution closure + taint policy + reject builders); the
+ * descent itself — shadow accumulation across nested scopes, the
+ * `unsupported-subquery-correlation` taint logic, sibling-leg scoping — is shared.
+ */
+/**
+ * Structurally clone an expression, substituting column references via
+ * `substitute`. A substituted replacement is cloned but NOT re-substituted
+ * (the replacement is already in target terms).
+ *
+ * Subquery operands (`subquery` / `exists` / `in … (select …)`) are descended
+ * into via the optional `descend` transformer, so a column reference nested
+ * inside a correlated subquery of a user predicate / assigned value is rewritten
+ * to its lineage (scope-aware — see {@link transformScopedQuery}). With `descend`
+ * omitted the subquery operand is passed through structurally — byte-identical to
+ * a plain structural rewrite — which keeps every top-level-only caller (and
+ * {@link cloneExpr}'s no-substitution clone) unchanged.
+ */
+export declare function transformExpr(expr: AST.Expression, substitute: (col: AST.ColumnExpr) => AST.Expression | undefined, descend?: (query: AST.QueryExpr) => AST.QueryExpr): AST.Expression;
+/** Deep structural clone of an expression, including any nested subqueries. */
+export declare function cloneExpr(expr: AST.Expression): AST.Expression;
+/**
+ * Substitute every `new.<name>`-qualified column reference in an authored
+ * inverse expression (docs/view-updateability.md § Authored inverses) — at any
+ * depth, including inside subquery operands (a `new.` ref correlates to the
+ * written view row wherever it appears; `new` is a reserved qualifier no FROM
+ * source legitimately shadows). The replacement is cloned by `transformExpr`,
+ * so `resolve` may return a shared expression.
+ */
+export declare function substituteNewRefs(expr: AST.Expression, resolve: (name: string) => AST.Expression): AST.Expression;
+/** Deep structural clone of a relation-producing subquery (no substitution). */
+export declare function cloneQueryExpr(query: AST.QueryExpr): AST.QueryExpr;
+/**
+ * Apply a column substitution uniformly through a subquery's structure — NOT
+ * scope-aware. The substitution decides purely on the column's own qualifier
+ * (e.g. {@link cloneQueryExpr}'s no-op, or the multi-source SET-value qualifier
+ * strip), so the enclosing scope is irrelevant and the same `substitute` is
+ * applied at every nesting depth. The `with` clause is cloned without
+ * substitution — a CTE body cannot correlate to the enclosing query, so it
+ * needs no rewrite, only severed sharing (see {@link cloneWithClause}).
+ */
+export declare function mapQueryExprUniform(query: AST.QueryExpr, substitute: (col: AST.ColumnExpr) => AST.Expression | undefined): AST.QueryExpr;
+/**
+ * Resolve the lowercased set of column names a subquery's FROM sources introduce
+ * into scope, or `null` when any source's columns cannot be resolved statically
+ * (a TVF, a `select *` / unnamed-projection subquery source, or an unknown name
+ * such as a CTE reference). A `null` marks the scope (and everything nested in
+ * it) **tainted**: a descent can no longer prove an unqualified reference is
+ * *not* a local column, so the {@link ScopeContext} decides whether to reject or
+ * carry the taint forward.
+ */
+export declare function collectFromColumnNames(ctx: PlanningContext, from: readonly AST.FromClause[] | undefined): Set<string> | null;
+/**
+ * The caller-specific knobs of a scope-aware substitution. The descent
+ * ({@link transformScopedQuery}) owns the shadow accumulation / taint
+ * propagation / sibling-leg scoping; this object owns only what differs between
+ * callers: the per-column substitution rule and how to treat an unresolvable
+ * scope or an embedded data-modifying subquery.
+ */
+interface ScopeContextBase {
+    /**
+     * Build the per-column substitution closure for ONE scope, given the set of
+     * column names shadowed by this (and enclosing) scopes, whether the scope is
+     * tainted (an enclosing scope's columns proved unresolvable), and the set of FROM
+     * **aliases** bound by this (and enclosing) scopes. Returns the replacement
+     * expression for a column, or `undefined` to leave it untouched. May throw a
+     * structured diagnostic (e.g. a tainted scope rejecting an unqualified,
+     * correlation-ambiguous reference).
+     *
+     * `aliasShadowed` is the alias-only analog of `shadowed` (built from
+     * {@link collectFromAliases}, never tainted — a FROM alias is always statically
+     * known). It lets a context distinguish a genuine outer-correlation qualifier from
+     * a qualifier that names a locally-shadowed FROM source: a view-name-qualified ref
+     * (`t.id`) is an outer view-column correlation UNLESS `t` is also a local FROM
+     * alias (the self-read `select t.id from t` over the eager capture), in which case
+     * it is the capture's own column and stays local. Implementers that do not care
+     * about alias shadowing simply ignore the parameter.
+     */
+    makeSubstitute(shadowed: ReadonlySet<string>, tainted: boolean, aliasShadowed: ReadonlySet<string>): (col: AST.ColumnExpr) => AST.Expression | undefined;
+    /** Raise the structured diagnostic for an embedded data-modifying (INSERT/UPDATE/DELETE) subquery. */
+    rejectDmlSubquery(): never;
+}
+/**
+ * The caller-specific knobs of a scope-aware substitution. The descent
+ * ({@link transformScopedQuery}) owns the shadow accumulation / taint
+ * propagation / sibling-leg scoping; this object owns only what differs between
+ * callers: the per-column substitution rule and how to treat an unresolvable
+ * scope or an embedded data-modifying subquery.
+ *
+ * The `unresolvableScope` policy — for when a scope's FROM columns are
+ * unresolvable (`collectFromColumnNames` returns `null`) — is a discriminated
+ * union: `'taint'` carries `tainted = true` forward (the substitution decides
+ * per-reference); `'reject'` raises `rejectUnresolvableScope` immediately rather
+ * than risk a silent mis-bind, and the union requires the handler be supplied
+ * exactly with that policy (so the descent never needs a non-null assertion).
+ */
+export type ScopeContext = ScopeContextBase & ({
+    readonly unresolvableScope: 'taint';
+    rejectUnresolvableScope?: undefined;
+} | {
+    readonly unresolvableScope: 'reject';
+    rejectUnresolvableScope(): never;
+});
+/**
+ * Scope-aware substitution over an expression, entered at the outermost scope
+ * (no shadowing, untainted). Used to rewrite a substituted *term* whose own
+ * correlation refs must be (re-)bound (the single-source base-term qualifier).
+ */
+export declare function transformScopedExpr(ctx: PlanningContext, scope: ScopeContext, expr: AST.Expression): AST.Expression;
+/**
+ * Scope-aware transform of an inner `QueryExpr`. Rewrites column references
+ * correlated to the outer scope per the {@link ScopeContext}, while leaving
+ * subquery-local same-named columns untouched.
+ *
+ * `shadowed` is the set of column names introduced by ENCLOSING subquery scopes;
+ * `tainted` is set once an enclosing scope's columns proved unresolvable (so the
+ * `ScopeContext`'s substitution can reject an unqualified, ambiguous reference at
+ * this depth or below). A `select`'s own FROM column names join the shadow set
+ * for its clauses and any subquery nested in them; a sibling compound / union leg
+ * keeps the incoming `shadowed` / `tainted` (it correlates to the same outer
+ * scope, not to this select's FROM).
+ */
+export declare function transformScopedQuery(ctx: PlanningContext, scope: ScopeContext, query: AST.QueryExpr, shadowed: ReadonlySet<string>, tainted: boolean, aliasShadowed?: ReadonlySet<string>): AST.QueryExpr;
+/**
+ * The lowercased set of FROM aliases a subquery's FROM sources bind into scope.
+ * Unlike {@link collectFromColumnNames} this NEVER returns `null` and needs no
+ * `PlanningContext`: a FROM alias is always statically known from the FROM clause
+ * itself, even when the source's *columns* are unresolvable (a `select *` / TVF /
+ * CTE still binds its own alias), so alias shadowing needs no taint signal.
+ *
+ *   table          -> alias ?? table.name
+ *   subquerySource -> alias              (always present)
+ *   functionSource -> alias ?? name.name
+ *   join           -> union(left, right)
+ */
+export declare function collectFromAliases(from: readonly AST.FromClause[] | undefined): Set<string>;
+/**
+ * Alias-shadow-aware structural substitution over an expression, entered at the
+ * outermost scope (no inner FROM aliases shadow yet). `substitute` receives each
+ * column AND the set of FROM aliases shadowing at the column's depth, so a
+ * qualifier shadowed by an inner value-subquery FROM alias can be left local
+ * (per innermost-scope SQL rules) instead of routed by the cross-source strip.
+ *
+ * Mirrors {@link transformScopedQuery}'s scope rules — a select's own FROM
+ * aliases join the shadow set for its clauses and any subquery nested in them; a
+ * compound / union leg keeps the incoming set (it correlates to the same outer
+ * scope); VALUES has no FROM — but threads ONLY an alias set: no column-name
+ * shadow set, no taint, no reject. An embedded INSERT/UPDATE/DELETE … RETURNING
+ * subquery is cloned through structurally (no substitution), exactly matching the
+ * cross-source strip's prior {@link mapQueryExprUniform} behaviour.
+ */
+export declare function transformAliasScopedExpr(expr: AST.Expression, substitute: (col: AST.ColumnExpr, aliasShadow: ReadonlySet<string>) => AST.Expression | undefined): AST.Expression;
+/**
+ * Alias-shadow-aware transform of an inner `QueryExpr`, threading the FROM-alias
+ * shadow set exactly as {@link transformScopedQuery} threads its column-name
+ * `shadowed` set: a `select`'s own FROM aliases join the set for its clauses and
+ * nested subqueries; a sibling compound / union leg keeps the incoming set; a
+ * VALUES body (no FROM) keeps it too; a DML … RETURNING subquery clones through.
+ */
+export declare function transformAliasScopedQuery(query: AST.QueryExpr, substitute: (col: AST.ColumnExpr, aliasShadow: ReadonlySet<string>) => AST.Expression | undefined, aliasShadow?: ReadonlySet<string>): AST.QueryExpr;
+export {};
+//# sourceMappingURL=scope-transform.d.ts.map

package/dist/src/planner/mutation/scope-transform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-transform.d.ts","sourceRoot":"","sources":["../../../../src/planner/mutation/scope-transform.ts"],"names":[],"mappings":"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"}