@jarenjs/contract 0.73.0 → 0.83.2

package/docs/CONTRACT-FORMAT.md

@@ -261,25 +261,44 @@ top-level `input.properties` member gets exactly one location:
    does not declare);
 4. otherwise the default: `query` for a `read`, `body` for a `command`.
 
-Path, query and header members arrive as strings and are decoded by a
-normalizer compiled **over those members only** with `coerceTypes`
-(`@jarenjs/validate/normalize`); **a body member is never coerced**. The
-compiled operation carries this as
-`input.transport = { normalize, members: { path, query, header, repeated }, schemas, required }`
-(`null` when nothing travels as a string) beside `input.effective` —
-the object schema the declared `input` resolves to (itself, or the end
-of its `$ref` chain), whose `properties` are the operation's members;
-`schemas` holds each
-transport member's declared schema and `required` the transport members
-the input requires (what a URL builder validates without the body), and
-`repeated` lists the
-query and header members whose effective schema type is `array` — a
-decoder collects repeats of those into an array (a repeated query key; a
-repeated header line or a comma-separated header list, RFC 9110 §5.3)
-before normalizing; every other query member is last-wins and every
-other header member is one line (§7.4). The server validates the
-reassembled input object with the operation's compiled validator; the
-client validates the same object before it splits it.
+Scalar path, query and header members arrive as strings and are decoded
+by a normalizer compiled over those members with `coerceTypes`
+(`@jarenjs/validate/normalize`). **JSON query members and body members are
+never coerced**, including nested values.
+
+A query member whose effective declared `type` is `object` or `array`
+(or a type array including either) uses **one JSON value in one query
+parameter**. The client applies `JSON.stringify`, then `URLSearchParams`;
+the server percent-decodes and applies `JSON.parse` before validation.
+This includes nullable and scalar/structured unions: their values always
+use JSON encoding. Empty arrays, nulls, arrays of objects, numeric object
+keys and strings inside those unions round-trip without guessing from
+text. An absent member is omitted. Plain `string` members remain literal,
+even when their text looks like JSON. `$ref` chains are resolved at
+compilation; unconstrained schemas and unions expressed only with
+`anyOf`/`oneOf` do not imply a codec — declare a top-level `type` to choose
+one. Malformed JSON or multiple occurrences of a JSON member are `JC2012`;
+a well-formed value of the wrong type is `JC2006`. Undeclared query keys
+are ignored. Scalar query members remain last-wins.
+
+The compiled operation carries
+`input.transport = { normalize, members: { path, query, header, repeated }, queryJson, schemas, required }`
+(`null` when nothing travels as a string), beside `input.effective`, the
+resolved input object schema. `schemas` and `required` describe all
+transport members for URL validation; `queryJson` lists the JSON members
+excluded from scalar normalization. `repeated` identifies array-typed
+query/header members; JSON query encoding takes precedence. Array headers
+still collect repeated lines or comma-separated values (RFC 9110 §5.3)
+before normalization; other headers require one line (§7.4). The server
+validates the reassembled input; the client validates before splitting it.
+
+**Wire migration:** array query members use `tag=["a","b"]` (URL-encoded),
+replacing `tag=a&tag=b`. Update handwritten callers and deploy matching
+client/server versions together; published contracts should change their
+`version` so revision negotiation detects a mismatched deployment. The
+OpenAPI projection declares these parameters with
+`content: { "application/json": { schema: ... } }`, rather than an
+exploded array schema.
 
 An operation bound to `GET` or `HEAD` MUST NOT carry a body-located
 member (`JC0016`) — including a `command` whose members default to the
@@ -413,6 +432,7 @@ carries the same codes and a test holds them equal.
 | JC0018 | a subscribe operation declares a `policy.task` other than `switch` — a subscription slot is replaced, never queued (§17) |
 | JC0019 | a subscribe operation is bound to a method other than `GET` — a stream is fetched, not sent (§17) |
 | JC0020 | a subscribe operation declares a `policy.idempotency` other than `none` — a subscription registers, it does not commit (§17) |
+| JC0021 | a provider descriptor is malformed or names an undeclared transform capability |
 
 `JC0021–JC0049` are reserved for further document-level rules and are
 appended to this table when they land; `JC0050–JC0069` are the binding-
@@ -601,12 +621,12 @@ is `JC2008`.
    stripped by the decoder); then `JSON.parse` (a failure is `JC2005`).
 7. **Assemble** the input object through a prototype-safe setter only, in
    this order: path members (raw decoded strings), query members
