@ultimat3/realtime 20.2.1 → 22.0.0

package/src/pg-entity-row.ts

@@ -1,198 +1,51 @@
-// Physical Postgres row -> entity-row shaping: snake_case columns become camelCase properties,
-// 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';
+// Physical Postgres row -> the entity row the app declared, by `@ultimat3/entity`'s own decoder.
+// The relation names the table, `entityForTable` names the entity, and `decodeRow` shapes the row
+// by each column's declared KIND — money included — exactly as a repository read does.
+//
+// It GUESSED, until 22.0.0: snake_case camelCased by string rules and any `<p>_minor`/`<p>_currency`
+// pair folded into money by name. So a nullable money column diverged from the repository shape,
+// two plain columns that happened to be called `x_minor`/`x_currency` were folded into a `Money`,
+// and a `.column()` rename arrived under its physical name. One decoder, the entity's, now.
+
+import { decodeRow, entityForTable } from '@ultimat3/entity';
 import { ReplicationProtocolError } from './errors';
-import type { PhysicalRow, PhysicalValue } from './pg-values';
-
-/** `org_id` -> `orgId`, `published_at` -> `publishedAt`. The inverse of `@ultimat3/entity`'s `snake()`. */
-export function camel(column: string): string {
-  const [head = '', ...tail] = column.split('_');
-  return head + tail.map(capitalize).join('');
-}
-
-/** A leading, trailing, or doubled underscore produces an empty part; it contributes nothing. */
-function capitalize(part: string): string {
-  return part.charAt(0).toUpperCase() + part.slice(1);
-}
-
-interface FoldedMoney {
-  readonly property: string;
-  /** The physical columns the fold consumed, in declaration order — named together on a collision. */
-  readonly columns: readonly string[];
-  readonly value: PhysicalRow;
-}
-
-/**
- * `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;
-}
-
-/**
- * `Money` is `{ minor: number; currency: string }` everywhere in the framework, so `minor` is
- * normalised here rather than passed through: `pgoutput` decodes an int8 as text once it leaves
- * `Number.isSafeInteger` range and a numeric as text always, which would otherwise make one column
- * a number on one row and a string on the next. A value no JS number holds exactly is not money
- * this pipeline can carry, and saying so is better than shipping a `minor` the contract forbids.
- */
-function moneyMinor(column: string, value: number | string): number {
-  const minor =
-    typeof value === 'number' ? value : /^-?\d+$/.test(value) ? Number(value) : Number.NaN;
-  if (Number.isSafeInteger(minor)) return minor;
-  throw new ReplicationProtocolError({
-    stage: 'value',
-    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`,
-  });
-}
-
-/**
- * `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: PhysicalValue): 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`,
-  });
-}
+import type { PhysicalRow } from './pg-values';
+import type { PgRelation } from './pgoutput';
 
 /**
- * **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.
+ * A key-only `before` image — any replica identity but FULL — carries NULL for every column that is
+ * not part of the key. Those NULLs are not the row's values, and handed to the decoder a not-null
+ * column would read as a table that no longer matches its entity. They are dropped, so the image
+ * decodes as what it is: the key, and nothing claimed about the rest.
  */
-function shownNumber(value: PhysicalValue): 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, PhysicalValue>>,
-  name: string,
-): FoldedMoney | null {
-  const prefix = moneyPrefix(name);
-  if (prefix === null) return null;
-
-  const minorKey = `${prefix}_minor`;
-  const currencyKey = `${prefix}_currency`;
-  if (!Object.hasOwn(physical, minorKey) || !Object.hasOwn(physical, currencyKey)) return null;
-
-  const minor = physical[minorKey];
-  const currency = physical[currencyKey];
-  if (!(typeof minor === 'number' || typeof minor === 'string') || typeof currency !== 'string') {
-    return null;
+function replicatedOnly(relation: PgRelation, physical: PhysicalRow): PhysicalRow {
+  if (relation.replicaIdentity === 'f') return physical;
+  const keys = new Set(relation.columns.filter((column) => column.key).map((c) => c.name));
+  const kept: PhysicalRow = {};
+  for (const [name, value] of Object.entries(physical)) {
+    if (value !== null || keys.has(name)) kept[name] = value;
   }
-
-  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,
-      ...(scale === undefined || scale === null ? {} : { scale: moneyScale(scaleKey, scale) }),
-    },
-  };
+  return kept;
 }
 
 /**
- * `camel()` is not injective — `a_b` and `a__b` both give `aB`, `x` and `x_` both give `x` — and
- * `entityRow` writes by assignment, so without this the second column would silently overwrite the
- * first and the row would be short one value with nothing to read about it.
+ * The entity row for one replicated tuple. A relation with no registered entity is refused: the
+ * stream only selects tables `replicatedRelations()` named from the entity registry, so one that
+ * arrives unregistered is a process that never loaded the app's entities.
  */
-function claim(taken: Map<string, string>, property: string, column: string): void {
-  const first = taken.get(property);
-  if (first !== undefined) {
+export function entityRow(
+  relation: PgRelation,
+  physical: PhysicalRow,
+  image: 'before' | 'after',
+): PhysicalRow {
+  const entity = entityForTable(relation.name);
+  if (entity === undefined) {
     throw new ReplicationProtocolError({
       stage: 'value',
-      detail: `columns "${first}" and "${column}" both map to the entity property "${property}"`,
-      fix: `rename one of them — two columns cannot share one property once camelCased`,
+      detail: `table "${relation.name}" has no registered entity, so its rows cannot be decoded`,
+      fix: 'load the app before starting the replicator — runRole({ root, env }) does — or drop the table from the entity list',
     });
   }
-  taken.set(property, column);
-}
-
-/**
- * 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 columns `<p>_minor`/`<p>_currency`
- * and the nullable `<p>_scale`.
- */
-export function entityRow(physical: Readonly<Record<string, PhysicalValue>>): PhysicalRow {
-  const row: PhysicalRow = {};
-  // 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>();
-
-  for (const name of Object.keys(physical)) {
-    if (consumed.has(name)) continue;
-
-    const money = foldMoney(physical, name);
-    if (money !== null) {
-      claim(taken, money.property, money.columns.join('/'));
-      row[money.property] = money.value;
-      for (const column of money.columns) consumed.add(column);
-      continue;
-    }
-
-    const property = camel(name);
-    claim(taken, property, name);
-    row[property] = physical[name] ?? null;
-  }
-  return row;
+  const source = image === 'before' ? replicatedOnly(relation, physical) : physical;
+  return decodeRow(entity, source) as PhysicalRow;
 }

package/src/pg-preflight.ts

@@ -45,17 +45,20 @@ export async function preflight(
     throw new ReplicationFailedError({
       stage: 'preflight',
       detail: `wal_level is "${walLevel?.[0] ?? 'unknown'}", so the server writes no logical WAL`,
-      fix: "ALTER SYSTEM SET wal_level = 'logical'; -- then restart postgres",
+      // Not `ALTER SYSTEM`: managed and operator-run Postgres refuse it, and the setting lives in
+      // the provider's configuration. The setting, where it goes, and that it needs a restart.
+      fix: "set wal_level=logical in the server configuration — postgresql.conf, your managed provider's database flags, or `postgres -c wal_level=logical` on a container — then restart postgres",
     });
   }
   const publications = await connection.query(
     `SELECT 1 FROM pg_publication WHERE pubname = '${publication}'`,
   );
   if (publications.length === 0) {
+    const [role] = await connection.query('SELECT current_user');
     throw new ReplicationFailedError({
       stage: 'preflight',
       detail: `no publication named "${publication}" exists`,
-      fix: `CREATE PUBLICATION ${publication} FOR ALL TABLES;`,
+      fix: publicationFix(publication, entities, role?.[0]),
     });
   }
   await warnPartialIdentity(connection, entities);
@@ -77,6 +80,25 @@ export async function preflight(
   }
 }
 
+/**
+ * The publication an app needs is exactly its entities' tables, and `FOR TABLE` is what an app role
+ * that owns them may create — `FOR ALL TABLES`, which this said, needs a superuser a managed
+ * database never hands out. Streaming also needs the `REPLICATION` role attribute, which no fix
+ * line named. Every name here already passed `assertIdentifier`; the role is quoted, because a
+ * role name is whatever the operator chose.
+ */
+function publicationFix(
+  publication: string,
+  entities: ReadonlySet<string>,
+  role: string | null | undefined,
+): string {
+  const tables = [...entities].sort().join(', ');
+  const create = `CREATE PUBLICATION ${publication} FOR TABLE ${tables};`;
+  const who =
+    typeof role === 'string' && role !== '' ? `"${role.replaceAll('"', '""')}"` : 'CURRENT_USER';
+  return `${create} -- and, if the role cannot stream yet: ALTER ROLE ${who} WITH REPLICATION;`;
+}
+
 /**
  * The fourth preflight question, and the one that does NOT refuse. A live query decides whether a
  * row left its result set from `change.before`, and under any replica identity but FULL that tuple

package/src/pg-replication.ts

@@ -13,7 +13,7 @@ import { entityRow } from './pg-entity-row';
 import { assertIdentifier, preflight } from './pg-preflight';
 import { bunPgStream, parsePgUrl } from './pg-socket';
 import type { PhysicalRow } from './pg-values';
-import { PgOutputDecoder, type PgOutputMessage, type PgRelation } from './pgoutput';
+import { keyedWrite, PgOutputDecoder, type PgOutputMessage, type PgRelation } from './pgoutput';
 
 const DEFAULT_STATUS_INTERVAL_MS = 10_000;
 
@@ -64,6 +64,8 @@ interface Transaction {
   readonly xid: number;
   /** Position of the next row inside this transaction. Reproducible, which is what makes it usable. */
   sequence: number;
+  /** The keyed write this transaction is (`ChangeEvent.write`), from its opening WAL message. */
+  write?: string | undefined;
 }
 
 /**
@@ -171,7 +173,7 @@ export class PgReplicationStream {
       this.#confirmed = from === undefined ? 0n : commitPositionOf(from);
       await connection.startCopyBoth(
         `START_REPLICATION SLOT ${slot} LOGICAL ${printLsn(this.#confirmed)} ` +
-          `(proto_version '1', publication_names '${publication}')`,
+          `(proto_version '1', publication_names '${publication}', messages 'true')`,
       );
     } catch (failure) {
       // The dial failure is the one that explains the boot, so a teardown that also failed must
@@ -318,6 +320,10 @@ export class PgReplicationStream {
           sequence: 0,
         };
         return;
+      case 'message':
+        // The driver's first statement in a keyed write: every row after it is that write's.
+        if (this.#transaction !== null) this.#transaction.write ??= keyedWrite(message);
+        return;
       case 'commit':
         this.#transaction = null;
         if (message.endLsn > this.#confirmed) this.#confirmed = message.endLsn;
@@ -331,8 +337,15 @@ export class PgReplicationStream {
       case 'delete':
         await this.#deliver('delete', message.relation, message.before, null, handlers);
         return;
+      case 'truncate':
+        // One change per truncated relation, rowless. It was decoded and DROPPED here, and with the
+        // recommended `FOR ALL TABLES` publication every window and every client kept the rows.
+        for (const relation of message.relations) {
+          await this.#deliver('truncate', relation, null, null, handlers);
+        }
+        return;
       default:
-        // Relation, truncate, origin, type, logical message: nothing the matcher can act on.
+        // Relation, origin, type, logical message: nothing the matcher can act on.
         return;
     }
   }
@@ -369,9 +382,11 @@ export class PgReplicationStream {
     // Read off the Relation message rather than off the tuple: a DEFAULT-identity table whose
     // non-key columns happen to be NULL sends the same bytes a FULL one does, so counting missing
     // keys would undercount exactly the rows a policy is most likely to misjudge.
-    if (op !== 'insert' && relation.replicaIdentity !== 'f') this.#partialBefore += 1;
-    const before = toRow(relation, oldTuple);
-    const after = toRow(relation, newTuple);
+    if ((op === 'update' || op === 'delete') && relation.replicaIdentity !== 'f') {
+      this.#partialBefore += 1;
+    }
+    const before = toRow(relation, oldTuple, 'before');
+    const after = toRow(relation, newTuple, 'after');
     const event: ChangeEvent = {
       entity: relation.name,
       op,
@@ -381,6 +396,7 @@ export class PgReplicationStream {
       txid: transaction.xid.toString(10),
       orgId: tenantOf(after ?? before),
       at: transaction.commitAt,
+      ...(transaction.write === undefined ? {} : { write: transaction.write }),
     };
     await handlers.onChange(event);
     this.#lastLsn = lsn;
@@ -455,9 +471,13 @@ export class PgReplicationStream {
 }
 
 /** A physical tuple becomes the row the matcher's predicates are written against, or nothing. */
