@omgbase/oqx 0.13.0 → 0.14.1

package/dist/optimize/hash-index.js

@@ -0,0 +1,79 @@
+// A hash index over the rows of one collection, keyed under OQX equality
+// (SEMANTICS §5) — the only key discipline that makes an index probe return
+// exactly the rows a `local == value` scan would keep:
+//
+//   • absent is one value: `undefined` and `null` share a bucket;
+//   • numbers are doubles: `-0` meets `0`; `NaN` equals nothing, so a row whose
+//     key is `NaN` is never indexed and a probe for `NaN` finds nothing;
+//   • strings, booleans and bigints key by value with a type tag, so `"5"`,
+//     `5` and `true` stay apart;
+//   • objects, arrays, functions and symbols key by REFERENCE — the reference
+//     engine's `===` — never structurally.
+//
+// Buckets hold row POSITIONS in ascending order, so a probe yields rows in the
+// receiver's order (§3 and §13 — a block's rows are the receiver's, in order).
+const NONE = Object.freeze([]);
+/** The engine's own `RowIndex`: `add` every row's key in row order, then probe. */
+export class HashIndex {
+    prim = new Map();
+    refs = new Map();
+    count = 0;
+    /** Record that the row at `position` has key `value`. Positions must be
+     * added in ascending order (row order). A `NaN` key is not indexed. */
+    add(value, position) {
+        const k = primitiveKey(value);
+        if (k === null)
+            return; // NaN: equals nothing
+        const map = k === undefined ? this.refs : this.prim;
+        const key = k === undefined ? value : k;
+        let bucket = map.get(key);
+        if (!bucket)
+            map.set(key, (bucket = []));
+        bucket.push(position);
+        this.count++;
+    }
+    lookup(value) {
+        const k = primitiveKey(value);
+        if (k === null)
+            return NONE;
+        return (k === undefined ? this.refs.get(value) : this.prim.get(k)) ?? NONE;
+    }
+    /** How many rows were indexed (rows with a `NaN` key are not). */
+    get size() {
+        return this.count;
+    }
+}
+/** The tagged bucket key of a primitive, `null` for `NaN` (no key: it equals
+ * nothing), `undefined` for a reference-keyed value (object, array, function,
+ * symbol — compared by identity). Mirrors `semantics.equals`: `===` after
+ * normalizing `undefined` to `null`. */
+export function primitiveKey(v) {
+    switch (typeof v) {
+        case "undefined": return "∅"; // absent ≡ absent
+        case "object": return v === null ? "∅" : undefined;
+        case "number": return Number.isNaN(v) ? null : `n${v}`; // `${-0}` is "0": -0 meets 0
+        case "string": return `s${v}`;
+        case "boolean": return v ? "t" : "f";
+        case "bigint": return `i${v}`;
+        default: return undefined; // function, symbol: reference identity
+    }
+}
+/** Intersect two ascending position lists, ascending. */
+export function intersectPositions(a, b) {
+    const out = [];
+    let i = 0, j = 0;
+    while (i < a.length && j < b.length) {
+        const x = a[i], y = b[j];
+        if (x === y) {
+            out.push(x);
+            i++;
+            j++;
+        }
+        else if (x < y)
+            i++;
+        else
+            j++;
+    }
+    return out;
+}
+//# sourceMappingURL=hash-index.js.map

package/dist/optimize/hash-index.js.map

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

package/dist/optimize/index.d.ts

@@ -0,0 +1,8 @@
+export type { BlockPlan, Correlation, Rule, RuleContext } from "./ir.js";
+export { logicalBlock, conjunction, conjuncts, residualWithout, lookupOrder } from "./ir.js";
+export { optimizeBlock, planFor } from "./driver.js";
+export { correlatedEqualityProbe, stableReceiver, invariantBlock, cardinalityOnly, DEFAULT_RULES } from "./rules.js";
+export type { RowIndex } from "./hash-index.js";
+export { HashIndex, primitiveKey, intersectPositions } from "./hash-index.js";
+export { exprReadsScopeIn, whereReadsScopeIn, opReadsScopeIn, exprReadsCurrentScope, exprRaiseFree, whereRaiseFree, opRaiseFree, opHasLifts, whereHasLifts, localPath, SCOPE_INTRINSICS, } from "./analysis.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/optimize/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/optimize/index.ts"],"names":[],"mappings":"AAMA,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACzE,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC7F,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,uBAAuB,EAAE,cAAc,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACrH,YAAY,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC9E,OAAO,EACL,gBAAgB,EAAE,iBAAiB,EAAE,cAAc,EAAE,qBAAqB,EAC1E,aAAa,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,gBAAgB,GACnG,MAAM,eAAe,CAAC"}

