@jarenjs/contract 0.43.1

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

@@ -0,0 +1,127 @@
+/**
+ * @file `openLocalClient(contract, handlers, options)`: the in-process
+ * binding of a compiled contract (docs/CONTRACT-FORMAT.md §15) — the
+ * same operation pipeline the HTTP server runs, with no wire: the test
+ * seam, SSR, a CLI. The client and the server are one object;
+ * `serveLocal` is the same factory under the serve name, for symmetry
+ * with the other bindings.
+ *
+ * `invoke(op, input, ctx)` validates the input with the operation's
+ * compiled validator (a refusal is the `JC2050` outcome — nothing ran),
+ * runs the neutral pipeline against the handler with a frozen context
+ * `{ op, trace, signal, params: null, headers: {}, fail, idempotency:
+ * null }`, and resolves a D6 outcome: a declared failure is `kind:
+ * "failure"` with `status: null` (the member present, never omitted —
+ * this binding carries no statuses and `capabilities` says so); a
+ * handler fault of any class — a throw, an undeclared code, a broken
+ * output or error-details schema — is `kind: "contract"` `JC2070`, its
+ * cause reported to `onError`, so a host bug is never mistaken for a
+ * declared failure; an aborted `ctx.signal` (or `close()`) is `kind:
+ * "cancelled"`, and a handler still running then settles into nothing.
+ *
+ * What this binding cannot carry, it refuses or ignores loudly:
+ * statuses, headers, entity tags and non-JSON media do not exist here
+ * (`invoke` of an opaque operation throws `JC1005`; a handler given for
+ * one is accepted so an HTTP handler table can be reused verbatim, and
+ * never called); a declared `policy.idempotency` is ALLOWED and ignored
+ * — the same contract must serve over http and locally, and re-running
+ * a command in one process is the caller's own hand — with
+ * `capabilities.idempotency: false` saying so.
+ */
+import { PORT_LOCAL_ERRORS } from '../pipeline.js';
+export { PORT_LOCAL_ERRORS };
+export type Contract = import('../compile.js').Contract;
+export type CompiledOperation = import('../compile.js').CompiledOperation;
+export type Catalog = import('../http/wire.js').Catalog;
+export type Handler = import('../http/dispatch.js').Handler;
+export type Outcome = import('../client/outcome.js').Outcome;
+export type OutcomeMeta = import('../client/outcome.js').OutcomeMeta;
+export type PipelineRoute = import('../pipeline.js').PipelineRoute;
+export type LocalOptions = {
+    /**
+     * - the trace generator; default `crypto.randomUUID`
+     */
+    trace?: () => string;
+    /**
+     * - `'never'` is a declared
+     * downgrade, reported in `capabilities.validatedOutput`
+     */
+    validateOutput?: 'always' | 'never';
+    /**
+     * - a message catalog consulted before the English one
+     */
+    catalog?: Record<string, string | ((params: object) => string)>;
+    /**
+     * - observes the cause behind every `JC2070` outcome and validator throw
+     */
+    onError?: (error: unknown, ctx: {
+        op: string;
+        trace: string;
+    } | null) => void;
+};
+export type LocalInvokeContext = {
+    /**
+     * - resolves the outcome `cancelled`
+     */
+    signal?: AbortSignal;
+    /**
+     * - the caller's attempt id, echoed in `meta.attempt`
+     */
+    attempt?: unknown;
+};
+export type LocalCapabilities = {
+    name: 'local';
+    status: false;
+    headers: false;
+    media: false;
+    etag: false;
+    idempotency: false;
+    /**
+     * - the output validator runs
+     */
+    validatedOutput: boolean;
+    stream: false;
+    cancel: 'signal';
+};
+export type LocalClient = {
+    invoke: (op: string, input?: unknown, ctx?: LocalInvokeContext) => Promise<Outcome>;
+    capabilities: LocalCapabilities;
+    contract: Contract;
+    describe: () => any;
+    /**
+     * - later invokes resolve `cancelled`; running handlers see their signal abort
+     */
+    close: () => void;
+};
+export type LocalRoute = PipelineRoute & {
+    hasInput: boolean;
+    outcome: import('../client/outcome.js').OutcomeRoute;
+};
+/**
+ * Serve a compiled contract in-process and call it through the same
+ * object: the `open(contract) → Client` half and the `serve(contract,
+ * handlers)` half of the driver pair are one here. Construction refuses
+ * host mistakes (`JC1001` handler table or option, `JC1002` missing
+ * handler — an opaque operation is exempt: this binding cannot invoke
+ * it, and an HTTP handler table that carries one may be reused verbatim).
+ *
+ * @param {Contract} contract
+ * @param {Record<string, Handler>} handlers - operation id → handler
+ * @param {LocalOptions} [options]
+ * @returns {LocalClient}
+ * @throws {ContractHostError}
+ * @example
+ * const client = openLocalClient(contract, {
+ *   'catalog.load': () => catalog,
+ *   'product.save': (input, ctx) => saved ? product : ctx.fail('conflict', {}, { current }),
+ * });
+ * const outcome = await client.invoke('catalog.load', { since: '2026-01-01T00:00:00Z' });
+ * if (!outcome.ok && outcome.kind === 'failure') show(outcome.error.code);   // status is null here
+ */
+export declare function openLocalClient(contract: Contract, handlers: Record<string, Handler>, options?: LocalOptions): LocalClient;
+/**
+ * The serve name of the same factory: the server half IS the client half
+ * here — one object, both names, for symmetry with `serveHttp`/
+ * `openHttpClient` and `servePort`/`openPortClient`.
+ */
+export declare const serveLocal: typeof openLocalClient;

