@jarenjs/contract 0.43.1

package/dist/types/diff.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @file `diffContracts(a, b)`: what changed from contract `a` to contract
+ * `b`, classified by the published rule table (docs/CONTRACT-FORMAT.md
+ * §13, rows R1–R15) into `breaking`, `additive`, `neutral` and `unknown`
+ * — where `unknown` is the honest fourth class: a schema construct the
+ * checker does not model (`anyOf`, `if`, a changed `pattern`, an external
+ * `$ref` that moved) is REPORTED, never silently classed.
+ *
+ * The schema comparison walks the two sides in parallel over the resolved
+ * same-document structure — a bare `{ "$ref": "#/$defs/X" }` hop is
+ * followed with the same rules the compiler used — and models exactly the
+ * R6 keyword set (`type`, `const`, `enum`, `maximum`, `minimum`,
+ * `maxLength`, `minLength`, `pattern`) plus object structure
+ * (`properties`, `required`, `additionalProperties`) and `items`. Pure
+ * annotations (`title`, `description`, `examples`, `$comment`,
+ * `deprecated`) never move a wire byte and are ignored; every other
+ * keyword that differs between the two sides lands in `unknown` (R15).
+ *
+ * A `Change`'s `docPath` points into the document that carries it — a
+ * removal into `a`, everything else into `b` — composed over the RESOLVED
+ * structure, so a constraint reached through a `$ref` reports the path a
+ * validator error would name, not the `$defs` entry's.
+ */
+export { isCompatible, compatReason } from './compat.js';
+export type Contract = import('./compile.js').Contract;
+export type CompiledOperation = import('./compile.js').CompiledOperation;
+export type Change = {
+    /**
+     * - a stable slug naming what changed (`'operation-removed'`, `'input-narrowed'`, …)
+     */
+    kind: string;
+    /**
+     * - the operation id
+     */
+    op: string;
+    /**
+     * - RFC 6901 pointer to the change (into `a` for a removal, into `b` otherwise)
+     */
+    docPath: string;
+    /**
+     * - the old value, where one exists
+     */
+    from?: unknown;
+    /**
+     * - the new value, where one exists
+     */
+    to?: unknown;
+    /**
+     * - the §13 row: `'R1'`–`'R15'`
+     */
+    rule: string;
+    /**
+     * - the honesty rider some rows carry (R5's "now ignored, not validated")
+     */
+    note?: string;
+};
+export type ContractDiff = {
+    breaking: Change[];
+    additive: Change[];
+    neutral: Change[];
+    unknown: Change[];
+};
+export type Side = {
+    doc: any;
+    anchors: Map<string, object>;
+};
+export type Sink = {
+    constraint: (direction: 'narrowed' | 'widened', keyword: string, path: string, from: unknown, to: unknown) => void;
+    /**
+     *   `direction` is the AP-aware narrowing/widening reading of the member
+     *   event (`null` when it is a no-op, e.g. an unconstrained optional
+     *   member added to an open object)
+     */
+    member: (event: 'removed' | 'added-required' | 'added-optional' | 'made-required' | 'made-optional', direction: 'narrowed' | 'widened' | null, path: string, member: string) => void;
+    unknown: (keyword: string, path: string, from: unknown, to: unknown) => void;
+};
+/**
+ * Classify every change from contract `a` to contract `b` by the §13
+ * rule table. Takes compiled contracts or raw documents (documents are
+ * compiled, so a malformed one refuses with its compile error before any
+ * comparison). Operations whose `policy.audience` is `server` on BOTH
+ * sides are outside the compatibility surface and are skipped; an
+ * audience flip is R14 and subsumes the operation's other changes.
+ * @param {Contract | Record<string, unknown>} a - the contract consumers hold today
+ * @param {Contract | Record<string, unknown>} b - the contract they would meet
+ * @returns {ContractDiff}
+ * @example
+ * const { breaking } = diffContracts(v1Doc, v2Doc);
+ * if (breaking.length > 0) throw new Error(breaking.map((c) => `${c.rule} ${c.op}: ${c.kind}`).join('\n'));
+ */
+export declare function diffContracts(a: Contract | Record<string, unknown>, b: Contract | Record<string, unknown>): ContractDiff;

