@ultimat3/core 29.4.0 → 30.0.0

package/src/outbound-hops.ts

@@ -0,0 +1,135 @@
+// Single responsibility: one attempt's hops — dial the URL as `dial` says (screened and pinned, or
+// as named), and under `redirect: 'follow'` take each 3xx by hand, re-screening the next address
+// and dropping credentials at an origin change. The platform's own `follow` dials a hop itself,
+// unscreened: measured, a default redirect from a screened name reached loopback.
+
+import type { DialResolve } from './outbound-dial';
+import { publicUrlRefusal, screenDial } from './outbound-dial';
+import type { OutboundSite } from './outbound-errors';
+import { outboundHostBlocked, outboundRedirected, outboundUnreachable } from './outbound-errors';
+import type { OutboundBody, OutboundFetch, OutboundInit } from './outbound-types';
+import { OUTBOUND_MAX_REDIRECTS } from './outbound-types';
+
+export interface HopCall {
+  readonly site: OutboundSite;
+  readonly url: URL;
+  readonly method: string;
+  /** As the caller spelled them; every rule below compares names lower-cased. */
+  readonly headers: Readonly<Record<string, string>>;
+  readonly body: OutboundBody | undefined;
+  readonly dial: 'named' | 'public';
+  readonly redirect: 'error' | 'follow';
+  readonly local: boolean;
+  readonly fetch: OutboundFetch;
+  readonly resolve: DialResolve | undefined;
+}
+
+/**
+ * What a hop to ANOTHER origin may carry: an allow-list, never a strip-list. The fetch standard
+ * strips `authorization` and `cookie`, but a vendor's own credential header (`x-api-key`) went
+ * along to `http://169.254.169.254` in a probe — so everything else is dropped.
+ */
+const CROSS_ORIGIN_KEPT: ReadonlySet<string> = new Set(['accept', 'content-type', 'user-agent']);
+
+const isRedirect = (status: number): boolean =>
+  status === 301 || status === 302 || status === 303 || status === 307 || status === 308;
+
+/**
+ * A path as a cause, `meta` or a log line may show it: the first segment, then only how long the
+ * rest is. A webhook URL keeps its credential IN the path (`/services/T000/B000/XXXX`).
+ */
+export function redactedPath(pathname: string): string {
+  const [first = '', ...rest] = pathname.split('/').filter((segment) => segment !== '');
+  if (rest.length === 0) return `/${first}`;
+  return `/${first}/…(${String(rest.join('/').length)} chars)`;
+}
+
+/** Where a URL points, for a cause or `meta`: origin and the redacted path, never the query. */
+export const redactedUrl = (url: URL): string => `${url.origin}${redactedPath(url.pathname)}`;
+
+interface Target {
+  readonly url: string;
+  readonly host?: string | undefined;
+  readonly serverName?: string | undefined;
+}
+
+/**
+ * The first hop as `dial` says; EVERY later hop screened as a public one, `'named'` included: the
+ * app named the first host, never the one a redirect points at.
+ */
+async function targetFor(call: HopCall, url: URL, hop: number): Promise<Target> {
+  if (call.dial === 'named' && hop === 0) return { url: url.href };
+  const refusal = publicUrlRefusal(url, call.local);
+  if (refusal !== undefined)
+    throw outboundHostBlocked(call.site, `${redactedUrl(url)}: ${refusal}`);
+  const verdict = await screenDial(url, { resolve: call.resolve });
+  if ('refused' in verdict) {
+    throw outboundHostBlocked(
+      call.site,
+      `${url.host} resolves to a ${verdict.refused} address, and a public dial opens only public ones`,
+    );
+  }
+  if ('unresolved' in verdict)
+    throw outboundUnreachable(call.site, verdict.error ?? verdict.unresolved);
+  return verdict.pin;
+}
+
+const discard = async (response: Response): Promise<void> => {
+  try {
+    await response.body?.cancel();
+  } catch {
+    // A redirect's body is nothing the caller waits for; its cancel failing is no failure.
+  }
+};
+
+/** The response the last hop answered. A 3xx comes back as itself under `redirect: 'error'`. */
+export async function sendHops(call: HopCall, signal: AbortSignal): Promise<Response> {
+  let url = call.url;
+  let method = call.method;
+  let body = call.body;
+  let headers: Record<string, string> = { ...call.headers };
+  for (let hop = 0; ; hop += 1) {
+    const target = await targetFor(call, url, hop);
+    const init: OutboundInit = {
+      method,
+      // Last: a pinned request is reached AS the name that was screened.
+      headers:
+        target.host === undefined
+          ? headers
+          : {
+              ...Object.fromEntries(
+                Object.entries(headers).filter(([name]) => name.toLowerCase() !== 'host'),
+              ),
+              host: target.host,
+            },
+      ...(body === undefined ? {} : { body }),
+      ...(target.serverName === undefined ? {} : { tls: { serverName: target.serverName } }),
+      signal,
+      redirect: 'manual',
+    };
+    const response = await call.fetch(target.url, init);
+    const location = response.headers.get('location');
+    if (!isRedirect(response.status) || location === null || call.redirect === 'error') {
+      return response;
+    }
+    await discard(response);
+    const next = new URL(location, url);
+    if (hop + 1 > OUTBOUND_MAX_REDIRECTS) {
+      throw outboundRedirected(call.site, response.status, redactedUrl(next));
+    }
+    if (next.origin !== url.origin) {
+      headers = Object.fromEntries(
+        Object.entries(headers).filter(([name]) => CROSS_ORIGIN_KEPT.has(name.toLowerCase())),
+      );
+    }
+    // 303 always, and 301/302 on a POST: the fetch standard re-sends as a GET with no body.
+    if (response.status === 303 || (method === 'POST' && response.status <= 302)) {
+      method = 'GET';
+      body = undefined;
+      headers = Object.fromEntries(
+        Object.entries(headers).filter(([name]) => name.toLowerCase() !== 'content-type'),
+      );
+    }
+    url = next;
+  }
+}

