@rulvar/core 1.113.0 → 1.114.0

package/dist/index.d.ts

@@ -3130,6 +3130,17 @@ declare const QUOTA_WINDOW_MS = 6e4;
 * from each of them. The counters are rule-scoped: one rule matching
 * two models pools them under one cap; write one rule per model for
 * per-model buckets.
+*
+* Window semantics, named as the deliberate compromise it is (RV708):
+* every PerMinute cap counts over FIXED epoch-aligned 60 s windows
+* ({@link QUOTA_WINDOW_MS}), not a sliding minute. Each fixed window
+* enforces its cap exactly, and a burst placed astride a boundary can
+* therefore consume up to TWO caps inside one sliding 60 s; that
+* bounded burst is the price of cross-process parity (every reference
+* limiter in every process computes the same window from the same
+* clock with no shared sliding state), and provider-side minute
+* windows are themselves fuzzy. Size caps with the boundary burst in
+* mind; the semantics are pinned as intended, not scheduled to change.
 */
 interface QuotaRule {
   /** Adapter id, as in `concurrency.perProvider` keys. */
@@ -4761,6 +4772,18 @@ interface RunAgentOptions<S extends SchemaSpec = JsonSchema> {
     fallbacks?: PhaseTarget[];
   };
   /**
+  * Opt-in policy-facts digest (RV709): when true AND a finalize
+  * invocation fires, one additional REQUEST-ONLY user message
+  * precedes the synthesis instruction, carrying the deterministic
+  * runtime facts the loop observed (quota denials and recoveries,
+  * tool budget pressure, the finalization window, recorded spend with
+  * its cost basis), so the final model can cite the run's own live
+  * evidence instead of underclaiming it. Never touches the durable
+  * transcript, never enters spawn identity; unset keeps the finalize
+  * request byte identical.
+  */
+  policyFacts?: boolean;
+  /**
   * Summarize invocation target for compaction (M4-T03): resolved
   * through the chain with role 'summarize', falling back to the loop
   * model when routing resolves nothing. Compaction
@@ -7962,6 +7985,18 @@ interface OrchestrateSynthesis {
   /** Extra deterministic instruction lines appended to the synthesis prompt. */
   instructions?: string;
   /**
+  * Opt-in policy-facts line in the 'single' synthesis prompt (RV709):
+  * a deterministic digest of the settled children's durable
+  * tool-budget facts (statuses, extension grants, finalization
+  * windows and reserves), so the composing model can cite the run's
+  * own observed evidence instead of underclaiming it. Folded ONLY
+  * from replay-stable material (the settled results the journal
+  * replays verbatim), so a resumed synthesis re-derives identical
+  * prompt bytes; off by default, and the prompt stays byte identical
+  * when unset (prompt bytes are journal identity).
+  */
+  policyFacts?: boolean;
+  /**
   * Admission estimate for the synthesize invocation, like
   * AgentOpts.estCost: under a tight orchestrator cap the default
   * reserve (full maxOutputTokens pricing) can refuse the dispatch; an

package/dist/index.js

@@ -11113,6 +11113,8 @@ async function runAgent(options) {
 	let invocationCounter = 0;
 	let transportRetries = 0;
 	let schemaRecoveredTerminalExchanges = 0;
+	let quotaDenials = 0;
+	let quotaRecoveries = 0;
 	const rateLimitObservations = /* @__PURE__ */ new Map();
 	const roleUsageSnapshot = (role) => {
 		const snapshot = /* @__PURE__ */ new Map();
@@ -12012,6 +12014,7 @@ async function runAgent(options) {
 		}
 	};
 	const dispatchPhase = async (site) => {
+		let deniedEpisode = false;
 		for (;;) {
 			const target = site.chain[site.cursor.index] ?? site.chain[0];
 			let tries = 0;
@@ -12083,6 +12086,13 @@ async function runAgent(options) {
 						msg: `the shared quota limiter failed to reconcile a reservation: ${detail}`
 					});
 				}
+				if (outcome.quotaDenied === true) {
+					quotaDenials += 1;
+					deniedEpisode = true;
+				} else if (deniedEpisode && outcome.neverDispatched !== true) {
+					quotaRecoveries += 1;
+					deniedEpisode = false;
+				}
 				if (outcome.quotaDenied !== true && outcome.neverDispatched !== true) {
 					const accounted = recordUsage(outcome.usage, outcome.reported, target.adapter.id, target.resolved.ref, site.role, outcome.usageViolation);
 					const namespace = outcome.providerMetadata?.[target.adapter.id];
@@ -12685,13 +12695,37 @@ async function runAgent(options) {
 		}
 		if (proceed) {
 			turns += 1;
-			const synthesisMessages = [...messages, {
-				role: "user",
-				parts: [{
-					type: "text",
-					text: FINALIZE_SYNTHESIS_INSTRUCTION
-				}]
-			}];
+			const policyFactsLines = () => {
+				const lines = ["POLICY FACTS (request-only runtime digest): deterministic facts this run observed; cite the ones your answer relies on."];
+				if (options.quota !== void 0) lines.push(`quota: ${String(quotaDenials)} denial(s), ${String(quotaRecoveries)} recovered`);
+				if (limits.maxToolCalls !== void 0 || limits.toolUnits !== void 0 || extension !== void 0) {
+					const cap = effectiveMaxToolCalls();
+					let budgetLine = `tool budget: ${String(toolCallsUsed)}${cap === void 0 ? "" : ` of ${String(cap)}`} calls used`;
+					if (extension !== void 0) budgetLine += `; extensions granted: ${String(extensionGrants)}`;
+					lines.push(budgetLine);
+				}
+				if (finalizationWindow !== void 0) lines.push(`finalization window: ${windowEntered ? "entered" : "not entered"}`);
+				const spend = recordedSpend();
+				lines.push(`recorded spend: $${spend.usd.toFixed(4)} (${spend.basis})` + (spend.basis === "aggregate-estimate" ? "; per-call records did not cover all usage, treat the number as an estimate" : ""));
+				return lines;
+			};
+			const synthesisMessages = [
+				...messages,
+				...options.policyFacts === true ? [{
+					role: "user",
+					parts: [{
+						type: "text",
+						text: policyFactsLines().join("\n")
+					}]
+				}] : [],
+				{
+					role: "user",
+					parts: [{
+						type: "text",
+						text: FINALIZE_SYNTHESIS_INSTRUCTION
+					}]
+				}
+			];
 			let finalizeDispatch;
 			try {
 				finalizeDispatch = await dispatchPhase({
@@ -17384,6 +17418,8 @@ function validateOrchestrateOptions(opts) {
 		].includes(synthesis.effort)) throw new ConfigError(`orchestrate synthesis.effort must be one of 'low' | 'medium' | 'high' | 'xhigh' | 'max'; got ${JSON.stringify(synthesis.effort)}`);
 		if (synthesis.limits !== void 0) validateUsageLimits(synthesis.limits, "orchestrate synthesis.limits");
 		if (synthesis.instructions !== void 0 && typeof synthesis.instructions !== "string") throw new ConfigError(`orchestrate synthesis.instructions must be a string; got ${typeof synthesis.instructions}`);
+		const facts = synthesis;
+		if (facts.policyFacts !== void 0 && typeof facts.policyFacts !== "boolean") throw new ConfigError(`orchestrate synthesis.policyFacts must be a boolean; got ${typeof facts.policyFacts}`);
 		if (synthesis.estCost !== void 0) requireNonNegativeNumber(synthesis.estCost, "orchestrate synthesis.estCost");
 	}
 	const spec = opts.budget;
@@ -18922,6 +18958,26 @@ function makeOrchestratorWorkflow(goal, opts) {
 				...repeatedClaims === void 0 ? [] : ["Repeated claims across children were deduplicated before this prompt: only the first occurrence of each repeated line remains in the digest, and the REPEATED CLAIMS index below lists each one with its reporters."],
 				...spec.instructions === void 0 ? [] : [spec.instructions],
 				...finishValidationPromptLines(validationSpec),
+				...spec.policyFacts === true ? [(() => {
+					const byStatus = {};
+					let extensionsGranted = 0;
+					let windowsEntered = 0;
+					let reservesUsed = 0;
+					for (const [, record] of settledEntries) {
+						const settled = record.settled;
+						byStatus[settled.status] = (byStatus[settled.status] ?? 0) + 1;
+						extensionsGranted += settled.toolBudget?.extensionsGranted ?? 0;
+						if (settled.toolBudget?.finalizationWindowEntered === true) windowsEntered += 1;
+						if (settled.toolBudget?.finalizationReserveUsed === true) reservesUsed += 1;
+					}
+					return `POLICY FACTS: ${JSON.stringify({
+						children: settledEntries.length,
+						byStatus: Object.fromEntries(Object.keys(byStatus).sort().map((status) => [status, byStatus[status]])),
+						extensionsGranted,
+						finalizationWindowsEntered: windowsEntered,
+						finalizationReservesUsed: reservesUsed
+					})}`;
+				})()] : [],
 				`GOAL: ${goal}`,
 				`DRAFT: ${draftJson}`,
 				`DIGEST: ${digestJson}`,

package/package.json

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