@jarenjs/db 0.49.2 → 0.66.1

package/docs/MODEL-FORMAT.md

@@ -163,9 +163,9 @@ Three things follow, and none of them is optional:
   per-mapping cell.
 
 **What it costs, both halves** (`benchmark/spatial.js`, the store's own
-rows over 50 000 points): the same `$within` measures <!--bm:spatial.rtreeStore-->0.46 ms against 2 ms — 4.3× in the R\*Tree's favour<!--/bm-->, and loading them
-costs <!--bm:spatial.rtreeLoad-->718 ms against 399 ms for 50,000 documents in one transaction — 1.8× the write cost<!--/bm-->. Isolated from the store on a raw
-connection, the same probe is <!--bm:spatial.rtree-->0.3 ms against 1.9 ms — 6.4× in the R\*Tree's favour<!--/bm-->. Read speed bought with write cost and a
+rows over 50 000 points): the same `$within` measures <!--fact:spatial.rtreeStore-->0.46 ms against 2 ms — 4.3× in the R\*Tree's favour<!--/fact-->, and loading them
+costs <!--fact:spatial.rtreeLoad-->718 ms against 399 ms for 50,000 documents in one transaction — 1.8× the write cost<!--/fact-->. Isolated from the store on a raw
+connection, the same probe is <!--fact:spatial.rtree-->0.3 ms against 1.9 ms — 6.4× in the R\*Tree's favour<!--/fact-->. Read speed bought with write cost and a
 second table: choose it deliberately, per index, which is why it is
 neither automatic nor a store-wide option.
 
@@ -198,11 +198,11 @@ Three things follow:
 
 **What it buys, and what it costs.** Measured against the same query
 over a collection with no such column — the whole embedding parsed out
-of the stored JSON per row — the column is worth <!--bm:vector.jsonDoc-->15.0× the plan at 10,000 × 768<!--/bm-->
-on the read, and costs <!--bm:vector.write-->10.6 s against 5.0 s for 50,000 documents in one transaction — 2.1× the write cost<!--/bm-->
+of the stored JSON per row — the column is worth <!--fact:vector.jsonDoc-->15.6× the plan at 10,000 × 768<!--/fact-->
+on the read, and costs <!--fact:vector.write-->10.2 s against 4.9 s for 50,000 documents in one transaction — 2.1× the write cost<!--/fact-->
 on the way in, because every write pays a JSON round trip of the member
 plus the normalize and the pack. On
-disk it is <!--bm:vector.storage-->3,072 B packed against 16,141 B as a JSON number array inside the document — 5.3× smaller<!--/bm-->
+disk it is <!--fact:vector.storage-->3,072 B packed against 16,141 B as a JSON number array inside the document — 5.3× smaller<!--/fact-->
 per vector — smaller than the member, and *added* to it, since the
 document still carries what the column is derived from. Choose it the
 way `physical: 'rtree'` is chosen: per index, with both halves in view
@@ -465,6 +465,19 @@ raise. The promotion therefore requires the schema to type the member
 as an array or an object and nothing else; a store that wants the
 engine's refusal instead keeps `compileSchema` injected.
 
+**The same rule, for an interval.** `$overlaps` (§8.16) promotes over a
+member the schema types as an object whose `start` and `end` are both
+REQUIRED and both numeric — and only numeric, since an RFC 3339 bound
+is a good instant to the engine and no epoch column compares against
+it. Under that declaration a bound that is absent, textual or `null` is
+a row the collection cannot hold, so the pushed comparison cannot swallow
+a refusal the engine would have raised. One malformed case remains
+declarable by no schema keyword — a span whose `end` is at or before its
+`start` — so the statement keeps every one of those rows and the operator
+raises over them, exactly as it would have. Both bounds must map to
+declared columns; an unmapped pair pushes nothing and `strict: true`
+names it (`JD0010`).
+
 Under `physical: 'rtree'` the same rule is enforced in SQL, by the
 `WHEN <stem>_w IS NOT NULL` guard on the sync triggers: **a document
 with no bounded position is ABSENT from the virtual table**, so the
@@ -553,6 +566,11 @@ the derived-column mapping branches on (§3.1), so a model that declares
 a spatial index is portable across all three drivers and the physical
 shape it produces is not.
 
+Closing a Bun connection finalizes its live prepared statements before
+closing the database, so releasing a file does not wait for garbage
+collection. Statement tracking uses weak references and does not retain
+past queries for the connection's lifetime.
+
 `rtree` is read from the library's compile options (`ENABLE_RTREE`) and
 is the second mapping branch: a `derive: 'bbox'` index that declares
 `physical: 'rtree'` (§2.1) opens on a build without the module as the
@@ -582,12 +600,96 @@ composition is sync-capable and adds none); the measured difference is
 the price of portability, published with the benchmarks rather than
 waved away.
 
-**Concurrency defaults are decided here.** A file-backed store opens
-with `PRAGMA busy_timeout` set to **5000 ms** and journal mode
-**WAL**, both overridable through `openStore`'s `busyTimeout` and
-`journalMode` options; `:memory:` stores set neither. The values in
-effect are visible on `store.capabilities.busyTimeoutMs` and
-`store.capabilities.journalMode` (`null` for in-memory stores).
+**Connection configuration is a closed, validated set, read back
+after it is applied.** `openStore` configures exactly eight
+connection pragmas, each by its own option: `busyTimeout` (ms,
+default **5000**), `journalMode` (`delete` | `truncate` | `persist` |
+`memory` | `wal` | `off`, default **`wal`** on a writable file),
+`synchronous` (`off` | `normal` | `full` | `extra`), `walAutocheckpoint`
+(pages, `0` disables), `journalSizeLimit` (bytes, `-1` for none),
+`cacheSize` (pages, or negative KiB), `mmapSize` (bytes) and
+`tempStore` (`default` | `file` | `memory`). An option naming any
+other pragma is refused `JD0006` — `foreign_keys` among them, which the
+model requires ON and verifies per connection — and a value outside a
+pragma's set is API misuse. A driver's capability table declares the
+pragmas its binding applies (`configurablePragmas`); a request outside
+that declaration is `JD0007`, as is an explicit `journalMode` on a
+read-only store, whose journal-mode write the engine refuses. After the
+open sequence every declared pragma is read back and the read values
+are what `store.capabilities.pragmas` carries; a requested value the
+engine did not take is `JD0008` and the store does not open. A
+`:memory:` database keeps journal mode `memory` whatever is asked and
+answers nothing for `mmap_size`, so those two are not written there and
+the report says what the engine answers (`'memory'`, `null`).
+`store.capabilities.busyTimeoutMs` and `store.capabilities.journalMode`
+are the same two read-back values under their long-published names.
+
+**Maintenance is a typed operation, never raw SQL.** Four store members
+run what an operator runs on a production database, each under the
+store gate (so none interleaves an in-flight write) and each answering
+the engine's own row as typed data: `checkpoint({ mode })` runs
+`PRAGMA wal_checkpoint` (`passive` | `full` | `restart` | `truncate`,
+default `passive`) and answers `{ busy, logFrames, checkpointedFrames }`
+— the engine's numbers, `-1` on a database that is not in WAL mode; a
+second passive checkpoint reports the same counts as the first (the
+frames stay in the log until a writer restarts it) and a second
+`truncate` reports zeros. `integrityCheck({ limit })` answers
+`{ ok, problems }`, the engine's rows verbatim — corruption is the
+result, never a throw. `foreignKeyCheck()` answers
+`{ ok, violations: [{ table, rowId, parent, fkid }] }`. `optimize()`
+answers `{ ran: true }`, because `PRAGMA optimize` reports nothing and
+this store invents no statistics. `store.capabilities.maintenance`
+carries one boolean per operation: `false` where the driver's binding
+does not declare it and, for `checkpoint` and `optimize`, on a
+read-only store (the engine would answer a checkpoint there with a
+silent no-op) — and a call is refused `JD2077` exactly where the report
+says `false`. A driver failure inside an operation is `JD2078` with
+the original as `cause`. None of them touches the change log's durable
+watermark (LIVE-FORMAT §5).
+
+**A backup is published whole or not at all.** `backupTo(targetPath,
+{ rate, onProgress, signal, checkpoint })` copies a live store through
+the platform's online-backup API — writers proceed meanwhile — and
+answers `{ path, pages, checkpoint }`. The copy is written to a
+temporary sibling of the target (`<target>.jaren-tmp-<suffix>`, in the
+same directory so the rename is one file system's) and renamed onto the
+target only once the platform reported the copy complete; a
+cancellation (`JD2079`, honoured between pages at the `rate` the
+platform reports progress — the API takes no signal, so the check runs
+in its progress callback), a copy failure or a rename failure removes
+the temporary file and leaves the target untouched. A `checkpoint`
+mode (default `passive`; `false` skips it, and a read-only store skips
+it by default) fixes the snapshot boundary first, under the store gate.
+Progress events are the platform's `{ totalPages, remainingPages }`
+verbatim, and the last one may still carry a remainder: the platform
+emits no zero event, completion is the resolved copy. The capability is
+`store.capabilities.maintenance.backup` — the Node binding's; every
+other binding reports `false` and refuses `JD2077`. What is NOT
+decided here: where backups go, how they are named, encrypted, rotated
+or retained — the host's policy.
+
+**Cancellation is honoured where the driver can honour it, and the
+report says where.** Every operation that runs more than one unit of
+work takes `{ signal, deadline }` and checks them BETWEEN units, on the
+clock the store's runtime record supplies — never inside a statement,
+because no shipped SQLite binding exposes an interrupt.
+`store.capabilities.cancellation` states the granularity per
+lifecycle: `query: 'row'` (a call before it runs, a cursor or page at
+every row boundary — `JD2072`), `queue: true` (a call still waiting for
+the open transaction leaves the queue — `JD2064`), `migration: 'step'`
+(between migrations, between steps and between the batches of a data
+step — `JD2080`; the migration in flight rolls back whole), `maintenance:
+'statement'` (before the one statement each operation issues —
+`JD2081`), `backup: 'page'` (between the pages the platform reports —
+`JD2079`), and `midStatement: false` — a filled slot, not an absent
+one; a driver that grows an interrupt flips exactly that member. A
+passed deadline is `JD2075` in every lifecycle. A cursor's own report
+is part of the same honesty: `capabilities.lazyIteration` is probed at
+open, and on a binding whose statements carry no lazy iterator (the
+driver composes `iterate` over `all()`) every cursor reports
+`streaming: 'buffered'` with a `{ construct: 'driver' }` barrier,
+`explain()` says the same, and `strictStreaming` refuses (`JD0037`) —
+never a row stream the driver cannot deliver.
 
 The runtime builtin behind a binding is imported lazily inside
 `open()` — never at module scope — so every driver subpath loads under
@@ -617,6 +719,15 @@ returns a validation function; the function returns `true`/`false` or
 and `store.capabilities.validated === false` — a declared downgrade.
 The cost of running without one: the database constraints only see the
 key and the indexed members; everything else is stored as given.
+Stated more sharply, because it changes ANSWERS and not only what is
+stored: a typed generated column carries SQLite affinity, so a value
+that violates the collection schema — the string `'020'` under an
+`integer` path — reads as the integer `20` in the column while the
+document still holds text, and a pushed `$eq: ['$it.n', '20']` finds
+a row the engine, which compares the JSON value, does not. On an
+unvalidated store the native and residual paths agree only over
+documents that conform to the schema; with the hook injected no other
+document is ever stored.
 `@jarenjs/db` never runs a validator of its own; what it imports from
 `@jarenjs/validate` is only the pure same-document `$ref`/`$anchor`
 resolution in `@jarenjs/validate/normalize`, for model compilation.
@@ -639,6 +750,18 @@ and may itself call `transaction`; each level is one savepoint. A
 throw rolls back exactly its own level and rethrows — an outer
 transaction that catches the error continues and its own work
 commits. There is no implicit retry.
+If `COMMIT` or `RELEASE` itself fails, for example on a deferred foreign
+key constraint, that level rolls back before another caller acquires
+the connection. A rollback failure accompanies the original failure in
+an `AggregateError`, retaining the primary failure's code, class and
+driver cause when the store classifies it.
+
+**On an asynchronous driver a refused write rejects.** Every write —
+`insert`, `put`, `patch`, `delete`, the entity set's `create`/`update`/
+`delete` and the queue's `enqueue` — answers its coded error (`JD2001`,
+`JD2003`, `JD2005`, …) through the promise it returned: never a
+synchronous throw, and never an unhandled rejection beside a result
+that looks like success.
 
 ### 5.1 Transaction ownership
 
