@omgbase/oqx 0.10.2 → 0.13.0

package/dist/parser.js

@@ -9,12 +9,36 @@
 //   2. Whitespace directives (collect/exists/count/first/single) belong to OQX —
 //      a consumer is `<receiver> <directive> { <block> }`, never a method.
 //
-// Departure from the reference parser: top-level clauses may appear in any order,
-// so the SQL-style projection-first form `name, id from ${people} where …` is
-// accepted (the reference requires `from` first).
+// Clause order is FIXED (ADR-020). Within one clause body — the top level or a
+// consumer block — each clause appears at most once, in exactly this order:
+//
+//   select <projection>  from <source>  where <predicate>  follow <relation> {…}
+//   order by …  limit N  offset N
+//
+// 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`).
+//
+// Principle of least surprise, applied to the grammar: a rule a careful user
+// would not predict is a bug. Hence `!` binds tighter than comparison in every
+// position (`!a == b` is `(!a) == b`, as in C); parentheses in `where` group a
+// predicate OR a scalar, decided by what follows the `)`; a range's open end
+// stops at a clause word; duplicate projection names, a `follow distinct` with
+// no relation, a lift outside a where-position `collect`, and a top-level
+// `limit ^n` (there is no enclosing scope) are parse errors rather than silent
+// misreads.
 import { lexTemplate, lexString } from "./lexer.js";
 import { OqxError } from "./errors.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"];
 // 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([
