@rulvar/cli 1.1.0 → 1.3.0

package/dist/{dist-CU6iYxCW.js → dist-M-vPRtBM.js}

@@ -6,9 +6,9 @@ import { createHash } from "node:crypto";
 * suite runners. A separate quality-measurement package built strictly on
 * the public APIs (L6).
 *
-* Owning spec: docs/09-observability-testing-spec.md, section
-* "@rulvar/evals"; determinism rules in docs/11-testing-strategy.md,
-* section "Eval CI": judge graders run THROUGH the engine, so judge calls
+* Determinism rules (https://docs.rulvar.com/guide/evals and
+* https://docs.rulvar.com/guide/testing): judge graders run THROUGH the
+* engine, so judge calls
 * are journaled, budgeted, and VCR-recordable, and an eval suite replays
 * deterministically from cassettes with zero live calls.
 */
@@ -244,14 +244,14 @@ function judgeGrader(options) {
 	};
 }
 /**
-* The eval-committer identity (M11-T01; docs/05, sections "Data model"
-* and "Commit discipline"). The pipeline-side commit path: builds
+* The eval-committer identity (M11-T01; https://docs.rulvar.com/guide/model-knowledge).
+* The pipeline-side commit path: builds
 * eval-committer-gated ops (the coherence square: class eval-measured,
 * author eval-pipeline, metrics present) and commits them with the
 * documented CAS-rebase recipe. Humans never call this; their path is
 * the human gate and it structurally cannot carry metrics.
 */
