@omgbase/oqx 0.24.0 → 0.25.0

package/src/engine.ts

@@ -139,6 +139,8 @@ const HARD_DEPTH_CAP = 8;
 type Projection = Pick<Subquery, "select" | "values">;
 // The grouping clauses of a body (0.24). Both `Query` and `Subquery` carry them.
 type Grouping = Pick<Subquery, "groupBy" | "having">;
+// The `flatten` clauses of a body (0.25). Both `Query` and `Subquery` carry them.
+type Flattening = Pick<Subquery, "flatten">;
 
 // The `$key: expr` item of a projection, if any — the identity the rows it
 // yields carry (SEMANTICS §16, since 0.20).
@@ -182,18 +184,19 @@ export class InMemoryEngine implements Engine {
     const src = this.coerceRows(this.evalRaw(query.source, root), query.source);
     const rows = this.reproject(src.rows, query.from, root);
     // One object as the source yields one record (SEMANTICS §3) — unless a
-    // `from` re-projection or a walk fans it out.
-    const single = src.single && query.from.length === 0 && !query.follow;
+    // `from` re-projection, a walk or a `flatten` fans it out.
+    const single = src.single && query.from.length === 0 && !query.follow && query.flatten.length === 0;
 
     const bound = this.boundOf(query, root);
     if (query.follow) return this.runFollow(query, rows, root, bound);
 
     // Consumer-directed short-circuits (skipped under `distinct`, which must
-    // materialize + dedup by projection before reducing, and under `group by`,
-    // whose consumer counts groups). Counting never materializes rows;
-    // exists/none stop as soon as the bound is known to be non-empty (the
-    // (offset+1)th match — or the first, when unbounded).
-    if (!query.distinct && !query.groupBy && (query.consumer === "exists" || query.consumer === "none" || query.consumer === "count")) {
+    // materialize + dedup by projection before reducing, under `group by`,
+    // whose consumer counts groups, and under `flatten`, whose consumer counts
+    // flattened rows). Counting never materializes rows; exists/none stop as
+    // soon as the bound is known to be non-empty (the (offset+1)th match — or
+    // the first, when unbounded).
+    if (!query.distinct && !query.groupBy && query.flatten.length === 0 && (query.consumer === "exists" || query.consumer === "none" || query.consumer === "count")) {
       const need = query.consumer === "count" ? Infinity : bound.offset + 1;
       let n = 0;
       for (const r of rows) {
@@ -208,7 +211,7 @@ export class InMemoryEngine implements Engine {
     // first over an unordered, non-distinct set needs only the rows up to the
     // bound (offset + 1). single materializes everything so its error can
     // report how many rows actually matched.
-    const cap = query.consumer === "first" && !query.orderBy && !query.distinct && !query.groupBy
+    const cap = query.consumer === "first" && !query.orderBy && !query.distinct && !query.groupBy && query.flatten.length === 0
       ? bound.offset + Math.min(1, bound.limit ?? 1)
       : Infinity;
     let kept: Scope[] = [];
@@ -219,6 +222,7 @@ export class InMemoryEngine implements Engine {
         if (kept.length >= cap) break;
       }
     }
+    if (query.flatten.length > 0) kept = this.flattenScopes(kept, query);
     if (query.groupBy) kept = this.groupScopes(kept, query, root);
     this.applyKey(kept, query);
     this.sortScopes(kept, query.orderBy);
@@ -329,6 +333,44 @@ export class InMemoryEngine implements Engine {
     return s;
   }
 
+  // ---- flatten (SEMANTICS §25) -----------------------------------------------
+
+  // Each `flatten` clause, in writing order, fans the scopes out: the expression
+  // is read in the row's scope (as `where` is) and its value split — an array
+  // (or a host collection) → one scope per element in collection order, so an
+  // empty collection yields none; absent → one scope with the name absent;
+  // anything else (an object, a scalar, a range) → one scope with the value.
+  // A flattened scope IS the parent scope — the same row, parent, lifts and
+  // intrinsics, so `$it`, `^` and `$depth` are unchanged — with the name bound
+  // beside the lifts (step 4 of §2: it shadows a same-named row property) and
+  // `$key` the pair `[parent identity, element identity]` (§16): an element's
+  // identity is the host's (an entry's key), else its structural value.
+  private flattenScopes(scopes: Scope[], body: Flattening): Scope[] {
+    for (const f of body.flatten) {
+      const out: Scope[] = [];
+      for (const s of scopes) {
+        const parentKey = this.scopeIdentity(s);
+        for (const elem of this.flattenElements(this.evalRaw(f.expr, s))) {
+          const key = [parentKey, elem == null ? null : this.hostIdentity(elem)];
+          out.push({ ...s, lifts: { ...(s.lifts ?? {}), [f.name]: elem }, meta: { ...(s.meta ?? {}), [KEY]: key } });
+        }
+      }
+      scopes = out;
+    }
+    return scopes;
+  }
+
+  // The elements a flattened value splits into (§25): §3's coercion with one
+  // softening — a scalar is one element, not an error, since no rows are
+  // sourced from it — and absent as one absent element rather than none.
+  private flattenElements(v: unknown): unknown[] {
+    if (v == null) return [undefined];
+    if (typeof v !== "object" || isRange(v) || isEntry(v)) return [v];
+    if (Array.isArray(v)) return v;
+    const single = this.ctx.isSingle ? this.ctx.isSingle(v) : !(Symbol.iterator in v);
+    return single ? [v] : Array.from(this.ctx.toRows(v));
+  }
+
   // ---- grouping (SEMANTICS §24) ----------------------------------------------
 
   // The kept scopes of a body, one GROUP scope per distinct key tuple, in order
@@ -425,6 +467,7 @@ export class InMemoryEngine implements Engine {
     const occ = this.followWalk(this.keyed(seeds, query, root), query.follow!, query.frontier, root);
     let scopes: Scope[] = occ.map((o) => this.enter(o.row, root, { lifts: {}, meta: o.meta }));
     if (post) scopes = scopes.filter((s) => this.evalWhere(post, s));
+    if (query.flatten.length > 0) scopes = this.flattenScopes(scopes, query);
     if (query.groupBy) scopes = this.groupScopes(scopes, query, root);
     this.sortScopes(scopes, query.orderBy);
     if (query.distinct) scopes = this.dedupByProjection(scopes, query);
@@ -649,10 +692,11 @@ export class InMemoryEngine implements Engine {
         // rows, and the consumer only needs their count after the bound.
         n = boundedCount(acc.rows.length, bound);
         scope.run.trace?.({ kind: "cardinality", count: n });
-      } else if (op.op !== "count" && bound === UNBOUNDED && !op.sub.groupBy) {
+      } else if (op.op !== "count" && bound === UNBOUNDED && !op.sub.groupBy && op.sub.flatten.length === 0) {
         // Unbounded exists/none: stop at the first match (dedup cannot change
-        // emptiness). Bounded, or grouped (`having` may empty the groups): the
-        // offset/limit decide emptiness, so materialize.
+        // emptiness). Bounded, grouped (`having` may empty the groups) or
+        // flattened (an empty collection yields no row): the offset/limit
+        // decide emptiness, so materialize.
         n = this.anyMatch(op, scope, acc) ? 1 : 0;
       } else n = this.opRows(op, scope, bound, acc).length;
       if (op.op === "count") return op.countCmp ? compareCount(n, op.countCmp) : n > 0;
@@ -677,9 +721,10 @@ export class InMemoryEngine implements Engine {
     return this.opRows(op, scope, bound).length > 0;
   }
 
-  // The rows a consumer op reduces: matched → grouped → ordered → distinct → bounded.
+  // The rows a consumer op reduces: matched → flattened → grouped → ordered → distinct → bounded.
   private opRows(op: OpNode, scope: Scope, bound: Bound, acc?: Access): Scope[] {
     let scopes = this.matchRows(op, scope, acc);
+    if (op.sub.flatten.length > 0) scopes = this.flattenScopes(scopes, op.sub);
     if (op.sub.groupBy) scopes = this.groupScopes(scopes, op.sub, scope);
     this.applyKey(scopes, op.sub);
     this.sortScopes(scopes, op.sub.orderBy);
@@ -765,9 +810,9 @@ export class InMemoryEngine implements Engine {
   }
 
   // The plain scan: the rows, re-projected by `from`, with the whole `where`.
-  // A `from` re-projection fans a single receiver out: the block is plural.
+  // A `from` re-projection or a `flatten` fans a single receiver out: the block is plural.
   private scan(src: Rows, op: OpNode, scope: Scope): Access {
-    return { rows: this.reproject(src.rows, op.sub.from, scope), where: op.sub.where, single: src.single && op.sub.from.length === 0 };
+    return { rows: this.reproject(src.rows, op.sub.from, scope), where: op.sub.where, single: src.single && op.sub.from.length === 0 && op.sub.flatten.length === 0 };
   }
 
   private reproject(rows: unknown[], from: readonly Expr[], scope: Scope): unknown[] {
@@ -891,6 +936,7 @@ export class InMemoryEngine implements Engine {
       const { rows, where } = this.access(op, plan, scope);
       const seeds = where ? rows.filter((r) => this.evalWhere(where, this.enter(r, scope, { lifts: {} }))) : rows;
       scopes = this.followWalk(this.keyed(seeds, sub, scope), sub.follow, destination ? null : sub.frontier, scope).map((o) => this.enter(o.row, scope, { meta: o.meta }));
+      if (sub.flatten.length > 0) scopes = this.flattenScopes(scopes, sub);
       if (sub.groupBy) scopes = this.groupScopes(scopes, sub, scope);
       this.sortScopes(scopes, sub.orderBy);
       if (op.distinct) scopes = this.dedupByProjection(scopes, sub);

package/src/optimize/analysis.ts

@@ -72,6 +72,8 @@ function subReadsScopeIn(sub: Subquery, at: number, upTo: number, destination: b
   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;
+  // A `flatten` expression is read on each row (0.25); its block is an op read there.
+  if (sub.flatten.some((f) => exprReadsScopeIn(f.expr, at, upTo))) return true;
   // `group by` keys are read on the rows, `having` on the groups — both at `at` (0.24).
   if (sub.groupBy?.keys.some((k) => exprReadsScopeIn(k.expr, at, upTo))) return true;
   if (sub.having && whereReadsScopeIn(sub.having, at, upTo)) return true;
@@ -148,6 +150,9 @@ export function opRaiseFree(op: OpNode, ctx: RuleContext): boolean {
   if (!sub.from.every((e) => exprRaiseFree(e, ctx))) return false;
   if (sub.where && !whereRaiseFree(sub.where, ctx)) return false;
   if (sub.orderBy && !sub.orderBy.every((o) => exprRaiseFree(o.expr, ctx))) return false;
+  // A `flatten` value is coerced without error (a scalar is one row, §25), so
+  // the clause raises only when its expression does.
+  if (!sub.flatten.every((f) => exprRaiseFree(f.expr, ctx))) return false;
   return !opHasLifts(op);
 }
 
@@ -163,6 +168,7 @@ function subHasLifts(sub: Subquery): boolean {
   if (sub.select.some((item) => (item.kind === "field" ? item.lift > 0 : opHasLifts(item.op)))) return true;
   if (sub.where && whereHasLifts(sub.where)) return true;
   if (sub.having && whereHasLifts(sub.having)) return true;
+  if (sub.flatten.some((f) => f.expr.kind === "op" && opHasLifts(f.expr))) return true;
   if (sub.follow?.destinations.some((d) => d.kind === "op" && opHasLifts(d))) return true;
   return false;
 }

package/src/optimize/ir.ts

@@ -10,7 +10,7 @@
 // cannot be built, a receiver that is not stable) always degrade to the plain
 // scan the plan started from.
 
-import type { Consumer, Expr, Follow, GroupBy, OpNode, OrderSpec, SelectItem, Where } from "../ast.ts";
+import type { Consumer, Expr, Flatten, Follow, GroupBy, OpNode, OrderSpec, SelectItem, Where } from "../ast.ts";
 
 /** One hoisted equality `local == outer` from the block's top-level `&&`
  * conjunction: `local` reads only the block's row (an identifier or member
@@ -45,6 +45,9 @@ export interface BlockPlan {
   readonly distinct: boolean;
   readonly bound: { readonly limit: Expr | null; readonly offset: Expr | null };
   readonly follow: Follow | null;
+  /** `flatten` clauses (0.25): the matched rows are fanned out per element
+   * before the consumer sees them, so a consumer counts FLATTENED rows. */
+  readonly flatten: readonly Flatten[];
   /** `group by` / `having` (0.24): the matched rows are grouped before the
    * consumer sees them, so a consumer counts GROUPS, never rows. */
   readonly groupBy: GroupBy | null;
@@ -94,6 +97,7 @@ export function logicalBlock(node: OpNode, depth: number): BlockPlan {
     distinct: node.distinct,
     bound: { limit: sub.limit, offset: sub.offset },
     follow: sub.follow,
+    flatten: sub.flatten,
     groupBy: sub.groupBy,
     having: sub.having,
     correlated: [],

package/src/optimize/rules.ts

@@ -113,7 +113,8 @@ export const invariantBlock: Rule = (plan) => {
 // Precondition. A where-position `exists`, `none` or `count` without `distinct`
 // (dedup projects every row), without `order by` (`count` evaluates the keys),
 // without `follow`, without `group by` (the consumer counts groups, not rows —
-// 0.24), and with nothing left to evaluate per row: either the block has no
+// 0.24), without `flatten` (the consumer counts flattened rows — 0.25), and
+// with nothing left to evaluate per row: either the block has no
 // `where`, or every conjunct is correlated (so the probe's bucket is the
 // matched set).
 //
@@ -128,7 +129,7 @@ export const invariantBlock: Rule = (plan) => {
 export const cardinalityOnly: Rule = (plan) => {
   if (plan.fromCardinality) return null;
   if (plan.consumer !== "exists" && plan.consumer !== "none" && plan.consumer !== "count") return null;
-  if (plan.distinct || plan.orderBy || plan.follow || plan.groupBy) return null;
+  if (plan.distinct || plan.orderBy || plan.follow || plan.groupBy || plan.flatten.length > 0) return null;
   if (plan.where !== null && plan.residual !== null) return null;
   return { ...plan, fromCardinality: true };
 };

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
@@ -83,7 +83,7 @@ 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";
@@ -96,8 +96,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 +112,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 +161,7 @@ interface BodyClauses {
   follow: Follow | null;
   frontier: Expr | null;
   depth: number | null;
+  flatten: Flatten[];
   groupBy: GroupBy | null;
   having: Where | null;
   distinct: boolean;
@@ -273,6 +277,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 +292,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 +315,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 +330,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(", ")}`);
       }
@@ -377,6 +385,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 +467,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, 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;
     }
-    return { froms, where, select, orderBy, follow, frontier, depth, groupBy, having, distinct, values, limit, offset };
+    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 +612,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 +771,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\``);
     }
@@ -1247,6 +1306,7 @@ class Parser {
       follow: body.follow,
       frontier: body.frontier,
       depth: body.depth,
+      flatten: body.flatten,
       groupBy: body.groupBy,
       having: body.having,
       values: body.values,
@@ -1307,7 +1367,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 +1663,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

@@ -12,7 +12,7 @@
 // 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
@@ -83,6 +83,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);
@@ -117,7 +118,7 @@ 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" | "groupBy" | "having" | "orderBy" | "limit" | "offset">
+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 +131,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), ", ")));
@@ -183,6 +185,13 @@ function follow(f: Follow): Out {
   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), ", "));

package/src/references.ts

@@ -25,7 +25,11 @@
 //     (`target.contains("x")` references `target`); a name a nested block
 //     LIFTS onto a scope (`^open: value`, SEMANTICS §19) is a binding of that
 //     scope, so reading it there (`select open`, `^open` from deeper) is not a
-//     reference either;
+//     reference either — and neither is a name a `flatten` bound (0.25,
+//     SEMANTICS §25) in the clauses after it: a later `flatten`, `group by`,
+//     `having`, the select, `order by`, or `^name` from a block under them; in
+//     its own expression and before the clause (`where`, `frontier`, `follow`)
+//     the name is still the row's property;
 //   • a `select` alias is not a reference where the language resolves it
 //     (SEMANTICS §14): in the same body's `where`, and in the items to its
 //     right — a bare identifier naming such an alias, or a chain headed by it,
@@ -54,7 +58,7 @@
 // are cut after the last step at its scope's depth. The empty list is the root
 // scope.
 
-import type { AstNode, Expr, Follow, GroupBy, Query, SelectItem, Span, Subquery } from "./ast.ts";
+import type { AstNode, Expr, Flatten, Follow, GroupBy, Query, SelectItem, Span, Subquery } from "./ast.ts";
 import type { Clause } from "./walk.ts";
 import { visit } from "./walk.ts";
 
@@ -122,6 +126,9 @@ export function references(root: Query | Subquery): Reference[] {
       const levels = head.kind === "outer" ? head.levels : 0;
       const depth = ctx.depth - levels;
       if (isLiftBound(name, depth, ctx.path, lifts)) return false;
+      // A name a `flatten` bound (0.25) is an alias of the expression already
+      // reported in clause `flatten`, read in the clauses after it.
+      if (isFlattenBound(name, depth, ctx.path, node)) return false;
       // At a group scope (0.24) a bare key name is the key — an alias of the
       // expression reported in clause `groupBy` — and `rows` is the language's
       // value; neither reads a row.
@@ -191,6 +198,31 @@ function liftsLandingOn(body: Query | Subquery): ReadonlySet<string> {
   return names;
 }
 
+/**
+ * Whether `name`, read at scope `depth`, is bound there by a `flatten` of the
+ * body whose rows are at `depth` (SEMANTICS §25) — the position lies in a
+ * clause evaluated after that flatten: a later `flatten`, `group by`, `having`,
+ * the select, or `order by` (`where`, `frontier`, `follow` and the body's
+ * sources run before any flatten, and a flatten's own expression before itself).
+ */
+function isFlattenBound(name: string, depth: number, path: readonly AstNode[], node: AstNode): boolean {
+  const i = bodyIndexAt(path, depth);
+  if (i === -1) return false;
+  const body = path[i] as Query | Subquery;
+  if (body.flatten.length === 0) return false;
+  const child = path[i + 1] ?? node;
+  let upto: number;
+  if (body.select.includes(child as SelectItem) || child === body.groupBy || child === body.having || (body.orderBy?.includes(child as never) ?? false)) {
+    upto = body.flatten.length;
+  } else {
+    const k = body.flatten.indexOf(child as Flatten);
+    if (k === -1) return false;
+    upto = k;
+  }
+  for (let j = 0; j < upto; j++) if (body.flatten[j]!.name === name) return true;
+  return false;
+}
+
 /**
  * Whether `name`, read at scope `depth`, is a value of a GROUP scope there
  * (SEMANTICS §24): the body whose rows are at `depth` has a `group by`, the

package/src/resolve.ts

@@ -26,7 +26,7 @@
 // given. Untouched nodes are returned by reference, so a cached query keeps the
 // identity of every block the rewrite did not reach.
 
-import type { Expr, Follow, FollowDestination, GroupBy, OpNode, Query, SelectItem, Subquery, Where } from "./ast.ts";
+import type { Expr, Flatten, Follow, FollowDestination, GroupBy, OpNode, Query, SelectItem, Subquery, Where } from "./ast.ts";
 import { OqxError } from "./errors.ts";
 
 /** How a resolution failure is reported: the parser raises its positioned parse
@@ -61,6 +61,13 @@ function resolveBody<T extends Query | Subquery>(node: T, fail: Fail): T {
   // The keys are read on the rows, not rewritten (a key IS the name the post-group
   // clauses read); their nested blocks resolve against their own select.
   const groupBy = node.groupBy === null ? null : resolveGroupBy(node.groupBy, fail);
+  // A `flatten` expression (0.25) reads the row, not the projection — like
+  // `order by` and `frontier` it is not rewritten against the select; its
+  // nested blocks resolve against their own select.
+  const flatten = mapSame(node.flatten, (f: Flatten) => {
+    const expr = resolveExpr(f.expr, fail);
+    return expr === f.expr ? f : { ...f, expr };
+  });
   const from = mapSame(node.from, (e) => resolveExpr(e, fail));
   const orderBy = node.orderBy === null ? null : mapSame(node.orderBy, (o) => {
     const expr = resolveExpr(o.expr, fail);
@@ -75,10 +82,10 @@ function resolveBody<T extends Query | Subquery>(node: T, fail: Fail): T {
   const source = node.kind === "query" ? resolveExpr(node.source, fail) : null;
   const same = where2 === node.where && select === node.select && follow === node.follow && from === node.from
     && orderBy === node.orderBy && limit === node.limit && offset === node.offset && frontier === node.frontier
-    && groupBy === node.groupBy && having2 === node.having
+    && groupBy === node.groupBy && having2 === node.having && flatten === node.flatten
     && (node.kind !== "query" || source === node.source);
   if (same) return node;
-  const out = { ...node, where: where2, select, follow, frontier, groupBy, having: having2, from, orderBy, limit, offset };
+  const out = { ...node, where: where2, select, follow, frontier, flatten, groupBy, having: having2, from, orderBy, limit, offset };
   if (node.kind === "query") (out as Query).source = source!;
   return out;
 }

package/src/version.ts

@@ -1,4 +1,4 @@
 /** The OQX language version (`spec/oqx/VERSION`, `major.minor`) this implementation
  * conforms to — distinct from the package's own semver, whose `major.minor` it
  * equals. Stamped on every `toJSON` document. */
-export const LANGUAGE_VERSION = "0.24";
+export const LANGUAGE_VERSION = "0.25";

package/src/walk.ts

@@ -15,6 +15,7 @@ import { LANGUAGE_VERSION } from "./version.ts";
 export type Clause =
   | "source" | "from" | "where" | "select" | "orderBy" | "limit" | "offset"
   | "follow" | "follow.destination" | "follow.frontier"
+  | "flatten" // a `flatten` node and its expression (0.25)
   | "groupBy" | "having"; // the `group by` keys and the post-group predicate (0.24)
 
 /** Where a visited node sits. `depth` is the scope depth at which the node is
@@ -58,6 +59,9 @@ export const CHILDREN: { readonly [K in AstKind]: readonly ChildKey[] } = {
     // The body's `frontier` (0.20) reads each seed in the row scope, like `where`.
     { key: "frontier", clause: "follow.frontier", depth: 1 },
     { key: "follow", clause: "follow", depth: 1 },
+    // A `flatten` expression is read on each row, like `where` (0.25); a
+    // flattened row sits at the same depth as its parent.
+    { key: "flatten", clause: "flatten", depth: 1 },
     // `group by` keys are read on the rows, `having` on the groups — both at
     // the row depth (the group scope sits where the rows did; 0.24).
     { key: "groupBy", clause: "groupBy", depth: 1 },
@@ -76,6 +80,7 @@ export const CHILDREN: { readonly [K in AstKind]: readonly ChildKey[] } = {
     // (`childDepth` tells the two apart by the block's position).
     { key: "frontier", clause: "follow.frontier", depth: -1 },
     { key: "follow", clause: "follow" },
+    { key: "flatten", clause: "flatten" },
     { key: "groupBy", clause: "groupBy" },
     { key: "having", clause: "having" },
     { key: "orderBy", clause: "orderBy" },
@@ -84,6 +89,7 @@ export const CHILDREN: { readonly [K in AstKind]: readonly ChildKey[] } = {
   ],
   op: [{ key: "receiver" }, { key: "sub", depth: 1 }],
   follow: [{ key: "destinations", clause: "follow.destination" }],
+  flatten: [{ key: "expr" }],
   groupBy: [{ key: "keys" }],
   key: [{ key: "expr" }],
   order: [{ key: "expr" }],