@classytic/arc 2.17.1 → 2.18.1

package/dist/{requestContext-SSaaTgW8.mjs → requestContext-DDLS3NVU.mjs}

@@ -64,5 +64,30 @@ const requestContext = {
 	*/
 	storage
 };
+/**
+* Returns the W3C Trace Context headers (`traceparent`, `tracestate`) from
+* the current request context as a plain `Record<string, string>`, suitable
+* for passing to `OutboxWriteOptions.headers` or forwarding to downstream
+* HTTP clients.
+*
+* Returns `undefined` when called outside a request scope or when no trace
+* context was propagated by the upstream caller.
+*
+* @example
+* ```typescript
+* // Propagate trace context through the outbox so downstream consumers
+* // can stitch together distributed traces.
+* const traceHeaders = getTraceHeaders();
+* await outbox.store(event, { headers: traceHeaders });
+* ```
+*/
+function getTraceHeaders() {
+	const store = requestContext.get();
+	if (!store) return void 0;
+	const headers = {};
+	if (store.traceparent) headers["traceparent"] = store.traceparent;
+	if (store.tracestate) headers["tracestate"] = store.tracestate;
+	return Object.keys(headers).length > 0 ? headers : void 0;
+}
 //#endregion
-export { requestContext as t };
+export { requestContext as n, getTraceHeaders as t };

package/dist/{routerShared-nCyJGOKX.mjs → routerShared-Dl0A77Ba.mjs}

@@ -1,7 +1,7 @@
 import { h as SYSTEM_FIELDS } from "./constants-TrJVIJl0.mjs";
 import { f as createError, r as ForbiddenError } from "./errors-j4aJm1Wg.mjs";
 import { b as isElevated, c as getOrgId, g as getUserId, n as PUBLIC_SCOPE, x as isMember } from "./types-Bi0r0vjG.mjs";
-import { t as requestContext } from "./requestContext-SSaaTgW8.mjs";
+import { n as requestContext } from "./requestContext-DDLS3NVU.mjs";
 import { I as evaluateAndApplyPermission, M as applyFieldWritePermissions, P as resolveEffectiveRoles, j as applyFieldReadPermissions } from "./permissions-B1Qy55fg.mjs";
 import { t as getUserRoles } from "./types-DV9WDfeg.mjs";
 import { t as executePipeline } from "./pipe-DiCyvyPN.mjs";

package/dist/{schemaIR-DAOvBWgT.mjs → schemaIR-Bk6Tns82.mjs}

@@ -56,7 +56,7 @@ function normalizeSchemaIR(raw) {
 		required: []
 	};
 	const properties = converted.properties ?? {};