-   (`URLSearchParams` semantics — `+` is a space; a member listed in
-   `transport.members.repeated` collects every occurrence into an array,
-   every other member is last-wins; an **undeclared query key is
-   ignored, never merged**; an undecodable query is `JC2012`), declared
-   header members (by their lowercased name; §7.4), then the transport
-   normalizer over exactly those members (`coerceTypes`), then the body,
+   (`URLSearchParams` semantics — `+` is a space; `queryJson` members
+   decode one JSON value, scalar members are last-wins; an **undeclared
+   query key is ignored, never merged**; malformed encoding/JSON or a
+   repeated JSON member is `JC2012`), declared header members (by their
+   lowercased name; §7.4), then the scalar transport normalizer (JSON
+   members excluded), then the body,
    **never coerced**: `http.body` names a member → the parsed value is
    that member; otherwise the parsed value must be an object (`JC2006`
    with `path: ""` otherwise) and each of its own members is set unless
@@ -747,7 +767,7 @@ below; `HTTP_ERRORS` (`@jarenjs/contract/http`) is the same table as data,
 | `JC2009` | 409 | `contract/idempotency-conflict` | see §8 | the ledger says `in-progress` (retryable, `retry-after: 1`) or `mismatch` (not retryable, `details: [{ "kind": "mismatch" }]`) |
 | `JC2010` | 500 | `contract/invalid-output` | no | the handler value fails the output validator, cannot be serialized, a raw response is malformed, or a declared error's details fail their schema — the server broke the contract |
 | `JC2011` | 400 | `contract/malformed-path` | no | the path carries a malformed percent-escape |
-| `JC2012` | 400 | `contract/malformed-query` | no | the query string is not decodable (a malformed escape, invalid UTF-8) |
+| `JC2012` | 400 | `contract/malformed-query` | no | the query string is not decodable (malformed escape/UTF-8/JSON, or a repeated JSON member) |
 | `JC2013` | 501 | `contract/not-implemented` | no | a `partial` server has no handler for the operation |
 | `JC2014` | 412 | `contract/precondition-failed` | no | `If-Match` does not match the armed tag (strong comparison), or `If-None-Match` matches on a non-GET/HEAD |
 | `JC2015` | 400 | `contract/invalid-header` | no | a declared scalar header member arrived repeated, or a header value is not a string |
@@ -773,6 +793,9 @@ wire response:
 | `JC1009` | the stream wire's SSE encoder was handed text the frame cannot carry: a bare carriage return inside `data`, a line terminator inside `event` or `id` (§18) |
 | `JC1010` | `client.subscribe` was asked for an operation that is not a subscribe operation (§19) |
 | `JC1011` | a ledger `commit`/`fail` named a ref that settles no started record — expired, reclaimed under a newer generation, or settled already (§8); refused by the ledger, reported to `onError` by the binding |
+| `JC1013` | a durable command settlement capability is malformed |
+| `JC2110` | a durable command was refused or failed validation |
+| `JC1012` | a provider executor, descriptor host or run capability is malformed (PROVIDER-FORMAT.md) |
 
 ### §7.4 Headers
 
@@ -1341,9 +1364,9 @@ is true exactly for a 304.
    by `policy.errors.details`; **nothing was sent**.
 3. **Split by location** (`http.in`): path variables → `encodeURIComponent`
    per segment into the canonical template; query members →
-   `URLSearchParams` (an array-typed member repeats the key per element;
-   `null`/`undefined` members are omitted; a scalar is its string, a
-   non-scalar its JSON); header members → the header named by the
+   `URLSearchParams` (`queryJson` members use one JSON value, including
+   null and empty arrays; undefined is omitted; scalar transport members
+   omit null/undefined and otherwise use their string); header members → the header named by the
    member lowercased (an array as a `, `-joined list); the body: `http.body`
    names a member → `JSON.stringify` of that member's value; otherwise
    the object of the body-located members, stringified. `method` from
@@ -1712,6 +1735,23 @@ The generated actions:
 - `<ns><op>/reset` — as for tasks: `status "idle"`, `kind`/`error`
   cleared, everything else kept.
 
+Reconnect is an opt-in **binding choice**, not a new stream policy:
+`contractAppBinding(contract, { subs: { "data.live": { reconnect: { max: 2 } } } })`
+embeds the per-operation option in its generated `withQuery` props and
+`createContractSubscription` forwards it to `client.subscribe`. During
+retry/backoff the slot stays `live`, retaining its id, value and sequence;
+replay patches continue against the same cached document. Exhaustion
+surfaces `JC2097` in the slot. Explicit server end and non-network errors
+are terminal. Stop/reset/destroy cancel the active stream and prevent
+further retries. Without the option a lost stream surfaces immediately.
+Unknown/unselected/non-subscribe operations and malformed reconnect
+options are `JC1007`. Reconnection is supplied by the HTTP client; port
+and local clients retain their existing terminal channel lifecycle.
+
+The subscription handler rejects stale sequence numbers **before**
+applying a patch to its cached document, and ignores callbacks after
+cleanup; the generated action guards provide the state-side check too.
+
 The binding additionally returns `subs` — one entry per subscribe
 operation — and names its handler in `subscription`:
 
