@omgbase/oqx 0.15.0 → 0.20.0

package/dist/engine.js

@@ -21,10 +21,19 @@
 import { DefaultContext } from "./context.js";
 import { OqxError } from "./errors.js";
 import { relate, arith, membership, truthy, compareForSort, compare, canonicalKey, makeRange, isEntry, isRange, } from "./semantics.js";
+import { printTemplate } from "./print.js";
 import { DEFAULT_RULES, HashIndex, intersectPositions, lookupOrder, planFor, residualWithout } from "./optimize/index.js";
 const RECUR = new Set(["$depth", "$stop", "$leaf", "$frontier", "$ordinal"]);
 const KEY = "$key";
 const HARD_DEPTH_CAP = 8;
+// The `$key: expr` item of a projection, if any — the identity the rows it
+// yields carry (SEMANTICS §16, since 0.20).
+function keyItem(proj) {
+    for (const it of proj.select)
+        if (it.kind === "field" && it.lift === 0 && it.name === KEY)
+            return it;
+    return null;
+}
 const UNBOUNDED = { offset: 0, limit: null };
 export class InMemoryEngine {
     ctx;
@@ -45,8 +54,12 @@ export class InMemoryEngine {
         };
         if (this.trace)
             run.trace = this.trace;
-        const root = { row: null, parent: null, bindings, run };
-        const rows = this.reproject(this.rowsOf(this.evalRaw(query.source, root)), query.from, root);
+        const root = { row: this.ctx.rootObject?.(), parent: null, bindings, run };
+        const src = this.coerceRows(this.evalRaw(query.source, root), query.source);
+        const rows = this.reproject(src.rows, query.from, root);
+        // One object as the source yields one record (SEMANTICS §3) — unless a
+        // `from` re-projection or a walk fans it out.
+        const single = src.single && query.from.length === 0 && !query.follow;
         const bound = this.boundOf(query, root);
         if (query.follow)
             return this.runFollow(query, rows, root, bound);
@@ -86,21 +99,26 @@ export class InMemoryEngine {
                     break;
             }
         }
+        this.applyKey(kept, query);
         this.sortScopes(kept, query.orderBy);
         if (query.distinct)
             kept = this.dedupByProjection(kept, query);
         kept = sliceBound(kept, bound);
-        return this.shape(query.consumer, kept, query);
+        return this.shape(query.consumer, kept, query, single);
     }
     // Evaluate a block's `limit`/`offset`. The bound is part of the block, so it
     // is read in a row-less scope INSIDE it: a bare name is absent (there is no
     // current item yet), `^name` is the enclosing row — exactly as in the block's