package/src/outbound-read.ts

@@ -0,0 +1,103 @@
+// Single responsibility: an outbound response body read under two bounds a header-only deadline
+// never gave — an IDLE watchdog (a body that stops sending is abandoned, measured: a stalled body
+// under a header deadline was `still-reading-after-300ms`) and a byte cap, counted as it arrives
+// so nothing past it is held. A bytes read is capped by `read-capped.ts`, the one counting reader.
+
+import type { DeadlineTimer } from './deadline-signal';
+
+export interface WatchedBodyOptions {
+  readonly idleMs: number;
+  /**
+   * The cap a STREAMED body is held to. Absent for a bytes read, which `read-capped.ts`'s
+   * `readWithinLimit` caps itself: the one counting reader, and it never holds an over-cap body.
+   */
+  readonly maxBytes?: number | undefined;
+  readonly timer: DeadlineTimer;
+  /** Ends a pending read at once, as a `source` failure carrying the signal's reason. */
+  readonly signal?: AbortSignal | undefined;
+  /** The gap passed: abort the attempt, so the fetch lets its socket go. */
+  readonly onIdle: () => void;
+  /** The coded error a source failure, an idle gap or the cap becomes for whoever reads. */
+  readonly failure: (cause: WatchedFailure) => unknown;
+  /** Settled once, however the stream ends: read out, cancelled or failed. */
+  readonly onSettled: () => void;
+}
+
+export type WatchedFailure =
+  | { readonly kind: 'idle' }
+  | { readonly kind: 'too-large' }
+  | { readonly kind: 'source'; readonly error: unknown };
+
+/**
+ * `body` behind the watchdog and the cap. Pull-driven, so the timer runs only while a reader is
+ * WAITING on the vendor: a consumer slow to pull is its own business, never the vendor's idle gap.
+ * The gap and `signal` end a pending read THEMSELVES, rather than trusting the source to reject
+ * when its fetch is aborted: a body that ignores the abort must not hold the reader past its bound.
+ */
+export function watchedBody(
+  body: ReadableStream<Uint8Array>,
+  options: WatchedBodyOptions,
+): ReadableStream<Uint8Array> {
+  const reader = body.getReader();
+  const { signal } = options;
+  let total = 0;
+  let settled = false;
+  const settle = (): void => {
+    if (settled) return;
+    settled = true;
+    options.onSettled();
+  };
+  const fail = (
+    controller: ReadableStreamDefaultController<Uint8Array>,
+    cause: WatchedFailure,
+  ): void => {
+    controller.error(options.failure(cause));
+    settle();
+    reader.cancel().catch(() => undefined);
+  };
+  return new ReadableStream<Uint8Array>({
+    pull: (controller) =>
+      new Promise<void>((done) => {
+        let finished = false;
+        const finish = (): boolean => {
+          if (finished) return false;
+          finished = true;
+          options.timer.clear(handle);
+          signal?.removeEventListener('abort', aborted);
+          return true;
+        };
+        const stop = (cause: WatchedFailure): void => {
+          if (!finish()) return;
+          if (cause.kind === 'idle') options.onIdle();
+          fail(controller, cause);
+          done();
+        };
+        const aborted = (): void => stop({ kind: 'source', error: signal?.reason });
+        const handle = options.timer.set(() => stop({ kind: 'idle' }), options.idleMs);
+        if (signal?.aborted === true) return aborted();
+        signal?.addEventListener('abort', aborted, { once: true });
+        reader.read().then(
+          (next) => {
+            if (!finish()) return;
+            if (next.done) {
+              controller.close();
+              settle();
+              return done();
+            }
+            total += next.value.byteLength;
+            if (options.maxBytes !== undefined && total > options.maxBytes) {
+              fail(controller, { kind: 'too-large' });
+            } else {
+              controller.enqueue(next.value);
+            }
+            done();
+          },
+          (error: unknown) => stop({ kind: 'source', error }),
+        );
+      }),
+    async cancel(reason): Promise<void> {
+      settle();
+      await reader.cancel(reason).catch(() => undefined);
+    },
+  });
+}