-/** One measured claim, TTL applied per the docs/05 decay table. */
+/** One measured claim; claimExpiry applies the TTL from the decay table. */
 function evalMeasuredClaim(input, committerId) {
 	return {
 		id: input.id,
@@ -306,8 +306,7 @@ async function commitEvalMeasured(store, claims, options) {
 	throw lastCas ?? /* @__PURE__ */ new Error("commitEvalMeasured: unreachable");
 }
 /**
-* The canary fingerprint (M11-T04; docs/05, section "Grounding and
-* decay"; OQ-06). The optional compensation for silent alias
+* The canary fingerprint (M11-T04; OQ-06). The optional compensation for silent alias
 * re-pointing that modelEpoch honestly cannot catch: a FIXED probe set
 * at temperature 0, run through the ordinary engine (journaled,
 * budgeted, VCR-recordable), hashed over normalized outputs. A
@@ -341,9 +340,8 @@ async function canaryFingerprint(engine, probes) {
 }
 /**
 * Flips the model's ACTIVE eval-measured claims to stale when their
-* recorded canary fingerprint differs from the fresh one (docs/05:
-* "a fingerprint change immediately flips the model's eval claims to
-* stale"). Claims without a recorded fingerprint have no baseline and
+* recorded canary fingerprint differs from the fresh one. Claims
+* without a recorded fingerprint have no baseline and
 * stay untouched (the documented no-probe posture); a second run is
 * an idempotent noop. CAS-rebased like every maintenance commit.
 */
@@ -382,9 +380,8 @@ async function flipStaleOnCanaryDrift(store, model, freshFingerprint, options) {
 	throw lastCas ?? /* @__PURE__ */ new Error("flipStaleOnCanaryDrift: unreachable");
 }
 /**
-* The phases 1-2 measured-value checkpoint (M12-T01; docs/05, section
-* "Phases and placement"; the quantitative criteria of OQ-09,
-* 14-open-questions.md, closed at M11-T06). The M12 gate: kb_propose
+* The phases 1-2 measured-value checkpoint (M12-T01; the quantitative
+* criteria of OQ-09, closed at M11-T06). The M12 gate: kb_propose
 * and the proposal loop ship ONLY if the knowledge card demonstrably
 * improves tier and agentType selection on eval cases.
 *
@@ -404,7 +401,11 @@ async function flipStaleOnCanaryDrift(store, model, freshFingerprint, options) {
 *    with and without the knowledge store configured (the card docks
 *    into the spawn tool description when configured). Criterion 2
 *    holds when the card-informed arm matches or beats the baseline
-*    pass rate at no more than 105 percent of its cost.
+*    pass rate at no more than 105 percent of its cost, OR beats it
+*    by at least 15 points at no more than 115 percent of its cost
+*    (the quality branch; OQ-09 as amended 2026-07-12: the baseline
+*    fails CHEAPLY, so the flat cost bar tightened exactly when the
+*    card was winning on quality).
 *
 * The checkpoint PASSES only when both criteria hold. Methodology
 * guard: the claims the treatment consumes MUST come from a seeding
@@ -413,6 +414,18 @@ async function flipStaleOnCanaryDrift(store, model, freshFingerprint, options) {
 */
 /** IEEE754 guard for the rule boundaries (0.8 + 0.05 exceeds 0.85). */
 const EPSILON = 1e-9;
+/**
+* The OQ-09 criterion 2 rule (as amended 2026-07-12): match-or-beat at
+* 105 percent of baseline cost, OR at least 15 points better at 115
+* percent (the quality branch: the baseline fails cheaply, so the flat
+* bar tightened exactly when the card won on quality). The vacuous-pass
+* guard stays with the caller.
+*/
+function agentTypeRuleHolds(baseline, informed) {
+	const matchesCheaply = informed.passRate >= baseline.passRate - EPSILON && informed.totalCostUsd <= 1.05 * baseline.totalCostUsd + EPSILON;
+	const clearlyBetterNearCost = informed.passRate >= baseline.passRate + .15 - EPSILON && informed.totalCostUsd <= 1.15 * baseline.totalCostUsd + EPSILON;
+	return matchesCheaply || clearlyBetterNearCost;
+}
 /** The OQ-09 cell rule (shared by the per-cell and pooled verdicts). */
 function rungRuleHolds(baseline, treatment) {
 	const equalOrBetterCheaper = treatment.passRate >= baseline.passRate - EPSILON && treatment.totalCostUsd <= .9 * baseline.totalCostUsd + EPSILON;
@@ -493,7 +506,7 @@ async function runValueCheckpoint(checkpointPool, options) {
 		criterion2 = {
 			baseline,
 			informed,
-			passed: informed.n > 0 && informed.passRate > 0 && informed.passRate >= baseline.passRate && informed.totalCostUsd <= 1.05 * baseline.totalCostUsd + EPSILON
+			passed: informed.n > 0 && informed.passRate > 0 && agentTypeRuleHolds(baseline, informed)
 		};
 	}
 	return {

package/dist/index.d.ts

@@ -37,7 +37,7 @@ declare function inspectCommand(argv: string[], context: CommandContext): Promis
 interface CliConfig {
   engineOptions?: Partial<CreateEngineOptions>;
   workflows?: WorkflowRegistry;
-  /** rulvar kb sweep configuration (M11-T05; docs/05, "Grounding and decay"). */
+  /** rulvar kb sweep configuration (M11-T05). */
   kbSweep?: KbSweepCliConfig;
 }
 /**
@@ -95,7 +95,7 @@ interface AssembledCli {
   engine: Engine;
   store: JournalStore;
   workflows: WorkflowRegistry;
-  /** The journal-fold price function (table wins over caps; docs/04, section 10). */
+  /** The journal-fold price function (table wins over caps). */
   priceUsd: (servedBy: ModelRef, usage: Usage) => number | undefined;
 }
 declare function assembleEngine(options: {
@@ -115,7 +115,7 @@ declare function driveRun(options: {
   engine: Engine;
   workflow: Workflow<never, unknown>;
   first: RunHandle<unknown>;
-  io: CliIo; /** Original run arguments: not journaled in v1, the host re-supplies them (docs/14). */
+  io: CliIo; /** Original run arguments: not journaled in v1, the host re-supplies them. */
   args?: unknown;
 }): Promise<RunOutcome<unknown>>;
 /** Renders the settled outcome; returns the process exit code. */
@@ -124,17 +124,17 @@ declare function reportOutcome(outcome: RunOutcome<unknown>, io: CliIo): number;
 //#region src/server.d.ts
 interface CreateServerOptions {
   engine: Engine;
-  /** The explicit, first-class registry (docs/06, section 10.4). */
+  /** The explicit, first-class registry. */
   workflows: WorkflowRegistry;
   /**
   * Prices the journal fold behind GET /runs/:id/cost for runs without a
   * settled in-process outcome (the host assembles pricing exactly as it
   * does for the CLI); absent means those usages surface as `unpriced`,
-  * never a silent zero (docs/04, section 10).
+  * never a silent zero.
   */
   priceUsd?: (servedBy: ModelRef, usage: Usage) => number | undefined;
   /**
-  * Opt-in retention (docs/02, 8.2; OQ-20 executed at M8-T04): evaluated
+  * Opt-in retention (OQ-20 executed at M8-T04): evaluated
   * when a tracked run settles terminally; a true verdict applies
   * engine.deleteRun (transcript cascade, then the journal) and
   * untracks the run. Absent means everything persists indefinitely.
@@ -147,7 +147,7 @@ interface RulvarServer {
 declare function createServer(options: CreateServerOptions): RulvarServer;
 //#endregion
 //#region src/worker.d.ts
-/** Appendix A: the committed reference lease ttl (docs/06). */
+/** Appendix A: the committed reference lease ttl. */
 declare const DEFAULT_WORKER_TTL_MS = 6e4;
 interface CreateWorkerOptions {
   /**
@@ -162,7 +162,7 @@ interface CreateWorkerOptions {
   owner?: string;
   /**
   * The store's lease ttl; the worker renews at ttl/3 (the normative
-  * bound, docs/03 12.3). Default: the Appendix A reference 60000 ms.
+  * bound). Default: the Appendix A reference 60000 ms.
   * MUST match the store's configured ttl.
   */
   ttlMs?: number;
@@ -179,7 +179,7 @@ interface CreateWorkerOptions {
   /** Observability hook for per-run failures; never throws into the loop. */
   onError?: (runId: string, error: unknown) => void;
   /**
-  * Opt-in retention (docs/02, 8.3; OQ-20 executed at M8-T04): evaluated
+  * Opt-in retention (OQ-20 executed at M8-T04): evaluated
   * during sweeps over SETTLED runs (terminal meta); a true verdict
   * applies engine.deleteRun under a briefly held lease. Absent means
   * everything persists indefinitely.

package/dist/index.js

@@ -1,12 +1,12 @@
-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-TjsY28AR.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-DSpNsEKg.js";
 import { ConfigError, InvalidResolutionError, JournalCompatibilityError, LeaseHeldError, Replayer, RulvarError, buildDeriverRegistry, costReportFromJournal, maskSecrets, normalizeEntry, scanJournalCompatibility, validateSchemaSpec } from "@rulvar/core";
 //#region src/server.ts
 /**
 * createServer (M8-T01): the HTTP shell over the public engine API
-* (docs/02, section 8.2; FR-702). Canonical signature
+* (FR-702). Canonical signature
 * `createServer({ engine, workflows })` returning
 * `{ fetch(req: Request): Promise<Response> }`; the journal store comes
-* from the engine (Engine.stores, docs/06 10.2, M8 entry amendment).
+* from the engine (Engine.stores, M8 entry amendment).
 *
 * Routes:
 *   POST /runs                     start a run of a registered workflow
@@ -16,20 +16,19 @@ import { ConfigError, InvalidResolutionError, JournalCompatibilityError, LeaseHe
 *   GET  /runs/:id/cost            CostReport
 *
 * Authentication is explicitly out of scope: the server is host-embedded
-* and auth belongs to host middleware (docs/14, OQ-16). SSE reconnection
-* maps Last-Event-ID to the event seq (the per-run telemetry counter,
-* docs/09, section 1.1); replay is at-least-once by design, matching the
-* journal-backed re-emission contract (docs/09, section 1.5: consumers
+* and auth belongs to host middleware (OQ-16). SSE reconnection
+* maps Last-Event-ID to the event seq (the per-run telemetry counter);
+* replay is at-least-once by design, matching the
+* journal-backed re-emission contract (consumers
 * deduplicate on `replayed`).
 *
 * The server is a single-process shell: it tracks the runs it started
 * (or resumed) in memory and serves everything else from the engine's
 * stores. A resolution posted for a run that is NOT live in this process
-* is the documented offline append (docs/03, section 8: load, compute
+* is the documented offline append (load, compute
 * next seq, append, under a lease where the store is leasable); such a
 * run resumes on a queue worker (createWorker, M8-T02), not here,
-* because original run arguments are not journaled in v1 (docs/14,
-* OQ-21).
+* because original run arguments are not journaled in v1 (OQ-21).
 */
 const JSON_HEADERS = { "content-type": "application/json; charset=utf-8" };
 const wallClock = Date.now.bind(globalThis);
@@ -64,7 +63,7 @@ function isLeasable(store) {
 	const candidate = store;
 	return typeof candidate.acquire === "function" && typeof candidate.renew === "function" && typeof candidate.release === "function";
 }
-/** The approval-suspension resolution key (docs/08, section 3.6). */
+/** The approval-suspension resolution key. */
 const APPROVAL_KEY_PREFIX = "approval:";
 function suspensionKeyOf(entry) {
 	if (entry.status !== "suspended") return;
@@ -299,7 +298,7 @@ function createServer(options) {
 		return section;
 	}
 	/**
-	* The offline path (docs/03, section 8): the run is not live in this
+	* The offline path: the run is not live in this
 	* process; append the resolution under a lease where the store is
 	* leasable and leave the resume to a queue worker.
 	*/
@@ -433,7 +432,7 @@ function createServer(options) {
 //#region src/worker.ts
 /**
 * createWorker (M8-T02): the queue shell over the public engine API
-* (docs/02, section 8.3; FR-703). Canonical signature
+* (FR-703). Canonical signature
 * `createWorker(engine, { store: LeasableStore, concurrency? })`.
 *
 * The worker leases resumable ('running' meta: a crashed or currently
@@ -441,7 +440,7 @@ function createServer(options) {
 * fencing epoch; acquire on a held lease rejects with LeaseHeldError and
 * the worker simply moves on. Stateless workers call engine.resume,
 * passing the lease via ResumeOptions.lease so EVERY engine append of
-* the resumed run is fenced (docs/03, section 12.3, M8 entry amendment):
+* the resumed run is fenced (M8 entry amendment):
 * lease theft is impossible because a stale writer's appends are
 * rejected by the store and never become visible, whether or not the
 * stale worker noticed it lost the lease.
@@ -452,23 +451,23 @@ function createServer(options) {
 * this worker (an older library never writes into a newer journal).
 *
 * Queue semantics are honestly at-least-once with deduplication by the
-* journal (docs/03, section 13.1): re-leasing a settled or unchanged
+* journal: re-leasing a settled or unchanged
 * run replays to the same outcome with zero live calls. Workflows
 * resolve through the engine's defaults.workflows registry plus the
-* persisted CompiledWorkflow sources, never through a worker parameter
-* (docs/06, section 10.4); original in-process run arguments are not
+* persisted CompiledWorkflow sources, never through a worker parameter;
+* original in-process run arguments are not
 * journaled in v1, so the host MAY re-supply them per run via `argsFor`
-* (docs/14, OQ-21).
+* (OQ-21).
 *
 * Appendix A (committed at M8 entry): concurrency defaults to 1 (one
 * leased run per worker process; hosts scale out by adding workers,
 * which the fencing epoch makes safe by construction); the renew
 * cadence is ttl/3 with the reference ttl of 60000 ms. There is no
-* distributed cross-process rate limiter in v1 (EXC-14; docs/14,
-* OQ-17): divide provider quota per worker or front an external
+* distributed cross-process rate limiter in v1 (EXC-14; OQ-17):
+* divide provider quota per worker or front an external
 * gateway.
 */
-/** Appendix A: the committed reference lease ttl (docs/06). */
+/** Appendix A: the committed reference lease ttl. */
 const DEFAULT_WORKER_TTL_MS = 6e4;
 const CANDIDATE_STATUSES = /* @__PURE__ */ new Set(["running", "suspended"]);
 let workerOrdinal = 0;
@@ -544,7 +543,7 @@ function createWorker(engine, options) {
 		});
 		await settled;
 	}
-	/** Opt-in retention over settled runs (docs/02, 8.3; M8-T04). */
+	/** Opt-in retention over settled runs (M8-T04). */
 	async function applyRetention(meta) {
 		if (options.retention?.(meta) !== true) return;
 		let lease;
@@ -630,9 +629,9 @@ function createWorker(engine, options) {
 //#endregion
 //#region src/otel.ts
 /**
-* OpenTelemetry exporter (M5-T08; docs/09, section 3). `toOtel(run,
+* OpenTelemetry exporter (M5-T08; https://docs.rulvar.com/guide/observability). `toOtel(run,
 * tracer)` maps the spanId tree of a run 1:1 onto OTel spans: one span
-* per rulvar span, parented per the docs/09 1.2 hierarchy (run > phase >
+* per rulvar span, parented per the span hierarchy (run > phase >
 * agent > tool > child), with start/end timestamps from the lifecycle
 * events. Events without an own span (log, budget:update) attach as span
 * events on their enclosing span.