@voltro/plugin-presence 0.32.0 → 0.34.0

package/README.md

@@ -2,7 +2,7 @@
 
 # @voltro/plugin-presence
 
-**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.**
+**Ephemeral realtime presence — who is online in a channel, with heartbeat + live roster + per-member metadata (cursor, status). Held in memory, owner-partitioned; cross-instance with @voltro/plugin-broadcast.**
 
 [📖 Documentation](https://docs.voltro.dev/docs/plugins/presence) · [voltro.dev](https://voltro.dev) · [Voltro Cloud](https://voltro.cloud)
 

package/dist/index.d.ts

@@ -1,8 +1,6 @@
-import { ColumnBuilder } from '@voltro/database';
 import { Effect } from 'effect';
-import { FieldDefinitions } from '@voltro/database';
+import { ReactivityChannel } from '@voltro/protocol';
 import { Schema } from 'effect';
-import { Table } from '@voltro/database';
 import { VoltroPlugin } from '@voltro/protocol';
 
 /**
@@ -25,18 +23,18 @@ export declare interface AttachPresenceBusOptions {
     };
     /** The namespaced presence channel, from the framework's one resolver. */
     readonly channel?: string | undefined;
+    /**
+     * Called when a REMOTE event moved this replica's roster — a peer's delta, or
+     * a peer's departure taking its partition with it.
+     *
+     * Only for the remote paths. A local heartbeat's push is the caller's, because
+     * only the caller knows whether the write it just made changed anything;
+     * routing it through here as well would give one fact two owners.
+     */
+    readonly onRosterChanged?: (() => void) | 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>;
-
-/** A member is online if its last heartbeat is within the timeout window. */
-export declare const isOnline: (lastSeen: number, now: number, timeoutMs: number) => boolean;
-
-/** 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.
@@ -78,16 +76,6 @@ export declare type PresenceDelta = {
     readonly key: string;
 };
 
-export declare interface PresenceEntry {
-    readonly channel: string;
-    /** Stable presence key — the subject id, or a client-supplied id for anon. */
-    readonly key: string;
-    readonly tenantId: string | null;
-    readonly meta: Record<string, unknown> | null;
-    /** epoch ms of the last heartbeat. */
-    readonly lastSeen: number;
-}
-
 /** The caller has no presence identity — an anonymous subject (no subject id)
  *  that also passed no explicit `key`. There's nothing stable to register a
  *  heartbeat under, so the route fails typed instead of silently no-opping.
@@ -132,20 +120,37 @@ export declare interface PresencePluginOptions {
      * the default is the right relationship for almost every room.
      */
     readonly sweepIntervalMs?: number;
+    /**
+     * Namespace for this plugin's rpc tags. Default `presence`.
+     *
+     * Set it when your app already publishes under that name — an exact tag
+     * collision is fatal at codegen, and this is the way out. Orthogonal to
+     * `name` below: `alias` REPLACES the namespace, `name` distinguishes two
+     * installations within it.
+     */
+    readonly alias?: string;
+    /**
+     * Discriminator for a SECOND installation of this plugin, when one app runs
+     * two (`@voltro/plugin-presence#analytics`). Not a rename — for that use
+     * `alias`.
+     */
     readonly name?: string;
 }
 
