@syncular/client 0.0.6-213 → 0.0.6-221

package/dist/pull-engine.js

@@ -1,6 +1,7 @@
 /**
  * @syncular/client - Sync pull engine
  */
+import { bytesToReadableStream, decodeSnapshotRows, gunzipBytes, readAllBytesFromStream as readAllBytesFromCoreStream, } from '@syncular/core';
 import { sql } from 'kysely';
 import { getClientHandlerOrThrow, } from './handlers/collection.js';
 // Simple JSON serialization cache to avoid repeated stringification
@@ -30,14 +31,6 @@ function serializeJsonCached(obj) {
 function isGzipBytes(bytes) {
     return bytes.length >= 2 && bytes[0] === 0x1f && bytes[1] === 0x8b;
 }
-function bytesToReadableStream(bytes) {
-    return new ReadableStream({
-        start(controller) {
-            controller.enqueue(bytes);
-            controller.close();
-        },
-    });
-}
 function concatBytes(chunks) {
     if (chunks.length === 1) {
         return chunks[0] ?? new Uint8Array();
@@ -111,7 +104,8 @@ async function maybeGunzipStream(stream) {
     if (typeof DecompressionStream !== 'undefined') {
         return replayStream.pipeThrough(new DecompressionStream('gzip'));
     }
-    throw new Error('Snapshot chunk appears gzip-compressed but gzip decompression is not available in this runtime');
+    const compressedBytes = await readAllBytesFromCoreStream(replayStream);
+    return bytesToReadableStream(await gunzipBytes(compressedBytes));
 }
 async function* decodeSnapshotRowStreamBatches(stream, batchSize) {
     const reader = stream.getReader();
@@ -249,45 +243,119 @@ async function readAllBytesFromStream(stream) {
     }
     return bytes;
 }
-async function materializeSnapshotChunkRows(transport, request, expectedHash, sha256Override) {
-    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);
+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) {
+        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;
         }
     }
-    catch (error) {
-        materializeError = error;
-    }
-    if (chunkHashPromise) {
+    try {
+        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 {
-            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) {
@@ -302,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({
@@ -322,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);
@@ -333,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;
         }
     }
 }
@@ -423,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 {};
@@ -509,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.
@@ -534,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();
@@ -585,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,
@@ -601,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) {
@@ -645,9 +832,14 @@ export async function applyPullResponse(db, transport, handlers, options, pullSt
         clientId: options.clientId,
     };
     const plugins = options.plugins ?? [];
-    const requiresMaterializedSnapshots = plugins.some((plugin) => !!plugin.afterPull);
+    const requiresMaterializedSnapshots = plugins.some((plugin) => !!plugin.afterPull) ||
+        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)
@@ -657,227 +849,423 @@ export async function applyPullResponse(db, transport, handlers, options, pullSt
             response: responseToApply,
         });
     }
