@syncular/testkit 0.1.2 → 0.2.0

package/README.md

@@ -0,0 +1,210 @@
+# @syncular/testkit
+
+The app-developer test kit. Stand up a whole Syncular backend and N real
+clients in memory, drive them from a `bun test` (or vitest/jest) file, and
+assert what your app sees — convergence, offline queues, conflicts, live
+queries — with **no HTTP server, no browser, no mocks**.
+
+Everything here is the shipped core: the same `SyncClient`
+(`@syncular/client`) and the same `@syncular/server` protocol
+handler your production app runs, wired through an in-process loopback. A
+green test here is real sync behaviour, not a fake.
+
+> Designed for **app tests** — readable and minimal. If you are implementing
+> a Syncular client or server and need the driver/pairing machinery, that is
+> `@syncular/conformance`, not this.
+
+## Install
+
+Workspace-internal only:
+
+```jsonc
+// package.json
+{
+  "devDependencies": {
+    "@syncular/testkit": "workspace:*"
+  }
+}
+```
+
+Requires the Bun runtime (the in-memory client backend is `bun:sqlite`). The
+React helper (`@syncular/testkit/react`) needs `react` — an optional peer.
+
+## 60-second tour
+
+```ts
+import { expect, test } from 'bun:test';
+import { createTestSync } from '@syncular/testkit';
+import { schema } from '../src/syncular.generated'; // your generated schema
+
+test('two clients converge', async () => {
+  const sync = await createTestSync({ schema });
+  const a = await sync.client('a');
+  const b = await sync.client('b');
+
+  const sub = { id: 's', table: 'notes', scopes: { list_id: ['welcome'] } };
+  a.api.subscribe(sub);
+  b.api.subscribe(sub);
+
+  a.api.mutate([
+    { table: 'notes', op: 'upsert', values: { id: 'n1', list_id: 'welcome', body: 'hi' } },
+  ]);
+  await sync.syncAll(); // push A's outbox, pull it into B
+
+  expect(b.api.query('SELECT body FROM notes')).toEqual([{ body: 'hi' }]);
+  await sync.dispose();
+});
+```
+
+`sync.client(id?)` returns a **`TestClient`**. Reach the full client API
+through `.api` (it is a real `SyncClient`: `subscribe`, `mutate`, `query`,
+`syncUntilIdle`, `conflicts`, `setWindow`, `uploadBlob`, …). The `TestClient`
+adds the test-only controls below.
+
+## The surface
+
+### `createTestSync(options) → Promise<TestSync>`
+
+| option          | default                | meaning                                                       |
+| --------------- | ---------------------- | ------------------------------------------------------------- |
+| `schema`        | —                      | your generated `ClientSchema` — feeds server and clients      |
+| `partition`     | `"test"`               | the §1.1 partition every client lives in                      |
+| `actorId`       | `"test-actor"`         | default actor a client authenticates as                       |
+| `resolveScopes` | grant-all              | host authorization (§3.2); omit to grant `'*'` for every var  |
+| `startMs`       | `1_750_000_000_000`    | epoch ms the shared virtual clock starts at                   |
+
+`TestSync`:
+
+- `clock` — the shared `VirtualClock` (below).
+- `server` — the in-memory server (`storage`, `segments`, realtime `hub`).
+- `clients` — every client created, in order.
+- `client(id?, overrides?)` — create **and start** one client.
+- `syncAll()` — `syncUntilIdle()` on every online client until quiescent.
+- `dispose()` — close every client and the server (idempotent).
+
+`overrides` lets a client use a different `actorId` or extra `SyncClient`
+config (e.g. `{ clientConfig: { onConflict: fn } }`).
+
+### `TestClient`
+
+```ts
+client.api            // the real SyncClient
+client.id             // stable client id (§1.5)
+client.actorId        // the actor it authenticates as
+client.faults         // transport-fault controller (below)
+client.offline        // boolean
+
+client.goOffline()    // cut the network — every hop rejects
+client.goOnline()     // restore it (does NOT auto-sync; call sync())
+await client.sync()   // syncUntilIdle: push the outbox, pull to idle
+await client.connectRealtime()    // attach a live socket to the hub
+client.disconnectRealtime()
+await client.close()
+```
+
+### Offline queue / drain
+
+```ts
+a.goOffline();
+a.api.mutate([{ table: 'notes', op: 'upsert', values: { id: 'n1', list_id: 'l', body: 'draft' } }]);
+
+// Visible locally (optimistic), but nothing leaves:
+expect(a.api.query('SELECT body FROM notes')).toEqual([{ body: 'draft' }]);
+expect(a.api.pendingCommits()).toHaveLength(1);
+await expect(a.api.sync()).rejects.toThrow(); // offline
+
+a.goOnline();
+await sync.syncAll();               // the queue drains
+expect(a.api.pendingCommits()).toHaveLength(0);
+```
+
+### Fault injection
+
+`client.faults` is the conformance harness's `TransportFaults` controller,
+**re-exported, not re-implemented** — the same vocabulary the reference
+pairing arms. Arm one flag; the next matching exchange misbehaves:
+
+```ts
+a.faults.dropNextRequests = 1;      // lose the next request (outbox survives)
+a.faults.dropNextResponses = 1;     // server applies it, the ack is lost
+a.faults.duplicateNextRequest = true;   // replay it — idempotency-cache test
+a.faults.truncateNextResponse = true;   // cut the response short (decode error)
+a.faults.truncateNextSegmentDownload = true;
+a.faults.corrupt(bytes);            // flip a seeded byte (§5.1 tamper)
+```
+
+```ts
+a.api.mutate([/* … */]);
+a.faults.dropNextRequests = 1;
+await expect(a.api.sync()).rejects.toThrow();   // request lost
+expect(a.api.pendingCommits()).toHaveLength(1); // still queued
+await a.sync();                                  // retried, drains
+```
+
+### Virtual clock
+
+The server, every client, and the realtime hub share one clock. Time only
+moves when you move it — so §5.1 segment TTLs, §5.4 signed-URL expiry, and
+§7.3 lease windows are deterministic with no wall-clock flake.
+
+```ts
+sync.clock.now();          // current epoch ms
+sync.clock.advance(60_000); // +60s → returns the new now()
+sync.clock.set(1_800_000_000_000); // jump to an absolute instant
+```
+
+> The clock is the epoch-ms source Syncular's clock seam reads. It does **not**
+> intercept `setTimeout`, so presence rate caps / heartbeats (which use real
+> timers) are out of scope — the kit targets sync / offline / fault behaviour.
+
+### Realtime deltas & presence
+
+```ts
+await b.connectRealtime();          // b now has a live socket on the hub
+a.api.mutate([/* … */]);
+await a.sync();                     // the hub fans the commit to b as a delta
+// b applies it without an explicit pull
+```
+
+`goOffline()` also drops the socket; reconnect with `connectRealtime()`.
+
+## React
+
+`@syncular/react`'s `SyncProvider` already takes any `SyncClient`, so
+mounting hooks against a test client is a one-liner. `syncWrapper` builds the
+`wrapper` prop `@testing-library/react` wants:
+
+```tsx
+import { renderHook, act, waitFor } from '@testing-library/react';
+import { useSyncQuery } from '@syncular/react';
+import { createTestSync } from '@syncular/testkit';
+import { syncWrapper } from '@syncular/testkit/react';
+
+const sync = await createTestSync({ schema });
+const client = await sync.client('a');
+client.api.subscribe({ id: 's', table: 'notes', scopes: { list_id: ['x'] } });
+await client.sync();
+
+const { result } = renderHook(
+  () => useSyncQuery('SELECT * FROM notes'),
+  { wrapper: syncWrapper(client) },
+);
+
+await act(async () => {
+  client.api.mutate([{ table: 'notes', op: 'upsert', values: { id: 'n1', list_id: 'x', body: 'hi' } }]);
+});
+await waitFor(() => expect(result.current.rows).toHaveLength(1));
+```
+
+The re-render is driven by the client's **real** invalidation choke point —
+the same one production hooks fire on — so a passing test reflects real
+live-query behaviour.
+
+## What it is not
+
+- Not an HTTP harness. The transport is an in-process loopback; if you need
+  to test your Hono/Workers adapter or real fetch/WebSocket wiring, boot the
+  server yourself (see `examples/quickstart`).
+- Not the conformance runner. No driver/pairing abstraction, no catalog —
+  those live in `@syncular/conformance`.
+- Not a `setTimeout` mock. See the clock note above.

