Rulvar API reference / @rulvar/core / PreflightReport
Interface: PreflightReport
Defined in: packages/core/src/engine/preflight.ts:520
The machine-readable preflight report; JSON-serializable throughout.
Properties
| Property | Type | Description | Defined in |
|---|---|---|---|
admission | { admitted: number; ceilingHeadroomShare?: number; ceilingHeadroomUsd?: number; ceilingUsd?: number; denied: number; liveRootExposureTermUsd?: number; requiredMinimumCeilingUsd?: number; reservedForFinalizationUsd: number; reserveLineHeadroomUsd?: number; reserveLineUsd?: number; synthesisReserveUsd: number; wave: PreflightAdmissionRow[]; } | - | packages/core/src/engine/preflight.ts:586 |
admission.admitted | number | - | packages/core/src/engine/preflight.ts:649 |
admission.ceilingHeadroomShare? | number | The same headroom as a fraction of the ceiling (RV3208): the one-field read of the admission cliff (the 2026-08-11 experiment ran at 0.0286). Present beside ceilingHeadroomUsd on positive ceilings. | packages/core/src/engine/preflight.ts:620 |
admission.ceilingHeadroomUsd? | number | The ceiling minus the required minimum (RV3208): the absolute dollars of drift the admission survives before the wave stops seating. Present beside requiredMinimumCeilingUsd whenever a ceiling is declared. | packages/core/src/engine/preflight.ts:613 |
admission.ceilingUsd? | number | - | packages/core/src/engine/preflight.ts:587 |
admission.denied | number | - | packages/core/src/engine/preflight.ts:650 |
admission.liveRootExposureTermUsd? | number | The live-root-exposure term of the wave projection (RV2004): the orchestrator's own worst-case turn floor, the money coordination has ALWAYS already spent (and holds in flight) by the time any spawn tool runs. The parity rerun's fourth seat fit the plain wave (5.95 under 6.00) and was refused live by exactly this term; the embedded spawn gate and requiredMinimumCeilingUsd now carry it, so a seat that cannot admit live cannot admit in preflight either. Present on orchestrate waves whose coordination turn prices. | packages/core/src/engine/preflight.ts:632 |
admission.requiredMinimumCeilingUsd? | number | The smallest run ceiling that seats the WHOLE declared wave (RV1907): every row's reserve plus the finalization and synthesis carve-outs. Children admit strictly below exact fill, so a viable ceiling must sit strictly ABOVE this figure; the four-role benchmark's $6.00 sat $0.98 below it and lost its third and fourth workers. Present whenever the wave has rows. | packages/core/src/engine/preflight.ts:606 |
admission.reservedForFinalizationUsd | number | - | packages/core/src/engine/preflight.ts:588 |
admission.reserveLineHeadroomUsd? | number | How far the admitted wave's steady state sits under the reserve line (RV2101). Child spend past the declared estimates consumes this headroom before the coordination loop is refused at the line; under two coordination turn floors the projection warns with reserve-line-headroom. Present beside reserveLineUsd. | packages/core/src/engine/preflight.ts:647 |
admission.reserveLineUsd? | number | The reserve line (RV2101): the run ceiling minus the synthesis reserve, the boundary the budget chain fences every non-tail dispatch at while the promise is held. Present when a ceiling and a positive synthesis reserve are both declared. | packages/core/src/engine/preflight.ts:639 |
admission.synthesisReserveUsd | number | The synthesis payload carve-out the projection holds against the run root, exactly the live commitSynthesisReserve mirror (RV1901): a capped orchestrator with budget.synthesisReserveUsd registers it on the root before any spawn admits, so the wave arithmetic must hold it too. Zero when the orchestrator is uncapped or declares no synthesis reserve, matching the runtime that then commits none. | packages/core/src/engine/preflight.ts:597 |
admission.wave | PreflightAdmissionRow[] | - | packages/core/src/engine/preflight.ts:648 |
budget | { ceilingUsd?: number; childBudgetFraction: number; flatReserveUsd: number; lifetimeSpawnCap: number; maxDepth: number; orchestrator?: { acceptanceReserve?: { declared: "warn" | "require" | "checkpoint"; effectiveCapUsd?: number; fits: boolean; requiredUsd: number; terms: AcceptanceTailTerms; }; effectiveCapUsd?: number; finalizeReserveUsd: number; finalizeTurns: number; projectedProviderTurns: number; repairPool?: { maxSemanticRepairRounds?: number; maxTotalRepairRounds?: number; mechanicalAllowance?: number; }; reserveCommitted: boolean; synthesis?: { projectedProviderTurns: number; servedBy?: `${string}:${string}`; }; }; } | - | packages/core/src/engine/preflight.ts:522 |
budget.ceilingUsd? | number | - | packages/core/src/engine/preflight.ts:523 |
budget.childBudgetFraction | number | - | packages/core/src/engine/preflight.ts:526 |
budget.flatReserveUsd | number | - | packages/core/src/engine/preflight.ts:524 |
budget.lifetimeSpawnCap | number | - | packages/core/src/engine/preflight.ts:525 |
budget.maxDepth | number | - | packages/core/src/engine/preflight.ts:527 |
budget.orchestrator? | { acceptanceReserve?: { declared: "warn" | "require" | "checkpoint"; effectiveCapUsd?: number; fits: boolean; requiredUsd: number; terms: AcceptanceTailTerms; }; effectiveCapUsd?: number; finalizeReserveUsd: number; finalizeTurns: number; projectedProviderTurns: number; repairPool?: { maxSemanticRepairRounds?: number; maxTotalRepairRounds?: number; mechanicalAllowance?: number; }; reserveCommitted: boolean; synthesis?: { projectedProviderTurns: number; servedBy?: `${string}:${string}`; }; } | - | packages/core/src/engine/preflight.ts:528 |
budget.orchestrator.acceptanceReserve? | { declared: "warn" | "require" | "checkpoint"; effectiveCapUsd?: number; fits: boolean; requiredUsd: number; terms: AcceptanceTailTerms; } | The acceptance-tail verdict (RV4001), present exactly when budget.acceptanceReserve is declared: the SAME acceptanceTailRequiredUsd arithmetic the RV3907 runtime gate holds the boot against, term by term, so fits here IS the gate's answer. The fifth comparison experiment ran a plan preflight passed green at a $4.54 cap into a typed runtime refusal at $4.82 because the two sides computed different formulas; they now compute one. | packages/core/src/engine/preflight.ts:557 |
budget.orchestrator.acceptanceReserve.declared | "warn" | "require" | "checkpoint" | - | packages/core/src/engine/preflight.ts:558 |
budget.orchestrator.acceptanceReserve.effectiveCapUsd? | number | Absent when no cap resolves; the runtime then refuses under 'require'. | packages/core/src/engine/preflight.ts:561 |
budget.orchestrator.acceptanceReserve.fits | boolean | Exact fill admits, exactly the runtime gate. | packages/core/src/engine/preflight.ts:563 |
budget.orchestrator.acceptanceReserve.requiredUsd | number | - | packages/core/src/engine/preflight.ts:559 |
budget.orchestrator.acceptanceReserve.terms | AcceptanceTailTerms | - | packages/core/src/engine/preflight.ts:564 |
budget.orchestrator.effectiveCapUsd? | number | min(capUsd, (capFraction ?? 0.2) x ceiling); absent when unresolvable. | packages/core/src/engine/preflight.ts:530 |
budget.orchestrator.finalizeReserveUsd | number | - | packages/core/src/engine/preflight.ts:531 |
budget.orchestrator.finalizeTurns | number | - | packages/core/src/engine/preflight.ts:532 |
budget.orchestrator.projectedProviderTurns | number | The orchestrator agent's own loop ceiling, derived exactly like a spawn's. | packages/core/src/engine/preflight.ts:536 |
budget.orchestrator.repairPool? | { maxSemanticRepairRounds?: number; maxTotalRepairRounds?: number; mechanicalAllowance?: number; } | The run repair pool and its scoped semantic reserve (RV4705), present when either bound is declared: mechanicalAllowance is what finish-validation grants can actually draw (the total minus the unspent reserve), the figure the eighth comparison rerun needed before its mechanical repair ate the armed round's only token. | packages/core/src/engine/preflight.ts:574 |
budget.orchestrator.repairPool.maxSemanticRepairRounds? | number | - | packages/core/src/engine/preflight.ts:576 |
budget.orchestrator.repairPool.maxTotalRepairRounds? | number | - | packages/core/src/engine/preflight.ts:575 |
budget.orchestrator.repairPool.mechanicalAllowance? | number | The pool minus the reserve; absent without a declared total. | packages/core/src/engine/preflight.ts:578 |
budget.orchestrator.reserveCommitted | boolean | Whether the finalize reserve is committed against the run root (extension runs). | packages/core/src/engine/preflight.ts:534 |
budget.orchestrator.synthesis? | { projectedProviderTurns: number; servedBy?: `${string}:${string}`; } | The separate synthesis invocation's projection, present when input.orchestrator.synthesis was declared and the role resolves: its turn ceiling (the repair turn reserve folded in when declared) and its serving model. | packages/core/src/engine/preflight.ts:543 |
budget.orchestrator.synthesis.projectedProviderTurns | number | - | packages/core/src/engine/preflight.ts:544 |
budget.orchestrator.synthesis.servedBy? | `${string}:${string}` | - | packages/core/src/engine/preflight.ts:545 |
concurrency | { perProvider?: Record<string, number>; perRun: number; } | - | packages/core/src/engine/preflight.ts:521 |
concurrency.perProvider? | Record<string, number> | - | packages/core/src/engine/preflight.ts:521 |
concurrency.perRun | number | - | packages/core/src/engine/preflight.ts:521 |
exposure | { maxInFlight: number; overshootOneTurnFloorUsd?: number; perProvider: Record<string, { inFlight: number; requestsPerWave: number; tokensPerWaveFloor: number; }>; requiredMinimumExposureUsd?: number; runCeiling?: { requests: number; tokens: number; }; } | - | packages/core/src/engine/preflight.ts:652 |
exposure.maxInFlight | number | Concurrent in-flight turns the declared wave can hold. | packages/core/src/engine/preflight.ts:654 |
exposure.overshootOneTurnFloorUsd? | number | The one-more-turn cost floor past a ceiling crossing: the sum of the maxInFlight most expensive declared turn floors. The documented overshoot bound is one turn per in-flight agent; real turns grow with the prompt, so this is the floor of that bound. | packages/core/src/engine/preflight.ts:661 |
exposure.perProvider | Record<string, { inFlight: number; requestsPerWave: number; tokensPerWaveFloor: number; }> | Per-provider first-wave demand at the declared estimates. | packages/core/src/engine/preflight.ts:674 |
exposure.requiredMinimumExposureUsd? | number | The smallest in-flight exposure cap under which the declared wave can breathe (RV1907): the finalization and synthesis carve-outs plus the turn floors of the maxInFlight most expensive declared dispatches, the orchestrator's own turn among them. Below it the root's next turn is refused beside a full child wave, the recovery arm's exact death; the RV1902 wait recovers the run, but only a cap at or above this floor avoids the stall entirely. Absent when no declared turn prices. | packages/core/src/engine/preflight.ts:672 |
exposure.runCeiling? | { requests: number; tokens: number; } | The declared wave run to its derived turn ceilings, at the declared estimates (the second experiment report, rec 9): total provider calls (fan-out times per-spawn projected turns, before any retries) and the cumulative token demand with the context regrowing every turn (turn k re-sends the declared prompt plus the k-1 prior output bounds, so K turns cost K x est + outputBound x K(K+1)/2). Absent when nothing is declared. | packages/core/src/engine/preflight.ts:687 |
exposure.runCeiling.requests | number | - | packages/core/src/engine/preflight.ts:687 |
exposure.runCeiling.tokens | number | - | packages/core/src/engine/preflight.ts:687 |
findings | PreflightFinding[] | - | packages/core/src/engine/preflight.ts:701 |
finishValidation? | { contractHash?: string; selfTest: "failed" | "passed" | "skipped"; validators: string[]; } | Present when input.finishValidation was provided: the self test echo. selfTest reflects the golden fixture run alone ('skipped' = no fixture resolvable); containment drift between a contract and the validator set reports through findings either way. | packages/core/src/engine/preflight.ts:696 |
finishValidation.contractHash? | string | - | packages/core/src/engine/preflight.ts:697 |
finishValidation.selfTest | "failed" | "passed" | "skipped" | - | packages/core/src/engine/preflight.ts:699 |
finishValidation.validators | string[] | - | packages/core/src/engine/preflight.ts:698 |
quota | { configured: boolean; rules?: number; tenant?: string; } | - | packages/core/src/engine/preflight.ts:582 |
quota.configured | boolean | - | packages/core/src/engine/preflight.ts:582 |
quota.rules? | number | - | packages/core/src/engine/preflight.ts:582 |
quota.tenant? | string | - | packages/core/src/engine/preflight.ts:582 |
runLimits | EffectiveUsageLimits | The run-level merge an undeclared spawn would receive. | packages/core/src/engine/preflight.ts:584 |
spawns | PreflightSpawnReport[] | - | packages/core/src/engine/preflight.ts:585 |