@rulvar/core 1.75.0 → 1.76.0

package/dist/index.d.ts

@@ -7126,6 +7126,30 @@ interface FinishValidationSpec {
   */
   repairTurnReserve?: number;
   /**
+  * The coordination draft gate (the v1.74 experiment review, P0.3),
+  * meaningful ONLY with `synthesis` configured: with validators bound
+  * to the synthesis finish, the coordination finish is an unvalidated
+  * draft, and the experiment's model escaped six failed finish
+  * exchanges with the schema-valid draft 'test', which then starved
+  * synthesis of every citation the validators demanded. The policy
+  * runs deterministic library checks on each coordination finish
+  * (whitespace-token `minWords`, literal `requireSections` markers,
+  * the wordCountValidator and requiredSectionsValidator semantics);
+  * a failing draft returns to the model as the finish call's error
+  * result and the turn continues, exactly like a host validation
+  * rejection, and `repairTurnReserve` grants coordination the same
+  * per-rejected-exchange headroom it grants the synthesis finish.
+  * Pure text checks over the durable exchange: nothing journals, a
+  * resumed segment recounts identically, and `maxRepairs` is not
+  * consumed (it belongs to the synthesis-bound validators). Absent =
+  * byte identical pre 1.76 behavior; configured without `synthesis` =
+  * ConfigError.
+  */
+  draftPolicy?: {
+    /** Minimum whitespace-separated words the draft must carry. */minWords?: number; /** Literal markers the draft text must contain. */
+    requireSections?: string[];
+  };
+  /**
   * 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
@@ -7286,6 +7310,31 @@ interface OrchestrateSynthesis {
   * { maxTurns: 2 }. Ignored in 'single' mode.
   */
   noteLimits?: UsageLimits;
+  /**
+  * Give the 'single' synthesis invocation the RV-201 evidence tools
+  * `get_child_result` and `read_child_artifact` beside `finish` (the
+  * v1.74 experiment review, P0.2): the finish validators hold the
+  * result against the FULL child outputs while the synthesis model
+  * sees 400 char digests, so when the coordination draft collapses the
+  * evidence the validators demand is model-invisible. With the tools
+  * exposed the digest rows in the synthesis prompt carry each child's
+  * `handle`, and the model pages any settled child's full output or
+  * artifacts before finishing. Off by default: the synthesis toolset
+  * and prompt stay byte identical, exactly like the coordination
+  * `exposeChildResultTools`.
+  */
+  exposeChildResultTools?: boolean;
+  /**
+  * What the 'single' synthesis prompt embeds beside the draft (the
+  * v1.74 experiment review, P0.2). Default 'digests': the 400 char
+  * settled digest rows, byte identical to pre 1.76. 'full' appends a
+  * CHILD OUTPUTS section carrying every settled child's FULL
+  * serialized output after the digest rows: the whole evidence pool
+  * the validators judge against rides the prompt, paid as input
+  * tokens (declare `estCost` or the preflight `estInputTokens`
+  * accordingly).
+  */
+  context?: "digests" | "full";
 }
 /**
 * The deterministic reconciliation envelope an 'incremental' synthesis
@@ -8866,6 +8915,14 @@ interface PreflightOrchestratorSpec {
     model?: ModelSpec;
     limits?: UsageLimits;
     estInputTokens?: number;
+    /**
+    * Mirrors OrchestrateSynthesis.exposeChildResultTools (the v1.74
+    * experiment review, P0.2): declaring it lets the evidence
+    * asymmetry check see that the synthesis model can page the full
+    * child outputs the validators judge against.
+    */
+    exposeChildResultTools?: boolean; /** Mirrors OrchestrateSynthesis.context; default 'digests'. */
+    context?: "digests" | "full";
   };
 }
 /** The full input: engine surface, run surface, and the declared wave. */

package/dist/index.js

