@bitkyc08/opencodex 2.60.0 → 2.61.0-preview.20260922

package/src/lib/proxy-env.ts

@@ -86,12 +86,30 @@ export function outboundProxyConfigured(
   return OUTBOUND_PROXY_ENV_KEYS.some(key => proxyEnvPresent(key, env));
 }
 
+/**
+ * The value when `raw` is a proxy URL Bun fetch can actually use, else null.
+ * Bun rejects unparseable values and non-http(s) schemes (UnsupportedProxyProtocol),
+ * so admitting them as "the proxy that applies" would only downgrade DNS pinning.
+ */
+function usableHttpProxyUrl(raw: string | undefined): string | null {
+  if (!raw) return null;
+  try {
+    const scheme = new URL(raw).protocol;
+    return scheme === "http:" || scheme === "https:" ? raw : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * The proxy URL selected by configured outbound fetch for `url`, or null when none applies.
  *
  * Bun selects by scheme: `HTTPS_PROXY` for `https:` targets, `HTTP_PROXY` for `http:`.
- * A SOCKS5 `ALL_PROXY` is selected by the explicit wrapper first; other ALL_PROXY
- * schemes remain excluded because the native HTTP fetch does not honor them.
+ * A SOCKS5 `ALL_PROXY` is selected by the explicit wrapper first. A non-SOCKS
+ * `ALL_PROXY` is still honoured by the native fetch for plain `http:` targets on
+ * every platform the CI matrix covers — the provider-outbound e2e drives exactly that
+ * request through the proxy on Linux, macOS and Windows. For `https:` targets the
+ * SOCKS wrapper remains the only `ALL_PROXY` route this module counts.
  * Presence of *some* proxy variable (`outboundProxyConfigured`) is not that guarantee.
  */
 export function effectiveProxyFor(
@@ -107,8 +125,47 @@ export function effectiveProxyFor(
   // The installed SOCKS wrapper takes this route before Bun sees scheme proxies.
   const socksProxy = socks5ProxyFromEnv(env);
   if (socksProxy) return socksProxy;
+  const schemeValue = env[key]?.trim() || env[key.toLowerCase()]?.trim();
+  if (schemeValue) {
+    // A SOCKS URL in a scheme-matched variable is a usable proxy: admission
+    // binds it explicitly and the transport follows, so it applies here too.
+    if (isSocks5ProxyUrl(schemeValue)) return schemeValue;
+    // A present but unusable scheme-matched variable fails closed: it is not a
+    // proxy Bun fetch can use, and it must not fall through to ALL_PROXY either.
+    // If Bun would have used ALL_PROXY here, keeping the DNS-pinned transport is
+    // the safe direction; if it would not, this is exactly right.
+    return usableHttpProxyUrl(schemeValue);
+  }
+  if (url.protocol !== "http:") return null;
+  return usableHttpProxyUrl(env.ALL_PROXY?.trim() || env.all_proxy?.trim());
+}
+
+/**
+ * The proxy a request can be explicitly bound to for fake-IP admission, or
+ * null: a scheme-matched variable or a SOCKS5 `ALL_PROXY`. This is the
+ * stricter documented gate for Mihomo IPv6 fake-IP answers — a non-SOCKS
+ * `ALL_PROXY` does not count here even when `effectiveProxyFor` reports it,
+ * because admission pins the transport to the returned value and the gate's
+ * contract is stated in those terms. The scheme-matched value counts only as
+ * a usable binding — a SOCKS or http(s) URL; anything else would admit a
+ * fake-IP answer nothing can resolve.
+ */
+export function schemeMatchedProxyFor(
+  url: URL,
+  env: ProxyEnvMap = process.env,
+): string | null {
+  const key: ProxyEnvKey | null = url.protocol === "https:"
+    ? "HTTPS_PROXY"
+    : url.protocol === "http:"
+      ? "HTTP_PROXY"
+      : null;
+  if (!key) return null;
+  const socksProxy = socks5ProxyFromEnv(env);
+  if (socksProxy) return socksProxy;
   const value = env[key]?.trim() || env[key.toLowerCase()]?.trim();
-  return value ? value : null;
+  if (!value) return null;
+  if (isSocks5ProxyUrl(value)) return value;
+  return usableHttpProxyUrl(value);
 }
 
 export function isSocks5ProxyUrl(proxy: string): boolean {
@@ -120,16 +177,34 @@ export function socks5ProxyFromEnv(env: ProxyEnvMap = process.env): string | und
   return candidates.find(value => typeof value === "string" && isSocks5ProxyUrl(value));
 }
 
+/**
+ * A request-scoped proxy decision as the outbound transports express it.
+ *
+ * `false` is Bun's documented "connect directly": it overrides HTTP_PROXY, HTTPS_PROXY and
+ * ALL_PROXY, and it overrides NO_PROXY too. Bun treats `undefined`, `null` and `""` alike as
+ * "no option given" and falls back to the environment, so none of those can express direct
+ * egress. Declared locally because the value travels through `RequestInit`, which does not
+ * carry it in the ambient DOM types.
+ */
+export type ProxyCapableRequestInit = RequestInit & { proxy?: string | false };
+
 export function configuredOutboundFetch(
   input: RequestInfo | URL,
   init?: RequestInit,
   fallback?: typeof globalThis.fetch,
 ): Promise<Response> {
   const base = fallback ?? (globalThis.fetch === installedFetch ? nativeFetch : globalThis.fetch);
-  const explicitProxy = (init as (RequestInit & { proxy?: string }) | undefined)?.proxy;
-  const proxy = typeof explicitProxy === "string"
-    ? (isSocks5ProxyUrl(explicitProxy) ? explicitProxy : undefined)
-    : socks5ProxyFromEnv();
+  const explicitProxy = (init as ProxyCapableRequestInit | undefined)?.proxy;
+  // An explicit `false` is a decision, so it also has to win over the installed SOCKS wrapper.
+  // Reading it as "no string was supplied" would fall through to ALL_PROXY and send a request
+  // the caller pinned to direct egress through the global SOCKS proxy instead — the silent
+  // substitution the caller asked this option to prevent. Bun applies the same `false` to its
+  // own HTTP(S) proxy environment once the request reaches the base fetch below.
+  const proxy = explicitProxy === false
+    ? undefined
+    : typeof explicitProxy === "string"
+      ? (isSocks5ProxyUrl(explicitProxy) ? explicitProxy : undefined)
+      : socks5ProxyFromEnv();
   let url: URL;
   try {
     url = new URL(input instanceof Request ? input.url : String(input));

package/src/lib/request-execution-budget.ts

@@ -165,6 +165,28 @@ export interface RequestExecutionBudget extends TransientSendBudget {
   readonly alternateTargetSends: number;
   readonly targetTransitions: number;
   readonly lastTargetKey: string | undefined;
+  /**
+   * Spend one operator-granted replacement for an AMBIGUOUS failure of this logical request,
+   * up to `limit`. False once the request has none left.
+   *
+   * It lives on the budget rather than beside the policy that grants it because it has to be
+   * shared exactly where the physical-send ledger is shared. A combo child derives its own
+   * budget from the parent's ledger, and two counters would let a request whose parent leg
+   * reset before the head and whose child leg reset after it replace an unknown-state send
+   * twice. It is NOT a send budget: an authorised replacement still has to fit inside
+   * `remainingBaseSends` like every other send.
+   *
+   * `limit` is the ceiling the ASKING leg is authorised to present, and the request keeps the
+   * smallest one any leg has presented. A leg reads it from `route.provider`, which credential
+   * rotation, OAuth refresh, transport resolution and a combo target all reassign mid-request,
+   * so a per-call ceiling meant the number of duplicate inferences a request could make
+   * depended on which row happened to ask last: a row granting one, then a row granting two,
+   * bought a second replacement of a turn that may already have run.
+   *
+   * Optional so a hand-written stub that satisfies the shape test keeps typechecking; a caller
+   * that cannot reach it has no operator override, which is the fail-closed answer.
+   */
+  claimAmbiguousResend?(limit: number): boolean;
 }
 
 const RESERVE_FUNDED_CLASSES: ReadonlySet<SendClass> = new Set<SendClass>([
@@ -192,11 +214,49 @@ let logicalRequestSeq = 0;
 interface SharedSendLedger {
   spent: number;
   pendingExternalSends: number;
+  /**
+   * Spend one of this logical request's replacements for an ambiguous failure. Beside `spent`
+   * for the same reason `pendingExternalSends` is: a derived scope that shared one without the
+   * other would hand the request a second grant.
+   *
+   * A function rather than the raw count, because the count is not the whole state. The
+   * ceiling belongs to the request too, and a bridged scope has no counter of its own to keep
+   * it in -- it has to ask whoever holds the request's grant.
+   */
+  claimAmbiguousResend(limit: number): boolean;
   readonly observer?: RequestSendObserver;
 }
 
 const sharedSendLedgers = new WeakMap<RequestExecutionBudget, SharedSendLedger>();
 
+/**
+ * One logical request's replacement grant: how many it has spent, and the ceiling it is held
+ * to.
+ *
+ * The ceiling is the SMALLEST any leg has presented rather than whatever the current leg
+ * presents. Each leg reads its number from the provider row it is running against, and that
+ * row changes inside one request -- credential rotation, OAuth refresh, transport resolution
+ * and each combo target reassign it. Taking the asking leg's number let a request that had
+ * already spent the one replacement a strict row granted buy another as soon as a more
+ * permissive row asked, which is a second duplicate inference of one turn.
+ */
+function createAmbiguousResendGrant(): (limit: number) => boolean {
+  let claimed = 0;
+  let ceiling: number | undefined;
+  return (limit: number): boolean => {
+    const presented = Number.isFinite(limit) ? Math.trunc(limit) : 0;
+    // A zero or nonsense ceiling refuses on its own and leaves the request's alone. It is a
+    // caller that cannot state a grant, not an operator narrowing this request: a leg with no
+    // policy is refused before it ever claims, so binding the request to a malformed number
+    // would only let such a caller cancel a grant an opted-in row really made.
+    if (presented <= 0) return false;
+    ceiling = ceiling === undefined ? presented : Math.min(ceiling, presented);
+    if (claimed >= ceiling) return false;
+    claimed += 1;
+    return true;
+  };
+}
+
 function createRequestExecutionBudgetWithLedger(
   policy: RequestExecutionBudgetPolicy,
   logicalRequestId: string | undefined,
@@ -239,6 +299,9 @@ function createRequestExecutionBudgetWithLedger(
       const capped = Number.isFinite(cap) ? Math.trunc(cap) : 0;
       return Math.max(0, Math.min(capped, policy.baseSendAllowance - counter.spent));
     },
+    claimAmbiguousResend(limit: number): boolean {
+      return counter.claimAmbiguousResend(limit);
+    },
     reserveDispatch(intent: DispatchIntent): DispatchDecision {
       if (intent.replaySafe === false) return { allowed: false, reason: "not-replay-safe" };
       if (counter.spent >= policy.maxTotalModelSends) return { allowed: false, reason: "total-exhausted" };
@@ -336,6 +399,7 @@ export function createRequestExecutionBudget(
   return createRequestExecutionBudgetWithLedger(policy, logicalRequestId, {
     spent: 0,
     pendingExternalSends: 0,
+    claimAmbiguousResend: createAmbiguousResendGrant(),
     ...(observer ? { observer } : {}),
   });
 }
@@ -375,6 +439,14 @@ function ledgerFor(parent: RequestExecutionBudget): SharedSendLedger {
     set spent(next: number) { parent.used = next; },
     get pendingExternalSends(): number { return pendingExternalSends; },
     set pendingExternalSends(next: number) { pendingExternalSends = next; },
+    // Asked of the parent rather than counted here. A local counter is a SECOND grant: two
+    // scopes derived from one bridged parent, or one scope beside the parent it was derived
+    // from, each replaced an unknown-state send once. Pending bookings and the durable-spend
+    // observer genuinely cannot cross this boundary because they are private to the factory,
+    // but the grant can -- `claimAmbiguousResend` is public on the parent. A parent that does
+    // not implement it grants nothing, which is the fail-closed answer for a send whose
+    // upstream state is unknown.
+    claimAmbiguousResend: (limit: number): boolean => parent.claimAmbiguousResend?.(limit) === true,
   };
 }
 

package/src/lib/request-failure-attribution.ts

@@ -0,0 +1,183 @@
+/**
+ * Derive how far a failed request got and why, from the closed facts the recorder already holds.
+ *
+ * #2366 asked for durable failure attribution and shipped its own `FailureSide` and seven-member
+ * `FailureStage` to carry it. Those are a second attribution vocabulary beside the one that
+ * landed in {@link ../lib/request-failure-model}, and two vocabularies for one question is the
+ * class of defect that blocked 2.60.0. This module is the same answer expressed in the landed
+ * vocabulary: no new stage names, no new cause names, and no new record store.
+ *
+ * Everything it reads is a CLOSED value the row already carries -- an HTTP status, a terminal
+ * status, a close reason, a transport phase, a recovery kind. It never reads `errorCode` or
+ * `upstreamError`, which are open strings assembled partly from upstream text: a classification
+ * keyed on those is a different answer per provider and per locale, and a grouping key built from
+ * them cannot promise it carries no content.
+ *
+ * MUST stay a leaf. Its only imports are types and the two tables it decides with, so nothing
+ * here can pull the usage or budget subsystems into a request path that lacked them.
+ */
+import type { AttemptRecoveryKind, RequestFailureCause, RequestFailureStage } from "../usage/telemetry-contract";
+import { causeForRecoveryKind } from "./request-failure-model";
+import { classifyRequestOutcome, type RequestOutcomeFacts } from "../usage/request-outcome";
+
+/**
+ * What the recorder knows about one finished exchange at the single seam every request passes.
+ *
+ * Deliberately the same narrow set {@link RequestOutcomeFacts} reads, plus the four observation
+ * facts a stage needs. A field that could carry a provider name, a model, an account or upstream
+ * text is absent by construction rather than by review.
+ */
+export interface RequestFailureFacts extends RequestOutcomeFacts {
+  readonly transportPhase?: "pre_headers" | "mid_stream" | "terminal_sse" | undefined;
+  /** Where the status and message came from: an origin response, or a tail this proxy wrote. */
+  readonly terminalSource?: "upstream" | "synthetic" | undefined;
+  /** True when the upstream stream died after its head was committed. */
+  readonly streamAborted?: boolean | undefined;
+  /** True once any output-bearing event reached the caller; `firstOutputMs` is the usual source. */
+  readonly outputObserved?: boolean | undefined;
+  /** True once a tool call or other externally visible effect was relayed to the caller. */
+  readonly sideEffectObserved?: boolean | undefined;
+  /** True when this proxy answered the turn itself and issued no upstream request. */
+  readonly locallyAnswered?: boolean | undefined;
+  /**
+   * Recovery kinds recorded on the attempt that ended the request, in the order they happened.
+   * Only the LAST one is ever consulted, and only under the narrow rule below.
+   */
+  readonly recoveryKinds?: readonly AttemptRecoveryKind[] | undefined;
+  /**
+   * A cause the CALLER proved, which the status alone cannot reconstruct.
+   *
+   * Set only by a finalizer that is sealing an attempt it knows the rejection for -- the
+   * key-account rotation seals the previous attempt because a named recovery rejected it, and
+   * that argument is direct evidence rather than an inference from history. It outranks the
+   * status table and is outranked by a client cancel, which is a fact about the caller and not
+   * about the origin.
+   */
+  readonly causeHint?: RequestFailureCause | undefined;
+}
+
+/**
+ * How far the caller's view of the exchange got.
+ *
+ * Total by construction and ordered downward from the most committed observation, so a fact that
+ * proves a later stage wins over one that only proves an earlier one. The boundary between
+ * `headers-only` and `protocol-prelude` is the one genuinely debatable step -- a non-streaming
+ * 4xx error body is a body, but not a protocol body event -- and it is safe to argue about
+ * because both stages carry the same `nothing-observed` commitment, so no resend decision turns
+ * on which side of it a row lands.
+ */
+export function deriveRequestFailureStage(facts: RequestFailureFacts): RequestFailureStage {
+  if (facts.terminalStatus === "completed" && facts.outputObserved === true) return "terminal";
+  if (facts.sideEffectObserved === true) return "side-effect";
+  if (facts.outputObserved === true) return "semantic-output";
+  if (facts.terminalStatus !== undefined
+    || facts.closeReason === "terminal"
+    || facts.transportPhase === "mid_stream"
+    || facts.transportPhase === "terminal_sse") return "protocol-prelude";
+  if (facts.status >= 100) return "headers-only";
+  return "pre-header";
+}
+
+/**
+ * The two recovery kinds that name a 4xx the status alone cannot tell apart.
+ *
+ * `causeForRecoveryKind` answers why a recovery was ATTEMPTED, which is usually a different
+ * question from why the request finally failed -- one that recovered from a 401 and then died on
+ * a 500 failed for the 500. So the rule here is deliberately narrow on three axes at once: only
+ * these two kinds, only when they are the LAST recovery this attempt recorded, and only when the
+ * attempt then ended on the very status that recovery was made for. Everything else falls
+ * through to the status table.
+ *
+ * The residual: a ciphertext recovery that SUCCEEDED, followed by an unrelated 400 on the same
+ * attempt, still reads as `ciphertext-refusal`, because a successful recovery does not currently
+ * clear its own evidence. Closing that belongs in the recovery path rather than here -- it is
+ * recorded in this lane's devlog as the next step -- and the rule is kept meanwhile because
+ * without it a rejected ciphertext, a rejected reasoning parameter and a rejected payload are one
+ * undifferentiated answer, which is three different remedies collapsed into one.
+ */
+const STATUS_CONFIRMED_RECOVERY_KINDS: Readonly<Partial<Record<AttemptRecoveryKind, number>>> = Object.freeze({
+  "opaque-blob-rejection": 400,
+  "reasoning-effort-downgrade": 400,
+});
+
+function refinedFourHundredCause(
+  facts: RequestFailureFacts,
+): RequestFailureCause | undefined {
+  const last = facts.recoveryKinds?.at(-1);
+  if (last === undefined) return undefined;
+  const confirmedStatus = STATUS_CONFIRMED_RECOVERY_KINDS[last];
+  return confirmedStatus === facts.status ? causeForRecoveryKind(last) : undefined;
+}
+
+/**
+ * Why the request failed.
+ *
+ * Returns `undefined` for an outcome that is not a failure. An incomplete turn is a real
+ * shortfall and gets a stage, but this dictionary answers "why did it fail", and a turn cut short
+ * by `max_output_tokens` did not fail for any of these reasons; inventing one would put a
+ * fabricated cause into a metric label and a grouping key.
+ *
+ * The status is the primary evidence because it is the one fact every transport produces. Two
+ * refinements sit above it, both from closed values: a client cancel is known from the close
+ * reason before any status is consulted, and a 400 that a recovery kind identified as a rejected
+ * ciphertext or a rejected reasoning parameter is not the same answer as a rejected payload.
+ */
+export function deriveRequestFailureCause(facts: RequestFailureFacts): RequestFailureCause | undefined {
+  const outcome = classifyRequestOutcome(facts);
+  if (outcome === "completed" || outcome === "incomplete") return undefined;
+  if (outcome === "aborted") return "client-cancelled";
+  if (facts.locallyAnswered === true) return "local-refusal";
+  // A cause the finalizer proved outranks anything reconstructed from the status.
+  if (facts.causeHint !== undefined) return facts.causeHint;
+
+  const status = facts.status;
+  // Transport evidence outranks the numeric status, because a stream that died mid-flight is
+  // reported as a SYNTHETIC 502 -- a tail this proxy wrote, not an answer the origin gave. Read
+  // in status order that 502 becomes `upstream-fault`, which claims the origin answered when it
+  // did not. Both causes refuse an automatic resend, so this is an accuracy fix rather than a
+  // safety one, but a label an operator cannot trust is a label they stop reading.
+  if (facts.streamAborted === true
+    || (facts.terminalSource === "synthetic"
+      && (facts.transportPhase === "mid_stream" || facts.transportPhase === "terminal_sse"))) {
+    return "transport-ambiguous";
+  }
+  // A 2xx head that carried a failed terminal: the origin ran the turn and said it failed. With
+  // no output relayed the useful distinction is that nothing usable came back at all.
+  if (status >= 100 && status < 400) {
+    return facts.outputObserved === true ? "upstream-fault" : "empty-output";
+  }
+  if (status === 401) return "credential-rejected";
+  if (status === 403) return "credential-rejected";
+  // Payment required. Waiting out a retry window does not help; the account has to change.
+  if (status === 402) return "quota-exhausted";
+  if (status === 413) return "payload-too-large";
+  if (status === 429) return "rate-limit";
+  if (status === 451) return "policy-refusal";
+  if (status === 503) return "upstream-declined";
+  if (status >= 500) return "upstream-fault";
+  if (status >= 400) return refinedFourHundredCause(facts) ?? "payload-rejected";
+  // No response head at all, and nothing proved the bytes never left. `transport-ambiguous` is
+  // the honest answer for an unknown execution state, and it is the safe one: it refuses an
+  // automatic resend where `transport-unsent` would permit one. `transport-unsent` is reachable
+  // only through `causeHint`, from a site that classified a pre-connect failure and can prove it.
+  return "transport-ambiguous";
+}
+
+export interface RequestFailureAttribution {
+  stage: RequestFailureStage;
+  cause?: RequestFailureCause;
+}
+
+/**
+ * The attribution to persist, or `undefined` when the request completed.
+ *
+ * A completed request has no failure to attribute, and recording a stage for one would put a
+ * `terminal` row into every grouping that exists to find failures.
+ */
+export function deriveRequestFailureAttribution(
+  facts: RequestFailureFacts,
+): RequestFailureAttribution | undefined {
+  if (classifyRequestOutcome(facts) === "completed") return undefined;
+  const cause = deriveRequestFailureCause(facts);
+  return { stage: deriveRequestFailureStage(facts), ...(cause ? { cause } : {}) };
+}

package/src/lib/request-failure-model.ts

@@ -0,0 +1,236 @@
+/**
+ * One vocabulary for how far a failed request got, why it failed, and whether this proxy may
+ * send it again (roadmap items 7 and 14).
+ *
+ * These two items are one module on purpose. Item 7 wants a resend decision per failure stage;
+ * item 14 wants one cause dictionary spanning logical request, attempt, physical send and
+ * terminal. Defined apart they typecheck on each branch and contradict each other in the merge,
+ * which is the class that blocked 2.60.0.
+ *
+ * What lives here is the vocabulary and the decision derived from it. What does NOT live here is
+ * a second record store: the durable shapes stay `PersistedUsageAttempt` and
+ * `PersistedUsageEntry` in src/usage/log.ts, and every projection below reads those structurally
+ * rather than growing a parallel history.
+ *
+ * MUST stay a leaf. Its one runtime import is `src/usage/telemetry-contract.ts`, which has no
+ * imports at all; everything else it names is a type, erased at runtime. So nothing here can
+ * pull the usage or budget subsystems into a request path that did not already have them.
+ */
+import type { SendClass } from "./request-execution-budget";
+import {
+  REQUEST_FAILURE_STAGES,
+  type AttemptRecoveryKind,
+  type RequestFailureCause,
+  type RequestFailureStage,
+  type ResendPermission,
+} from "../usage/telemetry-contract";
+
+/**
+ * The vocabulary this module decides over is DECLARED in `src/usage/telemetry-contract.ts` and
+ * re-exported here, so every importer of this module keeps its path while the dashboard can
+ * reach the same rosters without pulling this file's import graph into the browser project.
+ *
+ * What stays here is the decision: the per-stage commitment, the per-cause evidence and
+ * disposition, and the resend permission derived from them.
+ *
+ * A stage is how far the OBSERVABLE progression got, not which events happened to arrive. A turn
+ * that settled carrying no output -- an empty completion, a 4xx error body -- did not reach
+ * `terminal`; it stalled below `semantic-output`, because the caller saw no answer. `terminal`
+ * means the answer was delivered, which is why it is both last and refused.
+ */
+export {
+  REQUEST_FAILURE_CAUSES,
+  REQUEST_FAILURE_STAGES,
+  RESEND_PERMISSIONS,
+} from "../usage/telemetry-contract";
+export type {
+  RequestFailureCause,
+  RequestFailureStage,
+  ResendPermission,
+} from "../usage/telemetry-contract";
+
+/** Position in {@link REQUEST_FAILURE_STAGES}. Derived, so the order is stated exactly once. */
+export function stageRank(stage: RequestFailureStage): number {
+  return REQUEST_FAILURE_STAGES.indexOf(stage);
+}
+
+/**
+ * What the caller has irreversibly observed at a stage.
+ *
+ * Named separately from the rank so a reader can see WHY a stage refuses rather than inferring it
+ * from a position, and so the three committed stages stay distinguishable in a record.
+ */
+export type StageCommitment = "nothing-observed" | "output-observed" | "effect-observed" | "answer-delivered";
+
+const STAGE_COMMITMENT = {
+  "pre-header": "nothing-observed",
+  "headers-only": "nothing-observed",
+  "protocol-prelude": "nothing-observed",
+  "semantic-output": "output-observed",
+  "side-effect": "effect-observed",
+  "terminal": "answer-delivered",
+} as const satisfies Record<RequestFailureStage, StageCommitment>;
+
+export function stageCommitment(stage: RequestFailureStage): StageCommitment {
+  return STAGE_COMMITMENT[stage];
+}
+
+/**
+ * What the cause proves about whether the origin ran the turn.
+ *
+ * This is the safety axis. `unknown` is the RFC 9110 9.2.2 case and is never upgraded by having
+ * budget left: a request whose upstream execution state is unknown is not replayable merely
+ * because a counter allows another send.
+ */
+export type UpstreamProcessingEvidence = "not-processed" | "declined" | "processed" | "unknown";
+
+const CAUSE_EVIDENCE = {
+  "transport-unsent": "not-processed",
+  "transport-ambiguous": "unknown",
+  "upstream-declined": "declined",
+  "rate-limit": "declined",
+  "quota-exhausted": "declined",
+  "credential-rejected": "declined",
+  "policy-refusal": "processed",
+  "parameter-rejected": "declined",
+  "ciphertext-refusal": "declined",
+  "payload-too-large": "declined",
+  "payload-rejected": "declined",
+  "upstream-fault": "unknown",
+  "empty-output": "processed",
+  "client-cancelled": "unknown",
+  "local-refusal": "not-processed",
+} as const satisfies Record<RequestFailureCause, UpstreamProcessingEvidence>;
+
+export function causeEvidence(cause: RequestFailureCause): UpstreamProcessingEvidence {
+  return CAUSE_EVIDENCE[cause];
+}
+
+/**
+ * What a resend would have to change to have any chance.
+ *
+ * The usefulness axis, orthogonal to safety. A policy refusal is perfectly safe to repeat and
+ * completely pointless; an ambiguous reset is the reverse.
+ */
+export type ResendDisposition = "resend-may-help" | "resend-after-repair" | "resend-is-futile";
+
+const CAUSE_DISPOSITION = {
+  "transport-unsent": "resend-may-help",
+  "transport-ambiguous": "resend-may-help",
+  "upstream-declined": "resend-may-help",
+  "rate-limit": "resend-may-help",
+  "quota-exhausted": "resend-is-futile",
+  "credential-rejected": "resend-after-repair",
+  "policy-refusal": "resend-is-futile",
+  "parameter-rejected": "resend-after-repair",
+  "ciphertext-refusal": "resend-after-repair",
+  "payload-too-large": "resend-after-repair",
+  "payload-rejected": "resend-is-futile",
+  "upstream-fault": "resend-may-help",
+  "empty-output": "resend-may-help",
+  "client-cancelled": "resend-is-futile",
+  "local-refusal": "resend-is-futile",
+} as const satisfies Record<RequestFailureCause, ResendDisposition>;
+
+export function causeDisposition(cause: RequestFailureCause): ResendDisposition {
+  return CAUSE_DISPOSITION[cause];
+}
+
+/**
+ * Whether this proxy may send the request again, from the stage it failed at and the cause.
+ *
+ * Derived from the two per-cause facts above and the per-stage commitment, rather than written
+ * out as a stage-by-cause matrix. A matrix of that size is a restatement: it would have to be
+ * re-derived by hand every time a member is added, and the cell nobody revisited is exactly how
+ * two correct branches merge into a wrong table.
+ *
+ * `refused-ambiguous` forbids an AUTOMATIC resend. It does not forbid a narrowly scoped,
+ * explicitly opted-in recovery that a maintainer reasoned about and bounded -- the reset replay
+ * behind a default-off provider flag, the single-shot empty-completion rebuild. Those are
+ * separate recorded decisions with their own acceptance, which is precisely what distinguishes
+ * them from a retry loop that fires because a counter had room.
+ */
+export function resendPermission(
+  stage: RequestFailureStage,
+  cause: RequestFailureCause,
+): ResendPermission {
+  // Any stage at which the caller observed something refuses, whatever the cause says. Testing
+  // the commitment rather than listing the committed stages is what keeps a stage added later
+  // from defaulting into permission.
+  if (STAGE_COMMITMENT[stage] !== "nothing-observed") return "refused-committed";
+  if (CAUSE_DISPOSITION[cause] === "resend-is-futile") return "refused-futile";
+  const evidence = CAUSE_EVIDENCE[cause];
+  if (evidence === "unknown" || evidence === "processed") return "refused-ambiguous";
+  return CAUSE_DISPOSITION[cause] === "resend-after-repair" ? "permitted-after-repair" : "permitted";
+}
+
+/** True for the two permissions that allow a further send. */
+export function permitsResend(permission: ResendPermission): boolean {
+  return permission === "permitted" || permission === "permitted-after-repair";
+}
+
+/**
+ * Which request-wide send budget class a resend for this cause draws on, or null when no resend
+ * of any kind makes sense.
+ *
+ * Funding is keyed on the DISPOSITION, not on the permission. A cause the table refuses to resend
+ * automatically may still be resent by a narrowly scoped recovery a maintainer opted into, and
+ * that send has to be bought from the same budget every other send comes from -- the opt-in reset
+ * replay and the bounded empty-completion rebuild both draw on the transient allowance. Keying on
+ * permission instead would leave exactly those paths unfunded, which is how a per-layer counter
+ * reappears.
+ *
+ * Only a futile cause is null. `quota-exhausted` is null rather than `account-failover` because
+ * moving accounts is a route decision this table does not make.
+ */
+const CAUSE_SEND_CLASS = {
+  "transport-unsent": "transient",
+  "transport-ambiguous": "transient",
+  "upstream-declined": "transient",
+  "rate-limit": "transient",
+  "quota-exhausted": null,
+  "credential-rejected": "auth-recovery",
+  "policy-refusal": null,
+  "parameter-rejected": "repair",
+  "ciphertext-refusal": "repair",
+  "payload-too-large": "repair",
+  "payload-rejected": null,
+  "upstream-fault": "transient",
+  "empty-output": "transient",
+  "client-cancelled": null,
+  "local-refusal": null,
+} as const satisfies Record<RequestFailureCause, SendClass | null>;
+
+export function resendSendClass(cause: RequestFailureCause): SendClass | null {
+  return CAUSE_SEND_CLASS[cause];
+}
+
+/**
+ * The cause behind each recovery this proxy already records.
+ *
+ * Total over `AttemptRecoveryKind` by construction, so a new recovery kind is a typecheck
+ * failure here rather than a row that quietly classifies as "other" in three projections.
+ */
+const RECOVERY_KIND_CAUSE = {
+  // The retried status set mixes 503, which declined, with 500, which may already have run the
+  // turn. One kind cannot say both, so it says the weaker thing.
+  "transient-5xx": "upstream-fault",
+  "connection-reset": "transport-ambiguous",
+  "oauth-401": "credential-rejected",
+  "key-401": "credential-rejected",
+  "key-429": "rate-limit",
+  "rate-limit-429": "rate-limit",
+  "anthropic-oauth-429": "rate-limit",
+  "oauth-account-429": "rate-limit",
+  "image-413": "payload-too-large",
+  // The gateway rejects a body it accepts seconds later and the replay is byte-identical, so
+  // nothing about the payload was wrong; the origin declined to take it at that moment.
+  "console-go-upload-retry": "upstream-declined",
+  "opaque-blob-rejection": "ciphertext-refusal",
+  "empty-completion": "empty-output",
+  "reasoning-effort-downgrade": "parameter-rejected",
+} as const satisfies Record<AttemptRecoveryKind, RequestFailureCause>;
+
+export function causeForRecoveryKind(kind: AttemptRecoveryKind): RequestFailureCause {
+  return RECOVERY_KIND_CAUSE[kind];
+}