@quereus/quereus 3.3.0 → 4.0.0

package/dist/src/planner/analysis/coarsened-key.js

@@ -0,0 +1,228 @@
+/**
+ * Coarsened-backing-key derivation for materialized views — the create-time
+ * policy that enables the parallel-migration-table pattern
+ * (`docs/migration.md` § Convergence hazards): a body like
+ * `select handle collate nocase as handle, email from Contact_v1` has **no
+ * provable unique key** (the collation-weakening projection correctly drops the
+ * source key from `keysOf` — two source rows can collide under the output
+ * collation), yet the projected source key is the *intended backing identity*.
+ *
+ * This module recognizes that shape: when the body is a **row-preserving
+ * single-source chain** and every source primary-key column is reachable from
+ * an output column through a **value-preserving passthrough chain** (a bare
+ * column reference, `collate`, or a no-op `cast` — the
+ * `traceInvertibleColumn` passthrough subset with no inverse steps), the
+ * corresponding output columns form the **coarsened backing key** K'.
+ *
+ * K' is deliberately NOT a planner key fact — it never enters `keysOf` /
+ * `RelationType.keys`, because it is not a key of the body relation. It is an
+ * MV-create policy consumed by `deriveBackingShape` (key the backing on K',
+ * with the *output* collations) and `buildFullRebuildPlan` (do not reject the
+ * body as a bag). The runtime contract that makes this sound is documented in
+ * `docs/materialized-views.md` § Coarsened backing keys: create-fill rejects
+ * colliding rows loudly (the backing host's duplicate guard), and steady-state
+ * row-time maintenance merges colliding source rows last-writer-wins.
+ *
+ * **Coarsening classification.** A key column *coarsens* when its output
+ * collation can equate values the source enforcement collation distinguishes.
+ * `BINARY` is the finest collation (byte equality — nothing distinguishes
+ * more), so an output column at `BINARY` never coarsens; an output collation
+ * equal to the source's never coarsens; any *other* difference (BINARY →
+ * NOCASE/RTRIM, NOCASE → RTRIM, or an unknown custom collation) is treated as
+ * coarsening — conservative, since incomparable collations can equate values
+ * the source key keeps distinct. A coarsening K' triggers the key-coarsening
+ * warning at create ("colliding source rows will last-write-win until they are
+ * merged"); a non-coarsening K' (equal or refining collations) is a genuine
+ * unique key the key-propagation analysis just could not prove, and is
+ * accepted silently.
+ *
+ * **Why the chain must be row-preserving.** The LWW backing-identity semantics
+ * assume each source row maps to ≤1 output row. A collapsing node (aggregate,
+ * DISTINCT) between the source and the projection would make a lineage-covered
+ * source key a *false* identity — e.g. `group by b collate nocase, c` covers
+ * source PK {b} by lineage while the output holds many rows per b — so the
+ * walk admits only row-preserving/row-reducing links (Project / Filter / Sort
+ * / physical access nodes) over exactly one base table. Anything else
+ * (joins, set ops, aggregates, DISTINCT, window, TVFs, row caps) abstains and
+ * the caller keeps today's bag rejection.
+ */
+import { PlanNodeType } from '../nodes/plan-node-type.js';
+import { TableReferenceNode, ColumnReferenceNode } from '../nodes/reference.js';
+import { CastNode, CollateNode } from '../nodes/scalar.js';
+import { isNoOpCast } from './scalar-invertibility.js';
+/**
+ * Row-preserving / row-reducing single-source links the chain walk descends
+ * through (the coverage prover's pass-through vocabulary plus Filter). Each
+ * maps a source row to ≤1 output row, which is what the LWW backing-identity
+ * semantics require. Row caps (`LimitOffset` / `OrdinalSlice`) are deliberately
+ * excluded — conservative; a capped keyless body keeps the bag rejection.
+ */
+const ROW_PRESERVING_CHAIN = new Set([
+    PlanNodeType.Project,
+    PlanNodeType.Filter,
+    PlanNodeType.Sort,
+    PlanNodeType.Retrieve,
+    PlanNodeType.Alias,
+    PlanNodeType.AssertedKeys,
+    PlanNodeType.SeqScan,
+    PlanNodeType.IndexScan,
+    PlanNodeType.IndexSeek,
+    PlanNodeType.TableSeek,
+]);
+/** Canonical upper-case collation name (absent ⇒ `BINARY`). */
+function normalizeCollation(collation) {
+    return (collation ?? 'BINARY').toUpperCase();
+}
+/**
+ * Unwrap value-preserving wrappers — `collate` (comparison-only, value
+ * untouched) and no-op `cast` (target logical type === operand's) — down to
+ * the underlying expression. The `traceInvertibleColumn` passthrough subset
+ * with no `inverse` steps: the unwrapped expression evaluates to the SAME
+ * value as the wrapped one, which is what lets a wrapped column count as a
+ * passthrough projection of its source column.
+ */
+export function unwrapValuePreserving(expr) {
+    let node = expr;
+    for (;;) {
+        if (node instanceof CollateNode) {
+            node = node.operand;
+            continue;
+        }
+        if (node instanceof CastNode && isNoOpCast(node)) {
+            node = node.operand;
+            continue;
+        }
+        return node;
+    }
+}
+/**
+ * Resolve an output attribute id to a source column index through a
+ * transitive chain of **value-preserving** producing expressions: at each hop
+ * the attribute either belongs to the source directly or its producing
+ * expression unwraps ({@link unwrapValuePreserving}) to a column reference one
+ * hop closer. The value-preserving widening of
+ * `database-materialized-views.ts`'s `resolveTransitiveSourceCol` — shared by
+ * the coarsened-key derivation here and the inverse-projection arm's
+ * projector classification (a collate-wrapped projection copies the source
+ * value verbatim, so it is maintenance-passthrough).
+ */
+export function resolveValuePreservingSourceCol(attrId, sourceAttrToCol, producingByAttrId) {
+    const seen = new Set();
+    let cur = attrId;
+    while (!seen.has(cur)) {
+        seen.add(cur);
+        const direct = sourceAttrToCol.get(cur);
+        if (direct !== undefined)
+            return direct;
+        const expr = producingByAttrId.get(cur);
+        if (!expr)
+            return undefined;
+        const unwrapped = unwrapValuePreserving(expr);
+        if (!(unwrapped instanceof ColumnReferenceNode))
+            return undefined;
+        cur = unwrapped.attributeId;
+    }
+    return undefined;
+}
+/** Merge attribute provenance from one chain node into `out` (first writer wins). */
+function collectProducing(node, out) {
+    const fn = node.getProducingExprs;
+    if (typeof fn !== 'function')
+        return;
+    for (const [attrId, expr] of fn.call(node)) {
+        if (!out.has(attrId))
+            out.set(attrId, expr);
+    }
+}
+/**
+ * Derive the coarsened backing key K' for `root` (the optimized body
+ * relation), or `undefined` when the shape does not qualify (the caller then
+ * keeps today's bag rejection / all-columns fallback). See the module doc for
+ * the recognition rules. Deterministic over a given plan, so the two
+ * create-path consumers (`deriveBackingShape`, `buildFullRebuildPlan`) agree
+ * by construction.
+ *
+ * Only call when `keysOf(root)` is empty — a body with a provable key never
+ * needs (and must not be re-keyed by) lineage derivation.
+ */
+export function deriveCoarsenedBackingKey(root) {
+    // 1. Walk the row-preserving chain down to the single source table,
+    //    collecting attribute provenance from each link (Project nodes).
+    const producingByAttrId = new Map();
+    let tableRef;
+    let node = root;
+    const visited = new Set();
+    while (!visited.has(node)) {
+        visited.add(node);
+        if (node instanceof TableReferenceNode) {
+            tableRef = node;
+            break;
+        }
+        if (!ROW_PRESERVING_CHAIN.has(node.nodeType))
+            return undefined;
+        collectProducing(node, producingByAttrId);
+        const relations = node.getRelations();
+        if (relations.length !== 1)
+            return undefined;
+        node = relations[0];
+    }
+    if (!tableRef)
+        return undefined;
+    const sourceTable = tableRef.tableSchema;
+    const sourcePk = sourceTable.primaryKeyDefinition;
+    if (sourcePk.length === 0)
+        return undefined;
+    // 2. Trace each output column to a source column through value-preserving
+    //    passthrough chains only.
+    const sourceAttrToCol = new Map();
+    tableRef.getAttributes().forEach((a, i) => sourceAttrToCol.set(a.id, i));
+    const outAttrs = root.getAttributes();
+    const outputToSource = outAttrs.map(a => resolveValuePreservingSourceCol(a.id, sourceAttrToCol, producingByAttrId));
+    // 3. K' exists iff the source PK is fully covered by traced outputs. When a PK
+    //    column is covered by SEVERAL outputs (the same source column projected
+    //    under different wrappers), prefer a NON-coarsening one — it yields a true
+    //    unique key where a coarsening sibling would force the LWW contract (and
+    //    its warning) needlessly; ties break to the first covering output, for
+    //    determinism. Classify coarsening per column from the output vs source
+    //    enforcement collations.
+    const outputColumns = root.getType().columns;
+    const keyIndices = [];
+    const columns = [];
+    for (const def of sourcePk) {
+        const sourceCollation = normalizeCollation(def.collation ?? sourceTable.columns[def.index]?.collation);
+        // BINARY is the finest collation, so refinement to it never equates
+        // source-distinct values; any other difference is (conservatively) coarser.
+        const coarsensAt = (outIdx) => {
+            const outputCollation = normalizeCollation(outputColumns[outIdx]?.type.collationName);
+            return outputCollation !== sourceCollation && outputCollation !== 'BINARY';
+        };
+        let outputIndex = -1;
+        for (let i = 0; i < outputToSource.length; i++) {
+            if (outputToSource[i] !== def.index)
+                continue;
+            if (outputIndex < 0)
+                outputIndex = i;
+            if (!coarsensAt(i)) {
+                outputIndex = i;
+                break;
+            }
+        }
+        if (outputIndex < 0)
+            return undefined;
+        keyIndices.push(outputIndex);
+        columns.push({
+            outputIndex,
+            sourceColumn: def.index,
+            outputCollation: normalizeCollation(outputColumns[outputIndex]?.type.collationName),
+            sourceCollation,
+            coarsens: coarsensAt(outputIndex),
+        });
+    }
+    return {
+        keyIndices,
+        columns,
+        coarsens: columns.some(c => c.coarsens),
+        sourceTable,
+    };
+}
+//# sourceMappingURL=coarsened-key.js.map

