@jarenjs/contract 0.56.0 → 0.66.1

package/src/pipeline.js

@@ -89,7 +89,12 @@ function contractResult(code, details, cause) {
 
 /**
  * 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.
+ * throws or answers a non-string is replaced by the platform's UUID —
+ * the one last-resort platform read in this package, reached only when
+ * the injected generator (a `trace` option or the runtime record's
+ * `uuid`) has itself failed, so a request still carries a trace; a run
+ * whose generator fails was not the deterministic run the record
+ * configures, and the fallback says nothing about it.
  * @param {() => string} trace
  * @returns {string}
  */
@@ -161,6 +166,18 @@ function declaredResult(route, code, params, details, retryable) {
   };
 }
 
+/**
+ * Classify a declared failure a HOST hook answered (`identify`/`acquire`,
+ * docs/CONTRACT-FORMAT.md §7.7): the same rules as a handler's `ctx.fail`
+ * — the code must be declared, the details must pass the declaration.
+ * @param {PipelineRoute} route
+ * @param {import('./errors.js').ContractFailureValue} failure
+ * @returns {OperationResult}
+ */
+export function classifyDeclared(route, failure) {
+  return declaredResult(route, failure.code, failure.params, failure.details, failure.retryable);
+}
+
 /**
  * Classify the handler's resolved value: a `ContractFailure` is a
  * declared failure; anything else is the output, validated unless the

package/src/port/client.js

@@ -24,6 +24,7 @@
  */
 
 import { compileMessageCatalog } from '@jarenjs/core/message';
+import { resolveHostRuntime } from '../runtime.js';
 
 import { ContractHostError } from '../errors.js';
 import { validateOperationInput, PORT_LOCAL_ERRORS } from '../pipeline.js';
@@ -52,6 +53,10 @@ export { PORT_LOCAL_ERRORS };
  * @property {number} [timeoutMs] - per request; default 15000; `0` disables
  * @property {Record<string, string | ((params: object) => string)>} [catalog]
  *   - a message catalog consulted before the English one
+ * @property {Partial<import('@jarenjs/core/runtime').Runtime>} [runtime]
+ *   - the host's runtime record: its `uuid` mints the client id every
+ *   request id of this client is prefixed with; `crypto.randomUUID` by
+ *   default
  */
 
 /**
@@ -79,12 +84,15 @@ export { PORT_LOCAL_ERRORS };
  * There is no heartbeat on a port — delivery is in-process — so no
  * silence watchdog runs here.
  * @typedef {Object} PortSubscribeOptions
- * @property {(value: unknown, info: { seq: number, resumed: boolean }) => void} [onSnapshot]
+ * @property {(value: unknown, info: { seq: number, resumed: boolean, reset: boolean, earliestAvailable: number | null, highWatermark: number | null }) => void} [onSnapshot]
  * @property {(emission: { patch: unknown[], seq: number }) => void} [onPatch]
  * @property {(outcome: Outcome) => void} [onError]
  * @property {(info: { reason: string }) => void} [onEnd]
  * @property {AbortSignal} [signal] - stops the subscription silently
- * @property {number} [lastSeq] - the resume seq (what a reconnect passes)
+ * @property {number} [lastSeq] - the resume seq (what a re-entered subscribe passes)
+ * @property {{ max: number }} [reconnect] - validated as on the HTTP client, then
+ *   nothing: a channel has no network loss to reconnect from (a closed channel is
+ *   `JC2074`, final), so the same options object serves both clients
  */
 
 /**
@@ -186,7 +194,19 @@ export function openPortClient(contract, options) {
     routes.set(id, prepare(contract.operations[id]));
   }
 
-  const clientId = globalThis.crypto.randomUUID();
+  const runtime = resolveHostRuntime(options.runtime, host, 'JC1008');
+  // the record's generator is the host's; one that throws or answers no
+  // string is the host's own mistake, refused where it was passed
+  let clientId;
+  try {
+    clientId = runtime.uuid();
+  }
+  catch (error) {
+    throw host('JC1008', `options.runtime: uuid() threw (${error instanceof Error ? error.message : String(error)})`);
+  }
+  if (typeof clientId !== 'string' || clientId.length === 0) {
+    throw host('JC1008', 'options.runtime: uuid() must answer a non-empty string, the client id every request is prefixed with');
+  }
   const prefix = clientId + ':';
   let seq = 0;
   /** @type {Map<string, Pending>} */
