@abloatai/humans 0.65.0 → 0.66.0

package/dist/local/BaseSyncedStore.d.ts

@@ -676,7 +676,7 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      * with {@link Database.processDeltaBatch} — the lower-level local write this
      * eventually drives through `flushPendingDeltas`.
      */
-    protected applyDeltaFrame(deltas: SyncDelta[]): void;
+    protected applyDeltaFrame(deltas: SyncDelta[]): Promise<void>;
     /**
      * Per-delta bookkeeping + enqueue. Returns `true` when the delta was
      * pushed onto `pendingDeltas` (a regular batchable I/U/C/D delta that a

package/dist/local/BaseSyncedStore.js

@@ -877,7 +877,7 @@ export class BaseSyncedStore {
             getAllPoolIds: () => this.objectPool.getAllIds(),
             get bootstrapDeltaQueue() { return store.bootstrapDeltaQueue; },
             set bootstrapDeltaQueue(queue) { store.bootstrapDeltaQueue = queue; },
-            applyDeltaFrame: (deltas) => { this.applyDeltaFrame(deltas); },
+            applyDeltaFrame: (deltas) => { void this.applyDeltaFrame(deltas); },
         };
     }
     /** Apply bootstrap data to the {@link InstanceCache}, removing entities that are no longer present (ghost removal). Pool writes are delegated to {@link SyncClient}. */
