@jarenjs/linq 0.73.0 → 0.83.2

package/docs/LINQ-FORMAT.md

@@ -16,9 +16,9 @@ A **pen** is a by-code front-end to one of the suite's document formats:
 named functions that build a standard document — a JSON Schema, a
 `$model`, a `$jslt` stylesheet — the way the chain builds a query
 document. `@jarenjs/linq` exports each pen under its own subpath
-(<!--fact:coverage.subpaths-->`./ai`, `./app`, `./charts`, `./contract`, `./db`, `./flow`, `./forms`, `./jslt`, `./jtlt`, `./messages`, `./migration`, `./model`, `./project`, `./schema`<!--/fact-->); `.` stays the chain.
+(<!--fact:coverage.subpaths-->`./ai`, `./app`, `./charts`, `./contract`, `./db`, `./flow`, `./forms`, `./formula`, `./jslt`, `./jtlt`, `./messages`, `./migration`, `./model`, `./project`, `./schema`<!--/fact-->); `.` stays the chain.
 
-Coverage: <!--fact:coverage.pens-->14 public pen/client subpaths beside the chain; 69/69 owned schema keywords have dedicated emission routes.<!--/fact-->
+Coverage: <!--fact:coverage.pens-->15 public pen/client subpaths beside the chain; 69/69 owned schema keywords have dedicated emission routes.<!--/fact-->
 
 **This document is the family's normative reference**: §1 states the
 rules every pen keeps, §1.3 the error codes they share, and §4–§7 the
@@ -36,10 +36,10 @@ is the index of those guides, 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) | 948 | 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 guides it indexes. **Read it when** you want a rule that is true of every pen, an index of the documents, or one place to look up a method without knowing which pen owns it |
-| [QUERY-PEN.md](QUERY-PEN.md) | 1,725 | 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) | 965 | 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 guides it indexes. **Read it when** you want a rule that is true of every pen, an index of the documents, or one place to look up a method without knowing which pen owns it |
+| [QUERY-PEN.md](QUERY-PEN.md) | 1,752 | 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,205 | `./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,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 |
+| [MODEL-PEN.md](MODEL-PEN.md) | 1,116 | `./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,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 |
@@ -49,9 +49,10 @@ is the index of those guides, and it is how a reader reaches any of them.
 | [AI-PEN.md](AI-PEN.md) | 98 | `./ai` — the public action program over environment slots. **Read it when** you want typed fixtures or host-authored programs without a model client. |
 | [MESSAGES-PEN.md](MESSAGES-PEN.md) | 105 | `./messages` — JSON message catalogs and message references. **Read it when** you want checked translation keys, placeholders and explicit completeness. |
 | [JTLT-PEN.md](JTLT-PEN.md) | 83 | `./jtlt` — text templates with JSLT dispatch and query expressions. **Read it when** you want to author Markdown, XML or source text as portable JSON. |
-| [PROJECT-PEN.md](PROJECT-PEN.md) | 75 | `./project` — Studio projects with named, typed files. **Read it when** you want a portable editor workspace containing documents written by several pens. |
+| [PROJECT-PEN.md](PROJECT-PEN.md) | 81 | `./project` — Studio projects with named, typed files. **Read it when** you want a portable editor workspace containing documents written by several pens. |
 | [CHARTS-PEN.md](CHARTS-PEN.md) | 94 | `./charts` — chart-definition documents for every chart kind. **Read it when** you want typed chart data and presentation options that `compileChart` consumes. |
