@ultimat3/realtime 20.2.0 → 21.0.0

package/src/channel-decl.ts

@@ -0,0 +1,144 @@
+// `channel(name, { params, policy, catchUp, records, events })` — the ONLY way to declare a channel,
+// and through its ref the only way to spell a topic. `channel(ref, { records, policy })` is the
+// same declaration for a ref an island already holds (`channel-ref.ts`): the browser chunk then
+// carries the name and params, never `@ultimat3/entity` (plan 101, slice 09).
+
+import type { Ctx, Row } from '@ultimat3/core';
+import {
+  type ProjectedEntity,
+  type RecordProjection,
+  recordProjection,
+} from '@ultimat3/entity/record';
+import type { QueryPolicy } from '@ultimat3/query';
+import {
+  type ChannelHandle,
+  type ChannelParams,
+  type ChannelRefInit,
+  channelRef,
+  refuseChannel,
+  SEGMENT,
+  type Topic,
+} from './channel-ref';
+import { registerChannel } from './channel-registry';
+
+export { type ChannelParams, type Topic, topic } from './channel-ref';
+
+/** What `records: [posts]` accepts: anything `entity()` built. */
+export type ChannelEntity = ProjectedEntity;
+
+/** `recordProjection`, refused in this declaration's words rather than the entity's. */
+function projectionFor(name: string, entity: ChannelEntity): RecordProjection {
+  try {
+    return recordProjection(entity);
+  } catch {
+    return refuseChannel(
+      name,
+      `records lists "${entity.$name}", which carries no record brand`,
+      'list entities declared with entity() from @ultimat3/entity',
+    );
+  }
+}
+
+/** What only the server half declares: the rows it carries and who may join. */
+export interface ChannelServerInit {
+  /**
+   * Evaluated on subscribe: the params are the input, and `row` is what the loader below answered
+   * (`null` without one). Omitted = any socket may join. Records are NOT gated per row — the topic's
+   * params are the scope, so a channel that must hide rows is declared narrower.
+   */
+  readonly policy?: QueryPolicy;
+  /**
+   * The subject the policy decides about, loaded by the SURFACE before the rule runs — the same
+   * split an action's `row:` makes, because a rule is synchronous and membership is a read.
+   */
+  readonly row?: ChannelRowLoader;
+  /** Entities whose committed rows this channel carries as records, matched to params BY NAME. */
+  readonly records?: readonly ChannelEntity[];
+  /** Whether the channel also carries ephemeral `events` frames. */
+  readonly events?: boolean;
+}
+
+export type ChannelInit<K extends string> = ChannelRefInit<K> & ChannelServerInit;
+
+export type ChannelRowLoader = (args: {
+  readonly params: Readonly<Record<string, string>>;
+  readonly ctx: Ctx;
+}) => unknown;
+
+export interface Channel<K extends string = string> {
+  readonly kind: 'channel';
+  readonly name: string;
+  readonly params: readonly K[];
+  readonly policy: QueryPolicy | undefined;
+  readonly row: ChannelRowLoader | undefined;
+  readonly catchUp: string;
+  readonly records: readonly RecordProjection[];
+  readonly events: boolean;
+  /** The topic for one set of params — the one spelling both sides use. */
+  topic(params: ChannelParams<K>): Topic;
+  /**
+   * The params a committed row of a listed entity belongs to: each param read off the row's
+   * property of the SAME NAME. `null` when the row lacks one (a partial `before` image).
+   */
+  paramsOf(row: Row): ChannelParams<K> | null;
+}
+
+/**
+ * Registers the declaration (`channel-registry.ts`) — a second one of the same name is refused.
+ *
+ * The params-matching rule, decided here once: a row belongs to the topic whose params equal the
+ * row's own properties of those names. So `channel('org-feed', { params: ['orgId'], records:
+ * [posts] })` carries every `posts` row on `org-feed.<row.orgId>`, and every listed entity must have
+ * a column named after every param — refused at declaration, where the author is.
+ */
+export function channel<const K extends string>(name: string, init: ChannelInit<K>): Channel<K>;
+export function channel<K extends string>(
+  ref: ChannelHandle<K>,
+  init: ChannelServerInit,
+): Channel<K>;
+export function channel<K extends string>(
+  nameOrRef: string | ChannelHandle<K>,
+  init: ChannelInit<K> | ChannelServerInit,
+): Channel<K> {
+  const ref =
+    typeof nameOrRef === 'string' ? channelRef(nameOrRef, init as ChannelInit<K>) : nameOrRef;
+  const name = ref.name;
+  const records = (init.records ?? []).map((entity) => {
+    const projection = projectionFor(name, entity);
+    for (const param of ref.params) {
+      if (!Object.hasOwn(projection.schema.properties ?? {}, param)) {
+        refuseChannel(
+          name,
+          `param "${param}" is not a column of "${projection.type}", so its rows match no topic`,
+          `rename the param to a column every listed entity has, or drop ${projection.type} from records`,
+        );
+      }
+    }
+    return projection;
+  });
+
+  const declared: Channel<K> = Object.freeze({
+    kind: 'channel' as const,
+    name,
+    params: ref.params,
+    policy: init.policy,
+    row: init.row,
+    get catchUp(): string {
+      return ref.catchUp;
+    },
+    records,
+    events: init.events === true,
+    topic: ref.topic,
+    paramsOf: (row: Row): ChannelParams<K> | null => {
+      const params: Partial<Record<K, string>> = {};
+      for (const param of ref.params) {
+        const value = Object.hasOwn(row, param) ? row[param] : undefined;
+        if (typeof value !== 'string' || !SEGMENT.test(value)) return null;
+        params[param] = value;
+      }
+      return params as ChannelParams<K>;
+    },
+  });
+  registerChannel(declared);
+  return declared;
+}

