@ultimat3/realtime 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 developerz.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,180 @@
+# ⚡ @ultimat3/realtime
+
+Three tiers, one ladder, one protocol. Climbing a rung is a config change, never a rewrite.
+
+## The ladder
+
+| Tier | What it gives you | What it costs you |
+|---|---|---|
+| **1 — channels** | `publish`/`subscribe` on typed topics, presence, cursors, typing indicators | ~0. Pub/sub over Bun's native WS. No DB, no replication slot |
+| **2 — live queries** | the list updates when someone else edits; your own click feels instant | one change feed + a matcher per query id + a bounded change window |
+| **3 — local-first** | writes that survive being offline | a durable local store, a rebase log, client-side migrations, a conflict story per mutator |
+
+Tier 2 covers ~90% of "make it realtime". Tier 3 buys exactly one extra property — offline writes — and charges a client database for it. Do not buy it by accident.
+
+## Same mutator at every rung
+
+```ts
+// query
+export const liveFeed = query({
+  input: t.object({ orgId: t.uuid }),
+  policy: can('feed:read'),
+  live: true,
+  sql: ({ orgId }) => db.posts.where({ orgId }).orderBy('createdAt').limit(50),
+});
+
+// mutator (action + optimistic local twin)
+export const likePost = mutator({
+  // Convergent, not incremental: `local` replays on every rebase, so applying it N times has to
+  // equal applying it once — `likedByMe` is what makes the second application a no-op.
+  local(tx, { postId }) {
+    tx.posts.update(postId, (p) =>
+      p.likedByMe ? {} : { likedByMe: true, likeCount: p.likeCount + 1 });
+  },
+  async server(ctx, { postId }) { return ctx.posts.like(postId); },
+  conflict: 'server-wins', // | 'last-write-wins' | custom(merge)
+});
+```
+
+`persist: true` on the query moves that route from tier 2 to tier 3. Same mutator, same authz, same
+frames — `local` starts writing to a durable store and the mutation queue starts surviving reloads.
+**One protocol serves all three tiers**: a channel message, a live-query patch and an offline
+mutation drain are frames in the same discriminated union (`src/sync-protocol.ts`), so the client's
+frame handler is unchanged between rungs.
+
+`local` must be pure — no I/O, no `Date.now()`, no `Math.random()` — because rebase replays it.
+
+## Public API
+
+| Concern | Export |
+|---|---|
+| tier 1 | `topic`, `ChannelHub`, `PresenceRegistry`, `SyncSocket`, `SocketRegistry` |
+| tier 2 | `LiveQueryRegistry`, `InMemoryChangeFeed`, `PgLogicalReplicationFeed`, `selectChangeFeed`, `createReplicator`, `PgAdvisoryLock`, `matcherFor` |
+| replication | `parsePgUrl`, `bunPgStream`, `PgOutputDecoder`, `entityRow`, `changeLsn`, `commitPositionOf` |
+| fanout | `Transport`, `InProcessTransport`, `NatsTransport`, `selectTransport`, `subjectMatches` |
+| the bus client | `NatsConnection`, `NatsProtocolParser`, `NatsKvSet`, `ensureKvBucket`, `parseNatsUrl`, `bunNatsStream`, `FakeNatsServer` |
+| reconnect | `LiveCursor`, `resumeFrom`, `shouldResnapshot`, `defaultReconnectBudget`, `RingChangeBuffer`, `backoffDelay`, `drainPlan`, `AcceptBudget` |
+| tier 3 | `MemoryLocalStore`, `createOpfsLocalStore`, `OfflineQueue`, `RebaseLog`, `reconcile`, `custom` |
+| wire | `PROTOCOL_VERSION`, `encode`, `decode`, `Frame` |
+| halves | `LiveClient` (client), `createSyncNode` / `listenSyncNode` (`sync` role) |
+| hooks | `setLiveClient`, `useLive`, `useConnection`, `useMutation`, `useMutationQueue` |
+
+## The four hooks
+
+Register the client once, in the app entry. Every hook reads it from there — no hook takes a client
+argument, and one that runs before the registration is `X_LIVE_CLIENT_MISSING`, never a default.
+
+```ts
+setLiveClient(new LiveClient({ signal: createSignal, connect, buildId, store, queue }));
+
+const feed = useLive(liveFeed, () => ({ orgId: actor.orgId })); // feed(), feed.state(), feed.unsubscribe()
+const connection = useConnection();                             // .offline .online .reconnectAt .updateAvailable
+const like = useMutation(likePost);                             // await like(input); like.pending
+const queue = useMutationQueue();                               // .pending .failed .drain()
+```
+
+| Rule | Why |
+|---|---|
+| **No `solid-js` import.** Reactivity is the `SignalFactory` the client was built with | one reactive runtime per app, and a tier-3 package that installs and tests with none |
+| Every member is a **getter**, every result set an **accessor** | a value snapshotted at hook time never re-renders |
+| A thunk `input` is read **once**, at subscribe time | nothing here re-runs it; changing input is a new subscription |
+| The caller owns `unsubscribe` | this layer does not know what a mount is |
+| `pending` / `failed` are read off the queue, through an invalidation signal refreshed on each `mutate` and `drain` | the count is never a second copy of the queue, and `OfflineQueue` holds arrays, not signals |
+
+Tier 2 has no queue, so `pending` is `0` there — stated, not guessed.
+
+Authz goes through `@ultimat3/query`'s `guard`, which is the only contact with `@ultimat3/policy`.
+One authz system, never two: `policy` is evaluated **once per subscriber**, never once per query.
+Two actors on one live query get two different result sets, and a row that leaves an actor's policy
+is delivered to them as a `delete` — never as silence.
+
+## Reconnect is the hard part
+
+A deploy drops N sockets at once and every one asks "what changed since X?". If that answer needs
+arbitrary WAL replay or a re-run of every query, a rolling restart becomes a self-inflicted outage
+that outlasts the deploy. The design confronts it with exactly two paths and no third:
+
+| Path | When | Cost |
+|---|---|---|
+| **delta** | the cursor's gap is inside the retained window and inside the budget | one buffer read, zero DB work |
+| **snapshot** | out of window, past `maxLagMs`, or past `reconnectBudget` | one bounded indexed query |
+
+A `LiveCursor` is `lsn` + result-set `digest` + last-seen `ids` + `count`. The digest is
+order-sensitive, so a re-sort is detected; the ids let a delta be re-filtered per subscriber, because
+the retained window stores **pre-policy** patches. `resumeFrom()` picks the path,
+`shouldResnapshot()` explains it, and the budget is a cost model in patch-equivalents
+(`snapshotCost: 250` = "replaying 250 patches costs a snapshot") so the expensive path is *chosen*,
+never stumbled into.
+
+On drain, `drainPlan()` gives every client its own jittered slot in a spread window and the node
+sends a `reconnect` frame carrying that delay — clients redistribute instead of stampeding.
+`AcceptBudget` is the receiving node's token bucket, and a refusal always carries a retry delay,
+because refusing without one just moves the herd next door.
+
+### Limits, stated plainly
+
+- **The change window is per node.** A client that reconnects to a *different* `sync` node has no
+  window there and takes a snapshot. Making the window shared (replicator-side, request/reply) is
+  gated on the milestone-6 reconnect benchmark — 50k sockets, forced restart, measure
+  time-to-consistent — because that number decides the topology.
+- **A delta resume leaves the digest unverified** (`DIGEST_UNVERIFIED`). Only a snapshot re-establishes
+  it. `verifyDigest()` is how a client detects drift and asks for a fresh one.
+- **Backpressure drops patch frames.** That is safe *only* because a re-snapshot is cheap: the drop
+  is recorded on the socket (`desynced`) and the next flush re-snapshots rather than diverging.
+- **`PgLogicalReplicationFeed` decodes `pgoutput` off a real slot** — its own Postgres v3 client
+  (SCRAM-SHA-256, in-band TLS, CopyBoth), no driver dependency. It preflights `wal_level`, the
+  publication and the slot, creates the slot when there is none, and confirms the slot as it goes so
+  the WAL does not grow without bound. `InMemoryChangeFeed` + `InProcessTransport` remain the
+  defaults for `x dev` and every test.
+- **`selectChangeFeed(env, { entities })` decides which feed a boot installs** — same law
+  `selectMailDriver` follows: an unset variable means the embedded default. It returns `{ feed,
+  mode, detail, slot, lock }`: `mode` is `'embedded' | 'external'`, `detail` is the env key that
+  selected it and never a credential, and `lock` is the `AdvisoryLock` for that feed — built here
+  rather than by the caller, because constructing one needs the URL and the URL carries a password.
+  Neither `DATABASE_URL` nor `REPLICATION_URL` set → `InMemoryChangeFeed`,
+  `mode: 'embedded'`. `REPLICATION_URL` wins when both are set, but naming a different host, port or
+  database than `DATABASE_URL` is refused at boot with `X_CONFIG_INVALID` — a feed streaming the
+  wrong database's WAL would be silently wrong forever. `REPLICATION_SLOT` (default `x_replicator`)
+  and `REPLICATION_PUBLICATION` (default `x_changes`) name the slot and publication, both checked
+  against `[a-z_][a-z0-9_]*` before they reach a replication command.
+- **`PgAdvisoryLock` is the production `AdvisoryLock`** — `SELECT
+  pg_try_advisory_lock(hashtext('x:replicator:<slot>'))` on its own session. Session-scoped, so a
+  crashed replicator releases it automatically: no lease renewal, no fencing token, no split brain.
+  `InMemoryAdvisoryLock` remains the single-process default for `x dev` and tests.
+- **`selectTransport(env)` decides which transport a boot fans out on** — the same law again, and
+  the only place that reads `NATS_URL`. It returns `{ transport, mode, detail, bucket,
+  presenceTtlMs, connect }`: unset → `InProcessTransport` and `mode: 'embedded'`, set → a
+  `NatsTransport` on the KV bucket `NATS_KV_BUCKET` names (default `x_presence`, so two apps on one
+  cluster do not share one presence namespace), validated here rather than on first connect.
+  `presenceTtlMs` comes back with it because the bucket's whole-stream age limit was derived from
+  it — a `PresenceRegistry` given a different number would report members leaving that never left.
+  Selection is pure; `connect()` is the dial, so an unreachable bus fails at boot.
+- **`NatsTransport` speaks NATS itself** — its own protocol codec and session over `Bun.connect`,
+  no client dependency. Fanout is core NATS; `shared` is a JetStream KV bucket the transport
+  creates on first connect, one key per presence member, expired by the **server's** per-message
+  TTL so a node that dies needs nobody to notice. Subscriptions are held as *intent*, so a lost
+  connection re-dials and re-subscribes underneath the caller — which is what makes `sync`
+  stateless. That bucket needs nats-server ≥ 2.11 (batch direct get, per-message TTL); an older
+  one is `X_TRANSPORT_PROTOCOL` on the first dial, never a retry loop, because no amount of
+  reconnecting makes a server newer.
+- **The lsn is `<commit position><row position in the transaction>`, 24 hex characters.** Neither
+  half works alone: every row of one transaction shares a commit lsn, and logical decoding emits
+  *transactions* in commit order, so per-record WAL positions are not monotonic across them. The
+  pair sorts in delivery order and is byte-identical on replay, which is what turns at-least-once
+  redelivery into a drop instead of a duplicate.
+- **A live query needs `REPLICA IDENTITY FULL`.** Deciding whether a row *left* a result set needs
+  the old values; with the default identity a delete replicates only the key columns.
+- Tier 3's OPFS SQLite store is browser-only and throws until the browser entry ships; `MemoryLocalStore`
+  implements the full journal/rollback/replay semantics today.
+
+## Errors
+
+`X_TOPIC_FORBIDDEN` · `X_SUBSCRIPTION_LIMIT` · `X_PROTOCOL_VERSION` · `X_CURSOR_STALE` ·
+`X_REBASE_CONFLICT` · `X_TRANSPORT_UNAVAILABLE` · `X_TRANSPORT_PROTOCOL` ·
+`X_REPLICATION_FAILED` · `X_REPLICATION_PROTOCOL` · `X_REPLICATOR_SLOT_HELD` ·
+`X_LIVE_CLIENT_MISSING` · `X_NOT_IMPLEMENTED`
+
+Topics deny by default: a topic with no matching guard is forbidden. An authz hole is not a config
+option someone forgot to set.
+
+`As of 2026-07`: tiers 1–2 target v1, tier 3 targets v2.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@ultimat3/realtime",
+  "version": "1.0.0",
+  "description": "Three-tier realtime: channels, live queries, local-first sync — one protocol, one mutator shape",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/developerz-ai/ultimate.git",
+    "directory": "packages/realtime"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@ultimat3/core": "1.0.0",
+    "@ultimat3/query": "1.0.0"
+  }
+}

