@omgbase/oqx 0.7.0 → 0.9.0

package/src/ast.ts

@@ -4,8 +4,9 @@
 // current row (property navigation on the host object model), resolved at run
 // time rather than against a fixed schema.
 
-/** Query consumers — how a (sub)query's row set is shaped. */
-export type Consumer = "collect" | "exists" | "count" | "first" | "single";
+/** Query consumers — how a (sub)query's row set is shaped. `none` is the
+ * zero-cardinality complement of `exists` (true iff the block yields no rows). */
+export type Consumer = "collect" | "exists" | "none" | "count" | "first" | "single";
 
 /** Comparison operators usable in a `count { … } <op> <int>` test. */
 export type RelOp = "==" | "!=" | "<" | "<=" | ">" | ">=";
@@ -13,7 +14,7 @@ export type RelOp = "==" | "!=" | "<" | "<=" | ">" | ">=";
 /** Scalar value/predicate expression, evaluated against a row scope + bindings. */
 export type Expr =
   | { kind: "lit"; value: string | number | boolean | null }
-  | { kind: "ident"; name: string } // bare property of the CURRENT row/scope only (never climbs)
+  | { kind: "ident"; name: string } // bare property of the CURRENT row/scope only (never climbs); `$value` is the row itself
   | { kind: "outer"; levels: number; name: string } // `^name` — read from exactly `levels` scopes out
   | { kind: "binding"; index: number } // a ${…} interpolated host value
   | { kind: "member"; recv: Expr; name: string } // .prop navigation on the value to its left
@@ -73,6 +74,18 @@ export interface Subquery {
   select: SelectItem[];
   orderBy: OrderSpec[] | null;
   follow: Follow | null;
+  /** `values` — scalar projection mode: the (single) projected expression is the
+   * row's result itself rather than being wrapped in a `{ name: value }` record,
+   * so `name values` yields `["Bob", …]` and `$value values` yields the rows. */
+  values?: boolean;
+  /** `limit N` / `offset N` — bound the row set AFTER where/order/distinct and
+   * BEFORE the consumer reduces it, so `count { … limit 5 }` is at most 5 and
+   * `first { … offset 1 }` is the second row. Each is a value expression
+   * (a literal, a `${…}` binding, or an outer reference) read as part of the
+   * block — `^n` is the enclosing row's field, as everywhere inside `{ … }` —
+   * and must yield a non-negative integer. */
+  limit?: Expr;
+  offset?: Expr;
 }
 
 /** The where-clause boolean tree: OQX owns &&/||/!/grouping so consumer ops
@@ -95,4 +108,9 @@ export interface Query {
   follow: Follow | null;
   /** `distinct` — dedup the result rows by their projected value (see OpNode). */
   distinct?: boolean;
+  /** `values` — scalar projection mode (see Subquery). */
+  values?: boolean;
+  /** `limit N` / `offset N` (see Subquery); evaluated at the root scope. */
+  limit?: Expr;
+  offset?: Expr;
 }

package/src/engine.ts

@@ -13,7 +13,7 @@
 // fall-through from an inner scope to an outer one — see `resolveIn`.
 
 import type {
-  Query, Where, Expr, OpNode, SelectItem, OrderSpec, Follow,
+  Query, Where, Expr, OpNode, SelectItem, OrderSpec, Follow, Subquery,
 } from "./ast.ts";
 import type { DataContext } from "./context.ts";
 import { DefaultContext } from "./context.ts";
