@jarenjs/contract 0.43.1

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

@@ -0,0 +1,334 @@
+/**
+ * @file The wire shapes of the HTTP server binding: the request-time
+ * error taxonomy as data (code → status, msgid, retryable), the error
+ * body every non-2xx JSON response carries, header reading, media
+ * matching, entity-tag comparison and the query decoder. Nothing here
+ * calls a handler or touches a ledger; `dispatch.js` composes these.
+ *
+ * Every response header name is lowercase; every error response carries
+ * `x-jaren-trace` (the server trace, `requestId` in the body) and
+ * `cache-control: no-store`. A message is rendered from the msgid
+ * through the catalog and never interpolates a request value — the
+ * parameters are the operation id, a declared limit, a media type, a
+ * method list, a declared header name or a declared error code
+ * (docs/CONTRACT-FORMAT.md §7).
+ */
+export type HttpRequest = {
+    method: string;
+    url: string;
+    headers: Readonly<Record<string, string | readonly string[]>>;
+    body: string | Uint8Array | null;
+    signal?: AbortSignal | null;
+};
+export type HttpResponse = {
+    status: number;
+    headers: Readonly<Record<string, string>>;
+    body: string | Uint8Array | null;
+    stream?: (sink: {
+        write: (chunk: string) => void;
+        end: () => void;
+    }) => (() => void);
+};
+export type WireErrorBody = {
+    /**
+     * - a `JC2xxx` code, or the declared error code
+     */
+    code: string;
+    message: string;
+    /**
+     * - the server trace (`x-jaren-trace`)
+     */
+    requestId: string;
+    details?: unknown;
+    retryable: boolean;
+};
+export type WireErrorRow = {
+    status: number;
+    msgid: string;
+    retryable: boolean;
+};
+/**
+ * A request as the binding sees it — what an adapter builds and what a
+ * test hands to `dispatch` directly. `url` is origin-less: the path plus
+ * an optional `?query`; header names are lowercase; a header value is a
+ * string, or an array of strings when the adapter can see repeated field
+ * lines; `body` is the bytes/text as received (`null` for none);
+ * `signal` is the request's abort signal when the host has one.
+ * @typedef {Object} HttpRequest
+ * @property {string} method
+ * @property {string} url
+ * @property {Readonly<Record<string, string | readonly string[]>>} headers
+ * @property {string | Uint8Array | null} body
+ * @property {AbortSignal | null} [signal]
+ */
+/**
+ * A response as the binding answers it: a status, lowercase header names,
+ * and a body that is a string (JSON text), bytes (an opaque operation) or
+ * `null` (HEAD, 204, 304). A streaming response (a subscribe operation
+ * under `accept: text/event-stream`) carries `body: null` plus `stream`:
+ * the adapter writes the headers, then MUST call `stream` exactly once
+ * with its sink — the pump writes SSE text through `sink.write` and
+ * calls `sink.end()` when the stream terminates; the returned function
+ * stops the stream when the consumer cancels.
+ * @typedef {Object} HttpResponse
+ * @property {number} status
+ * @property {Readonly<Record<string, string>>} headers
+ * @property {string | Uint8Array | null} body
+ * @property {(sink: { write: (chunk: string) => void, end: () => void }) => (() => void)} [stream]
+ */
+/**
+ * The D7 error body of every non-2xx JSON response.
+ * @typedef {Object} WireErrorBody
+ * @property {string} code - a `JC2xxx` code, or the declared error code
+ * @property {string} message
+ * @property {string} requestId - the server trace (`x-jaren-trace`)
+ * @property {unknown} [details]
+ * @property {boolean} retryable
+ */
+/**
+ * The taxonomy row of one request-time code.
+ * @typedef {{ status: number, msgid: string, retryable: boolean }} WireErrorRow
+ */
+/**
+ * The request-time taxonomy as data: code → `{ status, msgid, retryable }`.
+ * The normative table is docs/CONTRACT-FORMAT.md §7; a test holds the
+ * two equal, and equal to `CONTRACT_CODES` and the English catalog. The
+ * client binding assembles outcomes from exactly these statuses.
+ */
+export declare const HTTP_ERRORS: Readonly<{
+    JC2001: Readonly<{
+        status: 404;
+        msgid: "contract/not-found";
+        retryable: false;
+    }>;
+    JC2002: Readonly<{
+        status: 405;
+        msgid: "contract/method-not-allowed";
+        retryable: false;
+    }>;
+    JC2003: Readonly<{
+        status: 413;
+        msgid: "contract/body-too-large";
+        retryable: false;
+    }>;
+    JC2004: Readonly<{
+        status: 415;
+        msgid: "contract/unsupported-media";
+        retryable: false;
+    }>;
+    JC2005: Readonly<{
+        status: 400;
+        msgid: "contract/malformed-json";
+        retryable: false;
+    }>;
+    JC2006: Readonly<{
+        status: 400;
+        msgid: "contract/invalid-input";
+        retryable: false;
+    }>;
+    JC2007: Readonly<{
+        status: 400;
+        msgid: "contract/idempotency-key-required";
+        retryable: false;
+    }>;
+    JC2008: Readonly<{
+        status: 500;
+        msgid: "contract/handler-failed";
+        retryable: false;
+    }>;
+    JC2009: Readonly<{
+        status: 409;
+        msgid: "contract/idempotency-conflict";
+        retryable: false;
+    }>;
+    JC2010: Readonly<{
+        status: 500;
+        msgid: "contract/invalid-output";
+        retryable: false;
+    }>;
+    JC2011: Readonly<{
+        status: 400;
+        msgid: "contract/malformed-path";
+        retryable: false;
+    }>;
+    JC2012: Readonly<{
+        status: 400;
+        msgid: "contract/malformed-query";
+        retryable: false;
+    }>;
+    JC2013: Readonly<{
+        status: 501;
+        msgid: "contract/not-implemented";
+        retryable: false;
+    }>;
+    JC2014: Readonly<{
+        status: 412;
+        msgid: "contract/precondition-failed";
+        retryable: false;
+    }>;
+    JC2015: Readonly<{
+        status: 400;
+        msgid: "contract/invalid-header";
+        retryable: false;
+    }>;
+}>;
+/** The msgid of a declared operation error that has no message of its own. */
+export declare const HANDLER_ERROR_MSGID = "contract/handler-error";
+/** The default well-known negotiation path, served by `serveHttp` and asked by the client. */
+export declare const WELL_KNOWN_PATH = "/.well-known/jaren-contract";
+/** The default JSON media of the binding. */
+export declare const JSON_MEDIA = "application/json";
+/** The response `content-type` of a JSON body. */
+export declare const JSON_CONTENT_TYPE = "application/json; charset=utf-8";
+export type Catalog = Readonly<Record<string, (params: object, error?: object) => string>>;
+/**
+ * A compiled catalog: msgid → render.
+ * @typedef {Readonly<Record<string, (params: object, error?: object) => string>>} Catalog
+ */
+/**
+ * Render a message: the host catalog first, the English catalog second,
+ * a fixed fallback last. TOTAL: a rendering closure that throws yields
+ * the fallback rather than escaping into the response path.
+ * @param {Catalog | null} catalog - the host catalog, or null for English only
+ * @param {string} msgid
+ * @param {Record<string, unknown>} params
+ * @returns {string}
+ */
+export declare function renderMessage(catalog: Catalog | null, msgid: string, params: Record<string, unknown>): string;
+/**
+ * The message of a declared operation error, as every server-side
+ * binding renders it: `contract/error/<code>` from the host catalog when
+ * it defines one, else the generic `contract/handler-error` — with the
+ * failure's own params plus `op` and `code`.
+ * @param {Catalog | null} catalog
+ * @param {string} op - the operation id
+ * @param {string} code - the declared error code
+ * @param {Readonly<Record<string, unknown>>} params
+ * @returns {string}
+ */
+export declare function declaredMessage(catalog: Catalog | null, op: string, code: string, params: Readonly<Record<string, unknown>>): string;
+/**
+ * The single string value of a header: a repeated field is combined with
+ * `, ` (RFC 9110 §5.3), an absent one is `undefined`. For the protocol
+ * headers the binding itself reads (`content-type`, `content-length`,
+ * `idempotency-key`, `if-match`, `if-none-match`).
+ * @param {Readonly<Record<string, string | readonly string[]>>} headers
+ * @param {string} name - lowercase
+ * @returns {string | undefined}
+ */
+export declare function headerValue(headers: Readonly<Record<string, string | readonly string[]>>, name: string): string | undefined;
+/**
+ * The declared `content-length` as a non-negative integer, or `-1` when
+ * absent or not a plain decimal number (a malformed value never blocks
+ * the read-length check that follows).
+ * @param {Readonly<Record<string, string | readonly string[]>>} headers
+ * @returns {number}
+ */
+export declare function contentLength(headers: Readonly<Record<string, string | readonly string[]>>): number;
+/**
+ * Whether a request `content-type` names the operation's media:
+ * type/subtype compared case-insensitively, parameters ignored, and a
+ * `+json` structured-syntax suffix accepted for `application/json`.
+ * @param {string | undefined} contentType
+ * @param {string} media - the operation's declared media
+ * @returns {boolean}
+ */
+export declare function mediaMatches(contentType: string | undefined, media: string): boolean;
+/**
+ * The byte length of a body — text measured as UTF-8. Cheap on the
+ * common path: a string shorter than the limit in code units cannot
+ * exceed it, and one longer than a third of the limit in code units is
+ * measured exactly only when it could.
+ * @param {string | Uint8Array} body
+ * @param {number} limit
+ * @returns {boolean} true when the body exceeds `limit` bytes
+ */
+export declare function exceedsBytes(body: string | Uint8Array, limit: number): boolean;
+/**
+ * Parse an `If-Match`/`If-None-Match` field into its opaque tags. `*` is
+ * reported as `null` in the list; a weak indicator is dropped
+ * (`W/"x"` → `x`) — the caller decides weak/strong comparison because a
+ * strong comparison must reject weak tags, which `weak[i]` records.
+ * @param {string} value
+ * @returns {{ any: boolean, tags: string[], weak: boolean[] }}
+ */
+export declare function parseEntityTags(value: string): {
+    any: boolean;
+    tags: string[];
+    weak: boolean[];
+};
+/**
+ * Whether a conditional header matches the tag the handler armed.
+ * Weak comparison ignores the weak indicators (RFC 9110 §8.8.3.2);
+ * strong comparison requires both tags strong.
+ * @param {string} header - the raw `if-match`/`if-none-match` value
+ * @param {string} tag - the armed opaque tag
+ * @param {boolean} tagStrong - whether the armed tag is strong
+ * @param {boolean} strong - strong comparison
+ * @returns {boolean}
+ */
+export declare function entityTagMatches(header: string, tag: string, tagStrong: boolean, strong: boolean): boolean;
+/**
+ * The `etag` header value of an armed tag.
+ * @param {string} tag
+ * @param {boolean} strong
+ * @returns {string}
+ */
+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
+ * 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.
+ * @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
+ * @returns {boolean} false when not decodable
+ */
+export declare function decodeQuery(query: string, declared: ReadonlySet<string>, repeated: ReadonlySet<string>, out: Record<string, unknown>): boolean;
+/**
+ * The verdict of a compiled validator under either contract: the
+ * default `{ valid, errors }` or a host-injected boolean validator.
+ * TOTAL: a validator that throws is a failed verdict carrying the throw.
+ * Shared by the server pipeline and the client.
+ * @param {(value: unknown) => any} validate
+ * @param {unknown} value
+ * @returns {{ valid: boolean, errors: any[], thrown: unknown }}
+ */
+export declare function verdict(validate: (value: unknown) => any, value: unknown): {
+    valid: boolean;
+    errors: any[];
+    thrown: unknown;
+};
+/**
+ * The details member of a validation failure by policy: `none` → absent,
+ * `paths` → `[{ path, keyword }]`, `full` → the validator's own error
+ * records (`toJSON()` when it has one) with their `params`.
+ * @param {'none' | 'paths' | 'full'} policy
+ * @param {any[]} errors - the validator's error list
+ * @returns {unknown}
+ */
+export declare function projectValidationDetails(policy: 'none' | 'paths' | 'full', errors: any[]): unknown;
+/**
+ * Build the D7 error body and the response around it. `override` is the
+ * host's `errorBody` option: called with the wire record (the body plus
+ * `status`) and the request context; TOTAL — a projector that throws or
+ * returns a non-JSON value falls back to the D7 shape.
+ * @param {number} status
+ * @param {string} code
+ * @param {string} message
+ * @param {string} trace
+ * @param {unknown} details - `undefined` for none
+ * @param {boolean} retryable
+ * @param {Readonly<Record<string, string>> | null} extraHeaders - `allow`, `retry-after`, `etag`
+ * @param {((wire: WireErrorBody & { status: number }, ctx: any) => unknown) | null} override
+ * @param {any} ctx - the request context, or null before an operation matched
+ * @returns {HttpResponse}
+ */
+export declare function errorResponse(status: number, code: string, message: string, trace: string, details: unknown, retryable: boolean, extraHeaders: Readonly<Record<string, string>> | null, override: ((wire: WireErrorBody & {
+    status: number;
+}, ctx: any) => unknown) | null, ctx: any): HttpResponse;