package/src/outbound-subpath.ts

@@ -0,0 +1,26 @@
+// Single responsibility: the `@ultimat3/core/outbound` entry — the outbound call, the dial screen
+// and the undoable deadline signal, and nothing else. A subpath, never the barrel: core is in every
+// bundle graph and this reads `Bun.dns` (axiom 6). `outbound-subpath.test.ts` pins the split.
+
+export type { DeadlineSignal, DeadlineTimer } from './deadline-signal';
+export { deadlineSignal, platformDeadlineTimer } from './deadline-signal';
+export { outbound, outboundResponse } from './outbound';
+export type { DialPin, DialResolve, DialVerdict, ScreenDialOptions } from './outbound-dial';
+export { publicUrlRefusal, resolveDialHost, screenDial } from './outbound-dial';
+export type { OutboundSite, OutboundTimeoutPhase } from './outbound-errors';
+export type {
+  OutboundAnswer,
+  OutboundBody,
+  OutboundDeps,
+  OutboundFetch,
+  OutboundInit,
+  OutboundMethod,
+  OutboundRequest,
+  OutboundStreamAnswer,
+} from './outbound-types';
+export {
+  OUTBOUND_IDLE_MS,
+  OUTBOUND_MAX_BYTES,
+  OUTBOUND_MAX_REDIRECTS,
+  OUTBOUND_RETRY,
+} from './outbound-types';

package/src/outbound-types.ts

