@syncular/client 0.45.0 → 0.46.3

package/dist/client.d.ts

@@ -95,6 +95,16 @@ export interface SyncSummary {
 export interface SyncIdleResult extends SyncSummary {
     readonly budgetExhausted: boolean;
 }
+export interface SyncIdleOptions {
+    /** §7.7: a strict positive round count. Default: 20. */
+    readonly maxRounds?: number;
+    /**
+     * Total wall-clock budget for one drive, across every round. When it
+     * elapses the drive rejects with `sync.idle_timeout`; a socket round in
+     * flight is aborted. Default: 60,000 ms. `Infinity` disables the bound.
+     */
+    readonly timeoutMs?: number;
+}
 export interface SyncClientLimits {
     readonly limitCommits?: number;
     readonly limitSnapshotRows?: number;
@@ -663,8 +673,13 @@ export declare class SyncClient {
      * caller may have mutated the outbox after the in-flight drive captured it.
      * Callers that arrive during the same drive with the same budget share that
      * single follow-up. `sync()` keeps rejecting a concurrent `sync()`.
+     *
+     * §7.7: one drive is bounded by a total deadline (`timeoutMs`, default
+     * 60 s). A drive that reaches it rejects with `sync.idle_timeout` and
+     * aborts a socket round in flight; the round budget does not bound elapsed
+     * time, and a transport that never answers must not hang the caller.
      */
-    syncUntilIdle(maxRounds?: number): Promise<SyncIdleResult>;
+    syncUntilIdle(options?: number | SyncIdleOptions): Promise<SyncIdleResult>;
     connectRealtime(): Promise<void>;
     disconnectRealtime(): void;
 }

package/dist/client.js

@@ -86,6 +86,8 @@ function emptySummary(pushed) {
     };
 }
 const LOG_EPOCH_META_KEY = 'logEpoch';
+/** §7.7: one `syncUntilIdle` drive's default total deadline. */
+const SYNC_IDLE_TIMEOUT_MS = 60_000;
 /** RFC 0005 defaults (D2/A4/D7). */
 const PREVIOUS_VERSION_DEFAULT_MAX_BYTES = 8 * 1024 * 1024;
 const PREVIOUS_VERSION_DEFAULT_MAX_ROWS = 20_000;
@@ -181,8 +183,9 @@ export class SyncClient {
     /**
      * Idle drives run one after another (§8.4): `#syncIdleTail` settles when
      * the last scheduled drive settles, and `#syncIdlePending` holds the
-     * scheduled drives that have not started, keyed by round budget, so a
-     * caller joins a waiting drive with its budget instead of queueing another.
+     * scheduled drives that have not started, keyed by round budget and
+     * deadline, so a caller joins a waiting drive with its budget instead of
+     * queueing another.
      */
     #syncIdleTail;
     #syncIdlePending = new Map();
@@ -2959,7 +2962,22 @@ export class SyncClient {
             const explicitlyRetryable = error.retryable;
             const retryable = explicitlyRetryable === true ||
                 (explicitlyRetryable === undefined && typeof code !== 'string');
-            if (retryable) {
+            // §1.8: a refused or unreachable endpoint (`connect` from the native
+            // transport, `network` from a browser fetch) is not a round worth
+            // backing off for. Stop without scheduling an intent or growing the
+            // delay; the host's own connectivity signal re-arms the drive.
+            const details = error instanceof ClientSyncError
+                ? error.details
+                : typeof error === 'object' && error !== null && 'details' in error
+                    ? error.details
+                    : undefined;
+            const causeKind = typeof details === 'object' &&
+                details !== null &&
+                'causeKind' in details
+                ? details.causeKind
+                : undefined;
+            const unreachable = causeKind === 'connect' || causeKind === 'network';
+            if (retryable && !unreachable) {
                 const realtimeUnavailable = error instanceof RealtimeUnavailableError;
                 const delay = realtimeUnavailable
                     ? error.retryDelayMs
@@ -2994,27 +3012,40 @@ export class SyncClient {
      * caller may have mutated the outbox after the in-flight drive captured it.
      * Callers that arrive during the same drive with the same budget share that
      * single follow-up. `sync()` keeps rejecting a concurrent `sync()`.
+     *
+     * §7.7: one drive is bounded by a total deadline (`timeoutMs`, default
+     * 60 s). A drive that reaches it rejects with `sync.idle_timeout` and
+     * aborts a socket round in flight; the round budget does not bound elapsed
+     * time, and a transport that never answers must not hang the caller.
      */
-    async syncUntilIdle(maxRounds) {
+    async syncUntilIdle(options) {
+        const maxRounds = typeof options === 'number' ? options : options?.maxRounds;
+        const timeoutMs = typeof options === 'number'
+            ? SYNC_IDLE_TIMEOUT_MS
+            : (options?.timeoutMs ?? SYNC_IDLE_TIMEOUT_MS);
         // §7.7: an explicit budget is a strict positive round count. Zero,
         // fractional, and out-of-range values are caller errors.
         if (maxRounds !== undefined &&
             (!Number.isInteger(maxRounds) || maxRounds < 1 || maxRounds > 0xffffffff))
             throw invalidRequest('maxRounds must be a positive integer');
-        const pending = this.#syncIdlePending.get(maxRounds);
+        if (timeoutMs !== Number.POSITIVE_INFINITY &&
+            !(Number.isFinite(timeoutMs) && timeoutMs > 0))
+            throw invalidRequest('timeoutMs must be a positive number or Infinity');
+        const key = `${maxRounds ?? 'default'}:${timeoutMs}`;
+        const pending = this.#syncIdlePending.get(key);
         if (pending !== undefined)
             return pending;
         const previous = this.#syncIdleTail;
         let drive;
         if (previous === undefined) {
-            drive = this.#syncIdleRounds(maxRounds);
+            drive = this.#syncIdleRounds(maxRounds, timeoutMs);
         }
         else {
             drive = previous.then(() => {
-                this.#syncIdlePending.delete(maxRounds);
-                return this.#syncIdleRounds(maxRounds);
+                this.#syncIdlePending.delete(key);
+                return this.#syncIdleRounds(maxRounds, timeoutMs);
             });
-            this.#syncIdlePending.set(maxRounds, drive);
+            this.#syncIdlePending.set(key, drive);
         }
         const tail = drive.then(() => undefined, () => undefined);
         this.#syncIdleTail = tail;
@@ -3025,7 +3056,7 @@ export class SyncClient {
         return drive;
     }
     /** The rounds loop of one idle drive; `syncUntilIdle` owns coalescing. */
-    async #syncIdleRounds(maxRounds) {
+    async #syncIdleRounds(maxRounds, timeoutMs) {
         const budget = maxRounds ?? 20;
         const aggregate = {
             pushed: 0,
@@ -3062,46 +3093,76 @@ export class SyncClient {
                 : {}),
             budgetExhausted,
         });
-        for (let round = 0; round < budget; round++) {
-            const before = JSON.stringify(loadSubscriptions(this.#db).map((sub) => [sub.id, sub.bootstrapState]));
-            const last = await this.sync();
-            // Historical counters accumulate; current readiness (`bootstrapping`,
-            // `deferredCommits`, `schemaFloor`) describes the latest round.
-            aggregate.pushed += last.pushed;
-            aggregate.applied.push(...last.applied);
-            aggregate.rejected.push(...last.rejected);
-            aggregate.retryable.push(...last.retryable);
-            aggregate.conflicts.push(...last.conflicts);
-            aggregate.commitsApplied += last.commitsApplied;
-            aggregate.segmentRowsApplied += last.segmentRowsApplied;
-            aggregate.bootstrapping = [...last.bootstrapping];
-            aggregate.resets.push(...last.resets);
-            aggregate.revoked.push(...last.revoked);
-            aggregate.failed.push(...last.failed);
-            aggregate.deferredCommits = last.deferredCommits ?? 0;
-            aggregate.schemaFloor = last.schemaFloor;
-            // A disabled transport or a schema floor ends the loop, not the budget.
-            if (!this.#transportEnabled || last.schemaFloor !== undefined)
-                return result(false);
-            if (maxRounds === undefined &&
-                last.segmentRowsApplied > 0 &&
-                last.bootstrapping.length > 0 &&
-                before !==
-                    JSON.stringify(loadSubscriptions(this.#db).map((sub) => [
-                        sub.id,
-                        sub.bootstrapState,
-                    ])))
-                round = -1;
-            if (last.commitsApplied === 0 &&
-                last.segmentRowsApplied === 0 &&
-                last.bootstrapping.length === 0 &&
-                last.resets.length === 0 &&
-                (last.deferredCommits ?? 0) === 0 &&
-                !this.#needsPull) {
-                return result(false);
+        let round = 0;
+        let expired = false;
+        let timer;
+        const deadline = timeoutMs === Number.POSITIVE_INFINITY
+            ? undefined
+            : new Promise((_, reject) => {
+                timer = setTimeout(() => {
+                    expired = true;
+                    // The transport may never answer; release the round so the
+                    // client can run another one after the caller sees the error.
+                    this.#abortPendingRound('syncUntilIdle deadline exceeded');
+                    reject(new ClientSyncError('sync.idle_timeout', 'syncUntilIdle exceeded its deadline', true, { timeoutMs, rounds: round }));
+                }, timeoutMs);
+            });
+        const drive = (async () => {
+            for (; round < budget; round++) {
+                // The race already rejected; stop spending rounds on a dead drive.
+                if (expired)
+                    throw new ClientSyncError('sync.idle_timeout', 'syncUntilIdle exceeded its deadline', true, { timeoutMs, rounds: round });
+                const before = JSON.stringify(loadSubscriptions(this.#db).map((sub) => [
+                    sub.id,
+                    sub.bootstrapState,
+                ]));
+                const last = await this.sync();
+                // Historical counters accumulate; current readiness (`bootstrapping`,
+                // `deferredCommits`, `schemaFloor`) describes the latest round.
+                aggregate.pushed += last.pushed;
+                aggregate.applied.push(...last.applied);
+                aggregate.rejected.push(...last.rejected);
+                aggregate.retryable.push(...last.retryable);
+                aggregate.conflicts.push(...last.conflicts);
+                aggregate.commitsApplied += last.commitsApplied;
+                aggregate.segmentRowsApplied += last.segmentRowsApplied;
+                aggregate.bootstrapping = [...last.bootstrapping];
+                aggregate.resets.push(...last.resets);
+                aggregate.revoked.push(...last.revoked);
+                aggregate.failed.push(...last.failed);
+                aggregate.deferredCommits = last.deferredCommits ?? 0;
+                aggregate.schemaFloor = last.schemaFloor;
+                // A disabled transport or a schema floor ends the loop, not the budget.
+                if (!this.#transportEnabled || last.schemaFloor !== undefined)
+                    return result(false);
+                if (maxRounds === undefined &&
+                    last.segmentRowsApplied > 0 &&
+                    last.bootstrapping.length > 0 &&
+                    before !==
+                        JSON.stringify(loadSubscriptions(this.#db).map((sub) => [
+                            sub.id,
+                            sub.bootstrapState,
+                        ])))
+                    round = -1;
+                if (last.commitsApplied === 0 &&
+                    last.segmentRowsApplied === 0 &&
+                    last.bootstrapping.length === 0 &&
+                    last.resets.length === 0 &&
+                    (last.deferredCommits ?? 0) === 0 &&
+                    !this.#needsPull) {
+                    return result(false);
+                }
             }
+            return result(true);
+        })();
+        try {
+            return await (deadline === undefined
+                ? drive
+                : Promise.race([drive, deadline]));
+        }
+        finally {
+            clearTimeout(timer);
         }
-        return result(true);
     }
     /**
      * One request/response round trip (§8.7): over the socket whenever it

package/dist/worker-entry.js

@@ -367,9 +367,9 @@ export function startSyncWorker(overrides = {}) {
             const running = requireClient();
             return serializedSync(() => running.sync());
         },
-        syncUntilIdle: (maxRounds) => {
+        syncUntilIdle: (options) => {
             const running = requireClient();
-            return serializedSync(() => running.syncUntilIdle(maxRounds));
+            return serializedSync(() => running.syncUntilIdle(options));
         },
         resetClientId: () => requireClient().resetClientId(),
         localRevision: () => requireClient().localRevision,

package/dist/worker-host.d.ts

@@ -25,7 +25,7 @@ import type { PromiseMethods } from './client.js';
  */
 import type { WakeReason } from '@syncular/core';
 import type { BlobRef, CachedBlob } from './blob.js';
-import type { ConflictRecord, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, SecurityLifecycle, SnapshotRead, SnapshotReadRequest, SubscribeInput, SyncClientConfig, SyncClientLimits, SyncSummary, SyncIdleResult, WindowState } from './client.js';
+import type { ConflictRecord, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, SecurityLifecycle, SnapshotRead, SnapshotReadRequest, SubscribeInput, SyncClientConfig, SyncClientLimits, SyncSummary, SyncIdleOptions, SyncIdleResult, WindowState } from './client.js';
 import type { SqlRow, SqlValue } from './database.js';
 import { ClientDiagnosticsEmitter, type ClientDiagnosticsListener, type ClientDiagnosticsRequest, type ClientDiagnosticsSnapshot, type RealtimePolicy } from './diagnostics.js';
 import type { EncryptionKeyringConfig } from './encryption.js';
@@ -245,7 +245,7 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
         discarded: boolean;
     }>;
     sync(): Promise<SyncSummary>;
-    syncUntilIdle(maxRounds?: number): Promise<SyncIdleResult>;
+    syncUntilIdle(options?: number | SyncIdleOptions): Promise<SyncIdleResult>;
     /**
      * Rotate the client id (§1.5) after a `sync.invalid_client_id` refusal.
      * The worker's next round carries the new id; the replica and outbox stay

package/dist/worker-host.js

@@ -329,8 +329,8 @@ export class SyncClientHandle {
     sync() {
         return this.#call('sync', []);
     }
-    syncUntilIdle(maxRounds) {
-        return this.#call('syncUntilIdle', [maxRounds]);
+    syncUntilIdle(options) {
+        return this.#call('syncUntilIdle', [options]);
     }
     /**
      * Rotate the client id (§1.5) after a `sync.invalid_client_id` refusal.

package/dist/worker-protocol.d.ts

@@ -19,7 +19,7 @@ import type { SyncProgress } from './progress.js';
  */
 import type { WakeReason } from '@syncular/core';
 import type { BlobRef, CachedBlob } from './blob.js';
-import type { ConflictRecord, ClientSnapshotMethods, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, SecurityLifecycle, SubscribeInput, SyncClientConfig, SyncClientLimits, SyncSummary, SyncIdleResult, WindowState } from './client.js';
+import type { ConflictRecord, ClientSnapshotMethods, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, SecurityLifecycle, SubscribeInput, SyncClientConfig, SyncClientLimits, SyncSummary, SyncIdleOptions, SyncIdleResult, WindowState } from './client.js';
 import type { SqlRow, SqlValue } from './database.js';
 import type { ClientDiagnosticsSnapshot, RealtimePolicy } from './diagnostics.js';
 import type { EncryptionKeyringConfig } from './encryption.js';
@@ -138,7 +138,7 @@ export interface WorkerApi extends Omit<ClientSnapshotMethods, 'querySnapshot'>
         discarded: boolean;
     };
     sync(): Promise<SyncSummary>;
-    syncUntilIdle(maxRounds?: number): Promise<SyncIdleResult>;
+    syncUntilIdle(options?: number | SyncIdleOptions): Promise<SyncIdleResult>;
     resetClientId(): string;
     query(sql: string, params?: readonly SqlValue[]): SqlRow[];
     authoritySnapshot(): import('./authority.js').AuthoritySnapshot;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.45.0",
+  "version": "0.46.3",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -97,10 +97,10 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.45.0"
+    "@syncular/core": "0.46.3"
   },
   "devDependencies": {
-    "@syncular/server": "0.45.0",
+    "@syncular/server": "0.46.3",
     "playwright": "1.63.0",
     "@electric-sql/pglite": "^0.5.4"
   }

package/src/client.ts

@@ -354,6 +354,17 @@ export interface SyncIdleResult extends SyncSummary {
   readonly budgetExhausted: boolean;
 }
 
+export interface SyncIdleOptions {
+  /** §7.7: a strict positive round count. Default: 20. */
+  readonly maxRounds?: number;
+  /**
+   * Total wall-clock budget for one drive, across every round. When it
+   * elapses the drive rejects with `sync.idle_timeout`; a socket round in
+   * flight is aborted. Default: 60,000 ms. `Infinity` disables the bound.
+   */
+  readonly timeoutMs?: number;
+}
+
 export interface SyncClientLimits {
   readonly limitCommits?: number;
   readonly limitSnapshotRows?: number;
@@ -730,6 +741,9 @@ function emptySummary(pushed: number): MutableSummary {
 
 const LOG_EPOCH_META_KEY = 'logEpoch';
 
+/** §7.7: one `syncUntilIdle` drive's default total deadline. */
+const SYNC_IDLE_TIMEOUT_MS = 60_000;
+
 /** RFC 0005 defaults (D2/A4/D7). */
 const PREVIOUS_VERSION_DEFAULT_MAX_BYTES = 8 * 1024 * 1024;
 const PREVIOUS_VERSION_DEFAULT_MAX_ROWS = 20_000;
@@ -898,14 +912,12 @@ export class SyncClient {
   /**
    * Idle drives run one after another (§8.4): `#syncIdleTail` settles when
    * the last scheduled drive settles, and `#syncIdlePending` holds the
-   * scheduled drives that have not started, keyed by round budget, so a
-   * caller joins a waiting drive with its budget instead of queueing another.
+   * scheduled drives that have not started, keyed by round budget and
+   * deadline, so a caller joins a waiting drive with its budget instead of
+   * queueing another.
    */
   #syncIdleTail: Promise<void> | undefined;
-  readonly #syncIdlePending = new Map<
-    number | undefined,
-    Promise<SyncIdleResult>
-  >();
+  readonly #syncIdlePending = new Map<string, Promise<SyncIdleResult>>();
   /**
    * Bumped by every local projection reset (`rebootstrapLocalData`). A sync
    * round captures this epoch together with its subscription state; a
@@ -4270,7 +4282,24 @@ export class SyncClient {
       const retryable =
         explicitlyRetryable === true ||
         (explicitlyRetryable === undefined && typeof code !== 'string');
-      if (retryable) {
+      // §1.8: a refused or unreachable endpoint (`connect` from the native
+      // transport, `network` from a browser fetch) is not a round worth
+      // backing off for. Stop without scheduling an intent or growing the
+      // delay; the host's own connectivity signal re-arms the drive.
+      const details =
+        error instanceof ClientSyncError
+          ? error.details
+          : typeof error === 'object' && error !== null && 'details' in error
+            ? error.details
+            : undefined;
+      const causeKind =
+        typeof details === 'object' &&
+        details !== null &&
+        'causeKind' in details
+          ? details.causeKind
+          : undefined;
+      const unreachable = causeKind === 'connect' || causeKind === 'network';
+      if (retryable && !unreachable) {
         const realtimeUnavailable = error instanceof RealtimeUnavailableError;
         const delay = realtimeUnavailable
           ? error.retryDelayMs
@@ -4307,8 +4336,21 @@ export class SyncClient {
    * caller may have mutated the outbox after the in-flight drive captured it.
    * Callers that arrive during the same drive with the same budget share that
    * single follow-up. `sync()` keeps rejecting a concurrent `sync()`.
+   *
+   * §7.7: one drive is bounded by a total deadline (`timeoutMs`, default
+   * 60 s). A drive that reaches it rejects with `sync.idle_timeout` and
+   * aborts a socket round in flight; the round budget does not bound elapsed
+   * time, and a transport that never answers must not hang the caller.
    */
-  async syncUntilIdle(maxRounds?: number): Promise<SyncIdleResult> {
+  async syncUntilIdle(
+    options?: number | SyncIdleOptions,
+  ): Promise<SyncIdleResult> {
+    const maxRounds =
+      typeof options === 'number' ? options : options?.maxRounds;
+    const timeoutMs =
+      typeof options === 'number'
+        ? SYNC_IDLE_TIMEOUT_MS
+        : (options?.timeoutMs ?? SYNC_IDLE_TIMEOUT_MS);
     // §7.7: an explicit budget is a strict positive round count. Zero,
     // fractional, and out-of-range values are caller errors.
     if (
@@ -4316,18 +4358,24 @@ export class SyncClient {
       (!Number.isInteger(maxRounds) || maxRounds < 1 || maxRounds > 0xffffffff)
     )
       throw invalidRequest('maxRounds must be a positive integer');
-    const pending = this.#syncIdlePending.get(maxRounds);
+    if (
+      timeoutMs !== Number.POSITIVE_INFINITY &&
+      !(Number.isFinite(timeoutMs) && timeoutMs > 0)
+    )
+      throw invalidRequest('timeoutMs must be a positive number or Infinity');
+    const key = `${maxRounds ?? 'default'}:${timeoutMs}`;
+    const pending = this.#syncIdlePending.get(key);
     if (pending !== undefined) return pending;
     const previous = this.#syncIdleTail;
     let drive: Promise<SyncIdleResult>;
     if (previous === undefined) {
-      drive = this.#syncIdleRounds(maxRounds);
+      drive = this.#syncIdleRounds(maxRounds, timeoutMs);
     } else {
       drive = previous.then(() => {
-        this.#syncIdlePending.delete(maxRounds);
-        return this.#syncIdleRounds(maxRounds);
+        this.#syncIdlePending.delete(key);
+        return this.#syncIdleRounds(maxRounds, timeoutMs);
       });
-      this.#syncIdlePending.set(maxRounds, drive);
+      this.#syncIdlePending.set(key, drive);
     }
     const tail = drive.then(
       () => undefined,
@@ -4343,6 +4391,7 @@ export class SyncClient {
   /** The rounds loop of one idle drive; `syncUntilIdle` owns coalescing. */
   async #syncIdleRounds(
     maxRounds: number | undefined,
+    timeoutMs: number,
   ): Promise<SyncIdleResult> {
     const budget = maxRounds ?? 20;
     const aggregate = {
@@ -4380,54 +4429,96 @@ export class SyncClient {
         : {}),
       budgetExhausted,
     });
-    for (let round = 0; round < budget; round++) {
-      const before = JSON.stringify(
-        loadSubscriptions(this.#db).map((sub) => [sub.id, sub.bootstrapState]),
-      );
-      const last = await this.sync();
-      // Historical counters accumulate; current readiness (`bootstrapping`,
-      // `deferredCommits`, `schemaFloor`) describes the latest round.
-      aggregate.pushed += last.pushed;
-      aggregate.applied.push(...last.applied);
-      aggregate.rejected.push(...last.rejected);
-      aggregate.retryable.push(...last.retryable);
-      aggregate.conflicts.push(...last.conflicts);
-      aggregate.commitsApplied += last.commitsApplied;
-      aggregate.segmentRowsApplied += last.segmentRowsApplied;
-      aggregate.bootstrapping = [...last.bootstrapping];
-      aggregate.resets.push(...last.resets);
-      aggregate.revoked.push(...last.revoked);
-      aggregate.failed.push(...last.failed);
-      aggregate.deferredCommits = last.deferredCommits ?? 0;
-      aggregate.schemaFloor = last.schemaFloor;
-      // A disabled transport or a schema floor ends the loop, not the budget.
-      if (!this.#transportEnabled || last.schemaFloor !== undefined)
-        return result(false);
-      if (
-        maxRounds === undefined &&
-        last.segmentRowsApplied > 0 &&
-        last.bootstrapping.length > 0 &&
-        before !==
-          JSON.stringify(
-            loadSubscriptions(this.#db).map((sub) => [
-              sub.id,
-              sub.bootstrapState,
-            ]),
-          )
-      )
-        round = -1;
-      if (
-        last.commitsApplied === 0 &&
-        last.segmentRowsApplied === 0 &&
-        last.bootstrapping.length === 0 &&
-        last.resets.length === 0 &&
-        (last.deferredCommits ?? 0) === 0 &&
-        !this.#needsPull
-      ) {
-        return result(false);
+    let round = 0;
+    let expired = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const deadline =
+      timeoutMs === Number.POSITIVE_INFINITY
+        ? undefined
+        : new Promise<never>((_, reject) => {
+            timer = setTimeout(() => {
+              expired = true;
+              // The transport may never answer; release the round so the
+              // client can run another one after the caller sees the error.
+              this.#abortPendingRound('syncUntilIdle deadline exceeded');
+              reject(
+                new ClientSyncError(
+                  'sync.idle_timeout',
+                  'syncUntilIdle exceeded its deadline',
+                  true,
+                  { timeoutMs, rounds: round },
+                ),
+              );
+            }, timeoutMs);
+          });
+    const drive = (async (): Promise<SyncIdleResult> => {
+      for (; round < budget; round++) {
+        // The race already rejected; stop spending rounds on a dead drive.
+        if (expired)
+          throw new ClientSyncError(
+            'sync.idle_timeout',
+            'syncUntilIdle exceeded its deadline',
+            true,
+            { timeoutMs, rounds: round },
+          );
+        const before = JSON.stringify(
+          loadSubscriptions(this.#db).map((sub) => [
+            sub.id,
+            sub.bootstrapState,
+          ]),
+        );
+        const last = await this.sync();
+        // Historical counters accumulate; current readiness (`bootstrapping`,
+        // `deferredCommits`, `schemaFloor`) describes the latest round.
+        aggregate.pushed += last.pushed;
+        aggregate.applied.push(...last.applied);
+        aggregate.rejected.push(...last.rejected);
+        aggregate.retryable.push(...last.retryable);
+        aggregate.conflicts.push(...last.conflicts);
+        aggregate.commitsApplied += last.commitsApplied;
+        aggregate.segmentRowsApplied += last.segmentRowsApplied;
+        aggregate.bootstrapping = [...last.bootstrapping];
+        aggregate.resets.push(...last.resets);
+        aggregate.revoked.push(...last.revoked);
+        aggregate.failed.push(...last.failed);
+        aggregate.deferredCommits = last.deferredCommits ?? 0;
+        aggregate.schemaFloor = last.schemaFloor;
+        // A disabled transport or a schema floor ends the loop, not the budget.
+        if (!this.#transportEnabled || last.schemaFloor !== undefined)
+          return result(false);
+        if (
+          maxRounds === undefined &&
+          last.segmentRowsApplied > 0 &&
+          last.bootstrapping.length > 0 &&
+          before !==
+            JSON.stringify(
+              loadSubscriptions(this.#db).map((sub) => [
+                sub.id,
+                sub.bootstrapState,
+              ]),
+            )
+        )
+          round = -1;
+        if (
+          last.commitsApplied === 0 &&
+          last.segmentRowsApplied === 0 &&
+          last.bootstrapping.length === 0 &&
+          last.resets.length === 0 &&
+          (last.deferredCommits ?? 0) === 0 &&
+          !this.#needsPull
+        ) {
+          return result(false);
+        }
       }
+      return result(true);
+    })();
+    try {
+      return await (deadline === undefined
+        ? drive
+        : Promise.race([drive, deadline]));
+    } finally {
+      clearTimeout(timer);
     }
-    return result(true);
   }
 
   /**

package/src/worker-entry.ts

@@ -488,9 +488,9 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
       const running = requireClient();
       return serializedSync(() => running.sync());
     },
-    syncUntilIdle: (maxRounds) => {
+    syncUntilIdle: (options) => {
       const running = requireClient();
-      return serializedSync(() => running.syncUntilIdle(maxRounds));
+      return serializedSync(() => running.syncUntilIdle(options));
     },
     resetClientId: () => requireClient().resetClientId(),
     localRevision: () => requireClient().localRevision,

package/src/worker-host.ts

@@ -43,6 +43,7 @@ import type {
   SyncClientConfig,
   SyncClientLimits,
   SyncSummary,
+  SyncIdleOptions,
   SyncIdleResult,
   WindowState,
 } from './client';
@@ -657,8 +658,8 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
     return this.#call('sync', []);
   }
 
-  syncUntilIdle(maxRounds?: number): Promise<SyncIdleResult> {
-    return this.#call('syncUntilIdle', [maxRounds]);
+  syncUntilIdle(options?: number | SyncIdleOptions): Promise<SyncIdleResult> {
+    return this.#call('syncUntilIdle', [options]);
   }
 
   /**

package/src/worker-protocol.ts

@@ -31,6 +31,7 @@ import type {
   SyncClientConfig,
   SyncClientLimits,
   SyncSummary,
+  SyncIdleOptions,
   SyncIdleResult,
   WindowState,
 } from './client';
@@ -187,7 +188,7 @@ export interface WorkerApi extends Omit<
   /** RFC 0005 D9: the executable rollback step — drop the container. */
   previousVersionDiscard(): { present: boolean; discarded: boolean };
   sync(): Promise<SyncSummary>;
-  syncUntilIdle(maxRounds?: number): Promise<SyncIdleResult>;
+  syncUntilIdle(options?: number | SyncIdleOptions): Promise<SyncIdleResult>;
   resetClientId(): string;
   query(sql: string, params?: readonly SqlValue[]): SqlRow[];
   authoritySnapshot(): import('./authority').AuthoritySnapshot;