@rulvar/core 1.100.0 → 1.101.0

package/dist/index.d.ts

@@ -7909,6 +7909,32 @@ interface OrchestrateSynthesis {
   * accordingly).
   */
   context?: "digests" | "full";
+  /**
+  * The conditional synthesis gate (RV510, the ninth comparison
+  * experiment: synthesis returned the byte-identical draft after
+  * 101.3 s and 0.5512 USD, 57.3% of post-fan-in wall time). With
+  * `true`, before the 'single' synthesis span starts the coordination
+  * draft is run through the FULL declared finish contract (the same
+  * `finishValidation.validators` that would bind the synthesis
+  * finish): a draft that passes skips the synthesis invocation
+  * entirely under a journaled 'orchestrator_synthesis_skip' decision
+  * with reason 'synthesis_skipped_by_valid_draft' (the existing skip
+  * vocabulary; the info log and the acceptance envelope carry it), and
+  * a resume rolls the journaled skip forward with zero paid calls. A
+  * draft that fails any validator goes to synthesis exactly as before,
+  * with the repair budget untouched (the gate is a pre-pass, never a
+  * journaled validation verdict). Deterministic by construction: only
+  * the declared contract judges, never a semantic delta heuristic.
+  * Requires `finishValidation` (a ConfigError at intake otherwise:
+  * without a contract there is nothing to judge the draft valid by),
+  * which transitively limits it to mode 'single'. With a configured
+  * `budget.synthesisReserveUsd` the held money is released unconsumed
+  * on the skip and no reserve lifecycle journals: there was no
+  * synthesis invocation to account. Default false: the gate, the
+  * decision entry, and the envelope field are all absent, byte for
+  * byte.
+  */
+  skipWhenDraftValid?: boolean;
 }
 /**
 * The deterministic reconciliation envelope an 'incremental' synthesis
@@ -7943,15 +7969,22 @@ interface IncrementalSynthesisResult {
 * notes were already paid during the run; the skipped step is the free
 * deterministic reconciliation). 'synthesis_skipped_by_budget_cap': the
 * orchestrator budget cap froze the plan, and a capped run settles
-* through the reserved finalizer, never synthesis. The reason is frozen
-* into the journaled decision that caused the skip (the acceptance
-* decision or the budget-cap decision), spread into the typed
-* FailRunError data on the failing paths, and announced by an info
-* 'orchestrator synthesis skipped' log event; it is absent everywhere
-* when synthesis is not configured or actually ran, so existing runs
-* stay byte identical.
-*/
-type OrchestrateSynthesisSkipReason = "synthesis_skipped_by_acceptance" | "synthesis_skipped_by_budget_cap";
+* through the reserved finalizer, never synthesis.
+* 'synthesis_skipped_by_valid_draft' (RV510): the opt-in
+* `synthesis.skipWhenDraftValid` gate ran the coordination draft
+* through the full declared finish contract and every validator
+* passed, so the synthesis invocation had nothing to add and never
+* started; unlike the other two reasons the run still settles ok with
+* the draft as its result. The reason is frozen into the journaled
+* decision that caused the skip (the acceptance decision, the
+* budget-cap decision, or the 'orchestrator_synthesis_skip' decision),
+* spread into the typed FailRunError data on the failing paths and
+* into the acceptance envelope on the valid-draft path, and announced
+* by an info 'orchestrator synthesis skipped' log event; it is absent
+* everywhere when synthesis is not configured or actually ran, so
+* existing runs stay byte identical.
+*/
+type OrchestrateSynthesisSkipReason = "synthesis_skipped_by_acceptance" | "synthesis_skipped_by_budget_cap" | "synthesis_skipped_by_valid_draft";
 declare const ORCHESTRATE_WORKFLOW_NAME = "rulvar-orchestrate";
 /**
 * Resolves per-spawn dispatch options against the engine registries

package/dist/index.js

@@ -16973,6 +16973,11 @@ function validateOrchestrateOptions(opts) {
 		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);
+		const conditional = synthesis;
+		if (conditional.skipWhenDraftValid !== void 0) {
+			if (typeof conditional.skipWhenDraftValid !== "boolean") throw new ConfigError("orchestrate synthesis.skipWhenDraftValid must be a boolean; got " + typeof conditional.skipWhenDraftValid);
+			if (conditional.skipWhenDraftValid && opts.finishValidation === void 0) throw new ConfigError("orchestrate synthesis.skipWhenDraftValid requires finishValidation: without a declared finish contract there is nothing to judge the draft valid by");
+		}
 		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 && ![
@@ -17980,6 +17985,24 @@ function makeOrchestratorWorkflow(goal, opts) {
 			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;
 		};
+		/**
+		* The children snapshot (RV-202): spawn order, pure reads of the
+		* records the orchestrator already tracks, so validators can hold
+		* a finish result (or the RV510 draft pre-pass) against the
+		* evidence the children produced. Only the JOURNALED verdict of
+		* validateFinish survives; on replay the snapshot is never rebuilt
+		* because the entry is read by call id there.
+		*/
+		const validationChildren = () => {
+			const salvageOutputOn = opts?.acceptance?.acceptValidatedTerminalOutputOnLimit === true;
+			return [...records.values()].sort((a, b) => a.spawnOrdinal - b.spawnOrdinal).map((record) => ({
+				handle: record.handle,
+				nodeId: record.nodeId,
+				status: record.settled?.status ?? "running",
+				text: record.settled === void 0 ? "" : serializeChildOutput(record.settled),
+				...salvageOutputOn && record.settled?.status === "limit" && record.settled.output !== null && record.settled.output !== void 0 ? { salvageableOutput: true } : {}
+			}));
+		};
 		const validateFinish = async (call) => {
 			if (validationSpec === void 0) return { ok: true };
 			const maxRepairs = validationSpec.maxRepairs ?? 1;
@@ -17987,18 +18010,10 @@ function makeOrchestratorWorkflow(goal, opts) {
 			let decision = known.find((candidate) => candidate.callId === call.id);
 			if (decision === void 0) {
 				const result = call.result ?? null;
-				const salvageOutputOn = opts?.acceptance?.acceptValidatedTerminalOutputOnLimit === true;
-				const children = [...records.values()].sort((a, b) => a.spawnOrdinal - b.spawnOrdinal).map((record) => ({
-					handle: record.handle,
-					nodeId: record.nodeId,
-					status: record.settled?.status ?? "running",
-					text: record.settled === void 0 ? "" : serializeChildOutput(record.settled),
-					...salvageOutputOn && record.settled?.status === "limit" && record.settled.output !== null && record.settled.output !== void 0 ? { salvageableOutput: true } : {}
-				}));
 				const input = {
 					result,
 					text: typeof result === "string" ? result : JSON.stringify(result),
-					children
+					children: validationChildren()
 				};
 				const failed = [];
 				for (const validator of validationSpec.validators) {
@@ -18392,11 +18407,75 @@ function makeOrchestratorWorkflow(goal, opts) {
 		* facts; absent everywhere when no reserve is configured.
 		*/
 		let synthesisReserveLifecycle;
+		/**
+		* Set exactly when the RV510 gate skipped the synthesis span (live
+		* pass and resume roll-forward alike); the acceptance envelope
+		* reports the machine reason through it.
+		*/
+		let synthesisSkippedByValidDraft = false;
 		const runSynthesis = async (draft) => {
 			const spec = opts?.synthesis;
 			if (spec === void 0) return draft;
 			await recoveryDone;
 			if (spec.mode === "incremental") return await reconcileIncremental(draft, spec);
+			if (spec.skipWhenDraftValid === true && validationSpec !== void 0) {
+				const skipKey = "synthesis-draft-valid-skip";
+				const announceSkip = (entryRef) => {
+					internals.events.emit({
+						type: "log",
+						level: "info",
+						msg: "orchestrator synthesis skipped",
+						data: {
+							reason: "synthesis_skipped_by_valid_draft",
+							skipDecisionRef: entryRef
+						}
+					}, callingState.spanId);
+				};
+				const prior = internals.replayer.snapshot().find((entry) => entry.kind === "decision" && entry.scope === callingState.scope && entry.key === skipKey);
+				if (prior !== void 0) {
+					synthesisSkippedByValidDraft = true;
+					announceSkip(prior.seq);
+					return draft;
+				}
+				const draftValue = draft ?? null;
+				const input = {
+					result: draftValue,
+					text: typeof draftValue === "string" ? draftValue : JSON.stringify(draftValue),
+					children: validationChildren()
+				};
+				let allPassed = true;
+				for (const validator of validationSpec.validators) {
+					let verdict;
+					try {
+						verdict = validator.validate(input);
+					} catch (thrown) {
+						throw new ConfigError(`finish validator '${validator.name}' threw instead of returning a verdict during the skipWhenDraftValid pre-pass: ` + (thrown instanceof Error ? thrown.message : String(thrown)));
+					}
+					if (!verdict.ok) {
+						allPassed = false;
+						break;
+					}
+				}
+				if (allPassed) {
+					const skipEntry = await internals.replayer.appendSinglePhase({
+						scope: callingState.scope,
+						key: skipKey,
+						kind: "decision",
+						status: "ok",
+						spanId: internals.spans.mint(callingState.spanId),
+						site: "orchestrator-synthesis-skip",
+						value: {
+							decisionType: "orchestrator_synthesis_skip",
+							reason: "synthesis_skipped_by_valid_draft",
+							validators: validationSpec.validators.map((validator) => validator.name)
+						}
+					});
+					if (orchestratorAccount !== void 0 && (opts?.budget?.synthesisReserveUsd ?? 0) > 0) internals.budget.releaseSynthesisReserve(orchestratorAccount);
+					synthesisSkippedByValidDraft = true;
+					announceSkip(skipEntry.seq);
+					return draft;
+				}
+			}
 			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] : []]);
@@ -18746,7 +18825,8 @@ function makeOrchestratorWorkflow(goal, opts) {
 			...decision.salvagedPartialChildren === void 0 ? {} : { salvagedPartialChildren: decision.salvagedPartialChildren },
 			...decision.salvagedTerminalOutputChildren === void 0 ? {} : { salvagedTerminalOutputChildren: decision.salvagedTerminalOutputChildren },
 			...envelopeSchemaRecovered === 0 ? {} : { schemaRecoveredFinishExchanges: envelopeSchemaRecovered },
-			...synthesisReserveLifecycle === void 0 ? {} : { synthesisReserve: synthesisReserveLifecycle }
+			...synthesisReserveLifecycle === void 0 ? {} : { synthesisReserve: synthesisReserveLifecycle },
+			...synthesisSkippedByValidDraft ? { synthesisSkipped: "synthesis_skipped_by_valid_draft" } : {}
 		};
 	});
 }

package/package.json

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