package/dist/optimize/index.js

@@ -0,0 +1,11 @@
+// The optimizer: a logical plan per nested block, rules that rewrite it, a
+// driver that applies them to a fixpoint, and the equality-faithful hash index
+// the hash-probe rule executes with. See `rules.ts` for the catalog and each
+// rule's semantics argument; README "Performance: relational patterns" for the
+// user-facing summary.
+export { logicalBlock, conjunction, conjuncts, residualWithout, lookupOrder } from "./ir.js";
+export { optimizeBlock, planFor } from "./driver.js";
+export { correlatedEqualityProbe, stableReceiver, invariantBlock, cardinalityOnly, DEFAULT_RULES } from "./rules.js";
+export { HashIndex, primitiveKey, intersectPositions } from "./hash-index.js";
+export { exprReadsScopeIn, whereReadsScopeIn, opReadsScopeIn, exprReadsCurrentScope, exprRaiseFree, whereRaiseFree, opRaiseFree, opHasLifts, whereHasLifts, localPath, SCOPE_INTRINSICS, } from "./analysis.js";
+//# sourceMappingURL=index.js.map

package/dist/optimize/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/optimize/index.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,+EAA+E;AAC/E,6EAA6E;AAC7E,+EAA+E;AAC/E,uBAAuB;AAGvB,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC7F,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,uBAAuB,EAAE,cAAc,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAErH,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC9E,OAAO,EACL,gBAAgB,EAAE,iBAAiB,EAAE,cAAc,EAAE,qBAAqB,EAC1E,aAAa,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,gBAAgB,GACnG,MAAM,eAAe,CAAC"}

package/dist/optimize/ir.d.ts

