@jarenjs/contract 0.43.1

package/src/port/frame.js

@@ -0,0 +1,196 @@
+//@ts-check
+/**
+ * @file The frame grammar of the port binding (docs/CONTRACT-FORMAT.md
+ * §16), shared by `servePort` and `openPortClient`: JSON-safe plain
+ * objects marked `jaren: "contract/0.1"`, so contract traffic is
+ * distinguishable BY SHAPE from anything else on a shared channel — a
+ * frame without the marker is never touched, and never answered.
+ *
+ * Request ids are `"<clientId>:<seq>"` — the client id a UUID per
+ * client instance, the sequence a per-client counter — so two clients
+ * on one broadcast channel can never collide, and a client recognizes
+ * its own responses with one cheap prefix test before any map lookup.
+ * The request members `attempt` and `key` are reserved by the grammar
+ * (`schemas/jaren-contract-port.schema.json`) and ignored by this
+ * order's server: the attempt id stays caller-side in `meta` (D6 — the
+ * identities live in state, never in the transport) and idempotency is
+ * not carried on this binding (`capabilities` says so).
+ */
+
+/** The frame marker: the protocol and its version. */
+export const FRAME_MARKER = 'contract/0.1';
+
+/**
+ * A request frame. `input` is the whole (validated) input object, or
+ * `null` for an input-less operation.
+ * @typedef {{ jaren: string, id: string, op: string, input: unknown }} RequestFrame
+ */
+
+/**
+ * A response frame: success with the value, or an error envelope —
+ * `code` a declared error code or a `JC2xxx` taxonomy/binding code,
+ * `details` present only when the failure carries some. Every response
+ * carries the server's `trace`.
+ * @typedef {{ jaren: string, id: string, ok: true, value: unknown, trace: string }
+ *   | { jaren: string, id: string, ok: false, error: { code: string, message: string, details?: unknown, retryable?: boolean }, trace: string }} ResponseFrame
+ */
+
+/**
+ * A cancel frame: aborts the server-side signal of the named request —
+ * an optimization; the client's id scoping is the guarantee. Never
+ * answered.
+ * @typedef {{ jaren: string, cancel: string }} CancelFrame
+ */
+
+/**
+ * A subscribe frame: opens one stream (docs/CONTRACT-FORMAT.md §18.2).
+ * `input` is the whole (validated) input object or `null`; `lastSeq`,
+ * when present, asks to resume after that seq.
+ * @typedef {{ jaren: string, subscribe: string, op: string, input: unknown, lastSeq?: number }} SubscribeFrame
+ */
+
+/**
+ * An unsubscribe frame: closes the named stream. Never answered.
+ * @typedef {{ jaren: string, unsubscribe: string }} UnsubscribeFrame
+ */
+
+/**
+ * A push frame: one stream event, server → client. `event` is
+ * `snapshot | patch | error | end` with the §18 data shapes; `seq` is
+ * the event's seq (`error`/`end` carry the last delivered one).
+ * @typedef {{ jaren: string, id: string, event: string, seq: number, data: unknown }} PushFrame
+ */
+
+/**
+ * The channel shape both halves accept: a `MessagePort`, a `Worker`, a
+ * `BroadcastChannel`, a worker's own `self`, or any object with
+ * `postMessage` and a message-listener surface. `start` is called when
+ * present (a `MessagePort` queues until it is).
+ * @typedef {{ postMessage: (message: any) => void,
+ *   addEventListener?: (type: string, listener: (event: any) => void) => void,
+ *   removeEventListener?: (type: string, listener: (event: any) => void) => void,
+ *   onmessage?: ((event: any) => void) | null,
+ *   start?: () => void }} ChannelLike
+ */
+
+/**
+ * Whether a value is a contract frame at all — the marker test every
+ * listener applies first, so foreign traffic on a shared channel is
+ * ignored by shape. Reads one member of a plain object; total.
+ * @param {unknown} value
+ * @returns {value is { jaren: string }}
+ */
+export function isContractFrame(value) {
+  return value !== null && typeof value === 'object' && /** @type {any} */ (value).jaren === FRAME_MARKER;
+}
+
+/**
+ * @param {string} id
+ * @param {string} op
+ * @param {unknown} input
+ * @returns {RequestFrame}
+ */
+export function requestFrame(id, op, input) {
+  return { jaren: FRAME_MARKER, id, op, input };
+}
+
+/**
+ * @param {string} id
+ * @param {unknown} value - `undefined` is carried as `null` (frames are JSON)
+ * @param {string} trace
+ * @returns {ResponseFrame}
+ */
+export function valueFrame(id, value, trace) {
+  return { jaren: FRAME_MARKER, id, ok: true, value: value === undefined ? null : value, trace };
+}
+
+/**
+ * @param {string} id
+ * @param {string} code
+ * @param {string} message
+ * @param {unknown} details - omitted from the frame when `undefined`
+ * @param {boolean} retryable
+ * @param {string} trace
+ * @returns {ResponseFrame}
+ */
+export function errorFrame(id, code, message, details, retryable, trace) {
+  return details === undefined
+    ? { jaren: FRAME_MARKER, id, ok: false, error: { code, message, retryable }, trace }
+    : { jaren: FRAME_MARKER, id, ok: false, error: { code, message, details, retryable }, trace };
+}
+
+/**
+ * @param {string} id
+ * @returns {CancelFrame}
+ */
+export function cancelFrame(id) {
+  return { jaren: FRAME_MARKER, cancel: id };
+}
+
+/**
+ * @param {string} id
+ * @param {string} op
+ * @param {unknown} input
+ * @param {number | null} lastSeq - omitted from the frame when `null`
+ * @returns {SubscribeFrame}
+ */
+export function subscribeFrame(id, op, input, lastSeq) {
+  return lastSeq === null
+    ? { jaren: FRAME_MARKER, subscribe: id, op, input }
+    : { jaren: FRAME_MARKER, subscribe: id, op, input, lastSeq };
+}
+
+/**
+ * @param {string} id
+ * @returns {UnsubscribeFrame}
+ */
+export function unsubscribeFrame(id) {
+  return { jaren: FRAME_MARKER, unsubscribe: id };
+}
+
+/**
+ * @param {string} id
+ * @param {string} event - `snapshot | patch | error | end`
+ * @param {number} seq
+ * @param {unknown} data
+ * @returns {PushFrame}
+ */
+export function pushFrame(id, event, seq, data) {
+  return { jaren: FRAME_MARKER, id, event, seq, data: data === undefined ? null : data };
+}
+
+/**
+ * Attach a message listener to a channel: `addEventListener` where the
+ * channel has one (plus `start()`, which a `MessagePort` needs to begin
+ * delivery), the `onmessage` slot otherwise. Returns the detacher.
+ * @param {ChannelLike} channel
+ * @param {(event: any) => void} listener
+ * @returns {() => void}
+ */
+export function attach(channel, listener) {
+  if (typeof channel.addEventListener === 'function') {
+    channel.addEventListener('message', listener);
+    if (typeof channel.start === 'function') channel.start();
+    return () => {
+      if (typeof channel.removeEventListener === 'function') channel.removeEventListener('message', listener);
+    };
+  }
+  channel.onmessage = listener;
+  return () => {
+    if (channel.onmessage === listener) channel.onmessage = null;
+  };
+}
+
+/**
+ * Whether a value is a usable channel. The listener surface is either
+ * `addEventListener` or an assignable `onmessage` slot — `in` sees the
+ * slot on platform channels and plain fakes alike.
+ * @param {unknown} value
+ * @returns {value is ChannelLike}
+ */
+export function isChannel(value) {
+  if (value === null || typeof value !== 'object') return false;
+  const c = /** @type {any} */ (value);
+  return typeof c.postMessage === 'function'
+    && (typeof c.addEventListener === 'function' || 'onmessage' in c);
+}