@@ -412,6 +432,12 @@ export function openPortClient(contract, options) {
       if (!Number.isInteger(options.lastSeq) || options.lastSeq < 0) throw host('JC1008', 'options.lastSeq must be a non-negative integer');
       lastSeq = options.lastSeq;
     }
+    if (options.reconnect !== undefined && options.reconnect !== null) {
+      const r = /** @type {any} */ (options.reconnect);
+      if (typeof r !== 'object' || !Number.isInteger(r.max) || r.max < 0) {
+        throw host('JC1008', 'options.reconnect must be { max } with a non-negative integer number of further attempts');
+      }
+    }
     const signal = options.signal === undefined || options.signal === null ? null : options.signal;
     const meta = makeMeta(route.op.id, null, null);
     const id = prefix + (++seq);
@@ -442,10 +468,17 @@ export function openPortClient(contract, options) {
         }
       }
     };
+    /** @type {Subscription} */
+    const subscription = Object.freeze({
+      stop,
+      get lastSeq() {
+        return consumer.lastSeq();
+      },
+    });
 
     if (closed || (signal !== null && signal.aborted)) {
       queueMicrotask(() => consumer.cancel());
-      return { stop };
+      return subscription;
     }
 
     // validate before anything is posted — the shared pre-send refusal
@@ -463,7 +496,7 @@ export function openPortClient(contract, options) {
     if (refusal !== null) {
       const outcome = failedOutcome('contract', clientError(catalog, 'JC2050', { op: route.op.id }, null, refusal), meta);
       queueMicrotask(() => consumer.fail(outcome));
-      return { stop };
+      return subscription;
     }
 
     streams.set(id, consumer);
@@ -479,7 +512,7 @@ export function openPortClient(contract, options) {
       const outcome = bindingOutcome('network', 'JC2074', { op: route.op.id }, meta);
       queueMicrotask(() => consumer.fail(outcome));
     }
-    return { stop };
+    return subscription;
   }
 
   /** @type {PortClientCapabilities} */

package/src/port/serve.js

@@ -23,8 +23,10 @@
 import { compileMessageCatalog } from '@jarenjs/core/message';
 
 import { ContractHostError, ContractFailure } from '../errors.js';
-import { validateOperationInput, settleOperation, safeTrace, PORT_LOCAL_ERRORS } from '../pipeline.js';
-import { isSubscriptionLike, runSubscription, STREAM_ERRORS } from '../stream/server.js';
+import { validateOperationInput, settleOperation, safeTrace, PORT_LOCAL_ERRORS, classifyDeclared } from '../pipeline.js';
+import { resolveLifecycle, identify as identifyHost, acquire as acquireHost, once, RollbackCarrier } from '../host.js';
+import { resolveHostRuntime } from '../runtime.js';
+import { isSubscriptionLike, runSubscription, resolveStreamLimits, STREAM_ERRORS } from '../stream/server.js';
 import { HTTP_ERRORS, renderMessage, declaredMessage } from '../http/wire.js';
 import { isContractFrame, valueFrame, errorFrame, pushFrame, attach, isChannel } from './frame.js';
 
