@omgbase/oqx 0.14.1 → 0.18.0

package/src/plan.ts

@@ -13,7 +13,7 @@
 // climbs to an enclosing scope or a named root), an `ident` in a top-level
 // `where` is unambiguously a column of the scanned rows and is safe to push. An
 // `outer` (`^name`) reference is not a row column and stays residual, and so is
-// the `$value` intrinsic (the row itself, not one of its columns) — adapters
+// the `$it` intrinsic (the row itself, not one of its columns) — adapters
 // gate idents on their known column set, which never includes it.
 
 import type { Query, Where, Expr } from "./ast.ts";
@@ -34,14 +34,15 @@ export function partitionPushable(
     if (p.kind === "scalar" && canPush(p.expr)) pushed.push(p.expr);
     else rest.push(p);
   }
-  const residual: Where | null = rest.length === 0 ? null : rest.length === 1 ? rest[0]! : { kind: "and", parts: rest };
+  if (pushed.length === 0) return { pushed, residual: where }; // nothing pushed: the where itself, span and all
+  const residual: Where | null = rest.length === 0 ? null : rest.length === 1 ? rest[0]! : { kind: "and", span: [0, 0], parts: rest };
   return { pushed, residual };
 }
 
 /** Rebuild a query to run in-memory over a plan's produced rows: scan the rows
  * root, drop pushed top-level `from`/predicates, keep projection/order/consumer. */
 export function residualQuery(query: Query, residualWhere: Where | null): Query {
-  return { ...query, source: { kind: "ident", name: ROWS_ROOT }, from: [], where: residualWhere };
+  return { ...query, source: { kind: "ident", span: [0, 0], name: ROWS_ROOT }, from: [], where: residualWhere };
 }
 
 /** A literal or binding — a value known without a row context. */

package/src/print.ts

