@ultimat3/testing 4.0.0 → 5.0.0

package/CLAUDE.md

@@ -26,7 +26,11 @@ is its own entry point and not part of the barrel.
 | Injection | `SqlRunner` and `connect` are parameters, so unit tests need no server |
 | Fixtures | the preload registers the whole framework bag — an app registers only what the framework cannot know (`seed`, `actorFor`) |
 | e2e without a driver | `e2eTest` becomes `test.skip`, and the gate reports the step GREEN over it — `bun test` exits 0 on a skip and the exit code is the only channel between the step and the child that registers the driver. `hasE2eDriver()` is what a harness asks instead of reading an all-skipped run as a pass. Zero drivers are registered `As of 2026-08` |
-| Built vs declared | `clock` `mail` `network` `runJobs` `statements` are built in-process; `page` `budget` `signIn` `deploy` `subscribe` are declared and wait for a driver (`X_TEST_FIXTURE_UNAVAILABLE`) |
+| Built vs declared | `clock` `mail` `network` `runJobs` `statements` `subscribe` are built in-process; `page` `budget` `signIn` `deploy` are declared and wait for a driver (`X_TEST_FIXTURE_UNAVAILABLE`). The four left all need a browser or a second build — things the framework genuinely cannot bundle |
+| `subscribe` is a whole `sync` node | `live-node.ts` assembles what `x dev --role sync` assembles minus the listener — real `LiveQueryRegistry`, real `liveQueryDefinition` bridge, real per-subscriber gate, real cursor — over a socket that is two objects handing each other the JSON a WebSocket would. `live-replicator.ts` feeds it from `@ultimat3/entity`'s `setRowObserver`, which is the change SOURCE a test process never had: PGlite has no walsender and the memory driver no log, so `InMemoryChangeFeed` had nothing upstream of it. The WAL decoder is the only thing substituted; everything downstream of it is production code |
+| What `subscribe` does NOT hold | a client store, an offline queue or a rebase log — so `feed.local()` answers `undefined` rather than the server row. A twin reported as applied whether or not a mutator ran is coverage that reads as proof, which is worse than none. That half is `useMutation` / `useMutationQueue` and an e2e |
+| Draining is a macrotask yield | the node dispatches `message` into a floating async task, so `settled()` yields with `setImmediate` until the frame count stops moving. Counting microtask turns is a number that is right until someone adds an `await` — the first version drained 32 and read `examples/dummy`'s deeper feed read as "the node answered nothing" |
+| A lone subscriber cannot resume | the retained window is the registry's ENTRY and the entry is dropped when its last subscriber goes, so a reconnect with nobody else holding it re-snapshots — correctly. `fixture-subscribe.test.ts` asserts both halves |
 | Strict is opt-in by destructuring | `statements` installs the N+1 detector in throw mode for one test. A fixture nobody names is a fixture nobody built, so there is no `strict: true` and no suite-wide switch — and no way to leave it on for the next file |
 | One threshold, one error | `N_PLUS_ONE_THRESHOLD` and `nPlusOne()` are `@ultimat3/entity`'s. A number or a message written here would make a loop that fails a test a different loop from the one `x dev` warns about |
 | The unit of work is the test | `x dev`'s ledger tallies per `Ctx` and ignores a statement issued outside a request; this counts every statement from build to disposal, because `posts.findById(id)` in a unit test has no request and is exactly the loop worth catching |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/testing",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "description": "Test harness: cloned template DBs per worker, frozen clock, sealed network, 6 test types",
   "license": "MIT",
   "type": "module",
@@ -33,14 +33,16 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "4.0.0",
-    "@ultimat3/core": "4.0.0",
-    "@ultimat3/db": "4.0.0",
-    "@ultimat3/entity": "4.0.0",
-    "@ultimat3/i18n": "4.0.0",
-    "@ultimat3/jobs": "4.0.0",
-    "@ultimat3/mail": "4.0.0",
-    "@ultimat3/policy": "4.0.0",
-    "@ultimat3/time": "4.0.0"
+    "@ultimat3/cache": "5.0.0",
+    "@ultimat3/core": "5.0.0",
+    "@ultimat3/db": "5.0.0",
+    "@ultimat3/entity": "5.0.0",
+    "@ultimat3/i18n": "5.0.0",
+    "@ultimat3/jobs": "5.0.0",
+    "@ultimat3/mail": "5.0.0",
+    "@ultimat3/policy": "5.0.0",
+    "@ultimat3/query": "5.0.0",
+    "@ultimat3/realtime": "5.0.0",
+    "@ultimat3/time": "5.0.0"
   }
 }

package/src/errors.ts

@@ -25,6 +25,8 @@ export const TESTING_ERROR_CODES = [
   'X_TEST_FACTORY_TRAIT_UNKNOWN',
   'X_TEST_FACTORY_NOT_PERSISTED',
   'X_TEST_REGISTRY_LEAK',
+  'X_TEST_LIVE_NODE_EMPTY',
+  'X_TEST_LIVE_NODE_UPGRADE_REFUSED',
 ] as const;
 
 export type TestingErrorCode = (typeof TESTING_ERROR_CODES)[number];
