@graphorin/server 0.5.0

package/dist/triggers/daemon.js

@@ -0,0 +1,114 @@
+//#region src/triggers/daemon.ts
+/**
+* @stable
+*/
+function createTriggersDaemon(options) {
+	const fires = /* @__PURE__ */ new Map();
+	let catchupApplied = 0;
+	let libModeWarnings = 0;
+	let lastFireAtMs;
+	let running = false;
+	let pump;
+	const warn = options.warn ?? ((m) => process.stderr.write(`${m}\n`));
+	function recordFire(id, kind) {
+		const entry = fires.get(id) ?? {
+			success: 0,
+			error: 0
+		};
+		entry[kind] += 1;
+		fires.set(id, entry);
+		lastFireAtMs = Date.now();
+	}
+	async function pumpEvents() {
+		try {
+			for await (const event of options.scheduler.events()) observe(event);
+		} catch (err) {
+			warn(`[graphorin/server] triggers daemon event pump aborted: ${describeError(err)}`);
+		}
+	}
+	function observe(event) {
+		switch (event.type) {
+			case "fire-end":
+				recordFire(event.id, "success");
+				return;
+			case "fire-error":
+				recordFire(event.id, "error");
+				warn(`[graphorin/server] triggers daemon: trigger '${event.id}' failed after ${event.durationMs}ms: ${describeError(event.error)}`);
+				return;
+			case "catchup-applied":
+				catchupApplied += event.missed;
+				return;
+			case "lib-mode-warning":
+				libModeWarnings += 1;
+				return;
+			default: return;
+		}
+	}
+	return {
+		get scheduler() {
+			return options.scheduler;
+		},
+		async start() {
+			if (running) return;
+			running = true;
+			pump = pumpEvents();
+			await options.scheduler.start();
+		},
+		async stop() {
+			if (!running) return;
+			running = false;
+			await options.scheduler.stop();
+			if (pump !== void 0) {
+				try {
+					await pump;
+				} catch {}
+				pump = void 0;
+			}
+		},
+		async status() {
+			const all = await options.scheduler.list();
+			let active = 0;
+			let disabled = 0;
+			let deferred = 0;
+			for (const t of all) {
+				if (t.disabled) disabled += 1;
+				else active += 1;
+				if (t.missedFires > 0) deferred += 1;
+			}
+			const out = {
+				running,
+				active,
+				disabled,
+				deferred
+			};
+			if (lastFireAtMs !== void 0) out.lastFireAt = new Date(lastFireAtMs).toISOString();
+			return Object.freeze(out);
+		},
+		metrics() {
+			return Object.freeze({
+				fires: new Map(fires),
+				catchupApplied,
+				libModeWarnings
+			});
+		}
+	};
+}
+/**
+* Resolve the catch-up policy default for triggers that did not
+* declare one explicitly. Returns `'none'` per DEC-150 (personal-
+* assistant friendly).
+*
+* @stable
+*/
+function defaultCatchupPolicy() {
+	return "none";
+}
+function describeError(err) {
+	if (err === null || err === void 0) return "unknown";
+	if (err instanceof Error) return err.message;
+	return String(err);
+}
+
+//#endregion
+export { createTriggersDaemon, defaultCatchupPolicy };
+//# sourceMappingURL=daemon.js.map

