@omgbase/oqx 0.18.0 → 0.20.0

package/src/optimize/analysis.ts

@@ -34,6 +34,7 @@ export function exprReadsScopeIn(e: Expr, at: number, upTo: number): boolean {
     case "op": return opReadsScopeIn(e, at, upTo);
     case "binary": case "logical": case "in": return exprReadsScopeIn(e.left, at, upTo) || exprReadsScopeIn(e.right, at, upTo);
     case "range": return (e.lo !== null && exprReadsScopeIn(e.lo, at, upTo)) || (e.hi !== null && exprReadsScopeIn(e.hi, at, upTo));
+    case "tuple": return e.items.some((x) => exprReadsScopeIn(x, at, upTo));
   }
 }
 
@@ -47,22 +48,26 @@ export function whereReadsScopeIn(w: Where, at: number, upTo: number): boolean {
 }
 
 /** A directive evaluated in a scope at depth `at`: its receiver is read there;
- * its rows are scopes at `at + 1`. */
-export function opReadsScopeIn(op: OpNode, at: number, upTo: number): boolean {
-  return exprReadsScopeIn(op.receiver, at, upTo) || subReadsScopeIn(op.sub, at + 1, upTo);
+ * its rows are scopes at `at + 1`. `destination` marks a follow destination
+ * block (its `frontier` is read one level out). */
+export function opReadsScopeIn(op: OpNode, at: number, upTo: number, destination = false): boolean {
+  return exprReadsScopeIn(op.receiver, at, upTo) || subReadsScopeIn(op.sub, at + 1, upTo, destination);
 }
 
 /** A block body whose rows are scopes at depth `at`. `from` re-projections,
  * `where`, `select`, `order by` and the bound are read in the row scope (the
- * bound in a row-less scope at the same depth); `follow` walks occurrences at
- * `at`, with its successor `where` one deeper (§20). */
-function subReadsScopeIn(sub: Subquery, at: number, upTo: number): boolean {
+ * bound in a row-less scope at the same depth); a destination block's
+ * `frontier` is read one level out, under the walk's enclosing scope (§20),
+ * any other block's `frontier` (its seeds') in the row scope like `where`;
+ * `follow` walks occurrences at `at`. */
+function subReadsScopeIn(sub: Subquery, at: number, upTo: number, destination: boolean): boolean {
   if (sub.from.some((e) => exprReadsScopeIn(e, at, upTo))) return true;
   if (sub.where && whereReadsScopeIn(sub.where, at, upTo)) return true;
   if (sub.select.some((item) => itemReadsScopeIn(item, at, upTo))) return true;
   if (sub.orderBy?.some((o) => exprReadsScopeIn(o.expr, at, upTo))) return true;
   if (sub.limit && exprReadsScopeIn(sub.limit, at, upTo)) return true;
   if (sub.offset && exprReadsScopeIn(sub.offset, at, upTo)) return true;
+  if (sub.frontier && exprReadsScopeIn(sub.frontier, destination ? at - 1 : at, upTo)) return true;
   return sub.follow !== null && followReadsScopeIn(sub.follow, at, upTo);
 }
 
@@ -71,12 +76,7 @@ function itemReadsScopeIn(item: SelectItem, at: number, upTo: number): boolean {
 }
 
 function followReadsScopeIn(f: Follow, at: number, upTo: number): boolean {
-  for (const d of f.destinations) {
-    if (d.kind === "op" ? opReadsScopeIn(d, at, upTo) : exprReadsScopeIn(d, at, upTo)) return true;
-  }
-  if (f.where && exprReadsScopeIn(f.where, at + 1, upTo)) return true;
-  if (f.frontier && exprReadsScopeIn(f.frontier, at, upTo)) return true;
-  return f.by !== null && exprReadsScopeIn(f.by, at, upTo);
+  return f.destinations.some((d) => (d.kind === "op" ? opReadsScopeIn(d, at, upTo, true) : exprReadsScopeIn(d, at, upTo)));
 }
 
 /** Does `e` read the scope it is evaluated in (a bare identifier anywhere)? */
@@ -100,6 +100,7 @@ export function exprRaiseFree(e: Expr, ctx: RuleContext): boolean {
     case "unary": return exprRaiseFree(e.expr, ctx);
     case "binary": case "logical": case "in": return exprRaiseFree(e.left, ctx) && exprRaiseFree(e.right, ctx);
     case "range": return (e.lo === null || exprRaiseFree(e.lo, ctx)) && (e.hi === null || exprRaiseFree(e.hi, ctx));
+    case "tuple": return e.items.every((x) => exprRaiseFree(x, ctx));
   }
 }
 

package/src/parser.ts

@@ -17,9 +17,12 @@
 //
 // 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
@@ -33,8 +36,9 @@
 // out-of-order clause is a parse error naming the order.
 //
 // Sugar (0.17) desugars HERE, to existing nodes: `x { … }` is `x collect { … }`
