@agentunion/fastaun-browser 0.5.8 → 0.5.10

package/dist/client/delivery.js

@@ -1,4 +1,5 @@
 import { slotIsolationKey } from '../config.js';
+import { normalizeGroupAid } from '../group-id.js';
 import { ConnectionState, isJsonObject } from '../types.js';
 import { hasGroupMentionModeField, normalizeGroupMentionMode } from './mention-mode.js';
 const PUSHED_SEQS_LIMIT = 50_000;
@@ -94,10 +95,15 @@ function p2pAppEventFromPlainPullMessage(message) {
 }
 export class MessageDeliveryEngine {
     runtime;
+    pendingPullDeliveryChanges = null;
+    deliveryGeneration = 0;
     realtimeTailResults = null;
     realtimeSyncing = null;
     pendingP2pPullUpper = null;
     pendingGroupPullUpper = null;
+    pendingPullNoProgressAcks = null;
+    onlineUnreadHintTargets = null;
+    onlineUnreadHintOwners = null;
     realtimeAcking = null;
     pendingP2PInlineAcks = null;
     pendingGroupInlineAcks = null;
@@ -111,9 +117,15 @@ export class MessageDeliveryEngine {
     }
     resetInlineAckState() {
         this.inlineGeneration += 1;
+        this.deliveryGeneration += 1;
+        this.pendingPullDeliveryChanges = null;
+        void this.runtime.client._rpcPipeline?.invalidatePulls?.();
         this.realtimeSyncing = null;
         this.pendingP2pPullUpper = null;
         this.pendingGroupPullUpper = null;
+        this.pendingPullNoProgressAcks = null;
+        this.onlineUnreadHintTargets = null;
+        this.onlineUnreadHintOwners = null;
         this.realtimeTailResults = null;
         this.realtimeAcking = null;
         this.pendingP2PInlineAcks = null;
@@ -123,6 +135,20 @@ export class MessageDeliveryEngine {
     isInlineGenerationCurrent(generation) {
         return generation === this.inlineGeneration;
     }
+    isPullOperationCurrent() {
+        const client = this.runtime.client;
+        const generation = client._pullOperationGeneration;
+        if (generation === undefined)
+            return true;
+        const pipeline = client._rpcPipeline;
+        return typeof pipeline?.isPullGenerationCurrent === 'function'
+            ? pipeline.isPullGenerationCurrent(generation)
+            : true;
+    }
+    ensurePullOperationCurrent() {
+        if (!this.isPullOperationCurrent())
+            throw new Error('pull invalidated');
+    }
     captureInlineGeneration() {
         return this.inlineGeneration;
     }
@@ -146,6 +172,85 @@ export class MessageDeliveryEngine {
             return;
         this.schedulePendingPullIfNeeded(ns, 'pull-gate-idle');
     }
+    onPullWorkSettled() {
+        const pipeline = this.runtime.client._rpcPipeline;
+        if (pipeline?.hasAnyPullActivity?.() === true)
+            return;
+        void this.flushPullDeliveryChanges();
+    }
+    deliveryChangeNamespace(event, payload, ns = '') {
+        if (event === 'message.received')
+            return 'p2p';
+        if (event !== 'group.message_created')
+            return '';
+        if (!isJsonObject(payload))
+            return '';
+        const aid = String(this.runtime.client._aid ?? '').trim().toLowerCase();
+        const dot = aid.indexOf('.');
+        const localIssuer = dot > 0 ? aid.slice(dot + 1) : '';
+        const fallback = ns.startsWith('group:') ? ns.slice('group:'.length) : '';
+        const groupAid = normalizeGroupAid(payload.group_aid ?? payload.group_id ?? fallback, { localIssuer });
+        return groupAid.includes('.') ? `group:${groupAid}` : '';
+    }
+    isDeliverableMessageBody(event, payload) {
+        if ((event !== 'message.received' && event !== 'group.message_created') || !isJsonObject(payload))
+            return false;
+        const messageId = typeof payload.message_id === 'string' && payload.message_id.trim().length > 0;
+        const seq = typeof payload.seq === 'number' && Number.isSafeInteger(payload.seq) && payload.seq > 0;
+        return messageId || seq;
+    }
+    recordDeliveryChange(changes, event, payload, ns, generation) {
+        if (generation !== this.deliveryGeneration || !this.isDeliverableMessageBody(event, payload))
+            return;
+        const namespace = this.deliveryChangeNamespace(event, payload, ns);
+        if (!namespace)
+            return;
+        changes.set(namespace, (changes.get(namespace) ?? 0) + 1);
+    }
+    deliveryChangesPayload(changes) {
+        return [...changes.entries()]
+            .filter(([, deliveredCount]) => deliveredCount > 0)
+            .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+            .map(([namespace, deliveredCount]) => ({ namespace, delivered_count: deliveredCount }));
+    }
+    createDeliveryChangeBatch(trigger) {
+        return { generation: this.deliveryGeneration, trigger, changes: new Map(), closed: false };
+    }
+    async flushRealtimeDeliveryChanges(batch) {
+        if (batch.closed)
+            return;
+        batch.closed = true;
+        if (batch.generation !== this.deliveryGeneration)
+            return;
+        if (this.deliveryChangesPayload(batch.changes).length === 0)
+            return;
+        const pendingPull = this.pendingPullDeliveryChanges;
+        this.pendingPullDeliveryChanges = null;
+        if (pendingPull) {
+            for (const [namespace, count] of pendingPull) {
+                batch.changes.set(namespace, (batch.changes.get(namespace) ?? 0) + count);
+            }
+        }
+        if (batch.generation !== this.deliveryGeneration)
+            return;
+        const changes = this.deliveryChangesPayload(batch.changes);
+        if (changes.length === 0)
+            return;
+        this.runtime.client._dispatcher.enqueue('delivery.changed', { trigger: batch.trigger, changes });
+    }
+    async flushPullDeliveryChanges() {
+        const generation = this.deliveryGeneration;
+        const pending = this.pendingPullDeliveryChanges;
+        if (!pending || pending.size === 0 || generation !== this.deliveryGeneration)
+            return;
+        this.pendingPullDeliveryChanges = null;
+        if (generation !== this.deliveryGeneration)
+            return;
+        const changes = this.deliveryChangesPayload(pending);
+        if (changes.length === 0)
+            return;
+        this.runtime.client._dispatcher.enqueue('delivery.changed', { trigger: 'pull_drained', changes });
+    }
     recordPendingPull(ns, seq) {
         if (!ns || !Number.isSafeInteger(seq) || seq <= 0)
             return;
@@ -160,8 +265,15 @@ export class MessageDeliveryEngine {
     }
     consumePendingPull(ns, throughSeq) {
         const pending = ns.startsWith('p2p:') ? this.pendingP2pPullUpper : this.pendingGroupPullUpper;
-        if ((pending?.get(ns) ?? 0) <= throughSeq)
+        if ((pending?.get(ns) ?? 0) <= throughSeq) {
             pending?.delete(ns);
+            this.pendingPullNoProgressAcks?.delete(ns);
+        }
+    }
+    markPendingPullNoProgress(ns, ack) {
+        const blocked = this.pendingPullNoProgressAcks ?? new Map();
+        this.pendingPullNoProgressAcks = blocked;
+        blocked.set(ns, ack);
     }
     schedulePendingPullIfNeeded(ns, reason) {
         const pending = ns.startsWith('p2p:') ? this.pendingP2pPullUpper : this.pendingGroupPullUpper;
@@ -170,15 +282,21 @@ export class MessageDeliveryEngine {
         const upper = pending.get(ns) ?? 0;
         if (upper <= 0) {
             pending.delete(ns);
+            this.pendingPullNoProgressAcks?.delete(ns);
             return false;
         }
         const client = this.runtime.client;
         const contiguous = client._seqTracker.getContiguousSeq(ns);
         if (upper <= contiguous) {
             pending.delete(ns);
+            this.pendingPullNoProgressAcks?.delete(ns);
             client._clientLog?.debug(`pending pull upper already covered: ns=${ns}, upper_seq=${upper}, contiguous=${contiguous}, reason=${reason}`);
             return false;
         }
+        const blockedAck = this.pendingPullNoProgressAcks?.get(ns);
+        if (blockedAck !== undefined && contiguous <= blockedAck)
+            return false;
+        this.pendingPullNoProgressAcks?.delete(ns);
         if (client.state !== ConnectionState.READY || client._closing || this.realtimeSyncing?.has(ns)
             || client._rpcPipeline?.hasPullActivity?.(ns, false))
             return false;
@@ -620,6 +738,20 @@ export class MessageDeliveryEngine {
         else if (Object.prototype.hasOwnProperty.call(row, 'ack_seq')) {
             value = row.ack_seq;
         }
+        else if (Object.prototype.hasOwnProperty.call(row, 'cursor')) {
+            const cursor = row.cursor;
+            const cursorRow = isJsonObject(cursor)
+                ? cursor
+                : null;
+            if (cursorRow) {
+                if (!Object.prototype.hasOwnProperty.call(cursorRow, 'current_seq'))
+                    return 0;
+                value = cursorRow.current_seq;
+            }
+            else {
+                value = cursor;
+            }
+        }
         else {
             return requestedSeq;
         }
@@ -640,6 +772,7 @@ export class MessageDeliveryEngine {
     }
     async confirmPlainForwardAck(ns, method, ackSeq, groupId = '') {
         const client = this.runtime.client;
+        this.ensurePullOperationCurrent();
         const coordinator = this.forwardCoordinator();
         const generation = this.captureInlineGeneration();
         coordinator.recordForwardAck(ns, ackSeq);
@@ -658,6 +791,7 @@ export class MessageDeliveryEngine {
                 _rpc_background: true,
             };
         const result = await client._rpcPipeline.rawCall(method, params, { background: true });
+        this.ensurePullOperationCurrent();
         const actualAckSeq = this.resolveForwardAckSeq(result, ackSeq);
         if (actualAckSeq < ackSeq) {
             throw new Error(`${method} server ACK watermark ${actualAckSeq} is below requested ${ackSeq}`);
@@ -675,6 +809,7 @@ export class MessageDeliveryEngine {
             throw new Error(`${method} response must be an object`);
         }
         const client = this.runtime.client;
+        this.ensurePullOperationCurrent();
         const response = result;
         const messages = deduplicatePlainForwardPageMessages(response.messages, afterSeq);
         const coordinator = this.forwardCoordinator();
@@ -705,25 +840,30 @@ export class MessageDeliveryEngine {
         let committed = false;
         try {
             for (const rawMessage of messages) {
+                this.ensurePullOperationCurrent();
                 const seq = positiveSafeSequenceHint(rawMessage.seq);
                 if (method === 'message.pull') {
                     const appEvent = p2pAppEventFromPlainPullMessage(rawMessage);
                     if (await this.publishPulledMessage(appEvent.event, ns, seq, appEvent.payload, false)) {
                         publishedCount += 1;
                     }
+                    this.ensurePullOperationCurrent();
                     continue;
                 }
                 const message = normalizeGroupMentionMode(rawMessage);
                 if (this.recallEventFromGroupMessage(message)) {
                     if (await this.publishGroupRecallTombstone(groupId, seq, message)) {
+                        this.ensurePullOperationCurrent();
                         this.markPublishedSeq(ns, seq);
                         publishedCount += 1;
                     }
                 }
                 else if (await this.publishPulledMessage('group.message_created', ns, seq, message, false)) {
+                    this.ensurePullOperationCurrent();
                     publishedCount += 1;
                 }
             }
+            this.ensurePullOperationCurrent();
             if (messages.length > 0)
                 client._seqTracker.onPullResult(ns, messages, afterSeq);
             const commitTarget = Math.max(client._seqTracker.getContiguousSeq(ns), retentionFloor, visibilityFloor, deferredServerCursor);
@@ -731,18 +871,21 @@ export class MessageDeliveryEngine {
                 client._seqTracker.forceContiguousSeq(ns, commitTarget);
             }
             if (client._seqTracker.getContiguousSeq(ns) !== pageContigBefore) {
+                this.ensurePullOperationCurrent();
                 await this.drainOrderedMessages(ns, undefined, false, false);
+                this.ensurePullOperationCurrent();
                 await client._commitSeqTrackerState(ns);
             }
             committed = true;
         }
         catch (exc) {
-            if (!committed && typeof client._seqTracker.restoreNamespaceSnapshot === 'function') {
+            if (this.isPullOperationCurrent() && !committed && typeof client._seqTracker.restoreNamespaceSnapshot === 'function') {
                 client._seqTracker.restoreNamespaceSnapshot(ns, pageTrackerSnapshot);
                 this.dropSeqTrackerPending(ns);
             }
             throw exc;
         }
+        this.ensurePullOperationCurrent();
         const committedAck = client._seqTracker.getContiguousSeq(ns);
         if (deferredServerCursor > 0 && committedAck >= deferredServerCursor) {
             coordinator.clearForwardCursor(ns, committedAck);
@@ -773,18 +916,19 @@ export class MessageDeliveryEngine {
             if (clampedAckSeq < pendingAckSeq) {
                 throw new Error(`${ackMethod} cannot confirm pending Forward watermark ${pendingAckSeq}`);
             }
+            this.ensurePullOperationCurrent();
             await this.confirmPlainForwardAck(ns, ackMethod, pendingAckSeq, groupId);
         }
         return { rawCount: messages.length, publishedCount };
     }
-    enqueueOrderedMessage(ns, event, seq, payload) {
+    enqueueOrderedMessage(ns, event, seq, payload, source = 'push') {
         const client = this.runtime.client;
         let queue = client._pendingOrderedMsgs.get(ns);
         if (!queue) {
             queue = new Map();
             client._pendingOrderedMsgs.set(ns, queue);
         }
-        queue.set(seq, { event, payload });
+        queue.set(seq, { event, payload, source });
         if (queue.size > PENDING_ORDERED_LIMIT) {
             const drop = [...queue.keys()].sort((a, b) => a - b).slice(0, queue.size - PENDING_ORDERED_LIMIT);
             for (const oldSeq of drop)
@@ -794,7 +938,7 @@ export class MessageDeliveryEngine {
     isGroupEventNamespace(ns) {
         return ns.startsWith('group_event:');
     }
-    async publishOrderedQueueItem(ns, event, seq, payload, pullResponse = false) {
+    async publishOrderedQueueItem(ns, event, seq, payload, pullResponse = false, source = 'push', batch) {
         const client = this.runtime.client;
         if (event === 'group.changed' && this.isGroupEventNamespace(ns)) {
             await this.publishOrderedGroupChanged(payload);
@@ -805,10 +949,10 @@ export class MessageDeliveryEngine {
             return;
         }
         if (pullResponse) {
-            await client._withPullResponseProcessing(ns, () => client._publishAppEvent(event, payload));
+            await client._withPullResponseProcessing(ns, () => client._publishAppEvent(event, payload, source, ns, batch));
             return;
         }
-        await client._publishAppEvent(event, payload);
+        await client._publishAppEvent(event, payload, source, ns, batch);
     }
     async publishOrderedGroupChanged(payload) {
         const client = this.runtime.client;
@@ -983,6 +1127,7 @@ export class MessageDeliveryEngine {
         setIfPresent('type', firstValue(body.type, params.type, params.message_type, params.payload_type));
         setIfPresent('kind', firstValue(body.kind, params.kind));
         setIfPresent('version', firstValue(body.version, params.version));
+        setIfPresent('message_id', firstValue(params.message_id, body.message_id, resultObj.message_id));
         setIfPresent('timestamp', firstValue(params.timestamp, resultObj.timestamp, resultObj.created_at, resultObj.t_server, Date.now()));
         envelope.encrypted = Boolean(encrypted);
         const context = this.envelopeMetadata(params.context);
@@ -1325,8 +1470,9 @@ export class MessageDeliveryEngine {
         if (contig !== contigBefore)
             this.persistSeq(ns);
     }
-    async publishAppEvent(event, payload) {
+    async publishAppEvent(event, payload, source = '', ns = '', batch) {
         const client = this.runtime.client;
+        const generation = this.deliveryGeneration;
         if ((event === 'message.received' || event === 'group.message_created') && isJsonObject(payload)) {
             client._maybeAppendEchoTraceReceive(payload);
         }
@@ -1346,7 +1492,25 @@ export class MessageDeliveryEngine {
                 client._clientLog.debug(`agent_md etag inject skipped: ${String(exc)}`);
             }
         }
-        await client._dispatcher.publish(event, this.normalizePublishedMessagePayload(event, payload));
+        client._dispatcher.enqueue(event, this.normalizePublishedMessagePayload(event, payload));
+        if (generation !== this.deliveryGeneration)
+            return;
+        if (source !== 'pull' && source !== 'tail' && source !== 'pending_retry'
+            && source !== 'push' && source !== 'inline_push')
+            return;
+        if (source === 'push' || source === 'inline_push') {
+            const localBatch = batch ?? this.createDeliveryChangeBatch(source);
+            this.recordDeliveryChange(localBatch.changes, event, payload, ns, generation);
+            if (!batch)
+                await this.flushRealtimeDeliveryChanges(localBatch);
+        }
+        else {
+            const changes = this.pendingPullDeliveryChanges ?? new Map();
+            this.pendingPullDeliveryChanges = changes;
+            this.recordDeliveryChange(changes, event, payload, ns, generation);
+            if (client._rpcPipeline?.hasAnyPullActivity?.() !== true)
+                await this.flushPullDeliveryChanges();
+        }
     }
     messageTargetsCurrentInstance(message) {
         if (!isJsonObject(message))
@@ -1502,7 +1666,7 @@ export class MessageDeliveryEngine {
         const client = this.runtime.client;
         try {
             if (!isJsonObject(data)) {
-                await client._publishAppEvent('message.received', data);
+                await client._publishAppEvent('message.received', data, 'push');
                 return;
             }
             const msg = { ...data };
@@ -1554,7 +1718,7 @@ export class MessageDeliveryEngine {
                     await client._publishEncryptedPushMessage('message.received', 'message.undecryptable', '', seq ?? 0, msg, false);
                     return;
                 }
-                await client._publishAppEvent('message.received', msg);
+                await client._publishAppEvent('message.received', msg, 'push');
             }
         }
         catch (exc) {
@@ -1598,7 +1762,7 @@ export class MessageDeliveryEngine {
         const client = this.runtime.client;
         try {
             if (!isJsonObject(data)) {
-                await client._publishAppEvent('group.message_created', data);
+                await client._publishAppEvent('group.message_created', data, 'push');
                 return;
             }
             const msg = { ...data };
@@ -1677,7 +1841,7 @@ export class MessageDeliveryEngine {
                     await client._publishEncryptedPushMessage('group.message_created', 'group.message_undecryptable', '', seq ?? 0, msg, true);
                     return;
                 }
-                await client._publishAppEvent('group.message_created', msg);
+                await client._publishAppEvent('group.message_created', msg, 'push');
             }
         }
         catch (exc) {
@@ -1761,12 +1925,15 @@ export class MessageDeliveryEngine {
             return;
         const delayMs = Math.min(P2P_GAP_FILL_RETRY_BASE_MS * retryAttempt, P2P_GAP_FILL_RETRY_MAX_MS);
         client._gapFillDone.add(retryKey);
+        const releasePullWork = client._rpcPipeline?.reservePullWork?.() ?? (() => { });
         client._clientLog.debug(`P2P message gap-fill retry scheduled: ns=${ns} attempt=${retryAttempt} delay_ms=${delayMs}`);
         globalThis.setTimeout(() => {
             client._gapFillDone.delete(retryKey);
-            if (client.state !== ConnectionState.READY || client._closing)
+            if (client.state !== ConnectionState.READY || client._closing) {
+                releasePullWork();
                 return;
-            client._safeAsync(this.fillP2pGap(retryAttempt));
+            }
+            client._safeAsync(this.fillP2pGap(retryAttempt).finally(releasePullWork));
         }, delayMs);
     }
     async fillP2pGap(retryAttempt = 0) {
@@ -2075,9 +2242,36 @@ export class MessageDeliveryEngine {
         if (!groupId)
             return;
         const ns = `group:${groupId}`;
-        client._safeAsync(this.runGroupForwardRecovery(groupId, ns, 50, true).catch((exc) => {
-            client._clientLog?.debug(`online unread hint background Forward failed: ns=${ns} err=${formatDeliveryError(exc)}`);
-        }));
+        const targets = this.onlineUnreadHintTargets ?? new Map();
+        const owners = this.onlineUnreadHintOwners ?? new Set();
+        this.onlineUnreadHintTargets = targets;
+        this.onlineUnreadHintOwners = owners;
+        targets.set(ns, Math.max(targets.get(ns) ?? 0, positiveSafeSequenceHint(data.seq)));
+        if (owners.has(ns))
+            return;
+        owners.add(ns);
+        client._safeAsync((async () => {
+            try {
+                while (true) {
+                    const throughSeq = targets.get(ns) ?? 0;
+                    const ackBefore = this.syncState(ns).ack;
+                    await this.runGroupForwardRecovery(groupId, ns, 50, true, throughSeq);
+                    const ackAfter = this.syncState(ns).ack;
+                    const target = targets.get(ns) ?? 0;
+                    if (ackAfter >= target || ackAfter <= ackBefore)
+                        return;
+                }
+            }
+            catch (exc) {
+                client._clientLog?.debug(`online unread hint background Forward failed: ns=${ns} err=${formatDeliveryError(exc)}`);
+            }
+            finally {
+                if (this.onlineUnreadHintTargets === targets)
+                    targets.delete(ns);
+                if (this.onlineUnreadHintOwners === owners)
+                    owners.delete(ns);
+            }
+        })());
     }
     enqueueOnlineUnreadEventHint(data) {
         const client = this.runtime.client;
@@ -2109,17 +2303,19 @@ export class MessageDeliveryEngine {
         const key = pipeline.pullGateKeyForCall('message.pull', request);
         return await pipeline.runPullSerialized(key, invoke, background);
     }
-    async runGroupForwardRecovery(groupId, ns, pageLimit, background = false) {
+    async runGroupForwardRecovery(groupId, ns, pageLimit, background = false, throughSeq = 0) {
         const client = this.runtime.client;
+        const state = this.syncState(ns);
+        const maxPages = this.forwardMaxPages(state.ack, throughSeq, pageLimit);
         const request = {
             group_id: groupId,
-            after_seq: this.syncState(ns).ack,
+            after_seq: state.ack,
             limit: pageLimit,
-            max_pages: 1,
+            max_pages: maxPages,
         };
         const invoke = async () => {
             const after = this.syncState(ns).ack;
-            const messages = await client._pullGroupV2(groupId, after, pageLimit, { gateLocked: true, maxPages: 1 });
+            const messages = await client._pullGroupV2(groupId, after, pageLimit, { gateLocked: true, maxPages });
             return { messages, raw_count: messages.length };
         };
         const pipeline = client._rpcPipeline;
@@ -2135,6 +2331,10 @@ export class MessageDeliveryEngine {
         const ack = Number(tracker.getContiguousSeq(ns) || 0);
         return { ack, tail: ack, head: Math.max(ack, Number(tracker.getMaxSeenSeq?.(ns) || 0)) };
     }
+    forwardMaxPages(ack, throughSeq, pageLimit) {
+        const limit = Number.isSafeInteger(pageLimit) && pageLimit > 0 ? pageLimit : 1;
+        return Math.max(1, Math.ceil(Math.max(0, throughSeq - ack) / limit));
+    }
     inlineMessage(data) {
         if (!isJsonObject(data))
             return null;
@@ -2434,7 +2634,7 @@ export class MessageDeliveryEngine {
             ? tracker.snapshotNamespace(ns)
             : null;
         try {
-            const published = await this.publishPulledMessage(event, ns, seq, payload);
+            const published = await this.publishPulledMessage(event, ns, seq, payload, true, 'inline_push');
             if (!this.isInlineGenerationCurrent(generation))
                 return false;
             if (!published)
@@ -2642,16 +2842,24 @@ export class MessageDeliveryEngine {
         // 落盘的 ack 为起点，至多补一页普通 Forward 即可恢复该小窗口。
         const tailMissedDuringPull = tailCompleted
             && Number(client._seqTracker.getMaxSeenSeq(ns) || 0) > state.head;
+        const maxSeen = Number(client._seqTracker.getMaxSeenSeq(ns) || 0);
         const pendingThroughSeq = tailMissedDuringPull
-            ? Number(client._seqTracker.getMaxSeenSeq(ns) || 0)
+            ? maxSeen
             : 0;
         const tailForward = tailCompleted && (state.ack < state.tail - 1 || tailMissedDuringPull);
         const backgroundWindowForward = order[0] === 'forward' && !headForward;
         if (headForward || tailForward
             || (client._sessionOptions?.background_sync !== false && backgroundWindowForward)) {
-            result = await run(false, !(headForward || tailForward), headForward ? 2 : order[0] === 'tail' ? 1 : undefined, headForward || tailMissedDuringPull);
-            if (pendingThroughSeq > 0)
-                this.consumePendingPull(ns, pendingThroughSeq);
+            const forwardTarget = Math.max(headForward ? Math.max(pushSeq, maxSeen) : 0, (tailForward || backgroundWindowForward) ? state.tail - 1 : 0, tailMissedDuringPull ? maxSeen : 0);
+            const forwardMaxPages = this.forwardMaxPages(state.ack, forwardTarget, pageLimit);
+            result = await run(false, !(headForward || tailForward), forwardMaxPages, headForward || tailMissedDuringPull);
+            if (pendingThroughSeq > 0) {
+                const committedAck = this.syncState(ns).ack;
+                if (committedAck >= pendingThroughSeq)
+                    this.consumePendingPull(ns, pendingThroughSeq);
+                else if (committedAck <= state.ack)
+                    this.markPendingPullNoProgress(ns, committedAck);
+            }
         }
         const finalState = this.syncState(ns);
         if (tailCompleted && finalState.ack < finalState.tail - 1) {
@@ -2706,16 +2914,24 @@ export class MessageDeliveryEngine {
         // 期间新到达的序号；绝不重新规划或再执行 Tail。
         const tailMissedDuringPull = tailCompleted
             && Number(client._seqTracker.getMaxSeenSeq(ns) || 0) > state.head;
+        const maxSeen = Number(client._seqTracker.getMaxSeenSeq(ns) || 0);
         const pendingThroughSeq = tailMissedDuringPull
-            ? Number(client._seqTracker.getMaxSeenSeq(ns) || 0)
+            ? maxSeen
             : 0;
         const tailForward = tailCompleted && (state.ack < state.tail - 1 || tailMissedDuringPull);
         const backgroundWindowForward = order[0] === 'forward' && !headForward;
         if (headForward || tailForward
             || (client._sessionOptions?.background_sync !== false && backgroundWindowForward)) {
-            result = await run(false, !(headForward || tailForward), headForward ? 2 : order[0] === 'tail' ? 1 : undefined, headForward || tailMissedDuringPull);
-            if (pendingThroughSeq > 0)
-                this.consumePendingPull(ns, pendingThroughSeq);
+            const forwardTarget = Math.max(headForward ? Math.max(pushSeq, maxSeen) : 0, (tailForward || backgroundWindowForward) ? state.tail - 1 : 0, tailMissedDuringPull ? maxSeen : 0);
+            const forwardMaxPages = this.forwardMaxPages(state.ack, forwardTarget, pageLimit);
+            result = await run(false, !(headForward || tailForward), forwardMaxPages, headForward || tailMissedDuringPull);
+            if (pendingThroughSeq > 0) {
+                const committedAck = this.syncState(ns).ack;
+                if (committedAck >= pendingThroughSeq)
+                    this.consumePendingPull(ns, pendingThroughSeq);
+                else if (committedAck <= state.ack)
+                    this.markPendingPullNoProgress(ns, committedAck);
+            }
         }
         const finalState = this.syncState(ns);
         if (tailCompleted && finalState.ack < finalState.tail - 1) {
@@ -2998,13 +3214,13 @@ export class MessageDeliveryEngine {
             }
         }
         catch (exc) {
-            client._dispatcher.publish('seq_tracker.persist_error', {
+            client._dispatcher.enqueue('seq_tracker.persist_error', {
                 phase: 'restore',
                 aid,
                 device_id: deviceId,
                 slot_id: slotId,
                 error: String(exc),
-            }).catch(() => { });
+            });
         }
     }
     async migrateSeqStateGroupIds(state) {
@@ -3212,13 +3428,13 @@ export class MessageDeliveryEngine {
         catch (exc) {
             const error = formatDeliveryError(exc);
             client._clientLog.warn(`save SeqTracker state failed: ${error}`);
-            client._dispatcher.publish('seq_tracker.persist_error', {
+            client._dispatcher.enqueue('seq_tracker.persist_error', {
                 phase: 'save',
                 aid,
                 device_id: deviceId,
                 slot_id: slotId,
                 error: String(error),
-            }).catch(() => { });
+            });
             if (throwOnError)
                 throw exc;
         }
@@ -3337,8 +3553,9 @@ export class MessageDeliveryEngine {
         }
         return params;
     }
-    async drainOrderedMessages(ns, beforeSeq, pullResponse = false, persist = true) {
+    async drainOrderedMessages(ns, beforeSeq, pullResponse = false, persist = true, batch, source = 'pull') {
         const client = this.runtime.client;
+        this.ensurePullOperationCurrent();
         const queue = client._pendingOrderedMsgs.get(ns);
         if (!queue || queue.size === 0)
             return;
@@ -3347,83 +3564,128 @@ export class MessageDeliveryEngine {
             .filter((seq) => seq <= contig && (beforeSeq === undefined || seq < beforeSeq))
             .sort((a, b) => a - b);
         let delivered = false;
-        for (const seq of ready) {
-            const item = queue.get(seq);
-            queue.delete(seq);
-            if (!item || client._pushedSeqs.get(ns)?.has(seq))
-                continue;
-            await this.publishOrderedQueueItem(ns, item.event, seq, item.payload, pullResponse);
-            this.markPublishedSeq(ns, seq);
-            delivered = true;
+        const drainBatches = new Map();
+        try {
+            for (const seq of ready) {
+                this.ensurePullOperationCurrent();
+                const item = queue.get(seq);
+                queue.delete(seq);
+                if (!item || client._pushedSeqs.get(ns)?.has(seq))
+                    continue;
+                const itemSource = item.source ?? source;
+                let itemBatch = batch;
+                if ((itemSource === 'push' || itemSource === 'inline_push')
+                    && (!batch || batch.trigger !== itemSource)) {
+                    itemBatch = drainBatches.get(itemSource);
+                    if (!itemBatch) {
+                        itemBatch = this.createDeliveryChangeBatch(itemSource);
+                        drainBatches.set(itemSource, itemBatch);
+                    }
+                }
+                await this.publishOrderedQueueItem(ns, item.event, seq, item.payload, pullResponse, itemSource, itemBatch);
+                this.ensurePullOperationCurrent();
+                this.markPublishedSeq(ns, seq);
+                delivered = true;
+            }
+        }
+        finally {
+            for (const drainBatch of drainBatches.values()) {
+                await this.flushRealtimeDeliveryChanges(drainBatch);
+            }
         }
         if (queue.size === 0) {
             client._pendingOrderedMsgs.delete(ns);
-            if (delivered && persist)
+            if (delivered && persist) {
+                this.ensurePullOperationCurrent();
                 await this.saveSeqTrackerState();
+            }
         }
     }
-    async publishOrderedMessage(event, ns, seq, payload) {
+    async publishOrderedMessage(event, ns, seq, payload, source = 'push', operationBatch) {
         const client = this.runtime.client;
-        const seqNum = Number(seq);
-        if (!Number.isFinite(seqNum) || !Number.isInteger(seqNum) || seqNum <= 0) {
-            await this.publishOrderedQueueItem(ns, event, seqNum, payload);
-            return true;
-        }
-        if (client._pushedSeqs.get(ns)?.has(seqNum)) {
+        const ownsBatch = !operationBatch && (source === 'push' || source === 'inline_push');
+        const batch = operationBatch ?? (ownsBatch ? this.createDeliveryChangeBatch(source) : undefined);
+        try {
+            const seqNum = Number(seq);
+            if (!Number.isFinite(seqNum) || !Number.isInteger(seqNum) || seqNum <= 0) {
+                await this.publishOrderedQueueItem(ns, event, seqNum, payload, false, source, batch);
+                return true;
+            }
+            if (client._pushedSeqs.get(ns)?.has(seqNum)) {
+                const queue = client._pendingOrderedMsgs.get(ns);
+                queue?.delete(seqNum);
+                if (queue && queue.size === 0)
+                    client._pendingOrderedMsgs.delete(ns);
+                return false;
+            }
+            const contig = client._seqTracker.getContiguousSeq(ns);
+            if (seqNum > contig) {
+                this.enqueueOrderedMessage(ns, event, seqNum, payload, source);
+                return false;
+            }
+            await this.drainOrderedMessages(ns, seqNum, true, true, batch, source);
+            if (client._pushedSeqs.get(ns)?.has(seqNum))
+                return false;
             const queue = client._pendingOrderedMsgs.get(ns);
             queue?.delete(seqNum);
             if (queue && queue.size === 0)
                 client._pendingOrderedMsgs.delete(ns);
-            return false;
+            await this.publishOrderedQueueItem(ns, event, seqNum, payload, false, source, batch);
+            this.markPublishedSeq(ns, seqNum);
+            await this.drainOrderedMessages(ns, undefined, false, true, batch, source);
+            if (!client._pendingOrderedMsgs.get(ns))
+                await this.saveSeqTrackerState();
+            return true;
         }
-        const contig = client._seqTracker.getContiguousSeq(ns);
-        if (seqNum > contig) {
-            this.enqueueOrderedMessage(ns, event, seqNum, payload);
-            return false;
+        finally {
+            if (ownsBatch && batch)
+                await this.flushRealtimeDeliveryChanges(batch);
         }
-        await this.drainOrderedMessages(ns, seqNum, true);
-        if (client._pushedSeqs.get(ns)?.has(seqNum))
-            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);
-        this.markPublishedSeq(ns, seqNum);
-        await this.drainOrderedMessages(ns);
-        if (!client._pendingOrderedMsgs.get(ns))
-            await this.saveSeqTrackerState();
-        return true;
     }
-    async publishPulledMessage(event, ns, seq, payload, persist = true) {
+    async publishPulledMessage(event, ns, seq, payload, persist = true, source = 'pull', operationBatch) {
         const client = this.runtime.client;
-        const seqNum = Number(seq);
-        if (!Number.isFinite(seqNum) || !Number.isInteger(seqNum) || seqNum <= 0 || !ns) {
-            if (event === 'message.recalled') {
-                return await client._withPullResponseProcessing(ns, () => this.publishMessageRecallTombstone(seq, payload));
+        const ownsBatch = !operationBatch && (source === 'push' || source === 'inline_push');
+        const batch = operationBatch ?? (ownsBatch ? this.createDeliveryChangeBatch(source) : undefined);
+        try {
+            this.ensurePullOperationCurrent();
+            const seqNum = Number(seq);
+            if (!Number.isFinite(seqNum) || !Number.isInteger(seqNum) || seqNum <= 0 || !ns) {
+                if (event === 'message.recalled') {
+                    const published = await client._withPullResponseProcessing(ns, () => this.publishMessageRecallTombstone(seq, payload));
+                    this.ensurePullOperationCurrent();
+                    return published;
+                }
+                await client._withPullResponseProcessing(ns, () => client._publishAppEvent(event, payload, source, ns, batch));
+                this.ensurePullOperationCurrent();
+                return true;
             }
-            await client._withPullResponseProcessing(ns, () => client._publishAppEvent(event, payload));
-            return true;
-        }
-        const queue = client._pendingOrderedMsgs.get(ns);
-        if (client._pushedSeqs.get(ns)?.has(seqNum)) {
+            const queue = client._pendingOrderedMsgs.get(ns);
+            if (client._pushedSeqs.get(ns)?.has(seqNum)) {
+                queue?.delete(seqNum);
+                if (queue && queue.size === 0)
+                    client._pendingOrderedMsgs.delete(ns);
+                return false;
+            }
+            await this.drainOrderedMessages(ns, seqNum, false, persist, batch, source);
+            this.ensurePullOperationCurrent();
             queue?.delete(seqNum);
             if (queue && queue.size === 0)
                 client._pendingOrderedMsgs.delete(ns);
-            return false;
-        }
-        await this.drainOrderedMessages(ns, seqNum, false, persist);
-        queue?.delete(seqNum);
-        if (queue && queue.size === 0)
-            client._pendingOrderedMsgs.delete(ns);
-        if (event === 'message.recalled') {
-            const published = await client._withPullResponseProcessing(ns, () => this.publishMessageRecallTombstone(seqNum, payload));
+            if (event === 'message.recalled') {
+                const published = await client._withPullResponseProcessing(ns, () => this.publishMessageRecallTombstone(seqNum, payload));
+                this.ensurePullOperationCurrent();
+                this.markPublishedSeq(ns, seqNum);
+                return published;
+            }
+            await client._withPullResponseProcessing(ns, () => client._publishAppEvent(event, payload, source, ns, batch));
+            this.ensurePullOperationCurrent();
             this.markPublishedSeq(ns, seqNum);
-            return published;
+            return true;
+        }
+        finally {
+            if (ownsBatch && batch)
+                await this.flushRealtimeDeliveryChanges(batch);
         }
-        await client._withPullResponseProcessing(ns, () => client._publishAppEvent(event, payload));
-        this.markPublishedSeq(ns, seqNum);
-        return true;
     }
 }
 //# sourceMappingURL=delivery.js.map