@rulvar/core 1.86.0 → 1.87.0

package/dist/index.d.ts

@@ -3579,6 +3579,11 @@ interface ToolBudgetSummary {
   noticesFired?: number[];
   /** Present and true when the finalization reserve summary turn ran. */
   finalizationReserveUsed?: boolean;
+  /**
+  * Present and true when the finalization window activated at least
+  * once this invocation (RV302).
+  */
+  finalizationWindowEntered?: boolean;
   /** The tool budget limiter that ended the loop, on that 'limit' only. */
   limiter?: "maxToolCalls" | "toolUnits";
 }
@@ -3710,11 +3715,12 @@ type ToolEvents = {
   rule?: Json;
   advisory?: Json;
   /**
-  * Present when an exploration guard (RV-210), not the permission
-  * chain, denied the call: the outcome is 'denied' and the call was
-  * never dispatched.
+  * Present when an engine guard, not the permission chain, denied
+  * the call: the exploration guards (RV-210) or the finalization
+  * window (RV302). The outcome is 'denied' and the call was never
+  * dispatched.
   */
-  guard?: "repeated-signature";
+  guard?: "repeated-signature" | "per-tool-cap" | "finalization-window";
 };
 /**
 * Bare-nondeterminism detection (RV-209). Emitted LIVE by the segment
@@ -4106,6 +4112,27 @@ interface UsageLimits {
     minHeadroomUsd?: number; /** Default true: a grant needs new evidence since the last one. */
     requireNewEvidence?: boolean;
   };
+  /**
+  * The finalization window (RV302, the seventh comparison experiment):
+  * once the remaining tool budget (executed calls against the effective
+  * maxToolCalls, or remaining weighted units against toolUnits.max,
+  * whichever is closer) drops to `reserveCalls`, only finalization
+  * tools may execute. A call outside the window's allowlist receives a
+  * typed error tool result naming the window (visible to the model,
+  * never terminal, consuming no budget), and the model is told ONCE,
+  * via a plain user message, to record its evidence and finish. The
+  * allowlist defaults to the tools priced at toolUnits cost 0 (the
+  * free bookkeeping tools); the engine terminal tool is always
+  * admitted regardless. With toolBudgetExtension configured, remaining
+  * money converts into a grant BEFORE any window refusal, so the
+  * window binds only when the extension is exhausted or denied. Off by
+  * default: the refusals and the notice enter the conversation, so
+  * enabling it changes recorded model requests.
+  */
+  finalizationWindow?: {
+    /** How many trailing executed calls (or units) the window reserves. */reserveCalls: number; /** Tool names allowed inside the window; default: zero-cost tools. */
+    allow?: string[];
+  };
 }
 declare const DEFAULT_MAX_TURNS = 32;
 declare const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 12e4;
@@ -4135,6 +4162,10 @@ interface EffectiveUsageLimits {
     minHeadroomUsd?: number;
     requireNewEvidence?: boolean;
   };
