@omgbase/oqx 0.18.0 → 0.21.0

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,14 @@
 // 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.
+//
+// Template literals (0.21): `` `text ${expr} text` `` is a `template` node — a
+// primary value whose interpolations are full expressions read at the current
+// depth (`parseTemplateLiteral`); the lexer balances the braces, so an
+// interpolation may hold a `{ … }` block or another template literal.
+//
 // 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
@@ -71,15 +83,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,
+  BinaryOp, Span, TemplatePart,
 } 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>([
@@ -103,8 +124,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 +147,8 @@ interface BodyClauses {
   select: SelectItem[];
   orderBy: OrderSpec[] | null;
   follow: Follow | null;
+  frontier: Expr | null;
+  depth: number | null;
   distinct: boolean;
   values: boolean;
   limit: Expr | null;
@@ -172,7 +199,10 @@ class Parser {
     return t.type === "op" && t.value === value;
   }
   private fail(msg: string): never {
-    throw new OqxError(`${msg} (at offset ${this.peek().pos})`, "parse");
+    this.failAt(this.peek().pos, msg);
+  }
+  private failAt(pos: number, msg: string): never {
+    throw new OqxError(`${msg} (at offset ${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; }
@@ -231,6 +261,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 +274,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 +295,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 +311,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 +336,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 +403,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 +462,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 +480,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 +557,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 +588,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 +624,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 +813,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 +922,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 +937,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 +957,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 +991,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 +1015,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,12 +1024,33 @@ 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
   // 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`);
+    if (recv.kind === "lit" || recv.kind === "template") 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;
@@ -997,7 +1075,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,10 +1171,14 @@ 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" ||
+    if (t.type === "number" || t.type === "string" || t.type === "tmpl_start" ||
         t.type === "binding" || t.type === "lparen" || t.type === "caret") return true;
     return t.type === "op" && (t.value === "-" || t.value === "!");
   }
@@ -1162,14 +1244,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.
-        if (expr.kind === "lit") this.fail(`\`${describe(expr)}\` is a literal, not a collection`);
-        expr = this.parseConsumerBlock(expr, this.atConsumerBlock()!, false);
+        // 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" || expr.kind === "template") this.fail(`\`${describe(expr)}\` is a literal, not a collection`);
+        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;
@@ -1206,10 +1290,19 @@ class Parser {
     }
     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 === "tmpl_start") return this.parseTemplateLiteral();
     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 withSpan(e, [t.pos, this.end()]);
@@ -1224,6 +1317,39 @@ class Parser {
     }
     this.fail(`unexpected ${this.tokDesc()} — expected a value`);
   }
+
+  // A template literal (GRAMMAR §4, since 0.21): the cursor is at the opening
+  // backtick. The lexer has already split the literal into text runs and `${ … }`
+  // interpolations (with balanced braces, so an interpolation may hold a block
+  // or another template literal); each interpolation holds one full value
+  // expression, read at the current scope depth. `parts` alternates strictly —
+  // text, expression, text, … — with a (possibly empty) text part first and last.
+  private parseTemplateLiteral(): Expr {
+    const open = this.next(); // the backtick
+    const parts: TemplatePart[] = [];
+    let text = "";
+    for (;;) {
+      const t = this.peek();
+      if (t.type === "tmpl_text") { this.next(); text += t.value; continue; }
+      if (t.type === "tmpl_end") { this.next(); break; }
+      if (t.type === "tmpl_interp_start") {
+        this.next();
+        if (this.at("tmpl_interp_end")) {
+          this.failAt(t.pos, "empty interpolation `${}` in a template literal — an interpolation holds an expression (`${name}`)");
+        }
+        const e = this.parseValueExpr();
+        if (!this.at("tmpl_interp_end")) this.fail("expected '}' to close the `${…}` interpolation of a template literal");
+        this.next();
+        parts.push(text, e);
+        text = "";
+        continue;
+      }
+      // Unreachable: the lexer closes every literal it opens or fails.
+      this.fail(`unexpected ${this.tokDesc()} in a template literal`);
+    }
+    parts.push(text);
+    return { kind: "template", span: [open.pos, this.end()], parts };
+  }
 }
 
 // The default key of an unaliased projection item: the last segment of a bare /