@jarenjs/linq 0.75.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,735 | 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,735 | 34 | 8 | 15 | 174,241 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,363 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 | 633,786 B |
-| **16 documents** | | **12,401** | **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,241 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,363 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) | 633,786 B | 634 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,363<!--/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

@@ -566,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
@@ -1324,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.**
 
@@ -1682,14 +1683,14 @@ are shorter:
 ## 17. Cost
 
 A consumer importing `from` from `@jarenjs/linq` and calling one
-terminal bundles **<!--fact:bundle.chain-->174,241<!--/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
@@ -1710,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-->634<!--/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.
 
@@ -1725,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,911<!--/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
@@ -1733,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.75.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.75.0",
-    "@jarenjs/json": "^0.75.0"
+    "@jarenjs/core": "^0.83.2",
+    "@jarenjs/json": "^0.83.2"
   },
   "peerDependencies": {
-    "@jarenjs/db": "^0.75.0",
-    "@jarenjs/formats": "^0.75.0",
-    "@jarenjs/validate": "^0.75.0"
+    "@jarenjs/db": "^0.83.2",
+    "@jarenjs/formats": "^0.83.2",
+    "@jarenjs/validate": "^0.83.2"
   },
   "peerDependenciesMeta": {
     "@jarenjs/db": {

package/src/db/effects.js

@@ -0,0 +1,148 @@
+//@ts-check
+/** Durable external intent/evidence in mapped tables, fenced by the existing job engine. */
+import { canonicalizeJson } from '@jarenjs/json/canonical';
+import { mappedRecords, recordTransaction, copyRecord, refuseRecord } from './records.js';
+
+const zero = Object.freeze({ changes: 0, writes: 0, revisions: 0 });
+const terminal = (state) => state === 'confirmed' || state === 'rejected';
+/**
+ * Preparation/outbox and each settlement commit locally. Remote delivery never
+ * runs inside this adapter. Intent is permanent until evidence resolves it.
+ * @param {any} client @param {{ operations: any, maxLegs?: number, maxBytes?: number }} options
+ */
+export function createDbEffectStore(client, options) {
+  const records = mappedRecords(client, options?.operations);
+  const { maxLegs = 64, maxBytes = 262144 } = options;
+  for (const limit of [maxLegs, maxBytes]) if (!Number.isSafeInteger(limit) || limit < 1) throw new TypeError('effect limits must be finite positive integers');
+  const inside = (fn) => recordTransaction(client, fn);
+  const requireRecord = async (tx, id) => {
+    const record = await records.get(tx, id);
+    if (!record) throw refuseRecord('unknown external operation');
+    return record;
+  };
+  const guard = async (tx, record, revision, lease) => {
+    if (record.revision !== revision || lease?.jobId !== record.plan.jobId) throw refuseRecord('stale operation revision or foreign job');
+    await tx.jobs.assertLease(lease);
+  };
+  const legOf = (record, id) => {
+    const leg = record.legs.find((value) => value.id === id);
+    if (!leg) throw refuseRecord('unknown operation leg');
+    return leg;
+  };
+  const write = async (tx, record) => {
+    record.revision++;
+    await records.put(tx, record);
+    return { record, changes: 1, writes: 1, revisions: 1 };
+  };
+  return Object.freeze({
+    /** Caller authorization must establish review/compensation authority before preparation.
+     * @param {any} plan @param {(tx: any) => any} [prepare] */
+    prepare(plan, prepare) {
+      const frozen = copyRecord(plan);
+      if (['id', 'jobId', 'kind', 'actor', 'reason', 'hashVersion'].some((name) => typeof frozen[name] !== 'string' || !frozen[name])
+        || !Array.isArray(frozen.legs) || !frozen.legs.length || frozen.legs.length > maxLegs
+        || new Set(frozen.legs.map((leg) => leg.id)).size !== frozen.legs.length
+        || frozen.legs.some((leg) => typeof leg.id !== 'string' || !leg.id
+          || !['single-send', 'provider-idempotent'].includes(leg.request?.safety)
+          || !Number.isSafeInteger(leg.maxAttempts) || leg.maxAttempts < 1 || leg.maxAttempts > 100
+          || (leg.request.safety === 'single-send' && leg.maxAttempts !== 1)
+          || (leg.request.safety === 'provider-idempotent' && !leg.request.idempotencyKey))
+        || (frozen.compensationOf !== undefined && frozen.compensationAuthorized !== true)
+        || new TextEncoder().encode(canonicalizeJson(frozen)).byteLength > maxBytes)
+        throw new TypeError('effect preparation needs bounded reviewed legs, replay safety, attempt budgets and explicit compensation authority');
+      const fingerprint = canonicalizeJson(frozen);
+      return inside(async (tx) => {
+        const prior = await records.get(tx, frozen.id);
+        if (prior) {
+          if (prior.fingerprint !== fingerprint) throw refuseRecord('reviewed operation payload changed');
+          return { record: prior, ...zero };
+        }
+        if (await tx.jobs.get(frozen.jobId) !== undefined) throw refuseRecord('operation job identity already belongs to another enqueue');
+        if (prepare) await prepare(tx);
+        const record = { id: frozen.id, plan: frozen, fingerprint, revision: 1,
+          legs: frozen.legs.map((leg) => ({ id: leg.id, state: 'prepared', attempts: 0, evidence: null, intent: null })), decisions: [] };
+        await records.put(tx, record, true);
+        await tx.jobs.enqueue(frozen.kind, { operationId: frozen.id }, { id: frozen.jobId });
+        return { record, changes: 1, writes: 1, revisions: 1 };
+      });
+    },
+    /** @param {string} id */
+    get: (id) => inside((tx) => requireRecord(tx, id)),
+    /** Persist sending before dispatch. A stale worker cannot start another send.
+     * @param {string} id @param {string} legId @param {number} revision @param {any} lease */
+    begin(id, legId, revision, lease) {
+      return inside(async (tx) => {
+        const record = await requireRecord(tx, id);
+        await guard(tx, record, revision, lease);
+        const leg = legOf(record, legId), plan = record.plan.legs.find((value) => value.id === legId);
+        if (leg.state !== 'prepared' && leg.state !== 'retry-approved') return { state: leg.state, record, ...zero };
+        if (leg.attempts >= plan.maxAttempts) return { state: 'exhausted', record, ...zero };
+        leg.state = 'sending';
+        leg.attempts++;
+        leg.intent = { generation: lease.generation, attempt: leg.attempts };
+        return { state: 'sending', ...(await write(tx, record)) };
+      });
+    },
+    /** Only the active attempt may persist transport evidence.
+     * @param {string} id @param {string} legId @param {number} revision @param {any} lease @param {any} outcome */
+    settle(id, legId, revision, lease, outcome) {
+      const observation = copyRecord(outcome);
+      if (!['confirmed', 'rejected', 'unresolved'].includes(observation.state)
+        || !Object.hasOwn(observation, 'evidence') || new TextEncoder().encode(canonicalizeJson(observation)).byteLength > maxBytes)
+        throw refuseRecord('external settlement needs bounded confirmed/rejected/unresolved evidence');
+      return inside(async (tx) => {
+        const record = await requireRecord(tx, id);
+        await guard(tx, record, revision, lease);
+        const leg = legOf(record, legId);
+        if (leg.state !== 'sending' || leg.intent.generation !== lease.generation) throw refuseRecord('no sending intent for this attempt');
+        leg.state = observation.state;
+        leg.evidence = observation.evidence;
+        return write(tx, record);
+      });
+    },
+    /** Lost workers leave uncertainty, never proof of non-application.
+     * @param {string} id @param {number} revision @param {any} lease */
+    recover(id, revision, lease) {
+      return inside(async (tx) => {
+        const record = await requireRecord(tx, id);
+        await guard(tx, record, revision, lease);
+        let changed = false;
+        for (const leg of record.legs) if (leg.state === 'sending') { leg.state = 'unresolved'; changed = true; }
+        return changed ? write(tx, record) : { record, ...zero };
+      });
+    },
+    /** Explicit read-back or operator decisions; absence is evidence only under
+     * the declared authoritative non-application guarantee. Idempotent retries
+     * retain the reviewed request/key and the original durable attempt budget.
+     * @param {string} id @param {string} legId @param {number} revision @param {any} lease @param {any} decision */
+    reconcile(id, legId, revision, lease, decision) {
+      const proof = copyRecord(decision);
+      if (['id', 'actor', 'reason'].some((key) => typeof proof[key] !== 'string' || !proof[key])
+        || !['confirm', 'reject', 'retry'].includes(proof.action) || !Object.hasOwn(proof, 'evidence')) throw refuseRecord('reconciliation needs actor/reason and evidence');
+      return inside(async (tx) => {
+        const record = await requireRecord(tx, id);
+        if (lease?.jobId !== record.plan.jobId) throw refuseRecord('foreign reconciliation job');
+        await tx.jobs.assertLease(lease);
+        const entry = { ...proof, legId };
+        const prior = record.decisions.find((value) => value.id === proof.id);
+        if (prior) {
+          if (canonicalizeJson(prior) !== canonicalizeJson(entry)) throw refuseRecord('reconciliation decision collision');
+          return { record, ...zero };
+        }
+        await guard(tx, record, revision, lease);
+        const leg = legOf(record, legId), plan = record.plan.legs.find((value) => value.id === legId);
+        if (terminal(leg.state) || !['sending', 'unresolved'].includes(leg.state)) throw refuseRecord('only unresolved intent can be reconciled');
+        if (proof.action === 'retry' && (plan.request.safety !== 'provider-idempotent' && proof.guarantee !== 'authoritative-non-application'))
+          throw refuseRecord('absence is not proof of non-application');
+        // Single-send remains single-send: an authoritative negative result can
+        // be recorded as rejected, followed by a separately reviewed operation.
+        if (proof.action === 'retry' && leg.attempts >= plan.maxAttempts) throw refuseRecord('durable attempt budget exhausted');
+        if (record.decisions.length >= 128 || new TextEncoder().encode(canonicalizeJson(entry)).byteLength > maxBytes) throw refuseRecord('reconciliation evidence limit');
+        leg.state = proof.action === 'confirm' ? 'confirmed' : proof.action === 'reject' ? 'rejected' : 'retry-approved';
+        leg.evidence = proof.evidence;
+        record.decisions.push(entry);
+        return write(tx, record);
+      });
+    },
+  });
+}

package/src/db/handle.js

@@ -18,6 +18,7 @@ import { fromAsync, AsyncSequence } from '../async.js';
 import { Graph } from './include.js';
 import { requireMembership } from './membership.js';
 import { registerLive } from './live.js';
+import { createDbRangeProvider } from './range.js';
 
 /** The chain surface, read once from the class: every public operator
  * and terminal, `explain` set aside for its overload. */
@@ -59,6 +60,7 @@ export function createEntityHandle(store, name) {
   // the graph with nothing included: the root clauses, the keyset and
   // the page over the rows alone
   members.graph = () => new Graph(set, name);
+  members.range = (spec, options) => createDbRangeProvider(store, name, spec, options);
   members.link = (own, member, target) => {
     requireMembership(set.relations, name, member, 'link');
     set.link(own, member, target);

package/src/db/index.js

@@ -22,4 +22,10 @@
 
 export { open, defaultValidator } from './open.js';
 export { createDbLedger } from './ledger.js';
+export { createDbIngestionStore } from './ingest.js';
+export { createDbRangeProvider } from './range.js';
+export { createLexicalRangeProvider } from './search.js';
 export { defineReplication } from './replication.js';
+export { createDbReceipts } from './receipts.js';
+export { createDbEffectStore } from './effects.js';
+export { createDbRunStore } from './runs.js';