@jarenjs/db 0.46.5 → 0.56.0

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
@@ -113,12 +189,29 @@ shape binds at `store.collection<User>('users')`.
   decided or merely narrowed. The worked example, the geofence and the
   measured numbers are in [Spatial storage](#spatial-storage--the-model-the-plan-the-fence-the-numbers)
   below.
+- **A time series is a composite index, not a storage kind.** Declare
+  `{ "path": ["$.series", "$.at"] }` over a numeric epoch member and the
+  planner recognizes three shapes over it: a half-open range under a
+  series equality, an as-of lookup (the index read backwards, one row),
+  and a fixed-width bucket ladder — a `$groupby` over `$time-bucket`, or
+  a `$resample` whose spec asks for nothing a `GROUP BY` cannot do — as
+  integer arithmetic in SQL. A fill policy, a calendar width, a rolling
+  window and an as-of JOIN are **named refinements**: the index bounds
+  the fetch and `@jarenjs/core/series` decides, with `explain().series`
+  carrying the reason code and the last run's actual candidate and
+  result counts. See [Time series](#time-series--the-index-the-ladder-the-refinement).
 - **Migrations are documents.** `planMigration` diffs two models into
   rendered-DDL + JSLT-transform + assertion steps; a shadow database
   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
@@ -228,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
@@ -252,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
@@ -378,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 |
@@ -391,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
@@ -407,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
@@ -425,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.
 
@@ -445,6 +538,92 @@ and unindexed — and every entry must answer identically, including a
 deliberate one-binary32-ulp near-tie and the windows that reach past the
 scored rows into the tail the column cannot rank.
 
+## Time series — the index, the ladder, the refinement
+
+The physical declaration is one a model already has:
+
+```json
+{ "name": "by_series_at", "path": ["$.series", "$.at"] }
+```
+
+No `derive` kind, no column type, no host function, no extension. What
+the planner adds is the reading of that index — a B-tree seeks as far
+as its leading columns are decided, so a query that pins `series` with
+an equality and ranges over `at` is a SEARCH, and one that only bounds
+`at` is a scan the plan says so about.
+
+```js
+// native: SEARCH sample USING INDEX sample_by_series_at (gx_series=? AND gx_at>? AND gx_at<?)
+await sample.execute({
+  $for: { s: '$[*]' },
+  $where: { $and: [
+    { $eq: ['$s.series', 'sensor-a'] },
+    { $ge: ['$s.at', from] },
+    { $lt: ['$s.at', to] },
+  ] },
+  $orderby: [{ $key: '$s.at' }],
+  $return: '$s',
+});
+
+// native: the same index, GROUP BY over integer bucket arithmetic
+await sample.execute({ $resample: [
+  { $for: { s: '$[*]' }, $where: { $eq: ['$s.series', 'sensor-a'] }, $return: '$s' },
+  { every: 'PT1M', aggregate: 'mean' },
+] });
+
+// hybrid: the index bounds the fetch, rollingSeries decides
+await sample.execute({ $rolling: [
+  { $for: { s: '$[*]' }, $where: { $eq: ['$s.series', 'sensor-a'] }, $return: '$s' },
+  { width: 'PT1M', aggregate: 'mean', minPeriods: 30 },
+] });
+```
+
+**The numbers, the loss included.** `benchmark/series.js` answers the
+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 <!--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: <!--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
+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`, `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
+number.
+
+**The as-of join is bounded, and the bound is the claim.** `$asof` with
+the collection on the right reads the probes it was given, bounds the
+fetch by their own span and by a membership test over their `by` keys,
+and issues exactly ONE statement whatever the probes number — the
+failure mode a batch exists to refuse is one seek per left row, and
+`test/db/statement-count.test.js` pins it at 1, 10 and 200 probes.
+Without a `tolerance` a backward join can only be bounded ABOVE, so
+that one statement can read most of a long history: the benchmark
+publishes the candidate count beside the timing rather than netting it
+out, and at fifty-one probes over a hundred thousand rows the batch
+LOSES to fifty-one separate index reads. Few questions of a large
+series belong to a batch; a join of two series does.
+
+**One corpus, five executors, proven to agree.** The committed temporal
+corpus (`test/json/fixtures/series-corpus.json`) runs through the plain
+references, the query vocabulary, `node:sqlite`, a real wasm build and
+both drivers again with pushdown forced off — indexed and unindexed —
+and every case must answer identically, plan mode and reason codes
+included.
+
 ## What SQLite-only means, frankly
 
 SQLite is the supported backend — 3.45 or newer, on `node:sqlite`,
@@ -479,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
@@ -493,7 +684,7 @@ SQLite's own story (WAL plus a busy timeout, both set and visible on
   journal where it does not (`bun:sqlite`, the wasm build). One diff
   format runs store → patch → live query → O(k) render. Capture is
   opt-in; the overhead is published, not waved away.
-- **Live queries** (LIVE-FORMAT §§7–12): `collection.live(document)`
+- **Live queries** (LIVE-FORMAT §§7–13): `collection.live(document)`
   maintains a result as writes arrive and emits patches — incremental
   for `where`/`select`/`orderBy`+`limit`/aggregates/single-level
   `groupBy` and a spatial `where` over a derived index (the geofence;
@@ -501,6 +692,11 @@ SQLite's own story (WAL plus a busy timeout, both set and visible on
   **declared, never silent** (`live.mode` names the reason).
   Unaffected rows stay reference-identical; a seeded oracle holds the
   maintained result equal to a fresh re-query after every mutation.
+- **Event time** (LIVE-FORMAT §13): a `$resample` or `$rolling` view
+  over a fixed width maintains exact event-time buckets and windows
+  against a watermark the HOST supplies — never a clock — and a reading
+  behind the declared lateness re-reads and emits a `lateData` record
+  rather than being folded in as though it had arrived on time.
 - **Durable runs and the job queue** (JOBS-FORMAT, FLOW-FORMAT §7.6):
   a `@jarenjs/flow` DAG run checkpoints declared nodes and RESUMES
   after a crash; `store.jobs` leases work in one guarded statement
@@ -510,7 +706,41 @@ 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
+
+`benchmark/live.js` maintains a 60 s bucket ladder and a 5 minute
+rolling window over a seeded series and rewrites one reading per commit,
+inside the lateness the view allows. The maintained rows are checked
+against `resampleSeries` / `rollingSeries` over the **whole** collection
+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.
+
+<!--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× |
+<!--/fact-->
+
+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
+emitted diff walks every one of them whatever changed. A bucket view
+also holds one maintained entry per reading *plus* one per bucket, which
+is over §12's default `maxMaintained` at ten thousand readings — the
+bound errors rather than degrading, and raising it is a decision
+somebody makes.
 
 ## Sync-readiness — what exists and what does not
 
@@ -540,13 +770,17 @@ replication on these primitives is a roadmap item, not a hint.
   priority classes, no cron, no workflow compensation.
 - **Live-query maintenance is limited to the declared table** (§7);
   joins, entity queries and non-canonical shapes re-run, reported.
+- **`eventTime.retention` bounds repair work, not memory.** It is the
+  horizon a view claims and is checked against the window it maintains;
+  the maintained state is still bounded by `live.maxMaintained`, and no
+  version of this compacts a bucket's rows away.
 - **The wasm build journals** (its session extension is not yet
   adapted); OPFS needs a secure context, and where it is absent the
   store runs in memory with the durability difference stated.
-- **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
@@ -554,7 +788,7 @@ profile §8, entities §9, relational translation §10, the unit of work
 §11), [docs/MIGRATION-FORMAT.md](docs/MIGRATION-FORMAT.md) (documents
 §§1–8, relational changes §§9–12),
 [docs/LIVE-FORMAT.md](docs/LIVE-FORMAT.md) (capture §§1–6, live queries
-§§7–12) and [docs/JOBS-FORMAT.md](docs/JOBS-FORMAT.md) (the durable
+§§7–12, event time §13) and [docs/JOBS-FORMAT.md](docs/JOBS-FORMAT.md) (the durable
 queue §§1–9); the seams, the pushdown contract and every engine are in
 [ARCHITECTURE.md](ARCHITECTURE.md); the benchmark methodology is in
 [benchmark/README.md](../../benchmark/README.md).

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.