package/src/port/serve.js

@@ -0,0 +1,442 @@
+//@ts-check
+/**
+ * @file `servePort(contract, handlers, options)`: the server half of the
+ * port binding (docs/CONTRACT-FORMAT.md §16) — request/response over a
+ * `MessagePort`, a `Worker`, a `BroadcastChannel` or a worker's own
+ * `self`. Requests run through the same neutral pipeline as every other
+ * server binding, under one `AbortController` per request id; a cancel
+ * frame aborts it (an optimization — the client's id scoping is the
+ * guarantee), and the response is posted back on the same channel.
+ *
+ * The listener touches nothing without the frame marker — other traffic
+ * may share the channel and is never answered — and never answers a
+ * RESPONSE frame either, so two ends on one broadcast channel cannot
+ * echo at each other. A request naming an operation this channel does
+ * not serve (unknown, or opaque — a port carries JSON only) is answered
+ * `JC2071` without echoing what it asked for; an invalid input is
+ * `JC2006` with details by the operation's policy; a handler fault of
+ * any class is `JC2070` with the cause reported to `onError`, never
+ * onto the wire. Exactly ONE server should serve a shared channel — two
+ * would both answer every request.
+ */
+
+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 { HTTP_ERRORS, renderMessage, declaredMessage } from '../http/wire.js';
+import { isContractFrame, valueFrame, errorFrame, pushFrame, attach, isChannel } from './frame.js';
+
+export { openPortClient } from './client.js';
+export { FRAME_MARKER, isContractFrame } from './frame.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('../pipeline.js').PipelineRoute} PipelineRoute
+ * @typedef {import('./frame.js').ChannelLike} ChannelLike
+ */
+
+/**
+ * @typedef {Object} ServePortOptions
+ * @property {ChannelLike} channel - the channel to serve (required)
+ * @property {() => string} [trace] - the server 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` frame, validator throws
+ *   and a channel whose `postMessage` throws
+ */
+
+/**
+ * The frozen capabilities table of the port server: JSON frames only —
+ * no statuses, headers, media or entity tags, no idempotency carriage
+ * (a declared policy is inert here, like on `local`), and cancellation
+ * arrives as a message.
+ * @typedef {Object} PortServerCapabilities
+ * @property {'port'} name
+ * @property {false} status
+ * @property {false} headers
+ * @property {false} media
+ * @property {false} etag
+ * @property {false} idempotency
+ * @property {boolean} validatedOutput
+ * @property {true} stream - subscribe operations stream as push frames (docs/CONTRACT-FORMAT.md §18.2)
+ * @property {'message'} cancel
+ */
+
+/**
+ * The server binding.
+ * @typedef {Object} PortServer
+ * @property {PortServerCapabilities} capabilities
+ * @property {Contract} contract
+ * @property {() => any} describe
+ * @property {() => void} close - ends every live stream with `end`
+ *   (`server-shutdown`), detaches the listener and aborts every in-flight request
+ */
+
+/** The frozen empty header table every port handler context carries. */
+const NO_HEADERS = Object.freeze({});
+
+/**
+ * @param {string} code
+ * @param {string} reason
+ * @returns {ContractHostError}
+ */
+function host(code, reason) {
+  return new ContractHostError(code, `servePort: ${reason}`);
+}
+
+/**
+ * One served operation: the neutral pipeline route plus whether it is a
+ * subscribe operation (a stream, never a request/response).
+ * @typedef {PipelineRoute & { stream: boolean }} PortRoute
+ */
+
+/**
+ * The pipeline route of one served operation.
+ * @param {CompiledOperation} op
+ * @param {Handler | null} handler
+ * @returns {PortRoute}
+ */
+function prepare(op, handler) {
+  return Object.freeze({
+    op,
+    handler,
+    raw: op.http.opaque,
+    stream: op.kind === 'subscribe',
+    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),
+  });
+}
+
+/**
+ * Serve a compiled contract over a message channel. Construction refuses
+ * host mistakes (`JC1001` handler table, channel or option, `JC1002`
+ * missing handler — an opaque operation is exempt, it is answered
+ * `JC2071` instead of served).
+ *
+ * @param {Contract} contract
+ * @param {Record<string, Handler>} handlers - operation id → handler
+ * @param {ServePortOptions} options
+ * @returns {PortServer}
+ * @throws {ContractHostError}
+ * @example
+ * // inside a worker: serve the worker's own channel
+ * servePort(contract, handlers, { channel: self });
+ * // and the same handlers to every tab on a BroadcastChannel
+ * servePort(contract, handlers, { channel: new BroadcastChannel('app') });
+ */
+export function servePort(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 with the channel');
+  const channel = options.channel;
+  if (!isChannel(channel)) {
+    throw host('JC1001', 'options.channel must expose postMessage and a message listener surface (a MessagePort, Worker, BroadcastChannel, a worker\'s self, or the shape)');
+  }
+  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 traceGen = 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, PortRoute>} */
+  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;
+    if (handler === null && !op.http.opaque) {
+      throw host('JC1002', `operation '${id}' has no handler`);
+    }
+    routes.set(id, prepare(op, handler));
+  }
+
+  /** @type {Map<string, AbortController>} */
+  const active = new Map();
+  let closed = false;
+
+  /**
+   * @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 response
+    }
+  }
+
+  /**
+   * Post a frame. TOTAL: a channel that throws (closed, detached) is
+   * reported, never a crash on the serving side.
+   * @param {unknown} frame
+   * @param {{ op: string, trace: string } | null} ctx
+   */
+  function post(frame, ctx) {
+    try {
+      channel.postMessage(frame);
+    }
+    catch (err) {
+      observe(err, ctx);
+    }
+  }
+
+  /**
+   * One request frame through the pipeline and back onto the channel.
+   * @param {string} id
+   * @param {unknown} op
+   * @param {unknown} input
+   */
+  function serveRequest(id, op, input) {
+    const trace = safeTrace(traceGen);
+    const route = typeof op === 'string' ? routes.get(op) : undefined;
+    // a subscribe operation is a stream, never a request/response —
+    // asked as one, it is "not served on this channel" like an opaque
+    if (route === undefined || route.raw || route.stream) {
+      // never echo what the frame asked for — it is the request's own value
+      post(errorFrame(id, 'JC2071', renderMessage(catalog, PORT_LOCAL_ERRORS.JC2071.msgid, {}), undefined, false, trace), null);
+      return;
+    }
+    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;
+      if (result.kind === 'value') {
+        post(valueFrame(id, result.value, trace), { op: opId, trace });
+      }
+      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 });
+      }
+      else {
+        if (result.cause !== undefined) observe(result.cause, { op: opId, trace });
+        post(errorFrame(id, 'JC2070', renderMessage(catalog, PORT_LOCAL_ERRORS.JC2070.msgid, { op: opId }),
+          undefined, false, trace), { op: opId, trace });
+      }
+    });
+  }
+
+  /**
+   * The live streams by id. An entry exists from the subscribe frame
+   * on, so an unsubscribe that races the handler's settlement still
+   * lands: `stop` is re-pointed at the runner once it exists.
+   * @type {Map<string, { stopped: boolean, stop: (reason: string | null) => void }>}
+   */
+  const streams = new Map();
+
+  /**
+   * An error push frame's data: the wire error record (§7.3's body
+   * without a status; `details` only when present).
+   * @param {string} code
+   * @param {string} message
+   * @param {string} trace
+   * @param {unknown} details
+   * @param {boolean} retryable
+   */
+  function wireError(code, message, trace, details, retryable) {
+    return details === undefined
+      ? { code, message, requestId: trace, retryable }
+      : { code, message, requestId: trace, details, retryable };
+  }
+
+  /**
+   * One subscribe frame: open the stream (docs/CONTRACT-FORMAT.md
+   * §18.2). Pre-stream failures — unknown or non-subscribe op, invalid
+   * input, a handler fault, an invalid snapshot — arrive as `error`
+   * push frames; then the carrier-neutral runner forwards the
+   * subscription's events as push frames until the stream ends.
+   * @param {string} id
+   * @param {unknown} op
+   * @param {unknown} input
+   * @param {unknown} lastSeqRaw
+   */
+  function serveSubscribe(id, op, input, lastSeqRaw) {
+    const trace = safeTrace(traceGen);
+    const route = typeof op === 'string' ? routes.get(op) : undefined;
+    if (route === undefined || !route.stream) {
+      post(pushFrame(id, 'error', 0, wireError('JC2071', renderMessage(catalog, PORT_LOCAL_ERRORS.JC2071.msgid, {}), trace, undefined, false)), null);
+      return;
+    }
+    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;
+      }
+      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)) {
+        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;
+      }
+      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);
+        },
+        end: (reason, seq) => post(pushFrame(id, 'end', seq, { reason }), pushCtx),
+        done: () => streams.delete(id),
+      }, { lastSeq, validate });
+      entry.stop = (reason) => runner.stop(reason);
+    });
+  }
+
+  /** @param {any} event */
+  function listener(event) {
+    const frame = event === null || typeof event !== 'object' ? undefined : event.data;
+    if (closed || !isContractFrame(frame)) return;
+    const f = /** @type {any} */ (frame);
+    if (Object.hasOwn(f, 'cancel')) {
+      const controller = typeof f.cancel === 'string' ? active.get(f.cancel) : undefined;
+      if (controller !== undefined) controller.abort();
+      return;
+    }
+    if (Object.hasOwn(f, 'subscribe')) {
+      if (typeof f.subscribe === 'string' && f.subscribe.length > 0 && !streams.has(f.subscribe)) {
+        serveSubscribe(f.subscribe, f.op, f.input, f.lastSeq);
+      }
+      return;
+    }
+    if (Object.hasOwn(f, 'unsubscribe')) {
+      const entry = typeof f.unsubscribe === 'string' ? streams.get(f.unsubscribe) : undefined;
+      if (entry !== undefined) {
+        streams.delete(f.unsubscribe);
+        entry.stop(null);
+      }
+      return;
+    }
+    // a response or push frame on a shared channel is another server's answer
+    if (Object.hasOwn(f, 'ok') || Object.hasOwn(f, 'event')) return;
+    // without a string id there is nothing to address an answer to
+    if (typeof f.id !== 'string' || f.id.length === 0) return;
+    serveRequest(f.id, f.op, f.input);
+  }
+
+  const detach = attach(channel, listener);
+
+  /** @type {PortServerCapabilities} */
+  const capabilities = Object.freeze({
+    name: 'port',
+    status: false,
+    headers: false,
+    media: false,
+    etag: false,
+    idempotency: false,
+    validatedOutput: validate,
+    stream: true,
+    cancel: 'message',
+  });
+
+  return Object.freeze({
+    capabilities,
+    contract,
+    describe: () => contract.describe(),
+    close: () => {
+      if (closed) return;
+      // every live stream ends with server-shutdown BEFORE the channel
+      // detaches, so the clients hear it
+      for (const entry of [...streams.values()]) entry.stop('server-shutdown');
+      streams.clear();
+      closed = true;
+      detach();
+      for (const controller of active.values()) controller.abort();
+      active.clear();
+    },
+  });
+}

