@classytic/arc 2.17.0 → 2.18.0

package/dist/integrations/websocket.mjs

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import sjson from "secure-json-parse";
 import fp from "fastify-plugin";
 //#region src/integrations/websocket/adapter.ts
@@ -12,6 +13,87 @@ var LocalWebSocketAdapter = class {
 	async close() {}
 };
 //#endregion
+//#region src/integrations/websocket/geo-room.ts
+let h3Cached;
+async function loadH3() {
+	if (h3Cached) return h3Cached;
+	try {
+		const mod = await import("h3-js");
+		const merged = {
+			...mod.default ?? {},
+			...mod
+		};
+		if (typeof merged.latLngToCell !== "function" || typeof merged.gridDisk !== "function") throw new Error("h3-js missing latLngToCell / gridDisk exports");
+		h3Cached = merged;
+		return h3Cached;
+	} catch {
+		throw new Error("[arc-websocket] geo-room support requires h3-js.\nInstall it: npm install h3-js");
+	}
+}
+/**
+* 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.
+*/
+var GeoRoom = class {
+	rooms;
+	resolution;
+	prefix;
+	h3;
+	constructor(rooms, opts = {}) {
+		this.rooms = rooms;
+		this.resolution = opts.resolution ?? 9;
+		this.prefix = opts.prefix ?? "geo:";
+	}
+	/** Subscribe a client to every cell within `ring` of `point`. */
+	async subscribe(clientId, point, opts = {}) {
+		const h3 = await this.h3lib();
+		const ring = opts.ring ?? 1;
+		const center = h3.latLngToCell(point.lat, point.lng, this.resolution);
+		const cells = h3.gridDisk(center, ring);
+		const rooms = [];
+		for (const cell of cells) {
+			const room = `${this.prefix}${cell}`;
+			if (this.rooms.subscribe(clientId, room)) rooms.push(room);
+		}
+		return rooms;
+	}
+	/** Symmetric — unsubscribe from every cell within `ring`. */
+	async unsubscribe(clientId, point, opts = {}) {
+		const h3 = await this.h3lib();
+		const ring = opts.ring ?? 1;
+		const center = h3.latLngToCell(point.lat, point.lng, this.resolution);
+		const cells = h3.gridDisk(center, ring);
+		for (const cell of cells) this.rooms.unsubscribe(clientId, `${this.prefix}${cell}`);
+	}
+	/**
+	* 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).
+	*/
+	async publish(publisher, point, payload, opts = {}) {
+		const h3 = await this.h3lib();
+		const ring = opts.ring ?? 1;
+		const center = h3.latLngToCell(point.lat, point.lng, this.resolution);
+		const cells = h3.gridDisk(center, ring);
+		const coalesceKey = opts.coalesceKey ?? publisher.pushRef;
+		const delivery = opts.delivery ?? "droppable";
+		for (const cell of cells) {
+			const room = `${this.prefix}${cell}`;
+			if (delivery === "critical") this.rooms.broadcast(room, payload);
+			else this.rooms.broadcastRealtime(room, payload, coalesceKey);
+		}
+	}
+	/** Compute the cell ID for a point without subscribing — useful for tests. */
+	async cellFor(point) {
+		return (await this.h3lib()).latLngToCell(point.lat, point.lng, this.resolution);
+	}
+	async h3lib() {
+		if (!this.h3) this.h3 = await loadH3();
+		return this.h3;
+	}
+};
+//#endregion
 //#region src/integrations/websocket/auth.ts
 function createCaptureReply() {
 	let rejected = false;
@@ -77,8 +159,653 @@ function readIdField(obj, key) {
 	const value = obj[key];
 	return typeof value === "string" ? value : void 0;
 }
+var DeadQueue = class {
+	buffer;
+	head = 0;
+	count = 0;
+	capacity;
+	constructor(capacity = 128) {
+		this.capacity = capacity;
+		this.buffer = new Array(capacity);
+	}
+	push(entry) {
+		this.buffer[this.head] = entry;
+		this.head = (this.head + 1) % this.capacity;
+		if (this.count < this.capacity) this.count++;
+	}
+	/**
+	* Return entries with seq strictly greater than `lastSeq`, in order,
+	* OR `null` if the gap is too large (entry with seq = lastSeq + 1 has
+	* already been evicted from the ring — caller should signal `resume_gap`).
+	*/
+	drainAfter(lastSeq) {
+		if (this.count === 0) return [];
+		const tail = (this.head - this.count + this.capacity) % this.capacity;
+		const oldest = this.buffer[tail];
+		if (!oldest) return [];
+		if (oldest.seq > lastSeq + 1) return null;
+		const out = [];
+		for (let i = 0; i < this.count; i++) {
+			const idx = (tail + i) % this.capacity;
+			const e = this.buffer[idx];
+			if (e && e.seq > lastSeq) out.push(e);
+		}
+		return out;
+	}
+	size() {
+		return this.count;
+	}
+	/** Highest seq currently in the ring (or 0 if empty). */
+	highestSeq() {
+		if (this.count === 0) return 0;
+		const lastIdx = (this.head - 1 + this.capacity) % this.capacity;
+		return this.buffer[lastIdx]?.seq ?? 0;
+	}
+	clear() {
+		this.buffer = new Array(this.capacity);
+		this.head = 0;
+		this.count = 0;
+	}
+	/**
+	* Return all entries in chronological order. Used by the registry's
+	* `persist()` to flush the live ring to the external store. Allocates
+	* a fresh array — caller owns it (mutations don't affect the ring).
+	*/
+	snapshot() {
+		if (this.count === 0) return [];
+		const tail = (this.head - this.count + this.capacity) % this.capacity;
+		const out = [];
+		for (let i = 0; i < this.count; i++) {
+			const idx = (tail + i) % this.capacity;
+			const e = this.buffer[idx];
+			if (e) out.push(e);
+		}
+		return out;
+	}
+};
+//#endregion
+//#region src/integrations/websocket/envelope.ts
+/**
+* Per-pushRef envelope state. One instance per logical session — when
+* a client reconnects under the same pushRef within TTL, the same
+* EnvelopeWriter is rehydrated so its `nextSeq` counter and dead queue
+* round-trip across reconnects.
+*
+* The constructor accepts `{ nextSeq }` for the rehydration path —
+* `PushRefRegistry.hydrateEnvelope` passes the persisted counter so
+* the next wrap() picks up where the previous socket left off (no
+* seq collisions, no replay gaps).
+*/
+var EnvelopeWriter = class {
+	nextSeq;
+	dead;
+	constructor(deadQueue, opts = {}) {
+		this.dead = deadQueue;
+		this.nextSeq = opts.nextSeq ?? 1;
+	}
+	/**
+	* Wrap a payload, assign next seq, persist to dead queue. Returns the
+	* JSON-stringified envelope ready for the socket.
+	*/
+	wrap(payload) {
+		const seq = this.nextSeq++;
+		const serialized = JSON.stringify({
+			seq,
+			t: Date.now(),
+			msg: payload
+		});
+		this.dead.push({
+			seq,
+			payload: serialized
+		});
+		return serialized;
+	}
+	/**
+	* Replay entries strictly greater than `lastSeq`. Returns either the
+	* array of payloads to write, OR `null` if the gap is unrecoverable
+	* (caller emits `resume_gap`).
+	*/
+	drainAfter(lastSeq) {
+		const entries = this.dead.drainAfter(lastSeq);
+		if (entries === null) return null;
+		return entries.map((e) => e.payload);
+	}
+	highestSeq() {
+		return this.dead.highestSeq();
+	}
+	/** Peek the next sequence to be assigned (without consuming). */
+	peekNextSeq() {
+		return this.nextSeq;
+	}
+	/** Snapshot the dead queue contents for persistence. */
+	snapshotDeadQueue() {
+		return this.dead.snapshot();
+	}
+};
+//#endregion
+//#region src/integrations/websocket/pushref-registry.ts
+/**
+* PushRef registry — owns the cross-connection state that has to outlive
+* a single TCP socket: the per-pushRef envelope writer + dead queue
+* (PR 3), and the principal binding that prevents another authenticated
+* user from hijacking a pushRef.
+*
+* Single-instance default: state lives in an in-memory `Map`. Same
+* shape as the original single-class registry — but the public surface
+* is **async** so a Redis-backed store can plug in without touching
+* connection.ts.
+*
+* Cross-instance: pass a `PushRefStore` (e.g. the Redis-backed one
+* from `@classytic/arc/integrations/websocket-pushref-redis`). The
+* envelope + principal binding then survive node-to-node reconnects —
+* a client originating on Node A and reconnecting to Node B picks up
+* the same dead queue and replays missed envelopes.
+*
+* Why every method returns a Promise even when the default store is
+* synchronous: making the API async-uniform means the connection
+* lifecycle code is identical for memory vs Redis. The microtask
+* overhead on the hot path is in the nanoseconds — negligible next
+* to the network I/O the Redis store actually does.
+*
+* Atomicity contract: `claim()` MUST be atomic relative to other
+* `claim()` calls on the same pushRef. The in-memory store gets this
+* for free (single-threaded event loop). Redis stores MUST use a
+* Lua script or WATCH/MULTI/EXEC to test-and-set the principal.
+*/
+/**
+* Default in-memory store — the previous single-instance registry's
+* behavior, repackaged behind the `PushRefStore` interface so the
+* registry layer doesn't care whether it's local or distributed.
+*
+* All methods are technically synchronous but return promises to
+* conform to the interface. Cost: one microtask per call. Negligible.
+*/
+var MemoryPushRefStore = class {
+	entries = /* @__PURE__ */ new Map();
+	async get(pushRef) {
+		return this.entries.get(pushRef);
+	}
+	async set(pushRef, entry) {
+		this.entries.set(pushRef, entry);
+	}
+	async delete(pushRef) {
+		this.entries.delete(pushRef);
+	}
+	async claim(args) {
+		const existing = this.entries.get(args.pushRef);
+		if (existing) if (!existing.active && existing.expiresAt <= args.now) this.entries.delete(args.pushRef);
+		else {
+			if (existing.principal !== args.principal) return { outcome: "rejected" };
+			const supersededActive = existing.active === true;
+			existing.active = true;
+			existing.expiresAt = args.now + args.ttlMs;
+			existing.generation = (existing.generation ?? 0) + 1;
+			this.entries.set(args.pushRef, existing);
+			return {
+				outcome: "resumed",
+				entry: existing,
+				supersededActive
+			};
+		}
+		if (this.entries.size >= args.maxEntries && !this.evictOldestInactive()) return { outcome: "rejected" };
+		const fresh = args.mintFresh();
+		this.entries.set(args.pushRef, fresh);
+		return {
+			outcome: "new",
+			entry: fresh
+		};
+	}
+	async releaseIfGen(args) {
+		const entry = this.entries.get(args.pushRef);
+		if (!entry) return "missing";
+		if (entry.generation !== args.expectedGeneration) return "stale";
+		entry.active = false;
+		entry.expiresAt = args.expiresAt;
+		if (args.snapshot) {
+			entry.nextSeq = args.snapshot.nextSeq;
+			entry.deadQueue = args.snapshot.deadQueue;
+		}
+		this.entries.set(args.pushRef, entry);
+		return "ok";
+	}
+	async persistIfGen(args) {
+		const entry = this.entries.get(args.pushRef);
+		if (!entry) return "missing";
+		if (entry.generation !== args.expectedGeneration) return "stale";
+		entry.nextSeq = args.snapshot.nextSeq;
+		entry.deadQueue = args.snapshot.deadQueue;
+		entry.expiresAt = args.expiresAt;
+		this.entries.set(args.pushRef, entry);
+		return "ok";
+	}
+	async stageIfInactive(args) {
+		const entry = this.entries.get(args.pushRef);
+		if (!entry) return "missing";
+		if (entry.active) return "active";
+		if (entry.envelopeMode !== "seq") return "raw";
+		const seq = entry.nextSeq;
+		entry.nextSeq = seq + 1;
+		const serialized = JSON.stringify({
+			seq,
+			t: args.timestamp,
+			msg: args.payload
+		});
+		entry.deadQueue.push({
+			seq,
+			payload: serialized
+		});
+		if (entry.deadQueue.length > entry.deadQueueSize) entry.deadQueue = entry.deadQueue.slice(-entry.deadQueueSize);
+		entry.expiresAt = args.expiresAt;
+		this.entries.set(args.pushRef, entry);
+		return "ok";
+	}
+	async gc(now) {
+		let removed = 0;
+		for (const [k, v] of this.entries) if (!v.active && v.expiresAt <= now) {
+			this.entries.delete(k);
+			removed++;
+		}
+		return removed;
+	}
+	async size() {
+		return this.entries.size;
+	}
+	/** Test-only inspection — not in the PushRefStore interface. */
+	inspect(pushRef) {
+		return this.entries.get(pushRef);
+	}
+	evictOldestInactive() {
+		let oldestKey;
+		let oldestTime = Infinity;
+		for (const [k, v] of this.entries) if (!v.active && v.expiresAt < oldestTime) {
+			oldestTime = v.expiresAt;
+			oldestKey = k;
+		}
+		if (oldestKey === void 0) return false;
+		this.entries.delete(oldestKey);
+		return true;
+	}
+};
+/**
+* Registry — the high-level interface connection.ts calls. Owns the
+* envelope-mint policy (envelope writers are LIVE objects with mutable
+* dead queues — they can't be reconstructed from a serialized snapshot
+* exactly because the `nextSeq` counter and ring buffer must round-trip
+* with full fidelity).
+*
+* The hot path:
+*
+*   1. `claim(pushRef, principal, deadQueueSize)` resolves the
+*      cross-connection state. On `new`, an EnvelopeWriter is minted
+*      around a fresh DeadQueue. On `resumed`, the EnvelopeWriter is
+*      reconstructed from the persisted nextSeq + deadQueue contents.
+*
+*   2. The connection lifecycle calls `release()` on close — starts the
+*      TTL countdown.
+*
+*   3. `stageForResume()` writes a payload into the orphan envelope
+*      when no live socket is attached (the offline-send path).
+*
+*   4. `persist()` flushes the in-memory EnvelopeWriter back to the
+*      store after each write — keeps the store in sync so a reconnect
+*      to a different node sees the latest dead queue. For the memory
+*      store this is a no-op; for Redis it's a HMSET write.
+*/
+var PushRefRegistry = class {
+	store;
+	ttlMs;
+	maxEntries;
+	now;
+	/**
+	* Live envelope writers indexed by pushRef. Stays in sync with the
+	* store via persist() after every wrap(). On `claim('resumed')`,
+	* rehydrated from the store's snapshot.
+	*/
+	liveEnvelopes = /* @__PURE__ */ new Map();
+	constructor(opts = {}) {
+		this.store = opts.store ?? new MemoryPushRefStore();
+		this.ttlMs = opts.ttlMs ?? 6e4;
+		this.maxEntries = opts.maxEntries ?? 1e4;
+		this.now = opts.now ?? Date.now;
+	}
+	async claim(pushRef, principal, opts) {
+		const now = this.now();
+		const result = await this.store.claim({
+			pushRef,
+			principal,
+			now,
+			ttlMs: this.ttlMs,
+			maxEntries: this.maxEntries,
+			countNonExpired: () => this.store.size(),
+			mintFresh: () => ({
+				principal,
+				nextSeq: 1,
+				deadQueue: [],
+				expiresAt: now + this.ttlMs,
+				active: true,
+				envelopeMode: opts.envelopeMode,
+				deadQueueSize: opts.deadQueueSize,
+				generation: 1
+			})
+		});
+		if (result.outcome === "rejected") return {
+			outcome: "rejected",
+			reason: "principal_mismatch"
+		};
+		if (!result.entry) return {
+			outcome: "rejected",
+			reason: "principal_mismatch"
+		};
+		const generation = result.entry.generation ?? 1;
+		const envelope = opts.envelopeMode === "seq" ? this.hydrateEnvelope(pushRef, result.entry) : void 0;
+		if (result.outcome === "new") return {
+			outcome: "new",
+			envelope,
+			generation
+		};
+		return {
+			outcome: "resumed",
+			envelope,
+			generation,
+			supersededActive: result.supersededActive === true
+		};
+	}
+	/**
+	* Mark the connection inactive (TTL countdown starts). Caller MUST
+	* pass the generation they captured at claim time — the store does
+	* a compare-and-set and silently no-ops if the entry has since been
+	* superseded by a higher-generation claim (i.e. another node took
+	* ownership while our close handler was pending).
+	*
+	* This closes the race the 2.17.2 review surfaced: previously, a
+	* stale release could overwrite Node B's freshly-claimed entry with
+	* Node A's outdated snapshot.
+	*
+	* Returns the outcome for callers that want to log fenced writes.
+	*/
+	async release(pushRef, expectedGeneration) {
+		const env = this.liveEnvelopes.get(pushRef);
+		const snapshot = env ? {
+			nextSeq: env.peekNextSeq(),
+			deadQueue: env.snapshotDeadQueue()
+		} : void 0;
+		const outcome = await this.store.releaseIfGen({
+			pushRef,
+			expectedGeneration,
+			...snapshot ? { snapshot } : {},
+			expiresAt: this.now() + this.ttlMs
+		});
+		this.liveEnvelopes.delete(pushRef);
+		return outcome;
+	}
+	async evict(pushRef) {
+		await this.store.delete(pushRef);
+		this.liveEnvelopes.delete(pushRef);
+	}
+	/**
+	* Stage a payload into the orphan envelope when no live socket is
+	* attached. Atomic — routes through `store.stageIfInactive` which
+	* does the read + wrap + write under a single Lua EVAL (Redis) or
+	* synchronous event-loop turn (Memory). This closes the 2.17.2
+	* stage-vs-claim race where a get-then-set could overwrite a freshly
+	* claimed higher-generation entry with the stale inactive snapshot.
+	*
+	* Returns `true` only when the payload was actually staged. `false`
+	* for any of:
+	*   - entry missing (unknown / GC'd pushRef)
+	*   - entry is currently active (route via room manager instead)
+	*   - envelope mode is `'raw'` (no dead queue to stage into)
+	*/
+	async stageForResume(pushRef, payload) {
+		return await this.store.stageIfInactive({
+			pushRef,
+			payload,
+			timestamp: this.now(),
+			expiresAt: this.now() + this.ttlMs
+		}) === "ok";
+	}
+	/**
+	* Generation-fenced persist. Called by the room-manager hook after
+	* every wrap() so the persisted snapshot stays in sync with the live
+	* envelope. Caller passes the connection's generation; a stale
+	* persist (after the connection was fenced) silently no-ops at the
+	* store level — never overwrites the newer owner's state.
+	*
+	* Returns the outcome for callers that want to log fenced writes.
+	*/
+	async persist(pushRef, expectedGeneration) {
+		const env = this.liveEnvelopes.get(pushRef);
+		if (!env) return "missing";
+		return this.store.persistIfGen({
+			pushRef,
+			expectedGeneration,
+			snapshot: {
+				nextSeq: env.peekNextSeq(),
+				deadQueue: env.snapshotDeadQueue()
+			},
+			expiresAt: this.now() + this.ttlMs
+		});
+	}
+	async size() {
+		return this.store.size();
+	}
+	async gc() {
+		return this.store.gc(this.now());
+	}
+	async close() {
+		this.liveEnvelopes.clear();
+		await this.store.close?.();
+	}
+	/** Diagnostics — read-only. */
+	async inspect(pushRef) {
+		return this.store.get(pushRef);
+	}
+	/** Reconstruct an EnvelopeWriter from a persisted snapshot. */
+	hydrateEnvelope(pushRef, entry) {
+		const existing = this.liveEnvelopes.get(pushRef);
+		if (existing) return existing;
+		const dq = new DeadQueue(entry.deadQueueSize);
+		for (const e of entry.deadQueue) dq.push(e);
+		const writer = new EnvelopeWriter(dq, { nextSeq: entry.nextSeq });
+		this.liveEnvelopes.set(pushRef, writer);
+		return writer;
+	}
+};
+/**
+* Derive a stable principal string from a connection's identity. Used
+* as the pushRef binding key — two connections sharing a principal can
+* resume each other's pushRef state.
+*
+* Returns:
+*   - `'u:<userId>'`         — interactive user session
+*   - `'c:<clientId>'`       — service / machine-to-machine
+*   - `'anon'`               — auth disabled (dev / test)
+*   - **`null`**             — auth ENABLED but no stable identity
+*                              (org-only credentials, etc.) — caller
+*                              MUST refuse URL pushRef claims and mint
+*                              a connection-bound fresh binding.
+*/
+function derivePrincipal(args) {
+	if (args.userId) return `u:${args.userId}`;
+	if (args.clientId) return `c:${args.clientId}`;
+	if (!args.authMode) return "anon";
+	return null;
+}
+//#endregion
+//#region src/integrations/websocket/safe-async.ts
+function safeAsync(p, logger, op, ctx) {
+	p.catch((err) => {
+		logger.warn({
+			err,
+			op,
+			...ctx
+		}, `[arc-websocket] async op failed: ${op}`);
+	});
+}
+/**
+* Per-socket bounded queue. Construct one per accepted connection;
+* `dispose()` on socket close to drop refs.
+*/
+var SendQueue = class {
+	entries = [];
+	/** `coalesceKey → entries[] index` for O(1) replacement. */
+	coalesceIndex = /* @__PURE__ */ new Map();
+	socket;
+	capacity;
+	drainThreshold;
+	retryDelayMs;
+	/** One-shot retry timer set while waiting for backpressure to clear. */
+	retryTimer;
+	disposed = false;
+	constructor(socket, opts = {}) {
+		this.socket = socket;
+		this.capacity = opts.capacity ?? 256;
+		this.drainThreshold = opts.drainThreshold ?? 262144;
+		this.retryDelayMs = opts.retryDelayMs ?? 50;
+	}
+	/** Ordered, guaranteed-best-effort delivery. Overflow ⇒ terminate. */
+	send(payload) {
+		if (this.disposed) return;
+		if (this.entries.length >= this.capacity) {
+			this.terminate("Queue overflow");
+			return;
+		}
+		this.entries.push({
+			payload,
+			cls: "critical"
+		});
+		this.flush();
+	}
+	/**
+	* 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, coalesceKey) {
+		if (this.disposed) return;
+		if (coalesceKey !== void 0) {
+			const idx = this.coalesceIndex.get(coalesceKey);
+			if (idx !== void 0 && this.entries[idx]) {
+				this.entries[idx] = {
+					payload,
+					cls: "droppable",
+					coalesceKey
+				};
+				this.flush();
+				return;
+			}
+		}
+		if (this.entries.length >= this.capacity) {
+			const shedIdx = this.entries.findIndex((e) => e.cls === "droppable");
+			if (shedIdx === -1) return;
+			const evicted = this.entries.splice(shedIdx, 1)[0];
+			if (evicted?.coalesceKey !== void 0) this.coalesceIndex.delete(evicted.coalesceKey);
+			this.reindexCoalesceFrom(shedIdx);
+		}
+		this.entries.push({
+			payload,
+			cls: "droppable",
+			coalesceKey
+		});
+		if (coalesceKey !== void 0) this.coalesceIndex.set(coalesceKey, this.entries.length - 1);
+		this.flush();
+	}
+	/**
+	* 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() {
+		if (this.disposed) return;
+		while (this.entries.length > 0 && this.socket.readyState === 1) {
+			if ((this.socket.bufferedAmount ?? 0) >= this.drainThreshold) {
+				this.scheduleRetry();
+				return;
+			}
+			const entry = this.entries.shift();
+			if (!entry) return;
+			if (entry.coalesceKey !== void 0) this.coalesceIndex.delete(entry.coalesceKey);
+			if (this.coalesceIndex.size > 0) this.reindexCoalesceFrom(0);
+			try {
+				this.socket.send(entry.payload);
+			} catch {
+				return;
+			}
+		}
+	}
+	size() {
+		return this.entries.length;
+	}
+	dispose() {
+		this.disposed = true;
+		this.entries.length = 0;
+		this.coalesceIndex.clear();
+		if (this.retryTimer) {
+			clearTimeout(this.retryTimer);
+			this.retryTimer = void 0;
+		}
+	}
+	/**
+	* 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.
+	*/
+	scheduleRetry() {
+		if (this.retryTimer !== void 0 || this.disposed) return;
+		this.retryTimer = setTimeout(() => {
+			this.retryTimer = void 0;
+			this.flush();
+		}, this.retryDelayMs);
+		this.retryTimer.unref?.();
+	}
+	terminate(reason) {
+		this.dispose();
+		if (typeof this.socket.terminate === "function") this.socket.terminate();
+		else if (typeof this.socket.close === "function") this.socket.close(1011, reason);
+	}
+	/** Rebuild the coalesce index from `start` onward after a splice/shift. */
+	reindexCoalesceFrom(start) {
+		for (let i = start; i < this.entries.length; i++) {
+			const k = this.entries[i]?.coalesceKey;
+			if (k !== void 0) this.coalesceIndex.set(k, i);
+		}
+	}
+};
 //#endregion
 //#region src/integrations/websocket/connection.ts
+/**
+* Per-connection lifecycle handler.
+*
+* Runs for every WebSocket upgrade accepted by the plugin's Fastify route.
+* Orchestrates the 5-phase lifecycle:
+*
+*   1. authenticate (handshake)     → accept or close(4001)
+*   2. register client, fire onConnect
+*   3. start heartbeat + reauth timers
+*   4. wire message handler (subscribe / unsubscribe / pong / custom)
+*   5. cleanup on close/error (clear timers, fire onDisconnect, remove from rooms)
+*
+* Keeps the plugin orchestrator (`plugin.ts`) thin — it just wires options,
+* creates a `RoomManager`, subscribes to the event bus, and hands each
+* connection off to `handleConnection`.
+*
+* The `socket` / `request` parameter types are `unknown`-boxed because
+* @fastify/websocket isn't a typecheck-time dependency. The shapes used
+* are documented inline.
+*/
+/** Extract a client-supplied pushRef from the upgrade URL, if any. */
+function readPushRefFromRequest(request) {
+	const req = request;
+	const fromQuery = req?.query?.pushRef;
+	if (typeof fromQuery === "string" && fromQuery.length > 0 && fromQuery.length <= 128) return fromQuery;
+	if (req?.url) try {
+		const v = new URL(req.url, "http://x").searchParams.get("pushRef");
+		if (v && v.length > 0 && v.length <= 128) return v;
+	} catch {}
+}
 async function handleConnection(ctx, socket, request) {
 	const { fastify, rooms, options } = ctx;
 	const clientId = ctx.nextClientId();
@@ -97,28 +824,108 @@ async function handleConnection(ctx, socket, request) {
 		serviceClientId = result.clientId;
 		serviceScopes = result.scopes;
 	}
+	const principal = derivePrincipal({
+		userId,
+		clientId: serviceClientId,
+		authMode: options.auth
+	});
+	options.messageEnvelope;
+	const urlPushRef = readPushRefFromRequest(request);
+	let pushRef;
+	let envelope;
+	let resumed = false;
+	/**
+	* Connection generation — monotonic per-pushRef counter the registry
+	* bumps on every claim. Used by the fence path: after we claim with
+	* a higher generation than any prior live owner, we publish
+	* `fence:<pushRef>` so OTHER nodes close their stale socket too.
+	*/
+	let generation = 1;
+	let supersededActive = false;
+	const claimOpts = {
+		envelopeMode: options.messageEnvelope,
+		deadQueueSize: options.deadQueueSize
+	};
+	if (principal === null) {
+		pushRef = `ps_${randomUUID()}`;
+		const fresh = await ctx.pushRefRegistry.claim(pushRef, `conn:${pushRef}`, claimOpts);
+		if (fresh.outcome === "rejected") {
+			socket.close(1011, "pushRef registry capacity");
+			return;
+		}
+		envelope = fresh.envelope;
+		if (fresh.outcome === "new" || fresh.outcome === "resumed") generation = fresh.generation;
+	} else if (urlPushRef !== void 0) {
+		const claim = await ctx.pushRefRegistry.claim(urlPushRef, principal, claimOpts);
+		if (claim.outcome === "rejected") {
+			pushRef = `ps_${randomUUID()}`;
+			const fresh = await ctx.pushRefRegistry.claim(pushRef, principal, claimOpts);
+			if (fresh.outcome === "rejected") {
+				socket.close(1011, "pushRef registry capacity");
+				return;
+			}
+			envelope = fresh.envelope;
+			if (fresh.outcome === "new" || fresh.outcome === "resumed") generation = fresh.generation;
+		} else {
+			pushRef = urlPushRef;
+			envelope = claim.envelope;
+			resumed = claim.outcome === "resumed";
+			generation = claim.generation;
+			if (claim.outcome === "resumed") supersededActive = claim.supersededActive;
+		}
+	} else {
+		pushRef = `ps_${randomUUID()}`;
+		const fresh = await ctx.pushRefRegistry.claim(pushRef, principal, claimOpts);
+		if (fresh.outcome === "rejected") {
+			socket.close(1011, "pushRef registry capacity");
+			return;
+		}
+		envelope = fresh.envelope;
+		if (fresh.outcome === "new" || fresh.outcome === "resumed") generation = fresh.generation;
+	}
+	if (supersededActive) {
+		const stale = rooms.getClientByPushRef(pushRef);
+		if (stale && stale.socket !== socket) stale.socket.close(4011, "Superseded by newer connection");
+		ctx.fence?.(pushRef, generation);
+	}
+	const queue = new SendQueue(socket);
 	const client = {
 		id: clientId,
+		pushRef,
 		socket,
 		subscriptions: /* @__PURE__ */ new Set(),
 		userId,
 		organizationId,
 		...serviceClientId ? { clientId: serviceClientId } : {},
-		...serviceScopes ? { scopes: serviceScopes } : {}
+		...serviceScopes ? { scopes: serviceScopes } : {},
+		queue,
+		...envelope ? { envelope } : {},
+		generation
 	};
 	rooms.addClient(client);
 	await options.onConnect?.(client);
 	socket.send(JSON.stringify({
 		type: "connected",
 		clientId,
-		resources: options.resources
+		pushRef,
+		resources: options.resources,
+		...envelope ? { envelope: "seq" } : {},
+		...resumed ? { resumed: true } : {}
 	}));
 	let heartbeatTimer;
+	let isAlive = true;
+	socket.on("pong", () => {
+		isAlive = true;
+	});
 	if (options.heartbeatInterval > 0) heartbeatTimer = setInterval(() => {
-		if (socket.readyState === 1) socket.send(JSON.stringify({
-			type: "ping",
-			timestamp: Date.now()
-		}));
+		if (socket.readyState !== 1) return;
+		if (!isAlive) {
+			if (typeof socket.terminate === "function") socket.terminate();
+			else socket.close(4008, "Heartbeat timeout");
+			return;
+		}
+		isAlive = false;
+		if (typeof socket.ping === "function") socket.ping();
 	}, options.heartbeatInterval);
 	let reauthTimer;
 	if (options.reauthInterval > 0 && options.auth) reauthTimer = setInterval(async () => {
@@ -190,7 +997,34 @@ async function handleConnection(ctx, socket, request) {
 				}
 				break;
 			}
-			case "pong": break;
+			case "resume": {
+				const raw = msg;
+				const lastSeq = typeof raw.lastSeq === "number" ? raw.lastSeq : -1;
+				if (!envelope) {
+					socket.send(JSON.stringify({
+						type: "resumed",
+						lastSeq,
+						replayed: 0
+					}));
+					break;
+				}
+				const replay = envelope.drainAfter(lastSeq);
+				if (replay === null) {
+					socket.send(JSON.stringify({
+						type: "resume_gap",
+						lastSeq,
+						highestSeq: envelope.highestSeq()
+					}));
+					break;
+				}
+				for (const payload of replay) socket.send(payload);
+				socket.send(JSON.stringify({
+					type: "resumed",
+					lastSeq,
+					replayed: replay.length
+				}));
+				break;
+			}
 			default:
 				await options.onMessage?.(client, msg);
 				break;
@@ -199,13 +1033,25 @@ async function handleConnection(ctx, socket, request) {
 	socket.on("close", async () => {
 		if (heartbeatTimer) clearInterval(heartbeatTimer);
 		if (reauthTimer) clearInterval(reauthTimer);
-		await options.onDisconnect?.(client);
-		rooms.removeClient(clientId);
+		if (rooms.getClient(clientId)?.socket === socket) {
+			await options.onDisconnect?.(client);
+			rooms.removeClient(clientId);
+		}
+		queue.dispose();
+		if (!rooms.getClientByPushRef(pushRef)) safeAsync(ctx.pushRefRegistry.release(pushRef, generation), fastify.log, "registry.release", {
+			pushRef,
+			generation
+		});
 	});
 	socket.on("error", () => {
 		if (heartbeatTimer) clearInterval(heartbeatTimer);
 		if (reauthTimer) clearInterval(reauthTimer);
-		rooms.removeClient(clientId);
+		if (rooms.getClient(clientId)?.socket === socket) rooms.removeClient(clientId);
+		queue.dispose();
+		if (!rooms.getClientByPushRef(pushRef)) safeAsync(ctx.pushRefRegistry.release(pushRef, generation), fastify.log, "registry.release", {
+			pushRef,
+			generation
+		});
 	});
 }
 //#endregion
@@ -269,18 +1115,105 @@ function registerStatsRoute(fastify, rooms, path, expose) {
 	} else fastify.log.warn("arc-websocket: exposeStats is \"authenticated\" but fastify.authenticate is not registered — stats endpoint skipped");
 }
 //#endregion
+//#region src/integrations/websocket/outbound-truncate.ts
+/**
+* Outbound payload truncation — mirrors n8n's pattern of capping any
+* single server→client frame at a sane upper bound, replacing oversize
+* payloads with a placeholder envelope the client knows to handle.
+*
+* The 2.17.2 review (NEW-LOW) flagged that an earlier draft used a
+* module-global cap mutated by `resetMaxOutboundBytes(maxOutboundBytes)`
+* at plugin construction. Two simultaneous plugin registrations with
+* different caps would surprise the host (last-write-wins). The
+* current shape is purely instance-scoped: every plugin instance owns
+* its own `truncate` closure, callers pass the cap at the call site.
+*
+*   - `truncateOutbound(json, max)` — cheap byte check; returns the
+*     placeholder JSON when oversize.
+*
+*   - `createTruncator(max)` — convenience: returns a function bound
+*     to a specific cap. The plugin holds one of these per registered
+*     instance, eliminating module state.
+*/
+/** 5 MiB default — same as n8n's `relayViaPubSub` ceiling. */
+const DEFAULT_MAX_OUTBOUND_BYTES = 5 * 1024 * 1024;
+/**
+* Returns either the original payload (when within `max`) or a
+* placeholder JSON string (when oversize). The placeholder carries the
+* original size so the client can surface a meaningful error / retry.
+*
+* Byte length is measured via Buffer.byteLength (UTF-8) — same metric
+* the underlying WebSocket frame uses for the payload-length header.
+*/
+function truncateOutbound(payload, max = DEFAULT_MAX_OUTBOUND_BYTES) {
+	const bytes = Buffer.byteLength(payload, "utf8");
+	if (bytes <= max) return payload;
+	return JSON.stringify({
+		type: "truncated",
+		originalBytes: bytes,
+		maxBytes: max,
+		hint: "Server-side payload exceeded the outbound cap. Refetch via REST or narrow your subscription filter."
+	});
+}
+/**
+* Bind a cap into a closure — the plugin uses one of these per
+* registered instance so no module state crosses plugin boundaries.
+* Hosts running two WebSocket plugins with different caps get the
+* exact cap each one declared, not last-writer-wins.
+*/
+function createTruncator(max = DEFAULT_MAX_OUTBOUND_BYTES) {
+	return (payload) => truncateOutbound(payload, max);
+}
+//#endregion
 //#region src/integrations/websocket/room-manager.ts
+/**
+* RoomManager — subscription bookkeeping for the WebSocket plugin.
+*
+* Every connected client lives in zero or more "rooms" (resource channels,
+* arbitrary topic names). The manager indexes in both directions:
+*   - `rooms: room → Set<clientId>` for fan-out
+*   - `clients: clientId → WebSocketClient` for lookup + cleanup
+*
+* Local broadcast delivers to sockets on THIS instance; adapter-aware
+* variants also publish through the optional cross-instance adapter so
+* other instances fan out to their local sockets.
+*/
+/** Drop fan-out to a client whose outbound buffer exceeds this threshold. */
+const WS_BACKPRESSURE_LIMIT = 256 * 1024;
 var RoomManager = class {
 	rooms = /* @__PURE__ */ new Map();
 	clients = /* @__PURE__ */ new Map();
+	/**
+	* 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.
+	*/
+	clientIdByPushRef = /* @__PURE__ */ new Map();
+	/**
+	* 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.
+	*/
+	clientIdsByUserId = /* @__PURE__ */ new Map();
 	maxPerRoom;
 	adapter;
-	constructor(maxPerRoom = 1e4, adapter) {
+	registry;
+	logger = { warn: () => {} };
+	constructor(maxPerRoom = 1e4, adapter, registry, logger) {
 		this.maxPerRoom = maxPerRoom;
 		this.adapter = adapter;
+		this.registry = registry;
+		if (logger) this.logger = logger;
 	}
 	addClient(client) {
 		this.clients.set(client.id, client);
+		this.clientIdByPushRef.set(client.pushRef, client.id);
+		if (client.userId) {
+			const set = this.clientIdsByUserId.get(client.userId) ?? /* @__PURE__ */ new Set();
+			set.add(client.id);
+			this.clientIdsByUserId.set(client.userId, set);
+		}
 	}
 	removeClient(clientId) {
 		const client = this.clients.get(clientId);
@@ -292,9 +1225,33 @@ var RoomManager = class {
 				if (members.size === 0) this.rooms.delete(room);
 			}
 		}
+		if (this.clientIdByPushRef.get(client.pushRef) === clientId) this.clientIdByPushRef.delete(client.pushRef);
+		if (client.userId) {
+			const set = this.clientIdsByUserId.get(client.userId);
+			if (set) {
+				set.delete(clientId);
+				if (set.size === 0) this.clientIdsByUserId.delete(client.userId);
+			}
+		}
 		client.subscriptions.clear();
 		this.clients.delete(clientId);
 	}
+	/** Resolve a pushRef to its current backing client, if any. */
+	getClientByPushRef(pushRef) {
+		const id = this.clientIdByPushRef.get(pushRef);
+		return id ? this.clients.get(id) : void 0;
+	}
+	/** Snapshot of all clients currently owned by `userId`. */
+	getClientsByUserId(userId) {
+		const ids = this.clientIdsByUserId.get(userId);
+		if (!ids) return [];
+		const out = [];
+		for (const id of ids) {
+			const c = this.clients.get(id);
+			if (c) out.push(c);
+		}
+		return out;
+	}
 	subscribe(clientId, room) {
 		const client = this.clients.get(clientId);
 		if (!client) return false;
@@ -318,10 +1275,37 @@ var RoomManager = class {
 	broadcast(room, message, excludeClientId) {
 		const members = this.rooms.get(room);
 		if (!members) return;
+		const dead = [];
 		for (const clientId of members) {
 			if (clientId === excludeClientId) continue;
 			const client = this.clients.get(clientId);
-			if (client && client.socket.readyState === 1) try {
+			if (!client || client.socket.readyState !== 1) continue;
+			if ((client.socket.bufferedAmount ?? 0) > WS_BACKPRESSURE_LIMIT) continue;
+			try {
+				client.socket.send(message);
+			} catch {
+				dead.push(clientId);
+			}
+		}
+		for (const id of dead) this.removeClient(id);
+	}
+	/**
+	* 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, message, coalesceKey) {
+		const members = this.rooms.get(room);
+		if (!members) return;
+		for (const clientId of members) {
+			const client = this.clients.get(clientId);
+			if (!client || client.socket.readyState !== 1) continue;
+			if (client.queue) client.queue.sendRealtime(message, coalesceKey);
+			else if ((client.socket.bufferedAmount ?? 0) <= WS_BACKPRESSURE_LIMIT) try {
 				client.socket.send(message);
 			} catch {}
 		}
@@ -329,12 +1313,18 @@ var RoomManager = class {
 	broadcastToOrg(organizationId, room, message) {
 		const members = this.rooms.get(room);
 		if (!members) return;
+		const dead = [];
 		for (const clientId of members) {
 			const client = this.clients.get(clientId);
-			if (client && client.organizationId === organizationId && client.socket.readyState === 1) try {
+			if (!client || client.organizationId !== organizationId || client.socket.readyState !== 1) continue;
+			if ((client.socket.bufferedAmount ?? 0) > WS_BACKPRESSURE_LIMIT) continue;
+			try {
 				client.socket.send(message);
-			} catch {}
+			} catch {
+				dead.push(clientId);
+			}
 		}
+		for (const id of dead) this.removeClient(id);
 	}
 	/**
 	* Broadcast locally AND through adapter (for cross-instance delivery).
@@ -353,6 +1343,84 @@ var RoomManager = class {
 		this.broadcastToOrg(organizationId, room, message);
 		if (this.adapter) await this.adapter.publish(`org:${organizationId}:${room}`, message);
 	}
+	/**
+	* 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.
+	*/
+	async sendToPushRefWithAdapter(pushRef, message) {
+		this.sendToPushRef(pushRef, message);
+		if (this.adapter) await this.adapter.publish(`pushref:${pushRef}`, message);
+	}
+	async sendRealtimeToPushRefWithAdapter(pushRef, message, coalesceKey) {
+		this.sendRealtimeToPushRef(pushRef, message, coalesceKey);
+		if (this.adapter) await this.adapter.publish(`pushref-rt:${pushRef}`, message);
+	}
+	async sendToUserWithAdapter(userId, message) {
+		this.sendToUser(userId, message);
+		if (this.adapter) await this.adapter.publish(`userid:${userId}`, message);
+	}
+	async sendRealtimeToUserWithAdapter(userId, message, coalesceKey) {
+		this.sendRealtimeToUser(userId, message, coalesceKey);
+		if (this.adapter) await this.adapter.publish(`userid-rt:${userId}`, message);
+	}
+	/** Ordered send to a single pushRef. Returns true if delivered/queued. */
+	sendToPushRef(pushRef, message) {
+		const c = this.getClientByPushRef(pushRef);
+		return c ? this.deliver(c, message, "critical") : false;
+	}
+	/** Droppable send to a single pushRef. */
+	sendRealtimeToPushRef(pushRef, message, coalesceKey) {
+		const c = this.getClientByPushRef(pushRef);
+		return c ? this.deliver(c, message, "droppable", coalesceKey) : false;
+	}
+	/**
+	* Ordered fan-out to every open connection for `userId` (all tabs/devices).
+	* Returns the count successfully queued.
+	*/
+	sendToUser(userId, message) {
+		let n = 0;
+		for (const c of this.getClientsByUserId(userId)) if (this.deliver(c, message, "critical")) n++;
+		return n;
+	}
+	/** Droppable fan-out to every open connection for `userId`. */
+	sendRealtimeToUser(userId, message, coalesceKey) {
+		let n = 0;
+		for (const c of this.getClientsByUserId(userId)) if (this.deliver(c, message, "droppable", coalesceKey)) n++;
+		return n;
+	}
+	deliver(client, message, cls, coalesceKey) {
+		if (client.socket.readyState !== 1) return false;
+		const queue = client.queue;
+		if (queue) {
+			if (cls === "critical") if (client.envelope) try {
+				const parsed = JSON.parse(message);
+				queue.send(client.envelope.wrap(parsed));
+				if (this.registry) safeAsync(this.registry.persist(client.pushRef, client.generation), this.logger, "registry.persist", {
+					pushRef: client.pushRef,
+					generation: client.generation
+				});
+			} catch {
+				queue.send(message);
+			}
+			else queue.send(message);
+			else queue.sendRealtime(message, coalesceKey);
+			return true;
+		}
+		if ((client.socket.bufferedAmount ?? 0) > WS_BACKPRESSURE_LIMIT) return false;
+		try {
+			client.socket.send(message);
+			return true;
+		} catch {
+			this.removeClient(client.id);
+			return false;
+		}
+	}
 	getClient(clientId) {
 		return this.clients.get(clientId);
 	}
@@ -369,9 +1437,21 @@ var RoomManager = class {
 //#endregion
 //#region src/integrations/websocket/plugin.ts
 const websocketPluginImpl = async (fastify, options) => {
-	const { path = "/ws", auth = true, resources = [], heartbeatInterval = 3e4, authenticate: customAuth, maxClientsPerRoom = 1e4, roomPolicy, maxMessageBytes = 16384, maxSubscriptionsPerClient = 100, reauthInterval = 0, adapter, exposeStats = false, onMessage, onConnect, onDisconnect } = options;
+	const { path = "/ws", auth = true, resources = [], heartbeatInterval = 3e4, authenticate: customAuth, maxClientsPerRoom = 1e4, roomPolicy, maxMessageBytes = 16384, maxSubscriptionsPerClient = 100, reauthInterval = 0, adapter, exposeStats = false, onMessage, onConnect, onDisconnect, messageEnvelope = "raw", deadQueueSize = 128, pushRefTtlMs = 6e4, pushRefMaxEntries = 1e4, maxOutboundBytes = DEFAULT_MAX_OUTBOUND_BYTES } = options;
+	const truncate = createTruncator(maxOutboundBytes);
+	if (!fastify.hasDecorator("websocketServer")) try {
+		const wsPlugin = await import("@fastify/websocket");
+		await fastify.register(wsPlugin.default ?? wsPlugin);
+	} catch {
+		throw new Error("[arc-websocket] WebSocket support requires @fastify/websocket.\nInstall it: npm install @fastify/websocket");
+	}
 	if (auth && !customAuth && !fastify.hasDecorator("authenticate")) throw new Error("[arc-websocket] auth is true but fastify.authenticate is not registered. Register an auth plugin before WebSocket, provide a custom authenticate function, or set auth: false.");
-	const rooms = new RoomManager(maxClientsPerRoom, adapter ?? new LocalWebSocketAdapter());
+	const pushRefRegistry = new PushRefRegistry({
+		ttlMs: pushRefTtlMs,
+		maxEntries: pushRefMaxEntries,
+		...options.pushRefStore ? { store: options.pushRefStore } : {}
+	});
+	const rooms = new RoomManager(maxClientsPerRoom, adapter ?? new LocalWebSocketAdapter(), pushRefRegistry, fastify.log);
 	if (adapter) await adapter.subscribe((room, message) => {
 		if (room.startsWith("org:")) {
 			const parts = room.split(":");
@@ -379,26 +1459,59 @@ const websocketPluginImpl = async (fastify, options) => {
 			if (!orgId) return;
 			const actualRoom = parts.slice(2).join(":");
 			rooms.broadcastToOrg(orgId, actualRoom, message);
-		} else rooms.broadcast(room, message);
+		} else if (room.startsWith("pushref-rt:")) rooms.sendRealtimeToPushRef(room.slice(11), message);
+		else if (room.startsWith("pushref:")) {
+			const id = room.slice(8);
+			if (!rooms.sendToPushRef(id, message)) try {
+				safeAsync(pushRefRegistry.stageForResume(id, JSON.parse(message)), fastify.log, "registry.stageForResume.relay", { pushRef: id });
+			} catch {}
+		} else if (room.startsWith("fence:")) {
+			const id = room.slice(6);
+			const stale = rooms.getClientByPushRef(id);
+			if (stale) stale.socket.close(4011, "Superseded by newer connection");
+		} else if (room.startsWith("userid-rt:")) rooms.sendRealtimeToUser(room.slice(10), message);
+		else if (room.startsWith("userid:")) rooms.sendToUser(room.slice(7), message);
+		else rooms.broadcast(room, message);
 	});
 	if (!fastify.hasDecorator("ws")) fastify.decorate("ws", {
 		rooms,
 		broadcast: (room, data) => {
-			const msg = JSON.stringify({
+			const msg = truncate(JSON.stringify({
 				type: "broadcast",
 				channel: room,
 				data
-			});
+			}));
 			rooms.broadcastWithAdapter(room, msg);
 		},
 		broadcastToOrg: (orgId, room, data) => {
-			const msg = JSON.stringify({
+			const msg = truncate(JSON.stringify({
 				type: "broadcast",
 				channel: room,
 				data
-			});
+			}));
 			rooms.broadcastToOrgWithAdapter(orgId, room, msg);
 		},
+		send: (target, data) => {
+			const payload = {
+				type: "direct",
+				data
+			};
+			const msg = truncate(JSON.stringify(payload));
+			if (target.pushRef) {
+				if (!rooms.sendToPushRef(target.pushRef, msg)) safeAsync(pushRefRegistry.stageForResume(target.pushRef, payload), fastify.log, "registry.stageForResume", { pushRef: target.pushRef });
+				if (adapter) safeAsync(adapter.publish(`pushref:${target.pushRef}`, msg), fastify.log, "adapter.publish", { kind: "pushref" });
+				return;
+			}
+			if (target.userId) return void rooms.sendToUserWithAdapter(target.userId, msg);
+		},
+		sendRealtime: (target, data, coalesceKey) => {
+			const msg = truncate(JSON.stringify({
+				type: "direct",
+				data
+			}));
+			if (target.pushRef) return void rooms.sendRealtimeToPushRefWithAdapter(target.pushRef, msg, coalesceKey);
+			if (target.userId) return void rooms.sendRealtimeToUserWithAdapter(target.userId, msg, coalesceKey);
+		},
 		getStats: () => rooms.getStats()
 	});
 	const eventUnsubscribers = await wireResourceEvents(fastify, rooms, resources);
@@ -406,7 +1519,11 @@ const websocketPluginImpl = async (fastify, options) => {
 	const ctx = {
 		fastify,
 		rooms,
+		pushRefRegistry,
 		nextClientId: () => `ws_${++clientCounter}_${Date.now()}`,
+		fence: (pushRef, _generation) => {
+			if (adapter) safeAsync(adapter.publish(`fence:${pushRef}`, ""), fastify.log, "fence.publish", { pushRef });
+		},
 		options: {
 			auth,
 			resources,
@@ -419,7 +1536,9 @@ const websocketPluginImpl = async (fastify, options) => {
 			roomPolicy,
 			onConnect,
 			onDisconnect,
-			onMessage
+			onMessage,
+			messageEnvelope,
+			deadQueueSize
 		}
 	};
 	fastify.get(path, { websocket: true }, async (socket, request) => {
@@ -438,4 +1557,4 @@ const websocketPlugin = fp(websocketPluginImpl, {
 	fastify: "5.x"
 });
 //#endregion
-export { LocalWebSocketAdapter, RoomManager, websocketPlugin };
+export { GeoRoom, LocalWebSocketAdapter, MemoryPushRefStore, PushRefRegistry, RoomManager, websocketPlugin };