@rulvar/cli 1.23.0 → 1.24.1

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { r as runCli, t as processIo } from "./io-Dh-Fa5Nf.js";
+import { r as runCli, t as processIo } from "./io-CV_G44A2.js";
 import { inspect } from "node:util";
 //#region src/cli.ts
 /**

package/dist/index.js

@@ -1,4 +1,4 @@
-import { a as resumeCommand, c as driveRun, d as renderEventLine, f as DEFAULT_STORE_DIR, g as looksLikeFile, h as loadWorkflowModule, i as inspectCommand, l as reportOutcome, m as loadCliConfig, n as HELP, o as runCommand, p as assembleEngine, r as runCli, s as runsLsCommand, t as processIo, u as attachProgress } from "./io-Dh-Fa5Nf.js";
+import { a as resumeCommand, c as driveRun, d as renderEventLine, f as DEFAULT_STORE_DIR, g as looksLikeFile, h as loadWorkflowModule, i as inspectCommand, l as reportOutcome, m as loadCliConfig, n as HELP, o as runCommand, p as assembleEngine, r as runCli, s as runsLsCommand, t as processIo, u as attachProgress } from "./io-CV_G44A2.js";
 import { ConfigError, InvalidResolutionError, JournalCompatibilityError, LeaseHeldError, Replayer, RulvarError, buildDeriverRegistry, costReportFromJournal, maskSecrets, normalizeEntry, scanJournalCompatibility, validateSchemaSpec } from "@rulvar/core";
 //#region src/server.ts
 /**

package/dist/{io-Dh-Fa5Nf.js → io-CV_G44A2.js}

@@ -1,4 +1,4 @@
-import { ConfigError, FileModelKnowledgeStore, INBOX_PROPOSAL_TTL_DAYS, JsonlFileStore, claimExpired, claimExpiry, compilePermissionPreset, costReportFromJournal, createEngine, parseModelRef, priceUsdOf, proposalStatement, remeasureQueue, resolvePricing, runProfile, sanitizeTerminalText } from "@rulvar/core";
+import { ConfigError, FileModelKnowledgeStore, INBOX_PROPOSAL_TTL_DAYS, JsonlFileStore, claimExpired, claimExpiry, compilePermissionPreset, costReportFromJournal, createEngine, hashRunArgs, parseModelRef, priceUsdOf, proposalStatement, remeasureQueue, resolvePricing, runProfile, sanitizeTerminalText } from "@rulvar/core";
 import { join, resolve } from "node:path";
 import { existsSync, statSync } from "node:fs";
 import { pathToFileURL } from "node:url";
@@ -303,6 +303,35 @@ async function driveRun(options) {
 		handle = options.engine.resume(handle.runId, options.workflow, { args: options.args });
 	}
 }
+/**
+* Renders the `resume --dry-run` preview (the v1.23.0 review): the
+* replay accounting from `handle.preview`, then what a real resume
+* would do. The engine's replay-strict mode guarantees zero journal or
+* meta writes and zero adapter calls. A preview that stops at a
+* would-be-live call is a SUCCESSFUL preview (the miss IS the answer),
+* so the exit code is 0 either way; only structural failures (missing
+* run, unregistered workflow, args refusal) exit nonzero via their
+* typed errors.
+*/
+async function reportDryRun(handle, io) {
+	const outcome = await handle.result;
+	const preview = await handle.preview;
+	io.err("dry-run preview (zero journal or meta writes, zero adapter calls):");
+	io.err(`  hits: ${preview.hits}  misses: ${preview.misses}  reruns: ${preview.reruns}  skipped: ${preview.skipped}`);
+	io.err(preview.orphaned.length === 0 ? "  orphaned effect roots: none" : `  orphaned effect roots (entryRefs): ${preview.orphaned.join(", ")}`);
+	if (preview.invalidResolutions.length === 0) io.err("  invalid resolutions: none");
+	else for (const invalid of preview.invalidResolutions) io.err(`  invalid resolution at seq ${invalid.seq}: ${invalid.detail}`);
+	if (outcome.error?.code === "journal_miss") {
+		io.err(`  stopped at the first would-be-live call: ${outcome.error.message}`);
+		io.err("  a real resume would perform new paid work from this point");
+		return 0;
+	}
+	io.err(`  would settle: ${outcome.status}`);
+	if (outcome.error !== void 0) io.err(`  error: ${outcome.error.message}`);
+	for (const pending of outcome.pending) io.err(`  pending: ${pending.key} (entry ${pending.entryRef})`);
+	if (outcome.value !== void 0) io.out(JSON.stringify(outcome.value, null, 2));
+	return 0;
+}
 /** Renders the settled outcome; returns the process exit code. */
 function reportOutcome(outcome, io) {
 	io.err(`status: ${outcome.status}`);
@@ -366,7 +395,12 @@ const GRAMMAR = {
 	resume: {
 		command: "resume",
 		positionals: ["<runId>"],
-		flags: [ARGS, STORE]
+		flags: [
+			ARGS,
+			STORE,
+			{ name: "dry-run" },
+			{ name: "allow-args-change" }
+		]
 	},
 	"runs ls": {
 		command: "runs ls",
@@ -607,14 +641,35 @@ async function loadCompanion(loading, specifier, command, 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. */
+/**
+* Parses --args JSON into workflow arguments; undefined when absent.
+*
+* CLI args must be representable in canonical JCS, i.e. finite JSON. A
+* numeric literal that overflows JavaScript's finite range parses to
+* Infinity, which `hashRunArgs` cannot canonicalize, so genesis would
+* record `argsProvided` WITHOUT a hash and the resume gate would soften
+* to an unverifiable warning that lets changed args through (v1.24.0
+* review P2-1). A CLI value always arrives as JSON text, so it can
+* always be canonicalized; reject the non-finite case here, before any
+* config, store, or adapter loads, instead of letting it defeat the gate
+* later. In-process hosts keep the wider engine contract (functions,
+* BigInt, cycles record presence without a hash); the CLI does not need
+* it.
+*/
 function parseArgsJson(raw) {
 	if (raw === void 0) return;
+	let parsed;
 	try {
-		return JSON.parse(raw);
+		parsed = JSON.parse(raw);
 	} catch {
 		throw new ConfigError(`--args is not valid JSON: ${raw}`);
 	}
+	try {
+		hashRunArgs(parsed);
+	} catch {
+		throw new ConfigError(`--args is not representable as canonical JSON: a numeric value overflows JavaScript's finite range (e.g. 1e400 parses to Infinity). Supply finite JSON so the run's args binding can be hashed and later verified on resume: ${raw}`);
+	}
+	return parsed;
 }
 async function runCommand(argv, context) {
 	const parsed = parseCommand(GRAMMAR.run, argv);
@@ -645,10 +700,58 @@ async function runCommand(argv, context) {
 		args
 	}), context.io);
 }
+/**
+* The resume args safety gate (the v1.23.0 review): a run's logical
+* identity includes its genesis args, so a resume that silently drops,
+* adds, or changes them is refused BEFORE the engine starts (zero
+* provider calls, zero journal writes). `--allow-args-change` is the
+* explicit override for every divergence class; legacy runs recorded
+* before the binding existed require it (or explicit `--args`) because
+* nothing can be verified against them.
+*/
+function enforceArgsBinding(input) {
+	const { meta, argsGiven, args, allowChange, io } = input;
+	if (meta.argsProvided === void 0) {
+		if (!argsGiven && !allowChange) throw new ConfigError(`run '${meta.runId}' predates the args binding (rulvar < 1.24.0), so the CLI cannot tell whether it was started with --args, and resuming without them silently changes the logical run if any were used at start. Re-supply the original --args, or acknowledge explicitly with --allow-args-change; ${usageOf(GRAMMAR.resume)}`);
+		if (argsGiven) io.err(`warning: run '${meta.runId}' predates the args binding; the supplied --args cannot be verified against the original invocation`);
+		return;
+	}
+	if (meta.argsProvided) {
+		if (!argsGiven) {
+			if (!allowChange) throw new ConfigError(`run '${meta.runId}' was started WITH args, but this resume supplies none; the workflow would see undefined and every args-dependent call would become new paid work instead of a replay. Re-supply the original --args, or force the change with --allow-args-change; ${usageOf(GRAMMAR.resume)}`);
+			io.err(`warning: resuming '${meta.runId}' without its genesis args (--allow-args-change)`);
+			return;
+		}
+		if (meta.argsHash === void 0) {
+			if (!allowChange) throw new ConfigError(`run '${meta.runId}' started WITH args but recorded no verifiable hash (the genesis args were not JCS-serializable), so the CLI cannot confirm the supplied --args match the original; resuming risks silently changing the logical run and re-paying every args-dependent call. Force deliberately with --allow-args-change; ${usageOf(GRAMMAR.resume)}`);
+			io.err(`warning: run '${meta.runId}' recorded args presence but no hash (genesis args not JCS-serializable); the supplied --args cannot be verified (--allow-args-change)`);
+			return;
+		}
+		let supplied;
+		try {
+			supplied = hashRunArgs(args);
+		} catch {
+			throw new ConfigError(`--args cannot be canonicalized to compare against run '${meta.runId}' (a numeric value overflows the finite range, or the value is otherwise not canonical JSON); supply finite JSON, or force the resume with --allow-args-change; ${usageOf(GRAMMAR.resume)}`);
+		}
+		if (supplied !== meta.argsHash) {
+			if (!allowChange) throw new ConfigError(`--args does not match the args run '${meta.runId}' was started with (recorded hash ${meta.argsHash.slice(0, 12)}, supplied ${supplied?.slice(0, 12) ?? "none"}); changed args silently change the logical run and re-pay every args-dependent call. Force deliberately with --allow-args-change; ${usageOf(GRAMMAR.resume)}`);
+			io.err(`warning: resuming '${meta.runId}' with changed args (--allow-args-change)`);
+		}
+		return;
+	}
+	if (argsGiven) {
+		if (!allowChange) throw new ConfigError(`run '${meta.runId}' was started WITHOUT args, but this resume supplies some; added args silently change the logical run. Drop --args, or force the change with --allow-args-change; ${usageOf(GRAMMAR.resume)}`);
+		io.err(`warning: resuming no-args run '${meta.runId}' with args (--allow-args-change)`);
+	}
+}
 async function resumeCommand(argv, context) {
 	const parsed = parseCommand(GRAMMAR.resume, argv);
 	const runId = parsed.positionals[0];
-	const args = parseArgsJson(parsed.values.args);
+	const rawArgs = parsed.values.args;
+	const args = parseArgsJson(rawArgs);
+	const argsGiven = rawArgs !== void 0;
+	const dryRun = parsed.values["dry-run"] === true;
+	const allowChange = parsed.values["allow-args-change"] === true;
 	const store = parsed.values.store;
 	const assembled = assembleEngine({
 		config: await loadCliConfig(context.cwd),
@@ -657,10 +760,21 @@ async function resumeCommand(argv, context) {
 	});
 	const meta = (await assembled.store.listRuns()).find((m) => m.runId === runId);
 	if (meta === void 0) throw new ConfigError(`run '${runId}' not found in the store`);
+	enforceArgsBinding({
+		meta,
+		argsGiven,
+		args,
+		allowChange,
+		io: context.io
+	});
 	const name = meta.workflowName;
 	const workflow = name === void 0 ? void 0 : assembled.workflows[name];
 	if (workflow === void 0) throw new ConfigError(`run '${runId}' was started from workflow '${name ?? "(unknown)"}'; register it under that name in rulvar.config.mjs workflows to resume (resume requires the in-process workflow value)`);
-	const first = assembled.engine.resume(runId, workflow, { args });
+	const first = assembled.engine.resume(runId, workflow, {
+		args,
+		...dryRun ? { dryRun: true } : {}
+	});
+	if (dryRun) return await reportDryRun(first, context.io);
 	return reportOutcome(await driveRun({
 		engine: assembled.engine,
 		workflow,
@@ -701,6 +815,7 @@ async function inspectCommand(argv, context) {
 	const entries = await assembled.store.load(runId);
 	context.io.out(`run ${meta.runId}: ${meta.status} (updated ${meta.updatedAt})`);
 	if (meta.workflowName !== void 0) context.io.out(`workflow: ${meta.workflowName}`);
+	if (meta.argsProvided !== void 0) context.io.out(meta.argsProvided ? `args at genesis: provided${meta.argsHash === void 0 ? " (no hash: not JCS-serializable)" : ` (hash ${meta.argsHash})`}` : "args at genesis: none");
 	const byKind = /* @__PURE__ */ new Map();
 	let openSuspensions = 0;
 	const resolvedRefs = /* @__PURE__ */ new Set();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/cli",
-  "version": "1.23.0",
+  "version": "1.24.1",
   "description": "Rulvar shell: run/resume/runs/inspect/plan/kb commands, TUI progress, createServer, createWorker, OTel exporter.",
   "type": "module",
   "license": "Apache-2.0",
@@ -22,17 +22,17 @@
     "access": "public"
   },
   "dependencies": {
-    "@rulvar/core": "1.23.0"
+    "@rulvar/core": "1.24.1"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",
     "tsdown": "^0.22.3",
     "typescript": "~6.0.3",
-    "@rulvar/testing": "1.23.0",
-    "@rulvar/store-sqlite": "1.23.0",
-    "@rulvar/planner": "1.23.0",
-    "@rulvar/plan": "1.23.0",
-    "@rulvar/evals": "1.23.0"
+    "@rulvar/store-sqlite": "1.24.1",
+    "@rulvar/testing": "1.24.1",
+    "@rulvar/planner": "1.24.1",
+    "@rulvar/plan": "1.24.1",
+    "@rulvar/evals": "1.24.1"
   },
   "bin": {
     "rulvar": "./dist/cli.js"