package/dist/types/errors.d.ts

@@ -0,0 +1,205 @@
+/**
+ * @file Error types for @jarenjs/contract, built on `@jarenjs/core`'s
+ * coded contract: every failure carries a stable `code`, a bare
+ * `reason`, a composed `message`, and — for compile errors — the
+ * `docPath` of the offending member of the contract document. The
+ * normative table lives in docs/CONTRACT-FORMAT.md §6, proven in sync
+ * with `CONTRACT_CODES` below by a test.
+ *
+ * The `JC` code space is partitioned by range so the layers of this
+ * package never collide:
+ *
+ *  - `JC0001–JC0049` document compile (`ContractCompileError`)
+ *  - `JC0050–JC0069` binding declaration and projection compile
+ *    (`JC0060`: the OpenAPI keyword policy)
+ *  - `JC1001–JC1049` host programming errors (thrown `TypeError`s)
+ *  - `JC2001–JC2049` http request-time (`ContractRuntimeError`)
+ *  - `JC2050–JC2069` client-side
+ *  - `JC2070–JC2089` port/local bindings
+ *  - `JC2090–JC2109` stream binding
+ *
+ * The document-compile range, the projection code, the host range, the
+ * http request-time range, the client range and the port/local range are
+ * populated; stream is reserved for its binding and is listed here so a
+ * later addition lands in its range rather than at the next free number.
+ */
+import { CodedError } from '@jarenjs/core/errors';
+/**
+ * The runtime code table: one entry per code this package can raise,
+ * proven in sync with CONTRACT-FORMAT.md §6's normative table by a test.
+ */
+export declare const CONTRACT_CODES: Readonly<{
+    JC0001: "the document is not a well-formed contract object: not an object, $contract is not \"0.1\", $defs is not a map of schemas, a member is not a JSON value, or a member threw when read";
+    JC0002: "operations is not an object with at least one member";
+    JC0003: "an operation id is not a dotted lowercase identifier";
+    JC0004: "kind is none of read, command, subscribe";
+    JC0005: "input is not a schema whose effective type is object";
+    JC0006: "output is absent or not a schema";
+    JC0007: "a $ref resolves neither within the document nor against the registered schemas";
+    JC0008: "http.path is not a valid path template";
+    JC0009: "a path variable, http.in key or http.body names no input member, or a member is mapped to a location it cannot travel in";
+    JC0010: "two operations share method and canonical path shape";
+    JC0011: "errors is malformed: not an object, a code is not a lowercase hyphenated word, a status is not a 100–599 integer, or a schema is not a schema";
+    JC0012: "http.method is not an uppercase token of the supported set, http.status is not a 200–299 integer, or http.media is not a media type";
+    JC0013: "an unknown member in a closed object (the document root, an operation, policy, http, limits, retry, or an error declaration)";
+    JC0014: "a policy member is mistyped or outside its declared set";
+    JC0015: "id, version, compat or an operation doc is mistyped";
+    JC0016: "an operation bound to GET or HEAD carries a body-located member (a GET body)";
+    JC0017: "an opaque operation (a non-JSON http.media) declares a body-located member — its body is bytes the contract never decodes, so the member could never be validated";
+    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";
+    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";
+    JC1002: "serveHttp, serveLocal or servePort: an operation has no handler (and, on serveHttp, options.partial is not set; an opaque operation needs none on the status-less bindings)";
+    JC1003: "a binding cannot carry a declared feature: an operation declares idempotency and serveHttp was given no ledger";
+    JC1004: "dispatch received a malformed request object (method or url not a string, headers not an object, body not a string, Uint8Array or null)";
+    JC1005: "a client or the contract effect was asked for an operation the contract does not declare, or invoke was asked for an opaque operation (use client.url on http; the status-less bindings cannot carry it at all)";
+    JC1006: "ctx.status(n) was called with a status that is not an integer in 200–299";
+    JC1007: "contractAppBinding: ops names an operation the contract does not declare, or namespace/statePath is malformed";
+    JC1008: "openHttpClient, openPortClient, client.url, createContractEffect, createContractSubscription or a projection (publicProjection, toOpenApi, toTypeScript, toMarkdown, contractTools): an argument or option is malformed (not a compiled contract, fetch/keys/sleep/createTaskEffect/projectError not a function, storage without read/write, a non-object input to url, an ops entry naming no or an opaque operation, a tool name outside ^[a-zA-Z0-9_-]{1,64}$ or shared by two operations)";
+    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)";
+    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)";
+    JC2004: "a body-carrying operation received a content-type that is not its declared media (415)";
+    JC2005: "the request body is present and is not valid JSON, or its bytes are not valid UTF-8 (400)";
+    JC2006: "the reassembled input fails the operation's input validator (400)";
+    JC2007: "the operation requires an Idempotency-Key header and none was sent (400)";
+    JC2008: "the handler threw a non-declared error, rejected, or returned a hostile value (500; onError sees it)";
+    JC2009: "the idempotency ledger reports the key in progress (retryable) or bound to a different request (mismatch) (409)";
+    JC2010: "the handler value fails the output validator or a declared error's details fail its schema — the server broke the contract (500)";
+    JC2011: "the request path carries a malformed percent-escape (400)";
+    JC2012: "the query string is not decodable (400)";
+    JC2013: "the operation has no handler on this partial server (501)";
+    JC2014: "the If-Match precondition does not match the entity tag the handler armed (412)";
+    JC2015: "a declared header member is repeated when its schema is scalar, or fails transport decoding (400)";
+    JC2050: "the input fails the operation's input validator before anything was sent (kind contract)";
+    JC2051: "the request did not complete: the transport rejected or timed out (kind network, retryable)";
+    JC2052: "the request was cancelled through the caller's signal or client.close() (kind cancelled)";
+    JC2053: "a success response is not JSON or fails the operation's output validator (kind contract)";
+    JC2054: "the durable idempotency-key storage threw before the request was sent (kind contract)";
+    JC2055: "the server answered a status with a body that is neither a declared error nor a taxonomy error (kind contract; retryable for 5xx and 429)";
+    JC2056: "negotiation: the server does not answer a jaren-contract description at the well-known path, or describes another contract id";
+    JC2057: "negotiation: the server speaks a version neither end declares compatible";
+    JC2058: "the host threw while invoking an operation through the contract effect — projected into an outcome, never a string";
+    JC2070: "the handler failed on a local or port serving host: it threw a non-declared error, rejected, answered an undeclared code, or broke its output or error-details schema (kind contract; onError sees the cause)";
+    JC2071: "a request frame names no operation this channel serves (unknown, or opaque — a port carries JSON only)";
+    JC2072: "a port request got no answer within timeoutMs (kind network, retryable)";
+    JC2073: "a response frame addressed to this client does not match the frame grammar (kind contract)";
+    JC2074: "the channel refused the request frame — closed or detached (kind network)";
+    JC2090: "the server answered a subscribe request with a non-stream response (kind contract)";
+    JC2091: "a snapshot fails the operation's output validator — the server broke the contract; the stream ends with an error event carrying this code";
+    JC2092: "a stream event's seq is not strictly greater than the last one delivered (kind contract, client-side)";
+    JC2093: "the stream ended with a server error event whose code the operation does not declare (kind contract; a declared code is a failure outcome under its own code)";
+    JC2094: "the stream went silent for twice policy.stream.heartbeatMs (kind network, client-side)";
+    JC2095: "a requested resume was refused — informational, carried as resumed:false in the fresh snapshot's event data, never an outcome";
+}>;
+/**
+ * A defect in the contract document itself, raised while
+ * `compileContract` compiles it. Every instance carries the JSON
+ * Pointer of the offending member as `docPath` (`''` is the document
+ * root; an operation id is one reference token, so a dotted id such as
+ * `product.save` appears unescaped and only `~` and `/` are escaped per
+ * RFC 6901). The codes are `JC0001–JC0049` (docs/CONTRACT-FORMAT.md §6).
+ */
+export declare class ContractCompileError extends CodedError {
+    /**
+     * @param {string} code
+     * @param {string} reason - The bare reason; `message` is composed per
+     *   the coded contract.
+     * @param {string} [docPath] - JSON Pointer into the contract document;
+     *   `''` is the document root, `undefined` means no location.
+     * @param {Error} [cause]
+     */
+    constructor(code: string, reason: string, docPath?: string, cause?: Error);
+}
+/**
+ * A request-time failure (`JC2xxx`) as it exists in-process before a
+ * binding maps it onto its wire: a stable `code`, a `msgid`
+ * (`contract/<slug>`) with `params` for the locale catalogs, and the
+ * transport hints a binding may carry (`status`, `retryable`). It has no
+ * document location — a request is not a document — so `docPath` is
+ * always `undefined`. Never thrown across a binding: a binding settles
+ * it into a wire error.
+ */
+export declare class ContractRuntimeError extends CodedError {
+    /** @type {string} */
+    msgid: string;
+    /** @type {Record<string, unknown>} */
+    params: Record<string, unknown>;
+    /** @type {number | undefined} */
+    status: number | undefined;
+    /** @type {boolean | undefined} */
+    retryable: boolean | undefined;
+    /**
+     * @param {string} code
+     * @param {string} reason - The bare English reason; `message` is
+     *   composed per the coded contract.
+     * @param {{ msgid: string, params?: Record<string, unknown>, status?: number, retryable?: boolean, cause?: unknown }} options
+     *   `msgid` is the catalog key; `cause` is installed as an own property
+     *   exactly when the key is present (`hasOwn` form).
+     */
+    constructor(code: string, reason: string, options: {
+        msgid: string;
+        params?: Record<string, unknown>;
+        status?: number;
+        retryable?: boolean;
+        cause?: unknown;
+    });
+}
+/**
+ * A host programming error at a binding's construction or use — a
+ * handler table that names no operation, a missing ledger for a declared
+ * idempotency policy, a malformed request object handed to `dispatch`, a
+ * `ctx.status` outside 2xx. `TypeError`, thrown, never a wire response:
+ * the mistake is the host's, not the request's. The codes are
+ * `JC1001–JC1049` (docs/CONTRACT-FORMAT.md §7).
+ */
+export declare class ContractHostError extends TypeError {
+    /** @type {string} */
+    code: string;
+    /** @type {string} */
+    reason: string;
+    /**
+     * @param {string} code
+     * @param {string} reason - The bare reason; `message` is `${code}: ${reason}`.
+     */
+    constructor(code: string, reason: string);
+}
+export type ContractFailureValue = {
+    code: string;
+    params: Readonly<Record<string, unknown>>;
+    /**
+     * - `undefined` when the failure carries none
+     */
+    details: unknown;
+    /**
+     * - `null` defers to the operation's retry policy
+     */
+    retryable: boolean | null;
+};
+/**
+ * Make a declared failure value: what a handler returns (or `ctx.fail`
+ * returns for it) to answer with one of the operation's declared error
+ * codes. A branded plain-object factory, not a class: the value crosses
+ * no binding as an `Error` and carries only JSON.
+ * @param {string} code - A code the operation declares in `errors`
+ * @param {Record<string, unknown>} [params] - Message parameters for the catalog
+ * @param {unknown} [details] - The wire `details` member
+ * @param {{ retryable?: boolean }} [options] - `retryable` overrides the
+ *   default taken from the operation's `policy.retry.on`
+ * @returns {ContractFailureValue}
+ */
+export declare function ContractFailure(code: string, params?: Record<string, unknown>, details?: unknown, options?: {
+    retryable?: boolean;
+}): ContractFailureValue;
+/**
+ * True exactly for a value `ContractFailure` produced. Reads nothing
+ * from the value, so it is total for a hostile object.
+ * @param {unknown} value
+ * @returns {value is ContractFailureValue}
+ */
+export declare function isContractFailure(value: unknown): value is ContractFailureValue;

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

