@classytic/arc 2.17.1 → 2.18.1

package/dist/{init-DYzfniuX.mjs → init-DQ_rY1J7.mjs}

@@ -917,9 +917,9 @@ ${config.adapter === "mongokit" ? `    await mongoose.connection.collection('use
 //#region src/cli/commands/init/dependency-plan.ts
 const SCAFFOLD_DEP_VERSIONS = {
 	core: {
-		"@classytic/arc": "^2.13.0",
+		"@classytic/arc": "^2.17.2",
 		"@classytic/primitives": "^0.6.0",
-		"@classytic/repo-core": "^0.4.2",
+		"@classytic/repo-core": "^0.5.0",
 		"@fastify/cors": "^11.2.0",
 		"@fastify/helmet": "^13.0.2",
 		"@fastify/rate-limit": "^10.3.0",
@@ -929,27 +929,27 @@ const SCAFFOLD_DEP_VERSIONS = {
 		fastify: "^5.8.5"
 	},
 	authJwt: {
-		"@fastify/jwt": "^10.0.0",
-		bcryptjs: "^3.0.0"
+		"@fastify/jwt": "^10.1.0",
+		bcryptjs: "^3.0.3"
 	},
 	authBetterAuth: {
-		"better-auth": "^1.6.9",
-		mongodb: "^7.1.0"
+		"better-auth": "^1.6.11",
+		mongodb: "^7.2.0"
 	},
-	authBetterAuthApiKey: { "@better-auth/api-key": "^1.6.9" },
+	authBetterAuthApiKey: { "@better-auth/api-key": "^1.6.11" },
 	adapterMongokit: {
-		"@classytic/mongokit": "^3.13.0",
-		mongoose: "^9.6.1"
+		"@classytic/mongokit": "^3.14.0",
+		mongoose: "^9.6.2"
 	},
 	devCommon: {
 		"mongodb-memory-server": "^11.1.0",
-		"pino-pretty": "^13.0.0",
-		vitest: "^4.1.5"
+		"pino-pretty": "^13.1.3",
+		vitest: "^4.1.7"
 	},
 	devTypescript: {
 		"@types/node": "^22.10.0",
-		tsx: "^4.21.0",
-		typescript: "^5.7.2"
+		tsx: "^4.22.3",
+		typescript: "^6.0.3"
 	},
 	typesJwt: { "@types/bcryptjs": "^3.0.0" }
 };

package/dist/integrations/event-gateway.d.mts

@@ -1,5 +1,5 @@
 import { n as DomainEvent } from "../EventTransport-B1GFiYUy.mjs";
-import { a as WebSocketMessage, i as WebSocketClient } from "../websocket-BJ0w-3Dt.mjs";
+import { c as WebSocketClient, l as WebSocketMessage } from "../websocket-BZMUP7Gr.mjs";
 import { FastifyPluginAsync, FastifyRequest } from "fastify";
 
 //#region src/integrations/event-gateway.d.ts

package/dist/integrations/index.d.mts

@@ -1,7 +1,7 @@
-import { a as WebSocketMessage, i as WebSocketClient, o as WebSocketPluginOptions } from "../websocket-BJ0w-3Dt.mjs";
+import { c as WebSocketClient, l as WebSocketMessage, u as WebSocketPluginOptions } from "../websocket-BZMUP7Gr.mjs";
 import { EventGatewayOptions } from "./event-gateway.mjs";
 import { JobDefinition, JobDispatchOptions, JobDispatcher, JobMeta, JobsPluginOptions, QueueStats } from "./jobs.mjs";
-import { c as McpAuthResult, d as PromptDefinition, g as ToolDefinition, h as ToolContext, l as McpPluginOptions, m as ToolAnnotations, n as CallToolResult, o as CrudOperation, r as CreateMcpServerConfig, t as BetterAuthHandler, u as McpResourceConfig } from "../types-CoMjNmkF.mjs";
+import { c as McpAuthResult, d as PromptDefinition, g as ToolDefinition, h as ToolContext, l as McpPluginOptions, m as ToolAnnotations, n as CallToolResult, o as CrudOperation, r as CreateMcpServerConfig, t as BetterAuthHandler, u as McpResourceConfig } from "../types-DH-7WO64.mjs";
 import { StreamlinePluginOptions, WorkflowLike, WorkflowRunLike } from "./streamline.mjs";
 import { WebhookDeliveryRecord, WebhookManager, WebhookPluginOptions, WebhookStore, WebhookSubscription } from "./webhooks.mjs";
 export { type BetterAuthHandler, type CallToolResult, type CreateMcpServerConfig, type CrudOperation, type EventGatewayOptions, type JobDefinition, type JobDispatchOptions, type JobDispatcher, type JobMeta, type JobsPluginOptions, type McpAuthResult, type McpPluginOptions, type McpResourceConfig, type PromptDefinition, type QueueStats, type StreamlinePluginOptions, type ToolAnnotations, type ToolContext, type ToolDefinition, type WebSocketClient, type WebSocketMessage, type WebSocketPluginOptions, type WebhookDeliveryRecord, type WebhookManager, type WebhookPluginOptions, type WebhookStore, type WebhookSubscription, type WorkflowLike, type WorkflowRunLike };

package/dist/integrations/mcp/index.d.mts

@@ -1,7 +1,7 @@
-import { V as ResourceDefinition, bt as IRequestContext, yt as IControllerResponse } from "../../index-C1JSBan-.mjs";
+import { V as ResourceDefinition, bt as IRequestContext, yt as IControllerResponse } from "../../index-C000faom.mjs";
 import { i as RequestScope } from "../../types-CfapW2t8.mjs";
 import { c as PermissionCheck } from "../../fields-DqZLp5d6.mjs";
-import { a as CrudDescriptionOverride, c as McpAuthResult, d as PromptDefinition, f as PromptResult, g as ToolDefinition, h as ToolContext, i as CrudDescriptionMeta, l as McpPluginOptions, m as ToolAnnotations, n as CallToolResult, o as CrudOperation, p as SessionEntry, r as CreateMcpServerConfig, s as McpAuthResolver, t as BetterAuthHandler, u as McpResourceConfig } from "../../types-CoMjNmkF.mjs";
+import { a as CrudDescriptionOverride, c as McpAuthResult, d as PromptDefinition, f as PromptResult, g as ToolDefinition, h as ToolContext, i as CrudDescriptionMeta, l as McpPluginOptions, m as ToolAnnotations, n as CallToolResult, o as CrudOperation, p as SessionEntry, r as CreateMcpServerConfig, s as McpAuthResolver, t as BetterAuthHandler, u as McpResourceConfig } from "../../types-DH-7WO64.mjs";
 import { ErrorContract } from "@classytic/repo-core/errors";
 import { FastifyPluginAsync } from "fastify";
 import { z } from "zod";
@@ -505,6 +505,46 @@ declare function filterResourcesForMcp<T extends {
 }>(resources: readonly T[], inputs: ResourceFilterInputs): T[];
 declare const mcpPlugin: FastifyPluginAsync<McpPluginOptions>;
 //#endregion
+//#region src/integrations/mcp/realtimeBridge.d.ts
+/**
+ * Inbound tool-call shape — accepts both LiveKit Agents (`arguments`)
+ * and OpenAI Realtime (`arguments_json` string) variants. Other realtime
+ * vendors stay flexible because we only look at the canonical fields.
+ */
+interface RealtimeToolCall {
+  id: string;
+  name: string;
+  /** Parsed object form. Preferred over `arguments_json`. */
+  arguments?: Record<string, unknown>;
+  /** JSON-string form (OpenAI Realtime tools). Parsed if `arguments` is absent. */
+  arguments_json?: string;
+}
+/** Outbound shape — mirrors js-genai's sendToolResponse. */
+interface RealtimeToolResponse {
+  id: string;
+  name: string;
+  /** Tool result — `content` from the MCP CallToolResult, normalized to plain JSON. */
+  response: Record<string, unknown>;
+  /** Surfaces tool-side errors so the model can recover. */
+  isError?: boolean;
+}
+interface DispatchOptions<TSession = unknown> {
+  session?: TSession | null;
+  log?: ToolContext<TSession>["log"];
+  /** Forwarded into `ctx.extra` for advanced handlers. */
+  extra?: Record<string, unknown>;
+}
+/**
+ * Dispatch a batch of tool calls through the host's MCP tool registry.
+ *
+ * Returns the response array in the same order as the input. Each
+ * response carries either the tool's `content` (success path) or a
+ * `{isError:true, error:{message,...}}` shape (validation failure or
+ * handler throw). The realtime client uses the `id` to correlate
+ * responses to the original calls.
+ */
+declare function dispatchRealtimeToolCall<TSession = unknown>(tools: readonly ToolDefinition[], calls: readonly RealtimeToolCall[], opts?: DispatchOptions<TSession>): Promise<RealtimeToolResponse[]>;
+//#endregion
 //#region src/integrations/mcp/resourceToTools.d.ts
 interface ResourceToToolsConfig extends McpResourceConfig {
   toolNamePrefix?: string;
@@ -578,4 +618,4 @@ declare function permissionDeniedResult(args: {
   session: McpAuthResult | null;
 }): CallToolResult;
 //#endregion
-export { type AuthRef, type BetterAuthHandler, type BuildMcpToolsFromBridgesOptions, type CallToolResult, type CreateMcpAuthFromBetterAuthApiKeyOptions, type CreateMcpServerConfig, type CrudDescriptionMeta, type CrudDescriptionOverride, type CrudOperation, type DefinePromptConfig, type DefineToolConfig, type FieldRuleEntry, type FieldRulesToZodOptions, type InvokeControllerOptions, type McpAuthResolver, type McpAuthResult, type McpBridge, type McpGuard, type McpOperation, type McpPluginOptions, type McpResourceConfig, type McpServerInstance, type PromptDefinition, type PromptResult, type ResourceToToolsConfig, type ToolAnnotations, type ToolContext, type ToolDefinition, bridgeToMcp, buildMcpToolsFromBridges, buildRequestContext, createMcpAuthFromBetterAuthApiKey, createMcpServer, customGuard, defaultCrudDescription, definePrompt, defineTool, denied, fieldRulesToZod, filterResourcesForMcp, getOrgId, getUserId, guard, hasOrg, invokeController, isAuthenticated, isOrg, mcpHandlerAdapter, mcpPlugin, permissionDeniedResult, requireAuth, requireOrg, requireOrgId, requireRole, resolveCrudDescription, resolveToolCollisions, resourceToTools, toCallToolError, toCallToolResult, toCallToolSuccess };
+export { type AuthRef, type BetterAuthHandler, type BuildMcpToolsFromBridgesOptions, type CallToolResult, type CreateMcpAuthFromBetterAuthApiKeyOptions, type CreateMcpServerConfig, type CrudDescriptionMeta, type CrudDescriptionOverride, type CrudOperation, type DefinePromptConfig, type DefineToolConfig, type DispatchOptions, type FieldRuleEntry, type FieldRulesToZodOptions, type InvokeControllerOptions, type McpAuthResolver, type McpAuthResult, type McpBridge, type McpGuard, type McpOperation, type McpPluginOptions, type McpResourceConfig, type McpServerInstance, type PromptDefinition, type PromptResult, type RealtimeToolCall, type RealtimeToolResponse, type ResourceToToolsConfig, type ToolAnnotations, type ToolContext, type ToolDefinition, bridgeToMcp, buildMcpToolsFromBridges, buildRequestContext, createMcpAuthFromBetterAuthApiKey, createMcpServer, customGuard, defaultCrudDescription, definePrompt, defineTool, denied, dispatchRealtimeToolCall, fieldRulesToZod, filterResourcesForMcp, getOrgId, getUserId, guard, hasOrg, invokeController, isAuthenticated, isOrg, mcpHandlerAdapter, mcpPlugin, permissionDeniedResult, requireAuth, requireOrg, requireOrgId, requireRole, resolveCrudDescription, resolveToolCollisions, resourceToTools, toCallToolError, toCallToolResult, toCallToolSuccess };

package/dist/integrations/mcp/index.mjs

@@ -1,4 +1,4 @@
-import { a as defaultCrudDescription, c as mcpHandlerAdapter, d as toCallToolResult, f as toCallToolSuccess, h as resolveToolCollisions, i as fieldRulesToZod, l as permissionDeniedResult, m as createMcpServer, n as mcpPlugin, o as resolveCrudDescription, p as buildRequestContext, r as resourceToTools, s as invokeController, t as filterResourcesForMcp, u as toCallToolError } from "../../mcpPlugin-C6FViZXw.mjs";
+import { a as defaultCrudDescription, c as mcpHandlerAdapter, d as toCallToolResult, f as toCallToolSuccess, h as resolveToolCollisions, i as fieldRulesToZod, l as permissionDeniedResult, m as createMcpServer, n as mcpPlugin, o as resolveCrudDescription, p as buildRequestContext, r as resourceToTools, s as invokeController, t as filterResourcesForMcp, u as toCallToolError } from "../../mcpPlugin-BrepZ0cV.mjs";
 //#region src/integrations/mcp/defineTool.ts
 /**
 * Define a type-safe MCP tool.
@@ -275,4 +275,104 @@ function definePrompt(name, config) {
 	};
 }
 //#endregion
-export { bridgeToMcp, buildMcpToolsFromBridges, buildRequestContext, createMcpAuthFromBetterAuthApiKey, createMcpServer, customGuard, defaultCrudDescription, definePrompt, defineTool, denied, fieldRulesToZod, filterResourcesForMcp, getOrgId, getUserId, guard, hasOrg, invokeController, isAuthenticated, isOrg, mcpHandlerAdapter, mcpPlugin, permissionDeniedResult, requireAuth, requireOrg, requireOrgId, requireRole, resolveCrudDescription, resolveToolCollisions, resourceToTools, toCallToolError, toCallToolResult, toCallToolSuccess };
+//#region src/integrations/mcp/realtimeBridge.ts
+/**
+* Dispatch a batch of tool calls through the host's MCP tool registry.
+*
+* Returns the response array in the same order as the input. Each
+* response carries either the tool's `content` (success path) or a
+* `{isError:true, error:{message,...}}` shape (validation failure or
+* handler throw). The realtime client uses the `id` to correlate
+* responses to the original calls.
+*/
+async function dispatchRealtimeToolCall(tools, calls, opts = {}) {
+	const byName = new Map(tools.map((t) => [t.name, t]));
+	const noopLog = async () => {};
+	const baseCtx = {
+		session: opts.session ?? null,
+		log: opts.log ?? noopLog,
+		extra: opts.extra ?? {}
+	};
+	return (await Promise.allSettled(calls.map((call) => dispatchOne(byName.get(call.name), call, baseCtx)))).map((s, i) => {
+		const call = calls[i];
+		if (!call) return {
+			id: "unknown",
+			name: "unknown",
+			isError: true,
+			response: { error: "missing call slot" }
+		};
+		if (s.status === "fulfilled") return s.value;
+		return {
+			id: call.id,
+			name: call.name,
+			isError: true,
+			response: { error: s.reason instanceof Error ? s.reason.message : String(s.reason) }
+		};
+	});
+}
+async function dispatchOne(def, call, ctx) {
+	if (!def) return {
+		id: call.id,
+		name: call.name,
+		isError: true,
+		response: { error: `unknown tool: ${call.name}` }
+	};
+	let parsedArgs = call.arguments ?? {};
+	if (!call.arguments && typeof call.arguments_json === "string") try {
+		parsedArgs = JSON.parse(call.arguments_json);
+	} catch {
+		return {
+			id: call.id,
+			name: call.name,
+			isError: true,
+			response: { error: "arguments_json is not valid JSON" }
+		};
+	}
+	if (def.inputSchema) {
+		const fieldErrors = [];
+		const validated = {};
+		for (const [key, schema] of Object.entries(def.inputSchema)) {
+			const result = schema.safeParse(parsedArgs[key]);
+			if (!result.success) fieldErrors.push(`${key}: ${result.error.message}`);
+			else validated[key] = result.data;
+		}
+		if (fieldErrors.length > 0) return {
+			id: call.id,
+			name: call.name,
+			isError: true,
+			response: {
+				error: "argument validation failed",
+				fields: fieldErrors
+			}
+		};
+		parsedArgs = validated;
+	}
+	const result = await def.handler(parsedArgs, ctx);
+	return {
+		id: call.id,
+		name: call.name,
+		isError: result.isError,
+		response: normalizeResult(result)
+	};
+}
+/**
+* Normalize an MCP `CallToolResult` into a flat JSON object the realtime
+* wire can carry. Prefers structuredContent; falls back to concatenated
+* text content.
+*/
+function normalizeResult(result) {
+	if (result.structuredContent) return result.structuredContent;
+	const texts = [];
+	for (const part of result.content) if (part.type === "text" && typeof part.text === "string") texts.push(part.text);
+	if (texts.length > 0) {
+		const joined = texts.join("");
+		try {
+			const parsed = JSON.parse(joined);
+			if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+		} catch {}
+		return { text: joined };
+	}
+	return {};
+}
+//#endregion
+export { bridgeToMcp, buildMcpToolsFromBridges, buildRequestContext, createMcpAuthFromBetterAuthApiKey, createMcpServer, customGuard, defaultCrudDescription, definePrompt, defineTool, denied, dispatchRealtimeToolCall, fieldRulesToZod, filterResourcesForMcp, getOrgId, getUserId, guard, hasOrg, invokeController, isAuthenticated, isOrg, mcpHandlerAdapter, mcpPlugin, permissionDeniedResult, requireAuth, requireOrg, requireOrgId, requireRole, resolveCrudDescription, resolveToolCollisions, resourceToTools, toCallToolError, toCallToolResult, toCallToolSuccess };

package/dist/integrations/mcp/testing.d.mts

@@ -1,4 +1,4 @@
-import { c as McpAuthResult, l as McpPluginOptions } from "../../types-CoMjNmkF.mjs";
+import { c as McpAuthResult, l as McpPluginOptions } from "../../types-DH-7WO64.mjs";
 
 //#region src/integrations/mcp/testing.d.ts
 interface TestMcpClientOptions {

package/dist/integrations/mcp/testing.mjs

@@ -1,4 +1,4 @@
-import { m as createMcpServer, r as resourceToTools, t as filterResourcesForMcp } from "../../mcpPlugin-C6FViZXw.mjs";
+import { m as createMcpServer, r as resourceToTools, t as filterResourcesForMcp } from "../../mcpPlugin-BrepZ0cV.mjs";
 //#region src/integrations/mcp/testing.ts
 /**
 * @classytic/arc/mcp/testing — MCP Test Utilities

package/dist/integrations/streamline.d.mts

@@ -238,6 +238,13 @@ declare const STREAMLINE_BUS_EVENTS: readonly ["step:started", "step:completed",
  * the run is still active after them.
  */
 declare const STREAMLINE_TERMINAL_EVENTS: readonly ["workflow:completed", "workflow:failed", "workflow:cancelled"];
+/**
+ * Terminal run STATUSES (distinct from the terminal EVENT names above).
+ * Mirrors streamline's `isTerminalState()` — a run in one of these will
+ * emit no further bus events, so the SSE handler sends its snapshot and
+ * closes immediately rather than holding a connection open on a dead run.
+ */
+declare const TERMINAL_RUN_STATUSES: Set<string>;
 /**
  * Pluggable streamline integration for Arc.
  *
@@ -248,4 +255,4 @@ declare const STREAMLINE_TERMINAL_EVENTS: readonly ["workflow:completed", "workf
  */
 declare const streamlinePlugin: FastifyPluginAsync<StreamlinePluginOptions>;
 //#endregion
-export { STREAMLINE_BUS_EVENTS, STREAMLINE_FAILURE_CODES, STREAMLINE_TERMINAL_EVENTS, StreamlinePluginOptions, WorkflowLike, WorkflowRunLike, WorkflowStartOptions, streamlinePlugin };
+export { STREAMLINE_BUS_EVENTS, STREAMLINE_FAILURE_CODES, STREAMLINE_TERMINAL_EVENTS, StreamlinePluginOptions, TERMINAL_RUN_STATUSES, WorkflowLike, WorkflowRunLike, WorkflowStartOptions, streamlinePlugin };

package/dist/integrations/streamline.mjs

@@ -58,6 +58,17 @@ const STREAMLINE_TERMINAL_EVENTS = [
 	"workflow:failed",
 	"workflow:cancelled"
 ];
+/**
+* Terminal run STATUSES (distinct from the terminal EVENT names above).
+* Mirrors streamline's `isTerminalState()` — a run in one of these will
+* emit no further bus events, so the SSE handler sends its snapshot and
+* closes immediately rather than holding a connection open on a dead run.
+*/
+const TERMINAL_RUN_STATUSES = new Set([
+	"done",
+	"failed",
+	"cancelled"
+]);
 const streamlinePluginImpl = async (fastify, options) => {
 	const { workflows, prefix = "/workflows", auth = true, bridgeEvents = true, enableStreaming = false, enableHookEndpoint = false, tenantResolver, bypassTenantResolver, permissions: perms } = options;
 	const routeScope = prefix;
@@ -255,15 +266,19 @@ const streamlinePluginImpl = async (fastify, options) => {
 		if (enableStreaming && wf.container?.eventBus) fastify.get(`${routePrefix}/runs/:runId/stream`, { preHandler: authPreHandler }, async (request, reply) => {
 			if (!await checkPerm("get", request)) throw new ForbiddenError();
 			const { runId } = request.params;
-			if (!await wf.get(runId)) throw new NotFoundError("Workflow run", runId);
+			const run = await wf.get(runId);
+			if (!run) throw new NotFoundError("Workflow run", runId);
 			reply.raw.writeHead(200, {
 				"Content-Type": "text/event-stream",
 				"Cache-Control": "no-cache",
-				Connection: "keep-alive"
+				Connection: "keep-alive",
+				"X-Accel-Buffering": "no"
 			});
+			reply.raw.flushHeaders();
 			const terminalEvents = new Set(STREAMLINE_TERMINAL_EVENTS);
 			const listeners = [];
 			let closed = false;
+			let heartbeat;
 			const send = (event, data) => {
 				if (closed) return;
 				try {
@@ -275,12 +290,28 @@ const streamlinePluginImpl = async (fastify, options) => {
 			const cleanup = () => {
 				if (closed) return;
 				closed = true;
+				if (heartbeat) clearInterval(heartbeat);
 				for (const { event, fn } of listeners) wf.container?.eventBus.off(event, fn);
 				listeners.length = 0;
 				try {
 					reply.raw.end();
 				} catch {}
 			};
+			send("workflow:snapshot", run);
+			const runStatus = run.status;
+			if (runStatus && TERMINAL_RUN_STATUSES.has(runStatus)) {
+				cleanup();
+				return;
+			}
+			heartbeat = setInterval(() => {
+				if (closed) return;
+				try {
+					reply.raw.write(`: ping\n\n`);
+				} catch {
+					cleanup();
+				}
+			}, 15e3);
+			heartbeat.unref?.();
 			for (const eventName of STREAMLINE_BUS_EVENTS) {
 				const fn = (payload) => {
 					const p = payload;
@@ -336,4 +367,4 @@ const streamlinePlugin = fp(streamlinePluginImpl, {
 	fastify: "5.x"
 });
 //#endregion
-export { STREAMLINE_BUS_EVENTS, STREAMLINE_FAILURE_CODES, STREAMLINE_TERMINAL_EVENTS, streamlinePlugin };
+export { STREAMLINE_BUS_EVENTS, STREAMLINE_FAILURE_CODES, STREAMLINE_TERMINAL_EVENTS, TERMINAL_RUN_STATUSES, streamlinePlugin };

package/dist/integrations/websocket-pushref-redis.d.mts

@@ -0,0 +1,71 @@
+import { c as SerializedEntry, i as Principal, n as FencedWriteOutcome, s as PushRefStore, t as EnvelopeSnapshot } from "../pushref-registry-Bq_-EVsC.mjs";
+
+//#region src/integrations/websocket-pushref-redis.d.ts
+/**
+ * Minimal `ioredis` shape — typed structurally so this file doesn't
+ * take a typecheck-time dep on `ioredis`. The peer dep is declared
+ * `optional: true` in package.json; hosts who don't use this subpath
+ * never need to install ioredis.
+ */
+interface RedisLike {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, mode?: string, duration?: number): Promise<unknown>;
+  del(key: string): Promise<number>;
+  pexpire(key: string, ttlMs: number): Promise<number>;
+  scan(cursor: string | number, matchKw: "MATCH", pattern: string, countKw: "COUNT", count: number): Promise<[string, string[]]>;
+  eval(script: string, numKeys: number, ...args: (string | number)[]): Promise<unknown>;
+}
+interface RedisPushRefStoreOptions {
+  /** Redis key namespace. Default `arc:pushref:`. */
+  keyPrefix?: string;
+  /**
+   * Grace ms added to the Redis-side TTL beyond the registry's logical
+   * TTL — protects against clock skew between application and broker.
+   * Default 5_000.
+   */
+  graceMs?: number;
+}
+declare class RedisPushRefStore implements PushRefStore {
+  private redis;
+  private prefix;
+  private graceMs;
+  constructor(redis: RedisLike, opts?: RedisPushRefStoreOptions);
+  get(pushRef: string): Promise<SerializedEntry | undefined>;
+  set(pushRef: string, entry: SerializedEntry): Promise<void>;
+  delete(pushRef: string): Promise<void>;
+  claim(args: {
+    pushRef: string;
+    principal: Principal;
+    now: number;
+    ttlMs: number;
+    mintFresh: () => SerializedEntry;
+    maxEntries: number;
+    countNonExpired: () => Promise<number>;
+  }): Promise<{
+    outcome: "new" | "resumed" | "rejected";
+    entry?: SerializedEntry;
+    supersededActive?: boolean;
+  }>;
+  releaseIfGen(args: {
+    pushRef: string;
+    expectedGeneration: number;
+    snapshot?: EnvelopeSnapshot;
+    expiresAt: number;
+  }): Promise<FencedWriteOutcome>;
+  persistIfGen(args: {
+    pushRef: string;
+    expectedGeneration: number;
+    snapshot: EnvelopeSnapshot;
+    expiresAt: number;
+  }): Promise<FencedWriteOutcome>;
+  stageIfInactive(args: {
+    pushRef: string;
+    payload: unknown;
+    timestamp: number;
+    expiresAt: number;
+  }): Promise<"ok" | "missing" | "active" | "raw">;
+  gc(_now: number): Promise<number>;
+  size(): Promise<number>;
+}
+//#endregion
+export { RedisLike, RedisPushRefStore, RedisPushRefStoreOptions };

package/dist/integrations/websocket-pushref-redis.mjs

@@ -0,0 +1,205 @@
+//#region src/integrations/websocket-pushref-redis.ts
+/**
+* Lua script for atomic claim. Runs server-side, single-roundtrip.
+*
+*   KEYS[1] = key
+*   ARGV[1] = principal
+*   ARGV[2] = now (ms)
+*   ARGV[3] = ttlMs
+*   ARGV[4] = mintedJson (serialized SerializedEntry for new-claim path)
+*   ARGV[5] = graceMs (added to PEXPIRE so the broker GC's stale keys)
+*
+* Returns: { outcome, json, supersededActive } where
+*   outcome ∈ {"new","resumed","rejected"}
+*   json is the SerializedEntry (or empty string for reject)
+*   supersededActive is "1" when the previous entry was still active
+*
+* Generation handling: every resumed claim bumps `entry.generation` so
+* the connection layer can fence the previous owner. The bump happens
+* atomically inside the script — no read-modify-write race across nodes.
+*/
+const CLAIM_SCRIPT = `
+local existing = redis.call('GET', KEYS[1])
+local now = tonumber(ARGV[2])
+local ttl = tonumber(ARGV[3])
+local pexpire = ttl + tonumber(ARGV[5])
+if existing then
+  local entry = cjson.decode(existing)
+  if entry.active == false and entry.expiresAt <= now then
+    -- expired — fall through to new-claim path
+  else
+    if entry.principal ~= ARGV[1] then
+      return {'rejected', '', '0'}
+    end
+    local superseded = '0'
+    if entry.active == true then
+      superseded = '1'
+    end
+    entry.active = true
+    entry.expiresAt = now + ttl
+    entry.generation = (entry.generation or 0) + 1
+    local payload = cjson.encode(entry)
+    redis.call('SET', KEYS[1], payload, 'PX', pexpire)
+    return {'resumed', payload, superseded}
+  end
+end
+redis.call('SET', KEYS[1], ARGV[4], 'PX', pexpire)
+return {'new', ARGV[4], '0'}
+`;
+/**
+* Generation-fenced release. Single Lua roundtrip:
+*
+*   KEYS[1] = key
+*   ARGV[1] = expectedGeneration
+*   ARGV[2] = expiresAt (ms epoch)
+*   ARGV[3] = pexpire ms (relative)
+*   ARGV[4] = snapshotJson or empty string (skip envelope flush when empty)
+*
+* Returns "ok" | "stale" | "missing".
+*
+* Stale outcome means another node has claimed a higher generation
+* since the caller captured theirs — caller's release is dropped at
+* the store level. This closes the 2.17.2 race where a fenced Node A's
+* close handler could mutate Node B's freshly-claimed entry.
+*/
+const RELEASE_IF_GEN_SCRIPT = `
+local existing = redis.call('GET', KEYS[1])
+if not existing then return 'missing' end
+local entry = cjson.decode(existing)
+local expected = tonumber(ARGV[1])
+if entry.generation ~= expected then return 'stale' end
+entry.active = false
+entry.expiresAt = tonumber(ARGV[2])
+if ARGV[4] ~= '' then
+  local snap = cjson.decode(ARGV[4])
+  entry.nextSeq = snap.nextSeq
+  entry.deadQueue = snap.deadQueue
+end
+redis.call('SET', KEYS[1], cjson.encode(entry), 'PX', tonumber(ARGV[3]))
+return 'ok'
+`;
+/**
+* Atomic offline-stage. Closes the read-modify-write race the 2.17.2
+* review surfaced for `stageForResume` — a get-then-set could clobber
+* a freshly-claimed higher-generation entry with the stale inactive
+* snapshot. The whole sequence (test active + seq mode, assign seq,
+* wrap payload, append, trim, extend TTL) runs in one EVAL.
+*
+*   KEYS[1] = key
+*   ARGV[1] = payloadJson (raw payload, NOT pre-wrapped)
+*   ARGV[2] = timestamp (ms, server clock)
+*   ARGV[3] = expiresAt (ms epoch)
+*   ARGV[4] = pexpire ms
+*
+* Returns "ok" | "missing" | "active" | "raw".
+*
+* Note on JSON key order: cjson.encode and JSON.stringify may emit
+* different orderings; consumers parse the envelope and read by key,
+* so order is not part of the wire contract.
+*/
+const STAGE_IF_INACTIVE_SCRIPT = `
+local existing = redis.call('GET', KEYS[1])
+if not existing then return 'missing' end
+local entry = cjson.decode(existing)
+if entry.active then return 'active' end
+if entry.envelopeMode ~= 'seq' then return 'raw' end
+local seq = entry.nextSeq
+entry.nextSeq = seq + 1
+local payload = cjson.decode(ARGV[1])
+local envelope = { seq = seq, t = tonumber(ARGV[2]), msg = payload }
+local serialized = cjson.encode(envelope)
+if not entry.deadQueue then entry.deadQueue = {} end
+table.insert(entry.deadQueue, { seq = seq, payload = serialized })
+while #entry.deadQueue > entry.deadQueueSize do
+  table.remove(entry.deadQueue, 1)
+end
+entry.expiresAt = tonumber(ARGV[3])
+redis.call('SET', KEYS[1], cjson.encode(entry), 'PX', tonumber(ARGV[4]))
+return 'ok'
+`;
+/**
+* Generation-fenced persist. Same atomicity contract as release.
+*
+*   KEYS[1] = key
+*   ARGV[1] = expectedGeneration
+*   ARGV[2] = expiresAt
+*   ARGV[3] = pexpire ms
+*   ARGV[4] = snapshotJson (required for persist — non-empty)
+*/
+const PERSIST_IF_GEN_SCRIPT = `
+local existing = redis.call('GET', KEYS[1])
+if not existing then return 'missing' end
+local entry = cjson.decode(existing)
+local expected = tonumber(ARGV[1])
+if entry.generation ~= expected then return 'stale' end
+local snap = cjson.decode(ARGV[4])
+entry.nextSeq = snap.nextSeq
+entry.deadQueue = snap.deadQueue
+entry.expiresAt = tonumber(ARGV[2])
+redis.call('SET', KEYS[1], cjson.encode(entry), 'PX', tonumber(ARGV[3]))
+return 'ok'
+`;
+var RedisPushRefStore = class {
+	redis;
+	prefix;
+	graceMs;
+	constructor(redis, opts = {}) {
+		this.redis = redis;
+		this.prefix = opts.keyPrefix ?? "arc:pushref:";
+		this.graceMs = opts.graceMs ?? 5e3;
+	}
+	async get(pushRef) {
+		const raw = await this.redis.get(this.prefix + pushRef);
+		if (!raw) return void 0;
+		return JSON.parse(raw);
+	}
+	async set(pushRef, entry) {
+		const json = JSON.stringify(entry);
+		const pexpire = Math.max(1e3, entry.expiresAt - Date.now() + this.graceMs);
+		await this.redis.set(this.prefix + pushRef, json, "PX", pexpire);
+	}
+	async delete(pushRef) {
+		await this.redis.del(this.prefix + pushRef);
+	}
+	async claim(args) {
+		if (args.maxEntries > 0) {
+			if (await args.countNonExpired() >= args.maxEntries) {}
+		}
+		const minted = JSON.stringify(args.mintFresh());
+		const result = await this.redis.eval(CLAIM_SCRIPT, 1, this.prefix + args.pushRef, args.principal, args.now, args.ttlMs, minted, this.graceMs);
+		const outcome = result[0];
+		if (outcome === "rejected") return { outcome };
+		return {
+			outcome,
+			entry: JSON.parse(result[1]),
+			supersededActive: result[2] === "1"
+		};
+	}
+	async releaseIfGen(args) {
+		const pexpire = Math.max(1e3, args.expiresAt - Date.now() + this.graceMs);
+		return await this.redis.eval(RELEASE_IF_GEN_SCRIPT, 1, this.prefix + args.pushRef, args.expectedGeneration, args.expiresAt, pexpire, args.snapshot ? JSON.stringify(args.snapshot) : "");
+	}
+	async persistIfGen(args) {
+		const pexpire = Math.max(1e3, args.expiresAt - Date.now() + this.graceMs);
+		return await this.redis.eval(PERSIST_IF_GEN_SCRIPT, 1, this.prefix + args.pushRef, args.expectedGeneration, args.expiresAt, pexpire, JSON.stringify(args.snapshot));
+	}
+	async stageIfInactive(args) {
+		const pexpire = Math.max(1e3, args.expiresAt - Date.now() + this.graceMs);
+		return await this.redis.eval(STAGE_IF_INACTIVE_SCRIPT, 1, this.prefix + args.pushRef, JSON.stringify(args.payload), args.timestamp, args.expiresAt, pexpire);
+	}
+	async gc(_now) {
+		return 0;
+	}
+	async size() {
+		let cursor = "0";
+		let count = 0;
+		do {
+			const [next, keys] = await this.redis.scan(cursor, "MATCH", `${this.prefix}*`, "COUNT", 500);
+			count += keys.length;
+			cursor = next;
+		} while (cursor !== "0");
+		return count;
+	}
+};
+//#endregion
+export { RedisPushRefStore };

package/dist/integrations/websocket-redis.d.mts

@@ -1,4 +1,4 @@
-import { c as WebSocketAdapter } from "../websocket-BJ0w-3Dt.mjs";
+import { f as WebSocketAdapter } from "../websocket-BZMUP7Gr.mjs";
 
 //#region src/integrations/websocket-redis.d.ts
 interface RedisLike {

package/dist/integrations/websocket.d.mts

@@ -1,2 +1,3 @@
-import { a as WebSocketMessage, c as WebSocketAdapter, i as WebSocketClient, n as websocketPlugin, o as WebSocketPluginOptions, r as AuthResult, s as LocalWebSocketAdapter, t as RoomManager } from "../websocket-BJ0w-3Dt.mjs";
-export { AuthResult, LocalWebSocketAdapter, RoomManager, WebSocketAdapter, WebSocketClient, WebSocketMessage, WebSocketPluginOptions, websocketPlugin };
+import { a as GeoRoomOptions, c as WebSocketClient, d as LocalWebSocketAdapter, f as WebSocketAdapter, i as GeoRoom, l as WebSocketMessage, n as GeoPoint, o as RoomManager, r as GeoPublishOpts, s as AuthResult, t as websocketPlugin, u as WebSocketPluginOptions } from "../websocket-BZMUP7Gr.mjs";
+import { a as PushRefRegistry, c as SerializedEntry, i as Principal, o as PushRefRegistryOptions, r as MemoryPushRefStore, s as PushRefStore } from "../pushref-registry-Bq_-EVsC.mjs";
+export { AuthResult, GeoPoint, GeoPublishOpts, GeoRoom, GeoRoomOptions, LocalWebSocketAdapter, MemoryPushRefStore, Principal, PushRefRegistry, PushRefRegistryOptions, PushRefStore, RoomManager, SerializedEntry, WebSocketAdapter, WebSocketClient, WebSocketMessage, WebSocketPluginOptions, websocketPlugin };