import { AsyncLocalStorage } from "node:async_hooks";
/**
 * One logical request, one execution budget (#4546).
 *
 * The amplification behind #4546 was never a single missing limit. Every layer that can
 * re-send a request -- transport retry, adapter retry, auth recovery, account failover, combo
 * failover, repair -- counted its own allowance, so a per-layer 3 composed into a per-request
 * 12. #4605 and #4608 gave the transient layers one shared counter; this module is the policy
 * that counter answers to.
 *
 * The policy is an INTERSECTION of constraints, not four independent counters. A request that
 * still has total allowance left is not thereby entitled to a second account move, and a
 * request that changed credentials does not get its target-transition allowance back. The
 * default profile keeps the recovery shape that actually works today -- three same-account
 * sends plus one alternate -- by funding the alternate from a reserve that a validated
 * sanitized repair can spend instead, but never both.
 */
import { sharedSpendPolicy, type SpendSeed, type SpendScopes, type SpendReservationProof, type SpendAdmissionPolicy, type SpendUsage } from "./spend-reservation-ledger";
import { SendBudgetExhaustedError, type RetryRecoveryAdmission, type TransientSendBudget } from "./upstream-retry";

export type SendClass =
  | "initial"
  | "transient"
  | "auth-recovery"
  | "repair"
  | "account-failover"
  | "combo-failover"
  | "auxiliary"
  | "prewarm";

/** A helper inference owns its admission and never consumes a routed leg's permit. */
export type AuxiliaryModelSend = <T>(
  target: Pick<SpendScopes, "identityId"> & { poolId: string; targetKey: string; estimate: { inputTokens: number; outputCeilingTokens: number } },
  dispatch: () => Promise<T>,
) => Promise<T>;

export interface RequestExecutionBudgetPolicy {
  /** Every model send of one logical request, including the reserve. */
  readonly maxTotalModelSends: number;
  /** Shared by the initial send, same-target transient retries, and refresh/repair legs. */
  readonly baseSendAllowance: number;
  /** ONE final recovery, shared by an account move and a validated rebuild. Not one each. */
  readonly finalRecoveryAllowance: number;
  readonly maxAlternateTargetSends: number;
  readonly maxTargetTransitions: number;
}

/**
 * Text Codex guarded profile. Three same-account sends plus one alternate is the recovery
 * shape that live traffic depends on, so a flat ceiling of 3 would break a working path.
 */
export const CODEX_TEXT_GUARDED_BUDGET_POLICY: RequestExecutionBudgetPolicy = {
  maxTotalModelSends: 4,
  baseSendAllowance: 3,
  finalRecoveryAllowance: 1,
  maxAlternateTargetSends: 1,
  maxTargetTransitions: 1,
};

export const REQUEST_BUDGET_POLICY_VERSION = "guarded-v1";

export type BudgetDenial =
  | "total-exhausted"
  | "base-allowance-exhausted"
  | "final-recovery-spent"
  | "alternate-target-exhausted"
  | "target-transition-exhausted"
  | "spend-exhausted"
  | "not-replay-safe";

export interface DispatchIntent {
  /** Reserve independent spend at use(), after the retry credential has been selected. */
  readonly freshRetrySpend?: boolean;
  readonly sendClass: SendClass;
  /**
   * (provider route, endpoint, model lane, upstream credential identity). A quota domain is a
   * different thing and must not be folded in here.
   */
  readonly targetKey: string;
  /** Selected spend scopes can differ from the budget owner's default route and account. */
  readonly spendScopes?: Pick<SpendScopes, "identityId" | "poolId">;
  readonly spendEstimate?: { inputTokens: number; outputCeilingTokens: number };
  /** Require fresh spend admission for a Codex cache-miss resend. */
  readonly incrementalRecovery?: { readonly prepaidDelta?: SpendReservationProof; readonly inputEstimateTokens?: number };
  /**
   * False refuses the dispatch outright. A request whose execution state upstream is unknown
   * is not replayable just because budget remains (RFC 9110 9.2.2).
   */
  readonly replaySafe?: boolean;
  /**
   * True when the physical send is already reported through another counter -- the retry
   * helpers' `onSendsConsumed` hook. The send is still booked at reservation time, because an
   * advisory reservation cannot stop a concurrent leg; what changes is that the booking is
   * PENDING, and the first send the external reporter names settles it instead of adding a
   * second charge. Charging both is how a four-send cap silently becomes a two-send cap.
   */
  readonly countedExternally?: boolean;
  /**
   * True when the caller's request was rebuilt onto a different destination by an
   * authorized mid-flight change (e.g. Kiro's reset-triggered account rebuild).
   * The physical destination is still recorded, but the move is not a failover
   * decision: it must not consume the request's single target transition or
   * alternate-target allowance, which belong to the actual endpoint fallback.
   */
  readonly rebasedTarget?: boolean;
}

export interface SingleUseDispatchPermit {
  readonly sendClass: SendClass;
  /**
   * Confirm the dispatch this permit already paid for. The reservation is the charge, so this
   * charges nothing; it is how a leg proves it is the one that sent. A second call returns
   * false, which is what keeps a retry thunk from sending twice on one permit.
   */
  use(): boolean;
  /** Keep the selected start rebindable until its executor finishes. */
  execute?<T>(run: () => Promise<T>): Promise<T>;
  /**
   * Hand back a reservation that never dispatched -- a credential move that found no alternate,
   * a rebuild abandoned before the send. Idempotent, and a no-op once the permit was used or
   * once an external send reporter already settled it.
   */
  release(): void;
  /**
   * Take over an externally counted booking, because the layer holding this permit is the one
   * that physically sends.
   *
   * `countedExternally` promises that a retry helper will name this send through
   * `onSendsConsumed`. An adapter that owns its own dispatch ladder -- Kiro's reset loop,
   * Cursor's transport loop -- reserves per physical send instead, so no reporter ever arrives
   * and the pending booking would sit there until it silently swallowed an unrelated later
   * report. Confirming through this method settles the permit AND closes the booking, so the
   * send stays charged exactly once (#4709). Returns false once the permit is settled, which is
   * what keeps one permit from admitting two sends.
   */
  assumeCharge(): boolean;
}

export type DispatchDecision =
  | { allowed: true; permit: SingleUseDispatchPermit }
  | { allowed: false; reason: BudgetDenial };

