@omgbase/oqx 0.15.0 → 0.20.0

package/dist/parser.js

@@ -17,20 +17,52 @@
 //
 // A `follow` destination is a relation of the current row (a receiver, never
 // an outer reference) or a destination block — a receiver (which MAY be an
-// outer reference, `^people`) immediately followed by `collect`/`first`/
-// `single` [`distinct`] `{ body }`, exactly the select-position directive
-// `tryOp(false)` recognizes, re-evaluated per frontier row (language 0.14).
+// outer reference, `^people`, or a tuple `(a, b)`) followed by `{ body }`, or
+// by `collect`/`first`/`single` [`distinct`] `{ body }`, exactly the
+// select-position directive `tryOp` recognizes, re-evaluated per frontier row.
+// Since 0.20 there is no options block: a brace after ANY destination opens
+// that destination's block, whose body admits two clauses no other block has —
+// `frontier P` and `depth n`, in the clause order after `where`.
 //
 // Every clause is optional except that a top-level body needs `from` (the
 // receiver-plus-consumer form `<receiver> <consumer> { block }` supplies the
 // source itself, so its block's `from` is an optional re-projection). Only
 // `select` may drop its keyword, and only when it is the first clause written
-// (`name, age from people`); every other clause always carries its keyword, so
-// a predicate is never implicit — a block filters with `where`. An out-of-order
-// clause is a parse error naming the order. `where` may reference the same
-// body's `select` aliases: after a body is parsed, each bare identifier in its
-// `where` that names an alias is replaced by the alias's expression (a
-// compile-time rewrite — see `inlineAliases`).
+// (`name, age from people`); every other clause always carries its keyword. A
+// BLOCK may instead lead with a predicate (since 0.17): a leading expression that
+// is syntactically a predicate — not a bare name, a dotted navigation or a lift —
+// opens a `where`-first body (`people exists { age > 50 }`); at the top level a
+// leading predicate is still an error, since `where` would precede `from`. An
+// out-of-order clause is a parse error naming the order.
+//
+// Sugar (0.17) desugars HERE, to existing nodes: `x { … }` is `x collect { … }`
+// wherever a value stands (a select item, a where leaf, a follow destination, a
+// call argument — since 0.20 without exception) and `x distinct { … }` is
+// `x collect distinct { … }` (0.20); `x[p]` is `x first { where p }`, `x[n]` is `x first { offset n }`, with a
+// trailing `!` making the first a `single` (predicate) or a `required` (index);
+// `is x` is `!!x`, `not x` is `!x`. Two shapes are new: the postfix `required`
+// (`x!`, tightest) and the identity operators `is` / `is not` (comparison
+// level). A directive may stand in value position (`jobs first { }.pay`), which
+// is how the canonical printer writes a bracket chain back. `where` may reference the same
+// body's `select` aliases: the parser VALIDATES those references (a cycle or a
+// block alias inside an expression is a parse error) but keeps the surface
+// form; `resolveAliases` (resolve.ts) substitutes them before evaluation.
+//
+// Absolute scope references (0.18) desugar HERE too: `N^name` — an unsigned
+// integer literal immediately followed by `^` — is the `outer` reference (or the
+// lift) reaching scope N, i.e. `levels = depth − N`, where `depth` is the
+// syntactic scope depth of the position being parsed (SEMANTICS §2: the root is
+// 0, a top-level row 1, a block's body one deeper than its receiver, a follow
+// `where` one deeper than the frontier row). The parser tracks that depth
+// (`this.depth`) exactly as the `visit` walk computes it; `N >= depth` is a
+// parse error. There is no new node: `print` writes the carets back.
+//
+// Every node carries its `span` — `[start, end)` in code points over the raw
+// source, from the first token that produced it to the end of the last; a
+// parenthesized operand's span includes its parentheses (spec/oqx/AST.md).
+//
+// Tuples (0.20): `(e1, e2, …)` with two or more elements is a `tuple` node — a
+// value and a receiver; one expression in parentheses stays grouping.
 //
 // Principle of least surprise, applied to the grammar: a rule a careful user
 // would not predict is a bug. Hence `!` binds tighter than comparison in every
@@ -42,9 +74,20 @@
 // misreads.
 import { lexTemplate, lexString } from "./lexer.js";
 import { OqxError } from "./errors.js";
