@jarenjs/linq 0.56.0 → 0.67.0

package/docs/LINQ-FORMAT.md

@@ -35,17 +35,17 @@ is the index of the ten, and it is how a reader reaches any of them.
 <!--fact:pens.index-->
 | Document | Lines | What it writes, and when to open it |
 |---|---:|---|
-| [LINQ-FORMAT.md](LINQ-FORMAT.md) | 812 | this file, the binder and the family's **normative reference**: what a pen is, the rules all of them keep, the shared `JL01xx` table, and the cross-pen views derived from the ten guides it indexes. **Read it when** you want a rule that is true of every pen, an index of the eleven documents, or one place to look up a method without knowing which pen owns it |
-| [QUERY-PEN.md](QUERY-PEN.md) | 1,636 | the chain, `.` — query documents (`jaren-query`) and the provider seam. **Read it when** you are querying data, or implementing a provider that answers a query document |
+| [LINQ-FORMAT.md](LINQ-FORMAT.md) | 820 | this file, the binder and the family's **normative reference**: what a pen is, the rules all of them keep, the shared `JL01xx` table, and the cross-pen views derived from the ten guides it indexes. **Read it when** you want a rule that is true of every pen, an index of the eleven documents, or one place to look up a method without knowing which pen owns it |
+| [QUERY-PEN.md](QUERY-PEN.md) | 1,724 | the chain, `.` — query documents (`jaren-query`) and the provider seam. **Read it when** you are querying data, or implementing a provider that answers a query document |
 | [SCHEMA-PEN.md](SCHEMA-PEN.md) | 1,218 | `./schema` — JSON Schema 2020-12: the structural keywords, the constraints and the annotations, each with a method of its own, plus `$query`, `$defs`/`$ref` recursion and the normalizer's per-field predicates. **Read it when** you are describing the shape of data — for validation, for a form, or as the base of an entity |
-| [MODEL-PEN.md](MODEL-PEN.md) | 1,083 | `./model` — the `x-entity` vocabulary on JSON Schema, and the `$model` 0.1 document `openStore` accepts unchanged. **Read it when** you are declaring a store's entities, their keys and their relations |
+| [MODEL-PEN.md](MODEL-PEN.md) | 1,092 | `./model` — the `x-entity` vocabulary on JSON Schema, and the `$model` 0.1 document `openStore` accepts unchanged. **Read it when** you are declaring a store's entities, their keys and their relations |
 | [JSLT-PEN.md](JSLT-PEN.md) | 955 | `./jslt` — `$jslt` 0.1 stylesheets: the envelope and its rules, whose bodies are captured over the matched value. **Read it when** you are transforming one document into another |
 | [MIGRATION-PEN.md](MIGRATION-PEN.md) | 781 | `./migration` — `$migration` 0.1 documents: the two shape hashes and the ordered steps the runner takes. **Read it when** you are moving a store from one model to the next |
-| [CONTRACT-PEN.md](CONTRACT-PEN.md) | 1,217 | `./contract` — `$contract` 0.1 documents: the operations, their schemas, their declared behavior and their REST binding. **Read it when** you are declaring an API and want its client, its server and its tools typed from one document |
-| [FLOW-PEN.md](FLOW-PEN.md) | 1,026 | `./flow` — `jaren-fsm` 0.1 machines and `jaren-dag` 0.1 dataflows, every query-valued member captured. **Read it when** you are declaring a state machine or a dependency graph of tasks |
+| [CONTRACT-PEN.md](CONTRACT-PEN.md) | 1,221 | `./contract` — `$contract` 0.1 documents: the operations, their schemas, their declared behavior and their REST binding. **Read it when** you are declaring an API and want its client, its server and its tools typed from one document |
+| [FLOW-PEN.md](FLOW-PEN.md) | 1,033 | `./flow` — `jaren-fsm` 0.1 machines and `jaren-dag` 0.1 dataflows, every query-valued member captured. **Read it when** you are declaring a state machine or a dependency graph of tasks |
 | [APP-PEN.md](APP-PEN.md) | 1,143 | `./app` — the `jaren-app` 0.1 document `createApp` runs, and the JSON Schema of its state beside it. **Read it when** you are declaring a whole application: state, view, actions, effects |
 | [FORMS-PEN.md](FORMS-PEN.md) | 940 | `./forms` — the `x-form` vocabulary on JSON Schema, and `assertOnSubmit()`, the same rules' layer-3 `$query` twin. **Read it when** you are turning a schema into a form |
-| [DB-CLIENT.md](DB-CLIENT.md) | 814 | `./db` — the client: the store's typed front door, not a pen, and the package's one runtime edge. **Read it when** you are reading or writing rows: `load`, `include`, `link`/`unlink`, `live` |
+| [DB-CLIENT.md](DB-CLIENT.md) | 893 | `./db` — the client: the store's typed front door, not a pen, and the package's one runtime edge. **Read it when** you are reading or writing rows: `load`, `include`, `link`/`unlink`, `live` |
 <!--/fact-->
 
 Every row of that table is derived, and none of it is written here: the
@@ -53,7 +53,7 @@ sentence is the document's own opening line, the length is the file's,
 and `npm run docs:derive` writes the table out of the eleven documents
 beside this one. The line counts are not decoration — they are what tells
 a reader whether the document they are about to open is a ten-minute read