package/dist/types/messages.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @file The English message catalog: one template per `contract/*` msgid
+ * a binding can answer with — the HTTP taxonomy, the port/local codes,
+ * `contract/handler-error` (the generic text for a declared operation
+ * error that has no message of its own) — and one per client-originated
+ * outcome (the `JC205x` codes a client resolves without a server
+ * message). Compiled ONCE at module scope
+ * with `@jarenjs/core`'s `compileMessageCatalog` (the two-stage house
+ * rule applied to messages) and exported in plain form for the locale
+ * packs to mirror key for key.
+ *
+ * A message never interpolates a request value: the parameters are the
+ * operation id, a declared limit, a media type, a method list, a
+ * declared header member name, a declared error code, a status, a
+ * platform error's NAME or a contract version — trusted artifacts or
+ * protocol facts, never something a peer sent as content (the
+ * trust-boundary rule of docs/CONTRACT-FORMAT.md §7).
+ */
+/**
+ * The plain English catalog: msgid → template (`{param}` placeholders).
+ * The keys are exactly the msgids of the CONTRACT-FORMAT.md §7 taxonomy,
+ * `contract/handler-error`, and the §10 client table; a test holds them
+ * equal.
+ */
+export declare const contractMessagesEn: Readonly<{
+    'contract/not-found': "no operation matches the request method and path";
+    'contract/method-not-allowed': "the path is served under other methods: {allow}";
+    'contract/body-too-large': "the request body of operation {op} exceeds its {limit}-byte limit";
+    'contract/unsupported-media': "operation {op} accepts {media} bodies only";
+    'contract/malformed-json': "the request body of operation {op} is not valid JSON";
+    'contract/invalid-input': "the input of operation {op} is invalid";
+    'contract/idempotency-key-required': "operation {op} requires an Idempotency-Key header";
+    'contract/handler-failed': "operation {op} failed";
+    'contract/idempotency-conflict': "the Idempotency-Key of operation {op} conflicts with an earlier request ({kind})";
+    'contract/invalid-output': "operation {op} produced a response that violates its contract";
+    'contract/malformed-path': "the request path carries a malformed percent-escape";
+    'contract/malformed-query': "the query string is not decodable";
+    'contract/not-implemented': "operation {op} is not implemented on this server";
+    'contract/precondition-failed': "the If-Match precondition of operation {op} failed";
+    'contract/invalid-header': "the {header} header of operation {op} is invalid";
+    'contract/handler-error': "operation {op} failed with {code}";
+    'contract/client-invalid-input': "the input of operation {op} is invalid; nothing was sent";
+    'contract/network': "the request of {op} did not complete ({name})";
+    'contract/cancelled': "the request of operation {op} was cancelled";
+    'contract/invalid-response': "the response of operation {op} violates its contract";
+    'contract/key-storage-failed': "the idempotency key of operation {op} could not be stored; nothing was sent";
+    'contract/undeclared-response': "operation {op} answered an undeclared response (status {status})";
+    'contract/not-a-contract': "the server does not describe contract {id} at its well-known path";
+    'contract/incompatible': "the server speaks version {server} of contract {id}; this client speaks {client} and neither end declares the other compatible";
+    'contract/host-failed': "operation {op} failed in the host before an outcome was produced";
+    'contract/local-handler-failed': "operation {op} failed in the serving host";
+    'contract/unknown-operation': "the request names no operation served on this channel";
+    'contract/port-timeout': "operation {op} got no answer on the channel within {ms}ms";
+    'contract/malformed-frame': "the response frame of operation {op} is malformed";
+    'contract/channel-closed': "the channel of operation {op} is closed";
+    'contract/not-a-stream': "the server answered the subscription of operation {op} with a non-stream response";
+    'contract/invalid-snapshot': "operation {op} produced a snapshot that violates its contract";
+    'contract/seq-regression': "the stream of operation {op} violated its seq order";
+    'contract/stream-error': "the stream of operation {op} ended with a server error ({code})";
+    'contract/heartbeat-missed': "the stream of operation {op} went silent for {ms}ms";
+}>;
+/** The compiled English catalog (module-level singleton). */
+export declare const contractCatalogEn: Readonly<Record<string, (params: object, error?: object) => string>>;

