@procedures/client 0.35.0 → 0.36.0

package/src/procedures/collection/procedures.ts

@@ -62,6 +62,7 @@ import { collectionChangeTopic, startChangeChain, writeWithChangeEvent } from ".
 import { partitionOfCall, storageOfCall, withPartition, type PartitionInput } from "./partition.js";
 import { admitsRow, admittedStorage, checkAdmission, type CollectionAdmission } from "./admission.js";
 import { patchItem } from "./patch-in-parts.js";
+import { withCollectionRules } from "./hint-filter.js";
 
 // =============================================================================
 // Handler Factory
@@ -125,8 +126,8 @@ export interface CollectionProceduresOptions {
    */
   changeEvents?: boolean | CollectionChangeEventsOptions | undefined;
   /**
-   * The rules of the rows (roadmap CLI-41). `admit` examines each row of each read and of each
-   * change event with values. `guard` examines each write before the storage changes, and a
+   * The rules of the rows (roadmap CLI-41). `admit` examines each row of each read, and each row of
+   * each change event for each subscriber (roadmap CLI-78). `guard` examines each write before the storage changes, and a
    * refused write gets `FORBIDDEN` (reason `write-not-allowed`). With `versionOf`, a guarded write
    * expects the version that the guard read. `maxScanned` stops the scan of a `find` (roadmap
    * CLI-55). Without it, the procedures check only the partition.
@@ -185,7 +186,7 @@ export function createCollectionProcedures(collectionName: string, options: Coll
   checkAdmission(admission);
   /** A write, and then its change event on the bus of the context. The chain of the events belongs to the storage, not to its view. */
   const changing = <R>(ctx: ProcedureContext, partition: string | undefined, storage: CollectionStorage<unknown>, ids: readonly string[] | "*", origin: string | undefined, write: () => Promise<R>): Promise<R> =>
-    writeWithChangeEvent(ctx.bus, storage, topicRule ? topicOf(ctx, partition) : undefined, ids, origin, write, withValues, admission?.admit);
+    writeWithChangeEvent(ctx.bus, storage, topicRule ? topicOf(ctx, partition) : undefined, ids, origin, write, withValues, admission);
   /**
    * The partition and the storage of a call (roadmap CLI-17). The repository of the call has the
    * partitions of the collection and their resolver: the tenant comes from the principal. Each read
@@ -195,10 +196,11 @@ export function createCollectionProcedures(collectionName: string, options: Coll
     const collection = getCollectionFromPath(ctx.path);
     const partition = await partitionOfCall(ctx, collection, input.partition);
     const storage = storageOfCall<unknown>(ctx, collection, partition);
-    return { storage, view: admittedStorage(storage, admission, ctx), partition };
+    return { storage, view: admittedStorage(storage, admission, ctx, partition), partition };
   };
 
-  return [
+  // The rules of the rows on the metadata: the publisher of the events filters each event with them (roadmap CLI-78)
+  return withCollectionRules([
     // Get
     defineProcedure({
       path: [...basePath, "get"],
@@ -485,5 +487,5 @@ export function createCollectionProcedures(collectionName: string, options: Coll
         return changing(ctx, partition, storage, input.ids, input.origin, () => view.deleteBatch(input.ids, writeOptionsOf(input)));
       },
     }),
-  ];
+  ], admission);
 }

package/src/procedures/index.ts

@@ -141,6 +141,9 @@ export {
   // The rules of the rows of a collection (roadmap CLI-41)
   admittedStorage,
   admitsRow,
+  // The images of the rows of a change event, for the row filter of each subscriber (roadmap CLI-78)
+  withHintImages,
+  hintImagesOf,
   DEFAULT_FIND_LIMIT,
   DEFAULT_QUERY_OPERATORS,
   DEFAULT_QUERY_POLICY,
@@ -177,6 +180,8 @@ export type {
   CollectionChangeEvent,
   CollectionAdmission,
   CollectionRow,
+  HintImages,
+  HintRowState,
   CollectionWrite,
   CollectionWriteGuard,
   CollectionPartitions,

package/src/server/error-policy.ts

@@ -0,0 +1,263 @@
+/**
+ * The error policy of a server (roadmap CLI-80): what an error tells the caller when it leaves
+ * the process.
+ *
+ * `Server.handle()` applies the policy to each response, so each face of the server (HTTP,
+ * WebSocket, MCP, a message port, the local face of a host) sends the same error. When
+ * `handle()` throws, or a face fails after it (for example, a value that JSON cannot encode), the
+ * last-resort catch of the face applies the same policy through `lastResortError`. A nested call
+ * of `ctx.client` does not go through `handle()`, so it keeps the real error.
+ *
+ * - `expose: "all"` (the default): each error goes to the caller as before.
+ * - `expose: "coded"`: an error with a known code (`isKnownErrorCode`, or a code of `codes`) goes
+ *   to the caller as it is. Each other error goes to the caller as `INTERNAL_ERROR` with the
+ *   message `"internal error"`, and the server logs it one time.
+ * - `map` runs first. Its result goes to the caller as it is. `undefined` gives the error to
+ *   `expose`.
+ *
+ * The policy reads the real error of a response through the links of `error-response.ts`: the
+ * status object, and the request object with the code and the message of the status. A copy of
+ * the response or of its status keeps a link.
+ */
+
+import type { ProcedurePath } from "../procedures/types.js";
+import { closableUnread } from "../procedures/invoke.js";
+import { isKnownErrorCode } from "../client/errors/registry.js";
+import { errorCodeOf } from "../protocol.js";
+import { errorResponse, realErrorOf } from "./error-response.js";
+import { methodToPath } from "./method.js";
+import { rawErrorOf } from "./last-resort.js";
+export { lastResortError } from "./last-resort.js";
+import { ServerError, type ServerRequest, type ServerResponse } from "./types.js";
+
+/** The error that the caller gets: its code, its message and its retryable flag. A `ServerError` is one. */
+export interface ExposedError {
+  /** The error code, for example `NOT_FOUND`, or a code of the application. */
+  readonly code: string;
+  /** The message that the caller gets. */
+  readonly message: string;
+  /**
+   * True when a retry of the same call can succeed. Without it, the error gets the flag of its
+   * code before the first item of a stream, and false after it (`retryableOf`).
+   */
+  readonly retryable?: boolean | undefined;
+  /** The wait before a retry, in milliseconds, as on an error of a handler (`Retry-After` on HTTP). */
+  readonly retryAfterMs?: number | undefined;
+}
+
+/** The call of an error that leaves the server. */
+export interface ErrorCall {
+  /** The path of the procedure. Empty when the face failed before it knew the call. */
+  readonly path: ProcedurePath;
+  /** The face that took the request (`http`, `websocket`, `port`, `mcp`), when the face tells it. */
+  readonly transport?: string | undefined;
+}
+
+/** The error policy of a server: the option `errors` (roadmap CLI-80). */
+export interface ServerErrorPolicy {
+  /**
+   * Which errors go to the caller as they are:
+   * - `"all"` (the default): each error, with its code and its message, as before.
+   * - `"coded"`: only an error with a known code (`isKnownErrorCode`: `NOT_FOUND`, `FORBIDDEN`,
+   *   `VALIDATION_ERROR`, `CONFLICT` and so on, or a code of `codes`), with its code, its
+   *   message, its retryable flag and its metadata. Each other error goes to the caller as
+   *   `INTERNAL_ERROR` with the message `"internal error"` and its real retryable flag, with
+   *   only the metadata keys of `keepMetadata`. The codes `INTERNAL_ERROR`, `HANDLER_ERROR`, `UNKNOWN`,
+   *   `OUTPUT_VALIDATION_ERROR` and `NO_OUTPUT` tell of a failure of the server, not of a
+   *   refusal, so their message is hidden too. The server gives the real error to its `onError`
+   *   logger one time, or to `console.error` without a logger.
+   */
+  readonly expose?: "all" | "coded" | undefined;
+  /**
+   * The codes of the application that also go to the caller as they are under `"coded"`, for
+   * example `["QUOTA_EXCEEDED"]`.
+   */
+  readonly codes?: readonly string[] | undefined;
+  /**
+   * The metadata keys that a hidden error response or a `map` result keeps from the response: an
+   * allowlist. Each other key goes, also a key that the server does not know (`issues`, a key of
+   * the application). The default is `DEFAULT_KEPT_METADATA`: the trace keys `traceparent` and
+   * `tracestate`.
+   */
+  readonly keepMetadata?: readonly string[] | undefined;
+  /**
+   * This function runs first, for each error that leaves the server. Its result goes to the
+   * caller as it is, also with a code of the application, and with the metadata of an error of a
+   * handler (`retryAfterMs`, the conflicts of a `VERSION_CONFLICT` error). `undefined` gives the
+   * error to `expose`. A function that throws gives `INTERNAL_ERROR`.
+   */
+  readonly map?: ((error: unknown, call: ErrorCall) => ExposedError | undefined) | undefined;
+}
+
+/** The message of a hidden error. */
+export const HIDDEN_ERROR_MESSAGE = "internal error";
+
+/** The codes that tell of a failure of the server, not of a refusal: `"coded"` hides their message. */
+const FAILURE_CODES: ReadonlySet<string> = new Set(["INTERNAL_ERROR", "HANDLER_ERROR", "UNKNOWN", "OUTPUT_VALIDATION_ERROR", "NO_OUTPUT"]);
+
+/** The errors that a logger got: each path logs an error one time. */
+const LOGGED = new WeakSet<object>();
+
+/**
+ * This function records that the logger of the server got this error, so the error policy does
+ * not log it again.
+ *
+ * @internal
+ */
+export function markLogged(error: unknown): void {
+  if (typeof error === "object" && error !== null) LOGGED.add(error);
+}
+
+/** The logger of the hidden errors: the hook `onError` of the server, or `console.error`. */
+export type HiddenErrorLog = (error: unknown, request: ServerRequest<unknown> | undefined) => void;
+
+/** This function gives an error to the logger, when the logger did not get it before. */
+function logOnce(log: HiddenErrorLog, error: unknown, request: ServerRequest<unknown> | undefined): void {
+  if (typeof error === "object" && error !== null && LOGGED.has(error)) return;
+  markLogged(error);
+  log(error, request);
+}
+
+/** True when the policy can change a response: `"coded"`, or a `map` function. */
+export function policyActs(policy: ServerErrorPolicy | undefined): policy is ServerErrorPolicy {
+  return policy !== undefined && (policy.expose === "coded" || policy.map !== undefined);
+}
+
+/**
+ * The call of a request, for `map`.
+ *
+ * @internal
+ */
+export function callOf(request: ServerRequest<unknown> | undefined): ErrorCall {
+  if (request === undefined) return { path: [] };
+  let path: ProcedurePath;
+  try {
+    path = methodToPath(request.method);
+  } catch {
+    path = [];
+  }
+  return request.transport !== undefined ? { path, transport: request.transport } : { path };
+}
+
+/** The decision of the policy for one error. */
+type Decision =
+  | { readonly kind: "keep" }
+  | { readonly kind: "replace"; readonly error: ExposedError }
+  | { readonly kind: "hide" };
+
+/**
+ * The decision of the policy for one error. `code` is the code that the error has on the wire. A
+ * `map` result is final. `"coded"` keeps an error with a code of `codes`, or with a known code
+ * that is not a failure code.
+ */
+function decide(policy: ServerErrorPolicy, error: unknown, code: string, call: ErrorCall, logMapError: (error: unknown) => void): Decision {
+  if (policy.map) {
+    let mapped: ExposedError | undefined;
+    try {
+      mapped = policy.map(error, call);
+    } catch (mapError) {
+      logMapError(mapError);
+      return { kind: "hide" };
+    }
+    if (mapped !== undefined) return { kind: "replace", error: mapped };
+  }
+  if (policy.expose !== "coded") return { kind: "keep" };
+  if (policy.codes?.includes(code) === true) return { kind: "keep" };
+  if (isKnownErrorCode(code) && !FAILURE_CODES.has(code)) return { kind: "keep" };
+  return { kind: "hide" };
+}
+
+/** A `map` result as an error: a result that is not an `Error` becomes one, with its fields. */
+function errorOfResult(result: ExposedError): Error {
+  return result instanceof Error ? result : Object.assign(new Error(result.message), result);
+}
+
+/** The metadata keys that a hidden error response keeps by default: the trace keys (CLI-80). */
+export const DEFAULT_KEPT_METADATA: readonly string[] = ["traceparent", "tracestate"];
+
+/** The metadata of a response with only the keys of the allowlist `keepMetadata` of the policy. */
+function keptMetadata(policy: ServerErrorPolicy, metadata: ServerResponse<unknown>["metadata"]): ServerResponse<unknown>["metadata"] {
+  const keys = policy.keepMetadata ?? DEFAULT_KEPT_METADATA;
+  const kept: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(metadata ?? {})) if (keys.includes(key)) kept[key] = value;
+  return kept as ServerResponse<unknown>["metadata"];
+}
+
+/**
+ * This function applies the error policy to a response that leaves the server: to an error
+ * status, and to the error that ends a stream.
+ *
+ * @internal
+ */
+export function exposedResponse<T>(policy: ServerErrorPolicy, request: ServerRequest<unknown>, response: ServerResponse<T>, log: HiddenErrorLog): ServerResponse<T> {
+  const status = response.status;
+  if (status.type === "error") {
+    // A response that the server made without an error (a refusal of the token, a duplicate
+    // stream), or a status without the link, gives `map` a ServerError of its status
+    const link = realErrorOf(response, request);
+    const real = link.found ? link.error : new ServerError(status.message, status.code, status.retryable);
+    const decision = decide(policy, real, status.code, callOf(request), (mapError) => logOnce(log, mapError, request));
+    if (decision.kind === "keep") return response;
+    const { stream: _stream, payload: _payload, ...rest } = response;
+    // Only the keys of the allowlist stay (the trace keys): an unknown key can tell of the error
+    const kept = keptMetadata(policy, response.metadata);
+    if (decision.kind === "replace") {
+      // The usual error response of the result: its wait and its conflicts go out too
+      const built = errorResponse(response.id, errorOfResult(decision.error));
+      return { ...rest, status: built.status, metadata: { ...kept, ...built.metadata } };
+    }
+    logOnce(log, real, request);
+    return {
+      ...rest,
+      // The retryable flag tells nothing private: a transient failure stays retryable
+      status: { type: "error", code: "INTERNAL_ERROR", message: HIDDEN_ERROR_MESSAGE, retryable: status.retryable },
+      metadata: kept,
+    };
+  }
+  if (response.stream === undefined) return response;
+  return { ...response, stream: exposedStream(policy, request, response.stream, log) };
+}
+
+/**
+ * The items of a stream, with the error policy for the error that ends it. A kept error goes on
+ * unchanged. Another error goes on as an error of its exposed code and message.
+ */
+function exposedStream<T>(policy: ServerErrorPolicy, request: ServerRequest<unknown>, items: AsyncIterable<T>, log: HiddenErrorLog): AsyncGenerator<T, void, undefined> {
+  const exposed = (async function* () {
+    try {
+      yield* items;
+    } catch (error) {
+      const decision = decide(policy, error, errorCodeOf(error), callOf(request), (mapError) => logOnce(log, mapError, request));
+      if (decision.kind === "keep") throw error;
+      if (decision.kind === "hide") {
+        logOnce(log, error, request);
+        // The real retryable flag of the error goes on. A last-resort catch that gets this error
+        // does not log it again.
+        const hidden = new ServerError(HIDDEN_ERROR_MESSAGE, "INTERNAL_ERROR", (error as { retryable?: unknown } | null)?.retryable === true);
+        markLogged(hidden);
+        throw hidden;
+      }
+      // Without a flag, the face gives the flag of the code (before the first item) or false
+      throw errorOfResult(decision.error);
+    }
+  })();
+  return closableUnread(exposed, items);
+}
+
+
+/**
+ * The error that a last-resort catch sends under a policy: when `handle()` throws, or when a face
+ * fails after it. `raw` is the error that the face sends without a policy. `map` runs first. Under
+ * `"coded"`, the code of `raw` decides, so `INTERNAL_ERROR` gives `"internal error"`, and the
+ * logger gets the real error one time.
+ */
+export function exposeError(policy: ServerErrorPolicy | undefined, error: unknown, call: ErrorCall, log: (error: unknown) => void, raw: ExposedError = rawErrorOf(error)): ExposedError {
+  if (!policyActs(policy)) return raw;
+  const once: HiddenErrorLog = (logged) => log(logged);
+  const decision = decide(policy, error, raw.code, call, (mapError) => logOnce(once, mapError, undefined));
+  if (decision.kind === "keep") return raw;
+  if (decision.kind === "replace") return decision.error;
+  logOnce(once, error, undefined);
+  return { code: "INTERNAL_ERROR", message: HIDDEN_ERROR_MESSAGE, retryable: raw.retryable === true };
+}
+

