@ultimat3/realtime 20.2.1 → 22.0.0

package/src/browser-socket.ts

@@ -0,0 +1,42 @@
+// The ONE `new WebSocket` in the framework. The page opens one socket, through this adapter; an
+// island never dials, and neither does an app. Four handlers and a send — the reconnect, the
+// backoff and the heartbeat all stay in `LiveClient`, which is why this is the whole adapter.
+
+import type { ClientSocket } from './client-contract';
+import type { SyncTarget } from './page-store';
+
+export function browserSocket(url: string): ClientSocket {
+  const socket = new WebSocket(url);
+  return {
+    send: (data: string): void => {
+      socket.send(data);
+    },
+    close: (code?: number, reason?: string): void => {
+      socket.close(code, reason);
+    },
+    onOpen: (handler: () => void): void => {
+      socket.onopen = (): void => {
+        handler();
+      };
+    },
+    onMessage: (handler: (data: string) => void): void => {
+      socket.onmessage = (event: MessageEvent): void => {
+        handler(String(event.data));
+      };
+    },
+    onClose: (handler: (code: number) => void): void => {
+      socket.onclose = (event: CloseEvent): void => {
+        handler(event.code);
+      };
+    },
+    get bufferedAmount(): number {
+      return socket.bufferedAmount;
+    },
+  };
+}
+
+/** `?build=` rides the dial, so a stale tab is told to reload on the socket it opens. */
+export function dialUrl(target: SyncTarget): string {
+  const joiner = target.url.includes('?') ? '&' : '?';
+  return `${target.url}${joiner}build=${encodeURIComponent(target.buildId)}`;
+}

package/src/changefeed.ts

@@ -11,7 +11,13 @@ import type { PgTarget } from './pg-socket';
 import type { PgStream } from './pg-wire';
 import type { Rng } from './thundering-herd';
 
-export type ChangeOp = 'insert' | 'update' | 'delete';
+/**
+ * `truncate` carries no row — `before` and `after` are both `null` — and means every row of the
+ * relation is gone. A window cannot be patched from it, only re-read; a channel's members are told
+ * to re-read (`replay-gap`). It was decoded and dropped, so with the recommended `FOR ALL TABLES`
+ * publication every window and every client kept the truncated rows forever.
+ */
+export type ChangeOp = 'insert' | 'update' | 'delete' | 'truncate';
 
 export interface ChangeEvent<R extends Row = Row> {
   /** Entity name, not table name — the matcher's dependency sets are declared in entity terms. */
@@ -26,6 +32,13 @@ export interface ChangeEvent<R extends Row = Row> {
   readonly orgId: string | null;
   /** Commit time, epoch ms. */
   readonly at: number;
+  /**
+   * The write that made this change: `writeDigest` of the idempotency key its request carried
+   * (`@ultimat3/core`). Absent for a change no keyed request made. Read off the WAL message the
+   * Postgres driver writes first in the transaction, or off the request scope in-process; a
+   * channel stamps it on the `records` frame so the writing page recognises its own echo.
+   */
+  readonly write?: string;
 }
 
 export interface ChangeFeedStartOptions {

package/src/channel-authz.ts

@@ -0,0 +1,52 @@
+// 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.
+
+import { type Actor, type Ctx, createContext, runWithContext } from '@ultimat3/core';
+import { guard, QueryDeniedError } from '@ultimat3/query';
+import type { Channel } from './channel-decl';
+import { 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.
+ */
+export async function authorizeChannel(
+  channel: Channel,
+  ctx: Ctx,
+  actor: Actor | null,
+  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 }));
+  try {
+    guard(channel.policy, { actor, input: params, row, ctx: scoped, query: channel.name }, 'live');
+  } catch (error) {
+    if (!(error instanceof QueryDeniedError)) throw error;
+    throw new TopicForbiddenError({
+      topic,
+      actorId: actor === null ? null : actor.id,
+      reason: `channel "${channel.name}" policy denied the subscribe`,
+    });
+  }
+}
+
+/** 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({
+    actor,
+    role: node.role,
+    buildId: node.buildId,
+    clock: node.clock,
+    locale: node.locale,
+    tz: node.tz,
+  });
+}

package/src/channel-bridge.ts

@@ -0,0 +1,34 @@
+// One topic's transport bridge into this node — the shape `ChannelHub` refcounts, and its safe
+// close.
+
+import type { TransportSubscription } from './fanout';
+
+/**
+ * One topic's fanout into this node. `sub` is the transport subscription as a PROMISE, published
+ * into the table before it is awaited: looked up before the await and written after it, two sockets
+ * reaching one topic at once opened two transport subscriptions — the second replacing the first in
+ * the table, and the first then unreachable by `#release`, by a socket dying, by `close()` or by
+ * anything else, delivering every message on that topic a second time for the life of the process.
+ *
+ * `null` means the slot is taken and nothing is open yet: the node cap is decided before the guard
+ * runs, so the reservation has to exist before there is anything to reserve it with.
+ */
+export interface Bridge {
+  sub: Promise<TransportSubscription> | null;
+  refs: number;
+}
+
+/**
+ * A bridge released while its subscription is still opening still has to be closed — the transport
+ * hands the handle back after the caller has gone, and dropping the promise would leave a live
+ * subscription this node can no longer name. An open that failed has nothing to unsubscribe and its
+ * rejection was already answered to the subscriber that caused it.
+ */
+export function unsubscribeWhenOpen(bridge: Bridge): void {
+  void bridge.sub?.then(
+    (sub) => {
+      sub.unsubscribe();
+    },
+    () => undefined,
+  );
+}

package/src/channel-decl.ts

@@ -0,0 +1,155 @@
+// `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). REQUIRED, as on an `action` and a `query`: it was optional, and an omitted
+   * one let any socket — anonymous included — join with any param and receive every committed row.
+   * A public channel says so with `allow('public')`. 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;
+  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'], policy, 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;
+  // The type requires it; this is the refusal a JS caller, or a cast, reaches.
+  const policy = (init as Partial<ChannelServerInit>).policy;
+  if (policy === undefined) {
+    refuseChannel(
+      name,
+      'declares no policy, so any socket, anonymous included, could join and receive every row',
+      "add policy: can('<resource>:read') to the channel() call, or policy: allow('public') for a channel anyone may join",
+    );
+  }
+  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,
+    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,35 @@
+// 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. Never absent since 22.0.0 — `channel()` requires a policy, and a
+   * channel any socket may join reads `allow('public')`'s label, said out loud.
+   */
+  readonly policy: string;
+  /** 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: policyCapability(declared.policy),
+    permissions: [...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,134 @@
+// 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 { carriesTable, 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 {
+    if (change.op === 'truncate') return this.#truncated(change.entity);
+    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;
+  }
+
+  /**
+   * 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.
+   */
+  #truncated(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);
+    }
+    return announced;
+  }
+
+  /**
+   * 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 };
+}