package/src/channel-describe.ts

@@ -0,0 +1,33 @@
+// The channel registry as the manifest reads it: one plain fact per declared channel, the policy
+// flattened the way a query's is. Server-side on purpose — the policy flattening is
+// `@ultimat3/query`'s, and a browser island declaring a channel must not bundle it.
+
+import { policyCapability, policyPermissions } from '@ultimat3/query';
+import { registeredChannels } from './channel-registry';
+
+export interface ChannelDescription {
+  readonly name: string;
+  readonly params: readonly string[];
+  /** The catch-up query's name, as `registerQueries` stamped it. */
+  readonly catchUp: string;
+  /** Record types (entity names) the channel carries, sorted. */
+  readonly records: readonly string[];
+  readonly events: boolean;
+  /** The policy's display label, `null` for a channel any socket may join. */
+  readonly policy: string | null;
+  /** Every permission the policy asserts, flattened — what a report matches a grant against. */
+  readonly permissions: readonly string[];
+}
+
+export function describeChannels(): readonly ChannelDescription[] {
+  return registeredChannels().map((declared) => ({
+    name: declared.name,
+    params: [...declared.params],
+    catchUp: declared.catchUp,
+    records: declared.records.map((projection) => projection.type).sort(),
+    events: declared.events,
+    policy: declared.policy === undefined ? null : policyCapability(declared.policy),
+    permissions:
+      declared.policy === undefined ? [] : [...policyPermissions(declared.policy)].sort(),
+  }));
+}

package/src/channel-gaps.ts

