@rulvar/core 1.72.0 → 1.73.0

package/dist/index.d.ts

@@ -4405,6 +4405,18 @@ interface RunAgentOptions<S extends SchemaSpec = JsonSchema> {
       ok: false;
       feedback: Record<string, unknown>;
     }>;
+    /**
+    * The repair reserve (the v1.71 experiment review, P0.4): max EXTRA
+    * turns the loop may grant past limits.maxTurns, one per rejected
+    * terminal-tool exchange, schema-invalid arguments and host
+    * validation rejections alike. The grant count derives from the
+    * message window itself (error tool results named after the
+    * terminal tool, clamped to the reserve), so a resumed segment that
+    * restored the window mid-exchange re-derives the same grants and
+    * nothing needs journaling. Zero (or absent) keeps the ceiling
+    * byte identical to the pre 1.73 loop.
+    */
+    repairTurnReserve?: number;
   };
   agentType?: string;
   /** The primary invocation role of the tool loop; default 'loop' (M6-T05; RV-211 adds synthesize). */
@@ -7038,6 +7050,23 @@ interface FinishValidationSpec {
   */
   maxRepairs?: number;
   /**
+  * The repair turn reserve (the v1.71 experiment review, P0.4; the
+  * reserve RV-204 deliberately deferred). A nonnegative integer,
+  * default 0: max EXTRA turns the invocation the validators bind (the
+  * synthesis invocation when `synthesis` is configured, the
+  * coordination loop otherwise) may consume past its `maxTurns`, one
+  * granted per rejected finish exchange, schema-invalid finish
+  * arguments and host validation rejections alike. Without it, repair
+  * exchanges and generation compete for the same turn budget: the
+  * v1.71 experiment lost its whole run to one malformed finish plus
+  * one validator rejection inside maxTurns 3. The reserve is bounded,
+  * spends from the ordinary budget ceilings (a granted turn is a paid
+  * provider turn), and folds into the preflight turn projection
+  * (`projectedProviderTurns` and the run ceiling) when declared
+  * there. Zero keeps the pre 1.73 ceiling byte identical.
+  */
+  repairTurnReserve?: number;
+  /**
   * The unified output contract this validator set enforces (the v1.71
   * experiment review, P0.1/P0.2). Construction then runs the golden
   * self test with the contract's fixtures as defaults, the contract's
@@ -8749,6 +8778,23 @@ interface PreflightOrchestratorSpec {
   * root, so only they subtract it from spawn-admission headroom.
   */
   extension?: 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
+  * turns). `limits` mirrors OrchestrateSynthesis.limits exactly
+  * (absent = the DEFAULT_SYNTHESIS_MAX_TURNS invocation), `model`
+  * mirrors its model override (absent = defaults.routing.synthesize),
+  * and `estInputTokens` is the prompt-size stand-in for the derived
+  * synthesis prompt. When `finishValidation.repairTurnReserve` is
+  * declared, the reserve folds into THIS invocation's projected turns,
+  * because the validators bind the synthesis finish.
+  */
+  synthesis?: {
+    model?: ModelSpec;
+    limits?: UsageLimits;
+    estInputTokens?: number;
+  };
 }
 /** The full input: engine surface, run surface, and the declared wave. */
 interface PreflightInput {
@@ -8780,6 +8826,15 @@ interface PreflightInput {
     validators: FinishValidator[];
     contract?: FinishContract;
     selfTest?: FinishSelfTestFixtures;
+    /**
+    * Mirrors FinishValidationSpec.repairTurnReserve: folds the
+    * declared repair headroom into the projected turns of the
+    * invocation the validators bind (the synthesis invocation when
+    * orchestrator.synthesis is declared, the coordination loop
+    * otherwise), so the run ceiling prices the repair exchange the
+    * runtime would actually grant.
+    */
+    repairTurnReserve?: number;
   };
 }
 /** One linter verdict; `spawn` names the wave entry it is about. */
