@rulvar/core 1.7.0 → 1.9.0

package/dist/index.d.ts

@@ -1800,7 +1800,16 @@ interface ResumeReport {
   misses: number;
   skipped: number;
   reruns: number;
-  /** Journaled operations never consumed by any live call (deleted calls). */
+  /**
+  * Effect roots that genuinely need recovery under the entry-type
+  * pairing rules: dangling dispatches (status 'running' with no
+  * terminal) and suspensions with no resolution, neither consumed by a
+  * live call nor covered by abandon. Complete operations are NEVER
+  * listed: settled roots, single-entry kinds (decisions, facts, plan
+  * and termination entries), and resolved suspensions are whole by
+  * construction. A call deleted from the code is silently skipped and
+  * never re-paid; it appears here only while its effect is dangling.
+  */
   orphaned: number[];
 }
 /**
@@ -1813,6 +1822,8 @@ declare class JournalMatcher {
   private readonly byScope;
   private readonly all;
   private readonly consumed;
+  /** Suspension seqs holding at least one resolution ref-entry. */
+  private readonly resolvedRefs;
   private readonly keyRing;
   private disposition;
   private aliasDisposition?;
@@ -3114,9 +3125,14 @@ interface TerminationLimits {
   kMax: number;
   /** B0; immutable after start, no API including HITL can top up. */
   runBudgetUsdCeiling: number;
-  /** From the orchestrator budget (DEF-7; XF-09). */
+  /**
+  * The resolved orchestrator cap in absolute USD (DEF-7; XF-09),
+  * frozen with the counters. Journals recorded before v1.8 store 0
+  * ("not yet resolved"); for them the orchestrator_budget_reserve
+  * decision is the authority and is recovered on resume.
+  */
   orchestratorCapUsd: number;
-  /** From the orchestrator budget (DEF-7; XF-09). */
+  /** The finalize reserve carved out of the cap; 0 in pre-v1.8 journals. */
   finalizeReserveUsd: number;
 }
 /** Appendix A committed defaults for the countable resources. */
@@ -3441,7 +3457,7 @@ declare class RunBudget {
     parentScope?: string;
     ceilingUsd?: number;
     finalizeReserveUsd?: number;
-    kind?: "orchestrator-cap";
+    kind?: "orchestrator-cap" | "child-allowance";
   }): void;
   /**
   * The diagnostic projection behind a ceiling error: the first CLOSED
@@ -3462,6 +3478,18 @@ declare class RunBudget {
   * fractions never eat finalization money). Undefined when uncapped.
   */
   remainderOf(scope: string): number | undefined;
+  /**
+  * The tightest allowance headroom on the chain of `scope`: the minimum
+  * remainder across 'child-allowance' accounts. An allowance ceiling
+  * bounds the child's LIFETIME spend, so projected admission must never
+  * hold more than this against the chain (the layer-2 mirror lives in
+  * the orchestrator admission's childCeiling clamp): a reserve above
+  * the allowance would deny work that the allowance itself already
+  * bounds. Undefined when no allowance account is on the chain; the
+  * clamp never applies to the run root or an orchestrator cap, whose
+  * headroom is shared money that projected admission must protect.
+  */
+  allowanceHeadroomOf(scope: string): number | undefined;
   /** Layer 3 ceiling signal of the run root; live streams sever through it. */
   get signal(): AbortSignal;
   /** The layer-3 signal of one sub-account's subtree, when it exists. */
@@ -3750,6 +3778,23 @@ type AdmitRejectReason = {
   code: "osc_guard";
   spawnKey: SpawnKey;
   oscillationCount: number;
+} | {
+  /**
+  * The declared estimate cannot fit the child's own ceiling: the
+  * host said the work costs more than the budget buys, so the op
+  * is bounced with the actionable correction BEFORE it changes
+  * plan state or consumes a spawn unit (the v1.7.0 follow-up
+  * review's P1). Heuristic reserves never produce this code; they
+  * clamp to the allowance instead.
+  */
+  code: "reserve_exceeds_budget";
+  agentType: string;
+  childAccount: string;
+  estCostUsd: number;
+  resolvedReserveUsd: number;
+  childCeilingUsd: number;
+  minimumBudgetUsd: number;
+  message: string;
 };
 /** Every spawn origin routed through the single admission point. */
 type SpawnOrigin = "ctx.workflow" | "ctx.orchestrate" | "spawn_agent" | "parallel_agents" | "escalation-decomposition" | "rung-respawn" | "reuse-link";
