@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
1,046 lines • 56 kB
text/typescript
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";
}