@@ -8861,6 +8916,16 @@ interface PreflightReport {
       finalizeTurns: number; /** Whether the finalize reserve is committed against the run root (extension runs). */
       reserveCommitted: boolean; /** The orchestrator agent's own loop ceiling, derived exactly like a spawn's. */
       projectedProviderTurns: number;
+      /**
+      * The separate synthesis invocation's projection, present when
+      * input.orchestrator.synthesis was declared and the role
+      * resolves: its turn ceiling (the repair turn reserve folded in
+      * when declared) and its serving model.
+      */
+      synthesis?: {
+        projectedProviderTurns: number;
+        servedBy?: ModelRef;
+      };
     };
   };
   quota: {

package/dist/index.js

@@ -11087,7 +11087,9 @@ async function runAgent(options) {
 			status = "limit";
 			break;
 		}
-		if (turns >= limits.maxTurns) {
+		const repairReserve = options.terminalTool?.repairTurnReserve ?? 0;
+		const grantedRepairTurns = repairReserve === 0 ? 0 : Math.min(repairReserve, messages.reduce((count, message) => count + message.parts.filter((part) => part.type === "tool-result" && part.name === options.terminalTool?.name && part.isError === true).length, 0));
+		if (turns >= limits.maxTurns + grantedRepairTurns) {
 			status = "limit";
 			break;
 		}
@@ -15651,6 +15653,7 @@ function validateOrchestrateOptions(opts) {
 			seen.add(validator.name);
 		}
 		if (fv.maxRepairs !== void 0) requireNonNegativeInteger(fv.maxRepairs, "orchestrate finishValidation.maxRepairs");
+		if (fv.repairTurnReserve !== void 0) requireNonNegativeInteger(fv.repairTurnReserve, "orchestrate finishValidation.repairTurnReserve");
 		const contract = fv.contract;
 		if (contract !== void 0) {
 			const shape = contract;
@@ -16756,7 +16759,10 @@ function makeOrchestratorWorkflow(goal, opts) {
 			},
 			[kTerminalTool]: {
 				name: FINISH_TOOL_NAME,
-				...validationSpec === void 0 || opts?.synthesis !== void 0 ? {} : { validate: validateFinish }
+				...validationSpec === void 0 || opts?.synthesis !== void 0 ? {} : {
+					validate: validateFinish,
+					...validationSpec.repairTurnReserve === void 0 ? {} : { repairTurnReserve: validationSpec.repairTurnReserve }
+				}
 			},
 			...(() => {
 				const priorCancelledRoot = internals.replayer.snapshot().filter((entry) => entry.kind === "agent" && entry.scope === callingState.scope && entry.status === "cancelled" && entry.checkpointRef !== void 0).at(-1);
@@ -17056,7 +17062,10 @@ function makeOrchestratorWorkflow(goal, opts) {
 				...spec.estCost === void 0 ? {} : { estCost: spec.estCost },
 				[kTerminalTool]: {
 					name: FINISH_TOOL_NAME,
-					...validationSpec === void 0 ? {} : { validate: validateFinish }
+					...validationSpec === void 0 ? {} : {
+						validate: validateFinish,
+						...validationSpec.repairTurnReserve === void 0 ? {} : { repairTurnReserve: validationSpec.repairTurnReserve }
+					}
 				}
 			};
 			const synthesized = await runtime.runInScope(synthesisState, () => ctx.agent(prompt, synthesisOpts));
@@ -17136,7 +17145,40 @@ function makeOrchestratorWorkflow(goal, opts) {
 		if (validationTermination !== void 0) throw validationTermination;
 		if (orchestratorAccount !== void 0) internals.cost.orchestrator.spentUsd = internals.budget.accountView(orchestratorAccount)?.spentUsd ?? 0;
 		if (result.status !== "ok") throw new ConfigError(`the orchestrator agent terminated with status '${result.status}'` + (result.errorMessage === void 0 ? "" : `: ${result.errorMessage}`));
-		if (opts?.acceptance === void 0) return await runSynthesis(result.output);
+		/**
+		* The synthesis failure enrichment (the v1.71 experiment review,
+		* P0.8 remainder + P1.7): every typed failure a synthesis
+		* invocation throws gains the verdict-derived repair taxonomy read
+		* from the JOURNALED validation decisions (identical live and on
+		* replay), and, when an acceptance verdict exists, the acceptance
+		* snapshot the children already earned; the completion mirror then
+		* lifts completion and childStatusCounts onto the error outcome,
+		* exactly like the acceptance rejection path. The experiment's
+		* outcome showed completion null beside four accepted children;
+		* these are the fields that say "the fan-out work is complete, the
+		* failure is downstream". The rejection-past-the-bound error keeps
+		* its own repairsUsed/maxRepairs/failed untouched.
+		*/
+		const enrichSynthesisFailure = (thrown, snapshot) => {
+			if (!(thrown instanceof FailRunError)) throw thrown;
+			const base = thrown.data ?? {};
+			const spent = validationDecisions().filter((candidate) => candidate.verdict !== "accepted");
+			const rejectedValidators = [...new Set(spent.flatMap((candidate) => candidate.failed.map((f) => f.name)))];
+			throw new FailRunError(thrown.message, { data: {
+				...base,
+				...snapshot ?? {},
+				...spent.length === 0 || base.repairsUsed !== void 0 ? {} : {
+					repairsUsed: spent.length,
+					maxRepairs: validationSpec?.maxRepairs ?? 1,
+					rejectedValidators
+				}
+			} });
+		};
+		if (opts?.acceptance === void 0) try {
+			return await runSynthesis(result.output);
+		} catch (thrown) {
+			return enrichSynthesisFailure(thrown);
+		}
 		const acceptanceKey = "acceptance";
 		const priorAcceptance = internals.replayer.snapshot().find((entry) => entry.kind === "decision" && entry.scope === callingState.scope && entry.key === acceptanceKey);
 		let decision;
@@ -17209,8 +17251,17 @@ function makeOrchestratorWorkflow(goal, opts) {
 				...decision.synthesisSkipped === void 0 ? {} : { synthesisSkipped: decision.synthesisSkipped }
 			} });
 		}
+		let synthesizedFinal;
+		try {
+			synthesizedFinal = await runSynthesis(result.output);
+		} catch (thrown) {
+			enrichSynthesisFailure(thrown, {
+				completion: decision.completion,
+				childStatusCounts: decision.childStatusCounts
+			});
+		}
 		return {
-			result: await runSynthesis(result.output),
+			result: synthesizedFinal,
 			completion: decision.completion,
 			childStatusCounts: decision.childStatusCounts,
 			degradedReasons: decision.degradedReasons,
@@ -17351,6 +17402,8 @@ function preflightEstimate(input) {
 	const maxDepth = engine.budgetDefaults?.maxDepth ?? 1;
 	const perRun = engine.concurrency?.perRun ?? 12;
 	const runLimits = mergeUsageLimits(void 0, input.run?.limits, defaults.limits);
+	const finishRepairReserve = input.finishValidation?.repairTurnReserve ?? 0;
+	const coordinationRepairReserve = input.orchestrator?.synthesis === void 0 ? finishRepairReserve : 0;
 	let orchestratorEcho;
 	let reservedForFinalizationUsd = 0;
 	let effectiveCapUsd;
@@ -17371,7 +17424,7 @@ function preflightEstimate(input) {
 			finalizeReserveUsd,
 			finalizeTurns,
 			reserveCommitted,
-			projectedProviderTurns: projectedProviderTurnsOf(echoLimits, overallExecutedCeiling(echoLimits, toolCeilingsOf(echoLimits)))
+			projectedProviderTurns: projectedProviderTurnsOf(echoLimits, overallExecutedCeiling(echoLimits, toolCeilingsOf(echoLimits))) + coordinationRepairReserve
 		};
 		if (spec?.capUsd !== void 0 && spec.capFraction === void 0 && effectiveCapUsd !== void 0 && effectiveCapUsd < spec.capUsd) say({
 			severity: "warning",
@@ -17589,7 +17642,7 @@ function preflightEstimate(input) {
 				model,
 				inputFloor: input.orchestrator.estInputTokens ?? 0,
 				outputBound: outputBound ?? 0,
-				turns: projectedProviderTurnsOf(orchLimits, overallExecutedCeiling(orchLimits, toolCeilingsOf(orchLimits))),
+				turns: projectedProviderTurnsOf(orchLimits, overallExecutedCeiling(orchLimits, toolCeilingsOf(orchLimits))) + coordinationRepairReserve,
 				count: 1
 			});
 			if (effectiveCapUsd !== void 0) orchestratorReserveUsd = Math.max(0, orchestratorAdmissionEstCostUsd(effectiveCapUsd, reservedForFinalizationUsd));
@@ -17601,6 +17654,38 @@ function preflightEstimate(input) {
 				flatReserveUsd
 			});
 		}
+		if (input.orchestrator.synthesis !== void 0) {
+			const synthesis = input.orchestrator.synthesis;
+			if (synthesis.limits !== void 0) validateUsageLimits(synthesis.limits, "preflight orchestrator.synthesis.limits");
+			if (synthesis.estInputTokens !== void 0) requireNonNegativeInteger(synthesis.estInputTokens, "preflight orchestrator.synthesis.estInputTokens");
+			const servedBy = resolveServing(synthesis.model) ?? resolveServing(defaults.routing?.synthesize);
+			if (servedBy === void 0) say({
+				severity: "error",
+				code: "unrouted-role",
+				message: "the synthesis invocation resolves no model for role 'synthesize': set defaults.routing.synthesize or a synthesis model on the call",
+				spawn: "synthesis"
+			});
+			else {
+				const caps = capsOf(servedBy);
+				const merged = mergeUsageLimits(synthesis.limits ?? { maxTurns: 4 }, void 0, defaults.limits);
+				const outputBound = caps === void 0 ? merged.maxOutputTokensPerTurn : merged.maxOutputTokensPerTurn === void 0 ? caps.maxOutputTokens : Math.min(caps.maxOutputTokens, merged.maxOutputTokensPerTurn);
+				const projected = projectedProviderTurnsOf(merged, overallExecutedCeiling(merged, toolCeilingsOf(merged))) + finishRepairReserve;
+				if (orchestratorEcho !== void 0) orchestratorEcho.synthesis = {
+					projectedProviderTurns: projected,
+					servedBy
+				};
+				const { adapterId, model } = parseModelRef(servedBy);
+				shapes.push({
+					label: "synthesis",
+					provider: adapterId,
+					model,
+					inputFloor: synthesis.estInputTokens ?? 0,
+					outputBound: outputBound ?? 0,
+					turns: projected,
+					count: 1
+				});
+			}
+		}
 	}
 	const wave = [];
 	let committed = 0;
@@ -17807,6 +17892,7 @@ function preflightEstimate(input) {
 			if (typeof validator.validate !== "function") throw new ConfigError(`preflight finish validator '${validator.name}' has no validate function`);
 			names.add(validator.name);
 		}
+		if (fv.repairTurnReserve !== void 0) requireNonNegativeInteger(fv.repairTurnReserve, "preflight finishValidation.repairTurnReserve");
 		if (fv.contract !== void 0) {
 			for (const contractValidator of fv.contract.validators) if (!names.has(contractValidator.name)) findings.push({
 				severity: "error",

package/package.json

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