@@ -43,6 +45,8 @@ export const TESTING_ERROR_TITLES: Readonly<Record<TestingErrorCode, string>> =
   X_TEST_FACTORY_TRAIT_UNKNOWN: 'a factory was asked for a trait it does not declare',
   X_TEST_FACTORY_NOT_PERSISTED: 'a factory create() had nowhere to write the row',
   X_TEST_REGISTRY_LEAK: 'a test file left a process-global registry dirty',
+  X_TEST_LIVE_NODE_EMPTY: 'the in-process sync node has no live query to serve',
+  X_TEST_LIVE_NODE_UPGRADE_REFUSED: 'the in-process sync node refused the connection',
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is
@@ -145,6 +149,50 @@ export class FixtureUnavailableError extends UltimateError {
 export const fixtureUnavailable = (name: string, needs: string): UltimateError =>
   new FixtureUnavailableError({ name, needs });
 
+/**
+ * The `subscribe` fixture built a node and found nothing to register. A registry with no definition
+ * answers every subscribe with "no live query registered" — a working socket serving no reads,
+ * which looks the same as a harness that is broken and an app that declared nothing. Said at the
+ * one moment the count is known, rather than three awaits later at the first subscribe.
+ *
+ * Almost always the same cause: the app's api module was never imported, so `registerQueries()`
+ * never ran and `listQueries()` is empty. The preload is where an app imports it — see
+ * `examples/dummy/scripts/test-setup.ts`.
+ */
+export class LiveNodeEmptyError extends UltimateError {
+  constructor() {
+    super({
+      code: 'X_TEST_LIVE_NODE_EMPTY',
+      cause:
+        'no query declared live: true is registered in this process, so the node would serve none',
+      fix: "import the app's api module in the test preload — import './apps/web/api' — then: x queries list --json",
+      docs: docsFor('X_TEST_LIVE_NODE_EMPTY'),
+    });
+  }
+}
+
+export const liveNodeUnavailable = (): UltimateError => new LiveNodeEmptyError();
+
+/**
+ * The node answered the upgrade with a response instead of taking it. A REAL refusal — the accept
+ * budget, the connection ceiling, or a node that is not ready — and a different failure from
+ * "nothing to serve", which is what this path reported until 2026-08-20 and sent a reader looking
+ * for a missing query rather than at a node that never started.
+ */
+export class LiveNodeUpgradeRefusedError extends UltimateError {
+  constructor(status: number | undefined) {
+    super({
+      code: 'X_TEST_LIVE_NODE_UPGRADE_REFUSED',
+      cause: `the sync node answered the upgrade with ${status === undefined ? 'no response' : `HTTP ${String(status)}`} instead of taking it`,
+      fix: 'await node.start() before connect(), and keep the request path at /_x/sync',
+      docs: docsFor('X_TEST_LIVE_NODE_UPGRADE_REFUSED'),
+    });
+  }
+}
+
+export const upgradeRefused = (status: number | undefined): UltimateError =>
+  new LiveNodeUpgradeRefusedError(status);
+
 /**
  * A request made while `network.offline()` (or `network.drop()`) is in force. Coded rather than a
  * bare `TypeError` because a test that lands here uncaught needs to know which of the two it was:

package/src/fixture-drivers.ts

@@ -1,7 +1,8 @@
 // The fixtures the framework DECLARES but cannot build in this process: a browser for `page`,
-// `budget`, `signIn` and `deploy`; a replicator feeding a live-query registry for `subscribe`.
+// `budget`, `signIn` and `deploy` — all four wait for a browser or a second build.
 // Each is a type a driver implements, plus a factory that says what is missing until one does.
 
+import type { Actor } from '@ultimat3/core';
 import { fixtureUnavailable } from './errors';
 import type { FixtureFactory, Fixtures } from './fixtures';
 
@@ -19,20 +20,20 @@ export interface TestDeploy {
 }
 
 /**
- * What `query.live(input, { actor })` resolves to, named structurally so `@ultimat3/testing` does
- * not take a dependency on `@ultimat3/query` for one type. The real `LiveQuery` satisfies it.
+ * The declared query itself — `liveFeed`, not a call to it. Named structurally so this package takes
+ * no static dependency on `@ultimat3/query` for one type; every `query()` satisfies it, because
+ * `registerQueries()` stamps the name a subscription is keyed by.
  *
- * NOT what `query.as(actor, input)` resolves to, which is a ROW ARRAY — and the difference is
- * invisible until a driver exists. `examples/dummy`'s five `subscribe` tests all call
- * `subscribe(liveFeed.as(actor, input))`, which is `TS2345` against `Subscribe` below and has
- * never been read, because that app's `typecheck` is pinned red in `scripts/lib/gated-apps.ts`.
- * A driver built to satisfy those call sites would have to accept a row array — and a `subscribe`
- * loose enough to do that proves nothing, which is strictly worse than the fixture being
- * unavailable, because it then reads as coverage.
+ * It was `{ name, queryHash }` — "what `query.live(input, { actor })` resolves to" — and that shape
+ * cannot be subscribed to: the node keys a subscription by `(name, input)`, and a hash is the input
+ * already thrown away. The five `subscribe` tests in `examples/dummy` wrote
+ * `subscribe(liveFeed.as(actor, input))`, which resolves to a ROW ARRAY and was `TS2345` against
+ * either shape — never read, because that app's `typecheck` is pinned red in
+ * `scripts/lib/gated-apps.ts`. The call is now `subscribe(liveFeed, input, actor)`: the query, its
+ * input, and who is asking — the three things a subscribe frame carries.
  */
 export interface LiveTarget {
   readonly name: string;
-  readonly queryHash: string;
 }
 
 export interface LiveFeedPatch<R extends object> {
@@ -50,17 +51,32 @@ export interface LiveFeed<R extends object> {
   /** Resolves when every patch in flight has been applied — never a sleep. */
   settled(): Promise<void>;
   lsn(): string;
+  /**
+   * Drop the connection and subscribe again with the cursor this feed holds — what a client does
+   * by itself on a reconnect, spelled out so a test can put a write between the two halves. It
+   * resolves once the node has answered, with either a delta or a fresh snapshot; which one is
+   * `snapshots()` and `resubscribedFrom()` below.
+   */
+  reconnect(): Promise<void>;
   /** Set when a reconnect resumed from a cursor; undefined when it resnapshotted. */
   resubscribedFrom(): string | undefined;
   /** How many snapshots this subscriber received. A resume that refetched shows up here. */
   snapshots(): number;
 }
 
+/**
+ * `actor` is the third argument rather than something baked into the target, because that is where
+ * the framework itself puts it: `liveQueryDefinition` builds the shared window with NO subject
+ * (`ToLiveOptions.enforce: false`) and decides per subscriber at subscribe time. A `subscribe` that
+ * took the actor inside the target would be describing a design the node does not have.
+ */
 export type Subscribe = <R extends object>(
-  target: LiveTarget | Promise<LiveTarget>,
+  target: LiveTarget,
+  input: Readonly<Record<string, unknown>>,
+  actor?: Actor | null,
 ) => Promise<LiveFeed<R>>;
 
-export const DRIVER_FIXTURE_NAMES = ['budget', 'deploy', 'page', 'signIn', 'subscribe'] as const;
+export const DRIVER_FIXTURE_NAMES = ['budget', 'deploy', 'page', 'signIn'] as const;
 
 export type DriverFixtureName = (typeof DRIVER_FIXTURE_NAMES)[number];
 
@@ -70,9 +86,6 @@ export const DRIVER_FIXTURE_NEEDS: Readonly<Record<DriverFixtureName, string>> =
   deploy: 'a second build to switch the running app to',
   page: 'a browser driving the built app',
   signIn: 'a browser session against the app’s own sign-in route',
-  subscribe:
-    'an in-process replicator feeding the live-query registry, and a caller that hands it ' +
-    'query.live(input, { actor }) — query.as() resolves to ROWS, which is not a LiveTarget',
 };
 
 /**
@@ -103,5 +116,4 @@ export const driverFixtures = (): DriverFixtures => ({
   deploy: unavailableFixture('deploy'),
   page: unavailableFixture('page'),
   signIn: unavailableFixture('signIn'),
-  subscribe: unavailableFixture('subscribe'),
 });

package/src/fixture-subscribe.ts

@@ -0,0 +1,214 @@
+// The `subscribe` fixture's driver: one in-process `sync` node, one replicator, and a `LiveFeed`
+// per subscriber built from the frames that subscriber actually received.
+//
+// Rows are never read out of the registry. They are accumulated from the `snapshot` and `patch`
+// frames the node wrote to this socket, through `@ultimat3/realtime`'s own `applyPatches` — so what
+// a test asserts is what a browser would hold, and a row the per-subscriber gate dropped is absent
+// here for the same reason it would be absent there. A feed that reached into the window would
+// prove the query works and say nothing about delivery, which is the half these tests are about.
+
+import type { Actor } from '@ultimat3/core';
+import { UltimateError } from '@ultimat3/core';
+import type { LiveFeed, LiveFeedPatch, LiveTarget } from './fixture-drivers';
+import type { LiveConnection, LiveNodeHandle } from './live-node';
+import { createLiveNode } from './live-node';
+import type { LiveReplicator } from './live-replicator';
+import { startLiveReplicator } from './live-replicator';
+
+interface Row {
+  readonly id: string;
+  readonly [column: string]: unknown;
+}
+
+interface SnapshotFrameLike {
+  readonly type: 'snapshot';
+  readonly sid: string;
+  readonly rows: readonly Row[];
+  /** `@ultimat3/realtime`'s `LiveCursor`, carried back verbatim on a resume. */
+  readonly cursor: { readonly qid: string; readonly lsn: string };
+}
+
+interface PatchFrameLike {
+  readonly type: 'patch';
+  readonly sid: string;
+  readonly patches: readonly {
+    readonly op: 'insert' | 'update' | 'delete';
+    readonly id: string;
+    readonly row: Record<string, unknown> | null;
+    readonly lsn: string;
+  }[];
+  readonly lsn: string;
+}
+
+export interface SubscribeDriver {
+  /** What `defineFixtures({ subscribe })` registers. */
+  subscribe<R extends object>(
+    target: LiveTarget,
+    input: Readonly<Record<string, unknown>>,
+    actor?: Actor | null,
+  ): Promise<LiveFeed<R>>;
+  readonly node: LiveNodeHandle;
+  readonly replicator: LiveReplicator;
+  stop(): Promise<void>;
+}
+
+/**
+ * One node and one replicator per FIXTURE, which is one per test: a node shared across tests would
+ * carry the previous test's subscriptions, and the row observer is process-global so two live at
+ * once would each see the other's writes. `bun test` builds a fixture on first use and disposes it
+ * with the test, which is exactly the lifetime this needs.
+ */
+export async function createSubscribeDriver(): Promise<SubscribeDriver> {
+  const realtime = await import('@ultimat3/realtime');
+  const node = await createLiveNode();
+  const replicator = await startLiveReplicator({ registry: node.registry });
+  const connections: LiveConnection[] = [];
+  let sid = 0;
+
+  const subscribe = async <R extends object>(
+    target: LiveTarget,
+    input: Readonly<Record<string, unknown>>,
+    actor: Actor | null = null,
+  ): Promise<LiveFeed<R>> => {
+    const connection = await node.connect(actor);
+    connections.push(connection);
+    sid += 1;
+    const id = `s${String(sid)}`;
+
+    connection.send({
+      type: 'hello',
+      v: realtime.PROTOCOL_VERSION,
+      buildId: 'test-build',
+      sessionId: null,
+      actorId: actor?.id ?? null,
+    });
+    await connection.settled();
+
+    connection.send({
+      type: 'subscribe',
+      v: realtime.PROTOCOL_VERSION,
+      op: 'add',
+      sid: id,
+      // `SubscribeTarget`'s query form. `qid` carries the query NAME on the way in — the node
+      // derives the real qid from `(name, input)`, so a client can never pick its own fanout key —
+      // and `cursor: null` is what makes this a fresh subscribe rather than a resume.
+      target: { kind: 'query', qid: target.name, input, cursor: null },
+    });
+    await connection.settled();
+
+    const mine = (): readonly Record<string, unknown>[] =>
+      connection.frames().filter((frame) => frame['sid'] === id);
+
+    // A refusal arrives as an `ack` carrying an error, never as a thrown call — the socket stayed
+    // up and the node answered. A test asserting `X_FORBIDDEN` wants the error, so it is rethrown
+    // here rather than left for `feed.rows()` to report as an empty result.
+    const refusal = connection
+      .frames()
+      .find((frame) => frame['type'] === 'ack' && frame['ref'] === id && frame['error'] != null);
+    if (refusal !== undefined) {
+      const wire = refusal['error'] as { code: string; cause: string; fix: string };
+      throw new UltimateError({ code: wire.code, cause: wire.cause, fix: wire.fix });
+    }
+
+    /**
+     * Where each reconnect started, and the lsn it asked to resume from. A resume is decided by
+     * what the node answered AFTER that point — a `patch` means it replayed from the cursor, a
+     * `snapshot` means `resumeFrom` refused it and re-read. Reading the frames is the only honest
+     * way to tell: the decision is the node's, and a harness that recorded its own intention would
+     * report a resume it never got.
+     */
+    const marks: { readonly at: number; readonly askedLsn: string }[] = [];
+
+    const state = () => {
+      let rows: readonly Row[] = [];
+      let snapshots = 0;
+      let lsn = '';
+      let cursor: unknown = null;
+      const patches: LiveFeedPatch<R>[] = [];
+      const frames = mine();
+      for (const frame of frames) {
+        if (frame['type'] === 'snapshot') {
+          const snapshot = frame as unknown as SnapshotFrameLike;
+          rows = snapshot.rows;
+          cursor = snapshot.cursor;
+          lsn = snapshot.cursor.lsn;
+          snapshots += 1;
+          continue;
+        }
+        if (frame['type'] !== 'patch') continue;
+        const patch = frame as unknown as PatchFrameLike;
+        rows = realtime.applyPatches(rows as never, patch.patches as never) as unknown as Row[];
+        for (const one of patch.patches) {
+          patches.push({ op: one.op, row: { id: one.id, ...(one.row ?? {}) } as unknown as R });
+        }
+        lsn = patch.lsn;
+      }
+      const last = marks[marks.length - 1];
+      const resumedFrom =
+        last === undefined || frames.slice(last.at).some((frame) => frame['type'] === 'snapshot')
+          ? undefined
+          : last.askedLsn;
+      return { rows, snapshots, lsn, cursor, resumedFrom, patches, frames };
+    };
+
+    return {
+      rows: () => state().rows as unknown as readonly R[],
+      row: (rowId: string) => state().rows.find((one) => one.id === rowId) as R | undefined,
+      // No optimistic twin on this feed: `local()` is the client store's answer, and this driver
+      // holds no store. A feed that returned the server row here would report the twin as applied
+      // whether or not a mutator ever ran, which is the "reads as coverage" failure the fixture was
+      // left unavailable to avoid. `useMutation` + `useMutationQueue` are the surface for that half.
+      local: () => undefined,
+      patches: () => state().patches,
+      settled: async () => {
+        await replicator.settled();
+        await connection.settled();
+      },
+      lsn: () => state().lsn,
+
+      reconnect: async () => {
+        const held = state();
+        if (held.cursor === null) return;
+        // The cursor the client holds: the snapshot's, advanced to the last patch it applied. That
+        // is what a real client carries, and what `resumeFrom` compares against the retained window.
+        const askedLsn = held.lsn;
+        marks.push({ at: held.frames.length, askedLsn });
+        connection.send({
+          type: 'subscribe',
+          v: realtime.PROTOCOL_VERSION,
+          op: 'drop',
+          sid: id,
+          target: { kind: 'query', qid: target.name, input, cursor: null },
+        });
+        await connection.settled();
+        connection.send({
+          type: 'subscribe',
+          v: realtime.PROTOCOL_VERSION,
+          op: 'add',
+          sid: id,
+          target: {
+            kind: 'query',
+            qid: target.name,
+            input,
+            cursor: { ...(held.cursor as Record<string, unknown>), lsn: askedLsn },
+          },
+        });
+        await replicator.settled();
+        await connection.settled();
+      },
+
+      resubscribedFrom: () => state().resumedFrom,
+      snapshots: () => state().snapshots,
+    };
+  };
+
+  return {
+    subscribe,
+    node,
+    replicator,
+    stop: async () => {
+      replicator.stop();
+      await node.stop();
+    },
+  };
+}

