@omgbase/oqx 0.14.0 → 0.14.1

package/src/engine.ts

@@ -8,6 +8,12 @@
 // and `&&` evaluates strictly left to right — evaluation order is observable
 // through errors, so the engine never reorders conjuncts.)
 //
+// Nested blocks run through the optimizer (`./optimize`): each block gets a
+// `BlockPlan` the engine only EXECUTES (`access`), degrading to the plain scan
+// whenever the planned access path is unavailable at run time. The rules and
+// their semantics arguments live in `optimize/rules.ts`; `rules: []` turns the
+// optimizer off, which the conformance suite uses to compare both paths.
+//
 // Name resolution is strictly lexical and LOCAL: a bare identifier is read from
 // the current scope only, and an enclosing scope is reached solely through an
 // explicit `^name` (exactly one scope out per caret). There is no implicit
@@ -22,6 +28,8 @@ import { OqxError } from "./errors.ts";
 import {
   relate, arith, membership, truthy, compareForSort, compare, canonicalKey, makeRange, isEntry, isRange,
 } from "./semantics.ts";
+import type { BlockPlan, Correlation, Rule, RowIndex } from "./optimize/index.ts";
+import { DEFAULT_RULES, HashIndex, intersectPositions, lookupOrder, planFor, residualWithout } from "./optimize/index.ts";
 
 /** The shaped result of a top-level query, discriminated by consumer. */
 export type OqxResult =
@@ -47,10 +55,59 @@ interface Scope {
   row: unknown;
   parent: Scope | null;
   bindings: readonly unknown[];
+  run: RunState;
   lifts?: Record<string, unknown>;
   meta?: Record<string, unknown>;
 }
 
+// State that lives for exactly one `run()` (nothing here outlives it, so data
+// that changes between runs is never served stale): the rule set, the receiver
+// collections seen — by the receiver VALUE's identity, or by the block when its
+// receiver is statically stable (see `access`) — the values of invariant
+// blocks, and an optional trace sink.
+interface RunState {
+  rules: readonly Rule[];
+  bindingCount: number;
+  collections: WeakMap<object, CollectionState>;
+  stableCollections: Map<OpNode, CollectionState>;
+  memo: Map<OpNode, unknown>;
+  trace?: (event: TraceEvent) => void;
+}
+
+// A receiver collection seen during a run: its value (what `toRows` coerces and
+// what `indexFor` is asked about), how many times it was reached, its rows once
+// materialized, and per local path the index serving it and what the context
+// offered (`null`: none could be built / none was offered — the scan serves it).
+interface CollectionState {
+  value: unknown;
+  seen: number;
+  rows: unknown[] | null;
+  indexes: Map<string, RowIndex | null>;
+  contextIndexes: Map<string, RowIndex | null>;
+}
+
+/** What the optimizer did at run time (for tests and diagnostics): an index
+ * built (or taken from the context) for a collection and path, a probe that
+ * selected a bucket, a context index that answered a probe with rows directly
+ * (`lookupRows`: the collection was never materialized), a memoized invariant
+ * block reused, a consumer answered from a cardinality, or a probe that fell
+ * back to the scan. */
+export type TraceEvent =
+  | { kind: "index"; path: readonly string[]; rows: number; source: "engine" | "context" }
+  | { kind: "probe"; paths: readonly (readonly string[])[]; candidates: number }
+  | { kind: "lookup"; path: readonly string[]; candidates: number }
+  | { kind: "memo"; op: OpNode }
+  | { kind: "cardinality"; count: number }
+  | { kind: "fallback"; reason: "unstable" | "index" | "probe-value" | "not-a-collection" };
+
+export interface InMemoryEngineOptions {
+  /** The optimizer rules to apply to nested blocks (default `DEFAULT_RULES`);
+   * `[]` runs the naive scan everywhere. */
+  rules?: readonly Rule[];
+  /** Receives a `TraceEvent` for each optimizer action during `run`. */
+  trace?: (event: TraceEvent) => void;
+}
+
 const RECUR = new Set(["$depth", "$stop", "$leaf", "$frontier", "$ordinal"]);
 const KEY = "$key";
 const HARD_DEPTH_CAP = 8;
