Rulvar API reference / @rulvar/core / OrchestrateOptions
Interface: OrchestrateOptions
Defined in: packages/core/src/orchestrator/orchestrate.ts:900
Properties
| Property | Type | Description | Defined in |
|---|---|---|---|
acceptance? | OrchestrateAcceptance | The opt in child completion policy; see OrchestrateAcceptance. | packages/core/src/orchestrator/orchestrate.ts:988 |
budget? | OrchestratorBudgetSpec | The orchestrator's own budget sub-account (cap enforcement layers only in M6). | packages/core/src/orchestrator/orchestrate.ts:915 |
citationAudit? | OrchestrateCitationAudit | The citation entailment audit (RV4004, the fifth comparison experiment): a deterministic stratified sample of the FINAL document's citing sentences, their cited lines read back through the host's own pure snapshot resolver (the citedValueValidator channel), and one bounded judge invocation ruling supported/partial/unsupported per sampled citation. The run's other verifiers judge VALUES, TARGETS, and CONSISTENCY against the child pool; none of them reads the cited lines and asks whether the text entails the sentence, which is exactly how the experiment shipped three unsupported citations that were mechanically valid, value-clean, and invisible to a pool that held no reading of those files (20 of 74 citing sentences had no candidates at all). This pass is the independent judge's own method, internalized. See OrchestrateCitationAudit. | packages/core/src/orchestrator/orchestrate.ts:1143 |
claimConsistency? | OrchestrateClaimConsistency | The opt-in claim-consistency pass (RV1501/RV1502, the eighteenth improvement plan). The contradiction pass compares the children against EACH OTHER; nothing compares the COMPOSED text against the pool it composed from, so a root that inverts a child's finding while citing the child's own span passes every mechanical check (the seventeenth comparison run shipped exactly that inversion over subprocess.ts:256-296). With this set, the accepted draft's citing sentences are paired with the pool sentences reading an intersecting span of the same file (pairDraftClaims, a pure fold), and ONE bounded judge invocation rules on the pairs. The judge is a PAID model call, journaled like any agent entry, so a resume replays its verdict with zero adapter calls; when the fold pairs nothing, no judge is ever dispatched. See OrchestrateClaimConsistency. | packages/core/src/orchestrator/orchestrate.ts:1126 |
contradictions? | OrchestrateContradictions | The opt-in bounded contradiction pass (RV1302, the sixteenth comparison experiment's P2-1 remainder). A fan-out produces N independent children and nothing else in the pipeline compares their claims against EACH OTHER: acceptance judges each child alone, the finish validators judge the final text mechanically, and synthesis.dedupeClaims matches on agreement, so it is blind to disagreement by construction. With this set, the settled evidence pool is folded through findContradictions at the post-fan-in chokepoint and the run says what it found. See OrchestrateContradictions. | packages/core/src/orchestrator/orchestrate.ts:1109 |
coordinationCheckpoints? | boolean | Journaled coordination checkpoints (RV4410, the seventh comparison experiment): with true, every settled await round appends a compact coordination_checkpoint decision (the round ordinal, the settled handles, the spend so far), so a timeout or kill terminal shows how far coordination durably got, an operator reads progress from rulvar inspect instead of the raw transcript, and a resumed run's replay visibly continues from the last checkpoint instead of an opaque prefix. Opt-in because the decisions are journal bytes; the replay machinery already never re-pays journaled coordination either way. | packages/core/src/orchestrator/orchestrate.ts:976 |
executionFacts? | boolean | Opt in per-child execution facts on the await digests and the child result page (RV1503, the eighteenth improvement plan). The seventeenth comparison run graded its whole dossier live-observed: no while the harness had just watched 118 wire requests settle, because no surface ever showed the composing root what its run actually executed. With this set, every TaskDigest an await returns (and every get_child_result page) carries facts: wire request and missing-response-id counts folded from the journaled per-dispatch reconciliation records, plus the journaled token totals (executionFactsOf), all replay-stable by construction. Dollars are deliberately absent (replay re-prices from the current table). Off by default: tool result bytes enter the window, and the window is journal identity, so the historical bytes stay exact without the opt-in. | packages/core/src/orchestrator/orchestrate.ts:1083 |
exposeChildResultTools? | boolean | Opt in to the evidence tools get_child_result and read_child_artifact (the v1.40.0 improvement plan's narrow RV-201 slice). The digest an await returns is a wake signal truncated to 400 characters; with this set, the orchestrator can page a settled child's FULL output and its artifact contents, both pure reads of durable journal state. Adding the tools changes the orchestrator toolset hash by design (exactly like the extension's plan tools), so leave it off and the default toolset, and every frozen cassette, stay unchanged. | packages/core/src/orchestrator/orchestrate.ts:1053 |
exposeSettledResultsTool? | boolean | Opt in the bulk settled-set read get_settled_child_results (RV1807). The nineteenth benchmark's root made fourteen get_child_result calls to consume six children, eight of them speculative probes that returned not-settled errors; with this set, the model consumes the exact settledHandles set an await_any digest returns in ONE call, refused typed BEFORE any read when a handle is unknown or still running. Its own opt-in rather than a rider on exposeChildResultTools, because adding a tool under the existing flag would move every opted-in run's toolset hash and re-key their resumes. | packages/core/src/orchestrator/orchestrate.ts:1066 |
extension? | OrchestratorExtension | The opt-in mode (c) extension seam (M7-T05): PlanRunner from @rulvar/plan attaches here. The extension boots strictly before the orchestrator's first agent entry, contributes tools, schedules ready plan nodes on every settlement, and participates in the mandatory quiescence trigger. | packages/core/src/orchestrator/orchestrate.ts:986 |
finishValidation? | FinishValidationSpec | The opt in deterministic host validation of the finish result, with bounded repair; see FinishValidationSpec. | packages/core/src/orchestrator/orchestrate.ts:1041 |
limits? | UsageLimits | UsageLimits of the orchestrator agent itself (maxTurns etc.). | packages/core/src/orchestrator/orchestrate.ts:978 |
maxSemanticRepairRounds? | number | The scoped semantic reserve inside the run repair pool (RV4705, the eighth comparison experiment's rerun): that run consumed its one-token pool on a MECHANICAL composition repair before the judges ruled, so the post-judge semantic round was refused while 38 census findings stood unconsumed, and the question contract's "exactly one bounded repair" meant exactly that round. Declared, this is BOTH a reserve and a cap: mechanical finish-validation grants may never consume the reserved rounds (they admit only while the total pool holds the UNSPENT reserve on top of them), and the semantic round itself is bounded by this number beside the total pool it still shares (a stage bound NARROWS the pool, never widens it, the RV4406 doctrine). Greater than a declared maxTotalRepairRounds refuses typed at construction: a reserve the pool cannot hold is a contradiction. Declared without a total pool it is the semantic round's own cap alone, and the mechanical grants stay unbounded exactly as before. Absent keeps every decision and refusal byte identical. | packages/core/src/orchestrator/orchestrate.ts:963 |
maxSpawns? | number | Per-orchestrate spawn cap: a nonnegative integer (zero admits no spawns), validated before any journal entry or dispatch. The engine lifetime cap applies regardless. The cap counts ADMITTED children: an admission-rejected spawn (budget, quota, depth) consumes no slot, so the orchestrator may retry a rejected role at a viable budget (v1.81; the sixth comparison experiment's run 2). Attempts stay bounded regardless through the coordination turn's own tool budget. | packages/core/src/orchestrator/orchestrate.ts:913 |
maxTotalRepairRounds? | number | One run-wide repair pool (RV4406, the seventh comparison experiment): every provider-dispatching repair grant consumes from it, whatever gate granted it. The per-stage bounds (finishValidation.maxRepairs, the one bounded semantic round) NARROW the pool, never widen it: a stage may grant fewer repairs than the pool has left, and a stage whose own bound is spent refuses regardless of the pool. The pool consumes durable tokens: a finish-validation 'repair' verdict IS its consumption (the decision lands before the repair turn dispatches), and a semantic repair round journals a repair_pool_consume decision strictly BEFORE its dispatch, keyed so a crash between the decision and the dispatch resumes without a double consume. The draft-gate pre-pass dispatches no provider work and spends nothing, by design. Absent keeps every decision and refusal byte identical. maxSemanticRepairRounds reserves rounds inside this pool for the semantic stage (RV4705). | packages/core/src/orchestrator/orchestrate.ts:943 |
model? | ModelSpec | - | packages/core/src/orchestrator/orchestrate.ts:901 |
onUnsettledAtExit? | "cancel" | "drain" | The terminal child barrier policy (RV1903, the four-role benchmark's recovery arm): what happens to children still running when the orchestration exits, on EVERY exit path (an accepted or rejected finish, a typed failure, a budget or exposure terminal). 'cancel' (the default) aborts them and awaits their journaled cancelled terminals; 'drain' awaits their natural terminals, bounded by their own limits and budgets, preserving their evidence at the price of the wait. Either way the orchestration returns only after every spawned child has a terminal journal entry, so run_settle can never precede a child's billing row again: the benchmark's recovery journal recorded three child terminals AFTER the settle decision, and four mutually inconsistent cost views followed. The verdict the run settled with is already frozen before the barrier runs, so late children never change it. | packages/core/src/orchestrator/orchestrate.ts:1005 |
parallelAdmission? | "fail-fast" | "try-all" | "all-or-none" | The parallel_agents admission policy (RV1908). 'fail-fast' (the default, the RV805 shape) admits in submission order and stops at the first refusal, tasks after it never attempted. 'try-all' attempts every task and reports every refusal, so one refused sibling no longer hides whether the rest would seat. 'all-or-none' projects the WHOLE batch against the live remainder first and refuses it typed with zero admissions when it cannot seat entirely; a non-budget failure mid-batch cancels the admitted siblings, best-effort atomicity over a machinery that cannot un-admit. Independent of the policy, a declared acceptance.minSpawnedChildren arms the roster pre-check: a batch large enough to seat the floor whose feasible count cannot reach it is refused before paying for the first child, the four-role benchmark's primary arm shape, where two workers were paid in full and the settle verdict was bound to reject them. | packages/core/src/orchestrator/orchestrate.ts:1023 |
profiles? | string[] | Registered profile names to advertise; default: every profile. | packages/core/src/orchestrator/orchestrate.ts:903 |
renderBudgetChars? | number | Deterministic digest render bound: a nonnegative integer, validated before any journal entry or dispatch. Each TaskDigest outputSummary is truncated to AT MOST this many CHARACTERS, the truncation marker included (a budget below 3 keeps the bound with a bare slice; the model-independent measure; OQ-04 closed at M10 entry). Default WAKE_SUMMARY_RENDER_BUDGET_CHARS. | packages/core/src/orchestrator/orchestrate.ts:924 |
requireBatchSpawn? | "reject-spawn-agent" | The batch-spawn discipline (RV2005). The third parity rerun's model ignored the instruction to spawn its roster in one parallel_agents call and spawned seat by seat through spawn_agent, so the RV1908 batchGate never saw a batch and the roster feasibility rode on per-seat luck. 'reject-spawn-agent' refuses every SINGLE spawn_agent call typed (code 'batch_required', nothing journaled, nothing paid) so model disobedience cannot split the policy: the model reads the refusal and re-issues the wave as one parallel_agents batch. Absent, both tools behave as documented. | packages/core/src/orchestrator/orchestrate.ts:1036 |
semanticAcceptance? | OrchestrateSemanticAcceptance | The atomic production posture (RV4201, the sixth comparison experiment): one declaration that a run may settle accepted only clean (full final coverage, zero surviving contradictions, zero surviving unsupported citations, no waiver, or exactly the one pinned-hash waiver). Intake refuses any claimConsistency / citationAudit field that contradicts it, so the observing postures the sixth experiment shipped under cannot coexist with the declaration. See OrchestrateSemanticAcceptance. | packages/core/src/orchestrator/orchestrate.ts:1154 |
synthesis? | OrchestrateSynthesis | The opt in post-fan-in synthesis invocation (RV-211): with this set, the coordination loop's finish({ result }) becomes a DRAFT, and a SEPARATE fresh invocation with role 'synthesize' (its own model, effort, and limits through the ordinary resolution chain; the routing key 'synthesize' picks its model and never summons it) composes the final run result from the goal, the draft, and the settled child digest, on the finish-only toolset. When finishValidation is configured its validators bind the SYNTHESIS finish (the final output), not the draft. See OrchestrateSynthesis. | packages/core/src/orchestrator/orchestrate.ts:1096 |