package/dist/client.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The client half of a test sync: a real `SyncClient` on bun:sqlite wired
+ * to the {@link TestServer} through an in-process loopback seam. No HTTP —
+ * the transport calls `handleSyncRequest` directly, the segment downloader
+ * calls `handleSegmentDownload`, and (when realtime is on) the connector
+ * attaches a `RealtimeSession` to the hub. Every hop passes through a fault
+ * gate so an app test can drop / duplicate / corrupt individual exchanges,
+ * and an offline flag that makes every hop reject like a lost network.
+ *
+ * The fault controller is the conformance harness's `TransportFaults`,
+ * re-exported (see `index.ts`) — the SAME vocabulary the reference pairing
+ * arms, not a parallel one.
+ */
+import { type ClientSchema, SyncClient, type SyncClientConfig } from '@syncular/client';
+import type { VirtualClock } from './clock.js';
+import { TransportFaults } from './faults.js';
+import type { TestServer } from './server.js';
+/**
+ * A test client. Everything an app test needs to script a scenario:
+ * the real `SyncClient` (`api`, or spread it — see the getters), the fault
+ * controller, and the connectivity toggle.
+ */
+export interface TestClient {
+    /** The stable client id (§1.5). */
+    readonly id: string;
+    /** The actor this client authenticates as (§1.1). */
+    readonly actorId: string;
+    /** The underlying `SyncClient` — the full shipped client API. */
+    readonly api: SyncClient;
+    /** Transport-seam faults: drop / duplicate / corrupt the next exchange. */
+    readonly faults: TransportFaults;
+    /** True while the client is offline (every hop rejects). */
+    readonly offline: boolean;
+    /** Cut the network: sync / segment / realtime hops reject until online. */
+    goOffline(): void;
+    /** Restore the network. Does NOT auto-sync — call `sync()` yourself. */
+    goOnline(): void;
+    /** Push the outbox and pull to quiescence (`SyncClient.syncUntilIdle`). */
+    sync(): Promise<void>;
+    /** Attach a realtime socket to the hub (deltas, presence, socket rounds). */
+    connectRealtime(): Promise<void>;
+    /** Detach the realtime socket. */
+    disconnectRealtime(): void;
+    /** Close the client and its database. */
+    close(): Promise<void>;
+}
+export interface TestClientOptions {
+    readonly server: TestServer;
+    readonly schema: ClientSchema;
+    readonly clock: VirtualClock;
+    readonly id: string;
+    readonly actorId: string;
+    /**
+     * Extra `SyncClient` config merged over the loopback defaults — e.g.
+     * `onConflict`, `limits`. `database`, `schema`, `clientId`, `now`,
+     * `transport`, `segments`, and `realtime` are owned by the kit.
+     */
+    readonly clientConfig?: Partial<Omit<SyncClientConfig, 'database' | 'schema' | 'clientId' | 'now' | 'transport' | 'segments' | 'realtime'>>;
+}
+/**
+ * Build a `TestClient`. The client is NOT started — the caller (or
+ * `createTestSync`) awaits `api.start()`. Split out so `createTestSync` can
+ * construct and start in one place.
+ */
+export declare function buildTestClient(options: TestClientOptions): {
+    client: TestClient;
+    start: () => Promise<void>;
+};