-export declare interface PresenceStore {
-    readonly upsert: (entry: PresenceEntry) => Promise<void>;
-    /** The channel's members FOR THE CALLER'S TENANT. Tenant-scoped + fail-closed:
-     *  a caller only ever sees members whose `tenantId` equals theirs (anon →
-     *  `null` sees only anon members); a same-named channel in another tenant is
-     *  invisible. Pass `subject.tenantId`. */
-    readonly list: (channel: string, tenantId: string | null) => Promise<ReadonlyArray<PresenceEntry>>;
-    readonly remove: (channel: string, key: string) => Promise<void>;
-    /** Drop every entry whose heartbeat is older than `olderThan` (epoch ms). */
-    readonly sweep: (olderThan: number) => Promise<number>;
-}
+/**
+ * The roster's reactivity channel — presence's push target.
+ *
+ * Declared HERE, in the browser-safe descriptor module, for two reasons. It is
+ * the `source:` of `listDescriptor`, so the client descriptor and the server
+ * route now carry the SAME value instead of the server adding one the client
+ * never saw. And the server's `publishReactivity` imports this exact object, so
+ * the thing that publishes and the thing that subscribes cannot name two
+ * different keys — the failure a pair of strings makes possible and silent.
+ *
+ * It replaces `_voltro_presence`, a table that was declared and deliberately
+ * never written purely to own this name.
+ */
+export declare const presenceRoster: ReactivityChannel;
 
 /** The presence store isn't bound — `bindDataStore` never ran. This is a boot/
  *  wiring bug (the plugin wasn't installed on an app with a DataStore), not a
@@ -157,37 +162,6 @@ 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>;
-    readonly key: ColumnBuilder<string, "text", boolean>;
-    readonly tenantId: ColumnBuilder<string | null, "text", boolean>;
-    readonly meta: ColumnBuilder<unknown, "json", boolean>;
-    readonly lastSeen: ColumnBuilder<Date, "timestamp", true>;
-}>, true, "byPresenceChannel">;
-
 /**
  * The merged presence view this instance can see.
  *
@@ -212,29 +186,36 @@ export declare class PresenceTracker {
      *
      * 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.
+     * nothing would report it. It returns `changed` beside it for the same kind of
+     * reason: a caller that has to derive "did this move the roster" would derive
+     * it from the delta, which cannot answer the question.
      */
     track(input: {
         readonly channel: string;
         readonly tenantId: string | null;
         readonly key: string;
         readonly meta?: Record<string, unknown> | null;
-    }): PresenceDelta;
+    }): PresenceWrite;
     /** A client of THIS instance left. */
     untrack(input: {
         readonly channel: string;
         readonly tenantId: string | null;
         readonly key: string;
-    }): PresenceDelta;
+    }): PresenceWrite;
     /**
-     * Apply a delta from ANOTHER instance.
+     * Apply a delta from ANOTHER instance. Returns whether the roster moved.
      *
      * 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.
+     *
+     * The return value is what lets the bus push a remote join to LOCAL
+     * subscribers. Until it existed, nothing did: a member who joined on replica A
+     * appeared on replica B's screens only when one of B's own clients happened to
+     * heartbeat, and the unconditional push on that heartbeat is what hid it.
      */
