@omgbase/oqx 0.24.0 → 0.26.0

package/src/parser.ts

@@ -13,7 +13,7 @@
 // consumer block — each clause appears at most once, in exactly this order:
 //
 //   select <projection>  from <source>  where <predicate>  follow <dest>, … {…}
-//   order by …  limit N  offset N
+//   flatten <expr> [{…}] [as <name>] …  group by …  having …  order by …  limit N  offset N
 //
 // 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
@@ -24,17 +24,27 @@
 // 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
+// A query names its source BEFORE its body (0.26, the collection-scoped form):
+// `<collection> [<consumer>] [distinct] { body }` — the receiver supplies the
+// rows, so the body never names its source and its `from` is the re-projection
+// (a flatMap). The clause form `select … from S …` is still read as the same
+// tree (its top-level body needs `from`); the printer never writes it. 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. 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
+// (`people { name, age }`); every other clause always carries its keyword. A
+// body with a receiver 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 { age > 50
+// }`, `people exists { age > 50 }`); at the clause form's 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.
 //
+// Two 0.26 shapes desugar HERE as well: a consumer word with no block is the
+// directive over the empty block (`jobs first` ≡ `jobs first { }`, `jobs count
+// > 1`, `_nodes exists`; a consumer word right after a complete receiver can be
+// nothing else), and a projection-only block over a `collect`/`first`/`single`
+// directive whose block projects nothing is that directive's projection
+// (`jobs[0] { name }` ≡ `jobs first { name offset 0 }`, `mergeProjectionBlock`).
+//
 // 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
@@ -83,10 +93,11 @@ 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, TemplatePart, GroupBy, GroupKey, AggregateName,
+  BinaryOp, Span, TemplatePart, Flatten, GroupBy, GroupKey, AggregateName,
 } from "./ast.ts";
 import { AGGREGATE_NAMES, isAggregateName } from "./ast.ts";
 import { resolveSelect, resolveWhere } from "./resolve.ts";
+import { visit } from "./walk.ts";
 import { printTemplate } from "./print.ts";
 
 const CONSUMERS = new Set<string>(["collect", "exists", "none", "count", "first", "single"]);