package/src/server/error-response.ts

@@ -0,0 +1,91 @@
+/**
+ * The error response of the server, and the link from an error status to its real error (roadmap
+ * CLI-80).
+ *
+ * The error policy of a server (`error-policy.ts`) reads the real error of a response: the error
+ * object that a handler threw, of its own class. Two links lead to it, and neither is a field of
+ * the response, so the wire, a log of the response and a deep comparison never see them:
+ * - The status object of the error response. A copy of the response (`{ ...response, id }`) keeps
+ *   the same status.
+ * - The request object of the call, with the code and the message of the status. A copy of the
+ *   status (`{ ...response.status }`, for example in a middleware or a wrapper) keeps the code
+ *   and the message, so the link holds. A status with another code or message is another error,
+ *   and has no link.
+ * - Without a link (a middleware copied both the request and the status, or made a new error),
+ *   the policy gives `map` a `ServerError` of the code, the message and the retryable flag of the
+ *   status.
+ */
+
+import { InvocationError } from "../procedures/invoke.js";
+import { VERSION_CONFLICTS_METADATA_KEY, versionConflictsOf } from "../procedures/collection/precondition.js";
+import { errorCodeOf, retryableOf } from "../protocol.js";
+import type { ServerResponse } from "./types.js";
+
+/** The real error of each error status that the server made from an error. */
+const ERRORS_OF_STATUSES = new WeakMap<object, unknown>();
+
+/** The last real error of each request, with the code and the message of its status. */
+const ERRORS_OF_REQUESTS = new WeakMap<object, { readonly code: string; readonly message: string; readonly error: unknown }>();
+
+/**
+ * This function records the real error of an error response, for the error policy: by its status
+ * object, and by the request object of the call. The response does not change.
+ *
+ * @internal
+ */
+export function withRealError<T extends ServerResponse<unknown>>(response: T, error: unknown, request?: object): T {
+  ERRORS_OF_STATUSES.set(response.status, error);
+  const status = response.status;
+  if (request !== undefined && status.type === "error") ERRORS_OF_REQUESTS.set(request, { code: String(status.code), message: status.message, error });
+  return response;
+}
+
+/**
+ * The real error of an error status of a request, or `{ found: false }` when no link leads to it.
+ *
+ * @internal
+ */
+export function realErrorOf(response: ServerResponse<unknown>, request?: object): { readonly found: true; readonly error: unknown } | { readonly found: false } {
+  const status = response.status;
+  if (ERRORS_OF_STATUSES.has(status)) return { found: true, error: ERRORS_OF_STATUSES.get(status) };
+  const recorded = request !== undefined ? ERRORS_OF_REQUESTS.get(request) : undefined;
+  if (recorded !== undefined && status.type === "error" && recorded.code === String(status.code) && recorded.message === status.message) return { found: true, error: recorded.error };
+  return { found: false };
+}
+
+/**
+ * The error response of a failed invocation. An invocation error keeps its code
+ * (VALIDATION_ERROR, NOT_EXPOSED, ABORTED and so on). An error of the handler keeps its own code
+ * when it is a string, as for a stream (`WIRE-PROTOCOL.md`). Without a code, it is HANDLER_ERROR.
+ * An error without a retryable flag gets the flag of its code in `ERROR_CODES`, or false (CLI-48).
+ * An in-band end before the first item of a stream gets the same default. After the first item,
+ * an in-band end without a flag gets false (`retryableOf`, CLI-58, CLI-68, `WIRE-PROTOCOL.md`,
+ * section "Error codes"). `request` is the request of the call: the link of the error policy to the
+ * real error (CLI-80).
+ */
+export function errorResponse(id: string, error: unknown, request?: object): ServerResponse<unknown> {
+  // A refusal of the capability says why (CAPABILITIES-2026-10)
+  const reason = error instanceof InvocationError ? error.reason : undefined;
+  // An error can ask the client to wait before a retry: retryAfterMs, in milliseconds (R12)
+  const retryAfterMs = (error as { retryAfterMs?: unknown } | undefined)?.retryAfterMs;
+  const metadata: Record<string, unknown> = reason ? { reason } : {};
+  if (typeof retryAfterMs === "number" && Number.isFinite(retryAfterMs) && retryAfterMs >= 0) metadata["retry-after"] = retryAfterMs;
+  // A VERSION_CONFLICT error tells the current item of each conflict (roadmap CLI-16)
+  const conflicts = versionConflictsOf(error);
+  if (conflicts !== undefined) metadata[VERSION_CONFLICTS_METADATA_KEY] = conflicts;
+  const code = errorCodeOf(error);
+  // The error policy of the server (CLI-80) reads the real error of the response
+  return withRealError({
+    id,
+    status: {
+      type: "error",
+      code,
+      message: error instanceof Error ? error.message : String(error),
+      // An error that says it is retryable stays retryable: before, every error lost the flag (deep
+      // dive TRN-7). Without a flag, the default of the code: UNAVAILABLE stays retryable, and
+      // keeps HTTP 503 (CLI-48). No item went out before this response.
+      retryable: retryableOf(error, 0),
+    },
+    metadata,
+  }, error, request);
+}