package/dist/client.js

@@ -0,0 +1,145 @@
+/**
+ * The client half of a test sync: a real `SyncClient` on bun:sqlite wired
+ * to the {@link TestServer} through an in-process loopback seam. No HTTP —
+ * the transport calls `handleSyncRequest` directly, the segment downloader
+ * calls `handleSegmentDownload`, and (when realtime is on) the connector
+ * attaches a `RealtimeSession` to the hub. Every hop passes through a fault
+ * gate so an app test can drop / duplicate / corrupt individual exchanges,
+ * and an offline flag that makes every hop reject like a lost network.
+ *
+ * The fault controller is the conformance harness's `TransportFaults`,
+ * re-exported (see `index.ts`) — the SAME vocabulary the reference pairing
+ * arms, not a parallel one.
+ */
+import { SyncClient, } from '@syncular/client';
+import { BunClientDatabase } from '@syncular/client/bun';
+import { handleSegmentDownload, handleSyncRequest } from '@syncular/server';
+import { seededRandom, TransportFault, TransportFaults } from './faults.js';
+/** A client-facing offline error: rejects a hop the way a dead network does. */
+class OfflineError extends Error {
+    name = 'OfflineError';
+    code = 'sync.transport_failed';
+    retryable = true;
+    constructor() {
+        super('injected: client is offline');
+    }
+}
+/**
+ * Build a `TestClient`. The client is NOT started — the caller (or
+ * `createTestSync`) awaits `api.start()`. Split out so `createTestSync` can
+ * construct and start in one place.
+ */
+export function buildTestClient(options) {
+    const { server, schema, clock, id, actorId } = options;
+    const db = new BunClientDatabase();
+    const faults = new TransportFaults(seededRandom(hashSeed(id)));
+    const state = { offline: false };
+    const ctx = () => server.ctxFor(actorId);
+    const transport = async (request) => {
+        if (state.offline)
+            throw new OfflineError();
+        if (faults.dropNextRequests > 0) {
+            faults.dropNextRequests -= 1;
+            throw new TransportFault('injected: request lost');
+        }
+        if (faults.duplicateNextRequest) {
+            faults.duplicateNextRequest = false;
+            // First delivery is processed by the server; its response is discarded
+            // (the §6 idempotency cache absorbs the replay on the second delivery).
+            await handleSyncRequest(request, ctx());
+        }
+        const bytes = await handleSyncRequest(request, ctx());
+        if (faults.dropNextResponses > 0) {
+            faults.dropNextResponses -= 1;
+            throw new TransportFault('injected: response lost');
+        }
+        if (faults.truncateNextResponse) {
+            faults.truncateNextResponse = false;
+            return faults.truncate(bytes);
+        }
+        return bytes;
+    };
+    const segments = async (request) => {
+        if (state.offline)
+            throw new OfflineError();
+        if (faults.dropNextSegmentRequests > 0) {
+            faults.dropNextSegmentRequests -= 1;
+            throw new TransportFault('injected: segment request lost');
+        }
+        const result = await handleSegmentDownload(ctx(), {
+            segmentId: request.segmentId,
+            scopesHeader: request.requestedScopesJson,
+        });
+        if (faults.truncateNextSegmentDownload) {
+            faults.truncateNextSegmentDownload = false;
+            return faults.truncate(result.bytes);
+        }
+        return result.bytes;
+    };
+    const realtime = async (handlers) => {
+        if (state.offline)
+            throw new OfflineError();
+        const session = await server.hub.connect({
+            partition: server.partition,
+            actorId,
+            clientId: id,
+            send: (data) => {
+                if (typeof data === 'string')
+                    handlers.onText(data);
+                else
+                    handlers.onBinary(data);
+            },
+        });
+        return {
+            send: (text) => session.handleMessage(text),
+            sendBytes: (bytes) => session.handleBinary(bytes),
+            close: () => {
+                session.close();
+                handlers.onClose?.();
+            },
+        };
+    };
+    const api = new SyncClient({
+        database: db,
+        schema,
+        clientId: id,
+        now: () => clock.now(),
+        transport,
+        segments,
+        realtime,
+        ...options.clientConfig,
+    });
+    const client = {
+        id,
+        actorId,
+        api,
+        faults,
+        get offline() {
+            return state.offline;
+        },
+        goOffline: () => {
+            state.offline = true;
+            api.disconnectRealtime();
+        },
+        goOnline: () => {
+            state.offline = false;
+        },
+        sync: async () => {
+            await api.syncUntilIdle();
+        },
+        connectRealtime: () => api.connectRealtime(),
+        disconnectRealtime: () => api.disconnectRealtime(),
+        close: () => api.close(),
+    };
+    return { client, start: () => api.start() };
+}
+/** Deterministic per-client fault seed from the client id (mirrors the
+ * conformance harness's per-scenario seeding). */
+function hashSeed(name) {
+    let hash = 2166136261;
+    for (let i = 0; i < name.length; i++) {
+        hash ^= name.charCodeAt(i);
+        hash = Math.imul(hash, 16777619);
+    }
+    return hash >>> 0;
+}