-function toRow(relation: PgRelation, physical: PhysicalRow | null): Row | null {
+function toRow(
+  relation: PgRelation,
+  physical: PhysicalRow | null,
+  image: 'before' | 'after',
+): Row | null {
   if (physical === null) return null;
-  const row = entityRow(physical);
+  const row = entityRow(relation, physical, image);
   // A bigserial id decodes as a number inside `Number.isSafeInteger` range and as text outside it,
   // so the same table would otherwise identify small rows by number and large ones by string.
   // `Row.id`, `RowPatch.id` and every cursor are text: the identity is normalised once, here.

package/src/pg-wire.ts

@@ -36,7 +36,17 @@ const MAX_MESSAGE_BYTES = 64 * 1024 * 1024;
  */
 export class MessageReader {
   readonly #stream: PgStream;
+  /** Bytes of messages whose length is not yet known, or complete ones not yet taken. */
   #buffer: Uint8Array = new Uint8Array(0);
+  /**
+   * One message whose length IS known and whose bytes are still arriving: allocated once at its
+   * full size and filled in place. Joining every chunk onto what was held re-copied the whole
+   * message per chunk — quadratic, measured at 5.2 s of blocked event loop for one 32 MB CopyData
+   * on the replication connection every live window depends on.
+   */
+  #pending: { readonly bytes: Uint8Array; filled: number } | null = null;
+  /** Messages completed out of `#pending`, in arrival order, ahead of anything in `#buffer`. */
+  readonly #ready: Uint8Array[] = [];
 
   constructor(stream: PgStream) {
     this.#stream = stream;
@@ -44,7 +54,8 @@ export class MessageReader {
 
   /** Bytes already read but not yet consumed — what a reconnect would have to replay. */
   get buffered(): number {
-    return this.#buffer.length;
+    const ready = this.#ready.reduce((sum, bytes) => sum + bytes.length, 0);
+    return this.#buffer.length + (this.#pending?.filled ?? 0) + ready;
   }
 
   /** The next complete message, or `undefined` at a clean EOF. */
@@ -54,10 +65,11 @@ export class MessageReader {
       if (framed !== undefined) return framed;
       const chunk = await this.#stream.read();
       if (chunk === undefined) {
-        if (this.#buffer.length === 0) return undefined;
+        const held = this.buffered;
+        if (held === 0) return undefined;
         throw new ReplicationProtocolError({
           stage: 'read',
-          detail: `the connection closed with ${this.#buffer.length} bytes of a partial message`,
+          detail: `the connection closed with ${held} bytes of a partial message`,
           fix: 'x doctor db — the backend was terminated mid-message; the server log names the reason',
         });
       }
@@ -66,18 +78,33 @@ export class MessageReader {
   }
 
   #append(chunk: Uint8Array): void {
+    let rest = chunk;
+    const pending = this.#pending;
+    if (pending !== null) {
+      const take = Math.min(pending.bytes.length - pending.filled, rest.length);
+      pending.bytes.set(rest.subarray(0, take), pending.filled);
+      pending.filled += take;
+      rest = rest.subarray(take);
+      if (pending.filled < pending.bytes.length) return;
+      this.#ready.push(pending.bytes);
+      this.#pending = null;
+    }
+    if (rest.length === 0) return;
     if (this.#buffer.length === 0) {
-      this.#buffer = chunk;
+      this.#buffer = rest;
       return;
     }
-    const joined = new Uint8Array(this.#buffer.length + chunk.length);
+    // Only ever a few bytes are held here: a message whose length is known moves to `#pending`.
+    const joined = new Uint8Array(this.#buffer.length + rest.length);
     joined.set(this.#buffer, 0);
-    joined.set(chunk, this.#buffer.length);
+    joined.set(rest, this.#buffer.length);
     this.#buffer = joined;
   }
 
   /** A message is `tag` + Int32 length that counts itself but not the tag. */
   #take(): PgMessage | undefined {
+    const done = this.#ready.shift();
+    if (done !== undefined) return messageOf(done);
     const buffer = this.#buffer;
     if (buffer.length < 5) return undefined;
     const length = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength).getInt32(
@@ -92,16 +119,24 @@ export class MessageReader {
       });
     }
     const total = length + 1;
-    if (buffer.length < total) return undefined;
-    const message: PgMessage = {
-      tag: String.fromCharCode(buffer[0] ?? 0),
-      body: buffer.subarray(5, total),
-    };
+    if (buffer.length < total) {
+      // The length is known, so the message gets its one allocation now and fills in place.
+      const bytes = new Uint8Array(total);
+      bytes.set(buffer, 0);
+      this.#pending = { bytes, filled: buffer.length };
+      this.#buffer = new Uint8Array(0);
+      return undefined;
+    }
     this.#buffer = buffer.subarray(total);
-    return message;
+    return messageOf(buffer.subarray(0, total));
   }
 }
 
+const messageOf = (whole: Uint8Array): PgMessage => ({
+  tag: String.fromCharCode(whole[0] ?? 0),
+  body: whole.subarray(5),
+});
+
 /** `tag` + Int32 length + body — the shape of every frontend message except the startup packet. */
 export const frame = (tag: string, body: Uint8Array): Uint8Array =>
   new ByteWriter(body.length + 5)
@@ -189,10 +224,11 @@ export const FIXES: Readonly<Record<string, string>> = {
   // the half of #97 that outlived the three log-injection holes. The publication is the operator's
   // to create; the slot the replicator creates for itself on its next start.
   '42704':
-    'psql "$REPLICATION_URL" -c "CREATE PUBLICATION x_changes FOR ALL TABLES"' +
-    "   # x_changes is the default name; use REPLICATION_PUBLICATION's value where it is set. " +
+    'psql "$REPLICATION_URL" -c "CREATE PUBLICATION x_changes FOR TABLE <every entity table>"' +
+    "   # x_changes is the default name; use REPLICATION_PUBLICATION's value where it is set, and FOR TABLE because FOR ALL TABLES needs a superuser. " +
     "The slot is the replicator's own and it creates one on its next start",
-  '0A000': 'set wal_level = logical in postgresql.conf and restart the server',
+  '0A000':
+    "set wal_level=logical in the server configuration (postgresql.conf, or your managed provider's database flags) and restart the server",
 };
 
 /** What a SQLSTATE this table has no entry for is answered with. */

package/src/pgoutput.ts

@@ -5,6 +5,7 @@
 // What a tuple's TEXT means is `pg-values.ts`'s: this file frames messages, that one owns the type
 // catalogue that turns postgres' text into the value a repository row holds.
 
+import { isWriteDigest, WRITE_ORIGIN_WAL_PREFIX } from '@ultimat3/core';
 import { ReplicationProtocolError } from './errors';
 import { ByteReader, pgTimestampToEpochMs } from './pg-bytes';
 import { decodeValue, type PhysicalRow } from './pg-values';
@@ -50,7 +51,14 @@ export type PgOutputMessage =
     }
   | { readonly kind: 'delete'; readonly relation: PgRelation; readonly before: PhysicalRow }
   | { readonly kind: 'truncate'; readonly relations: readonly PgRelation[] }
-  /** origin / type / logical message — decoded far enough to be skipped safely. */
+  /** `pg_logical_emit_message` — sent only when START_REPLICATION asks with `messages 'true'`. */
+  | {
+      readonly kind: 'message';
+      readonly transactional: boolean;
+      readonly prefix: string;
+      readonly content: string;
+    }
+  /** origin / type — decoded far enough to be skipped safely. */
   | { readonly kind: 'other'; readonly tag: string };
 
 /**
@@ -103,6 +111,31 @@ function decodeTupleData(reader: ByteReader, relation: PgRelation): PhysicalRow
   return row;
 }
 
+/**
+ * Int8 flags (bit 1: transactional) · Int64 lsn · String prefix · Int32 length · Byte[length]. No
+ * xid: that field exists only inside a streamed transaction, which this stream never asks for.
+ */
+function decodeMessage(reader: ByteReader): PgOutputMessage {
+  const transactional = (reader.uint8() & 1) === 1;
+  reader.int64();
+  const prefix = reader.cstring();
+  const content = reader.utf8(reader.int32());
+  return { kind: 'message', transactional, prefix, content };
+}
+
+/**
+ * The write a transactional message names — `@ultimat3/entity`'s Postgres driver opens a keyed
+ * write's transaction with one — or `undefined` for any other message an app or extension emits.
+ */
+export function keyedWrite(message: {
+  readonly transactional: boolean;
+  readonly prefix: string;
+  readonly content: string;
+}): string | undefined {
+  const named = message.transactional && message.prefix === WRITE_ORIGIN_WAL_PREFIX;
+  return named && isWriteDigest(message.content) ? message.content : undefined;
+}
+
 /**
  * Holds the relation cache: postgres sends a `Relation` message once per table per connection and
  * every later tuple references it by oid, so a decoder instance is per-connection and is thrown
@@ -129,7 +162,9 @@ export class PgOutputDecoder {
         return this.#decodeDelete(reader);
       case 'T':
         return this.#decodeTruncate(reader);
-      // 'O' (origin), 'Y' (type), 'M' (logical message), and any tag a newer server invents:
+      case 'M':
+        return decodeMessage(reader);
+      // 'O' (origin), 'Y' (type), and any tag a newer server invents:
       // nothing downstream needs them decoded, and guessing at an unknown tag's shape is how a
       // truncated read turns into a silent misread instead of a clean skip.
       default:

package/src/policy-fake.ts

@@ -0,0 +1,14 @@
+// A policy that admits every caller, for the tests that declare a channel whose authz is not
+// their subject. Structural, never built with `@ultimat3/policy`: realtime reaches that package
+// only through `@ultimat3/query`'s `guard`, and a direct import would be a second authz path.
+// An app says the same thing with `allow('public')`, which is what this stands in for.
+
+import type { QueryPolicy } from '@ultimat3/query';
+
+export const OPEN_POLICY: QueryPolicy = Object.freeze({
+  kind: 'allow',
+  label: 'public',
+  permissions: [],
+  children: [],
+  run: () => ({ allowed: true as const }),
+});

package/src/presence.ts

@@ -3,12 +3,16 @@
 // Presence lives in `transport.shared`, never in a node's heap: when a `sync` node dies its members
 // 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.
+// On the wire it is not a frame kind: a roster change is an `events` frame on the channel the member
+// joined (`channel-presence.ts` is the payload), so only a channel declared `events: true` has one.
 
 import { type Clock, finiteOption, systemClock, uuid } from '@ultimat3/core';
 import type { ChannelHub, Topic } from './channel';
+import { presenceEvent } from './channel-presence';
+import type { ChannelEventsFrame } from './channel-wire';
 import type { Transport } from './fanout';
 import type { JsonObject } from './json';
-import { type Frame, PROTOCOL_VERSION, type PresenceMember } from './sync-protocol';
+import { 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. */
@@ -218,7 +222,7 @@ export class PresenceRegistry {
   }
 
   /** Full-set frame for a client that just (re)connected — presence has no delta protocol. */
-  async syncFrame(name: Topic): Promise<Frame> {
+  async syncFrame(name: Topic): Promise<ChannelEventsFrame> {
     const roster = await this.roster(name);
     return presenceFrame(name, 'sync', roster.members, roster.total);
   }
@@ -256,23 +260,27 @@ export class PresenceRegistry {
     members: readonly PresenceMember[],
   ): Promise<void> {
     if (!this.#hub) return;
-    await this.#hub.publishFrame(name, presenceFrame(name, op, members));
+    await this.#hub.emit(name, presenceEvent(op, members));
   }
 }
 
 /**
- * `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.
+ * The roster as the `events` frame ONE socket is sent directly — the join reply. Everything else
+ * reaches sockets through `ChannelHub.emit`, the channel's own events path. `total` belongs to a
+ * full `sync` set and to nothing else: a delta carries the members that changed.
  */
 export function presenceFrame(
   name: Topic,
   op: 'join' | 'leave' | 'update' | 'sync',
   members: readonly PresenceMember[],
   total?: number,
-): Frame {
-  const base = { type: 'presence', v: PROTOCOL_VERSION, topic: name, op, members } as const;
-  return total === undefined ? base : { ...base, total };
+): ChannelEventsFrame {
+  return {
+    type: 'events',
+    v: PROTOCOL_VERSION,
+    channel: name,
+    event: presenceEvent(op, members, total),
+  };
 }
 
 function parseMember(id: string, value: string): PresenceMember | null {