package/src/framework-fixtures.ts

@@ -8,6 +8,7 @@ import { createRunJobs } from './fixture-jobs';
 import { createTestMail } from './fixture-mail';
 import { createTestNetwork } from './fixture-network';
 import { createTestStatements } from './fixture-statements';
+import { createSubscribeDriver } from './fixture-subscribe';
 import { defineFixtures } from './fixtures';
 
 /**
@@ -22,6 +23,12 @@ export const FRAMEWORK_FIXTURE_NAMES = [
   'network',
   'runJobs',
   'statements',
+  // Moved here from `DRIVER_FIXTURE_NAMES` on 2026-08-20: the driver it was waiting for is
+  // `createSubscribeDriver()`, and the framework can build one — a whole `sync` node in this
+  // process, over the change source `@ultimat3/entity`'s `setRowObserver` gives it. The four left
+  // in that list all need something the framework genuinely cannot bundle: a browser, or a
+  // second build.
+  'subscribe',
 ] as const;
 
 export { DRIVER_FIXTURE_NAMES };
@@ -46,5 +53,9 @@ export function registerFrameworkFixtures(): void {
     network: createTestNetwork,
     runJobs: createRunJobs,
     statements: createTestStatements,
+    // After the spread, so it REPLACES the `unavailableFixture('subscribe')` declaration above it —
+    // `defineFixtures` merges and the last registration wins, which is the same seam an app's own
+    // driver uses.
+    subscribe: async () => (await createSubscribeDriver()).subscribe,
   });
 }

package/src/index.ts

@@ -91,6 +91,8 @@ export type { TestNetwork } from './fixture-network';
 export { createTestNetwork } from './fixture-network';
 export type { ObservedStatement, StatementShape, TestStatements } from './fixture-statements';
 export { createTestStatements } from './fixture-statements';
+export type { SubscribeDriver } from './fixture-subscribe';
+export { createSubscribeDriver } from './fixture-subscribe';
 export { fixtureTest as test } from './fixtures';
 export {
   ALL_FIXTURE_NAMES,
@@ -100,6 +102,10 @@ export {
 } from './framework-fixtures';
 export type { AppHandle, AppOptions, BootedApp } from './harness';
 export { describeApp, testApp } from './harness';
+export type { LiveConnection, LiveNodeHandle, LiveNodeOptions } from './live-node';
+export { createLiveNode } from './live-node';
+export type { LiveReplicator, LiveReplicatorOptions } from './live-replicator';
+export { startLiveReplicator } from './live-replicator';
 export type { MatcherResult } from './matchers';
 export { matchersInstalled, recordSteps } from './matchers';
 // `isolateEntityRegistry` is deliberately NOT here — it is `@ultimat3/testing/registry-isolation`.

package/src/live-node.ts

@@ -0,0 +1,249 @@
+// A whole `sync` node and one client socket, in this process, with no port and no network. What
+// `x dev --role sync` assembles, minus the listener: the real `LiveQueryRegistry`, the real bridge
+// from every `query({ live: true })` the app declared, the real per-subscriber authz, the real
+// cursor. The only thing replaced is the socket, and it is replaced by a pair of objects that hand
+// each other the same JSON strings a WebSocket would.
+//
+// Dynamically imported by the `subscribe` fixture, never at module load: a test that never
+// subscribes must not pull `@ultimat3/realtime` and `@ultimat3/query` into its process, which is
+// the rule every fixture in this package already follows.
+
+import type { Actor } from '@ultimat3/core';
+import type {
+  ChangeEvent,
+  LiveQueryRegistry,
+  SyncNode,
+  SyncWs,
+  UpgradeTarget,
+  WsData,
+  WsLike,
+} from '@ultimat3/realtime';
+import { liveNodeUnavailable, upgradeRefused } from './errors';
+
+/** Every frame this end received, in order, already parsed. */
+export interface FramePipe {
+  readonly received: readonly unknown[];
+  send(data: string): void;
+}
+
+/**
+ * The server half of the pair. `SyncSocket` writes through `WsLike`, so a fake that records what
+ * it was handed is the whole of what a node needs to talk to a client that is in the same process.
+ * `getBufferedAmount` answers zero: backpressure is a real socket's, and a harness that invented
+ * one would fail a test for a reason no production node would.
+ */
+export class PipeWs implements WsLike {
+  readonly sent: string[] = [];
+  #deliver: (data: string) => void;
+  #closed = false;
+
+  constructor(
+    readonly data: WsData,
+    deliver: (data: string) => void,
+  ) {
+    this.#deliver = deliver;
+  }
+
+  get closed(): boolean {
+    return this.#closed;
+  }
+
+  send(data: string): number {
+    this.sent.push(data);
+    // A dropped connection is a socket that still exists and delivers nothing, which is exactly
+    // what a client observes: the frames the node believes it sent are counted, and none arrive.
+    if (!this.#closed) this.#deliver(data);
+    return data.length;
+  }
+
+  close(): void {
+    this.#closed = true;
+  }
+
+  subscribe(): void {}
+  unsubscribe(): void {}
+
+  getBufferedAmount(): number {
+    return 0;
+  }
+
+  /** Cut the wire without closing the socket — `network.drop()`'s server end. */
+  cut(): void {
+    this.#closed = true;
+  }
+}
+
+export interface LiveNodeOptions {
+  readonly buildId?: string;
+  /** Pins the reconnect epoch, so a test can force a refetch by changing it. */
+  readonly epoch?: string;
+  // No `onMutate`. `SyncNodeOptions` takes one — `{ socket, name, key, seq, input }`, the actor
+  // read off the socket — and nothing here needs it: the mutation half of a live subscription is
+  // the CLIENT's local store and offline queue, which this driver deliberately does not hold. A
+  // forwarded option no test passes is a declaration nothing reads, which is what 4.0.0 spent a
+  // major deleting. It arrives with its first caller, in that caller's shape.
+}
+
+export interface LiveNodeHandle {
+  readonly node: SyncNode;
+  readonly registry: LiveQueryRegistry;
+  /** Open one client connection as this actor. Resolves once the node has the socket. */
+  connect(actor: Actor | null): Promise<LiveConnection>;
+  /** Fan one committed change out to every subscriber. Returns the frames the node sent. */
+  deliver(change: ChangeEvent): Promise<number>;
+  stop(): Promise<void>;
+}
+
+export interface LiveConnection {
+  readonly ws: PipeWs;
+  readonly socketId: string;
+  /** Frames this client received, newest last, already decoded. */
+  frames(): readonly Record<string, unknown>[];
+  /** Hand one frame to the node, exactly as a WebSocket message would arrive. */
+  send(frame: Record<string, unknown>): void;
+  /** Resolves when every frame the node has scheduled for this socket has been written. */
+  settled(): Promise<void>;
+  cut(): void;
+  close(): void;
+}
+
+/**
+ * The actor for a connection travels in the upgrade URL rather than in a token, because both ends
+ * of this pair are the harness: minting a real credential would test `@ultimat3/auth`'s signer, and
+ * a test that has to sign in to assert a row filter is a test about the wrong thing. The node still
+ * runs its real `authenticate` seam, its accept budget and its connection ceiling — what is faked
+ * is the credential, never the path that reads one.
+ */
+const ACTORS = new Map<string, Actor | null>();
+
+let sequence = 0;
+
+export async function createLiveNode(options: LiveNodeOptions = {}): Promise<LiveNodeHandle> {
+  const core = await import('@ultimat3/core');
+  const query = await import('@ultimat3/query');
+  const realtime = await import('@ultimat3/realtime');
+
+  const buildId = options.buildId ?? 'test-build';
+  const transport = new realtime.InProcessTransport();
+  const sockets = new realtime.SocketRegistry();
+  const hub = new realtime.ChannelHub({ transport, sockets });
+  const registry = new realtime.LiveQueryRegistry({ source: new realtime.RingChangeBuffer() });
+
+  const ctx = core.createContext({ role: 'sync', buildId });
+  let live = 0;
+  for (const target of query.listQueries()) {
+    if (!target.isLive) continue;
+    registry.register(
+      realtime.liveQueryDefinition(target, {
+        ctx,
+        ...(options.epoch === undefined ? {} : { epoch: options.epoch }),
+      }),
+    );
+    live += 1;
+  }
+  // A registry with nothing in it answers every subscribe with "no live query registered" — a
+  // working socket serving no reads, which is indistinguishable from a harness that works and an
+  // app that declared nothing. Said here, where the count is known.
+  if (live === 0) throw liveNodeUnavailable();
+
+  const node = realtime.createSyncNode({
+    hub,
+    registry,
+    transport,
+    buildId,
+    sockets,
+    // A grant always, never `null`: `handleUpgrade` answers 401 to a `null` grant, so returning one
+    // for an anonymous connection would refuse the very socket a test asking about anonymous access
+    // needs. `anonymousActor()` is how core spells nobody — policy models it as `null`, core models
+    // it as an actor, and this is core's side of that seam.
+    authenticate: (request: Request) =>
+      Promise.resolve({
+        actor:
+          ACTORS.get(new URL(request.url).searchParams.get('c') ?? '') ?? core.anonymousActor(),
+      }),
+  });
+  await node.start();
+
+  const connections: LiveConnection[] = [];
+
+  return {
+    node,
+    registry,
+    deliver: (change) => registry.deliver(change),
+
+    connect: async (actor) => {
+      sequence += 1;
+      const key = `c${String(sequence)}`;
+      ACTORS.set(key, actor);
+      let data: WsData | undefined;
+      const target: UpgradeTarget = {
+        upgrade: (_request: Request, upgradeOptions: { data: WsData }) => {
+          data = upgradeOptions.data;
+          return true;
+        },
+      };
+      // `/_x/sync` is `SyncNodeOptions.path`'s default and `handleUpgrade` answers 404 to
+      // anything else. The `c` parameter is this connection's actor key — see `ACTORS` above.
+      const refusal = await node.fetch(new Request(`http://sync.test/_x/sync?c=${key}`), target);
+      // A refusal is a REAL one: the accept budget, the connection ceiling or `ready()`. Reported
+      // with what the node answered rather than as "no live query", which is a different failure
+      // and was this line's error until 2026-08-20. Thrown rather than asserted through a namespace
+      // import, which cannot narrow (TS2775).
+      if (data === undefined) throw upgradeRefused(refusal?.status);
+      const received: Record<string, unknown>[] = [];
+      const ws = new PipeWs(data, (raw) => {
+        received.push(JSON.parse(raw) as Record<string, unknown>);
+      });
+      node.websocket.open(ws as unknown as SyncWs);
+      const connection: LiveConnection = {
+        ws,
+        socketId: data.socketId,
+        frames: () => received,
+        send: (frame) => {
+          node.websocket.message(ws as unknown as SyncWs, JSON.stringify(frame));
+        },
+        /**
+         * `message` dispatches into a floating async task — `void (async () => …)()` — so a caller
+         * asserting straight after `send` would be reading frames that have not been routed.
+         *
+         * A MACROTASK yield, not a count of microtask turns. Counting turns is a number that is
+         * right until someone adds an `await`, and it fails as a flake: the first version drained 32
+         * turns and worked against a two-line query while `examples/dummy`'s feed — a repository, a
+         * cache lookup and a policy pass deeper — resolved nothing inside it, so the harness read an
+         * empty frame list as "the node answered nothing". One `setImmediate` drains the entire
+         * microtask queue however deep it is; the loop then repeats until the frame count has
+         * stopped moving for two yields, which is what covers a chain that goes quiet and then
+         * produces again.
+         *
+         * Bounded, because a harness that spins forever on a node that will never answer is worse
+         * than one that gives up and lets the assertion say what is missing. No timer: the preload
+         * freezes the clock this suite runs on, and a sleep would be a race dressed as a wait.
+         */
+        settled: async () => {
+          let quiet = 0;
+          for (let yields = 0; yields < 64 && quiet < 2; yields += 1) {
+            const before = received.length;
+            await new Promise<void>((resolve) => {
+              setImmediate(resolve);
+            });
+            quiet = received.length === before ? quiet + 1 : 0;
+          }
+        },
+        cut: () => {
+          ws.cut();
+        },
+        close: () => {
+          node.websocket.close(ws as unknown as SyncWs);
+          ACTORS.delete(key);
+        },
+      };
+      connections.push(connection);
+      return connection;
+    },
+
+    stop: async () => {
+      for (const connection of connections) connection.close();
+      await node.stop();
+    },
+  };
+}

package/src/live-replicator.ts

@@ -0,0 +1,141 @@
+// The in-process replicator: committed row changes in, `ChangeEvent`s out, fanned into the node.
+//
+// Production decodes the write-ahead log. PGlite has no walsender and the memory driver has no log,
+// so a test process had no change source at all — which is what left the `subscribe` fixture with
+// no driver, and its five tests in `examples/dummy` asserting against a snapshot that never moved.
+//
+// WHAT IS REAL HERE, and it is everything downstream of the decoder: the matcher, the shared window,
+// the per-subscriber `visible` gate, the cursor, the frames. This substitutes for the WAL DECODER
+// and for nothing else — `@ultimat3/entity`'s `setRowObserver` reports what a repository wrote, in
+// this process, and the events are shaped exactly as `PgLogicalReplicationFeed` shapes them.
+//
+// WHAT IS NOT: a write another process made is invisible, because nothing here reads a log. That is
+// the honest bound, and it is why this is a fixture and not a `ChangeFeed` — `selectChangeFeed`
+// still decides what a real node reads, and this is never in that decision.
+
+import type { RowBulkChange, RowChange, RowObserver } from '@ultimat3/entity';
+import type { ChangeEvent, ChangeOp, LiveQueryRegistry, Row } from '@ultimat3/realtime';
+
+/** What a caller does with a change nobody could deliver. */
+export interface LiveReplicatorOptions {
+  readonly registry: LiveQueryRegistry;
+  /** Tenant column, hoisted out of the row so fanout filters without parsing it. */
+  readonly tenantColumn?: string;
+  readonly onError?: (error: unknown) => void;
+}
+
+export interface LiveReplicator {
+  /** Resolves when every change observed so far has been fanned out. Never a sleep. */
+  settled(): Promise<void>;
+  /** Changes this replicator has delivered — the number a test asserts a patch count against. */
+  readonly delivered: number;
+  stop(): void;
+}
+
+const OPS: Readonly<Record<RowChange['op'], ChangeOp>> = {
+  insert: 'insert',
+  update: 'update',
+  delete: 'delete',
+};
+
+/**
+ * A `ChangeEvent` row is `Row` — a JSON object carrying an `id`. Every row a repository stores has
+ * one; the cast is what says so to a compiler that only sees `Record<string, unknown>`, and a row
+ * that genuinely has none fails downstream in `idOf`, with the entity named, exactly as a row off
+ * the wire would.
+ */
+const asRow = (value: Readonly<Record<string, unknown>> | null): Row | null =>
+  value === null ? null : (value as unknown as Row);
+
+/**
+ * Lexicographically comparable, which is the whole contract of an lsn — `formatLsn` in
+ * `@ultimat3/realtime` produces the same shape from a real WAL position. A counter is enough here
+ * because one process observes its own writes in the order it made them.
+ */
+const lsnOf = (position: number): string => position.toString(16).padStart(16, '0');
+
+/**
+ * Install the replicator for the length of one test. It takes over the process row observer and
+ * hands back whatever was installed before, because `bun test` shares one process across files and
+ * an unconditional clear would take an outer harness's observer with it.
+ */
+export async function startLiveReplicator(options: LiveReplicatorOptions): Promise<LiveReplicator> {
+  // Awaited BEFORE the observer exists, so installation is the last thing this function does and
+  // no write between the call and the install can slip past unobserved.
+  const entity = await import('@ultimat3/entity');
+  const { registry } = options;
+  const tenant = options.tenantColumn ?? 'orgId';
+  let position = 0;
+  let delivered = 0;
+  // One promise chain, because ORDERING is the guarantee the whole pipeline is built on — the same
+  // reason `InMemoryChangeFeed` serializes its deliveries rather than firing them concurrently.
+  let tail: Promise<void> = Promise.resolve();
+  let stopped = false;
+
+  const enqueue = (work: () => Promise<void>): void => {
+    tail = tail.then(work).catch((error: unknown) => {
+      // Never rethrown into the chain: one failed fanout must not silence every change behind it,
+      // and a rejection with nobody to hand it to ends the Bun process.
+      options.onError?.(error);
+    });
+  };
+
+  const observer: RowObserver = {
+    onChange(change: RowChange): void {
+      if (stopped) return;
+      position += 1;
+      const at = position;
+      const row = change.after ?? change.before;
+      const orgId = typeof row?.[tenant] === 'string' ? (row[tenant] as string) : null;
+      const event: ChangeEvent = {
+        entity: change.entity,
+        op: OPS[change.op],
+        before: asRow(change.before),
+        after: asRow(change.after),
+        lsn: lsnOf(at),
+        txid: String(at),
+        orgId,
+        // Deliberately not a clock read: the preload freezes `Date.now()`, and a change's commit
+        // time is not something any assertion in this repo reads. `at` keeps it monotonic anyway.
+        at,
+      };
+      enqueue(async () => {
+        delivered += await registry.deliver(event);
+      });
+    },
+
+    /**
+     * A filtered write names rows this seam never saw, so there is no event to shape. Every window
+     * on the node is marked stale instead and re-read on the next change — `invalidate()` is the
+     * node's own answer to "the change stream skipped something", used here for the one write that
+     * genuinely does. Silence would be the alternative, and a subscriber told nothing happened
+     * diverges with nobody ever asking again.
+     */
+    onBulk(_change: RowBulkChange): void {
+      if (stopped) return;
+      registry.invalidate();
+    },
+  };
+
+  const previous = entity.setRowObserver(observer);
+
+  return {
+    get delivered() {
+      return delivered;
+    },
+    settled: async () => {
+      // Twice: a fanout can enqueue nothing, but the writes that produced these changes may still
+      // be resolving their own promises when a test asks. Awaiting the chain, letting the
+      // microtask queue drain, then awaiting it again covers a change observed in between.
+      await tail;
+      for (let turn = 0; turn < 8; turn += 1) await Promise.resolve();
+      await tail;
+    },
+    stop: () => {
+      stopped = true;
+      // Restored, never cleared: one process runs every test file, and an outer harness's observer
+      // must survive an inner fixture finishing.
+      entity.setRowObserver(previous);
+    },
+  };
+}