@jarenjs/contract 0.49.2 → 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/tools.js

@@ -35,8 +35,15 @@ import { bundleSameDocument } from '../bundle.js';
 /**
  * A client as the tools read it — any binding's client. The members are
  * `any` so a client whose `invoke` narrows its own context type (the http
- * client's `InvokeContext`) still assigns.
- * @typedef {{ invoke: (op: string, input: any, ctx?: any) => any }} ToolClient
+ * client's `InvokeContext`) still assigns, and `invoke` is declared as a
+ * METHOD rather than as a function-valued property: a method's parameters
+ * are bivariant, so a client whose `invoke` narrows its OPERATION type to
+ * a literal union — `@jarenjs/linq/contract`'s `typedClient`, whose whole
+ * purpose is that narrowing — assigns here too. Under
+ * `strictFunctionTypes` the property form rejects it, and there is
+ * nothing to reject: this module only ever CALLS `invoke`, with an id it
+ * read out of the contract the client was opened on.
+ * @typedef {{ invoke(op: string, input: any, ctx?: any): any }} ToolClient
  */
 
 /**

package/src/project/typescript.js

@@ -23,6 +23,17 @@
  * stylesheet — the D6 shapes as every binding carries them
  * (`OUTCOME_META_MEMBERS` / `OUTCOME_ERROR_MEMBERS` in the client module
  * are the runtime twins; a test holds the text to them).
+ *
+ * One convention rides on top of emit's reading, the suite's: a string
+ * with `format: "date-time"` or `format: "date"` is the `DateTime`
+ * brand, so a consumer's generated types agree with `@jarenjs/db`'s
+ * entity types (`entityEmitModel`) and `@jarenjs/linq`'s schema pen,
+ * which both read a date format that way. Emit itself records a format
+ * only as a dropped constraint, so the brand is applied HERE, by
+ * rewriting date-formatted string nodes to a `$ref` of one shared
+ * definition before emit reads the document — in every position, an
+ * array item as much as a member — and giving that definition the brand
+ * intersection.
  */
 
 import { isJsonObject, setObjectMember } from '@jarenjs/core/object';
@@ -66,6 +77,72 @@ function pascal(word) {
   return out;
 }
 
+/** The two formats that carry the brand. */
+const DATE_FORMATS = ['date-time', 'date'];
+
+/** The definition name the brand takes when the contract leaves it free. */
+const DATE_TIME = 'DateTime';
+
+/**
+ * Rewrite every date-formatted string node to a reference to the shared
+ * brand definition, in every position. Nodes are rebuilt, never mutated:
+ * the schemas here are the compiled document's own frozen subtrees.
+ * @param {any} node
+ * @param {string} name - the brand definition's name in this document
+ * @returns {any}
+ */
+function brandDates(node, name) {
+  if (Array.isArray(node)) return node.map((item) => brandDates(item, name));
+  if (node === null || typeof node !== 'object') return node;
+  /** @type {Record<string, any>} */
+  const out = {};
+  const keys = Object.keys(node);
+  for (let i = 0; i < keys.length; i++) setObjectMember(out, keys[i], brandDates(node[keys[i]], name));
+  if (!DATE_FORMATS.includes(/** @type {any} */ (out.format))) return out;
+  const { type, format: _format, ...rest } = out;
+  if (type === 'string') return { $ref: `#/$defs/${name}`, ...rest };
+  // a nullable date: the brand or null, the rest of the node kept
+  if (Array.isArray(type) && type.length === 2 && type.includes('string') && type.includes('null')) {
+    return { anyOf: [{ $ref: `#/$defs/${name}` }, { type: 'null' }], ...rest };
+  }
+  return out;
+}
+
+/** Whether a document reaches a date-formatted string anywhere. */
+function usesDates(node) {
+  if (Array.isArray(node)) return node.some(usesDates);
+  if (node === null || typeof node !== 'object') return false;
+  if (DATE_FORMATS.includes(node.format)) return true;
+  return Object.values(node).some(usesDates);
+}
+
+/**
+ * Replace the brand definition's compiled declaration — a plain
+ * `string` — with the brand intersection `string & { __jarenTag:
+ * 'date-time' }`, structurally identical to `@jarenjs/db`'s and
+ * `@jarenjs/linq`'s.
+ * @param {any} model
+ * @param {string} name
+ */
+function brandDeclaration(model, name) {
+  const declaration = model.declarations.find((/** @type {any} */ d) => d.name === name);
+  /* c8 ignore next -- the definition is added exactly when it is referenced */
+  if (declaration === undefined) return;
+  declaration.type = {
+    kind: 'intersection',
+    parts: [{ kind: 'primitive', primitive: 'string' }, {
+      kind: 'object',
+      members: [{
+        kind: 'member', name: '__jarenTag',
+        type: { kind: 'literal', value: 'date-time' }, required: true,
+        constraints: [], doc: [],
+      }],
+    }],
+  };
+  declaration.doc = ['An RFC 3339 string branded for the date operators;',
+    'structurally identical to the @jarenjs/linq and @jarenjs/db brand.'];
+}
+
 /**
  * The type model of a contract: the synthetic `$defs` root, the row per
  * operation the stylesheet renders, and the rendered declarations.
@@ -117,7 +194,20 @@ export function contractTypeModel(contract, ops, source) {
   }
   const names = Object.keys(contractDefs);
   for (let i = 0; i < names.length; i++) setObjectMember(defs, names[i], contractDefs[names[i]]);
-  const model = compileEmitModel({ $defs: defs }, { name: 'Contract', source });
+  /** @type {Record<string, any>} */
+  let root = defs;
+  /** @type {string | null} */
+  let brand = null;
+  if (usesDates(defs)) {
+    // the brand takes its own name unless the contract already spells it
+    brand = taken.has(DATE_TIME) ? unique(DATE_TIME) : DATE_TIME;
+    root = { [brand]: { type: 'string' } };
+    const branded = brandDates(defs, brand);
+    const keys = Object.keys(branded);
+    for (let i = 0; i < keys.length; i++) setObjectMember(root, keys[i], branded[keys[i]]);
+  }
+  const model = compileEmitModel({ $defs: root }, { name: 'Contract', source });
+  if (brand !== null) brandDeclaration(model, brand);
   const declarations = model.declarations.filter((d) => d.name !== model.root);
   const types = renderTypeScript({ ...model, declarations }, { banner: false });
   return { types, rows, model: { ...model, declarations } };