@@ -0,0 +1,108 @@
+// Single responsibility: the shapes of one `outbound()` call — the request, the injected seams and
+// the answer — plus the defaults they fall back to. Types and constants only, so the attempt, the
+// call and a caller's wrapper can share them without importing each other.
+
+import type { Schema } from '@ultimat3/schema';
+import type { Random } from './backoff';
+import type { Breaker } from './breaker';
+import type { DeadlineTimer } from './deadline-signal';
+import type { DialResolve } from './outbound-dial';
+import type { RetryPolicy } from './retry-loop';
+
+export type OutboundMethod = 'GET' | 'HEAD' | 'PUT' | 'DELETE' | 'POST' | 'PATCH' | 'OPTIONS';
+
+/** Re-sendable bodies only: a retry or a 307 hop sends the body again, and a stream cannot. */
+export type OutboundBody =
+  | string
+  | Uint8Array<ArrayBuffer>
+  | ArrayBuffer
+  | Blob
+  | URLSearchParams
+  | FormData;
+
+/** What one hop is sent with. `tls.serverName` is the name a PINNED connection proves. */
+export type OutboundInit = RequestInit & {
+  readonly tls?: { readonly serverName?: string } | undefined;
+};
+
+/** "Just the call", the seam `MailFetch` already is. Its `init` always carries the signal. */
+export type OutboundFetch = (url: string, init: OutboundInit) => Promise<Response>;
+
+export interface OutboundRequest {
+  readonly url: string | URL;
+  /** A bounded label chosen in code (`'resend'`), in every log line and cause. */
+  readonly vendor: string;
+  /**
+   * Which network the URL may reach — a decision per call, so it is required. `'public'` screens
+   * every address the name answers and pins the connection; `'named'` dials a host the app itself
+   * names in code (a configured endpoint, a sidecar) as written.
+   */
+  readonly dial: 'named' | 'public';
+  /** The WHOLE call, retries and waits included. Clamped by the ambient request's own deadline. */
+  readonly deadlineMs: number;
+  readonly method?: OutboundMethod | undefined;
+  readonly headers?: Readonly<Record<string, string>> | undefined;
+  readonly body?: OutboundBody | undefined;
+  /** The longest gap between two body chunks, in ms. Default `OUTBOUND_IDLE_MS`. */
+  readonly idleMs?: number | undefined;
+  /** Default `OUTBOUND_MAX_BYTES`. */
+  readonly maxBytes?: number | undefined;
+  /** `'error'` by default: a 3xx is `X_OUTBOUND_REDIRECTED`, never a silent hop. */
+  readonly redirect?: 'error' | 'follow' | undefined;
+  /** Default `OUTBOUND_RETRY` for GET, HEAD, PUT, DELETE, OPTIONS; one attempt for POST, PATCH. */
+  readonly retry?: RetryPolicy | undefined;
+  /** A POST or PATCH carrying the vendor's idempotency key: retried as a safe method is. */
+  readonly idempotent?: true | undefined;
+  readonly read?: 'bytes' | 'stream' | undefined;
+  /**
+   * A signal of the caller's own, heard BESIDE the ambient `ctx.signal` — a fan-out's cancel. Its
+   * reason reaches the caller unchanged, as the context's does.
+   */
+  readonly signal?: AbortSignal | undefined;
+  /** Recorded once per call, after the retries: a 503 retried away is not a failure. */
+  readonly breaker?: Breaker | undefined;
+}
+
+export interface OutboundDeps {
+  readonly fetch?: OutboundFetch | undefined;
+  readonly resolve?: DialResolve | undefined;
+  readonly sleep?: ((ms: number) => Promise<void>) | undefined;
+  /** Monotonic ms. */
+  readonly now?: (() => number) | undefined;
+  readonly random?: Random | undefined;
+  /** The deadline and idle timers. A test fires it instead of waiting. */
+  readonly timer?: DeadlineTimer | undefined;
+  /** Which environment decides whether a public dial may use `http:`. Defaults to `process.env`. */
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+}
+
+interface OutboundHead {
+  readonly status: number;
+  readonly headers: Headers;
+}
+
+/** A 2xx, read whole. Anything else was thrown as a coded error. */
+export interface OutboundAnswer extends OutboundHead {
+  readonly bytes: Uint8Array;
+  text(): string;
+  /** The body through `schema`: `X_OUTBOUND_BODY_INVALID` when it does not fit. */
+  json<T>(schema: Schema<unknown, T>): T;
+}
+
+/** A 2xx whose body is read by the caller, under the same idle watchdog, cap and deadline. */
+export interface OutboundStreamAnswer extends OutboundHead {
+  readonly stream: ReadableStream<Uint8Array>;
+}
+
+/** Three tries, 250 ms then up to 5 s apart, full jitter. */
+export const OUTBOUND_RETRY: RetryPolicy = Object.freeze({
+  attempts: 3,
+  base: 250,
+  max: 5_000,
+  jitter: 'full',
+});
+
+export const OUTBOUND_IDLE_MS = 30_000;
+export const OUTBOUND_MAX_BYTES = 16 * 1024 * 1024;
+/** Hops a `redirect: 'follow'` call takes before it is `X_OUTBOUND_REDIRECTED`. */
+export const OUTBOUND_MAX_REDIRECTS = 5;

package/src/outbound.ts