package/src/server/index.ts

@@ -40,6 +40,8 @@
 
 export { Server } from "./server.js";
 export type { ServerOptions } from "./server.js";
+export type { ServerErrorPolicy, ExposedError, ErrorCall } from "./error-policy.js";
+export { exposeError, lastResortError, HIDDEN_ERROR_MESSAGE, DEFAULT_KEPT_METADATA } from "./error-policy.js";
 
 export { ProcedureServer, createProcedureServer, STREAM_METADATA_KEY, isUnboundedStream } from "./procedure-server.js";
 export type { ProcedureServerOptions, RegisterProcedureOptions, StorageConfig, StopOptions, StopParts, StorageHandle, UseStorageOptions } from "./procedure-server.js";

package/src/server/last-resort.ts

@@ -0,0 +1,23 @@
+/**
+ * The last-resort catch of a face (roadmap CLI-80): when `handle()` throws, or the face fails after
+ * it. This module has no runtime import, so a face in a browser bundle (for example
+ * `PortTransport`) does not load the error policy and its imports. The policy itself runs in the
+ * server, through `RequestHandler.exposeError`.
+ */
+
+import type { ExposedError } from "./error-policy.js";
+import type { RequestHandler, ServerRequest } from "./types.js";
+
+/** The error that a last-resort catch sends without a policy: `INTERNAL_ERROR` with the message of the error. */
+export function rawErrorOf(error: unknown): ExposedError {
+  return { code: "INTERNAL_ERROR", message: error instanceof Error ? error.message || "Internal server error" : String(error), retryable: false };
+}
+
+/**
+ * The error that the last-resort catch of a face sends: the error policy of the handler
+ * (`RequestHandler.exposeError`, which `Server` has), or `raw` for a handler without one. `raw`
+ * is the error that the face sends without a policy.
+ */
+export function lastResortError(handler: RequestHandler, error: unknown, request: ServerRequest<unknown> | undefined, raw: ExposedError = rawErrorOf(error)): ExposedError {
+  return handler.exposeError ? handler.exposeError(error, request, raw) : raw;
+}

