@rulvar/plan 1.33.0 → 1.35.0

package/dist/index.js

@@ -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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/plan",
-  "version": "1.33.0",
+  "version": "1.35.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.33.0"
+    "@rulvar/core": "1.35.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",
     "tsdown": "^0.22.3",
     "typescript": "~6.0.3",
-    "@rulvar/store-sqlite": "1.33.0"
+    "@rulvar/store-sqlite": "1.35.0"
   },
   "repository": {
     "type": "git",