@@ -65,17 +122,26 @@ const UNBOUNDED: Bound = { offset: 0, limit: null };
 
 export class InMemoryEngine implements Engine {
   private ctx: DataContext;
+  private rules: readonly Rule[];
+  private trace: ((event: TraceEvent) => void) | undefined;
 
-  constructor(context: DataContext = new DefaultContext()) {
+  constructor(context: DataContext = new DefaultContext(), options: InMemoryEngineOptions = {}) {
     this.ctx = context;
+    this.rules = options.rules ?? DEFAULT_RULES;
+    this.trace = options.trace;
   }
 
   run(query: Query, bindings: readonly unknown[] = []): OqxResult {
-    const root: Scope = { row: null, parent: null, bindings };
-    let rows = this.rowsOf(this.evalExpr(query.source, root));
-    for (const proj of query.from) {
-      rows = rows.flatMap((r) => this.rowsOf(this.evalExpr(proj, this.child(r, root))));
-    }
+    const run: RunState = {
+      rules: this.rules,
+      bindingCount: bindings.length,
+      collections: new WeakMap(),
+      stableCollections: new Map(),
+      memo: new Map(),
+    };
+    if (this.trace) run.trace = this.trace;
+    const root: Scope = { row: null, parent: null, bindings, run };
+    const rows = this.reproject(this.rowsOf(this.evalRaw(query.source, root)), query.from, root);
 
     const bound = this.boundOf(query, root);
     if (query.follow) return this.runFollow(query, rows, root, bound);
@@ -123,7 +189,7 @@ export class InMemoryEngine implements Engine {
   // is the root. Each must be a non-negative integer.
   private boundOf(b: Pick<Subquery, "limit" | "offset">, enclosing: Scope): Bound {
     if (!b.limit && !b.offset) return UNBOUNDED;
-    const scope: Scope = enclosing.parent === null ? enclosing : { row: undefined, parent: enclosing, bindings: enclosing.bindings };
+    const scope: Scope = enclosing.parent === null ? enclosing : rowless(enclosing);
     const read = (e: Expr | undefined, word: string): number | null => {
       if (!e) return null;
       const v = this.evalExpr(e, scope);
@@ -155,7 +221,7 @@ export class InMemoryEngine implements Engine {
   // goes through this, so entries behave the same at the top level, in nested
   // blocks, as `from` re-projections, and as follow seeds.
   private enter(row: unknown, parent: Scope, extra: { lifts?: Record<string, unknown>; meta?: Record<string, unknown> } = {}): Scope {
-    const s: Scope = { row, parent, bindings: parent.bindings };
+    const s: Scope = { row, parent, bindings: parent.bindings, run: parent.run };
     if (extra.lifts) s.lifts = extra.lifts;
     if (extra.meta) s.meta = extra.meta;
     if (isEntry(row)) {
@@ -232,7 +298,7 @@ export class InMemoryEngine implements Engine {
       const rowScope = scopeFor(row);
       const raw: unknown[] = [];
       for (const dest of follow.destinations) {
-        const v = dest.kind === "op" ? this.evalCollectValue(dest, rowScope) : this.evalExpr(dest, rowScope);
+        const v = dest.kind === "op" ? this.evalCollectValue(dest, rowScope) : this.evalRaw(dest, rowScope);
         raw.push(...this.rowsOf(v));
       }
       const kept = follow.where ? raw.filter((x) => truthy(this.evalExpr(follow.where!, this.enter(x, rowScope)))) : raw;
@@ -344,12 +410,28 @@ export class InMemoryEngine implements Engine {
 
   private evalWhereOp(op: OpNode, scope: Scope): boolean {
     if (op.sub.follow) throw new OqxError("`follow` is only valid on a select-position collect { … }, not a where op", "eval");
+    const plan = this.planOf(op, scope);
+    if (!plan.invariant) return this.evalWhereOpPlanned(op, plan, scope);
+    return this.memoized(op, scope, () => this.evalWhereOpPlanned(op, plan, scope));
+  }
+
+  private evalWhereOpPlanned(op: OpNode, plan: BlockPlan, scope: Scope): boolean {
     const bound = this.boundOf(op.sub, scope);
-    if (op.op === "exists" || op.op === "none") {
-      // Unbounded: stop at the first match (dedup cannot change emptiness).
-      // Bounded: the offset/limit decide emptiness, so materialize the set.
-      const any = bound === UNBOUNDED ? this.anyMatch(op, scope) : this.opRows(op, scope, bound).length > 0;
-      return op.op === "exists" ? any : !any;
+    if (op.op === "exists" || op.op === "none" || op.op === "count") {
+      const acc = this.access(op, plan, scope);
+      let n: number;
+      if (plan.fromCardinality && acc.where === null) {
+        // Nothing left to evaluate per row: the accessed rows ARE the matched
+        // rows, and the consumer only needs their count after the bound.
+        n = boundedCount(acc.rows.length, bound);
+        scope.run.trace?.({ kind: "cardinality", count: n });
+      } else if (op.op !== "count" && bound === UNBOUNDED) {
+        // Unbounded exists/none: stop at the first match (dedup cannot change
+        // emptiness). Bounded: the offset/limit decide emptiness, so materialize.
+        n = this.anyMatch(op, scope, acc) ? 1 : 0;
+      } else n = this.opRows(op, scope, bound, acc).length;
+      if (op.op === "count") return op.countCmp ? compareCount(n, op.countCmp) : n > 0;
+      return op.op === "exists" ? n > 0 : n === 0;
     }
     if (op.op === "collect") {
       const matched = this.opRows(op, scope, bound);
@@ -367,55 +449,207 @@ export class InMemoryEngine implements Engine {
       }
       return matched.length > 0;
     }
-    if (op.op === "count") {
-      const n = this.opRows(op, scope, bound).length;
-      return op.countCmp ? compareCount(n, op.countCmp) : n > 0;
-    }
     return this.opRows(op, scope, bound).length > 0;
   }
 
   // The rows a consumer op reduces: matched → ordered → distinct → bounded.
-  private opRows(op: OpNode, scope: Scope, bound: Bound): Scope[] {
-    let scopes = this.matchRows(op, scope);
+  private opRows(op: OpNode, scope: Scope, bound: Bound, acc?: Access): Scope[] {
+    let scopes = this.matchRows(op, scope, acc);
     this.sortScopes(scopes, op.sub.orderBy);
     if (op.distinct) scopes = this.dedupByProjection(scopes, op.sub);
     return sliceBound(scopes, bound);
   }
 
-  // Short-circuiting existence check over a consumer receiver.
-  private anyMatch(op: OpNode, scope: Scope): boolean {
-    for (const s of this.iterMatchRows(op, scope)) { void s; return true; }
+  // Short-circuiting existence check: over a probe's bucket this stops at the
+  // first row that passes the residual, so `exists`/`none` never materialize it.
+  private anyMatch(op: OpNode, scope: Scope, acc?: Access): boolean {
+    for (const s of this.iterMatchRows(op, scope, acc)) { void s; return true; }
     return false;
   }
 
-  private *iterMatchRows(op: OpNode, scope: Scope): Generator<Scope> {
-    let rows = this.rowsOf(this.evalExpr(op.receiver, scope));
-    for (const proj of op.sub.from) rows = rows.flatMap((r) => this.rowsOf(this.evalExpr(proj, this.child(r, scope))));
+  // The block's accessed rows, entered as scopes under `scope`, filtered by the
+  // predicate the access left to evaluate.
+  private *iterMatchRows(op: OpNode, scope: Scope, acc?: Access): Generator<Scope> {
+    const { rows, where } = acc ?? this.access(op, this.planOf(op, scope), scope);
     for (const r of rows) {
       const s = this.enter(r, scope, { lifts: {} });
-      if (!op.sub.where || this.evalWhere(op.sub.where, s)) yield s;
+      if (!where || this.evalWhere(where, s)) yield s;
+    }
+  }
+
+  private matchRows(op: OpNode, scope: Scope, acc?: Access): Scope[] {
+    return Array.from(this.iterMatchRows(op, scope, acc));
+  }
+
+  // ---- planned access -------------------------------------------------------
+  //
+  // The engine EXECUTES a block's `BlockPlan`; the rules and the semantics
+  // argument for each live in `./optimize` (rules.ts). `access` is the one path
+  // every consumer takes to a block's rows, and whatever the plan asked for
+  // that cannot be served at run time degrades to the scan the plan started from.
+
+  private planOf(op: OpNode, scope: Scope): BlockPlan {
+    return planFor(op, scopeDepth(scope), { bindingCount: scope.run.bindingCount }, scope.run.rules);
+  }
+
+  // An invariant block (rule 2) is evaluated the first time it is reached and
+  // its value reused, by reference, for every other enclosing row.
+  private memoized<T>(op: OpNode, scope: Scope, compute: () => T): T {
+    const memo = scope.run.memo;
+    if (memo.has(op)) { scope.run.trace?.({ kind: "memo", op }); return memo.get(op) as T; }
+    const value = compute();
+    memo.set(op, value);
+    return value;
+  }
+
+  // A block's rows and the predicate left to evaluate over each. A correlated
+  // plan is served, in order of preference, by a context index that yields rows
+  // (`lookupRows` — asked on every sight: it costs nothing and the collection
+  // is never read), by a probe on the engine's own index (built on the
+  // collection's second sight, or at once for a statically stable receiver: a
+  // collection seen once is cheaper to scan than to index), else by the scan.
+  // A statically stable receiver (rule 1b) is evaluated once per run; any other
+  // is keyed by its value's identity, so a fresh array per row is never indexed.
+  private access(op: OpNode, plan: BlockPlan, scope: Scope): Access {
+    const run = scope.run;
+    let state = plan.receiverStable ? run.stableCollections.get(op) : undefined;
+    if (!state) {
+      const value = this.evalRaw(op.receiver, scope);
+      if (plan.receiverStable) run.stableCollections.set(op, (state = newCollection(value)));
+      else if (plan.correlated.length === 0) return this.scan(this.rowsOf(value), op, scope);
+      else if (value !== null && typeof value === "object") {
+        state = run.collections.get(value);
+        if (!state) run.collections.set(value, (state = newCollection(value)));
+      } else {
+        run.trace?.({ kind: "fallback", reason: "not-a-collection" });
+        return this.scan(this.rowsOf(value), op, scope);
+      }
+    }
+    state.seen++;
+    if (plan.correlated.length > 0) {
+      const direct = this.lookupRows(plan, state, scope);
+      if (direct) return direct;
+      if (state.seen >= 2 || plan.receiverStable) {
+        const probed = this.probe(plan, state, scope);
+        if (probed) return { rows: probed, where: plan.residual };
+      } else run.trace?.({ kind: "fallback", reason: "unstable" });
     }
+    return this.scan(this.materialize(state), op, scope);
   }
 
-  private matchRows(op: OpNode, scope: Scope): Scope[] {
-    return Array.from(this.iterMatchRows(op, scope));
+  // The plain scan: the rows, re-projected by `from`, with the whole `where`.
+  private scan(rows: unknown[], op: OpNode, scope: Scope): Access {
+    return { rows: this.reproject(rows, op.sub.from, scope), where: op.sub.where };
+  }
+
+  private reproject(rows: unknown[], from: readonly Expr[], scope: Scope): unknown[] {
+    for (const proj of from) rows = rows.flatMap((r) => this.rowsOf(this.evalRaw(proj, this.child(r, scope))));
+    return rows;
+  }
+
+  private materialize(state: CollectionState): unknown[] {
+    return (state.rows ??= this.rowsOf(state.value));
+  }
+
+  // A probe answered by a context index that yields rows directly, before the
+  // collection is materialized: one correlation is probed (`lookupOrder`) and
+  // every other conjunct stays in place per selected row (`residualWithout`).
+  private lookupRows(plan: BlockPlan, state: CollectionState, scope: Scope): Access | null {
+    for (const c of lookupOrder(plan)) {
+      const index = this.contextIndex(state, c);
+      if (!index?.lookupRows) continue;
+      const outer = this.outerValue(c, scope);
+      if (!outer) return null;
+      const rows = Array.from(index.lookupRows(outer.value));
+      scope.run.trace?.({ kind: "lookup", path: c.path, candidates: rows.length });
+      return { rows, where: residualWithout(plan, c) };
+    }
+    return null;
+  }
+
+  // The engine's probe: one bucket per correlation, intersected smallest-first;
+  // the candidates come back in receiver order. `null` (an index that could
+  // not be built, an outer value whose evaluation threw) leaves the scan in charge.
+  private probe(plan: BlockPlan, state: CollectionState, scope: Scope): unknown[] | null {
+    const run = scope.run;
+    const rows = this.materialize(state);
+    const buckets: (readonly number[])[] = [];
+    for (const c of plan.correlated) {
+      const index = this.indexFor(state, c, scope);
+      if (!index) { run.trace?.({ kind: "fallback", reason: "index" }); return null; }
+      const outer = this.outerValue(c, scope);
+      if (!outer) return null;
+      buckets.push(index.lookup(outer.value));
+    }
+    buckets.sort((a, b) => a.length - b.length);
+    let candidates = buckets[0]!;
+    for (let i = 1; i < buckets.length && candidates.length > 0; i++) candidates = intersectPositions(candidates, buckets[i]!);
+    run.trace?.({ kind: "probe", paths: plan.correlated.map((c) => c.path), candidates: candidates.length });
+    return candidates.map((i) => rows[i]);
+  }
+
+  // A correlation's outer side, read once in a row-less scope inside the block
+  // (as a bound is); `null` when it threw — the scan then raises it in place.
+  private outerValue(c: Correlation, scope: Scope): { value: unknown } | null {
+    try { return { value: this.evalExpr(c.outer, rowless(scope)) }; }
+    catch { scope.run.trace?.({ kind: "fallback", reason: "probe-value" }); return null; }
+  }
+
+  // The context's pre-built index on a correlation's local path, if it offers
+  // one (asked once per collection and path; a refusal is cached too).
+  private contextIndex(state: CollectionState, c: Correlation): RowIndex | null {
+    const key = pathKey(c.path);
+    let index = state.contextIndexes.get(key);
+    if (index === undefined) state.contextIndexes.set(key, (index = this.ctx.indexFor?.(state.value, c.path) ?? null));
+    return index;
+  }
+
+  // The index serving a correlation's local path: the context's, else one built
+  // here by evaluating the local expression in each row's scope — the same read
+  // the scan performs, so the keys are exactly what `==` would compare. A throw
+  // while building (a context that rejects a read) leaves the path un-indexed.
+  private indexFor(state: CollectionState, c: Correlation, scope: Scope): RowIndex | null {
+    const key = pathKey(c.path);
+    const hit = state.indexes.get(key);
+    if (hit !== undefined) return hit;
+    const rows = this.materialize(state);
+    let index = this.contextIndex(state, c);
+    let source: "context" | "engine" = "context";
+    if (!index) {
+      source = "engine";
+      const built = new HashIndex();
+      try {
+        for (let i = 0; i < rows.length; i++) built.add(this.evalExpr(c.local, this.enter(rows[i], scope)), i);
+        index = built;
+      } catch { /* un-indexed: the scan serves this path */ }
+    }
+    if (index) scope.run.trace?.({ kind: "index", path: c.path, rows: rows.length, source });
+    state.indexes.set(key, index);
+    return index;
   }
 
   // A select-position collect/first/single, optionally recursive via `follow`.
   private evalCollectValue(op: OpNode, scope: Scope): unknown {
+    const plan = this.planOf(op, scope);
+    if (!plan.invariant) return this.evalCollectValuePlanned(op, plan, scope);
+    return this.memoized(op, scope, () => this.evalCollectValuePlanned(op, plan, scope));
+  }
+
+  private evalCollectValuePlanned(op: OpNode, plan: BlockPlan, scope: Scope): unknown {
     const sub = op.sub;
     const bound = this.boundOf(sub, scope);
     let scopes: Scope[];
     if (sub.follow) {
-      let rows = this.rowsOf(this.evalExpr(op.receiver, scope));
-      for (const proj of sub.from) rows = rows.flatMap((r) => this.rowsOf(this.evalExpr(proj, this.child(r, scope))));
-      const seeds = sub.where ? rows.filter((r) => this.evalWhere(sub.where!, this.enter(r, scope, { lifts: {} }))) : rows;
+      // The seeds are the matched rows themselves (`followWalk` enters them); a
+      // follow block is never correlated, so `where` here is the whole predicate.
+      const { rows, where } = this.access(op, plan, scope);
+      const seeds = where ? rows.filter((r) => this.evalWhere(where, this.enter(r, scope, { lifts: {} }))) : rows;
       scopes = this.followWalk(seeds, sub.follow, scope).map((o) => this.enter(o.row, scope, { meta: o.meta }));
       this.sortScopes(scopes, sub.orderBy);
       if (op.distinct) scopes = this.dedupByProjection(scopes, sub);
       scopes = sliceBound(scopes, bound);
     } else {
-      scopes = this.opRows(op, scope, bound);
+      scopes = this.opRows(op, scope, bound, this.access(op, plan, scope));
     }
     switch (op.op) {
       case "collect": return scopes.map((s) => this.projectRow(sub, s));
@@ -453,7 +687,19 @@ export class InMemoryEngine implements Engine {
 
   // ---- scalar expression evaluation -----------------------------------------
 
+  // An expression as a VALUE: whatever `evalRaw` yields, with a context's lazy
+  // stand-in resolved (`DataContext.materialize`), so no operand, argument, key
+  // or projected item ever observes a value the context meant as a collection
+  // it had not read yet.
   private evalExpr(e: Expr, scope: Scope): unknown {
+    const v = this.evalRaw(e, scope);
+    return this.ctx.materialize ? this.ctx.materialize(v) : v;
+  }
+
+  // An expression as the context handed it out — for ROW POSITION only (the
+  // source, a receiver, a `from`, a `follow` destination), where the value goes
+  // straight to `toRows` / `indexFor`. Operands inside it are values (`evalExpr`).
+  private evalRaw(e: Expr, scope: Scope): unknown {
     switch (e.kind) {
       case "lit": return e.value;
       case "binding":
@@ -547,8 +793,32 @@ export class InMemoryEngine implements Engine {
 
 interface Occurrence { row: unknown; meta: Record<string, unknown>; }
 
+// A block's accessed rows and the predicate still to evaluate over each.
+interface Access { rows: unknown[]; where: Where | null; }
+
 // ---- free helpers -----------------------------------------------------------
 
+function newCollection(value: unknown): CollectionState {
+  return { value, seen: 0, rows: null, indexes: new Map(), contextIndexes: new Map() };
+}
+
+function pathKey(path: readonly string[]): string {
+  return JSON.stringify(path);
+}
+
+// A row-less scope INSIDE a block: a bare name is absent, `^name` is the
+// enclosing row — how a block's bound and a probe's outer value are read.
+function rowless(enclosing: Scope): Scope {
+  return { row: undefined, parent: enclosing, bindings: enclosing.bindings, run: enclosing.run };
+}
+
+// How many scopes out the root is (the root itself is 0).
+function scopeDepth(scope: Scope): number {
+  let d = 0;
+  for (let s = scope; s.parent !== null; s = s.parent) d++;
+  return d;
+}
+
 function isRelOp(op: string): boolean {
   return op === "==" || op === "!=" || op === "<" || op === "<=" || op === ">" || op === ">=";
 }

package/src/index.ts

@@ -31,8 +31,13 @@ export { OqxError } from "./errors.ts";
 /** The OQX spec version (`spec/oqx/VERSION`, `major.minor`) this implementation
  * conforms to — distinct from the package's own semver. */
 export const LANGUAGE_VERSION = "0.14";
-export type { OqxResult, Engine } from "./engine.ts";
+export type { OqxResult, Engine, InMemoryEngineOptions, TraceEvent } from "./engine.ts";
 export { InMemoryEngine, runQuery } from "./engine.ts";
+export type { BlockPlan, Correlation, Rule, RuleContext, RowIndex } from "./optimize/index.ts";
+export {
+  DEFAULT_RULES, correlatedEqualityProbe, stableReceiver, invariantBlock, cardinalityOnly,
+  optimizeBlock, logicalBlock, HashIndex,
+} from "./optimize/index.ts";
 export type { DataContext, CallResult, DefaultContextOptions } from "./context.ts";
 export { DefaultContext } from "./context.ts";
 export type { RegexDialect, RegexFlags } from "./regex.ts";

package/src/optimize/analysis.ts

@@ -0,0 +1,183 @@
+// Static (syntactic) analyses the rules rest on. Each answers one question
+// about an AST fragment without evaluating anything:
+//
+//   • which scopes does it READ (`readsScopeIn`) — by depth, since a bare name
+//     reads the current scope and `^name` reads exactly `levels` scopes out
+//     (SEMANTICS §2), so an expression evaluated at a known depth reads a
+//     known set of depths;
+//   • can evaluating it RAISE (`raiseFree`) — the eval errors SEMANTICS §23
+//     enumerates: a call (unknown name, bad regex, wrong receiver), `single`
+//     over several rows, an invalid `limit`/`offset`, `follow` in a where op, a
+//     range in a result, a binding out of range. Property reads are total
+//     (navigating from absent is absent); a `DataContext.get` that throws is
+//     outside this model and is caught at the points the engine relies on it
+//     (index construction, probe-value evaluation), where it degrades to a scan;
+//   • does it have SIDE EFFECTS on scopes (`hasLifts`) — a `^name:` item binds a
+//     value into an enclosing scope (§19), observable by later conjuncts.
+
+import type { Expr, Follow, OpNode, SelectItem, Subquery, Where } from "../ast.ts";
+import type { RuleContext } from "./ir.ts";
+
+// ---- scope reads --------------------------------------------------------------
+
+/** Does `e`, evaluated in a scope at depth `at` (root = 0), read any scope whose
+ * depth lies in `[1, upTo]`? Reads of the root (named roots, depth 0) and of
+ * scopes deeper than `upTo` (the fragment's own rows) do not count. */
+export function exprReadsScopeIn(e: Expr, at: number, upTo: number): boolean {
+  switch (e.kind) {
+    case "lit": case "binding": return false;
+    case "ident": return at >= 1 && at <= upTo;
+    case "outer": { const d = at - e.levels; return d >= 1 && d <= upTo; }
+    case "member": return exprReadsScopeIn(e.recv, at, upTo);
+    case "index": return exprReadsScopeIn(e.recv, at, upTo) || exprReadsScopeIn(e.index, at, upTo);
+    case "call": return (e.recv !== null && exprReadsScopeIn(e.recv, at, upTo)) || e.args.some((a) => exprReadsScopeIn(a, at, upTo));
+    case "unary": return exprReadsScopeIn(e.expr, at, upTo);
+    case "binary": case "logical": case "in": return exprReadsScopeIn(e.left, at, upTo) || exprReadsScopeIn(e.right, at, upTo);
+    case "range": return (e.lo !== null && exprReadsScopeIn(e.lo, at, upTo)) || (e.hi !== null && exprReadsScopeIn(e.hi, at, upTo));
+  }
+}
+
+export function whereReadsScopeIn(w: Where, at: number, upTo: number): boolean {
+  switch (w.kind) {
+    case "and": case "or": return w.parts.some((p) => whereReadsScopeIn(p, at, upTo));
+    case "not": return whereReadsScopeIn(w.expr, at, upTo);
+    case "scalar": return exprReadsScopeIn(w.expr, at, upTo);
+    case "op": return opReadsScopeIn(w, at, upTo);
+  }
+}
+
+/** A directive evaluated in a scope at depth `at`: its receiver is read there;
+ * its rows are scopes at `at + 1`. */
+export function opReadsScopeIn(op: OpNode, at: number, upTo: number): boolean {
+  return exprReadsScopeIn(op.receiver, at, upTo) || subReadsScopeIn(op.sub, at + 1, upTo);
+}
+
+/** A block body whose rows are scopes at depth `at`. `from` re-projections,
+ * `where`, `select`, `order by` and the bound are read in the row scope (the
+ * bound in a row-less scope at the same depth); `follow` walks occurrences at
+ * `at`, with its successor `where` one deeper (§20). */
+function subReadsScopeIn(sub: Subquery, at: number, upTo: number): boolean {
+  if (sub.from.some((e) => exprReadsScopeIn(e, at, upTo))) return true;
+  if (sub.where && whereReadsScopeIn(sub.where, at, upTo)) return true;
+  if (sub.select.some((item) => itemReadsScopeIn(item, at, upTo))) return true;
+  if (sub.orderBy?.some((o) => exprReadsScopeIn(o.expr, at, upTo))) return true;
+  if (sub.limit && exprReadsScopeIn(sub.limit, at, upTo)) return true;
+  if (sub.offset && exprReadsScopeIn(sub.offset, at, upTo)) return true;
+  return sub.follow !== null && followReadsScopeIn(sub.follow, at, upTo);
+}
+
+function itemReadsScopeIn(item: SelectItem, at: number, upTo: number): boolean {
+  return item.kind === "field" ? exprReadsScopeIn(item.expr, at, upTo) : opReadsScopeIn(item.op, at, upTo);
+}
+
+function followReadsScopeIn(f: Follow, at: number, upTo: number): boolean {
+  for (const d of f.destinations) {
+    if (d.kind === "op" ? opReadsScopeIn(d, at, upTo) : exprReadsScopeIn(d, at, upTo)) return true;
+  }
+  if (f.where && exprReadsScopeIn(f.where, at + 1, upTo)) return true;
+  if (f.frontier && exprReadsScopeIn(f.frontier, at, upTo)) return true;
+  return f.by !== null && exprReadsScopeIn(f.by, at, upTo);
+}
+
+/** Does `e` read the scope it is evaluated in (a bare identifier anywhere)? */
+export function exprReadsCurrentScope(e: Expr): boolean {
+  return exprReadsScopeIn(e, 1, 1);
+}
+
+// ---- raise freedom ------------------------------------------------------------
+
+/** Can evaluating `e` raise? Calls can (unknown function/method, regex errors,
+ * a context's own failures); a binding at or past the run's count does; nothing
+ * else in a scalar expression can (§23). */
+export function exprRaiseFree(e: Expr, ctx: RuleContext): boolean {
+  switch (e.kind) {
+    case "lit": case "ident": case "outer": return true;
+    case "binding": return e.index < ctx.bindingCount;
+    case "call": return false;
+    case "member": return exprRaiseFree(e.recv, ctx);
+    case "index": return exprRaiseFree(e.recv, ctx) && exprRaiseFree(e.index, ctx);
+    case "unary": return exprRaiseFree(e.expr, ctx);
+    case "binary": case "logical": case "in": return exprRaiseFree(e.left, ctx) && exprRaiseFree(e.right, ctx);
+    case "range": return (e.lo === null || exprRaiseFree(e.lo, ctx)) && (e.hi === null || exprRaiseFree(e.hi, ctx));
+  }
+}
+
+/** Can evaluating `w` raise, or bind a lift? A where tree is raise-free when
+ * its scalars are and its directives are raise-free (`opRaiseFree`). */
+export function whereRaiseFree(w: Where, ctx: RuleContext): boolean {
+  switch (w.kind) {
+    case "and": case "or": return w.parts.every((p) => whereRaiseFree(p, ctx));
+    case "not": return whereRaiseFree(w.expr, ctx);
+    case "scalar": return exprRaiseFree(w.expr, ctx);
+    case "op": return opRaiseFree(w, ctx);
+  }
+}
+
+/** A where-position directive that can neither raise nor bind: `exists`,
+ * `none` or `count` (never `single`, which raises on several rows; `collect`
+ * binds lifts; `first`/`single` project), without `follow` (raises in where
+ * position), without a bound (an invalid value raises), without `distinct`
+ * (dedup projects, and a projected range raises), whose receiver, `from`,
+ * `where` and `order by` (evaluated by `count`) are raise-free and which lifts
+ * nothing anywhere. */
+export function opRaiseFree(op: OpNode, ctx: RuleContext): boolean {
+  if (op.op !== "exists" && op.op !== "none" && op.op !== "count") return false;
+  const sub = op.sub;
+  if (sub.follow || sub.limit || sub.offset || op.distinct) return false;
+  if (!exprRaiseFree(op.receiver, ctx)) return false;
+  if (!sub.from.every((e) => exprRaiseFree(e, ctx))) return false;
+  if (sub.where && !whereRaiseFree(sub.where, ctx)) return false;
+  if (sub.orderBy && !sub.orderBy.every((o) => exprRaiseFree(o.expr, ctx))) return false;
+  return !opHasLifts(op);
+}
+
+// ---- lifts --------------------------------------------------------------------
+
+/** Does any `^name:` item occur anywhere inside the directive (its own select,
+ * or any nested block's)? */
+export function opHasLifts(op: OpNode): boolean {
+  return subHasLifts(op.sub);
+}
+
+function subHasLifts(sub: Subquery): boolean {
+  if (sub.select.some((item) => (item.kind === "field" ? item.lift > 0 : opHasLifts(item.op)))) return true;
+  if (sub.where && whereHasLifts(sub.where)) return true;
+  if (sub.follow?.destinations.some((d) => d.kind === "op" && opHasLifts(d))) return true;
+  return false;
+}
+
+/** Does any `^name:` item occur inside a directive of this where tree? */
+export function whereHasLifts(w: Where): boolean {
+  switch (w.kind) {
+    case "and": case "or": return w.parts.some(whereHasLifts);
+    case "not": return whereHasLifts(w.expr);
+    case "scalar": return false;
+    case "op": return opHasLifts(w);
+  }
+}
+
+// ---- local paths --------------------------------------------------------------
+
+/** The scope-metadata intrinsics: `$key` (an entry's key) and the `follow`
+ * occurrence fields. In a block's row scope these read scope metadata when it is
+ * present and fall through to the context otherwise; every other `$`-name
+ * (`$id`, `$path`, a context's own intrinsics) is always a plain `get` on the
+ * row. */
+export const SCOPE_INTRINSICS: ReadonlySet<string> = new Set(["$key", "$depth", "$stop", "$leaf", "$frontier", "$ordinal"]);
+
+/** The property path a bare identifier or member chain reads off the current
+ * row — `customer_id` → `["customer_id"]`, `meta.id` → `["meta", "id"]`,
+ * `$value` → `[]`, `$value.x` → `["x"]`, `$path` → `["$path"]` — or `null` when
+ * `e` is not such a chain or starts from a scope intrinsic (`$key`, `$depth`,
+ * …, whose value is scope metadata rather than a row property). */
+export function localPath(e: Expr): readonly string[] | null {
+  if (e.kind === "ident") {
+    if (e.name === "$value") return [];
+    return SCOPE_INTRINSICS.has(e.name) ? null : [e.name];
+  }
+  if (e.kind === "member") {
+    const head = localPath(e.recv);
+    return head === null ? null : [...head, e.name];
+  }
+  return null;
+}