@rulvar/core 1.76.0 → 1.77.0

package/dist/index.d.ts

@@ -4197,6 +4197,16 @@ interface AgentResult<T> {
   * seeing a bare 'terminal status limit'.
   */
   partial?: ProgressReport;
+  /**
+  * Terminal-tool exchanges whose ARGUMENTS died at the schema gate
+  * (the unparsed second chance included, when it did not recover): the
+  * v1.74 experiment lost six finish payloads to exactly this class,
+  * and nothing outside the transcript said so (host validation
+  * rejections, by contrast, journal decision entries). Derived from
+  * the message window like the repair-reserve grants, so live and
+  * resumed segments count the same total; absent when zero.
+  */
+  schemaRejectedTerminalExchanges?: number;
 }
 /** One 429's provider-normalized limits, per (provider, model). */
 interface RateLimitObservation {
@@ -7162,8 +7172,17 @@ interface FinishValidationSpec {
   * hash and the validator names. A resumed segment whose live
   * contract hash differs appends a SUPERSEDING descriptor instead of
   * failing, because fixing a stale validator and resuming is the
-  * intended remedy, never a fault. Absent = byte identical pre 1.72
-  * behavior.
+  * intended remedy, never a fault. The remedy is generation-scoped
+  * (cycle 73): every decision entry written under a contract carries
+  * `contractHash`, and only the CURRENT generation is judged, so
+  * repairsUsed restarts under a fixed contract and a final rejection
+  * a superseded generation left in the crash window neither rolls
+  * forward at boot nor re-arms on replay (its exchange replays byte
+  * identical and the loop continues to a live repair turn). Decisions
+  * recorded before 1.77 carry no hash and bind to the current
+  * contract only while the journal holds a single bundle descriptor;
+  * once a supersession is recorded they are stale. Absent = byte
+  * identical pre 1.72 behavior.
   */
   contract?: FinishContract;
   /**
@@ -8964,6 +8983,13 @@ interface PreflightInput {
     * runtime would actually grant.
     */
     repairTurnReserve?: number;
+    /**
+    * Mirrors FinishValidationSpec.maxRepairs (default
+    * {@link DEFAULT_FINISH_MAX_REPAIRS}): with zero, the first
+    * rejection is final and there is no repair exchange to fund, so
+    * the repair-reserve-unfunded warning stays silent.
+    */
+    maxRepairs?: number;
   };
 }
 /** One linter verdict; `spawn` names the wave entry it is about. */

package/dist/index.js

