@jarenjs/contract 0.75.0 → 0.83.3

package/README.md

@@ -1,5 +1,7 @@
 # @jarenjs/contract
 
+Providers and permanent commands compose with injected transport, authority and receipt repositories. The [adoption evidence ledger](../../docs/ADOPTION-EVIDENCE.md) separates synthetic qualification from actual provider guarantees; unknown single-send outcomes require explicit reconciliation.
+
 Operation contracts for the Jaren suite. A **`$contract` document** — the
 sibling of `$model`, `$fsm` and `jaren-app` — declares the operations two
 Jaren ends may exchange: JSON in, JSON out, each with a *kind* (`read` or
@@ -734,6 +736,8 @@ Every subpath a consumer can import, derived from the manifest by
 | `@jarenjs/contract/schemas/jaren-contract.draft-07.schema.json` | schema | — |
 | `@jarenjs/contract/schemas/jaren-contract.schema.json` | schema | — |
 | `@jarenjs/contract/package.json` | metadata | — |
+| `@jarenjs/contract/provider` | JavaScript | declared |
+| `@jarenjs/contract/command` | JavaScript | declared |
 <!--/fact-->
 
 Author JSON template catalogs and MessageSpec references with the
@@ -771,3 +775,8 @@ and the producer's unwritten chunk separately from bytes already accepted
 by TCP. The in-process Fetch leg can measure produced-minus-consumed
 bytes directly. Complete-byte hashes, cursor pulls and cancellation
 finalizers remain part of the same end-to-end test.
+
+`@jarenjs/contract/provider` supplies bounded provider execution, compiled JSON
+REST/GraphQL dialects and private run authority. Partial observations retain
+wire text and never become complete snapshots. See
+[provider descriptors and ingestion](docs/PROVIDER-FORMAT.md).

package/dist/types/app/index.d.ts

@@ -10,7 +10,7 @@
  */
 export { contractAppBinding } from './binding.js';
 export { createContractEffect } from './effect.js';
-export { createContractSubscription } from './subscription.js';
+export { createContractSubscription, createRunPageHandler } from './subscription.js';
 export type ContractAppBinding = import('./binding.js').ContractAppBinding;
 export type ContractAppBindingOptions = import('./binding.js').ContractAppBindingOptions;
 export type TaskSlot = import('./binding.js').TaskSlot;

package/dist/types/app/subscription.d.ts

@@ -83,3 +83,13 @@ export type StreamProps = {
  */
 export declare function createContractSubscription(client: StreamClientLike, options?: ContractSubscriptionOptions): (props: StreamProps, dispatch: (name: string, payload?: any) => void) => (() => void);
 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 declare function createRunPageHandler(options: {
+    page: (id: string, options: any) => any;
+    authorize: (input: any, context: any) => any;
+    maxPage?: number;
+}): (input: any, context: any) => Promise<any>;

package/dist/types/command.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Compile once around the existing neutral operation pipeline. Identity and
+ * current authorization are application policy, never inferred from a receipt.
+ * Handlers receive the repository's transaction as ctx.host; current-state reads
+ * belong to a separate read operation. Transport TTL policy remains independent.
+ * @param {import('./compile.js').CompiledOperation} operation
+ * @param {{ repository: { execute: Function }, identity: (input: any, context: any) => any,
+ * authorize: (input: any, context: any) => any, handler: (input: any, context: any) => any,
+ * commitFailures?: string[], references?: (result: any, context: any) => any[],
+ * refuse?: (reason: string, context: any) => any }} options
+ */
+export declare function createCommand(operation: import('./compile.js').CompiledOperation, options: {
+    repository: {
+        execute: Function;
+    };
+    identity: (input: any, context: any) => any;
+    authorize: (input: any, context: any) => any;
+    handler: (input: any, context: any) => any;
+    commitFailures?: string[];
+    references?: (result: any, context: any) => any[];
+    refuse?: (reason: string, context: any) => any;
+}): Readonly<{
+    execute: (input: any, context?: any) => Promise<any>;
+    /** A deliberate carrier wrapper around the one settlement implementation.
+     * @param {any} input @param {any} context */
+    handler(input: any, context: any): Promise<any>;
+}>;

package/dist/types/errors.d.ts

@@ -49,6 +49,7 @@ export declare const CONTRACT_CODES: Readonly<{
     JC0018: "a subscribe operation declares a policy.task other than switch — a subscription slot is replaced, never queued";
     JC0019: "a subscribe operation is bound to a method other than GET — a stream is fetched, not sent";
     JC0020: "a subscribe operation declares a policy.idempotency other than none — a subscription registers, it does not commit";
+    JC0021: "a provider protocol descriptor is malformed or names an undeclared transform capability";
     JC0060: "the OpenAPI projection met a schema keyword it cannot map honestly: a boolean required (draft-04 style) or a same-document $ref that lands outside $defs (both dropped and reported under lenient), or a components member inside a schema";
     JC0061: "the public projection is not canonicalizable, so no revision exists — a string with an unpaired surrogate, say; docPath points at the offending value inside the projection";
     JC1001: "serveHttp, serveLocal or servePort: handlers is not an object, a key names no operation of the contract, a value is not a function, or an option (a channel without postMessage, say) is malformed";
@@ -62,6 +63,8 @@ export declare const CONTRACT_CODES: Readonly<{
     JC1009: "encodeSseEvent (the stream wire): an event, id or data string the SSE frame cannot carry — a bare carriage return inside data, a line terminator inside event or id";
     JC1010: "client.subscribe was asked for an operation that is not a subscribe operation (invoke carries reads and commands; subscribe carries streams)";
     JC1011: "a ledger commit or fail named a ref that settles no started record: the key expired, was reclaimed under a newer generation, or was settled already — the settlement is refused; the binding reports it to onError and the response still goes out";
+    JC1012: "a provider executor, descriptor host or run capability is malformed";
+    JC1013: "a durable command settlement capability is malformed";
     JC2001: "no operation matches the request method and path (404)";
     JC2002: "the path shape is served under other methods (405, Allow lists them)";
     JC2003: "the request body exceeds policy.limits.maxBodyBytes, by content-length or by read length (413)";
@@ -99,6 +102,7 @@ export declare const CONTRACT_CODES: Readonly<{
     JC2095: "a requested resume was refused — informational, carried as resumed:false in the fresh snapshot's event data, never an outcome";
     JC2096: "the stream's bounded queue would overflow — the consumer reads slower than the source emits, or a replay page outran it (kind network, retryable; the stream ends with an error event carrying this code and the carrier tears the connection down)";
     JC2097: "the client's reconnect budget is exhausted: every attempt after a network loss failed the same way (kind network, not retryable; details carry the attempts made and the last network code, client-side)";
+    JC2110: "a durable command was refused or failed validation";
 }>;
 /**
  * A defect in the contract document itself, raised while

package/dist/types/provider/compile.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Compile selectors/transforms once using the existing Query/JSLT engines.
+ * Named callbacks receive cloned protocol data only, never the run host.
+ * These are trusted host functions, not a sandbox for arbitrary JavaScript.
+ * @param {any} document
+ * @param {{ callbacks?: Record<string, (value: any) => any>, compileSchema?: (schema: any) => (value: any) => boolean }} [options]
+ */
+export declare function compileProvider(document: any, options?: {
+    callbacks?: Record<string, (value: any) => any>;
+    compileSchema?: (schema: any) => (value: any) => boolean;
+}): Readonly<{
+    document: any;
+    pages: (input: any, context: any) => AsyncGenerator<{
+        state: any;
+        reason: any;
+        pages: number;
+        rows: number;
+        bytes: number;
+        attempts: number;
+        cursor: any;
+    } | {
+        state: any;
+        reason: any;
+        pages: number;
+        rows: number;
+        bytes: number;
+        attempts: number;
+        cursor: any;
+        response: any;
+        raw?: undefined;
+        text?: undefined;
+        ids?: undefined;
+        continuation?: undefined;
+        complete?: undefined;
+        errors?: undefined;
+        cost?: undefined;
+        version?: undefined;
+    } | {
+        state: any;
+        reason: any;
+        pages: number;
+        rows: number;
+        bytes: number;
+        attempts: number;
+        cursor: any;
+        text: any;
+        raw?: undefined;
+        ids?: undefined;
+        continuation?: undefined;
+        complete?: undefined;
+        errors?: undefined;
+        cost?: undefined;
+        version?: undefined;
+    } | {
+        state: string;
+        raw: any;
+        text: any;
+        rows: any[];
+        ids: any[];
+        cursor: any;
+        continuation: any;
+        complete: boolean;
+        errors: any;
+        cost: any;
+        version: any;
+        reason: string | null;
+        bytes: any;
+        attempts: any;
+    }, void, unknown>;
+    /** Collect a bounded pull; streaming consumers should iterate pages instead.
+     * @param {any} input @param {any} context @returns {Promise<any>} */
+    pull(input: any, context: any): Promise<any>;
+}>;

package/dist/types/provider/execute.d.ts

@@ -0,0 +1,104 @@
+import { createAttemptBudget } from '@jarenjs/core/retry';
+import { ContractHostError } from '../errors.js';
+/** @param {string} reason @returns {ContractHostError} */
+export declare const providerHostError: (reason: string) => ContractHostError;
+export type ProviderRequest = {
+    url: string;
+    method?: string;
+    /**
+     * - public headers only; credentials belong to host transport
+     */
+    headers?: Record<string, string>;
+    body?: string;
+    safety: 'safe-read' | 'provider-idempotent' | 'single-send';
+    /**
+     * - required evidence for provider-idempotent
+     */
+    idempotencyKey?: string;
+    /**
+     * - opaque scheduler scope, never credentials
+     */
+    account?: string;
+};
+export type ProviderExecutorOptions = {
+    transport?: (request: ProviderRequest, context: {
+        signal: AbortSignal;
+        attempt: number;
+        maxAttempts: 1;
+    }) => Promise<Response>;
+    attempts?: number;
+    overallMs?: number;
+    attemptMs?: number;
+    /**
+     * - response bytes across all attempts
+     */
+    maxBytes?: number;
+    maxRequestBytes?: number;
+    baseMs?: number;
+    maxMs?: number;
+    retryAfter?: 'http' | 'milliseconds' | 'none';
+    retryAfterHeader?: string;
+    concurrency?: number;
+    maxQueue?: number;
+    maxScopes?: number;
+    spacingMs?: number;
+    now?: () => number;
+    random?: () => number;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+};
+/**
+ * @typedef {Object} ProviderRequest
+ * @property {string} url
+ * @property {string} [method]
+ * @property {Record<string, string>} [headers] - public headers only; credentials belong to host transport
+ * @property {string} [body]
+ * @property {'safe-read' | 'provider-idempotent' | 'single-send'} safety
+ * @property {string} [idempotencyKey] - required evidence for provider-idempotent
+ * @property {string} [account] - opaque scheduler scope, never credentials
+ */
+/**
+ * @typedef {Object} ProviderExecutorOptions
+ * @property {(request: ProviderRequest, context: { signal: AbortSignal, attempt: number, maxAttempts: 1 }) => Promise<Response>} [transport]
+ * @property {number} [attempts]
+ * @property {number} [overallMs]
+ * @property {number} [attemptMs]
+ * @property {number} [maxBytes] - response bytes across all attempts
+ * @property {number} [maxRequestBytes]
+ * @property {number} [baseMs]
+ * @property {number} [maxMs]
+ * @property {'http' | 'milliseconds' | 'none'} [retryAfter]
+ * @property {string} [retryAfterHeader]
+ * @property {number} [concurrency]
+ * @property {number} [maxQueue]
+ * @property {number} [maxScopes]
+ * @property {number} [spacingMs]
+ * @property {() => number} [now]
+ * @property {() => number} [random]
+ * @property {(ms: number, signal?: AbortSignal) => Promise<void>} [sleep]
+ */
+/**
+ * Injected transports must issue exactly one request and honor the supplied
+ * signal; SDK retry loops must be disabled. Shutdown awaits transport and body
+ * settlement even when a transport ignores its signal. JSON outcomes never
+ * contain exceptions, request headers, controllers or live response handles.
+ * @param {ProviderExecutorOptions} [options]
+ */
+export declare function createProviderExecutor(options?: ProviderExecutorOptions): Readonly<{
+    /** @param {ProviderRequest} request
+     * @param {{ signal?: AbortSignal, deadline?: number, maxBytes?: number, budget?: ReturnType<typeof createAttemptBudget>, beforeDispatch?: (request: ProviderRequest) => boolean | Promise<boolean> }} [context]
+     * @returns {Promise<any>} */
+    execute(request: ProviderRequest, context?: {
+        signal?: AbortSignal;
+        deadline?: number;
+        maxBytes?: number;
+        budget?: ReturnType<typeof createAttemptBudget>;
+        beforeDispatch?: (request: ProviderRequest) => boolean | Promise<boolean>;
+    }): Promise<any>;
+    /** Stop new work and drain requests, body readers and retry waits. */
+    close(): Promise<void>;
+    stats: () => {
+        active: number;
+        queued: number;
+        closed: boolean;
+    };
+}>;

package/dist/types/provider/index.d.ts

@@ -0,0 +1,4 @@
+/** Bounded provider protocols with host-injected transport and authority. */
+export { createProviderExecutor } from './execute.js';
+export { compileProvider } from './compile.js';
+export { withProviderRun } from './run.js';

package/dist/types/provider/run.d.ts

@@ -0,0 +1,33 @@
+export type ProviderAuthority = {
+    runId: string;
+    actor: string;
+    environment: string;
+    destination: string;
+    revision: string;
+    lease: string;
+};
+/**
+ * @typedef {{ runId: string, actor: string, environment: string,
+ * destination: string, revision: string, lease: string }} ProviderAuthority
+ */
+/**
+ * Run a callback with private, isolated transport resources. current() must
+ * re-read live authority and return the matching evidence, or null to revoke.
+ * The host owns membership, destination resolution, OAuth and account locks.
+ * Only opaque evidence and JSON callback results can leave this lifetime.
+ * @param {ProviderAuthority} authority
+ * @param {{ identify: Function, acquire: Function,
+ * current: (evidence: ProviderAuthority, host: any, operation: any) => ProviderAuthority | null | Promise<ProviderAuthority | null>,
+ * transport: (request: import('./execute.js').ProviderRequest, context: any) => Promise<Response> }} host
+ * @param {(run: any) => any} work
+ * @param {import('./execute.js').ProviderExecutorOptions & { signal?: AbortSignal }} [options]
+ * @returns {Promise<any>}
+ */
+export declare function withProviderRun(authority: ProviderAuthority, host: {
+    identify: Function;
+    acquire: Function;
+    current: (evidence: ProviderAuthority, host: any, operation: any) => ProviderAuthority | null | Promise<ProviderAuthority | null>;
+    transport: (request: import('./execute.js').ProviderRequest, context: any) => Promise<Response>;
+}, work: (run: any) => any, options?: import('./execute.js').ProviderExecutorOptions & {
+    signal?: AbortSignal;
+}): Promise<any>;

package/docs/CONTRACT-FORMAT.md

@@ -432,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-
@@ -792,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
 
@@ -2597,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.75.0",
+  "version": "0.83.3",
   "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.75.0",
-    "@jarenjs/json": "^0.75.0",
-    "@jarenjs/validate": "^0.75.0",
-    "@jarenjs/emit": "^0.75.0"
+    "@jarenjs/core": "^0.83.3",
+    "@jarenjs/json": "^0.83.3",
+    "@jarenjs/validate": "^0.83.3",
+    "@jarenjs/emit": "^0.83.3"
   }
 }