package/dist/src/planner/analysis/coarsened-key.js.map

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

package/dist/src/planner/analysis/comparison-collation.d.ts

@@ -0,0 +1,216 @@
+/**
+ * THE shared resolution of a comparison's *effective collation*. Both the
+ * plan-time mirrors (access-path collation-cover analysis, FD/EC gates in
+ * `fd-utils.ts`, the predicate normalizer's eq↔IN gate, the constraint
+ * extractor's collation gates) and the runtime emitters (`emitComparisonOp`,
+ * `emitIn`, `emitBetween`, the USING-join comparator) call through this module,
+ * so plan-time facts and runtime behavior cannot drift.
+ *
+ * ## The resolution lattice
+ *
+ * Each operand contributes at most one `(collation, rank)`, derived from the
+ * provenance of its `ScalarType.collationName` ({@link CollationSource}):
+ *
+ * | rank | source                                            | BINARY contributes? |
+ * |------|---------------------------------------------------|---------------------|
+ * | 3    | `explicit` — a COLLATE expression                 | yes (`collate binary` is a real demand) |
+ * | 2    | `declared` — column with an explicit COLLATE      | yes (`c text collate binary` is a real preference) |
+ * | 1    | `default` — defaulted column collation            | **no** — a defaulted BINARY is the engine floor |
+ * | —    | no `collationName` (literals, most expressions)   | n/a |
+ *
+ * Resolution of `left <op> right` is **symmetric** (`a = b` ≡ `b = a`):
+ * 1. The highest rank present among the two contributions wins.
+ * 2. If both operands contribute at that rank with *different* normalized
+ *    names: rank 3 or 2 → plan-time error ({@link collationConflictError});
+ *    rank 1 → BINARY, silently (defaults are preferences, not declarations).
+ * 3. Otherwise the winning (single, or name-identical) contribution's name;
+ *    no contributions at all → BINARY.
+ *
+ * This deliberately diverges from SQLite's left-operand precedence: the engine
+ * follows explicit-over-implicit semantics and keeps comparisons commutative.
+ * See `docs/types.md` § Comparison collation resolution.
+ */
+import type { ScalarPlanNode } from '../nodes/plan-node.js';
+import type { InNode } from '../nodes/subquery.js';
+import type * as AST from '../../parser/ast.js';
+import type { ScalarType, CollationSource } from '../../common/datatype.js';
+import type { LogicalType } from '../../types/logical-type.js';
+import { QuereusError } from '../../common/errors.js';
+export type { CollationSource } from '../../common/datatype.js';
+/** The `(normalized name, rank)` one operand contributes to a comparison. */
+export interface CollationContribution {
+    readonly name: string;
+    readonly rank: 3 | 2 | 1;
+}
+/**
+ * The contribution one operand's type makes to a comparison, or `undefined`
+ * when it makes none (no `collationName`, or a defaulted BINARY — the engine
+ * floor is not a preference). An absent `collationSource` with a present
+ * `collationName` is treated as `'default'` (the safe floor for any
+ * construction site the provenance sweep missed).
+ */
+export declare function collationContribution(t: ScalarType): CollationContribution | undefined;
+/** Outcome of resolving two contributions: a single collation, or a same-rank conflict. */
+export type CollationResolution = {
+    kind: 'resolved';
+    name: string;
+} | {
+    kind: 'conflict';
+    level: 'explicit' | 'declared';
+    left: string;
+    right: string;
+};
+/**
+ * Effective collation of a binary comparison `left <op> right` under the
+ * lattice. Pure — never throws; conflicts are returned for the caller to
+ * surface (plan-time validation) or gate on (the predicate normalizer).
+ */
+export declare function resolveComparisonCollation(left: ScalarType, right: ScalarType): CollationResolution;
+/** Build the plan-time error for a same-rank explicit/declared conflict. */
+export declare function collationConflictError(conflict: Extract<CollationResolution, {
+    kind: 'conflict';
+}>, expr?: AST.Expression): QuereusError;
+/**
+ * Throwing form of {@link resolveComparisonCollation} over bare types, for
+ * sites that hold types rather than plan nodes (the USING-join emitter). The
+ * throw is a backstop — plan-time validation rejects user-written conflicts.
+ */
+export declare function effectiveCollationOfTypes(left: ScalarType, right: ScalarType, expr?: AST.Expression): string;
+/**
+ * Effective collation of a binary comparison `left <op> right`. Symmetric —
+ * operand order never changes the result. Throws `QuereusError` on a
+ * same-rank explicit/declared conflict (normally unreachable past plan-time
+ * validation in `BinaryOpNode.generateType`).
+ */
+export declare function effectiveComparisonCollation(left: ScalarPlanNode, right: ScalarPlanNode): string;
+/**
+ * Effective collation of one BETWEEN bound comparison. BETWEEN desugars to
+ * `expr >= lower AND expr <= upper`; each bound resolves independently through
+ * the same lattice (two independent comparisons — differing bound collations
+ * are NOT a conflict with each other, only with the tested expression).
+ */
+export declare function effectiveBetweenBoundCollation(expr: ScalarPlanNode, bound: ScalarPlanNode): string;
+/**
+ * Pure IN resolution: merge the right-hand-side contributions first (list
+ * elements under the lattice — a rank-3/2 name conflict among elements is the
+ * same plan-time error; rank-1 conflicts merge to no-contribution; a subquery
+ * RHS contributes its single output column's contribution), then resolve
+ * condition-vs-RHS. Literal-only lists contribute nothing, preserving
+ * condition-driven behavior for the dominant case.
+ */
+export declare function resolveInCollation(condition: ScalarType, rhs: ReadonlyArray<ScalarType>): CollationResolution;
+/** Pure form of {@link effectiveInCollation} — conflicts returned, not thrown. */
+export declare function resolveInCollationForNode(node: InNode): CollationResolution;
+/**
+ * Effective collation of `condition IN (...)`. `emitIn` pre-resolves this ONE
+ * collation for the whole membership test (the BTree build keys under it).
+ * Throws on conflict (backstop past `InNode.generateType` validation).
+ */
+export declare function effectiveInCollation(node: InNode): string;
+/**
+ * Collation propagated through a non-comparison combiner (`||` concat, CASE
+ * branch merge): the highest-ranked contribution wins; equal-rank
+ * contributions with the same name keep it; equal-rank contributions with
+ * different names propagate **no** collation — the conflict is not an error
+ * here (these nodes do not compare), but it must not silently coin-flip; a
+ * later comparison over the result then falls back to BINARY. Set-based over
+ * the winning rank, so operand/branch order cannot change the result.
+ */
+export declare function mergePropagatedCollation(types: ReadonlyArray<ScalarType>): {
+    collationName?: string;
+    collationSource?: CollationSource;
+};
+/**
+ * Per-output-column collation of a set operation (UNION/INTERSECT/EXCEPT/DIFF),
+ * merged symmetrically from the two inputs' corresponding column types through
+ * the comparison lattice. Mirrors a comparison: a same-rank explicit/declared
+ * name conflict is returned for the caller to surface as a plan-time error
+ * (DISTINCT operators) or swallow (UNION ALL does no dedup, like `||` / CASE);
+ * rank-1 default conflicts resolve to the BINARY floor (no contribution). The
+ * winning rank propagates as `collationSource` so the output column carries
+ * forward correctly into nested set-ops / outer comparisons.
+ */
+export type SetOpColumnCollation = {
+    kind: 'resolved';
+    collationName?: string;
+    collationSource?: CollationSource;
+} | {
+    kind: 'conflict';
+    level: 'explicit' | 'declared';
+    left: string;
+    right: string;
+};
+/**
+ * Resolve one set-operation output column's dedup/compare collation across both
+ * inputs. Pure — never throws; a conflict is returned for the caller to handle
+ * per operator (throw for `union`/`intersect`/`except`; treat as no-collation
+ * for `union all`). Semantically `resolveContributions(left, right)` except it
+ * keeps the winning contribution's *rank* (as `collationSource`) instead of
+ * collapsing to a bare name, so a nested set-op re-resolves at the correct rank.
+ */
+export declare function resolveSetOpColumnCollation(left: ScalarType, right: ScalarType): SetOpColumnCollation;
+export declare function isComparisonOperator(op: string): boolean;
+/**
+ * The collation a single operand contributes to a comparison, normalized.
+ * `'BINARY'` when the operand's type carries none. Provenance-blind by design:
+ * gates that compare an operand's own collation against an effective collation
+ * (covered-key detection, equi-pair extraction) care about the *name* the
+ * operand resolves under, not its rank.
+ */
+export declare function operandCollation(node: ScalarPlanNode): string;
+/**
+ * True iff an equality `left = right` is **value-discriminating**: rows it
+ * passes are genuinely value-equal on the compared operands, so the conjunct
+ * may mint value-level facts (constant pins `∅ → col`, `col1 = col2` mirror
+ * FDs, equivalence classes, constant bindings, join equi-pairs).
+ *
+ * Rule (the soundness gate from ticket
+ * `collation-blind-equality-fact-extraction`):
+ *   - non-textual operands: always — collation does not apply to non-text
+ *     comparisons (`compareSqlValuesFast` only consults the collation function
+ *     for text/text; cross-class comparisons order by storage class);
+ *   - textual (or statically unknown) operands: every collation either
+ *     operand could contribute must be BINARY. A NOCASE/RTRIM comparison
+ *     passes value-DIFFERENT rows ('Bob' = 'bob' NOCASE), so any value-level
+ *     fact minted from it over-claims.
+ *
+ * Both sides are checked (not just `effectiveComparisonCollation`'s lattice
+ * winner) so the gate stays robust to per-algorithm resolution-order
+ * differences among runtime comparison sites (the merge/bloom join emitters
+ * resolve per-key from one side's attribute type). Note this deliberately
+ * blocks on a *defaulted* non-BINARY contribution too (session
+ * `default_collation`), which the lattice would also resolve to.
+ */
+export declare function isValueDiscriminatingEquality(left: ScalarPlanNode, right: ScalarPlanNode): boolean;
+/**
+ * Per-column declared metadata consumed by the schema-level (AST) variant of
+ * the value-discrimination gate. `ColumnSchema` is structurally assignable;
+ * unit tests construct minimal literals. Absent collation means BINARY; absent
+ * logical type means textuality unknown (treated as textual).
+ */
+export interface DeclaredColumnInfo {
+    readonly collation?: string;
+    readonly logicalType?: LogicalType;
+}
+/**
+ * Schema-level (AST + declared column metadata) variant of
+ * {@link isValueDiscriminatingEquality}, for fact producers that run on raw
+ * AST before any plan nodes exist (`check-extraction.ts`, assertion hoist).
+ *
+ * Mirrors **enforcement** semantics: write-time CHECK / assertion evaluation
+ * resolves declared column collations (constraint-builder threads
+ * `collationName` into the CHECK scope types) plus explicit COLLATE wrappers —
+ * so the comparison a declared constraint actually enforces is
+ * value-discriminating exactly when every collation either operand could
+ * contribute is BINARY, or both operands are statically non-textual.
+ *
+ * Used for ALL value-level CHECK contributions — equality facts (FDs, EC
+ * pairs, constant pins/bindings) AND domain facts (ranges, BETWEEN, IN enums):
+ * a text-typed domain extracted from a non-BINARY enforcement comparison
+ * over-claims just like an equality fact (`check (c in ('a','b'))` under
+ * NOCASE admits 'A'). Guard *scopes* are not gated here — discharge soundness
+ * lives in `buildPredicateFacts`' per-conjunct gate, which assumes guard
+ * scopes are evaluated under declared collations (true of enforcement).
+ */
+export declare function isValueDiscriminatingAstComparison(left: AST.Expression, right: AST.Expression, columnIndexMap: ReadonlyMap<string, number>, columns: ReadonlyArray<DeclaredColumnInfo>): boolean;
+//# sourceMappingURL=comparison-collation.d.ts.map

package/dist/src/planner/analysis/comparison-collation.d.ts.map

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