@rulvar/cli 1.16.1 → 1.17.0

package/dist/{io-Bex4Du1t.js → io-Dp2LeOi7.js}

@@ -1,8 +1,8 @@
 import { ConfigError, FileModelKnowledgeStore, INBOX_PROPOSAL_TTL_DAYS, JsonlFileStore, claimExpired, claimExpiry, compilePermissionPreset, costReportFromJournal, createEngine, parseModelRef, priceUsdOf, proposalStatement, remeasureQueue, resolvePricing, runProfile } from "@rulvar/core";
-import { parseArgs } from "node:util";
 import { join, resolve } from "node:path";
 import { existsSync, statSync } from "node:fs";
 import { pathToFileURL } from "node:url";
+import { parseArgs } from "node:util";
 import { createInterface } from "node:readline";
 //#region src/config.ts
 /**
@@ -302,6 +302,254 @@ function reportOutcome(outcome, io) {
 	}
 }
 //#endregion
+//#region src/grammar.ts
+/**
+* The canonical CLI grammar as data (v1.16.2 review P3-1): one
+* structure generates the help block, every per-command usage line,
+* and the docs contract test, so the three surfaces can never drift
+* apart again. Parsing goes through parseCommand, which converts
+* node:util parseArgs failures into the fail-loud ConfigError grammar
+* the CLI documents (v1.16.2 review P2-1): nothing is ignored; unknown
+* flags, duplicate value flags, mutually exclusive pairs, and wrong
+* positional arity all fail naming the canonical usage.
+*/
+const ARGS = {
+	name: "args",
+	placeholder: "JSON"
+};
+const STORE = {
+	name: "store",
+	placeholder: "PATH"
+};
+/**
+* Every command of the canonical grammar (no aliases in v1). The help
+* block, the per-command usage errors, and the docs grammar block in
+* docs/guide/cli.md all derive from this table; the docs contract test
+* compares them literally.
+*/
+const GRAMMAR = {
+	run: {
+		command: "run",
+		positionals: ["<file|name>"],
+		flags: [
+			ARGS,
+			STORE,
+			{
+				name: "budget-usd",
+				placeholder: "N"
+			},
+			{
+				name: "profile",
+				placeholder: "NAME"
+			}
+		]
+	},
+	resume: {
+		command: "resume",
+		positionals: ["<runId>"],
+		flags: [ARGS, STORE]
+	},
+	"runs ls": {
+		command: "runs ls",
+		positionals: [],
+		flags: [STORE],
+		note: "(no aliases in v1)"
+	},
+	inspect: {
+		command: "inspect",
+		positionals: ["<runId>"],
+		flags: [STORE]
+	},
+	plan: {
+		command: "plan",
+		positionals: ["\"<goal>\""],
+		flags: [
+			{
+				name: "planning-budget-usd",
+				placeholder: "N"
+			},
+			{
+				name: "budget-usd",
+				placeholder: "N"
+			},
+			{ name: "allow-unbounded" },
+			{ name: "dry-run" }
+		]
+	},
+	"kb list": {
+		command: "kb list",
+		positionals: [],
+		flags: []
+	},
+	"kb inbox": {
+		command: "kb inbox",
+		positionals: [],
+		flags: [STORE]
+	},
+	"kb gate": {
+		command: "kb gate",
+		positionals: ["<runId>", "<entryRef>"],
+		flags: [
+			{
+				name: "approver",
+				placeholder: "NAME",
+				required: true
+			},
+			{
+				name: "ruled-out",
+				placeholder: "a,b,c",
+				required: true
+			},
+			{
+				name: "contrast-run",
+				placeholder: "runId#seq",
+				exclusiveGroup: "contrast"
+			},
+			{
+				name: "contrast-eval",
+				placeholder: "reportId:caseId[,caseId...]",
+				exclusiveGroup: "contrast"
+			},
+			{
+				name: "confidence",
+				placeholder: "high|medium|low"
+			},
+			STORE
+		]
+	},
+	"kb sweep": {
+		command: "kb sweep",
+		positionals: [],
+		flags: [],
+		note: "(configuration lives in rulvar.config.mjs)"
+	}
+};
+/** The kb dispatch line: subcommands carry their own grammar entries. */
+const KB_FAMILY_USAGE = "usage: rulvar kb <list | inbox | gate | sweep> (no aliases in v1)";
+function renderFlags(flags) {
+	const tokens = [];
+	const renderedGroups = /* @__PURE__ */ new Set();
+	for (const flag of flags) {
+		if (flag.exclusiveGroup !== void 0) {
+			if (renderedGroups.has(flag.exclusiveGroup)) continue;
+			renderedGroups.add(flag.exclusiveGroup);
+			const members = flags.filter((candidate) => candidate.exclusiveGroup === flag.exclusiveGroup).map((member) => `--${member.name} ${member.placeholder ?? ""}`.trim());
+			tokens.push(`[${members.join(" | ")}]`);
+			continue;
+		}
+		const body = flag.placeholder === void 0 ? `--${flag.name}` : `--${flag.name} ${flag.placeholder}`;
+		tokens.push(flag.required === true ? body : `[${body}]`);
+	}
+	return tokens;
+}
+/** The full invocation shape, e.g. `rulvar run <file|name> [--args JSON] ...`. */
+function invocationOf(grammar) {
+	const parts = [
+		`rulvar ${grammar.command}`,
+		...grammar.positionals,
+		...renderFlags(grammar.flags)
+	];
+	if (grammar.note !== void 0) parts.push(grammar.note);
+	return parts.join(" ");
+}
+/** The canonical usage error line for a command. */
+function usageOf(grammar) {
+	return `usage: ${invocationOf(grammar)}`;
+}
+/**
+* The command lines of the help block: every top-level command plus the
+* kb family line, aligned on the flag column. The docs grammar block is
+* the same list verbatim (docs contract test).
+*/
+function helpCommandLines() {
+	const top = [
+		GRAMMAR.run,
+		GRAMMAR.resume,
+		GRAMMAR["runs ls"],
+		GRAMMAR.inspect,
+		GRAMMAR.plan
+	];
+	const heads = top.map((grammar) => [
+		"rulvar",
+		grammar.command,
+		...grammar.positionals
+	].join(" "));
+	const kbHead = "rulvar kb <list | inbox | gate | sweep>";
+	const width = Math.max(...heads.map((head) => head.length), 39);
+	const lines = top.map((grammar, index) => {
+		const tail = renderFlags(grammar.flags).join(" ");
+		return tail === "" ? heads[index] : `${heads[index].padEnd(width)} ${tail}`;
+	});
+	lines.push(kbHead);
+	return lines;
+}
+function isParseArgsError(error) {
+	if (!(error instanceof Error)) return false;
+	const code = error.code;
+	return typeof code === "string" && code.startsWith("ERR_PARSE_ARGS");
+}
+/**
+* Parses argv against one grammar entry. Everything the grammar does
+* not name is an error: unknown options (raised by parseArgs), value
+* flags given twice, both members of an exclusive group, and any
+* positional beyond the exact arity. Every rejection names the
+* canonical usage and happens before configs, stores, or adapters load.
+*/
+function parseCommand(grammar, argv) {
+	const options = {};
+	for (const flag of grammar.flags) options[flag.name] = {
+		type: flag.placeholder === void 0 ? "boolean" : "string",
+		multiple: true
+	};
+	let raw;
+	try {
+		raw = parseArgs({
+			args: argv,
+			allowPositionals: true,
+			options
+		});
+	} catch (error) {
+		if (isParseArgsError(error)) {
+			const summary = error.message.split(".")[0];
+			throw new ConfigError(`${summary}; ${usageOf(grammar)}`);
+		}
+		throw error;
+	}
+	if (raw.positionals.length < grammar.positionals.length) throw new ConfigError(usageOf(grammar));
+	if (raw.positionals.length > grammar.positionals.length) {
+		const extra = raw.positionals[grammar.positionals.length];
+		throw new ConfigError(`unexpected extra argument '${extra}'; ${usageOf(grammar)}`);
+	}
+	const values = {};
+	const groupMembers = /* @__PURE__ */ new Map();
+	for (const flag of grammar.flags) {
+		const entry = raw.values[flag.name];
+		if (entry === void 0) continue;
+		if (flag.placeholder !== void 0 && entry.length > 1) throw new ConfigError(`--${flag.name} may appear at most once; ${usageOf(grammar)}`);
+		values[flag.name] = flag.placeholder === void 0 ? true : entry[entry.length - 1];
+		if (flag.exclusiveGroup !== void 0) {
+			const members = groupMembers.get(flag.exclusiveGroup) ?? [];
+			members.push(`--${flag.name}`);
+			groupMembers.set(flag.exclusiveGroup, members);
+		}
+	}
+	for (const members of groupMembers.values()) if (members.length > 1) throw new ConfigError(`${members.join(" and ")} are mutually exclusive; ${usageOf(grammar)}`);
+	return {
+		positionals: raw.positionals,
+		values
+	};
+}
+/**
+* Validates a `--...-usd` flag value: a finite dollar amount strictly
+* above zero (0, NaN, Infinity, negatives, and non-numbers all fail),
+* checked at parse time, before any provider work.
+*/
+function parseBudgetValue(flagName, value) {
+	const budget = Number(value);
+	if (!Number.isFinite(budget) || budget <= 0) throw new ConfigError(`--${flagName} must be a positive number, got '${value}'`);
+	return budget;
+}
+//#endregion
 //#region src/commands.ts
 /**
 * The four M5 commands of the canonical CLI grammar (no aliases in v1):
@@ -314,61 +562,60 @@ function reportOutcome(outcome, io) {
 * `plan` and `kb` land with M6+/M10. Every command builds strictly from
 * the public @rulvar/core API.
 */