@@ -0,0 +1,84 @@
+import type { Consumer, Expr, Follow, OpNode, OrderSpec, SelectItem, Where } from "../ast.js";
+/** One hoisted equality `local == outer` from the block's top-level `&&`
+ * conjunction: `local` reads only the block's row (an identifier or member
+ * chain; `path` is its property path, `[]` for `$value`), `outer` reads nothing
+ * from the block's row (outer references, bindings, literals, arithmetic over
+ * them) and cannot raise. */
+export interface Correlation {
+    readonly local: Expr;
+    readonly outer: Expr;
+    readonly path: readonly string[];
+    /** Position of the equality among `conjuncts(where)`, so a probe that
+     * answers ONE correlation (a store-backed `lookupRows`) can put the others
+     * back in their place as residual conjuncts. */
+    readonly index: number;
+}
+/** The plan for one block. `receiver`/`from`/`projection`/`orderBy`/`bound`/
+ * `consumer`/`follow`/`distinct` transcribe the AST; `correlated`/`residual`
+ * split its `where`; `receiverStable`, `invariant` and `fromCardinality` are the
+ * annotations rules add. */
+export interface BlockPlan {
+    readonly node: OpNode;
+    /** Scope depth of the ENCLOSING scope (root = 0): the receiver is read there;
+     * the block's rows are scopes at `depth + 1`. */
+    readonly depth: number;
+    readonly consumer: Consumer;
+    readonly receiver: Expr;
+    readonly from: readonly Expr[];
+    readonly where: Where | null;
+    readonly projection: {
+        readonly select: readonly SelectItem[];
+        readonly values: boolean;
+    };
+    readonly orderBy: readonly OrderSpec[] | null;
+    readonly distinct: boolean;
+    readonly bound: {
+        readonly limit: Expr | undefined;
+        readonly offset: Expr | undefined;
+    };
+    readonly follow: Follow | null;
+    /** Equalities answered by an index probe on the receiver (in conjunct order). */
+    readonly correlated: readonly Correlation[];
+    /** The conjuncts still evaluated per row once the probe has selected its
+     * bucket; equals `where` when nothing is correlated. */
+    readonly residual: Where | null;
+    /** The receiver reads nothing from any enclosing row (only the root scope
+     * and bindings), so its rows are the same for every enclosing row and can be
+     * materialized and indexed once per run. */
+    readonly receiverStable: boolean;
+    /** The whole block reads nothing from any enclosing row and has no side
+     * effects on one (no lifts): its value is the same for every enclosing row
+     * and is computed once per run. */
+    readonly invariant: boolean;
+    /** `exists`/`none`/`count` may be answered from the cardinality of the
+     * accessed rows when no residual predicate remains (nothing per row to
+     * evaluate, order, dedup or project). */
+    readonly fromCardinality: boolean;
+}
+/** What a rule may consult besides the plan. */
+export interface RuleContext {
+    /** How many positional bindings this run has (a `${i}` with `i` at or past
+     * it raises when evaluated, so it is not raise-free). */
+    readonly bindingCount: number;
+}
+/** A rewrite: return an improved plan, or `null` when the rule does not apply
+ * (or has already been applied). Rules must be idempotent on their own output. */
+export type Rule = (plan: BlockPlan, ctx: RuleContext) => BlockPlan | null;
+/** The faithful transcription of a block: a scan with every predicate residual. */
+export declare function logicalBlock(node: OpNode, depth: number): BlockPlan;
+/** Rebuild a conjunction from its remaining parts. */
+export declare function conjunction(parts: readonly Where[]): Where | null;
+/** The top-level `&&` conjuncts of a where tree (a non-`and` tree is one). */
+export declare function conjuncts(where: Where): readonly Where[];
+/** The residual when exactly ONE correlation is answered by a probe (a context
+ * index's `lookupRows`): every other conjunct, the remaining equalities
+ * included, stays in its original place. A kept equality is true by
+ * construction for the rows the probe selects and, being two reads, can neither
+ * raise nor bind, so the scan's strict left-to-right order and outcome hold. */
+export declare function residualWithout(plan: BlockPlan, answered: Correlation): Where | null;
+/** The order in which a single-correlation probe tries the plan's correlations:
+ * those whose outer side varies with the enclosing row first (a literal selects
+ * the same rows for every enclosing row and narrows nothing), each group in
+ * conjunct order. */
+export declare function lookupOrder(plan: BlockPlan): readonly Correlation[];
+//# sourceMappingURL=ir.d.ts.map

package/dist/optimize/ir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ir.d.ts","sourceRoot":"","sources":["../../src/optimize/ir.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAE9F;;;;6BAI6B;AAC7B,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC;;oDAEgD;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;4BAG4B;AAC5B,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;qDACiD;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,SAAS,IAAI,EAAE,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC;IAC1F,QAAQ,CAAC,OAAO,EAAE,SAAS,SAAS,EAAE,GAAG,IAAI,CAAC;IAC9C,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,GAAG,SAAS,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,GAAG,SAAS,CAAA;KAAE,CAAC;IACxF,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,iFAAiF;IACjF,QAAQ,CAAC,UAAU,EAAE,SAAS,WAAW,EAAE,CAAC;IAC5C;4DACwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,KAAK,GAAG,IAAI,CAAC;IAChC;;gDAE4C;IAC5C,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC;;uCAEmC;IACnC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B;;6CAEyC;IACzC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;CACnC;AAED,gDAAgD;AAChD,MAAM,WAAW,WAAW;IAC1B;6DACyD;IACzD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;kFACkF;AAClF,MAAM,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,KAAK,SAAS,GAAG,IAAI,CAAC;AAE3E,mFAAmF;AACnF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,CAoBnE;AAED,sDAAsD;AACtD,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,KAAK,EAAE,GAAG,KAAK,GAAG,IAAI,CAEjE;AAED,8EAA8E;AAC9E,wBAAgB,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,KAAK,EAAE,CAExD;AAED;;;;gFAIgF;AAChF,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,GAAG,KAAK,GAAG,IAAI,CAEpF;AAED;;;qBAGqB;AACrB,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,WAAW,EAAE,CAInE"}

package/dist/optimize/ir.js

