@rulvar/cli 1.61.0 → 1.62.0

package/dist/cli.js

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

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { CreateEngineOptions, Engine, JournalStore, KeyDeriver, LeasableStore, ModelRef, RunHandle, RunMeta, RunOutcome, Usage, Workflow, WorkflowEvent, WorkflowRegistry } from "@rulvar/core";
+import { CreateEngineOptions, Engine, JournalStore, KeyDeriver, LeasableStore, ModelRef, PreflightInput, RunHandle, RunMeta, RunOutcome, Usage, Workflow, WorkflowEvent, WorkflowRegistry } from "@rulvar/core";
 
 //#region src/io.d.ts
 interface CliIo {
@@ -42,12 +42,38 @@ declare function inspectCommand(argv: string[], context: CommandContext): Promis
 * assembled price table, the same numbers rulvar inspect reports.
 */
 declare function invoiceCommand(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,
+* but constructs no engine, opens no store, and dispatches nothing:
+* the report is computed by preflightEstimate over options alone, so
+* the command cannot pay for a single provider token by construction.
+* The declared spawn wave comes from the `preflight` export of the
+* config or workflow module (module wins), and --spawns JSON overrides
+* it from the command line. --json prints the machine-readable report.
+* Exit 1 when any finding has severity 'error' (the linter contract:
+* green preflight means the run can at least start), 0 otherwise.
+*/
+declare function preflightCommand(argv: string[], context: CommandContext): Promise<number>;
 //#endregion
 //#region src/config.d.ts
+/**
+* The preflight declaration a config or workflow module may export
+* (the experiment-review P2.2): the declared spawn wave, the
+* orchestrator spec, and the quota rule set behind the configured
+* limiter, exactly the PreflightInput slices the estimator cannot
+* derive from engineOptions alone. `rulvar preflight` merges the
+* workflow module's declaration over the config file's, and --spawns
+* overrides the spawn wave from the command line.
+*/
+type PreflightDeclaration = Pick<PreflightInput, "spawns" | "orchestrator" | "quotaRules">;
 /** The shape both the config module and a workflow module may export. */
 interface CliConfig {
   engineOptions?: Partial<CreateEngineOptions>;
   workflows?: WorkflowRegistry;
+  /** rulvar preflight declaration (P2.2). */
+  preflight?: PreflightDeclaration;
   /** rulvar kb sweep configuration (M11-T05). */
   kbSweep?: KbSweepCliConfig;
 }
@@ -118,6 +144,7 @@ interface LoadedWorkflowModule {
   workflow?: Workflow<never, unknown>;
   engineOptions?: Partial<CreateEngineOptions>;
   workflows?: WorkflowRegistry;
+  preflight?: PreflightDeclaration;
 }
 /** Imports a workflow module given on the command line. */
 declare function loadWorkflowModule(file: string, cwd: string): Promise<LoadedWorkflowModule>;
@@ -386,4 +413,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_PENDING_EVENTS_PER_CLIENT, DEFAULT_STORE_DIR, DEFAULT_WORKER_TTL_MS, HELP, type KbSweepCliConfig, type LoadedWorkflowModule, type OtelContextApi, type RulvarServer, type SpanLike, type ToOtelOptions, type TracerLike, type Worker, assembleEngine, attachProgress, createServer, createWorker, driveRun, inspectCommand, invoiceCommand, loadCliConfig, loadWorkflowModule, looksLikeFile, processIo, renderEventLine, reportOutcome, resumeCommand, runCli, runCommand, runsLsCommand, strictExitCode, toOtel };
+export { type AssembledCli, type CliConfig, type CliIo, type CommandContext, type CreateServerOptions, type CreateWorkerOptions, 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 };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { _ as loadWorkflowModule, a as invoiceCommand, c as runsLsCommand, d as strictExitCode, f as attachProgress, g as loadCliConfig, h as assembleEngine, i as inspectCommand, l as driveRun, m as DEFAULT_STORE_DIR, n as HELP, o as resumeCommand, p as renderEventLine, r as runCli, s as runCommand, t as processIo, u as reportOutcome, v as looksLikeFile } from "./io-Dp8Qkr9V.js";
+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-DQqS6oAt.js";
 import { ConfigError, InvalidResolutionError, JournalCompatibilityError, LeaseHeldError, Replayer, RulvarError, buildDeriverRegistry, compileSecretMasker, costReportFromJournal, maskSecrets, normalizeEntry, readRunMeta, scanJournalCompatibility, validateSchemaSpec } from "@rulvar/core";
 //#region src/server.ts
 /**
@@ -961,4 +961,4 @@ async function toOtel(run, tracer, options = {}) {
 	return created;
 }
 //#endregion
-export { DEFAULT_MAX_PENDING_EVENTS_PER_CLIENT, DEFAULT_STORE_DIR, DEFAULT_WORKER_TTL_MS, HELP, assembleEngine, attachProgress, createServer, createWorker, driveRun, inspectCommand, invoiceCommand, loadCliConfig, loadWorkflowModule, looksLikeFile, processIo, renderEventLine, reportOutcome, resumeCommand, runCli, runCommand, runsLsCommand, strictExitCode, toOtel };
+export { 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 };

package/dist/{io-Dp8Qkr9V.js → io-DQqS6oAt.js}

@@ -1,4 +1,4 @@
-import { ConfigError, FileModelKnowledgeStore, INBOX_PROPOSAL_TTL_DAYS, JsonlFileStore, LeaseHeldError, auditRuns, claimExpired, claimExpiry, compilePermissionPreset, costReportFromJournal, createEngine, hashRunArgs, hashRunOutput, invoiceFromJournal, lastRunSettle, 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, invoiceFromJournal, lastRunSettle, parseModelRef, preflightEstimate, 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";
@@ -43,7 +43,8 @@ async function loadCliConfig(cwd) {
 		return {
 			...config ?? {},
 			...mod.engineOptions === void 0 ? {} : { engineOptions: mod.engineOptions },
-			...mod.workflows === void 0 ? {} : { workflows: mod.workflows }
+			...mod.workflows === void 0 ? {} : { workflows: mod.workflows },
+			...mod.preflight === void 0 ? {} : { preflight: mod.preflight }
 		};
 	}
 	return {};
@@ -58,6 +59,7 @@ async function loadWorkflowModule(file, cwd) {
 	if (candidate !== void 0 && isWorkflowValue(candidate)) loaded.workflow = candidate;
 	if (mod.engineOptions !== void 0) loaded.engineOptions = mod.engineOptions;
 	if (mod.workflows !== void 0) loaded.workflows = mod.workflows;
+	if (mod.preflight !== void 0) loaded.preflight = mod.preflight;
 	return loaded;
 }
 /** True when the `run` target names a file rather than a registry entry. */
@@ -495,6 +497,25 @@ const GRAMMAR = {
 			{ name: "dry-run" }
 		]
 	},