@@ -44,14 +46,32 @@ export { PORT_LOCAL_ERRORS };
 /**
  * @typedef {Object} ServePortOptions
  * @property {ChannelLike} channel - the channel to serve (required)
- * @property {() => string} [trace] - the server trace generator; default `crypto.randomUUID`
+ * @property {() => string} [trace] - the server trace generator; default
+ *   the runtime record's `uuid`, itself `crypto.randomUUID` by default
  * @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]
+ * @property {(meta: import('../host.js').IdentifyMeta) => unknown} [identify]
+ *   - the host lifecycle's first hook (docs/CONTRACT-FORMAT.md §7.7), run
+ *   after the operation resolved and before the input is validated;
+ *   `meta.carrier` is `'port'` and the request-line members are `null`
+ * @property {(input: unknown, identity: unknown, enter: (lease: unknown) => Promise<unknown>) => unknown} [acquire]
+ *   - the second hook, run after the input validated; a `settlement` on
+ *   its lease is accepted and unused — this binding carries no
+ *   idempotency
  *   - observes the cause behind every `JC2070` frame, validator throws
  *   and a channel whose `postMessage` throws
+ * @property {Partial<import('@jarenjs/core/runtime').Runtime>} [runtime]
+ *   - the host's runtime record: its `uuid` generates the server trace
+ *   where `trace` is absent
+ * @property {{ replay?: { limit?: number, maxBytes?: number }, queue?: { events?: number, bytes?: number } }} [streamLimits]
+ *   - the bounds of every push-frame stream (docs/CONTRACT-FORMAT.md
+ *   §18.1): a replay page asks for at most `replay.limit` emissions /
+ *   `replay.maxBytes` patch bytes (default 256 / 1 MiB); the undelivered
+ *   queue holds at most `queue.events` frames / `queue.bytes` frame
+ *   bytes (default 256 / 1 MiB) before the stream ends with `JC2096`
  */
 
 /**
@@ -169,7 +189,10 @@ export function servePort(contract, handlers, options) {
   if (options.catalog !== undefined && (options.catalog === null || typeof options.catalog !== 'object')) {
     throw host('JC1001', 'options.catalog must be a message catalog object');
   }
-  const traceGen = options.trace === undefined ? () => globalThis.crypto.randomUUID() : options.trace;
+  const runtime = resolveHostRuntime(options.runtime, host, 'JC1001');
+  const streamLimits = resolveStreamLimits(options.streamLimits, (reason) => host('JC1001', reason));
+  const lifecycle = resolveLifecycle(options, (reason) => host('JC1001', reason));
+  const traceGen = options.trace === undefined ? runtime.uuid : options.trace;
   const onError = options.onError === undefined ? null : options.onError;
   /** @type {Catalog | null} */
   const catalog = options.catalog === undefined ? null : compileMessageCatalog(options.catalog);
