@bitkyc08/opencodex 2.59.0 → 2.61.0-preview.20260922

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];
+}

package/src/lib/request-resend-gate.ts

@@ -0,0 +1,138 @@
+/**
+ * Whether one leg of a logical request may send it again, asked in the #5266 vocabulary.
+ *
+ * Two pull requests arrived at this question from opposite sides of the response head. #4942
+ * asked it for a connection that died before any head; #4989 asked it for an SSE body that
+ * died after the head while carrying only control events. Both are the same row of the stage
+ * table: a stage the caller observed nothing at, with a cause that cannot prove the origin did
+ * not run the turn. `resendPermission` answers `refused-ambiguous` for both, and
+ * request-failure-model.ts already names the only thing that may override that answer -- a
+ * narrowly scoped recovery a maintainer opted into and bounded.
+ *
+ * One override, not two. The reason this module exists rather than a boolean in each caller is
+ * that a request which resets before the head and again after it would otherwise buy a
+ * replacement send on each side, and the second one is exactly the duplicated inference the
+ * refusal exists to prevent. The allowance is claimed HERE, at the moment of authorisation, so
+ * a caller cannot ask without paying.
+ *
+ * MUST stay a leaf. It imports the vocabulary as values and everything else as types, so it
+ * reaches no request path that did not already have it.
+ */
+import {
+  causeForRecoveryKind,
+  permitsResend,
+  resendPermission,
+  resendSendClass,
+  type RequestFailureCause,
+  type RequestFailureStage,
+  type ResendPermission,
+} from "./request-failure-model";
+import type { SendClass } from "./request-execution-budget";
+import type { AttemptRecoveryKind } from "../usage/telemetry-contract";
+
+/**
+ * Why an authorisation was refused.
+ *
+ * The three ambiguous members are separate because they need different operator responses: no
+ * policy is a configuration choice, a request the proxy cannot judge is a property of the turn,
+ * and a spent allowance means the replacement already went somewhere else in this request.
+ */
+export const RESEND_REFUSALS = Object.freeze([
+  /** The caller already observed output, an effect, or the delivered answer. */
+  "committed",
+  /** Identical bytes would get the identical answer. */
+  "futile",
+  /** The origin's execution state is unknown and no operator policy overrides that. */
+  "ambiguous-no-policy",
+  /** An operator policy exists, but this request's second send could do more than re-infer. */
+  "ambiguous-request-not-replayable",
+  /** The operator policy exists and its replacement was already spent by this request. */
+  "ambiguous-allowance-spent",
+] as const);
+
+export type ResendRefusal = typeof RESEND_REFUSALS[number];
+
+/**
+ * The operator-granted replacement for ONE logical request.
+ *
+ * `claim` is the single counter both stages draw on. It is a method rather than a number
+ * because the holder is the request's send ledger, which a combo child shares with its parent;
+ * a number passed down per leg is what let each leg hold its own.
+ */
+export interface AmbiguousResendAllowance {
+  /** True when a second send of this request's body can only repeat the inference. */
+  readonly selfContained: boolean;
+  /** Spend one replacement. False once the request has none left. */
+  claim(): boolean;
+}
+
+interface ResendDecisionBase {
+  readonly stage: RequestFailureStage;
+  readonly cause: RequestFailureCause;
+  readonly permission: ResendPermission;
+  /**
+   * The recovery this send will be recorded as, when the caller asked in those terms. Carried
+   * back rather than re-chosen at the call site: the cause was derived from it, so recording a
+   * different kind would describe the send by a reason the gate never evaluated.
+   */
+  readonly recoveryKind?: AttemptRecoveryKind;
+}
+
+export type ResendDecision =
+  | ResendDecisionBase & {
+    readonly allowed: true;
+    /** Which request-wide send class funds it, or null when the cause funds no resend. */
+    readonly sendClass: SendClass | null;
+    /** True when the table refused and an operator allowance was spent to proceed. */
+    readonly spentOperatorAllowance: boolean;
+  }
+  | ResendDecisionBase & { readonly allowed: false; readonly refusal: ResendRefusal };
+
+/**
+ * Decide whether this proxy may send the request again after a failure at `stage` caused by
+ * `cause`, spending `allowance` when the table refuses only because the upstream state is
+ * unknown.
+ *
+ * The allowance is touched on exactly one path: a decision the table would otherwise refuse as
+ * ambiguous, for a request whose body the caller has judged replayable. A committed or futile
+ * failure never reaches it, so a turn that already produced output cannot quietly drain the
+ * replacement a later ambiguous reset would have been entitled to.
+ */
+export function authorizeResend(
+  stage: RequestFailureStage,
+  cause: RequestFailureCause,
+  allowance?: AmbiguousResendAllowance,
+  recoveryKind?: AttemptRecoveryKind,
+): ResendDecision {
+  const permission = resendPermission(stage, cause);
+  const base = { stage, cause, permission, ...(recoveryKind ? { recoveryKind } : {}) };
+  if (permitsResend(permission)) {
+    return { ...base, allowed: true, sendClass: resendSendClass(cause), spentOperatorAllowance: false };
+  }
+  if (permission === "refused-committed") return { ...base, allowed: false, refusal: "committed" };
+  if (permission === "refused-futile") return { ...base, allowed: false, refusal: "futile" };
+  if (!allowance) return { ...base, allowed: false, refusal: "ambiguous-no-policy" };
+  if (!allowance.selfContained) {
+    return { ...base, allowed: false, refusal: "ambiguous-request-not-replayable" };
+  }
+  // Claimed last, and only here. Asking earlier would spend the request's one replacement on a
+  // question whose answer was already no.
+  if (!allowance.claim()) return { ...base, allowed: false, refusal: "ambiguous-allowance-spent" };
+  return { ...base, allowed: true, sendClass: resendSendClass(cause), spentOperatorAllowance: true };
+}
+
+/**
+ * The same decision, asked in terms of the recovery this proxy will RECORD for the send.
+ *
+ * Deriving the cause from the recorded kind is what keeps the log honest: the reason an
+ * operator reads beside a send count is the reason the gate weighed, because it is the same
+ * value. A call site that recorded one kind and reasoned about another is how a send count
+ * stops meaning anything.
+ */
+export function authorizeResendForRecovery(
+  stage: RequestFailureStage,
+  kind: AttemptRecoveryKind,
+  allowance?: AmbiguousResendAllowance,
+): ResendDecision {
+  return authorizeResend(stage, causeForRecoveryKind(kind), allowance, kind);
+}