@@ -0,0 +1,60 @@
+// The optimizer's logical representation of one nested block (an `OpNode`):
+// where its rows come from, which predicates correlate them with the enclosing
+// rows, what remains to be checked per row, how they are shaped, and how the
+// consumer reduces them. Rules rewrite a `BlockPlan`; the engine executes it.
+//
+// A plan starts as a faithful transcription of the AST (`logicalBlock`): every
+// predicate residual, nothing correlated, nothing memoized. Rules move work
+// from the per-row path into the per-run or per-probe path only when the
+// semantics argument in `rules.ts` holds; the engine's fallbacks (an index that
+// cannot be built, a receiver that is not stable) always degrade to the plain
+// scan the plan started from.
+/** The faithful transcription of a block: a scan with every predicate residual. */
+export function logicalBlock(node, depth) {
+    const sub = node.sub;
+    return {
+        node,
+        depth,
+        consumer: node.op,
+        receiver: node.receiver,
+        from: sub.from,
+        where: sub.where,
+        projection: { select: sub.select, values: sub.values ?? false },
+        orderBy: sub.orderBy,
+        distinct: node.distinct ?? false,
+        bound: { limit: sub.limit, offset: sub.offset },
+        follow: sub.follow,
+        correlated: [],
+        residual: sub.where,
+        receiverStable: false,
+        invariant: false,
+        fromCardinality: false,
+    };
+}
+/** Rebuild a conjunction from its remaining parts. */
+export function conjunction(parts) {
+    return parts.length === 0 ? null : parts.length === 1 ? parts[0] : { kind: "and", parts: [...parts] };
+}
+/** The top-level `&&` conjuncts of a where tree (a non-`and` tree is one). */
+export function conjuncts(where) {
+    return where.kind === "and" ? where.parts : [where];
+}
+/** The residual when exactly ONE correlation is answered by a probe (a context
+ * index's `lookupRows`): every other conjunct, the remaining equalities
+ * included, stays in its original place. A kept equality is true by
+ * construction for the rows the probe selects and, being two reads, can neither
+ * raise nor bind, so the scan's strict left-to-right order and outcome hold. */
+export function residualWithout(plan, answered) {
+    return plan.where ? conjunction(conjuncts(plan.where).filter((_, i) => i !== answered.index)) : null;
+}
+/** The order in which a single-correlation probe tries the plan's correlations:
+ * those whose outer side varies with the enclosing row first (a literal selects
+ * the same rows for every enclosing row and narrows nothing), each group in
+ * conjunct order. */
+export function lookupOrder(plan) {
+    const all = plan.correlated;
+    if (all.length < 2)
+        return all;
+    return [...all.filter((c) => c.outer.kind !== "lit"), ...all.filter((c) => c.outer.kind === "lit")];
+}
+//# sourceMappingURL=ir.js.map

package/dist/optimize/ir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ir.js","sourceRoot":"","sources":["../../src/optimize/ir.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,+EAA+E;AAC/E,6EAA6E;AAC7E,8EAA8E;AAC9E,EAAE;AACF,+EAA+E;AAC/E,4EAA4E;AAC5E,yEAAyE;AACzE,gFAAgF;AAChF,8EAA8E;AAC9E,8BAA8B;AAmE9B,mFAAmF;AACnF,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,KAAa;IACtD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;IACrB,OAAO;QACL,IAAI;QACJ,KAAK;QACL,QAAQ,EAAE,IAAI,CAAC,EAAE;QACjB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,UAAU,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,KAAK,EAAE;QAC/D,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,KAAK;QAChC,KAAK,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE;QAC/C,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,UAAU,EAAE,EAAE;QACd,QAAQ,EAAE,GAAG,CAAC,KAAK;QACnB,cAAc,EAAE,KAAK;QACrB,SAAS,EAAE,KAAK;QAChB,eAAe,EAAE,KAAK;KACvB,CAAC;AACJ,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,WAAW,CAAC,KAAuB;IACjD,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,EAAE,CAAC;AACzG,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,SAAS,CAAC,KAAY;IACpC,OAAO,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AACtD,CAAC;AAED;;;;gFAIgF;AAChF,MAAM,UAAU,eAAe,CAAC,IAAe,EAAE,QAAqB;IACpE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACvG,CAAC;AAED;;;qBAGqB;AACrB,MAAM,UAAU,WAAW,CAAC,IAAe;IACzC,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC;IAC5B,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC;IAC/B,OAAO,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC;AACtG,CAAC"}

package/dist/optimize/rules.d.ts