package/src/project/index.js

@@ -0,0 +1,29 @@
+//@ts-check
+/**
+ * @file The projections of a compiled contract (`@jarenjs/contract/project`):
+ * `publicProjection` (the browser-safe subset — itself a `$contract`
+ * document, and what the revision hashes), `toOpenApi` (OpenAPI 3.1
+ * through a JSLT stylesheet), `toTypeScript` and `toMarkdown` (on
+ * `@jarenjs/emit`'s type model), `contractTools` (`@jarenjs/ai` tool
+ * definitions, no import edge) and the same-document bundler they share.
+ * This is the one subpath that imports `@jarenjs/emit`; a consumer that
+ * never imports it never loads it.
+ */
+
+export { publicProjection } from '../public.js';
+export { toOpenApi } from './openapi.js';
+export { toTypeScript } from './typescript.js';
+export { toMarkdown } from './markdown.js';
+export { contractTools } from './tools.js';
+export { reachableDefs, bundleSameDocument } from '../bundle.js';
+
+/**
+ * @typedef {import('../public.js').PublicProjectionOptions} PublicProjectionOptions
+ * @typedef {import('./openapi.js').OpenApiOptions} OpenApiOptions
+ * @typedef {import('./openapi.js').OpenApiResult} OpenApiResult
+ * @typedef {import('./openapi.js').DroppedKeyword} DroppedKeyword
+ * @typedef {import('./typescript.js').TypeScriptOptions} TypeScriptOptions
+ * @typedef {import('./markdown.js').MarkdownOptions} MarkdownOptions
+ * @typedef {import('./tools.js').ToolDefinition} ToolDefinition
+ * @typedef {import('./tools.js').ContractToolsOptions} ContractToolsOptions
+ */