@rulvar/cli 1.26.0 → 1.27.0

package/dist/index.d.ts

@@ -188,6 +188,8 @@ interface CreateServerOptions {
   * 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.
+  * Validated at construction: a non-negative safe integer (zero keeps
+  * no settled runs), anything else is a typed ConfigError.
   */
   maxTrackedRuns?: number;
   /**
@@ -198,10 +200,33 @@ interface CreateServerOptions {
   * 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).
+  * historical behavior). Validated at construction: a positive safe
+  * integer, anything else is a typed ConfigError.
   */
   maxBufferedEventsPerRun?: number;
+  /**
+  * Upper bound on SSE frames PENDING in one client connection's
+  * response queue, replay and live feed alike (v1.26.0 deep E2E
+  * review P1-2: the replay buffer bound does not bound what a
+  * connected consumer that stopped reading accumulates). When a
+  * connection's pending queue reaches the bound, the server unhooks
+  * the feed, appends an SSE comment naming the bound, and CLOSES that
+  * connection; queued frames stay readable, and the standard
+  * Last-Event-ID reconnect resumes strictly after the last frame the
+  * client consumed. A replay longer than the bound is likewise
+  * delivered in bounded chunks across reconnects, so pending memory
+  * per connection is O(bound), never O(events). Validated at
+  * construction: a positive safe integer. Defaults to 10000.
+  */
+  maxPendingEventsPerClient?: number;
 }
+/**
+* The default per-connection pending-frame bound: generous enough that
+* a reading consumer never notices (a normal reader keeps the queue
+* near empty), small enough that a consumer that stopped reading
+* cannot grow process memory past a few megabytes per connection.
+*/
+declare const DEFAULT_MAX_PENDING_EVENTS_PER_CLIENT = 1e4;
 interface RulvarServer {
   fetch(req: Request): Promise<Response>;
 }
@@ -315,4 +340,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_STORE_DIR, DEFAULT_WORKER_TTL_MS, HELP, type RulvarServer, type SpanLike, type ToOtelOptions, type TracerLike, type Worker, assembleEngine, attachProgress, createServer, createWorker, driveRun, inspectCommand, loadCliConfig, loadWorkflowModule, looksLikeFile, processIo, renderEventLine, reportOutcome, resumeCommand, runCli, runCommand, runsLsCommand, 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 RulvarServer, type SpanLike, type ToOtelOptions, type TracerLike, type Worker, assembleEngine, attachProgress, createServer, createWorker, driveRun, inspectCommand, loadCliConfig, loadWorkflowModule, looksLikeFile, processIo, renderEventLine, reportOutcome, resumeCommand, runCli, runCommand, runsLsCommand, toOtel };

package/dist/index.js