@@ -0,0 +1,8 @@
+import type { Rule } from "./ir.js";
+export declare const correlatedEqualityProbe: Rule;
+export declare const stableReceiver: Rule;
+export declare const invariantBlock: Rule;
+export declare const cardinalityOnly: Rule;
+/** The rules the engine applies by default, in order. */
+export declare const DEFAULT_RULES: readonly Rule[];
+//# sourceMappingURL=rules.d.ts.map

package/dist/optimize/rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../src/optimize/rules.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAe,IAAI,EAAe,MAAM,SAAS,CAAC;AA2B9D,eAAO,MAAM,uBAAuB,EAAE,IAgBrC,CAAC;AA6BF,eAAO,MAAM,cAAc,EAAE,IAI5B,CAAC;AAiBF,eAAO,MAAM,cAAc,EAAE,IAK5B,CAAC;AAkBF,eAAO,MAAM,eAAe,EAAE,IAM7B,CAAC;AAEF,yDAAyD;AACzD,eAAO,MAAM,aAAa,EAAE,SAAS,IAAI,EAA+E,CAAC"}

package/dist/optimize/rules.js

@@ -0,0 +1,136 @@
+// The rule catalog. Each rule states its precondition and the argument that the
+// rewritten plan is indistinguishable from the scan it replaces — same rows in
+// the same order, same lifts, same error (same message) at the same point, or
+// no error — under SEMANTICS §13's strict left-to-right `&&`.
+import { exprRaiseFree, exprReadsCurrentScope, exprReadsScopeIn, localPath, opHasLifts, opReadsScopeIn, whereHasLifts, whereRaiseFree, } from "./analysis.js";
+import { conjunction, conjuncts } from "./ir.js";
+// ---- rule 1: correlated equality → hash probe ------------------------------------
+//
+// Precondition. The block has no `from` re-projection (its rows ARE the
+// receiver's rows) and no `follow`; its `where` has no lift anywhere (a lift
+// into an enclosing scope by one row could change what the outer side reads
+// for the next row); some top-level conjunct k is `local == outer` (either
+// side) with `local` an identifier/member chain on the block's row and `outer`
+// a raise-free expression reading nothing from the block's row; and every
+// conjunct left of k is raise-free (no call, no `single`, no lift, no bound, no
+// binding past the run's count).
+//
+// Argument. The scan evaluates, per receiver row r in order, c1(r) && … &&
+// ck(r) && …, short-circuiting. The probe selects exactly the rows with
+// local(r) == outer (the index reproduces §5 equality, `outer` is evaluated
+// once because nothing in the block can change what it reads) and evaluates the
+// residual conjunction over them, in receiver order. For a selected row every
+// conjunct is evaluated as the scan would (ck is dropped: it is true by
+// construction and, being two reads, cannot raise or bind). For a row the probe
+// rejects, the scan would have evaluated c1..c(k-1) — which cannot raise or
+// bind — then ck, false, and stopped: no result, no error, no lift. So the two
+// paths keep the same rows, raise the same first error, and bind the same
+// lifts. A probe that cannot be built at run time (a receiver that is not
+// stable, an index whose construction throws) falls back to the scan itself.
+export const correlatedEqualityProbe = (plan, ctx) => {
+    if (plan.correlated.length > 0 || plan.from.length > 0 || plan.follow || !plan.where)
+        return null;
+    if (whereHasLifts(plan.where))
+        return null;
+    const correlated = [];
+    const residual = [];
+    let prefixRaiseFree = true;
+    conjuncts(plan.where).forEach((part, index) => {
+        const eq = prefixRaiseFree ? asCorrelation(part, index, ctx) : null;
+        if (eq)
+            correlated.push(eq);
+        else {
+            residual.push(part);
+            prefixRaiseFree &&= whereRaiseFree(part, ctx);
+        }
+    });
+    if (correlated.length === 0)
+        return null;
+    return { ...plan, correlated, residual: conjunction(residual) };
+};
+/** `local == outer` / `outer == local` as a correlation, else null. */
+function asCorrelation(w, index, ctx) {
+    if (w.kind !== "scalar" || w.expr.kind !== "binary" || w.expr.op !== "==")
+        return null;
+    const { left, right } = w.expr;
+    return pair(left, right, index, ctx) ?? pair(right, left, index, ctx);
+}
+function pair(local, outer, index, ctx) {
+    const path = localPath(local);
+    if (path === null)
+        return null;
+    if (exprReadsCurrentScope(outer) || !exprRaiseFree(outer, ctx))
+        return null;
+    return { local, outer, path, index };
+}
+// ---- rule 1b: a receiver stable across enclosing rows ----------------------------
+//
+// Precondition. The receiver expression, read in the enclosing scope (depth
+// `plan.depth`), reads no scope at depth 1..depth: only the root (named roots,
+// `^…^name` reaching it, or past it) and bindings.
+//
+// Argument. Such an expression yields the same value for every enclosing row
+// (evaluation is pure; the root and the bindings do not change within a run),
+// so its rows can be materialized once per run and indexed once per path. A
+// receiver that does read an enclosing row is still indexable when it happens
+// to evaluate to the same object twice (the engine keys indexes by collection
+// identity as well); a receiver that yields a fresh value per row is scanned.
+export const stableReceiver = (plan) => {
+    if (plan.receiverStable)
+        return null;
+    if (exprReadsScopeIn(plan.receiver, plan.depth, plan.depth))
+        return null;
+    return { ...plan, receiverStable: true };
+};
+// ---- rule 2: invariant nested block → evaluate once per run ----------------------
+//
+// Precondition. Nothing in the block — receiver, `from`, `where`, `select`,
+// `order by`, bound, `follow` — reads a scope at depth 1..depth (an enclosing
+// row), and the block lifts nothing (a lift is a side effect on an enclosing
+// scope that must recur per row).
+//
+// Argument. The block's value is a function of the root scope, the bindings
+// and its own rows only, all constant within a run, so every evaluation yields
+// the same value or raises the same error. The engine evaluates it the first
+// time the scan would (so an error surfaces at the same point) and returns the
+// memoized value afterwards; a run that raised never reaches a second
+// evaluation. The memoized value is shared by reference across the enclosing
+// rows that project it.
+export const invariantBlock = (plan) => {
+    if (plan.invariant)
+        return null;
+    if (opHasLifts(plan.node))
+        return null;
+    if (opReadsScopeIn(plan.node, plan.depth, plan.depth))
+        return null;
+    return { ...plan, invariant: true };
+};
+// ---- rule 3: exists / none / count from cardinality -------------------------------
+//
+// Precondition. A where-position `exists`, `none` or `count` without `distinct`
+// (dedup projects every row), without `order by` (`count` evaluates the keys),
+// without `follow`, and with nothing left to evaluate per row: either the block
+// has no `where`, or every conjunct is correlated (so the probe's bucket is the
+// matched set).
+//
+// Argument. With no residual predicate the matched rows are exactly the
+// accessed rows (§13: the receiver's rows filtered by `where`), entering a row
+// as a scope cannot raise, and the consumers only need the count after the
+// bound (§18): `count` is `boundedCount(n)`, `exists` is `boundedCount(n) > 0`,
+// `none` its negation — what the scan computes after materializing. When the
+// probe is unavailable at run time the residual is the whole `where` and the
+// engine takes the per-row path.
+export const cardinalityOnly = (plan) => {
+    if (plan.fromCardinality)
+        return null;
+    if (plan.consumer !== "exists" && plan.consumer !== "none" && plan.consumer !== "count")
+        return null;
+    if (plan.distinct || plan.orderBy || plan.follow)
+        return null;
+    if (plan.where !== null && plan.residual !== null)
+        return null;
+    return { ...plan, fromCardinality: true };
+};
+/** The rules the engine applies by default, in order. */
+export const DEFAULT_RULES = [correlatedEqualityProbe, stableReceiver, invariantBlock, cardinalityOnly];
+//# sourceMappingURL=rules.js.map