-or an afternoon — and `test/docs/linq-citations.test.js` holds each one
+or an afternoon — and `test/docs/format-citations.test.js` holds each one
 equal to the file it names, independently of the derivation.
 
 A document missing from that table is a document a reader cannot reach:
@@ -182,7 +182,7 @@ mirrored in QUERY-PEN §9 (one table, held equal by a test):
 | `JL0102` | a pen was asked for a construct the format cannot carry: a function `refine`/`transform` (cross-field rules are `check()`; transforms are application code), a coercion the normalizer would never run, closed objects under `allOf`, an annotation on `never()`, a draft the pen does not write; in the JSLT pen an `apply()` as a bare object member (the `[]` idiom, JSLT-FORMAT §6.3 — the engine would fail at run time on the second child), a `match` of `{}` (the compiler's `JT0003`, earlier), an `apply()` outside a body; in the contract pen a path template form CONTRACT-FORMAT §4.2 reserves (the compiler's `JC0008`, earlier, naming the same form), a member mapped to `path` the template does not declare, or a hand-written operation `kind` outside `read`/`command`/`subscribe`; in the flow pen a guard given as a plain STRING (FLOW-FORMAT §3 makes a non-`$` literal vacuously true, so a projected display annotation must not decide execution), or a state or node id no declaration carries (the compiler's `JF0004`/`JF0006`/`JF0013`, earlier, naming the id); in the app pen a patch path that is not a chain of member reads and subscripts (a JSON Pointer cannot be written for it), an `$event` field APP-FORMAT §3.1 excludes by construction (`target`, `files`, a touch list — `$event` must survive `JSON.stringify`), an initial state no `default()` describes, a subscription-member combination §5.3 calls `JA0008`, or a view binding an action `actions` does not declare (the loop's `JA2001`, earlier, naming the declared ones); in the forms pen `preview`, which the format registry DERIVES from the field's own `format` |
 | `JL0103` | a `$defs` name collision (two distinct builders under one name), a `ref()` no definition answers, or a `lazy()` that does not return a named builder |
 | `JL0104` | a pen-owned keyword written through `meta()`, or an external a captured rule did not declare: a `check()` external other than `root`/`path`, a `compute()` external at all, a `body()` external other than `root`/`path` and its declared parameters — or `root`/`path` declared as one, since the engine binds them; a flow guard, effect `with`, node query or edge `select` external at all, since both flow engines evaluate with one `$` and nothing else; an app action naming anything but `$event` and `$payload` (APP-FORMAT §3.1's whole ambient vocabulary), a subscription member naming anything but `$item`, and that only under `for` (§5.3's closed world); a form rule naming anything but the context's `root`, `value` and `pointer` |
-| `JL0105` | a relation hop on the chain — the query pen (QUERY-PEN §4, relation navigation) — cannot lower: the member is a many-to-many relation, whose join table is not a queryable root in this version (`load({ include })` reads the memberships); the relation's key column or the key it references is composite or undeclared; or the provider's relation table holds something that is not a relation record |
+| `JL0105` | a relation hop on the chain — the query pen (QUERY-PEN §4, relation navigation) — cannot lower: the relation's key column or the key it references is composite or undeclared; a many-to-many entry does not name its join row's columns (`{ joinTable, ownColumn, ownKey, targetColumn, targetKey }`), so there is no join root to lower through; the relation kind is not one this surface lowers; or the provider's relation table holds something that is not a relation record |
 | `JL0106` | a migration step names an entity or collection the target model does not declare (`transform`, `assert`, `derive`); or a `transform` over a planned document finds no draft to replace, or two drafts for one name |
 | `JL0107` | the client (`@jarenjs/linq/db`, [DB-CLIENT.md](DB-CLIENT.md)) was handed a member that is not the relation kind the operation needs: `include()` picks a declared relation member — a scalar member, or a name the model does not declare, is refused naming the declared ones; `link()`/`unlink()` attach many-to-many memberships only — a to-one or to-many relation is refused naming its kind |
 
@@ -201,18 +201,18 @@ and the bundle is the byte count the tree-shaking probe builds.
 <!--fact:pens.census-->
 | Document | Subpath | Lines | Mapping rows | Worked examples | Refusals | Bundle |
 |---|---|---:|---:|---:|---:|---:|
