@omgbase/oqx 0.1.0

package/src/lexer.ts

@@ -0,0 +1,175 @@
+// OQX structural lexer for the generic kernel.
+//
+// Unlike the reference lexer (which slices raw source for the CEL layer), this
+// one fully tokenizes: the parser builds an evaluable expression AST directly
+// from the token stream, so there is no source-slicing seam.
+//
+// Tagged-template bindings are lexed as first-class tokens. Each template string
+// FRAGMENT is lexed independently and a synthetic `binding` token is injected
+// between adjacent fragments. A binding therefore can never span a token or
+// alter the grammar — the prepared-statement / injection-safe property the
+// host-bindings design note calls for. (A consequence: `${x}` inside a string
+// literal does not interpolate — that fragment would be an unterminated string —
+// which is exactly the desired "interpolation is a value, never source text".)
+
+import { OqxError } from "./errors.ts";
+
+export type TokType =
+  | "ident"
+  | "kw" // from | where | select
+  | "string"
+  | "number"
+  | "lparen"
+  | "rparen"
+  | "lbrace"
+  | "rbrace"
+  | "comma"
+  | "colon"
+  | "caret" // ^ — one-scope lift marker
+  | "dot"
+  | "op" // == != <= >= < > && || ! + - * / %  (value carries the operator)
+  | "binding" // a ${…} interpolation; `index` names the value slot
+  | "eof";
+
+export interface Token {
+  type: TokType;
+  value: string;
+  pos: number;
+  index?: number; // binding tokens only
+}
+
+const KEYWORDS = new Set(["from", "where", "select"]);
+
+// Multi-char operators, longest first (the scanner tries these before singles).
+const MULTI_OPS = ["==", "!=", "<=", ">=", "&&", "||"];
+const SINGLE_OPS = new Set(["<", ">", "!", "+", "-", "*", "/", "%"]);
+
+const isIdentStart = (c: string): boolean => /[A-Za-z_$]/.test(c);
+const isIdentPart = (c: string): boolean => /[A-Za-z0-9_$]/.test(c);
+const isDigit = (c: string): boolean => c >= "0" && c <= "9";
+
+/** Lex a tagged-template call: the cooked string fragments and the count of
+ * interpolated values. Emits a single flat token stream with `binding` tokens
+ * (index 0..values-1) between fragments, terminated by `eof`. */
+export function lexTemplate(fragments: readonly string[], values: number): Token[] {
+  const tokens: Token[] = [];
+  let base = 0; // running offset across fragments + rendered `${…}` markers
+  for (let f = 0; f < fragments.length; f++) {
+    lexFragment(fragments[f]!, base, tokens);
+    base += fragments[f]!.length;
+    if (f < fragments.length - 1) {
+      // account for the value's rendered width in the display source (see rawSource)
+      const marker = `\${${f}}`;
+      tokens.push({ type: "binding", value: marker, pos: base, index: f });
+      base += marker.length;
+    }
+  }
+  if (values !== fragments.length - 1) {
+    throw new OqxError(`template arity mismatch: ${fragments.length} fragments, ${values} values`, "lex");
+  }
+  tokens.push({ type: "eof", value: "", pos: base });
+  return tokens;
+}
+
+/** Lex a plain string (no bindings) — used by the string entry point. */
+export function lexString(src: string): Token[] {
+  const tokens: Token[] = [];
+  lexFragment(src, 0, tokens);
+  tokens.push({ type: "eof", value: "", pos: src.length });
+  return tokens;
+}
+
+function lexFragment(src: string, base: number, out: Token[]): void {
+  let i = 0;
+  const n = src.length;
+  const push = (type: TokType, value: string, at: number): void => {
+    out.push({ type, value, pos: base + at });
+  };
+
+  while (i < n) {
+    const c = src[i]!;
+
+    if (c === " " || c === "\t" || c === "\n" || c === "\r") { i++; continue; }
+
+    if (c === "(") { push("lparen", c, i); i++; continue; }
+    if (c === ")") { push("rparen", c, i); i++; continue; }
+    if (c === "{") { push("lbrace", c, i); i++; continue; }
+    if (c === "}") { push("rbrace", c, i); i++; continue; }
+    if (c === ",") { push("comma", c, i); i++; continue; }
+    if (c === ":") { push("colon", c, i); i++; continue; }
+    if (c === "^") { push("caret", c, i); i++; continue; }
+
+    // `.` is a dot only when not the leading part of a number (.5) — but OQX has
+    // no leading-dot numerals, so a bare `.` is always navigation.
+    if (c === "." && !isDigit(src[i + 1] ?? "")) { push("dot", c, i); i++; continue; }
+
+    // string literal — decode into its VALUE (quotes stripped, escapes resolved).
+    if (c === '"' || c === "'") {
+      const quote = c;
+      const start = i;
+      i++;
+      let sval = "";
+      while (i < n && src[i] !== quote) {
+        if (src[i] === "\\") {
+          i++;
+          sval += unescape(src[i]);
+        } else {
+          sval += src[i];
+        }
+        i++;
+      }
+      if (i >= n) throw new OqxError(`unterminated string literal at ${base + start}`, "lex");
+      i++; // closing quote
+      out.push({ type: "string", value: sval, pos: base + start });
+      continue;
+    }
+
+    // number (integer or decimal, optional exponent)
+    if (isDigit(c) || (c === "." && isDigit(src[i + 1] ?? ""))) {
+      const start = i;
+      while (i < n && isDigit(src[i]!)) i++;
+      if (src[i] === ".") { i++; while (i < n && isDigit(src[i]!)) i++; }
+      if (src[i] === "e" || src[i] === "E") {
+        i++;
+        if (src[i] === "+" || src[i] === "-") i++;
+        while (i < n && isDigit(src[i]!)) i++;
+      }
+      push("number", src.slice(start, i), start);
+      continue;
+    }
+
+    // operators (multi-char first)
+    const two = src.slice(i, i + 2);
+    if (MULTI_OPS.includes(two)) { push("op", two, i); i += 2; continue; }
+    if (SINGLE_OPS.has(c)) { push("op", c, i); i++; continue; }
+
+    // identifier / keyword
+    if (isIdentStart(c)) {
+      const start = i;
+      i++;
+      while (i < n && isIdentPart(src[i]!)) i++;
+      const word = src.slice(start, i);
+      push(KEYWORDS.has(word) ? "kw" : "ident", word, start);
+      continue;
+    }
+
+    throw new OqxError(`unexpected character ${JSON.stringify(c)} at ${base + i}`, "lex");
+  }
+}
+
+function unescape(c: string | undefined): string {
+  switch (c) {
+    case "n": return "\n";
+    case "t": return "\t";
+    case "r": return "\r";
+    case "0": return "\0";
+    case undefined: return "";
+    default: return c; // \\, \", \', \/, and anything else → the literal char
+  }
+}
+
+/** A human-readable reconstruction of the query source, with `${N}` markers where
+ * bindings were, for error messages. */
+export function rawSource(fragments: readonly string[]): string {
+  return fragments.map((s, i) => (i < fragments.length - 1 ? `${s}\${${i}}` : s)).join("");
+}

