@rulvar/plan 1.6.0 → 1.8.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AdmissionDecision, AgentResult, CanonicalLadderSpec, ChatRequest, Effort, Engine, EntryRef, EscalationDecision, EscalationOptions, HashVersion, IsolationSpec, JournalEntry, JournalStore, Json, KbProposalTrigger, KeyDeriver, LadderSpec, LeasableStore, LineageStats, LogicalTaskId, NodeId, OrchestrateOptions, OrchestratorExtension, ProviderAdapter, ReuseConfig, RunHandle, SchemaSpec, SpawnLineageOpt, TerminationAccountSnapshot, TerminationLimits, ToolDef, TriggerClass, UsageLimits, WireError } from "@rulvar/core";
+import { AdmissionDecision, AdmitRejectReason, AgentResult, CanonicalLadderSpec, ChatRequest, Effort, Engine, EntryRef, EscalationDecision, EscalationOptions, HashVersion, IsolationSpec, JournalEntry, JournalStore, Json, KbProposalTrigger, KeyDeriver, LadderSpec, LeasableStore, LineageStats, LogicalTaskId, NodeId, OrchestrateOptions, OrchestratorExtension, ProviderAdapter, ReuseConfig, RunHandle, SchemaSpec, SpawnLineageOpt, TerminationAccountSnapshot, TerminationLimits, ToolDef, TriggerClass, UsageLimits, WireError } from "@rulvar/core";
 
 //#region src/plan-state.d.ts
 /**
@@ -287,7 +287,16 @@ interface PlanReviseRequest {
 }
 /** The canonical result form (XF-11): DEF-8 shape plus the DEF-2 balance. */
 interface PlanReviseResult {
-  outcomes: RebaseOutcome[];
+  /**
+  * Journaled outcomes, enriched IN THE RESULT ONLY: a dropped
+  * admission_denied op carries its typed reject reason (account,
+  * reserves, minimum correction) so the model can act on it without
+  * digging into the journal. The plan.revision entry stays byte-stable;
+  * the full verdicts live in its `admissions`.
+  */
+  outcomes: Array<RebaseOutcome & {
+    verdictReason?: AdmitRejectReason;
+  }>;
   assignedNodeIds: Record<number, NodeId>;
   planHashAfter: string;
   droppedAll: boolean;
@@ -327,14 +336,14 @@ interface PlanRevisionValue {
   }>;
 }
 /** Engine authorship origins of plan.decision entries. */
