@rulvar/cli 1.1.0 → 1.3.0

package/dist/{io-TjsY28AR.js → io-DSpNsEKg.js}

@@ -1,4 +1,4 @@
-import { ConfigError, FileModelKnowledgeStore, JsonlFileStore, claimExpired, compilePermissionPreset, costReportFromJournal, createEngine, parseModelRef, priceUsdOf, remeasureQueue, resolvePricing, runProfile } from "@rulvar/core";
+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";
@@ -6,9 +6,9 @@ import { pathToFileURL } from "node:url";
 import { createInterface } from "node:readline";
 //#region src/config.ts
 /**
-* CLI configuration convention (shell-owned; the canonical grammar in
-* docs/06 section 10.5 says nothing about engine assembly, and the CLI
-* builds exclusively from the public API per docs/02 section 4):
+* CLI configuration convention (shell-owned; the canonical CLI grammar
+* says nothing about engine assembly, and the CLI builds exclusively
+* from the public API):
 *
 * - `rulvar.config.mjs` (or .js) in the working directory default-exports
 *   `{ engineOptions?, workflows? }`: adapters, stores, defaults come
@@ -68,8 +68,8 @@ function looksLikeFile(target) {
 //#region src/engine-assembly.ts
 /**
 * Engine assembly for CLI commands: the host's config supplies adapters
-* and defaults (the CLI depends only on @rulvar/core, docs/02 section
-* 4); --store selects the JsonlFileStore directory (default `.rulvar`),
+* and defaults (the CLI depends only on @rulvar/core);
+* --store selects the JsonlFileStore directory (default `.rulvar`),
 * and an explicit stores entry in engineOptions wins over it.
 */
 const DEFAULT_STORE_DIR = ".rulvar";