@@ -0,0 +1,57 @@
+// The repair half of a dropped `records` frame: the per-socket mark is `SyncSocket.gaps`, and this
+// is what answers it — one `replay-gap` per (socket, topic), sent once the socket takes frames
+// again, counted in `channel_replay_gaps_total` beside `channel_frames_dropped_total`.
+
+import { type Counter, counter } from '@ultimat3/core';
+import type { ReplayGapFrame } from './channel-wire';
+import type { SyncSocket } from './socket';
+import { PROTOCOL_VERSION } from './sync-protocol';
+
+/**
+ * `replay-gap` frames this node ANNOUNCED — a socket took the frame. Not "repaired": the re-read
+ * is the client's, and a node can only count what it said, never what a browser did about it.
+ */
+const channelReplayGaps: Counter = counter('channel_replay_gaps_total', {
+  unit: '{gap}',
+  description: 'replay-gap frames delivered to a socket that lost a channel records frame',
+});
+
+export class GapRepairs {
+  #announced = 0;
+
+  /** `replay-gap` frames delivered since boot — the in-process read of the series above. */
+  get announced(): number {
+    return this.#announced;
+  }
+
+  /** Sends the one `replay-gap` this socket owes for `topic`, if any. `true` when one went out. */
+  repair(socket: SyncSocket, topic: string): boolean {
+    const epoch = socket.gaps.get(topic);
+    if (epoch === undefined) return false;
+    const frame: ReplayGapFrame = {
+      type: 'replay-gap',
+      v: PROTOCOL_VERSION,
+      channel: topic,
+      epoch,
+    };
+    if (!socket.send(frame)) return false;
+    socket.gaps.delete(topic);
+    this.#announced += 1;
+    channelReplayGaps.add(1);
+    return true;
+  }
+
+  /** Everything this socket is owed — for Bun's `drain` callback. Answers how many went out. */
+  repairAll(socket: SyncSocket): number {
+    let repaired = 0;
+    for (const topic of [...socket.gaps.keys()]) if (this.repair(socket, topic)) repaired += 1;
+    return repaired;
+  }
+
+  /** Marks not yet answered, across `sockets`. Zero is a node owing no repair. */
+  pending(sockets: Iterable<SyncSocket>): number {
+    let pending = 0;
+    for (const socket of sockets) pending += socket.gaps.size;
+    return pending;
+  }
+}

package/src/channel-logs.ts

