@rulvar/core 1.217.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;
   /**
@@ -13093,6 +13106,15 @@ interface PreflightOrchestratorSpec {
       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

@@ -13930,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();
 	}
@@ -24068,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 ?? {};
@@ -24096,6 +24128,7 @@ function makeOrchestratorWorkflow(goal, opts) {
 			try {
 				return await runSynthesis(result.output);
 			} catch (thrown) {
+				await journalSynthesisAdmissionDecline(thrown);
 				return enrichSynthesisFailure(thrown);
 			}
 		}
@@ -24302,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,
@@ -25093,10 +25127,11 @@ 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;
@@ -25109,6 +25144,21 @@ function preflightEstimate(input) {
 			});
 		}
 	}
+	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.217.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",