@jarenjs/linq 0.56.0 → 0.67.0

package/ARCHITECTURE.md

@@ -198,6 +198,16 @@ residual runs locally, and `explain()` reports the split.
   (`JL0005`) rather than silently materialised — except two providers
   sharing a `scope` (one store's entity sets), whose roots are two
   bindings of one multi-entity input.
+- **Federation is a door, not a default.** `federate({ sources,
+  maxRows, maxBytes })` (`src/federate.js`, QUERY-PEN §12.1) hands back
+  one provider source per name, sharing one scope, so the ordinary join
+  is admitted and the federation executes it: each side's own packed
+  document at its own source, the smaller side into a bounded hash
+  table, the other probed against it, and the caller's document decided
+  in the engine over the two reduced sets. It spells no join semantics
+  of its own — the reduction bounds the FETCH, and a value it cannot
+  key is kept rather than guessed at — and a budget is a refusal
+  (`JL2008`), never a spill.
 - **The engine result shape leaks nowhere.** Every surface — sync,
   async, provider — reproduces `undefined | item | items` exactly,
   which is why the window-wrapper trick exists at all.

package/README.md

@@ -409,6 +409,10 @@ const api = typedClient(openHttpClient(compileContract(shop.document), { baseUrl
 const outcome = await api.invoke('product.save', { id: 1, product });   // Outcome<Product>: ok | conflict, both typed
 ```
 
+An HTTP client takes `typedHttpClient` instead: the same typed client
+plus `bytes` over the opaque operations (`OpaqueOf<typeof shop>`), whose
+success is a live response stream rather than a JSON value.
+
 How to read it: an operation is a kind (`read`, `command`, `subscribe`),
 its input and output schemas by the schema pen, its named errors and its
 binding. A `named()` schema is hoisted into the contract's own `$defs`
@@ -569,14 +573,80 @@ const users = await db.entities.User
 db.entities.User.link(users[0], 'labels', 'admin');          // 'labels' only: the many-to-many members
 await db.saveChanges();                                      // the unit of work: get, mutate, save
 const live = await db.live(db.entities.Post.where((p) => p.stars.ge(3)));   // { result, subscribe, close, mode }
+
+await db.transaction(async (tx) => {                         // a client of its own, inside the transaction
+  tx.entities.Post.add({ title: 'draft', stars: 0, authorId: users[0].id });
+  await tx.saveChanges();                                    // its own unit of work: nobody else sees it
+});
 ```
 
+`createDbLedger(db)` is the third export: the `@jarenjs/contract`
+idempotency ledger over a declared collection of the store the client
+opened — root claims under an immediate transaction so two processes
+see one `new`, a transaction client's settlements inside the host's own
+transaction, a persisted generation fence (`JL2007` for a stale ref) —
+with no edge from the contract package to a store
+([DB-CLIENT §2.6](docs/DB-CLIENT.md#26-the-ledger)).
+
 How to read it: `db.entities.Post` is a chain root typed from the model,
 so `p.stars` is a number in the editor and `p.author.email` is a
 declared hop; `include` is a typed `load` spec and answers a two-level
 graph in ONE statement; a write is the unit of work — get an entity,
 mutate it, `saveChanges()` — and `live` re-answers a chain when the
-store changes. This subpath is the package's one runtime edge: it
+store changes.
+
+Every large read is a real cursor or a bounded page. A `for await`
+over a chain pulls one row per item from an open statement and a
+`break` releases it (three rows of twenty thousand cost three rows);
+`graph.cursor()` yields one root graph per pull with its includes
+attached, every include bounded per root (`maxRows`, `maxBytes`, a
+coded refusal — never a truncated graph); and `graph.page({ limit,
+after, maxBytes })` — `db.entities.Post.graph()` opens a graph with
+nothing included — pages over a composite keyset with the primary key
+appended, answering `{ items, continuation, hasMore, snapshot }`
+whose continuation is typed by the declared `orderBy`/`thenBy` and is
+unsigned and structural: the host signs it. The store's `explain()`
+says what each read will do (`streaming`, `barrier`, `budget`) before
+it runs:
+
+```js
+for await (const post of db.entities.Post.where((p) => p.stars.ge(3))) {   // one row per pull
+  if (post.stars > 100) break;                                              // the statement is released here
+}
+const page = await db.entities.Post.graph()
+  .orderByDescending((p) => p.stars).thenBy((p) => p.pid)
+  .page({ limit: 20, maxBytes: 65536 });                                    // { items, continuation, hasMore, snapshot: false }
+const next = await db.entities.Post.graph()
+  .orderByDescending((p) => p.stars).thenBy((p) => p.pid)
+  .page({ limit: 20, after: page.continuation });                            // the same ordering, or JD0035
+```
+
+`transaction` hands its callback a client of the same shape, over the
+store INSIDE the transaction, with a unit of work of its own — so two
+request handlers on one client hold two records for the same entity key
+and neither sees the other's pending state. The outer `db.entities.X` is
+by construction an unrelated caller: from inside, it waits for the commit
+and then names itself `JD0012` rather than joining a transaction it is
+not part of. One client is safe for a handler per request. The
+transaction client is pinned to its EXACT scope — a handle kept past its
+callback refuses `JD2070` instead of following a later transaction — and
+forwards the store's `tx.savepoints` (MODEL-FORMAT §5.2), so a callback
+can create, roll back to and release a named checkpoint mid-transaction
+without throwing for control flow:
+
+```js
+await db.transaction(async (tx) => {
+  await tx.savepoints.create('before-optional-import');
+  tx.entities.Post.add({ title: 'optional', stars: 0, authorId: users[0].id });
+  const report = await tx.saveChanges();                     // landed inside the transaction
+  if (report.fallbacks > 0) {                                // …until the caller changes its mind
+    await tx.savepoints.rollbackTo('before-optional-import');  // the add is pending again
+  }
+  await tx.savepoints.release('before-optional-import');     // the checkpoint is spent; the rest commits
+});
+```
+
+This subpath is the package's one runtime edge: it
 imports `@jarenjs/db`, `@jarenjs/validate` and `@jarenjs/formats` as
 OPTIONAL peer dependencies, so `npm install @jarenjs/linq` alone
 installs nothing new and the `.` entry carries not one byte of them
@@ -590,7 +660,7 @@ against Prisma, Drizzle and Kysely — is
 A pen builds a **definition** — once, at module load — and the engine
 compiles the document it emitted. That is the only place its price is
 paid, and `benchmark/db.js` measures it as ns per build beside the
-hand-written literal each pen must emit byte for byte — <!--fact:linq.penBuildCost-->schema 61.1×, model 87.1×, JSLT 72.1× a hand-written literal, and the migration pen 1.4× a hand-written document carrying the same two shape hashes<!--/fact-->.
+hand-written literal each pen must emit byte for byte — <!--fact:linq.penBuildCost-->schema 55.7×, model 89.4×, JSLT 61.2× a hand-written literal, and the migration pen 1.4× a hand-written document carrying the same two shape hashes<!--/fact-->.
 
 Multiples that size are what typed builders, `$defs` hoisting, a
 deep-freeze and a coded refusal per mistake cost against typing the JSON
@@ -626,3 +696,24 @@ you don't want this package.
 The normative mapping — every operator, its emitted phrase, and the
 deliberate deviations — is [docs/QUERY-PEN.md](docs/QUERY-PEN.md);
 internals are in [ARCHITECTURE.md](ARCHITECTURE.md).
+
+## Exports
+
+Every subpath a consumer can import, derived from the manifest by
+`npm run docs:derive` (`npm run docs:check` fails when the two drift):
+
+<!--fact:exports.linq-->
+| Import | Kind | Declarations |
+|---|---|---|
+| `@jarenjs/linq` | JavaScript | declared |
+| `@jarenjs/linq/schema` | JavaScript | declared |
+| `@jarenjs/linq/model` | JavaScript | declared |
+| `@jarenjs/linq/jslt` | JavaScript | declared |
+| `@jarenjs/linq/migration` | JavaScript | declared |
+| `@jarenjs/linq/contract` | JavaScript | declared |
+| `@jarenjs/linq/flow` | JavaScript | declared |
+| `@jarenjs/linq/app` | JavaScript | declared |
+| `@jarenjs/linq/forms` | JavaScript | declared |
+| `@jarenjs/linq/db` | JavaScript | declared |
+| `@jarenjs/linq/package.json` | metadata | — |
+<!--/fact-->

package/docs/APP-PEN.md

@@ -1123,7 +1123,7 @@ not look for them:
 
 ## 7. Cost
 
-`@jarenjs/linq/app` builds to **<!--fact:bundle.app-->46,862<!--/fact--> bytes** as a minified,
+`@jarenjs/linq/app` builds to **<!--fact:bundle.app-->47,444<!--/fact--> bytes** as a minified,
 tree-shaken ESM bundle — the figure `scripts/check-tree-shaking.js`
 measures and `npm run test:tree-shaking` reports, published rounded
 beside the other nine subpath prices in
@@ -1133,8 +1133,8 @@ pen and the JSLT pen (state, and views), and no chain module, no
 
 It is the second-largest pen bundle after the client, and the two pens
 it carries are most of it. The three figures the same probe measures,
-side by side: `@jarenjs/linq/schema` <!--fact:bundle.schema-->32,427<!--/fact--> bytes,
-`@jarenjs/linq/jslt` <!--fact:bundle.jslt-->19,124<!--/fact-->, `@jarenjs/linq/app` <!--fact:bundle.app-->46,862<!--/fact-->. The subpath sums do not add — all
+side by side: `@jarenjs/linq/schema` <!--fact:bundle.schema-->33,156<!--/fact--> bytes,
+`@jarenjs/linq/jslt` <!--fact:bundle.jslt-->19,856<!--/fact-->, `@jarenjs/linq/app` <!--fact:bundle.app-->47,444<!--/fact-->. The subpath sums do not add — all
 three carry the capture, the expression lowering and the JSON boundary,
 which each bundle counts once — so what the app pen costs a consumer who
 already imports the schema pen is the difference the numbers do state:

package/docs/CONTRACT-PEN.md

@@ -239,11 +239,12 @@ they exist so a mismatch is a compile error rather than a 404.
 | Method | Emits | Type reading | Status |
 |---|---|---|---|
 | `typedClient(client, contract)` | — (identity) | `TypedClient<C>`: `invoke` over the invokable operations, `subscribe` over the subscribe ones, `url` over all of them | native |
-| `typedHandlers(contract, handlers)` | — (identity) | `TypedHandlerTable<C>`: one handler per invokable operation, `(input, ctx) => output \| Failure` | native; a missing or misspelled operation does not compile |
+| `typedHttpClient(client, contract)` | — (identity) | `TypedHttpClient<C>`: `TypedClient<C>` plus `bytes` over `OpaqueOf<C>` — the opaque operations, whose success is a `ByteResponse` (a live stream) rather than the output type; for an `openHttpClient` client only, a local or port client has no `bytes` | native |
+| `typedHandlers(contract, handlers)` | — (identity) | `TypedHandlerTable<C, Host = null, Carrier = 'http'>`: one handler per invokable operation, `(input, ctx) => output \| Failure`; `ctx` is `HandlerContext<Host, Carrier>` — the HTTP context by default, `Host` the host lifecycle's `ctx.host`, a carrier union a discriminated union to narrow on `ctx.carrier` (CONTRACT-FORMAT §7.7) | native; a missing or misspelled operation does not compile, and an HTTP-only member on a port/local context does not either |
 | `typedTools(tools, contract)` | — (identity) | `TypedTool<C>[]`: `name` is the id with `.` → `_`, `execute` takes the operation's ACCEPTED input | native |
 
-All three are `void contract; return x;` at run time — they add nothing,
-wrap nothing and cost nothing. What they do is carry the phantom `Ops`
+All of them are `void contract; return x;` at run time — they add
+nothing, wrap nothing and cost nothing. What they do is carry the phantom `Ops`
 onto a value the engine produced, which is what makes one authored
 document type a client, a server's handler table and an AI toolbox with
 no generate step. §3.6 runs all three over one contract and §5 is what
@@ -1017,8 +1018,11 @@ const handlers = typedHandlers(shop, {
 const served = openLocalClient(compiled, handlers);    // the binding: any contract client
 const api = typedClient(served, shop);                 // the same object, narrowed by the phantom
 const outcome: Outcome<Product> = await api.invoke('product.save', { id: 1, revision: 4, product });
-api.url('image.bytes', { id: 3 });                     // an opaque operation: a URL builder only
+api.url('image.bytes', { id: 3 });                     // an opaque operation: a URL builder here
 api.invoke('image.bytes', { id: 3 });                  // does not compile — it carries bytes
+const web = typedHttpClient(openHttpClient(compiled, { baseUrl }), shop);
+const image = await web.bytes('image.bytes', { id: 3 });  // Outcome<ByteResponse>: { status, headers, media, body: ReadableStream }
+web.bytes('product.save', { id: 1, revision: 4, product });  // does not compile — a JSON operation is invoked, not streamed
 for (const tool of typedTools(contractTools(compiled, api), shop)) toolbox.add(tool);
 
 declare const anyContract: Contract<any>;              // the class: an annotation, never a `new`
@@ -1184,7 +1188,7 @@ to write, and reaching them means one import of `@jarenjs/contract` over
 
 ## 7. Cost
 
-`@jarenjs/linq/contract` builds to **<!--fact:bundle.contract-->44,644<!--/fact--> bytes** as a minified,
+`@jarenjs/linq/contract` builds to **<!--fact:bundle.contract-->45,298<!--/fact--> bytes** as a minified,
 tree-shaken ESM bundle — the figure `scripts/check-tree-shaking.js`
 measures and `npm run test:tree-shaking` reports, published rounded
 (<!--fact:bundle.contract.kb-->45<!--/fact--> kB) beside the other nine subpath prices in
@@ -1196,7 +1200,7 @@ them:
 
 - **the schema pen is included, and that is the ceiling.** A contract's
   inputs and outputs are schemas, so the two are measured together and
-  the bundle carries <!--fact:bundle.schema-->32,427<!--/fact--> of its <!--fact:bundle.contract-->44,644<!--/fact--> bytes as the schema pen's own.
+  the bundle carries <!--fact:bundle.schema-->33,156<!--/fact--> of its <!--fact:bundle.contract-->45,298<!--/fact--> bytes as the schema pen's own.
   The contract pen's own share is the remaining ~12 kB, most of it the
   refusal messages §4 lists;
 - **no chain module** — none of `sequence.js`, `document.js`, `async.js`,

package/docs/DB-CLIENT.md

@@ -83,10 +83,9 @@ invent one. §2 keeps its D3 slot and its meaning — this is where every
 name a caller writes is named — under the title that describes what it
 holds.
 
-The vocabulary is small and the surface is not. Two exported names, and
-then whatever those two hand back: a client of frozen handles, each of
+The exports include the store door and its helpers. The door hands back a client of frozen handles, each of
 which is the store's own set plus the chain plus three additions. §2.1
-divides the two; §2.2 to §2.5 enumerate them.
+divides the responsibilities; §2.2 to §2.7 enumerate the surface.
 
 ### 2.1 What is the store's and what is the client's
 
@@ -105,15 +104,17 @@ decides which document answers a question about behaviour.
 | `client.collections.<name>` | the store's collection | the same chain start and `live`, typed from the pen's collection schema (§2.5) |
 | `saveChanges()`, `transaction(fn)`, `close()`, `capabilities`, `store` | the store's | pass-throughs; `saveChanges` and `live` exist exactly when the model declares entities, as on the store; `store` is the escape hatch, typed `TypedStore` |
 
-### 2.2 The two exported names
+### 2.2 The exported names
 
-The whole export surface: a door, and a type-level reader for what it
-hands back.
+The whole export surface: a door, a type-level reader for what it hands
+back, the durable ledger over what it opened, and replication document authoring.
 
 | Name | Answers | Type reading |
 |---|---|---|
 | `open(model, options)` | a promise of the frozen client — `store`, `capabilities`, `entities`, `collections`, `transaction`, `close`, and `saveChanges`/`live` when the model declares entities | `Client<InferMeta<typeof model>>` for a pen model; `Client<E>` for `open<E>(json, …)`; the wide map for a bare JSON model |
+| `defineReplication(header)` | a logical replication document builder — §2.7 | `ReplicationPen` |
 | `defaultValidator()` | `new JarenValidator({ collectErrors: true })` with `stringFormats` and `dateTimeFormats` registered | `JarenValidator` |
+| `createDbLedger(client, options?)` | the contract idempotency ledger (`claim`/`commit`/`fail`/`lookup`/`sweep`) over a declared collection of the client's store — §2.6 | `DbLedger`; structurally `@jarenjs/contract`'s `Ledger` |
 
 `open` is the only door, and it is deliberately not a coded refusal: a
 missing `options`, or a `validator` that is not a `JarenValidator`, is a
@@ -168,7 +169,7 @@ hands it to `explain()` and asserts `mode: 'native'` with no residual.
 ### 2.4 The graph
 
 `include(pick, spec?)` opens a graph: an immutable builder of the store's
-`load` specification, with 15 members of its own.
+`load` specification, with 17 members of its own.
 
 | Member | Emits | Note |
 |---|---|---|
@@ -177,17 +178,19 @@ hands it to `explain()` and asserts `mode: 'native'` with no residual.
 | `orderBy(key, options?)`, `orderByDescending(key, options?)` | `orderBy` | replaces; `options` is `{ empty?, collation? }` |
 | `thenBy(key, options?)`, `thenByDescending(key, options?)` | appends to `orderBy` | `JL0005` when no `orderBy` precedes it |
 | `take(n)`, `skip(n)` | `take`, `skip` | the offset window |
-| `after(cursor)` | `after` | the keyset cursor (§10.5); the ROOT only |
+| `after(cursor)` | `after` | the keyset continuation (§10.5) a `page()` over the same ordering emitted — typed by the declared ordering, so a bare key does not compile; the ROOT only |
 | `maxDepth(n)` | `maxDepth` | the include depth bound (§10.4) |
 | `asNoTracking()` | — | changes the load, never the document |
 | `toSpec()`, `toJSON()` | the spec | plain deep-frozen JSON, a snapshot: mutating it changes nothing, and two builds are one document |
 | `toArray()` | — | `load(spec)`: the store's one statement |
-| `explain()` | — | `explainLoad(spec)`: the SQL, the includes, the pagination strategy |
+| `cursor(options?)` | — | `loadCursor(spec, options)`: one root graph per pull from that same statement, its includes attached and bounded per root; `return()` releases it; `{ signal?, tracking? }` — untracked unless `tracking: true` |
+| `page(options?)` | — | `page(spec, options)`: one bounded page over the composite keyset — `{ items, continuation, hasMore, snapshot }`, never more than `limit` roots or `maxBytes` bytes; `{ limit?, after?, maxBytes?, consistency?, signal?, tracking? }`; a `take`/`skip` on the graph beside it is the store's `JD0032` |
+| `explain()` | — | `explainLoad(spec)`: the SQL, the includes, the pagination strategy, the per-root bounds |
 
 The spec's member order is fixed — `where, orderBy, take, skip, after,
 maxDepth, include` at the root; `where, orderBy, take, skip, count,
-include` in an include — so one graph is one document however it was
-built. An include spec is `true` (or absent) for the rows, `{ count:
+maxRows, maxBytes, include` in an include — so one graph is one document
+however it was built. An include spec is `true` (or absent) for the rows, `{ count:
 true }` for the number, or an object of clauses:
 
 | Spec member | Emitted | Note |
@@ -198,6 +201,7 @@ true }` for the number, or an object of clauses:
 | `orderBy: (p) => p.pid` | `orderBy: "$it.pid"` | a bare key, ascending |
 | `orderBy: { key, desc?, empty?, collation? }` | `orderBy: { $key, $dir, $empty, $collation }` | as the chain spells `$orderby`; an array of either is an array |
 | `take`, `skip` | `take`, `skip` | the window inside the subquery (a non-integer is the store's `JD0032`) |
+| `maxRows`, `maxBytes` | `maxRows`, `maxBytes` | the per-root bounds (MODEL-FORMAT §10.4): rows of the relation per parent and serialised bytes per parent; crossing one is the store's `JD2073`, never a truncated graph. Defaults 1000 rows / 1 MiB (a `take` is the row bound of the include it windows); `Infinity` spells the unbounded case and emits as `null` |
 | `include: { comments: spec }` | `include: { comments: <lowered> }` | over the TARGET's relation table (the scope carries every root's) |
 | anything else | `JL0101` | the vocabulary is closed; `after` paginates the root, never an include |
 
@@ -233,6 +237,78 @@ because a collection has no relations and no tracking — and neither does
 its client: a collections-only model opens a client with no
 `saveChanges` and no `live` of its own, exactly as the store does.
 
+### 2.6 The ledger
+
+`createDbLedger(client, { collection = 'ledger', ttlMs = 86_400_000,
+runtime, now })` is the `Ledger` the `@jarenjs/contract` http binding
+calls under `policy.idempotency` (CONTRACT-FORMAT.md §8), over a
+declared collection of the store the client opened — the collection
+`idempotencyLedgerModel` declares, or any collection with that
+record's schema (`collection` names it; a name the model does not
+declare is a `TypeError` at construction, not at the first claim).
+The implementation is the client's own surface and nothing else: it
+imports no contract module, no driver, no store; the record it writes
+is exactly the model's, and the id is the same versioned JSON tuple the
+memory ledger spells (`1:["op","scope","key"]`, injective over `|`,
+control characters and Unicode). The contract package keeps its D1
+edge: it depends on no store, and this door depends on no contract.
+
+**Which client decides the transaction.** A root client (the one `open`
+answered) runs every claim, settlement, lookup and sweep in a
+transaction of its own with `mode: 'immediate'` — the write lock taken
+before the read, so two processes claiming one key from one file see
+exactly one `new` and the other `in-progress`, never two handlers. The
+client a transaction callback received runs them as savepoints inside
+that transaction instead: a domain write and the settlement then
+commit together or roll back together — the ledger a lifecycle
+settlement lease carries. Atomicity is same-store only: a ledger on
+one file and a domain write on another are two commits.
+
+**The generation fence.** A `new` claim mints a `generation` (the
+runtime record's `uuid`), persists it with the record and hands it
+back in the ref (`{ id, generation }`). `commit`/`fail` settle the
+record whose id AND generation the ref names while it is `started`; a
+ref whose key expired, was reclaimed under a newer generation, or was
+settled already is refused with **`JL2007`** (rejected), and the
+record it would have touched is unchanged — across processes and
+restarts, because the generation is in the file. The binding reports
+the refusal to its `onError`; the response still goes out.
+
+**Clocks and expiry.** `now` wins, then the runtime record's clock;
+given neither, the ledger follows the instants the binding passes with
+each call (a host-side `lookup`/`sweep` without one uses the latest).
+A record past `expiresAt` is dropped on `claim` and `lookup`;
+`sweep(now?)` drops every expired record and answers the count. A
+record written under the earlier `"<op>|<scope>|<key>"` id spelling
+is matched by no claim: it expires by its own `expiresAt`, or a host
+rewrites its `id` once with `ledgerId` from `@jarenjs/contract/ledger`.
+
+```js
+import { open, createDbLedger } from '@jarenjs/linq/db';
+import { nodeDriver } from '@jarenjs/db/node';
+import { idempotencyLedgerModel } from '@jarenjs/contract/ledger';
+import { serveHttp } from '@jarenjs/contract/http';
+
+const db = await open(idempotencyLedgerModel, { driver: nodeDriver(), path: 'ledger.db' });
+const server = serveHttp(contract, handlers, { ledger: createDbLedger(db) });   // root: immediate claims
+
+await db.transaction(async (tx) => {                          // a settlement inside the host's transaction
+  await tx.collections.orders.insert(order);
+  await createDbLedger(tx).commit(ref, response);             // commits with the order, or not at all
+});
+```
+
+### 2.7 Replication documents
+
+The DB client forwards `replication` open options to its Store. Access committed
+pages, frontiers, conflicts and resets through `client.store.replication`.
+`defineReplication({ replica, seq, frontier, model })` authors a logical envelope:
+chain `.change(table, key, before, after)`, then `.toDocument()` or `.toJSON()`.
+It shares the Store's normalization authority and preserves operation order.
+See the [replication format](../../db/docs/REPLICATION-FORMAT.md) for causality,
+conflict policy and bounded reset contracts. Authoring does not allocate a
+committed sequence; normal replication exports the Store's committed pages.
+
 ## 3. Worked examples
 
 The client's examples are not builder-to-document pairs, and this is
@@ -632,8 +708,11 @@ wrong — see [MODEL-PEN.md](MODEL-PEN.md) §5.
   and only the root, because the cursor is a key of the root entity and
   there is one root per load. `{ after: 1 }` inside a spec is `JL0101`
   naming the graph's own `after()` (§4.1); `.after(cursor)` on the graph
-  is the spelling that works, and the graph's `after` is typed `M['key']`
-  so a cursor of the wrong type does not compile.
+  is the spelling that works, and the graph's `after` is typed by the
+  declared ordering — the continuation a `page()` over the same
+  `orderBy`/`thenBy` chain emitted, its `keys` tuple following the
+  ordering and its `key` the row's primary key — so a bare key, or a
+  continuation with the wrong number of values, does not compile.
 
 ### 5.4 What the pin holds
 
@@ -655,7 +734,7 @@ void client.entities.Post.where((p) => p.strs.ge(3));        // a misspelled mem
 void client.entities.User.include((u) => u.email);           // not a relation member
 void client.entities.User.include((u) => u.posts, { where: (p) => p.email.eq('x') });  // the target's shape
 void client.entities.Post.include((p) => p.author, { include: { nope: true } });       // the target's relations
-void client.entities.Post.include((p) => p.author).after('one');  // the cursor is the key's type
+void client.entities.Post.include((p) => p.author).after('one');  // the cursor is the ordering's continuation, never a bare key
 client.entities.User.link('u1', 'posts', 1);                 // oneToMany is not a membership
 client.entities.Post.link(1, 'author', 'u1');                // oneToOne is not a membership
 client.entities.User.link('u1', 'labels', 42);               // the target's key type
@@ -747,10 +826,10 @@ never builds one; the migration between two of them is
 
 ## 7. Cost
 
-`@jarenjs/linq/db` builds to **<!--fact:bundle.db-->478,172<!--/fact--> bytes** as a minified,
+`@jarenjs/linq/db` builds to **<!--fact:bundle.db-->623,994<!--/fact--> bytes** as a minified,
 tree-shaken ESM bundle — the figure `scripts/check-tree-shaking.js`
 measures and `npm run test:tree-shaking` reports, published rounded
-(<!--fact:bundle.db.kb-->478<!--/fact--> kB) beside the other nine subpath prices in
+(<!--fact:bundle.db.kb-->624<!--/fact--> kB) beside the other nine subpath prices in
 [docs/CONSUMING.md](../../../docs/CONSUMING.md).
 
 It is by far the largest of the ten, and the reason is §1.1's edge rather
@@ -777,7 +856,7 @@ What the probe asserts, and fails the build on:
   asserts the same exclusion.
 
 A consumer who wants the model pen's types without the store pays
-`./model`'s <!--fact:bundle.model-->40,857<!--/fact--> bytes and installs no peer; one who wants to run
+`./model`'s <!--fact:bundle.model-->41,582<!--/fact--> bytes and installs no peer; one who wants to run
 queries against an array rather than a database pays the chain's price
 (§17 of [QUERY-PEN.md](QUERY-PEN.md)) and installs no peer. `./db` is
 the one subpath whose `package.json` entry carries an optional peer at
@@ -790,7 +869,7 @@ beside Prisma, Drizzle and Kysely over the same SQLite corpus, equality
 asserted before anything is timed and statement counts printed beside
 the timings.
 
-Against the store it fronts, the door is nearly free: <!--fact:orm.clientDoorPrice-->0.9× on a point read, 1.4× on an indexed predicate at 10 % selectivity, 1.0× on the two-level graph load<!--/fact-->
+Against the store it fronts, the door is nearly free: <!--fact:orm.clientDoorPrice-->1.0× on a point read, 1.0× on an indexed predicate at 10 % selectivity, 1.1× on the two-level graph load<!--/fact-->
 — because it issues the same documents the store would. What it does
 NOT amortize is capture: a chain re-captures its callbacks and re-emits
 its document on **every** call, by design, which is the predicate row's
@@ -798,7 +877,7 @@ difference and which a caller with a hot query removes by holding the
 `Sequence` (or the emitted document) instead of rebuilding it.
 
 Against the rivals, at this corpus, it is faster on <!--fact:orm.clientVsRivals-->8 of 9 against Prisma, 4 of 9 against Drizzle, 1 of 9 against Kysely<!--/fact-->,
-and here is every row where the *fastest* rival beats it — <!--fact:orm.clientLosses-->update one column by primary key 18.8× (Drizzle), nested json member filter 6.3× (Kysely), cold start 3.0× (Prisma), posts per user 2.4× (Kysely), graph load 2.2× (Kysely), indexed predicate over 500 users, ids only 2.0× (Kysely), pagination over 5000 comments, page size 20 1.6× (Kysely), insert 1.4× (Kysely), point read by primary key 1.2× (Drizzle)<!--/fact-->.
+and here is every row where the *fastest* rival beats it — <!--fact:orm.clientLosses-->update one column by primary key 13.1× (Drizzle), nested json member filter 5.8× (Kysely), cold start 3.4× (Prisma), graph load 2.8× (Kysely), posts per user 2.4× (Kysely), indexed predicate over 500 users, ids only 1.7× (Kysely), insert 1.6× (Kysely), pagination over 5000 comments, page size 20 1.6× (Kysely), point read by primary key 1.4× (Drizzle)<!--/fact-->.
 
 Three things make that list readable rather than damning, and none of
 them removes a row from it. **Kysely is a SQL builder**: on every row it

package/docs/FLOW-PEN.md

@@ -325,7 +325,7 @@ export const writing = defineDag({
   nodes: {
     brief: input(),
     draft: task('llm', (v) => ({ prompt: v.topic })),
-    review: task('critic', (v) => ({ text: v })).checkpoint(),
+    review: task('critic', (v) => ({ text: v }), { version: '1' }).checkpoint(),
     out: output(),
   },
   edges: [
@@ -342,7 +342,7 @@ export const writing = defineDag({
   "nodes": {
     "brief": { "kind": "input" },
     "draft": { "kind": "task", "run": "llm", "with": { "prompt": "$.topic" } },
-    "review": { "kind": "task", "run": "critic", "with": { "text": "$" }, "checkpoint": true },
+    "review": { "kind": "task", "run": "critic", "version": "1", "with": { "text": "$" }, "checkpoint": true },
     "out": { "kind": "output" }
   },
   "edges": [
@@ -353,6 +353,13 @@ export const writing = defineDag({
 }
 ```
 
+`review` carries a `version` because it is checkpointed: a recorded value
+is replayed on a later run only while the handler that produced it is the
+same one, so that identity is DECLARED — the registry must hand
+`compileDag` the same token as `{ run, version }`, and a disagreement is
+`JF0019` before any node runs. `.checkpoint()` refuses a task that has
+not declared one.
+
 `review`'s `with` is `{ "text": "$" }`: the callback returned the scope
 value itself, and the scope value of a node with one unported inbound
 edge IS the delivered value, verbatim (§6.1). `checkpoint: true` is
@@ -978,10 +985,10 @@ meaning is a `$return` that constructs an array explicitly.
 
 ## 7. Cost
 
-`@jarenjs/linq/flow` builds to **<!--fact:bundle.flow-->19,181<!--/fact--> bytes** as a minified,
+`@jarenjs/linq/flow` builds to **<!--fact:bundle.flow-->19,910<!--/fact--> bytes** as a minified,
 tree-shaken ESM bundle — the figure `scripts/check-tree-shaking.js`
 measures and `npm run test:tree-shaking` reports, published rounded
-(<!--fact:bundle.flow.kb-->19<!--/fact--> kB) beside the other nine subpath prices in
+(<!--fact:bundle.flow.kb-->20<!--/fact--> kB) beside the other nine subpath prices in
 [docs/CONSUMING.md](../../../docs/CONSUMING.md).
 
 The probe is a gate, not a report. Building a machine with a guard and
@@ -1008,7 +1015,7 @@ two effects as a consumer would — `defineFsm`, `state`, `on` and
   `packages/linq/src/flow/`.
 
 Two documents, two grammars, thirteen exported names — and 57 bytes more
-than `./jslt`'s <!--fact:bundle.jslt-->19,124<!--/fact-->, which writes one. The reason is that most of
+than `./jslt`'s <!--fact:bundle.jslt-->19,856<!--/fact-->, which writes one. The reason is that most of
 both prices is the same shared machinery: the recording proxy
 (`expression.js`), the root capture (`capture-root.js`) and the JSON
 boundary (`json-boundary.js`). What this pen adds on top of them is 685

package/docs/FORMS-PEN.md

@@ -925,7 +925,7 @@ for this pen at all.
 
 ## 7. Cost
 
-`@jarenjs/linq/forms` builds to **<!--fact:bundle.forms-->36,587<!--/fact--> bytes** as a minified,
+`@jarenjs/linq/forms` builds to **<!--fact:bundle.forms-->37,312<!--/fact--> bytes** as a minified,
 tree-shaken ESM bundle — the figure `scripts/check-tree-shaking.js`
 measures and `npm run test:tree-shaking` reports, published rounded
 beside the other nine subpath prices in
@@ -934,7 +934,7 @@ pen it subclasses, and no chain module, no `@jarenjs/forms` byte and no
 model pen.
 
 Most of that figure is the schema pen: `@jarenjs/linq/schema` alone
-is <!--fact:bundle.schema-->32,427<!--/fact--> bytes, so the whole `x-form` vocabulary — the mixin, the rule
+is <!--fact:bundle.schema-->33,156<!--/fact--> bytes, so the whole `x-form` vocabulary — the mixin, the rule
 capture, the submit transform and their refusal messages — is about 4 kB
 on top of a pen a form-shaped consumer usually already carries. A
 consumer importing both subpaths pays the schema pen once.

package/docs/JSLT-PEN.md

@@ -919,10 +919,10 @@ non-judgement is itself gated.
 
 ## 7. Cost
 
-`@jarenjs/linq/jslt` builds to **<!--fact:bundle.jslt-->19,124<!--/fact--> bytes** as a minified,
+`@jarenjs/linq/jslt` builds to **<!--fact:bundle.jslt-->19,856<!--/fact--> bytes** as a minified,
 tree-shaken ESM bundle — the figure `scripts/check-tree-shaking.js`
 measures and `npm run test:tree-shaking` reports, published rounded
-(<!--fact:bundle.jslt.kb-->19<!--/fact--> kB) beside the other nine subpath prices in
+(<!--fact:bundle.jslt.kb-->20<!--/fact--> kB) beside the other nine subpath prices in
 [docs/CONSUMING.md](../../../docs/CONSUMING.md).
 
 The probe is a gate, not a report. Building a stylesheet as a consumer
@@ -948,8 +948,8 @@ source. That makes it the SMALLEST of the nine pen bundles, and the
 reason is that a stylesheet is mostly bodies, and a body is the shared
 machine every pen already pays for.
 
-Two figures worth reading beside it: `./migration` (<!--fact:bundle.migration-->23,599<!--/fact--> bytes)
+Two figures worth reading beside it: `./migration` (<!--fact:bundle.migration-->24,259<!--/fact--> bytes)
 carries this pen's `body()` and pays for it, which is why the two prices
-sit so close; and `./flow` (<!--fact:bundle.flow-->19,181<!--/fact--> bytes) is within 60 bytes of this one
+sit so close; and `./flow` (<!--fact:bundle.flow-->19,910<!--/fact--> bytes) is within 60 bytes of this one
 despite writing two formats, because it shares the same capture and adds
 almost nothing but member checks and their messages.