@quereus/quereus 3.3.0 → 4.0.0

package/dist/src/planner/mutation/set-op.d.ts

@@ -0,0 +1,242 @@
+import type * as AST from '../../parser/ast.js';
+import type { PlanningContext } from '../planning-context.js';
+import { type BaseOp, type MutableViewLike, type MutationRequest } from './propagate.js';
+import { type MultiSourceKeyCapture } from './multi-source.js';
+/**
+ * Set-operation membership-column write decomposition — the **first set-op view
+ * writability** in the engine (docs/view-updateability.md § Set Operations).
+ *
+ * The read half (`set-op-membership-read`) reifies a binary set operation's branch
+ * provenance as first-class `existence`-sited boolean columns and, per row, computes
+ * a runtime membership probe (`inA ≡ tuple ∈ A`). This module delivers the write
+ * payoff: a membership column **is** the branch presence, and *writing* it drives the
+ * branch's existence:
+ *
+ * ```sql
+ * -- U = select id, x from A union exists left as inA, exists right as inB select id, x from B
+ * update U set inB = true  where id = 3   -- a row in A only ⇒ INSERT it into B
+ * update U set inB = false where id = 3   -- a row in B      ⇒ DELETE the matching B row
+ * ```
+ *
+ * **The substrate (Halloween-safe via an up-front capture).** Every affected view
+ * row — its data columns AND its membership-probe flags — is captured ONCE
+ * (`buildSetOpCapture`), *before* any branch op fires, into the same context-backed
+ * key relation the multi-source path uses ({@link MS_UPDATE_KEYS_CTE}). The per-branch
+ * ops then read that immutable capture rather than re-scanning the view (which reads
+ * the very branches being written), so a branch insert/delete can never perturb the
+ * affected set out from under a sibling branch op. The capture rides the existing
+ * `ViewMutationNode.identityCapture` side input + the void/drain runtime path — no new
+ * runtime substrate (see `runtime/emit/view-mutation.ts`).
+ *
+ * **A branch is itself a view body — routed per-branch via recursive `propagate`.**
+ * Each operand of the set operation is a relational sub-plan (`select … from B`). A
+ * **single-source** branch's per-branch op is lowered to an AST `BaseOp` against a
+ * **synthetic branch view-like** and run back through {@link propagate} — reusing the
+ * single-source spine verbatim (the branch's own σ predicate, renames, and base routing are
+ * honored by its spine).
+ *
+ * A **multi-source (INNER join) branch/leg** ({@link isInnerJoinBody}) is **composed** rather
+ * than routed through plain {@link propagate} (`set-op-write-multisource-leg-compose`): plain
+ * `propagate` builds NO capture, so its emitted multi-source predicates (`k<side>_<j>`) would
+ * bind to the outer set-op capture (view-output columns) — the internal `k.k0_0 isn't a column`
+ * error. Instead the fan builds the join branch itself (mirroring `buildViewMutation`'s
+ * orchestration): {@link analyzeJoinView} + {@link decomposeUpdate}/{@link decomposeDelete} +
+ * {@link buildMultiSourceKeyCapture} build an **inner per-branch base-PK capture** under a fresh
+ * `__vmupd_keys$N` name (minted monotonically — two join branches never collide), filtered by the
+ * SAME {@link buildMemberExists} predicate (so it scans the OUTER set-op capture), and bubble it
+ * up on {@link SetOpWritePlan.nestedCaptures} (materialized outer-first then inner, via
+ * `ViewMutationNode.nestedCaptures`). INSERT into a join branch is deferred to
+ * `set-op-write-multisource-leg-insert` (needs the plan-level shared-surrogate envelope) — a clean
+ * reject + `is_insertable_into = NO`; an OUTER (left/right/full) / cross / non-equi join leg is
+ * likewise deferred (a clean classification reject). A branch that bottoms out in a base table emits one base op; a branch
+ * that is itself a `SetOperationNode` (a **subtree operand**, `nestable-flagged-set-ops`)
+ * recurses *here* for the unambiguous fan-out — a data-column UPDATE, a DELETE, and a
+ * `set <subtreeFlag> = false` drop fan out to every member leaf, sharing the ONE up-front
+ * capture (`fanBranchDataUpdate` / `fanBranchDelete`, detected via {@link analyzeSetOpBranches}).
+ * A **union / union all** subtree fans freely (a leaf ⊆ the subtree). An **`except` /
+ * `intersect`** subtree fan is **membership-gated** (`set-op-membership-nested-except`): a leaf
+ * can hold rows the subtree excludes, so the recursion AND-s the captured subtree-membership
+ * boundary flag (`exists <branch> as <flag>`) into each leaf's member-exists, restricting the
+ * fan to genuine members — one conjunct per non-union boundary descended. A flag-less non-union
+ * boundary has no boundary probe to gate on and stays deferred (rejected).
+ * The genuinely ambiguous inserts into a subtree — `set <subtreeFlag> = true`, a
+ * surfaced-inner-flag write, and insert-through routing into a subtree side — have no single
+ * deterministic target leaf (product-coordinate addressing) and are rejected, pointing at
+ * `set-op-membership-nested`.
+ *
+ * **A LEFT operand can be a subtree too** (`set-op-leftwrap-write`). A parenthesized LEFT
+ * compound operand — `(A∪B) union[…] (C∪D)`, a *parallel-sibling* shape — is lifted by the parser
+ * into a `select * from (A∪B) as values_N` passthrough wrapper so the SELECT-level `compound` slot
+ * can host the outer operator. {@link buildBranch} **unwraps** that wrapper (via
+ * {@link unwrapBranchSelect}, the same {@link unwrapPassthroughSubquery} predicate the read/plan
+ * path uses) so the wrapped left operand is a first-class subtree operand — its data cols,
+ * `isNested`, and fan-out recursion all derive from the inner compound, exactly as the
+ * (always-direct) right compound operand. So the unambiguous fan-out (data UPDATE / DELETE /
+ * `set <subtreeFlag> = false`) reaches the LEFT subtree's leaves, while the ambiguous inserts
+ * into it stay deferred (`set-op-membership-nested`). The static surfaces walk both operands too.
+ *
+ * **Per-branch correlation.** A fan-out / membership-delete op identifies the branch's
+ * affected rows by a correlated `exists (select 1 from __vmupd_keys k where <k matches
+ * the branch row's data tuple>)` — a NULL-safe full-data-tuple match (set operations
+ * treat `NULL = NULL` as equal, and the engine has no `IS NOT DISTINCT FROM`, so each
+ * column is matched `k.c = b.c or (k.c is null and b.c is null)`). The branch's own
+ * columns are qualified with the synthetic branch-view name so {@link propagate}'s
+ * single-source correlation (the `__vm_self` self-alias) binds them to the lowered base
+ * row; the `k.*` capture columns stay unqualified-to-the-branch and resolve to the
+ * injected `__vmupd_keys` relation. The membership-INSERT branch instead reads the
+ * captured rows **absent** from the branch via the probe flag (`where not k.<flag>`),
+ * so a `set <flag> = true` is a clean no-op for rows already present (and across
+ * operators — `except`'s always-false right flag inserts every visible row, `intersect`'s
+ * always-true flags insert none).
+ *
+ * **Scope.** union / union all / except / intersect membership writes, data-column fan-out,
+ * delete fan-out, and insert-through, at any nesting depth for the unambiguous fan-out
+ * operations (data UPDATE / DELETE / `set <subtreeFlag> = false`). The ambiguous inserts
+ * into a subtree (`set <subtreeFlag> = true`, surfaced-inner-flag writes, insert-through into
+ * a subtree side) are `set-op-membership-nested` (product-coordinate addressing); non-literal
+ * boolean membership writes and the `strict` unspecified-case policy stay deferred.
+ */
+/**
+ * True iff `selectAst` is a **binary set-operation body carrying ≥1 membership flag**
+ * (`<setop> exists <branch> as <name>`) — the shape this write path decomposes. An
+ * AST peek (no plan built), the write-side shadow of the read half's combinator. A
+ * plain (flag-less) set-op body returns `false` and keeps rejecting `unsupported-set-op`
+ * through the single-source spine (there is no membership column to address a branch by).
+ * `diff` is excluded (the parser already rejects membership on it).
+ */
+export declare function isSetOpMembershipBody(selectAst: AST.QueryExpr): boolean;
+/**
+ * True iff a set-op membership body is reportable-writable by the static surfaces — the
+ * no-plan shadow of {@link analyzeSetOpView}'s pre-write rejections: an outer LIMIT/OFFSET
+ * (the body is not decomposable — a write would escape the limited window), a non-SELECT
+ * right operand, a `select *` leg, or a computed (non-plain-column) leg. Lets the
+ * `column_info` / `view_info` static surfaces gate the membership-writable claim on the SAME
+ * shape the dynamic write enforces, instead of reporting writable from the membership flag's
+ * presence alone.
+ *
+ * **Recursive** (`nestable-flagged-set-ops`): an operand is branch-writable iff it is a
+ * plain-leg leaf OR a (recursively) branch-writable set-op body — so a nested view reports
+ * `is_updatable` / `is_deletable` = YES, agreeing with the dynamic accept (data + delete
+ * fan-out recurse through a subtree operand). Inserts into a subtree are deferred, so
+ * insertability is gated separately on {@link setOpHasSubtreeOperand}.
+ */
+export declare function isSetOpBranchWritable(selectAst: AST.QueryExpr): boolean;
+/**
+ * True iff a membership body has a **subtree (compound) operand** — an inner
+ * `SetOperationNode` operand on EITHER side. Insert-through into a multi-leaf subtree has no
+ * single deterministic target leaf (product-coordinate addressing — `set-op-membership-nested`),
+ * so the static `is_insertable_into` surface gates to `NO` when this holds, while
+ * data/delete fan-out (which touches every member leaf) stays writable. A parenthesized LEFT
+ * compound operand is lifted into a `select * from (compound)` wrapper, so the left is unwrapped
+ * before probing — a parallel-sibling view (`set-op-leftwrap-write`) also reports NO.
+ */
+export declare function setOpHasSubtreeOperand(selectAst: AST.QueryExpr): boolean;
+/**
+ * True iff EVERY multi-source (INNER join) leg/branch of this set-op body would accept an
+ * implicit INSERT through the plan-level shared-surrogate envelope
+ * (`set-op-write-multisource-leg-insert`). A body with NO join leg returns `true` (its
+ * single-source legs are the existing insert-through path); a body with ≥1 join leg returns
+ * `true` only when every such leg's `analyzeMultiSourceInsert` probe succeeds.
+ *
+ * A purely structural inner-vs-outer predicate is INSUFFICIENT: an inner equi-join leg can still
+ * reject dynamically with `unsupported-decomposition-key` (a composite shared key — the CV shape),
+ * `unsupported-join` (a non-equi ON), or `no-default` (the shared key is neither supplied nor
+ * defaulted — e.g. the SJ self-join, whose anchor key `emp.mgr` has no default). So this re-derives
+ * the branches the same way the dynamic write does (membership via {@link analyzeSetOpView}, else
+ * {@link analyzeFlaglessSetOpView}) and probes each `isMultiSource` leg with
+ * {@link analyzeMultiSourceInsert} under a synthetic implicit (empty-column) `InsertStmt`, in
+ * try/catch — a leg that throws (composite key, non-equi, no-default, uncovered NOT NULL, …) ⇒
+ * `false`. The empty `columns` makes `analyzeMultiSourceInsert` use the implicit supply set, and an
+ * inner join leg has no existence columns, so the empty `values` is never read.
+ *
+ * This is only ever reached after {@link isSetOpBranchWritable} / {@link isSetOpFlaglessWritableBody}
+ * already passed (an outer-join branch / non-flagless body short-circuits to the conservative
+ * all-`NO` row upstream, never reaching here), so the branch re-derivation will not throw on the
+ * body shape; only the per-leg `analyzeMultiSourceInsert` probe may. It must not leak a structured
+ * diagnostic out of the read TVF, so every probe is caught.
+ */
+export declare function setOpJoinLegsInsertable(ctx: PlanningContext, view: MutableViewLike): boolean;
+/**
+ * The **surfaced inner-branch membership-flag names** of a (possibly nested) set-op body —
+ * every flag declared on a subtree operand, surfaced as a readable-but-non-writable column of
+ * the outer view. Returned in the plan's recursive `[L flags] ++ [R flags] ++ [own flags]`
+ * attribute layout (`SetOperationNode.buildAttributes`), so this list lands element-for-element
+ * on the plan-derived `analysis.surfacedInnerFlagNames` (`viewColNames` minus the leading data
+ * cols and trailing own flags). Empty for a binary (non-nested) body. Writing one addresses a
+ * branch *inside* a subtree operand (product-coordinate addressing), so `buildUpdate` rejects it
+ * with a `set-op-membership-nested` diagnostic and the `column_info` surface reports it
+ * `is_updatable = NO`.
+ */
+export declare function surfacedInnerFlagNames(selectAst: AST.QueryExpr): string[];
+/**
+ * One active multi-source (INNER join) leg/branch INSERT to build via the plan-level
+ * shared-surrogate envelope (`buildMultiSourceInsert`) and splice as a nested
+ * `ViewMutationNode` child of the outer set-op write node (`set-op-write-multisource-leg-insert`).
+ *
+ * The set-op insert builders cannot call `buildMultiSourceInsert` (it lives in the building
+ * layer, and `buildMultiSourceInsert` produces a whole `PlanNode`, not an AST `BaseOp`), so they
+ * record this per-leg descriptor instead of routing to {@link propagate}; `buildSetOpMutation`
+ * (beside `buildMultiSourceInsert`) turns each into a nested envelope-backed `ViewMutationNode`.
+ * The `stmt`'s source is self-contained for an insert-through / flag-less VALUES insert, or a
+ * SELECT over `__vmupd_keys` for a membership `set <flag> = true` flip (which reads the OUTER
+ * set-op capture — `buildSetOpMutation` passes the capture-injected context so it resolves).
+ */
+export interface JoinLegInsert {
+    /** The synthetic `__setop_*` / `__setop_legN` join-leg view-like the insert targets. */
+    readonly view: MutableViewLike;
+    /** The per-leg insert (VALUES self-contained, or a SELECT over `__vmupd_keys`). */
+    readonly stmt: AST.InsertStmt;
+}
+/**
+ * The decomposition of a set-op membership write: the ordered per-branch base ops plus
+ * the up-front capture they read. `capture` is absent for insert-through (whose values
+ * are self-contained — no affected-row read), present for every probe-driven write
+ * (membership flip, data fan-out, delete fan-out).
+ */
+export interface SetOpWritePlan {
+    readonly baseOps: BaseOp[];
+    readonly capture?: MultiSourceKeyCapture;
+    /**
+     * The inner per-branch base-PK captures one per **multi-source (join) branch** the fan
+     * reached (`set-op-write-multisource-leg-compose`), accumulated in fan order. Each is built
+     * over its branch's planned join body, filtered by the SAME `buildMemberExists` predicate
+     * (which scans the outer {@link capture} via `__vmupd_keys`), under a fresh
+     * `__vmupd_keys$N` name so two join branches never collide. `buildSetOpMutation` injects each
+     * under its own name for the branch base ops and rides them on `ViewMutationNode.nestedCaptures`
+     * (materialized AFTER the outer capture). Absent / empty for a join-leg-free set-op write —
+     * which then lowers byte-identically to the pre-list substrate.
+     */
+    readonly nestedCaptures?: MultiSourceKeyCapture[];
+    /**
+     * The active multi-source (INNER join) leg/branch INSERTs to build via the plan-level
+     * shared-surrogate envelope and splice as nested `ViewMutationNode` children of the outer
+     * set-op write node (`set-op-write-multisource-leg-insert`). Populated by the three insert
+     * routes — membership `set <flag> = true` ({@link buildBranchMembershipInsert}), flag-less
+     * consistent-leg INSERT ({@link buildFlaglessInsert}), and VALUES insert-through
+     * ({@link buildInsertThrough}) — in place of the join-leg `propagate` (which would raise the
+     * internal `unsupported-multisource-insert`). `buildSetOpMutation` builds each via
+     * `buildMultiSourceInsert`. Absent / empty for a join-leg-free insert.
+     */
+    readonly joinLegInserts?: JoinLegInsert[];
+}
+/** Decompose a set-op membership-column view mutation. Throws a structured diagnostic for unsupported shapes. */
+export declare function buildSetOpWrite(ctx: PlanningContext, view: MutableViewLike, req: MutationRequest): SetOpWritePlan;
+/**
+ * True iff `selectAst` is a flag-less set-op body writable through predicate-honest branch
+ * dispatch (`set-op-flagless-predicate-honest-writes`). Mutually exclusive with
+ * {@link isSetOpMembershipBody} (any `exists … as <flag>` takes the membership path); a
+ * non-decomposable shape (outer LIMIT/OFFSET, `select *` / computed leg, deep intersect/except)
+ * returns `false` and keeps rejecting `unsupported-set-op` through the single-source spine.
+ */
+export declare function isSetOpFlaglessWritableBody(selectAst: AST.QueryExpr): boolean;
+/**
+ * The flag-less view's **discriminator** column names — every data column projected as a
+ * literal in ANY leg (read-only, `no-inverse` on UPDATE). The view's column names come from
+ * the left-most leg (a set op takes its left child's names); a position is a discriminator
+ * iff some leg pins it with a literal projection. Used by the `column_info` static surface
+ * to report the discriminator `is_updatable = NO` (data / plain columns report YES).
+ */
+export declare function flaglessDiscriminatorColumnNames(selectAst: AST.QueryExpr): string[];
+/** Decompose a flag-less set-op view mutation. Throws a structured diagnostic for unsupported shapes. */
+export declare function buildFlaglessSetOpWrite(ctx: PlanningContext, view: MutableViewLike, req: MutationRequest): SetOpWritePlan;
+//# sourceMappingURL=set-op.d.ts.map

