@rulvar/core 1.211.0 → 1.212.0

package/dist/index.d.ts

@@ -382,13 +382,18 @@ type AgentError = {
   retryAfterMs?: number;
   issues?: Issue$1[];
   /**
-  * The typed refusal marker (RV2002): 'exposure-drained' names a
-  * spawned child refused pre-wire by the in-flight exposure cap with
-  * no live holder left to wait out. Zero provider attempts by
-  * construction, so the seat is cheap to re-spawn; an orchestrator
-  * treats it as a starved seat, never a crashed child.
-  */
-  reason?: "exposure-drained";
+  * The typed refusal marker (RV2002, widened by RV2101):
+  * 'exposure-drained' names a spawned child refused pre-wire by the
+  * in-flight exposure cap with no live holder left to wait out (zero
+  * provider attempts by construction, so the seat is cheap to
+  * re-spawn; an orchestrator treats it as a starved seat, never a
+  * crashed child). 'output-floor' names a turn refused pre-wire
+  * because the remaining budget past the held reserves cannot afford
+  * the model's output floor: at the reserve line this is the
+  * boundary where the coordination loop settles partial and the
+  * synthesis promise is redeemed, never a crash.
+  */
+  reason?: "exposure-drained" | "output-floor";
 };
 /**
 * Projects an AgentError to its WireError form: code 'agent', with kind,
@@ -6513,10 +6518,17 @@ declare class RunBudget {
   * price rows as the layer-2b clamp) right before the wire call and
   * releases at the attempt's settle, so the reservation lives exactly
   * as long as the exposure it covers. The admission refuses, typed
-  * and without waiting, when spent + the named reserves (finalize and
-  * synthesis money is promised elsewhere) + live reservations + this
+  * and without waiting, when spent + live reservations + this
   * estimate does not fit the cap; an exact fill admits, mirroring
-  * admitSpawn, and a full cap refuses even a zero estimate. A refusal
+  * admitSpawn, and a full cap refuses even a zero estimate. The tail
+  * reserves (finalize and synthesis) stay OUT of the sum (RV2101):
+  * the budget chain already fences them (remainingUsd subtracts the
+  * synthesis promise, and the finalize carve-out nets out of the
+  * orchestrator's own cap), so counting them here too made the cap
+  * bind at cap minus reserves while the actual wire risk was far
+  * below it: the fourth parity run's root was refused at spent
+  * 4.71 + reserve 1.00 against 5.70 with zero live estimates, one
+  * turn short of the synthesis the reserve existed to fund. A refusal
   * is TRANSIENT (in-flight money returns at settle), so it never
   * marks the run exhausted and never severs a stream. A model without
   * a price row reserves zero, exactly as it debits zero (the
@@ -13290,6 +13302,21 @@ interface PreflightReport {
     * coordination turn prices.
     */
     liveRootExposureTermUsd?: 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.
+    */
+    reserveLineUsd?: 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.
+    */
+    reserveLineHeadroomUsd?: number;
     wave: PreflightAdmissionRow[];
     admitted: number;
     denied: number;

package/dist/index.js

