cartethyia 2.7.9 → 2.8.0

package/src/transport/dispatch/attempt-finalize.ts

@@ -622,19 +622,20 @@ export function nativeCompletionBase(input: {
   | "tokensPerSec"
 > {
   return {
-    providerId: input.providerId,
-    modelId: input.modelId,
-    tenantId: input.tenantId,
-    ingressBody: input.ingressBody,
-    terminal: true,
-    ...(input.accountId === undefined ? {} : { accountId: input.accountId }),
-    ...(input.accountLabel === undefined ? {} : { accountLabel: input.accountLabel }),
-    ...(input.networkPoolId === undefined ? {} : { networkPoolId: input.networkPoolId }),
-    ...(input.lease === undefined ? {} : { lease: input.lease }),
-    db: input.db,
-    ...(input.telemetryBuffer === undefined ? {} : { telemetryBuffer: input.telemetryBuffer }),
-    ...(input.snapshotService === undefined ? {} : { snapshotService: input.snapshotService }),
-    ...(input.providerCapture === undefined ? {} : { providerCapture: input.providerCapture }),
+    ...completionContext({
+      providerId: input.providerId,
+      modelId: input.modelId,
+      tenantId: input.tenantId,
+      ingressBody: input.ingressBody,
+      ...(input.providerCapture === undefined ? {} : { providerCapture: input.providerCapture }),
+      db: input.db,
+      ...(input.accountId === undefined ? {} : { accountId: input.accountId }),
+      ...(input.accountLabel === undefined ? {} : { accountLabel: input.accountLabel }),
+      ...(input.networkPoolId === undefined ? {} : { networkPoolId: input.networkPoolId }),
+      ...(input.lease === undefined ? {} : { lease: input.lease }),
+      ...(input.telemetryBuffer === undefined ? {} : { telemetryBuffer: input.telemetryBuffer }),
+      ...(input.snapshotService === undefined ? {} : { snapshotService: input.snapshotService }),
+    }),
     ...(input.usage === undefined ? {} : { usage: input.usage }),
     ...(input.commitUsage === undefined ? {} : { commitUsage: input.commitUsage }),
   };

package/src/transport/dispatch/attempt-loop.ts

@@ -32,7 +32,7 @@ import { metrics } from "../../observability/metrics";
 import type { NetworkPoolSelector } from "../../network/pool/selector";
 import type { ProxyRequestState } from "../request/state";
 import type { TelemetryBatchBuffer } from "../../observability/telemetry-buffer";
-import { flagPoolBlocked, flagPoolCooldown } from "../../network/pool-health";
+import { flagPoolOnEgressFailure } from "../../network/pool-health";
 import {
   completeAttempt,
   errorClientResponseBody,
@@ -61,6 +61,41 @@ function comboCandidateKey(candidate: RouteCandidate): string {
   ].join(":");
 }
 
+/**
+ * Extra dials allowed for a mid-response upstream socket drop when the
+ * candidate list is exhausted (single-account providers). One extra dial
+ * recovers the transient reset; more would stack latency on a dying origin.
+ */
+const MAX_SOCKET_DROP_RETRIES = 1;
+
+/**
+ * Normalizes a raw (non-GatewayError) failure before it escapes the loop.
+ *
+ * A transport-level throw — e.g. Bun's `TypeError` with
+ * `code: "ECONNRESET"` when the upstream socket dies mid-response — carries a
+ * `.code` of its own. The error middleware reads that `.code` for Elysia
+ * built-in errors, so a raw socket drop leaked to the client as
+ * `{"code":"ECONNRESET","status":400}` with origin `cartethyia`: the wrong
+ * code, the wrong status, and the wrong blame. The classifier already knows
+ * what this is (`transport_unavailable`, 502, upstream) — materialize it as a
+ * real GatewayError so the client and the captured Client Response see the
+ * same stable envelope every other upstream transport failure gets.
+ */
+function normalizeEscapeError(error: unknown, signal: AbortSignal): unknown {
+  if (error instanceof GatewayError) return error;
+  const terminal = classifyTerminalOutcome(error, signal);
+  if (terminal.errorCategory === "transport_unavailable") {
+    return new GatewayError(
+      "transport_unavailable",
+      502,
+      "The upstream closed the connection mid-response (request {requestId}). Retry; if it keeps happening, the account or pool is unstable. The connection ghosted us — come back in a moment 👻",
+      {},
+      "upstream",
+    );
+  }
+  return error;
+}
+
 /**
  * True when the rejection is about the API key or the gateway's own policy,
  * not about the provider account that was dialled.
@@ -321,7 +356,7 @@ export async function runAttemptLoop<TResult, TAdapter>(
             status: terminal.status === "cancelled" ? "cancelled" : "failed",
           });
         }
-        throw lastError;
+        throw normalizeEscapeError(lastError, state.abortController.signal);
       }
     }
     let lease: AdmissionLease | undefined;
@@ -381,6 +416,13 @@ export async function runAttemptLoop<TResult, TAdapter>(
       // names the real cause.
       const drain = drainAbortReason(state.abortController.signal.reason);
       if (drain !== undefined) error = drain;
+      // Normalize a raw transport throw (e.g. Bun's `TypeError` with
+      // `code: "ECONNRESET"` when the upstream socket dies mid-response) into
+      // the stable `transport_unavailable`/502/upstream GatewayError **before**
+      // classification, so the telemetry row, the captured Client Response, and
+      // the escaped error all agree — and the raw `.code` never leaks to the
+      // client as a fake Elysia built-in code (see `normalizeEscapeError`).
+      error = normalizeEscapeError(error, state.abortController.signal);
       lastError = error;
       // A drain is a *server* close, not a client cancel: it must be recorded
       // as a failure with the shutdown code, and it is never retryable.
@@ -411,21 +453,33 @@ export async function runAttemptLoop<TResult, TAdapter>(
       // the pool excluded. Both flag helpers write the local entry
       // synchronously, so the ordering holds even though the Redis mirror is
       // fire-and-forget.
-      if (networkPoolId && deps.poolSelector && error instanceof GatewayError) {
-        if (rateLimitedPool) {
-          flagPoolCooldown(deps.poolSelector, deps.db, networkPoolId, candidate.provider_id, error);
-        } else if (blockedPool) {
-          // The address itself is refused, not the request: retire the egress
-          // so the next attempt leaves by a different one instead of retrying
-          // a proxy the upstream has already flagged.
-          flagPoolBlocked(deps.poolSelector, deps.db, networkPoolId, candidate.provider_id, error);
-        }
-      }
+      flagPoolOnEgressFailure(
+        deps.poolSelector,
+        deps.db,
+        networkPoolId,
+        candidate.provider_id,
+        error,
+        egressVerdict,
+      );
+      // A mid-response upstream socket drop (`transport_unavailable`) is the one
+      // retryable failure that receives an extra dial even when the candidate
+      // list is exhausted: an origin that closes the connection before the
+      // response is often transient (Trae's edge resets under concurrency),
+      // and the fresh dial recovers it — verified live 2026-11-09, 7/7
+      // recovered on the first retry. Without this, a single-account provider
+      // (the common case) tripped `index === candidates.length - 1` on the very
+      // first attempt and the client saw the raw socket error. The retry is
+      // bounded to one extra dial per request, never unbounded.
+      const memberAttempts = attemptsByMember.get(memberKey) ?? 0;
+      const socketDropRetryLeft =
+        terminal.errorCategory === "transport_unavailable" &&
+        !cancelled &&
+        memberAttempts < MAX_SOCKET_DROP_RETRIES;
       const terminalAttempt =
         cancelled ||
         isClientScopedRejection(error) ||
         !isRetryableFailure(error) ||
-        (index === candidates.length - 1 && !poolScopedFailure);
+        ((index === candidates.length - 1 && !poolScopedFailure) && !socketDropRetryLeft);
       // Track only the most recent fired exchange; the array this replaced
       // accumulated every attempt's capture until the loop returned.
       if (providerCapture.request !== null) lastFiredCapture = providerCapture;
@@ -474,7 +528,7 @@ export async function runAttemptLoop<TResult, TAdapter>(
       // A 403 can be a deterministic provider policy rejection, not an
       // invalid OAuth credential. Only the evidence-based classifier above
       // may trigger a refresh.
-      const candidateKey = `${candidate.provider_id}:${candidate.provider_account_id ?? "global"}:${candidate.model_id}:${candidate.endpoint}`;
+      const candidateKey = comboCandidateKey(candidate);
       const authInvalidated = isOAuthCredentialInvalidated(error);
       if (
         !cancelled &&
@@ -499,7 +553,7 @@ export async function runAttemptLoop<TResult, TAdapter>(
       }
       if (terminalAttempt) {
         metrics.proxy_requests_total.inc(1, { status: cancelled ? "cancelled" : "failed" });
-        throw error;
+        throw normalizeEscapeError(error, state.abortController.signal);
       }
       // A failed combo member stays flagged for this request. Move it behind
       // every candidate that has not failed yet, so the next attempt cannot
@@ -542,7 +596,7 @@ export async function runAttemptLoop<TResult, TAdapter>(
         // as the sleep's own error would leave `proxy_requests_total` missing
         // the request.
         metrics.proxy_requests_total.inc(1, { status: "cancelled" });
-        throw lastError;
+        throw normalizeEscapeError(lastError, state.abortController.signal);
       }
     }
   }
@@ -577,5 +631,5 @@ export async function runAttemptLoop<TResult, TAdapter>(
     }));
   }
   metrics.proxy_requests_total.inc(1, { status: "failed" });
-  throw lastError;
+  throw normalizeEscapeError(lastError, state.abortController.signal);
 }

package/src/transport/dispatch/generation.ts

@@ -27,6 +27,7 @@ import { completeAttempt, estimatedUsage, nativeCompletionBase } from "./attempt
 import { runAttemptLoop } from "./attempt-loop";
 import { captureProviderRateLimit } from "./ratelimit-capture";
 import {
+  forwardUpstreamResponse,
   hasScope,
   jsonResponse,
   networkFetchContext,
@@ -133,14 +134,7 @@ async function passThrough(
     responseBody: null,
   });
   metrics.proxy_requests_total.inc(1, { status: "completed" });
-  return new Response(upstream.body, {
-    status: upstream.status,
-    headers: {
-      "content-type": upstream.headers.get("content-type") ?? "text/event-stream",
-      "cache-control": "no-store",
-      "x-request-id": state.requestId,
-    },
-  });
+  return forwardUpstreamResponse(upstream, state.requestId, "text/event-stream");
 }
 
 /** Builds the handler for one generation surface. */

package/src/transport/dispatch/native-shared.ts

@@ -71,6 +71,31 @@ export function jsonResponse(payload: unknown, status: number, requestId: string
   });
 }
 
+/**
+ * Forwards an upstream response body verbatim with the shared native-response
+ * header set.
+ *
+ * The native handlers (System One, responses-compact, token-count,
+ * generation's passThrough) each spelled the same three headers by hand; the
+ * copies drifted at least once (generation's JSON builder lost `cache-control`).
+ * Status and body come from the upstream untouched; only the content-type
+ * default differs per route (SSE vs JSON) and is passed per call.
+ */
+export function forwardUpstreamResponse(
+  response: Response,
+  requestId: string,
+  defaultContentType = "application/json",
+): Response {
+  return new Response(response.body, {
+    status: response.status,
+    headers: {
+      "content-type": response.headers.get("content-type") ?? defaultContentType,
+      "cache-control": "no-store",
+      "x-request-id": requestId,
+    },
+  });
+}
+
 /**
  * Strips a thinking suffix (`model(high)`) from the model name and rebuilds
  * the body with the bare model when it changed. Returns the bare model and

package/src/transport/dispatch/proxy-request.ts

@@ -11,7 +11,7 @@ import { chatAdapter } from "../surface/chat/adapter";
 import { responsesAdapter } from "../surface/responses/adapter";
 import { messagesAdapter } from "../surface/messages/adapter";
 import { completionAdapter } from "../surface/completion";
-import { forwardedRequestHeaders, proxySuccessHeaders, buildUpstreamDispatchContext, reportedModelFrom } from "./upstream";
+import { forwardedRequestHeaders, proxySuccessHeaders, buildUpstreamDispatchContext, buildDispatchNetworkBindings, reportedModelFrom } from "./upstream";
 import { resolvePromptCacheKey } from "../../providers/operations/session-resolution";
 import {
   applyTenantPreferences,
@@ -21,18 +21,12 @@ import {
 import { metrics } from "../../observability/metrics";
 import { repriceUsage } from "../../providers/provider-usage";
 import {
-  captureProviderExchange,
   completeAttempt,
   completionContext,
   estimatedUsage,
   parseCapturedBody,
   terminalFailure,
 } from "./attempt-finalize";
-import {
-  providerCaptureMaxBytes,
-  resolveCaptureDepthForRequest,
-  shouldCaptureProviderBodyForRequest,
-} from "./capture-policy";
 import { runAttemptLoop } from "./attempt-loop";
 import { projectForRoute, routeCapabilitiesFor } from "../../protocol/translation/capabilities";
 import { dispatchStreamingAttempt } from "./streaming/stream";
@@ -264,45 +258,13 @@ export async function handleProviderProxyRequest(
         ...(tenantSystemPromptText === undefined ? {} : { tenantSystemPrompt: tenantSystemPromptText }),
         ...(candidate.user_agent === undefined ? {} : { userAgent: candidate.user_agent }),
         ...(providerCapture ? { providerCapture } : {}),
-        ...(deps.networkBindingFactory
-          ? {
-              outboundFetch: captureProviderExchange(
-                deps.networkBindingFactory.fetch(
-                  networkPoolId,
-                  prepared.authorization.snapshot.tenant_id,
-                ),
-                providerCapture,
-                await shouldCaptureProviderBodyForRequest(
-                  deps.db,
-                  prepared.authorization.snapshot.tenant_id,
-                  state,
-                ),
-                providerCaptureMaxBytes(
-                  await resolveCaptureDepthForRequest(
-                    deps.db,
-                    prepared.authorization.snapshot.tenant_id,
-                    state,
-                  ),
-                ),
-              ),
-            }
-          : {}),
-        ...(deps.networkBindingFactory
-          ? {
-              outboundAttachmentFetch: deps.networkBindingFactory.fetch(
-                networkPoolId,
-                prepared.authorization.snapshot.tenant_id,
-              ),
-            }
-          : {}),
-        ...(deps.networkBindingFactory
-          ? {
-              outboundHttp2: deps.networkBindingFactory.http2Bidi(
-                networkPoolId,
-                prepared.authorization.snapshot.tenant_id,
-              ),
-            }
-          : {}),
+        ...(await buildDispatchNetworkBindings({
+          deps,
+          networkPoolId,
+          tenantId: prepared.authorization.snapshot.tenant_id,
+          providerCapture,
+          state,
+        })),
         ...(leaseOwnership === undefined ? {} : { leaseOwnership }),
         ...(continuationScope === undefined ? {} : { continuationScope }),
       });

package/src/transport/dispatch/responses-compact.ts

@@ -4,6 +4,7 @@ import type { CodexCompactAdapter } from "../../providers/integrations/codex/cod
 import { completeAttempt, estimatedUsage, nativeCompletionBase } from "./attempt-finalize";
 import { runAttemptLoop } from "./attempt-loop";
 import {
+  forwardUpstreamResponse,
   networkFetchContext,
   requireRecordBody,
   resolveAttemptCredential,
@@ -143,14 +144,7 @@ export function createResponsesCompactHandler(deps: ResponsesCompactHandlerDeps)
           responseBody: null,
         });
         metrics.proxy_requests_total.inc(1, { status: "completed" });
-        return new Response(response.body, {
-          status: response.status,
-          headers: {
-            "content-type": response.headers.get("content-type") ?? "application/json",
-            "cache-control": "no-store",
-            "x-request-id": state.requestId,
-          },
-        });
+        return forwardUpstreamResponse(response, state.requestId);
       },
     });
   };

package/src/transport/dispatch/streaming/finalize.ts

@@ -23,7 +23,7 @@ import type { AdmissionLease } from "../../../security/admission/contracts";
 import type { Reservation } from "../../routing/route-model";
 import { repriceUsage } from "../../../providers/provider-usage";
 import { metrics } from "../../../observability/metrics";
-import { flagPoolBlocked, flagPoolCooldown } from "../../../network/pool-health";
+import { flagPoolOnEgressFailure } from "../../../network/pool-health";
 import { classifyEgressFailure } from "../../../network/rate-limit-verdict";
 import { releaseAttemptLeases } from "../leases";
 import type { AttemptLeaseOwnership } from "../leases";
@@ -581,11 +581,14 @@ export class StreamFinalizer {
     this.streamSettled = true;
     if (candidate.networkPoolId && !cancelled && deps.poolSelector && err instanceof GatewayError) {
       const egressVerdict = classifyEgressFailure(err, candidate.providerId);
-      if (egressVerdict.kind === "cooldown") {
-        flagPoolCooldown(deps.poolSelector, deps.db, candidate.networkPoolId, candidate.providerId, err);
-      } else if (egressVerdict.kind === "blocked") {
-        flagPoolBlocked(deps.poolSelector, deps.db, candidate.networkPoolId, candidate.providerId, err);
-      }
+      flagPoolOnEgressFailure(
+        deps.poolSelector,
+        deps.db,
+        candidate.networkPoolId,
+        candidate.providerId,
+        err,
+        egressVerdict,
+      );
     }
     if (!cancelled) metrics.proxy_requests_total.inc(1, { status: "failed" });
     else metrics.proxy_requests_total.inc(1, { status: "cancelled" });

package/src/transport/dispatch/streaming/stream.ts

@@ -43,17 +43,11 @@ import type { AdmissionLease } from "../../../security/admission/contracts";
 import type { NetworkPoolSelector } from "../../../network/pool/selector";
 import type { TelemetryBatchBuffer } from "../../../observability/telemetry-buffer";
 import type { ProviderExchangeCapture } from "../attempt-finalize";
-import { captureProviderExchange } from "../attempt-finalize";
-import {
-  providerCaptureMaxBytes,
-  resolveCaptureDepthForRequest,
-  resolveCaptureModeForRequest,
-  shouldCaptureProviderBodyForRequest,
-} from "../capture-policy";
+import { resolveCaptureModeForRequest } from "../capture-policy";
 import { resolveTenantImageClampMaxBytes, readTenantSystemPromptsForDispatch } from "../../request/tenant-preferences";
 import { resolveTenantSystemPrompt } from "../../request/system-prompt-injection";
 import { isWrappedInjectionProvider } from "../../../console/system-prompt/contracts";
-import { proxySuccessHeaders, buildUpstreamDispatchContext } from "../upstream";
+import { proxySuccessHeaders, buildUpstreamDispatchContext, buildDispatchNetworkBindings } from "../upstream";
 import type { AttemptLeaseOwnership } from "../leases";
 import type { ProviderContinuationScope } from "../../../providers/provider-contracts";
 import { resolveStreamFirstChunkTimeoutMs, resolveStreamStallTimeoutMs, resolveUpstreamTimeoutMs } from "../../../config/timeouts";
@@ -170,18 +164,13 @@ export async function dispatchStreamingAttempt(input: StreamingDispatchInput): P
     continuationScope,
   } = input;
 
-  const outboundFetch = deps.networkBindingFactory?.fetch(
+  const bindings = await buildDispatchNetworkBindings({
+    deps,
     networkPoolId,
-    prepared.authorization.snapshot.tenant_id,
-  );
-  const captureBody = outboundFetch
-    ? await shouldCaptureProviderBodyForRequest(deps.db, prepared.authorization.snapshot.tenant_id, state)
-    : false;
-  const captureDepth = await resolveCaptureDepthForRequest(
-    deps.db,
-    prepared.authorization.snapshot.tenant_id,
+    tenantId: prepared.authorization.snapshot.tenant_id,
+    providerCapture,
     state,
-  );
+  });
   // Resolved once, before the pipeline exists: the pipeline's diagnostics are
   // gated on it from construction, so `none`/`metadata` tenants never pay the
   // transcript serialization or the client-response copy for any event.
@@ -190,14 +179,6 @@ export async function dispatchStreamingAttempt(input: StreamingDispatchInput): P
     prepared.authorization.snapshot.tenant_id,
     state,
   );
-  const wrappedOutboundFetch = outboundFetch
-    ? captureProviderExchange(
-        outboundFetch,
-        providerCapture,
-        captureBody,
-        providerCaptureMaxBytes(captureDepth),
-      )
-    : undefined;
   // Same memoized ceiling the non-streaming path resolves, read before the
   // dispatch context is built so a stream gets the same limit as a normal
   // request rather than silently falling back to the deployment default.
@@ -237,16 +218,7 @@ export async function dispatchStreamingAttempt(input: StreamingDispatchInput): P
       return text === undefined ? {} : { tenantSystemPrompt: text };
     })()),
     ...(candidate.user_agent === undefined ? {} : { userAgent: candidate.user_agent }),
-    ...(wrappedOutboundFetch ? { outboundFetch: wrappedOutboundFetch } : {}),
-    ...(outboundFetch ? { outboundAttachmentFetch: outboundFetch } : {}),
-    ...(deps.networkBindingFactory
-      ? {
-          outboundHttp2: deps.networkBindingFactory.http2Bidi(
-            networkPoolId,
-            prepared.authorization.snapshot.tenant_id,
-          ),
-        }
-      : {}),
+    ...bindings,
     ...(leaseOwnership === undefined ? {} : { leaseOwnership }),
     ...(continuationScope === undefined ? {} : { continuationScope }),
     ...(providerCapture ? { providerCapture } : {}),

package/src/transport/dispatch/systemone.ts

@@ -4,6 +4,7 @@ import { metrics } from "../../observability/metrics";
 import { estimatedUsage, nativeCompletionBase, completeAttempt } from "./attempt-finalize";
 import { runAttemptLoop } from "./attempt-loop";
 import {
+  forwardUpstreamResponse,
   networkFetchContext,
   requireRecordBody,
   resolveAttemptCredential,
@@ -164,14 +165,7 @@ export function createSystemoneHandler(deps: SystemoneHandlerDeps) {
           responseBody: null,
         });
         metrics.proxy_requests_total.inc(1, { status: "completed" });
-        return new Response(response.body, {
-          status: response.status,
-          headers: {
-            "content-type": response.headers.get("content-type") ?? "application/json",
-            "cache-control": "no-store",
-            "x-request-id": state.requestId,
-          },
-        });
+        return forwardUpstreamResponse(response, state.requestId);
       },
     });
   };

package/src/transport/dispatch/token-count.ts

@@ -43,7 +43,7 @@ import type { PreparedNativeRequest } from "../request/preparer";
 import { completeAttempt, estimatedUsage, nativeCompletionBase } from "./attempt-finalize";
 import { finalizeRequestTelemetry } from "../guards/error-lifecycle";
 import { runAttemptLoop } from "./attempt-loop";
-import { hasScope, networkFetchContext, requireRecordBody, resolveAttemptCredential } from "./native-shared";
+import { forwardUpstreamResponse, hasScope, networkFetchContext, requireRecordBody, resolveAttemptCredential } from "./native-shared";
 
 import type { GatewayHandlerDeps } from "./handler-deps";
 
@@ -189,11 +189,7 @@ export function createTokenCountHandler(deps: TokenCountHandlerDeps) {
 
         // Verbatim: the client reads the provider's own number, and the
         // provider's own error when it refuses to produce one.
-        const contentType = upstream.headers.get("content-type") ?? "application/json";
-        return new Response(upstream.body, {
-          status: upstream.status,
-          headers: { "content-type": contentType, "cache-control": "no-store", "x-request-id": state.requestId },
-        });
+        return forwardUpstreamResponse(upstream, state.requestId);
       },
     });
   };

package/src/transport/dispatch/upstream.ts

@@ -2,6 +2,15 @@ import type { CanonicalEvent } from "../../protocol/canonical-model";
 import type { AttemptLeaseOwnership, ValidatedOutboundFetch, ValidatedOutboundHttp2Bidi } from "../../providers/provider-contracts";
 import type { ProviderCaptureExchange, ProviderContinuationScope } from "../../providers/provider-contracts";
 import { GATEWAY_SECURITY_HEADERS } from "../../security/outbound-headers";
+import type { ValidatedNetworkBindingFactory } from "../../network/pool/resolver";
+import type { CartethyiaDatabase } from "../../persistence/db-handle";
+import { captureProviderExchange, type ProviderExchangeCapture } from "./attempt-finalize";
+import {
+  providerCaptureMaxBytes,
+  resolveCaptureDepthForRequest,
+  shouldCaptureProviderBodyForRequest,
+  type CapturePreferenceState,
+} from "./capture-policy";
 
 const FORWARDED_REQUEST_HEADERS = new Set([
   "user-agent",
@@ -34,6 +43,60 @@ export function proxySuccessHeaders(state: { requestId: string }): Record<string
   };
 }
 
+/** The three validated egress bindings shared by every dispatch attempt. */
+export interface DispatchNetworkBindings {
+  readonly outboundFetch?: ValidatedOutboundFetch;
+  readonly outboundAttachmentFetch?: ValidatedOutboundFetch;
+  readonly outboundHttp2?: ValidatedOutboundHttp2Bidi;
+}
+
+/**
+ * Builds the outbound network bindings for one attempt's dispatch context,
+ * shared by the non-streaming proxy path and the streaming branch.
+ *
+ * Both previously assembled the same three objects by hand (wrapped fetch,
+ * attachment fetch, HTTP/2 bidi), which drifted in the capture wrap. The
+ * capture-body gating is preserved exactly: the DB-backed capture-preference
+ * read is skipped when no network binding exists (`outboundFetch ? ... :
+ * false`), so a request that can never tee a provider exchange does not pay
+ * for the preference read. The reads are memoized on the request state, so
+ * resolving them here costs no extra DB reads.
+ */
+export async function buildDispatchNetworkBindings(input: {
+  readonly deps: {
+    readonly networkBindingFactory?: ValidatedNetworkBindingFactory | undefined;
+    readonly db: CartethyiaDatabase;
+  };
+  readonly networkPoolId: string | undefined;
+  readonly tenantId: string | null;
+  readonly providerCapture: ProviderExchangeCapture;
+  readonly state: CapturePreferenceState;
+}): Promise<DispatchNetworkBindings> {
+  const factory = input.deps.networkBindingFactory;
+  if (factory === undefined) return {};
+  const outboundFetch = factory.fetch(input.networkPoolId, input.tenantId ?? undefined);
+  const captureBody = await shouldCaptureProviderBodyForRequest(
+    input.deps.db,
+    input.tenantId,
+    input.state,
+  );
+  const captureDepth = await resolveCaptureDepthForRequest(
+    input.deps.db,
+    input.tenantId,
+    input.state,
+  );
+  return {
+    outboundFetch: captureProviderExchange(
+      outboundFetch,
+      input.providerCapture,
+      captureBody,
+      providerCaptureMaxBytes(captureDepth),
+    ),
+    outboundAttachmentFetch: factory.fetch(input.networkPoolId, input.tenantId ?? undefined),
+    outboundHttp2: factory.http2Bidi(input.networkPoolId, input.tenantId ?? undefined),
+  };
+}
+
 export function buildUpstreamDispatchContext(input: {
   readonly credential: unknown;
   readonly deadline: number;

package/src/transport/drain-endpoint.ts

@@ -50,14 +50,41 @@ export function tokenMatches(provided: string | null, expected: string): boolean
   return a.length === b.length && timingSafeEqual(a, b);
 }
 
+interface LoopbackAdminGate {
+  /** Peer address of the request, resolved by the composition root. */
+  readonly peer: string | null;
+  /** Shared secret; the route is registered only when this is set. */
+  readonly token: string;
+  /** `policy_rejected` (403) message, preserved per surface. */
+  readonly policyRejectedMessage: string;
+  /** `authentication_failed` (401) message, preserved per surface. */
+  readonly authenticationFailedMessage: string;
+}
+
+/**
+ * The shared security gate for host-local admin operations: the request must
+ * come from loopback, then it must carry the drain token compared in constant
+ * time. The peer check is independent of the secret, so a leaked token alone
+ * cannot reach a remote surface. The peer refusal comes first, then the token,
+ * with the codes and messages preserved verbatim per caller.
+ */
+export function requireLoopbackAdmin(request: Request, gate: LoopbackAdminGate): void {
+  if (!isLoopbackPeer(gate.peer))
+    throw new GatewayError("policy_rejected", 403, gate.policyRejectedMessage);
+  if (!tokenMatches(request.headers.get("x-drain-token"), gate.token))
+    throw new GatewayError("authentication_failed", 401, gate.authenticationFailedMessage);
+}
+
 export function createDrainHandler(
   deps: DrainEndpointDeps,
 ): (context: { request: Request }) => Promise<Response> {
   return async ({ request }) => {
-    if (!isLoopbackPeer(deps.resolvePeerAddress(request)))
-      throw new GatewayError("policy_rejected", 403, "drain is only available from loopback (request {requestId}). This operation is only allowed from a trusted loopback connection — no hard feelings 🫂");
-    if (!tokenMatches(request.headers.get("x-drain-token"), deps.token))
-      throw new GatewayError("authentication_failed", 401, "invalid drain token (request {requestId}). Wrong key, right door — check the token 🔑");
+    requireLoopbackAdmin(request, {
+      peer: deps.resolvePeerAddress(request),
+      token: deps.token,
+      policyRejectedMessage: "drain is only available from loopback (request {requestId}). This operation is only allowed from a trusted loopback connection — no hard feelings 🫂",
+      authenticationFailedMessage: "invalid drain token (request {requestId}). Wrong key, right door — check the token 🔑",
+    });
     // Acknowledge first, then drain: the response must be on the wire before the
     // shutdown path starts closing sockets, or the caller sees a dropped
     // connection instead of a 202.