@@ -0,0 +1,148 @@
+/**
+ * @file The request pipeline of the HTTP server binding: one plain
+ * request object in, one plain response object out — route, decode,
+ * assemble, normalize, validate, claim idempotency, call the handler
+ * through one uniform promise boundary, validate the output, apply the
+ * entity-tag conditionals, serialize, commit. Every failure a request
+ * can cause is a coded response (docs/CONTRACT-FORMAT.md §7); the
+ * function rejects only for a malformed request OBJECT (`JC1004`, an
+ * adapter author's mistake) — never for request content and never for
+ * what a handler returns or throws (the `tasks.js` posture: a hostile
+ * value settles into `JC2008`/`JC2010`, it does not escape).
+ *
+ * The trust boundary: the contract, the handlers and the ledger are the
+ * host's; the request is hostile. Only declared header members and the
+ * protocol headers the binding itself needs are read; the input object
+ * is assembled through `setObjectMember` from declared names only; a
+ * body member that names a path/query/header member is ignored; nothing
+ * a request sent is echoed into a message.
+ */
+export type HttpRequest = import('./wire.js').HttpRequest;
+export type HttpResponse = import('./wire.js').HttpResponse;
+export type Catalog = import('./wire.js').Catalog;
+export type CompiledOperation = import('../compile.js').CompiledOperation;
+export type CompiledErrorDecl = import('../compile.js').CompiledErrorDecl;
+export type ContractFailureValue = import('../errors.js').ContractFailureValue;
+export type OperationResult = import('../pipeline.js').OperationResult;
+export type Ledger = import('../ledger.js').Ledger;
+export type RequestContext = {
+    op: CompiledOperation;
+    trace: string;
+    method: string;
+    path: string;
+    params: Readonly<Record<string, string>>;
+    headers: Readonly<Record<string, string>>;
+    body: string | Uint8Array | null;
+    signal: AbortSignal | null;
+    idempotency: Readonly<{
+        key: string;
+        scope: string;
+    }> | null;
+    fail: (code: string, params?: Record<string, unknown>, details?: unknown, options?: {
+        retryable?: boolean;
+    }) => ContractFailureValue;
+    etag: (tag: string, options?: {
+        strong?: boolean;
+    }) => void;
+    status: (status: number) => void;
+};
+export type Handler = (input: any, ctx: RequestContext) => unknown;
+export type RawResponse = {
+    status: number;
+    headers?: Record<string, string>;
+    body?: string | Uint8Array | null;
+};
+export type Route = {
+    op: CompiledOperation;
+    /**
+     * - `null` on a partial server
+     */
+    handler: Handler | null;
+    /**
+     * - opaque: the handler is raw
+     */
+    raw: boolean;
+    /**
+     * - a subscribe operation: the handler answers a subscription
+     */
+    stream: boolean;
+    maxBody: number;
+    media: string;
+    /**
+     * - any body-located member, or a whole-body member
+     */
+    hasBody: boolean;
+    wholeBody: string | null;
+    /**
+     * - path/query/header member names, never taken from the body
+     */
+    nonBody: ReadonlySet<string>;
+    pathMembers: readonly string[];
+    queryMembers: ReadonlySet<string>;
+    /**
+     * - array-typed query members
+     */
+    repeated: ReadonlySet<string>;
+    /**
+     * - member names
+     */
+    headerMembers: readonly string[];
+    /**
+     * - the lowercase header of each
+     */
+    headerNames: readonly string[];
+    /**
+     * - array-typed, per header member
+     */
+    headerArray: readonly boolean[];
+    normalize: ((value: any) => any) | null;
+    validateInput: ((value: unknown) => any) | null;
+    validateOutput: (value: unknown) => any;
+    details: 'none' | 'paths' | 'full';
+    idempotency: 'none' | 'optional' | 'required';
+    retryOn: ReadonlySet<string>;
+    errors: Readonly<Record<string, CompiledErrorDecl>>;
+    status: number;
+};
+export type Server = {
+    contract: import('../compile.js').Contract;
+    routes: ReadonlyMap<string, Route>;
+    trace: () => string;
+    ledger: Ledger | null;
+    scope: (ctx: RequestContext) => string;
+    head: boolean;
+    validateOutput: boolean;
+    wellKnown: string | false;
+    errorBody: ((wire: any, ctx: RequestContext | null) => unknown) | null;
+    onError: ((error: unknown, ctx: RequestContext | null) => void) | null;
+    catalog: Catalog | null;
+    now: () => number;
+    /**
+     * - the memoized well-known body
+     */
+    described: {
+        text: string | null;
+    };
+    /**
+     * - the live SSE
+     * streams' stoppers; the dispatcher's `close()` ends them all
+     */
+    streams: Set<(reason: string | null) => void>;
+};
+/**
+ * The one entry point. Validates the request object (a malformed one is
+ * `JC1004`, rejected — the adapter's mistake), then runs the pipeline and
+ * lifts its result into a promise. Total for request content: every
+ * request-caused failure resolves to a response.
+ * @param {Server} server
+ * @param {HttpRequest} request
+ * @returns {Promise<HttpResponse>}
+ */
+export declare function dispatch(server: Server, request: HttpRequest): Promise<HttpResponse>;
+export type Armed = {
+    etag: string | null;
+    strong: boolean;
+    status: number;
+    outcome: number;
+    retryable: boolean;
+};

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