package/dist/types/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @file Public surface of @jarenjs/contract: `compileContract` turns a
+ * `$contract` document into a frozen `Contract` (docs/CONTRACT-FORMAT.md);
+ * the error classes, the `JC` code table and the `ContractFailure`
+ * factory are what a host catches, reads and returns. The bindings live
+ * behind their own subpaths (`./http`, `./fetch`, `./node`, `./ledger`)
+ * so a consumer that only compiles never loads them. The path matcher is
+ * deliberately NOT exported — it is reached only through `contract.match`
+ * and `contract.allowed`.
+ */
+export { compileContract } from './compile.js';
+export { ContractCompileError, ContractRuntimeError, ContractHostError, ContractFailure, isContractFailure, CONTRACT_CODES, } from './errors.js';
+export { contractMessagesEn, contractCatalogEn } from './messages.js';
+export type Contract = import('./compile.js').Contract;
+export type CompiledOperation = import('./compile.js').CompiledOperation;
+export type CompiledHttp = import('./compile.js').CompiledHttp;
+export type CompiledPolicy = import('./compile.js').CompiledPolicy;
+export type CompiledInput = import('./compile.js').CompiledInput;
+export type CompiledOutput = import('./compile.js').CompiledOutput;
+export type CompiledErrorDecl = import('./compile.js').CompiledErrorDecl;
+export type InputTransport = import('./compile.js').InputTransport;
+export type CompileContractOptions = import('./compile.js').CompileContractOptions;
+export type ContractDescription = import('./describe.js').ContractDescription;
+export type OperationDescription = import('./describe.js').OperationDescription;
+export type ContractFailureValue = import('./errors.js').ContractFailureValue;
+/**
+ * @typedef {import('./compile.js').Contract} Contract
+ * @typedef {import('./compile.js').CompiledOperation} CompiledOperation
+ * @typedef {import('./compile.js').CompiledHttp} CompiledHttp
+ * @typedef {import('./compile.js').CompiledPolicy} CompiledPolicy
+ * @typedef {import('./compile.js').CompiledInput} CompiledInput
+ * @typedef {import('./compile.js').CompiledOutput} CompiledOutput
+ * @typedef {import('./compile.js').CompiledErrorDecl} CompiledErrorDecl
+ * @typedef {import('./compile.js').InputTransport} InputTransport
+ * @typedef {import('./compile.js').CompileContractOptions} CompileContractOptions
+ * @typedef {import('./describe.js').ContractDescription} ContractDescription
+ * @typedef {import('./describe.js').OperationDescription} OperationDescription
+ * @typedef {import('./errors.js').ContractFailureValue} ContractFailureValue
+ */

