@omgbase/oqx 0.9.0 → 0.10.1

package/CHANGELOG.md

@@ -0,0 +1,214 @@
+# Changelog
+
+All notable changes to `@omgbase/oqx` are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
+[Semantic Versioning](https://semver.org/) (pre-1.0: a minor bump may break).
+
+## [0.10.1] - 2026-09-23
+
+Metadata and documentation only; no code changes.
+
+### Added
+- `LICENSE` file (MIT) — `package.json` previously said ISC with no license text.
+- Package metadata: `author`, `repository`, `homepage`, `bugs`, `keywords`,
+  `sideEffects: false`, and a single consistent `description`.
+- This changelog, shipped in the package.
+- GitHub Actions CI (typecheck, test, build on Node 22 and 24).
+- README: an "Exports" reference for every public export, the
+  `DataContext.callFunction` / `callMethod` extension seam (and the
+  "unknown function" pitfall of a context that does not delegate to the
+  builtins), `OqxError` and its `stage` discriminator, an `IndexedCollection`
+  example, `SqliteTableOptions` fields, string-literal escapes, `has(x)` and
+  array `contains`, and a License section.
+
+### Changed
+- `engines.node` is now `>=22.13.0` — the floor at which `node:sqlite` (used
+  only by the `./sqlite` subpath) is available without a flag. The main entry is
+  plain ES2022 ESM and runs on older Node in practice.
+- README "Requirements" states the real floors (see above) and that the package
+  is ESM-only.
+
+### Fixed
+- README referred to `oqx.semantics`; the scalar contract is the named export
+  `semantics`.
+
+## [0.10.0] - 2026-09-22
+
+### Added
+- `entries(x)` builtin: the explicit bridge from a record to a collection of
+  `{ key, value }` entries. Objects yield own enumerable pairs in insertion
+  order, arrays yield `(index, element)`, `Map`s yield their entries; absence,
+  scalars, and ranges yield nothing. A plain object is still **not** iterable —
+  `from ${obj}` is one row.
+- `$key` intrinsic: inside an entry scope, the entry's key. The scope's row is
+  the property's *value*, so `$value` and bare names read the value.
+  `$key` exists only in entry scopes — an array element has no implicit index.
+- A free-function call may be a consumer receiver
+  (`entries(prefs) exists { … }`) and may be navigated further.
+- `semantics`: `makeEntry`, `isEntry`, `entriesOf` (the entry tag is a
+  non-enumerable symbol, so `entries(x)` as a plain value reads as an array of
+  `{ key, value }` records).
+
+### Changed
+- Engine: one `enter(row, parent, extra)` now creates every scope (top level,
+  nested blocks, `from` re-projections, follow seeds/occurrences, fast paths).
+
+## [0.9.0] - 2026-09-21
+
+### Added
+- `none { … }` consumer — true iff the block yields zero rows; the explicit
+  complement of `exists`, and how universal quantification is spelled
+  (`members none { where !active }`). Works in `where` position and as a
+  whole-query directive (`{ consumer: "none", none }`). Not comparable and not a
+  projection.
+- `limit N` / `offset N` — bound the row set **after** `where` / `order by` /
+  `distinct` and **before** the consumer reduces it, at the top level and in any
+  block. `N` is a literal, a `${…}` binding, or an outer reference (`limit ^n`);
+  it must be a non-negative integer (eval error otherwise). `limit`/`offset` are
+  clause words only when followed by a number, binding, or `^`, so a field with
+  that name still reads as a field.
+
+### Changed
+- Engine: `exists` / `none` / `count` fast paths stop at the (offset+1)th match;
+  `first` / `single` caps grow by the offset; consumer ops share one `opRows`
+  pipeline (matched → ordered → distinct → bounded), which also makes
+  `collect distinct { ^x: … }` lifts dedup as documented.
+- SQLite adapter: no SQL `LIMIT` under `first` / `single` when the query carries
+  its own `limit` / `offset` (the residual applies them).
+
+## [0.8.0] - 2026-09-21
+
+### Added
+- `$value` intrinsic — the current scope's own row, whatever its type. Absent at
+  the root scope. Inside a nested block `$value` is the inner item and `^$value`
+  the enclosing row. Never resolved through the `DataContext`.
+- `values` projection mode — after a projection of exactly one item, the row's
+  result is that value rather than a `{ name: value }` record. Works at the top
+  level and inside any `collect` / `first` / `single` block; composes with
+  `distinct` (dedup by the bare value). Cannot be combined with a lift.
+- An unaliased projection item may be any value expression: a bare or dotted
+  navigation keys by its last segment; a call / arithmetic / comparison is legal
+  only under `values`, otherwise a clear "needs an alias" parse error.
+
+### Fixed
+- `{ has(x) }` used to misparse as select `has` + where `(x)`; it is now the
+  alias error above (write `where has(x)`).
+
+## [0.7.0] - 2026-09-19
+
+### Changed
+- **BREAKING:** bare names resolve **locally only**. A bare identifier reads the
+  current row/scope; an absent local name stays absent and never falls through
+  to an enclosing scope. Outer correlation is always the explicit `^name`
+  (exactly one scope out per caret; past the root is absent).
+- **BREAKING:** `DataContext.has` removed — it existed only to stop the scope
+  climb; a computed relation now needs only `get`.
+- A consumer receiver may start with `^` (`^people collect { … }`), since a
+  named root is reachable from inside a row only as `^root`.
+- Planner helpers / SQLite adapter: a bare identifier in a top-level `where` is
+  now unambiguously a column of the scanned rows and is safe to push.
+
+## [0.6.0] - 2026-09-17
+
+### Added
+- `range(s)` builtin: parse a string (`"1..5"`, `"1...5"`, `"..5"`,
+  `"2026-01-01..2026-01-31"`, …) into the range value a `lo..hi` literal
+  produces; a range passes through unchanged; anything else yields an absent
+  range, so `x in range(bad)` is simply false. Bounds must share a scalar domain
+  (numeric or ISO-8601).
+- `semantics.parseRangeString`.
+
+## [0.5.0] - 2026-09-16
+
+### Added
+- Ruby-style range literals: `lo..hi` (inclusive), `lo...hi` (exclusive high
+  end), and open-ended `..hi` / `lo..`. Used mainly as the right side of `in`
+  for interval membership; a range is a general value expression. Bounds
+  compare via the ordering rules, so ranges work over numbers and ISO-8601
+  date/time strings; an absent value is never covered.
+- `semantics`: `makeRange`, `isRange`, `rangeCovers`; a `membership` branch for
+  ranges.
+
+### Fixed
+- Lexer: a decimal point now binds only when a digit follows, so `1..5` no
+  longer mis-lexes as `1.` + `.5`.
+
+## [0.4.0] - 2026-09-16
+
+### Added
+- `distinct` modifier on consumers (top-level and nested): dedup the rows a
+  consumer reduces by their **projected** value, keeping the first per distinct
+  projection in order; an empty projection dedups by row identity. Spelled
+  `<op> distinct { … }` or `select distinct …` inside the block.
+
+### Fixed
+- Parser: `looksLikePredicate` skips nested `{ … }` blocks when scanning for a
+  top-level operator and recognizes a consumer directive
+  (`… exists { }`, `… count distinct { } == N`) as a where-position predicate.
+
+## [0.3.0] - 2026-09-16
+
+### Changed
+- `follow` is now a **per-path** walk: a node reached by N distinct paths yields
+  N occurrences (previously collapsed by global identity dedup).
+- Cycles are admitted **once** as `$stop == "cycle"` and never re-expanded
+  (previously a revisit produced no occurrence).
+- `$stop` categories are `interior | leaf | frontier | depth | cycle`
+  (precedence cycle > frontier > depth > leaf > interior); only `interior` rows
+  expand. The old `"continue"` is renamed `"interior"`.
+- `$frontier` covers both frontier and depth cutoffs; `$leaf` stays "no
+  successors".
+
+### Added
+- `$ordinal` intrinsic: a deterministic 1..N rank over `(depth, path)`.
+
+### Fixed
+- `follow distinct` now works: collapse occurrences to the minimal
+  `(depth, path)` per identity (`by` key, else `ctx.identity`).
+
+## [0.2.0] - 2026-09-16
+
+### Changed
+- Ship a compiled `dist/` (JS + `.d.ts` + source maps) instead of raw `.ts`.
+  0.1.0 pointed `main` / `types` / `exports` at `src/*.ts`, which `tsc` rejects
+  under `module: NodeNext` and Node refuses to type-strip under `node_modules`.
+- Added `tsconfig.build.json` (`rewriteRelativeImportExtensions`) and
+  `scripts/fix-dts-extensions.mjs` to rewrite `.ts` specifiers left in emitted
+  declarations; `build`, `clean`, and `prepublishOnly` scripts.
+
+### Fixed
+- `order by <expr> desc` hoisted rows missing the sort key to the top. Absent
+  now sorts last regardless of direction.
+
+## [0.1.0] - 2026-09-14
+
+First public release as `@omgbase/oqx`.
+
+### Added
+- The OQX language kernel: lexer, parser, AST; the `oqx` tagged template with
+  typed value bindings (prepared-statement semantics); `parse`, `execute`, `run`.
+- Projection (optional `select`, aliases, dotted navigation), `where` predicates,
+  `order by`, consumers `collect` / `exists` / `count` / `first` / `single`,
+  nested consumer directives over relations, lifts (`^name:`) including
+  multi-level `^^` / `^^^` with flatten-append accumulation, `^name` outer
+  references, and bounded recursion with `follow` and its intrinsics.
+- `semantics.ts` — the normative scalar contract every backend must obey
+  (typed/strict equality, absent-operand comparisons false, CEL-style `in`,
+  absent-last sort), backed by a conformance suite.
+- `DataContext` / `DefaultContext` (tier 2), `Engine` / `InMemoryEngine`,
+  `QueryPlanner` / `Plan` / `PlannedEngine` (tier 3) with the pushdown helpers
+  in `plan.ts`, and two adapters: `IndexedCollection` (hash-index probe) and
+  `@omgbase/oqx/sqlite` (`SqliteTable`, real OQX→SQL pushdown over
+  `node:sqlite`).
+
+[0.10.1]: https://github.com/omgbase/oqx/compare/v0.10.0...HEAD
+[0.10.0]: https://github.com/omgbase/oqx/compare/v0.9.0...v0.10.0
+[0.9.0]: https://github.com/omgbase/oqx/compare/v0.8.0...v0.9.0
+[0.8.0]: https://github.com/omgbase/oqx/compare/v0.7.0...v0.8.0
+[0.7.0]: https://github.com/omgbase/oqx/compare/v0.6.0...v0.7.0
+[0.6.0]: https://github.com/omgbase/oqx/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/omgbase/oqx/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/omgbase/oqx/commits/v0.4.0
+[0.3.0]: https://github.com/omgbase/oqx/commit/aca739b
+[0.2.0]: https://github.com/omgbase/oqx/commit/82fb99e
+[0.1.0]: https://github.com/omgbase/oqx/commit/4552bb5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brendan Baldwin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -143,9 +143,32 @@ oqx`employee: $value from ${people} where name == "Bob"`;         // [{ employee
 ```
 
 Inside a nested block `$value` is the inner item; the enclosing row is `^$value`
-(§3). At the root scope (before any row) it is absent. Plain objects are **not**
-iterable through `$value` — a record stays a record; converting one to a
-collection of entries is a separate, explicit step (`entries()`, planned).
+(§3). At the root scope (before any row) it is absent.
+
+**`entries(x)` and `$key` — records to collections, explicitly.** A plain object
+is **not** iterable: `from ${obj}` is one row (the object). `entries(obj)`
+converts it into a collection of entries, and inside such a scope the current
+item is the property's **value** — `$value` and bare names read it — while
+**`$key`** is the property's key:
+
+```js
+const settings = { theme: "dark", fontSize: 14, autosave: true };
+oqx`key: $key, value: $value from entries(${settings})`;
+// [{ key: "theme", value: "dark" }, { key: "fontSize", value: 14 }, { key: "autosave", value: true }]
+oqx`$key values from entries(${settings}) where $value != "dark"`;   // ["fontSize", "autosave"]
+
+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 $value } from ${users}`;   // as a nested receiver
+oqx`name from ${users} where entries(prefs) exists { where $key == "dark" && $value }`;
+```
+
+`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
+ask for one. As a plain value (not a source) `entries(x)` is an array of
+`{ key, value }` records.
 
 ### 3. Predicates (where)
 
@@ -164,6 +187,14 @@ oqx`name from ${people} where !active`;            // → Carol
 Equality is **typed and strict** (`5 == "5"` is false); a comparison against an
 absent (`null`/`undefined`) field is simply false rather than an error.
 
+**String literals** may be double- or single-quoted (`"NYC"` / `'NYC'`) and
+support backslash escapes: `\n`, `\t`, `\r`, `\0`, and `\<any other char>`
+for that character itself (`\"`, `\'`, `\\`). An unterminated string is a lex
+error. Note that inside the `oqx` tagged template JavaScript resolves its own
+escapes first (the template's cooked strings are what OQX lexes), so `\\n` in
+your source reaches OQX as `\n`. Usually you don't need any of this —
+interpolate the host value instead (`where name == ${name}`).
+
 **Ranges.** A Ruby-style range `lo..hi` (inclusive) or `lo...hi` (exclusive high
 end) is a value, used most often as the right side of `in`. Either bound may be
 omitted for an open-ended range (`..hi`, `lo..`). Bounds compare with the same
@@ -257,13 +288,28 @@ like a row property.
 
 Methods on a value: `contains`, `startsWith`, `endsWith`, `matches` (regex),
 `size`, `lower`, `upper`. Free functions: `list(x)` (coerce to an array), `size(x)`,
-`has(x)`.
+`has(x)`, `range(s)` (§3), `entries(x)` (§2).
 
 ```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 tags.contains("admin")`;       // array membership
 ```
 
+- `has(x)` is true when `x` is **present** — anything other than `null` /
+  `undefined`. `has(0)`, `has("")`, and `has(false)` are all true; use bare
+  truthiness (`where active`) when you mean truthy.
+- `.contains(v)` works on strings (substring) **and arrays** (an element equal
+  to `v` under OQX's strict equality); on anything else it is false.
+- `.size()` / `size(x)` is the length of a string or array, the key count of
+  an object, and 0 for absent; `.matches(re)` compiles its argument as a
+  JavaScript `RegExp`.
+
+Anything not in these tables is an **eval error** (`unknown function 'f(…)'` /
+`unknown method '.m(…)'`) — see [custom functions](#custom-functions-and-methods)
+for adding your own.
+
 ### 5. Consumers
 
 A consumer shapes a result set. There are six:
@@ -467,10 +513,12 @@ where x in lo..hi / lo...hi / ..hi / lo..        range membership (incl. / excl.
 where x in range(field)                          coerce a string field to a range, then test coverage
 name                                             the CURRENT row's field only (never climbs)
 $value                                           the current item itself (a scalar row, or the whole object)
+from entries(obj) … $key / $value                a record's properties as a collection (key + value; bare names read the value)
 <expr> values                                    scalar projection: the value, not a { name: value } record
 ^name / ^^name                                   read an enclosing row's field (exactly N scopes out); ^$value = the enclosing row
 ^name: expr  /  ^^name: expr                     lift/export a value N scopes out (flatten-append)
 ^rel collect { … }  /  ^^root exists { … }       nested consumer over an enclosing row's relation / a named root
+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)
@@ -503,7 +551,7 @@ Query AST  ─┬─ InMemoryEngine(DataContext)     tier 1/2 — drive any data
                    └─ finishes the residual on the in-memory engine
 ```
 
-**Everything obeys one scalar-semantics contract** (`oqx.semantics`): typed/strict
+**Everything obeys one scalar-semantics contract** (the `semantics` export): typed/strict
 equality (`5 == "5"` is false), absent operands make ordering comparisons false,
 CEL-style `in`, absent-last sort order. Any backend that can't reproduce a rule
 in its native language must leave that fragment as an in-memory *residual* rather
@@ -531,6 +579,41 @@ const graph = {
 run(parse("id, depth: $depth from tree follow children"), { context: graph });
 ```
 
+#### Custom functions and methods
+
+`DataContext` has two optional hooks, `callFunction(name, args)` for free
+functions (`f(x)`) and `callMethod(name, recv, args)` for methods (`x.m()`).
+Each returns a `CallResult`: `{ handled: true, value }` to answer, or
+`{ handled: false }` to decline. **The engine does not consult the builtin
+table itself** — `DefaultContext` is what does that. So a context that omits
+these hooks, or handles only its own names without deferring, loses
+`entries()`, `size()`, `has()`, `range()`, `.contains()`, and the rest: the
+engine throws `OqxError("unknown function 'size(…)'", "eval")`. (The `graph`
+context above has exactly this limitation.) Delegate whatever you don't
+recognize:
+
+```js
+import { DefaultContext, parse, run } from "@omgbase/oqx";
+
+const builtins = new DefaultContext();          // or: semantics.BUILTIN_FUNCTIONS[name]
+const ctx = {
+  ...graph,
+  callFunction(name, args) {
+    if (name === "age") return { handled: true, value: yearsSince(args[0]) };
+    return builtins.callFunction(name, args);   // entries/size/has/range keep working
+  },
+  callMethod(name, recv, args) {
+    if (name === "slug") return { handled: true, value: slugify(recv) };
+    return builtins.callMethod(name, recv, args);
+  },
+};
+run(parse("id from tree where age(born) > 18 && title.slug() == 'x'"), { context: ctx });
+```
+
+The simplest route is to `extends DefaultContext` and `super.callFunction(...)`
+in the fallthrough. Custom calls are never pushed down by the shipped planners;
+they always run in the residual.
+
 ### Tier 3 — a `QueryPlanner` (pushdown + planning)
 
 A planner translates as much of a query as it can into its store's native query
@@ -559,11 +642,130 @@ blocks/nodes, the relations table, `$` intrinsics, `WITH RECURSIVE` for `follow`
 becomes a `QueryPlanner`, while oqx contributes the parser, IR, semantics
 contract, and residual executor.
 
+## Exports
+
+Everything below is exported from `@omgbase/oqx` (`src/index.ts`); the SQLite
+adapter lives on the `@omgbase/oqx/sqlite` subpath.
+
+**Running queries**
+
+- `oqx` (default export **and** named) — the tagged template. Returns the
+  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).
+- `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`.
+  `opts.values` are the positional `${…}` bindings; then exactly one of
+  `opts.engine` (any `Engine`, e.g. a `PlannedEngine`), `opts.context` (a
+  `DataContext`, run on the in-memory engine), or `opts.roots` (plain-object
+  named roots → `DefaultContext`). Default: an empty `DefaultContext`.
+- `runQuery(query, values, roots)` — the lower-level call `oqx` / `execute` use:
+  in-memory over a `DefaultContext(roots)` (`roots` may be `undefined`).
+- `OqxResult` — the discriminated result `run` returns:
+
+  ```ts
+  type OqxResult =
+    | { consumer: "collect"; rows: unknown[] }
+    | { consumer: "exists";  exists: boolean }
+    | { consumer: "none";    none: boolean }
+    | { consumer: "count";   count: number }
+    | { consumer: "first";   row: unknown | null }
+    | { consumer: "single";  row: unknown | null };
+  ```
+
+**Errors**
+
+- `OqxError` — the one error class for every failure. `error.stage` is
+  `"lex" | "parse" | "eval"` so you can branch without matching messages;
+  `error.message` carries the detail (position for lex/parse errors, the
+  offending name or count for eval errors). Eval errors include: unknown
+  function/method, a non-integer or negative `limit` / `offset`, and
+  `single { … }` matching **more than one** row (zero rows is `null`, not an
+  error — use `first` when zero-or-one is expected and you don't care to assert).
+
+**Engines and contexts**
+
+- `Engine` — `{ run(query, bindings): OqxResult }`; what `run({ engine })` accepts.
+- `InMemoryEngine` — `new InMemoryEngine(context?)`; the reference engine over a
+  `DataContext` (tier 1/2).
+- `DataContext` — the tier-2 interface: `root`, `get`, `toRows`, `identity`,
+  plus optional `callFunction` / `callMethod` (above).
+- `CallResult` — `{ handled: boolean; value?: unknown }`, returned by those hooks.
+- `DefaultContext` — `new DefaultContext(roots?)`; plain-object access, `.id`
+  identity, and the builtin function/method tables.
+- `semantics` — the scalar-contract module (`equals`, `relate`, `arith`,
+  `membership`, `truthy`, `compareForSort`, `sizeOf`, `toList`,
+  `coerceCollection`, ranges: `makeRange` / `isRange` / `rangeCovers` /
+  `parseRangeString`, entries: `makeEntry` / `isEntry` / `entriesOf`, and the
+  `BUILTIN_FUNCTIONS` / `BUILTIN_METHODS` tables). A backend reproducing a rule
+  natively must match these.
+
+**Planning (tier 3)**
+
+- `QueryPlanner` — `{ plan(query, params): Plan | null }`. Return `null` to
+  decline a query entirely (full in-memory fallback).
+- `Plan` — `{ rows(): Iterable; residual: Query; context?: DataContext }`: the
+  rows the store produced, the query to finish over them, and optionally a
+  context for navigating those rows' relations.
+- `PlannedEngine` — `new PlannedEngine(planner, fallbackContext?)`; an `Engine`
+  that runs the planner and finishes `plan.residual` on the in-memory engine
+  over `plan.rows()` (exposed as the `ROWS_ROOT` root).
+- Planner helpers, used together inside `plan()`: `partitionPushable(where,
+  canPush)` splits the top-level `where` conjunction into `pushed` expressions
+  (those your `canPush` accepts) and a `residual` where-tree; `asEquality(expr)`
+  recognizes `field == const` (either order) as `{ field, value }`;
+  `isConst(expr)` / `constValue(expr, params)` tell a literal-or-binding from a
+  row-dependent expression and evaluate it against the query bindings; and
+  `residualQuery(query, residualWhere)` rebuilds the query to scan `ROWS_ROOT`
+  with the pushed predicates dropped and projection / order / consumer / bounds
+  intact. A planner typically: checks `query.source` names its table (and
+  declines `from` / `follow`), partitions the `where`, translates `pushed` into
+  its native query using `constValue` for parameters, then returns
+  `{ rows, residual: residualQuery(query, residual) }`.
+- `IndexedCollection` — `new IndexedCollection(rootName, rows, indexFields)`; a
+  `QueryPlanner` that hash-indexes `rows` on `indexFields` and answers
+  `field == value` predicates on them from the index, leaving the rest residual:
+
+  ```js
+  import { parse, run, IndexedCollection, PlannedEngine } from "@omgbase/oqx";
+  const planner = new IndexedCollection("people", people, ["city", "title"]);
+  const engine = new PlannedEngine(planner);
+  run(parse('name from people where city == "NYC" && age > 30'), { engine });
+  // city probe from the index; `age > 30` finished in-memory over the candidates
+  ```
+
+- `SqliteTable` (from `@omgbase/oqx/sqlite`) —
+  `new SqliteTable(db, tableName, options)` over a `node:sqlite` `DatabaseSync`.
+  `SqliteTableOptions`:
+  - `columns: string[]` — the columns that map to bare OQX fields; only these
+    are pushable (any other identifier stays residual).
+  - `jsonColumns?: string[]` — columns whose stored text is `JSON.parse`d back
+    into the row (for nested relations kept as JSON).
+  - `map?: (raw) => row` — a custom raw-SQL-row → query-row mapper (overrides
+    `jsonColumns`).
+
+**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.
+
 ## Requirements
 
-Node 22.6+ (the sources are TypeScript, run natively via type-stripping — the
-package has **no runtime dependencies**). `npm test` runs the suite; `npm run
-typecheck` typechecks.
+No runtime dependencies. The package is **ESM-only** (there is no `require`
+condition in `exports`; Node 22.12+ can `require()` an ES module natively).
+
+- **Main entry** (`@omgbase/oqx`): compiled ES2022 ESM. `engines.node` says
+  `>=22.13.0`, but nothing in the main entry needs it — Node 18+ works in
+  practice.
+- **`@omgbase/oqx/sqlite`**: imports `node:sqlite`, which is available without
+  a flag from Node 22.13 (behind `--experimental-sqlite` in 22.5–22.12). This is
+  the reason for the `engines` floor.
+- **Developing the repo**: `npm test` runs the `.ts` suite directly through
+  Node's type stripping, unflagged from Node 22.18 (and all of 24). `npm run
+  typecheck` typechecks; `npm run build` emits `dist/`.
 
 ## Relationship to omgbase
 
@@ -571,3 +773,7 @@ This is tier 1 (the in-memory object/collection interpreter) of the OQX
 implementation tiers. The language kernel here is host-agnostic; richer hosts
 (e.g. omgbase's docs/blocks/nodes with index pushdown) layer data-model
 vocabulary and execution capabilities on top of the same surface syntax.
+
+## License
+
+[MIT](./LICENSE). Release history is in the [CHANGELOG](./CHANGELOG.md).

package/dist/engine.d.ts

@@ -32,6 +32,7 @@ export declare class InMemoryEngine implements Engine {
     private matches;
     private rowsOf;
     private child;
+    private enter;
     private runFollow;
     private dedupByProjection;
     private followWalk;

package/dist/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EACV,KAAK,EACN,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAOhD,yEAAyE;AACzE,MAAM,MAAM,SAAS,GACjB;IAAE,QAAQ,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,OAAO,EAAE,CAAA;CAAE,GACxC;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GACvC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GACnC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAAA;CAAE,GAC1C;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAAA;CAAE,CAAC;AAEhD,6EAA6E;AAC7E,MAAM,WAAW,MAAM;IACrB,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,SAAS,CAAC;CAC5D;AA0BD,qBAAa,cAAe,YAAW,MAAM;IAC3C,OAAO,CAAC,GAAG,CAAc;gBAEb,OAAO,GAAE,WAAkC;IAIvD,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,GAAE,SAAS,OAAO,EAAO,GAAG,SAAS;IAmD/D,OAAO,CAAC,OAAO;IAef,OAAO,CAAC,OAAO;IAKf,OAAO,CAAC,MAAM;IAId,OAAO,CAAC,KAAK;IAMb,OAAO,CAAC,SAAS;IAejB,OAAO,CAAC,iBAAiB;IA2BzB,OAAO,CAAC,UAAU;IA6DlB,OAAO,CAAC,KAAK;IAeb,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,SAAS;IAcjB,OAAO,CAAC,WAAW;IAiCnB,OAAO,CAAC,MAAM;IAQd,OAAO,CAAC,QAAQ;IAKhB,OAAO,CAAE,aAAa;IAStB,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,gBAAgB;IA2BxB,OAAO,CAAC,UAAU;IAwBlB,OAAO,CAAC,QAAQ;IAuDhB,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,QAAQ;CAYjB;AAyFD,8EAA8E;AAC9E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,GAAG,SAAS,CAG9F"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EACV,KAAK,EACN,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAOhD,yEAAyE;AACzE,MAAM,MAAM,SAAS,GACjB;IAAE,QAAQ,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,OAAO,EAAE,CAAA;CAAE,GACxC;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GACvC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GACnC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAAA;CAAE,GAC1C;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAAA;CAAE,CAAC;AAEhD,6EAA6E;AAC7E,MAAM,WAAW,MAAM;IACrB,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,SAAS,CAAC;CAC5D;AA4BD,qBAAa,cAAe,YAAW,MAAM;IAC3C,OAAO,CAAC,GAAG,CAAc;gBAEb,OAAO,GAAE,WAAkC;IAIvD,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,GAAE,SAAS,OAAO,EAAO,GAAG,SAAS;IAmD/D,OAAO,CAAC,OAAO;IAef,OAAO,CAAC,OAAO;IAKf,OAAO,CAAC,MAAM;IAId,OAAO,CAAC,KAAK;IASb,OAAO,CAAC,KAAK;IAab,OAAO,CAAC,SAAS;IAejB,OAAO,CAAC,iBAAiB;IA2BzB,OAAO,CAAC,UAAU;IA6DlB,OAAO,CAAC,KAAK;IAeb,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,SAAS;IAcjB,OAAO,CAAC,WAAW;IAiCnB,OAAO,CAAC,MAAM;IAQd,OAAO,CAAC,QAAQ;IAKhB,OAAO,CAAE,aAAa;IAStB,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,gBAAgB;IA2BxB,OAAO,CAAC,UAAU;IAwBlB,OAAO,CAAC,QAAQ;IAwDhB,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,QAAQ;CAYjB;AAyFD,8EAA8E;AAC9E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,GAAG,SAAS,CAG9F"}

package/dist/engine.js

@@ -13,8 +13,9 @@
 // fall-through from an inner scope to an outer one — see `resolveIn`.
 import { DefaultContext } from "./context.js";
 import { OqxError } from "./errors.js";
-import { equals, relate, arith, membership, truthy, toNumber, compareForSort, makeRange, } from "./semantics.js";
+import { equals, relate, arith, membership, truthy, toNumber, compareForSort, makeRange, isEntry, } from "./semantics.js";
 const RECUR = new Set(["$depth", "$stop", "$leaf", "$frontier", "$ordinal"]);
+const KEY = "$key";
 const HARD_DEPTH_CAP = 8;
 const UNBOUNDED = { offset: 0, limit: null };
 export class InMemoryEngine {
@@ -60,7 +61,7 @@ export class InMemoryEngine {
             : Infinity;
         let kept = [];
         for (const r of rows) {
-            const s = { row: r, parent: root, bindings, lifts: {} };
+            const s = this.enter(r, root, { lifts: {} });
             if (!query.where || this.evalWhere(query.where, s)) {
                 kept.push(s);
                 if (kept.length >= cap)
@@ -97,20 +98,37 @@ export class InMemoryEngine {
     matches(where, row, parent) {
         if (!where)
             return true;
-        return this.evalWhere(where, { row, parent, bindings: parent.bindings });
+        return this.evalWhere(where, this.enter(row, parent));
     }
     rowsOf(v) {
         return Array.from(this.ctx.toRows(v));
     }
     child(row, parent) {
-        return { row, parent, bindings: parent.bindings };
+        return this.enter(row, parent);
+    }
+    // Make the scope for a row. An `entries()` entry is unwrapped here: the scope's
+    // row is the property's VALUE (so `$value` and bare names read it) and the key
+    // becomes the `$key` intrinsic in `meta`. Every place a row becomes a scope
+    // goes through this, so entries behave the same at the top level, in nested
+    // blocks, as `from` re-projections, and as follow seeds.
+    enter(row, parent, extra = {}) {
+        const s = { row, parent, bindings: parent.bindings };
+        if (extra.lifts)
+            s.lifts = extra.lifts;
+        if (extra.meta)
+            s.meta = extra.meta;
+        if (isEntry(row)) {
+            s.row = row.value;
+            s.meta = { ...(s.meta ?? {}), [KEY]: row.key };
+        }
+        return s;
     }
     // ---- follow ---------------------------------------------------------------
     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);
-        let scopes = occ.map((o) => ({ row: o.row, parent: root, bindings: root.bindings, lifts: {}, meta: o.meta }));
+        let scopes = occ.map((o) => this.enter(o.row, root, { lifts: {}, meta: o.meta }));
         if (post)
             scopes = scopes.filter((s) => this.evalWhere(post, s));
         this.sortScopes(scopes, query.orderBy);
@@ -151,7 +169,7 @@ export class InMemoryEngine {
     //     `ctx.identity(row)`.
     followWalk(seedRows, follow, parent) {
         const cap = follow.depth ?? HARD_DEPTH_CAP;
-        const scopeFor = (row) => ({ row, parent, bindings: parent.bindings });
+        const scopeFor = (row) => this.enter(row, parent);
         const keyOf = (row) => String(follow.by ? this.evalExpr(follow.by, scopeFor(row)) : this.ctx.identity(row));
         const succOf = (row) => {
             const raw = this.rowsOf(this.evalExpr(follow.receiver, scopeFor(row)));
@@ -309,7 +327,7 @@ export class InMemoryEngine {
         for (const proj of op.sub.from)
             rows = rows.flatMap((r) => this.rowsOf(this.evalExpr(proj, this.child(r, scope))));
         for (const r of rows) {
-            const s = { row: r, parent: scope, bindings: scope.bindings, lifts: {} };
+            const s = this.enter(r, scope, { lifts: {} });
             if (!op.sub.where || this.evalWhere(op.sub.where, s))
                 yield s;
         }
@@ -326,8 +344,8 @@ export class InMemoryEngine {
             let rows = this.rowsOf(this.evalExpr(op.receiver, scope));
             for (const proj of sub.from)
                 rows = rows.flatMap((r) => this.rowsOf(this.evalExpr(proj, this.child(r, scope))));
-            const seeds = sub.where ? rows.filter((r) => this.evalWhere(sub.where, { row: r, parent: scope, bindings: scope.bindings, lifts: {} })) : rows;
-            scopes = this.followWalk(seeds, sub.follow, scope).map((o) => ({ row: o.row, parent: scope, bindings: scope.bindings, meta: o.meta }));
+            const seeds = sub.where ? rows.filter((r) => this.evalWhere(sub.where, this.enter(r, scope, { lifts: {} }))) : rows;
+            scopes = this.followWalk(seeds, sub.follow, scope).map((o) => this.enter(o.row, scope, { meta: o.meta }));
             this.sortScopes(scopes, sub.orderBy);
             if (op.distinct)
                 scopes = this.dedupByProjection(scopes, sub);
@@ -417,9 +435,10 @@ export class InMemoryEngine {
     // Resolve a name against ONE scope — never its ancestors. A scope provides,
     // in order: `$value` (the scope's row itself — the current item, whatever its
     // type, so scalar collections are queryable; absent at the root, which has no
-    // row); 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.
+    // row); `$key` (the property key, for an entry scope only — 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.
     //
     // A name the scope lacks is simply absent (undefined). It does NOT fall
     // through to an enclosing scope, so a query's meaning never depends on which
@@ -430,7 +449,7 @@ export class InMemoryEngine {
     resolveIn(name, scope) {
         if (name === "$value")
             return scope.parent === null ? undefined : scope.row;
-        if (RECUR.has(name))
+        if (name === KEY || RECUR.has(name))
             return scope.meta ? scope.meta[name] : undefined;
         if (scope.lifts && name in scope.lifts)
             return scope.lifts[name];