@jarenjs/db 0.56.0 → 0.66.1

package/README.md

@@ -136,7 +136,44 @@ stated per call (`users.execute<User>(…)`) because only the caller
 knows what its `$return` produces. `query()` answers the same document
 as an item cursor (`for await`), one item per pull and never unwrapped —
 the read to use when an item may itself be an array. The handle's own
-shape binds at `store.collection<User>('users')`.
+shape binds at `store.collection<User>('users')`. An entity set answers
+the same cursor as `cursor(document, options)`: one row per pull from
+an open statement, the statement released exactly once when the loop
+breaks, throws, finishes or its `signal` aborts (`JD2072` on the next
+pull). Every cursor says what it will do — `streaming: 'row'`, or
+`'buffered'` with the `barrier` that forces it (a set residual's
+construct, an external the database cannot bind, a chain's window) —
+and a linq chain's `for await` over a set IS this cursor, so a
+`break` after three rows of twenty thousand costs three rows. A cursor
+registers no snapshots unless asked (`tracking: true`, one per yielded
+row — unbounded in the result size, by the caller's choice).
+
+On synchronous connections, `store.sync.entity(name)` also offers `cursor`,
+`loadCursor` and `page`. The cursors use `for...of` and support `return()`
+and `Symbol.dispose`; pages return values immediately. Both surfaces use
+the same plans, bounds and continuation identities. Closing the store
+releases every active iterator; later entry refuses with `JD2063`.
+
+A graph
+streams the same way: `loadCursor(spec)` yields one root with its
+includes attached, and every include is bounded per root (`maxRows`,
+`maxBytes`, defaults 1000 rows and 1 MiB; `Infinity` spelled for the
+unbounded case) — crossing a bound is `JD2073` naming the root, the
+member and the bound, never a silently truncated graph. A list pages
+over a composite keyset — `entity.page(spec, { limit, after, maxBytes })`
+with `orderBy` over `(updatedAt, id)`-shaped orderings, the primary
+key appended as the tie-breaker and null placement matching the plan —
+and answers `{ items, continuation, hasMore, snapshot }`: the
+continuation is unsigned and structural (the host signs it), an item
+larger than `maxBytes` is `JD2074` without advancing it, and
+`snapshot` is true only over an immutable ordering; over a mutable one
+the page is live and says so (MODEL-FORMAT §10.5). `explainLoad()`
+reports both facts separately: `order` is the deterministic order the
+statement executes under in EVERY load mode — the declared terms and the
+tie-breaker the clause appends, the primary key in keyset mode and the
+row identity otherwise — and `identity` is the ordering identity a
+continuation carries and is checked against, `null` for a load that has
+no continuation to emit.
 
 - **The pushdown planner with `explain()`.** A query compiles through
   the engine's published AST into a dialect-neutral plan and renders
@@ -144,10 +181,50 @@ shape binds at `store.collection<User>('users')`.
   equivalent runs as a real compiled Jaren query (the residual), and
   `explain()` always says which is which — the SQL, the bound
   parameters, the indexes used (verified against the database's own
-  plan output), and the residual's named reasons. A differential
+  plan output), and the residual's named reasons. It answers for the
+  RUN it describes: given the externals `execute` is given, a value the
+  database cannot bind (a boolean, a null, a missing name) is reported
+  as the set residual the call becomes — mode, statement and reason —
+  and counted in `stats().bind.diverted`, so a production diversion is
+  visible where nobody calls `explain()`. Every explanation carries
+  `streaming` (`'row'` or `'buffered'`) and `barrier` (the construct
+  that forces a buffer, or `null`), the same classification the cursor
+  itself carries; `strictStreaming: true` on a cursor declines a
+  buffering plan by name (`JD0037`) before any statement runs. Every
+  explanation also carries `order`: the deterministic order the
+  statement executes under, in one closed vocabulary — a mapped
+  `column`, a `document` path, a bucketed plan's `group` key, or the
+  row `identity` the plan appends so a sequence answers in insertion
+  order — read from the plan rather than parsed back out of SQL, and
+  `null` only for a statement that orders nothing at all (an aggregate
+  answers one row; a k-nearest fetch is unordered because the engine
+  ranks it). Each refusal reason is drawn from a closed vocabulary too,
+  so a reason a caller matched on stays the sentence it was. A
+  `$return` that is ONE member path over the binding projects that
+  path into the statement — its value beside its JSON type, so a
+  present `null`, an absent member and a boolean read back exactly as
+  the engine answers them — and `$count` over it counts the rows where
+  the member is present with a `COUNT(*)`. A `$return` that is a nested
+  SHAPE — objects, arrays, literals and member paths, to any depth —
+  projects the same way: the statement fetches one value/type pair per
+  DISTINCT leaf (a path named twice is fetched once) and the decoder
+  rebuilds the shape, so an absent member is omitted from its object
+  and skipped in its array exactly as the engine does it, and a literal
+  `null` stays present where a path that finds nothing does not.
+  `explain().projection` names the path or the leaf `paths`, and
+  reading a shape no longer reads every document. A shape the tree
+  cannot rebuild — an operator over a member, a reference to the
+  binding itself, a projection with no path at all — refuses WHOLE and
+  runs per row, with `explain().residualProjection` naming what stayed
+  behind: promoting the half that composes would answer a shape nobody
+  asked for. Every `explain()` also carries `budget`: the profile
+  that applied, every bound it imposed, and the two driver slots
+  (`time`, `estimatedRows`) reported `unavailable` on SQLite rather
+  than estimated (MODEL-FORMAT §8). A differential
   oracle — a committed corpus and a seeded generator, every case run
-  in both modes — keeps both paths agreeing, with the one arithmetic
-  deviation declared rather than hidden (MODEL-FORMAT §10.6: SQLite's
+  resident, native, native again over a store with every declared index
+  removed, and forced-residual — keeps every path agreeing, with the one
+  arithmetic deviation declared rather than hidden (MODEL-FORMAT §10.6: SQLite's
   compensated `SUM` and the engine's naive one differ in the last
   bit). `strict: true` turns any residual into a compile error.
 - **Registered operators, correct in the residual, pushed where it
@@ -167,6 +244,44 @@ shape binds at `store.collection<User>('users')`.
   registration for untrusted documents); the profile's `functions`
   allow-list still governs a `$call`-reached `fn`; the row bound still
   fires. Without a registry the store is unchanged — `$npv` is `JQ0002`.
+  A pack may also mark a whole-sequence summary `pushable: 'aggregate'`
+  (the statistics pack's `$mean`, `$median`, `$variance`, `$stddev`):
+  where the driver has an aggregate API it becomes a registered **SQL
+  aggregate** over the member's column, folded by the same pure
+  function, so the accumulation runs in SQLite rather than over fetched
+  rows. The token is a promise the store checks — one `seq<number>`
+  operand and a scalar result, or the declaration is refused at
+  `openStore` by name — and the promotion still needs a numeric member
+  the schema forbids `null` on, because SQL cannot tell a stored `null`
+  from an absent one and the engine can.
+- **Grouping and joins lower whole, or not at all.** A `$groupby` over
+  schema-typed member keys becomes a real `GROUP BY`: the keys come back
+  with their JSON types beside them, so a group whose key is ABSENT
+  leaves that member out exactly as the object constructor does, the
+  closed aggregate set (`$count`, `$sum`, `$avg`, `$min`, `$max`) folds
+  in SQL under the ENGINE's empty rules (`0` for a count or a sum, no
+  member at all for the other three), and the groups come out in the
+  engine's own order of first appearance unless an `$orderby` over the
+  keys says otherwise. Entity queries join any number of bindings: every
+  binding past the first must be attached by a column equality to one
+  already joined, which is what makes the plan a nested loop the engine
+  can be compared against — a binding nothing attaches would be a
+  cartesian product, so it is the residual, named, and `strict: true`
+  refuses it. `explain()` lists the join order with the equalities that
+  attached each binding, and the group's keys, aggregates and order.
+  A join predicate that is not an equality — a range between two mapped
+  columns of one family — refines a match it never makes: the anchor is
+  still an equality, so a range alone stays the residual. A projected
+  join lowers too, through the same leaf decoder a single-binding
+  projection uses, each leaf read from its own binding's alias.
+- **A declared join table is a read-only query root.** `$.<JoinTable>[*]`
+  answers rows carrying exactly its two key columns and joins to the
+  entities it relates, so `Person → Person_Tag → Tag` is one statement
+  over three roots — while `store.entity('<JoinTable>')` is still
+  `JD2004` and memberships are still written through `link`/`unlink`.
+  Because the root exists, a many-to-many hop on the chain lowers
+  through it (two links: the membership, then the row it names) instead
+  of refusing.
 - **Storage is declarative.** Indexed paths become generated columns
   plus real indexes, typed from the collection's schema. Opening an
   existing database verifies the declared shape and refuses to alter
@@ -212,11 +327,42 @@ shape binds at `store.collection<User>('users')`.
   from the committed `model.snapshot.json`, refuses a module that is
   not pure, and `jaren-db check` fails CI on a model that moved without
   a plan (MIGRATION-FORMAT §11).
+- **A document migration does not need the database.** Its `jslt` and
+  `query` steps act on documents, so `migrateDocuments` runs them over
+  arrays and `streamDocuments` over a source it may walk only once,
+  writing each document out as it finishes and holding one batch. Both
+  share ONE implementation of what a step means with the store runner,
+  so the array answer equals the store answer — on the same step, in the
+  same words, down to the refusal. A step that needs tables (`ddl`,
+  `sql`, `rebuild`, `derive`) is refused by name before the first
+  document is read, never skipped (MIGRATION-FORMAT §6.1). `jaren-db
+  documents` is the same thing at the command line, over a JSON array,
+  JSONL or stdio:
+
+  ```sh
+  # rewrite a file in place — a sibling temporary is renamed over it
+  # only once every document has survived every step
+  jaren-db documents --migrations ./migrations --in users.jsonl --in-place --yes
+
+  # the CI shape: transform and validate everything, write nothing
+  jaren-db documents --migrations ./migrations --in users.json --check
+  # 0 the chain applies, 1 the run failed, 2 the command line was wrong
+
+  # also the converter: the input and output encodings are independent
+  jaren-db documents --migrations ./migrations --in users.json --out users.jsonl
+  ```
+
+  A JSON array is scanned structurally rather than parsed whole, so both
+  encodings hold one batch and not the file: the live set is flat in the
+  size of the input, and a file larger than memory still migrates.
 - **The safe profile.** Untrusted query documents run under composed
   bounds: engine limits on the residual, a mandatory row bound that
   refuses rather than truncates, reference allow-lists, optional
-  full-scan refusal, and per-collection mandatory predicates no
-  document shape can shed. Read-only stores refuse writes at the
+  full-scan refusal, per-collection mandatory predicates no document
+  shape can shed, and a per-root MEMBER allow-list — the members a
+  document may read, checked wherever it names one, where allowing a
+  member allows what is under it and reading the item whole is refused
+  rather than quietly narrowed. Read-only stores refuse writes at the
   driver.
 - **Writes validate** through an injected hook; without one,
   `store.capabilities.validated` is `false` and the docs say what that
@@ -370,8 +516,8 @@ fixture on disk and the number of entries run against the corpus. Each
 runner names the executor, the entry and the query when it disagrees.
 That is the whole claim — not faster than anyone, not PostGIS — and the
 browser leg's limit is stated with it: **it proves execution, not
-durability.** Where OPFS is unavailable the tab's store is in-memory,
-which is a property of the host, not of the suite.
+durability.** The separate [host matrix](docs/HOSTS.md) proves OPFS and
+IndexedDB persistence and the visibly non-durable memory fallback.
 
 **No head-to-head rival, and saying so.** Nothing else in JavaScript
 stores GeoJSON in SQLite from a JSON query document, so the suite
@@ -470,28 +616,40 @@ wrong width is refused at plan time and `explain()` says why; an
 `knn` and the fallback is counted instead — `stats().knn.diverted` is
 that count, and a consumer who binds probes from a model should watch it.
 
+**Several declared widths, one compiled query.** A member may carry more
+than one `derive: 'vector'` index — a 384-wide embedding beside a
+768-wide one — and an external probe then binds the column its OWN width
+names. The plan carries one alternative per declared width and emits one
+statement per alternative, prepared once and kept with the plan; the
+bind picks exactly one. No `CASE` across the columns (that would read
+every one of them per row) and no statement per call (that would give up
+the prepared cache). `explain().rank` names the `alternatives` and, when
+the call was given its externals, the `selected` width — the probe is
+named, never printed. A width the model does not declare is the same
+counted diversion any unbindable probe is.
+
 **The numbers, the losses included.** `benchmark/vector.js` measures one
 k-nearest query every physical way it can run — over <!--fact:vector.grid-->10,000 and 50,000 vectors at 384 and 768 dimensions, k = 10, the median of 10 probes<!--/fact--> —
 and asserts that every path returns the identical top-k, ids and order,
 on every probe before a single timing prints. The flagship row is the
-plan a consumer's own document runs, which measures <!--fact:vector.plan-->206 ms at 50,000 × 768<!--/fact-->:
+plan a consumer's own document runs, which measures <!--fact:vector.plan-->191 ms at 50,000 × 768<!--/fact-->:
 <!--fact:vector.table-->
 | path (ms) | 10,000 × 384 | 10,000 × 768 | 50,000 × 384 | 50,000 × 768 |
 |---|---:|---:|---:|---:|
-| engine resident sweep (no database) | 3.3 | 6.7 | 17 | 32 |
-| **the k-nearest plan (the store's own)** | 22 | 33 | 139 | 206 |
-| raw fetch + engine sweep (the plan's statement) | 20 | 31 | 130 | 202 |
-| `ORDER BY` over a registered function | 18 | 31 | 121 | 180 |
-| JSON-doc sweep (no vector column) | 249 | 501 | — | — |
-| sqlite-vec | 3.6 | 7.5 | 18 | 38 |
+| engine resident sweep (no database) | 3 | 5.8 | 15 | 28 |
+| **the k-nearest plan (the store's own)** | 21 | 30 | 127 | 191 |
+| raw fetch + engine sweep (the plan's statement) | 19 | 28 | 118 | 182 |
+| `ORDER BY` over a registered function | 17 | 26 | 113 | 158 |
+| JSON-doc sweep (no vector column) | 232 | 468 | — | — |
+| sqlite-vec | 3.3 | 6.9 | 17 | 35 |
 <!--/fact-->
 
 The row the column exists to beat is the last one that has no column: the
 same query document over a collection that stores the embedding only
-inside the document costs <!--fact:vector.jsonDoc-->15.0× the plan at 10,000 × 768<!--/fact-->,
+inside the document costs <!--fact:vector.jsonDoc-->15.6× the plan at 10,000 × 768<!--/fact-->,
 because every row's vector is parsed out of JSON before it can be
 compared. The row the store **cannot** beat is the one with no database
-in it: the same top-k over a resident `Float32Array` is <!--fact:vector.resident-->32 ms, which the plan is 6.4× slower than<!--/fact-->.
+in it: the same top-k over a resident `Float32Array` is <!--fact:vector.resident-->28 ms, which the plan is 6.8× slower than<!--/fact-->.
 That comparison is not an even one and the direction is the point — the
 sweep starts from decoded floats in RAM and pays nothing for durability,
 for filters that compose with the ranking, or for a process that can
@@ -500,7 +658,7 @@ price should be able to say what the price is.
 
 **Both halves of the price.** The column costs on the way in as well as
 saving on the way out: writing the same documents with
-the index costs <!--fact:vector.write-->10.6 s against 5.0 s for 50,000 documents in one transaction — 2.1× the write cost<!--/fact-->,
+the index costs <!--fact:vector.write-->10.2 s against 4.9 s for 50,000 documents in one transaction — 2.1× the write cost<!--/fact-->,
 because every write pays a JSON round trip of the member plus a
 normalize and a pack. On disk one vector is <!--fact:vector.storage-->3,072 B packed against 16,141 B as a JSON number array inside the document — 5.3× smaller<!--/fact--> —
 smaller, but *added*, since the document still carries the member the
@@ -509,7 +667,7 @@ column is derived from.
 **Pushing the rank into SQL, re-measured.** A registered similarity
 function inside an `ORDER BY … LIMIT k` is the obvious alternative, and
 the suite measures it against the real column with the probe hoisted out
-of the per-row call: <!--fact:vector.udf-->180 ms against 202 ms at 50,000 × 768, and 0.87–1.00× the fetch-and-rank across the grid — rough parity on speed<!--/fact-->.
+of the per-row call: <!--fact:vector.udf-->158 ms against 182 ms at 50,000 × 768, and 0.87–0.95× the fetch-and-rank across the grid — rough parity on speed<!--/fact-->.
 The plan does not emit it, and after that measurement the reasons are not
 speed: `bun` has no user-function API, so a plan that needed one would
 exclude an executor outright; and an ordering decided in SQL cannot break
@@ -518,7 +676,7 @@ executors have to agree on.
 
 **The rival, and the ceiling.** `sqlite-vec` is the extension built for
 exactly this, and it is measured rather than described: it answers the
-same probes in <!--fact:vector.rival-->38 ms against 206 ms at 50,000 × 768 — 5.4× in sqlite-vec's favour, out of a database 6.6× smaller that holds no documents<!--/fact-->,
+same probes in <!--fact:vector.rival-->35 ms against 191 ms at 50,000 × 768 — 5.5× in sqlite-vec's favour, out of a database 6.6× smaller that holds no documents<!--/fact-->,
 over <!--fact:vector.agreement-->40 probes, no disagreements<!--/fact-->. It is a
 loadable native extension, which is the one thing this store will not
 require — it would exclude the wasm tab and stock `bun`, half the
@@ -526,7 +684,7 @@ execution story — so the comparison is published as what it is: a faster
 engine you may prefer, and a dependency this one does not take. What
 neither of them is, is an approximate index. Exact brute force is linear
 in `n · d`, and the suite states the envelope as arithmetic rather than
-opinion: <!--fact:vector.ceiling-->5.546 ns per vector component — one query reaches 100 ms at about 22,000 vectors of 768 dimensions and one second at about 234,000<!--/fact-->.
+opinion: <!--fact:vector.ceiling-->5.142 ns per vector component — one query reaches 100 ms at about 24,000 vectors of 768 dimensions and one second at about 252,000<!--/fact-->.
 Past that this design is the wrong tool and no margin changes it; what
 lies beyond is an approximate index, and this store does not have one.
 
@@ -584,12 +742,12 @@ as-of join over one seeded corpus by plain references, by the temporal
 kernel, by a generic query document, by hand-written SQL and by the
 store — every route checked against the others before a timing is
 taken. At <!--fact:series.corpus-->100,000 samples at 1-second spacing, Node v24.19.0<!--/fact-->,
-the store is measured three ways at once — <!--fact:series.storeShapes-->the planned range costs 4.2× the hand-written statement and 1535.5× the resident cut, and the pushed bucket ladder 2.5× the hand-written GROUP BY, 1.6× FASTER than the generic query route, and 155.1× the one-pass loop<!--/fact-->.
+the store is measured three ways at once — <!--fact:series.storeShapes-->the planned range costs 4.3× the hand-written statement and 1435.1× the resident cut, and the pushed bucket ladder 2.1× the hand-written GROUP BY, 1.8× FASTER than the generic query route, and 146.6× the one-pass loop<!--/fact-->.
 The range row is not the planner's price: the statement selects two
 COLUMNS where the store renders and parses a whole JSON document per
 row, which is what storing documents costs.
 
-And what a refinement costs, with the loss in it: <!--fact:series.storeRefinement-->A window measured in time is not pushed: the store answers it at 18.5× the kernel over an array already in memory, over 100,000 candidates the index bounded. The batched as-of join reads 99,129 rows in 1 statement and costs 1424.3× fifty-one separate index reads — a bound is what it buys, not a speed-up, and without a tolerance a backward join can only be bounded above.<!--/fact-->
+And what a refinement costs, with the loss in it: <!--fact:series.storeRefinement-->A window measured in time is not pushed: the store answers it at 17.7× the kernel over an array already in memory, over 100,000 candidates the index bounded. The batched as-of join reads 91,682 rows in 2 statements and costs 1477.0× fifty-one separate index reads — a bound is what it buys, not a speed-up. Without a tolerance the open side has no bound the probes imply, so the plan reads the data's own: the last instant each series carries at or before the earliest probe, folded to the least of them. That anchor is the extra statement, and what it saves depends on where the probes sit — evenly spread ones, as here, leave the least below them to skip.<!--/fact-->
 
 **A refinement is named, never quiet.** `explain().series` reports
 `mode` — `native`, `hybrid` or `engine` — the declared index the fetch
@@ -602,20 +760,49 @@ answer, and a reason code for every thing the database could not do:
 every one of them before a statement runs, and the counts `explain()`
 prints are the LAST ACTUAL execution's — `null` until the document has
 run, because an estimate wearing a count's name is worse than no
-number.
+number. Every path counts: a set residual, a row projection, a native
+aggregate (whose `candidates` stays `null`, since no row reached the
+engine and SQLite reports no visited-row count) and a cursor, which
+counts as it is drained and is final when it settles — read
+mid-iteration, `counts.partial` is `true`. `series.mode` follows the
+plan mode: a selection the engine finishes is `hybrid` when the index
+narrowed the fetch and `engine` when nothing did, never `native` on the
+strength of an index alone.
 
 **The as-of join is bounded, and the bound is the claim.** `$asof` with
 the collection on the right reads the probes it was given, bounds the
 fetch by their own span and by a membership test over their `by` keys,
-and issues exactly ONE statement whatever the probes number — the
-failure mode a batch exists to refuse is one seek per left row, and
-`test/db/statement-count.test.js` pins it at 1, 10 and 200 probes.
-Without a `tolerance` a backward join can only be bounded ABOVE, so
-that one statement can read most of a long history: the benchmark
+and issues a FIXED number of statements whatever the probes number —
+the failure mode a batch exists to refuse is one seek per left row, and
+`test/db/statement-count.test.js` pins the count at 1, 10 and 200
+probes. Without a `tolerance` the open side has no bound the probes
+imply — the row that answers the earliest probe may lie arbitrarily far
+before it — so the plan asks the database for the data's own: per
+series, the last instant at or before that probe, folded to the least
+of them. That anchor is one aggregate read through the same declared
+index, bound through a typed slot, and it is the second statement.
+
+What it saves depends on where the probes sit, so the benchmark
 publishes the candidate count beside the timing rather than netting it
-out, and at fifty-one probes over a hundred thousand rows the batch
-LOSES to fifty-one separate index reads. Few questions of a large
-series belong to a batch; a join of two series does.
+out, over probes spread evenly across the whole span — which is the
+anchor at its worst, since the earliest of them has almost nothing
+below it to skip. At fifty-one such probes over a hundred thousand rows
+the batch still LOSES to fifty-one separate index reads. Few questions
+of a large series belong to a batch; a join of two series does.
+
+**`$overlaps` narrows through a declared interval.** Type a member as an
+object whose `start` and `end` are both required and both numeric, map
+each bound to a column, and the half-open test pushes: two comparisons
+over the declared columns, with the engine's own operator deciding over
+what comes back. It stays a pre-filter rather than an exact translation
+because §8.16 RAISES on a span whose end is at or before its start, and
+no schema keyword forbids storing one — so the statement keeps every
+inverted row and the operator raises over it exactly as it would have.
+That disjunct compares two columns, which no index bounds, so the fetch
+scans; what it buys is that the pruned rows never reach the engine at
+all. An unmapped pair, a schema that admits a textual bound, or a probe
+that is not itself a half-open span pushes nothing and names why —
+`strict: true` answers `JD0010`.
 
 **One corpus, five executors, proven to agree.** The committed temporal
 corpus (`test/json/fixtures/series-corpus.json`) runs through the plain
@@ -624,16 +811,93 @@ both drivers again with pushdown forced off — indexed and unindexed —
 and every case must answer identically, plan mode and reason codes
 included.
 
-## What SQLite-only means, frankly
+## Two backends, frankly
+
+SQLite is the primary backend — 3.45 or newer, on `node:sqlite`,
+`bun:sqlite`, or your injected wasm build — and **PostgreSQL 16+** is
+the second, through `@jarenjs/db/postgres`:
 
-SQLite is the supported backend — 3.45 or newer, on `node:sqlite`,
-`bun:sqlite`, or your injected wasm build — and nothing else is
-promised. The dialect seam exists and is tested against a double, but
-no second dialect ships. Concretely: there is **no statement timeout**
-(the drivers expose no interrupt; the capability slot is honestly
-`false`), no server, no replication, and cross-process concurrency is
-SQLite's own story (WAL plus a busy timeout, both set and visible on
-`store.capabilities`).
+```js
+import { openStore } from '@jarenjs/db';
+import { postgresDriver } from '@jarenjs/db/postgres';
+import { Pool } from 'pg';                    // yours, not ours
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+const store = await openStore(model, {
+  driver: postgresDriver(pool, { schema: 'app' }),
+});
+```
+
+The client is INJECTED. `@jarenjs/db` depends on nothing outside
+`@jarenjs/*` and imports no PostgreSQL package; anything with
+`connect()` answering `{ query(text, values), release?() }` will do, and
+a `pg.Pool` is one as it stands. One client is acquired at open, held
+for the store's life (a connection owns one savepoint stack) and
+released exactly once at `close()`.
+
+The same model, the same query documents and the same differential
+oracle run on both. What differs is declared rather than discovered:
+
+| | SQLite | PostgreSQL |
+|---|---|---|
+| documents | JSONB in a `BLOB` of a `STRICT` table | `jsonb` |
+| an indexed path | a `VIRTUAL` generated column | a `STORED` one, guarded by `jsonb_typeof` |
+| text ordering | the default `BINARY` collation | `COLLATE "C"`, which is the same bytes |
+| a collection's order | the implicit `rowid` | a declared `rid bigserial` |
+| `integer` and `number` | `INTEGER` and `REAL` | both `numeric` |
+| a `boolean` member | `INTEGER` 1/0 | `smallint` 1/0 |
+| an untyped indexed path | `ANY` — compares with anything | `jsonb` — the predicate reads the document instead |
+| configuration | the closed pragma set, read back at open | the operator's; `store.capabilities.pragmas` is all `null` |
+| drift detection | the stored `CREATE` text, exactly | the structural check: columns, indexes, foreign keys |
+| the job queue, the change ledger and live queries | yes | no — `capabilities.jobs` and `capabilities.changeCapture` are `false`, and asking for one is a coded refusal at open |
+| maintenance (checkpoint, integrity, optimize) | yes | no — every one of them IS a pragma |
+| a spatial `physical: 'rtree'` | an R\*Tree virtual table | the B-tree over the four edge columns, and `explain().prefilters[].via` says so |
+| a transaction a statement failed in | continues | is aborted until it ends (`JD2088`); catch-and-continue needs a nested `transaction()` |
+| `ALTER TABLE` | additive only | full, so a rebuild is never needed |
+
+Neither backend has a **statement timeout** (`capabilities.statementTimeout`
+is `false` on both) or **row estimates**. There is no replication.
+Cross-process concurrency on SQLite is its own story — WAL plus a busy
+timeout, both set and visible on `store.capabilities`; on PostgreSQL it
+is the server's, and a serialization failure or a deadlock arrives as
+`class: 'busy'`, `retryable: true` — the same verdict, and the same
+caller branch, a locked SQLite file gets.
+
+### What PostgreSQL costs
+
+`npm run benchmark:postgres` runs the same model, the same documents and
+the same query documents through the same store on both engines, checks
+that they answered identically, and prints the difference. It is **not**
+a rival comparison and reading it as one would be reading it wrong: an
+in-process database against a server over a socket loses every row that
+pays a round trip, and the shape of the loss is the point.
+
+Measured here at 500 documents — PostgreSQL 17.5 in a container on the
+same host, SQLite in memory, Node 24.19.0 — every row a loss except the
+first, and every one expected:
+
+| operation | ratio, PostgreSQL over SQLite |
+|---|---|
+| open the store (create or verify the shape) | 0.9× |
+| insert one document | 14.5× |
+| get one document by key | 12.8× |
+| an indexed equality over 500 documents | 1.6× |
+| an indexed range over 500 documents | 1.6× |
+| an unindexed equality over 500 documents | 1.5× |
+| one transaction with one write | 4.7× |
+| apply one migration (one new index) | 4.3× |
+
+The reading: a per-ROW operation pays about thirteen to fifteen times,
+because each one is a round trip that SQLite makes as a function call. A
+whole-collection query pays about one and a half, because the round trip
+is amortized over five hundred rows and the rest is the server doing the
+same work SQLite did. Two consequences worth stating: a loop of
+`insert()` is the wrong shape on PostgreSQL in a way it is not on SQLite,
+and pushdown matters MORE there — an unindexed scan that comes back as
+five hundred rows for the engine to filter would pay the per-row price,
+not the per-query one.
+
+Your numbers will differ; the command is the point, not the table.
 
 ## The relational half (phase B)
 
@@ -652,7 +916,37 @@ SQLite's own story (WAL plus a busy timeout, both set and visible on
   proxies, asserted); mutation is replacement; `saveChanges()` diffs
   snapshots into minimal parameterised statements in one transaction,
   with insert batching, `JD0040` cycle refusal, `JD2040` optimistic
-  conflicts, and a report of every statement, fallback and count.
+  conflicts, and a report of every statement, fallback and count. Its
+  fate is its transaction's: an enclosing rollback WITHDRAWS the advance,
+  so a caller's retry plans the same statements again instead of
+  reporting a success it never had.
+- **Transaction ownership** (MODEL-FORMAT §5.1): the store a transaction
+  callback receives IS the transaction — `tx.collection`, `tx.entity`,
+  `tx.sync`, `tx.jobs`, `tx.saveChanges()`, and `tx.transaction()`
+  nesting through its savepoint. A store-level handle is by construction
+  somebody else: it holds the connection for its own extent, so an
+  unrelated writer on a shared store keeps its own fate rather than
+  sharing a rollback it knows nothing about. Contention waits under
+  `queueTimeout` and then names itself `JD0012`, or refuses at once under
+  `openStore(model, { transactions: 'strict' })`. One store is safe for a
+  handler per request. Every `tx` view is pinned to its EXACT scope: a
+  handle retained past its callback, or an outer handle used while an
+  async inner savepoint is open, refuses `JD2070` instead of joining a
+  transaction it does not own — and a transaction view carries no
+  `close`, because it never owns the connection's lifetime. A root
+  cursor (`collection.query()`, `entity.cursor()`, `entity.loadCursor()`)
+  is admitted **per pull**: construction holds nothing, each `next()` and
+  `return()` borrows the gate for one item's work and releases before it
+  settles, so a paused consumer blocks no transaction and no pull ever
+  reads another transaction's uncommitted row; `store.live()` registers
+  under the same gate through its initial query.
+- **Named savepoints** (MODEL-FORMAT §5.2): `tx.savepoints.create /
+  rollbackTo / release` give a live transaction checkpoint-and-continue
+  without a sentinel exception — the target stays active after a
+  rollback, `release` keeps the rows, labels never reach SQL, and the
+  tracker, capture stream and `tx.jobs` outbox all agree with the
+  database after every partial rollback. The synchronous twin is
+  `tx.sync.savepoints`; a blank, duplicate or unknown label is `JD2071`.
 - **Generated types**: `entityEmitModel` + `@jarenjs/emit` render the
   model into entity interfaces, input variants and an `EntityMetaMap`;
   `typedStore` (from `@jarenjs/db/typed`) types every read, checks
@@ -676,12 +970,24 @@ SQLite's own story (WAL plus a busy timeout, both set and visible on
   EQUALITY against a fresh build as the acceptance criterion, drift
   detection, and `jaren-db check` for CI.
 
+## Execution hosts
+
+`@jarenjs/db/node-worker` exports `nodeWorkerDriver()` for SQLite off the caller
+thread; `@jarenjs/db/node-pool` exports `nodeWorkerPoolDriver()` for one writer and
+bounded read-only WAL workers. Both use the ordinary Store contract, with credited
+row frames, generation fencing, queue refusals and inspected lifecycle metrics.
+Async connections declare `store.sync` and live queries unavailable. See
+[execution hosts](docs/HOSTS.md) for options, cleanup guarantees, native-call
+shutdown limits, the browser persistence matrix and measured latency/memory losses.
+
 ## The reactive and durable half (phase C)
 
 - **Change capture** (LIVE-FORMAT §§1–6): every committed write
   becomes an observable stream of RFC 6902 patches — from SQLite's
   own session changesets where the binding has them, from a write-path
-  journal where it does not (`bun:sqlite`, the wasm build). One diff
+  journal where it does not (`bun:sqlite`, Node worker connections). The
+  wasm adapter probes the live session API and names a failed probe in
+  `sessionReason`. One diff
   format runs store → patch → live query → O(k) render. Capture is
   opt-in; the overhead is published, not waved away.
 - **Live queries** (LIVE-FORMAT §§7–13): `collection.live(document)`
@@ -699,19 +1005,53 @@ SQLite's own story (WAL plus a busy timeout, both set and visible on
   rather than being folded in as though it had arrived on time.
 - **Durable runs and the job queue** (JOBS-FORMAT, FLOW-FORMAT §7.6):
   a `@jarenjs/flow` DAG run checkpoints declared nodes and RESUMES
-  after a crash; `store.jobs` leases work in one guarded statement
-  (exactly-once completion, no distributed lock), retries with
-  backoff, dead-letters, and reclaims expired leases as recovery.
+  after a crash; `store.jobs` leases work in one guarded statement (no
+  distributed lock), retries with backoff, dead-letters, and reclaims
+  expired leases as recovery. Every settling call carries a FENCE — the
+  opaque token one claim mints, plus a lease that is still valid — so an
+  expired or superseded attempt cannot mark a job done over the live
+  one's result, and is told which of three things happened rather than
+  answered `false`. `jobs.renew()` replaces a lease while a handler runs;
+  the worker does it automatically, retries a renewal that failed for a
+  mere storage reason, and aborts only an attempt whose lease is proven
+  lost by a fence code. Settlement is exactly-once **against the store**
+  — an external effect is still the handler's to make idempotent.
+  Ownership follows the handle: root `store.jobs.*` and all worker I/O
+  take the store gate and never join an open application transaction,
+  while `tx.jobs` is the transactional outbox that co-commits with it;
+  and `worker.stop()` quiesces every claim, renewal, checkpoint and
+  settlement before it resolves, so closing the store releases the
+  database file deterministically.
 - **The browser** (`@jarenjs/db/wasm`): the same store, the same
   queries, the same live updates run on the official SQLite wasm build
-  over the header-free OPFS SAH-pool VFS — one tab owns the
+  over a probed persistence ladder: isolated SharedArrayBuffer OPFS,
+  header-free SAH-pool OPFS, atomic IndexedDB snapshots, then visibly
+  non-durable memory. One tab owns the
   connection, others are clients. Proven in the `#/data` studio across
-  Chromium, Firefox and WebKit. The subpath exports the two helpers
+  Chromium, Firefox and WebKit, whose boot is a closed five-stage protocol
+  (LIVE-FORMAT §11): every attempt ends ready or in a named, retryable
+  `DATA_BOOT` failure, never a status line stuck at boot. The subpath exports the two helpers
   that studio is built on: `sqlite3Handle(sqlite3, { DbClass })` builds
   the injected handle from a loaded wasm module and the database class
   the host picks (`sqlite3.oo1.DB` in memory, the SAH-pool
-  `OpfsSAHPoolDb` for OPFS), and `adaptOo1Database(sqlite3, db)` wraps
-  an oo1 database the host already opened.
+  `OpfsSAHPoolDb` or `OpfsDb` for OPFS), and `adaptOo1Database(sqlite3, db)`
+  wraps an oo1 database the host already opened. `indexedDbSnapshotHandle`
+  adds bounded atomic persistence with asynchronous commit acknowledgements;
+  its connection declares synchronous/live methods unavailable.
+- **The runtime record** (`@jarenjs/core/runtime`): `openStore(model,
+  { runtime })` and `migrate(target, migrations, { runtime })` take one
+  frozen record — `{ now, uuid, random, zoneProvider }`, defaulting
+  member for member to the platform's own — for the clock the capture
+  log and the job queue stamp, the identifier a `uuid` identity and a
+  `default: 'uuid'` allocate, the backoff jitter, and the zone provider
+  a temporal spec naming a zone compiles through. The store hands it to
+  the job engine it constructs, so a consumer configures it once, and a
+  subsystem's own explicit option (`zoneProvider`, `jobs.now`,
+  `jobs.random`) wins over the record's member. A query `deadline` is an
+  absolute instant the caller computed and is compared against the
+  record's `now` — before a statement runs and at every row boundary of
+  a cursor or page — so a deterministic run computes its deadlines from
+  the same clock the store reads.
 
 ### What an event-time view costs
 
@@ -742,6 +1082,86 @@ is over §12's default `maxMaintained` at ten thousand readings — the
 bound errors rather than degrading, and raising it is a decision
 somebody makes.
 
+## Indexing a computed value
+
+An index may name a computation instead of a member:
+
+```js
+const model = {
+  $model: '0.1',
+  collections: {
+    users: {
+      schema: { type: 'object', properties: { id: { type: 'string' }, email: { type: 'string' } } },
+      key: '/id',
+      indexes: [{
+        name: 'by_lower_email',
+        expression: { call: 'lower', args: [{ member: '$.email' }] },
+        unique: true,
+      }],
+    },
+  },
+};
+
+const store = await openStore(model, {
+  driver: nodeDriver(),
+  expressions: {
+    lower: {
+      arity: 1,
+      deterministic: true,
+      apply: (value) => String(value).toLowerCase(),  // SQLite registers this
+      sql: 'lower',                                   // PostgreSQL calls its own
+    },
+  },
+});
+
+await store.collection('users').insert({ id: 'a', email: 'ANN@Example.COM' });
+await store.collection('users').insert({ id: 'b', email: 'ann@example.com' });
+// JD2001 — the unique index is over the LOWERED value
+```
+
+The expression is a closed AST — a member, a JSON scalar, or a call —
+and **never SQL text**. The function is DECLARED by you and resolved at
+open: an unknown name, a wrong arity, one not declared `deterministic`,
+or a declaration missing the half this engine needs is `JD0004` before a
+single statement runs. That is not ceremony: an index over a function is
+a schema dependency, and a database whose column is computed by
+`lower(…)` cannot be written from a connection that has no `lower`.
+
+`@jarenjs/linq/model`'s `expressionIndex()` writes the same document
+from a lambda: `expressionIndex({ call: 'lower', args: [(d) => d.email] },
+{ unique: true })`.
+
+## Reading a database back into a model
+
+`store.introspect()` answers the `jaren-model` document a live
+database's shape says it is, and a report of everything the shape
+cannot carry:
+
+```js
+const { model, report } = await store.introspect({ keys: { users: '/id' } });
+// model  — a valid jaren-model: collections, keys, indexes with their paths,
+//          entities with their keys, unique/indexed columns and foreign keys
+// report — [{ code, object, detail }], sorted, one row per gap
+```
+
+It issues no DDL and no DML — every statement it runs begins `SELECT` —
+so reading a production database is a read. What comes back is exact
+where the shape carries the fact and REPORTED where it does not: a
+document's unindexed members are not in the physical shape
+(`document-members`), a text key column cannot say which member filled
+it (`key-source` — `options.keys` supplies the pointer), a view cannot
+be declared (`unmapped-view`), a foreign key cannot say which side
+declared the edge (`ambiguous-relation`). `strict: true` refuses rather
+than answering a partial model.
+
+The derived model is usable as a migration's `from`: read a database,
+plan against your declared model, and an unchanged shape plans nothing.
+SQLite and PostgreSQL derive the same logical model from equivalent
+databases — same collections, same keys, same index names and paths,
+same report rows — with the one difference the PostgreSQL mapping
+states: `numeric` carries both JSON number types, so an `integer`
+member reads back as `number`.
+
 ## Sync-readiness — what exists and what does not
 
 The change stream is an ordered log of RFC 6902 patches with a
@@ -753,6 +1173,93 @@ writes made by another connection (the coarse `dataVersion()` signal
 is the honest mitigation, not a pretend fine-grained one). Building
 replication on these primitives is a roadmap item, not a hint.
 
+## Operating a store — configuration, maintenance, backup, cancellation, the queue
+
+Everything an operator does to a production SQLite database is a typed
+operation with a capability, a cancellation and an error class; none of
+it needs raw SQL or the raw handle. The rules, in one place:
+
+- **Configuration is a closed, validated set, read back.** Eight
+  connection pragmas are `openStore` options — `busyTimeout`,
+  `journalMode`, `synchronous`, `walAutocheckpoint`, `journalSizeLimit`,
+  `cacheSize`, `mmapSize`, `tempStore` — validated before anything
+  reaches SQL. An option naming any other pragma is refused (`JD0006`),
+  one the driver or the store kind cannot apply is refused (`JD0007`),
+  and after the open every declared pragma is read back:
+  `store.capabilities.pragmas` carries the values the connection
+  actually has, and an explicitly requested value the engine did not
+  take refuses the open (`JD0008`) rather than leaving a store that
+  believes a configuration it does not have.
+- **Maintenance is four typed operations under the store gate** —
+  `checkpoint({ mode })`, `integrityCheck({ limit })`, `foreignKeyCheck()`,
+  `optimize()` — each answering SQLite's own row as typed data, refused
+  by code (`JD2077`) exactly where `capabilities.maintenance` says
+  `false` (a read-only store for the two that write; a binding that
+  declares one absent). Corruption an integrity check finds is its
+  RESULT, never a throw.
+- **A backup is published whole or not at all.** `backupTo(path)` copies
+  a live store while writers proceed, into a temporary sibling in the
+  same directory, and renames it onto the target only once the platform
+  reported the copy complete; a cancelled (`JD2079`) or failed copy
+  leaves neither the target nor the temporary file. Where it goes, how
+  it is named, rotated or encrypted is the host's.
+- **Cancellation is honoured where the driver can honour it, and the
+  report says where.** `capabilities.cancellation` states the
+  granularity per lifecycle — `query: 'row'`, `queue: true`, `migration:
+  'step'`, `maintenance: 'statement'`, `backup: 'page'`, `midStatement:
+  false` — and every operation with more than one unit of work takes
+  `{ signal, deadline }` on the store's injected clock. A cursor over a
+  binding with no lazy iterator says `streaming: 'buffered'` with a
+  driver barrier instead of a row stream it cannot deliver.
+- **One classification of driver failures.** A locked, full, read-only,
+  corrupt or unopenable database arrives under one code with a stable
+  `class` and a `retryable` verdict from every path alike (`JD2005`
+  busy, `JD2082`–`JD2085`; `JD0002` at open), the driver's error as
+  `cause`; a pushed integer aggregate past int64 is answered by the
+  engine as the coded residual it always was elsewhere.
+- **The queue is administrable, never scheduled.** `store.jobs.page`,
+  `cancel` (through the lease fence), `requeue` and `sweep` (with a
+  required horizon) are mechanisms; WHEN to sweep or cancel is the
+  host's call, and priority classes stay a documented non-goal.
+
+```js
+import { openStore } from '@jarenjs/db';
+import { nodeDriver } from '@jarenjs/db/node';
+
+const store = await openStore(model, {
+  driver: nodeDriver(), path: 'app.db', jobs: true,
+  synchronous: 'normal', cacheSize: -8000, walAutocheckpoint: 250,
+});
+// the values the CONNECTION has, read back — not the request
+const { journalMode, synchronous } = store.capabilities.pragmas;
+
+const checkpoint = await store.checkpoint({ mode: 'truncate' });   // { busy, logFrames, checkpointedFrames }
+const health = await store.integrityCheck();                        // { ok, problems }
+const copy = await store.backupTo('backups/app.db', {
+  rate: 64,
+  onProgress: ({ totalPages, remainingPages }) => report(totalPages - remainingPages, totalPages),
+  signal: controller.signal,                                        // JD2079 between pages, nothing left behind
+});
+
+for await (const job of store.jobs.page({ state: 'failed', kind: 'mail' })) await store.jobs.requeue(job.id);
+await store.jobs.sweep({ settledBefore: Date.now() - 7 * 24 * 3600 * 1000 });
+
+try {
+  await store.collection('users').insert(user);
+}
+catch (error) {
+  if (error.class === 'busy' && error.retryable) scheduleRetry(); // one class, whichever path met it
+  else throw error;
+}
+```
+
+The normative contract is [MODEL-FORMAT](docs/MODEL-FORMAT.md) §4 (the
+pragma set, the maintenance and backup rules, the cancellation report)
+and §7 (the codes and the classifier); the queue's administration is
+[JOBS-FORMAT](docs/JOBS-FORMAT.md) §10; a migration's cancellation and
+its side-effect-free status read are in
+[MIGRATION-FORMAT](docs/MIGRATION-FORMAT.md) §6.
+
 ## What this is not — every non-claim in one place
 
 - **SQLite only.** One backend (3.45+); the dialect seam is tested
@@ -774,9 +1281,10 @@ replication on these primitives is a roadmap item, not a hint.
   horizon a view claims and is checked against the window it maintains;
   the maintained state is still bounded by `live.maxMaintained`, and no
   version of this compacts a bucket's rows away.
-- **The wasm build journals** (its session extension is not yet
-  adapted); OPFS needs a secure context, and where it is absent the
-  store runs in memory with the durability difference stated.
+- **Browser storage is probed.** The canonical wasm build supports session
+  capture after a disposable live probe. Failed session probes select journal
+  capture. OPFS, IndexedDB snapshots and memory have explicit capability and
+  durability differences; see [execution hosts](docs/HOSTS.md).
 - **Named future work, not silent gaps**: `$groupby` pushdown beyond
   the `$time-bucket` ladder, a many-to-many hop on the chain, membership
   on an auto-keyed pending insert, incremental joins, other SQL dialects,
@@ -792,3 +1300,27 @@ profile §8, entities §9, relational translation §10, the unit of work
 queue §§1–9); the seams, the pushdown contract and every engine are in
 [ARCHITECTURE.md](ARCHITECTURE.md); the benchmark methodology is in
 [benchmark/README.md](../../benchmark/README.md).