package/src/change-buffer.ts

@@ -0,0 +1,69 @@
+// The bounded per-query change window that makes reconnect a delta instead of a refetch.
+// Lives on the `replicator` (one per DB), so a reconnecting client costs zero DB work while its
+// gap is inside the window. Outside it, `resumeFrom` takes one snapshot — never WAL traversal.
+
+import type { ResumeSource } from './cursor';
+import type { RowPatch } from './json';
+
+export interface ChangeBufferOptions {
+  /** Retained patches per query hash. */
+  readonly capacity?: number;
+  /** Retained query hashes; the least-recently-written is dropped first. */
+  readonly maxQueries?: number;
+}
+
+interface Ring {
+  patches: RowPatch[];
+  /** Highest lsn already dropped. A cursor at or after this is still resumable. */
+  evictedThrough: string | null;
+}
+
+export class RingChangeBuffer implements ResumeSource {
+  readonly #rings = new Map<string, Ring>();
+  readonly #capacity: number;
+  readonly #maxQueries: number;
+
+  constructor(options: ChangeBufferOptions = {}) {
+    this.#capacity = options.capacity ?? 1024;
+    this.#maxQueries = options.maxQueries ?? 4096;
+  }
+
+  append(qid: string, patch: RowPatch): void {
+    const existing = this.#rings.get(qid);
+    const ring: Ring = existing ?? { patches: [], evictedThrough: null };
+    ring.patches.push(patch);
+    while (ring.patches.length > this.#capacity) {
+      const dropped = ring.patches.shift();
+      if (dropped) ring.evictedThrough = dropped.lsn;
+    }
+    // Re-insert to move this qid to the tail of the LRU order.
+    if (existing) this.#rings.delete(qid);
+    this.#rings.set(qid, ring);
+    if (this.#rings.size > this.#maxQueries) {
+      const oldest = this.#rings.keys().next();
+      if (!oldest.done) this.#rings.delete(oldest.value);
+    }
+  }
+
+  since(qid: string, lsn: string): RowPatch[] | null {
+    const ring = this.#rings.get(qid);
+    if (!ring) return null;
+    if (ring.evictedThrough !== null && lsn < ring.evictedThrough) return null;
+    return ring.patches.filter((patch) => patch.lsn > lsn);
+  }
+
+  headLsn(qid: string): string | null {
+    const ring = this.#rings.get(qid);
+    const last = ring?.patches.at(-1);
+    return last ? last.lsn : null;
+  }
+
+  /** Called when the last subscriber of a query goes away, so an idle query stops costing memory. */
+  forget(qid: string): void {
+    this.#rings.delete(qid);
+  }
+
+  get queryCount(): number {
+    return this.#rings.size;
+  }
+}

