@omgbase/oqx 0.15.0 → 0.20.0

package/src/parser.ts

@@ -17,20 +17,52 @@
 //
 // A `follow` destination is a relation of the current row (a receiver, never
 // an outer reference) or a destination block — a receiver (which MAY be an
-// outer reference, `^people`) immediately followed by `collect`/`first`/
-// `single` [`distinct`] `{ body }`, exactly the select-position directive
-// `tryOp(false)` recognizes, re-evaluated per frontier row (language 0.14).
+// outer reference, `^people`, or a tuple `(a, b)`) followed by `{ body }`, or
+// by `collect`/`first`/`single` [`distinct`] `{ body }`, exactly the
+// select-position directive `tryOp` recognizes, re-evaluated per frontier row.
+// Since 0.20 there is no options block: a brace after ANY destination opens
+// that destination's block, whose body admits two clauses no other block has —
+// `frontier P` and `depth n`, in the clause order after `where`.
 //
 // Every clause is optional except that a top-level body needs `from` (the
 // receiver-plus-consumer form `<receiver> <consumer> { block }` supplies the
 // source itself, so its block's `from` is an optional re-projection). Only
 // `select` may drop its keyword, and only when it is the first clause written
-// (`name, age from people`); every other clause always carries its keyword, so
-// a predicate is never implicit — a block filters with `where`. An out-of-order
-// clause is a parse error naming the order. `where` may reference the same
-// body's `select` aliases: after a body is parsed, each bare identifier in its
-// `where` that names an alias is replaced by the alias's expression (a
-// compile-time rewrite — see `inlineAliases`).
+// (`name, age from people`); every other clause always carries its keyword. A
+// BLOCK may instead lead with a predicate (since 0.17): a leading expression that
+// is syntactically a predicate — not a bare name, a dotted navigation or a lift —
+// opens a `where`-first body (`people exists { age > 50 }`); at the top level a
+// leading predicate is still an error, since `where` would precede `from`. An
+// out-of-order clause is a parse error naming the order.
+//
+// Sugar (0.17) desugars HERE, to existing nodes: `x { … }` is `x collect { … }`
+// wherever a value stands (a select item, a where leaf, a follow destination, a
+// call argument — since 0.20 without exception) and `x distinct { … }` is
+// `x collect distinct { … }` (0.20); `x[p]` is `x first { where p }`, `x[n]` is `x first { offset n }`, with a
+// trailing `!` making the first a `single` (predicate) or a `required` (index);
+// `is x` is `!!x`, `not x` is `!x`. Two shapes are new: the postfix `required`
+// (`x!`, tightest) and the identity operators `is` / `is not` (comparison
+// level). A directive may stand in value position (`jobs first { }.pay`), which
+// is how the canonical printer writes a bracket chain back. `where` may reference the same
+// body's `select` aliases: the parser VALIDATES those references (a cycle or a
+// block alias inside an expression is a parse error) but keeps the surface
+// form; `resolveAliases` (resolve.ts) substitutes them before evaluation.
+//
+// Absolute scope references (0.18) desugar HERE too: `N^name` — an unsigned
+// integer literal immediately followed by `^` — is the `outer` reference (or the
+// lift) reaching scope N, i.e. `levels = depth − N`, where `depth` is the
+// syntactic scope depth of the position being parsed (SEMANTICS §2: the root is
+// 0, a top-level row 1, a block's body one deeper than its receiver, a follow
+// `where` one deeper than the frontier row). The parser tracks that depth
+// (`this.depth`) exactly as the `visit` walk computes it; `N >= depth` is a
+// parse error. There is no new node: `print` writes the carets back.
+//
+// Every node carries its `span` — `[start, end)` in code points over the raw
+// source, from the first token that produced it to the end of the last; a
+// parenthesized operand's span includes its parentheses (spec/oqx/AST.md).
+//
+// Tuples (0.20): `(e1, e2, …)` with two or more elements is a `tuple` node — a
+// value and a receiver; one expression in parentheses stays grouping.
 //
 // Principle of least surprise, applied to the grammar: a rule a careful user
 // would not predict is a bug. Hence `!` binds tighter than comparison in every
@@ -46,12 +78,24 @@ import { lexTemplate, lexString } from "./lexer.ts";
 import { OqxError } from "./errors.ts";
 import type {
   Query, Where, Expr, OpNode, Subquery, SelectItem, OrderSpec, Follow, FollowDestination, Consumer, RelOp,
+  BinaryOp, Span,
 } from "./ast.ts";
+import { resolveSelect, resolveWhere } from "./resolve.ts";
+import { printTemplate } from "./print.ts";
 
 const CONSUMERS = new Set<string>(["collect", "exists", "none", "count", "first", "single"]);
 // The fixed clause order of a body (ADR-020). Each clause appears at most once.
-const CLAUSE_ORDER = ["select", "from", "where", "follow", "order by", "limit", "offset"] as const;
+// `frontier` is a clause of every body that has a `follow` (a destination
+// block's marks the occurrences it reaches, any other body's its seeds — 0.20);
+// `depth` is legal only in a follow destination block, and the order sentence
+// names it only there.
+const CLAUSE_ORDER = ["select", "from", "where", "frontier", "depth", "follow", "order by", "limit", "offset"] as const;
 type Clause = (typeof CLAUSE_ORDER)[number];