@@ -653,39 +776,209 @@ So a **top-level transaction owns its connection until it settles**, and
 an overlapping one waits its turn. Two concurrent request handlers
 sharing a store both commit, and both report success.
 
+**The store the callback receives is the transaction.** `tx.collection`,
+`tx.entity`, `tx.sync`, `tx.jobs` and `tx.saveChanges()` run as the
+transaction's owner, and `tx.transaction()` nests through its savepoint:
+
+```js
+await store.transaction(async (tx) => {
+  await tx.collection('docs').put(doc, 'a');     // inside this transaction
+  await tx.transaction(async (inner) => {
+    await inner.collection('docs').put(other, 'b');  // nested savepoint
+  });
+});
+```
+
+**A root transaction may take the write lock up front.**
+`store.transaction(fn, { mode: 'immediate' })` begins with `BEGIN
+IMMEDIATE` instead of a deferred savepoint. A body that reads before it
+writes — a ledger claim: read the record, decide, insert — otherwise
+meets the read→write upgrade `SQLITE_BUSY` when another connection
+commits between its read and its write, the one busy the busy handler
+cannot retry; with the lock taken first that wait is an ordinary busy
+wait the `busyTimeout` covers, and two processes claiming one key see
+one `new`. The default `'deferred'` is unchanged, `tx.transaction()`
+inside either mode is a savepoint, `signal` and `unitOfWork` behave the
+same, and the synchronous twin has no mode. The open path already
+brackets every first-open object — collection, entity and join tables,
+indexes, the change log and its state row, the job tables — the same
+way (§2.4).
+
+**A transaction handle lives exactly as long as its own scope.** Every
+`tx` view is pinned to the exact scope that created it, and every
+stateful member — connection work, unit-of-work bookkeeping like
+`add()`, `tx.stats()`, a lazy `query()` cursor's `next()` — checks that
+pin before reading tracker state or issuing a statement. A handle
+retained past its callback, or an OUTER handle used while an async
+inner savepoint is current, refuses **`JD2070`** naming the live
+callback's handle as the fix; it never falls through to the root and
+never follows a newer scope. Inside an inner transaction, use the inner
+callback's own handle (synchronous nesting is unaffected — nothing can
+interleave while a synchronous body is on the stack). `tx.stats()`
+reports the work captured by its exact scope, and root `store.stats()`
+always reports the root's, whichever scope happens to be current.
+
+**A transaction view does not own the store lifetime.** The view
+carries no `close` member, at runtime or in the declarations: closing
+the connection under the view's own savepoint could only corrupt, so
+the root store (or client) remains the only owner of connection
+lifetime.
+
+**Jobs have the same two spellings.** Root `store.jobs.*` finite calls
+(and every worker's own claim/renewal/checkpoint/settlement I/O, no
+matter where the worker was created) take the store gate, so an
+unrelated job write can never join an open application transaction's
+fate. `tx.jobs.*` runs as the exact scope — the transactional-outbox
+spelling: an enqueue or settlement there co-commits with the domain
+transaction and rolls back with it. A checkpoint store keeps the
+root-or-scope ownership of the jobs view that created it.
+
+**Capture is transparent to transaction options.** `{ capture: true }`
+changes how committed records are translated, never queue cancellation
+or tracker ownership: `store.transaction(fn, { signal, unitOfWork })`
+behaves identically with and without capture — an aborted queued
+callback still never runs (`JD2064`), and `unitOfWork: 'own'` still
+gives the callback a tracker of its own without consuming the root's
+pending state.
+
 Nesting is asked for in one of two ways, and the difference is not
 cosmetic:
 
 - **Synchronously** — a `transaction` called while an owning callback is
   still on the stack nests, because nothing can interleave there. This is
-  `store.sync.transaction` inside `store.sync.transaction`.
+  `store.sync.transaction` inside `store.sync.transaction`, and it is why
+  a store-level synchronous call inside a synchronous callback runs as the
+  owner rather than waiting.
 - **Through the scope** — an `async` callback has already awaited, so the
   stack cannot say whether a request is its own nested work or an
