@syncular/client 0.0.6-219 → 0.0.6-221

package/dist/pull-engine.js

@@ -243,59 +243,119 @@ async function readAllBytesFromStream(stream) {
     }
     return bytes;
 }
-async function materializeSnapshotChunkRows(transport, request, expectedHash, sha256Override) {
+async function materializeSnapshotChunkRows(transport, request, expectedHash, sha256Override, trace) {
+    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)) {
+                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}`);
+                }
             }
+            const rows = decodeSnapshotRows(bytes);
+            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 = null;
-    if (expectedHash) {
-        const [hashStream, decodeStream] = decodedStream.tee();
-        streamForDecode = decodeStream;
-        chunkHashPromise = readAllBytesFromStream(hashStream).then((bytes) => computeSha256Hex(bytes, sha256Override));
     }
-    const rows = [];
-    let materializeError = null;
     try {
-        for await (const batch of decodeSnapshotRowStreamBatches(streamForDecode, SNAPSHOT_APPLY_BATCH_ROWS)) {
-            rows.push(...batch);
+        const rawStream = await fetchSnapshotChunkStream(transport, request);
+        const decodedStream = await maybeGunzipStream(rawStream);
+        let streamForDecode = decodedStream;
+        let chunkHashPromise = 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 = [];
+        let materializeError = 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 = error;
+        }
+        if (chunkHashPromise) {
+            try {
+                const actualHash = await chunkHashPromise;
+                if (!materializeError && actualHash !== expectedHash) {
+                    materializeError = new Error(`Snapshot chunk integrity check failed: expected sha256 ${expectedHash}, got ${actualHash}`);
+                }
             }
+            catch (hashError) {
+                if (!materializeError) {
+                    materializeError = hashError;
+                }
+            }
+        }
+        if (materializeError) {
+            throw materializeError;
         }
+        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;
     }
-    if (materializeError) {
-        throw materializeError;
+    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 rows;
 }
-async function materializeChunkedSnapshots(transport, response, sha256Override) {
+async function materializeChunkedSnapshots(transport, response, sha256Override, trace) {
     const subscriptions = [];
     for (const sub of response.subscriptions) {
         if (!sub.bootstrap || !sub.snapshots || sub.snapshots.length === 0) {
@@ -310,11 +370,20 @@ async function materializeChunkedSnapshots(transport, response, sha256Override)
                 continue;
             }
             const rows = [];
-            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, {
                     chunkId: chunk.id,
                     scopeValues: sub.scopes,
-                }, chunk.sha256, sha256Override);
+                }, chunk.sha256, sha256Override, {
+                    stateId: trace?.stateId ?? 'default',
+                    subscriptionId: sub.id,
+                    table: snapshot.table,
+                    chunkIndex,
+                    onTrace: trace?.onTrace,
+                });
                 rows.push(...chunkRows);
             }
             snapshots.push({
@@ -330,7 +399,7 @@ async function materializeChunkedSnapshots(transport, response, sha256Override)
     }
     return { ...response, subscriptions };
 }
-async function applyChunkedSnapshot(transport, handler, trx, snapshot, scopeValues, sha256Override) {
+async function applyChunkedSnapshot(transport, handler, trx, snapshot, scopeValues, sha256Override, trace) {
     const chunks = snapshot.chunks ?? [];
     if (chunks.length === 0) {
         await handler.applySnapshot({ trx }, snapshot);
@@ -341,69 +410,105 @@ async function applyChunkedSnapshot(transport, handler, trx, snapshot, scopeValu
         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 = 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);
-        let pendingBatch = null;
-        let applyError = null;
+        const chunkStartedAt = Date.now();
         try {
-            // eslint-disable-next-line no-await-in-loop
-            for await (const batch of rowBatchIterator) {
+            const rawStream = await fetchSnapshotChunkStream(transport, {
+                chunkId: chunk.id,
+                scopeValues,
+            });
+            const decodedStream = await maybeGunzipStream(rawStream);
+            let streamForDecode = decodedStream;
+            let chunkHashPromise = 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);
+            let pendingBatch = null;
+            let applyError = 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
+                        await handler.applySnapshot({ trx }, {
+                            ...snapshot,
+                            rows: pendingBatch,
+                            chunks: undefined,
+                            isFirstPage: nextIsFirstPage,
+                            isLastPage: false,
+                        });
+                        nextIsFirstPage = false;
+                    }
+                    pendingBatch = batch;
+                }
                 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,
+                        isLastPage: isLastChunk ? snapshot.isLastPage : false,
                     });
                     nextIsFirstPage = false;
                 }
-                pendingBatch = batch;
             }
-            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,
-                });
-                nextIsFirstPage = false;
+            catch (error) {
+                applyError = error;
             }
-        }
-        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}`);
+            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;
+                catch (hashError) {
+                    if (!applyError) {
+                        applyError = hashError;
+                    }
                 }
             }
+            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),
+            });
         }
-        if (applyError) {
-            throw applyError;
+        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;
         }
     }
 }
@@ -431,6 +536,50 @@ function parseBootstrapState(value) {
         return null;
     }
 }