/**
 * Notified when this request's physical-send count moves.
 *
 * `spent` is the only number here that counts SENDS rather than intentions: a reservation
 * increments it, a refund decrements it, and an externally reported send settles against a
 * booking that was already counted. Anything that books one entry per increment therefore
 * books exactly one entry per physical send -- which is what lets the durable spend ledger
 * have a production caller without every dispatch site in the tree remembering to call it.
 *
 * `charge` may refuse, and a refusal denies the dispatch. That is deliberate: the ledger is
 * the only bound here that survives a restart, so a limit it enforces has to be able to stop a
 * send rather than merely describe one.
 */
export interface RequestSendObserver {
  /** Atomically claim the root workflow count at physical admission, before inference I/O. */
  beforePhysicalSend?(auxiliary?: boolean): boolean;
  /** Record an already-sent legacy receipt without booking its durable spend twice. */
  recordWorkflowSend?(): void;
  /**
   * Book one physical send. False refuses the dispatch before the budget charges it.
   *
   * `alreadySent` marks a send that has already left, which the reporting transports below
   * do after the fact. Its answer is not a decision -- nothing can un-send it -- and the
   * observer must RECORD it rather than drop it. Dropping it is a fixpoint: the send that
   * would cross a ceiling never joins the total, the total stays just under, and the ceiling
   * never fires for any later request either.
   */
  charge(options?: { alreadySent?: boolean; deferDispatch?: boolean; workflowAlreadyCounted?: boolean; onReserved?: (proof: SpendReservationProof) => void; targetKey?: string; scopes?: Pick<SpendScopes, "identityId" | "poolId">; auxiliary?: boolean; estimate?: { inputTokens: number; outputCeilingTokens: number }; incrementalRecovery?: DispatchIntent["incrementalRecovery"] }): boolean;
  /** Confirm the exact reservation once its dispatch is known. */
  readonly enforced?: boolean;
  readonly policyStarted?: boolean;
  readonly spendAdmissionPolicy?: SpendAdmissionPolicy;
  /** Capture/query original ceilings for a selected target without starting accounting. */
  hasCapturedSpendCeiling?(target?: SpendScopes): boolean;
  /** Capture request policy at its first admission or actual physical start. */
  startRequest?(target?: SpendScopes & { targetKey?: string }): void;
  ensureSeed?(target: SpendScopes & { targetKey?: string; auxiliary?: boolean; estimate?: { inputTokens: number; outputCeilingTokens: number }; explicitEstimate?: boolean; freshRetry?: boolean }, proof?: SpendReservationProof): SpendSeed | undefined;
  /** Release only this tracker's unstarted seed when physical admission refuses it. */
  releaseSeed?(seed: SpendSeed): void;
  beginReporter?(): {
    start(seed: SpendSeed, ordinal: number): void;
    rebindTarget(target: SpendScopes & { targetKey?: string }, ordinal: number): boolean;
    recordUsage?(ordinal: number, usage: Partial<SpendUsage> | null): void;
    report(sends: number): void;
    close(): void;
  };
  dispatch?(proof: SpendReservationProof): void;
  /** Give back a booking whose send never happened. */
  refund(proof?: SpendReservationProof | null): void;
}

/**
 * Carried on HandleResponsesOptions so a combo child, a rebuild and an alternate-account leg
 * all decrement the same holder. `used` is the existing #4605 counter and still counts every
 * model send; the reserve is what the fourth send draws on once the base allowance is gone.
 */
export interface RequestExecutionBudget extends TransientSendBudget {
  readonly explicitSendCeiling?: number;
  readonly physicalStarted?: number;
  readonly physicalLimit?: number;
  readonly spendEnforced?: boolean;
  /** True when physical admission owns this budget's root workflow accounting. */
  readonly workflowCountObserved?: boolean;
  readonly spendPolicyStarted?: boolean;
  readonly spendAdmissionPolicy?: SpendAdmissionPolicy;
  /** Optional hosted work checks the original ceilings even before an account was selected. */
  hasCapturedSpendCeiling?(target?: SpendScopes): boolean;
  startRequest?(target?: SpendScopes & { targetKey?: string }): void;
  claimPhysicalSend?(auxiliary?: boolean): number | undefined;
  /** A validated explicit successor still pays root/spend admission, not the recovery allowance. */
  claimContinuationPhysicalSend?(): number | undefined;
  /** Claim one root workflow send at physical admission; false refuses the send. */
  claimWorkflowSend?(auxiliary?: boolean): boolean;
  beginSpendProducer?(): { close(): void } | undefined;
  readonly logicalRequestId: string;
  readonly policyVersion: string;
  readonly policy: RequestExecutionBudgetPolicy;
  reserveDispatch(intent: DispatchIntent): DispatchDecision;
  /**
   * Sends still available from the base allowance, capped by a layer's own maximum.
   * Returns 0 when the allowance is gone -- it never floors to 1, because a floor of 1 is
   * what let every recovery leg send one more time forever.
   *
   * A reserved-but-unconfirmed send is spent for this purpose. The alternative -- counting only
   * confirmed sends -- is what let two legs read the same remainder and both dispatch.
   */
  remainingBaseSends(cap: number): number;
  readonly reserveSpent: boolean;
  readonly alternateTargetSends: number;
  readonly targetTransitions: number;
  readonly lastTargetKey: string | undefined;
  /** Seed a fresh derived scope with the actual endpoint of its already-paid initial send. */
  bindPrepaidTarget?(targetKey: string): void;
  /**
   * 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;
  /** True once any scope has claimed a replacement for this logical request. */
  readonly ambiguousResendSpent?: boolean;
}

const RESERVE_FUNDED_CLASSES: ReadonlySet<SendClass> = new Set<SendClass>([
  "account-failover",
  "combo-failover",
  "repair",
  "auth-recovery",
]);

let logicalRequestSeq = 0;

/**
 * One request's physical-send ledger, held apart from the budget object so a derived policy
 * scope can share the exact same one.
 *
 * `spent` and `pendingExternalSends` belong together: a pending booking is a send that is
 * already counted in `spent` and awaiting its reporter, so a scope that shared one without the
 * other would either charge that send twice or never charge it at all.
 *
 * The durable-spend observer belongs here for the same reason. It books one entry per physical
 * send by watching this counter move, so a derived scope that spent the counter without
 * carrying the observer would move it without booking, and a combo child's sends would go
 * missing from the ledger (#4707).
 */
