@omgbase/oqx 0.18.0 → 0.21.0

package/dist/walk.d.ts

@@ -3,12 +3,14 @@ import type { AstKind, AstNode, Expr, Query, QueryJson, Subquery } from "./ast.j
  * root collection (`from <source>` or the directive receiver); `from` the further
  * re-projections; `follow` the `Follow` node itself and `follow.*` its parts.
  * The root node has no clause (`null`). */
-export type Clause = "source" | "from" | "where" | "select" | "orderBy" | "limit" | "offset" | "follow" | "follow.destination" | "follow.where" | "follow.frontier" | "follow.by";
+export type Clause = "source" | "from" | "where" | "select" | "orderBy" | "limit" | "offset" | "follow" | "follow.destination" | "follow.frontier";
 /** Where a visited node sits. `depth` is the scope depth at which the node is
  * evaluated (0 = the root scope: a top-level `source`, `limit`, `offset`; 1 =
  * a top-level row: its `where`, `select`, `order by`, `from` re-projections and
- * `follow`; a block's rows are one deeper than the block's receiver; a follow
- * `where` is one deeper than the frontier row it tests successors of). */
+ * `follow`; a block's rows are one deeper than the block's receiver — a follow
+ * destination block's `where` therefore one deeper than the frontier row —
+ * and a destination block's `frontier` one level out of its rows, under the
+ * walk's enclosing scope). */
 export interface VisitContext {
     /** The ancestors of the node, root first (empty for the root). */
     readonly path: readonly AstNode[];

package/dist/walk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAInF;;;2CAG2C;AAC3C,MAAM,MAAM,MAAM,GACd,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,GACvE,QAAQ,GAAG,oBAAoB,GAAG,cAAc,GAAG,iBAAiB,GAAG,WAAW,CAAC;AAEvF;;;;0EAI0E;AAC1E,MAAM,WAAW,YAAY;IAC3B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,OAAO;IACtB;iDAC6C;IAC7C,KAAK,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,YAAY,GAAG,OAAO,GAAG,IAAI,CAAC;IACzD,sCAAsC;IACtC,KAAK,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,YAAY,GAAG,IAAI,CAAC;CAChD;AAED;oEACoE;AACpE,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;6DAC6D;AAC7D,eAAO,MAAM,QAAQ,EAAE;IAAE,QAAQ,EAAE,CAAC,IAAI,OAAO,GAAG,SAAS,QAAQ,EAAE;CA8CpE,CAAC;AAQF,yDAAyD;AACzD,wBAAgB,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAoB3D;AAED;;;4EAG4E;AAC5E,wBAAgB,SAAS,CAAC,CAAC,SAAS,KAAK,GAAG,QAAQ,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,YAAY,KAAK,IAAI,GAAG,CAAC,CAuB5G;AAED;4EAC4E;AAC5E,MAAM,MAAM,QAAQ,CAAC,CAAC,IACpB,CAAC,SAAS,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,EAAE,GAC5C,CAAC,SAAS,MAAM,GAAG;KAAG,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,MAAM,GAAG,KAAK,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GACrF,CAAC,CAAC;AAEN,wBAAgB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAWlD;AAED;;gDAEgD;AAChD,wBAAgB,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAE9C"}
+{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAInF;;;2CAG2C;AAC3C,MAAM,MAAM,MAAM,GACd,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,GACvE,QAAQ,GAAG,oBAAoB,GAAG,iBAAiB,CAAC;AAExD;;;;;;8BAM8B;AAC9B,MAAM,WAAW,YAAY;IAC3B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,OAAO;IACtB;iDAC6C;IAC7C,KAAK,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,YAAY,GAAG,OAAO,GAAG,IAAI,CAAC;IACzD,sCAAsC;IACtC,KAAK,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,YAAY,GAAG,IAAI,CAAC;CAChD;AAED;oEACoE;AACpE,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;6DAC6D;AAC7D,eAAO,MAAM,QAAQ,EAAE;IAAE,QAAQ,EAAE,CAAC,IAAI,OAAO,GAAG,SAAS,QAAQ,EAAE;CAmDpE,CAAC;AA0BF,yDAAyD;AACzD,wBAAgB,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAoB3D;AAED;;;4EAG4E;AAC5E,wBAAgB,SAAS,CAAC,CAAC,SAAS,KAAK,GAAG,QAAQ,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,YAAY,KAAK,IAAI,GAAG,CAAC,CAuB5G;AAED;4EAC4E;AAC5E,MAAM,MAAM,QAAQ,CAAC,CAAC,IACpB,CAAC,SAAS,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,EAAE,GAC5C,CAAC,SAAS,MAAM,GAAG;KAAG,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,MAAM,GAAG,KAAK,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GACrF,CAAC,CAAC;AAEN,wBAAgB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAWlD;AAED;;gDAEgD;AAChD,wBAAgB,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAE9C"}

package/dist/walk.js

@@ -13,6 +13,8 @@ export const CHILDREN = {
         { key: "source", clause: "source" },
         { key: "from", clause: "from", depth: 1 },
         { key: "where", clause: "where", depth: 1 },
+        // The body's `frontier` (0.20) reads each seed in the row scope, like `where`.
+        { key: "frontier", clause: "follow.frontier", depth: 1 },
         { key: "follow", clause: "follow", depth: 1 },
         { key: "orderBy", clause: "orderBy", depth: 1 },
         { key: "limit", clause: "limit" },
@@ -22,18 +24,18 @@ export const CHILDREN = {
         { key: "select", clause: "select" },
         { key: "from", clause: "from" },
         { key: "where", clause: "where" },
+        // A destination block's `frontier` reads the occurrence under the walk's
+        // enclosing scope — one level OUT of the block's rows (SEMANTICS §20); any
+        // other block's reads its seeds in the row scope, like `where`
+        // (`childDepth` tells the two apart by the block's position).
+        { key: "frontier", clause: "follow.frontier", depth: -1 },
         { key: "follow", clause: "follow" },
         { key: "orderBy", clause: "orderBy" },
         { key: "limit", clause: "limit" },
         { key: "offset", clause: "offset" },
     ],
     op: [{ key: "receiver" }, { key: "sub", depth: 1 }],
-    follow: [
-        { key: "destinations", clause: "follow.destination" },
-        { key: "where", clause: "follow.where", depth: 1 },
-        { key: "frontier", clause: "follow.frontier" },
-        { key: "by", clause: "follow.by" },
-    ],
+    follow: [{ key: "destinations", clause: "follow.destination" }],
     order: [{ key: "expr" }],
     field: [{ key: "expr" }],
     collect: [{ key: "op" }],
@@ -53,10 +55,28 @@ export const CHILDREN = {
     logical: [{ key: "left" }, { key: "right" }],
     in: [{ key: "left" }, { key: "right" }],
     range: [{ key: "lo" }, { key: "hi" }],
+    tuple: [{ key: "items" }],
+    // The interpolations; the text parts between them are strings, not nodes.
+    template: [{ key: "parts" }],
 };
 function slot(node, key) {
     return node[key] ?? null;
 }
+/** A block is a follow destination block when its `op` is a direct destination
+ * of a `follow` node. `path` is the ancestors with the block itself last. */
+function isDestinationBlock(path) {
+    const op = path[path.length - 2];
+    const owner = path[path.length - 3];
+    return op?.kind === "op" && owner?.kind === "follow";
+}
+/** How much deeper a child's scope is: the table's value, except a block's
+ * `frontier`, which is one level OUT only for a destination block (the walk's
+ * enclosing scope) and the row scope itself for a body with its own `follow`. */
+function childDepth(node, child, path) {
+    if (node.kind === "subquery" && child.key === "frontier" && !isDestinationBlock(path))
+        return 0;
+    return child.depth ?? 0;
+}
 /** Walk a tree depth-first in canonical source order. */
 export function visit(root, visitor) {
     const path = [];
@@ -70,10 +90,12 @@ export function visit(root, visitor) {
                 if (v === null)
                     continue;
                 const c = child.clause ?? clause;
-                const d = depth + (child.depth ?? 0);
-                if (Array.isArray(v))
+                const d = depth + childDepth(node, child, path);
+                if (Array.isArray(v)) {
                     for (const x of v)
-                        go(x, c, d);
+                        if (typeof x !== "string")
+                            go(x, c, d);
+                }
                 else
                     go(v, c, d);
             }
@@ -98,11 +120,12 @@ export function transform(root, f) {
             if (v === null)
                 continue;
             const c = child.clause ?? clause;
-            const d = depth + (child.depth ?? 0);
+            const d = depth + childDepth(node, child, path);
             let next;
             if (Array.isArray(v)) {
                 let changed = false;
-                const mapped = v.map((x) => { const y = go(x, c, d); if (y !== x)
+                const mapped = v.map((x) => { if (typeof x === "string")
+                    return x; const y = go(x, c, d); if (y !== x)
                     changed = true; return y; });
                 next = changed ? mapped : v;
             }

package/dist/walk.js.map

@@ -1 +1 @@
-{"version":3,"file":"walk.js","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"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"}
+{"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.18.0",
+  "version": "0.21.0",
   "description": "OQX (omgbase Query eXpressions): a composable query language and engine for JavaScript collections",
   "keywords": [
     "query",

package/src/ast.ts

@@ -35,6 +35,10 @@ export type UnaryOp = "!" | "-";
 /** The operator of a `logical` expression. */
 export type LogicalOp = "&&" | "||";
 
+/** One part of a template literal (since 0.21): a decoded text run, or an
+ * interpolated expression. The strings are not nodes (no `kind`, no span). */
+export type TemplatePart = string | Expr;
+
 /** Scalar value/predicate expression, evaluated against a row scope + bindings. */
 export type Expr =
   | { kind: "lit"; span: Span; value: string | number | boolean | null }
@@ -53,6 +57,17 @@ export type Expr =
   // (`..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"; span: Span; lo: Expr | null; hi: Expr | null; exclusiveEnd: boolean }
+  // A tuple `(e1, e2, …)` (since 0.20): two or more expressions whose values
+  // concatenate with one level of flattening (SEMANTICS §3b) — a value and a
+  // receiver (`(a, b) { … }`, `follow (a, b) { depth 2 }`). One expression in
+  // parentheses is grouping and leaves no node.
+  | { kind: "tuple"; span: Span; items: Expr[] }
+  // A template literal `` `text ${expr} text` `` (since 0.21): `parts` alternates
+  // strictly — text, interpolation, text, … — so it always has an odd length and
+  // begins and ends with a (possibly empty) text part; the text is decoded (the
+  // GRAMMAR §1 escapes resolved). Evaluates to the concatenation of the text and
+  // the interpolated values' string forms (SEMANTICS §7b).
+  | { kind: "template"; span: Span; parts: TemplatePart[] }
   // 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"`.
@@ -104,16 +119,13 @@ export interface OpNode {
  * per frontier row, inside which `^` is that row. Discriminate on `kind === "op"`. */
 export type FollowDestination = Expr | OpNode;
 
-/** The recursive `follow` clause. */
+/** The recursive `follow` clause (since 0.20 just the destinations: a
+ * destination's `where`, `frontier` and `depth` live in its own block). */
 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
-  frontier: Expr | null; // boundary predicate: cut a relation that could continue
-  depth: number | null; // 1..8 cap; null = the hard cap
-  by: Expr | null; // identity expression for cycle detection / dedup
 }
 
 /** A nested (sub)query body — the `{ … }` of a directive. */
@@ -125,6 +137,16 @@ export interface Subquery {
   select: SelectItem[];
   orderBy: OrderSpec[] | null;
   follow: Follow | null;
+  /** `frontier P` / `depth n` (since 0.20). In a `follow` destination block
+   * `frontier` marks the occurrences reached through this destination for
+   * which `P` holds (not expanded; `P` read one level out, under the walk's
+   * enclosing scope), and `depth n` makes the destination expand a frontier
+   * row only while that row's `$depth < n` (1..8; `null` = the hard cap 8).
+   * In any other block `frontier` is legal only with a `follow` and marks the
+   * walk's SEEDS, read in the seed's scope like `where` (as on `Query`);
+   * `depth` is destination-only. Both `null` when absent. */
+  frontier: Expr | null;
+  depth: number | 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 `$it values` yields the rows. */
@@ -159,6 +181,11 @@ export interface Query {
   orderBy: OrderSpec[] | null;
   consumer: Consumer;
   follow: Follow | null;
+  /** `frontier P` (since 0.20) — legal only when the body has a `follow`: a
+   * seed for which `P` holds (read in the seed's own scope, `^` the enclosing
+   * scope, like `where`) is a frontier (`$stop == "frontier"`, not expanded).
+   * `null` without one. */
+  frontier: Expr | null;
   /** `distinct` — dedup the result rows by their projected value (see OpNode). */
   distinct: boolean;
   /** `values` — scalar projection mode (see Subquery). */
@@ -176,7 +203,7 @@ 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",
+  "lit", "ident", "outer", "binding", "member", "call", "unary", "required", "binary", "logical", "in", "range", "tuple", "template",
 ]);
 
 /** Whether a node is a scalar `Expr` (an `op` in expression position is not: it

package/src/build.ts

@@ -5,7 +5,7 @@
 
 import type {
   BinaryOp, Consumer, CountCmp, Expr, Follow, FollowDestination, LogicalOp, OpNode, OrderSpec, Query, SelectItem, Span,
-  Subquery, UnaryOp, Where,
+  Subquery, TemplatePart, UnaryOp, Where,
 } from "./ast.ts";
 
 /** A fresh empty span (never shared: spans are mutable tuples). */
@@ -26,6 +26,11 @@ export const binary = (op: BinaryOp, left: Expr, right: Expr): Expr => ({ kind:
 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 });
+/** `(e1, e2, …)` — a tuple of two or more expressions (SEMANTICS §3b). */
+export const tuple = (items: Expr[]): Expr => ({ kind: "tuple", span: span(), items });
+/** `` `text ${expr} …` `` — a template literal (SEMANTICS §7b); `parts` alternates
+ * text, expression, text, … (odd length, text first and last). */
+export const template = (parts: TemplatePart[]): Expr => ({ kind: "template", span: span(), parts });
 
 export const scalar = (expr: Expr): Where => ({ kind: "scalar", span: span(), expr });
 export const and = (parts: Where[]): Where => ({ kind: "and", span: span(), parts });
@@ -40,7 +45,7 @@ export const order = (expr: Expr, desc = false): OrderSpec => ({ kind: "order",
 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,
+    from: [], where: null, select: [], orderBy: null, follow: null, frontier: null, depth: null, values: false, limit: null, offset: null,
     ...parts,
   };
 }
@@ -53,11 +58,10 @@ export function op(
   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 };
+/** `follow [distinct] <destinations>`; a destination's `where`/`frontier`/`depth`
+ * belong to its block (`op(recv, "collect", subquery({ depth: 2 }))`). */
+export function follow(destinations: FollowDestination[], opts: { distinct?: boolean } = {}): Follow {
+  return { kind: "follow", span: span(), destinations, distinct: opts.distinct ?? false };
 }
 
 /** A top-level query over `source`; every other clause defaults to empty/absent
@@ -65,7 +69,7 @@ export function follow(
 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,
+    from: [], where: null, select: [], orderBy: null, consumer: "collect", follow: null, frontier: null,
     distinct: false, values: false, limit: null, offset: null,
     ...parts,
   };

package/src/context.ts

@@ -1,8 +1,9 @@
 // The tier-2 seam: a DataContext binds OQX's query semantics to a concrete data
 // model. The engine never touches host objects directly — it asks the context to
 // resolve named roots, read properties/relations, coerce a relation result into
-// rows, compute identity (for `follow` dedup), and optionally supply custom
-// scalar functions/methods. This is what lets the same query semantics run over
+// rows (and say which objects are one row rather than a collection), name a
+// row's identity (`$key`: `follow` dedup, `distinct`, `is`), and optionally
+// supply custom scalar functions/methods. This is what lets the same query semantics run over
 // plain objects, a lazy ORM graph, or a remote API without changing the engine.
 //
 // (Performant execution over a real store is the tier-3 seam — see planner.ts —
@@ -45,6 +46,13 @@ export interface DataContext {
   get(row: unknown, key: string): unknown;
   /** Coerce a relation/source value into rows (may be lazy). */
   toRows(value: unknown): Iterable<unknown>;
+  /** Optional: whether an object this context handed out in row position is
+   * ONE row — a record, not a collection (SEMANTICS §3, since 0.20) — so a block
+   * over it yields one result rather than a one-element list (`doc { title }`
+   * is a record; `docs { title }` a list). Asked only for non-array objects;
+   * absent, any non-iterable object is one row and any iterable (a `Set`, a
+   * lazy handle with `Symbol.iterator`) is a collection. */
+  isSingle?(value: unknown): boolean;
   /** Optional: a value this context handed out as a stand-in for a collection
    * it has not read yet (a lazy table handle), resolved to what it stands for.
    * The engine calls it on every value it is about to observe AS A VALUE — an
@@ -57,8 +65,15 @@ export interface DataContext {
    * seen by the language. Absent = identity; a context whose handle already
    * behaves as the collection (a `Proxy` over an array) needs none. */
   materialize?(value: unknown): unknown;
-  /** Identity of a row for `follow` cycle detection / dedup. */
-  identity(row: unknown): unknown;
+  /** Optional: the identity a row is known by — `$key` (SEMANTICS §16, since
+   * 0.20): what `follow` cycle detection, the per-step union, `follow distinct`,
+   * `distinct` over unprojected rows and `is` compare, and what reading `$key`
+   * on the row returns. Absent, a row's identity is its structural value (an
+   * entry's is its key either way). A store-backed context answers its row id. */
+  identityOf?(row: unknown): unknown;
+  /** @deprecated The pre-0.20 spelling of `identityOf`; read when `identityOf`
+   * is absent. Removed in the next minor. */
+  identity?(row: unknown): unknown;
   /** Optional custom free function; return `{ handled: false }` to defer. */
   callFunction?(name: string, args: unknown[]): CallResult;
   /** Optional custom method; return `{ handled: false }` to defer. */
@@ -92,8 +107,9 @@ export interface DefaultContextOptions {
 /** The default context: ordinary JavaScript objects. Named roots come from a
  * 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). */
+ * integer indices, a primitive has none); it names no identity of its own, so a
+ * row's `$key` is its structural value (SEMANTICS §16) unless a query projects
+ * one (`$key: id`). */
 export class DefaultContext implements DataContext {
   private roots: Record<string, unknown>;
   readonly regexDialect: RegexDialect;
@@ -121,11 +137,6 @@ export class DefaultContext implements DataContext {
     return coerceCollection(value);
   }
 
-  identity(row: unknown): unknown {
-    if (row != null && typeof row === "object" && "id" in row) return (row as Record<string, unknown>).id;
-    return row;
-  }
-
   callFunction(name: string, args: unknown[]): CallResult {
     const fn = Object.hasOwn(BUILTIN_FUNCTIONS, name) ? BUILTIN_FUNCTIONS[name] : undefined;
     return fn ? { handled: true, value: fn(args) } : { handled: false };