@omgbase/oqx 0.14.1 → 0.18.0

package/dist/walk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.js","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omgbase/oqx",
-  "version": "0.14.1",
+  "version": "0.18.0",
   "description": "OQX (omgbase Query eXpressions): a composable query language and engine for JavaScript collections",
   "keywords": [
     "query",

package/src/ast.ts

@@ -1,8 +1,20 @@
-// OQX query AST for the generic kernel. The parser produces this directly and
-// the interpreter walks it — there is no separate lowering/IR pass, because a
-// "relation" in the generic kernel is just an expression evaluated against the
-// current row (property navigation on the host object model), resolved at run
-// time rather than against a fixed schema.
+// The OQX AST — a first-class, language-level contract (spec/oqx/AST.md, since
+// language 0.16). The parser produces it, the interpreter walks it, and tools
+// reflect on it without re-parsing: every node carries `kind` and `span`, every
+// optional field is materialized (`null` / `false`), and the in-memory objects
+// ARE the JSON shape both implementations serialize (plain data, no parent
+// pointers, no methods). There is no separate lowering/IR pass: a "relation" is
+// just an expression evaluated against the current row.
+//
+// `where` keeps its surface form: a `select` alias referenced in `where` stays a
+// bare identifier here; `resolveAliases` (resolve.ts) performs the substitution
+// before evaluation. Nodes built by a tool rather than the parser carry the
+// empty span `[0, 0]` (see `build.ts`).
+
+/** A half-open source range `[start, end)` in Unicode code points over the raw
+ * source (`rawSource` for a template, where a binding occupies its `${n}`
+ * marker). The empty span `[0, 0]` marks a node that did not come from source. */
+export type Span = [start: number, end: number];
 
 /** 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). */
@@ -11,50 +23,80 @@ export type Consumer = "collect" | "exists" | "none" | "count" | "first" | "sing
 /** Comparison operators usable in a `count { … } <op> <int>` test. */
 export type RelOp = "==" | "!=" | "<" | "<=" | ">" | ">=";
 
+/** The identity operators (SEMANTICS §5b, since 0.17). */
+export type IdentityOp = "is" | "is not";
+
+/** The operator of a `binary` expression: a comparison, an identity test, or arithmetic. */
+export type BinaryOp = RelOp | IdentityOp | "+" | "-" | "*" | "/" | "%";
+
+/** The operator of a `unary` expression. */
+export type UnaryOp = "!" | "-";
+
+/** The operator of a `logical` expression. */
+export type LogicalOp = "&&" | "||";
+
 /** 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); `$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
-  | { kind: "index"; recv: Expr; index: Expr } // [expr] navigation
-  | { kind: "call"; recv: Expr | null; name: string; args: Expr[] } // fn / method
-  | { kind: "unary"; op: "!" | "-"; expr: Expr }
-  | { kind: "binary"; op: string; left: Expr; right: Expr } // arithmetic + comparison
-  | { kind: "logical"; op: "&&" | "||"; left: Expr; right: Expr }
-  | { kind: "in"; left: Expr; right: Expr }
+  | { kind: "lit"; span: Span; value: string | number | boolean | null }
+  | { kind: "ident"; span: Span; name: string } // bare property of the CURRENT row/scope only (never climbs); `$it` is the row itself
+  | { kind: "outer"; span: Span; levels: number; name: string } // `^name` — read from exactly `levels` scopes out (also what `N^name` parses to, since 0.18)
+  | { kind: "binding"; span: Span; index: number } // a ${…} interpolated host value
+  | { kind: "member"; span: Span; recv: Expr; name: string } // .prop navigation on the value to its left
+  | { kind: "call"; span: Span; recv: Expr | null; name: string; args: Expr[] } // fn / method
+  | { kind: "unary"; span: Span; op: UnaryOp; expr: Expr }
+  // `x!` — the value of `expr`, or an eval error when it is absent (since 0.17).
+  | { kind: "required"; span: Span; expr: Expr }
+  | { kind: "binary"; span: Span; op: BinaryOp; left: Expr; right: Expr } // arithmetic + comparison + identity
+  | { kind: "logical"; span: Span; op: LogicalOp; left: Expr; right: Expr }
+  | { kind: "in"; span: Span; left: Expr; right: Expr }
   // A Ruby-style range value. `lo`/`hi` are null for the open-ended forms
   // (`..5` / `5..`); `exclusiveEnd` distinguishes `1...5` from `1..5`. Evaluates
   // to a runtime range value (see semantics.makeRange); primarily the RHS of `in`.
-  | { kind: "range"; lo: Expr | null; hi: Expr | null; exclusiveEnd: boolean };
+  | { kind: "range"; span: Span; lo: Expr | null; hi: Expr | null; exclusiveEnd: boolean }
+  // A value-position directive (since 0.17): `recv first { … }.pay`, and what a
+  // bracket lookup `x[…]` desugars to. `isExpr` is false for it — an op is an
+  // expression only by position; discriminate on `kind === "op"`.
+  | OpNode;
 
+/** One `order by` term. */
 export interface OrderSpec {
+  kind: "order";
+  span: Span;
   expr: Expr;
   desc: boolean;
 }
 
 /** One projection item: a named scalar/navigation value, or a named nested
- * collection consumer. `lift` marks a `^name` one-scope lift. */
+ * collection consumer. `lift` marks a `^name` lift. */
 export type SelectItem =
   // `lift` is the number of `^` carets: 0 = an ordinary projection, N = a lift
-  // that binds this value N scopes out (see the engine's flatten-append).
-  | { kind: "field"; name: string; expr: Expr; lift: number }
-  | { kind: "collect"; name: string; op: OpNode };
+  // that binds this value N scopes out (see the engine's flatten-append). `name`
+  // is `""` for an unaliased non-navigation item, which the parser only admits
+  // under `values`.
+  | { kind: "field"; span: Span; name: string; expr: Expr; lift: number }
+  | { kind: "collect"; span: Span; name: string; op: OpNode };
+
+/** The `count { … } <op> <int>` test attached to an `OpNode` — an attribute of
+ * the directive, not a node of its own. */
+export interface CountCmp {
+  op: RelOp;
+  value: number;
+}
 
 /** A postfix consumer directive over a receiver collection:
  * `<receiver> <op> { <sub> }`, optionally `count { … } <relop> <int>`. */
 export interface OpNode {
   kind: "op";
+  span: Span;
   receiver: Expr;
   op: Consumer;
   sub: Subquery;
-  countCmp?: { op: RelOp; value: number };
+  countCmp: CountCmp | null;
   /** `distinct` — dedup the rows this directive consumes by their projected
    * value (the `select`), so `count distinct { … }` counts distinct projections
    * and `collect distinct { … }` yields distinct rows. Empty select ⇒ dedup by
    * row identity. Spellable as `<op> distinct { … }` or `{ select distinct … }`. */
-  distinct?: boolean;
+  distinct: boolean;
 }
 
 /** One `follow` destination: a relation of the current row (an `Expr` receiver), or a
@@ -64,6 +106,8 @@ export type FollowDestination = Expr | OpNode;
 
 /** The recursive `follow` clause. */
 export interface Follow {
+  kind: "follow";
+  span: Span;
   destinations: FollowDestination[]; // ≥ 1, in source order; the walk is their union
   distinct: boolean;
   where: Expr | null; // successor predicate: which successors keep participating
@@ -72,8 +116,10 @@ export interface Follow {
   by: Expr | null; // identity expression for cycle detection / dedup
 }
 
-/** A nested (sub)query body. */
+/** A nested (sub)query body — the `{ … }` of a directive. */
 export interface Subquery {
+  kind: "subquery";
+  span: Span;
   from: Expr[]; // body-level `from E` re-projections (flatMap chain)
   where: Where | null;
   select: SelectItem[];
@@ -81,29 +127,31 @@ export interface Subquery {
   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;
+   * so `name values` yields `["Bob", …]` and `$it 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;
+  limit: Expr | null;
+  offset: Expr | null;
 }
 
 /** The where-clause boolean tree: OQX owns &&/||/!/grouping so consumer ops
  * (invisible to the scalar evaluator) compose with scalar predicates. */
 export type Where =
-  | { kind: "and"; parts: Where[] }
-  | { kind: "or"; parts: Where[] }
-  | { kind: "not"; expr: Where }
-  | { kind: "scalar"; expr: Expr }
+  | { kind: "and"; span: Span; parts: Where[] }
+  | { kind: "or"; span: Span; parts: Where[] }
+  | { kind: "not"; span: Span; expr: Where }
+  | { kind: "scalar"; span: Span; expr: Expr }
   | OpNode;
 
 /** A top-level OQX query. */
 export interface Query {
+  kind: "query";
+  span: Span;
   source: Expr; // the root collection (`from <source>` or the directive receiver)
   from: Expr[]; // further top-level `from E` re-projections
   where: Where | null;
@@ -112,10 +160,31 @@ export interface Query {
   consumer: Consumer;
   follow: Follow | null;
   /** `distinct` — dedup the result rows by their projected value (see OpNode). */
-  distinct?: boolean;
+  distinct: boolean;
   /** `values` — scalar projection mode (see Subquery). */
-  values?: boolean;
+  values: boolean;
   /** `limit N` / `offset N` (see Subquery); evaluated at the root scope. */
-  limit?: Expr;
-  offset?: Expr;
+  limit: Expr | null;
+  offset: Expr | null;
+}
+
+/** Every node of the tree. `AstNode["kind"]` is the closed set of node kinds. */
+export type AstNode = Query | Subquery | OpNode | Follow | OrderSpec | SelectItem | Where | Expr;
+
+/** The closed set of node kinds. */
+export type AstKind = AstNode["kind"];
+
+/** The expression kinds (`Expr["kind"]`), for `isExpr`. */
+const EXPR_KINDS: ReadonlySet<string> = new Set([
+  "lit", "ident", "outer", "binding", "member", "call", "unary", "required", "binary", "logical", "in", "range",
+]);
+
+/** Whether a node is a scalar `Expr` (an `op` in expression position is not: it
+ * is an expression only by position, see AST.md §1). */
+export function isExpr(node: AstNode): node is Expr {
+  return EXPR_KINDS.has(node.kind);
 }
+
+/** The parsed query's JSON form (`toJSON`): the tree with the language version
+ * it was produced under. */
+export type QueryJson = Query & { oqx: string };

package/src/build.ts

@@ -0,0 +1,72 @@
+// Builders for AST nodes a tool constructs itself (spec/oqx/AST.md §7). Every
+// node they make carries the empty span `[0, 0]` — "not from source" — and the
+// materialized defaults (`distinct: false`, `limit: null`, …), so a hand-built
+// tree has the same shape as a parsed one and prints with `print`.
+
+import type {
+  BinaryOp, Consumer, CountCmp, Expr, Follow, FollowDestination, LogicalOp, OpNode, OrderSpec, Query, SelectItem, Span,
+  Subquery, UnaryOp, Where,
+} from "./ast.ts";
+
+/** A fresh empty span (never shared: spans are mutable tuples). */
+export const span = (): Span => [0, 0];
+
+export const lit = (value: string | number | boolean | null): Expr => ({ kind: "lit", span: span(), value });
+export const ident = (name: string): Expr => ({ kind: "ident", span: span(), name });
+export const outer = (levels: number, name: string): Expr => ({ kind: "outer", span: span(), levels, name });
+export const binding = (index: number): Expr => ({ kind: "binding", span: span(), index });
+export const member = (recv: Expr, name: string): Expr => ({ kind: "member", span: span(), recv, name });
+/** `a.b.c` from a dotted path. */
+export const path = (first: string, ...rest: string[]): Expr => rest.reduce<Expr>((e, n) => member(e, n), ident(first));
+export const call = (recv: Expr | null, name: string, args: Expr[] = []): Expr => ({ kind: "call", span: span(), recv, name, args });
+export const unary = (op: UnaryOp, expr: Expr): Expr => ({ kind: "unary", span: span(), op, expr });
+/** `expr!` — the required value (SEMANTICS §5b). */
+export const required = (expr: Expr): Expr => ({ kind: "required", span: span(), expr });
+export const binary = (op: BinaryOp, left: Expr, right: Expr): Expr => ({ kind: "binary", span: span(), op, left, right });
+export const logical = (op: LogicalOp, left: Expr, right: Expr): Expr => ({ kind: "logical", span: span(), op, left, right });
+export const inOp = (left: Expr, right: Expr): Expr => ({ kind: "in", span: span(), left, right });
+export const range = (lo: Expr | null, hi: Expr | null, exclusiveEnd = false): Expr => ({ kind: "range", span: span(), lo, hi, exclusiveEnd });
+
+export const scalar = (expr: Expr): Where => ({ kind: "scalar", span: span(), expr });
+export const and = (parts: Where[]): Where => ({ kind: "and", span: span(), parts });
+export const or = (parts: Where[]): Where => ({ kind: "or", span: span(), parts });
+export const not = (expr: Where): Where => ({ kind: "not", span: span(), expr });
+
+export const field = (name: string, expr: Expr, lift = 0): SelectItem => ({ kind: "field", span: span(), name, expr, lift });
+export const collect = (name: string, op: OpNode): SelectItem => ({ kind: "collect", span: span(), name, op });
+export const order = (expr: Expr, desc = false): OrderSpec => ({ kind: "order", span: span(), expr, desc });
+
+/** A block body; every clause defaults to empty/absent. */
+export function subquery(parts: Partial<Omit<Subquery, "kind" | "span">> = {}): Subquery {
+  return {
+    kind: "subquery", span: span(),
+    from: [], where: null, select: [], orderBy: null, follow: null, values: false, limit: null, offset: null,
+    ...parts,
+  };
+}
+
+/** `<receiver> <op> [distinct] { sub } [<relop> N]`. */
+export function op(
+  receiver: Expr, consumer: Consumer, sub: Subquery = subquery(),
+  opts: { distinct?: boolean; countCmp?: CountCmp | null } = {},
+): OpNode {
+  return { kind: "op", span: span(), receiver, op: consumer, sub, countCmp: opts.countCmp ?? null, distinct: opts.distinct ?? false };
+}
+
+export function follow(
+  destinations: FollowDestination[],
+  opts: Partial<Omit<Follow, "kind" | "span" | "destinations">> = {},
+): Follow {
+  return { kind: "follow", span: span(), destinations, distinct: false, where: null, frontier: null, depth: null, by: null, ...opts };
+}
+
+/** A top-level query over `source`; every other clause defaults to empty/absent
+ * and the consumer to `collect`. */
+export function query(source: Expr, parts: Partial<Omit<Query, "kind" | "span" | "source">> = {}): Query {
+  return {
+    kind: "query", span: span(), source,
+    from: [], where: null, select: [], orderBy: null, consumer: "collect", follow: null,
+    distinct: false, values: false, limit: null, offset: null,
+    ...parts,
+  };
+}

package/src/context.ts

@@ -28,6 +28,14 @@ export interface CallResult {
 export interface DataContext {
   /** Resolve a named root collection (the `from <name>` / directive receiver). */
   root(name: string): unknown;
+  /** The root scope's row — the host's root object: what `$it` is at the root
+   * scope and `^$it` from a top-level row (SEMANTICS §2, since 0.18), so
+   * `^$it.people` navigates it through `get` and `entries(^$it)` enumerates it.
+   * Bare names at the root still resolve through `root(name)`, so a host with
+   * lazy roots is unaffected. Optional: a context without it (or returning
+   * `undefined`) has no root row — `$it` at the root is absent, the pre-0.18
+   * behavior. `DefaultContext` returns its roots record. */
+  rootObject?(): unknown;
   /** Read a property/relation off a row: a bare identifier (`field`), a
    * `.field` segment, or a `^field` outer reference all come through here, each
    * against exactly the row of the scope it names. An absent property is
@@ -82,9 +90,10 @@ export interface DefaultContextOptions {
 }
 
 /** The default context: ordinary JavaScript objects. Named roots come from a
- * plain `{ name: collection }` map; properties are OWN keys only (an array
- * exposes only its integer indices, a primitive has none); identity is `.id`
- * when present, else the row itself (the engine keys it structurally). */
+ * plain `{ name: collection }` map, which is also the root object (`^$it` from
+ * a top-level row); properties are OWN keys only (an array exposes only its
+ * integer indices, a primitive has none); identity is `.id` when present, else
+ * the row itself (the engine keys it structurally). */
 export class DefaultContext implements DataContext {
   private roots: Record<string, unknown>;
   readonly regexDialect: RegexDialect;
@@ -98,6 +107,10 @@ export class DefaultContext implements DataContext {
     return Object.hasOwn(this.roots, name) ? this.roots[name] : undefined;
   }
 
+  rootObject(): unknown {
+    return this.roots;
+  }
+
   get(row: unknown, key: string): unknown {
     if (row == null || typeof row !== "object") return undefined;
     if (Array.isArray(row)) return isIndexKey(key) ? row[Number(key)] : undefined;

package/src/engine.ts

@@ -29,6 +29,7 @@ import {
   relate, arith, membership, truthy, compareForSort, compare, canonicalKey, makeRange, isEntry, isRange,
 } from "./semantics.ts";
 import type { BlockPlan, Correlation, Rule, RowIndex } from "./optimize/index.ts";
+import { printTemplate } from "./print.ts";
 import { DEFAULT_RULES, HashIndex, intersectPositions, lookupOrder, planFor, residualWithout } from "./optimize/index.ts";
 
 /** The shaped result of a top-level query, discriminated by consumer. */
@@ -46,7 +47,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
+// that `^` walks. The root scope (parent === null) is a row too: its row is the
+// host's root object (`DataContext.rootObject`, since 0.18 — what `$it` is
+// there and `^$it` from a top-level row), while its bare names are the
 // context's named roots. `lifts` holds values bound INTO this scope by `^name:`
 // 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
@@ -140,7 +143,7 @@ export class InMemoryEngine implements Engine {
       memo: new Map(),
     };
     if (this.trace) run.trace = this.trace;
-    const root: Scope = { row: null, parent: null, bindings, run };
+    const root: Scope = { row: this.ctx.rootObject?.(), parent: null, bindings, run };
     const rows = this.reproject(this.rowsOf(this.evalRaw(query.source, root)), query.from, root);
 
     const bound = this.boundOf(query, root);
@@ -185,12 +188,16 @@ export class InMemoryEngine implements Engine {
   // 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.
+  // body — and literals/bindings are themselves. For a top-level query the
+  // scope is the root scope WITHOUT its row (SEMANTICS §18): bare names are
+  // still the named roots, but `$it` — reached through a bracket inside the
+  // bound — is absent, not the root object. 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 : rowless(enclosing);
-    const read = (e: Expr | undefined, word: string): number | null => {
+    const scope: Scope = enclosing.parent === null
+      ? { row: undefined, parent: null, bindings: enclosing.bindings, run: enclosing.run }
+      : rowless(enclosing);
+    const read = (e: Expr | null, word: string): number | null => {
       if (!e) return null;
       const v = this.evalExpr(e, scope);
       if (typeof v !== "number" || !Number.isInteger(v) || v < 0) {
@@ -216,7 +223,7 @@ export class InMemoryEngine implements Engine {
   }
 
   // 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
+  // row is the property's VALUE (so `$it` 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.
@@ -719,20 +726,30 @@ export class InMemoryEngine implements Engine {
         const r = this.evalExpr(e.recv, scope);
         return r == null ? undefined : this.ctx.get(r, e.name);
       }
-      case "index": {
-        const r = this.evalExpr(e.recv, scope);
-        const i = this.evalExpr(e.index, scope);
-        return r == null ? undefined : this.ctx.get(r, String(i));
-      }
       case "call": return this.evalCall(e, scope);
       case "unary": {
         const v = this.evalExpr(e.expr, scope);
         if (e.op === "!") return !truthy(v);
         return v == null ? undefined : -(v as number);
       }
+      // `x!` — the value, or an eval error naming the expression (and the row's
+      // identity when it has a scalar one). Never a filter, never a coercion.
+      case "required": {
+        const v = this.evalExpr(e.expr, scope);
+        if (v == null) throw new OqxError(`\`${describe(e.expr)}!\` is absent${this.rowIdentity(scope)}`, "eval");
+        return v;
+      }
+      // A value-position directive (`jobs first { … }.pay`, the desugared `x[…]`).
+      case "op": return this.evalCollectValue(e, scope);
       case "binary": {
         const l = this.evalExpr(e.left, scope);
         const r = this.evalExpr(e.right, scope);
+        if (e.op === "is" || e.op === "is not") {
+          // Identity (SEMANTICS §5b): the context's identity of each side,
+          // compared structurally — the key `distinct` and `follow` use.
+          const same = canonicalKey(this.ctx.identity(l)) === canonicalKey(this.ctx.identity(r));
+          return e.op === "is" ? same : !same;
+        }
         return isRelOp(e.op) ? relate(e.op, l, r) : arith(e.op, l, r);
       }
       case "logical": {
@@ -749,12 +766,15 @@ 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); `$key` (the property key) when it is an entry scope — 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.
+  // in order: `$it` (the scope's row itself — the current item, whatever its
+  // type, so scalar collections are queryable; at the root the host's root
+  // object, since 0.18; `$value`, its pre-0.15 spelling, is an ordinary
+  // property name now); `$key` (the property key) when it is an entry scope —
+  // 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, the context's named roots (`root(name)`
+  // — never a property of the root object, so a host with lazy roots is
+  // unaffected by what its root object holds).
   //
   // The two metadata steps apply only where the scope CARRIES that metadata
   // (SEMANTICS §2, since 0.13). Anywhere else — `$key` on an ordinary row,
@@ -770,13 +790,22 @@ 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 (name === "$it") return scope.row;
     if ((name === KEY || RECUR.has(name)) && scope.meta && Object.hasOwn(scope.meta, name)) return scope.meta[name];
     if (scope.lifts && Object.hasOwn(scope.lifts, name)) return scope.lifts[name];
     if (scope.parent === null) return this.ctx.root(name);
     return this.ctx.get(scope.row, name);
   }
 
+  // ` on <identity>` for a required-value error when the scope has a row with a
+  // scalar identity (its `id`, through the context); empty otherwise, and at the
+  // root (the root object is not a row of the data).
+  private rowIdentity(scope: Scope): string {
+    if (scope.parent === null || scope.row == null) return "";
+    const id = this.ctx.identity(scope.row);
+    return typeof id === "string" || typeof id === "number" ? ` on ${JSON.stringify(id)}` : "";
+  }
+
   private evalCall(e: Extract<Expr, { kind: "call" }>, scope: Scope): unknown {
     const args = e.args.map((a) => this.evalExpr(a, scope));
     if (e.recv === null) {
@@ -873,6 +902,13 @@ function boundedCount(n: number, b: Bound): number {
   return b.limit == null ? rest : Math.min(rest, b.limit);
 }
 
+// The canonical text of an expression for an error message; a binding shows as
+// its `${n}` marker (the printer refuses to turn a bound value into source).
+function describe(e: Expr): string {
+  const t = printTemplate(e);
+  return t.strings.map((s, i) => (i < t.count ? `${s}\${${t.indices[i]}}` : s)).join("");
+}
+
 function describeReceiver(e: Expr): string {
   if (e.kind === "ident") return e.name;
   if (e.kind === "member") return `${describeReceiver(e.recv)}.${e.name}`;
@@ -890,7 +926,7 @@ function partitionRecur(w: Where): { seed: Where | null; post: Where | null } {
   const seed: Where[] = [];
   const post: Where[] = [];
   for (const p of parts) (whereHasRecur(p) ? post : seed).push(p);
-  const rebuild = (ps: Where[]): Where | null => (ps.length === 0 ? null : ps.length === 1 ? ps[0]! : { kind: "and", parts: ps });
+  const rebuild = (ps: Where[]): Where | null => (ps.length === 0 ? null : ps.length === 1 ? ps[0]! : { kind: "and", span: [0, 0], parts: ps });
   return { seed: rebuild(seed), post: rebuild(post) };
 }
 
@@ -907,17 +943,10 @@ function exprHasRecur(e: Expr): boolean {
   switch (e.kind) {
     case "ident": return RECUR.has(e.name);
     case "member": return exprHasRecur(e.recv);
-    case "index": return exprHasRecur(e.recv) || exprHasRecur(e.index);
     case "call": return (e.recv ? exprHasRecur(e.recv) : false) || e.args.some(exprHasRecur);
-    case "unary": return exprHasRecur(e.expr);
+    case "unary": case "required": return exprHasRecur(e.expr);
     case "binary": case "logical": case "in": return exprHasRecur(e.left) || exprHasRecur(e.right);
     case "range": return (e.lo != null && exprHasRecur(e.lo)) || (e.hi != null && exprHasRecur(e.hi));
     default: return false;
   }
 }
-
-/** Convenience: run a query with plain-object roots (the default context). */
-export function runQuery(query: Query, bindings: readonly unknown[], roots: unknown): OqxResult {
-  const ctx = new DefaultContext((roots as Record<string, unknown>) ?? {});
-  return new InMemoryEngine(ctx).run(query, bindings);
-}

package/src/errors.ts

@@ -1,9 +1,10 @@
-// A single error type for every OQX failure — lex, parse, and evaluation. `stage`
+// A single error type for every OQX failure — lex, parse, evaluation, and
+// printing (a binding has no source text). `stage`
 // distinguishes where it came from so callers (and tests) can branch without
 // string-matching messages. Mirrors the reference impl's FilterInvalid, but the
 // generic kernel has no SQL/CEL layer to name.
 
-export type OqxStage = "lex" | "parse" | "eval";
+export type OqxStage = "lex" | "parse" | "eval" | "print";
 
 export class OqxError extends Error {
   readonly stage: OqxStage;