@@ -191,6 +214,77 @@ export function servePort(contract, handlers, options) {
   const active = new Map();
   let closed = false;
 
+  /**
+   * The frozen context of one request or subscription on this carrier:
+   * the request-line members are `null` here, `etag`/`status` are not
+   * callable, and `host` is the identity's until `acquire` entered.
+   * @param {PortRoute} route
+   * @param {string} trace
+   * @param {AbortSignal} signal
+   * @param {unknown} hostValue
+   */
+  const contextOf = (route, trace, signal, hostValue) => Object.freeze({
+    op: route.op, trace, carrier: /** @type {const} */ ('port'), host: hostValue, signal,
+    method: null, path: null, params: null, headers: NO_HEADERS, body: null,
+    fail: ContractFailure, idempotency: null, etag: null, status: null,
+  });
+
+  /**
+   * Run the host lifecycle around a served request or subscription:
+   * identify before validation, the validation itself (`validate`),
+   * acquire after it, then `enter` with the handler's context. Every
+   * fault of a hook is the binding's host fault (`JC2070`); a declared
+   * failure is classified like a handler's. The answer is what `enter`
+   * (or a refusal) produced, plus the releases the caller runs at its
+   * own boundary.
+   * @param {PortRoute} route
+   * @param {string} trace
+   * @param {AbortSignal} signal
+   * @param {unknown} value - the input as the frame carried it
+   * @param {(error: unknown) => void} observed
+   * @param {(code: 'JC2006' | 'JC2070', details: unknown, cause: unknown) => void} refuse - a pre-handler refusal
+   * @param {(result: import('../pipeline.js').OperationResult) => void} failed - a declared failure of a hook
+   * @param {(hctx: any) => Promise<unknown>} enter
+   * @returns {Promise<{ entered: boolean, value: unknown, release: () => Promise<boolean> }>}
+   */
+  async function lifecycleAround(route, trace, signal, value, observed, refuse, failed, enter) {
+    const meta = Object.freeze({ op: route.op, trace, signal, carrier: /** @type {const} */ ('port'), method: null, path: null, headers: null, fail: ContractFailure });
+    const identified = await identifyHost(lifecycle, meta);
+    const none = () => Promise.resolve(true);
+    if (identified.kind === 'fault') {
+      refuse('JC2070', undefined, identified.cause);
+      return { entered: false, value: undefined, release: none };
+    }
+    if (identified.kind === 'failure') {
+      failed(classifyDeclared(route, identified.failure));
+      return { entered: false, value: undefined, release: none };
+    }
+    const identity = once(identified.lease.release, observed);
+    /** @type {(() => Promise<boolean>) | null} */
+    let acquired = null;
+    const release = () => (acquired === null ? identity() : acquired().then((a) => identity().then((b) => a && b)));
+    const invalid = validateOperationInput(route, value);
+    if (invalid !== null && invalid.kind === 'contract') {
+      refuse('JC2006', invalid.details, invalid.cause);
+      return { entered: false, value: undefined, release };
+    }
+    const ictx = contextOf(route, trace, signal, identified.lease.host);
+    const out = await acquireHost(lifecycle, value, ictx, (lease) => {
+      acquired = once(lease.release, observed);
+      return enter(Object.freeze({ ...ictx, host: lease.host }));
+    });
+    if (out.kind === 'fault') {
+      refuse('JC2070', undefined, out.cause);
+      return { entered: false, value: undefined, release };
+    }
+    if (out.kind === 'failure') {
+      failed(classifyDeclared(route, out.failure));
+      return { entered: false, value: undefined, release };
+    }
+    if (out.afterFault !== undefined) observed(out.afterFault);
+    return { entered: true, value: out.result, release };
+  }
+
   /**
    * @param {unknown} error
    * @param {{ op: string, trace: string } | null} ctx
@@ -238,37 +332,46 @@ export function servePort(contract, handlers, options) {
     }
     const opId = route.op.id;
     const value = route.validateInput === null ? null : input === undefined ? null : input;
-    const invalid = validateOperationInput(route, value);
-    if (invalid !== null && invalid.kind === 'contract') {
-      if (invalid.cause !== undefined) observe(invalid.cause, { op: opId, trace });
-      post(errorFrame(id, 'JC2006', renderMessage(catalog, HTTP_ERRORS.JC2006.msgid, { op: opId }),
-        invalid.details, false, trace), { op: opId, trace });
-      return;
-    }
     const controller = new AbortController();
     active.set(id, controller);
-    const ctx = Object.freeze({
-      op: route.op, trace, signal: controller.signal, params: null, headers: NO_HEADERS,
-      fail: ContractFailure, idempotency: null,
-    });
-    settleOperation(route, value, ctx, validate).then((result) => {
-      if (active.get(id) === controller) active.delete(id);
-      // a cancelled request's client is gone and drops late responses
-      // anyway; not answering just keeps the channel quiet
-      if (controller.signal.aborted || closed) return;
+    const pushCtx = { op: opId, trace };
+    /** @param {import('../pipeline.js').OperationResult} result */
+    const answer = (result) => {
       if (result.kind === 'value') {
-        post(valueFrame(id, result.value, trace), { op: opId, trace });
+        post(valueFrame(id, result.value, trace), pushCtx);
       }
       else if (result.kind === 'failure') {
         post(errorFrame(id, result.code, declaredMessage(catalog, opId, result.code, result.params),
-          result.details, result.retryable, trace), { op: opId, trace });
+          result.details, result.retryable, trace), pushCtx);
       }
       else {
-        if (result.cause !== undefined) observe(result.cause, { op: opId, trace });
+        if (result.cause !== undefined) observe(result.cause, pushCtx);
         post(errorFrame(id, 'JC2070', renderMessage(catalog, PORT_LOCAL_ERRORS.JC2070.msgid, { op: opId }),
-          undefined, false, trace), { op: opId, trace });
+          undefined, false, trace), pushCtx);
       }
