@rulvar/core 1.223.0 → 1.224.0

package/dist/index.d.ts

@@ -7623,8 +7623,10 @@ interface RunOptions {
   * used to be per-invocation and unrecorded, so a resumed segment
   * silently ran without the bound the original invocation declared
   * (the seventeenth comparison benchmark's top FinOps gap). A run
-  * started without the cap stays uncapped for its whole life, and
-  * ResumeOptions deliberately has no field to override it.
+  * started without the cap stays uncapped for its whole life unless
+  * a host changes the posture through the explicit, validated,
+  * journaled ResumeOptions.run override (RV2208); nothing changes it
+  * silently.
   */
   maxInFlightExposureUsd?: number;
   /**
@@ -7637,7 +7639,9 @@ interface RunOptions {
   * and `allowUnpriced` (exact model refs the host KNOWS are free,
   * the explicit exception). Recorded in RunMeta at genesis and
   * restored on every resume, the exposure cap's rule (RV1504): a
-  * FinOps posture a resumed segment silently drops is not a posture.
+  * FinOps posture a resumed segment silently drops is not a posture
+  * (and unlike the two ceilings, ResumeOptions.run has no field for
+  * this gate: pricing hygiene is not a per-segment decision).
   * Absent by default: dispatch behavior stays byte identical, and an
   * unpriced model keeps debiting nothing, the documented ceiling
   * hole this mode exists to close.
@@ -7711,6 +7715,27 @@ interface ResumeOptions {
   * meta/blob surfaces remain advisory (the fenced run state RFC).
   */
   lease?: Lease;
+  /**
+  * Ceiling overrides for the resumed segment and the run's remaining
+  * life (RV2208). The RV1504 rule stands: the RunMeta-recorded
+  * posture is what a bare resume restores; this field is the ONE
+  * explicit way to change that posture after genesis. Each supplied
+  * value is validated exactly like its RunOptions counterpart,
+  * applied to this segment's budget, written back by the segment's
+  * first meta write (a LATER bare resume restores the overridden
+  * posture, not the genesis one), and journaled as a
+  * `run_budget_override` decision naming the recorded and applied
+  * values and the settled spend it was judged against. A `budgetUsd`
+  * below the journal's settled spend refuses typed before ownership,
+  * meta, or any append: such a ceiling would exhaust the segment
+  * before its first turn and read like a fresh money death. Absent
+  * fields keep the recorded values; an absent object keeps the
+  * historical behavior byte for byte.
+  */
+  run?: {
+    budgetUsd?: number;
+    maxInFlightExposureUsd?: number;
+  };
 }
 interface ResumeHandle<R> extends RunHandle<R> {
   /** Resolves at settle with the replay accounting. */
@@ -7726,7 +7751,9 @@ interface Engine {
   * A compiled run resumes WITHOUT wf: the engine rehydrates the
   * persisted source pinned by workflowHash; supplying a compiled wf
   * whose source hash differs from the recorded one is a typed
-  * ConfigError (M6-T02).
+  * ConfigError (M6-T02). ResumeOptions.run (RV2208) overrides the
+  * recorded budget ceilings for the run's remaining life, with a
+  * journaled decision and a typed floor at the settled spend.
   */
   resume<A, R>(runId: string, wf?: Workflow<A, R> | CompiledWorkflow, options?: ResumeOptions): ResumeHandle<R>;
   /**

package/dist/index.js

@@ -26541,8 +26541,8 @@ function createEngine(options) {
 		});
 		const rootSpanId = spans.mint();
 		let budgetSeed;
-		const ceilingUsd = opts?.budgetUsd ?? resumeCtx?.budgetUsd;
-		const exposureCapUsd = opts?.maxInFlightExposureUsd ?? resumeCtx?.maxInFlightExposureUsd;
+		const ceilingUsd = opts?.budgetUsd ?? resumeCtx?.budgetOverride?.budgetUsd ?? resumeCtx?.budgetUsd;
+		const exposureCapUsd = opts?.maxInFlightExposureUsd ?? resumeCtx?.budgetOverride?.maxInFlightExposureUsd ?? resumeCtx?.maxInFlightExposureUsd;
 		const strictPricing = opts?.strictPricing === void 0 ? resumeCtx?.strictPricing : opts.strictPricing === true ? {} : opts.strictPricing === false ? void 0 : {
 			...opts.strictPricing.maxRatesAgeDays === void 0 ? {} : { maxRatesAgeDays: opts.strictPricing.maxRatesAgeDays },
 			...opts.strictPricing.allowUnpriced === void 0 ? {} : { allowUnpriced: [...opts.strictPricing.allowUnpriced] }
@@ -26590,6 +26590,8 @@ function createEngine(options) {
 				agentsSpawned: prior.agentsSpawned,
 				accounts: accountSpendFromJournal(replayer.snapshot(), priorPriceUsd)
 			};
+			const overrideCeilingUsd = resumeCtx.budgetOverride?.budgetUsd;
+			if (overrideCeilingUsd !== void 0 && budgetSeed.usd > overrideCeilingUsd) throw new ConfigError(`ResumeOptions.run.budgetUsd ${String(overrideCeilingUsd)} is below the ${budgetSeed.usd.toFixed(4)} USD the journal already records as settled spend; a ceiling below spent exhausts the resumed segment before its first turn. Pass a value at or above the recorded spend, or resume without the override`);
 		}
 		const controller = new AbortController();
 		let cancelReason;
@@ -26785,6 +26787,34 @@ function createEngine(options) {
 			let wireError;
 			let pending = [];
 			if (compiled !== void 0 && resumeCtx?.strict !== true) await transcripts.put(workflowSourceRef(runId), new TextEncoder().encode(compiled.source), segmentLease.current);
+			if (resumeCtx?.budgetOverride !== void 0 && resumeCtx.strict !== true) {
+				const override = resumeCtx.budgetOverride;
+				await replayer.appendSinglePhase({
+					scope: "",
+					key: deriverV2.deriveKey({
+						kind: "run-budget-override",
+						segment: segmentsBefore + 1
+					}),
+					kind: "decision",
+					status: "ok",
+					spanId: rootSpanId,
+					site: "run-budget-override",
+					value: {
+						decisionType: "run_budget_override",
+						source: "resume-options",
+						segment: segmentsBefore + 1,
+						...override.budgetUsd === void 0 ? {} : { budgetUsd: {
+							recorded: resumeCtx.budgetUsd ?? null,
+							applied: override.budgetUsd
+						} },
+						...override.maxInFlightExposureUsd === void 0 ? {} : { maxInFlightExposureUsd: {
+							recorded: resumeCtx.maxInFlightExposureUsd ?? null,
+							applied: override.maxInFlightExposureUsd
+						} },
+						...budgetSeed === void 0 ? {} : { settledSpendUsd: budgetSeed.usd }
+					}
+				});
+			}
 			await putMeta("running");
 			bus.emit({
 				type: "run:start",
@@ -27029,6 +27059,8 @@ function createEngine(options) {
 			previewResolve = resolve;
 		});
 		const handlePromise = (async () => {
+			if (resumeOptions?.run?.budgetUsd !== void 0) requireNonNegativeNumber(resumeOptions.run.budgetUsd, "ResumeOptions.run.budgetUsd");
+			if (resumeOptions?.run?.maxInFlightExposureUsd !== void 0) requireNonNegativeNumber(resumeOptions.run.maxInFlightExposureUsd, "ResumeOptions.run.maxInFlightExposureUsd");
 			const meta = await readRunMeta(journal, runId);
 			let supplied = wf;
 			if (supplied === void 0 && meta?.workflowSourceRef === void 0) {
@@ -27070,12 +27102,18 @@ function createEngine(options) {
 				code: "RULVAR_LEGACY_CACHE_SEMANTICS",
 				type: "RulvarWarning"
 			});
+			const runOverride = resumeOptions?.run;
+			const budgetOverride = runOverride === void 0 || runOverride.budgetUsd === void 0 && runOverride.maxInFlightExposureUsd === void 0 ? void 0 : {
+				...runOverride.budgetUsd === void 0 ? {} : { budgetUsd: runOverride.budgetUsd },
+				...runOverride.maxInFlightExposureUsd === void 0 ? {} : { maxInFlightExposureUsd: runOverride.maxInFlightExposureUsd }
+			};
 			return run(bound, resumeOptions?.args, void 0, {
 				runId,
 				priorEntries,
 				strict: resumeOptions?.dryRun ?? false,
 				invalidate: resumeOptions?.invalidate ?? [],
 				...resumeOptions?.lease === void 0 ? {} : { lease: resumeOptions.lease },
+				...budgetOverride === void 0 ? {} : { budgetOverride },
 				...typeof meta?.budgetUsd === "number" ? { budgetUsd: meta.budgetUsd } : {},
 				...typeof meta?.maxInFlightExposureUsd === "number" ? { maxInFlightExposureUsd: meta.maxInFlightExposureUsd } : {},
 				...typeof meta?.strictPricing === "object" && meta.strictPricing !== null ? { strictPricing: meta.strictPricing } : {},

package/package.json

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