+    const subsById = new Map();
+    for (const s of options.subscriptions ?? [])
+        subsById.set(s.id, s);
     await db.transaction().execute(async (trx) => {
-        const desiredIds = new Set((options.subscriptions ?? []).map((s) => s.id));
-        // Remove local data for subscriptions that are no longer desired.
-        for (const row of existing) {
-            if (desiredIds.has(row.subscription_id))
-                continue;
-            // Clear data for this table matching the subscription's scopes
-            if (row.table) {
+        await removeUndesiredSubscriptions(trx, handlers, existing, options.subscriptions ?? [], stateId);
+    });
+    if (bootstrapApplyMode === 'per-subscription') {
+        for (const sub of responseToApply.subscriptions) {
+            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,
+                    transactionMode: bootstrapApplyMode,
+                    subscriptionIds: [sub.id],
+                    subscriptionCount: 1,
+                    durationMs: Math.max(0, Date.now() - transactionStartedAt),
+                });
+            }
+            catch (error) {
+                emitTrace(options.onTrace, {
+                    stage: 'apply:transaction:error',
+                    stateId,
+                    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;
+}
+function resolveBootstrapApplyMode(options, response, capabilities) {
+    const mode = options.bootstrapApplyMode ?? 'auto';
+    if (mode === 'single-transaction' || mode === 'per-subscription') {
+        return mode;
+    }
+    if (!response.subscriptions.some((sub) => sub.bootstrap)) {
+        return 'single-transaction';
+    }
+    if (capabilities?.preferredBootstrapApplyMode) {
+        return capabilities.preferredBootstrapApplyMode;
+    }
+    if (capabilities?.snapshotChunkReadMode === 'bytes' ||
+        capabilities?.gzipDecompressionMode === 'buffered') {
+        return 'per-subscription';
+    }
+    return 'single-transaction';
+}
+async function removeUndesiredSubscriptions(trx, handlers, existing, desiredSubscriptions, stateId) {
+    const desiredIds = new Set(desiredSubscriptions.map((subscription) => subscription.id));
+    for (const row of existing) {
+        if (desiredIds.has(row.subscription_id))
+            continue;
+        if (row.table) {
+            try {
+                const scopes = row.scopes_json
+                    ? typeof row.scopes_json === 'string'
+                        ? JSON.parse(row.scopes_json)
+                        : row.scopes_json
+                    : {};
+                await getClientHandlerOrThrow(handlers, row.table).clearAll({
+                    trx,
+                    scopes,
+                });
+            }
+            catch {
+                // ignore missing table 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(row.subscription_id)}
+    `.execute(trx);
+    }
+}
+async function readLatestSubscriptionCursor(trx, stateId, subscriptionId) {
+    const result = await sql `
+    select ${sql.ref('cursor')} as cursor
+    from ${sql.table('sync_subscription_state')}
+    where ${sql.ref('state_id')} = ${sql.val(stateId)}
+      and ${sql.ref('subscription_id')} = ${sql.val(subscriptionId)}
+    limit 1
+  `.execute(trx);
+    const raw = result.rows[0]?.cursor;
+    return typeof raw === 'number'
+        ? raw
+        : raw === null || raw === undefined
+            ? null
+            : Number(raw);
+}
+async function applySubscriptionResponse(args) {
+    const { trx, handlers, transport, options, stateId, existingById, subsById, sub, } = args;
+    const def = subsById.get(sub.id);
+    const prev = existingById.get(sub.id);
+    const prevCursorRaw = prev?.cursor;
+    const prevCursor = typeof prevCursorRaw === 'number'
+        ? prevCursorRaw
+        : prevCursorRaw === null || prevCursorRaw === undefined
+            ? null
+            : Number(prevCursorRaw);
+    const latestCursor = await readLatestSubscriptionCursor(trx, stateId, sub.id);
+    const effectiveCursor = prevCursor !== null &&
+        Number.isFinite(prevCursor) &&
+        latestCursor !== null &&
+        Number.isFinite(latestCursor)
+        ? Math.max(prevCursor, latestCursor)
+        : prevCursor !== null && Number.isFinite(prevCursor)
+            ? prevCursor
+            : latestCursor !== null && Number.isFinite(latestCursor)
+                ? latestCursor
+                : null;
+    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;
+    }
+    try {
+        if (sub.status === 'revoked') {
+            if (prev?.table) {
                 try {
-                    const scopes = row.scopes_json
-                        ? typeof row.scopes_json === 'string'
-                            ? JSON.parse(row.scopes_json)
-                            : row.scopes_json
-                        : {};
-                    await getClientHandlerOrThrow(handlers, row.table).clearAll({
+                    const scopes = parseScopeValuesJson(prev.scopes_json);
+                    await getClientHandlerOrThrow(handlers, prev.table).clearAll({
                         trx,
                         scopes,
                     });
                 }
                 catch {
-                    // ignore missing table handler
+                    // 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(row.subscription_id)}
-	      `.execute(trx);
-        }
-        const subsById = new Map();
-        for (const s of options.subscriptions ?? [])
-            subsById.set(s.id, s);
-        const latestStateRows = await sql `
-      select
-        ${sql.ref('subscription_id')} as subscription_id,
-        ${sql.ref('cursor')} as cursor
-      from ${sql.table('sync_subscription_state')}
-      where ${sql.ref('state_id')} = ${sql.val(stateId)}
-    `.execute(trx);
-        const latestCursorBySubscriptionId = new Map();
-        for (const row of latestStateRows.rows) {
-            const raw = row.cursor;
-            const cursor = typeof raw === 'number'
-                ? raw
-                : raw === null || raw === undefined
-                    ? null
-                    : Number(raw);
-            latestCursorBySubscriptionId.set(row.subscription_id, cursor);
+        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;
         }
-        for (const sub of responseToApply.subscriptions) {
-            const def = subsById.get(sub.id);
-            const prev = existingById.get(sub.id);
-            const prevCursorRaw = prev?.cursor;
-            const prevCursor = typeof prevCursorRaw === 'number'
-                ? prevCursorRaw
-                : prevCursorRaw === null || prevCursorRaw === undefined
-                    ? null
-                    : Number(prevCursorRaw);
-            const latestCursorRaw = latestCursorBySubscriptionId.get(sub.id);
-            const latestCursor = typeof latestCursorRaw === 'number'
-                ? latestCursorRaw
-                : latestCursorRaw === null || latestCursorRaw === undefined
-                    ? null
-                    : Number(latestCursorRaw);
-            const effectiveCursor = prevCursor !== null &&
-                Number.isFinite(prevCursor) &&
-                latestCursor !== null &&
-                Number.isFinite(latestCursor)
-                ? Math.max(prevCursor, latestCursor)
-                : prevCursor !== null && Number.isFinite(prevCursor)
-                    ? prevCursor
-                    : latestCursor !== null && Number.isFinite(latestCursor)
-                        ? latestCursor
-                        : null;
-            const staleIncrementalResponse = !sub.bootstrap &&
-                effectiveCursor !== null &&
-                sub.nextCursor < effectiveCursor;
-            // Guard against out-of-order duplicate pull responses from older requests.
-            if (staleIncrementalResponse) {
-                continue;
-            }
-            // Revoked: clear data and drop the subscription row.
-            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
-                    }
+        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,
+                    });
                 }
-                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);
-                latestCursorBySubscriptionId.delete(sub.id);
-                continue;
             }
-            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,
-                        });
-                    }
+            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,
+                    });
                 }
