import { createInferenceSendBudget } from "../inference/context";
import { responsesSpendTarget } from "./request-spend-target";
import type { ResponsesRequestContext } from "./core-options";
import { claimDispatchSpendProof, createPhysicalSendReporter, createRequestExecutionBudget, isRequestExecutionBudget, hasWorkflowSendObserver, reportDispatchSends, requestHasCapturedSpendCeiling } from "../../lib/request-execution-budget";
import {
  chargeWorkflowSends,
  reserveWorkflowSend,
  workflowSendCeilingReached,
  workflowSpendCeilingReached,
} from "../../lib/workflow-budget";
import { currentWorkflowBudgetPolicy } from "../../lib/workflow-budget-config";
import { poolContinuityRefusalReason, workflowRefusalResponse } from "../workflow-refusal";
import type { AttemptRecoveryKind, AttemptRecoveryWithheld } from "../../usage/log";
import { noteAttemptRecoveryWithheld, noteAttemptSend, type RequestLogContext } from "../request-log";
import { TRANSIENT_RETRY_MAX_ATTEMPTS, SendBudgetExhaustedError, type TransientSendBudget } from "../../lib/upstream-retry";
import type { ErrorDestinationLabel } from "../../lib/error-destination";
import type { SpendScopes } from "../../lib/spend-reservation-ledger";
import { estimateTokens } from "../../lib/token-estimate";
import type {
  DispatchDecision,
  DispatchIntent,
  RequestExecutionBudget,
  SendClass,
  SingleUseDispatchPermit,
  AuxiliaryModelSend,
} from "../../lib/request-execution-budget";

/**
 * The transient-5xx ladder cap for ONE leg, given the provider's configured request total.
 *
 * `remainingTransientSendBudget(cap)` treats `cap` as a ceiling on what REMAINS, which is the
 * right shape for the fixed constant: every leg may ask for up to three, and the request-wide
 * base allowance is what actually bounds the total. A configured `transientRetryOn5xx.attempts`
 * is documented as the total for one request including the first send, so it has to be reduced
 * by what the request already sent before it is intersected with that allowance. Passing it
 * straight through would make it a per-leg ceiling instead, and a request configured at one send
 * could still reach upstream again on a recovery leg (#4893).
 *
 * An absent policy returns the constant unchanged, so a provider that configures nothing behaves
 * exactly as it does today at every call site.
 */
export function transientSendCapFor(
  configuredAttempts: number | undefined,
  sendsUsed: number,
): number {
  if (configuredAttempts === undefined) return TRANSIENT_RETRY_MAX_ATTEMPTS;
  return Math.max(0, configuredAttempts - Math.max(0, sendsUsed));
}

/** A native compact credential recovery spends one send from the shared request budget. */
export async function sendSingleCompactRecovery(
  budget: RequestExecutionBudget,
  target: () => SpendScopes,
  targetKey: string,
  destination: ErrorDestinationLabel,
  dispatch: () => Promise<Response>,
): Promise<Response> {
  const freshRetrySpend = budget.explicitSendCeiling !== undefined;
  const exhausted = () => new SendBudgetExhaustedError(destination);
  if (budget.remainingBaseSends(TRANSIENT_RETRY_MAX_ATTEMPTS) > 0) {
    const report = createPhysicalSendReporter(budget, target);
    let started = false;
    try {
      if (report.beforeSend?.(freshRetrySpend) === false) throw exhausted();
      started = true;
      return await (report.execute ? report.execute(dispatch) : dispatch());
    } finally {
      try { if (started) report(1); }
      finally { report.close?.(); }
    }
  }
  const decision = budget.reserveDispatch({ sendClass: "auth-recovery", targetKey, freshRetrySpend });
  if (!decision.allowed) throw exhausted();
  const { permit } = decision;
  const run = () => {
    if (!permit.use()) { permit.release(); throw exhausted(); }
    return dispatch();
  };
  return permit.execute ? permit.execute(run) : run();
}

