@voltro/plugin-presence 0.24.0 → 0.26.0

package/dist/index.d.ts

@@ -1,9 +1,33 @@
 import { ColumnBuilder } from '@voltro/database';
+import { Effect } from 'effect';
 import { FieldDefinitions } from '@voltro/database';
 import { Schema } from 'effect';
 import { Table } from '@voltro/database';
 import { VoltroPlugin } from '@voltro/protocol';
 
+/**
+ * Wire a tracker to the transport and the membership registry.
+ *
+ * Returns a working tracker EVEN WITH NO PROVIDER — a single-instance
+ * deployment is just a cluster of one, and its roster is complete. Making the
+ * provider optional here rather than branching at the call site is what keeps
+ * "works in dev, silently different in production" off the table.
+ */
+export declare const attachPresenceBus: (options: AttachPresenceBusOptions) => PresenceBusHandle;
+
+export declare interface AttachPresenceBusOptions {
+    readonly instanceId: string;
+    readonly membership: PresenceMembership;
+    /** Absent ⇒ single instance. The tracker still works; nothing is broadcast. */
+    readonly provider?: PresenceTransport | undefined;
+    readonly logger?: {
+        readonly warn: (m: string, f?: Record<string, unknown>) => void;
+    };
+    /** The namespaced presence channel, from the framework's one resolver. */
+    readonly channel?: string | undefined;
+    readonly now?: () => number;
+}
+
 /** The currently-online members of a channel, newest heartbeat first. */
 export declare const filterOnline: (entries: ReadonlyArray<PresenceEntry>, now: number, timeoutMs: number) => ReadonlyArray<PresenceEntry>;
 
@@ -13,6 +37,47 @@ export declare const isOnline: (lastSeen: number, now: number, timeoutMs: number
 /** In-memory presence store (tests + single-process dev). */
 export declare const memoryPresenceStore: () => PresenceStore;
 
+/**
+ * Its own channel, for the same reason events are not on the change channel —
+ * and namespaced by the framework, which passes the resolved value in.
+ *
+ * This constant is the fallback for a single-app broker and for tests. It is NOT
+ * the normal path: a flat name is what let two apps on one Redis apply each
+ * other's presence deltas, and adding a member nobody is connected to is a
+ * member that can never leave — there is no owner to time out.
+ */
+export declare const PRESENCE_BROADCAST_CHANNEL = "voltro:presence";
+
+export declare interface PresenceBusHandle {
+    readonly tracker: PresenceTracker;
+    /**
+     * Whether a cross-instance transport is attached.
+     *
+     * Exposed so the plugin can WARN at boot. Without one every replica keeps a
+     * correct roster of its own clients and nothing errors — which is why the
+     * multi-replica failure looks exactly like success on a single box.
+     */
+    readonly hasTransport: boolean;
+    /** Broadcast one local change. Returns immediately; delivery is best-effort. */
+    readonly announce: (delta: PresenceDelta) => void;
+    readonly detach: () => void;
+}
+
+/** The wire shape of one change, broadcast by the owning instance. */
+export declare type PresenceDelta = {
+    readonly op: 'set';
+    readonly channel: string;
+    readonly tenantId: string | null;
+    readonly key: string;
+    readonly meta: Record<string, unknown> | null;
+    readonly lastSeen: number;
+} | {
+    readonly op: 'remove';
+    readonly channel: string;
+    readonly tenantId: string | null;
+    readonly key: string;
+};
+
 export declare interface PresenceEntry {
     readonly channel: string;
     /** Stable presence key — the subject id, or a client-supplied id for anon. */
@@ -36,12 +101,36 @@ declare const PresenceKeyMissing_base: Schema.TaggedErrorClass<PresenceKeyMissin
     channel: typeof Schema.String;
 }>;
 
+export declare interface PresenceMember {
+    /** Stable per-client key — the subject id, or a client-supplied one. */
+    readonly key: string;
+    readonly meta: Record<string, unknown> | null;
+    /** The owning instance's clock when it last saw a heartbeat. Compared only
+     *  against other timestamps from THAT owner. */
+    readonly lastSeen: number;
+}
+
+/** The one method of the membership registry this needs. */
+export declare interface PresenceMembership {
+    readonly onChange: (listener: (event: {
+        readonly kind: 'joined' | 'left' | 'restarted';
+        readonly instanceId: string;
+    }) => void) => () => void;
+}
+
 export declare const presencePlugin: (options?: PresencePluginOptions) => VoltroPlugin;
 
 export declare interface PresencePluginOptions {
     /** A member counts as online for this long after its last heartbeat. Default 30s. */
     readonly timeoutMs?: number;
-    /** Sweep interval for stale rows. Default 60s. */
+    /**
+     * How often to sweep members whose heartbeat has gone stale.
+     *
+     * Defaults to a THIRD of `timeoutMs`, so a vanished member is gone within
+     * roughly 1.3x the online window. Set it explicitly only if you need that
+     * detection delay tightened or relaxed independently of the window itself —
+     * the default is the right relationship for almost every room.
+     */
     readonly sweepIntervalMs?: number;
     readonly name?: string;
 }
@@ -68,6 +157,28 @@ declare const PresenceStoreUnavailable_base: Schema.TaggedErrorClass<PresenceSto
     readonly _tag: Schema.tag<"PresenceStoreUnavailable">;
 }>;
 
