@omgbase/oqx 0.15.0 → 0.20.0

package/README.md

@@ -16,7 +16,7 @@ JavaScript tagged template.
 > OQX is a language with more than one implementation; the specification is
 > [`spec/oqx`](https://github.com/omgbase/omgbase/tree/main/spec/oqx). The
 > language version is the package version's `major.minor` (`LANGUAGE_VERSION`,
-> `"0.15"`); the patch digit is this implementation's own.
+> `"0.17"`); the patch digit is this implementation's own.
 > Requirements: Node ≥ 22.13 for `@omgbase/oqx/sqlite`; Node ≥ 22.18 to run the
 > test suite (see [Requirements](#requirements)).
 
@@ -34,7 +34,7 @@ const company = "Globocorp";
 const employees = oqx`
   name, id, title
   from ${people}
-  where jobs exists { where employer == ${company} && !end_date }
+  where jobs exists { where employer == ${company} and not end_date }
 `;
 // → [{ name: "Bob", id: 124, title: "Engineer" }, …]  (current Globocorp employees)
 ```
@@ -56,8 +56,8 @@ once, and every one is optional except `from` at the top level:
 ```
 [ [select] projection ]    name, id, title: label        (or: select distinct …, … values)
 from <collection>          from ${people}
-[ where <predicate> ]      where age >= 18 && jobs exists { where !end }
-[ follow <dest>, … ]       follow children { depth 4 }     (or: follow before, after; follow ^people collect { … })
+[ where <predicate> ]      where age >= 18 and jobs exists { where not end }
+[ follow <dest>, … ]       follow children { depth 4 }     (or: follow before, after; follow ^people { where … })
 [ order by <expr> … ]      order by age desc, name
 [ limit N ]                limit 10
 [ offset N ]               offset 20
@@ -65,9 +65,12 @@ from <collection>          from ${people}
 
 **`select` is the only keyword you may drop, and only when the projection comes
 first** (`name, id from ${people}`). Every other clause always carries its
-keyword — in particular a predicate is never implicit, so a block filters with
-`where` (`jobs exists { where !end }`), and `from ${people} count` is an error
-rather than a projection of a field called `count`. Writing a clause out of
+keyword — with one piece of sugar (0.17): a **block** whose leading expression
+is syntactically a predicate is a `where`-first body (`jobs exists { !end }` ≡
+`jobs exists { where !end }`; a bare name still projects, so `jobs { employer }`
+projects and `jobs { is current }` filters — see §10). At the top level a
+predicate always needs `where`, and `from ${people} count` is an error rather
+than a projection of a field called `count`. Writing a clause out of
 order is a parse error that names the order (`` `select` must come before
 `from` — OQX clause order is select, from, where, follow, order by, limit,
 offset ``). The same body grammar applies inside every consumer block
@@ -171,7 +174,10 @@ oqx`employee: $it from ${people} where name == "Bob"`;         // [{ employee: <
 ```
 
 Inside a nested block `$it` is the inner item; the enclosing row is `^$it`
-(§3). At the root scope (before any row) it is absent. `$it` is the only name
+(§3). At the root scope `$it` is the context's **root object** (language 0.18;
+`DataContext.rootObject()` — `DefaultContext` returns the roots record, so
+`^$it` from a top-level row is `{ people, … }` and `entries(^$it)` lists the
+named roots). `$it` is the only name
 for the current item (language 0.15; through 0.14 it was spelled `$value`, and
 there is no synonym): `$value` is now an ordinary property read, like any other
 non-metadata `$name` — a row `{ "$value": 3 }` projects `3`, a row without one
@@ -194,19 +200,22 @@ const flags = { beta: { on: true }, legacy: { on: false } };
 oqx`$key values from entries(${flags}) where on`;                    // ["beta"]  (bare `on` reads the value)
 
 oqx`name, on: entries(prefs) collect { $key values where $it } from ${users}`;   // as a nested receiver
-oqx`name from ${users} where entries(prefs) exists { where $key == "dark" && $it }`;
+oqx`name from ${users} where entries(prefs) exists { where $key == "dark" and $it }`;
 ```
 
 `entries(array)` yields numeric index keys, a `Map` yields its entries, and
-absence/scalars yield nothing. `$key` exists **only** in an entry scope — an
-ordinary row or array element has no implicit index; `entries(arr)` is how you
+absence/scalars yield nothing. An entry's `$key` is its key — and since
+language 0.20 `$key` is the **identity** every row is known by (§9): an
+ordinary row's `$key` is the host's identity, structurally the row itself for
+plain data; an array element has no implicit index — `entries(arr)` is how you
 ask for one. As a plain value (not a source) `entries(x)` is an array of
 `{ key, value }` records.
 
 ### 3. Predicates (where)
 
 `where` filters rows. The predicate language has comparisons (`== != < <= > >=`),
-boolean operators (`&& || !`) with grouping `( )`, membership (`in`), arithmetic
+boolean operators — the words `and`, `or`, `not`; the symbols `&& || !` are
+accepted synonyms — with grouping `( )`, membership (`in`), arithmetic
 (`+ - * / %`), and bare truthiness. The `where` keyword is always written — a
 leading expression without it is a projection, and a bare comparison in that
 position is an error that points you at `where`.
@@ -259,9 +268,10 @@ against the value of `x`; a string in `x` can't inject operators or identifiers.
 
 **`where` sees the `select` aliases.** A name defined in the same body's
 projection may be used in its `where`; an alias shadows a same-named field
-there. It is a compile-time rewrite — the alias's expression is substituted
-inline — so it costs nothing at run time and a storage planner still sees an
-ordinary predicate:
+there. The alias's expression is substituted inline before evaluation
+(`resolveAliases`, applied once by the run entry points — the parsed tree keeps
+what you wrote), so it costs nothing at run time and a storage planner still
+sees an ordinary predicate:
 
 ```js
 oqx`select name, adult: age >= 18 from ${people} where adult`;        // ≡ where age >= 18
@@ -280,7 +290,11 @@ an alias. `order by` is not rewritten — it reads row fields (§8).
 against the **current row only**. If the row lacks that property the value is
 absent — it never falls through to an enclosing row. To correlate with an
 enclosing scope you say so explicitly with `^name` ("exactly one scope out";
-`^^name` for two, and so on):
+`^^name` for two, and so on) — or by **depth** with `N^name` (language 0.18):
+`0^people` is the root scope's `people` from any depth, `1^name` the top-level
+row's `name`, `0^$it` the root object. `N^` is an integer touching a caret
+(`1 ^x` is not one); it is pure sugar for the caret form with `levels = depth −
+N`, and `N ≥ the current depth` is a parse error.
 
 ```js
 const accounts = [
@@ -308,7 +322,7 @@ from a row nested one level deeper. A receiver may start with `^` too, which is
 how a nested consumer runs over a named root or an enclosing row's relation:
 
 ```js
-execute("name, peers: ^people collect { name where city == ^city && name != ^name } from people", { people });
+execute("name, peers: ^people collect { name where city == ^city and name != ^name } from people", { people });
 ```
 
 **Correlated subqueries.** Because inner and outer rows often share names, the
@@ -323,7 +337,7 @@ const family = [
 ];
 oqx`
   name,
-  siblings: ${family} collect { name where parent == ^parent && name != ^name }
+  siblings: ${family} collect { name where parent == ^parent and name != ^name }
   from ${family}
 `;
 // [{ name: "Ada", siblings: [{ name: "Ben" }] },
@@ -346,7 +360,7 @@ Methods on a value: `contains`, `startsWith`, `endsWith`, `matches` (regex),
 ```js
 oqx`name from ${people} where title.startsWith("Eng")`;      // → Bob
 oqx`name from ${people} where title.lower() == "director"`;  // → Alice
-oqx`name from ${people} where has(age) && !has(nickname)`;   // present vs absent
+oqx`name from ${people} where has(age) and not has(nickname)`;   // present vs absent
 oqx`name from ${people} where tags.contains("admin")`;       // array membership
 ```
 
@@ -580,8 +594,10 @@ Reached rows expose recursion **intrinsics** in `select` / `order by`:
 graph beyond — a boundary or the depth cap), `$ordinal` (a deterministic 1..N
 rank over the walk, ordered by depth then path), and `$stop`
 (`"interior"` / `"leaf"` / `"frontier"` / `"depth"` / `"cycle"`, precedence
-cycle > frontier > depth > leaf > interior — only `interior` rows expand). Options
-go in a trailing block:
+cycle > frontier > depth > leaf > interior — only `interior` rows expand). A
+brace after a destination opens that destination's **block** (language 0.20),
+whose body has two clauses of its own after `where`: `depth <n>` and
+`frontier <pred>`:
 
 ```js
 oqx`id, stop: $stop from ${tree} follow children { depth 2 } order by $ordinal`;
@@ -593,10 +609,10 @@ a nested block (`kids: children collect { … }`) a bare `$depth` is the nested
 row's own `$depth` property (absent unless the data carries one), and the
 occurrence's depth is `^$depth`. The same holds everywhere the metadata is not
 present — outside a `follow`, `$depth`/`$ordinal`/`$stop`/`$leaf`/`$frontier`
-are ordinary property reads (a row `{ "$depth": 3 }` projects `3`), and `$key`
-is likewise an ordinary property read outside an `entries()` scope. Where the
-metadata exists it wins over a same-named property (language 0.13; before, the
-six names read absent everywhere they were not metadata).
+are ordinary property reads (a row `{ "$depth": 3 }` projects `3`). `$key` is
+the exception: it is the row's identity everywhere (below). Where the metadata
+exists it wins over a same-named property (language 0.13; before, the six names
+read absent everywhere they were not metadata).
 
 The walk is **per-path**: a node reached by N distinct paths yields N
 occurrences, and revisiting an identity already on the current path is admitted
@@ -605,42 +621,159 @@ runaway. `follow distinct` collapses occurrences to reached nodes (the minimal
 `(depth, path)` per identity).
 
 **Destinations** (language 0.14) are comma-separated; the walk is their union.
-A **plain destination** is a relation of the current row (`children`, `doc.out`
-— an outer reference `^rel` or a literal is a parse error). A **destination
-block** is a receiver followed by `collect`, `first` or `single` (optionally
-`distinct`) and a block — the same directive you would write in `select`,
-re-evaluated per frontier row with `^` bound to that row. Its receiver *may* be
-an outer reference, so a walk can compute successors from a named root:
+A **plain destination** is a relation of the current row (`children`, `doc.out`,
+`entries(kids)`, a tuple `(before, after)` — one destination over the union of
+its elements; an outer reference `^rel` on its own or a literal is a parse
+error). A **destination block** is a receiver followed by a block — `children {
+depth 2 }`, `^people { where manager == ^id }`, `(before, after) { depth 2 }`,
+or with its consumer, `^chain first distinct { … }` — the same directive you
+would write in `select`, re-evaluated per frontier row with `^` bound to that
+row. Its receiver *may* be an outer reference, so a walk can compute successors
+from a named root. Since language 0.20 **a brace after any destination opens
+that destination's block** (there is no options block any more):
 
 ```js
 const people = [{ id: 1, manager: null }, { id: 2, manager: 1 }, { id: 3, manager: 1 }, { id: 4, manager: 2 }];
-oqx`id values from ${people} where id == 1 follow ^people collect { where manager == ^id } order by $ordinal`;
+oqx`id values from ${people} where id == 1 follow ^people { where manager == ^id } order by $ordinal`;
 // [1, 2, 3, 4] — the reporting tree under person 1 (`^people` names the root from a top-level walk)
+oqx`id values from ${people} where id == 1 follow ^people { where manager == ^id depth 2 } order by $ordinal`;
+// [1, 2, 3] — `depth` is a clause of the destination block, after its `where`
 
 const chain = [{ id: "a" }, { id: "b", prev: "a" }, { id: "c", prev: "b" }];
-oqx`id values from ${chain} where id == "b" follow distinct ^chain collect { where id == ^prev }, ^chain collect { where prev == ^id } order by $ordinal`;
+oqx`id values from ${chain} where id == "b" follow distinct ^chain { where id == ^prev }, ^chain { where prev == ^id } order by $ordinal`;
 // ["b", "a", "c"] — both directions of a chain; a block may order, bound and `distinct` its rows
 ```
 
-A row's successors are, per destination in order, that destination's rows,
-filtered by the follow `where`, then **unioned by identity within the step**: a
-node reached by two destinations (or twice by one relation) in the same step is
-a single successor. `exists`/`none`/`count` are not destinations (they are
+A row's successors are, per destination in order, that destination's rows
+(shaped by the block's projection, if any), then **unioned by identity within
+the step**: a node reached by two destinations (or twice by one relation) in the
+same step is a single successor, and the destination that reached it first
+governs it. `exists`/`none`/`count` are not destinations (they are
 where-position tests).
 
-The block accepts: `where <succ>` (which successors keep participating),
-`frontier <pred>` (cut a relation that could continue, whichever destination
-reached it), `depth <n>` (1–8), and `by <expr>` (the identity used for cycle
-detection + `distinct` — default `.id` or the object reference). The follow
-`where` is **correlated**: it reads the candidate successor's scope whose parent
-is the frontier row's — a bare name is the candidate's own property, `^name` is
-the row being expanded, `^^name` the walk's enclosing scope (language 0.14;
-before, `^` skipped the frontier row). So `follow doc.in { where
-before.contains(^$path) }` steps only into rows that name the row they were
-reached from. `frontier` and `by` are not correlated: they read the occurrence
-with `^` the enclosing scope, as the body does. Give `follow` a stable identity
-(`.id` or `by`) when your relation returns fresh objects rather than shared
-references.
+A destination block's body is an ordinary block — `where <succ>` (which
+successors keep participating), a projection, `order by`, `limit`/`offset`,
+`distinct` — plus two clauses after `where`: `frontier <pred>` (an occurrence
+this destination reached for which it holds is a frontier — cut, not expanded)
+and `depth <n>` (1–8: this destination expands a frontier row only while its
+`$depth < n`; a destination block's clause alone). The block's `where` is **correlated**: it reads
+the candidate successor's scope whose parent is the frontier row's — a bare name
+is the candidate's own property, `^name` is the row being expanded, `^^name` the
+walk's enclosing scope (language 0.14; before, `^` skipped the frontier row). So
+`follow doc.in { where before.contains(^$path) }` steps only into rows that
+name the row they were reached from. `frontier` is not correlated: it reads the
+occurrence with `^` the enclosing scope, as the body does; seeds are reached
+through no destination and are never frontiers by a destination's rule. **The
+body that carries the `follow` may write `frontier <pred>` too**, after its
+`where` and before `follow`: it applies to the seeds — a matching seed stays in
+the result with `$stop == "frontier"` and is not expanded (`id from tree frontier
+!active follow children { depth 2 }`); read in the seed's scope like the body's
+`where`. Each destination's `frontier` is its own; without a `follow`, a
+body-level `frontier` is a parse error.
+
+**Identity is `$key`** (language 0.20). Cycle detection, the per-step union,
+`follow distinct`, `distinct` over unprojected rows and `is` all compare one
+thing — the identity a row is known by — and reading `$key` on any row returns
+it. The default is the host's (`DataContext.identityOf`), else the row's
+**structural value**; `DefaultContext` names none, so over plain objects two
+objects with the same `id` are two nodes. A block may project `$key: <expr>` to
+give the rows it yields that identity — the body's `select` names the seeds, a
+destination block its successors (where `$key:` is not a column; the rows keep
+their shape):
+
+```js
+const n1 = { id: 1 }, n2 = { id: 2, next: [n1] }; n1.next = [n2];   // a cyclic graph of fresh references
+oqx`id, stop: $stop, $key: id from ${[n1]} follow next { $key: id } order by $ordinal`;
+// [{ id: 1, stop: "interior", $key: 1 }, { id: 2, stop: "interior", $key: 2 }, { id: 1, stop: "cycle", $key: 1 }]
+oqx`name, $key: email from ${people} follow next { $key: email }`;   // known by email at every step
+```
+
+Identities are compared as values across the whole walk, so destinations that
+can reach the same rows should project the same `$key`, or a cycle through both
+may run to the depth cap. Give a cyclic graph of fresh objects a `$key` (or a
+context with `identityOf`) rather than rely on the structural default.
+
+### 9b. Cardinality and tuples (0.20)
+
+In row position an **array** is a collection and a non-array **object** is one
+row: a block over it yields **one record** (or absent, when the row is filtered
+out) rather than a one-element list, `values` the one value, `first`/`single`
+that object — `doc { title }` is `{ title }`, `doc { status == "active" }` is the
+object or absent (a conditional reach-through), `title from doc` the same record.
+A scalar in row position is an eval error (`list(s)` says "one element"
+explicitly); a `from` re-projection or a `follow` is plural. A host says which
+of its objects are collections through `DataContext.isSingle` (a lazy handle);
+by default a non-iterable object is one row.
+
+```js
+oqx`${settings} { theme }`;             // { theme: "dark" }      (one object → one record)
+oqx`${[settings]} { theme }`;           // [{ theme: "dark" }]    (a collection → a list)
+oqx`from list(${settings})`;            // [settings]             (the explicit one-element collection)
+```
+
+A **tuple** `(e1, e2, …)` — two or more expressions in parentheses — is a value
+and a receiver: its elements concatenated with one level of flattening (a
+collection contributes its items, a row itself; an absent element nothing, a
+`null` is kept; duplicates kept). One parenthesized expression is grouping.
+
+```js
+oqx`n: size((tags, aliases)) from ${people}`;                       // one count over both lists
+oqx`name from ${people} where "x" in (tags, aliases)`;              // membership in the union
+oqx`n: (mom, dad, siblings) { name values } from ${people}`;        // one block over the union
+oqx`id from ${g} follow (before, after) { depth 2 }`;               // one destination over the union
+```
+
+### 10. Sugar (0.17)
+
+Every form below is shorthand for an explicit directive — it **desugars in the
+parser** to the nodes you already know (`print` writes the explicit form, the
+optimizer and any pushdown planner see it), so nothing here has semantics of its
+own except the postfix `!` and the infix `is`:
+
+```js
+// A receiver block without a consumer is `collect` — wherever a value stands
+// (language 0.20): a select item, a where leaf, a follow destination, a call
+// argument; `x distinct { … }` is `x collect distinct { … }`. A block whose
+// LEADING expression is syntactically a predicate drops `where`.
+oqx`name, current: jobs { !end_date } from ${people}`
+//   ≡ name, current: jobs collect { where !end_date } from ${people}
+oqx`${people} { age > 40 }`                  // ≡ ${people} collect { where age > 40 }
+oqx`n: size(jobs { !end_date }) from ${people}`   // a block as a call argument
+oqx`${people} distinct { city }`             // ≡ ${people} collect distinct { city }
+oqx`${people} count { jobs exists { } }`     // a consumer test is predicate-shaped too
+oqx`${people} first { name }`                // a bare name still projects — unchanged
+oqx`${people} first { is active }`           // the bare-field filter: `is x` ≡ `!!x`, `not x` ≡ `!x`
+
+// Brackets: `[p]` is `first { where p }`, `[n]` is `first { offset n }`;
+// a trailing `!` requires the result (and makes the predicate form `single`).
+oqx`name, boss: ^people[id == ^manager].name from ${people}`   // the first match, navigated
+oqx`name, first_job: jobs[0], primary: jobs[pay > 2]! from ${people}`
+//   jobs[0]          ≡ jobs first { offset 0 }        (out of range ⇒ absent)
+//   jobs[pay > 2]!   ≡ jobs single { where pay > 2 }!  (zero or many matches ⇒ an eval error)
+
+// Postfix `!` — required: the value, or an eval error naming the expression
+// (and the row's `$key` when scalar). Never a filter, never a coercion: 0! and ""! are values.
+oqx`select id!, title from ${docs}`           // insist on an identity before a write
+// Tightest precedence: `refs(c)[0]!.name` requires the lookup, `refs(c)[0].name!` the name.
+
+// `is` / `is not` compare IDENTITY (`$key`: the host's, else structural — §9):
+oqx`name from ${people} where manager is null`            // absent (same as == null)
+oqx`${people} count { ^people exists { $it is ^$it } }`   // rows compare; `==` leaves that unspecified
+// `and` / `or` / `not` are the canonical connectives; `&&` / `||` / `!` are exact
+// synonyms (`title or path` coalesces). `print` writes the words (language 0.18); `!` stays `!`.
+
+// A select item may use the items to its left (inlined like a `where` alias):
+oqx`boss: ^people[id == ^manager], bossName: boss.name from ${people}`
+```
+
+Reserved words, never a bare field name: `from where select is not and or` and
+the literal words `true false null`. The top level is unchanged — `age > 15
+from ${people}` stays an error, because `where` would precede `from`. One
+carve-out: after a `follow` destination that is a relation of the current row
+(a bare name, a call, a binding) a brace is still the **options** block (`follow
+children { depth 2 }`), never a collect; only over an outer-reference receiver,
+which cannot be a plain destination, is the brace a destination block with the
+implicit `collect` (`follow ^people { where … }`, language 0.19).
 
 ### Cheat-sheet
 
@@ -648,8 +781,12 @@ references.
 select … from … where … follow … order by … limit N offset N   the fixed clause order (each at most once)
 name, alias: expr, nested: rel collect { … }   projection (`select` may be dropped only here, in first position)
 from ${source}                                  source collection (required at the top level)
-where a == b && rel exists { where … } || !c    predicate tree + nested ops (`where` is never implicit)
-where alias                                      `where` may use this body's select aliases (inlined; an alias shadows a field)
+where a == b and rel exists { where … } or not c  predicate tree + nested ops (`&&`/`||`/`!` are accepted synonyms)
+rel { pay > 2 }  /  rel { employer }            a block without a consumer is collect; a leading predicate is where-first, a bare name projects
+rel[p]  /  rel[p]!  /  rel[0]  /  rel[0]!       first match / exactly one (required) / positional / required positional
+x!                                               required: the value, or an error when absent (tightest; `a!.b` vs `a.b!`)
+is x / not x  /  x is y / x is not y             truthiness (≡ !!x / !x) / identity ($key: the host's, else structural; absent ≡ null)
+where alias  /  a: expr, b: a                    `where` and later items may use this body's select aliases (resolved before evaluation; an alias shadows a field)
 where rel none { … }                             zero rows (≡ !rel exists { … }; "all" = none over the complement)
 where x in lo..hi / lo...hi / ..hi / lo..        range membership (incl. / excl. / open-ended)
 where x in range(field)                          coerce a string field to a range, then test coverage
@@ -663,12 +800,87 @@ from entries(obj) … $key / $it                   a record's properties as a co
 entries(rel) exists { … }                        a free-function call may be a receiver
 order by expr desc, expr2                        ordering
 limit n / offset n                               bound the row set (after where/order/distinct, before the consumer)
-follow rel { where … frontier … depth n by … }  recursion ($depth/$stop/$leaf/$frontier); `^name` in the where is the frontier row
-follow before, after                             several destinations: the union of their rows (per step, by identity)
-follow ^people collect { where manager == ^id } a destination block: successors computed per frontier row (`^` = that row)
+follow rel { where … frontier … depth n }       recursion ($depth/$stop/$leaf/$frontier/$key); the brace is the destination's block, `^name` in its where the frontier row
+follow before, after  /  follow (before, after)  several destinations: the union of their rows (per step, by identity) / one tuple destination
+follow ^people { where manager == ^id }         a destination block: successors computed per frontier row (`^` = that row; `collect` implicit, 0.20)
+$key  /  $key: expr                              the identity a row is known by (the host's, else structural) / give the rows a block yields that identity
+(a, b)  /  rel distinct { … }                   a tuple: the elements, one level flat (a value and a receiver) / collect distinct (0.20)
+obj { title }                                   one object → one record (or absent); a collection → a list; a scalar → an error (0.20)
 ${source} <collect|exists|none|count|first|single> { … }   whole-query consumer
 ```
 
+## The AST: reflecting on a query
+
+`parse(source)` returns the query's abstract syntax tree, and since language
+0.16 that tree is a **public contract** shared by both implementations
+([`spec/oqx/AST.md`](https://github.com/omgbase/omgbase/tree/main/spec/oqx/AST.md)):
+a tool reflects on a query — which relations it names, which clauses it has,
+where in the text each piece sits — without re-parsing. The objects are plain
+data (no parent pointers, no methods) and *are* the JSON shape.
+
+- **Every node has `kind` and `span`.** `span` is `[start, end)` in Unicode
+  **code points** over the raw source (for a template, `rawSource(strings)`,
+  where a binding occupies its `${n}` marker); `toUtf16(span, source)` converts
+  for an editor that counts UTF-16 units. A parenthesized operand spans its
+  parentheses; a block (`subquery`) spans its braces.
+- **Optionals are materialized** — `where: null`, `limit: null`, `countCmp: null`,
+  `distinct: false`, `values: false` — so nothing has to be defaulted.
+- **`where` keeps its surface form.** A `select` alias used in `where` stays an
+  `ident` in the tree; `resolveAliases(query)` is the pure substitution the run
+  entry points (`oqx`, `run`, `execute`, `runQuery`) apply exactly once before
+  evaluation. An `Engine.run` evaluates the query it is given — if you drive an
+  engine yourself, resolve first.
+
+```js
+import { parse, visit, transform, print, printTemplate, toJSON, stripSpans, build } from "@omgbase/oqx";
+
+const q = parse('select name, n: jobs collect { employer } from people where jobs exists { where !end }');
+
+// visit: every node, with its ancestors, the clause it sits in, and the scope depth
+const relations = [];
+visit(q, {
+  enter(node, { clause, depth }) {
+    if (node.kind === "op") relations.push({ relation: print(node.receiver), clause, depth });
+  },
+});
+// → [{ relation: "jobs", clause: "select", depth: 1 }, { relation: "jobs", clause: "where", depth: 1 }]
+
+// transform: rebuild with every expression mapped (children first; untouched nodes keep identity + spans)
+const rewritten = transform(q, (e) => (e.kind === "ident" && e.name === "name" ? build.member(build.ident("person"), "name") : e));
+
+// print: the canonical source — single spaces, `select` written, minimal parentheses
+print(rewritten);
+// 'select name: person.name, n: jobs collect { employer: employer } from people where jobs exists { where !end }'
+
+toJSON(q);        // { oqx: "0.17", kind: "query", span: [0, 93], … } — the shared JSON document
+stripSpans(q);    // the same tree without spans, for shape comparisons
+```
+
+`visit(root, { enter?, leave? })` walks depth-first in canonical source order;
+`enter` may return `false` to skip a subtree. Its context is `{ path, clause,
+depth }` — the ancestors, the clause (`source` · `from` · `where` · `select` ·
+`orderBy` · `limit` · `offset` · `follow` · `follow.destination` · `follow.where`
+· `follow.frontier` · `follow.by`; `null` at the root) and the **scope depth**
+the node is evaluated at (0 = the root scope: a top-level source or bound; 1 =
+a top-level row; a block's body is one deeper than its receiver). Both walks
+are driven by one child-key table, `CHILDREN`, so a future field is added in one
+place.
+
+`print(node)` is canonical, and the law `stripSpans(parse(print(parse(q))))`
+≡ `stripSpans(parse(q))` holds for every spec fixture (both runners check it);
+`print(parse(q)) === q` is *not* a law — spelling is normalized. A binding is a
+value, never source text: `print` throws (`OqxError`, stage `"print"`) on one,
+and `printTemplate(node)` returns `{ strings, count, indices }` — the fragments
+around each binding and the binding each gap stands for (the canonical clause
+order can move one past another), to re-run with `parseTemplate(strings,
+count)` and the values permuted by `indices`.
+
+`build.*` constructs nodes with the empty span `[0, 0]` and the materialized
+defaults (`build.query(source, { select, where, … })`, `build.op(receiver,
+"collect", build.subquery({ … }))`, `build.field`, `build.collect`,
+`build.follow`, `build.ident`, `build.lit`, `build.binary`, `build.and`, …), so
+a tree you assemble prints with `print` and has the shape of a parsed one.
+
 ## Data context: string queries and named roots
 
 When you don't need interpolation, `execute` runs a plain string query against a
@@ -687,7 +899,8 @@ the full discriminated result (`{ consumer, … }`).
 ## Architecture: adapting to other storage & query systems
 
 OQX is layered so it can be the front-end for query systems far beyond in-memory
-objects. The parsed `Query` AST is the host-agnostic IR; execution is pluggable.
+objects. The parsed `Query` AST is the host-agnostic contract (above); execution
+is pluggable.
 
 ```
 Query AST  ─┬─ InMemoryEngine(DataContext)     tier 1/2 — drive any data model
@@ -705,8 +918,13 @@ than approximate it. The conformance suite verifies this.
 
 The engine never touches host objects directly; it asks a `DataContext` to
 resolve named roots, read properties/relations, coerce results to rows, and
-compute identity. Implement it to query an ORM graph, a remote API, or lazily
-loaded relations — the query *semantics* stay in OQX. Name resolution is simple
+optionally to name a row's identity (`identityOf` — `$key`; the default is the
+row's structural value), to say which of its objects are collections rather
+than one row (`isSingle`; by default a non-iterable object is one row, so a
+block over it is one record), and to supply a `rootObject()` — the root
+scope's row, what `$it` is at the root and `^$it` from a top-level row; without
+one the root row is absent. Implement it to query an ORM graph, a remote API,
+or lazily loaded relations — the query *semantics* stay in OQX. Name resolution is simple
 for a context: a bare `field`, a `.field` segment, and a `^field` outer
 reference each become one `get(row, key)` against exactly the row of the scope
 they name, so a computed relation only needs `get` to know about it:
@@ -718,7 +936,7 @@ const graph = {
   root: (name) => name === "tree" ? [nodes.get(1)] : undefined,
   get:  (row, key) => key === "children" ? row.childIds.map(id => nodes.get(id)) : row[key],
   toRows: (v) => v == null ? [] : Array.isArray(v) ? v : [v],
-  identity: (row) => row.id,                                // for follow dedup
+  identityOf: (row) => row.id,                              // `$key`: for follow dedup, distinct, `is` (optional; default: structural)
 };
 run(parse("id, depth: $depth from tree follow children"), { context: graph });
 ```
@@ -751,7 +969,7 @@ const ctx = {
     return builtins.callMethod(name, recv, args);
   },
 };
-run(parse("id from tree where age(born) > 18 && title.slug() == 'x'"), { context: ctx });
+run(parse("id from tree where age(born) > 18 and title.slug() == 'x'"), { context: ctx });
 ```
 
 The simplest route is to `extends DefaultContext` and `super.callFunction(...)`
@@ -777,7 +995,7 @@ import { parse, PlannedEngine } from "@omgbase/oqx";
 import { SqliteTable } from "@omgbase/oqx/sqlite";
 
 const planner = new SqliteTable(db, "emp", { columns: ["id", "name", "dept", "level"] });
-new PlannedEngine(planner).run(parse('name from emp where dept == "eng" && level >= 5'), []);
+new PlannedEngine(planner).run(parse('name from emp where dept == "eng" and level >= 5'), []);
 // → `dept`/`level` pushed to SQL; anything untranslatable finishes in-memory
 ```
 
@@ -808,7 +1026,7 @@ results and on errors.
 
 **What is optimized**
 
-- **Correlated equality → hash probe.** A top-level `&&` conjunct of the block's
+- **Correlated equality → hash probe.** A top-level `and` conjunct of the block's
   `where` of the form `local == outer` (either side) — `local` a bare identifier
   or member chain on the block's row (`customer_id`, `meta.id`, `$it`),
   `outer` anything that reads nothing from that row (`^customer_id`, `^^x.id`,
@@ -830,7 +1048,7 @@ results and on errors.
   by`) are answered from the bucket's size after the bound without entering a
   row.
 
-**The sound rule.** `&&` is strictly left to right and short-circuiting (§13),
+**The sound rule.** `and` is strictly left to right and short-circuiting (§13),
 so a probe may skip a row only if everything the scan would have evaluated for
 it could neither raise nor bind: an equality is hoisted only when **every
 conjunct to its left is raise-free** — no function or method call, no `single`,
@@ -840,7 +1058,7 @@ too. A conjunct that could raise *right* of the equality is simply evaluated
 over the bucket, where the scan would have evaluated it on the same rows. A
 block whose `where` lifts anywhere is never probed (a lift could change what
 the outer side reads between rows). Otherwise the block scans as before, so
-`where nope(x) && id == ^id` still raises `unknown function`.
+`where nope(x) and id == ^id` still raises `unknown function`.
 
 Property reads are treated as total (§23: evaluation is otherwise total). A
 `DataContext.get` that throws is caught where the engine relies on reads it
@@ -908,7 +1126,8 @@ adapter lives on the `@omgbase/oqx/sqlite` subpath.
   consumer-shaped value: an array for `collect`, a boolean for `exists` / `none`,
   a number for `count`, a record or `null` for `first` / `single`.
 - `parse(source)` — a query string → reusable `Query` AST (an `OqxError` with
-  `stage: "lex" | "parse"` on bad input).
+  `stage: "lex" | "parse"` on bad input); `parseTemplate(strings, count)` the
+  tagged-template form, with `binding` nodes for the `${…}` slots.
 - `execute(source, roots?)` — parse and run a string against named roots
   (`{ people }`), returning the consumer-shaped value.
 - `run(query, opts?)` — run a parsed `Query`, returning the full `OqxResult`.
@@ -948,7 +1167,7 @@ adapter lives on the `@omgbase/oqx/sqlite` subpath.
   (the optimizer rules for nested blocks, default `DEFAULT_RULES`; `[]` is the
   naive scan) and `trace` (a `(event: TraceEvent) => void` sink for index /
   probe / memo / cardinality / fallback events). See [Performance](#performance-relational-patterns).
-- `DataContext` — the tier-2 interface: `root`, `get`, `toRows`, `identity`,
+- `DataContext` — the tier-2 interface: `root`, `get`, `toRows`, `identityOf`, `isSingle`,
   plus optional `callFunction` / `callMethod` (above), an optional
   `indexFor(collection, path)` returning a `RowIndex` for a pre-built equality
   index (`lookup` → positions; optionally `lookupRows` → rows, probed without
@@ -961,7 +1180,7 @@ adapter lives on the `@omgbase/oqx/sqlite` subpath.
   "native")`; `BUILTIN_METHODS.matches` is always the baseline.
 - `CallResult` — `{ handled: boolean; value?: unknown }`, returned by those hooks.
 - `DefaultContext` — `new DefaultContext(roots?, options?)`; plain-object
-  access, `.id` identity, and the builtin function/method tables. `options`:
+  access, structural identity (`$key` is the row itself unless projected), and the builtin function/method tables. `options`:
   `{ regexDialect?: RegexDialect }` (see the regex baseline, §4).
 - `compileRegex(pattern, flags?, dialect?)` — the `matches()` compiler: a
   `RegExp`, or an `OqxError` for a bad pattern/flag. `RegexDialect` /
@@ -1008,7 +1227,7 @@ adapter lives on the `@omgbase/oqx/sqlite` subpath.
   import { parse, run, IndexedCollection, PlannedEngine } from "@omgbase/oqx";
   const planner = new IndexedCollection("people", people, ["city", "title"]);
   const engine = new PlannedEngine(planner, planner.context());
-  run(parse('name from people where city == "NYC" && age > 30'), { engine });
+  run(parse('name from people where city == "NYC" and age > 30'), { engine });
   // city probe from the index; `age > 30` finished in-memory over the candidates
   ```
 
@@ -1032,11 +1251,30 @@ adapter lives on the `@omgbase/oqx/sqlite` subpath.
   - `map?: (raw) => row` — a custom raw-SQL-row → query-row mapper (overrides
     `jsonColumns`).
 
+**The AST** (see [above](#the-ast-reflecting-on-a-query); `spec/oqx/AST.md` is normative)
+
+- `visit(root, { enter?, leave? })` / `transform(root, f)` — the generic walks
+  (`Visitor`, `VisitContext`, `Clause` are the types); `CHILDREN` — the
+  child-key table per node kind that drives them.
+- `print(node)` / `printTemplate(node)` — the canonical printer (`Template` is
+  `{ strings, count, indices }`).
+- `resolveAliases(query)` — the `select`-alias substitution the entry points
+  apply before evaluation (SEMANTICS §14).
+- `toJSON(query)` — the tree stamped with `oqx: LANGUAGE_VERSION`; `stripSpans(node)`
+  — the tree without spans (`Stripped<T>`); `toUtf16(span, source)` and
+  `codePointLength(s)` — code-point ↔ UTF-16 offsets; `rawSource(strings)` —
+  the display source of a template.
+- `build` — the node builders (`build.query`, `build.op`, `build.subquery`,
+  `build.field`, `build.ident`, …).
+- `LANGUAGE_VERSION` — the `spec/oqx/VERSION` this implementation conforms to (`"0.17"`).
+
 **Types**
 
 - Every AST node type from `src/ast.ts` is re-exported (`Query`, `Subquery`,
-  `Where`, `Expr`, `OpNode`, `SelectItem`, `OrderSpec`, `Follow`, …) for
-  planners that walk the IR.
+  `Where`, `Expr`, `OpNode`, `SelectItem`, `OrderSpec`, `Follow`,
+  `AstNode`, `AstKind`, `Span`, …) for tools that reflect on queries and
+  planners that walk the tree; `isExpr(node)` tells an expression from the
+  structural nodes.
 
 ## Requirements