@ultimat3/core 29.4.0 → 30.0.0

package/src/otlp-span-exporter.ts

@@ -7,6 +7,7 @@ import {
   assertFiniteOtlpBound,
   OTLP_SCOPE,
   type OtlpKeyValue,
+  type OtlpPostOptions,
   otlpAttributes,
   otlpEndpoint,
   otlpHeaders,
@@ -110,6 +111,10 @@ export interface OtlpSpanExporterOptions {
   readonly timeoutMs?: number | undefined;
   /** Injected by tests; the preload seals the real one. */
   readonly fetch?: typeof globalThis.fetch | undefined;
+  /** The retry's wait, die and clock, passed to `postOtlp`. Injected by tests. */
+  readonly sleep?: OtlpPostOptions['sleep'];
+  readonly random?: OtlpPostOptions['random'];
+  readonly now?: OtlpPostOptions['now'];
 }
 
 export interface OtlpSpanExporter extends SpanExporter {
@@ -135,6 +140,7 @@ export function otlpSpanExporter(options: OtlpSpanExporterOptions = {}): OtlpSpa
     options.flushIntervalMs ?? 5_000,
   );
   const send = options.fetch ?? globalThis.fetch;
+  const seams = { sleep: options.sleep, random: options.random, now: options.now };
   const queue: ReadableSpan[] = [];
   /** The ONE batch in flight, or `undefined`. Never a chain: see `pump`. */
   let sending: Promise<void> | undefined;
@@ -158,7 +164,7 @@ export function otlpSpanExporter(options: OtlpSpanExporterOptions = {}): OtlpSpa
       });
       return Promise.resolve();
     }
-    return postOtlp({ url, headers, body, timeoutMs, fetch: send });
+    return postOtlp({ url, headers, body, timeoutMs, fetch: send, ...seams });
   };
 
   /**

package/src/otlp.ts

@@ -1,11 +1,9 @@
 // Single responsibility: the pieces both OTLP exporters share — endpoint resolution from the env
-// an operator already sets, header parsing, the OTLP/JSON value encoding, and one POST that never
-// throws. A serialisation, not a vendor (axiom 7), exactly as `metrics-text.ts` is to Prometheus.
+// an operator already sets, header parsing, the OTLP/JSON value encoding, and (from `otlp-post.ts`) one POST that
+// never throws. A serialisation, not a vendor (axiom 7), exactly as `metrics-text.ts` is to Prometheus.
 
 import { assert } from './assert';
-import { renderThrowable } from './error-render';
 import { type CodedErrorInit, UltimateError } from './errors';
-import { logger } from './logger';
 import type { AttributeValue, SpanResource } from './telemetry';
 
 export class OtlpEndpointInvalidError extends UltimateError {
@@ -270,36 +268,5 @@ export function otlpResource(resource: SpanResource): {
 /** The instrumentation scope every signal this package emits belongs to. */
 export const OTLP_SCOPE = Object.freeze({ name: '@ultimat3/core' });
 
-export interface OtlpPostOptions {
-  readonly url: string;
-  readonly headers: Readonly<Record<string, string>>;
-  readonly body: string;
-  readonly timeoutMs: number;
-  readonly fetch: typeof globalThis.fetch;
-}
-
-/**
- * Never throws and never rejects. Telemetry delivery is not the request: a collector that is down
- * must not become the app's outage, and the alternative — an unhandled rejection from a `void`ed
- * promise — takes the process with it on Bun.
- */
-export async function postOtlp(options: OtlpPostOptions): Promise<void> {
-  try {
-    const response = await options.fetch(options.url, {
-      method: 'POST',
-      headers: { ...options.headers },
-      body: options.body,
-      signal: AbortSignal.timeout(options.timeoutMs),
-    });
-    if (!response.ok) {
-      logger.warn('otlp export rejected', { url: options.url, status: response.status });
-    }
-  } catch (failure) {
-    logger.warn('otlp export failed', {
-      url: options.url,
-      // `renderThrowable`: the read that renders a caught value must not itself throw, or the
-      // export failure this catch exists to swallow escapes as an unhandled rejection.
-      error: renderThrowable(failure),
-    });
-  }
-}
+// Delivery, retry included, is its own module; re-exported so the exporters' one import stays.
+export { OTLP_RETRY_STATUSES, type OtlpPostOptions, postOtlp } from './otlp-post';