@@ -0,0 +1,274 @@
+// The canonical printer (spec/oqx/AST.md §6): the one source text of a tree.
+// Single spaces, double-quoted strings with GRAMMAR §1 escapes, the minimal
+// parentheses the precedence table (GRAMMAR §4) needs, `select` written at the
+// top level, the connectives as the words `and` / `or` (since 0.18; `!` stays
+// `!`), every option in its canonical position. The law both spec runners
+// enforce over every fixture query:
+//
+//   strip(parse(print(parse(q)))) ≡ strip(parse(q))
+//
+// `print(parse(q)) == q` is NOT a law — the printer normalizes spelling. A
+// binding is a value, never source text: `print` throws on one; `printTemplate`
+// emits template fragments around each binding instead.
+
+import type { AstNode, Expr, Follow, OpNode, OrderSpec, Query, SelectItem, Subquery, Where } from "./ast.ts";
+import { OqxError } from "./errors.ts";
+
+/** The template form of a tree: `strings` has `count + 1` fragments; the i-th gap
+ * stands for the binding `indices[i]` of the printed tree, so a caller re-runs it
+ * as `parseTemplate(strings, count)` with the values permuted by `indices`. In a
+ * tree straight from `parseTemplate`, `indices` is `0..count-1` unless the
+ * canonical clause order moved a binding past another (`${0} collect { x: ${1} }`
+ * prints as `select x: ${1} from ${0}`). */
+export interface Template {
+  strings: string[];
+  count: number;
+  indices: number[];
+}
+
+/** The canonical source of a node. Throws (`OqxError`, stage `print`) on a binding. */
+export function print(node: AstNode): string {
+  let text = "";
+  for (const p of render(node)) {
+    if (typeof p === "number") {
+      throw new OqxError(`cannot print binding \${${p}}: a binding is a value, not source text — use printTemplate`, "print");
+    }
+    text += p;
+  }
+  return text;
+}
+
+/** The canonical source of a node as template fragments, one gap per binding. */
+export function printTemplate(node: AstNode): Template {
+  const strings: string[] = [];
+  const indices: number[] = [];
+  let current = "";
+  for (const p of render(node)) {
+    if (typeof p === "number") { strings.push(current); current = ""; indices.push(p); }
+    else current += p;
+  }
+  strings.push(current);
+  return { strings, count: indices.length, indices };
+}
+
+// Output is a list of pieces: source text, or a binding index standing where the
+// binding goes (so a template can be split exactly there).
+type Out = (string | number)[];
+
+const cat = (...xs: (string | Out)[]): Out => xs.flatMap((x) => (typeof x === "string" ? [x] : x));
+const join = (parts: Out[], sep: string): Out => parts.flatMap((p, i) => (i === 0 ? p : [sep, ...p]));
+const paren = (o: Out, yes: boolean): Out => (yes ? cat("(", o, ")") : o);
+
+// Precedence levels of GRAMMAR §4, loosest to tightest. A child is parenthesized
+// when its level is below what its position requires.
+const OR = 1, AND = 2, CMP = 3, RANGE = 4, ADD = 5, MUL = 6, UNARY = 7, POSTFIX = 8, PRIMARY = 9;
+
+function prec(e: Expr): number {
+  switch (e.kind) {
+    case "lit": case "ident": case "outer": case "binding": return PRIMARY;
+    case "member": case "call": case "required": case "op": return POSTFIX;
+    case "unary": return UNARY;
+    case "binary": return e.op === "+" || e.op === "-" ? ADD : e.op === "*" || e.op === "/" || e.op === "%" ? MUL : CMP;
+    case "in": return CMP;
+    case "range": return RANGE;
+    case "logical": return e.op === "&&" ? AND : OR;
+  }
+}
+
+function render(n: AstNode): Out {
+  switch (n.kind) {
+    case "query": return query(n);
+    case "subquery": return block(n);
+    case "op": return op(n);
+    case "follow": return follow(n);
+    case "order": return order(n);
+    case "field": case "collect": return item(n);
+    case "and": case "or": case "not": case "scalar": return where(n);
+    default: return expr(n);
+  }
+}
+
+// ---- query / bodies ---------------------------------------------------------
+
+function query(q: Query): Out {
+  // Body form for `collect` — unless the query carries body-level `from`
+  // re-projections, which only a block can hold (a second top-level `from` is a
+  // duplicate clause): then the directive form `source collect { … from E }`.
+  if (q.consumer === "collect" && q.from.length === 0) {
+    // `select` is always written — except for a leading bare item literally
+    // named `distinct`, which the keyword would swallow as the modifier.
+    const first = q.select[0];
+    const bareDistinct = !q.distinct && first?.kind === "field" && first.name === "distinct"
+      && first.expr.kind === "ident" && first.expr.name === "distinct";
+    const clauses: Out[] = [];
+    if (q.select.length > 0) {
+      const items = projection(q.select, q.values);
+      clauses.push(bareDistinct ? items : cat(`select ${q.distinct ? "distinct " : ""}`, items));
+    }
+    clauses.push(cat("from ", expr(q.source)));
+    clauses.push(...tail(q));
+    return join(clauses, " ");
+  }
+  // Directive form: `<source> <consumer> [distinct] { body }`.
+  return cat(expr(q.source), ` ${q.consumer}${q.distinct ? " distinct" : ""} `, braces(body(q)));
+}
+
+type Body = Pick<Subquery, "select" | "values" | "from" | "where" | "follow" | "orderBy" | "limit" | "offset">;
+
+// The clauses after `from` (a query) or after the projection (a block): the
+// fixed clause order, each present clause once.
+function tail(b: Omit<Body, "select" | "values">): Out[] {
+  const out: Out[] = [];
+  for (const e of b.from) out.push(cat("from ", expr(e)));
+  if (b.where) out.push(cat("where ", where(b.where)));
+  if (b.follow) out.push(follow(b.follow));
+  if (b.orderBy && b.orderBy.length > 0) out.push(cat("order by ", join(b.orderBy.map(order), ", ")));
+  if (b.limit) out.push(cat("limit ", expr(b.limit)));
+  if (b.offset) out.push(cat("offset ", expr(b.offset)));
+  return out;
+}
+
+// A block body: the projection leads without its keyword (the body's first
+// clause is always the projection, so the keyword adds nothing there).
+function body(b: Body): Out[] {
+  const clauses: Out[] = [];
+  if (b.select.length > 0) clauses.push(projection(b.select, b.values));
+  clauses.push(...tail(b));
+  return clauses;
+}
+
+function block(sub: Subquery): Out {
+  return braces(body(sub));
+}
+
+function braces(clauses: Out[]): Out {
+  return clauses.length === 0 ? ["{ }"] : cat("{ ", join(clauses, " "), " }");
+}
+
+function projection(items: SelectItem[], values: boolean): Out {
+  return cat(join(items.map(item), ", "), values ? " values" : "");
+}
+
+function item(it: SelectItem): Out {
+  // An unnamed directive item exists only under `values` (`jobs[0] values`).
+  if (it.kind === "collect") return it.name === "" ? op(it.op) : cat(`${it.name}: `, op(it.op));
+  return cat("^".repeat(it.lift), it.name === "" ? "" : `${it.name}: `, expr(it.expr));
+}
+
+function order(o: OrderSpec): Out {
+  return cat(expr(o.expr), o.desc ? " desc" : "");
+}
+
+function op(o: OpNode): Out {
+  return cat(
+    receiver(o.receiver),
+    ` ${o.op}${o.distinct ? " distinct" : ""} `,
+    block(o.sub),
+    o.countCmp ? ` ${o.countCmp.op} ${number(o.countCmp.value)}` : "",
+  );
+}
+
+function follow(f: Follow): Out {
+  const dests = join(f.destinations.map((d) => (d.kind === "op" ? op(d) : expr(d))), ", ");
+  const opts: Out[] = [];
+  if (f.where) opts.push(cat("where ", expr(f.where)));
+  if (f.frontier) opts.push(cat("frontier ", expr(f.frontier)));
+  if (f.depth !== null) opts.push([`depth ${f.depth}`]);
+  if (f.by) opts.push(cat("by ", expr(f.by)));
+  return cat(`follow${f.distinct ? " distinct" : ""} `, dests, opts.length > 0 ? cat(" { ", join(opts, " "), " }") : "");
+}
+
+// ---- where ------------------------------------------------------------------
+
+function where(w: Where): Out {
+  switch (w.kind) {
+    // The connectives print as the words (`and` / `or`, since 0.18); the symbols
+    // parse to the same nodes.
+    case "and": return join(w.parts.map((p) => paren(where(p), p.kind === "or" || p.kind === "and")), " and ");
+    case "or": return join(w.parts.map((p) => paren(where(p), p.kind === "or")), " or ");
+    case "not": {
+      const inner = w.expr;
+      // The operand of `!` is a consumer test, a group, or a scalar primary —
+      // a comparison or anything looser must be grouped (`!(a == b)`).
+      const grouped = inner.kind === "and" || inner.kind === "or" || (inner.kind === "scalar" && prec(inner.expr) < UNARY);
+      return cat("!", paren(where(inner), grouped));
+    }
+    case "scalar": return expr(w.expr);
+    case "op": return op(w);
+  }
+}
+
+// ---- expressions ------------------------------------------------------------
+
+function expr(e: Expr): Out {
+  switch (e.kind) {
+    case "lit": return [literal(e.value)];
+    case "ident": return [e.name];
+    case "outer": return ["^".repeat(e.levels) + e.name];
+    case "binding": return [e.index];
+    case "member": return cat(receiver(e.recv), `.${e.name}`);
+    case "call": {
+      const args = cat("(", join(e.args.map(expr), ", "), ")");
+      return e.recv === null ? cat(e.name, args) : cat(receiver(e.recv), `.${e.name}`, args);
+    }
+    case "unary": return cat(e.op, operand(e.expr, UNARY));
+    // Postfix, tightest: anything below postfix level is grouped (`(a + 1)!`).
+    case "required": return cat(operand(e.expr, POSTFIX), "!");
+    case "op": return op(e);
+    case "binary": {
+      const p = prec(e);
+      // Left-associative arithmetic keeps an equal-level left operand bare and
+      // groups an equal-level right one; a comparison is non-associative, so a
+      // nested comparison is grouped on either side.
+      return cat(operand(e.left, p === CMP ? p + 1 : p), ` ${e.op} `, operand(e.right, p + 1));
+    }
+    case "logical": {
+      const p = prec(e);
+      return cat(operand(e.left, p), e.op === "&&" ? " and " : " or ", operand(e.right, p + 1));
+    }
+    case "in": return cat(operand(e.left, CMP + 1), " in ", operand(e.right, CMP + 1));
+    case "range":
+      return cat(e.lo ? operand(e.lo, ADD) : "", e.exclusiveEnd ? "..." : "..", e.hi ? operand(e.hi, ADD) : "");
+  }
+}
+
+// A child expression, parenthesized when its level is below `min`.
+function operand(e: Expr, min: number): Out {
+  return paren(expr(e), prec(e) < min);
+}
+
+// The value a `.name` navigates: postfix level, and a number literal is grouped
+// too (`1.size()` would lex as a malformed number).
+function receiver(e: Expr): Out {
+  return paren(expr(e), prec(e) < POSTFIX || (e.kind === "lit" && typeof e.value === "number"));
+}
+
+function literal(v: string | number | boolean | null): string {
+  if (v === null) return "null";
+  if (typeof v === "boolean") return v ? "true" : "false";
+  if (typeof v === "number") return number(v);
+  return quote(v);
+}
+
+/** A number in the shortest round-trip form (`String(n)`); the lexer reads every
+ * spelling JavaScript produces for a finite number, including `1e+21`. */
+function number(n: number): string {
+  return String(n);
+}
+
+/** A double-quoted string literal with the GRAMMAR §1 escapes. */
+function quote(s: string): string {
+  let out = '"';
+  for (const ch of s) {
+    switch (ch) {
+      case '"': out += '\\"'; break;
+      case "\\": out += "\\\\"; break;
+      case "\n": out += "\\n"; break;
+      case "\t": out += "\\t"; break;
+      case "\r": out += "\\r"; break;
+      case "\0": out += "\\0"; break;
+      default: out += ch;
+    }
+  }
+  return out + '"';
+}

