@rulvar/core 1.201.0 → 1.203.0

package/dist/index.d.ts

@@ -6199,6 +6199,25 @@ declare class RunBudget {
   /** Live dispatch estimates held by reserveTurnExposure (RV711). */
   private inFlightExposureUsd;
   /**
+  * The same live estimates attributed to their holders (RV2001): one
+  * entry per holder scope with a nonzero balance, kept in lockstep
+  * with the scalar above by every acquire and release. The holder is
+  * the agent invocation the dispatch belongs to, so a terminal can
+  * return whatever its agent still holds; entries at zero are removed,
+  * making the map size the live holder count.
+  */
+  private readonly exposureHolds;
+  /**
+  * Live holds taken without a holder attribution (a direct caller of
+  * reserveTurnExposure): counted so the zero-holders snap below knows
+  * when NOTHING is held. Subtraction leaves float residue (three 0.18
+  * releases leave 5.5e-17), and a residue above zero would park the
+  * exposure wait on money nobody holds, the epsilon-scale rebirth of
+  * the very deadlock RV2001 closes; when the last hold of any kind
+  * releases, the scalar snaps to exactly zero.
+  */
+  private unattributedHoldCount;
+  /**
   * Waiters parked on the next exposure release (RV1902): the
   * orchestrate root's dispatch waits out a transient refusal here
   * instead of settling a budget error. Notified (and self-removed)
@@ -6418,7 +6437,37 @@ declare class RunBudget {
   * (committedReserveUsd) stay out of the formula, because a child's
   * lifetime reserve and its own turn exposure would double-count.
   */
-  reserveTurnExposure(servedBy: ModelRef, estimatedInputTokens: number, plannedOutputTokens: number): (() => void) | undefined;
+  reserveTurnExposure(servedBy: ModelRef, estimatedInputTokens: number, plannedOutputTokens: number, holderScope?: string): (() => void) | undefined;
+  /**
+  * The one release chokepoint of the exposure scalar (RV2001):
+  * subtracts, snaps to exactly zero when no hold of any kind remains
+  * (float subtraction leaves residue, and a residue would park the
+  * exposure wait on money nobody holds), and wakes the parked
+  * waiters. Spend never shrinks, so releases stay the only wake
+  * source that can turn a refusal into a fit.
+  */
+  private settleExposureRelease;
+  /**
+  * The terminal backstop of the exposure surface (RV2001, the third
+  * parity rerun's quiescence deadlock): EVERY terminal of an agent
+  * invocation (ok, error, exhausted, cancelled) returns whatever live
+  * dispatch estimates that holder still has to the exposure budget.
+  * The attempt settle owns the per-hold closure in a finally, so this
+  * usually finds nothing; the parity crash proved a dispatch path can
+  * die without its closure (three killed children left 0.478 USD of
+  * live estimates parked against the cap forever, and the root's
+  * exposure wait starved on money no live dispatch was holding). A
+  * real release wakes the parked waiters exactly like the closure
+  * does; a holder with nothing held is a free no-op. Returns the USD
+  * actually returned.
+  */
+  releaseExposureHolder(holderScope: string): number;
+  /**
+  * Live exposure holders: agents with a nonzero held balance (RV2001).
+  * Zero with live waiters means nothing can ever release, the drained
+  * signal the quiescence machinery keys on.
+  */
+  get liveExposureHolderCount(): number;
   /** Live in-flight exposure currently held by open dispatches (RV1902). */
   get liveExposureUsd(): number;
   /**

package/dist/index.js

@@ -13523,6 +13523,25 @@ var RunBudget = class {
 	/** Live dispatch estimates held by reserveTurnExposure (RV711). */
 	inFlightExposureUsd = 0;
 	/**
+	* The same live estimates attributed to their holders (RV2001): one
+	* entry per holder scope with a nonzero balance, kept in lockstep
+	* with the scalar above by every acquire and release. The holder is
+	* the agent invocation the dispatch belongs to, so a terminal can
+	* return whatever its agent still holds; entries at zero are removed,
+	* making the map size the live holder count.
+	*/
+	exposureHolds = /* @__PURE__ */ new Map();
+	/**
+	* Live holds taken without a holder attribution (a direct caller of
+	* reserveTurnExposure): counted so the zero-holders snap below knows
+	* when NOTHING is held. Subtraction leaves float residue (three 0.18
+	* releases leave 5.5e-17), and a residue above zero would park the
+	* exposure wait on money nobody holds, the epsilon-scale rebirth of
+	* the very deadlock RV2001 closes; when the last hold of any kind
+	* releases, the scalar snaps to exactly zero.
+	*/
+	unattributedHoldCount = 0;
+	/**
 	* Waiters parked on the next exposure release (RV1902): the
 	* orchestrate root's dispatch waits out a transient refusal here
 	* instead of settling a budget error. Notified (and self-removed)
@@ -13920,7 +13939,7 @@ var RunBudget = class {
 	* (committedReserveUsd) stay out of the formula, because a child's
 	* lifetime reserve and its own turn exposure would double-count.
 	*/
-	reserveTurnExposure(servedBy, estimatedInputTokens, plannedOutputTokens) {
+	reserveTurnExposure(servedBy, estimatedInputTokens, plannedOutputTokens, holderScope) {
 		const cap = this.maxInFlightExposureUsd;
 		if (cap === void 0) return;
 		const pricing = this.pricingOf?.(servedBy);
@@ -13941,14 +13960,69 @@ var RunBudget = class {
 			estimateUsd
 		} });
 		this.inFlightExposureUsd += estimateUsd;
+		if (estimateUsd > 0) if (holderScope === void 0) this.unattributedHoldCount += 1;
+		else this.exposureHolds.set(holderScope, (this.exposureHolds.get(holderScope) ?? 0) + estimateUsd);
 		let released = false;
 		return () => {
 			if (released) return;
 			released = true;
-			this.inFlightExposureUsd = Math.max(0, this.inFlightExposureUsd - estimateUsd);
-			for (const waiter of [...this.exposureWaiters]) waiter();
+			let amount = estimateUsd;
+			if (estimateUsd > 0) if (holderScope === void 0) this.unattributedHoldCount = Math.max(0, this.unattributedHoldCount - 1);
+			else {
+				const held = this.exposureHolds.get(holderScope) ?? 0;
+				amount = Math.min(amount, held);
+				const next = held - amount;
+				if (next <= 0) this.exposureHolds.delete(holderScope);
+				else this.exposureHolds.set(holderScope, next);
+			}
+			this.settleExposureRelease(amount);
 		};
 	}