-| [LINQ-FORMAT.md](LINQ-FORMAT.md) | — | 812 | — | — | — | — |
-| [QUERY-PEN.md](QUERY-PEN.md) | `.` | 1,636 | 34 | 8 | 14 | 173,080 B |
-| [SCHEMA-PEN.md](SCHEMA-PEN.md) | `./schema` | 1,218 | 66 | 10 | 4 | 32,427 B |
-| [MODEL-PEN.md](MODEL-PEN.md) | `./model` | 1,083 | 28 | 6 | 3 | 40,857 B |
-| [JSLT-PEN.md](JSLT-PEN.md) | `./jslt` | 955 | 17 | 8 | 3 | 19,124 B |
-| [MIGRATION-PEN.md](MIGRATION-PEN.md) | `./migration` | 781 | 11 | 5 | 4 | 23,599 B |
-| [CONTRACT-PEN.md](CONTRACT-PEN.md) | `./contract` | 1,217 | 37 | 6 | 3 | 44,644 B |
-| [FLOW-PEN.md](FLOW-PEN.md) | `./flow` | 1,026 | 16 | 7 | 3 | 19,181 B |
-| [APP-PEN.md](APP-PEN.md) | `./app` | 1,143 | 22 | 7 | 3 | 46,862 B |
-| [FORMS-PEN.md](FORMS-PEN.md) | `./forms` | 940 | 18 | 6 | 3 | 36,587 B |
-| [DB-CLIENT.md](DB-CLIENT.md) | `./db` | 814 | 36 | 4 | 2 | 478,172 B |
-| **eleven documents** | | **11,625** | **285** | **67** | | |
+| [LINQ-FORMAT.md](LINQ-FORMAT.md) | — | 820 | — | — | — | — |
+| [QUERY-PEN.md](QUERY-PEN.md) | `.` | 1,724 | 34 | 8 | 15 | 174,264 B |
+| [SCHEMA-PEN.md](SCHEMA-PEN.md) | `./schema` | 1,218 | 66 | 10 | 4 | 33,156 B |
+| [MODEL-PEN.md](MODEL-PEN.md) | `./model` | 1,092 | 28 | 6 | 3 | 41,582 B |
+| [JSLT-PEN.md](JSLT-PEN.md) | `./jslt` | 955 | 17 | 8 | 3 | 19,856 B |
+| [MIGRATION-PEN.md](MIGRATION-PEN.md) | `./migration` | 781 | 11 | 5 | 4 | 24,259 B |
+| [CONTRACT-PEN.md](CONTRACT-PEN.md) | `./contract` | 1,221 | 38 | 6 | 3 | 45,298 B |
+| [FLOW-PEN.md](FLOW-PEN.md) | `./flow` | 1,033 | 16 | 7 | 3 | 19,910 B |
+| [APP-PEN.md](APP-PEN.md) | `./app` | 1,143 | 22 | 7 | 3 | 47,444 B |
+| [FORMS-PEN.md](FORMS-PEN.md) | `./forms` | 940 | 18 | 6 | 3 | 37,312 B |
+| [DB-CLIENT.md](DB-CLIENT.md) | `./db` | 893 | 41 | 4 | 2 | 623,994 B |
+| **eleven documents** | | **11,820** | **291** | **67** | | |
 <!--/fact-->
 
 A pen whose mapping rows are far below its worked examples is a pen
@@ -254,16 +254,16 @@ it and each document publishes it. The rounded column is what
 <!--fact:pens.cost-->
 | Subpath | Document | Bundle | Rounded |
 |---|---|---:|---:|
-| `@jarenjs/linq` | [QUERY-PEN.md](QUERY-PEN.md) | 173,080 B | 173 kB |
-| `@jarenjs/linq/schema` | [SCHEMA-PEN.md](SCHEMA-PEN.md) | 32,427 B | 32 kB |
-| `@jarenjs/linq/model` | [MODEL-PEN.md](MODEL-PEN.md) | 40,857 B | 41 kB |
-| `@jarenjs/linq/jslt` | [JSLT-PEN.md](JSLT-PEN.md) | 19,124 B | 19 kB |
-| `@jarenjs/linq/migration` | [MIGRATION-PEN.md](MIGRATION-PEN.md) | 23,599 B | 24 kB |
-| `@jarenjs/linq/contract` | [CONTRACT-PEN.md](CONTRACT-PEN.md) | 44,644 B | 45 kB |
-| `@jarenjs/linq/flow` | [FLOW-PEN.md](FLOW-PEN.md) | 19,181 B | 19 kB |
-| `@jarenjs/linq/app` | [APP-PEN.md](APP-PEN.md) | 46,862 B | 47 kB |
-| `@jarenjs/linq/forms` | [FORMS-PEN.md](FORMS-PEN.md) | 36,587 B | 37 kB |
-| `@jarenjs/linq/db` | [DB-CLIENT.md](DB-CLIENT.md) | 478,172 B | 478 kB |
+| `@jarenjs/linq` | [QUERY-PEN.md](QUERY-PEN.md) | 174,264 B | 174 kB |
+| `@jarenjs/linq/schema` | [SCHEMA-PEN.md](SCHEMA-PEN.md) | 33,156 B | 33 kB |
+| `@jarenjs/linq/model` | [MODEL-PEN.md](MODEL-PEN.md) | 41,582 B | 42 kB |
+| `@jarenjs/linq/jslt` | [JSLT-PEN.md](JSLT-PEN.md) | 19,856 B | 20 kB |
+| `@jarenjs/linq/migration` | [MIGRATION-PEN.md](MIGRATION-PEN.md) | 24,259 B | 24 kB |
+| `@jarenjs/linq/contract` | [CONTRACT-PEN.md](CONTRACT-PEN.md) | 45,298 B | 45 kB |
+| `@jarenjs/linq/flow` | [FLOW-PEN.md](FLOW-PEN.md) | 19,910 B | 20 kB |
+| `@jarenjs/linq/app` | [APP-PEN.md](APP-PEN.md) | 47,444 B | 47 kB |
+| `@jarenjs/linq/forms` | [FORMS-PEN.md](FORMS-PEN.md) | 37,312 B | 37 kB |
+| `@jarenjs/linq/db` | [DB-CLIENT.md](DB-CLIENT.md) | 623,994 B | 624 kB |
 <!--/fact-->
 
 Read these as prices, not as scores. `./db` is the largest by an order of
