@agentunion/fastaun 0.5.3 → 0.5.6

package/dist/client/delivery.js

@@ -1,16 +1,17 @@
 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;
 const GROUP_RECALL_SEEN_LIMIT = 10_000;
 const SEQ_TRACKER_PERSIST_FLUSH_DELAY_MS = 200;
+const MAX_INLINE_PENDING_ACK_NAMESPACES = 4096;
 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',
@@ -38,9 +39,57 @@ function formatDeliveryError(error) {
 }
 export class MessageDeliveryEngine {
     runtime;
+    realtimeTailHeads = null;
+    realtimeSyncing = null;
+    pendingP2PInlineAcks = null;
+    pendingGroupInlineAcks = null;
+    pendingGroupInlineAckNamespaces = null;
+    inlineAckGeneration = 0;
     constructor(runtime) {
         this.runtime = runtime;
     }
+    resetInlineAckState() {
+        this.inlineAckGeneration += 1;
+        this.pendingP2PInlineAcks = null;
+        this.pendingGroupInlineAcks = null;
+        this.pendingGroupInlineAckNamespaces = null;
+        this.realtimeSyncing = null;
+        this.realtimeTailHeads = null;
+    }
+    inlineGenerationIsCurrent(generation) {
+        return this.inlineAckGeneration === generation;
+    }
+    captureInlineAckGeneration() {
+        return this.inlineAckGeneration;
+    }
+    captureP2PInlineAckGeneration() {
+        return this.pendingP2PInlineAcks?.size ? this.inlineAckGeneration : null;
+    }
+    captureGroupInlineAckGeneration() {
+        return this.pendingGroupInlineAcks?.size ? this.inlineAckGeneration : null;
+    }
+    pendingInlineAckNamespaceCount() {
+        return (this.pendingP2PInlineAcks?.size ?? 0) + (this.pendingGroupInlineAcks?.size ?? 0);
+    }
+    markRealtimeTailCompleted(result, tailHead) {
+        const heads = this.realtimeTailHeads ?? new WeakMap();
+        this.realtimeTailHeads = heads;
+        heads.set(result, tailHead);
+    }
+    realtimeTailHead(result) {
+        return this.realtimeTailHeads?.get(result) ?? null;
+    }
+    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);
+    }
     prunePushedSeqs(ns) {
         const client = this.runtime.client;
         const pushed = client._pushedSeqs.get(ns);
@@ -108,8 +157,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);
             }
