@rulvar/core 1.219.0 → 1.221.0

package/dist/index.d.ts

@@ -2162,7 +2162,15 @@ type CoreEvents = {
       ran: boolean;
       reason?: string;
     };
-  }; /** Children accepted through validated terminal output salvage on 'limit'; same lift. */
+  };
+  /**
+  * The claim-consistency pass meta, lifted from the same envelope
+  * (or typed error data) when it carries a valid object (RV2203);
+  * `judgeDeclined` rides here on the failed terminals that used to
+  * read null while the journal held the verdict.
+  */
+  claimConsistencyMeta?: Record<string, unknown>; /** The synthesis-skip marker from the same envelope; same lift (RV2203). */
+  synthesisSkipped?: boolean | string; /** Children accepted through validated terminal output salvage on 'limit'; same lift. */
   salvagedTerminalOutputChildren?: string[];
   /**
   * Children that settled 'ok' below their declared evidence floor
@@ -11305,6 +11313,15 @@ type RunOutcome<R> = {
   salvagedPartialChildren?: string[]; /** The explicit semantic pass summaries (RV1906); same lift and posture. */
   semanticPasses?: SemanticPassesSummary;
   /**
+  * The claim-consistency pass meta (`judgeInvoked`, `judgeDeclined`,
+  * the pair counts), lifted from the same envelope or typed error
+  * data (RV2203). The RV2106 mirror run journaled its declined judge
+  * and the error terminal carried null: the truth now rides every
+  * terminal that has it, ok and failed alike.
+  */
+  claimConsistencyMeta?: Record<string, unknown>; /** The synthesis-skip marker from the same envelope; same lift and posture (RV2203). */
+  synthesisSkipped?: boolean | string;
+  /**
   * Children accepted through validated terminal output salvage on
   * 'limit'; same lift and posture.
   */

package/dist/index.js

@@ -12604,6 +12604,102 @@ async function runAgent(options) {
 		resolved: options.resolved
 	}, ...options.fallbacks ?? []];
 	const loopCursor = { index: 0 };
+	/**
+	* The drained-finalization grant (RV2204, the third parity rerun).
+	* The exposure drain is terminal mid-work: spend only grows, so a
+	* seat refused with no live holder left can never dispatch an
+	* ordinary turn again. The third parity rerun killed three workers
+	* ~30 turns into research with evidence pools of 17 and 22 under a
+	* floor of 24 and a CONFIGURED finalization window: the drain came
+	* before the window, and the window's play needs the very wire the
+	* drain refuses. With `limits.finalizationReserve.maxOutputTokens`
+	* declared, a drained seat that already did work now spends ONE
+	* clamped finalization turn before its typed terminal: the output
+	* clamp shrinks the turn's exposure estimate (the full estimate was
+	* refused; the clamped one prices the summary allowance instead of
+	* the whole per-turn cap), the finalization-window allowlist rides
+	* as the turn's only tools so outstanding record_evidence calls can
+	* land in parallel, and the executed calls persist through the
+	* ordinary tool machinery. Best effort, exactly like the tool-budget
+	* reserve turn: a refusal of even the clamped estimate warns and
+	* keeps the typed drained terminal; a seat with NO completed turns
+	* keeps dying free (the RV2002 zero-cost doctrine: nothing to
+	* summarize, nothing paid).
+	*/
+	let drainFinalizationRan = false;
+	const runDrainFinalization = async (refusal) => {
+		const allow = limits.finalizationWindow?.allow;
+		const allowedTools = allow === void 0 ? void 0 : options.tools?.contracts.filter((contract) => allow.includes(contract.name));
+		const toolsRide = allowedTools !== void 0 && allowedTools.length > 0;
+		const drainMessages = [...messages, {
+			role: "user",
+			parts: [{
+				type: "text",
+				text: `The run's in-flight exposure pool is drained; no further ordinary turns can dispatch (${refusal}). This is your single finalization turn` + (toolsRide ? ": record any outstanding evidence with the allowed tools IN THIS turn (parallel calls), then close" : `: close`) + ` with your best final summary of the work already done.`
+			}]
+		}];
+		let grant;
+		try {
+			grant = await dispatchPhase({
+				role: primaryRole,
+				chain: loopChain,
+				cursor: loopCursor,
+				requestFor: (target) => {
+					let req = buildRequest(target.resolved, projectHistory(drainMessages, providerOf(target.adapter)), limits, toolsRide ? allowedTools : void 0);
+					const reserveMax = limits.finalizationReserve?.maxOutputTokens;
+					if (reserveMax !== void 0) req = {
+						...req,
+						maxOutputTokens: Math.min(req.maxOutputTokens ?? reserveMax, reserveMax)
+					};
+					req = applyCachePolicy(req, target, options.cache);
+					return applyOutputBudget(req, target, options.budget);
+				},
+				streamOptionsFor: (target) => {
+					const drainStreamOptions = {
+						idleTimeoutMs: limits.streamIdleTimeoutMs,
+						signals: options.signal === void 0 ? [] : [options.signal],
+						onUsage: (delta) => options.budget?.onUsage(delta, target.resolved.ref)
+					};
+					if (options.budget?.signal !== void 0) drainStreamOptions.budgetSignal = options.budget.signal;
+					if (options.stream === true) drainStreamOptions.onDelta = (delta) => events?.emit({
+						type: "agent:stream",
+						delta
+					});
+					return drainStreamOptions;
+				}
+			});
+		} catch (grantThrown) {
+			if (!(grantThrown instanceof BudgetExhaustedError)) throw grantThrown;
+			events?.emit({
+				type: "log",
+				level: "warn",
+				msg: `the drained-finalization turn was skipped: ${grantThrown.message}`
+			});
+			return;
+		}
+		const { outcome: grantOutcome, target: grantTarget } = grant;
+		servedBy = grantTarget.resolved.ref;
+		usageApprox = usageApprox || grantOutcome.usageApprox;
+		messages.push(assistantMsg(grantOutcome.turn, liftRetainedParts(grantOutcome.providerMetadata, grantTarget.adapter)));
+		if (toolsRide && grantOutcome.turn.toolCalls.length > 0) try {
+			await runToolCalls(grantOutcome.turn.toolCalls, []);
+		} catch (toolThrown) {
+			events?.emit({
+				type: "log",
+				level: "warn",
+				msg: `a drained-finalization tool call failed: ${toolThrown instanceof Error ? toolThrown.message : String(toolThrown)}`
+			});
+		}
+		events?.emit({
+			type: "log",
+			level: "info",
+			msg: "the drained seat spent its finalization turn",
+			data: {
+				toolCalls: grantOutcome.turn.toolCalls.length,
+				outputTokens: grantOutcome.usage.outputTokens
+			}
+		});
+	};
 	loop: while (status === "ok" && !finishedViaTool) {
 		if (limits.timeoutMs !== void 0 && now() - startedAt >= limits.timeoutMs) {
 			status = "limit";
@@ -12657,8 +12753,12 @@ async function runAgent(options) {
 			});
 		} catch (thrown) {
 			if (!(thrown instanceof BudgetExhaustedError)) throw thrown;
-			status = "error";
 			const typedReason = thrown.data?.reason;
+			if (typedReason === "exposure-drained" && limits.finalizationReserve !== void 0 && turns > 1 && !drainFinalizationRan) {
+				drainFinalizationRan = true;
+				await runDrainFinalization(thrown.message);
+			}
+			status = "error";
 			agentError = {
 				kind: "budget",
 				retryable: false,
@@ -24100,7 +24200,41 @@ function makeOrchestratorWorkflow(goal, opts) {
 				}
 			});
 		};