+  finalizationWindow?: {
+    reserveCalls: number;
+    allow?: string[];
+  };
 }
 /**
 * Limits merge per spawn: AgentOpts.limits over profile limits over engine
@@ -9234,6 +9265,19 @@ interface PreflightOrchestratorSpec {
   */
   extension?: boolean;
   /**
+  * The OrchestrateAcceptance slice the estimator judges (RV305):
+  * declaring it lets preflight relate capped children to the salvage
+  * arms. Absent, the salvage findings stay silent, exactly like every
+  * other undeclared input.
+  */
+  acceptance?: {
+    childPolicy?: "all-ok" | {
+      minSuccessful: number;
+    };
+    acceptPartialChildren?: boolean;
+    acceptValidatedTerminalOutputOnLimit?: boolean;
+  };
+  /**
   * The separate synthesis invocation (RV-211), when the orchestration
   * configures one (the v1.71 experiment review: the run ceiling used
   * to stop at the coordination loop, undercounting the synthesis

package/dist/index.js

@@ -9023,6 +9023,8 @@ function mergeUsageLimits(call, profile, engine) {
 	if (finalizationReserve !== void 0) merged.finalizationReserve = finalizationReserve;
 	const toolBudgetExtension = pick("toolBudgetExtension");
 	if (toolBudgetExtension !== void 0) merged.toolBudgetExtension = toolBudgetExtension;
+	const finalizationWindow = pick("finalizationWindow");
+	if (finalizationWindow !== void 0) merged.finalizationWindow = finalizationWindow;
 	return merged;
 }
 /**
@@ -9077,6 +9079,16 @@ function validateUsageLimits(limits, site) {
 		if (minHeadroomUsd !== void 0 && (typeof minHeadroomUsd !== "number" || !Number.isFinite(minHeadroomUsd) || minHeadroomUsd < 0)) throw new ConfigError(`${site}.toolBudgetExtension.minHeadroomUsd must be a finite nonnegative USD amount, got ${typeof minHeadroomUsd === "number" ? String(minHeadroomUsd) : typeof minHeadroomUsd}`);
 		if (requireNewEvidence !== void 0 && typeof requireNewEvidence !== "boolean") throw new ConfigError(`${site}.toolBudgetExtension.requireNewEvidence must be a boolean; got ${typeof requireNewEvidence}`);
 	}
+	if (limits.finalizationWindow !== void 0) {
+		const window = limits.finalizationWindow;
+		if (typeof window !== "object" || window === null || Array.isArray(window)) throw new ConfigError(`${site}.finalizationWindow must be { reserveCalls, allow? }`);
+		const { reserveCalls, allow } = window;
+		requirePositiveInteger(reserveCalls, `${site}.finalizationWindow.reserveCalls`);
+		if (allow !== void 0) {
+			if (!Array.isArray(allow)) throw new ConfigError(`${site}.finalizationWindow.allow must be an array of tool names`);
+			for (const [index, name] of allow.entries()) if (typeof name !== "string" || name.length === 0) throw new ConfigError(`${site}.finalizationWindow.allow[${String(index)}] must be a nonempty tool name`);
+		}
+	}
 }
 //#endregion
 //#region src/model/failover.ts
@@ -9657,6 +9669,8 @@ const DEFAULT_MODEL_RETRY_ATTEMPTS = 2;
 */
 /** The docs anchor cited by guard denials and the guard abort. */
 const GUARD_DOCS_URL = "https://docs.rulvar.com/guide/agents#exploration-guards";