package/src/outbound-attempt.ts

@@ -0,0 +1,235 @@
+// Single responsibility: ONE attempt of an `outbound()` call — its signal, its hops, its status
+// read as a coded answer, and its body under the idle watchdog and the cap. Every way it can end
+// is classified here, so `retry()` above it reads a code and never an unclassified throw (which
+// it retries: measured, an unclassified throw from a POST ran three attempts).
+
+import { retryAfterSecondsOf } from './client-retry-after';
+import { tryUseContext } from './context';
+import type { DeadlineTimer } from './deadline-signal';
+import { deadlineSignal } from './deadline-signal';
+import { isUltimateError } from './errors';
+import { logger, redactFields } from './logger';
+import type { OutboundSite } from './outbound-errors';
+import {
+  callerDeadline,
+  outboundRedirected,
+  outboundRefused,
+  outboundThrottled,
+  outboundTimeout,
+  outboundTooLarge,
+  outboundUnavailable,
+  outboundUnreachable,
+} from './outbound-errors';
+import type { HopCall } from './outbound-hops';
+import { redactedUrl, sendHops } from './outbound-hops';
+import type { WatchedFailure } from './outbound-read';
+import { watchedBody } from './outbound-read';
+import { readWithinLimit } from './read-capped';
+import { isRetryableStatus } from './retryable-status';
+
+export interface AttemptCall extends HopCall {
+  /** The call's own signal, heard beside the ambient one. */
+  readonly signal: AbortSignal | undefined;
+  /** Monotonic instant the whole call must end by. */
+  readonly endsAt: number;
+  readonly deadlineMs: number;
+  readonly idleMs: number;
+  readonly maxBytes: number;
+  readonly read: 'bytes' | 'stream';
+  readonly now: () => number;
+  readonly timer: DeadlineTimer;
+}
+
+/** What a settled attempt hands up: a 2xx, with its body read or still to be read. */
+export type AttemptAnswer =
+  | { readonly status: number; readonly headers: Headers; readonly bytes: Uint8Array }
+  | {
+      readonly status: number;
+      readonly headers: Headers;
+      readonly stream: ReadableStream<Uint8Array>;
+    };
+
+/** How many bytes of a refusal's body are read for its `meta.detail`, and how much is kept. */
+const DETAIL_READ_BYTES = 1_024;
+const DETAIL_CHARS = 200;
+
+/** The first `DETAIL_READ_BYTES` of a body, the rest cancelled unread: an endless 5xx stays cheap. */
+async function prefixOf(body: ReadableStream<Uint8Array>): Promise<string> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let text = '';
+  try {
+    while (text.length < DETAIL_READ_BYTES) {
+      const next = await reader.read();
+      if (next.done) break;
+      text += decoder.decode(next.value, { stream: true });
+    }
+  } finally {
+    await reader.cancel().catch(() => undefined);
+  }
+  return text;
+}
+
+/** A refusal's body, short and with every credential-named field redacted. Never throws. */
+async function detailOf(body: ReadableStream<Uint8Array>): Promise<string> {
+  let text = '';
+  try {
+    text = await prefixOf(body);
+  } catch {
+    return '';
+  }
+  // A JSON OBJECT, redacted by key, or nothing: raw text is never kept. A body cut at the prefix,
+  // an array, a form (`client_secret=…`) or an HTML page carries a credential no key names.
+  try {
+    const parsed: unknown = JSON.parse(text);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return '';
+    return JSON.stringify(redactFields(parsed as Record<string, unknown>)).slice(0, DETAIL_CHARS);
+  } catch {
+    return '';
+  }
+}
+
+/** The ambient request's time left, in ms, or `Infinity` when it has no deadline. */
+function ambientLeftMs(): number {
+  const ctx = tryUseContext();
+  if (ctx === undefined || ctx.deadlineAt === null) return Number.POSITIVE_INFINITY;
+  return ctx.deadlineAt - ctx.now().getTime();
+}
+
+/** A non-2xx as the code it is. The body has been read for the detail, or cancelled. */
+async function refusalOf(
+  site: OutboundSite,
+  response: Response,
+  body: ReadableStream<Uint8Array>,
+  url: URL,
+): Promise<unknown> {
+  const { status, headers } = response;
+  if (status >= 300 && status < 400) {
+    await body.cancel().catch(() => undefined);
+    const location = headers.get('location');
+    const where = location === null ? 'nowhere' : redactedUrl(new URL(location, url));
+    return outboundRedirected(site, status, where);
+  }
+  if (isRetryableStatus(status)) {
+    const after = retryAfterSecondsOf(headers.get('retry-after'), headers.get('date'));
+    const detail = await detailOf(body);
+    return after === undefined
+      ? outboundUnavailable(site, status, detail)
+      : outboundThrottled(site, status, after, detail);
+  }
+  return outboundRefused(site, status, await detailOf(body));
+}
+
+export async function runAttempt(call: AttemptCall, attempt: number): Promise<AttemptAnswer> {
+  const startedAt = call.now();
+  // The ambient caller's signal and the call's own, each heard; neither composed into one that
+  // could not be undone (`AbortSignal.any` would leave a listener on a long-lived one per call).
+  const outers = [tryUseContext()?.signal, call.signal].filter(
+    (signal): signal is AbortSignal => signal !== undefined,
+  );
+  const gone = (): AbortSignal | undefined => outers.find((signal) => signal.aborted);
+  const outer = {
+    get aborted() {
+      return gone() !== undefined;
+    },
+    get reason(): unknown {
+      return gone()?.reason;
+    },
+  };
+  if (outer.aborted) throw outer.reason;
+  // Whole milliseconds, up: a timer armed for 899.97 ms is a 900 ms deadline read late.
+  const ownLeft = call.endsAt - startedAt;
+  const ambientLeft = ambientLeftMs();
+  // Which bound fires decides the code: the caller's own deadline is no fact about the vendor.
+  const callerBinds = ambientLeft < ownLeft;
+  const timedOut = (): unknown =>
+    callerBinds
+      ? callerDeadline(call.site)
+      : outboundTimeout(call.site, 'deadline', call.deadlineMs);
+  const leftMs = Math.ceil(Math.min(ownLeft, ambientLeft));
+  if (leftMs <= 0) throw timedOut();
+  const local = new AbortController();
+  const forward = (): void => local.abort(outer.reason);
+  for (const signal of outers) signal.addEventListener('abort', forward, { once: true });
+  const deadline = deadlineSignal(leftMs, local.signal, call.timer);
+  let idle = false;
+  let open = true;
+  const release = (): void => {
+    if (!open) return;
+    open = false;
+    deadline[Symbol.dispose]();
+    for (const signal of outers) signal.removeEventListener('abort', forward);
+  };
+  // A caller gone is ITS reason, unchanged (`X_DRAINING` keeps its meaning); else which bound fired.
+  const coded = (error: unknown): unknown => {
+    if (outer.aborted) return outer.reason;
+    if (isUltimateError(error)) return error;
+    if (deadline.timedOut()) return timedOut();
+    if (idle) return outboundTimeout(call.site, 'idle', call.idleMs);
+    return outboundUnreachable(call.site, error);
+  };
+  const failure = (cause: WatchedFailure): unknown => {
+    if (cause.kind === 'too-large') return outboundTooLarge(call.site, call.maxBytes);
+    return coded(cause.kind === 'idle' ? undefined : cause.error);
+  };
+  let status: number | undefined;
+  try {
+    const response = await sendHops(call, deadline.signal);
+    status = response.status;
+    const body = watchedBody(response.body ?? new Blob([]).stream(), {
+      idleMs: call.idleMs,
+      ...(call.read === 'stream' ? { maxBytes: call.maxBytes } : {}),
+      timer: call.timer,
+      signal: deadline.signal,
+      onIdle: () => {
+        idle = true;
+        local.abort();
+      },
+      failure,
+      onSettled: release,
+    });
+    if (status < 200 || status >= 300) throw await refusalOf(call.site, response, body, call.url);
+    if (call.read === 'stream') {
+      logAttempt(call, attempt, startedAt, status, undefined);
+      return { status, headers: response.headers, stream: body };
+    }
+    const read = await readWithinLimit(body, call.maxBytes);
+    if ('over' in read) throw outboundTooLarge(call.site, call.maxBytes);
+    logAttempt(call, attempt, startedAt, status, undefined);
+    return { status, headers: response.headers, bytes: read.bytes };
+  } catch (error) {
+    const thrown = coded(error);
+    logAttempt(call, attempt, startedAt, status, thrown);
+    release();
+    throw thrown;
+  } finally {
+    if (call.read === 'bytes') release();
+  }
+}
+
+/**
+ * One line per attempt: the call's label, never its query or headers. `debug` for an answer,
+ * `warn` for a failure, so a healthy vendor costs no line at the default level.
+ */
+function logAttempt(
+  call: AttemptCall,
+  attempt: number,
+  startedAt: number,
+  status: number | undefined,
+  thrown: unknown,
+): void {
+  const fields = {
+    ...call.site,
+    attempt,
+    ms: Math.round(call.now() - startedAt),
+    ...(status === undefined ? {} : { status }),
+  };
+  if (thrown === undefined) {
+    logger.debug('outbound.attempt', fields);
+    return;
+  }
+  logger.warn('outbound.attempt', {
+    ...fields,
+    code: isUltimateError(thrown) ? thrown.code : 'uncoded',
+  });
+}