-                catch {
-                    // ignore missing handler
+                if (hasChunkRefs) {
+                    await applyChunkedSnapshot(transport, handler, trx, snapshot, sub.scopes, options.sha256, {
+                        stateId,
+                        subscriptionId: sub.id,
+                        onTrace: options.onTrace,
+                    });
                 }
-            }
-            // Apply snapshots (bootstrap mode)
-            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;
-                    // Call onSnapshotStart hook when starting a new snapshot
-                    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);
-                    }
-                    // Call onSnapshotEnd hook when snapshot is complete
-                    if (snapshot.isLastPage && handler.onSnapshotEnd) {
-                        await handler.onSnapshotEnd({
-                            trx,
-                            table: snapshot.table,
-                            scopes: sub.scopes,
-                        });
-                    }
+                else {
+                    await handler.applySnapshot({ trx }, snapshot);
                 }
-            }
-            else {
-                // Apply incremental changes
-                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,
+                if (snapshot.isLastPage && handler.onSnapshotEnd) {
+                    await handler.onSnapshotEnd({
+                        trx,
+                        table: snapshot.table,
+                        scopes: sub.scopes,
                     });
                 }
             }
-            // Persist subscription cursor + metadata.
-            // Use cached JSON serialization to avoid repeated stringification
-            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);
-            latestCursorBySubscriptionId.set(sub.id, sub.nextCursor);
         }
-    });
-    return responseToApply;
+        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),
+        });
+    }
+    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;
+    }
 }
 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