@@ -10181,6 +10181,15 @@ function estimateInputTokens(messages) {
 	return Math.ceil(chars / 4);
 }
 /**
+* The terminal tool's schema-rejection feedback line. One producer, two
+* readers: the interception writes it as the error result, and the
+* window-derived schemaRejectedTerminalExchanges counter recognizes the
+* exchange by exactly these bytes, so the two can never drift.
+*/
+function terminalSchemaRejectionMessage(name) {
+	return `the '${name}' call failed validation`;
+}
+/**
 * The serving model's declared minimum request output cap, default one.
 * OpenAI's Responses API rejects max_output_tokens below 16, so a
 * below-floor dispatch is a guaranteed provider 400: the v1.74
@@ -10870,7 +10879,7 @@ async function runAgent(options) {
 						durationMs: now() - gateStartedAt
 					});
 					parts.push(errorPart(call, {
-						error: `the '${gatedCall.name}' call failed validation`,
+						error: terminalSchemaRejectionMessage(gatedCall.name),
 						issues: validation === void 0 ? [] : validation.issues.map((i) => i.message)
 					}));
 					continue;
@@ -12008,6 +12017,9 @@ async function runAgent(options) {
 	if (errorMessage !== void 0) result.errorMessage = errorMessage;
 	if (guard !== void 0) result.exploration = guard.summary(toolCallsUsed);
 	if (limitPartial !== void 0) result.partial = limitPartial;
+	const terminalName = options.terminalTool?.name;
+	const schemaRejectedTerminalExchanges = terminalName === void 0 ? 0 : messages.reduce((count, message) => count + message.parts.filter((part) => part.type === "tool-result" && part.name === terminalName && part.isError === true && part.result?.error === terminalSchemaRejectionMessage(terminalName)).length, 0);
+	if (schemaRejectedTerminalExchanges > 0) result.schemaRejectedTerminalExchanges = schemaRejectedTerminalExchanges;
 	if (usageApprox) result.usageApprox = true;
 	if (transportRetries > 0) result.transportRetries = transportRetries;
 	if (rateLimitObservations.size > 0) result.rateLimitObservations = [...rateLimitObservations.values()];
@@ -16869,6 +16881,12 @@ function makeOrchestratorWorkflow(goal, opts) {
 		const validationSpec = opts?.finishValidation;
 		const validationAbort = new AbortController();
 		let validationTermination;
+		/**
+		* The synthesis invocation's schema-dead finish exchanges (cycle
+		* 73), captured from its full agent result so the failure
+		* enrichment can fold BOTH windows into one honest counter.
+		*/
+		let synthesisSchemaRejectedExchanges = 0;
 		const finishValidationError = (decision) => new FailRunError(`the orchestrator finish failed host validation with all ${String(decision.maxRepairs)} repair attempts spent: ` + decision.failed.map((f) => `validator '${f.name}' rejected: ${f.reasons.join("; ")}`).join("; "), { data: {
 			source: "orchestrator_finish_validation",
 			callId: decision.callId,
@@ -16877,6 +16895,22 @@ function makeOrchestratorWorkflow(goal, opts) {
 			maxRepairs: decision.maxRepairs
 		} });
 		const validationDecisions = () => internals.replayer.snapshot().filter((entry) => entry.kind === "decision" && entry.scope === callingState.scope && entry.value?.decisionType === "orchestrator_finish_validation").map((entry) => entry.value);
+		/**
+		* The contract generation membership test (cycle 73). Without a
+		* contract there are no generations and every decision is current
+		* (the pre 1.77 behavior, byte identical). With one, a decision
+		* belongs to the current generation when its journaled hash matches
+		* the live contract; a pre 1.77 decision carries no hash and counts
+		* as current only while the journal has never recorded a
+		* superseding bundle descriptor, because a single descriptor means
+		* every decision was necessarily rendered under it.
+		*/
+		const contractGenerationCurrent = (decision) => {
+			const hash = validationSpec?.contract?.hash;
+			if (hash === void 0) return true;
+			if (decision.contractHash !== void 0) return decision.contractHash === hash;
+			return internals.replayer.snapshot().filter((entry) => entry.kind === "decision" && entry.scope === callingState.scope && entry.value?.decisionType === "orchestrator_finish_validation_bundle").length <= 1;
+		};
 		const validateFinish = async (call) => {
 			if (validationSpec === void 0) return { ok: true };
 			const maxRepairs = validationSpec.maxRepairs ?? 1;
@@ -16915,14 +16949,15 @@ function makeOrchestratorWorkflow(goal, opts) {
 						reasons: verdict.reasons
 					});
 				}
