@rulvar/cli 1.200.0 → 1.202.0

package/dist/cli.js

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

package/dist/index.d.ts

@@ -49,6 +49,18 @@ declare function inspectCommand(argv: string[], context: CommandContext): Promis
 */
 declare function invoiceCommand(argv: string[], context: CommandContext): Promise<number>;
 /**
+* cost-audit (RV1910): the denominator diagnostic over one stored run.
+* The four-role benchmark's recovery run produced four mutually
+* inconsistent cost views; the lifecycle now admits one, and this
+* command VERIFIES it on a concrete journal instead of trusting the
+* doctrine: the roster is closed (every agent entry terminal), the
+* settle is recorded and is the billing boundary, and the settled
+* fold, the invoice totals and the wire cardinality agree. Exit 1
+* with the failing checks named when any diverge, which is exactly
+* what a pre-RV1904 journal (the benchmark's own) reports.
+*/
+declare function costAuditCommand(argv: string[], context: CommandContext): Promise<number>;
+/**
 * rulvar preflight (the experiment-review P2.2; grammar in grammar.ts):
 * the effective-config linter and dry-run estimator. Loads the SAME
 * config, module, and run-profile merge `rulvar run` would assemble,
@@ -463,4 +475,4 @@ declare function toOtel(run: {
   result: Promise<RunOutcome<unknown>>;
 }, tracer: TracerLike, options?: ToOtelOptions): Promise<number>;
 //#endregion
-export { type AssembledCli, type CliConfig, type CliIo, type CommandContext, type CreateServerOptions, type CreateWorkerOptions, DEFAULT_MAX_BUFFERED_EVENTS_PER_RUN, DEFAULT_MAX_PENDING_EVENTS_PER_CLIENT, DEFAULT_STORE_DIR, DEFAULT_WORKER_TTL_MS, HELP, type KbSweepCliConfig, type LoadedWorkflowModule, type OtelContextApi, type PreflightDeclaration, type RulvarServer, type SpanLike, type ToOtelOptions, type TracerLike, type Worker, assembleEngine, attachProgress, createServer, createWorker, driveRun, inspectCommand, invoiceCommand, loadCliConfig, loadWorkflowModule, looksLikeFile, preflightCommand, processIo, renderEventLine, reportOutcome, resumeCommand, runCli, runCommand, runsLsCommand, strictExitCode, toOtel };
+export { type AssembledCli, type CliConfig, type CliIo, type CommandContext, type CreateServerOptions, type CreateWorkerOptions, DEFAULT_MAX_BUFFERED_EVENTS_PER_RUN, DEFAULT_MAX_PENDING_EVENTS_PER_CLIENT, DEFAULT_STORE_DIR, DEFAULT_WORKER_TTL_MS, HELP, type KbSweepCliConfig, type LoadedWorkflowModule, type OtelContextApi, type PreflightDeclaration, type RulvarServer, type SpanLike, type ToOtelOptions, type TracerLike, type Worker, assembleEngine, attachProgress, costAuditCommand, createServer, createWorker, driveRun, inspectCommand, invoiceCommand, loadCliConfig, loadWorkflowModule, looksLikeFile, preflightCommand, processIo, renderEventLine, reportOutcome, resumeCommand, runCli, runCommand, runsLsCommand, strictExitCode, toOtel };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { _ as loadCliConfig, a as invoiceCommand, c as runCommand, d as reportOutcome, f as strictExitCode, g as assembleEngine, h as DEFAULT_STORE_DIR, i as inspectCommand, l as runsLsCommand, m as renderEventLine, n as HELP, o as preflightCommand, p as attachProgress, r as runCli, s as resumeCommand, t as processIo, u as driveRun, v as loadWorkflowModule, y as looksLikeFile } from "./io-C7TUZgVv.js";
+import { _ as assembleEngine, a as inspectCommand, b as looksLikeFile, c as resumeCommand, d as driveRun, f as reportOutcome, g as DEFAULT_STORE_DIR, h as renderEventLine, i as costAuditCommand, l as runCommand, m as attachProgress, n as HELP, o as invoiceCommand, p as strictExitCode, r as runCli, s as preflightCommand, t as processIo, u as runsLsCommand, v as loadCliConfig, y as loadWorkflowModule } from "./io-CAD1flsO.js";
 import { ConfigError, JournalCompatibilityError, LeaseHeldError, Replayer, RulvarError, buildDeriverRegistry, compileSecretMasker, costReportFromJournal, journalPricingSnapshot, maskSecrets, normalizeEntry, persistedTerminalEnvelope, readRunMeta, scanJournalCompatibility, validateDetachedResolution } from "@rulvar/core";
 //#region src/server.ts
 /**
@@ -1108,4 +1108,4 @@ async function toOtel(run, tracer, options = {}) {
 	return created;
 }
 //#endregion
-export { DEFAULT_MAX_BUFFERED_EVENTS_PER_RUN, DEFAULT_MAX_PENDING_EVENTS_PER_CLIENT, DEFAULT_STORE_DIR, DEFAULT_WORKER_TTL_MS, HELP, assembleEngine, attachProgress, createServer, createWorker, driveRun, inspectCommand, invoiceCommand, loadCliConfig, loadWorkflowModule, looksLikeFile, preflightCommand, processIo, renderEventLine, reportOutcome, resumeCommand, runCli, runCommand, runsLsCommand, strictExitCode, toOtel };
+export { DEFAULT_MAX_BUFFERED_EVENTS_PER_RUN, DEFAULT_MAX_PENDING_EVENTS_PER_CLIENT, DEFAULT_STORE_DIR, DEFAULT_WORKER_TTL_MS, HELP, assembleEngine, attachProgress, costAuditCommand, createServer, createWorker, driveRun, inspectCommand, invoiceCommand, loadCliConfig, loadWorkflowModule, looksLikeFile, preflightCommand, processIo, renderEventLine, reportOutcome, resumeCommand, runCli, runCommand, runsLsCommand, strictExitCode, toOtel };

package/dist/{io-C7TUZgVv.js → io-CAD1flsO.js}

@@ -558,6 +558,11 @@ const GRAMMAR = {
 		positionals: ["<runId>"],
 		flags: [STORE, { name: "json" }]
 	},
+	"cost-audit": {
+		command: "cost-audit",
+		positionals: ["<runId>"],
+		flags: [STORE, { name: "json" }]
+	},
 	plan: {
 		command: "plan",
 		positionals: ["\"<goal>\""],
@@ -689,6 +694,7 @@ function helpCommandLines() {
 		GRAMMAR["runs audit"],
 		GRAMMAR.inspect,
 		GRAMMAR.invoice,
+		GRAMMAR["cost-audit"],
 		GRAMMAR.plan,
 		GRAMMAR.preflight
 	];
@@ -1278,6 +1284,90 @@ async function invoiceCommand(argv, context) {
 	for (const item of invoice.unpriced) context.io.out(`unpriced: ${item.model} (${item.usage.inputTokens + item.usage.outputTokens} tok)`);
 	return 0;
 }
+/**
+* cost-audit (RV1910): the denominator diagnostic over one stored run.
+* The four-role benchmark's recovery run produced four mutually
+* inconsistent cost views; the lifecycle now admits one, and this
+* command VERIFIES it on a concrete journal instead of trusting the
+* doctrine: the roster is closed (every agent entry terminal), the
+* settle is recorded and is the billing boundary, and the settled
+* fold, the invoice totals and the wire cardinality agree. Exit 1
+* with the failing checks named when any diverge, which is exactly
+* what a pre-RV1904 journal (the benchmark's own) reports.
+*/
+async function costAuditCommand(argv, context) {
+	const parsed = parseCommand(GRAMMAR["cost-audit"], argv);
+	const runId = parsed.positionals[0];
+	const store = parsed.values.store;
+	const json = parsed.values.json === true;
+	const assembled = assembleEngine({
+		config: await loadCliConfig(context.cwd),
+		...store === void 0 ? {} : { storePath: store },
+		cwd: context.cwd
+	});
+	if (await readRunMeta(assembled.store, runId) === void 0) throw new ConfigError(`run '${runId}' not found in the store`);
+	const entries = await assembled.store.load(runId);
+	const snapshot = journalPricingSnapshot(entries);
+	const composed = snapshot === void 0 ? assembled.priceUsd : snapshot.composedPriceUsd(assembled.priceUsd);
+	const report = costReportFromJournal(entries, composed);
+	const invoice = invoiceFromJournal(entries, composed);
+	const terminalRefs = new Set(entries.filter((entry) => entry.kind === "agent" && entry.status !== "running").map((entry) => entry.ref));
+	const openAgents = entries.filter((entry) => entry.kind === "agent" && entry.status === "running" && !terminalRefs.has(entry.seq));
+	const settle = [...entries].reverse().find((entry) => entry.kind === "decision" && entry.value?.decisionType === "run_settle");
+	const agentsAfterSettle = settle === void 0 ? [] : entries.filter((entry) => entry.kind === "agent" && entry.seq > settle.seq);
+	const grossDelta = Math.abs(report.grossUsd - invoice.totalUsd);
+	const checks = [
+		{
+			name: "roster-closed",
+			pass: openAgents.length === 0,
+			detail: openAgents.length === 0 ? "every agent entry has a terminal" : `${String(openAgents.length)} agent entr${openAgents.length === 1 ? "y" : "ies"} still running (seq ${openAgents.map((entry) => entry.seq).join(", ")})`
+		},
+		{
+			name: "settle-recorded",
+			pass: settle !== void 0,
+			detail: settle === void 0 ? "no run_settle decision" : `run_settle at seq ${String(settle.seq)}`
+		},
+		{
+			name: "settle-is-billing-boundary",
+			pass: agentsAfterSettle.length === 0,
+			detail: agentsAfterSettle.length === 0 ? "no agent entry follows the settle" : `${String(agentsAfterSettle.length)} agent entr${agentsAfterSettle.length === 1 ? "y" : "ies"} after the settle (seq ${agentsAfterSettle.map((entry) => entry.seq).join(", ")}), the benchmark recovery shape`
+		},
+		{
+			name: "fold-matches-invoice",
+			pass: grossDelta < 1e-9,
+			detail: `settled gross $${report.grossUsd.toFixed(7)} vs invoice total $${invoice.totalUsd.toFixed(7)}`
+		},
+		{
+			name: "wires-match",
+			pass: (report.wireRequests ?? -1) === invoice.cardinality.wireRequests,
+			detail: `fold wires ${String(report.wireRequests ?? "absent")} vs invoice wires ${String(invoice.cardinality.wireRequests)}`
+		}
+	];
+	const failed = checks.filter((check) => !check.pass);
+	if (json) {
+		context.io.out(JSON.stringify({
+			runId,
+			verdict: failed.length === 0 ? "one-denominator" : "divergent",
+			settled: {
+				totalUsd: report.totalUsd,
+				grossUsd: report.grossUsd,
+				wireRequests: report.wireRequests ?? null
+			},
+			invoice: {
+				totalUsd: invoice.totalUsd,
+				rows: invoice.rows.length,
+				wireRequests: invoice.cardinality.wireRequests
+			},
+			checks
+		}, null, 2));
+		return failed.length === 0 ? 0 : 1;
+	}
+	context.io.out(`run ${runId}: cost audit (${failed.length === 0 ? "one denominator" : "DIVERGENT"})`);
+	context.io.out(`settled: gross $${report.grossUsd.toFixed(4)} | net $${report.totalUsd.toFixed(4)} | wires ${String(report.wireRequests ?? "absent")}`);
+	context.io.out(`invoice: total $${invoice.totalUsd.toFixed(4)} | rows ${String(invoice.rows.length)} | wires ${String(invoice.cardinality.wireRequests)}`);
+	for (const check of checks) context.io.out(`  [${check.pass ? "pass" : "FAIL"}] ${check.name}: ${check.detail}`);
+	return failed.length === 0 ? 0 : 1;
+}
 /** Formats an optional USD number for the preflight text rows. */
 function usdOf(value) {
 	return value === void 0 ? "n/a" : `$${value.toFixed(4)}`;
@@ -1890,6 +1980,10 @@ billable provider call (failed and retried attempts included) with the
 provider's response id when the adapter surfaced one, plus the
 gross/net ledger totals (gross includes abandoned subtrees, exactly
 what the provider bills); --json emits the machine-readable form.
+cost-audit verifies the one-denominator contract on a stored run: the
+roster is closed, the settle is the billing boundary, and the settled
+fold, the invoice totals and the wire cardinality agree; exit 1 with
+the failing checks named when any diverge.
 preflight is the effective-config linter and dry-run estimator: it
 assembles the SAME options rulvar run would (config, module exports,
 --profile, --budget-usd) but constructs no engine and dispatches
@@ -1937,6 +2031,7 @@ async function runCli(argv, options) {
 			}
 			case "inspect": return await inspectCommand(rest, context);
 			case "invoice": return await invoiceCommand(rest, context);
+			case "cost-audit": return await costAuditCommand(rest, context);
 			case "plan": return await planCommand(rest, context);
 			case "preflight": return await preflightCommand(rest, context);
 			case "kb": return await kbCommand(rest, context);
@@ -1988,4 +2083,4 @@ function processIo() {
 	};
 }
 //#endregion
