Rulvar API reference / @rulvar/rulvar / PreflightSpawnReport
Interface: PreflightSpawnReport
Defined in: packages/core/dist/index.d.ts
The effective picture of one declared spawn shape.
Properties
| Property | Type | Description | Defined in |
|---|---|---|---|
admissionReserveUsd | number | The layer-1 admission reserve this spawn would be admitted under. | packages/core/dist/index.d.ts |
cachedLoopInputFloorUsd? | number | The same loop under the RV2006 cache policy: one cache write of the prompt floor plus a cache read on every later turn, priced by the row's cache rates. Present beside the uncached figure when the row carries cache rates. The parity worker shape (36k-token prompt floor, a long cycle) prices the difference at roughly three to four times, the gap between four seats fitting a $6 envelope and three seats dying against it. | packages/core/dist/index.d.ts |
count | number | - | packages/core/dist/index.d.ts |
estCeiling? | { ceilingUsd: number; fits: boolean; requiredFloorUsd: number; } | The estIsCeiling feasibility line (RV4702, the eighth comparison experiment's first run): present exactly when the orchestrator budget declares estIsCeiling: true and the floors price. ceilingUsd is the child's hard ceiling under that flag (the explicit spawn budget, else the declared estimate), and requiredFloorUsd the cheapest honest reading of the declared posture: the loop input floor across the projected turns (cache-aware when the policy allows) plus ONE tail turn at the declared floor, the finalize-shaped dispatch that run died on. A ceiling below the floor cannot finish the loop it admits at the declared prices, by construction; that run shipped 1.35 against roughly 1.88, preflight said nothing, and the death cost 6.74 USD. | packages/core/dist/index.d.ts |
estCeiling.ceilingUsd | number | - | packages/core/dist/index.d.ts |
estCeiling.fits | boolean | - | packages/core/dist/index.d.ts |
estCeiling.requiredFloorUsd | number | - | packages/core/dist/index.d.ts |
executedToolCallCeiling | number | null | Executed-call ceiling across any tool mix; null = unlimited. | packages/core/dist/index.d.ts |
label | string | - | packages/core/dist/index.d.ts |
limits | EffectiveUsageLimits | The SAME merge the runtime applies: call over profile over engine defaults. | packages/core/dist/index.d.ts |
maxOutputTokensPerTurn? | number | The per-turn output bound: caps.maxOutputTokens clamped by the limits field. | packages/core/dist/index.d.ts |
projectedProviderTurns | number | The provider-call ceiling of ONE spawn's whole loop: maxTurns bounded by the executed-call ceiling plus its final no-tool turn, plus the finalization summary turn when a tool budget limiter arms it. Every provider turn is one wire request and one quota reservation, so this is the per-spawn multiplier of quota demand; retries sit on top of it. | packages/core/dist/index.d.ts |
ratesVerifiedAt? | string | The serving row's last rates verification date (RV814), copied from the resolved pricing; absent when the row names none. Every dollar in this report is priced under that row, so its staleness is part of the projection's honesty. | packages/core/dist/index.d.ts |
reserveSource | | "estCost" | "profile-estCost" | "priced-estimate" | "flat-default" | "unpriced-zero" | Which arm of the reserve formula produced the number. | packages/core/dist/index.d.ts |
role | InvocationRole | - | packages/core/dist/index.d.ts |
servedBy? | `${string}:${string}` | The resolved serving target; absent when no model resolves (see findings). | packages/core/dist/index.d.ts |
toolCeilings | PreflightToolCeiling[] | Per-tool ceilings for every tool a cap or a unit cost names. | packages/core/dist/index.d.ts |
turnFloorUsd? | number | The cost floor of ONE turn at the declared estimates: estInputTokens (default 0) plus the output bound, priced like settlement. A real turn grows with the prompt, so this is a floor, never a cap. | packages/core/dist/index.d.ts |
uncachedLoopInputFloorUsd? | number | The loop's input floor over its projected turns, UNCACHED (RV2007): the declared prompt floor (estInputTokens) re-billed at the full input rate on every projected provider turn. A floor over the static prefix: real prompts grow. Present when the shape prices and projects more than one turn. | packages/core/dist/index.d.ts |
unpriced? | true | True when the serving model has no price row: a USD ceiling cannot bound it. | packages/core/dist/index.d.ts |