+/**
+ * The presence table — DECLARED, and deliberately NEVER WRITTEN.
+ *
+ * Presence state lives in the owner-partitioned `PresenceTracker`, in memory,
+ * announced between replicas over the broadcast channel. No row is inserted or
+ * updated any more: a heartbeat used to rewrite one row per client every 15
+ * seconds, which is a lot of write amplification for a datum that is meaningless
+ * 30 seconds later.
+ *
+ * The declaration survives because the name is the REACTIVITY KEY. `presence.list`
+ * declares `source: '_voltro_presence'`, and the framework routes change events
+ * by table name — so the plugin injects a synthetic change on that name whenever
+ * the tracker moves, and every subscribed client is pushed a fresh roster
+ * through the path it already used. Removing the declaration would make the
+ * `source` name resolve to nothing, which the boot audit reports (correctly) and
+ * which would silently stop every roster from updating.
+ *
+ * It therefore stays as an empty table. That is a real cost — one unused table
+ * in every user's database — accepted over the alternatives: a `source` that
+ * names nothing (invisible breakage, and an audit exemption that would rot), or
+ * a second client-side subscription concept just for presence.
+ */
 export declare const presenceTable: Table<"_voltro_presence", FieldDefinitions<{
     readonly id: ColumnBuilder<string, "id", boolean>;
     readonly channel: ColumnBuilder<string, "text", boolean>;
@@ -77,7 +188,134 @@ export declare const presenceTable: Table<"_voltro_presence", FieldDefinitions<{
     readonly lastSeen: ColumnBuilder<Date, "timestamp", true>;
 }>, true, "byPresenceChannel">;
 
+/**
+ * The merged presence view this instance can see.
+ *
+ * Owner-partitioned: `owner → route → key → member`. Every write names its
+ * owner, so dropping a departed instance is deleting one branch rather than
+ * scanning for its entries — which matters when a pod dies holding a thousand
+ * connections and the roster must settle in one operation, not a thousand.
+ */
+export declare class PresenceTracker {
+    private readonly partitions;
+    private readonly selfId;
+    private readonly now;
+    constructor(options: {
+        readonly instanceId: string;
+        readonly now?: () => number;
+    });
+    /** This instance's id — the owner stamped on everything it tracks. */
+    get owner(): string;
+    private branch;
+    /**
+     * Record a heartbeat from a client THIS instance holds.
+     *
+     * Returns the delta to broadcast, so the caller cannot forget to — a local
+     * write that is not announced is a member the other replicas never see, and
+     * nothing would report it.
+     */
+    track(input: {
+        readonly channel: string;
+        readonly tenantId: string | null;
+        readonly key: string;
+        readonly meta?: Record<string, unknown> | null;
+    }): PresenceDelta;
+    /** A client of THIS instance left. */
+    untrack(input: {
+        readonly channel: string;
+        readonly tenantId: string | null;
+        readonly key: string;
+    }): PresenceDelta;
+    /**
+     * Apply a delta from ANOTHER instance.
+     *
+     * Our own owner id is ignored: the local write already happened synchronously
+     * in `track`, and re-applying the echo would be harmless today but would make
+     * the local map depend on the broker — so a broker outage would silently stop
+     * this instance from seeing its OWN clients.
+     */
+    apply(owner: string, delta: PresenceDelta): void;
+    /**
+     * An instance is gone — drop everything it owned, in one operation.
+     *
+     * This is the whole reason membership had to be built. Its clients are not
+     * connected to anything any more, and no message will ever say so: a crashing
+     * process does not send a goodbye, and on the event channel it is simply
+     * quiet. Without this the roster keeps showing them forever.
+     */
+    dropOwner(owner: string): number;
+    /**
+     * Drop OUR OWN members that have stopped heartbeating, and return the deltas
+     * to broadcast.
+     *
+     * The comment on `roster` used to argue that no staleness filter was needed
+     * because "an entry here leaves when its client does". That premise was
+     * false: an entry left only when the client explicitly CALLED leave. A closed
+     * laptop, a dropped network or a crashed tab call nothing, and the owning
+     * replica is still alive so `dropOwner` never fires either — so those members
+     * stayed in the roster forever and every screen showed people who had gone.
+     *
+     * ONLY our own partition. Another owner's entries carry timestamps from THEIR
+     * clock, and judging them against ours is precisely the mistake instance
+     * membership exists to avoid: a peer that is gone is dropped whole, on a
+     * signal, not on a guess about clock skew. That asymmetry is the design —
+     * every entry is owned by exactly one instance, and only its owner can say
+     * whether it is still there.
+     *
+     * Returns the removals rather than being void for the same reason `track`
+     * does: a local removal nobody broadcasts is a member every OTHER replica
+     * keeps showing.
+     */
+    sweep(timeoutMs: number): ReadonlyArray<PresenceDelta>;
+    /** Everything this instance owns — what a newly-seen peer must be told. */
+    ownSnapshot(): ReadonlyArray<PresenceDelta>;
+    /**
+     * The roster for one channel, in one tenant.
+     *
+     * TENANT-SCOPED AND FAIL-CLOSED, exactly as the table version was: a caller
+     * only ever sees members whose tenant equals theirs, and an anonymous caller
+     * (`null`) sees only anonymous members. A same-named channel in another
+     * tenant is invisible, not merged.
+     *
+     * No staleness filter IN THE READ — the sweep does it on the write side
+     * instead, and the distinction matters.
+     *
+     * This comment used to argue that no staleness handling was needed at all,
+     * because "an entry is removed when the client leaves". That was false: an
+     * entry left only when a client explicitly CALLED leave. A closed laptop, a
+     * dropped network or a crashed tab call nothing, and the owning replica is
+     * still alive so `dropOwner` never fires either — so those members stayed in
+     * the roster forever and every screen showed people who had gone home.
+     *
+     * `sweep()` removes them on the OWNER's side, on a timer, and announces the
+     * removals. Reading stays filter-free because by the time a read happens the
+     * stale entries are already gone — which is the property the original comment
+     * claimed and did not have.
+     */
+    roster(channel: string, tenantId: string | null): ReadonlyArray<TrackedMember>;
+    /** Owners currently holding at least one member — for inspect. */
+    owners(): ReadonlyArray<{
+        readonly owner: string;
+        readonly members: number;
+    }>;
+    /** Total tracked members across every owner and channel. */
+    size(): number;
+}
+
+/** The two methods of a broadcast provider this needs. */
+export declare interface PresenceTransport {
+    readonly publish: (channel: string, payload: string) => Effect.Effect<unknown, unknown>;
+    readonly subscribe: (channel: string, handler: (payload: string) => void) => Effect.Effect<() => void, unknown>;
+}
+
 /** Keys that have gone stale (eligible for the sweep). */
 export declare const staleKeys: (entries: ReadonlyArray<PresenceEntry>, now: number, timeoutMs: number) => ReadonlyArray<PresenceEntry>;
 
+/** One member as the roster reports it, with the owner it belongs to. */
+export declare interface TrackedMember extends PresenceMember {
+    readonly owner: string;
+    readonly channel: string;
+    readonly tenantId: string | null;
+}
+
 export { }

package/dist/index.js

@@ -1,10 +1,178 @@
 import { PresenceKeyMissing as e, PresenceStoreUnavailable as t } from "./errors.js";
 import { heartbeatDescriptor as n, leaveDescriptor as r, listDescriptor as i, presenceRpcClientImports as a } from "./rpc.js";
 import { Effect as o } from "effect";
-import { and as s, eq as c, id as l, json as u, lt as d, queryFor as f, table as p, text as m, timestamp as h } from "@voltro/database";
-import { definePlugin as g, tsMs as _ } from "@voltro/protocol";
-//#region src/presence.ts
-var v = (e, t, n) => t - e < n, y = (e, t, n) => e.filter((e) => v(e.lastSeen, t, n)).sort((e, t) => t.lastSeen - e.lastSeen), b = (e, t, n) => e.filter((e) => !v(e.lastSeen, t, n)), x = () => {
+import { id as s, json as c, table as l, text as u, timestamp as d } from "@voltro/database";
+import { definePlugin as f } from "@voltro/protocol";
+//#region src/tracker.ts
+var p = (e, t) => `${e ?? "~"}::${t}`, m = class {
+	partitions = /* @__PURE__ */ new Map();
+	selfId;
+	now;
+	constructor(e) {
+		this.selfId = e.instanceId, this.now = e.now ?? Date.now;
+	}
+	get owner() {
+		return this.selfId;
+	}
+	branch(e, t, n) {
+		let r = this.partitions.get(e);
+		r === void 0 && (r = /* @__PURE__ */ new Map(), this.partitions.set(e, r));
+		let i = p(t, n), a = r.get(i);
+		return a === void 0 && (a = {
+			tenantId: t,
+			channel: n,
+			members: /* @__PURE__ */ new Map()
+		}, r.set(i, a)), a;
+	}
+	track(e) {
+		let t = this.now(), n = e.meta ?? null;
+		return this.branch(this.selfId, e.tenantId, e.channel).members.set(e.key, {
+			key: e.key,
+			meta: n,
+			lastSeen: t
+		}), {
+			op: "set",
+			channel: e.channel,
+			tenantId: e.tenantId,
+			key: e.key,
+			meta: n,
+			lastSeen: t
+		};
+	}
+	untrack(e) {
+		return this.branch(this.selfId, e.tenantId, e.channel).members.delete(e.key), {
+			op: "remove",
+			channel: e.channel,
+			tenantId: e.tenantId,
+			key: e.key
+		};
+	}
+	apply(e, t) {
+		if (e === this.selfId) return;
+		let { members: n } = this.branch(e, t.tenantId, t.channel);
+		if (t.op === "remove") {
+			n.delete(t.key);
+			return;
+		}
+		n.set(t.key, {
+			key: t.key,
+			meta: t.meta,
+			lastSeen: t.lastSeen
+		});
+	}
+	dropOwner(e) {
+		if (e === this.selfId) return 0;
+		let t = this.partitions.get(e);
+		if (t === void 0) return 0;
+		let n = 0;
+		for (let e of t.values()) n += e.members.size;
+		return this.partitions.delete(e), n;
+	}
+	sweep(e) {
+		let t = this.partitions.get(this.selfId);
+		if (t === void 0) return [];
+		let n = this.now() - e, r = [];
+		for (let e of t.values()) for (let [t, i] of e.members) i.lastSeen >= n || (e.members.delete(t), r.push({
+			op: "remove",
+			channel: e.channel,
+			tenantId: e.tenantId,
+			key: t
+		}));
+		return r;
+	}
+	ownSnapshot() {
+		let e = [], t = this.partitions.get(this.selfId);
+		if (t === void 0) return e;
+		for (let n of t.values()) for (let t of n.members.values()) e.push({
+			op: "set",
+			channel: n.channel,
+			tenantId: n.tenantId,
+			key: t.key,
+			meta: t.meta,
+			lastSeen: t.lastSeen
+		});
+		return e;
+	}
+	roster(e, t) {
+		let n = p(t, e), r = [];
+		for (let [i, a] of this.partitions) {
+			let o = a.get(n);
+			if (o !== void 0) for (let n of o.members.values()) r.push({
+				...n,
+				owner: i,
+				channel: e,
+				tenantId: t
+			});
+		}
+		return r.sort((e, t) => t.lastSeen - e.lastSeen);
+	}
+	owners() {
+		return [...this.partitions.entries()].map(([e, t]) => {
+			let n = 0;
+			for (let e of t.values()) n += e.members.size;
+			return {
+				owner: e,
+				members: n
+			};
+		});
+	}
+	size() {
+		return this.owners().reduce((e, t) => e + t.members, 0);
+	}
+}, h = "voltro:presence", g = (e) => typeof e == "object" && !!e && typeof e.owner == "string" && typeof e.delta == "object" && e.delta !== null, _ = (e) => typeof e == "object" && !!e && typeof e.owner == "string" && Array.isArray(e.sync), v = (e) => {
+	let t = new m({
+		instanceId: e.instanceId,
+		...e.now === void 0 ? {} : { now: e.now }
+	}), n = e.logger, r = e.membership.onChange((e) => {
+		if (e.kind === "joined") {
+			c();
+			return;
+		}
+		let r = t.dropOwner(e.instanceId);
+		r > 0 && n?.warn("presence: dropped members of a departed instance", {
+			instanceId: e.instanceId,
+			members: r,
+			reason: e.kind
+		}), e.kind === "restarted" && c();
+	}), i = e.provider, a = e.channel ?? "voltro:presence", s = (e) => {
+		i !== void 0 && o.runPromise(i.publish(a, JSON.stringify(e))).catch(() => {});
+	}, c = () => {
+		let n = t.ownSnapshot();
+		n.length !== 0 && s({
+			owner: e.instanceId,
+			sync: n
+		});
+	}, l;
+	return i !== void 0 && o.runPromise(i.subscribe(a, (e) => {
+		let n;
+		try {
+			n = JSON.parse(e);
+		} catch {
+			return;
+		}
+		if (_(n)) {
+			for (let e of n.sync) t.apply(n.owner, e);
+			return;
+		}
+		g(n) && t.apply(n.owner, n.delta);
+	})).then((e) => {
+		l = e;
+	}, (e) => {
+		n?.warn("presence: could not subscribe — this instance will only see its own members", { cause: e });
+	}), {
+		tracker: t,
+		hasTransport: i !== void 0,
+		announce: (t) => {
+			s({
+				owner: e.instanceId,
+				delta: t
+			});
+		},
+		detach: () => {
+			r(), l?.();
+		}
+	};
+}, y = (e, t, n) => t - e < n, b = (e, t, n) => e.filter((e) => y(e.lastSeen, t, n)).sort((e, t) => t.lastSeen - e.lastSeen), x = (e, t, n) => e.filter((e) => !y(e.lastSeen, t, n)), S = () => {
 	let e = /* @__PURE__ */ new Map(), t = (e, t) => `${e}|${t}`;
 	return {
 		upsert: async (n) => {
@@ -20,70 +188,53 @@ var v = (e, t, n) => t - e < n, y = (e, t, n) => e.filter((e) => v(e.lastSeen, t
 			return n;
 		}
 	};
-}, S = "_voltro_presence", C = p(S, {
-	id: l({ prefix: "pres" }),
-	channel: m(),
-	key: m(),
-	tenantId: m().nullable(),
-	meta: u().nullable(),
-	lastSeen: h().default("now")
-}).unique(["channel", "key"]).index("byPresenceChannel", ["channel", "lastSeen"]), w = (e) => e instanceof Date ? e : new Date(e), T = (e) => {
-	let t = (t) => e.query(f(C).where(t).descriptor), n = (e) => ({
-		channel: String(e.channel),
-		key: String(e.key),
-		tenantId: e.tenantId ?? null,
-		meta: e.meta ?? null,
-		lastSeen: _(e.lastSeen)
-	});
-	return {
-		upsert: async (t) => {
-			let n = {
-				channel: t.channel,
-				key: t.key,
-				tenantId: t.tenantId,
-				meta: t.meta,
-				lastSeen: w(t.lastSeen)
-			};
-			await e.upsert(S, n, {
-				conflictColumns: ["channel", "key"],
-				update: [
-					"tenantId",
-					"meta",
-					"lastSeen"
-				]
-			});
-		},
-		list: async (e, r) => (await t(c("channel", e))).map(n).filter((e) => e.tenantId === r),
-		remove: async (n, r) => {
-			let i = await t(s(c("channel", n), c("key", r)));
-			for (let t of i) await e.delete(S, String(t.id));
-		},
-		sweep: async (t) => e.deleteMany(S, { where: d("lastSeen", w(t)) })
-	};
-}, E = (s = {}) => {
-	let c = s.timeoutMs ?? 3e4, l = s.name ? `@voltro/plugin-presence#${s.name}` : "@voltro/plugin-presence", u, d, f = (e, t) => typeof t == "string" && t.length > 0 ? t : e.request.subject?.id ?? null, p = (e) => e.request.subject?.tenantId ?? null, m = [
+}, C = "_voltro_presence", w = l(C, {
+	id: s({ prefix: "pres" }),
+	channel: u(),
+	key: u(),
+	tenantId: u().nullable(),
+	meta: c().nullable(),
+	lastSeen: d().default("now")
+}).unique(["channel", "key"]).index("byPresenceChannel", ["channel", "lastSeen"]), T = (s = {}) => {
+	let c = s.timeoutMs ?? 3e4, l = Math.max(1e3, Math.floor(s.sweepIntervalMs ?? c / 3)), u = s.name ? `@voltro/plugin-presence#${s.name}` : "@voltro/plugin-presence", d, p, m, h = () => {
+		m !== void 0 || d === void 0 || (m = setInterval(() => {
+			let e = d;
+			if (e === void 0) return;
+			let t = e.tracker.sweep(c);
+			if (t.length !== 0) {
+				for (let n of t) e.announce(n);
+				y();
+			}
+		}, l), m.unref?.());
+	}, g = (e, t) => typeof t == "string" && t.length > 0 ? t : e.request.subject?.id ?? null, _ = (e) => e.request.subject?.tenantId ?? null, y = () => {
+		p?.injectExternalChange?.({
+			table: C,
+			op: "update",
+			new: {},
+			old: {}
+		});
+	}, b = [
 		{
 			...n,
 			description: "Register/refresh the caller's presence in a channel.",
 			execute: (n, r) => o.gen(function* () {
 				let i = n;
-				if (!u) return yield* o.fail(new t({}));
-				let a = f(r, i.key);
-				return a === null ? yield* o.fail(new e({ channel: i.channel })) : (yield* o.promise(() => u.upsert({
+				if (!d) return yield* o.fail(new t({}));
+				let a = g(r, i.key);
+				return a === null ? yield* o.fail(new e({ channel: i.channel })) : (d.announce(d.tracker.track({
 					channel: i.channel,
+					tenantId: _(r),
 					key: a,
-					tenantId: p(r),
-					meta: i.meta ?? null,
-					lastSeen: Date.now()
-				})), { ok: !0 });
+					...i.meta === void 0 ? {} : { meta: i.meta }
+				})), y(), { ok: !0 });
 			})
 		},
 		{
 			...i,
 			description: "The online roster of a channel (heartbeat-fresh members). Push-driven — updates live.",
-			source: S,
+			source: C,
 			execute: (e, n) => o.gen(function* () {
-				return u ? y(yield* o.promise(() => u.list(e.channel, p(n))), Date.now(), c).map((e) => ({
+				return d ? d.tracker.roster(e.channel, _(n)).map((e) => ({
 					key: e.key,
 					meta: e.meta,
 					lastSeen: e.lastSeen
@@ -95,33 +246,46 @@ var v = (e, t, n) => t - e < n, y = (e, t, n) => e.filter((e) => v(e.lastSeen, t
 			description: "Remove the caller's presence from a channel.",
 			execute: (n, r) => o.gen(function* () {
 				let i = n;
-				if (!u) return yield* o.fail(new t({}));
-				let a = f(r, i.key);
-				return a === null ? yield* o.fail(new e({ channel: i.channel })) : (yield* o.promise(() => u.remove(i.channel, a)), { ok: !0 });
+				if (!d) return yield* o.fail(new t({}));
+				let a = g(r, i.key);
+				return a === null ? yield* o.fail(new e({ channel: i.channel })) : (d.announce(d.tracker.untrack({
+					channel: i.channel,
+					tenantId: _(r),
+					key: a
+				})), y(), { ok: !0 });
 			})
 		}
 	];
-	return g({
-		name: l,
+	return f({
+		name: u,
 		description: "Ephemeral realtime presence — heartbeat roster per channel.",
 		permissions: ["store:write"],
-		extendSchema: { tables: [C] },
-		routes: m,
+		extendSchema: { tables: [w] },
+		routes: b,
 		rpcClientDescriptors: a,
 		bindDataStore: (e, t) => {
-			u = T(e);
-			let n = s.sweepIntervalMs ?? 6e4;
-			d = t?.scheduleCoordinated("presence.sweep", n, async () => {
-				await u?.sweep(Date.now() - c * 2);
+			p = e;
+			let n = t;
+			d = v({
+				instanceId: n?.instanceId ?? `presence-${process.pid}`,
+				membership: n?.membership ?? { onChange: () => () => {} },
+				...n?.broadcast === void 0 ? {} : { provider: n.broadcast },
+				...n?.broadcastChannels?.presence === void 0 ? {} : { channel: n.broadcastChannels.presence }
 			});
 		},
 		onActivate: (e) => o.sync(() => {
-			e.logger.info("presence active", { timeoutMs: c });
+			h();
+			let t = d?.hasTransport === !0;
+			e.logger.info("presence active", {
+				timeoutMs: c,
+				sweepEveryMs: l,
+				crossInstance: t
+			}), t || e.logger.warn("presence: no broadcast provider — each replica sees only the clients CONNECTED TO IT. Correct for a single instance; on more than one, every screen shows a fraction of the room and nothing reports it. Add @voltro/plugin-broadcast (redis:// or nats://) to share the roster.");
 		}),
 		onDeactivate: () => o.sync(() => {
-			d?.stop(), d = void 0;
+			m !== void 0 && (clearInterval(m), m = void 0), d?.detach(), d = void 0, p = void 0;
 		})
 	});
 };
 //#endregion
-export { e as PresenceKeyMissing, t as PresenceStoreUnavailable, y as filterOnline, v as isOnline, x as memoryPresenceStore, E as presencePlugin, C as presenceTable, b as staleKeys };
+export { h as PRESENCE_BROADCAST_CHANNEL, e as PresenceKeyMissing, t as PresenceStoreUnavailable, m as PresenceTracker, v as attachPresenceBus, b as filterOnline, y as isOnline, S as memoryPresenceStore, T as presencePlugin, w as presenceTable, x as staleKeys };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/plugin-presence",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "Ephemeral realtime presence — who is online in a channel, with heartbeat + live roster + per-member metadata (cursor, status). Backed by a swept presence table; works cross-instance.",
   "keywords": [
     "voltro",
@@ -47,9 +47,9 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/client": "0.24.0",
-    "@voltro/database": "0.24.0",
-    "@voltro/protocol": "0.24.0"
+    "@voltro/client": "0.26.0",
+    "@voltro/database": "0.26.0",
+    "@voltro/protocol": "0.26.0"
   },
   "peerDependencies": {
     "effect": "^3.22.0",