@@ -0,0 +1,116 @@
+// Every declared channel topic this node delivers records on: its ring (epoch, seq, recent frames),
+// the change → frame path, and the resume a resubscribe `since` asks for. One per `ChannelHub`.
+// Records never cross the bus — each node reads every change itself — so seq is minted here.
+
+import { logger, renderThrowable, uuid } from '@ultimat3/core';
+import type { ChangeEvent } from './changefeed';
+import type { Channel } from './channel-decl';
+import { updatesFor } from './channel-records';
+import { renderRecords } from './channel-render';
+import { ChannelRing } from './channel-ring';
+import type { ChannelSince, ReplayGapFrame } from './channel-wire';
+import type { SocketRegistry, SyncSocket } from './socket';
+import { PROTOCOL_VERSION } from './sync-protocol';
+
+/** What a joined topic resolves to. A topic is `name.params…`, so it names both exactly. */
+export interface ChannelTopic {
+  readonly channel: Channel;
+  readonly params: Readonly<Record<string, string>>;
+}
+
+export class ChannelLogs {
+  readonly #sockets: SocketRegistry;
+  readonly #ringSize: number | undefined;
+  /** This hub's mark on every epoch it mints: a restarted node can never reuse one. */
+  readonly #hubId = uuid();
+  #rings = 0;
+  readonly #byTopic = new Map<
+    string,
+    { readonly ring: ChannelRing; readonly target: ChannelTopic }
+  >();
+
+  constructor(sockets: SocketRegistry, ringSize?: number) {
+    this.#sockets = sockets;
+    this.#ringSize = ringSize;
+  }
+
+  /** The topic's log, opened on its first local member. */
+  open(topic: string, target: ChannelTopic): ChannelRing {
+    const existing = this.#byTopic.get(topic);
+    if (existing !== undefined) return existing.ring;
+    this.#rings += 1;
+    const ring = new ChannelRing(`${this.#hubId}:${this.#rings}`, this.#ringSize);
+    this.#byTopic.set(topic, { ring, target });
+    return ring;
+  }
+
+  /** Dropped with the topic's last local member; the next member gets a new epoch. */
+  close(topic: string): void {
+    this.#byTopic.delete(topic);
+  }
+
+  target(topic: string): ChannelTopic | undefined {
+    return this.#byTopic.get(topic)?.target;
+  }
+
+  /**
+   * One committed change → a `records` frame on every open topic it touches, rendered per socket.
+   * A key that cannot be computed (`X_RECORD_KEY_MISSING`) is logged and skipped for that channel:
+   * the change is somebody else's too, and one malformed image must not stop the rest.
+   */
+  deliverChange(channels: Iterable<Channel>, change: ChangeEvent): number {
+    let frames = 0;
+    let updates: ReturnType<typeof updatesFor>;
+    try {
+      updates = updatesFor(channels, change);
+    } catch (error) {
+      logger.warn('channel.records_unkeyed', {
+        table: change.entity,
+        error: renderThrowable(error),
+      });
+      return 0;
+    }
+    for (const update of updates) {
+      const open = this.#byTopic.get(update.topic);
+      if (open === undefined) continue;
+      const entry = open.ring.append(update.adopt, update.remove, change.write);
+      const frame = renderRecords(update.topic, open.ring.epoch, entry);
+      frames += this.#sockets.deliverRecords(update.topic, open.ring.epoch, frame);
+    }
+    return frames;
+  }
+
+  /**
+   * A (re)subscribe `since` a position: every frame after it from the ring, or — when the ring
+   * cannot prove it holds them all, or the epoch moved — one `replay-gap`.
+   *
+   * A FRESH seat with no `since` is a `replay-gap` too. The client's first read of these rows went
+   * over HTTP, on another connection, before this seat existed, so a commit between the two
+   * reached nobody — and nothing the client holds can name it. The seat is the one point after
+   * which every commit is a frame, so the re-read is told to start from here. A repeated `add` on
+   * a socket already seated (the presence beat), or a channel with no records, is sent nothing.
+   */
+  resume(socket: SyncSocket, topic: string, since: ChannelSince | undefined, fresh: boolean): void {
+    const open = this.#byTopic.get(topic);
+    if (open === undefined) return;
+    // An events-only channel (typing, a cursor) carries no rows, so there is nothing to re-read.
+    if (since === undefined && (!fresh || open.target.channel.records.length === 0)) return;
+    const entries = since === undefined ? null : open.ring.since(since);
+    if (entries === null) {
+      const frame: ReplayGapFrame = {
+        type: 'replay-gap',
+        v: PROTOCOL_VERSION,
+        channel: topic,
+        epoch: open.ring.epoch,
+      };
+      if (!socket.send(frame)) socket.gaps.set(topic, open.ring.epoch);
+      return;
+    }
+    for (const entry of entries) {
+      if (!socket.send(renderRecords(topic, open.ring.epoch, entry))) {
+        socket.gaps.set(topic, open.ring.epoch);
+        return;
+      }
+    }
+  }
+}

package/src/channel-presence.ts

@@ -0,0 +1,68 @@
+// Presence as a channel EVENT, not a frame kind of its own: joining a channel declared with
+// `events: true` joins its presence set, and a roster change is one `events` frame on that topic.
+// Browser-safe — the client reads the same shape back out with `readPresence`.
+
+import { isJsonObject, type JsonObject } from './json';
+import { FRAME_LIMITS, type PresenceMember } from './sync-protocol';
+
+export type PresenceOp = 'join' | 'leave' | 'update' | 'sync';
+
+const OPS: readonly PresenceOp[] = ['join', 'leave', 'update', 'sync'];
+
+/** The event payload: `{ presence, members, total? }`. `total` belongs to a full `sync` set only. */
+export interface PresenceEvent {
+  readonly presence: PresenceOp;
+  readonly members: readonly PresenceMember[];
+  /** Members in the whole set behind a capped `sync`; never on a delta. */
+  readonly total?: number;
+}
+
+export function presenceEvent(
+  op: PresenceOp,
+  members: readonly PresenceMember[],
+  total?: number,
+): JsonObject {
+  const base: JsonObject = {
+    presence: op,
+    members: members.map((m) => ({
+      id: m.id,
+      actorId: m.actorId,
+      meta: m.meta,
+      updatedAt: m.updatedAt,
+    })),
+  };
+  return total === undefined ? base : { ...base, total };
+}
+
+/**
+ * The presence payload of an `events` frame, or `null` when the event is not one — an app's own
+ * events share the channel. Refuses rather than repairs: a malformed roster is `null`, never a
+ * partial one, and a list past `FRAME_LIMITS.members` is refused like any oversized frame field.
+ */
+export function readPresence(event: JsonObject): PresenceEvent | null {
+  const op = event['presence'];
+  const members = event['members'];
+  if (typeof op !== 'string' || !OPS.includes(op as PresenceOp)) return null;
+  if (!Array.isArray(members) || members.length > FRAME_LIMITS.members) return null;
+  const parsed: PresenceMember[] = [];
+  for (const value of members) {
+    const one = memberOf(value);
+    if (one === null) return null;
+    parsed.push(one);
+  }
+  const total = event['total'];
+  const base = { presence: op as PresenceOp, members: parsed };
+  if (total === undefined) return base;
+  // A count a UI would render: anything but a whole non-negative number is a malformed roster.
+  return typeof total === 'number' && Number.isInteger(total) && total >= 0
+    ? { ...base, total }
+    : null;
+}
+
+function memberOf(value: unknown): PresenceMember | null {
+  if (!isJsonObject(value)) return null;
+  const { id, actorId, meta, updatedAt } = value;
+  if (typeof id !== 'string' || typeof updatedAt !== 'number') return null;
+  if (actorId !== null && typeof actorId !== 'string') return null;
+  return { id, actorId, meta: isJsonObject(meta) ? meta : {}, updatedAt };
+}

package/src/channel-records.ts

@@ -0,0 +1,79 @@
+// A committed change → the record updates each declared channel owes its subscribers. Pure: no
+// socket, no seq, no policy — `ChannelHub` does those per node and per socket. The only derivation
+// of "which channel carries this row" lives here, so a write never names a channel (axiom 2).
+
+import type { Row } from '@ultimat3/core/page';
+import type { RecordProjection } from '@ultimat3/entity/record';
+import type { ChangeEvent } from './changefeed';
+import type { Channel, Topic } from './channel-decl';
+import type { RecordPart } from './channel-ring';
+
+/** One topic's share of one change. `row` is what a per-row policy decides on. */
+export interface TopicUpdate {
+  readonly channel: Channel;
+  readonly topic: Topic;
+  readonly params: Readonly<Record<string, string>>;
+  readonly adopt: readonly RecordPart[];
+  readonly remove: readonly { readonly type: string; readonly key: string }[];
+  readonly row: Row;
+}
+
+/**
+ * `change.entity` is the replicated RELATION name (`pg-replication.ts` reads it off the Relation
+ * message), so it is matched against each projection's `table`, never its `type`.
+ *
+ * - insert/update: the new row is adopted on the topic its params name.
+ * - an update that moved the row to other params (`orgId` changed): a remove on the OLD topic too.
+ * - delete: a remove on the topic the old image names — which needs the params columns in the
+ *   `before` image, i.e. `REPLICA IDENTITY FULL`; a key-only image names no topic and is skipped.
+ */
+export function updatesFor(channels: Iterable<Channel>, change: ChangeEvent): TopicUpdate[] {
+  const updates: TopicUpdate[] = [];
+  for (const channel of channels) {
+    const projection = channel.records.find((candidate) => candidate.table === change.entity);
+    if (projection === undefined) continue;
+    const after = change.op === 'delete' ? null : change.after;
+    const before = change.before;
+    const afterParams = after === null ? null : channel.paramsOf(after);
+    const beforeParams = before === null ? null : channel.paramsOf(before);
+    const afterTopic = afterParams === null ? null : channel.topic(afterParams);
+    const beforeTopic = beforeParams === null ? null : channel.topic(beforeParams);
+
+    if (after !== null && afterParams !== null && afterTopic !== null) {
+      updates.push({
+        channel,
+        topic: afterTopic,
+        params: afterParams,
+        adopt: [{ type: projection.type, key: projection.key(after), row: after }],
+        remove: [],
+        row: after,
+      });
+    }
+    if (
+      before !== null &&
+      beforeParams !== null &&
+      beforeTopic !== null &&
+      beforeTopic !== afterTopic
+    ) {
+      updates.push(removal(channel, projection, beforeTopic, beforeParams, before));
+    }
+  }
+  return updates;
+}
+
+function removal(
+  channel: Channel,
+  projection: RecordProjection,
+  topic: Topic,
+  params: Readonly<Record<string, string>>,
+  row: Row,
+): TopicUpdate {
+  return {
+    channel,
+    topic,
+    params,
+    adopt: [],
+    remove: [{ type: projection.type, key: projection.key(row) }],
+    row,
+  };
+}

package/src/channel-ref.ts

@@ -0,0 +1,83 @@
+// A channel's CLIENT half: its name, params and catch-up read, and the one topic builder — no
+// entity, no policy, no registration. An island holds this; the server declares the same ref's
+// records and policy with `channel(ref, { … })`, so name and params are written once and a browser
+// chunk never carries `@ultimat3/entity`.
+
+import { invariant } from '@ultimat3/core/page';
+import { TopicForbiddenError } from './errors';
+
+/** Branded so a raw string can never be published to; `topic()` is the only constructor. */
+export type Topic = string & { readonly __ultimateTopic: unique symbol };
+
+export const SEGMENT = /^[A-Za-z0-9_-]+$/;
+
+/** `topic('org', orgId, 'cursors')` -> `org.<orgId>.cursors`. Segments are validated, never escaped. */
+export function topic(...parts: readonly (string | number)[]): Topic {
+  const segments = parts.map((part) => String(part));
+  for (const segment of segments) {
+    if (!SEGMENT.test(segment)) {
+      throw new TopicForbiddenError({
+        topic: segments.join('.'),
+        actorId: null,
+        reason: `segment "${segment}" must match ${SEGMENT.source} (dots and wildcards are reserved)`,
+      });
+    }
+  }
+  return segments.join('.') as Topic;
+}
+
+export type ChannelParams<K extends string> = Readonly<Record<K, string>>;
+
+export interface ChannelRefInit<K extends string> {
+  /** Ordered param names. Each becomes one topic segment, so each value is a segment-safe string. */
+  readonly params: readonly K[];
+  /**
+   * The read a client re-runs on `replay-gap` or a new epoch — a query, by name. Read on every
+   * access, never at declaration: `registerQueries()` stamps a declared query's name at boot.
+   */
+  readonly catchUp: { readonly name: string };
+}
+
+/** What a browser subscribes by — `useChannel(ref, params)`. */
+export interface ChannelHandle<K extends string = string> {
+  readonly kind: 'channel-ref';
+  readonly name: string;
+  readonly params: readonly K[];
+  readonly catchUp: string;
+  /** The topic for one set of params — the one spelling both halves use. */
+  topic(params: ChannelParams<K>): Topic;
+}
+
+export function refuseChannel(name: string, detail: string, fix: string): never {
+  invariant(false, 'X_CHANNEL_DECLARATION_INVALID', `channel("${name}"): ${detail}`, fix);
+}
+
+/** Refuses a bad name or a repeated param, and builds the ref. `channel()` is built on this. */
+export function channelRef<const K extends string>(
+  name: string,
+  init: ChannelRefInit<K>,
+): ChannelHandle<K> {
+  if (!SEGMENT.test(name)) {
+    refuseChannel(
+      name,
+      `the name must match ${SEGMENT.source}`,
+      `rename it, e.g. channel('org-feed', …)`,
+    );
+  }
+  if (new Set(init.params).size !== init.params.length) {
+    refuseChannel(name, 'a param is listed twice', 'list each param once in params: [...]');
+  }
+  // `Object.hasOwn`, never a bare `params[param]`: params arrive off a subscribe frame, and an
+  // inherited member would spell a topic nobody declared. Absent is `''`, which `topic()` refuses.
+  const topicOf = (params: ChannelParams<K>): Topic =>
+    topic(name, ...init.params.map((param) => (Object.hasOwn(params, param) ? params[param] : '')));
+  return Object.freeze({
+    kind: 'channel-ref' as const,
+    name,
+    params: init.params,
+    get catchUp(): string {
+      return init.catchUp.name;
+    },
+    topic: topicOf,
+  });
+}

package/src/channel-registry.ts

@@ -0,0 +1,35 @@
+// Every `channel()` declared in this process, keyed by name — the realtime twin of the entity and
+// query registries. `channel()` registers itself, so a host builds `new ChannelHub()` with no list
+// and the manifest reads the same table (`channel-describe.ts`); a second declaration of one name
+// is refused. Browser-safe: `channel()` runs in islands too.
+
+import { invariant } from '@ultimat3/core';
+import type { Channel } from './channel-decl';
+
+const channels = new Map<string, Channel>();
+
+export function registerChannel(declared: Channel): Channel {
+  invariant(
+    !channels.has(declared.name),
+    'X_CHANNEL_DECLARATION_INVALID',
+    `two channel() declarations share the name "${declared.name}"`,
+    'rename one of them: a channel name is its topic prefix, so it must be unique per app',
+  );
+  channels.set(declared.name, declared);
+  return declared;
+}
+
+/** The declaration of that name, or `undefined`. A `Map`, so a prototype member is never one. */
+export function getChannel(name: string): Channel | undefined {
+  return channels.get(name);
+}
+
+/** Sorted by name: a projection of the registry is a build input and must diff cleanly. */
+export function registeredChannels(): readonly Channel[] {
+  return [...channels.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Test seam. Production code never unregisters a channel. */
+export function clearChannels(): void {
+  channels.clear();
+}

package/src/channel-render.ts

@@ -0,0 +1,37 @@
+// One ring entry → the `records` frame every member of its topic receives. The same frame for all
+// of them: a channel's scope is its params, decided once at subscribe, never re-decided per row.
+
+import type { Row } from '@ultimat3/core/page';
+import type { RecordsEntry } from './channel-ring';
+import type { ChannelAdopt, ChannelRecordsFrame, ChannelRemove } from './channel-wire';
+import { PROTOCOL_VERSION } from './sync-protocol';
+
+export function renderRecords(
+  topic: string,
+  epoch: string,
+  entry: RecordsEntry,
+): ChannelRecordsFrame {
+  // Null-prototype maps: a record type and a record key are data, and `'__proto__'` stays a key.
+  const adopt = Object.create(null) as Record<string, Record<string, Row>>;
+  const remove = Object.create(null) as Record<string, string[]>;
+  for (const part of entry.adopt) {
+    const byKey = adopt[part.type] ?? (Object.create(null) as Record<string, Row>);
+    byKey[part.key] = part.row;
+    adopt[part.type] = byKey;
+  }
+  for (const part of entry.remove) {
+    const keys = remove[part.type] ?? [];
+    keys.push(part.key);
+    remove[part.type] = keys;
+  }
+  return {
+    type: 'records',
+    v: PROTOCOL_VERSION,
+    channel: topic,
+    seq: entry.seq,
+    epoch,
+    ...(entry.adopt.length === 0 ? {} : { adopt: adopt as ChannelAdopt }),
+    ...(entry.remove.length === 0 ? {} : { remove: remove as ChannelRemove }),
+    ...(entry.write === undefined ? {} : { write: entry.write }),
+  };
+}