rulvar API reference

---

rulvar API reference / @rulvar/rulvar / RunBudget

Class: RunBudget

Defined in: packages/core/dist/index.d.ts

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/dist/index.d.ts

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/dist/index.d.ts

Accessors

committedReserveUsd

Get Signature

get committedReserveUsd(): number;

Defined in: packages/core/dist/index.d.ts

Returns

number

---

exhausted

Get Signature

get exhausted(): boolean;

Defined in: packages/core/dist/index.d.ts

Returns

boolean

---

signal

Get Signature

get signal(): AbortSignal;

Defined in: packages/core/dist/index.d.ts

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/dist/index.d.ts

Spawn headroom under the engine lifetime cap (embedded in admission verdicts).

Returns

number

Methods

accountView()

accountView(scope): 
  | BudgetAccountView
  | undefined;

Defined in: packages/core/dist/index.d.ts

Parameters

Parameter	Type
scope	string

Returns

| BudgetAccountView | undefined

---

admitRecovered()

admitRecovered(reserveUsd, accountScope?): void;

Defined in: packages/core/dist/index.d.ts

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
reserveUsd	number
accountScope?	string

Returns

void

---

admitSpawn()

admitSpawn(reserveUsd, accountScope?): void;

Defined in: packages/core/dist/index.d.ts

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
reserveUsd	number
accountScope?	string

Returns

void

---

beforeTurn()

beforeTurn(accountScope?): void;

Defined in: packages/core/dist/index.d.ts

Layer 2: the per-turn guard. A turn that would cross any ceiling in the chain is not dispatched.

Parameters

Parameter	Type
accountScope?	string

Returns

void

---

commitFinalizeReserve()

commitFinalizeReserve(scope, reserveUsd): void;

Defined in: packages/core/dist/index.d.ts

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/dist/index.d.ts

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/dist/index.d.ts

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
usage	Usage
servedBy	`${string}:${string}`
accountScope?	string

Returns

void

---

openAccount()

openAccount(scope, options): void;

Defined in: packages/core/dist/index.d.ts

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/dist/index.d.ts

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/dist/index.d.ts

The reserve is replaced by real spend when the spawn settles.

Parameters

Parameter	Type
reserveUsd	number
accountScope?	string

Returns

void

---

remainderOf()

remainderOf(scope): number | undefined;

Defined in: packages/core/dist/index.d.ts

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/dist/index.d.ts

Null when the run has no USD ceiling.

Returns

Spend | null

---

signalOf()

signalOf(scope): AbortSignal | undefined;

Defined in: packages/core/dist/index.d.ts

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/dist/index.d.ts

Returns

Spend