+function normalizeBootstrapPhase(value) {
+    if (value === undefined)
+        return 0;
+    return Number.isFinite(value) ? Math.max(0, Math.trunc(value)) : 0;
+}
+function isSubscriptionReady(row) {
+    return (row?.status === 'active' &&
+        parseBootstrapState(row.bootstrap_state_json) === null &&
+        row.cursor >= 0);
+}
+function isSubscriptionBootstrapping(row) {
+    return (row?.status === 'active' &&
+        parseBootstrapState(row.bootstrap_state_json) !== null);
+}
+function resolveActiveBootstrapPhase(subscriptions, existingById) {
+    let lowestPendingPhase = 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, existingById) {
+    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) {
     if (!value)
         return {};
@@ -517,6 +666,26 @@ function resolveBootstrapClearScopes(previous, next) {
     }
     return narrowed;
 }
+function emitTrace(onTrace, event) {
+    onTrace?.({
+        timestamp: Date.now(),
+        ...event,
+    });
+}
+function countSubscriptionRows(subscription) {
+    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) {
+    if (!subscription.bootstrap)
+        return undefined;
+    const snapshots = subscription.snapshots ?? [];
+    return snapshots.reduce((sum, snapshot) => sum + (snapshot.chunks?.length ?? 0), 0);
+}
 /**
  * Build a pull request from subscription state. Exported for use
  * by the combined sync path in sync-loop.ts.
@@ -542,19 +711,27 @@ export async function buildPullRequest(db, options) {
     const existingById = new Map();
     for (const row of existing)
         existingById.set(row.subscription_id, row);
+    const configuredSubscriptions = options.subscriptions ?? [];
+    const selectedSubscriptions = selectPullSubscriptions(configuredSubscriptions, existingById);
     const request = {
         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(existingById.get(sub.id)?.bootstrap_state_json),
         })),
     };
-    return { request, existing, existingById, stateId };
+    return {
+        request,
+        existing,
+        existingById,
+        stateId,
+        configuredSubscriptions,
+    };
 }
 export function createFollowupPullState(pullState, response) {
     const responseById = new Map();
@@ -593,9 +770,10 @@ export function createFollowupPullState(pullState, response) {
         nextExisting.push(nextRow);
         nextExistingById.set(nextRow.subscription_id, nextRow);
     }
+    const nextSelectedSubscriptions = selectPullSubscriptions(pullState.configuredSubscriptions, nextExistingById);
     const nextRequest = {
         ...pullState.request,
-        subscriptions: (pullState.request.subscriptions ?? []).map((sub) => {
+        subscriptions: nextSelectedSubscriptions.map((sub) => {
             const row = nextExistingById.get(sub.id);
             return {
                 ...sub,
@@ -609,6 +787,7 @@ export function createFollowupPullState(pullState, response) {
         existing: nextExisting,
         existingById: nextExistingById,
         stateId: pullState.stateId,
+        configuredSubscriptions: pullState.configuredSubscriptions,
     };
 }
 export async function applyIncrementalCommitChanges(handlers, trx, args) {
@@ -657,7 +836,10 @@ export async function applyPullResponse(db, transport, handlers, options, pullSt
         transport.capabilities?.preferMaterializedSnapshots === true;
     const bootstrapApplyMode = resolveBootstrapApplyMode(options, rawResponse, transport.capabilities);
     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)
@@ -675,35 +857,95 @@ export async function applyPullResponse(db, transport, handlers, options, pullSt
     });
     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;
 }
@@ -791,137 +1033,239 @@ async function applySubscriptionResponse(args) {
     const staleIncrementalResponse = !sub.bootstrap &&
         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;
-    }
-    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 clearScopes = resolveBootstrapClearScopes(previousScopes, nextScopes);
-            if (clearScopes !== 'none') {
-                await getClientHandlerOrThrow(handlers, prev.table).clearAll({
-                    trx,
-                    scopes: clearScopes ?? previousScopes,
-                });
+        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,
+                    });
+                }
+                if (hasChunkRefs) {
+                    await applyChunkedSnapshot(transport, handler, trx, snapshot, sub.scopes, options.sha256, {
+                        stateId,
+                        subscriptionId: sub.id,
+                        onTrace: options.onTrace,
+                    });
+                }
+                else {
+                    await handler.applySnapshot({ trx }, snapshot);
+                }
+                if (snapshot.isLastPage && handler.onSnapshotEnd) {
+                    await handler.onSnapshotEnd({
+                        trx,
+                        table: snapshot.table,
+                        scopes: sub.scopes,
+                    });
+                }
             }
         }
-        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,
-                });
-            }
-            if (hasChunkRefs) {
-                await applyChunkedSnapshot(transport, handler, trx, snapshot, sub.scopes, options.sha256);
-            }
-            else {
-                await handler.applySnapshot({ trx }, snapshot);
-            }
-            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,
                 });
             }
         }
+        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);
+        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),
+        });
     }
-    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,
-            });
-        }
+    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, transport, handlers, options, pullStateOverride) {
     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;
+    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, handlers, options, pullState, combined.pull);
 }
 //# sourceMappingURL=pull-engine.js.map