-| [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` |
+| [DB-CLIENT.md](DB-CLIENT.md) | 1,085 | `./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` |
+| [FORMULA-PEN.md](FORMULA-PEN.md) | 41 | `./formula` — author versioned saved JSON Query profiles without executing them. |
 <!--/fact-->
 
 Every row of that table is derived, and none of it is written here: the
@@ -204,23 +205,24 @@ 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) | — | 948 | — | — | — | — |
-| [QUERY-PEN.md](QUERY-PEN.md) | `.` | 1,725 | 34 | 8 | 15 | 174,131 B |
-| [SCHEMA-PEN.md](SCHEMA-PEN.md) | `./schema` | 1,205 | 82 | 10 | 4 | 36,717 B |
-| [MODEL-PEN.md](MODEL-PEN.md) | `./model` | 1,092 | 28 | 6 | 3 | 45,143 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 | 48,859 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 | 51,006 B |
-| [FORMS-PEN.md](FORMS-PEN.md) | `./forms` | 940 | 18 | 6 | 3 | 40,873 B |
-| [AI-PEN.md](AI-PEN.md) | `./ai` | 98 | 12 | 1 | 3 | 16,904 B |
-| [MESSAGES-PEN.md](MESSAGES-PEN.md) | `./messages` | 105 | 9 | 2 | 1 | 18,337 B |
-| [JTLT-PEN.md](JTLT-PEN.md) | `./jtlt` | 83 | 13 | 1 | 2 | 16,725 B |
-| [PROJECT-PEN.md](PROJECT-PEN.md) | `./project` | 75 | 9 | 1 | 1 | 15,132 B |
-| [CHARTS-PEN.md](CHARTS-PEN.md) | `./charts` | 94 | 21 | 1 | 1 | 17,014 B |
-| [DB-CLIENT.md](DB-CLIENT.md) | `./db` | 893 | 41 | 4 | 2 | 627,769 B |
-| **16 documents** | | **12,391** | **371** | **73** | | |
+| [LINQ-FORMAT.md](LINQ-FORMAT.md) | — | 965 | — | — | — | — |
+| [QUERY-PEN.md](QUERY-PEN.md) | `.` | 1,752 | 34 | 8 | 15 | 175,221 B |
+| [SCHEMA-PEN.md](SCHEMA-PEN.md) | `./schema` | 1,205 | 82 | 10 | 4 | 35,285 B |
+| [MODEL-PEN.md](MODEL-PEN.md) | `./model` | 1,116 | 30 | 6 | 3 | 44,143 B |
+| [JSLT-PEN.md](JSLT-PEN.md) | `./jslt` | 955 | 17 | 8 | 3 | 18,424 B |
+| [MIGRATION-PEN.md](MIGRATION-PEN.md) | `./migration` | 781 | 11 | 5 | 4 | 22,827 B |
+| [CONTRACT-PEN.md](CONTRACT-PEN.md) | `./contract` | 1,221 | 38 | 6 | 3 | 47,427 B |
+| [FLOW-PEN.md](FLOW-PEN.md) | `./flow` | 1,033 | 16 | 7 | 3 | 18,478 B |
+| [APP-PEN.md](APP-PEN.md) | `./app` | 1,143 | 22 | 7 | 3 | 49,574 B |
+| [FORMS-PEN.md](FORMS-PEN.md) | `./forms` | 940 | 18 | 6 | 3 | 39,441 B |
+| [AI-PEN.md](AI-PEN.md) | `./ai` | 98 | 12 | 1 | 3 | 15,472 B |
+| [MESSAGES-PEN.md](MESSAGES-PEN.md) | `./messages` | 105 | 9 | 2 | 1 | 16,931 B |
+| [JTLT-PEN.md](JTLT-PEN.md) | `./jtlt` | 83 | 13 | 1 | 2 | 15,293 B |
+| [PROJECT-PEN.md](PROJECT-PEN.md) | `./project` | 81 | 9 | 1 | 1 | 13,793 B |
+| [CHARTS-PEN.md](CHARTS-PEN.md) | `./charts` | 94 | 21 | 1 | 1 | 15,582 B |
+| [DB-CLIENT.md](DB-CLIENT.md) | `./db` | 1,085 | 46 | 4 | 2 | 675,752 B |
+| [FORMULA-PEN.md](FORMULA-PEN.md) | `./formula` | 41 | 2 | — | — | 14,850 B |
+| **17 documents** | | **12,698** | **380** | **73** | | |
 <!--/fact-->
 
 A pen whose mapping rows are far below its worked examples is a pen
@@ -262,21 +264,22 @@ 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) | 174,131 B | 174 kB |
-| `@jarenjs/linq/schema` | [SCHEMA-PEN.md](SCHEMA-PEN.md) | 36,717 B | 37 kB |
-| `@jarenjs/linq/model` | [MODEL-PEN.md](MODEL-PEN.md) | 45,143 B | 45 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) | 48,859 B | 49 kB |
-| `@jarenjs/linq/flow` | [FLOW-PEN.md](FLOW-PEN.md) | 19,910 B | 20 kB |
-| `@jarenjs/linq/app` | [APP-PEN.md](APP-PEN.md) | 51,006 B | 51 kB |
-| `@jarenjs/linq/forms` | [FORMS-PEN.md](FORMS-PEN.md) | 40,873 B | 41 kB |
-| `@jarenjs/linq/ai` | [AI-PEN.md](AI-PEN.md) | 16,904 B | 17 kB |
-| `@jarenjs/linq/messages` | [MESSAGES-PEN.md](MESSAGES-PEN.md) | 18,337 B | 18 kB |
-| `@jarenjs/linq/jtlt` | [JTLT-PEN.md](JTLT-PEN.md) | 16,725 B | 17 kB |
-| `@jarenjs/linq/project` | [PROJECT-PEN.md](PROJECT-PEN.md) | 15,132 B | 15 kB |
-| `@jarenjs/linq/charts` | [CHARTS-PEN.md](CHARTS-PEN.md) | 17,014 B | 17 kB |
-| `@jarenjs/linq/db` | [DB-CLIENT.md](DB-CLIENT.md) | 627,769 B | 628 kB |
+| `@jarenjs/linq` | [QUERY-PEN.md](QUERY-PEN.md) | 175,221 B | 175 kB |
+| `@jarenjs/linq/schema` | [SCHEMA-PEN.md](SCHEMA-PEN.md) | 35,285 B | 35 kB |
+| `@jarenjs/linq/model` | [MODEL-PEN.md](MODEL-PEN.md) | 44,143 B | 44 kB |
+| `@jarenjs/linq/jslt` | [JSLT-PEN.md](JSLT-PEN.md) | 18,424 B | 18 kB |
+| `@jarenjs/linq/migration` | [MIGRATION-PEN.md](MIGRATION-PEN.md) | 22,827 B | 23 kB |
+| `@jarenjs/linq/contract` | [CONTRACT-PEN.md](CONTRACT-PEN.md) | 47,427 B | 47 kB |
+| `@jarenjs/linq/flow` | [FLOW-PEN.md](FLOW-PEN.md) | 18,478 B | 18 kB |
+| `@jarenjs/linq/app` | [APP-PEN.md](APP-PEN.md) | 49,574 B | 50 kB |
+| `@jarenjs/linq/forms` | [FORMS-PEN.md](FORMS-PEN.md) | 39,441 B | 39 kB |
+| `@jarenjs/linq/ai` | [AI-PEN.md](AI-PEN.md) | 15,472 B | 15 kB |
+| `@jarenjs/linq/messages` | [MESSAGES-PEN.md](MESSAGES-PEN.md) | 16,931 B | 17 kB |
+| `@jarenjs/linq/jtlt` | [JTLT-PEN.md](JTLT-PEN.md) | 15,293 B | 15 kB |
+| `@jarenjs/linq/project` | [PROJECT-PEN.md](PROJECT-PEN.md) | 13,793 B | 14 kB |
+| `@jarenjs/linq/charts` | [CHARTS-PEN.md](CHARTS-PEN.md) | 15,582 B | 16 kB |
+| `@jarenjs/linq/db` | [DB-CLIENT.md](DB-CLIENT.md) | 675,752 B | 676 kB |
+| `@jarenjs/linq/formula` | [FORMULA-PEN.md](FORMULA-PEN.md) | 14,850 B | 15 kB |
 <!--/fact-->
 
 Read these as prices, not as scores. `./db` is the largest by an order of
@@ -524,6 +527,8 @@ it says.
 | `.updated()` | `default: 'updated'` — a stamp on insert AND on every update | marks it `generated` | native |
 | `.fill(value)` | `default: { value }` — a literal, filled when absent; the value crosses the JSON boundary (`requireJson`) | marks it `generated` | native; a value that is not JSON is `JL0101` |
 | `.compute(fn)`, `.compute(query)` | `default: { query }` — captured over the document being written (`$`), or a query document verbatim | marks it `generated` | native; a captured rule that binds ANY external is `JL0104` |
+| `.physical(layout)` | `physical` on the entity declaration | preserves entity types; explicit column codecs | native on an object builder |
+| `.invariants(rules)` | `invariants` on the entity declaration | explicit writer qualification | native on an object builder |
 | `.renamedFrom(name)` | `x-rename: name` on the ENTITY (or collection) declaration — a planning hint the migration planner reads, never part of the shape (MIGRATION-FORMAT §3) | — | native on the declaration's own builder; on a member, `JL0102` (the document has no place for one) |
 | `.meta(annotations)` | as the schema pen ([SCHEMA-PEN.md](SCHEMA-PEN.md#28-annotations-and-messages)), minus one key | — | refused (`JL0104`) for `x-entity`: the pen owns that keyword |
 | `.entity(patch)` | the patch, merged into `x-entity` — the primitive every row above is written in terms of, and the way to spell a member of the vocabulary that has no method of its own | — (it sets no flag; the named methods do — §5.2) | native; a member outside the closed vocabulary, `JL0102` |
@@ -844,8 +849,8 @@ it says.
 
 | Method | Emits | Type | Status |
 |---|---|---|---|
-| `file(name, kind, text)` | `{ name, kind, text }`, preserving text | literal name/kind | native |
-| `jsonFile(name, kind, document)` | same file, with serialized JSON text | literal name/kind | native |
+| `file(name, kind, text, options?)` | `{ name, kind, text }` and optional routing/import members, preserving text | literal name/kind | native |
+| `jsonFile(name, kind, document, options?)` | same file, with serialized JSON text | literal name/kind | native |
 | `defineProject(files?, options?)` | version, files, optional active/layout | names from files | native |
 | `.files(files)` | replacement file list | replaces known names | native |
 | `.file(file)` | appended file | adds its name | native |
@@ -903,17 +908,22 @@ it says.
 | `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` |
+| `createDbReceipts(client, options)` | permanent receipts and independent fenced leases; see durable mapped records | structural receipt repository |
+| `createDbEffectStore(client, options)` | reviewed external intent and reconciliation under job fences | structural effect store |
+| `createDbRunStore(client, options)` | mapped workflow checkpoints and bounded revision event pages | structural run store |
+| `createDbIngestionStore(client, options)` | atomic page/checkpoint staging and complete snapshot publication; see [complete ingestion store](DB-CLIENT.md#complete-ingestion-store) | structural ingestion store |
+| `createDbRangeProvider(store, entity, spec, options)` | a bounded structural range source over keyset pages and committed capture; also `handle.range(spec, options)` — [COLLECTION-PROVIDER.md](../../app/docs/COLLECTION-PROVIDER.md) | `Promise<DbRangeProvider>` |
 
 **The entity handle**
 
 | Group | Members |
 |---|---|
-| the unit of work | `create` `get` `update` `delete` `add` `put` `remove` `discard` `asNoTracking` |
+| the unit of work | `create` `get` `update` `delete` `add` `put` `remove` `discard` `asNoTracking`; `mutate` executes an untracked [native column mutation](../../db/docs/NATIVE-PLANS.md) |
 | the store's reads | `load` `explainLoad` `execute` |
 | the provider seam | `root` `scope` `relations` |
 | membership | `link` `unlink` — the store's, behind §4.2's check |
 | the chain | every `AsyncSequence` operator and terminal: `where` `select` `selectMany` `orderBy` `orderByDescending` `thenBy` `thenByDescending` `groupBy` `aggregate` `join` `groupJoin` `skip` `take` `distinct` `reverse` `concat` `defaultIfEmpty` `ofType` `cast` `zip` `mapAsync` `params` `toDocument` `toArray` `first` `firstOrDefault` `single` `singleOrDefault` `last` `lastOrDefault` `elementAt` `elementAtOrDefault` `count` `sum` `average` `min` `max` `any` `all`, and `Symbol.asyncIterator` |
-| the client's own | `include` (§2.4) and `live` |
+| the client's own | `include` (§2.4), `live`, and `range(spec, options)` |
 | in both | `explain` |
 
 **The graph**
@@ -945,4 +955,11 @@ it says.
 | `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 |
+
+### Formula document authoring — [FORMULA-PEN.md §2](FORMULA-PEN.md)
+
+| Call / option | Emitted member |
+|---|---|
+| `defineFormula(id, expression)` | `$formula`, `id`, `expression`, default `revision` |
+| `revision`, `bindings`, schema/helper references, result mode | Same named profile members |
 <!--/fact-->

package/docs/MESSAGES-PEN.md

@@ -100,6 +100,6 @@ gate compares generated files and all locale parameter sets with their sources.
 
 ## 7. Cost
 
-The isolated messages pen costs **<!--fact:bundle.messages-->18,337<!--/fact--> bytes**.
+The isolated messages pen costs **<!--fact:bundle.messages-->16,931<!--/fact--> bytes**.
 It carries the shared template compiler and generated vocabulary, with no locale,
 validator, forms or contract engine and no query chain.

package/docs/MIGRATION-PEN.md

@@ -745,10 +745,10 @@ from a drop plus a create, and guessing risks silent data loss.
 
 ## 7. Cost
 
-`@jarenjs/linq/migration` builds to **<!--fact:bundle.migration-->24,259<!--/fact--> bytes** as a minified,
+`@jarenjs/linq/migration` builds to **<!--fact:bundle.migration-->22,827<!--/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
+(<!--fact:bundle.migration.kb-->23<!--/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-step migration as a
@@ -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-->45,143<!--/fact--> bytes for it.
+`./model`'s <!--fact:bundle.model-->44,143<!--/fact--> bytes for it.

package/docs/MODEL-PEN.md

@@ -135,6 +135,8 @@ leaves `key` where it was and replaces `default`.
 | `.updated()` | `default: 'updated'` — a stamp on insert AND on every update | marks it `generated` | native |
 | `.fill(value)` | `default: { value }` — a literal, filled when absent; the value crosses the JSON boundary (`requireJson`) | marks it `generated` | native; a value that is not JSON is `JL0101` |
 | `.compute(fn)`, `.compute(query)` | `default: { query }` — captured over the document being written (`$`), or a query document verbatim | marks it `generated` | native; a captured rule that binds ANY external is `JL0104` |
+| `.physical(layout)` | `physical` on the entity declaration | preserves entity types; explicit column codecs | native on an object builder |
+| `.invariants(rules)` | `invariants` on the entity declaration | explicit writer qualification | native on an object builder |
 | `.renamedFrom(name)` | `x-rename: name` on the ENTITY (or collection) declaration — a planning hint the migration planner reads, never part of the shape (MIGRATION-FORMAT §3) | — | native on the declaration's own builder; on a member, `JL0102` (the document has no place for one) |
 | `.meta(annotations)` | as the schema pen ([SCHEMA-PEN.md](SCHEMA-PEN.md#28-annotations-and-messages)), minus one key | — | refused (`JL0104`) for `x-entity`: the pen owns that keyword |
 | `.entity(patch)` | the patch, merged into `x-entity` — the primitive every row above is written in terms of, and the way to spell a member of the vocabulary that has no method of its own | — (it sets no flag; the named methods do — §5.2) | native; a member outside the closed vocabulary, `JL0102` |
@@ -1062,10 +1064,10 @@ catch them:
 
 ## 7. Cost
 
-`@jarenjs/linq/model` builds to **<!--fact:bundle.model-->45,143<!--/fact--> bytes** as a minified,
+`@jarenjs/linq/model` builds to **<!--fact:bundle.model-->44,143<!--/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-->45<!--/fact--> kB) beside the other nine subpath prices in
+(<!--fact:bundle.model.kb-->44<!--/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
@@ -1083,10 +1085,32 @@ 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-->36,717<!--/fact--> is about 8 kB: the mixin, the
+The price above the schema pen's <!--fact:bundle.schema-->35,285<!--/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
 works is why a mapping mistake is a `JL0102` at build rather than a
 `JD0005` at `openStore`, so the ceiling is raised with the reason and the
 text is not shaved.
+
+## Existing column layouts and persistence rules
+
+An entity object builder's `.physical({ table, kind?, keys?, columns })` writes
+an explicit column-only layout onto the entity declaration. Each column names
+its physical identifier, codec, SQL NULL policy, and optional database default
+or generated ownership. `.invariants(rules)` writes application-declared predicates
+with explicit database/store enforcement. The pen emits declarations; the database
+package owns validation, codecs, SQL lowering and preservation planning. See
+[MODEL-FORMAT](../../db/docs/MODEL-FORMAT.md#12-existing-column-layouts).
+
+```js
+import * as m from '@jarenjs/linq/model';
+const model = m.defineModel({ entities: {
+  Setting: m.object({ id: m.string().key(), value: m.string() }).physical({
+    table: 'app_settings', columns: {
+      id: { name: 'key', codec: 'text', null: 'reject' },
+      value: { name: 'value', codec: 'text', null: 'reject' }
+    }
+  })
+} });
+```

package/docs/PROJECT-PEN.md

@@ -17,8 +17,8 @@ layout defaults. `validateFile()` checks each file through its own engine.
 
 | Method | Emits | Type | Status |
 |---|---|---|---|
-| `file(name, kind, text)` | `{ name, kind, text }`, preserving text | literal name/kind | native |
-| `jsonFile(name, kind, document)` | same file, with serialized JSON text | literal name/kind | native |
+| `file(name, kind, text, options?)` | `{ name, kind, text }` and optional routing/import members, preserving text | literal name/kind | native |
+| `jsonFile(name, kind, document, options?)` | same file, with serialized JSON text | literal name/kind | native |
 | `defineProject(files?, options?)` | version, files, optional active/layout | names from files | native |
 | `.files(files)` | replacement file list | replaces known names | native |
 | `.file(file)` | appended file | adds its name | native |
@@ -42,6 +42,12 @@ Call `parseProject(project.schema)` from `@jarenjs/studio`. A parsed nonempty
 project round-trips through JSON and the parser unchanged. Empty projects are
 valid; the parser represents their absent active file as `null` internally.
 
+File options preserve `imports`, `input`, `model` and `collection`. For example,
+`jsonFile('app', 'app', { view: [] }, { imports: { state: 'seed' } })` supplies
+state from another file; `file('q', 'query', '"$"', { model: 'store', collection:
+'notes' })` routes a query to a store. The pen snapshots these values without
+resolving them. Studio checks missing references, cycles and execution kinds.
+
 ## 4. Refusals
 
 | Code | Condition |
@@ -57,7 +63,7 @@ pen preserves these behaviors and does not carry a second project validator.
 
 `ProjectBuilder<Names>` tracks file names only in declarations. `FILE_KINDS`
 contains the schema's file-kind vocabulary, checked against Studio's own set.
-`ProjectFile<Name, Kind>`, `FileKind`, `ProjectLayout` and `ProjectDocument` are
+`ProjectFile<Name, Kind>`, `ProjectFileOptions`, `FileKind`, `ProjectLayout` and `ProjectDocument` are
 types. `JsonInput` accepts readonly structural documents and leaves unknown
 schema extension values to the runtime JSON check. `.files()` replaces the name union and `.file()` widens it. `.active()`
 refuses an undeclared literal name in TypeScript. `from()` deliberately keeps
@@ -71,5 +77,5 @@ app rendering and contract checks remain the file engines' responsibilities.
 
 ## 7. Cost
 
-The isolated project pen costs **<!--fact:bundle.project-->15,132<!--/fact--> bytes**.
+The isolated project pen costs **<!--fact:bundle.project-->13,793<!--/fact--> bytes**.
 Its tree probe excludes Studio, other target engines and the query chain.

package/docs/QUERY-PEN.md

@@ -472,8 +472,9 @@ time:
   emits `{ "$for": { "it": "$.Post[*]", "it2": "$.User[*]" }, "$where":
   { "$eq": ["$it.authorId", "$it2.id"] }, "$return": "$it" }` — the shape
   the store's translator answers in ONE statement when the result is a
-  bare binding (MODEL-FORMAT §10.2), and the declared residual over both
-  fetched roots when it is a projection (§10.6). `concat` stays
+  bare binding or a projection tree of member paths and constants
+  (MODEL-FORMAT §10.2). An opaque projection remains a declared residual
+  over the fetched roots (§10.6). `concat` stays
   same-source even within a scope: one input per document. A scope MAY
   carry `relations` — the relation tables of every root of the scope,
   keyed by root name (a store's does) — which is where a chained hop
@@ -565,6 +566,7 @@ Runtime errors (`LinqRuntimeError`):
 | `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)) |
+| `JL2009` | a durable mapped record violated identity, retention or fencing |
 | `JL2008` | a federated fetch reached its row or byte budget (§12.1) |
 
 Engine errors (`JQ…`) from a hand-written `fromDocument` document pass
@@ -732,46 +734,55 @@ const rows = await fromAsync(fed.source('orders'))
 spaces or other characters), 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.
+1. Each side's own filters and projection run at its source. Cursor sources
+   receive that document directly; buffered sources receive an array wrapper
+   so array-valued projected rows retain their item boundaries.
+2. Mandatory equality predicates form a connected binding graph. The smallest
+   declared `estimatedRows` starts the fetch. Each subsequent side is the
+   smallest estimated side connected to an already fetched side. Missing or
+   equal estimates preserve binding declaration order. Equality inside an OR
+   does not establish an edge; disconnected bindings refuse `JL0005` before
+   any source opens.
+3. Each next side is reduced against the retained keys of its already fetched
+   neighbours. Singular member/index paths are supported, including quoted
+   names and negative array indexes. Compound key values are conservatively
+   retained for the engine to compare.
+4. The original query engine decides the result over those sets, in the
+   original binding order. Fetch order never changes tuple or result order.
+   Packed joins emitted by successive `.join()` calls execute inside out;
+   their projected results become bounded intermediate sides. Aliases of one
+   source retain independent fetched sets.
+
+`explain(document)` reports `strategy`, per-side `budget`, `combinedBudget`,
+`order` (the ordered side descriptions), and `resident.document`. Each side
+names its source, estimate, join key, child document and `row`/`buffered`
+streaming mode. Nested sides additionally expose `children`. `build` and
+`probe` remain the first two sides for compatibility.
+
+**Budgets are admission credits.** `maxRows` and `maxBytes` apply separately
+at each source or intermediate. `maxTotalRows` and `maxTotalBytes` cover all
+retained source and intermediate admissions in the entire call, and default
+to twice their corresponding per-side budget. All four are positive safe
+integers. Credits are cumulative: freeing an intermediate's inputs does not
+refund them. This conservative rule makes a nested plan's total explicit.
+
+A cursor refuses with `JL2008` before retaining the row that would exceed a
+credit. Buffered sources are checked after they produce their array. Nested
+resident phrases additionally cap `sequenceItems` and `resultItems` at
+`maxRows` (or a stricter caller limit); exceeding those intermediate limits
+raises `JL2008`. Intermediate bytes are checked after projection. These are
+bounds on admitted data and intermediate item counts, **not** a promise to
+bound a buffered provider's heap, the size of one constructed value, or the
+final resident result. A caller can also supply query-engine limits for that
+final result. Estimates affect planning only, never admission.
+
+Every opened cursor closes exactly once on success, budget refusal, child
+failure or cancellation. `signal` is checked at row boundaries and passed to
+providers. Cleanup failures preserve a primary execution failure and never
+strand another opened cursor.
+
+There is no spill, distributed transaction or cross-source write. A merge
+strategy remains unavailable because providers declare no ordering guarantee.
 
 ## 13. Worked examples
 
@@ -1195,7 +1206,7 @@ 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) |
+| `JL2008` | a federated fetch or intermediate reached a per-side or combined row/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
@@ -1314,7 +1325,7 @@ that preserves it, so there is no spelling that is allowed to.
 | `from(rows).join([], …)` | `join takes another sequence as its inner side` | `from(sameSource)` |
 | `from(a).join(from(b), …)` | `join's other side must derive from the same source, or from two providers sharing one scope (one store's entity sets) — a query document reads one input; load both collections under one root, or join two entity sets of one store` | one source, or one store's two entity sets (§13.2) |
 | `from(rows).concat(42)` | `concat takes a sequence or a constant array` | a sequence over the same source, or an array |
-| `select((r) => r.v.all().rolling(spec))` where `spec` reads the row | `rolling() takes a plain literal spec object; it is read once when the query compiles, so it cannot be an expression or carry a captured value` | a literal spec |
+| `select((r) => r.v.all().rolling(spec))` where `spec` reads the row | `rolling() takes a plain literal spec object, not an expression or captured value` | a literal spec |
 
 **A provider or a document that is not shaped as the contract says.**
 
@@ -1672,14 +1683,14 @@ are shorter:
 ## 17. Cost
 
 A consumer importing `from` from `@jarenjs/linq` and calling one
-terminal bundles **<!--fact:bundle.chain-->174,131<!--/fact--> bytes** (esbuild, ESM, minified, tree-shaken,
+terminal bundles **<!--fact:bundle.chain-->175,221<!--/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-->40,131<!--/fact--> bytes** are the chain's own modules — `sequence.js`,
+Of that, **<!--fact:bundle.chain.own-->38,701<!--/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
@@ -1700,13 +1711,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-->20<!--/fact--> kB JSLT
-  pen <!--fact:bundle.jslt.kb-->20<!--/fact--> kB.
+  module either, which is what keeps a <!--fact:bundle.jslt.kb-->18<!--/fact--> kB JSLT
+  pen <!--fact:bundle.jslt.kb-->18<!--/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-->174<!--/fact--> kB and
-`./db` at <!--fact:bundle.db.kb-->628<!--/fact--> kB.
+are the ones to read together: the chain at <!--fact:bundle.chain.kb-->175<!--/fact--> kB and
+`./db` at <!--fact:bundle.db.kb-->676<!--/fact--> kB.
 The client costs what the store costs, by construction, and the chain
 costs what running a query costs.
 
@@ -1715,7 +1726,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-->198,801<!--/fact--> bytes** — **<!--fact:bundle.chain.shared-->12,047<!--/fact--> bytes** less than the sum of the
+bundles **<!--fact:bundle.chain.withSchemaPen-->199,375<!--/fact--> bytes** — **<!--fact:bundle.chain.shared-->11,131<!--/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
@@ -1723,3 +1734,19 @@ share with a pen is the pens' own two shared doors, `capture-root.js`
 and `json-boundary.js`: no chain callback reaches either, and neither is
 in the figure above. Every pen document's §7 carries its own
 subpath's figure; nothing here restates one.
+
+## Native column queries and ranges
+
+Chains and JSON documents share the db planner. Adopted scalar projections, connected joins, restricted correlated counts and proved one-root grouped aggregates have [native plans](../../db/docs/NATIVE-PLANS.md); unsupported shapes retain explanations and strict-mode refusals. The structural [range provider](../../app/docs/COLLECTION-PROVIDER.md) is `handle.range(spec, options)` from the root client, composed over the existing pager and capture.
+
+
+## Lexical provider authoring
+
+A string expression's `lexical(provider, request)` method emits
+`{ $lexical: [provider, textExpression, request] }`. The provider name is a nonempty
+string; the request is a plain literal JSON object. It records a declaration,
+never builds an index or runs a second ranker. Compile the emitted document with
+`compileJsonQuery(document, {lexicalProviders})`, binding the same
+`createLexicalProvider` capability that a hand-written query uses. The ordinary
+sequence provider has no implicit search catalog. Filters/facets run before top-k,
+continuations bind the source snapshot, and `$search` remains regex-based.

package/docs/SCHEMA-PEN.md

@@ -1167,10 +1167,10 @@ hand, or generate it some other way, when:
 
 ## 7. Cost
 
-`@jarenjs/linq/schema` builds to **<!--fact:bundle.schema-->36,717<!--/fact--> bytes** as a minified,
+`@jarenjs/linq/schema` builds to **<!--fact:bundle.schema-->35,285<!--/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-->37<!--/fact--> kB) beside the other nine subpath prices in
+(<!--fact:bundle.schema.kb-->35<!--/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.73.0",
+  "version": "0.83.2",
   "type": "module",
   "main": "./src/index.js",
   "types": "./types/index.d.ts",
@@ -67,6 +67,10 @@
     "./ai": {
       "types": "./types/ai.d.ts",
       "default": "./src/ai/index.js"
+    },
+    "./formula": {
+      "types": "./types/formula.d.ts",
+      "default": "./src/formula/index.js"
     }
   },
   "files": [
@@ -104,13 +108,13 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.73.0",
-    "@jarenjs/json": "^0.73.0"
+    "@jarenjs/core": "^0.83.2",
+    "@jarenjs/json": "^0.83.2"
   },
   "peerDependencies": {
-    "@jarenjs/db": "^0.73.0",
-    "@jarenjs/formats": "^0.73.0",
-    "@jarenjs/validate": "^0.73.0"
+    "@jarenjs/db": "^0.83.2",
+    "@jarenjs/formats": "^0.83.2",
+    "@jarenjs/validate": "^0.83.2"
   },
   "peerDependenciesMeta": {
     "@jarenjs/db": {