@jxsuite/ai 0.37.2 → 0.39.0

package/src/gateway/chat.ts

@@ -0,0 +1,224 @@
+/**
+ * The chat route: a request from a Jx client in, an SSE stream of normalized frames out.
+ *
+ * @module @jxsuite/ai/gateway
+ */
+
+import { upstreamCacheHints } from "../cache-hints.ts";
+import type { StreamEvent } from "../streaming-client.ts";
+import { fetchFailureFrame, normalizeOpenAIStream } from "./normalize.ts";
+import { problemResponse, refusal } from "./problem.ts";
+import { encodeSse, SSE_HEADERS } from "./sse.ts";
+import type { ChatGatewayOptions, GatewayRefusal, Upstream } from "./types.ts";
+
+/** The refusal's detail for a body that is not JSON. */
+const INVALID_JSON = "Invalid JSON body";
+
+/** The version 1 chat body, as a client sends it. Every member is optional on the wire. */
+interface ChatRequestBody {
+  messages?: unknown;
+  tools?: unknown;
+  systemPrompt?: unknown;
+  model?: unknown;
+}
+
+/** The chat-completions body forwarded upstream. */
+interface UpstreamBody {
+  model: unknown;
+  messages: unknown[];
+  stream: boolean;
+  stream_options: { include_usage: boolean };
+  tools?: unknown;
+  tool_choice?: string;
+  parallel_tool_calls?: boolean;
+  prompt_cache_key?: string;
+}
+
+/**
+ * Whether `resolveUpstream` answered with a refusal rather than an upstream.
+ *
+ * @param {Upstream | GatewayRefusal} value - What `resolveUpstream` returned
+ * @returns {boolean}
+ */
+function isRefusal(value: Upstream | GatewayRefusal): value is GatewayRefusal {
+  return "problem" in value;
+}
+
+/**
+ * Read the request body to the end, or until it passes `limit` bytes, in which case the rest is
+ * never read and the result is null. Measured on the bytes that actually arrive, because a
+ * `Content-Length` is only a claim.
+ *
+ * @param {Request} request - The client's request
+ * @param {number | undefined} limit - The most bytes accepted, or undefined for no limit
+ * @returns {Promise<Uint8Array | null>}
+ */
+async function readBody(request: Request, limit: number | undefined): Promise<Uint8Array | null> {
+  const chunks: Uint8Array[] = [];
+  let length = 0;
+  const reader = request.body?.getReader();
+  if (reader) {
+    for (let chunk = await reader.read(); !chunk.done; chunk = await reader.read()) {
+      length += chunk.value.byteLength;
+      if (limit !== undefined && length > limit) {
+        void reader.cancel();
+        return null;
+      }
+      chunks.push(chunk.value);
+    }
+  }
+  const bytes = new Uint8Array(length);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
+}
+
+/**
+ * The frames of one upstream exchange: the request, then its normalized response, or the one frame
+ * that says why there is no response.
+ *
+ * @param {typeof fetch} upstreamFetch - The fetch to call the upstream with
+ * @param {string} url - The upstream's chat-completions URL
+ * @param {RequestInit} init - The upstream request
+ * @yields {StreamEvent} The route's frames, in wire order
+ */
+async function* exchange(
+  upstreamFetch: typeof fetch,
+  url: string,
+  init: RequestInit,
+): AsyncGenerator<StreamEvent> {
+  let response: Response;
+  try {
+    response = await upstreamFetch(url, init);
+  } catch (error) {
+    yield fetchFailureFrame(error);
+    return;
+  }
+  yield* normalizeOpenAIStream(response);
+}
+
+/**
+ * Build the chat route's handler around a host's policy.
+ *
+ * Each request goes through the same steps in the same order, and the first one that refuses
+ * answers it as `application/problem+json` without contacting the upstream:
+ *
+ * 1. `admit`, before the body is read.
+ * 2. `resolveUpstream`: where the request goes, or why it goes nowhere.
+ * 3. The body is read, stopping at `maxBodyBytes` (413), and parsed as JSON (400 when it is not).
+ * 4. `messages` must be an array (400); its absence reads as an empty one.
+ * 5. `maxMessages` (413).
+ * 6. `onAccepted`.
+ * 7. The stream: a `200 text/event-stream` whose frames are the upstream's response normalized by
+ *    `normalizeOpenAIStream`, or the one frame saying why the upstream could not be reached.
+ *
+ * The version 1 body is forwarded as the OpenAI-compatible request it describes: the system prompt
+ * as a leading `system` message, `stream_options.include_usage` so the provider's own token count
+ * arrives, and `tool_choice: "auto"` with parallel calls whenever tools are offered. When the host
+ * resolved a `sessionAffinity`, it rides along as the prompt-cache hint the upstream's host
+ * understands, and not at all to any other host (`upstreamCacheHints`). The upstream request
+ * carries `context.signal`, so aborting it ends the stream with `done: cancelled`.
+ *
+ * @param {ChatGatewayOptions<C>} options - The host's policy
+ * @returns {(request: Request, context: C) => Promise<Response>}
+ */
+export function createChatHandler<C extends { readonly signal: AbortSignal }>(
+  options: ChatGatewayOptions<C>,
+): (request: Request, context: C) => Promise<Response> {
+  return async (request, context) => {
+    const admitted = await options.admit?.(request, context);
+    if (admitted) {
+      return problemResponse(admitted);
+    }
+
+    const upstream = await options.resolveUpstream(request, context);
+    if (isRefusal(upstream)) {
+      return problemResponse(upstream);
+    }
+
+    // A body that cannot be read is answered as one that cannot be parsed, as it always was.
+    let bytes: Uint8Array | null;
+    try {
+      bytes = await readBody(request, options.maxBodyBytes);
+    } catch {
+      return problemResponse(refusal("invalidRequest", INVALID_JSON));
+    }
+    if (bytes === null) {
+      return problemResponse(
+        refusal(
+          "payloadTooLarge",
+          `The request body is larger than this gateway accepts (${String(options.maxBodyBytes)} bytes).`,
+        ),
+      );
+    }
+    let body: ChatRequestBody;
+    try {
+      /* `ignoreBOM` keeps a leading U+FEFF in the text, so a body that starts with one is invalid
+         JSON, as it was when the server read it with Bun's `req.json()`. The default decoder would
+         strip it and accept the body; this extraction changes no byte a client receives. */
+      const text = new TextDecoder("utf-8", { fatal: false, ignoreBOM: true }).decode(bytes);
+      body = JSON.parse(text) as ChatRequestBody;
+    } catch {
+      return problemResponse(refusal("invalidRequest", INVALID_JSON));
+    }
+
+    /* Defaults apply to an ABSENT member only, so a `null` one is forwarded as sent (and a `null`
+       `messages` is refused below). A body of JSON `null` throws here, as it always has. */
+    const { messages = [], tools = [], systemPrompt = "", model = upstream.defaultModel } = body;
+
+    if (!Array.isArray(messages)) {
+      return problemResponse(refusal("invalidRequest", "messages must be an array"));
+    }
+    if (options.maxMessages !== undefined && messages.length > options.maxMessages) {
+      return problemResponse(
+        refusal(
+          "payloadTooLarge",
+          `The request carries ${String(messages.length)} messages; this gateway accepts at most ${String(options.maxMessages)}.`,
+        ),
+      );
+    }
+
+    options.onAccepted?.(
+      {
+        bytes: bytes.byteLength,
+        messageCount: messages.length,
+        model: String(model),
+        wire: 1,
+      },
+      upstream,
+      context,
+    );
+
+    const upstreamBody: UpstreamBody = {
+      model,
+      messages: [{ role: "system", content: systemPrompt }, ...(messages as unknown[])],
+      stream: true,
+      stream_options: { include_usage: true },
+    };
+    // The wire has always forwarded `tools` as sent, so a non-array with a length passes through.
+    if (tools && (tools as { length: number }).length > 0) {
+      upstreamBody.tools = tools;
+      upstreamBody.tool_choice = "auto";
+      upstreamBody.parallel_tool_calls = true;
+    }
+    const hints = upstreamCacheHints(upstream.baseUrl, upstream.sessionAffinity);
+    Object.assign(upstreamBody, hints.body);
+
+    // Looked up per request, not captured at construction: a host or a test may swap it.
+    const upstreamFetch = options.fetch ?? fetch;
+    const frames = exchange(upstreamFetch, `${upstream.baseUrl}/chat/completions`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${upstream.apiKey}`,
+        ...hints.headers,
+      },
+      body: JSON.stringify(upstreamBody),
+      signal: context.signal,
+    });
+    return new Response(encodeSse(frames), { headers: SSE_HEADERS });
+  };
+}

package/src/gateway/index.ts

@@ -0,0 +1,33 @@
+/**
+ * `@jxsuite/ai/gateway`: the server half of the `ai/chat` and `ai/models` routes, written once.
+ *
+ * Every Jx backend that proxies the assistant to a provider does the same wire work: read the
+ * client's body, forward it as an OpenAI-compatible request, normalize the provider's stream into
+ * the route's frames, and frame those as SSE. Before this module each backend carried its own copy,
+ * and the copies drifted. Now `@jxsuite/server` runs this one, and any other backend can.
+ *
+ * What stays with the host is policy: whose key a request may use, which base URLs are safe to
+ * reach, how requests are admitted, and what the model catalogue says. The host supplies those as
+ * `ChatGatewayOptions`, and the gateway never second-guesses them.
+ *
+ * Worker-safe: it imports `@jxsuite/protocol`'s problem modules and nothing host-bound
+ * (`tests/worker-safety.test.ts`, `tsconfig.worker.json`).
+ *
+ * @module @jxsuite/ai/gateway
+ * @docs extending/embedding/backend-protocol
+ */
+
+export {
+  AI_SESSION_HEADER,
+  affinityKey,
+  isAiSessionId,
+  upstreamCacheHints,
+} from "../cache-hints.ts";
+export { createChatHandler } from "./chat.ts";
+export { modelsResponse } from "./models.ts";
+export { normalizeOpenAIStream } from "./normalize.ts";
+export { problemResponse } from "./problem.ts";
+export { encodeSse } from "./sse.ts";
+export { extractUpstreamErrorMessage } from "./upstream-error.ts";
+export type { UpstreamCacheHints } from "../cache-hints.ts";
+export type { ChatAdmission, ChatGatewayOptions, GatewayRefusal, Upstream } from "./types.ts";

package/src/gateway/models.ts

@@ -0,0 +1,22 @@
+/**
+ * The models route's answer.
+ *
+ * @module @jxsuite/ai/gateway
+ */
+
+import type { AiModelsResponse } from "@jxsuite/protocol/types";
+
+/**
+ * Answer the models route with `body`, always at `200`.
+ *
+ * The models route is a capability probe (ai.md §2.1), so every credential state is a 200: "no
+ * credentials", "credentials lapsed" and "the upstream could not list" are all answers the client
+ * reads, and a non-2xx makes the probe throw. Which catalogue to answer with is the host's business
+ * (its defaults, the upstream's listing, a brokered one); this only fixes the envelope.
+ *
+ * @param {AiModelsResponse} body - The catalogue and the credential state
+ * @returns {Response}
+ */
+export function modelsResponse(body: AiModelsResponse): Response {
+  return Response.json(body, { headers: { "Content-Type": "application/json" }, status: 200 });
+}

package/src/gateway/normalize.ts

@@ -0,0 +1,302 @@
+/**
+ * The OpenAI-compatible stream normalizer: an upstream chat-completions response in, the chat
+ * route's frames out.
+ *
+ * This is `@jxsuite/server`'s normalizer, moved here verbatim (specs/ai.md §2.4), so that every
+ * backend serving the chat route can run the same one. Its frames are frozen by the server's
+ * upstream fixtures (`packages/server/tests/fixtures/ai-upstream/*.server.json`); a change to what
+ * this file yields is a behaviour change and belongs in a change whose spec fragment names it.
+ *
+ * @module @jxsuite/ai/gateway
+ */
+
+import { problemDetails } from "@jxsuite/protocol/problems";
+import type { StreamEvent, StreamUsageEvent } from "../streaming-client.ts";
+import { problemTypeForStatus } from "./problem.ts";
+import { extractUpstreamErrorMessage } from "./upstream-error.ts";
+
+/** A tool-call fragment inside an OpenAI streaming `delta`. */
+interface ToolCallDelta {
+  index: number;
+  id?: string;
+  type?: string;
+  function?: { name?: string; arguments?: string };
+}
+
+/** A single OpenAI chat-completions streaming chunk (the JSON after `data: `). */
+interface OpenAIStreamChunk {
+  choices?: {
+    index?: number;
+    delta?: {
+      content?: string;
+      /** Thinking models' chain-of-thought: DeepSeek and Volcengine spell it this way... */
+      reasoning_content?: string;
+      /** ...and OpenRouter this way. Both carry the same thing. */
+      reasoning?: string;
+      tool_calls?: ToolCallDelta[];
+    };
+    finish_reason?: string | null;
+  }[];
+  /** The count `stream_options.include_usage` asks for, normally a final chunk with no choices. */
+  usage?: {
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    prompt_tokens_details?: { cached_tokens?: number } | null;
+    completion_tokens_details?: { reasoning_tokens?: number } | null;
+  } | null;
+}
+
+/**
+ * Normalize an upstream usage object into a `usage` frame, or null when it carries no count. The
+ * detail figures are included only when the provider sent them: absent is "not said", not zero.
+ *
+ * @param {OpenAIStreamChunk["usage"]} usage - The chunk's `usage` member
+ * @returns {StreamUsageEvent | null}
+ */
+function usageFrame(usage: OpenAIStreamChunk["usage"]): StreamUsageEvent | null {
+  if (!usage || typeof usage.prompt_tokens !== "number") {
+    return null;
+  }
+  const frame: StreamUsageEvent = {
+    type: "usage",
+    inputTokens: usage.prompt_tokens,
+    outputTokens: usage.completion_tokens ?? 0,
+  };
+  const cached = usage.prompt_tokens_details?.cached_tokens;
+  if (typeof cached === "number") {
+    frame.cachedInputTokens = cached;
+  }
+  const reasoning = usage.completion_tokens_details?.reasoning_tokens;
+  if (typeof reasoning === "number") {
+    frame.reasoningTokens = reasoning;
+  }
+  return frame;
+}
+
+/**
+ * The stop reasons the stream reports; any other `finish_reason` keeps it reading.
+ *
+ * @param {string | null | undefined} reason - The chunk's `finish_reason`
+ * @returns {string | null}
+ */
+function stopReasonOf(reason: string | null | undefined): string | null {
+  if (reason === "tool_calls" || reason === "length" || reason === "stop") {
+    return reason;
+  }
+  return null;
+}
+
+/**
+ * The frame for an upstream request that never got a response: `done: cancelled` when it was
+ * aborted, otherwise an `error` frame carrying an `upstreamFailure` problem.
+ *
+ * The frame carries a problem rather than being one: the response began with a 200 long before this
+ * failed, so nothing can change the status now. `message` stays for the readers that already show
+ * it (server.md §4.3).
+ *
+ * @param {unknown} error - What `fetch` rejected with
+ * @returns {StreamEvent}
+ */
+export function fetchFailureFrame(error: unknown): StreamEvent {
+  if ((error as Error).name === "AbortError") {
+    return { type: "done", stopReason: "cancelled" };
+  }
+  const message = `Network error: ${(error as Error).message}`;
+  return { message, problem: problemDetails("upstreamFailure", message), type: "error" };
+}
+
+/**
+ * Normalize an OpenAI-compatible chat-completions response into the chat route's frames.
+ *
+ * - A non-2xx response is one `error` frame: the sentence inside the provider's body as `message`,
+ *   the upstream's own status as `code`, and a problem naming the kind of failure.
+ * - Text is `delta`; chain-of-thought (`reasoning_content`, or `reasoning` at OpenRouter) is
+ *   `reasoning`, forwarded rather than dropped, because DeepSeek's thinking mode requires every
+ *   prior turn's reasoning back on any request carrying `tools`.
+ * - A tool call is `tool_call_start`, then `tool_call_delta` per fragment, then `tool_call_end`.
+ * - The finish reason is REMEMBERED, not acted on: with `include_usage` the count arrives in a chunk
+ *   of its own after the finish, so the stream ends at `[DONE]` or when the body closes. The last
+ *   frames are the open calls' ends, the `usage` count when there is one, then `done`.
+ * - An aborted read is `done: cancelled`; any other failed read is an `error` frame.
+ * - A consumer that stops reading early cancels the upstream body.
+ *
+ * @param {Response} response - The upstream's response to the chat-completions request
+ * @yields {StreamEvent} The route's frames, in wire order
+ */
+export async function* normalizeOpenAIStream(response: Response): AsyncGenerator<StreamEvent> {
+  if (!response.ok) {
+    let errorBody = "";
+    try {
+      errorBody = await response.text();
+    } catch {
+      /* Ignore */
+    }
+    const cleanMessage = extractUpstreamErrorMessage(errorBody, response.statusText);
+    yield {
+      code: String(response.status),
+      message: cleanMessage,
+      // The upstream's own status is preserved in `code`; the problem names the KIND.
+      problem: problemDetails(problemTypeForStatus(response.status), cleanMessage),
+      type: "error",
+    };
+    return;
+  }
+
+  const reader = response.body?.getReader();
+  if (!reader) {
+    yield {
+      message: "No response body from upstream",
+      problem: problemDetails("upstreamFailure", "No response body from upstream"),
+      type: "error",
+    };
+    return;
+  }
+
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  const pendingToolCalls = new Map<number, { id: string; name: string; args: string }>();
+  let stopReason: string | null = null;
+  let usage: StreamUsageEvent | null = null;
+
+  /**
+   * Close every open call.
+   *
+   * @yields {StreamEvent} A `tool_call_end` per open call
+   */
+  function* closePendingToolCalls(): Generator<StreamEvent> {
+    for (const [, tc] of pendingToolCalls) {
+      yield { type: "tool_call_end", id: tc.id };
+    }
+    pendingToolCalls.clear();
+  }
+
+  /**
+   * The stream's last frames: open calls, the count when there is one, then `done`. The count comes
+   * BEFORE `done`, because a reader stops at `done`.
+   *
+   * @yields {StreamEvent} The closing frames, in order
+   */
+  function* finish(): Generator<StreamEvent> {
+    yield* closePendingToolCalls();
+    if (usage) {
+      yield usage;
+    }
+    yield { type: "done", stopReason: stopReason ?? "stop" };
+  }
+
+  /* Whether the loop ended on its own terms. A consumer that stops reading ends a generator through
+     `return()`, which runs `finally` and nothing else; when the server wrote each frame itself, that
+     exit was the next write throwing inside this `try`, so the `catch` cancelled the upstream body.
+     `finally` keeps that: the upstream must not outlive the reader it streams to. */
+  let settled = false;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() || "";
+
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || !trimmed.startsWith("data: ")) {
+          continue;
+        }
+
+        const dataStr = trimmed.slice(6);
+        if (dataStr === "[DONE]") {
+          yield* finish();
+          settled = true;
+          return;
+        }
+
+        let parsed: OpenAIStreamChunk;
+        try {
+          parsed = JSON.parse(dataStr) as OpenAIStreamChunk;
+        } catch {
+          continue;
+        }
+
+        // Usually a final chunk with no choices, but a provider may put it beside the finish.
+        usage = usageFrame(parsed.usage) ?? usage;
+
+        const choice = parsed.choices?.[0];
+        if (!choice) {
+          continue;
+        }
+
+        const { delta } = choice;
+
+        // Text content
+        if (delta?.content) {
+          yield { type: "delta", content: delta.content };
+        }
+
+        /* Chain-of-thought, under either of the two names providers give it. Forwarded rather than
+           dropped: DeepSeek's thinking mode requires every prior turn's reasoning back on any
+           request carrying `tools`, so a proxy that swallows these frames makes the NEXT round a
+           400 the client cannot repair. */
+        const reasoning = delta?.reasoning_content ?? delta?.reasoning;
+        if (typeof reasoning === "string" && reasoning) {
+          yield { type: "reasoning", content: reasoning };
+        }
+
+        // Tool calls
+        if (delta?.tool_calls) {
+          for (const tc of delta.tool_calls) {
+            if (tc.id) {
+              // First appearance
+              const entry = {
+                id: tc.id,
+                name: tc.function?.name || "",
+                args: tc.function?.arguments || "",
+              };
+              pendingToolCalls.set(tc.index, entry);
+
+              yield { type: "tool_call_start", id: tc.id, name: entry.name };
+
+              if (entry.args) {
+                yield { type: "tool_call_delta", id: tc.id, args: entry.args };
+              }
+            } else if (tc.function?.arguments) {
+              // Subsequent fragment
+              const existing = pendingToolCalls.get(tc.index);
+              if (existing) {
+                existing.args += tc.function.arguments;
+                yield { type: "tool_call_delta", id: existing.id, args: tc.function.arguments };
+              }
+            }
+          }
+        }
+
+        // Finish reason: close the calls now, report the reason at the end of the stream.
+        const finished = stopReasonOf(choice.finish_reason);
+        if (finished) {
+          yield* closePendingToolCalls();
+          stopReason = finished;
+        }
+      }
+    }
+
+    // Stream ended without `[DONE]`
+    yield* finish();
+    settled = true;
+  } catch (error) {
+    settled = true;
+    void reader.cancel();
+    if ((error as Error).name === "AbortError") {
+      yield { type: "done", stopReason: "cancelled" };
+      return;
+    }
+    const message = `Stream error: ${(error as Error).message}`;
+    yield { message, problem: problemDetails("upstreamFailure", message), type: "error" };
+  } finally {
+    if (!settled) {
+      void reader.cancel();
+    }
+  }
+}

