@syncular/client 0.0.6-219 → 0.0.6-223

package/src/pull-engine.ts

@@ -11,15 +11,17 @@ import {
   type SyncBootstrapApplyMode,
   type SyncBootstrapState,
   type SyncChange,
+  type SyncCombinedResponse,
   type SyncPullRequest,
   type SyncPullResponse,
   type SyncPullSubscriptionResponse,
   type SyncSnapshot,
-  type SyncSubscriptionRequest,
   type SyncTransport,
   type SyncTransportCapabilities,
 } from '@syncular/core';
 import { type Kysely, sql, type Transaction } from 'kysely';
+import type { SyncClientSubscription, SyncTraceEvent } from './engine/types';
+import { SyncClientStageError, wrapSyncClientStageError } from './errors';
 import {
   type ClientHandlerCollection,
   getClientHandlerOrThrow,
@@ -93,7 +95,13 @@ function toOwnedUint8Array(chunk: Uint8Array): Uint8Array<ArrayBuffer> {
 }
 
 async function maybeGunzipStream(
-  stream: ReadableStream<Uint8Array>
+  stream: ReadableStream<Uint8Array>,
+  context?: {
+    stateId?: string;
+    subscriptionId?: string;
+    table?: string;
+    chunkId?: string;
+  }
 ): Promise<ReadableStream<Uint8Array>> {
   const reader = stream.getReader();
   const prefetched: Uint8Array[] = [];
@@ -139,7 +147,20 @@ async function maybeGunzipStream(
   }
 
   const compressedBytes = await readAllBytesFromCoreStream(replayStream);
-  return bytesToReadableStream(await gunzipBytes(compressedBytes));
+  try {
+    return bytesToReadableStream(await gunzipBytes(compressedBytes));
+  } catch (error) {
+    throw wrapSyncClientStageError(
+      error,
+      {
+        stage: 'snapshot-gzip-decode',
+        ...context,
+      },
+      `Failed to gunzip snapshot chunk${
+        context?.chunkId ? ` "${context.chunkId}"` : ''
+      }`
+    );
+  }
 }
 
 async function* decodeSnapshotRowStreamBatches(
@@ -280,13 +301,30 @@ async function fetchSnapshotChunkStream(
   request: {
     chunkId: string;
     scopeValues?: ScopeValues;
+  },
+  context?: {
+    stateId?: string;
+    subscriptionId?: string;
+    table?: string;
   }
 ): Promise<ReadableStream<Uint8Array>> {
-  if (transport.fetchSnapshotChunkStream) {
-    return transport.fetchSnapshotChunkStream(request);
+  try {
+    if (transport.fetchSnapshotChunkStream) {
+      return await transport.fetchSnapshotChunkStream(request);
+    }
+    const bytes = await transport.fetchSnapshotChunk(request);
+    return bytesToReadableStream(bytes);
+  } catch (error) {
+    throw wrapSyncClientStageError(
+      error,
+      {
+        stage: 'snapshot-chunk-fetch',
+        chunkId: request.chunkId,
+        ...context,
+      },
+      `Failed to fetch snapshot chunk "${request.chunkId}"`
+    );
   }
-  const bytes = await transport.fetchSnapshotChunk(request);
-  return bytesToReadableStream(bytes);
 }
 
 async function readAllBytesFromStream(
@@ -332,80 +370,212 @@ async function materializeSnapshotChunkRows(
     scopeValues?: ScopeValues;
   },
   expectedHash: string | undefined,
-  sha256Override?: (bytes: Uint8Array) => Promise<string>
+  sha256Override?: (bytes: Uint8Array) => Promise<string>,
+  trace?: {
+    stateId: string;
+    subscriptionId: string;
+    table: string;
+    chunkIndex: number;
+    onTrace?: SyncPullOnceOptions['onTrace'];
+  }
 ): Promise<unknown[]> {
+  emitTrace(trace?.onTrace, {
+    stage: 'apply:chunk-materialize:start',
+    stateId: trace?.stateId,
+    subscriptionId: trace?.subscriptionId,
+    table: trace?.table,
+    chunkId: request.chunkId,
+    chunkIndex: trace?.chunkIndex,
+  });
+  const startedAt = Date.now();
+
   if (
     transport.capabilities?.snapshotChunkReadMode === 'bytes' &&
     transport.fetchSnapshotChunk
   ) {
-    let bytes = await transport.fetchSnapshotChunk(request);
-    if (isGzipBytes(bytes)) {
-      bytes = await gunzipBytes(bytes);
-    }
-    if (expectedHash) {
-      const actualHash = await computeSha256Hex(bytes, sha256Override);
-      if (actualHash !== expectedHash) {
-        throw new Error(
-          `Snapshot chunk integrity check failed: expected sha256 ${expectedHash}, got ${actualHash}`
+    try {
+      let bytes = await transport.fetchSnapshotChunk(request);
+      if (isGzipBytes(bytes)) {
+        try {
+          bytes = await gunzipBytes(bytes);
+        } catch (error) {
+          throw wrapSyncClientStageError(
+            error,
+            {
+              stage: 'snapshot-gzip-decode',
+              stateId: trace?.stateId,
+              subscriptionId: trace?.subscriptionId,
+              table: trace?.table,
+              chunkId: request.chunkId,
+            },
+            `Failed to gunzip snapshot chunk "${request.chunkId}"`
+          );
+        }
+      }
+      if (expectedHash) {
+        const actualHash = await computeSha256Hex(bytes, sha256Override);
+        if (actualHash !== expectedHash) {
+          throw new SyncClientStageError(
+            `Snapshot chunk integrity check failed: expected sha256 ${expectedHash}, got ${actualHash}`,
+            {
+              stage: 'snapshot-integrity',
+              stateId: trace?.stateId,
+              subscriptionId: trace?.subscriptionId,
+              table: trace?.table,
+              chunkId: request.chunkId,
+            }
+          );
+        }
+      }
+      let rows: unknown[];
+      try {
+        rows = decodeSnapshotRows(bytes);
+      } catch (error) {
+        throw wrapSyncClientStageError(
+          error,
+          {
+            stage: 'snapshot-chunk-decode',
+            stateId: trace?.stateId,
+            subscriptionId: trace?.subscriptionId,
+            table: trace?.table,
+            chunkId: request.chunkId,
+          },
+          `Failed to decode snapshot chunk "${request.chunkId}"`
         );
       }
+      emitTrace(trace?.onTrace, {
+        stage: 'apply:chunk-materialize:complete',
+        stateId: trace?.stateId,
+        subscriptionId: trace?.subscriptionId,
+        table: trace?.table,
+        chunkId: request.chunkId,
+        chunkIndex: trace?.chunkIndex,
+        rowCount: rows.length,
+        durationMs: Math.max(0, Date.now() - startedAt),
+      });
+      return rows;
+    } catch (error) {
+      emitTrace(trace?.onTrace, {
+        stage: 'apply:chunk-materialize:error',
+        stateId: trace?.stateId,
+        subscriptionId: trace?.subscriptionId,
+        table: trace?.table,
+        chunkId: request.chunkId,
+        chunkIndex: trace?.chunkIndex,
+        durationMs: Math.max(0, Date.now() - startedAt),
+        errorMessage: error instanceof Error ? error.message : String(error),
+      });
+      throw error;
     }
-    return decodeSnapshotRows(bytes);
   }
 
-  const rawStream = await fetchSnapshotChunkStream(transport, request);
-  const decodedStream = await maybeGunzipStream(rawStream);
-  let streamForDecode = decodedStream;
-  let chunkHashPromise: Promise<string> | null = null;
-
-  if (expectedHash) {
-    const [hashStream, decodeStream] = decodedStream.tee();
-    streamForDecode = decodeStream;
-    chunkHashPromise = readAllBytesFromStream(hashStream).then((bytes) =>
-      computeSha256Hex(bytes, sha256Override)
-    );
-  }
-
-  const rows: unknown[] = [];
-  let materializeError: unknown = null;
-
   try {
-    for await (const batch of decodeSnapshotRowStreamBatches(
-      streamForDecode,
-      SNAPSHOT_APPLY_BATCH_ROWS
-    )) {
-      rows.push(...batch);
+    const rawStream = await fetchSnapshotChunkStream(transport, request, {
+      stateId: trace?.stateId,
+      subscriptionId: trace?.subscriptionId,
+      table: trace?.table,
+    });
+    const decodedStream = await maybeGunzipStream(rawStream, {
+      stateId: trace?.stateId,
+      subscriptionId: trace?.subscriptionId,
+      table: trace?.table,
+      chunkId: request.chunkId,
+    });
+    let streamForDecode = decodedStream;
+    let chunkHashPromise: Promise<string> | null = null;
+
+    if (expectedHash) {
+      const [hashStream, decodeStream] = decodedStream.tee();
+      streamForDecode = decodeStream;
+      chunkHashPromise = readAllBytesFromStream(hashStream).then((bytes) =>
+        computeSha256Hex(bytes, sha256Override)
+      );
     }
-  } catch (error) {
-    materializeError = error;
-  }
 
-  if (chunkHashPromise) {
+    const rows: unknown[] = [];
+    let materializeError: unknown = null;
+
     try {
-      const actualHash = await chunkHashPromise;
-      if (!materializeError && actualHash !== expectedHash) {
-        materializeError = new Error(
-          `Snapshot chunk integrity check failed: expected sha256 ${expectedHash}, got ${actualHash}`
-        );
+      for await (const batch of decodeSnapshotRowStreamBatches(
+        streamForDecode,
+        SNAPSHOT_APPLY_BATCH_ROWS
+      )) {
+        rows.push(...batch);
       }
-    } catch (hashError) {
-      if (!materializeError) {
-        materializeError = hashError;
+    } catch (error) {
+      materializeError = wrapSyncClientStageError(
+        error,
+        {
+          stage: 'snapshot-chunk-decode',
+          stateId: trace?.stateId,
+          subscriptionId: trace?.subscriptionId,
+          table: trace?.table,
+          chunkId: request.chunkId,
+        },
+        `Failed to decode snapshot chunk "${request.chunkId}"`
+      );
+    }
+
+    if (chunkHashPromise) {
+      try {
+        const actualHash = await chunkHashPromise;
+        if (!materializeError && actualHash !== expectedHash) {
+          materializeError = new SyncClientStageError(
+            `Snapshot chunk integrity check failed: expected sha256 ${expectedHash}, got ${actualHash}`,
+            {
+              stage: 'snapshot-integrity',
+              stateId: trace?.stateId,
+              subscriptionId: trace?.subscriptionId,
+              table: trace?.table,
+              chunkId: request.chunkId,
+            }
+          );
+        }
+      } catch (hashError) {
+        if (!materializeError) {
+          materializeError = hashError;
+        }
       }
     }
-  }
 
-  if (materializeError) {
-    throw materializeError;
-  }
+    if (materializeError) {
+      throw materializeError;
+    }
 
-  return rows;
+    emitTrace(trace?.onTrace, {
+      stage: 'apply:chunk-materialize:complete',
+      stateId: trace?.stateId,
+      subscriptionId: trace?.subscriptionId,
+      table: trace?.table,
+      chunkId: request.chunkId,
+      chunkIndex: trace?.chunkIndex,
+      rowCount: rows.length,
+      durationMs: Math.max(0, Date.now() - startedAt),
+    });
+    return rows;
+  } catch (error) {
+    emitTrace(trace?.onTrace, {
+      stage: 'apply:chunk-materialize:error',
+      stateId: trace?.stateId,
+      subscriptionId: trace?.subscriptionId,
+      table: trace?.table,
+      chunkId: request.chunkId,
+      chunkIndex: trace?.chunkIndex,
+      durationMs: Math.max(0, Date.now() - startedAt),
+      errorMessage: error instanceof Error ? error.message : String(error),
+    });
+    throw error;
+  }
 }
 
 async function materializeChunkedSnapshots(
   transport: SyncTransport,
   response: SyncPullResponse,
-  sha256Override?: (bytes: Uint8Array) => Promise<string>
+  sha256Override?: (bytes: Uint8Array) => Promise<string>,
+  trace?: {
+    stateId: string;
+    onTrace?: SyncPullOnceOptions['onTrace'];
+  }
 ): Promise<SyncPullResponse> {
   const subscriptions: SyncPullResponse['subscriptions'] = [];
 
@@ -424,7 +594,9 @@ async function materializeChunkedSnapshots(
       }
 
       const rows: unknown[] = [];
-      for (const chunk of chunks) {
+      for (let chunkIndex = 0; chunkIndex < chunks.length; chunkIndex += 1) {
+        const chunk = chunks[chunkIndex];
+        if (!chunk) continue;
         const chunkRows = await materializeSnapshotChunkRows(
           transport,
           {
@@ -432,7 +604,14 @@ async function materializeChunkedSnapshots(
             scopeValues: sub.scopes,
           },
           chunk.sha256,
-          sha256Override
+          sha256Override,
+          {
+            stateId: trace?.stateId ?? 'default',
+            subscriptionId: sub.id,
+            table: snapshot.table,
+            chunkIndex,
+            onTrace: trace?.onTrace,
+          }
         );
         rows.push(...chunkRows);
       }
@@ -459,7 +638,12 @@ async function applyChunkedSnapshot<DB extends SyncClientDb>(
   trx: Transaction<DB>,
   snapshot: SyncSnapshot,
   scopeValues: ScopeValues,
-  sha256Override?: (bytes: Uint8Array) => Promise<string>
+  sha256Override?: (bytes: Uint8Array) => Promise<string>,
+  trace?: {
+    stateId: string;
+    subscriptionId: string;
+    onTrace?: SyncPullOnceOptions['onTrace'];
+  }
 ): Promise<void> {
   const chunks = snapshot.chunks ?? [];
   if (chunks.length === 0) {
@@ -472,88 +656,185 @@ async function applyChunkedSnapshot<DB extends SyncClientDb>(
   for (let chunkIndex = 0; chunkIndex < chunks.length; chunkIndex += 1) {
     const chunk = chunks[chunkIndex];
     if (!chunk) continue;
-
-    const rawStream = await fetchSnapshotChunkStream(transport, {
+    emitTrace(trace?.onTrace, {
+      stage: 'apply:chunk-materialize:start',
+      stateId: trace?.stateId,
+      subscriptionId: trace?.subscriptionId,
+      table: snapshot.table,
       chunkId: chunk.id,
-      scopeValues,
+      chunkIndex,
     });
-    const decodedStream = await maybeGunzipStream(rawStream);
-    let streamForDecode = decodedStream;
-    let chunkHashPromise: Promise<string> | null = null;
+    const chunkStartedAt = Date.now();
 
-    if (chunk.sha256) {
-      const [hashStream, decodeStream] = decodedStream.tee();
-      streamForDecode = decodeStream;
-      chunkHashPromise = readAllBytesFromStream(hashStream).then((bytes) =>
-        computeSha256Hex(bytes, sha256Override)
+    try {
+      const rawStream = await fetchSnapshotChunkStream(
+        transport,
+        {
+          chunkId: chunk.id,
+          scopeValues,
+        },
+        {
+          stateId: trace?.stateId,
+          subscriptionId: trace?.subscriptionId,
+          table: snapshot.table,
+        }
       );
-    }
+      const decodedStream = await maybeGunzipStream(rawStream, {
+        stateId: trace?.stateId,
+        subscriptionId: trace?.subscriptionId,
+        table: snapshot.table,
+        chunkId: chunk.id,
+      });
+      let streamForDecode = decodedStream;
+      let chunkHashPromise: Promise<string> | null = null;
+
+      if (chunk.sha256) {
+        const [hashStream, decodeStream] = decodedStream.tee();
+        streamForDecode = decodeStream;
+        chunkHashPromise = readAllBytesFromStream(hashStream).then((bytes) =>
+          computeSha256Hex(bytes, sha256Override)
+        );
+      }
 
-    const rowBatchIterator = decodeSnapshotRowStreamBatches(
-      streamForDecode,
-      SNAPSHOT_APPLY_BATCH_ROWS
-    );
+      const rowBatchIterator = decodeSnapshotRowStreamBatches(
+        streamForDecode,
+        SNAPSHOT_APPLY_BATCH_ROWS
+      );
 
-    let pendingBatch: unknown[] | null = null;
-    let applyError: unknown = null;
+      let pendingBatch: unknown[] | null = null;
+      let applyError: unknown = null;
+      let chunkRowCount = 0;
+
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        for await (const batch of rowBatchIterator) {
+          chunkRowCount += batch.length;
+          if (pendingBatch) {
+            // eslint-disable-next-line no-await-in-loop
+            try {
+              await handler.applySnapshot(
+                { trx },
+                {
+                  ...snapshot,
+                  rows: pendingBatch,
+                  chunks: undefined,
+                  isFirstPage: nextIsFirstPage,
+                  isLastPage: false,
+                }
+              );
+            } catch (error) {
+              throw wrapSyncClientStageError(
+                error,
+                {
+                  stage: 'snapshot-apply',
+                  stateId: trace?.stateId,
+                  subscriptionId: trace?.subscriptionId,
+                  table: snapshot.table,
+                  chunkId: chunk.id,
+                },
+                `Failed to apply snapshot chunk "${chunk.id}"`
+              );
+            }
+            nextIsFirstPage = false;
+          }
+          pendingBatch = batch;
+        }
 
-    try {
-      // eslint-disable-next-line no-await-in-loop
-      for await (const batch of rowBatchIterator) {
         if (pendingBatch) {
+          const isLastChunk = chunkIndex === chunks.length - 1;
           // eslint-disable-next-line no-await-in-loop
-          await handler.applySnapshot(
-            { trx },
-            {
-              ...snapshot,
-              rows: pendingBatch,
-              chunks: undefined,
-              isFirstPage: nextIsFirstPage,
-              isLastPage: false,
-            }
-          );
+          try {
+            await handler.applySnapshot(
+              { trx },
+              {
+                ...snapshot,
+                rows: pendingBatch,
+                chunks: undefined,
+                isFirstPage: nextIsFirstPage,
+                isLastPage: isLastChunk ? snapshot.isLastPage : false,
+              }
+            );
+          } catch (error) {
+            throw wrapSyncClientStageError(
+              error,
+              {
+                stage: 'snapshot-apply',
+                stateId: trace?.stateId,
+                subscriptionId: trace?.subscriptionId,
+                table: snapshot.table,
+                chunkId: chunk.id,
+              },
+              `Failed to apply snapshot chunk "${chunk.id}"`
+            );
+          }
           nextIsFirstPage = false;
         }
-        pendingBatch = batch;
+      } catch (error) {
+        applyError =
+          error instanceof SyncClientStageError
+            ? error
+            : wrapSyncClientStageError(
+                error,
+                {
+                  stage: 'snapshot-chunk-decode',
+                  stateId: trace?.stateId,
+                  subscriptionId: trace?.subscriptionId,
+                  table: snapshot.table,
+                  chunkId: chunk.id,
+                },
+                `Failed to decode snapshot chunk "${chunk.id}"`
+              );
       }
 
-      if (pendingBatch) {
-        const isLastChunk = chunkIndex === chunks.length - 1;
-        // eslint-disable-next-line no-await-in-loop
-        await handler.applySnapshot(
-          { trx },
-          {
-            ...snapshot,
-            rows: pendingBatch,
-            chunks: undefined,
-            isFirstPage: nextIsFirstPage,
-            isLastPage: isLastChunk ? snapshot.isLastPage : false,
+      if (chunkHashPromise) {
+        try {
+          // eslint-disable-next-line no-await-in-loop
+          const actualHash = await chunkHashPromise;
+          if (!applyError && actualHash !== chunk.sha256) {
+            applyError = new SyncClientStageError(
+              `Snapshot chunk integrity check failed: expected sha256 ${chunk.sha256}, got ${actualHash}`,
+              {
+                stage: 'snapshot-integrity',
+                stateId: trace?.stateId,
+                subscriptionId: trace?.subscriptionId,
+                table: snapshot.table,
+                chunkId: chunk.id,
+              }
+            );
           }
-        );
-        nextIsFirstPage = false;
+        } catch (hashError) {
+          if (!applyError) {
+            applyError = hashError;
+          }
+        }
       }
-    } catch (error) {
-      applyError = error;
-    }
 
-    if (chunkHashPromise) {
-      try {
-        // eslint-disable-next-line no-await-in-loop
-        const actualHash = await chunkHashPromise;
-        if (!applyError && actualHash !== chunk.sha256) {
-          applyError = new Error(
-            `Snapshot chunk integrity check failed: expected sha256 ${chunk.sha256}, got ${actualHash}`
-          );
-        }
-      } catch (hashError) {
-        if (!applyError) {
-          applyError = hashError;
-        }
+      if (applyError) {
+        throw applyError;
       }
-    }
 
-    if (applyError) {
-      throw applyError;
+      emitTrace(trace?.onTrace, {
+        stage: 'apply:chunk-materialize:complete',
+        stateId: trace?.stateId,
+        subscriptionId: trace?.subscriptionId,
+        table: snapshot.table,
+        chunkId: chunk.id,
+        chunkIndex,
+        rowCount: chunkRowCount,
+        durationMs: Math.max(0, Date.now() - chunkStartedAt),
+      });
+    } catch (error) {
+      emitTrace(trace?.onTrace, {
+        stage: 'apply:chunk-materialize:error',
+        stateId: trace?.stateId,
+        subscriptionId: trace?.subscriptionId,
+        table: snapshot.table,
+        chunkId: chunk.id,
+        chunkIndex,
+        durationMs: Math.max(0, Date.now() - chunkStartedAt),
+        errorMessage: error instanceof Error ? error.message : String(error),
+      });
+      throw error;
     }
   }
 }
@@ -580,6 +861,69 @@ function parseBootstrapState(
   }
 }
 
+function normalizeBootstrapPhase(value: number | undefined): number {
+  if (value === undefined) return 0;
+  return Number.isFinite(value) ? Math.max(0, Math.trunc(value)) : 0;
+}
+
+function isSubscriptionReady(
+  row: SyncSubscriptionStateTable | undefined
+): boolean {
+  return (
+    row?.status === 'active' &&
+    parseBootstrapState(row.bootstrap_state_json) === null &&
+    row.cursor >= 0
+  );
+}
+
+function isSubscriptionBootstrapping(
+  row: SyncSubscriptionStateTable | undefined
+): boolean {
+  return (
+    row?.status === 'active' &&
+    parseBootstrapState(row.bootstrap_state_json) !== null
+  );
+}
+
+function resolveActiveBootstrapPhase(
+  subscriptions: readonly SyncClientSubscription[],
+  existingById: ReadonlyMap<string, SyncSubscriptionStateTable>
+): number | null {
+  let lowestPendingPhase: number | null = null;
+
+  for (const subscription of subscriptions) {
+    const phase = normalizeBootstrapPhase(subscription.bootstrapPhase);
+    if (isSubscriptionReady(existingById.get(subscription.id))) {
+      continue;
+    }
+    if (lowestPendingPhase === null || phase < lowestPendingPhase) {
+      lowestPendingPhase = phase;
+    }
+  }
+
+  return lowestPendingPhase;
+}
+
+function selectPullSubscriptions(
+  subscriptions: readonly SyncClientSubscription[],
+  existingById: ReadonlyMap<string, SyncSubscriptionStateTable>
+): SyncClientSubscription[] {
+  const activePhase = resolveActiveBootstrapPhase(subscriptions, existingById);
+  if (activePhase === null) {
+    return [...subscriptions];
+  }
+
+  return subscriptions.filter((subscription) => {
+    const phase = normalizeBootstrapPhase(subscription.bootstrapPhase);
+    const existing = existingById.get(subscription.id);
+
+    if (phase <= activePhase) return true;
+    if (isSubscriptionReady(existing)) return true;
+    if (isSubscriptionBootstrapping(existing)) return true;
+    return false;
+  });
+}
+
 function parseScopeValuesJson(
   value: string | object | null | undefined
 ): ScopeValues {
@@ -698,7 +1042,7 @@ export interface SyncPullOnceOptions {
    * Desired subscriptions (client-chosen ids).
    * Cursors are persisted in `sync_subscription_state`.
    */
-  subscriptions: Array<Omit<SyncSubscriptionRequest, 'cursor'>>;
+  subscriptions: SyncClientSubscription[];
   limitCommits?: number;
   limitSnapshotRows?: number;
   maxSnapshotPages?: number;
@@ -721,6 +1065,8 @@ export interface SyncPullOnceOptions {
    * Must return the hex-encoded hash string.
    */
   sha256?: (bytes: Uint8Array) => Promise<string>;
+  /** Optional structured tracing hook for pull/apply lifecycle diagnostics. */
+  onTrace?: (event: SyncTraceEvent) => void;
 }
 
 export interface SyncPullRequestState {
@@ -728,6 +1074,40 @@ export interface SyncPullRequestState {
   existing: SyncSubscriptionStateTable[];
   existingById: Map<string, SyncSubscriptionStateTable>;
   stateId: string;
+  configuredSubscriptions: SyncClientSubscription[];
+}
+
+function emitTrace(
+  onTrace: SyncPullOnceOptions['onTrace'],
+  event: Omit<SyncTraceEvent, 'timestamp'>
+): void {
+  onTrace?.({
+    timestamp: Date.now(),
+    ...event,
+  });
+}
+
+function countSubscriptionRows(
+  subscription: SyncPullSubscriptionResponse
+): number | undefined {
+  if (!subscription.bootstrap) return undefined;
+  const snapshots = subscription.snapshots ?? [];
+  if (snapshots.length === 0) return 0;
+  return snapshots.reduce(
+    (sum, snapshot) => sum + (snapshot.rows?.length ?? 0),
+    0
+  );
+}
+
+function countSubscriptionChunks(
+  subscription: SyncPullSubscriptionResponse
+): number | undefined {
+  if (!subscription.bootstrap) return undefined;
+  const snapshots = subscription.snapshots ?? [];
+  return snapshots.reduce(
+    (sum, snapshot) => sum + (snapshot.chunks?.length ?? 0),
+    0
+  );
 }
 
 /**
@@ -760,13 +1140,19 @@ export async function buildPullRequest<DB extends SyncClientDb>(
   const existingById = new Map<string, SyncSubscriptionStateTable>();
   for (const row of existing) existingById.set(row.subscription_id, row);
 
+  const configuredSubscriptions = options.subscriptions ?? [];
+  const selectedSubscriptions = selectPullSubscriptions(
+    configuredSubscriptions,
+    existingById
+  );
+
   const request: SyncPullRequest = {
     clientId: options.clientId,
     limitCommits: options.limitCommits ?? 50,
     limitSnapshotRows: options.limitSnapshotRows ?? 1000,
     maxSnapshotPages: options.maxSnapshotPages ?? 4,
     dedupeRows: options.dedupeRows,
-    subscriptions: (options.subscriptions ?? []).map((sub) => ({
+    subscriptions: selectedSubscriptions.map((sub) => ({
       ...sub,
       cursor: Math.max(-1, existingById.get(sub.id)?.cursor ?? -1),
       bootstrapState: parseBootstrapState(
@@ -775,7 +1161,13 @@ export async function buildPullRequest<DB extends SyncClientDb>(
     })),
   };
 
-  return { request, existing, existingById, stateId };
+  return {
+    request,
+    existing,
+    existingById,
+    stateId,
+    configuredSubscriptions,
+  };
 }
 
 export function createFollowupPullState(
@@ -822,9 +1214,13 @@ export function createFollowupPullState(
     nextExistingById.set(nextRow.subscription_id, nextRow);
   }
 
+  const nextSelectedSubscriptions = selectPullSubscriptions(
+    pullState.configuredSubscriptions,
+    nextExistingById
+  );
   const nextRequest: SyncPullRequest = {
     ...pullState.request,
-    subscriptions: (pullState.request.subscriptions ?? []).map((sub) => {
+    subscriptions: nextSelectedSubscriptions.map((sub) => {
       const row = nextExistingById.get(sub.id);
       return {
         ...sub,
@@ -839,6 +1235,7 @@ export function createFollowupPullState(
     existing: nextExisting,
     existingById: nextExistingById,
     stateId: pullState.stateId,
+    configuredSubscriptions: pullState.configuredSubscriptions,
   };
 }
 
@@ -916,7 +1313,15 @@ export async function applyPullResponse<DB extends SyncClientDb>(
   );
 
   let responseToApply = requiresMaterializedSnapshots
-    ? await materializeChunkedSnapshots(transport, rawResponse, options.sha256)
+    ? await materializeChunkedSnapshots(
+        transport,
+        rawResponse,
+        options.sha256,
+        {
+          stateId,
+          onTrace: options.onTrace,
+        }
+      )
     : rawResponse;
   for (const plugin of plugins) {
     if (!plugin.afterPull) continue;
@@ -941,34 +1346,92 @@ export async function applyPullResponse<DB extends SyncClientDb>(
 
   if (bootstrapApplyMode === 'per-subscription') {
     for (const sub of responseToApply.subscriptions) {
-      await db.transaction().execute(async (trx) => {
-        await applySubscriptionResponse({
-          trx,
-          handlers,
-          transport,
-          options,
+      emitTrace(options.onTrace, {
+        stage: 'apply:transaction:start',
+        stateId,
+        transactionMode: bootstrapApplyMode,
+        subscriptionIds: [sub.id],
+        subscriptionCount: 1,
+      });
+      const transactionStartedAt = Date.now();
+      try {
+        await db.transaction().execute(async (trx) => {
+          await applySubscriptionResponse({
+            trx,
+            handlers,
+            transport,
+            options,
+            stateId,
+            existingById,
+            subsById,
+            sub,
+          });
+        });
+        emitTrace(options.onTrace, {
+          stage: 'apply:transaction:complete',
           stateId,
-          existingById,
-          subsById,
-          sub,
+          transactionMode: bootstrapApplyMode,
+          subscriptionIds: [sub.id],
+          subscriptionCount: 1,
+          durationMs: Math.max(0, Date.now() - transactionStartedAt),
         });
-      });
-    }
-  } else {
-    await db.transaction().execute(async (trx) => {
-      for (const sub of responseToApply.subscriptions) {
-        await applySubscriptionResponse({
-          trx,
-          handlers,
-          transport,
-          options,
+      } catch (error) {
+        emitTrace(options.onTrace, {
+          stage: 'apply:transaction:error',
           stateId,
-          existingById,
-          subsById,
-          sub,
+          transactionMode: bootstrapApplyMode,
+          subscriptionIds: [sub.id],
+          subscriptionCount: 1,
+          durationMs: Math.max(0, Date.now() - transactionStartedAt),
+          errorMessage: error instanceof Error ? error.message : String(error),
         });
+        throw error;
       }
+    }
+  } else {
+    emitTrace(options.onTrace, {
+      stage: 'apply:transaction:start',
+      stateId,
+      transactionMode: bootstrapApplyMode,
+      subscriptionIds: responseToApply.subscriptions.map((sub) => sub.id),
+      subscriptionCount: responseToApply.subscriptions.length,
     });
+    const transactionStartedAt = Date.now();
+    try {
+      await db.transaction().execute(async (trx) => {
+        for (const sub of responseToApply.subscriptions) {
+          await applySubscriptionResponse({
+            trx,
+            handlers,
+            transport,
+            options,
+            stateId,
+            existingById,
+            subsById,
+            sub,
+          });
+        }
+      });
+      emitTrace(options.onTrace, {
+        stage: 'apply:transaction:complete',
+        stateId,
+        transactionMode: bootstrapApplyMode,
+        subscriptionIds: responseToApply.subscriptions.map((sub) => sub.id),
+        subscriptionCount: responseToApply.subscriptions.length,
+        durationMs: Math.max(0, Date.now() - transactionStartedAt),
+      });
+    } catch (error) {
+      emitTrace(options.onTrace, {
+        stage: 'apply:transaction:error',
+        stateId,
+        transactionMode: bootstrapApplyMode,
+        subscriptionIds: responseToApply.subscriptions.map((sub) => sub.id),
+        subscriptionCount: responseToApply.subscriptions.length,
+        durationMs: Math.max(0, Date.now() - transactionStartedAt),
+        errorMessage: error instanceof Error ? error.message : String(error),
+      });
+      throw error;
+    }
   }
 
   return responseToApply;
@@ -1002,7 +1465,7 @@ async function removeUndesiredSubscriptions<DB extends SyncClientDb>(
   trx: Transaction<DB>,
   handlers: ClientHandlerCollection<DB>,
   existing: SyncSubscriptionStateTable[],
-  desiredSubscriptions: Array<Omit<SyncSubscriptionRequest, 'cursor'>>,
+  desiredSubscriptions: SyncClientSubscription[],
   stateId: string
 ): Promise<void> {
   const desiredIds = new Set(
@@ -1063,7 +1526,7 @@ async function applySubscriptionResponse<DB extends SyncClientDb>(args: {
   options: SyncPullOnceOptions;
   stateId: string;
   existingById: Map<string, SyncSubscriptionStateTable>;
-  subsById: Map<string, Omit<SyncSubscriptionRequest, 'cursor'> | undefined>;
+  subsById: Map<string, SyncClientSubscription | undefined>;
   sub: SyncPullSubscriptionResponse;
 }): Promise<void> {
   const {
@@ -1102,146 +1565,275 @@ async function applySubscriptionResponse<DB extends SyncClientDb>(args: {
     effectiveCursor !== null &&
     sub.nextCursor < effectiveCursor;
 
+  const applyStartedAt = Date.now();
+  emitTrace(options.onTrace, {
+    stage: 'apply:subscription:start',
+    stateId,
+    subscriptionId: sub.id,
+    table: def?.table ?? prev?.table,
+    bootstrap: sub.bootstrap,
+    snapshotCount: sub.snapshots?.length ?? 0,
+    commitCount: sub.commits?.length ?? 0,
+    chunkCount: countSubscriptionChunks(sub),
+    rowCount: countSubscriptionRows(sub),
+    nextCursor: sub.nextCursor,
+  });
+
   if (staleIncrementalResponse) {
+    emitTrace(options.onTrace, {
+      stage: 'apply:subscription:complete',
+      stateId,
+      subscriptionId: sub.id,
+      table: def?.table ?? prev?.table,
+      bootstrap: sub.bootstrap,
+      snapshotCount: sub.snapshots?.length ?? 0,
+      commitCount: sub.commits?.length ?? 0,
+      chunkCount: countSubscriptionChunks(sub),
+      rowCount: countSubscriptionRows(sub),
+      nextCursor: sub.nextCursor,
+      durationMs: Math.max(0, Date.now() - applyStartedAt),
+    });
     return;
   }
 
-  if (sub.status === 'revoked') {
-    if (prev?.table) {
+  try {
+    if (sub.status === 'revoked') {
+      if (prev?.table) {
+        try {
+          const scopes = parseScopeValuesJson(prev.scopes_json);
+          await getClientHandlerOrThrow(handlers, prev.table).clearAll({
+            trx,
+            scopes,
+          });
+        } catch {
+          // ignore missing handler
+        }
+      }
+
+      await sql`
+        delete from ${sql.table('sync_subscription_state')}
+        where ${sql.ref('state_id')} = ${sql.val(stateId)}
+          and ${sql.ref('subscription_id')} = ${sql.val(sub.id)}
+      `.execute(trx);
+      emitTrace(options.onTrace, {
+        stage: 'apply:subscription:complete',
+        stateId,
+        subscriptionId: sub.id,
+        table: def?.table ?? prev?.table,
+        bootstrap: sub.bootstrap,
+        snapshotCount: sub.snapshots?.length ?? 0,
+        commitCount: sub.commits?.length ?? 0,
+        chunkCount: countSubscriptionChunks(sub),
+        rowCount: countSubscriptionRows(sub),
+        nextCursor: null,
+        durationMs: Math.max(0, Date.now() - applyStartedAt),
+      });
+      return;
+    }
+
+    const nextScopes = sub.scopes ?? def?.scopes ?? {};
+    const previousScopes = parseScopeValuesJson(prev?.scopes_json);
+    const scopesChanged = !scopeValuesEqual(previousScopes, nextScopes);
+
+    if (sub.bootstrap && prev?.table && scopesChanged) {
       try {
-        const scopes = parseScopeValuesJson(prev.scopes_json);
-        await getClientHandlerOrThrow(handlers, prev.table).clearAll({
-          trx,
-          scopes,
-        });
+        const clearScopes = resolveBootstrapClearScopes(
+          previousScopes,
+          nextScopes
+        );
+        if (clearScopes !== 'none') {
+          await getClientHandlerOrThrow(handlers, prev.table).clearAll({
+            trx,
+            scopes: clearScopes ?? previousScopes,
+          });
+        }
       } catch {
         // ignore missing handler
       }
     }
 
-    await sql`
-      delete from ${sql.table('sync_subscription_state')}
-      where ${sql.ref('state_id')} = ${sql.val(stateId)}
-        and ${sql.ref('subscription_id')} = ${sql.val(sub.id)}
-    `.execute(trx);
-    return;
-  }
+    if (sub.bootstrap) {
+      for (const snapshot of sub.snapshots ?? []) {
+        const handler = getClientHandlerOrThrow(handlers, snapshot.table);
+        const hasChunkRefs =
+          Array.isArray(snapshot.chunks) && snapshot.chunks.length > 0;
+
+        if (snapshot.isFirstPage && handler.onSnapshotStart) {
+          try {
+            await handler.onSnapshotStart({
+              trx,
+              table: snapshot.table,
+              scopes: sub.scopes,
+            });
+          } catch (error) {
+            throw wrapSyncClientStageError(
+              error,
+              {
+                stage: 'snapshot-apply',
+                stateId,
+                subscriptionId: sub.id,
+                table: snapshot.table,
+              },
+              `Failed to start snapshot apply for subscription "${sub.id}"`
+            );
+          }
+        }
 
-  const nextScopes = sub.scopes ?? def?.scopes ?? {};
-  const previousScopes = parseScopeValuesJson(prev?.scopes_json);
-  const scopesChanged = !scopeValuesEqual(previousScopes, nextScopes);
+        if (hasChunkRefs) {
+          await applyChunkedSnapshot(
+            transport,
+            handler,
+            trx,
+            snapshot,
+            sub.scopes,
+            options.sha256,
+            {
+              stateId,
+              subscriptionId: sub.id,
+              onTrace: options.onTrace,
+            }
+          );
+        } else {
+          try {
+            await handler.applySnapshot({ trx }, snapshot);
+          } catch (error) {
+            throw wrapSyncClientStageError(
+              error,
+              {
+                stage: 'snapshot-apply',
+                stateId,
+                subscriptionId: sub.id,
+                table: snapshot.table,
+              },
+              `Failed to apply snapshot for subscription "${sub.id}"`
+            );
+          }
+        }
 
-  if (sub.bootstrap && prev?.table && scopesChanged) {
-    try {
-      const clearScopes = resolveBootstrapClearScopes(
-        previousScopes,
-        nextScopes
-      );
-      if (clearScopes !== 'none') {
-        await getClientHandlerOrThrow(handlers, prev.table).clearAll({
-          trx,
-          scopes: clearScopes ?? previousScopes,
-        });
+        if (snapshot.isLastPage && handler.onSnapshotEnd) {
+          try {
+            await handler.onSnapshotEnd({
+              trx,
+              table: snapshot.table,
+              scopes: sub.scopes,
+            });
+          } catch (error) {
+            throw wrapSyncClientStageError(
+              error,
+              {
+                stage: 'snapshot-apply',
+                stateId,
+                subscriptionId: sub.id,
+                table: snapshot.table,
+              },
+              `Failed to finalize snapshot apply for subscription "${sub.id}"`
+            );
+          }
+        }
+      }
+    } else {
+      for (const commit of sub.commits) {
+        try {
+          await applyIncrementalCommitChanges(handlers, trx, {
+            changes: commit.changes,
+            commitSeq: commit.commitSeq ?? null,
+            actorId: commit.actorId ?? null,
+            createdAt: commit.createdAt ?? null,
+          });
+        } catch (error) {
+          throw wrapSyncClientStageError(
+            error,
+            {
+              stage: 'snapshot-apply',
+              stateId,
+              subscriptionId: sub.id,
+              table: def?.table ?? prev?.table,
+            },
+            `Failed to apply incremental changes for subscription "${sub.id}"`
+          );
+        }
       }
-    } catch {
-      // ignore missing handler
     }
-  }
 
-  if (sub.bootstrap) {
-    for (const snapshot of sub.snapshots ?? []) {
-      const handler = getClientHandlerOrThrow(handlers, snapshot.table);
-      const hasChunkRefs =
-        Array.isArray(snapshot.chunks) && snapshot.chunks.length > 0;
-
-      if (snapshot.isFirstPage && handler.onSnapshotStart) {
-        await handler.onSnapshotStart({
-          trx,
-          table: snapshot.table,
-          scopes: sub.scopes,
-        });
-      }
+    const now = Date.now();
+    const paramsJson = serializeJsonCached(def?.params ?? {});
+    const scopesJson = serializeJsonCached(nextScopes);
+    const bootstrapStateJson = sub.bootstrap
+      ? sub.bootstrapState
+        ? serializeJsonCached(sub.bootstrapState)
+        : null
+      : null;
+    const table = def?.table ?? 'unknown';
 
-      if (hasChunkRefs) {
-        await applyChunkedSnapshot(
-          transport,
-          handler,
-          trx,
-          snapshot,
-          sub.scopes,
-          options.sha256
-        );
-      } else {
-        await handler.applySnapshot({ trx }, snapshot);
-      }
+    await sql`
+      insert into ${sql.table('sync_subscription_state')} (
+        ${sql.join([
+          sql.ref('state_id'),
+          sql.ref('subscription_id'),
+          sql.ref('table'),
+          sql.ref('scopes_json'),
+          sql.ref('params_json'),
+          sql.ref('cursor'),
+          sql.ref('bootstrap_state_json'),
+          sql.ref('status'),
+          sql.ref('created_at'),
+          sql.ref('updated_at'),
+        ])}
+      ) values (
+        ${sql.join([
+          sql.val(stateId),
+          sql.val(sub.id),
+          sql.val(table),
+          sql.val(scopesJson),
+          sql.val(paramsJson),
+          sql.val(sub.nextCursor),
+          sql.val(bootstrapStateJson),
+          sql.val('active'),
+          sql.val(now),
+          sql.val(now),
+        ])}
+      )
+      on conflict (${sql.join([sql.ref('state_id'), sql.ref('subscription_id')])})
+      do update set
+        ${sql.ref('table')} = ${sql.val(table)},
+        ${sql.ref('scopes_json')} = ${sql.val(scopesJson)},
+        ${sql.ref('params_json')} = ${sql.val(paramsJson)},
+        ${sql.ref('cursor')} = ${sql.val(sub.nextCursor)},
+        ${sql.ref('bootstrap_state_json')} = ${sql.val(bootstrapStateJson)},
+        ${sql.ref('status')} = ${sql.val('active')},
+        ${sql.ref('updated_at')} = ${sql.val(now)}
+    `.execute(trx);
 
-      if (snapshot.isLastPage && handler.onSnapshotEnd) {
-        await handler.onSnapshotEnd({
-          trx,
-          table: snapshot.table,
-          scopes: sub.scopes,
-        });
-      }
-    }
-  } else {
-    for (const commit of sub.commits) {
-      await applyIncrementalCommitChanges(handlers, trx, {
-        changes: commit.changes,
-        commitSeq: commit.commitSeq ?? null,
-        actorId: commit.actorId ?? null,
-        createdAt: commit.createdAt ?? null,
-      });
-    }
+    emitTrace(options.onTrace, {
+      stage: 'apply:subscription:complete',
+      stateId,
+      subscriptionId: sub.id,
+      table,
+      bootstrap: sub.bootstrap,
+      snapshotCount: sub.snapshots?.length ?? 0,
+      commitCount: sub.commits?.length ?? 0,
+      chunkCount: countSubscriptionChunks(sub),
+      rowCount: countSubscriptionRows(sub),
+      nextCursor: sub.nextCursor,
+      durationMs: Math.max(0, Date.now() - applyStartedAt),
+    });
+  } catch (error) {
+    emitTrace(options.onTrace, {
+      stage: 'apply:subscription:error',
+      stateId,
+      subscriptionId: sub.id,
+      table: def?.table ?? prev?.table,
+      bootstrap: sub.bootstrap,
+      snapshotCount: sub.snapshots?.length ?? 0,
+      commitCount: sub.commits?.length ?? 0,
+      chunkCount: countSubscriptionChunks(sub),
+      rowCount: countSubscriptionRows(sub),
+      nextCursor: sub.nextCursor,
+      durationMs: Math.max(0, Date.now() - applyStartedAt),
+      errorMessage: error instanceof Error ? error.message : String(error),
+    });
+    throw error;
   }
-
-  const now = Date.now();
-  const paramsJson = serializeJsonCached(def?.params ?? {});
-  const scopesJson = serializeJsonCached(nextScopes);
-  const bootstrapStateJson = sub.bootstrap
-    ? sub.bootstrapState
-      ? serializeJsonCached(sub.bootstrapState)
-      : null
-    : null;
-  const table = def?.table ?? 'unknown';
-
-  await sql`
-    insert into ${sql.table('sync_subscription_state')} (
-      ${sql.join([
-        sql.ref('state_id'),
-        sql.ref('subscription_id'),
-        sql.ref('table'),
-        sql.ref('scopes_json'),
-        sql.ref('params_json'),
-        sql.ref('cursor'),
-        sql.ref('bootstrap_state_json'),
-        sql.ref('status'),
-        sql.ref('created_at'),
-        sql.ref('updated_at'),
-      ])}
-    ) values (
-      ${sql.join([
-        sql.val(stateId),
-        sql.val(sub.id),
-        sql.val(table),
-        sql.val(scopesJson),
-        sql.val(paramsJson),
-        sql.val(sub.nextCursor),
-        sql.val(bootstrapStateJson),
-        sql.val('active'),
-        sql.val(now),
-        sql.val(now),
-      ])}
-    )
-    on conflict (${sql.join([sql.ref('state_id'), sql.ref('subscription_id')])})
-    do update set
-      ${sql.ref('table')} = ${sql.val(table)},
-      ${sql.ref('scopes_json')} = ${sql.val(scopesJson)},
-      ${sql.ref('params_json')} = ${sql.val(paramsJson)},
-      ${sql.ref('cursor')} = ${sql.val(sub.nextCursor)},
-      ${sql.ref('bootstrap_state_json')} = ${sql.val(bootstrapStateJson)},
-      ${sql.ref('status')} = ${sql.val('active')},
-      ${sql.ref('updated_at')} = ${sql.val(now)}
-  `.execute(trx);
 }
 
 export async function syncPullOnce<DB extends SyncClientDb>(
@@ -1253,10 +1845,48 @@ export async function syncPullOnce<DB extends SyncClientDb>(
 ): Promise<SyncPullResponse> {
   const pullState = pullStateOverride ?? (await buildPullRequest(db, options));
   const { clientId, ...pullBody } = pullState.request;
-  const combined = await transport.sync({ clientId, pull: pullBody });
+  emitTrace(options.onTrace, {
+    stage: 'pull:start',
+    stateId: pullState.stateId,
+    subscriptionIds: pullState.request.subscriptions.map(
+      (subscription) => subscription.id
+    ),
+    subscriptionCount: pullState.request.subscriptions.length,
+  });
+  let combined: SyncCombinedResponse;
+  try {
+    combined = await transport.sync({ clientId, pull: pullBody });
+  } catch (error) {
+    emitTrace(options.onTrace, {
+      stage: 'pull:error',
+      stateId: pullState.stateId,
+      subscriptionIds: pullState.request.subscriptions.map(
+        (subscription) => subscription.id
+      ),
+      subscriptionCount: pullState.request.subscriptions.length,
+      errorMessage: error instanceof Error ? error.message : String(error),
+    });
+    throw error;
+  }
   if (!combined.pull) {
     return { ok: true, subscriptions: [] };
   }
+  emitTrace(options.onTrace, {
+    stage: 'pull:response',
+    stateId: pullState.stateId,
+    subscriptionIds: combined.pull.subscriptions.map(
+      (subscription) => subscription.id
+    ),
+    subscriptionCount: combined.pull.subscriptions.length,
+    commitCount: combined.pull.subscriptions.reduce(
+      (sum, subscription) => sum + (subscription.commits?.length ?? 0),
+      0
+    ),
+    snapshotCount: combined.pull.subscriptions.reduce(
+      (sum, subscription) => sum + (subscription.snapshots?.length ?? 0),
+      0
+    ),
+  });
   return applyPullResponse(
     db,
     transport,