@ultimat3/realtime 1.2.0 → 2.0.0

package/src/pg-entity-row.ts

@@ -1,8 +1,11 @@
 // Physical Postgres row -> entity-row shaping: snake_case columns become camelCase properties,
-// and a `<p>_minor` / `<p>_currency` column pair folds into one `<p>: Money`-shaped property.
-// The inverse of the camelCasing here is `@ultimat3/entity`'s `column.ts#snake` — not imported
-// (a tier-3 package may not reach across to tier-2), so the round trip is pinned by a test instead.
+// and the `<p>_minor` / `<p>_currency` / `<p>_scale` columns fold into one `<p>: Money`-shaped
+// property. The inverse of the camelCasing here is `@ultimat3/entity`'s `column.ts#snake`, and
+// the fold is its `pg-row.ts#moneyOf` — neither is imported (this package declares no dependency
+// on tier 2), so both are pinned by a test instead: `pg-entity-row-parity.test.ts` reads one
+// physical row through both surfaces and asserts one object.
 
+import { describeValue } from '@ultimat3/core';
 import { ReplicationProtocolError } from './errors';
 import type { JsonObject, JsonValue } from './json';
 
@@ -17,18 +20,24 @@ function capitalize(part: string): string {
   return part.charAt(0).toUpperCase() + part.slice(1);
 }
 