package/src/outbound-dial.ts

@@ -0,0 +1,103 @@
+// Single responsibility: where a dial to a URL may land, decided BEFORE the first byte leaves —
+// resolve the name, classify every address it answers by core's one classifier, and pin the
+// connection to an approved address. `@ultimat3/jobs`' webhook target, `@ultimat3/scraping`'s
+// wildcard leg and `outbound({ dial: 'public' })` each held a copy of this; now they call it.
+
+import type { AddressClass } from './address-class';
+import { classifyAddress } from './address-class';
+import { renderThrowable } from './error-render';
+
+/** Every address a hostname answers. Injected in tests: the network is sealed in this repo. */
+export type DialResolve = (hostname: string) => Promise<readonly string[]>;
+
+/** `Bun.dns.lookup` — the runtime's own resolver, every family, every address. The one call site. */
+export const resolveDialHost: DialResolve = async (hostname) =>
+  (await Bun.dns.lookup(hostname)).map((entry) => entry.address);
+
+/** The connection a screened dial makes: an approved address, and the name it proves. */
+export interface DialPin {
+  /** The URL with its host replaced by the approved address. */
+  readonly url: string;
+  /** The original `host[:port]`, sent as the `Host` header. */
+  readonly host: string;
+  /** For `https:` — the certificate is verified against the NAME, not the address. */
+  readonly serverName?: string;
+}
+
+/**
+ * What the screen decided. `unresolved` is a name that did not resolve — a TRANSIENT fact the
+ * caller decides about (a webhook retries it, a scrape refuses it), carrying the resolver's error
+ * when there was one. `refused` names the address CLASS, never the address: a reason reaches a
+ * durable dead-letter row.
+ */
+export type DialVerdict =
+  | { readonly pin: DialPin }
+  | { readonly refused: AddressClass | 'unclassifiable' }
+  | { readonly unresolved: string; readonly error?: unknown };
+
+export interface ScreenDialOptions {
+  readonly resolve?: DialResolve | undefined;
+  /** Skip the class check, still pin: a receiver the app declared to be inside its network. */
+  readonly allowPrivate?: boolean | undefined;
+}
+
+/**
+ * Why `url` may not be dialled as a public vendor, before any name is resolved, or `undefined`.
+ * `http:` only where a dev receiver lives (`local`), and no credentials in the URL: they would ride
+ * every hop and every log line. Asked of each redirect hop as well as the first URL.
+ */
+export function publicUrlRefusal(url: URL, local: boolean): string | undefined {
+  if (url.protocol !== 'https:' && !(local && url.protocol === 'http:')) {
+    return `${url.protocol} is not https:, the only scheme a public dial takes outside a local environment`;
+  }
+  if (url.username !== '' || url.password !== '') {
+    return 'the URL carries credentials, which would ride every hop and every log line';
+  }
+  return undefined;
+}
+
+/** The refusal reason for a verdict that is not a pin, phrased by class, never by address. */
+export function dialRefusalReason(verdict: DialVerdict): string | undefined {
+  if ('refused' in verdict) return `the host resolves to a ${verdict.refused} address`;
+  if ('unresolved' in verdict) return verdict.unresolved;
+  return undefined;
+}
+
+/**
+ * Screen and pin `url`. An address literal is classified as itself; a name is resolved and ONE
+ * address that is not public refuses it, because the socket may pick any of them. Pinned: the
+ * screen approved THESE addresses, and connecting by name would resolve again — a name answering
+ * public here and private to the socket (DNS rebinding) would walk past.
+ */
+export async function screenDial(url: URL, options: ScreenDialOptions = {}): Promise<DialVerdict> {
+  const hostname = url.hostname.replace(/^\[|\]$/g, '');
+  let addresses: readonly string[];
+  if (classifyAddress(hostname) !== undefined) {
+    addresses = [hostname];
+  } else {
+    try {
+      addresses = await (options.resolve ?? resolveDialHost)(hostname);
+    } catch (error) {
+      return { unresolved: `could not resolve the host: ${renderThrowable(error)}`, error };
+    }
+    if (addresses.length === 0) return { unresolved: 'the host resolved to no address' };
+  }
+  if (options.allowPrivate !== true) {
+    const refused = addresses
+      .map(
+        (address): AddressClass | 'unclassifiable' => classifyAddress(address) ?? 'unclassifiable',
+      )
+      .find((kind) => kind !== 'public');
+    if (refused !== undefined) return { refused };
+  }
+  const pinned = addresses[0] ?? hostname;
+  const target = new URL(url.href);
+  target.hostname = pinned.includes(':') ? `[${pinned}]` : pinned;
+  return {
+    pin: {
+      url: target.href,
+      host: url.host,
+      ...(url.protocol === 'https:' ? { serverName: hostname } : {}),
+    },
+  };
+}