-    });
+    };
+    lifecycleAround(route, trace, controller.signal, value,
+      (error) => observe(error, pushCtx),
+      (code, details, cause) => {
+        if (cause !== undefined) observe(cause, pushCtx);
+        post(errorFrame(id, code, renderMessage(catalog, code === 'JC2006' ? HTTP_ERRORS.JC2006.msgid : PORT_LOCAL_ERRORS.JC2070.msgid, { op: opId }),
+          details, false, trace), pushCtx);
+      },
+      answer,
+      // inside enter: the handler through the neutral pipeline; a host
+      // fault rejects enter with the rollback carrier so a transaction
+      // around it rolls back, the fault still the answer
+      (hctx) => settleOperation(route, value, hctx, validate).then((result) => {
+        if (result.kind === 'contract') throw new RollbackCarrier(result, result.cause);
+        return result;
+      }))
+      .then((run) => {
+        if (active.get(id) === controller) active.delete(id);
+        // a cancelled request's client is gone and drops late responses
+        // anyway; not answering just keeps the channel quiet
+        if (run.entered && !controller.signal.aborted && !closed) answer(/** @type {any} */ (run.value));
+        return run.release();
+      });
   }
 
   /**
@@ -314,67 +417,102 @@ export function servePort(contract, handlers, options) {
     }
     const opId = route.op.id;
     const value = route.validateInput === null ? null : input === undefined ? null : input;
-    const invalid = validateOperationInput(route, value);
-    if (invalid !== null && invalid.kind === 'contract') {
-      if (invalid.cause !== undefined) observe(invalid.cause, { op: opId, trace });
-      post(pushFrame(id, 'error', 0, wireError('JC2006', renderMessage(catalog, HTTP_ERRORS.JC2006.msgid, { op: opId }), trace, invalid.details, false)), { op: opId, trace });
-      return;
-    }
     const lastSeq = Number.isInteger(lastSeqRaw) && /** @type {number} */ (lastSeqRaw) >= 0 ? /** @type {number} */ (lastSeqRaw) : null;
     const entry = { stopped: false, stop: /** @type {(reason: string | null) => void} */ (() => { entry.stopped = true; }) };
     streams.set(id, entry);
     const controller = new AbortController();
-    const ctx = Object.freeze({
-      op: route.op, trace, signal: controller.signal, params: null, headers: NO_HEADERS,
-      fail: ContractFailure, idempotency: null,
-    });
     const pushCtx = { op: opId, trace };