@@ -0,0 +1,223 @@
+// Single responsibility: `outbound()`, the one outbound HTTP call — screen the request, run its
+// attempts through core's `retry()` (which owns the clamp to the ambient caller), record the
+// breaker once, and hand back a 2xx. Three adopters built this client and agreed on every property;
+// the parts were in core already, unassembled. Server-only: `@ultimat3/core/outbound`, never the barrel.
+
+import type { Schema } from '@ultimat3/schema';
+import type { Breaker } from './breaker';
+import { settleWith } from './breaker';
+import { systemClock } from './clock';
+import { tryUseContext } from './context';
+import { platformDeadlineTimer } from './deadline-signal';
+import { isLocal } from './environment';
+import { isUltimateError } from './errors';
+import { finiteCount } from './finite-option';
+import type { AttemptAnswer, AttemptCall } from './outbound-attempt';
+import { runAttempt } from './outbound-attempt';
+import type { OutboundSite } from './outbound-errors';
+import { isCallerBound, outboundBodyInvalid, outboundRetryUnsafe } from './outbound-errors';
+import { redactedPath } from './outbound-hops';
+import type {
+  OutboundAnswer,
+  OutboundDeps,
+  OutboundFetch,
+  OutboundRequest,
+  OutboundStreamAnswer,
+} from './outbound-types';
+import { OUTBOUND_IDLE_MS, OUTBOUND_MAX_BYTES, OUTBOUND_RETRY } from './outbound-types';
+import { retry } from './retry';
+import type { RetryPolicy } from './retry-loop';
+
+/** The platform's `fetch`, closed over (a detached `fetch` is "Illegal invocation" on some hosts). */
+const platformFetch: OutboundFetch = (target, init) =>
+  fetch(target, { ...init, signal: init.signal ?? null });
+
+/** A backoff wait the call's OWN signal also ends; `retry()` already hears the ambient one. */
+const signalledSleep =
+  (signal: AbortSignal) =>
+  (ms: number): Promise<void> =>
+    new Promise<void>((done) => {
+      const finish = (): void => {
+        clearTimeout(timer);
+        signal.removeEventListener('abort', finish);
+        done();
+      };
+      const timer = setTimeout(finish, ms);
+      if (signal.aborted) finish();
+      else signal.addEventListener('abort', finish, { once: true });
+    });
+
+/** A write the vendor cannot tell from a second one: never replayed without its key. */
+const UNSAFE = new Set(['POST', 'PATCH']);
+
+const ONE_ATTEMPT: RetryPolicy = Object.freeze({ attempts: 1, base: 0, max: 0, jitter: 'none' });
+
+function policyFor(request: OutboundRequest, site: OutboundSite): RetryPolicy {
+  const unsafe = UNSAFE.has(site.method) && request.idempotent !== true;
+  // Refused at the call, before a byte: a replayed charge is not a failure a log line repairs.
+  if (unsafe && request.retry !== undefined) throw outboundRetryUnsafe(site);
+  const policy = request.retry ?? (unsafe ? ONE_ATTEMPT : OUTBOUND_RETRY);
+  const budget = policy.timeBudgetMs ?? Number.POSITIVE_INFINITY;
+  return { ...policy, timeBudgetMs: Math.min(budget, request.deadlineMs) };
+}
+
+function prepare(request: OutboundRequest, deps: OutboundDeps): AttemptCall {
+  const url = new URL(request.url);
+  const method = request.method ?? 'GET';
+  const site: OutboundSite = {
+    vendor: request.vendor,
+    method,
+    origin: url.origin,
+    path: redactedPath(url.pathname),
+  };
+  const deadlineMs = finiteCount('outbound()', 'deadlineMs', request.deadlineMs, 1);
+  const now = deps.now ?? ((): number => systemClock.monotonic());
+  const send = deps.fetch ?? platformFetch;
+  return {
+    site,
+    url,
+    method,
+    headers: { ...request.headers },
+    body: request.body,
+    dial: request.dial,
+    redirect: request.redirect ?? 'error',
+    local: isLocal({ env: deps.env, fallback: 'production' }),
+    fetch: send,
+    resolve: deps.resolve,
+    endsAt: now() + deadlineMs,
+    deadlineMs,
+    idleMs: finiteCount('outbound()', 'idleMs', request.idleMs ?? OUTBOUND_IDLE_MS, 1),
+    maxBytes: finiteCount('outbound()', 'maxBytes', request.maxBytes ?? OUTBOUND_MAX_BYTES),
+    read: request.read ?? 'bytes',
+    signal: request.signal,
+    now,
+    timer: deps.timer ?? platformDeadlineTimer,
+  };
+}
+
+/** Once per CALL, after the retries; a caller gone gives the probe back and counts nothing. */
+async function guarded(
+  gate: Breaker,
+  signal: AbortSignal | undefined,
+  work: () => Promise<AttemptAnswer>,
+): Promise<AttemptAnswer> {
+  const ticket = gate.admit();
+  if (ticket === undefined) throw gate.refusal();
+  try {
+    const answer = await work();
+    gate.succeeded(ticket);
+    return answer;
+  } catch (error) {
+    // A caller gone, or the caller's own deadline spent, says nothing about the vendor.
+    const gone =
+      tryUseContext()?.signal.aborted === true || signal?.aborted === true || isCallerBound(error);
+    settleWith(gate, gone ? 'ignore' : gate.judge(error), ticket);
+    throw error;
+  }
+}
+
+function bytesAnswer(site: OutboundSite, answer: AttemptAnswer & { bytes: Uint8Array }) {
+  const text = (): string => new TextDecoder().decode(answer.bytes);
+  return {
+    status: answer.status,
+    headers: answer.headers,
+    bytes: answer.bytes,
+    text,
+    json<T>(schema: Schema<unknown, T>): T {
+      let value: unknown;
+      try {
+        value = JSON.parse(text());
+      } catch {
+        throw outboundBodyInvalid(site, ['the body is not JSON']);
+      }
+      const result = schema.safeParse(value);
+      if ('value' in result && result.issues === undefined) return result.value;
+      const issues = (result.issues ?? []).map(
+        (issue) =>
+          (issue.path ?? [])
+            .map((part) => String(typeof part === 'object' ? part.key : part))
+            .join('.') || '(root)',
+      );
+      throw outboundBodyInvalid(site, issues);
+    },
+  } satisfies OutboundAnswer;
+}
+
+/**
+ * One outbound HTTP call, every property decided: a deadline over the WHOLE call, the ambient
+ * request's signal and deadline honoured (`runToCompletion` lifts both, its `bound` sets them
+ * again), safe-only retry with `Retry-After`, an idle watchdog and a byte cap on the body, a 3xx
+ * never followed unless asked, and every failure a code whose cause names no query or header.
+ */
+export async function outbound(
+  request: OutboundRequest & { readonly read: 'stream' },
+  deps?: OutboundDeps,
+): Promise<OutboundStreamAnswer>;
+export async function outbound(
+  request: OutboundRequest & { readonly read?: 'bytes' | undefined },
+  deps?: OutboundDeps,
+): Promise<OutboundAnswer>;
+export async function outbound(
+  request: OutboundRequest,
+  deps: OutboundDeps = {},
+): Promise<OutboundAnswer | OutboundStreamAnswer> {
+  const call = prepare(request, deps);
+  const policy = policyFor(request, call.site);
+  const work = (): Promise<AttemptAnswer> =>
+    retry((attempt) => runAttempt(call, attempt), policy, {
+      sleep:
+        deps.sleep ?? (request.signal === undefined ? undefined : signalledSleep(request.signal)),
+      now: call.now,
+      random: deps.random,
+    });
+  const answer =
+    request.breaker === undefined
+      ? await work()
+      : await guarded(request.breaker, request.signal, work);
+  if ('stream' in answer) return answer;
+  return bytesAnswer(call.site, answer);
+}
+
+/**
+ * `outbound()` for a caller whose existing code READS a refusal: the final answer as a `Response`
+ * whatever its status. Every property above still holds — deadline, signal, retry, caps, redaction
+ * (a refusal's body is its redacted 200-character `meta.detail`) — and a call that got no answer
+ * still throws its code. For a driver mapping statuses onto codes it already shipped.
+ */
+export async function outboundResponse(
+  request: OutboundRequest & { readonly read?: 'bytes' | undefined },
+  deps: OutboundDeps = {},
+): Promise<Response> {
+  // The last answer's HEADERS, kept for the refusal rebuilt below: a vendor names its error type
+  // in one (SES's `x-amzn-ErrorType`), and a cause never carries a header.
+  let lastHeaders: Headers | undefined;
+  const send = deps.fetch ?? platformFetch;
+  const recording: OutboundFetch = async (target, init) => {
+    const response = await send(target, init);
+    lastHeaders = response.headers;
+    return response;
+  };
+  try {
+    const answer = await outbound(request, { ...deps, fetch: recording });
+    return new Response(answer.bytes.slice(), { status: answer.status, headers: answer.headers });
+  } catch (error) {
+    const refused = refusalResponse(error, lastHeaders);
+    if (refused === undefined) throw error;
+    return refused;
+  }
+}
+
+/** The answer a coded refusal carried, rebuilt: its status, its stated delay, its detail. */
+function refusalResponse(error: unknown, received: Headers | undefined): Response | undefined {
+  if (!isUltimateError(error) || !error.code.startsWith('X_OUTBOUND_')) return undefined;
+  const status = error.meta?.['status'];
+  if (typeof status !== 'number') return undefined;
+  const detail = error.meta?.['detail'];
+  const after = error.meta?.['retryAfterSeconds'];
+  const headers = new Headers(received);
+  // The body is the detail now, never the vendor's bytes: their length and encoding no longer hold.
+  headers.delete('content-length');
+  headers.delete('content-encoding');
+  if (typeof after === 'number') headers.set('retry-after', String(after));
+  return new Response(typeof detail === 'string' ? detail : '', { status, headers });
+}