-  unrelated caller. Nest through the store the callback RECEIVED:
+  unrelated caller. Nest through the store the callback RECEIVED.
+
+**A store-level handle is never inside the transaction.** `store.collection`,
+`store.entity`, `store.saveChanges()`, `store.execute`, `store.dataVersion`
+and the whole `store.sync` surface hold the connection for their own
+extent, so their statements cannot fall inside a transaction they are not
+part of and share a rollback they know nothing about. One store is
+therefore safe for a handler per request: an unrelated writer waits for
+the commit and keeps its own fate.
+
+What that costs, stated plainly:
+
+- A store-level call made while another caller's transaction is open
+  **waits** on the connection's gate, under `queueTimeout` (default 5 s,
+  the busy-timeout default). `openStore(model, { transactions: 'strict' })`
+  refuses at once instead, for a host that would rather see the contention
+  than pay for it.
+- A store-level call **awaited from inside its own transaction** is a
+  self-wait: the store cannot tell it from an unrelated caller, so it
+  queues and, at `queueTimeout`, becomes `JD0012` whose message names
+  `tx.collection` / `tx.entity` / `tx.entities` as the fix. Bounded and
+  named, never a hang.
+- `store.transaction(fn, { signal })` abandons a call that is still
+  **queued** — the callback never runs, and `JD2064` says so. A
+  transaction that has already taken the connection runs to its own end.
+- A store-level **cursor** — `collection.query()`, `entity.cursor()`,
+  `entity.loadCursor()` — takes the gate **per pull**, not for its life:
+  constructing it touches no connection, each `next()` holds the
+  connection for exactly the source work one item needs (the first pull
+  prepares and opens the statement) and releases before it settles, and
+  `return()` is admitted the same way — a release the gate refuses (a
+  contended `'strict'` store, a queue timeout) still resets the statement
+  off-gate and answers `{ done: true }`, and an abort resets it at once,
+  because a statement left open until a stranger commits is the worse
+  outcome. So a consumer paused between pulls blocks no transaction, and
+  a pull made while one is open waits for its commit and observes
+  committed state only — never a row a stranger's transaction later rolls
+  back. Every cursor iterates a statement of its own, so two cursors over
+  one document never invalidate each other. A pull abandoned while queued
+  is `JD2064`; an aborted cursor is `JD2072` at its row boundary; a
+  passed deadline is `JD2075`; a settled cursor answers `{ done: true }`
+  whatever the clock or the gate say. A transaction view's cursors are
+  pinned to their exact scope instead (`JD2070`), as above.
+- `store.live()` and `collection.live()` register **under the gate through
+  their initial query**: the registration is local but the first result is
+  a statement, so it waits for an open transaction like every other
+  store-level read and never publishes rows that transaction rolls back
+  (LIVE-FORMAT §7). A registration that is refused leaves no live query
+  behind. A live query registered from INSIDE a transaction (`tx.live`,
+  `tx.collection(name).live`) initializes from that transaction's rows and
+  shares its fate: committed, it stays and is maintained; rolled back, it
+  is closed with the rows that never existed.
+
+**A unit of work's fate is its transaction's.** A tracked `saveChanges()`
+inside a transaction writes its statements immediately — inside the
+transaction the database does hold them, and every later read, plan and
+optimistic guard in that unit of work agrees with that. What waits for
+the commit is the right to *keep* the advance: if the enclosing
+transaction rolls back, the tracker's snapshots are withdrawn to what
+they were before the save, so a caller's retry plans the same statements
+again instead of reporting a success it never had. A nested savepoint
+that rolls back withdraws only what was registered inside it.
+
+`@jarenjs/linq/db` projects all of this: `client.transaction(async (tx) =>
+…)` hands the callback a typed client whose `tx.entities.X` and
+`tx.collections.Y` are the transaction's, with a unit of work of its own
+by default so two handlers never see each other's pending state
+(`unitOfWork: 'shared'` opts back into the client's). The typed client
+forwards `tx.savepoints` (§5.2) unchanged, and `tx.store` is the
+underlying `TransactionStore`.
+
+### 5.2 Named savepoints: partial rollback without a sentinel exception
+
+Structured nesting already gives partial rollback around a callback: an
+inner `tx.transaction(fn)` is one savepoint, and an outer callback that
+catches its error continues. What it cannot express is
+checkpoint-and-continue from a LATER point without throwing for control
+flow. A live transaction view carries that as `tx.savepoints`:
 
-  ```js
-  await store.transaction(async (tx) => {
-    await store.collection('docs').put(doc, 'a');   // joins this transaction
-    await tx.transaction(async () => { … });        // nests inside it
-  });
-  ```
-
-  Reaching back through the outer `store.transaction` from inside a
-  callback queues behind the transaction the caller is part of, so it
-  waits for itself; after `queueTimeout` (default 5 s, the busy-timeout
-  default) that becomes `JD0012` naming the fix rather than hanging.
-
-**One residual, stated plainly.** A bare statement issued while a
-transaction is open JOINS that transaction and shares its fate, because
-SQLite has no per-statement transaction scope and every operation inside
-a callback reaches the connection the same way an unrelated caller does.
-Work that must be in the transaction is therefore safe; an unrelated
-writer on a SHARED store is not. Give each concurrent writer its own
-store when independent writes must not share a rollback. Closing this
-— scope-bound `tx` handles, with store-level calls waiting on the gate
-while a foreign scope is open — is an open ROADMAP item (`@jarenjs/db`,
-"Strong same-store transaction ownership"); until it lands, one store
-shared by independent request handlers is unsafe for bare writes.
+```js
+await store.transaction(async (tx) => {
+  await tx.savepoints.create('before-optional-import');
+  await tx.collection('docs').put(optionalDoc, 'optional');
+
+  if (!accepted) {
+    await tx.savepoints.rollbackTo('before-optional-import');
+    // the checkpoint remains active and may be rolled back to again
+  }
+
+  await tx.savepoints.release('before-optional-import');
+});
+```
+
+The synchronous twin is `tx.sync.savepoints`, answering values. Root
+`Store`, root `Client`, workers and checkpoint stores expose **none** of
+it: only the transaction that owns the connection may move its stack,
+and a stale or cross-scope view is `JD2070` before any label is even
+looked at.
+
+- **The label never reaches SQL.** It is a map key and diagnostic for
+  that exact transaction; the driver generates the same monotonic
+  `jaren_sp_*` identifier structured nesting uses, so both savepoint
+  kinds share one engine stack and cannot cross-release one another. A
+  structured inner transaction gets its own exact namespace — it cannot
+  target an outer label, and the `JD2070` rule keeps the outer view
+  from destroying an async inner savepoint.
+- **A blank, duplicate or unknown label is `JD2071`**, raised before
+  any statement, so the database and the settlement/capture marks are
+  untouched.
+- **`rollbackTo` follows the engine's semantics exactly.** The target
+  savepoint stays active (a second rollback to it is defined) while
+  every checkpoint created after it is invalidated; the rows after the
+  target are gone. In-memory effects follow the database: settlement
+  effects registered after the checkpoint run their rollback halves in
+  reverse — a `saveChanges()` advance after the checkpoint is
+  withdrawn, its entity intention pending again, so a corrected
+  `saveChanges()` retries it (and an enclosing rollback still withdraws
+  that later advance). Direct collection writes and `tx.jobs` writes
+  are undone by SQLite itself. Session capture observes the engine's
+  final changeset; journal capture truncates to the checkpoint's mark —
+  the two modes agree.
+- **`release` keeps the rows.** It removes the target and every later
+  checkpoint without running rollback effects: those rows remain part
+  of the owning transaction, and their tracker withdrawals stay
+  registered until outer settlement. An outer commit or rollback
+  invalidates whatever names the callback left active.
+- No observer delivery or persisted capture record occurs before the
+  owning transaction commits, exactly as everywhere else.
 
 ## 6. Identity
 
@@ -717,16 +1010,24 @@ error.
 | code | raised when |
 |---|---|
 | `JD0001` | the SQLite library is below the supported floor |
-| `JD0002` | the declared model disagrees with the existing database |
+| `JD0002` | the existing database disagrees with the declared model, or the open failed in the driver |
 | `JD0003` | the driver binding is unavailable on this runtime |
 | `JD0004` | a declared index cannot be mapped to a column |
 | `JD0005` | the model document is invalid |
+| `JD0006` | an open option named a pragma this store does not configure |
+| `JD0007` | the pragma cannot be applied on this driver or store |
+| `JD0008` | a pragma did not take: the read-back disagrees with the request |
 | `JD0010` | strict mode refused a residual |
 | `JD0011` | the profile refused the document |
 | `JD0012` | work waited too long for the open transaction to settle |
 | `JD0030` | an unknown x-entity member was declared |
 | `JD0031` | relation declarations contradict each other |
 | `JD0032` | the include specification is invalid |
+| `JD0033` | an entity query names no entity array |
+| `JD0034` | a tracked cursor needs a bare entity return |
+| `JD0035` | the continuation does not belong to this ordering |
+| `JD0036` | a snapshot page needs an immutable ordering |
+| `JD0037` | strictStreaming refused a plan that buffers |
 | `JD0040` | the save spans a relation cycle |
 | `JD0050` | live queries require change capture |
 | `JD0051` | the demanded live mode is unavailable |
@@ -745,16 +1046,154 @@ error.
 | `JD2060` | the maintained live state exceeded its bound |
 | `JD2061` | another context owns the database |
 | `JD2062` | the store closed with job handlers still in flight |
+| `JD2063` | the store is closed |
+| `JD2064` | the call was aborted while it waited for the open transaction |
+| `JD2065` | the job is not leased — it is unknown, or already settled |
+| `JD2066` | the lease was superseded by a newer claim or renewal |
+| `JD2067` | the lease expired before the call |
+| `JD2068` | a settling call needs the lease the claim returned |
+| `JD2069` | a resumed run does not match the workflow or input it was checkpointed under |
+| `JD2070` | the transaction handle does not belong to the live scope |
+| `JD2071` | the savepoint label is blank, duplicate or unknown |
+| `JD2072` | the call was aborted before its next row |
+| `JD2073` | an include exceeded its per-root bound |
+| `JD2074` | an item exceeds the page byte bound |
+| `JD2075` | the deadline passed before the next unit of work |
+| `JD2076` | an item exceeds the profile byte bound |
+| `JD2077` | the maintenance operation is unavailable on this store |
+| `JD2078` | the maintenance operation failed |
+| `JD2079` | the backup was cancelled |
+| `JD2080` | the migration was cancelled between steps |
+| `JD2081` | the maintenance operation was cancelled |
+| `JD2082` | the database or its disk is full |
+| `JD2083` | the database is read-only |
+| `JD2084` | a disk I/O error |
+| `JD2085` | the database file is corrupt or not a database |
+| `JD2086` | a seek anchor came back with a type the plan did not declare |
+| `JD2087` | the connection to the database was lost |
+| `JD2088` | the transaction was aborted by an earlier failure in it |
+| `JD2089` | the statement was cancelled by the server |
+| `JD2090` | worker generation lost; reopen, never automatically replay; retryable only outside a transaction |
+| `JD2091` | bounded worker/pool admission overflow; retryable, with queue depth |
+| `JD2092` | a worker row, compatibility result or remote identity count exceeds its declared bound |
+| `JD2093` | malformed worker protocol request |
+| `JD2094` | invalid or uncommitted durable snapshot; reopen the last committed version |
 
 The table above is proven in sync with the runtime `DB_CODES` table by
 a test.
 
+**One classification of driver failures.** Every path that meets a
+driver error — a collection or entity write, the job queue, the query
+path, a maintenance operation, the backup, the open sequence —
+consults one table (`classifyDriverError`), so the same failure arrives
+under the same code with the same `class` and `retryable` verdict
+whichever path met it: `busy` (SQLITE_BUSY/LOCKED → `JD2005`,
+retryable), `full` (`JD2082`), `readonly` (`JD2083`), `io` (`JD2084`),
+`corrupt` (`JD2085`), `cantopen` and `constraint` (`JD2005`), `duplicate`
+(a UNIQUE collision on the key column → `JD2001`), `overflow` (a pushed
+integer aggregate past int64 — never raised: the query path re-runs the
+document in the engine and answers the double, and `explain().fallback`
+records it), and the fallback `error` (`JD2005`). A classified error
+carries `class`, `retryable` and the driver's error as `cause`; a
+lifecycle that owns its failure code (`JD2078` for maintenance and
+backup, `JD0002` at open) keeps the code and still carries the class.
+
+The ENGINE is discriminated by the evidence the error itself carries,
+never by a table threaded down from the caller: a SQLite binding
+attaches a numeric result code, a PostgreSQL one attaches a
+five-character SQLSTATE. Both land in the classes above, and three
+conditions a single-writer file database does not have get their own:
+`connection` (`JD2087`, retryable — SQLSTATE class 08 and the
+administrator's own terminations), `aborted` (`JD2088` — SQLSTATE
+`25P02`, a statement issued after an earlier failure inside the same
+transaction) and `cancelled` (`JD2089` — SQLSTATE `57014`). A
+serialization failure or a deadlock (`40001`, `40P01`) is `busy` and
+retryable, which is the same verdict, and the same caller branch, a
+locked SQLite file gets.
+An engine error thrown inside a pushed user function (`JQ…`) is not a
+driver error: it passes through untouched, relocated onto the caller's
+document path (`/$where/…`, never the hatch's `/$return/…`).
+
+## 7A. Model-declared index expressions
+
+An index may name a computation instead of a member:
+
+```json
+{
+  "name": "by_lower_email",
+  "expression": { "call": "lower", "args": [{ "member": "$.email" }] },
+  "unique": true
+}
+```
+
+`expression` is mutually exclusive with `path` and with `derive`
+(`JD0004`): an expression names the members it reads itself, and a
+derived spatial column IS an expression this format spells for you.
+
+**The vocabulary is closed — three node kinds and no fourth**, and none
+of them is SQL text:
+
+| node | meaning |
+|---|---|
+| `{ "member": "$.a.b" }` | a singular JSONPath expression into the stored document |
+| `{ "value": 1 }` | a JSON string, number or boolean. A `null` or a compound has no place in an index expression |
+| `{ "call": "lower", "args": [ … ] }` | a function the HOST declared, applied to its arguments in order |
+
+Argument order is significant: `sub(a, b)` and `sub(b, a)` are
+different expressions and different columns. An expression nests at
+most eight deep.
+
+**A function is DECLARED by the host, never created by the store.**
+`openStore(model, { expressions })` takes one declaration per name:
+
+```jsonc
+{
+  "lower": {
+    "arity": 1,
+    "deterministic": true,           // required, and never inferred
+    "apply": (value) => …,           // an engine that registers functions calls this
+    "sql": "lower"                   // one that cannot calls this IMMUTABLE function
+  }
+}
+```
+
+Why a declaration rather than an escape hatch: **an index over a
+function is a schema dependency.** A database whose column is computed
+by `lower(…)` cannot be written from a connection that has no `lower`,
+and a raw-SQL index would have had exactly that hazard with none of the
+checking. Here the model names the function, every store that opens the
+model is handed the same declaration, and a store that cannot honour
+one refuses at open — `JD0004`, before a single statement:
+
+- a name this store was not given
+- an arity the expression does not match
+- a function not declared `deterministic`
+- no `apply` where the engine computes the value itself
+- no `sql` name where the engine calls its own — and that name is an
+  identifier, never SQL text
+
+**How each engine computes it.** SQLite registers `apply` as a
+deterministic function under a namespaced name (`jaren_x_lower`) — so a
+model's `lower` never shadows the engine's own — and the column is
+`GENERATED ALWAYS AS (jaren_x_lower(<member>)) VIRTUAL`. PostgreSQL
+registers nothing: the column is `GENERATED ALWAYS AS (lower(<member>))
+STORED` over the immutable function the host promised the server has.
+Both read the member as its own SCALAR, so `lower` of a string is the
+same answer on both.
+
+One column serves every index that declares the same canonical
+expression, and the canonical form — order-preserving — is what the
+shape hash and the migration diff read. `store.introspect()` reads the
+expression back out of the SQL the dialect wrote (each dialect reads its
+own), so a declared expression index survives the round trip; without
+the declarations the column is REPORTED as unmapped rather than guessed.
+
 ## 8. The safe execution profile
 
 A query document that arrives from a tenant, a remote client or a
 language model can reach a database. Parameter binding makes injection
 structurally impossible; it does nothing about resource exhaustion or
-cross-tenant reads. A **profile** composes four independent bounds:
+cross-tenant reads. A **profile** composes five independent bounds:
 
 ```js
 const store = await openStore(model, { driver, profile: 'safe' });
@@ -763,10 +1202,98 @@ collection.query(doc, { profile: { maxRows: 200, externals: ['min'] } });
 ```
 
 `'safe'` is the default table; a profile object overrides members over
-it. The defaults: engine limits
+it. A per-call `profile` REPLACES the store's for that call — it is
+normalized over the `'safe'` defaults, not over the store's profile —
+so a store-level mandatory predicate or allow-list does not carry into
+`execute(doc, { profile: { maxRows: 50 } })`: spell the whole profile
+per call, or set it once on the store and pass none. The defaults: engine limits
 `{ sequenceItems: 100000, resultItems: 10000, steps: 1000000, depth: 32 }`,
 `maxRows: 1000`, no externals, no host functions, no collations, all
-of the store's collections, no mandatory predicates, no scan refusal.
+of the store's collections, no mandatory predicates, no scan refusal,
+and no graph caps (`maxIncludedRows`, `maxDepth`, `maxBytes` all
+`null`), and no member allow-list (`members: null`).
+
+**One profile, every engine.** A profile — the store's, or the call's
+through `ExecuteOptions.profile` on `execute`, `query`, `cursor`,
+`loadCursor`, `page` and `explain` alike — applies identically to
+collection execution, entity execution (`entity.execute`, the chain's
+cursor), graph loading (`load`, `loadCursor`, `page`, every include
+subquery) and store-root execution (`store.execute`). `collections` is
+the one allow-list and names collections AND entity roots; a document
+that reads a name outside it is `JD0011` on every engine, with the
+same reason. `predicates` is keyed by collection or entity name, and
+an entity's predicate is conjoined into every fetch of that entity —
+the native statement, each root the residual fetches, the load's root
+and every include subquery over that entity. `maxRows` bounds every
+fetch on every engine (`JD2007`), the residual's input rows included:
+each root an entity residual fetches carries `LIMIT maxRows + 1`. The
+graph caps are hard maxima an include's own declaration cannot exceed:
+`maxIncludedRows` refuses an include that declares more rows per root
+(or `Infinity`), `maxDepth` refuses a deeper load, and `maxBytes`
+refuses any one item — a document, an entity row, a loaded root graph —
+larger than that many serialised bytes (`JD2076`).
+
+**The member allow-list.** `collections` says which roots a document
+may read; `members` says which MEMBERS of a root it may read. It is
+keyed by collection or entity name, and each value is a list in the
+model's own singular index-path spelling:
+
+```js
+collection.query(doc, { profile: {
+  members: { docs: ['$.id', '$.n'], User: ['$.id', '$.age'] } } });
+```
+
+A root the list does not name is unrestricted; a root the MODEL does
+not declare is `JD0011` before any statement runs, because a policy
+that applies to nothing is a policy failing open. Allowing a member
+allows everything UNDER it (`$.address` allows `$.address.city`) and
+none of its siblings (`$.address.city` does not allow `$.address`,
+which would answer the rest of the address). One collector reads every
+member path a document references — in `$where`, in `$orderby`, in
+`$return`, in a join condition, in a registered operator's operands —
+so a denial is the same `JD0011` wherever the member was named, and it
+names the root, the member and the place in the caller's document.
+
+Reading a root item WHOLE is refused, not narrowed: `$return: '$it'`,
+an alias of the binding through `$let`, and a wildcard with no singular
+prefix each answer members the list does not allow, and no list can
+cover them. For the same reason a graph `load()`, `page()` or
+`loadCursor()` over a policed entity is refused — it answers whole
+documents by definition — and the refusal names the members that ARE
+allowed, which the document query engine can project.
+
+**Enforced, or refused — never approximated.** A budget the engine
+can COUNT is enforced during execution: rows returned, rows
+materialised, residual-input rows, included rows per root, depth,
+bytes, and the engine limits. A budget SQLite cannot measure is
+refused at preflight on plan shape instead: `refuseFullScan` declines
+a native plan whose own `EXPLAIN QUERY PLAN` shows a full-table scan,
+and declines an entity residual outright, because the residual reads
+every row of every referenced root before the engine decides — that
+is a full-table scan by shape, so it is refused before any fetch
+rather than estimated. Visited-row and elapsed-time budgets exist
+only where a driver supplies a progress or interrupt hook; the
+shipped SQLite drivers supply neither, and `explain().budget` reports
+`time: 'unavailable'` and `estimatedRows: 'unavailable'` rather than
+a number nothing measured.
+
+**`signal` and `deadline`.** `ExecuteOptions.signal` cancels: a call
+already aborted issues no statement (`JD2072`), and a cursor or page
+releases its statement at the next row boundary. `deadline` is an
+epoch-millisecond instant checked before a statement runs and at
+every row boundary of a cursor or page (`JD2075`) — a row-boundary
+check, never a statement interrupt, for the reason above. The clock it
+is checked against is the store's runtime record's `now`
+(`@jarenjs/core/runtime`; the platform clock with no record), so a
+caller under an injected clock computes deadlines from that clock.
+
+**Provenance.** Every `explain()` — collection, entity, graph —
+carries `budget`: the profile that applied and from where (`{ source:
+'call' | 'store', name: 'safe' | 'custom' }`, or `null`), every bound
+it imposed (`rows`, `includedRows`, `depth`, `bytes`, `limits`), the
+scan verdict (`'refused-by-shape'` or `'unbounded'`), and the two
+driver slots by name (`time`, `estimatedRows`). A budget nobody can
+prove was applied is not a budget.
 
 1. **Engine limits.** The four engine limits ride into every residual
    compilation, so the JavaScript portion of a query is bounded by the
@@ -934,6 +1461,38 @@ to build one on — a crude guess would be dishonest. It pushes
 deterministically and this profile is published so the shape of the win
 is known; add a narrowing predicate or a `LIMIT` and the push pays.
 
+**`pushable: 'aggregate'` — the whole-sequence fold, in SQL.** A pack
+entry marked `'aggregate'` is lowered to a registered **SQL aggregate**
+where the driver has one (`capabilities.aggregateFunctions`): the plan
+emits `… SELECT jaren_a_<hash>(<the member's column>)`, SQLite drives
+the accumulation, and the SAME pure function the residual would call
+folds the values it collected. `$mean`, `$median`, `$variance` and
+`$stddev` of the statistics pack carry the token.
+
+The token is a promise about the FOLD, and three rules enforce it:
+
+- **order-insensitive.** A SQL aggregate visits rows in an order
+  nothing specifies, so only a summary whose value depends on the
+  multiset alone may be declared pushable.
+- **one sequence operand.** A SQL aggregate's final step sees only what
+  the row steps accumulated, so a second operand does not reach a fold
+  over zero rows. An entry declaring anything but a single
+  `'seq<number>'` operand and a `'number'` result is a `TypeError` at
+  `openStore`, naming the operator — loud, rather than a silent
+  non-promotion. `$percentile`, whose second operand is the percentile,
+  is therefore `pushable: false` and folds in the engine.
+- **a numeric member that cannot hold `null`.** SQL cannot tell a
+  stored `null` from an absent member and the engine's sequence can, so
+  the promotion needs the same schema-typed path the core `$sum` and
+  `$avg` need. An absent member contributes nothing on either side.
+
+A grouped fold is not promoted — a `$groupby` outside the fixed
+temporal bucket is engine work (§6) — and neither is an aggregate under
+a window. Both answer what the engine answers, and `explain()` names
+the reason. As with the scalar hatch, a profiled document triggers no
+registration: the same `$mean` under a profile folds in the residual,
+and `strict: true` refuses it by name (`JD0010`).
+
 **The same profile for a spatial predicate.** A `$within` against a
 LITERAL region takes the hatch only on a collection that declares **no**
 derived spatial index on the member: where one is declared the
@@ -945,15 +1504,15 @@ changing state. Measured on the same terms as the `$sqrt` rows
 mean of 20 executions after a warm one; the residual comparator
 pushes everything BUT the spatial conjunct):
 
-<!--bm:spatial.udfTable-->
+<!--fact:spatial.udfTable-->
 | shape | pushed (ms) | residual (ms) | verdict |
 |---|---|---|---|
 | solo `$within` over a full scan | 94 | 80 | ~even |
 | indexed `$eq` **and** `$within` (~5 % pass the index) | 5.7 | 52 | push **9.1×** |
 | `$within` with `LIMIT 10` | 1.9 | 77 | push **41.0×** |
-<!--/bm-->
+<!--/fact-->
 
-So the spatial hatch <!--bm:spatial.udfVerdict-->earns its row: 9.1× beside the selective conjunct and 41.0× under the LIMIT<!--/bm-->,
+So the spatial hatch <!--fact:spatial.udfVerdict-->earns its row: 9.1× beside the selective conjunct and 41.0× under the LIMIT<!--/fact-->,
 by the same rule as `$sqrt`: a sole `$within` over a full scan is a
 loss (the UDF re-parses every row in the callback, and the exact
 containment test is dearer than a square root), a `$within` beside
@@ -964,15 +1523,11 @@ it returns, which is faster than either column above.
 
 **The honest ceiling.** A `pushable:false` operator (a whole-series
 `$npv`, an `$sma`) is never a UDF — it stays the residual, `explain()`
-lists no `udfs` for it. Aggregate-UDF pushdown (`db.aggregate` step/final
-over `GROUP BY`) is **not emitted**: no shipped pack marks an entry
-`pushable:'aggregate'` (the finance/stats aggregators fold a *per-document*
-sequence — that is a per-row scalar to SQL, already covered by the scalar
-path where marked — not a cross-row column), and cross-row aggregate
-pushdown additionally waits on `$groupby` pushdown, itself a deliberate
-residual today. The `aggregateFunctions` capability is probed and
-reported regardless, so the day a pack marks `'aggregate'` the driver
-gate is already in place.
+lists no `udfs` for it, and neither does a `pushable:'aggregate'` entry
+whose shape the store refuses (above). A registered aggregate lowers
+only as the top-level fold of a whole selection: inside a `$groupby`'s
+`$return` the closed BUILT-IN set is what SQL groups by, and a
+registered summary there stays the engine's.
 
 ## 9. Entities, the `x-entity` vocabulary, relations
 
@@ -1013,7 +1568,10 @@ names:
 The schema stays a valid JSON Schema throughout: strip every
 `x-entity` member and it accepts and rejects exactly the same values
 (test-asserted over a corpus). The vocabulary is invisible to the
-validator by the same argument as `x-form`.
+validator by the same argument as `x-form`. A model document may also
+be written by code — `@jarenjs/linq/model`'s `defineModel()` emits
+exactly this document ([MODEL-PEN.md](../../linq/docs/MODEL-PEN.md)), and this section stays its
+one specification.
 
 ### 9.2 The `x-entity` vocabulary (a closed set)
 
@@ -1033,6 +1591,13 @@ happen, so this vocabulary is deliberately stricter than the
 validator's ignore-unknown posture — the strictness is local to the
 one namespace this package owns.
 
+The vocabulary is closed in POSITION as well as in name: `x-entity` is
+read on an entity's top-level properties (and through their `allOf`,
+`$defs` and `definitions` blocks) only. A block nested anywhere else —
+under a property's `properties`, `items`, `anyOf`, … — is never walked
+for mapping directives, so one found there is `JD0030` at its `docPath`
+rather than a key, an index or a relation that silently never existed.
+
 ### 9.3 The hybrid mapping
 
 Stated once, mechanically applied, and returned as data by
