rulvar API reference / @rulvar/core / RunBudget
Class: RunBudget
Defined in: packages/core/src/engine/budget.ts:95
The per-run budget account tree. All spend accounting is per instance; the journal remains the durable source (the root is seeded by the ledger fold on resume, M2; sub-account reserves are recovered from spawn-admission decision entries, M6).
Constructors
Constructor
new RunBudget(options): RunBudget;Defined in: packages/core/src/engine/budget.ts:106
Parameters
| Parameter | Type | Description |
|---|---|---|
options | { ceilingUsd?: number; events?: RuntimeEventSink; lifetimeSpawnCap?: number; priceUsd?: (servedBy, usage) => number | undefined; seed?: { agentsSpawned: number; usage: Usage; usd: number; }; } | - |
options.ceilingUsd? | number | - |
options.events? | RuntimeEventSink | - |
options.lifetimeSpawnCap? | number | - |
options.priceUsd? | (servedBy, usage) => number | undefined | - |
options.seed? | { agentsSpawned: number; usage: Usage; usd: number; } | The resume ledger fold: spend is never reset and never double-counted; replayed entries are already inside this seed and add no increments. |
options.seed.agentsSpawned | number | - |
options.seed.usage | Usage | - |
options.seed.usd | number | - |
Returns
RunBudget
Properties
| Property | Modifier | Type | Description | Defined in |
|---|---|---|---|---|
ceilingUsd? | readonly | number | B0; immutable after start. Undefined means no USD ceiling. | packages/core/src/engine/budget.ts:97 |
Accessors
committedReserveUsd
Get Signature
get committedReserveUsd(): number;Defined in: packages/core/src/engine/budget.ts:268
Returns
number
exhausted
Get Signature
get exhausted(): boolean;Defined in: packages/core/src/engine/budget.ts:254
Returns
boolean
signal
Get Signature
get signal(): AbortSignal;Defined in: packages/core/src/engine/budget.ts:245
Layer 3 ceiling signal of the run root; live streams sever through it.
Returns
AbortSignal
spawnHeadroom
Get Signature
get spawnHeadroom(): number;Defined in: packages/core/src/engine/budget.ts:273
Spawn headroom under the engine lifetime cap (embedded in admission verdicts).
Returns
number
Methods
accountView()
accountView(scope):
| BudgetAccountView
| undefined;Defined in: packages/core/src/engine/budget.ts:205
Parameters
| Parameter | Type |
|---|---|
scope | string |
Returns
| BudgetAccountView | undefined
admitRecovered()
admitRecovered(reserveUsd, accountScope?): void;Defined in: packages/core/src/engine/budget.ts:331
Resume roll-forward: commits a reserve recovered from a journaled spawn-admission decision entry without re-evaluating admission (reserves are recovered, never re-estimated).
Parameters
| Parameter | Type | Default value |
|---|---|---|
reserveUsd | number | undefined |
accountScope | string | ROOT_ACCOUNT |
Returns
void
admitSpawn()
admitSpawn(reserveUsd, accountScope?): void;Defined in: packages/core/src/engine/budget.ts:283
Layer 1: admission before spawn. Blocks when spent + committedReserve has reached the ceiling on ANY account in the ancestor chain of accountScope, otherwise commits the reserve along the whole chain. Also enforces the engine lifetime spawn cap.
Parameters
| Parameter | Type | Default value |
|---|---|---|
reserveUsd | number | undefined |
accountScope | string | ROOT_ACCOUNT |
Returns
void
beforeTurn()
beforeTurn(accountScope?): void;Defined in: packages/core/src/engine/budget.ts:383
Layer 2: the per-turn guard. A turn that would cross any ceiling in the chain is not dispatched.
Parameters
| Parameter | Type | Default value |
|---|---|---|
accountScope | string | ROOT_ACCOUNT |
Returns
void
commitFinalizeReserve()
commitFinalizeReserve(scope, reserveUsd): void;Defined in: packages/core/src/engine/budget.ts:347
Registers the orchestrator finalize reserve (DEF-7): absolute dollars set on the named account AND the run root, so admission never lets any spawn eat the finalization money even against whole-run exhaustion. Kept SEPARATE from committedReserveUsd (the block checks add both), so remainders never double-count. Idempotent: re-registering on resume keeps the journaled amount.
Parameters
| Parameter | Type |
|---|---|
scope | string |
reserveUsd | number |
Returns
void
markExhausted()
markExhausted(): void;Defined in: packages/core/src/engine/budget.ts:263
Marks the run exhausted without a ceiling event: the orchestrator finalize fallback maps to outcome 'exhausted' with the synthesized partial value (DEF-7; exhaustion is never null).
Returns
void
onUsage()
onUsage(
usage,
servedBy,
accountScope?): void;Defined in: packages/core/src/engine/budget.ts:410
Live accounting; spend propagates from accountScope to every ancestor. Crossing a ceiling severs the crossing account's subtree via its layer-3 AbortSignal (overshoot bounded by one turn per in-flight agent; providers bill severed streams).
Parameters
| Parameter | Type | Default value |
|---|---|---|
usage | Usage | undefined |
servedBy | `${string}:${string}` | undefined |
accountScope | string | ROOT_ACCOUNT |
Returns
void
openAccount()
openAccount(scope, options): void;Defined in: packages/core/src/engine/budget.ts:177
Opens a child sub-account under parentScope. Re-opening an existing scope is the resume roll-forward path: the recorded ceiling wins once and the accumulated state is kept.
Parameters
| Parameter | Type |
|---|---|
scope | string |
options | { ceilingUsd?: number; finalizeReserveUsd?: number; parentScope?: string; } |
options.ceilingUsd? | number |
options.finalizeReserveUsd? | number |
options.parentScope? | string |
Returns
void
releaseFinalizeReserve()
releaseFinalizeReserve(scope): void;Defined in: packages/core/src/engine/budget.ts:365
The forced finish CONSUMES its reserve (DEF-7 reserve-survives-run-exhaustion): once the cap decision is durable and the finalize dispatch begins, the reserve stops subtracting from the admission remainder, or the finalize agent could never draw the money reserved for it under a tight run ceiling. Admissions stay frozen past the cap, so nothing else can take it.
Parameters
| Parameter | Type |
|---|---|
scope | string |
Returns
void
releaseReserve()
releaseReserve(reserveUsd, accountScope?): void;Defined in: packages/core/src/engine/budget.ts:375
The reserve is replaced by real spend when the spawn settles.
Parameters
| Parameter | Type | Default value |
|---|---|---|
reserveUsd | number | undefined |
accountScope | string | ROOT_ACCOUNT |
Returns
void
remainderOf()
remainderOf(scope): number | undefined;Defined in: packages/core/src/engine/budget.ts:230
The admission remainder of one account: ceiling minus spend minus committed reserves minus the finalize reserve (DEF-7: childBudget fractions never eat finalization money). Undefined when uncapped.
Parameters
| Parameter | Type |
|---|---|
scope | string |
Returns
number | undefined
remaining()
remaining(): Spend | null;Defined in: packages/core/src/engine/budget.ts:447
Null when the run has no USD ceiling.
Returns
Spend | null
signalOf()
signalOf(scope): AbortSignal | undefined;Defined in: packages/core/src/engine/budget.ts:250
The layer-3 signal of one sub-account's subtree, when it exists.
Parameters
| Parameter | Type |
|---|---|
scope | string |
Returns
AbortSignal | undefined
spent()
spent(): Spend;Defined in: packages/core/src/engine/budget.ts:438