package/dist/types/path.d.ts

@@ -0,0 +1,119 @@
+/**
+ * @file The path matcher: RFC 6570 level-1 templates (`/api/products/{id}`)
+ * compiled into one static-segment tree per HTTP method, walked by
+ * char-code scan with zero allocation until the leaf is known.
+ *
+ * Package-private (docs/CONTRACT-FORMAT.md §5). Two stages:
+ *
+ *  1. `parsePathTemplate` — the one template parser in the suite: it
+ *     canonicalizes `:name` to `{name}`, splits static from variable
+ *     segments and refuses every reserved form with a message that names
+ *     it. `compileContract` calls it once per operation and maps a
+ *     refusal to `JC0008`.
+ *  2. `compileRoutes` — the operation table becomes a tree of nodes
+ *     `{ statics, variable, leaf }`; `match(method, path)` walks statics
+ *     first, falls back to the variable child, and backtracks on a dead
+ *     end. Static beats variable REGARDLESS of registration order — the
+ *     ordering case a regex-per-route router refuses or gets wrong.
+ *
+ * Matching rules a binding relies on: exact on trailing slash (`/a/` is
+ * a different shape from `/a` and, since no template has an empty
+ * segment, never matches); a variable never binds an empty segment; each
+ * segment is percent-decoded once, statics compared in decoded space, and
+ * a decoded `/` never re-splits; a malformed escape makes `match` return
+ * `null` (never throw — a request is hostile input). `?`/`#` never reach
+ * `match`: the binding splits the query off first.
+ *
+ * Variable names live on the LEAF, not on the variable node: two
+ * templates that differ only in a variable's name (`/a/{x}/b`,
+ * `/a/{y}/c`) share the variable child and each leaf binds its own name.
+ * The one shape that cannot be represented is two leaves for one method
+ * and one shape — a duplicate the compiler has already refused as
+ * `JC0010`, so here it is a `TypeError` (a host programming guard).
+ */
+export type PathSegment = {
+    variable: boolean;
+    text: string;
+};
+export type ParsedPathTemplate = {
+    /**
+     * - The canonical template (`{name}` form).
+     */
+    path: string;
+    /**
+     * - In order; empty for `/`.
+     */
+    segments: readonly PathSegment[];
+    /**
+     * - Variable names in order.
+     */
+    variables: readonly string[];
+};
+/**
+ * Parse a path template into segments, canonicalizing `:name` to
+ * `{name}`. Throws a `TypeError` whose message names the rule that was
+ * broken (the compiler wraps it as `JC0008`).
+ *
+ * The dialect: a leading `/`; the root template `/` has no segments;
+ * every other segment is non-empty; a variable is a whole segment,
+ * `{name}` or `:name`, with `name` an identifier, declared once per
+ * template; the RFC 6570 operator and modifier forms (`{+name}`,
+ * `{?name}`, `{name*}`, `{name:3}`, `{a,b}`), the `{name+}` tail and the
+ * `*` wildcard are reserved and refused by name.
+ * @param {unknown} source
+ * @returns {ParsedPathTemplate}
+ */
+export declare function parsePathTemplate(source: unknown): ParsedPathTemplate;
+/**
+ * The shape of a template with every variable normalized to `{}` — the
+ * identity `JC0010` is decided on.
+ * @param {ParsedPathTemplate} parsed
+ * @returns {string}
+ */
+export declare function pathShape(parsed: ParsedPathTemplate): string;
+export type Leaf = {
+    key: any;
+    names: readonly string[];
+    depths: readonly number[];
+};
+export type Node = {
+    statics: Map<string, Node> | null;
+    variable: Node | null;
+    leaf: Leaf | null;
+};
+export type Router = {
+    match: (method: string, path: string) => {
+        key: any;
+        params: Record<string, string>;
+    } | null;
+    /**
+     * - the methods whose tree
+     * reaches a leaf for this path shape, sorted — what a 405 lists in
+     * `Allow`; `[]` for a malformed or unknown path
+     */
+    allowed: (path: string) => string[];
+};
+/**
+ * A compiled router.
+ * @typedef {Object} Router
+ * @property {(method: string, path: string) => { key: any, params: Record<string, string> } | null} match
+ * @property {(path: string) => string[]} allowed - the methods whose tree
+ *   reaches a leaf for this path shape, sorted — what a 405 lists in
+ *   `Allow`; `[]` for a malformed or unknown path
+ */
+/**
+ * Compile a route table into a `Router`. `entries` are
+ * `{ method, path, key }` with `path` in canonical `{name}` form (a
+ * `:name` template is a `TypeError` here — canonicalize with
+ * `parsePathTemplate` first). Two entries with one method and one shape
+ * are a `TypeError` (the compiler's `JC0010` has already refused them);
+ * templates that differ only in a variable name under a shared parent are
+ * fine as long as they end in different leaves.
+ * @param {readonly { method: string, path: string, key: any }[]} entries
+ * @returns {Router}
+ */
+export declare function compileRoutes(entries: readonly {
+    method: string;
+    path: string;
+    key: any;
+}[]): Router;