+import { resolveSelect, resolveWhere } from "./resolve.js";
+import { printTemplate } from "./print.js";
 const CONSUMERS = new Set(["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"];
+// `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"];
+const DESTINATION_ONLY = new Set(["depth"]);
+// The clauses a body may hold, in order.
+function clausesOf(ctx) {
+    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([
@@ -59,7 +102,7 @@ const MUL_OPS = new Set(["*", "/", "%"]);
 // `true`/`false`/`null` are literals in every position, so they can never name a
 // receiver (`true exists { … }`, `follow null`).
 const LITERAL_WORDS = new Set(["true", "false", "null"]);
-const TOP_CTX = { top: true, op: null, liftsAllowed: false };
+const TOP_CTX = { top: true, op: null, liftsAllowed: false, destination: false };
 /** Parse a tagged-template call into a Query. */
 export function parseTemplate(fragments, values) {
     return new Parser(lexTemplate(fragments, values)).parseQuery();
@@ -68,12 +111,38 @@ export function parseTemplate(fragments, values) {
 export function parseString(src) {
     return new Parser(lexString(src)).parseQuery();
 }
+// A copy of a node with another span (a parenthesized operand takes the span of
+// its parentheses).
+function withSpan(node, span) {
+    return { ...node, span };
+}
 class Parser {
     tokens;
     pos = 0;
+    /** While a block's leading run is read speculatively as a predicate, a bare
+     * `first`/`single` leaf is not rejected on sight: the body decides after the
+     * run is classified (`rejectBareLookups`). */
+    deferLookup = false;
+    /** The scope depth (SEMANTICS §2) at which the construct being parsed is
+     * evaluated: 0 at the root (the top-level source and bounds), 1 for a
+     * top-level row's clauses, one deeper per block body and per follow `where`.
+     * An absolute reference `N^name` reads `depth − N` scopes out. */
+    depth = 0;
     constructor(tokens) {
         this.tokens = tokens;
     }
+    /** Run `f` with the scope depth set to `d`, restoring it afterwards (also on
+     * the error path, so a speculative read that fails leaves the depth intact). */
+    atDepth(d, f) {
+        const saved = this.depth;
+        this.depth = d;
+        try {
+            return f();
+        }
+        finally {
+            this.depth = saved;
+        }
+    }
     // ---- cursor helpers -------------------------------------------------------
     peek() { return this.tokens[this.pos]; }
     peekAt(n) { return this.tokens[this.pos + n]; }
@@ -89,26 +158,54 @@ class Parser {
     fail(msg) {
         throw new OqxError(`${msg} (at offset ${this.peek().pos})`, "parse");
     }
+    /** Code-point offset of the next token (the start of a node about to be parsed). */
+    start() { return this.peek().pos; }
+    /** Code-point offset just past the last consumed token (the end of a node just parsed). */
+    end() { return this.pos === 0 ? 0 : this.tokens[this.pos - 1].end; }
+    sp(start) { return [start, this.end()]; }
     // ---- top level ------------------------------------------------------------
     parseQuery() {
+        const start = this.start();
         // Directive form: `<receiver> <consumer> { … }` consuming the whole query.
-        const directive = this.tryOp(false);
-        if (directive && this.at("eof")) {
-            return {
-                source: directive.receiver,
-                from: directive.sub.from,
-                where: directive.sub.where,
-                select: directive.sub.select,
-                orderBy: directive.sub.orderBy,
-                consumer: directive.op,
-                follow: directive.sub.follow,
-                distinct: directive.distinct ?? false,
-                values: directive.sub.values ?? false,
-                ...bounds(directive.sub),
-            };
+        let directive = this.tryOp(false);
+        if (directive && !this.at("eof") && (this.at("lbracket") || this.atValueDirective())) {
+            // A longer chain whose outermost node is still a directive
+            // (`people first { } first { }` — how `people[p][0]` prints back).
+            const save = this.pos;
+            try {
+                const e = this.parsePostfix(directive);
+                if (e.kind === "op" && this.at("eof"))
+                    directive = e;
+                else
+                    this.pos = save;
+            }
+            catch (err) {
+                if (!(err instanceof OqxError))
+                    throw err;
+                this.pos = save;
+            }
         }
+        if (directive && this.at("eof"))
+            return this.queryFromOp(directive, start);
         if (directive)
             this.fail(`unexpected ${this.tokDesc()} after the top-level directive`);
+        // A bracket chain whose outermost node is a directive is the whole query too
+        // (`people[age > 40]` ≡ `people first { where age > 40 }`). Read
+        // speculatively: anything else (a parse error, a longer expression) is the
+        // body form's business.
+        if (this.at("ident") || this.at("caret") || this.at("binding")) {
+            const save = this.pos;
+            try {
+                const e = this.parsePostfix();
+                if (e.kind === "op" && this.at("eof"))
+                    return this.queryFromOp(e, start);
+            }
+            catch (err) {
+                if (!(err instanceof OqxError))
+                    throw err;
+            }
+            this.pos = save;
+        }
         // Body form: the fixed clause list; its `from` is the source.
         const body = this.parseBody(TOP_CTX);
         if (!this.at("eof"))
@@ -117,6 +214,8 @@ class Parser {
             this.fail("a query must name its source with `from <collection>` (or be `<collection> <consumer> { … }`)");
         }
         return {
+            kind: "query",
+            span: this.sp(start),
             source: body.froms[0],
             from: body.froms.slice(1),
             where: body.where,
@@ -124,9 +223,20 @@ class Parser {
             orderBy: body.orderBy,
             consumer: "collect",
             follow: body.follow,
+            frontier: body.frontier,
             distinct: body.distinct,
             values: body.values,
-            ...bounds(body),
+            limit: body.limit,
+            offset: body.offset,
+        };
+    }
+    // The whole-query form of a directive: its receiver is the source, its block
+    // the body, its consumer the query's.
+    queryFromOp(e, start) {
+        return {
+            kind: "query", span: this.sp(start), source: e.receiver, from: e.sub.from, where: e.sub.where, select: e.sub.select,
+            orderBy: e.sub.orderBy, consumer: e.op, follow: e.sub.follow, frontier: e.sub.frontier, distinct: e.distinct, values: e.sub.values,
+            limit: e.sub.limit, offset: e.sub.offset,
         };
     }
     tokDesc() {
@@ -144,17 +254,23 @@ class Parser {
         let select = [];
         let orderBy = null;
         let follow = null;
+        let frontier = null;
+        let depth = null;
         let distinct = false;
         let values = false;
         let limit = null;
         let offset = null;
         let stage = -1;
+        // A top-level body's row clauses (select/where/follow/order by) are read at
+        // depth 1, its source and bounds at the root (0); a block's clauses are all
+        // at the block's depth, which `parseConsumerBlock` set.
+        const rowDepth = ctx.top ? 1 : this.depth;
         const enter = (clause) => {
             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;
         };
@@ -166,7 +282,7 @@ class Parser {
                     this.next();
                     distinct = true;
                 }
-                ({ items: select, values } = this.parseProjection(ctx));
+                ({ items: select, values } = this.atDepth(rowDepth, () => this.parseProjection(ctx)));
                 continue;
             }
             if (this.at("kw", "from")) {
@@ -178,19 +294,41 @@ class Parser {
             if (this.at("kw", "where")) {
                 enter("where");
                 this.next();
-                where = this.parseWhere();
+                where = this.atDepth(rowDepth, () => this.parseWhere());
+                continue;
+            }
+            // `frontier P` (0.20) — in a follow destination block the destination's
+            // own clause, read in the occurrence's scope whose parent is the walk's
+            // enclosing scope: one level OUT of the block's rows (SEMANTICS §20), so
+            // `^` there is the enclosing scope, not the frontier row. In any other
+            // body it marks the seeds of the body's own `follow` (checked below) and
+            // is read in the seed's scope, like `where`.
+            if (this.at("ident", "frontier") && this.startsValue(this.peekAt(1))) {
+                enter("frontier");
+                this.next();
+                frontier = this.atDepth(ctx.destination ? rowDepth - 1 : rowDepth, () => this.parseValueExpr());
+                continue;
+            }
+            // `depth n` — a follow destination block's own clause (0.20).
+            if (ctx.destination && this.at("ident", "depth") && this.peekAt(1)?.type === "number") {
+                enter("depth");
+                this.next();
+                const v = Number(this.next().value);
+                if (!Number.isInteger(v) || v < 1 || v > 8)
+                    this.fail("follow depth must be an integer between 1 and 8");
+                depth = v;
                 continue;
             }
             if (this.atFollow()) {
                 enter("follow");
-                follow = this.parseFollow();
+                follow = this.atDepth(rowDepth, () => this.parseFollow());
                 continue;
             }
             if (this.atOrderBy()) {
                 enter("order by");
                 this.next();
                 this.next(); // `order` `by`
-                orderBy = this.parseOrderSpecs();
+                orderBy = this.atDepth(rowDepth, () => this.parseOrderSpecs());
                 continue;
             }
             if (this.atBound()) {
@@ -210,25 +348,93 @@ class Parser {
                 continue;
             }
             // A keyword-less run. Before any clause it is the projection (`select` is
-            // the one keyword that may be dropped, and only in first position); after
-            // any clause it is an error — a predicate is never implicit.
+            // the one keyword that may be dropped, and only in first position) — or,
+            // in a block, a leading predicate that opens a `where`-first body. After
+            // any clause it is an error.
             if (stage === -1 && (this.at("ident") || this.at("binding") || this.at("caret") || this.canStartValue())) {
-                enter("select");
-                ({ items: select, values } = this.parseProjection(ctx));
+                const lead = this.atDepth(rowDepth, () => this.parseLeadingRun(ctx));
+                if (lead.where) {
+                    enter("where");
+                    where = lead.where;
+                }
+                else {
+                    enter("select");
+                    ({ items: select, values } = lead.projection);
+                }
                 continue;
             }
             this.failUnexpectedInBody(stage, ctx);
         }
-        where = this.inlineAliases(select, where);
-        return { froms, where, select, orderBy, follow, distinct, values, limit, offset };
+        // Validate the alias references of this body (cycles, a block alias inside a
+        // `where` expression, a `select` item naming an item to its right); the
+        // surface form is kept. `where` first: its cycle report follows its own path.
+        if (where)
+            resolveWhere(select, where, (msg) => this.fail(msg));
+        resolveSelect(select, (msg) => this.fail(msg));
+        // Outside a destination block `frontier` marks the seeds of this body's walk,
+        // so it needs one.
+        if (frontier && !follow && !ctx.destination) {
+            this.fail("`frontier` needs a `follow` — a body's `frontier <expr>` marks which of its rows (the walk's seeds) are frontiers; a destination block's marks the occurrences reached through it");
+        }
+        return { froms, where, select, orderBy, follow, frontier, depth, distinct, values, limit, offset };
+    }
+    // The keyword-less run that opens a body. At the top level it is always the
+    // projection. In a block it is a `where`-first body when the leading expression
+    // is SYNTACTICALLY a predicate (GRAMMAR §2): the run is read as a where tree
+    // first; if that tree is predicate-shaped — anything but a bare name, a dotted
+    // navigation or a lift, with a parenthesized expression counting as a
+    // predicate — and is not the item of a `values` projection, it is the `where`.
+    // Otherwise the tokens are re-read as the projection. When both readings fail,
+    // the error that got further wins (the farthest-failure rule), so a mistake
+    // deep inside `{ jobs exists { … } }` is reported where it is.
+    parseLeadingRun(ctx) {
+        if (!ctx.top) {
+            const save = this.pos;
+            const first = this.peek();
+            let w = null;
+            let specErr = null;
+            let specPos = -1;
+            this.deferLookup = true;
+            try {
+                w = this.parseWhere();
+            }
+            catch (e) {
+                if (!(e instanceof OqxError))
+                    throw e;
+                specErr = e;
+                specPos = this.pos;
+            }
+            finally {
+                this.deferLookup = false;
+            }
+            if (w && predicateShaped(w, first) && !this.at("ident", "values")) {
+                if (this.at("comma")) {
+                    this.fail(`a leading predicate starts a \`where\`-first body, which has no projection — write the projection first: \`{ <projection> where ${describe(w)} }\``);
+                }
+                this.rejectBareLookups(w);
+                return { where: w, projection: null };
+            }
+            this.pos = save;
+            if (specErr) {
+                try {
+                    return { where: null, projection: this.parseProjection(ctx) };
+                }
+                catch (e) {
+                    if (e instanceof OqxError && this.pos < specPos)
+                        throw specErr;
+                    throw e;
+                }
+            }
+        }
+        return { where: null, projection: this.parseProjection(ctx) };
     }
     // The error for a token that starts no clause, phrased for the mistake it most
     // likely is: a bare run right after `from` (the old implicit `where`, or a
     // consumer word where a whole-query directive was meant), or a stray token.
     failUnexpectedInBody(stage, ctx) {
         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
@@ -248,6 +454,13 @@ 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\``);
@@ -255,10 +468,10 @@ class Parser {
         if (last === "from") {
             this.fail(`unexpected ${this.tokDesc()} after \`from\` — a predicate needs \`where\` (there is no implicit where), and a projection goes before \`from\` (\`select … from …\`); expected ${remaining}`);
         }
-        // `{ rel exists { … } }` / `{ rel count { … } >= 2 }`: the leading `rel` was
-        // read as the projection, so the consumer word is where the mistake shows.
+        // `{ name, rel exists { … } }`: the leading items were read as the projection,
+        // so the consumer word is where the mistake shows.
         if (last === "select" && t.type === "ident" && CONSUMERS.has(t.value)) {
-            this.fail(`unexpected \`${t.value}\` after a projection — a consumer test is a predicate: write \`where <relation> ${t.value} { … }\` — a predicate is never implicit; a nested block in a projection needs a name (\`name: <relation> collect { … }\`)`);
+            this.fail(`unexpected \`${t.value}\` after a projection — a consumer test is a predicate: write \`where <relation> ${t.value} { … }\` after the projection (a block may lead with a predicate only when nothing is projected); a nested block in a projection needs a name (\`name: <relation> collect { … }\`)`);
         }
         if (last === null)
             this.fail(`unexpected ${this.tokDesc()} — expected a projection or ${remaining}`);
@@ -274,83 +487,37 @@ class Parser {
         const nx = this.peekAt(1);
         return !!nx && (nx.type === "number" || nx.type === "binding" || nx.type === "caret");
     }
-    // ---- alias inlining -------------------------------------------------------
-    // `where` may reference the same body's `select` aliases. This is a
-    // compile-time rewrite, not a second execution pass: every bare identifier in
-    // the where tree that names an alias is replaced by that alias's expression,
-    // so the engine and any pushdown planner see an ordinary where over row
-    // fields. Rules:
-    //   • an alias shadows a same-named row field inside `where`;
-    //   • an alias's own name inside its own expression is the row field
-    //     (`name: name.upper()` is not recursive), but a chain of aliases that
-    //     comes back to one being resolved (`a: b, b: a`) is a cycle → error;
-    //   • an alias whose value is a `collect`/`first`/`single { … }` block may
-    //     stand alone as a where leaf (a collection in predicate position means
-    //     non-empty) but not appear inside an expression;
-    //   • nested blocks (consumer bodies, follow blocks) are their own scopes and
-    //     are not rewritten against this body's select — each body rewrites
-    //     against its own.
-    inlineAliases(select, where) {
-        if (!where || select.length === 0)
-            return where;
-        const aliases = new Map();
-        for (const it of select) {
-            if (it.kind === "collect")
-                aliases.set(it.name, it);
-            else if (it.lift === 0 && it.name !== "")
-                aliases.set(it.name, it);
-        }
-        if (aliases.size === 0)
-            return where;
-        const resolving = [];
-        const subst = (e) => {
-            switch (e.kind) {
-                case "ident": {
-                    const a = aliases.get(e.name);
-                    if (!a)
-                        return e;
-                    if (resolving[resolving.length - 1] === e.name)
-                        return e; // its own name inside its own expression: the row field
-                    if (resolving.includes(e.name)) {
-                        const cycle = [...resolving.slice(resolving.indexOf(e.name)), e.name].join(" → ");
-                        this.fail(`select aliases form a cycle: ${cycle} — an alias used in \`where\` cannot depend on itself`);
-                    }
-                    if (a.kind === "collect") {
-                        this.fail(`select alias '${e.name}' is a ${a.op.op} { … } block — in \`where\` it can only stand alone as a non-empty test, not inside an expression`);
-                    }
-                    resolving.push(e.name);
-                    const out = subst(a.expr);
-                    resolving.pop();
-                    return out;
-                }
-                case "member": return { ...e, recv: subst(e.recv) };
-                case "index": return { ...e, recv: subst(e.recv), index: subst(e.index) };
-                case "call": return { ...e, recv: e.recv ? subst(e.recv) : null, args: e.args.map(subst) };
-                case "unary": return { ...e, expr: subst(e.expr) };
-                case "binary":
-                case "logical":
-                case "in": return { ...e, left: subst(e.left), right: subst(e.right) };
-                case "range": return { ...e, lo: e.lo ? subst(e.lo) : null, hi: e.hi ? subst(e.hi) : null };
-                default: return e; // lit, binding, outer (`^name` reads an enclosing row, never an alias)
-            }
-        };
-        const walk = (w) => {
-            switch (w.kind) {
-                case "and": return { kind: "and", parts: w.parts.map(walk) };
-                case "or": return { kind: "or", parts: w.parts.map(walk) };
-                case "not": return { kind: "not", expr: walk(w.expr) };
-                case "scalar": {
-                    if (w.expr.kind === "ident") {
-                        const a = aliases.get(w.expr.name);
-                        if (a?.kind === "collect")
-                            return a.op; // a collection in predicate position: non-empty
-                    }
-                    return { kind: "scalar", expr: subst(w.expr) };
-                }
-                case "op": return { ...w, receiver: subst(w.receiver) }; // the receiver is read in this scope; the block is its own scope
+    // Whether the token `n` ahead can head a scope reference: a `^` run, or the
+    // `N^` of an absolute reference.
+    atScopeRefAt(n) {
+        return this.peekAt(n)?.type === "caret" || this.atAbsoluteRefAt(n);
+    }
+    // `N^` — an unsigned integer literal (digits only) immediately followed by a
+    // caret, no whitespace between: an absolute scope reference (GRAMMAR §4).
+    // `1 ^x` is not one (the `^` then fails as a stray token), nor is `1.0^x`.
+    atAbsoluteRef() { return this.atAbsoluteRefAt(0); }
+    atAbsoluteRefAt(n) {
+        const t = this.peekAt(n);
+        const nx = this.peekAt(n + 1);
+        return t?.type === "number" && /^\d+$/.test(t.value) && nx?.type === "caret" && nx.pos === t.end;
+    }
+    // The head of an outer reference or a lift: a run of carets (one scope out
+    // per caret), or an absolute reference `N^` (scope N, GRAMMAR §4), both as the
+    // number of scopes out from the current depth. Returns 0 when there is none.
+    // The absolute form is checked before anything is consumed, so a failing
+    // lookahead (`tryOp`) leaves the cursor on the integer.
+    parseScopeRef() {
+        if (this.atAbsoluteRef()) {
+            const n = this.peek();
+            const target = Number(n.value);
+            if (target >= this.depth) {
+                this.fail(`scope ${n.value} does not enclose this block (the current scope is depth ${this.depth})`);
             }
-        };
-        return walk(where);
+            this.next(); // the integer
+            this.next(); // the caret
+            return this.depth - target;
+        }
+        return this.parseCarets();
     }
     atOrderBy() {
         const t = this.peek();
@@ -363,10 +530,16 @@ class Parser {
         if (!this.at("ident", "follow"))
             return false;
         const nx = this.peekAt(1);
-        return !!nx && (nx.type === "ident" || nx.type === "binding" || nx.type === "caret");
+        return !!nx && (nx.type === "ident" || nx.type === "binding" || nx.type === "lparen" || this.atScopeRefAt(1));
+    }
+    // Whether the cursor is at something that can begin a `follow` destination:
+    // a name, a binding, a scope reference, or a tuple's `(`.
+    atDestinationStart() {
+        return this.at("ident") || this.at("binding") || this.at("lparen") || this.atScopeRefAt(0);
     }
     // ---- follow ---------------------------------------------------------------
     parseFollow() {
+        const start = this.start();
         this.next(); // `follow`
         let distinct = false;
         // After `follow`, `distinct` is a keyword (a relation literally named
@@ -374,102 +547,42 @@ class Parser {
         if (this.at("ident", "distinct")) {
             this.next();
             distinct = true;
-            if (!this.at("ident") && !this.at("binding") && !this.at("caret")) {
+            if (!this.atDestinationStart()) {
                 this.fail("expected a relation after `follow distinct` (`follow distinct <relation>`)");
             }
         }
         const destinations = [this.parseFollowDestination()];
         while (this.at("comma")) {
             this.next();
-            if (!this.at("ident") && !this.at("binding") && !this.at("caret")) {
+            if (!this.atDestinationStart()) {
                 this.fail("expected a relation after ',' (`follow <relation>, <relation>`)");
             }
             destinations.push(this.parseFollowDestination());
         }
-        const follow = { destinations, distinct, where: null, frontier: null, depth: null, by: null };
-        if (!this.at("lbrace"))
-            return follow;
-        this.next(); // '{'
-        while (!this.at("eof") && !this.at("rbrace")) {
-            if (this.at("kw", "where")) {
-                if (follow.where)
-                    this.fail("duplicate `where` in follow clause");
-                this.next();
-                follow.where = this.parseValueExpr();
-            }
-            else if (this.at("ident", "frontier")) {
-                if (follow.frontier)
-                    this.fail("duplicate `frontier` in follow clause");
-                this.next();
-                follow.frontier = this.parseValueExpr();
-            }
-            else if (this.at("ident", "by")) {
-                if (follow.by !== null)
-                    this.fail("duplicate `by` in follow clause");
-                this.next();
-                follow.by = this.parseValueExpr();
-            }
-            else if (this.at("ident", "depth")) {
-                if (follow.depth !== null)
-                    this.fail("duplicate `depth` in follow clause");
-                this.next();
-                if (!this.at("number"))
-                    this.fail("expected an integer after `depth`");
-                const v = Number(this.next().value);
-                if (!Number.isInteger(v) || v < 1 || v > 8)
-                    this.fail("follow depth must be an integer between 1 and 8");
-                follow.depth = v;
-            }
-            else {
-                this.fail(`unexpected ${this.tokDesc()} in follow block — expected where/frontier/depth/by`);
-            }
-        }
-        if (!this.at("rbrace"))
-            this.fail("expected '}' to close the follow block");
-        this.next();
-        return follow;
-    }
-    // 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).
+        return { kind: "follow", span: this.sp(start), destinations, distinct };
+    }
+    // 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.
     parseFollowDestination() {
-        const start = this.pos;
-        let isReceiver = false;
-        if (this.at("binding")) {
-            this.next();
-            isReceiver = true;
-        }
-        else if (this.at("ident") || this.at("caret")) {
-            this.parseCarets();
-            if (this.at("ident")) {
-                this.parseNavFrom(this.next());
-                isReceiver = true;
-            }
-        }
-        if (isReceiver && this.at("ident") && CONSUMERS.has(this.peek().value)) {
-            const op = this.peek().value;
-            const after = this.peekAt(1);
-            const opThenBrace = after?.type === "lbrace";
-            const opDistinctBrace = after?.type === "ident" && after.value === "distinct" && this.peekAt(2)?.type === "lbrace";
-            if (opThenBrace || opDistinctBrace) {
-                if (op !== "collect" && op !== "first" && op !== "single") {
-                    this.fail(`a follow destination must use collect/first/single, not \`${op}\` (exists/none/count are where-position tests)`);
-                }
-                this.pos = start;
-                const block = this.tryOp(false);
-                if (!block)
-                    this.fail("expected a destination block (`<receiver> collect { … }`) after `follow`");
-                return block;
+        const outer = this.atScopeRefAt(0);
+        const op = this.tryOp(false, true);
+        if (op) {
+            if (op.op !== "collect" && op.op !== "first" && op.op !== "single") {
+                this.fail(`a follow destination must use collect/first/single, not \`${op.op}\` (exists/none/count are where-position tests)`);
             }
+            return op;
         }
-        this.pos = start;
-        if (this.at("caret")) {
-            this.fail("`follow` takes a relation of the current row (`follow <relation>`); an outer reference `^name` is not allowed there — it may only head a destination block (`follow ^name collect { … }`)");
+        if (outer) {
+            this.fail("`follow` takes a relation of the current row (`follow <relation>`); an outer reference walks a root collection only as a destination block — `follow ^docs { where … }` or `follow ^docs collect { … }`");
         }
         return this.parseReceiver();
     }
@@ -480,13 +593,23 @@ class Parser {
     // call (`entries(prefs)`), so a computed collection can be consumed directly.
     parseReceiver() {
         if (this.at("binding"))
-            return { kind: "binding", index: this.next().index };
-        const levels = this.parseCarets();
+            return this.bindingNode(this.next());
+        if (this.at("lparen")) {
+            const t = this.tryTuple();
+            if (t)
+                return t;
+            this.fail("expected a collection navigation (a property/relation name) or a tuple `(a, b)`");
+        }
+        const start = this.start();
+        const levels = this.parseScopeRef();
         if (!this.at("ident"))
             this.fail("expected a collection navigation (a property/relation name)");
         if (LITERAL_WORDS.has(this.peek().value))
             this.fail(`\`${this.peek().value}\` is a literal, not a collection`);
-        return this.parseNavFrom(this.next(), levels).expr;
+        return this.parseNavFrom(this.next(), levels, start).expr;
+    }
+    bindingNode(t) {
+        return { kind: "binding", span: [t.pos, t.end], index: t.index };
     }
     // Consume a run of `^` and return its length (0 when there is none).
     parseCarets() {
@@ -498,19 +621,24 @@ class Parser {
         return levels;
     }
     // A dotted navigation chain from `head`; `levels` > 0 makes the head an outer
-    // reference read exactly that many scopes out. A bare head followed by `(` is
-    // a free-function call (`entries(x)`), which may then be navigated further.
-    parseNavFrom(head, levels = 0) {
-        let expr = levels > 0 ? { kind: "outer", levels, name: head.value } : { kind: "ident", name: head.value };
+    // reference read exactly that many scopes out (`start` is then the position
+    // of the first caret). A bare head followed by `(` is a free-function call
+    // (`entries(x)`), which may then be navigated further.
+    parseNavFrom(head, levels = 0, start = head.pos) {
+        let expr = levels > 0
+            ? { kind: "outer", span: [start, head.end], levels, name: head.value }
+            : { kind: "ident", span: [start, head.end], name: head.value };
         let name = head.value;
-        if (levels === 0 && this.at("lparen"))
-            expr = { kind: "call", recv: null, name: head.value, args: this.parseArgs() };
+        if (levels === 0 && this.at("lparen")) {
+            const args = this.parseArgs();
+            expr = { kind: "call", span: this.sp(start), recv: null, name: head.value, args };
+        }
         while (this.at("dot")) {
             this.next();
             if (!this.at("ident"))
                 this.fail("expected a property name after '.'");
             name = this.next().value;
-            expr = { kind: "member", recv: expr, name };
+            expr = { kind: "member", span: this.sp(start), recv: expr, name };
         }
         return { expr, name };
     }
@@ -543,8 +671,13 @@ class Parser {
             // `^^x` bind different rows), so the lift depth is part of the key.
             const seen = new Set();
             for (const it of items) {
-                if (it.name === "")
-                    this.fail("a leading expression is a projection (select): an item that is not a plain name needs an alias (`name: expr`) or `values`; to filter by it write `where …` — a predicate is never implicit");
+                if (it.name === "") {
+                    if (it.kind === "collect")
+                        this.fail("a nested block in a projection needs a name (`name: <relation> collect { … }`); as a predicate, a consumer test is written `where <relation> exists { … }`");
+                    if (ctx.top)
+                        this.fail("a leading expression is a projection (select): an item that is not a plain name needs an alias (`name: expr`) or `values`; to filter by it write `where …` after `from` — at the top level a predicate is never implicit (the clause order puts `from` first)");
+                    this.fail("an item that is not a plain name needs an alias (`name: expr`) or `values`; to filter by it write `where …` after the projection (a block may lead with a predicate only when nothing is projected: `{ age > 18 }`)");
+                }
                 const key = `${"^".repeat(it.kind === "field" ? it.lift : 0)}${it.name}`;
                 if (seen.has(key))
                     this.fail(`duplicate projection name '${it.name}' — each projected item needs its own name (alias one: \`other: expr\`)`);
@@ -554,12 +687,13 @@ class Parser {
         return { items, values };
     }
     parseSelectItem(ctx) {
+        const start = this.start();
         // Leading `^`s mark a lift; the count is how many scopes out it binds. A
         // lift is bound by a `collect { … }` in where position and nowhere else — at
         // the top level, in a select-position block, or in an exists/none/count
         // block it would silently do nothing (or act as a plain field), so it is an
-        // error there.
-        const lift = this.parseCarets();
+        // error there. `N^name:` is the lift into scope N (GRAMMAR §4).
+        const lift = this.parseScopeRef();
         if (!this.at("ident") && !this.canStartValue())
             this.fail("expected a projection name");
         if (lift > 0 && !ctx.liftsAllowed) {
@@ -571,21 +705,31 @@ class Parser {
             this.next(); // ':'
             const op = this.tryOp(false);
             if (op) {
+                // `name: jobs first { }.pay`: the directive is the head of a longer value.
+                if (this.atScalarContinuation() || this.atValueDirective())
+                    return this.finishItem(name, this.parseOr(op), lift, start);
                 if (op.op !== "collect" && op.op !== "first" && op.op !== "single") {
                     this.fail(`projection '${name}' must use collect/first/single, not ${op.op} (exists/none/count are where-position tests)`);
                 }
-                if (lift)
-                    this.fail(`a lift (^${name}) value must be a scalar expression, not ${op.op} { … }`);
-                return { kind: "collect", name, op };
+                return this.finishItem(name, op, lift, start);
             }
-            const expr = this.parseValueExpr();
-            return { kind: "field", name, expr, lift };
+            return this.finishItem(name, this.parseValueExpr(), lift, start);
         }
-        // Unaliased item: a bare/dotted navigation keys by its last segment; any
-        // other expression is unnamed ("") — legal only under `values` (checked by
-        // parseProjection, which sees the whole list).
+        // Unaliased item: a bare/dotted navigation (under any `!`) keys by its last
+        // segment; any other expression is unnamed ("") — legal only under `values`
+        // (checked by parseProjection, which sees the whole list).
         const expr = this.parseValueExpr();
-        return { kind: "field", name: navKey(expr) ?? "", expr, lift };
+        return this.finishItem(navKey(expr) ?? "", expr, lift, start);
+    }
+    // An item from its value: exactly a directive (written out, or the bracket
+    // sugar) is the `collect` item kind; anything else is a `field`.
+    finishItem(name, expr, lift, start) {
+        if (expr.kind === "op") {
+            if (lift)
+                this.fail(`a lift (^${name}) value must be a scalar expression, not ${expr.op} { … }`);
+            return { kind: "collect", span: this.sp(start), name, op: expr };
+        }
+        return { kind: "field", span: this.sp(start), name, expr, lift };
     }
     // ---- order by -------------------------------------------------------------
     parseOrderSpecs() {
@@ -597,6 +741,7 @@ class Parser {
         return specs;
     }
     parseOrderSpec() {
+        const start = this.start();
         const expr = this.parseValueExpr();
         let desc = false;
         if (this.at("ident", "asc"))
@@ -605,7 +750,7 @@ class Parser {
             this.next();
             desc = true;
         }
-        return { expr, desc };
+        return { kind: "order", span: this.sp(start), expr, desc };
     }
     // ---- where boolean tree: or → and → primary --------------------------------
     // `!` is handled in `parseWherePrimary`: it applies to the operand right after
@@ -613,27 +758,33 @@ class Parser {
     // whole comparison — `!a == b` is `(!a) == b`, exactly as in value position.
     parseWhere() { return this.parseWhereOr(); }
     parseWhereOr() {
+        const start = this.start();
         const left = this.parseWhereAnd();
-        if (!this.atOp("||"))
+        if (!this.atOr())
             return left;
         const parts = [left];
-        while (this.atOp("||")) {
+        while (this.atOr()) {
             this.next();
             parts.push(this.parseWhereAnd());
         }
-        return { kind: "or", parts };
+        return { kind: "or", span: this.sp(start), parts };
     }
     parseWhereAnd() {
+        const start = this.start();
         const left = this.parseWherePrimary();
-        if (!this.atOp("&&"))
+        if (!this.atAnd())
             return left;
         const parts = [left];
-        while (this.atOp("&&")) {
+        while (this.atAnd()) {
             this.next();
             parts.push(this.parseWherePrimary());
         }
-        return { kind: "and", parts };
+        return { kind: "and", span: this.sp(start), parts };
     }
+    // `&&` / `and` and `||` / `or` are one operator each (0.17): the words are
+    // exact synonyms of the symbols, parsed to the same nodes.
+    atAnd() { return this.atOp("&&") || this.at("kw", "and"); }
+    atOr() { return this.atOp("||") || this.at("kw", "or"); }
     // A where operand: `[!…] ( where )`, `[!…] <receiver> <consumer> { … }`, or a
     // scalar leaf (a cmp-level expression, which handles its own `!`).
     //
@@ -645,51 +796,112 @@ class Parser {
     // predicate.
     parseWherePrimary() {
         const start = this.pos;
-        let nots = 0;
-        while (this.atOp("!")) {
-            this.next();
-            nots++;
+        // Leading negations: `!`, `not` (one each) and `is` (two — `is x` ≡ `!!x`).
+        const notStarts = [];
+        for (;;) {
+            if (this.atOp("!") || this.at("kw", "not"))
+                notStarts.push(this.next().pos);
+            else if (this.at("kw", "is")) {
+                const p = this.next().pos;
+                notStarts.push(p, p);
+            }
+            else
+                break;
         }
         if (this.at("lparen")) {
-            this.next();
+            // A tuple (0.20) is a value, not a group: the receiver of a consumer test
+            // (`(a, b) exists { }`) or a scalar operand (`(a, b).size() > 1`).
+            const tuple = this.tryTuple();
+            if (tuple) {
+                if (this.atBlock())
+                    return wrapNot(this.finishWhereOp(this.parseConsumerBlock(tuple, this.atBlock(), true)), notStarts);
+                let e = this.parsePostfix(tuple);
+                for (let i = notStarts.length - 1; i >= 0; i--)
+                    e = { kind: "unary", span: [notStarts[i], e.span[1]], op: "!", expr: e };
+                const expr = this.parseCmp(e);
+                return { kind: "scalar", span: expr.span, expr };
+            }
+            const lparen = this.next().pos;
             const inner = this.parseWhere();
             if (!this.at("rparen"))
                 this.fail("expected ')' to close a grouped where expression");
             this.next();
+            const group = [lparen, this.end()];
             if (this.atScalarContinuation()) {
-                let e = this.parsePostfix(this.whereToExpr(inner));
-                for (let i = 0; i < nots; i++)
-                    e = { kind: "unary", op: "!", expr: e };
-                return { kind: "scalar", expr: this.parseCmp(e) };
+                let e = this.parsePostfix(withSpan(this.whereToExpr(inner), group));
+                for (let i = notStarts.length - 1; i >= 0; i--)
+                    e = { kind: "unary", span: [notStarts[i], e.span[1]], op: "!", expr: e };
+                const expr = this.parseCmp(e);
+                return { kind: "scalar", span: expr.span, expr };
             }
-            return wrapNot(inner, nots);
+            return wrapNot(withSpan(inner, group), notStarts);
         }
         const op = this.tryOp(true);
-        if (op)
-            return wrapNot(this.finishWhereOp(op), nots);
+        // A `first`/`single` directive is a value, never a test: the scalar grammar
+        // reads it (as a value-position directive) with whatever follows it, and
+        // `rejectBareLookup` turns a bare one into the lookup error.
+        if (op && op.op !== "first" && op.op !== "single")
+            return wrapNot(this.finishWhereOp(op), notStarts);
         // A scalar leaf, re-read from the first `!` so the scalar grammar gives `!`
         // its one precedence (tighter than comparison). A leaf whose whole value is
         // a negation keeps the `not` node shape (`where !active`).
         this.pos = start;
-        return scalarLeaf(this.parseCmp());
+        const leaf = scalarLeaf(this.parseCmp());
+        if (!this.deferLookup)
+            this.rejectBareLookup(leaf);
+        return leaf;
+    }
+    // A where leaf that is exactly a `first`/`single` directive (under any `!`) is
+    // the select-position lookup error: a lookup is a value, and alone in `where`
+    // the writer almost certainly meant `exists`.
+    rejectBareLookup(w) {
+        let core = w;
+        while (core.kind === "not")
+            core = core.expr;
+        if (core.kind !== "scalar")
+            return;
+        let e = core.expr;
+        while (e.kind === "unary" && e.op === "!")
+            e = e.expr;
+        if (e.kind === "op" && (e.op === "first" || e.op === "single")) {
+            this.fail(`${e.op} { … } is a select-position lookup; in where use exists { … } / none { … } or count { … } <op> N (\`x[p]\` is \`x first { where p }\`; a lookup is a value — compare it, navigate it or require it: \`x[p].name == …\`, \`x[0]!\`)`);
+        }
+    }
+    // `rejectBareLookup` over every leaf of a tree read with `deferLookup` on.
+    rejectBareLookups(w) {
+        switch (w.kind) {
+            case "and":
+            case "or":
+                w.parts.forEach((p) => this.rejectBareLookups(p));
+                return;
+            case "not":
+            case "scalar":
+                this.rejectBareLookup(w);
+                return;
+            case "op": return;
+        }
     }
-    // Whether the token after a `)` continues a scalar expression.
+    // Whether the token after a `)` (or a directive) continues a scalar
+    // expression: an operator, `.`-navigation, a bracket, a postfix `!`, a range,
+    // `in`, or `is`.
     atScalarContinuation() {
         const t = this.peek();
         if (t.type === "op")
-            return CMP_OPS.has(t.value) || ADD_OPS.has(t.value) || MUL_OPS.has(t.value);
-        return t.type === "dot" || t.type === "range" || (t.type === "ident" && t.value === "in");
+            return CMP_OPS.has(t.value) || ADD_OPS.has(t.value) || MUL_OPS.has(t.value) || t.value === "!";
+        if (t.type === "kw")
+            return t.value === "is";
+        return t.type === "dot" || t.type === "range" || t.type === "lbracket" || (t.type === "ident" && t.value === "in");
     }
     // A parenthesized where-group that turned out to be a scalar operand, as an
     // expression. A consumer test has no scalar value, so it cannot be operated on.
     whereToExpr(w) {
         switch (w.kind) {
             case "scalar": return w.expr;
-            case "not": return { kind: "unary", op: "!", expr: this.whereToExpr(w.expr) };
+            case "not": return { kind: "unary", span: w.span, op: "!", expr: this.whereToExpr(w.expr) };
             case "and":
             case "or": {
                 const op = w.kind === "and" ? "&&" : "||";
-                return w.parts.map((p) => this.whereToExpr(p)).reduce((l, r) => ({ kind: "logical", op, left: l, right: r }));
+                return w.parts.map((p) => this.whereToExpr(p)).reduce((l, r) => ({ kind: "logical", span: [l.span[0], r.span[1]], op, left: l, right: r }));
             }
             case "op": {
                 const hint = w.op === "count" ? ` — write \`<relation> count { … } ${this.peek().value} N\` without the parentheses` : "";
@@ -717,74 +929,230 @@ class Parser {
             if (!Number.isInteger(v))
                 this.fail("count comparison takes an integer");
             op.countCmp = { op: relop, value: v };
+            op.span = [op.span[0], this.end()];
         }
         return op;
     }
-    // Detect + parse a postfix consumer op `<receiver> <consumer> { <sub> }`.
-    // Returns null (rewinding) when the lookahead is not a consumer op.
-    tryOp(inWhere) {
+    // Detect + parse a postfix consumer op `<receiver> <consumer> { <sub> }` — or
+    // its implicit-`collect` forms `<receiver> { <sub> }` and `<receiver> distinct
+    // { <sub> }` (0.20). Returns null (rewinding) when the lookahead is not a
+    // directive. `destination` marks a follow destination block (its body admits
+    // `frontier`/`depth`).
+    tryOp(inWhere, destination = false) {
         const start = this.pos;
+        const startPos = this.start();
         let receiver;
+        // An absolute reference that does not enclose this scope is an error only
+        // if the tokens do form a directive (`0^docs collect { }` at the root);
+        // otherwise the expression grammar gets to read them (a top-level `0^name`
+        // item is a lift, with the lift's own error), so the failure is held back
+        // until the lookahead has decided.
+        let scopeErr = null;
         if (this.at("binding"))
-            receiver = { kind: "binding", index: this.next().index };
-        else if (this.at("ident") || this.at("caret")) {
-            const levels = this.parseCarets();
+            receiver = this.bindingNode(this.next());
+        else if (this.at("lparen")) {
+            // A tuple receiver, `(a, b) { … }`; a single parenthesized expression is
+            // grouping and never a receiver.
+            const t = this.tryTuple();
+            if (!t) {
+                this.pos = start;
+                return null;
+            }
+            receiver = t;
+        }
+        else if (this.at("ident") || this.atScopeRefAt(0)) {
+            let levels = 0;
+            try {
+                levels = this.parseScopeRef();
+            }
+            catch (err) {
+                if (!(err instanceof OqxError))
+                    throw err;
+                scopeErr = err;
+                this.next();
+                this.next(); // the integer and the caret, as if it had parsed
+                levels = 1;
+            }
             if (!this.at("ident")) {
                 this.pos = start;
                 return null;
             }
-            receiver = this.parseNavFrom(this.next(), levels).expr;
+            receiver = this.parseNavFrom(this.next(), levels, startPos).expr;
         }
         else
             return null;
-        if (this.at("ident") && CONSUMERS.has(this.peek().value)) {
-            const after = this.peekAt(1);
-            // `<op> { … }` or `<op> distinct { … }`.
-            const opThenBrace = after?.type === "lbrace";
-            const opDistinctBrace = after?.type === "ident" && after.value === "distinct" && this.peekAt(2)?.type === "lbrace";
-            if (opThenBrace || opDistinctBrace) {
-                if (receiver.kind === "ident" && LITERAL_WORDS.has(receiver.name))
-                    this.fail(`\`${receiver.name}\` is a literal, not a collection`);
-                const op = this.next().value;
-                let distinct = false;
-                if (this.at("ident", "distinct")) {
-                    this.next();
-                    distinct = true;
-                }
-                this.next(); // '{'
-                const { sub, distinct: bodyDistinct } = this.parseSubquery({ top: false, op, liftsAllowed: inWhere && op === "collect" });
-                if (!this.at("rbrace"))
-                    this.fail(`expected '}' to close the ${op} { … } block`);
-                this.next();
-                return { kind: "op", receiver, op, sub, distinct: distinct || bodyDistinct };
+        const op = this.atBlock();
+        if (op) {
+            if (scopeErr)
+                throw scopeErr;
+            if (receiver.kind === "ident" && LITERAL_WORDS.has(receiver.name))
+                this.fail(`\`${receiver.name}\` is a literal, not a collection`);
+            // `count { }` with nothing before it: the consumer word is not a receiver.
+            if (op === "collect" && receiver.kind === "ident" && CONSUMERS.has(receiver.name) && this.at("lbrace")) {
+                this.fail(`unexpected '{' after \`${receiver.name}\` — a consumer needs a receiver: \`<collection> ${receiver.name} { … }\``);
             }
+            return this.parseConsumerBlock(receiver, op, inWhere, destination);
         }
         this.pos = start;
         return null;
     }
-    parseSubquery(ctx) {
-        const body = this.parseBody(ctx);
-        return {
-            sub: { from: body.froms, where: body.where, select: body.select, orderBy: body.orderBy, follow: body.follow, values: body.values, ...bounds(body) },
-            distinct: body.distinct,
+    // The cursor is at what opens a block over an already-read receiver: `{` or
+    // `distinct {` (the implicit `collect`), or a consumer word and `{` /
+    // `distinct {`. Consumes nothing.
+    atBlock() {
+        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.
+    atConsumerBlock() {
+        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 : null;
+    }
+    // `[<op>] [distinct] { <sub> }` over an already-parsed receiver; the cursor is
+    // at the consumer word, at `distinct`, or at the `{` of the implicit `collect`.
+    // `destination` marks a follow destination block (0.20): its body may carry
+    // `frontier` and `depth`.
+    parseConsumerBlock(receiver, op, inWhere, destination = false) {
+        const startPos = receiver.span[0];
+        if (this.at("ident") && CONSUMERS.has(this.peek().value))
+            this.next(); // the consumer word (absent for `x { … }`)
+        let distinct = false;
+        if (this.at("ident", "distinct")) {
+            this.next();
+            distinct = true;
+        }
+        const lbrace = this.next().pos; // '{'
+        const defer = this.deferLookup;
+        this.deferLookup = false;
+        // The receiver was read at the enclosing depth; the block's rows are one deeper.
+        const body = this.atDepth(this.depth + 1, () => this.parseBody({ top: false, op, liftsAllowed: inWhere && op === "collect", destination }));
+        this.deferLookup = defer;
+        if (!this.at("rbrace"))
+            this.fail(`expected '}' to close the ${op} { … } block`);
+        this.next();
+        const sub = {
+            kind: "subquery",
+            span: this.sp(lbrace),
+            from: body.froms,
+            where: body.where,
+            select: body.select,
+            orderBy: body.orderBy,
+            follow: body.follow,
+            frontier: body.frontier,
+            depth: body.depth,
+            values: body.values,
+            limit: body.limit,
+            offset: body.offset,
         };
+        return { kind: "op", span: this.sp(startPos), receiver, op, sub, countCmp: null, distinct: distinct || body.distinct };
+    }
+    // A tuple `(e1, e2, …)` at the cursor's `(` (0.20): two or more comma-separated
+    // expressions. A single parenthesized expression is grouping, not a tuple —
+    // the cursor is rewound and null returned (also on a parse error, so the
+    // caller's own reading reports its own error).
+    tryTuple() {
+        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).
+    parseBracket(recv) {
+        if (recv.kind === "lit")
+            this.fail(`\`${describe(recv)}\` is a literal, not a collection`);
+        const start = recv.span[0];
+        const lbracket = this.next().pos; // '['
+        let index = null;
+        let where = null;
+        if (this.at("number") && this.peekAt(1)?.type === "rbracket") {
+            const t = this.next();
+            const v = Number(t.value);
+            if (!Number.isInteger(v))
+                this.fail(`an index is a non-negative integer literal or a binding (got ${t.value})`);
+            index = { kind: "lit", span: [t.pos, t.end], value: v };
+        }
+        else if (this.at("binding") && this.peekAt(1)?.type === "rbracket") {
+            index = this.bindingNode(this.next());
+        }
+        else if (this.atOp("-") && this.peekAt(1)?.type === "number" && this.peekAt(2)?.type === "rbracket") {
+            this.fail("negative indices are not supported (`x[-1]`): an index is a non-negative integer literal or a binding");
+        }
+        else {
+            const defer = this.deferLookup;
+            this.deferLookup = false;
+            // The predicate is the block's `where`: read in the rows' scope, one deeper.
+            where = this.atDepth(this.depth + 1, () => this.parseWhere());
+            this.deferLookup = defer;
+        }
+        if (!this.at("rbracket"))
+            this.fail("expected ']' to close the bracket");
+        this.next();
+        const subSpan = [lbracket, this.end()];
+        const sub = (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) {
+            const op = { kind: "op", span: [start, subSpan[1]], receiver: recv, op: "first", sub: sub({ offset: index }), countCmp: null, distinct: false };
+            return bang ? { kind: "required", span: [start, bang.end], expr: op } : op;
+        }
+        if (bang) {
+            const op = { kind: "op", span: [start, bang.end], receiver: recv, op: "single", sub: sub({ where }), countCmp: null, distinct: false };
+            return { kind: "required", span: [start, bang.end], expr: op };
+        }
+        return { kind: "op", span: [start, subSpan[1]], receiver: recv, op: "first", sub: sub({ where }), countCmp: null, distinct: false };
     }
     // ---- expression Pratt parser ----------------------------------------------
-    // Value position (select/order/follow/source): full boolean+arithmetic.
+    // Value position (select/order/follow/source): full boolean+arithmetic. Each
+    // level takes an optional already-parsed `left` operand (a directive read by
+    // `tryOp`, a promoted where-group), so it continues into the operator tail
+    // without re-reading its tokens.
     parseValueExpr() { return this.parseOr(); }
-    parseOr() {
-        let left = this.parseAnd();
-        while (this.atOp("||")) {
+    parseOr(left) {
+        left = this.parseAnd(left);
+        while (this.atOr()) {
             this.next();
-            left = { kind: "logical", op: "||", left, right: this.parseAnd() };
+            const right = this.parseAnd();
+            left = { kind: "logical", span: [left.span[0], right.span[1]], op: "||", left, right };
         }
         return left;
     }
-    parseAnd() {
-        let left = this.parseCmp();
-        while (this.atOp("&&")) {
+    parseAnd(left) {
+        left = this.parseCmp(left);
+        while (this.atAnd()) {
             this.next();
-            left = { kind: "logical", op: "&&", left, right: this.parseCmp() };
+            const right = this.parseCmp();
+            left = { kind: "logical", span: [left.span[0], right.span[1]], op: "&&", left, right };
         }
         return left;
     }
@@ -798,12 +1166,20 @@ class Parser {
     parseCmp(left) {
         const lhs = this.parseRange(left);
         const t = this.peek();
-        const isCmp = () => (this.peek().type === "op" && CMP_OPS.has(this.peek().value)) || this.at("ident", "in");
+        const isCmp = () => (this.peek().type === "op" && CMP_OPS.has(this.peek().value)) || this.at("ident", "in") || this.at("kw", "is");
         if (!isCmp())
             return lhs;
-        const op = this.next().value;
+        let op = this.next().value;
+        // `is` / `is not` — identity (SEMANTICS §5b); `is not` is the compound.
+        if (op === "is" && this.at("kw", "not")) {
+            this.next();
+            op = "is not";
+        }
         const rhs = this.parseRange();
-        const result = op === "in" ? { kind: "in", left: lhs, right: rhs } : { kind: "binary", op, left: lhs, right: rhs };
+        const span = [lhs.span[0], rhs.span[1]];
+        const result = op === "in"
+            ? { kind: "in", span, left: lhs, right: rhs }
+            : { kind: "binary", span, op: op, left: lhs, right: rhs };
         if (isCmp()) {
             this.fail(`comparisons do not chain: \`a ${t.value} b ${this.peek().value} c\` — write two comparisons joined with \`&&\``);
         }
@@ -816,16 +1192,19 @@ class Parser {
     // opens the high end.
     parseRange(left) {
         if (left === undefined && this.at("range")) {
-            const exclusiveEnd = this.next().value === "...";
+            const tok = this.next();
+            const exclusiveEnd = tok.value === "...";
             if (!this.canStartValue())
                 this.fail("a range needs at least one bound: `lo..hi`, `lo..`, or `..hi`");
-            return { kind: "range", lo: null, hi: this.parseAdd(), exclusiveEnd };
+            const hi = this.parseAdd();
+            return { kind: "range", span: [tok.pos, hi.span[1]], lo: null, hi, exclusiveEnd };
         }
         const lo = this.parseAdd(left);
         if (this.at("range")) {
-            const exclusiveEnd = this.next().value === "...";
+            const tok = this.next();
+            const exclusiveEnd = tok.value === "...";
             const hi = this.canStartValue() ? this.parseAdd() : null;
-            return { kind: "range", lo, hi, exclusiveEnd };
+            return { kind: "range", span: [lo.span[0], hi ? hi.span[1] : tok.end], lo, hi, exclusiveEnd };
         }
         return lo;
     }
@@ -835,9 +1214,15 @@ 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.
     canStartValue() {
-        const t = this.peek();
+        return this.startsValue(this.peek());
+    }
+    startsValue(t) {
+        if (!t)
+            return false;
         if (t.type === "ident")
             return !CLAUSE_WORDS.has(t.value);
+        if (t.type === "kw")
+            return t.value === "is" || t.value === "not"; // the prefix operators
         if (t.type === "number" || t.type === "string" ||
             t.type === "binding" || t.type === "lparen" || t.type === "caret")
             return true;
@@ -847,7 +1232,8 @@ class Parser {
         left = this.parseMul(left);
         while (this.peek().type === "op" && ADD_OPS.has(this.peek().value)) {
             const op = this.next().value;
-            left = { kind: "binary", op, left, right: this.parseMul() };
+            const right = this.parseMul();
+            left = { kind: "binary", span: [left.span[0], right.span[1]], op, left, right };
         }
         return left;
     }
@@ -855,25 +1241,30 @@ class Parser {
         left = this.parseUnary(left);
         while (this.peek().type === "op" && MUL_OPS.has(this.peek().value)) {
             const op = this.next().value;
-            left = { kind: "binary", op, left, right: this.parseUnary() };
+            const right = this.parseUnary();
+            left = { kind: "binary", span: [left.span[0], right.span[1]], op, left, right };
         }
         return left;
     }
     parseUnary(left) {
         if (left !== undefined)
             return this.parsePostfix(left);
-        if (this.atOp("!")) {
-            this.next();
-            return { kind: "unary", op: "!", expr: this.parseUnary() };
-        }
-        if (this.atOp("-")) {
-            this.next();
-            return { kind: "unary", op: "-", expr: this.parseUnary() };
+        if (this.atOp("!") || this.atOp("-") || this.at("kw", "is") || this.at("kw", "not")) {
+            const tok = this.next();
+            const expr = this.parseUnary();
+            const span = [tok.pos, expr.span[1]];
+            // `is x` ≡ `!!x`, `not x` ≡ `!x`: pure sugar, both nodes spanning the sugar.
+            if (tok.type === "kw") {
+                const not = { kind: "unary", span, op: "!", expr };
+                return tok.value === "is" ? { kind: "unary", span, op: "!", expr: not } : not;
+            }
+            return { kind: "unary", span, op: tok.value, expr };
         }
         return this.parsePostfix();
     }
     parsePostfix(left) {
         let expr = left ?? this.parsePrimary();
+        const start = expr.span[0];
         for (;;) {
             if (this.at("dot")) {
                 this.next();
@@ -881,25 +1272,47 @@ class Parser {
                     this.fail("expected a property name after '.'");
                 const name = this.next().value;
                 if (this.at("lparen")) {
-                    expr = { kind: "call", recv: expr, name, args: this.parseArgs() };
+                    const args = this.parseArgs();
+                    expr = { kind: "call", span: this.sp(start), recv: expr, name, args };
                 }
                 else {
-                    expr = { kind: "member", recv: expr, name };
+                    expr = { kind: "member", span: this.sp(start), recv: expr, name };
                 }
             }
             else if (this.at("lparen") && left === undefined && expr.kind === "ident") {
                 // free function call: name(args) — a bare name read here, not `(f)(x)`
-                expr = { kind: "call", recv: null, name: expr.name, args: this.parseArgs() };
+                const args = this.parseArgs();
+                expr = { kind: "call", span: this.sp(start), recv: null, name: expr.name, args };
+            }
+            else if (this.at("lbracket")) {
+                expr = this.parseBracket(expr);
+            }
+            else if (this.atOp("!")) {
+                // Postfix `!`: a `!` right after a complete chain is `required` — OQX
+                // never places two operands side by side, so it cannot begin one here.
+                const bang = this.next();
+                expr = { kind: "required", span: [start, bang.end], expr };
             }
-            else if (this.at("lbrace")) {
-                break; // a consumer block boundary — not part of a value expression
+            else if (this.atValueDirective() || this.at("lbrace") || (this.at("ident", "distinct") && this.peekAt(1)?.type === "lbrace")) {
+                // A value-position directive, `recv first { … }` — how a bracket chain
+                // prints back — or the implicit `collect` of a bare `{ … }` / `distinct
+                // { … }` (0.20: the receiver-block sugar stands wherever a value does,
+                // `size(children { is checked })`). exists/none/count have no value form
+                // and are left to the body's own error.
+                if (expr.kind === "lit")
+                    this.fail(`\`${describe(expr)}\` is a literal, not a collection`);
+                expr = this.parseConsumerBlock(expr, this.atBlock(), false);
             }
             else {
-                break;
+                break; // anything else ends the chain
             }
         }
         return expr;
     }
+    atValueDirective() {
+        const op = this.atConsumerBlock();
+        return op === "collect" || op === "first" || op === "single";
+    }
     parseArgs() {
         this.next(); // '('
         const args = [];
@@ -921,41 +1334,55 @@ class Parser {
         // select-item head `^name:` is a lift, handled in parseSelectItem; here, in
         // expression position, `^` reads an enclosing row's field even when the
         // current row shadows the name.)
-        if (t.type === "caret") {
-            const levels = this.parseCarets();
+        if (t.type === "caret" || this.atAbsoluteRef()) {
+            const levels = this.parseScopeRef();
             if (!this.at("ident"))
                 this.fail("expected an identifier after '^' (an outer reference)");
-            return { kind: "outer", levels, name: this.next().value };
+            const name = this.next();
+            return { kind: "outer", span: [t.pos, name.end], levels, name: name.value };
         }
         if (t.type === "number") {
             this.next();
-            return { kind: "lit", value: Number(t.value) };
+            return { kind: "lit", span: [t.pos, t.end], value: Number(t.value) };
         }
         if (t.type === "string") {
             this.next();
-            return { kind: "lit", value: t.value };
+            return { kind: "lit", span: [t.pos, t.end], value: t.value };
         }
         if (t.type === "binding") {
             this.next();
-            return { kind: "binding", index: t.index };
+            return this.bindingNode(t);
         }
         if (t.type === "lparen") {
             this.next();
             const e = this.parseValueExpr();
+            if (this.at("comma")) {
+                // A tuple `(e1, e2, …)` (0.20): two or more elements.
+                const items = [e];
+                while (this.at("comma")) {
+                    this.next();
+                    items.push(this.parseValueExpr());
+                }
+                if (!this.at("rparen"))
+                    this.fail("expected ')' to close the tuple");
+                this.next();
+                return { kind: "tuple", span: [t.pos, this.end()], items };
+            }
             if (!this.at("rparen"))
                 this.fail("expected ')'");
             this.next();
-            return e;
+            return withSpan(e, [t.pos, this.end()]);
         }
         if (t.type === "ident") {
             this.next();
+            const span = [t.pos, t.end];
             if (t.value === "true")
-                return { kind: "lit", value: true };
+                return { kind: "lit", span, value: true };
             if (t.value === "false")
-                return { kind: "lit", value: false };
+                return { kind: "lit", span, value: false };
             if (t.value === "null")
-                return { kind: "lit", value: null };
-            return { kind: "ident", name: t.value };
+                return { kind: "lit", span, value: null };
+            return { kind: "ident", span, name: t.value };
         }
         this.fail(`unexpected ${this.tokDesc()} — expected a value`);
     }
@@ -967,25 +1394,45 @@ function navKey(e) {
         case "ident": return e.name;
         case "outer": return e.name;
         case "member": return e.name;
+        case "required": return navKey(e.expr);
         default: return null;
     }
 }
-// `!` applied `n` times to a where node.
-function wrapNot(w, n) {
-    for (let i = 0; i < n; i++)
-        w = { kind: "not", expr: w };
+// Whether a block's leading run, read as a where tree, is syntactically a
+// predicate (GRAMMAR §2): anything but a bare name, a dotted navigation or a lift
+// (an `outer`), with a parenthesized leading expression always a predicate.
+function predicateShaped(w, first) {
+    if (first.type === "lparen")
+        return true;
+    if (w.kind !== "scalar")
+        return true;
+    return !isNavigation(w.expr);
+}
+function isNavigation(e) {
+    switch (e.kind) {
+        case "ident":
+        case "outer": return true;
+        case "member": return isNavigation(e.recv);
+        default: return false;
+    }
+}
+// The canonical text of a node for an error message; a binding shows as its
+// `${n}` marker (the printer refuses to turn a bound value into source).
+function describe(node) {
+    const t = printTemplate(node);
+    return t.strings.map((s, i) => (i < t.count ? `${s}\${${t.indices[i]}}` : s)).join("");
+}
+// `!` applied once per recorded `!` position to a where node, innermost first.
+function wrapNot(w, notStarts) {
+    for (let i = notStarts.length - 1; i >= 0; i--)
+        w = { kind: "not", span: [notStarts[i], w.span[1]], expr: w };
     return w;
 }
 // A scalar where leaf. A leading `!` on the whole leaf becomes a `not` node (so
 // `where !active` keeps its shape); inside a comparison it stays a unary `!`.
 function scalarLeaf(e) {
     if (e.kind === "unary" && e.op === "!")
-        return { kind: "not", expr: scalarLeaf(e.expr) };
-    return { kind: "scalar", expr: e };
-}
-// The optional `limit`/`offset` fields of a Query/Subquery, present only when set
-// (so a Query built without them is unchanged).
-function bounds(b) {
-    return { ...(b.limit ? { limit: b.limit } : {}), ...(b.offset ? { offset: b.offset } : {}) };
+        return { kind: "not", span: e.span, expr: scalarLeaf(e.expr) };
+    return { kind: "scalar", span: e.span, expr: e };
 }
 //# sourceMappingURL=parser.js.map