@abloatai/humans 0.65.0 → 0.66.1

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.1",
   "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.1",
     "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/SyncClient.ts

@@ -106,6 +106,11 @@ export class SyncClient extends EventEmitter {
    * {@link SyncClient.getEchoMetrics} exposes its counters.
    */
   private readonly echoTracker = new UnconfirmedWrites();
+  private readonly pendingDeletes = new Set<string>();
+
+  isDeletePending(id: string): boolean {
+    return this.pendingDeletes.has(id);
+  }
 
   // Connection state
   private connectionState: 'connected' | 'disconnected' | 'connecting' = 'disconnected';
@@ -312,7 +317,14 @@ export class SyncClient extends EventEmitter {
             // Guard: if the model was disposed (e.g. by a concurrent DELETE rollback or
             // cascade), don't re-add it — Object.assign cannot restore the private
             // isDisposed flag, so the model would be added in a broken state.
-            if (model.disposed) {
+            if (model.disposed && transaction.type === 'delete') {
+              const restored = this.objectPool.createFromData({
+                ...model.toJSON(),
+                ...(previousState && typeof previousState === 'object' ? previousState : {}),
+                __typename: transaction.modelName,
+              });
+              if (restored) this.objectPool.add(restored, ModelScope.live);
+            } else if (model.disposed) {
               // Follow-on of an already-logged permanent error, not its own
               // problem: the tx that failed has already surfaced the cause in
               // MutationQueue. Restoring a disposed model is a no-op by
@@ -330,6 +342,8 @@ export class SyncClient extends EventEmitter {
             }
           }
 
+          if (transaction.type === 'delete') this.pendingDeletes.delete(transaction.modelId);
+
           this.notifyObservers({
             type: 'rollback',
             modelType: transaction.modelName,
@@ -1084,7 +1098,17 @@ export class SyncClient extends EventEmitter {
   delete(model: Model, options?: WriteOptions): Promise<void> | undefined {
     // Clear pending mutations first to prevent "not found" errors on fast delete
     this.mutationQueue.cancelTransactionsForModel(model.id);
-    return this.mutate('delete', model, () => this.objectPool.remove(model.id), options);
+    this.pendingDeletes.add(model.id);
+    this.emit('optimistic:delete', model.id);
+    const confirmation = this.mutate('delete', model, () => this.objectPool.remove(model.id), options);
+    // Confirmation can precede the IndexedDB delta write. Keep the guard until
+    // the persisted remove is applied, except when no durable row exists.
+    void confirmation?.then(async () => {
+      if (!await this.database.getStore(model.getModelName())?.get(model.id)) {
+        this.pendingDeletes.delete(model.id);
+      }
+    }).catch(() => undefined);
+    return confirmation;
   }
 
   private fileUploadContext(): FileUploadContext {
@@ -1871,6 +1895,7 @@ export class SyncClient extends EventEmitter {
       // otherwise re-add it for the brief window before the matching delete
       // confirmation lands.
       if (this.echoTracker.consumeEcho(transactionId)) {
+        if (action === 'remove') this.pendingDeletes.delete(modelId);
         // A direct assignment can re-enter change tracking while this
         // optimistic write is in flight. Leaving the acknowledged field dirty
         // makes conflict resolution preserve it over the next collaborator
@@ -1944,6 +1969,7 @@ export class SyncClient extends EventEmitter {
         }
         case 'remove':
           idsToRemove.push(modelId);
+          this.pendingDeletes.delete(modelId);
           break;
         case 'archive':
           idsToArchive.push(modelId);

package/src/local/client/createInternalComponents.ts

@@ -127,7 +127,9 @@ export function createInternalComponents<S extends SchemaRecord>(
     // leaves so a late answer cannot overwrite a row the pool already knows to
     // be further along.
     position: syncClient.position,
+    isDeletePending: (id) => syncClient.isDeletePending(id),
   });
+  syncClient.on('optimistic:delete', (id: string) => hydration.markDeleted(id));
 
   // Drop the lazy-lane hydration ledger on reconnect. While connected, the
   // WebSocket delta stream keeps hydrated rows fresh so repeat reads serve

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/OnDemandLoader.ts

@@ -71,6 +71,7 @@ export interface OnDemandLoaderOptions {
    * against before a snapshot may overwrite it (see {@link RowWatermarks}).
    */
   readonly position: Pick<LogPositionPort, 'readFloor'>;
+  readonly isDeletePending?: (id: string) => boolean;
 }
 
 export interface FetchOptions<T> {
@@ -153,6 +154,11 @@ function snapshotPosition(
 }
 
 export class OnDemandLoader {
+  private readonly activeReadDeletes = new Set<Set<string>>();
+
+  markDeleted(id: string): void {
+    for (const deleted of this.activeReadDeletes) deleted.add(id);
+  }
   private readonly readEvidence = new WeakMap<object, number>();
   private readonly inFlight = new Map<string, Promise<Model[]>>();
   /**
@@ -302,8 +308,10 @@ export class OnDemandLoader {
     // through to the blocking fetch that brings parent and children together;
     // the second open is served by the fast path.
     if (!explicitComplete && !hasExpand) {
-      const local = await this.readLocal(modelName, typename, ModelClass, clauses, hasExpand, expand);
-      if (local.length > 0) {
+      let suppressed = false;
+      const local = await this.readLocal(modelName, typename, ModelClass, clauses, hasExpand, expand,
+        () => { suppressed = true; });
+      if (local.length > 0 || suppressed) {
         this.scheduleHydratingFetch(queryKey, modelName, typename, clauses, options);
         return applyLimit(local, options?.limit);
       }
@@ -330,16 +338,30 @@ export class OnDemandLoader {
     clauses: readonly WhereClause[],
     hasExpand: boolean,
     expand: readonly string[] | undefined,
+    onSuppressed?: () => void,
   ): Promise<Model[]> {
-    let local = scanPool(this.opts.objectPool, ModelClass, clauses);
+    let local = scanPool(this.opts.objectPool, ModelClass, clauses)
+      .filter((model) => !this.opts.isDeletePending?.(model.id));
     if (local.length === 0) {
-      const fromIdb = await scanIdb(this.opts.database, typename, clauses);
-      const idbModels = fromIdb
-        .map((raw) => this.hydrateOne(raw, LOCAL, typename))
-        .filter((m): m is Model => m !== null);
-      if (idbModels.length > 0) {
-        this.opts.objectPool.addBatch(idbModels, ModelScope.live);
-        local = idbModels;
+      const deleted = new Set<string>();
+      this.activeReadDeletes.add(deleted);
+      try {
+        const fromIdb = await scanIdb(this.opts.database, typename, clauses);
+        if (fromIdb.some((raw) => {
+          const id = raw && typeof raw === 'object' ? (raw as { id?: unknown }).id : undefined;
+          return typeof id === 'string' && (this.opts.isDeletePending?.(id) || deleted.has(id));
+        })) {
+          onSuppressed?.();
+        }
+        const idbModels = fromIdb
+          .map((raw) => this.hydrateOne(raw, LOCAL, typename, { deleted }))
+          .filter((m): m is Model => m !== null);
+        if (idbModels.length > 0) {
+          this.opts.objectPool.addBatch(idbModels, ModelScope.live);
+          local = idbModels;
+        }
+      } finally {
+        this.activeReadDeletes.delete(deleted);
       }
     }
     if (hasExpand && expand && local.length > 0) {
@@ -370,41 +392,47 @@ export class OnDemandLoader {
     clauses: readonly WhereClause[],
     options: FetchOptions<unknown> | undefined,
   ): Promise<Model[]> {
-    const network = await this.queryNetwork(modelName, clauses, options);
-    const networkRows = network.rows;
-    const evidenceById = new Map(network.evidence.map((entry) => [entry.id, entry.stamp]));
-    const acceptedRows: unknown[] = [];
-    const networkModels = networkRows
-      // Strict: a row the server returned whose type name this client never
-      // registered is a genuine schema collision (the pushed schema differs
-      // from the local one). Throw here, naming the cause, rather than silently
-      // dropping the row and failing downstream as `entity_not_found`.
-      .map((raw) =>
-        this.hydrateOne(
-          raw,
-          { kind: 'network', position: snapshotPosition(raw, evidenceById, network.position) },
-          typename,
-          { strict: true, acceptedRows },
-        ),
-      )
-      .filter((m): m is Model => m !== null);
-
-    for (const model of networkModels) {
-      const stamp = evidenceById.get(model.id);
-      if (stamp === undefined) continue;
-      // The read's evidence, kept for the premise a guarded write may cite;
-      // and the position the pooled row now reflects, for freshness.
-      this.readEvidence.set(model, stamp);
-      this.opts.objectPool.watermarks.advance(model, stamp);
-    }
+    const deleted = new Set<string>();
+    this.activeReadDeletes.add(deleted);
+    try {
+      const network = await this.queryNetwork(modelName, clauses, options, deleted);
+      const networkRows = network.rows;
+      const evidenceById = new Map(network.evidence.map((entry) => [entry.id, entry.stamp]));
+      const acceptedRows: unknown[] = [];
+      const networkModels = networkRows
+        // Strict: a row the server returned whose type name this client never
+        // registered is a genuine schema collision (the pushed schema differs
+        // from the local one). Throw here, naming the cause, rather than silently
+        // dropping the row and failing downstream as `entity_not_found`.
+        .map((raw) =>
+          this.hydrateOne(
+            raw,
+            { kind: 'network', position: snapshotPosition(raw, evidenceById, network.position) },
+            typename,
+            { strict: true, acceptedRows, deleted },
+          ),
+        )
+        .filter((m): m is Model => m !== null);
 
-    if (networkModels.length > 0) {
-      this.opts.objectPool.addBatch(networkModels, ModelScope.live);
-      // Persist only accepted snapshots: a stale response must not roll disk back.
-      await this.persistToIdb(modelName, acceptedRows);
-    }
+      for (const model of networkModels) {
+        const stamp = evidenceById.get(model.id);
+        if (stamp === undefined) continue;
+        // The read's evidence, kept for the premise a guarded write may cite;
+        // and the position the pooled row now reflects, for freshness.
+        this.readEvidence.set(model, stamp);
+        this.opts.objectPool.watermarks.advance(model, stamp);
+      }
+
+      if (networkModels.length > 0) {
+        this.opts.objectPool.addBatch(networkModels, ModelScope.live);
+        // Persist only accepted snapshots: a stale response must not roll disk back.
+        await this.persistToIdb(modelName, acceptedRows);
+      }
 
-    return networkModels;
+      return networkModels;
+    } finally {
+      this.activeReadDeletes.delete(deleted);
+    }
   }
 
   /**
@@ -473,12 +501,18 @@ export class OnDemandLoader {
       );
       if (missing.length === 0) continue;
 
-      const rows = await this.readChildrenLocal(targetTypename, foreignKey, missing);
-      const models = rows
-        .map((raw) => this.hydrateOne(this.stampTypename(raw, targetTypename), LOCAL, targetTypename))
-        .filter((m): m is Model => m !== null);
-      if (models.length > 0) {
-        this.opts.objectPool.addBatch(models, ModelScope.live);
+      const deleted = new Set<string>();
+      this.activeReadDeletes.add(deleted);
+      try {
+        const rows = await this.readChildrenLocal(targetTypename, foreignKey, missing);
+        const models = rows
+          .map((raw) => this.hydrateOne(this.stampTypename(raw, targetTypename), LOCAL, targetTypename, { deleted }))
+          .filter((m): m is Model => m !== null);
+        if (models.length > 0) {
+          this.opts.objectPool.addBatch(models, ModelScope.live);
+        }
+      } finally {
+        this.activeReadDeletes.delete(deleted);
       }
     }
   }
@@ -532,11 +566,12 @@ export class OnDemandLoader {
     raw: unknown,
     origin: HydrationOrigin,
     typename?: string,
-    opts?: { strict?: boolean; acceptedRows?: unknown[] },
+    opts?: { strict?: boolean; acceptedRows?: unknown[]; deleted?: ReadonlySet<string> },
   ): Model | null {
     if (!raw || typeof raw !== 'object') return null;
     const obj = raw as Record<string, unknown>;
     if (typeof obj.id !== 'string') return null;
+    if (this.opts.isDeletePending?.(obj.id) || opts?.deleted?.has(obj.id)) return null;
     if (this.opts.objectPool.has(obj.id)) {
       // Keep the existing instance alive when a query refreshes it. A query
       // can carry fresher server state after a missed delta, but unlike the
@@ -617,6 +652,7 @@ export class OnDemandLoader {
     modelName: string,
     clauses: readonly WhereClause[],
     options: FetchOptions<unknown> | undefined,
+    deleted: ReadonlySet<string>,
   ): Promise<{
     rows: unknown[];
     evidence: readonly { id: string; stamp: number }[];
@@ -672,7 +708,7 @@ export class OnDemandLoader {
     // own typed pool, then leave the nested arrays in place on the
     // primary row.
     if (options?.expand && options.expand.length > 0) {
-      await this.hydrateExpanded(modelName, normalized, options.expand, position);
+      await this.hydrateExpanded(modelName, normalized, options.expand, position, deleted);
     }
     return { rows: normalized, evidence, position };
   }
@@ -689,6 +725,7 @@ export class OnDemandLoader {
     rows: unknown[],
     relationNames: readonly string[],
     position: number,
+    deleted: ReadonlySet<string>,
   ): Promise<void> {
     const writes: Promise<void>[] = [];
     const parentDef = this.getModelDef(parentModelName);
@@ -711,7 +748,7 @@ export class OnDemandLoader {
         const stampedItems: unknown[] = [];
         for (const item of items) {
           const stamped = this.stampTypename(item, targetTypename);
-          const m = this.hydrateOne(stamped, origin, targetTypename, { acceptedRows: stampedItems });
+          const m = this.hydrateOne(stamped, origin, targetTypename, { acceptedRows: stampedItems, deleted });
           if (m) models.push(m);
         }
         if (models.length > 0) {

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();
 }
 
 /**