@omgbase/oqx 0.15.0 → 0.20.0

package/dist/ast.d.ts

@@ -1,142 +1,195 @@
+/** 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). */
 export type Consumer = "collect" | "exists" | "none" | "count" | "first" | "single";
 /** 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";
+    span: Span;
     value: string | number | boolean | null;
 } | {
     kind: "ident";
+    span: Span;
     name: string;
 } | {
     kind: "outer";
+    span: Span;
     levels: number;
     name: string;
 } | {
     kind: "binding";
+    span: Span;
     index: number;
 } | {
     kind: "member";
+    span: Span;
     recv: Expr;
     name: string;
-} | {
-    kind: "index";
-    recv: Expr;
-    index: Expr;
 } | {
     kind: "call";
+    span: Span;
     recv: Expr | null;
     name: string;
     args: Expr[];
 } | {
     kind: "unary";
-    op: "!" | "-";
+    span: Span;
+    op: UnaryOp;
+    expr: Expr;
+} | {
+    kind: "required";
+    span: Span;
     expr: Expr;
 } | {
     kind: "binary";
-    op: string;
+    span: Span;
+    op: BinaryOp;
     left: Expr;
     right: Expr;
 } | {
     kind: "logical";
-    op: "&&" | "||";
+    span: Span;
+    op: LogicalOp;
     left: Expr;
     right: Expr;
 } | {
     kind: "in";
+    span: Span;
     left: Expr;
     right: Expr;
 } | {
     kind: "range";
+    span: Span;
     lo: Expr | null;
     hi: Expr | null;
     exclusiveEnd: boolean;
-};
+} | {
+    kind: "tuple";
+    span: Span;
+    items: Expr[];
+} | 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 = {
     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
  * destination block — a select-position directive (`collect`/`first`/`single`) re-evaluated
  * 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[];
     distinct: boolean;
-    where: Expr | null;
-    frontier: Expr | null;
-    depth: number | null;
-    by: Expr | null;
 }
-/** A nested (sub)query body. */
+/** A nested (sub)query body — the `{ … }` of a directive. */
 export interface Subquery {
+    kind: "subquery";
+    span: Span;
     from: Expr[];
     where: Where | null;
     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. */
-    values?: boolean;
+    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";
+    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;
     from: Expr[];
     where: Where | null;
@@ -144,12 +197,29 @@ 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;
+    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"];
+/** 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 declare function isExpr(node: AstNode): node is Expr;
+/** The parsed query's JSON form (`toJSON`): the tree with the language version
+ * it was produced under. */
+export type QueryJson = Query & {
+    oqx: string;
+};
 //# sourceMappingURL=ast.d.ts.map

package/dist/ast.d.ts.map

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

package/dist/ast.js

@@ -1,7 +1,22 @@
-// 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.
-export {};
+// 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`).
+/** The expression kinds (`Expr["kind"]`), for `isExpr`. */
+const EXPR_KINDS = new Set([
+    "lit", "ident", "outer", "binding", "member", "call", "unary", "required", "binary", "logical", "in", "range", "tuple",
+]);
+/** 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) {
+    return EXPR_KINDS.has(node.kind);
+}
 //# sourceMappingURL=ast.js.map

package/dist/ast.js.map

@@ -1 +1 @@
-{"version":3,"file":"ast.js","sourceRoot":"","sources":["../src/ast.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,8EAA8E;AAC9E,+EAA+E;AAC/E,8EAA8E;AAC9E,2CAA2C"}
+{"version":3,"file":"ast.js","sourceRoot":"","sources":["../src/ast.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,8EAA8E;AAC9E,gFAAgF;AAChF,+EAA+E;AAC/E,2EAA2E;AAC3E,gFAAgF;AAChF,wDAAwD;AACxD,EAAE;AACF,iFAAiF;AACjF,gFAAgF;AAChF,4EAA4E;AAC5E,wCAAwC;AAsLxC,2DAA2D;AAC3D,MAAM,UAAU,GAAwB,IAAI,GAAG,CAAC;IAC9C,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO;CACvH,CAAC,CAAC;AAEH;wDACwD;AACxD,MAAM,UAAU,MAAM,CAAC,IAAa;IAClC,OAAO,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACnC,CAAC"}

package/dist/build.d.ts

@@ -0,0 +1,43 @@
+import type { BinaryOp, Consumer, CountCmp, Expr, Follow, FollowDestination, LogicalOp, OpNode, OrderSpec, Query, SelectItem, Span, Subquery, UnaryOp, Where } from "./ast.js";
+/** A fresh empty span (never shared: spans are mutable tuples). */
+export declare const span: () => Span;
+export declare const lit: (value: string | number | boolean | null) => Expr;
+export declare const ident: (name: string) => Expr;
+export declare const outer: (levels: number, name: string) => Expr;
+export declare const binding: (index: number) => Expr;
+export declare const member: (recv: Expr, name: string) => Expr;
+/** `a.b.c` from a dotted path. */
+export declare const path: (first: string, ...rest: string[]) => Expr;
+export declare const call: (recv: Expr | null, name: string, args?: Expr[]) => Expr;
+export declare const unary: (op: UnaryOp, expr: Expr) => Expr;
+/** `expr!` — the required value (SEMANTICS §5b). */
+export declare const required: (expr: Expr) => Expr;
+export declare const binary: (op: BinaryOp, left: Expr, right: Expr) => Expr;
+export declare const logical: (op: LogicalOp, left: Expr, right: Expr) => Expr;
+export declare const inOp: (left: Expr, right: Expr) => Expr;
+export declare const range: (lo: Expr | null, hi: Expr | null, exclusiveEnd?: boolean) => Expr;
+/** `(e1, e2, …)` — a tuple of two or more expressions (SEMANTICS §3b). */
+export declare const tuple: (items: Expr[]) => Expr;
+export declare const scalar: (expr: Expr) => Where;
+export declare const and: (parts: Where[]) => Where;
+export declare const or: (parts: Where[]) => Where;
+export declare const not: (expr: Where) => Where;
+export declare const field: (name: string, expr: Expr, lift?: number) => SelectItem;
+export declare const collect: (name: string, op: OpNode) => SelectItem;
+export declare const order: (expr: Expr, desc?: boolean) => OrderSpec;
+/** A block body; every clause defaults to empty/absent. */
+export declare function subquery(parts?: Partial<Omit<Subquery, "kind" | "span">>): Subquery;
+/** `<receiver> <op> [distinct] { sub } [<relop> N]`. */
+export declare function op(receiver: Expr, consumer: Consumer, sub?: Subquery, opts?: {
+    distinct?: boolean;
+    countCmp?: CountCmp | null;
+}): OpNode;
+/** `follow [distinct] <destinations>`; a destination's `where`/`frontier`/`depth`
+ * belong to its block (`op(recv, "collect", subquery({ depth: 2 }))`). */
+export declare function follow(destinations: FollowDestination[], opts?: {
+    distinct?: boolean;
+}): Follow;
+/** A top-level query over `source`; every other clause defaults to empty/absent
+ * and the consumer to `collect`. */
+export declare function query(source: Expr, parts?: Partial<Omit<Query, "kind" | "span" | "source">>): Query;
+//# sourceMappingURL=build.d.ts.map

package/dist/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EACpH,QAAQ,EAAE,OAAO,EAAE,KAAK,EACzB,MAAM,UAAU,CAAC;AAElB,mEAAmE;AACnE,eAAO,MAAM,IAAI,QAAO,IAAc,CAAC;AAEvC,eAAO,MAAM,GAAG,GAAI,OAAO,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,KAAG,IAA8C,CAAC;AAC7G,eAAO,MAAM,KAAK,GAAI,MAAM,MAAM,KAAG,IAA+C,CAAC;AACrF,eAAO,MAAM,KAAK,GAAI,QAAQ,MAAM,EAAE,MAAM,MAAM,KAAG,IAAuD,CAAC;AAC7G,eAAO,MAAM,OAAO,GAAI,OAAO,MAAM,KAAG,IAAkD,CAAC;AAC3F,eAAO,MAAM,MAAM,GAAI,MAAM,IAAI,EAAE,MAAM,MAAM,KAAG,IAAsD,CAAC;AACzG,kCAAkC;AAClC,eAAO,MAAM,IAAI,GAAI,OAAO,MAAM,EAAE,GAAG,MAAM,MAAM,EAAE,KAAG,IAA+D,CAAC;AACxH,eAAO,MAAM,IAAI,GAAI,MAAM,IAAI,GAAG,IAAI,EAAE,MAAM,MAAM,EAAE,OAAM,IAAI,EAAO,KAAG,IAA0D,CAAC;AACrI,eAAO,MAAM,KAAK,GAAI,IAAI,OAAO,EAAE,MAAM,IAAI,KAAG,IAAmD,CAAC;AACpG,oDAAoD;AACpD,eAAO,MAAM,QAAQ,GAAI,MAAM,IAAI,KAAG,IAAkD,CAAC;AACzF,eAAO,MAAM,MAAM,GAAI,IAAI,QAAQ,EAAE,MAAM,IAAI,EAAE,OAAO,IAAI,KAAG,IAA2D,CAAC;AAC3H,eAAO,MAAM,OAAO,GAAI,IAAI,SAAS,EAAE,MAAM,IAAI,EAAE,OAAO,IAAI,KAAG,IAA4D,CAAC;AAC9H,eAAO,MAAM,IAAI,GAAI,MAAM,IAAI,EAAE,OAAO,IAAI,KAAG,IAAmD,CAAC;AACnG,eAAO,MAAM,KAAK,GAAI,IAAI,IAAI,GAAG,IAAI,EAAE,IAAI,IAAI,GAAG,IAAI,EAAE,sBAAoB,KAAG,IAA+D,CAAC;AAC/I,0EAA0E;AAC1E,eAAO,MAAM,KAAK,GAAI,OAAO,IAAI,EAAE,KAAG,IAAgD,CAAC;AAEvF,eAAO,MAAM,MAAM,GAAI,MAAM,IAAI,KAAG,KAAiD,CAAC;AACtF,eAAO,MAAM,GAAG,GAAI,OAAO,KAAK,EAAE,KAAG,KAA+C,CAAC;AACrF,eAAO,MAAM,EAAE,GAAI,OAAO,KAAK,EAAE,KAAG,KAA8C,CAAC;AACnF,eAAO,MAAM,GAAG,GAAI,MAAM,KAAK,KAAG,KAA8C,CAAC;AAEjF,eAAO,MAAM,KAAK,GAAI,MAAM,MAAM,EAAE,MAAM,IAAI,EAAE,aAAQ,KAAG,UAAiE,CAAC;AAC7H,eAAO,MAAM,OAAO,GAAI,MAAM,MAAM,EAAE,IAAI,MAAM,KAAG,UAA2D,CAAC;AAC/G,eAAO,MAAM,KAAK,GAAI,MAAM,IAAI,EAAE,cAAY,KAAG,SAA0D,CAAC;AAE5G,2DAA2D;AAC3D,wBAAgB,QAAQ,CAAC,KAAK,GAAE,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,CAAM,GAAG,QAAQ,CAMvF;AAED,wDAAwD;AACxD,wBAAgB,EAAE,CAChB,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,GAAE,QAAqB,EAC9D,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAA;CAAO,GAC5D,MAAM,CAER;AAED;0EAC0E;AAC1E,wBAAgB,MAAM,CAAC,YAAY,EAAE,iBAAiB,EAAE,EAAE,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,MAAM,CAEnG;AAED;oCACoC;AACpC,wBAAgB,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK,GAAE,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC,CAAM,GAAG,KAAK,CAOvG"}

package/dist/build.js

@@ -0,0 +1,58 @@
+// 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`.
+/** A fresh empty span (never shared: spans are mutable tuples). */
+export const span = () => [0, 0];
+export const lit = (value) => ({ kind: "lit", span: span(), value });
+export const ident = (name) => ({ kind: "ident", span: span(), name });
+export const outer = (levels, name) => ({ kind: "outer", span: span(), levels, name });
+export const binding = (index) => ({ kind: "binding", span: span(), index });
+export const member = (recv, name) => ({ kind: "member", span: span(), recv, name });
+/** `a.b.c` from a dotted path. */
+export const path = (first, ...rest) => rest.reduce((e, n) => member(e, n), ident(first));
+export const call = (recv, name, args = []) => ({ kind: "call", span: span(), recv, name, args });
+export const unary = (op, expr) => ({ kind: "unary", span: span(), op, expr });
+/** `expr!` — the required value (SEMANTICS §5b). */
+export const required = (expr) => ({ kind: "required", span: span(), expr });
+export const binary = (op, left, right) => ({ kind: "binary", span: span(), op, left, right });
+export const logical = (op, left, right) => ({ kind: "logical", span: span(), op, left, right });
+export const inOp = (left, right) => ({ kind: "in", span: span(), left, right });
+export const range = (lo, hi, exclusiveEnd = false) => ({ kind: "range", span: span(), lo, hi, exclusiveEnd });
+/** `(e1, e2, …)` — a tuple of two or more expressions (SEMANTICS §3b). */
+export const tuple = (items) => ({ kind: "tuple", span: span(), items });
+export const scalar = (expr) => ({ kind: "scalar", span: span(), expr });
+export const and = (parts) => ({ kind: "and", span: span(), parts });
+export const or = (parts) => ({ kind: "or", span: span(), parts });
+export const not = (expr) => ({ kind: "not", span: span(), expr });
+export const field = (name, expr, lift = 0) => ({ kind: "field", span: span(), name, expr, lift });
+export const collect = (name, op) => ({ kind: "collect", span: span(), name, op });
+export const order = (expr, desc = false) => ({ kind: "order", span: span(), expr, desc });
+/** A block body; every clause defaults to empty/absent. */
+export function subquery(parts = {}) {
+    return {
+        kind: "subquery", span: span(),
+        from: [], where: null, select: [], orderBy: null, follow: null, frontier: null, depth: null, values: false, limit: null, offset: null,
+        ...parts,
+    };
+}
+/** `<receiver> <op> [distinct] { sub } [<relop> N]`. */
+export function op(receiver, consumer, sub = subquery(), opts = {}) {
+    return { kind: "op", span: span(), receiver, op: consumer, sub, countCmp: opts.countCmp ?? null, distinct: opts.distinct ?? false };
+}
+/** `follow [distinct] <destinations>`; a destination's `where`/`frontier`/`depth`
+ * belong to its block (`op(recv, "collect", subquery({ depth: 2 }))`). */
+export function follow(destinations, opts = {}) {
+    return { kind: "follow", span: span(), destinations, distinct: opts.distinct ?? false };
+}
+/** A top-level query over `source`; every other clause defaults to empty/absent
+ * and the consumer to `collect`. */
+export function query(source, parts = {}) {
+    return {
+        kind: "query", span: span(), source,
+        from: [], where: null, select: [], orderBy: null, consumer: "collect", follow: null, frontier: null,
+        distinct: false, values: false, limit: null, offset: null,
+        ...parts,
+    };
+}
+//# sourceMappingURL=build.js.map

package/dist/build.js.map

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

package/dist/context.d.ts

@@ -9,6 +9,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
@@ -18,6 +26,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
@@ -30,8 +45,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. */
@@ -61,17 +83,19 @@ export interface DefaultContextOptions {
     regexDialect?: RegexDialect;
 }
 /** 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); 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 declare class DefaultContext implements DataContext {
     private roots;
     readonly regexDialect: RegexDialect;
     constructor(roots?: Record<string, unknown>, options?: DefaultContextOptions);
     root(name: string): unknown;
+    rootObject(): unknown;
     get(row: unknown, key: string): unknown;
     toRows(value: unknown): Iterable<unknown>;
-    identity(row: unknown): unknown;
     callFunction(name: string, args: unknown[]): CallResult;
     callMethod(name: string, recv: unknown, args: unknown[]): CallResult;
 }

package/dist/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAQzD;kEACkE;AAClE,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,gFAAgF;IAChF,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5B;;;;;kFAK8E;IAC9E,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACxC,8DAA8D;IAC9D,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC1C;;;;;;;;;;yEAUqE;IACrE,WAAW,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;IACtC,8DAA8D;IAC9D,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC;IAChC,2EAA2E;IAC3E,YAAY,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,UAAU,CAAC;IACzD,oEAAoE;IACpE,UAAU,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,UAAU,CAAC;IACtE;;;;;;iCAM6B;IAC7B,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC;;;;;;;;;yCASqC;IACrC,QAAQ,CAAC,CAAC,UAAU,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,QAAQ,GAAG,SAAS,CAAC;CAC/E;AAED,MAAM,WAAW,qBAAqB;IACpC,uDAAuD;IACvD,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED;;;0EAG0E;AAC1E,qBAAa,cAAe,YAAW,WAAW;IAChD,OAAO,CAAC,KAAK,CAA0B;IACvC,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;gBAExB,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EAAE,OAAO,GAAE,qBAA0B;IAKpF,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI3B,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;IAMvC,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC;IAIzC,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO;IAK/B,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,UAAU;IAKvD,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,UAAU;CAKrE"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAQzD;kEACkE;AAClE,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,gFAAgF;IAChF,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5B;;;;;;8DAM0D;IAC1D,UAAU,CAAC,IAAI,OAAO,CAAC;IACvB;;;;;kFAK8E;IAC9E,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACxC,8DAA8D;IAC9D,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC1C;;;;;8DAK0D;IAC1D,QAAQ,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;IACnC;;;;;;;;;;yEAUqE;IACrE,WAAW,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;IACtC;;;;oFAIgF;IAChF,UAAU,CAAC,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC;IACnC;+CAC2C;IAC3C,QAAQ,CAAC,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC;IACjC,2EAA2E;IAC3E,YAAY,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,UAAU,CAAC;IACzD,oEAAoE;IACpE,UAAU,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,UAAU,CAAC;IACtE;;;;;;iCAM6B;IAC7B,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC;;;;;;;;;yCASqC;IACrC,QAAQ,CAAC,CAAC,UAAU,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,QAAQ,GAAG,SAAS,CAAC;CAC/E;AAED,MAAM,WAAW,qBAAqB;IACpC,uDAAuD;IACvD,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED;;;;;uBAKuB;AACvB,qBAAa,cAAe,YAAW,WAAW;IAChD,OAAO,CAAC,KAAK,CAA0B;IACvC,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;gBAExB,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EAAE,OAAO,GAAE,qBAA0B;IAKpF,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI3B,UAAU,IAAI,OAAO;IAIrB,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;IAMvC,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC;IAIzC,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,UAAU;IAKvD,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,UAAU;CAKrE"}

package/dist/context.js

@@ -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 —
@@ -14,9 +15,11 @@ function isIndexKey(key) {
     return /^(0|[1-9]\d*)$/.test(key);
 }
 /** 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); 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 {
     roots;
     regexDialect;
@@ -27,6 +30,9 @@ export class DefaultContext {
     root(name) {
         return Object.hasOwn(this.roots, name) ? this.roots[name] : undefined;
     }
+    rootObject() {
+        return this.roots;
+    }
     get(row, key) {
         if (row == null || typeof row !== "object")
             return undefined;
@@ -37,11 +43,6 @@ export class DefaultContext {
     toRows(value) {
         return coerceCollection(value);
     }
-    identity(row) {
-        if (row != null && typeof row === "object" && "id" in row)
-            return row.id;
-        return row;
-    }
     callFunction(name, args) {
         const fn = Object.hasOwn(BUILTIN_FUNCTIONS, name) ? BUILTIN_FUNCTIONS[name] : undefined;
         return fn ? { handled: true, value: fn(args) } : { handled: false };

package/dist/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,iFAAiF;AACjF,gFAAgF;AAChF,4EAA4E;AAC5E,4EAA4E;AAC5E,8FAA8F;AAC9F,gFAAgF;AAChF,EAAE;AACF,gFAAgF;AAChF,2EAA2E;AAE3E,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAIpG,0EAA0E;AAC1E,+DAA+D;AAC/D,SAAS,UAAU,CAAC,GAAW;IAC7B,OAAO,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACpC,CAAC;AAuFD;;;;;uBAKuB;AACvB,MAAM,OAAO,cAAc;IACjB,KAAK,CAA0B;IAC9B,YAAY,CAAe;IAEpC,YAAY,QAAiC,EAAE,EAAE,UAAiC,EAAE;QAClF,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,KAAK,CAAC;IACpD,CAAC;IAED,IAAI,CAAC,IAAY;QACf,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACxE,CAAC;IAED,UAAU;QACR,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,GAAG,CAAC,GAAY,EAAE,GAAW;QAC3B,IAAI,GAAG,IAAI,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QAC7D,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;YAAE,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC9E,OAAO,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAE,GAA+B,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACrF,CAAC;IAED,MAAM,CAAC,KAAc;QACnB,OAAO,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;IAED,YAAY,CAAC,IAAY,EAAE,IAAe;QACxC,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC,iBAAiB,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACxF,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IACtE,CAAC;IAED,UAAU,CAAC,IAAY,EAAE,IAAa,EAAE,IAAe;QACrD,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC;QACrG,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC,eAAe,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACpF,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC5E,CAAC;CACF"}

package/dist/engine.d.ts

@@ -1,10 +1,14 @@
 import type { Query, OpNode } from "./ast.js";
 import type { DataContext } from "./context.js";
 import type { Rule } from "./optimize/index.js";
-/** The shaped result of a top-level query, discriminated by consumer. */
+/** The shaped result of a top-level query, discriminated by consumer. A
+ * `collect` over a **single** receiver (one object, SEMANTICS §3) is one record
+ * or absent rather than a list: `single` is true and `rows` holds at most that
+ * one row (`unwrap` yields `rows[0] ?? null`). */
 export type OqxResult = {
     consumer: "collect";
     rows: unknown[];
+    single: boolean;
 } | {
     consumer: "exists";
     exists: boolean;
@@ -69,12 +73,18 @@ export declare class InMemoryEngine implements Engine {
     run(query: Query, bindings?: readonly unknown[]): OqxResult;
     private boundOf;
     private matches;
+    private coerceRows;
     private rowsOf;
+    private hostIdentity;
+    private scopeIdentity;
+    private applyKey;
     private child;
     private enter;
     private runFollow;
+    private keyed;
     private dedupByProjection;
     private followWalk;
+    private destinationRows;
     private shape;
     private projectRow;
     private itemValue;
@@ -98,12 +108,12 @@ export declare class InMemoryEngine implements Engine {
     private indexFor;
     private evalCollectValue;
     private evalCollectValuePlanned;
+    private evalCollectScopes;
     private sortScopes;
     private evalExpr;
     private evalRaw;
     private resolveIn;
+    private rowIdentity;
     private evalCall;
 }
-/** Convenience: run a query with plain-object roots (the default context). */
-export declare function runQuery(query: Query, bindings: readonly unknown[], roots: unknown): OqxResult;
 //# sourceMappingURL=engine.d.ts.map