@agentunion/fastaun-browser 0.5.6 → 0.5.9

package/dist/client/v2-e2ee.js

@@ -4,6 +4,10 @@ import { decryptMessage, encryptGroupMessage, encryptP2PMessage, } from '../v2/e
 import { V2Session, V2KeyStore } from '../v2/session/index.js';
 import { ConnectionState, isJsonObject } from '../types.js';
 import { normalizeGroupMentionMode } from './mention-mode.js';
+function pullGateKeyForClient(client, method, params, fallback) {
+    const key = client._rpcPipeline?.pullGateKeyForCall?.(method, params);
+    return typeof key === 'string' && key ? key : fallback;
+}
 const V2_BOOTSTRAP_TTL_MS = 60 * 60 * 1000;
 const V2_RETRYABLE_CODES = new Set([-33011, -33012, -33050, -33052, -33054]);
 const V2_GROUP_STALE_BOOTSTRAP_CODE = -33054;
@@ -21,6 +25,9 @@ function strictWindowSeq(value, field, positive = false) {
         throw new ValidationError(`${field} must be >= ${minimum}`);
     return value;
 }
+function safeNonNegativeSeq(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
 function strictWindowLimit(value) {
     const limit = strictWindowSeq(value, 'limit', true);
     if (limit > V2_PULL_MAX_PAGE_LIMIT)
@@ -53,26 +60,50 @@ function deduplicateForwardPageMessages(value, afterSeq) {
         if (!isJsonObject(raw))
             continue;
         const row = raw;
-        const seq = Number(row.seq ?? 0);
-        if (!Number.isSafeInteger(seq) || seq <= afterSeq || bySeq.has(seq))
+        const seq = safeNonNegativeSeq(row.seq);
+        if (seq === null || seq <= 0 || seq <= afterSeq || bySeq.has(seq))
             continue;
         bySeq.set(seq, row);
     }
     return [...bySeq.entries()].sort(([a], [b]) => a - b).map(([, row]) => row);
 }
-function validateTailPage(result, pageLimit) {
+function shouldContinueForwardPage({ rawCount, nextAfterSeq, nextAfter, limit, hasMoreField, hasMore, serverHead, pendingAckSeq, }) {
+    // 无新 seq 或游标未前进时必须停止，避免错误元数据造成循环。
+    if (rawCount <= 0 || nextAfter <= nextAfterSeq)
+        return false;
+    if (hasMore || serverHead > nextAfter || pendingAckSeq > 0)
+        return true;
+    // 仅旧服务缺失 has_more 时，以满页保留兼容续拉。
+    return !hasMoreField && limit > 0 && rawCount >= limit;
+}
+function validateTailPage(result, afterSeq, pageLimit) {
     if (!isJsonObject(result))
         throw new ValidationError('tail response must be an object');
     const row = result;
     if (row.window_mode !== 'tail')
         throw new ValidationError('tail response window_mode must equal tail');
+    strictWindowSeq(afterSeq, 'after_seq');
     const windowStart = strictWindowSeq(row.window_start_seq, 'window_start_seq');
     const head = strictWindowSeq(row.head_seq, 'head_seq');
     const covered = strictWindowSeq(row.covered_through_seq, 'covered_through_seq');
     if (windowStart > head || covered !== head || head - windowStart + 1 > pageLimit) {
         throw new ValidationError('tail response proof is invalid');
     }
-    return { windowStart, head, messages: deduplicateWindowMessages(row.messages, windowStart, head, 'the proven tail window') };
+    let lowerSeq = windowStart;
+    if (head <= afterSeq) {
+        if (windowStart !== head)
+            throw new ValidationError('empty tail window must end at head_seq');
+        lowerSeq = head + 1;
+    }
+    else {
+        if (windowStart < afterSeq + 1)
+            throw new ValidationError('tail window_start_seq is below after_seq');
+        lowerSeq = Math.max(windowStart, afterSeq + 1);
+    }
+    const messages = deduplicateWindowMessages(row.messages, lowerSeq, head, 'the proven tail window');
+    if (head <= afterSeq && messages.length > 0)
+        throw new ValidationError('tail response must not include messages at or below after_seq');
+    return { windowStart, head, messages };
 }
 function validateHistoryPage(result, beforeSeq) {
     if (!isJsonObject(result))
@@ -329,6 +360,9 @@ export class V2E2EECoordinator {
     runtime;
     targetSetCache = new Map();
     senderIKSyncFetches = new Map();
+    /** 服务端 ACK cursor 高于本地 A 时，延迟到下一次 Forward Pull 再恢复。 */
+    pendingForwardCursors = new Map();
+    pendingForwardAcks = new Map();
     v2SessionInitRetryTimer = null;
     v2SessionInitRetryBackgroundSync = false;
     v2SessionInitRetryIdentityKey = null;
@@ -338,6 +372,51 @@ export class V2E2EECoordinator {
     get client() {
         return this.runtime.client;
     }
+    resetForwardCursorState() {
+        this.pendingForwardCursors.clear();
+        this.pendingForwardAcks.clear();
+    }
+    pendingForwardCursor(ns, localAck) {
+        if (!ns)
+            return 0;
+        const pending = this.pendingForwardCursors.get(ns) ?? 0;
+        if (pending <= localAck) {
+            if (pending > 0)
+                this.pendingForwardCursors.delete(ns);
+            return 0;
+        }
+        return pending;
+    }
+    recordForwardCursor(ns, cursor, localAck) {
+        if (!ns || !Number.isSafeInteger(cursor) || cursor <= localAck)
+            return;
+        this.pendingForwardCursors.set(ns, Math.max(this.pendingForwardCursors.get(ns) ?? 0, cursor));
+    }
+    clearForwardCursor(ns, committedAck) {
+        const pending = this.pendingForwardCursors.get(ns) ?? 0;
+        if (pending > 0 && committedAck >= pending)
+            this.pendingForwardCursors.delete(ns);
+    }
+    pendingForwardAck(ns, localAck) {
+        if (!ns)
+            return 0;
+        const pending = this.pendingForwardAcks.get(ns) ?? 0;
+        if (!Number.isSafeInteger(pending) || pending <= 0 || localAck <= 0 || pending > localAck) {
+            this.pendingForwardAcks.delete(ns);
+            return 0;
+        }
+        return pending;
+    }
+    recordForwardAck(ns, ackSeq) {
+        if (!ns || !Number.isSafeInteger(ackSeq) || ackSeq <= 0)
+            return;
+        this.pendingForwardAcks.set(ns, Math.max(this.pendingForwardAcks.get(ns) ?? 0, ackSeq));
+    }
+    clearForwardAck(ns, confirmedSeq) {
+        const pending = this.pendingForwardAcks.get(ns) ?? 0;
+        if (pending > 0 && confirmedSeq >= pending)
+            this.pendingForwardAcks.delete(ns);
+    }
     get bootstrapCache() {
         const client = this.client;
         if (!(client._v2BootstrapCache instanceof Map)) {
@@ -759,7 +838,8 @@ export class V2E2EECoordinator {
             createdAt: Date.now(),
         });
         client._clientLog.debug(`V2 decrypt pending sender IK: key=${messageKey} from=${fromAid} device=${senderDeviceId || '-'} group=${groupId || '<p2p>'} pending=${client._v2SenderIKPending.size}`);
-        this.scheduleSenderIKFetch(fromAid, senderDeviceId, groupId);
+        if (args.startFetch !== false)
+            this.scheduleSenderIKFetch(fromAid, senderDeviceId, groupId);
     }
     scheduleSenderIKFetch(fromAid, senderDeviceId, groupId) {
         const client = this.client;
@@ -810,8 +890,9 @@ export class V2E2EECoordinator {
             const pendingItems = [...client._v2SenderIKPending.entries()].filter(([, entry]) => entry.fromAid === fromAid && entry.senderDeviceId === senderDeviceId && entry.groupId === groupId);
             for (const [key, entry] of pendingItems) {
                 let plaintext = null;
+                const retryStatus = {};
                 try {
-                    plaintext = await client._decryptV2Message(entry.msg, false);
+                    plaintext = await client._decryptV2Message(entry.msg, false, true, true, true, retryStatus);
                 }
                 catch (exc) {
                     client._clientLog.warn(`V2 sender IK pending retry raised: key=${key} err=${String(formatE2EEError(exc))}`);
@@ -819,6 +900,10 @@ export class V2E2EECoordinator {
                     continue;
                 }
                 if (plaintext === null) {
+                    if (retryStatus.deferred) {
+                        client._clientLog.warn(`V2 pending retry still missing key material: key=${key}`);
+                        continue;
+                    }
                     client._clientLog.warn(`V2 sender IK pending retry still undecryptable: key=${key}`);
                     const isGroup = Boolean(entry.groupId);
                     const eventName = isGroup ? 'group.message_undecryptable' : 'message.undecryptable';
@@ -907,7 +992,7 @@ export class V2E2EECoordinator {
             history_error: { code: 'decrypt_failed', message: reason },
         };
     }
-    async decodeP2PWindowMessage(msg, publish, history, source) {
+    async decodeP2PWindowMessage(msg, publish, history, source, orderedPublish = false) {
         const client = this.client;
         const seq = strictWindowSeq(msg.seq, 'messages[].seq', true);
         let plaintext = null;
@@ -939,16 +1024,27 @@ export class V2E2EECoordinator {
         }
         if (publish) {
             const event = client._delivery.p2pAppEventForMessage(plaintext);
-            await client._publishAppEvent(event.event, event.payload, source);
+            if (orderedPublish) {
+                await client._delivery.publishOrderedMessage(event.event, client._aid ? `p2p:${client._aid}` : '', seq, event.payload);
+            }
+            else {
+                await client._publishAppEvent(event.event, event.payload, source);
+            }
         }
         return plaintext;
     }
-    async decodeGroupWindowMessage(msg, groupId, groupAid, publish, history, source) {
+    async decodeGroupWindowMessage(msg, groupId, groupAid, publish, history, source, orderedPublish = false) {
         const client = this.client;
         const seq = strictWindowSeq(msg.seq, 'messages[].seq', true);
         let plaintext = null;
         if (String(msg.version ?? '') === 'v1') {
             const payload = msg.payload;
+            if (payload === undefined || payload === null) {
+                if (history)
+                    return this.historyDecryptFailure(msg, 'legacy payload is missing');
+                client._clientLog.warn(`Group Tail 缺少 payload 的 V1 行已跳过，连续性证明仍保留: group=${groupId}, seq=${seq}`);
+                return null;
+            }
             if (isJsonObject(payload)
                 && ['e2ee.encrypted', 'e2ee.group_encrypted'].includes(String(payload.type ?? ''))) {
                 if (history)
@@ -985,8 +1081,14 @@ export class V2E2EECoordinator {
             client._clientLog.warn(`Group Tail 单条消息解密失败，连续性证明仍保留: group=${groupId}, seq=${seq}`);
             return null;
         }
-        if (publish)
-            await client._publishAppEvent('group.message_created', plaintext, source);
+        if (publish) {
+            if (orderedPublish) {
+                await client._delivery.publishOrderedMessage('group.message_created', `group:${groupId}`, seq, plaintext);
+            }
+            else {
+                await client._publishAppEvent('group.message_created', plaintext, source);
+            }
+        }
         return plaintext;
     }
     async decodeInlineP2PMessage(msg) {
@@ -1003,7 +1105,7 @@ export class V2E2EECoordinator {
         client._persistSeq(ns);
         await client._saveSeqTrackerState?.();
     }
-    async pullV2TailInternal(params) {
+    async pullV2TailInternal(params, deferPublish = false) {
         const client = this.client;
         if (params.window_mode !== 'tail')
             throw new ValidationError('window_mode must equal tail');
@@ -1016,7 +1118,7 @@ export class V2E2EECoordinator {
         const floor = Number(result.retention_floor_seq ?? 0);
         const previous = ns ? client._seqTracker.getSyncState(ns) : null;
         await this.applyTailFloor(ns, Number.isSafeInteger(floor) ? floor : 0);
-        const page = validateTailPage(result, limit);
+        const page = validateTailPage(result, afterSeq, limit);
         if (ns) {
             client._seqTracker.commitTailWindow(ns, {
                 windowStartSeq: page.windowStart, headSeq: page.head, coveredThroughSeq: page.head, pageLimit: limit,
@@ -1026,7 +1128,7 @@ export class V2E2EECoordinator {
         }
         const decoded = [];
         for (const msg of page.messages) {
-            const plaintext = await this.decodeP2PWindowMessage(msg, true, false, 'tail');
+            const plaintext = await this.decodeP2PWindowMessage(msg, true, false, 'tail', deferPublish);
             if (plaintext)
                 decoded.push(plaintext);
         }
@@ -1053,14 +1155,39 @@ export class V2E2EECoordinator {
         await client._ensureV2SessionReady('message.pull');
         const ns = client._aid ? `p2p:${client._aid}` : '';
         if (opts?.windowMode === 'tail') {
+            if (!opts.gateLocked) {
+                const key = pullGateKeyForClient(client, 'message.v2.pull', {
+                    window_mode: 'tail', after_seq: afterSeq, limit,
+                }, `${ns}|tail|after=${afterSeq}|limit=${limit}`);
+                return await client._runPullSerialized(key, () => this.pullV2(afterSeq, limit, {
+                    ...(opts ?? {}),
+                    gateLocked: true,
+                }), false);
+            }
             const result = await this.pullV2TailInternal({ window_mode: 'tail', after_seq: afterSeq, limit });
             return Array.isArray(result.messages) ? result.messages : [];
         }
+        if (ns && !opts?.gateLocked) {
+            const key = pullGateKeyForClient(client, 'message.v2.pull', {
+                after_seq: afterSeq, force: opts?.force === true, limit,
+            }, `${ns}|forward|after=${afterSeq}|force=${String(Boolean(opts?.force))}|limit=${limit}`);
+            return await client._runPullSerialized(key, () => this.pullV2(afterSeq, limit, {
+                ...(opts ?? {}),
+                gateLocked: true,
+            }), true);
+        }
         const decrypted = [];
         let nextAfterSeq = opts?.force ? afterSeq : (afterSeq || (ns ? client._seqTracker.getContiguousSeq(ns) : 0));
+        let pullGateKey = ns
+            ? pullGateKeyForClient(client, 'message.v2.pull', {
+                after_seq: afterSeq, force: opts?.force === true, limit,
+            }, `${ns}|forward|after=${afterSeq}|force=${String(Boolean(opts?.force))}|limit=${limit}`)
+            : '';
+        const deferredServerCursor = ns ? this.pendingForwardCursor(ns, client._seqTracker.getContiguousSeq(ns)) : 0;
+        const deferredForwardAck = ns ? this.pendingForwardAck(ns, client._seqTracker.getContiguousSeq(ns)) : 0;
         let pageCount = 0;
         let lastAutoAckSeq = 0;
-        let pendingAckSeq = 0;
+        let pendingAckSeq = deferredForwardAck;
         const maxPages = Math.max(1, Math.min(100, Math.trunc(Number(opts?.maxPages ?? 100) || 100)));
         while (pageCount < maxPages) {
             pageCount += 1;
@@ -1075,24 +1202,29 @@ export class V2E2EECoordinator {
                 ...(ackUpToSeq > 0 ? { ack_up_to_seq: ackUpToSeq } : {}),
             });
             if (ackUpToSeq > 0) {
-                if (pendingInlineGeneration !== null) {
-                    let actualAckSeq = ackUpToSeq;
-                    if (Object.prototype.hasOwnProperty.call(result, 'server_ack_seq')) {
-                        actualAckSeq = typeof result.server_ack_seq === 'number'
-                            && Number.isSafeInteger(result.server_ack_seq) && result.server_ack_seq >= 0
-                            ? result.server_ack_seq
-                            : 0;
-                    }
-                    if (actualAckSeq > 0) {
+                const actualAckSeq = client._delivery?.resolveP2PPullAckSeq?.(result, ackUpToSeq) ?? 0;
+                if (actualAckSeq >= ackUpToSeq) {
+                    if (pendingInlineGeneration !== null) {
                         client._delivery?.completePendingP2PInlineAckUpTo?.(ns, actualAckSeq, pendingInlineGeneration);
                     }
+                    pendingAckSeq = 0;
+                    lastAutoAckSeq = Math.max(lastAutoAckSeq, ackUpToSeq);
+                    this.clearForwardAck(ns, ackUpToSeq);
+                }
+                else {
+                    client._clientLog.warn(`message.v2.pull piggyback ACK below target: requested=${ackUpToSeq}, actual=${actualAckSeq}; fallback terminal ACK`);
+                    await this.confirmForwardP2PAck(ackUpToSeq, pendingInlineGeneration ?? undefined);
+                    pendingAckSeq = 0;
+                    lastAutoAckSeq = Math.max(lastAutoAckSeq, ackUpToSeq);
                 }
-                pendingAckSeq = 0;
-                lastAutoAckSeq = Math.max(lastAutoAckSeq, ackUpToSeq);
             }
             const pageMessages = (Array.isArray(result?.messages) ? result.messages : []);
             const messages = deduplicateForwardPageMessages(pageMessages, nextAfterSeq);
-            client._clientLog.debug(`message.v2.pull page response: page=${pageCount}, raw_count=${messages.length}, stale_count=${Math.max(0, pageMessages.length - messages.length)}, has_more=${String(result.has_more ?? '')}, server_ack_seq=${String(result.server_ack_seq ?? '')}`);
+            const cursor = isJsonObject(result.cursor) ? result.cursor : null;
+            const hasMoreField = Object.prototype.hasOwnProperty.call(result, 'has_more');
+            const hasMore = result.has_more === true;
+            const serverHead = safeNonNegativeSeq(cursor?.latest_seq) ?? 0;
+            client._clientLog.debug(`message.v2.pull page response: page=${pageCount}, raw_count=${messages.length}, stale_count=${Math.max(0, pageMessages.length - messages.length)}, has_more=${String(result.has_more ?? '')}, server_head=${serverHead}, server_ack_seq=${String(result.server_ack_seq ?? '')}`);
             const seqs = messages
                 .map((msg) => Number(msg.seq ?? 0))
                 .filter((seq) => Number.isFinite(seq) && seq > 0);
@@ -1101,6 +1233,8 @@ export class V2E2EECoordinator {
                 ? client._seqTracker.snapshotNamespace(ns)
                 : null;
             const pageMaxSeq = seqs.length > 0 ? Math.max(...seqs) : nextAfterSeq;
+            const deferredKeyFetches = new Map();
+            let blockedSeq = 0;
             for (const msg of messages) {
                 const seq = Number(msg.seq ?? 0);
                 if (!Number.isFinite(seq) || seq <= 0)
@@ -1127,7 +1261,7 @@ export class V2E2EECoordinator {
                         attachGatewayProximity(v1Msg, msg);
                         const appEvent = client._delivery.p2pAppEventForMessage(v1Msg);
                         if (ns)
-                            await client._publishPulledMessage(appEvent.event, ns, seq, appEvent.payload);
+                            await client._publishPulledMessage(appEvent.event, ns, seq, appEvent.payload, false);
                         else
                             await client._publishAppEvent(appEvent.event, appEvent.payload);
                         decrypted.push(v1Msg);
@@ -1145,11 +1279,23 @@ export class V2E2EECoordinator {
                 if (msgSpkId && client._v2Session && !client._v2Session.isCurrentSPK(msgSpkId)) {
                     client._v2Session.trackOldSPKMaxSeq(msgSpkId, seq);
                 }
-                const plaintext = await client._decryptV2Message(msg);
+                const deferStatus = {};
+                const plaintext = await client._decryptV2Message(msg, true, true, true, true, deferStatus, true);
+                if (deferStatus.deferred) {
+                    blockedSeq = blockedSeq > 0 ? Math.min(blockedSeq, seq) : seq;
+                }
+                if (deferStatus.deferred && deferStatus.fromAid) {
+                    const key = `${deferStatus.fromAid}\u0000${deferStatus.senderDeviceId ?? ''}\u0000${deferStatus.groupId ?? ''}`;
+                    deferredKeyFetches.set(key, {
+                        fromAid: deferStatus.fromAid,
+                        senderDeviceId: deferStatus.senderDeviceId ?? '',
+                        groupId: deferStatus.groupId ?? '',
+                    });
+                }
                 if (plaintext === null)
                     continue;
                 if (ns) {
-                    await client._publishPulledMessage('message.received', ns, seq, plaintext);
+                    await client._publishPulledMessage('message.received', ns, seq, plaintext, false);
                     decrypted.push(plaintext);
                 }
                 else {
@@ -1158,10 +1304,11 @@ export class V2E2EECoordinator {
                 }
             }
             const hasServerAckSeq = Object.prototype.hasOwnProperty.call(result, 'server_ack_seq');
-            const serverAckSeq = Number(result.server_ack_seq ?? 0);
+            const parsedServerAckSeq = hasServerAckSeq ? safeNonNegativeSeq(result.server_ack_seq) : null;
+            const serverAckSeq = parsedServerAckSeq ?? 0;
             const retentionFloor = Math.max(0, Number(result.retention_floor_seq ?? 0));
             if (ns) {
-                const commitTarget = Math.max(pageContigBefore, Number.isFinite(retentionFloor) ? retentionFloor : 0, seqs.length > 0 ? pageMaxSeq : pageContigBefore);
+                const commitTarget = blockedSeq > 0 ? pageContigBefore : Math.max(pageContigBefore, Number.isFinite(retentionFloor) ? retentionFloor : 0, pageCount === 1 ? deferredServerCursor : 0, seqs.length > 0 ? pageMaxSeq : pageContigBefore);
                 let ackSeq = pageContigBefore;
                 let contigAdvanced = false;
                 try {
@@ -1170,6 +1317,9 @@ export class V2E2EECoordinator {
                         if (retentionFloor > pageContigBefore) {
                             client._clientLog.info(`message.v2.pull retention-floor advance: ns=${ns} contiguous=${pageContigBefore} -> retention_floor_seq=${retentionFloor}`);
                         }
+                        if (deferredServerCursor > pageContigBefore && pageCount === 1) {
+                            client._clientLog.info(`message.v2.pull restore local A from deferred server ACK cursor: ns=${ns}, contiguous=${pageContigBefore} -> server_ack_seq=${deferredServerCursor}`);
+                        }
                         if (seqs.length > 0) {
                             client._clientLog.debug(`message.v2.pull force contiguous: ns=${ns}, page_max_seq=${pageMaxSeq}, previous=${pageContigBefore}`);
                         }
@@ -1177,10 +1327,9 @@ export class V2E2EECoordinator {
                     ackSeq = client._seqTracker.getContiguousSeq(ns);
                     contigAdvanced = ackSeq !== pageContigBefore;
                     if (contigAdvanced) {
-                        await client._drainOrderedMessages(ns);
-                        ackSeq = client._seqTracker.getContiguousSeq(ns);
-                        contigAdvanced = ackSeq !== pageContigBefore;
                         await client._commitSeqTrackerState(ns);
+                        if (pageCount === 1 && deferredServerCursor > 0)
+                            this.clearForwardCursor(ns, ackSeq);
                     }
                 }
                 catch (exc) {
@@ -1190,11 +1339,26 @@ export class V2E2EECoordinator {
                     client._clientLog.error?.(`message.v2.pull Forward commit rolled back: ns=${ns} target=${commitTarget} error=${formatE2EEError(exc)}`);
                     throw exc;
                 }
-                const ackNeeded = pageMessages.length > 0
+                if (contigAdvanced)
+                    await client._drainOrderedMessages(ns, undefined, false, false);
+                for (const fetch of deferredKeyFetches.values()) {
+                    this.scheduleSenderIKFetch(fetch.fromAid, fetch.senderDeviceId, fetch.groupId);
+                }
+                if (parsedServerAckSeq !== null && serverAckSeq > ackSeq) {
+                    this.recordForwardCursor(ns, serverAckSeq, ackSeq);
+                }
+                // 无本页服务端水位时，只有本页成功提交了比已知服务端更高的 A
+                // 才新增 ACK 义务。空页不能仅因本地已有 A 而重复 ACK。
+                const knownServerAckSeq = hasServerAckSeq
+                    ? serverAckSeq
+                    : (pageCount === 1 ? deferredServerCursor : 0);
+                const ackNeeded = blockedSeq <= 0
                     && ackSeq > 0
                     && ackSeq > lastAutoAckSeq
-                    && (contigAdvanced || (hasServerAckSeq && ackSeq > serverAckSeq));
+                    && ((hasServerAckSeq && ackSeq > serverAckSeq)
+                        || (contigAdvanced && ackSeq > knownServerAckSeq));
                 if (ackNeeded) {
+                    this.recordForwardAck(ns, ackSeq);
                     const nextAfter = Math.max(pageMaxSeq, nextAfterSeq);
                     const canContinuePage = messages.length > 0 && nextAfter > nextAfterSeq;
                     if (canContinuePage) {
@@ -1202,18 +1366,34 @@ export class V2E2EECoordinator {
                         lastAutoAckSeq = Math.max(lastAutoAckSeq, ackSeq);
                     }
                     else {
-                        await this.ackV2(ackSeq);
+                        await this.confirmForwardP2PAck(ackSeq);
                         lastAutoAckSeq = Math.max(lastAutoAckSeq, ackSeq);
                     }
                 }
             }
             const nextAfter = Math.max(pageMaxSeq, nextAfterSeq);
             const rawCount = messages.length;
-            const canContinuePage = rawCount > 0 && nextAfter > nextAfterSeq;
-            const fullPage = canContinuePage && limit > 0 && rawCount >= limit;
-            const shouldContinue = canContinuePage && (fullPage || pendingAckSeq > 0);
+            if (blockedSeq > 0)
+                break;
+            const shouldContinue = shouldContinueForwardPage({
+                rawCount,
+                nextAfterSeq,
+                nextAfter,
+                limit,
+                hasMoreField,
+                hasMore,
+                serverHead,
+                pendingAckSeq,
+            });
             if (!shouldContinue)
                 break;
+            if (pullGateKey && opts?.gateLocked && client._rpcPipeline?.yieldPullGate) {
+                const nextKey = pullGateKeyForClient(client, 'message.v2.pull', {
+                    after_seq: nextAfter, force: opts?.force === true, limit,
+                }, `${ns}|forward|after=${nextAfter}|force=${String(Boolean(opts?.force))}|limit=${limit}`);
+                await client._rpcPipeline.yieldPullGate(pullGateKey, nextKey, true);
+                pullGateKey = nextKey;
+            }
             const tailDelayMs = v2PullTailDelayMs(rawCount, limit);
             if (tailDelayMs > 0)
                 await v2Sleep(tailDelayMs);
@@ -1222,13 +1402,34 @@ export class V2E2EECoordinator {
         if (pageCount >= maxPages) {
             client._clientLog.warn(`message.v2.pull reached max_pages=${maxPages} after_seq=${nextAfterSeq}`);
             if (pendingAckSeq > 0) {
-                await this.ackV2(pendingAckSeq);
+                await this.confirmForwardP2PAck(pendingAckSeq);
                 pendingAckSeq = 0;
             }
         }
         return decrypted;
     }
+    async confirmForwardP2PAck(upToSeq, inlineGeneration) {
+        const ns = this.client._aid ? `p2p:${this.client._aid}` : '';
+        try {
+            const result = await this.ackV2ForForward(upToSeq, inlineGeneration);
+            const actualAckSeq = this.client._delivery?.resolveForwardAckSeq?.(result, upToSeq) ?? 0;
+            if (actualAckSeq < upToSeq) {
+                throw new E2EEError(`message.v2.ack server ACK watermark ${actualAckSeq} is below requested ${upToSeq}`);
+            }
+            this.clearForwardAck(ns, upToSeq);
+        }
+        catch (exc) {
+            this.recordForwardAck(ns, upToSeq);
+            throw exc;
+        }
+    }
     async ackV2(upToSeq, inlineGeneration) {
+        return this.ackV2WithConfirmation(upToSeq, inlineGeneration, false);
+    }
+    async ackV2ForForward(upToSeq, inlineGeneration) {
+        return this.ackV2WithConfirmation(upToSeq, inlineGeneration, true);
+    }
+    async ackV2WithConfirmation(upToSeq, inlineGeneration, requireServerWatermark) {
         const client = this.client;
         const ns = client._aid ? `p2p:${client._aid}` : '';
         let seq = upToSeq ?? (ns ? client._seqTracker.getContiguousSeq(ns) : 0);
@@ -1237,23 +1438,33 @@ export class V2E2EECoordinator {
         seq = client._clampAckSeq('message.v2.ack', 'up_to_seq', ns, seq);
         if (!Number.isSafeInteger(seq) || seq <= 0)
             return { acked: 0 };
+        // ACK 发出前绑定当时的 inline pending；迟到响应不得结算重置后新建的 pending。
+        const ackGeneration = inlineGeneration ?? client._delivery?.pendingP2PInlineAckGeneration?.(ns) ?? null;
+        const v2SessionAtStart = client._v2Session;
+        const v2RuntimeGenerationAtStart = Number(client._v2RuntimeGeneration ?? 0);
         const raw = await client._callRawV2Rpc('message.v2.ack', { up_to_seq: seq });
         const result = isJsonObject(raw)
             ? { ...raw }
             : { result: raw };
-        const actualAckSeq = client._delivery?.resolveActualAckSeq?.(result, seq) ?? seq;
+        const actualAckSeq = requireServerWatermark
+            ? (client._delivery?.resolveForwardAckSeq?.(result, seq) ?? 0)
+            : (client._delivery?.resolveActualAckSeq?.(result, seq) ?? seq);
+        if (requireServerWatermark && actualAckSeq < seq) {
+            throw new E2EEError(`message.v2.ack server ACK watermark ${actualAckSeq} is below requested ${seq}`);
+        }
         result.ack_seq = actualAckSeq;
         result.success = true;
-        if (inlineGeneration === undefined) {
-            client._delivery?.completePendingP2PInlineAckUpTo?.(ns, actualAckSeq);
-        }
-        else {
-            client._delivery?.completePendingP2PInlineAckUpTo?.(ns, actualAckSeq, inlineGeneration);
+        if (ackGeneration !== null) {
+            client._delivery?.completePendingP2PInlineAckUpTo?.(ns, actualAckSeq, ackGeneration);
         }
-        if (client._v2Session) {
+        if (v2SessionAtStart
+            && client._v2Session === v2SessionAtStart
+            && Number(client._v2RuntimeGeneration ?? 0) === v2RuntimeGenerationAtStart) {
             try {
-                const destroyed = await client._v2Session.maybeDestroyOldSPKs(actualAckSeq);
-                if (destroyed.length > 0) {
+                const destroyed = await v2SessionAtStart.maybeDestroyOldSPKs(actualAckSeq);
+                if (client._v2Session === v2SessionAtStart
+                    && Number(client._v2RuntimeGeneration ?? 0) === v2RuntimeGenerationAtStart
+                    && destroyed.length > 0) {
                     client._clientLog.info(`V2 destroyed old SPKs after ack: ${destroyed.slice(0, 3)} (PFS)`);
                 }
             }
@@ -1334,7 +1545,7 @@ export class V2E2EECoordinator {
             throw exc;
         }
     }
-    async pullGroupV2TailInternal(params) {
+    async pullGroupV2TailInternal(params, deferPublish = false) {
         const client = this.client;
         if (params.window_mode !== 'tail')
             throw new ValidationError('window_mode must equal tail');
@@ -1356,7 +1567,7 @@ export class V2E2EECoordinator {
         const floor = Number(result.retention_floor_message_seq ?? result.retention_floor_seq ?? 0);
         const previous = client._seqTracker.getSyncState(ns);
         await this.applyTailFloor(ns, Number.isSafeInteger(floor) ? floor : 0);
-        const page = validateTailPage(result, limit);
+        const page = validateTailPage(result, afterSeq, limit);
         client._seqTracker.commitTailWindow(ns, {
             windowStartSeq: page.windowStart, headSeq: page.head, coveredThroughSeq: page.head, pageLimit: limit,
         });
@@ -1364,7 +1575,8 @@ export class V2E2EECoordinator {
         await client._saveSeqTrackerState?.();
         const decoded = [];
         for (const msg of page.messages) {
-            const plaintext = await this.decodeGroupWindowMessage(msg, groupId, groupAid, true, false, 'tail');
+            client._logMessageDebug?.('tail-raw', 'group.v2.pull', 'group.message_created', msg);
+            const plaintext = await this.decodeGroupWindowMessage(msg, groupId, groupAid, true, false, 'tail', deferPublish);
             if (plaintext)
                 decoded.push(plaintext);
         }
@@ -1411,22 +1623,52 @@ export class V2E2EECoordinator {
         let groupAid = String(opts?.groupAid ?? '').trim();
         const ns = `group:${gid}`;
         if (opts?.windowMode === 'tail') {
+            if (!opts.gateLocked) {
+                const key = pullGateKeyForClient(client, 'group.v2.pull', {
+                    group_id: gid, window_mode: 'tail', after_seq: afterSeq, limit,
+                    _group_cursor_params: opts?.cursorParams,
+                }, `${ns}|tail|after=${afterSeq}|limit=${limit}`);
+                return await client._runPullSerialized(key, () => this.pullGroupV2(gid, afterSeq, limit, {
+                    ...(opts ?? {}),
+                    gateLocked: true,
+                }), false);
+            }
             const result = await this.pullGroupV2TailInternal({
                 group_id: String(opts.wireGroupId ?? gid), group_aid: groupAid || undefined,
                 window_mode: 'tail', after_seq: afterSeq, limit,
             });
             return Array.isArray(result.messages) ? result.messages : [];
         }
+        if (!opts?.gateLocked) {
+            const key = pullGateKeyForClient(client, 'group.v2.pull', {
+                group_id: gid, after_seq: afterSeq, force: opts?.force === true, limit,
+                _group_cursor_params: opts?.cursorParams,
+            }, `${ns}|forward|after=${afterSeq}|force=${String(Boolean(opts?.force))}|limit=${limit}`);
+            return await client._runPullSerialized(key, () => this.pullGroupV2(gid, afterSeq, limit, {
+                ...(opts ?? {}),
+                gateLocked: true,
+            }), true);
+        }
         const decrypted = [];
         const wireGroupId = String(opts?.wireGroupId ?? groupId ?? '').trim() || gid;
         const cursorParams = opts?.cursorParams ?? {};
         const ownsCursor = opts?.ownsCursor !== false;
+        let pullGateKey = ownsCursor
+            ? pullGateKeyForClient(client, 'group.v2.pull', {
+                group_id: gid, after_seq: afterSeq, force: opts?.force === true, limit,
+                _group_cursor_params: cursorParams,
+            }, `${ns}|forward|after=${afterSeq}|force=${String(Boolean(opts?.force))}|limit=${limit}`)
+            : '';
         let nextAfterSeq = (opts?.explicitAfterSeq || opts?.force)
             ? afterSeq
             : (afterSeq || client._seqTracker.getContiguousSeq(ns));
+        const deferredServerCursor = ownsCursor
+            ? this.pendingForwardCursor(ns, client._seqTracker.getContiguousSeq(ns))
+            : 0;
+        const deferredForwardAck = ownsCursor ? this.pendingForwardAck(ns, client._seqTracker.getContiguousSeq(ns)) : 0;
         let pageCount = 0;
         let lastAutoAckSeq = 0;
-        let pendingAckSeq = 0;
+        let pendingAckSeq = deferredForwardAck;
         const maxPages = Math.max(1, Math.min(100, Math.trunc(Number(opts?.maxPages ?? 100) || 100)));
         while (pageCount < maxPages) {
             pageCount += 1;
@@ -1443,23 +1685,21 @@ export class V2E2EECoordinator {
                 ...(ackUpToSeq > 0 ? { ack_up_to_seq: ackUpToSeq } : {}),
             }, groupAid));
             if (ackUpToSeq > 0) {
-                if (pendingInlineGeneration !== null) {
-                    let actualAckSeq = ackUpToSeq;
-                    const ackCursor = isJsonObject(result.cursor)
-                        ? result.cursor
-                        : null;
-                    if (ackCursor && Object.prototype.hasOwnProperty.call(ackCursor, 'current_seq')) {
-                        actualAckSeq = typeof ackCursor.current_seq === 'number'
-                            && Number.isSafeInteger(ackCursor.current_seq) && ackCursor.current_seq >= 0
-                            ? ackCursor.current_seq
-                            : 0;
-                    }
-                    if (actualAckSeq > 0) {
+                const actualAckSeq = client._delivery?.resolveGroupPullAckSeq?.(result, ackUpToSeq) ?? 0;
+                if (actualAckSeq >= ackUpToSeq) {
+                    if (pendingInlineGeneration !== null) {
                         client._delivery?.completePendingGroupInlineAckUpTo?.(ns, actualAckSeq, pendingInlineGeneration);
                     }
+                    pendingAckSeq = 0;
+                    lastAutoAckSeq = Math.max(lastAutoAckSeq, ackUpToSeq);
+                    this.clearForwardAck(ns, ackUpToSeq);
+                }
+                else {
+                    client._clientLog.warn(`group.v2.pull piggyback ACK below target: group=${gid}, requested=${ackUpToSeq}, actual=${actualAckSeq}; fallback terminal ACK`);
+                    await this.confirmForwardGroupAck(gid, ackUpToSeq, groupAid);
+                    pendingAckSeq = 0;
+                    lastAutoAckSeq = Math.max(lastAutoAckSeq, ackUpToSeq);
                 }
-                pendingAckSeq = 0;
-                lastAutoAckSeq = Math.max(lastAutoAckSeq, ackUpToSeq);
             }
             const resultGroupAid = String(result.group_aid ?? result.groupAid ?? '').trim();
             if (resultGroupAid)
@@ -1467,6 +1707,10 @@ export class V2E2EECoordinator {
             const eventGroupAid = resultGroupAid || groupAid || gid;
             const pageMessages = (Array.isArray(result?.messages) ? result.messages : []);
             const messages = deduplicateForwardPageMessages(pageMessages, nextAfterSeq);
+            const cursor = isJsonObject(result.cursor) ? result.cursor : null;
+            const hasMoreField = Object.prototype.hasOwnProperty.call(result, 'has_more');
+            const hasMore = result.has_more === true;
+            const serverHead = Math.max(safeNonNegativeSeq(result.latest_message_seq) ?? 0, safeNonNegativeSeq(cursor?.latest_seq) ?? 0);
             const seqs = messages
                 .map((msg) => Number(msg.seq ?? 0))
                 .filter((seq) => Number.isFinite(seq) && seq > 0);
@@ -1475,6 +1719,8 @@ export class V2E2EECoordinator {
                 ? client._seqTracker.snapshotNamespace(ns)
                 : null;
             const pageMaxSeq = seqs.length > 0 ? Math.max(...seqs) : nextAfterSeq;
+            const deferredKeyFetches = new Map();
+            let blockedSeq = 0;
             for (const msg of messages) {
                 const seq = Number(msg.seq ?? 0);
                 if (!Number.isFinite(seq) || seq <= 0)
@@ -1510,7 +1756,7 @@ export class V2E2EECoordinator {
                             };
                             v1Msg = normalizeGroupMentionMode(v1Msg, msg, msg.envelope_json);
                             attachGatewayProximity(v1Msg, msg);
-                            await client._publishPulledMessage('group.message_created', ns, seq, v1Msg);
+                            await client._publishPulledMessage('group.message_created', ns, seq, v1Msg, false);
                             decrypted.push(v1Msg);
                             continue;
                         }
@@ -1529,7 +1775,7 @@ export class V2E2EECoordinator {
                         };
                         v1Msg = normalizeGroupMentionMode(v1Msg, msg, msg.envelope_json);
                         attachGatewayProximity(v1Msg, msg);
-                        await client._publishPulledMessage('group.message_created', ns, seq, v1Msg);
+                        await client._publishPulledMessage('group.message_created', ns, seq, v1Msg, false);
                         decrypted.push(v1Msg);
                         continue;
                     }
@@ -1540,56 +1786,87 @@ export class V2E2EECoordinator {
                     client._clientLog.debug(`group.v2.pull skipping non-V2 row group=${gid} seq=${seq} version=${String(msg.version ?? '')}`);
                     continue;
                 }
-                let plaintext = await client._decryptV2Message(msg);
+                const deferStatus = {};
+                let plaintext = await client._decryptV2Message(msg, true, true, true, true, deferStatus, true);
+                if (deferStatus.deferred) {
+                    blockedSeq = blockedSeq > 0 ? Math.min(blockedSeq, seq) : seq;
+                }
+                if (deferStatus.deferred && deferStatus.fromAid) {
+                    const key = `${deferStatus.fromAid}\u0000${deferStatus.senderDeviceId ?? ''}\u0000${deferStatus.groupId ?? ''}`;
+                    deferredKeyFetches.set(key, {
+                        fromAid: deferStatus.fromAid,
+                        senderDeviceId: deferStatus.senderDeviceId ?? '',
+                        groupId: deferStatus.groupId ?? '',
+                    });
+                }
                 if (plaintext === null)
                     continue;
                 plaintext = normalizeGroupMentionMode(plaintext, msg, msg.envelope_json);
                 plaintext.group_id = gid;
                 plaintext.group_aid = eventGroupAid;
-                await client._publishPulledMessage('group.message_created', ns, seq, plaintext);
+                await client._publishPulledMessage('group.message_created', ns, seq, plaintext, false);
                 decrypted.push(plaintext);
             }
-            const cursor = isJsonObject(result.cursor) ? result.cursor : null;
-            const cursorCurrentSeq = Number(cursor?.current_seq ?? 0);
+            const hasServerCursor = cursor !== null && Object.prototype.hasOwnProperty.call(cursor, 'current_seq');
+            const parsedCursorCurrentSeq = hasServerCursor ? safeNonNegativeSeq(cursor?.current_seq) : null;
+            const cursorCurrentSeq = parsedCursorCurrentSeq ?? 0;
             const retentionFloor = Math.max(Number(result.retention_floor_message_seq ?? result.retention_floor_seq ?? 0), Number(cursor?.retention_floor_seq ?? 0));
             const visibilityFloor = Math.max(0, Math.max(0, Number(result.earliest_available_message_seq ?? 1) - 1), Number(cursor?.join_seq ?? 0));
             const effectiveFloor = Math.max(retentionFloor, visibilityFloor);
-            const commitTarget = Math.max(pageContigBefore, Number.isFinite(effectiveFloor) ? effectiveFloor : 0, seqs.length > 0 ? pageMaxSeq : pageContigBefore);
+            const commitTarget = blockedSeq > 0 ? pageContigBefore : Math.max(pageContigBefore, Number.isFinite(effectiveFloor) ? effectiveFloor : 0, ownsCursor && pageCount === 1 ? deferredServerCursor : 0, seqs.length > 0 ? pageMaxSeq : pageContigBefore);
             let ackSeq = pageContigBefore;
             let contigAdvanced = false;
-            try {
-                if (commitTarget > pageContigBefore) {
-                    client._seqTracker.forceContiguousSeq(ns, commitTarget);
-                    if (effectiveFloor > pageContigBefore) {
-                        client._clientLog.info(`group.v2.pull floor advance: ns=${ns} contiguous=${pageContigBefore} -> effective_floor=${effectiveFloor} retention_floor=${retentionFloor} visibility_floor=${visibilityFloor}`);
-                    }
-                    if (seqs.length > 0) {
-                        client._clientLog.debug(`group.v2.pull force contiguous: group=${gid}, ns=${ns}, page_max_seq=${pageMaxSeq}, previous=${pageContigBefore}`);
+            if (ownsCursor) {
+                try {
+                    if (commitTarget > pageContigBefore) {
+                        client._seqTracker.forceContiguousSeq(ns, commitTarget);
+                        if (effectiveFloor > pageContigBefore) {
+                            client._clientLog.info(`group.v2.pull floor advance: ns=${ns} contiguous=${pageContigBefore} -> effective_floor=${effectiveFloor} retention_floor=${retentionFloor} visibility_floor=${visibilityFloor}`);
+                        }
+                        if (deferredServerCursor > pageContigBefore && pageCount === 1) {
+                            client._clientLog.info(`group.v2.pull restore local A from deferred server ACK cursor: group=${gid}, ns=${ns}, contiguous=${pageContigBefore} -> current_seq=${deferredServerCursor}`);
+                        }
+                        if (seqs.length > 0) {
+                            client._clientLog.debug(`group.v2.pull force contiguous: group=${gid}, ns=${ns}, page_max_seq=${pageMaxSeq}, previous=${pageContigBefore}`);
+                        }
                     }
-                }
-                ackSeq = client._seqTracker.getContiguousSeq(ns);
-                contigAdvanced = ackSeq !== pageContigBefore;
-                if (contigAdvanced) {
-                    await client._drainOrderedMessages(ns);
                     ackSeq = client._seqTracker.getContiguousSeq(ns);
                     contigAdvanced = ackSeq !== pageContigBefore;
-                    await client._commitSeqTrackerState(ns);
+                    if (contigAdvanced) {
+                        await client._commitSeqTrackerState(ns);
+                        if (pageCount === 1 && deferredServerCursor > 0)
+                            this.clearForwardCursor(ns, ackSeq);
+                    }
                 }
-            }
-            catch (exc) {
-                if (typeof client._seqTracker.restoreNamespaceSnapshot === 'function') {
-                    client._seqTracker.restoreNamespaceSnapshot(ns, pageTrackerSnapshot);
+                catch (exc) {
+                    if (typeof client._seqTracker.restoreNamespaceSnapshot === 'function') {
+                        client._seqTracker.restoreNamespaceSnapshot(ns, pageTrackerSnapshot);
+                    }
+                    client._clientLog.error?.(`group.v2.pull Forward commit rolled back: group=${gid} ns=${ns} target=${commitTarget} error=${formatE2EEError(exc)}`);
+                    throw exc;
                 }
-                client._clientLog.error?.(`group.v2.pull Forward commit rolled back: group=${gid} ns=${ns} target=${commitTarget} error=${formatE2EEError(exc)}`);
-                throw exc;
+                if (contigAdvanced)
+                    await client._drainOrderedMessages(ns, undefined, false, false);
             }
-            const hasServerCursor = cursor !== null && Object.prototype.hasOwnProperty.call(cursor, 'current_seq');
-            const ackNeeded = pageMessages.length > 0
+            for (const fetch of deferredKeyFetches.values()) {
+                this.scheduleSenderIKFetch(fetch.fromAid, fetch.senderDeviceId, fetch.groupId);
+            }
+            if (ownsCursor && parsedCursorCurrentSeq !== null && cursorCurrentSeq > ackSeq) {
+                this.recordForwardCursor(ns, cursorCurrentSeq, ackSeq);
+            }
+            // 无本页 cursor.current_seq 时，只有本页成功提交了比已知 cursor
+            // 更高的 A 才新增 ACK 义务；空页不得因已有本地 A 重复确认。
+            const knownServerCursorSeq = hasServerCursor
+                ? cursorCurrentSeq
+                : (ownsCursor && pageCount === 1 ? deferredServerCursor : 0);
+            const ackNeeded = blockedSeq <= 0
                 && ackSeq > 0
                 && ackSeq > lastAutoAckSeq
                 && ownsCursor
-                && (contigAdvanced || (hasServerCursor && ackSeq > cursorCurrentSeq));
+                && ((hasServerCursor && ackSeq > cursorCurrentSeq)
+                    || (contigAdvanced && ackSeq > knownServerCursorSeq));
             if (ackNeeded) {
+                this.recordForwardAck(ns, ackSeq);
                 const nextAfter = Math.max(pageMaxSeq, nextAfterSeq);
                 const canContinuePage = messages.length > 0 && nextAfter > nextAfterSeq && ownsCursor;
                 if (canContinuePage) {
@@ -1597,7 +1874,7 @@ export class V2E2EECoordinator {
                     lastAutoAckSeq = Math.max(lastAutoAckSeq, ackSeq);
                 }
                 else {
-                    await this.ackGroupV2(gid, ackSeq);
+                    await this.confirmForwardGroupAck(gid, ackSeq, groupAid);
                     lastAutoAckSeq = Math.max(lastAutoAckSeq, ackSeq);
                 }
             }
@@ -1605,11 +1882,28 @@ export class V2E2EECoordinator {
             if (!ownsCursor)
                 break;
             const rawCount = messages.length;
-            const canContinuePage = rawCount > 0 && nextAfter > nextAfterSeq;
-            const fullPage = canContinuePage && limit > 0 && rawCount >= limit;
-            const shouldContinue = canContinuePage && (fullPage || pendingAckSeq > 0);
+            if (blockedSeq > 0)
+                break;
+            const shouldContinue = shouldContinueForwardPage({
+                rawCount,
+                nextAfterSeq,
+                nextAfter,
+                limit,
+                hasMoreField,
+                hasMore,
+                serverHead,
+                pendingAckSeq,
+            });
             if (!shouldContinue)
                 break;
+            if (pullGateKey && opts?.gateLocked && client._rpcPipeline?.yieldPullGate) {
+                const nextKey = pullGateKeyForClient(client, 'group.v2.pull', {
+                    group_id: gid, after_seq: nextAfter, force: opts?.force === true, limit,
+                    _group_cursor_params: cursorParams,
+                }, `${ns}|forward|after=${nextAfter}|force=${String(Boolean(opts?.force))}|limit=${limit}`);
+                await client._rpcPipeline.yieldPullGate(pullGateKey, nextKey, true);
+                pullGateKey = nextKey;
+            }
             const tailDelayMs = v2PullTailDelayMs(rawCount, limit);
             if (tailDelayMs > 0)
                 await v2Sleep(tailDelayMs);
@@ -1618,13 +1912,34 @@ export class V2E2EECoordinator {
         if (pageCount >= maxPages) {
             client._clientLog.warn(`group.v2.pull reached max_pages=${maxPages} group=${gid} after_seq=${nextAfterSeq}`);
             if (pendingAckSeq > 0) {
-                await this.ackGroupV2(gid, pendingAckSeq);
+                await this.confirmForwardGroupAck(gid, pendingAckSeq, groupAid);
                 pendingAckSeq = 0;
             }
         }
         return decrypted;
     }
+    async confirmForwardGroupAck(groupId, upToSeq, groupAid) {
+        const ns = `group:${String(groupId ?? '').trim()}`;
+        try {
+            const result = await this.ackGroupV2ForForward(groupId, upToSeq, groupAid);
+            const actualAckSeq = this.client._delivery?.resolveForwardAckSeq?.(result, upToSeq) ?? 0;
+            if (actualAckSeq < upToSeq) {
+                throw new E2EEError(`group.v2.ack server ACK watermark ${actualAckSeq} is below requested ${upToSeq}`);
+            }
+            this.clearForwardAck(ns, upToSeq);
+        }
+        catch (exc) {
+            this.recordForwardAck(ns, upToSeq);
+            throw exc;
+        }
+    }
     async ackGroupV2(groupId, upToSeq, groupAid, inlineGeneration) {
+        return this.ackGroupV2WithConfirmation(groupId, upToSeq, groupAid, inlineGeneration, false);
+    }
+    async ackGroupV2ForForward(groupId, upToSeq, groupAid) {
+        return this.ackGroupV2WithConfirmation(groupId, upToSeq, groupAid, undefined, true);
+    }
+    async ackGroupV2WithConfirmation(groupId, upToSeq, groupAid, inlineGeneration, requireServerWatermark) {
         const client = this.client;
         const gid = typeof groupId === 'string' ? groupId.trim() : '';
         if (!gid)
@@ -1644,13 +1959,17 @@ export class V2E2EECoordinator {
         seq = client._clampAckSeq('group.v2.ack', 'up_to_seq', ns, seq);
         if (!Number.isSafeInteger(seq) || seq <= 0)
             return { acked: 0 };
+        // 与 P2P 一致，必须将 ACK 响应限定到请求开始时对应的 inline generation。
+        const ackGeneration = inlineGeneration ?? client._delivery?.pendingGroupInlineAckGeneration?.(ns) ?? null;
         const raw = await client._callRawV2Rpc('group.v2.ack', withExplicitGroupAid({ group_id: gid, up_to_seq: seq }, explicitGroupAid));
-        const actualAckSeq = client._delivery?.resolveActualAckSeq?.(raw, seq) ?? seq;
-        if (inlineGeneration === undefined) {
-            client._delivery?.completePendingGroupInlineAckUpTo?.(ns, actualAckSeq);
+        const actualAckSeq = requireServerWatermark
+            ? (client._delivery?.resolveForwardAckSeq?.(raw, seq) ?? 0)
+            : (client._delivery?.resolveActualAckSeq?.(raw, seq) ?? seq);
+        if (requireServerWatermark && actualAckSeq < seq) {
+            throw new E2EEError(`group.v2.ack server ACK watermark ${actualAckSeq} is below requested ${seq}`);
         }
-        else {
-            client._delivery?.completePendingGroupInlineAckUpTo?.(ns, actualAckSeq, inlineGeneration);
+        if (ackGeneration !== null) {
+            client._delivery?.completePendingGroupInlineAckUpTo?.(ns, actualAckSeq, ackGeneration);
         }
         return raw;
     }
@@ -1830,7 +2149,7 @@ export class V2E2EECoordinator {
             let e2ee;
             if (payload?.type === 'e2ee.group_encrypted' && String(payload.version ?? '') === 'v2') {
                 e2ee = v2E2eeMeta(payload);
-                const plain = await client._decryptV2EnvelopeForThought({ envelope: payload, fromAid });
+                const plain = await client._decryptV2EnvelopeForThought({ envelope: payload, fromAid, fetchSenderIK: true });
                 if (plain === null) {
                     decryptFailed = true;
                     client._clientLog.debug(`group.thought.get decrypt returned null: group=${groupId}, thought_id=${thoughtId}, from=${fromAid}`);
@@ -1900,7 +2219,7 @@ export class V2E2EECoordinator {
             let e2ee;
             if (payload?.type === 'e2ee.p2p_encrypted' && String(payload.version ?? '') === 'v2') {
                 e2ee = v2E2eeMeta(payload);
-                const plain = await client._decryptV2EnvelopeForThought({ envelope: payload, fromAid });
+                const plain = await client._decryptV2EnvelopeForThought({ envelope: payload, fromAid, fetchSenderIK: true });
                 if (plain === null) {
                     decryptFailed = true;
                     client._clientLog.debug(`message.thought.get decrypt returned null: thought_id=${thoughtId}, from=${fromAid}, to=${toAid}`);
@@ -1987,7 +2306,10 @@ export class V2E2EECoordinator {
         const fromAid = String(opts.fromAid || aad.from || '').trim();
         const senderDeviceId = String(aad.from_device ?? '');
         const senderCertFingerprint = String(envelope.sender_cert_fingerprint ?? '').trim().toLowerCase();
-        const senderPubDer = await this.getV2SenderPubDer(fromAid, senderDeviceId, senderCertFingerprint);
+        let senderPubDer = await this.getV2SenderPubDer(fromAid, senderDeviceId, senderCertFingerprint);
+        if (!senderPubDer && opts.fetchSenderIK) {
+            senderPubDer = await this.fetchSenderIKOnce(fromAid, senderDeviceId, groupIdForKeys, senderCertFingerprint);
+        }
         if (!senderPubDer) {
             client._clientLog.warn(`V2 thought decrypt: no sender IK for ${fromAid} device=${senderDeviceId}`);
             this.scheduleSenderIKFetch(fromAid, senderDeviceId, groupIdForKeys);