@rulvar/planner 1.11.0 → 1.12.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { CompiledWorkflow, Ctx, Engine, InMemoryStore, JournalEntry, Json, ModelSpec, RunHandle, ScriptRejected, ScriptRunner } from "@rulvar/core";
+import { CompiledWorkflow, Ctx, Engine, InMemoryStore, JournalEntry, Json, ModelSpec, RunHandle, RunOptions, ScriptRejected, ScriptRunner } from "@rulvar/core";
 
 //#region src/compile.d.ts
 /**
@@ -49,6 +49,30 @@ interface PlanOptions {
   profiles?: string[];
   /** Self-repair rounds from JSON diagnostics; default 3 (Appendix A). */
   repairRounds?: number;
+  /**
+  * Run options of the planning conversation itself, applied at GENESIS
+  * only: the first plan() of a goal starts the journal with them, and
+  * budgetUsd becomes the run's immutable ceiling B0, recorded in
+  * RunMeta. A later plan() of the same goal resumes the existing
+  * journal under its RECORDED ceiling: a differing explicit budgetUsd
+  * warns (RULVAR_PLAN_BUDGET_DRIFT) and never tops up or replaces the
+  * frozen value, and limits/deadlineAt/signal do not apply to a
+  * resumed journal (core resume semantics; cancel through the handle).
+  * The runId stays goal-derived (planRunIdOf) and is not overridable.
+  * Absent options, the planning run is UNBOUNDED, as before.
+  */
+  run?: Pick<RunOptions, "budgetUsd" | "limits" | "deadlineAt" | "signal">;
+}
+interface RunPlannedOptions {
+  /** Options of the planning conversation (see plan()). */
+  plan?: PlanOptions;
+  /**
+  * RunOptions of the generated workflow's execution run, passed to
+  * engine.run verbatim (budgetUsd here is the EXECUTION ceiling,
+  * independent of the planning ceiling). Absent, the execution run is
+  * UNBOUNDED, as before.
+  */
+  run?: RunOptions;
 }
 interface PlanResult {
   source: string;
@@ -78,8 +102,11 @@ declare function plan(engine: Engine, goal: string, o?: PlanOptions): Promise<Pl
 /**
 * plan-then-run in one call (amended during M6-T05:
 * the composition is async because planning itself is a run).
+* options.plan bounds the planning conversation, options.run bounds the
+* generated workflow's execution; the two ceilings are independent, and
+* the bare form without options runs BOTH legs unbounded, as before.
 */
-declare function runPlanned(engine: Engine, goal: string, args?: Json): Promise<RunHandle<unknown>>;
+declare function runPlanned(engine: Engine, goal: string, args?: Json, options?: RunPlannedOptions): Promise<RunHandle<unknown>>;
 //#endregion
 //#region src/cassettes.d.ts
 /** The M3-convention cassette normalization: wall clock and spans only. */

package/dist/index.js

@@ -188,7 +188,18 @@ async function plan(engine, goal, o) {
 		repairRounds,
 		...o?.model === void 0 ? {} : { model: o.model }
 	};
-	const outcome = await engine.resume(planRunIdOf(goal), planWorkflow, { args }).result;
+	const runId = planRunIdOf(goal);
+	const recorded = (await engine.stores.journal.listRuns()).find((meta) => meta.runId === runId);
+	const existing = recorded !== void 0 || (await engine.stores.journal.load(runId)).length > 0;
+	const requested = o?.run?.budgetUsd;
+	if (existing && requested !== void 0 && recorded?.budgetUsd !== requested) process.emitWarning(`plan: run '${runId}' already has a planning journal ` + (recorded?.budgetUsd === void 0 ? "with no recorded budget ceiling" : `with its ceiling frozen at $${String(recorded.budgetUsd)}`) + `; the requested budgetUsd ${String(requested)} does not apply (delete the run or plan a new goal to change the ceiling)`, {
+		code: "RULVAR_PLAN_BUDGET_DRIFT",
+		type: "RulvarWarning"
+	});
+	const outcome = await (existing ? engine.resume(runId, planWorkflow, { args }) : engine.run(planWorkflow, args, {
+		runId,
+		...o?.run
+	})).result;
 	if (outcome.status !== "ok" || outcome.value === void 0) {
 		const wire = outcome.error;
 		throw new ScriptRejected(`plan: the planner run settled '${outcome.status}'${wire === void 0 ? "" : `: ${wire.message}`}`, { data: {
@@ -207,10 +218,13 @@ async function plan(engine, goal, o) {
 /**
 * plan-then-run in one call (amended during M6-T05:
 * the composition is async because planning itself is a run).
+* options.plan bounds the planning conversation, options.run bounds the
+* generated workflow's execution; the two ceilings are independent, and
+* the bare form without options runs BOTH legs unbounded, as before.
 */
-async function runPlanned(engine, goal, args) {
-	const planned = await plan(engine, goal);
-	return engine.run(planned.workflow, args ?? null);
+async function runPlanned(engine, goal, args, options) {
+	const planned = await plan(engine, goal, options?.plan);
+	return engine.run(planned.workflow, args ?? null, options?.run);
 }
 //#endregion
 //#region src/sandbox-runner.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/planner",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "Rulvar flagship hybrid mode: plan agent, compileScript, WorkerSandboxRunner, self-repair loop.",
   "type": "module",
   "license": "Apache-2.0",
@@ -23,14 +23,14 @@
   },
   "dependencies": {
     "eslint": "^9.39.4",
-    "eslint-plugin-rulvar": "1.11.0",
-    "@rulvar/core": "1.11.0"
+    "@rulvar/core": "1.12.0",
+    "eslint-plugin-rulvar": "1.12.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",
     "tsdown": "^0.22.3",
     "typescript": "~6.0.3",
-    "@rulvar/testing": "1.11.0"
+    "@rulvar/testing": "1.12.0"
   },
   "repository": {
     "type": "git",