-    settleOperation(route, value, ctx, false).then((result) => {
-      if (closed || entry.stopped) {
-        streams.delete(id);
-        // the settlement may still hold a live subscription — release it
-        if (result.kind === 'value' && isSubscriptionLike(result.value)) {
-          try {
-            result.value.close();
-          }
-          catch {
-            // a throwing close changes nothing for a gone client
-          }
-        }
-        return;
-      }
+    /** @param {import('../pipeline.js').OperationResult} result */
+    const preStream = (result) => {
+      streams.delete(id);
       if (result.kind === 'failure') {
-        streams.delete(id);
         post(pushFrame(id, 'error', 0, wireError(result.code, declaredMessage(catalog, opId, result.code, result.params), trace, result.details, result.retryable)), pushCtx);
         return;
       }
       if (result.kind === 'contract') {
-        streams.delete(id);
         if (result.cause !== undefined) observe(result.cause, pushCtx);
         post(pushFrame(id, 'error', 0, wireError('JC2070', renderMessage(catalog, PORT_LOCAL_ERRORS.JC2070.msgid, { op: opId }), trace, undefined, false)), pushCtx);
-        return;
       }
-      const sub = result.value;
-      if (!isSubscriptionLike(sub)) {
+    };
+    lifecycleAround(route, trace, controller.signal, value,
+      (error) => observe(error, pushCtx),
+      (code, details, cause) => {
         streams.delete(id);
-        observe(new TypeError(`the handler of subscribe operation '${opId}' did not answer a subscription ({ result | snapshot(), subscribe, close })`), pushCtx);
-        post(pushFrame(id, 'error', 0, wireError('JC2070', renderMessage(catalog, PORT_LOCAL_ERRORS.JC2070.msgid, { op: opId }), trace, undefined, false)), pushCtx);
-        return;
-      }
+        if (cause !== undefined) observe(cause, pushCtx);
+        post(pushFrame(id, 'error', 0, wireError(code, renderMessage(catalog, code === 'JC2006' ? HTTP_ERRORS.JC2006.msgid : PORT_LOCAL_ERRORS.JC2070.msgid, { op: opId }), trace, details, false)), pushCtx);
+      },
+      preStream,
+      (hctx) => settleOperation(route, value, hctx, false))
+      .then((run) => {
+        if (!run.entered) return run.release();
+        const result = /** @type {import('../pipeline.js').OperationResult} */ (run.value);
+        if (closed || entry.stopped) {
+          streams.delete(id);
+          // the settlement may still hold a live subscription — release it
+          if (result.kind === 'value' && isSubscriptionLike(result.value)) {
+            try {
+              result.value.close();
+            }
+            catch {
+              // a throwing close changes nothing for a gone client
+            }
+          }
+          return run.release();
+        }
+        if (result.kind !== 'value') {
+          preStream(result);
+          return run.release();
+        }
+        const sub = result.value;
+        if (!isSubscriptionLike(sub)) {
+          streams.delete(id);
+          observe(new TypeError(`the handler of subscribe operation '${opId}' did not answer a subscription ({ result | snapshot(), subscribe, close })`), pushCtx);
+          post(pushFrame(id, 'error', 0, wireError('JC2070', renderMessage(catalog, PORT_LOCAL_ERRORS.JC2070.msgid, { op: opId }), trace, undefined, false)), pushCtx);
+          return run.release();
+        }
+        return streamSubscription(id, route, sub, lastSeq, trace, pushCtx, entry, run.release);
+      });
+  }
+
+  /**
+   * The runner over a live subscription on this channel; the leases are
+   * released after the runner's stop/close/done sequence.
+   * @param {string} id
+   * @param {PortRoute} route
+   * @param {any} sub
+   * @param {number | null} lastSeq
+   * @param {string} trace
+   * @param {{ op: string, trace: string }} pushCtx
+   * @param {{ stopped: boolean, stop: (reason: string | null) => void }} entry
+   * @param {() => Promise<boolean>} release
+   */
+  function streamSubscription(id, route, sub, lastSeq, trace, pushCtx, entry, release) {
+    const opId = route.op.id;
+    {
       const runner = runSubscription(route, sub, {
-        snapshot: (seq, snapValue, resumed) => post(pushFrame(id, 'snapshot', seq, { value: snapValue, resumed }), pushCtx),
-        patch: (seq, emission) => post(pushFrame(id, 'patch', seq, emission), pushCtx),
-        error: (intent, cause, seq) => {
-          observe(cause, pushCtx);
-          const code = intent === 'invalid-snapshot' ? 'JC2091' : 'JC2070';
-          const msgid = intent === 'invalid-snapshot' ? STREAM_ERRORS.JC2091.msgid : PORT_LOCAL_ERRORS.JC2070.msgid;
-          post(pushFrame(id, 'error', seq, wireError(code, renderMessage(catalog, msgid, { op: opId }), trace, undefined, false)), pushCtx);
+        snapshot: (seq, data) => pushFrame(id, 'snapshot', seq, data),
+        patch: (seq, emission) => pushFrame(id, 'patch', seq, emission),
+        error: (intent, cause, seq, declared) => {
+          if (intent !== 'slow-consumer') observe(cause, pushCtx);
+          if (intent === 'declared' && declared !== null) {
+            return pushFrame(id, 'error', seq, wireError(declared.code, declaredMessage(catalog, opId, declared.code, {}), trace, declared.details, declared.retryable));
+          }
+          const code = intent === 'invalid-snapshot' ? 'JC2091' : intent === 'slow-consumer' ? 'JC2096' : 'JC2070';
+          const row = intent === 'invalid-snapshot' ? STREAM_ERRORS.JC2091
+            : intent === 'slow-consumer' ? STREAM_ERRORS.JC2096 : PORT_LOCAL_ERRORS.JC2070;
+          return pushFrame(id, 'error', seq, wireError(code, renderMessage(catalog, row.msgid, { op: opId }), trace, undefined, row.retryable));
         },
-        end: (reason, seq) => post(pushFrame(id, 'end', seq, { reason }), pushCtx),
-        done: () => streams.delete(id),
-      }, { lastSeq, validate });
+        end: (reason, seq) => pushFrame(id, 'end', seq, { reason }),
+        // the byte account is the frame as posted: its JSON text
+        size: (frame) => JSON.stringify(frame).length,
+        write: (frame) => post(frame, pushCtx),
+        done: () => {
+          streams.delete(id);
+          return release().then(() => undefined);
+        },
+      }, { lastSeq, validate, limits: streamLimits });
       entry.stop = (reason) => runner.stop(reason);
-    });
+    }
   }
 
   /** @param {any} event */

