@jarenjs/contract 0.43.1

package/src/ledger.js

@@ -0,0 +1,225 @@
+//@ts-check
+/**
+ * @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.
+ */
+
+/**
+ * The record a ledger keeps per `(op, scope, key)`; the schema of
+ * `idempotencyLedgerModel`'s collection.
+ * @typedef {Object} LedgerRecord
+ * @property {string} id - `"<op>|<scope>|<key>"`
+ * @property {string} op
+ * @property {string} scope
+ * @property {string} key
+ * @property {string} hash - lowercase hex SHA-256 over the canonical input
+ * @property {'started' | 'committed' | 'failed'} status
+ * @property {any} response - the stored `{ status, headers, body }`, or null
+ * @property {boolean | null} retryable - of a failed record; null otherwise
+ * @property {number} createdAt - epoch ms
+ * @property {number} updatedAt - epoch ms
+ * @property {number} expiresAt - epoch ms
+ */
+
+/**
+ * The claim result: `new` hands back a `ref` to commit or fail; `replay`
+ * carries the stored response; `in-progress` and `mismatch` are the two
+ * 409 answers.
+ * @typedef {{ state: 'new', ref: unknown }
+ *   | { state: 'replay', response: any }
+ *   | { state: 'in-progress' }
+ *   | { state: 'mismatch' }} ClaimResult
+ */
+
+/**
+ * The ledger interface the http binding calls. Every method may return
+ * its value or a promise of it — the binding composes with `chain`, so a
+ * synchronous ledger costs no promise. Semantics the binding relies on:
+ * same key + same hash → `replay` of the stored response; same key +
+ * different hash → `mismatch`; `started` and unexpired → `in-progress`;
+ * `failed` with `retryable: true` → `new` (the key may be retried);
+ * `failed` and not retryable → `replay` of the stored failure. `now` on
+ * a claim is the binding's clock (epoch ms) a ledger may prefer to its
+ * own.
+ * @typedef {Object} Ledger
+ * @property {(claim: { op: string, scope: string, key: string, hash: string, now?: number }) => ClaimResult | Promise<ClaimResult>} claim
+ * @property {(ref: unknown, response: any) => void | Promise<void>} commit
+ * @property {(ref: unknown, retryable: boolean, response?: any) => void | Promise<void>} fail
+ * @property {(key: { op: string, scope: string, key: string }) => LedgerRecord | null | Promise<LedgerRecord | null>} lookup
+ */
+
+/** One day, the default retention of a key. */
+const DEFAULT_TTL_MS = 86_400_000;
+
+/**
+ * @param {string} op
+ * @param {string} scope
+ * @param {string} key
+ * @returns {string}
+ */
+function idOf(op, scope, key) {
+  return `${op}|${scope}|${key}`;
+}
+
+/**
+ * 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 function createMemoryLedger(options = {}) {
+  const ttlMs = options.ttlMs === undefined ? DEFAULT_TTL_MS : options.ttlMs;
+  if (!Number.isFinite(ttlMs) || ttlMs <= 0) throw new TypeError('createMemoryLedger: ttlMs must be a positive number');
+  const clock = options.now === undefined ? Date.now : options.now;
+  if (typeof clock !== 'function') throw new TypeError('createMemoryLedger: now must be a function');
+  /** @type {Map<string, LedgerRecord>} */
+  const records = new Map();
+
+  return {
+    claim({ op, scope, key, hash, now }) {
+      const at = typeof now === 'number' ? now : clock();
+      const id = idOf(op, scope, key);
+      const existing = records.get(id);
+      if (existing !== undefined) {
+        if (existing.expiresAt <= at) records.delete(id);
+        else if (existing.hash !== hash) return { state: 'mismatch' };
+        else if (existing.status === 'started') return { state: 'in-progress' };
+        else if (existing.status === 'committed') return { state: 'replay', response: existing.response };
+        else if (existing.retryable !== true && existing.response !== null) return { state: 'replay', response: existing.response };
+        else records.delete(id);
+      }
+      /** @type {LedgerRecord} */
+      const record = {
+        id, op, scope, key, hash, status: 'started', response: null, retryable: null,
+        createdAt: at, updatedAt: at, expiresAt: at + ttlMs,
+      };
+      records.set(id, record);
+      return { state: 'new', ref: record };
+    },
+    commit(ref, response) {
+      const record = /** @type {LedgerRecord} */ (ref);
+      if (records.get(record.id) !== record) return;
+      record.status = 'committed';
+      record.response = response;
+      record.retryable = null;
+      record.updatedAt = clock();
+    },
+    fail(ref, retryable, response) {
+      const record = /** @type {LedgerRecord} */ (ref);
+      if (records.get(record.id) !== record) return;
+      record.status = 'failed';
+      record.retryable = retryable === true;
+      record.response = response === undefined ? null : response;
+      record.updatedAt = clock();
+    },
+    lookup({ op, scope, key }) {
+      const record = records.get(idOf(op, scope, key));
+      if (record === undefined) return null;
+      if (record.expiresAt <= clock()) {
+        records.delete(record.id);
+        return null;
+      }
+      return record;
+    },
+    sweep() {
+      const at = clock();
+      let dropped = 0;
+      for (const [id, record] of records) {
+        if (record.expiresAt <= at) {
+          records.delete(id);
+          dropped++;
+        }
+      }
+      return dropped;
+    },
+    get size() {
+      return records.size;
+    },
+  };
+}
+
+/**
+ * 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 const idempotencyLedgerModel = Object.freeze({
+  $model: '0.1',
+  collections: {
+    ledger: {
+      schema: {
+        type: 'object',
+        required: ['id', 'op', 'scope', 'key', 'hash', 'status', 'response', 'retryable', 'createdAt', 'updatedAt', 'expiresAt'],
+        properties: {
+          id: { type: 'string', minLength: 1 },
+          op: { type: 'string', minLength: 1 },
+          scope: { type: 'string' },
+          key: { type: 'string', minLength: 1 },
+          hash: { type: 'string', pattern: '^[0-9a-f]{64}$' },
+          status: { type: 'string', enum: ['started', 'committed', 'failed'] },
+          response: {
+            oneOf: [
+              { type: 'null' },
+              {
+                type: 'object',
+                required: ['status', 'headers', 'body'],
+                properties: {
+                  status: { type: 'integer', minimum: 100, maximum: 599 },
+                  headers: { type: 'object', additionalProperties: { type: 'string' } },
+                  body: { type: ['string', 'null'] },
+                },
+              },
+            ],
+          },
+          retryable: { type: ['boolean', 'null'] },
+          createdAt: { type: 'integer' },
+          updatedAt: { type: 'integer' },
+          expiresAt: { type: 'integer' },
+        },
+        additionalProperties: false,
+      },
+      key: '/id',
+      indexes: [
+        { name: 'by_expires', path: '$.expiresAt' },
+        { name: 'by_status', path: '$.status' },
+      ],
+    },
+  },
+});
+
+/**
+ * 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 const commandLifecycleFsm = Object.freeze({
+  $fsm: '0.1',
+  initial: 'idle',
+  states: ['idle', 'started', { id: 'committed', final: true }, 'failed'],
+  transitions: [
+    { from: 'idle', event: 'claim', to: 'started' },
+    { from: 'started', event: 'commit', to: 'committed' },
+    { from: 'started', event: 'fail', to: 'failed' },
+    { from: 'failed', event: 'claim', guard: '$.context.retryable', to: 'started' },
+  ],
+});

package/src/local/index.js

@@ -0,0 +1,363 @@
+//@ts-check
+/**
+ * @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 { compileMessageCatalog } from '@jarenjs/core/message';
+
+import { ContractHostError, ContractFailure } from '../errors.js';
+import { validateOperationInput, settleOperation, safeTrace, PORT_LOCAL_ERRORS } from '../pipeline.js';
+import { renderMessage, declaredMessage } from '../http/wire.js';
+import {
+  prepareOutcomeRoute, assembleOutcome, makeMeta, failedOutcome, outcomeError, clientError,
+} from '../client/outcome.js';
+
+export { PORT_LOCAL_ERRORS };
+
+/**
+ * @typedef {import('../compile.js').Contract} Contract
+ * @typedef {import('../compile.js').CompiledOperation} CompiledOperation
+ * @typedef {import('../http/wire.js').Catalog} Catalog
+ * @typedef {import('../http/dispatch.js').Handler} Handler
+ * @typedef {import('../client/outcome.js').Outcome} Outcome
+ * @typedef {import('../client/outcome.js').OutcomeMeta} OutcomeMeta
+ * @typedef {import('../pipeline.js').PipelineRoute} PipelineRoute
+ */
+
+/**
+ * @typedef {Object} LocalOptions
+ * @property {() => string} [trace] - the trace generator; default `crypto.randomUUID`
+ * @property {'always' | 'never'} [validateOutput] - `'never'` is a declared
+ *   downgrade, reported in `capabilities.validatedOutput`
+ * @property {Record<string, string | ((params: object) => string)>} [catalog]
+ *   - a message catalog consulted before the English one
+ * @property {(error: unknown, ctx: { op: string, trace: string } | null) => void} [onError]
+ *   - observes the cause behind every `JC2070` outcome and validator throw
+ */
+
+/**
+ * Per-call context of `invoke` — the client half's, not the handler's.
+ * @typedef {Object} LocalInvokeContext
+ * @property {AbortSignal} [signal] - resolves the outcome `cancelled`
+ * @property {unknown} [attempt] - the caller's attempt id, echoed in `meta.attempt`
+ */
+
+/**
+ * The frozen capabilities table of the local binding: no wire, so no
+ * statuses, headers, media, entity tags or idempotency carriage — a
+ * contract declaring them still serves (the declarations describe its
+ * HTTP life), and this table is how a consumer knows they are inert here.
+ * @typedef {Object} LocalCapabilities
+ * @property {'local'} name
+ * @property {false} status
+ * @property {false} headers
+ * @property {false} media
+ * @property {false} etag
+ * @property {false} idempotency
+ * @property {boolean} validatedOutput - the output validator runs
+ * @property {false} stream
+ * @property {'signal'} cancel
+ */
+
+/**
+ * The local client — client and server in one object.
+ * @typedef {Object} LocalClient
+ * @property {(op: string, input?: unknown, ctx?: LocalInvokeContext) => Promise<Outcome>} invoke
+ * @property {LocalCapabilities} capabilities
+ * @property {Contract} contract
+ * @property {() => any} describe
+ * @property {() => void} close - later invokes resolve `cancelled`; running handlers see their signal abort
+ */
+
+/** The frozen empty header table every local handler context carries. */
+const NO_HEADERS = Object.freeze({});
+
+/** The sentinel `race` resolves when the signal wins. */
+const ABORTED = Symbol('aborted');
+
+/**
+ * @param {string} code
+ * @param {string} reason
+ * @returns {ContractHostError}
+ */
+function host(code, reason) {
+  return new ContractHostError(code, `serveLocal: ${reason}`);
+}
+
+/**
+ * One operation as this binding prepared it: the pipeline's subset plus
+ * the outcome assembly. The outcome route's output validator is a
+ * pass-through — the pipeline already validated (or the host declared
+ * `validateOutput: 'never'`), and one validation per invoke is the point
+ * of having no wire.
+ * @typedef {PipelineRoute & { hasInput: boolean, outcome: import('../client/outcome.js').OutcomeRoute }} LocalRoute
+ */
+
+/**
+ * @param {CompiledOperation} op
+ * @param {Handler | null} handler
+ * @returns {LocalRoute}
+ */
+function prepare(op, handler) {
+  return Object.freeze({
+    op,
+    handler,
+    raw: op.http.opaque,
+    validateInput: op.input === null ? null : op.input.validate,
+    validateOutput: op.output.validate,
+    details: op.policy.errors.details,
+    errors: op.errors,
+    retryOn: new Set(op.policy.retry === null ? [] : op.policy.retry.on),
+    hasInput: op.input !== null,
+    outcome: Object.freeze({ ...prepareOutcomeRoute(op), validateOutput: () => true }),
+  });
+}
+
+/**
+ * Race the pipeline's settlement against the abort signal: the first
+ * one wins, and a handler that settles after the abort settles into
+ * nothing (the state-side id guard is the caller's guarantee; this is
+ * the honest local reading of "the request was cancelled").
+ * @param {Promise<import('../pipeline.js').OperationResult>} settled
+ * @param {AbortSignal} signal
+ * @returns {Promise<import('../pipeline.js').OperationResult | typeof ABORTED>}
+ */
+function race(settled, signal) {
+  return new Promise((resolve) => {
+    const onAbort = () => resolve(ABORTED);
+    signal.addEventListener('abort', onAbort, { once: true });
+    settled.then((result) => {
+      signal.removeEventListener('abort', onAbort);
+      resolve(result);
+    });
+  });
+}
+
+/**
+ * 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 function openLocalClient(contract, handlers, options = {}) {
+  if (contract === null || typeof contract !== 'object' || typeof contract.match !== 'function'
+    || contract.operations === null || typeof contract.operations !== 'object' || !Array.isArray(contract.ids)) {
+    throw host('JC1001', 'the first argument must be a compiled contract (compileContract)');
+  }
+  if (handlers === null || typeof handlers !== 'object' || Array.isArray(handlers)) {
+    throw host('JC1001', 'handlers must be an object of operation id → function');
+  }
+  const names = Object.keys(handlers);
+  for (let i = 0; i < names.length; i++) {
+    const id = names[i];
+    if (!Object.hasOwn(contract.operations, id)) {
+      throw host('JC1001', `handlers names '${id}', which is not an operation of the contract`);
+    }
+    if (typeof handlers[id] !== 'function') {
+      throw host('JC1001', `the handler of '${id}' must be a function, got ${typeof handlers[id]}`);
+    }
+  }
+  if (options === null || typeof options !== 'object') throw host('JC1001', 'options must be an object');
+  const validateOutput = options.validateOutput === undefined ? 'always' : options.validateOutput;
+  if (validateOutput !== 'always' && validateOutput !== 'never') {
+    throw host('JC1001', "options.validateOutput must be 'always' or 'never'");
+  }
+  for (const [name, value] of [['trace', options.trace], ['onError', options.onError]]) {
+    if (value !== undefined && typeof value !== 'function') throw host('JC1001', `options.${name} must be a function`);
+  }
+  if (options.catalog !== undefined && (options.catalog === null || typeof options.catalog !== 'object')) {
+    throw host('JC1001', 'options.catalog must be a message catalog object');
+  }
+  const trace = options.trace === undefined ? () => globalThis.crypto.randomUUID() : options.trace;
+  const onError = options.onError === undefined ? null : options.onError;
+  /** @type {Catalog | null} */
+  const catalog = options.catalog === undefined ? null : compileMessageCatalog(options.catalog);
+  const validate = validateOutput === 'always';
+
+  /** @type {Map<string, LocalRoute>} */
+  const routes = new Map();
+  for (let i = 0; i < contract.ids.length; i++) {
+    const id = contract.ids[i];
+    const op = contract.operations[id];
+    const handler = Object.hasOwn(handlers, id) ? handlers[id] : null;
+    // an opaque operation cannot be invoked here, and a subscribe
+    // operation cannot be streamed here (capabilities.stream is false) —
+    // neither demands a handler, so an HTTP handler table reuses verbatim
+    if (handler === null && !op.http.opaque && op.kind !== 'subscribe') {
+      throw host('JC1002', `operation '${id}' has no handler`);
+    }
+    routes.set(id, prepare(op, handler));
+  }
+
+  const closer = new AbortController();
+  let closed = false;
+
+  /**
+   * Report a fault to the host observer. TOTAL.
+   * @param {unknown} error
+   * @param {{ op: string, trace: string } | null} ctx
+   */
+  function observe(error, ctx) {
+    if (onError === null) return;
+    try {
+      onError(error, ctx);
+    }
+    catch {
+      // an observer that throws never reaches the outcome
+    }
+  }
+
+  /**
+   * @param {LocalRoute} route
+   * @param {OutcomeMeta} meta
+   * @returns {Outcome}
+   */
+  function cancelled(route, meta) {
+    return failedOutcome('cancelled', clientError(catalog, 'JC2052', { op: route.outcome.id }, null, undefined), meta);
+  }
+
+  /**
+   * @param {string} op
+   * @param {unknown} [input]
+   * @param {LocalInvokeContext} [ctx]
+   * @returns {Promise<Outcome>}
+   */
+  async function invoke(op, input, ctx = {}) {
+    const route = routes.get(op);
+    if (route === undefined) {
+      throw new ContractHostError('JC1005', `client: '${String(op)}' is not an operation of the contract`);
+    }
+    if (route.raw) {
+      throw new ContractHostError('JC1005', `client: '${route.outcome.id}' is an opaque operation (media ${route.op.http.media}); the local binding carries JSON only (capabilities.media is false)`);
+    }
+    if (route.op.kind === 'subscribe') {
+      throw new ContractHostError('JC1005', `client: '${route.outcome.id}' is a subscribe operation; the local binding cannot carry a stream (capabilities.stream is false)`);
+    }
+    if (ctx === null || typeof ctx !== 'object') throw host('JC1001', 'ctx must be an object');
+    const meta = makeMeta(route.outcome.id, ctx.attempt, null);
+    const caller = ctx.signal === undefined || ctx.signal === null ? null : ctx.signal;
+    if ((caller !== null && caller.aborted) || closed) return cancelled(route, meta);
+
+    // 1. validate — the same verdict the pipeline would reach, once
+    let value;
+    if (!route.hasInput) {
+      if (input !== undefined && input !== null) {
+        return failedOutcome('contract', clientError(catalog, 'JC2050', { op: route.outcome.id }, null,
+          [{ path: '', keyword: 'input' }]), meta);
+      }
+      value = null;
+    }
+    else {
+      value = input === undefined || input === null ? {} : input;
+      const invalid = validateOperationInput(route, value);
+      if (invalid !== null && invalid.kind === 'contract') {
+        if (invalid.cause !== undefined) observe(invalid.cause, null);
+        return failedOutcome('contract', clientError(catalog, 'JC2050', { op: route.outcome.id }, null, invalid.details), meta);
+      }
+    }
+
+    // 2. run the neutral pipeline under the composed signal
+    const signal = caller === null ? closer.signal : AbortSignal.any([closer.signal, caller]);
+    const id = safeTrace(trace);
+    meta.trace = id;
+    const handlerCtx = Object.freeze({
+      op: route.op, trace: id, signal, params: null, headers: NO_HEADERS,
+      fail: ContractFailure, idempotency: null,
+    });
+    const result = await race(settleOperation(route, value, handlerCtx, validate), signal);
+    if (result === ABORTED) return cancelled(route, meta);
+
+    // 3. assemble the D6 outcome
+    if (result.kind === 'contract') {
+      if (result.cause !== undefined) observe(result.cause, { op: route.outcome.id, trace: id });
+      return failedOutcome('contract', outcomeError('JC2070',
+        renderMessage(catalog, PORT_LOCAL_ERRORS.JC2070.msgid, { op: route.outcome.id }), null, null, false), meta);
+    }
+    if (result.kind === 'failure') {
+      return assembleOutcome(route.outcome, {
+        status: null,
+        headers: null,
+        error: {
+          code: result.code,
+          message: declaredMessage(catalog, route.outcome.id, result.code, result.params),
+          details: result.details,
+          retryable: result.retryable,
+        },
+      }, meta, catalog);
+    }
+    return assembleOutcome(route.outcome, { status: null, headers: null, value: result.value }, meta, catalog);
+  }
+
+  /** @type {LocalCapabilities} */
+  const capabilities = Object.freeze({
+    name: 'local',
+    status: false,
+    headers: false,
+    media: false,
+    etag: false,
+    idempotency: false,
+    validatedOutput: validate,
+    stream: false,
+    cancel: 'signal',
+  });
+
+  return Object.freeze({
+    invoke,
+    capabilities,
+    contract,
+    describe: () => contract.describe(),
+    close: () => {
+      closed = true;
+      closer.abort();
+    },
+  });
+}
+
+/**
+ * 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 const serveLocal = openLocalClient;

package/src/messages.js

@@ -0,0 +1,68 @@
+//@ts-check
+/**
+ * @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).
+ */
+
+import { compileMessageCatalog } from '@jarenjs/core/message';
+
+/**
+ * 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 const contractMessagesEn = Object.freeze({
+  '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 const contractCatalogEn = compileMessageCatalog(contractMessagesEn);