package/src/server/procedure-server.ts

@@ -6,6 +6,9 @@
  */
 
 import { Server, type ServerOptions } from "./server.js";
+import { errorResponse } from "./error-response.js";
+
+export { errorResponse };
 import type { Admission, AmbientCredentials, Credentials, Method, Principal, PrincipalOf, RequestIdentity, ServerHandler, ServerRequest, ServerResponse } from "./types.js";
 import { methodToPath, pathToMethod } from "./method.js";
 import { isLocalCredentials } from "./request-auth.js";
@@ -21,14 +24,13 @@ import { createCollectionProcedures } from "../procedures/collection/procedures.
 import { InvocationError, closableUnread, invokeProcedure, type AdmitItem, type Interceptor, type Invocation } from "../procedures/invoke.js";
 import type { Capability, ClearanceOrder, ProcedureContext, ResourcesOf } from "../procedures/types.js";
 import type { CollectionPartitions } from "../procedures/collection/partition.js";
-import { VERSION_CONFLICTS_METADATA_KEY, versionConflictsOf } from "../procedures/collection/precondition.js";
 import { TIMEOUT_METADATA_KEY, effectsOf, joinNarrowing, narrowCapability } from "../procedures/capability.js";
 import { IdempotencyCache, idempotencyKeyOf, isRepeatable, type IdempotencyOptions } from "../procedures/idempotency.js";
 import { optionalMs, type Duration } from "../duration.js";
 import type { CollectionStorage } from "../procedures/collection/storage.js";
 import { TIMER_DEFAULTS } from "../timers.js";
 import { realClock, type Clock } from "../clock.js";
