@rulvar/core 1.216.0 → 1.218.0

package/dist/index.d.ts

@@ -6470,7 +6470,20 @@ declare class RunBudget {
   /**
   * Resume roll-forward: commits a reserve recovered from a journaled
   * spawn-admission decision entry without re-evaluating admission
-  * (reserves are recovered, never re-estimated).
+  * (reserves are recovered, never re-estimated). The lifetime spawn
+  * counter does NOT increment here (RV2201): every agent the
+  * roll-forward re-covers already counted through the resume seed,
+  * whose journal fold counts each dispatched agent entry, so an
+  * incrementing roll-forward double-counts every recovered child.
+  * The seventh subscription parity run resumed a killed 4-child
+  * fan-out into a seed of 5, re-counted the children to 9 against a
+  * cap of 8, and the post-acceptance tail starved on the counter
+  * while the synthesis reserve's money sat whole: the judge declined
+  * typed, the synthesis spawn refusal reached the terminal, and the
+  * accepted dossier was lost. Each spawned agent counts a single
+  * time across the run's whole life, never twice: at its fresh
+  * admitSpawn, or through the seed of whichever segment rolls it
+  * forward.
   */
   admitRecovered(reserveUsd: number, accountScope?: string): void;
   /**
@@ -9992,6 +10005,17 @@ interface OrchestrateClaimConsistencyMeta {
   /** Present when the judge invocation did not settle ok. */
   judgeFailed?: true;
   /**
+  * Present when the judge invocation was refused ADMISSION and never
+  * dispatched (RV2106): the ninth parity run's judge estimate did not
+  * fit the orchestrator account's working room past the held
+  * synthesis reserve, and the bare refusal killed a run whose fan-out
+  * and draft were already complete. The declined pass degrades like a
+  * failed judge (the meta names it, the journaled decision carries
+  * the arithmetic, only the armed 'fail' posture stops the run) and
+  * the synthesis its reserve was holding money for still dispatches.
+  */
+  judgeDeclined?: true;
+  /**
   * The one field a consumer reads INSTEAD of inferring semantic
   * health from an empty findings array (RV1702):
   * {@link claimCoverageOf} over this meta, so `completion:
@@ -13068,6 +13092,29 @@ interface PreflightOrchestratorSpec {
     exposeChildResultTools?: boolean; /** Mirrors OrchestrateSynthesis.context; default 'digests'. */
     context?: "digests" | "full";
   };
