@agentunion/fastaun 0.5.18 → 0.5.20

package/dist/client/delivery.js

@@ -9,6 +9,7 @@ const MESSAGE_RECALL_SEEN_LIMIT = 10_000;
 const GROUP_RECALL_SEEN_LIMIT = 10_000;
 const VOLATILE_SEEN_LIMIT = 10_000;
 const SEQ_TRACKER_PERSIST_FLUSH_DELAY_MS = 200;
+const BACKGROUND_PULL_RETRY_DELAY_MS = 250;
 const DELIVERY_CHANGED_MESSAGE_EVENTS = new Set([
     'message.received',
     'group.message_created',
@@ -80,6 +81,11 @@ export class MessageDeliveryEngine {
     pendingGroupPullUpper = null;
     onlineUnreadHintTargets = null;
     onlineUnreadHintTasks = null;
+    backgroundPullNeeds = new Map();
+    backgroundPullTasks = new Set();
+    backgroundPullCheckQueued = false;
+    backgroundPullTimer = null;
+    backgroundPullTimerAt = 0;
     pendingP2PInlineAcks = null;
     pendingGroupInlineAcks = null;
     pendingGroupInlineAckNamespaces = null;
@@ -175,9 +181,8 @@ export class MessageDeliveryEngine {
         const pageInlineGeneration = this.captureInlineAckGeneration();
         const deferredServerCursor = Number(coordinator.pendingForwardCursor(ns, pageContigBefore) ?? 0);
         const deferredForwardAck = Number(coordinator.pendingForwardAck(ns, pageContigBefore) ?? 0);
-        const pageTrackerSnapshot = typeof client._seqTracker.snapshotNamespace === 'function'
-            ? client._seqTracker.snapshotNamespace(ns)
-            : null;
+        let pageTrackerSnapshot = null;
+        let trackerMutated = false;
         response._contig_before = pageContigBefore;
         const cursor = isJsonObject(response.cursor)
             ? response.cursor
@@ -225,6 +230,18 @@ export class MessageDeliveryEngine {
                 }
             }
             this.ensurePullOperationCurrent(ns);
+            if (pageInlineGeneration !== this.captureInlineAckGeneration())
+                throw new Error('pull invalidated');
+            const previousWindow = client._seqTracker.getSyncState(ns);
+            const scanTarget = Math.max(pageContigBefore, ...messages.map((message) => positiveSafeSequenceHint(message.seq)), positiveSafeSequenceHint(response.contiguous_seq), retentionFloor, visibilityFloor, deferredServerCursor);
+            const deliveryTarget = scanTarget >= previousWindow.tail - 1
+                ? Math.max(scanTarget, previousWindow.head) : scanTarget;
+            await this.drainOrderedMessages(ns, undefined, false, false, 'pull', undefined, deliveryTarget);
+            this.ensurePullOperationCurrent(ns);
+            if (pageInlineGeneration !== this.captureInlineAckGeneration())
+                throw new Error('pull invalidated');
+            pageTrackerSnapshot = client._seqTracker.snapshotNamespace?.(ns) ?? null;
+            trackerMutated = true;
             client._seqTracker.onPullResult(ns, messages, afterSeq, Number.isSafeInteger(result.contiguous_seq)
                 ? result.contiguous_seq
                 : undefined);
@@ -233,16 +250,19 @@ export class MessageDeliveryEngine {
                 client._seqTracker.forceContiguousSeq(ns, commitTarget);
             }
             if (client._seqTracker.getContiguousSeq(ns) !== pageContigBefore) {
-                this.ensurePullOperationCurrent(ns);
-                await this.drainOrderedMessages(ns, undefined, false, false, 'pull');
                 this.ensurePullOperationCurrent(ns);
                 await client._commitSeqTrackerState(ns);
+                this.ensurePullOperationCurrent(ns);
+                if (pageInlineGeneration !== this.captureInlineAckGeneration())
+                    throw new Error('pull invalidated');
             }
             committed = true;
         }
         catch (exc) {
-            if (this.isPullOperationCurrent(ns) && !committed && typeof client._seqTracker.restoreNamespaceSnapshot === 'function') {
-                client._seqTracker.restoreNamespaceSnapshot(ns, pageTrackerSnapshot);
+            if (trackerMutated && pageInlineGeneration === this.captureInlineAckGeneration() && this.isPullOperationCurrent(ns)
+                && !committed && typeof client._seqTracker.restoreNamespaceSnapshot === 'function') {
+                (client._seqTracker._restoreNamespaceSnapshotPreservingPush ?? client._seqTracker.restoreNamespaceSnapshot)
+                    .call(client._seqTracker, ns, pageTrackerSnapshot);
                 this.dropSeqTrackerPending(ns);
             }
             throw exc;
@@ -408,6 +428,13 @@ export class MessageDeliveryEngine {
         this.deliveryChangedGeneration += 1;
         this.pendingDeliveryChanges = null;
         this.inlineAckGeneration += 1;
+        if (this.backgroundPullTimer)
+            clearTimeout(this.backgroundPullTimer);
+        this.backgroundPullTimer = null;
+        this.backgroundPullTimerAt = 0;
+        this.backgroundPullNeeds.clear();
+        this.backgroundPullTasks.clear();
+        this.backgroundPullCheckQueued = false;
         void this.runtime.client._rpcPipeline?.invalidatePulls?.();
         this.pendingP2PInlineAcks = null;
         this.pendingGroupInlineAcks = null;
@@ -679,6 +706,7 @@ export class MessageDeliveryEngine {
     }
     endRealtimeSync(ns) {
         this.realtimeSyncing?.delete(ns);
+        this.requestBackgroundPullRecovery();
         this.runtime.client._rpcPipeline?.requestPullDrainedCheck?.();
     }
     hasPendingPull(ns) {
@@ -689,6 +717,7 @@ export class MessageDeliveryEngine {
     }
     hasAnyPendingPull() {
         return [...(this.pendingGroupPullUpper?.values() ?? [])].some((seq) => seq > 0)
+            || this.backgroundPullNeeds.size > 0
             || Boolean(this.onlineUnreadHintTasks?.size)
             || Boolean(this.realtimeSyncing?.size)
             || Boolean(this.runtime.client._v2E2EE?.hasPendingSenderIKWork?.());
@@ -696,12 +725,136 @@ export class MessageDeliveryEngine {
     onPullGateIdle(ns) {
         if (!ns)
             return;
+        this.requestBackgroundPullRecovery();
         if (ns.startsWith('p2p:')) {
             this.runtime.client._schedulePendingP2pPullIfNeeded?.(ns, 'pull-gate-idle');
             return;
         }
         this.schedulePendingGroupPullIfNeeded(ns, 'pull-gate-idle');
     }
+    recordBackgroundPullNeed(ns, throughSeq = 0, probe = false) {
+        const client = this.runtime.client;
+        if (client._sessionOptions?.background_sync === false || !client._aid
+            || !(ns === `p2p:${client._aid}` || ns.startsWith('group:') || ns.startsWith('group_event:')))
+            return;
+        const need = this.backgroundPullNeeds.get(ns) ?? {
+            throughSeq: 0, hasMore: false, probe, lastAfter: -1, retryAt: 0,
+        };
+        need.throughSeq = Math.max(need.throughSeq, throughSeq);
+        need.probe ||= probe;
+        this.backgroundPullNeeds.set(ns, need);
+    }
+    observeBackgroundPullResponse(ns, afterSeq, result, limit = 50) {
+        if (!isJsonObject(result))
+            return;
+        const response = result;
+        const rows = ns.startsWith('group_event:') ? response.events : response.messages;
+        if (!Array.isArray(rows))
+            return;
+        const cursor = isJsonObject(response.cursor)
+            ? response.cursor : null;
+        const throughSeq = Math.max(positiveSafeSequenceHint(cursor?.latest_seq), positiveSafeSequenceHint(response.latest_seq), positiveSafeSequenceHint(response.latest_message_seq), positiveSafeSequenceHint(response.latest_event_seq), ...rows.map((row) => row && typeof row === 'object' && row.storage !== 'volatile'
+            ? positiveSafeSequenceHint(row.seq ?? row.event_seq) : 0));
+        this.recordBackgroundPullNeed(ns, throughSeq);
+        const need = this.backgroundPullNeeds.get(ns);
+        if (!need || afterSeq < need.lastAfter)
+            return;
+        need.lastAfter = afterSeq;
+        need.hasMore = response.has_more === true || positiveSafeSequenceHint(response.remaining) > 0
+            || (!('has_more' in response) && limit > 0 && rows.length >= limit);
+        need.probe = false;
+    }
+    finishBackgroundPull(ns, generation, afterSeq, failed) {
+        if (generation !== this.captureInlineAckGeneration())
+            return;
+        const need = this.backgroundPullNeeds.get(ns);
+        if (need) {
+            if (failed)
+                need.probe = true;
+            else
+                need.probe = false;
+            need.retryAt = failed || this.syncState(ns).ack <= afterSeq
+                ? Date.now() + BACKGROUND_PULL_RETRY_DELAY_MS : 0;
+        }
+        this.requestBackgroundPullRecovery();
+    }
+    requestBackgroundPullRecovery() {
+        if (this.backgroundPullCheckQueued || this.backgroundPullNeeds.size === 0)
+            return;
+        this.backgroundPullCheckQueued = true;
+        const generation = this.captureInlineAckGeneration();
+        queueMicrotask(() => {
+            this.backgroundPullCheckQueued = false;
+            if (generation !== this.captureInlineAckGeneration())
+                return;
+            const client = this.runtime.client;
+            if (client._sessionOptions?.background_sync === false || client.state !== ConnectionState.READY || client._closing)
+                return;
+            let retryAt = Infinity;
+            for (const [ns, need] of this.backgroundPullNeeds) {
+                if (this.backgroundPullTasks.has(ns) || this.realtimeSyncing?.has(ns) || this.onlineUnreadHintTasks?.has(ns))
+                    continue;
+                const eventScope = ns.startsWith('group_event:');
+                const filling = [...(client._gapFillDone?.keys?.() ?? [])].some((key) => eventScope
+                    ? String(key) === `group_event_pull:${ns}`
+                    : ns.startsWith('p2p:') ? String(key).startsWith('p2p:') : String(key).startsWith(`group_msg:${ns.slice(6)}:`));
+                if (filling || (!eventScope && client._rpcPipeline?.hasPullActivity?.(ns, false))
+                    || (eventScope && ['pulling', 'processing', 'pulled'].includes(client._rpcPipeline?.getPullLifecycle?.(ns))))
+                    continue;
+                if (this.syncState(ns).ack >= need.throughSeq && !need.hasMore && !need.probe) {
+                    this.backgroundPullNeeds.delete(ns);
+                    continue;
+                }
+                if (need.retryAt > Date.now()) {
+                    retryAt = Math.min(retryAt, need.retryAt);
+                    continue;
+                }
+                this.backgroundPullTasks.add(ns);
+                const task = Promise.resolve().then(() => {
+                    if (generation !== this.captureInlineAckGeneration())
+                        return;
+                    return eventScope ? this.fillGroupEventGap(ns.slice('group_event:'.length))
+                        : ns.startsWith('group:') ? this.fillGroupGap(ns.slice(6)) : this.fillP2pGap();
+                }).finally(() => {
+                    if (generation !== this.captureInlineAckGeneration())
+                        return;
+                    this.backgroundPullTasks.delete(ns);
+                    this.requestBackgroundPullRecovery();
+                });
+                client._safeAsync(task);
+            }
+            if (this.backgroundPullNeeds.size === 0) {
+                if (this.backgroundPullTimer)
+                    clearTimeout(this.backgroundPullTimer);
+                this.backgroundPullTimer = null;
+                this.backgroundPullTimerAt = 0;
+                client._rpcPipeline?.requestPullDrainedCheck?.();
+            }
+            if (Number.isFinite(retryAt) && (!this.backgroundPullTimer || retryAt < this.backgroundPullTimerAt)) {
+                if (this.backgroundPullTimer)
+                    clearTimeout(this.backgroundPullTimer);
+                this.backgroundPullTimerAt = retryAt;
+                this.backgroundPullTimer = setTimeout(() => {
+                    this.backgroundPullTimer = null;
+                    this.backgroundPullTimerAt = 0;
+                    this.requestBackgroundPullRecovery();
+                }, Math.max(0, retryAt - Date.now()));
+                this.backgroundPullTimer.unref?.();
+            }
+        });
+    }
+    onForegroundPullsDrained() {
+        const client = this.runtime.client;
+        if (!client._aid || client._sessionOptions?.background_sync === false
+            || client.state !== ConnectionState.READY || client._closing)
+            return;
+        const ns = `p2p:${client._aid}`;
+        const state = this.syncState(ns);
+        const maxSeen = client._seqTracker.getMaxSeenSeq(ns);
+        if (maxSeen <= state.ack && state.ack >= state.tail - 1)
+            return;
+        client._safeAsync(this.fillP2pGap());
+    }
     recordPendingGroupPull(ns, seq) {
         if (!ns || !Number.isSafeInteger(seq) || seq <= 0)
             return;
@@ -792,12 +945,12 @@ export class MessageDeliveryEngine {
             return;
         }
         if (pullResponse) {
-            const published = client._withPullResponseProcessing(ns, () => this.publishAppEvent(event, payload, source, deliveryContext));
+            const published = client._withPullResponseProcessing(ns, () => client._publishAppEvent(event, payload, source, deliveryContext));
             if (isPromiseLike(published))
                 await published;
         }
         else {
-            const published = this.publishAppEvent(event, payload, source, deliveryContext);
+            const published = client._publishAppEvent(event, payload, source, deliveryContext);
             if (isPromiseLike(published))
                 await published;
         }
@@ -806,6 +959,12 @@ export class MessageDeliveryEngine {
     }
     async publishOrderedGroupChanged(payload, source = 'ordered') {
         const client = this.runtime.client;
+        const generation = this.captureInlineAckGeneration();
+        const published = client._publishAppEvent('group.changed', payload, source);
+        if (isPromiseLike(published))
+            await published;
+        if (generation !== this.captureInlineAckGeneration())
+            throw new Error('pull invalidated');
         if (isJsonObject(payload)) {
             const eventPayload = payload;
             client._groupState?.handleGroupChangedV2Membership?.(eventPayload);
@@ -816,9 +975,6 @@ export class MessageDeliveryEngine {
                     client._cleanupDissolvedGroup?.(groupId);
             }
         }
-        const published = client._publishAppEvent('group.changed', payload, source);
-        if (isPromiseLike(published))
-            await published;
     }
     isInstanceScopedMessageEvent(event) {
         return event === 'message.received'
@@ -1131,6 +1287,7 @@ export class MessageDeliveryEngine {
     }
     async publishMessageRecallTombstone(seq, message, source = 'push') {
         const client = this.runtime.client;
+        const generation = this.captureInlineAckGeneration();
         const eventPayload = this.recallEventFromMessage(message);
         if (!eventPayload)
             return false;
@@ -1144,13 +1301,17 @@ export class MessageDeliveryEngine {
             client._clientLog.debug(`message.recalled dedup suppressed: seq=${String(seq)} key=${dedupKey}`);
             return false;
         }
+        await client._publishAppEvent('message.recalled', eventPayload, source);
+        if (generation !== this.captureInlineAckGeneration())
+            throw new Error('pull invalidated');
+        if (this.isPullScopedSource(source))
+            this.ensurePullOperationCurrent(`p2p:${client._aid ?? ''}`);
         seen.set(dedupKey, Date.now());
         if (seen.size > MESSAGE_RECALL_SEEN_LIMIT) {
             const drop = [...seen.entries()].sort((a, b) => a[1] - b[1]).slice(0, seen.size - MESSAGE_RECALL_SEEN_LIMIT);
             for (const [oldKey] of drop)
                 seen.delete(oldKey);
         }
-        await client._publishAppEvent('message.recalled', eventPayload, source);
         client._clientLog.debug(`message.recalled published: seq=${String(seq)} ids=${JSON.stringify(eventPayload.message_ids)}`);
         return true;
     }
@@ -1235,6 +1396,7 @@ export class MessageDeliveryEngine {
     }
     async publishGroupRecallTombstone(groupId, seq, message, source = 'push') {
         const client = this.runtime.client;
+        const generation = this.captureInlineAckGeneration();
         const eventPayload = this.recallEventFromGroupMessage(message);
         if (!eventPayload)
             return false;
@@ -1250,13 +1412,17 @@ export class MessageDeliveryEngine {
             client._clientLog.debug(`group.message_recalled dedup suppressed: group=${groupId} seq=${String(seq)} key=${dedupKey}`);
             return false;
         }
+        await client._publishAppEvent('group.message_recalled', eventPayload, source);
+        if (generation !== this.captureInlineAckGeneration())
+            throw new Error('pull invalidated');
+        if (this.isPullScopedSource(source))
+            this.ensurePullOperationCurrent(`group:${groupId}`);
         seen.set(dedupKey, Date.now());
         if (seen.size > GROUP_RECALL_SEEN_LIMIT) {
             const drop = [...seen.entries()].sort((a, b) => a[1] - b[1]).slice(0, seen.size - GROUP_RECALL_SEEN_LIMIT);
             for (const [oldKey] of drop)
                 seen.delete(oldKey);
         }
-        await client._publishAppEvent('group.message_recalled', eventPayload, source);
         client._clientLog.debug(`group.message_recalled published: group=${groupId} seq=${String(seq)} ids=${JSON.stringify(eventPayload.message_ids)}`);
         return true;
     }
@@ -1301,6 +1467,7 @@ export class MessageDeliveryEngine {
         if (seqNum > client._seqTracker.getContiguousSeq(ns) && client._sessionOptions?.background_sync !== false) {
             this.fillGroupGap(groupId).catch((exc) => client._clientLog.warn(`background recall gap fill failed: ${formatDeliveryError(exc)}`));
         }
+        await this.publishGroupRecallTombstone(groupId, seq, wrapped);
     }
     publishAppEvent(event, payload, source = 'direct', deliveryContext) {
         const client = this.runtime.client;
@@ -1325,11 +1492,14 @@ export class MessageDeliveryEngine {
         const generation = this.deliveryChangedGeneration;
         const normalized = this.normalizePublishedMessagePayload(event, payload, source);
         const dispatcher = client._dispatcher;
-        const result = typeof dispatcher.enqueue === 'function'
-            ? (dispatcher.enqueue(event, normalized), undefined)
-            : typeof dispatcher.publishSyncAware === 'function'
-                ? dispatcher.publishSyncAware(event, normalized)
-                : dispatcher.publish?.(event, normalized);
+        const result = ['message.received', 'group.message_created', 'message.recalled', 'group.message_recalled', 'group.changed'].includes(event)
+            && typeof dispatcher._publishAndWait === 'function'
+            ? dispatcher._publishAndWait(event, normalized)
+            : typeof dispatcher.enqueue === 'function'
+                ? (dispatcher.enqueue(event, normalized), undefined)
+                : typeof dispatcher.publishSyncAware === 'function'
+                    ? dispatcher.publishSyncAware(event, normalized)
+                    : dispatcher.publish?.(event, normalized);
         const note = () => {
             if (generation === this.deliveryChangedGeneration) {
                 this.noteDeliveryChanged(event, payload, source, deliveryContext);
@@ -1583,7 +1753,6 @@ export class MessageDeliveryEngine {
             if (Number(seq) > client._seqTracker.getContiguousSeq(ns) && client._sessionOptions?.background_sync !== false) {
                 this.fillP2pGap().catch((exc) => client._clientLog.warn(`background recall gap fill failed: ${formatDeliveryError(exc)}`));
             }
-            return;
         }
         await this.publishMessageRecallTombstone(seq, msg);
     }
@@ -1784,12 +1953,15 @@ export class MessageDeliveryEngine {
             return;
         const ns = `p2p:${client._aid}`;
         const afterSeq = client._seqTracker.getContiguousSeq(ns);
+        const generation = this.captureInlineAckGeneration();
         const dedupKey = `p2p:${afterSeq}`;
         if (client._gapFillDone.has(dedupKey))
             return;
         client._gapFillDone.set(dedupKey, Date.now());
+        this.recordBackgroundPullNeed(ns, 0, true);
         client._clientLog.debug(`P2P message gap fill start: after_seq=${afterSeq}`);
         let filled = 0;
+        let failed = false;
         try {
             // Gap Fill 本身就是 Forward Pull，必须沿用协调器的完整事务：
             // 原始页提交成功后由协调器负责 Piggyback/终端 ACK。
@@ -1802,11 +1974,15 @@ export class MessageDeliveryEngine {
             client._clientLog.debug(`P2P message gap fill done: after_seq=${afterSeq}, filled=${filled}`);
         }
         catch (exc) {
+            failed = true;
             client._clientLog.warn(`P2P message gap fill failed: ${formatDeliveryError(exc)}`);
         }
         finally {
+            if (generation !== this.captureInlineAckGeneration())
+                return;
             client._gapFillDone.delete(dedupKey);
             client._schedulePendingP2pPullIfNeeded?.(ns, 'gap-fill-complete');
+            this.finishBackgroundPull(ns, generation, afterSeq, failed);
         }
     }
     async fillGroupGap(groupId) {
@@ -1818,12 +1994,15 @@ export class MessageDeliveryEngine {
             return;
         const ns = `group:${groupId}`;
         const afterSeq = client._seqTracker.getContiguousSeq(ns);
+        const generation = this.captureInlineAckGeneration();
         const dedupKey = `group_msg:${groupId}:${afterSeq}`;
         if (client._gapFillDone.has(dedupKey))
             return;
         client._gapFillDone.set(dedupKey, Date.now());
+        this.recordBackgroundPullNeed(ns, 0, true);
         client._clientLog.debug(`group message gap fill start: group=${groupId}, after_seq=${afterSeq}`);
         let filled = 0;
+        let failed = false;
         try {
             const operation = () => client._pullGroupV2(groupId, afterSeq, 50, { gateLocked: true });
             const messages = client._rpcPipeline
@@ -1834,14 +2013,15 @@ export class MessageDeliveryEngine {
             client._clientLog.debug(`group message gap fill done: group=${groupId}, after_seq=${afterSeq}, filled=${filled}`);
         }
         catch (exc) {
+            failed = true;
             client._clientLog.warn(`group message gap fill failed: ${formatDeliveryError(exc)}`);
         }
         finally {
+            if (generation !== this.captureInlineAckGeneration())
+                return;
             client._gapFillDone.delete(dedupKey);
-            if (filled > 0 && client._seqTracker.getContiguousSeq(ns) > afterSeq) {
-                void this.fillGroupGap(groupId);
-            }
             this.schedulePendingGroupPullIfNeeded(ns, 'gap-fill-complete');
+            this.finishBackgroundPull(ns, generation, afterSeq, failed);
         }
     }
     scheduleRealtimeWindowForward(ns, groupId = '') {
@@ -1883,6 +2063,7 @@ export class MessageDeliveryEngine {
         if (!groupId)
             return;
         const ns = `group_event:${groupId}`;
+        const generation = this.captureInlineAckGeneration();
         const requestedAfterSeq = Number(options.afterSeq ?? 0);
         const afterSeq = Number.isSafeInteger(requestedAfterSeq) && requestedAfterSeq > 0
             ? requestedAfterSeq
@@ -1901,10 +2082,12 @@ export class MessageDeliveryEngine {
             }
         }
         client._gapFillDone.set(dedupKey, Date.now());
+        this.recordBackgroundPullNeed(ns, client._seqTracker.getMaxSeenSeq(ns), true);
         this.syncStarted(ns);
         let filled = 0;
         let continuationAfterSeq = 0;
         let failed = false;
+        let dissolved = false;
         try {
             let nextAfterSeq = afterSeq;
             const maxPages = singlePage ? 1 : 100;
@@ -1930,14 +2113,16 @@ export class MessageDeliveryEngine {
                 }
                 if (!isJsonObject(result))
                     return;
+                if (generation !== this.captureInlineAckGeneration())
+                    return;
+                this.observeBackgroundPullResponse(ns, nextAfterSeq, result);
                 const events = result.events;
                 if (!Array.isArray(events))
                     return;
                 const pageContigBefore = client._seqTracker.getContiguousSeq(ns);
+                let pageTrackerSnapshot = null;
+                let trackerMutated = false;
                 const eventObjects = events.filter((evt) => isJsonObject(evt));
-                client._seqTracker.onPullResult(ns, eventObjects, nextAfterSeq, Number.isSafeInteger(result.contiguous_seq)
-                    ? result.contiguous_seq
-                    : undefined);
                 const cursor = isJsonObject(result.cursor)
                     ? result.cursor
                     : null;
@@ -1947,13 +2132,6 @@ export class MessageDeliveryEngine {
                 const earliestAvailable = Number(result.earliest_available_event_seq ?? 0);
                 const visibilityFloor = Math.max(0, Number.isFinite(Number(cursor?.join_seq)) ? Number(cursor?.join_seq) : 0, Number.isFinite(earliestAvailable) && earliestAvailable > 0 ? earliestAvailable - 1 : 0);
                 const effectiveFloor = Math.max(retentionFloor, serverAckFloor, visibilityFloor);
-                if (effectiveFloor > 0) {
-                    const contigBeforeFloor = client._seqTracker.getContiguousSeq(ns);
-                    if (contigBeforeFloor < effectiveFloor) {
-                        client._clientLog.info(`group.pull_events floor advance: ns=${ns} contiguous=${contigBeforeFloor} -> effective_floor=${effectiveFloor} retention_floor=${retentionFloor} server_ack=${serverAckFloor} visibility_floor=${visibilityFloor}`);
-                        client._seqTracker.forceContiguousSeq(ns, effectiveFloor);
-                    }
-                }
                 const eventSeqs = [];
                 let hasDissolvedEvent = false;
                 let publishedEventCount = 0;
@@ -1983,11 +2161,40 @@ export class MessageDeliveryEngine {
                     if (et !== 'group.message_created')
                         filled += 1;
                 }
-                const ackContig = client._seqTracker.getContiguousSeq(ns);
-                await this.drainOrderedMessages(ns);
-                if (ackContig !== pageContigBefore && !hasDissolvedEvent) {
-                    this.persistSeq(ns);
+                try {
+                    const scanTarget = Math.max(pageContigBefore, effectiveFloor, positiveSafeSequenceHint(result.contiguous_seq), ...eventSeqs);
+                    await this.drainOrderedMessages(ns, undefined, false, false, 'pull', undefined, scanTarget);
+                    if (generation !== this.captureInlineAckGeneration())
+                        throw new Error('pull invalidated');
+                    this.ensurePullOperationCurrent(ns);
+                    if (hasDissolvedEvent) {
+                        dissolved = true;
+                        break;
+                    }
+                    pageTrackerSnapshot = client._seqTracker.snapshotNamespace?.(ns) ?? null;
+                    trackerMutated = true;
+                    client._seqTracker.onPullResult(ns, eventObjects, nextAfterSeq, Number.isSafeInteger(result.contiguous_seq)
+                        ? result.contiguous_seq : undefined);
+                    if (client._seqTracker.getContiguousSeq(ns) < effectiveFloor) {
+                        client._seqTracker.forceContiguousSeq(ns, effectiveFloor);
+                    }
+                    if (client._seqTracker.getContiguousSeq(ns) !== pageContigBefore && !hasDissolvedEvent) {
+                        await client._commitSeqTrackerState(ns);
+                        this.ensurePullOperationCurrent(ns);
+                        if (generation !== this.captureInlineAckGeneration())
+                            throw new Error('pull invalidated');
+                    }
                 }
+                catch (exc) {
+                    if (trackerMutated && generation === this.captureInlineAckGeneration() && this.isPullOperationCurrent(ns)
+                        && typeof client._seqTracker.restoreNamespaceSnapshot === 'function') {
+                        (client._seqTracker._restoreNamespaceSnapshotPreservingPush ?? client._seqTracker.restoreNamespaceSnapshot)
+                            .call(client._seqTracker, ns, pageTrackerSnapshot);
+                        this.dropSeqTrackerPending(ns);
+                    }
+                    throw exc;
+                }
+                const ackContig = client._seqTracker.getContiguousSeq(ns);
                 if (eventObjects.length > 0 && ackContig > 0 && ackContig !== pageContigBefore) {
                     const ackSeq = this.clampAckSeq('group.ack_events', 'event_seq', ns, ackContig);
                     try {
@@ -2020,6 +2227,7 @@ export class MessageDeliveryEngine {
                 const nextAfter = Math.max(eventSeqs.length > 0 ? Math.max(...eventSeqs) : nextAfterSeq, nextAfterSeq);
                 const pageAdvanced = eventObjects.length > 0 && nextAfter > nextAfterSeq;
                 const needsMore = result.has_more === true
+                    || positiveSafeSequenceHint(result.remaining) > 0
                     || client._seqTracker.getMaxSeenSeq(ns) > nextAfter;
                 if (singlePage && pageAdvanced && needsMore) {
                     continuationAfterSeq = nextAfter;
@@ -2038,19 +2246,22 @@ export class MessageDeliveryEngine {
             client._clientLog.warn(`group event gap fill failed: ${formatDeliveryError(exc)}`);
         }
         finally {
-            client._gapFillDone.delete(dedupKey);
+            if (generation === this.captureInlineAckGeneration())
+                client._gapFillDone.delete(dedupKey);
             if (legacyGateToken !== null && typeof client._releasePullGate === 'function') {
                 client._releasePullGate(ns, legacyGateToken);
             }
-            if (singlePage && continuationAfterSeq > afterSeq) {
+            if (generation !== this.captureInlineAckGeneration())
+                return;
+            if (dissolved)
+                this.backgroundPullNeeds.delete(ns);
+            if (!dissolved && singlePage && continuationAfterSeq > afterSeq) {
                 this.enqueueOnlineUnreadEventHint({
                     group_id: groupId,
                     _online_hint_after_event_seq: continuationAfterSeq,
                 });
             }
-            else if (!singlePage && filled > 0 && client._seqTracker.getContiguousSeq(ns) > afterSeq) {
-                void this.fillGroupEventGap(groupId);
-            }
+            this.finishBackgroundPull(ns, generation, afterSeq, failed);
             if (!client._rpcPipeline)
                 this.syncStopped(failed ? 'aborted' : 'pull_drained');
         }
@@ -2060,6 +2271,7 @@ export class MessageDeliveryEngine {
         const groupId = String(data.group_id ?? '').trim();
         if (!groupId || client._sessionOptions?.background_sync === false)
             return;
+        this.recordBackgroundPullNeed(`group_event:${groupId}`, positiveSafeSequenceHint(data.event_seq), true);
         const rawAfter = Number(data._online_hint_after_event_seq ?? 0);
         const afterSeq = Number.isSafeInteger(rawAfter) && rawAfter > 0 ? rawAfter : 0;
         client._safeAsync(this.fillGroupEventGap(groupId, {
@@ -2864,7 +3076,8 @@ export class MessageDeliveryEngine {
             return false;
         const client = this.runtime.client;
         const tracker = client._seqTracker;
-        const snapshot = typeof tracker.snapshotNamespace === 'function' ? tracker.snapshotNamespace(ns) : null;
+        let snapshot = null;
+        let trackerMutated = false;
         let delivered = false;
         try {
             const selfSync = (event === 'message.received' && this.isSelfSentP2PMessage(payload))
@@ -2879,6 +3092,8 @@ export class MessageDeliveryEngine {
             delivered = true;
             if (!this.inlineGenerationIsCurrent(generation))
                 return false;
+            snapshot = typeof tracker.snapshotNamespace === 'function' ? tracker.snapshotNamespace(ns) : null;
+            trackerMutated = true;
             const needsPull = Boolean(tracker.onMessageSeq(ns, seq));
             if (!this.inlineGenerationIsCurrent(generation))
                 return false;
@@ -2901,9 +3116,10 @@ export class MessageDeliveryEngine {
             return true;
         }
         catch (exc) {
-            if (this.inlineGenerationIsCurrent(generation)
-                && typeof tracker.restoreNamespaceSnapshot === 'function')
-                tracker.restoreNamespaceSnapshot(ns, snapshot);
+            if (trackerMutated && this.inlineGenerationIsCurrent(generation)
+                && typeof tracker.restoreNamespaceSnapshot === 'function') {
+                (tracker._restoreNamespaceSnapshotPreservingPush ?? tracker.restoreNamespaceSnapshot).call(tracker, ns, snapshot);
+            }
             if (this.inlineGenerationIsCurrent(generation) && delivered)
                 this.markPublishedSeq(ns, seq);
             client._clientLog.debug(`inline realtime consume rolled back: ns=${ns} seq=${seq} err=${formatDeliveryError(exc)}`);
@@ -2929,11 +3145,13 @@ export class MessageDeliveryEngine {
                 throw new Error('inline realtime terminal cursor did not collapse after consume');
             }
             await client._commitSeqTrackerState(ns);
-            return true;
+            return this.inlineGenerationIsCurrent(generation);
         }
         catch (exc) {
-            if (typeof tracker.restoreNamespaceSnapshot === 'function')
-                tracker.restoreNamespaceSnapshot(ns, snapshot);
+            if (this.inlineGenerationIsCurrent(generation)
+                && typeof tracker.restoreNamespaceSnapshot === 'function') {
+                (tracker._restoreNamespaceSnapshotPreservingPush ?? tracker.restoreNamespaceSnapshot).call(tracker, ns, snapshot);
+            }
             client._clientLog.debug(`inline realtime terminal consume rolled back: ns=${ns} seq=${seq} err=${formatDeliveryError(exc)}`);
             return false;
         }
@@ -3126,6 +3344,7 @@ export class MessageDeliveryEngine {
     }
     async onV2PushNotification(data, expectedVersion, inlineGeneration) {
         const client = this.runtime.client;
+        const syncGeneration = this.captureInlineAckGeneration();
         if (inlineGeneration !== undefined && !this.inlineGenerationIsCurrent(inlineGeneration))
             return;
         const pushData = isJsonObject(data) ? data : null;
@@ -3180,6 +3399,7 @@ export class MessageDeliveryEngine {
                 this.retryPendingP2PInlineAck(ns, pushSeq, 'covered inline push');
             return;
         }
+        this.recordBackgroundPullNeed(ns, pushSeq);
         const pullActive = client._rpcPipeline?.hasPullActivity?.(ns) === true;
         if (pullActive || !this.beginRealtimeSync(ns)) {
             client._recordPendingP2pPull(ns, pushSeq);
@@ -3196,7 +3416,9 @@ export class MessageDeliveryEngine {
             client._clientLog.warn(`V2 P2P push auto-sync failed: ${formatDeliveryError(exc)}`);
         }
         finally {
-            if (inlineGeneration === undefined || this.inlineGenerationIsCurrent(inlineGeneration)) {
+            if (syncGeneration === this.captureInlineAckGeneration()
+                && (inlineGeneration === undefined || this.inlineGenerationIsCurrent(inlineGeneration))) {
+                this.finishBackgroundPull(ns, syncGeneration, this.syncState(ns).ack, false);
                 this.endRealtimeSync(ns);
                 client._schedulePendingP2pPullIfNeeded?.(ns, 'push-auto-pull-complete');
             }
@@ -3208,6 +3430,9 @@ export class MessageDeliveryEngine {
         if (!groupId)
             return;
         const ns = `group:${groupId}`;
+        const generation = this.captureInlineAckGeneration();
+        const afterSeq = this.syncState(ns).ack;
+        this.recordBackgroundPullNeed(ns, positiveSafeSequenceHint(data.seq));
         const targets = this.onlineUnreadHintTargets ?? new Map();
         const tasks = this.onlineUnreadHintTasks ?? new Map();
         this.onlineUnreadHintTargets = targets;
@@ -3215,10 +3440,13 @@ export class MessageDeliveryEngine {
         targets.set(ns, Math.max(targets.get(ns) ?? 0, positiveSafeSequenceHint(data.seq)));
         if (tasks.has(ns))
             return;
+        let attemptAfterSeq = afterSeq;
         const task = Promise.resolve().then(async () => {
+            let failed = false;
             try {
                 while (true) {
                     const ackBefore = this.syncState(ns).ack;
+                    attemptAfterSeq = ackBefore;
                     await this.runGroupForwardRecovery(groupId, ns, 50, true, targets.get(ns) ?? 0);
                     const ackAfter = this.syncState(ns).ack;
                     if (ackAfter >= (targets.get(ns) ?? 0) || ackAfter <= ackBefore)
@@ -3226,12 +3454,14 @@ export class MessageDeliveryEngine {
                 }
             }
             catch (exc) {
+                failed = true;
                 client._clientLog.debug(`online unread hint background Forward failed: ns=${ns} err=${formatDeliveryError(exc)}`);
             }
             finally {
                 targets.delete(ns);
                 if (tasks.get(ns) === task)
                     tasks.delete(ns);
+                this.finishBackgroundPull(ns, generation, attemptAfterSeq, failed);
                 client._rpcPipeline?.requestPullDrainedCheck?.();
             }
         });
@@ -3240,6 +3470,7 @@ export class MessageDeliveryEngine {
     }
     async onRawGroupV2MessageCreated(data, expectedVersion, inlineGeneration) {
         const client = this.runtime.client;
+        const syncGeneration = this.captureInlineAckGeneration();
         if (inlineGeneration !== undefined && !this.inlineGenerationIsCurrent(inlineGeneration))
             return;
         if (!isJsonObject(data)) {
@@ -3302,6 +3533,7 @@ export class MessageDeliveryEngine {
             }
             return;
         }
+        this.recordBackgroundPullNeed(ns, seq);
         const pullActive = client._rpcPipeline?.hasPullActivity?.(ns) === true;
         if (pullActive || !this.beginRealtimeSync(ns)) {
             this.recordPendingGroupPull(ns, seq);
@@ -3317,7 +3549,9 @@ export class MessageDeliveryEngine {
                 return;
             client._clientLog.warn(`V2 group push auto-sync failed: group=${groupId} err=${formatDeliveryError(exc)}`);
         }).finally(() => {
-            if (inlineGeneration === undefined || this.inlineGenerationIsCurrent(inlineGeneration)) {
+            if (syncGeneration === this.captureInlineAckGeneration()
+                && (inlineGeneration === undefined || this.inlineGenerationIsCurrent(inlineGeneration))) {
+                this.finishBackgroundPull(ns, syncGeneration, this.syncState(ns).ack, false);
                 this.endRealtimeSync(ns);
                 this.schedulePendingGroupPullIfNeeded(ns, 'push-auto-pull-complete');
             }
@@ -3379,9 +3613,14 @@ export class MessageDeliveryEngine {
         if (!client._aid || !client._v2Session)
             return;
         const ns = `p2p:${client._aid}`;
+        const generation = this.captureInlineAckGeneration();
+        const afterSeq = this.syncState(ns).ack;
+        this.recordBackgroundPullNeed(ns, positiveSafeSequenceHint(data.seq), true);
+        let failed = false;
         client._safeAsync(this.runP2PForwardRecovery(ns, 50, true).catch((exc) => {
+            failed = true;
             client._clientLog.debug(`P2P online unread hint background Forward failed: ns=${ns} err=${formatDeliveryError(exc)}`);
-        }));
+        }).finally(() => this.finishBackgroundPull(ns, generation, afterSeq, failed)));
     }
     async saveSeqTrackerState() {
         const client = this.runtime.client;
@@ -3711,8 +3950,9 @@ export class MessageDeliveryEngine {
         }
         return params;
     }
-    async drainOrderedMessages(ns, beforeSeq, pullResponse = false, persist = true, source = 'push', context) {
+    async drainOrderedMessages(ns, beforeSeq, pullResponse = false, persist = true, source = 'push', context, throughSeq) {
         const client = this.runtime.client;
+        const generation = this.captureInlineAckGeneration();
         const pullScoped = this.isPullScopedSource(source);
         if (pullScoped)
             this.ensurePullOperationCurrent(ns);
@@ -3728,11 +3968,11 @@ export class MessageDeliveryEngine {
                     this.ensurePullOperationCurrent(ns);
                 const contig = client._seqTracker.getContiguousSeq(ns);
                 const ready = [...queue.keys()]
-                    .filter((seq) => seq <= contig && (beforeSeq === undefined || seq < beforeSeq))
+                    .filter((seq) => seq <= Math.max(contig, throughSeq ?? contig) && (beforeSeq === undefined || seq < beforeSeq))
                     .sort((a, b) => a - b);
                 let seq = ready[0];
                 if (seq === undefined) {
-                    const nextSeq = contig + 1;
+                    const nextSeq = Math.max(contig, throughSeq ?? contig) + 1;
                     if (beforeSeq !== undefined && nextSeq >= beforeSeq)
                         break;
                     if (!queue.has(nextSeq))
@@ -3742,10 +3982,10 @@ export class MessageDeliveryEngine {
                 if (seq === undefined)
                     continue;
                 const item = queue.get(seq);
-                queue.delete(seq);
                 if (!item)
                     continue;
                 if (client._pushedSeqs.get(ns)?.has(seq)) {
+                    queue.delete(seq);
                     client._clientLog.debug(`publish ordered drain skipped duplicate: ns=${ns}, seq=${seq}, event=${item.event}`);
                     client._markOrderedSeqDelivered(ns, seq);
                     continue;
@@ -3763,10 +4003,18 @@ export class MessageDeliveryEngine {
                     }
                 }
                 await this.publishOrderedQueueItem(ns, item.event, seq, item.payload, itemSource, pullResponse, itemContext);
+                if (generation !== this.captureInlineAckGeneration())
+                    throw new Error('pull invalidated');
                 if (pullScoped)
                     this.ensurePullOperationCurrent(ns);
+                queue.delete(seq);
+                if (item.event === 'group.changed' && isJsonObject(item.payload)
+                    && item.payload.action === 'dissolved')
+                    break;
                 this.markPublishedSeq(ns, seq);
                 client._markOrderedSeqDelivered(ns, seq);
+                if (throughSeq !== undefined)
+                    throughSeq = Math.max(throughSeq, seq);
                 delivered = true;
                 client._clientLog.debug(`publish ordered drain delivered: ns=${ns}, seq=${seq}, event=${item.event}`);
             }
@@ -3810,6 +4058,7 @@ export class MessageDeliveryEngine {
     }
     async publishOrderedMessageInternal(event, ns, seq, payload, source, context) {
         const client = this.runtime.client;
+        const generation = this.captureInlineAckGeneration();
         const pullScoped = this.isPullScopedSource(source);
         if (pullScoped)
             this.ensurePullOperationCurrent(ns);
@@ -3853,12 +4102,14 @@ export class MessageDeliveryEngine {
             return false;
         }
         const queue = client._pendingOrderedMsgs.get(ns);
-        queue?.delete(seqNum);
-        if (queue && queue.size === 0)
-            client._pendingOrderedMsgs.delete(ns);
         await this.publishOrderedQueueItem(ns, event, seqNum, payload, source, false, context);
+        if (generation !== this.captureInlineAckGeneration())
+            throw new Error('pull invalidated');
         if (pullScoped)
             this.ensurePullOperationCurrent(ns);
+        queue?.delete(seqNum);
+        if (queue && queue.size === 0)
+            client._pendingOrderedMsgs.delete(ns);
         this.markPublishedSeq(ns, seqNum);
         client._markOrderedSeqDelivered(ns, seqNum);
         client._clientLog.debug(`publish ordered delivered: event=${event}, ns=${ns}, seq=${seqNum}`);
@@ -3872,6 +4123,7 @@ export class MessageDeliveryEngine {
     }
     async publishPulledMessage(event, ns, seq, payload, persist = true, source = 'pull') {
         const client = this.runtime.client;
+        const generation = this.captureInlineAckGeneration();
         const pullScoped = this.isPullScopedSource(source);
         if (pullScoped)
             this.ensurePullOperationCurrent(ns);
@@ -3907,13 +4159,15 @@ export class MessageDeliveryEngine {
         await this.drainOrderedMessages(ns, seqNum, true, persist, source);
         if (pullScoped)
             this.ensurePullOperationCurrent(ns);
-        queue?.delete(seqNum);
-        if (queue && queue.size === 0)
-            client._pendingOrderedMsgs.delete(ns);
         if (event === 'message.recalled') {
             const recallPublished = await this.publishMessageRecallTombstone(seqNum, payload, source);
+            if (generation !== this.captureInlineAckGeneration())
+                throw new Error('pull invalidated');
             if (pullScoped)
                 this.ensurePullOperationCurrent(ns);
+            queue?.delete(seqNum);
+            if (queue && queue.size === 0)
+                client._pendingOrderedMsgs.delete(ns);
             this.markPublishedSeq(ns, seqNum);
             client._clientLog.debug(`publish pulled delivered: event=${event}, ns=${ns}, seq=${seqNum}`);
             await this.drainOrderedMessages(ns, undefined, true, persist, source);
@@ -3924,8 +4178,13 @@ export class MessageDeliveryEngine {
         const published = client._withPullResponseProcessing(ns, () => client._publishAppEvent(event, payload, source));
         if (isPromiseLike(published))
             await published;
+        if (generation !== this.captureInlineAckGeneration())
+            throw new Error('pull invalidated');
         if (pullScoped)
             this.ensurePullOperationCurrent(ns);
+        queue?.delete(seqNum);
+        if (queue && queue.size === 0)
+            client._pendingOrderedMsgs.delete(ns);
         this.markPublishedSeq(ns, seqNum);
         client._clientLog.debug(`publish pulled delivered: event=${event}, ns=${ns}, seq=${seqNum}`);
         await this.drainOrderedMessages(ns, undefined, true, persist, source);