-import { errorCodeOf, retryableOf } from "../protocol.js";
+import { retryableOf } from "../protocol.js";
 import { EventPublisher, type EventPublisherOptions } from "../events/publisher.js";
 import { getGlobalEventBus } from "../events/bus.js";
 import type { CollectionProceduresOptions } from "../procedures/collection/procedures.js";
@@ -382,41 +384,6 @@ function withRequestTimeout(
   return narrowCapability(capability, { timeoutMs }, order);
 }
 
-/**
- * The error response of a failed invocation. An invocation error keeps its code
- * (VALIDATION_ERROR, NOT_EXPOSED, ABORTED and so on). An error of the handler keeps its own code
- * when it is a string, as for a stream (`WIRE-PROTOCOL.md`). Without a code, it is HANDLER_ERROR.
- * An error without a retryable flag gets the flag of its code in `ERROR_CODES`, or false (CLI-48).
- * An in-band end before the first item of a stream gets the same default. After the first item,
- * an in-band end without a flag gets false (`retryableOf`, CLI-58, CLI-68, `WIRE-PROTOCOL.md`,
- * section "Error codes").
- */
-export function errorResponse(id: string, error: unknown): ServerResponse<unknown> {
-  // A refusal of the capability says why (CAPABILITIES-2026-10)
-  const reason = error instanceof InvocationError ? error.reason : undefined;
-  // An error can ask the client to wait before a retry: retryAfterMs, in milliseconds (R12)
-  const retryAfterMs = (error as { retryAfterMs?: unknown } | undefined)?.retryAfterMs;
-  const metadata: Record<string, unknown> = reason ? { reason } : {};
-  if (typeof retryAfterMs === "number" && Number.isFinite(retryAfterMs) && retryAfterMs >= 0) metadata["retry-after"] = retryAfterMs;
-  // A VERSION_CONFLICT error tells the current item of each conflict (roadmap CLI-16)
-  const conflicts = versionConflictsOf(error);
-  if (conflicts !== undefined) metadata[VERSION_CONFLICTS_METADATA_KEY] = conflicts;
-  const code = errorCodeOf(error);
-  return {
-    id,
-    status: {
-      type: "error",
-      code,
-      message: error instanceof Error ? error.message : String(error),
-      // An error that says it is retryable stays retryable: before, every error lost the flag (deep
-      // dive TRN-7). Without a flag, the default of the code: UNAVAILABLE stays retryable, and
-      // keeps HTTP 503 (CLI-48). No item went out before this response.
-      retryable: retryableOf(error, 0),
-    },
-    metadata,
-  };
-}
-
 // =============================================================================
 // Procedure Server
 // =============================================================================
