@procedures/client 0.2.3 → 0.4.0

package/src/client/middleware/cache.ts

@@ -8,6 +8,9 @@
 import type { ClientRunner, ClientContext, ResponseItem, Metadata, Method, TypedClientMiddleware } from "../types.js";
 import type { CacheContext } from "./contexts.js";
 import { LruMap } from "./lru.js";
+import { isDuration, optionalMs, type Duration } from "../../duration.js";
+import type { Effects } from "../../procedures/types.js";
+import { TIMER_DEFAULTS } from "../../timers.js";
 
 /**
  * Cache middleware options.
@@ -21,10 +24,10 @@ export interface CacheOptions {
   methods: readonly string[] | ((method: Method) => boolean);
 
   /**
-   * Time-to-live for cache entries in milliseconds. A call can give its own: `cache: { ttl }`.
+   * Time-to-live for cache entries, for example `minutes(1)`. A call can give its own: `cache: { ttl }`.
    * @default 60000 (1 minute)
    */
-  ttl?: number;
+  ttl?: Duration;
 
   /**
    * Maximum number of cache entries (LRU eviction when exceeded).
@@ -39,11 +42,11 @@ export interface CacheOptions {
   onStats?: (stats: CacheStats) => void;
 
   /**
-   * Interval in milliseconds for emitting cache statistics.
+   * Interval for emitting cache statistics.
    * Only used if onStats is provided.
    * @default 60000 (1 minute)
    */
-  statsInterval?: number;
+  statsInterval?: Duration;
 
   /**
    * Custom cache key generator.
@@ -64,6 +67,14 @@ export interface CacheOptions {
    * @returns true if response should be cached
    */
   shouldCache?: (item: ResponseItem<unknown>) => boolean;
+
+  /**
+   * The effects of each method (roadmap R13), for example `effectsIn(registry)`. A call that
+   * writes resources deletes the cached entries of the methods that read one of them, when it
+   * succeeds. An entry of a method with unknown reads goes too. Without this option, a write
+   * deletes nothing, and the entries live until their time to live ends.
+   */
+  effects?: (method: Method) => Effects | undefined;
 }
 
 /**
@@ -110,10 +121,21 @@ export function stableStringify(value: unknown): string {
 }
 
 /**
- * The metadata keys that do not change a response: middleware state and tracing. The other
- * keys (auth, pagination, custom fields) are part of the cache key.
+ * The metadata keys that do not change a response: middleware state, tracing, and the keys of
+ * one call (its idempotency key and the remaining time of its deadline). The other keys (auth,
+ * pagination, custom fields) are part of the cache key.
  */