+	/**
+	* The one release chokepoint of the exposure scalar (RV2001):
+	* subtracts, snaps to exactly zero when no hold of any kind remains
+	* (float subtraction leaves residue, and a residue would park the
+	* exposure wait on money nobody holds), and wakes the parked
+	* waiters. Spend never shrinks, so releases stay the only wake
+	* source that can turn a refusal into a fit.
+	*/
+	settleExposureRelease(amountUsd) {
+		this.inFlightExposureUsd = Math.max(0, this.inFlightExposureUsd - amountUsd);
+		if (this.exposureHolds.size === 0 && this.unattributedHoldCount === 0) this.inFlightExposureUsd = 0;
+		for (const waiter of [...this.exposureWaiters]) waiter();
+	}
+	/**
+	* The terminal backstop of the exposure surface (RV2001, the third
+	* parity rerun's quiescence deadlock): EVERY terminal of an agent
+	* invocation (ok, error, exhausted, cancelled) returns whatever live
+	* dispatch estimates that holder still has to the exposure budget.
+	* The attempt settle owns the per-hold closure in a finally, so this
+	* usually finds nothing; the parity crash proved a dispatch path can
+	* die without its closure (three killed children left 0.478 USD of
+	* live estimates parked against the cap forever, and the root's
+	* exposure wait starved on money no live dispatch was holding). A
+	* real release wakes the parked waiters exactly like the closure
+	* does; a holder with nothing held is a free no-op. Returns the USD
+	* actually returned.
+	*/
+	releaseExposureHolder(holderScope) {
+		const held = this.exposureHolds.get(holderScope) ?? 0;
+		if (held <= 0) {
+			this.exposureHolds.delete(holderScope);
+			return 0;
+		}
+		this.exposureHolds.delete(holderScope);
+		this.settleExposureRelease(held);
+		return held;
+	}
+	/**
+	* Live exposure holders: agents with a nonzero held balance (RV2001).
+	* Zero with live waiters means nothing can ever release, the drained
+	* signal the quiescence machinery keys on.
+	*/
+	get liveExposureHolderCount() {
+		return this.exposureHolds.size;
+	}
 	/** Live in-flight exposure currently held by open dispatches (RV1902). */
 	get liveExposureUsd() {
 		return this.inFlightExposureUsd;
@@ -17761,7 +17835,7 @@ function createCtx(internals, rootWorkflow) {
 				remainingUsd: () => internals.budget.remainingUsd(budgetAccount),
 				...internals.budget.strictPricing === void 0 ? {} : { assertPricedDispatch: (servedBy) => internals.budget.assertPricedDispatch(servedBy) },
 				...internals.budget.maxInFlightExposureUsd === void 0 ? {} : {
-					admitTurnExposure: (servedBy, estimatedInputTokens, plannedOutputTokens) => internals.budget.reserveTurnExposure(servedBy, estimatedInputTokens, plannedOutputTokens),
+					admitTurnExposure: (servedBy, estimatedInputTokens, plannedOutputTokens) => internals.budget.reserveTurnExposure(servedBy, estimatedInputTokens, plannedOutputTokens, `agent:${running.seq}`),
 					awaitExposureRelease: (signal) => internals.budget.awaitExposureRelease(signal),
 					liveExposureUsd: () => internals.budget.liveExposureUsd
 				},
@@ -17865,6 +17939,7 @@ function createCtx(internals, rootWorkflow) {
 			}, spanId), branchOrRunSignal);
 		} finally {
 			exitActivity?.();
+			internals.budget.releaseExposureHolder(`agent:${running.seq}`);
 		}
 		internals.budget.releaseReserve(reserve, budgetAccount);
 		const declaredRules = internals.quota?.declaredRules;

package/package.json

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