@rulvar/plan 1.35.0 → 1.37.0

package/dist/index.d.ts

@@ -503,7 +503,16 @@ declare function rebasePlanRevision(request: PlanReviseRequest, context: RebaseC
 //#region src/guards.d.ts
 /** RevisionGuards configuration. */
 interface RevisionGuardsOptions {
-  /** Default 'finish-with-partial'; the chain is non-HITL and terminating. */
+  /**
+  * Default 'finish-with-partial'; the chain is non-HITL and
+  * terminating. 'reject-revision' and 'finish-with-partial' freeze the
+  * plan and steer the orchestrator to finish with the partial result
+  * (run outcome 'ok'). 'fail-run' closes the run as a FAILURE: after
+  * the journaled guard verdict the PlanRunner terminates the
+  * orchestration with FailRunError (code 'fail_run', data.source
+  * 'plan_guards', data.verdictRef), no further model turn is consulted,
+  * and resume rolls the same failure forward from the verdict entry.
+  */
   fallback?: "reject-revision" | "finish-with-partial" | "fail-run";
   /** Default 3 consecutive fully-dropped revisions. */
   droppedRevisionLimit?: number;

package/dist/index.js

@@ -1,4 +1,4 @@
-import { AdmissionRejectedError, BudgetExhaustedError, CURRENT_HASH_VERSION, ConfigError, DedupIndex, InMemoryStore, LEGACY_LTID_PREFIX, LEGACY_SIGNATURE_INPUTS, LineageIndex, PlanInvariantError, ROOT_ACCOUNT, ReplayPlanHashMismatch, TerminationAccount, approachSigCoarse, buildTerminationInitValue, canonicalIsolationTag, canonicalizeLadder, checkpointRefFor, countsAgainstLimit, createEngine, defineWorkflow, deriverV2, evaluateReuse, foldTermination, kMaxOf, knowledgeHash, ladderLengthOf, ladderRungChoice, makeOrchestratorWorkflow, nodeLinkKey, normalizeApproachTag, orchestrate, planNodeScope, profileRegistrySnapshotHash, tool, validateTerminationLimits } from "@rulvar/core";
+import { AdmissionRejectedError, BudgetExhaustedError, CURRENT_HASH_VERSION, ConfigError, DedupIndex, FailRunError, InMemoryStore, LEGACY_LTID_PREFIX, LEGACY_SIGNATURE_INPUTS, LineageIndex, PlanInvariantError, ROOT_ACCOUNT, ReplayPlanHashMismatch, TerminationAccount, approachSigCoarse, buildTerminationInitValue, canonicalIsolationTag, canonicalizeLadder, checkpointRefFor, countsAgainstLimit, createEngine, defineWorkflow, deriverV2, evaluateReuse, foldTermination, kMaxOf, knowledgeHash, ladderLengthOf, ladderRungChoice, makeOrchestratorWorkflow, nodeLinkKey, normalizeApproachTag, orchestrate, planNodeScope, profileRegistrySnapshotHash, tool, validateTerminationLimits } from "@rulvar/core";
 //#region src/plan-state.ts
 /**
 * Plan scope substrate (M7-T01): TaskPlan as engine-owned typed data, the
@@ -2029,6 +2029,26 @@ function planRunner(options) {
 		guard: verdict.guard,
 		...verdict.approachSigCoarse === void 0 ? {} : { approachSigCoarse: verdict.approachSigCoarse }
 	});
+	/**
+	* The engaged 'fail-run' fallback closes the run as a typed failure
+	* (v1.35.0 review P2-1: the verdict used to journal the fallback and
+	* then behave exactly like finish-with-partial). The journaled verdict
+	* is the decision; terminate() aborts the loop and the orchestrate
+	* settle boundary rethrows the failure, so a crash after the verdict
+	* rolls the SAME outcome forward from the journal on resume, with no
+	* second decision and no model call.
+	*/
+	let failRunSignalled = false;
+	const enforceEngagedFailRun = () => {
+		if (failRunSignalled || guards.state.engaged !== "fail-run") return;
+		failRunSignalled = true;
+		const verdictEntry = io.snapshot().find((entry) => entry.scope === planScope && entry.kind === "decision" && entry.value?.decisionType === "guard-verdict" && entry.value.fallback === "fail-run");
+		const guardName = (verdictEntry?.value)?.guard;
+		io.terminate?.(new FailRunError(`revision guards engaged (${guardName ?? "guard"}) with fallback 'fail-run': the plan is closed for adaptation and the run fails instead of finishing with the partial result`, { data: {
+			source: "plan_guards",
+			...verdictEntry === void 0 ? {} : { verdictRef: verdictEntry.seq }
+		} }));
+	};
 	/** Guard verdict state is a pure fold of journaled verdicts (M7-T06). */
 	const absorbGuardVerdicts = () => {
 		for (const entry of io.snapshot()) {
@@ -2040,6 +2060,7 @@ function planRunner(options) {
 			}
 			guardCursor = entry.seq;
 		}
+		enforceEngagedFailRun();
 	};
 	/**
 	* Appends fold-fired verdicts strictly BEFORE their effects; a
@@ -2065,6 +2086,7 @@ function planRunner(options) {
 				limit: verdict.oscillationCount ?? 0
 			});
 		}
+		enforceEngagedFailRun();
 	};
 	/** The coarse approach signature of a spec (mirrors admission's inputs). */
 	const coarseOf = (spec) => approachSigCoarse({
@@ -3340,7 +3362,13 @@ function planRunner(options) {
 			await io.flush();
 			absorbPlan();
 			absorbGuardVerdicts();
-			if (guards.revisionsRejected) throw new ConfigError(`revision guards engaged (${guards.state.engaged ?? "unknown"}): the plan is closed for adaptation; call finish with the partial result`);
+			if (guards.revisionsRejected) {
+				if (guards.state.engaged === "fail-run") {
+					enforceEngagedFailRun();
+					throw new FailRunError("revision guards engaged with fallback 'fail-run': the plan is closed and the run fails instead of finishing with the partial result", { data: { source: "plan_guards" } });
+				}
+				throw new ConfigError(`revision guards engaged (${guards.state.engaged ?? "unknown"}): the plan is closed for adaptation; call finish with the partial result`);
+			}
 			if (vocabulary !== void 0) {
 				for (const op of request.ops) if (op.op === "add_task") {
 					const tag = op.approach ?? op.spec.approach;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/plan",
-  "version": "1.35.0",
+  "version": "1.37.0",
   "description": "Rulvar adaptive orchestration extension: PlanRunner, RunLedger, escalation extensions, ModelLadder configuration.",
   "type": "module",
   "license": "Apache-2.0",
@@ -22,13 +22,13 @@
     "access": "public"
   },
   "dependencies": {
-    "@rulvar/core": "1.35.0"
+    "@rulvar/core": "1.37.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",
     "tsdown": "^0.22.3",
     "typescript": "~6.0.3",
-    "@rulvar/store-sqlite": "1.35.0"
+    "@rulvar/store-sqlite": "1.37.0"
   },
   "repository": {
     "type": "git",