@@ -0,0 +1,154 @@
+/**
+ * @file `serveHttp(contract, handlers, options)`: the HTTP server binding
+ * of a compiled contract — a driver in the `@jarenjs/db` sense: a
+ * `name`, a frozen `capabilities` table that says what this binding
+ * cannot carry (never a silent downgrade), and the one method a host
+ * calls per request, `dispatch(request) → Promise<response>` over plain
+ * request/response objects (docs/CONTRACT-FORMAT.md §7). The adapters
+ * (`@jarenjs/contract/fetch`, `/node`) put that function behind the
+ * platform's request and response types.
+ *
+ * Construction refuses host mistakes with thrown `ContractHostError`s
+ * (`JC1001–JC1003`): a handler table that names no operation, a missing
+ * handler on a non-partial server, a declared idempotency policy with no
+ * ledger to carry it. Everything the pipeline reads per request is
+ * decided here, once, into a `Route` per operation.
+ */
+import { HTTP_ERRORS, WELL_KNOWN_PATH } from './wire.js';
+export { HTTP_ERRORS, WELL_KNOWN_PATH };
+export type HttpRequest = import('./wire.js').HttpRequest;
+export type HttpResponse = import('./wire.js').HttpResponse;
+export type WireErrorBody = import('./wire.js').WireErrorBody;
+export type RequestContext = import('./dispatch.js').RequestContext;
+export type Handler = import('./dispatch.js').Handler;
+export type RawResponse = import('./dispatch.js').RawResponse;
+export type Route = import('./dispatch.js').Route;
+export type Server = import('./dispatch.js').Server;
+export type Ledger = import('../ledger.js').Ledger;
+export type Contract = import('../compile.js').Contract;
+export type CompiledOperation = import('../compile.js').CompiledOperation;
+export type ServeHttpOptions = {
+    /**
+     * - the server trace generator; default `crypto.randomUUID`
+     */
+    trace?: () => string;
+    /**
+     * - the idempotency ledger; `null` refuses
+     * (`JC1003`) any operation whose `policy.idempotency` is not `none`
+     */
+    ledger?: Ledger | null;
+    /**
+     * - the idempotency scope
+     * of a request (an installation, a principal — never a rotating token);
+     * default `''`; called before `ctx.idempotency` is set
+     */
+    scope?: (ctx: RequestContext) => string;
+    /**
+     * - allow missing handlers; a missing one answers 501 `JC2013`
+     */
+    partial?: boolean;
+    /**
+     * - answer HEAD for GET operations by running the handler and dropping the body; default true
+     */
+    head?: boolean;
+    /**
+     * - `'never'` is a declared downgrade, reported in `capabilities.validatedOutput`
+     */
+    validateOutput?: 'always' | 'never';
+    /**
+     * - the path answering `describe()`; default `/.well-known/jaren-contract`; `false` disables
+     */
+    wellKnown?: string | false;
+    /**
+     * - projects the wire error record into the response body (a legacy
+     * shape, an extra `error` string); a throw or a non-JSON result falls
+     * back to the D7 shape
+     */
+    errorBody?: (wire: WireErrorBody & {
+        status: number;
+    }, ctx: RequestContext | null) => unknown;
+    /**
+     * - observes `JC2008`/`JC2010` causes and ledger faults; the response never carries them
+     */
+    onError?: (error: unknown, ctx: RequestContext | null) => void;
+    /**
+     * - a message catalog (templates or compiled renderers) consulted before the English one
+     */
+    catalog?: Record<string, string | ((params: object) => string)>;
+    /**
+     * - the clock stamped into ledger claims; default `Date.now`
+     */
+    now?: () => number;
+};
+export type HttpCapabilities = {
+    name: 'http';
+    /**
+     * - statuses are carried
+     */
+    status: true;
+    /**
+     * - headers are carried
+     */
+    headers: true;
+    /**
+     * - non-JSON media is carried (opaque operations)
+     */
+    media: true;
+    /**
+     * - HEAD is answered for GET operations
+     */
+    head: boolean;
+    /**
+     * - entity tags and conditionals are honored
+     */
+    etag: true;
+    /**
+     * - a ledger is present
+     */
+    idempotency: boolean;
+    /**
+     * - the output validator runs
+     */
+    validatedOutput: boolean;
+    /**
+     * - subscribe operations stream as SSE (docs/CONTRACT-FORMAT.md §18.1)
+     */
+    stream: true;
+    /**
+     * - cancellation reaches the handler as `ctx.signal`
+     */
+    cancel: 'signal';
+};
+export type HttpDispatcher = {
+    dispatch: (request: HttpRequest) => Promise<HttpResponse>;
+    capabilities: HttpCapabilities;
+    contract: Contract;
+    describe: () => any;
+    /**
+     * - ends every live SSE stream with an `end`
+     * event (`server-shutdown`) and releases its subscription; requests in
+     * flight are unaffected
+     */
+    close: () => void;
+};
+/**
+ * Serve a compiled contract over HTTP: a dispatcher whose `dispatch`
+ * routes, decodes, normalizes, validates, calls the handler, validates
+ * the output, applies idempotency and entity-tag policy and answers with
+ * the declared statuses and the D7 error body — a pure function over
+ * plain request/response objects. Refuses host mistakes at construction
+ * (`JC1001` handler table, `JC1002` missing handler, `JC1003` idempotency
+ * without a ledger).
+ *
+ * @param {Contract} contract
+ * @param {Record<string, Handler>} handlers - operation id → handler
+ * @param {ServeHttpOptions} [options]
+ * @returns {HttpDispatcher}
+ * @example
+ * const server = serveHttp(contract, {
+ *   'catalog.load': async (input, ctx) => { ctx.etag('r42'); return catalog; },
+ *   'product.save': (input, ctx) => saved ? product : ctx.fail('conflict', {}, { current }),
+ * }, { ledger: createMemoryLedger() });
+ * const response = await server.dispatch({ method: 'GET', url: '/api/catalog', headers: {}, body: null });
+ */
+export declare function serveHttp(contract: Contract, handlers: Record<string, Handler>, options?: ServeHttpOptions): HttpDispatcher;