@@ -140,7 +189,10 @@ export class MessageDeliveryEngine {
         return result;
     }
     normalizePublishedMessagePayload(event, payload) {
+        payload = this.stripInlineInternalFields(payload);
         if (this.isInstanceScopedMessageEvent(event)) {
+            if (event === 'group.message_created')
+                payload = normalizeGroupMentionMode(payload);
             return this.attachAppMessageEnvelope(this.stripInternalSenderDeviceFields(this.attachCurrentInstanceContext(payload)));
         }
         if (this.isGroupScopedEvent(event)) {
@@ -148,6 +200,18 @@ export class MessageDeliveryEngine {
         }
         return payload;
     }
+    stripInlineInternalFields(payload) {
+        if (!isJsonObject(payload))
+            return payload;
+        const source = payload;
+        if (!Object.prototype.hasOwnProperty.call(source, 'inline_message')
+            && !Object.prototype.hasOwnProperty.call(source, '_inline_message_candidates_v1'))
+            return payload;
+        const result = { ...source };
+        delete result.inline_message;
+        delete result._inline_message_candidates_v1;
+        return result;
+    }
     envelopeMetadata(value) {
         let source = value;
         if (source && typeof source === 'object') {
@@ -205,6 +269,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) {
@@ -271,19 +336,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) {
@@ -473,8 +549,7 @@ export class MessageDeliveryEngine {
         // (group_id, sorted message_ids) 已能唯一标识一次撤回；缺 message_ids 时按原消息 id/seq 兜底。
         // 去重键不含 recalled_at：占位/通知 tombstone（pull，事务内时间）与在线 push（事务后重取时间）
         // 三条通道对同一次撤回可能携带不同来源的时间戳，纳入 recalled_at 会使去重失效、回调多次。
-        // group_id 归一化一次，使去重键与来源无关（pull 用 normalizeGroupId，push 可能是原始值）。
-        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(',')
@@ -503,9 +578,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) {
@@ -643,11 +716,11 @@ export class MessageDeliveryEngine {
         if (!isJsonObject(message)) {
             return { value_type: typeof message };
         }
-        const msg = message;
+        const msg = normalizeGroupMentionMode(message);
         const keys = [
             'message_id', 'id', 'from', 'from_aid', 'sender_aid', 'to', 'to_aid',
             'group_id', 'seq', 'msg_seq', 'type', 'version', 'timestamp', 't_server',
-            'device_id', 'slot_id', 'encrypted', 'dispatch_mode', 'dispatch',
+            'device_id', 'slot_id', 'encrypted', 'mention_mode', 'dispatch',
             'e2ee', 'headers', 'protected_headers', 'context', 'status',
             '_decrypt_error', '_decrypt_stage',
         ];
@@ -684,24 +757,72 @@ export class MessageDeliveryEngine {
             return true;
         const client = this.runtime.client;
         const msg = message;
-        if ('device_id' in msg) {
-            const targetDeviceId = String(msg.device_id ?? '').trim();
-            if (targetDeviceId !== client._deviceId) {
+        if (Object.prototype.hasOwnProperty.call(msg, 'target_device_id')) {
+            if (typeof msg.target_device_id !== 'string')
+                return false;
+            const targetDeviceId = msg.target_device_id.trim();
+            if (!targetDeviceId || targetDeviceId !== client._deviceId) {
                 return false;
             }
         }
-        if ('slot_id' in msg) {
-            const targetSlotId = String(msg.slot_id ?? '').trim();
-            if (slotIsolationKey(targetSlotId) !== slotIsolationKey(client._slotId)) {
+        else if (Object.prototype.hasOwnProperty.call(msg, 'device_id')) {
+            if (typeof msg.device_id !== 'string')
+                return false;
+            const deviceId = msg.device_id.trim();
+            if (deviceId !== client._deviceId)
+                return false;
+        }
+        if (Object.prototype.hasOwnProperty.call(msg, 'target_slot_id')) {
+            if (typeof msg.target_slot_id !== 'string')
+                return false;
+            const targetSlotId = msg.target_slot_id.trim();
+            if (!targetSlotId || slotIsolationKey(targetSlotId) !== slotIsolationKey(client._slotId)) {
                 return false;
             }
         }
+        else if (Object.prototype.hasOwnProperty.call(msg, 'slot_id')) {
+            if (typeof msg.slot_id !== 'string')
+                return false;
+            const slotId = msg.slot_id.trim();
+            if (slotIsolationKey(slotId) !== slotIsolationKey(client._slotId))
+                return false;
+        }
         return true;
     }
-    async runPushProcessSerialized(ns, operation) {
+    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.inlineGenerationIsCurrent(inlineGeneration))
+                return;
             await operation();
+            if (!this.inlineGenerationIsCurrent(inlineGeneration))
+                return;
+        };
+        if (!ns) {
+            await run();
             return;
         }
         let queues = client._pushProcessQueues;
@@ -710,7 +831,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 {
@@ -734,7 +855,10 @@ export class MessageDeliveryEngine {
         const ns = isJsonObject(data) && client._aid && data.seq !== undefined
             ? `p2p:${client._aid}`
             : '';
-        this.runPushProcessSerialized(ns, () => this.processAndPublishMessage(data)).catch((exc) => {
+        const inlineGeneration = isJsonObject(data)
+            && Object.prototype.hasOwnProperty.call(data, 'inline_message')
+            ? this.captureInlineAckGeneration() : undefined;
+        this.runPushProcessSerialized(ns, () => this.processAndPublishMessage(data, inlineGeneration), inlineGeneration).catch((exc) => {
             client._clientLog.warn(`P2P message decrypt failed: ${formatDeliveryError(exc)}`);
             if (isJsonObject(data)) {
                 const src = data;
@@ -770,7 +894,7 @@ export class MessageDeliveryEngine {
             const contigBefore = client._seqTracker.getContiguousSeq(ns);
             const published = await this.publishOrderedMessage('message.recalled', ns, seq, msg);
             const contigAfter = client._seqTracker.getContiguousSeq(ns);
-            if (Number(seq) > contigAfter && !published) {
+            if (Number(seq) > contigAfter && !published && client._sessionOptions?.background_sync !== false) {
                 this.fillP2pGap().catch((exc) => client._clientLog.warn(`background recall gap fill failed: ${formatDeliveryError(exc)}`));
             }
             const contig = client._seqTracker.getContiguousSeq(ns);
@@ -785,7 +909,7 @@ export class MessageDeliveryEngine {
         }
         await this.publishMessageRecallTombstone(seq, msg);
     }
-    async processAndPublishMessage(data) {
+    async processAndPublishMessage(data, inlineGeneration) {
         const client = this.runtime.client;
         if (!isJsonObject(data)) {
             await client._publishAppEvent('message.received', data, 'push');
@@ -796,6 +920,22 @@ export class MessageDeliveryEngine {
             client._clientLog.debug(`P2P push filtered by instance: message_id=${String(msg.message_id ?? '')}, seq=${String(msg.seq ?? '')}, target_device=${String(msg.device_id ?? '')}, target_slot=${String(msg.slot_id ?? '')}, local_device=${client._deviceId}, local_slot=${client._slotId}`);
             return;
         }
+        // 新 SDK 的所有带合法 seq P2P Push 都只作为 Head 通知处理。
+        // 新服务端为兼容旧 SDK 仍可能发送 message.received；V2 会话下必须
+        // 在旧 seq tracking / ordered publish 之前转入前台 Tail 协调器。
+        const inlinePresent = Object.prototype.hasOwnProperty.call(msg, 'inline_message');
+        const legacyPushSeq = this.realtimeHeadSeq(msg.seq, inlinePresent);
+        if (client._v2Session && client._aid && msg.seq !== undefined && msg.seq !== null) {
+            if (legacyPushSeq === null) {
+                if (inlinePresent)
+                    await this.recoverInvalidP2PRealtimeHead(`p2p:${client._aid}`, msg.seq);
+                return;
+            }
+            await this.onV2PushNotification({ ...msg, seq: legacyPushSeq }, 'v1', inlineGeneration);
+            if (inlineGeneration !== undefined && !this.inlineGenerationIsCurrent(inlineGeneration))
+                return;
+            return;
+        }
         const encryptedPush = client._isEncryptedPushMessage(msg);
         const seq = msg.seq;
         if (seq !== undefined && seq !== null && client._aid) {
@@ -808,7 +948,7 @@ export class MessageDeliveryEngine {
                 : await this.publishOrderedMessage('message.received', ns, seq, msg);
             const contigAfter = client._seqTracker.getContiguousSeq(ns);
             const needPull = Number(seq) > contigAfter && !published;
-            if (needPull) {
+            if (needPull && client._sessionOptions?.background_sync !== false) {
                 client._clientLog.debug(`P2P seq gap detected: ns=${ns}, seq=${seq}, contiguous=${contigAfter}`);
                 this.fillP2pGap().catch((exc) => client._clientLog.warn(`background gap fill trigger failed: ${formatDeliveryError(exc)}`));
             }
@@ -847,7 +987,10 @@ export class MessageDeliveryEngine {
         const groupNs = isJsonObject(data)
             ? String(data.group_id ?? '').trim()
             : '';
-        this.runPushProcessSerialized(groupNs ? `group:${groupNs}` : '', () => this.processAndPublishGroupMessage(data)).catch((exc) => {
+        const inlineGeneration = isJsonObject(data)
+            && Object.prototype.hasOwnProperty.call(data, 'inline_message')
+            ? this.captureInlineAckGeneration() : undefined;
+        this.runPushProcessSerialized(groupNs ? `group:${groupNs}` : '', () => this.processAndPublishGroupMessage(data, inlineGeneration), inlineGeneration).catch((exc) => {
             client._clientLog.warn(`group message decrypt failed: ${formatDeliveryError(exc)}`);
             if (isJsonObject(data)) {
                 const src = data;
@@ -865,7 +1008,7 @@ export class MessageDeliveryEngine {
         });
         client._clientLog.debug(`_onRawGroupMessageCreated exit: elapsed=${Date.now() - tStart}ms (handler dispatched)`);
     }
-    async processAndPublishGroupMessage(data) {
+    async processAndPublishGroupMessage(data, inlineGeneration) {
         const client = this.runtime.client;
         if (!isJsonObject(data)) {
             await client._publishAppEvent('group.message_created', data, 'group-push');
@@ -878,6 +1021,21 @@ export class MessageDeliveryEngine {
         if (groupId) {
             client._groupSynced.add(groupId);
         }
+        // V2 会话中旧 group.message_created 也只是 Head 通知；必须先 Tail，
+        // 不能让 payload 路径直接推进旧 ordered publish 状态。
+        const inlinePresent = Object.prototype.hasOwnProperty.call(msg, 'inline_message');
+        const legacyPushSeq = this.realtimeHeadSeq(seq, inlinePresent);
+        if (client._v2Session && groupId && seq !== undefined && seq !== null) {
+            if (legacyPushSeq === null) {
+                if (inlinePresent)
+                    await this.recoverInvalidGroupRealtimeHead(groupId, `group:${groupId}`, seq);
+                return;
+            }
+            await this.onRawGroupV2MessageCreated({ ...msg, seq: legacyPushSeq }, 'v1', inlineGeneration);
+            if (inlineGeneration !== undefined && !this.inlineGenerationIsCurrent(inlineGeneration))
+                return;
+            return;
+        }
         if (payload === undefined || payload === null
             || (typeof payload === 'object' && Object.keys(payload).length === 0)) {
             void this.autoPullGroupMessages(msg).catch((exc) => {
@@ -911,7 +1069,7 @@ export class MessageDeliveryEngine {
                 : await this.publishOrderedMessage('group.message_created', ns, seq, msg);
             const contigAfter = client._seqTracker.getContiguousSeq(ns);
             const needPull = Number(seq) > contigAfter && !published;
-            if (needPull) {
+            if (needPull && client._sessionOptions?.background_sync !== false) {
                 client._clientLog.debug(`group message seq gap detected: group=${groupId}, seq=${seq}, contiguous=${contigAfter}`);
                 this.fillGroupGap(groupId).catch((exc) => client._clientLog.warn(`background gap fill trigger failed: ${formatDeliveryError(exc)}`));
             }
@@ -944,22 +1102,32 @@ export class MessageDeliveryEngine {
             await client._publishAppEvent('group.message_created', notification);
             return;
         }
-        groupId = normalizeGroupId(groupId) || groupId;
+        if (client._sessionOptions?.background_sync === false) {
+            client._clientLog.debug(`auto pull group messages skipped: group=${groupId} background_sync=false`);
+            return;
+        }
+        groupId = String(groupId ?? '').trim();
         const ns = `group:${groupId}`;
         const afterSeq = client._seqTracker.getContiguousSeq(ns);
         client._clientLog.debug(`auto pull group messages start: group=${groupId}, after_seq=${afterSeq}, seq=${String(notification.seq ?? '')}`);
-        const started = await client._tryRunBackgroundPull(ns, async () => {
+        const operation = async () => {
             const pullAfterSeq = client._seqTracker.getContiguousSeq(ns);
             const messages = await client._pullGroupV2(groupId, pullAfterSeq, 50, { gateLocked: true });
             this.prunePushedSeqs(ns);
             return messages.length;
-        }, true);
-        if (!started) {
-            client._clientLog.debug(`auto pull group messages skipped: pull in-flight group=${groupId}`);
+        };
+        if (client._rpcPipeline) {
+            const key = client._rpcPipeline.pullGateKeyForCall('group.pull', { group_id: groupId, after_seq: afterSeq, limit: 50 });
+            await client._rpcPipeline.runPullSerialized(key, operation, true);
+        }
+        else {
+            await client._withBackgroundRpc(operation);
         }
     }
     async fillP2pGap() {
         const client = this.runtime.client;
+        if (client._sessionOptions?.background_sync === false)
+            return;
         if (!client._aid)
             return;
         const ns = `p2p:${client._aid}`;
@@ -967,16 +1135,14 @@ export class MessageDeliveryEngine {
         const dedupKey = `p2p:${afterSeq}`;
         if (client._gapFillDone.has(dedupKey))
             return;
-        const token = client._tryAcquirePullGate(ns);
-        if (token === null) {
-            client._clientLog.debug(`P2P message gap fill skipped: pull in-flight ns=${ns}`);
-            return;
-        }
         client._gapFillDone.set(dedupKey, Date.now());
         client._clientLog.debug(`P2P message gap fill start: after_seq=${afterSeq}`);
         let filled = 0;
         try {
-            const messages = await client._withBackgroundRpc(() => client._pullV2(afterSeq, 50, { skipAutoAck: true, gateLocked: true }));
+            const operation = () => client._pullV2(afterSeq, 50, { skipAutoAck: true, gateLocked: true });
+            const messages = client._rpcPipeline
+                ? await client._rpcPipeline.runPullSerialized(client._rpcPipeline.pullGateKeyForCall('message.pull', { after_seq: afterSeq, limit: 50 }), operation, true)
+                : await client._withBackgroundRpc(operation);
             filled = messages.length;
             this.prunePushedSeqs(ns);
             if (client._seqTracker.getContiguousSeq(ns) !== afterSeq) {
@@ -994,12 +1160,13 @@ export class MessageDeliveryEngine {
         }
         finally {
             client._gapFillDone.delete(dedupKey);
-            client._releasePullGate(ns, token);
         }
     }
     async fillGroupGap(groupId) {
         const client = this.runtime.client;
-        groupId = normalizeGroupId(groupId) || String(groupId ?? '').trim();
+        if (client._sessionOptions?.background_sync === false)
+            return;
+        groupId = String(groupId ?? '').trim();
         if (!groupId)
             return;
         const ns = `group:${groupId}`;
@@ -1007,16 +1174,14 @@ export class MessageDeliveryEngine {
         const dedupKey = `group_msg:${groupId}:${afterSeq}`;
         if (client._gapFillDone.has(dedupKey))
             return;
-        const token = client._tryAcquirePullGate(ns);
-        if (token === null) {
-            client._clientLog.debug(`group message gap fill skipped: pull in-flight group=${groupId}`);
-            return;
-        }
         client._gapFillDone.set(dedupKey, Date.now());
         client._clientLog.debug(`group message gap fill start: group=${groupId}, after_seq=${afterSeq}`);
         let filled = 0;
         try {
-            const messages = await client._withBackgroundRpc(() => client._pullGroupV2(groupId, afterSeq, 50, { gateLocked: true }));
+            const operation = () => client._pullGroupV2(groupId, afterSeq, 50, { gateLocked: true });
+            const messages = client._rpcPipeline
+                ? await client._rpcPipeline.runPullSerialized(client._rpcPipeline.pullGateKeyForCall('group.pull', { group_id: groupId, after_seq: afterSeq, limit: 50 }), operation, true)
+                : await client._withBackgroundRpc(operation);
             filled = messages.length;
             this.prunePushedSeqs(ns);
             if (client._seqTracker.getContiguousSeq(ns) !== afterSeq) {
@@ -1030,7 +1195,6 @@ export class MessageDeliveryEngine {
         }
         finally {
             client._gapFillDone.delete(dedupKey);
-            client._releasePullGate(ns, token);
             if (filled > 0 && client._seqTracker.getContiguousSeq(ns) > afterSeq) {
                 void this.fillGroupGap(groupId);
             }
@@ -1038,7 +1202,9 @@ export class MessageDeliveryEngine {
     }
     async fillGroupEventGap(groupId) {
         const client = this.runtime.client;
-        groupId = normalizeGroupId(groupId) || String(groupId ?? '').trim();
+        if (client._sessionOptions?.background_sync === false)
+            return;
+        groupId = String(groupId ?? '').trim();
         if (!groupId)
             return;
         const ns = `group_event:${groupId}`;
@@ -1082,12 +1248,16 @@ export class MessageDeliveryEngine {
                     ? result.cursor
                     : null;
                 const cursorCurrentSeq = Number(cursor?.current_seq ?? 0);
-                const retentionFloor = Math.max(client._pullRetentionFloor(result, 'retention_floor_event_seq', 'retention_floor_event_seq'), Number.isFinite(cursorCurrentSeq) ? cursorCurrentSeq : 0);
-                if (retentionFloor > 0) {
+                const retentionFloor = Math.max(client._pullRetentionFloor(result, 'retention_floor_event_seq', 'retention_floor_event_seq'));
+                const serverAckFloor = Number.isFinite(cursorCurrentSeq) ? Math.max(0, cursorCurrentSeq) : 0;
+                const earliestAvailable = Number(result.earliest_available_event_seq ?? 0);
+                const visibilityFloor = Math.max(0, Number.isFinite(Number(cursor?.join_seq)) ? Number(cursor?.join_seq) : 0, Number.isFinite(earliestAvailable) && earliestAvailable > 0 ? earliestAvailable - 1 : 0);
+                const effectiveFloor = Math.max(retentionFloor, serverAckFloor, visibilityFloor);
+                if (effectiveFloor > 0) {
                     const contigBeforeFloor = client._seqTracker.getContiguousSeq(ns);
-                    if (contigBeforeFloor < retentionFloor) {
-                        client._clientLog.info(`group.pull_events cursor/floor advance: ns=${ns} contiguous=${contigBeforeFloor} -> cursor.current_seq=${cursorCurrentSeq} floor=${retentionFloor}`);
-                        client._seqTracker.forceContiguousSeq(ns, retentionFloor);
+                    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 = [];
@@ -1155,7 +1325,7 @@ export class MessageDeliveryEngine {
     }
     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);
@@ -1164,6 +1334,17 @@ 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 gap fill: group=${groupId}, event_seq=${eventSeq}`);
+            this.fillGroupEventGap(groupId).catch((exc) => {
+                client._clientLog.warn(`background gap fill trigger failed: ${formatDeliveryError(exc)}`);
+            });
+            return;
+        }
         if (this.isSelfJoinGroupChanged(data)) {
             const contig = client._seqTracker.getContiguousSeq(ns);
             const maxSeen = client._seqTracker.getMaxSeenSeq(ns);
@@ -1185,17 +1366,16 @@ 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,
             }, undefined, undefined, true).catch((e) => {
                 client._clientLog.debug(`group event push auto-ack failed: group=${groupId} ${formatDeliveryError(e)}`);
             });
         }
-        if (needPull && groupId && !data._from_gap_fill) {
+        if (needPull && groupId && !data._from_gap_fill && client._sessionOptions?.background_sync !== false) {
             this.fillGroupEventGap(groupId).catch((exc) => {
                 client._clientLog.warn(`background gap fill trigger failed: ${formatDeliveryError(exc)}`);
             });
@@ -1203,7 +1383,7 @@ export class MessageDeliveryEngine {
     }
     fireGroupEventAck(groupId, eventSeq, reason) {
         const client = this.runtime.client;
-        const gid = normalizeGroupId(groupId) || String(groupId ?? '').trim();
+        const gid = String(groupId ?? '').trim();
         if (!gid)
             return;
         const ns = `group_event:${gid}`;
@@ -1226,21 +1406,25 @@ export class MessageDeliveryEngine {
             client._clientLog.debug(`group event ${reason} ack failed: group=${gid} ${formatDeliveryError(e)}`);
         }
     }
-    fireGroupV2Ack(groupId, upToSeq, reason) {
+    fireGroupV2Ack(groupId, upToSeq, reason, groupAid = '') {
         const client = this.runtime.client;
-        const gid = normalizeGroupId(groupId) || String(groupId ?? '').trim();
+        const gid = String(groupId ?? '').trim();
         if (!gid)
             return;
         const ns = `group:${gid}`;
         const ackSeq = this.clampAckSeq('group.v2.ack', 'up_to_seq', ns, Number(upToSeq) || 0);
         if (ackSeq <= 0)
             return;
+        const generation = this.inlineAckGeneration;
         try {
             Promise.resolve(client.call('group.v2.ack', {
                 group_id: gid,
+                ...(groupAid ? { group_aid: groupAid } : {}),
                 up_to_seq: ackSeq,
                 _rpc_background: true,
-            })).catch((e) => {
+            })).then((result) => {
+                this.onGroupV2AckResult(gid, result, ackSeq, generation);
+            }).catch((e) => {
                 client._clientLog.debug(`group.v2 ${reason} ack failed: group=${gid} ${formatDeliveryError(e)}`);
             });
         }
@@ -1261,84 +1445,948 @@ export class MessageDeliveryEngine {
         const actorAid = String(data.actor_aid ?? '').trim();
         return !joinedAid && ['joined', 'invite_code_used'].includes(action) && actorAid === selfAid;
     }
-    async onV2PushNotification(data) {
+    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;
+        }
+        const seq = this.inlineSafePositiveSeq(row.seq);
+        if (seq !== null)
+            result.seq = seq;
+        return result;
+    }
+    reservePendingGroupInlineAck(ns, seq, row, groupAid) {
+        if (!ns || !Number.isSafeInteger(seq) || seq <= 0 || this.pendingGroupInlineAcks?.has(ns)
+            || this.pendingInlineAckNamespaceCount() >= MAX_INLINE_PENDING_ACK_NAMESPACES)
+            return false;
+        const normalizedGroupAid = typeof groupAid === 'string' ? groupAid.trim() : '';
+        const aliasNs = normalizedGroupAid ? `group:${normalizedGroupAid}` : '';
+        const namespaces = aliasNs && aliasNs !== ns ? [ns, aliasNs] : [ns];
+        const pendingMap = this.pendingGroupInlineAcks ?? new Map();
+        const namespaceMap = this.pendingGroupInlineAckNamespaces ?? new Map();
+        this.pendingGroupInlineAcks = pendingMap;
+        this.pendingGroupInlineAckNamespaces = namespaceMap;
+        pendingMap.set(ns, {
+            seq,
+            row: this.inlinePostAckRow(row),
+            groupAid: normalizedGroupAid,
+            namespaces,
+            acking: false,
+            committed: false,
+            observedAckSeq: 0,
+        });
+        for (const namespace of namespaces) {
+            let candidates = namespaceMap.get(namespace);
+            if (!candidates) {
+                candidates = new Set();
+                namespaceMap.set(namespace, candidates);
+            }
+            candidates.add(ns);
+        }
+        return true;
+    }
+    removePendingGroupInlineAck(ns, pending) {
+        const pendingMap = this.pendingGroupInlineAcks;
+        if (pendingMap?.get(ns) !== pending)
+            return false;
+        pendingMap.delete(ns);
+        for (const namespace of pending.namespaces) {
+            const aliases = this.pendingGroupInlineAckNamespaces?.get(namespace);
+            if (!aliases)
+                continue;
+            aliases.delete(ns);
+            if (aliases.size === 0)
+                this.pendingGroupInlineAckNamespaces?.delete(namespace);
+        }
+        return true;
+    }
+    dropPendingGroupInlineAck(ns, seq) {
+        const pending = this.pendingGroupInlineAcks?.get(ns);
+        if (pending?.seq === seq)
+            this.removePendingGroupInlineAck(ns, pending);
+    }
+    resolvePendingGroupInlineAckNamespace(ns) {
+        const candidates = this.pendingGroupInlineAckNamespaces?.get(ns);
+        if (!candidates || candidates.size !== 1)
+            return ns;
+        const canonicalNs = candidates.values().next().value;
+        return typeof canonicalNs === 'string' && Boolean(this.pendingGroupInlineAcks?.has(canonicalNs))
+            ? canonicalNs
+            : ns;
+    }
+    completePendingGroupInlineAck(ns, upToSeq) {
+        if (!ns || !Number.isSafeInteger(upToSeq) || upToSeq <= 0)
+            return;
+        const candidates = this.pendingGroupInlineAckNamespaces?.get(ns);
+        if (!candidates || candidates.size !== 1)
+            return;
+        const canonicalNs = candidates.values().next().value;
+        if (typeof canonicalNs !== 'string')
+            return;
+        const pending = this.pendingGroupInlineAcks?.get(canonicalNs);
+        if (!pending || upToSeq < pending.seq)
+            return;
+        if (!pending.committed) {
+            pending.observedAckSeq = Math.max(pending.observedAckSeq, upToSeq);
+            return;
+        }
+        this.removePendingGroupInlineAck(canonicalNs, pending);
+        this.runPostInlineCommit(pending.row);
+    }
+    markPendingGroupInlineAckCommitted(ns, seq) {
+        const pending = this.pendingGroupInlineAcks?.get(ns);
+        if (!pending || pending.seq !== seq)
+            return false;
+        pending.committed = true;
+        if (pending.observedAckSeq < seq)
+            return true;
+        this.removePendingGroupInlineAck(ns, pending);
+        this.runPostInlineCommit(pending.row);
+        return true;
+    }
+    retryPendingGroupInlineAck(ns, seq, reason, ackThrough = seq) {
+        const pending = this.pendingGroupInlineAcks?.get(ns);
+        if (!pending || pending.seq !== seq)
+            return false;
+        if (pending.acking || !pending.committed)
+            return true;
+        const groupId = ns.startsWith('group:') ? ns.slice('group:'.length) : '';
+        if (!groupId)
+            return true;
+        pending.acking = true;
+        const requestedSeq = Math.max(seq, ackThrough);
+        const generation = this.inlineAckGeneration;
+        try {
+            Promise.resolve(this.runtime.client.call('group.v2.ack', {
+                group_id: groupId,
+                ...(pending.groupAid ? { group_aid: pending.groupAid } : {}),
+                up_to_seq: requestedSeq,
+                _rpc_background: true,
+            })).then((result) => {
+                this.onGroupV2AckResult(groupId, result, requestedSeq, generation);
+            }).catch((error) => {
+                const current = this.pendingGroupInlineAcks?.get(ns);
+                if (current === pending)
+                    current.acking = false;
+                this.runtime.client._clientLog.debug(`group.v2 ${reason} ack failed: group=${groupId} ${formatDeliveryError(error)}`);
+            }).finally(() => {
+                const current = this.pendingGroupInlineAcks?.get(ns);
+                if (current === pending)
+                    current.acking = false;
+            });
+        }
+        catch (error) {
+            pending.acking = false;
+            this.runtime.client._clientLog.debug(`group.v2 ${reason} ack failed: group=${groupId} ${formatDeliveryError(error)}`);
+        }
+        return true;
+    }
+    runPostInlineCommit(row) {
         const client = this.runtime.client;
-        if (!client._v2Session)
+        if (typeof client._postInlineV2CommitAndAck === 'function') {
+            client._postInlineV2CommitAndAck(row);
+        }
+    }
+    onGroupV2AckSucceeded(groupId, upToSeq, generation = this.inlineAckGeneration) {
+        if (!this.inlineGenerationIsCurrent(generation))
             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 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;
+        const gid = String(groupId ?? '').trim();
+        if (!gid || !Number.isSafeInteger(upToSeq) || upToSeq <= 0)
+            return;
+        this.completePendingGroupInlineAck(`group:${gid}`, upToSeq);
+    }
+    onGroupV2AckResult(groupId, result, requestedSeq, generation = this.inlineAckGeneration) {
+        if (!this.pendingGroupInlineAcks?.size || !this.inlineGenerationIsCurrent(generation))
+            return;
+        this.onGroupV2AckSucceeded(groupId, this.resolveActualAckSeq(result, requestedSeq), generation);
+    }
+    onGroupV2PullAckResult(groupId, result, requestedSeq, generation) {
+        if (!this.pendingGroupInlineAcks?.size || !this.inlineGenerationIsCurrent(generation)
+            || !Number.isSafeInteger(requestedSeq) || requestedSeq <= 0)
+            return;
+        let actualAckSeq = requestedSeq;
+        const response = isJsonObject(result) ? result : null;
+        const cursor = response && isJsonObject(response.cursor)
+            ? response.cursor
+            : null;
+        if (cursor && Object.prototype.hasOwnProperty.call(cursor, 'current_seq')) {
+            const raw = cursor.current_seq;
+            actualAckSeq = typeof raw === 'number' && Number.isSafeInteger(raw) && raw >= 0 ? raw : 0;
+        }
+        this.onGroupV2AckSucceeded(groupId, actualAckSeq, generation);
+    }
+    resolveActualAckSeq(result, requestedSeq) {
+        if (!Number.isSafeInteger(requestedSeq) || requestedSeq <= 0)
+            return 0;
+        const response = isJsonObject(result) ? result : null;
+        if (!response)
+            return requestedSeq;
+        let raw;
+        if (Object.prototype.hasOwnProperty.call(response, 'effective_ack_seq'))
+            raw = response.effective_ack_seq;
+        else if (Object.prototype.hasOwnProperty.call(response, 'ack_seq'))
+            raw = response.ack_seq;
+        else if (Object.prototype.hasOwnProperty.call(response, 'cursor')) {
+            const cursor = response.cursor;
+            const cursorObject = isJsonObject(cursor) ? cursor : null;
+            if (cursorObject) {
+                if (!Object.prototype.hasOwnProperty.call(cursorObject, 'current_seq'))
+                    return 0;
+                raw = cursorObject.current_seq;
+            }
+            else {
+                raw = cursor;
             }
-            contigBefore = client._repairPushContiguousBound(ns, pushSeq, hasPayload, '_raw.peer.v2.message_received');
         }
-        if (hasPayload && pushSeq > 0 && ns) {
-            try {
-                const decrypted = await client._decryptV2PushMessage(data);
-                if (decrypted) {
-                    const published = await client._publishOrderedMessage('message.received', ns, pushSeq, decrypted);
-                    const newContig = client._seqTracker.getContiguousSeq(ns);
-                    const needPull = pushSeq > newContig && !published;
-                    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.call('message.v2.ack', { up_to_seq: ackSeq, _rpc_background: true });
-                        }
-                        catch (e) {
-                            client._clientLog.debug(`V2 P2P push-ack failed: ${formatDeliveryError(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}`);
+        else
+            return requestedSeq;
+        return typeof raw === 'number' && Number.isSafeInteger(raw) && raw >= 0 ? raw : 0;
+    }
+    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)
+            : (pushSeq > before.ack ? ['tail'] : []);
+        let result = { messages: [], raw_count: 0 };
+        let tailHead = null;
+        const run = async (request, background) => {
+            const invoke = async () => {
+                const live = this.syncState(ns);
+                if (request.window_mode === 'tail' && !forceTail && typeof client._seqTracker.getSyncState === 'function' && pushSeq <= live.head)
+                    return { messages: [], raw_count: 0 };
+                if (request.window_mode !== 'tail' && live.ack >= live.tail - 1)
+                    return { messages: [], raw_count: 0 };
+                if (request.window_mode === 'tail') {
+                    const tailResult = await client._v2E2EE.pullV2TailInternal({
+                        window_mode: 'tail',
+                        after_seq: live.ack,
+                        limit: pageLimit,
+                    });
+                    tailHead = this.syncState(ns).head;
+                    return tailResult;
+                }
+                const after = live.ack;
+                const opts = { gateLocked: true };
+                if (request.max_pages !== undefined)
+                    opts.maxPages = request.max_pages;
+                const messages = await client._pullV2(after, pageLimit, opts);
+                return { messages, raw_count: messages.length };
+            };
+            if (!client._rpcPipeline)
+                return await invoke();
+            const key = client._rpcPipeline.pullGateKeyForCall('message.pull', request);
+            return await client._rpcPipeline.runPullSerialized(key, invoke, background);
+        };
+        if (order.length === 1 && order[0] === 'tail') {
+            result = await run({ window_mode: 'tail', after_seq: this.syncState(ns).ack, limit: pageLimit }, false);
+        }
+        const state = this.syncState(ns);
+        const needsForward = state.ack < state.tail - 1;
+        const backgroundEnabled = client._sessionOptions?.background_sync !== false;
+        if (backgroundEnabled && (order.length === 1 && order[0] === 'forward' || (order.length === 1 && order[0] === 'tail' && needsForward))) {
+            result = await run({ after_seq: state.ack, limit: pageLimit, ...(order[0] === 'tail' ? { max_pages: 1 } : {}) }, true);
+        }
+        if (tailHead !== null) {
+            this.markRealtimeTailCompleted(result, tailHead);
+        }
+        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)
+            : (pushSeq > before.ack ? ['tail'] : []);
+        let result = { messages: [], raw_count: 0 };
+        let tailHead = null;
+        const run = async (request, background) => {
+            const invoke = async () => {
+                const live = this.syncState(ns);
+                if (request.window_mode === 'tail' && !forceTail && typeof client._seqTracker.getSyncState === 'function' && pushSeq <= live.head)
+                    return { messages: [], raw_count: 0 };
+                if (request.window_mode !== 'tail' && live.ack >= live.tail - 1)
+                    return { messages: [], raw_count: 0 };
+                if (request.window_mode === 'tail') {
+                    const tailResult = await client._v2E2EE.pullGroupV2TailInternal({
+                        group_id: groupId,
+                        window_mode: 'tail',
+                        after_seq: live.ack,
+                        limit: pageLimit,
+                    });
+                    tailHead = this.syncState(ns).head;
+                    return tailResult;
                 }
+                const opts = { gateLocked: true };
+                if (request.max_pages !== undefined)
+                    opts.maxPages = request.max_pages;
+                const messages = await client._pullGroupV2(groupId, live.ack, pageLimit, opts);
+                return { messages, raw_count: messages.length };
+            };
+            if (!client._rpcPipeline)
+                return await invoke();
+            const key = client._rpcPipeline.pullGateKeyForCall('group.pull', { group_id: groupId, ...request });
+            return await client._rpcPipeline.runPullSerialized(key, invoke, background);
+        };
+        if (order.length === 1 && order[0] === 'tail') {
+            result = await run({ window_mode: 'tail', after_seq: this.syncState(ns).ack, limit: pageLimit }, false);
+        }
+        const state = this.syncState(ns);
+        const needsForward = state.ack < state.tail - 1;
+        const backgroundEnabled = client._sessionOptions?.background_sync !== false;
+        if (backgroundEnabled && (order.length === 1 && order[0] === 'forward' || (order.length === 1 && order[0] === 'tail' && needsForward))) {
+            result = await run({ after_seq: state.ack, limit: pageLimit, ...(order[0] === 'tail' ? { max_pages: 1 } : {}) }, true);
+        }
+        if (tailHead !== null) {
+            this.markRealtimeTailCompleted(result, tailHead);
+        }
+        return result;
+    }
+    async runP2PForwardRecovery(ns, pageLimit) {
+        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 };
+        };
+        if (!client._rpcPipeline)
+            return await invoke();
+        const key = client._rpcPipeline.pullGateKeyForCall('message.pull', request);
+        return await client._rpcPipeline.runPullSerialized(key, invoke, true);
+    }
+    async runGroupForwardRecovery(groupId, ns, pageLimit) {
+        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 };
+        };
+        if (!client._rpcPipeline)
+            return await invoke();
+        const key = client._rpcPipeline.pullGateKeyForCall('group.pull', request);
+        return await client._rpcPipeline.runPullSerialized(key, invoke, true);
+    }
+    syncState(ns) {
+        const tracker = this.runtime.client._seqTracker;
+        if (typeof tracker.getSyncState === 'function')
+            return tracker.getSyncState(ns);
+        const ack = Number(tracker.getContiguousSeq(ns) || 0);
+        const maxSeen = Number(tracker.getMaxSeenSeq?.(ns) || 0);
+        return { ack, tail: ack, head: Math.max(ack, maxSeen) };
+    }
+    inlineEnvelope(row) {
+        const raw = row.envelope_json;
+        if (typeof raw !== 'string' || !raw.trim())
+            return null;
+        try {
+            const parsed = JSON.parse(raw);
+            return isJsonObject(parsed) ? parsed : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    inlineRowKind(row) {
+        if (row.version === 'v1') {
+            if (Object.prototype.hasOwnProperty.call(row, 'envelope_json'))
+                return 'invalid';
+            return 'v1';
+        }
+        if (row.version === 'v2') {
+            if (typeof row.envelope_json !== 'string' || row.envelope_json.length === 0)
+                return 'invalid';
+            if (Object.prototype.hasOwnProperty.call(row, 'legacy_v1')
+                || Object.prototype.hasOwnProperty.call(row, 'payload'))
+                return 'invalid';
+            return 'v2';
+        }
+        return 'invalid';
+    }
+    inlineTargetBindingMatches(head, row, envelope) {
+        const client = this.runtime.client;
+        if (!this.messageTargetsCurrentInstance(head))
+            return false;
+        const targetValue = (source, targetKey, legacyKey) => {
+            if (Object.prototype.hasOwnProperty.call(source, targetKey)) {
+                return typeof source[targetKey] === 'string' ? source[targetKey].trim() : '';
             }
-            catch (exc) {
-                client._clientLog.debug(`_onV2PushNotification: push payload 解密失败, fallback to pull: ${formatDeliveryError(exc)}`);
+            if (Object.prototype.hasOwnProperty.call(source, legacyKey)) {
+                return typeof source[legacyKey] === 'string' ? source[legacyKey].trim() : '';
+            }
+            return null;
+        };
+        const headDevice = targetValue(head, 'target_device_id', 'device_id');
+        if (!headDevice || headDevice !== client._deviceId)
+            return false;
+        const rowDevice = targetValue(row, 'target_device_id', 'device_id');
+        if (rowDevice !== null && (!rowDevice || rowDevice !== headDevice))
+            return false;
+        const localSlot = slotIsolationKey(client._slotId);
+        const headSlot = targetValue(head, 'target_slot_id', 'slot_id');
+        if (headSlot !== null && slotIsolationKey(headSlot) !== localSlot)
+            return false;
+        const rowSlot = targetValue(row, 'target_slot_id', 'slot_id');
+        if (rowSlot !== null && (!rowSlot || slotIsolationKey(rowSlot) !== localSlot))
+            return false;
+        if (headSlot !== null && rowSlot !== null && slotIsolationKey(rowSlot) !== slotIsolationKey(headSlot))
+            return false;
+        if (!envelope)
+            return true;
+        if (Object.prototype.hasOwnProperty.call(envelope, 'recipients'))
+            return false;
+        if (!isJsonObject(envelope.recipient))
+            return false;
+        const recipient = envelope.recipient;
+        if (typeof recipient.aid !== 'string' || typeof recipient.device_id !== 'string'
+            || typeof client._aid !== 'string' || typeof client._deviceId !== 'string')
+            return false;
+        const recipientAid = recipient.aid;
+        const recipientDevice = recipient.device_id;
+        if (!recipientAid || recipientAid !== client._aid || !client._deviceId)
+            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 (recipientDevice)
+            return recipientDevice === client._deviceId;
+        return hasDeliveryDevice;
+    }
+    inlineRequiredBinding(left, leftKeys, right, rightKeys) {
+        const leftValue = this.consistentBindingValue(left, leftKeys);
+        const rightValue = this.consistentBindingValue(right, rightKeys);
+        return leftValue !== null && rightValue !== null && leftValue === rightValue;
+    }
+    consistentBindingValue(source, keys) {
+        let value = null;
+        for (const key of keys) {
+            if (!Object.prototype.hasOwnProperty.call(source, key))
+                continue;
+            if (typeof source[key] !== 'string')
+                return null;
+            const candidate = source[key].trim();
+            if (!candidate || (value !== null && candidate !== value))
+                return null;
+            value = candidate;
+        }
+        return value;
+    }
+    inlineHeadMatches(head, row, pushSeq, groupId = '') {
+        const rowSeq = this.inlineSafePositiveSeq(row.seq);
+        if (rowSeq === null || rowSeq !== pushSeq)
+            return false;
+        if (!this.inlineRequiredBinding(head, ['message_id'], row, ['message_id']))
+            return false;
+        if (groupId) {
+            const rowGroupId = typeof row.group_id === 'string' ? row.group_id.trim() : '';
+            if (!rowGroupId || rowGroupId !== groupId)
+                return false;
+            if (Object.prototype.hasOwnProperty.call(head, 'group_aid')
+                && (typeof head.group_aid !== 'string' || !head.group_aid.trim()))
+                return false;
+        }
+        if (!this.inlineRequiredBinding(head, ['from_aid', 'sender_aid', 'from'], row, ['from_aid', 'sender_aid', 'from'])
+            || !this.inlineRequiredBinding(head, ['sender_device_id'], row, ['sender_device_id']))
+            return false;
+        const kind = this.inlineRowKind(row);
+        if (kind === 'invalid')
+            return false;
+        const envelope = kind === 'v2' ? this.inlineEnvelope(row) : null;
+        if (kind === 'v2' && !envelope)
+            return false;
+        if (!this.inlineTargetBindingMatches(head, row, envelope))
+            return false;
+        const logicalTo = groupId ? null : this.consistentBindingValue(head, ['to_aid', 'to']);
+        if (!groupId && !logicalTo)
+            return false;
+        if (kind === 'v1') {
+            if (groupId) {
+                if (Object.prototype.hasOwnProperty.call(row, 'legacy_v1'))
+                    return false;
+            }
+            else {
+                if (Object.prototype.hasOwnProperty.call(row, 'payload'))
+                    return false;
+                const legacy = isJsonObject(row.legacy_v1)
+                    ? row.legacy_v1
+                    : null;
+                const legacyTo = legacy ? this.consistentBindingValue(legacy, ['to']) : null;
+                if (!legacyTo || legacyTo !== logicalTo)
+                    return false;
             }
         }
-        if (pushSeq > 0 && ns) {
-            client._clientLog.debug(`_onV2PushNotification: 纯通知 push_seq=${pushSeq} > contiguous_seq=${contigBefore}, 触发 pull(after_seq=${contigBefore})`);
+        if (envelope) {
+            const envelopeType = typeof envelope.type === 'string' ? envelope.type.trim() : '';
+            const envelopeVersion = typeof envelope.version === 'string' ? envelope.version.trim() : '';
+            const hasEnvelopeGroupId = Object.prototype.hasOwnProperty.call(envelope, 'group_id');
+            const envelopeGroupId = typeof envelope.group_id === 'string' ? envelope.group_id.trim() : '';
+            if (groupId) {
+                if (envelopeType !== 'e2ee.group_encrypted'
+                    || envelopeVersion !== 'v2'
+                    || (hasEnvelopeGroupId && envelopeGroupId !== groupId))
+                    return false;
+            }
+            else if (envelopeType !== 'e2ee.p2p_encrypted'
+                || envelopeVersion !== 'v2'
+                || (hasEnvelopeGroupId
+                    && (typeof envelope.group_id !== 'string' || envelopeGroupId !== '')))
+                return false;
+            if (!isJsonObject(envelope.aad))
+                return false;
+            const aad = envelope.aad;
+            if (!this.inlineRequiredBinding(aad, ['message_id'], row, ['message_id'])
+                || !this.inlineRequiredBinding(aad, ['from'], row, ['from_aid', 'sender_aid', 'from'])
+                || !this.inlineRequiredBinding(aad, ['from_device'], row, ['sender_device_id']))
+                return false;
+            const aadGroupId = this.consistentBindingValue(aad, ['group_id']);
+            if (groupId) {
+                if (aadGroupId !== groupId)
+                    return false;
+            }
+            else {
+                if ((Object.prototype.hasOwnProperty.call(aad, 'group_id') && aadGroupId !== '')
+                    || this.consistentBindingValue(aad, ['to']) !== logicalTo)
+                    return false;
+            }
         }
-        if (!ns)
+        return true;
+    }
+    inlineSafePositiveSeq(value) {
+        return typeof value === 'number' && Number.isSafeInteger(value) && value > 0 ? value : null;
+    }
+    realtimeHeadSeq(value, inlinePresent) {
+        const strict = this.inlineSafePositiveSeq(value);
+        if (strict !== null || inlinePresent || typeof value !== 'string' || !value.trim())
+            return strict;
+        return this.inlineSafePositiveSeq(Number(value));
+    }
+    async recoverInvalidP2PRealtimeHead(ns, rawSeq) {
+        const client = this.runtime.client;
+        client._clientLog.warn(`V2 P2P push has invalid seq; forcing authoritative Tail: seq=${String(rawSeq)}`);
+        if (!this.beginRealtimeSync(ns))
             return;
-        await client._tryRunBackgroundPull(ns, async () => {
-            const operationBefore = client._seqTracker.getContiguousSeq(ns);
-            const dedupKey = `p2p_pull:${ns}`;
-            if (client._gapFillDone.has(dedupKey)) {
-                client._recordPendingP2pPull(ns, pushSeq);
-                return 0;
+        try {
+            await this.runP2PRealtimeSync(ns, this.syncState(ns).head, 50, true);
+        }
+        catch (exc) {
+            client._clientLog.warn(`V2 P2P invalid-seq Tail failed: ${formatDeliveryError(exc)}`);
+        }
+        finally {
+            this.endRealtimeSync(ns);
+        }
+    }
+    async recoverInvalidGroupRealtimeHead(groupId, ns, rawSeq) {
+        const client = this.runtime.client;
+        client._clientLog.warn(`V2 group push 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);
+        }
+        catch (exc) {
+            client._clientLog.warn(`V2 group invalid-seq Tail failed: group=${groupId} ${formatDeliveryError(exc)}`);
+        }
+        finally {
+            this.endRealtimeSync(ns);
+        }
+    }
+    inlineStateIsCaughtUp(ns, pushSeq) {
+        const client = this.runtime.client;
+        const state = this.syncState(ns);
+        if (state.ack !== state.tail || state.tail !== state.head || pushSeq !== state.ack + 1)
+            return false;
+        if (Number(client._seqTracker.getMaxSeenSeq?.(ns) ?? state.head) > state.head)
+            return false;
+        const pending = client._pendingOrderedMsgs.get(ns);
+        return !pending || pending.size === 0;
+    }
+    async decodeInlineP2P(row) {
+        const client = this.runtime.client;
+        if (this.inlineRowKind(row) === 'v2') {
+            const decrypted = await client._decryptV2PushMessage(row);
+            return isJsonObject(decrypted) ? decrypted : null;
+        }
+        const legacy = isJsonObject(row.legacy_v1) ? row.legacy_v1 : null;
+        const payload = legacy?.payload;
+        if (!legacy || payload === undefined || payload === null)
+            return null;
+        const payloadType = isJsonObject(payload)
+            ? String(payload.type ?? '').trim()
+            : '';
+        if (payloadType === 'e2ee.encrypted' || payloadType === 'e2ee.group_encrypted')
+            return null;
+        const fromAid = String(row.from_aid ?? '').trim();
+        const seq = this.inlineSafePositiveSeq(row.seq);
+        if (seq === null)
+            return null;
+        const result = {
+            message_id: String(row.message_id ?? ''),
+            from: fromAid,
+            to: String(legacy.to ?? client._aid ?? ''),
+            seq,
+            type: String(row.type ?? ''),
+            timestamp: row.t_server,
+            payload: payload,
+            encrypted: false,
+            direction: String(row.direction ?? '').trim() || (fromAid && fromAid === client._aid ? 'outbound_sync' : 'inbound'),
+        };
+        if (row.sender_device_id !== undefined)
+            result.sender_device_id = row.sender_device_id;
+        return result;
+    }
+    async decodeInlineGroup(row, groupId, groupAid) {
+        const client = this.runtime.client;
+        if (this.inlineRowKind(row) === 'v2') {
+            const decrypted = await client._decryptV2PushMessage(row);
+            if (!isJsonObject(decrypted))
+                return null;
+            const decoded = decrypted;
+            if (Object.prototype.hasOwnProperty.call(decoded, 'group_id')) {
+                const decryptedGroupId = decoded.group_id;
+                if (typeof decryptedGroupId !== 'string' || !decryptedGroupId.trim() || decryptedGroupId.trim() !== groupId)
+                    return null;
+            }
+            return normalizeGroupMentionMode({
+                ...decoded,
+                group_id: groupId,
+                group_aid: groupAid || groupId,
+            }, row, row.envelope_json);
+        }
+        if (this.recallEventFromGroupMessage(row))
+            return null;
+        const payload = row.payload;
+        if (payload === undefined || payload === null)
+            return null;
+        const payloadType = isJsonObject(payload)
+            ? String(payload.type ?? '').trim()
+            : '';
+        if (payloadType === 'e2ee.encrypted' || payloadType === 'e2ee.group_encrypted')
+            return null;
+        const seq = this.inlineSafePositiveSeq(row.seq);
+        if (seq === null)
+            return null;
+        const result = {
+            message_id: String(row.message_id ?? ''),
+            from: String(row.from_aid ?? ''),
+            group_id: groupId,
+            group_aid: groupAid || groupId,
+            seq,
+            type: String(row.type ?? ''),
+            timestamp: row.t_server,
+            payload: payload,
+            encrypted: false,
+        };
+        if (row.sender_device_id !== undefined)
+            result.sender_device_id = row.sender_device_id;
+        return normalizeGroupMentionMode(result, row, row.envelope_json);
+    }
+    decodedInlineMatches(head, decoded, pushSeq, groupId = '') {
+        if (this.inlineSafePositiveSeq(decoded.seq) !== pushSeq)
+            return false;
+        if (!this.inlineRequiredBinding(head, ['message_id'], decoded, ['message_id']))
+            return false;
+        const headSender = this.consistentBindingValue(head, ['from_aid', 'sender_aid', 'from']);
+        const decodedSender = this.consistentBindingValue(decoded, ['from', 'from_aid', 'sender_aid']);
+        if (!headSender || decodedSender !== headSender)
+            return false;
+        if (groupId)
+            return this.consistentBindingValue(decoded, ['group_id']) === groupId;
+        const headTo = this.consistentBindingValue(head, ['to_aid', 'to']);
+        const decodedTo = this.consistentBindingValue(decoded, ['to', 'to_aid']);
+        return Boolean(headTo) && decodedTo === headTo;
+    }
+    async publishInlineMessage(event, ns, seq, payload, generation) {
+        if (!this.inlineGenerationIsCurrent(generation))
+            return false;
+        const client = this.runtime.client;
+        const tracker = client._seqTracker;
+        const snapshot = typeof tracker.snapshotNamespace === 'function' ? tracker.snapshotNamespace(ns) : null;
+        let delivered = false;
+        try {
+            const published = client._publishAppEvent(event, payload, 'inline-push');
+            if (isPromiseLike(published))
+                await published;
+            if (!this.inlineGenerationIsCurrent(generation))
+                return false;
+            delivered = true;
+            if (!this.inlineGenerationIsCurrent(generation))
+                return false;
+            const needsPull = Boolean(tracker.onMessageSeq(ns, seq));
+            if (!this.inlineGenerationIsCurrent(generation))
+                return false;
+            tracker.commitTailWindow(ns, {
+                windowStartSeq: seq,
+                headSeq: seq,
+                coveredThroughSeq: seq,
+                pageLimit: 1,
+            });
+            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.inlineGenerationIsCurrent(generation))
+                return false;
+            client._commitSeqTrackerState(ns);
+            if (!this.inlineGenerationIsCurrent(generation))
+                return false;
+            this.markPublishedSeq(ns, seq);
+            return true;
+        }
+        catch (exc) {
+            if (this.inlineGenerationIsCurrent(generation)
+                && typeof tracker.restoreNamespaceSnapshot === 'function')
+                tracker.restoreNamespaceSnapshot(ns, snapshot);
+            if (this.inlineGenerationIsCurrent(generation) && delivered)
+                this.markPublishedSeq(ns, seq);
+            client._clientLog.debug(`inline realtime consume rolled back: ns=${ns} seq=${seq} err=${formatDeliveryError(exc)}`);
+            return false;
+        }
+    }
+    async tryConsumeInlineP2P(head, ns, pushSeq, expectedVersion, inlineGeneration) {
+        const client = this.runtime.client;
+        if (!isJsonObject(head.inline_message))
+            return false;
+        const row = { ...head.inline_message };
+        if (expectedVersion !== undefined && this.inlineRowKind(row) !== expectedVersion)
+            return false;
+        const runner = client._tryRunInlineRealtime;
+        if (typeof runner !== 'function')
+            return false;
+        const generation = inlineGeneration ?? this.inlineAckGeneration;
+        if (!this.inlineGenerationIsCurrent(generation))
+            return false;
+        const result = await runner.call(client, ns, pushSeq, async () => {
+            if (!this.inlineGenerationIsCurrent(generation) || !this.inlineStateIsCaughtUp(ns, pushSeq) || !this.inlineHeadMatches(head, row, pushSeq)
+                || !this.reservePendingP2PInlineAck(ns, pushSeq, row))
+                return false;
+            let committed = false;
+            try {
+                const decoded = await this.decodeInlineP2P(row);
+                if (!this.inlineGenerationIsCurrent(generation) || !decoded || !this.inlineStateIsCaughtUp(ns, pushSeq)
+                    || !this.decodedInlineMatches(head, decoded, pushSeq))
+                    return false;
+                const appEvent = this.p2pAppEventForMessage(decoded);
+                const published = await this.publishInlineMessage(appEvent.event, ns, pushSeq, appEvent.payload, generation);
+                if (!this.inlineGenerationIsCurrent(generation) || !published)
+                    return false;
+                committed = this.markPendingP2PInlineAckCommitted(ns, pushSeq);
+                return committed;
+            }
+            finally {
+                if (!committed && this.inlineGenerationIsCurrent(generation))
+                    this.dropPendingP2PInlineAck(ns, pushSeq);
             }
-            client._gapFillDone.set(dedupKey, Date.now());
+        });
+        return this.inlineGenerationIsCurrent(generation) && result?.acquired === true && result.value === true;
+    }
+    async tryConsumeInlineGroup(head, groupId, ns, pushSeq, expectedVersion, inlineGeneration) {
+        const client = this.runtime.client;
+        if (!isJsonObject(head.inline_message))
+            return false;
+        const row = { ...head.inline_message };
+        if (expectedVersion !== undefined && this.inlineRowKind(row) !== expectedVersion)
+            return false;
+        const runner = client._tryRunInlineRealtime;
+        if (typeof runner !== 'function')
+            return false;
+        const groupAid = typeof head.group_aid === 'string' ? head.group_aid.trim() : '';
+        const generation = inlineGeneration ?? this.inlineAckGeneration;
+        if (!this.inlineGenerationIsCurrent(generation))
+            return false;
+        const result = await runner.call(client, ns, pushSeq, async () => {
+            if (!this.inlineGenerationIsCurrent(generation) || !this.inlineStateIsCaughtUp(ns, pushSeq) || !this.inlineHeadMatches(head, row, pushSeq, groupId)
+                || !this.reservePendingGroupInlineAck(ns, pushSeq, row, groupAid))
+                return false;
+            let committed = false;
             try {
-                const pulled = await client._pullV2(0, 50, { gateLocked: true });
-                const newContig = client._seqTracker.getContiguousSeq(ns);
-                client._clientLog.debug(`_onV2PushNotification pull done: contiguous_seq=${contigBefore}->${newContig} (push_seq=${pushSeq || 'null'})`);
-                if (newContig <= operationBefore)
-                    return 0;
-                return pulled.length;
+                const decoded = await this.decodeInlineGroup(row, groupId, groupAid || groupId);
+                if (!this.inlineGenerationIsCurrent(generation) || !decoded || !this.inlineStateIsCaughtUp(ns, pushSeq)
+                    || !this.decodedInlineMatches(head, decoded, pushSeq, groupId))
+                    return false;
+                const published = await this.publishInlineMessage('group.message_created', ns, pushSeq, decoded, generation);
+                if (!this.inlineGenerationIsCurrent(generation) || !published)
+                    return false;
+                committed = this.markPendingGroupInlineAckCommitted(ns, pushSeq);
+                return committed;
             }
             finally {
-                client._gapFillDone.delete(dedupKey);
+                if (!committed && this.inlineGenerationIsCurrent(generation))
+                    this.dropPendingGroupInlineAck(ns, pushSeq);
             }
-        }, true, () => client._recordPendingP2pPull(ns, pushSeq)).catch((exc) => {
-            const newContig = client._seqTracker.getContiguousSeq(ns);
-            client._clientLog.warn(`V2 push auto-pull failed: contiguous_seq=${contigBefore}->${newContig} err=${formatDeliveryError(exc)}`);
         });
+        return this.inlineGenerationIsCurrent(generation) && result?.acquired === true && result.value === true;
+    }
+    reservePendingP2PInlineAck(ns, seq, row) {
+        if (!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),
+            acking: false,
+            committed: false,
+            observedAckSeq: 0,
+        });
+        return true;
+    }
+    dropPendingP2PInlineAck(ns, seq) {
+        const pending = this.pendingP2PInlineAcks?.get(ns);
+        if (pending?.seq === seq)
+            this.pendingP2PInlineAcks?.delete(ns);
+    }
+    completePendingP2PInlineAck(ns, seq) {
+        if (!ns || !Number.isSafeInteger(seq) || seq <= 0)
+            return;
+        const pending = this.pendingP2PInlineAcks?.get(ns);
+        if (!pending || seq < pending.seq)
+            return;
+        if (!pending.committed) {
+            pending.observedAckSeq = Math.max(pending.observedAckSeq, seq);
+            return;
+        }
+        this.pendingP2PInlineAcks?.delete(ns);
+        this.runPostInlineCommit(pending.row);
+    }
+    markPendingP2PInlineAckCommitted(ns, seq) {
+        const pending = this.pendingP2PInlineAcks?.get(ns);
+        if (!pending || pending.seq !== seq)
+            return false;
+        pending.committed = true;
+        if (pending.observedAckSeq < seq)
+            return true;
+        this.pendingP2PInlineAcks?.delete(ns);
+        this.runPostInlineCommit(pending.row);
+        return true;
+    }
+    retryPendingP2PInlineAck(ns, seq, reason, ackThrough = seq) {
+        const pending = this.pendingP2PInlineAcks?.get(ns);
+        if (!pending || pending.seq !== seq)
+            return false;
+        if (pending.acking || !pending.committed)
+            return true;
+        pending.acking = true;
+        const requestedSeq = Math.max(seq, ackThrough);
+        const generation = this.inlineAckGeneration;
+        this.runtime.client._withBackgroundRpc(() => this.runtime.client._ackV2(requestedSeq))
+            .then((result) => {
+            this.onP2PV2AckResult(result, requestedSeq, generation);
+        }).catch((error) => {
+            const current = this.pendingP2PInlineAcks?.get(ns);
+            if (current === pending)
+                current.acking = false;
+            this.runtime.client._clientLog.debug(`message.v2 ${reason} ack failed: ${formatDeliveryError(error)}`);
+        }).finally(() => {
+            const current = this.pendingP2PInlineAcks?.get(ns);
+            if (current === pending)
+                current.acking = false;
+        });
+        return true;
+    }
+    onP2PV2AckSucceeded(upToSeq, generation = this.inlineAckGeneration) {
+        if (!this.inlineGenerationIsCurrent(generation))
+            return;
+        const ns = this.runtime.client._aid ? `p2p:${this.runtime.client._aid}` : '';
+        if (!ns || !Number.isSafeInteger(upToSeq) || upToSeq <= 0)
+            return;
+        this.completePendingP2PInlineAck(ns, upToSeq);
+    }
+    onP2PV2AckResult(result, requestedSeq, generation = this.inlineAckGeneration) {
+        if (!this.pendingP2PInlineAcks?.size || !this.inlineGenerationIsCurrent(generation))
+            return;
+        this.onP2PV2AckSucceeded(this.resolveActualAckSeq(result, requestedSeq), generation);
+    }
+    onP2PV2PullAckResult(result, requestedSeq, generation) {
+        if (!this.pendingP2PInlineAcks?.size || !this.inlineGenerationIsCurrent(generation)
+            || !Number.isSafeInteger(requestedSeq) || requestedSeq <= 0)
+            return;
+        let actualAckSeq = requestedSeq;
+        const response = isJsonObject(result) ? result : null;
+        if (response && Object.prototype.hasOwnProperty.call(response, 'server_ack_seq')) {
+            const raw = response.server_ack_seq;
+            actualAckSeq = typeof raw === 'number' && Number.isSafeInteger(raw) && raw >= 0 ? raw : 0;
+        }
+        this.onP2PV2AckSucceeded(actualAckSeq, generation);
+    }
+    async onV2PushNotification(data, expectedVersion, inlineGeneration) {
+        const client = this.runtime.client;
+        if (inlineGeneration !== undefined && !this.inlineGenerationIsCurrent(inlineGeneration))
+            return;
+        if (!client._v2Session)
+            return;
+        const pushData = isJsonObject(data) ? data : null;
+        const rawPushSeq = pushData?.seq;
+        const ns = client._aid ? `p2p:${client._aid}` : '';
+        if (!pushData || !ns)
+            return;
+        const inlinePresent = Object.prototype.hasOwnProperty.call(pushData, 'inline_message');
+        const pushSeq = this.realtimeHeadSeq(rawPushSeq, inlinePresent);
+        if (pushSeq === null) {
+            if (inlinePresent && rawPushSeq !== undefined && rawPushSeq !== null) {
+                await this.recoverInvalidP2PRealtimeHead(ns, rawPushSeq);
+            }
+            return;
+        }
+        let inlineConsumed = false;
+        const pendingInlineAck = this.pendingP2PInlineAcks?.get(ns);
+        const inlineBlockedByPendingAck = Boolean(pendingInlineAck && pendingInlineAck.seq !== pushSeq);
+        if (inlinePresent && !inlineBlockedByPendingAck && isJsonObject(pushData.inline_message))
+            try {
+                inlineConsumed = await this.tryConsumeInlineP2P(pushData, ns, pushSeq, expectedVersion, inlineGeneration);
+                if (inlineGeneration !== undefined && !this.inlineGenerationIsCurrent(inlineGeneration))
+                    return;
+                if (inlineConsumed) {
+                    client._clientLog.debug(`V2 P2P inline push consumed: seq=${pushSeq}`);
+                    this.retryPendingP2PInlineAck(ns, pushSeq, 'inline push');
+                    return;
+                }
+            }
+            catch (exc) {
+                if (inlineGeneration !== undefined && !this.inlineGenerationIsCurrent(inlineGeneration))
+                    return;
+                client._clientLog.warn(`V2 P2P inline push rejected, falling back to Tail: seq=${pushSeq} err=${formatDeliveryError(exc)}`);
+            }
+        const before = this.syncState(ns);
+        client._seqTracker.updateMaxSeen(ns, pushSeq);
+        const hasGap = before.ack < before.tail - 1;
+        if (pushSeq <= before.head && !hasGap && !inlinePresent) {
+            client._clientLog.debug(`V2 P2P duplicate push ignored: seq=${pushSeq} A/T/H=${JSON.stringify(before)}`);
+            this.retryPendingP2PInlineAck(ns, pushSeq, 'covered inline push');
+            return;
+        }
+        if (!this.beginRealtimeSync(ns)) {
+            client._clientLog.debug(`V2 P2P push coalesced into in-flight realtime sync: ns=${ns} seq=${pushSeq}`);
+            return;
+        }
+        try {
+            const syncResult = await this.runP2PRealtimeSync(ns, pushSeq, 50, inlinePresent && !inlineConsumed);
+            if (inlineGeneration !== undefined && !this.inlineGenerationIsCurrent(inlineGeneration))
+                return;
+            const tailHead = this.realtimeTailHead(syncResult);
+            const maxSeen = Number(client._seqTracker.getMaxSeenSeq?.(ns) ?? 0);
+            if (client._sessionOptions?.background_sync !== false
+                && tailHead !== null && Number.isSafeInteger(maxSeen) && maxSeen > tailHead) {
+                await this.runP2PForwardRecovery(ns, 50).catch((exc) => {
+                    client._clientLog.warn(`V2 P2P stale Tail Forward recovery failed: ${formatDeliveryError(exc)}`);
+                });
+                if (inlineGeneration !== undefined && !this.inlineGenerationIsCurrent(inlineGeneration))
+                    return;
+            }
+        }
+        catch (exc) {
+            client._clientLog.warn(`V2 P2P push auto-sync failed: ${formatDeliveryError(exc)}`);
+        }
+        finally {
+            if (inlineGeneration === undefined || this.inlineGenerationIsCurrent(inlineGeneration)) {
+                this.endRealtimeSync(ns);
+            }
+        }
     }
     enqueueOnlineUnreadHint(data) {
         const client = this.runtime.client;
@@ -1359,12 +2407,11 @@ export class MessageDeliveryEngine {
         if (client._onlineUnreadHintDrainActive)
             return;
         this.runtime.delivery.setOnlineUnreadHintDrainActive(true);
+        const attemptedAckByGroup = new Map();
         try {
             while (client._onlineUnreadHintQueue.size > 0) {
                 if (client.state !== ConnectionState.READY)
                     return;
-                if (client._sessionOptions?.background_sync === false)
-                    return;
                 const groupId = client._onlineUnreadHintQueue.keys().next().value;
                 if (!groupId)
                     return;
@@ -1372,6 +2419,11 @@ export class MessageDeliveryEngine {
                 client._onlineUnreadHintQueue.delete(groupId);
                 if (!payload)
                     continue;
+                const currentAck = this.syncState(`group:${groupId}`).ack;
+                const attemptedAck = attemptedAckByGroup.get(groupId);
+                if (attemptedAck !== undefined && currentAck <= attemptedAck)
+                    continue;
+                attemptedAckByGroup.set(groupId, currentAck);
                 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) {
@@ -1386,62 +2438,110 @@ export class MessageDeliveryEngine {
             this.runtime.delivery.setOnlineUnreadHintDrainActive(false);
         }
     }
-    async onRawGroupV2MessageCreated(data) {
+    async onRawGroupV2MessageCreated(data, expectedVersion, inlineGeneration) {
         const client = this.runtime.client;
+        if (inlineGeneration !== undefined && !this.inlineGenerationIsCurrent(inlineGeneration))
+            return;
         if (!isJsonObject(data) || !client._v2Session) {
             client._clientLog.debug(`_onRawGroupV2MessageCreated skipped: is_object=${String(isJsonObject(data))}, has_v2_session=${String(!!client._v2Session)}`);
             return;
         }
         const d = data;
         client._logMessageDebug('server-push', '_raw.group.v2.message_created', 'group.message_created', d);
-        const rawGroupId = String(d.group_id ?? '').trim();
-        const groupId = normalizeGroupId(rawGroupId) || rawGroupId;
-        const seq = Number(d.seq ?? 0);
-        if (!groupId || !Number.isFinite(seq) || seq <= 0) {
+        const groupId = typeof d.group_id === 'string' ? d.group_id.trim() : '';
+        const rawSeq = d.seq;
+        const inlinePresent = Object.prototype.hasOwnProperty.call(d, 'inline_message');
+        const seq = this.realtimeHeadSeq(rawSeq, inlinePresent);
+        if (!groupId) {
             client._clientLog.debug(`_onRawGroupV2MessageCreated skipped: group=${groupId || '<empty>'}, seq=${String(d.seq ?? '')}`);
             return;
         }
+        if (seq === null) {
+            if (inlinePresent && rawSeq !== undefined && rawSeq !== null) {
+                await this.recoverInvalidGroupRealtimeHead(groupId, `group:${groupId}`, rawSeq);
+            }
+            return;
+        }
         const eventKind = String(d.kind ?? '').trim();
-        if (eventKind === 'group.online_unread_hint' && !d._online_hint_drained) {
-            if (client._sessionOptions?.background_sync === false) {
-                client._clientLog.debug(`_onRawGroupV2MessageCreated skipped online unread hint: group=${groupId} background_sync=false`);
+        if (eventKind === 'group.online_unread_hint') {
+            if (!d._online_hint_drained) {
+                if (client._sessionOptions.background_sync === false)
+                    return;
+                this.enqueueOnlineUnreadHint(d);
                 return;
             }
-            this.enqueueOnlineUnreadHint(d);
+            // Hint 不是真实消息 Head：不消费 inline、不推进水位、也不直接 ACK。
+            // 只在后台同步开启时，从已提交 Ack 强制做一次普通 Forward，绝不进入 Tail planner。
+            if (client._sessionOptions.background_sync === false)
+                return;
+            try {
+                await this.runGroupForwardRecovery(groupId, `group:${groupId}`, 50);
+            }
+            catch (exc) {
+                client._clientLog.warn(`group online unread hint recovery pull failed: group=${groupId} err=${formatDeliveryError(exc)}`);
+            }
             return;
         }
         const ns = `group:${groupId}`;
+        let inlineConsumed = false;
+        const pendingInlineAck = this.pendingGroupInlineAcks?.get(ns);
+        const inlineBlockedByPendingAck = Boolean(pendingInlineAck && pendingInlineAck.seq !== seq);
+        if (inlinePresent && !inlineBlockedByPendingAck && isJsonObject(d.inline_message)) {
+            try {
+                inlineConsumed = await this.tryConsumeInlineGroup(d, groupId, ns, seq, expectedVersion, inlineGeneration);
+                if (inlineGeneration !== undefined && !this.inlineGenerationIsCurrent(inlineGeneration))
+                    return;
+                if (inlineConsumed) {
+                    client._clientLog.debug(`V2 group inline push consumed: group=${groupId} seq=${seq}`);
+                    this.retryPendingGroupInlineAck(ns, seq, 'inline push');
+                    return;
+                }
+            }
+            catch (exc) {
+                if (inlineGeneration !== undefined && !this.inlineGenerationIsCurrent(inlineGeneration))
+                    return;
+                client._clientLog.warn(`V2 group inline push rejected, falling back to Tail: group=${groupId} seq=${seq} err=${formatDeliveryError(exc)}`);
+            }
+        }
+        const before = this.syncState(ns);
         client._seqTracker.updateMaxSeen(ns, seq);
-        const contigBefore = client._seqTracker.getContiguousSeq(ns);
-        client._clientLog.debug(`_onRawGroupV2MessageCreated enter: group=${groupId}, seq=${seq}, contiguous=${contigBefore}, max_seen=${client._seqTracker.getMaxSeenSeq(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, seq, 'covered push');
+        const hasGap = before.ack < before.tail - 1;
+        if (seq <= before.head && !hasGap && !inlinePresent) {
+            client._clientLog.debug(`V2 group duplicate push ignored: group=${groupId} seq=${seq} A/T/H=${JSON.stringify(before)}`);
+            const pending = this.pendingGroupInlineAcks?.get(ns);
+            if (pending?.seq === seq) {
+                this.retryPendingGroupInlineAck(ns, seq, 'covered inline push');
+            }
+            else {
+                this.fireGroupV2Ack(groupId, seq, 'covered push');
+            }
             return;
         }
-        const afterSeq = client._repairPushContiguousBound(ns, seq, false, '_raw.group.v2.message_created');
-        const dedupKey = `v2_group_push:${groupId}:${afterSeq}`;
-        const pullTask = client._tryRunBackgroundPull(ns, async () => {
-            const pullAfterSeq = client._seqTracker.getContiguousSeq(ns);
-            if (client._gapFillDone.has(dedupKey)) {
-                client._clientLog.debug(`_onRawGroupV2MessageCreated skipped duplicate in-flight pull: group=${groupId}, dedup=${dedupKey}`);
-                return 0;
-            }
-            client._gapFillDone.set(dedupKey, Date.now());
-            try {
-                client._clientLog.debug(`_onRawGroupV2MessageCreated auto-pull start: group=${groupId}, after_seq=${pullAfterSeq}, push_seq=${seq}`);
-                const pulled = await client._pullGroupV2(groupId, pullAfterSeq, 50, { gateLocked: true });
-                const newContig = client._seqTracker.getContiguousSeq(ns);
-                client._clientLog.debug(`_onRawGroupV2MessageCreated auto-pull done: group=${groupId}, after_seq=${pullAfterSeq}, push_seq=${seq}, contiguous=${newContig}`);
-                if (newContig <= pullAfterSeq)
-                    return 0;
-                return pulled.length;
+        if (!this.beginRealtimeSync(ns)) {
+            client._clientLog.debug(`V2 group push coalesced into in-flight realtime sync: ns=${ns} seq=${seq}`);
+            return;
+        }
+        const pullTask = this.runGroupRealtimeSync(groupId, ns, seq, 50, inlinePresent && !inlineConsumed).then(async (syncResult) => {
+            if (inlineGeneration !== undefined && !this.inlineGenerationIsCurrent(inlineGeneration))
+                return;
+            const tailHead = this.realtimeTailHead(syncResult);
+            const maxSeen = Number(client._seqTracker.getMaxSeenSeq?.(ns) ?? 0);
+            if (client._sessionOptions?.background_sync !== false
+                && tailHead !== null && Number.isSafeInteger(maxSeen) && maxSeen > tailHead) {
+                await this.runGroupForwardRecovery(groupId, ns, 50).catch((exc) => {
+                    client._clientLog.warn(`V2 group stale Tail Forward recovery failed: group=${groupId} err=${formatDeliveryError(exc)}`);
+                });
+                if (inlineGeneration !== undefined && !this.inlineGenerationIsCurrent(inlineGeneration))
+                    return;
             }
-            finally {
-                client._gapFillDone.delete(dedupKey);
+        }).catch((exc) => {
+            if (inlineGeneration !== undefined && !this.inlineGenerationIsCurrent(inlineGeneration))
+                return;
+            client._clientLog.warn(`V2 group push auto-sync failed: group=${groupId} err=${formatDeliveryError(exc)}`);
+        }).finally(() => {
+            if (inlineGeneration === undefined || this.inlineGenerationIsCurrent(inlineGeneration)) {
+                this.endRealtimeSync(ns);
             }
-        }, true).catch((exc) => {
-            client._clientLog.warn(`V2 group push auto-pull failed: group=${groupId} err=${formatDeliveryError(exc)}`);
         });
         if (d._online_hint_drained) {
             await pullTask;
@@ -1452,6 +2552,15 @@ export class MessageDeliveryEngine {
         if (!client._aid)
             return;
         try {
+            const loadSync = client._tokenStore.loadAllSyncStates;
+            if (typeof loadSync === 'function' && typeof client._seqTracker.restoreSyncState === 'function') {
+                let state = loadSync.call(client._tokenStore, client._aid, client._deviceId, client._slotId);
+                if (state && Object.keys(state).length > 0) {
+                    state = this.migrateSeqStateGroupIds(state);
+                    client._seqTracker.restoreSyncState(state);
+                    return;
+                }
+            }
             const loadAll = client._tokenStore.loadAllSeqs;
             if (typeof loadAll === 'function') {
                 let state = loadAll.call(client._tokenStore, client._aid, client._deviceId, client._slotId);
@@ -1467,7 +2576,10 @@ export class MessageDeliveryEngine {
                 if (instanceState && typeof instanceState.seq_tracker_state === 'object') {
                     let state = instanceState.seq_tracker_state;
                     state = this.migrateSeqStateGroupIds(state);
-                    client._seqTracker.restoreState(state);
+                    if (typeof client._seqTracker.restoreSyncState === 'function')
+                        client._seqTracker.restoreSyncState(state);
+                    else
+                        client._seqTracker.restoreState(state);
                 }
             }
         }
@@ -1484,53 +2596,7 @@ export class MessageDeliveryEngine {
         }
     }
     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);
-        }
-        client._clientLog.info(`SeqTracker group_id migration: ${Object.keys(renameMap).length} namespaces rewritten`);
-        const saver = client._tokenStore.saveSeq;
-        const deleter = client._tokenStore.deleteSeq;
-        if (typeof saver === 'function' && client._aid) {
-            for (const [oldNs, newNs] of Object.entries(renameMap)) {
-                if (typeof deleter === 'function') {
-                    try {
-                        deleter.call(client._tokenStore, client._aid, client._deviceId, client._slotId, oldNs);
-                    }
-                    catch (e) {
-                        client._clientLog.debug(`delete old seq ns failed: ns=${oldNs} err=${formatDeliveryError(e)}`);
-                    }
-                }
-                try {
-                    saver.call(client._tokenStore, client._aid, client._deviceId, client._slotId, newNs, newState[newNs]);
-                }
-                catch (e) {
-                    client._clientLog.debug(`write new seq ns failed: ns=${newNs} err=${formatDeliveryError(e)}`);
-                }
-            }
-        }
-        return newState;
+        return state;
     }
     saveSeqTrackerState() {
         const client = this.runtime.client;
@@ -1539,7 +2605,9 @@ export class MessageDeliveryEngine {
             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));
@@ -1567,9 +2635,27 @@ 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();
     }
+    commitSeqTrackerState(ns) {
+        const client = this.runtime.client;
+        const context = this.currentSeqTrackerContext();
+        if (!context || !ns)
+            return;
+        const state = typeof client._seqTracker.getSyncState === 'function'
+            ? client._seqTracker.getSyncState(ns)
+            : { ack: client._seqTracker.getContiguousSeq(ns), tail: client._seqTracker.getContiguousSeq(ns), head: client._seqTracker.getContiguousSeq(ns) };
+        if (![state.ack, state.tail, state.head].some((value) => Number(value) > 0))
+            return;
+        const [aid, deviceId, slotId] = JSON.parse(context);
+        this.writeSeqTrackerState(aid, deviceId, slotId, { [ns]: state }, true);
+        this.dropSeqTrackerPending(ns);
+        client._clientLog.debug(`seq_tracker atomic commit: ns=${ns} A/T/H=${JSON.stringify(state)} context=${context}`);
+    }
     flushSeqTrackerPending() {
         const client = this.runtime.client;
         this.cancelSeqTrackerFlushTimer();
@@ -1615,10 +2701,12 @@ export class MessageDeliveryEngine {
             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 });
             }
         }
     }
@@ -1641,15 +2729,20 @@ export class MessageDeliveryEngine {
             client._seqTrackerFlushTimer = null;
         }
     }
-    writeSeqTrackerState(aid, deviceId, slotId, state) {
+    writeSeqTrackerState(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;
+            if (typeof saveSync === 'function') {
+                saveSync.call(client._tokenStore, aid, deviceId, slotId, state);
+                return;
+            }
             const saveFn = client._tokenStore.saveSeq;
             if (typeof saveFn === 'function') {
-                for (const [ns, seq] of Object.entries(state)) {
-                    saveFn.call(client._tokenStore, aid, deviceId, slotId, ns, seq);
+                for (const [ns, triplet] of Object.entries(state)) {
+                    saveFn.call(client._tokenStore, aid, deviceId, slotId, ns, triplet.ack);
                 }
                 return;
             }
@@ -1674,6 +2767,8 @@ export class MessageDeliveryEngine {
                 slot_id: slotId,
                 error: String(error),
             }).catch(() => { });
+            if (throwOnError)
+                throw exc;
         }
     }
     persistRepairedSeq(ns) {
@@ -1721,10 +2816,21 @@ export class MessageDeliveryEngine {
         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;
@@ -1747,7 +2853,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);
@@ -1818,15 +2924,7 @@ export class MessageDeliveryEngine {
             return false;
         }
         const contig = client._seqTracker.getContiguousSeq(ns);
-        if (seqNum <= contig) {
-            client._clientLog.debug(`publish ordered stale covered: event=${event}, ns=${ns}, seq=${seqNum}, contiguous=${contig}`);
-            const queue = client._pendingOrderedMsgs.get(ns);
-            queue?.delete(seqNum);
-            if (queue && queue.size === 0)
-                client._pendingOrderedMsgs.delete(ns);
-            return false;
-        }
-        if (seqNum !== contig + 1) {
+        if (seqNum > contig && seqNum !== contig + 1) {
             client._clientLog.debug(`publish ordered enqueue(gap): event=${event}, ns=${ns}, seq=${seqNum}, contiguous=${contig}`);
             this.enqueueOrderedMessage(ns, event, seqNum, payload);
             return false;
@@ -1898,16 +2996,16 @@ export class MessageDeliveryEngine {
         if (event === 'message.recalled') {
             const recallPublished = await this.publishMessageRecallTombstone(seqNum, payload);
             this.markPublishedSeq(ns, seqNum);
-            client._markPulledSeqDelivered(ns, seqNum);
             client._clientLog.debug(`publish pulled delivered: event=${event}, ns=${ns}, seq=${seqNum}`);
+            await this.drainOrderedMessages(ns, undefined, true);
             return recallPublished;
         }
         const published = client._withPullResponseProcessing(ns, () => client._publishAppEvent(event, payload, 'pull'));
         if (isPromiseLike(published))
             await published;
         this.markPublishedSeq(ns, seqNum);
-        client._markPulledSeqDelivered(ns, seqNum);
         client._clientLog.debug(`publish pulled delivered: event=${event}, ns=${ns}, seq=${seqNum}`);
+        await this.drainOrderedMessages(ns, undefined, true);
         return true;
     }
 }