-interface MoneyPair {
+interface FoldedMoney {
   readonly property: string;
-  readonly minorKey: string;
-  readonly currencyKey: string;
-  readonly minor: number;
-  readonly currency: string;
+  /** The physical columns the fold consumed, in declaration order — named together on a collision. */
+  readonly columns: readonly string[];
+  readonly value: JsonObject;
 }
 
-/** `price_minor` / `price_currency` -> `price`; any other column name has no money prefix. */
+/**
+ * `price_minor` / `price_currency` / `price_scale` -> `price`; any other column name has no money
+ * prefix. The scale column is matched here for the same reason the other two are: unmatched, it
+ * survived the fold as a physical `priceScale` property beside `price`, so one row read live and
+ * the same row read through a repository reported two different shapes — and the sub-cent amount
+ * the scale names was delivered to every subscriber unscaled.
+ */
 function moneyPrefix(column: string): string | null {
   if (column.endsWith('_minor')) return column.slice(0, -'_minor'.length);
   if (column.endsWith('_currency')) return column.slice(0, -'_currency'.length);
+  if (column.endsWith('_scale')) return column.slice(0, -'_scale'.length);
   return null;
 }
 
@@ -45,20 +54,74 @@ function moneyMinor(column: string, value: number | string): number {
   if (Number.isSafeInteger(minor)) return minor;
   throw new ReplicationProtocolError({
     stage: 'value',
-    detail: `column "${column}" carries "${value}", which is not a whole number of minor units`,
+    detail: `column "${column}" carries ${shownNumber(value)}, which is not a whole number of minor units`,
     fix: `store ${column} as a bigint inside ±2^53 — Money.minor is a number, never a float or a bigint`,
   });
 }
 
 /**
- * `name` is one half of a `<p>_minor` / `<p>_currency` pair, or null if it is not part of one.
- * Both halves must be present *and* typed like money — a null currency (an unset money value) is
- * not "half a pair", it simply is not a pair, so both columns fall through as ordinary values.
+ * `MoneyValue.scale` is a whole, non-negative count of decimal places, so that — and only that —
+ * is what this decoder refuses: a fractional or negative scale is not a value the shape can carry
+ * at all, exactly as an out-of-range `minor` is not.
+ *
+ * The `0…MAX_MONEY_SCALE` CEILING is `@ultimat3/schema`'s and is deliberately not restated here:
+ * it is enforced at both ends of this column already — the CHECK `@ultimat3/entity`'s
+ * `describeColumn` emits on `<p>_scale`, and `parseScale` on the repository read — and this
+ * package declares no `@ultimat3/schema` dependency, so a copy of the bound here would be a
+ * second declaration that can drift from the one that decides.
+ *
+ * `/^\d+$/` and not `Number(value)`: `Number('')` is 0, and 0 means whole units — the one value
+ * an empty column must never decode to. The same guard `parseScale` uses.
+ */
+function moneyScale(column: string, value: JsonValue): number {
+  const digits = typeof value === 'string' && /^\d+$/.test(value);
+  const scale = typeof value === 'number' ? value : digits ? Number(value) : Number.NaN;
+  if (Number.isSafeInteger(scale) && scale >= 0) return scale;
+  throw new ReplicationProtocolError({
+    stage: 'value',
+    detail: `column "${column}" carries ${shownNumber(value)}, which is not a whole number of decimal places`,
+    fix: `store ${column} as a non-negative integer, or null for the currency's own minor unit`,
+  });
+}
+
+/**
+ * **Paired with `parseMinor` in `@ultimat3/entity`'s `columns.ts`, and the pairing is the rule
+ * rather than the spelling: an amount may be echoed when it is *provably numeric*, and this file
+ * has to prove it at run time because entity proves it from the branch.**
+ *
+ * Entity reaches its echo only on a value already narrowed to a finite non-integer `number`, a
+ * `bigint`, or a `/^-?\d+$/` string. Here the value came off the WAL, and a `<p>_minor` pair is
+ * matched by column *name*: any `text` column called `note_minor` beside `note_currency` routes
+ * arbitrary user content through this throw. `"${value}"` on that path is the leak
+ * `describeValue` exists for — the message is built before any field-level redaction can see it,
+ * and it reaches the log store and the operator alike.
+ *
+ * So the amount survives when its content is a number (a float, an out-of-range integer, or a
+ * string that *is* one), and everything else is reported as shape. The scale column is matched by
+ * name the same way and carries the same risk, so it renders through here too.
  */
-function moneyPairAt(
+function shownNumber(value: JsonValue): string {
+  if (typeof value === 'number') return `"${value}"`;
+  if (typeof value !== 'string') return describeValue(value);
+  const numeric = value.trim() !== '' && Number.isFinite(Number(value));
+  return numeric ? `"${value}"` : describeValue(value);
+}
+
+/**
+ * `name` is part of a `<p>_minor` / `<p>_currency` (/ `<p>_scale`) group, or null if it is not.
+ * The first two must be present *and* typed like money — a null currency (an unset money value) is
+ * not "half a pair", it simply is not a pair, so every column falls through as an ordinary value.
+ *
+ * The scale column is the one member that may be absent or NULL, and both mean the same thing:
+ * "the currency's own minor unit". Neither produces a `scale` key, because `undefined` and `0` are
+ * different values — `0` claims whole units, a 100x reinterpretation of an ordinary price — which
+ * is exactly the rule `moneyOf` follows on the repository side. What it may NOT do is survive as a
+ * column of its own: the fold consumes it whenever the group folds.
+ */
+function foldMoney(
   physical: Readonly<Record<string, JsonValue>>,
   name: string,
-): MoneyPair | null {
+): FoldedMoney | null {
   const prefix = moneyPrefix(name);
   if (prefix === null) return null;
 
@@ -68,16 +131,21 @@ function moneyPairAt(
 
   const minor = physical[minorKey];
   const currency = physical[currencyKey];
-  if ((typeof minor === 'number' || typeof minor === 'string') && typeof currency === 'string') {
-    return {
-      property: camel(prefix),
-      minorKey,
-      currencyKey,
+  if (!(typeof minor === 'number' || typeof minor === 'string') || typeof currency !== 'string') {
+    return null;
+  }
+
+  const scaleKey = `${prefix}_scale`;
+  const scale = Object.hasOwn(physical, scaleKey) ? physical[scaleKey] : undefined;
+  return {
+    property: camel(prefix),
+    columns: scale === undefined ? [minorKey, currencyKey] : [minorKey, currencyKey, scaleKey],
+    value: {
       minor: moneyMinor(minorKey, minor),
       currency,
-    };
-  }
-  return null;
+      ...(scale === undefined || scale === null ? {} : { scale: moneyScale(scaleKey, scale) }),
+    },
+  };
 }
 
 /**
@@ -100,12 +168,13 @@ function claim(taken: Map<string, string>, property: string, column: string): vo
 /**
  * A physical postgres row -> the row shape the rest of the pipeline is written against.
  * Two things are not one-to-one and both live here: the column is snake_case while the entity
- * property is camelCase, and money is one property over the two columns `<p>_minor`/`<p>_currency`.
+ * property is camelCase, and money is one property over the columns `<p>_minor`/`<p>_currency`
+ * and the nullable `<p>_scale`.
  */
 export function entityRow(physical: Readonly<Record<string, JsonValue>>): JsonObject {
   const row: JsonObject = {};
-  // Column order in is key order out; a folded money property lands wherever its earlier half
-  // (whichever of _minor/_currency the source happened to emit first) would otherwise have sat.
+  // Column order in is key order out; a folded money property lands wherever its earliest member
+  // (whichever of the three the source happened to emit first) would otherwise have sat.
   const consumed = new Set<string>();
   // Which column produced each property, so a collision names both sides rather than losing one.
   const taken = new Map<string, string>();
@@ -113,12 +182,11 @@ export function entityRow(physical: Readonly<Record<string, JsonValue>>): JsonOb
   for (const name of Object.keys(physical)) {
     if (consumed.has(name)) continue;
 
-    const money = moneyPairAt(physical, name);
+    const money = foldMoney(physical, name);
     if (money !== null) {
-      claim(taken, money.property, `${money.minorKey}/${money.currencyKey}`);
-      row[money.property] = { minor: money.minor, currency: money.currency };
-      consumed.add(money.minorKey);
-      consumed.add(money.currencyKey);
+      claim(taken, money.property, money.columns.join('/'));
+      row[money.property] = money.value;
+      for (const column of money.columns) consumed.add(column);
       continue;
     }
 

package/src/pg-replication.ts

@@ -123,6 +123,15 @@ export class PgReplicationStream {
   /** Resolves once the stream is live. Delivery continues on the pump until `stop()`. */
   async start(handlers: ReplicationStreamHandlers): Promise<void> {
     if (this.#running) return;
+    // `#pump` is the previous run's *terminal cleanup*, not just its read loop: `#drain` awaits
+    // `#die`, and `#die` awaits `connection.close()`. `#die` clears `#running` and nulls
+    // `#connection` before that close settles, so a restart that dialled here would replace
+    // `#pump` with its own and leave the old walsender holding the slot — the next `stop()` would
+    // await only the new pump and report a released slot to a supervisor whose next process then
+    // collides with one that is still `active`. Waiting for it is waiting for the prior teardown.
+    const previous = this.#pump;
+    this.#pump = null;
+    if (previous !== null) await previous;
     const slot = this.#slot;
     const publication = this.#publication;
     const target = parsePgUrl(this.#options.url);
@@ -146,10 +155,15 @@ export class PgReplicationStream {
           `(proto_version '1', publication_names '${publication}')`,
       );
     } catch (failure) {
-      await this.stop();
+      // The dial failure is the one that explains the boot, so a teardown that also failed must
+      // not replace it — `stop()` has released everything either way by the time it rethrows.
+      await this.stop().catch(() => undefined);
       throw failure;
     }
     this.#running = true;
+    // A restart that kept the last death in `stats()` reports a live stream as failed, and the
+    // supervisor that reads it never sees the replicator come back.
+    this.#failure = null;
     this.#timer = setInterval(() => {
       void this.#confirm();
     }, this.#options.statusIntervalMs ?? DEFAULT_STATUS_INTERVAL_MS);
@@ -158,24 +172,75 @@ export class PgReplicationStream {
     this.#pump = this.#drain(connection, handlers);
   }
 
+  /**
+   * Every step here runs whatever the step before it did. A `#confirm` or an `endCopy` that threw
+   * used to skip the close and the pump await entirely: the socket leaked, the slot stayed
+   * `active`, and `stop()` reported the failure to a supervisor that was already starting the next
+   * process — teardown announced as finished before it had begun. The first failure is the one
+   * that explains the shutdown, so it is the one rethrown, and only once everything is let go.
+   */
   async stop(): Promise<void> {
     this.#running = false;
-    if (this.#timer !== null) {
-      clearInterval(this.#timer);
-      this.#timer = null;
-    }
+    this.#clearTimer();
     const connection = this.#connection;
     this.#connection = null;
-    if (connection === null) return;
-    // Confirming before the goodbye is what stops a restart from replaying the whole window.
-    if (connection.inCopyBoth) {
-      await this.#confirm(connection);
-      await connection.endCopy();
+    const failures: unknown[] = [];
+    try {
+      // Confirming before the goodbye is what stops a restart from replaying the whole window.
+      if (connection?.inCopyBoth === true) {
+        await this.#confirm(connection);
+        await connection.endCopy();
+      }
+    } catch (failure) {
+      failures.push(failure);
     }
-    await connection.close();
+    try {
+      await connection?.close();
+    } catch (failure) {
+      failures.push(failure);
+    }
+    // Awaited even when the stream died on its own: `#die` nulls the connection *before* closing
+    // it, so returning here would report the socket as released while it is still going down.
     const pump = this.#pump;
     this.#pump = null;
-    if (pump !== null) await pump;
+    try {
+      if (pump !== null) await pump;
+    } catch (failure) {
+      failures.push(failure);
+    }
+    if (failures.length > 0) throw failures[0];
+  }
+
+  /**
+   * The pump's only way out, however it ended — a decode error, or a walsender that said goodbye.
+   * The four things it owns go together or not at all, because each one left behind is a dead
+   * replicator claiming to be a live one: a `null` failure for a loop that stopped reading, a
+   * confirm timer still telling the walsender the stream is keeping up, a socket nobody closed,
+   * and a `#connection` the next `start()` overwrites instead of releasing. A `stop()` that got
+   * here first owns the connection, and its exit is an orderly one, not a failure.
+   */
+  async #die(reason: string): Promise<void> {
+    if (!this.#running) return;
+    this.#running = false;
+    this.#failure = reason;
+    this.#clearTimer();
+    const connection = this.#connection;
+    this.#connection = null;
+    // The supervisor reads /readyz, so the loop records, reports and ends rather than throwing
+    // into a promise nothing awaits.
+    logger.error('replication stream ended', { slot: this.#options.slot, error: reason });
+    try {
+      await connection?.close();
+    } catch {
+      // The socket is already unusable and `failure` above is the report that matters — a
+      // goodbye that throws must not become the rejection `#drain` promised never to produce.
+    }
+  }
+
+  #clearTimer(): void {
+    if (this.#timer === null) return;
+    clearInterval(this.#timer);
+    this.#timer = null;
   }
 
   /** The read loop. It owns no timers and no state beyond the current transaction. */
@@ -183,7 +248,12 @@ export class PgReplicationStream {
     try {
       for (;;) {
         const payload = await connection.nextCopyData();
-        if (payload === undefined) return;
+        if (payload === undefined) {
+          // The walsender ended the copy. However politely it said so, nothing reads the slot
+          // again until something restarts this — which is a failure, not a shutdown.
+          await this.#die('the walsender ended the copy stream');
+          return;
+        }
         const reader = new ByteReader(payload, 'copy-data');
         const tag = reader.tag();
         if (tag === 'w') {
@@ -207,20 +277,7 @@ export class PgReplicationStream {
         }
       }
     } catch (failure) {
-      if (!this.#running) return;
-      this.#running = false;
-      // The supervisor reads /readyz, so the loop records, reports and ends rather than throwing
-      // into a timer callback nothing awaits — and the confirm timer stops with the loop it
-      // confirms for, or it keeps telling the walsender a dead stream is still keeping up.
-      this.#failure = failure instanceof Error ? failure.message : String(failure);
-      if (this.#timer !== null) {
-        clearInterval(this.#timer);
-        this.#timer = null;
-      }
-      logger.error('replication stream ended', {
-        slot: this.#options.slot,
-        error: this.#failure,
-      });
+      await this.#die(failure instanceof Error ? failure.message : String(failure));
     }
   }
 

package/src/pg-socket.ts

@@ -51,9 +51,12 @@ export function parsePgUrl(url: string): PgTarget {
   try {
     parsed = new URL(url);
   } catch {
+    // The variable, never its value: a connection URL carries the database password, and an
+    // error is the one thing that reaches a log, `--json`, an agent transcript and a ticket.
+    // Same rule as `packages/mail/src/driver-smtp.ts:68`.
     throw new ReplicationFailedError({
       stage: 'connect',
-      detail: `"${url}" is not a connection URL`,
+      detail: 'DATABASE_URL is not a connection URL',
       fix: 'set DATABASE_URL to postgres://user:password@host:5432/database',
     });
   }

package/src/policy-gate.ts

@@ -4,9 +4,11 @@
 //
 // The row gate turns a denial into "not visible" instead of an error: a row that fails an actor's
 // policy is dropped, never sent. That is the rule from the live-query pipeline, implemented once.
+// A *denial* only — a gate that could not reach a decision raises, because "denied" and "the
+// database is down" are different facts and one of them has to page someone.
 
 import type { Actor, Ctx } from '@ultimat3/core';
-import { guard, type QueryPolicy, type QuerySubject } from '@ultimat3/query';
+import { guard, QueryDeniedError, type QueryPolicy, type QuerySubject } from '@ultimat3/query';
 import type { JsonValue, Row } from './json';
 
 export interface GateOptions {
@@ -23,7 +25,7 @@ export function authorizeWithPolicy(
   return async (args) => {
     // No row exists yet at subscribe time; `null` says so rather than leaving the predicate
     // to infer it from an absent field.
-    await guard(policy, subjectOf(options, args.actor, args.input, null), 'live');
+    guard(policy, subjectOf(options, args.actor, args.input, null), 'live');
   };
 }
 
@@ -38,10 +40,16 @@ export function visibleWithPolicy<R extends Row = Row>(
 ): (args: { actor: Actor | null; row: R; input: JsonValue }) => Promise<boolean> {
   return async (args) => {
     try {
-      await guard(policy, subjectOf(options, args.actor, args.input, args.row), 'live');
+      guard(policy, subjectOf(options, args.actor, args.input, args.row), 'live');
       return true;
-    } catch {
-      return false;
+    } catch (error) {
+      // `guard` throws `QueryDeniedError` for a decision and for nothing else, so that class is
+      // the whole of "not visible". A rule that reached for a row and timed out throws something
+      // else, and answering `false` to it would report an outage as a permission change: the rows
+      // leave the subscriber's screen, `live.rows_denied` counts the drop, and no error reaches
+      // the node. The registry is the one that decides what a failure costs — see `deliver`.
+      if (error instanceof QueryDeniedError) return false;
+      throw error;
     }
   };
 }

package/src/presence.ts

@@ -4,13 +4,22 @@
 // simply stop heartbeating and expire, and every other node already sees the same set. Ephemeral
 // state is never modelled as rows — that rule is what keeps presence off the write path entirely.
 
-import { type Clock, systemClock } from '@ultimat3/core';
+import { type Clock, systemClock, uuid } from '@ultimat3/core';
 import type { ChannelHub, Topic } from './channel';
 import type { Transport } from './fanout';
 import type { JsonObject } from './json';
 import { type Frame, PROTOCOL_VERSION, type PresenceMember } from './sync-protocol';
 
 export const PRESENCE_KEY_PREFIX = 'presence';
+/** Separate namespace: the sweep lease is one member per *node*, never one per participant. */
+export const PRESENCE_SWEEP_PREFIX = 'presence.sweep';
+
+/**
+ * Members carried on one full-set frame. A 5,000-avatar row is not a UI anyone renders, and the
+ * full set is 25M member deserializations across one all-hands join storm; the count rides along
+ * on the frame so a client can say "and 4,744 others" without ever holding them.
+ */
+export const DEFAULT_MAX_PRESENCE_MEMBERS = 256;
 
 export interface PresenceOptions {
   readonly transport: Transport;
@@ -19,6 +28,20 @@ export interface PresenceOptions {
   readonly clock?: Clock;
   /** Member TTL. Clients should heartbeat at ttl/3 so one lost beat is not a false leave. */
   readonly ttlMs?: number;
+  /** Members on a full-set frame. The set itself is never capped — only what is shipped. */
+  readonly maxMembers?: number;
+  /**
+   * This node's identity in the per-topic sweep election. Defaults to a fresh id per registry,
+   * which is what a `sync` node wants: an election between processes, never between rooms.
+   */
+  readonly nodeId?: string;
+}
+
+/** One full-set frame's worth of a room, and how big the room actually is. */
+export interface PresenceRoster {
+  readonly members: readonly PresenceMember[];
+  /** Members in the set, whatever was shipped. `total > members.length` means truncated. */
+  readonly total: number;
 }
 
 export interface PresenceInput {
@@ -34,6 +57,8 @@ export class PresenceRegistry {
   readonly #hub: ChannelHub | undefined;
   readonly #clock: Clock;
   readonly #ttlMs: number;
+  readonly #maxMembers: number;
+  readonly #nodeId: string;
   /** Diffing cache only — the truth is always `transport.shared`. Safe to lose. */
   readonly #seen = new Map<string, Set<string>>();
 
@@ -42,6 +67,8 @@ export class PresenceRegistry {
     this.#hub = options.hub;
     this.#clock = options.clock ?? systemClock;
     this.#ttlMs = options.ttlMs ?? 30_000;
+    this.#maxMembers = Math.max(1, options.maxMembers ?? DEFAULT_MAX_PRESENCE_MEMBERS);
+    this.#nodeId = options.nodeId ?? uuid();
   }
 
   get ttlMs(): number {
@@ -53,7 +80,7 @@ export class PresenceRegistry {
     return Math.max(1_000, Math.floor(this.#ttlMs / 3));
   }
 
-  async join(name: Topic, input: PresenceInput): Promise<readonly PresenceMember[]> {
+  async join(name: Topic, input: PresenceInput): Promise<PresenceRoster> {
     const member: PresenceMember = {
       id: input.id,
       actorId: input.actorId,
@@ -63,7 +90,7 @@ export class PresenceRegistry {
     await this.#write(name, member);
     this.#track(name).add(member.id);
     await this.#emit(name, 'join', [member]);
-    return await this.list(name);
+    return await this.roster(name);
   }
 
   /** `false` means the member had already expired: the caller must `join` again, not `heartbeat`. */
@@ -114,6 +141,15 @@ export class PresenceRegistry {
     return members;
   }
 
+  /**
+   * What a full-set frame carries. `list` stays the whole set because the sweep decides who left by
+   * differencing it — capping *that* would report every member past the cap as gone.
+   */
+  async roster(name: Topic): Promise<PresenceRoster> {
+    const members = await this.list(name);
+    return { members: members.slice(0, this.#maxMembers), total: members.length };
+  }
+
   /** Turns TTL expiry into explicit `leave` frames. Called on an interval by the `sync` node. */
   async sweep(name: Topic): Promise<readonly PresenceMember[]> {
     const live = await this.list(name);
@@ -144,17 +180,44 @@ export class PresenceRegistry {
   async sweepAll(): Promise<readonly PresenceMember[]> {
     const gone: PresenceMember[] = [];
     for (const name of [...this.#seen.keys()] as Topic[]) {
-      gone.push(...(await this.sweep(name)));
       // A room nobody is in is not a room. Without this the cache keeps one entry per topic ever
       // subscribed to, for the life of the process, and the sweep walks all of them forever.
+      if ((this.#seen.get(name)?.size ?? 0) === 0) {
+        this.#seen.delete(name);
+        continue;
+      }
+      if (!(await this.#claimSweep(name))) continue;
+      gone.push(...(await this.sweep(name)));
       if ((this.#seen.get(name)?.size ?? 0) === 0) this.#seen.delete(name);
     }
     return gone;
   }
 
+  /**
+   * One node per topic per pass reads the full member set. Every node sweeping every room it has
+   * ever seen is the same full-set read multiplied by the fleet — twenty nodes reading a
+   * 5,000-member set every ten seconds, forever, to produce twenty copies of one `leave` frame.
+   *
+   * The election needs no compare-and-set the shared store does not have: the lease key is a
+   * *keyed set*, so every node's claim is its own member and the winner is simply the lowest id
+   * every claimant can see. It is eventually consistent, and the worst case of two nodes reading
+   * different views is a duplicate `leave` for a member who has already gone — which is what a
+   * `leave` frame means anyway. What it never produces is nobody sweeping: a claim is re-put every
+   * pass, and a dead leader's expires within one TTL.
+   */
+  async #claimSweep(name: Topic): Promise<boolean> {
+    const key = `${PRESENCE_SWEEP_PREFIX}.${name}`;
+    await this.#transport.shared.put(key, this.#nodeId, '', this.#ttlMs);
+    const claimants = await this.#transport.shared.entries(key);
+    let leader = this.#nodeId;
+    for (const claimant of claimants) if (claimant.member < leader) leader = claimant.member;
+    return leader === this.#nodeId;
+  }
+
   /** Full-set frame for a client that just (re)connected — presence has no delta protocol. */
   async syncFrame(name: Topic): Promise<Frame> {
-    return presenceFrame(name, 'sync', await this.list(name));
+    const roster = await this.roster(name);
+    return presenceFrame(name, 'sync', roster.members, roster.total);
   }
 
   #key(name: Topic): string {
@@ -194,12 +257,19 @@ export class PresenceRegistry {
   }
 }
 
+/**
+ * `total` belongs to a **full set** and to nothing else: a `join`/`leave`/`update` frame carries the
+ * members that changed, so a count beside them would read as "and the rest were truncated". Absent
+ * is a defined answer — the client renders what it was sent.
+ */
 export function presenceFrame(
   name: Topic,
   op: 'join' | 'leave' | 'update' | 'sync',
   members: readonly PresenceMember[],
+  total?: number,
 ): Frame {
-  return { type: 'presence', v: PROTOCOL_VERSION, topic: name, op, members };
+  const base = { type: 'presence', v: PROTOCOL_VERSION, topic: name, op, members } as const;
+  return total === undefined ? base : { ...base, total };
 }
 
 function parseMember(id: string, value: string): PresenceMember | null {

package/src/query-hook.ts

@@ -0,0 +1,56 @@
+// The typed projection of a query into the hook a component calls: `liveHookFor(liveFeed)` is
+// `useLiveFeed`, and `useLiveFeed({ orgId })` carries that query's own input and row types. It
+// binds `useLive` rather than re-implementing it — one subscribe path, given the query's name.
+
+import { QueryNotSubscribableError } from './errors';
+import { type LiveInput, type LiveRows, useLive } from './hooks';
+
+/**
+ * What the hook needs from a `@ultimat3/query` `Query`: the name it subscribes under, the declared
+ * `live:` flag, and the call signature both types are read off. Named structurally rather than
+ * imported, the way `hooks.ts` names a mutator — a hook is browser code, and a value import of
+ * `@ultimat3/query` would carry the server's read path into the bundle.
+ *
+ * `options` is `never` because this side never passes one; a `Query`, whose second parameter is
+ * optional and wider, still assigns.
+ */
+export interface LiveQuerySource<TInput, TRow extends object> {
+  (input: TInput, options?: never): Promise<readonly TRow[]>;
+  readonly name: string;
+  readonly isLive: boolean;
+}
+
+/**
+ * The bound hook. Input is the query's own — a wrong key is a compile error in the component, not
+ * a subscription that returns nothing. A thunk is read **once**, at subscribe time, exactly as
+ * `useLive`'s is: there is no reactive runtime here to re-run it, so new input means a new
+ * subscription.
+ */
+export type LiveQueryHook<TInput, TRow extends object> = (
+  input: TInput | (() => TInput),
+) => LiveRows<TRow>;
+
+/**
+ * Bind one live query to one hook: `export const useLiveFeed = liveHookFor(liveFeed)`, then
+ * `useLiveFeed({ orgId })` in a component. Nothing is generated and nothing is fetched by hand —
+ * the types come off the query declaration and the rows off its subscription.
+ *
+ * Binding a query that is not `live: true` throws here, at module load, rather than handing back a
+ * hook that could only ever return an empty set.
+ */
+export function liveHookFor<TInput, TRow extends object>(
+  query: LiveQuerySource<TInput, TRow>,
+): LiveQueryHook<TInput, TRow> {
+  if (!query.isLive) throw new QueryNotSubscribableError({ name: query.name });
+  // The query object is handed through, never its `name` read now: `registerQueries()` stamps that
+  // at boot, and this binding runs at import — earlier. `useLive` reads it per subscription.
+  return (input) => {
+    // Both assertions are the one wire seam: the input is about to be serialised into a subscribe
+    // frame, and the rows come back off that subscription. `unknown` in between rather than a
+    // direct cast, exactly as `query.client()` hops through it at the same seam.
+    const rows: unknown = useLive(query, input as LiveInput);
+    // Erased at the wire seam, the way `query.client()` erases its own: the rows arriving on this
+    // subscription are this query's by construction, because the server built them from its `sql`.
+    return rows as LiveRows<TRow>;
+  };
+}