package/dist/clock.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A virtual clock the whole test sync shares — server, every client, and
+ * the realtime hub read the same `now()`. Time only moves when the test
+ * moves it, so §5.1 TTLs, §5.4 signed-URL expiry, and §7.3 lease windows
+ * are exercised deterministically with no wall-clock flake.
+ *
+ * This is deliberately NOT a fake-timers shim: it does not intercept
+ * `setTimeout`. It is the single epoch-ms source that Syncular's clock seam
+ * (`SyncServerConfig.clock`, `SyncClientConfig.now`) reads. Presence rate
+ * caps and heartbeats, which use real `setTimeout`, are out of scope — the
+ * kit targets sync/offline/fault behaviour, not wall-clock scheduling.
+ */
+/** The default epoch (ms) a fresh clock starts at — a fixed, readable point
+ * so golden values and TTL maths are stable across runs. */
+export declare const DEFAULT_EPOCH_MS = 1750000000000;
+export interface VirtualClock {
+    /** Current time in epoch ms — the value the clock seam returns. */
+    now(): number;
+    /** Move time forward by `ms` (must be ≥ 0). Returns the new `now()`. */
+    advance(ms: number): number;
+    /** Jump to an absolute epoch-ms instant. Returns the new `now()`. */
+    set(ms: number): number;
+}
+export declare function createVirtualClock(startMs?: number): VirtualClock;