-    // body — and literals/bindings are themselves. For a top-level query `scope`
-    // is the root. Each must be a non-negative integer.
+    // body — and literals/bindings are themselves. For a top-level query the
+    // scope is the root scope WITHOUT its row (SEMANTICS §18): bare names are
+    // still the named roots, but `$it` — reached through a bracket inside the
+    // bound — is absent, not the root object. Each must be a non-negative integer.
     boundOf(b, enclosing) {
         if (!b.limit && !b.offset)
             return UNBOUNDED;
-        const scope = enclosing.parent === null ? enclosing : rowless(enclosing);
+        const scope = enclosing.parent === null
+            ? { row: undefined, parent: null, bindings: enclosing.bindings, run: enclosing.run }
+            : rowless(enclosing);
         const read = (e, word) => {
             if (!e)
                 return null;
@@ -118,8 +136,60 @@ export class InMemoryEngine {
             return true;
         return this.evalWhere(where, this.enter(row, parent));
     }
-    rowsOf(v) {
-        return Array.from(this.ctx.toRows(v));
+    // The rows of a value in row position (SEMANTICS §3): absent → none; an array
+    // (or a host iterable) → its elements, a collection; an object → one row, and
+    // the value is SINGLE — a block over it yields one result rather than a list;
+    // a scalar (a string, a number, a boolean) or a range → an eval error. A
+    // context says which of its objects are single (`isSingle`); without it, any
+    // non-iterable object is.
+    coerceRows(v, what) {
+        if (v == null)
+            return { rows: [], single: false };
+        if (Array.isArray(v))
+            return { rows: v, single: false };
+        if (typeof v !== "object" || isRange(v)) {
+            const kind = isRange(v) ? "a range" : typeof v === "string" ? "a string" : typeof v === "number" ? "a number" : typeof v === "boolean" ? "a boolean" : `a ${typeof v}`;
+            const shown = isRange(v) ? "" : ` (${JSON.stringify(v)})`;
+            const subject = what ? `\`${describe(what)}\` is` : "the receiver is";
+            throw new OqxError(`${subject} ${kind}${shown}, not a collection or an object — rows come from a collection (a list) or one object (a record)`, "eval");
+        }
+        const rows = Array.from(this.ctx.toRows(v));
+        const single = this.ctx.isSingle ? this.ctx.isSingle(v) : !(Symbol.iterator in v);
+        return { rows, single };
+    }
+    rowsOf(v, what = null) {
+        return this.coerceRows(v, what).rows;
+    }
+    // The host's identity of a row (SEMANTICS §16): an entry is known by its key;
+    // any other row by the context's `identityOf`, else by its structural value.
+    hostIdentity(row) {
+        if (isEntry(row))
+            return row.key;
+        if (this.ctx.identityOf)
+            return this.ctx.identityOf(row);
+        if (this.ctx.identity)
+            return this.ctx.identity(row);
+        return row;
+    }
+    // The identity a scope's row is known by — `$key`: the identity the walk or a
+    // `$key:` projection gave it (`meta`), else the host's.
+    scopeIdentity(scope) {
+        if (scope.meta && Object.hasOwn(scope.meta, KEY))
+            return scope.meta[KEY];
+        if (scope.parent === null && scope.row === undefined)
+            return undefined;
+        return this.hostIdentity(scope.row);
+    }
+    // A projection's `$key: expr` item gives the rows it yields that identity:
+    // evaluate it on each kept scope and record it as the scope's `$key`.
+    applyKey(scopes, proj) {
+        const item = keyItem(proj);
+        if (!item)
+            return;
+        for (const s of scopes) {
+            const key = this.evalExpr(item.expr, s);
+            s.meta = { ...(s.meta ?? {}), [KEY]: key };
+        }
     }
     child(row, parent) {
         return this.enter(row, parent);
@@ -145,7 +215,7 @@ export class InMemoryEngine {
     runFollow(query, rows, root, bound) {
         const { seed, post } = query.where ? partitionRecur(query.where) : { seed: null, post: null };
         const seeds = seed ? rows.filter((r) => this.matches(seed, r, root)) : rows;
-        const occ = this.followWalk(seeds, query.follow, root);
+        const occ = this.followWalk(this.keyed(seeds, query, root), query.follow, query.frontier, root);
         let scopes = occ.map((o) => this.enter(o.row, root, { lifts: {}, meta: o.meta }));
         if (post)
             scopes = scopes.filter((s) => this.evalWhere(post, s));
@@ -153,7 +223,13 @@ export class InMemoryEngine {
         if (query.distinct)
             scopes = this.dedupByProjection(scopes, query);
         scopes = sliceBound(scopes, bound);
-        return this.shape(query.consumer, scopes, query);
+        return this.shape(query.consumer, scopes, query, false);
+    }
+    // The seeds of a walk with their identities: the body's `$key: expr` item,
+    // read in each seed's scope, else the host's identity (SEMANTICS §20).
+    keyed(rows, proj, parent) {
+        const item = keyItem(proj);
+        return rows.map((row) => ({ row, key: item ? this.evalExpr(item.expr, this.enter(row, parent)) : this.hostIdentity(row) }));
     }
     // Dedup scopes by their PROJECTED value (`distinct`): keep the first scope per
     // distinct projection, preserving order. An empty projection dedups by row
@@ -165,7 +241,7 @@ export class InMemoryEngine {
         const out = [];
         for (const s of scopes) {
             const key = proj.select.length === 0
-                ? `i:${canonicalKey(this.ctx.identity(s.row))}`
+                ? `i:${canonicalKey(this.scopeIdentity(s))}`
                 : `p:${canonicalKey(this.projectRow(proj, s))}`;
             if (seen.has(key))
                 continue;
@@ -175,81 +251,102 @@ export class InMemoryEngine {
         return out;
     }
     // A bounded, per-path recursive walk. Each occurrence carries recursion
-    // metadata: `$depth` (seed = 1), a categorical `$stop`, and a deterministic
-    // `$ordinal`. Semantics:
+    // metadata: `$depth` (seed = 1), a categorical `$stop`, a deterministic
+    // `$ordinal`, and `$key`, the identity it is known by. Semantics (SEMANTICS §20):
     //   • per-path — a node reached by N distinct paths yields N occurrences
     //     (unless `distinct`, which keeps the minimal (depth, path) per identity);
-    //   • cycles are safe — revisiting a key already on the current path admits ONE
-    //     occurrence with `$stop == "cycle"` and does not expand it (no runaway);
+    //   • cycles are safe — revisiting an identity already on the current path
+    //     admits ONE occurrence with `$stop == "cycle"` and does not expand it;
     //   • `$stop` ∈ interior | leaf | frontier | depth | cycle, with precedence
     //     cycle > frontier > depth > leaf > interior; only `interior` rows expand;
     //   • `$leaf` = (stop == leaf); `$frontier` = (stop ∈ {frontier, depth}) — the
     //     "there is unfollowed graph beyond me" signal;
-    //   • identity for cycle detection + `distinct` is `by <expr>` when given, else
-    //     `ctx.identity(row)` (an entry's identity is its value's); identities are
-    //     compared structurally via `canonicalKey`, and `$ordinal` paths compare
-    //     component-wise (`comparePath`), so `10` follows `9`;
+    //   • identity is `$key` (since 0.20): a seed's is the body's `$key:` item or
+    //     the host's identity; a successor's is its destination block's `$key:`
+    //     item, else the host's identity of the yielded row. Identities compare
+    //     structurally (`canonicalKey`); `$ordinal` paths compare component-wise
+    //     (`comparePath`), so `10` follows `9`;
     //   • a row's successors are the destinations' rows in source order — a plain
     //     relation read in the row's scope, a destination block evaluated as a
     //     select-position directive in that scope (so `^` inside it is the frontier
-    //     row and its `^people` receiver resolves one scope further out) — filtered
-    //     by the follow `where`, then unioned by identity within the step (a
-    //     recurring identity is kept once, at its first position);
-    //   • the follow `where` reads the candidate's scope hung off the FRONTIER
-    //     row's scope: a bare name is the candidate's, `^name` the row being
-    //     expanded, `^^name` the walk's enclosing scope. `frontier` and `by` read
-    //     the occurrence's own scope with `^` the enclosing scope, as the body does.
-    followWalk(seedRows, follow, parent) {
-        const cap = follow.depth ?? HARD_DEPTH_CAP;
-        const scopeFor = (row) => this.enter(row, parent);
-        const identityOf = (row) => follow.by ? this.evalExpr(follow.by, scopeFor(row)) : this.ctx.identity(isEntry(row) ? row.value : row);
-        const succOf = (row) => {
-            const rowScope = scopeFor(row);
+    //     row and its `^people` receiver resolves one scope further out), shaped by
+    //     the block's items other than `$key` — then unioned by identity within
+    //     the step (a recurring identity is kept once, at its first position, and
+    //     the destination that reached it first governs the occurrence);
+    //   • a destination block's `depth n` (0.20) makes it decline to expand a
+    //     frontier row whose `$depth >= n`; a row with no successors some
+    //     destination declined is `depth`, with none declined `leaf`; the hard
+    //     cap 8 is every destination's ceiling;
+    //   • a destination block's `frontier P` marks the occurrences IT reached for
+    //     which `P` holds (seeds are reached by none); `P` reads the occurrence's
+    //     own scope with `^` the walk's enclosing scope, as the body does;
+    //   • the body's own `frontier P` (`seedFrontier`, 0.20) marks the SEEDS for
+    //     which `P` holds, read in the seed's scope exactly like the body's `where`.
+    followWalk(seeds, follow, seedFrontier, parent) {
+        const frontierScope = (k) => this.enter(k.row, parent, { meta: { [KEY]: k.key } });
+        const succOf = (k, depth) => {
+            const rowScope = frontierScope(k);
             const raw = [];
-            for (const dest of follow.destinations) {
-                const v = dest.kind === "op" ? this.evalCollectValue(dest, rowScope) : this.evalRaw(dest, rowScope);
-                raw.push(...this.rowsOf(v));
-            }
-            const kept = follow.where ? raw.filter((x) => truthy(this.evalExpr(follow.where, this.enter(x, rowScope)))) : raw;
+            let declined = false;
+            follow.destinations.forEach((dest, via) => {
+                if (dest.kind === "op") {
+                    if (dest.sub.depth !== null && depth >= dest.sub.depth) {
+                        declined = true;
+                        return;
+                    }
+                    for (const x of this.destinationRows(dest, rowScope))
+                        raw.push({ ...x, via });
+                }
+                else {
+                    for (const row of this.rowsOf(this.evalRaw(dest, rowScope), dest))
+                        raw.push({ row, key: this.hostIdentity(row), via });
+                }
+            });
             const seen = new Set();
-            const out = [];
-            for (const x of kept) {
-                const key = canonicalKey(identityOf(x));
+            const succ = [];
+            for (const x of raw) {
+                const key = canonicalKey(x.key);
                 if (seen.has(key))
                     continue;
                 seen.add(key);
-                out.push(x);
+                succ.push(x);
             }
-            return out;
+            return { succ, declined };
+        };
+        const frontierHit = (k, via) => {
+            if (via === null)
+                return seedFrontier !== null && truthy(this.evalExpr(seedFrontier, frontierScope(k)));
+            const dest = follow.destinations[via];
+            if (dest.kind !== "op" || !dest.sub.frontier)
+                return false;
+            return truthy(this.evalExpr(dest.sub.frontier, frontierScope(k)));
         };
-        const frontierHit = (row) => follow.frontier ? truthy(this.evalExpr(follow.frontier, scopeFor(row))) : false;
         const walked = [];
-        const visit = (row, depth, ancestors, ancestorIds) => {
-            const id = identityOf(row);
-            const key = canonicalKey(id);
-            const path = [...ancestorIds, id];
+        const visit = (k, via, depth, ancestors, ancestorIds) => {
+            const key = canonicalKey(k.key);
+            const path = [...ancestorIds, k.key];
             let stop;
             if (ancestors.includes(key))
                 stop = "cycle";
-            else if (frontierHit(row))
+            else if (frontierHit(k, via))
                 stop = "frontier";
-            else if (depth >= cap)
+            else if (depth >= HARD_DEPTH_CAP)
                 stop = "depth";
             else {
-                const succ = succOf(row);
+                const { succ, declined } = succOf(k, depth);
                 if (succ.length === 0)
-                    stop = "leaf";
+                    stop = declined ? "depth" : "leaf";
                 else {
-                    walked.push({ row, depth, path, key, stop: "interior" });
-                    for (const s of succ)
-                        visit(s, depth + 1, [...ancestors, key], path);
+                    walked.push({ row: k.row, depth, path, id: k.key, key, stop: "interior" });
+                    for (const x of succ)
+                        visit(x, x.via, depth + 1, [...ancestors, key], path);
                     return;
                 }
             }
-            walked.push({ row, depth, path, key, stop });
+            walked.push({ row: k.row, depth, path, id: k.key, key, stop });
         };
-        for (const r of seedRows)
-            visit(r, 1, [], []);
+        for (const k of seeds)
+            visit(k, null, 1, [], []);
         let rows = walked;
         if (follow.distinct) {
             // keep the minimal (depth, path) occurrence per identity key.
@@ -266,6 +363,7 @@ export class InMemoryEngine {
         return rows.map((w, i) => ({
             row: w.row,
             meta: {
+                [KEY]: w.id,
                 $depth: w.depth,
                 $stop: w.stop,
                 $leaf: w.stop === "leaf",
@@ -274,13 +372,30 @@ export class InMemoryEngine {
             },
         }));
     }
+    // A destination block's successors for one frontier row, each with its
+    // identity: the block's rows (its `where`, order, `distinct`, bound and
+    // consumer applied — `first`/`single` yield at most one), shaped by its items
+    // other than `$key` (the raw rows when none remain), keyed by its `$key:`
+    // item read in the row's scope, else by the host's identity of the row yielded.
+    destinationRows(dest, rowScope) {
+        const { scopes } = this.evalCollectScopes(dest, rowScope, this.planOf(dest, rowScope), true);
+        const key = keyItem(dest.sub);
+        const shape = key ? { select: dest.sub.select.filter((it) => it !== key), values: dest.sub.values } : dest.sub;
+        return scopes.map((s) => {
+            const row = this.projectRow(shape, s);
+            const id = key ? this.evalExpr(key.expr, s) : shape.select.length === 0 ? this.scopeIdentity(s) : this.hostIdentity(row);
+            return { row, key: id };
+        });
+    }
     // ---- consumer shaping -----------------------------------------------------
-    shape(consumer, scopes, proj) {
+    // `single` — the receiver was one object: a `collect` yields its one record
+    // (or nothing) rather than a one-element list (SEMANTICS §3, §15).
+    shape(consumer, scopes, proj, single) {
         switch (consumer) {
             case "exists": return { consumer, exists: scopes.length > 0 };
             case "none": return { consumer, none: scopes.length === 0 };
             case "count": return { consumer, count: scopes.length };
-            case "collect": return { consumer, rows: scopes.map((s) => this.projectRow(proj, s)) };
+            case "collect": return { consumer, rows: scopes.map((s) => this.projectRow(proj, s)), single };
             case "first": return { consumer, row: scopes.length > 0 ? this.projectRow(proj, scopes[0]) : null };
             case "single":
                 if (scopes.length > 1)
@@ -370,6 +485,7 @@ export class InMemoryEngine {
     // The rows a consumer op reduces: matched → ordered → distinct → bounded.
     opRows(op, scope, bound, acc) {
         let scopes = this.matchRows(op, scope, acc);
+        this.applyKey(scopes, op.sub);
         this.sortScopes(scopes, op.sub.orderBy);
         if (op.distinct)
             scopes = this.dedupByProjection(scopes, op.sub);
@@ -434,7 +550,7 @@ export class InMemoryEngine {
             if (plan.receiverStable)
                 run.stableCollections.set(op, (state = newCollection(value)));
             else if (plan.correlated.length === 0)
-                return this.scan(this.rowsOf(value), op, scope);
+                return this.scan(this.coerceRows(value, op.receiver), op, scope);
             else if (value !== null && typeof value === "object") {
                 state = run.collections.get(value);
                 if (!state)
@@ -442,7 +558,7 @@ export class InMemoryEngine {
             }
             else {
                 run.trace?.({ kind: "fallback", reason: "not-a-collection" });
-                return this.scan(this.rowsOf(value), op, scope);
+                return this.scan(this.coerceRows(value, op.receiver), op, scope);
             }
         }
         state.seen++;
@@ -451,26 +567,27 @@ export class InMemoryEngine {
             if (direct)
                 return direct;
             if (state.seen >= 2 || plan.receiverStable) {
-                const probed = this.probe(plan, state, scope);
+                const probed = this.probe(plan, state, scope, op);
                 if (probed)
-                    return { rows: probed, where: plan.residual };
+                    return { rows: probed, where: plan.residual, single: false };
             }
             else
                 run.trace?.({ kind: "fallback", reason: "unstable" });
         }
-        return this.scan(this.materialize(state), op, scope);
+        return this.scan(this.materialize(state, op), op, scope);
     }
     // The plain scan: the rows, re-projected by `from`, with the whole `where`.
-    scan(rows, op, scope) {
-        return { rows: this.reproject(rows, op.sub.from, scope), where: op.sub.where };
+    // A `from` re-projection fans a single receiver out: the block is plural.
+    scan(src, op, scope) {
+        return { rows: this.reproject(src.rows, op.sub.from, scope), where: op.sub.where, single: src.single && op.sub.from.length === 0 };
     }
     reproject(rows, from, scope) {
         for (const proj of from)
-            rows = rows.flatMap((r) => this.rowsOf(this.evalRaw(proj, this.child(r, scope))));
+            rows = rows.flatMap((r) => this.rowsOf(this.evalRaw(proj, this.child(r, scope)), proj));
         return rows;
     }
-    materialize(state) {
-        return (state.rows ??= this.rowsOf(state.value));
+    materialize(state, op) {
+        return (state.rows ??= this.coerceRows(state.value, op.receiver));
     }
     // A probe answered by a context index that yields rows directly, before the
     // collection is materialized: one correlation is probed (`lookupOrder`) and
@@ -485,19 +602,19 @@ export class InMemoryEngine {
                 return null;
             const rows = Array.from(index.lookupRows(outer.value));
             scope.run.trace?.({ kind: "lookup", path: c.path, candidates: rows.length });
-            return { rows, where: residualWithout(plan, c) };
+            return { rows, where: residualWithout(plan, c), single: false };
         }
         return null;
     }
     // The engine's probe: one bucket per correlation, intersected smallest-first;
     // the candidates come back in receiver order. `null` (an index that could
     // not be built, an outer value whose evaluation threw) leaves the scan in charge.
-    probe(plan, state, scope) {
+    probe(plan, state, scope, op) {
         const run = scope.run;
-        const rows = this.materialize(state);
+        const rows = this.materialize(state, op).rows;
         const buckets = [];
         for (const c of plan.correlated) {
-            const index = this.indexFor(state, c, scope);
+            const index = this.indexFor(state, c, scope, op);
             if (!index) {
                 run.trace?.({ kind: "fallback", reason: "index" });
                 return null;
@@ -538,12 +655,12 @@ export class InMemoryEngine {
     // here by evaluating the local expression in each row's scope — the same read
     // the scan performs, so the keys are exactly what `==` would compare. A throw
     // while building (a context that rejects a read) leaves the path un-indexed.
-    indexFor(state, c, scope) {
+    indexFor(state, c, scope, op) {
         const key = pathKey(c.path);
         const hit = state.indexes.get(key);
         if (hit !== undefined)
             return hit;
-        const rows = this.materialize(state);
+        const rows = this.materialize(state, op).rows;
         let index = this.contextIndex(state, c);
         let source = "context";
         if (!index) {
@@ -569,30 +686,47 @@ export class InMemoryEngine {
         return this.memoized(op, scope, () => this.evalCollectValuePlanned(op, plan, scope));
     }
     evalCollectValuePlanned(op, plan, scope) {
+        const { scopes, single } = this.evalCollectScopes(op, scope, plan);
+        switch (op.op) {
+            // Over a single receiver (one object) a `collect` is the record or absent,
+            // not a one-element list (SEMANTICS §3).
+            case "collect": return single ? (scopes.length > 0 ? this.projectRow(op.sub, scopes[0]) : undefined) : scopes.map((s) => this.projectRow(op.sub, s));
+            default: return scopes.length > 0 ? this.projectRow(op.sub, scopes[0]) : null;
+        }
+    }
+    // The rows a select-position directive yields, as scopes, reduced by its
+    // consumer (`first`/`single` keep at most one; `single` raises on more), and
+    // whether its receiver was a single object. `destination` marks a follow
+    // destination block: its `frontier` is the destination's (read by the outer
+    // walk), never a seed frontier for a `follow` of its own.
+    evalCollectScopes(op, scope, plan = this.planOf(op, scope), destination = false) {
         const sub = op.sub;
         const bound = this.boundOf(sub, scope);
         let scopes;
+        let single = false;
         if (sub.follow) {
             // The seeds are the matched rows themselves (`followWalk` enters them); a
             // follow block is never correlated, so `where` here is the whole predicate.
             const { rows, where } = this.access(op, plan, scope);
             const seeds = where ? rows.filter((r) => this.evalWhere(where, this.enter(r, scope, { lifts: {} }))) : rows;
-            scopes = this.followWalk(seeds, sub.follow, scope).map((o) => this.enter(o.row, scope, { meta: o.meta }));
+            scopes = this.followWalk(this.keyed(seeds, sub, scope), sub.follow, destination ? null : sub.frontier, scope).map((o) => this.enter(o.row, scope, { meta: o.meta }));
             this.sortScopes(scopes, sub.orderBy);
             if (op.distinct)
                 scopes = this.dedupByProjection(scopes, sub);
             scopes = sliceBound(scopes, bound);
         }
         else {
-            scopes = this.opRows(op, scope, bound, this.access(op, plan, scope));
+            const acc = this.access(op, plan, scope);
+            single = acc.single;
+            scopes = this.opRows(op, scope, bound, acc);
         }
         switch (op.op) {
-            case "collect": return scopes.map((s) => this.projectRow(sub, s));
-            case "first": return scopes.length > 0 ? this.projectRow(sub, scopes[0]) : null;
+            case "collect": return { scopes, single };
+            case "first": return { scopes: scopes.slice(0, 1), single };
             case "single":
                 if (scopes.length > 1)
                     throw new OqxError(`single { … } for '${describeReceiver(op.receiver)}' matched ${scopes.length} rows`, "eval");
-                return scopes.length > 0 ? this.projectRow(sub, scopes[0]) : null;
+                return { scopes, single };
             default: throw new OqxError(`${op.op} { … } is not valid in select position`, "eval");
         }
     }
@@ -656,11 +790,6 @@ export class InMemoryEngine {
                 const r = this.evalExpr(e.recv, scope);
                 return r == null ? undefined : this.ctx.get(r, e.name);
             }
-            case "index": {
-                const r = this.evalExpr(e.recv, scope);
-                const i = this.evalExpr(e.index, scope);
-                return r == null ? undefined : this.ctx.get(r, String(i));
-            }
             case "call": return this.evalCall(e, scope);
             case "unary": {
                 const v = this.evalExpr(e.expr, scope);
@@ -668,9 +797,25 @@ export class InMemoryEngine {
                     return !truthy(v);
                 return v == null ? undefined : -v;
             }
+            // `x!` — the value, or an eval error naming the expression (and the row's
+            // identity when it has a scalar one). Never a filter, never a coercion.
+            case "required": {
+                const v = this.evalExpr(e.expr, scope);
+                if (v == null)
+                    throw new OqxError(`\`${describe(e.expr)}!\` is absent${this.rowIdentity(scope)}`, "eval");
+                return v;
+            }
+            // A value-position directive (`jobs first { … }.pay`, the desugared `x[…]`).
+            case "op": return this.evalCollectValue(e, scope);
             case "binary": {
                 const l = this.evalExpr(e.left, scope);
                 const r = this.evalExpr(e.right, scope);
+                if (e.op === "is" || e.op === "is not") {
+                    // Identity (SEMANTICS §5b): the host's identity of each side,
+                    // compared structurally — the key `distinct` and `follow` use.
+                    const same = canonicalKey(this.hostIdentity(l)) === canonicalKey(this.hostIdentity(r));
+                    return e.op === "is" ? same : !same;
+                }
                 return isRelOp(e.op) ? relate(e.op, l, r) : arith(e.op, l, r);
             }
             case "logical": {
@@ -681,15 +826,37 @@ export class InMemoryEngine {
             }
             case "in": return membership(this.evalExpr(e.left, scope), this.evalExpr(e.right, scope));
             case "range": return makeRange(e.lo == null ? null : this.evalExpr(e.lo, scope), e.hi == null ? null : this.evalExpr(e.hi, scope), e.exclusiveEnd);
+            // A tuple (SEMANTICS §3b): the elements in order, concatenated with ONE
+            // level of flattening — a collection contributes its items, anything else
+            // itself; an absent (`undefined`) element contributes nothing, a `null`
+            // one `null`; duplicates are kept.
+            case "tuple": {
+                const out = [];
+                for (const item of e.items) {
+                    const v = this.evalExpr(item, scope);
+                    if (v === undefined)
+                        continue;
+                    if (Array.isArray(v))
+                        out.push(...v);
+                    else if (v !== null && typeof v === "object" && !isEntry(v) && !isRange(v) && Symbol.iterator in v)
+                        out.push(...v);
+                    else
+                        out.push(v);
+                }
+                return out;
+            }
         }
     }
     // Resolve a name against ONE scope — never its ancestors. A scope provides,
     // in order: `$it` (the scope's row itself — the current item, whatever its
-    // type, so scalar collections are queryable; absent at the root, which has no
-    // row; `$value`, its pre-0.15 spelling, is an ordinary property name now); `$key` (the property key) when it is an entry scope — see `enter`;
-    // the recursion intrinsics (`$depth`, …) when it is a follow occurrence;
-    // values lifted into it by `^name:` items; then either the row's own property
-    // or, for the root scope (no row), the context's named roots.
+    // type, so scalar collections are queryable; at the root the host's root
+    // object, since 0.18; `$value`, its pre-0.15 spelling, is an ordinary
+    // property name now); `$key` (the property key) when it is an entry scope —
+    // see `enter`; the recursion intrinsics (`$depth`, …) when it is a follow
+    // occurrence; values lifted into it by `^name:` items; then either the row's
+    // own property or, for the root scope, the context's named roots (`root(name)`
+    // — never a property of the root object, so a host with lazy roots is
+    // unaffected by what its root object holds).
     //
     // The two metadata steps apply only where the scope CARRIES that metadata
     // (SEMANTICS §2, since 0.13). Anywhere else — `$key` on an ordinary row,
@@ -706,8 +873,11 @@ export class InMemoryEngine {
     // 0, "") need no special case — there is no "absent, so look outward" rule.
     resolveIn(name, scope) {
         if (name === "$it")
-            return scope.parent === null ? undefined : scope.row;
-        if ((name === KEY || RECUR.has(name)) && scope.meta && Object.hasOwn(scope.meta, name))
+            return scope.row;
+        // `$key` is the row's identity on every row (SEMANTICS §16, since 0.20).
+        if (name === KEY)
+            return this.scopeIdentity(scope);
+        if (RECUR.has(name) && scope.meta && Object.hasOwn(scope.meta, name))
             return scope.meta[name];
         if (scope.lifts && Object.hasOwn(scope.lifts, name))
             return scope.lifts[name];
@@ -715,6 +885,15 @@ export class InMemoryEngine {
             return this.ctx.root(name);
         return this.ctx.get(scope.row, name);
     }
+    // ` on <identity>` for a required-value error when the scope's row has a
+    // scalar identity (`$key`: the host's, an entry's key, a `$key:` projection);
+    // empty otherwise, and at the root (the root object is not a row of the data).
+    rowIdentity(scope) {
+        if (scope.parent === null || scope.row == null)
+            return "";
+        const id = this.scopeIdentity(scope);
+        return typeof id === "string" || typeof id === "number" ? ` on ${JSON.stringify(id)}` : "";
+    }
     evalCall(e, scope) {
         const args = e.args.map((a) => this.evalExpr(a, scope));
         if (e.recv === null) {
@@ -800,6 +979,12 @@ function boundedCount(n, b) {
     const rest = Math.max(0, n - b.offset);
     return b.limit == null ? rest : Math.min(rest, b.limit);
 }
+// The canonical text of an expression for an error message; a binding shows as
+// its `${n}` marker (the printer refuses to turn a bound value into source).
+function describe(e) {
+    const t = printTemplate(e);
+    return t.strings.map((s, i) => (i < t.count ? `${s}\${${t.indices[i]}}` : s)).join("");
+}
 function describeReceiver(e) {
     if (e.kind === "ident")
         return e.name;
@@ -820,7 +1005,7 @@ function partitionRecur(w) {
     const post = [];
     for (const p of parts)
         (whereHasRecur(p) ? post : seed).push(p);
-    const rebuild = (ps) => (ps.length === 0 ? null : ps.length === 1 ? ps[0] : { kind: "and", parts: ps });
+    const rebuild = (ps) => (ps.length === 0 ? null : ps.length === 1 ? ps[0] : { kind: "and", span: [0, 0], parts: ps });
     return { seed: rebuild(seed), post: rebuild(post) };
 }
 function whereHasRecur(w) {
@@ -836,19 +1021,15 @@ function exprHasRecur(e) {
     switch (e.kind) {
         case "ident": return RECUR.has(e.name);
         case "member": return exprHasRecur(e.recv);
-        case "index": return exprHasRecur(e.recv) || exprHasRecur(e.index);
         case "call": return (e.recv ? exprHasRecur(e.recv) : false) || e.args.some(exprHasRecur);
-        case "unary": return exprHasRecur(e.expr);
+        case "unary":
+        case "required": return exprHasRecur(e.expr);
         case "binary":
         case "logical":
         case "in": return exprHasRecur(e.left) || exprHasRecur(e.right);
         case "range": return (e.lo != null && exprHasRecur(e.lo)) || (e.hi != null && exprHasRecur(e.hi));
+        case "tuple": return e.items.some(exprHasRecur);
         default: return false;
     }
 }
-/** Convenience: run a query with plain-object roots (the default context). */
-export function runQuery(query, bindings, roots) {
-    const ctx = new DefaultContext(roots ?? {});
-    return new InMemoryEngine(ctx).run(query, bindings);
-}
 //# sourceMappingURL=engine.js.map