package/dist/triggers/daemon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon.js","names":["lastFireAtMs: number | undefined","pump: Promise<void> | undefined","out: {\n        -readonly [K in keyof TriggersDaemonStatus]?: TriggersDaemonStatus[K];\n      }"],"sources":["../../src/triggers/daemon.ts"],"sourcesContent":["/**\n * Trigger scheduler integration with the server lifecycle.\n *\n * The daemon wraps a `Scheduler` from `@graphorin/triggers` and binds\n * its `start()` / `stop()` calls to the `beforeStart` / `beforeShutdown`\n * lifecycle hooks. On `start()`, every persisted trigger is loaded\n * from `trigger_state` (durable) and the per-trigger `catchupPolicy`\n * is honoured so cron / interval / idle / event triggers survive\n * process restarts as documented in the runtime spec.\n *\n * The daemon never invokes user callbacks itself — those run inside\n * the `Scheduler`. The daemon only owns lifecycle + observability.\n *\n * @packageDocumentation\n */\n\nimport type { CatchupPolicy, Scheduler, SchedulerEvent } from '@graphorin/triggers';\n\n/**\n * Snapshot exposed via {@link TriggersDaemon.status} + the\n * `/v1/health` aggregator. Counts split by `disabled` so the health\n * endpoint can flag a deployment that disabled every cron trigger.\n *\n * @stable\n */\nexport interface TriggersDaemonStatus {\n  readonly running: boolean;\n  readonly active: number;\n  readonly disabled: number;\n  readonly deferred: number;\n  /** Last fire timestamp across the entire pool (ISO-8601). */\n  readonly lastFireAt?: string;\n}\n\n/**\n * Aggregate counters surfaced through the Prometheus\n * `/v1/metrics` exposition. Updated incrementally as the scheduler\n * publishes lifecycle events.\n *\n * @stable\n */\nexport interface TriggersDaemonMetrics {\n  readonly fires: ReadonlyMap<string, { readonly success: number; readonly error: number }>;\n  readonly catchupApplied: number;\n  readonly libModeWarnings: number;\n}\n\n/**\n * @stable\n */\nexport interface CreateTriggersDaemonOptions {\n  readonly scheduler: Scheduler;\n  /**\n   * Optional logger. Defaults to the standard error stream so the\n   * daemon never depends on the framework logger directly.\n   */\n  readonly warn?: (message: string) => void;\n}\n\n/**\n * Stateful handle returned by {@link createTriggersDaemon}. The\n * `start()` / `stop()` methods are wired into\n * `LifecycleHooks.beforeStart` / `beforeShutdown` by `createServer`.\n *\n * @stable\n */\nexport interface TriggersDaemon {\n  start(): Promise<void>;\n  stop(): Promise<void>;\n  status(): Promise<TriggersDaemonStatus>;\n  metrics(): TriggersDaemonMetrics;\n  readonly scheduler: Scheduler;\n}\n\n/**\n * @stable\n */\nexport function createTriggersDaemon(options: CreateTriggersDaemonOptions): TriggersDaemon {\n  const fires = new Map<string, { success: number; error: number }>();\n  let catchupApplied = 0;\n  let libModeWarnings = 0;\n  let lastFireAtMs: number | undefined;\n  let running = false;\n  let pump: Promise<void> | undefined;\n\n  const warn = options.warn ?? ((m: string) => process.stderr.write(`${m}\\n`));\n\n  function recordFire(id: string, kind: 'success' | 'error'): void {\n    const entry = fires.get(id) ?? { success: 0, error: 0 };\n    entry[kind] += 1;\n    fires.set(id, entry);\n    lastFireAtMs = Date.now();\n  }\n\n  async function pumpEvents(): Promise<void> {\n    try {\n      for await (const event of options.scheduler.events()) {\n        observe(event);\n      }\n    } catch (err) {\n      warn(`[graphorin/server] triggers daemon event pump aborted: ${describeError(err)}`);\n    }\n  }\n\n  function observe(event: SchedulerEvent): void {\n    switch (event.type) {\n      case 'fire-end':\n        recordFire(event.id, 'success');\n        return;\n      case 'fire-error':\n        recordFire(event.id, 'error');\n        warn(\n          `[graphorin/server] triggers daemon: trigger '${event.id}' failed after ${event.durationMs}ms: ${describeError(event.error)}`,\n        );\n        return;\n      case 'catchup-applied':\n        catchupApplied += event.missed;\n        return;\n      case 'lib-mode-warning':\n        libModeWarnings += 1;\n        return;\n      default:\n        return;\n    }\n  }\n\n  return {\n    get scheduler() {\n      return options.scheduler;\n    },\n    async start() {\n      if (running) return;\n      running = true;\n      pump = pumpEvents();\n      await options.scheduler.start();\n    },\n    async stop() {\n      if (!running) return;\n      running = false;\n      await options.scheduler.stop();\n      if (pump !== undefined) {\n        try {\n          await pump;\n        } catch {\n          // Best-effort during stop().\n        }\n        pump = undefined;\n      }\n    },\n    async status() {\n      const all = await options.scheduler.list();\n      let active = 0;\n      let disabled = 0;\n      let deferred = 0;\n      for (const t of all) {\n        if (t.disabled) disabled += 1;\n        else active += 1;\n        if (t.missedFires > 0) deferred += 1;\n      }\n      const out: {\n        -readonly [K in keyof TriggersDaemonStatus]?: TriggersDaemonStatus[K];\n      } = {\n        running,\n        active,\n        disabled,\n        deferred,\n      };\n      if (lastFireAtMs !== undefined) {\n        out.lastFireAt = new Date(lastFireAtMs).toISOString();\n      }\n      return Object.freeze(out as TriggersDaemonStatus);\n    },\n    metrics() {\n      return Object.freeze({\n        fires: new Map(fires),\n        catchupApplied,\n        libModeWarnings,\n      });\n    },\n  };\n}\n\n/**\n * Resolve the catch-up policy default for triggers that did not\n * declare one explicitly. Returns `'none'` per DEC-150 (personal-\n * assistant friendly).\n *\n * @stable\n */\nexport function defaultCatchupPolicy(): CatchupPolicy {\n  return 'none';\n}\n\nfunction describeError(err: unknown): string {\n  if (err === null || err === undefined) return 'unknown';\n  if (err instanceof Error) return err.message;\n  return String(err);\n}\n"],"mappings":";;;;AA6EA,SAAgB,qBAAqB,SAAsD;CACzF,MAAM,wBAAQ,IAAI,KAAiD;CACnE,IAAI,iBAAiB;CACrB,IAAI,kBAAkB;CACtB,IAAIA;CACJ,IAAI,UAAU;CACd,IAAIC;CAEJ,MAAM,OAAO,QAAQ,UAAU,MAAc,QAAQ,OAAO,MAAM,GAAG,EAAE,IAAI;CAE3E,SAAS,WAAW,IAAY,MAAiC;EAC/D,MAAM,QAAQ,MAAM,IAAI,GAAG,IAAI;GAAE,SAAS;GAAG,OAAO;GAAG;AACvD,QAAM,SAAS;AACf,QAAM,IAAI,IAAI,MAAM;AACpB,iBAAe,KAAK,KAAK;;CAG3B,eAAe,aAA4B;AACzC,MAAI;AACF,cAAW,MAAM,SAAS,QAAQ,UAAU,QAAQ,CAClD,SAAQ,MAAM;WAET,KAAK;AACZ,QAAK,0DAA0D,cAAc,IAAI,GAAG;;;CAIxF,SAAS,QAAQ,OAA6B;AAC5C,UAAQ,MAAM,MAAd;GACE,KAAK;AACH,eAAW,MAAM,IAAI,UAAU;AAC/B;GACF,KAAK;AACH,eAAW,MAAM,IAAI,QAAQ;AAC7B,SACE,gDAAgD,MAAM,GAAG,iBAAiB,MAAM,WAAW,MAAM,cAAc,MAAM,MAAM,GAC5H;AACD;GACF,KAAK;AACH,sBAAkB,MAAM;AACxB;GACF,KAAK;AACH,uBAAmB;AACnB;GACF,QACE;;;AAIN,QAAO;EACL,IAAI,YAAY;AACd,UAAO,QAAQ;;EAEjB,MAAM,QAAQ;AACZ,OAAI,QAAS;AACb,aAAU;AACV,UAAO,YAAY;AACnB,SAAM,QAAQ,UAAU,OAAO;;EAEjC,MAAM,OAAO;AACX,OAAI,CAAC,QAAS;AACd,aAAU;AACV,SAAM,QAAQ,UAAU,MAAM;AAC9B,OAAI,SAAS,QAAW;AACtB,QAAI;AACF,WAAM;YACA;AAGR,WAAO;;;EAGX,MAAM,SAAS;GACb,MAAM,MAAM,MAAM,QAAQ,UAAU,MAAM;GAC1C,IAAI,SAAS;GACb,IAAI,WAAW;GACf,IAAI,WAAW;AACf,QAAK,MAAM,KAAK,KAAK;AACnB,QAAI,EAAE,SAAU,aAAY;QACvB,WAAU;AACf,QAAI,EAAE,cAAc,EAAG,aAAY;;GAErC,MAAMC,MAEF;IACF;IACA;IACA;IACA;IACD;AACD,OAAI,iBAAiB,OACnB,KAAI,aAAa,IAAI,KAAK,aAAa,CAAC,aAAa;AAEvD,UAAO,OAAO,OAAO,IAA4B;;EAEnD,UAAU;AACR,UAAO,OAAO,OAAO;IACnB,OAAO,IAAI,IAAI,MAAM;IACrB;IACA;IACD,CAAC;;EAEL;;;;;;;;;AAUH,SAAgB,uBAAsC;AACpD,QAAO;;AAGT,SAAS,cAAc,KAAsB;AAC3C,KAAI,QAAQ,QAAQ,QAAQ,OAAW,QAAO;AAC9C,KAAI,eAAe,MAAO,QAAO,IAAI;AACrC,QAAO,OAAO,IAAI"}

package/dist/triggers/index.d.ts

@@ -0,0 +1,3 @@
+import { CreateTriggersDaemonOptions, TriggersDaemon, TriggersDaemonMetrics, TriggersDaemonStatus, createTriggersDaemon, defaultCatchupPolicy } from "./daemon.js";
+import { TriggersRoutesDeps, createTriggersRoutes } from "./routes.js";
+export { type CreateTriggersDaemonOptions, type TriggersDaemon, type TriggersDaemonMetrics, type TriggersDaemonStatus, type TriggersRoutesDeps, createTriggersDaemon, createTriggersRoutes, defaultCatchupPolicy };

package/dist/triggers/index.js

@@ -0,0 +1,4 @@
+import { createTriggersDaemon, defaultCatchupPolicy } from "./daemon.js";
+import { createTriggersRoutes } from "./routes.js";
+
+export { createTriggersDaemon, createTriggersRoutes, defaultCatchupPolicy };

package/dist/triggers/routes.d.ts

@@ -0,0 +1,21 @@
+import { TriggersDaemon } from "./daemon.js";
+import { ServerVariables } from "../internal/context.js";
+import { Hono } from "hono";
+
+//#region src/triggers/routes.d.ts
+
+/**
+ * @stable
+ */
+interface TriggersRoutesDeps {
+  readonly daemon: TriggersDaemon;
+}
+/**
+ * @stable
+ */
+declare function createTriggersRoutes(deps: TriggersRoutesDeps): Hono<{
+  Variables: ServerVariables;
+}>;
+//#endregion
+export { TriggersRoutesDeps, createTriggersRoutes };
+//# sourceMappingURL=routes.d.ts.map

package/dist/triggers/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","names":[],"sources":["../../src/triggers/routes.ts"],"sourcesContent":[],"mappings":";;;;;;;;;UA6BiB,kBAAA;mBACE;;;;;iBAMH,oBAAA,OACR,qBACL;aAAkB"}

package/dist/triggers/routes.js

@@ -0,0 +1,117 @@
+import { createScopeMiddleware } from "../middleware/scope.js";
+import { Hono } from "hono";
+
+//#region src/triggers/routes.ts
+/**
+* @stable
+*/
+function createTriggersRoutes(deps) {
+	const app = new Hono();
+	const scheduler = deps.daemon.scheduler;
+	app.get("/", createScopeMiddleware("triggers:read"), async (c) => {
+		const all = await scheduler.list();
+		return c.json({ triggers: all.map(serializeTrigger) });
+	});
+	app.get("/:id", createScopeMiddleware("triggers:read"), async (c) => {
+		const id = c.req.param("id");
+		const found = (await scheduler.list()).find((t) => t.id === id);
+		if (found === void 0) return c.json({
+			error: "not-found",
+			message: `Trigger '${id}' not found.`
+		}, 404);
+		return c.json({ trigger: serializeTrigger(found) });
+	});
+	app.post("/:id/fire", createScopeMiddleware("triggers:fire"), async (c) => {
+		const id = c.req.param("id");
+		try {
+			await scheduler.fire(id);
+		} catch (err) {
+			return c.json({
+				error: "not-found",
+				message: err instanceof Error ? err.message : `Trigger '${id}' not found.`
+			}, 404);
+		}
+		return c.json({
+			ok: true,
+			fired: id
+		});
+	});
+	app.post("/:id/disable", createScopeMiddleware("triggers:disable"), async (c) => {
+		const id = c.req.param("id");
+		try {
+			const updated = await scheduler.setDisabled(id, true);
+			return c.json({
+				ok: true,
+				trigger: serializeTrigger(updated)
+			});
+		} catch {
+			return c.json({
+				error: "not-found",
+				message: `Trigger '${id}' not found.`
+			}, 404);
+		}
+	});
+	app.post("/:id/enable", createScopeMiddleware("triggers:disable"), async (c) => {
+		const id = c.req.param("id");
+		try {
+			const updated = await scheduler.setDisabled(id, false);
+			return c.json({
+				ok: true,
+				trigger: serializeTrigger(updated)
+			});
+		} catch {
+			return c.json({
+				error: "not-found",
+				message: `Trigger '${id}' not found.`
+			}, 404);
+		}
+	});
+	app.delete("/:id", createScopeMiddleware("triggers:disable"), async (c) => {
+		const id = c.req.param("id");
+		if (!(await scheduler.list()).some((t) => t.id === id)) return c.json({
+			error: "not-found",
+			message: `Trigger '${id}' not found.`
+		}, 404);
+		await scheduler.unregister(id);
+		return c.json({
+			ok: true,
+			removed: id
+		});
+	});
+	app.post("/prune", createScopeMiddleware("triggers:disable"), async (c) => {
+		const all = await scheduler.list();
+		const removedIds = [];
+		for (const trigger of all) if (trigger.disabled) {
+			await scheduler.unregister(trigger.id);
+			removedIds.push(trigger.id);
+		}
+		return c.json({
+			ok: true,
+			removed: removedIds,
+			count: removedIds.length
+		});
+	});
+	return app;
+}
+function serializeTrigger(state) {
+	return {
+		id: state.id,
+		kind: state.kind,
+		spec: state.spec,
+		callbackRef: state.callbackRef,
+		...state.nextFireAt !== void 0 ? { nextFireAt: state.nextFireAt } : {},
+		...state.lastFiredAt !== void 0 ? { lastFiredAt: state.lastFiredAt } : {},
+		missedFires: state.missedFires,
+		disabled: state.disabled,
+		catchupPolicy: state.catchupPolicy,
+		maxCatchupRuns: state.maxCatchupRuns,
+		catchupWindowMs: state.catchupWindowMs,
+		...state.tags !== void 0 ? { tags: [...state.tags] } : {},
+		createdAt: state.createdAt,
+		...state.updatedAt !== void 0 ? { updatedAt: state.updatedAt } : {}
+	};
+}
+
+//#endregion
+export { createTriggersRoutes };
+//# sourceMappingURL=routes.js.map

package/dist/triggers/routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.js","names":["scheduler: Scheduler","removedIds: string[]"],"sources":["../../src/triggers/routes.ts"],"sourcesContent":["/**\n * REST routes for the `/v1/triggers` family. Mounted by the server\n * factory when a {@link TriggersDaemon} is wired in.\n *\n *   GET    /triggers                    (scope `triggers:read`)\n *   GET    /triggers/:id                (scope `triggers:read`)\n *   POST   /triggers/:id/fire           (scope `triggers:fire`)\n *   POST   /triggers/:id/disable        (scope `triggers:disable`) — flag flip\n *   POST   /triggers/:id/enable         (scope `triggers:disable`) — flag flip\n *   DELETE /triggers/:id                (scope `triggers:disable`) — unregister\n *   POST   /triggers/prune              (scope `triggers:disable`)\n *\n * Response shapes mirror the persisted `TriggerState` rows so CLI +\n * dashboard consumers can render them without re-mapping.\n *\n * @packageDocumentation\n */\n\nimport type { TriggerState } from '@graphorin/core/contracts';\nimport type { Scheduler } from '@graphorin/triggers';\nimport { Hono } from 'hono';\n\nimport type { ServerVariables } from '../internal/context.js';\nimport { createScopeMiddleware } from '../middleware/scope.js';\nimport type { TriggersDaemon } from './daemon.js';\n\n/**\n * @stable\n */\nexport interface TriggersRoutesDeps {\n  readonly daemon: TriggersDaemon;\n}\n\n/**\n * @stable\n */\nexport function createTriggersRoutes(\n  deps: TriggersRoutesDeps,\n): Hono<{ Variables: ServerVariables }> {\n  const app = new Hono<{ Variables: ServerVariables }>();\n  const scheduler: Scheduler = deps.daemon.scheduler;\n\n  app.get('/', createScopeMiddleware('triggers:read'), async (c) => {\n    const all = await scheduler.list();\n    return c.json({ triggers: all.map(serializeTrigger) });\n  });\n\n  app.get('/:id', createScopeMiddleware('triggers:read'), async (c) => {\n    const id = c.req.param('id');\n    const all = await scheduler.list();\n    const found = all.find((t) => t.id === id);\n    if (found === undefined) {\n      return c.json({ error: 'not-found', message: `Trigger '${id}' not found.` }, 404);\n    }\n    return c.json({ trigger: serializeTrigger(found) });\n  });\n\n  app.post('/:id/fire', createScopeMiddleware('triggers:fire'), async (c) => {\n    const id = c.req.param('id');\n    try {\n      await scheduler.fire(id);\n    } catch (err) {\n      return c.json(\n        {\n          error: 'not-found',\n          message: err instanceof Error ? err.message : `Trigger '${id}' not found.`,\n        },\n        404,\n      );\n    }\n    return c.json({ ok: true, fired: id });\n  });\n\n  // IP-17: disable/enable are non-destructive flag flips on the\n  // persistent TriggerState (in agreement with the CLI); the\n  // destructive removal is DELETE /:id.\n  app.post('/:id/disable', createScopeMiddleware('triggers:disable'), async (c) => {\n    const id = c.req.param('id');\n    try {\n      const updated = await scheduler.setDisabled(id, true);\n      return c.json({ ok: true, trigger: serializeTrigger(updated) });\n    } catch {\n      return c.json({ error: 'not-found', message: `Trigger '${id}' not found.` }, 404);\n    }\n  });\n\n  app.post('/:id/enable', createScopeMiddleware('triggers:disable'), async (c) => {\n    const id = c.req.param('id');\n    try {\n      const updated = await scheduler.setDisabled(id, false);\n      return c.json({ ok: true, trigger: serializeTrigger(updated) });\n    } catch {\n      return c.json({ error: 'not-found', message: `Trigger '${id}' not found.` }, 404);\n    }\n  });\n\n  app.delete('/:id', createScopeMiddleware('triggers:disable'), async (c) => {\n    const id = c.req.param('id');\n    const all = await scheduler.list();\n    if (!all.some((t) => t.id === id)) {\n      return c.json({ error: 'not-found', message: `Trigger '${id}' not found.` }, 404);\n    }\n    await scheduler.unregister(id);\n    return c.json({ ok: true, removed: id });\n  });\n\n  app.post('/prune', createScopeMiddleware('triggers:disable'), async (c) => {\n    const all = await scheduler.list();\n    const removedIds: string[] = [];\n    for (const trigger of all) {\n      if (trigger.disabled) {\n        await scheduler.unregister(trigger.id);\n        removedIds.push(trigger.id);\n      }\n    }\n    return c.json({ ok: true, removed: removedIds, count: removedIds.length });\n  });\n\n  return app;\n}\n\nfunction serializeTrigger(state: TriggerState): Record<string, unknown> {\n  return {\n    id: state.id,\n    kind: state.kind,\n    spec: state.spec,\n    callbackRef: state.callbackRef,\n    ...(state.nextFireAt !== undefined ? { nextFireAt: state.nextFireAt } : {}),\n    ...(state.lastFiredAt !== undefined ? { lastFiredAt: state.lastFiredAt } : {}),\n    missedFires: state.missedFires,\n    disabled: state.disabled,\n    catchupPolicy: state.catchupPolicy,\n    maxCatchupRuns: state.maxCatchupRuns,\n    catchupWindowMs: state.catchupWindowMs,\n    ...(state.tags !== undefined ? { tags: [...state.tags] } : {}),\n    createdAt: state.createdAt,\n    ...(state.updatedAt !== undefined ? { updatedAt: state.updatedAt } : {}),\n  };\n}\n"],"mappings":"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"}

package/dist/ws/dispatcher.d.ts

@@ -0,0 +1,169 @@
+import { DeliveryCommentaryConfig } from "../commentary/types.js";
+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";
+
+//#region src/ws/dispatcher.d.ts
+
+/**
+ * Public configuration accepted by {@link createWsDispatcher}.
+ *
+ * @stable
+ */
+interface WsDispatcherOptions {
+  readonly commentary?: DeliveryCommentaryConfig;
+  readonly replayBuffer?: ReplayBufferOptions;
+  /**
+   * Cap on outstanding events queued for an offline subscriber.
+   * Defaults to the same value as the replay buffer per-subject cap.
+   */
+  readonly perConnectionQueueLimit?: number;
+  readonly now?: () => number;
+  /**
+   * Logger sink for protocol violations + dropped frames. When
+   * omitted, the dispatcher is silent (production wiring uses the
+   * server's structured logger).
+   */
+  readonly onWarn?: (event: WsDispatcherWarning) => void;
+}
+/**
+ * Discriminator surfaced to the optional warn sink.
+ *
+ * @stable
+ */
+type WsDispatcherWarning = {
+  readonly kind: 'invalid-frame';
+  readonly subscriptionId: string;
+  readonly issues: ReadonlyArray<string>;
+} | {
+  readonly kind: 'queue-overflow';
+  readonly subscriptionId: string;
+} | {
+  readonly kind: 'subject-rejected';
+  readonly subject: string;
+  readonly reason: string;
+};
+/**
+ * Subscriber surface used by the dispatcher. Each WebSocket
+ * connection wraps its `WSContext.send` in this interface so the
+ * dispatcher does not depend on `@hono/node-ws` types directly.
+ *
+ * @stable
+ */
+interface WsSubscriberHandle {
+  readonly id: string;
+  readonly tokenId: string;
+  readonly grantedScopes: ReadonlyArray<ParsedScope>;
+  /** Send a server frame; the dispatcher already validated it. */
+  send(frame: ServerMessage): void;
+  /** Close the underlying WebSocket with a Graphorin close code. */
+  close(code: number, reason: string): void;
+  /**
+   * Optional buffered-byte sample. The dispatcher reads this on every
+   * emit to detect sustained backpressure and close the connection
+   * with the Graphorin `flow.throttled` code (4006) before the OS-
+   * level send buffer collapses. Consumers backed by `@hono/node-ws`
+   * can return the underlying `ws.bufferedAmount`. When the field is
+   * not implemented, the dispatcher falls back to the per-connection
+   * outstanding-event counter.
+   */
+  bufferedAmount?(): number;
+}
+/**
+ * Snapshot of an active subscription. Surfaced via
+ * {@link WsDispatcher.snapshotSubscription}.
+ *
+ * @stable
+ */
+interface WsSubscriptionSnapshot {
+  readonly subscriptionId: string;
+  readonly subject: string;
+  readonly subjectKind: ParsedSubject['kind'];
+  readonly subscriberId: string;
+  readonly tokenId: string;
+  readonly createdAt: number;
+  readonly lastEventId: string | undefined;
+}
+/**
+ * Result of {@link WsDispatcher.subscribe}.
+ *
+ * @stable
+ */
+type SubscribeResult = {
+  readonly ok: true;
+  readonly subscription: WsSubscriptionSnapshot;
+  readonly replayedCount: number;
+  readonly snapshotEventId: string | undefined;
+} | {
+  readonly ok: false;
+  readonly reason: 'subject-malformed' | 'subject-unknown' | 'subject-wildcard' | 'scope-denied';
+};
+/**
+ * Public surface of the dispatcher.
+ *
+ * @stable
+ */
+interface WsDispatcher {
+  readonly sanitizer: DeliveryCommentarySanitizer;
+  readonly replayBuffer: ReplayBuffer;
+  /**
+   * Register a subscriber (one per WebSocket connection).
+   * `unregister` is called on close.
+   */
+  registerSubscriber(handle: WsSubscriberHandle): {
+    unregister(): void;
+  };
+  /**
+   * Open a new subscription for an active subscriber. Returns either
+   * the subscription snapshot + replayed-event count or a typed
+   * failure reason the caller maps to the appropriate close code /
+   * RPC error.
+   */
+  subscribe(input: {
+    readonly subscriberId: string;
+    readonly subject: string;
+    readonly subscriptionId: string;
+    readonly sinceEventId?: string;
+  }): SubscribeResult;
+  unsubscribe(subscriptionId: string): boolean;
+  /**
+   * Push an event into the dispatcher. Goes through the sanitizer,
+   * validates against the protocol schema, persists into the replay
+   * buffer, and fans out to every matching active subscription.
+   */
+  emit(subject: string, frame: BareEventFrame): void;
+  /** Push a lifecycle frame to a single subscription. */
+  emitLifecycle(subscriptionId: string, status: ServerLifecycleFrame['status'], reason?: string): void;
+  /** List active subscriptions for a given subscriber (diagnostics). */
+  listForSubscriber(subscriberId: string): ReadonlyArray<WsSubscriptionSnapshot>;
+  snapshotSubscription(subscriptionId: string): WsSubscriptionSnapshot | undefined;
+  size(): {
+    readonly subscribers: number;
+    readonly subscriptions: number;
+  };
+  /** Clear in-memory state (used during graceful shutdown). */
+  shutdown(): void;
+}
+/**
+ * Frame argument accepted by {@link WsDispatcher.emit}. The
+ * dispatcher fills in `subscriptionId`, `subject`, and `eventId`.
+ *
+ * @stable
+ */
+interface BareEventFrame {
+  readonly type: string;
+  readonly payload: unknown;
+  readonly eventId?: string;
+}
+/**
+ * Build a fresh dispatcher.
+ *
+ * @stable
+ */
+declare function createWsDispatcher(options?: WsDispatcherOptions): WsDispatcher;
+//#endregion
+export { BareEventFrame, SubscribeResult, WsDispatcher, WsDispatcherOptions, WsDispatcherWarning, WsSubscriberHandle, WsSubscriptionSnapshot, createWsDispatcher };
+//# sourceMappingURL=dispatcher.d.ts.map

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

@@ -0,0 +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,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"}