package/dist/types/pipeline.d.ts

@@ -0,0 +1,157 @@
+/**
+ * @file The transport-neutral core of every server-side binding: validate
+ * the assembled input, call the handler through ONE uniform promise
+ * boundary — a synchronous throw, a non-promise return and a rejection
+ * settle exactly alike — classify the settlement (a declared operation
+ * failure, with its details validated against the declaration's schema,
+ * or a host fault), and validate the output. The HTTP binding wraps the
+ * result in statuses, headers and bodies; the `local` and `port`
+ * bindings wrap it in D6 outcomes and frames — the classification is
+ * decided here once so the three can never disagree.
+ *
+ * Total for everything a handler can do: a hostile value whose `then`
+ * accessor throws is a rejection at the boundary (`JC2008`-class), a
+ * value whose other members throw survives it and dies in output
+ * validation (`JC2010`-class); nothing here throws for a settlement and
+ * nothing renders a message — the binding renders at its edge.
+ */
+export type CompiledOperation = import('./compile.js').CompiledOperation;
+export type CompiledErrorDecl = import('./compile.js').CompiledErrorDecl;
+export type PipelineRoute = {
+    op: CompiledOperation;
+    handler: ((input: any, ctx: any) => unknown) | null;
+    /**
+     * - opaque: the value is the binding's to check, never the output validator's
+     */
+    raw: boolean;
+    validateInput: ((value: unknown) => any) | null;
+    validateOutput: (value: unknown) => any;
+    details: 'none' | 'paths' | 'full';
+    errors: Readonly<Record<string, CompiledErrorDecl>>;
+    retryOn: ReadonlySet<string>;
+};
+export type OperationResult = {
+    kind: 'value';
+    value: unknown;
+} | {
+    kind: 'failure';
+    code: string;
+    params: Readonly<Record<string, unknown>>;
+    details: unknown;
+    retryable: boolean;
+    status: number;
+} | {
+    kind: 'contract';
+    code: 'JC2006' | 'JC2008' | 'JC2010';
+    details: unknown;
+    cause: unknown;
+};
+/**
+ * @typedef {import('./compile.js').CompiledOperation} CompiledOperation
+ * @typedef {import('./compile.js').CompiledErrorDecl} CompiledErrorDecl
+ */
+/**
+ * The neutral subset of a binding's prepared route — what the pipeline
+ * reads per operation. The HTTP binding's `Route` carries these members
+ * verbatim; the `local` and `port` bindings prepare exactly this.
+ * @typedef {Object} PipelineRoute
+ * @property {CompiledOperation} op
+ * @property {((input: any, ctx: any) => unknown) | null} handler
+ * @property {boolean} raw - opaque: the value is the binding's to check, never the output validator's
+ * @property {((value: unknown) => any) | null} validateInput
+ * @property {(value: unknown) => any} validateOutput
+ * @property {'none' | 'paths' | 'full'} details
+ * @property {Readonly<Record<string, CompiledErrorDecl>>} errors
+ * @property {ReadonlySet<string>} retryOn
+ */
+/**
+ * The classified settlement of one operation:
+ *
+ *  - `value` — the handler's output, validated;
+ *  - `failure` — a declared operation error (`errors[code]`), its
+ *    `details` validated, `retryable` from the failure or the retry
+ *    policy, `status` the declaration's (a status-less binding ignores
+ *    it);
+ *  - `contract` — the host broke the contract: `JC2006` the input fails
+ *    its validator (`details` by `policy.errors.details`), `JC2008` the
+ *    handler threw a non-declared error, rejected or answered an
+ *    undeclared code, `JC2010` the output or a declared error's details
+ *    fail their schema. `cause` is for the binding's `onError` observer
+ *    (`undefined` when there is nothing to report); it never crosses a
+ *    wire.
+ *
+ * @typedef {{ kind: 'value', value: unknown }
+ *   | { kind: 'failure', code: string, params: Readonly<Record<string, unknown>>, details: unknown, retryable: boolean, status: number }
+ *   | { kind: 'contract', code: 'JC2006' | 'JC2008' | 'JC2010', details: unknown, cause: unknown }} OperationResult
+ */
+/**
+ * The request-time codes of the `local` and `port` bindings —
+ * code → `{ msgid, retryable }`, the same table-as-data shape as
+ * `HTTP_ERRORS` and `CLIENT_ERRORS`. The normative table is
+ * docs/CONTRACT-FORMAT.md §15–§16; a test holds them equal.
+ */
+export declare const PORT_LOCAL_ERRORS: Readonly<{
+    JC2070: Readonly<{
+        msgid: "contract/local-handler-failed";
+        retryable: false;
+    }>;
+    JC2071: Readonly<{
+        msgid: "contract/unknown-operation";
+        retryable: false;
+    }>;
+    JC2072: Readonly<{
+        msgid: "contract/port-timeout";
+        retryable: true;
+    }>;
+    JC2073: Readonly<{
+        msgid: "contract/malformed-frame";
+        retryable: false;
+    }>;
+    JC2074: Readonly<{
+        msgid: "contract/channel-closed";
+        retryable: false;
+    }>;
+}>;
+/**
+ * A server trace id from a host generator. TOTAL: a generator that
+ * throws or answers a non-string is replaced by the platform's UUID.
+ * @param {() => string} trace
+ * @returns {string}
+ */
+export declare function safeTrace(trace: () => string): string;
+/**
+ * Validate the assembled input against the operation's input validator.
+ * `null` when valid (or the operation validates nothing); a `JC2006`
+ * contract result otherwise, its `details` projected by
+ * `policy.errors.details` and its `cause` the validator's own throw when
+ * it had one.
+ * @param {PipelineRoute} route
+ * @param {unknown} input
+ * @returns {OperationResult | null}
+ */
+export declare function validateOperationInput(route: PipelineRoute, input: unknown): OperationResult | null;
+/**
+ * Call the handler through the uniform promise boundary and classify the
+ * settlement. Never rejects; the returned promise always resolves an
+ * {@link OperationResult}.
+ * @param {PipelineRoute} route
+ * @param {any} input - the validated input (`null` for an input-less operation)
+ * @param {any} ctx - the frozen per-request context the handler receives
+ * @param {boolean} validateOutput
+ * @returns {Promise<OperationResult>}
+ */
+export declare function settleOperation(route: PipelineRoute, input: any, ctx: any, validateOutput: boolean): Promise<OperationResult>;
+/**
+ * The whole neutral pipeline of one operation: validate the input, then
+ * call and classify — for a binding with nothing of its own between the
+ * two steps (the HTTP binding interposes its idempotency claim and calls
+ * the two halves itself).
+ * @param {PipelineRoute} route
+ * @param {any} input
+ * @param {any} ctx
+ * @param {{ validateOutput?: boolean }} [options]
+ * @returns {Promise<OperationResult>}
+ */
+export declare function runOperation(route: PipelineRoute, input: any, ctx: any, options?: {
+    validateOutput?: boolean;
+}): Promise<OperationResult>;

