@rulvar/plan 1.34.0 → 1.36.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
@@ -923,6 +923,49 @@ function cascadeOf(plan, root) {
 }
 //#endregion
 //#region src/guards.ts
+/**
+* RevisionGuards, the oscillation detector, and hysteresis (M7-T06).
+*
+* Guide: https://docs.rulvar.com/guide/adaptive-orchestration
+* (DEF-8; DEF-2/DEF-5 interactions). The guards are non-HITL and
+* terminating: a human in the loop is NEVER required for a run to end.
+* Every guard verdict is a decision entry written strictly BEFORE its
+* effects; verdict state is a pure fold of those entries, so replay
+* re-derives the same freezes with zero live calls.
+*
+* Three detectors:
+*
+* - droppedRevisionStreak: `effectiveDroppedStreak` (the hashed counter
+*   plus trailing bad_base entries) reaching `droppedRevisionLimit`
+*   (default 3) fires the configured terminating fallback
+*   (reject-revision -> finish-with-partial -> fail-run; default
+*   finish-with-partial).
+* - Oscillation: keyed on approachSigCoarse ACROSS LogicalTaskId
+*   boundaries (a content-identical rebirth under a fresh lineage root
+*   is still flagged): a re-add after a severing cancel of the same
+*   coarse signature counts one oscillation; at the per-key limit
+*   further re-adds FREEZE (the per-SpawnKey osc_guard of DEF-5 lands
+*   in M7-T07 and keys the DedupIndex instead).
+* - Stall replans: hard-bounded per run; the streak already excludes
+*   transient and environment classes.
+*
+* Hysteresis on almost-done nodes is structural: park and cancel against
+* RUNNING nodes only ever land as boundary flags (requestOnly), so a
+* nearly-finished child is never killed mid-turn, and park/unpark churn
+* feeds the oscillation counter.
+*/
+/**
+* Local mirror of the core numeric-intake idiom (v1.34.0 review P2-3):
+* guard limits are compared with `<` and `!==`, and every comparison
+* with NaN is false, so an unvalidated NaN limit made the dropped and
+* oscillation guards trip immediately and the stall cap never trip.
+*/
+function requireCount(value, site, min) {
+	if (typeof value !== "number" || !Number.isInteger(value) || value < min) throw new ConfigError(`${site} must be ${min === 1 ? "a positive integer" : "a nonnegative integer"}; got ${String(value)}`);
+}
+function requireGuardFraction(value, site) {
+	if (typeof value !== "number" || !Number.isFinite(value) || value <= 0 || value > 1) throw new ConfigError(`${site} must be a fraction in (0, 1]; got ${String(value)}`);
+}
 /** Appendix A: osc_guard reject threshold per key (shared default). */
 const DEFAULT_MAX_OSCILLATIONS_PER_KEY = 2;
 /** The hard per-run stall replan bound. */
@@ -947,6 +990,10 @@ var RevisionGuards = class {
 	frozen = /* @__PURE__ */ new Set();
 	stallReplans = 0;
 	constructor(options) {
+		if (options?.droppedRevisionLimit !== void 0) requireCount(options.droppedRevisionLimit, "RevisionGuards droppedRevisionLimit", 1);
+		if (options?.maxOscillationsPerKey !== void 0) requireCount(options.maxOscillationsPerKey, "RevisionGuards maxOscillationsPerKey", 1);
+		if (options?.stallReplanCap !== void 0) requireCount(options.stallReplanCap, "RevisionGuards stallReplanCap", 0);
+		if (options?.maxAbandonedNetUsdFraction !== void 0) requireGuardFraction(options.maxAbandonedNetUsdFraction, "RevisionGuards maxAbandonedNetUsdFraction");
 		this.fallback = options?.fallback ?? "finish-with-partial";
 		this.droppedRevisionLimit = options?.droppedRevisionLimit ?? 3;
 		this.maxOscillationsPerKey = options?.maxOscillationsPerKey ?? 2;
@@ -1982,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()) {
@@ -1993,6 +2060,7 @@ function planRunner(options) {
 			}
 			guardCursor = entry.seq;
 		}
+		enforceEngagedFailRun();
 	};
 	/**
 	* Appends fold-fired verdicts strictly BEFORE their effects; a
@@ -2018,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({
@@ -3293,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.34.0",
+  "version": "1.36.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.34.0"
+    "@rulvar/core": "1.36.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",
     "tsdown": "^0.22.3",
     "typescript": "~6.0.3",
-    "@rulvar/store-sqlite": "1.34.0"
+    "@rulvar/store-sqlite": "1.36.0"
   },
   "repository": {
     "type": "git",