@@ -10931,7 +10931,7 @@ function applyOutputBudget(req, target, budget) {
 	if (affordable === void 0) return req;
 	if (affordable < floor) {
 		const zeroInputAffordable = hook(target.resolved.ref, 0);
-		if (zeroInputAffordable !== void 0 && zeroInputAffordable < floor) throw new BudgetExhaustedError(floor === 1 ? `the remaining budget cannot afford one output token from ${target.resolved.ref}; the turn was not dispatched` : `the remaining budget cannot afford the ${String(floor)} token output floor of ${target.resolved.ref}; the turn was not dispatched`);
+		if (zeroInputAffordable !== void 0 && zeroInputAffordable < floor) throw new BudgetExhaustedError(floor === 1 ? `the remaining budget cannot afford one output token from ${target.resolved.ref}; the turn was not dispatched` : `the remaining budget cannot afford the ${String(floor)} token output floor of ${target.resolved.ref}; the turn was not dispatched`, { data: { reason: "output-floor" } });
 		return {
 			...req,
 			maxOutputTokens: floor
@@ -12657,10 +12657,11 @@ async function runAgent(options) {
 		} catch (thrown) {
 			if (!(thrown instanceof BudgetExhaustedError)) throw thrown;
 			status = "error";
+			const typedReason = thrown.data?.reason;
 			agentError = {
 				kind: "budget",
 				retryable: false,
-				...thrown.data?.reason === "exposure-drained" ? { reason: "exposure-drained" } : {}
+				...typedReason === "exposure-drained" || typedReason === "output-floor" ? { reason: typedReason } : {}
 			};
 			errorMessage = thrown.message;
 			break;
@@ -14001,10 +14002,17 @@ var RunBudget = class {
 	* price rows as the layer-2b clamp) right before the wire call and
 	* releases at the attempt's settle, so the reservation lives exactly
 	* as long as the exposure it covers. The admission refuses, typed
-	* and without waiting, when spent + the named reserves (finalize and
-	* synthesis money is promised elsewhere) + live reservations + this
+	* and without waiting, when spent + live reservations + this
 	* estimate does not fit the cap; an exact fill admits, mirroring
-	* admitSpawn, and a full cap refuses even a zero estimate. A refusal
+	* admitSpawn, and a full cap refuses even a zero estimate. The tail
+	* reserves (finalize and synthesis) stay OUT of the sum (RV2101):
+	* the budget chain already fences them (remainingUsd subtracts the
+	* synthesis promise, and the finalize carve-out nets out of the
+	* orchestrator's own cap), so counting them here too made the cap
+	* bind at cap minus reserves while the actual wire risk was far
+	* below it: the fourth parity run's root was refused at spent
+	* 4.71 + reserve 1.00 against 5.70 with zero live estimates, one
+	* turn short of the synthesis the reserve existed to fund. A refusal
 	* is TRANSIENT (in-flight money returns at settle), so it never
 	* marks the run exhausted and never severs a stream. A model without
 	* a price row reserves zero, exactly as it debits zero (the
@@ -14028,8 +14036,8 @@ var RunBudget = class {
 		});
 		const estimateUsd = Number.isFinite(rawEstimate) && rawEstimate > 0 ? rawEstimate : 0;
 		const root = this.root;
-		const committed = root.spentUsd + root.finalizeReserveUsd + root.synthesisReserveUsd + this.inFlightExposureUsd;
-		if (committed >= cap || committed + estimateUsd > cap) throw new BudgetExhaustedError(`${IN_FLIGHT_EXPOSURE_REFUSAL_PREFIX}: spent ${root.spentUsd.toFixed(4)} USD plus reserves ${(root.finalizeReserveUsd + root.synthesisReserveUsd).toFixed(4)} USD plus live dispatch estimates ${this.inFlightExposureUsd.toFixed(4)} USD plus this turn's estimate ${estimateUsd.toFixed(4)} USD does not fit maxInFlightExposureUsd ${cap.toFixed(4)} USD; the dispatch was refused before any provider call`, { data: {
+		const committed = root.spentUsd + this.inFlightExposureUsd;
+		if (committed >= cap || committed + estimateUsd > cap) throw new BudgetExhaustedError(`${IN_FLIGHT_EXPOSURE_REFUSAL_PREFIX}: spent ${root.spentUsd.toFixed(4)} USD plus live dispatch estimates ${this.inFlightExposureUsd.toFixed(4)} USD plus this turn's estimate ${estimateUsd.toFixed(4)} USD does not fit maxInFlightExposureUsd ${cap.toFixed(4)} USD; the dispatch was refused before any provider call`, { data: {
 			reason: "in-flight-exposure",
 			capUsd: cap,
 			spentUsd: root.spentUsd,
@@ -18396,6 +18404,12 @@ function createCtx(internals, rootWorkflow) {
 				source: "in-flight-exposure",
 				reason: "in-flight-exposure"
 			} });
+			if (!internals.budget.exhausted && result.error?.kind === "budget" && result.error.reason === "output-floor" && result.errorMessage !== void 0) throw new BudgetExhaustedError(result.errorMessage, { data: {
+				scope: state.scope,
+				entryRef: terminal.seq,
+				source: "output-floor",
+				reason: "output-floor"
+			} });
 			const diagnostics = internals.budget.exhaustionDiagnostics(state.budgetScope ?? "run");
 			const crossed = diagnostics.crossed;
 			const rootSuffix = `run root: spent ${diagnostics.root.spentUsd.toFixed(4)}` + (diagnostics.root.ceilingUsd === void 0 ? " USD, no ceiling" : ` of ${diagnostics.root.ceilingUsd.toFixed(4)} USD`);
@@ -23884,7 +23898,8 @@ function makeOrchestratorWorkflow(goal, opts) {
 		try {
 			result = await runtime.runInScope(orchestratorState, () => ctx.agent(orchestratorPrompt(goal, opts?.maxSpawns, promptLines.length === 0 ? void 0 : promptLines), agentOpts));
 		} catch (thrown) {
-			if (!(thrown instanceof BudgetExhaustedError) || thrown.data?.reason !== "in-flight-exposure") throw thrown;
+			const budgetReason = thrown instanceof BudgetExhaustedError ? thrown.data?.reason : void 0;
+			if (budgetReason !== "in-flight-exposure" && budgetReason !== "output-floor") throw thrown;
 			const exposureKey = deriverV2.deriveKey({ kind: "orchestrator-exposure-fallback" });
 			if (!internals.replayer.snapshot().some((entry) => entry.kind === "decision" && entry.key === exposureKey)) await internals.replayer.appendSinglePhase({
 				scope: callingState.scope,
@@ -23895,7 +23910,7 @@ function makeOrchestratorWorkflow(goal, opts) {
 				site: "orchestrator-budget",
 				value: {
 					decisionType: "orchestrator_finalize_fallback",
-					reason: "exposure-abort",
+					reason: budgetReason === "output-floor" ? "budget-floor" : "exposure-abort",
 					turnsUsed: 0,
 					foldParams: {
 						planHash: "",
@@ -23904,12 +23919,24 @@ function makeOrchestratorWorkflow(goal, opts) {
 				}
 			});
 			internals.budget.markExhausted();
-			return {
+			const fold = {
 				forcedFinishFallback: true,
 				completion: "partial",
 				planHash: "",
 				completed: [...byOrdinal.values()].filter((record) => record.settled !== void 0).sort((a, b) => a.spawnOrdinal - b.spawnOrdinal).map((record) => digestOf(record, record.settled))
 			};
+			const synthesisReserveStillCommitted = orchestratorAccount !== void 0 && (internals.budget.accountView(orchestratorAccount)?.synthesisReserveUsd ?? 0) > 0;
+			const anySettled = [...byOrdinal.values()].some((record) => record.settled !== void 0);
+			if (opts?.synthesis !== void 0 && synthesisReserveStillCommitted && anySettled) try {
+				const synthesized = await runSynthesis(void 0);
+				return {
+					...fold,
+					result: synthesized
+				};
+			} catch {
+				return fold;
+			}
+			return fold;
 		}
 		const liveTermination = extensionTermination;
 		if (liveTermination !== void 0) throw liveTermination;
@@ -24932,6 +24959,13 @@ function preflightEstimate(input) {
 	const admitted = wave.filter((row) => row.admitted).length;
 	const denied = wave.length - admitted;
 	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({
+		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`
+	});
 	if (wave.length > 0 && denied > 0) {
 		const deniedLabels = wave.filter((row) => !row.admitted).map((row) => row.label);
 		if (admitted === 0) say({
@@ -24996,11 +25030,11 @@ function preflightEstimate(input) {
 		code: "in-flight-exposure-cap",
 		message: `RunOptions.maxInFlightExposureUsd ${exposureCapUsd.toFixed(4)} USD bounds spent money plus live dispatch estimates: a dispatch whose estimate does not fit is refused typed before the provider call, so the worst concurrent overshoot past the cap is the estimate error of the in-flight turns, not one whole turn per agent`
 	});
-	const requiredMinimumExposureUsd = overshootOneTurnFloorUsd === void 0 ? void 0 : reservedForFinalizationUsd + synthesisHoldUsd + overshootOneTurnFloorUsd;
-	if (exposureCapUsd !== void 0 && overshootOneTurnFloorUsd !== void 0 && requiredMinimumExposureUsd !== void 0 && requiredMinimumExposureUsd > exposureCapUsd) say({
+	const requiredMinimumExposureUsd = overshootOneTurnFloorUsd;
+	if (exposureCapUsd !== void 0 && requiredMinimumExposureUsd !== void 0 && requiredMinimumExposureUsd > exposureCapUsd) say({
 		severity: "warning",
 		code: "exposure-cap-tight",
-		message: `maxInFlightExposureUsd ${exposureCapUsd.toFixed(4)} USD sits below the declared wave's breathing floor ${requiredMinimumExposureUsd.toFixed(4)} USD (finalize + synthesis reserves ${(reservedForFinalizationUsd + synthesisHoldUsd).toFixed(4)} plus the ${String(pricedTurns.length)} most expensive concurrent turn floors ${overshootOneTurnFloorUsd.toFixed(4)}): a coordinating turn beside a full child wave will be refused pre-wire and park until a hold releases (RV1902); raise the cap to at least the floor to avoid the stall entirely`
+		message: `maxInFlightExposureUsd ${exposureCapUsd.toFixed(4)} USD sits below the declared wave's breathing floor ${requiredMinimumExposureUsd.toFixed(4)} USD (the ${String(pricedTurns.length)} most expensive concurrent turn floors): a coordinating turn beside a full child wave will be refused pre-wire and park until a hold releases (RV1902); raise the cap to at least the floor to avoid the stall entirely`
 	});
 	const quotaConfigured = engine.quota !== void 0;
 	if (!quotaConfigured && maxInFlight > 1 && units.length > 0) say({
@@ -25190,6 +25224,8 @@ function preflightEstimate(input) {
 			synthesisReserveUsd: synthesisHoldUsd,
 			...requiredMinimumCeilingUsd === void 0 ? {} : { requiredMinimumCeilingUsd },
 			...liveRootExposureTermUsd > 0 ? { liveRootExposureTermUsd } : {},
+			...reserveLineUsd === void 0 ? {} : { reserveLineUsd },
+			...reserveLineHeadroomUsd === void 0 ? {} : { reserveLineHeadroomUsd },
 			wave,
 			admitted,
 			denied

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/core",
-  "version": "1.211.0",
+  "version": "1.212.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",