@omgbase/oqx 0.8.0 → 0.10.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 = "==" | "!=" | "<" | "<=" | ">" | ">=";
@@ -77,6 +78,14 @@ export interface Subquery {
    * 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
@@ -101,4 +110,7 @@ export interface Query {
   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

@@ -19,13 +19,14 @@ import type { DataContext } from "./context.ts";
 import { DefaultContext } from "./context.ts";
 import { OqxError } from "./errors.ts";
 import {
-  equals, relate, arith, membership, truthy, toNumber, compareForSort, makeRange,
+  equals, relate, arith, membership, truthy, toNumber, compareForSort, makeRange, isEntry,
 } from "./semantics.ts";
 
 /** The shaped result of a top-level query, discriminated by consumer. */
 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 };
@@ -38,8 +39,9 @@ export interface Engine {
 // One query scope: the row under evaluation plus the chain of enclosing scopes
 // that `^` walks. The root scope (parent === null) has no row; its names are the
 // context's named roots. `lifts` holds values bound INTO this scope by `^name:`
-// items in nested blocks; `meta` holds recursion intrinsics for a follow
-// occurrence.
+// items in nested blocks; `meta` holds the scope's intrinsics: recursion
+// metadata for a follow occurrence, and `$key` for an entry scope (a row that
+// arrived as an `entries()` entry — see `enter`).
 interface Scope {
   row: unknown;
   parent: Scope | null;
@@ -49,12 +51,17 @@ interface Scope {
 }
 
 const RECUR = new Set(["$depth", "$stop", "$leaf", "$frontier", "$ordinal"]);
+const KEY = "$key";
 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;
 
@@ -69,26 +76,34 @@ 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) {
-      const s: Scope = { row: r, parent: root, bindings, lifts: {} };
+      const s = this.enter(r, root, { lifts: {} });
       if (!query.where || this.evalWhere(query.where, s)) {
         kept.push(s);
         if (kept.length >= cap) break;
@@ -96,13 +111,33 @@ export class InMemoryEngine implements Engine {
     }
     this.sortScopes(kept, query.orderBy);
     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).
   private matches(where: Where | null, row: unknown, parent: Scope): boolean {
     if (!where) return true;
-    return this.evalWhere(where, { row, parent, bindings: parent.bindings });
+    return this.evalWhere(where, this.enter(row, parent));
   }
 
   private rowsOf(v: unknown): unknown[] {
@@ -110,19 +145,36 @@ export class InMemoryEngine implements Engine {
   }
 
   private child(row: unknown, parent: Scope): Scope {
-    return { row, parent, bindings: parent.bindings };
+    return this.enter(row, parent);
+  }
+
+  // Make the scope for a row. An `entries()` entry is unwrapped here: the scope's
+  // row is the property's VALUE (so `$value` and bare names read it) and the key
+  // becomes the `$key` intrinsic in `meta`. Every place a row becomes a scope
+  // goes through this, so entries behave the same at the top level, in nested
+  // blocks, as `from` re-projections, and as follow seeds.
+  private enter(row: unknown, parent: Scope, extra: { lifts?: Record<string, unknown>; meta?: Record<string, unknown> } = {}): Scope {
+    const s: Scope = { row, parent, bindings: parent.bindings };
+    if (extra.lifts) s.lifts = extra.lifts;
+    if (extra.meta) s.meta = extra.meta;
+    if (isEntry(row)) {
+      s.row = row.value;
+      s.meta = { ...(s.meta ?? {}), [KEY]: row.key };
+    }
+    return s;
   }
 
   // ---- 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 }));
+    let scopes: Scope[] = occ.map((o) => this.enter(o.row, root, { lifts: {}, meta: o.meta }));
     if (post) scopes = scopes.filter((s) => this.evalWhere(post, s));
     this.sortScopes(scopes, query.orderBy);
     if (query.distinct) scopes = this.dedupByProjection(scopes, query);
+    scopes = sliceBound(scopes, bound);
     return this.shape(query.consumer, scopes, query);
   }
 
@@ -158,7 +210,7 @@ export class InMemoryEngine implements Engine {
   //     `ctx.identity(row)`.
   private followWalk(seedRows: unknown[], follow: Follow, parent: Scope): Occurrence[] {
     const cap = follow.depth ?? HARD_DEPTH_CAP;
-    const scopeFor = (row: unknown): Scope => ({ row, parent, bindings: parent.bindings });
+    const scopeFor = (row: unknown): Scope => this.enter(row, parent);
     const keyOf = (row: unknown): string =>
       String(follow.by ? this.evalExpr(follow.by, scopeFor(row)) : this.ctx.identity(row));
     const succOf = (row: unknown): unknown[] => {
@@ -220,6 +272,7 @@ export class InMemoryEngine implements Engine {
   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(proj, s)) };
       case "first": return { consumer, row: scopes.length > 0 ? this.projectRow(proj, scopes[0]!) : null };
@@ -262,9 +315,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
@@ -280,12 +339,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);
-      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.
@@ -298,7 +363,7 @@ export class InMemoryEngine implements Engine {
     let rows = this.rowsOf(this.evalExpr(op.receiver, scope));
     for (const proj of op.sub.from) rows = rows.flatMap((r) => this.rowsOf(this.evalExpr(proj, this.child(r, scope))));
     for (const r of rows) {
-      const s: Scope = { row: r, parent: scope, bindings: scope.bindings, lifts: {} };
+      const s = this.enter(r, scope, { lifts: {} });
       if (!op.sub.where || this.evalWhere(op.sub.where, s)) yield s;
     }
   }
@@ -310,17 +375,19 @@ 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 }));
+      const seeds = sub.where ? rows.filter((r) => this.evalWhere(sub.where!, this.enter(r, scope, { lifts: {} }))) : rows;
+      scopes = this.followWalk(seeds, sub.follow, scope).map((o) => this.enter(o.row, scope, { 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);
     switch (op.op) {
       case "collect": return scopes.map((s) => this.projectRow(sub, s));
       case "first": return scopes.length > 0 ? this.projectRow(sub, scopes[0]!) : null;
@@ -402,9 +469,10 @@ export class InMemoryEngine implements Engine {
   // Resolve a name against ONE scope — never its ancestors. A scope provides,
   // 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.
+  // row); `$key` (the property key, for an entry scope only — see `enter`); 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
@@ -414,7 +482,7 @@ export class InMemoryEngine implements Engine {
   // 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 (name === KEY || 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);
     return this.ctx.get(scope.row, name);
@@ -459,6 +527,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",
+  "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>(["==", "!=", "<", "<=", ">", ">="]);
@@ -50,6 +51,8 @@ interface BodyClauses {
   follow: Follow | null;
   distinct: boolean;
   values: boolean;
+  limit: Expr | null;
+  offset: Expr | null;
 }
 
 class Parser {
@@ -91,6 +94,7 @@ class Parser {
         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`);
@@ -111,6 +115,7 @@ class Parser {
       follow: body.follow,
       distinct: body.distinct,
       values: body.values,
+      ...bounds(body),
     };
   }
 
@@ -128,6 +133,8 @@ class Parser {
     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")) {
@@ -155,6 +162,13 @@ class Parser {
         ({ 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()) {
         if (sawOrder) this.fail("duplicate `order by` clause");
         sawOrder = true;
@@ -174,9 +188,19 @@ class Parser {
         ({ 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, values };
+    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
@@ -270,7 +294,8 @@ class Parser {
   // A receiver/source: a `${…}` binding, or a dotted identifier navigation chain
   // whose head may be an outer reference (`^rel`, `^^root.rel`) — since a bare
   // name is the current row's own property, an enclosing row's relation or a
-  // named root is only reachable as a receiver through `^`.
+  // named root is only reachable as a receiver through `^` — or a free-function
+  // call (`entries(prefs)`), so a computed collection can be consumed directly.
   private parseReceiver(): Expr {
     if (this.at("binding")) return { kind: "binding", index: this.next().index! };
     const levels = this.parseCarets();
@@ -286,10 +311,12 @@ class Parser {
   }
 
   // A dotted navigation chain from `head`; `levels` > 0 makes the head an outer
-  // reference read exactly that many scopes out.
+  // 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.
   private parseNavFrom(head: Token, levels = 0): { expr: Expr; name: string } {
     let expr: Expr = levels > 0 ? { kind: "outer", levels, name: head.value } : { kind: "ident", name: head.value };
     let name = head.value;
+    if (levels === 0 && this.at("lparen")) expr = { kind: "call", recv: null, name: head.value, args: this.parseArgs() };
     while (this.at("dot")) {
       this.next();
       if (!this.at("ident")) this.fail("expected an identifier after '.' in a navigation");
@@ -333,7 +360,7 @@ class Parser {
       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 };
@@ -405,7 +432,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);
@@ -457,7 +484,7 @@ 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, values: body.values },
+      sub: { from: body.froms, where: body.where, select: body.select, orderBy: body.orderBy, follow: body.follow, values: body.values, ...bounds(body) },
       distinct: body.distinct,
     };
   }
@@ -624,3 +651,9 @@ function navKey(e: Expr): string | null {
     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/semantics.ts

@@ -167,9 +167,51 @@ export function parseRangeString(s: string): OqxRange | null {
   return null;
 }
 
+// ---- entries: the explicit record → collection bridge -----------------------
+//
+// A plain object is NOT iterable in OQX (`from ${obj}` is one row). `entries(x)`
+// converts it explicitly into a collection of ENTRY values, each `{ key, value }`
+// tagged (non-enumerably, so JSON/deepEqual see a plain record) so the engine
+// can recognize one: when an entry becomes a query scope, the scope's ROW is
+// the property's value (`$value`, bare names) and `$key` is scope metadata.
+// Arrays yield numeric index keys; a Map yields its entries; null/scalars yield
+// nothing. (Arrays never expose an implicit `$key` — `entries(arr)` is how you
+// ask for the index.)
+
+const ENTRY: unique symbol = Symbol.for("oqx.entry");
+
+export interface OqxEntry {
+  readonly key: unknown;
+  readonly value: unknown;
+  readonly [ENTRY]: true;
+}
+
+/** Construct an entry value (see entriesOf). */
+export function makeEntry(key: unknown, value: unknown): OqxEntry {
+  const e = { key, value } as { key: unknown; value: unknown; [ENTRY]?: true };
+  Object.defineProperty(e, ENTRY, { value: true, enumerable: false });
+  return e as OqxEntry;
+}
+
+/** Whether a value is an entry produced by `entries()` / `makeEntry`. */
+export function isEntry(v: unknown): v is OqxEntry {
+  return typeof v === "object" && v !== null && (v as { [ENTRY]?: unknown })[ENTRY] === true;
+}
+
+/** The entries of a host value: object → own enumerable (key, value) pairs in
+ * insertion order; array → (index, element); Map → its entries; anything else
+ * (absent, scalars, ranges) → none. */
+export function entriesOf(v: unknown): OqxEntry[] {
+  if (v == null || typeof v !== "object" || isRange(v)) return [];
+  if (Array.isArray(v)) return v.map((x, i) => makeEntry(i, x));
+  if (v instanceof Map) return Array.from(v, ([k, x]) => makeEntry(k, x));
+  return Object.entries(v as Record<string, unknown>).map(([k, x]) => makeEntry(k, x));
+}
+
 /** Free functions callable as `name(args)`. */
 export const BUILTIN_FUNCTIONS: Record<string, (args: unknown[]) => unknown> = {
   list: (args) => toList(args[0]),
+  entries: (args) => entriesOf(args[0]),
   size: (args) => sizeOf(args[0]),
   has: (args) => args[0] != null,
   // Coerce a string to a range value (or pass a range through); anything else,