@ultimat3/realtime 23.0.0 → 25.0.0

package/src/channel-authz.ts

@@ -1,15 +1,21 @@
 // A declared channel's policy, asked on subscribe: the params are the input and the row is what
-// the channel's own loader answered. Through `@ultimat3/query`'s `guard`, the package's one authz
-// seam — the same call `policy-gate.ts` makes for a live query.
+// the channel's own loader answered. Through `@ultimat3/query`'s `guardQuery`, the package's one
+// authz seam — the same call `policy-gate.ts` makes for a live query.
 
-import { type Actor, type Ctx, createContext, runWithContext } from '@ultimat3/core';
-import { guard, QueryDeniedError } from '@ultimat3/query';
+import { type Actor, type Ctx, ctxOf, runWithContext } from '@ultimat3/core';
+import { guardQuery, QueryDeniedError } from '@ultimat3/query';
 import type { Channel } from './channel-decl';
-import { TopicForbiddenError } from './errors';
+import { isTenancyDenial, TopicForbiddenError } from './errors';
 
 /**
  * A denial is `X_TOPIC_FORBIDDEN`. A loader or a rule that RAISED is not a denial and leaves as it
- * came, so the caller can tell an outage from a decision — `onActorChange` keeps the topic on one.
+ * came, so the caller can tell an outage from a decision — `onActorChange` suspends the topic on one.
+ *
+ * Two answers are denials before any rule runs, because neither is an outage:
+ * - **nobody, on a channel that decides on a row.** A loader runs AS the subscriber; with no actor
+ *   it would run as the node, and a row is not something nobody is entitled to.
+ * - **a loader the tenant guard refused** (`TENANCY_DENIAL_CODES`): the actor has no org, or names
+ *   another one. That is the verdict about a removed member, not a store that could not answer.
  */
 export async function authorizeChannel(
   channel: Channel,
@@ -18,17 +24,42 @@ export async function authorizeChannel(
   topic: string,
   params: Readonly<Record<string, string>>,
 ): Promise<void> {
-  // The loader and the rule run AS the subscriber, never as the node. Under the node's context — no
-  // actor, no tenant — a repository read inside the loader was scoped by nothing but what the
-  // loader happened to name, and `@ultimat3/entity`'s tenancy seam had no actor to hold it to.
-  // Services are rebuilt for this actor by `createContext`, the rule `withChildContext` follows.
-  const scoped = actor === null ? ctx : subscriberContext(ctx, actor);
-  const row =
-    channel.row === undefined
-      ? null
-      : await runWithContext(scoped, async () => await channel.row?.({ params, ctx: scoped }));
+  const loader = channel.row;
+  if (loader === undefined) return decide(channel, ctx, actor, topic, params, null);
+  if (actor === null) {
+    throw new TopicForbiddenError({
+      topic,
+      actorId: null,
+      reason: `channel "${channel.name}" decides on a row, and an anonymous socket has no actor to load one as`,
+    });
+  }
+  // The loader and the rule run AS the subscriber, never as the node. Services are rebuilt for
+  // this actor by `ctxOf`, the rule `withChildContext` follows.
+  const scoped = subscriberContext(ctx, actor);
+  let row: unknown;
+  try {
+    row = await runWithContext(scoped, async () => await loader({ params, ctx: scoped }));
+  } catch (error) {
+    if (!isTenancyDenial(error)) throw error;
+    throw new TopicForbiddenError({
+      topic,
+      actorId: actor.id,
+      reason: `channel "${channel.name}" reads a row outside this actor's tenant`,
+    });
+  }
+  decide(channel, scoped, actor, topic, params, row);
+}
+
+function decide(
+  channel: Channel,
+  ctx: Ctx,
+  actor: Actor | null,
+  topic: string,
+  params: Readonly<Record<string, string>>,
+  row: unknown,
+): void {
   try {
-    guard(channel.policy, { actor, input: params, row, ctx: scoped, query: channel.name }, 'live');
+    guardQuery(channel.policy, { actor, input: params, row, ctx, query: channel.name }, 'live');
   } catch (error) {
     if (!(error instanceof QueryDeniedError)) throw error;
     throw new TopicForbiddenError({
@@ -41,7 +72,7 @@ export async function authorizeChannel(
 
 /** The node's context, re-made for one subscriber: same deploy, role and clock, their actor. */
 function subscriberContext(node: Ctx, actor: Actor): Ctx {
-  return createContext({
+  return ctxOf({
     actor,
     role: node.role,
     buildId: node.buildId,

package/src/channel-describe.ts

@@ -2,7 +2,7 @@
 // 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 { policyCapability, policyPermissions } from '@ultimat3/policy';
 import { registeredChannels } from './channel-registry';
 
 export interface ChannelDescription {

package/src/channel-latch.ts

@@ -0,0 +1,52 @@
+// The denials one socket has been answered with, latched until its session changes — so a client
+// re-asking in a loop is answered without re-running the policy, and only THAT topic is refused.
+// Bounded: a topic is spelled from client params, so an unbounded latch was one entry per refusal.
+
+import { SubscriptionLimitError } from './errors';
+import type { SyncSocket } from './socket';
+
+export class DenialLatch {
+  /** Weakly keyed, so a socket's latch dies with it and no close path has to remember it. */
+  readonly #bySocket = new WeakMap<SyncSocket, Set<string>>();
+  readonly #max: number;
+  readonly #knob: string;
+
+  constructor(max: number, knob: string) {
+    this.#max = max;
+    this.#knob = knob;
+  }
+
+  has(socket: SyncSocket, name: string): boolean {
+    return this.#bySocket.get(socket)?.has(name) === true;
+  }
+
+  /**
+   * Refused BEFORE a policy runs once the latch is full: a socket that has been denied this many
+   * distinct topics is asking for more than it may hold, and each further ask would otherwise be
+   * either a retained entry or a policy pass the client schedules at will.
+   */
+  assertRoom(socket: SyncSocket): void {
+    if ((this.#bySocket.get(socket)?.size ?? 0) < this.#max) return;
+    throw new SubscriptionLimitError({
+      scope: 'socket',
+      id: socket.id,
+      limit: this.#max,
+      knob: this.#knob,
+    });
+  }
+
+  add(socket: SyncSocket, name: string): void {
+    const latched = this.#bySocket.get(socket) ?? new Set<string>();
+    if (latched.size < this.#max) this.#bySocket.set(socket, latched.add(name));
+  }
+
+  /** A new session re-decides everything. */
+  clear(socket: SyncSocket): void {
+    this.#bySocket.delete(socket);
+  }
+
+  /** Denials held for one socket — what a test bounds. */
+  count(socket: SyncSocket): number {
+    return this.#bySocket.get(socket)?.size ?? 0;
+  }
+}

package/src/channel-logs.ts

@@ -2,7 +2,7 @@
 // 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 { logger, renderThrowable, uuidV7 } from '@ultimat3/core';
 import type { ChangeEvent } from './changefeed';
 import type { Channel } from './channel-decl';
 import { carriesTable, updatesFor } from './channel-records';
@@ -22,7 +22,7 @@ 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();
+  readonly #hubId = uuidV7();
   #rings = 0;
   readonly #byTopic = new Map<
     string,
@@ -59,14 +59,14 @@ export class ChannelLogs {
    * the change is somebody else's too, and one malformed image must not stop the rest.
    */
   deliverChange(channels: Iterable<Channel>, change: ChangeEvent): number {
-    if (change.op === 'truncate') return this.#truncated(change.entity);
+    if (change.op === 'truncate') return this.invalidate(change.table);
     let frames = 0;
     let updates: ReturnType<typeof updatesFor>;
     try {
       updates = updatesFor(channels, change);
     } catch (error) {
       logger.warn('channel.records_unkeyed', {
-        table: change.entity,
+        table: change.table,
         error: renderThrowable(error),
       });
       return 0;
@@ -74,7 +74,12 @@ export class ChannelLogs {
     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);
+      // The change could not carry the whole row (`channel-records.ts`): members re-read it.
+      if (update.gap === true) {
+        frames += this.#reopen(update.topic, open.target);
+        continue;
+      }
+      const entry = open.ring.append(update.adopt, update.remove, change.write ?? undefined);
       const frame = renderRecords(update.topic, open.ring.epoch, entry);
       frames += this.#sockets.deliverRecords(update.topic, open.ring.epoch, frame);
     }
@@ -82,22 +87,33 @@ export class ChannelLogs {
   }
 
   /**
-   * Every row of `table` is gone, and no frame can say which ones a member holds. Each open topic
-   * of a channel carrying it starts a NEW epoch — nothing in the old ring may be replayed onto a
-   * table that no longer has those rows — and every member is told `replay-gap` at it, which the
-   * client answers by re-running the channel's catch-up read.
+   * This node may have missed a change, and seq is minted HERE from the changes it sees, so the
+   * hole is invisible to the ring: the next change would be appended as the next seq and a
+   * `since` replayed across it as complete history. Every open topic that carries records — or,
+   * given a `table`, every one carrying THAT table — starts a new epoch and tells its members
+   * `replay-gap`, which the client answers by re-running the channel's catch-up read.
+   *
+   * With a table, three callers: a gap on the bus (none), a truncate (every row of it is gone, and
+   * no frame can say which ones a member holds), and a bulk write the in-process replicator saw
+   * as a fact rather than as rows (`live-replicator.ts`).
    */
-  #truncated(table: string): number {
+  invalidate(table?: string): number {
     let announced = 0;
     for (const [topic, open] of [...this.#byTopic]) {
-      if (!carriesTable(open.target.channel, table)) continue;
-      this.#byTopic.delete(topic);
-      const ring = this.open(topic, open.target);
-      announced += this.#sockets.announceGap(topic, ring.epoch);
+      if (open.target.channel.records.length === 0) continue;
+      if (table !== undefined && !carriesTable(open.target.channel, table)) continue;
+      announced += this.#reopen(topic, open.target);
     }
     return announced;
   }
 
+  /** A new epoch for one topic — nothing in the old ring may be replayed — and a gap to each member. */
+  #reopen(topic: string, target: ChannelTopic): number {
+    this.#byTopic.delete(topic);
+    const ring = this.open(topic, target);
+    return this.#sockets.announceGap(topic, ring.epoch);
+  }
+
   /**
    * 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`.
@@ -107,6 +123,10 @@ export class ChannelLogs {
    * 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.
+   *
+   * A `since` that is already CURRENT is answered too: the frame AT its cursor, carrying nothing.
+   * Sent nothing, the client had no frame to leave `joining` on — a channel that was up to date
+   * read as never joined. The seq is one it already holds, so its cursor does not move.
    */
   resume(socket: SyncSocket, topic: string, since: ChannelSince | undefined, fresh: boolean): void {
     const open = this.#byTopic.get(topic);
@@ -124,7 +144,8 @@ export class ChannelLogs {
       if (!socket.send(frame)) socket.gaps.set(topic, open.ring.epoch);
       return;
     }
-    for (const entry of entries) {
+    const answer = entries.length > 0 ? entries : [{ seq: open.ring.seq, adopt: [], remove: [] }];
+    for (const entry of answer) {
       if (!socket.send(renderRecords(topic, open.ring.epoch, entry))) {
         socket.gaps.set(topic, open.ring.epoch);
         return;

package/src/channel-presence.ts

@@ -2,7 +2,7 @@
 // `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 { isParsedJsonObject, type JsonObject } from './json';
 import { FRAME_LIMITS, type PresenceMember } from './sync-protocol';
 
 export type PresenceOp = 'join' | 'leave' | 'update' | 'sync';
@@ -60,9 +60,9 @@ export function readPresence(event: JsonObject): PresenceEvent | null {
 }
 
 function memberOf(value: unknown): PresenceMember | null {
-  if (!isJsonObject(value)) return null;
+  if (!isParsedJsonObject(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 };
+  return { id, actorId, meta: isParsedJsonObject(meta) ? meta : {}, updatedAt };
 }

package/src/channel-records.ts

@@ -2,6 +2,7 @@
 // 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 Counter, counter, logger } from '@ultimat3/core';
 import type { Row } from '@ultimat3/core/page';
 import type { RecordProjection } from '@ultimat3/entity/record';
 import type { ChangeEvent } from './changefeed';
@@ -16,16 +17,35 @@ export interface TopicUpdate {
   readonly adopt: readonly RecordPart[];
   readonly remove: readonly { readonly type: string; readonly key: string }[];
   readonly row: Row;
+  /**
+   * The change could not carry this row whole (`ChangeEvent.omitted` names a column the record
+   * projects), so there is nothing sound to adopt: the topic's members are told to re-read.
+   */
+  readonly gap?: true;
+}
+
+const removalsSkipped: Counter = counter('channel_removals_skipped_total', {
+  unit: '{removal}',
+  description:
+    'Channel record removals that could not be routed: the old row image lacked the channel params (the table is not REPLICA IDENTITY FULL), so members keep the removed record.',
+});
+let skipped = 0;
+
+/** Removals this process could not route since boot — the in-process read of the counter above. */
+export function skippedRemovals(): number {
+  return skipped;
 }
 
 /**
- * `change.entity` is the replicated RELATION name (`pg-replication.ts` reads it off the Relation
+ * `change.table` 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.
+ *   `before` image, i.e. `REPLICA IDENTITY FULL`; a key-only image names no topic and is skipped
+ *   — COUNTED and logged (`channel.removal_skipped`), because the members of that topic keep a
+ *   record the database no longer has and nothing else would ever say so.
  */
 export function updatesFor(channels: Iterable<Channel>, change: ChangeEvent): TopicUpdate[] {
   const updates: TopicUpdate[] = [];
@@ -33,23 +53,34 @@ export function updatesFor(channels: Iterable<Channel>, change: ChangeEvent): To
   // open topic of every channel carrying the relation instead (`truncatedTopics`).
   if (change.op === 'truncate') return updates;
   for (const channel of channels) {
-    const projection = channel.records.find((candidate) => candidate.table === change.entity);
+    const projection = channel.records.find((candidate) => candidate.table === change.table);
     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);
+    if (before !== null && beforeParams === null && channel.params.length > 0) {
+      skipped += 1;
+      removalsSkipped.add(1);
+      logger.warn('channel.removal_skipped', { channel: channel.name, table: change.table });
+    }
     const afterTopic = afterParams === null ? null : channel.topic(afterParams);
     const beforeTopic = beforeParams === null ? null : channel.topic(beforeParams);
 
     if (after !== null && afterParams !== null && afterTopic !== null) {
+      // An unchanged out-of-line value Postgres logged no bytes for: adopted, the partial row
+      // would be retained in the ring as the whole record and handed to every later joiner.
+      const partial = (change.omitted ?? []).some((column) =>
+        Object.hasOwn(projection.schema.properties ?? {}, column),
+      );
       updates.push({
         channel,
         topic: afterTopic,
         params: afterParams,
-        adopt: [{ type: projection.type, key: projection.key(after), row: after }],
+        adopt: partial ? [] : [{ type: projection.type, key: projection.key(after), row: after }],
         remove: [],
         row: after,
+        ...(partial ? { gap: true as const } : {}),
       });
     }
     if (

package/src/channel-ref.ts

@@ -3,7 +3,7 @@
 // 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 { assertCoded } from '@ultimat3/core/page';
 import { TopicForbiddenError } from './errors';
 
 /** Branded so a raw string can never be published to; `topic()` is the only constructor. */
@@ -49,7 +49,7 @@ export interface ChannelHandle<K extends string = string> {
 }
 
 export function refuseChannel(name: string, detail: string, fix: string): never {
-  invariant(false, 'X_CHANNEL_DECLARATION_INVALID', `channel("${name}"): ${detail}`, fix);
+  assertCoded(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. */

package/src/channel-registry.ts

@@ -3,13 +3,13 @@
 // 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 { assertCoded } from '@ultimat3/core';
 import type { Channel } from './channel-decl';
 
 const channels = new Map<string, Channel>();
 
 export function registerChannel(declared: Channel): Channel {
-  invariant(
+  assertCoded(
     !channels.has(declared.name),
     'X_CHANNEL_DECLARATION_INVALID',
     `two channel() declarations share the name "${declared.name}"`,

package/src/channel-sids.ts

@@ -0,0 +1,37 @@
+// The sid each of a socket's channel seats was answered under, keyed by TOPIC. A sid is client
+// data: keyed by it, one socket minted an entry per fresh sid without bound, and two sids naming
+// one topic aliased one membership — dropping either unsubscribed the other.
+
+import type { Topic } from './channel-decl';
+import type { SyncSocket } from './socket';
+
+/** Weakly keyed by socket, so a socket's entries die with it; bounded by the hub's topic cap. */
+export class ChannelSids {
+  readonly #bySocket = new WeakMap<SyncSocket, Map<Topic, string>>();
+
+  /** The latest sid wins: a repeated `add` under a new sid re-names the one seat, never adds one. */
+  set(socket: SyncSocket, topic: Topic, sid: string): void {
+    const topics = this.#bySocket.get(socket) ?? new Map<Topic, string>();
+    this.#bySocket.set(socket, topics.set(topic, sid));
+  }
+
+  /** The sid a refusal for this seat must name — `undefined` when the socket holds no such seat. */
+  sidOf(socket: SyncSocket, topic: Topic): string | undefined {
+    return this.#bySocket.get(socket)?.get(topic);
+  }
+
+  /** The topic currently held under `sid`. A sid an earlier `add` was re-named away from holds none. */
+  topicOf(socket: SyncSocket, sid: string): Topic | undefined {
+    for (const [topic, held] of this.#bySocket.get(socket) ?? []) if (held === sid) return topic;
+    return undefined;
+  }
+
+  delete(socket: SyncSocket, topic: Topic): void {
+    this.#bySocket.get(socket)?.delete(topic);
+  }
+
+  /** Seats recorded for one socket — what a test bounds. */
+  count(socket: SyncSocket): number {
+    return this.#bySocket.get(socket)?.size ?? 0;
+  }
+}