package/dist/types/ledger.d.ts

@@ -0,0 +1,207 @@
+/**
+ * @file Idempotency as data: the ledger INTERFACE the http server
+ * binding calls when an operation declares `policy.idempotency`, a
+ * `createMemoryLedger` reference implementation for tests and
+ * single-process hosts, and the two documents a durable host opens with
+ * the rest of the suite — `idempotencyLedgerModel` (a `$model` 0.1
+ * document for `@jarenjs/db`) and `commandLifecycleFsm` (a `$fsm` 0.1
+ * document for `@jarenjs/flow`). Both are JSON only: this package never
+ * imports db or flow (docs/CONTRACT-FORMAT.md §8).
+ *
+ * The three identities stay apart here as everywhere: the idempotency
+ * KEY is the caller's (sent as `Idempotency-Key`, scoped by the host's
+ * `scope`), the request HASH is the binding's (SHA-256 over the RFC 8785
+ * canonical input), and the TRACE is never stored — a replay carries a
+ * fresh one.
+ */
+export type LedgerRecord = {
+    /**
+     * - `"<op>|<scope>|<key>"`
+     */
+    id: string;
+    op: string;
+    scope: string;
+    key: string;
+    /**
+     * - lowercase hex SHA-256 over the canonical input
+     */
+    hash: string;
+    status: 'started' | 'committed' | 'failed';
+    /**
+     * - the stored `{ status, headers, body }`, or null
+     */
+    response: any;
+    /**
+     * - of a failed record; null otherwise
+     */
+    retryable: boolean | null;
+    /**
+     * - epoch ms
+     */
+    createdAt: number;
+    /**
+     * - epoch ms
+     */
+    updatedAt: number;
+    /**
+     * - epoch ms
+     */
+    expiresAt: number;
+};
+export type ClaimResult = {
+    state: 'new';
+    ref: unknown;
+} | {
+    state: 'replay';
+    response: any;
+} | {
+    state: 'in-progress';
+} | {
+    state: 'mismatch';
+};
+export type Ledger = {
+    claim: (claim: {
+        op: string;
+        scope: string;
+        key: string;
+        hash: string;
+        now?: number;
+    }) => ClaimResult | Promise<ClaimResult>;
+    commit: (ref: unknown, response: any) => void | Promise<void>;
+    fail: (ref: unknown, retryable: boolean, response?: any) => void | Promise<void>;
+    lookup: (key: {
+        op: string;
+        scope: string;
+        key: string;
+    }) => LedgerRecord | null | Promise<LedgerRecord | null>;
+};
+/**
+ * The reference ledger over a `Map`: synchronous, single-process,
+ * expiring on `claim` (a record past `expiresAt` is dropped and the key
+ * is `new` again). `sweep()` drops every expired record — a host may
+ * call it on a timer.
+ * @param {{ ttlMs?: number, now?: () => number }} [options]
+ * @returns {Ledger & { sweep(): number, size: number }}
+ */
+export declare function createMemoryLedger(options?: {
+    ttlMs?: number;
+    now?: () => number;
+}): Ledger & {
+    sweep(): number;
+    size: number;
+};
+/**
+ * The `$model` 0.1 document of a durable ledger: one collection,
+ * `ledger`, keyed by `/id` (`"<op>|<scope>|<key>"`), indexed on
+ * `expiresAt` (the sweep) and `status` (the in-flight scan). A host
+ * opens it with `@jarenjs/db`'s `openStore` and implements the `Ledger`
+ * interface over the collection; the record shape is exactly what
+ * `createMemoryLedger` keeps.
+ */
+export declare const idempotencyLedgerModel: Readonly<{
+    $model: "0.1";
+    collections: {
+        ledger: {
+            schema: {
+                type: string;
+                required: string[];
+                properties: {
+                    id: {
+                        type: string;
+                        minLength: number;
+                    };
+                    op: {
+                        type: string;
+                        minLength: number;
+                    };
+                    scope: {
+                        type: string;
+                    };
+                    key: {
+                        type: string;
+                        minLength: number;
+                    };
+                    hash: {
+                        type: string;
+                        pattern: string;
+                    };
+                    status: {
+                        type: string;
+                        enum: string[];
+                    };
+                    response: {
+                        oneOf: ({
+                            type: string;
+                            required?: undefined;
+                            properties?: undefined;
+                        } | {
+                            type: string;
+                            required: string[];
+                            properties: {
+                                status: {
+                                    type: string;
+                                    minimum: number;
+                                    maximum: number;
+                                };
+                                headers: {
+                                    type: string;
+                                    additionalProperties: {
+                                        type: string;
+                                    };
+                                };
+                                body: {
+                                    type: string[];
+                                };
+                            };
+                        })[];
+                    };
+                    retryable: {
+                        type: string[];
+                    };
+                    createdAt: {
+                        type: string;
+                    };
+                    updatedAt: {
+                        type: string;
+                    };
+                    expiresAt: {
+                        type: string;
+                    };
+                };
+                additionalProperties: boolean;
+            };
+            key: string;
+            indexes: {
+                name: string;
+                path: string;
+            }[];
+        };
+    };
+}>;
+/**
+ * The `$fsm` 0.1 document of one command's lifecycle under an
+ * idempotency key: `idle → started` on `claim`, `started → committed` on
+ * `commit`, `started → failed` on `fail`, and `failed → started` on
+ * `claim` only when the failure was retryable (`$.context.retryable`).
+ * A host compiles it with `@jarenjs/flow` to drive or audit a durable
+ * ledger; the memory ledger walks exactly these transitions.
+ */
+export declare const commandLifecycleFsm: Readonly<{
+    $fsm: "0.1";
+    initial: "idle";
+    states: (string | {
+        id: string;
+        final: boolean;
+    })[];
+    transitions: ({
+        from: string;
+        event: string;
+        to: string;
+        guard?: undefined;
+    } | {
+        from: string;
+        event: string;
+        guard: string;
+        to: string;
+    })[];
+}>;