package/src/resolve.ts

@@ -0,0 +1,305 @@
+// Select-alias resolution (SEMANTICS §14). `where` may reference the same body's
+// `select` aliases, and since 0.17 a `select` item may reference the items to
+// its left; the parser keeps the surface form (so the tree can be printed back
+// and reflected on) and only VALIDATES the references, and this module performs
+// the substitution — a pure rewrite the entry points (`run`, `execute`, `oqx`,
+// `runQuery`) apply once before evaluation, so the engine and any pushdown
+// planner see an ordinary `where` and `select` over row fields. Rules:
+//   • an alias shadows a same-named row field inside `where` and in the items
+//     after it;
+//   • an alias's own name inside its own expression is the row field
+//     (`name: name.upper()` is not recursive), but a chain of aliases that
+//     comes back to one being resolved (`a: b, b: a`) is a cycle → error;
+//   • a `select` item may name only the items to its LEFT; a reference to an
+//     item to its right is an error (it is a cycle when that item refers back);
+//   • an alias whose value is a `collect`/`first`/`single { … }` block may
+//     stand alone as a where leaf (a collection in predicate position means
+//     non-empty) but not appear inside a `where` expression; in a later `select`
+//     item it inlines as a value-position directive (`boss.name`);
+//   • nested blocks (consumer bodies, follow blocks, bracket lookups) are their
+//     own scopes and are not rewritten against this body's select — each body
+//     rewrites against its own.
+//
+// Resolution is NOT idempotent (`name: name.upper() … where name` resolves to
+// `name.upper()`, whose `name` would be substituted again), so it must run
+// exactly once: the entry points do it, `Engine.run` evaluates the query as
+// given. Untouched nodes are returned by reference, so a cached query keeps the
+// identity of every block the rewrite did not reach.
+
+import type { Expr, Follow, FollowDestination, OpNode, Query, SelectItem, Subquery, Where } from "./ast.ts";
+import { OqxError } from "./errors.ts";
+
+/** How a resolution failure is reported: the parser raises its positioned parse
+ * error, the standalone entry point a plain one. */
+export type Fail = (message: string) => never;
+
+const failPlain: Fail = (message) => {
+  throw new OqxError(message, "parse");
+};
+
+/** Resolve every `where` and `select` of a query (its own and every nested
+ * block's) against the `select` of the same body. Pure: returns a new tree
+ * sharing every node the rewrite did not touch. Throws an `OqxError` (stage
+ * `parse`) for an alias cycle, a forward reference, or a block alias used
+ * inside a `where` expression — the same conditions the parser rejects, so a
+ * parsed query never throws here. */
+export function resolveAliases<T extends Query | Subquery>(node: T): T {
+  return resolveBody(node, failPlain);
+}
+
+function resolveBody<T extends Query | Subquery>(node: T, fail: Fail): T {
+  // `where` is validated and substituted against the raw select first: its
+  // cycle report follows the where's own path (`c → a → b → c`), as pinned.
+  const where = node.where === null ? null : resolveWhere(node.select, node.where, fail);
+  const where2 = where === null ? null : resolveNestedWhere(where, fail);
+  const select = resolveSelect(node.select, fail);
+  const follow = node.follow === null ? null : resolveFollow(node.follow, fail);
+  const from = mapSame(node.from, (e) => resolveExpr(e, fail));
+  const orderBy = node.orderBy === null ? null : mapSame(node.orderBy, (o) => {
+    const expr = resolveExpr(o.expr, fail);
+    return expr === o.expr ? o : { ...o, expr };
+  });
+  const limit = node.limit === null ? null : resolveExpr(node.limit, fail);
+  const offset = node.offset === null ? null : resolveExpr(node.offset, fail);
+  const source = node.kind === "query" ? resolveExpr(node.source, fail) : null;
+  const same = where2 === node.where && select === node.select && follow === node.follow && from === node.from
+    && orderBy === node.orderBy && limit === node.limit && offset === node.offset
+    && (node.kind !== "query" || source === node.source);
+  if (same) return node;
+  const out = { ...node, where: where2, select, follow, from, orderBy, limit, offset };
+  if (node.kind === "query") (out as Query).source = source!;
+  return out;
+}
+
+function resolveOp(op: OpNode, fail: Fail): OpNode {
+  const receiver = resolveExpr(op.receiver, fail);
+  const sub = resolveBody(op.sub, fail);
+  return sub === op.sub && receiver === op.receiver ? op : { ...op, receiver, sub };
+}
+
+function resolveFollow(f: Follow, fail: Fail): Follow {
+  const destinations = mapSame(f.destinations, (d: FollowDestination) => (d.kind === "op" ? resolveOp(d, fail) : resolveExpr(d, fail)));
+  const where = f.where === null ? null : resolveExpr(f.where, fail);
+  const frontier = f.frontier === null ? null : resolveExpr(f.frontier, fail);
+  const by = f.by === null ? null : resolveExpr(f.by, fail);
+  if (destinations === f.destinations && where === f.where && frontier === f.frontier && by === f.by) return f;
+  return { ...f, destinations, where, frontier, by };
+}
+
+// Nested blocks inside a where tree are their own scopes: resolve each against
+// its own select (a scalar leaf may hold a value-position directive).
+function resolveNestedWhere(w: Where, fail: Fail): Where {
+  switch (w.kind) {
+    case "and": case "or": {
+      const parts = mapSame(w.parts, (p) => resolveNestedWhere(p, fail));
+      return parts === w.parts ? w : { ...w, parts };
+    }
+    case "not": {
+      const expr = resolveNestedWhere(w.expr, fail);
+      return expr === w.expr ? w : { ...w, expr };
+    }
+    case "scalar": {
+      const expr = resolveExpr(w.expr, fail);
+      return expr === w.expr ? w : { ...w, expr };
+    }
+    case "op": return resolveOp(w, fail);
+  }
+}
+
+/** Resolve the nested blocks (value-position directives) inside an expression,
+ * each against its own select; the expression's own idents are left alone. */
+function resolveExpr(e: Expr, fail: Fail): Expr {
+  return mapExpr(e, (x) => (x.kind === "op" ? resolveOp(x, fail) : null));
+}
+
+/** Rebuild `e` bottom-up, letting `f` replace a node (return `null` to keep it;
+ * a replaced node's children are not visited — `f` owns them). Untouched nodes
+ * are returned by reference. */
+function mapExpr(e: Expr, f: (e: Expr) => Expr | null): Expr {
+  const hit = f(e);
+  if (hit !== null) return hit;
+  const go = (x: Expr): Expr => mapExpr(x, f);
+  switch (e.kind) {
+    case "member": { const recv = go(e.recv); return recv === e.recv ? e : { ...e, recv }; }
+    case "call": {
+      const recv = e.recv ? go(e.recv) : null;
+      const args = mapSame(e.args, go);
+      return recv === e.recv && args === e.args ? e : { ...e, recv, args };
+    }
+    case "unary": case "required": { const expr = go(e.expr); return expr === e.expr ? e : { ...e, expr }; }
+    case "binary": case "logical": case "in": {
+      const left = go(e.left);
+      const right = go(e.right);
+      return left === e.left && right === e.right ? e : { ...e, left, right };
+    }
+    case "range": {
+      const lo = e.lo ? go(e.lo) : null;
+      const hi = e.hi ? go(e.hi) : null;
+      return lo === e.lo && hi === e.hi ? e : { ...e, lo, hi };
+    }
+    case "op": { // the receiver is read in this scope; the block is its own scope
+      const receiver = go(e.receiver);
+      return receiver === e.receiver ? e : { ...e, receiver };
+    }
+    default: return e; // lit, ident, binding, outer
+  }
+}
+
+// An item other items may name: a `collect` item, or a named non-lift field.
+function aliasName(it: SelectItem): string | null {
+  if (it.kind === "collect") return it.name === "" ? null : it.name;
+  return it.lift === 0 && it.name !== "" ? it.name : null;
+}
+
+// The alias names an item's own expression (the receiver, for a block) mentions
+// as bare identifiers, excluding its own name (the row field).
+function aliasRefs(it: SelectItem, index: ReadonlyMap<string, number>): string[] {
+  const own = aliasName(it);
+  const out: string[] = [];
+  const visit = (e: Expr): void => {
+    mapExpr(e, (x) => {
+      if (x.kind === "ident" && x.name !== own && index.has(x.name) && !out.includes(x.name)) out.push(x.name);
+      return null;
+    });
+  };
+  visit(it.kind === "collect" ? it.op.receiver : it.expr);
+  return out;
+}
+
+/** Resolve one body's `select` items left to right (this body only; each item's
+ * nested blocks are resolved against their own select). An item's bare
+ * identifier that names an item to its left is replaced by that item's resolved
+ * value — a block alias inlines as a value-position directive — and the item's
+ * own name is the row field. A reference to an item to its right fails: as a
+ * cycle when that item refers back, else as a forward reference. Exported for
+ * the parser's validation pass. */
+export function resolveSelect(select: readonly SelectItem[], fail: Fail = failPlain): SelectItem[] {
+  const index = new Map<string, number>();
+  select.forEach((it, i) => { const n = aliasName(it); if (n !== null) index.set(n, i); });
+  if (index.size === 0) {
+    return mapSame(select as SelectItem[], (it) => resolveItemBlocks(it, fail));
+  }
+  const resolved = new Map<string, Expr>();
+  let out: SelectItem[] | null = null;
+  for (let i = 0; i < select.length; i++) {
+    const it = select[i]!;
+    const own = aliasName(it);
+    const subst = (e: Expr): Expr => mapExpr(e, (x) => {
+      if (x.kind !== "ident") return null;
+      if (x.name === own) return x;
+      const r = resolved.get(x.name);
+      if (r) return r;
+      const j = index.get(x.name);
+      if (j === undefined || j <= i) return null;
+      const back = own === null ? null : cyclePath(select, index, j, own);
+      if (back) fail(`select aliases form a cycle: ${[own, ...back].join(" → ")} — an alias cannot depend on itself`);
+      fail(`select alias '${x.name}' is used before it is defined — a select item may reference only the items to its left`);
+    });
+    let r: SelectItem;
+    if (it.kind === "collect") {
+      const receiver = subst(it.op.receiver);
+      const op = resolveOp(receiver === it.op.receiver ? it.op : { ...it.op, receiver }, fail);
+      r = op === it.op ? it : { ...it, op };
+      if (own !== null) resolved.set(own, op);
+    } else {
+      const expr = resolveExpr(subst(it.expr), fail);
+      r = expr === it.expr ? it : expr.kind === "op"
+        ? { kind: "collect", span: it.span, name: it.name, op: expr }
+        : { ...it, expr };
+      if (own !== null) resolved.set(own, expr);
+    }
+    if (r !== it) { out ??= select.slice(); out[i] = r; }
+  }
+  return out ?? (select as SelectItem[]);
+}
+
+// The nested blocks of an item, resolved against their own select.
+function resolveItemBlocks(it: SelectItem, fail: Fail): SelectItem {
+  if (it.kind === "collect") {
+    const op = resolveOp(it.op, fail);
+    return op === it.op ? it : { ...it, op };
+  }
+  const expr = resolveExpr(it.expr, fail);
+  return expr === it.expr ? it : { ...it, expr };
+}
+
+// The alias path from item `from` back to the alias `to`, if the raw reference
+// graph has one (`[b, a]` for `a: b, b: a` from `b` back to `a`).
+function cyclePath(select: readonly SelectItem[], index: ReadonlyMap<string, number>, from: number, to: string): string[] | null {
+  const seen = new Set<number>();
+  const go = (i: number, path: string[]): string[] | null => {
+    if (seen.has(i)) return null;
+    seen.add(i);
+    const it = select[i]!;
+    const name = aliasName(it)!;
+    for (const ref of aliasRefs(it, index)) {
+      if (ref === to) return [...path, name, to];
+      const hit = go(index.get(ref)!, [...path, name]);
+      if (hit) return hit;
+    }
+    return null;
+  };
+  return go(from, []);
+}
+
+/** Resolve one body's `where` against its `select` (this body only; nested
+ * blocks are left as they are). Exported for the parser's validation pass. */
+export function resolveWhere(select: readonly SelectItem[], where: Where, fail: Fail = failPlain): Where {
+  if (select.length === 0) return where;
+  const aliases = new Map<string, SelectItem>();
+  for (const it of select) {
+    const n = aliasName(it);
+    if (n !== null) aliases.set(n, it);
+  }
+  if (aliases.size === 0) return where;
+  const resolving: string[] = [];
+  const subst = (e: Expr): Expr => mapExpr(e, (x) => {
+    if (x.kind !== "ident") return null;
+    const a = aliases.get(x.name);
+    if (!a) return null;
+    if (resolving[resolving.length - 1] === x.name) return x; // its own name inside its own expression: the row field
+    if (resolving.includes(x.name)) {
+      const cycle = [...resolving.slice(resolving.indexOf(x.name)), x.name].join(" → ");
+      fail(`select aliases form a cycle: ${cycle} — an alias used in \`where\` cannot depend on itself`);
+    }
+    if (a.kind === "collect") {
+      fail(`select alias '${x.name}' is a ${a.op.op} { … } block — in \`where\` it can only stand alone as a non-empty test, not inside an expression`);
+    }
+    resolving.push(x.name);
+    const out = subst(a.expr);
+    resolving.pop();
+    return out;
+  });
+  const walk = (w: Where): Where => {
+    switch (w.kind) {
+      case "and": case "or": { const parts = mapSame(w.parts, walk); return parts === w.parts ? w : { ...w, parts }; }
+      case "not": { const expr = walk(w.expr); return expr === w.expr ? w : { ...w, expr }; }
+      case "scalar": {
+        if (w.expr.kind === "ident") {
+          const a = aliases.get(w.expr.name);
+          if (a?.kind === "collect") return a.op; // a collection in predicate position: non-empty
+        }
+        const expr = subst(w.expr);
+        return expr === w.expr ? w : { ...w, expr };
+      }
+      case "op": { // the receiver is read in this scope; the block is its own scope
+        const receiver = subst(w.receiver);
+        return receiver === w.receiver ? w : { ...w, receiver };
+      }
+    }
+  };
+  return walk(where);
+}
+
+// `map` that returns the input array itself when no element changed.
+function mapSame<T>(xs: readonly T[], f: (x: T) => T): T[] {
+  let out: T[] | null = null;
+  for (let i = 0; i < xs.length; i++) {
+    const y = f(xs[i]!);
+    if (y !== xs[i]) {
+      out ??= xs.slice();
+      out[i] = y;
+    }
+  }
+  return out ?? (xs as T[]);
+}

package/src/semantics.ts

@@ -252,7 +252,7 @@ export function parseRangeString(s: string): OqxRange | null {
 // converts it explicitly into a collection of ENTRY values, each `{ key, value }`
 // tagged (non-enumerably, so JSON/deepEqual see a plain record) so the engine
 // can recognize one: when an entry becomes a query scope, the scope's ROW is
-// the property's value (`$value`, bare names) and `$key` is scope metadata.
+// the property's value (`$it`, bare names) and `$key` is scope metadata.
 // Arrays yield numeric index keys; a Map yields its entries; null/scalars yield
 // nothing. (Arrays never expose an implicit `$key` — `entries(arr)` is how you
 // ask for the index.)

package/src/version.ts

@@ -0,0 +1,4 @@
+/** The OQX language version (`spec/oqx/VERSION`, `major.minor`) this implementation
+ * conforms to — distinct from the package's own semver, whose `major.minor` it
+ * equals. Stamped on every `toJSON` document. */
+export const LANGUAGE_VERSION = "0.18";