@jarenjs/contract 0.73.0 → 0.83.2

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,8 +736,47 @@ 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
 [messages pen](../linq/docs/MESSAGES-PEN.md); existing locale render functions
 retain their pluralization and formatting behavior.
+
+## Structured query inputs and app reconnect
+
+Object- and array-typed query members use one JSON-encoded parameter,
+including empty arrays, nulls and nested values. Scalar strings stay
+literal; parsed JSON is validated without coercion. The client, URL
+builder, server dispatcher and OpenAPI projection share this codec.
+Malformed or repeated JSON members are `JC2012`. Handwritten callers
+must migrate repeated array keys (`tag=a&tag=b`) to one encoded JSON array;
+deploy matching client/server versions and revise the contract's `version`
+for revision negotiation. See [the wire rules](docs/CONTRACT-FORMAT.md#4-the-http-binding-and-member-locations).
+
+Opt into HTTP subscription recovery per operation:
+
+```javascript
+const binding = contractAppBinding(contract, {
+  subs: { 'board.feed': { reconnect: { max: 2 } } },
+});
+```
+
+The generated subscription forwards the option to `client.subscribe`.
+The slot stays live with its id and last value while reconnecting; replay
+continues from the last delivered sequence. Exhaustion surfaces `JC2097`.
+Stop, reset and app destruction stop recovery. Without the option,
+network loss is surfaced immediately; an explicit server end remains
+terminal. Port and local channel lifecycles are unchanged.
+
+The fixed-heap host-seam test measures the Node response's writable queue
+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/binding.d.ts

@@ -33,6 +33,16 @@ export type ContractAppBindingOptions = {
      * - the operations the app uses; default every operation
      */
     ops?: readonly string[];
+    /**
+     * - per
+     * subscribe-operation options. Reconnect is opt-in; the slot stays live
+     * while the HTTP client resumes, and reports error after exhaustion.
+     */
+    subs?: Record<string, {
+        reconnect: {
+            max: number;
+        };
+    }>;
 };
 export type TaskSlot = {
     id: number;

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

@@ -42,6 +42,9 @@ export type StreamProps = {
     snapshot: string;
     patch: string;
     error: string;
+    reconnect?: {
+        max: number;
+    };
 };
 /**
  * @typedef {import('../compile.js').Contract} Contract
@@ -60,7 +63,7 @@ export type StreamProps = {
 /**
  * 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
  */
 /**
  * Make the `contract-stream` subscription handler of an app over a
@@ -80,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/client/http.d.ts

@@ -262,7 +262,7 @@ export type ClientRoute = {
     method: string;
     segments: readonly import('../path.js').PathSegment[];
     queryMembers: readonly string[];
-    queryRepeated: ReadonlySet<string>;
+    queryJson: ReadonlySet<string>;
     headerMembers: readonly string[];
     headerNames: readonly string[];
     /**

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/compile.d.ts

@@ -38,6 +38,11 @@ export type InputTransport = {
         header: readonly string[];
         repeated: readonly string[];
     };
+    /**
+     * - query members with a declared
+     * object/array type, encoded as one JSON value (including nullable unions)
+     */
+    queryJson: readonly string[];
     schemas: Readonly<Record<string, any>>;
     required: readonly string[];
 };

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/http/dispatch.d.ts

@@ -102,9 +102,9 @@ export type Route = {
     pathMembers: readonly string[];
     queryMembers: ReadonlySet<string>;
     /**
-     * - array-typed query members
+     * - JSON-encoded query members
      */
-    repeated: ReadonlySet<string>;
+    queryJson: ReadonlySet<string>;
     /**
      * - member names
      */

package/dist/types/http/wire.d.ts

@@ -292,18 +292,19 @@ export declare function formatEntityTag(tag: string, strong: boolean): string;
 /**
  * Decode a query string into the declared members of an input object:
  * only declared names are set (an undeclared key is never merged, so no
- * request can smuggle a member); a `repeated` member collects every
- * occurrence into an array, every other member is last-wins; a `+` is a
+ * request can smuggle a member); JSON members decode exactly one value,
+ * scalar members are last-wins; a `+` is a
  * space and escapes decode as `application/x-www-form-urlencoded`
  * (`URLSearchParams`). Returns `false` when the query is not decodable
- * (a malformed percent-escape or invalid UTF-8) — the `JC2012` case.
+ * (malformed percent-escape, UTF-8 or JSON, or a repeated JSON member)
+ * — the `JC2012` case.
  * @param {string} query - the part after `?`, possibly empty
  * @param {ReadonlySet<string>} declared - the query member names
- * @param {ReadonlySet<string>} repeated - the array-typed ones
  * @param {Record<string, unknown>} out - the input object under assembly
+ * @param {ReadonlySet<string>} json - schema-directed JSON members
  * @returns {boolean} false when not decodable
  */
-export declare function decodeQuery(query: string, declared: ReadonlySet<string>, repeated: ReadonlySet<string>, out: Record<string, unknown>): boolean;
+export declare function decodeQuery(query: string, declared: ReadonlySet<string>, out: Record<string, unknown>, json: ReadonlySet<string>): boolean;
 /**
  * The verdict of a compiled validator under either contract: the
  * default `{ valid, errors }` or a host-injected boolean validator.

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>;