/** Read the admitted target's ceilings without claiming a send or a prepaid proof. */
export function responsesHasCapturedSpendCeiling(
  sendBudget: TransientSendBudget,
  req: Pick<Request, "headers">,
  logCtx: RequestLogContext,
  target: SpendScopes,
): boolean {
  return requestHasCapturedSpendCeiling(sendBudget, {
    rootId: req.headers.get("x-codex-parent-thread-id")?.trim() || undefined,
    identityId: target.identityId ?? logCtx.accountLogLabel,
    poolId: target.poolId ?? logCtx.spendPoolId ?? logCtx.provider,
  });
}

/** Owns the shared request send counter and recovery permits. */
export function createResponsesSendBudget(
  requestContext: Pick<ResponsesRequestContext, "options" | "req" | "logCtx">,
) {
  const { options, req, logCtx } = requestContext;


  // One transient-retry budget for the whole LOGICAL request, read ABOVE the passthrough branch
  // so that branch shares it too. It used to be a local declared below, which put it in the
  // temporal dead zone for the passthrough sends and left each recovery leg taking the helper's
  // fresh default of 3. It is now a holder carried on options, so a combo child inherits the
  // parent's spend instead of starting over per target -- both halves of the measured
  // amplification in #4546.
  const sendBudget = options.sendBudget ?? createInferenceSendBudget(req, logCtx, options.hostedAdvisorSpendScope?.ceilings);
  // The root workflow is the user-visible task. A per-request cap cannot bound a fan-out that
  // sends once per child seven hundred times, so every send charged to the request is charged
  // to the root as well (#4546).
  const workflowRootId = req.headers.get("x-codex-parent-thread-id")?.trim() || undefined;
  const physicalWorkflowAccounting = hasWorkflowSendObserver(sendBudget);
  // A child that owns its Combo booking settles that exact permit through the reporter, even
  // when its caller handed ownership over only as `comboInitialSend`.
  const inheritedPermit = options.compactionRecoveryPermit ?? options.comboDispatchPermit
    ?? options.comboInitialSend?.permit;
  let pendingHopPermit: SingleUseDispatchPermit | undefined = options.compactionRecoveryPermit;
  let initialPermit = options.comboInitialSend?.permit;
  const compactHandoffSendCeiling = options.compactionRecoveryKind === "compaction-v1"
    && isRequestExecutionBudget(sendBudget) && sendBudget.used > 0 ? sendBudget.explicitSendCeiling : undefined;
  // Count this owner's physical sends, not later bookings made by other shared-ledger owners.
  // Direct callers retain sends reported before this owner was constructed.
  let targetSendsUsed = initialPermit ? 0 : Math.max(0,
    sendBudget.used - (options.compactionRecoveryPermit ? 1 : 0));
  /** Attribute reported physical sends to this owner; the prepaid booking is spent once reported. */
  const noteTargetSends = (charged: number): void => {
    targetSendsUsed += charged;
    if (charged > 0) initialPermit = undefined;
  };
  const recordTransientSends = (used: number, permit?: SingleUseDispatchPermit, workflowAlreadyCounted = false): void => {
    const charged = Math.max(0, used);
    noteTargetSends(charged);
    reportDispatchSends(sendBudget, charged, permit, workflowAlreadyCounted);
    options.onCompactionRecoverySendsReported?.(charged);
    if (!physicalWorkflowAccounting && !workflowAlreadyCounted) chargeWorkflowSends(workflowRootId, charged);
  };
  const noteTransientSends = (used: number): void => recordTransientSends(used, pendingHopPermit ?? inheritedPermit);
  const physicalSendReporter = (permit?: SingleUseDispatchPermit, explicitContinuation = false,
    wireEstimate?: { inputTokens: number; outputCeilingTokens: number },
    receiptOwned = false, targetKey = explicitContinuation ? `native-continuation:${crypto.randomUUID()}` : undefined) => {
    let unreportedWorkflowStarts = 0;
    const reporter = createPhysicalSendReporter(sendBudget, () => ({ ...responsesSpendTarget(logCtx),
      ...(targetKey ? { targetKey } : {}),
      ...(wireEstimate ? { estimate: wireEstimate, explicitEstimate: true } : {}) }), permit, charged => {
      noteTargetSends(Math.max(0, charged));
      options.onCompactionRecoverySendsReported?.(charged);
      const prepaid = Math.min(unreportedWorkflowStarts, Math.max(0, charged));
      unreportedWorkflowStarts -= prepaid;
      if (!physicalWorkflowAccounting) chargeWorkflowSends(workflowRootId, charged - prepaid);
    }, { explicitContinuation, receiptOwned });
    if (compactHandoffSendCeiling !== undefined && !explicitContinuation && reporter.beforeSend) {
      const beforeSend = reporter.beforeSend;
      let prepaid = permit !== undefined;
      reporter.beforeSend = freshRetry => {
        if (!beforeSend(freshRetry || !prepaid)) return false;
        prepaid = false;
        return true;
      };
    }
    if (!receiptOwned && workflowRootId && !physicalWorkflowAccounting) {
      const beforeSend = reporter.beforeSend, close = reporter.close;
      let closed = false;
      reporter.beforeSend = reserveRetrySpend => {
        const policy = currentWorkflowBudgetPolicy();
        // Check before a legacy permit's admission can spend it. No await separates this
        // read from the atomic claim, and the reporter owns the later accounting receipt.
        if (closed || workflowSendCeilingReached(workflowRootId, policy) || beforeSend?.(reserveRetrySpend) === false
          || !reserveWorkflowSend(workflowRootId, policy)) return false;
        unreportedWorkflowStarts++;
        return true;
      };
      reporter.close = () => { closed = true; close?.(); };
    }
    return reporter;
  };
  // Capture at helper creation, before another leg can replace the pending handoff.
  const transientSendReporter = (permit = pendingHopPermit ?? inheritedPermit, receiptOwned = false) =>
    physicalSendReporter(permit, false, undefined, receiptOwned);
  // A helper owns a fresh booking, never a routed leg's permit or target-local retry counter.
  const dispatchSidecarSend: AuxiliaryModelSend = async (target, dispatch) => {
    if (!isRequestExecutionBudget(sendBudget)) {
      if (!reserveWorkflowSend(workflowRootId, currentWorkflowBudgetPolicy())) throw new SendBudgetExhaustedError();
      sendBudget.used++;
      return dispatch();
    }
    const decision = sendBudget.reserveDispatch({
      sendClass: "auxiliary", targetKey: target.targetKey,
      spendScopes: { poolId: target.poolId, identityId: target.identityId ?? "" },
      spendEstimate: target.estimate,
    });
    if (!decision.allowed) throw new SendBudgetExhaustedError();
    const permit = decision.permit;
    const run = () => {
      const policy = currentWorkflowBudgetPolicy();
      // No await separates this precheck, synchronous permit admission and the root claim.
      // Refuse before use() so the finally path can return an unused reservation.
      if (!physicalWorkflowAccounting && workflowSendCeilingReached(workflowRootId, policy)) throw new SendBudgetExhaustedError();
      if (!permit.use()) throw new SendBudgetExhaustedError();
      if (!physicalWorkflowAccounting && !reserveWorkflowSend(workflowRootId, policy)) throw new SendBudgetExhaustedError();
      return dispatch();
    };
    try { return await (permit.execute ? permit.execute(run) : run()); }
    finally { permit.release(); }
  };
  // Refused before any dispatch, and deliberately not by evicting the root's ledger entry:
  // dropping the record to make room would hand the fan-out a fresh allowance, which is the
  // laundering this ceiling exists to stop. The client is told the task needs a new grant
  // rather than being given a synthetic upstream error.
  if (workflowSendCeilingReached(workflowRootId, currentWorkflowBudgetPolicy())) {
    // A log context exists here, unlike at HTTP admission, so the row this request writes is
    // marked synthetic rather than reading as a request that vanished with zero sends.
    return workflowRefusalResponse("workflow-sends-exhausted", logCtx, undefined, workflowRootId);
  }
  // The token ceiling asked at the same seam, for the same reason the count one is asked here.
  // Without it a spent root reaches the dispatch ladder, is refused by the ledger at the first
  // physical send, and answers with the generic send-budget error every exhausted request
  // returns -- a refusal an operator cannot tell from an ordinary budget exhaustion, on a
  // ceiling they configured themselves. Asked before dispatch, it names the scope and the
  // number instead. Returns undefined and touches no ledger when no ceiling is configured.
  // Passthrough reports sends after they leave. Invalid or conflicting identity evidence
  // still refuses here as well as in reserve(), including requests with no workflow root.
  // Positive unbound balances alone are instead overlaid on each candidate pool below.
  const continuityRefusal = poolContinuityRefusalReason();
  if (continuityRefusal) {
    return workflowRefusalResponse(continuityRefusal, logCtx, undefined, workflowRootId);
  }
  const prepaid = isRequestExecutionBudget(sendBudget)
    ? claimDispatchSpendProof(sendBudget, options.compactionRecoveryPermit ?? options.comboDispatchPermit) : undefined;
  const admissionPolicy = isRequestExecutionBudget(sendBudget) ? sendBudget.spendAdmissionPolicy : undefined;
  const spentCeiling = workflowSpendCeilingReached(workflowRootId, undefined, logCtx.spendPoolId ?? logCtx.provider, prepaid, admissionPolicy);
  if (spentCeiling) {
    return workflowRefusalResponse(
      "workflow-spend-exhausted",
      logCtx,
      undefined,
      workflowRootId,
      spentCeiling,
    );
  }
  // No floor. Math.max(1, ...) meant an exhausted request still funded one send on every
  // recovery leg, so a bounded per-leg allowance never became a bounded per-request one.
  const remainingTransientSendBudget = (budget: number): number =>
    isRequestExecutionBudget(sendBudget)
      ? sendBudget.remainingBaseSends(budget)
      : Math.max(0, budget - sendBudget.used);
  // The adapter contract needs the full budget, not just the counter. options.sendBudget is
  // typed as the narrow holder so a caller that predates this can still pass one, so narrow it
  // once here rather than asserting at each adapter call site.
  const adapterSendBudget = isRequestExecutionBudget(sendBudget) ? sendBudget : undefined;
  const hasCapturedSpendCeiling = (target: SpendScopes = {}): boolean => responsesHasCapturedSpendCeiling(sendBudget, req, logCtx, target);
  /**
   * Records an adapter's OWN inner retries against this attempt.
   *
   * The first receipt binds the attempt's identity. The budget counts every receipt, and
   * subsequent sends add to the active attempt without rebinding the credential.
   */
  const noteAdapterPhysicalSend = (
    inputTokens: number | undefined,
    send: { ordinal: number; recovery?: AttemptRecoveryKind },
  ): void => {
    targetSendsUsed += 1;
    if (send.ordinal > 1) noteAttemptSend(logCtx.activeAttempt, inputTokens, send.recovery);
  };
  /**
   * Records a recovery an adapter was ready to make and the budget refused.
   *
   * No send happened, so this deliberately does not touch `sendCount`. It is the other half of
   * the pair that makes a one-send log readable: no recovery kind AND no withheld reason means
   * nothing was eligible; a withheld reason means something was (#5044).
   */
  const noteAdapterRecoveryWithheld = (withheld: { reason: AttemptRecoveryWithheld }): void => {
    noteAttemptRecoveryWithheld(logCtx.activeAttempt, withheld.reason);
  };
  /**
   * Whether this request has any base send left under `cap`.
   *
   * The cap is a parameter because a lane that reads a provider's configured
   * `transientRetryOn5xx` ladder has to ask this question at the SAME cap its sends use.
   * Asking at the constant while dispatching at a configured value lets a provider with
   * headroom be told it is exhausted, and lets one configured below the constant pass this
   * check and then be refused at the send (#4893). Defaulted, so every existing caller keeps
   * the constant it already used.
   */
  const sendBudgetExhausted = (cap: number = TRANSIENT_RETRY_MAX_ATTEMPTS): boolean =>
    remainingTransientSendBudget(cap) === 0;
  /**
   * Spend one operator-granted replacement for an ambiguous failure of THIS logical request.
   *
   * The counter is the execution budget's, so a combo child that derives its own scope draws on
   * the same grant. A budget that predates it -- a stub, or a caller that passed the narrow
   * holder -- cannot grant anything, and refusing is the fail-closed answer for a send whose
   * upstream state is unknown.
   */
  const claimAmbiguousResend = (limit: number): boolean =>
    isRequestExecutionBudget(sendBudget) && sendBudget.claimAmbiguousResend?.(limit) === true;
  /**
   * A credential hop reserves the send its own replay will make, and that replay is a recovery
   * leg. The leg must SPEND the hop's reservation instead of taking a second one: the
   * final-recovery reserve is single, so a rebuild that reserved on top of a hop would be
   * refused and the request would answer with a synthetic 502 in place of the real 429 the hop
   * was recovering from.
   */
  /**
   * The budget an adapter's OWN dispatch ladder reserves against.
   *
   * Kiro and Cursor reserve once per physical send, and that is right: their ladders are the
   * layer that actually sends, and counting one adapter call as one send hid up to eighteen
   * upstream requests. But a credential hop has already booked the replay it is about to make,
   * and a reservation IS the charge, so an adapter that reserves again turns one physical send
   * into two charges -- and once the base allowance is spent, into a refusal that answers with
   * a synthetic error in place of the 429 the hop was recovering from (#4709).
   *
   * The hop hands its reservation down through `pendingHopPermit`, the same seam the
   * passthrough ladder already uses, and this view spends it on the adapter's FIRST
   * reservation. Every later send in that ladder is a new physical send and is charged
   * normally. Claiming preserves the refundable single-use booking until physical dispatch;
   * an abandoned replay releases only that exact booking.
   */
  const permits = {
    /** Transfer the initial booking once to the adapter dispatch owner. */
    claimInitialPermit: () => {
      const permit = initialPermit;
      initialPermit = undefined;
      return permit;
    },
    /** Transfer a pending recovery booking once, without creating a new allowance. */
    claimHopPermit: () => {
      const permit = pendingHopPermit;
      pendingHopPermit = undefined;
      return permit;
    },
  };
  const adapterDispatchBudget = adapterSendBudget === undefined
    ? undefined : adapterDispatchBudgetView(adapterSendBudget, permits);
  // Preserve the existing opted-in view for direct callers, including its admitted replacement
  // of an already-settled hop. Exact-owned Combo and sidecar handoffs use the ordinary view.
  const refundableAdapterDispatchBudget = adapterSendBudget === undefined
    ? undefined : adapterDispatchBudgetView(adapterSendBudget, permits, true);
  /**
   * How many sends a recovery leg may make, and the permit that authorises the last one.
   *
   * The base allowance is spent first. Once it is gone a recovery class may still draw the
   * single shared final-recovery reserve -- which is what keeps the validated sanitized rebuild
   * after a 5xx streak alive at four total sends -- but an account move and a rebuild cannot
   * each take one. A caller with an exact provider total can suppress that reserve. The
   * `countedExternally` flag exists because these legs run through the retry helper, which reports
   * the same send again through `onSendsConsumed`.
   */
  const recoverySendAllowance = (
    cap: number,
    sendClass: SendClass,
    targetKey: string,
    options: { allowFinalRecoveryReserve?: boolean } = {},
  ): { attempts: number; permit?: SingleUseDispatchPermit } => {
    const base = remainingTransientSendBudget(cap);
    // The hop already paid for this leg's first send. Include it in the helper's total
    // attempts without charging it again, or the final account loses one transient attempt.
    if (base > 0) return { attempts: Math.min(cap, base + (pendingHopPermit ? 1 : 0)) };
    // A provider-configured transient total is an exact physical-send ceiling. Once it is
    // exhausted, the request-wide recovery reserve must not silently widen it. The default stays
    // permissive so unconfigured providers retain the guarded profile's fourth recovery send.
    if (options.allowFinalRecoveryReserve === false) return { attempts: 0 };
    if (pendingHopPermit) {
      const hopPermit = pendingHopPermit;
      pendingHopPermit = undefined;
      return { attempts: 1, permit: hopPermit };
    }
    if (!isRequestExecutionBudget(sendBudget)) return { attempts: 0 };
    const decision = sendBudget.reserveDispatch({ sendClass, targetKey, countedExternally: true });
    return decision.allowed ? { attempts: 1, permit: decision.permit } : { attempts: 0 };
  };
  /**
   * One credential hop of this logical request, admitted by the INTERSECTION of two bounds.
   *
   * The snapshotted generic OAuth and Anthropic roster caps
   * bound rotation within one credential roster. What neither
   * can see is everything else this request already sent, so three hops layered on a spent
   * budget still reached upstream three more times. A hop now happens only when its own layer
   * cap AND the shared budget both permit it, and the smaller of the two wins.
   *
   * `countedExternally` is for the hops whose replay goes out through the retry helper, which
   * reports the same physical send through `onSendsConsumed`; the others are charged here and
   * nowhere else. A refusal is not an error: the caller keeps the real upstream response --
   * status, `Retry-After`, quota body -- because return-the-last-answer is the exhaustion
   * contract this unit settled on.
   */
  /**
   * A credential rotation inside ONE provider's roster is "auth-recovery", not
   * "account-failover". The distinction is load-bearing: "account-failover" sets
   * `isAlternateTarget` unconditionally, so under `maxAlternateTargetSends: 1` the first
   * rotation would refuse every later one AND consume the single slot a genuine cross-pool
   * move needs -- a roster whose first two accounts are both 429'd would return the 429
   * while a free third account sat unused. The roster cap bounds how far rotation walks;
   * the shared total bounds how many sends the request makes. Reserve "account-failover"
   * for a real move between pools.
   */
  const reserveCredentialHop = (
    sendClass: SendClass,
    targetKey: string,
    countedExternally = false,
  ): { allowed: boolean; permit?: SingleUseDispatchPermit } => {
    if (!isRequestExecutionBudget(sendBudget)) return { allowed: true };
    const decision = sendBudget.reserveDispatch({
      sendClass,
      // A same-provider credential hop is not a model/endpoint transition. Its diagnostic
      // label must not replace the physical target used by the adapter's next retry.
      targetKey: sendClass === "auth-recovery" ? sendBudget.lastTargetKey ?? targetKey : targetKey,
      countedExternally,
    });
    return decision.allowed ? { allowed: true, permit: decision.permit } : { allowed: false };
  };
  /**
   * Both classes share the one reserve, so this only changes what the decision is called --
   * but a recovery event that says "repair" when a credential refresh drove it is the kind of
   * mislabelled evidence #4592 existed to stop.
   */
  const recoveryClassFor = (recovery: AttemptRecoveryKind): SendClass =>
    /401|429|oauth|rate-limit|key/.test(recovery) ? "auth-recovery" : "repair";

  return {
    imageRecoverySendReporter: (body: string, maxOutputTokens: number) => {
      // Each leg needs its own seed at normal capacity, on the ordinary physical-send counter.
      const reporter = physicalSendReporter(undefined, false, { inputTokens: estimateTokens(body, logCtx.model),
        outputCeilingTokens: maxOutputTokens }, false, `image-413:${crypto.randomUUID()}`);
      const beforeSend = reporter.beforeSend;
      reporter.beforeSend = () => {
        const target = responsesSpendTarget(logCtx);
        // A legacy or observe-only holder may know the ceiling without being able to reserve.
        if (adapterSendBudget?.spendEnforced !== true && hasCapturedSpendCeiling(target)) return false;
        return beforeSend?.() !== false;
      };
      return reporter;
    },
    workflowRootId,
    noteTransientSends,
    transientSendReporter,
    /**
     * A new native continuation cannot consume an initial or recovery booking. Its
     * reservation is priced on the exact successor frame about to leave — the
     * production dispatch path always supplies it. The merged outgoing body's
     * max_output_tokens replaces the output reservation when present, including null.
     * When the wire omits it, retain the caller's local output reservation: the
     * canonical backend strips unsupported output caps. Input is always remeasured.
     */
    continuationSendReporter: (frame: { body: Record<string, unknown>; text: string }) =>
      physicalSendReporter(undefined, true, {
        inputTokens: Math.max(1, estimateTokens(frame.text, logCtx.model)),
        outputCeilingTokens: typeof frame.body.max_output_tokens === "number"
          && Number.isFinite(frame.body.max_output_tokens) && frame.body.max_output_tokens > 0
          ? Math.trunc(frame.body.max_output_tokens)
          : Object.hasOwn(frame.body, "max_output_tokens") ? 0 : logCtx.spendOutputCeilingTokens ?? 0,
      }),
    remainingTransientSendBudget,
    /** Only this child's prepaid send, not every pending external booking, is spendable here. */
    initialSendAllowance: (cap: number): number => Math.min(cap,
      remainingTransientSendBudget(cap) + (initialPermit ? 1 : 0)),
    /** At final executor admission, settle only the owning booking or reserve this send. */
    noteInitialDispatch: (prepaid = initialPermit, reserveUnbookedSend = false): void => {
      const policy = currentWorkflowBudgetPolicy();
      if (!physicalWorkflowAccounting && workflowSendCeilingReached(workflowRootId, policy)) {
        prepaid?.release();
        throw new SendBudgetExhaustedError();
      }
      if (prepaid) {
        if (!prepaid.assumeCharge()) { prepaid.release(); throw new SendBudgetExhaustedError(); }
        if (prepaid === initialPermit) initialPermit = undefined;
      } else if (adapterSendBudget && (reserveUnbookedSend || options.comboInitialSend || options.compactionRecoveryPermit)) {
        const decision = adapterSendBudget.reserveDispatch({ sendClass: "transient",
          targetKey: adapterSendBudget.lastTargetKey ?? `${logCtx.provider}/${logCtx.model}` });
        if (!decision.allowed) throw new SendBudgetExhaustedError();
        if (!decision.permit.use()) { decision.permit.release(); throw new SendBudgetExhaustedError(); }
      } else {
        // Legacy direct callers can prebook without handing over a permit; keep their reporter.
        if (reserveUnbookedSend && sendBudgetExhausted()) throw new SendBudgetExhaustedError();
        if (adapterSendBudget?.claimWorkflowSend && !adapterSendBudget.claimWorkflowSend()) throw new SendBudgetExhaustedError();
        if (!physicalWorkflowAccounting && !reserveWorkflowSend(workflowRootId, policy)) throw new SendBudgetExhaustedError();
        recordTransientSends(1, pendingHopPermit ?? inheritedPermit, true);
        return;
      }
      if (!physicalWorkflowAccounting && !reserveWorkflowSend(workflowRootId, policy)) throw new SendBudgetExhaustedError();
      targetSendsUsed += 1;
      options.onCompactionRecoverySendsReported?.(1);
    },
    /** Physical sends reported by this owner; unrelated shared reservations cannot consume it. */
    get targetSendsUsed(): number { return targetSendsUsed; },
    /** Attribute sends charged by a separate recovery permit to this target. */
    noteTargetSends,
    /**
     * Charged sends, including open prepaid reservations, across this logical request.
     *
     * A live getter, not a completed-send snapshot. Initial ladders use the child's own
     * prepaid allowance and target-local count; shared admission keeps every booking spent.
     */
    get sendsUsed(): number { return sendBudget.used; },
    adapterSendBudget,
    compactHandoffSendCeiling,
    hasCapturedSpendCeiling,
    dispatchSidecarSend,
    adapterDispatchBudget,
    refundableAdapterDispatchBudget,
    noteAdapterPhysicalSend,
    noteAdapterRecoveryWithheld,
    sendBudgetExhausted,
    claimAmbiguousResend,
    get ambiguousResendSpent(): boolean {
      return isRequestExecutionBudget(sendBudget) && sendBudget.ambiguousResendSpent === true;
    },
    get pendingHopPermit(): SingleUseDispatchPermit | undefined {
      return pendingHopPermit;
    },
    set pendingHopPermit(value: SingleUseDispatchPermit | undefined) {
      pendingHopPermit = value;
    },
    recoverySendAllowance,
    reserveCredentialHop,
    recoveryClassFor,
  };
}

