@rulvar/cli 1.25.0 → 1.26.0

package/dist/cli.js

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

package/dist/index.d.ts

@@ -164,12 +164,43 @@ interface CreateServerOptions {
   */
   priceUsd?: (servedBy: ModelRef, usage: Usage) => number | undefined;
   /**
-  * Opt-in retention (OQ-20 executed at M8-T04): evaluated
+  * Opt-in DURABLE 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.
+  * untracks the run. This deletes the durable record; to release only
+  * process memory, use `memoryRetention` or `maxTrackedRuns`. Absent
+  * means nothing is deleted.
   */
   retention?: (meta: RunMeta) => boolean;
+  /**
+  * Opt-in retention of PROCESS MEMORY, decoupled from the durable kind
+  * (v1.25.0 scale review P1-2): evaluated when a tracked run settles
+  * terminally, after `retention`; a true verdict releases the tracked
+  * state (args, outcome, handle, SSE buffer) while the journal and
+  * transcripts stay untouched, after which GET status/cost serve from
+  * the store exactly as for a run another process owns, and GET events
+  * answers with the documented empty stream for a run not live here.
+  */
+  memoryRetention?: (meta: RunMeta) => boolean;
+  /**
+  * Cap on SETTLED tracked runs kept in process memory: when a run
+  * settles terminally and neither retention released it, the oldest
+  * settled tracked runs beyond the cap are released exactly like a
+  * `memoryRetention` verdict (durable state untouched). Live runs are
+  * never evicted and do not count toward the cap. Absent means no cap.
+  */
+  maxTrackedRuns?: number;
+  /**
+  * Upper bound on buffered SSE replay events per tracked run: past the
+  * bound the OLDEST buffered events are dropped in chunks (so the
+  * retained replay window stays at least seven eighths of the bound)
+  * and counted. A replay that no longer reaches back to a client's
+  * cursor carries `x-rulvar-events-dropped: <count>` and a leading SSE
+  * comment naming the first retained seq; the journal remains the
+  * durable record of the run itself. Absent means unbounded (the
+  * historical behavior).
+  */
+  maxBufferedEventsPerRun?: number;
 }
 interface RulvarServer {
   fetch(req: Request): Promise<Response>;

package/dist/index.js

@@ -1,5 +1,5 @@
-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-CAXfPWq7.js";
-import { ConfigError, InvalidResolutionError, JournalCompatibilityError, LeaseHeldError, Replayer, RulvarError, buildDeriverRegistry, costReportFromJournal, maskSecrets, normalizeEntry, scanJournalCompatibility, validateSchemaSpec } from "@rulvar/core";
+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-C3T5nbNg.js";
+import { ConfigError, InvalidResolutionError, JournalCompatibilityError, LeaseHeldError, Replayer, RulvarError, buildDeriverRegistry, costReportFromJournal, maskSecrets, normalizeEntry, readRunMeta, scanJournalCompatibility, validateSchemaSpec } from "@rulvar/core";
 //#region src/server.ts
 /**
 * createServer (M8-T01): the HTTP shell over the public engine API
@@ -77,13 +77,39 @@ function createServer(options) {
 	const { engine, workflows } = options;
 	const journal = engine.stores.journal;
 	const runs = /* @__PURE__ */ new Map();
+	/**
+	* Buffers one event under the configured bound. Overflow drops the
+	* oldest chunk (an eighth of the bound) in one splice, so the
+	* amortized cost per event stays O(1) and the retained window never
+	* falls below seven eighths of the bound.
+	*/
+	function pushBuffered(run, event) {
+		run.buffer.push(event);
+		const max = options.maxBufferedEventsPerRun;
+		if (max !== void 0 && run.buffer.length > max) {
+			const chunk = Math.max(1, Math.floor(max / 8));
+			run.buffer.splice(0, chunk);
+			run.dropped += chunk;
+		}
+	}
+	/**
+	* Releases settled tracked runs beyond maxTrackedRuns, oldest first
+	* (Map insertion order), durable state untouched. Live runs never
+	* count and are never evicted.
+	*/
+	function enforceTrackedCap() {
+		const cap = options.maxTrackedRuns;
+		if (cap === void 0) return;
+		const settled = [...runs.values()].filter((run) => run.done);
+		for (const run of settled.slice(0, Math.max(0, settled.length - cap))) runs.delete(run.runId);
+	}
 	/** Pumps one resume segment's events into the buffer and the feeds. */
 	function attach(run, handle) {
 		run.handle = handle;
 		run.outcome = void 0;
 		(async () => {
 			for await (const event of handle.events) {
-				run.buffer.push(event);
+				pushBuffered(run, event);
 				for (const feed of [...run.feeds]) feed(event);
 			}
 		})().catch(() => void 0);
@@ -93,12 +119,18 @@ function createServer(options) {
 				run.done = true;
 				for (const feed of [...run.feeds]) feed(null);
 				run.feeds.clear();
-				if (options.retention !== void 0) (async () => {
-					const meta = await metaOf(run.runId);
+				(async () => {
+					const meta = options.retention === void 0 && options.memoryRetention === void 0 ? void 0 : await metaOf(run.runId);
 					if (meta !== void 0 && options.retention?.(meta) === true) {
 						await engine.deleteRun(run.runId);
 						runs.delete(run.runId);
+						return;
+					}
+					if (meta !== void 0 && options.memoryRetention?.(meta) === true) {
+						runs.delete(run.runId);
+						return;
 					}
+					enforceTrackedCap();
 				})().catch(() => void 0);
 			}
 		}).catch(() => void 0);
@@ -109,6 +141,7 @@ function createServer(options) {
 			workflowName,
 			args,
 			buffer: [],
+			dropped: 0,
 			feeds: /* @__PURE__ */ new Set(),
 			handle,
 			done: false,
@@ -119,7 +152,7 @@ function createServer(options) {
 		return run;
 	}
 	async function metaOf(runId) {
-		return (await journal.listRuns()).find((meta) => meta.runId === runId);
+		return readRunMeta(journal, runId);
 	}
 	async function startRun(req) {
 		let body;
@@ -221,19 +254,35 @@ function createServer(options) {
 		const lastEventId = req.headers.get("last-event-id");
 		const encoder = new TextEncoder();
 		let feed;
+		let cursor;
+		if (lastEventId !== null) {
+			const parsed = Number(lastEventId);
+			if (Number.isFinite(parsed)) cursor = parsed;
+		}
+		let startIndex = 0;
+		if (cursor !== void 0) {
+			let lo = 0;
+			let hi = run.buffer.length;
+			while (lo < hi) {
+				const mid = lo + hi >> 1;
+				if (run.buffer[mid].seq <= cursor) lo = mid + 1;
+				else hi = mid;
+			}
+			startIndex = lo;
+		}
+		const firstRetained = run.buffer.length > 0 ? run.buffer[0].seq : void 0;
+		const gap = run.dropped > 0 && (cursor === void 0 || firstRetained === void 0 || cursor < firstRetained);
+		const headers = {
+			"content-type": "text/event-stream",
+			"cache-control": "no-cache",
+			...run.dropped > 0 ? { "x-rulvar-events-dropped": String(run.dropped) } : {}
+		};
 		const stream = new ReadableStream({
 			start(controller) {
-				let startIndex = 0;
-				if (lastEventId !== null) {
-					const cursor = Number(lastEventId);
-					if (Number.isFinite(cursor)) {
-						for (let i = run.buffer.length - 1; i >= 0; i -= 1) if (run.buffer[i].seq === cursor) {
-							startIndex = i + 1;
-							break;
-						}
-					}
-				}
-				for (const event of run.buffer.slice(startIndex)) controller.enqueue(encoder.encode(sseFrame(event)));
+				if (gap) controller.enqueue(encoder.encode(`: replay window starts at seq ${String(firstRetained ?? "none")}; ${run.dropped} earlier events were dropped from the in-memory buffer (the journal is the durable record)
+
+`));
+				for (let i = startIndex; i < run.buffer.length; i += 1) controller.enqueue(encoder.encode(sseFrame(run.buffer[i])));
 				if (run.done) {
 					controller.close();
 					return;
@@ -257,10 +306,7 @@ function createServer(options) {
 		});
 		return new Response(stream, {
 			status: 200,
-			headers: {
-				"content-type": "text/event-stream",
-				"cache-control": "no-cache"
-			}
+			headers
 		});
 	}
 	/** The tracked path: live (or settled-suspended) in this process. */
@@ -487,14 +533,28 @@ function createWorker(engine, options) {
 	const pollMs = options.pollMs ?? 1e3;
 	const registry = buildDeriverRegistry(options.extraDerivers);
 	const active = /* @__PURE__ */ new Map();
-	/** Runs this worker must not retry (DEF-6 violations, binding errors). */
-	const poisoned = /* @__PURE__ */ new Set();
 	/**
-	* Journal length at our last release of a still-suspended run: nothing
-	* new to consume until it grows (an offline resolution appends).
+	* Runs this worker must not retry (DEF-6 violations, binding errors),
+	* keyed to the run's generation (RunMeta.genesis) at poison time: a
+	* deleteRun and recreate of the same runId is a NEW run and must not
+	* inherit the poison. Entries for runIds that leave the candidate set
+	* are dropped each sweep, so an external delete cannot pin
+	* process-local state forever (v1.25.0 scale review).
+	*/
+	const poisoned = /* @__PURE__ */ new Map();
+	/**
+	* Journal length AND generation at our last release of a
+	* still-suspended run: nothing new to consume until the journal grows
+	* (an offline resolution appends) or the generation changes (the same
+	* runId was deleted and recreated; length alone cannot tell the new
+	* run from the old unchanged one, the v1.25.0 scale review). Runs
+	* whose meta predates the genesis field compare as equal when both
+	* sides are undefined, the historical behavior of length alone.
 	*/
 	const suspendedAt = /* @__PURE__ */ new Map();
 	let pollTimer;
+	/** An interval tick never overlaps a sweep that is still running. */
+	let sweeping = false;
 	let stopping = false;
 	function reportError(runId, error) {
 		try {
@@ -523,10 +583,13 @@ function createWorker(engine, options) {
 		const settled = handle.result.then(async (outcome) => {
 			if (outcome.status === "suspended") {
 				const entries = await store.load(runId);
-				suspendedAt.set(runId, entries.length);
+				suspendedAt.set(runId, {
+					length: entries.length,
+					genesis: meta.genesis
+				});
 			} else suspendedAt.delete(runId);
 		}).catch((thrown) => {
-			if (thrown instanceof ConfigError || thrown instanceof JournalCompatibilityError) poisoned.add(runId);
+			if (thrown instanceof ConfigError || thrown instanceof JournalCompatibilityError) poisoned.set(runId, meta.genesis);
 			reportError(runId, thrown);
 		}).finally(async () => {
 			clearInterval(renewTimer);
@@ -562,45 +625,58 @@ function createWorker(engine, options) {
 		}
 	}
 	async function sweep() {
-		if (stopping) return 0;
-		let picked = 0;
-		const metas = await store.listRuns();
-		for (const meta of metas) {
-			if (active.size >= concurrency) break;
-			if (!CANDIDATE_STATUSES.has(meta.status)) {
-				if (options.retention !== void 0 && !active.has(meta.runId)) await applyRetention(meta).catch((thrown) => {
-					reportError(meta.runId, thrown);
-				});
-				continue;
-			}
-			if (active.has(meta.runId) || poisoned.has(meta.runId)) continue;
-			let lease;
-			try {
-				lease = await store.acquire(meta.runId, owner);
-			} catch (thrown) {
-				if (thrown instanceof LeaseHeldError) continue;
-				throw thrown;
-			}
-			try {
-				const entries = (await store.load(meta.runId)).map((raw) => normalizeEntry(raw));
-				scanJournalCompatibility(meta.runId, entries, registry);
-				if (meta.status === "suspended" && suspendedAt.get(meta.runId) === entries.length) {
-					await releaseQuietly(lease);
+		if (stopping || sweeping) return 0;
+		sweeping = true;
+		try {
+			let picked = 0;
+			const metas = options.retention === void 0 ? await store.listRuns({ statuses: [...CANDIDATE_STATUSES] }) : await store.listRuns();
+			const candidateIds = new Set(metas.filter((meta) => CANDIDATE_STATUSES.has(meta.status)).map((meta) => meta.runId));
+			for (const runId of [...suspendedAt.keys()]) if (!candidateIds.has(runId)) suspendedAt.delete(runId);
+			for (const runId of [...poisoned.keys()]) if (!candidateIds.has(runId)) poisoned.delete(runId);
+			for (const meta of metas) {
+				if (active.size >= concurrency) break;
+				if (!CANDIDATE_STATUSES.has(meta.status)) {
+					if (options.retention !== void 0 && !active.has(meta.runId)) await applyRetention(meta).catch((thrown) => {
+						reportError(meta.runId, thrown);
+					});
 					continue;
 				}
-				picked += 1;
-				drive(meta.runId, meta, lease);
-			} catch (thrown) {
-				await releaseQuietly(lease);
-				if (thrown instanceof JournalCompatibilityError || thrown instanceof ConfigError) {
-					poisoned.add(meta.runId);
+				if (active.has(meta.runId)) continue;
+				if (poisoned.has(meta.runId)) {
+					if (poisoned.get(meta.runId) === meta.genesis) continue;
+					poisoned.delete(meta.runId);
+				}
+				let lease;
+				try {
+					lease = await store.acquire(meta.runId, owner);
+				} catch (thrown) {
+					if (thrown instanceof LeaseHeldError) continue;
+					throw thrown;
+				}
+				try {
+					const entries = (await store.load(meta.runId)).map((raw) => normalizeEntry(raw));
+					scanJournalCompatibility(meta.runId, entries, registry);
+					const cached = suspendedAt.get(meta.runId);
+					if (meta.status === "suspended" && cached !== void 0 && cached.length === entries.length && cached.genesis === meta.genesis) {
+						await releaseQuietly(lease);
+						continue;
+					}
+					picked += 1;
+					drive(meta.runId, meta, lease);
+				} catch (thrown) {
+					await releaseQuietly(lease);
+					if (thrown instanceof JournalCompatibilityError || thrown instanceof ConfigError) {
+						poisoned.set(meta.runId, meta.genesis);
+						reportError(meta.runId, thrown);
+						continue;
+					}
 					reportError(meta.runId, thrown);
-					continue;
 				}
-				reportError(meta.runId, thrown);
 			}
+			return picked;
+		} finally {
+			sweeping = false;
 		}
-		return picked;
 	}
 	return {
 		start: () => {

package/dist/{io-CAXfPWq7.js → io-C3T5nbNg.js}

@@ -1,4 +1,4 @@
-import { ConfigError, FileModelKnowledgeStore, INBOX_PROPOSAL_TTL_DAYS, JsonlFileStore, claimExpired, claimExpiry, compilePermissionPreset, costReportFromJournal, createEngine, hashRunArgs, parseModelRef, priceUsdOf, proposalStatement, remeasureQueue, resolvePricing, runProfile, sanitizeTerminalText } from "@rulvar/core";
+import { ConfigError, FileModelKnowledgeStore, INBOX_PROPOSAL_TTL_DAYS, JsonlFileStore, claimExpired, claimExpiry, compilePermissionPreset, costReportFromJournal, createEngine, hashRunArgs, parseModelRef, priceUsdOf, proposalStatement, readRunMeta, remeasureQueue, resolvePricing, runProfile, sanitizeTerminalText } from "@rulvar/core";
 import { join, resolve } from "node:path";
 import { existsSync, statSync } from "node:fs";
 import { pathToFileURL } from "node:url";
@@ -777,7 +777,7 @@ async function resumeCommand(argv, context) {
 		...store === void 0 ? {} : { storePath: store },
 		cwd: context.cwd
 	});
-	const meta = (await assembled.store.listRuns()).find((m) => m.runId === runId);
+	const meta = await readRunMeta(assembled.store, runId);
 	if (meta === void 0) throw new ConfigError(`run '${runId}' not found in the store`);
 	enforceArgsBinding({
 		meta,
@@ -829,7 +829,7 @@ async function inspectCommand(argv, context) {
 		...store === void 0 ? {} : { storePath: store },
 		cwd: context.cwd
 	});
-	const meta = (await assembled.store.listRuns()).find((m) => m.runId === runId);
+	const meta = await readRunMeta(assembled.store, runId);
 	if (meta === void 0) throw new ConfigError(`run '${runId}' not found in the store`);
 	const entries = await assembled.store.load(runId);
 	context.io.out(`run ${meta.runId}: ${meta.status} (updated ${meta.updatedAt})`);
@@ -1087,7 +1087,7 @@ async function kbGateCommand(argv, context) {
 		...values.store === void 0 ? {} : { storePath: values.store },
 		cwd: context.cwd
 	});
-	const meta = (await assembled.store.listRuns()).find((candidate) => candidate.runId === runId);
+	const meta = await readRunMeta(assembled.store, 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`);

package/package.json

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