@procedures/client 0.2.3 → 0.4.0

package/src/client/middleware/timeout.ts

@@ -5,26 +5,29 @@
  * Works with any transport!
  */
 
-import type { ClientMiddleware, ClientRunner, ClientContext, ResponseItem, TypedClientMiddleware } from "../types.js";
-import { ABORTED_FIRST, errorItem, nextOrAbort } from "./items.js";
+import type { ClientRunner, ClientContext, ResponseItem, TypedClientMiddleware } from "../types.js";
+import { ABORTED_FIRST, abortedItem, errorItem, nextOrAbort, withDelivery } from "./items.js";
 import type { TimeoutContext } from "./contexts.js";
+import { deadlineOf, narrowDeadline, restoreDeadline } from "../deadline.js";
+import { resilience } from "./resilience.js";
+import { optionalMs, type Duration } from "../../duration.js";
 
 /**
  * Timeout middleware options.
  */
 export interface TimeoutOptions {
   /**
-   * Timeout in milliseconds for the entire request (including retries).
+   * The time of the entire request (including retries), for example `seconds(10)`.
    * @default undefined (no overall timeout)
    */
-  overall?: number;
+  overall?: Duration | undefined;
 
   /**
-   * Timeout in milliseconds for each individual attempt.
+   * The time of each individual attempt, for example `seconds(2)`.
    * Useful with retry middleware for per-attempt timeouts.
    * @default undefined (no per-attempt timeout)
    */
-  perAttempt?: number;
+  perAttempt?: Duration | undefined;
 
   /**
    * Custom timeout error message.
@@ -89,17 +92,18 @@ function composeAbortSignals(...signals: (AbortSignal | undefined)[]): {
     }
   }
 
-  // Fallback: Manual composition for older environments
+  // Fallback: Manual composition for older environments. The composed signal keeps the reason of
+  // the signal that aborted, as with AbortSignal.any() (before, it got a new AbortError).
   const controller = new AbortController();
   const abortListeners: Array<() => void> = [];
 
   for (const signal of validSignals) {
     if (signal.aborted) {
-      controller.abort();
+      controller.abort(signal.reason);
       break;
     }
 
-    const listener = () => controller.abort();
+    const listener = () => controller.abort(signal.reason);
     signal.addEventListener("abort", listener, { once: true });
     abortListeners.push(() => signal.removeEventListener("abort", listener));
   }
@@ -116,7 +120,8 @@ function composeAbortSignals(...signals: (AbortSignal | undefined)[]): {
 /**
  * Run `next` with a timeout. When the time runs out, the request's signal aborts, and the
  * reader gets one TIMEOUT error item in place of the transport's ABORTED item or thrown error.
- * The middleware does not wait for a transport that ignores the signal.
+ * The middleware does not wait for a transport that ignores the signal: not after the timeout,
+ * and not after an abort of the caller, which gives an ABORTED item.
  *
  * Before, the middleware waited for a thrown error, but the transports yield error items: the
  * reader got "ABORTED" (not retryable), so a per-attempt timeout with retry never retried, and
@@ -131,47 +136,50 @@ async function* runWithTimeout<TReq, TRes>(
 ): AsyncGenerator<ResponseItem<TRes>, void, undefined> {
   const timeoutController = new AbortController();
   const timeoutId = setTimeout(() => timeoutController.abort(), ms);
+  // The overall timeout is the deadline of the call: the transport sends its remaining time to
+  // the server (roadmap R10). The timeout of one try is not: the server keeps a keyed write
+  // until the next try can get its result, and the request signal stops another call.
+  const deadlineBefore = retryable ? deadlineOf(context.message.metadata) : narrowDeadline(context.message.metadata, Date.now() + ms);
 
   // Compose with existing signal
   const originalSignal = context.message.signal;
   const { controller: composedController, cleanup } = composeAbortSignals(originalSignal, timeoutController.signal);
   context.message.signal = composedController.signal;
   const timedOut = (): boolean => timeoutController.signal.aborted && !originalSignal?.aborted;
-  const timeoutItem = (): ResponseItem<TRes> => errorItem<TRes>(context.message.id, "TIMEOUT", message, retryable);
+  // The request left before the time ran out: the server can still run it (R1)
+  const timeoutItem = (): ResponseItem<TRes> =>
+    withDelivery(errorItem<TRes>(context.message.id, "TIMEOUT", message, retryable), "indeterminate");
 
   const iterator = next(context)[Symbol.asyncIterator]();
   // "running": a next() may be pending; "done": the iterator ended; "abandoned": the timeout won
   let phase: "running" | "done" | "abandoned" = "running";
   try {
     for (;;) {
-      const result = await nextOrAbort(iterator, timeoutController.signal);
+      // The timeout and the abort of the caller both end the wait (roadmap R30: before, the wait
+      // ignored the abort of the caller, so a transport that ignored the signal kept the caller
+      // waiting until the timeout, and the caller got TIMEOUT for its own abort)
+      const result = await nextOrAbort(iterator, composedController.signal);
       if (result === ABORTED_FIRST) {
         phase = "abandoned";
-        // The transport did not stop in time: end it in the background, and give the timeout
+        // The transport did not stop in time: end it in the background, and give the timeout or the abort
         void Promise.resolve(iterator.return?.()).catch(() => undefined);
-        yield timeoutItem();
+        yield timedOut() ? timeoutItem() : abortedItem<TRes>(context.message.id);
         return;
       }
       if (result.done) {
         phase = "done";
         return;
       }
-      if (result.value.status.type === "error" && timedOut()) {
-        // The transport saw the aborted signal and reported ABORTED: it is a timeout
-        yield timeoutItem();
-        return;
-      }
+      // An item or an error of the transport comes before the abort. `nextOrAbort` adds its abort
+      // listener before it calls `next()`, so a later abort gives ABORTED_FIRST, not an item.
       yield result.value;
     }
   } catch (error) {
     phase = "done";
-    if (timedOut()) {
-      yield timeoutItem();
-      return;
-    }
     throw error;
   } finally {
     clearTimeout(timeoutId);
+    restoreDeadline(context.message.metadata, deadlineBefore);
     cleanup();
     // Restore the caller's original signal; we only swapped in the composed signal for this
     // attempt. Leaving the (possibly aborted) composed signal in place poisons subsequent
@@ -200,22 +208,24 @@ async function* runWithTimeout<TReq, TRes>(
  * @example
  * ```typescript
  * // Create middleware with default timeout
- * client.use(createOverallTimeoutMiddleware({ overall: 5000 }));
+ * client.use(createOverallTimeoutMiddleware({ overall: seconds(5) }));
  *
  * // Override per-call via context
  * await client.call(method, payload, {
- *   context: { timeout: { overall: 10000 } }
+ *   context: { timeout: { overall: seconds(10) } }
  * });
  * ```
  */
 export function createOverallTimeoutMiddleware(options: Pick<TimeoutOptions, "overall" | "message">): TypedClientMiddleware<TimeoutContext, {}> {
-  const { overall: defaultOverall, message = "Overall request timeout" } = options;
+  const { message = "Overall request timeout" } = options;
+  const defaultOverall = optionalMs(options.overall, "overall");
 
   return <TReq, TRes>(next: ClientRunner<TReq, TRes>): ClientRunner<TReq, TRes> => {
     return async function* (context: ClientContext<TReq>) {
       // Read from metadata first (user-provided context), then fall back to options
-      const overall = (context.message.metadata.timeout as TimeoutContext["timeout"] | undefined)?.overall
-        ?? defaultOverall;
+      const overall =
+        optionalMs((context.message.metadata.timeout as TimeoutContext["timeout"] | undefined)?.overall, "timeout.overall") ??
+        defaultOverall;
 
       if (!overall) {
         // No timeout - passthrough
@@ -243,22 +253,24 @@ export function createOverallTimeoutMiddleware(options: Pick<TimeoutOptions, "ov
  * @example
  * ```typescript
  * // Create middleware with default timeout
- * client.use(createTimeoutMiddleware({ perAttempt: 1000 }));
+ * client.use(createTimeoutMiddleware({ perAttempt: seconds(1) }));
  *
  * // Override per-call via context
  * await client.call(method, payload, {
- *   context: { timeout: { perAttempt: 2000 } }
+ *   context: { timeout: { perAttempt: seconds(2) } }
  * });
  * ```
  */
 export function createTimeoutMiddleware(options: Pick<TimeoutOptions, "perAttempt" | "message">): TypedClientMiddleware<TimeoutContext, {}> {
-  const { perAttempt: defaultPerAttempt, message = "Request timeout" } = options;
+  const { message = "Request timeout" } = options;
+  const defaultPerAttempt = optionalMs(options.perAttempt, "perAttempt");
 
   return <TReq, TRes>(next: ClientRunner<TReq, TRes>): ClientRunner<TReq, TRes> => {
     return async function* (context: ClientContext<TReq>) {
       // Read from metadata first (user-provided context), then fall back to options
-      const perAttempt = (context.message.metadata.timeout as TimeoutContext["timeout"] | undefined)?.perAttempt
-        ?? defaultPerAttempt;
+      const perAttempt =
+        optionalMs((context.message.metadata.timeout as TimeoutContext["timeout"] | undefined)?.perAttempt, "timeout.perAttempt") ??
+        defaultPerAttempt;
 
       if (!perAttempt) {
         // No timeout - passthrough
@@ -266,8 +278,12 @@ export function createTimeoutMiddleware(options: Pick<TimeoutOptions, "perAttemp
         return;
       }
 
+      // The limit of one try is at most the remaining time of the call (roadmap R10)
+      const deadline = deadlineOf(context.message.metadata);
+      const limit = deadline === undefined ? perAttempt : Math.max(0, Math.min(perAttempt, deadline - Date.now()));
+
       // A retry middleware outside this one can start a new attempt
-      yield* runWithTimeout(next, context, perAttempt, message, true);
+      yield* runWithTimeout(next, context, limit, message, true);
     };
   };
 }
@@ -275,34 +291,20 @@ export function createTimeoutMiddleware(options: Pick<TimeoutOptions, "perAttemp
 /**
  * Create combined timeout middleware with both overall and per-attempt timeouts.
  *
+ * @deprecated Use `resilience({ overall, perAttempt, retry })`. This function puts the two
+ * timeouts in one slot, so a retry middleware that you add with another `use()` cannot sit
+ * between them: the retry is outside both, or inside both. `resilience` puts the retry between
+ * them (roadmap R10).
+ *
  * @param options - Timeout configuration
  * @returns Middleware function
  *
  * @example
  * ```typescript
- * client.use(createCombinedTimeoutMiddleware({
- *   overall: 5000,     // 5 seconds total
- *   perAttempt: 1000   // 1 second per attempt
- * }));
+ * client.use(resilience({ overall: seconds(5), perAttempt: seconds(1), retry: { maxRetries: 2 } }));
  * ```
  */
 export function createCombinedTimeoutMiddleware(options: TimeoutOptions): TypedClientMiddleware<TimeoutContext, {}> {
   const { overall, perAttempt, message = "Request timeout" } = options;
-
-  return <TReq, TRes>(next: ClientRunner<TReq, TRes>): ClientRunner<TReq, TRes> => {
-    // Compose both timeout middlewares
-    let composed: ClientRunner<TReq, TRes> = next;
-
-    if (perAttempt) {
-      const perAttemptMiddleware = createTimeoutMiddleware({ perAttempt, message: `${message} (per-attempt)` }) as ClientMiddleware<TReq, TRes>;
-      composed = perAttemptMiddleware(composed);
-    }
-
-    if (overall) {
-      const overallMiddleware = createOverallTimeoutMiddleware({ overall, message: `${message} (overall)` }) as ClientMiddleware<TReq, TRes>;
-      composed = overallMiddleware(composed);
-    }
-
-    return composed;
-  };
+  return resilience({ overall, perAttempt, message }) as TypedClientMiddleware<TimeoutContext, {}>;
 }

package/src/client/middleware/tracing.ts

@@ -14,6 +14,7 @@
 
 import type { TypedClientMiddleware } from "../types.js";
 import type { TracingContext } from "./contexts.js";
+import { TRACEPARENT_METADATA_KEY, formatTraceparent, isW3cIds, newSpanId, newTraceId, parseTraceparent } from "../../tracing/traceparent.js";
 
 /**
  * Tracing Configuration
@@ -98,9 +99,10 @@ function generateId(): string {
 export function createTracingMiddleware(
   options: TracingOptions = {}
 ): TypedClientMiddleware<TracingContext, {}> {
+  // W3C ids by default, so the server continues the trace (roadmap R16)
   const {
-    generateTraceId = generateId,
-    generateSpanId = generateId,
+    generateTraceId = newTraceId,
+    generateSpanId = newSpanId,
     getCurrentTrace,
     serviceName,
   } = options;
@@ -108,8 +110,9 @@ export function createTracingMiddleware(
   return (next) => async function* (context) {
     // Check if there's already tracing metadata
     if (!context.message.metadata.tracing) {
-      // Try to get current trace context
-      const currentTrace = getCurrentTrace?.();
+      // Try to get current trace context: the function of the options, or the trace context of
+      // the caller (a call that a handler makes on a server carries the span of that handler)
+      const currentTrace = getCurrentTrace?.() ?? parseTraceparent(context.message.metadata[TRACEPARENT_METADATA_KEY]) ?? null;
 
       if (currentTrace) {
         // Continue existing trace (create child span)
@@ -132,6 +135,12 @@ export function createTracingMiddleware(
       }
     }
 
+    // The W3C trace context of the call: the server continues this trace (R16)
+    const tracing = context.message.metadata.tracing;
+    if (tracing && isW3cIds(tracing.traceId, tracing.spanId)) {
+      context.message.metadata[TRACEPARENT_METADATA_KEY] = formatTraceparent(tracing.traceId, tracing.spanId);
+    }
+
     // Continue middleware chain
     yield* next(context);
   };

package/src/client/types.ts

@@ -26,7 +26,13 @@ export interface Method {
   /** Operation name (e.g., "get", "create", "update", "delete", "watch") */
   operation: string;
 
-  /** Optional version (e.g., "v1", "v2") */
+  /**
+   * Optional version (e.g., "v1", "v2").
+   *
+   * @deprecated The wire protocol (v1, roadmap R25) has no version of a procedure: the server
+   * ignores this field. A URL strategy can put it in the path. Use a new path for a procedure
+   * that changes in a way that is not compatible.
+   */
   version?: string;
 }
 
@@ -66,6 +72,8 @@ export interface Metadata {
   retry?: {
     attempt: number;
     maxAttempts: number;
+    /** True: a second run of the call changes nothing more, so a retry is safe */
+    idempotent?: boolean;
   };
 
   /** Extensible for custom fields */

package/src/clock.ts

@@ -0,0 +1,21 @@
+/**
+ * The clock of the core (roadmap R35). The retry, the circuit breaker and the WebSocket client
+ * read the time and start their timers only through a clock. Thus a test gives a fake clock, and
+ * the timing is exact and repeatable.
+ *
+ * The clock comes from `@mark1russell7/service/clock` (roadmap R37). The entry imports nothing
+ * else, and it has 228 bytes of gzip. The `fakeClock` of `@mark1russell7/service/testing` fits here.
+ * A `Cancel` of the platform also has `unref`. The circuit breaker uses it for its reset: a breaker
+ * must not keep a process alive for its reset time (BUGS-2026-07 M4).
+ */
+
+import { platformClock, type Cancel, type Clock } from "@mark1russell7/service/clock";
+
+export type { Cancel, Clock };
+
+/**
+ * The clock of the platform: `performance.now()` and `setTimeout`. Its timers keep a Node process
+ * alive, as `setTimeout` does: a script that waits for a retry does not end during the wait. The
+ * `realClock` of the service package is different: its timers do not keep a process alive.
+ */
+export const realClock: Clock = platformClock();

package/src/duration.ts

@@ -0,0 +1,56 @@
+/**
+ * Typed durations (roadmap R11).
+ *
+ * Each public option of this package that is a time takes a `Duration`: a quantity of
+ * `@mark1russell7/quantity` with a time unit. A plain number is a type error, so `timeout: 5`
+ * cannot mean five milliseconds in one place and five seconds in another. The wire keeps
+ * milliseconds (`procedure-timeout`), and the internals convert each duration one time, when an
+ * option is read.
+ *
+ * `@mark1russell7/quantity` has no `Duration` type yet. This alias narrows its `Quantity` to the
+ * time units, so the type also refuses `{ value: 5, unit: "kg" }`.
+ */
+
+import { quantity, valueIn, type Quantity } from "@mark1russell7/quantity";
+
+/** The canonical time units of `@mark1russell7/quantity` that a duration of this package uses. */
+export type TimeUnit = "ns" | "us" | "ms" | "s" | "min" | "h" | "d";
+
+/** A time: a quantity with a time unit. */
+export type Duration = Quantity & { readonly unit: TimeUnit };
+
+const TIME_UNITS: ReadonlySet<string> = new Set<TimeUnit>(["ns", "us", "ms", "s", "min", "h", "d"]);
+
+/** This function makes a duration of milliseconds. */
+export const ms = (value: number): Duration => quantity(value, "ms") as Duration;
+/** This function makes a duration of seconds. */
+export const seconds = (value: number): Duration => quantity(value, "s") as Duration;
+/** This function makes a duration of minutes. */
+export const minutes = (value: number): Duration => quantity(value, "min") as Duration;
+/** This function makes a duration of hours. */
+export const hours = (value: number): Duration => quantity(value, "h") as Duration;
+
+/** True when a value is a duration: a finite number with a time unit. */
+export function isDuration(value: unknown): value is Duration {
+  if (value === null || typeof value !== "object") return false;
+  const { value: amount, unit } = value as { value?: unknown; unit?: unknown };
+  return typeof amount === "number" && Number.isFinite(amount) && typeof unit === "string" && TIME_UNITS.has(unit);
+}
+
+/**
+ * The number of milliseconds of a duration. A value that is not a duration (a plain number, or
+ * a quantity of another kind) throws a `TypeError` that names the option.
+ */
+export function toMs(duration: Duration, option = "duration"): number {
+  if (!isDuration(duration)) {
+    throw new TypeError(
+      `${option} must be a duration such as ms(500) or seconds(2), got ${JSON.stringify(duration)}. Plain numbers are not durations (roadmap R11).`,
+    );
+  }
+  return valueIn(duration, "ms");
+}
+
+/** The milliseconds of an optional duration, or undefined. */
+export function optionalMs(duration: Duration | undefined, option?: string): number | undefined {
+  return duration === undefined ? undefined : toMs(duration, option);
+}

package/src/index.ts

@@ -6,6 +6,10 @@
  *
  * This entry point is for Node. It exports the browser-safe entry point
  * ("@procedures/client/browser") and the server transports, which use `http` and `ws`.
+ *
+ * The `WebSocketTransport` of this entry uses the global `WebSocket`, because some applications
+ * bundle this entry for a browser. The Node entry "@procedures/client/node" has a
+ * `WebSocketTransport` whose sockets are of the `ws` package: a drop ends them at once.
  */
 
 export * from "./browser.js";

package/src/machines.ts

@@ -0,0 +1,186 @@
+/**
+ * The state machines of the core as data (roadmap R35): the connection of the WebSocket client
+ * and the circuit breaker. The documents have the format `mark1russell7.machine/1` of
+ * `@mark1russell7/algebra`. They are the specification, and the code implements them. Their knobs
+ * are the default times of the core (`TIMER_DEFAULTS`), and their timers say which knob gives each
+ * wait.
+ *
+ * The code reports each change of its state as a `MachineTransition` (the option `onTransition`).
+ * `replayTransitions()` replays the reports of a run against a document, so a test finds each
+ * change that the document does not allow. It uses `replay` of `@mark1russell7/algebra/replay`
+ * (roadmap R37). That entry imports nothing else, and it has 418 bytes of gzip.
+ */
+
+import { replay } from "@mark1russell7/algebra/replay";
+import { TIMER_DEFAULTS } from "./timers.js";
+
+/** A change of state that the code reports. It has the fields of a lifecycle event of `@mark1russell7/service`. */
+export interface MachineTransition {
+  /** The id of the document. */
+  readonly machine: string;
+  /** The instance: one connection, one breaker. */
+  readonly instance: string;
+  readonly from: string;
+  readonly on: string;
+  readonly to: string;
+  /** The time of the clock of the instance, in milliseconds. */
+  readonly at: number;
+}
+
+/** A time of a timer: one knob, in a unit. */
+export interface MachineDuration {
+  readonly knob: string;
+  readonly unit: string;
+}
+
+/** A timer of a document: the events that start and stop it, and the event that it gives. */
+export interface MachineTimer {
+  readonly duration: MachineDuration;
+  readonly arms: readonly string[];
+  readonly cancels?: readonly string[] | undefined;
+  readonly fires: string;
+  /** A timer that starts again after it fires, with a longer wait each time. */
+  readonly backoff?: { readonly resets: readonly string[] } | undefined;
+  readonly note?: string | undefined;
+}
+
+/** A transition of a document. */
+export interface MachineTransitionDef {
+  readonly id: string;
+  readonly from: string | readonly string[];
+  readonly on: string | readonly string[];
+  readonly to: string;
+  readonly timer?: string | undefined;
+  readonly note?: string | undefined;
+}
+
+/** A machine document: the subset of `mark1russell7.machine/1` that the core uses. */
+export interface MachineDocument {
+  readonly format: "mark1russell7.machine/1";
+  readonly id: string;
+  readonly title: string;
+  readonly layer: "self";
+  readonly version: string;
+  readonly sources: ReadonlyArray<{ readonly ref: string; readonly rung: "implemented" }>;
+  readonly states: Readonly<Record<string, { readonly initial?: boolean; readonly final?: boolean; readonly note?: string }>>;
+  readonly events: Readonly<Record<string, { readonly kind: "rx" | "tx" | "app" | "timer" | "local"; readonly note?: string }>>;
+  readonly knobs: Readonly<Record<string, { readonly key: string; readonly scope: string; readonly unit: string | null; readonly default: number | null }>>;
+  readonly timers: Readonly<Record<string, MachineTimer>>;
+  readonly transitions: readonly MachineTransitionDef[];
+}
+
+const SOURCE = [{ ref: "packages/client/src (the core implements this document)", rung: "implemented" as const }];
+const ms = (knob: string): MachineDuration => ({ knob, unit: "ms" });
+const client = TIMER_DEFAULTS.webSocketClient;
+
+/** The connection of the WebSocket client (`WebSocketTransport`). */
+export const WEBSOCKET_CONNECTION_MACHINE: MachineDocument = {
+  format: "mark1russell7.machine/1",
+  id: "procedures.machine.websocket-connection",
+  title: "The connection of the WebSocket client",
+  layer: "self",
+  version: "0.2.3",
+  sources: SOURCE,
+  states: {
+    DISCONNECTED: { initial: true, note: "no socket" },
+    CONNECTING: { note: "the handshake, with its time limit" },
+    CONNECTED: { note: "the calls and the heartbeat" },
+    RECONNECTING: { note: "the backoff before the next try" },
+    DISCONNECTING: { note: "close() ends the socket and the calls" },
+  },
+  events: {
+    connect: { kind: "app", note: "the transport starts" },
+    "reconnect-due": { kind: "timer" },
+    open: { kind: "rx", note: "the handshake ends" },
+    drop: { kind: "local", note: "the socket closes, or an error ends it" },
+    "handshake-timeout": { kind: "timer" },
+    "ping-due": { kind: "timer" },
+    pong: { kind: "rx" },
+    "pong-timeout": { kind: "timer", note: "a drop after the last allowed miss" },
+    "give-up": { kind: "local", note: "a drop without reconnect, or without tries left" },
+    close: { kind: "app", note: "close() of the application" },
+    closed: { kind: "local" },
+  },
+  knobs: {
+    connection_timeout: { key: "connectionTimeout", scope: "client", unit: "ms", default: client.connectionTimeoutMs },
+    request_timeout: { key: "requestTimeout", scope: "client", unit: "ms", default: client.requestTimeoutMs },
+    heartbeat_interval: { key: "heartbeat.interval", scope: "client", unit: "ms", default: client.heartbeatIntervalMs },
+    heartbeat_timeout: { key: "heartbeat.timeout", scope: "client", unit: "ms", default: client.heartbeatTimeoutMs },
+    heartbeat_misses: { key: "heartbeat.misses", scope: "client", unit: "count", default: client.heartbeatMisses },
+    reconnect_initial_delay: { key: "reconnect.initialDelay", scope: "client", unit: "ms", default: client.reconnectInitialDelayMs },
+    reconnect_max_delay: { key: "reconnect.maxDelay", scope: "client", unit: "ms", default: client.reconnectMaxDelayMs },
+  },
+  timers: {
+    handshake: { duration: ms("connection_timeout"), arms: ["enter:CONNECTING"], cancels: ["open", "drop", "close"], fires: "handshake-timeout" },
+    reconnect: {
+      duration: ms("reconnect_max_delay"),
+      arms: ["enter:RECONNECTING"],
+      cancels: ["close"],
+      fires: "reconnect-due",
+      backoff: { resets: ["open"] },
+      note: "the longest wait: try n waits a random time up to min(maxDelay, initialDelay × 2^(n-1))",
+    },
+    ping: { duration: ms("heartbeat_interval"), arms: ["enter:CONNECTED", "ping-due"], cancels: ["drop", "close"], fires: "ping-due" },
+    pong: { duration: ms("heartbeat_timeout"), arms: ["ping-due"], cancels: ["pong", "drop", "close"], fires: "pong-timeout" },
+  },
+  transitions: [
+    { id: "connect", from: "DISCONNECTED", on: "connect", to: "CONNECTING" },
+    { id: "reconnect", from: "RECONNECTING", on: "reconnect-due", to: "CONNECTING", timer: "reconnect" },
+    { id: "open", from: "CONNECTING", on: "open", to: "CONNECTED" },
+    {
+      id: "drop",
+      from: ["CONNECTING", "CONNECTED", "RECONNECTING"],
+      on: ["drop", "handshake-timeout", "pong-timeout"],
+      to: "RECONNECTING",
+      note: "the code reports each of them as drop",
+    },
+    { id: "give-up", from: ["CONNECTING", "CONNECTED", "RECONNECTING"], on: "give-up", to: "DISCONNECTED" },
+    { id: "close", from: ["DISCONNECTED", "CONNECTING", "CONNECTED", "RECONNECTING"], on: "close", to: "DISCONNECTING" },
+    { id: "closed", from: "DISCONNECTING", on: "closed", to: "DISCONNECTED" },
+  ],
+};
+
+/** The circuit breaker (`createCircuitBreakerMiddleware`). */
+export const CIRCUIT_BREAKER_MACHINE: MachineDocument = {
+  format: "mark1russell7.machine/1",
+  id: "procedures.machine.circuit-breaker",
+  title: "The circuit breaker",
+  layer: "self",
+  version: "0.2.3",
+  sources: SOURCE,
+  states: {
+    CLOSED: { initial: true, note: "each call goes through. The window counts the failures of availability." },
+    OPEN: { note: "each call fails at once, until the reset time" },
+    HALF_OPEN: { note: "a limited number of probes go through" },
+  },
+  events: {
+    "failure-threshold": { kind: "local", note: "the window has the threshold of failures" },
+    "reset-timeout": { kind: "timer" },
+    "probe-failure": { kind: "local" },
+    "probe-successes": { kind: "local", note: "the threshold of successes of the probes" },
+  },
+  knobs: {
+    failure_threshold: { key: "failureThreshold", scope: "client", unit: "count", default: 5 },
+    failure_window: { key: "failureWindow", scope: "client", unit: "ms", default: TIMER_DEFAULTS.circuitBreaker.failureWindowMs },
+    reset_timeout: { key: "resetTimeout", scope: "client", unit: "ms", default: TIMER_DEFAULTS.circuitBreaker.resetTimeoutMs },
+    success_threshold: { key: "successThreshold", scope: "client", unit: "count", default: 2 },
+  },
+  timers: {
+    reset: { duration: ms("reset_timeout"), arms: ["failure-threshold", "probe-failure"], cancels: ["probe-successes"], fires: "reset-timeout" },
+  },
+  transitions: [
+    { id: "trip", from: "CLOSED", on: "failure-threshold", to: "OPEN" },
+    { id: "reset", from: "OPEN", on: "reset-timeout", to: "HALF_OPEN", timer: "reset" },
+    { id: "reopen", from: "HALF_OPEN", on: "probe-failure", to: "OPEN" },
+    { id: "recover", from: "HALF_OPEN", on: "probe-successes", to: "CLOSED" },
+  ],
+};
+
+/**
+ * This function replays the reported transitions of one document. Each instance starts in the
+ * state that its first transition leaves. Each transition must leave the state where the replay
+ * is, and the document must allow it. The function gives each disagreement.
+ */
+export function replayTransitions(machine: MachineDocument, events: readonly MachineTransition[]): string[] {
+  return replay(machine, events, { machine: machine.id });
+}

package/src/node.ts

@@ -0,0 +1,11 @@
+/**
+ * The Node entry of `@procedures/client`: `@procedures/client/node`.
+ *
+ * This entry exports the client transports with the defaults of Node. Its `WebSocketTransport`
+ * uses the `WebSocket` class of the `ws` package, so a drop ends a socket at once with
+ * `terminate()` (finding of roadmap R36). The other entries keep the global `WebSocket`: a browser
+ * bundle imports `@procedures/client/browser`, and that entry does not import `ws`.
+ */
+
+export { WebSocketTransport } from "./adapters/websocket/client/node.js";
+export type { WebSocketTransportOptions, WebSocketClass } from "./adapters/websocket/client/types.js";

package/src/procedures/capability.ts

@@ -25,16 +25,14 @@ import type {
 } from "./types.js";
 import { pathToKey } from "./types.js";
 import { isDataDriven } from "./ref.js";
+import { inferredEffectsOf } from "./effects.js";
 import { callMatches } from "./policy.js";
 
 /** The standard resource names. An application adds its own names. */
 export const STANDARD_RESOURCES = ["fs", "network", "process", "registry"] as const;
 
-/**
- * The metadata key of the remaining time of a remote call, in milliseconds. A server uses it
- * only to make its deadline earlier.
- */
-export const TIMEOUT_METADATA_KEY = "procedure-timeout";
+// The metadata key of the remaining time of a remote call, in milliseconds (client/deadline.ts)
+export { TIMEOUT_METADATA_KEY } from "../client/deadline.js";
 
 /** The capability without limits: the capability of a host that sets none. */
 export const UNLIMITED_CAPABILITY: Capability = Object.freeze({});
@@ -97,11 +95,12 @@ export interface ToolHints {
 /**
  * The MCP hints of a procedure, from its declared effects. A procedure without a declaration,
  * or a data-driven one (its operands decide what it does), gets no hints: then the MCP defaults
- * apply (not read-only, destructive, open world).
+ * apply (not read-only, destructive, open world). A procedure that `procedure.define` made gets
+ * the hints of the effects that the host found for its body (`inferredEffects`, roadmap R22).
  */
 export function toolHints(procedure: AnyProcedure): ToolHints {
-  const effects = effectsOf(procedure);
-  if (!effects || isDataDriven(procedure)) return {};
+  const effects = isDataDriven(procedure) ? inferredEffectsOf(procedure) : effectsOf(procedure);
+  if (!effects) return {};
   if (isReadOnly(effects)) {
     return { readOnlyHint: true, openWorldHint: isOpenWorld(effects) };
   }