@graphorin/server 0.6.0 → 0.7.0

package/dist/workflows/timer-daemon.d.ts

@@ -0,0 +1,69 @@
+//#region src/workflows/timer-daemon.d.ts
+/**
+ * W-032: durable-timer driver integration with the server lifecycle.
+ *
+ * Mirrors the triggers daemon: the operator builds a
+ * `createTimerDriver(...)` (from `@graphorin/workflow`) over their
+ * workflows + checkpoint stores and hands it to `createServer({
+ * workflowTimers: { driver } })`; the daemon binds `start()`/`stop()`
+ * to the lifecycle hooks and surfaces `status()` through `/v1/health`.
+ * The driver is typed STRUCTURALLY so `@graphorin/server` takes no
+ * dependency on `@graphorin/workflow`.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Structural slice of `@graphorin/workflow`'s `TimerDriver` the daemon
+ * consumes.
+ *
+ * @stable
+ */
+interface WorkflowTimerDriverLike {
+  start(): void;
+  stop(): void;
+  status(): {
+    readonly running: boolean;
+    readonly sweeps: number;
+    readonly fired: number;
+    readonly errors: number;
+    readonly lastSweepAt?: number;
+    readonly nextWakeAt?: number;
+  };
+  sweep(): Promise<number>;
+}
+/**
+ * Snapshot exposed via {@link WorkflowTimerDaemon.status} + the
+ * `/v1/health` aggregator.
+ *
+ * @stable
+ */
+interface WorkflowTimerDaemonStatus {
+  readonly running: boolean;
+  readonly sweeps: number;
+  readonly fired: number;
+  readonly errors: number;
+  readonly lastSweepAt?: string;
+  readonly nextWakeAt?: string;
+}
+/** @stable */
+interface CreateWorkflowTimerDaemonOptions {
+  readonly driver: WorkflowTimerDriverLike;
+}
+/**
+ * Stateful handle returned by {@link createWorkflowTimerDaemon}.
+ *
+ * @stable
+ */
+interface WorkflowTimerDaemon {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  status(): Promise<WorkflowTimerDaemonStatus>;
+  readonly driver: WorkflowTimerDriverLike;
+}
+/**
+ * @stable
+ */
+declare function createWorkflowTimerDaemon(options: CreateWorkflowTimerDaemonOptions): WorkflowTimerDaemon;
+//#endregion
+export { CreateWorkflowTimerDaemonOptions, WorkflowTimerDaemon, WorkflowTimerDaemonStatus, WorkflowTimerDriverLike, createWorkflowTimerDaemon };
+//# sourceMappingURL=timer-daemon.d.ts.map

package/dist/workflows/timer-daemon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timer-daemon.d.ts","names":[],"sources":["../../src/workflows/timer-daemon.ts"],"sourcesContent":[],"mappings":";;AAoBA;AAoBA;AAUA;AASA;;;;;;;AAUA;;;;;;;;UAjDiB,uBAAA;;;;;;;;;;;WAWN;;;;;;;;UASM,yBAAA;;;;;;;;;UAUA,gCAAA;mBACE;;;;;;;UAQF,mBAAA;WACN;UACD;YACE,QAAQ;mBACD;;;;;iBAMH,yBAAA,UACL,mCACR"}

package/dist/workflows/timer-daemon.js

@@ -0,0 +1,37 @@
+//#region src/workflows/timer-daemon.ts
+/**
+* @stable
+*/
+function createWorkflowTimerDaemon(options) {
+	let running = false;
+	return {
+		get driver() {
+			return options.driver;
+		},
+		async start() {
+			if (running) return;
+			running = true;
+			options.driver.start();
+		},
+		async stop() {
+			if (!running) return;
+			running = false;
+			options.driver.stop();
+		},
+		async status() {
+			const s = options.driver.status();
+			return Object.freeze({
+				running: s.running,
+				sweeps: s.sweeps,
+				fired: s.fired,
+				errors: s.errors,
+				...s.lastSweepAt !== void 0 ? { lastSweepAt: new Date(s.lastSweepAt).toISOString() } : {},
+				...s.nextWakeAt !== void 0 ? { nextWakeAt: new Date(s.nextWakeAt).toISOString() } : {}
+			});
+		}
+	};
+}
+
+//#endregion
+export { createWorkflowTimerDaemon };
+//# sourceMappingURL=timer-daemon.js.map

package/dist/workflows/timer-daemon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timer-daemon.js","names":[],"sources":["../../src/workflows/timer-daemon.ts"],"sourcesContent":["/**\n * W-032: durable-timer driver integration with the server lifecycle.\n *\n * Mirrors the triggers daemon: the operator builds a\n * `createTimerDriver(...)` (from `@graphorin/workflow`) over their\n * workflows + checkpoint stores and hands it to `createServer({\n * workflowTimers: { driver } })`; the daemon binds `start()`/`stop()`\n * to the lifecycle hooks and surfaces `status()` through `/v1/health`.\n * The driver is typed STRUCTURALLY so `@graphorin/server` takes no\n * dependency on `@graphorin/workflow`.\n *\n * @packageDocumentation\n */\n\n/**\n * Structural slice of `@graphorin/workflow`'s `TimerDriver` the daemon\n * consumes.\n *\n * @stable\n */\nexport interface WorkflowTimerDriverLike {\n  start(): void;\n  stop(): void;\n  status(): {\n    readonly running: boolean;\n    readonly sweeps: number;\n    readonly fired: number;\n    readonly errors: number;\n    readonly lastSweepAt?: number;\n    readonly nextWakeAt?: number;\n  };\n  sweep(): Promise<number>;\n}\n\n/**\n * Snapshot exposed via {@link WorkflowTimerDaemon.status} + the\n * `/v1/health` aggregator.\n *\n * @stable\n */\nexport interface WorkflowTimerDaemonStatus {\n  readonly running: boolean;\n  readonly sweeps: number;\n  readonly fired: number;\n  readonly errors: number;\n  readonly lastSweepAt?: string;\n  readonly nextWakeAt?: string;\n}\n\n/** @stable */\nexport interface CreateWorkflowTimerDaemonOptions {\n  readonly driver: WorkflowTimerDriverLike;\n}\n\n/**\n * Stateful handle returned by {@link createWorkflowTimerDaemon}.\n *\n * @stable\n */\nexport interface WorkflowTimerDaemon {\n  start(): Promise<void>;\n  stop(): Promise<void>;\n  status(): Promise<WorkflowTimerDaemonStatus>;\n  readonly driver: WorkflowTimerDriverLike;\n}\n\n/**\n * @stable\n */\nexport function createWorkflowTimerDaemon(\n  options: CreateWorkflowTimerDaemonOptions,\n): WorkflowTimerDaemon {\n  let running = false;\n  return {\n    get driver() {\n      return options.driver;\n    },\n    async start() {\n      if (running) return;\n      running = true;\n      options.driver.start();\n    },\n    async stop() {\n      if (!running) return;\n      running = false;\n      options.driver.stop();\n    },\n    async status() {\n      const s = options.driver.status();\n      return Object.freeze({\n        running: s.running,\n        sweeps: s.sweeps,\n        fired: s.fired,\n        errors: s.errors,\n        ...(s.lastSweepAt !== undefined\n          ? { lastSweepAt: new Date(s.lastSweepAt).toISOString() }\n          : {}),\n        ...(s.nextWakeAt !== undefined ? { nextWakeAt: new Date(s.nextWakeAt).toISOString() } : {}),\n      });\n    },\n  };\n}\n"],"mappings":";;;;AAqEA,SAAgB,0BACd,SACqB;CACrB,IAAI,UAAU;AACd,QAAO;EACL,IAAI,SAAS;AACX,UAAO,QAAQ;;EAEjB,MAAM,QAAQ;AACZ,OAAI,QAAS;AACb,aAAU;AACV,WAAQ,OAAO,OAAO;;EAExB,MAAM,OAAO;AACX,OAAI,CAAC,QAAS;AACd,aAAU;AACV,WAAQ,OAAO,MAAM;;EAEvB,MAAM,SAAS;GACb,MAAM,IAAI,QAAQ,OAAO,QAAQ;AACjC,UAAO,OAAO,OAAO;IACnB,SAAS,EAAE;IACX,QAAQ,EAAE;IACV,OAAO,EAAE;IACT,QAAQ,EAAE;IACV,GAAI,EAAE,gBAAgB,SAClB,EAAE,aAAa,IAAI,KAAK,EAAE,YAAY,CAAC,aAAa,EAAE,GACtD,EAAE;IACN,GAAI,EAAE,eAAe,SAAY,EAAE,YAAY,IAAI,KAAK,EAAE,WAAW,CAAC,aAAa,EAAE,GAAG,EAAE;IAC3F,CAAC;;EAEL"}

package/dist/ws/dispatcher.d.ts

@@ -3,8 +3,8 @@ import { DeliveryCommentarySanitizer } from "../commentary/sanitizer.js";
 import "../commentary/index.js";
 import { ReplayBuffer, ReplayBufferOptions } from "./replay-buffer.js";
 import { ParsedSubject } from "./subjects.js";
-import { ServerLifecycleFrame, ServerMessage } from "@graphorin/protocol";
 import { ParsedScope } from "@graphorin/security/auth";
+import { ServerLifecycleFrame, ServerMessage } from "@graphorin/protocol";
 
 //#region src/ws/dispatcher.d.ts
 