-type PlanDecisionOrigin = "escalation-default" | "escalation-class" | "escalation-live" | "no-progress" | "child-result" | "park-landed" | "cancel-landed";
+type PlanDecisionOrigin = "escalation-default" | "escalation-class" | "escalation-live" | "no-progress" | "child-result" | "park-landed" | "cancel-landed" | "dispatch-rejected";
 /** The closed EnginePlanOp set. */
 type EnginePlanOp = {
   kind: "set_node_status";
   nodeId: NodeId;
   from: PlanNodeStatus;
   to: PlanNodeStatus;
-  cause: "child-result" | "no-progress" | "park-landed" | "cancel-landed";
+  cause: "child-result" | "no-progress" | "park-landed" | "cancel-landed" | "dispatch-rejected";
   causeRef: EntryRef; /** The retained checkpoint anchor recorded at park landing (M7-T08). */
   checkpointRef?: EntryRef;
 } | {

package/dist/index.js

@@ -1,4 +1,4 @@
-import { 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, 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
@@ -3077,17 +3077,51 @@ function planRunner(options) {
 			...ladder === void 0 ? {} : ladderDispatchFields(node, spec, ladder)
 		};
 	};
+	/**
+	* A dispatch refused by budget/admission facts that changed AFTER the
+	* op was admitted (another child consumed the shared parent between
+	* turns, a rung ceiling re-resolved differently) lands as a terminal
+	* plan decision: the node fails loudly instead of sitting ready
+	* forever, the other ready nodes still dispatch, and the wake digest
+	* carries the failure to the orchestrator (the v1.7.0 follow-up
+	* review's P1: no stranded node without a dispatch root or terminal
+	* decision). Everything else (engine bugs) still propagates.
+	*/
+	const landDispatchRejection = async (node, from, thrown) => {
+		const message = thrown instanceof Error ? thrown.message : String(thrown);
+		io.emit({
+			type: "log",
+			level: "warn",
+			msg: `plan node ${node.nodeId} failed dispatch admission and lands terminally failed: ${message}`,
+			data: {
+				nodeId: node.nodeId,
+				logicalTaskId: node.logicalTaskId
+			}
+		});
+		await appendPlanDecision("dispatch-rejected", [{
+			kind: "set_node_status",
+			nodeId: node.nodeId,
+			from,
+			to: "failed",
+			cause: "dispatch-rejected",
+			causeRef: Math.max(planCursor, 0)
+		}], Math.max(planCursor, 0));
+	};
+	const isDispatchRejection = (thrown) => thrown instanceof AdmissionRejectedError || thrown instanceof BudgetExhaustedError;
 	/** Dispatches every ready node under its plan/NodeId scope. */
 	const scheduleReady = async () => {
 		for (const node of Object.values(fold.plan.nodes)) {
 			if (node.status === "running" && !dispatched.has(node.nodeId)) {
 				const spec = fold.specs[node.nodeId];
-				if (spec !== void 0) {
+				if (spec !== void 0) try {
 					const { handle } = await io.dispatch(buildDispatchSpec(node, spec), nodeScopeOf(node.nodeId), {
 						nodeId: node.nodeId,
 						logicalTaskId: node.logicalTaskId
 					});
 					dispatched.set(node.nodeId, handle);
+				} catch (thrown) {
+					if (!isDispatchRejection(thrown)) throw thrown;
+					await landDispatchRejection(node, "running", thrown);
 				}
 				continue;
 			}
@@ -3114,10 +3148,17 @@ function planRunner(options) {
 			}
 			const spec = fold.specs[node.nodeId];
 			if (spec === void 0) continue;
-			const { handle } = await io.dispatch(buildDispatchSpec(node, spec), nodeScopeOf(node.nodeId), {
-				nodeId: node.nodeId,
-				logicalTaskId: node.logicalTaskId
-			});
+			let handle;
+			try {
+				({handle} = await io.dispatch(buildDispatchSpec(node, spec), nodeScopeOf(node.nodeId), {
+					nodeId: node.nodeId,
+					logicalTaskId: node.logicalTaskId
+				}));
+			} catch (thrown) {
+				if (!isDispatchRejection(thrown)) throw thrown;
+				await landDispatchRejection(node, "ready", thrown);
+				continue;
+			}
 			dispatched.set(node.nodeId, handle);
 			await appendPlanDecision("child-result", [{
 				kind: "set_node_status",
@@ -3198,6 +3239,14 @@ function planRunner(options) {
 			return { entryRef: entry.seq };
 		},
 		planRevise: async (request) => writeLock.runExclusive(async () => {
+			const withVerdictDetail = (outcomes, admissions) => outcomes.map((outcome, opIndex) => {
+				if (outcome.kind !== "dropped" || outcome.reason !== "admission_denied") return outcome;
+				const verdict = admissions.find((admission) => admission.opIndex === opIndex)?.decision.verdict;
+				return verdict !== void 0 && verdict.kind === "reject" ? {
+					...outcome,
+					verdictReason: verdict.reason
+				} : outcome;
+			});
 			await io.flush();
 			absorbPlan();
 			absorbGuardVerdicts();
@@ -3227,7 +3276,7 @@ function planRunner(options) {
 				}
 				await scheduleReady();
 				return {
-					outcomes: value.outcomes,
+					outcomes: withVerdictDetail(value.outcomes, value.admissions),
 					assignedNodeIds: value.assignedNodeIds,
 					planHashAfter: value.planHashAfter,
 					droppedAll: value.outcomes.every((outcome) => outcome.kind === "dropped"),
@@ -3241,6 +3290,7 @@ function planRunner(options) {
 			const freshNotes = /* @__PURE__ */ new Map();
 			const frozen = io.snapshot().some((candidate) => candidate.kind === "decision" && candidate.value?.decisionType === "orchestrator_budget_cap");
 			const claimedThisRevision = /* @__PURE__ */ new Set();
+			let pendingReserveUsd = 0;
 			const evaluation = rebasePlanRevision(request, {
 				state: fold,
 				frozen,
@@ -3307,13 +3357,47 @@ function planRunner(options) {
 							depth: 1
 						}
 					};
+					const profile = io.profiles[op.spec.agentType];
+					const childAccount = rootScope === "" ? planNodeScope(nodeId) : `${rootScope}/${planNodeScope(nodeId)}`;
+					const ladder = canonicalLadderOf(profile);
+					const dispatchCeilingUsd = (() => {
+						if (ladder !== void 0) {
+							const startTier = clampStartTier(ladder, op.spec.model_hint?.startTier);
+							const raises = op.lineage === void 0 ? 0 : requireAccount().rungIndexOf(op.lineage.continues);
+							const rung = ladder.rungs[executingRungOf(ladder, startTier, raises)];
+							if (rung?.maxCostUsd !== void 0) return rung.maxCostUsd;
+						}
+						return op.spec.budgetUsd;
+					})();
+					if (profile?.estCost !== void 0 && dispatchCeilingUsd !== void 0 && profile.estCost > dispatchCeilingUsd) return {
+						verdict: {
+							kind: "reject",
+							reason: {
+								code: "reserve_exceeds_budget",
+								agentType: op.spec.agentType,
+								childAccount,
+								estCostUsd: profile.estCost,
+								resolvedReserveUsd: Math.min(profile.estCost, dispatchCeilingUsd),
+								childCeilingUsd: dispatchCeilingUsd,
+								minimumBudgetUsd: profile.estCost,
+								message: `agent profile '${op.spec.agentType}' declares estCost ${profile.estCost.toFixed(4)} USD, which cannot fit the child ceiling ${dispatchCeilingUsd.toFixed(4)} USD of account '${childAccount}'; raise budgetUsd to at least ${profile.estCost.toFixed(4)} or pick a cheaper profile`
+							}
+						},
+						statsBefore: {
+							spawnsBefore: 0,
+							childrenOfParentBefore: 0,
+							depth: 1
+						}
+					};
 					const admitted = io.admission.admit({
 						origin: "spawn_agent",
 						name: op.spec.agentType,
-						childScope: rootScope === "" ? planNodeScope(nodeId) : `${rootScope}/${planNodeScope(nodeId)}`,
+						childScope: childAccount,
 						parentAccountScope: ROOT_ACCOUNT,
 						nodeKey: planScope,
 						...op.spec.budgetUsd === void 0 ? {} : { budgetUsd: op.spec.budgetUsd },
+						...profile?.estCost === void 0 ? {} : { estCostUsd: profile.estCost },
+						...pendingReserveUsd === 0 ? {} : { pendingReserveUsd },
 						...op.lineage === void 0 ? {} : { lineage: op.lineage },
 						...(op.approach ?? op.spec.approach) === void 0 ? {} : { approach: op.approach ?? op.spec.approach },
 						signature: {
@@ -3322,6 +3406,10 @@ function planRunner(options) {
 						},
 						ladderLength: ladderLengthOf(io.profiles[op.spec.agentType])
 					}, { commitReserve: false });
+					if (admitted.verdict.kind === "admit") pendingReserveUsd += io.admission.projectedDispatchReserveUsd({
+						...profile?.estCost === void 0 ? {} : { estCostUsd: profile.estCost },
+						...op.spec.budgetUsd === void 0 ? {} : { budgetUsd: op.spec.budgetUsd }
+					});
 					const note = freshNotes.get(opIndex);
 					if (note !== void 0 && admitted.verdict.kind === "admit") return {
 						...admitted,
@@ -3335,12 +3423,13 @@ function planRunner(options) {
 				admitUnpark: (op, node) => {
 					const spec = fold.specs[op.nodeId];
 					const wasDispatched = nodeRootOf(op.nodeId) !== void 0;
-					return io.admission.admit({
+					const unparkAdmitted = io.admission.admit({
 						origin: "spawn_agent",
 						name: spec?.agentType ?? "unknown",
 						childScope: nodeScopeOf(op.nodeId),
 						parentAccountScope: ROOT_ACCOUNT,
 						nodeKey: planScope,
+						...pendingReserveUsd === 0 ? {} : { pendingReserveUsd },
 						...wasDispatched ? { lineage: {
 							continues: node.logicalTaskId,
 							causeRef: node.checkpointRef ?? Math.max(planCursor, 1),
@@ -3352,6 +3441,8 @@ function planRunner(options) {
 						},
 						ladderLength: ladderLengthOf(io.profiles[spec?.agentType ?? ""])
 					}, { commitReserve: false });
+					if (unparkAdmitted.verdict.kind === "admit") pendingReserveUsd += io.admission.projectedDispatchReserveUsd({});
+					return unparkAdmitted;
 				},
 				lineageCheck: (continues) => {
 					const index = io.admission.lineage();
@@ -3386,19 +3477,6 @@ function planRunner(options) {
 			consumedRevisionSeqs.add(entry.seq);
 			await io.flush();
 			absorbPlan();
-			await drainGuardVerdicts();
-			await landReuseLinks(entry);
-			await landCancelAbandons(value, entry.seq);
-			await landRevisionEscalations(value);
-			for (const outcome of evaluation.outcomes) {
-				if (outcome.kind === "dropped") continue;
-				const applied = outcome.kind === "applied" ? outcome.op : outcome.applied;
-				if ((applied.op === "cancel_task" || applied.op === "park_task") && applied.requestOnly === true) {
-					const handle = dispatched.get(applied.nodeId);
-					if (handle !== void 0) io.cancel(handle, applied.op === "cancel_task" ? applied.reason : "park_task");
-				}
-			}
-			await scheduleReady();
 			const appliedCount = evaluation.outcomes.filter((o) => o.kind !== "dropped").length;
 			io.emit({
 				type: "plan:revised",
@@ -3415,8 +3493,21 @@ function planRunner(options) {
 				remaining: debit.balanceAfter,
 				phi: requireAccount().phi()
 			});
+			await drainGuardVerdicts();
+			await landReuseLinks(entry);
+			await landCancelAbandons(value, entry.seq);
+			await landRevisionEscalations(value);
+			for (const outcome of evaluation.outcomes) {
+				if (outcome.kind === "dropped") continue;
+				const applied = outcome.kind === "applied" ? outcome.op : outcome.applied;
+				if ((applied.op === "cancel_task" || applied.op === "park_task") && applied.requestOnly === true) {
+					const handle = dispatched.get(applied.nodeId);
+					if (handle !== void 0) io.cancel(handle, applied.op === "cancel_task" ? applied.reason : "park_task");
+				}
+			}
+			await scheduleReady();
 			return {
-				outcomes: evaluation.outcomes,
+				outcomes: withVerdictDetail(evaluation.outcomes, evaluation.admissions),
 				assignedNodeIds: evaluation.assignedNodeIds,
 				planHashAfter: evaluation.planHashAfter,
 				droppedAll: evaluation.droppedAll,
@@ -3510,8 +3601,8 @@ function planRunner(options) {
 					maxDepth: options?.limits?.maxDepth ?? 1,
 					kMax: kMaxOf(io.profiles),
 					runBudgetUsdCeiling: io.runCeilingUsd ?? 0,
-					orchestratorCapUsd: 0,
-					finalizeReserveUsd: 0
+					orchestratorCapUsd: io.orchestratorCapUsd ?? 0,
+					finalizeReserveUsd: io.finalizeReserveUsd ?? 0
 				});
 				const value = buildTerminationInitValue(limits, profileRegistrySnapshotHash(io.profiles));
 				await io.append({

package/package.json

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