@@ -504,6 +504,8 @@ it says.
 | `collection(schema, { key?, identity?, indexes?, renamedFrom? })` | `{ schema, key?, identity?, indexes?, 'x-rename'? }` — `key` is an RFC 6901 pointer, a captured member path (`(d) => d.id` → `/id`) or `null` (the store allocates, `identity` says how); the other options ride verbatim | `CollectionSpec<Infer<B>>`, carrying the document shape its paths are checked against | native; an option outside the four, a key that is neither pointer nor lambda nor `null`, an `indexes` that is not an array of `index()` entries, all `JL0101` |
 | `index(path, options?)` | `{ name, path, unique?, derive?, precision?, dims?, physical? }` — `path` is a captured lambda (`(p) => p.cell` → `$.cell`), a non-empty array of them (a composite), or a JSONPath string; `name` defaults to `by_<segments>`; the rest ride verbatim for the store's model walk to judge (§2.1) | `IndexPath<D>` over the collection's shape: a member the shape lacks does not compile | native; an option outside the six is `JL0101`; a lambda that answers an operator result or a surface method is `JL0102` |
 
+| `expressionIndex(expression, options?)` | `{ name, expression, unique? }` — an index over a COMPUTED value: a `{ call, args }` node whose arguments are member lambdas, JSONPath strings, JSON scalars or further calls; `name` defaults to `by_<call>_<members>` | the expression's member lambdas are checked against the collection's shape | native; a node outside the vocabulary, an option outside the two, and anything that looks like SQL text are all `JL0101` |
+
 **The model document**
 
 | Method | Emits | Type reading | Status |
@@ -627,7 +629,8 @@ it says.
 | 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 |
 
 **What the pen does not judge**
@@ -764,12 +767,14 @@ it says.
 | `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` |
 
-**The two exported names**
+**The exported names**
 
 | 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` |
 
 **The entity handle**
 
@@ -792,12 +797,14 @@ it says.
 | `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 |
 
 | Spec member | Emitted | Note |
 |---|---|---|