package/dist/types/port/client.d.ts

@@ -0,0 +1,142 @@
+/**
+ * @file `openPortClient(contract, options)`: the client half of the port
+ * binding (docs/CONTRACT-FORMAT.md §16). `invoke(op, input, ctx)`
+ * validates the input with the operation's compiled validator (a refusal
+ * is the `JC2050` outcome — nothing is posted), posts one request frame,
+ * and resolves a D6 outcome for every way a channel can answer: the
+ * matching response (success validated against the output schema,
+ * `JC2053`; a declared or taxonomy error a `failure` with `status:
+ * null`; a served-host fault `kind: "contract"` with the server's
+ * `JC2070`/`JC2071` code kept), no answer within `timeoutMs` (`JC2072`,
+ * network), a malformed response frame (`JC2073`, contract), a channel
+ * whose `postMessage` throws (`JC2074`, network), and a caller abort
+ * (`cancelled` — a cancel frame is also posted so the server can stop
+ * work; the id scoping is the guarantee, so a late response for a
+ * cancelled or timed-out id is dropped silently).
+ *
+ * Request ids are `"<clientId>:<seq>"` with a UUID client id, and every
+ * incoming frame is prefix-tested against `clientId + ":"` BEFORE any
+ * map lookup — two clients on one shared channel can never cross-settle,
+ * whatever the other one sends. `close()` rejects nothing: pending
+ * invokes resolve `cancelled` and the listener is removed (the channel
+ * itself is the host's to close).
+ */
+import { PORT_LOCAL_ERRORS } from '../pipeline.js';
+export { PORT_LOCAL_ERRORS };
+export type Contract = import('../compile.js').Contract;
+export type CompiledOperation = import('../compile.js').CompiledOperation;
+export type Catalog = import('../http/wire.js').Catalog;
+export type Outcome = import('../client/outcome.js').Outcome;
+export type OutcomeMeta = import('../client/outcome.js').OutcomeMeta;
+export type OutcomeRoute = import('../client/outcome.js').OutcomeRoute;
+export type ChannelLike = import('./frame.js').ChannelLike;
+export type PortClientOptions = {
+    /**
+     * - the channel to talk over (required)
+     */
+    channel: ChannelLike;
+    /**
+     * - per request; default 15000; `0` disables
+     */
+    timeoutMs?: number;
+    /**
+     * - a message catalog consulted before the English one
+     */
+    catalog?: Record<string, string | ((params: object) => string)>;
+};
+export type PortInvokeContext = {
+    /**
+     * - resolves the outcome `cancelled` and posts a cancel frame
+     */
+    signal?: AbortSignal;
+    /**
+     * - the caller's attempt id, echoed in `meta.attempt`, never sent
+     */
+    attempt?: unknown;
+};
+export type PortClientCapabilities = {
+    name: 'port';
+    status: false;
+    headers: false;
+    media: false;
+    etag: false;
+    idempotency: false;
+    /**
+     * - `subscribe` carries push-frame streams (docs/CONTRACT-FORMAT.md §18.2)
+     */
+    stream: true;
+    cancel: 'message';
+};
+export type PortSubscribeOptions = {
+    onSnapshot?: (value: unknown, info: {
+        seq: number;
+        resumed: boolean;
+    }) => void;
+    onPatch?: (emission: {
+        patch: unknown[];
+        seq: number;
+    }) => void;
+    onError?: (outcome: Outcome) => void;
+    onEnd?: (info: {
+        reason: string;
+    }) => void;
+    /**
+     * - stops the subscription silently
+     */
+    signal?: AbortSignal;
+    /**
+     * - the resume seq (what a reconnect passes)
+     */
+    lastSeq?: number;
+};
+export type PortClient = {
+    invoke: (op: string, input?: unknown, ctx?: PortInvokeContext) => Promise<Outcome>;
+    subscribe: (op: string, input?: unknown, options?: PortSubscribeOptions) => {
+        stop: () => void;
+    };
+    capabilities: PortClientCapabilities;
+    contract: Contract;
+    describe: () => any;
+    close: () => void;
+};
+export type PortRoute = {
+    op: CompiledOperation;
+    raw: boolean;
+    hasInput: boolean;
+    validateInput: ((value: unknown) => any) | null;
+    details: 'none' | 'paths' | 'full';
+    outcome: OutcomeRoute;
+};
+export type Pending = {
+    resolve: (outcome: Outcome) => void;
+    route: PortRoute;
+    meta: OutcomeMeta;
+    timer: ReturnType<typeof setTimeout> | 0;
+    /**
+     * - removes the abort listener
+     */
+    cleanup: () => void;
+};
+/**
+ * One pending request: what the listener needs to settle it.
+ * @typedef {Object} Pending
+ * @property {(outcome: Outcome) => void} resolve
+ * @property {PortRoute} route
+ * @property {OutcomeMeta} meta
+ * @property {ReturnType<typeof setTimeout> | 0} timer
+ * @property {() => void} cleanup - removes the abort listener
+ */
+/**
+ * Open a port client over a compiled contract.
+ *
+ * @param {Contract} contract
+ * @param {PortClientOptions} options
+ * @returns {PortClient}
+ * @throws {ContractHostError} `JC1008` for a malformed argument or option
+ * @example
+ * const worker = new Worker(new URL('./owner.js', import.meta.url), { type: 'module' });
+ * const client = openPortClient(contract, { channel: worker });
+ * const outcome = await client.invoke('data.rows', { collection: 'notes' });
+ * if (outcome.ok) render(outcome.value);          // outcome.error.status is null on this binding
+ */
+export declare function openPortClient(contract: Contract, options: PortClientOptions): PortClient;