+		/**
+		* The pass summaries as one builder (RV2203): the ok envelope and
+		* the failure enrichment must tell the same {ran, reason} story,
+		* with only the synthesis arm differing by path.
+		*/
+		const semanticPassesSummary = (synthesis) => ({
+			contradictions: opts?.contradictions === void 0 ? {
+				ran: false,
+				reason: "not-configured"
+			} : contradictionsFound === void 0 ? {
+				ran: false,
+				reason: "not-run"
+			} : { ran: true },
+			claimConsistency: opts?.claimConsistency === void 0 ? {
+				ran: false,
+				reason: "not-configured"
+			} : claimConsistencyMeta === void 0 ? {
+				ran: false,
+				reason: "not-run"
+			} : { ran: true },
+			synthesis
+		});
 		const enrichSynthesisFailure = (thrown, snapshot) => {
+			const passTruth = {
+				...claimConsistencyMeta === void 0 ? {} : { claimConsistencyMeta },
+				semanticPasses: semanticPassesSummary({
+					ran: false,
+					reason: "synthesis-failed"
+				})
+			};
+			if (thrown instanceof BudgetExhaustedError) throw new BudgetExhaustedError(thrown.message, { data: {
+				...thrown.data ?? {},
+				...snapshot ?? {},
+				...passTruth
+			} });
 			if (!(thrown instanceof FailRunError)) throw thrown;
 			const base = thrown.data ?? {};
 			const spent = validationDecisions().filter((candidate) => candidate.verdict !== "accepted" && contractGenerationCurrent(candidate));
@@ -24110,6 +24244,7 @@ function makeOrchestratorWorkflow(goal, opts) {
 			throw new FailRunError(thrown.message, { data: {
 				...base,
 				...snapshot ?? {},
+				...passTruth,
 				...spent.length === 0 || base.repairsUsed !== void 0 ? {} : {
 					repairsUsed: spent.length,
 					maxRepairs: validationSpec?.maxRepairs ?? 1,
@@ -24368,29 +24503,13 @@ function makeOrchestratorWorkflow(goal, opts) {
 				...claimFindingsFound === void 0 ? {} : { claimContradictions: claimFindingsFound },
 				claimConsistencyMeta
 			},
-			semanticPasses: {
-				contradictions: opts?.contradictions === void 0 ? {
-					ran: false,
-					reason: "not-configured"
-				} : contradictionsFound === void 0 ? {
-					ran: false,
-					reason: "not-run"
-				} : { ran: true },
-				claimConsistency: opts?.claimConsistency === void 0 ? {
-					ran: false,
-					reason: "not-configured"
-				} : claimConsistencyMeta === void 0 ? {
-					ran: false,
-					reason: "not-run"
-				} : { ran: true },
-				synthesis: opts?.synthesis === void 0 ? {
-					ran: false,
-					reason: "not-configured"
-				} : synthesisSkippedByValidDraft ? {
-					ran: false,
-					reason: "valid-draft"
-				} : { ran: true }
-			}
+			semanticPasses: semanticPassesSummary(opts?.synthesis === void 0 ? {
+				ran: false,
+				reason: "not-configured"
+			} : synthesisSkippedByValidDraft ? {
+				ran: false,
+				reason: "valid-draft"
+			} : { ran: true })
 		};
 	};
 	return defineWorkflow({ name: ORCHESTRATE_WORKFLOW_NAME }, async (ctx) => {
@@ -24773,10 +24892,16 @@ function preflightEstimate(input) {
 				spawn: label
 			});
 		}
-		if (limits.finalizationReserve !== void 0 && limits.maxToolCalls === void 0 && limits.toolUnits === void 0) say({
+		if (limits.finalizationReserve !== void 0 && limits.maxToolCalls === void 0 && limits.toolUnits === void 0 && input.run?.maxInFlightExposureUsd === void 0) say({
 			severity: "warning",
 			code: "inert-finalization-reserve",
-			message: `spawn '${label}' sets finalizationReserve without maxToolCalls or toolUnits: no tool budget limiter exists for it to fire on`,
+			message: `spawn '${label}' sets finalizationReserve without maxToolCalls or toolUnits: no tool budget limiter exists for it to fire on, and no in-flight exposure cap is declared for the drained-finalization grant (RV2204) to spend it at`,
+			spawn: label
+		});
+		if (limits.finalizationWindow !== void 0 && limits.finalizationReserve?.maxOutputTokens === void 0 && input.run?.maxInFlightExposureUsd !== void 0) say({
+			severity: "info",
+			code: "drained-finalization-unfunded",
+			message: `spawn '${label}' declares finalizationWindow under an in-flight exposure cap but no finalizationReserve.maxOutputTokens: a mid-work exposure drain refuses the wire the window needs, and without the reserve's clamped turn the seat dies with its window unplayed (RV2204); declare the reserve to fund one drained-finalization turn`,
 			spawn: label
 		});
 		if (limits.toolBudgetNotices === true && limits.maxToolCalls === void 0) say({
@@ -26026,6 +26151,10 @@ function liftRunCompletion(candidate) {
 			synthesis: { ...synthesis }
 		};
 	}
+	const metaCandidate = candidate.claimConsistencyMeta;
+	if (typeof metaCandidate === "object" && metaCandidate !== null && !Array.isArray(metaCandidate)) lifted.claimConsistencyMeta = { ...metaCandidate };
+	const skippedCandidate = candidate.synthesisSkipped;
+	if (typeof skippedCandidate === "boolean" || typeof skippedCandidate === "string") lifted.synthesisSkipped = skippedCandidate;
 	return lifted;
 }
 /**
@@ -26576,7 +26705,8 @@ function createEngine(options) {
 			};
 			if (value !== void 0 && (status === "ok" || status === "exhausted")) outcomeFacts.value = value;
 			if (wireError !== void 0) outcomeFacts.error = wireError;
-			const lifted = liftRunCompletion(status === "ok" || status === "exhausted" ? outcomeFacts.value : status === "error" ? wireError?.data : void 0);
+			let lifted = liftRunCompletion(status === "ok" || status === "exhausted" ? outcomeFacts.value : status === "error" ? wireError?.data : void 0);
+			if (lifted === void 0 && status === "exhausted") lifted = liftRunCompletion(wireError?.data);
 			if (lifted !== void 0) {
 				outcomeFacts.completion = lifted.completion;
 				if (lifted.childStatusCounts !== void 0) outcomeFacts.childStatusCounts = lifted.childStatusCounts;
@@ -26586,6 +26716,8 @@ function createEngine(options) {
 				if (lifted.belowFloorOkChildren !== void 0) outcomeFacts.belowFloorOkChildren = lifted.belowFloorOkChildren;
 				if (lifted.acceptanceChildren !== void 0) outcomeFacts.acceptanceChildren = lifted.acceptanceChildren;
 				if (lifted.semanticPasses !== void 0) outcomeFacts.semanticPasses = lifted.semanticPasses;
+				if (lifted.claimConsistencyMeta !== void 0) outcomeFacts.claimConsistencyMeta = lifted.claimConsistencyMeta;
+				if (lifted.synthesisSkipped !== void 0) outcomeFacts.synthesisSkipped = lifted.synthesisSkipped;
 			}
 			let settlementFailure;
 			let supersededBy;

package/package.json

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