package/dist/optimize/rules.js.map

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

package/dist/parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"AAwCA,OAAO,KAAK,EACV,KAAK,EACN,MAAM,UAAU,CAAC;AAgClB,iDAAiD;AACjD,wBAAgB,aAAa,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,KAAK,CAEjF;AAED,6DAA6D;AAC7D,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAE9C"}
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"AA8CA,OAAO,KAAK,EACV,KAAK,EACN,MAAM,UAAU,CAAC;AAgClB,iDAAiD;AACjD,wBAAgB,aAAa,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,KAAK,CAEjF;AAED,6DAA6D;AAC7D,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAE9C"}

package/dist/parser.js

@@ -12,9 +12,15 @@
 // Clause order is FIXED (ADR-020). Within one clause body — the top level or a
 // consumer block — each clause appears at most once, in exactly this order:
 //
-//   select <projection>  from <source>  where <predicate>  follow <relation> {…}
+//   select <projection>  from <source>  where <predicate>  follow <dest>, … {…}
 //   order by …  limit N  offset N
 //
+// A `follow` destination is a relation of the current row (a receiver, never
+// an outer reference) or a destination block — a receiver (which MAY be an
+// outer reference, `^people`) immediately followed by `collect`/`first`/
+// `single` [`distinct`] `{ body }`, exactly the select-position directive
+// `tryOp(false)` recognizes, re-evaluated per frontier row (language 0.14).
+//
 // Every clause is optional except that a top-level body needs `from` (the
 // receiver-plus-consumer form `<receiver> <consumer> { block }` supplies the
 // source itself, so its block's `from` is an optional re-projection). Only