+/** The docs anchor cited by finalization window refusals (RV302). */
+const WINDOW_DOCS_URL = "https://docs.rulvar.com/guide/agents#the-finalization-window";
 /**
 * True when any exploration guard field asks for tracking. The tool
 * budget extension (RV301) counts too: its requireNewEvidence admission
@@ -9791,6 +9805,15 @@ var ExplorationGuard = class {
 		return this.config.toolUnits !== void 0 && this.unitsUsed >= this.config.toolUnits.max;
 	}
 	/**
+	* Weighted units still spendable, floored at zero; undefined without
+	* toolUnits configured. The finalization window (RV302) reads this on
+	* every call evaluation, so it stays an O(1) counter, unlike the
+	* allocating summary().
+	*/
+	unitsRemaining() {
+		return this.config.toolUnits === void 0 ? void 0 : Math.max(0, this.config.toolUnits.max - this.unitsUsed);
+	}
+	/**
 	* Distinct successful result digests seen this invocation: the
 	* extension's requireNewEvidence admission compares snapshots of this
 	* count (RV301). A result JCS cannot digest never counts, so a grant
@@ -9847,6 +9870,21 @@ function toolBudgetExtensionNoticeText(grant, maxExtensions, used, cap) {
 	const remaining = Math.max(0, cap - used);
 	return `Tool budget extended: grant ${String(grant)} of ${String(maxExtensions)}; ${String(used)} of ${String(cap)} tool calls used, ${String(remaining)} remaining. The budget headroom permits continued work; prioritize the highest value calls.`;
 }
+/**
+* The one-time model-visible window notice (RV302). Deterministic for
+* given counts, like the notices above.
+*/
+function finalizationWindowNoticeText(remaining, reserve, budget) {
+	return `Finalization window: ${String(Math.max(0, remaining))} of the reserved final ${String(reserve)} ${budget} remain. Only finalization tools (and the terminal tool) may execute now; record your evidence and finish with what you have.`;
+}
+/**
+* The typed window refusal a non-allowlisted call receives (RV302):
+* the same posture as the guard denials above, visible to the model,
+* never terminal, consuming no budget.
+*/
+function finalizationWindowRefusalText(name, reserve, budget) {
+	return `finalization window: the last ${String(reserve)} ${budget} are reserved for finalization tools, and '${name}' is not in the window allowlist. Record your evidence with the allowed tools and call the terminal tool (${WINDOW_DOCS_URL}).`;
+}
 //#endregion
 //#region src/runtime/no-progress.ts
 /**
@@ -10730,6 +10768,77 @@ async function runAgent(options) {
 			}]
 		});
 	};
+	/**
+	* The finalization window (RV302): once the remaining tool budget
+	* drops to reserveCalls, only the allowlisted finalization tools (and
+	* the always-admitted terminal tool) execute; everything else gets a
+	* typed refusal that consumes nothing. The run that motivated it
+	* recorded 10 of 14 evidence entries before the cap: one summary turn
+	* cannot dump a backlog, a reserved tail of bookkeeping calls can.
+	*/
+	const finalizationWindow = limits.finalizationWindow;
+	let windowEntered = false;
+	let windowNoticeFired = false;
+	const pendingWindowNotices = [];
+	/** The tightest remaining budget and which dimension provides it. */
+	const windowRemaining = () => {
+		let best;
+		const cap = effectiveMaxToolCalls();
+		if (cap !== void 0) best = {
+			remaining: Math.max(0, cap - toolCallsUsed),
+			budget: "tool calls"
+		};
+		const units = guard?.unitsRemaining();
+		if (units !== void 0 && (best === void 0 || units < best.remaining)) best = {
+			remaining: units,
+			budget: "tool units"
+		};
+		return best;
+	};
+	const windowActive = () => {
+		if (finalizationWindow === void 0) return;
+		const state = windowRemaining();
+		return state !== void 0 && state.remaining <= finalizationWindow.reserveCalls ? state : void 0;
+	};
+	/**
+	* Marks the entry and queues the one-time notice. Queued, not pushed:
+	* a user message may not interleave a tool batch, so the queue
+	* flushes with the other notices after the batch's results join the
+	* history. On resume the flags re-derive from the restored counts and
+	* the notice (already in the restored messages) never re-fires.
+	*/
+	const maybeMarkWindowEntry = () => {
+		if (finalizationWindow === void 0 || windowNoticeFired) return;
+		const state = windowActive();
+		if (state === void 0) return;
+		windowEntered = true;
+		windowNoticeFired = true;
+		pendingWindowNotices.push(finalizationWindowNoticeText(state.remaining, finalizationWindow.reserveCalls, state.budget));
+		events?.emit({
+			type: "log",
+			level: "info",
+			msg: `finalization window entered: ${String(state.remaining)} of the reserved final ${String(finalizationWindow.reserveCalls)} ${state.budget} remain`
+		});
+	};
+	const flushWindowNotices = () => {
+		for (const text of pendingWindowNotices.splice(0)) messages.push({
+			role: "user",
+			parts: [{
+				type: "text",
+				text
+			}]
+		});
+	};
+	/**
+	* The window allowlist. The terminal and escalate tools never reach
+	* this check: the dispatch walk intercepts both before the window
+	* block, so the exits are structurally exempt rather than listed.
+	*/
+	const windowAllows = (name) => {
+		const allow = finalizationWindow?.allow;
+		if (allow !== void 0) return allow.includes(name);
+		return limits.toolUnits?.costs?.[name] === 0;
+	};
 	const modelRetryCounts = /* @__PURE__ */ new Map();
 	let lastTurnUsage = {
 		inputTokens: 0,
@@ -10766,6 +10875,10 @@ async function runAgent(options) {
 			extensionGrants = Math.min(extension.maxExtensions, Math.ceil((toolCallsUsed - limits.maxToolCalls) / extension.increment));
 			extensionEvidenceAtLastGrant = guard?.evidenceCount() ?? 0;
 		}
+		if (windowActive() !== void 0) {
+			windowEntered = true;
+			windowNoticeFired = true;
+		}
 	}
 	const usageSlices = () => [...usageByPhaseModel.values()].map(({ role, servedBy: sliceServedBy, usage }) => ({
 		servedBy: sliceServedBy,
@@ -11044,6 +11157,27 @@ async function runAgent(options) {
 					finished: finishArgs.result ?? null
 				};
 			}
+			if (finalizationWindow !== void 0) {
+				maybeMarkWindowEntry();
+				let windowState = windowActive();
+				if (windowState !== void 0 && !windowAllows(gatedCall.name)) {
+					if (windowState.budget === "tool calls" && extension !== void 0 && windowState.remaining + extension.increment > finalizationWindow.reserveCalls && tryToolBudgetGrant()) windowState = windowActive();
+					if (windowState !== void 0 && !windowAllows(gatedCall.name)) {
+						events?.emit({
+							type: "tool:end",
+							toolName: gatedCall.name,
+							outcome: "denied",
+							durationMs: now() - gateStartedAt,
+							guard: "finalization-window"
+						});
+						parts.push(errorPart(call, {
+							error: finalizationWindowRefusalText(gatedCall.name, finalizationWindow.reserveCalls, windowState.budget),
+							guard: "finalization-window"
+						}));
+						continue;
+					}
+				}
+			}
 			if (guard !== void 0) {
 				const guardVerdict = guard.beforeExecute(gatedCall.name, gatedCall.args);
 				if (guardVerdict.deny) {
@@ -11082,6 +11216,7 @@ async function runAgent(options) {
 				};
 			}
 		}
+		maybeMarkWindowEntry();
 		return {
 			parts,
 			limitHit: false
@@ -11133,6 +11268,7 @@ async function runAgent(options) {
 			}
 		} else {
 			flushExtensionNotices();
+			flushWindowNotices();
 			maybePushBudgetNotice();
 			await saveBoundary();
 		}
@@ -11598,6 +11734,7 @@ async function runAgent(options) {
 				break;
 			}
 			flushExtensionNotices();
+			flushWindowNotices();
 			maybePushBudgetNotice();
 			if (options.summarize !== void 0 && !compactionDisabled && shouldCompact({
 				lastTurnUsage,
@@ -12159,6 +12296,7 @@ async function runAgent(options) {
 		if (extension !== void 0) toolBudget.extensionsGranted = extensionGrants;
 		if (firedNotices.size > 0) toolBudget.noticesFired = [...firedNotices].sort((a, b) => a - b);
 		if (reserveSummaryRan) toolBudget.finalizationReserveUsed = true;
+		if (windowEntered) toolBudget.finalizationWindowEntered = true;
 		if (limitLimiter !== void 0) toolBudget.limiter = limitLimiter;
 		result.toolBudget = toolBudget;
 	}
@@ -17810,6 +17948,18 @@ function makeOrchestratorWorkflow(goal, opts) {
 		* run falls back to the draft under a journaled decision and a warn
 		* log, never silently.
 		*/
+		/**
+		* The reserve lifecycle snapshot (RV304 second half, the seventh
+		* comparison experiment review, P1.7): configured is the declared
+		* hold, held what actually registered on the cap account (zero when
+		* no cap resolved and the config was silently inert), released
+		* what the synthesis dispatch freed, remainingBeforeSynthesisUsd
+		* the chain headroom the invocation saw right after the release,
+		* and consumedUsd its own priced spend. Frozen into a journaled
+		* decision at first completion, so a resume reports the identical
+		* facts; absent everywhere when no reserve is configured.
+		*/
+		let synthesisReserveLifecycle;
 		const runSynthesis = async (draft) => {
 			const spec = opts?.synthesis;
 			if (spec === void 0) return draft;
@@ -17872,11 +18022,14 @@ function makeOrchestratorWorkflow(goal, opts) {
 					...repeatedClaims === void 0 ? {} : { repeatedClaims: repeatedClaims.length }
 				}
 			}, callingState.spanId);
+			const configuredReserveUsd = opts?.budget?.synthesisReserveUsd ?? 0;
+			const heldReserveUsd = orchestratorAccount === void 0 ? 0 : internals.budget.accountView(orchestratorAccount)?.synthesisReserveUsd ?? 0;
 			const synthesisState = { ...callingState };
 			if (orchestratorAccount !== void 0) {
 				synthesisState.budgetScope = orchestratorAccount;
 				internals.budget.releaseSynthesisReserve(orchestratorAccount);
 			}
+			const remainingBeforeSynthesisUsd = configuredReserveUsd > 0 ? internals.budget.remainingUsd(orchestratorAccount ?? callingState.budgetScope ?? void 0) : void 0;
 			const synthesisBreak = validationSpec === void 0 ? void 0 : validationAbort.signal;
 			if (synthesisBreak !== void 0) synthesisState.signal = callingState.signal === void 0 ? synthesisBreak : AbortSignal.any([callingState.signal, synthesisBreak]);
 			const synthesisOpts = {
@@ -17899,6 +18052,46 @@ function makeOrchestratorWorkflow(goal, opts) {
 			synthesisSchemaRejectedExchanges = synthesized.schemaRejectedTerminalExchanges ?? 0;
 			synthesisSchemaRecoveredExchanges = synthesized.schemaRecoveredTerminalExchanges ?? 0;
 			if (validationTermination !== void 0) throw validationTermination;
+			if (configuredReserveUsd > 0) {
+				const reserveKey = "synthesis-reserve-lifecycle";
+				const prior = internals.replayer.snapshot().find((entry) => entry.kind === "decision" && entry.scope === callingState.scope && entry.key === reserveKey);
+				if (prior !== void 0) {
+					const frozen = prior.value;
+					synthesisReserveLifecycle = {
+						configuredUsd: frozen.configuredUsd,
+						heldUsd: frozen.heldUsd,
+						releasedUsd: frozen.releasedUsd,
+						...frozen.remainingBeforeSynthesisUsd === void 0 ? {} : { remainingBeforeSynthesisUsd: frozen.remainingBeforeSynthesisUsd },
+						...frozen.consumedUsd === void 0 ? {} : { consumedUsd: frozen.consumedUsd }
+					};
+				} else {
+					synthesisReserveLifecycle = {
+						configuredUsd: configuredReserveUsd,
+						heldUsd: heldReserveUsd,
+						releasedUsd: heldReserveUsd,
+						...remainingBeforeSynthesisUsd === void 0 ? {} : { remainingBeforeSynthesisUsd },
+						consumedUsd: synthesized.costUsd
+					};
+					await internals.replayer.appendSinglePhase({
+						scope: callingState.scope,
+						key: reserveKey,
+						kind: "decision",
+						status: "ok",
+						spanId: internals.spans.mint(callingState.spanId),
+						site: "orchestrator-synthesis-reserve",
+						value: {
+							decisionType: "orchestrator_synthesis_reserve",
+							...synthesisReserveLifecycle
+						}
+					});
+				}
+				internals.events.emit({
+					type: "log",
+					level: "info",
+					msg: "orchestrator synthesis reserve lifecycle",
+					data: { ...synthesisReserveLifecycle }
+				}, callingState.spanId);
+			}
 			if (synthesized.status === "ok") return synthesized.output;
 			if (validationSpec !== void 0) throw new FailRunError(`the synthesis invocation terminated with status '${synthesized.status}'` + (synthesized.errorMessage === void 0 ? "" : `: ${synthesized.errorMessage}`) + "; finish validators are configured, so the unvalidated draft cannot stand", { data: {
 				source: "orchestrator_synthesis",
@@ -18109,7 +18302,8 @@ function makeOrchestratorWorkflow(goal, opts) {
 			degradedReasons: decision.degradedReasons,
 			...decision.salvagedPartialChildren === void 0 ? {} : { salvagedPartialChildren: decision.salvagedPartialChildren },
 			...decision.salvagedTerminalOutputChildren === void 0 ? {} : { salvagedTerminalOutputChildren: decision.salvagedTerminalOutputChildren },
-			...envelopeSchemaRecovered === 0 ? {} : { schemaRecoveredFinishExchanges: envelopeSchemaRecovered }
+			...envelopeSchemaRecovered === 0 ? {} : { schemaRecoveredFinishExchanges: envelopeSchemaRecovered },
+			...synthesisReserveLifecycle === void 0 ? {} : { synthesisReserve: synthesisReserveLifecycle }
 		};
 	});
 }
@@ -18337,6 +18531,8 @@ function preflightEstimate(input) {
 	const waveGateInputs = [];
 	const units = [];
 	const shapes = [];
+	/** Whether any declared spawn caps its tool budget (RV305). */
+	let anyCappedSpawn = false;
 	for (const spec of spawnSpecs) {
 		const role = spec.role ?? "loop";
 		const label = spec.label ?? role;
@@ -18460,6 +18656,37 @@ function preflightEstimate(input) {
 			message: `spawn '${label}' sets toolBudgetNotices without maxToolCalls: the notices never fire`,
 			spawn: label
 		});
+		if (limits.finalizationWindow !== void 0) if (limits.maxToolCalls === void 0 && limits.toolUnits === void 0) say({
+			severity: "warning",
+			code: "inert-finalization-window",
+			message: `spawn '${label}' sets finalizationWindow without maxToolCalls or toolUnits: no tool budget exists for the window to reserve a tail of`,
+			spawn: label
+		});
+		else {
+			const reserve = limits.finalizationWindow.reserveCalls;
+			const windowCallCap = extendedMaxToolCalls(limits);
+			const unitsMax = limits.toolUnits?.max;
+			if (windowCallCap !== void 0 && reserve >= windowCallCap || unitsMax !== void 0 && reserve >= unitsMax) say({
+				severity: "warning",
+				code: "finalization-window-covers-cap",
+				message: `spawn '${label}': finalizationWindow.reserveCalls ${String(reserve)} is not below the tool budget, so the window governs from the very first call and nothing but the allowlisted finalization tools ever executes`,
+				spawn: label
+			});
+			if (limits.finalizationWindow.allow !== void 0 && limits.finalizationWindow.allow.length === 0) say({
+				severity: "warning",
+				code: "finalization-window-empty-allowlist",
+				message: `spawn '${label}': finalizationWindow.allow is empty, so inside the window only the engine terminal tool (when one exists) remains callable and every other call is refused`,
+				spawn: label
+			});
+		}
+		const positiveCallCap = limits.maxToolCalls !== void 0 && limits.maxToolCalls > 0;
+		if ((positiveCallCap || limits.toolUnits !== void 0) && limits.toolBudgetNotices !== true && limits.finalizationReserve === void 0 && limits.toolBudgetExtension === void 0 && limits.finalizationWindow === void 0) say({
+			severity: "warning",
+			code: "bare-tool-cap",
+			message: `spawn '${label}' caps its tool budget (${positiveCallCap ? `maxToolCalls ${String(limits.maxToolCalls)}` : `toolUnits.max ${String(limits.toolUnits?.max ?? 0)}`}) with no softener: no toolBudgetNotices, no toolBudgetExtension, no finalizationReserve, no finalizationWindow. Expiry is a silent hard 'limit' the model never saw coming; enable a notice or a reserve, or drop the cap and rely on the USD ceiling`,
+			spawn: label
+		});
+		if (positiveCallCap || limits.toolUnits !== void 0) anyCappedSpawn = true;
 		if (unpriced && ceilingUsd !== void 0) say({
 			severity: "warning",
 			code: "unpriced-under-ceiling",
@@ -18519,6 +18746,12 @@ function preflightEstimate(input) {
 	}
 	let orchestratorReserveUsd;
 	if (input.orchestrator !== void 0) {
+		const acceptance = input.orchestrator.acceptance;
+		if (acceptance !== void 0 && anyCappedSpawn && acceptance.acceptPartialChildren !== true && acceptance.acceptValidatedTerminalOutputOnLimit !== true) say({
+			severity: "info",
+			code: "capped-children-without-salvage",
+			message: "children in the declared wave cap their tool budgets and the declared acceptance policy enables no salvage arm (acceptPartialChildren, acceptValidatedTerminalOutputOnLimit): a child that expires settles limit and counts against the policy with nothing to salvage"
+		});
 		const servedBy = resolveServing(defaults.routing?.orchestrate);
 		if (servedBy === void 0) say({
 			severity: "error",

package/package.json

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