@omgbase/oqx 0.13.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)) {
@@ -212,15 +278,39 @@ export class InMemoryEngine implements Engine {
   //   • identity for cycle detection + `distinct` is `by <expr>` when given, else
   //     `ctx.identity(row)` (an entry's identity is its value's); identities are
   //     compared structurally via `canonicalKey`, and `$ordinal` paths compare
-  //     component-wise (`comparePath`), so `10` follows `9`.
+  //     component-wise (`comparePath`), so `10` follows `9`;
+  //   • a row's successors are the destinations' rows in source order — a plain
+  //     relation read in the row's scope, a destination block evaluated as a
+  //     select-position directive in that scope (so `^` inside it is the frontier
+  //     row and its `^people` receiver resolves one scope further out) — filtered
+  //     by the follow `where`, then unioned by identity within the step (a
+  //     recurring identity is kept once, at its first position);
+  //   • the follow `where` reads the candidate's scope hung off the FRONTIER
+  //     row's scope: a bare name is the candidate's, `^name` the row being
+  //     expanded, `^^name` the walk's enclosing scope. `frontier` and `by` read
+  //     the occurrence's own scope with `^` the enclosing scope, as the body does.
   private followWalk(seedRows: unknown[], follow: Follow, parent: Scope): Occurrence[] {
     const cap = follow.depth ?? HARD_DEPTH_CAP;
     const scopeFor = (row: unknown): Scope => this.enter(row, parent);
     const identityOf = (row: unknown): unknown =>
       follow.by ? this.evalExpr(follow.by, scopeFor(row)) : this.ctx.identity(isEntry(row) ? row.value : row);
     const succOf = (row: unknown): unknown[] => {
-      const raw = this.rowsOf(this.evalExpr(follow.receiver, scopeFor(row)));
-      return follow.where ? raw.filter((x) => truthy(this.evalExpr(follow.where!, scopeFor(x)))) : raw;
+      const rowScope = scopeFor(row);
+      const raw: unknown[] = [];
+      for (const dest of follow.destinations) {
+        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;
+      const seen = new Set<string>();
+      const out: unknown[] = [];
+      for (const x of kept) {
+        const key = canonicalKey(identityOf(x));
+        if (seen.has(key)) continue;
+        seen.add(key);
+        out.push(x);
+      }
+      return out;
     };
     const frontierHit = (row: unknown): boolean =>
       follow.frontier ? truthy(this.evalExpr(follow.frontier, scopeFor(row))) : false;
@@ -320,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);
@@ -343,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): Scope[] {
-    return Array.from(this.iterMatchRows(op, scope));
+  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);
+  }
+
+  // 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));
@@ -429,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":
@@ -523,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

@@ -30,9 +30,14 @@ 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.13";
-export type { OqxResult, Engine } from "./engine.ts";
+export const LANGUAGE_VERSION = "0.14";
+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";