package/dist/clock.js

@@ -0,0 +1,32 @@
+/**
+ * A virtual clock the whole test sync shares — server, every client, and
+ * the realtime hub read the same `now()`. Time only moves when the test
+ * moves it, so §5.1 TTLs, §5.4 signed-URL expiry, and §7.3 lease windows
+ * are exercised deterministically with no wall-clock flake.
+ *
+ * This is deliberately NOT a fake-timers shim: it does not intercept
+ * `setTimeout`. It is the single epoch-ms source that Syncular's clock seam
+ * (`SyncServerConfig.clock`, `SyncClientConfig.now`) reads. Presence rate
+ * caps and heartbeats, which use real `setTimeout`, are out of scope — the
+ * kit targets sync/offline/fault behaviour, not wall-clock scheduling.
+ */
+/** The default epoch (ms) a fresh clock starts at — a fixed, readable point
+ * so golden values and TTL maths are stable across runs. */
+export const DEFAULT_EPOCH_MS = 1_750_000_000_000;
+export function createVirtualClock(startMs = DEFAULT_EPOCH_MS) {
+    let ms = startMs;
+    return {
+        now: () => ms,
+        advance: (delta) => {
+            if (delta < 0) {
+                throw new Error(`clock.advance: time cannot move backwards (${delta}ms)`);
+            }
+            ms += delta;
+            return ms;
+        },
+        set: (next) => {
+            ms = next;
+            return ms;
+        },
+    };
+}

package/dist/create-test-sync.d.ts

@@ -0,0 +1,67 @@
+/**
+ * `createTestSync` — the one call an app test makes. It stands up an
+ * in-memory Syncular backend and hands back a factory for N real clients,
+ * all sharing one virtual clock, all talking to the server through an
+ * in-process loopback (no HTTP unless you ask). Everything is the SHIPPED
+ * core; the kit is wiring, not a mock.
+ *
+ *     const sync = await createTestSync({ schema });
+ *     const a = await sync.client('a');
+ *     const b = await sync.client('b');
+ *     a.api.subscribe({ id: 's', table: 'notes', scopes: { list_id: ['x'] } });
+ *     b.api.subscribe({ id: 's', table: 'notes', scopes: { list_id: ['x'] } });
+ *     a.api.mutate([{ table: 'notes', op: 'upsert', values: … }]);
+ *     await sync.syncAll();           // both converge
+ *     await sync.dispose();
+ */
+import type { ClientSchema, SyncClientConfig } from '@syncular/client';
+import type { ResolveScopes } from '@syncular/server';
+import { type TestClient } from './client.js';
+import { type VirtualClock } from './clock.js';
+import { type TestServer } from './server.js';
+export interface CreateTestSyncOptions {
+    /**
+     * The generated schema (`syncular.generated.ts`'s `schema`, or any
+     * `ClientSchema`). The same object feeds the server and every client — a
+     * single-version, matched-schema world, which is what an app test wants.
+     */
+    readonly schema: ClientSchema;
+    /** Partition every client lives in (§1.1); defaults to `"test"`. */
+    readonly partition?: string;
+    /** Default actor a client authenticates as; defaults to `"test-actor"`. */
+    readonly actorId?: string;
+    /**
+     * Host authorization (§3.2 step 3). Omit for "grant everything" — the
+     * default resolver returns `'*'` for every scope variable the schema
+     * declares. Provide your own to test scope-scoping / revocation; it runs
+     * in the server exactly as it would in production.
+     */
+    readonly resolveScopes?: ResolveScopes;
+    /** Epoch ms the shared virtual clock starts at (default 1_750_000_000_000). */
+    readonly startMs?: number;
+}
+export interface TestClientOverrides {
+    /** Actor id for this client (defaults to the sync-wide actor). */
+    readonly actorId?: string;
+    /** Extra `SyncClient` config (e.g. `onConflict`, `limits`). */
+    readonly clientConfig?: Partial<Omit<SyncClientConfig, 'database' | 'schema' | 'clientId' | 'now' | 'transport' | 'segments' | 'realtime'>>;
+}
+export interface TestSync {
+    /** The shared virtual clock — server + every client read it. */
+    readonly clock: VirtualClock;
+    /** The in-memory server (storage / segments / realtime hub). */
+    readonly server: TestServer;
+    /** Every client created so far, in creation order. */
+    readonly clients: readonly TestClient[];
+    /**
+     * Create and start one client. `id` is its stable client id (§1.5);
+     * omit for an auto-generated one. Returns once `start()` has run, so the
+     * client is ready to `subscribe` / `mutate` immediately.
+     */
+    client(id?: string, overrides?: TestClientOverrides): Promise<TestClient>;
+    /** `syncUntilIdle` on every online client — the "let them converge" step. */
+    syncAll(): Promise<void>;
+    /** Close every client and the server. Idempotent. */
+    dispose(): Promise<void>;
+}
+export declare function createTestSync(options: CreateTestSyncOptions): Promise<TestSync>;

