@rulvar/core 1.193.0 → 1.195.0

package/dist/index.d.ts

@@ -2389,6 +2389,16 @@ type AgentEvents = {
   reason?: string;
   retryAfterMs?: number;
   willRetry: true;
+} | {
+  type: "budget:exposure-wait";
+  agentType: string;
+  label?: string; /** The refused model ref. */
+  model?: string; /** The refusal arithmetic, verbatim from the typed refusal. */
+  capUsd?: number;
+  spentUsd?: number;
+  inFlightUsd?: number;
+  estimateUsd?: number;
+  willWait: boolean;
 } | {
   type: "agent:schema-retry";
   agentType: string;
@@ -5107,6 +5117,16 @@ interface BudgetHooks {
   */
   assertPricedDispatch?: (servedBy: ModelRef) => void;
   admitTurnExposure?: (servedBy: ModelRef, estimatedInputTokens: number, plannedOutputTokens: number) => (() => void) | undefined;
+  /**
+  * Parks until the next in-flight exposure hold releases (RV1902):
+  * 'released' on that wake, 'drained' immediately when no hold is
+  * live, 'aborted' when the signal fires first. Wired beside
+  * admitTurnExposure when the cap is configured; consumed only by
+  * invocations that opted into the exposure wait.
+  */
+  awaitExposureRelease?: (signal?: AbortSignal) => Promise<"released" | "drained" | "aborted">;
+  /** Live in-flight exposure currently held by open dispatches (RV1902). */
+  liveExposureUsd?: () => number;
   /** Live usage accounting; layer 3 may respond by aborting `signal`. */
   onUsage(usage: Usage, servedBy: ModelRef): void;
   /**
@@ -5391,6 +5411,15 @@ interface RunAgentOptions<S extends SchemaSpec = JsonSchema> {
   /** Host or sibling cancellation. */
   signal?: AbortSignal;
   budget?: BudgetHooks;
+  /**
+  * The exposure-wait posture (RV1902): an in-flight exposure refusal
+  * on this invocation parks until a live hold releases and retries
+  * pre-wire, instead of settling a budget error. Set only by the
+  * orchestrate-owned root dispatches (the coordination loop, the
+  * synthesis invocation, the forced-finish wake), whose settle would
+  * tear down the run its own admitted children are still funding.
+  */
+  exposureWait?: boolean;
   events?: RuntimeEventSink;
   transcript?: {
     mintRef(): string;
@@ -6094,6 +6123,13 @@ declare class RunBudget {
   private exhaustedInternal;
   /** Live dispatch estimates held by reserveTurnExposure (RV711). */
   private inFlightExposureUsd;
+  /**
+  * Waiters parked on the next exposure release (RV1902): the
+  * orchestrate root's dispatch waits out a transient refusal here
+  * instead of settling a budget error. Notified (and self-removed)
+  * on every hold release; never on spend, which only grows.
+  */
+  private readonly exposureWaiters;
   /** Models already warned about; the warning fires once per model per run. */
   private readonly unpricedWarned;
   /** Models whose price function already returned an invalid USD once. */
@@ -6308,6 +6344,19 @@ declare class RunBudget {
   * lifetime reserve and its own turn exposure would double-count.
   */
   reserveTurnExposure(servedBy: ModelRef, estimatedInputTokens: number, plannedOutputTokens: number): (() => void) | undefined;
+  /** Live in-flight exposure currently held by open dispatches (RV1902). */
+  get liveExposureUsd(): number;
+  /**
+  * Parks until the NEXT in-flight exposure hold releases (RV1902):
+  * resolves 'released' on that wake, 'drained' immediately when no
+  * hold is live (there is nothing to wait out, so the caller's refusal
+  * is terminal for its turn), and 'aborted' when the signal fires
+  * first. The waiter registers BEFORE any check, so a release racing
+  * the caller's refusal is never lost; spend never shrinks, so
+  * releases are the only wake source that can turn a refusal into a
+  * fit.
+  */
+  awaitExposureRelease(signal?: AbortSignal): Promise<"released" | "drained" | "aborted">;
   /** Layer 2: the per-turn guard. A turn that would cross any ceiling in the chain is not dispatched. */
   beforeTurn(accountScope?: string): void;
   /**
@@ -7241,8 +7290,12 @@ interface RunOptions {
   * settles, and the dispatch whose estimate does not fit
   * spent + finalize/synthesis reserves + live estimates is refused
   * with a typed BudgetExhaustedError (data.reason
-  * 'in-flight-exposure') instead of waiting; the refused agent
-  * settles as a budget error. Worst concurrent overshoot past the cap
+  * 'in-flight-exposure'). A plain agent settles the refusal as a
+  * budget error; an orchestrate-owned root dispatch waits it out
+  * (RV1902): it parks until a live hold releases, retries pre-wire,
+  * and emits budget:exposure-wait, while a drained refusal settles
+  * the documented forced-finish partial instead of tearing the run
+  * down. Worst concurrent overshoot past the cap
   * is thereby the estimate error of the in-flight turns, not one
   * whole turn per agent. Absent by default: wire traffic, journals,
   * and hooks stay byte-identical. Recorded in RunMeta at genesis
@@ -9276,6 +9329,23 @@ interface OrchestrateOptions {
   /** The opt in child completion policy; see {@link OrchestrateAcceptance}. */
   acceptance?: OrchestrateAcceptance;
   /**
+  * 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.
+  */
+  onUnsettledAtExit?: "cancel" | "drain";
+  /**
   * The opt in deterministic host validation of the finish result, with
   * bounded repair; see {@link FinishValidationSpec}.
   */

package/dist/index.js

@@ -12308,10 +12308,33 @@ async function runAgent(options) {
 					return dispatchWithQuota(options.quota);
 				};
 				let outcome;
-				try {
-					outcome = await (options.providerSlot === void 0 ? dispatch() : options.providerSlot(target.adapter.id, dispatch, options.signal));
-				} finally {
-					releaseExposure?.();
+				for (;;) {
+					try {
+						outcome = await (options.providerSlot === void 0 ? dispatch() : options.providerSlot(target.adapter.id, dispatch, options.signal));
+					} catch (thrown) {
+						const refusalData = thrown instanceof BudgetExhaustedError ? thrown.data : void 0;
+						const awaitRelease = options.budget?.awaitExposureRelease;
+						if (options.exposureWait !== true || refusalData?.reason !== "in-flight-exposure" || awaitRelease === void 0) throw thrown;
+						const willWait = (options.budget?.liveExposureUsd?.() ?? 0) > 0;
+						events?.emit({
+							type: "budget:exposure-wait",
+							agentType,
+							label: options.label,
+							model: target.resolved.ref,
+							...typeof refusalData.capUsd === "number" ? { capUsd: refusalData.capUsd } : {},
+							...typeof refusalData.spentUsd === "number" ? { spentUsd: refusalData.spentUsd } : {},
+							...typeof refusalData.inFlightUsd === "number" ? { inFlightUsd: refusalData.inFlightUsd } : {},
+							...typeof refusalData.estimateUsd === "number" ? { estimateUsd: refusalData.estimateUsd } : {},
+							willWait
+						});
+						if (!willWait) throw thrown;
+						const waitSignals = [options.signal, options.budget?.signal].filter((candidate) => candidate !== void 0);
+						await awaitRelease(waitSignals.length === 0 ? void 0 : AbortSignal.any(waitSignals));
+						continue;
+					} finally {
+						releaseExposure?.();
+					}
+					break;
 				}
 				if (reservationId !== void 0 && options.quota !== void 0) {
 					const rawWireCount = (outcome.providerMetadata?.[target.adapter.id])?.wireRequests?.count;
@@ -13445,6 +13468,13 @@ var RunBudget = class {
 	exhaustedInternal = false;
 	/** Live dispatch estimates held by reserveTurnExposure (RV711). */
 	inFlightExposureUsd = 0;
+	/**
+	* Waiters parked on the next exposure release (RV1902): the
+	* orchestrate root's dispatch waits out a transient refusal here
+	* instead of settling a budget error. Notified (and self-removed)
+	* on every hold release; never on spend, which only grows.
+	*/
+	exposureWaiters = /* @__PURE__ */ new Set();
 	/** Models already warned about; the warning fires once per model per run. */
 	unpricedWarned = /* @__PURE__ */ new Set();
 	/** Models whose price function already returned an invalid USD once. */
@@ -13862,8 +13892,42 @@ var RunBudget = class {
 			if (released) return;
 			released = true;
 			this.inFlightExposureUsd = Math.max(0, this.inFlightExposureUsd - estimateUsd);
+			for (const waiter of [...this.exposureWaiters]) waiter();
 		};
 	}
+	/** Live in-flight exposure currently held by open dispatches (RV1902). */
+	get liveExposureUsd() {
+		return this.inFlightExposureUsd;
+	}
+	/**
+	* Parks until the NEXT in-flight exposure hold releases (RV1902):
+	* resolves 'released' on that wake, 'drained' immediately when no
+	* hold is live (there is nothing to wait out, so the caller's refusal
+	* is terminal for its turn), and 'aborted' when the signal fires
+	* first. The waiter registers BEFORE any check, so a release racing
+	* the caller's refusal is never lost; spend never shrinks, so
+	* releases are the only wake source that can turn a refusal into a
+	* fit.
+	*/
+	awaitExposureRelease(signal) {
+		if (signal?.aborted === true) return Promise.resolve("aborted");
+		if (this.inFlightExposureUsd <= 0) return Promise.resolve("drained");
+		return new Promise((resolve) => {
+			const settle = (outcome) => {
+				this.exposureWaiters.delete(waiter);
+				signal?.removeEventListener("abort", onAbort);
+				resolve(outcome);
+			};
+			const waiter = () => {
+				settle("released");
+			};
+			const onAbort = () => {
+				settle("aborted");
+			};
+			this.exposureWaiters.add(waiter);
+			signal?.addEventListener("abort", onAbort, { once: true });
+		});
+	}
 	/** Layer 2: the per-turn guard. A turn that would cross any ceiling in the chain is not dispatched. */
 	beforeTurn(accountScope = "run") {
 		for (const account of this.chainOf(accountScope)) if (account.ceilingUsd !== void 0 && account.spentUsd >= account.ceilingUsd) {
@@ -16270,6 +16334,19 @@ const kBootCheckpoint = Symbol("rulvar.bootCheckpoint");
 * attribution so the journal fold reproduces reserveUsedUsd.
 */
 const kFinalizeReserve = Symbol("rulvar.finalizeReserve");
+/**
+* Internal AgentOpts channel (RV1902): marks an orchestrate-owned root
+* dispatch (the coordination loop, the synthesis invocation, the
+* forced-finish wake) as one that WAITS OUT a transient in-flight
+* exposure refusal instead of settling a budget error. The four-role
+* benchmark's recovery arm died exactly there: the refusal is transient
+* by contract (budgets guide), but the refused agent was the workflow's
+* coordinating root, so its settle tore down the whole run while four
+* admitted children were still finalizing. Never part of the public
+* AgentOpts surface; plain agents keep the documented settle-as-budget-
+* error behavior, because their caller can catch and decide.
+*/
+const kExposureWait = Symbol("rulvar.exposureWait");
 /** Typed accessor used by the in-package consumers. */
 function runtimeOf(ctx) {
 	const runtime = ctxRuntimes.get(ctx);
@@ -17607,7 +17684,11 @@ function createCtx(internals, rootWorkflow) {
 				maxAffordableOutputTokens: (servedBy, estimatedInputTokens) => internals.budget.maxAffordableOutputTokens(servedBy, estimatedInputTokens, budgetAccount),
 				remainingUsd: () => internals.budget.remainingUsd(budgetAccount),
 				...internals.budget.strictPricing === void 0 ? {} : { assertPricedDispatch: (servedBy) => internals.budget.assertPricedDispatch(servedBy) },
-				...internals.budget.maxInFlightExposureUsd === void 0 ? {} : { admitTurnExposure: (servedBy, estimatedInputTokens, plannedOutputTokens) => internals.budget.reserveTurnExposure(servedBy, estimatedInputTokens, plannedOutputTokens) },
+				...internals.budget.maxInFlightExposureUsd === void 0 ? {} : {
+					admitTurnExposure: (servedBy, estimatedInputTokens, plannedOutputTokens) => internals.budget.reserveTurnExposure(servedBy, estimatedInputTokens, plannedOutputTokens),
+					awaitExposureRelease: (signal) => internals.budget.awaitExposureRelease(signal),
+					liveExposureUsd: () => internals.budget.liveExposureUsd
+				},
 				onUsage: (usage, servedBy) => internals.budget.onUsage(usage, servedBy, budgetAccount),
 				openCallMeter: (servedBy) => internals.budget.openCallMeter(servedBy, budgetAccount),
 				signal: budgetAccount === "run" ? internals.budget.signal : AbortSignal.any([internals.budget.signal, internals.budget.signalOf(budgetAccount)].filter((signal) => signal !== void 0))
@@ -17621,6 +17702,7 @@ function createCtx(internals, rootWorkflow) {
 		if (escalation !== void 0) runAgentOptions.escalation = { minSpendUsd: escalation.minSpendUsd ?? 0 };
 		const terminalTool = opts[kTerminalTool];
 		if (terminalTool !== void 0) runAgentOptions.terminalTool = terminalTool;
+		if (opts[kExposureWait] === true) runAgentOptions.exposureWait = true;
 		runAgentOptions.checkpoint = checkpointPlumbing;
 		if (opts.schema !== void 0) runAgentOptions.schema = opts.schema;
 		if (canonicalSchema !== void 0) runAgentOptions.canonicalSchema = canonicalSchema;
@@ -20658,6 +20740,7 @@ function validateOrchestrateOptions(opts) {
 	if (opts === void 0) return;
 	if (opts.maxSpawns !== void 0) requireNonNegativeInteger(opts.maxSpawns, "orchestrate maxSpawns");
 	if (opts.renderBudgetChars !== void 0) requireNonNegativeInteger(opts.renderBudgetChars, "orchestrate renderBudgetChars");
+	if (opts.onUnsettledAtExit !== void 0 && opts.onUnsettledAtExit !== "cancel" && opts.onUnsettledAtExit !== "drain") throw new ConfigError(`orchestrate onUnsettledAtExit must be 'cancel' or 'drain'; got ${String(opts.onUnsettledAtExit)}`);
 	if (opts.acceptance !== void 0) {
 		const policy = opts.acceptance.childPolicy;
 		const minSuccessful = typeof policy === "object" && policy !== null && !Array.isArray(policy) ? policy.minSuccessful : void 0;
@@ -20969,7 +21052,7 @@ function filterProfiles(registered, names) {
 */
 function makeOrchestratorWorkflow(goal, opts) {
 	validateOrchestrateOptions(opts);
-	return defineWorkflow({ name: ORCHESTRATE_WORKFLOW_NAME }, async (ctx) => {
+	const orchestrationBody = async (ctx, barrier) => {
 		const runtime = runtimeOf(ctx);
 		const { internals } = runtime;
 		if (internals.admission === void 0) throw new ConfigError("orchestrate requires the engine run context (createEngine)");
@@ -21070,6 +21153,28 @@ function makeOrchestratorWorkflow(goal, opts) {
 		const byOrdinal = /* @__PURE__ */ new Map();
 		const rejectedByOrdinal = /* @__PURE__ */ new Map();
 		/**
+		* The terminal child barrier (RV1903): every exit of this
+		* orchestration, returned or thrown, passes through the finally
+		* below, so a child still running when the verdict froze reaches a
+		* journaled terminal BEFORE the workflow settles. The benchmark's
+		* recovery journal recorded run_settle at sequence 18 and three
+		* child terminals at 19..21; the returned outcome, the terminal
+		* invoice and the event snapshot all disagreed with the final
+		* journal. 'cancel' (default) aborts the stragglers and awaits
+		* their cancelled terminals; 'drain' awaits their natural
+		* terminals, bounded by their own limits. The frozen verdict is
+		* journaled before the barrier runs, so late children never change
+		* it; result promises never reject (SpawnRecord contract), so the
+		* barrier never masks the exit's own error.
+		*/
+		const exitBarrier = async () => {
+			const live = [...byOrdinal.values()].filter((record) => record.settled === void 0);
+			if (live.length === 0) return;
+			if ((opts?.onUnsettledAtExit ?? "cancel") === "cancel") for (const record of live) record.abort();
+			await Promise.allSettled(live.map((record) => record.result));
+		};
+		barrier.run = exitBarrier;
+		/**
 		* The journaled spec behind each recovered ordinal: the idempotent
 		* re-execution guard compares it against the incoming call, because
 		* after a cross-attempt resume a REGENERATED turn (the boundary
@@ -22235,6 +22340,7 @@ function makeOrchestratorWorkflow(goal, opts) {
 			role: "orchestrate",
 			result: "full",
 			tools,
+			[kExposureWait]: true,
 			...capState === void 0 ? {} : { estCost: orchestratorAdmissionEstCostUsd(capState.effectiveCapUsd, orchestratorAccount === void 0 ? 0 : (internals.budget.accountView(orchestratorAccount)?.finalizeReserveUsd ?? 0) + (internals.budget.accountView(orchestratorAccount)?.synthesisReserveUsd ?? 0)) },
 			...opts?.model === void 0 ? {} : { model: opts.model },
 			...opts?.limits === void 0 ? {} : { limits: opts.limits },
@@ -22293,11 +22399,13 @@ function makeOrchestratorWorkflow(goal, opts) {
 			const fallbackKey = deriverV2.deriveKey({ kind: "orchestrator-finalize-fallback" });
 			const priorFallback = internals.replayer.snapshot().find((entry) => entry.kind === "decision" && entry.key === fallbackKey);
 			const priorFinalize = internals.replayer.snapshot().filter((entry) => entry.kind === "agent" && entry.scope === callingState.scope && entry.seq > (capDecisionRef ?? -1) && entry.status !== "running" && entry.costAttribution?.finalizeReserve === true).at(-1);
+			const finalizeTurns = capState?.finalizeTurns ?? 2;
 			const finalOpts = {
 				role: "orchestrate",
 				result: "full",
 				tools: finishOnly,
-				limits: { maxTurns: capState?.finalizeTurns ?? 2 },
+				[kExposureWait]: true,
+				limits: { maxTurns: finalizeTurns },
 				...capState === void 0 ? {} : { estCost: capState.finalizeReserveUsd },
 				...opts?.model === void 0 ? {} : { model: opts.model },
 				[kTerminalTool]: {
@@ -23202,6 +23310,7 @@ function makeOrchestratorWorkflow(goal, opts) {
 				role: "synthesize",
 				result: "full",
 				tools: synthesisTools,
+				[kExposureWait]: true,
 				limits: spec.limits ?? { maxTurns: 4 },
 				...spec.model === void 0 ? {} : { model: spec.model },
 				...spec.effort === void 0 ? {} : { effort: spec.effort },
@@ -23340,7 +23449,37 @@ function makeOrchestratorWorkflow(goal, opts) {
 			...finishValidationPromptLines(validationSpec, coordSectionalFinish ? "rejected-attempt" : void 0),
 			...acceptancePromptLines(opts?.acceptance)
 		];
-		const result = await runtime.runInScope(orchestratorState, () => ctx.agent(orchestratorPrompt(goal, opts?.maxSpawns, promptLines.length === 0 ? void 0 : promptLines), agentOpts));
+		let result;
+		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 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,
+				key: exposureKey,
+				kind: "decision",
+				status: "ok",
+				spanId: internals.spans.mint(callingState.spanId),
+				site: "orchestrator-budget",
+				value: {
+					decisionType: "orchestrator_finalize_fallback",
+					reason: "exposure-abort",
+					turnsUsed: 0,
+					foldParams: {
+						planHash: "",
+						digestOrdinalMax: wakeOrdinal
+					}
+				}
+			});
+			internals.budget.markExhausted();
+			return {
+				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 liveTermination = extensionTermination;
 		if (liveTermination !== void 0) throw liveTermination;
 		if (capDecisionRef !== void 0) return await settleCapOutcome();
@@ -23594,6 +23733,14 @@ function makeOrchestratorWorkflow(goal, opts) {
 				claimConsistencyMeta
 			}
 		};
+	};
+	return defineWorkflow({ name: ORCHESTRATE_WORKFLOW_NAME }, async (ctx) => {
+		const barrier = {};
+		try {
+			return await orchestrationBody(ctx, barrier);
+		} finally {
+			await barrier.run?.();
+		}
 	});
 }
 /**

package/package.json

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