+
+## Exports
+
+Every subpath a consumer can import, derived from the manifest by
+`npm run docs:derive` (`npm run docs:check` fails when the two drift):
+
+<!--fact:exports.db-->
+| Import | Kind | Declarations |
+|---|---|---|
+| `@jarenjs/db` | JavaScript | declared |
+| `@jarenjs/db/node` | JavaScript | declared |
+| `@jarenjs/db/postgres` | JavaScript | declared |
+| `@jarenjs/db/bun` | JavaScript | declared |
+| `@jarenjs/db/wasm` | JavaScript | declared |
+| `@jarenjs/db/typed` | JavaScript | declared |
+| `@jarenjs/db/app` | JavaScript | declared |
+| `@jarenjs/db/schemas/jaren-migration.draft-07.schema.json` | schema | — |
+| `@jarenjs/db/schemas/jaren-migration.schema.json` | schema | — |
+| `@jarenjs/db/schemas/jaren-model.draft-07.schema.json` | schema | — |
+| `@jarenjs/db/schemas/jaren-model.schema.json` | schema | — |
+| `@jarenjs/db/package.json` | metadata | — |
+| `@jarenjs/db/node-worker` | JavaScript | declared |
+| `@jarenjs/db/node-pool` | JavaScript | declared |
+<!--/fact-->