package/dist/ws/dispatcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatcher.d.ts","names":[],"sources":["../../src/ws/dispatcher.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;AA0EA;;;;;AA0BiB,UAhEA,mBAAA,CAgEsB;EAe3B,SAAA,UAAe,CAAA,EA9EH,wBAiFK;EAkBZ,SAAA,YAAY,CAAA,EAlGH,mBAkGG;EACP;;;;EAyBS,SAAA,uBAAA,CAAA,EAAA,MAAA;EAInB,SAAA,GAAA,CAAA,EAAA,GAAA,GAAA,MAAA;EAI6C;;;;AAazD;EA6BgB,SAAA,MAAA,CAAA,EAAA,CAAA,KAAkB,EAlKN,mBAkKgB,EAAA,GAAA,IAA2B;;;;;;;KA1J3D,mBAAA;;;mBAIW;;;;;;;;;;;;;;;;UAYN,kBAAA;;;0BAGS,cAAc;;cAE1B;;;;;;;;;;;;;;;;;;;;UAqBG,sBAAA;;;wBAGO;;;;;;;;;;;KAYZ,eAAA;;yBAGiB;;;;;;;;;;;;UAkBZ,YAAA;sBACK;yBACG;;;;;6BAKI;;;;;;;;;;;;;;MAYvB;;;;;;;+BAOyB;;gDAInB;;2CAI+B,cAAc;gDACT;;;;;;;;;;;;;;UAY/B,cAAA;;;;;;;;;;iBA6BD,kBAAA,WAA4B,sBAA2B"}
+{"version":3,"file":"dispatcher.d.ts","names":[],"sources":["../../src/ws/dispatcher.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;AA0EA;;;;;AA0BiB,UAhEA,mBAAA,CAgEsB;EAe3B,SAAA,UAAe,CAAA,EA9EH,wBAiFK;EAkBZ,SAAA,YAAY,CAAA,EAlGH,mBAkGG;EACP;;;;EAyBS,SAAA,uBAAA,CAAA,EAAA,MAAA;EAInB,SAAA,GAAA,CAAA,EAAA,GAAA,GAAA,MAAA;EAI6C;;;;AAazD;EA6BgB,SAAA,MAAA,CAAA,EAAA,CAAA,KAAkB,EAlKN,mBAkKgB,EAAA,GAAA,IAAA;;;;;;;KA1JhC,mBAAA;;;mBAIW;;;;;;;;;;;;;;;;UAYN,kBAAA;;;0BAGS,cAAc;;cAE1B;;;;;;;;;;;;;;;;;;;;UAqBG,sBAAA;;;wBAGO;;;;;;;;;;;KAYZ,eAAA;;yBAGiB;;;;;;;;;;;;UAkBZ,YAAA;sBACK;yBACG;;;;;6BAKI;;;;;;;;;;;;;;MAYvB;;;;;;;+BAOyB;;gDAInB;;2CAI+B,cAAc;gDACT;;;;;;;;;;;;;;UAY/B,cAAA;;;;;;;;;;iBA6BD,kBAAA,WAA4B,sBAA2B"}

package/dist/ws/dispatcher.js

@@ -1,5 +1,4 @@
 import { createDeliveryCommentarySanitizer } from "../commentary/sanitizer.js";
-import "../commentary/index.js";
 import { createReplayBuffer } from "./replay-buffer.js";
 import { isSubjectAllowed, tryParseSubject } from "./subjects.js";
 import { ServerMessageSchema, isEventFrame } from "@graphorin/protocol";
@@ -168,12 +167,10 @@ function createWsDispatcher(options = {}) {
 		let replayed = 0;
 		let snapshotEventId = replay.nextEventIdHint;
 		for (const event of replay.events) {
-			const frame = {
+			dispatchSanitized(record, {
 				...event,
 				subscriptionId: input.subscriptionId
-			};
-			validateAndDispatch(record, frame);
-			record.lastEventId = frame.eventId;
+			});
 			replayed += 1;
 		}
 		if (replay.droppedCount > 0) {
@@ -202,12 +199,25 @@ function createWsDispatcher(options = {}) {
 		subscriptions.delete(subscriptionId);
 		return true;
 	}
+	/**
+	* W-027: single choke point for delivering a frame to a
+	* subscription. Sanitizes, dispatches, and advances `lastEventId` -
+	* BOTH the live path and the replay path go through here so a future
+	* delivery path cannot silently bypass the commentary sanitizer
+	* (structural regression guard). `sanitize` no-ops on non-`event`
+	* frames and never changes `eventId`, so the ordering invariant is
+	* untouched.
+	*/
+	function dispatchSanitized(record, frame) {
+		const sanitized = sanitizer.sanitize(frame, "ws");
+		validateAndDispatch(record, sanitized);
+		record.lastEventId = sanitized.eventId;
+	}
 	function emit(subject, bare) {
-		const eventId = bare.eventId ?? nextEventId();
 		const bufferedFrame = {
 			v: "1",
 			kind: "event",
-			eventId,
+			eventId: bare.eventId ?? nextEventId(),
 			subscriptionId: "__pending__",
 			subject,
 			type: bare.type,
@@ -219,13 +229,10 @@ function createWsDispatcher(options = {}) {
 		for (const subscriptionId of subjectSubscribers) {
 			const record = subscriptions.get(subscriptionId);
 			if (record === void 0) continue;
-			const sanitized = sanitizer.sanitize({
+			dispatchSanitized(record, {
 				...bufferedFrame,
 				subscriptionId
-			}, "ws");
-			validateAndDispatch(record, sanitized);
-			record.lastEventId = sanitized.eventId;
-			if (sanitized.eventId === eventId) continue;
+			});
 		}
 	}
 	function emitLifecycle(subscriptionId, status, reason) {

package/dist/ws/dispatcher.js.map

@@ -1 +1 @@
-{"version":3,"file":"dispatcher.js","names":["record: SubscriptionRecord","snapshotEventId: string | undefined","frame: ServerEventFrame","bufferedFrame: ServerEventFrame"],"sources":["../../src/ws/dispatcher.ts"],"sourcesContent":["/**\n * Per-server WebSocket dispatcher. Owns the in-memory subscription\n * map, fans out events to matching connections, applies the\n * delivery-layer commentary-phase trace sanitization, validates\n * outbound frames against the `@graphorin/protocol` schema, and\n * exposes a tiny `emit(subject, event)` surface route handlers\n * (and the agent / workflow runtimes) consume.\n *\n * @packageDocumentation\n */\n\nimport {\n  isEventFrame,\n  type ServerEventFrame,\n  type ServerLifecycleFrame,\n  type ServerMessage,\n  ServerMessageSchema,\n} from '@graphorin/protocol';\nimport type { ParsedScope } from '@graphorin/security/auth';\nimport {\n  createDeliveryCommentarySanitizer,\n  type DeliveryCommentaryConfig,\n  type DeliveryCommentarySanitizer,\n} from '../commentary/index.js';\nimport {\n  createReplayBuffer,\n  type ReplayBuffer,\n  type ReplayBufferOptions,\n} from './replay-buffer.js';\nimport { isSubjectAllowed, type ParsedSubject, tryParseSubject } from './subjects.js';\n\n/**\n * Public configuration accepted by {@link createWsDispatcher}.\n *\n * @stable\n */\nexport interface WsDispatcherOptions {\n  readonly commentary?: DeliveryCommentaryConfig;\n  readonly replayBuffer?: ReplayBufferOptions;\n  /**\n   * Cap on outstanding events queued for an offline subscriber.\n   * Defaults to the same value as the replay buffer per-subject cap.\n   */\n  readonly perConnectionQueueLimit?: number;\n  readonly now?: () => number;\n  /**\n   * Logger sink for protocol violations + dropped frames. When\n   * omitted, the dispatcher is silent (production wiring uses the\n   * server's structured logger).\n   */\n  readonly onWarn?: (event: WsDispatcherWarning) => void;\n}\n\n/**\n * Discriminator surfaced to the optional warn sink.\n *\n * @stable\n */\nexport type WsDispatcherWarning =\n  | {\n      readonly kind: 'invalid-frame';\n      readonly subscriptionId: string;\n      readonly issues: ReadonlyArray<string>;\n    }\n  | { readonly kind: 'queue-overflow'; readonly subscriptionId: string }\n  | { readonly kind: 'subject-rejected'; readonly subject: string; readonly reason: string };\n\n/**\n * Subscriber surface used by the dispatcher. Each WebSocket\n * connection wraps its `WSContext.send` in this interface so the\n * dispatcher does not depend on `@hono/node-ws` types directly.\n *\n * @stable\n */\nexport interface WsSubscriberHandle {\n  readonly id: string;\n  readonly tokenId: string;\n  readonly grantedScopes: ReadonlyArray<ParsedScope>;\n  /** Send a server frame; the dispatcher already validated it. */\n  send(frame: ServerMessage): void;\n  /** Close the underlying WebSocket with a Graphorin close code. */\n  close(code: number, reason: string): void;\n  /**\n   * Optional buffered-byte sample. The dispatcher reads this on every\n   * emit to detect sustained backpressure and close the connection\n   * with the Graphorin `flow.throttled` code (4006) before the OS-\n   * level send buffer collapses. Consumers backed by `@hono/node-ws`\n   * can return the underlying `ws.bufferedAmount`. When the field is\n   * not implemented, the dispatcher falls back to the per-connection\n   * outstanding-event counter.\n   */\n  bufferedAmount?(): number;\n}\n\n/**\n * Snapshot of an active subscription. Surfaced via\n * {@link WsDispatcher.snapshotSubscription}.\n *\n * @stable\n */\nexport interface WsSubscriptionSnapshot {\n  readonly subscriptionId: string;\n  readonly subject: string;\n  readonly subjectKind: ParsedSubject['kind'];\n  readonly subscriberId: string;\n  readonly tokenId: string;\n  readonly createdAt: number;\n  readonly lastEventId: string | undefined;\n}\n\n/**\n * Result of {@link WsDispatcher.subscribe}.\n *\n * @stable\n */\nexport type SubscribeResult =\n  | {\n      readonly ok: true;\n      readonly subscription: WsSubscriptionSnapshot;\n      readonly replayedCount: number;\n      readonly snapshotEventId: string | undefined;\n    }\n  | {\n      readonly ok: false;\n      readonly reason:\n        | 'subject-malformed'\n        | 'subject-unknown'\n        | 'subject-wildcard'\n        | 'scope-denied';\n    };\n\n/**\n * Public surface of the dispatcher.\n *\n * @stable\n */\nexport interface WsDispatcher {\n  readonly sanitizer: DeliveryCommentarySanitizer;\n  readonly replayBuffer: ReplayBuffer;\n  /**\n   * Register a subscriber (one per WebSocket connection).\n   * `unregister` is called on close.\n   */\n  registerSubscriber(handle: WsSubscriberHandle): { unregister(): void };\n  /**\n   * Open a new subscription for an active subscriber. Returns either\n   * the subscription snapshot + replayed-event count or a typed\n   * failure reason the caller maps to the appropriate close code /\n   * RPC error.\n   */\n  subscribe(input: {\n    readonly subscriberId: string;\n    readonly subject: string;\n    readonly subscriptionId: string;\n    readonly sinceEventId?: string;\n  }): SubscribeResult;\n  unsubscribe(subscriptionId: string): boolean;\n  /**\n   * Push an event into the dispatcher. Goes through the sanitizer,\n   * validates against the protocol schema, persists into the replay\n   * buffer, and fans out to every matching active subscription.\n   */\n  emit(subject: string, frame: BareEventFrame): void;\n  /** Push a lifecycle frame to a single subscription. */\n  emitLifecycle(\n    subscriptionId: string,\n    status: ServerLifecycleFrame['status'],\n    reason?: string,\n  ): void;\n  /** List active subscriptions for a given subscriber (diagnostics). */\n  listForSubscriber(subscriberId: string): ReadonlyArray<WsSubscriptionSnapshot>;\n  snapshotSubscription(subscriptionId: string): WsSubscriptionSnapshot | undefined;\n  size(): { readonly subscribers: number; readonly subscriptions: number };\n  /** Clear in-memory state (used during graceful shutdown). */\n  shutdown(): void;\n}\n\n/**\n * Frame argument accepted by {@link WsDispatcher.emit}. The\n * dispatcher fills in `subscriptionId`, `subject`, and `eventId`.\n *\n * @stable\n */\nexport interface BareEventFrame {\n  readonly type: string;\n  readonly payload: unknown;\n  readonly eventId?: string;\n}\n\ninterface SubscriberRecord {\n  readonly handle: WsSubscriberHandle;\n  readonly subscriptions: Set<string>;\n  outstandingEvents: number;\n  closed: boolean;\n}\n\ninterface SubscriptionRecord {\n  readonly subscriberId: string;\n  /** IP-18: the authenticating principal's token id (not the connection id). */\n  readonly tokenId: string;\n  readonly subscriptionId: string;\n  readonly subject: string;\n  readonly parsed: ParsedSubject;\n  readonly createdAt: number;\n  lastEventId: string | undefined;\n}\n\n/**\n * Build a fresh dispatcher.\n *\n * @stable\n */\nexport function createWsDispatcher(options: WsDispatcherOptions = {}): WsDispatcher {\n  const sanitizer = createDeliveryCommentarySanitizer(options.commentary);\n  const replayBuffer = createReplayBuffer(options.replayBuffer ?? {});\n  const now = options.now ?? Date.now;\n  const onWarn = options.onWarn;\n  const perConnectionQueueLimit = options.perConnectionQueueLimit ?? 1_000;\n  const subscribers = new Map<string, SubscriberRecord>();\n  const subscriptions = new Map<string, SubscriptionRecord>();\n  const subjectIndex = new Map<string, Set<string>>();\n  let eventCounter = 0;\n\n  function indexSubject(subject: string, subscriptionId: string): void {\n    let set = subjectIndex.get(subject);\n    if (set === undefined) {\n      set = new Set();\n      subjectIndex.set(subject, set);\n    }\n    set.add(subscriptionId);\n  }\n\n  function deindexSubject(subject: string, subscriptionId: string): void {\n    const set = subjectIndex.get(subject);\n    if (set === undefined) return;\n    set.delete(subscriptionId);\n    if (set.size === 0) subjectIndex.delete(subject);\n  }\n\n  function nextEventId(): string {\n    eventCounter += 1;\n    return `evt-${now().toString(36)}-${eventCounter.toString(36)}`;\n  }\n\n  function dispatchToSubscriber(record: SubscriptionRecord, frame: ServerMessage): void {\n    const subscriber = subscribers.get(record.subscriberId);\n    if (subscriber === undefined || subscriber.closed) return;\n    // Per-connection backpressure: track the outstanding-event counter\n    // and consult the optional `bufferedAmount()` sample. The\n    // dispatcher closes the connection with the Graphorin\n    // `flow.throttled` code (4006) when either signal exceeds the\n    // configured limit so the client can reconnect against the\n    // replay buffer instead of accumulating an unbounded send queue.\n    const buffered =\n      typeof subscriber.handle.bufferedAmount === 'function'\n        ? subscriber.handle.bufferedAmount()\n        : 0;\n    if (\n      subscriber.outstandingEvents >= perConnectionQueueLimit ||\n      buffered >= perConnectionQueueLimit * 1024\n    ) {\n      onWarn?.({ kind: 'queue-overflow', subscriptionId: record.subscriptionId });\n      shutdownSubscriber(subscriber, 4006, 'flow.throttled');\n      return;\n    }\n    subscriber.outstandingEvents += 1;\n    try {\n      subscriber.handle.send(frame);\n    } catch (err) {\n      onWarn?.({ kind: 'queue-overflow', subscriptionId: record.subscriptionId });\n      shutdownSubscriber(subscriber, 4006, 'flow.throttled');\n      void err;\n    } finally {\n      subscriber.outstandingEvents = Math.max(0, subscriber.outstandingEvents - 1);\n    }\n  }\n\n  function shutdownSubscriber(subscriber: SubscriberRecord, code: number, reason: string): void {\n    if (subscriber.closed) return;\n    subscriber.closed = true;\n    try {\n      subscriber.handle.close(code, reason);\n    } catch {\n      // ignore - we are tearing the subscriber down.\n    }\n    for (const id of subscriber.subscriptions) {\n      const sub = subscriptions.get(id);\n      if (sub !== undefined) {\n        deindexSubject(sub.subject, id);\n        subscriptions.delete(id);\n      }\n    }\n    subscriber.subscriptions.clear();\n    subscribers.delete(subscriber.handle.id);\n  }\n\n  function validateAndDispatch(record: SubscriptionRecord, frame: ServerMessage): void {\n    const validated = ServerMessageSchema.safeParse(frame);\n    if (!validated.success) {\n      onWarn?.({\n        kind: 'invalid-frame',\n        subscriptionId: record.subscriptionId,\n        issues: validated.error.issues.map((i) => `${i.path.join('.') || '<root>'}: ${i.message}`),\n      });\n      return;\n    }\n    dispatchToSubscriber(record, validated.data);\n  }\n\n  function registerSubscriber(handle: WsSubscriberHandle): { unregister(): void } {\n    subscribers.set(handle.id, {\n      handle,\n      subscriptions: new Set(),\n      outstandingEvents: 0,\n      closed: false,\n    });\n    return {\n      unregister: () => {\n        const record = subscribers.get(handle.id);\n        if (record === undefined) return;\n        for (const id of record.subscriptions) {\n          const sub = subscriptions.get(id);\n          if (sub !== undefined) {\n            deindexSubject(sub.subject, id);\n            subscriptions.delete(id);\n          }\n        }\n        subscribers.delete(handle.id);\n      },\n    };\n  }\n\n  function subscribe(input: {\n    readonly subscriberId: string;\n    readonly subject: string;\n    readonly subscriptionId: string;\n    readonly sinceEventId?: string;\n  }): SubscribeResult {\n    const subscriber = subscribers.get(input.subscriberId);\n    if (subscriber === undefined) {\n      return { ok: false, reason: 'subject-unknown' };\n    }\n    const parseResult = tryParseSubject(input.subject);\n    if (!parseResult.ok) {\n      const reason = parseResult.reason;\n      onWarn?.({ kind: 'subject-rejected', subject: input.subject, reason });\n      if (reason === 'wildcard-not-supported') return { ok: false, reason: 'subject-wildcard' };\n      if (reason === 'unknown-subject') return { ok: false, reason: 'subject-unknown' };\n      return { ok: false, reason: 'subject-malformed' };\n    }\n    if (!isSubjectAllowed(subscriber.handle.grantedScopes, parseResult.subject)) {\n      return { ok: false, reason: 'scope-denied' };\n    }\n    const record: SubscriptionRecord = {\n      subscriberId: input.subscriberId,\n      tokenId: subscriber.handle.tokenId,\n      subscriptionId: input.subscriptionId,\n      subject: input.subject,\n      parsed: parseResult.subject,\n      createdAt: now(),\n      lastEventId: undefined,\n    };\n    subscriptions.set(input.subscriptionId, record);\n    subscriber.subscriptions.add(input.subscriptionId);\n    indexSubject(input.subject, input.subscriptionId);\n    const replay = replayBuffer.replay(input.subject, input.sinceEventId);\n    let replayed = 0;\n    let snapshotEventId: string | undefined = replay.nextEventIdHint;\n    for (const event of replay.events) {\n      const frame: ServerEventFrame = {\n        ...event,\n        subscriptionId: input.subscriptionId,\n      };\n      validateAndDispatch(record, frame);\n      record.lastEventId = frame.eventId;\n      replayed += 1;\n    }\n    if (replay.droppedCount > 0) {\n      validateAndDispatch(record, {\n        v: '1',\n        kind: 'replay-marker',\n        subscriptionId: input.subscriptionId,\n        eventId: snapshotEventId ?? `evt-replay-${now().toString(36)}`,\n        droppedCount: replay.droppedCount,\n        note: `Replay buffer dropped ${replay.droppedCount} events before resume.`,\n      });\n      snapshotEventId = snapshotEventId ?? `evt-replay-${now().toString(36)}`;\n    }\n    return {\n      ok: true,\n      subscription: snapshotForRecord(record),\n      replayedCount: replayed,\n      snapshotEventId,\n    };\n  }\n\n  function unsubscribe(subscriptionId: string): boolean {\n    const record = subscriptions.get(subscriptionId);\n    if (record === undefined) return false;\n    const subscriber = subscribers.get(record.subscriberId);\n    subscriber?.subscriptions.delete(subscriptionId);\n    deindexSubject(record.subject, subscriptionId);\n    subscriptions.delete(subscriptionId);\n    return true;\n  }\n\n  function emit(subject: string, bare: BareEventFrame): void {\n    const eventId = bare.eventId ?? nextEventId();\n    // Buffer first so the replay layer captures every event, even\n    // when there is no live subscriber. The buffered frame is\n    // sanitizer-neutral (the per-subscription dispatch sanitizes\n    // again on the wire so the second pass is idempotent - by\n    // construction matching wraps are not re-wrapped).\n    const bufferedFrame: ServerEventFrame = {\n      v: '1',\n      kind: 'event',\n      eventId,\n      subscriptionId: '__pending__',\n      subject,\n      type: bare.type,\n      payload: bare.payload,\n    };\n    replayBuffer.push(subject, bufferedFrame);\n    const subjectSubscribers = subjectIndex.get(subject);\n    if (subjectSubscribers === undefined || subjectSubscribers.size === 0) return;\n    for (const subscriptionId of subjectSubscribers) {\n      const record = subscriptions.get(subscriptionId);\n      if (record === undefined) continue;\n      const sanitized = sanitizer.sanitize({ ...bufferedFrame, subscriptionId }, 'ws');\n      validateAndDispatch(record, sanitized);\n      record.lastEventId = sanitized.eventId;\n      if (sanitized.eventId === eventId) continue;\n    }\n    void isEventFrame; // keep import warm\n  }\n\n  function emitLifecycle(\n    subscriptionId: string,\n    status: ServerLifecycleFrame['status'],\n    reason?: string,\n  ): void {\n    const record = subscriptions.get(subscriptionId);\n    if (record === undefined) return;\n    const frame: ServerLifecycleFrame = {\n      v: '1',\n      kind: 'lifecycle',\n      subscriptionId,\n      status,\n      ...(reason !== undefined ? { reason } : {}),\n    };\n    validateAndDispatch(record, frame);\n  }\n\n  function listForSubscriber(subscriberId: string): ReadonlyArray<WsSubscriptionSnapshot> {\n    const subscriber = subscribers.get(subscriberId);\n    if (subscriber === undefined) return Object.freeze([]);\n    return Object.freeze(\n      [...subscriber.subscriptions]\n        .map((id) => subscriptions.get(id))\n        .filter((entry): entry is SubscriptionRecord => entry !== undefined)\n        .map(snapshotForRecord),\n    );\n  }\n\n  function snapshotSubscription(subscriptionId: string): WsSubscriptionSnapshot | undefined {\n    const record = subscriptions.get(subscriptionId);\n    if (record === undefined) return undefined;\n    return snapshotForRecord(record);\n  }\n\n  function size(): { readonly subscribers: number; readonly subscriptions: number } {\n    return Object.freeze({\n      subscribers: subscribers.size,\n      subscriptions: subscriptions.size,\n    });\n  }\n\n  function shutdown(): void {\n    for (const subscription of subscriptions.values()) {\n      const subscriber = subscribers.get(subscription.subscriberId);\n      try {\n        subscriber?.handle.send({\n          v: '1',\n          kind: 'lifecycle',\n          subscriptionId: subscription.subscriptionId,\n          status: 'aborted',\n          reason: 'server-shutdown',\n        });\n      } catch {\n        // swallow - we are tearing down.\n      }\n    }\n    subscriptions.clear();\n    subjectIndex.clear();\n    subscribers.clear();\n  }\n\n  return Object.freeze({\n    sanitizer,\n    replayBuffer,\n    registerSubscriber,\n    subscribe,\n    unsubscribe,\n    emit,\n    emitLifecycle,\n    listForSubscriber,\n    snapshotSubscription,\n    size,\n    shutdown,\n  });\n}\n\nfunction snapshotForRecord(record: SubscriptionRecord): WsSubscriptionSnapshot {\n  return Object.freeze({\n    subscriptionId: record.subscriptionId,\n    subject: record.subject,\n    subjectKind: record.parsed.kind,\n    subscriberId: record.subscriberId,\n    tokenId: record.tokenId,\n    createdAt: record.createdAt,\n    lastEventId: record.lastEventId,\n  });\n}\n"],"mappings":"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"}
+{"version":3,"file":"dispatcher.js","names":["record: SubscriptionRecord","snapshotEventId: string | undefined","bufferedFrame: ServerEventFrame"],"sources":["../../src/ws/dispatcher.ts"],"sourcesContent":["/**\n * Per-server WebSocket dispatcher. Owns the in-memory subscription\n * map, fans out events to matching connections, applies the\n * delivery-layer commentary-phase trace sanitization, validates\n * outbound frames against the `@graphorin/protocol` schema, and\n * exposes a tiny `emit(subject, event)` surface route handlers\n * (and the agent / workflow runtimes) consume.\n *\n * @packageDocumentation\n */\n\nimport {\n  isEventFrame,\n  type ServerEventFrame,\n  type ServerLifecycleFrame,\n  type ServerMessage,\n  ServerMessageSchema,\n} from '@graphorin/protocol';\nimport type { ParsedScope } from '@graphorin/security/auth';\nimport {\n  createDeliveryCommentarySanitizer,\n  type DeliveryCommentaryConfig,\n  type DeliveryCommentarySanitizer,\n} from '../commentary/index.js';\nimport {\n  createReplayBuffer,\n  type ReplayBuffer,\n  type ReplayBufferOptions,\n} from './replay-buffer.js';\nimport { isSubjectAllowed, type ParsedSubject, tryParseSubject } from './subjects.js';\n\n/**\n * Public configuration accepted by {@link createWsDispatcher}.\n *\n * @stable\n */\nexport interface WsDispatcherOptions {\n  readonly commentary?: DeliveryCommentaryConfig;\n  readonly replayBuffer?: ReplayBufferOptions;\n  /**\n   * Cap on outstanding events queued for an offline subscriber.\n   * Defaults to the same value as the replay buffer per-subject cap.\n   */\n  readonly perConnectionQueueLimit?: number;\n  readonly now?: () => number;\n  /**\n   * Logger sink for protocol violations + dropped frames. When\n   * omitted, the dispatcher is silent (production wiring uses the\n   * server's structured logger).\n   */\n  readonly onWarn?: (event: WsDispatcherWarning) => void;\n}\n\n/**\n * Discriminator surfaced to the optional warn sink.\n *\n * @stable\n */\nexport type WsDispatcherWarning =\n  | {\n      readonly kind: 'invalid-frame';\n      readonly subscriptionId: string;\n      readonly issues: ReadonlyArray<string>;\n    }\n  | { readonly kind: 'queue-overflow'; readonly subscriptionId: string }\n  | { readonly kind: 'subject-rejected'; readonly subject: string; readonly reason: string };\n\n/**\n * Subscriber surface used by the dispatcher. Each WebSocket\n * connection wraps its `WSContext.send` in this interface so the\n * dispatcher does not depend on `@hono/node-ws` types directly.\n *\n * @stable\n */\nexport interface WsSubscriberHandle {\n  readonly id: string;\n  readonly tokenId: string;\n  readonly grantedScopes: ReadonlyArray<ParsedScope>;\n  /** Send a server frame; the dispatcher already validated it. */\n  send(frame: ServerMessage): void;\n  /** Close the underlying WebSocket with a Graphorin close code. */\n  close(code: number, reason: string): void;\n  /**\n   * Optional buffered-byte sample. The dispatcher reads this on every\n   * emit to detect sustained backpressure and close the connection\n   * with the Graphorin `flow.throttled` code (4006) before the OS-\n   * level send buffer collapses. Consumers backed by `@hono/node-ws`\n   * can return the underlying `ws.bufferedAmount`. When the field is\n   * not implemented, the dispatcher falls back to the per-connection\n   * outstanding-event counter.\n   */\n  bufferedAmount?(): number;\n}\n\n/**\n * Snapshot of an active subscription. Surfaced via\n * {@link WsDispatcher.snapshotSubscription}.\n *\n * @stable\n */\nexport interface WsSubscriptionSnapshot {\n  readonly subscriptionId: string;\n  readonly subject: string;\n  readonly subjectKind: ParsedSubject['kind'];\n  readonly subscriberId: string;\n  readonly tokenId: string;\n  readonly createdAt: number;\n  readonly lastEventId: string | undefined;\n}\n\n/**\n * Result of {@link WsDispatcher.subscribe}.\n *\n * @stable\n */\nexport type SubscribeResult =\n  | {\n      readonly ok: true;\n      readonly subscription: WsSubscriptionSnapshot;\n      readonly replayedCount: number;\n      readonly snapshotEventId: string | undefined;\n    }\n  | {\n      readonly ok: false;\n      readonly reason:\n        | 'subject-malformed'\n        | 'subject-unknown'\n        | 'subject-wildcard'\n        | 'scope-denied';\n    };\n\n/**\n * Public surface of the dispatcher.\n *\n * @stable\n */\nexport interface WsDispatcher {\n  readonly sanitizer: DeliveryCommentarySanitizer;\n  readonly replayBuffer: ReplayBuffer;\n  /**\n   * Register a subscriber (one per WebSocket connection).\n   * `unregister` is called on close.\n   */\n  registerSubscriber(handle: WsSubscriberHandle): { unregister(): void };\n  /**\n   * Open a new subscription for an active subscriber. Returns either\n   * the subscription snapshot + replayed-event count or a typed\n   * failure reason the caller maps to the appropriate close code /\n   * RPC error.\n   */\n  subscribe(input: {\n    readonly subscriberId: string;\n    readonly subject: string;\n    readonly subscriptionId: string;\n    readonly sinceEventId?: string;\n  }): SubscribeResult;\n  unsubscribe(subscriptionId: string): boolean;\n  /**\n   * Push an event into the dispatcher. Goes through the sanitizer,\n   * validates against the protocol schema, persists into the replay\n   * buffer, and fans out to every matching active subscription.\n   */\n  emit(subject: string, frame: BareEventFrame): void;\n  /** Push a lifecycle frame to a single subscription. */\n  emitLifecycle(\n    subscriptionId: string,\n    status: ServerLifecycleFrame['status'],\n    reason?: string,\n  ): void;\n  /** List active subscriptions for a given subscriber (diagnostics). */\n  listForSubscriber(subscriberId: string): ReadonlyArray<WsSubscriptionSnapshot>;\n  snapshotSubscription(subscriptionId: string): WsSubscriptionSnapshot | undefined;\n  size(): { readonly subscribers: number; readonly subscriptions: number };\n  /** Clear in-memory state (used during graceful shutdown). */\n  shutdown(): void;\n}\n\n/**\n * Frame argument accepted by {@link WsDispatcher.emit}. The\n * dispatcher fills in `subscriptionId`, `subject`, and `eventId`.\n *\n * @stable\n */\nexport interface BareEventFrame {\n  readonly type: string;\n  readonly payload: unknown;\n  readonly eventId?: string;\n}\n\ninterface SubscriberRecord {\n  readonly handle: WsSubscriberHandle;\n  readonly subscriptions: Set<string>;\n  outstandingEvents: number;\n  closed: boolean;\n}\n\ninterface SubscriptionRecord {\n  readonly subscriberId: string;\n  /** IP-18: the authenticating principal's token id (not the connection id). */\n  readonly tokenId: string;\n  readonly subscriptionId: string;\n  readonly subject: string;\n  readonly parsed: ParsedSubject;\n  readonly createdAt: number;\n  lastEventId: string | undefined;\n}\n\n/**\n * Build a fresh dispatcher.\n *\n * @stable\n */\nexport function createWsDispatcher(options: WsDispatcherOptions = {}): WsDispatcher {\n  const sanitizer = createDeliveryCommentarySanitizer(options.commentary);\n  const replayBuffer = createReplayBuffer(options.replayBuffer ?? {});\n  const now = options.now ?? Date.now;\n  const onWarn = options.onWarn;\n  const perConnectionQueueLimit = options.perConnectionQueueLimit ?? 1_000;\n  const subscribers = new Map<string, SubscriberRecord>();\n  const subscriptions = new Map<string, SubscriptionRecord>();\n  const subjectIndex = new Map<string, Set<string>>();\n  let eventCounter = 0;\n\n  function indexSubject(subject: string, subscriptionId: string): void {\n    let set = subjectIndex.get(subject);\n    if (set === undefined) {\n      set = new Set();\n      subjectIndex.set(subject, set);\n    }\n    set.add(subscriptionId);\n  }\n\n  function deindexSubject(subject: string, subscriptionId: string): void {\n    const set = subjectIndex.get(subject);\n    if (set === undefined) return;\n    set.delete(subscriptionId);\n    if (set.size === 0) subjectIndex.delete(subject);\n  }\n\n  function nextEventId(): string {\n    eventCounter += 1;\n    return `evt-${now().toString(36)}-${eventCounter.toString(36)}`;\n  }\n\n  function dispatchToSubscriber(record: SubscriptionRecord, frame: ServerMessage): void {\n    const subscriber = subscribers.get(record.subscriberId);\n    if (subscriber === undefined || subscriber.closed) return;\n    // Per-connection backpressure: track the outstanding-event counter\n    // and consult the optional `bufferedAmount()` sample. The\n    // dispatcher closes the connection with the Graphorin\n    // `flow.throttled` code (4006) when either signal exceeds the\n    // configured limit so the client can reconnect against the\n    // replay buffer instead of accumulating an unbounded send queue.\n    const buffered =\n      typeof subscriber.handle.bufferedAmount === 'function'\n        ? subscriber.handle.bufferedAmount()\n        : 0;\n    if (\n      subscriber.outstandingEvents >= perConnectionQueueLimit ||\n      buffered >= perConnectionQueueLimit * 1024\n    ) {\n      onWarn?.({ kind: 'queue-overflow', subscriptionId: record.subscriptionId });\n      shutdownSubscriber(subscriber, 4006, 'flow.throttled');\n      return;\n    }\n    subscriber.outstandingEvents += 1;\n    try {\n      subscriber.handle.send(frame);\n    } catch (err) {\n      onWarn?.({ kind: 'queue-overflow', subscriptionId: record.subscriptionId });\n      shutdownSubscriber(subscriber, 4006, 'flow.throttled');\n      void err;\n    } finally {\n      subscriber.outstandingEvents = Math.max(0, subscriber.outstandingEvents - 1);\n    }\n  }\n\n  function shutdownSubscriber(subscriber: SubscriberRecord, code: number, reason: string): void {\n    if (subscriber.closed) return;\n    subscriber.closed = true;\n    try {\n      subscriber.handle.close(code, reason);\n    } catch {\n      // ignore - we are tearing the subscriber down.\n    }\n    for (const id of subscriber.subscriptions) {\n      const sub = subscriptions.get(id);\n      if (sub !== undefined) {\n        deindexSubject(sub.subject, id);\n        subscriptions.delete(id);\n      }\n    }\n    subscriber.subscriptions.clear();\n    subscribers.delete(subscriber.handle.id);\n  }\n\n  function validateAndDispatch(record: SubscriptionRecord, frame: ServerMessage): void {\n    const validated = ServerMessageSchema.safeParse(frame);\n    if (!validated.success) {\n      onWarn?.({\n        kind: 'invalid-frame',\n        subscriptionId: record.subscriptionId,\n        issues: validated.error.issues.map((i) => `${i.path.join('.') || '<root>'}: ${i.message}`),\n      });\n      return;\n    }\n    dispatchToSubscriber(record, validated.data);\n  }\n\n  function registerSubscriber(handle: WsSubscriberHandle): { unregister(): void } {\n    subscribers.set(handle.id, {\n      handle,\n      subscriptions: new Set(),\n      outstandingEvents: 0,\n      closed: false,\n    });\n    return {\n      unregister: () => {\n        const record = subscribers.get(handle.id);\n        if (record === undefined) return;\n        for (const id of record.subscriptions) {\n          const sub = subscriptions.get(id);\n          if (sub !== undefined) {\n            deindexSubject(sub.subject, id);\n            subscriptions.delete(id);\n          }\n        }\n        subscribers.delete(handle.id);\n      },\n    };\n  }\n\n  function subscribe(input: {\n    readonly subscriberId: string;\n    readonly subject: string;\n    readonly subscriptionId: string;\n    readonly sinceEventId?: string;\n  }): SubscribeResult {\n    const subscriber = subscribers.get(input.subscriberId);\n    if (subscriber === undefined) {\n      return { ok: false, reason: 'subject-unknown' };\n    }\n    const parseResult = tryParseSubject(input.subject);\n    if (!parseResult.ok) {\n      const reason = parseResult.reason;\n      onWarn?.({ kind: 'subject-rejected', subject: input.subject, reason });\n      if (reason === 'wildcard-not-supported') return { ok: false, reason: 'subject-wildcard' };\n      if (reason === 'unknown-subject') return { ok: false, reason: 'subject-unknown' };\n      return { ok: false, reason: 'subject-malformed' };\n    }\n    if (!isSubjectAllowed(subscriber.handle.grantedScopes, parseResult.subject)) {\n      return { ok: false, reason: 'scope-denied' };\n    }\n    const record: SubscriptionRecord = {\n      subscriberId: input.subscriberId,\n      tokenId: subscriber.handle.tokenId,\n      subscriptionId: input.subscriptionId,\n      subject: input.subject,\n      parsed: parseResult.subject,\n      createdAt: now(),\n      lastEventId: undefined,\n    };\n    subscriptions.set(input.subscriptionId, record);\n    subscriber.subscriptions.add(input.subscriptionId);\n    indexSubject(input.subject, input.subscriptionId);\n    const replay = replayBuffer.replay(input.subject, input.sinceEventId);\n    let replayed = 0;\n    let snapshotEventId: string | undefined = replay.nextEventIdHint;\n    for (const event of replay.events) {\n      // W-027: the buffer stores RAW frames, so the replay path (fresh\n      // subscription or reconnect-resume) must sanitize per delivery\n      // exactly like the live path and the SSE replay do - otherwise\n      // the commentary policy is defeated precisely on the reconnect\n      // scenario the buffer exists for.\n      dispatchSanitized(record, { ...event, subscriptionId: input.subscriptionId });\n      replayed += 1;\n    }\n    if (replay.droppedCount > 0) {\n      // The replay-marker is dispatcher-authored (no payload to\n      // sanitize) and deliberately does NOT advance lastEventId.\n      validateAndDispatch(record, {\n        v: '1',\n        kind: 'replay-marker',\n        subscriptionId: input.subscriptionId,\n        eventId: snapshotEventId ?? `evt-replay-${now().toString(36)}`,\n        droppedCount: replay.droppedCount,\n        note: `Replay buffer dropped ${replay.droppedCount} events before resume.`,\n      });\n      snapshotEventId = snapshotEventId ?? `evt-replay-${now().toString(36)}`;\n    }\n    return {\n      ok: true,\n      subscription: snapshotForRecord(record),\n      replayedCount: replayed,\n      snapshotEventId,\n    };\n  }\n\n  function unsubscribe(subscriptionId: string): boolean {\n    const record = subscriptions.get(subscriptionId);\n    if (record === undefined) return false;\n    const subscriber = subscribers.get(record.subscriberId);\n    subscriber?.subscriptions.delete(subscriptionId);\n    deindexSubject(record.subject, subscriptionId);\n    subscriptions.delete(subscriptionId);\n    return true;\n  }\n\n  /**\n   * W-027: single choke point for delivering a frame to a\n   * subscription. Sanitizes, dispatches, and advances `lastEventId` -\n   * BOTH the live path and the replay path go through here so a future\n   * delivery path cannot silently bypass the commentary sanitizer\n   * (structural regression guard). `sanitize` no-ops on non-`event`\n   * frames and never changes `eventId`, so the ordering invariant is\n   * untouched.\n   */\n  function dispatchSanitized(record: SubscriptionRecord, frame: ServerEventFrame): void {\n    const sanitized = sanitizer.sanitize(frame, 'ws');\n    validateAndDispatch(record, sanitized);\n    record.lastEventId = sanitized.eventId;\n  }\n\n  function emit(subject: string, bare: BareEventFrame): void {\n    const eventId = bare.eventId ?? nextEventId();\n    // Buffer first so the replay layer captures every event, even\n    // when there is no live subscriber. The buffered frame is\n    // sanitizer-neutral (both the live dispatch and the replay\n    // dispatch sanitize per delivery, so a buffered raw frame is\n    // sanitized exactly once on every path that reaches a wire).\n    const bufferedFrame: ServerEventFrame = {\n      v: '1',\n      kind: 'event',\n      eventId,\n      subscriptionId: '__pending__',\n      subject,\n      type: bare.type,\n      payload: bare.payload,\n    };\n    replayBuffer.push(subject, bufferedFrame);\n    const subjectSubscribers = subjectIndex.get(subject);\n    if (subjectSubscribers === undefined || subjectSubscribers.size === 0) return;\n    for (const subscriptionId of subjectSubscribers) {\n      const record = subscriptions.get(subscriptionId);\n      if (record === undefined) continue;\n      dispatchSanitized(record, { ...bufferedFrame, subscriptionId });\n    }\n    void isEventFrame; // keep import warm\n  }\n\n  function emitLifecycle(\n    subscriptionId: string,\n    status: ServerLifecycleFrame['status'],\n    reason?: string,\n  ): void {\n    const record = subscriptions.get(subscriptionId);\n    if (record === undefined) return;\n    const frame: ServerLifecycleFrame = {\n      v: '1',\n      kind: 'lifecycle',\n      subscriptionId,\n      status,\n      ...(reason !== undefined ? { reason } : {}),\n    };\n    validateAndDispatch(record, frame);\n  }\n\n  function listForSubscriber(subscriberId: string): ReadonlyArray<WsSubscriptionSnapshot> {\n    const subscriber = subscribers.get(subscriberId);\n    if (subscriber === undefined) return Object.freeze([]);\n    return Object.freeze(\n      [...subscriber.subscriptions]\n        .map((id) => subscriptions.get(id))\n        .filter((entry): entry is SubscriptionRecord => entry !== undefined)\n        .map(snapshotForRecord),\n    );\n  }\n\n  function snapshotSubscription(subscriptionId: string): WsSubscriptionSnapshot | undefined {\n    const record = subscriptions.get(subscriptionId);\n    if (record === undefined) return undefined;\n    return snapshotForRecord(record);\n  }\n\n  function size(): { readonly subscribers: number; readonly subscriptions: number } {\n    return Object.freeze({\n      subscribers: subscribers.size,\n      subscriptions: subscriptions.size,\n    });\n  }\n\n  function shutdown(): void {\n    for (const subscription of subscriptions.values()) {\n      const subscriber = subscribers.get(subscription.subscriberId);\n      try {\n        subscriber?.handle.send({\n          v: '1',\n          kind: 'lifecycle',\n          subscriptionId: subscription.subscriptionId,\n          status: 'aborted',\n          reason: 'server-shutdown',\n        });\n      } catch {\n        // swallow - we are tearing down.\n      }\n    }\n    subscriptions.clear();\n    subjectIndex.clear();\n    subscribers.clear();\n  }\n\n  return Object.freeze({\n    sanitizer,\n    replayBuffer,\n    registerSubscriber,\n    subscribe,\n    unsubscribe,\n    emit,\n    emitLifecycle,\n    listForSubscriber,\n    snapshotSubscription,\n    size,\n    shutdown,\n  });\n}\n\nfunction snapshotForRecord(record: SubscriptionRecord): WsSubscriptionSnapshot {\n  return Object.freeze({\n    subscriptionId: record.subscriptionId,\n    subject: record.subject,\n    subjectKind: record.parsed.kind,\n    subscriberId: record.subscriberId,\n    tokenId: record.tokenId,\n    createdAt: record.createdAt,\n    lastEventId: record.lastEventId,\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAoNA,SAAgB,mBAAmB,UAA+B,EAAE,EAAgB;CAClF,MAAM,YAAY,kCAAkC,QAAQ,WAAW;CACvE,MAAM,eAAe,mBAAmB,QAAQ,gBAAgB,EAAE,CAAC;CACnE,MAAM,MAAM,QAAQ,OAAO,KAAK;CAChC,MAAM,SAAS,QAAQ;CACvB,MAAM,0BAA0B,QAAQ,2BAA2B;CACnE,MAAM,8BAAc,IAAI,KAA+B;CACvD,MAAM,gCAAgB,IAAI,KAAiC;CAC3D,MAAM,+BAAe,IAAI,KAA0B;CACnD,IAAI,eAAe;CAEnB,SAAS,aAAa,SAAiB,gBAA8B;EACnE,IAAI,MAAM,aAAa,IAAI,QAAQ;AACnC,MAAI,QAAQ,QAAW;AACrB,yBAAM,IAAI,KAAK;AACf,gBAAa,IAAI,SAAS,IAAI;;AAEhC,MAAI,IAAI,eAAe;;CAGzB,SAAS,eAAe,SAAiB,gBAA8B;EACrE,MAAM,MAAM,aAAa,IAAI,QAAQ;AACrC,MAAI,QAAQ,OAAW;AACvB,MAAI,OAAO,eAAe;AAC1B,MAAI,IAAI,SAAS,EAAG,cAAa,OAAO,QAAQ;;CAGlD,SAAS,cAAsB;AAC7B,kBAAgB;AAChB,SAAO,OAAO,KAAK,CAAC,SAAS,GAAG,CAAC,GAAG,aAAa,SAAS,GAAG;;CAG/D,SAAS,qBAAqB,QAA4B,OAA4B;EACpF,MAAM,aAAa,YAAY,IAAI,OAAO,aAAa;AACvD,MAAI,eAAe,UAAa,WAAW,OAAQ;EAOnD,MAAM,WACJ,OAAO,WAAW,OAAO,mBAAmB,aACxC,WAAW,OAAO,gBAAgB,GAClC;AACN,MACE,WAAW,qBAAqB,2BAChC,YAAY,0BAA0B,MACtC;AACA,YAAS;IAAE,MAAM;IAAkB,gBAAgB,OAAO;IAAgB,CAAC;AAC3E,sBAAmB,YAAY,MAAM,iBAAiB;AACtD;;AAEF,aAAW,qBAAqB;AAChC,MAAI;AACF,cAAW,OAAO,KAAK,MAAM;WACtB,KAAK;AACZ,YAAS;IAAE,MAAM;IAAkB,gBAAgB,OAAO;IAAgB,CAAC;AAC3E,sBAAmB,YAAY,MAAM,iBAAiB;YAE9C;AACR,cAAW,oBAAoB,KAAK,IAAI,GAAG,WAAW,oBAAoB,EAAE;;;CAIhF,SAAS,mBAAmB,YAA8B,MAAc,QAAsB;AAC5F,MAAI,WAAW,OAAQ;AACvB,aAAW,SAAS;AACpB,MAAI;AACF,cAAW,OAAO,MAAM,MAAM,OAAO;UAC/B;AAGR,OAAK,MAAM,MAAM,WAAW,eAAe;GACzC,MAAM,MAAM,cAAc,IAAI,GAAG;AACjC,OAAI,QAAQ,QAAW;AACrB,mBAAe,IAAI,SAAS,GAAG;AAC/B,kBAAc,OAAO,GAAG;;;AAG5B,aAAW,cAAc,OAAO;AAChC,cAAY,OAAO,WAAW,OAAO,GAAG;;CAG1C,SAAS,oBAAoB,QAA4B,OAA4B;EACnF,MAAM,YAAY,oBAAoB,UAAU,MAAM;AACtD,MAAI,CAAC,UAAU,SAAS;AACtB,YAAS;IACP,MAAM;IACN,gBAAgB,OAAO;IACvB,QAAQ,UAAU,MAAM,OAAO,KAAK,MAAM,GAAG,EAAE,KAAK,KAAK,IAAI,IAAI,SAAS,IAAI,EAAE,UAAU;IAC3F,CAAC;AACF;;AAEF,uBAAqB,QAAQ,UAAU,KAAK;;CAG9C,SAAS,mBAAmB,QAAoD;AAC9E,cAAY,IAAI,OAAO,IAAI;GACzB;GACA,+BAAe,IAAI,KAAK;GACxB,mBAAmB;GACnB,QAAQ;GACT,CAAC;AACF,SAAO,EACL,kBAAkB;GAChB,MAAM,SAAS,YAAY,IAAI,OAAO,GAAG;AACzC,OAAI,WAAW,OAAW;AAC1B,QAAK,MAAM,MAAM,OAAO,eAAe;IACrC,MAAM,MAAM,cAAc,IAAI,GAAG;AACjC,QAAI,QAAQ,QAAW;AACrB,oBAAe,IAAI,SAAS,GAAG;AAC/B,mBAAc,OAAO,GAAG;;;AAG5B,eAAY,OAAO,OAAO,GAAG;KAEhC;;CAGH,SAAS,UAAU,OAKC;EAClB,MAAM,aAAa,YAAY,IAAI,MAAM,aAAa;AACtD,MAAI,eAAe,OACjB,QAAO;GAAE,IAAI;GAAO,QAAQ;GAAmB;EAEjD,MAAM,cAAc,gBAAgB,MAAM,QAAQ;AAClD,MAAI,CAAC,YAAY,IAAI;GACnB,MAAM,SAAS,YAAY;AAC3B,YAAS;IAAE,MAAM;IAAoB,SAAS,MAAM;IAAS;IAAQ,CAAC;AACtE,OAAI,WAAW,yBAA0B,QAAO;IAAE,IAAI;IAAO,QAAQ;IAAoB;AACzF,OAAI,WAAW,kBAAmB,QAAO;IAAE,IAAI;IAAO,QAAQ;IAAmB;AACjF,UAAO;IAAE,IAAI;IAAO,QAAQ;IAAqB;;AAEnD,MAAI,CAAC,iBAAiB,WAAW,OAAO,eAAe,YAAY,QAAQ,CACzE,QAAO;GAAE,IAAI;GAAO,QAAQ;GAAgB;EAE9C,MAAMA,SAA6B;GACjC,cAAc,MAAM;GACpB,SAAS,WAAW,OAAO;GAC3B,gBAAgB,MAAM;GACtB,SAAS,MAAM;GACf,QAAQ,YAAY;GACpB,WAAW,KAAK;GAChB,aAAa;GACd;AACD,gBAAc,IAAI,MAAM,gBAAgB,OAAO;AAC/C,aAAW,cAAc,IAAI,MAAM,eAAe;AAClD,eAAa,MAAM,SAAS,MAAM,eAAe;EACjD,MAAM,SAAS,aAAa,OAAO,MAAM,SAAS,MAAM,aAAa;EACrE,IAAI,WAAW;EACf,IAAIC,kBAAsC,OAAO;AACjD,OAAK,MAAM,SAAS,OAAO,QAAQ;AAMjC,qBAAkB,QAAQ;IAAE,GAAG;IAAO,gBAAgB,MAAM;IAAgB,CAAC;AAC7E,eAAY;;AAEd,MAAI,OAAO,eAAe,GAAG;AAG3B,uBAAoB,QAAQ;IAC1B,GAAG;IACH,MAAM;IACN,gBAAgB,MAAM;IACtB,SAAS,mBAAmB,cAAc,KAAK,CAAC,SAAS,GAAG;IAC5D,cAAc,OAAO;IACrB,MAAM,yBAAyB,OAAO,aAAa;IACpD,CAAC;AACF,qBAAkB,mBAAmB,cAAc,KAAK,CAAC,SAAS,GAAG;;AAEvE,SAAO;GACL,IAAI;GACJ,cAAc,kBAAkB,OAAO;GACvC,eAAe;GACf;GACD;;CAGH,SAAS,YAAY,gBAAiC;EACpD,MAAM,SAAS,cAAc,IAAI,eAAe;AAChD,MAAI,WAAW,OAAW,QAAO;AAEjC,EADmB,YAAY,IAAI,OAAO,aAAa,EAC3C,cAAc,OAAO,eAAe;AAChD,iBAAe,OAAO,SAAS,eAAe;AAC9C,gBAAc,OAAO,eAAe;AACpC,SAAO;;;;;;;;;;;CAYT,SAAS,kBAAkB,QAA4B,OAA+B;EACpF,MAAM,YAAY,UAAU,SAAS,OAAO,KAAK;AACjD,sBAAoB,QAAQ,UAAU;AACtC,SAAO,cAAc,UAAU;;CAGjC,SAAS,KAAK,SAAiB,MAA4B;EAOzD,MAAMC,gBAAkC;GACtC,GAAG;GACH,MAAM;GACN,SATc,KAAK,WAAW,aAAa;GAU3C,gBAAgB;GAChB;GACA,MAAM,KAAK;GACX,SAAS,KAAK;GACf;AACD,eAAa,KAAK,SAAS,cAAc;EACzC,MAAM,qBAAqB,aAAa,IAAI,QAAQ;AACpD,MAAI,uBAAuB,UAAa,mBAAmB,SAAS,EAAG;AACvE,OAAK,MAAM,kBAAkB,oBAAoB;GAC/C,MAAM,SAAS,cAAc,IAAI,eAAe;AAChD,OAAI,WAAW,OAAW;AAC1B,qBAAkB,QAAQ;IAAE,GAAG;IAAe;IAAgB,CAAC;;;CAKnE,SAAS,cACP,gBACA,QACA,QACM;EACN,MAAM,SAAS,cAAc,IAAI,eAAe;AAChD,MAAI,WAAW,OAAW;AAQ1B,sBAAoB,QAPgB;GAClC,GAAG;GACH,MAAM;GACN;GACA;GACA,GAAI,WAAW,SAAY,EAAE,QAAQ,GAAG,EAAE;GAC3C,CACiC;;CAGpC,SAAS,kBAAkB,cAA6D;EACtF,MAAM,aAAa,YAAY,IAAI,aAAa;AAChD,MAAI,eAAe,OAAW,QAAO,OAAO,OAAO,EAAE,CAAC;AACtD,SAAO,OAAO,OACZ,CAAC,GAAG,WAAW,cAAc,CAC1B,KAAK,OAAO,cAAc,IAAI,GAAG,CAAC,CAClC,QAAQ,UAAuC,UAAU,OAAU,CACnE,IAAI,kBAAkB,CAC1B;;CAGH,SAAS,qBAAqB,gBAA4D;EACxF,MAAM,SAAS,cAAc,IAAI,eAAe;AAChD,MAAI,WAAW,OAAW,QAAO;AACjC,SAAO,kBAAkB,OAAO;;CAGlC,SAAS,OAAyE;AAChF,SAAO,OAAO,OAAO;GACnB,aAAa,YAAY;GACzB,eAAe,cAAc;GAC9B,CAAC;;CAGJ,SAAS,WAAiB;AACxB,OAAK,MAAM,gBAAgB,cAAc,QAAQ,EAAE;GACjD,MAAM,aAAa,YAAY,IAAI,aAAa,aAAa;AAC7D,OAAI;AACF,gBAAY,OAAO,KAAK;KACtB,GAAG;KACH,MAAM;KACN,gBAAgB,aAAa;KAC7B,QAAQ;KACR,QAAQ;KACT,CAAC;WACI;;AAIV,gBAAc,OAAO;AACrB,eAAa,OAAO;AACpB,cAAY,OAAO;;AAGrB,QAAO,OAAO,OAAO;EACnB;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACD,CAAC;;AAGJ,SAAS,kBAAkB,QAAoD;AAC7E,QAAO,OAAO,OAAO;EACnB,gBAAgB,OAAO;EACvB,SAAS,OAAO;EAChB,aAAa,OAAO,OAAO;EAC3B,cAAc,OAAO;EACrB,SAAS,OAAO;EAChB,WAAW,OAAO;EAClB,aAAa,OAAO;EACrB,CAAC"}

package/dist/ws/index.d.ts

@@ -1,6 +1,6 @@
-import { ReplayBuffer, ReplayBufferOptions, ReplayBufferSlice, createReplayBuffer } from "./replay-buffer.js";
+import { ReplayBuffer, ReplayBufferOptions, ReplayBufferSlice, ReplayBufferStats, createReplayBuffer, scheduleReplayBufferPruning } from "./replay-buffer.js";
 import { ParseSubjectResult, ParsedSubject, isSubjectAllowed, requiredScopeFor, tryParseSubject } from "./subjects.js";
 import { BareEventFrame, SubscribeResult, WsDispatcher, WsDispatcherOptions, WsDispatcherWarning, WsSubscriberHandle, WsSubscriptionSnapshot, createWsDispatcher } from "./dispatcher.js";
 import { WsTicket, WsTicketConsumeResult, WsTicketStore, WsTicketStoreOptions, createWsTicketStore } from "./ticket.js";
 import { WsUpgradeOptions, createWsUpgradeEvents } from "./upgrade.js";
-export { type BareEventFrame, type ParseSubjectResult, type ParsedSubject, type ReplayBuffer, type ReplayBufferOptions, type ReplayBufferSlice, type SubscribeResult, type WsDispatcher, type WsDispatcherOptions, type WsDispatcherWarning, type WsSubscriberHandle, type WsSubscriptionSnapshot, type WsTicket, type WsTicketConsumeResult, type WsTicketStore, type WsTicketStoreOptions, type WsUpgradeOptions, createReplayBuffer, createWsDispatcher, createWsTicketStore, createWsUpgradeEvents, isSubjectAllowed, requiredScopeFor, tryParseSubject };
+export { type BareEventFrame, type ParseSubjectResult, type ParsedSubject, type ReplayBuffer, type ReplayBufferOptions, type ReplayBufferSlice, type ReplayBufferStats, type SubscribeResult, type WsDispatcher, type WsDispatcherOptions, type WsDispatcherWarning, type WsSubscriberHandle, type WsSubscriptionSnapshot, type WsTicket, type WsTicketConsumeResult, type WsTicketStore, type WsTicketStoreOptions, type WsUpgradeOptions, createReplayBuffer, createWsDispatcher, createWsTicketStore, createWsUpgradeEvents, isSubjectAllowed, requiredScopeFor, scheduleReplayBufferPruning, tryParseSubject };

package/dist/ws/index.js

@@ -1,7 +1,7 @@
-import { createReplayBuffer } from "./replay-buffer.js";
+import { createWsUpgradeEvents } from "./upgrade.js";
+import { createReplayBuffer, scheduleReplayBufferPruning } from "./replay-buffer.js";
 import { isSubjectAllowed, requiredScopeFor, tryParseSubject } from "./subjects.js";
 import { createWsDispatcher } from "./dispatcher.js";
 import { createWsTicketStore } from "./ticket.js";
-import { createWsUpgradeEvents } from "./upgrade.js";
 
-export { createReplayBuffer, createWsDispatcher, createWsTicketStore, createWsUpgradeEvents, isSubjectAllowed, requiredScopeFor, tryParseSubject };
+export { createReplayBuffer, createWsDispatcher, createWsTicketStore, createWsUpgradeEvents, isSubjectAllowed, requiredScopeFor, scheduleReplayBufferPruning, tryParseSubject };

package/dist/ws/replay-buffer.d.ts

@@ -22,6 +22,17 @@ interface ReplayBufferSlice {
   readonly droppedCount: number;
   readonly nextEventIdHint: string | undefined;
 }
+/**
+ * Occupancy snapshot returned by {@link ReplayBuffer.stats}.
+ *
+ * @stable
+ */
+interface ReplayBufferStats {
+  /** Number of subjects currently holding at least one buffered event. */
+  readonly subjects: number;
+  /** Total buffered events across all subjects. */
+  readonly events: number;
+}
 /**
  * Per-subject replay buffer. Stores up to `maxEvents` per subject
  * with a TTL; thread-safe under the single-writer Node event loop
@@ -35,6 +46,13 @@ interface ReplayBuffer {
   size(subject: string): number;
   forget(subject: string): void;
   prune(): void;
+  /**
+   * Occupancy snapshot (W-028). OPTIONAL so external implementations
+   * of this `@stable` interface keep compiling; `createReplayBuffer`
+   * always provides it. When absent, the `/v1/metrics` replay-buffer
+   * gauge degrades to `0`.
+   */
+  stats?(): ReplayBufferStats;
 }
 /**
  * Build an in-memory replay buffer.
@@ -42,6 +60,22 @@ interface ReplayBuffer {
  * @stable
  */
 declare function createReplayBuffer(options?: ReplayBufferOptions): ReplayBuffer;
+/**
+ * W-028: schedule a periodic {@link ReplayBuffer.prune} sweep. Without
+ * it TTL expiry only ran lazily inside `push`/`replay`/`size` FOR THE
+ * SAME SUBJECT, so every finished run-subject (a fresh runId per run)
+ * retained up to `maxEvents` full payloads forever on a long-living
+ * server. Mirrors `scheduleRunPruning` (IP-16): `unref`-ed timer,
+ * returns a stop function. The sweep applies only the already
+ * documented TTL - replay semantics inside the TTL window are
+ * unchanged (an immediate `forget` on run completion would break
+ * short-disconnect resume of terminal events).
+ *
+ * @stable
+ */
+declare function scheduleReplayBufferPruning(buffer: ReplayBuffer, opts?: {
+  readonly intervalMs?: number;
+}): () => void;
 //#endregion
-export { ReplayBuffer, ReplayBufferOptions, ReplayBufferSlice, createReplayBuffer };
+export { ReplayBuffer, ReplayBufferOptions, ReplayBufferSlice, ReplayBufferStats, createReplayBuffer, scheduleReplayBufferPruning };
 //# sourceMappingURL=replay-buffer.d.ts.map

package/dist/ws/replay-buffer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"replay-buffer.d.ts","names":[],"sources":["../../src/ws/replay-buffer.ts"],"sourcesContent":[],"mappings":";;;;;;;;;UAoBiB,mBAAA;;;;;;;;;;UAWA,iBAAA;mBACE,cAAc;;;;;;;;;;;UAYhB,YAAA;+BACc;6DAC8B;;;;;;;;;;iBAgB7C,kBAAA,WAA4B,sBAA2B"}
+{"version":3,"file":"replay-buffer.d.ts","names":[],"sources":["../../src/ws/replay-buffer.ts"],"sourcesContent":[],"mappings":";;;;;;;;;UAoBiB,mBAAA;;;;;;;;;;UAWA,iBAAA;mBACE,cAAc;;;;;;;;;UAUhB,iBAAA;;;;;;;;;;;;;UAcA,YAAA;+BACc;6DAC8B;;;;;;;;;;YAUjD;;;;;;;iBAaI,kBAAA,WAA4B,sBAA2B;;;;;;;;;;;;;;iBAmHvD,2BAAA,SACN"}

package/dist/ws/replay-buffer.js

@@ -24,7 +24,10 @@ function createReplayBuffer(options = {}) {
 			list.splice(0, cutoffIndex);
 			dropped.set(subject, (dropped.get(subject) ?? 0) + cutoffIndex);
 		}
-		if (list.length === 0) buffers.delete(subject);
+		if (list.length === 0) {
+			buffers.delete(subject);
+			dropped.delete(subject);
+		}
 	}
 	function push(subject, event) {
 		pruneSubject(subject);
@@ -56,7 +59,7 @@ function createReplayBuffer(options = {}) {
 		const startIndex = list.findIndex((entry) => entry.event.eventId === sinceEventId);
 		if (startIndex < 0) return {
 			events: list.map((entry) => entry.event),
-			droppedCount,
+			droppedCount: Math.max(droppedCount, 1),
 			nextEventIdHint: last?.event.eventId
 		};
 		const replayed = list.slice(startIndex + 1).map((entry) => entry.event);
@@ -79,10 +82,39 @@ function createReplayBuffer(options = {}) {
 		},
 		prune() {
 			for (const subject of [...buffers.keys()]) pruneSubject(subject);
+		},
+		stats() {
+			let events = 0;
+			for (const list of buffers.values()) events += list.length;
+			return {
+				subjects: buffers.size,
+				events
+			};
 		}
 	});
 }
+/**
+* W-028: schedule a periodic {@link ReplayBuffer.prune} sweep. Without
+* it TTL expiry only ran lazily inside `push`/`replay`/`size` FOR THE
+* SAME SUBJECT, so every finished run-subject (a fresh runId per run)
+* retained up to `maxEvents` full payloads forever on a long-living
+* server. Mirrors `scheduleRunPruning` (IP-16): `unref`-ed timer,
+* returns a stop function. The sweep applies only the already
+* documented TTL - replay semantics inside the TTL window are
+* unchanged (an immediate `forget` on run completion would break
+* short-disconnect resume of terminal events).
+*
+* @stable
+*/
+function scheduleReplayBufferPruning(buffer, opts = {}) {
+	const intervalMs = opts.intervalMs ?? 6e4;
+	const timer = setInterval(() => {
+		buffer.prune();
+	}, intervalMs);
+	if (typeof timer.unref === "function") timer.unref();
+	return () => clearInterval(timer);
+}
 
 //#endregion
-export { createReplayBuffer };
+export { createReplayBuffer, scheduleReplayBufferPruning };
 //# sourceMappingURL=replay-buffer.js.map

package/dist/ws/replay-buffer.js.map

@@ -1 +1 @@
-{"version":3,"file":"replay-buffer.js","names":[],"sources":["../../src/ws/replay-buffer.ts"],"sourcesContent":["/**\n * Per-subscription replay buffer used by the dispatcher to support\n * short-disconnect resume. When a client reconnects with a\n * `lastEventId`, the dispatcher walks the buffer from the matching\n * cursor and re-emits every event the client missed.\n *\n * Defaults (configurable per-server):\n *  - `maxEvents`: 1000 (per subscription)\n *  - `ttlMs`: 5 minutes\n *\n * @packageDocumentation\n */\n\nimport type { ServerEventFrame } from '@graphorin/protocol';\n\n/**\n * Public configuration accepted by {@link createReplayBuffer}.\n *\n * @stable\n */\nexport interface ReplayBufferOptions {\n  readonly maxEvents?: number;\n  readonly ttlMs?: number;\n  readonly now?: () => number;\n}\n\n/**\n * Snapshot returned by {@link ReplayBuffer.replay}.\n *\n * @stable\n */\nexport interface ReplayBufferSlice {\n  readonly events: ReadonlyArray<ServerEventFrame>;\n  readonly droppedCount: number;\n  readonly nextEventIdHint: string | undefined;\n}\n\n/**\n * Per-subject replay buffer. Stores up to `maxEvents` per subject\n * with a TTL; thread-safe under the single-writer Node event loop\n * model.\n *\n * @stable\n */\nexport interface ReplayBuffer {\n  push(subject: string, event: ServerEventFrame): void;\n  replay(subject: string, sinceEventId: string | undefined): ReplayBufferSlice;\n  size(subject: string): number;\n  forget(subject: string): void;\n  prune(): void;\n}\n\ninterface BufferedEvent {\n  readonly event: ServerEventFrame;\n  readonly bufferedAt: number;\n}\n\n/**\n * Build an in-memory replay buffer.\n *\n * @stable\n */\nexport function createReplayBuffer(options: ReplayBufferOptions = {}): ReplayBuffer {\n  const maxEvents = options.maxEvents ?? 1_000;\n  const ttlMs = options.ttlMs ?? 5 * 60_000;\n  const now = options.now ?? Date.now;\n  const buffers = new Map<string, BufferedEvent[]>();\n  const dropped = new Map<string, number>();\n\n  function pruneSubject(subject: string): void {\n    const list = buffers.get(subject);\n    if (list === undefined || list.length === 0) return;\n    const cutoff = now() - ttlMs;\n    let cutoffIndex = 0;\n    while (cutoffIndex < list.length) {\n      const entry = list[cutoffIndex];\n      if (entry === undefined || entry.bufferedAt >= cutoff) break;\n      cutoffIndex += 1;\n    }\n    if (cutoffIndex > 0) {\n      list.splice(0, cutoffIndex);\n      dropped.set(subject, (dropped.get(subject) ?? 0) + cutoffIndex);\n    }\n    if (list.length === 0) buffers.delete(subject);\n  }\n\n  function push(subject: string, event: ServerEventFrame): void {\n    pruneSubject(subject);\n    let list = buffers.get(subject);\n    if (list === undefined) {\n      list = [];\n      buffers.set(subject, list);\n    }\n    list.push({ event, bufferedAt: now() });\n    if (list.length > maxEvents) {\n      const overflow = list.length - maxEvents;\n      list.splice(0, overflow);\n      dropped.set(subject, (dropped.get(subject) ?? 0) + overflow);\n    }\n  }\n\n  function replay(subject: string, sinceEventId: string | undefined): ReplayBufferSlice {\n    pruneSubject(subject);\n    const list = buffers.get(subject) ?? [];\n    const droppedCount = dropped.get(subject) ?? 0;\n    const last = list.at(-1);\n    if (sinceEventId === undefined) {\n      const slice: ReplayBufferSlice = {\n        events: list.map((entry) => entry.event),\n        droppedCount,\n        nextEventIdHint: last?.event.eventId,\n      };\n      return slice;\n    }\n    const startIndex = list.findIndex((entry) => entry.event.eventId === sinceEventId);\n    if (startIndex < 0) {\n      // Cursor predates the buffer; return everything we still have +\n      // signal the gap via `droppedCount`.\n      return {\n        events: list.map((entry) => entry.event),\n        droppedCount,\n        nextEventIdHint: last?.event.eventId,\n      };\n    }\n    const replayed = list.slice(startIndex + 1).map((entry) => entry.event);\n    return {\n      events: replayed,\n      droppedCount: 0,\n      nextEventIdHint: replayed.at(-1)?.eventId,\n    };\n  }\n\n  return Object.freeze({\n    push,\n    replay,\n    size(subject: string): number {\n      pruneSubject(subject);\n      return buffers.get(subject)?.length ?? 0;\n    },\n    forget(subject: string): void {\n      buffers.delete(subject);\n      dropped.delete(subject);\n    },\n    prune(): void {\n      for (const subject of [...buffers.keys()]) pruneSubject(subject);\n    },\n  });\n}\n"],"mappings":";;;;;;AA8DA,SAAgB,mBAAmB,UAA+B,EAAE,EAAgB;CAClF,MAAM,YAAY,QAAQ,aAAa;CACvC,MAAM,QAAQ,QAAQ,SAAS,IAAI;CACnC,MAAM,MAAM,QAAQ,OAAO,KAAK;CAChC,MAAM,0BAAU,IAAI,KAA8B;CAClD,MAAM,0BAAU,IAAI,KAAqB;CAEzC,SAAS,aAAa,SAAuB;EAC3C,MAAM,OAAO,QAAQ,IAAI,QAAQ;AACjC,MAAI,SAAS,UAAa,KAAK,WAAW,EAAG;EAC7C,MAAM,SAAS,KAAK,GAAG;EACvB,IAAI,cAAc;AAClB,SAAO,cAAc,KAAK,QAAQ;GAChC,MAAM,QAAQ,KAAK;AACnB,OAAI,UAAU,UAAa,MAAM,cAAc,OAAQ;AACvD,kBAAe;;AAEjB,MAAI,cAAc,GAAG;AACnB,QAAK,OAAO,GAAG,YAAY;AAC3B,WAAQ,IAAI,UAAU,QAAQ,IAAI,QAAQ,IAAI,KAAK,YAAY;;AAEjE,MAAI,KAAK,WAAW,EAAG,SAAQ,OAAO,QAAQ;;CAGhD,SAAS,KAAK,SAAiB,OAA+B;AAC5D,eAAa,QAAQ;EACrB,IAAI,OAAO,QAAQ,IAAI,QAAQ;AAC/B,MAAI,SAAS,QAAW;AACtB,UAAO,EAAE;AACT,WAAQ,IAAI,SAAS,KAAK;;AAE5B,OAAK,KAAK;GAAE;GAAO,YAAY,KAAK;GAAE,CAAC;AACvC,MAAI,KAAK,SAAS,WAAW;GAC3B,MAAM,WAAW,KAAK,SAAS;AAC/B,QAAK,OAAO,GAAG,SAAS;AACxB,WAAQ,IAAI,UAAU,QAAQ,IAAI,QAAQ,IAAI,KAAK,SAAS;;;CAIhE,SAAS,OAAO,SAAiB,cAAqD;AACpF,eAAa,QAAQ;EACrB,MAAM,OAAO,QAAQ,IAAI,QAAQ,IAAI,EAAE;EACvC,MAAM,eAAe,QAAQ,IAAI,QAAQ,IAAI;EAC7C,MAAM,OAAO,KAAK,GAAG,GAAG;AACxB,MAAI,iBAAiB,OAMnB,QALiC;GAC/B,QAAQ,KAAK,KAAK,UAAU,MAAM,MAAM;GACxC;GACA,iBAAiB,MAAM,MAAM;GAC9B;EAGH,MAAM,aAAa,KAAK,WAAW,UAAU,MAAM,MAAM,YAAY,aAAa;AAClF,MAAI,aAAa,EAGf,QAAO;GACL,QAAQ,KAAK,KAAK,UAAU,MAAM,MAAM;GACxC;GACA,iBAAiB,MAAM,MAAM;GAC9B;EAEH,MAAM,WAAW,KAAK,MAAM,aAAa,EAAE,CAAC,KAAK,UAAU,MAAM,MAAM;AACvE,SAAO;GACL,QAAQ;GACR,cAAc;GACd,iBAAiB,SAAS,GAAG,GAAG,EAAE;GACnC;;AAGH,QAAO,OAAO,OAAO;EACnB;EACA;EACA,KAAK,SAAyB;AAC5B,gBAAa,QAAQ;AACrB,UAAO,QAAQ,IAAI,QAAQ,EAAE,UAAU;;EAEzC,OAAO,SAAuB;AAC5B,WAAQ,OAAO,QAAQ;AACvB,WAAQ,OAAO,QAAQ;;EAEzB,QAAc;AACZ,QAAK,MAAM,WAAW,CAAC,GAAG,QAAQ,MAAM,CAAC,CAAE,cAAa,QAAQ;;EAEnE,CAAC"}
+{"version":3,"file":"replay-buffer.js","names":[],"sources":["../../src/ws/replay-buffer.ts"],"sourcesContent":["/**\n * Per-subscription replay buffer used by the dispatcher to support\n * short-disconnect resume. When a client reconnects with a\n * `lastEventId`, the dispatcher walks the buffer from the matching\n * cursor and re-emits every event the client missed.\n *\n * Defaults (configurable per-server):\n *  - `maxEvents`: 1000 (per subscription)\n *  - `ttlMs`: 5 minutes\n *\n * @packageDocumentation\n */\n\nimport type { ServerEventFrame } from '@graphorin/protocol';\n\n/**\n * Public configuration accepted by {@link createReplayBuffer}.\n *\n * @stable\n */\nexport interface ReplayBufferOptions {\n  readonly maxEvents?: number;\n  readonly ttlMs?: number;\n  readonly now?: () => number;\n}\n\n/**\n * Snapshot returned by {@link ReplayBuffer.replay}.\n *\n * @stable\n */\nexport interface ReplayBufferSlice {\n  readonly events: ReadonlyArray<ServerEventFrame>;\n  readonly droppedCount: number;\n  readonly nextEventIdHint: string | undefined;\n}\n\n/**\n * Occupancy snapshot returned by {@link ReplayBuffer.stats}.\n *\n * @stable\n */\nexport interface ReplayBufferStats {\n  /** Number of subjects currently holding at least one buffered event. */\n  readonly subjects: number;\n  /** Total buffered events across all subjects. */\n  readonly events: number;\n}\n\n/**\n * Per-subject replay buffer. Stores up to `maxEvents` per subject\n * with a TTL; thread-safe under the single-writer Node event loop\n * model.\n *\n * @stable\n */\nexport interface ReplayBuffer {\n  push(subject: string, event: ServerEventFrame): void;\n  replay(subject: string, sinceEventId: string | undefined): ReplayBufferSlice;\n  size(subject: string): number;\n  forget(subject: string): void;\n  prune(): void;\n  /**\n   * Occupancy snapshot (W-028). OPTIONAL so external implementations\n   * of this `@stable` interface keep compiling; `createReplayBuffer`\n   * always provides it. When absent, the `/v1/metrics` replay-buffer\n   * gauge degrades to `0`.\n   */\n  stats?(): ReplayBufferStats;\n}\n\ninterface BufferedEvent {\n  readonly event: ServerEventFrame;\n  readonly bufferedAt: number;\n}\n\n/**\n * Build an in-memory replay buffer.\n *\n * @stable\n */\nexport function createReplayBuffer(options: ReplayBufferOptions = {}): ReplayBuffer {\n  const maxEvents = options.maxEvents ?? 1_000;\n  const ttlMs = options.ttlMs ?? 5 * 60_000;\n  const now = options.now ?? Date.now;\n  const buffers = new Map<string, BufferedEvent[]>();\n  const dropped = new Map<string, number>();\n\n  function pruneSubject(subject: string): void {\n    const list = buffers.get(subject);\n    if (list === undefined || list.length === 0) return;\n    const cutoff = now() - ttlMs;\n    let cutoffIndex = 0;\n    while (cutoffIndex < list.length) {\n      const entry = list[cutoffIndex];\n      if (entry === undefined || entry.bufferedAt >= cutoff) break;\n      cutoffIndex += 1;\n    }\n    if (cutoffIndex > 0) {\n      list.splice(0, cutoffIndex);\n      dropped.set(subject, (dropped.get(subject) ?? 0) + cutoffIndex);\n    }\n    if (list.length === 0) {\n      // W-028: release the whole subject, including its dropped-count\n      // entry - otherwise every finished run leaves a Map entry behind\n      // forever. A resume with a stale cursor still signals the gap:\n      // `replay()` floors droppedCount at 1 when the cursor misses.\n      buffers.delete(subject);\n      dropped.delete(subject);\n    }\n  }\n\n  function push(subject: string, event: ServerEventFrame): void {\n    pruneSubject(subject);\n    let list = buffers.get(subject);\n    if (list === undefined) {\n      list = [];\n      buffers.set(subject, list);\n    }\n    list.push({ event, bufferedAt: now() });\n    if (list.length > maxEvents) {\n      const overflow = list.length - maxEvents;\n      list.splice(0, overflow);\n      dropped.set(subject, (dropped.get(subject) ?? 0) + overflow);\n    }\n  }\n\n  function replay(subject: string, sinceEventId: string | undefined): ReplayBufferSlice {\n    pruneSubject(subject);\n    const list = buffers.get(subject) ?? [];\n    const droppedCount = dropped.get(subject) ?? 0;\n    const last = list.at(-1);\n    if (sinceEventId === undefined) {\n      const slice: ReplayBufferSlice = {\n        events: list.map((entry) => entry.event),\n        droppedCount,\n        nextEventIdHint: last?.event.eventId,\n      };\n      return slice;\n    }\n    const startIndex = list.findIndex((entry) => entry.event.eventId === sinceEventId);\n    if (startIndex < 0) {\n      // Cursor predates the buffer; return everything we still have +\n      // signal the gap via `droppedCount`. The miss itself PROVES at\n      // least one event was dropped, so floor the count at 1 even\n      // after the dropped-map entry was released by pruning (W-028) -\n      // the dispatcher must still send the replay-marker.\n      return {\n        events: list.map((entry) => entry.event),\n        droppedCount: Math.max(droppedCount, 1),\n        nextEventIdHint: last?.event.eventId,\n      };\n    }\n    const replayed = list.slice(startIndex + 1).map((entry) => entry.event);\n    return {\n      events: replayed,\n      droppedCount: 0,\n      nextEventIdHint: replayed.at(-1)?.eventId,\n    };\n  }\n\n  return Object.freeze({\n    push,\n    replay,\n    size(subject: string): number {\n      pruneSubject(subject);\n      return buffers.get(subject)?.length ?? 0;\n    },\n    forget(subject: string): void {\n      buffers.delete(subject);\n      dropped.delete(subject);\n    },\n    prune(): void {\n      for (const subject of [...buffers.keys()]) pruneSubject(subject);\n    },\n    stats(): ReplayBufferStats {\n      let events = 0;\n      for (const list of buffers.values()) events += list.length;\n      return { subjects: buffers.size, events };\n    },\n  });\n}\n\n/**\n * W-028: schedule a periodic {@link ReplayBuffer.prune} sweep. Without\n * it TTL expiry only ran lazily inside `push`/`replay`/`size` FOR THE\n * SAME SUBJECT, so every finished run-subject (a fresh runId per run)\n * retained up to `maxEvents` full payloads forever on a long-living\n * server. Mirrors `scheduleRunPruning` (IP-16): `unref`-ed timer,\n * returns a stop function. The sweep applies only the already\n * documented TTL - replay semantics inside the TTL window are\n * unchanged (an immediate `forget` on run completion would break\n * short-disconnect resume of terminal events).\n *\n * @stable\n */\nexport function scheduleReplayBufferPruning(\n  buffer: ReplayBuffer,\n  opts: { readonly intervalMs?: number } = {},\n): () => void {\n  const intervalMs = opts.intervalMs ?? 60_000;\n  const timer = setInterval(() => {\n    buffer.prune();\n  }, intervalMs);\n  if (typeof (timer as { unref?: () => void }).unref === 'function') {\n    (timer as { unref: () => void }).unref();\n  }\n  return () => clearInterval(timer);\n}\n"],"mappings":"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"}

package/dist/ws/upgrade.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upgrade.d.ts","names":[],"sources":["../../src/ws/upgrade.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;UA0DiB,gBAAA;uBACM;oBACH;;;;;;sBAME;;;;;;;;kBAQJ;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2BI,qBAAA,IACjB;aAAqB;aACf,mBACR,QAAQ"}
+{"version":3,"file":"upgrade.d.ts","names":[],"sources":["../../src/ws/upgrade.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;AA4DA;;;AAQsB,UARL,gBAAA,CAQK;EAQJ,SAAA,UAAA,EAfK,YAeL;EAAe,SAAA,OAAA,EAdb,aAca;EA2BX;;;;;EAGnB,SAAA,QAAA,CAAA,EAtCmB,aAsCnB;EAAO;;;;;;;kBA9BQ;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2BI,qBAAA,IACjB;aAAqB;aACf,mBACR,QAAQ"}

package/dist/ws/upgrade.js

@@ -1,5 +1,8 @@
+import { version } from "../package.js";
+import { checkScope } from "../middleware/scope.js";
+import { requiredRunScope } from "../runtime/run-state.js";
+import { parseScope } from "@graphorin/security/auth";
 import { ClientMessageSchema, RPC_ERROR_CODES, SUBPROTOCOL_NAME, closeCodeFor, isCancelledNotification, isInitializeRequest, isPingRequest, isRunCancelRequest, isSubscribeRequest, isUnsubscribeRequest, negotiateSubprotocol, parseTicketSubprotocol } from "@graphorin/protocol";
-import { parseScope, scopeMatches } from "@graphorin/security/auth";
 
 //#region src/ws/upgrade.ts
 /**
@@ -88,7 +91,13 @@ async function createWsUpgradeEvents(c, options) {
 			}
 			const message = parsed.data;
 			if (isCancelledNotification(message)) {
-				if (initialized && grantsInvokeScope(auth.grantedScopes)) options.runs?.abort(message.params.requestId, "mcp-cancel");
+				if (initialized) {
+					const snapshot = options.runs?.snapshot(message.params.requestId);
+					if (snapshot !== void 0 && checkScope({
+						kind: "token",
+						grantedScopes: auth.grantedScopes
+					}, requiredRunScope(snapshot, "control"))) options.runs?.abort(message.params.requestId, "mcp-cancel");
+				}
 				return;
 			}
 			if (!initialized && !isInitializeRequest(message) && !isPingRequest(message)) {
@@ -100,7 +109,7 @@ async function createWsUpgradeEvents(c, options) {
 				sendRpcSuccess(ws, message.id, {
 					serverInfo: {
 						name: "graphorin-server",
-						version: "0.6.0"
+						version
 					},
 					capabilities: {
 						subscriptions: true,
@@ -164,11 +173,20 @@ async function createWsUpgradeEvents(c, options) {
 				return;
 			}
 			if (isRunCancelRequest(message)) {
-				if (!grantsInvokeScope(auth.grantedScopes)) {
-					sendRpcError(ws, message.id, RPC_ERROR_CODES.SCOPE_DENIED, "Token lacks required scope 'agents:invoke'.");
+				const runId = message.params.runId;
+				const snapshot = options.runs?.snapshot(runId);
+				if (snapshot === void 0) {
+					sendRpcError(ws, message.id, RPC_ERROR_CODES.RUN_NOT_FOUND, `Run '${runId}' is not active.`);
+					return;
+				}
+				const required = requiredRunScope(snapshot, "control");
+				if (!checkScope({
+					kind: "token",
+					grantedScopes: auth.grantedScopes
+				}, required)) {
+					sendRpcError(ws, message.id, RPC_ERROR_CODES.SCOPE_DENIED, `Token lacks required scope '${required}'.`);
 					return;
 				}
-				const runId = message.params.runId;
 				if (!(options.runs?.abort(runId, message.params.reason ?? "rpc-cancel") === true)) {
 					sendRpcError(ws, message.id, RPC_ERROR_CODES.RUN_NOT_FOUND, `Run '${runId}' is not active.`);
 					return;
@@ -269,21 +287,10 @@ async function resolveUpgradeAuth(c, options) {
 	};
 }
 /**
-* IP-8: the `agents:invoke` scope required to cancel a run over the WS
-* transport - the same requirement the REST `POST /runs/:runId/abort` route
-* enforces. `scopeMatches` honours wildcards (`agents:*`, `admin:*`).
-*/
-const INVOKE_SCOPE = parseScope("agents:invoke");
-/**
-* IP-13: full scope grant handed to a no-auth (`auth.kind='none'`) upgrade.
-* `admin:*` matches every required scope, including the {@link INVOKE_SCOPE}
-* gate on run cancellation.
+* IP-13: the anonymous trusted-loopback principal (auth disabled) holds
+* `admin:*` so every per-subject and per-run check passes uniformly.
 */
 const ANONYMOUS_WS_SCOPES = [parseScope("admin:*")];
-function grantsInvokeScope(granted) {
-	for (const scope of granted) if (scopeMatches(scope, INVOKE_SCOPE)) return true;
-	return false;
-}
 function acceptTicket(ticket) {
 	return {
 		kind: "ok",