@agentunion/fastaun 0.5.8 → 0.5.10

package/dist/client/delivery.js

@@ -1,11 +1,16 @@
 import { slotIsolationKey } from '../config.js';
 import { ConnectionState, isJsonObject } from '../types.js';
+import { validateGroupAIDFormat } from '../validators.js';
 import { hasGroupMentionModeField, normalizeGroupMentionMode } from './mention-mode.js';
 const PUSHED_SEQS_LIMIT = 50_000;
 const PENDING_ORDERED_LIMIT = 50_000;
 const MESSAGE_RECALL_SEEN_LIMIT = 10_000;
 const GROUP_RECALL_SEEN_LIMIT = 10_000;
 const SEQ_TRACKER_PERSIST_FLUSH_DELAY_MS = 200;
+const DELIVERY_CHANGED_MESSAGE_EVENTS = new Set([
+    'message.received',
+    'group.message_created',
+]);
 const MAX_INLINE_PENDING_ACK_NAMESPACES = 4096;
 const APP_MESSAGE_ENVELOPE_KEYS = [
     'module_id', 'message_type', 'type', 'kind', 'version',
@@ -67,15 +72,33 @@ export class MessageDeliveryEngine {
     realtimeTailHeads = null;
     realtimeSyncing = null;
     pendingGroupPullUpper = null;
+    onlineUnreadHintTargets = null;
+    onlineUnreadHintTasks = null;
     pendingP2PInlineAcks = null;
     pendingGroupInlineAcks = null;
     pendingGroupInlineAckNamespaces = null;
     inlineAckGeneration = 0;
+    pendingDeliveryChanges = null;
+    deliveryChangedGeneration = 0;
     // 同一实例的 tracker 写入必须串行，避免旧的延迟 flush 覆盖新的 Forward 提交。
     seqTrackerWriteChain = Promise.resolve();
     constructor(runtime) {
         this.runtime = runtime;
     }
+    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');
+    }
     forwardCoordinator() {
         const coordinator = this.runtime.client._v2E2EE;
         if (!coordinator
@@ -91,6 +114,7 @@ export class MessageDeliveryEngine {
     }
     async confirmPlainForwardAck(ns, method, ackSeq, groupId = '') {
         const client = this.runtime.client;
+        this.ensurePullOperationCurrent();
         const coordinator = this.forwardCoordinator();
         const generation = this.captureInlineAckGeneration();
         coordinator.recordForwardAck(ns, ackSeq);
@@ -109,6 +133,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}`);
@@ -126,6 +151,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();
@@ -156,25 +182,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 = this.p2pAppEventForMessage(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);
@@ -182,18 +213,21 @@ export class MessageDeliveryEngine {
                 client._seqTracker.forceContiguousSeq(ns, commitTarget);
             }
             if (client._seqTracker.getContiguousSeq(ns) !== pageContigBefore) {
-                await this.drainOrderedMessages(ns, undefined, false, false);
+                this.ensurePullOperationCurrent();
+                await this.drainOrderedMessages(ns, undefined, false, false, 'pull');
+                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);
@@ -224,19 +258,132 @@ 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 };
     }
     resetInlineAckState() {
+        this.deliveryChangedGeneration += 1;
+        this.pendingDeliveryChanges = null;
         this.inlineAckGeneration += 1;
+        void this.runtime.client._rpcPipeline?.invalidatePulls?.();
         this.pendingP2PInlineAcks = null;
         this.pendingGroupInlineAcks = null;
         this.pendingGroupInlineAckNamespaces = null;
         this.realtimeSyncing = null;
         this.pendingGroupPullUpper = null;
+        this.onlineUnreadHintTargets = null;
+        this.onlineUnreadHintTasks = null;
         this.realtimeTailHeads = null;
     }
+    deliveryChangedNamespace(event, payload) {
+        if (event === 'group.message_created' && isJsonObject(payload)) {
+            const aid = String(this.runtime.client._aid ?? '').trim();
+            const dot = aid.indexOf('.');
+            try {
+                const groupAid = validateGroupAIDFormat(payload.group_aid ?? payload.group_id, { localIssuer: dot >= 0 ? aid.slice(dot + 1) : '' });
+                return groupAid.includes('.') ? `group:${groupAid}` : '';
+            }
+            catch {
+                return '';
+            }
+        }
+        return 'p2p';
+    }
+    isDeliveryChangedMessage(event, payload) {
+        if (!DELIVERY_CHANGED_MESSAGE_EVENTS.has(event)
+            || !isJsonObject(payload))
+            return false;
+        const messageId = payload.message_id;
+        const seq = payload.seq;
+        return (typeof messageId === 'string' && messageId.trim().length > 0)
+            || (typeof seq === 'number' && Number.isSafeInteger(seq) && seq > 0);
+    }
+    deliveryChangedTrigger(source) {
+        if (source === 'inline-push')
+            return 'inline_push';
+        if (source === 'pull' || source === 'tail')
+            return 'pull_drained';
+        if (source === 'push' || source === 'group-push' || source === 'ordered')
+            return 'push';
+        return null;
+    }
+    noteDeliveryChanged(event, payload, source, context) {
+        if (!this.isDeliveryChangedMessage(event, payload))
+            return;
+        const trigger = this.deliveryChangedTrigger(source);
+        const namespace = this.deliveryChangedNamespace(event, payload);
+        if (!trigger || !namespace)
+            return;
+        const pending = trigger === 'pull_drained'
+            ? this.pendingDeliveryChanges ?? new Map()
+            : context?.changes ?? this.pendingDeliveryChanges ?? new Map();
+        if (trigger === 'pull_drained' || !context)
+            this.pendingDeliveryChanges = pending;
+        pending.set(namespace, (pending.get(namespace) ?? 0) + 1);
+        if (!context && trigger !== 'pull_drained')
+            this.flushDeliveryChanged(trigger);
+    }
+    flushDeliveryChanged(trigger) {
+        const pending = this.pendingDeliveryChanges;
+        if (!pending || pending.size === 0)
+            return;
+        const changes = [...pending.entries()]
+            .filter(([, deliveredCount]) => deliveredCount > 0)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([namespace, deliveredCount]) => ({ namespace, delivered_count: deliveredCount }));
+        pending.clear();
+        if (changes.length === 0)
+            return;
+        const payload = { trigger, changes };
+        const dispatcher = this.runtime.client._dispatcher;
+        const published = typeof dispatcher.enqueue === 'function'
+            ? (dispatcher.enqueue('delivery.changed', payload), undefined)
+            : typeof dispatcher.publishSyncAware === 'function'
+                ? dispatcher.publishSyncAware('delivery.changed', payload)
+                : dispatcher.publish?.('delivery.changed', payload);
+        if (isPromiseLike(published))
+            void Promise.resolve(published).catch((exc) => {
+                this.runtime.client._clientLog.warn(`delivery.changed handler failed: ${formatDeliveryError(exc)}`);
+            });
+    }
+    onPullDrained() {
+        this.flushDeliveryChanged('pull_drained');
+    }
+    flushDeliveryChangedContext(context, trigger) {
+        if (context.generation !== this.deliveryChangedGeneration || context.changes.size === 0)
+            return;
+        const pending = this.pendingDeliveryChanges;
+        if (pending) {
+            for (const [namespace, count] of pending) {
+                context.changes.set(namespace, (context.changes.get(namespace) ?? 0) + count);
+            }
+            pending.clear();
+        }
+        const changes = [...context.changes.entries()]
+            .filter(([, count]) => count > 0)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([namespace, delivered_count]) => ({ namespace, delivered_count }));
+        context.changes.clear();
+        if (changes.length === 0)
+            return;
+        const dispatcher = this.runtime.client._dispatcher;
+        const payload = { trigger, changes };
+        const published = typeof dispatcher.enqueue === 'function'
+            ? (dispatcher.enqueue('delivery.changed', payload), undefined)
+            : typeof dispatcher.publishSyncAware === 'function'
+                ? dispatcher.publishSyncAware('delivery.changed', payload)
+                : dispatcher.publish?.('delivery.changed', payload);
+        if (isPromiseLike(published))
+            void Promise.resolve(published).catch((exc) => {
+                this.runtime.client._clientLog.warn(`delivery.changed handler failed: ${formatDeliveryError(exc)}`);
+            });
+    }
+    invalidateDeliveryChanges() {
+        this.deliveryChangedGeneration += 1;
+        this.pendingDeliveryChanges = null;
+    }
     inlineGenerationIsCurrent(generation) {
         return this.inlineAckGeneration === generation;
     }
@@ -279,10 +426,17 @@ export class MessageDeliveryEngine {
     }
     endRealtimeSync(ns) {
         this.realtimeSyncing?.delete(ns);
+        this.runtime.client._rpcPipeline?.requestPullDrainedCheck?.();
     }
     hasPendingPull(ns) {
         return (this.pendingGroupPullUpper?.get(ns) ?? 0) > 0;
     }
+    hasAnyPendingPull() {
+        return [...(this.pendingGroupPullUpper?.values() ?? [])].some((seq) => seq > 0)
+            || Boolean(this.onlineUnreadHintTasks?.size)
+            || Boolean(this.realtimeSyncing?.size)
+            || Boolean(this.runtime.client._v2E2EE?.hasPendingSenderIKWork?.());
+    }
     onPullGateIdle(ns) {
         if (!ns)
             return;
@@ -347,14 +501,14 @@ export class MessageDeliveryEngine {
             client._pushedSeqs.set(ns, new Set(keep));
         }
     }
-    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)
@@ -364,26 +518,30 @@ export class MessageDeliveryEngine {
     isGroupEventNamespace(ns) {
         return ns.startsWith('group_event:');
     }
-    async publishOrderedQueueItem(ns, event, seq, payload, source, pullResponse = false) {
+    async publishOrderedQueueItem(ns, event, seq, payload, source, pullResponse = false, deliveryContext) {
         const client = this.runtime.client;
+        this.ensurePullOperationCurrent();
         if (event === 'group.changed' && this.isGroupEventNamespace(ns)) {
             await this.publishOrderedGroupChanged(payload, source);
+            this.ensurePullOperationCurrent();
             return;
         }
         if (event === 'message.recalled') {
             await this.publishMessageRecallTombstone(seq, payload);
+            this.ensurePullOperationCurrent();
             return;
         }
         if (pullResponse) {
-            const published = client._withPullResponseProcessing(ns, () => client._publishAppEvent(event, payload, source));
+            const published = client._withPullResponseProcessing(ns, () => this.publishAppEvent(event, payload, source, deliveryContext));
             if (isPromiseLike(published))
                 await published;
         }
         else {
-            const published = client._publishAppEvent(event, payload, source);
+            const published = this.publishAppEvent(event, payload, source, deliveryContext);
             if (isPromiseLike(published))
                 await published;
         }
+        this.ensurePullOperationCurrent();
     }
     async publishOrderedGroupChanged(payload, source = 'ordered') {
         const client = this.runtime.client;
@@ -899,7 +1057,7 @@ export class MessageDeliveryEngine {
         if (contig !== contigBefore)
             this.persistSeq(ns);
     }
-    publishAppEvent(event, payload, source = 'direct') {
+    publishAppEvent(event, payload, source = 'direct', deliveryContext) {
         const client = this.runtime.client;
         if ((event === 'message.received' || event === 'group.message_created') && isJsonObject(payload)) {
             client._maybeAppendEchoTraceReceive(payload);
@@ -919,7 +1077,23 @@ export class MessageDeliveryEngine {
                 client._clientLog.debug(`agent_md etag inject skipped: ${err instanceof Error ? err.message : String(err)}`);
             }
         }
-        return client._dispatcher.publishSyncAware(event, this.normalizePublishedMessagePayload(event, payload));
+        const generation = this.deliveryChangedGeneration;
+        const normalized = this.normalizePublishedMessagePayload(event, payload);
+        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 note = () => {
+            if (generation === this.deliveryChangedGeneration) {
+                this.noteDeliveryChanged(event, payload, source, deliveryContext);
+            }
+        };
+        if (isPromiseLike(result))
+            return Promise.resolve(result).then(note);
+        note();
+        return result;
     }
     messagePayloadForDebug(message) {
         if (!isJsonObject(message))
@@ -1938,6 +2112,18 @@ export class MessageDeliveryEngine {
             raw = response.effective_ack_seq;
         else if (Object.prototype.hasOwnProperty.call(response, 'ack_seq'))
             raw = response.ack_seq;
+        else if (Object.prototype.hasOwnProperty.call(response, 'cursor')) {
+            const cursor = response.cursor;
+            const cursorObject = isJsonObject(cursor) ? cursor : null;
+            if (cursorObject) {
+                if (!Object.prototype.hasOwnProperty.call(cursorObject, 'current_seq'))
+                    return 0;
+                raw = cursorObject.current_seq;
+            }
+            else {
+                raw = cursor;
+            }
+        }
         else
             return requestedSeq;
         return typeof raw === 'number' && Number.isSafeInteger(raw) && raw >= 0 ? raw : 0;
@@ -2020,19 +2206,20 @@ export class MessageDeliveryEngine {
         const state = this.syncState(ns);
         const needsForward = state.ack < state.tail - 1;
         const backgroundEnabled = client._sessionOptions?.background_sync !== false;
-        // Tail 期间到达的新 Push 可能只更新 maxSeen 而没有扩展 Tail 窗口；
-        // 仍须在本次 Tail 周期内补一页 Forward，不能交给外层重复恢复。
-        const tailMissedDuringPull = tailHead !== null
-            && Number(client._seqTracker.getMaxSeenSeq?.(ns) ?? 0) > state.head;
+        // Tail 期间到达的新 Push 可能只更新 maxSeen 而没有扩展 Tail 窗口。
+        const maxSeen = Number(client._seqTracker.getMaxSeenSeq?.(ns) ?? 0);
+        const tailMissedDuringPull = tailHead !== null && maxSeen > state.head;
         const tailForward = tailHead !== null && (needsForward || tailMissedDuringPull);
         const backgroundWindowForward = (order.length === 1 && order[0] === 'forward' && !headForward)
             || (order.length === 1 && order[0] === 'tail' && tailHead === null && needsForward);
         const foregroundForward = headForward || tailForward;
         if (foregroundForward || backgroundEnabled && backgroundWindowForward) {
+            const forwardTarget = Math.max(headForward ? pushSeq : 0, tailForward || backgroundWindowForward ? state.tail - 1 : 0, tailMissedDuringPull ? maxSeen : 0);
+            const requiredPages = Math.max(1, Math.ceil(Math.max(0, forwardTarget - state.ack) / pageLimit));
             result = await run({
                 after_seq: state.ack,
                 limit: pageLimit,
-                ...(headForward ? { max_pages: 2 } : order[0] === 'tail' ? { max_pages: 1 } : {}),
+                ...(headForward ? { max_pages: Math.max(2, requiredPages) } : order[0] === 'tail' ? { max_pages: requiredPages } : {}),
             }, !foregroundForward, headForward || tailMissedDuringPull);
         }
         if (tailHead !== null && this.syncState(ns).ack < this.syncState(ns).tail - 1) {
@@ -2094,18 +2281,19 @@ export class MessageDeliveryEngine {
         const state = this.syncState(ns);
         const needsForward = state.ack < state.tail - 1;
         const backgroundEnabled = client._sessionOptions?.background_sync !== false;
-        // 与 P2P 对称：Tail 期间出现的新 Push 在本次周期内补一页 Forward。
-        const tailMissedDuringPull = tailHead !== null
-            && Number(client._seqTracker.getMaxSeenSeq?.(ns) ?? 0) > state.head;
+        const maxSeen = Number(client._seqTracker.getMaxSeenSeq?.(ns) ?? 0);
+        const tailMissedDuringPull = tailHead !== null && maxSeen > state.head;
         const tailForward = tailHead !== null && (needsForward || tailMissedDuringPull);
         const backgroundWindowForward = (order.length === 1 && order[0] === 'forward' && !headForward)
             || (order.length === 1 && order[0] === 'tail' && tailHead === null && needsForward);
         const foregroundForward = headForward || tailForward;
         if (foregroundForward || backgroundEnabled && backgroundWindowForward) {
+            const forwardTarget = Math.max(headForward ? pushSeq : 0, tailForward || backgroundWindowForward ? state.tail - 1 : 0, tailMissedDuringPull ? maxSeen : 0);
+            const requiredPages = Math.max(1, Math.ceil(Math.max(0, forwardTarget - state.ack) / pageLimit));
             result = await run({
                 after_seq: state.ack,
                 limit: pageLimit,
-                ...(headForward ? { max_pages: 2 } : order[0] === 'tail' ? { max_pages: 1 } : {}),
+                ...(headForward ? { max_pages: Math.max(2, requiredPages) } : order[0] === 'tail' ? { max_pages: requiredPages } : {}),
             }, !foregroundForward, headForward || tailMissedDuringPull);
         }
         if (tailHead !== null && this.syncState(ns).ack < this.syncState(ns).tail - 1) {
@@ -2129,12 +2317,14 @@ export class MessageDeliveryEngine {
         const key = client._rpcPipeline.pullGateKeyForCall('message.pull', request);
         return await client._rpcPipeline.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 request = { group_id: groupId, after_seq: this.syncState(ns).ack, limit: pageLimit, max_pages: 1 };
+        const ack = this.syncState(ns).ack;
+        const maxPages = Math.max(1, Math.ceil(Math.max(0, throughSeq - ack) / pageLimit));
+        const request = { group_id: groupId, after_seq: ack, limit: pageLimit, 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 };
         };
         if (!client._rpcPipeline)
@@ -2770,9 +2960,35 @@ 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 tasks = this.onlineUnreadHintTasks ?? new Map();
+        this.onlineUnreadHintTargets = targets;
+        this.onlineUnreadHintTasks = tasks;
+        targets.set(ns, Math.max(targets.get(ns) ?? 0, positiveSafeSequenceHint(data.seq)));
+        if (tasks.has(ns))
+            return;
+        const task = Promise.resolve().then(async () => {
+            try {
+                while (true) {
+                    const ackBefore = this.syncState(ns).ack;
+                    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)
+                        return;
+                }
+            }
+            catch (exc) {
+                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);
+                client._rpcPipeline?.requestPullDrainedCheck?.();
+            }
+        });
+        tasks.set(ns, task);
+        client._safeAsync(task);
     }
     async onRawGroupV2MessageCreated(data, expectedVersion, inlineGeneration) {
         const client = this.runtime.client;
@@ -2899,13 +3115,13 @@ export class MessageDeliveryEngine {
         catch (exc) {
             const error = formatDeliveryError(exc);
             client._clientLog.warn(`restore SeqTracker state failed: ${error}`);
-            client._dispatcher.publish('seq_tracker.persist_error', {
+            client._dispatcher.enqueue('seq_tracker.persist_error', {
                 phase: 'restore',
                 aid: client._aid,
                 device_id: client._deviceId,
                 slot_id: client._slotId,
                 error: String(error),
-            }).catch(() => { });
+            });
         }
     }
     migrateSeqStateGroupIds(state) {
@@ -3124,13 +3340,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;
         }
@@ -3248,55 +3464,106 @@ export class MessageDeliveryEngine {
         }
         return params;
     }
-    async drainOrderedMessages(ns, beforeSeq, pullResponse = false, persist = true) {
+    async drainOrderedMessages(ns, beforeSeq, pullResponse = false, persist = true, source = 'push', context) {
         const client = this.runtime.client;
+        this.ensurePullOperationCurrent();
         const queue = client._pendingOrderedMsgs.get(ns);
         if (!queue || queue.size === 0)
             return;
         let delivered = false;
-        while (true) {
-            const contig = client._seqTracker.getContiguousSeq(ns);
-            const ready = [...queue.keys()]
-                .filter((seq) => seq <= contig && (beforeSeq === undefined || seq < beforeSeq))
-                .sort((a, b) => a - b);
-            let seq = ready[0];
-            if (seq === undefined) {
-                const nextSeq = contig + 1;
-                if (beforeSeq !== undefined && nextSeq >= beforeSeq)
-                    break;
-                if (!queue.has(nextSeq))
-                    break;
-                seq = nextSeq;
-            }
-            if (seq === undefined)
-                continue;
-            const item = queue.get(seq);
-            queue.delete(seq);
-            if (!item)
-                continue;
-            if (client._pushedSeqs.get(ns)?.has(seq)) {
-                client._clientLog.debug(`publish ordered drain skipped duplicate: ns=${ns}, seq=${seq}, event=${item.event}`);
+        const rootTrigger = this.deliveryChangedTrigger(source);
+        const drainContexts = new Map();
+        try {
+            while (true) {
+                this.ensurePullOperationCurrent();
+                const contig = client._seqTracker.getContiguousSeq(ns);
+                const ready = [...queue.keys()]
+                    .filter((seq) => seq <= contig && (beforeSeq === undefined || seq < beforeSeq))
+                    .sort((a, b) => a - b);
+                let seq = ready[0];
+                if (seq === undefined) {
+                    const nextSeq = contig + 1;
+                    if (beforeSeq !== undefined && nextSeq >= beforeSeq)
+                        break;
+                    if (!queue.has(nextSeq))
+                        break;
+                    seq = nextSeq;
+                }
+                if (seq === undefined)
+                    continue;
+                const item = queue.get(seq);
+                queue.delete(seq);
+                if (!item)
+                    continue;
+                if (client._pushedSeqs.get(ns)?.has(seq)) {
+                    client._clientLog.debug(`publish ordered drain skipped duplicate: ns=${ns}, seq=${seq}, event=${item.event}`);
+                    client._markOrderedSeqDelivered(ns, seq);
+                    continue;
+                }
+                const itemSource = item.source ?? source;
+                const itemTrigger = this.deliveryChangedTrigger(itemSource);
+                let itemContext = itemTrigger === rootTrigger ? context : undefined;
+                if (itemTrigger === 'push' || itemTrigger === 'inline_push') {
+                    if (!itemContext) {
+                        itemContext = drainContexts.get(itemTrigger);
+                        if (!itemContext) {
+                            itemContext = { generation: this.deliveryChangedGeneration, changes: new Map() };
+                            drainContexts.set(itemTrigger, itemContext);
+                        }
+                    }
+                }
+                await this.publishOrderedQueueItem(ns, item.event, seq, item.payload, itemSource, pullResponse, itemContext);
+                this.ensurePullOperationCurrent();
+                this.markPublishedSeq(ns, seq);
                 client._markOrderedSeqDelivered(ns, seq);
-                continue;
+                delivered = true;
+                client._clientLog.debug(`publish ordered drain delivered: ns=${ns}, seq=${seq}, event=${item.event}`);
+            }
+        }
+        finally {
+            for (const [trigger, drainContext] of drainContexts) {
+                if (drainContext !== context)
+                    this.flushDeliveryChangedContext(drainContext, trigger);
             }
-            await this.publishOrderedQueueItem(ns, item.event, seq, item.payload, 'ordered-drain', pullResponse);
-            this.markPublishedSeq(ns, seq);
-            client._markOrderedSeqDelivered(ns, seq);
-            delivered = true;
-            client._clientLog.debug(`publish ordered drain delivered: ns=${ns}, seq=${seq}, event=${item.event}`);
         }
         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') {
+        const context = {
+            generation: this.deliveryChangedGeneration,
+            changes: new Map(),
+        };
+        try {
+            return await this.publishOrderedMessageInternal(event, ns, seq, payload, source, context);
+        }
+        finally {
+            const trigger = this.deliveryChangedTrigger(source);
+            if (trigger === 'pull_drained' && context.generation === this.deliveryChangedGeneration) {
+                const pending = this.pendingDeliveryChanges ?? new Map();
+                this.pendingDeliveryChanges = pending;
+                for (const [namespace, count] of context.changes) {
+                    pending.set(namespace, (pending.get(namespace) ?? 0) + count);
+                }
+            }
+            else if (trigger && trigger !== 'pull_drained') {
+                this.flushDeliveryChangedContext(context, trigger);
+            }
+        }
+    }
+    async publishOrderedMessageInternal(event, ns, seq, payload, source, context) {
         const client = this.runtime.client;
+        this.ensurePullOperationCurrent();
         const seqNum = Number(seq);
         if (!Number.isFinite(seqNum) || !Number.isInteger(seqNum) || seqNum <= 0) {
             client._clientLog.debug(`publish ordered direct(no-seq): event=${event}, ns=${ns || '<none>'}, seq=${String(seq)}`);
-            await this.publishOrderedQueueItem(ns, event, seqNum, payload, 'ordered');
+            await this.publishOrderedQueueItem(ns, event, seqNum, payload, source, false, context);
+            this.ensurePullOperationCurrent();
             return true;
         }
         if (client._pushedSeqs.get(ns)?.has(seqNum)) {
@@ -3310,10 +3577,11 @@ export class MessageDeliveryEngine {
         const contig = client._seqTracker.getContiguousSeq(ns);
         if (seqNum > contig && seqNum !== contig + 1) {
             client._clientLog.debug(`publish ordered enqueue(gap): event=${event}, ns=${ns}, seq=${seqNum}, contiguous=${contig}`);
-            this.enqueueOrderedMessage(ns, event, seqNum, payload);
+            this.enqueueOrderedMessage(ns, event, seqNum, payload, source);
             return false;
         }
-        await this.drainOrderedMessages(ns, seqNum);
+        await this.drainOrderedMessages(ns, seqNum, false, true, source, context);
+        this.ensurePullOperationCurrent();
         if (client._pushedSeqs.get(ns)?.has(seqNum)) {
             client._clientLog.debug(`publish ordered skipped after-drain duplicate: event=${event}, ns=${ns}, seq=${seqNum}`);
             return false;
@@ -3322,20 +3590,25 @@ export class MessageDeliveryEngine {
         queue?.delete(seqNum);
         if (queue && queue.size === 0)
             client._pendingOrderedMsgs.delete(ns);
-        await this.publishOrderedQueueItem(ns, event, seqNum, payload, 'ordered');
+        await this.publishOrderedQueueItem(ns, event, seqNum, payload, source, false, context);
+        this.ensurePullOperationCurrent();
         this.markPublishedSeq(ns, seqNum);
         client._markOrderedSeqDelivered(ns, seqNum);
         client._clientLog.debug(`publish ordered delivered: event=${event}, ns=${ns}, seq=${seqNum}`);
-        await this.drainOrderedMessages(ns);
-        if (!client._pendingOrderedMsgs.get(ns))
+        await this.drainOrderedMessages(ns, undefined, false, true, source, context);
+        if (!client._pendingOrderedMsgs.get(ns)) {
+            this.ensurePullOperationCurrent();
             await this.saveSeqTrackerState();
+        }
         return true;
     }
     async publishOrderedGroupRecall(ns, seq, message) {
         const client = this.runtime.client;
+        this.ensurePullOperationCurrent();
         const seqNum = Number(seq);
         if (!Number.isFinite(seqNum) || !Number.isInteger(seqNum) || seqNum <= 0) {
             await this.publishGroupRecallTombstone(ns.replace(/^group:/, ''), seq, message);
+            this.ensurePullOperationCurrent();
             return true;
         }
         // 撤回 tombstone 也占 seq：推进 contiguous 并标记已发布，确保 ack 正常推进、不留空洞。
@@ -3345,24 +3618,31 @@ export class MessageDeliveryEngine {
         }
         client._seqTracker.onMessageSeq(ns, seqNum);
         await this.publishGroupRecallTombstone(ns.replace(/^group:/, ''), seq, message);
+        this.ensurePullOperationCurrent();
         this.markPublishedSeq(ns, seqNum);
         client._markOrderedSeqDelivered?.(ns, seqNum);
         await this.drainOrderedMessages(ns);
-        if (!client._pendingOrderedMsgs.get(ns))
+        if (!client._pendingOrderedMsgs.get(ns)) {
+            this.ensurePullOperationCurrent();
             await this.saveSeqTrackerState();
+        }
         return true;
     }
     async publishPulledMessage(event, ns, seq, payload, persist = true) {
         const client = this.runtime.client;
+        this.ensurePullOperationCurrent();
         const seqNum = Number(seq);
         if (!Number.isFinite(seqNum) || !Number.isInteger(seqNum) || seqNum <= 0 || !ns) {
             client._clientLog.debug(`publish pulled direct(no-seq): event=${event}, ns=${ns || '<none>'}, seq=${String(seq)}`);
             if (event === 'message.recalled') {
-                return this.publishMessageRecallTombstone(seq, payload);
+                const published = await this.publishMessageRecallTombstone(seq, payload);
+                this.ensurePullOperationCurrent();
+                return published;
             }
             const published = client._withPullResponseProcessing(ns, () => client._publishAppEvent(event, payload, 'pull'));
             if (isPromiseLike(published))
                 await published;
+            this.ensurePullOperationCurrent();
             return true;
         }
         const queue = client._pendingOrderedMsgs.get(ns);
@@ -3373,23 +3653,28 @@ export class MessageDeliveryEngine {
                 client._pendingOrderedMsgs.delete(ns);
             return false;
         }
-        await this.drainOrderedMessages(ns, seqNum, true, persist);
+        await this.drainOrderedMessages(ns, seqNum, true, persist, 'pull');
+        this.ensurePullOperationCurrent();
         queue?.delete(seqNum);
         if (queue && queue.size === 0)
             client._pendingOrderedMsgs.delete(ns);
         if (event === 'message.recalled') {
             const recallPublished = await this.publishMessageRecallTombstone(seqNum, payload);
+            this.ensurePullOperationCurrent();
             this.markPublishedSeq(ns, seqNum);
             client._clientLog.debug(`publish pulled delivered: event=${event}, ns=${ns}, seq=${seqNum}`);
-            await this.drainOrderedMessages(ns, undefined, true, persist);
+            await this.drainOrderedMessages(ns, undefined, true, persist, 'pull');
+            this.ensurePullOperationCurrent();
             return recallPublished;
         }
         const published = client._withPullResponseProcessing(ns, () => client._publishAppEvent(event, payload, 'pull'));
         if (isPromiseLike(published))
             await published;
+        this.ensurePullOperationCurrent();
         this.markPublishedSeq(ns, seqNum);
         client._clientLog.debug(`publish pulled delivered: event=${event}, ns=${ns}, seq=${seqNum}`);
-        await this.drainOrderedMessages(ns, undefined, true, persist);
+        await this.drainOrderedMessages(ns, undefined, true, persist, 'pull');
+        this.ensurePullOperationCurrent();
         return true;
     }
 }