@@ -1100,7 +1100,7 @@ export class BaseSyncedStore {
             onConnectionEvent: this.onConnectionEvent,
             updateSyncStatus: (updates) => { this.updateSyncStatus(updates); },
             processDeltaWithBatching: (delta) => { this.processDeltaWithBatching(delta); },
-            applyDeltaFrame: (deltas) => { this.applyDeltaFrame(deltas); },
+            applyDeltaFrame: (deltas) => this.applyDeltaFrame(deltas),
             handleBootstrapRequired: (hint) => { this.handleBootstrapRequired(hint); },
             handleBootstrapData: (data) => { this.handleBootstrapData(data); },
             performCredentialRefresh: () => this.performCredentialRefresh(),
@@ -1231,7 +1231,7 @@ export class BaseSyncedStore {
      * eventually drives through `flushPendingDeltas`.
      */
     applyDeltaFrame(deltas) {
-        deltaPipeline.applyDeltaFrame(this.deltaPipelineContext, deltas);
+        return deltaPipeline.persistDeltaFrame(this.deltaPipelineContext, deltas);
     }
     /**
      * Per-delta bookkeeping + enqueue. Returns `true` when the delta was

package/dist/local/sync/BootstrapFetcher.js

@@ -28,6 +28,19 @@ const PAGE_LIMIT = 5000;
 const MAX_PAGES_PER_MODEL = 200;
 /** How many model chunks a cold start fetches at once. */
 const CHUNK_CONCURRENCY = 3;
+/** Keep bootstrap URLs below common proxy limits when the subscribed group set grows. */
+function bootstrapRequest(baseUrl, params) {
+    const url = `${baseUrl}/sync/bootstrap?${params.toString()}`;
+    if (url.length <= 8_000)
+        return { url, method: 'GET' };
+    const syncGroups = params.getAll('syncGroups');
+    params.delete('syncGroups');
+    return {
+        url: `${baseUrl}/sync/bootstrap?${params.toString()}`,
+        method: 'POST',
+        body: JSON.stringify({ syncGroups }),
+    };
+}
 /**
  * The reason handed to `abort()` when a request is stopped deliberately —
  * superseded by a newer bootstrap, or abandoned because the bootstrap it
@@ -359,7 +372,7 @@ export class BootstrapFetcher {
         if (this.options.instantModels && this.options.instantModels.length > 0) {
             params.append('models', this.options.instantModels.join(','));
         }
-        const url = `${this.options.baseUrl}/sync/bootstrap?${params.toString()}`;
+        const request = bootstrapRequest(this.options.baseUrl, params);
         // If offline, try the cached bootstrap. Skipped for a scoped override: the
         // cache holds the full snapshot, which is not a valid answer to a subset
         // request; a scoped hydrate just soft-fails offline and retries on re-enter.
@@ -384,7 +397,7 @@ export class BootstrapFetcher {
                 code: 'bootstrap_offline_no_cache',
             });
         }
-        this.runtime.logger.info('Fetching fresh bootstrap data', { url });
+        this.runtime.logger.info('Fetching fresh bootstrap data', { url: request.url });
         const lane = syncGroupsOverride ? 'scoped' : 'bootstrap';
         // Chunk a COLD start by model: each instant model is its own request, so
         // one giant model can't make the whole snapshot undeliverable, and a
@@ -401,7 +414,7 @@ export class BootstrapFetcher {
         try {
             const data = chunked
                 ? await this.fetchChunkedBootstrap(instantModels, this.options.syncGroups)
-                : await this.fetchWithRetries(url, lane);
+                : await this.fetchWithRetries(request, lane);
             this.runtime.logger.info('Bootstrap data fetched', {
                 type: data.type,
                 lastSyncId: data.lastSyncId,
@@ -448,12 +461,12 @@ export class BootstrapFetcher {
      * (5xx, 429, timeouts, network blips) consume attempts. A cancellation is
      * deliberate and therefore non-retryable — it leaves through the same gate.
      */
-    async fetchWithRetries(url, lane) {
+    async fetchWithRetries(request, lane) {
         let lastError = null;
         const capacityDeadline = Date.now() + this.options.fetchTimeout;
         for (let attempt = 0; attempt < this.options.maxRetries;) {
             try {
-                return await this.fetchOnce(url, lane);
+                return await this.fetchOnce(request, lane);
             }
             catch (error) {
                 // SessionError should NOT be retried - the session is invalid and needs re-authentication
@@ -539,8 +552,8 @@ export class BootstrapFetcher {
                         params.append('limit', String(PAGE_LIMIT));
                         if (cursor !== undefined)
                             params.append('cursor', cursor);
-                        const url = `${this.options.baseUrl}/sync/bootstrap?${params.toString()}`;
-                        const data = await this.fetchWithRetries(url, 'bootstrap');
+                        const request = bootstrapRequest(this.options.baseUrl, params);
+                        const data = await this.fetchWithRetries(request, 'bootstrap');
                         chunks.push(data);
                         if (data.nextCursor === undefined)
                             break;
@@ -576,7 +589,7 @@ export class BootstrapFetcher {
         if (this.options.instantModels && this.options.instantModels.length > 0) {
             params.append('models', this.options.instantModels.join(','));
         }
-        const url = `${this.options.baseUrl}/sync/bootstrap?${params.toString()}`;
+        const request = bootstrapRequest(this.options.baseUrl, params);
         // Note: ETag caching is deliberately app-side, not SDK-side. The server
         // still returns an ETag on responses, which is captured below and
         // forwarded to callers via BootstrapFetchResult.etag — apps that want
@@ -587,15 +600,16 @@ export class BootstrapFetcher {
         const controller = new AbortController();
         this.activeControllers.set(controller, 'bootstrap');
         try {
-            return await this.fetchWithETagUsing(url, headers, controller);
+            return await this.fetchWithETagUsing(request, headers, controller);
         }
         finally {
             this.activeControllers.delete(controller);
         }
     }
-    async fetchWithETagUsing(url, headers, controller) {
-        const res = await fetch(url, {
-            method: 'GET',
+    async fetchWithETagUsing(request, headers, controller) {
+        const res = await fetch(request.url, {
+            method: request.method,
+            body: request.body,
             headers,
             signal: controller.signal,
         });
@@ -726,17 +740,17 @@ export class BootstrapFetcher {
      * registry) — chunk requests run through here concurrently and must
      * not cancel each other.
      */
-    async fetchOnce(url, lane) {
+    async fetchOnce(request, lane) {
         const controller = new AbortController();
         this.activeControllers.set(controller, lane);
         try {
-            return await this.fetchOnceWith(url, controller);
+            return await this.fetchOnceWith(request, controller);
         }
         finally {
             this.activeControllers.delete(controller);
         }
     }
-    async fetchOnceWith(url, controller) {
+    async fetchOnceWith(request, controller) {
         const timeoutId = setTimeout(() => {
             this.runtime.observability.breadcrumb('Bootstrap fetch timeout', 'sync.bootstrap', 'warning', {
                 timeoutMs: this.options.fetchTimeout,
@@ -745,8 +759,9 @@ export class BootstrapFetcher {
         }, this.options.fetchTimeout);
         let response;
         try {
-            response = await fetch(url, {
-                method: 'GET',
+            response = await fetch(request.url, {
+                method: request.method,
+                body: request.body,
                 headers: withAuthHeaders(this.options.getAuthToken, {
                     'Content-Type': 'application/json',
                     'Cache-Control': 'no-cache, no-store, must-revalidate',

package/dist/local/sync/SyncWebSocket.d.ts

@@ -62,6 +62,7 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      * the state itself lives in {@link SyncCursor}.
      */
     private readonly cursor;
+    private catchUp;
     constructor(options: SyncWebSocketOptions);
     /** The persisted resume position, sent on the upgrade URL. */
     protected resumeCursor(): string;
@@ -121,6 +122,12 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      * Public wrapper for sending ack from outside the class
      */
     acknowledge(syncId: number): void;
+    /** Publish completion only after the store's chunk-persistence lane drains. */
+    completeCatchUp(payload: {
+        exchangeId: string;
+        currentSyncId: number;
+        chunks: number;
+    }): void;
     /**
      * Stop the periodic catchup interval
      */
@@ -160,6 +167,9 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      * of the batch).
      */
     protected handleSyncResponse(rawPayload: unknown): void;
+    protected handleCatchUpBegin(rawPayload: unknown): void;
+    protected handleCatchUpChunk(rawPayload: unknown): void;
+    protected handleCatchUpEnd(rawPayload: unknown): void;
     /**
      * Handle bootstrap response from server
      */

package/dist/local/sync/SyncWebSocket.js

@@ -38,6 +38,7 @@ export class SyncWebSocket extends WsTransport {
      * the state itself lives in {@link SyncCursor}.
      */
     cursor;
+    catchUp = null;
     constructor(options) {
         super({
             ...options,
@@ -221,6 +222,10 @@ export class SyncWebSocket extends WsTransport {
     acknowledge(syncId) {
         this.sendAck(syncId);
     }
+    /** Publish completion only after the store's chunk-persistence lane drains. */
+    completeCatchUp(payload) {
+        this.emit('catchup_complete', payload);
+    }
     /**
      * Stop the periodic catchup interval
      */
@@ -415,6 +420,44 @@ export class SyncWebSocket extends WsTransport {
             this.cursor.syncCursor = payload.cursor;
         }
     }
+    handleCatchUpBegin(rawPayload) {
+        if (!isRecord(rawPayload))
+            return;
+        const { exchangeId, fromSyncId, currentSyncId } = rawPayload;
+        if (typeof exchangeId !== 'string' || !Number.isSafeInteger(fromSyncId) || !Number.isSafeInteger(currentSyncId))
+            return;
+        this.catchUp = { exchangeId, currentSyncId: currentSyncId, nextSequence: 0 };
+        this.emit('catchup_begin', { exchangeId, fromSyncId: fromSyncId, currentSyncId: currentSyncId });
+    }
+    handleCatchUpChunk(rawPayload) {
+        if (!isRecord(rawPayload) || !this.catchUp)
+            return;
+        const { exchangeId, sequence, position, deltas } = rawPayload;
+        if (exchangeId !== this.catchUp.exchangeId || sequence !== this.catchUp.nextSequence
+            || !Number.isSafeInteger(position) || position > this.catchUp.currentSyncId
+            || !Array.isArray(deltas))
+            return;
+        const normalized = [];
+        for (const raw of deltas) {
+            const delta = this.normalizeWireDelta(raw);
+            if (delta)
+                normalized.push(delta);
+        }
+        if (normalized.length !== deltas.length)
+            return;
+        this.catchUp.nextSequence++;
+        this.emit('catchup_chunk', { exchangeId, sequence, position, deltas: normalized });
+    }
+    handleCatchUpEnd(rawPayload) {
+        if (!isRecord(rawPayload) || !this.catchUp)
+            return;
+        const { exchangeId, currentSyncId, chunks } = rawPayload;
+        if (exchangeId !== this.catchUp.exchangeId || currentSyncId !== this.catchUp.currentSyncId
+            || chunks !== this.catchUp.nextSequence)
+            return;
+        this.catchUp = null;
+        this.emit('catchup_end', { exchangeId, currentSyncId, chunks });
+    }
     /**
      * Handle bootstrap response from server
      */

package/dist/local/sync/deltaPipeline.d.ts

@@ -118,8 +118,10 @@ export declare function enqueueDelta(ctx: DeltaPipelineContext, delta: SyncDelta
 }): boolean;
 /** Debounce a flush for live single-delta traffic. */
 export declare function scheduleDeltaFlush(ctx: DeltaPipelineContext): void;
-/** Apply an authoritative delta frame as one atomic flush. */
+/** Apply an authoritative legacy frame without exposing its persistence promise. */
 export declare function applyDeltaFrame(ctx: DeltaPipelineContext, deltas: SyncDelta[]): void;
+/** Persist one resumable chunk before its raw tail position may advance. */
+export declare function persistDeltaFrame(ctx: DeltaPipelineContext, deltas: SyncDelta[]): Promise<void>;
 /**
  * Flushes the queued deltas: deduplicates them, applies custom-entity deltas
  * straight to the pool, writes the rest to the local store and then the pool,

package/dist/local/sync/deltaPipeline.js

@@ -164,8 +164,12 @@ export function scheduleDeltaFlush(ctx) {
         }, ctx.smartSyncOptions.batchingDelay);
     }
 }
-/** Apply an authoritative delta frame as one atomic flush. */
+/** Apply an authoritative legacy frame without exposing its persistence promise. */
 export function applyDeltaFrame(ctx, deltas) {
+    void persistDeltaFrame(ctx, deltas).catch(ctx.handleFlushError);
+}
+/** Persist one resumable chunk before its raw tail position may advance. */
+export async function persistDeltaFrame(ctx, deltas) {
     let enqueuedAny = false;
     for (const delta of deltas) {
         if (enqueueDelta(ctx, delta, { authoritative: true }))
@@ -177,7 +181,7 @@ export function applyDeltaFrame(ctx, deltas) {
         clearTimeout(ctx.batchTimer);
         ctx.batchTimer = null;
     }
-    void ctx.flushPendingDeltas().catch(ctx.handleFlushError);
+    await ctx.flushPendingDeltas();
 }
 /**
  * Flushes the queued deltas: deduplicates them, applies custom-entity deltas

package/dist/local/sync/socketEventWiring.d.ts

@@ -20,7 +20,7 @@ export interface SocketEventHost<TCollaboration extends EventMap<TCollaboration>
     onConnectionEvent?: (event: string) => void;
     updateSyncStatus(updates: Partial<SyncStatus>): void;
     processDeltaWithBatching(delta: SyncDelta): void;
-    applyDeltaFrame(deltas: SyncDelta[]): void;
+    applyDeltaFrame(deltas: SyncDelta[]): Promise<void>;
     handleBootstrapRequired(hint: BootstrapHint): void;
     handleBootstrapData(data: BootstrapDataEvent): void;
     performCredentialRefresh(): Promise<'refreshed' | 'session_error' | 'network_error'>;

package/dist/local/sync/socketEventWiring.js

@@ -35,7 +35,27 @@ export function wireSocketEvents(deps) {
         // A catch-up/reconnect frame is already complete — apply it as ONE
         // atomic flush so the gallery re-renders once, not once per 50-delta
         // chunk. See `applyDeltaFrame`.
-        deps.applyDeltaFrame(deltas);
+        void deps.applyDeltaFrame(deltas).catch((error) => {
+            deps.updateSyncStatus({ state: 'error', error: error instanceof Error ? error : new Error(String(error)) });
+        });
+    });
+    let catchUpLane = Promise.resolve();
+    const onCatchUpChunk = deps.syncWebSocket.subscribe('catchup_chunk', (chunk) => {
+        catchUpLane = catchUpLane.then(async () => {
+            await deps.applyDeltaFrame(chunk.deltas);
+            // The raw position covers filtered rows too. Advance only after this
+            // chunk's visible rows are durable; replay is therefore idempotent.
+            deps.syncWebSocket.acknowledge(chunk.position);
+        });
+        void catchUpLane.catch((error) => {
+            deps.updateSyncStatus({ state: 'error', error: error instanceof Error ? error : new Error(String(error)) });
+        });
+    });
+    const onCatchUpEnd = deps.syncWebSocket.subscribe('catchup_end', (end) => {
+        void catchUpLane.then(() => {
+            deps.syncWebSocket.acknowledge(end.currentSyncId);
+            deps.syncWebSocket.completeCatchUp(end);
+        }).catch(() => undefined);
     });
     // Bootstrap events
     const onBootstrapRequired = deps.syncWebSocket.subscribe('bootstrap_required', (hint) => { deps.handleBootstrapRequired(hint); });
@@ -122,5 +142,5 @@ export function wireSocketEvents(deps) {
         deps.runtime.logger.debug('[BaseSyncedStore] WebSocket reconnection gave up', { attempts });
         deps.updateSyncStatus({ state: 'reconnecting' });
     });
-    deps.disposers.push(onConnected, onDisconnected, onReconnecting, onDelta, onDeltaBatch, onBootstrapRequired, onBootstrapData, onError, onSessionError, onHandshakeFailed, onReconnectFailed, () => { deps.areaOfInterest.dispose(); });
+    deps.disposers.push(onConnected, onDisconnected, onReconnecting, onDelta, onDeltaBatch, onCatchUpChunk, onCatchUpEnd, onBootstrapRequired, onBootstrapData, onError, onSessionError, onHandshakeFailed, onReconnectFailed, () => { deps.areaOfInterest.dispose(); });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/humans",
-  "version": "0.65.0",
+  "version": "0.66.0",
   "description": "The optional human-facing local-state package for Ablo: presence, live queries, and React bindings.",
   "license": "Apache-2.0",
   "type": "module",
@@ -85,7 +85,7 @@
     "directory": "packages/humans"
   },
   "dependencies": {
-    "@abloatai/transaction": "0.65.0",
+    "@abloatai/transaction": "0.66.0",
     "events": "^3.3.0",
     "mobx": "^6.13.7",
     "uuid": "^11.1.0",

package/src/local/BaseSyncedStore.ts

@@ -1247,7 +1247,7 @@ export class BaseSyncedStore<
       getAllPoolIds: () => this.objectPool.getAllIds(),
       get bootstrapDeltaQueue() { return store.bootstrapDeltaQueue; },
       set bootstrapDeltaQueue(queue) { store.bootstrapDeltaQueue = queue; },
-      applyDeltaFrame: (deltas) => { this.applyDeltaFrame(deltas); },
+      applyDeltaFrame: (deltas) => { void this.applyDeltaFrame(deltas); },
     };
   }
 
@@ -1495,7 +1495,7 @@ export class BaseSyncedStore<
       onConnectionEvent: this.onConnectionEvent,
       updateSyncStatus: (updates) => { this.updateSyncStatus(updates); },
       processDeltaWithBatching: (delta) => { this.processDeltaWithBatching(delta); },
-      applyDeltaFrame: (deltas) => { this.applyDeltaFrame(deltas); },
+      applyDeltaFrame: (deltas) => this.applyDeltaFrame(deltas),
       handleBootstrapRequired: (hint) => { this.handleBootstrapRequired(hint); },
       handleBootstrapData: (data) => { this.handleBootstrapData(data); },
       performCredentialRefresh: () => this.performCredentialRefresh(),
@@ -1636,8 +1636,8 @@ export class BaseSyncedStore<
    * with {@link Database.processDeltaBatch} — the lower-level local write this
    * eventually drives through `flushPendingDeltas`.
    */
-  protected applyDeltaFrame(deltas: SyncDelta[]): void {
-    deltaPipeline.applyDeltaFrame(this.deltaPipelineContext, deltas);
+  protected applyDeltaFrame(deltas: SyncDelta[]): Promise<void> {
+    return deltaPipeline.persistDeltaFrame(this.deltaPipelineContext, deltas);
   }
   /**
    * Per-delta bookkeeping + enqueue. Returns `true` when the delta was

package/src/local/sync/BootstrapFetcher.ts

@@ -134,6 +134,19 @@ const MAX_PAGES_PER_MODEL = 200;
 /** How many model chunks a cold start fetches at once. */
 const CHUNK_CONCURRENCY = 3;
 
+/** Keep bootstrap URLs below common proxy limits when the subscribed group set grows. */
+function bootstrapRequest(baseUrl: string, params: URLSearchParams): { url: string; method: 'GET' | 'POST'; body?: string } {
+  const url = `${baseUrl}/sync/bootstrap?${params.toString()}`;
+  if (url.length <= 8_000) return { url, method: 'GET' };
+  const syncGroups = params.getAll('syncGroups');
+  params.delete('syncGroups');
+  return {
+    url: `${baseUrl}/sync/bootstrap?${params.toString()}`,
+    method: 'POST',
+    body: JSON.stringify({ syncGroups }),
+  };
+}
+
 /**
  * Which cancellation lane a request belongs to. Cancellation targets one lane
  * at a time, so superseding a cold-start bootstrap cannot take down a scoped
@@ -526,7 +539,7 @@ export class BootstrapFetcher {
       params.append('models', this.options.instantModels.join(','));
     }
 
-    const url = `${this.options.baseUrl}/sync/bootstrap?${params.toString()}`;
+    const request = bootstrapRequest(this.options.baseUrl, params);
 
     // If offline, try the cached bootstrap. Skipped for a scoped override: the
     // cache holds the full snapshot, which is not a valid answer to a subset
@@ -554,7 +567,7 @@ export class BootstrapFetcher {
       });
     }
 
-    this.runtime.logger.info('Fetching fresh bootstrap data', { url });
+    this.runtime.logger.info('Fetching fresh bootstrap data', { url: request.url });
 
     const lane: CancelLane = syncGroupsOverride ? 'scoped' : 'bootstrap';
 
@@ -575,7 +588,7 @@ export class BootstrapFetcher {
     try {
       const data = chunked
         ? await this.fetchChunkedBootstrap(instantModels, this.options.syncGroups)
-        : await this.fetchWithRetries(url, lane);
+        : await this.fetchWithRetries(request, lane);
 
       this.runtime.logger.info('Bootstrap data fetched', {
         type: data.type,
@@ -628,12 +641,12 @@ export class BootstrapFetcher {
    * (5xx, 429, timeouts, network blips) consume attempts. A cancellation is
    * deliberate and therefore non-retryable — it leaves through the same gate.
    */
-  private async fetchWithRetries(url: string, lane: CancelLane): Promise<BootstrapData> {
+  private async fetchWithRetries(request: ReturnType<typeof bootstrapRequest>, lane: CancelLane): Promise<BootstrapData> {
     let lastError: Error | null = null;
     const capacityDeadline = Date.now() + this.options.fetchTimeout;
     for (let attempt = 0; attempt < this.options.maxRetries;) {
       try {
-        return await this.fetchOnce(url, lane);
+        return await this.fetchOnce(request, lane);
       } catch (error) {
         // SessionError should NOT be retried - the session is invalid and needs re-authentication
         if (AbloSessionError.isSessionError(error)) {
@@ -740,8 +753,8 @@ export class BootstrapFetcher {
             params.append('models', model);
             params.append('limit', String(PAGE_LIMIT));
             if (cursor !== undefined) params.append('cursor', cursor);
-            const url = `${this.options.baseUrl}/sync/bootstrap?${params.toString()}`;
-            const data = await this.fetchWithRetries(url, 'bootstrap');
+            const request = bootstrapRequest(this.options.baseUrl, params);
+            const data = await this.fetchWithRetries(request, 'bootstrap');
             chunks.push(data);
             if (data.nextCursor === undefined) break;
             cursor = data.nextCursor;
@@ -781,7 +794,7 @@ export class BootstrapFetcher {
     if (this.options.instantModels && this.options.instantModels.length > 0) {
       params.append('models', this.options.instantModels.join(','));
     }
-    const url = `${this.options.baseUrl}/sync/bootstrap?${params.toString()}`;
+    const request = bootstrapRequest(this.options.baseUrl, params);
 
     // Note: ETag caching is deliberately app-side, not SDK-side. The server
     // still returns an ETag on responses, which is captured below and
@@ -799,19 +812,20 @@ export class BootstrapFetcher {
     const controller = new AbortController();
     this.activeControllers.set(controller, 'bootstrap');
     try {
-      return await this.fetchWithETagUsing(url, headers, controller);
+      return await this.fetchWithETagUsing(request, headers, controller);
     } finally {
       this.activeControllers.delete(controller);
     }
   }
 
   private async fetchWithETagUsing(
-    url: string,
+    request: ReturnType<typeof bootstrapRequest>,
     headers: Record<string, string>,
     controller: AbortController,
   ): Promise<BootstrapFetchResult> {
-    const res = await fetch(url, {
-      method: 'GET',
+    const res = await fetch(request.url, {
+      method: request.method,
+      body: request.body,
       headers,
       signal: controller.signal,
     });
@@ -973,17 +987,17 @@ export class BootstrapFetcher {
    * registry) — chunk requests run through here concurrently and must
    * not cancel each other.
    */
-  private async fetchOnce(url: string, lane: CancelLane): Promise<BootstrapData> {
+  private async fetchOnce(request: ReturnType<typeof bootstrapRequest>, lane: CancelLane): Promise<BootstrapData> {
     const controller = new AbortController();
     this.activeControllers.set(controller, lane);
     try {
-      return await this.fetchOnceWith(url, controller);
+      return await this.fetchOnceWith(request, controller);
     } finally {
       this.activeControllers.delete(controller);
     }
   }
 
-  private async fetchOnceWith(url: string, controller: AbortController): Promise<BootstrapData> {
+  private async fetchOnceWith(request: ReturnType<typeof bootstrapRequest>, controller: AbortController): Promise<BootstrapData> {
     const timeoutId = setTimeout(() => {
       this.runtime.observability.breadcrumb('Bootstrap fetch timeout', 'sync.bootstrap', 'warning', {
         timeoutMs: this.options.fetchTimeout,
@@ -998,8 +1012,9 @@ export class BootstrapFetcher {
 
     let response: Response;
     try {
-      response = await fetch(url, {
-        method: 'GET',
+      response = await fetch(request.url, {
+        method: request.method,
+        body: request.body,
 	        headers: withAuthHeaders(this.options.getAuthToken, {
 	          'Content-Type': 'application/json',
 	          'Cache-Control': 'no-cache, no-store, must-revalidate',

package/src/local/sync/SyncWebSocket.ts

@@ -110,6 +110,7 @@ export class SyncWebSocket<
    * the state itself lives in {@link SyncCursor}.
    */
   private readonly cursor: SyncCursor;
+  private catchUp: { exchangeId: string; currentSyncId: number; nextSequence: number } | null = null;
 
   constructor(options: SyncWebSocketOptions) {
     super({
@@ -318,6 +319,11 @@ export class SyncWebSocket<
     this.sendAck(syncId);
   }
 
+  /** Publish completion only after the store's chunk-persistence lane drains. */
+  completeCatchUp(payload: { exchangeId: string; currentSyncId: number; chunks: number }): void {
+    this.emit('catchup_complete', payload);
+  }
+
   /**
    * Stop the periodic catchup interval
    */
@@ -548,6 +554,39 @@ export class SyncWebSocket<
     }
   }
 
+  protected override handleCatchUpBegin(rawPayload: unknown): void {
+    if (!isRecord(rawPayload)) return;
+    const { exchangeId, fromSyncId, currentSyncId } = rawPayload;
+    if (typeof exchangeId !== 'string' || !Number.isSafeInteger(fromSyncId) || !Number.isSafeInteger(currentSyncId)) return;
+    this.catchUp = { exchangeId, currentSyncId: currentSyncId as number, nextSequence: 0 };
+    this.emit('catchup_begin', { exchangeId, fromSyncId: fromSyncId as number, currentSyncId: currentSyncId as number });
+  }
+
+  protected override handleCatchUpChunk(rawPayload: unknown): void {
+    if (!isRecord(rawPayload) || !this.catchUp) return;
+    const { exchangeId, sequence, position, deltas } = rawPayload;
+    if (exchangeId !== this.catchUp.exchangeId || sequence !== this.catchUp.nextSequence
+      || !Number.isSafeInteger(position) || (position as number) > this.catchUp.currentSyncId
+      || !Array.isArray(deltas)) return;
+    const normalized: SyncDelta[] = [];
+    for (const raw of deltas) {
+      const delta = this.normalizeWireDelta(raw);
+      if (delta) normalized.push(delta);
+    }
+    if (normalized.length !== deltas.length) return;
+    this.catchUp.nextSequence++;
+    this.emit('catchup_chunk', { exchangeId, sequence, position, deltas: normalized });
+  }
+
+  protected override handleCatchUpEnd(rawPayload: unknown): void {
+    if (!isRecord(rawPayload) || !this.catchUp) return;
+    const { exchangeId, currentSyncId, chunks } = rawPayload;
+    if (exchangeId !== this.catchUp.exchangeId || currentSyncId !== this.catchUp.currentSyncId
+      || chunks !== this.catchUp.nextSequence) return;
+    this.catchUp = null;
+    this.emit('catchup_end', { exchangeId, currentSyncId, chunks });
+  }
+
   /**
    * Handle bootstrap response from server
    */

package/src/local/sync/deltaPipeline.ts

@@ -282,8 +282,13 @@ export function scheduleDeltaFlush(ctx: DeltaPipelineContext): void {
   }
 }
 
-/** Apply an authoritative delta frame as one atomic flush. */
+/** Apply an authoritative legacy frame without exposing its persistence promise. */
 export function applyDeltaFrame(ctx: DeltaPipelineContext, deltas: SyncDelta[]): void {
+  void persistDeltaFrame(ctx, deltas).catch(ctx.handleFlushError);
+}
+
+/** Persist one resumable chunk before its raw tail position may advance. */
+export async function persistDeltaFrame(ctx: DeltaPipelineContext, deltas: SyncDelta[]): Promise<void> {
   let enqueuedAny = false;
   for (const delta of deltas) {
     if (enqueueDelta(ctx, delta, { authoritative: true })) enqueuedAny = true;
@@ -293,7 +298,7 @@ export function applyDeltaFrame(ctx: DeltaPipelineContext, deltas: SyncDelta[]):
     clearTimeout(ctx.batchTimer);
     ctx.batchTimer = null;
   }
-  void ctx.flushPendingDeltas().catch(ctx.handleFlushError);
+  await ctx.flushPendingDeltas();
 }
 
 /**

package/src/local/sync/socketEventWiring.ts

@@ -27,7 +27,7 @@ export interface SocketEventHost<TCollaboration extends EventMap<TCollaboration>
   onConnectionEvent?: (event: string) => void;
   updateSyncStatus(updates: Partial<SyncStatus>): void;
   processDeltaWithBatching(delta: SyncDelta): void;
-  applyDeltaFrame(deltas: SyncDelta[]): void;
+  applyDeltaFrame(deltas: SyncDelta[]): Promise<void>;
   handleBootstrapRequired(hint: BootstrapHint): void;
   handleBootstrapData(data: BootstrapDataEvent): void;
   performCredentialRefresh(): Promise<'refreshed' | 'session_error' | 'network_error'>;
@@ -77,7 +77,28 @@ export function wireSocketEvents<TCollaboration extends EventMap<TCollaboration>
       // A catch-up/reconnect frame is already complete — apply it as ONE
       // atomic flush so the gallery re-renders once, not once per 50-delta
       // chunk. See `applyDeltaFrame`.
-      deps.applyDeltaFrame(deltas);
+      void deps.applyDeltaFrame(deltas).catch((error: unknown) => {
+        deps.updateSyncStatus({ state: 'error', error: error instanceof Error ? error : new Error(String(error)) });
+      });
+    });
+
+    let catchUpLane = Promise.resolve();
+    const onCatchUpChunk = deps.syncWebSocket.subscribe('catchup_chunk', (chunk) => {
+      catchUpLane = catchUpLane.then(async () => {
+        await deps.applyDeltaFrame(chunk.deltas);
+        // The raw position covers filtered rows too. Advance only after this
+        // chunk's visible rows are durable; replay is therefore idempotent.
+        deps.syncWebSocket.acknowledge(chunk.position);
+      });
+      void catchUpLane.catch((error: unknown) => {
+        deps.updateSyncStatus({ state: 'error', error: error instanceof Error ? error : new Error(String(error)) });
+      });
+    });
+    const onCatchUpEnd = deps.syncWebSocket.subscribe('catchup_end', (end) => {
+      void catchUpLane.then(() => {
+        deps.syncWebSocket.acknowledge(end.currentSyncId);
+        deps.syncWebSocket.completeCatchUp(end);
+      }).catch(() => undefined);
     });
 
     // Bootstrap events
@@ -181,7 +202,7 @@ export function wireSocketEvents<TCollaboration extends EventMap<TCollaboration>
 
     deps.disposers.push(
       onConnected, onDisconnected, onReconnecting,
-      onDelta, onDeltaBatch, onBootstrapRequired,
+      onDelta, onDeltaBatch, onCatchUpChunk, onCatchUpEnd, onBootstrapRequired,
       onBootstrapData,
       onError, onSessionError, onHandshakeFailed, onReconnectFailed,
       () => { deps.areaOfInterest.dispose(); },