Rulvar API reference

---

Rulvar API reference / @rulvar/rulvar / OrchestratorBudgetSpec

Interface: OrchestratorBudgetSpec

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

Budget contract: https://docs.rulvar.com/guide/budgets; the cap machinery (reserves, freeze) completes in M7 (DEF-7).

Properties

Property	Type	Description	Defined in
acceptanceReserve?	"warn" | "require" | "checkpoint"	The admission posture of the acceptance path (RV3907, the fourth comparison experiment). Preflight has long PRICED the tail and warned (reserve-line-headroom, orchestrator-working-room), and the experiment's run started anyway, with the warnings on record and the acceptance machinery funded by luck. 'warn' (default) keeps exactly that: findings in preflight, nothing at runtime. 'require' turns the arithmetic into a boot refusal BEFORE the first wire: the effective cap must cover, at exact fill or better, the DECLARED acceptance tail (the held synthesisReserveUsd, the claim judge's judge.estCost times one plus the armed semantic repair round, the declared finishValidation.estRepairCostUsd, and the armed round's declared synthesis.estCost composition floor) plus one coordination turn floor of working room. Undeclared estimates contribute zero, so the gate binds exactly what the host declared; the refusal journals an acceptance_reserve_refused decision naming every term and throws the typed OrchestratorCapConfigError with the same arithmetic. 'checkpoint' (RV4404, the seventh comparison experiment) is 'require' plus a runtime re-check of the SAME arithmetic before each paid acceptance-tail dispatch (the first composition, each judge pass): the worst case still ahead, at the money actually spent, must fit the effective cap, or the run refuses typed NOW, before paying the stage. The intake gate binds declared estimates; runtime actuals can exceed them (the seventh run's workers overshot their declared estimate 2.8x and the refusal came only where the armed round could not dispatch, after the composition and both judges were already paid). The checkpoint moves the refusal to the first moment the arithmetic is known lost; in the seventh run that is right after the workers, saving the composition and both judge passes. The refusal journals an acceptance_checkpoint_refused decision naming the stage and every term, and throws typed with the same fields.	packages/core/dist/index.d.ts
atCap?	"finish-with-partial" | "fail-run"	The policy at the cap, validated as exactly one of the two literals even at a plain JS/JSON boundary. 'finish-with-partial' (default) runs the reserved finalizer and settles run status 'ok' with the completion envelope { result, completion } as the value (RV906): completion is 'partial' unless the finalizer's finish provably passed the FULL declared contract (the declared finish validators bind the reserved finalizer; a declared acceptance policy is never judged at the cap, so with one declared the terminal stays 'partial'). The engine lifts the same literal onto run:end and the outcome mirror, so a consumer reading only status cannot execute a truncated plan as a full success. A finalizer that cannot produce an accepted finish falls back to the deterministic partial on the 'exhausted' outcome, itself carrying completion 'partial'. 'fail-run' skips the finalizer entirely: the run fails with outcome 'error' carrying FailRunError (code 'fail_run', data.source 'orchestrator_budget_cap', data.capDecisionRef); resume rolls the same failure forward from the journaled cap decision without another model call.	packages/core/dist/index.d.ts
capFraction?	number	A fraction in (0, 1], default 0.2; effectiveCap = min of the given bounds. Zero does not lift the cap (it would make every turn unpayable): anything outside (0, 1] is a ConfigError before any journal entry or dispatch.	packages/core/dist/index.d.ts
capUsd?	number	Absolute bound in USD: a finite number >= 0, validated before any journal entry or dispatch (a malformed value is a ConfigError). It never REPLACES the fraction bound: effectiveCap = min(capUsd, (capFraction ?? 0.2) * ceiling), so an explicit capUsd larger than the default fraction of the run ceiling is still cut to that fraction (and a warn log says so). Pass capFraction: 1.0 to make capUsd the sole bound.	packages/core/dist/index.d.ts
estIsCeiling?	boolean	Enforced stage ceilings (RV4404): with estIsCeiling: true, a spawned child's DECLARED estimate (its budgetUsd, else its profile's estCost) becomes the hard ceiling of its own allowance account, so a child that overshoots its declaration refuses individually and honestly at its own ceiling instead of silently eating the acceptance tail. The seventh comparison experiment's workers declared 0.25 USD each and spent 0.58..0.77; the intake gate had verified the tail against the declarations, so the run passed fits: true honestly and still could not pay its armed round. Under this mode plus 'checkpoint', a preflight fits: true becomes a dispatch guarantee for the declared tail: the fan-out cannot spend past its declarations, and the checkpoint refuses before any tail stage the remaining money cannot carry. Opt-in; spawns without any declared estimate keep the parent-account flow byte for byte.	packages/core/dist/index.d.ts
finalizeReserveUsd?	number	A finite number >= 0, validated before any journal entry or dispatch. The reserve is SUBTRACTED from the soft boundary, so a negative value would widen the cap instead of reserving.	packages/core/dist/index.d.ts
finalizeTurns?	number	A positive integer, validated before any journal entry or dispatch: the turn limit of the reserved final wake.	packages/core/dist/index.d.ts
synthesisReserveUsd?	number	The synthesis payload reserve (the sixth comparison experiment, cycle 76): absolute USD held out of the orchestrator sub account while the coordination loop runs, released to the synthesis invocation just before it dispatches. Without it a pricey coordination can leave the synthesis turns a remainder the budget clamp shrinks below the contract's minimal accepting payload: the finish is then cut at the output allowance before any tool call, the invocation dies at maxTurns, and a validator-bound run fails closed (the rematch run 1 lost an entire paid run exactly there). Requires the synthesis option (single mode); must stay below the effective cap. Declaring it changes budget arithmetic only; absent keeps every account byte identical.	packages/core/dist/index.d.ts