+	preflight: {
+		command: "preflight",
+		positionals: ["<file|name>"],
+		flags: [
+			{
+				name: "budget-usd",
+				placeholder: "N"
+			},
+			{
+				name: "profile",
+				placeholder: "NAME"
+			},
+			{
+				name: "spawns",
+				placeholder: "JSON"
+			},
+			{ name: "json" }
+		]
+	},
 	"kb list": {
 		command: "kb list",
 		positionals: [],
@@ -591,7 +612,8 @@ function helpCommandLines() {
 		GRAMMAR["runs audit"],
 		GRAMMAR.inspect,
 		GRAMMAR.invoice,
-		GRAMMAR.plan
+		GRAMMAR.plan,
+		GRAMMAR.preflight
 	];
 	const heads = top.map((grammar) => [
 		"rulvar",
@@ -1130,6 +1152,102 @@ 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;
 }
+/** Formats an optional USD number for the preflight text rows. */
+function usdOf(value) {
+	return value === void 0 ? "n/a" : `$${value.toFixed(4)}`;
+}
+function renderPreflight(report, io) {
+	io.out("preflight: effective limits and admission projection (zero provider dispatches)");
+	const perProvider = report.concurrency.perProvider;
+	io.out(`concurrency: perRun=${report.concurrency.perRun}` + (perProvider === void 0 ? "" : ` perProvider={${Object.entries(perProvider).map(([id, cap]) => `${id}:${cap}`).join(", ")}}`));
+	const budget = report.budget;
+	io.out(`budget: ceiling=${usdOf(budget.ceilingUsd)} flatReserve=${usdOf(budget.flatReserveUsd)} lifetimeSpawnCap=${budget.lifetimeSpawnCap} childFraction=${budget.childBudgetFraction} maxDepth=${budget.maxDepth}`);
+	if (budget.orchestrator !== void 0) {
+		const orch = budget.orchestrator;
+		io.out(`orchestrator: effectiveCap=${usdOf(orch.effectiveCapUsd)} finalizeReserve=${usdOf(orch.finalizeReserveUsd)} over ${orch.finalizeTurns} turns (${orch.reserveCommitted ? "committed against the run root" : "not committed: no plan extension"})`);
+	}
+	io.out(`quota: ${report.quota.configured ? "configured" : "none"}` + (report.quota.tenant === void 0 ? "" : ` tenant=${report.quota.tenant}`) + (report.quota.rules === void 0 ? "" : ` rules=${report.quota.rules}`));
+	io.out(`run limits: ${JSON.stringify(report.runLimits)}`);
+	for (const spawn of report.spawns) {
+		io.out(`spawn '${spawn.label}' role=${spawn.role} x${spawn.count} servedBy=${spawn.servedBy ?? "UNROUTED"}${spawn.unpriced === true ? " (unpriced)" : ""} reserve=${usdOf(spawn.admissionReserveUsd)} (${spawn.reserveSource})` + (spawn.maxOutputTokensPerTurn === void 0 ? "" : ` maxOutput=${spawn.maxOutputTokensPerTurn}`) + (spawn.turnFloorUsd === void 0 ? "" : ` turnFloor=${usdOf(spawn.turnFloorUsd)}`) + ` toolCallCeiling=${spawn.executedToolCallCeiling ?? "unlimited"}`);
+		io.out(`  limits: ${JSON.stringify(spawn.limits)}`);
+		for (const row of spawn.toolCeilings) {
+			if (row.tool === "(any)" && row.ceiling === null) continue;
+			io.out(`  tool ${row.tool}: ceiling=${row.ceiling ?? "unlimited"}` + (row.boundBy === void 0 ? "" : ` (${row.boundBy})`));
+		}
+	}
+	const admission = report.admission;
+	if (admission.wave.length > 0) {
+		io.out(`admission: ${admission.admitted} of ${admission.wave.length} admitted` + (admission.ceilingUsd === void 0 ? "" : ` under ceiling=${usdOf(admission.ceilingUsd)}`) + (admission.reservedForFinalizationUsd === 0 ? "" : ` (finalization holds ${usdOf(admission.reservedForFinalizationUsd)})`));
+		for (const row of admission.wave) io.out(`  ${row.admitted ? "admit" : "DENY "} ${row.label} reserve=${usdOf(row.reserveUsd)}` + (row.deniedBy === void 0 ? "" : ` [${row.deniedBy}]`));
+	}
+	io.out(`exposure: maxInFlight=${report.exposure.maxInFlight}` + (report.exposure.overshootOneTurnFloorUsd === void 0 ? "" : ` overshootOneTurnFloor=${usdOf(report.exposure.overshootOneTurnFloorUsd)}`));
+	for (const [provider, row] of Object.entries(report.exposure.perProvider)) io.out(`  provider ${provider}: inFlight=${row.inFlight} requestsPerWave=${row.requestsPerWave} tokensPerWaveFloor=${row.tokensPerWaveFloor}`);
+	io.out(`findings: ${report.findings.length}`);
+	for (const finding of report.findings) io.out(`  ${finding.severity} ${finding.code}: ${finding.message}` + (finding.spawn === void 0 ? "" : ` [spawn ${finding.spawn}]`));
+}
+/**
+* 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,
+* but constructs no engine, opens no store, and dispatches nothing:
+* the report is computed by preflightEstimate over options alone, so
+* the command cannot pay for a single provider token by construction.
+* The declared spawn wave comes from the `preflight` export of the
+* config or workflow module (module wins), and --spawns JSON overrides
+* it from the command line. --json prints the machine-readable report.
+* Exit 1 when any finding has severity 'error' (the linter contract:
+* green preflight means the run can at least start), 0 otherwise.
+*/
+async function preflightCommand(argv, context) {
+	const parsed = parseCommand(GRAMMAR.preflight, argv);
+	const target = parsed.positionals[0];
+	const profile = parsed.values.profile;
+	const json = parsed.values.json === true;
+	const budgetUsd = parsed.values["budget-usd"] === void 0 ? void 0 : parseBudgetValue("budget-usd", parsed.values["budget-usd"]);
+	const config = await loadCliConfig(context.cwd);
+	const module = looksLikeFile(target) ? await loadWorkflowModule(target, context.cwd) : void 0;
+	const workflows = {
+		...config.workflows,
+		...module?.workflows
+	};
+	if ((module?.workflow ?? workflows[target]) === 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 engineOptions = {
+		...config.engineOptions,
+		...module?.engineOptions
+	};
+	if (profile !== void 0) {
+		const preset = runProfile(profile);
+		if (preset === void 0) throw new ConfigError(`unknown run profile '${profile}'; shipped: fast, standard, deep, ultra`);
+		engineOptions = applyRunProfile(preset, engineOptions);
+	}
+	const declaration = {
+		...config.preflight,
+		...module?.preflight
+	};
+	let spawns = declaration.spawns;
+	const spawnsJson = parsed.values.spawns;
+	if (spawnsJson !== void 0) {
+		let parsedSpawns;
+		try {
+			parsedSpawns = JSON.parse(spawnsJson);
+		} catch (error) {
+			throw new ConfigError(`--spawns is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		if (!Array.isArray(parsedSpawns)) throw new ConfigError("--spawns must be a JSON array of spawn specs");
+		spawns = parsedSpawns;
+	}
+	const report = preflightEstimate({
+		engine: engineOptions,
+		run: { ...budgetUsd === void 0 ? {} : { budgetUsd } },
+		...declaration.orchestrator === void 0 ? {} : { orchestrator: declaration.orchestrator },
+		...spawns === void 0 ? {} : { spawns },
+		...declaration.quotaRules === void 0 ? {} : { quotaRules: declaration.quotaRules }
+	});
+	if (json) context.io.out(JSON.stringify(report, null, 2));
+	else renderPreflight(report, context.io);
+	return report.findings.some((finding) => finding.severity === "error") ? 1 : 0;
+}
 /**
 * rulvar plan (M6-T11; grammar in grammar.ts): plans a workflow script
 * through @rulvar/planner (loaded dynamically: the CLI's static
@@ -1598,6 +1716,16 @@ 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.
+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
+nothing, then prints the effective merged limits per declared spawn,
+the layer-1 admission projection over the declared wave (which spawns
+admit, which are denied and by what), the per-tool and weighted-unit
+bottleneck ordering, the concurrency and quota exposure floors, and
+the linter findings. The declared wave comes from the preflight export
+of the config or workflow module, or --spawns JSON; --json emits the
+machine-readable report; exit 1 when any finding is severity error.
 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
@@ -1636,6 +1764,7 @@ async function runCli(argv, options) {
 			case "inspect": return await inspectCommand(rest, context);
 			case "invoice": return await invoiceCommand(rest, context);
 			case "plan": return await planCommand(rest, context);
+			case "preflight": return await preflightCommand(rest, context);
 			case "kb": return await kbCommand(rest, context);
 			case void 0:
 			case "help":
@@ -1685,4 +1814,4 @@ function processIo() {
 	};
 }
 //#endregion
-export { loadWorkflowModule as _, invoiceCommand as a, runsLsCommand as c, strictExitCode as d, attachProgress as f, loadCliConfig as g, assembleEngine as h, inspectCommand as i, driveRun as l, DEFAULT_STORE_DIR as m, HELP as n, resumeCommand as o, renderEventLine as p, runCli as r, runCommand as s, processIo as t, reportOutcome as u, looksLikeFile as v };
+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 };

package/package.json

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