@@ -1042,7 +1607,8 @@ Stated once, mechanically applied, and returned as data by
 |---|---|
 | scalar (`string`/`number`/`integer`/`boolean`) at the top level | a real typed column |
 | `format: date-time`/`date` with `column: "integer"` | an epoch-milliseconds `INTEGER` column; the document keeps the RFC 3339 string, the column carries the derived epoch |
-| `enum` of scalars | a column plus a `CHECK (column IN (…))` |
+| `enum` of scalars | a column plus a `CHECK (column IN (…))` — a `null` member of the enum is left to the column's nullability, never written into the list |
+| a union of several scalar types (`['string', 'integer']`) | the JSONB document — a column has one affinity and a union has several; `['integer', 'null']` is that scalar, nullable |
 | nested object / array, or `column: "json"` | the JSONB document column, queryable by path exactly as in phase A |
 | relation | a foreign-key column, or a join table for many-to-many (§9.4) |
 
@@ -1052,13 +1618,39 @@ everything else; a read merges them back. **The absent-versus-null
 rule, plainly**: for a column-mapped scalar, JSON `null` and absence
 both store as SQL `NULL` and read back as ABSENT. A property that
 needs present-`null` semantics declares `column: "json"` and stays in
-the document.
+the document. The rule reaches the WRITE's return value, not only the
+read: `create()`, `update()` and `add()` answer the document a read
+would answer, so a `null` handed in for a column-mapped scalar is
+absent from what comes back — a returned object never names a member
+no read will show. An epoch column (§9.3's `column: "integer"` row)
+keeps its string in the document, present-`null` included.
 
 ### 9.4 Relations and referential integrity
 
 Declared on one side, inferred on the other; when both sides declare,
 the inverses MUST agree (`JD0031` on any contradiction).
 
+What counts as "the same edge" is decided by `via`, not by the pair of
+entity names: two declarations pair up when they name the same
+foreign-key property, and a pair is one `many` side and one `one`
+side. Two `many` sides, or two `one` sides, on one `via` is `JD0031`,
+and a paired edge must agree on `onDelete`.
+
+Between one pair of entities, a `many` declaration facing a `one`
+declaration with a DIFFERENT `via` is `JD0031` as well (the pair
+disagrees on its key) — the check is per entity pair, so **two
+one-to-many edges between the same two entities declare their inverse
+on ONE side only**. The author-and-editor model is written with both
+edges on `User` (`authored` by `authorId`, `edited` by `editorId`) and
+the foreign-key properties on `Post`, or with both edges on `Post` and
+none on `User`; declaring `Post.author` AND `User.edited` makes
+`User.authored` face `Post.editor` and is refused. Two declarations of
+the SAME kind with different `via`s are two independent edges — which
+is how a legitimate cycle is written (`Post.author` by `authorId` and
+`User.featured` by `featuredPostId`, one-to-one each way).
+Many-to-many pairs must agree on the join table, and a many-to-many
+facing a foreign-key relation is `JD0031`.
+
 - **one-to-many** — `{ to, many: true, via, onDelete }`: `via` names
   the foreign-key property on the TARGET entity (`authorId` on
   `Post`). If the target declares that property it MUST be a
@@ -1096,19 +1688,37 @@ reads and deletes take `{ prop: value, … }`.
 Applied on write in JavaScript, never by SQL `DEFAULT`, so the value
 the application sees and the value stored are the same — and the
 behaviour is identical on every driver. `"now"` stamps an RFC 3339
-UTC string on insert when the property is absent; `"updated"` stamps
+UTC string on insert when the property is absent — the calendar date
+alone (`YYYY-MM-DD`) on a `format: date` property, so the stamp
+validates against its own format; `"updated"` stamps
 on insert AND on every update, always; `{ "value": … }` fills a
 literal when absent; `{ "query": … }` evaluates a query document over
 the document being written. Defaults run BEFORE validation, so the
-injected hook sees the completed document.
+injected hook sees the completed document — with one member exempt: a
+store-allocated key (`default: "auto"`) is allocated by the database
+AFTER validation, so a write validates against the schema with that
+key dropped from `required` (the generated input type marks it
+optional for the same reason); the document the store answers carries
+it, and the read shape keeps it required. A `version` property is
+engine-owned and never defaulted by the caller: an insert without one
+writes `0` — not SQL `NULL`, which no `WHERE version = ?` guard could
+match — and every successful write bumps it (§11.5).
 
 ### 9.7 Error-code additions
 
-The entity engine adds two codes to the package's single table (§7):
-`JD0030` — an unknown `x-entity` member; `JD0031` — relation
-declarations whose inverses contradict. Everything else raises the
-existing codes (`JD0005` for structural model defects, `JD2005` for
-database-refused writes including foreign-key violations).
+The entity engine adds four codes to the package's single table (§7):
+`JD0030` — an unknown or unread `x-entity` member; `JD0031` — relation
+declarations whose inverses contradict; `JD0033` — an entity query
+document that binds no entity array (§10.1); `JD0034` — a cursor asked
+to track (`tracking: true`) over a document that yields no entity
+document to register: a projection, a count or a window (§10.1, the
+cursor). Everything else raises the
+existing codes: `JD0005` for structural model defects (a key, index or
+version property without a column of its own, a default on a relation,
+`default: "auto"` off the key, a self-referencing many-to-many, a
+foreign key onto a composite key), `JD2001` for a duplicate key on
+`create()` exactly as on a collection `insert`, and `JD2005` for
+database-refused writes including foreign-key violations.
 
 ## 10. Relational translation
 
@@ -1122,13 +1732,65 @@ translatable runs the set residual over the fetched entity root,
 
 `store.execute(document)` queries the **multi-entity root**: the
 engine-side value is `{ <EntityName>: [documents…], … }` and bindings
-range over `$.<Entity>[*]`. This is the shape the differential oracle
+range over `$.<Entity>[*]`. A document that binds no entity array at
+all — a `$for` over a member the model does not name, or over a
+scalar — is `JD0033` at compile, never an empty answer. The
+array-constructor spelling `["$.<Entity>[*]"]`, which `@jarenjs/linq`
+emits so that an item that is itself an array stays one item
+(QUERY-PEN §3), names the same whole-entity source; the planner
+reads through it for collections (`["$[*]"]`) and entities alike.
+
+An entity set is a provider (QUERY-PEN §8): `store.entity(name)` and
+`store.sync.entity(name)` carry `execute(document, options)` and
+`explain(document, options)` — the document is over the multi-entity
+root and goes to the entity translator whole, exactly as
+`store.execute` runs it — plus `root` (`"$.<Entity>[*]"`, the one
+spelling `collectEntityRoots` reads, so a chain binds its items through
+it) and `scope` (one identity per store, shared by every set, so two
+sets may be joined in one document). The store itself carries `roots`,
+the entity names, because it has no single root: a chain over it is
+refused by name (`JL0007`) rather than answering the mixed rows or
+counting the sets, and a document naming no entity array stays
+`JD0033`. A chain's element terminal hands over the one-item window
+`[<phrase>]` (QUERY-PEN §6); the planner reads through the window as
+it reads through the packed source — the phrase inside plans as if
+bare, and the store answers its rows as the ONE array item the engine
+would (`[]` for none, `[row]` for one, never singleton-unwrapped;
+`explain().wrapped` says so) — so `toArray()` over an entity set runs
+the translator, and a two-root equijoin returning a bare binding runs
+as one statement.
+This is the shape the differential oracle
 can actually prove — the in-memory engine sees exactly the documents
 the entity sets return (`test/db/oracle/relations/`). Relation-NAME
 navigation (`$.author.name`) is deliberately not query-document sugar:
 the engine has no embedded `author` member to walk, so no oracle could
 vouch for it. Name-based navigation lives on the `load` surface
-(§10.4), where results and statement counts are the proof.
+(§10.4), where results and statement counts are the proof — and, by
+code, on a query producer that lowers a hop to what the engine CAN walk.
+
+For that, every entity set carries **`relations`**, the relation table
+a producer may read: a frozen plain record, one entry per declared
+relation member of the entity, `{ to, kind, via?, fkEntity?, fkTargets?,
+joinTable?, targetKey }` — `to` the target entity, `kind` one of
+`oneToOne`/`oneToMany`/`manyToMany`; for a foreign-key relation `via`
+the key property, `fkEntity` the entity holding it, `fkTargets` the
+entity it references and `targetKey` the key property it references
+there (the column a hop's equality compares `via` with; `kind` says
+which side holds the key: `oneToOne` the declaring entity, `oneToMany`
+the target); for a many-to-many `joinTable` and the target's `targetKey`.
+The store (`store.relations`) and every set's `scope` (`scope.relations`)
+carry the same tables keyed by entity name, so a producer holding one
+set can follow a hop into another root. `relationTables(entities)` is
+the one function that derives them. The document format is unchanged:
+`@jarenjs/linq`'s chain reads the table and lowers `p.author.email` to
+`{ $for: { r1: '$.User[*]' }, $where: { $eq: ['$r1.id', '$it.authorId'] },
+$return: '$r1.email' }` (QUERY-PEN §4, relation navigation) — a
+document a hand could have written, which this translator and the
+engine both run and the oracle proves (`15-linq-hops.json`). Every such
+lowered shape is a residual here (§10.6 — a projection, a comparison or
+an existence test over a phrase rather than a member path, an ordering
+by a phrase), named by `explain()` and refused under `strict`; none
+pushes natively in this version.
 
 Per binding, predicates resolve through three reference flavors:
 
@@ -1212,26 +1874,137 @@ store.entity('User').load({
 })
 ```
 
-Per-relation `where`/`orderBy`/`take` apply INSIDE the subquery — the
-point where naive loaders fall back to N+1. Clauses compile against
+Per-relation `where`/`orderBy`/`take`/`skip` apply INSIDE the subquery
+(`LIMIT`/`OFFSET` per parent row) — the point where naive loaders fall
+back to N+1; `after` (§10.5) paginates the ROOT alone, since a keyset
+cursor is one position in one ordered set, and on an include it is
+`JD0032`. Clauses compile against
 the child's own reference flavors; an untranslatable clause is a
 refusal (`JD0032`) naming the include path, never a silent residual.
 Include depth is bounded (default 3, override with `maxDepth`);
 exceeding it is `JD0032` with the bound printed. A cyclic include
 specification is rejected. Unknown relation names are `JD0032` too.
 
+**Every include is bounded per root.** One root graph is the unit a
+graph cursor yields and a page counts, and "one root" is no bound at
+all if one root may aggregate a million related rows. So a to-many
+include carries `maxRows` — related rows per parent — and every
+row-projecting include carries `maxBytes` — serialised bytes of the
+relation per parent, measured on the JSON text the database projects.
+A relation that crosses either bound is the coded refusal **`JD2073`**
+naming the root (entity and key), the member and the bound that was
+hit — never a truncated graph, which a caller could not tell from a
+whole one. The refusal names the two supported alternatives: read
+`{ count: true }` when the size is the question, or page that relation
+separately. A bound always exists: an include with none declared
+inherits the store defaults, `INCLUDE_ROWS_DEFAULT` (1000 rows) and
+`INCLUDE_BYTES_DEFAULT` (1 MiB); an include with a `take` has that
+window as its row bound. The unbounded case is spelled, never
+inherited — `maxRows: Infinity` (`null` in the JSON spec) — so loading
+a relation whole is a decision rather than an oversight. The to-many
+subquery carries `LIMIT maxRows + 1`, so the bound is detected at the
+bound instead of after aggregating the whole relation; a `count`
+include is a number and carries neither. `explainLoad().bounds` lists
+the bounds every include ran under.
+
+**The graph cursor.** `store.entity(name).loadCursor(spec, options)` —
+`graph.cursor(options)` on the client — yields one root graph per
+pull, its includes attached and bounded as above, from the same one
+statement `load` runs: the include rows ride inside each root row as
+the JSON the database projected, so the window is the row itself and
+there is no second statement per level to hold or release. `return()`
+releases the statement exactly once; `signal` cancels at a row boundary
+(`JD2072`). The cursor registers nothing with the unit of work unless
+`tracking: true` is spelled per call — a snapshot per yielded root is a
+tracker that grows with the result.
+
 ### 10.5 Pagination
 
 `$orderby` + `$subsequence` translate to `ORDER BY` + `LIMIT/OFFSET`
-on the query surface. On the `load` surface, `after` (a cursor) with a
-single ascending or descending ordering over a UNIQUE column — the
-key, or any `unique: true` column — compiles to **keyset pagination**
-(`WHERE col > ?` / `< ?`) instead of a growing `OFFSET`; `skip`
-compiles to offset. `explainLoad()` reports which strategy ran
-(`keyset` / `offset` / `none`) — offset degrading quietly on large
-tables is a well-known footgun, and naming it is cheap. A cursor over
-a non-unique column, a document path, or a multi-key ordering is
-refused (`JD0032`).
+on the query surface. On the `load` surface `skip` compiles to offset,
+and `after` — a cursor — to **keyset pagination** (`WHERE …` over the
+last row's order keys) instead of a growing `OFFSET`; `explainLoad()`
+reports which strategy ran (`keyset` / `offset` / `none`) — offset
+degrading quietly on large tables is a well-known footgun, and naming
+it is cheap.
+
+**The single-column form.** `after: <value>` with a single ascending or
+descending ordering over a UNIQUE column — the key, or any `unique:
+true` column — compiles to `WHERE col > ?` / `< ?`. A scalar cursor
+over a non-unique column, a document path, or a multi-key ordering is
+refused (`JD0032`), because such a cursor either skips rows or repeats
+them wherever the value ties.
+
+**The composite keyset.** The orderings a list actually wants —
+`(updatedAt, id)`, `(createdAt, id)`, `(priority desc, id)` — have a
+non-unique first column. `page()` and a structural `after` compile them
+as the lexicographic expansion over the declared terms
+`(k1 dir1, k2 dir2, …)` with **the primary key appended** as the
+tie-breaker whether or not the caller named it (it is the one column
+guaranteed unique, and a tie on every declared key would otherwise be a
+skipped row or a repeated one):
+
+```sql
+(k1 > v1) OR (k1 = v1 AND k2 > v2) OR (k1 = v1 AND k2 = v2 AND pk > vpk)
+```
+
+with `<` for a descending term, and the `ORDER BY` ending in the key
+column(s) rather than the row identity. **Null placement agrees with
+the plan**: every term's null order (`NULLS FIRST`/`LAST`, from `$dir`
+and `$empty`) is spelled in the expansion too — after a null value come
+the non-nulls when nulls sort first and nothing when they sort last;
+after a non-null value come the greater (or lesser) values and, when
+nulls sort last, the nulls — because SQL's `col > ?` is neither true
+nor false for `NULL`, and a comparison alone would visit a null-keyed
+row twice or never. Only mapped columns carry a keyset; a document path
+in the ordering is refused (`JD0032`).
+
+**The continuation** a page emits is unsigned, structural and opaque:
+
+```jsonc
+{ "order": [{ "column": "updatedAt", "desc": true, "nullsFirst": false },
+            { "column": "id", "desc": false, "nullsFirst": false }],
+  "keys": [v1],         // the declared order-key values, as the document carries them
+  "key": vpk }          // the row's primary key (a record for a composite key)
+```
+
+`order` is the ordering's identity: a continuation replayed against a
+different ordering is the refusal `JD0035`, never a wrong page; a
+continuation whose `keys` do not match the declared key count, or
+whose `key` is not the entity's key shape, is `JD0035` too. Signing,
+tenant scoping, expiry and wire encoding are the **host's**: the store
+has no principal and no key, so any signature it invented would be
+security theatre — a host that ships a continuation to an untrusted
+client signs it first.
+
+**The page.** `store.entity(name).page(spec, { limit, after, maxBytes,
+consistency, signal })` — `graph.page(options)` on the client — drains
+the graph cursor in keyset mode and answers `{ items, continuation,
+hasMore, snapshot }`: never more than `limit` roots (default
+`PAGE_LIMIT_DEFAULT`, 100) nor more than `maxBytes` serialised bytes
+(none unless given; every root is bounded by §10.4 regardless), the
+continuation of the last delivered root, and `hasMore` decided by one
+peek past the page. A `take` or `skip` in the spec beside `page()` is
+refused (`JD0032`): the page windows by its limit. **The
+`item_too_large` rule**: an item that alone exceeds `maxBytes` when
+nothing has been delivered yet is the coded refusal `JD2074`, raised
+without advancing the continuation — a caller that retries meets the
+same refusal, which is the honest answer, never a loop and never a
+silent breach; an item that does not fit beside earlier ones ends the
+page before it (`hasMore: true`). A page registers no snapshots unless
+`tracking: true` is spelled.
+
+**Snapshot versus live.** A page reports `snapshot: true` only when
+every order key is immutable — and the primary key is the one column
+the engine itself guarantees never moves (`update()` refuses to rewrite
+it). Ordering a live table by a mutable column such as `updatedAt` is
+**live pagination**, and the page says so (`snapshot: false`): later
+inserts land where their keys sort, but an existing row whose order
+key changes between two pages can move across the cursor — it may be
+seen twice, or not at all — and no cutoff on later writes prevents
+that. `consistency: 'snapshot'` over such an ordering is refused
+(`JD0036`) rather than mislabelled; the default `'live'` reports the
+truth either way. A caller who needs a snapshot orders by the key.
 
 ### 10.6 What remains residual
 
@@ -1240,16 +2013,62 @@ because joins make residuals more expensive — accompanied by the
 `EXPLAIN QUERY PLAN` narrative (SQLite exposes no row estimates;
 a number appears only where `capabilities.rowEstimates` is filled):
 
-- three or more bindings;
+- a binding nothing joins to — the cartesian product a nested-loop plan
+  must never emit by accident; every binding past the first attaches by
+  a column equality to one already joined, and a graph that does not
+  close is the engine's;
 - non-equality join predicates, and disjunctions spanning bindings;
-- `$groupby` (the engine's post-group cardinality rebinding deserves
-  its own order; the count-of-related-rows case ORMs are bad at is
-  already native via `count: true` includes);
-- projections (`$return` objects) — over one binding or across a join;
+- a `$groupby` whose key is untyped or admits `null`, whose `$return`
+  reads the binding (after a grouping it holds the group's ROWS), or
+  whose `$orderby` names anything but a group key; a window over the
+  groups, or an aggregate of them;
+- projections (`$return` objects) ACROSS a join — over one binding a
+  nested shape of member paths lowers (§ the projection tree);
 - externals against document paths; booleans and `null` at bind time;
 - everything phase A already listed (§8 of `QUERY-FORMAT.md`
   notwithstanding, the truth table is the contract).
 
+Two deviations between a pushed answer and the engine's are DECLARED
+rather than refused, because in both the database is right by its own
+arithmetic:
+
+- `$sum`/`$avg` over `number` paths — SQLite sums with Kahan–Babuška
+  compensation and the engine sums naively, so over `0.1, 0.2, 0.3`
+  the store answers `0.6` and the residual `0.6000000000000001`: equal
+  to within an ulp, never equal by `===` (the differential oracle
+  draws dyadic fractions, which are exact on both sides).
+- a `$time-bucket` `$groupby` whose aggregated path admits `null`
+  (`['number', 'null']`): the pushed `AVG` skips a `null` reading
+  exactly as the series kernel — and therefore the `$resample`
+  spelling — does, while the engine's `$avg` over a sequence holding
+  `null` raises `JQ2001`; under this one spelling the store answers
+  where the in-memory engine refuses. Everywhere else an ordering or
+  an aggregate over a path that admits `null`, or over a boolean path,
+  is a named residual, so the two paths keep answering alike.
+
+### 10.7 The join table as a query root
+
+A declared many-to-many join table is a **read-only query root**:
+`$.<JoinTable>[*]` binds like any entity array and answers rows carrying
+exactly its two key columns — `<A>_key` and `<B>_key`, the names the DDL
+creates — and nothing else, because a join row has no document of its
+own. It joins to the entities it relates like any other binding, so
+`Person → Person_Tag → Tag` is one statement over three roots.
+
+It is a ROOT and not an entity: `store.entity('<JoinTable>')` is
+`JD2004`, memberships are still written through `link`/`unlink` and the
+unit of work, and nothing about the table's lifecycle changes. The two
+namespaces are one, so a join table whose name is also a declared
+entity's is refused at open (`JD0005`) — `$.X[*]` may mean one thing.
+
+Because the root exists, a many-to-many **hop** lowers: a chain's
+`u.labels` becomes two links — the join row that names the membership,
+then the target row it names — instead of the `JL0105` refusal it was.
+A relation entry that does not name its join row's columns
+(`{ joinTable, ownColumn, ownKey, targetColumn, targetKey }` — §10.1)
+still refuses with that code, because there is then nothing to lower
+through.
+
 
 ## 11. The unit of work
 
@@ -1293,8 +2112,19 @@ const report = await store.saveChanges();     // one transaction
 
 ### 11.2 Explicit updates (the other mode)
 
-`set.update(key, changes)` and `set.delete(key)` skip tracking: one
-immediate statement, last-write-wins by contract. An explicit update
+`set.create(doc)`, `set.update(key, changes)` and `set.delete(key)`
+skip tracking: one immediate statement, last-write-wins by contract.
+`create` applies defaults, validates, inserts, and — for a
+many-to-many relation whose member the document carries as an array
+of target keys — writes the join rows in the same transaction, which
+rolls back whole when a membership names a row that does not exist; a
+duplicate key is `JD2001`. `update` takes the document's own members
+only: a relation member (`posts`) is `JD2003` exactly as on `create`,
+and a membership array (`labels`) — which `create` writes — is
+`JD2003` on `update` as well, because an explicit update never writes
+join rows or child rows and never echoes back a member it did not
+store; a change to a key member is `JD2003` too (the key column would
+go stale — delete and create). An explicit update
 still bumps a declared version property, so optimistic savers observe
 the row changed. This is the path reactive layers and job runners use.
 
@@ -1337,7 +2167,10 @@ the 100× statement reduction is the point for anything remote.
 
 ### 11.5 Optimistic concurrency
 
-Declare a token with `version: true` (§9.2). Every `saveChanges()`
+Declare a token with `version: true` (§9.2). A row inserted without
+one starts at `0` — never SQL `NULL`, which no guard could match
+(§9.6) — so the first tracked save after `create()`/`add()` carries
+`WHERE version = 0`. Every `saveChanges()`
 update and guarded delete carries `WHERE version = ?` (the SNAPSHOT
 version) and writes snapshot + 1; a zero-row result is **`JD2040`**
 carrying the entity and key, and the whole save rolls back. Without a
@@ -1352,8 +2185,14 @@ zero rows.) An unguarded delete of a missing row is a no-op.
 `saveChanges()` is all-or-nothing inside one transaction. On ANY
 failure the tracker is left exactly as it was before the call — the
 same save can be retried once the cause is gone; a half-applied
-tracker is worse than a rollback. Only a committed save advances
-snapshots (bumped versions, generated keys) and clears pending work.
+tracker is worse than a rollback. A save whose statements all succeed
+advances snapshots (bumped versions, generated keys) and clears pending
+work **immediately**, even inside an enclosing transaction — inside it
+the database does hold those rows, and every later read, plan and
+optimistic guard must agree. The scope that owns the connection holds
+the exact undo delta: an enclosing rollback (or a named-savepoint
+rollback past the save, §5.2) withdraws the advance, a nested rollback
+withdraws only its own effects, and outer commit keeps it.
 
 The return value is data, not a boolean:
 
@@ -1367,3 +2206,46 @@ The return value is data, not a boolean:
   elapsedMs,
 }
 ```
+
+### 11.7 Membership: `link` and `unlink`
+
+A many-to-many membership is attached or detached one row at a time
+through the unit of work, without carrying the whole membership array:
+
+```js
+users.link('u1', 'labels', 'admin');           // a key, or a document carrying the key
+users.unlink(ada, 'labels', { name: 'dev' });  // the own side is a key or a document too
+const report = await store.saveChanges();      // { joinInserted: 1, joinDeleted: 1, … }
+```
+
+- `link`/`unlink` are local, synchronous bookkeeping, like `add`/`put`/
+  `remove`; nothing reaches the database until `saveChanges()`.
+- The member MUST be a many-to-many relation of the entity — `JD2003`
+  otherwise, naming the relation's kind or the missing declaration. The
+  target is read exactly as a membership array's element is: a key, or
+  a document carrying the target's key (`JD2003` when it carries none).
+- The own side needs the entity's key. A pending insert whose `auto`
+  key the save allocates has none to attach to and is refused (`JD2003`:
+  "save the entity first, then attach"); a pending insert with a
+  caller-supplied key may be linked in the same save, since join rows
+  run after the inserts (§11.4).
+- The baseline is the join table **as read at save time**, not a
+  snapshot: linking a member that already exists and unlinking one that
+  does not are no-ops, so a save repeated with the same calls changes
+  nothing (asserted). The last word on one target wins — `unlink` after
+  `link` means unlink.
+- A `link`/`unlink` beside a `put` carrying the SAME member's membership
+  array folds into that array's key-set difference (§11.3): one intent
+  per entity, own key and member, never two statements racing for one
+  row.
+- A tracked snapshot's loaded membership array is not rewritten by a
+  saved `link`/`unlink` — a projection stays what it was read as;
+  re-read (`load({ include })`) to see the membership. `discard(key)`
+  drops the key's pending membership changes together with its
+  tracking, and a failed save leaves them pending, as §11.6 promises.
+- The report counts the rows written under `joinInserted`/`joinDeleted`
+  and `stats().tracker.pendingMemberships` counts the pending
+  (entity, key, member) records.
+
+Worker/pool options, synchronous cursors, wasm session probing and the browser
+persistence ladder are specified in [execution hosts](HOSTS.md).