@agentunion/fastaun-browser 0.5.4 → 0.5.8

package/dist/client/delivery.js

@@ -1,6 +1,6 @@
 import { slotIsolationKey } from '../config.js';
-import { normalizeGroupId } from '../group-id.js';
 import { ConnectionState, isJsonObject } from '../types.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;
@@ -13,7 +13,7 @@ const APP_MESSAGE_ENVELOPE_KEYS = [
     'module_id', 'message_type', 'type', 'kind', 'version',
     'from', 'from_aid', 'sender_aid', 'to', 'to_aid', 'group_id',
     'timestamp', 'created_at', 'encrypted',
-    'context', 'protected_headers', 'headers', 'payload_type',
+    'context', 'protected_headers', 'headers', 'payload_type', 'mention_mode',
 ];
 const RECALL_PAYLOAD_KEYS = [
     'message_ids', 'target_message_seqs',
@@ -33,6 +33,7 @@ const APP_GROUP_EVENT_ENVELOPE_KEYS = [
     'actor_aid', 'sender_aid', 'member_aid', 'target_aid', 'operator_aid',
     'created_at', 'timestamp', 't_server', 'status', 'device_id', 'slot_id',
 ];
+const MAX_INLINE_PENDING_ACK_NAMESPACES = 4096;
 function formatDeliveryError(error) {
     return error instanceof Error ? error : String(error);
 }
@@ -47,6 +48,34 @@ function isTransientGapFillError(error) {
         || text.includes('connection closed')
         || text.includes('socket closed');
 }
+function positiveSafeSequenceHint(value) {
+    if (typeof value === 'number') {
+        return Number.isSafeInteger(value) && value > 0 ? value : 0;
+    }
+    if (typeof value !== 'string' || !value || value.trim() !== value)
+        return 0;
+    const parsed = Number(value);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : 0;
+}
+function nonNegativeSafeSequenceHint(value) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0)
+        return null;
+    return value;
+}
+function deduplicatePlainForwardPageMessages(value, afterSeq) {
+    if (!Array.isArray(value))
+        return [];
+    const bySeq = new Map();
+    for (const raw of value) {
+        if (!isJsonObject(raw))
+            continue;
+        const seq = positiveSafeSequenceHint(raw.seq);
+        if (seq <= afterSeq || bySeq.has(seq))
+            continue;
+        bySeq.set(seq, { ...raw, seq });
+    }
+    return [...bySeq.entries()].sort(([left], [right]) => left - right).map(([, message]) => message);
+}
 function p2pAppEventFromPlainPullMessage(message) {
     const payload = message.payload;
     const payloadType = isJsonObject(payload)
@@ -65,9 +94,146 @@ function p2pAppEventFromPlainPullMessage(message) {
 }
 export class MessageDeliveryEngine {
     runtime;
+    realtimeTailResults = null;
+    realtimeSyncing = null;
+    pendingP2pPullUpper = null;
+    pendingGroupPullUpper = null;
+    realtimeAcking = null;
+    pendingP2PInlineAcks = null;
+    pendingGroupInlineAcks = null;
+    pendingGroupInlineAckNamespaces = null;
+    // reset 后旧 inline Promise 只能自行结束，不能触碰新身份上下文的状态。
+    inlineGeneration = 0;
+    // 同一实例的 tracker 写入必须串行，避免旧的延迟 flush 覆盖新的 Forward 提交。
+    seqTrackerWriteChain = Promise.resolve();
     constructor(runtime) {
         this.runtime = runtime;
     }
+    resetInlineAckState() {
+        this.inlineGeneration += 1;
+        this.realtimeSyncing = null;
+        this.pendingP2pPullUpper = null;
+        this.pendingGroupPullUpper = null;
+        this.realtimeTailResults = null;
+        this.realtimeAcking = null;
+        this.pendingP2PInlineAcks = null;
+        this.pendingGroupInlineAcks = null;
+        this.pendingGroupInlineAckNamespaces = null;
+    }
+    isInlineGenerationCurrent(generation) {
+        return generation === this.inlineGeneration;
+    }
+    captureInlineGeneration() {
+        return this.inlineGeneration;
+    }
+    beginRealtimeSync(ns) {
+        if (!ns || this.realtimeSyncing?.has(ns))
+            return false;
+        const syncing = this.realtimeSyncing ?? new Set();
+        this.realtimeSyncing = syncing;
+        syncing.add(ns);
+        return true;
+    }
+    endRealtimeSync(ns) {
+        this.realtimeSyncing?.delete(ns);
+    }
+    hasPendingPull(ns) {
+        const pending = ns.startsWith('p2p:') ? this.pendingP2pPullUpper : this.pendingGroupPullUpper;
+        return (pending?.get(ns) ?? 0) > 0;
+    }
+    onPullGateIdle(ns) {
+        if (!ns)
+            return;
+        this.schedulePendingPullIfNeeded(ns, 'pull-gate-idle');
+    }
+    recordPendingPull(ns, seq) {
+        if (!ns || !Number.isSafeInteger(seq) || seq <= 0)
+            return;
+        const pending = ns.startsWith('p2p:')
+            ? (this.pendingP2pPullUpper ?? new Map())
+            : (this.pendingGroupPullUpper ?? new Map());
+        if (ns.startsWith('p2p:'))
+            this.pendingP2pPullUpper = pending;
+        else
+            this.pendingGroupPullUpper = pending;
+        pending.set(ns, Math.max(pending.get(ns) ?? 0, seq));
+    }
+    consumePendingPull(ns, throughSeq) {
+        const pending = ns.startsWith('p2p:') ? this.pendingP2pPullUpper : this.pendingGroupPullUpper;
+        if ((pending?.get(ns) ?? 0) <= throughSeq)
+            pending?.delete(ns);
+    }
+    schedulePendingPullIfNeeded(ns, reason) {
+        const pending = ns.startsWith('p2p:') ? this.pendingP2pPullUpper : this.pendingGroupPullUpper;
+        if (!pending)
+            return false;
+        const upper = pending.get(ns) ?? 0;
+        if (upper <= 0) {
+            pending.delete(ns);
+            return false;
+        }
+        const client = this.runtime.client;
+        const contiguous = client._seqTracker.getContiguousSeq(ns);
+        if (upper <= contiguous) {
+            pending.delete(ns);
+            client._clientLog?.debug(`pending pull upper already covered: ns=${ns}, upper_seq=${upper}, contiguous=${contiguous}, reason=${reason}`);
+            return false;
+        }
+        if (client.state !== ConnectionState.READY || client._closing || this.realtimeSyncing?.has(ns)
+            || client._rpcPipeline?.hasPullActivity?.(ns, false))
+            return false;
+        pending.delete(ns);
+        client._clientLog?.debug(`pending push follow-up pull scheduled: ns=${ns}, upper_seq=${upper}, reason=${reason}`);
+        if (ns.startsWith('p2p:')) {
+            client._safeAsync(this.onV2PushNotification({ seq: upper }));
+        }
+        else {
+            client._safeAsync(this.onRawGroupV2MessageCreated({ group_id: ns.slice('group:'.length), seq: upper }));
+        }
+        return true;
+    }
+    beginRealtimeAck(ns, seq) {
+        if (!ns || !Number.isSafeInteger(seq) || seq <= 0)
+            return false;
+        const current = this.realtimeAcking?.get(ns);
+        if (current !== undefined) {
+            if (seq > current)
+                this.realtimeAcking?.set(ns, seq);
+            return false;
+        }
+        const acking = this.realtimeAcking ?? new Map();
+        this.realtimeAcking = acking;
+        acking.set(ns, seq);
+        return true;
+    }
+    finishRealtimeAck(ns, completedSeq) {
+        const latest = this.realtimeAcking?.get(ns) ?? 0;
+        this.realtimeAcking?.delete(ns);
+        return latest > completedSeq ? latest : 0;
+    }
+    pendingInlineAckNamespaceCount() {
+        return (this.pendingP2PInlineAcks?.size ?? 0) + (this.pendingGroupInlineAcks?.size ?? 0);
+    }
+    inlinePostAckRow(row) {
+        const result = {};
+        for (const key of ['envelope_json', 'spk_id', 'group_id', 'message_id']) {
+            const value = row[key];
+            if (typeof value === 'string' && value)
+                result[key] = value;
+        }
+        if (typeof row.seq === 'number' && Number.isSafeInteger(row.seq) && row.seq > 0)
+            result.seq = row.seq;
+        return result;
+    }
+    markRealtimeTailCompleted(result) {
+        const completed = this.realtimeTailResults ?? new WeakSet();
+        this.realtimeTailResults = completed;
+        completed.add(result);
+        Object.defineProperty(result, '_realtime_tail_completed', { value: true, enumerable: false });
+    }
+    isRealtimeTailCompleted(result) {
+        return this.realtimeTailResults?.has(result) ?? false;
+    }
     prunePushedSeqs(ns) {
         const client = this.runtime.client;
         const pushed = client._pushedSeqs.get(ns);
@@ -106,18 +272,510 @@ export class MessageDeliveryEngine {
             client._clientLog.warn(`${label} failed: group=${groupId}`, e);
         });
     }
-    fireGroupV2Ack(groupId, ns, seq, label) {
+    fireGroupV2Ack(groupId, ns, seq, label, generation = null) {
         const client = this.runtime.client;
         const ackSeq = this.clampAckSeq('group.v2.ack', 'up_to_seq', ns, seq);
-        if (ackSeq <= 0)
+        if (ackSeq <= 0 || !this.beginRealtimeAck(ns, ackSeq))
             return;
-        void client._callRawV2Rpc('group.v2.ack', {
-            group_id: groupId,
-            up_to_seq: ackSeq,
-            _rpc_background: true,
+        let task;
+        try {
+            task = Promise.resolve(client._callRawV2Rpc('group.v2.ack', {
+                group_id: groupId,
+                up_to_seq: ackSeq,
+                _rpc_background: true,
+            }));
+        }
+        catch (exc) {
+            this.finishRealtimeAck(ns, ackSeq);
+            client._clientLog.debug(`${label} failed: group=${groupId} seq=${ackSeq} err=${formatDeliveryError(exc)}`);
+            return;
+        }
+        void task.then((result) => {
+            if (generation !== null && this.isInlineGenerationCurrent(generation)) {
+                this.completePendingGroupInlineAckUpTo(ns, this.resolveActualAckSeq(result, ackSeq), generation);
+            }
         }).catch((e) => {
             client._clientLog.debug(`${label} failed: group=${groupId} seq=${ackSeq} err=${String(e)}`);
+        }).finally(() => {
+            if (generation !== null && !this.isInlineGenerationCurrent(generation))
+                return;
+            const nextAckSeq = this.finishRealtimeAck(ns, ackSeq);
+            if (nextAckSeq > 0)
+                this.fireGroupV2Ack(groupId, ns, nextAckSeq, label, generation);
+        });
+    }
+    fireP2PV2Ack(seq, label, generation = null) {
+        const client = this.runtime.client;
+        const ns = client._aid ? `p2p:${client._aid}` : '';
+        if (!Number.isSafeInteger(seq) || seq <= 0 || typeof client._ackV2 !== 'function'
+            || !this.beginRealtimeAck(ns, seq))
+            return;
+        try {
+            const ackTask = generation === null ? client._ackV2(seq) : client._ackV2(seq, generation);
+            void Promise.resolve(ackTask).catch((exc) => {
+                client._clientLog.debug(`${label} failed: seq=${seq} err=${formatDeliveryError(exc)}`);
+            }).finally(() => {
+                if (generation !== null && !this.isInlineGenerationCurrent(generation))
+                    return;
+                const nextAckSeq = this.finishRealtimeAck(ns, seq);
+                if (nextAckSeq > 0)
+                    this.fireP2PV2Ack(nextAckSeq, label, generation);
+            });
+        }
+        catch (exc) {
+            this.finishRealtimeAck(ns, seq);
+            client._clientLog.debug(`${label} failed: seq=${seq} err=${formatDeliveryError(exc)}`);
+        }
+    }
+    retryPendingP2PInlineAck(ns, seq, label, ackThrough = seq) {
+        const pending = this.pendingP2PInlineAcks?.get(ns);
+        if (!pending || pending.seq !== seq)
+            return false;
+        if (pending.acking || !pending.committed)
+            return true;
+        if (!Number.isSafeInteger(ackThrough) || ackThrough < seq)
+            ackThrough = seq;
+        const client = this.runtime.client;
+        if (typeof client._ackV2 !== 'function')
+            return true;
+        pending.acking = true;
+        const generation = pending.generation;
+        let task;
+        try {
+            task = Promise.resolve(client._ackV2(ackThrough, generation));
+        }
+        catch (exc) {
+            pending.acking = false;
+            client._clientLog.debug(`${label} failed: seq=${seq} err=${formatDeliveryError(exc)}`);
+            return true;
+        }
+        void task.catch((exc) => {
+            client._clientLog.debug(`${label} failed: seq=${seq} err=${formatDeliveryError(exc)}`);
+        }).finally(() => {
+            const current = this.pendingP2PInlineAcks?.get(ns);
+            if (this.isInlineGenerationCurrent(generation) && current === pending)
+                current.acking = false;
+        });
+        return true;
+    }
+    retryPendingGroupInlineAck(ns, seq, label, ackThrough = seq) {
+        const pending = this.pendingGroupInlineAcks?.get(ns);
+        if (!pending || pending.seq !== seq)
+            return false;
+        if (pending.acking || !pending.committed)
+            return true;
+        if (!Number.isSafeInteger(ackThrough) || ackThrough < seq)
+            ackThrough = seq;
+        const client = this.runtime.client;
+        if (typeof client._ackGroupV2 !== 'function')
+            return true;
+        pending.acking = true;
+        const generation = pending.generation;
+        let task;
+        try {
+            task = Promise.resolve(client._ackGroupV2(pending.groupId, ackThrough, pending.groupAid || undefined, generation));
+        }
+        catch (exc) {
+            pending.acking = false;
+            client._clientLog.debug(`${label} failed: group=${pending.groupId} seq=${seq} err=${formatDeliveryError(exc)}`);
+            return true;
+        }
+        void task.catch((exc) => {
+            client._clientLog.debug(`${label} failed: group=${pending.groupId} seq=${seq} err=${formatDeliveryError(exc)}`);
+        }).finally(() => {
+            const current = this.pendingGroupInlineAcks?.get(ns);
+            if (this.isInlineGenerationCurrent(generation) && current === pending)
+                current.acking = false;
+        });
+        return true;
+    }
+    reservePendingP2PInlineAck(ns, seq, row, generation = this.inlineGeneration) {
+        if (!this.isInlineGenerationCurrent(generation)
+            || !ns || !Number.isSafeInteger(seq) || seq <= 0 || this.pendingP2PInlineAcks?.has(ns)
+            || this.pendingInlineAckNamespaceCount() >= MAX_INLINE_PENDING_ACK_NAMESPACES)
+            return false;
+        const pendingMap = this.pendingP2PInlineAcks ?? new Map();
+        this.pendingP2PInlineAcks = pendingMap;
+        pendingMap.set(ns, {
+            seq,
+            row: this.inlinePostAckRow(row),
+            generation,
+            committed: false,
+            observedAckSeq: 0,
+            acking: false,
+        });
+        return true;
+    }
+    dropPendingP2PInlineAck(ns, seq, generation = this.inlineGeneration) {
+        const pending = this.pendingP2PInlineAcks?.get(ns);
+        if (this.isInlineGenerationCurrent(generation) && pending?.seq === seq && pending.generation === generation) {
+            this.pendingP2PInlineAcks?.delete(ns);
+        }
+    }
+    reservePendingGroupInlineAck(ns, seq, row, groupAid, groupId, generation = this.inlineGeneration) {
+        if (!this.isInlineGenerationCurrent(generation)
+            || !ns || !groupId || !Number.isSafeInteger(seq) || seq <= 0
+            || this.pendingGroupInlineAcks?.has(ns)
+            || this.pendingGroupInlineAckNamespaces?.has(ns)
+            || this.pendingInlineAckNamespaceCount() >= MAX_INLINE_PENDING_ACK_NAMESPACES)
+            return false;
+        const normalizedGroupAid = typeof groupAid === 'string' ? groupAid.trim() : '';
+        const aliasNs = normalizedGroupAid ? `group:${normalizedGroupAid}` : '';
+        if (aliasNs && aliasNs !== ns
+            && (this.pendingGroupInlineAcks?.has(aliasNs) || this.pendingGroupInlineAckNamespaces?.has(aliasNs)))
+            return false;
+        const pendingMap = this.pendingGroupInlineAcks ?? new Map();
+        this.pendingGroupInlineAcks = pendingMap;
+        pendingMap.set(ns, {
+            seq,
+            row: this.inlinePostAckRow(row),
+            generation,
+            groupId,
+            groupAid: normalizedGroupAid,
+            aliasNs: aliasNs !== ns ? aliasNs : '',
+            committed: false,
+            observedAckSeq: 0,
+            acking: false,
         });
+        if (aliasNs && aliasNs !== ns) {
+            const aliasMap = this.pendingGroupInlineAckNamespaces ?? new Map();
+            this.pendingGroupInlineAckNamespaces = aliasMap;
+            aliasMap.set(aliasNs, ns);
+        }
+        return true;
+    }
+    removePendingGroupInlineAck(ns, pending) {
+        if (this.pendingGroupInlineAcks?.get(ns) !== pending)
+            return false;
+        this.pendingGroupInlineAcks.delete(ns);
+        if (pending.aliasNs && this.pendingGroupInlineAckNamespaces?.get(pending.aliasNs) === ns) {
+            this.pendingGroupInlineAckNamespaces.delete(pending.aliasNs);
+        }
+        return true;
+    }
+    dropPendingGroupInlineAck(ns, seq, generation = this.inlineGeneration) {
+        const pending = this.pendingGroupInlineAcks?.get(ns);
+        if (this.isInlineGenerationCurrent(generation) && pending?.seq === seq && pending.generation === generation) {
+            this.removePendingGroupInlineAck(ns, pending);
+        }
+    }
+    resolvePendingGroupInlineAckNamespace(ns) {
+        const pendingMap = this.pendingGroupInlineAcks;
+        if (!ns || !pendingMap || pendingMap.size === 0 || pendingMap.has(ns))
+            return ns;
+        const canonicalNs = this.pendingGroupInlineAckNamespaces?.get(ns);
+        return canonicalNs && pendingMap.has(canonicalNs) ? canonicalNs : ns;
+    }
+    pendingP2PInlineAckGeneration(ns) {
+        const pendingMap = this.pendingP2PInlineAcks;
+        if (!ns || !pendingMap || pendingMap.size === 0)
+            return null;
+        const pending = pendingMap.get(ns);
+        return pending && this.isInlineGenerationCurrent(pending.generation) ? pending.generation : null;
+    }
+    pendingGroupInlineAckGeneration(ns) {
+        const pendingMap = this.pendingGroupInlineAcks;
+        if (!ns || !pendingMap || pendingMap.size === 0)
+            return null;
+        const canonicalNs = pendingMap.has(ns) ? ns : this.pendingGroupInlineAckNamespaces?.get(ns);
+        if (!canonicalNs)
+            return null;
+        const pending = pendingMap.get(canonicalNs);
+        return pending && this.isInlineGenerationCurrent(pending.generation) ? pending.generation : null;
+    }
+    completePendingP2PInlineAckUpTo(ns, ackSeq, generation = this.inlineGeneration) {
+        const pendingMap = this.pendingP2PInlineAcks;
+        if (!this.isInlineGenerationCurrent(generation)
+            || !ns || !Number.isSafeInteger(ackSeq) || ackSeq <= 0 || !pendingMap || pendingMap.size === 0)
+            return;
+        const pending = pendingMap.get(ns);
+        if (!pending || pending.generation !== generation || ackSeq < pending.seq)
+            return;
+        if (!pending.committed) {
+            pending.observedAckSeq = Math.max(pending.observedAckSeq, ackSeq);
+            return;
+        }
+        pendingMap.delete(ns);
+        this.runPostInlineCommit(pending.row, pending.seq, 'P2P', generation);
+    }
+    completePendingGroupInlineAckUpTo(ns, ackSeq, generation = this.inlineGeneration) {
+        const pendingMap = this.pendingGroupInlineAcks;
+        if (!this.isInlineGenerationCurrent(generation)
+            || !ns || !Number.isSafeInteger(ackSeq) || ackSeq <= 0 || !pendingMap || pendingMap.size === 0)
+            return;
+        const canonicalNs = this.resolvePendingGroupInlineAckNamespace(ns);
+        const pending = pendingMap.get(canonicalNs);
+        if (!pending || pending.generation !== generation || ackSeq < pending.seq)
+            return;
+        if (!pending.committed) {
+            pending.observedAckSeq = Math.max(pending.observedAckSeq, ackSeq);
+            return;
+        }
+        this.removePendingGroupInlineAck(canonicalNs, pending);
+        this.runPostInlineCommit(pending.row, pending.seq, 'Group', generation);
+    }
+    runPostInlineCommit(row, seq, scope, generation) {
+        const client = this.runtime.client;
+        if (!this.isInlineGenerationCurrent(generation) || typeof client._postInlineV2CommitAndAck !== 'function')
+            return;
+        try {
+            void Promise.resolve(client._postInlineV2CommitAndAck(row)).catch((exc) => {
+                client._clientLog.debug(`inline ${scope} post-commit work failed: seq=${seq} err=${formatDeliveryError(exc)}`);
+            });
+        }
+        catch (exc) {
+            client._clientLog.debug(`inline ${scope} post-commit work failed: seq=${seq} err=${formatDeliveryError(exc)}`);
+        }
+    }
+    markPendingP2PInlineAckCommitted(ns, seq, generation = this.inlineGeneration) {
+        const pending = this.pendingP2PInlineAcks?.get(ns);
+        if (!this.isInlineGenerationCurrent(generation) || !pending || pending.seq !== seq || pending.generation !== generation)
+            return false;
+        pending.committed = true;
+        if (pending.observedAckSeq < seq)
+            return true;
+        this.pendingP2PInlineAcks?.delete(ns);
+        this.runPostInlineCommit(pending.row, pending.seq, 'P2P', generation);
+        return true;
+    }
+    markPendingGroupInlineAckCommitted(ns, seq, generation = this.inlineGeneration) {
+        const pending = this.pendingGroupInlineAcks?.get(ns);
+        if (!this.isInlineGenerationCurrent(generation) || !pending || pending.seq !== seq || pending.generation !== generation)
+            return false;
+        pending.committed = true;
+        if (pending.observedAckSeq < seq)
+            return true;
+        this.removePendingGroupInlineAck(ns, pending);
+        this.runPostInlineCommit(pending.row, pending.seq, 'Group', generation);
+        return true;
+    }
+    resolveActualAckSeq(result, requestedSeq) {
+        if (!Number.isSafeInteger(requestedSeq) || requestedSeq <= 0)
+            return 0;
+        if (!isJsonObject(result))
+            return requestedSeq;
+        const row = result;
+        let value;
+        if (Object.prototype.hasOwnProperty.call(row, 'effective_ack_seq')) {
+            value = row.effective_ack_seq;
+        }
+        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;
+            if (isJsonObject(cursor)) {
+                const cursorRow = cursor;
+                if (!Object.prototype.hasOwnProperty.call(cursorRow, 'current_seq'))
+                    return 0;
+                value = cursorRow.current_seq;
+            }
+            else {
+                value = cursor;
+            }
+        }
+        else {
+            return requestedSeq;
+        }
+        return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : 0;
+    }
+    resolveP2PPullAckSeq(result, requestedSeq) {
+        if (!Number.isSafeInteger(requestedSeq) || requestedSeq <= 0)
+            return 0;
+        if (isJsonObject(result)
+            && Object.prototype.hasOwnProperty.call(result, 'server_ack_seq')) {
+            const value = result.server_ack_seq;
+            return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : 0;
+        }
+        return 0;
+    }
+    resolveGroupPullAckSeq(result, requestedSeq) {
+        if (!Number.isSafeInteger(requestedSeq) || requestedSeq <= 0)
+            return 0;
+        if (!isJsonObject(result))
+            return 0;
+        const row = result;
+        if (!Object.prototype.hasOwnProperty.call(row, 'cursor'))
+            return 0;
+        const cursor = row.cursor;
+        if (!isJsonObject(cursor))
+            return 0;
+        const cursorRow = cursor;
+        if (!Object.prototype.hasOwnProperty.call(cursorRow, 'current_seq'))
+            return 0;
+        const value = cursorRow.current_seq;
+        return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : 0;
+    }
+    resolveForwardAckSeq(result, requestedSeq) {
+        if (!Number.isSafeInteger(requestedSeq) || requestedSeq <= 0)
+            return 0;
+        // 旧服务端成功响应可能不带累计水位字段；RPC 已成功，兼容按请求水位处理。
+        if (!isJsonObject(result))
+            return requestedSeq;
+        const row = result;
+        let value;
+        if (Object.prototype.hasOwnProperty.call(row, 'effective_ack_seq')) {
+            value = row.effective_ack_seq;
+        }
+        else if (Object.prototype.hasOwnProperty.call(row, 'ack_seq')) {
+            value = row.ack_seq;
+        }
+        else {
+            return requestedSeq;
+        }
+        return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : 0;
+    }
+    forwardCoordinator() {
+        const coordinator = this.runtime.client._v2E2EE;
+        if (!coordinator
+            || typeof coordinator.pendingForwardCursor !== 'function'
+            || typeof coordinator.recordForwardCursor !== 'function'
+            || typeof coordinator.clearForwardCursor !== 'function'
+            || typeof coordinator.pendingForwardAck !== 'function'
+            || typeof coordinator.recordForwardAck !== 'function'
+            || typeof coordinator.clearForwardAck !== 'function') {
+            throw new Error('Forward cursor coordinator is unavailable');
+        }
+        return coordinator;
+    }
+    async confirmPlainForwardAck(ns, method, ackSeq, groupId = '') {
+        const client = this.runtime.client;
+        const coordinator = this.forwardCoordinator();
+        const generation = this.captureInlineGeneration();
+        coordinator.recordForwardAck(ns, ackSeq);
+        const params = method === 'message.ack'
+            ? {
+                seq: ackSeq,
+                device_id: client._deviceId,
+                slot_id: client._slotId,
+                _rpc_background: true,
+            }
+            : {
+                group_id: groupId,
+                msg_seq: ackSeq,
+                device_id: client._deviceId,
+                slot_id: client._slotId,
+                _rpc_background: true,
+            };
+        const result = await client._rpcPipeline.rawCall(method, params, { background: true });
+        const actualAckSeq = this.resolveForwardAckSeq(result, ackSeq);
+        if (actualAckSeq < ackSeq) {
+            throw new Error(`${method} server ACK watermark ${actualAckSeq} is below requested ${ackSeq}`);
+        }
+        coordinator.clearForwardAck(ns, actualAckSeq);
+        if (method === 'message.ack') {
+            this.completePendingP2PInlineAckUpTo(ns, actualAckSeq, generation);
+        }
+        else {
+            this.completePendingGroupInlineAckUpTo(ns, actualAckSeq, generation);
+        }
+    }
+    async commitPlainForwardPage(ns, afterSeq, method, result, groupId = '') {
+        if (!isJsonObject(result)) {
+            throw new Error(`${method} response must be an object`);
+        }
+        const client = this.runtime.client;
+        const response = result;
+        const messages = deduplicatePlainForwardPageMessages(response.messages, afterSeq);
+        const coordinator = this.forwardCoordinator();
+        const pageContigBefore = client._seqTracker.getContiguousSeq(ns);
+        const pageInlineGeneration = this.captureInlineGeneration();
+        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;
+        response._contig_before = pageContigBefore;
+        const cursor = isJsonObject(response.cursor)
+            ? response.cursor
+            : null;
+        const serverAckRaw = method === 'message.pull' ? response.server_ack_seq : cursor?.current_seq;
+        const hasServerAck = method === 'message.pull'
+            ? Object.prototype.hasOwnProperty.call(response, 'server_ack_seq')
+            : Boolean(cursor && Object.prototype.hasOwnProperty.call(cursor, 'current_seq'));
+        const parsedServerAck = hasServerAck ? nonNegativeSafeSequenceHint(serverAckRaw) : null;
+        const serverAckSeq = parsedServerAck ?? 0;
+        const retentionFloor = method === 'message.pull'
+            ? positiveSafeSequenceHint(response.retention_floor_seq)
+            : Math.max(positiveSafeSequenceHint(response.retention_floor_message_seq), positiveSafeSequenceHint(response.retention_floor_seq), positiveSafeSequenceHint(cursor?.retention_floor_seq));
+        const visibilityFloor = method === 'group.pull'
+            ? Math.max(positiveSafeSequenceHint(cursor?.join_seq), Math.max(0, positiveSafeSequenceHint(response.earliest_available_message_seq) - 1))
+            : 0;
+        let publishedCount = 0;
+        let committed = false;
+        try {
+            for (const rawMessage of messages) {
+                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;
+                    }
+                    continue;
+                }
+                const message = normalizeGroupMentionMode(rawMessage);
+                if (this.recallEventFromGroupMessage(message)) {
+                    if (await this.publishGroupRecallTombstone(groupId, seq, message)) {
+                        this.markPublishedSeq(ns, seq);
+                        publishedCount += 1;
+                    }
+                }
+                else if (await this.publishPulledMessage('group.message_created', ns, seq, message, false)) {
+                    publishedCount += 1;
+                }
+            }
+            if (messages.length > 0)
+                client._seqTracker.onPullResult(ns, messages, afterSeq);
+            const commitTarget = Math.max(client._seqTracker.getContiguousSeq(ns), retentionFloor, visibilityFloor, deferredServerCursor);
+            if (commitTarget > client._seqTracker.getContiguousSeq(ns)) {
+                client._seqTracker.forceContiguousSeq(ns, commitTarget);
+            }
+            if (client._seqTracker.getContiguousSeq(ns) !== pageContigBefore) {
+                await this.drainOrderedMessages(ns, undefined, false, false);
+                await client._commitSeqTrackerState(ns);
+            }
+            committed = true;
+        }
+        catch (exc) {
+            if (!committed && typeof client._seqTracker.restoreNamespaceSnapshot === 'function') {
+                client._seqTracker.restoreNamespaceSnapshot(ns, pageTrackerSnapshot);
+                this.dropSeqTrackerPending(ns);
+            }
+            throw exc;
+        }
+        const committedAck = client._seqTracker.getContiguousSeq(ns);
+        if (deferredServerCursor > 0 && committedAck >= deferredServerCursor) {
+            coordinator.clearForwardCursor(ns, committedAck);
+        }
+        if (hasServerAck && parsedServerAck !== null && serverAckSeq > committedAck) {
+            coordinator.recordForwardCursor(ns, serverAckSeq, committedAck);
+        }
+        if (hasServerAck && parsedServerAck !== null && serverAckSeq >= deferredForwardAck) {
+            coordinator.clearForwardAck(ns, serverAckSeq);
+            if (method === 'message.pull') {
+                this.completePendingP2PInlineAckUpTo(ns, serverAckSeq, pageInlineGeneration);
+            }
+            else {
+                this.completePendingGroupInlineAckUpTo(ns, serverAckSeq, pageInlineGeneration);
+            }
+        }
+        const contigAdvanced = committedAck > pageContigBefore;
+        const knownServerAck = hasServerAck ? serverAckSeq : deferredServerCursor;
+        if (committedAck > 0
+            && ((hasServerAck && committedAck > serverAckSeq)
+                || (contigAdvanced && committedAck > knownServerAck))) {
+            coordinator.recordForwardAck(ns, committedAck);
+        }
+        const pendingAckSeq = Number(coordinator.pendingForwardAck(ns, committedAck) ?? 0);
+        if (pendingAckSeq > 0) {
+            const ackMethod = method === 'message.pull' ? 'message.ack' : 'group.ack_messages';
+            const clampedAckSeq = this.clampAckSeq(ackMethod, ackMethod === 'message.ack' ? 'seq' : 'msg_seq', ns, pendingAckSeq);
+            if (clampedAckSeq < pendingAckSeq) {
+                throw new Error(`${ackMethod} cannot confirm pending Forward watermark ${pendingAckSeq}`);
+            }
+            await this.confirmPlainForwardAck(ns, ackMethod, pendingAckSeq, groupId);
+        }
+        return { rawCount: messages.length, publishedCount };
     }
     enqueueOrderedMessage(ns, event, seq, payload) {
         const client = this.runtime.client;
@@ -136,7 +794,7 @@ export class MessageDeliveryEngine {
     isGroupEventNamespace(ns) {
         return ns.startsWith('group_event:');
     }
-    async publishOrderedQueueItem(ns, event, seq, payload) {
+    async publishOrderedQueueItem(ns, event, seq, payload, pullResponse = false) {
         const client = this.runtime.client;
         if (event === 'group.changed' && this.isGroupEventNamespace(ns)) {
             await this.publishOrderedGroupChanged(payload);
@@ -146,6 +804,10 @@ export class MessageDeliveryEngine {
             await this.publishMessageRecallTombstone(seq, payload);
             return;
         }
+        if (pullResponse) {
+            await client._withPullResponseProcessing(ns, () => client._publishAppEvent(event, payload));
+            return;
+        }
         await client._publishAppEvent(event, payload);
     }
     async publishOrderedGroupChanged(payload) {
@@ -154,8 +816,8 @@ export class MessageDeliveryEngine {
             const eventPayload = payload;
             client._groupState?.handleGroupChangedV2Membership?.(eventPayload);
             if (eventPayload.action === 'dissolved') {
-                const rawGroupId = eventPayload.group_aid ?? eventPayload.group_id ?? '';
-                const groupId = normalizeGroupId(String(rawGroupId)) || String(rawGroupId).trim();
+                const rawGroupId = eventPayload.group_id ?? eventPayload.group_aid ?? '';
+                const groupId = String(rawGroupId).trim();
                 if (groupId)
                     client._cleanupDissolvedGroup?.(groupId);
             }
@@ -185,13 +847,28 @@ export class MessageDeliveryEngine {
     }
     normalizePublishedMessagePayload(event, payload) {
         if (this.isInstanceScopedMessageEvent(event)) {
+            payload = this.stripInlineInternalFields(payload);
+            if (event === 'group.message_created')
+                payload = normalizeGroupMentionMode(payload);
             return this.attachAppMessageEnvelope(this.stripInternalSenderDeviceFields(this.attachCurrentInstanceContext(payload)));
         }
         if (this.isGroupScopedEvent(event)) {
+            payload = this.stripInlineInternalFields(payload);
             return this.attachAppGroupEventEnvelope(this.attachCurrentInstanceContext(payload));
         }
         return payload;
     }
+    stripInlineInternalFields(payload) {
+        if (!isJsonObject(payload))
+            return payload;
+        if (!Object.prototype.hasOwnProperty.call(payload, 'inline_message')
+            && !Object.prototype.hasOwnProperty.call(payload, '_inline_message_candidates_v1'))
+            return payload;
+        const result = { ...payload };
+        delete result.inline_message;
+        delete result._inline_message_candidates_v1;
+        return result;
+    }
     envelopeMetadata(value) {
         let source = value;
         if (source && typeof source === 'object') {
@@ -248,6 +925,7 @@ export class MessageDeliveryEngine {
         if (protectedHeaders)
             envelope.protected_headers = protectedHeaders;
         setIfPresent('payload_type', firstValue(message.payload_type, protectedHeaders?.payload_type));
+        setIfPresent('mention_mode', message.mention_mode);
         return envelope;
     }
     isGroupScopedEvent(event) {
@@ -314,19 +992,30 @@ export class MessageDeliveryEngine {
         if (protectedHeaders)
             envelope.protected_headers = protectedHeaders;
         setIfPresent('payload_type', firstValue(params.payload_type, protectedHeaders?.payload_type, body.type));
+        if (method === 'group.send')
+            setIfPresent('mention_mode', resultObj.mention_mode);
         return envelope;
     }
-    attachSendResultEnvelope(method, params, result, encrypted) {
+    attachSendResultEnvelope(method, params, result, encrypted, modeSource) {
         if (!APP_SEND_ENVELOPE_METHODS.has(method) || !isJsonObject(result))
             return result;
-        const out = { ...result };
-        out.envelope = this.sendResultEnvelope(method, params, out, encrypted);
+        let out = { ...result };
+        const serverEnvelope = method === 'group.send' && isJsonObject(out.envelope)
+            ? { ...out.envelope }
+            : undefined;
         if ('payload' in params) {
             out.payload = params.payload;
         }
         else if ('content' in params) {
             out.payload = params.content;
         }
+        const generatedEnvelope = this.sendResultEnvelope(method, params, out, encrypted);
+        out.envelope = serverEnvelope ? { ...generatedEnvelope, ...serverEnvelope } : generatedEnvelope;
+        if (method === 'group.send') {
+            const serverSource = modeSource ?? result;
+            const authoritativeSource = hasGroupMentionModeField(serverSource) ? serverSource : out;
+            out = normalizeGroupMentionMode(out, authoritativeSource);
+        }
         return out;
     }
     attachAppGroupEventEnvelope(payload) {
@@ -516,7 +1205,7 @@ export class MessageDeliveryEngine {
         // (group_id, sorted message_ids) 已能唯一标识一次撤回；缺 message_ids 时按原消息 id/seq 兜底。
         // 去重键不含 recalled_at：占位/通知 tombstone（pull）与在线 push 三条通道对同一次撤回
         // 可能携带不同来源的时间戳（push 在事务后重取），纳入 recalled_at 会使去重失效、回调多次。
-        const normalizedGroupId = normalizeGroupId(groupId) || String(groupId ?? '').trim();
+        const normalizedGroupId = String(groupId ?? '').trim();
         const ids = payload.message_ids;
         const idPart = Array.isArray(ids)
             ? ids.map((i) => String(i ?? '').trim()).filter(Boolean).sort().join(',')
@@ -545,9 +1234,7 @@ export class MessageDeliveryEngine {
         if (!eventPayload)
             return false;
         const rawGroupId = String(eventPayload.group_id ?? groupId ?? '').trim();
-        const dedupGroupId = normalizeGroupId(rawGroupId) || rawGroupId;
-        if (dedupGroupId)
-            eventPayload.group_id = dedupGroupId;
+        const dedupGroupId = rawGroupId;
         const dedupKey = this.groupRecallDedupKey(dedupGroupId, eventPayload);
         let seen = client._groupRecallSeen;
         if (!seen) {
@@ -645,7 +1332,7 @@ export class MessageDeliveryEngine {
         }
         if (isJsonObject(payload)) {
             try {
-                const snapshot = client._agentMdManager.eventSnapshot();
+                const snapshot = await client._agentMdManager.eventSnapshot();
                 const localEtag = snapshot?.local_etag || '';
                 const remoteEtag = snapshot?.remote_etag || '';
                 if ((localEtag || remoteEtag) && payload._agent_md === undefined) {
@@ -665,24 +1352,76 @@ export class MessageDeliveryEngine {
         if (!isJsonObject(message))
             return true;
         const client = this.runtime.client;
-        if ('device_id' in message) {
-            const targetDeviceId = String(message.device_id ?? '').trim();
-            if (targetDeviceId !== client._deviceId) {
+        const explicitDevice = this.strictTargetString(message, 'target_device_id');
+        if (explicitDevice.present) {
+            if (!explicitDevice.valid || explicitDevice.value !== client._deviceId)
+                return false;
+        }
+        else {
+            const targetDeviceId = this.boundString(message, ['device_id']);
+            if (targetDeviceId.present && targetDeviceId.value !== client._deviceId) {
                 return false;
             }
         }
-        if ('slot_id' in message) {
-            const targetSlotId = String(message.slot_id ?? '').trim();
-            if (slotIsolationKey(targetSlotId) !== slotIsolationKey(client._slotId)) {
+        const explicitSlot = this.strictTargetString(message, 'target_slot_id');
+        if (explicitSlot.present) {
+            if (!explicitSlot.valid
+                || slotIsolationKey(explicitSlot.value) !== slotIsolationKey(client._slotId))
+                return false;
+        }
+        else {
+            const targetSlotId = this.boundString(message, ['slot_id']);
+            if (targetSlotId.present
+                && slotIsolationKey(targetSlotId.value) !== slotIsolationKey(client._slotId)) {
                 return false;
             }
         }
         return true;
     }
-    async runPushProcessSerialized(ns, operation) {
+    strictTargetString(source, key) {
+        if (!Object.prototype.hasOwnProperty.call(source, key)) {
+            return { present: false, valid: false, value: '' };
+        }
+        const raw = source[key];
+        if (typeof raw !== 'string')
+            return { present: true, valid: false, value: '' };
+        const value = raw.trim();
+        return { present: true, valid: Boolean(value), value };
+    }
+    async runPushProcessSerialized(ns, operation, inlineGeneration) {
         const client = this.runtime.client;
-        if (!ns) {
+        if (inlineGeneration === undefined) {
+            if (!ns) {
+                await operation();
+                return;
+            }
+            let queues = client._pushProcessQueues;
+            if (!queues) {
+                queues = new Map();
+                client._pushProcessQueues = queues;
+            }
+            const previous = queues.get(ns) ?? Promise.resolve();
+            const current = previous.catch(() => undefined).then(operation);
+            const stored = current.then(() => undefined, () => undefined);
+            queues.set(ns, stored);
+            try {
+                await current;
+            }
+            finally {
+                if (queues.get(ns) === stored)
+                    queues.delete(ns);
+            }
+            return;
+        }
+        const run = async () => {
+            if (!this.isInlineGenerationCurrent(inlineGeneration))
+                return;
             await operation();
+            if (!this.isInlineGenerationCurrent(inlineGeneration))
+                return;
+        };
+        if (!ns) {
+            await run();
             return;
         }
         let queues = client._pushProcessQueues;
@@ -691,7 +1430,7 @@ export class MessageDeliveryEngine {
             client._pushProcessQueues = queues;
         }
         const previous = queues.get(ns) ?? Promise.resolve();
-        const current = previous.catch(() => undefined).then(operation);
+        const current = previous.catch(() => undefined).then(run);
         const stored = current.then(() => undefined, () => undefined);
         queues.set(ns, stored);
         try {
@@ -708,7 +1447,18 @@ export class MessageDeliveryEngine {
         const ns = isJsonObject(data) && client._aid && data.seq !== undefined
             ? `p2p:${client._aid}`
             : '';
-        client._safeAsync(this.runPushProcessSerialized(ns, () => this.processAndPublishMessage(data)));
+        const seq = isJsonObject(data) && typeof data.seq === 'number' ? data.seq : 0;
+        if (client._v2Session && ns && Number.isSafeInteger(seq) && seq > 0
+            && this.messageTargetsCurrentInstance(data)) {
+            client._seqTracker.updateMaxSeen(ns, seq);
+        }
+        const hasInlineObject = isJsonObject(data)
+            && isJsonObject(data.inline_message);
+        const inlineGeneration = hasInlineObject ? this.captureInlineGeneration() : undefined;
+        const operation = () => this.processAndPublishMessage(data, inlineGeneration);
+        client._safeAsync(client._v2Session && ns && !hasInlineObject
+            ? operation()
+            : this.runPushProcessSerialized(ns, operation, inlineGeneration));
         client._clientLog.debug('_onRawMessageReceived exit: elapsed=0ms (dispatched async)');
     }
     async onRawMessageRecalled(data) {
@@ -729,7 +1479,7 @@ export class MessageDeliveryEngine {
             const seqNeedsPull = client._seqTracker.onMessageSeq(ns, seq);
             const published = await this.publishOrderedMessage('message.recalled', ns, seq, msg);
             const contigAfter = client._seqTracker.getContiguousSeq(ns);
-            if (seqNeedsPull && !published) {
+            if (seqNeedsPull && !published && client._sessionOptions?.background_sync !== false) {
                 client._safeAsync(this.fillP2pGap());
             }
             const contig = client._seqTracker.getContiguousSeq(ns);
@@ -748,7 +1498,7 @@ export class MessageDeliveryEngine {
         }
         await this.publishMessageRecallTombstone(seq, msg);
     }
-    async processAndPublishMessage(data) {
+    async processAndPublishMessage(data, inlineGeneration) {
         const client = this.runtime.client;
         try {
             if (!isJsonObject(data)) {
@@ -759,6 +1509,15 @@ export class MessageDeliveryEngine {
             if (!this.messageTargetsCurrentInstance(msg)) {
                 return;
             }
+            // 新 SDK 的所有带合法 seq P2P Push 都只作为 Head 通知处理。
+            // 新服务端为兼容旧 SDK 仍可能发送 message.received；V2 会话下必须
+            // 在旧 seq tracking / ordered publish 之前转入前台 Tail 协调器。
+            const legacyPushSeq = positiveSafeSequenceHint(msg.seq);
+            const hasInlineField = Object.prototype.hasOwnProperty.call(msg, 'inline_message');
+            if (client._v2Session && client._aid && (legacyPushSeq > 0 || hasInlineField)) {
+                await this.processV2P2PNotification(msg, 'v1', inlineGeneration);
+                return;
+            }
             const seq = msg.seq;
             const encryptedPush = client._isEncryptedPushMessage(msg);
             if (seq !== undefined && seq !== null && client._aid) {
@@ -772,7 +1531,7 @@ export class MessageDeliveryEngine {
                     : await this.publishOrderedMessage('message.received', ns, seq, msg);
                 const contigAfter = client._seqTracker.getContiguousSeq(ns);
                 const needPull = seqNeedsPull && !published;
-                if (needPull) {
+                if (needPull && client._sessionOptions?.background_sync !== false) {
                     client._safeAsync(this.fillP2pGap());
                 }
                 const contig = client._seqTracker.getContiguousSeq(ns);
@@ -818,11 +1577,24 @@ export class MessageDeliveryEngine {
     onRawGroupMessageCreated(data) {
         const client = this.runtime.client;
         client._clientLog.debug(`_onRawGroupMessageCreated enter: group_id=${data?.group_id ?? '-'} from=${data?.from ?? '-'} seq=${data?.seq ?? '-'}`);
-        const groupId = isJsonObject(data) ? String(data.group_id ?? '').trim() : '';
-        client._safeAsync(this.runPushProcessSerialized(groupId ? `group:${groupId}` : '', () => this.processAndPublishGroupMessage(data)));
+        const groupId = isJsonObject(data) && typeof data.group_id === 'string' ? data.group_id.trim() : '';
+        const seq = isJsonObject(data) && typeof data.seq === 'number' ? data.seq : 0;
+        const kind = isJsonObject(data) ? String(data.kind ?? '').trim() : '';
+        if (client._v2Session && groupId && kind !== 'group.online_unread_hint'
+            && Number.isSafeInteger(seq) && seq > 0) {
+            client._seqTracker.updateMaxSeen(`group:${groupId}`, seq);
+        }
+        const ns = groupId ? `group:${groupId}` : '';
+        const hasInlineObject = isJsonObject(data)
+            && isJsonObject(data.inline_message);
+        const inlineGeneration = hasInlineObject ? this.captureInlineGeneration() : undefined;
+        const operation = () => this.processAndPublishGroupMessage(data, inlineGeneration);
+        client._safeAsync(client._v2Session && ns && !hasInlineObject
+            ? operation()
+            : this.runPushProcessSerialized(ns, operation, inlineGeneration));
         client._clientLog.debug('_onRawGroupMessageCreated exit: elapsed=0ms (dispatched async)');
     }
-    async processAndPublishGroupMessage(data) {
+    async processAndPublishGroupMessage(data, inlineGeneration) {
         const client = this.runtime.client;
         try {
             if (!isJsonObject(data)) {
@@ -830,12 +1602,20 @@ export class MessageDeliveryEngine {
                 return;
             }
             const msg = { ...data };
-            const groupId = (msg.group_id ?? '');
+            const groupId = typeof msg.group_id === 'string' ? msg.group_id.trim() : '';
             const seq = msg.seq;
             const payload = msg.payload;
             if (groupId) {
                 client._groupSynced.add(groupId);
             }
+            // V2 会话中旧 group.message_created 也只是 Head 通知；必须先 Tail，
+            // 不能让 payload 路径直接推进旧 ordered publish 状态。
+            const legacyPushSeq = positiveSafeSequenceHint(seq);
+            const hasInlineField = Object.prototype.hasOwnProperty.call(msg, 'inline_message');
+            if (client._v2Session && groupId && (legacyPushSeq > 0 || hasInlineField)) {
+                await this.processGroupV2MessageCreated(msg, 'v1', inlineGeneration);
+                return;
+            }
             if (payload === undefined || payload === null
                 || (typeof payload === 'object' && Object.keys(payload).length === 0)) {
                 await this.autoPullGroupMessages(msg);
@@ -873,7 +1653,7 @@ export class MessageDeliveryEngine {
                     : await this.publishOrderedMessage('group.message_created', ns, seq, msg);
                 const contigAfter = client._seqTracker.getContiguousSeq(ns);
                 const needPull = seqNeedsPull && !published;
-                if (needPull) {
+                if (needPull && client._sessionOptions?.background_sync !== false) {
                     client._safeAsync(this.fillGroupGap(groupId));
                 }
                 const contig = client._seqTracker.getContiguousSeq(ns);
@@ -924,56 +1704,53 @@ export class MessageDeliveryEngine {
             await client._publishAppEvent('group.message_created', notification);
             return;
         }
-        const ns = `group:${groupId}`;
+        if (client._sessionOptions?.background_sync === false) {
+            client._clientLog.debug(`auto pull group messages skipped: group=${groupId} background_sync=false`);
+            return;
+        }
+        const ns = this.resolvePendingGroupInlineAckNamespace(`group:${groupId}`);
         const afterSeq = client._seqTracker.getContiguousSeq(ns);
-        try {
-            if (client._v2Session) {
-                await client._withBackgroundRpc(() => client._pullGroupV2Internal({ group_id: groupId, after_seq: afterSeq, limit: 50 }));
+        if (client._v2Session) {
+            try {
+                const key = client._rpcPipeline.pullGateKeyForCall('group.pull', { group_id: groupId, after_seq: afterSeq, limit: 50 });
+                await client._rpcPipeline.runPullSerialized(key, () => client._pullGroupV2(groupId, afterSeq, 50, { gateLocked: true }), true);
+                return;
+            }
+            catch (exc) {
+                client._clientLog.warn(`auto pull group message failed:${String(exc)}`);
+                await client._publishAppEvent('group.message_created', notification);
                 return;
             }
-            const result = await client.call('group.pull', {
+        }
+        let rawCompleted = false;
+        try {
+            const key = client._rpcPipeline.pullGateKeyForCall('group.pull', {
                 group_id: groupId,
                 after_message_seq: afterSeq,
-                device_id: client._deviceId,
                 limit: 50,
-                _rpc_background: true,
             });
-            if (isJsonObject(result)) {
-                const messages = result.messages;
-                if (Array.isArray(messages)) {
-                    const pushed = client._pushedSeqs.get(ns);
-                    for (const msg of messages) {
-                        if (isJsonObject(msg)) {
-                            const s = msg.seq;
-                            if (pushed && s !== undefined && s !== null && pushed.has(s)) {
-                                continue;
-                            }
-                            // 群撤回 tombstone（占位 / 通知）：归一化为 group.message_recalled 事件，仍占 seq。
-                            // 与 V2 pull 路径（v2-e2ee.ts pullGroupV2）对齐，避免 legacy 回退路径把撤回
-                            // tombstone 当普通 group.message_created 投递给应用层。
-                            if (s !== undefined && s !== null
-                                && this.recallEventFromGroupMessage(msg)) {
-                                await this.publishGroupRecallTombstone(groupId, s, msg);
-                                this.markPublishedSeq(ns, Number(s));
-                                continue;
-                            }
-                            if (s !== undefined && s !== null) {
-                                await client._publishPulledMessage('group.message_created', ns, s, msg);
-                            }
-                            else {
-                                await client._publishAppEvent('group.message_created', msg);
-                            }
-                        }
-                    }
-                    this.prunePushedSeqs(ns);
-                    return;
-                }
-            }
-        }
-        catch (exc) {
-            client._clientLog.warn(`auto pull group message failed:${String(exc)}`);
+            await client._rpcPipeline.runPullSerialized(key, async () => {
+                const result = await client._rpcPipeline.rawCall('group.pull', {
+                    group_id: groupId,
+                    after_message_seq: afterSeq,
+                    device_id: client._deviceId,
+                    slot_id: client._slotId,
+                    limit: 50,
+                    _rpc_background: true,
+                }, { background: true });
+                rawCompleted = true;
+                await this.commitPlainForwardPage(ns, afterSeq, 'group.pull', result, groupId);
+                this.prunePushedSeqs(ns);
+            }, true);
+        }
+        catch (exc) {
+            // 页发布或本地提交失败不能 ACK；提交后 ACK 失败则保留 pending。
+            // 两种情况都不能再把原始通知当作第二条业务消息发布。
+            client._clientLog.warn(`auto pull group message commit/ack failed:${String(exc)}`);
+            if (!rawCompleted) {
+                await client._publishAppEvent('group.message_created', notification);
+            }
         }
-        await client._publishAppEvent('group.message_created', notification);
     }
     scheduleP2pGapRetry(ns, retryAttempt) {
         const client = this.runtime.client;
@@ -994,6 +1771,8 @@ export class MessageDeliveryEngine {
     }
     async fillP2pGap(retryAttempt = 0) {
         const client = this.runtime.client;
+        if (client._sessionOptions?.background_sync === false)
+            return;
         if (client.state !== ConnectionState.READY || client._closing)
             return;
         if (!client._aid)
@@ -1007,7 +1786,8 @@ export class MessageDeliveryEngine {
         this.runtime.delivery.setGapFillActive(true);
         let filled = 0;
         try {
-            const messages = await client._withBackgroundRpc(() => client._pullV2(afterSeq, 50));
+            const key = client._rpcPipeline.pullGateKeyForCall('message.pull', { after_seq: afterSeq, limit: 50 });
+            const messages = await client._rpcPipeline.runPullSerialized(key, () => client._pullV2(afterSeq, 50, { gateLocked: true }), true);
             filled = messages.length;
             this.prunePushedSeqs(ns);
         }
@@ -1031,6 +1811,7 @@ export class MessageDeliveryEngine {
         finally {
             client._gapFillDone.delete(dedupKey);
             this.runtime.delivery.setGapFillActive(false);
+            this.schedulePendingPullIfNeeded(ns, 'gap-fill-complete');
         }
     }
     async fillP2pGapWithPlainPull(ns, afterSeq) {
@@ -1042,31 +1823,17 @@ export class MessageDeliveryEngine {
             slot_id: client._slotId,
             _rpc_background: true,
         };
-        const raw = await client._transport.call('message.pull', params, undefined, undefined, true);
-        const result = typeof client._rpcPipeline?.postprocessResult === 'function'
-            ? await client._rpcPipeline.postprocessResult('message.pull', params, raw)
-            : raw;
-        const messages = (isJsonObject(result) && Array.isArray(result.messages))
-            ? result.messages
-            : [];
-        let published = 0;
-        for (const item of messages) {
-            if (!isJsonObject(item))
-                continue;
-            const msg = item;
-            const seq = Number(msg.seq ?? 0);
-            const appEvent = p2pAppEventFromPlainPullMessage(msg);
-            if (await this.publishPulledMessage(appEvent.event, ns, seq, appEvent.payload)) {
-                published += 1;
-            }
-        }
-        return published;
+        const raw = await client._rpcPipeline.rawCall('message.pull', params, { background: true });
+        const page = await this.commitPlainForwardPage(ns, afterSeq, 'message.pull', raw);
+        return page.publishedCount;
     }
     async fillGroupGap(groupId) {
         const client = this.runtime.client;
+        if (client._sessionOptions?.background_sync === false)
+            return;
         if (client.state !== ConnectionState.READY || client._closing)
             return;
-        groupId = normalizeGroupId(groupId) || String(groupId ?? '').trim();
+        groupId = String(groupId ?? '').trim();
         if (!groupId)
             return;
         const ns = `group:${groupId}`;
@@ -1078,7 +1845,8 @@ export class MessageDeliveryEngine {
         this.runtime.delivery.setGapFillActive(true);
         let filled = 0;
         try {
-            const messages = await client._withBackgroundRpc(() => client._pullGroupV2(groupId, afterSeq, 50));
+            const key = client._rpcPipeline.pullGateKeyForCall('group.pull', { group_id: groupId, after_seq: afterSeq, limit: 50 });
+            const messages = await client._rpcPipeline.runPullSerialized(key, () => client._pullGroupV2(groupId, afterSeq, 50, { gateLocked: true }), true);
             filled = messages.length;
             this.prunePushedSeqs(ns);
         }
@@ -1091,35 +1859,44 @@ export class MessageDeliveryEngine {
             if (filled > 0 && client._seqTracker.getContiguousSeq(ns) > afterSeq) {
                 client._safeAsync(this.fillGroupGap(groupId));
             }
+            this.schedulePendingPullIfNeeded(ns, 'gap-fill-complete');
         }
     }
-    async fillGroupEventGap(groupId) {
+    async fillGroupEventGap(groupId, options) {
         const client = this.runtime.client;
+        if (client._sessionOptions?.background_sync === false)
+            return;
         if (client.state !== ConnectionState.READY || client._closing)
             return;
-        groupId = normalizeGroupId(groupId) || String(groupId ?? '').trim();
+        groupId = String(groupId ?? '').trim();
         if (!groupId)
             return;
         const ns = `group_event:${groupId}`;
-        const afterSeq = client._seqTracker.getContiguousSeq(ns);
+        const requestedAfterSeq = Number(options?.afterSeq ?? 0);
+        const afterSeq = Number.isSafeInteger(requestedAfterSeq) && requestedAfterSeq > 0
+            ? requestedAfterSeq
+            : client._seqTracker.getContiguousSeq(ns);
+        const singlePage = options?.singlePage === true;
         const dedupKey = `group_event_pull:${ns}`;
         if (client._gapFillDone.has(dedupKey))
             return;
         client._gapFillDone.add(dedupKey);
         this.runtime.delivery.setGapFillActive(true);
+        let continuationAfterSeq = 0;
         try {
             let nextAfterSeq = afterSeq;
-            const maxPages = 100;
+            const maxPages = singlePage ? 1 : 100;
             let pageCount = 0;
             while (pageCount < maxPages) {
                 pageCount += 1;
-                const result = await client.call('group.pull_events', {
+                const request = {
                     group_id: groupId,
                     after_event_seq: nextAfterSeq,
                     device_id: client._deviceId,
                     limit: 50,
                     _rpc_background: true,
-                });
+                };
+                const result = await client.call('group.pull_events', request);
                 if (!isJsonObject(result))
                     return;
                 const events = result.events;
@@ -1131,12 +1908,16 @@ export class MessageDeliveryEngine {
                     client._seqTracker.onPullResult(ns, eventObjects, nextAfterSeq);
                 }
                 const cursor = isJsonObject(result.cursor) ? result.cursor : null;
-                const serverAck = cursor ? Number(cursor.current_seq ?? 0) : 0;
-                if (serverAck > 0) {
+                const retentionFloor = Math.max(0, Number(result.retention_floor_event_seq ?? 0), Number(cursor?.retention_floor_seq ?? 0));
+                const serverAckFloor = Math.max(0, Number(cursor?.current_seq ?? 0));
+                const earliestAvailable = Number(result.earliest_available_event_seq ?? 0);
+                const visibilityFloor = Math.max(0, Number(cursor?.join_seq ?? 0), Number.isFinite(earliestAvailable) && earliestAvailable > 0 ? earliestAvailable - 1 : 0);
+                const effectiveFloor = Math.max(...[retentionFloor, serverAckFloor, visibilityFloor].filter((value) => Number.isFinite(value)));
+                if (effectiveFloor > 0) {
                     const contigBeforeFloor = client._seqTracker.getContiguousSeq(ns);
-                    if (contigBeforeFloor < serverAck) {
-                        client._clientLog.info('group.pull_events retention-floor advance: ns=' + ns + ' contiguous=' + contigBeforeFloor + ' -> cursor.current_seq=' + serverAck);
-                        client._seqTracker.forceContiguousSeq(ns, serverAck);
+                    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 = [];
@@ -1171,17 +1952,28 @@ export class MessageDeliveryEngine {
                     this.persistSeq(ns);
                 }
                 if (eventObjects.length > 0 && ackContig > 0 && ackContig !== pageContigBefore) {
-                    const ackSeq = this.clampAckSeq('group.ack_events', 'event_seq', ns, ackContig);
-                    client._transport.call('group.ack_events', {
-                        group_id: groupId,
-                        event_seq: ackSeq,
-                        device_id: client._deviceId,
-                        slot_id: client._slotId,
-                        _rpc_background: true,
-                    }).catch((e) => { client._clientLog.warn('group event auto-ack failed: group=' + groupId, e); });
+                    try {
+                        const ackPromise = client._transport.call('group.ack_events', {
+                            group_id: groupId,
+                            event_seq: ackContig,
+                            device_id: client._deviceId,
+                            slot_id: client._slotId,
+                            _rpc_background: true,
+                        });
+                        if (singlePage)
+                            await ackPromise;
+                        else
+                            ackPromise.catch((e) => { client._clientLog.warn('group event auto-ack failed: group=' + groupId, e); });
+                    }
+                    catch (e) {
+                        client._clientLog.warn('group event auto-ack failed: group=' + groupId, e);
+                    }
                 }
                 const nextAfter = Math.max(eventSeqs.length > 0 ? Math.max(...eventSeqs) : nextAfterSeq, nextAfterSeq);
-                if (eventObjects.length === 0 || nextAfter <= nextAfterSeq || result.has_more === false)
+                if (singlePage && result.has_more === true && nextAfter > nextAfterSeq) {
+                    continuationAfterSeq = nextAfter;
+                }
+                if (eventObjects.length === 0 || nextAfter <= nextAfterSeq || result.has_more !== true)
                     break;
                 nextAfterSeq = nextAfter;
             }
@@ -1195,11 +1987,17 @@ export class MessageDeliveryEngine {
         finally {
             client._gapFillDone.delete(dedupKey);
             this.runtime.delivery.setGapFillActive(false);
+            if (singlePage && continuationAfterSeq > afterSeq) {
+                this.enqueueOnlineUnreadEventHint({
+                    group_id: groupId,
+                    _online_hint_after_event_seq: continuationAfterSeq,
+                });
+            }
         }
     }
     async handleGroupChangedEventSeq(data, groupId) {
         const client = this.runtime.client;
-        groupId = normalizeGroupId(groupId) || String(groupId ?? '').trim();
+        groupId = String(groupId ?? '').trim();
         let needPull = false;
         const rawEventSeq = data.event_seq;
         const eventSeq = Number(rawEventSeq);
@@ -1208,6 +2006,15 @@ export class MessageDeliveryEngine {
             return;
         }
         const ns = `group_event:${groupId}`;
+        if (String(data.kind ?? '').trim() === 'group.online_unread_hint') {
+            if (client._sessionOptions?.background_sync === false) {
+                client._clientLog.debug(`group.changed online unread hint skipped: group=${groupId} background_sync=false`);
+                return;
+            }
+            client._clientLog.debug(`group.changed online unread hint triggering event Forward: group=${groupId}, event_seq=${eventSeq}`);
+            this.enqueueOnlineUnreadEventHint(data);
+            return;
+        }
         if (this.isSelfJoinGroupChanged(data)) {
             const contig = client._seqTracker.getContiguousSeq(ns);
             const maxSeen = client._seqTracker.getMaxSeenSeq(ns);
@@ -1235,10 +2042,9 @@ export class MessageDeliveryEngine {
         if (ackContig > 0 && ackContig !== contigBefore) {
             if (data.action !== 'dissolved')
                 this.persistSeq(ns);
-            const ackSeq = this.clampAckSeq('group.ack_events', 'event_seq', ns, ackContig);
             client._transport.call('group.ack_events', {
                 group_id: groupId,
-                event_seq: ackSeq,
+                event_seq: ackContig,
                 device_id: client._deviceId,
                 slot_id: client._slotId,
                 _rpc_background: true,
@@ -1246,7 +2052,7 @@ export class MessageDeliveryEngine {
                 client._clientLog.warn('group event push auto-ack failed: group=' + groupId, e);
             });
         }
-        if (needPull && groupId && !data._from_gap_fill) {
+        if (needPull && groupId && !data._from_gap_fill && client._sessionOptions?.background_sync !== false) {
             client._safeAsync(this.fillGroupEventGap(groupId));
         }
     }
@@ -1268,185 +2074,882 @@ export class MessageDeliveryEngine {
         const groupId = String(data.group_id ?? '').trim();
         if (!groupId)
             return;
-        client._onlineUnreadHintQueue.set(groupId, { ...data });
-        if (client._onlineUnreadHintTimer || client._onlineUnreadHintDrainActive)
-            return;
-        const delayMs = Math.max(0, Number(client._onlineUnreadHintInitialDelayMs ?? 750) || 0);
-        this.runtime.delivery.setOnlineUnreadHintTimer(setTimeout(() => {
-            this.runtime.delivery.setOnlineUnreadHintTimer(null);
-            client._safeAsync(this.drainOnlineUnreadHints());
-        }, delayMs));
+        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)}`);
+        }));
     }
-    async drainOnlineUnreadHints() {
+    enqueueOnlineUnreadEventHint(data) {
         const client = this.runtime.client;
-        if (client._onlineUnreadHintDrainActive)
+        const groupId = String(data.group_id ?? '').trim();
+        if (!groupId || client._sessionOptions?.background_sync === false)
             return;
-        this.runtime.delivery.setOnlineUnreadHintDrainActive(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, {
+            afterSeq,
+            singlePage: true,
+        }));
+    }
+    async runP2PForwardRecovery(ns, pageLimit, background = false) {
+        const client = this.runtime.client;
+        const request = {
+            after_seq: this.syncState(ns).ack,
+            limit: pageLimit,
+            max_pages: 1,
+        };
+        const invoke = async () => {
+            const after = this.syncState(ns).ack;
+            const messages = await client._pullV2(after, pageLimit, { gateLocked: true, maxPages: 1 });
+            return { messages, raw_count: messages.length };
+        };
+        const pipeline = client._rpcPipeline;
+        if (!pipeline)
+            return await invoke();
+        const key = pipeline.pullGateKeyForCall('message.pull', request);
+        return await pipeline.runPullSerialized(key, invoke, background);
+    }
+    async runGroupForwardRecovery(groupId, ns, pageLimit, background = false) {
+        const client = this.runtime.client;
+        const request = {
+            group_id: groupId,
+            after_seq: this.syncState(ns).ack,
+            limit: pageLimit,
+            max_pages: 1,
+        };
+        const invoke = async () => {
+            const after = this.syncState(ns).ack;
+            const messages = await client._pullGroupV2(groupId, after, pageLimit, { gateLocked: true, maxPages: 1 });
+            return { messages, raw_count: messages.length };
+        };
+        const pipeline = client._rpcPipeline;
+        if (!pipeline)
+            return await invoke();
+        const key = pipeline.pullGateKeyForCall('group.pull', request);
+        return await pipeline.runPullSerialized(key, invoke, background);
+    }
+    syncState(ns) {
+        const tracker = this.runtime.client._seqTracker;
+        if (typeof tracker.getSyncState === 'function')
+            return tracker.getSyncState(ns);
+        const ack = Number(tracker.getContiguousSeq(ns) || 0);
+        return { ack, tail: ack, head: Math.max(ack, Number(tracker.getMaxSeenSeq?.(ns) || 0)) };
+    }
+    inlineMessage(data) {
+        if (!isJsonObject(data))
+            return null;
+        const inline = data.inline_message;
+        return isJsonObject(inline)
+            ? inline
+            : null;
+    }
+    boundString(source, keys) {
+        for (const key of keys) {
+            if (Object.prototype.hasOwnProperty.call(source, key)) {
+                return { present: true, value: String(source[key] ?? '').trim() };
+            }
+        }
+        return { present: false, value: '' };
+    }
+    sameRequiredBinding(left, leftKeys, right, rightKeys) {
+        const lhs = this.consistentBindingValue(left, leftKeys);
+        const rhs = this.consistentBindingValue(right, rightKeys);
+        return lhs.present && rhs.present && Boolean(lhs.value) && lhs.value === rhs.value;
+    }
+    consistentBindingValue(source, keys) {
+        const binding = this.strictBoundString(source, keys);
+        return binding.present && binding.valid
+            ? { present: true, value: binding.value }
+            : { present: false, value: '' };
+    }
+    strictBoundString(source, keys) {
+        let value = null;
+        for (const key of keys) {
+            if (!Object.prototype.hasOwnProperty.call(source, key))
+                continue;
+            const raw = source[key];
+            if (typeof raw !== 'string')
+                return { present: true, valid: false, value: '' };
+            const candidate = raw.trim();
+            if (!candidate || (value !== null && candidate !== value)) {
+                return { present: true, valid: false, value: '' };
+            }
+            value = candidate;
+        }
+        return { present: value !== null, valid: value !== null, value: value ?? '' };
+    }
+    onlyEmptyOptionalStrings(source, keys) {
+        for (const key of keys) {
+            if (!Object.prototype.hasOwnProperty.call(source, key))
+                continue;
+            const raw = source[key];
+            if (typeof raw !== 'string' || raw.trim())
+                return false;
+        }
+        return true;
+    }
+    inlineTargetMatchesCurrentInstance(head, inline) {
+        const client = this.runtime.client;
+        const explicitHeadDevice = this.strictTargetString(head, 'target_device_id');
+        if (explicitHeadDevice.present && !explicitHeadDevice.valid)
+            return false;
+        const headDevice = explicitHeadDevice.present
+            ? explicitHeadDevice
+            : this.strictBoundString(head, ['device_id']);
+        if (!headDevice.present || !headDevice.valid
+            || headDevice.value !== String(client._deviceId ?? '').trim())
+            return false;
+        const explicitRowDevice = this.strictTargetString(inline, 'target_device_id');
+        if (explicitRowDevice.present
+            && (!explicitRowDevice.valid || explicitRowDevice.value !== headDevice.value))
+            return false;
+        if (!explicitRowDevice.present) {
+            const rowDevice = this.strictBoundString(inline, ['device_id']);
+            if (rowDevice.present && (!rowDevice.valid || rowDevice.value !== headDevice.value))
+                return false;
+        }
+        const currentSlot = slotIsolationKey(String(client._slotId ?? ''));
+        const explicitHeadSlot = this.strictTargetString(head, 'target_slot_id');
+        if (explicitHeadSlot.present && !explicitHeadSlot.valid)
+            return false;
+        const headSlot = explicitHeadSlot.present
+            ? explicitHeadSlot
+            : this.strictBoundString(head, ['slot_id']);
+        if (headSlot.present && (!headSlot.valid || slotIsolationKey(headSlot.value) !== currentSlot))
+            return false;
+        const explicitRowSlot = this.strictTargetString(inline, 'target_slot_id');
+        if (explicitRowSlot.present && (!explicitRowSlot.valid
+            || slotIsolationKey(explicitRowSlot.value) !== currentSlot
+            || (headSlot.present
+                && slotIsolationKey(explicitRowSlot.value) !== slotIsolationKey(headSlot.value))))
+            return false;
+        if (!explicitRowSlot.present) {
+            const rowSlot = this.strictBoundString(inline, ['slot_id']);
+            if (rowSlot.present && (!rowSlot.valid
+                || slotIsolationKey(rowSlot.value) !== currentSlot
+                || (headSlot.present
+                    && slotIsolationKey(rowSlot.value) !== slotIsolationKey(headSlot.value))))
+                return false;
+        }
+        return true;
+    }
+    inlineV2Envelope(inline) {
+        const raw = inline.envelope_json;
+        if (typeof raw !== 'string' || !raw.trim())
+            return null;
         try {
-            while (client._onlineUnreadHintQueue.size > 0) {
-                if (client.state !== ConnectionState.READY)
-                    return;
-                if (client._sessionOptions?.background_sync === false)
+            const envelope = JSON.parse(raw);
+            return isJsonObject(envelope)
+                ? envelope
+                : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    isInlineV2Row(inline) {
+        return inline.version === 'v2'
+            && typeof inline.envelope_json === 'string'
+            && Boolean(inline.envelope_json.trim());
+    }
+    inlineRecipientMatchesCurrentInstance(envelope) {
+        if (Object.prototype.hasOwnProperty.call(envelope, 'recipients'))
+            return false;
+        if (!isJsonObject(envelope.recipient))
+            return false;
+        const recipient = envelope.recipient;
+        const client = this.runtime.client;
+        if (typeof recipient.aid !== 'string' || typeof recipient.device_id !== 'string'
+            || typeof client._aid !== 'string' || typeof client._deviceId !== 'string'
+            || !recipient.aid || !client._aid || !client._deviceId
+            || recipient.aid !== client._aid)
+            return false;
+        const hasDeliveryDevice = Object.prototype.hasOwnProperty.call(envelope, 'delivery_device_id');
+        const deliveryDevice = envelope.delivery_device_id;
+        if (hasDeliveryDevice
+            && (typeof deliveryDevice !== 'string' || !deliveryDevice || deliveryDevice !== client._deviceId))
+            return false;
+        if (recipient.device_id)
+            return recipient.device_id === client._deviceId;
+        return hasDeliveryDevice;
+    }
+    inlineP2PBindingMatches(head, inline, seq, expectedInlineVersion) {
+        if (typeof head.seq !== 'number' || !Number.isSafeInteger(head.seq) || head.seq <= 0 || head.seq !== seq
+            || typeof inline.seq !== 'number' || !Number.isSafeInteger(inline.seq) || inline.seq <= 0 || inline.seq !== seq
+            || inline.version !== expectedInlineVersion
+            || !this.sameRequiredBinding(head, ['message_id'], inline, ['message_id'])
+            || !this.sameRequiredBinding(head, ['from_aid', 'sender_aid', 'from'], inline, ['from_aid', 'sender_aid', 'from'])
+            || !this.sameRequiredBinding(head, ['sender_device_id'], inline, ['sender_device_id'])
+            || !this.inlineTargetMatchesCurrentInstance(head, inline))
+            return false;
+        const logicalTo = this.consistentBindingValue(head, ['to_aid', 'to']);
+        if (!logicalTo.present || !logicalTo.value)
+            return false;
+        if (expectedInlineVersion === 'v1') {
+            if (Object.prototype.hasOwnProperty.call(inline, 'envelope_json')
+                || Object.prototype.hasOwnProperty.call(inline, 'payload')
+                || !isJsonObject(inline.legacy_v1))
+                return false;
+            const legacy = inline.legacy_v1;
+            const payload = legacy.payload;
+            if (payload === undefined || payload === null)
+                return false;
+            if (isJsonObject(payload)) {
+                const payloadType = String(payload.type ?? '').trim();
+                if (payloadType === 'e2ee.encrypted' || payloadType === 'e2ee.group_encrypted')
+                    return false;
+            }
+            const legacyTo = this.strictBoundString(legacy, ['to']);
+            return legacyTo.present && legacyTo.valid && legacyTo.value === logicalTo.value;
+        }
+        if (!this.isInlineV2Row(inline)
+            || Object.prototype.hasOwnProperty.call(inline, 'legacy_v1')
+            || Object.prototype.hasOwnProperty.call(inline, 'payload')
+            || !this.onlyEmptyOptionalStrings(head, ['group_id', 'group_aid'])
+            || !this.onlyEmptyOptionalStrings(inline, ['group_id', 'group_aid']))
+            return false;
+        const envelope = this.inlineV2Envelope(inline);
+        if (!envelope
+            || envelope.type !== 'e2ee.p2p_encrypted'
+            || envelope.version !== 'v2'
+            || !this.onlyEmptyOptionalStrings(envelope, ['group_id'])
+            || !this.inlineRecipientMatchesCurrentInstance(envelope))
+            return false;
+        if (!isJsonObject(envelope.aad))
+            return false;
+        const aad = envelope.aad;
+        if (!this.onlyEmptyOptionalStrings(aad, ['group_id']))
+            return false;
+        const aadMessageId = this.consistentBindingValue(aad, ['message_id']);
+        const aadFrom = this.consistentBindingValue(aad, ['from']);
+        const aadFromDevice = this.consistentBindingValue(aad, ['from_device']);
+        const aadTo = this.consistentBindingValue(aad, ['to']);
+        if (!aadMessageId.present || aadMessageId.value !== this.consistentBindingValue(inline, ['message_id']).value
+            || !aadFrom.present || aadFrom.value !== this.consistentBindingValue(inline, ['from_aid', 'sender_aid', 'from']).value
+            || !aadFromDevice.present || aadFromDevice.value !== this.consistentBindingValue(inline, ['sender_device_id']).value
+            || !aadTo.present)
+            return false;
+        if (aadTo.value === logicalTo.value)
+            return true;
+        const recipient = envelope.recipient;
+        return typeof recipient.role === 'string'
+            && recipient.role.trim() === 'self_sync'
+            && aadTo.value.length > 0
+            && aadFrom.value === String(this.runtime.client._aid ?? '').trim()
+            && logicalTo.value === String(this.runtime.client._aid ?? '').trim();
+    }
+    inlineGroupBindingMatches(head, inline, groupId, seq, expectedInlineVersion) {
+        const headGroupId = this.strictBoundString(head, ['group_id']);
+        const rowGroupId = this.strictBoundString(inline, ['group_id']);
+        const headGroupAid = this.strictBoundString(head, ['group_aid']);
+        const rowGroupAid = this.strictBoundString(inline, ['group_aid']);
+        if (typeof head.seq !== 'number' || !Number.isSafeInteger(head.seq) || head.seq <= 0 || head.seq !== seq
+            || typeof inline.seq !== 'number' || !Number.isSafeInteger(inline.seq) || inline.seq <= 0 || inline.seq !== seq
+            || inline.version !== expectedInlineVersion
+            || !headGroupId.present || !headGroupId.valid || headGroupId.value !== groupId
+            || !rowGroupId.present || !rowGroupId.valid || rowGroupId.value !== groupId
+            || (headGroupAid.present && !headGroupAid.valid)
+            || (rowGroupAid.present && !rowGroupAid.valid)
+            || !this.sameRequiredBinding(head, ['message_id'], inline, ['message_id'])
+            || !this.sameRequiredBinding(head, ['sender_aid', 'from_aid', 'from'], inline, ['from_aid', 'sender_aid', 'from'])
+            || !this.sameRequiredBinding(head, ['sender_device_id'], inline, ['sender_device_id'])
+            || !this.inlineTargetMatchesCurrentInstance(head, inline))
+            return false;
+        if (expectedInlineVersion === 'v1') {
+            if (Object.prototype.hasOwnProperty.call(inline, 'envelope_json')
+                || Object.prototype.hasOwnProperty.call(inline, 'legacy_v1')
+                || !Object.prototype.hasOwnProperty.call(inline, 'payload')
+                || inline.payload === null
+                || inline.payload === undefined)
+                return false;
+            if (isJsonObject(inline.payload)) {
+                const payloadType = String(inline.payload.type ?? '').trim();
+                if (payloadType === 'e2ee.encrypted' || payloadType === 'e2ee.group_encrypted')
+                    return false;
+            }
+            return true;
+        }
+        if (!this.isInlineV2Row(inline)
+            || Object.prototype.hasOwnProperty.call(inline, 'legacy_v1')
+            || Object.prototype.hasOwnProperty.call(inline, 'payload'))
+            return false;
+        const envelope = this.inlineV2Envelope(inline);
+        const envelopeGroupId = envelope ? this.strictBoundString(envelope, ['group_id']) : null;
+        if (!envelope
+            || envelope.type !== 'e2ee.group_encrypted'
+            || envelope.version !== 'v2'
+            || (envelopeGroupId?.present && (!envelopeGroupId.valid || envelopeGroupId.value !== groupId))
+            || !this.inlineRecipientMatchesCurrentInstance(envelope))
+            return false;
+        if (!isJsonObject(envelope.aad))
+            return false;
+        const aad = envelope.aad;
+        return this.consistentBindingValue(aad, ['message_id']).value === this.consistentBindingValue(inline, ['message_id']).value
+            && this.consistentBindingValue(aad, ['from']).value === this.consistentBindingValue(inline, ['from_aid', 'sender_aid', 'from']).value
+            && this.consistentBindingValue(aad, ['from_device']).value === this.consistentBindingValue(inline, ['sender_device_id']).value
+            && this.consistentBindingValue(aad, ['group_id']).value === groupId;
+    }
+    inlineWindowReady(ns, seq) {
+        if (!ns || !Number.isSafeInteger(seq) || seq <= 0)
+            return false;
+        const expected = seq - 1;
+        const state = this.syncState(ns);
+        if (state.ack !== expected || state.tail !== expected || state.head !== expected)
+            return false;
+        const client = this.runtime.client;
+        // 入口会先登记当前 Push 的 Head，因此 maxSeen==seq 仍是合法的
+        // 单条 inline 快路径；只有已经观察到更高序号时才退回同步路径。
+        if (Number(client._seqTracker.getMaxSeenSeq?.(ns) ?? expected) > seq)
+            return false;
+        const pending = client._pendingOrderedMsgs.get(ns);
+        return !pending || pending.size === 0;
+    }
+    decodedInlineP2PMatches(head, decoded, seq) {
+        const decodedMessageId = this.consistentBindingValue(decoded, ['message_id']);
+        const headMessageId = this.consistentBindingValue(head, ['message_id']);
+        const decodedFrom = this.consistentBindingValue(decoded, ['from', 'from_aid', 'sender_aid']);
+        const headFrom = this.consistentBindingValue(head, ['from_aid', 'sender_aid', 'from']);
+        const decodedTo = this.consistentBindingValue(decoded, ['to', 'to_aid']);
+        const headTo = this.consistentBindingValue(head, ['to_aid', 'to']);
+        return typeof decoded.seq === 'number' && Number.isSafeInteger(decoded.seq) && decoded.seq === seq
+            && decodedMessageId.present && headMessageId.present && decodedMessageId.value === headMessageId.value
+            && decodedFrom.present && headFrom.present && decodedFrom.value === headFrom.value
+            && decodedTo.present && headTo.present && decodedTo.value === headTo.value;
+    }
+    decodedInlineGroupMatches(head, decoded, groupId, seq) {
+        const decodedMessageId = this.consistentBindingValue(decoded, ['message_id']);
+        const headMessageId = this.consistentBindingValue(head, ['message_id']);
+        const decodedFrom = this.consistentBindingValue(decoded, ['from', 'from_aid', 'sender_aid']);
+        const headFrom = this.consistentBindingValue(head, ['sender_aid', 'from_aid', 'from']);
+        const decodedGroupId = this.consistentBindingValue(decoded, ['group_id']);
+        return typeof decoded.seq === 'number' && Number.isSafeInteger(decoded.seq) && decoded.seq === seq
+            && decodedMessageId.present && headMessageId.present && decodedMessageId.value === headMessageId.value
+            && decodedFrom.present && headFrom.present && decodedFrom.value === headFrom.value
+            && decodedGroupId.present && decodedGroupId.value === groupId;
+    }
+    async commitInlineMessage(ns, seq, event, payload, generation) {
+        const client = this.runtime.client;
+        const tracker = client._seqTracker;
+        const snapshot = typeof tracker.snapshotNamespace === 'function'
+            ? tracker.snapshotNamespace(ns)
+            : null;
+        try {
+            const published = await this.publishPulledMessage(event, ns, seq, payload);
+            if (!this.isInlineGenerationCurrent(generation))
+                return false;
+            if (!published)
+                return false;
+            const needsPull = Boolean(tracker.onMessageSeq(ns, seq));
+            const committed = this.syncState(ns);
+            if (needsPull || committed.ack !== seq || committed.tail !== seq || committed.head !== seq) {
+                throw new Error('inline realtime cursor did not collapse after consume');
+            }
+            if (!this.isInlineGenerationCurrent(generation))
+                return false;
+            await client._commitSeqTrackerState(ns);
+            if (!this.isInlineGenerationCurrent(generation))
+                return false;
+            return true;
+        }
+        catch (exc) {
+            if (this.isInlineGenerationCurrent(generation) && typeof tracker.restoreNamespaceSnapshot === 'function') {
+                tracker.restoreNamespaceSnapshot(ns, snapshot);
+            }
+            client._clientLog.debug(`inline realtime consume rolled back: ns=${ns} seq=${seq} err=${formatDeliveryError(exc)}`);
+            return false;
+        }
+    }
+    async tryConsumeInlineP2P(head, inline, ns, seq, expectedInlineVersion, generation) {
+        if (!this.isInlineGenerationCurrent(generation)
+            || !this.inlineP2PBindingMatches(head, inline, seq, expectedInlineVersion) || !this.inlineWindowReady(ns, seq))
+            return false;
+        const client = this.runtime.client;
+        try {
+            const result = await client._rpcPipeline.tryRunInlineRealtime(ns, seq, async () => {
+                if (!this.isInlineGenerationCurrent(generation)
+                    || !this.inlineWindowReady(ns, seq)
+                    || !this.inlineP2PBindingMatches(head, inline, seq, expectedInlineVersion)
+                    || !this.reservePendingP2PInlineAck(ns, seq, inline, generation))
+                    return false;
+                let committed = false;
+                try {
+                    const decoded = await client._v2E2EE.decodeInlineP2PMessage(inline);
+                    if (!this.isInlineGenerationCurrent(generation)
+                        || !decoded || !this.decodedInlineP2PMatches(head, decoded, seq)
+                        || !this.inlineWindowReady(ns, seq))
+                        return false;
+                    const appEvent = this.p2pAppEventForMessage(decoded);
+                    if (!await this.commitInlineMessage(ns, seq, appEvent.event, appEvent.payload, generation))
+                        return false;
+                    if (!this.isInlineGenerationCurrent(generation))
+                        return false;
+                    committed = this.markPendingP2PInlineAckCommitted(ns, seq, generation);
+                    return committed;
+                }
+                finally {
+                    if (!committed && this.isInlineGenerationCurrent(generation))
+                        this.dropPendingP2PInlineAck(ns, seq, generation);
+                }
+            });
+            const consumed = this.isInlineGenerationCurrent(generation) && result.acquired === true && result.value === true;
+            return consumed;
+        }
+        catch (exc) {
+            client._clientLog.debug(`inline P2P consume failed: seq=${seq} err=${formatDeliveryError(exc)}`);
+            return false;
+        }
+    }
+    async tryConsumeInlineGroup(head, inline, groupId, ns, seq, expectedInlineVersion, generation) {
+        if (!this.isInlineGenerationCurrent(generation)
+            || !this.inlineGroupBindingMatches(head, inline, groupId, seq, expectedInlineVersion) || !this.inlineWindowReady(ns, seq))
+            return false;
+        const client = this.runtime.client;
+        const groupAid = typeof head.group_aid === 'string' && head.group_aid.trim()
+            ? head.group_aid.trim()
+            : groupId;
+        try {
+            const result = await client._rpcPipeline.tryRunInlineRealtime(ns, seq, async () => {
+                if (!this.isInlineGenerationCurrent(generation)
+                    || !this.inlineWindowReady(ns, seq)
+                    || !this.inlineGroupBindingMatches(head, inline, groupId, seq, expectedInlineVersion)
+                    || !this.reservePendingGroupInlineAck(ns, seq, inline, groupAid, groupId, generation))
+                    return false;
+                let committed = false;
+                try {
+                    const decoded = await client._v2E2EE.decodeInlineGroupMessage(inline, groupId, groupAid);
+                    if (!this.isInlineGenerationCurrent(generation)
+                        || !decoded || !this.decodedInlineGroupMatches(head, decoded, groupId, seq)
+                        || !this.inlineWindowReady(ns, seq))
+                        return false;
+                    if (!await this.commitInlineMessage(ns, seq, 'group.message_created', decoded, generation))
+                        return false;
+                    if (!this.isInlineGenerationCurrent(generation))
+                        return false;
+                    committed = this.markPendingGroupInlineAckCommitted(ns, seq, generation);
+                    return committed;
+                }
+                finally {
+                    if (!committed && this.isInlineGenerationCurrent(generation))
+                        this.dropPendingGroupInlineAck(ns, seq, generation);
+                }
+            });
+            const consumed = this.isInlineGenerationCurrent(generation) && result.acquired === true && result.value === true;
+            return consumed;
+        }
+        catch (exc) {
+            client._clientLog.debug(`inline Group consume failed: group=${groupId} seq=${seq} err=${formatDeliveryError(exc)}`);
+            return false;
+        }
+    }
+    hasOutstandingRealtimeGap(ns) {
+        const state = this.syncState(ns);
+        // Tail 已建立可靠后缀窗口；后台续拉只针对尚未接上窗口的真实缺口。
+        // maxSeen 可能只是 Tail 期间到达的通知，不能单独据此启动全量补洞。
+        return state.ack < state.tail - 1;
+    }
+    scheduleP2PRealtimeFullGapFill(ns) {
+        const client = this.runtime.client;
+        const currentNs = client._aid ? `p2p:${client._aid}` : '';
+        if (client._sessionOptions?.background_sync === false
+            || client.state !== ConnectionState.READY || client._closing
+            || currentNs !== ns || !this.hasOutstandingRealtimeGap(ns))
+            return;
+        const scheduleKey = `p2p_realtime_full_gap:${ns}`;
+        if (client._gapFillDone.has(scheduleKey))
+            return;
+        client._gapFillDone.add(scheduleKey);
+        client._safeAsync(Promise.resolve().then(async () => {
+            try {
+                const liveNs = client._aid ? `p2p:${client._aid}` : '';
+                if (client._sessionOptions?.background_sync === false
+                    || client.state !== ConnectionState.READY || client._closing
+                    || liveNs !== ns || !this.hasOutstandingRealtimeGap(ns))
                     return;
-                const groupId = client._onlineUnreadHintQueue.keys().next().value;
-                if (!groupId)
+                await this.fillP2pGap();
+            }
+            finally {
+                client._gapFillDone.delete(scheduleKey);
+            }
+        }));
+    }
+    scheduleGroupRealtimeFullGapFill(groupId, ns) {
+        const client = this.runtime.client;
+        groupId = String(groupId ?? '').trim();
+        if (!groupId || client._sessionOptions?.background_sync === false
+            || client.state !== ConnectionState.READY || client._closing
+            || !this.hasOutstandingRealtimeGap(ns))
+            return;
+        const scheduleKey = `group_realtime_full_gap:${ns}`;
+        if (client._gapFillDone.has(scheduleKey))
+            return;
+        client._gapFillDone.add(scheduleKey);
+        client._safeAsync(Promise.resolve().then(async () => {
+            try {
+                if (client._sessionOptions?.background_sync === false
+                    || client.state !== ConnectionState.READY || client._closing
+                    || !this.hasOutstandingRealtimeGap(ns))
                     return;
-                const payload = client._onlineUnreadHintQueue.get(groupId);
-                client._onlineUnreadHintQueue.delete(groupId);
-                if (!payload)
-                    continue;
-                await this.onRawGroupV2MessageCreated({ ...payload, _online_hint_drained: true });
-                const intervalMs = Math.max(0, Number(client._onlineUnreadHintIntervalMs ?? 50) || 0);
-                if (intervalMs > 0 && client._onlineUnreadHintQueue.size > 0) {
-                    await new Promise((resolve) => setTimeout(resolve, intervalMs));
-                }
+                await this.fillGroupGap(groupId);
             }
+            finally {
+                client._gapFillDone.delete(scheduleKey);
+            }
+        }));
+    }
+    async runP2PRealtimeSync(ns, pushSeq, pageLimit = 50, forceTail = false) {
+        const client = this.runtime.client;
+        const before = this.syncState(ns);
+        const order = forceTail ? ['tail'] : typeof client._seqTracker.planRealtimeSync === 'function'
+            ? client._seqTracker.planRealtimeSync(ns, pushSeq, pageLimit)
+            : (() => {
+                const gap = pushSeq - before.ack;
+                if (gap <= 0)
+                    return before.ack < before.tail - 1 ? ['forward'] : [];
+                return gap <= pageLimit * 2 ? ['forward'] : ['tail'];
+            })();
+        // Planner 依据 S-A 选路；H 已覆盖 S 也不代表 A 已连续提交，仍需前台 Forward。
+        const headForward = order[0] === 'forward' && pushSeq > before.ack;
+        let result = { messages: [], raw_count: 0 };
+        let tailCompleted = false;
+        const run = async (tail, background, maxPages, forceForward = false, bypassCoveredHead = false) => {
+            const live = this.syncState(ns);
+            if (tail && !bypassCoveredHead && pushSeq <= live.head)
+                return { messages: [], raw_count: 0 };
+            if (!tail && !forceForward && live.ack >= live.tail - 1)
+                return { messages: [], raw_count: 0 };
+            const request = { ...(tail ? { window_mode: 'tail' } : {}), after_seq: live.ack, limit: pageLimit };
+            const key = client._rpcPipeline.pullGateKeyForCall('message.pull', request);
+            return await client._rpcPipeline.runPullSerialized(key, async () => {
+                if (tail) {
+                    const tailResult = await client._v2E2EE.pullV2TailInternal({
+                        window_mode: 'tail', after_seq: live.ack, limit: pageLimit,
+                    }, true);
+                    tailCompleted = true;
+                    return tailResult;
+                }
+                const messages = await client._pullV2(live.ack, pageLimit, {
+                    gateLocked: true,
+                    ...(maxPages ? { maxPages } : {}),
+                });
+                return { messages, raw_count: messages.length };
+            }, background);
+        };
+        if (forceTail || order[0] === 'tail')
+            result = await run(true, false, undefined, false, forceTail);
+        const state = this.syncState(ns);
+        // Tail 的连续性证明只覆盖其返回的 head。Tail 进行期间到达的新
+        // Push 不能再次进入 realtime planner（那会再做一次 Tail）；以已经
+        // 落盘的 ack 为起点，至多补一页普通 Forward 即可恢复该小窗口。
+        const tailMissedDuringPull = tailCompleted
+            && Number(client._seqTracker.getMaxSeenSeq(ns) || 0) > state.head;
+        const pendingThroughSeq = tailMissedDuringPull
+            ? Number(client._seqTracker.getMaxSeenSeq(ns) || 0)
+            : 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 finalState = this.syncState(ns);
+        if (tailCompleted && finalState.ack < finalState.tail - 1) {
+            this.scheduleP2PRealtimeFullGapFill(ns);
+        }
+        if (tailCompleted)
+            this.markRealtimeTailCompleted(result);
+        return result;
+    }
+    async runGroupRealtimeSync(groupId, ns, pushSeq, pageLimit = 50, forceTail = false) {
+        const client = this.runtime.client;
+        const before = this.syncState(ns);
+        const order = forceTail ? ['tail'] : typeof client._seqTracker.planRealtimeSync === 'function'
+            ? client._seqTracker.planRealtimeSync(ns, pushSeq, pageLimit)
+            : (() => {
+                const gap = pushSeq - before.ack;
+                if (gap <= 0)
+                    return before.ack < before.tail - 1 ? ['forward'] : [];
+                return gap <= pageLimit * 2 ? ['forward'] : ['tail'];
+            })();
+        // Planner 依据 S-A 选路；H 已覆盖 S 也不代表 A 已连续提交，仍需前台 Forward。
+        const headForward = order[0] === 'forward' && pushSeq > before.ack;
+        let result = { messages: [], raw_count: 0 };
+        let tailCompleted = false;
+        const run = async (tail, background, maxPages, forceForward = false, bypassCoveredHead = false) => {
+            const live = this.syncState(ns);
+            if (tail && !bypassCoveredHead && pushSeq <= live.head)
+                return { messages: [], raw_count: 0 };
+            if (!tail && !forceForward && live.ack >= live.tail - 1)
+                return { messages: [], raw_count: 0 };
+            const request = { group_id: groupId, ...(tail ? { window_mode: 'tail' } : {}), after_seq: live.ack, limit: pageLimit };
+            const key = client._rpcPipeline.pullGateKeyForCall('group.pull', request);
+            return await client._rpcPipeline.runPullSerialized(key, async () => {
+                if (tail) {
+                    const tailResult = await client._v2E2EE.pullGroupV2TailInternal({
+                        group_id: groupId, window_mode: 'tail', after_seq: live.ack, limit: pageLimit,
+                    }, true);
+                    tailCompleted = true;
+                    return tailResult;
+                }
+                const messages = await client._pullGroupV2(groupId, live.ack, pageLimit, {
+                    gateLocked: true,
+                    ...(maxPages ? { maxPages } : {}),
+                });
+                return { messages, raw_count: messages.length };
+            }, background);
+        };
+        if (forceTail || order[0] === 'tail')
+            result = await run(true, false, undefined, false, forceTail);
+        const state = this.syncState(ns);
+        // 与 P2P 相同：真实完成 Tail 后，至多用一页 Forward 收敛 Tail
+        // 期间新到达的序号；绝不重新规划或再执行 Tail。
+        const tailMissedDuringPull = tailCompleted
+            && Number(client._seqTracker.getMaxSeenSeq(ns) || 0) > state.head;
+        const pendingThroughSeq = tailMissedDuringPull
+            ? Number(client._seqTracker.getMaxSeenSeq(ns) || 0)
+            : 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 finalState = this.syncState(ns);
+        if (tailCompleted && finalState.ack < finalState.tail - 1) {
+            this.scheduleGroupRealtimeFullGapFill(groupId, ns);
+        }
+        if (tailCompleted)
+            this.markRealtimeTailCompleted(result);
+        return result;
+    }
+    async recoverInvalidP2PRealtimeHead(ns, rawSeq) {
+        const client = this.runtime.client;
+        client._clientLog.warn(`V2 P2P inline Head has invalid seq; forcing authoritative Tail: seq=${String(rawSeq)}`);
+        if (!this.beginRealtimeSync(ns))
+            return;
+        try {
+            await this.runP2PRealtimeSync(ns, this.syncState(ns).head, 50, true);
         }
         catch (exc) {
-            client._clientLog.debug(`online unread hint drain failed: ${formatDeliveryError(exc)}`);
+            client._clientLog.warn(`V2 P2P invalid-seq Tail failed: ${formatDeliveryError(exc)}`);
         }
         finally {
-            this.runtime.delivery.setOnlineUnreadHintDrainActive(false);
+            this.endRealtimeSync(ns);
         }
     }
-    async onRawGroupV2MessageCreated(data) {
+    async recoverInvalidGroupRealtimeHead(groupId, ns, rawSeq) {
         const client = this.runtime.client;
-        const tStart = Date.now();
-        if (!isJsonObject(data)) {
-            client._clientLog.debug(`_onRawGroupV2MessageCreated skipped: non-object type=${typeof data}`);
+        client._clientLog.warn(`V2 Group inline Head has invalid seq; forcing authoritative Tail: group=${groupId} seq=${String(rawSeq)}`);
+        if (!this.beginRealtimeSync(ns))
             return;
+        try {
+            await this.runGroupRealtimeSync(groupId, ns, this.syncState(ns).head, 50, true);
         }
-        const groupId = String(data.group_id ?? '').trim();
-        const seq = Number(data.seq ?? 0) || 0;
-        const messageId = String(data.message_id ?? '').trim();
-        const senderAid = String(data.sender_aid ?? '').trim();
-        client._clientLog.debug(`_onRawGroupV2MessageCreated group=${groupId} seq=${seq} message_id=${messageId} sender=${senderAid}`);
-        if (!groupId || seq <= 0) {
-            client._clientLog.debug('_onRawGroupV2MessageCreated skipped: missing group_id or seq');
-            return;
+        catch (exc) {
+            client._clientLog.warn(`V2 Group invalid-seq Tail failed: group=${groupId} err=${formatDeliveryError(exc)}`);
         }
-        if (!client._v2Session) {
-            client._clientLog.debug('_onRawGroupV2MessageCreated skipped: V2 session not initialized');
+        finally {
+            this.endRealtimeSync(ns);
+        }
+    }
+    async onRawGroupV2MessageCreated(data) {
+        const client = this.runtime.client;
+        const row = isJsonObject(data) ? data : null;
+        if (!row)
+            return;
+        const groupId = typeof row.group_id === 'string' ? row.group_id.trim() : '';
+        if (!groupId)
             return;
+        const seq = typeof row.seq === 'number' ? row.seq : 0;
+        const eventKind = String(row.kind ?? '').trim();
+        const ns = this.resolvePendingGroupInlineAckNamespace(`group:${groupId}`);
+        if (client._v2Session && eventKind !== 'group.online_unread_hint'
+            && Number.isSafeInteger(seq) && seq > 0) {
+            // 必须在进入 namespace 队列前登记，才能让在途 Tail 看见后来 Push。
+            client._seqTracker.updateMaxSeen(ns, seq);
         }
+        const hasInlineObject = isJsonObject(row.inline_message)
+            && eventKind !== 'group.online_unread_hint';
+        const inlineGeneration = hasInlineObject ? this.captureInlineGeneration() : undefined;
+        const operation = () => this.processGroupV2MessageCreated(data, 'v2', inlineGeneration);
+        if (hasInlineObject)
+            await this.runPushProcessSerialized(ns, operation, inlineGeneration);
+        else
+            await operation();
+    }
+    async processGroupV2MessageCreated(data, expectedInlineVersion, queuedInlineGeneration) {
+        if (queuedInlineGeneration !== undefined && !this.isInlineGenerationCurrent(queuedInlineGeneration))
+            return;
+        const client = this.runtime.client;
+        if (!isJsonObject(data) || !client._v2Session)
+            return;
+        const groupId = typeof data.group_id === 'string' ? data.group_id.trim() : '';
+        const seq = positiveSafeSequenceHint(data.seq);
+        const strictSeq = typeof data.seq === 'number' && Number.isSafeInteger(data.seq) && data.seq > 0;
+        if (!groupId)
+            return;
         const eventKind = String(data.kind ?? '').trim();
-        if (eventKind === 'group.online_unread_hint' && !data._online_hint_drained) {
-            if (client._sessionOptions?.background_sync === false) {
-                client._clientLog.debug(`_onRawGroupV2MessageCreated skipped online unread hint: group=${groupId} background_sync=false`);
+        // Hint 是恢复信号而不是消息 Head：不得消费 inline、推进水位或直接 ACK。
+        if (eventKind === 'group.online_unread_hint') {
+            if (client._sessionOptions?.background_sync === false)
                 return;
-            }
             this.enqueueOnlineUnreadHint(data);
             return;
         }
-        try {
-            const ns = `group:${groupId}`;
+        const ns = this.resolvePendingGroupInlineAckNamespace(`group:${groupId}`);
+        const inlinePresent = Object.prototype.hasOwnProperty.call(data, 'inline_message');
+        if (seq <= 0) {
+            if (inlinePresent)
+                await this.recoverInvalidGroupRealtimeHead(groupId, ns, data.seq);
+            return;
+        }
+        const inline = this.inlineMessage(data);
+        const inlineMatches = inline !== null
+            && this.inlineGroupBindingMatches(data, inline, groupId, seq, expectedInlineVersion);
+        const pendingInline = this.pendingGroupInlineAcks?.get(ns);
+        const pendingConflict = inline !== null && pendingInline !== undefined && pendingInline.seq !== seq;
+        const inlineGeneration = inlineMatches ? (queuedInlineGeneration ?? this.inlineGeneration) : -1;
+        if (inlineMatches && !pendingConflict
+            && await this.tryConsumeInlineGroup(data, inline, groupId, ns, seq, expectedInlineVersion, inlineGeneration)) {
+            const pending = this.pendingGroupInlineAcks?.get(ns);
+            if (pending)
+                this.retryPendingGroupInlineAck(ns, pending.seq, 'inline Group ack');
+            return;
+        }
+        if (inlineMatches && !this.isInlineGenerationCurrent(inlineGeneration))
+            return;
+        const before = this.syncState(ns);
+        // 无正文的旧服务端 Head 可把 JSON-safe 数字字符串作为恢复 hint；
+        // inline 绑定仍要求原始 seq 是严格 number，避免类型归一化后消费正文。
+        if (strictSeq || !inlinePresent)
             client._seqTracker.updateMaxSeen(ns, seq);
-            const contigBefore = client._seqTracker.getContiguousSeq(ns);
-            if (contigBefore === seq || (eventKind === 'group.online_unread_hint' && contigBefore > seq)) {
-                client._clientLog.debug(`_onRawGroupV2MessageCreated duplicate push already covered: group=${groupId} seq=${seq}`);
-                this.fireGroupV2Ack(groupId, ns, seq, 'group v2 covered push ack');
-                return;
+        if (seq <= before.ack && before.ack >= before.tail - 1) {
+            const canonicalNs = this.resolvePendingGroupInlineAckNamespace(ns);
+            const pending = this.pendingGroupInlineAcks?.get(canonicalNs);
+            if (pending && seq >= pending.seq) {
+                this.retryPendingGroupInlineAck(canonicalNs, pending.seq, 'covered inline Group ack', seq);
             }
-            const afterSeq = client._repairPushContiguousBound(ns, seq, false, '_raw.group.v2.message_created');
-            const dedupKey = `group_pull:${ns}`;
-            if (client._gapFillDone.has(dedupKey)) {
-                client._clientLog.debug(`_onRawGroupV2MessageCreated skipped: dedupKey=${dedupKey} in flight`);
-                return;
-            }
-            client._gapFillDone.add(dedupKey);
-            try {
-                client._clientLog.debug(`_onRawGroupV2MessageCreated -> group.v2.pull group=${groupId} after_seq=${afterSeq}`);
-                const messages = await client._withBackgroundRpc(() => client._pullGroupV2(groupId, afterSeq, 50));
-                client._clientLog.debug(`_onRawGroupV2MessageCreated pulled ${messages.length} msgs for group=${groupId}`);
-            }
-            finally {
-                client._gapFillDone.delete(dedupKey);
+            else if (!inlinePresent || inlineMatches) {
+                this.fireGroupV2Ack(groupId, ns, seq, 'group v2 covered push ack', inlineMatches ? inlineGeneration : null);
             }
+            return;
+        }
+        const pullActive = client._rpcPipeline?.hasPullActivity?.(ns) === true;
+        if (pullActive || !this.beginRealtimeSync(ns)) {
+            this.recordPendingPull(ns, seq);
+            client._clientLog?.debug(`V2 group push queued behind in-flight realtime sync: ns=${ns} seq=${seq}`);
+            return;
+        }
+        try {
+            // namespace 串行区必须覆盖 Tail 与其后至多一次 Forward 的完整周期。
+            await this.runGroupRealtimeSync(groupId, ns, seq, 50, false);
         }
         catch (exc) {
-            client._clientLog.warn(`_onRawGroupV2MessageCreated pull failed group=${groupId}: ${String(exc)}`);
+            client._clientLog.warn(`V2 group push auto-sync failed: group=${groupId} err=${formatDeliveryError(exc)}`);
         }
         finally {
-            client._clientLog.debug(`_onRawGroupV2MessageCreated exit: elapsed=${Date.now() - tStart}ms`);
+            this.endRealtimeSync(ns);
+            this.schedulePendingPullIfNeeded(ns, 'push-auto-pull-complete');
         }
     }
     async onV2PushNotification(data) {
         const client = this.runtime.client;
+        const ns = client._aid ? `p2p:${client._aid}` : '';
+        if (!ns)
+            return;
+        if (isJsonObject(data) && String(data.kind ?? '').trim() === 'message.online_unread_hint') {
+            if (client._sessionOptions?.background_sync === false)
+                return;
+            this.enqueueOnlineUnreadP2pHint(data);
+            return;
+        }
+        const pushSeq = isJsonObject(data) && typeof data.seq === 'number' ? data.seq : 0;
+        if (client._v2Session && Number.isSafeInteger(pushSeq) && pushSeq > 0) {
+            // 与 Group 相同，在排队前暴露更高 Head 给当前在途 Tail。
+            client._seqTracker.updateMaxSeen(ns, pushSeq);
+        }
+        const hasInlineObject = isJsonObject(data)
+            && isJsonObject(data.inline_message);
+        const inlineGeneration = hasInlineObject ? this.captureInlineGeneration() : undefined;
+        const operation = () => this.processV2P2PNotification(data, 'v2', inlineGeneration);
+        if (hasInlineObject)
+            await this.runPushProcessSerialized(ns, operation, inlineGeneration);
+        else
+            await operation();
+    }
+    async processV2P2PNotification(data, expectedInlineVersion, queuedInlineGeneration) {
+        if (queuedInlineGeneration !== undefined && !this.isInlineGenerationCurrent(queuedInlineGeneration))
+            return;
+        const client = this.runtime.client;
         if (!client._v2Session)
             return;
-        const pushSeq = isJsonObject(data) ? Number(data.seq ?? 0) || 0 : 0;
-        const pushFrom = isJsonObject(data) ? String(data.from_aid ?? '') : '';
-        const pushMsgId = isJsonObject(data) ? String(data.message_id ?? '') : '';
-        const envelopeJson = isJsonObject(data) ? data.envelope_json : undefined;
-        const hasPayload = !!envelopeJson;
+        const pushSeq = isJsonObject(data) ? positiveSafeSequenceHint(data.seq) : 0;
+        const strictSeq = isJsonObject(data)
+            && typeof data.seq === 'number' && Number.isSafeInteger(data.seq) && data.seq > 0;
         const ns = client._aid ? `p2p:${client._aid}` : '';
-        let contigBefore = ns ? client._seqTracker.getContiguousSeq(ns) : 0;
-        client._clientLog.debug(`_onV2PushNotification: push_seq=${pushSeq || 'null'} push_from=${pushFrom} push_msg_id=${pushMsgId} has_payload=${hasPayload} contiguous_seq=${contigBefore}`);
-        if (pushSeq > 0 && ns) {
-            client._seqTracker.updateMaxSeen(ns, pushSeq);
-            if (contigBefore === pushSeq) {
-                client._clientLog.debug(`_onV2PushNotification: push seq=${pushSeq} already covered by contiguous_seq=${contigBefore}, ignore duplicate push`);
-                return;
-            }
-            contigBefore = client._repairPushContiguousBound(ns, pushSeq, hasPayload, '_raw.peer.v2.message_received');
+        if (!ns)
+            return;
+        const inlinePresent = isJsonObject(data) && Object.prototype.hasOwnProperty.call(data, 'inline_message');
+        if (pushSeq <= 0) {
+            if (inlinePresent)
+                await this.recoverInvalidP2PRealtimeHead(ns, isJsonObject(data) ? data.seq : undefined);
+            return;
         }
-        if (hasPayload && pushSeq > 0 && ns) {
-            try {
-                const decrypted = await client._decryptV2PushMessage(data);
-                if (decrypted) {
-                    const needPull = client._seqTracker.onMessageSeq(ns, pushSeq);
-                    const published = await client._publishOrderedMessage('message.received', ns, pushSeq, decrypted);
-                    const newContig = client._seqTracker.getContiguousSeq(ns);
-                    if (newContig !== contigBefore) {
-                        this.persistSeq(ns);
-                    }
-                    if (newContig > 0 && newContig !== contigBefore) {
-                        const ackSeq = this.clampAckSeq('message.v2.ack', 'up_to_seq', ns, newContig);
-                        try {
-                            await client._callRawV2Rpc('message.v2.ack', { up_to_seq: ackSeq, _rpc_background: true });
-                        }
-                        catch (e) {
-                            client._clientLog.debug(`V2 P2P push-ack failed: ${e}`);
-                        }
-                    }
-                    client._clientLog.debug(`_onV2PushNotification: push 带 payload 解密成功, contiguous_seq=${contigBefore}->${newContig} push_seq=${pushSeq}`);
-                    if (!needPull && (published || newContig >= pushSeq || pushSeq <= contigBefore)) {
-                        return;
-                    }
-                    client._clientLog.debug(`_onV2PushNotification: payload push seq=${pushSeq} 因空洞挂起，继续 pull 补齐 after_seq=${newContig}`);
-                }
+        const inline = isJsonObject(data) ? this.inlineMessage(data) : null;
+        const inlineMatches = inline !== null
+            && this.inlineP2PBindingMatches(data, inline, pushSeq, expectedInlineVersion);
+        const pendingInline = this.pendingP2PInlineAcks?.get(ns);
+        const pendingConflict = inline !== null && pendingInline !== undefined && pendingInline.seq !== pushSeq;
+        const inlineGeneration = inlineMatches ? (queuedInlineGeneration ?? this.inlineGeneration) : -1;
+        if (inlineMatches && !pendingConflict
+            && await this.tryConsumeInlineP2P(data, inline, ns, pushSeq, expectedInlineVersion, inlineGeneration)) {
+            this.retryPendingP2PInlineAck(ns, pushSeq, 'inline P2P ack');
+            return;
+        }
+        if (inlineMatches && !this.isInlineGenerationCurrent(inlineGeneration))
+            return;
+        const before = this.syncState(ns);
+        if (strictSeq || !inlinePresent)
+            client._seqTracker.updateMaxSeen(ns, pushSeq);
+        if (pushSeq <= before.ack && before.ack >= before.tail - 1) {
+            const pending = this.pendingP2PInlineAcks?.get(ns);
+            if (pending && pushSeq >= pending.seq) {
+                this.retryPendingP2PInlineAck(ns, pending.seq, 'covered inline P2P ack', pushSeq);
             }
-            catch (exc) {
-                client._clientLog.debug(`_onV2PushNotification: push payload 解密失败, fallback to pull: ${exc}`);
+            else if (inlineMatches) {
+                this.fireP2PV2Ack(pushSeq, 'P2P inline covered push ack', inlineGeneration);
             }
+            return;
         }
-        if (pushSeq > 0 && ns) {
-            client._clientLog.debug(`_onV2PushNotification: 纯通知 push_seq=${pushSeq} > contiguous_seq=${contigBefore}, 触发 pull(after_seq=${contigBefore})`);
-        }
-        if (client._v2PullInflight) {
-            this.runtime.delivery.setV2PullPending(true);
+        const pullActive = client._rpcPipeline?.hasPullActivity?.(ns) === true;
+        if (pullActive || !this.beginRealtimeSync(ns)) {
+            this.recordPendingPull(ns, pushSeq);
+            client._clientLog?.debug(`V2 P2P push queued behind in-flight realtime sync: ns=${ns} seq=${pushSeq}`);
             return;
         }
-        this.runtime.delivery.setV2PullInflight(true);
-        const dedupKey = `p2p_pull:${ns}`;
-        client._gapFillDone.add(dedupKey);
         try {
-            do {
-                this.runtime.delivery.setV2PullPending(false);
-                await client._withBackgroundRpc(() => client._pullV2());
-                const newContig = ns ? client._seqTracker.getContiguousSeq(ns) : -1;
-                client._clientLog.debug(`_onV2PushNotification pull done: contiguous_seq=${contigBefore}->${newContig} (push_seq=${pushSeq || 'null'})`);
-            } while (client._v2PullPending);
+            await this.runP2PRealtimeSync(ns, pushSeq, 50, false);
         }
         catch (exc) {
-            const newContig = ns ? client._seqTracker.getContiguousSeq(ns) : -1;
-            client._clientLog.warn(`V2 push auto-pull failed: contiguous_seq=${contigBefore}->${newContig} err=${exc}`);
+            client._clientLog.warn(`V2 P2P push auto-sync failed: ${formatDeliveryError(exc)}`);
         }
         finally {
-            this.runtime.delivery.setV2PullInflight(false);
-            client._gapFillDone.delete(dedupKey);
+            this.endRealtimeSync(ns);
+            this.schedulePendingPullIfNeeded(ns, 'push-auto-pull-complete');
         }
     }
+    enqueueOnlineUnreadP2pHint(data) {
+        const client = this.runtime.client;
+        if (!client._aid || !client._v2Session)
+            return;
+        const ns = `p2p:${client._aid}`;
+        client._safeAsync(this.runP2PForwardRecovery(ns, 50, true).catch((exc) => {
+            client._clientLog?.debug(`P2P online unread hint background Forward failed: ns=${ns} err=${formatDeliveryError(exc)}`);
+        }));
+    }
     async restoreSeqTrackerState() {
         const client = this.runtime.client;
         if (!client._aid)
@@ -1458,6 +2961,17 @@ export class MessageDeliveryEngine {
         const deviceId = client._deviceId;
         const slotId = client._slotId;
         try {
+            const loadSync = client._tokenStore.loadAllSyncStates?.bind(client._tokenStore);
+            if (typeof loadSync === 'function' && typeof client._seqTracker.restoreSyncState === 'function') {
+                let state = await loadSync(aid, deviceId, slotId);
+                if (client._seqTrackerContext !== context)
+                    return;
+                if (state && typeof state === 'object' && Object.keys(state).length > 0) {
+                    state = await this.migrateSeqStateGroupIds(state);
+                    client._seqTracker.restoreSyncState(state);
+                    return;
+                }
+            }
             const loadAll = client._tokenStore.loadAllSeqs?.bind(client._tokenStore);
             if (typeof loadAll === 'function') {
                 let state = await loadAll(aid, deviceId, slotId);
@@ -1494,71 +3008,7 @@ export class MessageDeliveryEngine {
         }
     }
     async migrateSeqStateGroupIds(state) {
-        const client = this.runtime.client;
-        if (!state || Object.keys(state).length === 0)
-            return state;
-        const renameMap = {};
-        for (const ns of Object.keys(state)) {
-            for (const prefix of ['group_event:', 'group_msg:']) {
-                if (ns.startsWith(prefix)) {
-                    const oldGid = ns.slice(prefix.length);
-                    const newGid = normalizeGroupId(oldGid);
-                    if (newGid && newGid !== oldGid) {
-                        renameMap[ns] = `${prefix}${newGid}`;
-                    }
-                    break;
-                }
-            }
-        }
-        if (Object.keys(renameMap).length === 0)
-            return state;
-        const newState = { ...state };
-        for (const [oldNs, newNs] of Object.entries(renameMap)) {
-            const oldVal = Number(newState[oldNs] ?? 0);
-            const curVal = Number(newState[newNs] ?? 0);
-            delete newState[oldNs];
-            newState[newNs] = Math.max(oldVal, curVal);
-        }
-        if (!client._aid)
-            return newState;
-        const aid = client._aid;
-        const deviceId = client._deviceId;
-        const slotId = client._slotId;
-        const saver = client._tokenStore.saveSeq?.bind(client._tokenStore);
-        const deleter = client._tokenStore.deleteSeq?.bind(client._tokenStore);
-        if (typeof saver === 'function') {
-            for (const [oldNs, newNs] of Object.entries(renameMap)) {
-                if (typeof deleter === 'function') {
-                    try {
-                        await deleter(aid, deviceId, slotId, oldNs);
-                    }
-                    catch (e) {
-                        client._dispatcher.publish('seq_tracker.persist_error', {
-                            phase: 'migrate_delete',
-                            aid,
-                            device_id: deviceId,
-                            slot_id: slotId,
-                            ns: oldNs,
-                            error: String(e),
-                        }).catch(() => { });
-                    }
-                }
-                try {
-                    await saver(aid, deviceId, slotId, newNs, newState[newNs]);
-                }
-                catch (e) {
-                    client._dispatcher.publish('seq_tracker.persist_error', {
-                        phase: 'migrate_save',
-                        aid,
-                        device_id: deviceId,
-                        slot_id: slotId,
-                        ns: newNs,
-                        error: String(e),
-                    }).catch(() => { });
-                }
-            }
-        }
-        return newState;
+        return state;
     }
     async saveSeqTrackerState() {
         const client = this.runtime.client;
@@ -1567,7 +3017,9 @@ export class MessageDeliveryEngine {
             await this.flushSeqTrackerPending();
             return;
         }
-        const state = client._seqTracker.exportState();
+        const state = typeof client._seqTracker.exportSyncState === 'function'
+            ? client._seqTracker.exportSyncState()
+            : Object.fromEntries(Object.entries(client._seqTracker.exportState()).map(([ns, seq]) => [ns, { ack: Number(seq), tail: Number(seq), head: Number(seq) }]));
         const pending = this.seqTrackerPending();
         if (pending.size > 0 && client._seqTrackerPendingPersistContext === context) {
             const liveNamespaces = new Set(Object.keys(state));
@@ -1595,9 +3047,34 @@ export class MessageDeliveryEngine {
         if (forceSeq !== undefined) {
             client._seqTracker.forceContiguousSeq(ns, seq);
         }
-        this.mergeSeqTrackerPending(context, { [ns]: seq });
+        const state = typeof client._seqTracker.getSyncState === 'function'
+            ? client._seqTracker.getSyncState(ns)
+            : { ack: seq, tail: seq, head: seq };
+        this.mergeSeqTrackerPending(context, { [ns]: state });
         this.scheduleSeqTrackerFlush();
     }
+    async commitSeqTrackerState(ns) {
+        const client = this.runtime.client;
+        const context = this.currentSeqTrackerContext();
+        if (!context || !ns)
+            return;
+        const current = client._seqTracker.getContiguousSeq(ns);
+        const state = typeof client._seqTracker.getSyncState === 'function'
+            ? client._seqTracker.getSyncState(ns)
+            : { ack: current, tail: current, head: current };
+        if (![state.ack, state.tail, state.head].some((value) => Number(value) > 0))
+            return;
+        const [aid, deviceId, slotId] = JSON.parse(context);
+        const pendingBeforeCommit = this.takeSeqTrackerPending(context, ns);
+        try {
+            await this.writeSeqTrackerState(aid, deviceId, slotId, { [ns]: state }, true);
+        }
+        catch (exc) {
+            this.restoreSeqTrackerPending(context, ns, pendingBeforeCommit);
+            throw exc;
+        }
+        client._clientLog.debug(`seq_tracker atomic commit: ns=${ns} A/T/H=${JSON.stringify(state)} context=${context}`);
+    }
     async flushSeqTrackerPending() {
         const client = this.runtime.client;
         this.cancelSeqTrackerFlushTimer();
@@ -1622,6 +3099,34 @@ export class MessageDeliveryEngine {
             this.cancelSeqTrackerFlushTimer();
         }
     }
+    takeSeqTrackerPending(context, ns) {
+        const client = this.runtime.client;
+        if (client._seqTrackerPendingPersistContext !== context)
+            return null;
+        const pending = this.seqTrackerPending();
+        const state = pending.get(ns);
+        if (!state)
+            return null;
+        pending.delete(ns);
+        if (pending.size === 0) {
+            client._seqTrackerPendingPersistContext = null;
+            this.cancelSeqTrackerFlushTimer();
+        }
+        return { ...state };
+    }
+    restoreSeqTrackerPending(context, ns, state) {
+        if (!state || this.currentSeqTrackerContext() !== context)
+            return;
+        const client = this.runtime.client;
+        const pendingContext = client._seqTrackerPendingPersistContext;
+        if (pendingContext && pendingContext !== context)
+            return;
+        const pending = this.seqTrackerPending();
+        if (!pending.has(ns))
+            pending.set(ns, state);
+        client._seqTrackerPendingPersistContext = context;
+        this.scheduleSeqTrackerFlush();
+    }
     currentSeqTrackerContext() {
         const client = this.runtime.client;
         if (!client._aid)
@@ -1643,10 +3148,12 @@ export class MessageDeliveryEngine {
             void this.flushSeqTrackerPending();
         }
         client._seqTrackerPendingPersistContext = context;
-        for (const [ns, seq] of Object.entries(state)) {
-            const seqNum = Number(seq);
-            if (ns && Number.isFinite(seqNum) && seqNum > 0) {
-                pending.set(ns, seqNum);
+        for (const [ns, raw] of Object.entries(state)) {
+            const ack = Number(raw.ack);
+            const tail = Number(raw.tail);
+            const head = Number(raw.head);
+            if (ns && [ack, tail, head].every(Number.isFinite) && Math.max(ack, tail, head) > 0) {
+                pending.set(ns, { ack, tail, head });
             }
         }
     }
@@ -1669,14 +3176,27 @@ export class MessageDeliveryEngine {
             client._seqTrackerFlushTimer = null;
         }
     }
-    async writeSeqTrackerState(aid, deviceId, slotId, state) {
+    async writeSeqTrackerState(aid, deviceId, slotId, state, throwOnError = false) {
+        await this.enqueueSeqTrackerWrite(() => this.writeSeqTrackerStateNow(aid, deviceId, slotId, state, throwOnError));
+    }
+    enqueueSeqTrackerWrite(operation) {
+        const run = this.seqTrackerWriteChain.then(operation, operation);
+        this.seqTrackerWriteChain = run.catch(() => { });
+        return run;
+    }
+    async writeSeqTrackerStateNow(aid, deviceId, slotId, state, throwOnError = false) {
         const client = this.runtime.client;
         if (!aid || Object.keys(state).length === 0)
             return;
         try {
+            const saveSync = client._tokenStore.saveSyncStates?.bind(client._tokenStore);
+            if (typeof saveSync === 'function') {
+                await saveSync(aid, deviceId, slotId, state);
+                return;
+            }
             const saveFn = client._tokenStore.saveSeq?.bind(client._tokenStore);
             if (typeof saveFn === 'function') {
-                await Promise.all(Object.entries(state).map(([ns, seq]) => saveFn(aid, deviceId, slotId, ns, seq)));
+                await Promise.all(Object.entries(state).map(([ns, triplet]) => saveFn(aid, deviceId, slotId, ns, triplet.ack)));
                 return;
             }
             if (typeof client._tokenStore.updateInstanceState === 'function') {
@@ -1690,69 +3210,99 @@ export class MessageDeliveryEngine {
             }
         }
         catch (exc) {
+            const error = formatDeliveryError(exc);
+            client._clientLog.warn(`save SeqTracker state failed: ${error}`);
             client._dispatcher.publish('seq_tracker.persist_error', {
                 phase: 'save',
                 aid,
                 device_id: deviceId,
                 slot_id: slotId,
-                error: String(exc),
+                error: String(error),
             }).catch(() => { });
+            if (throwOnError)
+                throw exc;
         }
     }
     persistRepairedSeq(ns) {
         const client = this.runtime.client;
         if (!client._aid || !ns)
             return;
+        const aid = client._aid;
+        const deviceId = client._deviceId;
+        const slotId = client._slotId;
         const seq = client._seqTracker.getContiguousSeq(ns);
         this.dropSeqTrackerPending(ns);
-        try {
-            if (seq > 0 && typeof client._tokenStore.saveSeq === 'function') {
-                client._tokenStore.saveSeq(client._aid, client._deviceId, client._slotId, ns, seq).catch((exc) => {
+        const saveSeq = client._tokenStore.saveSeq;
+        if (seq > 0 && typeof saveSeq === 'function') {
+            void this.enqueueSeqTrackerWrite(async () => {
+                try {
+                    await saveSeq.call(client._tokenStore, aid, deviceId, slotId, ns, seq);
+                }
+                catch (exc) {
                     client._clientLog.debug(`persist repaired seq failed: ns=${ns} err=${formatDeliveryError(exc)}`);
-                });
-                return;
-            }
-            const deleteSeq = client._tokenStore.deleteSeq;
-            if (seq <= 0 && typeof deleteSeq === 'function') {
-                deleteSeq.call(client._tokenStore, client._aid, client._deviceId, client._slotId, ns).catch((exc) => {
+                }
+            });
+            return;
+        }
+        const deleteSeq = client._tokenStore.deleteSeq;
+        if (seq <= 0 && typeof deleteSeq === 'function') {
+            void this.enqueueSeqTrackerWrite(async () => {
+                try {
+                    await deleteSeq.call(client._tokenStore, aid, deviceId, slotId, ns);
+                }
+                catch (exc) {
                     client._clientLog.debug(`delete repaired seq failed: ns=${ns} err=${formatDeliveryError(exc)}`);
-                });
-                return;
-            }
-            if (seq <= 0 && typeof client._tokenStore.updateInstanceState === 'function') {
-                Promise.resolve(client._tokenStore.updateInstanceState(client._aid, client._deviceId, client._slotId, (current) => {
-                    if (isJsonObject(current.seq_tracker_state)) {
-                        const next = { ...current.seq_tracker_state };
-                        delete next[ns];
-                        current.seq_tracker_state = next;
-                    }
-                    return current;
-                })).catch((exc) => {
+                }
+            });
+            return;
+        }
+        const updater = client._tokenStore.updateInstanceState;
+        if (seq <= 0 && typeof updater === 'function') {
+            void this.enqueueSeqTrackerWrite(async () => {
+                try {
+                    await updater.call(client._tokenStore, aid, deviceId, slotId, (current) => {
+                        if (isJsonObject(current.seq_tracker_state)) {
+                            const next = { ...current.seq_tracker_state };
+                            delete next[ns];
+                            current.seq_tracker_state = next;
+                        }
+                        return current;
+                    });
+                }
+                catch (exc) {
                     client._clientLog.debug(`delete repaired seq failed: ns=${ns} err=${formatDeliveryError(exc)}`);
-                });
-                return;
-            }
-            if (seq > 0) {
-                void this.saveSeqTrackerState();
-            }
+                }
+            });
+            return;
         }
-        catch (exc) {
-            client._clientLog.debug(`persist repaired seq failed: ns=${ns} err=${formatDeliveryError(exc)}`);
+        if (seq > 0) {
+            void this.saveSeqTrackerState();
         }
     }
     clampAckSeq(method, field, ns, seq) {
         const client = this.runtime.client;
         const original = seq;
-        let next = Number(seq);
-        if (!Number.isFinite(next))
+        let next = seq;
+        if (typeof next !== 'number' || !Number.isSafeInteger(next))
             return 0;
         if (next < 0)
             next = 0;
         if (ns) {
-            const maxSeen = client._seqTracker.getMaxSeenSeq(ns);
-            if (maxSeen > 0 && next > maxSeen) {
-                client._clientLog.warn(`ack clamp: method=${method} ${field}=${original} > max_seen=${maxSeen}, clamp`);
-                next = maxSeen;
+            const committedAck = client._seqTracker.getContiguousSeq(ns);
+            if (next > committedAck) {
+                client._clientLog.warn(`ack clamp: method=${method} ${field}=${original} > committed_ack=${committedAck}, clamp`);
+                next = committedAck;
+            }
+            if ((method === 'message.v2.ack' || method === 'message.ack')) {
+                const pending = this.pendingP2PInlineAcks?.get(ns);
+                if (pending && !pending.committed && next >= pending.seq)
+                    next = pending.seq - 1;
+            }
+            else if (method === 'group.v2.ack' || method === 'group.ack_messages') {
+                const canonicalNs = this.resolvePendingGroupInlineAckNamespace(ns);
+                const pending = this.pendingGroupInlineAcks?.get(canonicalNs);
+                if (pending && !pending.committed && next >= pending.seq)
+                    next = pending.seq - 1;
             }
         }
         return next;
@@ -1761,7 +3311,8 @@ export class MessageDeliveryEngine {
         const client = this.runtime.client;
         const clampField = (field, ns) => {
             const raw = params[field];
-            if (typeof raw !== 'number' || !Number.isFinite(raw))
+            // 保留非法类型/数值，让 V2 ACK 严格入口失败关闭，不能先 clamp 成合法游标。
+            if (typeof raw !== 'number' || !Number.isSafeInteger(raw))
                 return params;
             const next = this.clampAckSeq(method, field, ns, raw);
             return next === raw ? params : { ...params, [field]: next };
@@ -1775,7 +3326,7 @@ export class MessageDeliveryEngine {
             return clampField('seq', ns);
         }
         if (method === 'group.v2.ack' || method === 'group.ack_messages' || method === 'group.ack_events') {
-            const groupId = normalizeGroupId(String(params.group_id ?? '')) || String(params.group_id ?? '').trim();
+            const groupId = String(params.group_id ?? params.group_aid ?? '').trim();
             const ns = groupId ? `group:${groupId}` : '';
             if (method === 'group.v2.ack')
                 return clampField('up_to_seq', ns);
@@ -1786,7 +3337,7 @@ export class MessageDeliveryEngine {
         }
         return params;
     }
-    async drainOrderedMessages(ns, beforeSeq) {
+    async drainOrderedMessages(ns, beforeSeq, pullResponse = false, persist = true) {
         const client = this.runtime.client;
         const queue = client._pendingOrderedMsgs.get(ns);
         if (!queue || queue.size === 0)
@@ -1801,13 +3352,13 @@ export class MessageDeliveryEngine {
             queue.delete(seq);
             if (!item || client._pushedSeqs.get(ns)?.has(seq))
                 continue;
-            await this.publishOrderedQueueItem(ns, item.event, seq, item.payload);
+            await this.publishOrderedQueueItem(ns, item.event, seq, item.payload, pullResponse);
             this.markPublishedSeq(ns, seq);
             delivered = true;
         }
         if (queue.size === 0) {
             client._pendingOrderedMsgs.delete(ns);
-            if (delivered)
+            if (delivered && persist)
                 await this.saveSeqTrackerState();
         }
     }
@@ -1830,7 +3381,7 @@ export class MessageDeliveryEngine {
             this.enqueueOrderedMessage(ns, event, seqNum, payload);
             return false;
         }
-        await this.drainOrderedMessages(ns, seqNum);
+        await this.drainOrderedMessages(ns, seqNum, true);
         if (client._pushedSeqs.get(ns)?.has(seqNum))
             return false;
         const queue = client._pendingOrderedMsgs.get(ns);
@@ -1844,14 +3395,14 @@ export class MessageDeliveryEngine {
             await this.saveSeqTrackerState();
         return true;
     }
-    async publishPulledMessage(event, ns, seq, payload) {
+    async publishPulledMessage(event, ns, seq, payload, persist = true) {
         const client = this.runtime.client;
         const seqNum = Number(seq);
         if (!Number.isFinite(seqNum) || !Number.isInteger(seqNum) || seqNum <= 0 || !ns) {
             if (event === 'message.recalled') {
-                return this.publishMessageRecallTombstone(seq, payload);
+                return await client._withPullResponseProcessing(ns, () => this.publishMessageRecallTombstone(seq, payload));
             }
-            await client._publishAppEvent(event, payload);
+            await client._withPullResponseProcessing(ns, () => client._publishAppEvent(event, payload));
             return true;
         }
         const queue = client._pendingOrderedMsgs.get(ns);
@@ -1861,16 +3412,16 @@ export class MessageDeliveryEngine {
                 client._pendingOrderedMsgs.delete(ns);
             return false;
         }
-        await this.drainOrderedMessages(ns, seqNum);
+        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 this.publishMessageRecallTombstone(seqNum, payload);
+            const published = await client._withPullResponseProcessing(ns, () => this.publishMessageRecallTombstone(seqNum, payload));
             this.markPublishedSeq(ns, seqNum);
             return published;
         }
-        await client._publishAppEvent(event, payload);
+        await client._withPullResponseProcessing(ns, () => client._publishAppEvent(event, payload));
         this.markPublishedSeq(ns, seqNum);
         return true;
     }