@jarenjs/db 0.49.2 → 0.56.0

package/ARCHITECTURE.md

@@ -247,14 +247,21 @@ index-usable spelling and read every row of the collection.
 
 The guards make the forms sound for typed AND untyped paths alike —
 the schema type's job is choosing the generated COLUMN (the index),
-never weakening the guard. Two documented preconditions: string
-operators, aggregates AND ordering are only promoted on schema-typed
-paths because the engine ERRORS on non-conforming operands where SQL
-would coerce or sort — a stored `null` under an ordered key, a
-non-string under a string operator — so on an unvalidated store, rows
-violating the collection schema can make the engine throw where the
-database answers; keep `compileSchema` injected if that distinction
-matters to you.
+never weakening the guard. Two documented preconditions. String
+operators, aggregates and ordering are only promoted on schema-typed
+paths that cannot hold `null` and are not boolean, because the engine
+ERRORS on non-conforming operands where SQL would coerce or sort — a
+`null` under an ordered key, a non-string under a string operator —
+so a path whose schema admits `null` is a named residual for those
+forms and the two engines keep answering alike over conforming data.
+And the guards protect the JSON TYPE, not the VALUE: a typed
+generated column carries SQLite affinity, so on an unvalidated store a
+row that violates the schema — the string `'020'` under an `integer`
+path — reads as the integer `20` in the column while `json_type` still
+says text, and a pushed comparison answers rows the engine (comparing
+the JSON value) does not. Keep `compileSchema` injected: with the hook
+no such row is ever stored, and without it the pushdown is exact only
+over documents that happen to conform.
 
 **Bind-time diversion.** SQLite cannot bind a boolean, and a
 `null`-valued external needs Jaren's null semantics, not SQL's. At
@@ -571,8 +578,9 @@ collection binding, so the planner passes that binding's **name** in:
 wrapped under any other name every reference would read as an external,
 the determinism rule would reject the fragment, and the hatch would
 silently not engage — no error and no reason in `explain()`.
-Registration is keyed by `contentKey(fragment)`
-so identical fragments share one registration, and the planner MUST
+Registration is keyed by `semanticKey(fragment)` (the
+order-insensitive identity from `@jarenjs/core/object`) so identical
+fragments share one registration, and the planner MUST
 produce a correct plan with the capability disabled (tested that way).
 Preference order: native SQL → deterministic function → residual, and
 `explain()` names the choice. **Index-form UDFs are deliberately not
@@ -585,11 +593,15 @@ UDF-expression indexes.
 ### The statement cache
 
 A caller of the core primitives, not an eighth implementation:
-`createBoundedCache` keyed by `contentKey(document)` plus collection,
-dialect and strictness. `contentKey` is the memo-grade key
-(`hashContent(stableStringify(x) ?? '')` — drops `undefined` members,
-no cycle guard; both properties acceptable for a cache key), never
-`canonicalizeJson` (signature-grade, throws on `undefined`).
+`createSemanticCache` keyed by the whole discriminating tuple — the
+document plus collection, dialect, strictness, the pushdown switch and
+the profile — where the identity is the tuple's COMPLETE
+serialization, never a fingerprint of it: a 32-bit content hash
+collides after tens of thousands of documents, and a collision here
+answers one query with another query's plan and rows (the
+cache-identity test exists to keep that key abolished).
+`store.stats()` exposes hits, misses and evictions so the cache is
+proven rather than assumed.
 `store.stats()` exposes hits, misses and evictions, so the cache is
 proven rather than assumed.
 

package/README.md