@@ -26,6 +50,10 @@ const RELOPS = new Set(["==", "!=", "<", "<=", ">", ">="]);
 const CMP_OPS = new Set(["==", "!=", "<", "<=", ">", ">="]);
 const ADD_OPS = new Set(["+", "-"]);
 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 };
 /** Parse a tagged-template call into a Query. */
 export function parseTemplate(fragments, values) {
     return new Parser(lexTemplate(fragments, values)).parseQuery();
@@ -58,7 +86,7 @@ class Parser {
     // ---- top level ------------------------------------------------------------
     parseQuery() {
         // Directive form: `<receiver> <consumer> { … }` consuming the whole query.
-        const directive = this.tryOp();
+        const directive = this.tryOp(false);
         if (directive && this.at("eof")) {
             return {
                 source: directive.receiver,
@@ -75,12 +103,12 @@ class Parser {
         }
         if (directive)
             this.fail(`unexpected ${this.tokDesc()} after the top-level directive`);
-        // Body form: order-flexible clauses; the first `from` is the source.
-        const body = this.parseBody(true);
+        // Body form: the fixed clause list; its `from` is the source.
+        const body = this.parseBody(TOP_CTX);
         if (!this.at("eof"))
-            this.fail(`unexpected ${this.tokDesc()} after the query`);
+            this.fail(`unexpected ${this.tokDesc()} after the query — nothing may follow the last clause`);
         if (body.froms.length === 0) {
-            this.fail("a query must select a source with `from <collection>`");
+            this.fail("a query must name its source with `from <collection>` (or be `<collection> <consumer> { … }`)");
         }
         return {
             source: body.froms[0],
@@ -100,7 +128,11 @@ class Parser {
         return t.type === "eof" ? "end of query" : `'${t.value || t.type}'`;
     }
     // ---- clause body (shared by top level and consumer blocks) ----------------
-    parseBody(orderByAllowed) {
+    // An ordered state machine over the fixed clause sequence: `stage` is the
+    // index (in CLAUSE_ORDER) of the last clause parsed, so a clause with a lower
+    // index is out of order and an equal index is a duplicate. The only
+    // keyword-less clause is a leading projection (while `stage` is still -1).
+    parseBody(ctx) {
         const froms = [];
         let where = null;
         let select = [];
@@ -110,83 +142,122 @@ class Parser {
         let values = false;
         let limit = null;
         let offset = null;
-        let sawWhere = false, sawSelect = false, sawOrder = false;
+        let stage = -1;
+        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(", ")}`);
+            }
+            stage = idx;
+        };
         while (!this.at("eof") && !this.at("rbrace")) {
-            if (this.atFollow()) {
-                if (follow)
-                    this.fail("duplicate `follow` clause");
-                follow = this.parseFollow();
+            if (this.at("kw", "select")) {
+                enter("select");
+                this.next();
+                if (this.at("ident", "distinct")) {
+                    this.next();
+                    distinct = true;
+                }
+                ({ items: select, values } = this.parseProjection(ctx));
                 continue;
             }
             if (this.at("kw", "from")) {
+                enter("from");
                 this.next();
                 froms.push(this.parseValueExpr());
                 continue;
             }
             if (this.at("kw", "where")) {
-                if (sawWhere)
-                    this.fail("duplicate `where` clause");
-                sawWhere = true;
+                enter("where");
                 this.next();
                 where = this.parseWhere();
                 continue;
             }
-            if (this.at("kw", "select") || this.at("caret")) {
-                if (sawSelect)
-                    this.fail("duplicate projection");
-                sawSelect = true;
-                if (this.at("kw")) {
-                    this.next();
-                    if (this.at("ident", "distinct")) {
-                        this.next();
-                        distinct = true;
-                    }
-                } // consume `select` + optional `distinct`; a leading `^` is part of the item
-                ({ items: select, values } = this.parseProjection());
-                continue;
-            }
-            if (this.atBound()) {
-                const word = this.next().value;
-                const e = this.parsePostfix();
-                if (word === "limit") {
-                    if (limit)
-                        this.fail("duplicate `limit` clause");
-                    limit = e;
-                }
-                else {
-                    if (offset)
-                        this.fail("duplicate `offset` clause");
-                    offset = e;
-                }
+            if (this.atFollow()) {
+                enter("follow");
+                follow = this.parseFollow();
                 continue;
             }
-            if (orderByAllowed && this.atOrderBy()) {
-                if (sawOrder)
-                    this.fail("duplicate `order by` clause");
-                sawOrder = true;
+            if (this.atOrderBy()) {
+                enter("order by");
                 this.next();
                 this.next(); // `order` `by`
                 orderBy = this.parseOrderSpecs();
                 continue;
             }
-            if (this.looksLikePredicate()) {
-                if (sawWhere)
-                    this.fail("duplicate `where` (an implicit predicate cannot follow a `where`)");
-                sawWhere = true;
-                where = this.parseWhere();
+            if (this.atBound()) {
+                const word = this.peek().value;
+                enter(word);
+                this.next();
+                // A top-level bound is evaluated at the root scope itself, so `^n` there
+                // has nothing to read: say so now instead of an "absent" error at eval.
+                if (ctx.top && this.at("caret")) {
+                    this.fail(`\`${word} ^…\` at the top level has no enclosing scope — a top-level bound is a number literal or a binding; inside a block \`^name\` reads the enclosing row`);
+                }
+                const e = this.parsePostfix();
+                if (word === "limit")
+                    limit = e;
+                else
+                    offset = e;
                 continue;
             }
-            if (this.at("ident") || this.at("binding")) {
-                if (sawSelect)
-                    this.fail("duplicate projection (an implicit select cannot follow a `select`)");
-                sawSelect = true;
-                ({ items: select, values } = this.parseProjection());
+            // 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.
+            if (stage === -1 && (this.at("ident") || this.at("binding") || this.at("caret") || this.canStartValue())) {
+                enter("select");
+                ({ items: select, values } = this.parseProjection(ctx));
                 continue;
             }
-            this.fail(`unexpected ${this.tokDesc()} — expected from/where/select${orderByAllowed ? "/order by" : ""}/limit/offset/follow`);
+            this.failUnexpectedInBody(stage, ctx);
         }
+        where = this.inlineAliases(select, where);
         return { froms, where, select, orderBy, follow, distinct, values, limit, offset };
     }
+    // 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 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
+        // the projection hint below — `name from r, id` almost always meant a
+        // projection.)
+        if (last !== null && !isWord && t.type !== "comma") {
+            if (ctx.top)
+                this.fail(`unexpected ${this.tokDesc()} after the query — nothing may follow the last clause (expected ${remaining} or the end of the query)`);
+            this.fail(`unexpected ${this.tokDesc()} in the ${ctx.op} { … } block — expected ${remaining} or '}' to close the block`);
+        }
+        // Clause words that did not form a clause: say what the clause needs.
+        if (last !== null && t.type === "ident") {
+            if (t.value === "order")
+                this.fail(`unexpected 'order' after \`${last}\` — an ordering is written \`order by <expr> [asc|desc]\``);
+            if (t.value === "follow")
+                this.fail(`unexpected 'follow' after \`${last}\` — \`follow\` needs a relation: \`follow <relation>\` or \`follow distinct <relation>\``);
+            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 (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\``);
+        }
+        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.
+        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 { … }\`)`);
+        }
+        if (last === null)
+            this.fail(`unexpected ${this.tokDesc()} — expected a projection or ${remaining}`);
+        this.fail(`unexpected ${this.tokDesc()} after \`${last}\` — expected ${remaining}`);
+    }
     // `limit <n>` / `offset <n>` — the word must be followed by something that can
     // be a bound (a number, a binding, or an outer reference), so a field that
     // happens to be called `limit` still projects/filters as a bare name.
@@ -197,79 +268,113 @@ class Parser {
         const nx = this.peekAt(1);
         return !!nx && (nx.type === "number" || nx.type === "binding" || nx.type === "caret");
     }
-    // Decide, by syntactic shape only, whether a leading unkeyworded run is a
-    // predicate (→ implicit where) or a projection (→ implicit select). A depth-0
-    // comparison / && / || / `in` before any comma/colon marks a predicate; a bare
-    // reference or a `name:`/comma projection list marks a projection.
-    looksLikePredicate() {
-        if (this.at("op"))
-            return true; // leading unary `!` (or a stray operator)
-        if (this.at("lparen"))
-            return true; // a grouped boolean expression
-        let depth = 0;
-        for (let i = this.pos; i < this.tokens.length; i++) {
-            const t = this.tokens[i];
-            if (t.type === "eof")
-                break;
-            // Skip nested `{ … }` consumer blocks and `( … )` groups: a keyword/select
-            // inside them is not part of the top-level shape (e.g. `count { select x } == N`).
-            if (t.type === "lbrace" || t.type === "lparen") {
-                depth++;
-                continue;
-            }
-            if (t.type === "rbrace" || t.type === "rparen") {
-                if (depth === 0)
-                    break;
-                depth--;
-                continue;
-            }
-            if (depth === 0) {
-                if (t.type === "colon" || t.type === "comma")
-                    return false;
-                if (t.type === "kw")
-                    break;
-                if (t.type === "op" && (CMP_OPS.has(t.value) || t.value === "&&" || t.value === "||"))
-                    return true;
-                if (t.type === "ident" && t.value === "in")
-                    return true;
-                // A consumer directive in where position (`… exists { … }`, `… count { … }`,
-                // optionally `count distinct { … }`) is a predicate.
-                if (t.type === "ident" && CONSUMERS.has(t.value)) {
-                    const nx = this.tokens[i + 1];
-                    if (nx && (nx.type === "lbrace" || (nx.type === "ident" && nx.value === "distinct")))
-                        return true;
+    // ---- 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;
                 }
-                if (t.type === "ident" && (t.value === "order" || t.value === "follow")) {
-                    const nx = this.tokens[i + 1];
-                    if (nx && nx.type === "ident")
-                        break;
+                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
             }
-        }
-        return false;
+        };
+        return walk(where);
     }
     atOrderBy() {
         const t = this.peek();
         const nx = this.peekAt(1);
         return t.type === "ident" && t.value === "order" && !!nx && nx.type === "ident" && nx.value === "by";
     }
+    // `follow` is a clause when a relation (or something that tries to be one —
+    // `distinct`, an outer reference) follows; otherwise it is a field name.
     atFollow() {
         if (!this.at("ident", "follow"))
             return false;
         const nx = this.peekAt(1);
-        return !!nx && (nx.type === "ident" || nx.type === "binding");
+        return !!nx && (nx.type === "ident" || nx.type === "binding" || nx.type === "caret");
     }
     // ---- follow ---------------------------------------------------------------
     parseFollow() {
         this.next(); // `follow`
         let distinct = false;
+        // After `follow`, `distinct` is a keyword (a relation literally named
+        // `distinct` is not supported); it must be followed by the relation.
         if (this.at("ident", "distinct")) {
-            const nx = this.peekAt(1);
-            if (nx && (nx.type === "ident" || nx.type === "binding")) {
-                this.next();
-                distinct = true;
+            this.next();
+            distinct = true;
+            if (!this.at("ident") && !this.at("binding") && !this.at("caret")) {
+                this.fail("expected a relation after `follow distinct` (`follow distinct <relation>`)");
             }
         }
+        if (this.at("caret")) {
+            this.fail("`follow` takes a relation of the current row (`follow <relation>`); an outer reference `^name` is not allowed there");
+        }
         const receiver = this.parseReceiver();
         const follow = { receiver, distinct, where: null, frontier: null, depth: null, by: null };
         if (!this.at("lbrace"))
@@ -325,6 +430,8 @@ class Parser {
         const levels = this.parseCarets();
         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;
     }
     // Consume a run of `^` and return its length (0 when there is none).
@@ -347,7 +454,7 @@ class Parser {
         while (this.at("dot")) {
             this.next();
             if (!this.at("ident"))
-                this.fail("expected an identifier after '.' in a navigation");
+                this.fail("expected a property name after '.'");
             name = this.next().value;
             expr = { kind: "member", recv: expr, name };
         }
@@ -360,11 +467,11 @@ class Parser {
     // meaningless. Without `values`, every item needs a key — a bare/dotted
     // navigation supplies its own (the last segment); any other expression must be
     // aliased (`name: expr`).
-    parseProjection() {
-        const items = [this.parseSelectItem()];
+    parseProjection(ctx) {
+        const items = [this.parseSelectItem(ctx)];
         while (this.at("comma")) {
             this.next();
-            items.push(this.parseSelectItem());
+            items.push(this.parseSelectItem(ctx));
         }
         let values = false;
         if (this.at("ident", "values")) {
@@ -377,20 +484,38 @@ class Parser {
                 this.fail("a lift (^name: …) cannot be combined with `values`");
         }
         else {
+            // Every item needs a distinct key: two items with one name would silently
+            // overwrite each other in the record. Lifts are keyed per scope (`^x` and
+            // `^^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 projection item that is not a plain name needs an alias (`name: expr`) unless it is followed by `values`");
+                    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");
+                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\`)`);
+                seen.add(key);
             }
         }
         return { items, values };
     }
-    parseSelectItem() {
-        // Leading `^`s mark a lift; the count is how many scopes out it binds.
+    parseSelectItem(ctx) {
+        // 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();
+        if (!this.at("ident") && !this.canStartValue())
+            this.fail("expected a projection name");
+        if (lift > 0 && !ctx.liftsAllowed) {
+            const what = this.at("ident") ? `^${this.peek().value}` : "^name";
+            this.fail(`a lift (${what}) binds a value into the enclosing row and is only valid in a \`collect { … }\` in where position (\`where <relation> collect { ${what}: … }\`)`);
+        }
         if (this.at("ident") && this.peekAt(1)?.type === "colon") {
             const name = this.next().value;
             this.next(); // ':'
-            const op = this.tryOp();
+            const op = this.tryOp(false);
             if (op) {
                 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)`);
@@ -402,8 +527,6 @@ class Parser {
             const expr = this.parseValueExpr();
             return { kind: "field", name, expr, lift };
         }
-        if (!this.at("ident") && !this.canStartValue())
-            this.fail("expected a projection name");
         // 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).
@@ -430,7 +553,10 @@ class Parser {
         }
         return { expr, desc };
     }
-    // ---- where boolean tree: or → and → not → primary -------------------------
+    // ---- where boolean tree: or → and → primary --------------------------------
+    // `!` is handled in `parseWherePrimary`: it applies to the operand right after
+    // it (a consumer test, a parenthesized group, or a scalar primary), never to a
+    // whole comparison — `!a == b` is `(!a) == b`, exactly as in value position.
     parseWhere() { return this.parseWhereOr(); }
     parseWhereOr() {
         const left = this.parseWhereAnd();
@@ -444,37 +570,78 @@ class Parser {
         return { kind: "or", parts };
     }
     parseWhereAnd() {
-        const left = this.parseWhereNot();
+        const left = this.parseWherePrimary();
         if (!this.atOp("&&"))
             return left;
         const parts = [left];
         while (this.atOp("&&")) {
             this.next();
-            parts.push(this.parseWhereNot());
+            parts.push(this.parseWherePrimary());
         }
         return { kind: "and", parts };
     }
-    parseWhereNot() {
-        if (this.atOp("!")) {
+    // A where operand: `[!…] ( where )`, `[!…] <receiver> <consumer> { … }`, or a
+    // scalar leaf (a cmp-level expression, which handles its own `!`).
+    //
+    // Parentheses group EITHER a predicate or a scalar, decided by what follows
+    // the `)`: a comparison, arithmetic, `in`, a range, or `.`-navigation means
+    // the group is a scalar operand (`(a + 1) > 2`, `(a || b) == 5`,
+    // `(x).size() > 1`); anything else means it is a predicate group
+    // (`(a > 1) && b`). A group that contains a consumer test can only be a
+    // predicate.
+    parseWherePrimary() {
+        const start = this.pos;
+        let nots = 0;
+        while (this.atOp("!")) {
             this.next();
-            return { kind: "not", expr: this.parseWhereNot() };
+            nots++;
         }
-        return this.parseWherePrimary();
-    }
-    parseWherePrimary() {
         if (this.at("lparen")) {
             this.next();
-            const e = this.parseWhere();
+            const inner = this.parseWhere();
             if (!this.at("rparen"))
                 this.fail("expected ')' to close a grouped where expression");
             this.next();
-            return e;
+            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) };
+            }
+            return wrapNot(inner, nots);
         }
-        const op = this.tryOp();
+        const op = this.tryOp(true);
         if (op)
-            return this.finishWhereOp(op);
-        const expr = this.parseCmp();
-        return { kind: "scalar", expr };
+            return wrapNot(this.finishWhereOp(op), nots);
+        // 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());
+    }
+    // Whether the token after a `)` continues a scalar expression.
+    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");
+    }
+    // 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 "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 }));
+            }
+            case "op": {
+                const hint = w.op === "count" ? ` — write \`<relation> count { … } ${this.peek().value} N\` without the parentheses` : "";
+                this.fail(`a consumer test (${w.op} { … }) is a predicate, not a value, so it cannot be compared or operated on${hint}`);
+            }
+        }
     }
     // Validate a consumer op used in where position and attach any `count { … } <op> N`.
     finishWhereOp(op) {
@@ -501,7 +668,7 @@ class Parser {
     }
     // Detect + parse a postfix consumer op `<receiver> <consumer> { <sub> }`.
     // Returns null (rewinding) when the lookahead is not a consumer op.
-    tryOp() {
+    tryOp(inWhere) {
         const start = this.pos;
         let receiver;
         if (this.at("binding"))
@@ -522,6 +689,8 @@ class Parser {
             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")) {
@@ -529,7 +698,7 @@ class Parser {
                     distinct = true;
                 }
                 this.next(); // '{'
-                const { sub, distinct: bodyDistinct } = this.parseSubquery();
+                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();
@@ -539,8 +708,8 @@ class Parser {
         this.pos = start;
         return null;
     }
-    parseSubquery() {
-        const body = this.parseBody(true);
+    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,
@@ -566,30 +735,39 @@ class Parser {
         return left;
     }
     // Comparison / membership (also the entry point for a where scalar leaf, so a
-    // where leaf never swallows the where-tree's && / ||).
-    parseCmp() {
-        let left = this.parseRange();
-        if (this.peek().type === "op" && CMP_OPS.has(this.peek().value)) {
-            const op = this.next().value;
-            return { kind: "binary", op, left, right: this.parseRange() };
-        }
-        if (this.at("ident", "in")) {
-            this.next();
-            return { kind: "in", left, right: this.parseRange() };
+    // where leaf never swallows the where-tree's && / ||). Non-associative: a
+    // second comparison in a row is an error, not a silent stray token.
+    //
+    // Each level from here down takes an optional already-parsed `left` operand,
+    // so a parenthesized where-group promoted to a scalar continues into the
+    // operator tail without re-reading its tokens.
+    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");
+        if (!isCmp())
+            return lhs;
+        const op = this.next().value;
+        const rhs = this.parseRange();
+        const result = op === "in" ? { kind: "in", left: lhs, right: rhs } : { kind: "binary", 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 \`&&\``);
         }
-        return left;
+        return result;
     }
     // Range literal: `lo..hi` / `lo...hi` and the open-ended forms `..hi`, `lo..`.
     // Binds looser than arithmetic (so `1+1..2*3` is the range 2..6) but tighter
     // than comparison / `in` (so `n in 1..5` reads as `n in (1..5)`). A leading
     // `..`/`...` opens the low end; a trailing `..`/`...` with no following value
     // opens the high end.
-    parseRange() {
-        if (this.at("range")) {
+    parseRange(left) {
+        if (left === undefined && this.at("range")) {
             const exclusiveEnd = this.next().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 lo = this.parseAdd();
+        const lo = this.parseAdd(left);
         if (this.at("range")) {
             const exclusiveEnd = this.next().value === "...";
             const hi = this.canStartValue() ? this.parseAdd() : null;
@@ -611,23 +789,25 @@ class Parser {
             return true;
         return t.type === "op" && (t.value === "-" || t.value === "!");
     }
-    parseAdd() {
-        let left = this.parseMul();
+    parseAdd(left) {
+        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() };
         }
         return left;
     }
-    parseMul() {
-        let left = this.parseUnary();
+    parseMul(left) {
+        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() };
         }
         return left;
     }
-    parseUnary() {
+    parseUnary(left) {
+        if (left !== undefined)
+            return this.parsePostfix(left);
         if (this.atOp("!")) {
             this.next();
             return { kind: "unary", op: "!", expr: this.parseUnary() };
@@ -638,8 +818,8 @@ class Parser {
         }
         return this.parsePostfix();
     }
-    parsePostfix() {
-        let expr = this.parsePrimary();
+    parsePostfix(left) {
+        let expr = left ?? this.parsePrimary();
         for (;;) {
             if (this.at("dot")) {
                 this.next();
@@ -653,8 +833,8 @@ class Parser {
                     expr = { kind: "member", recv: expr, name };
                 }
             }
-            else if (this.at("lparen") && expr.kind === "ident") {
-                // free function call: name(args)
+            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() };
             }
             else if (this.at("lbrace")) {
@@ -736,6 +916,19 @@ function navKey(e) {
         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 };
+    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) {