-	const required = Array.isArray(converted.required) ? converted.required : [];
+	const required = (Array.isArray(converted.required) ? converted.required : []).filter((field) => !("default" in (properties[field] ?? {})));
 	const additionalProperties = converted.additionalProperties;
 	return {
 		properties,
@@ -73,14 +73,26 @@ function normalizeSchemaIR(raw) {
 * reach AJV intact, so HTTP validation rejects unknown fields before the
 * handler runs. This closes the bug where the documented strict-mode
 * escape hatch silently no-opped because normalization dropped the flag.
+*
+* `default` is stripped from each property schema. Zod v4's `z.toJSONSchema()`
+* emits `default` for `.default()` fields, but AJV with `useDefaults: true`
+* cannot apply defaults inside `oneOf` branches and throws a strict-mode error
+* (`strict mode: default is ignored for: <path>`). Runtime defaults are applied
+* by Zod parsing at the handler layer anyway, so the keyword is a no-op for AJV.
+* The OpenAPI doc path uses a separate `openapi-3.0` target and is unaffected.
 */
 function schemaIRToJsonSchemaBranch(ir, extras = {}) {
+	const mergedProperties = {};
+	for (const [key, prop] of Object.entries({
+		...extras.properties ?? {},
+		...ir.properties
+	})) if (typeof prop === "object" && prop !== null && "default" in prop) {
+		const { default: _dropped, ...rest } = prop;
+		mergedProperties[key] = rest;
+	} else mergedProperties[key] = prop;
 	return {
 		type: "object",
-		properties: {
-			...extras.properties ?? {},
-			...ir.properties
-		},
+		properties: mergedProperties,
 		required: [...extras.required ?? [], ...ir.required.filter((f) => !(extras.required ?? []).includes(f))],
 		...ir.additionalProperties !== void 0 ? { additionalProperties: ir.additionalProperties } : {}
 	};

package/dist/testing/index.d.mts

@@ -1,5 +1,5 @@
-import { Kt as AnyRecord, V as ResourceDefinition } from "../index-C1JSBan-.mjs";
-import { d as preloadResourcesAsync, r as CreateAppOptions, u as preloadResources } from "../types-BRmS8TNa.mjs";
+import { Kt as AnyRecord, V as ResourceDefinition } from "../index-C000faom.mjs";
+import { d as preloadResourcesAsync, r as CreateAppOptions, u as preloadResources } from "../types-DEEWwQFR.mjs";
 import { StorageContractSetup, StorageContractSetupResult, runStorageContract } from "./storageContract.mjs";
 import { FastifyInstance, FastifyServerOptions } from "fastify";
 import { Mock } from "vitest";

package/dist/testing/index.mjs

@@ -1036,7 +1036,7 @@ function pickDefaultAuth(authMode, callerAuth) {
 	};
 }
 async function createTestApp(options = {}) {
-	const { createApp } = await import("../createApp-CzCEEsEm.mjs").then((n) => n.r);
+	const { createApp } = await import("../createApp-DZvrb587.mjs").then((n) => n.r);
 	const { resources = [], db = "in-memory", connectMongoose = false, authMode = "jwt", defaultOrgId, plugins, auth: callerAuth, ...appOptions } = options;
 	let dbHandle;
 	let dbUri;

package/dist/testing/storageContract.d.mts

@@ -1,4 +1,4 @@
-import { t as Storage } from "../storage-HcAgP5Ni.mjs";
+import { t as Storage } from "../storage-BFmamN5m.mjs";
 
 //#region src/testing/storageContract.d.ts
 interface StorageContractSetupResult {

package/dist/types/index.d.mts

@@ -1,4 +1,4 @@
-import { $ as OnTenantDeleteConfig, A as RequestIdOptions, Bt as AuthHelpers, C as RequestContext, D as HealthCheck, E as GracefulShutdownOptions, F as FastifyWithDecorators, G as ActionsMap, Gt as TokenPair, H as ActionDefinition, Ht as Authenticator, I as MiddlewareHandler, J as CrudRouteKey, Jt as ArcRequest, K as ArcFieldRule, Kt as AnyRecord, L as RequestWithExtras, M as EventsDecorator, N as FastifyRequestExtras, O as HealthOptions, P as FastifyWithAuth, Q as MiddlewareConfig, Qt as UserOrganization, S as QueryParserInterface, T as CrudRouterOptions, U as ActionEntry, Ut as AuthenticatorContext, Vt as AuthPluginOptions, W as ActionHandlerFn, Wt as JwtContext, X as EventDefinition, Xt as ObjectId, Y as CrudSchemas, Yt as JWTPayload, Z as FieldRule, Zt as UserLike, _ as ControllerQueryOptions, _t as FastifyHandler, a as InferAdapterDoc, at as ResolvedTenantPurge, b as ParsedQuery, bt as IRequestContext, c as TypedController, cn as BaseControllerOptions, ct as ResourceHookContext, d as PaginationResult, dt as RouteDefinition, et as OpenApiSchemas, f as IntrospectionData, ft as RouteMcpConfig, g as ArcInternalMetadata, gt as ControllerLike, h as ResourceMetadata, ht as ControllerHandler, i as ValidationResult, it as RateLimitConfig, j as ArcDecorator, k as IntrospectionPluginOptions, l as TypedRepository, lt as ResourceHooks, m as RegistryStats, mt as RouteSchemaOptions, n as ConfigError, nt as PresetHook, o as InferDocType, ot as ResourceCacheConfig, p as RegistryEntry, pt as RouteMethod, q as CrudController, qt as ApiResponse, r as ValidateOptions, rt as PresetResult, s as InferResourceDoc, st as ResourceConfig, t as RouteHandlerMethod, tt as PresetFunction, u as TypedResourceConfig, ut as ResourcePermissions, v as LookupOption, vt as IController, w as ServiceContext, x as PopulateOption, xt as RouteHandler, y as OwnershipCheck, yt as IControllerResponse } from "../index-C1JSBan-.mjs";
+import { $ as OnTenantDeleteConfig, A as RequestIdOptions, Bt as AuthHelpers, C as RequestContext, D as HealthCheck, E as GracefulShutdownOptions, F as FastifyWithDecorators, G as ActionsMap, Gt as TokenPair, H as ActionDefinition, Ht as Authenticator, I as MiddlewareHandler, J as CrudRouteKey, Jt as ArcRequest, K as ArcFieldRule, Kt as AnyRecord, L as RequestWithExtras, M as EventsDecorator, N as FastifyRequestExtras, O as HealthOptions, P as FastifyWithAuth, Q as MiddlewareConfig, Qt as UserOrganization, S as QueryParserInterface, T as CrudRouterOptions, U as ActionEntry, Ut as AuthenticatorContext, Vt as AuthPluginOptions, W as ActionHandlerFn, Wt as JwtContext, X as EventDefinition, Xt as ObjectId, Y as CrudSchemas, Yt as JWTPayload, Z as FieldRule, Zt as UserLike, _ as ControllerQueryOptions, _t as FastifyHandler, a as InferAdapterDoc, at as ResolvedTenantPurge, b as ParsedQuery, bt as IRequestContext, c as TypedController, cn as BaseControllerOptions, ct as ResourceHookContext, d as PaginationResult, dt as RouteDefinition, et as OpenApiSchemas, f as IntrospectionData, ft as RouteMcpConfig, g as ArcInternalMetadata, gt as ControllerLike, h as ResourceMetadata, ht as ControllerHandler, i as ValidationResult, it as RateLimitConfig, j as ArcDecorator, k as IntrospectionPluginOptions, l as TypedRepository, lt as ResourceHooks, m as RegistryStats, mt as RouteSchemaOptions, n as ConfigError, nt as PresetHook, o as InferDocType, ot as ResourceCacheConfig, p as RegistryEntry, pt as RouteMethod, q as CrudController, qt as ApiResponse, r as ValidateOptions, rt as PresetResult, s as InferResourceDoc, st as ResourceConfig, t as RouteHandlerMethod, tt as PresetFunction, u as TypedResourceConfig, ut as ResourcePermissions, v as LookupOption, vt as IController, w as ServiceContext, x as PopulateOption, xt as RouteHandler, y as OwnershipCheck, yt as IControllerResponse } from "../index-C000faom.mjs";
 import { i as RequestScope } from "../types-CfapW2t8.mjs";
 import { c as PermissionCheck, d as UserBase, l as PermissionContext, u as PermissionResult } from "../fields-DqZLp5d6.mjs";
 import { n as ElevationOptions, t as ElevationEvent } from "../elevation-DvwtjDwu.mjs";

package/dist/types/storage.d.mts

@@ -1,2 +1,2 @@
-import { a as StorageReadResult, i as StorageReadRange, n as StorageContext, o as StorageUploadInput, r as StorageFile, t as Storage } from "../storage-HcAgP5Ni.mjs";
+import { a as StorageReadResult, i as StorageReadRange, n as StorageContext, o as StorageUploadInput, r as StorageFile, t as Storage } from "../storage-BFmamN5m.mjs";
 export { Storage, StorageContext, StorageFile, StorageReadRange, StorageReadResult, StorageUploadInput };

package/dist/{types-BRmS8TNa.d.mts → types-DEEWwQFR.d.mts}

@@ -1,5 +1,5 @@
 import { r as CacheStore } from "./interface-BVkZsvEe.mjs";
-import { Ht as Authenticator } from "./index-C1JSBan-.mjs";
+import { Ht as Authenticator } from "./index-C000faom.mjs";
 import { n as ElevationOptions } from "./elevation-DvwtjDwu.mjs";
 import { a as EventTransport } from "./EventTransport-B1GFiYUy.mjs";
 import { t as ExternalOpenApiPaths } from "./externalPaths-ClykOQqa.mjs";

package/dist/{types-CoMjNmkF.d.mts → types-DH-7WO64.d.mts}

@@ -1,4 +1,4 @@
-import { V as ResourceDefinition } from "./index-C1JSBan-.mjs";
+import { V as ResourceDefinition } from "./index-C000faom.mjs";
 import { z } from "zod";
 
 //#region src/integrations/mcp/types.d.ts

package/dist/utils/index.d.mts

@@ -1,4 +1,4 @@
-import { Kt as AnyRecord, S as QueryParserInterface, Zt as UserLike, b as ParsedQuery, et as OpenApiSchemas, st as ResourceConfig } from "../index-C1JSBan-.mjs";
+import { Kt as AnyRecord, S as QueryParserInterface, Zt as UserLike, b as ParsedQuery, et as OpenApiSchemas, st as ResourceConfig } from "../index-C000faom.mjs";
 import { n as ErrorMapper } from "../errorHandler-DuqTqeqn.mjs";
 import { a as NotFoundError, c as RateLimitError, d as ValidationError, f as createDomainError, i as ForbiddenError, l as ServiceUnavailableError, m as isArcError, n as ConflictError, o as OrgAccessDeniedError, p as createError, r as ErrorOptions, s as OrgRequiredError, t as ArcError, u as UnauthorizedError } from "../errors-4ZloYFvm.mjs";
 import { errorContractSchema, errorDetailSchema } from "@classytic/repo-core/errors";

package/dist/websocket-BZMUP7Gr.d.mts

@@ -0,0 +1,456 @@
+import { a as PushRefRegistry, l as EnvelopeWriter, s as PushRefStore } from "./pushref-registry-Bq_-EVsC.mjs";
+import { FastifyBaseLogger, FastifyPluginAsync } from "fastify";
+
+//#region src/integrations/websocket/adapter.d.ts
+/**
+ * WebSocket cross-instance adapter contract.
+ *
+ * The adapter is NOT used for local broadcasts — `RoomManager` handles those.
+ * The adapter only handles the cross-instance relay (Redis pub/sub, NATS, etc.)
+ * so a message broadcast on instance A is also delivered to clients connected
+ * to instance B.
+ *
+ * Implementations:
+ *   - `LocalWebSocketAdapter` (here) — no-op, single-instance only
+ *   - `RedisWebSocketAdapter` (@classytic/arc/integrations/websocket-redis)
+ *
+ * Custom adapters just need to satisfy the interface.
+ */
+/**
+ * Adapter interface for cross-instance WebSocket broadcast.
+ *
+ * - `publish()`: Send a message to all instances (via Redis, NATS, etc.)
+ * - `subscribe()`: Receive messages from other instances
+ * - `close()`: Clean up connections
+ */
+interface WebSocketAdapter {
+  /** Adapter name for logging */
+  readonly name: string;
+  /** Publish a room broadcast to all other instances */
+  publish(room: string, message: string): Promise<void>;
+  /** Subscribe to broadcasts from other instances */
+  subscribe(callback: (room: string, message: string) => void): Promise<void>;
+  /** Close adapter connections */
+  close(): Promise<void>;
+}
+/**
+ * Default adapter — no cross-instance broadcast (single-instance only).
+ * All methods are no-ops. Used when no adapter is configured.
+ */
+declare class LocalWebSocketAdapter implements WebSocketAdapter {
+  readonly name = "local";
+  publish(): Promise<void>;
+  subscribe(): Promise<void>;
+  close(): Promise<void>;
+}
+//#endregion
+//#region src/integrations/websocket/safe-async.d.ts
+type SafeAsyncLogger = Pick<FastifyBaseLogger, "warn">;
+//#endregion
+//#region src/integrations/websocket/send-queue.d.ts
+interface SendQueueSocket {
+  send(data: string): void;
+  readyState: number;
+  bufferedAmount?: number;
+  terminate?(): void;
+  close?(code?: number, reason?: string): void;
+}
+interface SendQueueOptions {
+  capacity?: number;
+  drainThreshold?: number;
+  /** Auto-flush retry delay in ms when backpressure pauses draining. */
+  retryDelayMs?: number;
+}
+/**
+ * Per-socket bounded queue. Construct one per accepted connection;
+ * `dispose()` on socket close to drop refs.
+ */
+declare class SendQueue {
+  private entries;
+  /** `coalesceKey → entries[] index` for O(1) replacement. */
+  private coalesceIndex;
+  private socket;
+  private capacity;
+  private drainThreshold;
+  private retryDelayMs;
+  /** One-shot retry timer set while waiting for backpressure to clear. */
+  private retryTimer?;
+  private disposed;
+  constructor(socket: SendQueueSocket, opts?: SendQueueOptions);
+  /** Ordered, guaranteed-best-effort delivery. Overflow ⇒ terminate. */
+  send(payload: string): void;
+  /**
+   * Fire-and-forget, droppable. With `coalesceKey`, older entry for the
+   * same key is replaced in place (preserves queue order, keeps latest
+   * payload). Without a key, oldest droppable entry is shed on overflow.
+   */
+  sendRealtime(payload: string, coalesceKey?: string): void;
+  /**
+   * Drain entries to the socket until either the queue empties or the
+   * socket's outbound buffer crosses the drain threshold. Idempotent —
+   * also runs on a self-scheduled retry timer when backpressure pauses
+   * draining (so callers never need to manually re-prod the queue).
+   */
+  flush(): void;
+  size(): number;
+  dispose(): void;
+  /**
+   * One-shot retry timer. Called when `flush()` hits backpressure and
+   * leaves entries queued — without this, queued frames would stall
+   * indefinitely after the socket's buffer drains, because nothing
+   * else prods the queue. The timer self-clears on each fire so a
+   * single delay is the worst case between drain and resume.
+   */
+  private scheduleRetry;
+  private terminate;
+  /** Rebuild the coalesce index from `start` onward after a splice/shift. */
+  private reindexCoalesceFrom;
+}
+//#endregion
+//#region src/integrations/websocket/types.d.ts
+/**
+ * A connected WebSocket client — one entry per TCP socket.
+ *
+ * `subscriptions` is mutated by `RoomManager`; other fields are set once at
+ * handshake time and treated as effectively immutable for the lifetime of
+ * the connection.
+ */
+interface WebSocketClient {
+  /**
+   * Transport-level connection ID (one per TCP socket). Stable for the
+   * lifetime of THIS connection only — a reconnect mints a new `id`.
+   */
+  id: string;
+  /**
+   * Session reference — stable across reconnects, distinct from `userId`.
+   * One user with three browser tabs = three `pushRef`s, one `userId`.
+   * Routing layer keys off this for "send to THIS tab" semantics.
+   *
+   * Clients MAY supply their own pushRef via the `?pushRef=` query param
+   * on the upgrade URL (e.g. resumed reconnect); otherwise the server mints
+   * one at handshake time.
+   */
+  pushRef: string;
+  socket: {
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    readyState: number;
+    bufferedAmount?: number; /** RFC 6455 §5.5.2 ping control frame. Browsers auto-respond at the protocol layer. */
+    ping?(data?: unknown): void; /** Immediate socket destroy — no Close frame, no flush. Use for zombies. */
+    terminate?(): void;
+  };
+  subscriptions: Set<string>;
+  userId?: string;
+  organizationId?: string;
+  /** OAuth client ID — present for service/machine-to-machine connections */
+  clientId?: string;
+  /** OAuth scopes — present for service/machine-to-machine connections */
+  scopes?: readonly string[];
+  metadata?: Record<string, unknown>;
+  /**
+   * Outbound send queue — created at connect time, disposed on close.
+   * `RoomManager.send/sendRealtime` enqueue via this; the raw
+   * `client.socket.send()` path bypasses queue/coalesce/overflow policy
+   * and should only be used for the connection-lifecycle handshake.
+   */
+  queue?: SendQueue;
+  /**
+   * Sequence-numbered envelope writer + dead queue. Present iff the
+   * plugin was started with `messageEnvelope: 'seq'`. Critical sends are
+   * wrapped via this so the client can RESUME after reconnect.
+   */
+  envelope?: EnvelopeWriter;
+  /**
+   * Connection generation captured at claim time. The fence + CAS
+   * write paths use this — every release/persist passes it so the
+   * store can refuse stale writes from a connection that's been
+   * superseded by a newer claim on another node.
+   */
+  generation: number;
+}
+interface WebSocketMessage {
+  type: string;
+  resource?: string;
+  channel?: string;
+  data?: unknown;
+}
+/**
+ * Result of a successful authentication. The plugin's handshake and the
+ * optional re-auth loop both return this shape so the downstream code
+ * doesn't branch on auth mode. `null` means rejected.
+ */
+interface AuthResult {
+  userId?: string;
+  organizationId?: string;
+  /** Set for machine-to-machine / service account auth */
+  clientId?: string;
+  /** OAuth scopes for service accounts */
+  scopes?: readonly string[];
+}
+interface WebSocketPluginOptions {
+  /** WebSocket endpoint path (default: '/ws') */
+  path?: string;
+  /** Require authentication for WebSocket connections (default: true) */
+  auth?: boolean;
+  /** Resources to auto-broadcast CRUD events for */
+  resources?: string[];
+  /** Heartbeat interval in ms (default: 30000). Set 0 to disable. */
+  heartbeatInterval?: number;
+  /** Custom authentication function for WebSocket upgrade */
+  authenticate?: (request: unknown) => Promise<AuthResult | null>;
+  /** Max clients per resource subscription (default: 10000) */
+  maxClientsPerRoom?: number;
+  /**
+   * Expose a stats endpoint at `{path}/stats`.
+   * - `false` (default): stats endpoint is not registered
+   * - `true`: registered without auth
+   * - `'authenticated'`: guarded by `fastify.authenticate` if available
+   */
+  exposeStats?: boolean | "authenticated";
+  /**
+   * Authorize room subscriptions. Return true to allow, false to deny.
+   * Called before every subscribe. If not provided, all rooms are allowed.
+   */
+  roomPolicy?: (client: WebSocketClient, room: string) => boolean | Promise<boolean>;
+  /** Maximum message size in bytes from client (default: 16384 = 16KB). Messages exceeding this are dropped. */
+  maxMessageBytes?: number;
+  /** Maximum subscriptions per client (default: 100). Prevents resource exhaustion. */
+  maxSubscriptionsPerClient?: number;
+  /**
+   * Periodic re-authentication interval in ms (default: 0 = disabled).
+   * When set, the server periodically re-validates the client's auth token.
+   * If the token is expired/revoked, the client is disconnected with code 4003.
+   *
+   * Recommended: 300000 (5 minutes) for production.
+   *
+   * @example
+   * ```typescript
+   * websocketPlugin({ reauthInterval: 5 * 60 * 1000 }) // re-check every 5 min
+   * ```
+   */
+  reauthInterval?: number;
+  /** Custom message handler */
+  onMessage?: (client: WebSocketClient, message: WebSocketMessage) => void | Promise<void>;
+  /** Called when a client connects */
+  onConnect?: (client: WebSocketClient) => void | Promise<void>;
+  /** Called when a client disconnects */
+  onDisconnect?: (client: WebSocketClient) => void | Promise<void>;
+  /**
+   * Cross-instance broadcast adapter (default: LocalWebSocketAdapter — single-instance only).
+   * Provide a RedisWebSocketAdapter for multi-instance deployments.
+   *
+   * @example
+   * ```typescript
+   * import { RedisWebSocketAdapter } from '@classytic/arc/integrations/websocket-redis';
+   * adapter: new RedisWebSocketAdapter(redis, { channel: 'arc-ws' })
+   * ```
+   */
+  adapter?: WebSocketAdapter;
+  /**
+   * Outbound message wire format.
+   *   - `'raw'` (default): write payloads as-is — no envelope, no replay.
+   *   - `'seq'`: wrap every critical send in `{seq, t, msg}`. The dead
+   *     queue of the last N envelopes is owned by the **PushRefRegistry**
+   *     (per-pushRef / per-session, NOT per-connection) so a client
+   *     reconnecting under the same pushRef within `pushRefTtlMs` can
+   *     RESUME via `{type:'resume', lastSeq}` and replay missed messages
+   *     across the disconnect — not just within a single socket.
+   *
+   * Opt-in to preserve compatibility with existing clients. Set to
+   * `'seq'` for chat, ride-status, payment flows — anything where a
+   * message lost mid-disconnect is a real bug.
+   */
+  messageEnvelope?: "raw" | "seq";
+  /** Dead queue size (per pushRef) when `messageEnvelope: 'seq'`. Defaults to 128. */
+  deadQueueSize?: number;
+  /**
+   * Time (ms) a released pushRef stays in the registry waiting for a
+   * reconnect to RESUME against its envelope + dead queue. Past this
+   * window the entry is GC'd. Default `60_000` (60 s) — typical mobile
+   * lock-screen + carrier-handoff reconnect window.
+   */
+  pushRefTtlMs?: number;
+  /**
+   * Hard cap on pushRef registry entries. When full, the longest-inactive
+   * entry is evicted to make room. Default `10_000` — sized for a single
+   * Node process supporting tens of thousands of concurrent users with
+   * tab-level granularity.
+   */
+  pushRefMaxEntries?: number;
+  /**
+   * Maximum bytes per outbound frame. Payloads exceeding this are
+   * replaced with a `{type:'truncated', originalBytes, hint}` placeholder
+   * so a misbehaving server-side emitter can't pin socket buffers across
+   * the fleet. Default `5 * 1024 * 1024` (5 MiB) — same as n8n's
+   * `relayViaPubSub` ceiling. Hosts may tighten for low-bandwidth tiers.
+   */
+  maxOutboundBytes?: number;
+  /**
+   * Optional external store for cross-instance pushRef state. When
+   * provided, the envelope + dead queue survive reconnects to ANY node
+   * in the cluster (not just the originator). See
+   * `@classytic/arc/integrations/websocket-pushref-redis` for the
+   * Redis-backed implementation.
+   *
+   * Without this, the in-memory registry is per-process — fine for
+   * single-node deployments OR sticky-session load balancing, but a
+   * client reconnecting through a different node loses dead-queue
+   * state.
+   */
+  pushRefStore?: PushRefStore;
+}
+//#endregion
+//#region src/integrations/websocket/room-manager.d.ts
+declare class RoomManager {
+  private rooms;
+  private clients;
+  /**
+   * Secondary index: `pushRef → clientId`. A pushRef is stable across
+   * reconnects (one per browser tab/device), where `clientId` is per-socket.
+   * Lets the host send to a logical session ("this tab") without caring
+   * which TCP connection currently backs it.
+   */
+  private clientIdByPushRef;
+  /**
+   * Tertiary index: `userId → Set<clientId>`. Lets `sendToUser(userId, msg)`
+   * fan out to every open tab/device for that user without scanning the
+   * full client set.
+   */
+  private clientIdsByUserId;
+  private maxPerRoom;
+  private adapter?;
+  private registry?;
+  private logger;
+  constructor(maxPerRoom?: number, adapter?: WebSocketAdapter, registry?: PushRefRegistry, logger?: SafeAsyncLogger);
+  addClient(client: WebSocketClient): void;
+  removeClient(clientId: string): void;
+  /** Resolve a pushRef to its current backing client, if any. */
+  getClientByPushRef(pushRef: string): WebSocketClient | undefined;
+  /** Snapshot of all clients currently owned by `userId`. */
+  getClientsByUserId(userId: string): WebSocketClient[];
+  subscribe(clientId: string, room: string): boolean;
+  unsubscribe(clientId: string, room: string): void;
+  broadcast(room: string, message: string, excludeClientId?: string): void;
+  /**
+   * Droppable, coalesce-by-key broadcast to a room. Mirrors `broadcast()`
+   * but routes through each client's `SendQueue.sendRealtime` so high-
+   * frequency streams (GPS, cursors, presence) collapse to one queued
+   * frame per recipient.
+   *
+   * Used by `GeoRoom.publish` for hyperlocal fan-out where the latest
+   * snapshot is the only one that matters.
+   */
+  broadcastRealtime(room: string, message: string, coalesceKey: string): void;
+  broadcastToOrg(organizationId: string, room: string, message: string): void;
+  /**
+   * Broadcast locally AND through adapter (for cross-instance delivery).
+   * Use this instead of broadcast() when multi-instance is possible.
+   */
+  broadcastWithAdapter(room: string, message: string, excludeClientId?: string): Promise<void>;
+  /**
+   * Org-scoped broadcast locally AND through adapter.
+   * Uses a namespaced room key for the adapter so other instances
+   * can filter by org when delivering locally.
+   */
+  broadcastToOrgWithAdapter(organizationId: string, room: string, message: string): Promise<void>;
+  /**
+   * Addressed sends across instances. Wire format reuses the existing
+   * room-prefix convention (`pushref:<id>`, `userid:<id>`) so the adapter
+   * interface stays unchanged. Receiver-side plugin code dispatches on the
+   * prefix and calls `sendToPushRef` / `sendToUser` locally.
+   *
+   * Critical guarantee (n8n shouldRelayViaPubSub pattern): the local call
+   * is a no-op on every instance EXCEPT the one that owns the pushRef —
+   * the address lookup itself is the ownership check.
+   */
+  sendToPushRefWithAdapter(pushRef: string, message: string): Promise<void>;
+  sendRealtimeToPushRefWithAdapter(pushRef: string, message: string, coalesceKey?: string): Promise<void>;
+  sendToUserWithAdapter(userId: string, message: string): Promise<void>;
+  sendRealtimeToUserWithAdapter(userId: string, message: string, coalesceKey?: string): Promise<void>;
+  /** Ordered send to a single pushRef. Returns true if delivered/queued. */
+  sendToPushRef(pushRef: string, message: string): boolean;
+  /** Droppable send to a single pushRef. */
+  sendRealtimeToPushRef(pushRef: string, message: string, coalesceKey?: string): boolean;
+  /**
+   * Ordered fan-out to every open connection for `userId` (all tabs/devices).
+   * Returns the count successfully queued.
+   */
+  sendToUser(userId: string, message: string): number;
+  /** Droppable fan-out to every open connection for `userId`. */
+  sendRealtimeToUser(userId: string, message: string, coalesceKey?: string): number;
+  private deliver;
+  getClient(clientId: string): WebSocketClient | undefined;
+  getStats(): {
+    clients: number;
+    rooms: number;
+    subscriptions: Record<string, number>;
+  };
+}
+//#endregion
+//#region src/integrations/websocket/geo-room.d.ts
+interface GeoRoomOptions {
+  /** H3 resolution. 9 ≈ 100 m edge (ride-hailing default); 10 ≈ 40 m. */
+  resolution?: number;
+  /**
+   * Room-key prefix so geo-rooms don't collide with arbitrary topic names.
+   * Defaults to `geo:`. Resulting room: `geo:<h3cell>`.
+   */
+  prefix?: string;
+}
+interface GeoPoint {
+  lat: number;
+  lng: number;
+}
+interface GeoPublishOpts {
+  /** k-ring radius — `0` = just the cell, `1` = cell + 6 neighbors, etc. */
+  ring?: number;
+  /**
+   * Coalesce key for queue-side keep-latest-snapshot. Defaults to the
+   * client's pushRef so a driver streaming 5 Hz GPS collapses to one
+   * queued frame per recipient.
+   */
+  coalesceKey?: string;
+  /**
+   * Delivery class. `'droppable'` (default) routes through `sendRealtime`
+   * — correct for high-frequency location streams. `'critical'` routes
+   * through `send` — use sparingly for dispatch events like "ride accepted".
+   */
+  delivery?: "droppable" | "critical";
+}
+/**
+ * A geo-aware subscription layer on top of `RoomManager`. Construct one
+ * per logical channel (e.g. one for `drivers`, one for `couriers`) so
+ * resolutions and prefixes don't cross-contaminate.
+ */
+declare class GeoRoom {
+  private rooms;
+  private resolution;
+  private prefix;
+  private h3?;
+  constructor(rooms: RoomManager, opts?: GeoRoomOptions);
+  /** Subscribe a client to every cell within `ring` of `point`. */
+  subscribe(clientId: string, point: GeoPoint, opts?: {
+    ring?: number;
+  }): Promise<string[]>;
+  /** Symmetric — unsubscribe from every cell within `ring`. */
+  unsubscribe(clientId: string, point: GeoPoint, opts?: {
+    ring?: number;
+  }): Promise<void>;
+  /**
+   * Publish to every client subscribed to a cell within `ring` of `point`.
+   * Droppable by default — every recipient queue keeps only the latest
+   * per `coalesceKey` (defaults to the publisher's pushRef).
+   */
+  publish(publisher: {
+    pushRef: string;
+  }, point: GeoPoint, payload: string, opts?: GeoPublishOpts): Promise<void>;
+  /** Compute the cell ID for a point without subscribing — useful for tests. */
+  cellFor(point: GeoPoint): Promise<string>;
+  private h3lib;
+}
+//#endregion
+//#region src/integrations/websocket/plugin.d.ts
+/** Pluggable WebSocket integration for Arc */
+declare const websocketPlugin: FastifyPluginAsync<WebSocketPluginOptions>;
+//#endregion
+export { GeoRoomOptions as a, WebSocketClient as c, LocalWebSocketAdapter as d, WebSocketAdapter as f, GeoRoom as i, WebSocketMessage as l, GeoPoint as n, RoomManager as o, GeoPublishOpts as r, AuthResult as s, websocketPlugin as t, WebSocketPluginOptions as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc",
-  "version": "2.17.1",
+  "version": "2.18.1",
   "description": "Resource-oriented backend framework for Fastify - clean, minimal, powerful, tree-shakable",
   "type": "module",
   "exports": {
@@ -156,6 +156,10 @@
       "types": "./dist/integrations/websocket-redis.d.mts",
       "default": "./dist/integrations/websocket-redis.mjs"
     },
+    "./integrations/websocket-pushref-redis": {
+      "types": "./dist/integrations/websocket-pushref-redis.d.mts",
+      "default": "./dist/integrations/websocket-pushref-redis.mjs"
+    },
     "./integrations/jobs": {
       "types": "./dist/integrations/jobs.d.mts",
       "default": "./dist/integrations/jobs.mjs"
@@ -227,6 +231,8 @@
     "test:coverage": "vitest run --coverage",
     "test:e2e": "vitest run tests/e2e",
     "test:unit": "vitest run tests/core tests/hooks tests/utils tests/plugins",
+    "test:smoke:ws": "vitest run tests/integrations/websocket/smoke.test.ts",
+    "test:smoke:redis": "node scripts/smoke-ws-redis.mjs",
     "smoke": "node scripts/smoke-test.mjs",
     "push": "classytic-push",
     "release:tag": "node -e \"require('child_process').execSync('npm run push -- v'+require('./package.json').version,{stdio:'inherit'})\"",
@@ -261,6 +267,7 @@
     "bullmq": ">=5.0.0",
     "fastify": "^5.8.5",
     "fastify-raw-body": ">=5.0.0",
+    "h3-js": ">=4.0.0",
     "ioredis": ">=5.0.0",
     "pino-pretty": ">=13.0.0",
     "zod": ">=4.0.0"
@@ -296,6 +303,9 @@
     "fastify-raw-body": {
       "optional": true
     },
+    "h3-js": {
+      "optional": true
+    },
     "pino-pretty": {
       "optional": true
     },
@@ -378,6 +388,7 @@
     "fast-check": "^4.8.0",
     "fastify": "^5.8.5",
     "fastify-raw-body": "^5.0.0",
+    "h3-js": "^4.4.0",
     "ioredis": "^5.10.1",
     "jsonwebtoken": "^9.0.0",
     "knip": "^6.14.1",