package/src/page-meta.ts

@@ -34,6 +34,14 @@ export const APP_UPDATE_MESSAGE = 'AppUpdateAvailable';
  */
 export const CLIENT_PATH_STYLE_META = 'ultimate-path-style';
 
+/**
+ * Every PINNED action and query (`http: { path, method }`) the server serves, as one JSON object
+ * (`client-paths-pins.ts` owns the format). A browser caller reaching one BY NAME — `rpc`,
+ * `queryClient`, `useQuery`, `useMutation`, the outbox — goes where the declaration put it, and
+ * no browser ref restates a pin it could drift from. Absent when nothing is pinned.
+ */
+export const CLIENT_PINS_META = 'ultimate-pins';
+
 /** Where the page's one socket dials: `/_x/sync`, or the deployment's absolute `SYNC_URL`. */
 export const CLIENT_SYNC_META = 'ultimate-sync';
 

package/src/page.ts

@@ -17,6 +17,8 @@ export { backoffDelay } from './backoff';
 export type { FetchLike, TransportRequest } from './client-dispatch';
 export { IDEMPOTENCY_HEADER } from './client-dispatch';
 export { actionPath, queryPath, splitWords } from './client-paths';
+export type { ActionPin, PinnedActionMethod } from './client-paths-pins';
+export { renderedActionPin, renderedQueryPin } from './client-paths-pins';
 export type { ClientScope } from './client-scope';
 export { onRescope, rescope } from './client-scope';
 export { clientTransport } from './client-transport';