package/dist/create-test-sync.js

@@ -0,0 +1,90 @@
+/**
+ * `createTestSync` — the one call an app test makes. It stands up an
+ * in-memory Syncular backend and hands back a factory for N real clients,
+ * all sharing one virtual clock, all talking to the server through an
+ * in-process loopback (no HTTP unless you ask). Everything is the SHIPPED
+ * core; the kit is wiring, not a mock.
+ *
+ *     const sync = await createTestSync({ schema });
+ *     const a = await sync.client('a');
+ *     const b = await sync.client('b');
+ *     a.api.subscribe({ id: 's', table: 'notes', scopes: { list_id: ['x'] } });
+ *     b.api.subscribe({ id: 's', table: 'notes', scopes: { list_id: ['x'] } });
+ *     a.api.mutate([{ table: 'notes', op: 'upsert', values: … }]);
+ *     await sync.syncAll();           // both converge
+ *     await sync.dispose();
+ */
+import { buildTestClient } from './client.js';
+import { createVirtualClock } from './clock.js';
+import { createTestServer, DEFAULT_ACTOR, DEFAULT_PARTITION, } from './server.js';
+export async function createTestSync(options) {
+    const partition = options.partition ?? DEFAULT_PARTITION;
+    const defaultActor = options.actorId ?? DEFAULT_ACTOR;
+    const clock = createVirtualClock(options.startMs);
+    const server = createTestServer({
+        schema: options.schema,
+        clock,
+        partition,
+        ...(options.resolveScopes !== undefined
+            ? { resolveScopes: options.resolveScopes }
+            : {}),
+    });
+    const clients = [];
+    let autoId = 0;
+    let disposed = false;
+    const sync = {
+        clock,
+        server,
+        clients,
+        client: async (id, overrides) => {
+            const clientId = id ?? `client-${++autoId}`;
+            const { client, start } = buildTestClient({
+                server,
+                schema: options.schema,
+                clock,
+                id: clientId,
+                actorId: overrides?.actorId ?? defaultActor,
+                ...(overrides?.clientConfig !== undefined
+                    ? { clientConfig: overrides.clientConfig }
+                    : {}),
+            });
+            await start();
+            clients.push(client);
+            return client;
+        },
+        syncAll: async () => {
+            // Sequential, not parallel: the reference server serializes anyway, and
+            // sequential rounds make cross-client convergence order deterministic.
+            // Repeat until no online client still has pending commits — one pass of
+            // A's push may be another's pull.
+            for (let pass = 0; pass < 20; pass++) {
+                let progressed = false;
+                for (const client of clients) {
+                    if (client.offline)
+                        continue;
+                    const before = client.api.pendingCommits().length;
+                    await client.sync();
+                    if (before > 0)
+                        progressed = true;
+                }
+                if (!progressed)
+                    return;
+            }
+        },
+        dispose: async () => {
+            if (disposed)
+                return;
+            disposed = true;
+            for (const client of clients) {
+                try {
+                    await client.close();
+                }
+                catch {
+                    // best-effort teardown; keep closing the rest
+                }
+            }
+            server.close();
+        },
+    };
+    return sync;
+}