-// (not in `follow` destination position, where a brace is the options block);
-// `x[p]` is `x first { where p }`, `x[n]` is `x first { offset n }`, with a
+// 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
@@ -57,6 +61,9 @@
 // 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
 // position (`!a == b` is `(!a) == b`, as in C); parentheses in `where` group a
@@ -78,8 +85,17 @@ 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>([
@@ -103,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 {
@@ -122,6 +142,8 @@ interface BodyClauses {
   select: SelectItem[];
   orderBy: OrderSpec[] | null;
   follow: Follow | null;
+  frontier: Expr | null;
+  depth: number | null;
   distinct: boolean;
   values: boolean;
   limit: Expr | null;
@@ -231,6 +253,7 @@ class Parser {
       orderBy: body.orderBy,
       consumer: "collect",
       follow: body.follow,
+      frontier: body.frontier,
       distinct: body.distinct,
       values: body.values,
       limit: body.limit,
@@ -243,7 +266,7 @@ class Parser {
   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, distinct: e.distinct, values: e.sub.values,
+      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,
     };
   }
@@ -264,6 +287,8 @@ 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;
@@ -278,7 +303,7 @@ class Parser {
       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;
     };
@@ -303,6 +328,27 @@ class Parser {
         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.atDepth(rowDepth, () => this.parseFollow());
@@ -349,7 +395,12 @@ class Parser {
     // 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));
-    return { froms, where, select, orderBy, follow, distinct, values, limit, offset };
+    // 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
@@ -403,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
@@ -421,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\``);
@@ -493,12 +549,13 @@ 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" || this.atScopeRefAt(1));
+    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.
+  // 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.atScopeRefAt(0);
+    return this.at("ident") || this.at("binding") || this.at("lparen") || this.atScopeRefAt(0);
   }
 
   // ---- follow ---------------------------------------------------------------
@@ -523,75 +580,31 @@ class Parser {
       }
       destinations.push(this.parseFollowDestination());
     }
-    const follow: Follow = { kind: "follow", span: this.sp(start), 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();
-        // Read in the successor's scope, one deeper than the frontier row.
-        follow.where = this.atDepth(this.depth + 1, () => 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 (a brace after the last destination is the options block; a destination block needs its consumer: \`follow <relation> collect { … }\`)`);
-      }
-    }
-    if (!this.at("rbrace")) this.fail("expected '}' to close the follow block");
-    this.next();
-    follow.span = this.sp(start);
-    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.atScopeRefAt(0)) {
-      const startPos = this.start();
-      this.parseScopeRef();
-      if (this.at("ident")) { this.parseNavFrom(this.next(), 0, startPos); 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.atScopeRefAt(0)) {
-      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();
   }
@@ -603,6 +616,11 @@ class Parser {
   // call (`entries(prefs)`), so a computed collection can be consumed directly.
   private parseReceiver(): Expr {
     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)");
@@ -787,6 +805,16 @@ class Parser {
       else break;
     }
     if (this.at("lparen")) {
+      // 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");
@@ -886,9 +914,11 @@ class Parser {
   }
 
   // Detect + parse a postfix consumer op `<receiver> <consumer> { <sub> }` — or
-  // its implicit-`collect` form `<receiver> { <sub> }`. Returns null (rewinding)
-  // when the lookahead is not a directive.
-  private tryOp(inWhere: boolean): OpNode | null {
+  // 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;
@@ -899,7 +929,13 @@ class Parser {
     // until the lookahead has decided.
     let scopeErr: OqxError | null = null;
     if (this.at("binding")) receiver = this.bindingNode(this.next());
-    else if (this.at("ident") || this.atScopeRefAt(0)) {
+    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();
@@ -913,20 +949,29 @@ class Parser {
       receiver = this.parseNavFrom(this.next(), levels, startPos).expr;
     } else return null;
 
-    const op = this.at("lbrace") ? "collect" : this.atConsumerBlock();
+    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)) {
+      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);
+      return this.parseConsumerBlock(receiver, op, inWhere, destination);
     }
     this.pos = start;
     return null;
   }
 
+  // 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 {
@@ -938,17 +983,19 @@ class Parser {
   }
 
   // `[<op>] [distinct] { <sub> }` over an already-parsed receiver; the cursor is
-  // at the consumer word, or at the `{` of the implicit `collect`.
-  private parseConsumerBlock(receiver: Expr, op: Consumer, inWhere: boolean): OpNode {
+  // 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")) this.next(); // the consumer word (absent for `x { … }`)
+    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" }));
+    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();
@@ -960,6 +1007,8 @@ class Parser {
       select: body.select,
       orderBy: body.orderBy,
       follow: body.follow,
+      frontier: body.frontier,
+      depth: body.depth,
       values: body.values,
       limit: body.limit,
       offset: body.offset,
@@ -967,6 +1016,27 @@ class Parser {
     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
@@ -997,7 +1067,7 @@ class Parser {
     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, values: false, limit: null, offset: null, ...parts,
+      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) {
@@ -1093,7 +1163,11 @@ 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" ||
@@ -1162,14 +1236,16 @@ class Parser {
         // 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()) {
+      } 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; exists/none/count have no value form and are left to
-        // the body's own error.
+        // 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.atConsumerBlock()!, false);
+        expr = this.parseConsumerBlock(expr, this.atBlock()!, false);
       } else {
-        break; // a bare `{` is a consumer block boundary — not part of a value expression; anything else ends the chain too
+        break; // anything else ends the chain
       }
     }
     return expr;
@@ -1210,6 +1286,14 @@ class Parser {
     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 withSpan(e, [t.pos, this.end()]);

package/src/print.ts

@@ -2,7 +2,8 @@
 // Single spaces, double-quoted strings with GRAMMAR §1 escapes, the minimal
 // parentheses the precedence table (GRAMMAR §4) needs, `select` written at the
 // top level, the connectives as the words `and` / `or` (since 0.18; `!` stays
-// `!`), every option in its canonical position. The law both spec runners
+// `!`), every clause in its canonical position (a destination block's
+// `frontier` and `depth` after its `where`, since 0.20). The law both spec runners
 // enforce over every fixture query:
 //
 //   strip(parse(print(parse(q)))) ≡ strip(parse(q))
@@ -65,7 +66,7 @@ const OR = 1, AND = 2, CMP = 3, RANGE = 4, ADD = 5, MUL = 6, UNARY = 7, POSTFIX
 
 function prec(e: Expr): number {
   switch (e.kind) {
-    case "lit": case "ident": case "outer": case "binding": return PRIMARY;
+    case "lit": case "ident": case "outer": case "binding": case "tuple": return PRIMARY;
     case "member": case "call": case "required": case "op": return POSTFIX;
     case "unary": return UNARY;
     case "binary": return e.op === "+" || e.op === "-" ? ADD : e.op === "*" || e.op === "/" || e.op === "%" ? MUL : CMP;
@@ -113,14 +114,18 @@ function query(q: Query): Out {
   return cat(expr(q.source), ` ${q.consumer}${q.distinct ? " distinct" : ""} `, braces(body(q)));
 }
 
-type Body = Pick<Subquery, "select" | "values" | "from" | "where" | "follow" | "orderBy" | "limit" | "offset">;
+type Body = Pick<Subquery, "select" | "values" | "from" | "where" | "follow" | "orderBy" | "limit" | "offset">
+  & Partial<Pick<Subquery, "frontier" | "depth">>;
 
 // The clauses after `from` (a query) or after the projection (a block): the
-// fixed clause order, each present clause once.
+// fixed clause order, each present clause once. `frontier`/`depth` exist only
+// on a follow destination block's body (a `Query` has neither).
 function tail(b: Omit<Body, "select" | "values">): Out[] {
   const out: Out[] = [];
   for (const e of b.from) out.push(cat("from ", expr(e)));
   if (b.where) out.push(cat("where ", where(b.where)));
+  if (b.frontier) out.push(cat("frontier ", expr(b.frontier)));
+  if (b.depth != null) out.push([`depth ${number(b.depth)}`]);
   if (b.follow) out.push(follow(b.follow));
   if (b.orderBy && b.orderBy.length > 0) out.push(cat("order by ", join(b.orderBy.map(order), ", ")));
   if (b.limit) out.push(cat("limit ", expr(b.limit)));
@@ -170,12 +175,7 @@ function op(o: OpNode): Out {
 
 function follow(f: Follow): Out {
   const dests = join(f.destinations.map((d) => (d.kind === "op" ? op(d) : expr(d))), ", ");
-  const opts: Out[] = [];
-  if (f.where) opts.push(cat("where ", expr(f.where)));
-  if (f.frontier) opts.push(cat("frontier ", expr(f.frontier)));
-  if (f.depth !== null) opts.push([`depth ${f.depth}`]);
-  if (f.by) opts.push(cat("by ", expr(f.by)));
-  return cat(`follow${f.distinct ? " distinct" : ""} `, dests, opts.length > 0 ? cat(" { ", join(opts, " "), " }") : "");
+  return cat(`follow${f.distinct ? " distinct" : ""} `, dests);
 }
 
 // ---- where ------------------------------------------------------------------
@@ -229,6 +229,8 @@ function expr(e: Expr): Out {
     case "in": return cat(operand(e.left, CMP + 1), " in ", operand(e.right, CMP + 1));
     case "range":
       return cat(e.lo ? operand(e.lo, ADD) : "", e.exclusiveEnd ? "..." : "..", e.hi ? operand(e.hi, ADD) : "");
+    // A tuple is self-delimiting; its elements are full expressions.
+    case "tuple": return cat("(", join(e.items.map(expr), ", "), ")");
   }
 }