@@ -34,6 +36,7 @@ export { renderFixShellArg, renderThrowable, stringField } from './error-render'
 export { classifyThrown } from './error-retry';
 export type { UltimateErrorInit } from './errors';
 export { isUltimateError, UltimateError } from './errors';
+export { fillWire } from './fill-wire';
 export { finiteCount, finiteOption } from './finite-option';
 export { isSuperseded } from './generation-fence';
 export { uuidV7 } from './ids';
@@ -49,6 +52,7 @@ export {
   CLIENT_NAVIGATION_SURFACE_HEADER,
   CLIENT_PATH_STYLE_META,
   CLIENT_PERSIST_META,
+  CLIENT_PINS_META,
   CLIENT_SCOPE_HEADER,
   CLIENT_SCOPE_META,
   CLIENT_SYNC_META,
@@ -58,8 +62,13 @@ export type { RecordEnvelope, RecordRows } from './record-envelope';
 export { decodeRecordEnvelope, RECORDS_HEADER } from './record-envelope';
 export type { PageClient, RecordSink } from './record-sink';
 export { pageClient } from './record-sink';
+export { fillTemplate, templateParams } from './route-path-template';
+export { onSessionLost, sessionIsLost } from './session-lost';
 // The key the theme boot script reads and the toggle island writes.
 export { THEME_STORAGE_KEY } from './theme-storage';
+// A poll a hidden tab and a lost session stop: here, so an island polling reaches no realtime.
+export type { VisibleIntervalOptions } from './visible-interval';
+export { visibleInterval } from './visible-interval';
 // What `clientTransport` revives a read's instants by: the header the server names them in.
 export { DATES_HEADER, reviveWireDates } from './wire-dates';
 // A write's public name, so the page's store can recognise the `records` frame its own write made.

package/src/record-envelope-openapi.ts

@@ -27,6 +27,12 @@ export function recordEnvelopeSchema(
         description: 'Record keys the client store must drop, keyed by record type.',
         additionalProperties: { type: 'array', items: { type: 'string' } },
       },
+      order: {
+        type: 'object',
+        description:
+          "A record type's keys in answer order, sent only where `records` cannot keep it (integer-like keys enumerate ascending).",
+        additionalProperties: { type: 'array', items: { type: 'string' } },
+      },
     },
   };
 }