@@ -3767,6 +3812,13 @@ interface AdmitSpec {
   /** Reserve hint; falls back to the flat engine default. */
   estCostUsd?: number;
   /**
+  * Same-batch reserves already admitted read-only but not yet
+  * committed (a multi-op plan revision): the read-only branch adds
+  * them to this spawn's reserve so every embedded admit of one batch
+  * is dispatchable under the same snapshot, not just the first.
+  */
+  pendingReserveUsd?: number;
+  /**
   * Lineage continuation (DEF-3); absence mints a fresh lineage root. A
   * continuation demands a causeRef: the seq of the entry that caused the
   * rebirth.
@@ -3917,6 +3969,17 @@ declare class AdmissionController {
   * journaled by the caller so replay re-delivers it without
   * re-evaluation.
   */
+  /**
+  * The reserve the DISPATCH layer will actually commit for this spec:
+  * the estimate (or the flat default) clamped by the explicit child
+  * budget when one exists, because only an explicit budget opens a
+  * child-allowance account at dispatch; the childBudgetFraction cap
+  * never materializes as an account and must not shrink the
+  * projection. The token-count-priced estimate of ctx.agent is
+  * unreachable here (async); a divergence there lands as a journaled
+  * dispatch rejection instead of a strand.
+  */
+  projectedDispatchReserveUsd(spec: Pick<AdmitSpec, "estCostUsd" | "budgetUsd">): number;
   admit(spec: AdmitSpec, options?: {
     commitReserve?: boolean;
   }): AdmissionDecision;
@@ -4818,6 +4881,16 @@ interface OrchestratorExtensionIO {
   readonly gates: Record<string, unknown>;
   /** The run USD ceiling (B0), when one exists. */
   readonly runCeilingUsd?: number;
+  /**
+  * The resolved orchestrator cap in absolute USD (DEF-7; XF-09):
+  * min(budget.capUsd, capFraction x B0) on a fresh run, the frozen
+  * orchestrator_budget_reserve dollars on resume. Resolved strictly
+  * before boot so an extension can freeze it into termination.init;
+  * always present under PlanRunner (an unresolvable cap refuses boot).
+  */
+  readonly orchestratorCapUsd?: number;
+  /** The finalize reserve carved out of the cap, resolved with it. */
+  readonly finalizeReserveUsd?: number;
   /** ULID minting for engine-owned identifiers (NodeIds). */
   mintId(): string;
   /**

package/dist/index.js

@@ -5054,6 +5054,8 @@ var JournalMatcher = class {
 	byScope = /* @__PURE__ */ new Map();
 	all = [];
 	consumed = /* @__PURE__ */ new Set();
+	/** Suspension seqs holding at least one resolution ref-entry. */
+	resolvedRefs = /* @__PURE__ */ new Set();
 	keyRing;
 	disposition;
 	aliasDisposition;
@@ -5069,7 +5071,10 @@ var JournalMatcher = class {
 		this.disposition = options?.disposition ?? roundOneDisposition;
 		const terminalsByRef = /* @__PURE__ */ new Map();
 		for (const entry of entries) {
-			if (REF_ENTRY_KINDS.has(entry.kind)) continue;
+			if (REF_ENTRY_KINDS.has(entry.kind)) {
+				if (entry.kind === "resolution" && entry.ref !== void 0) this.resolvedRefs.add(entry.ref);
+				continue;
+			}
 			if (entry.ref !== void 0) terminalsByRef.set(entry.ref, entry);
 		}
 		for (const entry of entries) {
@@ -5246,7 +5251,12 @@ var JournalMatcher = class {
 			misses: this.missesInternal,
 			skipped: this.skippedInternal,
 			reruns: this.rerunsInternal,
-			orphaned: this.all.filter((op) => !this.consumed.has(op.running.seq)).map((op) => op.running.seq)
+			orphaned: this.all.filter((op) => {
+				if (this.consumed.has(op.running.seq) || op.terminal !== void 0) return false;
+				if (op.running.status === "running") return true;
+				if (op.running.status === "suspended") return !this.resolvedRefs.has(op.running.seq);
+				return false;
+			}).map((op) => op.running.seq)
 		};
 	}
 };
@@ -7285,7 +7295,7 @@ var NoProgressDetector = class {
 		return this.streakInternal >= this.threshold;
 	}
 	describe() {
-		return `no-progress abort after ${this.streakInternal} consecutive turns without tool calls or artifact deltas (threshold ${this.threshold}; docs/06 Appendix A)`;
+		return `no-progress abort after ${this.streakInternal} consecutive turns without tool calls or artifact deltas (threshold ${this.threshold}; https://docs.rulvar.com/guide/agents#the-agent-loop-and-turns)`;
 	}
 };
 //#endregion
@@ -9059,6 +9069,26 @@ var RunBudget = class {
 		if (account?.ceilingUsd === void 0) return;
 		return Math.max(0, account.ceilingUsd - account.spentUsd - account.committedReserveUsd - account.finalizeReserveUsd);
 	}
+	/**
+	* The tightest allowance headroom on the chain of `scope`: the minimum
+	* remainder across 'child-allowance' accounts. An allowance ceiling
+	* bounds the child's LIFETIME spend, so projected admission must never
+	* hold more than this against the chain (the layer-2 mirror lives in
+	* the orchestrator admission's childCeiling clamp): a reserve above
+	* the allowance would deny work that the allowance itself already
+	* bounds. Undefined when no allowance account is on the chain; the
+	* clamp never applies to the run root or an orchestrator cap, whose
+	* headroom is shared money that projected admission must protect.
+	*/
+	allowanceHeadroomOf(scope) {
+		let headroom;
+		for (const account of this.chainOf(scope)) {
+			if (account.kind !== "child-allowance" || account.ceilingUsd === void 0) continue;
+			const remainder = Math.max(0, account.ceilingUsd - account.spentUsd - account.committedReserveUsd - account.finalizeReserveUsd);
+			headroom = headroom === void 0 ? remainder : Math.min(headroom, remainder);
+		}
+		return headroom;
+	}
 	/** Layer 3 ceiling signal of the run root; live streams sever through it. */
 	get signal() {
 		return this.root.controller.signal;
@@ -9416,6 +9446,20 @@ var AdmissionController = class {
 	* journaled by the caller so replay re-delivers it without
 	* re-evaluation.
 	*/
+	/**
+	* The reserve the DISPATCH layer will actually commit for this spec:
+	* the estimate (or the flat default) clamped by the explicit child
+	* budget when one exists, because only an explicit budget opens a
+	* child-allowance account at dispatch; the childBudgetFraction cap
+	* never materializes as an account and must not shrink the
+	* projection. The token-count-priced estimate of ctx.agent is
+	* unreachable here (async); a divergence there lands as a journaled
+	* dispatch rejection instead of a strand.
+	*/
+	projectedDispatchReserveUsd(spec) {
+		const base = spec.estCostUsd ?? this.flatReserveUsd;
+		return spec.budgetUsd === void 0 ? base : Math.min(base, spec.budgetUsd);
+	}
 	admit(spec, options) {
 		const commitReserve = options?.commitReserve ?? true;
 		const nodeKey = spec.nodeKey ?? spec.parentAccountScope;
@@ -9502,7 +9546,8 @@ var AdmissionController = class {
 		}
 		else {
 			const remainder = this.budget.remainderOf(spec.parentAccountScope);
-			if (remainder !== void 0 && remainder <= 0) return {
+			const projection = this.projectedDispatchReserveUsd(spec);
+			if (remainder !== void 0 && (remainder <= 0 || remainder < projection + (spec.pendingReserveUsd ?? 0))) return {
 				verdict: {
 					kind: "reject",
 					reason: { code: "budget" }
@@ -10485,7 +10530,8 @@ function createCtx(internals, rootWorkflow) {
 		if (internals.flatReserveUsd !== void 0) reserveOptions.flatReserveUsd = internals.flatReserveUsd;
 		const reserve = internals.pricingOf !== void 0 && internals.pricingOf(loopResolved.ref) === void 0 && opts.estCost === void 0 && profile?.estCost === void 0 ? 0 : admissionReserveUsd(reserveOptions);
 		const budgetAccount = state.budgetScope ?? "run";
-		internals.budget.admitSpawn(reserve, budgetAccount);
+		const allowanceHeadroomUsd = internals.budget.allowanceHeadroomOf(budgetAccount);
+		internals.budget.admitSpawn(allowanceHeadroomUsd === void 0 ? reserve : Math.min(reserve, allowanceHeadroomUsd), budgetAccount);
 		let acquired;
 		if (typeof isolation === "object" && isolation.kind === "worktree") {
 			const acquireInput = {
@@ -11129,7 +11175,10 @@ function createCtx(internals, rootWorkflow) {
 		if (verdict.kind !== "admit") throw new ConfigError(`admission verdict '${verdict.kind}' has no producer before M7 (DEF-5)`);
 		const reserve = verdict.reserve;
 		const openOptions = { parentScope: budgetAccount };
-		if (reserve.childCeilingUsd !== void 0) openOptions.ceilingUsd = reserve.childCeilingUsd;
+		if (reserve.childCeilingUsd !== void 0) {
+			openOptions.ceilingUsd = reserve.childCeilingUsd;
+			openOptions.kind = "child-allowance";
+		}
 		internals.budget.openAccount(childScope, openOptions);
 		const running = danglingRunning ?? await internals.replayer.appendRunning({
 			scope: state.scope,
@@ -11419,6 +11468,8 @@ function makeOrchestratorWorkflow(goal, opts) {
 		const cardText = declaredLadderNames.length === 0 ? profileCard(advertisedProfiles) : `${profileCard(spawnableProfiles)}\nDeclared ladders (tier context for the knowledge card; NOT agentType values, never spawn them): ${declaredLadderNames.join(", ")}.`;
 		const extension = opts?.extension;
 		let orchestratorAccount;
+		/** DEF-2 cap drift found in the sync prologue; emitted after boot. */
+		const pendingCapDrifts = [];
 		let capState;
 		{
 			const runCeiling = internals.budget.accountView(callingState.budgetScope ?? "run")?.ceilingUsd;
@@ -11427,8 +11478,45 @@ function makeOrchestratorWorkflow(goal, opts) {
 			if (fraction > 1) throw new OrchestratorCapConfigError(`capFraction ${String(fraction)} exceeds 1.0 (opting out of the cap is explicit only, up to 1.0 inclusive)`);
 			const fromFraction = runCeiling === void 0 ? void 0 : fraction * runCeiling;
 			const bounds = [spec?.capUsd, fromFraction].filter((bound) => bound !== void 0);
-			if (extension !== void 0 && bounds.length === 0) throw new OrchestratorCapConfigError("the orchestrator cap is unresolvable: the run has no USD ceiling and no explicit budget.capUsd; PlanRunner requires a resolved effectiveCap");
-			if (bounds.length > 0) {
+			const priorReserveDecision = internals.replayer.snapshot().find((entry) => {
+				if (entry.kind !== "decision" || entry.scope !== callingState.scope) return false;
+				return entry.value?.decisionType === "orchestrator_budget_reserve";
+			});
+			if (priorReserveDecision !== void 0) {
+				const frozen = priorReserveDecision.value;
+				const turnEstimateUsd = internals.flatReserveUsd ?? .5;
+				const liveFinalizeReserveUsd = spec?.finalizeReserveUsd ?? (spec?.finalizeTurns ?? 2) * turnEstimateUsd;
+				pendingCapDrifts.push(...bounds.length > 0 && Math.min(...bounds) !== frozen.capUsd ? [{
+					field: "orchestratorCapUsd",
+					frozenValue: frozen.capUsd,
+					liveValue: Math.min(...bounds)
+				}] : [], ...liveFinalizeReserveUsd !== frozen.finalizeReserveUsd ? [{
+					field: "finalizeReserveUsd",
+					frozenValue: frozen.finalizeReserveUsd,
+					liveValue: liveFinalizeReserveUsd
+				}] : [], ...frozen.pricingVersion !== void 0 && frozen.pricingVersion !== (internals.pricingVersion ?? "unpriced") ? [{
+					field: "pricingVersion",
+					frozenValue: frozen.pricingVersion,
+					liveValue: internals.pricingVersion ?? "unpriced"
+				}] : []);
+				orchestratorAccount = callingState.scope === "" ? "orchestrator" : `${callingState.scope}/orchestrator`;
+				internals.budget.openAccount(orchestratorAccount, {
+					parentScope: callingState.budgetScope ?? "run",
+					ceilingUsd: frozen.capUsd,
+					kind: "orchestrator-cap"
+				});
+				if (extension !== void 0) internals.budget.commitFinalizeReserve(orchestratorAccount, frozen.finalizeReserveUsd);
+				capState = {
+					effectiveCapUsd: frozen.capUsd,
+					finalizeReserveUsd: frozen.finalizeReserveUsd,
+					finalizeTurns: frozen.finalizeTurns,
+					turnEstimateUsd,
+					atCap: spec?.atCap ?? "finish-with-partial",
+					source: frozen.source
+				};
+			}
+			if (capState === void 0 && extension !== void 0 && bounds.length === 0) throw new OrchestratorCapConfigError("the orchestrator cap is unresolvable: the run has no USD ceiling and no explicit budget.capUsd; PlanRunner requires a resolved effectiveCap");
+			if (capState === void 0 && bounds.length > 0) {
 				const effectiveCapUsd = Math.min(...bounds);
 				const turnEstimateUsd = internals.flatReserveUsd ?? .5;
 				const finalizeTurns = spec?.finalizeTurns ?? 2;
@@ -11505,7 +11593,10 @@ function makeOrchestratorWorkflow(goal, opts) {
 			const scope = placement?.childScope ?? childScopeOf();
 			if (placement?.ownAccount === true) internals.budget.openAccount(scope, {
 				parentScope: callingState.budgetScope ?? "run",
-				...placement.childCeilingUsd === void 0 ? {} : { ceilingUsd: placement.childCeilingUsd }
+				...placement.childCeilingUsd === void 0 ? {} : {
+					ceilingUsd: placement.childCeilingUsd,
+					kind: "child-allowance"
+				}
 			});
 			const childState = {
 				scope,
@@ -11574,6 +11665,10 @@ function makeOrchestratorWorkflow(goal, opts) {
 			profiles: advertisedProfiles,
 			gates: internals.defaults.gates ?? {},
 			...internals.budget.ceilingUsd === void 0 ? {} : { runCeilingUsd: internals.budget.ceilingUsd },
+			...capState === void 0 ? {} : {
+				orchestratorCapUsd: capState.effectiveCapUsd,
+				finalizeReserveUsd: capState.finalizeReserveUsd
+			},
 			mintId: createCanonicalIdMinter(),
 			random: (key) => runtime.runInScope(callingState, () => Promise.resolve(ctx.random(key))),
 			append: (input) => internals.replayer.appendSinglePhase({
@@ -11831,6 +11926,7 @@ function makeOrchestratorWorkflow(goal, opts) {
 					parentAccountScope: callingState.budgetScope ?? "run",
 					nodeKey: scope,
 					...params.budgetUsd === void 0 ? {} : { budgetUsd: params.budgetUsd },
+					...profile?.estCost === void 0 ? {} : { estCostUsd: profile.estCost },
 					...params.lineage === void 0 ? {} : { lineage: {
 						continues: params.lineage.continues,
 						causeRef: params.lineage.causeRef,
@@ -11994,6 +12090,12 @@ function makeOrchestratorWorkflow(goal, opts) {
 			}
 		};
 		if (extension?.boot !== void 0) await extension.boot(io);
+		for (const drift of pendingCapDrifts) internals.events.emit({
+			type: "termination:config-drift",
+			field: drift.field,
+			frozenValue: drift.frozenValue,
+			liveValue: drift.liveValue
+		}, callingState.spanId);
 		let kbCardText;
 		const appendKbPin = async (decisionType, key) => {
 			const handle = internals.knowledge;
@@ -12037,7 +12139,7 @@ function makeOrchestratorWorkflow(goal, opts) {
 		}
 		const fullCardText = kbCardText === void 0 ? cardText : `${cardText}\n${kbCardText}`;
 		const reserveKey = deriverV2.deriveKey({ kind: "orchestrator-budget-reserve" });
-		if (extension !== void 0 && capState !== void 0 && !internals.replayer.snapshot().some((entry) => entry.kind === "decision" && entry.key === reserveKey)) {
+		if (extension !== void 0 && capState !== void 0 && !internals.replayer.snapshot().some((entry) => entry.kind === "decision" && entry.scope === callingState.scope && entry.key === reserveKey)) {
 			const initRef = internals.replayer.snapshot().find((entry) => entry.kind === "termination.init")?.seq;
 			await internals.replayer.appendSinglePhase({
 				scope: callingState.scope,

package/package.json

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