@@ -26,6 +26,7 @@ import {
 export type OqxResult =
   | { consumer: "collect"; rows: unknown[] }
   | { consumer: "exists"; exists: boolean }
+  | { consumer: "none"; none: boolean }
   | { consumer: "count"; count: number }
   | { consumer: "first"; row: unknown | null }
   | { consumer: "single"; row: unknown | null };
@@ -51,6 +52,14 @@ interface Scope {
 const RECUR = new Set(["$depth", "$stop", "$leaf", "$frontier", "$ordinal"]);
 const HARD_DEPTH_CAP = 8;
 
+// What a scope projects to: the select list plus the `values` mode flag. Both
+// `Query` and `Subquery` carry this shape.
+type Projection = Pick<Subquery, "select" | "values">;
+
+// An evaluated `limit`/`offset` pair. `limit === null` is unbounded.
+interface Bound { offset: number; limit: number | null; }
+const UNBOUNDED: Bound = { offset: 0, limit: null };
+
 export class InMemoryEngine implements Engine {
   private ctx: DataContext;
 
@@ -65,22 +74,30 @@ export class InMemoryEngine implements Engine {
       rows = rows.flatMap((r) => this.rowsOf(this.evalExpr(proj, this.child(r, root))));
     }
 
-    if (query.follow) return this.runFollow(query, rows, root);
+    const bound = this.boundOf(query, root);
+    if (query.follow) return this.runFollow(query, rows, root, bound);
 
     // Consumer-directed short-circuits (skipped under `distinct`, which must
-    // materialize + dedup by projection before reducing).
-    if (!query.distinct && query.consumer === "exists") {
-      for (const r of rows) if (this.matches(query.where, r, root)) return { consumer: "exists", exists: true };
-      return { consumer: "exists", exists: false };
-    }
-    if (!query.distinct && query.consumer === "count") {
-      let count = 0;
-      for (const r of rows) if (this.matches(query.where, r, root)) count++;
-      return { consumer: "count", count };
+    // materialize + dedup by projection before reducing). Counting never
+    // materializes rows; exists/none stop as soon as the bound is known to be
+    // non-empty (the (offset+1)th match — or the first, when unbounded).
+    if (!query.distinct && (query.consumer === "exists" || query.consumer === "none" || query.consumer === "count")) {
+      const need = query.consumer === "count" ? Infinity : bound.offset + 1;
+      let n = 0;
+      for (const r of rows) {
+        if (this.matches(query.where, r, root)) { n++; if (n >= need) break; }
+      }
+      const m = boundedCount(n, bound);
+      if (query.consumer === "count") return { consumer: "count", count: m };
+      if (query.consumer === "exists") return { consumer: "exists", exists: m > 0 };
+      return { consumer: "none", none: m === 0 };
     }
 
-    const cap = !query.orderBy && !query.distinct && query.consumer === "first" ? 1
-      : !query.orderBy && !query.distinct && query.consumer === "single" ? 2
+    // first/single over an unordered, non-distinct set need only the rows up to
+    // the bound: offset + 1 (first) / offset + 2 (single, to detect a second).
+    const want = query.consumer === "first" ? 1 : query.consumer === "single" ? 2 : Infinity;
+    const cap = !query.orderBy && !query.distinct && want !== Infinity
+      ? bound.offset + Math.min(want, bound.limit ?? want)
       : Infinity;
     let kept: Scope[] = [];
     for (const r of rows) {
@@ -91,8 +108,28 @@ export class InMemoryEngine implements Engine {
       }
     }
     this.sortScopes(kept, query.orderBy);
-    if (query.distinct) kept = this.dedupByProjection(kept, query.select);
-    return this.shape(query.consumer, kept, query.select);
+    if (query.distinct) kept = this.dedupByProjection(kept, query);
+    kept = sliceBound(kept, bound);
+    return this.shape(query.consumer, kept, query);
+  }
+
+  // Evaluate a block's `limit`/`offset`. The bound is part of the block, so it
+  // is read in a row-less scope INSIDE it: a bare name is absent (there is no
+  // current item yet), `^name` is the enclosing row — exactly as in the block's
+  // body — and literals/bindings are themselves. For a top-level query `scope`
+  // is the root. Each must be a non-negative integer.
+  private boundOf(b: Pick<Subquery, "limit" | "offset">, enclosing: Scope): Bound {
+    if (!b.limit && !b.offset) return UNBOUNDED;
+    const scope: Scope = enclosing.parent === null ? enclosing : { row: undefined, parent: enclosing, bindings: enclosing.bindings };
+    const read = (e: Expr | undefined, word: string): number | null => {
+      if (!e) return null;
+      const v = this.evalExpr(e, scope);
+      if (typeof v !== "number" || !Number.isInteger(v) || v < 0) {
+        throw new OqxError(`${word} must be a non-negative integer (got ${JSON.stringify(v ?? null)})`, "eval");
+      }
+      return v;
+    };
+    return { offset: read(b.offset, "offset") ?? 0, limit: read(b.limit, "limit") };
   }
 
   // A where match that needs no lift capture (exists/count fast paths).
@@ -111,27 +148,28 @@ export class InMemoryEngine implements Engine {
 
   // ---- follow ---------------------------------------------------------------
 
-  private runFollow(query: Query, rows: unknown[], root: Scope): OqxResult {
+  private runFollow(query: Query, rows: unknown[], root: Scope, bound: Bound): OqxResult {
     const { seed, post } = query.where ? partitionRecur(query.where) : { seed: null, post: null };
     const seeds = seed ? rows.filter((r) => this.matches(seed, r, root)) : rows;
     const occ = this.followWalk(seeds, query.follow!, root);
     let scopes: Scope[] = occ.map((o) => ({ row: o.row, parent: root, bindings: root.bindings, lifts: {}, meta: o.meta }));
     if (post) scopes = scopes.filter((s) => this.evalWhere(post, s));
     this.sortScopes(scopes, query.orderBy);
-    if (query.distinct) scopes = this.dedupByProjection(scopes, query.select);
-    return this.shape(query.consumer, scopes, query.select);
+    if (query.distinct) scopes = this.dedupByProjection(scopes, query);
+    scopes = sliceBound(scopes, bound);
+    return this.shape(query.consumer, scopes, query);
   }
 
   // Dedup scopes by their PROJECTED value (`distinct`): keep the first scope per
   // distinct projection, preserving order. An empty projection dedups by row
   // identity (so `count distinct { }` counts distinct rows).
-  private dedupByProjection(scopes: Scope[], select: SelectItem[]): Scope[] {
+  private dedupByProjection(scopes: Scope[], proj: Projection): Scope[] {
     const seen = new Set<string>();
     const out: Scope[] = [];
     for (const s of scopes) {
-      const key = select.length === 0
+      const key = proj.select.length === 0
         ? `i:${String(this.ctx.identity(s.row))}`
-        : `p:${stableStringify(this.projectRow(select, s))}`;
+        : `p:${stableStringify(this.projectRow(proj, s))}`;
       if (seen.has(key)) continue;
       seen.add(key);
       out.push(s);
@@ -213,27 +251,34 @@ export class InMemoryEngine implements Engine {
 
   // ---- consumer shaping -----------------------------------------------------
 
-  private shape(consumer: Query["consumer"], scopes: Scope[], select: SelectItem[]): OqxResult {
+  private shape(consumer: Query["consumer"], scopes: Scope[], proj: Projection): OqxResult {
     switch (consumer) {
       case "exists": return { consumer, exists: scopes.length > 0 };
+      case "none": return { consumer, none: scopes.length === 0 };
       case "count": return { consumer, count: scopes.length };
-      case "collect": return { consumer, rows: scopes.map((s) => this.projectRow(select, s)) };
-      case "first": return { consumer, row: scopes.length > 0 ? this.projectRow(select, scopes[0]!) : null };
+      case "collect": return { consumer, rows: scopes.map((s) => this.projectRow(proj, s)) };
+      case "first": return { consumer, row: scopes.length > 0 ? this.projectRow(proj, scopes[0]!) : null };
       case "single":
         if (scopes.length > 1) throw new OqxError(`single { … } matched ${scopes.length} rows; use first { … } for zero-or-one`, "eval");
-        return { consumer, row: scopes.length > 0 ? this.projectRow(select, scopes[0]!) : null };
+        return { consumer, row: scopes.length > 0 ? this.projectRow(proj, scopes[0]!) : null };
     }
   }
 
-  private projectRow(select: SelectItem[], scope: Scope): unknown {
+  // The per-row result: the raw row (empty projection), the single item's value
+  // itself (`values` mode), or a `{ name: value }` record.
+  private projectRow(proj: Projection, scope: Scope): unknown {
+    const { select } = proj;
     if (select.length === 0) return scope.row;
+    if (proj.values) return this.itemValue(select[0]!, scope);
     const out: Record<string, unknown> = {};
-    for (const item of select) {
-      out[item.name] = item.kind === "field" ? this.evalExpr(item.expr, scope) : this.evalCollectValue(item.op, scope);
-    }
+    for (const item of select) out[item.name] = this.itemValue(item, scope);
     return out;
   }
 
+  private itemValue(item: SelectItem, scope: Scope): unknown {
+    return item.kind === "field" ? this.evalExpr(item.expr, scope) : this.evalCollectValue(item.op, scope);
+  }
+
   // ---- where evaluation -----------------------------------------------------
 
   private evalWhere(w: Where, scope: Scope): boolean {
@@ -252,9 +297,15 @@ export class InMemoryEngine implements Engine {
 
   private evalWhereOp(op: OpNode, scope: Scope): boolean {
     if (op.sub.follow) throw new OqxError("`follow` is only valid on a select-position collect { … }, not a where op", "eval");
-    if (op.op === "exists") return this.anyMatch(op, scope);
+    const bound = this.boundOf(op.sub, scope);
+    if (op.op === "exists" || op.op === "none") {
+      // Unbounded: stop at the first match (dedup cannot change emptiness).
+      // Bounded: the offset/limit decide emptiness, so materialize the set.
+      const any = bound === UNBOUNDED ? this.anyMatch(op, scope) : this.opRows(op, scope, bound).length > 0;
+      return op.op === "exists" ? any : !any;
+    }
     if (op.op === "collect") {
-      const matched = this.matchRows(op, scope);
+      const matched = this.opRows(op, scope, bound);
       for (const item of op.sub.select) {
         if (item.kind !== "field") continue;
         // Bind `item.lift` scopes out: `^` = the collect's own scope, `^^` its
@@ -270,12 +321,18 @@ export class InMemoryEngine implements Engine {
       return matched.length > 0;
     }
     if (op.op === "count") {
-      let rows = this.matchRows(op, scope);
-      if (op.distinct) rows = this.dedupByProjection(rows, op.sub.select);
-      const n = rows.length;
+      const n = this.opRows(op, scope, bound).length;
       return op.countCmp ? compareCount(n, op.countCmp) : n > 0;
     }
-    return this.matchRows(op, scope).length > 0;
+    return this.opRows(op, scope, bound).length > 0;
+  }
+
+  // The rows a consumer op reduces: matched → ordered → distinct → bounded.
+  private opRows(op: OpNode, scope: Scope, bound: Bound): Scope[] {
+    let scopes = this.matchRows(op, scope);
+    this.sortScopes(scopes, op.sub.orderBy);
+    if (op.distinct) scopes = this.dedupByProjection(scopes, op.sub);
+    return sliceBound(scopes, bound);
   }
 
   // Short-circuiting existence check over a consumer receiver.
@@ -300,23 +357,25 @@ export class InMemoryEngine implements Engine {
   // A select-position collect/first/single, optionally recursive via `follow`.
   private evalCollectValue(op: OpNode, scope: Scope): unknown {
     const sub = op.sub;
+    const bound = this.boundOf(sub, scope);
     let scopes: Scope[];
     if (sub.follow) {
       let rows = this.rowsOf(this.evalExpr(op.receiver, scope));
       for (const proj of sub.from) rows = rows.flatMap((r) => this.rowsOf(this.evalExpr(proj, this.child(r, scope))));
       const seeds = sub.where ? rows.filter((r) => this.evalWhere(sub.where!, { row: r, parent: scope, bindings: scope.bindings, lifts: {} })) : rows;
       scopes = this.followWalk(seeds, sub.follow, scope).map((o) => ({ row: o.row, parent: scope, bindings: scope.bindings, meta: o.meta }));
+      this.sortScopes(scopes, sub.orderBy);
+      if (op.distinct) scopes = this.dedupByProjection(scopes, sub);
+      scopes = sliceBound(scopes, bound);
     } else {
-      scopes = this.matchRows(op, scope);
+      scopes = this.opRows(op, scope, bound);
     }
-    this.sortScopes(scopes, sub.orderBy);
-    if (op.distinct) scopes = this.dedupByProjection(scopes, sub.select);
     switch (op.op) {
-      case "collect": return scopes.map((s) => this.projectRow(sub.select, s));
-      case "first": return scopes.length > 0 ? this.projectRow(sub.select, scopes[0]!) : null;
+      case "collect": return scopes.map((s) => this.projectRow(sub, s));
+      case "first": return scopes.length > 0 ? this.projectRow(sub, scopes[0]!) : null;
       case "single":
         if (scopes.length > 1) throw new OqxError(`single { … } for '${describeReceiver(op.receiver)}' matched ${scopes.length} rows`, "eval");
-        return scopes.length > 0 ? this.projectRow(sub.select, scopes[0]!) : null;
+        return scopes.length > 0 ? this.projectRow(sub, scopes[0]!) : null;
       default: throw new OqxError(`${op.op} { … } is not valid in select position`, "eval");
     }
   }
@@ -390,9 +449,11 @@ export class InMemoryEngine implements Engine {
   }
 
   // Resolve a name against ONE scope — never its ancestors. A scope provides,
-  // in order: the recursion intrinsics (`$depth`, …) when it is a follow
-  // occurrence; values lifted into it by `^name:` items; then either the row's
-  // own property or, for the root scope (no row), the context's named roots.
+  // in order: `$value` (the scope's row itself — the current item, whatever its
+  // type, so scalar collections are queryable; absent at the root, which has no
+  // row); the recursion intrinsics (`$depth`, …) when it is a follow occurrence;
+  // values lifted into it by `^name:` items; then either the row's own property
+  // or, for the root scope (no row), the context's named roots.
   //
   // A name the scope lacks is simply absent (undefined). It does NOT fall
   // through to an enclosing scope, so a query's meaning never depends on which
@@ -401,6 +462,7 @@ export class InMemoryEngine implements Engine {
   // always spelled explicitly as `^name`. Present-but-falsy values (null, false,
   // 0, "") need no special case — there is no "absent, so look outward" rule.
   private resolveIn(name: string, scope: Scope): unknown {
+    if (name === "$value") return scope.parent === null ? undefined : scope.row;
     if (RECUR.has(name)) return scope.meta ? scope.meta[name] : undefined;
     if (scope.lifts && name in scope.lifts) return scope.lifts[name];
     if (scope.parent === null) return this.ctx.root(name);
@@ -446,6 +508,16 @@ function compareCount(n: number, cmp: { op: string; value: number }): boolean {
   return relate(cmp.op, n, cmp.value);
 }
 
+// Apply a bound to an ordered row set / to a match count.
+function sliceBound<T>(rows: T[], b: Bound): T[] {
+  if (b === UNBOUNDED) return rows;
+  return rows.slice(b.offset, b.limit == null ? undefined : b.offset + b.limit);
+}
+function boundedCount(n: number, b: Bound): number {
+  const rest = Math.max(0, n - b.offset);
+  return b.limit == null ? rest : Math.min(rest, b.limit);
+}
+
 // Order `&&` conjuncts so cheap scalar leaves run before consumer-op leaves.
 function orderByCost(parts: Where[]): Where[] {
   return [...parts].sort((a, b) => whereCost(a) - whereCost(b));

package/src/index.ts

@@ -43,8 +43,8 @@ export type * from "./ast.ts";
 const templateCache = new WeakMap<TemplateStringsArray, Query>();
 
 /** The OQX tagged template. Returns the query result shaped by its consumer:
- * an array for `collect` (the default), a boolean for `exists`, a number for
- * `count`, or a single record / null for `first` / `single`. */
+ * an array for `collect` (the default), a boolean for `exists` / `none`, a
+ * number for `count`, or a single record / null for `first` / `single`. */
 export function oqx(strings: TemplateStringsArray, ...values: unknown[]): unknown {
   let query = templateCache.get(strings);
   if (!query) {
@@ -82,6 +82,7 @@ function unwrap(result: OqxResult): unknown {
   switch (result.consumer) {
     case "collect": return result.rows;
     case "exists": return result.exists;
+    case "none": return result.none;
     case "count": return result.count;
     case "first": case "single": return result.row;
   }

package/src/parser.ts

@@ -20,12 +20,13 @@ import type {
   Query, Where, Expr, OpNode, Subquery, SelectItem, OrderSpec, Follow, Consumer, RelOp,
 } from "./ast.ts";
 
-const CONSUMERS = new Set<string>(["collect", "exists", "count", "first", "single"]);
+const CONSUMERS = new Set<string>(["collect", "exists", "none", "count", "first", "single"]);
 // Contextual clause words lexed as bare idents; an open-ended range must stop
 // before them rather than consume them as its high bound.
 const CLAUSE_WORDS = new Set<string>([
-  "collect", "exists", "count", "first", "single",
-  "order", "by", "asc", "desc", "follow", "distinct", "frontier", "depth", "in",
+  "collect", "exists", "none", "count", "first", "single",
+  "order", "by", "asc", "desc", "follow", "distinct", "frontier", "depth", "in", "values",
+  "limit", "offset",
 ]);
 const RELOPS = new Set<string>(["==", "!=", "<", "<=", ">", ">="]);
 const CMP_OPS = new Set<string>(["==", "!=", "<", "<=", ">", ">="]);
@@ -49,6 +50,9 @@ interface BodyClauses {
   orderBy: OrderSpec[] | null;
   follow: Follow | null;
   distinct: boolean;
+  values: boolean;
+  limit: Expr | null;
+  offset: Expr | null;
 }
 
 class Parser {
@@ -89,6 +93,8 @@ class Parser {
         consumer: directive.op,
         follow: directive.sub.follow,
         distinct: directive.distinct ?? false,
+        values: directive.sub.values ?? false,
+        ...bounds(directive.sub),
       };
     }
     if (directive) this.fail(`unexpected ${this.tokDesc()} after the top-level directive`);
@@ -108,6 +114,8 @@ class Parser {
       consumer: "collect",
       follow: body.follow,
       distinct: body.distinct,
+      values: body.values,
+      ...bounds(body),
     };
   }
 
@@ -124,6 +132,9 @@ class Parser {
     let orderBy: OrderSpec[] | null = null;
     let follow: Follow | null = null;
     let distinct = false;
+    let values = false;
+    let limit: Expr | null = null;
+    let offset: Expr | null = null;
     let sawWhere = false, sawSelect = false, sawOrder = false;
 
     while (!this.at("eof") && !this.at("rbrace")) {
@@ -148,7 +159,14 @@ class Parser {
         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
-        select = this.parseSelectItems();
+        ({ 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; }
         continue;
       }
       if (orderByAllowed && this.atOrderBy()) {
@@ -167,12 +185,22 @@ class Parser {
       if (this.at("ident") || this.at("binding")) {
         if (sawSelect) this.fail("duplicate projection (an implicit select cannot follow a `select`)");
         sawSelect = true;
-        select = this.parseSelectItems();
+        ({ items: select, values } = this.parseProjection());
         continue;
       }
-      this.fail(`unexpected ${this.tokDesc()} — expected from/where/select${orderByAllowed ? "/order by" : ""}/follow`);
+      this.fail(`unexpected ${this.tokDesc()} — expected from/where/select${orderByAllowed ? "/order by" : ""}/limit/offset/follow`);
     }
-    return { froms, where, select, orderBy, follow, distinct };
+    return { froms, where, select, orderBy, follow, distinct, values, limit, offset };
+  }
+
+  // `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.
+  private atBound(): boolean {
+    const t = this.peek();
+    if (t.type !== "ident" || (t.value !== "limit" && t.value !== "offset")) return false;
+    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
@@ -296,24 +324,40 @@ class Parser {
   }
 
   // ---- select ---------------------------------------------------------------
-  private parseSelectItems(): SelectItem[] {
+  // A projection list, optionally followed by the `values` mode word. Under
+  // `values` the list must be exactly one item, which need not be named: the
+  // row's result IS that value (no `{ name: value }` record), so a name would be
+  // 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`).
+  private parseProjection(): { items: SelectItem[]; values: boolean } {
     const items = [this.parseSelectItem()];
     while (this.at("comma")) { this.next(); items.push(this.parseSelectItem()); }
-    return items;
+    let values = false;
+    if (this.at("ident", "values")) {
+      this.next();
+      values = true;
+      if (items.length !== 1) this.fail("`values` projects exactly one expression (got " + items.length + ")");
+      const only = items[0]!;
+      if (only.kind === "field" && only.lift > 0) this.fail("a lift (^name: …) cannot be combined with `values`");
+    } else {
+      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`");
+      }
+    }
+    return { items, values };
   }
 
   private parseSelectItem(): SelectItem {
     // Leading `^`s mark a lift; the count is how many scopes out it binds.
     const lift = this.parseCarets();
-    if (!this.at("ident")) this.fail("expected a projection name");
-    const nameTok = this.next();
-    if (this.at("colon")) {
-      this.next();
-      const name = nameTok.value;
+    if (this.at("ident") && this.peekAt(1)?.type === "colon") {
+      const name = this.next().value;
+      this.next(); // ':'
       const op = this.tryOp();
       if (op) {
         if (op.op !== "collect" && op.op !== "first" && op.op !== "single") {
-          this.fail(`projection '${name}' must use collect/first/single, not ${op.op}`);
+          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 };
@@ -321,9 +365,12 @@ class Parser {
       const expr = this.parseValueExpr();
       return { kind: "field", name, expr, lift };
     }
-    // bare/dotted projection: key defaults to the last navigation segment.
-    const { expr, name } = this.parseNavFrom(nameTok);
-    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).
+    const expr = this.parseValueExpr();
+    return { kind: "field", name: navKey(expr) ?? "", expr, lift };
   }
 
   // ---- order by -------------------------------------------------------------
@@ -382,7 +429,7 @@ class Parser {
   // Validate a consumer op used in where position and attach any `count { … } <op> N`.
   private finishWhereOp(op: OpNode): OpNode {
     if (op.op === "first" || op.op === "single") {
-      this.fail(`${op.op} { … } is a select-position lookup; in where use exists { … } or count { … } <op> N`);
+      this.fail(`${op.op} { … } is a select-position lookup; in where use exists { … } / none { … } or count { … } <op> N`);
     }
     if (op.op === "collect") {
       const allLift = op.sub.select.length > 0 && op.sub.select.every((s) => s.kind === "field" && s.lift > 0);
@@ -433,7 +480,10 @@ class Parser {
 
   private parseSubquery(): { sub: Subquery; distinct: boolean } {
     const body = this.parseBody(true);
-    return { sub: { from: body.froms, where: body.where, select: body.select, orderBy: body.orderBy, follow: body.follow }, distinct: body.distinct };
+    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,
+    };
   }
 
   // ---- expression Pratt parser ----------------------------------------------
@@ -587,3 +637,20 @@ class Parser {
     this.fail(`unexpected ${this.tokDesc()} — expected a value`);
   }
 }
+
+// The default key of an unaliased projection item: the last segment of a bare /
+// dotted / outer navigation (`name`, `meta.slug` → "slug", `^name`), else null.
+function navKey(e: Expr): string | null {
+  switch (e.kind) {
+    case "ident": return e.name;
+    case "outer": return e.name;
+    case "member": return e.name;
+    default: return null;
+  }
+}
+
+// The optional `limit`/`offset` fields of a Query/Subquery, present only when set
+// (so a Query built without them is unchanged).
+function bounds(b: { limit?: Expr | null; offset?: Expr | null }): { limit?: Expr; offset?: Expr } {
+  return { ...(b.limit ? { limit: b.limit } : {}), ...(b.offset ? { offset: b.offset } : {}) };
+}

package/src/plan.ts

@@ -12,7 +12,9 @@
 // Because a bare identifier resolves against the current row ONLY (it never
 // climbs to an enclosing scope or a named root), an `ident` in a top-level
 // `where` is unambiguously a column of the scanned rows and is safe to push. An
-// `outer` (`^name`) reference is not a row column and stays residual.
+// `outer` (`^name`) reference is not a row column and stays residual, and so is
+// the `$value` intrinsic (the row itself, not one of its columns) — adapters
+// gate idents on their known column set, which never includes it.
 
 import type { Query, Where, Expr } from "./ast.ts";