@@ -10377,6 +10377,22 @@ function recoverUnparsedArgs(raw) {
 	};
 }
 /**
+* The recovery adoption warn line, shared verbatim by the regular tool
+* executor and the terminal tool interception so the two sites cannot
+* drift. The recovery itself stays INLINE at both call sites (v1.75.1):
+* an async wrapper around the common validation added one microtask
+* tick to EVERY tool validation and shifted quiescence-sensitive
+* cassette flows, and promise-tick identity is part of the byte
+* contract, so only the synchronous pieces are shared.
+*/
+function unparsedRecoveryLog(toolName, rawChars, pass) {
+	return {
+		type: "log",
+		level: "warn",
+		msg: `arguments for '${toolName}' arrived unparsed (${String(rawChars)} chars) and were recovered by a ${pass} JSON pass; the recovered object passed the tool schema and the call executed`
+	};
+}
+/**
 * Executes one model-issued tool call to a tool-result part. Failures are
 * surfaced to the model as error tool results and never thrown past
 * policy: unknown names, argument-validation issues, ModelRetry (bounded
@@ -10409,15 +10425,11 @@ async function executeToolCall(options) {
 	if (!validation.valid) {
 		const unparsedRaw = unparsedMarkerOf(call.args);
 		const recovered = unparsedRaw === void 0 ? void 0 : recoverUnparsedArgs(unparsedRaw);
-		if (recovered !== void 0) {
+		if (recovered !== void 0 && unparsedRaw !== void 0) {
 			const revalidation = await validateSchemaSpec(def.parameters, recovered.value);
 			if (revalidation.valid) {
 				validation = revalidation;
-				options.events?.emit({
-					type: "log",
-					level: "warn",
-					msg: `arguments for '${call.name}' arrived unparsed (${String(unparsedRaw?.length ?? 0)} chars) and were recovered by a ${recovered.pass} JSON pass; the recovered object passed the tool schema and the call executed`
-				});
+				options.events?.emit(unparsedRecoveryLog(call.name, unparsedRaw.length, recovered.pass));
 			}
 		}
 	}
@@ -10838,7 +10850,18 @@ async function runAgent(options) {
 			}
 			if (options.terminalTool !== void 0 && gatedCall.name === options.terminalTool.name) {
 				const terminalDef = runtime.defs.find((candidate) => candidate.name === gatedCall.name);
-				const validation = terminalDef === void 0 ? void 0 : await validateSchemaSpec(terminalDef.parameters, gatedCall.args);
+				let validation = terminalDef === void 0 ? void 0 : await validateSchemaSpec(terminalDef.parameters, gatedCall.args);
+				if (terminalDef !== void 0 && validation !== void 0 && !validation.valid) {
+					const unparsedRaw = unparsedMarkerOf(gatedCall.args);
+					const recovered = unparsedRaw === void 0 ? void 0 : recoverUnparsedArgs(unparsedRaw);
+					if (recovered !== void 0 && unparsedRaw !== void 0) {
+						const revalidation = await validateSchemaSpec(terminalDef.parameters, recovered.value);
+						if (revalidation.valid) {
+							validation = revalidation;
+							events?.emit(unparsedRecoveryLog(gatedCall.name, unparsedRaw.length, recovered.pass));
+						}
+					}
+				}
 				if (validation === void 0 || !validation.valid) {
 					events?.emit({
 						type: "tool:end",
@@ -15856,6 +15879,19 @@ function validateOrchestrateOptions(opts) {
 		}
 		if (fv.maxRepairs !== void 0) requireNonNegativeInteger(fv.maxRepairs, "orchestrate finishValidation.maxRepairs");
 		if (fv.repairTurnReserve !== void 0) requireNonNegativeInteger(fv.repairTurnReserve, "orchestrate finishValidation.repairTurnReserve");
+		const draftPolicy = fv.draftPolicy;
+		if (draftPolicy !== void 0) {
+			if (typeof draftPolicy !== "object" || draftPolicy === null) throw new ConfigError("orchestrate finishValidation.draftPolicy must be an object");
+			if (opts.synthesis === void 0) throw new ConfigError("orchestrate finishValidation.draftPolicy requires synthesis: without a synthesis invocation the validators bind the coordination finish itself and there is no unvalidated draft to gate");
+			const policy = draftPolicy;
+			if (policy.minWords === void 0 && policy.requireSections === void 0) throw new ConfigError("orchestrate finishValidation.draftPolicy must declare minWords, requireSections, or both");
+			if (policy.minWords !== void 0) {
+				if (typeof policy.minWords !== "number" || !Number.isInteger(policy.minWords) || policy.minWords < 1) throw new ConfigError(`orchestrate finishValidation.draftPolicy.minWords must be a positive integer; got ${JSON.stringify(policy.minWords)}`);
+			}
+			if (policy.requireSections !== void 0) {
+				if (!Array.isArray(policy.requireSections) || policy.requireSections.length === 0 || policy.requireSections.some((section) => typeof section !== "string" || section.length === 0)) throw new ConfigError("orchestrate finishValidation.draftPolicy.requireSections must be a non empty array of non empty strings");
+			}
+		}
 		const contract = fv.contract;
 		if (contract !== void 0) {
 			const shape = contract;
@@ -15881,6 +15917,9 @@ function validateOrchestrateOptions(opts) {
 		if (synthesis.mode !== void 0 && synthesis.mode !== "single" && synthesis.mode !== "incremental") throw new ConfigError("orchestrate synthesis.mode must be 'single' or 'incremental'; got " + JSON.stringify(synthesis.mode));
 		if (synthesis.mode === "incremental" && opts.finishValidation !== void 0) throw new ConfigError("orchestrate synthesis.mode 'incremental' reconciles deterministically and has no model-composed final finish for finishValidation to bind; configure validators with mode 'single', or drop them");
 		if (synthesis.dedupeClaims !== void 0 && typeof synthesis.dedupeClaims !== "boolean") throw new ConfigError("orchestrate synthesis.dedupeClaims must be a boolean; got " + typeof synthesis.dedupeClaims);
+		const symmetry = synthesis;
+		if (symmetry.exposeChildResultTools !== void 0 && typeof symmetry.exposeChildResultTools !== "boolean") throw new ConfigError("orchestrate synthesis.exposeChildResultTools must be a boolean; got " + typeof symmetry.exposeChildResultTools);
+		if (symmetry.context !== void 0 && symmetry.context !== "digests" && symmetry.context !== "full") throw new ConfigError("orchestrate synthesis.context must be 'digests' or 'full'; got " + JSON.stringify(symmetry.context));
 		if (synthesis.noteLimits !== void 0) validateUsageLimits(synthesis.noteLimits, "orchestrate synthesis.noteLimits");
 		if (synthesis.effort !== void 0 && ![
 			"low",
@@ -16917,6 +16956,37 @@ function makeOrchestratorWorkflow(goal, opts) {
 			};
 		};
 		/**
+		* The coordination draft gate (the v1.74 experiment review, P0.3):
+		* deterministic library text checks over the draft finish, run only
+		* when the validators bind synthesis. Unlike validateFinish nothing
+		* journals: the checks are pure functions of the exchange, the
+		* rejected exchange is durable in the transcript itself, and a
+		* resumed segment recounts identically. The rejection is the finish
+		* call's error result, so the loop's repair-reserve grants count it
+		* exactly like a host validation rejection.
+		*/
+		const validateDraft = (call) => {
+			const policy = validationSpec?.draftPolicy;
+			if (policy === void 0) return Promise.resolve({ ok: true });
+			const result = call.result ?? null;
+			const text = typeof result === "string" ? result : JSON.stringify(result);
+			const reasons = [];
+			if (policy.minWords !== void 0) {
+				const trimmed = text.trim();
+				const words = trimmed === "" ? 0 : trimmed.split(/\s+/).length;
+				if (words < policy.minWords) reasons.push(`the draft carries ${String(words)} words, below the required ${String(policy.minWords)}`);
+			}
+			for (const section of policy.requireSections ?? []) if (!text.includes(section)) reasons.push(`required draft section '${section}' is missing`);
+			if (reasons.length === 0) return Promise.resolve({ ok: true });
+			return Promise.resolve({
+				ok: false,
+				feedback: {
+					error: "the coordination draft failed the draft policy; repair the draft and call finish again: the synthesis invocation composes the FINAL result from this draft, and a collapsed draft starves it of the evidence the validators demand",
+					reasons
+				}
+			});
+		};
+		/**
 		* The frozen bundle descriptor (the v1.71 experiment review,
 		* P0.2): with a contract configured, the run durably records WHAT
 		* validates it. One decision entry per distinct contract hash, in
@@ -16961,7 +17031,10 @@ function makeOrchestratorWorkflow(goal, opts) {
 			},
 			[kTerminalTool]: {
 				name: FINISH_TOOL_NAME,
-				...validationSpec === void 0 || opts?.synthesis !== void 0 ? {} : {
+				...validationSpec === void 0 || opts?.synthesis !== void 0 ? validationSpec?.draftPolicy !== void 0 && opts?.synthesis !== void 0 ? {
+					validate: validateDraft,
+					...validationSpec.repairTurnReserve === void 0 ? {} : { repairTurnReserve: validationSpec.repairTurnReserve }
+				} : {} : {
 					validate: validateFinish,
 					...validationSpec.repairTurnReserve === void 0 ? {} : { repairTurnReserve: validationSpec.repairTurnReserve }
 				}
@@ -17206,8 +17279,15 @@ function makeOrchestratorWorkflow(goal, opts) {
 			if (spec === void 0) return draft;
 			await recoveryDone;
 			if (spec.mode === "incremental") return await reconcileIncremental(draft, spec);
-			const finishOnly = buildOrchestratorTools(orchestratorRuntime, fullCardText).filter((tool) => tool.name === FINISH_TOOL_NAME);
-			const settledDigests = [...records.values()].filter((record) => record.settled !== void 0).sort((a, b) => a.spawnOrdinal - b.spawnOrdinal).map((record) => digestOf(record, record.settled));
+			const exposeTools = spec.exposeChildResultTools === true;
+			const fullContext = spec.context === "full";
+			const synthesisToolNames = /* @__PURE__ */ new Set([FINISH_TOOL_NAME, ...exposeTools ? [GET_CHILD_RESULT_TOOL_NAME, READ_CHILD_ARTIFACT_TOOL_NAME] : []]);
+			const synthesisTools = buildOrchestratorTools(orchestratorRuntime, fullCardText, { childResultTools: exposeTools }).filter((tool) => synthesisToolNames.has(tool.name));
+			const settledEntries = [...records.entries()].filter((entry) => entry[1].settled !== void 0).sort((a, b) => a[1].spawnOrdinal - b[1].spawnOrdinal);
+			const settledDigests = settledEntries.map(([handle, record]) => ({
+				...exposeTools ? { handle } : {},
+				...digestOf(record, record.settled)
+			}));
 			let digestRows = settledDigests;
 			let repeatedClaims;
 			if (spec.dedupeClaims === true) {
@@ -17225,13 +17305,19 @@ function makeOrchestratorWorkflow(goal, opts) {
 			const draftJson = JSON.stringify(draft ?? null);
 			const digestJson = JSON.stringify(digestRows);
 			const prompt = [
-				"You are the synthesis invocation of an orchestrated run. Compose the FINAL result of the run from the goal, the coordination draft, and the settled child evidence below by calling finish({ result }) EXACTLY once. Preserve the evidence and citations the draft relies on; do not invent findings. No other tool exists.",
+				"You are the synthesis invocation of an orchestrated run. Compose the FINAL result of the run from the goal, the coordination draft, and the settled child evidence below by calling finish({ result }) EXACTLY once. Preserve the evidence and citations the draft relies on; do not invent findings. " + (exposeTools ? "Beside finish, get_child_result and read_child_artifact page any SETTLED child's FULL output and artifacts by handle (each DIGEST row carries its handle); read what the validators will hold you to before finishing." : "No other tool exists."),
 				...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),
 				`GOAL: ${goal}`,
 				`DRAFT: ${draftJson}`,
 				`DIGEST: ${digestJson}`,
+				...fullContext ? [`CHILD OUTPUTS: ${JSON.stringify(settledEntries.map(([handle, record]) => ({
+					...exposeTools ? { handle } : {},
+					nodeId: record.nodeId,
+					status: record.settled.status,
+					text: serializeChildOutput(record.settled)
+				})))}`] : [],
 				...repeatedClaims === void 0 ? [] : [`REPEATED CLAIMS: ${JSON.stringify(repeatedClaims)}`]
 			].join("\n");
 			internals.events.emit({
@@ -17257,7 +17343,7 @@ function makeOrchestratorWorkflow(goal, opts) {
 			const synthesisOpts = {
 				role: "synthesize",
 				result: "full",
-				tools: finishOnly,
+				tools: synthesisTools,
 				limits: spec.limits ?? { maxTurns: 4 },
 				...spec.model === void 0 ? {} : { model: spec.model },
 				...spec.effort === void 0 ? {} : { effort: spec.effort },
@@ -17872,6 +17958,21 @@ function preflightEstimate(input) {
 			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");
+			if (synthesis.context !== void 0 && synthesis.context !== "digests" && synthesis.context !== "full") throw new ConfigError("preflight orchestrator.synthesis.context must be 'digests' or 'full'; got " + JSON.stringify(synthesis.context));
+			{
+				const evidenceNames = /* @__PURE__ */ new Set([
+					"evidence-preserved",
+					"contract-citations",
+					"contract-section-citations"
+				]);
+				const evidenceValidators = (input.finishValidation?.validators ?? []).map((validator) => validator.name).filter((name) => evidenceNames.has(name));
+				if ((evidenceValidators.length > 0 || input.finishValidation?.contract?.manifest.citations !== void 0) && synthesis.exposeChildResultTools !== true && (synthesis.context ?? "digests") === "digests") say({
+					severity: "warning",
+					code: "synthesis-evidence-asymmetry",
+					message: `the finish validators demand child evidence (${evidenceValidators.length > 0 ? evidenceValidators.join(", ") : "contract citations"}) but the synthesis invocation sees only truncated digest rows and has no child read tools: a collapsed coordination draft starves it of every citation (the v1.74 experiment shape); set synthesis.exposeChildResultTools, synthesis.context 'full', or bind the validators to coordination by dropping synthesis`,
+					spawn: "synthesis"
+				});
+			}
 			const servedBy = resolveServing(synthesis.model) ?? resolveServing(defaults.routing?.synthesize);
 			if (servedBy === void 0) say({
 				severity: "error",

package/package.json

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