package/src/project/typescript.jtlt.json

@@ -29,25 +29,57 @@
         "  url<K extends keyof UrlOperations>(op: K, input: UrlOperations[K]): string;\n",
         "  close(): void;\n",
         "}\n\n",
+        "/** Every opaque public operation by id, with its input type, for `HttpClient.bytes`. */\n",
+        "export interface ByteOperations {\n",
+        [{ "$apply": ["$.operations[?@.opaque == true]", "url"] }],
+        "}\n\n",
+        "/** Per-call options of bytes: the members of InvokeContext that apply to an opaque call, plus the request body to send — text, bytes, a Web stream, an async iterable of chunks, or none. */\n",
+        "export interface ByteContext { signal?: AbortSignal; attempt?: unknown; headers?: Record<string, string>; ifNoneMatch?: string; ifMatch?: string; body?: string | Uint8Array | ReadableStream<Uint8Array> | AsyncIterable<Uint8Array> | null }\n\n",
+        "/** The success value of bytes: the status, the response headers (lowercase names), the response media (null when none) and the live response body — a stream the caller reads; null when the response carries none. */\n",
+        "export type ByteResponse = { status: number; headers: Record<string, string>; media: string | null; body: ReadableStream<Uint8Array> | null };\n\n",
+        "/** The HTTP client: the binding-neutral Client plus bytes over the opaque operations, whose success owns a live stream rather than a JSON value. */\n",
+        "export interface HttpClient extends Client {\n",
+        "  bytes<K extends keyof ByteOperations>(op: K, input: ByteOperations[K], ctx?: ByteContext): Promise<Outcome<ByteResponse>>;\n",
+        "}\n\n",
         "/** A declared failure a handler returns (ctx.fail): the declared code, the catalog parameters, the wire details and whether the caller may retry (null defers to the operation's retry policy). */\n",
         "export type Failure = { code: string; params: Readonly<Record<string, unknown>>; details: unknown; retryable: boolean | null };\n\n",
-        "/** The per-request context a server binding hands a handler. */\n",
-        "export interface HandlerContext {\n",
+        "/** The binding a handler context comes from. */\n",
+        "export type CarrierName = 'http' | 'port' | 'local';\n\n",
+        "/** The members every carrier's context shares; `host` is the host lifecycle's acquired value (null by default). */\n",
+        "export interface HandlerContextBase<Host = null> {\n",
         "  op: unknown;\n",
         "  trace: string;\n",
+        "  host: Host;\n",
+        "  headers: Readonly<Record<string, string>>;\n",
+        "  signal: AbortSignal | null;\n",
+        "  fail(code: string, params?: Record<string, unknown>, details?: unknown, options?: { retryable?: boolean }): Failure;\n",
+        "}\n\n",
+        "/** The HTTP binding's context: the request line, the raw body of an opaque operation, the idempotency key, and the entity-tag and status arms. */\n",
+        "export interface HttpHandlerContext<Host = null> extends HandlerContextBase<Host> {\n",
+        "  carrier: 'http';\n",
         "  method: string;\n",
         "  path: string;\n",
         "  params: Readonly<Record<string, string>>;\n",