-const VOLATILE_METADATA = new Set(["retry", "timeout", "tracing", "cache", "circuitBreaker", "rateLimit"]);
+const VOLATILE_METADATA = new Set([
+  "retry",
+  "timeout",
+  "tracing",
+  "cache",
+  "circuitBreaker",
+  "rateLimit",
+  "idempotency-key",
+  "procedure-timeout",
+  "traceparent",
+]);
 
 /** The part of the metadata that can change a response. */
 function keyMetadata(metadata: Metadata): Record<string, unknown> {
@@ -153,6 +175,21 @@ function copyItem<T>(item: ResponseItem<T>): ResponseItem<T> | undefined {
 interface CacheEntry {
   items: ResponseItem<unknown>[];
   expiresAt: number;
+  /** The resources that the method of the entry reads, when the `effects` option knows them */
+  reads: readonly string[] | undefined;
+  /** The method of the entry, for the invalidation by method */
+  method: Method;
+}
+
+/** The deleters of each cache middleware, for `invalidateCache` */
+const invalidators = new WeakMap<object, (matches?: (method: Method) => boolean) => number>();
+
+/**
+ * This function deletes the entries of a cache middleware: all of them, or the entries of the
+ * methods that `matches` selects. It gives the number of deleted entries.
+ */
+export function invalidateCache(middleware: object, matches?: (method: Method) => boolean): number {
+  return invalidators.get(middleware)?.(matches) ?? 0;
 }
 
 /** The overrides of one call: `cache: { ttl, bypass, refresh }` in its context. */
@@ -160,7 +197,7 @@ function cacheOverrides(value: unknown): { ttl?: number; bypass?: boolean; refre
   if (typeof value !== "object" || value === null) return {};
   const { ttl, bypass, refresh } = value as Record<string, unknown>;
   return {
-    ...(typeof ttl === "number" && ttl >= 0 ? { ttl } : {}),
+    ...(isDuration(ttl) && ttl.value >= 0 ? { ttl: optionalMs(ttl, "cache.ttl")! } : {}),
     ...(bypass === true ? { bypass: true } : {}),
     ...(refresh === true ? { refresh: true } : {}),
   };
@@ -199,18 +236,18 @@ function defaultShouldCache(item: ResponseItem<unknown>): boolean {
  * client.use(createCacheMiddleware({
  *   methods: ["users.get", "users.list"], // only these calls are cached
  *   capacity: 100,
- *   ttl: 60000, // 1 minute
+ *   ttl: minutes(1),
  *   onStats: (stats) => console.log(`Hit rate: ${stats.hitRate}%`)
  * }));
  * ```
  */
 export function createCacheMiddleware(options: CacheOptions): TypedClientMiddleware<CacheContext, {}> {
+  const ttl = optionalMs(options.ttl, "ttl") ?? TIMER_DEFAULTS.cache.ttlMs;
+  const statsInterval = optionalMs(options.statsInterval, "statsInterval") ?? TIMER_DEFAULTS.cache.statsIntervalMs;
   const {
     methods,
-    ttl = 60000,
     capacity = 100,
     onStats,
-    statsInterval = 60000,
     keyGenerator = defaultKeyGenerator,
     shouldCache = defaultShouldCache,
   } = options;
@@ -253,11 +290,30 @@ export function createCacheMiddleware(options: CacheOptions): TypedClientMiddlew
       : ((names: ReadonlySet<string>) => (method: Method): boolean => names.has(`${method.service}.${method.operation}`))(
           new Set(methods),
         );
+  const effectsOf = options.effects;
+
+  /**
+   * The calls in flight, by key: a second call with the same key waits for the first one and
+   * gets a copy of its response (roadmap R13). Before, each one made its own request.
+   */
+  const inFlight = new Map<string, Promise<CacheEntry | undefined>>();
 
-  return <TReq, TRes>(next: ClientRunner<TReq, TRes>): ClientRunner<TReq, TRes> => {
+  /** A write that succeeded deletes the entries that read one of its resources (R13). */
+  const invalidateAfterWrite = (method: Method): void => {
+    const writes = effectsOf?.(method)?.writes;
+    if (!writes || writes.length === 0) return;
+    cache.deleteWhere((entry) => entry.reads === undefined || entry.reads.some((resource) => writes.includes(resource)));
+  };
+
+  const middleware = <TReq, TRes>(next: ClientRunner<TReq, TRes>): ClientRunner<TReq, TRes> => {
     return async function* (context: ClientContext<TReq>) {
       if (!cacheable(context.message.method)) {
-        yield* next(context);
+        let failed = false;
+        for await (const item of next(context)) {
+          if (item.status.type === "error") failed = true;
+          yield item;
+        }
+        if (!failed && effectsOf) invalidateAfterWrite(context.message.method);
         return;
       }
 
@@ -294,23 +350,64 @@ export function createCacheMiddleware(options: CacheOptions): TypedClientMiddlew
         cache.delete(cacheKey);
       }
 
+      // The same call is in flight: wait for it and give a copy of its response (R13)
+      const pending = overrides.refresh ? undefined : inFlight.get(cacheKey);
+      if (pending) {
+        const shared = await pending;
+        if (shared) {
+          stats.hits++;
+          setState(true);
+          for (const item of shared.items) yield (copyItem(item) ?? item) as ResponseItem<TRes>;
+          return;
+        }
+        // The first call gave a stream or an error: this call makes its own request
+      }
+
       // Cache miss - fetch and store. Only a response of one item is cached: a stream is never
       // collected or cached (before, the middleware kept every item of a stream in memory).
       stats.misses++;
       let first: ResponseItem<TRes> | undefined;
       let count = 0;
+      let settle: (entry: CacheEntry | undefined) => void = () => undefined;
+      const mine = new Promise<CacheEntry | undefined>((resolve) => (settle = resolve));
+      if (!overrides.refresh) inFlight.set(cacheKey, mine);
+      let entry: CacheEntry | undefined;
+      try {
+        for await (const item of next(context)) {
+          count++;
+          if (count === 1) first = item;
+          yield item;
+        }
+        setState(false);
 
-      for await (const item of next(context)) {
-        count++;
-        if (count === 1) first = item;
-        yield item;
-      }
-      setState(false);
-
-      if (count === 1 && first && shouldCache(first)) {
-        const copy = copyItem(first);
-        if (copy) cache.set(cacheKey, { items: [copy as ResponseItem<unknown>], expiresAt: Date.now() + (overrides.ttl ?? ttl) });
+        // An inner layer that changed the key metadata during the call (an auth middleware
+        // inside the cache) makes the key wrong: such a response is not stored (R13)
+        const keyAfter = keyGenerator(context.message.method, context.message.payload, metadata);
+        if (count === 1 && first && shouldCache(first) && keyAfter === cacheKey) {
+          const copy = copyItem(first);
+          if (copy) {
+            entry = {
+              items: [copy as ResponseItem<unknown>],
+              expiresAt: Date.now() + (overrides.ttl ?? ttl),
+              reads: effectsOf?.(context.message.method)?.reads,
+              method: context.message.method,
+            };
+            cache.set(cacheKey, entry);
+          }
+        }
+      } finally {
+        if (inFlight.get(cacheKey) === mine) inFlight.delete(cacheKey);
+        settle(entry);
       }
     };
   };
+  invalidators.set(middleware, (matches) => {
+    if (!matches) {
+      const size = cache.size;
+      cache.clear();
+      return size;
+    }
+    return cache.deleteWhere((entry) => matches(entry.method));
+  });
+  return middleware;
 }

package/src/client/middleware/circuit-breaker.ts

@@ -12,6 +12,11 @@
 
 import type { ClientMiddleware, ClientRunner, ClientContext, TypedClientMiddleware } from "../types.js";
 import type { CircuitBreakerContext } from "./contexts.js";
+import { optionalMs, type Duration } from "../../duration.js";
+import { isAvailabilityFailure } from "./items.js";
+import { realClock, type Cancel, type Clock } from "../../clock.js";
+import { CIRCUIT_BREAKER_MACHINE, type MachineTransition } from "../../machines.js";
+import { TIMER_DEFAULTS } from "../../timers.js";
 
 /**
  * Circuit breaker state.
@@ -29,16 +34,16 @@ export interface CircuitBreakerOptions {
   failureThreshold?: number;
 
   /**
-   * Time window for counting failures (in milliseconds).
-   * @default 10000 (10 seconds)
+   * Time window for counting failures.
+   * @default 10 seconds
    */
-  failureWindow?: number;
+  failureWindow?: Duration;
 
   /**
-   * Time to wait before attempting to close circuit (in milliseconds).
-   * @default 30000 (30 seconds)
+   * Time to wait before attempting to close circuit.
+   * @default 30 seconds
    */
-  resetTimeout?: number;
+  resetTimeout?: Duration;
 
   /**
    * Number of successful requests required to close circuit from HALF_OPEN.
@@ -55,8 +60,11 @@ export interface CircuitBreakerOptions {
 
   /**
    * Custom error predicate.
-   * Return true if error should count as failure.
-   * @default All errors count as failures
+   * Return true if error should count as failure. An error that is not a failure counts as
+   * nothing: not a failure and not a success.
+   * @default `isAvailabilityFailure`: only UNAVAILABLE, TIMEOUT, a stopped server, a gateway
+   * error and network errors count. An abort or a validation error does not (roadmap R12: before,
+   * every error counted, so a caller that aborted could open the circuit).
    */
   isFailure?: (error: Error) => boolean;
 
@@ -64,12 +72,30 @@ export interface CircuitBreakerOptions {
    * Callback when circuit state changes.
    */
   onStateChange?: (oldState: CircuitState, newState: CircuitState) => void;
+
+  /**
+   * The clock of the window and of the reset (roadmap R35). The default is the clock of the
+   * platform. A test gives a fake clock.
+   */
+  clock?: Clock;
+
+  /**
+   * This function gets each change of the state, with its event, as a transition of
+   * `CIRCUIT_BREAKER_MACHINE` (roadmap R35). A test replays them against the document.
+   */
+  onTransition?: (transition: MachineTransition) => void;
+
+  /** The name of the breaker in its transitions. The default is "circuit-breaker". */
+  name?: string;
 }
 
 /**
  * Failure record for tracking errors.
  */
 interface FailureRecord {
+  /** The time of the monotonic clock: the window uses it */
+  at: number;
+  /** The wall-clock time, for the statistics */
   timestamp: number;
   error: Error;
 }
@@ -114,8 +140,8 @@ export class CircuitBreakerError extends Error {
  * ```typescript
  * client.use(createCircuitBreakerMiddleware({
  *   failureThreshold: 5,      // Open after 5 failures
- *   failureWindow: 10000,      // Within 10 seconds
- *   resetTimeout: 30000,       // Try again after 30 seconds
+ *   failureWindow: seconds(10),  // Within 10 seconds
+ *   resetTimeout: seconds(30),   // Try again after 30 seconds
  *   successThreshold: 2        // Close after 2 successes
  * }));
  * ```
@@ -125,13 +151,13 @@ export function createCircuitBreakerMiddleware(
 ): TypedClientMiddleware<CircuitBreakerContext, {}> {
   const {
     failureThreshold = 5,
-    failureWindow = 10000,
-    resetTimeout = 30000,
     successThreshold = 2,
-    isFailure = () => true,
+    isFailure = isAvailabilityFailure,
     onStateChange,
   } = options;
   const halfOpenMaxRequests = options.halfOpenMaxRequests ?? successThreshold;
+  const failureWindow = optionalMs(options.failureWindow, "failureWindow") ?? TIMER_DEFAULTS.circuitBreaker.failureWindowMs;
+  const resetTimeout = optionalMs(options.resetTimeout, "resetTimeout") ?? TIMER_DEFAULTS.circuitBreaker.resetTimeoutMs;
 
   let state: CircuitState = "CLOSED";
   let failures: FailureRecord[] = [];
@@ -139,23 +165,26 @@ export function createCircuitBreakerMiddleware(
   let totalRequests = 0;
   let probesInFlight = 0;
   let lastStateChange = Date.now();
-  let resetTimer: ReturnType<typeof setTimeout> | null = null;
+  let resetTimer: Cancel | null = null;
+  const clock = options.clock ?? realClock;
+  const instance = options.name ?? "circuit-breaker";
 
   /**
-   * Change circuit state.
+   * Change circuit state. `on` is the event of `CIRCUIT_BREAKER_MACHINE`.
    */
-  function setState(newState: CircuitState): void {
+  function setState(newState: CircuitState, on: string): void {
     const oldState = state;
     state = newState;
     if (oldState !== newState) lastStateChange = Date.now();
 
-    if (oldState !== newState && onStateChange) {
-      onStateChange(oldState, newState);
+    if (oldState !== newState) {
+      options.onTransition?.({ machine: CIRCUIT_BREAKER_MACHINE.id, instance, from: oldState, on, to: newState, at: clock.now() });
+      onStateChange?.(oldState, newState);
     }
 
     // Clear reset timer when moving to CLOSED
     if (newState === "CLOSED" && resetTimer) {
-      clearTimeout(resetTimer);
+      resetTimer();
       resetTimer = null;
     }
   }
@@ -164,22 +193,23 @@ export function createCircuitBreakerMiddleware(
    * Record a failure.
    */
   function recordFailure(error: Error): void {
-    const now = Date.now();
+    // The window uses a monotonic clock: a change of the wall clock does not move it (R12)
+    const now = clock.now();
 
     // Add failure
-    failures.push({ timestamp: now, error });
+    failures.push({ at: now, timestamp: Date.now(), error });
 
     // Remove old failures outside window
-    failures = failures.filter((f) => now - f.timestamp < failureWindow);
+    failures = failures.filter((f) => now - f.at < failureWindow);
 
     if (state === "HALF_OPEN") {
       // Any failure while testing reopens the circuit immediately — don't wait for the full
       // failureThreshold. See documentation/BUGS-2026-07.md (H11).
-      setState("OPEN");
+      setState("OPEN", "probe-failure");
       successes = 0;
       scheduleReset();
     } else if (state === "CLOSED" && failures.length >= failureThreshold) {
-      setState("OPEN");
+      setState("OPEN", "failure-threshold");
       scheduleReset();
     }
   }
@@ -192,14 +222,14 @@ export function createCircuitBreakerMiddleware(
       successes++;
       if (successes >= successThreshold) {
         // Enough successes - close circuit
-        setState("CLOSED");
+        setState("CLOSED", "probe-successes");
         failures = [];
         successes = 0;
       }
     } else if (state === "CLOSED") {
       // Clear old failures on success
-      const now = Date.now();
-      failures = failures.filter((f) => now - f.timestamp < failureWindow);
+      const now = clock.now();
+      failures = failures.filter((f) => now - f.at < failureWindow);
     }
   }
 
@@ -208,15 +238,15 @@ export function createCircuitBreakerMiddleware(
    */
   function scheduleReset(): void {
     if (resetTimer) {
-      clearTimeout(resetTimer);
+      resetTimer();
     }
 
-    resetTimer = setTimeout(() => {
+    resetTimer = clock.after(resetTimeout, () => {
       if (state === "OPEN") {
-        setState("HALF_OPEN");
+        setState("HALF_OPEN", "reset-timeout");
         successes = 0;
       }
-    }, resetTimeout);
+    });
     // Don't keep the event loop alive just for the reset timer. See BUGS-2026-07.md (M4).
     resetTimer.unref?.();
   }
@@ -239,10 +269,10 @@ export function createCircuitBreakerMiddleware(
   }
 
   function getStats(): CircuitBreakerStats {
-    const now = Date.now();
+    const now = clock.now();
     return {
       state,
-      failures: failures.filter((f) => now - f.timestamp < failureWindow).length,
+      failures: failures.filter((f) => now - f.at < failureWindow).length,
       successes,
       totalRequests,
       lastFailureTime: failures.length > 0 ? failures[failures.length - 1]!.timestamp : null,
@@ -257,10 +287,10 @@ export function createCircuitBreakerMiddleware(
       totalRequests++;
       // The state for the other middlewares (CircuitBreakerContext)
       const writeState = (): void => {
-        const now = Date.now();
+        const now = clock.now();
         context.message.metadata["circuitBreaker"] = {
           state,
-          failures: failures.filter((f) => now - f.timestamp < failureWindow).length,
+          failures: failures.filter((f) => now - f.at < failureWindow).length,
           successes,
         };
       };

package/src/client/middleware/contexts.ts

@@ -15,6 +15,8 @@
  * ```
  */
 
+import type { Duration } from "../../duration.js";
+
 // =============================================================================
 // Retry Middleware Context
 // =============================================================================
@@ -29,12 +31,17 @@ export interface RetryContext {
     attempt?: number;
     /** Maximum number of attempts: an override of a call, then the value that the middleware uses */
     maxAttempts?: number;
-    /** An override of the base delay, in milliseconds */
-    delay?: number;
+    /** An override of the base delay */
+    delay?: Duration;
     /** An override of the factor of the delay from one attempt to the next */
     backoffMultiplier?: number;
-    /** An override of the longest delay, in milliseconds */
-    maxDelay?: number;
+    /** An override of the longest delay */
+    maxDelay?: Duration;
+    /**
+     * True: the call can go again after a try with an indeterminate outcome, because a second
+     * run changes nothing more (roadmap R1). It overrides the `idempotent` option of the middleware.
+     */
+    idempotent?: boolean;
   };
 }
 
@@ -51,8 +58,8 @@ export interface RetryContext {
  */
 export interface CacheContext {
   cache: {
-    /** The time-to-live of the entry that this call stores, in milliseconds */
-    ttl?: number;
+    /** The time-to-live of the entry that this call stores */
+    ttl?: Duration;
     /** True: the call skips the cache (no read, no write) */
     bypass?: boolean;
     /** True: the call fetches and replaces the stored response */
@@ -72,10 +79,10 @@ export interface CacheContext {
  */
 export interface TimeoutContext {
   timeout: {
-    /** Overall timeout in milliseconds (if configured) */
-    overall?: number;
-    /** Per-attempt timeout in milliseconds (if configured) */
-    perAttempt?: number;
+    /** The overall timeout (if configured) */
+    overall?: Duration;
+    /** The timeout of each attempt (if configured) */
+    perAttempt?: Duration;
   };
 }
 

package/src/client/middleware/items.ts

@@ -8,6 +8,7 @@
  */
 
 import type { ResponseItem } from "../types.js";
+import { realClock, type Clock } from "../../clock.js";
 
 /** This function makes an error item. */
 export function errorItem<TRes>(id: string, code: string, message: string, retryable: boolean): ResponseItem<TRes> {
@@ -19,6 +20,72 @@ export function abortedItem<TRes>(id: string): ResponseItem<TRes> {
   return errorItem<TRes>(id, "ABORTED", "Request was aborted", false);
 }
 
+/**
+ * What a failed try tells about its request, in the metadata of the error item (`delivery`).
+ * - `not-sent`: the request did not leave the client. A retry is safe.
+ * - `indeterminate`: the request left, and no answer came. The server can have run it, so only
+ *   an idempotent call can go again (the three outcomes of `@mark1russell7/service`).
+ * An error item without the field is an answer of the server: its `retryable` flag decides.
+ */
+export type Delivery = "not-sent" | "indeterminate";
+
+/** The metadata key of the delivery of a failed try. */
+export const DELIVERY_METADATA_KEY = "delivery";
+
+/** This function marks an error item with the delivery of its request. */
+export function withDelivery<TRes>(item: ResponseItem<TRes>, delivery: Delivery): ResponseItem<TRes> {
+  return { ...item, metadata: { ...item.metadata, [DELIVERY_METADATA_KEY]: delivery } };
+}
+
+/** The metadata key of the time that the server asks a client to wait before a retry, in milliseconds. */
+export const RETRY_AFTER_METADATA_KEY = "retry-after";
+
+/** The time that an error item asks a client to wait before a retry, in milliseconds, or undefined. */
+export function retryAfterOf(item: ResponseItem<unknown>): number | undefined {
+  const value = item.metadata?.[RETRY_AFTER_METADATA_KEY];
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+
+/**
+ * The error codes that say that the service is not available: the server is down, busy, slow or
+ * stopping, or the network failed. A circuit breaker counts only these (roadmap R12). An abort,
+ * a validation error, a refusal or an error of the handler says nothing about the health of the
+ * service.
+ */
+const AVAILABILITY_CODES = new Set([
+  "UNAVAILABLE",
+  "TIMEOUT",
+  "SERVER_STOPPED",
+  "SERVICE_UNAVAILABLE",
+  "BAD_GATEWAY",
+  "GATEWAY_TIMEOUT",
+  "NETWORK_ERROR",
+  "CONNECTION_REFUSED",
+  "STREAM_ENDED",
+  // The connection to the other side closed before the call left (roadmap R30: before, the list
+  // did not have this code of R24)
+  "CONNECTION_CLOSED",
+]);
+
+/** True when an error says that the service is not available (see AVAILABILITY_CODES). */
+export function isAvailabilityFailure(error: unknown): boolean {
+  const code = (error as { code?: unknown } | undefined)?.code;
+  if (typeof code === "string" && AVAILABILITY_CODES.has(code)) return true;
+  return isNetworkError(error);
+}
+
+/** The time of a monotonic clock in milliseconds: a change of the wall clock does not move it. */
+export function monotonicNow(): number {
+  const performance = (globalThis as { performance?: { now(): number } }).performance;
+  return performance ? performance.now() : Date.now();
+}
+
+/** The delivery of a failed try, or undefined for an answer of the server. */
+export function deliveryOf(item: ResponseItem<unknown>): Delivery | undefined {
+  const delivery = item.metadata?.[DELIVERY_METADATA_KEY];
+  return delivery === "not-sent" || delivery === "indeterminate" ? delivery : undefined;
+}
+
 const NETWORK_CODES = new Set([
   "ECONNREFUSED",
   "ECONNRESET",
@@ -52,35 +119,63 @@ export function isNetworkError(error: unknown): boolean {
   return /WebSocket (connection closed|disconnected)|Connection timeout/.test(error.message);
 }
 
+/** The network codes that tell that the connection never opened, so no request left. */
+const NOT_SENT_CODES = new Set([
+  "ECONNREFUSED",
+  "ENETUNREACH",
+  "EHOSTUNREACH",
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "UND_ERR_CONNECT_TIMEOUT",
+  "CONNECTION_REFUSED",
+]);
+
+/**
+ * This function tells if a thrown error proves that the request did not leave the client: the
+ * connection was refused, the name did not resolve, or the WebSocket did not open in time.
+ * A reset or a close during the request does not prove it (the request can have arrived).
+ */
+export function isNotSentError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  const code = (error as { code?: unknown }).code;
+  if (typeof code === "string" && NOT_SENT_CODES.has(code)) return true;
+  const cause = (error as { cause?: unknown }).cause;
+  if (cause !== undefined && cause !== error && isNotSentError(cause)) return true;
+  // The WebSocket transport fails a request that waited for a connection that did not come
+  return /^(WebSocket disconnected|Connection timeout)$/.test(error.message);
+}
+
 /**
  * The item that stands for a thrown error, so that `shouldRetry` can decide about it. It is
- * retryable only when the error is a network failure.
+ * retryable only when the error is a network failure. Its delivery tells if the request left.
  */
 export function thrownItem<TRes>(id: string, error: unknown): ResponseItem<TRes> {
   const code = (error as { code?: unknown } | undefined)?.code;
-  return errorItem<TRes>(
+  const item = errorItem<TRes>(
     id,
     typeof code === "string" ? code : "THROWN",
     error instanceof Error ? error.message : String(error),
     isNetworkError(error),
   );
+  return withDelivery(item, isNotSentError(error) ? "not-sent" : "indeterminate");
 }
 
 /**
  * This function waits `ms` milliseconds. It returns false at once when the signal aborts (deep
  * dive TRN-8: before, the backoff of the retry middleware ignored the signal).
  */
-export function sleep(ms: number, signal?: AbortSignal): Promise<boolean> {
+export function sleep(ms: number, signal?: AbortSignal, clock: Clock = realClock): Promise<boolean> {
   if (signal?.aborted) return Promise.resolve(false);
   return new Promise((resolve) => {
     const onAbort = (): void => {
-      clearTimeout(timer);
+      cancel();
       resolve(false);
     };
-    const timer = setTimeout(() => {
+    // The clock of the caller (roadmap R35): a test gives a fake clock
+    const cancel = clock.after(Math.max(0, ms), () => {
       signal?.removeEventListener("abort", onAbort);
       resolve(true);
-    }, Math.max(0, ms));
+    });
     signal?.addEventListener("abort", onAbort, { once: true });
   });
 }