@@ -372,11 +378,15 @@ class Parser {
                 this.fail("expected a relation after `follow distinct` (`follow distinct <relation>`)");
             }
         }
-        if (this.at("caret")) {
-            this.fail("`follow` takes a relation of the current row (`follow <relation>`); an outer reference `^name` is not allowed there");
+        const destinations = [this.parseFollowDestination()];
+        while (this.at("comma")) {
+            this.next();
+            if (!this.at("ident") && !this.at("binding") && !this.at("caret")) {
+                this.fail("expected a relation after ',' (`follow <relation>, <relation>`)");
+            }
+            destinations.push(this.parseFollowDestination());
         }
-        const receiver = this.parseReceiver();
-        const follow = { receiver, distinct, where: null, frontier: null, depth: null, by: null };
+        const follow = { destinations, distinct, where: null, frontier: null, depth: null, by: null };
         if (!this.at("lbrace"))
             return follow;
         this.next(); // '{'
@@ -419,6 +429,50 @@ class Parser {
         this.next();
         return follow;
     }
+    // One `follow` destination. The lookahead mirrors `tryOp`: a receiver (binding,
+    // or carets + a dotted name) followed by a consumer word and `{` / `distinct {`
+    // is a destination block, parsed by `tryOp(false)` itself — but only the
+    // select-position consumers (collect/first/single) yield rows to walk; the
+    // where-position tests are rejected by name before their body is read. With
+    // no directive the tokens are re-read as a plain relation of the current row,
+    // where an outer reference is still an error (a `^name` head only makes sense
+    // as the receiver of a block, since the block is what varies per row).
+    parseFollowDestination() {
+        const start = this.pos;
+        let isReceiver = false;
+        if (this.at("binding")) {
+            this.next();
+            isReceiver = true;
+        }
+        else if (this.at("ident") || this.at("caret")) {
+            this.parseCarets();
+            if (this.at("ident")) {
+                this.parseNavFrom(this.next());
+                isReceiver = true;
+            }
+        }
+        if (isReceiver && this.at("ident") && CONSUMERS.has(this.peek().value)) {
+            const op = this.peek().value;
+            const after = this.peekAt(1);
+            const opThenBrace = after?.type === "lbrace";
+            const opDistinctBrace = after?.type === "ident" && after.value === "distinct" && this.peekAt(2)?.type === "lbrace";
+            if (opThenBrace || opDistinctBrace) {
+                if (op !== "collect" && op !== "first" && op !== "single") {
+                    this.fail(`a follow destination must use collect/first/single, not \`${op}\` (exists/none/count are where-position tests)`);
+                }
+                this.pos = start;
+                const block = this.tryOp(false);
+                if (!block)
+                    this.fail("expected a destination block (`<receiver> collect { … }`) after `follow`");
+                return block;
+            }
+        }
+        this.pos = start;
+        if (this.at("caret")) {
+            this.fail("`follow` takes a relation of the current row (`follow <relation>`); an outer reference `^name` is not allowed there — it may only head a destination block (`follow ^name collect { … }`)");
+        }
+        return this.parseReceiver();
+    }
     // A receiver/source: a `${…}` binding, or a dotted identifier navigation chain
     // whose head may be an outer reference (`^rel`, `^^root.rel`) — since a bare
     // name is the current row's own property, an enclosing row's relation or a