package/src/changefeed-env.ts

@@ -0,0 +1,146 @@
+// Single responsibility: environment → change feed. The one place that decides which `ChangeFeed`
+// a boot installs, so `x dev`, a replicator container and any custom host resolve it identically.
+// `PgLogicalReplicationFeed` is useless until something constructs it from a connection string;
+// this is that something, keyed on env rather than a config field so one image deploys everywhere.
+
+import type { Clock } from '@ultimat3/core';
+import { ConfigInvalidError } from '@ultimat3/core';
+import type { ChangeFeed } from './changefeed';
+import { InMemoryChangeFeed, PgLogicalReplicationFeed } from './changefeed';
+import { PgAdvisoryLock } from './pg-advisory-lock';
+import type { PgTarget } from './pg-socket';
+import { parsePgUrl } from './pg-socket';
+import type { PgStream } from './pg-wire';
+import type { AdvisoryLock } from './replicator';
+import { InMemoryAdvisoryLock } from './replicator';
+import type { Rng } from './thundering-herd';
+
+/** The keys read here, and nothing else. Named once so docs and tests cannot drift from the code. */
+export const REPLICATION_ENV_KEYS = [
+  'DATABASE_URL',
+  'REPLICATION_URL',
+  'REPLICATION_SLOT',
+  'REPLICATION_PUBLICATION',
+] as const;
+
+/** The slot one replicator holds, and the publication it decodes, when env names neither. */
+export const DEFAULT_REPLICATION_SLOT = 'x_replicator';
+export const DEFAULT_REPLICATION_PUBLICATION = 'x_changes';
+
+/** The advisory-lock key for a slot. One database, one replicator, one key — derived, never typed. */
+export const replicatorLockKey = (slot: string): string => `x:replicator:${slot}`;
+
+export type ReplicationEnvironment = Readonly<Record<string, string | undefined>>;
+
+export interface ChangeFeedSelection {
+  readonly feed: ChangeFeed;
+  /** `embedded` is the in-process feed; `external` decodes a real WAL. */
+  readonly mode: 'embedded' | 'external';
+  /**
+   * Why this feed, in one line: the env key that selected it, or what to set to change it. A boot
+   * prints it, so "which WAL is this process reading" is never a guess — and it is the env key
+   * rather than the URL, because a replication URL carries a password.
+   */
+  readonly detail: string;
+  /** Null in embedded mode: there is no slot to lock, and nothing to be the second replicator of. */
+  readonly slot: string | null;
+  /**
+   * The lock that keeps "one replicator per database" true for this feed. Returned here rather
+   * than built by the caller so the connection string stays inside this module — a caller that
+   * had to construct the lock itself would need the URL, and the URL carries a password.
+   */
+  readonly lock: AdvisoryLock;
+}
+
+export interface SelectChangeFeedOptions {
+  /** Entities to decode. Anything else is skipped before it reaches the matcher. */
+  readonly entities: readonly string[];
+  /** Retained events in the embedded feed, so a `start({ from })` replays instead of skipping. */
+  readonly retain?: number | undefined;
+  readonly clock?: Clock | undefined;
+  readonly rng?: Rng | undefined;
+  readonly stream?: ((target: PgTarget) => Promise<PgStream>) | undefined;
+}
+
+const nonEmpty = (value: string | undefined): string | undefined =>
+  value === undefined || value.trim().length === 0 ? undefined : value.trim();
+
+/**
+ * A feed pointed at a *different* database than the app writes to decodes a WAL in which the app's
+ * own transactions never appear: every live query stays on its first snapshot forever and nothing
+ * downstream can tell. There is no runtime symptom to debug, so the two URLs are compared at the
+ * boundary — the only place both are still in hand.
+ */
+function assertSameDatabase(replicationUrl: string, databaseUrl: string): void {
+  const replication = parsePgUrl(replicationUrl);
+  const application = parsePgUrl(databaseUrl);
+  const differs =
+    replication.host !== application.host ||
+    replication.port !== application.port ||
+    replication.database !== application.database;
+  if (!differs) return;
+  throw new ConfigInvalidError({
+    cause:
+      `REPLICATION_URL names ${replication.host}:${replication.port}/${replication.database} but ` +
+      `DATABASE_URL names ${application.host}:${application.port}/${application.database} — the ` +
+      'feed would decode a WAL the app never writes to',
+    fix: 'point REPLICATION_URL at the same host, port and database as DATABASE_URL, changing only the role',
+    meta: { REPLICATION_URL: replication.database, DATABASE_URL: application.database },
+  });
+}
+
+/**
+ * No connection string means the in-process feed — the same "an unset variable means the embedded
+ * default" law the db, events and storage bindings follow. `REPLICATION_URL` exists because the
+ * app's own role usually lacks `REPLICATION`; it overrides which credentials are used, never which
+ * database is read, which is what `assertSameDatabase` holds to.
+ */
+export function selectChangeFeed(
+  env: ReplicationEnvironment,
+  options: SelectChangeFeedOptions,
+): ChangeFeedSelection {
+  const databaseUrl = nonEmpty(env['DATABASE_URL']);
+  const replicationUrl = nonEmpty(env['REPLICATION_URL']);
+  const url = replicationUrl ?? databaseUrl;
+
+  if (url === undefined) {
+    return {
+      feed: new InMemoryChangeFeed(options.retain === undefined ? {} : { retain: options.retain }),
+      mode: 'embedded',
+      detail: 'in-process change feed — set DATABASE_URL to decode a real WAL',
+      slot: null,
+      // Single-process mutual exclusion, which is all one process needs and all it can enforce.
+      lock: new InMemoryAdvisoryLock(replicatorLockKey(DEFAULT_REPLICATION_SLOT)),
+    };
+  }
+
+  if (replicationUrl !== undefined && databaseUrl !== undefined) {
+    assertSameDatabase(replicationUrl, databaseUrl);
+  }
+
+  const slot = nonEmpty(env['REPLICATION_SLOT']) ?? DEFAULT_REPLICATION_SLOT;
+  return {
+    // Slot and publication are validated inside the feed, against the same identifier rule the
+    // replication command needs — a second copy of that regex here is a second thing to keep true.
+    feed: new PgLogicalReplicationFeed({
+      url,
+      slot,
+      publication: nonEmpty(env['REPLICATION_PUBLICATION']) ?? DEFAULT_REPLICATION_PUBLICATION,
+      entities: options.entities,
+      clock: options.clock,
+      rng: options.rng,
+      stream: options.stream,
+    }),
+    mode: 'external',
+    detail: replicationUrl === undefined ? 'DATABASE_URL' : 'REPLICATION_URL',
+    slot,
+    // Taken on the same database the feed reads, so the lock and the slot cannot end up in
+    // different places — which is the only way "exactly one replicator" could quietly become two.
+    lock: new PgAdvisoryLock({
+      url,
+      key: replicatorLockKey(slot),
+      stream: options.stream,
+      rng: options.rng,
+    }),
+  };
+}

