@syncular/client 0.0.6-212 → 0.0.6-219

package/dist/pull-engine.d.ts

@@ -1,7 +1,7 @@
 /**
  * @syncular/client - Sync pull engine
  */
-import type { SyncChange, SyncPullRequest, SyncPullResponse, SyncSubscriptionRequest, SyncTransport } from '@syncular/core';
+import { type SyncBootstrapApplyMode, type SyncChange, type SyncPullRequest, type SyncPullResponse, type SyncSubscriptionRequest, type SyncTransport } from '@syncular/core';
 import { type Kysely, type Transaction } from 'kysely';
 import { type ClientHandlerCollection } from './handlers/collection';
 import type { SyncClientPlugin } from './plugins/types';
@@ -20,6 +20,17 @@ export interface SyncPullOnceOptions {
     maxSnapshotPages?: number;
     dedupeRows?: boolean;
     stateId?: string;
+    /**
+     * Controls how bootstrap snapshot results are committed to the local DB.
+     * - `single-transaction`: all subscriptions in one DB transaction
+     * - `per-subscription`: each subscription in its own DB transaction
+     * - `auto`: choose a sensible runtime-specific default
+     *
+     * `per-subscription` makes early subscriptions visible sooner and prevents a
+     * later large bootstrap table from hiding already-applied tables behind one
+     * long-running transaction.
+     */
+    bootstrapApplyMode?: 'auto' | SyncBootstrapApplyMode;
     /**
      * Custom SHA-256 hash function for snapshot chunk integrity verification.
      * Provide this on platforms where `crypto.subtle` is unavailable (e.g. React Native).

package/dist/pull-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pull-engine.d.ts","sourceRoot":"","sources":["../src/pull-engine.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAGV,UAAU,EACV,eAAe,EACf,gBAAgB,EAGhB,uBAAuB,EACvB,aAAa,EACd,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,KAAK,MAAM,EAAO,KAAK,WAAW,EAAE,MAAM,QAAQ,CAAC;AAC5D,OAAO,EACL,KAAK,uBAAuB,EAE7B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EACV,gBAAgB,EAEjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,YAAY,EAAE,0BAA0B,EAAE,MAAM,UAAU,CAAC;AA4oBzE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC7B;;;OAGG;IACH,aAAa,EAAE,KAAK,CAAC,IAAI,CAAC,uBAAuB,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACjD;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,eAAe,CAAC;IACzB,QAAQ,EAAE,0BAA0B,EAAE,CAAC;IACvC,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAAC;IACtD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,EAAE,SAAS,YAAY,EAC5D,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC,EACd,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,oBAAoB,CAAC,CAuC/B;AAED,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,oBAAoB,EAC/B,QAAQ,EAAE,gBAAgB,GACzB,oBAAoB,CA2DtB;AAED,wBAAsB,6BAA6B,CAAC,EAAE,SAAS,YAAY,EACzE,QAAQ,EAAE,uBAAuB,CAAC,EAAE,CAAC,EACrC,GAAG,EAAE,WAAW,CAAC,EAAE,CAAC,EACpB,IAAI,EAAE;IACJ,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,GACA,OAAO,CAAC,IAAI,CAAC,CAkCf;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,EAAE,SAAS,YAAY,EAC7D,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC,EACd,SAAS,EAAE,aAAa,EACxB,QAAQ,EAAE,uBAAuB,CAAC,EAAE,CAAC,EACrC,OAAO,EAAE,mBAAmB,EAC5B,SAAS,EAAE,oBAAoB,EAC/B,WAAW,EAAE,gBAAgB,GAC5B,OAAO,CAAC,gBAAgB,CAAC,CAyQ3B;AAED,wBAAsB,YAAY,CAAC,EAAE,SAAS,YAAY,EACxD,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC,EACd,SAAS,EAAE,aAAa,EACxB,QAAQ,EAAE,uBAAuB,CAAC,EAAE,CAAC,EACrC,OAAO,EAAE,mBAAmB,EAC5B,iBAAiB,CAAC,EAAE,oBAAoB,GACvC,OAAO,CAAC,gBAAgB,CAAC,CAe3B"}
+{"version":3,"file":"pull-engine.d.ts","sourceRoot":"","sources":["../src/pull-engine.ts"],"names":[],"mappings":"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"}

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();
@@ -250,6 +244,20 @@ async function readAllBytesFromStream(stream) {
     return bytes;
 }
 async function materializeSnapshotChunkRows(transport, request, expectedHash, sha256Override) {
+    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}`);
+            }
+        }
+        return decodeSnapshotRows(bytes);
+    }
     const rawStream = await fetchSnapshotChunkStream(transport, request);
     const decodedStream = await maybeGunzipStream(rawStream);
     let streamForDecode = decodedStream;
@@ -645,7 +653,9 @@ 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)
         : rawResponse;
@@ -657,219 +667,253 @@ 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) {
-                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 removeUndesiredSubscriptions(trx, handlers, existing, options.subscriptions ?? [], stateId);
+    });
+    if (bootstrapApplyMode === 'per-subscription') {
+        for (const sub of responseToApply.subscriptions) {
+            await db.transaction().execute(async (trx) => {
+                await applySubscriptionResponse({
+                    trx,
+                    handlers,
+                    transport,
+                    options,
+                    stateId,
+                    existingById,
+                    subsById,
+                    sub,
+                });
+            });
+        }
+    }
+    else {
+        await db.transaction().execute(async (trx) => {
+            for (const sub of responseToApply.subscriptions) {
+                await applySubscriptionResponse({
+                    trx,
+                    handlers,
+                    transport,
+                    options,
+                    stateId,
+                    existingById,
+                    subsById,
+                    sub,
+                });
+            }
+        });
+    }
+    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,
+                });
             }
-            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')}
+            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);
-        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);
-        }
-        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;
+    }
+}
+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;
+    if (staleIncrementalResponse) {
+        return;
+    }
+    if (sub.status === 'revoked') {
+        if (prev?.table) {
+            try {
+                const scopes = parseScopeValuesJson(prev.scopes_json);
+                await getClientHandlerOrThrow(handlers, prev.table).clearAll({
+                    trx,
+                    scopes,
+                });
             }
-            // 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
-                    }
-                }
-                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;
+            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,
-                        });
-                    }
-                }
-                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,
+                });
             }
-            // 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,
-                        });
-                    }
-                }
+        }
+        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 {
-                // 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,
-                    });
-                }
+                await handler.applySnapshot({ trx }, snapshot);
+            }
+            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);
 }
 export async function syncPullOnce(db, transport, handlers, options, pullStateOverride) {
     const pullState = pullStateOverride ?? (await buildPullRequest(db, options));