@ultimat3/realtime 20.2.1 → 22.0.0

package/src/record-store.ts

@@ -0,0 +1,364 @@
+// The page's ONE record store — Ember Data's shape: one record per `type:key`, shown in N places,
+// updated once. Two layers: SYNCED is server truth (HTTP envelopes, socket frames), and the
+// OVERLAY is every pending optimistic write, replayed over synced truth on every change. It is
+// core's `RecordSink`, so `clientTransport` adopts into it without importing this package.
+
+import type { ConflictPolicy, RecordRows, RecordSink, Row } from '@ultimat3/core/page';
+import { resolveConflict } from '@ultimat3/core/page';
+import { RebaseConflictError, RecordRejectedError } from './page-errors';
+import { ServerWait } from './record-await';
+import { isRow, type RecordKey, recordKey } from './record-key';
+import { WriteNames } from './record-names';
+import { SyncedLayer } from './record-synced';
+import { type OverlayEntry, replayOverlays, sameRow } from './record-tx';
+import type { Scheduler } from './thundering-herd';
+
+// The store's own names for a record, kept importable from here: every caller names a record
+// through the store it reads.
+export { DEFAULT_AWAIT_SERVER_MS } from './record-await';
+export { carriedBy, type RecordKey, recordKey } from './record-key';
+
+export type RecordListener = (changed: ReadonlySet<RecordKey>) => void;
+
+export interface RecordStoreOptions {
+  /** Where a rejected row is reported. Browser code: `console.error`, never core's `logger`. */
+  readonly report?: (error: unknown) => void;
+  /** How an overlay's wait for server truth is bounded. Defaults to `setTimeout`; tests inject. */
+  readonly schedule?: Scheduler;
+  /** How long an overlay waits for the server's row before the synced layer stands. */
+  readonly awaitMs?: number;
+}
+
+export class RecordStore implements RecordSink {
+  readonly #synced = new SyncedLayer();
+  /** The overlay's answer per key: a row, or `null` for a record the overlay deleted. */
+  #view = new Map<RecordKey, Row | null>();
+  readonly #overlays = new Map<string, OverlayEntry>();
+  /** Which keys each pending overlay wrote on its last replay — what a settle resolves over. */
+  #touched = new Map<string, ReadonlySet<RecordKey>>();
+  readonly #listeners = new Set<RecordListener>();
+  readonly #report: (error: unknown) => void;
+  #changed: Set<RecordKey> | null = null;
+  #syncedMoved = false;
+  /** Synced keys moved in the open batch — what an overlay awaiting server truth is checked against. */
+  readonly #moved = new Set<RecordKey>();
+  readonly #wait: ServerWait;
+  /** Which pending overlay each write digest names — what a frame's `write` is looked up in. */
+  readonly #names = new WriteNames();
+
+  constructor(options: RecordStoreOptions = {}) {
+    this.#report = options.report ?? ((error) => console.error(error));
+    this.#wait = new ServerWait(options.schedule, options.awaitMs);
+  }
+
+  /** The record as every holder sees it: the overlay's answer over synced truth. */
+  peek(type: string, key: string): Row | undefined {
+    const rk = recordKey(type, key);
+    const overlaid = this.#view.get(rk);
+    if (overlaid !== undefined) return overlaid ?? undefined;
+    return this.#synced.get(rk);
+  }
+
+  /** Every record of one type, as seen — what a mutator's `tx.<type>.all()` walks. */
+  all(type: string): readonly Row[] {
+    const prefix = `${type}:`;
+    const out: Row[] = [];
+    const seen = new Set<RecordKey>();
+    for (const [rk, row] of this.#view) {
+      if (!rk.startsWith(prefix)) continue;
+      seen.add(rk);
+      if (row !== null) out.push(row);
+    }
+    for (const [rk, row] of this.#synced.entries()) {
+      if (rk.startsWith(prefix) && !seen.has(rk)) out.push(row);
+    }
+    return out;
+  }
+
+  /**
+   * `RecordSink.adopt`: server truth, keyed by the server (it holds the entity's primary key; the
+   * browser does not). Merged column by column. A structurally bad row is dropped, never merged.
+   */
+  adopt(type: string, rows: RecordRows): void {
+    this.batch(() => {
+      for (const [key, row] of Object.entries(rows)) {
+        if (!isRow(row) || key === '') {
+          this.#report(
+            new RecordRejectedError({
+              type,
+              reason: key === '' ? 'it arrived under an empty key' : 'it is not an object',
+            }),
+          );
+          continue;
+        }
+        this.merge(type, key, row);
+      }
+    });
+  }
+
+  /** `RecordSink.remove`: the server says these records are gone, for every holder at once. */
+  remove(type: string, keys: readonly string[]): void {
+    this.batch(() => {
+      for (const key of keys) {
+        const rk = recordKey(type, key);
+        if (this.#synced.remove(rk)) this.#touchSynced(rk);
+      }
+    });
+  }
+
+  /** The server's row alone — no overlay, no notification. What the persister writes to disk. */
+  synced(type: string, key: string): Row | undefined {
+    return this.#synced.get(recordKey(type, key));
+  }
+
+  /**
+   * Rows put back from disk before the socket connects. Inserted only where the server has not
+   * already answered, and PROVISIONAL: stale until confirmed, so the first server row for that key
+   * replaces it outright rather than merging a column the server has since dropped.
+   */
+  restore(type: string, rows: RecordRows): void {
+    this.batch(() => {
+      for (const [key, row] of Object.entries(rows)) {
+        const rk = recordKey(type, key);
+        if (!isRow(row) || key === '') continue;
+        if (this.#synced.restore(rk, row)) this.#touchSynced(rk);
+      }
+    });
+  }
+
+  /** One server write, merged column by column (`SyncedLayer.merge`). */
+  merge(type: string, key: string, columns: Row): Row {
+    const rk = recordKey(type, key);
+    const { row, changed } = this.#synced.merge(rk, columns);
+    if (changed) {
+      this.#touchSynced(rk);
+    } else if (this.#overlays.size > 0) {
+      // Unchanged is still an answer: an overlay awaiting server truth for this row — or still in
+      // flight, and about to — gets it here.
+      this.batch(() => {
+        this.#moved.add(rk);
+        this.#syncedMoved = true;
+      });
+    }
+    return row;
+  }
+
+  retain(type: string, key: string): void {
+    this.#synced.retain(recordKey(type, key));
+  }
+
+  /** The last holder leaving evicts the synced record: an infinite scroll must not keep every row. */
+  release(type: string, key: string): void {
+    const rk = recordKey(type, key);
+    if (this.#synced.release(rk)) this.#touchSynced(rk);
+  }
+
+  /**
+   * An optimistic write, visible to every holder before this returns. `apply` is the mutator's
+   * pure `local` half: it is REPLAYED over synced truth whenever synced truth moves, which is what
+   * makes two pending writes on one row land in order over a server update.
+   */
+  push(key: string, apply: OverlayEntry['apply'], policy: ConflictPolicy): void {
+    this.batch(() => {
+      this.#overlays.set(key, { key, apply, policy });
+      this.#replay();
+    });
+    this.#names.name(key, (named) => this.#overlays.has(named));
+  }
+
+  /** Take the write back — the server refused it. Everything behind it replays without it. */
+  drop(key: string): void {
+    this.#wait.forget(key);
+    this.batch(() => {
+      if (this.#forget(key)) this.#replay();
+    });
+  }
+
+  /**
+   * The server took the write, and its records were adopted BEFORE this runs (the transport adopts
+   * inside the call), so the overlay is dropped over truth that already carries it: no flicker.
+   * A non-default policy decides each record the write touched, local view against server row.
+   *
+   * `carried` is the answer's own records. A row the write touched that the answer did NOT carry
+   * (an action that returns a view, not the entity) has no server truth yet: dropping the overlay
+   * would show the pre-write value until a frame arrives. So the overlay waits for that row's next
+   * server write, bounded by `awaitMs`, after which the synced layer stands — unless the server
+   * already reached it while the write was in flight.
+   */
+  settle(key: string, carried?: ReadonlySet<RecordKey>): void {
+    const entry = this.#overlays.get(key);
+    if (entry === undefined) return;
+    this.batch(() => {
+      const touched = this.#touched.get(key) ?? new Set<RecordKey>();
+      if (entry.policy !== 'server-wins') {
+        for (const rk of touched)
+          if (carried === undefined || carried.has(rk)) this.#resolve(entry, rk);
+      }
+      const heard = this.#wait.takeHeard(key);
+      const missing =
+        carried === undefined
+          ? []
+          : [...touched].filter((rk) => !carried.has(rk) && heard?.has(rk) !== true);
+      if (missing.length > 0) {
+        // What the server did answer holds this write already: the twin stays on the rest only.
+        const answered = [...touched].filter((rk) => !missing.includes(rk));
+        if (answered.length > 0) {
+          const confirmed = new Set([...(entry.confirmed ?? []), ...answered]);
+          this.#overlays.set(key, { ...entry, confirmed });
+          this.#replay();
+        }
+        this.#wait.start(key, new Set(missing), () => this.drop(key));
+        return;
+      }
+      this.#forget(key);
+      this.#replay();
+    });
+  }
+
+  /**
+   * A `records` frame's rows, merged in the OPEN batch, named the write `digest`. When that is a
+   * write this page still holds, it is settled here against the rows the frame carried — in the
+   * same notification as the merge, so no holder ever sees the write's own row with its twin
+   * replayed over it (a like counted twice). A digest this page never pushed, or one already
+   * settled, changes nothing: the rows are server truth under whatever is still pending.
+   */
+  settleWrite(digest: string, carried: ReadonlySet<RecordKey>): void {
+    const key = this.#names.keyOf(digest);
+    if (key === undefined || !this.#overlays.has(key)) return;
+    this.batch(() => {
+      // The view the settle resolves a custom policy against is the overlay over the NEW truth —
+      // what an HTTP answer's settle sees too, because its adopt closed a batch first.
+      if (this.#syncedMoved) this.#replay();
+      this.settle(key, carried);
+    });
+  }
+
+  /**
+   * The write's answer was unreadable (a 2xx that is not JSON): it MAY have landed. Its overlay
+   * stays on screen until server truth next reaches a row it wrote — then the server's row stands.
+   * Dropping it now could flash the pre-write value over a write that did land.
+   */
+  awaitServer(key: string): void {
+    if (!this.#overlays.has(key)) return;
+    this.#wait.start(key, this.#touched.get(key) ?? new Set(), () => this.drop(key));
+  }
+
+  /** Pending optimistic writes, oldest first. */
+  pending(): readonly string[] {
+    return [...this.#overlays.keys()];
+  }
+
+  /** A principal change: nothing of the previous one survives in memory. */
+  clear(): void {
+    this.batch(() => {
+      for (const rk of this.#synced.keys()) this.#touch(rk);
+      for (const rk of this.#view.keys()) this.#touch(rk);
+      this.#synced.clear();
+      this.#overlays.clear();
+      this.#names.clear();
+      this.#wait.clear();
+      this.#view = new Map();
+      this.#touched = new Map();
+    });
+  }
+
+  /** Every write inside `fn` is one notification — one frame, one response, one render. */
+  batch<T>(fn: () => T): T {
+    if (this.#changed !== null) return fn();
+    const collected = new Set<RecordKey>();
+    this.#changed = collected;
+    try {
+      return fn();
+    } finally {
+      // Synced truth moved under pending writes: replay them once, at the end, over the new truth.
+      if (this.#syncedMoved) {
+        this.#syncedMoved = false;
+        // A row put back from disk is a guess, not the server reaching it.
+        this.#wait.hear(
+          [...this.#overlays.keys()].map((key) => [key, this.#touched.get(key) ?? new Set()]),
+          (rk) => this.#moved.has(rk) && !this.#synced.isProvisional(rk),
+        );
+        const answered = this.#wait.resolve((key) => this.#overlays.has(key), this.#moved);
+        for (const key of answered) this.#forget(key);
+        if (this.#overlays.size > 0 || answered.length > 0) this.#replay();
+      }
+      this.#moved.clear();
+      this.#changed = null;
+      if (collected.size > 0) for (const listener of this.#listeners) listener(collected);
+    }
+  }
+
+  subscribe(listener: RecordListener): () => void {
+    this.#listeners.add(listener);
+    return () => {
+      this.#listeners.delete(listener);
+    };
+  }
+
+  /** Synced records held. Tests assert on it; nothing branches on a count. */
+  get size(): number {
+    return this.#synced.size;
+  }
+
+  #resolve(entry: OverlayEntry, rk: RecordKey): void {
+    const local = this.#view.get(rk);
+    const server = this.#synced.get(rk);
+    // A delete on either side leaves nothing to merge: the server's answer stands.
+    if (local === undefined || local === null || server === undefined) return;
+    const kept = resolveConflict(entry.policy, local, server);
+    if (kept === server) return;
+    if (!isRow(kept)) {
+      throw new RebaseConflictError({
+        key: entry.key,
+        entity: rk.slice(0, rk.indexOf(':')),
+        reason: 'the custom merge returned something other than a row',
+      });
+    }
+    this.#synced.set(rk, kept);
+    this.#touch(rk);
+  }
+
+  #replay(): void {
+    const previous = this.#view;
+    const result = replayOverlays(
+      [...this.#overlays.values()],
+      (rk) => this.#synced.get(rk),
+      (type) => this.#synced.ofType(type),
+      (error) => this.#report(error),
+    );
+    for (const failed of result.failed) {
+      this.#forget(failed);
+      this.#wait.unhear(failed);
+    }
+    const next = new Map<RecordKey, Row | null>();
+    for (const [rk, row] of result.view) {
+      const before = previous.get(rk);
+      // Same content keeps the same object: a replay that changed nothing re-renders nothing.
+      next.set(rk, before !== undefined && sameRow(before, row) ? before : row);
+      if (before === undefined || !sameRow(before, row)) this.#touch(rk);
+    }
+    for (const rk of previous.keys()) if (!next.has(rk)) this.#touch(rk);
+    this.#view = next;
+    this.#touched = result.touched;
+  }
+
+  /** The one way an overlay leaves: its entry and the digest that named it go together. */
+  #forget(key: string): boolean {
+    this.#names.forget(key);
+    return this.#overlays.delete(key);
+  }
+
+  #touchSynced(rk: RecordKey): void {
+    this.#syncedMoved = true;
+    this.#moved.add(rk);
+    this.#touch(rk);
+  }
+
+  #touch(rk: RecordKey): void {
+    if (this.#changed !== null) {
+      this.#changed.add(rk);
+      return;
+    }
+    this.batch(() => this.#changed?.add(rk));
+  }
+}

package/src/record-synced.ts

@@ -0,0 +1,100 @@
+// The store's SYNCED layer: server truth per `type:key`, merged column by column, with the holds
+// that evict a record nobody renders and the provisional mark on rows restored from disk. Pure
+// state — it answers what moved, and the store decides who hears about it.
+
+import type { Row } from '@ultimat3/core/page';
+import type { RecordKey } from './record-key';
+
+export class SyncedLayer {
+  readonly #rows = new Map<RecordKey, Row>();
+  readonly #holds = new Map<RecordKey, number>();
+  /** Keys restored from disk and not yet confirmed: the first server row REPLACES, never merges. */
+  readonly #provisional = new Set<RecordKey>();
+
+  get(rk: RecordKey): Row | undefined {
+    return this.#rows.get(rk);
+  }
+
+  get size(): number {
+    return this.#rows.size;
+  }
+
+  keys(): IterableIterator<RecordKey> {
+    return this.#rows.keys();
+  }
+
+  entries(): IterableIterator<[RecordKey, Row]> {
+    return this.#rows.entries();
+  }
+
+  /** Every row of one type — what a replay's `tx.<type>.all()` reads under the overlay. */
+  ofType(type: string): readonly [RecordKey, Row][] {
+    const prefix = `${type}:`;
+    return [...this.#rows].filter(([rk]) => rk.startsWith(prefix));
+  }
+
+  isProvisional(rk: RecordKey): boolean {
+    return this.#provisional.has(rk);
+  }
+
+  /**
+   * One server write. Merged, never replaced: a projection that selected fewer columns must not
+   * blank the columns another is rendering, so an omitted (or `undefined`) field is left alone.
+   * Answers the row as it now stands, and whether anything in it changed.
+   */
+  merge(rk: RecordKey, columns: Row): { readonly row: Row; readonly changed: boolean } {
+    // A restored row is a guess from disk: the server's first answer is the whole truth.
+    const current = this.#provisional.delete(rk) ? undefined : this.#rows.get(rk);
+    const next: Record<string, unknown> = { ...current };
+    let changed = current === undefined;
+    for (const [column, value] of Object.entries(columns)) {
+      if (value === undefined) continue;
+      if (current === undefined || current[column] !== value) changed = true;
+      next[column] = value;
+    }
+    if (!changed && current !== undefined) return { row: current, changed: false };
+    const row = Object.freeze(next);
+    this.#rows.set(rk, row);
+    return { row, changed: true };
+  }
+
+  /** A conflict policy's verdict replacing the server row outright. */
+  set(rk: RecordKey, row: Row): void {
+    this.#rows.set(rk, Object.freeze({ ...row }));
+  }
+
+  /** A row from disk, only where the server has not answered. Answers whether it went in. */
+  restore(rk: RecordKey, row: Row): boolean {
+    if (this.#rows.has(rk)) return false;
+    this.#rows.set(rk, Object.freeze({ ...row }));
+    this.#provisional.add(rk);
+    return true;
+  }
+
+  /** Answers whether a row was there to remove. */
+  remove(rk: RecordKey): boolean {
+    this.#provisional.delete(rk);
+    return this.#rows.delete(rk);
+  }
+
+  retain(rk: RecordKey): void {
+    this.#holds.set(rk, (this.#holds.get(rk) ?? 0) + 1);
+  }
+
+  /** The last holder leaving evicts the row. Answers whether a row went. */
+  release(rk: RecordKey): boolean {
+    const holds = this.#holds.get(rk);
+    if (holds === undefined) return false;
+    if (holds > 1) {
+      this.#holds.set(rk, holds - 1);
+      return false;
+    }
+    this.#holds.delete(rk);
+    return this.remove(rk);
+  }
+
+  clear(): void {
+    this.#rows.clear();
+    this.#provisional.clear();
+  }
+}

package/src/record-tx.ts

@@ -0,0 +1,145 @@
+// The optimistic layer: every pending mutator's pure `local(tx, input)` half, replayed in order
+// over synced truth. Replay, not stored results, is the point — a like counted as `likeCount + 1`
+// over the OLD row must become `+ 1` over the row the server just sent, never the stale sum.
+
+import type { ConflictPolicy, Row } from '@ultimat3/core/page';
+
+/** One table as a mutator's `local` half sees it, keyed by record type (the entity's name). */
+export interface LocalTable<R extends Row = Row> {
+  get(key: string): R | undefined;
+  all(): readonly R[];
+  /**
+   * The key is the caller's, never derived here: the browser holds no entity schema, so it cannot
+   * know a primary key. An optimistic insert names the key its server twin will answer under.
+   */
+  insert(key: string, row: R): void;
+  upsert(key: string, row: R): void;
+  /** Changed fields only — or a function returning them; an omitted field is left as it was. */
+  update(key: string, patch: Partial<R> | ((row: R) => Partial<R>)): void;
+  delete(key: string): void;
+}
+
+export type TableMap = Record<string, Row>;
+
+/** `tx.posts`, typed by the app's own entity rows. `tx.table(name)` is the string-named door. */
+export type LocalTx<T extends TableMap = TableMap> = { readonly [K in keyof T]: LocalTable<T[K]> };
+
+export interface OverlayEntry {
+  /** The write's idempotency key — the same key the HTTP dispatch carries. */
+  readonly key: string;
+  readonly policy: ConflictPolicy;
+  apply(tx: LocalTx): void;
+  /**
+   * Rows the server has already answered for THIS write (its echo, or its answer, carried them):
+   * their synced truth holds the write, so a replay leaves them alone and only the rows still
+   * awaiting truth show the twin. Without it, a write whose echo carried one of its two rows
+   * replayed the twin over that row's truth too — the write counted twice until the other arrived.
+   */
+  readonly confirmed?: ReadonlySet<string>;
+}
+
+export interface ReplayResult {
+  readonly view: ReadonlyMap<string, Row | null>;
+  readonly touched: Map<string, ReadonlySet<string>>;
+  /** Entries whose `local` threw: dropped from the overlay and reported, never half-applied. */
+  readonly failed: readonly string[];
+}
+
+/** Shallow content equality — a replay producing the same columns must not re-render anything. */
+export function sameRow(a: Row | null, b: Row | null): boolean {
+  if (a === b) return true;
+  if (a === null || b === null) return false;
+  const keys = Object.keys(a);
+  if (keys.length !== Object.keys(b).length) return false;
+  return keys.every((key) => Object.hasOwn(b, key) && a[key] === b[key]);
+}
+
+export function replayOverlays(
+  entries: readonly OverlayEntry[],
+  synced: (recordKey: string) => Row | undefined,
+  syncedOf: (type: string) => readonly (readonly [string, Row])[],
+  report: (error: unknown) => void,
+): ReplayResult {
+  const view = new Map<string, Row | null>();
+  const touched = new Map<string, ReadonlySet<string>>();
+  const failed: string[] = [];
+  for (const entry of entries) {
+    // Each entry writes into a scratch copy, so a `local` that throws halfway leaves nothing.
+    const scratch = new Map(view);
+    const wrote = new Set<string>();
+    try {
+      entry.apply(txOver(scratch, wrote, synced, syncedOf));
+    } catch (error) {
+      report(error);
+      failed.push(entry.key);
+      continue;
+    }
+    const confirmed = entry.confirmed;
+    const pending = new Set<string>();
+    for (const rk of wrote) {
+      if (confirmed?.has(rk) === true) continue;
+      view.set(rk, scratch.get(rk) ?? null);
+      pending.add(rk);
+    }
+    touched.set(entry.key, pending);
+  }
+  return { view, touched, failed };
+}
+
+function txOver(
+  view: Map<string, Row | null>,
+  wrote: Set<string>,
+  synced: (recordKey: string) => Row | undefined,
+  syncedOf: (type: string) => readonly (readonly [string, Row])[],
+): LocalTx {
+  const tables = new Map<string, LocalTable>();
+  const table = (type: string): LocalTable => {
+    const existing = tables.get(type);
+    if (existing !== undefined) return existing;
+    const rk = (key: string): string => `${type}:${key}`;
+    const read = (key: string): Row | undefined => {
+      const overlaid = view.get(rk(key));
+      return overlaid === undefined ? synced(rk(key)) : (overlaid ?? undefined);
+    };
+    const write = (key: string, row: Row | null): void => {
+      view.set(rk(key), row === null ? null : Object.freeze({ ...row }));
+      wrote.add(rk(key));
+    };
+    const created: LocalTable = {
+      get: read,
+      all: () => {
+        const prefix = `${type}:`;
+        const out = new Map<string, Row | null>();
+        for (const [key, row] of syncedOf(type)) out.set(key, row);
+        for (const [key, row] of view) if (key.startsWith(prefix)) out.set(key, row);
+        return [...out.values()].filter((row): row is Row => row !== null);
+      },
+      insert: (key, row) => write(key, row),
+      upsert: (key, row) => write(key, { ...read(key), ...definedOf(row) }),
+      update: (key, patch) => {
+        const current = read(key);
+        if (current === undefined) return;
+        const changed = typeof patch === 'function' ? patch(current) : patch;
+        write(key, { ...current, ...definedOf(changed) });
+      },
+      delete: (key) => write(key, null),
+    };
+    tables.set(type, created);
+    return created;
+  };
+  return new Proxy({} as LocalTx, {
+    get: (_target, property) => {
+      if (typeof property !== 'string') return undefined;
+      if (property === 'table') return table;
+      return table(property);
+    },
+  });
+}
+
+/** `undefined` in a patch means "leave it alone", exactly as a server merge reads it. */
+function definedOf(columns: Readonly<Record<string, unknown>>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [column, value] of Object.entries(columns))
+    if (value !== undefined) out[column] = value;
+  return out;
+}

package/src/replicator.ts

@@ -11,13 +11,16 @@
 // its feed and reports `/readyz` false; it retries with jittered backoff and takes over the moment
 // the holder dies. Scaling the replicator is therefore always vertical, and that is by design.
 
-import { logger, uuid, withSpan } from '@ultimat3/core';
+import { isWriteDigest, logger, uuid, withSpan } from '@ultimat3/core';
 import type { ChangeEvent, ChangeFeed } from './changefeed';
 import type { Transport } from './fanout';
-import { type BackoffPolicy, backoffDelay, defaultBackoff, type Rng } from './thundering-herd';
+import { type BackoffPolicy, defaultBackoff, policyDelay, type Rng } from './thundering-herd';
 
 export const CHANGE_SUBJECT_PREFIX = 'x.change';
 
+/** Every change subject: what a `sync` node subscribes to. A changefeed subject, never a channel. */
+export const CHANGE_SUBJECT_ALL = `${CHANGE_SUBJECT_PREFIX}.>`;
+
 /** Session-scoped mutual exclusion. Postgres-backed in production, in-memory for `x dev`. */
 export interface AdvisoryLock {
   readonly key: string;
@@ -222,13 +225,16 @@ export function createReplicator(options: ReplicatorOptions): Replicator {
     },
 
     retryDelayMs(attempt: number): number {
-      return backoffDelay(attempt, backoff, options.rng ?? Math.random);
+      // This method's contract is 0-based (`retryDelayMs(0)` is the base); core counts from 1.
+      return policyDelay(backoff, attempt + 1, options.rng ?? Math.random);
     },
   };
 }
 
 /** Drops events the pipeline cannot use and hoists the tenant id out of the row. */
 export function normalize(change: ChangeEvent): ChangeEvent | null {
+  // The one change that carries no row by design; nothing to hoist a tenant out of.
+  if (change.op === 'truncate') return change;
   const row = change.after ?? change.before;
   if (!row) return null;
   if (change.op === 'insert' && change.after === null) return null;
@@ -250,7 +256,14 @@ export function parseEnvelope(payload: string): ChangeEnvelope | null {
     if (typeof parsed !== 'object' || parsed === null) return null;
     const shape = parsed as Partial<ChangeEvent> & { seq?: unknown; producer?: unknown };
     if (typeof shape.entity !== 'string' || typeof shape.lsn !== 'string') return null;
-    if (shape.op !== 'insert' && shape.op !== 'update' && shape.op !== 'delete') return null;
+    if (
+      shape.op !== 'insert' &&
+      shape.op !== 'update' &&
+      shape.op !== 'delete' &&
+      shape.op !== 'truncate'
+    ) {
+      return null;
+    }
     return {
       change: {
         entity: shape.entity,
@@ -261,6 +274,9 @@ export function parseEnvelope(payload: string): ChangeEnvelope | null {
         txid: typeof shape.txid === 'string' ? shape.txid : '',
         orgId: typeof shape.orgId === 'string' ? shape.orgId : null,
         at: typeof shape.at === 'number' ? shape.at : 0,
+        // Only the minted shape crosses: a frame decoder refuses anything else, so a malformed
+        // label here would cost every member the whole frame rather than one page its echo.
+        ...(isWriteDigest(shape.write) ? { write: shape.write } : {}),
       },
       seq: typeof shape.seq === 'number' && Number.isFinite(shape.seq) ? shape.seq : null,
       producer: typeof shape.producer === 'string' ? shape.producer : null,