package/src/outbound-errors.ts

@@ -0,0 +1,193 @@
+// Single responsibility: the ten refusals `outbound()` can end on, each built from the call's
+// redacted label. Never a query string, never a header: a cause reaches a log store and a
+// problem document, and a signed URL's query is the credential.
+
+import { renderFixShellArg, renderThrowable } from './error-render';
+import { registerErrorRetry } from './error-retry';
+import { UltimateError } from './errors';
+
+/**
+ * The ten codes' retry classes, registered HERE and not in `error-retry.ts`'s core table: that
+ * table rides every browser page, and these are server-only (axiom 6). The transport faults are
+ * retryable, a stated delay is `retry-after`, and every answer the same request gets again is
+ * terminal — unclassified, `retry()` would replay a 401 three times.
+ */
+registerErrorRetry({
+  X_OUTBOUND_TIMEOUT: 'retryable',
+  X_OUTBOUND_UNREACHABLE: 'retryable',
+  X_OUTBOUND_UNAVAILABLE: 'retryable',
+  X_OUTBOUND_THROTTLED: 'retry-after',
+  X_OUTBOUND_REFUSED: 'terminal',
+  X_OUTBOUND_TOO_LARGE: 'terminal',
+  X_OUTBOUND_HOST_BLOCKED: 'terminal',
+  X_OUTBOUND_REDIRECTED: 'terminal',
+  X_OUTBOUND_RETRY_UNSAFE: 'terminal',
+  X_OUTBOUND_BODY_INVALID: 'terminal',
+});
+
+/** What a failure may say about the call: who, how, and where, never the query or a header. */
+export interface OutboundSite {
+  readonly vendor: string;
+  readonly method: string;
+  readonly origin: string;
+  readonly path: string;
+}
+
+/** `resend POST https://api.resend.com/emails` — the one spelling every cause opens with. */
+export const siteLabel = (site: OutboundSite): string =>
+  `${site.vendor} ${site.method} ${site.origin}${site.path}`;
+
+const siteMeta = (site: OutboundSite): Readonly<Record<string, string>> => ({
+  vendor: site.vendor,
+  method: site.method,
+  origin: site.origin,
+  path: site.path,
+});
+
+/** Which bound ran out: the whole call's `deadlineMs`, or a body that went quiet for `idleMs`. */
+export type OutboundTimeoutPhase = 'deadline' | 'idle';
+
+export function outboundTimeout(
+  site: OutboundSite,
+  phase: OutboundTimeoutPhase,
+  boundMs: number,
+): UltimateError {
+  const bound = phase === 'deadline' ? 'deadlineMs' : 'idleMs';
+  const what =
+    phase === 'deadline'
+      ? `did not finish within its deadline of ${String(boundMs)} ms, retries and waits included`
+      : `sent no body bytes for ${String(boundMs)} ms`;
+  return new UltimateError({
+    code: 'X_OUTBOUND_TIMEOUT',
+    cause: `${siteLabel(site)} ${what}`,
+    fix: `outbound({ url, vendor: '${site.vendor}', dial, ${bound}: ${String(boundMs * 2)} })   # raise ${bound} on this call, or check the vendor's latency`,
+    meta: { ...siteMeta(site), phase, [bound]: boundMs },
+  });
+}
+
+/**
+ * A transport failure in its own words with every query string cut (`?…`): a runtime's message
+ * may quote the URL it was dialling, and the query is where a signed URL keeps its credential.
+ */
+const transportText = (error: unknown): string =>
+  renderThrowable(error).replaceAll(/\?[^\s"'`)]*/g, '?…');
+
+/** The refusals that say the CALLER's bound ran out, not the vendor: a breaker hears nothing. */
+const CALLER_BOUND = new WeakSet<UltimateError>();
+
+/** Whether `error` is `callerDeadline`'s: the caller's time ran out, nothing about the vendor. */
+export const isCallerBound = (error: unknown): boolean =>
+  error instanceof UltimateError && CALLER_BOUND.has(error);
+
+/**
+ * The AMBIENT deadline was the binding bound and it ran out — the request's or a `bound`'s, never
+ * `deadlineMs`. Core's `X_TIMEOUT`, the code the caller's own deadline already answers with.
+ */
+export function callerDeadline(site: OutboundSite): UltimateError {
+  const error = new UltimateError({
+    code: 'X_TIMEOUT',
+    cause: `the caller's own deadline ran out before ${siteLabel(site)} answered; its deadlineMs was not the bound that fired`,
+    fix: 'configureHttp({ requestTimeoutMs: 60_000 })   # at module scope in a file under apps/*/, if the request deadline is the one that is too short for this vendor',
+    meta: { ...siteMeta(site), bound: 'caller' },
+  });
+  CALLER_BOUND.add(error);
+  return error;
+}
+
+export function outboundUnreachable(site: OutboundSite, error: unknown): UltimateError {
+  return new UltimateError({
+    code: 'X_OUTBOUND_UNREACHABLE',
+    cause: `${siteLabel(site)} got no response: ${transportText(error)}`,
+    fix: `curl -sS -m 5 -o /dev/null ${renderFixShellArg(site.origin, '<vendor origin>')}   # reachable from here? else check the egress rule and ${site.vendor}'s status, then re-run the call`,
+    meta: siteMeta(site),
+    sourceError: error,
+  });
+}
+
+export function outboundThrottled(
+  site: OutboundSite,
+  status: number,
+  retryAfterSeconds: number,
+  detail = '',
+): UltimateError {
+  return new UltimateError({
+    code: 'X_OUTBOUND_THROTTLED',
+    cause: `${siteLabel(site)} answered ${String(status)} and asked to wait ${String(retryAfterSeconds)} s`,
+    fix: `await Bun.sleep(${String(retryAfterSeconds * 1000)})   # then call ${site.vendor} again, or lower the call rate at the site that calls outbound()`,
+    meta: { ...siteMeta(site), status, retryAfterSeconds, detail },
+  });
+}
+
+export function outboundUnavailable(
+  site: OutboundSite,
+  status: number,
+  detail = '',
+): UltimateError {
+  return new UltimateError({
+    code: 'X_OUTBOUND_UNAVAILABLE',
+    cause: `${siteLabel(site)} answered ${String(status)} on every attempt: the vendor's fault, not the request's`,
+    fix: `curl -sS -m 5 -o /dev/null -w '%{http_code}\\n' ${renderFixShellArg(site.origin, '<vendor origin>')}   # the vendor's fault: re-run the call; if ${String(status)} persists, check ${site.vendor}'s status page`,
+    meta: { ...siteMeta(site), status, detail },
+  });
+}
+
+export function outboundRefused(site: OutboundSite, status: number, detail: string): UltimateError {
+  return new UltimateError({
+    code: 'X_OUTBOUND_REFUSED',
+    cause: `${siteLabel(site)} answered ${String(status)}, and the same request will get it again`,
+    fix:
+      status === 401
+        ? `outbound({ url, vendor: '${site.vendor}', headers: { authorization } })   # with a refreshed credential, then call again`
+        : `outbound({ url, vendor: '${site.vendor}', body })   # with the request fixed from meta.detail and meta.status`,
+    meta: { ...siteMeta(site), status, detail },
+  });
+}
+
+export function outboundTooLarge(site: OutboundSite, maxBytes: number): UltimateError {
+  return new UltimateError({
+    code: 'X_OUTBOUND_TOO_LARGE',
+    cause: `${siteLabel(site)} answered more than ${String(maxBytes)} bytes; the read stopped at the cap`,
+    fix: `outbound({ url, vendor: '${site.vendor}', dial, deadlineMs, maxBytes: ${String(maxBytes * 4)} })   # or read: 'stream' to consume it in chunks`,
+    meta: { ...siteMeta(site), maxBytes },
+  });
+}
+
+export function outboundHostBlocked(site: OutboundSite, reason: string): UltimateError {
+  return new UltimateError({
+    code: 'X_OUTBOUND_HOST_BLOCKED',
+    cause: `${siteLabel(site)} was refused before dialling: ${reason}`,
+    fix: `outbound({ url, vendor: '${site.vendor}', dial: 'named' })   # for a host this app names in code; otherwise give it a public https:// URL`,
+    meta: { ...siteMeta(site), reason },
+  });
+}
+
+export function outboundRedirected(
+  site: OutboundSite,
+  status: number,
+  location: string,
+): UltimateError {
+  return new UltimateError({
+    code: 'X_OUTBOUND_REDIRECTED',
+    cause: `${siteLabel(site)} answered ${String(status)} towards ${location}, and redirects are not followed by default`,
+    fix: `outbound({ url, vendor: '${site.vendor}', redirect: 'follow' })   # or call the Location the cause names directly`,
+    meta: { ...siteMeta(site), status, location },
+  });
+}
+
+export function outboundRetryUnsafe(site: OutboundSite): UltimateError {
+  return new UltimateError({
+    code: 'X_OUTBOUND_RETRY_UNSAFE',
+    cause: `${siteLabel(site)} was given a retry policy, and a ${site.method} replayed is a second write`,
+    fix: `outbound({ …, idempotent: true, headers: { 'idempotency-key': key } })   # with ${site.vendor}'s key header; or drop retry`,
+    meta: siteMeta(site),
+  });
+}
+
+export function outboundBodyInvalid(site: OutboundSite, issues: readonly string[]): UltimateError {
+  return new UltimateError({
+    code: 'X_OUTBOUND_BODY_INVALID',
+    cause: `${siteLabel(site)} answered a body its schema refused at ${issues.join(', ') || 'the root'}`,
+    fix: `answer.json(schema)   # edit that schema for ${site.vendor}, or ask the vendor whether the response changed`,
+    meta: { ...siteMeta(site), issues },
+  });
+}