+const DESTINATION_ONLY: ReadonlySet<Clause> = new Set<Clause>(["depth"]);
+// The clauses a body may hold, in order.
+function clausesOf(ctx: BodyCtx): Clause[] {
+  return CLAUSE_ORDER.filter((c) => ctx.destination || !DESTINATION_ONLY.has(c));
+}
 // Contextual clause words lexed as bare idents; an open-ended range must stop
 // before them rather than consume them as its high bound.
 const CLAUSE_WORDS = new Set<string>([
@@ -75,8 +119,12 @@ interface BodyCtx {
   op: Consumer | null;
   /** Whether `^name: expr` lift items are legal: only in a where-position `collect { … }`. */
   liftsAllowed: boolean;
+  /** A `follow` destination block (0.20): the only body that admits `depth`, and
+   * the one whose `frontier` marks the occurrences it reaches (read one level out)
+   * rather than the seeds of its own `follow`. */
+  destination: boolean;
 }
-const TOP_CTX: BodyCtx = { top: true, op: null, liftsAllowed: false };
+const TOP_CTX: BodyCtx = { top: true, op: null, liftsAllowed: false, destination: false };
 
 /** Parse a tagged-template call into a Query. */
 export function parseTemplate(fragments: readonly string[], values: number): Query {
@@ -94,20 +142,45 @@ interface BodyClauses {
   select: SelectItem[];
   orderBy: OrderSpec[] | null;
   follow: Follow | null;
+  frontier: Expr | null;
+  depth: number | null;
   distinct: boolean;
   values: boolean;
   limit: Expr | null;
   offset: Expr | null;
 }
 
+// A copy of a node with another span (a parenthesized operand takes the span of
+// its parentheses).
+function withSpan<T extends { span: Span }>(node: T, span: Span): T {
+  return { ...node, span };
+}
+
 class Parser {
   private tokens: Token[];
   private pos = 0;
+  /** While a block's leading run is read speculatively as a predicate, a bare
+   * `first`/`single` leaf is not rejected on sight: the body decides after the
+   * run is classified (`rejectBareLookups`). */
+  private deferLookup = false;
+  /** The scope depth (SEMANTICS §2) at which the construct being parsed is
+   * evaluated: 0 at the root (the top-level source and bounds), 1 for a
+   * top-level row's clauses, one deeper per block body and per follow `where`.
+   * An absolute reference `N^name` reads `depth − N` scopes out. */
+  private depth = 0;
 
   constructor(tokens: Token[]) {
     this.tokens = tokens;
   }
 
+  /** Run `f` with the scope depth set to `d`, restoring it afterwards (also on
+   * the error path, so a speculative read that fails leaves the depth intact). */
+  private atDepth<T>(d: number, f: () => T): T {
+    const saved = this.depth;
+    this.depth = d;
+    try { return f(); } finally { this.depth = saved; }
+  }
+
   // ---- cursor helpers -------------------------------------------------------
   private peek(): Token { return this.tokens[this.pos]!; }
   private peekAt(n: number): Token | undefined { return this.tokens[this.pos + n]; }
@@ -123,26 +196,46 @@ class Parser {
   private fail(msg: string): never {
     throw new OqxError(`${msg} (at offset ${this.peek().pos})`, "parse");
   }
+  /** Code-point offset of the next token (the start of a node about to be parsed). */
+  private start(): number { return this.peek().pos; }
+  /** Code-point offset just past the last consumed token (the end of a node just parsed). */
+  private end(): number { return this.pos === 0 ? 0 : this.tokens[this.pos - 1]!.end; }
+  private sp(start: number): Span { return [start, this.end()]; }
 
   // ---- top level ------------------------------------------------------------
   parseQuery(): Query {
+    const start = this.start();
     // Directive form: `<receiver> <consumer> { … }` consuming the whole query.
-    const directive = this.tryOp(false);
-    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,
-        distinct: directive.distinct ?? false,
-        values: directive.sub.values ?? false,
-        ...bounds(directive.sub),
-      };
+    let directive = this.tryOp(false);
+    if (directive && !this.at("eof") && (this.at("lbracket") || this.atValueDirective())) {
+      // A longer chain whose outermost node is still a directive
+      // (`people first { } first { }` — how `people[p][0]` prints back).
+      const save = this.pos;
+      try {
+        const e = this.parsePostfix(directive);
+        if (e.kind === "op" && this.at("eof")) directive = e;
+        else this.pos = save;
+      } catch (err) {
+        if (!(err instanceof OqxError)) throw err;
+        this.pos = save;
+      }
     }
+    if (directive && this.at("eof")) return this.queryFromOp(directive, start);
     if (directive) this.fail(`unexpected ${this.tokDesc()} after the top-level directive`);
+    // A bracket chain whose outermost node is a directive is the whole query too
+    // (`people[age > 40]` ≡ `people first { where age > 40 }`). Read
+    // speculatively: anything else (a parse error, a longer expression) is the
+    // body form's business.
+    if (this.at("ident") || this.at("caret") || this.at("binding")) {
+      const save = this.pos;
+      try {
+        const e = this.parsePostfix();
+        if (e.kind === "op" && this.at("eof")) return this.queryFromOp(e, start);
+      } catch (err) {
+        if (!(err instanceof OqxError)) throw err;
+      }
+      this.pos = save;
+    }
 
     // Body form: the fixed clause list; its `from` is the source.
     const body = this.parseBody(TOP_CTX);
@@ -151,6 +244,8 @@ class Parser {
       this.fail("a query must name its source with `from <collection>` (or be `<collection> <consumer> { … }`)");
     }
     return {
+      kind: "query",
+      span: this.sp(start),
       source: body.froms[0]!,
       from: body.froms.slice(1),
       where: body.where,
@@ -158,9 +253,21 @@ class Parser {
       orderBy: body.orderBy,
       consumer: "collect",
       follow: body.follow,
+      frontier: body.frontier,
       distinct: body.distinct,
       values: body.values,
-      ...bounds(body),
+      limit: body.limit,
+      offset: body.offset,
+    };
+  }
+
+  // The whole-query form of a directive: its receiver is the source, its block
+  // the body, its consumer the query's.
+  private queryFromOp(e: OpNode, start: number): Query {
+    return {
+      kind: "query", span: this.sp(start), source: e.receiver, from: e.sub.from, where: e.sub.where, select: e.sub.select,
+      orderBy: e.sub.orderBy, consumer: e.op, follow: e.sub.follow, frontier: e.sub.frontier, distinct: e.distinct, values: e.sub.values,
+      limit: e.sub.limit, offset: e.sub.offset,
     };
   }
 
@@ -180,17 +287,23 @@ class Parser {
     let select: SelectItem[] = [];
     let orderBy: OrderSpec[] | null = null;
     let follow: Follow | null = null;
+    let frontier: Expr | null = null;
+    let depth: number | null = null;
     let distinct = false;
     let values = false;
     let limit: Expr | null = null;
     let offset: Expr | null = null;
     let stage = -1;
+    // A top-level body's row clauses (select/where/follow/order by) are read at
+    // depth 1, its source and bounds at the root (0); a block's clauses are all
+    // at the block's depth, which `parseConsumerBlock` set.
+    const rowDepth = ctx.top ? 1 : this.depth;
 
     const enter = (clause: Clause): void => {
       const idx = CLAUSE_ORDER.indexOf(clause);
       if (idx === stage) this.fail(`duplicate \`${clause}\` clause`);
       if (idx < stage) {
-        this.fail(`\`${clause}\` must come before \`${CLAUSE_ORDER[stage]}\` — OQX clause order is ${CLAUSE_ORDER.join(", ")}`);
+        this.fail(`\`${clause}\` must come before \`${CLAUSE_ORDER[stage]}\` — OQX clause order is ${clausesOf(ctx).join(", ")}`);
       }
       stage = idx;
     };
@@ -200,7 +313,7 @@ class Parser {
         enter("select");
         this.next();
         if (this.at("ident", "distinct")) { this.next(); distinct = true; }
-        ({ items: select, values } = this.parseProjection(ctx));
+        ({ items: select, values } = this.atDepth(rowDepth, () => this.parseProjection(ctx)));
         continue;
       }
       if (this.at("kw", "from")) {
@@ -212,18 +325,39 @@ class Parser {
       if (this.at("kw", "where")) {
         enter("where");
         this.next();
-        where = this.parseWhere();
+        where = this.atDepth(rowDepth, () => this.parseWhere());
+        continue;
+      }
+      // `frontier P` (0.20) — in a follow destination block the destination's
+      // own clause, read in the occurrence's scope whose parent is the walk's
+      // enclosing scope: one level OUT of the block's rows (SEMANTICS §20), so
+      // `^` there is the enclosing scope, not the frontier row. In any other
+      // body it marks the seeds of the body's own `follow` (checked below) and
+      // is read in the seed's scope, like `where`.
+      if (this.at("ident", "frontier") && this.startsValue(this.peekAt(1))) {
+        enter("frontier");
+        this.next();
+        frontier = this.atDepth(ctx.destination ? rowDepth - 1 : rowDepth, () => this.parseValueExpr());
+        continue;
+      }
+      // `depth n` — a follow destination block's own clause (0.20).
+      if (ctx.destination && this.at("ident", "depth") && this.peekAt(1)?.type === "number") {
+        enter("depth");
+        this.next();
+        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");
+        depth = v;
         continue;
       }
       if (this.atFollow()) {
         enter("follow");
-        follow = this.parseFollow();
+        follow = this.atDepth(rowDepth, () => this.parseFollow());
         continue;
       }
       if (this.atOrderBy()) {
         enter("order by");
         this.next(); this.next(); // `order` `by`
-        orderBy = this.parseOrderSpecs();
+        orderBy = this.atDepth(rowDepth, () => this.parseOrderSpecs());
         continue;
       }
       if (this.atBound()) {
@@ -240,17 +374,79 @@ class Parser {
         continue;
       }
       // A keyword-less run. Before any clause it is the projection (`select` is
-      // the one keyword that may be dropped, and only in first position); after
-      // any clause it is an error — a predicate is never implicit.
+      // the one keyword that may be dropped, and only in first position) — or,
+      // in a block, a leading predicate that opens a `where`-first body. After
+      // any clause it is an error.
       if (stage === -1 && (this.at("ident") || this.at("binding") || this.at("caret") || this.canStartValue())) {
-        enter("select");
-        ({ items: select, values } = this.parseProjection(ctx));
+        const lead = this.atDepth(rowDepth, () => this.parseLeadingRun(ctx));
+        if (lead.where) {
+          enter("where");
+          where = lead.where;
+        } else {
+          enter("select");
+          ({ items: select, values } = lead.projection!);
+        }
         continue;
       }
       this.failUnexpectedInBody(stage, ctx);
     }
-    where = this.inlineAliases(select, where);
-    return { froms, where, select, orderBy, follow, distinct, values, limit, offset };
+    // Validate the alias references of this body (cycles, a block alias inside a
+    // `where` expression, a `select` item naming an item to its right); the
+    // surface form is kept. `where` first: its cycle report follows its own path.
+    if (where) resolveWhere(select, where, (msg) => this.fail(msg));
+    resolveSelect(select, (msg) => this.fail(msg));
+    // Outside a destination block `frontier` marks the seeds of this body's walk,
+    // so it needs one.
+    if (frontier && !follow && !ctx.destination) {
+      this.fail("`frontier` needs a `follow` — a body's `frontier <expr>` marks which of its rows (the walk's seeds) are frontiers; a destination block's marks the occurrences reached through it");
+    }
+    return { froms, where, select, orderBy, follow, frontier, depth, distinct, values, limit, offset };
+  }
+
+  // The keyword-less run that opens a body. At the top level it is always the
+  // projection. In a block it is a `where`-first body when the leading expression
+  // is SYNTACTICALLY a predicate (GRAMMAR §2): the run is read as a where tree
+  // first; if that tree is predicate-shaped — anything but a bare name, a dotted
+  // navigation or a lift, with a parenthesized expression counting as a
+  // predicate — and is not the item of a `values` projection, it is the `where`.
+  // Otherwise the tokens are re-read as the projection. When both readings fail,
+  // the error that got further wins (the farthest-failure rule), so a mistake
+  // deep inside `{ jobs exists { … } }` is reported where it is.
+  private parseLeadingRun(ctx: BodyCtx): { where: Where | null; projection: { items: SelectItem[]; values: boolean } | null } {
+    if (!ctx.top) {
+      const save = this.pos;
+      const first = this.peek();
+      let w: Where | null = null;
+      let specErr: OqxError | null = null;
+      let specPos = -1;
+      this.deferLookup = true;
+      try {
+        w = this.parseWhere();
+      } catch (e) {
+        if (!(e instanceof OqxError)) throw e;
+        specErr = e;
+        specPos = this.pos;
+      } finally {
+        this.deferLookup = false;
+      }
+      if (w && predicateShaped(w, first) && !this.at("ident", "values")) {
+        if (this.at("comma")) {
+          this.fail(`a leading predicate starts a \`where\`-first body, which has no projection — write the projection first: \`{ <projection> where ${describe(w)} }\``);
+        }
+        this.rejectBareLookups(w);
+        return { where: w, projection: null };
+      }
+      this.pos = save;
+      if (specErr) {
+        try {
+          return { where: null, projection: this.parseProjection(ctx) };
+        } catch (e) {
+          if (e instanceof OqxError && this.pos < specPos) throw specErr;
+          throw e;
+        }
+      }
+    }
+    return { where: null, projection: this.parseProjection(ctx) };
   }
 
   // The error for a token that starts no clause, phrased for the mistake it most
@@ -258,8 +454,8 @@ class Parser {
   // consumer word where a whole-query directive was meant), or a stray token.
   private failUnexpectedInBody(stage: number, ctx: BodyCtx): never {
     const t = this.peek();
-    const remaining = CLAUSE_ORDER.slice(stage + 1).join("/");
     const last = stage >= 0 ? CLAUSE_ORDER[stage] : null;
+    const remaining = clausesOf(ctx).filter((c) => CLAUSE_ORDER.indexOf(c) > stage).join("/");
     const isWord = t.type === "ident" || t.type === "kw" || t.type === "binding" || t.type === "caret";
     // Punctuation, an operator, or a literal after a complete clause is a stray
     // token, not a misplaced predicate: name where the body ends. (A comma keeps
@@ -276,6 +472,11 @@ class Parser {
       if (t.value === "limit" || t.value === "offset") {
         this.fail(`unexpected '${t.value}' after \`${last}\` — a bound is a non-negative number literal, a binding, or (inside a block) an outer reference \`^name\``);
       }
+      if (t.value === "depth" && !ctx.destination) {
+        this.fail(`unexpected 'depth' after \`${last}\` — \`depth\` is a clause of a follow destination block only (\`follow <relation> { depth 2 }\`)`);
+      }
+      if (t.value === "depth") this.fail("expected an integer after `depth` (`depth 1`..`depth 8`)");
+      if (t.value === "frontier") this.fail(`unexpected 'frontier' after \`${last}\` — \`frontier\` takes an expression (\`frontier <expr>\`) and belongs to a body that has a \`follow\``);
     }
     if (last === "from" && t.type === "ident" && CONSUMERS.has(t.value)) {
       this.fail(`unexpected \`${t.value}\` after \`from\` — a whole-query consumer is written \`<collection> ${t.value} { … }\`; to project a field named ${t.value} write \`select ${t.value} from …\`; a predicate needs \`where\``);
@@ -283,10 +484,10 @@ class Parser {
     if (last === "from") {
       this.fail(`unexpected ${this.tokDesc()} after \`from\` — a predicate needs \`where\` (there is no implicit where), and a projection goes before \`from\` (\`select … from …\`); expected ${remaining}`);
     }
-    // `{ rel exists { … } }` / `{ rel count { … } >= 2 }`: the leading `rel` was
-    // read as the projection, so the consumer word is where the mistake shows.
+    // `{ name, rel exists { … } }`: the leading items were read as the projection,
+    // so the consumer word is where the mistake shows.
     if (last === "select" && t.type === "ident" && CONSUMERS.has(t.value)) {
-      this.fail(`unexpected \`${t.value}\` after a projection — a consumer test is a predicate: write \`where <relation> ${t.value} { … }\` — a predicate is never implicit; a nested block in a projection needs a name (\`name: <relation> collect { … }\`)`);
+      this.fail(`unexpected \`${t.value}\` after a projection — a consumer test is a predicate: write \`where <relation> ${t.value} { … }\` after the projection (a block may lead with a predicate only when nothing is projected); a nested block in a projection needs a name (\`name: <relation> collect { … }\`)`);
     }
     if (last === null) this.fail(`unexpected ${this.tokDesc()} — expected a projection or ${remaining}`);
     this.fail(`unexpected ${this.tokDesc()} after \`${last}\` — expected ${remaining}`);
@@ -302,74 +503,39 @@ class Parser {
     return !!nx && (nx.type === "number" || nx.type === "binding" || nx.type === "caret");
   }
 
-  // ---- alias inlining -------------------------------------------------------
-  // `where` may reference the same body's `select` aliases. This is a
-  // compile-time rewrite, not a second execution pass: every bare identifier in
-  // the where tree that names an alias is replaced by that alias's expression,
-  // so the engine and any pushdown planner see an ordinary where over row
-  // fields. Rules:
-  //   • an alias shadows a same-named row field inside `where`;
-  //   • 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;
-  //   • 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 an expression;
-  //   • nested blocks (consumer bodies, follow blocks) are their own scopes and
-  //     are not rewritten against this body's select — each body rewrites
-  //     against its own.
-  private inlineAliases(select: SelectItem[], where: Where | null): Where | null {
-    if (!where || select.length === 0) return where;
-    const aliases = new Map<string, SelectItem>();
-    for (const it of select) {
-      if (it.kind === "collect") aliases.set(it.name, it);
-      else if (it.lift === 0 && it.name !== "") aliases.set(it.name, it);
-    }
-    if (aliases.size === 0) return where;
-    const resolving: string[] = [];
-    const subst = (e: Expr): Expr => {
-      switch (e.kind) {
-        case "ident": {
-          const a = aliases.get(e.name);
-          if (!a) return e;
-          if (resolving[resolving.length - 1] === e.name) return e; // its own name inside its own expression: the row field
-          if (resolving.includes(e.name)) {
-            const cycle = [...resolving.slice(resolving.indexOf(e.name)), e.name].join(" → ");
-            this.fail(`select aliases form a cycle: ${cycle} — an alias used in \`where\` cannot depend on itself`);
-          }
-          if (a.kind === "collect") {
-            this.fail(`select alias '${e.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(e.name);
-          const out = subst(a.expr);
-          resolving.pop();
-          return out;
-        }
-        case "member": return { ...e, recv: subst(e.recv) };
-        case "index": return { ...e, recv: subst(e.recv), index: subst(e.index) };
-        case "call": return { ...e, recv: e.recv ? subst(e.recv) : null, args: e.args.map(subst) };
-        case "unary": return { ...e, expr: subst(e.expr) };
-        case "binary": case "logical": case "in": return { ...e, left: subst(e.left), right: subst(e.right) };
-        case "range": return { ...e, lo: e.lo ? subst(e.lo) : null, hi: e.hi ? subst(e.hi) : null };
-        default: return e; // lit, binding, outer (`^name` reads an enclosing row, never an alias)
-      }
-    };
-    const walk = (w: Where): Where => {
-      switch (w.kind) {
-        case "and": return { kind: "and", parts: w.parts.map(walk) };
-        case "or": return { kind: "or", parts: w.parts.map(walk) };
-        case "not": return { kind: "not", expr: walk(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
-          }
-          return { kind: "scalar", expr: subst(w.expr) };
-        }
-        case "op": return { ...w, receiver: subst(w.receiver) }; // the receiver is read in this scope; the block is its own scope
+  // Whether the token `n` ahead can head a scope reference: a `^` run, or the
+  // `N^` of an absolute reference.
+  private atScopeRefAt(n: number): boolean {
+    return this.peekAt(n)?.type === "caret" || this.atAbsoluteRefAt(n);
+  }
+
+  // `N^` — an unsigned integer literal (digits only) immediately followed by a
+  // caret, no whitespace between: an absolute scope reference (GRAMMAR §4).
+  // `1 ^x` is not one (the `^` then fails as a stray token), nor is `1.0^x`.
+  private atAbsoluteRef(): boolean { return this.atAbsoluteRefAt(0); }
+  private atAbsoluteRefAt(n: number): boolean {
+    const t = this.peekAt(n);
+    const nx = this.peekAt(n + 1);
+    return t?.type === "number" && /^\d+$/.test(t.value) && nx?.type === "caret" && nx.pos === t.end;
+  }
+
+  // The head of an outer reference or a lift: a run of carets (one scope out
+  // per caret), or an absolute reference `N^` (scope N, GRAMMAR §4), both as the
+  // number of scopes out from the current depth. Returns 0 when there is none.
+  // The absolute form is checked before anything is consumed, so a failing
+  // lookahead (`tryOp`) leaves the cursor on the integer.
+  private parseScopeRef(): number {
+    if (this.atAbsoluteRef()) {
+      const n = this.peek();
+      const target = Number(n.value);
+      if (target >= this.depth) {
+        this.fail(`scope ${n.value} does not enclose this block (the current scope is depth ${this.depth})`);
       }
-    };
-    return walk(where);
+      this.next(); // the integer
+      this.next(); // the caret
+      return this.depth - target;
+    }
+    return this.parseCarets();
   }
 
   private atOrderBy(): boolean {
@@ -383,11 +549,18 @@ class Parser {
   private atFollow(): boolean {
     if (!this.at("ident", "follow")) return false;
     const nx = this.peekAt(1);
-    return !!nx && (nx.type === "ident" || nx.type === "binding" || nx.type === "caret");
+    return !!nx && (nx.type === "ident" || nx.type === "binding" || nx.type === "lparen" || this.atScopeRefAt(1));
+  }
+
+  // Whether the cursor is at something that can begin a `follow` destination:
+  // a name, a binding, a scope reference, or a tuple's `(`.
+  private atDestinationStart(): boolean {
+    return this.at("ident") || this.at("binding") || this.at("lparen") || this.atScopeRefAt(0);
   }
 
   // ---- follow ---------------------------------------------------------------
   private parseFollow(): Follow {
+    const start = this.start();
     this.next(); // `follow`
     let distinct = false;
     // After `follow`, `distinct` is a keyword (a relation literally named
@@ -395,84 +568,43 @@ class Parser {
     if (this.at("ident", "distinct")) {
       this.next();
       distinct = true;
-      if (!this.at("ident") && !this.at("binding") && !this.at("caret")) {
+      if (!this.atDestinationStart()) {
         this.fail("expected a relation after `follow distinct` (`follow distinct <relation>`)");
       }
     }
     const destinations: FollowDestination[] = [this.parseFollowDestination()];
     while (this.at("comma")) {
       this.next();
-      if (!this.at("ident") && !this.at("binding") && !this.at("caret")) {
+      if (!this.atDestinationStart()) {
         this.fail("expected a relation after ',' (`follow <relation>, <relation>`)");
       }
       destinations.push(this.parseFollowDestination());
     }
-    const follow: Follow = { destinations, 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;
+    return { kind: "follow", span: this.sp(start), destinations, distinct };
   }
 
-  // One `follow` destination. The lookahead mirrors `tryOp`: a receiver (binding,
-  // or carets + a dotted name) followed by a consumer word and `{` / `distinct {`
-  // is a destination block, parsed by `tryOp(false)` itself — but only the
-  // select-position consumers (collect/first/single) yield rows to walk; the
-  // where-position tests are rejected by name before their body is read. With
-  // no directive the tokens are re-read as a plain relation of the current row,
-  // where an outer reference is still an error (a `^name` head only makes sense
-  // as the receiver of a block, since the block is what varies per row).
+  // One `follow` destination: a receiver (a binding, a dotted name — headed by a
+  // bare name, an outer reference or a free-function call — or a tuple) that is
+  // either a plain relation of the current row or, when a block follows, a
+  // destination block. The block is what `tryOp` recognizes in select position
+  // — `{ … }` (the implicit `collect`), `distinct { … }`, or a consumer word and
+  // `{` / `distinct {` — read with the destination flag so its body admits
+  // `frontier` and `depth`. Only collect/first/single yield rows to walk; the
+  // where-position tests are rejected by name. A receiver headed by an outer
+  // reference can never be a plain destination (plain destinations are relations
+  // of the current row), so without a block it is an error naming the block
+  // spellings.
   private parseFollowDestination(): FollowDestination {
-    const start = this.pos;
-    let isReceiver = false;
-    if (this.at("binding")) { this.next(); isReceiver = true; }
-    else if (this.at("ident") || this.at("caret")) {
-      this.parseCarets();
-      if (this.at("ident")) { this.parseNavFrom(this.next()); isReceiver = true; }
-    }
-    if (isReceiver && this.at("ident") && CONSUMERS.has(this.peek().value)) {
-      const op = this.peek().value;
-      const after = this.peekAt(1);
-      const opThenBrace = after?.type === "lbrace";
-      const opDistinctBrace = after?.type === "ident" && after.value === "distinct" && this.peekAt(2)?.type === "lbrace";
-      if (opThenBrace || opDistinctBrace) {
-        if (op !== "collect" && op !== "first" && op !== "single") {
-          this.fail(`a follow destination must use collect/first/single, not \`${op}\` (exists/none/count are where-position tests)`);
-        }
-        this.pos = start;
-        const block = this.tryOp(false);
-        if (!block) this.fail("expected a destination block (`<receiver> collect { … }`) after `follow`");
-        return block;
+    const outer = this.atScopeRefAt(0);
+    const op = this.tryOp(false, true);
+    if (op) {
+      if (op.op !== "collect" && op.op !== "first" && op.op !== "single") {
+        this.fail(`a follow destination must use collect/first/single, not \`${op.op}\` (exists/none/count are where-position tests)`);
       }
+      return op;
     }
-    this.pos = start;
-    if (this.at("caret")) {
-      this.fail("`follow` takes a relation of the current row (`follow <relation>`); an outer reference `^name` is not allowed there — it may only head a destination block (`follow ^name collect { … }`)");
+    if (outer) {
+      this.fail("`follow` takes a relation of the current row (`follow <relation>`); an outer reference walks a root collection only as a destination block — `follow ^docs { where … }` or `follow ^docs collect { … }`");
     }
     return this.parseReceiver();
   }
@@ -483,11 +615,21 @@ class Parser {
   // named root is only reachable as a receiver through `^` — or a free-function
   // call (`entries(prefs)`), so a computed collection can be consumed directly.
   private parseReceiver(): Expr {
-    if (this.at("binding")) return { kind: "binding", index: this.next().index! };
-    const levels = this.parseCarets();
+    if (this.at("binding")) return this.bindingNode(this.next());
+    if (this.at("lparen")) {
+      const t = this.tryTuple();
+      if (t) return t;
+      this.fail("expected a collection navigation (a property/relation name) or a tuple `(a, b)`");
+    }
+    const start = this.start();
+    const levels = this.parseScopeRef();
     if (!this.at("ident")) this.fail("expected a collection navigation (a property/relation name)");
     if (LITERAL_WORDS.has(this.peek().value)) this.fail(`\`${this.peek().value}\` is a literal, not a collection`);
-    return this.parseNavFrom(this.next(), levels).expr;
+    return this.parseNavFrom(this.next(), levels, start).expr;
+  }
+
+  private bindingNode(t: Token): Expr {
+    return { kind: "binding", span: [t.pos, t.end], index: t.index! };
   }
 
   // Consume a run of `^` and return its length (0 when there is none).
@@ -498,17 +640,23 @@ class Parser {
   }
 
   // A dotted navigation chain from `head`; `levels` > 0 makes the head an outer
-  // reference read exactly that many scopes out. A bare head followed by `(` is
-  // a free-function call (`entries(x)`), which may then be navigated further.
-  private parseNavFrom(head: Token, levels = 0): { expr: Expr; name: string } {
-    let expr: Expr = levels > 0 ? { kind: "outer", levels, name: head.value } : { kind: "ident", name: head.value };
+  // reference read exactly that many scopes out (`start` is then the position
+  // of the first caret). A bare head followed by `(` is a free-function call
+  // (`entries(x)`), which may then be navigated further.
+  private parseNavFrom(head: Token, levels = 0, start = head.pos): { expr: Expr; name: string } {
+    let expr: Expr = levels > 0
+      ? { kind: "outer", span: [start, head.end], levels, name: head.value }
+      : { kind: "ident", span: [start, head.end], name: head.value };
     let name = head.value;
-    if (levels === 0 && this.at("lparen")) expr = { kind: "call", recv: null, name: head.value, args: this.parseArgs() };
+    if (levels === 0 && this.at("lparen")) {
+      const args = this.parseArgs();
+      expr = { kind: "call", span: this.sp(start), recv: null, name: head.value, args };
+    }
     while (this.at("dot")) {
       this.next();
       if (!this.at("ident")) this.fail("expected a property name after '.'");
       name = this.next().value;
-      expr = { kind: "member", recv: expr, name };
+      expr = { kind: "member", span: this.sp(start), recv: expr, name };
     }
     return { expr, name };
   }
@@ -536,7 +684,11 @@ class Parser {
       // `^^x` bind different rows), so the lift depth is part of the key.
       const seen = new Set<string>();
       for (const it of items) {
-        if (it.name === "") this.fail("a leading expression is a projection (select): an item that is not a plain name needs an alias (`name: expr`) or `values`; to filter by it write `where …` — a predicate is never implicit");
+        if (it.name === "") {
+          if (it.kind === "collect") this.fail("a nested block in a projection needs a name (`name: <relation> collect { … }`); as a predicate, a consumer test is written `where <relation> exists { … }`");
+          if (ctx.top) this.fail("a leading expression is a projection (select): an item that is not a plain name needs an alias (`name: expr`) or `values`; to filter by it write `where …` after `from` — at the top level a predicate is never implicit (the clause order puts `from` first)");
+          this.fail("an item that is not a plain name needs an alias (`name: expr`) or `values`; to filter by it write `where …` after the projection (a block may lead with a predicate only when nothing is projected: `{ age > 18 }`)");
+        }
         const key = `${"^".repeat(it.kind === "field" ? it.lift : 0)}${it.name}`;
         if (seen.has(key)) this.fail(`duplicate projection name '${it.name}' — each projected item needs its own name (alias one: \`other: expr\`)`);
         seen.add(key);
@@ -546,12 +698,13 @@ class Parser {
   }
 
   private parseSelectItem(ctx: BodyCtx): SelectItem {
+    const start = this.start();
     // Leading `^`s mark a lift; the count is how many scopes out it binds. A
     // lift is bound by a `collect { … }` in where position and nowhere else — at
     // the top level, in a select-position block, or in an exists/none/count
     // block it would silently do nothing (or act as a plain field), so it is an
-    // error there.
-    const lift = this.parseCarets();
+    // error there. `N^name:` is the lift into scope N (GRAMMAR §4).
+    const lift = this.parseScopeRef();
     if (!this.at("ident") && !this.canStartValue()) this.fail("expected a projection name");
     if (lift > 0 && !ctx.liftsAllowed) {
       const what = this.at("ident") ? `^${this.peek().value}` : "^name";
@@ -562,20 +715,30 @@ class Parser {
       this.next(); // ':'
       const op = this.tryOp(false);
       if (op) {
+        // `name: jobs first { }.pay`: the directive is the head of a longer value.
+        if (this.atScalarContinuation() || this.atValueDirective()) return this.finishItem(name, this.parseOr(op), lift, start);
         if (op.op !== "collect" && op.op !== "first" && op.op !== "single") {
           this.fail(`projection '${name}' must use collect/first/single, not ${op.op} (exists/none/count are where-position tests)`);
         }
-        if (lift) this.fail(`a lift (^${name}) value must be a scalar expression, not ${op.op} { … }`);
-        return { kind: "collect", name, op };
+        return this.finishItem(name, op, lift, start);
       }
-      const expr = this.parseValueExpr();
-      return { kind: "field", name, expr, lift };
+      return this.finishItem(name, this.parseValueExpr(), lift, start);
     }
-    // Unaliased item: a bare/dotted navigation keys by its last segment; any
-    // other expression is unnamed ("") — legal only under `values` (checked by
-    // parseProjection, which sees the whole list).
+    // Unaliased item: a bare/dotted navigation (under any `!`) keys by its last
+    // segment; any other expression is unnamed ("") — legal only under `values`
+    // (checked by parseProjection, which sees the whole list).
     const expr = this.parseValueExpr();
-    return { kind: "field", name: navKey(expr) ?? "", expr, lift };
+    return this.finishItem(navKey(expr) ?? "", expr, lift, start);
+  }
+
+  // An item from its value: exactly a directive (written out, or the bracket
+  // sugar) is the `collect` item kind; anything else is a `field`.
+  private finishItem(name: string, expr: Expr, lift: number, start: number): SelectItem {
+    if (expr.kind === "op") {
+      if (lift) this.fail(`a lift (^${name}) value must be a scalar expression, not ${expr.op} { … }`);
+      return { kind: "collect", span: this.sp(start), name, op: expr };
+    }
+    return { kind: "field", span: this.sp(start), name, expr, lift };
   }
 
   // ---- order by -------------------------------------------------------------
@@ -586,11 +749,12 @@ class Parser {
   }
 
   private parseOrderSpec(): OrderSpec {
+    const start = this.start();
     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 };
+    return { kind: "order", span: this.sp(start), expr, desc };
   }
 
   // ---- where boolean tree: or → and → primary --------------------------------
@@ -600,21 +764,28 @@ class Parser {
   private parseWhere(): Where { return this.parseWhereOr(); }
 
   private parseWhereOr(): Where {
+    const start = this.start();
     const left = this.parseWhereAnd();
-    if (!this.atOp("||")) return left;
+    if (!this.atOr()) return left;
     const parts = [left];
-    while (this.atOp("||")) { this.next(); parts.push(this.parseWhereAnd()); }
-    return { kind: "or", parts };
+    while (this.atOr()) { this.next(); parts.push(this.parseWhereAnd()); }
+    return { kind: "or", span: this.sp(start), parts };
   }
 
   private parseWhereAnd(): Where {
+    const start = this.start();
     const left = this.parseWherePrimary();
-    if (!this.atOp("&&")) return left;
+    if (!this.atAnd()) return left;
     const parts = [left];
-    while (this.atOp("&&")) { this.next(); parts.push(this.parseWherePrimary()); }
-    return { kind: "and", parts };
+    while (this.atAnd()) { this.next(); parts.push(this.parseWherePrimary()); }
+    return { kind: "and", span: this.sp(start), parts };
   }
 
+  // `&&` / `and` and `||` / `or` are one operator each (0.17): the words are
+  // exact synonyms of the symbols, parsed to the same nodes.
+  private atAnd(): boolean { return this.atOp("&&") || this.at("kw", "and"); }
+  private atOr(): boolean { return this.atOp("||") || this.at("kw", "or"); }
+
   // A where operand: `[!…] ( where )`, `[!…] <receiver> <consumer> { … }`, or a
   // scalar leaf (a cmp-level expression, which handles its own `!`).
   //
@@ -626,34 +797,82 @@ class Parser {
   // predicate.
   private parseWherePrimary(): Where {
     const start = this.pos;
-    let nots = 0;
-    while (this.atOp("!")) { this.next(); nots++; }
+    // Leading negations: `!`, `not` (one each) and `is` (two — `is x` ≡ `!!x`).
+    const notStarts: number[] = [];
+    for (;;) {
+      if (this.atOp("!") || this.at("kw", "not")) notStarts.push(this.next().pos);
+      else if (this.at("kw", "is")) { const p = this.next().pos; notStarts.push(p, p); }
+      else break;
+    }
     if (this.at("lparen")) {
-      this.next();
+      // A tuple (0.20) is a value, not a group: the receiver of a consumer test
+      // (`(a, b) exists { }`) or a scalar operand (`(a, b).size() > 1`).
+      const tuple = this.tryTuple();
+      if (tuple) {
+        if (this.atBlock()) return wrapNot(this.finishWhereOp(this.parseConsumerBlock(tuple, this.atBlock()!, true)), notStarts);
+        let e = this.parsePostfix(tuple);
+        for (let i = notStarts.length - 1; i >= 0; i--) e = { kind: "unary", span: [notStarts[i]!, e.span[1]], op: "!", expr: e };
+        const expr = this.parseCmp(e);
+        return { kind: "scalar", span: expr.span, expr };
+      }
+      const lparen = this.next().pos;
       const inner = this.parseWhere();
       if (!this.at("rparen")) this.fail("expected ')' to close a grouped where expression");
       this.next();
+      const group: Span = [lparen, this.end()];
       if (this.atScalarContinuation()) {
-        let e = this.parsePostfix(this.whereToExpr(inner));
-        for (let i = 0; i < nots; i++) e = { kind: "unary", op: "!", expr: e };
-        return { kind: "scalar", expr: this.parseCmp(e) };
+        let e = this.parsePostfix(withSpan(this.whereToExpr(inner), group));
+        for (let i = notStarts.length - 1; i >= 0; i--) e = { kind: "unary", span: [notStarts[i]!, e.span[1]], op: "!", expr: e };
+        const expr = this.parseCmp(e);
+        return { kind: "scalar", span: expr.span, expr };
       }
-      return wrapNot(inner, nots);
+      return wrapNot(withSpan(inner, group), notStarts);
     }
     const op = this.tryOp(true);
-    if (op) return wrapNot(this.finishWhereOp(op), nots);
+    // A `first`/`single` directive is a value, never a test: the scalar grammar
+    // reads it (as a value-position directive) with whatever follows it, and
+    // `rejectBareLookup` turns a bare one into the lookup error.
+    if (op && op.op !== "first" && op.op !== "single") return wrapNot(this.finishWhereOp(op), notStarts);
     // A scalar leaf, re-read from the first `!` so the scalar grammar gives `!`
     // its one precedence (tighter than comparison). A leaf whose whole value is
     // a negation keeps the `not` node shape (`where !active`).
     this.pos = start;
-    return scalarLeaf(this.parseCmp());
+    const leaf = scalarLeaf(this.parseCmp());
+    if (!this.deferLookup) this.rejectBareLookup(leaf);
+    return leaf;
+  }
+
+  // A where leaf that is exactly a `first`/`single` directive (under any `!`) is
+  // the select-position lookup error: a lookup is a value, and alone in `where`
+  // the writer almost certainly meant `exists`.
+  private rejectBareLookup(w: Where): void {
+    let core: Where = w;
+    while (core.kind === "not") core = core.expr;
+    if (core.kind !== "scalar") return;
+    let e = core.expr;
+    while (e.kind === "unary" && e.op === "!") e = e.expr;
+    if (e.kind === "op" && (e.op === "first" || e.op === "single")) {
+      this.fail(`${e.op} { … } is a select-position lookup; in where use exists { … } / none { … } or count { … } <op> N (\`x[p]\` is \`x first { where p }\`; a lookup is a value — compare it, navigate it or require it: \`x[p].name == …\`, \`x[0]!\`)`);
+    }
+  }
+
+  // `rejectBareLookup` over every leaf of a tree read with `deferLookup` on.
+  private rejectBareLookups(w: Where): void {
+    switch (w.kind) {
+      case "and": case "or": w.parts.forEach((p) => this.rejectBareLookups(p)); return;
+      case "not": case "scalar": this.rejectBareLookup(w); return;
+      case "op": return;
+    }
   }
 
-  // Whether the token after a `)` continues a scalar expression.
+  // Whether the token after a `)` (or a directive) continues a scalar
+  // expression: an operator, `.`-navigation, a bracket, a postfix `!`, a range,
+  // `in`, or `is`.
   private atScalarContinuation(): boolean {
     const t = this.peek();
-    if (t.type === "op") return CMP_OPS.has(t.value) || ADD_OPS.has(t.value) || MUL_OPS.has(t.value);
-    return t.type === "dot" || t.type === "range" || (t.type === "ident" && t.value === "in");
+    if (t.type === "op") return CMP_OPS.has(t.value) || ADD_OPS.has(t.value) || MUL_OPS.has(t.value) || t.value === "!";
+    if (t.type === "kw") return t.value === "is";
+    return t.type === "dot" || t.type === "range" || t.type === "lbracket" || (t.type === "ident" && t.value === "in");
   }
 
   // A parenthesized where-group that turned out to be a scalar operand, as an
@@ -661,10 +880,10 @@ class Parser {
   private whereToExpr(w: Where): Expr {
     switch (w.kind) {
       case "scalar": return w.expr;
-      case "not": return { kind: "unary", op: "!", expr: this.whereToExpr(w.expr) };
+      case "not": return { kind: "unary", span: w.span, op: "!", expr: this.whereToExpr(w.expr) };
       case "and": case "or": {
         const op = w.kind === "and" ? "&&" : "||";
-        return w.parts.map((p) => this.whereToExpr(p)).reduce((l, r) => ({ kind: "logical", op, left: l, right: r }));
+        return w.parts.map((p) => this.whereToExpr(p)).reduce((l, r) => ({ kind: "logical", span: [l.span[0], r.span[1]], op, left: l, right: r }));
       }
       case "op": {
         const hint = w.op === "count" ? ` — write \`<relation> count { … } ${this.peek().value} N\` without the parentheses` : "";
@@ -689,64 +908,203 @@ class Parser {
       const v = Number(this.next().value);
       if (!Number.isInteger(v)) this.fail("count comparison takes an integer");
       op.countCmp = { op: relop, value: v };
+      op.span = [op.span[0], this.end()];
     }
     return op;
   }
 
-  // Detect + parse a postfix consumer op `<receiver> <consumer> { <sub> }`.
-  // Returns null (rewinding) when the lookahead is not a consumer op.
-  private tryOp(inWhere: boolean): OpNode | null {
+  // Detect + parse a postfix consumer op `<receiver> <consumer> { <sub> }` — or
+  // its implicit-`collect` forms `<receiver> { <sub> }` and `<receiver> distinct
+  // { <sub> }` (0.20). Returns null (rewinding) when the lookahead is not a
+  // directive. `destination` marks a follow destination block (its body admits
+  // `frontier`/`depth`).
+  private tryOp(inWhere: boolean, destination = false): OpNode | null {
     const start = this.pos;
+    const startPos = this.start();
     let receiver: Expr;
-    if (this.at("binding")) receiver = { kind: "binding", index: this.next().index! };
-    else if (this.at("ident") || this.at("caret")) {
-      const levels = this.parseCarets();
+    // An absolute reference that does not enclose this scope is an error only
+    // if the tokens do form a directive (`0^docs collect { }` at the root);
+    // otherwise the expression grammar gets to read them (a top-level `0^name`
+    // item is a lift, with the lift's own error), so the failure is held back
+    // until the lookahead has decided.
+    let scopeErr: OqxError | null = null;
+    if (this.at("binding")) receiver = this.bindingNode(this.next());
+    else if (this.at("lparen")) {
+      // A tuple receiver, `(a, b) { … }`; a single parenthesized expression is
+      // grouping and never a receiver.
+      const t = this.tryTuple();
+      if (!t) { this.pos = start; return null; }
+      receiver = t;
+    } else if (this.at("ident") || this.atScopeRefAt(0)) {
+      let levels = 0;
+      try {
+        levels = this.parseScopeRef();
+      } catch (err) {
+        if (!(err instanceof OqxError)) throw err;
+        scopeErr = err;
+        this.next(); this.next(); // the integer and the caret, as if it had parsed
+        levels = 1;
+      }
       if (!this.at("ident")) { this.pos = start; return null; }
-      receiver = this.parseNavFrom(this.next(), levels).expr;
+      receiver = this.parseNavFrom(this.next(), levels, startPos).expr;
     } else return null;
 
-    if (this.at("ident") && CONSUMERS.has(this.peek().value)) {
-      const after = this.peekAt(1);
-      // `<op> { … }` or `<op> distinct { … }`.
-      const opThenBrace = after?.type === "lbrace";
-      const opDistinctBrace = after?.type === "ident" && after.value === "distinct" && this.peekAt(2)?.type === "lbrace";
-      if (opThenBrace || opDistinctBrace) {
-        if (receiver.kind === "ident" && LITERAL_WORDS.has(receiver.name)) this.fail(`\`${receiver.name}\` is a literal, not a collection`);
-        const op = this.next().value as Consumer;
-        let distinct = false;
-        if (this.at("ident", "distinct")) { this.next(); distinct = true; }
-        this.next(); // '{'
-        const { sub, distinct: bodyDistinct } = this.parseSubquery({ top: false, op, liftsAllowed: inWhere && op === "collect" });
-        if (!this.at("rbrace")) this.fail(`expected '}' to close the ${op} { … } block`);
-        this.next();
-        return { kind: "op", receiver, op, sub, distinct: distinct || bodyDistinct };
+    const op = this.atBlock();
+    if (op) {
+      if (scopeErr) throw scopeErr;
+      if (receiver.kind === "ident" && LITERAL_WORDS.has(receiver.name)) this.fail(`\`${receiver.name}\` is a literal, not a collection`);
+      // `count { }` with nothing before it: the consumer word is not a receiver.
+      if (op === "collect" && receiver.kind === "ident" && CONSUMERS.has(receiver.name) && this.at("lbrace")) {
+        this.fail(`unexpected '{' after \`${receiver.name}\` — a consumer needs a receiver: \`<collection> ${receiver.name} { … }\``);
       }
+      return this.parseConsumerBlock(receiver, op, inWhere, destination);
     }
     this.pos = start;
     return null;
   }
 
-  private parseSubquery(ctx: BodyCtx): { sub: Subquery; distinct: boolean } {
-    const body = this.parseBody(ctx);
-    return {
-      sub: { from: body.froms, where: body.where, select: body.select, orderBy: body.orderBy, follow: body.follow, values: body.values, ...bounds(body) },
-      distinct: body.distinct,
+  // The cursor is at what opens a block over an already-read receiver: `{` or
+  // `distinct {` (the implicit `collect`), or a consumer word and `{` /
+  // `distinct {`. Consumes nothing.
+  private atBlock(): Consumer | null {
+    if (this.at("lbrace")) return "collect";
+    if (this.at("ident", "distinct") && this.peekAt(1)?.type === "lbrace") return "collect";
+    return this.atConsumerBlock();
+  }
+
+  // The cursor is at a consumer word that opens a block — `<op> {` or
+  // `<op> distinct {`. Consumes nothing.
+  private atConsumerBlock(): Consumer | null {
+    if (!this.at("ident") || !CONSUMERS.has(this.peek().value)) return null;
+    const after = this.peekAt(1);
+    const opThenBrace = after?.type === "lbrace";
+    const opDistinctBrace = after?.type === "ident" && after.value === "distinct" && this.peekAt(2)?.type === "lbrace";
+    return opThenBrace || opDistinctBrace ? (this.peek().value as Consumer) : null;
+  }
+
+  // `[<op>] [distinct] { <sub> }` over an already-parsed receiver; the cursor is
+  // at the consumer word, at `distinct`, or at the `{` of the implicit `collect`.
+  // `destination` marks a follow destination block (0.20): its body may carry
+  // `frontier` and `depth`.
+  private parseConsumerBlock(receiver: Expr, op: Consumer, inWhere: boolean, destination = false): OpNode {
+    const startPos = receiver.span[0];
+    if (this.at("ident") && CONSUMERS.has(this.peek().value)) this.next(); // the consumer word (absent for `x { … }`)
+    let distinct = false;
+    if (this.at("ident", "distinct")) { this.next(); distinct = true; }
+    const lbrace = this.next().pos; // '{'
+    const defer = this.deferLookup;
+    this.deferLookup = false;
+    // The receiver was read at the enclosing depth; the block's rows are one deeper.
+    const body = this.atDepth(this.depth + 1, () => this.parseBody({ top: false, op, liftsAllowed: inWhere && op === "collect", destination }));
+    this.deferLookup = defer;
+    if (!this.at("rbrace")) this.fail(`expected '}' to close the ${op} { … } block`);
+    this.next();
+    const sub: Subquery = {
+      kind: "subquery",
+      span: this.sp(lbrace),
+      from: body.froms,
+      where: body.where,
+      select: body.select,
+      orderBy: body.orderBy,
+      follow: body.follow,
+      frontier: body.frontier,
+      depth: body.depth,
+      values: body.values,
+      limit: body.limit,
+      offset: body.offset,
     };
+    return { kind: "op", span: this.sp(startPos), receiver, op, sub, countCmp: null, distinct: distinct || body.distinct };
+  }
+
+  // A tuple `(e1, e2, …)` at the cursor's `(` (0.20): two or more comma-separated
+  // expressions. A single parenthesized expression is grouping, not a tuple —
+  // the cursor is rewound and null returned (also on a parse error, so the
+  // caller's own reading reports its own error).
+  private tryTuple(): Expr | null {
+    const save = this.pos;
+    const lparen = this.next().pos; // '('
+    try {
+      const items = [this.parseValueExpr()];
+      if (!this.at("comma")) { this.pos = save; return null; }
+      while (this.at("comma")) { this.next(); items.push(this.parseValueExpr()); }
+      if (!this.at("rparen")) this.fail("expected ')' to close the tuple");
+      this.next();
+      return { kind: "tuple", span: [lparen, this.end()], items };
+    } catch (err) {
+      if (!(err instanceof OqxError)) throw err;
+      this.pos = save;
+      return null;
+    }
+  }
+
+  // A bracket suffix on `recv` (GRAMMAR §4): `[n]` / `[${…}]` is positional —
+  // `recv first { offset n }` — and anything else a predicate —
+  // `recv first { where p }`; a trailing `!` makes the index required and the
+  // predicate a `single` (required too, so that zero matches is an error).
+  private parseBracket(recv: Expr): Expr {
+    if (recv.kind === "lit") this.fail(`\`${describe(recv)}\` is a literal, not a collection`);
+    const start = recv.span[0];
+    const lbracket = this.next().pos; // '['
+    let index: Expr | null = null;
+    let where: Where | null = null;
+    if (this.at("number") && this.peekAt(1)?.type === "rbracket") {
+      const t = this.next();
+      const v = Number(t.value);
+      if (!Number.isInteger(v)) this.fail(`an index is a non-negative integer literal or a binding (got ${t.value})`);
+      index = { kind: "lit", span: [t.pos, t.end], value: v };
+    } else if (this.at("binding") && this.peekAt(1)?.type === "rbracket") {
+      index = this.bindingNode(this.next());
+    } else if (this.atOp("-") && this.peekAt(1)?.type === "number" && this.peekAt(2)?.type === "rbracket") {
+      this.fail("negative indices are not supported (`x[-1]`): an index is a non-negative integer literal or a binding");
+    } else {
+      const defer = this.deferLookup;
+      this.deferLookup = false;
+      // The predicate is the block's `where`: read in the rows' scope, one deeper.
+      where = this.atDepth(this.depth + 1, () => this.parseWhere());
+      this.deferLookup = defer;
+    }
+    if (!this.at("rbracket")) this.fail("expected ']' to close the bracket");
+    this.next();
+    const subSpan: Span = [lbracket, this.end()];
+    const sub = (parts: Partial<Subquery>): Subquery => ({
+      kind: "subquery", span: subSpan, from: [], where: null, select: [], orderBy: null, follow: null, frontier: null, depth: null, values: false, limit: null, offset: null, ...parts,
+    });
+    const bang = this.atOp("!") ? this.next() : null;
+    if (index) {
+      const op: OpNode = { kind: "op", span: [start, subSpan[1]], receiver: recv, op: "first", sub: sub({ offset: index }), countCmp: null, distinct: false };
+      return bang ? { kind: "required", span: [start, bang.end], expr: op } : op;
+    }
+    if (bang) {
+      const op: OpNode = { kind: "op", span: [start, bang.end], receiver: recv, op: "single", sub: sub({ where }), countCmp: null, distinct: false };
+      return { kind: "required", span: [start, bang.end], expr: op };
+    }
+    return { kind: "op", span: [start, subSpan[1]], receiver: recv, op: "first", sub: sub({ where }), countCmp: null, distinct: false };
   }
 
   // ---- expression Pratt parser ----------------------------------------------
-  // Value position (select/order/follow/source): full boolean+arithmetic.
+  // Value position (select/order/follow/source): full boolean+arithmetic. Each
+  // level takes an optional already-parsed `left` operand (a directive read by
+  // `tryOp`, a promoted where-group), so it continues into the operator tail
+  // without re-reading its tokens.
   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() }; }
+  private parseOr(left?: Expr): Expr {
+    left = this.parseAnd(left);
+    while (this.atOr()) {
+      this.next();
+      const right = this.parseAnd();
+      left = { kind: "logical", span: [left.span[0], right.span[1]], op: "||", left, right };
+    }
     return left;
   }
 
-  private parseAnd(): Expr {
-    let left = this.parseCmp();
-    while (this.atOp("&&")) { this.next(); left = { kind: "logical", op: "&&", left, right: this.parseCmp() }; }
+  private parseAnd(left?: Expr): Expr {
+    left = this.parseCmp(left);
+    while (this.atAnd()) {
+      this.next();
+      const right = this.parseCmp();
+      left = { kind: "logical", span: [left.span[0], right.span[1]], op: "&&", left, right };
+    }
     return left;
   }
 
@@ -760,11 +1118,16 @@ class Parser {
   private parseCmp(left?: Expr): Expr {
     const lhs = this.parseRange(left);
     const t = this.peek();
-    const isCmp = (): boolean => (this.peek().type === "op" && CMP_OPS.has(this.peek().value)) || this.at("ident", "in");
+    const isCmp = (): boolean => (this.peek().type === "op" && CMP_OPS.has(this.peek().value)) || this.at("ident", "in") || this.at("kw", "is");
     if (!isCmp()) return lhs;
-    const op = this.next().value;
+    let op = this.next().value;
+    // `is` / `is not` — identity (SEMANTICS §5b); `is not` is the compound.
+    if (op === "is" && this.at("kw", "not")) { this.next(); op = "is not"; }
     const rhs = this.parseRange();
-    const result: Expr = op === "in" ? { kind: "in", left: lhs, right: rhs } : { kind: "binary", op, left: lhs, right: rhs };
+    const span: Span = [lhs.span[0], rhs.span[1]];
+    const result: Expr = op === "in"
+      ? { kind: "in", span, left: lhs, right: rhs }
+      : { kind: "binary", span, op: op as BinaryOp, left: lhs, right: rhs };
     if (isCmp()) {
       this.fail(`comparisons do not chain: \`a ${t.value} b ${this.peek().value} c\` — write two comparisons joined with \`&&\``);
     }
@@ -778,15 +1141,18 @@ class Parser {
   // opens the high end.
   private parseRange(left?: Expr): Expr {
     if (left === undefined && this.at("range")) {
-      const exclusiveEnd = this.next().value === "...";
+      const tok = this.next();
+      const exclusiveEnd = tok.value === "...";
       if (!this.canStartValue()) this.fail("a range needs at least one bound: `lo..hi`, `lo..`, or `..hi`");
-      return { kind: "range", lo: null, hi: this.parseAdd(), exclusiveEnd };
+      const hi = this.parseAdd();
+      return { kind: "range", span: [tok.pos, hi.span[1]], lo: null, hi, exclusiveEnd };
     }
     const lo = this.parseAdd(left);
     if (this.at("range")) {
-      const exclusiveEnd = this.next().value === "...";
+      const tok = this.next();
+      const exclusiveEnd = tok.value === "...";
       const hi = this.canStartValue() ? this.parseAdd() : null;
-      return { kind: "range", lo, hi, exclusiveEnd };
+      return { kind: "range", span: [lo.span[0], hi ? hi.span[1] : tok.end], lo, hi, exclusiveEnd };
     }
     return lo;
   }
@@ -797,8 +1163,13 @@ class Parser {
   // consumers, …) are lexed as bare idents, so they must NOT count as a value
   // start, or `where age in 18.. order by name` would read `order` as the bound.
   private canStartValue(): boolean {
-    const t = this.peek();
+    return this.startsValue(this.peek());
+  }
+
+  private startsValue(t: Token | undefined): boolean {
+    if (!t) return false;
     if (t.type === "ident") return !CLAUSE_WORDS.has(t.value);
+    if (t.type === "kw") return t.value === "is" || t.value === "not"; // the prefix operators
     if (t.type === "number" || t.type === "string" ||
         t.type === "binding" || t.type === "lparen" || t.type === "caret") return true;
     return t.type === "op" && (t.value === "-" || t.value === "!");
@@ -807,8 +1178,9 @@ class Parser {
   private parseAdd(left?: Expr): Expr {
     left = this.parseMul(left);
     while (this.peek().type === "op" && ADD_OPS.has(this.peek().value)) {
-      const op = this.next().value;
-      left = { kind: "binary", op, left, right: this.parseMul() };
+      const op = this.next().value as BinaryOp;
+      const right = this.parseMul();
+      left = { kind: "binary", span: [left.span[0], right.span[1]], op, left, right };
     }
     return left;
   }
@@ -816,43 +1188,74 @@ class Parser {
   private parseMul(left?: Expr): Expr {
     left = this.parseUnary(left);
     while (this.peek().type === "op" && MUL_OPS.has(this.peek().value)) {
-      const op = this.next().value;
-      left = { kind: "binary", op, left, right: this.parseUnary() };
+      const op = this.next().value as BinaryOp;
+      const right = this.parseUnary();
+      left = { kind: "binary", span: [left.span[0], right.span[1]], op, left, right };
     }
     return left;
   }
 
   private parseUnary(left?: Expr): Expr {
     if (left !== undefined) return this.parsePostfix(left);
-    if (this.atOp("!")) { this.next(); return { kind: "unary", op: "!", expr: this.parseUnary() }; }
-    if (this.atOp("-")) { this.next(); return { kind: "unary", op: "-", expr: this.parseUnary() }; }
+    if (this.atOp("!") || this.atOp("-") || this.at("kw", "is") || this.at("kw", "not")) {
+      const tok = this.next();
+      const expr = this.parseUnary();
+      const span: Span = [tok.pos, expr.span[1]];
+      // `is x` ≡ `!!x`, `not x` ≡ `!x`: pure sugar, both nodes spanning the sugar.
+      if (tok.type === "kw") {
+        const not: Expr = { kind: "unary", span, op: "!", expr };
+        return tok.value === "is" ? { kind: "unary", span, op: "!", expr: not } : not;
+      }
+      return { kind: "unary", span, op: tok.value as "!" | "-", expr };
+    }
     return this.parsePostfix();
   }
 
   private parsePostfix(left?: Expr): Expr {
     let expr = left ?? this.parsePrimary();
+    const start = expr.span[0];
     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() };
+          const args = this.parseArgs();
+          expr = { kind: "call", span: this.sp(start), recv: expr, name, args };
         } else {
-          expr = { kind: "member", recv: expr, name };
+          expr = { kind: "member", span: this.sp(start), recv: expr, name };
         }
       } else if (this.at("lparen") && left === undefined && expr.kind === "ident") {
         // free function call: name(args) — a bare name read here, not `(f)(x)`
-        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
+        const args = this.parseArgs();
+        expr = { kind: "call", span: this.sp(start), recv: null, name: expr.name, args };
+      } else if (this.at("lbracket")) {
+        expr = this.parseBracket(expr);
+      } else if (this.atOp("!")) {
+        // Postfix `!`: a `!` right after a complete chain is `required` — OQX
+        // never places two operands side by side, so it cannot begin one here.
+        const bang = this.next();
+        expr = { kind: "required", span: [start, bang.end], expr };
+      } else if (this.atValueDirective() || this.at("lbrace") || (this.at("ident", "distinct") && this.peekAt(1)?.type === "lbrace")) {
+        // A value-position directive, `recv first { … }` — how a bracket chain
+        // prints back — or the implicit `collect` of a bare `{ … }` / `distinct
+        // { … }` (0.20: the receiver-block sugar stands wherever a value does,
+        // `size(children { is checked })`). exists/none/count have no value form
+        // and are left to the body's own error.
+        if (expr.kind === "lit") this.fail(`\`${describe(expr)}\` is a literal, not a collection`);
+        expr = this.parseConsumerBlock(expr, this.atBlock()!, false);
       } else {
-        break;
+        break; // anything else ends the chain
       }
     }
     return expr;
   }
 
+  private atValueDirective(): boolean {
+    const op = this.atConsumerBlock();
+    return op === "collect" || op === "first" || op === "single";
+  }
+
   private parseArgs(): Expr[] {
     this.next(); // '('
     const args: Expr[] = [];
@@ -871,27 +1274,37 @@ class Parser {
     // 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") {
-      const levels = this.parseCarets();
+    if (t.type === "caret" || this.atAbsoluteRef()) {
+      const levels = this.parseScopeRef();
       if (!this.at("ident")) this.fail("expected an identifier after '^' (an outer reference)");
-      return { kind: "outer", levels, name: this.next().value };
+      const name = this.next();
+      return { kind: "outer", span: [t.pos, name.end], levels, name: name.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 === "number") { this.next(); return { kind: "lit", span: [t.pos, t.end], value: Number(t.value) }; }
+    if (t.type === "string") { this.next(); return { kind: "lit", span: [t.pos, t.end], value: t.value }; }
+    if (t.type === "binding") { this.next(); return this.bindingNode(t); }
     if (t.type === "lparen") {
       this.next();
       const e = this.parseValueExpr();
+      if (this.at("comma")) {
+        // A tuple `(e1, e2, …)` (0.20): two or more elements.
+        const items = [e];
+        while (this.at("comma")) { this.next(); items.push(this.parseValueExpr()); }
+        if (!this.at("rparen")) this.fail("expected ')' to close the tuple");
+        this.next();
+        return { kind: "tuple", span: [t.pos, this.end()], items };
+      }
       if (!this.at("rparen")) this.fail("expected ')'");
       this.next();
-      return e;
+      return withSpan(e, [t.pos, this.end()]);
     }
     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 };
+      const span: Span = [t.pos, t.end];
+      if (t.value === "true") return { kind: "lit", span, value: true };
+      if (t.value === "false") return { kind: "lit", span, value: false };
+      if (t.value === "null") return { kind: "lit", span, value: null };
+      return { kind: "ident", span, name: t.value };
     }
     this.fail(`unexpected ${this.tokDesc()} — expected a value`);
   }
@@ -904,25 +1317,44 @@ function navKey(e: Expr): string | null {
     case "ident": return e.name;
     case "outer": return e.name;
     case "member": return e.name;
+    case "required": return navKey(e.expr);
     default: return null;
   }
 }
 
-// `!` applied `n` times to a where node.
-function wrapNot(w: Where, n: number): Where {
-  for (let i = 0; i < n; i++) w = { kind: "not", expr: w };
+// Whether a block's leading run, read as a where tree, is syntactically a
+// predicate (GRAMMAR §2): anything but a bare name, a dotted navigation or a lift
+// (an `outer`), with a parenthesized leading expression always a predicate.
+function predicateShaped(w: Where, first: Token): boolean {
+  if (first.type === "lparen") return true;
+  if (w.kind !== "scalar") return true;
+  return !isNavigation(w.expr);
+}
+
+function isNavigation(e: Expr): boolean {
+  switch (e.kind) {
+    case "ident": case "outer": return true;
+    case "member": return isNavigation(e.recv);
+    default: return false;
+  }
+}
+
+// The canonical text of a node for an error message; a binding shows as its
+// `${n}` marker (the printer refuses to turn a bound value into source).
+function describe(node: Expr | Where): string {
+  const t = printTemplate(node);
+  return t.strings.map((s, i) => (i < t.count ? `${s}\${${t.indices[i]}}` : s)).join("");
+}
+
+// `!` applied once per recorded `!` position to a where node, innermost first.
+function wrapNot(w: Where, notStarts: readonly number[]): Where {
+  for (let i = notStarts.length - 1; i >= 0; i--) w = { kind: "not", span: [notStarts[i]!, w.span[1]], expr: w };
   return w;
 }
 
 // A scalar where leaf. A leading `!` on the whole leaf becomes a `not` node (so
 // `where !active` keeps its shape); inside a comparison it stays a unary `!`.
 function scalarLeaf(e: Expr): Where {
-  if (e.kind === "unary" && e.op === "!") return { kind: "not", expr: scalarLeaf(e.expr) };
-  return { kind: "scalar", expr: e };
-}
-
-// The optional `limit`/`offset` fields of a Query/Subquery, present only when set
-// (so a Query built without them is unchanged).
-function bounds(b: { limit?: Expr | null; offset?: Expr | null }): { limit?: Expr; offset?: Expr } {
-  return { ...(b.limit ? { limit: b.limit } : {}), ...(b.offset ? { offset: b.offset } : {}) };
+  if (e.kind === "unary" && e.op === "!") return { kind: "not", span: e.span, expr: scalarLeaf(e.expr) };
+  return { kind: "scalar", span: e.span, expr: e };
 }