@@ -977,7 +944,7 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
       return refused ? rateLimitedResponse(request.id, refused) : undefined;
     } catch (error) {
       const message = `The limits of the server cannot admit the call: ${error instanceof Error ? error.message : String(error)}`;
-      return errorResponse(request.id, Object.assign(new Error(message), { code: "INTERNAL_ERROR" }));
+      return errorResponse(request.id, Object.assign(new Error(message), { code: "INTERNAL_ERROR" }), request);
     }
   }
 
@@ -1083,7 +1050,7 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
       );
     }
     const response = await untilAborted(result, request.signal);
-    if (response === undefined) return errorResponse(request.id, new InvocationError("ABORTED", "The request was aborted", procedure.path));
+    if (response === undefined) return errorResponse(request.id, new InvocationError("ABORTED", "The request was aborted", procedure.path), request);
     if (response.stream) {
       return {
         id: request.id,
@@ -1138,7 +1105,7 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
         capability = this.capabilityOf(request);
       } catch (error) {
         const message = `The server cannot narrow the capability of the request: ${error instanceof Error ? error.message : String(error)}`;
-        return errorResponse(request.id, Object.assign(new Error(message), { code: "INTERNAL_ERROR" }));
+        return errorResponse(request.id, Object.assign(new Error(message), { code: "INTERNAL_ERROR" }), request);
       }
       const output = await invokeProcedure(procedure, request.payload, {
         registry: this.procedureRegistry,
@@ -1175,7 +1142,7 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
       }
       return { id: request.id, status: { type: "success", code: 200 }, payload: output.value, metadata: {} };
     } catch (error) {
-      return errorResponse(request.id, error);
+      return errorResponse(request.id, error, request);
     } finally {
       if (!streams) release();
     }