@@ -1807,7 +1847,7 @@ point). The mapping:
 |---|---|
 | — | `openapi: "3.1.0"`, `jsonSchemaDialect: "https://json-schema.org/draft/2020-12/schema"`, `info` (title/version defaulting to the contract id/version), `servers` when given |
 | operation | `paths[<canonical path>][<lowercased method>]`, paths sorted by path then method; `operationId` = the id; `summary` = `doc`'s first line (`description` = the whole `doc` when it has more); `tags` = the id's first dotted segment |
-| `http.in` `path`/`query`/`header` members | `parameters` (name, `in`, `schema`; `required` from the effective input's `required`, a path parameter always required); an idempotent operation gains the `Idempotency-Key` header parameter (required under `"required"`) |
+| `http.in` `path`/`query`/`header` members | `parameters` (name, `in`, `schema`, or `content.application/json.schema` for JSON query members; `required` from the effective input's `required`, a path parameter always required); an idempotent operation gains the `Idempotency-Key` header parameter (required under `"required"`) |
 | body members | `requestBody`: the object of the body-located members (their `required` intersection, the input's `additionalProperties`); the whole input schema when every member is body-located; the member's own schema under `http.body`; `content[<http.media>]` |
 | `output`, `http.status` | `responses[<status>]` with the output schema; no content on `204`; opaque → `content[<media>]: { type: "string", format: "binary" }` |
 | declared `errors` | one response per status: the D7 wire-error schema (`code` **enum-pinned** to the codes of that status, `details` the declared schema when present) |
@@ -2561,3 +2601,40 @@ a body that ends without an `end` event is then `onEnd({ reason:
 as the HTTP client does and then does nothing with it: a channel has no
 network loss to reconnect from (a closed channel is `JC2074`, final),
 and one options object serves both clients.
+
+## Durable business commands
+
+`createCommand(operation, options)` from `@jarenjs/contract/command` composes
+business settlement with the existing neutral input/output/error pipeline.
+It accepts a JSON command with `policy.idempotency: "none"`, an injected
+`repository.execute(identity, work, context)`, `identity(input, context)`,
+`authorize(input, context)` and `handler(input, context)`. The identity declares
+tenant, environment, aggregate, operation, command key, hash version and payload
+hash. The host is responsible for a collision-resistant hash over every field
+that affects the command; canonical JSON itself is a lossless alternative.
+
+The handler receives the repository transaction as `ctx.host`. Expected entity
+revisions, domain writes, receipt writes and `ctx.host.jobs.enqueue` belong to
+that transaction. The neutral pipeline validates the handler's result before
+settlement. Any invalid output/error, failed receipt write or failed commit
+rolls back the transaction. Only failure codes explicitly listed in
+`commitFailures` may commit observations; ordinary declared failures roll back.
+The optional `references(outcome, context)` preserves application audit IDs.
+
+Use the same `command.handler` in HTTP/local/port handler tables and
+`command.execute(input, context)` in jobs. Direct execution reports `committed`,
+`replay`, `uncommitted` or `refused`; committed/replayed outcomes live in
+`receipt.outcome`. `historic: true` means the stored effect, never current entity
+state. A separate read operation observes current state. Every invocation checks
+current authorization before accessing a receipt. Refused execution exposes no
+historic result. Bindings render a refusal as a generic host fault unless the
+host supplies `refuse(reason, context)` returning a declared operation failure.
+
+Transport response caching is deliberately disallowed on a durable command:
+an HTTP ledger replay could bypass the command's current authorization hook.
+Existing HTTP TTL policies and local `capabilities.idempotency: false` retain
+their meanings. Business replay is supplied by the mapped receipt repository,
+not by the transport capability. Cancellation cannot undo an already committed
+receipt or establish that a remote effect did not happen.
+
+See [durable composition](DURABLE.md) for the crash matrix and public recipe.

package/docs/DURABLE.md

@@ -0,0 +1,66 @@
+# Durable business operations
+
+Commands, mapped receipts, existing jobs and workflow checkpoints compose through
+injected capabilities. Application models own business history, field mapping,
+authorization, revision policy and arithmetic. No second authoritative ledger or
+scheduler is created. These are local atomicity and recovery guarantees; external
+exactly-once delivery is not claimed.
+
+| Boundary | Durable observation | Automatic send/replay |
+|---|---|---|
+| Same command identity/hash on HTTP, local or job | Original validated outcome | Business effect replays without another mutation |
+| Different payload/hash version | Identity mismatch | Refused before mutation |
+| Current actor unauthorized | No historic disclosure | Refused before receipt read |
+| Output/error/receipt/commit failure | Entire local transaction rolls back | No business receipt exists |
+| Declared committed failure | Validated observation and stable references | Historic failure replays |
+| Lease/HTTP TTL expires | Business receipt remains | Receipt wins before work admission |
+| Before external sending intent | Prepared leg | A valid job fence may admit its first send |
+| Sending intent, lost response or lost settlement | Unresolved leg | No automatic resend |
+| One confirmed leg, one unresolved leg | Both per-leg observations retained | Confirmed leg skipped; unresolved leg awaits evidence |
+| Provider idempotency guarantee and explicit retry decision | Original key and finite attempt budget | Only the approved next attempt is admitted |
+| Probe absent without guarantee | Uncertainty retained | Refused as retry proof |
+| Lease takeover | New job fence | Stale begin/settlement refused |
+| Observer navigation | Run persists; observation detaches | Resume by durable cursor |
+| Explicit cancellation | Intent, worker drain, final observation | Resources release after final persistence |
+| Incompatible checkpoint | Stored history retained | Refused before reuse |
+| Reset/compaction | Receipt identity and audit references retained | Cannot authorize unresolved replay |
+
+Use installed public exports:
+
+```js
+import { createCommand } from '@jarenjs/contract/command';
+import { createDbReceipts, createDbEffectStore, createDbRunStore } from '@jarenjs/linq/db';
+import { createExternalEffects, createDomainRun } from '@jarenjs/flow';
+import { createProviderExecutor } from '@jarenjs/contract/provider';
+import { createRunPageHandler } from '@jarenjs/contract/app';
+import { createRunObservation } from '@jarenjs/app';
+
+// Application declarations: client, compiledContract, identity, authorize, adjust.
+const receipts = createDbReceipts(client, { receipts: 'history', leases: 'claims' });
+const command = createCommand(compiledContract.operations['item.adjust'], {
+  repository: receipts, identity, authorize, handler: adjust,
+});
+// HTTP/local use { 'item.adjust': command.handler }; jobs call command.execute.
+```
+
+`test/consumer/durable.js` exercises the installed composition with synthetic data.
+The receipt, external-effect and run tests include cross-process races, interrupted
+multi-leg execution, second-run no-op checks and current authorization. The measured
+cost probe is `npm run benchmark:durable`; its results below report overhead as
+well as resource bounds. Real provider guarantees, downstream cutover, native
+executables, PostgreSQL behavior and operator reconciliation acceptance require
+separate host/application qualification. Synthetic Node/Bun results cannot prove
+those claims. The retained reference fixtures remain unchanged.
+
+<!--fact:durable.measurements-->
+
+Measured on v24.19.0, linux/x64, AMD Ryzen 9 5900HX with Radeon Graphics.
+
+| Commands | Domain/outbox ms | Durable command ms | Receipt replay ms | Added cost ratio | Sends / unresolved resends | Second writes / revisions | Events | Heap / RSS MiB | Teardown ms / resources |
+|---:|---:|---:|---:|---:|---|---|---:|---|---|
+| 32 | 7.09 | 15.88 | 5.42 | 2.24x | 2 / 0 | 0 / 0 | 8 | 23.69 / 112.07 | 0.28 / 0 |
+| 128 | 14.73 | 33.22 | 13.35 | 2.26x | 2 / 0 | 0 / 0 | 8 | 41.05 / 123.25 | 0.13 / 0 |
+
+Synthetic local SQLite commands and interrupted multi-leg effects. Baseline executes the same domain/outbox work without a receipt; durable execution adds validation, authorization and immutable replay. Limits are fixed acceptance ceilings, not performance claims. Real providers, downstream acceptance, native executables, PostgreSQL and operator reconciliation are pending.
+
+<!--/fact-->

package/docs/PROVIDER-FORMAT.md

@@ -0,0 +1,157 @@
+# Provider descriptors, authority and complete ingestion
+
+`@jarenjs/contract/provider` exports `createProviderExecutor`, `compileProvider`
+and `withProviderRun`. The executor composes core scheduling with one injected
+HTTP attempt. The compiler describes JSON REST and explicitly declared GraphQL
+dialects. Credentials, destination rules and provider schemas remain host inputs.
+
+## Executor
+
+```js
+import { createProviderExecutor, compileProvider } from '@jarenjs/contract/provider';
+
+const executor = createProviderExecutor({ attempts: 3, overallMs: 30000,
+  attemptMs: 10000, maxBytes: 262144, concurrency: 4, maxQueue: 64 });
+const provider = compileProvider({
+  $provider: '0.1', id: 'inventory', apiVersion: '2026-01',
+  endpoint: 'https://inventory.example/items', protocol: 'rest',
+  method: 'GET', safety: 'safe-read',
+  query: { environment: '$.input.environment' },
+  response: { rows: '$.items', id: '$.id', cursor: '$.next', version: '$.version' },
+  pagination: { cursorParam: 'cursor', empty: 'complete' },
+  limits: { pages: 3, rows: 256, bytes: 262144 },
+});
+try {
+  const result = await provider.pull({ environment: 'test' }, { executor });
+  // Inspect result.state and the preserved result.observations before using it.
+} finally { await executor.close(); }
+```
+
+`execute(request, context)` requires an absolute HTTP(S) URL without embedded
+credentials and explicit safety: `safe-read`, `provider-idempotent`, or
+`single-send`. Provider-idempotent also requires `idempotencyKey`; the injected
+transport must bind that key using the provider's documented mechanism. The
+default transport refuses provider-idempotent requests with
+`idempotency-transport-required` because it has no dialect-specific key binding. An
+idempotency key does not qualify business reconciliation or durable receipts.
+Single-send transport/body uncertainty returns `unresolved` and never resends
+inside the executor. Supply the same core attempt budget in `context.budget`
+when an outer job or workflow can invoke the same request again.
+
+The optional injected `transport(request, {signal,attempt,maxAttempts})` returns
+a Fetch `Response`. It must make exactly one request (`maxAttempts:1`), disable
+SDK retries, and honor abort. The default uses `fetch` with redirects disabled.
+Custom redirect handling and idempotency binding remain transport obligations.
+JSON results preserve status, exact response text, consumed byte count, attempts
+and Retry-After, but never raw exceptions, credentials or response handles.
+`state` is `ok`, `failed`, `refused`, `unresolved` or `cancelled`.
+
+Defaults are three total attempts, an overall deadline of 30 seconds, ten seconds
+per attempt, 262144 response bytes across attempts and 262144 request-body bytes.
+`baseMs` defaults to 500 and `maxMs` to 8000. `now`, `random` and `sleep` are
+injectable. Core concurrency, queue, scope and spacing options are forwarded.
+The `account` request field combines with URL origin for fair rate scopes.
+`context.deadline` and `context.maxBytes` can tighten the executor's limits.
+Stream readers stop on byte exhaustion; late replies cannot become successes
+after abort/deadline. Close drains transport, body readers and retry waits.
+
+Retryable transport failures and HTTP 408/429/5xx consume the same total budget.
+`retryAfter` selects `http` (seconds/date), `milliseconds`, or `none`;
+`retryAfterHeader` names the header. A server delay which cannot fit the remaining
+deadline refuses with `deadline`. It is never shortened to the backoff cap.
+AI's declared clamp and the contract client's jitter remain their explicit
+[compatibility policies](../../core/docs/SCHEDULING.md).
+
+## Versioned descriptor
+
+`$provider:'0.1'`, `id`, `apiVersion`, `endpoint`, `protocol`, `method`, `safety`
+and `response` are required. API version is public data available to request
+selectors; the descriptor explicitly binds it in the endpoint, headers or query.
+Unknown fields are refused at compile time (`JC0021`). Malformed executor/run
+host options use `JC1012`.
+
+| Declaration | Contract |
+|---|---|
+| `headers` | Static public string headers. Authentication/cookie/key headers are refused; host transport owns credentials. |
+| `query`, `body` | Existing Query documents over `{input,cursor,apiVersion,partition,sourceVersion}`; query returns scalar parameters, body becomes canonical JSON. GET/HEAD bodies are refused. |
+| `graphql` | POST with `{query,variables?}`; variables is a Query document. `pagination.cursorVariable` receives the continuation. |
+| `response.rows`, `id` | Query selectors for an array and each source identity. String identities remain strings; numeric IDs must be safe integers. |
+| `response.cursor`, `hasMore` | Scalar continuation and optional explicit boolean. GraphQL terminal cursors may remain present when hasMore is false. |
+| `response.errors`, `cost`, `version` | Extracted protocol evidence. GraphQL errors default to `$.errors`; any partial errors make the pull incomplete. |
+| `response.transform` | `{kind:'query',expression}`, `{kind:'jslt',expression}`, or `{callback:name}`. Source raw/text/IDs remain beside transformed rows. |
+| `inputSchema`, `response.schema` | Optional schemas compiled by injected `compileSchema`; absence of that capability refuses the descriptor. |
+| `pagination` | `cursorParam`, `cursorVariable`, and explicit `empty:'complete'` or `'incomplete'`. Empty pages with continuation are always incomplete. |
+| `limits` | Positive finite `pages`, `rows`, `bytes`; defaults match the example. Budgets apply across one iterator, including failed request bytes. |
+| `capability` | `json` is supported. `upload`, `media`, `bulk`, `binary` refuse before dispatch. |
+
+Named selector callbacks are supplied in `compileProvider(doc,{callbacks})`.
+They receive cloned protocol data only. They are trusted host functions, not a
+JavaScript sandbox; the framework never supplies run resources to them.
+Schema, Query and JSLT each retain their existing compiler and semantics.
+
+`pages(input,context)` is an async iterator. Each `page` contains exact `text`,
+parsed `raw`, transformed `rows`, source `ids`, input `cursor`, `continuation`,
+`complete`, `version`, `errors`, `cost`, `reason`, `bytes` and `attempts`.
+The consumer's next pull admits the next request. A terminal `complete`,
+`incomplete` or `refused` record reports totals; `pull` collects that bounded
+sequence into `observations`. Repeated cursors, duplicate IDs, empty intermediate
+pages, partial errors, broken transforms and exhausted credits remain incomplete.
+Accepted partial pages remain inspectable. Bytes refused at a stream limit are
+discarded, and malformed response text is returned without claiming parsed rows.
+Raw text retains wire distinctions that JSON numbers alone cannot represent.
+
+## Private run authority
+
+`withProviderRun(evidence,host,work,options)` composes the existing
+identify/acquire/release hooks. Evidence is a closed JSON record of nonempty
+opaque strings: `runId`, `actor`, `environment`, `destination`, `revision`, `lease`.
+The host implements `identify(meta)`, `acquire(input,identity,enter)`,
+`current(evidence,privateHost,operation)` and `transport(request,context)`.
+`current` re-reads live authority and returns matching evidence or null.
+The framework compares every field before dispatch and publication, including
+after asynchronous refresh. All allowlists and membership rules stay in current.
+
+The callback receives a run with enumerable `evidence` only. Its private
+`execute`, `check`, `publish` and `signal` members cannot enter ordinary JSON
+state. Transport alone receives `context.host`; privileged clients are unique
+to concurrent runs. Host acquisition must serialize account switching where
+required. Shutdown stops admission and drains workers and callbacks before
+acquired and identity resources release, in that order. Released run callbacks
+cannot dispatch or publish again. The library suppresses raw host errors;
+applications must also keep secrets out of explicitly returned business data.
+
+Flow DAG/workflow `run(...,{resources})` passes resources as the task handler's
+third argument, separate from JSON input, checkpoint identity and trace data.
+Tasks with resources drain on abort before the workflow rejects. Compile the
+workflow once, then provide the particular run on each invocation. Authority
+is reacquired on resume; persisted references never restore live credentials.
+
+## Complete snapshots and qualification
+
+[`createIngestion`](../../flow/docs/WORKFLOW-FORMAT.md#complete-provider-ingestion)
+composes bounded pages with the existing workflow engine and an injected store.
+[`createDbIngestionStore`](../../linq/docs/DB-CLIENT.md#complete-ingestion-store)
+co-commits pages/checkpoints and publishes only complete requested partitions.
+Source snapshot or monotonic revision evidence is mandatory, including a version
+on every page. Identical published input is a no-op; application reconciliation
+owns manual provenance. No network operation holds a page transaction.
+
+Offline REST, partial GraphQL and archive-link transcripts and two independent
+bounded consumers are executable through `npm run test:packed` on Node and Bun.
+Node's abrupt-process recovery, rollback and zero-write tests run in the unit
+suite. Real provider authority/read-back, native external SDK behavior and
+downstream cutover remain separate qualifications. External writes await durable
+receipt/reconciliation capability; streaming DAG inputs are not required here.
+
+<!--fact:providers.measurements-->
+
+Measured on v24.19.0, linux/x64, AMD Ryzen 9 5900HX with Radeon Graphics.
+
+| Consumer | Rows | Requests / budget | Response bytes / budget | Retained reader ms | Native ingestion ms | Second writes / revisions | Teardown ms / remaining resources | Sampled heap / RSS MiB |
+|---|---:|---|---|---:|---:|---|---|---|
+| catalog | 256 | 3 / 3 | 66426 / 262144 | 0.96 | 64.45 | 0 / 0 | 0.27 / 0 | 35.69 / 116.45 |
+| archive-stock | 512 | 6 / 6 | 135886 / 524288 | 1.31 | 79.46 | 0 / 0 | 0.11 / 0 | 42.55 / 173.56 |
+
+Offline synthetic Node SQLite ingestion. The retained reader only extracts recorded transcripts; native timings include opening storage, descriptor execution, private authority checks, page/checkpoint commits, publication and zero-write replay. Their timings describe different work. No real provider latency, credentials, external write reconciliation or production cutover is qualified.
+
+<!--/fact-->

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/contract",
   "private": false,
-  "version": "0.73.0",
+  "version": "0.83.2",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -59,7 +59,15 @@
       "default": "./src/project/index.js"
     },
     "./schemas/*": "./schemas/*",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./provider": {
+      "types": "./dist/types/provider/index.d.ts",
+      "default": "./src/provider/index.js"
+    },
+    "./command": {
+      "types": "./dist/types/command.d.ts",
+      "default": "./src/command.js"
+    }
   },
   "files": [
     "dist/types/",
@@ -102,9 +110,9 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.73.0",
-    "@jarenjs/json": "^0.73.0",
-    "@jarenjs/validate": "^0.73.0",
-    "@jarenjs/emit": "^0.73.0"
+    "@jarenjs/core": "^0.83.2",
+    "@jarenjs/json": "^0.83.2",
+    "@jarenjs/validate": "^0.83.2",
+    "@jarenjs/emit": "^0.83.2"
   }
 }

package/src/app/binding.js

@@ -34,6 +34,9 @@ import { ContractHostError } from '../errors.js';
  * @property {string} [statePath] - where the slice lives in app state, as a
  *   chain of identifier-safe segments; default `/contract`
  * @property {readonly string[]} [ops] - the operations the app uses; default every operation
+ * @property {Record<string, { reconnect: { max: number } }>} [subs] - per
+ *   subscribe-operation options. Reconnect is opt-in; the slot stays live
+ *   while the HTTP client resumes, and reports error after exhaustion.
  */
 
 /**
@@ -145,8 +148,9 @@ function replace(path, value) {
  * @param {Record<string, any>} actions
  * @param {any[]} subs
  * @param {Record<string, any>} properties
+ * @param {{ max: number } | undefined} reconnect
  */
-function appendSubscription(contract, op, id, namespace, slot, slotQuery, idQuery, nextId, actions, subs, properties) {
+function appendSubscription(contract, op, id, namespace, slot, slotQuery, idQuery, nextId, actions, subs, properties, reconnect) {
   const idGuard = { $eq: ['$payload.id', idQuery] };
 
   setObjectMember(actions, `${namespace}${id}/start`, {
@@ -224,6 +228,7 @@ function appendSubscription(contract, op, id, namespace, slot, slotQuery, idQuer
       snapshot: `${namespace}${id}/snapshot`,
       patch: `${namespace}${id}/patch`,
       error: `${namespace}${id}/error`,
+      ...(reconnect === undefined ? {} : { reconnect: { $const: { max: reconnect.max } } }),
     },
   });
 
@@ -302,6 +307,21 @@ export function contractAppBinding(contract, options = {}) {
   }
   const ops = options.ops === undefined ? contract.ids : options.ops;
   if (!Array.isArray(ops)) throw host('ops must be an array of operation ids');
+  const streamOptions = options.subs === undefined ? {} : options.subs;
+  if (streamOptions === null || typeof streamOptions !== 'object' || Array.isArray(streamOptions))
+    throw host('subs must be an operation-options object');
+  for (const id of Object.keys(streamOptions)) {
+    if (!ops.includes(id) || !Object.hasOwn(contract.operations, id) || contract.operations[id].kind !== 'subscribe')
+      throw host(`subs names '${id}', which is not a selected subscribe operation`);
+    const entry = streamOptions[id];
+    const reconnect = entry?.reconnect;
+    if (entry === null || typeof entry !== 'object' || Array.isArray(entry)
+      || Object.keys(entry).some((key) => key !== 'reconnect')
+      || reconnect === null || typeof reconnect !== 'object' || Array.isArray(reconnect)
+      || Object.keys(reconnect).some((key) => key !== 'max')
+      || !Number.isSafeInteger(reconnect.max) || reconnect.max < 0)
+      throw host(`subs['${id}'] must be { reconnect: { max } } with a non-negative safe integer max`);
+  }
   const queryRoot = '$' + statePath.replaceAll('/', '.');
 
   /** @type {Record<string, TaskSlot | StreamSlot>} */
@@ -328,7 +348,8 @@ export function contractAppBinding(contract, options = {}) {
     const done = `${namespace}${id}/done`;
 
     if (op.kind === 'subscribe') {
-      appendSubscription(contract, op, id, namespace, slot, slotQuery, idQuery, nextId, actions, subs, properties);
+      appendSubscription(contract, op, id, namespace, slot, slotQuery, idQuery, nextId, actions, subs, properties,
+        Object.hasOwn(streamOptions, id) ? streamOptions[id].reconnect : undefined);
       setObjectMember(slice, id, { id: 0, status: 'idle', kind: null, input: null, value: null, error: null, meta: null, seq: 0 });
       required.push(id);
       continue;

package/src/app/index.js

@@ -12,7 +12,7 @@
 
 export { contractAppBinding } from './binding.js';
 export { createContractEffect } from './effect.js';
-export { createContractSubscription } from './subscription.js';
+export { createContractSubscription, createRunPageHandler } from './subscription.js';
 
 /**
  * @typedef {import('./binding.js').ContractAppBinding} ContractAppBinding

package/src/app/subscription.js

@@ -21,6 +21,8 @@
  * slot must say so, so a view can offer a reconnect (a new `start`).
  */
 
+import { deepFreeze } from '@jarenjs/core/object';
+import { canonicalizeJson } from '@jarenjs/json/canonical';
 import { compileJSONPatch } from '@jarenjs/json/patch';
 
 import { ContractHostError } from '../errors.js';
@@ -48,7 +50,7 @@ import { PORT_LOCAL_ERRORS } from '../pipeline.js';
 /**
  * The props of one generated subs entry: the operation, the slot id and
  * input resolved from state, and the action names to dispatch.
- * @typedef {{ op: string, id: number, input: unknown, snapshot: string, patch: string, error: string }} StreamProps
+ * @typedef {{ op: string, id: number, input: unknown, snapshot: string, patch: string, error: string, reconnect?: { max: number } }} StreamProps
  */
 
 /**
@@ -86,12 +88,18 @@ export function createContractSubscription(client, options = {}) {
     const { op, id } = p;
     /** @type {unknown} */
     let doc = null;
+    let seq = -1;
+    let stopped = false;
     const sub = client.subscribe(op, p.input === undefined ? null : p.input, {
+      ...(p.reconnect === undefined ? {} : { reconnect: p.reconnect }),
       onSnapshot: (/** @type {unknown} */ value, /** @type {{ seq: number }} */ info) => {
+        if (stopped) return;
         doc = value;
+        seq = info.seq;
         dispatch(p.snapshot, { id, value, seq: info.seq });
       },
       onPatch: (/** @type {{ patch: any[], seq: number }} */ emission) => {
+        if (stopped || emission.seq <= seq) return;
         try {
           doc = compileJSONPatch(/** @type {any} */ (emission.patch))(doc);
         }
@@ -107,10 +115,12 @@ export function createContractSubscription(client, options = {}) {
           });
           return;
         }
+        seq = emission.seq;
         dispatch(p.patch, { id, value: doc, seq: emission.seq });
       },
-      onError: (/** @type {Outcome} */ outcome) => dispatch(p.error, { id, outcome }),
+      onError: (/** @type {Outcome} */ outcome) => { if (!stopped) dispatch(p.error, { id, outcome }); },
       onEnd: () => {
+        if (stopped) return;
         // the server ended the stream: the slot must say the channel is
         // gone, so a view can offer a reconnect (a fresh start)
         dispatch(p.error, {
@@ -121,10 +131,29 @@ export function createContractSubscription(client, options = {}) {
         });
       },
     });
-    return () => sub.stop();
+    return () => { stopped = true; sub.stop(); };
   };
 }
 
 // re-exported so a host settling its own outcomes beside the handler
 // needs no second import path
 export { CLIENT_ERRORS };
+
+/**
+ * Authorize each bounded run-page read before touching durable history. Register
+ * as an ordinary read handler; callers may poll or resume from their last cursor.
+ * @param {{ page: (id: string, options: any) => any, authorize: (input: any, context: any) => any, maxPage?: number }} options
+ */
+export function createRunPageHandler(options) {
+  const maxPage = options?.maxPage ?? 128;
+  if (typeof options?.page !== 'function' || typeof options.authorize !== 'function' || !Number.isSafeInteger(maxPage) || maxPage < 1)
+    throw new ContractHostError('JC1008', 'run pages need page/authorize capabilities and a finite limit');
+  return async (input, context) => {
+    input = deepFreeze(JSON.parse(canonicalizeJson(input)));
+    if (await options.authorize(input, context) !== true) throw new ContractHostError('JC1008', 'run observation refused');
+    if (typeof input?.id !== 'string' || !input.id || !Number.isSafeInteger(input.after) || input.after < 0
+      || !Number.isSafeInteger(input.limit) || input.limit < 1 || input.limit > maxPage)
+      throw new ContractHostError('JC1008', 'run observation needs id, revision cursor and bounded limit');
+    return options.page(input.id, { after: input.after, limit: input.limit });
+  };
+}