@@ -48,7 +48,8 @@ const store = await openStore({
 const users = store.collection('users');
 await users.insert({ id: 'u1', email: 'ada@example.test', age: 36 });
 
-// a query document — here written by hand; linq writes the same thing
+// a query document — here written by hand; linq writes the same one,
+// its source wrapped as ['$[*]'] so an item that is an array stays one item
 const adults = await users.execute({
   $for: { it: '$[*]' },
   $where: { $ge: ['$it.age', 21] },
@@ -56,6 +57,78 @@ const adults = await users.execute({
 });
 ```
 
+Or, by code — the same document, written by the model pen
+([MODEL-PEN.md](../linq/docs/MODEL-PEN.md)) and typed without a generate
+step (`InferMeta<typeof model>` binds the typed store):
+
+```js
+import * as m from '@jarenjs/linq/model';
+
+const model = m.defineModel({
+  collections: {
+    users: m.collection(
+      m.object({ id: m.string(), email: m.string().email(), age: m.integer().optional() }).open(),
+      { key: (u) => u.id, indexes: [m.index((u) => u.age)] },
+    ),
+  },
+});
+const store = await openStore(model, { driver: nodeDriver(), path: 'app.db' });
+```
+
+Over an entities model, an entity set is a provider too (MODEL-FORMAT
+§10.1): a chain binds through the set's root and the store runs the
+document whole — the translator for a bare-binding selection or
+equijoin, the declared residual for a projection — while the store
+itself, serving several roots, is refused by name (`JL0007`):
+
+```js
+import { from, fromAsync } from '@jarenjs/linq';
+
+const starred = from(store.sync.entity('Post')).where((p) => p.stars.ge(3));
+starred.toDocument();   // { $for: { it: '$.Post[*]' }, $where: { $ge: ['$it.stars', 3] }, $return: '$it' }
+starred.toArray();      // the entity translator, one statement
+await fromAsync(store.entity('Post'))
+  .join(fromAsync(store.entity('User')), (p) => p.authorId, (u) => u.id, (p) => p)
+  .toArray();           // a two-root equijoin, one statement
+```
+
+A declared relation navigates on the chain, and the document still
+carries no relation name: the chain reads the set's relation table
+(`store.entity('Post').relations`, MODEL-FORMAT §10.1) and lowers
+`p.author.email` to the correlated phrase the engine and the store both
+run. The store answers it as the residual it is — `explain()` says so,
+`strict` refuses it — over the two fetched roots, never a statement per
+row:
+
+```js
+const byAuthor = from(store.sync.entity('Post'))
+  .where((p) => p.stars.ge(3))
+  .select((p) => ({ title: p.title, by: p.author.email }));
+
+byAuthor.toDocument();
+// { $for: { it: '$.Post[*]' },
+//   $where: { $ge: ['$it.stars', 3] },
+//   $return: { title: '$it.title',
+//              by: { $for: { r1: '$.User[*]' },
+//                    $where: { $eq: ['$r1.id', '$it.authorId'] },
+//                    $return: '$r1.email' } } }
+byAuthor.explain().hops;   // [{ member: 'author', kind: 'oneToOne', binding: 'r1' }]
+store.sync.explain(byAuthor.toDocument());
+// { mode: 'set', referenced: ['Post', 'User'], sql: null,
+//   reasons: [{ construct: '$return',
+//               reason: 'entity queries return one bare binding natively; projections run in the engine' }], … }
+byAuthor.toArray();        // the rows, two fetches — one per referenced root
+
+from(store.sync.entity('User')).where((u) => u.posts.all().count().ge(2));
+// … $where: { $ge: [{ $count: { $for: { r1: '$.Post[*]' },
+//                                $where: { $eq: ['$r1.authorId', '$it.id'] },
+//                                $return: '$r1' } }, 2] } …
+```
+
+A many-to-many member (`u.labels`) is refused at build time (`JL0105`)
+naming the join table: it is not a queryable root in this version, so
+`load({ include: { labels: true } })` is how the memberships are read.
+
 `execute` answers in the ENGINE's result shape (QUERY-FORMAT §1,
 "singleton ≡ item"): `undefined` for no rows, the document itself for
 exactly one, an array for more — typed `SequenceResult<R>`, with `R`
@@ -71,9 +144,12 @@ shape binds at `store.collection<User>('users')`.
   equivalent runs as a real compiled Jaren query (the residual), and
   `explain()` always says which is which — the SQL, the bound
   parameters, the indexes used (verified against the database's own
-  plan output), and the residual's named reasons. A 418-run
-  differential oracle keeps both paths agreeing. `strict: true` turns
-  any residual into a compile error.
+  plan output), and the residual's named reasons. A differential
+  oracle — a committed corpus and a seeded generator, every case run
+  in both modes — keeps both paths agreeing, with the one arithmetic
+  deviation declared rather than hidden (MODEL-FORMAT §10.6: SQLite's
+  compensated `SUM` and the engine's naive one differ in the last
+  bit). `strict: true` turns any residual into a compile error.
 - **Registered operators, correct in the residual, pushed where it
   pays.** Open with a registry (`operators:
   createJsltRegistry().use(mathPack).use(financePack)`) and a query may
@@ -129,7 +205,13 @@ shape binds at `store.collection<User>('users')`.
   replays the whole chain before the real store is touched; a
   checksummed history refuses edited or reordered migrations; a
   narrowing without an adequate transform is refused against the REAL
-  data, inside the transaction.
+  data, inside the transaction. And by code: `@jarenjs/linq/migration`
+  ([MIGRATION-PEN.md](../linq/docs/MIGRATION-PEN.md))
+  writes the same document with the data transform typed old row → new
+  row, `jaren-db` loads model and migration MODULES beside JSON, plans
+  from the committed `model.snapshot.json`, refuses a module that is
+  not pure, and `jaren-db check` fails CI on a model that moved without
+  a plan (MIGRATION-FORMAT §11).
 - **The safe profile.** Untrusted query documents run under composed
   bounds: engine limits on the residual, a mandatory row bound that
   refuses rather than truncates, reference allow-lists, optional
@@ -239,16 +321,16 @@ every write (LIVE-FORMAT §7 states the cost). An ordering by
 `$distance` or a spatial aggregate re-runs on invalidation with the
 reason in `live.mode` — declared, never silent.
 
-**The numbers, the loss included.** `benchmark/spatial.js` stores <!--bm:spatial.corpus-->50,000 points<!--/bm-->
-over the Netherlands and probes one box at <!--bm:spatial.rows-->258 of 50,000 (0.5 %)<!--/bm--> selectivity,
+**The numbers, the loss included.** `benchmark/spatial.js` stores <!--fact:spatial.corpus-->50,000 points<!--/fact-->
+over the Netherlands and probes one box at <!--fact:spatial.rows-->258 of 50,000 (0.5 %)<!--/fact--> selectivity,
 asserting every plan case of the committed spatial corpus and every timed shape against the JavaScript
-engine before a single timing is printed. The `$within` a consumer writes went from <!--bm:spatial.scan-->80 ms<!--/bm-->
-as a full scan to <!--bm:spatial.within-->2 ms<!--/bm--> over the `bbox` index (<!--bm:spatial.scanVsIndexed-->40.0<!--/bm-->×);
-`$bbox-intersects` is <!--bm:spatial.bboxIntersects-->1.9 ms<!--/bm-->, a bounded `$distance` <!--bm:spatial.distance-->1.5 ms<!--/bm-->;
-one geohash cell answers in <!--bm:spatial.cellOne-->0.0068 ms for 0 row(s)<!--/bm--> and the honest nine-cell
-probe in <!--bm:spatial.cellNine-->0.026 ms for 2 row(s)<!--/bm-->. The row the store had to win is the same
-`$within` in the in-memory engine over the parsed array, no database at all: <!--bm:spatial.engine-->32 ms<!--/bm-->.
-The indexed store is now <!--bm:spatial.engineVsIndexed-->16.1× faster than<!--/bm--> it — but the un-indexed scan
+engine before a single timing is printed. The `$within` a consumer writes went from <!--fact:spatial.scan-->80 ms<!--/fact-->
+as a full scan to <!--fact:spatial.within-->2 ms<!--/fact--> over the `bbox` index (<!--fact:spatial.scanVsIndexed-->40.0<!--/fact-->×);
+`$bbox-intersects` is <!--fact:spatial.bboxIntersects-->1.9 ms<!--/fact-->, a bounded `$distance` <!--fact:spatial.distance-->1.5 ms<!--/fact-->;
+one geohash cell answers in <!--fact:spatial.cellOne-->0.0068 ms for 0 row(s)<!--/fact--> and the honest nine-cell
+probe in <!--fact:spatial.cellNine-->0.026 ms for 2 row(s)<!--/fact-->. The row the store had to win is the same
+`$within` in the in-memory engine over the parsed array, no database at all: <!--fact:spatial.engine-->32 ms<!--/fact-->.
+The indexed store is now <!--fact:spatial.engineVsIndexed-->16.1× faster than<!--/fact--> it — but the un-indexed scan
 is not, and the comparison is not an even one either way: the engine starts from parsed objects where the
 store starts from bytes on a page and pays JSON materialisation for every row it returns. Both rows stay
 published. The deterministic-UDF hatch takes a literal `$within` on a collection with no derived index, and
@@ -263,10 +345,10 @@ columns (MODEL-FORMAT §2.1). The logical model is unchanged — the
 spatial corpus runs every entry under both mappings, in all three
 executors, with no special-cased entry — and the pushed conjunct becomes
 a `rowid` subquery over the virtual table. Through the store the same
-`$within` measures <!--bm:spatial.rtreeStore-->0.46 ms against 2 ms — 4.3× in the R\*Tree's favour<!--/bm-->; loading the same rows
-costs <!--bm:spatial.rtreeLoad-->718 ms against 399 ms for 50,000 documents in one transaction — 1.8× the write cost<!--/bm-->, because the R\*Tree is a
+`$within` measures <!--fact:spatial.rtreeStore-->0.46 ms against 2 ms — 4.3× in the R\*Tree's favour<!--/fact-->; loading the same rows
+costs <!--fact:spatial.rtreeLoad-->718 ms against 399 ms for 50,000 documents in one transaction — 1.8× the write cost<!--/fact-->, because the R\*Tree is a
 second table written inside every write transaction. Isolated from the
-store on a raw connection the probe is <!--bm:spatial.rtree-->0.3 ms against 1.9 ms — 6.4× in the R\*Tree's favour<!--/bm-->.
+store on a raw connection the probe is <!--fact:spatial.rtree-->0.3 ms against 1.9 ms — 6.4× in the R\*Tree's favour<!--/fact-->.
 Both halves are published because both are the price. One honest
 difference comes with it: an R\*Tree stores 32-bit floats rounded
 outward, so its box is a superset and `$bbox-intersects` is refined
@@ -389,11 +471,11 @@ wrong width is refused at plan time and `explain()` says why; an
 that count, and a consumer who binds probes from a model should watch it.
 
 **The numbers, the losses included.** `benchmark/vector.js` measures one
-k-nearest query every physical way it can run — over <!--bm:vector.grid-->10,000 and 50,000 vectors at 384 and 768 dimensions, k = 10, the median of 10 probes<!--/bm--> —
+k-nearest query every physical way it can run — over <!--fact:vector.grid-->10,000 and 50,000 vectors at 384 and 768 dimensions, k = 10, the median of 10 probes<!--/fact--> —
 and asserts that every path returns the identical top-k, ids and order,
 on every probe before a single timing prints. The flagship row is the
-plan a consumer's own document runs, which measures <!--bm:vector.plan-->206 ms at 50,000 × 768<!--/bm-->:
-<!--bm:vector.table-->
+plan a consumer's own document runs, which measures <!--fact:vector.plan-->206 ms at 50,000 × 768<!--/fact-->:
+<!--fact:vector.table-->
 | path (ms) | 10,000 × 384 | 10,000 × 768 | 50,000 × 384 | 50,000 × 768 |
 |---|---:|---:|---:|---:|
 | engine resident sweep (no database) | 3.3 | 6.7 | 17 | 32 |
@@ -402,14 +484,14 @@ plan a consumer's own document runs, which measures <!--bm:vector.plan-->206 ms
 | `ORDER BY` over a registered function | 18 | 31 | 121 | 180 |
 | JSON-doc sweep (no vector column) | 249 | 501 | — | — |
 | sqlite-vec | 3.6 | 7.5 | 18 | 38 |
-<!--/bm-->
+<!--/fact-->
 
 The row the column exists to beat is the last one that has no column: the
 same query document over a collection that stores the embedding only
-inside the document costs <!--bm:vector.jsonDoc-->15.0× the plan at 10,000 × 768<!--/bm-->,
+inside the document costs <!--fact:vector.jsonDoc-->15.0× the plan at 10,000 × 768<!--/fact-->,
 because every row's vector is parsed out of JSON before it can be
 compared. The row the store **cannot** beat is the one with no database
-in it: the same top-k over a resident `Float32Array` is <!--bm:vector.resident-->32 ms, which the plan is 6.4× slower than<!--/bm-->.
+in it: the same top-k over a resident `Float32Array` is <!--fact:vector.resident-->32 ms, which the plan is 6.4× slower than<!--/fact-->.
 That comparison is not an even one and the direction is the point — the
 sweep starts from decoded floats in RAM and pays nothing for durability,
 for filters that compose with the ranking, or for a process that can
@@ -418,16 +500,16 @@ price should be able to say what the price is.
 
 **Both halves of the price.** The column costs on the way in as well as
 saving on the way out: writing the same documents with
-the index costs <!--bm:vector.write-->10.6 s against 5.0 s for 50,000 documents in one transaction — 2.1× the write cost<!--/bm-->,
+the index costs <!--fact:vector.write-->10.6 s against 5.0 s for 50,000 documents in one transaction — 2.1× the write cost<!--/fact-->,
 because every write pays a JSON round trip of the member plus a
-normalize and a pack. On disk one vector is <!--bm:vector.storage-->3,072 B packed against 16,141 B as a JSON number array inside the document — 5.3× smaller<!--/bm--> —
+normalize and a pack. On disk one vector is <!--fact:vector.storage-->3,072 B packed against 16,141 B as a JSON number array inside the document — 5.3× smaller<!--/fact--> —
 smaller, but *added*, since the document still carries the member the
 column is derived from.
 
 **Pushing the rank into SQL, re-measured.** A registered similarity
 function inside an `ORDER BY … LIMIT k` is the obvious alternative, and
 the suite measures it against the real column with the probe hoisted out
-of the per-row call: <!--bm:vector.udf-->180 ms against 202 ms at 50,000 × 768, and 0.87–1.00× the fetch-and-rank across the grid — rough parity on speed<!--/bm-->.
+of the per-row call: <!--fact:vector.udf-->180 ms against 202 ms at 50,000 × 768, and 0.87–1.00× the fetch-and-rank across the grid — rough parity on speed<!--/fact-->.
 The plan does not emit it, and after that measurement the reasons are not
 speed: `bun` has no user-function API, so a plan that needed one would
 exclude an executor outright; and an ordering decided in SQL cannot break
@@ -436,15 +518,15 @@ executors have to agree on.
 
 **The rival, and the ceiling.** `sqlite-vec` is the extension built for
 exactly this, and it is measured rather than described: it answers the
-same probes in <!--bm:vector.rival-->38 ms against 206 ms at 50,000 × 768 — 5.4× in sqlite-vec's favour, out of a database 6.6× smaller that holds no documents<!--/bm-->,
-over <!--bm:vector.agreement-->40 probes, no disagreements<!--/bm-->. It is a
+same probes in <!--fact:vector.rival-->38 ms against 206 ms at 50,000 × 768 — 5.4× in sqlite-vec's favour, out of a database 6.6× smaller that holds no documents<!--/fact-->,
+over <!--fact:vector.agreement-->40 probes, no disagreements<!--/fact-->. It is a
 loadable native extension, which is the one thing this store will not
 require — it would exclude the wasm tab and stock `bun`, half the
 execution story — so the comparison is published as what it is: a faster
 engine you may prefer, and a dependency this one does not take. What
 neither of them is, is an approximate index. Exact brute force is linear
 in `n · d`, and the suite states the envelope as arithmetic rather than
-opinion: <!--bm:vector.ceiling-->5.546 ns per vector component — one query reaches 100 ms at about 22,000 vectors of 768 dimensions and one second at about 234,000<!--/bm-->.
+opinion: <!--fact:vector.ceiling-->5.546 ns per vector component — one query reaches 100 ms at about 22,000 vectors of 768 dimensions and one second at about 234,000<!--/fact-->.
 Past that this design is the wrong tool and no margin changes it; what
 lies beyond is an approximate index, and this store does not have one.
 
@@ -501,13 +583,13 @@ same range, the same buckets, the same rolling window and the same
 as-of join over one seeded corpus by plain references, by the temporal
 kernel, by a generic query document, by hand-written SQL and by the
 store — every route checked against the others before a timing is
-taken. At <!--bm:series.corpus-->100,000 samples at 1-second spacing, Node v24.19.0<!--/bm-->,
-the store is measured three ways at once — <!--bm:series.storeShapes-->the planned range costs 4.2× the hand-written statement and 1535.5× the resident cut, and the pushed bucket ladder 2.5× the hand-written GROUP BY, 1.6× FASTER than the generic query route, and 155.1× the one-pass loop<!--/bm-->.
+taken. At <!--fact:series.corpus-->100,000 samples at 1-second spacing, Node v24.19.0<!--/fact-->,
+the store is measured three ways at once — <!--fact:series.storeShapes-->the planned range costs 4.2× the hand-written statement and 1535.5× the resident cut, and the pushed bucket ladder 2.5× the hand-written GROUP BY, 1.6× FASTER than the generic query route, and 155.1× the one-pass loop<!--/fact-->.
 The range row is not the planner's price: the statement selects two
 COLUMNS where the store renders and parses a whole JSON document per
 row, which is what storing documents costs.
 
-And what a refinement costs, with the loss in it: <!--bm:series.storeRefinement-->A window measured in time is not pushed: the store answers it at 18.5× the kernel over an array already in memory, over 100,000 candidates the index bounded. The batched as-of join reads 99,129 rows in 1 statement and costs 1424.3× fifty-one separate index reads — a bound is what it buys, not a speed-up, and without a tolerance a backward join can only be bounded above.<!--/bm-->
+And what a refinement costs, with the loss in it: <!--fact:series.storeRefinement-->A window measured in time is not pushed: the store answers it at 18.5× the kernel over an array already in memory, over 100,000 candidates the index bounded. The batched as-of join reads 99,129 rows in 1 statement and costs 1424.3× fifty-one separate index reads — a bound is what it buys, not a speed-up, and without a tolerance a backward join can only be bounded above.<!--/fact-->
 
 **A refinement is named, never quiet.** `explain().series` reports
 `mode` — `native`, `hybrid` or `engine` — the declared index the fetch
@@ -515,7 +597,8 @@ seeks through, the instant bounds it used, which kernel finished the
 answer, and a reason code for every thing the database could not do:
 `fill-policy`, `calendar-width`, `named-zone`, `rolling-refinement`,
 `asof-refinement`, `unsupported-aggregate`, `nonliteral-spec`,
-`instant-not-integer`, `missing-series-prefix`. `strict: true` refuses
+`instant-not-integer`, `missing-series-prefix`, `row-selector`,
+`value-not-numeric`, `nonnative-grouping`, `invalid-spec`. `strict: true` refuses
 every one of them before a statement runs, and the counts `explain()`
 prints are the LAST ACTUAL execution's — `null` until the document has
 run, because an estimate wearing a count's name is worse than no
@@ -575,6 +658,18 @@ SQLite's own story (WAL plus a busy timeout, both set and visible on
   `typedStore` (from `@jarenjs/db/typed`) types every read, checks
   every write, and widens `load` results by their include
   specification.
+- **Membership** (§11.7): `link(own, member, target)` and `unlink` attach
+  and detach one many-to-many membership at a time through the unit of
+  work — written against the join table as it stands at save time, so a
+  repeated save changes nothing.
+- **The front door**: `@jarenjs/linq/db` opens this store behind a
+  client typed from the model pen — `db.entities.Post.where((p) =>
+  p.stars.ge(3))` is the chain over the entity set, pushed down;
+  `db.entities.User.include((u) => u.posts, { where: (p) => p.stars.ge(3),
+  take: 2 }).toArray()` emits exactly the `load` spec above and runs in
+  the same one statement; `link`/`unlink` reach §11.7 and `live` the
+  registration below. It imports this package as an optional peer; this
+  package never imports it.
 - **Relational migrations and the `jaren-db` CLI** (MIGRATION-FORMAT
   §§9–12): the strategy-table diff, the documented twelve-step table
   rebuild with `foreign_key_check` inside the transaction, shape
@@ -611,7 +706,12 @@ SQLite's own story (WAL plus a busy timeout, both set and visible on
   queries, the same live updates run on the official SQLite wasm build
   over the header-free OPFS SAH-pool VFS — one tab owns the
   connection, others are clients. Proven in the `#/data` studio across
-  Chromium, Firefox and WebKit.
+  Chromium, Firefox and WebKit. The subpath exports the two helpers
+  that studio is built on: `sqlite3Handle(sqlite3, { DbClass })` builds
+  the injected handle from a loaded wasm module and the database class
+  the host picks (`sqlite3.oo1.DB` in memory, the SAH-pool
+  `OpfsSAHPoolDb` for OPFS), and `adaptOo1Database(sqlite3, db)` wraps
+  an oo1 database the host already opened.
 
 ### What an event-time view costs
 
@@ -623,16 +723,16 @@ before a single timing is printed — a fast live view with the wrong
 answer is not a fast live view — and the run exits non-zero if they
 disagree.
 
-<!--bm:live.eventTimeTable-->
+<!--fact:live.eventTimeTable-->
 | view | maintained | re-run | ratio |
 |---|---:|---:|---:|
 | bucket (60 s ladder, mean), 1000 rows | 119 µs | 1.09 ms | 9.2× |
 | rolling (5 min window, mean), 1000 rows | 407 µs | 3.86 ms | 9.5× |
 | bucket (60 s ladder, mean), 10000 rows | 136 µs | 10.9 ms | 80.2× |
 | rolling (5 min window, mean), 10000 rows | 13.7 ms | 62.7 ms | 4.6× |
-<!--/bm-->
+<!--/fact-->
 
-The gain is <!--bm:live.eventTimeBand-->80.2× for the bucket and 4.6× for the rolling at 10,000 readings<!--/bm-->. A bucket
+The gain is <!--fact:live.eventTimeBand-->80.2× for the bucket and 4.6× for the rolling at 10,000 readings<!--/fact-->. A bucket
 view is nearly flat in the series length, because a write folds one
 bucket again and the rest of the ladder is untouched. A rolling view is
 not, and the table says so: its answer is one row per reading, so the
@@ -677,10 +777,10 @@ replication on these primitives is a roadmap item, not a hint.
 - **The wasm build journals** (its session extension is not yet
   adapted); OPFS needs a secure context, and where it is absent the
   store runs in memory with the durability difference stated.
-- **Named future work, not silent gaps**: `$groupby` pushdown,
-  relation-name query sugar, a many-to-many membership API, incremental
-  joins, other SQL dialects, replication, database introspection
-  (MODEL-FORMAT §10.6, the roadmap).
+- **Named future work, not silent gaps**: `$groupby` pushdown beyond
+  the `$time-bucket` ladder, a many-to-many hop on the chain, membership
+  on an auto-keyed pending insert, incremental joins, other SQL dialects,
+  replication, database introspection (MODEL-FORMAT §10.6, the roadmap).
 
 The normative formats are
 [docs/MODEL-FORMAT.md](docs/MODEL-FORMAT.md) (storage §§1–7, safe

package/docs/JOBS-FORMAT.md

@@ -49,7 +49,10 @@ restarting.
 `_jaren_job_checkpoints` holds `(run_id, node_id, value)` rows — the
 flow checkpoint store of §7, keyed by the JOB id (the run id IS the
 job id). Both tables are created on open when `jobs` is requested;
-neither appears in the model.
+neither appears in the model. `enqueue`'s options are validated as
+they are stored: `runAt` must be a finite epoch in milliseconds and
+`maxAttempts` a positive integer (`TypeError`) — a `NaN` eligibility
+was once stored, and that job was pending forever.
 
 ## 3. Leasing and exactly-once execution
 
@@ -113,22 +116,31 @@ reclaimed — size `leaseMs` to the slowest honest handler.
 ## 6. Workers and concurrency
 
 `createWorker({ handlers, concurrency, pollInterval, leaseMs, owner,
-maxAttempts, backoff, random })` returns `{ start(), stop(),
+backoffBase, backoffCap, stopGraceMs })` returns `{ start(), stop(),
 stats() }`:
 
-- `concurrency` (default 1) independent claim-execute loops share one
-  worker registration;
+- `concurrency` (default 1, a positive integer — `TypeError`
+  otherwise, because a worker with zero loops would `start()` and never
+  claim) independent claim-execute loops share one worker registration;
 - an idle loop sleeps `pollInterval` (default 500 ms — at most
   2 claims/s of idle cost per loop, stated). An `enqueue` on the SAME
   store wakes every idle local loop immediately, so same-process
   latency is not poll-bound; **cross-process wake-up is polling**,
   plainly (§8);
+- retry backoff is `min(backoffCap, backoffBase × 2^(attempts − 1))`,
+  jittered to between half and all of itself (defaults 1 s and 60 s);
+  `maxAttempts` belongs to the JOB (`enqueue(kind, payload,
+  { maxAttempts })`, default 5), not to the worker;
 - `stop({ graceMs })` aborts in-flight handlers and resolves once they
-  settle **or** the grace period expires (default 5 s), answering
+  settle **or** the grace period expires (default `stopGraceMs`, 5 s),
+  answering
   `{ drained, inFlight }`; a loop the grace period could not drain is
   **cancelled**, not left running — see §6.1;
-- `stats()` reports claims, completions, failures, wakes, polls and the
-  in-flight handler count.
+- `stats()` reports claims, completions, failures, wakes, polls, the
+  in-flight handler count and `claimErrors` — a claim statement the
+  database refused (a read-only file, a closed store), counted rather
+  than swallowed, so a worker that can never claim is visible instead
+  of silently idle.
 
 ### 6.1 A handler cannot break the loop, and cannot hold shutdown
 
@@ -224,6 +236,10 @@ await store.jobs.enqueue('sync-report', { input: { day: '2026-08-05' } });
 This format adds NO codes. API misuse (a malformed handler map, a
 non-string kind, a worker started twice) is a `TypeError` at the
 call, matching the capture and live precedents; storage failures ride
-the existing `JD2005` wrap; a job's own failure is DATA — recorded in
+the existing `JD2005` wrap and a coded error passes through it
+unchanged (`JD2063` after `close()`); `store.jobs` on a read-only
+store is `JD0002` at first use, because the queue tables cannot be
+created — named there, not a raw `SQLITE_READONLY` at the first
+enqueue; a job's own failure is DATA — recorded in
 `last_error` and the state machine of §4 — because a queue that
 throws away its failure story has failed twice.

package/docs/LIVE-FORMAT.md

@@ -92,7 +92,10 @@ them).
   already knows what it wrote. **Less complete, stated plainly**: it
   cannot see writes made through raw SQL, triggers, or another
   connection; a journal-mode delete of a row the store never read
-  emits its `remove` without having seen the old document; and of the
+  emits its `remove` without having seen the old document; a keyed
+  `put` reads the stored document first, so it emits the `replace`
+  session mode emits and a `put` that changes nothing emits nothing;
+  and of the
   database's own `ON DELETE` side effects it reconstructs exactly ONE
   — join-table membership dying with its entity (read before the
   delete) — while cascades into CHILD rows (`onDelete: 'cascade'` /
@@ -114,8 +117,14 @@ reads forward:
 const records = await store.changesSince(lastSeq);  // JD2051 when no log
 ```
 
-`seq` is monotonic; with the log enabled it continues across reopens
-(seeded from `MAX(seq)`), without it it is per-process. Retention is
+`seq` is monotonic; with the log enabled the DATABASE allocates it —
+each record's `seq` is `MAX(seq) + 1` computed inside the insert
+statement and read back through `RETURNING` — so two stores over one
+file never collide on the log's key and each sees the other's
+sequence continue; without the log it is per-process. `changesSince`
+answers records in the shape observers receive, `collections`
+included; a cursor that is not a number is a `TypeError`, as is a
+`retention` that is not a positive integer. Retention is
 a bounded count (`retention`, default 1000): older rows are pruned in
 the same transaction. The log is an ordered, replayable stream —
 which is what makes a late-joining consumer possible. **Replication
@@ -161,6 +170,14 @@ multi-entity shape of MODEL-FORMAT §10) the same way. Live queries
 REQUIRE change capture — the patch stream is the invalidation source —
 and registering on a store opened without `capture` is `JD0050`.
 
+A producer may hand a registration a CHAIN instead of a document: the
+`@jarenjs/linq/db` client's `live(chain, options)` passes the chain's
+`toDocument()` and its `explain().bindings` as the externals to exactly
+these two registrations (`store.live` for an entity-root chain,
+`collection.live` for a collection's), so the strategy, the reason and
+the maintenance are this table's — an entity chain re-runs, declared —
+and this document stays the only place they are decided.
+
 **This table is normative.** Every row is implemented and tested;
 nothing outside it is attempted. Classification reads the compiled
 PLAN (never the raw document), so "extractable" below means exactly
@@ -260,7 +277,11 @@ state. `externals` are fixed at registration — a query whose inputs
 change is a new registration.
 
 Maintenance runs synchronously inside patch delivery, in commit
-order, on the store's own connection. Writes from ANOTHER connection
+order, on the store's own connection. Delivery is never re-entered: a
+write made from inside an observer or a subscriber commits at once,
+but its record is queued and delivered after the current record has
+reached every consumer, so sibling live views see commits in commit
+order rather than in call-stack order. Writes from ANOTHER connection
 are invisible to capture (§6) and therefore to live queries; the
 coarse `dataVersion()` signal and the §11 topology are the honest
 answers, and re-registering re-reads.
@@ -375,9 +396,11 @@ ERRORING rather than degrading (the D14 rule — the bound is printed):
 
 Non-claims, in one place: no incremental joins (re-run is the declared
 strategy), no cross-connection invalidation (§6's `data_version` is
-the signal), no maintenance over asynchronous connections in this
-version (every current driver is synchronous; the browser driver's
-order owns that story), no replication, and no ordering guarantee for
+the signal), no maintenance over asynchronous connections —
+`capabilities.live` is `false` there and a registration is `JD0051`
+naming the reason, because maintenance point-reads rows synchronously
+inside delivery (the wasm driver's oo1 API is synchronous, which is
+why the browser has live queries at all) — no replication, and no ordering guarantee for
 unordered queries beyond §9's determinism.
 
 ## 13. Event time
@@ -404,7 +427,8 @@ live.stats().watermark;          // what it is now
 `eventTime` is a **closed** member set: `path`, `watermark`,
 `allowedLateness` (default 0) and `retention`. Anything else — a
 misspelling, a non-finite epoch, a negative lateness, a `path` that is
-not a singular row selector — is `JD0053` at registration, not a member
+not a singular row selector — is `JD0053` at registration (its
+`docPath` names the collection, `/collections/<name>`), not a member
 quietly ignored. `advance()` refuses a value that is not finite or that
 goes backwards (a `TypeError`), and it is absent on every view
 registered without an `eventTime`. An entity document has no collection
@@ -415,7 +439,12 @@ to place rows in and re-runs, so an `eventTime` on `store.live` is
 
 Two documents, and only these two shapes: `$resample` and `$rolling`
 whose series operand is the collection (`"$[*]"`, or a FLWOR over it
-whose `$where` narrows and whose `$return` is the bare binding).
+whose `$where` narrows and whose `$return` is the bare binding). A
+spec that spells `at` and `value` explicitly — the spelling the query
+language accepts — is maintained: the view folds with the kernel
+reading the declared instant member and the `value` member the spec
+names, and a `value` selector the view cannot follow re-runs with the
+reason named, never a maintained view that dies on its first fold.
 
 - **A bucket view keeps its rows by bucket.** A write touches one bucket
   — two, when it moves a reading across a boundary — and exactly those