@jarenjs/linq 0.73.0 → 0.83.2

package/ARCHITECTURE.md

@@ -202,16 +202,14 @@ residual runs locally, and `explain()` reports the split.
   (`JL0005`) rather than silently materialised — except two providers
   sharing a `scope` (one store's entity sets), whose roots are two
   bindings of one multi-entity input.
-- **Federation is a door, not a default.** `federate({ sources,
-  maxRows, maxBytes })` (`src/federate.js`, QUERY-PEN §12.1) hands back
-  one provider source per name, sharing one scope, so the ordinary join
-  is admitted and the federation executes it: each side's own packed
-  document at its own source, the smaller side into a bounded hash
-  table, the other probed against it, and the caller's document decided
-  in the engine over the two reduced sets. It spells no join semantics
-  of its own — the reduction bounds the FETCH, and a value it cannot
-  key is kept rather than guessed at — and a budget is a refusal
-  (`JL2008`), never a spill.
+- **Federation is explicit.** `federate()` (QUERY-PEN §12.1) accepts a
+  connected equality graph across named providers. Source-local work runs at
+  its provider; estimates choose a connected fetch order, hash sets reduce
+  candidates, and the engine retains the original tuple semantics. Packed
+  joins run inside out under the same cumulative row/byte admission credits.
+  Per-side budgets also cap intermediates; buffered production and final
+  results have the explicit limits documented in §12.1. Aliases receive
+  independent input members, and array framing preserves array-valued rows.
 - **The engine result shape leaks nowhere.** Every surface — sync,
   async, provider — reproduces `undefined | item | items` exactly,
   which is why the window-wrapper trick exists at all.

package/README.md

@@ -1,5 +1,7 @@
 # @jarenjs/linq
 
+The pens emit documents; `linq/db` supplies the declared optional database adapter edge. The [combined adoption recipe](../../docs/ADOPTION-EVIDENCE.md) composes mappings, receipts, ingestion and run adapters over one transaction owner, with host and retirement limits visible.
+
 **Write it once, in typed JavaScript. Keep it as data.**
 
 Every engine in this repository runs a JSON document. The validator runs
@@ -47,7 +49,7 @@ SQL — and nothing is hidden: the chain's `explain()` shows the document
 it sent, and the store's `explain(document)` shows what that became,
 `SELECT … FROM "User" WHERE "age" > ? ORDER BY "name"`.
 
-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-->
 
 ## What you gain
 
@@ -729,4 +731,16 @@ Every subpath a consumer can import, derived from the manifest by
 | `@jarenjs/linq/jtlt` | JavaScript | declared |
 | `@jarenjs/linq/messages` | JavaScript | declared |
 | `@jarenjs/linq/ai` | JavaScript | declared |
+| `@jarenjs/linq/formula` | JavaScript | declared |
 <!--/fact-->
+
+Explicit cross-provider joins use `federate({ sources, maxRows, maxBytes,
+maxTotalRows, maxTotalBytes })`. Connected joins across three or more sources,
+including successive fluent `.join()` calls, preserve the engine's result
+order while sharing cumulative admission credits. See
+[QUERY-PEN §12.1](docs/QUERY-PEN.md#121-the-federation-boundary-federate) for
+planning, buffering limits and cleanup guarantees.
+
+## Saved formula documents
+
+`@jarenjs/linq/formula` exports `defineFormula` for immutable JSON Query profiles with revision, bindings and schema/helper references. See [FORMULA-PEN](docs/FORMULA-PEN.md); execution remains in json/formula.

package/docs/AI-PEN.md

@@ -94,5 +94,5 @@ sub-call budgets, storage and result interpretation remain runner concerns.
 
 ## 7. Cost
 
-The isolated AI program pen costs **<!--fact:bundle.ai-->16,904<!--/fact--> bytes**.
+The isolated AI program pen costs **<!--fact:bundle.ai-->15,472<!--/fact--> bytes**.
 Its tree probe excludes AI, other target engines and the query chain.

package/docs/APP-PEN.md

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

package/docs/CHARTS-PEN.md

@@ -89,6 +89,6 @@ render tooltips; those responsibilities remain in the chart engine.
 
 ## 7. Cost
 
-The isolated chart pen costs **<!--fact:bundle.charts-->17,014<!--/fact--> bytes**.
+The isolated chart pen costs **<!--fact:bundle.charts-->15,582<!--/fact--> bytes**.
 The tree-shaking gate refuses chart engine, other target engine and chain
 modules in this bundle, and checks that the chain and schema pen do not import it.

package/docs/CONTRACT-PEN.md

@@ -1188,10 +1188,10 @@ to write, and reaching them means one import of `@jarenjs/contract` over
 
 ## 7. Cost
 
-`@jarenjs/linq/contract` builds to **<!--fact:bundle.contract-->48,859<!--/fact--> bytes** as a minified,
+`@jarenjs/linq/contract` builds to **<!--fact:bundle.contract-->47,427<!--/fact--> bytes** as a minified,
 tree-shaken ESM bundle — the figure `scripts/check-tree-shaking.js`
 measures and `npm run test:tree-shaking` reports, published rounded
-(<!--fact:bundle.contract.kb-->49<!--/fact--> kB) beside the other nine subpath prices in
+(<!--fact:bundle.contract.kb-->47<!--/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 one-operation contract as a
@@ -1200,7 +1200,7 @@ them:
 
 - **the schema pen is included, and that is the ceiling.** A contract's
   inputs and outputs are schemas, so the two are measured together and
-  the bundle carries <!--fact:bundle.schema-->36,717<!--/fact--> of its <!--fact:bundle.contract-->48,859<!--/fact--> bytes as the schema pen's own.
+  the bundle carries <!--fact:bundle.schema-->35,285<!--/fact--> of its <!--fact:bundle.contract-->47,427<!--/fact--> bytes as the schema pen's own.
   The contract pen's own share is the remaining ~12 kB, most of it the
   refusal messages §4 lists;
 - **no chain module** — none of `sequence.js`, `document.js`, `async.js`,
@@ -1216,6 +1216,6 @@ them:
 A consumer who writes a contract and also compiles it pays both prices
 and they add rather than overlap. That is the shape the separation is
 for: a browser bundle that only needs the TYPES a contract implies —
-`typedClient` over an HTTP binding, say — ships the pen's <!--fact:bundle.contract.kb-->49<!--/fact--> kB and none
+`typedClient` over an HTTP binding, say — ships the pen's <!--fact:bundle.contract.kb-->47<!--/fact--> kB and none
 of the compiler, while the server that serves the contract imports
 `@jarenjs/contract` and does not need the pen at all.

package/docs/DB-CLIENT.md

@@ -115,6 +115,11 @@ back, the durable ledger over what it opened, and replication document authoring
 | `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>` |
 
 `open` is the only door, and it is deliberately not a coded refusal: a
 missing `options`, or a `validator` that is not a `JarenValidator`, is a
@@ -128,18 +133,18 @@ reconstruct the configuration by reading this paragraph.
 
 ### 2.3 The entity handle
 
-A handle is 59 members and no Proxy: 18 from the store's entity set, 40
-from the chain, one name in both (`explain`, resolved below), and two of
-the client's own.
+A handle has no Proxy. It combines the store's entity set, the asynchronous
+chain, and the client's graph, live and range adapters. `explain` is shared
+and resolved below.
 
 | 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` |
 
 **`explain` is the one name the store's set and the chain both carry, and
@@ -309,6 +314,18 @@ See the [replication format](../../db/docs/REPLICATION-FORMAT.md) for causality,
 conflict policy and bounded reset contracts. Authoring does not allocate a
 committed sequence; normal replication exports the Store's committed pages.
 
+### Lexical ranges
+
+`createLexicalRangeProvider(source, text, request, options)` composes a
+`createDbSearch` source from `@jarenjs/db/search` with the shared structural range
+implementation. `maxMatches` and `maxSourceBytes` cap complete source membership;
+`maxRows`, `maxBytes`, `maxPages` and `maxInFlight` cap range work and retained pages.
+A truncated search refuses rather than presenting incomplete membership as a
+complete collection. Filters/facets/order use the query provider's one meaning.
+Source resets invalidate requests; `refresh()` rebuilds the bounded range under
+the new source revision. Disposal drains the range and unsubscribes; set
+`disposeSource` when the range also owns its source.
+
 ## 3. Worked examples
 
 The client's examples are not builder-to-document pairs, and this is
@@ -826,10 +843,10 @@ never builds one; the migration between two of them is
 
 ## 7. Cost
 
-`@jarenjs/linq/db` builds to **<!--fact:bundle.db-->627,769<!--/fact--> bytes** as a minified,
+`@jarenjs/linq/db` builds to **<!--fact:bundle.db-->675,752<!--/fact--> bytes** as a minified,
 tree-shaken ESM bundle — the figure `scripts/check-tree-shaking.js`
 measures and `npm run test:tree-shaking` reports, published rounded
-(<!--fact:bundle.db.kb-->628<!--/fact--> kB) beside the other nine subpath prices in
+(<!--fact:bundle.db.kb-->676<!--/fact--> kB) beside the other nine subpath prices in
 [docs/CONSUMING.md](../../../docs/CONSUMING.md).
 
 It is by far the largest of the ten, and the reason is §1.1's edge rather
@@ -840,6 +857,10 @@ planner, a unit of work, a live-maintenance engine and a JSON Schema
 validator, and the honest way to read the figure is as the price of the
 database, not of the front door.
 
+Explicit physical codecs, catalog verification, invariant lowering and guarded
+SQL also ride with the store. Their measured cost is included in this figure;
+the structural bundle ceiling is 665 kB. The frozen consumer budgets are unchanged.
+
 What the probe asserts, and fails the build on:
 
 - **all three peers ride** — `@jarenjs/db`, `@jarenjs/validate` and
@@ -856,7 +877,7 @@ What the probe asserts, and fails the build on:
   asserts the same exclusion.
 
 A consumer who wants the model pen's types without the store pays
-`./model`'s <!--fact:bundle.model-->45,143<!--/fact--> bytes and installs no peer; one who wants to run
+`./model`'s <!--fact:bundle.model-->44,143<!--/fact--> bytes and installs no peer; one who wants to run
 queries against an array rather than a database pays the chain's price
 (§17 of [QUERY-PEN.md](QUERY-PEN.md)) and installs no peer. `./db` is
 the one subpath whose `package.json` entry carries an optional peer at
@@ -891,3 +912,174 @@ survives is structural, not temporal** — the graph load's statement
 counts are printed beside its timings, and the client answers a
 two-level graph in ONE statement where the schema-first ORM takes three,
 whatever the corpus and whatever the clock says.
+
+## Trusted SQL during adoption
+
+`open()` forwards `adopt: true` and physical model declarations to the store.
+A transaction client exposes `tx.sql`, `tx.jobs`, and the store's optional
+`tx.sync` surface. `tx.sql.prepare(text, { access: 'read' | 'write', affects? })`
+returns `run(params)`, `get(params)`, `all(params)` and `close()`. Parameters are
+positional arrays. These methods answer values on synchronous hosts and promises
+on asynchronous hosts. Always await asynchronous operations inside the callback;
+statement preparation rechecks scope ownership before execution, so a late
+preparation cannot write after settlement.
+
+```js
+await client.transaction(async tx => {
+  const insert = tx.sql.prepare('INSERT INTO legacy_note(body) VALUES (?)',
+    { access: 'write' });
+  await insert.run(['reviewed']);
+  await tx.entities.Setting.update('locale', { value: 'nl-NL' });
+  await tx.jobs.enqueue('publish', { key: 'locale' });
+  insert.close();
+}, { mode: 'immediate' });
+```
+
+The SQL capability accepts trusted application statements with explicit access.
+It refuses multiple statements, transaction control, schema changes and connection
+configuration. A retained statement or continuation refuses after scope settlement
+or while a nested scope owns the connection. Closing a statement invalidates its
+public handle; underlying cached/native storage belongs to the connection.
+
+SQL writes conservatively invalidate clean tracked entities, including effects of
+unknown triggers/cascades. Pending tracked changes must first be saved or discarded.
+The optional `affects` declaration does not narrow this conservative policy.
+SQL writes refuse capture/replication and store-only invariant configurations whose
+coverage they cannot honor. This capability is not an untrusted-SQL sandbox;
+application-supplied SQL and host functions remain trusted.
+
+`store.sync.transaction(fn, { mode: 'immediate' })` uses the same writer and
+savepoint owner. It rejects thenables and invalidates post-return work. Async-only
+hosts have no synchronous transaction surface. The outbox infrastructure must
+already have been provisioned through an explicit setup/migration before a
+no-DDL adoption; opening with jobs enabled is a separate infrastructure operation.
+
+## Complete ingestion store
+
+`createDbIngestionStore(client,{staging,checkpoints,publications,facts?,reconcile?})`
+uses application-declared document collections through the root or transaction
+client. Collection names must be distinct. The root adapter opens an immediate
+transaction; a transaction adapter nests under that owner. It introduces no
+second ledger, transaction engine or fixed provider schema.
+
+```js
+import { open, createDbIngestionStore } from '@jarenjs/linq/db';
+import { nodeDriver } from '@jarenjs/db/node';
+
+const model = { $model: '0.1', collections: Object.fromEntries(
+  ['observations', 'pulls', 'snapshots', 'facts'].map((name) => [name, {
+    key: '/id', schema: { type: 'object' }, indexes: [],
+  }]),
+) };
+const client = await open(model, { driver: nodeDriver(), path: 'ingestion.db' });
+const store = createDbIngestionStore(client, {
+  staging: 'observations', checkpoints: 'pulls', publications: 'snapshots', facts: 'facts',
+  reconcile: (existing, incoming) => existing?.provenance === 'manual' ? existing : incoming,
+});
+// Pass store to createIngestion; close client after ingestion and workers drain.
+```
+
+`begin(plan)` creates or resumes a generation, or returns `unchanged` when the
+current published fingerprint matches. A fingerprint includes source version,
+partitions, input, policy revision and consistency. Generations cannot be reused
+with a changed plan. `stage(plan,partition,page)` commits exact raw page text,
+parsed/transformed observations and continuation/completion evidence together.
+An identical repeated page does no work; a conflicting page or stale cursor is
+refused. `inspect(plan)` returns the checkpoint and retained observations.
+`invalidate` preserves them while fencing the generation from publication.
+
+`publish(plan,evidence)` requires completed coverage of every requested
+partition, matching source evidence and the publication generation observed at
+begin. Concurrent stale publication is refused. The pointer, completion record
+and any reconciled facts commit together. If reconciliation or persistence
+fails, all those changes roll back while staging remains available for recovery.
+`current(source)` reads the published pointer and its completion evidence.
+
+Facts use the collision-free JSON tuple `[source,partition,providerId]`; strings
+retain leading zeros. `reconcile(existingValue,incomingRow,evidence)` is a pure
+synchronous policy and defaults to the incoming row. It must explicitly preserve
+manual provenance when required. Equal values do not write or increment the
+fact's revision. Reported `changes`, `writes` and `revisions` count effective
+fact changes; staging/checkpoint/manifest metadata is separate. An identical
+published pull performs no metadata writes either. A new policy or source
+version can publish a new manifest with zero fact changes.
+
+The complete pointer defines source membership. The facts collection is a
+reconciled history of observed identities; missing identities are not implicitly
+deleted. Applications own retirement of absent facts, staging retention and
+business-history policy. Without `facts`, only raw staging and publication are
+maintained. No provider schema, receipt TTL or manual-edit rule is inferred.
+
+## Durable mapped records
+
+`createDbReceipts`, `createDbEffectStore` and `createDbRunStore` from
+`@jarenjs/linq/db` adapt application-declared collections or entities. Each record option
+accepts its name, `{ collection, read, write }` or `{ entity, read, write, key? }`:
+synchronous, lossless mappings
+between application fields and canonical records with an `id`. The optional
+`key(id)` maps canonical identity to the declared physical key, including a
+composite key object. Entity writes use the existing direct create/update/delete
+API, read back the persisted result, and refuse lost identity before commit. A failed
+round-trip or changed identity refuses `JL2009`. Physical tables and column names
+remain the model's declarations; no adapter creates a second authoritative
+business ledger. Root operations use immediate transactions; transaction-client
+adapters use the caller's savepoint and commit with that caller.
+
+`createDbReceipts(client, { receipts, leases?, runtime? })` stores permanent
+command identity, validated outcome, stable references and creation/revision
+metadata. Its trusted-host methods are `lookup`, `execute`, `claim`, `release`,
+`sweep`, `migrate` and `compact`. Authorization belongs to the command layer.
+Claim leases are independent execution capabilities: expiry/recovery replaces
+the token, while receipt lookup always wins before admitting any work. A hash
+or hash-version collision refuses; receipts never expire. Sweep accepts at most
+1000 selected identities and deletes only expired leases. It never interprets
+replication acknowledgement as retention permission.
+
+Migration takes at most 1000 explicit receipt outcomes with references. It
+preserves originals and later receipts; a conflicting identity/outcome/reference
+refuses the whole batch. Repeating it reports zero changes, writes and revisions,
+including after compaction/restart. Expired HTTP claims cannot be imported as
+business outcomes implicitly. Compaction requires `retainReplay: true`,
+`retainReferences: true`, `actor` and `reason`; it removes only auxiliary data,
+keeps collision identity/outcome/references, and becomes a zero-write no-op on
+repeat. Erasure is unsupported and refused.
+
+`createDbEffectStore(client, { operations, maxLegs?, maxBytes? })` provides
+`prepare`, `get`, `begin`, `settle`, `recover` and `reconcile`. A reviewed plan
+contains `id`, `jobId`, `kind`, `actor`, `reason`, `hashVersion` and bounded `legs`.
+Each leg names `id`, a provider `request` and `maxAttempts`; arbitrary reviewed
+selection/payload declarations stay in the frozen plan. Preparation plus its
+optional local callback and enqueue co-commit. Repeated preparation is a no-op;
+changed reviewed bytes refuse. Each sending/settlement operation compares the
+operation revision and uses `tx.jobs.assertLease` against the plan's job ID.
+Remote I/O occurs outside these transactions. Confirmed/rejected/unresolved
+states and individual leg attempts survive lease takeover.
+
+Reconciliation requires a unique decision `id`, `actor`, `reason`, `action`
+(`confirm`, `reject`, `retry`) and public `evidence`. Repeating identical evidence
+is a zero-write/revision no-op; a reused decision ID with different evidence
+refuses. Idempotent retries preserve the provider key and original attempt
+budget. Absence without an authoritative non-application guarantee is not retry
+permission. A single-send leg remains limited to one attempt; a proven negative
+may be rejected and followed by a separately reviewed operation. Compensation
+requires a separate plan with `compensationOf`, `compensationAuthorized: true`
+and its own authorized actor/reason. The trusted host must establish that
+permission; the boolean is recorded evidence, not authentication.
+
+`createDbRunStore(client, { runs, events, statuses?, summary?, canReset?,
+maxPage?, maxBytes? })` attaches existing IDs and status vocabularies to workflow
+checkpoints. `attach` verifies workflow/schema/job identity, `load` checks it
+before reading a checkpoint, and `save` combines workflow generation CAS, the
+job fence, mapped status, summary and event in one transaction. The application
+`summary(snapshot)` projects only public JSON. Default summaries contain status
+and generation, not inputs or results. `get` is trusted/private;
+`page(id, { after, limit })` exposes bounded public events and current summary.
+Missing event history returns `reset-required` with the current durable cursor.
+
+`requestCancel` compares the observed revision and records actor/reason;
+`finish` persists a final cancelled/failed observation after draining.
+`reset` changes only this run's checkpoint and requires current revision,
+inactive status, actor/reason and a transactional `canReset(tx, record)` policy.
+The default refuses; the policy must consult receipts and unresolved effects.
+Reset never deletes those tables. Incompatible workflow/schema identities refuse;
+a host must perform an explicitly reviewed migration before attachment.

package/docs/FLOW-PEN.md

@@ -985,10 +985,10 @@ meaning is a `$return` that constructs an array explicitly.
 
 ## 7. Cost
 
-`@jarenjs/linq/flow` builds to **<!--fact:bundle.flow-->19,910<!--/fact--> bytes** as a minified,
+`@jarenjs/linq/flow` builds to **<!--fact:bundle.flow-->18,478<!--/fact--> bytes** as a minified,
 tree-shaken ESM bundle — the figure `scripts/check-tree-shaking.js`
 measures and `npm run test:tree-shaking` reports, published rounded
-(<!--fact:bundle.flow.kb-->20<!--/fact--> kB) beside the other nine subpath prices in
+(<!--fact:bundle.flow.kb-->18<!--/fact--> kB) beside the other nine subpath prices in
 [docs/CONSUMING.md](../../../docs/CONSUMING.md).
 
 The probe is a gate, not a report. Building a machine with a guard and
@@ -1015,7 +1015,7 @@ two effects as a consumer would — `defineFsm`, `state`, `on` and
   `packages/linq/src/flow/`.
 
 Two documents, two grammars, thirteen exported names — and 57 bytes more
-than `./jslt`'s <!--fact:bundle.jslt-->19,856<!--/fact-->, which writes one. The reason is that most of
+than `./jslt`'s <!--fact:bundle.jslt-->18,424<!--/fact-->, which writes one. The reason is that most of
 both prices is the same shared machinery: the recording proxy
 (`expression.js`), the root capture (`capture-root.js`) and the JSON
 boundary (`json-boundary.js`). What this pen adds on top of them is 685

package/docs/FORMS-PEN.md

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

package/docs/FORMULA-PEN.md

@@ -0,0 +1,41 @@
+# Formula document authoring
+
+> `./formula` — author versioned saved JSON Query profiles without executing them.
+
+## 1. What it writes
+
+`defineFormula(id, expression, options?)` from `@jarenjs/linq/formula` emits a frozen
+`$formula: "1"` JSON document. The default revision is `"1"`. Options declare
+revision, immutable bindings, input/result schema references, helper versions and
+result mode. The expression is an existing JSON Query document. The pen validates
+the envelope and JSON boundary without executing a formula or importing a component.
+
+```js
+import { defineFormula } from '@jarenjs/linq/formula';
+const amount = defineFormula('amount', { $mul: ['$.price', '$.quantity'] }, {
+  revision: '2',
+  inputSchema: { id: 'row', version: '1' },
+});
+```
+
+Compile the document using `@jarenjs/json/formula` and a host schema registry/type
+compiler. [The formula format](../../json/docs/FORMULA-FORMAT.md) owns execution,
+missing/null arithmetic, explicit migration and reviewed-plan semantics.
+
+## 2. The mapping table
+
+| Call / option | Emitted member |
+|---|---|
+| `defineFormula(id, expression)` | `$formula`, `id`, `expression`, default `revision` |
+| `revision`, `bindings`, schema/helper references, result mode | Same named profile members |
+
+## 3. Refusals
+
+Non-JSON authoring input is `JL0101`; invalid envelopes and unresolved runtime
+capabilities use the owning JSON formula registry. The pen never executes a query.
+
+## 4. Cost
+
+The isolated formula pen costs **<!--fact:bundle.formula-->14,850<!--/fact--> bytes**.
+Its bundle contains envelope validation and JSON helpers, with no Query evaluator
+or component. The tree-shaking gate enforces the separate authoring boundary.

package/docs/JSLT-PEN.md

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

package/docs/JTLT-PEN.md

@@ -79,5 +79,5 @@ validate XML well-formedness, render text, or add a second dispatch language.
 
 ## 7. Cost
 
-The isolated JTLT pen costs **<!--fact:bundle.jtlt-->16,725<!--/fact--> bytes**.
+The isolated JTLT pen costs **<!--fact:bundle.jtlt-->15,293<!--/fact--> bytes**.
 Its tree probe excludes target engines and the query chain.