@rulvar/cli 1.49.0 → 1.51.0

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { r as runCli, t as processIo } from "./io-DHbOOiYv.js";
+import { r as runCli, t as processIo } from "./io-DK9Ji_H2.js";
 import { sanitizeTerminalText } from "@rulvar/core";
 import { inspect } from "node:util";
 //#region src/cli.ts

package/dist/index.js

@@ -1,4 +1,4 @@
-import { _ as looksLikeFile, a as resumeCommand, c as driveRun, d as attachProgress, f as renderEventLine, g as loadWorkflowModule, h as loadCliConfig, i as inspectCommand, l as reportOutcome, m as assembleEngine, n as HELP, o as runCommand, p as DEFAULT_STORE_DIR, r as runCli, s as runsLsCommand, t as processIo, u as strictExitCode } from "./io-DHbOOiYv.js";
+import { _ as looksLikeFile, a as resumeCommand, c as driveRun, d as attachProgress, f as renderEventLine, g as loadWorkflowModule, h as loadCliConfig, i as inspectCommand, l as reportOutcome, m as assembleEngine, n as HELP, o as runCommand, p as DEFAULT_STORE_DIR, r as runCli, s as runsLsCommand, t as processIo, u as strictExitCode } from "./io-DK9Ji_H2.js";
 import { ConfigError, InvalidResolutionError, JournalCompatibilityError, LeaseHeldError, Replayer, RulvarError, buildDeriverRegistry, costReportFromJournal, maskSecrets, normalizeEntry, readRunMeta, scanJournalCompatibility, validateSchemaSpec } from "@rulvar/core";
 //#region src/server.ts
 /**
@@ -924,6 +924,15 @@ async function toOtel(run, tracer, options = {}) {
 			case "child:end":
 				endSpan(event.spanId, event.ts, event.status);
 				break;
+			case "determinism:warning":
+				(openBySpanId.get(event.spanId) ?? stack[stack.length - 1])?.span.addEvent("determinism:warning", {
+					"rulvar.entry_seq": event.seq,
+					"rulvar.determinism.category": event.category,
+					"rulvar.determinism.provenance": event.provenance,
+					...event.file === void 0 ? {} : { "code.filepath": maskSecrets(event.file) },
+					...event.line === void 0 ? {} : { "code.lineno": event.line }
+				});
+				break;
 			default: (openBySpanId.get(event.spanId) ?? stack[stack.length - 1])?.span.addEvent(event.type, { "rulvar.entry_seq": event.seq });
 		}
 	}

package/dist/{io-DHbOOiYv.js → io-DK9Ji_H2.js}

@@ -1,4 +1,4 @@
-import { ConfigError, FileModelKnowledgeStore, INBOX_PROPOSAL_TTL_DAYS, JsonlFileStore, LeaseHeldError, auditRuns, claimExpired, claimExpiry, compilePermissionPreset, costReportFromJournal, createEngine, hashRunArgs, parseModelRef, priceUsdOf, proposalStatement, readRunMeta, reconcileRunMeta, remeasureQueue, resolvePricing, runProfile, sanitizeTerminalText } from "@rulvar/core";
+import { ConfigError, FileModelKnowledgeStore, INBOX_PROPOSAL_TTL_DAYS, JsonlFileStore, LeaseHeldError, auditRuns, claimExpired, claimExpiry, compilePermissionPreset, costReportFromJournal, createEngine, hashRunArgs, hashRunOutput, lastRunSettle, parseModelRef, priceUsdOf, proposalStatement, readRunMeta, reconcileRunMeta, remeasureQueue, resolvePricing, runProfile, sanitizeTerminalText } from "@rulvar/core";
 import { join, resolve } from "node:path";
 import { existsSync, statSync } from "node:fs";
 import { pathToFileURL } from "node:url";
@@ -205,6 +205,10 @@ function rawEventLine(event) {
 		case "tool:start": return `${replayMark}tool ${str(event.toolName)}`;
 		case "tool:end": return `${replayMark}tool ${str(event.toolName)} ${str(event.outcome)} (${String(num(event.durationMs))}ms)`;
 		case "approval:pending": return `approval pending: tool ${str(event.toolName)} (entry ${String(num(event.entryRef))})`;
+		case "determinism:warning": {
+			const where = str(event.file) === "" ? str(event.frame) : `at ${str(event.file)}:${String(num(event.line))}:${String(num(event.column))}`;
+			return `determinism ${str(event.category)} (${str(event.provenance)}) ${where}`;
+		}
 		case "log": return event.level === "debug" ? void 0 : `${str(event.level)}: ${str(event.msg)}`;
 		case "run:end": return `run ${str(event.runId)} ${str(event.status)}${event.usageApprox === true ? " (cost approx)" : ""}`;
 		default: return;
@@ -229,6 +233,7 @@ function attachProgress(handle, io) {
 		"tool:start",
 		"tool:end",
 		"approval:pending",
+		"determinism:warning",
 		"log",
 		"run:end"
 	]) detachers.push(handle.on(type, forward));
@@ -441,6 +446,16 @@ const GRAMMAR = {
 			{ name: "strict" }
 		]
 	},
+	replay: {
+		command: "replay",
+		positionals: ["<runId>"],
+		flags: [
+			ARGS,
+			STORE,
+			{ name: "assert-no-live" },
+			{ name: "compare-output-hash" }
+		]
+	},
 	"runs ls": {
 		command: "runs ls",
 		positionals: [],
@@ -564,6 +579,7 @@ function helpCommandLines() {
 	const top = [
 		GRAMMAR.run,
 		GRAMMAR.resume,
+		GRAMMAR.replay,
 		GRAMMAR["runs ls"],
 		GRAMMAR["runs audit"],
 		GRAMMAR.inspect,
@@ -867,6 +883,92 @@ async function resumeCommand(argv, context) {
 	return parsed.values.strict === true ? strictExitCode(outcome, base, context.io) : base;
 }
 /**
+* `rulvar replay` (RV-209): replay-strict verification of a recorded
+* run. Resumes under the engine's dry-run mode (zero journal or meta
+* writes, zero adapter calls; the first would-be-live call is a typed
+* JournalMissError settle), then reports the replay accounting, every
+* determinism warning the re-executed body raised (with its localized
+* frame), and the output digest comparison against the journaled
+* settle. `--assert-no-live` exits nonzero unless the replay was pure
+* (zero misses, zero reruns); `--compare-output-hash` exits nonzero
+* unless the replayed result's JCS sha256 equals the recorded
+* `outputHash`. Without flags the command reports and exits 0, so it
+* can sit in a pipeline as a diagnostic before it gates anything.
+* Args follow the resume binding exactly, but there is no
+* --allow-args-change here: changed args change the logical run, and a
+* verification against a different logical run proves nothing.
+*/
+async function replayCommand(argv, context) {
+	const parsed = parseCommand(GRAMMAR.replay, argv);
+	const runId = parsed.positionals[0];
+	const rawArgs = parsed.values.args;
+	const args = parseArgsJson(rawArgs);
+	const argsGiven = rawArgs !== void 0;
+	const assertNoLive = parsed.values["assert-no-live"] === true;
+	const compareOutputHash = parsed.values["compare-output-hash"] === true;
+	const store = parsed.values.store;
+	const assembled = assembleEngine({
+		config: await loadCliConfig(context.cwd),
+		...store === void 0 ? {} : { storePath: store },
+		cwd: context.cwd
+	});
+	const meta = await readRunMeta(assembled.store, runId);
+	if (meta === void 0) throw new ConfigError(`run '${runId}' not found in the store`);
+	enforceArgsBinding({
+		meta,
+		argsGiven,
+		args,
+		allowChange: false,
+		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 replay (replay requires the in-process workflow value)`);
+	const handle = assembled.engine.resume(runId, workflow, {
+		args,
+		dryRun: true
+	});
+	const warnings = [];
+	const consumer = (async () => {
+		for await (const event of handle.events) if (event.type === "determinism:warning") warnings.push(event);
+	})().catch(() => void 0);
+	const outcome = await handle.result;
+	const preview = await handle.preview;
+	await consumer;
+	const recorded = lastRunSettle(await assembled.store.load(runId));
+	const io = context.io;
+	io.err(`replay of '${sanitizeTerminalText(runId)}' (zero journal or meta writes, zero adapter calls):`);
+	io.err(`  hits: ${preview.hits}  misses: ${preview.misses}  reruns: ${preview.reruns}  skipped: ${preview.skipped}`);
+	io.err(recorded === void 0 ? "  recorded settle: none (journal predates the settle entry)" : `  recorded settle: ${recorded.runStatus}`);
+	io.err(`  replayed settle: ${outcome.status}`);
+	if (outcome.error !== void 0 && outcome.error.code !== "journal_miss") io.err(`  error: ${sanitizeTerminalText(outcome.error.message)}`);
+	for (const warning of warnings) {
+		const where = warning.file === void 0 ? warning.frame : `at ${warning.file}:${warning.line ?? "?"}:${warning.column ?? "?"}`;
+		io.err(`  determinism: ${warning.category} (${warning.provenance}) ${sanitizeTerminalText(where)}`);
+	}
+	let exit = 0;
+	if (assertNoLive) if (preview.misses === 0 && preview.reruns === 0 && outcome.error?.code !== "journal_miss") io.err("  assert-no-live: PASS (pure replay, zero would-be-live calls)");
+	else {
+		io.err(`  assert-no-live: FAIL (misses ${preview.misses}, reruns ${preview.reruns}: a real resume would perform new paid work)`);
+		exit = 1;
+	}
+	if (compareOutputHash) {
+		const replayedHash = hashRunOutput(outcome.value);
+		if (recorded?.outputHash === void 0) {
+			io.err("  compare-output-hash: FAIL (the recorded settle carries no output hash: the run predates it, settled without a value, or the value is not JCS-serializable)");
+			exit = 1;
+		} else if (replayedHash === void 0) {
+			io.err("  compare-output-hash: FAIL (the replayed run produced no hashable value)");
+			exit = 1;
+		} else if (replayedHash === recorded.outputHash) io.err(`  compare-output-hash: PASS (${replayedHash.slice(0, 12)})`);
+		else {
+			io.err(`  compare-output-hash: FAIL (recorded ${recorded.outputHash.slice(0, 12)}, replayed ${replayedHash.slice(0, 12)}: the workflow does not reproduce its output)`);
+			exit = 1;
+		}
+	}
+	return exit;
+}
+/**
 * The stranded run probe and reconciler (fenced run state RFC, phase
 * 3): audits every run the catalog lists against its journal, prints
 * the divergences worker sweeps can never see, and with --repair
@@ -1434,6 +1536,12 @@ runs audit compares every run's meta row against its journal and names
 the divergences worker sweeps cannot see (a stranded run's terminal
 meta over live journal work); --repair rewrites the sound ones from
 the journal under a brief lease, exit 1 while any divergence remains.
+replay verifies a recorded run without paying: a dry-run resume (zero
+journal or meta writes, zero adapter calls) that reports replay
+accounting, localized determinism warnings, and the output digest;
+--assert-no-live exits 1 unless the replay is pure, and
+--compare-output-hash exits 1 unless the replayed result's digest
+equals the journaled one.
 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. Both stages are paid runs
@@ -1462,6 +1570,7 @@ async function runCli(argv, options) {
 		switch (command) {
 			case "run": return await runCommand(rest, context);
 			case "resume": return await resumeCommand(rest, context);
+			case "replay": return await replayCommand(rest, context);
 			case "runs": {
 				const [sub, ...subRest] = rest;
 				if (sub === "ls") return await runsLsCommand(subRest, context);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/cli",
-  "version": "1.49.0",
+  "version": "1.51.0",
   "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.49.0"
+    "@rulvar/core": "1.51.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",
     "tsdown": "^0.22.3",
     "typescript": "~6.0.3",
-    "@rulvar/store-sqlite": "1.49.0",
-    "@rulvar/planner": "1.49.0",
-    "@rulvar/plan": "1.49.0",
-    "@rulvar/evals": "1.49.0",
-    "@rulvar/testing": "1.49.0"
+    "@rulvar/store-sqlite": "1.51.0",
+    "@rulvar/planner": "1.51.0",
+    "@rulvar/testing": "1.51.0",
+    "@rulvar/evals": "1.51.0",
+    "@rulvar/plan": "1.51.0"
   },
   "bin": {
     "rulvar": "./dist/cli.js"