-function parseRunFlags(argv) {
-	const { values, positionals } = parseArgs({
-		args: argv,
-		allowPositionals: true,
-		options: {
-			args: { type: "string" },
-			store: { type: "string" },
-			"budget-usd": { type: "string" },
-			profile: { type: "string" }
-		}
-	});
-	const parsed = { positionals };
-	if (values.store !== void 0) parsed.store = values.store;
-	if (values.profile !== void 0) parsed.profile = values.profile;
-	if (values.args !== void 0) parsed.args = values.args;
-	if (values["budget-usd"] !== void 0) {
-		const budget = Number(values["budget-usd"]);
-		if (!Number.isFinite(budget) || budget <= 0) throw new ConfigError(`--budget-usd must be a positive number, got '${values["budget-usd"]}'`);
-		parsed.budgetUsd = budget;
-	}
-	return parsed;
-}
-function parseCommonFlags(argv) {
-	const { values, positionals } = parseArgs({
-		args: argv,
-		allowPositionals: true,
-		options: { store: { type: "string" } }
-	});
-	return {
-		positionals,
-		...values.store === void 0 ? {} : { store: values.store }
-	};
+/**
+* True exactly when a companion dynamic import failed because THAT
+* package is not installed (the v1.16.1 review P1): the Node code must
+* be ERR_MODULE_NOT_FOUND and the quoted missing specifier must be the
+* requested companion itself. A transitive miss inside a found
+* companion (same code, different quoted specifier) or any throw during
+* module evaluation is that package's own defect, never install advice.
+*/
+function isCompanionMissing(error, specifier) {
+	return error instanceof Error && error.code === "ERR_MODULE_NOT_FOUND" && error.message.includes(`'${specifier}'`);
+}
+/**
+* Awaits a command-local companion import. Call sites keep the literal
+* `import('@rulvar/...')` so the specifier stays analyzable and the
+* tsdown external rule preserves it in dist. Missing package: the
+* friendly ConfigError install hint. Anything else: the original error
+* survives as `cause` under a command-prefixed message.
+*/
+async function loadCompanion(loading, specifier, command, missingMessage) {
+	try {
+		return await loading;
+	} catch (error) {
+		if (isCompanionMissing(error, specifier)) throw new ConfigError(missingMessage);
+		throw new Error(`${command}: ${specifier} is installed but failed to load; the cause below is a defect in the installed package or its dependencies, not a missing install`, { cause: error });
+	}
+}
+/** Parses --args JSON into workflow arguments; undefined when absent. */
+function parseArgsJson(raw) {
+	if (raw === void 0) return;
+	try {
+		return JSON.parse(raw);
+	} catch {
+		throw new ConfigError(`--args is not valid JSON: ${raw}`);
+	}
 }
 async function runCommand(argv, context) {
-	const flags = parseRunFlags(argv);
-	const target = flags.positionals[0];
-	if (target === void 0) throw new ConfigError("usage: rulvar run <file|name> [--args JSON] [--store PATH] [--budget-usd N]");
+	const parsed = parseCommand(GRAMMAR.run, argv);
+	const target = parsed.positionals[0];
+	const store = parsed.values.store;
+	const profile = parsed.values.profile;
+	const budgetUsd = parsed.values["budget-usd"] === void 0 ? void 0 : parseBudgetValue("budget-usd", parsed.values["budget-usd"]);
+	const args = parseArgsJson(parsed.values.args);
 	const config = await loadCliConfig(context.cwd);
 	const module = looksLikeFile(target) ? await loadWorkflowModule(target, context.cwd) : void 0;
 	const assembled = assembleEngine({
 		config,
 		...module === void 0 ? {} : { module },
-		...flags.store === void 0 ? {} : { storePath: flags.store },
-		...flags.profile === void 0 ? {} : { profile: flags.profile },
+		...store === void 0 ? {} : { storePath: store },
+		...profile === void 0 ? {} : { profile },
 		cwd: context.cwd
 	});
 	const workflow = module?.workflow ?? assembled.workflows[target];
 	if (workflow === void 0) throw new ConfigError(looksLikeFile(target) ? `${target} exports no workflow (default export or named 'workflow')` : `no workflow named '${target}' in the registry; register it in rulvar.config.mjs`);
-	let args;
-	if (flags.args !== void 0) try {
-		args = JSON.parse(flags.args);
-	} catch {
-		throw new ConfigError(`--args is not valid JSON: ${flags.args}`);
-	}
-	const runOptions = { ...flags.budgetUsd === void 0 ? {} : { budgetUsd: flags.budgetUsd } };
+	const runOptions = { ...budgetUsd === void 0 ? {} : { budgetUsd } };
 	const first = assembled.engine.run(workflow, args, runOptions);
 	context.io.err(`runId: ${first.runId}`);
 	return reportOutcome(await driveRun({
@@ -380,18 +627,13 @@ async function runCommand(argv, context) {
 	}), context.io);
 }
 async function resumeCommand(argv, context) {
-	const flags = parseRunFlags(argv);
-	const runId = flags.positionals[0];
-	if (runId === void 0) throw new ConfigError("usage: rulvar resume <runId> [--args JSON] [--store PATH]");
-	let args;
-	if (flags.args !== void 0) try {
-		args = JSON.parse(flags.args);
-	} catch {
-		throw new ConfigError(`--args is not valid JSON: ${flags.args}`);
-	}
+	const parsed = parseCommand(GRAMMAR.resume, argv);
+	const runId = parsed.positionals[0];
+	const args = parseArgsJson(parsed.values.args);
+	const store = parsed.values.store;
 	const assembled = assembleEngine({
 		config: await loadCliConfig(context.cwd),
-		...flags.store === void 0 ? {} : { storePath: flags.store },
+		...store === void 0 ? {} : { storePath: store },
 		cwd: context.cwd
 	});
 	const meta = (await assembled.store.listRuns()).find((m) => m.runId === runId);
@@ -409,10 +651,10 @@ async function resumeCommand(argv, context) {
 	}), context.io);
 }
 async function runsLsCommand(argv, context) {
-	const flags = parseCommonFlags(argv);
+	const store = parseCommand(GRAMMAR["runs ls"], argv).values.store;
 	const metas = await assembleEngine({
 		config: await loadCliConfig(context.cwd),
-		...flags.store === void 0 ? {} : { storePath: flags.store },
+		...store === void 0 ? {} : { storePath: store },
 		cwd: context.cwd
 	}).store.listRuns();
 	if (metas.length === 0) {
@@ -427,12 +669,12 @@ async function runsLsCommand(argv, context) {
 	return 0;
 }
 async function inspectCommand(argv, context) {
-	const flags = parseCommonFlags(argv);
-	const runId = flags.positionals[0];
-	if (runId === void 0) throw new ConfigError("usage: rulvar inspect <runId> [--store PATH]");
+	const parsed = parseCommand(GRAMMAR.inspect, argv);
+	const runId = parsed.positionals[0];
+	const store = parsed.values.store;
 	const assembled = assembleEngine({
 		config: await loadCliConfig(context.cwd),
-		...flags.store === void 0 ? {} : { storePath: flags.store },
+		...store === void 0 ? {} : { storePath: store },
 		cwd: context.cwd
 	});
 	const meta = (await assembled.store.listRuns()).find((m) => m.runId === runId);
@@ -465,39 +707,44 @@ async function inspectCommand(argv, context) {
 	return 0;
 }
 /**
-* rulvar plan "<goal>" [--dry-run] (M6-T11): plans a
-* workflow script through @rulvar/planner (loaded dynamically: the CLI's
-* static dependency stays @rulvar/core only),
-* prints the accepted script and its advisories, and runs it in the
-* worker sandbox unless --dry-run.
+* rulvar plan (M6-T11; grammar in grammar.ts): plans a workflow script
+* through @rulvar/planner (loaded dynamically: the CLI's static
+* dependency stays @rulvar/core only), prints the accepted script and
+* its advisories, and runs it in the worker sandbox unless --dry-run.
+*
+* Both stages are paid runs with their OWN immutable ceilings (the
+* v1.16.2 review P1-1): --planning-budget-usd caps the planning run
+* (PlanOptions.run.budgetUsd, frozen at the planning journal's
+* genesis), --budget-usd caps the execution run (RunOptions.budgetUsd,
+* consistent with rulvar run). A machine-written workflow never runs
+* unbounded silently: missing ceilings fail loudly unless
+* --allow-unbounded waives them explicitly, and an execution ceiling
+* beside --dry-run is a contradiction, not an ignorable leftover.
 */
 async function planCommand(argv, context) {
-	const parsed = parseArgs({
-		args: argv,
-		allowPositionals: true,
-		options: { "dry-run": { type: "boolean" } }
-	});
+	const parsed = parseCommand(GRAMMAR.plan, argv);
 	const goal = parsed.positionals[0];
-	if (goal === void 0 || parsed.positionals.length > 1) throw new ConfigError("usage: rulvar plan \"<goal>\" [--dry-run]");
-	let plannerModule;
-	try {
-		plannerModule = await import("./dist-D9g28MUP.js");
-	} catch {
-		throw new ConfigError("rulvar plan requires @rulvar/planner (the plan agent, compileScript, and the worker sandbox live there); install it next to the CLI");
-	}
+	const dryRun = parsed.values["dry-run"] === true;
+	const allowUnbounded = parsed.values["allow-unbounded"] === true;
+	const planningBudgetUsd = parsed.values["planning-budget-usd"] === void 0 ? void 0 : parseBudgetValue("planning-budget-usd", parsed.values["planning-budget-usd"]);
+	const executionBudgetUsd = parsed.values["budget-usd"] === void 0 ? void 0 : parseBudgetValue("budget-usd", parsed.values["budget-usd"]);
+	if (dryRun && executionBudgetUsd !== void 0) throw new ConfigError("--dry-run never executes the planned workflow, so --budget-usd (the execution ceiling) has nothing to bound; drop one of the two");
+	if (!allowUnbounded && planningBudgetUsd === void 0) throw new ConfigError("rulvar plan runs the planner model as a paid run; set --planning-budget-usd N (its immutable ceiling) or waive it explicitly with --allow-unbounded");
+	if (!allowUnbounded && !dryRun && executionBudgetUsd === void 0) throw new ConfigError("executing the planned workflow is a second paid run; set --budget-usd N (its immutable ceiling) or waive it explicitly with --allow-unbounded");
+	const plannerModule = await loadCompanion(import("@rulvar/planner"), "@rulvar/planner", "rulvar plan", "rulvar plan requires @rulvar/planner (the plan agent, compileScript, and the worker sandbox live there); install it next to the CLI");
 	const assembled = assembleEngine({
 		config: await loadCliConfig(context.cwd),
 		cwd: context.cwd
 	});
-	const planned = await plannerModule.plan(assembled.engine, goal);
+	const planned = await plannerModule.plan(assembled.engine, goal, planningBudgetUsd === void 0 ? void 0 : { run: { budgetUsd: planningBudgetUsd } });
 	context.io.err(`plan: accepted with ${String(planned.lint.length)} advisory diagnostic(s)`);
 	for (const diagnostic of planned.lint) context.io.err(`  ${diagnostic.ruleId}: ${diagnostic.message}`);
-	if (parsed.values["dry-run"] === true) {
+	if (dryRun) {
 		context.io.out(planned.source);
 		return 0;
 	}
 	const workflow = planned.workflow;
-	const first = assembled.engine.run(workflow, null);
+	const first = assembled.engine.run(workflow, null, executionBudgetUsd === void 0 ? {} : { budgetUsd: executionBudgetUsd });
 	context.io.err(`runId: ${first.runId}`);
 	return reportOutcome(await driveRun({
 		engine: assembled.engine,
@@ -519,7 +766,8 @@ async function kbCommand(argv, context) {
 	if (sub === "inbox") return await kbInboxCommand(rest, context);
 	if (sub === "gate") return await kbGateCommand(rest, context);
 	if (sub === "sweep") return await kbSweepCommand(rest, context);
-	if (sub !== "list" || rest.length > 0) throw new ConfigError("usage: rulvar kb <list | inbox | gate | sweep> (no aliases in v1)");
+	if (sub !== "list") throw new ConfigError(KB_FAMILY_USAGE);
+	parseCommand(GRAMMAR["kb list"], rest);
 	const snapshot = await new FileModelKnowledgeStore({ path: join(context.cwd, "rulvar.models.json") }).current();
 	context.io.out(`knowledge store: rulvar.models.json (version ${String(snapshot.version)}, ${String(snapshot.claims.length)} claim${snapshot.claims.length === 1 ? "" : "s"})`);
 	renderKbList(snapshot, context);
@@ -553,14 +801,8 @@ function renderKbList(snapshot, context) {
 * concrete model names render here VERBATIM, exactly like kb list.
 */
 async function kbInboxCommand(argv, context) {
-	const flags = parseCommonFlags(argv);
-	if (flags.positionals.length > 0) throw new ConfigError("usage: rulvar kb inbox [--store PATH]");
-	let plan;
-	try {
-		plan = await import("./dist-A5zLp_kr.js");
-	} catch {
-		throw new ConfigError("rulvar kb inbox requires @rulvar/plan (the RunLedger fold behind the LedgerExport seam)");
-	}
+	const flags = { store: parseCommand(GRAMMAR["kb inbox"], argv).values.store };
+	const plan = await loadCompanion(import("@rulvar/plan"), "@rulvar/plan", "rulvar kb inbox", "rulvar kb inbox requires @rulvar/plan (the RunLedger fold behind the LedgerExport seam)");
 	const assembled = assembleEngine({
 		config: await loadCliConfig(context.cwd),
 		...flags.store === void 0 ? {} : { storePath: flags.store },
@@ -646,22 +888,11 @@ const RULED_OUT_VOCABULARY = [
 * per-project file store, whose git review is the authenticating gate.
 */
 async function kbGateCommand(argv, context) {
-	const { values, positionals } = parseArgs({
-		args: argv,
-		allowPositionals: true,
-		options: {
-			store: { type: "string" },
-			approver: { type: "string" },
-			"ruled-out": { type: "string" },
-			"contrast-run": { type: "string" },
-			"contrast-eval": { type: "string" },
-			confidence: { type: "string" }
-		}
-	});
-	const usage = "usage: rulvar kb gate <runId> <entryRef> --approver NAME --ruled-out a,b,c [--contrast-run runId#seq | --contrast-eval reportId:caseId[,caseId...]] [--confidence high|medium|low] [--store PATH]";
-	const runId = positionals[0];
-	const entryRefRaw = positionals[1];
-	if (runId === void 0 || entryRefRaw === void 0 || positionals.length > 2) throw new ConfigError(usage);
+	const parsed = parseCommand(GRAMMAR["kb gate"], argv);
+	const values = parsed.values;
+	const usage = usageOf(GRAMMAR["kb gate"]);
+	const runId = parsed.positionals[0];
+	const entryRefRaw = parsed.positionals[1];
 	const entryRef = Number(entryRefRaw);
 	if (!Number.isInteger(entryRef) || entryRef < 1) throw new ConfigError(`entryRef must be a positive integer entry seq, got '${entryRefRaw}'`);
 	const approver = values.approver;
@@ -670,7 +901,6 @@ async function kbGateCommand(argv, context) {
 	if (ruledOutRaw === void 0 || ruledOutRaw === "") throw new ConfigError(`--ruled-out is required: the attribution attestation lists the alternative causes you ruled out (${RULED_OUT_VOCABULARY.join(", ")}). ${usage}`);
 	const ruledOut = ruledOutRaw.split(",").map((entry) => entry.trim());
 	for (const entry of ruledOut) if (!RULED_OUT_VOCABULARY.includes(entry)) throw new ConfigError(`--ruled-out '${entry}' is not in the attestation vocabulary (${RULED_OUT_VOCABULARY.join(", ")})`);
-	if (values["contrast-run"] !== void 0 && values["contrast-eval"] !== void 0) throw new ConfigError("--contrast-run and --contrast-eval are mutually exclusive");
 	let contrastEvidence;
 	if (values["contrast-run"] !== void 0) {
 		const [contrastRun, seqRaw, ...tail] = values["contrast-run"].split("#");
@@ -698,12 +928,7 @@ async function kbGateCommand(argv, context) {
 		"medium",
 		"low"
 	].includes(confidence)) throw new ConfigError(`--confidence must be high, medium or low, got '${String(values.confidence)}'`);
-	let plan;
-	try {
-		plan = await import("./dist-A5zLp_kr.js");
-	} catch {
-		throw new ConfigError("rulvar kb gate requires @rulvar/plan (the RunLedger fold behind the LedgerExport seam)");
-	}
+	const plan = await loadCompanion(import("@rulvar/plan"), "@rulvar/plan", "rulvar kb gate", "rulvar kb gate requires @rulvar/plan (the RunLedger fold behind the LedgerExport seam)");
 	const assembled = assembleEngine({
 		config: await loadCliConfig(context.cwd),
 		...values.store === void 0 ? {} : { storePath: values.store },
@@ -793,16 +1018,22 @@ async function kbGateCommand(argv, context) {
 * sweep re-measures.
 */
 async function kbSweepCommand(argv, context) {
-	if (argv.length > 0) throw new ConfigError("usage: rulvar kb sweep (configuration lives in rulvar.config.mjs)");
+	parseCommand(GRAMMAR["kb sweep"], argv);
 	const config = await loadCliConfig(context.cwd);
 	const sweep = config.kbSweep;
 	if (sweep === void 0) throw new ConfigError("rulvar kb sweep requires a kbSweep section in rulvar.config.mjs ({ committerId, models, cases })");
-	let evals;
-	try {
-		evals = await import("./dist-CdhvWszV.js");
-	} catch {
-		throw new ConfigError("rulvar kb sweep requires @rulvar/evals (matrix sweeps, the eval-committer identity, and the canary live there); install it next to the CLI");
+	const budgets = sweep.budgets;
+	if (budgets === void 0 && sweep.allowUnbounded !== true) throw new ConfigError("rulvar kb sweep runs paid target, judge, and canary runs; set kbSweep.budgets ({ targetUsd, judgeUsd, canaryUsd, maxTotalUsd }) so every run carries an immutable ceiling and the whole sweep stays under maxTotalUsd, or waive the ceilings explicitly with kbSweep.allowUnbounded: true");
+	if (budgets !== void 0) for (const field of [
+		"targetUsd",
+		"judgeUsd",
+		"canaryUsd",
+		"maxTotalUsd"
+	]) {
+		const value = budgets[field];
+		if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) throw new ConfigError(`kbSweep.budgets.${field} must be a positive finite number, got ${String(value)}`);
 	}
+	const evals = await loadCompanion(import("@rulvar/evals"), "@rulvar/evals", "rulvar kb sweep", "rulvar kb sweep requires @rulvar/evals (matrix sweeps, the eval-committer identity, and the canary live there); install it next to the CLI");
 	const store = new FileModelKnowledgeStore({ path: join(context.cwd, "rulvar.models.json") });
 	const snapshot = await store.current();
 	const observedAt = (/* @__PURE__ */ new Date()).toISOString();
@@ -843,15 +1074,39 @@ async function kbSweepCommand(argv, context) {
 			}
 		}
 	}));
+	const usd = (amount) => `$${String(Math.round(amount * 1e6) / 1e6)}`;
+	let envelope;
+	if (budgets !== void 0) {
+		envelope = new evals.SpendEnvelope(budgets.maxTotalUsd);
+		const canaryRuns = (sweep.canary?.prompts.length ?? 0) * pool.size;
+		const targetRuns = sweep.cases.length * pool.size;
+		context.io.out(`sweep budget: ${usd(budgets.maxTotalUsd)} maxTotalUsd hard ceiling; authorizes up to ${usd(canaryRuns * budgets.canaryUsd + targetRuns * budgets.targetUsd)} for ${String(canaryRuns)} canary + ${String(targetRuns)} target run(s) before judges (each judge run up to ${usd(budgets.judgeUsd)} draws from the same envelope at grade time)`);
+	} else context.io.err("kb sweep: running UNBOUNDED (kbSweep.allowUnbounded); no target, judge, or canary run carries a ceiling");
 	for (const { member, origin } of pool.values()) {
 		const effort = member.effort === void 0 ? "" : ` effort=${member.effort}`;
 		context.io.out(`pool: ${member.model}${effort} [${origin}]`);
 	}
 	if (sweep.canary !== void 0) for (const { member } of pool.values()) {
 		const engine = await engineFor(member);
-		const fingerprint = await evals.canaryFingerprint(engine, sweep.canary);
-		const drift = await evals.flipStaleOnCanaryDrift(store, member.model, fingerprint);
-		context.io.out(`canary ${member.model}: ${fingerprint.slice(0, 12)}...` + (drift.flipped.length === 0 ? " no drift" : ` DRIFT, ${String(drift.flipped.length)} claim(s) flipped stale`));
+		let canary;
+		try {
+			canary = await evals.runCanary(engine, sweep.canary, { ...budgets === void 0 ? {} : {
+				budgetUsd: budgets.canaryUsd,
+				envelope
+			} });
+		} catch (error) {
+			if (error instanceof Error && error.name === "SweepBudgetError") {
+				context.io.out(`canary ${member.model}: envelope exhausted, skipped`);
+				continue;
+			}
+			throw error;
+		}
+		if (!canary.allOk) {
+			context.io.out(`canary ${member.model}: ${canary.fingerprint.slice(0, 12)}... incomplete (a probe did not settle ok); NOT flipping claims`);
+			continue;
+		}
+		const drift = await evals.flipStaleOnCanaryDrift(store, member.model, canary.fingerprint);
+		context.io.out(`canary ${member.model}: ${canary.fingerprint.slice(0, 12)}...` + (drift.flipped.length === 0 ? " no drift" : ` DRIFT, ${String(drift.flipped.length)} claim(s) flipped stale`));
 	}
 	const report = await evals.runSweepMatrix({
 		models: [...pool.values()].map((entry) => entry.member),
@@ -862,11 +1117,26 @@ async function kbSweepCommand(argv, context) {
 		observedAt,
 		engineFor,
 		store,
-		...sweep.thresholds === void 0 ? {} : { thresholds: sweep.thresholds }
+		...sweep.thresholds === void 0 ? {} : { thresholds: sweep.thresholds },
+		...budgets === void 0 ? {} : {
+			suite: {
+				budgetUsd: budgets.targetUsd,
+				judgeBudgetUsd: budgets.judgeUsd
+			},
+			envelope
+		}
 	});
-	for (const cell of report.cells) context.io.out(`cell ${cell.model} :: ${cell.taskClass}: passRate ${cell.passRate.toFixed(2)} over ${String(cell.n)} case${cell.n === 1 ? "" : "s"}`);
+	for (const cell of report.cells) {
+		if (cell.envelopeExhausted === true) {
+			context.io.out(`cell ${cell.model} :: ${cell.taskClass}: envelope exhausted, not measured (no claim)`);
+			continue;
+		}
+		const exhausted = cell.exhaustedRuns === void 0 ? "" : ` (${String(cell.exhaustedRuns)} run(s) hit their own ceiling; no claim)`;
+		context.io.out(`cell ${cell.model} :: ${cell.taskClass}: passRate ${cell.passRate.toFixed(2)} over ${String(cell.n)} case${cell.n === 1 ? "" : "s"}${exhausted}`);
+	}
 	for (const claim of report.claims) context.io.out(`claim ${claim.id}: ${claim.taskClass} ${claim.polarity}`);
 	context.io.out(report.committedVersion === void 0 ? "no claims crossed a threshold; nothing committed" : `committed ${String(report.claims.length)} claim(s) as store version ${String(report.committedVersion)} (report ${report.reportId})`);
+	if (envelope !== void 0) context.io.out(`sweep budget: authorized ${usd(envelope.authorizedUsd)} of ${usd(envelope.maxTotalUsd)}`);
 	return 0;
 }
 //#endregion
@@ -877,12 +1147,7 @@ async function kbSweepCommand(argv, context) {
 */
 const HELP = `rulvar: durable multi-agent workflows (https://docs.rulvar.com)
 
-  rulvar run <file|name> [--args JSON] [--store PATH] [--budget-usd N]
-  rulvar resume <runId>  [--store PATH]
-  rulvar runs ls         [--store PATH]
-  rulvar inspect <runId> [--store PATH]
-  rulvar plan "<goal>"   [--dry-run]
-  rulvar kb <list | inbox | gate | sweep>
+${helpCommandLines().map((line) => `  ${line}`).join("\n")}
 
 Engine assembly: adapters, defaults, and the workflow registry come from
 rulvar.config.mjs in the working directory (default export
@@ -890,13 +1155,18 @@ rulvar.config.mjs in the working directory (default export
 exports. --store selects the JsonlFileStore directory (default .rulvar).
 plan asks the planner model (role plan) to write a workflow script,
 lints and self-repairs it, then runs it in the worker sandbox; --dry-run
-prints the accepted script without running. Requires @rulvar/planner
-installed. kb list shows the per-project claim store
+prints the accepted script without running. Both stages are paid runs
+with their own immutable ceilings: --planning-budget-usd caps the
+planning run, --budget-usd caps the execution run, and a missing
+ceiling fails loudly unless --allow-unbounded waives it explicitly.
+Requires @rulvar/planner installed. kb list shows the per-project claim store
 (./rulvar.models.json) with full provenance. kb sweep runs the
 falsification matrix from the kbSweep section of rulvar.config.mjs
 (fixed pool UNIONED with every model carrying an active negative claim
 plus the re-measure queue; optional canary probes flip drifted claims
-stale first; requires @rulvar/evals installed). kb inbox aggregates
+stale first; kbSweep.budgets sets per-run ceilings plus the maxTotalUsd
+envelope, required unless allowUnbounded waives it; requires
+@rulvar/evals installed). kb inbox aggregates
 kb_propose proposals from finished runs (14 day TTL); kb gate turns one
 inbox proposal into a committed claim behind a human attestation
 (--approver and --ruled-out are mandatory). inbox and gate require
@@ -913,7 +1183,7 @@ async function runCli(argv, options) {
 			case "resume": return await resumeCommand(rest, context);
 			case "runs": {
 				const [sub, ...subRest] = rest;
-				if (sub !== "ls") throw new ConfigError("usage: rulvar runs ls [--store PATH] (no aliases in v1)");
+				if (sub !== "ls") throw new ConfigError(usageOf(GRAMMAR["runs ls"]));
 				return await runsLsCommand(subRest, context);
 			}
 			case "inspect": return await inspectCommand(rest, context);