@@ -807,6 +814,7 @@ it says.
 | `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 |
 <!--/fact-->

package/docs/MIGRATION-PEN.md

@@ -745,7 +745,7 @@ from a drop plus a create, and guessing risks silent data loss.
 
 ## 7. Cost
 
-`@jarenjs/linq/migration` builds to **<!--fact:bundle.migration-->23,599<!--/fact--> bytes** as a minified,
+`@jarenjs/linq/migration` builds to **<!--fact:bundle.migration-->24,259<!--/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.migration.kb-->24<!--/fact--> kB) beside the other nine subpath prices in
@@ -778,4 +778,4 @@ proxy behind it, and the canonicalizer — and the two model documents
 themselves arrive as data, deep-frozen JSON that the consumer's own model
 module built. So a consumer who ships migrations to a browser does not
 ship the model pen with them; a consumer who OPENS a store does, and pays
-`./model`'s <!--fact:bundle.model-->40,857<!--/fact--> bytes for it.
+`./model`'s <!--fact:bundle.model-->41,582<!--/fact--> bytes for it.

package/docs/MODEL-PEN.md

@@ -197,11 +197,20 @@ no relations (MODEL-FORMAT §9.1); one physical engine sits under both.
 | `collection(schema, { key?, identity?, indexes?, renamedFrom? })` | `{ schema, key?, identity?, indexes?, 'x-rename'? }` — `key` is an RFC 6901 pointer, a captured member path (`(d) => d.id` → `/id`) or `null` (the store allocates, `identity` says how); the other options ride verbatim | `CollectionSpec<Infer<B>>`, carrying the document shape its paths are checked against | native; an option outside the four, a key that is neither pointer nor lambda nor `null`, an `indexes` that is not an array of `index()` entries, all `JL0101` |
 | `index(path, options?)` | `{ name, path, unique?, derive?, precision?, dims?, physical? }` — `path` is a captured lambda (`(p) => p.cell` → `$.cell`), a non-empty array of them (a composite), or a JSONPath string; `name` defaults to `by_<segments>`; the rest ride verbatim for the store's model walk to judge (§2.1) | `IndexPath<D>` over the collection's shape: a member the shape lacks does not compile | native; an option outside the six is `JL0101`; a lambda that answers an operator result or a surface method is `JL0102` |
 
-The option set is exactly `name`, `unique`, `derive`, `precision`,
-`dims`, `physical` (`src/model/collection.js:18`); the default name is
-`by_` plus the path's member segments, identifier-safe
+| `expressionIndex(expression, options?)` | `{ name, expression, unique? }` — an index over a COMPUTED value: a `{ call, args }` node whose arguments are member lambdas, JSONPath strings, JSON scalars or further calls; `name` defaults to `by_<call>_<members>` | the expression's member lambdas are checked against the collection's shape | native; a node outside the vocabulary, an option outside the two, and anything that looks like SQL text are all `JL0101` |
+
+The option set for `index()` is exactly `name`, `unique`, `derive`,
+`precision`, `dims`, `physical` (`src/model/collection.js:18`); the
+default name is `by_` plus the path's member segments, identifier-safe
 (`collection.js:76-80`) — `by_series_t`, `by_x_y`.
 
+`expressionIndex()` takes only `name` and `unique`, because an
+expression names the members it reads itself — nothing that describes a
+member's storage belongs beside one. The pen resolves NO function name:
+arity and determinism are the store's to check against the declarations
+`openStore({ expressions })` was given, and a name this pen has never
+heard of is not an error here. What it decides is the shape.
+
 ### 2.4 The model document
 
 The three calls that assemble the whole thing — the document, the
@@ -1053,10 +1062,10 @@ catch them:
 
 ## 7. Cost
 
-`@jarenjs/linq/model` builds to **<!--fact:bundle.model-->40,857<!--/fact--> bytes** as a minified,
+`@jarenjs/linq/model` builds to **<!--fact:bundle.model-->41,582<!--/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.model.kb-->41<!--/fact--> kB) beside the other nine subpath prices in
+(<!--fact:bundle.model.kb-->42<!--/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 two-member model as a
@@ -1074,7 +1083,7 @@ them:
   byte of `packages/linq/src/model/`, because the subclasses are built by
   this subpath rather than patched onto the base classes.
 
-The price above the schema pen's <!--fact:bundle.schema-->32,427<!--/fact--> is about 8 kB: the mixin, the
+The price above the schema pen's <!--fact:bundle.schema-->33,156<!--/fact--> is about 8 kB: the mixin, the
 three relation factories, `collection()`/`index()` with their capture,
 `defineModel()` — and the refusal MESSAGES, which are most of what §4
 costs. That is a deliberate trade: naming the rule and the spelling that

package/docs/QUERY-PEN.md

@@ -200,8 +200,9 @@ value becomes the expression:
   `groupJoin`, `aggregate` (and a `mapAsync`) a relation name is an
   ordinary member again — and a `fromDocument` chain never hops: there
   the document decides what the items are. A hop that cannot lower is
-  `JL0105` at build time (a many-to-many member: its join table is not a
-  queryable root in this version; a composite key); a member read off
+  `JL0105` at build time (a composite key; a many-to-many entry that
+  does not name its join row's columns, so there is no join root to
+  lower through — MODEL-FORMAT §10.7); a member read off
   the to-many ARRAY before `all()` is `JL0005` with the fix named, where
   the same read off a stored array would answer nothing.
 
@@ -563,6 +564,8 @@ Runtime errors (`LinqRuntimeError`):
 | `JL2004` | an asynchronous provider cannot back the synchronous surface |
 | `JL2005` | a push queue was fed after it ended |
 | `JL2006` | a provider answered an element terminal with something other than one array |
+| `JL2007` | a ledger settlement named a ref that settles no started record — `createDbLedger`'s fence ([DB-CLIENT.md §2.6](DB-CLIENT.md#26-the-ledger)) |
+| `JL2008` | a federated fetch reached its row or byte budget (§12.1) |
 
 Engine errors (`JQ…`) from a hand-written `fromDocument` document pass
 through unwrapped — they already carry their own code and `docPath` —
@@ -604,12 +607,19 @@ because the engine itself materialises for `$orderby`/`$groupby`):
 `take(n)`, and an exception mid-chain all call `.return()` on the
 iterator — a generator left suspended holds a file handle or a read
 transaction open. `explain()` reports `{ barriers: [{ operator,
-reason }], hops, document }` — `hops` the relation hops the callbacks
-navigated, as on the sync surface (§4) — or, when a `mapAsync` sits in
-the chain, `{ split: { pushed, residual } }` instead of `document`
-(`toDocument()` refuses with `JL0005`: a host callback has no document
-form). No silent caps, no silent buffering: if a chain materialises,
-the report says which operator forced it.
+reason }], streaming, barrier, hops, document }` — `hops` the relation
+hops the callbacks navigated, as on the sync surface (§4); `streaming`
+(`'row'` or `'buffered'`) and `barrier` what THIS surface does with the
+item stream, one item at a time or a buffer at its first local barrier
+— or, when a `mapAsync` sits in the chain, `{ split: { pushed,
+residual } }` instead of `document` (`toDocument()` refuses with
+`JL0005`: a host callback has no document form). Over a provider the
+pushed document's own class — a set residual, an external the store
+cannot bind — is the provider's `explain(document, { externals:
+bindings })` to report, and the cursor a `for await` pulls from
+carries the same `streaming`/`barrier` (§12). No silent caps, no silent
+buffering: if a chain materialises, the report says which operator
+forced it.
 
 Re-enumeration follows the sync contract: each enumeration calls the
 source's iterator method again. A one-shot generator object simply
@@ -645,8 +655,11 @@ operators; a per-element async *predicate* is `mapAsync` then `where`.
   completion.
 - An `AbortSignal` is threaded to every callback and aborted on early
   termination and on failure. A rejected callback FAILS CLOSED: the
-  first failure wins, every in-flight sibling aborts, the source
-  closes (the `compileDag` discipline).
+  first rejection aborts every in-flight sibling and closes the source,
+  including while its next pull is pending. Ordered mode still delivers
+  preceding values and reports callback failures in source order. The
+  producer is closed once; a failed close accompanies the callback's
+  original failure in an `AggregateError`.
 - `mapAsync` is NOT translatable to a provider. A provider-backed
   chain that reaches it SPLITS: everything before is pushed to the
   provider whole, everything after runs locally, and `explain()`
@@ -674,8 +687,12 @@ operators; a per-element async *predicate* is `mapAsync` then `where`.
   `iterateCsvStream` output);
 - any sync iterable (wrapped);
 - a **cursor**: `{ next(): Promise<{done, value}>, return?() }` — the
-  shape the SQL provider's row iterator implements later, adopted
-  as-is;
+  shape the store's own row cursor implements (`QueryCursor`), adopted
+  as-is. A provider that offers `cursor(document, options)` — the
+  store's collections and entity sets do — is handed the pushed
+  document there when the chain is ITERATED, so a `for await` pulls
+  one row at a time from an open statement and a `break` releases it;
+  `toArray()` and the other terminals still push one whole window;
 - a **push queue** (`createPushQueue({ highWaterMark = 1024 })`) for
   feed/end-style readers with no pull protocol of their own (josl's
   push parsers deliberately have no backpressure protocol; the queue
@@ -689,6 +706,72 @@ engine async (`packages/json` is untouched and strictly synchronous),
 it does not add a second operator table, and it does not add
 `selectAwait`/`whereAwait` variants.
 
+### 12.1 The federation boundary (`federate`)
+
+A query document reads ONE input, and a join whose sides come from two
+unrelated sources is `JL0005` (§8). That refusal stands: nothing in a
+chain relaxes it. What `federate()` adds is the one place to opt OUT of
+it explicitly, by naming the sources and the bounds together:
+
+```js
+const fed = federate({
+  sources: { orders: shop.entity('Order'), events: analytics },
+  maxRows: 50_000,
+  maxBytes: 32 * 1024 * 1024,
+});
+
+const rows = await fromAsync(fed.source('orders'))
+  .where((o) => o.placedAt.gt(cutoff))
+  .join(fromAsync(fed.source('events')), (o) => o.id, (e) => e.orderId,
+    (o, e) => ({ id: o.id, at: e.at }))
+  .toArray();
+```
+
+`fed.source(name)` is an ordinary provider source (§8) with the root
+`$.<name>[*]`, and all of a federation's sources share one scope — which
+is exactly what admits the join. The federation is what executes it:
+
+1. each side's own document — the filters and the projection the chain
+   already packed per side — runs against ITS source, over that
+   source's own root;
+2. the smaller side (by declared `estimatedRows`, else the first named)
+   is streamed into a hash table keyed by the join key, counting rows
+   and serialized bytes against the budget as it fills;
+3. the other side is streamed and PROBED: a row whose key no build row
+   carries cannot pair, so it is dropped before it costs anything;
+4. the caller's own document runs in the engine over the two reduced
+   sets — the **resident join**, which is what decides.
+
+Step 4 is the contract. This boundary spells no join semantics of its
+own: the engine's `$eq` decides which rows pair, its ordering orders
+them, its projection shapes them. The hash table bounds the FETCH and
+nothing else, so a reduction that cannot key a value (a compound join
+key) keeps the row rather than guessing at it.
+
+`fed.source(name).explain(document)` answers the plan without running
+any of it: the `strategy`, the `budget`, the `build` and `probe` sides
+with their estimates, their own documents and whether each streams, and
+the `resident` document the engine answers.
+
+**A budget is a refusal, not a spill.** A side that reaches `maxRows` or
+`maxBytes` stops at the row that WOULD have broken it and raises
+`JL2008`; every cursor the call opened is closed exactly once, whether
+it answered, refused, failed or was aborted. A `signal` on the call is
+read at the ROW boundary — where a cursor can be let go without
+abandoning a pull the source is still inside — and a declared
+`estimatedRows` decides only which side BUILDS, never how much is held:
+a source that under-reports is refused by the budget all the same. A source offering a
+cursor (§12) is pulled row by row, so the bound is enforced before the
+memory is spent; one offering only `execute` answers whole, and
+`explain()` says `buffered` rather than pretending otherwise.
+
+Refused, by name: more than two sides in one federated document, a
+binding over a root the federation does not carry, and a join with no
+equality between one member of each side — without one the fetch is the
+cross product of two sources, which is what the budget exists to
+refuse. Non-goals: no spill, no distributed transaction, no
+cross-source write.
+
 ## 13. Worked examples
 
 Every `js` fence below is EXECUTED. `test/linq/pen-docs.test.js` writes
@@ -1111,6 +1194,11 @@ proves that too, so the exclusion cannot hide a chain refusal).
 | `JL2004` | a provider's `execute()` answered a promise on the synchronous surface |
 | `JL2005` | a push queue was fed after `end()` |
 | `JL2006` | a provider answered an element terminal with something other than one array |
+| `JL2008` | a federated fetch reached one side's row or byte budget (§12.1) |
+
+`JL2007` is the client door's, not the chain's: `createDbLedger`'s stale
+settlement ([DB-CLIENT.md §2.6](DB-CLIENT.md#26-the-ledger)); it is
+listed with the runtime errors above and raised by no chain module.
 
 Every message below is the one the chain raised when the spelling beside
 it was run, with the code prefix (`JL0005: `) removed. Where a refusal
@@ -1583,14 +1671,14 @@ are shorter:
 ## 17. Cost
 
 A consumer importing `from` from `@jarenjs/linq` and calling one
-terminal bundles **<!--fact:bundle.chain-->173,080<!--/fact--> bytes** (esbuild, ESM, minified, tree-shaken,
+terminal bundles **<!--fact:bundle.chain-->174,264<!--/fact--> bytes** (esbuild, ESM, minified, tree-shaken,
 `platform: 'neutral'`). The figure is measured by
 `scripts/check-tree-shaking.js`'s chain probe and compared with this
 section on every `npm run test:tree-shaking`: it is derived, never typed,
 and a stale one is red here rather than wrong in a document somebody
 reads.
 
-Of that, **<!--fact:bundle.chain.own-->39,025<!--/fact--> bytes** are the chain's own modules — `sequence.js`,
+Of that, **<!--fact:bundle.chain.own-->40,280<!--/fact--> bytes** are the chain's own modules — `sequence.js`,
 `async.js`, `expression.js`, `document.js`, `provider.js`,
 `concurrency.js`, `errors.js` and `schema-of.js`. The remaining ~134 kB
 is the query ENGINE and the core it stands on: a chain's document has to
@@ -1611,13 +1699,13 @@ making:
   `@jarenjs/formats`** — the client's optional peers. A consumer of the
   chain alone installs nothing new;
 - **no pen bytes at all**, in either direction: the pens carry no chain
-  module either, which is what keeps a <!--fact:bundle.jslt.kb-->19<!--/fact--> kB JSLT
-  pen <!--fact:bundle.jslt.kb-->19<!--/fact--> kB.
+  module either, which is what keeps a <!--fact:bundle.jslt.kb-->20<!--/fact--> kB JSLT
+  pen <!--fact:bundle.jslt.kb-->20<!--/fact--> kB.
 
 `docs/CONSUMING.md` states the rounded price of all ten subpaths in one
 table, each figure held equal to the same measurements. Two of its rows
-are the ones to read together: the chain at <!--fact:bundle.chain.kb-->173<!--/fact--> kB and
-`./db` at <!--fact:bundle.db.kb-->478<!--/fact--> kB.
+are the ones to read together: the chain at <!--fact:bundle.chain.kb-->174<!--/fact--> kB and
+`./db` at <!--fact:bundle.db.kb-->624<!--/fact--> kB.
 The client costs what the store costs, by construction, and the chain
 costs what running a query costs.
 
@@ -1626,7 +1714,7 @@ the reason is worth knowing: a bundler counts a shared module once, and
 the chain and every pen share the expression capture (`expression.js`)
 and the coded errors under it (`errors.js`, and `@jarenjs/core`'s error
 and object helpers). A consumer importing the chain AND the schema pen
-bundles **<!--fact:bundle.chain.withSchemaPen-->194,155<!--/fact--> bytes** — **<!--fact:bundle.chain.shared-->11,352<!--/fact--> bytes** less than the sum of the
+bundles **<!--fact:bundle.chain.withSchemaPen-->195,342<!--/fact--> bytes** — **<!--fact:bundle.chain.shared-->12,078<!--/fact--> bytes** less than the sum of the
 figure above and [SCHEMA-PEN.md](SCHEMA-PEN.md#7-cost) §7's, which is
 what those shared modules weigh. The probe measures that pair too, so
 the saving is derived like everything else here. What the chain does NOT

package/docs/SCHEMA-PEN.md

@@ -1180,10 +1180,10 @@ hand, or generate it some other way, when:
 
 ## 7. Cost
 
-`@jarenjs/linq/schema` builds to **<!--fact:bundle.schema-->32,427<!--/fact--> bytes** as a minified,
+`@jarenjs/linq/schema` builds to **<!--fact:bundle.schema-->33,156<!--/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.schema.kb-->32<!--/fact--> kB) beside the other nine subpath prices in
+(<!--fact:bundle.schema.kb-->33<!--/fact--> kB) beside the other nine subpath prices in
 [docs/CONSUMING.md](../../../docs/CONSUMING.md).
 
 The probe is a gate, not a report: building

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/linq",
   "private": false,
-  "version": "0.56.0",
+  "version": "0.67.0",
   "type": "module",
   "main": "./src/index.js",
   "types": "./types/index.d.ts",
@@ -84,13 +84,13 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.56.0",
-    "@jarenjs/json": "^0.56.0"
+    "@jarenjs/core": "^0.67.0",
+    "@jarenjs/json": "^0.67.0"
   },
   "peerDependencies": {
-    "@jarenjs/db": "^0.56.0",
-    "@jarenjs/formats": "^0.56.0",
-    "@jarenjs/validate": "^0.56.0"
+    "@jarenjs/db": "^0.67.0",
+    "@jarenjs/formats": "^0.67.0",
+    "@jarenjs/validate": "^0.67.0"
   },
   "peerDependenciesMeta": {
     "@jarenjs/db": {

package/src/app/action.js

@@ -19,6 +19,7 @@
  * payload-creator function.
  */
 
+import { isJsonObject } from '@jarenjs/core/object';
 import { LinqBuildError } from '../errors.js';
 import { effectDescriptor, readEffects } from '../effect.js';
 import { describeValue } from '../json-boundary.js';
@@ -52,11 +53,6 @@ const EXCLUDED_FIELDS = new Set([
   'path', 'composedPath', 'clipboardData', 'submitter',
 ]);
 
-/** @param {any} value */
-function isPlainObject(value) {
-  return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-
 /**
  * A member set the pen knows, or `JL0101` naming the one it does not.
  * @param {any} spec
@@ -120,7 +116,7 @@ export function effect(run, props = undefined) {
  * transition({ state: () => null, effects: [effect('save')] });
  */
 export function transition(spec) {
-  if (!isPlainObject(spec)) {
+  if (!isJsonObject(spec)) {
     throw new LinqBuildError('JL0101',
       `transition() takes { state?, patch?, effects? }, got ${describeValue(spec)}`);
   }
@@ -157,7 +153,7 @@ export function action(fn, options = undefined) {
       `action() takes a callback (s, x) => transition(…), got ${describeValue(fn)}`);
   }
   if (options !== undefined) {
-    if (!isPlainObject(options)) {
+    if (!isJsonObject(options)) {
       throw new LinqBuildError('JL0101',
         `action() options are { payload?, event? }, got ${describeValue(options)}`);
     }
@@ -232,7 +228,7 @@ export function bind(name, options = undefined) {
   }
   const out = { action: name };
   if (options !== undefined) {
-    if (!isPlainObject(options)) {
+    if (!isJsonObject(options)) {
       throw new LinqBuildError('JL0101',
         'bind() options are { payload?, event?, preventDefault?, stopPropagation? }, got '
         + describeValue(options));

package/src/app/define.js

@@ -24,7 +24,7 @@
  * click; the pen can see the whole document at once and refuses it.
  */
 
-import { deepFreeze, setObjectMember } from '@jarenjs/core/object';
+import { deepFreeze, setObjectMember, isJsonObject } from '@jarenjs/core/object';
 
 import { LinqBuildError } from '../errors.js';
 import { describeValue, requireJson, requireNameMap } from '../json-boundary.js';
@@ -37,11 +37,6 @@ const APP_VERSION = '0.1';
 /** The members `defineApp()` takes. */
 const APP_MEMBERS = Object.freeze(['state', 'initial', 'schema', 'view', 'actions', 'subs']);
 
-/** @param {any} value */
-function isPlainObject(value) {
-  return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-
 /** A JSON value, copied: the document is a value of its own. @param {any} v */
 const copy = (v) => JSON.parse(JSON.stringify(v));
 
@@ -65,7 +60,7 @@ function initialOf(schema, at, needed) {
   }
   if (schema.default !== undefined) return { has: true, value: copy(schema.default) };
   if (schema.const !== undefined) return { has: true, value: copy(schema.const) };
-  if (!isPlainObject(schema.properties)) return { has: false };
+  if (!isJsonObject(schema.properties)) return { has: false };
 
   const required = Array.isArray(schema.required) ? schema.required : [];
   const out = {};
@@ -114,7 +109,7 @@ function collectBoundActions(node, out) {
       const name = literalName(value);
       if (name !== null) out.add(name);
     }
-    if (key === 'on' && isPlainObject(value)) {
+    if (key === 'on' && isJsonObject(value)) {
       for (const binding of Object.values(value)) {
         const name = literalName(binding);
         if (name !== null) out.add(name);
@@ -137,7 +132,7 @@ function readView(view) {
       + 'bare rule array; the format requires the member and the runtime refuses an app '
       + 'without one (JA0002)', '/view');
   }
-  if (!Array.isArray(view) && !isPlainObject(view)) {
+  if (!Array.isArray(view) && !isJsonObject(view)) {
     throw new LinqBuildError('JL0101',
       `defineApp() view is a JSLT stylesheet document or a bare rule array, got ${describeValue(view)}`,
       '/view');
@@ -165,7 +160,7 @@ function readView(view) {
  * createApp(document, { node, validateState: new JarenValidator().compile(stateSchema) });
  */
 export function defineApp(spec) {
-  if (!isPlainObject(spec)) {
+  if (!isJsonObject(spec)) {
     throw new LinqBuildError('JL0101',
       `defineApp() takes { state, initial?, schema?, view, actions?, subs? }, got ${describeValue(spec)}`);
   }
@@ -199,7 +194,7 @@ export function defineApp(spec) {
   /** @type {Record<string, any> | undefined} */
   let actions;
   if (spec.actions !== undefined) {
-    if (!isPlainObject(spec.actions)) {
+    if (!isJsonObject(spec.actions)) {
       throw new LinqBuildError('JL0101',
         `defineApp() actions is an object of named action() declarations, got ${describeValue(spec.actions)}`,
         '/actions');
@@ -207,7 +202,7 @@ export function defineApp(spec) {
     requireNameMap(spec.actions, 'defineApp() actions', '/actions');
     actions = {};
     for (const [name, declared] of Object.entries(spec.actions)) {
-      if (!isPlainObject(declared) || declared[ACTION] !== true) {
+      if (!isJsonObject(declared) || declared[ACTION] !== true) {
         throw new LinqBuildError('JL0101',
           `defineApp() action '${name}' is action((s, x) => transition(…)), got ${describeValue(declared)}`,
           `/actions/${name}`);
@@ -225,7 +220,7 @@ export function defineApp(spec) {
         '/subs');
     }
     subs = spec.subs.map((declared, i) => {
-      if (!isPlainObject(declared) || declared[SUB] !== true) {
+      if (!isJsonObject(declared) || declared[SUB] !== true) {
         throw new LinqBuildError('JL0101',
           `defineApp() subs[${i}] is sub(run, options?), got ${describeValue(declared)}`,
           `/subs/${i}`);