package/src/changefeed.ts

@@ -0,0 +1,191 @@
+// The ordered stream of committed row changes. Production source is Postgres logical replication;
+// `x dev` and every test use the in-memory feed. Both satisfy one interface, so the matcher, the
+// replicator, and the fanout never learn which one they are attached to.
+
+import type { Clock } from '@ultimat3/core';
+import { ReplicationFailedError } from './errors';
+import type { Row } from './json';
+import { PgReplicationStream, type ReplicationStreamStats } from './pg-replication';
+import type { PgTarget } from './pg-socket';
+import type { PgStream } from './pg-wire';
+import type { Rng } from './thundering-herd';
+
+export type ChangeOp = 'insert' | 'update' | 'delete';
+
+export interface ChangeEvent<R extends Row = Row> {
+  /** Entity name, not table name — the matcher's dependency sets are declared in entity terms. */
+  readonly entity: string;
+  readonly op: ChangeOp;
+  readonly before: R | null;
+  readonly after: R | null;
+  /** Lexicographically comparable position. Use `formatLsn` / `parseLsn`, never a raw pg string. */
+  readonly lsn: string;
+  readonly txid: string;
+  /** Tenant column, hoisted out of the row so fanout can filter without parsing it. */
+  readonly orgId: string | null;
+  /** Commit time, epoch ms. */
+  readonly at: number;
+}
+
+export interface ChangeFeedStartOptions {
+  /** Resume position. Omitted means "from now". */
+  readonly from?: string;
+  readonly onChange: (event: ChangeEvent) => void | Promise<void>;
+}
+
+export interface ChangeFeed {
+  readonly source: string;
+  start(options: ChangeFeedStartOptions): Promise<void>;
+  stop(): Promise<void>;
+  /** Highest lsn delivered to the handler; the replicator persists this to survive a restart. */
+  lastLsn(): string | null;
+}
+
+/** 16-hex zero-padded so string comparison equals numeric comparison. */
+export function formatLsn(position: bigint | number): string {
+  return BigInt(position).toString(16).padStart(16, '0');
+}
+
+/** Postgres prints LSNs as `0/16B3748`. Both halves are hex; join them into one sortable value. */
+export function parseLsn(pgLsn: string): string {
+  const [high = '0', low = '0'] = pgLsn.split('/');
+  return formatLsn((BigInt(`0x${high}`) << 32n) | BigInt(`0x${low}`));
+}
+
+export interface InMemoryChangeFeedOptions {
+  /** Retained events, so a `start({ from })` inside the window replays instead of skipping. */
+  readonly retain?: number;
+}
+
+/**
+ * The blessed development and test feed. Deliveries are serialized through one promise chain:
+ * ordering is the guarantee the whole pipeline is built on, so it is enforced here rather than
+ * assumed downstream.
+ */
+export class InMemoryChangeFeed implements ChangeFeed {
+  readonly source = 'in-memory';
+  readonly #retained: ChangeEvent[] = [];
+  readonly #retain: number;
+  #handler: ChangeFeedStartOptions['onChange'] | null = null;
+  #tail: Promise<void> = Promise.resolve();
+  #position = 0n;
+  #lastLsn: string | null = null;
+
+  constructor(options: InMemoryChangeFeedOptions = {}) {
+    this.#retain = options.retain ?? 1024;
+  }
+
+  async start(options: ChangeFeedStartOptions): Promise<void> {
+    this.#handler = options.onChange;
+    const from = options.from;
+    if (from === undefined) return;
+    for (const event of this.#retained) {
+      if (event.lsn > from) await this.#deliver(event);
+    }
+  }
+
+  async stop(): Promise<void> {
+    this.#handler = null;
+    await this.#tail;
+  }
+
+  lastLsn(): string | null {
+    return this.#lastLsn;
+  }
+
+  /** Append a fully-formed event. Used by tests that need an exact lsn or txid. */
+  async emit(event: ChangeEvent): Promise<void> {
+    if (this.#retain > 0) {
+      this.#retained.push(event);
+      while (this.#retained.length > this.#retain) this.#retained.shift();
+    }
+    await this.#deliver(event);
+  }
+
+  /** Ergonomic emit: assigns the next lsn and txid so tests read as domain events. */
+  async push(
+    entity: string,
+    op: ChangeOp,
+    rows: { before?: Row | null; after?: Row | null; orgId?: string | null; at?: number },
+  ): Promise<ChangeEvent> {
+    this.#position += 1n;
+    const event: ChangeEvent = {
+      entity,
+      op,
+      before: rows.before ?? null,
+      after: rows.after ?? null,
+      lsn: formatLsn(this.#position),
+      txid: this.#position.toString(10),
+      orgId: rows.orgId ?? null,
+      at: rows.at ?? 0,
+    };
+    await this.emit(event);
+    return event;
+  }
+
+  async #deliver(event: ChangeEvent): Promise<void> {
+    const handler = this.#handler;
+    if (!handler) return;
+    this.#tail = this.#tail.then(async () => {
+      await handler(event);
+      this.#lastLsn = event.lsn;
+    });
+    await this.#tail;
+  }
+}
+
+export interface PgLogicalReplicationOptions {
+  /** Connection string for a role with REPLICATION: `postgres://user:pass@host:5432/db`. */
+  readonly url: string;
+  /** Replication slot name. Exactly one `replicator` process may hold it. */
+  readonly slot: string;
+  readonly publication: string;
+  /** Entities to decode; anything else is skipped before it reaches the matcher. */
+  readonly entities: readonly string[];
+  /** How often the slot is confirmed. Longer means more WAL retained after a crash. */
+  readonly statusIntervalMs?: number | undefined;
+  readonly clock?: Clock | undefined;
+  /** Injected so the SCRAM nonce is deterministic under a seeded test. */
+  readonly rng?: Rng | undefined;
+  /** The byte pipe, injected. Defaults to `Bun.connect`; a test drives a scripted server instead. */
+  readonly stream?: ((target: PgTarget) => Promise<PgStream>) | undefined;
+}
+
+/**
+ * The production feed: `pgoutput` decoding off a logical replication slot. Everything about *how*
+ * lives in `pg-replication.ts`; what this class adds is the `ChangeFeed` contract the matcher, the
+ * replicator and the fanout are written against — so swapping it for `InMemoryChangeFeed` in `x dev`
+ * changes nothing downstream.
+ */
+export class PgLogicalReplicationFeed implements ChangeFeed {
+  readonly source = 'pg-logical-replication';
+  readonly #stream: PgReplicationStream;
+
+  constructor(options: PgLogicalReplicationOptions) {
+    if (options.entities.length === 0) {
+      throw new ReplicationFailedError({
+        stage: 'preflight',
+        detail: 'the feed was given an empty entity list, so no change could ever match',
+        fix: 'pass the entities the publication covers: new PgLogicalReplicationFeed({ entities: [...] })',
+      });
+    }
+    this.#stream = new PgReplicationStream(options);
+  }
+
+  async start(options: ChangeFeedStartOptions): Promise<void> {
+    await this.#stream.start({ from: options.from, onChange: options.onChange });
+  }
+
+  async stop(): Promise<void> {
+    await this.#stream.stop();
+  }
+
+  lastLsn(): string | null {
+    return this.#stream.lastLsn();
+  }
+
+  /** Delivered / skipped / replayed counts, for `/readyz` and the `x dev` dashboard. */
+  stats(): ReplicationStreamStats {
+    return this.#stream.stats();
+  }
+}