interface SharedSendLedger {
  spent: number;
  physicalStarted: number;
  explicitPhysicalStarted: number;
  physicalLimit?: number;
  explicitSendCeiling?: number;
  /** Foreign legacy views retain one bounded recovery owner across derived bridges. */
  recoveryOwner?: RequestExecutionBudget;
  pendingExternalSends: Set<object>;
  /**
   * 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 ambiguousResendSpent: boolean;
  readonly observer?: RequestSendObserver;
}

const sharedSendLedgers = new WeakMap<RequestExecutionBudget, SharedSendLedger>();
// Only optional-work queries capture this fallback. Factory scopes key it by their shared
// ledger; legacy/foreign holders key it by their public owner. No accounting observer is added.
const fallbackSpendPolicies = new WeakMap<object, SpendAdmissionPolicy>();
function fallbackHasCapturedSpendCeiling(owner: object, target: SpendScopes = {}, published?: SpendAdmissionPolicy): boolean {
  let policy = published ?? fallbackSpendPolicies.get(owner);
  if (!policy) {
    const current = sharedSpendPolicy();
    policy = Object.freeze({ root: Object.freeze({ ...current.root }), identity: Object.freeze({ ...current.identity }), pool: Object.freeze({ ...current.pool }) });
    fallbackSpendPolicies.set(owner, policy);
  }
  return (Boolean(target.rootId) && policy.root.maxTokens !== undefined)
    || (Boolean(target.identityId) && policy.identity.maxTokens !== undefined)
    || (Boolean(target.poolId) && policy.pool.maxTokens !== undefined);
}

/** An authoritative query's false is final; only absent query authority uses the fallback. */
export function requestHasCapturedSpendCeiling(budget: TransientSendBudget, target?: SpendScopes): boolean {
  const execution = budget as Partial<RequestExecutionBudget>;
  if (execution.hasCapturedSpendCeiling) return execution.hasCapturedSpendCeiling(target);
  if (execution.spendEnforced === true) return true;
  return fallbackHasCapturedSpendCeiling(budget, target, execution.spendAdmissionPolicy);
}

interface SameTargetRecoveryScope {
  targetKey: string;
  maxAdditionalSends: number;
  physicalLimit: number;
  reservationPrefix: string;
  reservationSequence: number;
}
export interface BoundedSameTargetRecovery {
  readonly workflowCountObserved: boolean;
  /** Reserve an additional same-target send within the fixed, shared recovery grant. */
  reserve(): DispatchDecision;
}
const sameTargetRecoveries = new WeakMap<object, { targetKey: string; recovery: BoundedSameTargetRecovery }>();
/** Whether physical admission owns this budget's workflow accounting. */
export function hasWorkflowSendObserver(budget: TransientSendBudget): boolean {
  return (budget as RequestExecutionBudget).workflowCountObserved === true;
}
const dispatchSpendProofs = new WeakMap<SingleUseDispatchPermit, {
  owner: SharedSendLedger;
  claim(): SpendReservationProof | undefined;
  dispatched(): SpendReservationProof | undefined;
  report(): boolean;
  pending(): boolean;
}>();

/** One preflight for the exact prepaid dispatch, never another budget or a replayed permit. */
export function claimDispatchSpendProof(budget: RequestExecutionBudget, permit?: SingleUseDispatchPermit): SpendReservationProof | undefined {
  const proof = permit && dispatchSpendProofs.get(permit);
  return proof && proof.owner === sharedSendLedgers.get(budget) ? proof.claim() : undefined;
}

/**
 * Reports actual sends against only the named permit on this shared ledger.
 * `workflowAlreadyCounted` marks starts already charged at physical admission:
 * non-enforced observers then record request-ledger spend without charging the root again.
 * Enforced sends remain reconciled through their producer's claimed starts.
 */
export function reportDispatchSends(
  budget: TransientSendBudget,
  sends: number,
  permit?: SingleUseDispatchPermit,
  workflowAlreadyCounted = false,
): void {
  const count = Number.isFinite(sends) ? Math.max(0, Math.trunc(sends)) : 0;
  if (count === 0) return;
  const receipt = permit && dispatchSpendProofs.get(permit);
  const prepaid = receipt && receipt.owner === sharedSendLedgers.get(budget as RequestExecutionBudget)
    && receipt.report() ? 1 : 0;
  // Unnamed, foreign, released or already-reported permits cannot consume another receipt.
  const counter = sharedSendLedgers.get(budget as RequestExecutionBudget);
  if (!workflowAlreadyCounted && prepaid > 0) counter?.observer?.recordWorkflowSend?.();
  if (workflowAlreadyCounted && counter && counter.observer?.enforced !== true) {
    counter.spent += count - prepaid;
    for (let index = prepaid; index < count; index++) counter.observer?.charge({ alreadySent: true, workflowAlreadyCounted: true });
  } else budget.used += count - prepaid;
}

type RecordPhysicalSendUsage = (usage: Partial<SpendUsage> | null) => void;
/** A helper owns its starts and can never consume another helper's receipts. */
export type PhysicalSendReporter = ((sends: number) => void) & {
  remaining?: () => number;
  beforeSend?: (reserveRetrySpend?: boolean) => boolean;
  close?: () => void;
  execute?: <T>(run: () => Promise<T>, recoveryAdmission?: RetryRecoveryAdmission) => Promise<T>;
  bind?: (target: SpendScopes & { targetKey?: string }) => boolean;
  /** Null gives this send exclusive ownership of its usage, even if none arrives. */
  recordUsage?: RecordPhysicalSendUsage;
  captureUsageRecorder?: () => RecordPhysicalSendUsage | undefined;
  recover?: (send: Parameters<PhysicalSendRecovery>[0], admission: RetryRecoveryAdmission, inputEstimateTokens?: number) => Promise<boolean>;
};
export type PhysicalSendRecovery = (send: (dispatch: () => void) => Promise<void>, inputEstimateTokens?: number) => Promise<boolean>;
const activePhysicalReporters = new AsyncLocalStorage<{
  reporter: PhysicalSendReporter;
  recoveryAdmission?: RetryRecoveryAdmission;
}>();
export function recordCurrentPhysicalSendUsage(usage: Partial<SpendUsage> | null): void {
  activePhysicalReporters.getStore()?.reporter.recordUsage?.(usage);
}
/** Retain the receipt of this exact dispatch across a later recovery decision. */
export function captureCurrentPhysicalSendUsage(): RecordPhysicalSendUsage | undefined {
  return activePhysicalReporters.getStore()?.reporter.captureUsageRecorder?.();
}
/** Capture before entering a socket callback; missing ownership never authorizes another send. */
export function capturePhysicalSendRecovery(): PhysicalSendRecovery | undefined {
  const active = activePhysicalReporters.getStore();
  const recover = active?.reporter.recover;
  const admission = active?.recoveryAdmission;
  if (recover && admission) return (send, inputEstimateTokens) => recover(send, admission, inputEstimateTokens);
}
/** Selection owners rebind this helper's current start before invoking the executor. */
export function rebindPhysicalSend(budget: TransientSendBudget | undefined, target: SpendScopes & { targetKey?: string }): boolean {
  if (!(budget as RequestExecutionBudget | undefined)?.spendEnforced) return true;
  return activePhysicalReporters.getStore()?.reporter.bind?.(target) ?? true;
}
/**
 * Bind observations to this helper's starts and matching permit receipt.
 * `beforeSend` refuses disallowed starts. Producer-backed reports are capped to
 * unreported starts; excess legacy reports remain charged as observed sends.
 */
export function createPhysicalSendReporter(
  budget: TransientSendBudget,
  target: () => SpendScopes & { targetKey?: string; estimate?: { inputTokens: number; outputCeilingTokens: number }; explicitEstimate?: boolean },
  permit?: SingleUseDispatchPermit,
  telemetry?: (sends: number) => void,
  options: { explicitContinuation?: boolean; receiptOwned?: boolean } = {},
): PhysicalSendReporter {
  const counter = sharedSendLedgers.get(budget as RequestExecutionBudget);
  const observer = counter?.observer;
  const cappedCaller = counter?.explicitSendCeiling === undefined ? undefined : counter.recoveryOwner;
  let producer: ReturnType<NonNullable<RequestSendObserver["beginReporter"]>> | undefined;
  let closed = false;
  let started = 0;
  let reported = 0;
  let currentOrdinal: number | undefined;
  let executions = 0;
  let outerReported = 0;
  let earlyReported = 0;
  const record = (sends: number) => {
    if (closed) return;
    if (!producer) {
      if (observer?.enforced === true) return;
      const count = Number.isFinite(sends) ? Math.max(0, Math.trunc(sends)) : 0;
      if (cappedCaller) { telemetry?.(count); return; } // The caller was charged at admission.
      const admitted = Math.min(count, started - reported);
      if (admitted > 0) reportDispatchSends(budget, admitted, permit, true);
      if (count > admitted) reportDispatchSends(budget, count - admitted, permit);
      reported += admitted;
      telemetry?.(count);
      return;
    }
    const count = Math.min(Math.max(0, Math.trunc(sends)), started - reported);
    try { producer.report(count); }
    finally {
      reported += count;
      const receipt = permit && dispatchSpendProofs.get(permit);
      const prepaid = count > 0 && receipt && receipt.owner === counter && receipt.report() ? 1 : 0;
      if (counter) counter.spent += count - prepaid;
      telemetry?.(count);
    }
  };
  const recordEarly = (sends: number): void => {
    record(sends);
    earlyReported += sends;
  };
  const report: PhysicalSendReporter = sends => {
    if (options.receiptOwned) return;
    outerReported += sends;
    const prepaid = Math.min(earlyReported, sends);
    earlyReported -= prepaid;
    record(sends - prepaid);
  };
  if (!options.receiptOwned && isRequestExecutionBudget(budget)) report.remaining = () => {
    if (closed) return 0;
    // The caller already admitted this helper's initial send. Preserve that grant;
    // only subsequent retries must reconcile the allowance spent inside the helper.
    if (executions === 0 && outerReported === 0) return Infinity;
    const pending = cappedCaller ? 0 : Math.max(0, executions - outerReported - earlyReported);
    const receipt = permit && dispatchSpendProofs.get(permit);
    const prepaid = receipt?.owner === counter && receipt?.pending() ? 1 : 0;
    // Deferred reports still consume allowance. Only this reporter's pending booking
    // authorizes its prepaid send; recovery and other owners have already charged theirs.
    return Math.max(0, Math.min(budget.policy.baseSendAllowance, budget.policy.maxTotalModelSends,
      budget.explicitSendCeiling ?? Infinity)
      - budget.used - pending + prepaid);
  };
  if (!options.receiptOwned && cappedCaller) report.beforeSend = () => {
    // An opaque caller cannot share a prepaid receipt. Ordinary sends must still fit the
    // caller's live allowance and be charged before a second leg can claim the same send.
    if (closed || permit || (budget as RequestExecutionBudget).remainingBaseSends(1) < 1) return false;
    const next = budget.used + 1;
    return Reflect.set(cappedCaller, "used", next) && cappedCaller.used === next;
  };
  else if (!options.receiptOwned && (observer?.startRequest || observer?.enforced === true)) report.beforeSend = reserveRetrySpend => {
    if (closed) return false;
    const selected = target();
    if ((budget as RequestExecutionBudget).startRequest) (budget as RequestExecutionBudget).startRequest!(selected);
    else observer?.startRequest?.(selected);
    if (observer?.enforced !== true) {
      if (observer?.beforePhysicalSend?.() === false) return false;
      started++;
      return true;
    }
    producer ??= observer.beginReporter?.();
    // A recovery leg may have reused an earlier anchor for its first send. Book that send
    // before a funded retry checks how many tokens remain.
    if (reserveRetrySpend) recordEarly(started - reported);
    const receipt = permit && dispatchSpendProofs.get(permit);
    const proof = !reserveRetrySpend && receipt?.owner === counter ? receipt?.claim() : undefined;
    const seed = observer.ensureSeed?.(reserveRetrySpend ? { ...selected, freshRetry: true } : selected, proof);
    if (!seed) return false;
    const ordinal = options.explicitContinuation
      ? (budget as RequestExecutionBudget).claimContinuationPhysicalSend?.()
      : (budget as RequestExecutionBudget).claimPhysicalSend?.();
    if (ordinal === undefined) { observer.releaseSeed?.(seed); return false; }
    producer?.start(seed, ordinal);
    currentOrdinal = ordinal;
    started++;
    return true;
  };
  report.execute = (run, recoveryAdmission) => {
    // Receipt-owned sends are settled at dispatch. Only the nested recovery uses this scope.
    executions++;
    return activePhysicalReporters.run({ reporter: report, recoveryAdmission }, run);
  };
  report.recover = async (send, admission, inputEstimateTokens) => {
    if (closed || !admission.canSend() || !isRequestExecutionBudget(budget)) return false;
    // Retry helpers report on return. Settle their in-flight send before asking for another,
    // then subtract that early report when the helper eventually reports its own sends.
    const pending = options.receiptOwned ? 0 : Math.max(0, executions - outerReported - earlyReported);
    recordEarly(pending);
    const selected = target();
    // Only the first execution can consume this exact Combo booking. Later attempts
    // get their own booking through the dispatch callback, outside this reporter.
    const receipt = options.receiptOwned && executions === 1 && permit ? dispatchSpendProofs.get(permit) : undefined;
    const decision = budget.reserveDispatch({
      sendClass: "transient",
      targetKey: budget.lastTargetKey ?? selected.targetKey ?? JSON.stringify(selected),
      spendScopes: { poolId: selected.poolId, identityId: selected.identityId ?? "" },
      incrementalRecovery: {
        prepaidDelta: receipt && receipt.owner === counter ? receipt.dispatched() : undefined,
        inputEstimateTokens,
      },
    });
    if (!decision.allowed) return false;
    const recovery = decision.permit;
    const run = () => send(() => {
      if (!admission.claim(() => recovery.use())) throw new SendBudgetExhaustedError();
      telemetry?.(1);
    });
    try {
      await (recovery.execute ? recovery.execute(run) : run());
      return true;
    } catch (error) {
      if (error instanceof SendBudgetExhaustedError) return false;
      throw error;
    } finally { recovery.release(); }
  };
  report.bind = (selected: SpendScopes & { targetKey?: string }) => {
    if (!producer || currentOrdinal === undefined || observer?.enforced !== true) return true;
    return producer.rebindTarget(selected, currentOrdinal);
  };
  report.recordUsage = (usage) => {
    if (currentOrdinal !== undefined) producer?.recordUsage?.(currentOrdinal, usage);
  };
  report.captureUsageRecorder = () => {
    const ordinal = currentOrdinal;
    const owner = producer;
    if (ordinal !== undefined && owner) return usage => owner.recordUsage?.(ordinal, usage);
  };
  report.close = () => {
    if (closed) return;
    try { if (producer) record(started - reported); }
    finally { closed = true; producer?.close(); }
  };
  return report;
}

/**
 * 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(): Pick<SharedSendLedger, "claimAmbiguousResend" | "ambiguousResendSpent"> {
  let claimed = 0;
  let ceiling: number | undefined;
  return {
    get ambiguousResendSpent(): boolean { return claimed > 0; },
    claimAmbiguousResend(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;
    },
  };
}

/** Keep target-local transition state over the shared ledger and its single-use bookings. */
function createRequestExecutionBudgetWithLedger(
  policy: RequestExecutionBudgetPolicy,
  logicalRequestId: string | undefined,
  counter: SharedSendLedger,
  recovery?: SameTargetRecoveryScope,
): RequestExecutionBudget {
  const observer = counter.observer;
  let reserveSpent = false;
  let alternateTargetSends = 0;
  let targetTransitions = 0;
  let recoverySends = 0;
  let lastTargetKey: string | undefined = recovery?.targetKey;
  const targetReservations: Array<{ targetKey: string }> = [];
  const clampSendCeiling = (limit: number): number => Math.min(limit, counter.explicitSendCeiling ?? Infinity);
  const cappedCaller = () => counter.explicitSendCeiling === undefined ? undefined : counter.recoveryOwner;

  const budget: RequestExecutionBudget = {
    get explicitSendCeiling() { return counter.explicitSendCeiling; },
    get physicalStarted(): number { return counter.physicalStarted; },
    get physicalLimit(): number | undefined {
      const limit = recovery?.physicalLimit ?? counter.physicalLimit;
      return limit === undefined ? undefined : clampSendCeiling(limit) + counter.explicitPhysicalStarted;
    },
    get spendEnforced(): boolean { return observer?.enforced === true; },
    get workflowCountObserved(): boolean { return observer?.beforePhysicalSend !== undefined; },
    get spendPolicyStarted(): boolean { return observer?.policyStarted === true; },
    get spendAdmissionPolicy(): SpendAdmissionPolicy | undefined { return observer?.spendAdmissionPolicy; },
    hasCapturedSpendCeiling(target) {
      if (observer?.hasCapturedSpendCeiling) return observer.hasCapturedSpendCeiling(target);
      if (observer?.enforced === true) return true;
      return counter.recoveryOwner
        ? requestHasCapturedSpendCeiling(counter.recoveryOwner, target)
        : fallbackHasCapturedSpendCeiling(counter, target, observer?.spendAdmissionPolicy);
    },
    startRequest(target) {
      observer?.startRequest?.(target);
      if (observer?.enforced && counter.physicalLimit === undefined) {
        counter.physicalLimit = Number.isSafeInteger(policy.maxTotalModelSends) && policy.maxTotalModelSends > 0 ? policy.maxTotalModelSends : 0;
      }
    },
    beginSpendProducer() { return observer?.enforced ? observer.beginReporter?.() : undefined; },
    claimWorkflowSend(auxiliary = false): boolean {
      budget.startRequest?.();
      return (auxiliary ? observer?.beforePhysicalSend?.(true) : observer?.beforePhysicalSend?.()) ?? true;
    },
    claimPhysicalSend(auxiliary = false): number | undefined {
      budget.startRequest?.();
      const limit = recovery?.physicalLimit ?? counter.physicalLimit;
      if (observer?.enforced !== true || limit === undefined) return undefined;
      if (counter.physicalStarted - counter.explicitPhysicalStarted >= clampSendCeiling(limit)
        || !(auxiliary ? budget.claimWorkflowSend!(true) : budget.claimWorkflowSend!())) return undefined;
      return ++counter.physicalStarted;
    },
    claimContinuationPhysicalSend(): number | undefined {
      budget.startRequest?.();
      if (recovery || observer?.enforced !== true || !budget.claimWorkflowSend!()) return undefined;
      counter.explicitPhysicalStarted++;
      return ++counter.physicalStarted;
    },
    get used(): number { return counter.spent; },
    set used(next: number) {
      // A numeric report has no receipt identity. Only reportDispatchSends may settle a
      // prepaid permit; guessing by reservation order can refund another leg's actual send.
      // Enforced sends can only be reconciled through their producer's claimed starts.
      if (observer?.enforced === true) return;
      const charged = next - counter.spent;
      counter.spent = Math.max(0, next);
      // These sends have already left. The ledger records them even past a ceiling it would
      // have refused, because refusing after the fact only hides spend that was really
      // incurred -- the refusal has to happen at the reservation below, or not at all.
      for (let index = 0; index < charged; index += 1) observer?.charge({ alreadySent: true });
    },
    logicalRequestId: logicalRequestId ?? `lr-${Date.now().toString(36)}-${(logicalRequestSeq += 1).toString(36)}`,
    policyVersion: REQUEST_BUDGET_POLICY_VERSION,
    policy,
    get reserveSpent() { return reserveSpent; },
    get alternateTargetSends() { return alternateTargetSends; },
    get targetTransitions() { return targetTransitions; },
    get lastTargetKey() { return lastTargetKey; },
    /** Seed only a fresh scope; never reset recovery history on an existing target. */
    bindPrepaidTarget(targetKey: string): void {
      // Only a fresh scope may bind: this is initial identity, never a recovery rebase.
      if (lastTargetKey === undefined) lastTargetKey = targetKey;
    },
    remainingBaseSends(cap: number): number {
      const capped = Number.isFinite(cap) ? Math.trunc(cap) : 0;
      const remaining = Math.max(0, Math.min(capped, clampSendCeiling(policy.baseSendAllowance) - counter.spent));
      const caller = cappedCaller();
      if (!caller || remaining === 0) return remaining;
      const admitted = caller.remainingBaseSends(remaining);
      return Number.isSafeInteger(admitted) ? Math.max(0, Math.min(remaining, admitted)) : 0;
    },
    claimAmbiguousResend(limit: number): boolean {
      return counter.claimAmbiguousResend(limit);
    },
    get ambiguousResendSpent(): boolean { return counter.ambiguousResendSpent; },
    reserveDispatch(intent: DispatchIntent): DispatchDecision {
      if (recovery && (intent.targetKey !== recovery.targetKey || intent.sendClass !== "transient")) {
        return { allowed: false, reason: "target-transition-exhausted" };
      }
      if (recovery && recoverySends >= recovery.maxAdditionalSends) return { allowed: false, reason: "total-exhausted" };
      if (intent.replaySafe === false) return { allowed: false, reason: "not-replay-safe" };
      if (counter.spent >= clampSendCeiling(policy.maxTotalModelSends)) return { allowed: false, reason: "total-exhausted" };

      const auxiliary = intent.sendClass === "auxiliary";
      const countedExternally = !auxiliary && intent.countedExternally === true;
      const changesTarget = !auxiliary && lastTargetKey !== undefined && lastTargetKey !== intent.targetKey;
      const isAlternateTarget = changesTarget || intent.sendClass === "account-failover"
        || intent.sendClass === "combo-failover";
      const chargesTransition = changesTarget && intent.rebasedTarget !== true;
      const chargesAlternateTarget = isAlternateTarget && intent.rebasedTarget !== true;
      if (isAlternateTarget && chargesTransition && targetTransitions >= policy.maxTargetTransitions) {
        return { allowed: false, reason: "target-transition-exhausted" };
      }
      if (chargesAlternateTarget && alternateTargetSends >= policy.maxAlternateTargetSends) {
        return { allowed: false, reason: "alternate-target-exhausted" };
      }

      // The base allowance is spent first. Only once it is gone does a recovery class reach
      // for the single shared reserve -- an account move and a validated rebuild cannot each
      // take one.
      const drawsReserve = policy.baseSendAllowance - counter.spent <= 0;
      if (drawsReserve) {
        if (!RESERVE_FUNDED_CLASSES.has(intent.sendClass)) {
          return { allowed: false, reason: "base-allowance-exhausted" };
        }
        if (reserveSpent || policy.finalRecoveryAllowance <= 0) {
          return { allowed: false, reason: "final-recovery-spent" };
        }
      }

      const caller = cappedCaller();
      if (caller) {
        // Private receipts and target ledgers cannot be intersected across a derived policy.
        if (intent.countedExternally || policy !== caller.policy || recovery) {
          return { allowed: false, reason: "total-exhausted" };
        }
        const expectedUsed = counter.spent + 1;
        const decision = caller.reserveDispatch(intent);
        if (!decision.allowed || counter.spent === expectedUsed) return decision;
        decision.permit.release();
        return { allowed: false, reason: "total-exhausted" };
      }

      // Consulted last, because it is the only bound here that WRITES. A ledger entry booked
      // for a dispatch a cheaper check above would have refused is spend this request never
      // makes, and it would hold those tokens against the scope until retention expired.
      // Extra same-target recovery is outside the request's original physical allowance.
      // Each rung therefore needs fresh normal-capacity spend admission; it cannot reuse
      // an earlier seed to turn a request-total exception into a token-ceiling exception.
      const spendTargetKey = recovery
        ? `${recovery.reservationPrefix}:${++recovery.reservationSequence}`
        : intent.incrementalRecovery ? `fresh-spend:${++logicalRequestSeq}` : intent.targetKey;
      const spendTarget = { ...intent.spendScopes, targetKey: spendTargetKey,
        ...(auxiliary ? { estimate: intent.spendEstimate, auxiliary: true } : {}) };
      budget.startRequest?.(spendTarget);
      const freshRetry = intent.freshRetrySpend === true && !countedExternally && observer?.enforced === true;
      // Adapter-owned sends following configured native compact can reserve before pacing.
      // Pool moves instead opt into fresh admission at use(), once the alternate is known.
      const prepayRetry = !intent.incrementalRecovery && !freshRetry && !countedExternally && !auxiliary
        && observer?.enforced === true
        && counter.explicitSendCeiling !== undefined && counter.spent > 0;
      const retrySeed = prepayRetry ? observer.ensureSeed?.({ ...spendTarget, freshRetry: true }) : undefined;
      if (prepayRetry && !retrySeed) return { allowed: false, reason: "spend-exhausted" };
      let spendProof: SpendReservationProof | undefined;
      if (observer && !freshRetry && !retrySeed && !observer.charge({ targetKey: spendTargetKey, scopes: intent.spendScopes,
        ...(auxiliary ? { estimate: intent.spendEstimate, auxiliary: true } : {}),
        ...(intent.incrementalRecovery ? { incrementalRecovery: intent.incrementalRecovery } : {}),
        deferDispatch: true, onReserved: proof => { spendProof = proof; } })) {
        return { allowed: false, reason: "spend-exhausted" };
      }

      // THE RESERVATION IS THE CHARGE. Deciding here and charging in `use()` left a window in
      // which two legs read the same remainder, both received a permit, and both dispatched:
      // one remaining send admitted two physical sends, which is the per-request multiplication
      // this budget exists to stop. Everything is booked now; `release()` is the way back.
      counter.spent += 1;
      if (recovery) recoverySends += 1;
      const receipt = { targetKey: intent.targetKey };
      if (!auxiliary) targetReservations.push(receipt);
      if (countedExternally) counter.pendingExternalSends.add(receipt);
      if (drawsReserve) reserveSpent = true;
      if (chargesAlternateTarget) alternateTargetSends += 1;
      if (chargesTransition) targetTransitions += 1;
      if (!auxiliary) lastTargetKey = intent.targetKey;

      let producer: ReturnType<NonNullable<RequestSendObserver["beginReporter"]>> | undefined;
      let executing = false;
      let physicalOrdinal: number | undefined;
      let selectedTarget: SpendScopes & { targetKey?: string } | undefined;
      const startPhysical = (): boolean => {
        if (observer?.enforced !== true) return auxiliary ? budget.claimWorkflowSend!(true) : budget.claimWorkflowSend!();
        const selected = { ...spendTarget, ...selectedTarget, targetKey: selectedTarget?.targetKey ?? spendTargetKey };
        // A prepaid retry seed predates credential selection; rebook it on the selected target.
        if (retrySeed && selectedTarget) observer.releaseSeed?.(retrySeed);
        const seed = retrySeed && !selectedTarget ? retrySeed
          : observer.ensureSeed?.(freshRetry || retrySeed ? { ...selected, freshRetry: true } : selected, spendProof);
        if (!seed) return false;
        const ordinal = auxiliary ? budget.claimPhysicalSend?.(true) : budget.claimPhysicalSend?.();
        if (ordinal === undefined) { observer.releaseSeed?.(seed); return false; }
        producer = observer.beginReporter?.();
        producer?.start(seed, ordinal);
        physicalOrdinal = ordinal;
        if (!executing) { try { producer?.report(1); } finally { producer?.close(); } }
        return true;
      };
      let settled: "open" | "used" | "released" = "open";
      const permit: SingleUseDispatchPermit = {
        sendClass: intent.sendClass,
        async execute<T>(run: () => Promise<T>): Promise<T> {
          if (executing) throw new Error("Dispatch permit executor already active");
          executing = true;
          const binding: PhysicalSendReporter = () => {};
          binding.bind = (target: SpendScopes & { targetKey?: string }) => {
            if (physicalOrdinal !== undefined && producer) return producer.rebindTarget(target, physicalOrdinal);
            selectedTarget = target;
            return true;
          };
          try { return await activePhysicalReporters.run({ reporter: binding }, run); }
          finally {
            executing = false;
            try { producer?.report(1); } finally { producer?.close(); }
          }
        },
        use(): boolean {
          if (settled !== "open") return false;
          if (!countedExternally && !startPhysical()) return false;
          settled = "used";
          if (!countedExternally && spendProof) observer?.dispatch?.(spendProof);
          return true;
        },
        assumeCharge(): boolean {
          if (settled !== "open" || (countedExternally && !counter.pendingExternalSends.has(receipt))) return false;
          if (!startPhysical()) return false;
          settled = "used";
          // The booking this reservation made for an external reporter is now owned by the
          // caller. Close only its own receipt so a later reporter cannot spend it again.
          if (countedExternally) counter.pendingExternalSends.delete(receipt);
          if (spendProof) observer?.dispatch?.(spendProof);
          return true;
        },
        release(): void {
          if (settled !== "open") return;
          settled = "released";
          // An externally counted reservation the reporter already settled paid for a send
          // that physically happened. Refunding it would hand the request a free send back.
          if (countedExternally) {
            if (!counter.pendingExternalSends.delete(receipt)) return;
          }
          counter.spent -= 1;
          if (recovery) recoverySends -= 1;
          if (retrySeed) observer?.releaseSeed?.(retrySeed);
          else observer?.refund(spendProof ?? null);
          if (drawsReserve) reserveSpent = false;
          if (chargesAlternateTarget) alternateTargetSends -= 1;
          if (chargesTransition) targetTransitions -= 1;
          if (!auxiliary) {
            targetReservations.splice(targetReservations.indexOf(receipt), 1);
            lastTargetKey = targetReservations.at(-1)?.targetKey;
          }
        },
      };
      let preflightClaimed = false;
      dispatchSpendProofs.set(permit, { owner: counter, pending: () => counter.pendingExternalSends.has(receipt), report: () => {
        if (!counter.pendingExternalSends.has(receipt)) return false;
        if (spendProof) observer?.dispatch?.(spendProof);
        counter.pendingExternalSends.delete(receipt);
        // Reset-only helpers report just BEFORE calling the dispatch thunk. Its one use()
        // remains available, but release/proof cannot refund or reuse this reported receipt.
        return true;
      }, dispatched: () => settled === "used" ? spendProof : undefined, claim: () => {
        if (preflightClaimed || settled === "released"
          || (countedExternally ? !counter.pendingExternalSends.has(receipt) : settled !== "open")) return undefined;
        preflightClaimed = true;
        return spendProof;
      } });
      return { allowed: true, permit };
    },
  };
  sharedSendLedgers.set(budget, counter);
  return budget;
}

export function createRequestExecutionBudget(
  policy: RequestExecutionBudgetPolicy = CODEX_TEXT_GUARDED_BUDGET_POLICY,
  logicalRequestId?: string,
  observer?: RequestSendObserver,
): RequestExecutionBudget {
  const grant = createAmbiguousResendGrant();
  return createRequestExecutionBudgetWithLedger(policy, logicalRequestId, {
    spent: 0,
    physicalStarted: 0,
    explicitPhysicalStarted: 0,
    pendingExternalSends: new Set(),
    claimAmbiguousResend: grant.claimAmbiguousResend,
    get ambiguousResendSpent(): boolean { return grant.ambiguousResendSpent; },
    ...(observer ? { observer } : {}),
  });
}

/**
 * A budget that applies its own policy and keeps its own recovery ledgers while spending the
 * parent's exact physical-send ledger.
 *
 * Aliasing the public `used` property was not enough, and that is the whole defect. The factory
 * reads its own private counter back in `remainingBaseSends`, in the total check, and in the
 * reserve test, so an aliased scope answered every admission question from a counter that only
 * ever saw its own reservations. A combo's per-target holdback is computed from
 * `maxTotalModelSends` and is therefore unenforceable unless the scope actually observes what
 * the request has already spent.
 */
export function deriveRequestExecutionBudget(
  parent: RequestExecutionBudget,
  policy: RequestExecutionBudgetPolicy,
): RequestExecutionBudget {
  return createRequestExecutionBudgetWithLedger(policy, parent.logicalRequestId, ledgerFor(parent));
}

/** Carry the explicit ceiling without replacing the caller's admission or private accounting. */
export function capRequestExecutionBudgetSends(parent: RequestExecutionBudget, ceiling: number): RequestExecutionBudget | undefined {
  const existing = sharedSendLedgers.get(parent);
  const caller = existing ? existing.recoveryOwner : parent;
  // An uncapped legacy scope has already forked its reservation state from the caller.
  if (caller && (caller.spendEnforced || hasWorkflowSendObserver(caller)
    || (existing && existing.explicitSendCeiling === undefined))) return undefined;
  const ledger = existing ?? ledgerFor(parent);
  ledger.explicitSendCeiling = Math.min(ceiling, parent.explicitSendCeiling ?? Infinity, ledger.explicitSendCeiling ?? Infinity);
  return existing ? parent : createRequestExecutionBudgetWithLedger(parent.policy, parent.logicalRequestId, ledger);
}

/**
 * A validated same-target recovery may own a bounded exception to the request send total.
 * It shares all spend/root accounting, but never raises the parent's ordinary allowances.
 * The first grant is fixed for this shared ledger; another target or caller cannot replenish it.
 */
export function createBoundedSameTargetRecovery(
  parent: RequestExecutionBudget,
  targetKey: string,
  maxAdditionalSends: number,
): BoundedSameTargetRecovery {
  const counter = sharedSendLedgers.get(parent);
  const owner = counter?.recoveryOwner ?? counter ?? parent;
  const existing = sameTargetRecoveries.get(owner);
  const refused = (reason: BudgetDenial): BoundedSameTargetRecovery => ({
    workflowCountObserved: false, reserve: () => ({ allowed: false, reason }),
  });
  if (existing) return existing.targetKey === targetKey ? existing.recovery : refused("target-transition-exhausted");
  // A foreign budget cannot transfer a private durable-spend observer to this exception,
  // including when it reaches this owner through a derived legacy bridge.
  const foreignParent = counter?.recoveryOwner ?? (!counter ? parent : undefined);
  if (foreignParent && (foreignParent.spendEnforced || hasWorkflowSendObserver(foreignParent))) return refused("spend-exhausted");
  if (!Number.isSafeInteger(maxAdditionalSends) || maxAdditionalSends <= 0
    || !Number.isSafeInteger(parent.used + maxAdditionalSends)) return refused("total-exhausted");
  // Freeze the ordinary limit through its original owner before constructing the exception.
  parent.startRequest?.();
  const shared = counter ?? ledgerFor(parent);
  const allowance = parent.used + maxAdditionalSends;
  const budget = createRequestExecutionBudgetWithLedger({
    maxTotalModelSends: allowance, baseSendAllowance: allowance, finalRecoveryAllowance: 0,
    maxAlternateTargetSends: 0, maxTargetTransitions: 0,
  }, parent.logicalRequestId, shared, {
    targetKey, maxAdditionalSends, physicalLimit: shared.physicalStarted - shared.explicitPhysicalStarted + maxAdditionalSends,
    reservationPrefix: `${targetKey}|same-target-recovery:${++logicalRequestSeq}`, reservationSequence: 0,
  });
  const recovery: BoundedSameTargetRecovery = {
    get workflowCountObserved() { return hasWorkflowSendObserver(budget); },
    reserve: () => budget.reserveDispatch({ sendClass: "transient", targetKey }),
  };
  sameTargetRecoveries.set(owner, { targetKey, recovery });
  return recovery;
}

/**
 * A budget that did not come from this factory still honors the public `used` contract, so
 * bridge onto it rather than failing the request. `isRequestExecutionBudget` is a shape test,
 * so a stub can reach here; turning that into a thrown error would convert a routing request
 * into a 500 to report a condition production never produces. Only a factory-backed parent can
 * share pending external bookings and a durable-spend observer, which are private by
 * construction; a bridged scope keeps the parent's spend accurate and books nothing of its own.
 */
/**
 * Grant claims made THROUGH a bridge, keyed by the bridged parent so every scope derived from it
 * sees them. A parent that predates `ambiguousResendSpent` can still grant through
 * `claimAmbiguousResend`; reading only its missing flag would report "not spent" after a derived
 * scope spent the grant, and a combo would then hop on a zero-output 200 from the replacement.
 */
const bridgedGrantClaims = new WeakMap<RequestExecutionBudget, { claimed: boolean }>();

function ledgerFor(parent: RequestExecutionBudget): SharedSendLedger {
  const existing = sharedSendLedgers.get(parent);
  if (existing) return existing;
  const pendingExternalSends = new Set<object>();
  let bridged = bridgedGrantClaims.get(parent);
  if (!bridged) {
    bridged = { claimed: false };
    bridgedGrantClaims.set(parent, bridged);
  }
  const claims = bridged;
  return {
    get spent(): number { return parent.used; },
    set spent(next: number) { parent.used = next; },
    recoveryOwner: parent,
    pendingExternalSends,
    physicalStarted: 0,
    explicitPhysicalStarted: 0,
    // 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 => {
      const granted = parent.claimAmbiguousResend?.(limit) === true;
      if (granted) claims.claimed = true;
      return granted;
    },
    get ambiguousResendSpent(): boolean { return claims.claimed || parent.ambiguousResendSpent === true; },
  };
}

export function isRequestExecutionBudget(
  value: TransientSendBudget | undefined,
): value is RequestExecutionBudget {
  return typeof (value as RequestExecutionBudget | undefined)?.reserveDispatch === "function";
}
