@syncular/client 0.30.15 → 0.31.0

package/src/outcomes.ts

@@ -9,11 +9,16 @@ import { RETAINED_ROWS } from './failed-overlay';
  * restart can never turn "rejected" into an inferred success. Conflict payloads
  * deliberately stay local; retention never deletes an unresolved failure.
  */
-import type { RejectionDetails, RowValue } from '@syncular/core';
+import {
+  normalizeRejectionDetails,
+  type RejectionDetails,
+  type RowValue,
+} from '@syncular/core';
 import type { ClientDatabase } from './database';
 import { ClientSyncError } from './errors';
 import type { OutboxOperation } from './outbox';
 import {
+  isBytesEnvelope,
   mapRowValues,
   type JsonRowValue,
   jsonToRowValue,
@@ -155,61 +160,168 @@ function encodeResults(results: readonly CommitOperationOutcome[]): string {
   return JSON.stringify(stored);
 }
 
+/** A JSON object that is neither null nor an array. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isStoredRow(value: unknown): value is Record<string, JsonRowValue> {
+  return (
+    isRecord(value) &&
+    Object.values(value).every(
+      (cell) =>
+        cell === null ||
+        typeof cell === 'string' ||
+        typeof cell === 'boolean' ||
+        (typeof cell === 'number' && Number.isFinite(cell)) ||
+        isBytesEnvelope(cell),
+    )
+  );
+}
+
+export function isStoredOperation(value: unknown): value is OutboxOperation {
+  return (
+    isRecord(value) &&
+    typeof value.table === 'string' &&
+    typeof value.rowId === 'string' &&
+    (value.baseVersion === undefined ||
+      Number.isSafeInteger(value.baseVersion)) &&
+    ((value.op === 'upsert' && isStoredRow(value.values)) ||
+      (value.op === 'delete' && value.values === undefined))
+  );
+}
+
 function decodeResults(raw: string): CommitOperationOutcome[] {
+  function corrupt(): never {
+    throw new ClientSyncError(
+      'sync.local_corrupt',
+      'persisted commit outcome is invalid',
+    );
+  }
   const stored = JSON.parse(raw) as StoredCommitOperationOutcome[];
+  if (!Array.isArray(stored)) corrupt();
   return stored.map((result) => {
-    if (result.status !== 'conflict') return result;
-    return {
-      status: 'conflict',
-      conflict: {
-        ...result.conflict,
-        // Pre-column-version journal entries carry no conflictColumns.
-        conflictColumns: result.conflict.conflictColumns ?? [],
-        serverRow: mapRowValues(result.conflict.serverRow, jsonToRowValue),
-      },
-    };
+    if (!isRecord(result)) corrupt();
+    if (result.status === 'applied') {
+      if (
+        !Number.isInteger(result.opIndex) ||
+        result.opIndex < -2147483648 ||
+        result.opIndex > 2147483647
+      )
+        corrupt();
+      return result;
+    }
+    if (result.status === 'conflict') {
+      const conflict = result.conflict;
+      if (
+        !isRecord(conflict) ||
+        !isStoredRow(conflict.serverRow) ||
+        typeof conflict.clientCommitId !== 'string' ||
+        !Number.isInteger(conflict.opIndex) ||
+        conflict.opIndex < -2147483648 ||
+        conflict.opIndex > 2147483647 ||
+        typeof conflict.table !== 'string' ||
+        typeof conflict.rowId !== 'string' ||
+        typeof conflict.code !== 'string' ||
+        typeof conflict.message !== 'string' ||
+        (conflict.operation !== undefined &&
+          !isStoredOperation(conflict.operation)) ||
+        !Number.isSafeInteger(conflict.serverVersion) ||
+        (conflict.conflictColumns !== undefined &&
+          (!Array.isArray(conflict.conflictColumns) ||
+            !conflict.conflictColumns.every(
+              (column) => typeof column === 'string',
+            )))
+      ) {
+        corrupt();
+      }
+      return {
+        status: 'conflict',
+        conflict: {
+          ...conflict,
+          // Pre-column-version journal entries carry no conflictColumns.
+          conflictColumns: conflict.conflictColumns ?? [],
+          serverRow: mapRowValues(conflict.serverRow, jsonToRowValue),
+        },
+      };
+    }
+    if (result.status === 'error') {
+      const rejection = result.rejection;
+      if (
+        !isRecord(rejection) ||
+        typeof rejection.clientCommitId !== 'string' ||
+        !Number.isInteger(rejection.opIndex) ||
+        rejection.opIndex < -2147483648 ||
+        rejection.opIndex > 2147483647 ||
+        typeof rejection.code !== 'string' ||
+        typeof rejection.message !== 'string' ||
+        typeof rejection.retryable !== 'boolean' ||
+        (rejection.operation !== undefined &&
+          !isStoredOperation(rejection.operation))
+      ) {
+        corrupt();
+      }
+      try {
+        const { details, ...fields } = rejection;
+        return {
+          status: 'error',
+          rejection: {
+            ...fields,
+            ...(details == null
+              ? {}
+              : { details: normalizeRejectionDetails(details) }),
+          },
+        };
+      } catch {
+        corrupt();
+      }
+    }
+    corrupt();
   });
 }
 
 function parseOutcome(
   db: ClientDatabase,
   row: Readonly<Record<string, unknown>>,
+  attachRetainedRows = true,
 ): CommitOutcome {
-  const retainedRows: RetainedCommitRow[] = db
-    .query(
-      `SELECT tbl,id,intent,base,version,unique_conflicts FROM ${RETAINED_ROWS} WHERE commit_seq IS NULL AND commit_id=? ORDER BY idx`,
-      [row.client_commit_id as string],
-    )
-    .map((retained) => {
-      const decode = (value: unknown): Record<string, RowValue> | null =>
-        value === null
-          ? null
-          : Object.fromEntries(
-              Object.entries(
-                JSON.parse(String(value)) as Record<string, JsonRowValue>,
-              ).map(([key, value]) => [key, jsonToRowValue(value)]),
-            );
-      return {
-        table: retained.tbl as string,
-        rowId: retained.id as string,
-        localRow: decode(retained.intent),
-        ...(retained.unique_conflicts === null
-          ? {}
-          : {
-              uniqueConflicts: (
-                JSON.parse(retained.unique_conflicts as string) as NonNullable<
-                  RetainedCommitRow['uniqueConflicts']
-                >
-              ).map((conflict) => ({
-                ...conflict,
-                serverRow: decode(JSON.stringify(conflict.serverRow))!,
-              })),
-            }),
-        serverRow: decode(retained.base),
-        serverVersion:
-          retained.version === null ? null : (retained.version as number),
-      };
-    });
+  const retainedRows: RetainedCommitRow[] = attachRetainedRows
+    ? db
+        .query(
+          `SELECT tbl,id,intent,base,version,unique_conflicts FROM ${RETAINED_ROWS} WHERE commit_seq IS NULL AND commit_id=? ORDER BY idx`,
+          [row.client_commit_id as string],
+        )
+        .map((retained) => {
+          const decode = (value: unknown): Record<string, RowValue> | null =>
+            value === null
+              ? null
+              : Object.fromEntries(
+                  Object.entries(
+                    JSON.parse(String(value)) as Record<string, JsonRowValue>,
+                  ).map(([key, value]) => [key, jsonToRowValue(value)]),
+                );
+          return {
+            table: retained.tbl as string,
+            rowId: retained.id as string,
+            localRow: decode(retained.intent),
+            ...(retained.unique_conflicts === null
+              ? {}
+              : {
+                  uniqueConflicts: (
+                    JSON.parse(
+                      retained.unique_conflicts as string,
+                    ) as NonNullable<RetainedCommitRow['uniqueConflicts']>
+                  ).map((conflict) => ({
+                    ...conflict,
+                    serverRow: decode(JSON.stringify(conflict.serverRow))!,
+                  })),
+                }),
+            serverRow: decode(retained.base),
+            serverVersion:
+              retained.version === null ? null : (retained.version as number),
+          };
+        })
+    : [];
   return {
     sequence: row.seq as number,
     clientCommitId: row.client_commit_id as string,
@@ -259,6 +371,78 @@ export function commitOutcome(
   return row === undefined ? undefined : parseOutcome(db, row);
 }
 
+/**
+ * §7.5 persisted-journal view: the stored outcome WITHOUT the owner-derived
+ * `retainedRows` images. A malformed journal row (invalid status, resolution,
+ * results, or operations JSON) raises the same static `sync.local_corrupt` the
+ * native sidecar reports, never a raw `SyntaxError`.
+ */
+export function persistedCommitOutcome(
+  db: ClientDatabase,
+  clientCommitId: string,
+): CommitOutcome | undefined {
+  const row = db.query(`${SELECT_OUTCOME} WHERE client_commit_id=?`, [
+    clientCommitId,
+  ])[0];
+  if (row === undefined) return undefined;
+  function corrupt(): never {
+    throw new ClientSyncError(
+      'sync.local_corrupt',
+      'persisted commit outcome is invalid',
+    );
+  }
+  const status = row.status;
+  const resolution = row.resolution;
+  if (
+    (status !== 'applied' &&
+      status !== 'cached' &&
+      status !== 'conflict' &&
+      status !== 'rejected') ||
+    (resolution !== 'active' &&
+      resolution !== 'resolved_keep_server' &&
+      resolution !== 'superseded' &&
+      resolution !== 'dismissed') ||
+    !Number.isSafeInteger(row.seq) ||
+    typeof row.client_commit_id !== 'string' ||
+    !Number.isSafeInteger(row.recorded_at_ms) ||
+    typeof row.results !== 'string' ||
+    (row.operations !== null && typeof row.operations !== 'string') ||
+    (row.resolved_at_ms !== null &&
+      !Number.isSafeInteger(row.resolved_at_ms)) ||
+    (row.replacement_client_commit_id !== null &&
+      typeof row.replacement_client_commit_id !== 'string')
+  ) {
+    corrupt();
+  }
+  try {
+    const outcome = parseOutcome(db, row, false);
+    const hasConflict = outcome.results.some(
+      (result) => result.status === 'conflict',
+    );
+    const hasError = outcome.results.some(
+      (result) => result.status === 'error',
+    );
+    const redacted =
+      outcome.results.length === 0 && outcome.operations === undefined;
+    if (
+      ((status === 'applied' || status === 'cached') &&
+        (hasConflict || hasError)) ||
+      (status === 'conflict' && !(hasConflict || redacted)) ||
+      (status === 'rejected' && (hasConflict || !(hasError || redacted)))
+    )
+      corrupt();
+    if (
+      outcome.operations !== undefined &&
+      (!Array.isArray(outcome.operations) ||
+        !outcome.operations.every(isStoredOperation))
+    )
+      corrupt();
+    return outcome;
+  } catch {
+    corrupt();
+  }
+}
+
 export function listCommitOutcomes(
   db: ClientDatabase,
   query: CommitOutcomeQuery = {},

package/src/schema.ts

@@ -105,6 +105,19 @@ function invalidSchema(message: string): never {
 export function compileClientSchema(
   schema: ClientSchema,
 ): CompiledClientSchema {
+  // §7.4.2: the persisted marker is a canonical positive i32 and a replica
+  // refuses any requested version outside that range before it touches
+  // storage, so a client can never persist a marker it would reject on the
+  // next open.
+  if (
+    !Number.isInteger(schema.version) ||
+    schema.version < 1 ||
+    schema.version > 2147483647
+  ) {
+    throw invalidRequest(
+      'generated schema version must be an integer in 1..=2147483647',
+    );
+  }
   const tables = new Map<string, CompiledClientTable>();
   const schemaObjectNames = new Set<string>();
   for (const table of schema.tables) {
@@ -726,7 +739,13 @@ export function coerceSqlRepresentation(
   switch (localColumnType(column)) {
     case 'boolean':
       return value === 0 ? false : value === 1 ? true : value;
-    case 'integer':
+    case 'integer': {
+      const integer = typeof value === 'bigint' ? Number(value) : value;
+      if (typeof integer === 'number' && !Number.isSafeInteger(integer)) {
+        throw invalidRequest('integer value is outside the safe-integer range');
+      }
+      return integer;
+    }
     case 'float':
       return typeof value === 'bigint' ? Number(value) : value;
     default:
@@ -775,6 +794,24 @@ function bytesToHex(bytes: Uint8Array): string {
   return out;
 }
 
+/**
+ * The canonical §7.1 byte envelope: exactly one `$bytes` key holding a string
+ * of hexadecimal digit pairs. Uppercase digits are accepted; encoders emit
+ * lowercase. A malformed envelope is a caller error, never a value to coerce.
+ */
+export function isBytesEnvelope(
+  value: unknown,
+): value is { readonly $bytes: string } {
+  if (typeof value !== 'object' || value === null || Array.isArray(value))
+    return false;
+  const record = value as Record<string, unknown>;
+  return (
+    Object.keys(record).length === 1 &&
+    typeof record.$bytes === 'string' &&
+    /^(?:[0-9a-fA-F]{2})*$/.test(record.$bytes)
+  );
+}
+
 export function hexToBytes(hex: string): Uint8Array {
   const out = new Uint8Array(hex.length / 2);
   for (let i = 0; i < out.length; i++) {
@@ -790,6 +827,10 @@ export function rowValueToJson(value: RowValue): JsonRowValue {
 
 export function jsonToRowValue(value: JsonRowValue): RowValue {
   if (typeof value === 'object' && value !== null) {
+    if (!isBytesEnvelope(value))
+      throw invalidRequest(
+        'an object value must be one $bytes key holding an even-length hexadecimal string',
+      );
     return hexToBytes(value.$bytes);
   }
   return value;

package/src/state.ts

@@ -9,6 +9,7 @@ export const SUBSCRIPTIONS_TABLE = '_syncular_subscriptions';
  * exactly for that purpose.
  */
 import type { ScopeMap } from '@syncular/core';
+import { ClientSyncError } from './errors';
 import type { CompiledClientSchema } from './schema';
 import type { ClientDatabase } from './database';
 import type { LocalRevision } from './invalidation';
@@ -225,12 +226,18 @@ export function setMeta(db: ClientDatabase, key: string, value: string): void {
 export function getLocalRevision(db: ClientDatabase): LocalRevision {
   const raw = getMeta(db, LOCAL_REVISION_KEY);
   if (raw === undefined) return 0n;
-  if (!/^(0|[1-9][0-9]*)$/.test(raw)) {
-    throw new Error(`invalid persisted local revision ${JSON.stringify(raw)}`);
+  if (typeof raw !== 'string' || !/^(0|[1-9][0-9]*)$/.test(raw)) {
+    throw new ClientSyncError(
+      'sync.local_corrupt',
+      'persisted local revision is invalid',
+    );
   }
   const revision = BigInt(raw);
   if (revision > MAX_U64) {
-    throw new Error(`persisted local revision exceeds u64: ${raw}`);
+    throw new ClientSyncError(
+      'sync.local_corrupt',
+      'persisted local revision is invalid',
+    );
   }
   return revision;
 }
@@ -242,7 +249,10 @@ export function getLocalRevision(db: ClientDatabase): LocalRevision {
 export function bumpLocalRevision(db: ClientDatabase): LocalRevision {
   const current = getLocalRevision(db);
   if (current === MAX_U64) {
-    throw new Error('local revision exhausted u64');
+    throw new ClientSyncError(
+      'sync.local_corrupt',
+      'local revision exhausted u64',
+    );
   }
   const next = current + 1n;
   setMeta(db, LOCAL_REVISION_KEY, next.toString());

package/src/sync-scheduler.ts

@@ -87,6 +87,16 @@ export function installSyncScheduler(
     backgroundReady = false;
     void client
       .syncUntilIdle(options.maxRounds)
+      .then((result) => {
+        if (
+          result !== null &&
+          typeof result === 'object' &&
+          'budgetExhausted' in result &&
+          result.budgetExhausted === true
+        ) {
+          queueImmediate();
+        }
+      })
       .catch((error: unknown) => {
         if (!stopped) report(error);
       })

package/src/worker-entry.ts

@@ -13,7 +13,7 @@
  * RPC-driven and auto-driven sync rounds serialize on one queue because
  * the core owns exactly one loop.
  */
-import { defineAuthorityReads } from './authority';
+import type { defineAuthorityReads } from './authority';
 import { SyncClient } from './client';
 import type { ClientDatabase } from './database';
 import {
@@ -52,6 +52,8 @@ import {
 } from './worker-protocol';
 
 export interface SyncWorkerOverrides {
+  /** Explicit authority reader factory. Required when init declares authorityReads. */
+  readonly createAuthorityReads?: typeof defineAuthorityReads;
   /** Database factory indirection: tests inject bun:sqlite here. */
   readonly openDatabase?: (
     config: WorkerInitConfig,
@@ -175,6 +177,7 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
     void serializedSync(() => running.syncUntilIdle())
       .then((summary) => {
         if (!closed) post({ t: 'event', event: { kind: 'synced', summary } });
+        if (summary.budgetExhausted) consumeSyncIntent({ kind: 'interactive' });
       })
       .catch((error: unknown) => {
         if (!closed) {
@@ -239,6 +242,11 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
   }
 
   async function init(config: WorkerInitConfig): Promise<WorkerInitResult> {
+    if (config.authorityReads !== undefined && !overrides.createAuthorityReads)
+      throw new ClientSyncError(
+        'client.authority_read_forbidden',
+        'authorityReads requires startSyncWorker({ createAuthorityReads })',
+      );
     if (client !== undefined) {
       throw new ClientSyncError(
         WORKER_FAILED_CODE,
@@ -325,7 +333,11 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
         ? { encryption: encryptionConfigFromKeyring(config.encryption) }
         : {}),
       ...(config.authorityReads !== undefined
-        ? { authorityReads: defineAuthorityReads(config.authorityReads) }
+        ? {
+            authorityReads: overrides.createAuthorityReads!(
+              config.authorityReads,
+            ),
+          }
         : {}),
       ...(config.securityPreflight !== undefined
         ? { securityPreflight: config.securityPreflight }
@@ -393,8 +405,47 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
     return { clientId: started.clientId };
   }
 
+  // Forward every argument to core methods, including authority's zero-argument check.
+  const coreMethods = [
+    'securityLifecycle',
+    'subscribe',
+    'unsubscribe',
+    'windowState',
+    'purgeLocalData',
+    'rebootstrapLocalData',
+    'previousVersionSnapshot',
+    'previousVersionAudit',
+    'previousVersionDiscard',
+    'query',
+    'authoritySnapshot',
+    'querySnapshot',
+    'snapshotRead',
+    'statusSnapshot',
+    'conflicts',
+    'rejections',
+    'commitOutcome',
+    'commitOutcomes',
+    'resolveCommitOutcome',
+    'pendingCommits',
+    'subscriptions',
+    'subscription',
+    'connectRealtime',
+    'disconnectRealtime',
+    'setPresence',
+    'presence',
+    'uploadBlob',
+    'fetchBlob',
+  ] as const satisfies readonly (keyof WorkerApi & keyof SyncClient)[];
   const api: WorkerApi = {
-    securityLifecycle: () => requireClient().securityLifecycle(),
+    ...(Object.fromEntries(
+      coreMethods.map((method) => [
+        method,
+        (...args: unknown[]) => {
+          const running = requireClient();
+          return Reflect.apply(running[method], running, args);
+        },
+      ]),
+    ) as Pick<WorkerApi, (typeof coreMethods)[number]>),
     beginSecurityPreflight: async () => {
       if (backgroundTimer !== undefined) clearTimeout(backgroundTimer);
       backgroundTimer = undefined;
@@ -409,12 +460,9 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
           : {}),
       });
     },
-    subscribe: (input) => requireClient().subscribe(input),
-    unsubscribe: (id) => requireClient().unsubscribe(id),
     setWindow: async (base, units) => {
       await requireClient().setWindowCommand(base, units);
     },
-    windowState: (base) => requireClient().windowState(base),
     mutate: (mutations) => {
       return requireClient().mutateCommand(mutations).value;
     },
@@ -429,13 +477,6 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
       );
       return result.value;
     },
-    purgeLocalData: (input) => requireClient().purgeLocalData(input),
-    rebootstrapLocalData: (input) =>
-      requireClient().rebootstrapLocalData(input),
-    previousVersionSnapshot: (spec) =>
-      requireClient().previousVersionSnapshot(spec),
-    previousVersionAudit: () => requireClient().previousVersionAudit(),
-    previousVersionDiscard: () => requireClient().previousVersionDiscard(),
     sync: () => {
       const running = requireClient();
       return serializedSync(() => running.sync());
@@ -444,11 +485,7 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
       const running = requireClient();
       return serializedSync(() => running.syncUntilIdle(maxRounds));
     },
-    query: (sql, params) => requireClient().query(sql, params),
-    authoritySnapshot: () => requireClient().authoritySnapshot(),
-    querySnapshot: (spec) => requireClient().querySnapshot(spec),
     localRevision: () => requireClient().localRevision,
-    statusSnapshot: () => requireClient().statusSnapshot(),
     diagnosticsSnapshot: (request) => {
       const snapshot = requireClient().diagnosticsSnapshot(request);
       return withClientDiagnosticsHost(snapshot, {
@@ -458,22 +495,6 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
         realtime: snapshot.host.realtime,
       });
     },
-    conflicts: () => requireClient().conflicts(),
-    rejections: () => requireClient().rejections(),
-    commitOutcome: (clientCommitId) =>
-      requireClient().commitOutcome(clientCommitId),
-    commitOutcomes: (query) => requireClient().commitOutcomes(query),
-    resolveCommitOutcome: (input) =>
-      requireClient().resolveCommitOutcome(input),
-    pendingCommits: () => requireClient().pendingCommits(),
-    subscriptions: () => requireClient().subscriptions(),
-    subscription: (id) => requireClient().subscription(id),
-    connectRealtime: () => requireClient().connectRealtime(),
-    disconnectRealtime: () => requireClient().disconnectRealtime(),
-    setPresence: (scopeKey, doc) => requireClient().setPresence(scopeKey, doc),
-    presence: (scopeKey) => requireClient().presence(scopeKey),
-    uploadBlob: (bytes, options) => requireClient().uploadBlob(bytes, options),
-    fetchBlob: (blobIdOrRef) => requireClient().fetchBlob(blobIdOrRef),
     setHeaders: (next) => {
       headers = next;
     },
@@ -525,11 +546,6 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
   ]);
 
   async function dispatch(message: WorkerCallMessage): Promise<unknown> {
-    if (message.method === 'authoritySnapshot' && message.args.length)
-      throw new ClientSyncError(
-        'client.authority_read_forbidden',
-        'authoritySnapshot accepts no arguments',
-      );
     const method = api[message.method] as (...args: unknown[]) => unknown;
     const invoke = () => method.apply(api, message.args as unknown[]);
     if (syncChainMethods.has(message.method)) {

package/src/worker-host.ts

@@ -37,10 +37,13 @@ import type {
   QuerySnapshot,
   RejectionRecord,
   SecurityLifecycle,
+  SnapshotRead,
+  SnapshotReadRequest,
   SubscribeInput,
   SyncClientConfig,
   SyncClientLimits,
   SyncSummary,
+  SyncIdleResult,
   WindowState,
 } from './client';
 import type { SqlRow, SqlValue } from './database';
@@ -650,7 +653,7 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
     return this.#call('sync', []);
   }
 
-  syncUntilIdle(maxRounds?: number): Promise<SyncSummary> {
+  syncUntilIdle(maxRounds?: number): Promise<SyncIdleResult> {
     return this.#call('syncUntilIdle', [maxRounds]);
   }
 
@@ -673,6 +676,12 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
     return this.#call('querySnapshot', [spec]) as Promise<QuerySnapshot<Row>>;
   }
 
+  snapshotRead<Row = SqlRow>(
+    spec: SnapshotReadRequest,
+  ): Promise<SnapshotRead<Row>> {
+    return this.#call('snapshotRead', [spec]) as Promise<SnapshotRead<Row>>;
+  }
+
   localRevision(): Promise<LocalRevision> {
     return this.#call('localRevision', []);
   }

package/src/worker-protocol.ts

@@ -31,6 +31,7 @@ import type {
   SyncClientConfig,
   SyncClientLimits,
   SyncSummary,
+  SyncIdleResult,
   WindowState,
 } from './client';
 import type { SqlRow, SqlValue } from './database';
@@ -185,7 +186,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<SyncSummary>;
+  syncUntilIdle(maxRounds?: number): Promise<SyncIdleResult>;
   query(sql: string, params?: readonly SqlValue[]): SqlRow[];
   authoritySnapshot(): import('./authority').AuthoritySnapshot;
   querySnapshot(spec: QueryReadSpec): QuerySnapshot;