@jarenjs/db 0.56.0 → 0.67.0

package/docs/MODEL-FORMAT.md

@@ -198,8 +198,8 @@ 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 <!--fact:vector.jsonDoc-->15.0× the plan at 10,000 × 768<!--/fact-->
-on the read, and costs <!--fact:vector.write-->10.6 s against 5.0 s for 50,000 documents in one transaction — 2.1× the write cost<!--/fact-->
+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 <!--fact:vector.storage-->3,072 B packed against 16,141 B as a JSON number array inside the document — 5.3× smaller<!--/fact-->
@@ -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
@@ -648,6 +750,11 @@ 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`/
@@ -669,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
 
@@ -733,10 +1010,13 @@ 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 |
@@ -744,6 +1024,10 @@ error.
 | `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 |
@@ -763,16 +1047,161 @@ error.
 | `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 |
+| `JD0060` | a replication envelope or snapshot is invalid |
+| `JD2100` | a replica sequence or causal dependency has a gap |
+| `JD2101` | an envelope identity names different content or an unknown local origin |
+| `JD2102` | the replica identity or model revision disagrees |
+| `JD2103` | a resolver fails its synchronous decision contract |
+| `JD2104` | a logical row or snapshot disagrees with its causal history |
+| `JD2105` | an explicit snapshot reset is required, or reset would discard acknowledged history |
+| `JD2106` | a replication operation or snapshot exceeds its configured bound |
 
 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' });
@@ -788,7 +1217,91 @@ so a store-level mandatory predicate or allow-list does not carry into
 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
@@ -956,6 +1469,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
@@ -986,15 +1531,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
 
@@ -1173,10 +1714,13 @@ match — and every successful write bumps it (§11.5).
 
 ### 9.7 Error-code additions
 
-The entity engine adds three codes to the package's single table (§7):
+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). Everything else raises the
+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
@@ -1349,18 +1893,126 @@ 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
 
@@ -1369,13 +2021,17 @@ 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`, except the `$time-bucket` ladder the series plan pushes
-  (README, *Time series*) — 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).
@@ -1398,6 +2054,29 @@ arithmetic:
   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
 
@@ -1514,8 +2193,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:
 
@@ -1569,3 +2254,6 @@ const report = await store.saveChanges();      // { joinInserted: 1, joinDeleted
 - 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).