@@ -96,8 +107,11 @@ const CONSUMERS = new Set<string>(["collect", "exists", "none", "count", "first"
 // `depth` is legal only in a follow destination block, and the order sentence
 // names it only there. `group by` and `having` (0.24) sit after `follow`: the
 // rows a body yields — the walk's occurrences, when it has one — are what gets
-// grouped, and the bound and the ordering then apply to the groups.
-const CLAUSE_ORDER = ["select", "from", "where", "frontier", "depth", "follow", "group by", "having", "order by", "limit", "offset"] as const;
+// grouped, and the bound and the ordering then apply to the groups. `flatten`
+// (0.25) sits between them: it fans the rows a body yields — the occurrences,
+// after a walk — out per element, and is the one clause that may repeat (each
+// `flatten` fans out the rows the previous produced, SEMANTICS §25).
+const CLAUSE_ORDER = ["select", "from", "where", "frontier", "depth", "follow", "flatten", "group by", "having", "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.
@@ -109,7 +123,7 @@ function clausesOf(ctx: BodyCtx): Clause[] {
 const CLAUSE_WORDS = new Set<string>([
   "collect", "exists", "none", "count", "first", "single",
   "order", "by", "asc", "desc", "follow", "distinct", "frontier", "depth", "in", "values",
-  "limit", "offset", "group", "having",
+  "limit", "offset", "group", "having", "flatten", "as",
 ]);
 // The names a group scope resolves besides its keys (SEMANTICS §24): the
 // group's rows, the key record itself, and its identity.
@@ -158,6 +172,7 @@ interface BodyClauses {
   follow: Follow | null;
   frontier: Expr | null;
   depth: number | null;
+  flatten: Flatten[];
   groupBy: GroupBy | null;
   having: Where | null;
   distinct: boolean;
@@ -166,6 +181,30 @@ interface BodyClauses {
   offset: Expr | null;
 }
 
+/** The clauses of an omitted block (`jobs first` — the empty block `{ }`). */
+function emptyBody(): BodyClauses {
+  return { froms: [], where: null, select: [], orderBy: null, follow: null, frontier: null, depth: null, flatten: [], groupBy: null, having: null, distinct: false, values: false, limit: null, offset: null };
+}
+
+/** The names a projection would shadow in a `where` of the same body: every
+ * item's name except a plain self-projection (`pay: pay`, `pay`), which
+ * substitutes a name for itself. */
+function shadowingNames(items: SelectItem[]): string[] {
+  return items
+    .filter((it) => it.name !== "" && !(it.kind === "field" && it.lift === 0 && it.expr.kind === "ident" && it.expr.name === it.name))
+    .map((it) => it.name);
+}
+
+/** Whether a bare identifier anywhere under `w` has one of `names` (the alias
+ * guard of the projection-block merge; conservative: nested blocks included). */
+function readsAnyOf(w: Where, names: string[]): boolean {
+  const wanted = new Set(names.filter((n) => n !== ""));
+  if (wanted.size === 0) return false;
+  let found = false;
+  visit(w, { enter(node) { if (node.kind === "ident" && wanted.has(node.name)) found = true; return !found; } });
+  return found;
+}
+
 // 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 {
@@ -184,6 +223,11 @@ class Parser {
    * 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;
+  /** Whether a consumer word with no block is read as a directive over the
+   * empty block (`jobs first` ≡ `jobs first { }`, since 0.26). Off only while
+   * the clause form's top-level `from` expression is read, so `from people
+   * count` keeps its whole-query hint (a count is never a source). */
+  private bareDirectives = true;
 
   constructor(tokens: Token[]) {
     this.tokens = tokens;
@@ -226,9 +270,10 @@ class Parser {
     const start = this.start();
     // Directive form: `<receiver> <consumer> { … }` consuming the whole query.
     let directive = this.tryOp(false);
-    if (directive && !this.at("eof") && (this.at("lbracket") || this.atValueDirective())) {
+    if (directive && !this.at("eof") && (this.at("lbracket") || this.atBlock() !== null)) {
       // A longer chain whose outermost node is still a directive
-      // (`people first { } first { }` — how `people[p][0]` prints back).
+      // (`people first { } first { }` — how `people[p][0]` prints back; a block
+      // over the directive, `people[0] { name }`, merges into it, 0.26).
       const save = this.pos;
       try {
         const e = this.parsePostfix(directive);
@@ -260,7 +305,7 @@ class Parser {
     const body = this.parseBody(TOP_CTX);
     if (!this.at("eof")) this.fail(`unexpected ${this.tokDesc()} after the query — nothing may follow the last clause`);
     if (body.froms.length === 0) {
-      this.fail("a query must name its source with `from <collection>` (or be `<collection> <consumer> { … }`)");
+      this.fail("a query must name its source before its body: `<collection> { … }` (or `<collection> <consumer> { … }`; the clause form `select … from <collection> …` is still read)");
     }
     return {
       kind: "query",
@@ -273,6 +318,7 @@ class Parser {
       consumer: "collect",
       follow: body.follow,
       frontier: body.frontier,
+      flatten: body.flatten,
       groupBy: body.groupBy,
       having: body.having,
       distinct: body.distinct,
@@ -287,7 +333,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, frontier: e.sub.frontier, groupBy: e.sub.groupBy, having: e.sub.having,
+      orderBy: e.sub.orderBy, consumer: e.op, follow: e.sub.follow, frontier: e.sub.frontier, flatten: e.sub.flatten, groupBy: e.sub.groupBy, having: e.sub.having,
       distinct: e.distinct, values: e.sub.values, limit: e.sub.limit, offset: e.sub.offset,
     };
   }
@@ -310,6 +356,7 @@ class Parser {
     let follow: Follow | null = null;
     let frontier: Expr | null = null;
     let depth: number | null = null;
+    const flatten: Flatten[] = [];
     let groupBy: GroupBy | null = null;
     let having: Where | null = null;
     let distinct = false;
@@ -324,7 +371,9 @@ class Parser {
 
     const enter = (clause: Clause): void => {
       const idx = CLAUSE_ORDER.indexOf(clause);
-      if (idx === stage) this.fail(`duplicate \`${clause}\` clause`);
+      // `flatten` is the one clause that may repeat (0.25): each fans out the
+      // rows the previous produced.
+      if (idx === stage && clause !== "flatten") this.fail(`duplicate \`${clause}\` clause`);
       if (idx < stage) {
         this.fail(`\`${clause}\` must come before \`${CLAUSE_ORDER[stage]}\` — OQX clause order is ${clausesOf(ctx).join(", ")}`);
       }
@@ -342,7 +391,12 @@ class Parser {
       if (this.at("kw", "from")) {
         enter("from");
         this.next();
-        froms.push(this.parseValueExpr());
+        // At the clause form's top level a consumer word after the source is the
+        // whole-query mistake (`from people count`): kept as the hint below,
+        // not read as a braceless directive (a count is never a source).
+        const bare = this.bareDirectives;
+        if (ctx.top) this.bareDirectives = false;
+        try { froms.push(this.parseValueExpr()); } finally { this.bareDirectives = bare; }
         continue;
       }
       if (this.at("kw", "where")) {
@@ -377,6 +431,14 @@ class Parser {
         follow = this.atDepth(rowDepth, () => this.parseFollow());
         continue;
       }
+      // `flatten <expr> [{ … }] [as <name>]` (0.25): the value is read on each
+      // row, like `where`; a brace after a receiver is the receiver-block sugar
+      // (the `collect` op), so the block needs no slot of its own.
+      if (this.atFlatten()) {
+        enter("flatten");
+        flatten.push(this.atDepth(rowDepth, () => this.parseFlatten(flatten)));
+        continue;
+      }
       // `group by k, name: expr` (0.24): the keys are read on the rows, like `where`.
       if (this.atGroupBy()) {
         enter("group by");
@@ -451,11 +513,52 @@ class Parser {
     }
     if (groupBy) {
       if (distinct) this.failAt(groupBy.span[0], DISTINCT_WITH_GROUP);
-      this.checkGroupedBody({ select, resolvedSelect, having, resolvedHaving, orderBy, froms, where: resolvedWhere, frontier, limit, offset, groupBy });
+      this.checkGroupedBody({ select, resolvedSelect, having, resolvedHaving, orderBy, froms, where: resolvedWhere, frontier, flatten, limit, offset, groupBy });
     } else {
-      this.rejectAggregates({ select, resolvedSelect, having: null, resolvedHaving: null, orderBy, froms, where: resolvedWhere, frontier, limit, offset, groupBy: null });
+      this.rejectAggregates({ select, resolvedSelect, having: null, resolvedHaving: null, orderBy, froms, where: resolvedWhere, frontier, flatten, limit, offset, groupBy: null });
     }
-    return { froms, where, select, orderBy, follow, frontier, depth, groupBy, having, distinct, values, limit, offset };
+    return { froms, where, select, orderBy, follow, frontier, depth, flatten, groupBy, having, distinct, values, limit, offset };
+  }
+
+  // ---- flatten (0.25) -------------------------------------------------------
+
+  // `flatten` is a clause when a value can follow the word; otherwise it is a
+  // field name (`select flatten from r`).
+  private atFlatten(): boolean {
+    if (!this.at("ident", "flatten")) return false;
+    const nx = this.peekAt(1);
+    // A value start — or an aggregate call whose name is a consumer word
+    // (`flatten collect(x)`), admitted so the aggregate check can name it.
+    return this.startsValue(nx) || (nx?.type === "ident" && isAggregateName(nx.value) && this.peekAt(2)?.type === "lparen");
+  }
+
+  // `flatten <expr> [as <name>]`. The expression is any value — a block after a
+  // receiver is read by the postfix grammar as the implicit `collect` op (0.20),
+  // which is exactly the block over the coerced collection SEMANTICS §25 wants.
+  // The name defaults to a plain navigation's last segment (as a select item's
+  // or a group key's does); anything else needs `as`. Names are unique within
+  // the body, never a `$`-name (the language's), a keyword or a literal word.
+  private parseFlatten(earlier: readonly Flatten[]): Flatten {
+    const start = this.start();
+    this.next(); // `flatten`
+    const expr = this.parseValueExpr();
+    let name: string;
+    if (this.at("ident", "as")) {
+      this.next();
+      const t = this.peek();
+      if (t.type !== "ident") this.fail("expected a name after `as` (`flatten <expr> as <name>`)");
+      if (LITERAL_WORDS.has(t.value)) this.fail(`\`${t.value}\` is a literal and cannot name a flattened value (\`flatten <expr> as <name>\`)`);
+      if (t.value.startsWith("$")) this.fail(`a flattened value cannot be bound to a \`$\`-name (\`${t.value}\`) — \`$\` belongs to the language; choose another name`);
+      name = this.next().value;
+    } else {
+      const key = navKey(expr);
+      if (key === null) {
+        this.failAt(start, `\`flatten ${describe(expr)}\` needs a name (\`flatten ${describe(expr)} as <name>\`) — only a plain navigation names itself by its last segment`);
+      }
+      name = key;
+    }
+    if (earlier.some((f) => f.name === name)) this.failAt(start, `duplicate flatten name '${name}' — each flatten binds its own name (\`flatten <expr> as <other>\`)`);
+    return { kind: "flatten", span: this.sp(start), expr, name };
   }
 
   // ---- grouping (0.24) ------------------------------------------------------
@@ -555,6 +658,7 @@ class Parser {
     for (const a of where) found.push([a, "`where`"]);
     collect(b.froms, "`from`");
     collect([b.frontier], "`frontier`");
+    collect(b.flatten.map((f) => f.expr), "`flatten`");
     collect([b.limit], "`limit`");
     collect([b.offset], "`offset`");
     if (b.groupBy) collect(b.groupBy.keys.map((k) => k.expr), "a `group by` key");
@@ -713,6 +817,7 @@ class Parser {
       }
       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 (t.value === "flatten") this.fail(`unexpected 'flatten' after \`${last}\` — \`flatten\` takes a value to split into rows (\`flatten <expr> [{ … }] [as <name>]\`)`);
       if (t.value === "group") this.fail(`unexpected 'group' after \`${last}\` — a grouping is written \`group by <key>[, <key>…]\` (a key is a name or \`alias: <expr>\`)`);
       if (t.value === "having") this.fail(`unexpected 'having' after \`${last}\` — \`having\` takes a predicate over each group (\`having count() > 1\`) and belongs to a body that has a \`group by\``);
     }
@@ -921,7 +1026,7 @@ class Parser {
       for (const it of items) {
         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)");
+          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 `<collection> { <predicate> }`, or write `where …` after `from` — at the top level of the clause form 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}`;
@@ -950,8 +1055,9 @@ 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);
+        // `name: jobs first { }.pay`: the directive is the head of a longer value
+        // (a block over it, `jobs[0] { name }`, merges into it — 0.26).
+        if (this.atScalarContinuation() || this.atBlock() !== null) return this.finishItem(name, this.parseOr(op), lift, start);
         if (op.op !== "collect" && op.op !== "first" && op.op !== "single" && op.op !== "count") {
           this.fail(`projection '${name}' must use collect/first/single/count, not ${op.op} (exists/none are where-position tests; \`count { … }\` is a value since 0.24)`);
         }
@@ -1208,13 +1314,18 @@ class Parser {
   }
 
   // The cursor is at a consumer word that opens a block — `<op> {` or
-  // `<op> distinct {`. Consumes nothing.
+  // `<op> distinct {` — or, since 0.26, at the word alone: a consumer word
+  // right after a complete receiver can be nothing else (OQX never places two
+  // operands side by side), and it reads as the directive over the empty block
+  // (`jobs first` ≡ `jobs first { }`, `_nodes exists`, `jobs count > 1`). The
+  // braceless reading is off only inside the clause form's top-level `from`
+  // (`bareDirectives`). 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;
+    return opThenBrace || opDistinctBrace || this.bareDirectives ? (this.peek().value as Consumer) : null;
   }
 
   // `[<op>] [distinct] { <sub> }` over an already-parsed receiver; the cursor is
@@ -1226,20 +1337,32 @@ class Parser {
     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();
-    // `x collect distinct { group by k }`: the directive's distinct is as
-    // redundant as the body's own (checked in parseBody).
-    if (distinct && body.groupBy) this.failAt(body.groupBy.span[0], DISTINCT_WITH_GROUP);
+    let body: BodyClauses;
+    let subSpan: Span;
+    if (this.at("lbrace")) {
+      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.
+      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();
+      // `x collect distinct { group by k }`: the directive's distinct is as
+      // redundant as the body's own (checked in parseBody).
+      if (distinct && body.groupBy) this.failAt(body.groupBy.span[0], DISTINCT_WITH_GROUP);
+      subSpan = this.sp(lbrace);
+    } else {
+      // A consumer word with no block (0.26) is the directive over the empty
+      // block `{ }` — the word was written (only a brace makes a bare
+      // `collect`), so nothing more is consumed; the block spans nothing, at
+      // the end of the word.
+      body = emptyBody();
+      subSpan = [this.end(), this.end()];
+    }
     const sub: Subquery = {
       kind: "subquery",
-      span: this.sp(lbrace),
+      span: subSpan,
       from: body.froms,
       where: body.where,
       select: body.select,
@@ -1247,13 +1370,41 @@ class Parser {
       follow: body.follow,
       frontier: body.frontier,
       depth: body.depth,
+      flatten: body.flatten,
       groupBy: body.groupBy,
       having: body.having,
       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 };
+    return this.mergeProjectionBlock(receiver, op, distinct || body.distinct, sub, startPos);
+  }
+
+  // A projection-only block over a `collect`/`first`/`single` directive whose
+  // own block projects nothing IS that directive's projection (0.26):
+  // `jobs[0] { name }` ≡ `jobs first { name offset 0 }`, `jobs[p] { name }` ≡
+  // `jobs first { name where p }`, `jobs[0] { }` ≡ `jobs[0]`. The outer items
+  // are read on the very rows the inner block filtered, at the same depth, so
+  // the merge is exact — except when the outer block carries a clause of its
+  // own (those run AFTER the pick: `jobs[0] { name where pay > 2 }` is the
+  // first job, kept only if it pays), when the inner directive dedups
+  // (`distinct` compares the projection), or when an outer alias would shadow a
+  // bare name the inner `where` reads (`jobs[pay > 2] { pay: employer }`): then
+  // the two directives stay.
+  private mergeProjectionBlock(receiver: Expr, op: Consumer, distinct: boolean, sub: Subquery, startPos: number): OpNode {
+    const plain: OpNode = { kind: "op", span: this.sp(startPos), receiver, op, sub, countCmp: null, distinct };
+    if (receiver.kind !== "op" || op !== "collect") return plain;
+    const inner = receiver;
+    if ((inner.op !== "collect" && inner.op !== "first" && inner.op !== "single") || inner.distinct || inner.countCmp !== null) return plain;
+    if (inner.sub.select.length > 0 || inner.sub.values) return plain;
+    const projectionOnly = sub.from.length === 0 && sub.where === null && sub.orderBy === null && sub.follow === null && sub.frontier === null
+      && sub.depth === null && sub.flatten.length === 0 && sub.groupBy === null && sub.having === null && sub.limit === null && sub.offset === null;
+    if (!projectionOnly) return plain;
+    if (inner.sub.where && readsAnyOf(inner.sub.where, shadowingNames(sub.select))) return plain;
+    return {
+      kind: "op", span: this.sp(startPos), receiver: inner.receiver, op: inner.op, countCmp: null, distinct,
+      sub: { ...inner.sub, select: sub.select, values: sub.values, span: [inner.sub.span[0], sub.span[1]] },
+    };
   }
 
   // A tuple `(e1, e2, …)` at the cursor's `(` (0.20): two or more comma-separated
@@ -1307,7 +1458,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, frontier: null, depth: null, groupBy: null, having: null, values: false, limit: null, offset: null, ...parts,
+      kind: "subquery", span: subSpan, from: [], where: null, select: [], orderBy: null, follow: null, frontier: null, depth: null, flatten: [], groupBy: null, having: null, values: false, limit: null, offset: null, ...parts,
     });
     const bang = this.atOp("!") ? this.next() : null;
     if (index) {
@@ -1603,6 +1754,7 @@ interface GroupCheck {
   froms: Expr[];
   where: Where | null;
   frontier: Expr | null;
+  flatten: readonly Flatten[];
   limit: Expr | null;
   offset: Expr | null;
   groupBy: GroupBy | null;

package/src/print.ts

@@ -1,10 +1,12 @@
 // The canonical printer (spec/oqx/AST.md §6): the one source text of a tree.
 // Single spaces, double-quoted strings with GRAMMAR §1 escapes, the minimal
-// parentheses the precedence table (GRAMMAR §4) needs, `select` written at the
-// top level, the connectives as the words `and` / `or` (since 0.18; `!` stays
-// `!`), every 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:
+// parentheses the precedence table (GRAMMAR §4) needs, the collection-scoped
+// form `<source> { … }` for every query whose source can head a block (since
+// 0.26; `collect` is the bare brace, every other consumer its word), the
+// projection leading its body without `select`, the connectives as the words
+// `and` / `or` (since 0.18; `!` stays `!`), 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))
 //
@@ -12,15 +14,15 @@
 // binding is a value, never source text: `print` throws on one; `printTemplate`
 // emits template fragments around each binding instead.
 
-import type { AstNode, Expr, Follow, GroupBy, GroupKey, OpNode, OrderSpec, Query, SelectItem, Subquery, Where } from "./ast.ts";
+import type { AstNode, Expr, Flatten, Follow, GroupBy, GroupKey, OpNode, OrderSpec, Query, SelectItem, Subquery, Where } from "./ast.ts";
 import { OqxError } from "./errors.ts";
 
 /** The template form of a tree: `strings` has `count + 1` fragments; the i-th gap
  * stands for the binding `indices[i]` of the printed tree, so a caller re-runs it
  * as `parseTemplate(strings, count)` with the values permuted by `indices`. In a
  * tree straight from `parseTemplate`, `indices` is `0..count-1` unless the
- * canonical clause order moved a binding past another (`${0} collect { x: ${1} }`
- * prints as `select x: ${1} from ${0}`). */
+ * canonical form moved a binding past another (`select x: ${1} from ${0}` prints
+ * as `${0} { x: ${1} }`). */
 export interface Template {
   strings: string[];
   count: number;
@@ -83,6 +85,7 @@ function render(n: AstNode): Out {
     case "subquery": return block(n);
     case "op": return op(n);
     case "follow": return follow(n);
+    case "flatten": return flatten(n);
     case "groupBy": return groupBy(n);
     case "key": return key(n);
     case "order": return order(n);
@@ -95,29 +98,65 @@ function render(n: AstNode): Out {
 // ---- query / bodies ---------------------------------------------------------
 
 function query(q: Query): Out {
-  // Body form for `collect` — unless the query carries body-level `from`
-  // re-projections, which only a block can hold (a second top-level `from` is a
-  // duplicate clause): then the directive form `source collect { … from E }`.
-  if (q.consumer === "collect" && q.from.length === 0) {
-    // `select` is always written — except for a leading bare item literally
-    // named `distinct`, which the keyword would swallow as the modifier.
-    const first = q.select[0];
-    const bareDistinct = !q.distinct && first?.kind === "field" && first.name === "distinct"
-      && first.expr.kind === "ident" && first.expr.name === "distinct";
-    const clauses: Out[] = [];
-    if (q.select.length > 0) {
-      const items = projection(q.select, q.values);
-      clauses.push(bareDistinct ? items : cat(`select ${q.distinct ? "distinct " : ""}`, items));
-    }
-    clauses.push(cat("from ", expr(q.source)));
-    clauses.push(...tail(q));
-    return join(clauses, " ");
+  // The collection-scoped form (since 0.26): `<source> [<consumer>] [distinct]
+  // { body }` — the source heads the body, `collect` is the bare brace (the
+  // directive word is written after an `op` source, where a bare brace is not
+  // read as a block), `distinct` stays on the head.
+  if (canHeadBlock(q.source)) {
+    return cat(expr(q.source), directive(q.consumer, q.distinct, q.source, q));
+  }
+  // A source that cannot head a block — a literal, a template, a range,
+  // arithmetic, a logical or `in` operand, a unary, an aggregate: every one an
+  // eval error or a degenerate query — keeps the clause form `select … from S …`
+  // (a `collect`; another consumer over such a source is unparseable either way).
+  // `select` is always written — except for a leading bare item literally named
+  // `distinct`, which the keyword would swallow as the modifier.
+  const first = q.select[0];
+  const bareDistinct = !q.distinct && first?.kind === "field" && first.name === "distinct"
+    && first.expr.kind === "ident" && first.expr.name === "distinct";
+  const clauses: Out[] = [];
+  if (q.select.length > 0) {
+    const items = projection(q.select, q.values);
+    clauses.push(bareDistinct ? items : cat(`select ${q.distinct ? "distinct " : ""}`, items));
   }
-  // Directive form: `<source> <consumer> [distinct] { body }`.
-  return cat(expr(q.source), ` ${q.consumer}${q.distinct ? " distinct" : ""} `, braces(body(q)));
+  clauses.push(cat("from ", expr(q.source)));
+  clauses.push(...tail(q));
+  return join(clauses, " ");
+}
+
+// Whether `e { … }` parses with `e` as the receiver (GRAMMAR §5 and the postfix
+// chain of §4): a tuple, or a chain — navigation, calls, `!`, directives — whose
+// head is a bare name, an outer reference, a binding or a free call. A literal
+// or template head is "not a collection"; an operator (`-x`, `a + b`, `a..b`,
+// `a in b`, `a or b`) or an aggregate cannot head a receiver.
+function canHeadBlock(e: Expr): boolean {
+  switch (e.kind) {
+    case "ident": case "outer": case "binding": case "tuple": return true;
+    case "call": return e.recv === null || chainHead(e.recv);
+    case "member": return chainHead(e.recv);
+    case "required": return chainHead(e.expr);
+    case "op": return chainHead(e.receiver);
+    default: return false;
+  }
+}
+
+// The head of a postfix chain that may take a block: as `canHeadBlock`, but a
+// tuple is a receiver only on its own (`(a, b).x { … }` is not read as one).
+function chainHead(e: Expr): boolean {
+  return e.kind !== "tuple" && canHeadBlock(e);
 }
 
-type Body = Pick<Subquery, "select" | "values" | "from" | "where" | "follow" | "groupBy" | "having" | "orderBy" | "limit" | "offset">
+// The text between a receiver and its block: ` { ` for the bare-brace `collect`
+// (since 0.26 the canonical spelling), ` distinct { ` for a distinct collect,
+// ` <op> [distinct] { ` for the other consumers — and for a `collect` over an
+// `op` receiver, where a bare brace right after a written directive is not
+// read as a block (`jobs first { offset 0 } collect { … }`).
+function directiveWord(consumer: OpNode["op"], distinct: boolean, receiver: Expr): string {
+  if (consumer === "collect" && receiver.kind !== "op") return distinct ? " distinct " : " ";
+  return ` ${consumer}${distinct ? " distinct" : ""} `;
+}
+
+type Body = Pick<Subquery, "select" | "values" | "from" | "where" | "follow" | "flatten" | "groupBy" | "having" | "orderBy" | "limit" | "offset">
   & Partial<Pick<Subquery, "frontier" | "depth">>;
 
 // The clauses after `from` (a query) or after the projection (a block): the
@@ -130,6 +169,7 @@ function tail(b: Omit<Body, "select" | "values">): Out[] {
   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));
+  for (const f of b.flatten) out.push(flatten(f));
   if (b.groupBy) out.push(groupBy(b.groupBy));
   if (b.having) out.push(cat("having ", where(b.having)));
   if (b.orderBy && b.orderBy.length > 0) out.push(cat("order by ", join(b.orderBy.map(order), ", ")));
@@ -172,17 +212,39 @@ function order(o: OrderSpec): Out {
 function op(o: OpNode): Out {
   return cat(
     receiver(o.receiver),
-    ` ${o.op}${o.distinct ? " distinct" : ""} `,
-    block(o.sub),
+    directive(o.op, o.distinct, o.receiver, o.sub),
     o.countCmp ? ` ${o.countCmp.op} ${number(o.countCmp.value)}` : "",
   );
 }
 
+// A directive's word and block after its receiver: the bare brace for
+// `collect`, the word for every other consumer — and, when the word is written
+// and the block is empty, the word alone (`jobs first`, `_nodes exists`, `jobs
+// count distinct`; since 0.26 an omitted block is the empty block).
+function directive(consumer: OpNode["op"], distinct: boolean, receiver: Expr, b: Body): Out {
+  const word = directiveWord(consumer, distinct, receiver);
+  if (word !== " " && word !== " distinct " && emptyBody(b)) return [word.trimEnd()];
+  return cat(word, braces(body(b)));
+}
+
+function emptyBody(b: Body): boolean {
+  return b.select.length === 0 && !b.values && b.from.length === 0 && b.where === null && (b.frontier ?? null) === null && (b.depth ?? null) === null
+    && b.follow === null && b.flatten.length === 0 && b.groupBy === null && b.having === null && (b.orderBy === null || b.orderBy.length === 0)
+    && b.limit === null && b.offset === null;
+}
+
 function follow(f: Follow): Out {
   const dests = join(f.destinations.map((d) => (d.kind === "op" ? op(d) : expr(d))), ", ");
   return cat(`follow${f.distinct ? " distinct" : ""} `, dests);
 }
 
+// `as <name>` is always written (0.25), as every select item and group key is
+// aliased: the tree does not record whether it was, and the name is what the
+// later clauses read.
+function flatten(f: Flatten): Out {
+  return cat("flatten ", expr(f.expr), ` as ${f.name}`);
+}
+
 // Every key aliased, as every select item is (`layer: layer`).
 function groupBy(g: GroupBy): Out {
   return cat("group by ", join(g.keys.map(key), ", "));