-export { loadCliConfig as _, invoiceCommand as a, runCommand as c, reportOutcome as d, strictExitCode as f, assembleEngine as g, DEFAULT_STORE_DIR as h, inspectCommand as i, runsLsCommand as l, renderEventLine as m, HELP as n, preflightCommand as o, attachProgress as p, runCli as r, resumeCommand as s, processIo as t, driveRun as u, loadWorkflowModule as v, looksLikeFile as y };
+export { assembleEngine as _, inspectCommand as a, looksLikeFile as b, resumeCommand as c, driveRun as d, reportOutcome as f, DEFAULT_STORE_DIR as g, renderEventLine as h, costAuditCommand as i, runCommand as l, attachProgress as m, HELP as n, invoiceCommand as o, strictExitCode as p, runCli as r, preflightCommand as s, processIo as t, runsLsCommand as u, loadCliConfig as v, loadWorkflowModule as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/cli",
-  "version": "1.200.0",
+  "version": "1.202.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.200.0"
+    "@rulvar/core": "1.202.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",
     "tsdown": "^0.22.14",
     "typescript": "~6.0.3",
-    "@rulvar/store-sqlite": "1.200.0",
-    "@rulvar/plan": "1.200.0",
-    "@rulvar/planner": "1.200.0",
-    "@rulvar/evals": "1.200.0",
-    "@rulvar/testing": "1.200.0"
+    "@rulvar/store-sqlite": "1.202.0",
+    "@rulvar/planner": "1.202.0",
+    "@rulvar/evals": "1.202.0",
+    "@rulvar/testing": "1.202.0",
+    "@rulvar/plan": "1.202.0"
   },
   "bin": {
     "rulvar": "./dist/cli.js"