@abloatai/humans 0.65.0 → 0.66.1

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/SyncClient.d.ts

@@ -57,6 +57,8 @@ export declare class SyncClient extends EventEmitter {
      * {@link SyncClient.getEchoMetrics} exposes its counters.
      */
     private readonly echoTracker;
+    private readonly pendingDeletes;
+    isDeletePending(id: string): boolean;
     private connectionState;
     private isDisposed;
     /**

package/dist/local/SyncClient.js

@@ -69,6 +69,10 @@ export class SyncClient extends EventEmitter {
      * {@link SyncClient.getEchoMetrics} exposes its counters.
      */
     echoTracker = new UnconfirmedWrites();
+    pendingDeletes = new Set();
+    isDeletePending(id) {
+        return this.pendingDeletes.has(id);
+    }
     // Connection state
     connectionState = 'disconnected';
     // Configuration
@@ -237,7 +241,16 @@ 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
@@ -256,6 +269,8 @@ export class SyncClient extends EventEmitter {
                         this.objectPool.add(model, ModelScope.live);
                     }
                 }
+                if (transaction.type === 'delete')
+                    this.pendingDeletes.delete(transaction.modelId);
                 this.notifyObservers({
                     type: 'rollback',
                     modelType: transaction.modelName,
@@ -876,7 +891,17 @@ export class SyncClient extends EventEmitter {
     delete(model, options) {
         // 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;
     }
     fileUploadContext() {
         return {
@@ -1530,6 +1555,8 @@ 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
@@ -1600,6 +1627,7 @@ export class SyncClient extends EventEmitter {
                 }
                 case 'remove':
                     idsToRemove.push(modelId);
+                    this.pendingDeletes.delete(modelId);
                     break;
                 case 'archive':
                     idsToArchive.push(modelId);

package/dist/local/client/createInternalComponents.js

@@ -68,7 +68,9 @@ export function createInternalComponents(input) {
         // 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) => 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
     // pure-local with no network; after a drop, deltas may have been missed, so

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

@@ -66,6 +66,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> {
     /**
@@ -99,6 +100,8 @@ export interface FetchOptions<T> {
 }
 export declare class OnDemandLoader {
     private readonly opts;
+    private readonly activeReadDeletes;
+    markDeleted(id: string): void;
     private readonly readEvidence;
     private readonly inFlight;
     /**

package/dist/local/sync/OnDemandLoader.js

@@ -47,6 +47,11 @@ function snapshotPosition(raw, evidenceById, readFloorAtIssue) {
 }
 export class OnDemandLoader {
     opts;
+    activeReadDeletes = new Set();
+    markDeleted(id) {
+        for (const deleted of this.activeReadDeletes)
+            deleted.add(id);
+    }
     readEvidence = new WeakMap();
     inFlight = new Map();
     /**
@@ -166,8 +171,9 @@ 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);
             }
@@ -185,16 +191,30 @@ export class OnDemandLoader {
      * pool from IDB as a side effect. Resolves requested `expand` relations from
      * their own local stores too. Never touches the network.
      */
-    async readLocal(modelName, typename, ModelClass, clauses, hasExpand, expand) {
-        let local = scanPool(this.opts.objectPool, ModelClass, clauses);
+    async readLocal(modelName, typename, ModelClass, clauses, hasExpand, expand, onSuppressed) {
+        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 !== null);
-            if (idbModels.length > 0) {
-                this.opts.objectPool.addBatch(idbModels, ModelScope.live);
-                local = idbModels;
+            const deleted = new Set();
+            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.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 !== 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) {
@@ -218,32 +238,39 @@ export class OnDemandLoader {
      * revalidation kicked off after an `'unknown'` local hit.
      */
     async fetchFromNetwork(modelName, typename, clauses, options) {
-        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 = [];
-        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 !== 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();
+        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 = [];
+            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 !== 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);
+            }
+            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;
         }
-        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);
+        finally {
+            this.activeReadDeletes.delete(deleted);
         }
-        return networkModels;
     }
     /**
      * Fires the single background confirm for a query that was just served from
@@ -301,12 +328,19 @@ export class OnDemandLoader {
             const missing = parentIds.filter((pid) => this.opts.objectPool.getByForeignKey(targetTypename, foreignKey, pid).length === 0);
             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 !== null);
-            if (models.length > 0) {
-                this.opts.objectPool.addBatch(models, ModelScope.live);
+            const deleted = new Set();
+            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 !== null);
+                if (models.length > 0) {
+                    this.opts.objectPool.addBatch(models, ModelScope.live);
+                }
+            }
+            finally {
+                this.activeReadDeletes.delete(deleted);
             }
         }
     }
@@ -358,6 +392,8 @@ export class OnDemandLoader {
         const obj = raw;
         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
@@ -430,7 +466,7 @@ export class OnDemandLoader {
         void _dropRowVariant;
         return { __typename: typename, ...rest };
     }
-    async queryNetwork(modelName, clauses, options) {
+    async queryNetwork(modelName, clauses, options, deleted) {
         const typename = this.resolveTypename(modelName);
         const orderEntries = options?.orderBy ? Object.entries(options.orderBy) : [];
         const firstOrder = orderEntries[0];
@@ -476,7 +512,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 };
     }
@@ -487,7 +523,7 @@ export class OnDemandLoader {
      * `__typename` field gets mangled by `postgres.camel` (`__typename`
      * → `_Typename`), so the SDK can't trust whatever string lands.
      */
-    async hydrateExpanded(parentModelName, rows, relationNames, position) {
+    async hydrateExpanded(parentModelName, rows, relationNames, position, deleted) {
         const writes = [];
         const parentDef = this.getModelDef(parentModelName);
         // Nested rows carry no evidence of their own; the read floor at issue
@@ -510,7 +546,7 @@ export class OnDemandLoader {
                 const stampedItems = [];
                 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);
                 }

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'>;