package/src/gateway/problem.ts

@@ -0,0 +1,80 @@
+/**
+ * How the gateway says no: an RFC 9457 problem response, and the problem type an upstream's status
+ * maps onto.
+ *
+ * @module @jxsuite/ai/gateway
+ */
+
+import { PROBLEM_MEDIA_TYPE } from "@jxsuite/protocol/problem";
+import { problemDetails } from "@jxsuite/protocol/problems";
+import type { ProblemTypeName } from "@jxsuite/protocol/problems";
+import type { GatewayRefusal } from "./types.ts";
+
+/**
+ * A refusal of one declared problem type, answered with that type's own status.
+ *
+ * @param {ProblemTypeName} name - A declared type from `PROBLEM_TYPES`
+ * @param {string} detail - What happened this time; the line a human reads
+ * @returns {GatewayRefusal}
+ */
+export function refusal(name: ProblemTypeName, detail: string): GatewayRefusal {
+  const problem = problemDetails(name, detail);
+  return { problem, status: problem.status };
+}
+
+/**
+ * The response a refusal is answered with: `application/problem+json` at the refusal's status.
+ *
+ * One body satisfies both kinds of client. A problem reader keys on `type` and shows `detail`; an
+ * older reader shows `error` and acts on `code`. So `error` is present whenever `detail` is (it
+ * already is on a problem built by `problemDetails`, and is added here to one built by hand), and
+ * the refusal's `code`, when it has one, rides beside them.
+ *
+ * @param {GatewayRefusal} refused - What was refused, and why
+ * @returns {Response}
+ */
+export function problemResponse(refused: GatewayRefusal): Response {
+  const { code, problem, status } = refused;
+  const body = {
+    ...problem,
+    ...(problem.error === undefined && problem.detail !== undefined
+      ? { error: problem.detail }
+      : {}),
+    ...(code === undefined ? {} : { code }),
+  };
+  // Response.json would send `application/json`; RFC 9457 §3 is what says this body is a problem.
+  return Response.json(body, { headers: { "Content-Type": PROBLEM_MEDIA_TYPE }, status });
+}
+
+/**
+ * The declared type for an upstream provider's status.
+ *
+ * The normalizer needs it for the one failure that arrives with a status of its own: an upstream
+ * that answered non-2xx. The status itself is kept (as the frame's `code`), and the problem names
+ * the KIND of failure, which is the part a client can act on. `@jxsuite/server`'s `problem.ts`
+ * carries the same table for its own routes; `packages/server/tests/ai-api-gateway.test.ts` holds
+ * the two to agreement.
+ *
+ * @param {number} status - The upstream's HTTP status
+ * @returns {ProblemTypeName}
+ */
+export function problemTypeForStatus(status: number): ProblemTypeName {
+  /* Any other status still becomes SOME type, and which side of 500 it falls on is what decides
+     whether the caller is being told it made a mistake or that the upstream did. */
+  return STATUS_TYPES[status] ?? (status >= 500 ? "internalError" : "invalidRequest");
+}
+
+/** The statuses the table distinguishes, each onto a type answered with that same status. */
+const STATUS_TYPES: Readonly<Record<number, ProblemTypeName>> = {
+  400: "invalidRequest",
+  401: "unauthorized",
+  403: "forbidden",
+  404: "notFound",
+  405: "methodNotAllowed",
+  409: "conflict",
+  413: "payloadTooLarge",
+  501: "capabilityUnavailable",
+  502: "upstreamFailure",
+  503: "upstreamFailure",
+  504: "upstreamFailure",
+};