-        "  headers: Readonly<Record<string, string>>;\n",
-        "  body: string | Uint8Array | null;\n",
-        "  signal: AbortSignal | null;\n",
+        "  body: string | Uint8Array | AsyncIterable<Uint8Array> | null;\n",
         "  idempotency: Readonly<{ key: string; scope: string }> | null;\n",
-        "  fail(code: string, params?: Record<string, unknown>, details?: unknown, options?: { retryable?: boolean }): Failure;\n",
         "  etag(tag: string, options?: { strong?: boolean }): void;\n",
         "  status(status: number): void;\n",
         "}\n\n",
+        "/** The port and local bindings' context: no request line, no body, no key, and no callable etag or status — spelled null, never omitted. */\n",
+        "export interface ChannelHandlerContext<Host = null, Carrier extends 'port' | 'local' = 'port' | 'local'> extends HandlerContextBase<Host> {\n",
+        "  carrier: Carrier;\n",
+        "  method: null;\n",
+        "  path: null;\n",
+        "  params: null;\n",
+        "  body: null;\n",
+        "  idempotency: null;\n",
+        "  etag: null;\n",
+        "  status: null;\n",
+        "}\n\n",
+        "/** The per-request context a server binding hands a handler, selected by carrier: the HTTP context by default; a carrier union is a discriminated union to narrow on `carrier`. */\n",
+        "export type HandlerContext<Host = null, Carrier extends CarrierName = 'http'> = Extract<HttpHandlerContext<Host> | ChannelHandlerContext<Host, 'port'> | ChannelHandlerContext<Host, 'local'>, { carrier: Carrier }>;\n\n",
         "/** The typed handler table of a server binding: one handler per invokable operation, answering the output, a declared failure, or a promise of either. */\n",
-        "export type Handlers = { [K in keyof Operations]: (input: Operations[K]['input'], ctx: HandlerContext) => Operations[K]['output'] | Failure | Promise<Operations[K]['output'] | Failure> };\n"
+        "export type Handlers<Host = null, Carrier extends CarrierName = 'http'> = { [K in keyof Operations]: (input: Operations[K]['input'], ctx: HandlerContext<Host, Carrier>) => Operations[K]['output'] | Failure | Promise<Operations[K]['output'] | Failure> };\n"
       ]
     },
     {

package/src/runtime.js

@@ -0,0 +1,36 @@
+//@ts-check
+/**
+ * @file The one place a contract binding reads its `runtime` option:
+ * the record is resolved through `@jarenjs/core/runtime` — nothing given
+ * is the platform's own clock, identifier and source — and a malformed
+ * record is refused as the binding's OWN host error (`JC1001` for a
+ * server, `JC1008` for a client), naming the option, so the refusal
+ * reads like every other option refusal of that constructor. Every
+ * binding then takes its host facts from the record only where its
+ * explicit option (`trace`, `keys`, `now`) is absent: the record
+ * injects, it never replaces a published option.
+ */
+
+import { resolveRuntime } from '@jarenjs/core/runtime';
+
+/**
+ * @typedef {import('@jarenjs/core/runtime').Runtime} Runtime
+ */
+
+/**
+ * Resolve a binding's `options.runtime`, or refuse it as that binding's
+ * host error under the code it refuses every malformed option with.
+ * @param {Partial<Runtime> | undefined | null} candidate - `options.runtime`
+ * @param {(code: any, reason: string) => Error} host - the binding's host
+ *   error constructor
+ * @param {'JC1001' | 'JC1008'} code - the binding's malformed-option code
+ * @returns {Readonly<Runtime>}
+ */
+export function resolveHostRuntime(candidate, host, code) {
+  try {
+    return resolveRuntime(candidate);
+  }
+  catch (error) {
+    throw host(code, `options.runtime: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}