+  /**
+  * The claim-consistency judge's admission estimate (RV2106), exactly
+  * OrchestrateClaimConsistency.judge.estCost: the post-fan-in judge
+  * admits against the ORCHESTRATOR account, whose working room past
+  * the held synthesis reserve the coordination loop's own turns spend
+  * from first. Declaring the estimate lets the estimator judge that
+  * room statically (`orchestrator-working-room`); absent, the finding
+  * stays silent, exactly like every other undeclared input.
+  */
+  claimConsistency?: {
+    judge?: {
+      estCost?: number;
+    };
+  };
+  /**
+  * The `reserve-line-headroom` threshold in coordination turn floors
+  * (RV2201; previously hardwired to 2): the finding warns when the
+  * admitted wave's steady state sits closer to the reserve line than
+  * this many coordination turn floors. Raise it for waves whose
+  * children routinely overrun their declared estimates; 0 silences
+  * the finding entirely. Default 2.
+  */
+  headroomTurns?: number;
 }
 /** The full input: engine surface, run surface, and the declared wave. */
 interface PreflightInput {

package/dist/index.js

@@ -13909,10 +13909,12 @@ var RunBudget = class {
 			const committed = account.spentUsd + account.committedReserveUsd + account.finalizeReserveUsd + account.synthesisReserveUsd;
 			if (committed >= account.ceilingUsd || committed + reserveUsd > account.ceilingUsd) {
 				if (account.scope === "run") this.exhaustedInternal = true;
-				throw new BudgetExhaustedError(`budget ceiling reached on account '${account.scope}': spent ${account.spentUsd.toFixed(4)} USD plus committed reserves ${(account.committedReserveUsd + account.finalizeReserveUsd).toFixed(4)} USD plus the proposed reserve ${reserveUsd.toFixed(4)} USD does not fit the ceiling ${account.ceilingUsd.toFixed(4)} USD`, { data: {
+				throw new BudgetExhaustedError(`budget ceiling reached on account '${account.scope}': spent ${account.spentUsd.toFixed(4)} USD plus committed reserves ${(account.committedReserveUsd + account.finalizeReserveUsd).toFixed(4)} USD ` + (account.synthesisReserveUsd > 0 ? `plus the held synthesis reserve ${account.synthesisReserveUsd.toFixed(4)} USD ` : "") + `plus the proposed reserve ${reserveUsd.toFixed(4)} USD does not fit the ceiling ${account.ceilingUsd.toFixed(4)} USD`, { data: {
 					account: account.scope,
 					spentUsd: account.spentUsd,
 					committedReserveUsd: account.committedReserveUsd,
+					finalizeReserveUsd: account.finalizeReserveUsd,
+					synthesisReserveUsd: account.synthesisReserveUsd,
 					proposedReserveUsd: reserveUsd,
 					ceilingUsd: account.ceilingUsd
 				} });
@@ -13928,10 +13930,22 @@ var RunBudget = class {
 	/**
 	* Resume roll-forward: commits a reserve recovered from a journaled
 	* spawn-admission decision entry without re-evaluating admission
-	* (reserves are recovered, never re-estimated).
+	* (reserves are recovered, never re-estimated). The lifetime spawn
+	* counter does NOT increment here (RV2201): every agent the
+	* roll-forward re-covers already counted through the resume seed,
+	* whose journal fold counts each dispatched agent entry, so an
+	* incrementing roll-forward double-counts every recovered child.
+	* The seventh subscription parity run resumed a killed 4-child
+	* fan-out into a seed of 5, re-counted the children to 9 against a
+	* cap of 8, and the post-acceptance tail starved on the counter
+	* while the synthesis reserve's money sat whole: the judge declined
+	* typed, the synthesis spawn refusal reached the terminal, and the
+	* accepted dossier was lost. Each spawned agent counts a single
+	* time across the run's whole life, never twice: at its fresh
+	* admitSpawn, or through the seed of whichever segment rolls it
+	* forward.
 	*/
 	admitRecovered(reserveUsd, accountScope = "run") {
-		this.agentsSpawnedInternal += 1;
 		for (const account of this.chainOf(accountScope)) account.committedReserveUsd += reserveUsd;
 		this.emitUpdate();
 	}
@@ -23402,7 +23416,42 @@ function makeOrchestratorWorkflow(goal, opts) {
 				...spec.judge?.effort === void 0 ? {} : { effort: spec.judge.effort },
 				...spec.judge?.estCost === void 0 ? {} : { estCost: spec.judge.estCost }
 			};
-			const judged = await runtime.runInScope(judgeState, () => ctx.agent(judgePrompt, judgeOpts));
+			let judged;
+			try {
+				judged = await runtime.runInScope(judgeState, () => ctx.agent(judgePrompt, judgeOpts));
+			} catch (declined) {
+				if (!(declined instanceof BudgetExhaustedError)) throw declined;
+				claimConsistencyMeta = finishMeta({
+					judgeInvoked: false,
+					judgeDeclined: true
+				});
+				const declineKey = deriverV2.deriveKey({ kind: "orchestrator-claim-judge-declined" });
+				if (!internals.replayer.snapshot().some((entry) => entry.kind === "decision" && entry.key === declineKey)) await internals.replayer.appendSinglePhase({
+					scope: callingState.scope,
+					key: declineKey,
+					kind: "decision",
+					status: "ok",
+					spanId: internals.spans.mint(callingState.spanId),
+					site: "orchestrator-budget",
+					value: {
+						decisionType: "orchestrator_claim_judge_declined",
+						reason: declined.message.slice(0, 300),
+						remainingUsd: internals.budget.remainingUsd(orchestratorAccount ?? "run") ?? null
+					}
+				});
+				internals.events.emit({
+					type: "log",
+					level: "warn",
+					msg: "orchestrator claim consistency judge declined by admission",
+					data: { reason: declined.message.slice(0, 300) }
+				}, callingState.spanId);
+				if (onFound === "fail") throw new FailRunError("the claim-consistency judge could not be admitted within the orchestrator account, so the armed fail posture cannot pass the draft: " + declined.message.slice(0, 300), { data: {
+					source: "orchestrator_claim_consistency",
+					claimConsistencyMeta,
+					...snapshot ?? {}
+				} });
+				return;
+			}
 			if (judged.status !== "ok" || judged.output === null || judged.output === void 0) {
 				claimConsistencyMeta = finishMeta({
 					judgeInvoked: true,
@@ -24031,6 +24080,26 @@ function makeOrchestratorWorkflow(goal, opts) {
 		* rejection-past-the-bound error keeps its own
 		* repairsUsed/maxRepairs/failed untouched.
 		*/
+		const journalSynthesisAdmissionDecline = async (thrown) => {
+			if (!(thrown instanceof BudgetExhaustedError)) return;
+			const declineKey = deriverV2.deriveKey({ kind: "orchestrator-synthesis-redemption-declined" });
+			if (internals.replayer.snapshot().some((entry) => entry.kind === "decision" && entry.key === declineKey)) return;
+			await internals.replayer.appendSinglePhase({
+				scope: callingState.scope,
+				key: declineKey,
+				kind: "decision",
+				status: "ok",
+				spanId: internals.spans.mint(callingState.spanId),
+				site: "orchestrator-budget",
+				value: {
+					decisionType: "orchestrator_synthesis_redemption_declined",
+					reason: thrown.message.slice(0, 300),
+					remainingUsd: internals.budget.remainingUsd() ?? null,
+					spawnHeadroom: internals.budget.spawnHeadroom,
+					path: "accepted-finish"
+				}
+			});
+		};
 		const enrichSynthesisFailure = (thrown, snapshot) => {
 			if (!(thrown instanceof FailRunError)) throw thrown;
 			const base = thrown.data ?? {};
@@ -24059,6 +24128,7 @@ function makeOrchestratorWorkflow(goal, opts) {
 			try {
 				return await runSynthesis(result.output);
 			} catch (thrown) {
+				await journalSynthesisAdmissionDecline(thrown);
 				return enrichSynthesisFailure(thrown);
 			}
 		}
@@ -24265,6 +24335,7 @@ function makeOrchestratorWorkflow(goal, opts) {
 		try {
 			synthesizedFinal = await runSynthesis(result.output);
 		} catch (thrown) {
+			await journalSynthesisAdmissionDecline(thrown);
 			enrichSynthesisFailure(thrown, {
 				completion: decision.completion,
 				childStatusCounts: decision.childStatusCounts,
@@ -24524,6 +24595,7 @@ function preflightEstimate(input) {
 	if (input.orchestrator !== void 0) {
 		if (input.orchestrator.estInputTokens !== void 0) requireNonNegativeInteger(input.orchestrator.estInputTokens, "preflight.orchestrator.estInputTokens");
 		if (input.orchestrator.acceptance?.minSpawnedChildren !== void 0) requirePositiveInteger$2(input.orchestrator.acceptance.minSpawnedChildren, "preflight.orchestrator.acceptance.minSpawnedChildren");
+		if (input.orchestrator.claimConsistency?.judge?.estCost !== void 0) requireNonNegativeNumber(input.orchestrator.claimConsistency.judge.estCost, "preflight.orchestrator.claimConsistency.judge.estCost");
 		const spec = input.orchestrator.budget;
 		const fraction = spec?.capFraction ?? .2;
 		const fromFraction = ceilingUsd === void 0 ? void 0 : fraction * ceilingUsd;
@@ -25055,11 +25127,38 @@ function preflightEstimate(input) {
 	const requiredMinimumCeilingUsd = wave.length === 0 ? void 0 : wave.reduce((sum, row) => sum + row.reserveUsd, 0) + reservedForFinalizationUsd + synthesisHoldUsd + liveRootExposureTermUsd;
 	const reserveLineUsd = ceilingUsd === void 0 || synthesisHoldUsd <= 0 ? void 0 : ceilingUsd - synthesisHoldUsd;
 	const reserveLineHeadroomUsd = reserveLineUsd === void 0 ? void 0 : reserveLineUsd - wave.filter((row) => row.admitted).reduce((sum, row) => sum + row.reserveUsd, 0);
-	if (orchestrateWave && reserveLineUsd !== void 0 && reserveLineHeadroomUsd !== void 0 && wave.some((row) => row.admitted) && reserveLineHeadroomUsd < 2 * Math.max(liveRootExposureTermUsd, 1e-4)) say({
+	const headroomTurns = input.orchestrator?.headroomTurns ?? 2;
+	if (orchestrateWave && reserveLineUsd !== void 0 && reserveLineHeadroomUsd !== void 0 && wave.some((row) => row.admitted) && headroomTurns > 0 && reserveLineHeadroomUsd < headroomTurns * Math.max(liveRootExposureTermUsd, 1e-4)) say({
 		severity: "warning",
 		code: "reserve-line-headroom",
-		message: `the admitted wave's steady state sits ${reserveLineHeadroomUsd.toFixed(4)} USD under the reserve line ${reserveLineUsd.toFixed(4)} USD (the ceiling minus the synthesis reserve), less than two coordination turn floors of headroom (${liveRootExposureTermUsd.toFixed(4)} USD each): child spend past the declared estimates eats that headroom, the coordination loop is then refused at the line, and the run settles partial with the synthesis redeemed from its reserve (RV2101); size the wave below the line or raise the ceiling to keep coordinating past it`
+		message: `the admitted wave's steady state sits ${reserveLineHeadroomUsd.toFixed(4)} USD under the reserve line ${reserveLineUsd.toFixed(4)} USD (the ceiling minus the synthesis reserve), less than ${String(headroomTurns)} coordination turn floors of headroom (${liveRootExposureTermUsd.toFixed(4)} USD each): child spend past the declared estimates eats that headroom, the coordination loop is then refused at the line, and the run settles partial with the synthesis redeemed from its reserve (RV2101); size the wave below the line or raise the ceiling to keep coordinating past it`
 	});
+	{
+		const judgeEstUsd = input.orchestrator?.claimConsistency?.judge?.estCost;
+		if (judgeEstUsd !== void 0 && effectiveCapUsd !== void 0 && synthesisHoldUsd > 0) {
+			const workingRoomUsd = effectiveCapUsd - synthesisHoldUsd;
+			if (workingRoomUsd < liveRootExposureTermUsd + judgeEstUsd) say({
+				severity: "warning",
+				code: "orchestrator-working-room",
+				message: `the orchestrator account's working room past the held synthesis reserve is ${workingRoomUsd.toFixed(4)} USD (cap ${effectiveCapUsd.toFixed(4)} minus the ${synthesisHoldUsd.toFixed(4)} USD hold), below one coordination turn floor (${liveRootExposureTermUsd.toFixed(4)} USD) plus the declared ${judgeEstUsd.toFixed(4)} USD claim-consistency judge estimate: the judge admission will be declined once the coordination loop has taken even one turn, and the pass degrades to its journaled declined verdict (RV2106); raise the cap, shrink the judge estimate, or shrink the synthesis reserve`
+			});
+		}
+	}
+	if (orchestrateWave && wave.length > 0 && admitted === wave.length) {
+		const lifetimeSpawnCap = input.engine?.budgetDefaults?.lifetimeSpawnCap ?? 500;
+		const judgeDeclared = input.orchestrator?.claimConsistency?.judge !== void 0;
+		const synthesisDeclared = input.orchestrator?.synthesis !== void 0;
+		const plannedSpawns = wave.length + (judgeDeclared ? 1 : 0) + (synthesisDeclared ? 1 : 0);
+		const spawnHeadroom = lifetimeSpawnCap - plannedSpawns;
+		if (spawnHeadroom <= 0) {
+			const breakdown = `the admitted wave of ${String(wave.length)} agent invocations` + (judgeDeclared ? " plus the claim-consistency judge" : "") + (synthesisDeclared ? " plus the synthesis invocation" : "") + ` is ${String(plannedSpawns)} against budgetDefaults.lifetimeSpawnCap ` + String(lifetimeSpawnCap);
+			say({
+				severity: "warning",
+				code: "tail-spawn-budget",
+				message: spawnHeadroom < 0 ? breakdown + ": the post-fan-in tail starves on the counter with its money whole: the judge admission declines typed (RV2106) and the synthesis spawn journals its declined verdict (RV2201) instead of composing; raise the cap to seat the declared tail" : breakdown + ": an exact fill leaves zero spawn headroom, so nothing the plan did not name (a re-spawned child, a second pass) can ever be admitted; raise the cap for margin"
+			});
+		}
+	}
 	if (wave.length > 0 && denied > 0) {
 		const deniedLabels = wave.filter((row) => !row.admitted).map((row) => row.label);
 		if (admitted === 0) say({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/core",
-  "version": "1.216.0",
+  "version": "1.218.0",
   "description": "Rulvar core: L0 contracts, journal kernel, ctx primitives, agent runtime, model router, tool system, dynamic orchestrator, InMemory and JSONL stores, event stream.",
   "type": "module",
   "license": "Apache-2.0",