export type ResponsesSendBudget = Exclude<ReturnType<typeof createResponsesSendBudget>, Response>;

/**
 * A LIVE delegating view of one request's execution budget, with a credential hop's
 * reservation spendable through it.
 *
 * Every member forwards rather than copying. A spread of the budget would freeze `used`,
 * `reserveSpent` and the target counters at construction time, handing the adapter a budget
 * that can never read as exhausted -- the same class of defect as the fresh per-layer
 * allowances #4546 removed.
 */
function adapterDispatchBudgetView(
  budget: RequestExecutionBudget,
  hop: {
    claimInitialPermit: () => SingleUseDispatchPermit | undefined;
    claimHopPermit: () => SingleUseDispatchPermit | undefined;
  },
  legacyHopReplacement = false,
): RequestExecutionBudget {
  return {
    get physicalStarted() { return budget.physicalStarted; },
    get physicalLimit() { return budget.physicalLimit; },
    get workflowCountObserved() { return budget.workflowCountObserved; },
    get spendEnforced() { return budget.spendEnforced; },
    get spendPolicyStarted() { return budget.spendPolicyStarted; },
    get spendAdmissionPolicy() { return budget.spendAdmissionPolicy; },
    hasCapturedSpendCeiling: target => requestHasCapturedSpendCeiling(budget, target),
    startRequest: target => budget.startRequest?.(target),
    claimPhysicalSend: auxiliary => auxiliary ? budget.claimPhysicalSend?.(true) : budget.claimPhysicalSend?.(),
    claimContinuationPhysicalSend: () => budget.claimContinuationPhysicalSend?.(),
    claimWorkflowSend: auxiliary => (auxiliary ? budget.claimWorkflowSend?.(true) : budget.claimWorkflowSend?.()) ?? true,
    beginSpendProducer: () => budget.beginSpendProducer?.(),
    get used(): number { return budget.used; },
    set used(next: number) { budget.used = next; },
    logicalRequestId: budget.logicalRequestId,
    policyVersion: budget.policyVersion,
    policy: budget.policy,
    get reserveSpent(): boolean { return budget.reserveSpent; },
    get alternateTargetSends(): number { return budget.alternateTargetSends; },
    get targetTransitions(): number { return budget.targetTransitions; },
    get lastTargetKey(): string | undefined { return budget.lastTargetKey; },
    remainingBaseSends: (cap: number): number => budget.remainingBaseSends(cap),
    claimAmbiguousResend: (limit: number): boolean => budget.claimAmbiguousResend?.(limit) === true,
    get ambiguousResendSpent(): boolean { return budget.ambiguousResendSpent === true; },
    reserveDispatch(intent: DispatchIntent): DispatchDecision {
      // A dispatch whose upstream state is unknown is refused on its own merits. A hop that
      // already paid does not make an unsafe replay safe, so that check stays with the budget.
      if (intent.replaySafe !== false) {
        // The Combo reserves a logical provider/model identity. The child's first actual
        // endpoint is not a recovery transition; retain the original refundable permit.
        const initialPermit = hop.claimInitialPermit();
        if (initialPermit) {
          budget.bindPrepaidTarget?.(intent.targetKey);
          return { allowed: true, permit: {
            sendClass: initialPermit.sendClass,
            execute: run => initialPermit.execute ? initialPermit.execute(run) : run(),
            use: () => initialPermit.assumeCharge(),
            assumeCharge: () => initialPermit.assumeCharge(),
            release: () => initialPermit.release(),
          } };
        }
        const hopPermit = hop.claimHopPermit();
        if (hopPermit && intent.targetKey !== budget.lastTargetKey) {
          // The rotated credential can select a different regional endpoint. Replace the
          // provisional booking synchronously so the actual destination obeys transition
          // limits, while the physical send is still charged only once.
          hopPermit.release();
          return budget.reserveDispatch({ ...intent, sendClass: hopPermit.sendClass });
        }
        // Reservation precedes pacing and beforeDispatch. Transfer the exact open booking;
        // only physical consumption closes external reporting and makes it non-refundable.
        // The underlying permit enforces single use, including settlement by another owner.
        if (hopPermit !== undefined) {
          if (legacyHopReplacement) {
            let settled = false;
            let executionPermit = hopPermit;
            const confirm = (): boolean => {
              if (settled) return false;
              settled = true;
              if (hopPermit.assumeCharge()) return true;
              // Preserve the old fallback for a permit another leg already settled.
              const fresh = budget.reserveDispatch(intent);
              if (!fresh.allowed) return false;
              executionPermit = fresh.permit;
              return fresh.permit.assumeCharge();
            };
            return { allowed: true, permit: {
              sendClass: hopPermit.sendClass,
              execute: run => executionPermit.execute ? executionPermit.execute(run) : run(),
              use: confirm, assumeCharge: confirm,
              release: () => { if (!settled) { settled = true; hopPermit.release(); } },
            } };
          }
          return { allowed: true, permit: {
            sendClass: hopPermit.sendClass,
            execute: run => hopPermit.execute ? hopPermit.execute(run) : run(),
            use: () => hopPermit.assumeCharge(),
            assumeCharge: () => hopPermit.assumeCharge(),
            release: () => hopPermit.release(),
          } };
        }
      }
      return budget.reserveDispatch(intent);
    },
  };
}