package/dist/src/planner/mutation/set-op.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"set-op.d.ts","sourceRoot":"","sources":["../../../../src/planner/mutation/set-op.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,GAAG,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAe9D,OAAO,EAAa,KAAK,MAAM,EAAE,KAAK,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACpG,OAAO,EAAiM,KAAK,qBAAqB,EAAyB,MAAM,mBAAmB,CAAC;AAIrR;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6FG;AAEH;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,GAAG,CAAC,SAAS,GAAG,OAAO,CAMvE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,GAAG,CAAC,SAAS,GAAG,OAAO,CAGvE;AA0ED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,GAAG,CAAC,SAAS,GAAG,OAAO,CAIxE;AAOD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,eAAe,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAmB5F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,GAAG,CAAC,SAAS,GAAG,MAAM,EAAE,CAYzE;AAyFD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa;IAC7B,wFAAwF;IACxF,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,UAAU,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,qBAAqB,CAAC;IACzC;;;;;;;;;OASG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,qBAAqB,EAAE,CAAC;IAClD;;;;;;;;;OASG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,aAAa,EAAE,CAAC;CAC1C;AAED,iHAAiH;AACjH,wBAAgB,eAAe,CAAC,GAAG,EAAE,eAAe,EAAE,IAAI,EAAE,eAAe,EAAE,GAAG,EAAE,eAAe,GAAG,cAAc,CAOjH;AAsoCD;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,GAAG,CAAC,SAAS,GAAG,OAAO,CAI7E;AAED;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAAC,SAAS,EAAE,GAAG,CAAC,SAAS,GAAG,MAAM,EAAE,CAcnF;AA+BD,yGAAyG;AACzG,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,eAAe,EAAE,IAAI,EAAE,eAAe,EAAE,GAAG,EAAE,eAAe,GAAG,cAAc,CAOzH"}