-    apply(owner: string, delta: PresenceDelta): void;
+    apply(owner: string, delta: PresenceDelta): boolean;
     /**
      * An instance is gone — drop everything it owned, in one operation.
      *
@@ -308,8 +289,28 @@ export declare interface PresenceTransport {
     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>;
+/**
+ * A local write, and whether it MOVED the roster.
+ *
+ * The second field is the whole reason this is not just a `PresenceDelta`. A
+ * heartbeat arrives every 15 seconds per client and almost never changes
+ * anything a subscriber can observe — the member was already there with the same
+ * metadata. Pushing on it anyway made the cost quadratic: N clients heartbeating
+ * into a room woke all N subscribers each time, N² wake-ups per interval, for a
+ * roster that had not moved.
+ *
+ * `changed` is exact rather than approximate because `lastSeen` is no longer on
+ * the wire (see `rpc.ts`). It is a heartbeat's ONLY effect in the steady state,
+ * so while it was observable, "did anything change" could only ever be answered
+ * "yes".
+ */
+export declare interface PresenceWrite {
+    /** The delta to broadcast. Always present — a peer must learn of a heartbeat
+     *  even when the roster did not move, or its own sweep will drop the member. */
+    readonly delta: PresenceDelta;
+    /** Whether a local subscriber would see a different roster. */
+    readonly changed: boolean;
+}
 
 /** One member as the roster reports it, with the owner it belongs to. */
 export declare interface TrackedMember extends PresenceMember {

package/dist/index.js

@@ -1,10 +1,9 @@
 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 { 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";
+import { heartbeatDescriptor as n, leaveDescriptor as r, listDescriptor as i, presenceRoster as a, presenceRpcClientImports as o } from "./rpc.js";
+import { Effect as s } from "effect";
+import { definePlugin as c, pluginInstanceName as l, publishReactivity as u } from "@voltro/protocol";
 //#region src/tracker.ts
-var p = (e, t) => `${e ?? "~"}::${t}`, m = class {
+var d = (e, t) => `${e ?? "~"}::${t}`, f = (e) => e === void 0 ? "undefined" : typeof e != "object" || !e ? JSON.stringify(e) ?? "undefined" : Array.isArray(e) ? `[${e.map(f).join(",")}]` : `{${Object.entries(e).sort(([e], [t]) => e < t ? -1 : +(e > t)).map(([e, t]) => `${JSON.stringify(e)}:${f(t)}`).join(",")}}`, p = (e, t) => e === t || e !== null && t !== null && f(e) === f(t), m = class {
 	partitions = /* @__PURE__ */ new Map();
 	selfId;
 	now;
@@ -17,7 +16,7 @@ var p = (e, t) => `${e ?? "~"}::${t}`, m = class {
 	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);
+		let i = d(t, n), a = r.get(i);
 		return a === void 0 && (a = {
 			tenantId: t,
 			channel: n,
@@ -25,40 +24,45 @@ var p = (e, t) => `${e ?? "~"}::${t}`, m = class {
 		}, 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, {
+		let t = this.now(), n = e.meta ?? null, { members: r } = this.branch(this.selfId, e.tenantId, e.channel), i = r.get(e.key);
+		return r.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
+			delta: {
+				op: "set",
+				channel: e.channel,
+				tenantId: e.tenantId,
+				key: e.key,
+				meta: n,
+				lastSeen: t
+			},
+			changed: i === void 0 || !p(i.meta, n)
 		};
 	}
 	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
+		let t = this.branch(this.selfId, e.tenantId, e.channel).members.delete(e.key);
+		return {
+			delta: {
+				op: "remove",
+				channel: e.channel,
+				tenantId: e.tenantId,
+				key: e.key
+			},
+			changed: t
 		};
 	}
 	apply(e, t) {
-		if (e === this.selfId) return;
+		if (e === this.selfId) return !1;
 		let { members: n } = this.branch(e, t.tenantId, t.channel);
-		if (t.op === "remove") {
-			n.delete(t.key);
-			return;
-		}
-		n.set(t.key, {
+		if (t.op === "remove") return n.delete(t.key);
+		let r = n.get(t.key);
+		return n.set(t.key, {
 			key: t.key,
 			meta: t.meta,
 			lastSeen: t.lastSeen
-		});
+		}), r === void 0 || !p(r.meta, t.meta);
 	}
 	dropOwner(e) {
 		if (e === this.selfId) return 0;
@@ -94,7 +98,7 @@ var p = (e, t) => `${e ?? "~"}::${t}`, m = class {
 		return e;
 	}
 	roster(e, t) {
-		let n = p(t, e), r = [];
+		let n = d(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({
@@ -123,27 +127,31 @@ var p = (e, t) => `${e ?? "~"}::${t}`, m = class {
 	let t = new m({
 		instanceId: e.instanceId,
 		...e.now === void 0 ? {} : { now: e.now }
-	}), n = e.logger, r = e.membership.onChange((e) => {
+	}), n = e.logger, r = () => {
+		try {
+			e.onRosterChanged?.();
+		} catch {}
+	}, i = e.membership.onChange((e) => {
 		if (e.kind === "joined") {
-			c();
+			l();
 			return;
 		}
-		let r = t.dropOwner(e.instanceId);
-		r > 0 && n?.warn("presence: dropped members of a departed instance", {
+		let i = t.dropOwner(e.instanceId);
+		i > 0 && (n?.warn("presence: dropped members of a departed instance", {
 			instanceId: e.instanceId,
-			members: r,
+			members: i,
 			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 = () => {
+		}), r()), e.kind === "restarted" && l();
+	}), a = e.provider, o = e.channel ?? "voltro:presence", c = (e) => {
+		a !== void 0 && s.runPromise(a.publish(o, JSON.stringify(e))).catch(() => {});
+	}, l = () => {
 		let n = t.ownSnapshot();
-		n.length !== 0 && s({
+		n.length !== 0 && c({
 			owner: e.instanceId,
 			sync: n
 		});
-	}, l;
-	return i !== void 0 && o.runPromise(i.subscribe(a, (e) => {
+	}, u;
+	return a !== void 0 && s.runPromise(a.subscribe(o, (e) => {
 		let n;
 		try {
 			n = JSON.parse(e);
@@ -151,147 +159,127 @@ var p = (e, t) => `${e ?? "~"}::${t}`, m = class {
 			return;
 		}
 		if (_(n)) {
-			for (let e of n.sync) t.apply(n.owner, e);
+			let e = !1;
+			for (let r of n.sync) e = t.apply(n.owner, r) || e;
+			e && r();
 			return;
 		}
-		g(n) && t.apply(n.owner, n.delta);
+		g(n) && t.apply(n.owner, n.delta) && r();
 	})).then((e) => {
-		l = e;
+		u = e;
 	}, (e) => {
 		n?.warn("presence: could not subscribe — this instance will only see its own members", { cause: e });
 	}), {
 		tracker: t,
-		hasTransport: i !== void 0,
+		hasTransport: a !== void 0,
 		announce: (t) => {
-			s({
+			c({
 				owner: e.instanceId,
 				delta: t
 			});
 		},
 		detach: () => {
-			r(), l?.();
+			i(), u?.();
 		}
 	};
-}, 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) => {
-			e.set(t(n.channel, n.key), n);
-		},
-		list: async (t, n) => [...e.values()].filter((e) => e.channel === t && e.tenantId === n),
-		remove: async (n, r) => {
-			e.delete(t(n, r));
-		},
-		sweep: async (t) => {
-			let n = 0;
-			for (let [r, i] of e) i.lastSeen < t && (e.delete(r), n++);
-			return n;
-		}
-	};
-}, 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 = {}) => {
-	if (s.timeoutMs !== void 0 && s.timeoutMs < 1e3) throw Error(`presencePlugin: \`timeoutMs\` is ${s.timeoutMs}, which expires every member before it can heartbeat again.
+}, y = "@voltro/plugin-presence", b = (d = {}) => {
+	if (d.timeoutMs !== void 0 && d.timeoutMs < 1e3) throw Error(`presencePlugin: \`timeoutMs\` is ${d.timeoutMs}, which expires every member before it can heartbeat again.
   A member is online for \`timeoutMs\` after its last heartbeat, and \`usePresence\` beats every 15s by default — so this must be LARGER than your client's
   \`heartbeatMs\`, comfortably. The default pair is 30s server / 15s client.
   There is no "never expire" spelling: omit \`timeoutMs\` for the default.`);
-	let c, l = s.timeoutMs ?? 3e4, u = Math.max(1e3, Math.floor(s.sweepIntervalMs ?? l / 3)), d = s.name ? `@voltro/plugin-presence#${s.name}` : "@voltro/plugin-presence", p, m, h, g = () => {
-		h !== void 0 || p === void 0 || (h = setInterval(() => {
-			let e = p;
+	let f, p = d.timeoutMs ?? 3e4, m = Math.max(1e3, Math.floor(d.sweepIntervalMs ?? p / 3)), h = l({
+		base: y,
+		alias: d.alias,
+		instance: d.name
+	}), g, _, b, x = () => {
+		b !== void 0 || g === void 0 || (b = setInterval(() => {
+			let e = g;
 			if (e === void 0) return;
-			let t = e.tracker.sweep(l);
+			let t = e.tracker.sweep(p);
 			if (t.length !== 0) {
 				for (let n of t) e.announce(n);
-				b();
+				w();
 			}
-		}, u), h.unref?.());
-	}, _ = (e, t) => typeof t == "string" && t.length > 0 ? t : e.request.subject?.id ?? null, y = (e) => e.request.subject?.tenantId ?? null, b = () => {
-		m?.injectExternalChange?.({
-			table: C,
-			op: "update",
-			new: {},
-			old: {}
-		});
-	}, x = [
-		{
-			...n,
-			description: "Register/refresh the caller's presence in a channel.",
-			execute: (n, r) => o.gen(function* () {
-				let i = n;
-				if (!p) return yield* o.fail(new t({}));
-				let a = _(r, i.key);
-				return a === null ? yield* o.fail(new e({ channel: i.channel })) : (p.announce(p.tracker.track({
-					channel: i.channel,
-					tenantId: y(r),
-					key: a,
-					...i.meta === void 0 ? {} : { meta: i.meta }
-				})), b(), { ok: !0 });
-			})
-		},
-		{
-			...i,
-			description: "The online roster of a channel (heartbeat-fresh members). Push-driven — updates live.",
-			source: C,
-			execute: (e, n) => o.gen(function* () {
-				return p ? p.tracker.roster(e.channel, y(n)).map((e) => ({
-					key: e.key,
-					meta: e.meta,
-					lastSeen: e.lastSeen
-				})) : yield* o.fail(new t({}));
-			})
-		},
-		{
-			...r,
-			description: "Remove the caller's presence from a channel.",
-			execute: (n, r) => o.gen(function* () {
-				let i = n;
-				if (!p) return yield* o.fail(new t({}));
-				let a = _(r, i.key);
-				return a === null ? yield* o.fail(new e({ channel: i.channel })) : (p.announce(p.tracker.untrack({
-					channel: i.channel,
-					tenantId: y(r),
-					key: a
-				})), b(), { ok: !0 });
-			})
-		}
-	];
-	return f({
-		name: d,
+		}, m), b.unref?.());
+	}, S = (e, t) => typeof t == "string" && t.length > 0 ? t : e.request.subject?.id ?? null, C = (e) => e.request.subject?.tenantId ?? null, w = () => {
+		u(_, a);
+	};
+	return c({
+		name: h,
+		baseName: y,
 		description: "Ephemeral realtime presence — heartbeat roster per channel.",
-		permissions: ["store:write"],
-		extendSchema: { tables: [w] },
-		routes: x,
-		rpcClientDescriptors: a,
+		routes: [
+			{
+				...n,
+				description: "Register/refresh the caller's presence in a channel.",
+				execute: (n, r) => s.gen(function* () {
+					let i = n;
+					if (!g) return yield* s.fail(new t({}));
+					let a = S(r, i.key);
+					if (a === null) return yield* s.fail(new e({ channel: i.channel }));
+					let o = g.tracker.track({
+						channel: i.channel,
+						tenantId: C(r),
+						key: a,
+						...i.meta === void 0 ? {} : { meta: i.meta }
+					});
+					return g.announce(o.delta), o.changed && w(), { ok: !0 };
+				})
+			},
+			{
+				...i,
+				description: "The online roster of a channel (heartbeat-fresh members). Push-driven — updates live.",
+				execute: (e, n) => s.gen(function* () {
+					return g ? g.tracker.roster(e.channel, C(n)).map((e) => ({
+						key: e.key,
+						meta: e.meta
+					})) : yield* s.fail(new t({}));
+				})
+			},
+			{
+				...r,
+				description: "Remove the caller's presence from a channel.",
+				execute: (n, r) => s.gen(function* () {
+					let i = n;
+					if (!g) return yield* s.fail(new t({}));
+					let a = S(r, i.key);
+					if (a === null) return yield* s.fail(new e({ channel: i.channel }));
+					let o = g.tracker.untrack({
+						channel: i.channel,
+						tenantId: C(r),
+						key: a
+					});
+					return g.announce(o.delta), o.changed && w(), { ok: !0 };
+				})
+			}
+		],
+		rpcClientDescriptors: o,
 		bindDataStore: (e, t) => {
-			m = e;
+			_ = e;
 			let n = t;
-			p = v({
+			g = 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 }
+				...n?.broadcastChannels?.presence === void 0 ? {} : { channel: n.broadcastChannels.presence },
+				onRosterChanged: w
 			});
 		},
-		onActivate: (e) => o.sync(() => {
-			g(), e.logger.info("presence active", {
-				timeoutMs: l,
-				sweepEveryMs: u
+		onActivate: (e) => s.sync(() => {
+			x(), e.logger.info("presence active", {
+				timeoutMs: p,
+				sweepEveryMs: m
 			});
 			let t = Number(process.env.VOLTRO_PRESENCE_BROKER_GRACE_MS ?? 5e3), n = setTimeout(() => {
-				let t = p?.hasTransport === !0;
+				let t = g?.hasTransport === !0;
 				e.logger.info("presence transport", { 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.");
 			}, t);
-			n.unref?.(), c = n;
+			n.unref?.(), f = n;
 		}),
-		onDeactivate: () => o.sync(() => {
-			c !== void 0 && (clearTimeout(c), c = void 0), h !== void 0 && (clearInterval(h), h = void 0), p?.detach(), p = void 0, m = void 0;
+		onDeactivate: () => s.sync(() => {
+			f !== void 0 && (clearTimeout(f), f = void 0), b !== void 0 && (clearInterval(b), b = void 0), g?.detach(), g = void 0, _ = void 0;
 		})
 	});
 };
 //#endregion
-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 };
+export { h as PRESENCE_BROADCAST_CHANNEL, e as PresenceKeyMissing, t as PresenceStoreUnavailable, m as PresenceTracker, v as attachPresenceBus, b as presencePlugin, a as presenceRoster };

package/dist/rpc.d.ts

@@ -1,6 +1,7 @@
 import { MutationProcedureDescriptor } from '@voltro/protocol';
 import { PluginRpcClientDescriptor } from '@voltro/protocol';
 import { QueryProcedureDescriptor } from '@voltro/protocol';
+import { ReactivityChannel } from '@voltro/protocol';
 import { Schema } from 'effect';
 
 export declare const heartbeatDescriptor: MutationProcedureDescriptor<"presence.heartbeat", Schema.Struct<{
@@ -23,7 +24,6 @@ export declare const listDescriptor: QueryProcedureDescriptor<"presence.list", S
 }>, Schema.Array$<Schema.Struct<{
     key: typeof Schema.String;
     meta: Schema.NullOr<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
-    lastSeen: typeof Schema.Number;
 }>>, typeof PresenceStoreUnavailable>;
 
 /** The caller has no presence identity — an anonymous subject (no subject id)
@@ -39,6 +39,21 @@ declare const PresenceKeyMissing_base: Schema.TaggedErrorClass<PresenceKeyMissin
     channel: typeof Schema.String;
 }>;
 
+/**
+ * The roster's reactivity channel — presence's push target.
+ *
+ * Declared HERE, in the browser-safe descriptor module, for two reasons. It is
+ * the `source:` of `listDescriptor`, so the client descriptor and the server
+ * route now carry the SAME value instead of the server adding one the client
+ * never saw. And the server's `publishReactivity` imports this exact object, so
+ * the thing that publishes and the thing that subscribes cannot name two
+ * different keys — the failure a pair of strings makes possible and silent.
+ *
+ * It replaces `_voltro_presence`, a table that was declared and deliberately
+ * never written purely to own this name.
+ */
+export declare const presenceRoster: ReactivityChannel;
+
 /** Declared for the codegen (`VoltroPlugin.rpcClientDescriptors`) so each tag is
  *  emitted into the generated client group. Kept in lockstep with the exports. */
 export declare const presenceRpcClientImports: ReadonlyArray<PluginRpcClientDescriptor>;