@@ -20,7 +20,12 @@ import { ConfigError, InvalidResolutionError, JournalCompatibilityError, LeaseHe
 * 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`).
+* deduplicate on `replayed`). A terminal settle closes connected
+* streams only AFTER the segment's event pump has delivered the full
+* tail (run:end included), and every connection's pending queue is
+* bounded by maxPendingEventsPerClient: a consumer that stops reading
+* is closed at the bound and resumes through the standard
+* Last-Event-ID replay window (v1.26.0 deep E2E review P1-1/P1-2).
 *
 * 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
@@ -30,6 +35,13 @@ import { ConfigError, InvalidResolutionError, JournalCompatibilityError, LeaseHe
 * run resumes on a queue worker (createWorker, M8-T02), not here,
 * because original run arguments are not journaled in v1 (OQ-21).
 */
+/**
+* The default per-connection pending-frame bound: generous enough that
+* a reading consumer never notices (a normal reader keeps the queue
+* near empty), small enough that a consumer that stopped reading
+* cannot grow process memory past a few megabytes per connection.
+*/
+const DEFAULT_MAX_PENDING_EVENTS_PER_CLIENT = 1e4;
 const JSON_HEADERS = { "content-type": "application/json; charset=utf-8" };
 const wallClock = Date.now.bind(globalThis);
 function json(status, body) {
@@ -73,8 +85,22 @@ function suspensionKeyOf(entry) {
 	}
 	if (entry.kind === "approval") return `${APPROVAL_KEY_PREFIX}${entry.seq}`;
 }
+/**
+* Rejects a numeric cap outside its documented domain with a typed
+* ConfigError at construction (v1.26.0 deep E2E review P2-1: NaN
+* silently meant unbounded, Infinity looked like a cap without capping,
+* negatives and fractions produced policies nobody asked for).
+*/
+function requireCap(name, value, minimum) {
+	if (value === void 0) return;
+	if (!Number.isSafeInteger(value) || value < minimum) throw new ConfigError(`createServer ${name} must be a ${minimum === 0 ? "non-negative" : "positive"} safe integer, got ${String(value)}`);
+}
 function createServer(options) {
 	const { engine, workflows } = options;
+	requireCap("maxTrackedRuns", options.maxTrackedRuns, 0);
+	requireCap("maxBufferedEventsPerRun", options.maxBufferedEventsPerRun, 1);
+	requireCap("maxPendingEventsPerClient", options.maxPendingEventsPerClient, 1);
+	const pendingCap = options.maxPendingEventsPerClient ?? 1e4;
 	const journal = engine.stores.journal;
 	const runs = /* @__PURE__ */ new Map();
 	/**
@@ -107,32 +133,35 @@ function createServer(options) {
 	function attach(run, handle) {
 		run.handle = handle;
 		run.outcome = void 0;
-		(async () => {
+		let pumpFailed = false;
+		const pump = (async () => {
 			for await (const event of handle.events) {
 				pushBuffered(run, event);
 				for (const feed of [...run.feeds]) feed(event);
 			}
-		})().catch(() => void 0);
-		handle.result.then((outcome) => {
+		})().catch(() => {
+			pumpFailed = true;
+		});
+		handle.result.then(async (outcome) => {
 			run.outcome = outcome;
-			if (outcome.status !== "suspended") {
-				run.done = true;
-				for (const feed of [...run.feeds]) feed(null);
-				run.feeds.clear();
-				(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);
-			}
+			if (outcome.status === "suspended") return;
+			await pump;
+			run.done = true;
+			for (const feed of [...run.feeds]) feed(null, pumpFailed ? "event pump failed; the stream may be incomplete, reconnect with Last-Event-ID to replay" : void 0);
+			run.feeds.clear();
+			(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);
 	}
 	function track(runId, workflowName, args, handle) {
@@ -254,6 +283,13 @@ function createServer(options) {
 		const lastEventId = req.headers.get("last-event-id");
 		const encoder = new TextEncoder();
 		let feed;
+		const pendingOf = (controller) => {
+			const desired = controller.desiredSize;
+			return desired === null ? null : 1 - desired;
+		};
+		const slowConsumerComment = `: pending frames reached maxPendingEventsPerClient (${pendingCap}); reconnect with Last-Event-ID to continue
+
+`;
 		let cursor;
 		if (lastEventId !== null) {
 			const parsed = Number(lastEventId);
@@ -282,14 +318,33 @@ function createServer(options) {
 				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])));
+				for (let i = startIndex; i < run.buffer.length; i += 1) {
+					const pending = pendingOf(controller);
+					if (pending === null) return;
+					if (pending >= pendingCap) {
+						controller.enqueue(encoder.encode(slowConsumerComment));
+						controller.close();
+						return;
+					}
+					controller.enqueue(encoder.encode(sseFrame(run.buffer[i])));
+				}
 				if (run.done) {
 					controller.close();
 					return;
 				}
-				feed = (event) => {
+				feed = (event, note) => {
 					if (event === null) {
 						try {
+							if (note !== void 0) controller.enqueue(encoder.encode(`: ${note}\n\n`));
+							controller.close();
+						} catch {}
+						return;
+					}
+					const pending = pendingOf(controller);
+					if (pending !== null && pending >= pendingCap) {
+						if (feed !== void 0) run.feeds.delete(feed);
+						try {
+							controller.enqueue(encoder.encode(slowConsumerComment));
 							controller.close();
 						} catch {}
 						return;
@@ -312,7 +367,7 @@ function createServer(options) {
 	/** The tracked path: live (or settled-suspended) in this process. */
 	async function resolveTracked(run, key, value) {
 		const section = run.queue.then(async () => {
-			if (run.done) return json(409, { error: {
+			if (run.done || run.outcome !== void 0 && run.outcome.status !== "suspended") return json(409, { error: {
 				code: "config",
 				message: `run '${run.runId}' already settled '${run.outcome?.status ?? "unknown"}'`
 			} });
@@ -835,4 +890,4 @@ async function toOtel(run, tracer, options = {}) {
 	return created;
 }
 //#endregion
-export { DEFAULT_STORE_DIR, DEFAULT_WORKER_TTL_MS, HELP, assembleEngine, attachProgress, createServer, createWorker, driveRun, inspectCommand, loadCliConfig, loadWorkflowModule, looksLikeFile, processIo, renderEventLine, reportOutcome, resumeCommand, runCli, runCommand, runsLsCommand, toOtel };
+export { DEFAULT_MAX_PENDING_EVENTS_PER_CLIENT, DEFAULT_STORE_DIR, DEFAULT_WORKER_TTL_MS, HELP, assembleEngine, attachProgress, createServer, createWorker, driveRun, inspectCommand, loadCliConfig, loadWorkflowModule, looksLikeFile, processIo, renderEventLine, reportOutcome, resumeCommand, runCli, runCommand, runsLsCommand, toOtel };

package/package.json

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