@@ -279,8 +279,7 @@ function reportOutcome(outcome, io) {
 //#endregion
 //#region src/commands.ts
 /**
-* The four M5 commands of the canonical CLI grammar (docs/06, section
-* 10.5; no aliases in v1):
+* The four M5 commands of the canonical CLI grammar (no aliases in v1):
 *
 *   rulvar run <file|name> [--args JSON] [--store PATH] [--budget-usd N]
 *   rulvar resume <runId>  [--store PATH]
@@ -288,7 +287,7 @@ function reportOutcome(outcome, io) {
 *   rulvar inspect <runId> [--store PATH]
 *
 * `plan` and `kb` land with M6+/M10. Every command builds strictly from
-* the public @rulvar/core API (docs/02, section 4).
+* the public @rulvar/core API.
 */
 function parseRunFlags(argv) {
 	const { values, positionals } = parseArgs({
@@ -441,9 +440,9 @@ async function inspectCommand(argv, context) {
 	return 0;
 }
 /**
-* rulvar plan "<goal>" [--dry-run] (docs/06, 10.5; M6-T11): plans a
+* 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, docs/02 dependency rules),
+* static dependency stays @rulvar/core only),
 * prints the accepted script and its advisories, and runs it in the
 * worker sandbox unless --dry-run.
 */
@@ -457,7 +456,7 @@ async function planCommand(argv, context) {
 	if (goal === void 0 || parsed.positionals.length > 1) throw new ConfigError("usage: rulvar plan \"<goal>\" [--dry-run]");
 	let plannerModule;
 	try {
-		plannerModule = await import("./dist-DtuSmcav.js");
+		plannerModule = await import("./dist-Cdj5YBRG.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");
 	}
@@ -484,19 +483,18 @@ async function planCommand(argv, context) {
 	}), context.io);
 }
 /**
-* rulvar kb list (docs/06, 10.5; docs/05, 4.4; M10-T04): the second
+* rulvar kb list (M10-T04): the second
 * consumption path. Claims with full provenance for the humans who
 * author ladders, floors, and profiles; no run and no pin, so model
 * names render VERBATIM here (only in-run cards are nameless). Reads
-* the per-project file store (./rulvar.models.json). The grammar
-* members inbox (phase 3) and sweep (phase 2) fail loudly until their
-* phases ship.
+* the per-project file store (./rulvar.models.json).
 */
 async function kbCommand(argv, context) {
 	const [sub, ...rest] = argv;
-	if (sub === "inbox") throw new ConfigError("rulvar kb inbox arrives with ModelKnowledge phase 3 (M12, gated by the measured-value checkpoint; docs/05, section \"Phases and placement\")");
+	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 | sweep> (no aliases in v1)");
+	if (sub !== "list" || rest.length > 0) throw new ConfigError("usage: rulvar kb <list | inbox | gate | sweep> (no aliases in v1)");
 	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);
@@ -518,7 +516,249 @@ function renderKbList(snapshot, context) {
 	}
 }
 /**
-* rulvar kb sweep (M11-T05; docs/05, section "Grounding and decay"):
+* rulvar kb inbox (M12-T03): aggregates kb_propose-born proposals from
+* FINISHED runs through the RunLedger fold behind the LedgerExport
+* seam. Grouping of matching (subject, taskClass, polarity) triples is
+* STRICTLY display: the command writes nothing, authorizes no spend,
+* and schedules no sweeps; gating a proposal into a claim is the
+* separate human gate flow. The age anchor is the run's terminal
+* updatedAt (journal entries carry no wall clock by design): proposals
+* of runs finished more than fourteen days ago expire out of the view.
+* This is the human review surface, so the quarantined note text and
+* 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-Clz0iBp5.js");
+	} catch {
+		throw new ConfigError("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 },
+		cwd: context.cwd
+	});
+	const finished = (await assembled.store.listRuns()).filter((meta) => meta.status !== "running");
+	const cutoffMs = Date.now() - INBOX_PROPOSAL_TTL_DAYS * 24 * 60 * 60 * 1e3;
+	const groups = /* @__PURE__ */ new Map();
+	let expired = 0;
+	for (const meta of finished) {
+		const entries = await assembled.store.load(meta.runId);
+		const view = plan.foldLedger(entries, {
+			ledgerScope: "",
+			planScope: "plan"
+		});
+		for (const row of view.observations) {
+			if (row.subject === void 0 || row.polarity === void 0 || row.trigger === void 0) continue;
+			if (Date.parse(meta.updatedAt) < cutoffMs) {
+				expired += 1;
+				continue;
+			}
+			const key = [
+				row.subject.model,
+				row.subject.effort ?? "",
+				row.taskClass,
+				row.polarity
+			].join("|");
+			const group = groups.get(key) ?? {
+				subject: row.subject,
+				taskClass: row.taskClass,
+				polarity: row.polarity,
+				members: []
+			};
+			group.members.push({
+				runId: meta.runId,
+				runLabel: meta.name ?? meta.workflowName ?? "",
+				entryRef: row.entryRef,
+				logicalTaskId: row.logicalTaskId,
+				...row.tierObserved === void 0 ? {} : { tierObserved: row.tierObserved },
+				trigger: row.trigger,
+				note: row.note,
+				evidenceRefs: row.evidenceRefs,
+				finishedAt: meta.updatedAt
+			});
+			groups.set(key, group);
+		}
+	}
+	const total = [...groups.values()].reduce((sum, group) => sum + group.members.length, 0);
+	context.io.out(`kb inbox: ${String(total)} live proposal${total === 1 ? "" : "s"} in ${String(groups.size)} group${groups.size === 1 ? "" : "s"} across ${String(finished.length)} finished run${finished.length === 1 ? "" : "s"}` + (expired > 0 ? `; ${String(expired)} expired (older than 14 days)` : ""));
+	for (const key of [...groups.keys()].sort()) {
+		const group = groups.get(key);
+		const effort = group.subject.effort === void 0 ? "" : ` effort=${group.subject.effort}`;
+		context.io.out(`${group.subject.model}${effort} :: ${group.taskClass} ${group.polarity} (${String(group.members.length)} proposal${group.members.length === 1 ? "" : "s"})`);
+		context.io.out(`  statement: ${proposalStatement({
+			taskClass: group.taskClass,
+			polarity: group.polarity,
+			trigger: group.members[0].trigger
+		})}`);
+		for (const member of group.members) {
+			const tier = member.tierObserved === void 0 ? "" : ` tier=${String(member.tierObserved)}`;
+			const label = member.runLabel === "" ? "" : ` (${member.runLabel})`;
+			context.io.out(`  - run=${member.runId}${label}#${String(member.entryRef)}${tier} trigger=${member.trigger} lineage=${member.logicalTaskId} finished=${member.finishedAt}`);
+			if (member.note !== "") context.io.out(`    note: ${member.note}`);
+			if (member.evidenceRefs.length > 0) context.io.out(`    evidence: ${member.evidenceRefs.map((ref) => `#${String(ref)}`).join(", ")}`);
+		}
+	}
+	return 0;
+}
+const RULED_OUT_VOCABULARY = [
+	"prompt",
+	"tools",
+	"difficulty",
+	"transient-provider"
+];
+/**
+* rulvar kb gate (M12-T04): the human gate turning ONE inbox proposal
+* into a human-editorial claim. The attribution attestation is
+* mandatory by construction: without --ruled-out the GateRecord does
+* not assemble and nothing is written. The born claim carries the
+* typed template statement (never the quarantined note), the origin
+* provenance back to the proposing run, evidence resolving into that
+* run's journal, and the editorial TTL; the commit is CAS against the
+* 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 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;
+	if (approver === void 0 || approver === "") throw new ConfigError(`--approver is required: the attestation names its human. ${usage}`);
+	const ruledOutRaw = values["ruled-out"];
+	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("#");
+		const seq = Number(seqRaw);
+		if (contrastRun === void 0 || contrastRun === "" || tail.length > 0 || !Number.isInteger(seq) || seq < 1) throw new ConfigError("--contrast-run must look like 'runId#seq'");
+		contrastEvidence = {
+			kind: "journal",
+			runId: contrastRun,
+			entryRef: seq
+		};
+	}
+	if (values["contrast-eval"] !== void 0) {
+		const [reportId, caseList, ...tail] = values["contrast-eval"].split(":");
+		const caseIds = (caseList ?? "").split(",").filter((entry) => entry !== "");
+		if (reportId === void 0 || reportId === "" || tail.length > 0 || caseIds.length === 0) throw new ConfigError("--contrast-eval must look like 'reportId:caseId[,caseId...]'");
+		contrastEvidence = {
+			kind: "eval",
+			reportId,
+			caseIds
+		};
+	}
+	const confidence = values.confidence ?? "medium";
+	if (![
+		"high",
+		"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-Clz0iBp5.js");
+	} catch {
+		throw new ConfigError("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 },
+		cwd: context.cwd
+	});
+	const meta = (await assembled.store.listRuns()).find((candidate) => candidate.runId === runId);
+	if (meta === void 0) throw new ConfigError(`run '${runId}' not found in the store`);
+	if (meta.status === "running") throw new ConfigError(`run '${runId}' is still running; proposals gate from finished runs`);
+	if (Date.parse(meta.updatedAt) < Date.now() - INBOX_PROPOSAL_TTL_DAYS * 24 * 60 * 60 * 1e3) throw new ConfigError(`the proposal expired: run '${runId}' finished ${meta.updatedAt}, and inbox entries expire after ${String(INBOX_PROPOSAL_TTL_DAYS)} days`);
+	const entries = await assembled.store.load(runId);
+	const proposal = plan.foldLedger(entries, {
+		ledgerScope: "",
+		planScope: "plan"
+	}).observations.find((row) => row.entryRef === entryRef);
+	if (proposal === void 0 || proposal.subject === void 0 || proposal.polarity === void 0 || proposal.trigger === void 0) throw new ConfigError(`run '${runId}' entry ${String(entryRef)} is not a kb_propose proposal (see rulvar kb inbox for the gateable entries)`);
+	const store = new FileModelKnowledgeStore({ path: join(context.cwd, "rulvar.models.json") });
+	const snapshot = await store.current();
+	const already = snapshot.claims.find((claim) => claim.origin?.kind === "kb-proposal" && claim.origin.runId === runId && claim.origin.entryRef === entryRef && claim.status === "active");
+	if (already !== void 0) throw new ConfigError(`this proposal is already gated as claim '${already.id}' (supersede is the edit path)`);
+	const observedAt = meta.updatedAt;
+	const evidence = proposal.evidenceRefs.length > 0 ? proposal.evidenceRefs.map((ref) => ({
+		kind: "journal",
+		runId,
+		entryRef: ref
+	})) : [{
+		kind: "journal",
+		runId,
+		entryRef
+	}];
+	const claim = {
+		id: `kb-proposal-${runId}-${String(entryRef)}`,
+		subject: {
+			model: proposal.subject.model,
+			...proposal.subject.effort === void 0 ? {} : { effort: proposal.subject.effort }
+		},
+		taskClass: proposal.taskClass,
+		polarity: proposal.polarity,
+		statement: proposalStatement({
+			taskClass: proposal.taskClass,
+			polarity: proposal.polarity,
+			trigger: proposal.trigger
+		}),
+		class: "human-editorial",
+		status: "active",
+		evidence,
+		confidence,
+		observedAt,
+		expiresAt: claimExpiry("human-editorial", proposal.polarity, observedAt),
+		author: {
+			kind: "human",
+			id: approver
+		},
+		origin: {
+			kind: "kb-proposal",
+			runId,
+			entryRef
+		}
+	};
+	const gate = {
+		kind: "human",
+		approver,
+		at: (/* @__PURE__ */ new Date()).toISOString(),
+		attribution: {
+			ruledOut,
+			...contrastEvidence === void 0 ? {} : { contrastEvidence }
+		}
+	};
+	const version = await store.commit([{
+		op: "add",
+		claim,
+		gate
+	}], snapshot.version);
+	context.io.out(`gated: ${claim.id} (store version ${String(version)}); the git review of rulvar.models.json is the authenticating gate`);
+	context.io.out(`  ${claim.subject.model}${claim.subject.effort === void 0 ? "" : ` effort=${claim.subject.effort}`} :: ${claim.taskClass} ${claim.polarity}`);
+	context.io.out(`  ${claim.statement}`);
+	context.io.out(`  origin: kb-proposal run=${runId}#${String(entryRef)} expires=${claim.expiresAt}`);
+	return 0;
+}
+/**
+* rulvar kb sweep (M11-T05):
 * falsification sweeps, run manually, from CI, or from a user cron,
 * NEVER engine-scheduled. The matrix is the config's FIXED pool
 * UNIONED with the store's falsification set: every model carrying an
@@ -534,7 +774,7 @@ async function kbSweepCommand(argv, context) {
 	if (sweep === void 0) throw new ConfigError("rulvar kb sweep requires a kbSweep section in rulvar.config.mjs ({ committerId, models, cases }; docs/05, section 'Grounding and decay')");
 	let evals;
 	try {
-		evals = await import("./dist-CU6iYxCW.js");
+		evals = await import("./dist-M-vPRtBM.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");
 	}
@@ -607,7 +847,7 @@ async function kbSweepCommand(argv, context) {
 //#endregion
 //#region src/cli-main.ts
 /**
-* Command dispatch for the canonical grammar (docs/06, section 10.5):
+* Command dispatch for the canonical grammar (https://docs.rulvar.com/guide/cli):
 * no aliases in v1; unknown commands and flags fail loudly with usage.
 */
 const HELP = `rulvar: durable multi-agent workflows (docs/06, section 10.5)
@@ -672,8 +912,8 @@ async function runCli(argv, options) {
 /**
 * CLI io seam: every command writes and prompts through this interface
 * so the e2e suite drives the real command paths in-process with
-* scripted stdin and captured output (docs/02, section 8.1: the CLI is
-* a shell strictly on top of the public APIs).
+* scripted stdin and captured output (the CLI is a shell strictly on
+* top of the public APIs).
 */
 /** The process-backed io the bin entry uses. */
 function processIo() {

package/dist/{src-DVFj9U50.js → src-BA7JP7vn.js}

@@ -1,4 +1,4 @@
-import { t as __esmMin } from "./dist-DtuSmcav.js";
+import { t as __esmMin } from "./dist-Cdj5YBRG.js";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import nativeFsp from "node:fs/promises";

package/package.json

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