package/src/parser.ts

@@ -0,0 +1,517 @@
+// OQX parser for the generic kernel. Parses query STRUCTURE (source chain,
+// where/select/order/follow, the where-clause boolean tree, and postfix consumer
+// directives) and, for scalar interiors, builds an evaluable expression AST with
+// an embedded Pratt parser sharing the same token cursor.
+//
+// Two design-kernel rules (see the OQX syntax notes) shape the grammar:
+//   1. Dot navigation belongs to the host object model — a receiver/source is a
+//      dotted identifier chain (or a `${…}` binding), NOT a method call.
+//   2. Whitespace directives (collect/exists/count/first/single) belong to OQX —
+//      a consumer is `<receiver> <directive> { <block> }`, never a method.
+//
+// Departure from the reference parser: top-level clauses may appear in any order,
+// so the SQL-style projection-first form `name, id from ${people} where …` is
+// accepted (the reference requires `from` first).
+
+import type { Token, TokType } from "./lexer.ts";
+import { lexTemplate, lexString } from "./lexer.ts";
+import { OqxError } from "./errors.ts";
+import type {
+  Query, Where, Expr, OpNode, Subquery, SelectItem, OrderSpec, Follow, Consumer, RelOp,
+} from "./ast.ts";
+
+const CONSUMERS = new Set<string>(["collect", "exists", "count", "first", "single"]);
+const RELOPS = new Set<string>(["==", "!=", "<", "<=", ">", ">="]);
+const CMP_OPS = new Set<string>(["==", "!=", "<", "<=", ">", ">="]);
+const ADD_OPS = new Set<string>(["+", "-"]);
+const MUL_OPS = new Set<string>(["*", "/", "%"]);
+
+/** Parse a tagged-template call into a Query. */
+export function parseTemplate(fragments: readonly string[], values: number): Query {
+  return new Parser(lexTemplate(fragments, values)).parseQuery();
+}
+
+/** Parse a plain query string (no bindings) into a Query. */
+export function parseString(src: string): Query {
+  return new Parser(lexString(src)).parseQuery();
+}
+
+interface BodyClauses {
+  froms: Expr[];
+  where: Where | null;
+  select: SelectItem[];
+  orderBy: OrderSpec[] | null;
+  follow: Follow | null;
+}
+
+class Parser {
+  private tokens: Token[];
+  private pos = 0;
+
+  constructor(tokens: Token[]) {
+    this.tokens = tokens;
+  }
+
+  // ---- cursor helpers -------------------------------------------------------
+  private peek(): Token { return this.tokens[this.pos]!; }
+  private peekAt(n: number): Token | undefined { return this.tokens[this.pos + n]; }
+  private next(): Token { return this.tokens[this.pos++]!; }
+  private at(type: TokType, value?: string): boolean {
+    const t = this.peek();
+    return t.type === type && (value === undefined || t.value === value);
+  }
+  private atOp(value: string): boolean {
+    const t = this.peek();
+    return t.type === "op" && t.value === value;
+  }
+  private fail(msg: string): never {
+    throw new OqxError(`${msg} (at offset ${this.peek().pos})`, "parse");
+  }
+
+  // ---- top level ------------------------------------------------------------
+  parseQuery(): Query {
+    // Directive form: `<receiver> <consumer> { … }` consuming the whole query.
+    const directive = this.tryOp();
+    if (directive && this.at("eof")) {
+      return {
+        source: directive.receiver,
+        from: directive.sub.from,
+        where: directive.sub.where,
+        select: directive.sub.select,
+        orderBy: directive.sub.orderBy,
+        consumer: directive.op,
+        follow: directive.sub.follow,
+      };
+    }
+    if (directive) this.fail(`unexpected ${this.tokDesc()} after the top-level directive`);
+
+    // Body form: order-flexible clauses; the first `from` is the source.
+    const body = this.parseBody(true);
+    if (!this.at("eof")) this.fail(`unexpected ${this.tokDesc()} after the query`);
+    if (body.froms.length === 0) {
+      this.fail("a query must select a source with `from <collection>`");
+    }
+    return {
+      source: body.froms[0]!,
+      from: body.froms.slice(1),
+      where: body.where,
+      select: body.select,
+      orderBy: body.orderBy,
+      consumer: "collect",
+      follow: body.follow,
+    };
+  }
+
+  private tokDesc(): string {
+    const t = this.peek();
+    return t.type === "eof" ? "end of query" : `'${t.value || t.type}'`;
+  }
+
+  // ---- clause body (shared by top level and consumer blocks) ----------------
+  private parseBody(orderByAllowed: boolean): BodyClauses {
+    const froms: Expr[] = [];
+    let where: Where | null = null;
+    let select: SelectItem[] = [];
+    let orderBy: OrderSpec[] | null = null;
+    let follow: Follow | null = null;
+    let sawWhere = false, sawSelect = false, sawOrder = false;
+
+    while (!this.at("eof") && !this.at("rbrace")) {
+      if (this.atFollow()) {
+        if (follow) this.fail("duplicate `follow` clause");
+        follow = this.parseFollow();
+        continue;
+      }
+      if (this.at("kw", "from")) {
+        this.next();
+        froms.push(this.parseValueExpr());
+        continue;
+      }
+      if (this.at("kw", "where")) {
+        if (sawWhere) this.fail("duplicate `where` clause");
+        sawWhere = true;
+        this.next();
+        where = this.parseWhere();
+        continue;
+      }
+      if (this.at("kw", "select") || this.at("caret")) {
+        if (sawSelect) this.fail("duplicate projection");
+        sawSelect = true;
+        if (this.at("kw")) this.next(); // consume `select`; a leading `^` is part of the item
+        select = this.parseSelectItems();
+        continue;
+      }
+      if (orderByAllowed && this.atOrderBy()) {
+        if (sawOrder) this.fail("duplicate `order by` clause");
+        sawOrder = true;
+        this.next(); this.next(); // `order` `by`
+        orderBy = this.parseOrderSpecs();
+        continue;
+      }
+      if (this.looksLikePredicate()) {
+        if (sawWhere) this.fail("duplicate `where` (an implicit predicate cannot follow a `where`)");
+        sawWhere = true;
+        where = this.parseWhere();
+        continue;
+      }
+      if (this.at("ident") || this.at("binding")) {
+        if (sawSelect) this.fail("duplicate projection (an implicit select cannot follow a `select`)");
+        sawSelect = true;
+        select = this.parseSelectItems();
+        continue;
+      }
+      this.fail(`unexpected ${this.tokDesc()} — expected from/where/select${orderByAllowed ? "/order by" : ""}/follow`);
+    }
+    return { froms, where, select, orderBy, follow };
+  }
+
+  // Decide, by syntactic shape only, whether a leading unkeyworded run is a
+  // predicate (→ implicit where) or a projection (→ implicit select). A depth-0
+  // comparison / && / || / `in` before any comma/colon marks a predicate; a bare
+  // reference or a `name:`/comma projection list marks a projection.
+  private looksLikePredicate(): boolean {
+    if (this.at("op")) return true; // leading unary `!` (or a stray operator)
+    if (this.at("lparen")) return true; // a grouped boolean expression
+    let depth = 0;
+    for (let i = this.pos; i < this.tokens.length; i++) {
+      const t = this.tokens[i]!;
+      if (t.type === "eof" || t.type === "rbrace") break;
+      if (depth === 0) {
+        if (t.type === "colon" || t.type === "comma") return false;
+        if (t.type === "kw") break;
+        if (t.type === "op" && (CMP_OPS.has(t.value) || t.value === "&&" || t.value === "||")) return true;
+        if (t.type === "ident" && t.value === "in") return true;
+        if (t.type === "ident" && (t.value === "order" || t.value === "follow")) {
+          const nx = this.tokens[i + 1];
+          if (nx && nx.type === "ident") break;
+        }
+      }
+      if (t.type === "lparen") depth++;
+      else if (t.type === "rparen") { if (depth === 0) break; depth--; }
+    }
+    return false;
+  }
+
+  private atOrderBy(): boolean {
+    const t = this.peek();
+    const nx = this.peekAt(1);
+    return t.type === "ident" && t.value === "order" && !!nx && nx.type === "ident" && nx.value === "by";
+  }
+
+  private atFollow(): boolean {
+    if (!this.at("ident", "follow")) return false;
+    const nx = this.peekAt(1);
+    return !!nx && (nx.type === "ident" || nx.type === "binding");
+  }
+
+  // ---- follow ---------------------------------------------------------------
+  private parseFollow(): Follow {
+    this.next(); // `follow`
+    let distinct = false;
+    if (this.at("ident", "distinct")) {
+      const nx = this.peekAt(1);
+      if (nx && (nx.type === "ident" || nx.type === "binding")) { this.next(); distinct = true; }
+    }
+    const receiver = this.parseReceiver();
+    const follow: Follow = { receiver, distinct, where: null, frontier: null, depth: null, by: null };
+    if (!this.at("lbrace")) return follow;
+    this.next(); // '{'
+    while (!this.at("eof") && !this.at("rbrace")) {
+      if (this.at("kw", "where")) {
+        if (follow.where) this.fail("duplicate `where` in follow clause");
+        this.next();
+        follow.where = this.parseValueExpr();
+      } else if (this.at("ident", "frontier")) {
+        if (follow.frontier) this.fail("duplicate `frontier` in follow clause");
+        this.next();
+        follow.frontier = this.parseValueExpr();
+      } else if (this.at("ident", "by")) {
+        if (follow.by !== null) this.fail("duplicate `by` in follow clause");
+        this.next();
+        follow.by = this.parseValueExpr();
+      } else if (this.at("ident", "depth")) {
+        if (follow.depth !== null) this.fail("duplicate `depth` in follow clause");
+        this.next();
+        if (!this.at("number")) this.fail("expected an integer after `depth`");
+        const v = Number(this.next().value);
+        if (!Number.isInteger(v) || v < 1 || v > 8) this.fail("follow depth must be an integer between 1 and 8");
+        follow.depth = v;
+      } else {
+        this.fail(`unexpected ${this.tokDesc()} in follow block — expected where/frontier/depth/by`);
+      }
+    }
+    if (!this.at("rbrace")) this.fail("expected '}' to close the follow block");
+    this.next();
+    return follow;
+  }
+
+  // A receiver/source: a `${…}` binding, or a dotted identifier navigation chain.
+  private parseReceiver(): Expr {
+    if (this.at("binding")) return { kind: "binding", index: this.next().index! };
+    if (!this.at("ident")) this.fail("expected a collection navigation (a property/relation name)");
+    return this.parseNavFrom(this.next()).expr;
+  }
+
+  private parseNavFrom(head: Token): { expr: Expr; name: string } {
+    let expr: Expr = { kind: "ident", name: head.value };
+    let name = head.value;
+    while (this.at("dot")) {
+      this.next();
+      if (!this.at("ident")) this.fail("expected an identifier after '.' in a navigation");
+      name = this.next().value;
+      expr = { kind: "member", recv: expr, name };
+    }
+    return { expr, name };
+  }
+
+  // ---- select ---------------------------------------------------------------
+  private parseSelectItems(): SelectItem[] {
+    const items = [this.parseSelectItem()];
+    while (this.at("comma")) { this.next(); items.push(this.parseSelectItem()); }
+    return items;
+  }
+
+  private parseSelectItem(): SelectItem {
+    // Leading `^`s mark a lift; the count is how many scopes out it binds.
+    let lift = 0;
+    while (this.at("caret")) { this.next(); lift++; }
+    if (!this.at("ident")) this.fail("expected a projection name");
+    const nameTok = this.next();
+    if (this.at("colon")) {
+      this.next();
+      const name = nameTok.value;
+      const op = this.tryOp();
+      if (op) {
+        if (op.op !== "collect" && op.op !== "first" && op.op !== "single") {
+          this.fail(`projection '${name}' must use collect/first/single, not ${op.op}`);
+        }
+        if (lift) this.fail(`a lift (^${name}) value must be a scalar expression, not ${op.op} { … }`);
+        return { kind: "collect", name, op };
+      }
+      const expr = this.parseValueExpr();
+      return { kind: "field", name, expr, lift };
+    }
+    // bare/dotted projection: key defaults to the last navigation segment.
+    const { expr, name } = this.parseNavFrom(nameTok);
+    return { kind: "field", name, expr, lift };
+  }
+
+  // ---- order by -------------------------------------------------------------
+  private parseOrderSpecs(): OrderSpec[] {
+    const specs = [this.parseOrderSpec()];
+    while (this.at("comma")) { this.next(); specs.push(this.parseOrderSpec()); }
+    return specs;
+  }
+
+  private parseOrderSpec(): OrderSpec {
+    const expr = this.parseValueExpr();
+    let desc = false;
+    if (this.at("ident", "asc")) this.next();
+    else if (this.at("ident", "desc")) { this.next(); desc = true; }
+    return { expr, desc };
+  }
+
+  // ---- where boolean tree: or → and → not → primary -------------------------
+  private parseWhere(): Where { return this.parseWhereOr(); }
+
+  private parseWhereOr(): Where {
+    const left = this.parseWhereAnd();
+    if (!this.atOp("||")) return left;
+    const parts = [left];
+    while (this.atOp("||")) { this.next(); parts.push(this.parseWhereAnd()); }
+    return { kind: "or", parts };
+  }
+
+  private parseWhereAnd(): Where {
+    const left = this.parseWhereNot();
+    if (!this.atOp("&&")) return left;
+    const parts = [left];
+    while (this.atOp("&&")) { this.next(); parts.push(this.parseWhereNot()); }
+    return { kind: "and", parts };
+  }
+
+  private parseWhereNot(): Where {
+    if (this.atOp("!")) { this.next(); return { kind: "not", expr: this.parseWhereNot() }; }
+    return this.parseWherePrimary();
+  }
+
+  private parseWherePrimary(): Where {
+    if (this.at("lparen")) {
+      this.next();
+      const e = this.parseWhere();
+      if (!this.at("rparen")) this.fail("expected ')' to close a grouped where expression");
+      this.next();
+      return e;
+    }
+    const op = this.tryOp();
+    if (op) return this.finishWhereOp(op);
+    const expr = this.parseCmp();
+    return { kind: "scalar", expr };
+  }
+
+  // Validate a consumer op used in where position and attach any `count { … } <op> N`.
+  private finishWhereOp(op: OpNode): OpNode {
+    if (op.op === "first" || op.op === "single") {
+      this.fail(`${op.op} { … } is a select-position lookup; in where use exists { … } or count { … } <op> N`);
+    }
+    if (op.op === "collect") {
+      const allLift = op.sub.select.length > 0 && op.sub.select.every((s) => s.kind === "field" && s.lift > 0);
+      if (!allLift) this.fail("collect { … } in where must project only ^lift values (else use exists/count)");
+    }
+    if (this.peek().type === "op" && RELOPS.has(this.peek().value)) {
+      if (op.op !== "count") this.fail(`only count { … } is comparable; '${op.op} { … } <op> N' is not valid`);
+      const relop = this.next().value as RelOp;
+      if (!this.at("number")) this.fail(`expected an integer after 'count { … } ${relop}'`);
+      const v = Number(this.next().value);
+      if (!Number.isInteger(v)) this.fail("count comparison takes an integer");
+      op.countCmp = { op: relop, value: v };
+    }
+    return op;
+  }
+
+  // Detect + parse a postfix consumer op `<receiver> <consumer> { <sub> }`.
+  // Returns null (rewinding) when the lookahead is not a consumer op.
+  private tryOp(): OpNode | null {
+    const start = this.pos;
+    let receiver: Expr;
+    if (this.at("binding")) receiver = { kind: "binding", index: this.next().index! };
+    else if (this.at("ident")) receiver = this.parseNavFrom(this.next()).expr;
+    else return null;
+
+    if (this.at("ident") && CONSUMERS.has(this.peek().value) && this.peekAt(1)?.type === "lbrace") {
+      const op = this.next().value as Consumer;
+      this.next(); // '{'
+      const sub = this.parseSubquery();
+      if (!this.at("rbrace")) this.fail(`expected '}' to close the ${op} { … } block`);
+      this.next();
+      return { kind: "op", receiver, op, sub };
+    }
+    this.pos = start;
+    return null;
+  }
+
+  private parseSubquery(): Subquery {
+    const body = this.parseBody(true);
+    return { from: body.froms, where: body.where, select: body.select, orderBy: body.orderBy, follow: body.follow };
+  }
+
+  // ---- expression Pratt parser ----------------------------------------------
+  // Value position (select/order/follow/source): full boolean+arithmetic.
+  private parseValueExpr(): Expr { return this.parseOr(); }
+
+  private parseOr(): Expr {
+    let left = this.parseAnd();
+    while (this.atOp("||")) { this.next(); left = { kind: "logical", op: "||", left, right: this.parseAnd() }; }
+    return left;
+  }
+
+  private parseAnd(): Expr {
+    let left = this.parseCmp();
+    while (this.atOp("&&")) { this.next(); left = { kind: "logical", op: "&&", left, right: this.parseCmp() }; }
+    return left;
+  }
+
+  // Comparison / membership (also the entry point for a where scalar leaf, so a
+  // where leaf never swallows the where-tree's && / ||).
+  private parseCmp(): Expr {
+    let left = this.parseAdd();
+    if (this.peek().type === "op" && CMP_OPS.has(this.peek().value)) {
+      const op = this.next().value;
+      return { kind: "binary", op, left, right: this.parseAdd() };
+    }
+    if (this.at("ident", "in")) { this.next(); return { kind: "in", left, right: this.parseAdd() }; }
+    return left;
+  }
+
+  private parseAdd(): Expr {
+    let left = this.parseMul();
+    while (this.peek().type === "op" && ADD_OPS.has(this.peek().value)) {
+      const op = this.next().value;
+      left = { kind: "binary", op, left, right: this.parseMul() };
+    }
+    return left;
+  }
+
+  private parseMul(): Expr {
+    let left = this.parseUnary();
+    while (this.peek().type === "op" && MUL_OPS.has(this.peek().value)) {
+      const op = this.next().value;
+      left = { kind: "binary", op, left, right: this.parseUnary() };
+    }
+    return left;
+  }
+
+  private parseUnary(): Expr {
+    if (this.atOp("!")) { this.next(); return { kind: "unary", op: "!", expr: this.parseUnary() }; }
+    if (this.atOp("-")) { this.next(); return { kind: "unary", op: "-", expr: this.parseUnary() }; }
+    return this.parsePostfix();
+  }
+
+  private parsePostfix(): Expr {
+    let expr = this.parsePrimary();
+    for (;;) {
+      if (this.at("dot")) {
+        this.next();
+        if (!this.at("ident")) this.fail("expected a property name after '.'");
+        const name = this.next().value;
+        if (this.at("lparen")) {
+          expr = { kind: "call", recv: expr, name, args: this.parseArgs() };
+        } else {
+          expr = { kind: "member", recv: expr, name };
+        }
+      } else if (this.at("lparen") && expr.kind === "ident") {
+        // free function call: name(args)
+        expr = { kind: "call", recv: null, name: expr.name, args: this.parseArgs() };
+      } else if (this.at("lbrace")) {
+        break; // a consumer block boundary — not part of a value expression
+      } else {
+        break;
+      }
+    }
+    return expr;
+  }
+
+  private parseArgs(): Expr[] {
+    this.next(); // '('
+    const args: Expr[] = [];
+    if (!this.at("rparen")) {
+      args.push(this.parseValueExpr());
+      while (this.at("comma")) { this.next(); args.push(this.parseValueExpr()); }
+    }
+    if (!this.at("rparen")) this.fail("expected ')' to close call arguments");
+    this.next();
+    return args;
+  }
+
+  private parsePrimary(): Expr {
+    const t = this.peek();
+    // `^name` / `^^name` — an outer reference reading `levels` scopes out. (As a
+    // select-item head `^name:` is a lift, handled in parseSelectItem; here, in
+    // expression position, `^` reads an enclosing row's field even when the
+    // current row shadows the name.)
+    if (t.type === "caret") {
+      let levels = 0;
+      while (this.at("caret")) { this.next(); levels++; }
+      if (!this.at("ident")) this.fail("expected an identifier after '^' (an outer reference)");
+      return { kind: "outer", levels, name: this.next().value };
+    }
+    if (t.type === "number") { this.next(); return { kind: "lit", value: Number(t.value) }; }
+    if (t.type === "string") { this.next(); return { kind: "lit", value: t.value }; }
+    if (t.type === "binding") { this.next(); return { kind: "binding", index: t.index! }; }
+    if (t.type === "lparen") {
+      this.next();
+      const e = this.parseValueExpr();
+      if (!this.at("rparen")) this.fail("expected ')'");
+      this.next();
+      return e;
+    }
+    if (t.type === "ident") {
+      this.next();
+      if (t.value === "true") return { kind: "lit", value: true };
+      if (t.value === "false") return { kind: "lit", value: false };
+      if (t.value === "null") return { kind: "lit", value: null };
+      return { kind: "ident", name: t.value };
+    }
+    this.fail(`unexpected ${this.tokDesc()} — expected a value`);
+  }
+}