-				const repairsUsed = known.filter((candidate) => candidate.verdict !== "accepted").length;
+				const repairsUsed = known.filter((candidate) => candidate.verdict !== "accepted" && contractGenerationCurrent(candidate)).length;
 				decision = {
 					decisionType: "orchestrator_finish_validation",
 					callId: call.id,
 					verdict: failed.length === 0 ? "accepted" : repairsUsed < maxRepairs ? "repair" : "rejected",
 					failed,
 					repairsUsed,
-					maxRepairs
+					maxRepairs,
+					...validationSpec.contract === void 0 ? {} : { contractHash: validationSpec.contract.hash }
 				};
 				await internals.replayer.appendSinglePhase({
 					scope: callingState.scope,
@@ -16936,8 +16971,10 @@ function makeOrchestratorWorkflow(goal, opts) {
 			}
 			if (decision.verdict === "accepted") return { ok: true };
 			if (decision.verdict === "rejected") {
-				validationTermination = finishValidationError(decision);
-				validationAbort.abort("rulvar:finish-validation");
+				if (contractGenerationCurrent(decision)) {
+					validationTermination = finishValidationError(decision);
+					validationAbort.abort("rulvar:finish-validation");
+				}
 				return {
 					ok: false,
 					feedback: {
@@ -17357,6 +17394,7 @@ function makeOrchestratorWorkflow(goal, opts) {
 				}
 			};
 			const synthesized = await runtime.runInScope(synthesisState, () => ctx.agent(prompt, synthesisOpts));
+			synthesisSchemaRejectedExchanges = synthesized.schemaRejectedTerminalExchanges ?? 0;
 			if (validationTermination !== void 0) throw validationTermination;
 			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: {
@@ -17419,7 +17457,10 @@ function makeOrchestratorWorkflow(goal, opts) {
 		if (capDecisionRef !== void 0) return await settleCapOutcome();
 		if (validationSpec !== void 0) {
 			const priorRejection = validationDecisions().find((decision) => decision.verdict === "rejected");
-			if (priorRejection !== void 0) throw finishValidationError(priorRejection);
+			if (priorRejection !== void 0) {
+				const settle = lastRunSettle(internals.replayer.snapshot());
+				if (settle !== void 0 && settle.runStatus !== "running" && settle.runStatus !== "suspended" || contractGenerationCurrent(priorRejection)) throw finishValidationError(priorRejection);
+			}
 		}
 		const promptLines = [
 			...extension?.promptLines?.() ?? [],
@@ -17430,28 +17471,28 @@ function makeOrchestratorWorkflow(goal, opts) {
 		const liveTermination = extensionTermination;
 		if (liveTermination !== void 0) throw liveTermination;
 		if (capDecisionRef !== void 0) return await settleCapOutcome();
-		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}`));
 		/**
-		* 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.
+		* The finish-validation failure enrichment (the v1.71 experiment
+		* review, P0.8 remainder + P1.7; widened by cycle 73): every typed
+		* failure a finish rejection produces gains the verdict-derived
+		* repair taxonomy read from the JOURNALED validation decisions of
+		* the CURRENT contract generation (identical live and on replay),
+		* the schema-dead finish exchange counter derived from the
+		* coordination and synthesis windows (the class the v1.74 run lost
+		* six payloads to, invisible in every other field), and, when an
+		* acceptance verdict exists, the acceptance snapshot the children
+		* already earned: completion and childStatusCounts, and now the
+		* degradation facts beside them (degradedReasons and the salvage
+		* lists), exactly what the ok envelope reports. 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 spent = validationDecisions().filter((candidate) => candidate.verdict !== "accepted" && contractGenerationCurrent(candidate));
 			const rejectedValidators = [...new Set(spent.flatMap((candidate) => candidate.failed.map((f) => f.name)))];
+			const schemaRejected = (result.schemaRejectedTerminalExchanges ?? 0) + synthesisSchemaRejectedExchanges;
 			throw new FailRunError(thrown.message, { data: {
 				...base,
 				...snapshot ?? {},
@@ -17459,9 +17500,13 @@ function makeOrchestratorWorkflow(goal, opts) {
 					repairsUsed: spent.length,
 					maxRepairs: validationSpec?.maxRepairs ?? 1,
 					rejectedValidators
-				}
+				},
+				...schemaRejected === 0 || base.schemaRejectedFinishExchanges !== void 0 ? {} : { schemaRejectedFinishExchanges: schemaRejected }
 			} });
 		};
+		if (validationTermination !== void 0) enrichSynthesisFailure(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) try {
 			return await runSynthesis(result.output);
 		} catch (thrown) {
@@ -17545,7 +17590,10 @@ function makeOrchestratorWorkflow(goal, opts) {
 		} catch (thrown) {
 			enrichSynthesisFailure(thrown, {
 				completion: decision.completion,
-				childStatusCounts: decision.childStatusCounts
+				childStatusCounts: decision.childStatusCounts,
+				degradedReasons: decision.degradedReasons,
+				...decision.salvagedPartialChildren === void 0 ? {} : { salvagedPartialChildren: decision.salvagedPartialChildren },
+				...decision.salvagedTerminalOutputChildren === void 0 ? {} : { salvagedTerminalOutputChildren: decision.salvagedTerminalOutputChildren }
 			});
 		}
 		return {
@@ -17677,6 +17725,39 @@ function preflightEstimate(input) {
 	const say = (finding) => {
 		findings.push(finding);
 	};
+	/**
+	* The contract turn feasibility check (the v1.74 experiment review,
+	* cycle 73), run against the invocation the validators bind. The
+	* floor is the contract's own minimal accepting payload, serialized
+	* exactly as the model must emit it ({ result }) and priced at the
+	* loop's four-characters-per-token output heuristic: the v1.74 run's
+	* conforming payloads truncated at their 9000 token turn cap, and its
+	* contract's minimum alone prices above that cap. A minimum at or
+	* over the bound is an error (every conforming finish truncates mid
+	* payload); a minimum within double of the bound is a warning,
+	* because real conforming payloads run richer than the minimum.
+	*/
+	const contractFeasibilityFindings = (outputBound, spawn, servedBy) => {
+		const contract = input.finishValidation?.contract;
+		if (contract === void 0 || outputBound === void 0) return;
+		const minTokens = Math.ceil(JSON.stringify({ result: contract.goldenAccept.text }).length / 4);
+		const which = spawn === "synthesis" ? "the synthesis invocation" : "the coordination loop";
+		if (minTokens >= outputBound) {
+			say({
+				severity: "error",
+				code: "output-contract-turn-infeasible",
+				message: `the finish contract's minimal accepting payload is about ${String(minTokens)} tokens (four characters per token over the golden accept fixture) but ${which} dispatches at most ${String(outputBound)} output tokens per turn ('${servedBy}'): every conforming finish truncates mid payload; raise maxOutputTokensPerTurn or shrink the contract`,
+				spawn
+			});
+			return;
+		}
+		if (minTokens * 2 > outputBound) say({
+			severity: "warning",
+			code: "output-contract-turn-headroom",
+			message: `the finish contract's minimal accepting payload is about ${String(minTokens)} tokens against the ${String(outputBound)} token output bound of ${which} ('${servedBy}'): real conforming payloads run richer than the minimum and the margin is under double; raise the bound or trim the contract`,
+			spawn
+		});
+	};
 	const adapters = new Map((engine.adapters ?? []).map((adapter) => [adapter.id, adapter]));
 	const capsOf = (ref) => {
 		const { adapterId, model } = parseModelRef(ref);
@@ -17922,6 +18003,7 @@ function preflightEstimate(input) {
 				message: `the orchestrator sets maxOutputTokensPerTurn ${String(orchLimits.maxOutputTokensPerTurn)} below the ${String(caps.minOutputTokensPerTurn)} token output floor of '${servedBy}': every dispatch would be refused typed before the wire; raise the cap to at least the floor`,
 				spawn: "orchestrator"
 			});
+			if (input.orchestrator.synthesis === void 0) contractFeasibilityFindings(outputBound, "orchestrator", servedBy);
 			const { adapterId, model } = parseModelRef(servedBy);
 			const unit = {
 				label: "orchestrator",
@@ -17990,6 +18072,7 @@ function preflightEstimate(input) {
 					message: `the synthesis invocation sets maxOutputTokensPerTurn ${String(merged.maxOutputTokensPerTurn)} below the ${String(caps.minOutputTokensPerTurn)} token output floor of '${servedBy}': every dispatch would be refused typed before the wire; raise the cap to at least the floor`,
 					spawn: "synthesis"
 				});
+				contractFeasibilityFindings(outputBound, "synthesis", servedBy);
 				const projected = projectedProviderTurnsOf(merged, overallExecutedCeiling(merged, toolCeilingsOf(merged))) + finishRepairReserve;
 				if (orchestratorEcho !== void 0) orchestratorEcho.synthesis = {
 					projectedProviderTurns: projected,
@@ -18214,6 +18297,15 @@ function preflightEstimate(input) {
 			names.add(validator.name);
 		}
 		if (fv.repairTurnReserve !== void 0) requireNonNegativeInteger(fv.repairTurnReserve, "preflight finishValidation.repairTurnReserve");
+		if (fv.maxRepairs !== void 0) requireNonNegativeInteger(fv.maxRepairs, "preflight finishValidation.maxRepairs");
+		{
+			const grantedRepairs = fv.maxRepairs ?? 1;
+			if (grantedRepairs > 0 && fv.repairTurnReserve === void 0) findings.push({
+				severity: "warning",
+				code: "repair-reserve-unfunded",
+				message: `finishValidation grants up to ${String(grantedRepairs)} repair exchange(s) but declares no repairTurnReserve: a rejected finish burns an ordinary turn and a window at maxTurns settles 'limit' with the repair unspent; set finishValidation.repairTurnReserve to fund the repair exchanges`
+			});
+		}
 		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.76.0",
+  "version": "1.77.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",