@agentunion/fastaun-browser 0.5.3 → 0.5.6

package/dist/client/v2-e2ee.js

@@ -1,15 +1,106 @@
 import { importCertPublicKeyEcdsa } from '../crypto.js';
 import { E2EEError, StateError, ValidationError } from '../errors.js';
-import { normalizeGroupId } from '../group-id.js';
 import { decryptMessage, encryptGroupMessage, encryptP2PMessage, } from '../v2/e2ee/index.js';
 import { V2Session, V2KeyStore } from '../v2/session/index.js';
 import { ConnectionState, isJsonObject } from '../types.js';
+import { normalizeGroupMentionMode } from './mention-mode.js';
 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;
+const V2_PULL_DEFAULT_PAGE_LIMIT = 50;
+const V2_PULL_MAX_PAGE_LIMIT = 50;
+const V2_SENDER_IK_SYNC_FETCH_TIMEOUT_MS = 3_000;
 const V2_SESSION_INIT_RETRY_LIMIT = 12;
 const V2_SESSION_INIT_RETRY_BASE_MS = 1000;
 const V2_SESSION_INIT_RETRY_MAX_MS = 5000;
+function strictWindowSeq(value, field, positive = false) {
+    if (!Number.isSafeInteger(value))
+        throw new ValidationError(`${field} must be an integer`);
+    const minimum = positive ? 1 : 0;
+    if (value < minimum)
+        throw new ValidationError(`${field} must be >= ${minimum}`);
+    return value;
+}
+function strictWindowLimit(value) {
+    const limit = strictWindowSeq(value, 'limit', true);
+    if (limit > V2_PULL_MAX_PAGE_LIMIT)
+        throw new ValidationError(`limit must be <= ${V2_PULL_MAX_PAGE_LIMIT}`);
+    return limit;
+}
+function deduplicateWindowMessages(value, lowerSeq, upperSeq, boundary) {
+    if (!Array.isArray(value))
+        throw new ValidationError('messages must be an array');
+    const bySeq = new Map();
+    for (const raw of value) {
+        if (!isJsonObject(raw))
+            throw new ValidationError('messages entries must be objects');
+        const row = raw;
+        const seq = strictWindowSeq(row.seq, 'messages[].seq', true);
+        if (seq < lowerSeq || seq > upperSeq)
+            throw new ValidationError(`messages[].seq is outside ${boundary}`);
+        const previous = bySeq.get(seq);
+        if (previous && JSON.stringify(previous) !== JSON.stringify(row))
+            throw new ValidationError('messages contains conflicting duplicate seq');
+        bySeq.set(seq, row);
+    }
+    return [...bySeq.entries()].sort(([a], [b]) => a - b).map(([, row]) => row);
+}
+function deduplicateForwardPageMessages(value, afterSeq) {
+    if (!Array.isArray(value))
+        return [];
+    const bySeq = new Map();
+    for (const raw of value) {
+        if (!isJsonObject(raw))
+            continue;
+        const row = raw;
+        const seq = Number(row.seq ?? 0);
+        if (!Number.isSafeInteger(seq) || 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) {
+    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');
+    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') };
+}
+function validateHistoryPage(result, beforeSeq) {
+    if (!isJsonObject(result))
+        throw new ValidationError('history response must be an object');
+    const row = result;
+    const rawStart = row.window_start_seq;
+    const rawNext = row.next_before_seq;
+    if ((rawStart === undefined) !== (rawNext === undefined))
+        throw new ValidationError('history pagination boundaries must both be present or absent');
+    let lowerSeq = 1;
+    let windowStart;
+    if (rawStart !== undefined) {
+        windowStart = strictWindowSeq(rawStart, 'window_start_seq', true);
+        const nextBefore = strictWindowSeq(rawNext, 'next_before_seq', true);
+        if (windowStart !== nextBefore || windowStart >= beforeSeq)
+            throw new ValidationError('history boundary is invalid');
+        lowerSeq = windowStart;
+    }
+    const messages = deduplicateWindowMessages(row.messages, lowerSeq, beforeSeq - 1, 'the history page');
+    if (messages.length > 0 && (windowStart === undefined || Number(messages[0].seq) !== windowStart)) {
+        throw new ValidationError('history messages require exact pagination boundaries');
+    }
+    if (messages.length === 0 && windowStart !== undefined)
+        throw new ValidationError('empty history page must not include pagination boundaries');
+    if (typeof row.has_older !== 'boolean' || (messages.length === 0 && row.has_older))
+        throw new ValidationError('has_older is invalid');
+    return messages;
+}
 const MEMBERSHIP_ACTIONS = new Set([
     'member_added',
     'member_left',
@@ -205,6 +296,12 @@ function v2WrapCapabilities() {
         per_device_wrap: true,
     };
 }
+function withExplicitGroupAid(params, groupAid) {
+    const aid = String(groupAid ?? '').trim();
+    if (aid)
+        params.group_aid = aid;
+    return params;
+}
 function applyV2WrapPolicyToTargets(targets, policy) {
     if (!policy)
         return targets;
@@ -231,6 +328,7 @@ function applyV2WrapPolicyToTargets(targets, policy) {
 export class V2E2EECoordinator {
     runtime;
     targetSetCache = new Map();
+    senderIKSyncFetches = new Map();
     v2SessionInitRetryTimer = null;
     v2SessionInitRetryBackgroundSync = false;
     v2SessionInitRetryIdentityKey = null;
@@ -253,6 +351,18 @@ export class V2E2EECoordinator {
     setBootstrapCacheEntry(key, entry) {
         this.bootstrapCache.set(key, entry);
     }
+    cacheBundledSelfDevices(bootstrap, wrapPolicy) {
+        const client = this.client;
+        if (!client._aid || !Object.prototype.hasOwnProperty.call(bootstrap, 'self_devices'))
+            return;
+        const selfDevices = (Array.isArray(bootstrap.self_devices) ? bootstrap.self_devices : []);
+        this.setBootstrapCacheEntry(client._aid, {
+            devices: selfDevices,
+            auditRecipients: [],
+            cachedAt: Date.now(),
+            wrapPolicy,
+        });
+    }
     deleteBootstrapCacheEntry(key) {
         this.bootstrapCache.delete(key);
         this.targetSetCache.delete(key);
@@ -555,6 +665,84 @@ export class V2E2EECoordinator {
     pendingSenderIKFetchKey(fromAid, senderDeviceId, groupId) {
         return `${fromAid}#${senderDeviceId}#${groupId || ''}`;
     }
+    async fetchSenderIKOnce(fromAid, senderDeviceId, groupId, certFingerprint = '') {
+        const client = this.client;
+        const peerAid = String(fromAid ?? '').trim();
+        const deviceId = String(senderDeviceId ?? '').trim();
+        const gid = String(groupId ?? '').trim();
+        const fingerprint = String(certFingerprint ?? '').trim().toLowerCase();
+        if (!peerAid)
+            return null;
+        const fetchKey = [peerAid, deviceId, gid, fingerprint].join('#');
+        const existing = this.senderIKSyncFetches.get(fetchKey);
+        if (existing)
+            return await existing;
+        const task = (async () => {
+            const started = Date.now();
+            let timer;
+            const timedOut = Symbol('sender-ik-timeout');
+            const fetch = async () => {
+                try {
+                    const bootstrap = await client.call('message.v2.bootstrap', {
+                        peer_aid: peerAid,
+                        e2ee_wrap_capabilities: v2WrapCapabilities(),
+                    });
+                    const peers = (Array.isArray(bootstrap?.peer_devices) ? bootstrap.peer_devices : []);
+                    for (const dev of peers)
+                        client._cacheV2PeerIKFromDevice(dev, peerAid);
+                }
+                catch (exc) {
+                    client._clientLog.warn(`V2 sender IK 同步 bootstrap 失败: peer=${peerAid} device=${deviceId || '-'} err=${String(formatE2EEError(exc))}`);
+                }
+                let senderPubDer = await this.getV2SenderPubDer(peerAid, deviceId, fingerprint);
+                if (senderPubDer || !gid)
+                    return senderPubDer;
+                try {
+                    const bootstrap = await client.call('group.v2.bootstrap', {
+                        group_id: gid,
+                        e2ee_wrap_capabilities: v2WrapCapabilities(),
+                    });
+                    const devices = (Array.isArray(bootstrap?.devices) ? bootstrap.devices : []);
+                    const audit = (Array.isArray(bootstrap?.audit_recipients) ? bootstrap.audit_recipients : []);
+                    for (const dev of devices)
+                        client._cacheV2PeerIKFromDevice(dev);
+                    for (const dev of audit)
+                        client._cacheV2PeerIKFromDevice(dev);
+                }
+                catch (exc) {
+                    client._clientLog.warn(`V2 sender IK 同步 group bootstrap 失败: group=${gid} peer=${peerAid} err=${String(formatE2EEError(exc))}`);
+                }
+                senderPubDer = await this.getV2SenderPubDer(peerAid, deviceId, fingerprint);
+                return senderPubDer;
+            };
+            try {
+                const result = await Promise.race([
+                    fetch(),
+                    new Promise((resolve) => {
+                        timer = setTimeout(() => resolve(timedOut), V2_SENDER_IK_SYNC_FETCH_TIMEOUT_MS);
+                    }),
+                ]);
+                if (result === timedOut) {
+                    client._clientLog.warn(`V2 sender IK 同步获取超时: peer=${peerAid} device=${deviceId || '-'} group=${gid || '<p2p>'} timeout_ms=${V2_SENDER_IK_SYNC_FETCH_TIMEOUT_MS}`);
+                    return null;
+                }
+                return result;
+            }
+            finally {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                client._clientLog.debug(`V2 sender IK 同步获取完成: peer=${peerAid} device=${deviceId || '-'} group=${gid || '<p2p>'} elapsed_ms=${Date.now() - started}`);
+            }
+        })();
+        this.senderIKSyncFetches.set(fetchKey, task);
+        try {
+            return await task;
+        }
+        finally {
+            if (this.senderIKSyncFetches.get(fetchKey) === task)
+                this.senderIKSyncFetches.delete(fetchKey);
+        }
+    }
     scheduleSenderIKPending(args) {
         const client = this.client;
         const fromAid = String(args.fromAid ?? '').trim();
@@ -627,21 +815,23 @@ export class V2E2EECoordinator {
                 }
                 catch (exc) {
                     client._clientLog.warn(`V2 sender IK pending retry raised: key=${key} err=${String(formatE2EEError(exc))}`);
+                    client._v2SenderIKPending.delete(key);
+                    continue;
                 }
-                client._v2SenderIKPending.delete(key);
                 if (plaintext === null) {
-                    client._clientLog.debug(`V2 sender IK pending retry failed: key=${key}`);
-                    client.emit('message.undecryptable', {
-                        from: entry.fromAid,
-                        sender_device_id: entry.senderDeviceId,
-                        group_id: entry.groupId || undefined,
-                        seq: Number(entry.msg.seq ?? 0),
-                        reason: 'sender_ik_retry_failed',
-                    });
+                    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';
+                    const safeEvent = this.safeUndecryptablePushEvent(entry.msg, isGroup);
+                    safeEvent._decrypt_error = 'sender IK pending retry failed';
+                    safeEvent._decrypt_stage = 'sender_ik_pending_retry';
+                    await client._publishAppEvent(eventName, safeEvent, 'pending_retry');
                     continue;
                 }
+                client._v2SenderIKPending.delete(key);
                 const seq = Number(entry.msg.seq ?? 0);
                 if (entry.groupId) {
+                    plaintext = normalizeGroupMentionMode(plaintext, entry.msg, entry.msg.envelope_json);
                     plaintext.group_id = entry.groupId;
                     await client._publishPulledMessage('group.message_created', `group:${entry.groupId}`, seq, plaintext);
                 }
@@ -709,19 +899,175 @@ export class V2E2EECoordinator {
             throw exc;
         }
     }
+    historyDecryptFailure(msg, reason) {
+        return {
+            message_id: String(msg.message_id ?? ''),
+            seq: Number(msg.seq ?? 0),
+            encrypted: true,
+            history_error: { code: 'decrypt_failed', message: reason },
+        };
+    }
+    async decodeP2PWindowMessage(msg, publish, history, source) {
+        const client = this.client;
+        const seq = strictWindowSeq(msg.seq, 'messages[].seq', true);
+        let plaintext = null;
+        if (String(msg.version ?? '') === 'v1') {
+            const legacy = isJsonObject(msg.legacy_v1)
+                ? msg.legacy_v1 : {};
+            const payload = legacy.payload;
+            const payloadType = isJsonObject(payload)
+                ? String(payload.type ?? '').trim() : '';
+            if (payload !== undefined && payload !== null && !['e2ee.encrypted', 'e2ee.group_encrypted'].includes(payloadType)) {
+                plaintext = {
+                    message_id: String(msg.message_id ?? ''), from: String(msg.from_aid ?? ''),
+                    to: String(legacy.to ?? client._aid ?? ''), seq, type: String(msg.type ?? ''),
+                    timestamp: msg.t_server, payload: payload, encrypted: false,
+                };
+                attachGatewayProximity(plaintext, msg);
+            }
+        }
+        else {
+            plaintext = source === 'inline_push'
+                ? await client._decryptV2Message(msg, false, false, false, false)
+                : await client._decryptV2Message(msg, false);
+        }
+        if (!plaintext) {
+            if (history)
+                return this.historyDecryptFailure(msg, 'message could not be decrypted');
+            client._clientLog.warn(`P2P Tail 单条消息解密失败，连续性证明仍保留: seq=${seq}`);
+            return null;
+        }
+        if (publish) {
+            const event = client._delivery.p2pAppEventForMessage(plaintext);
+            await client._publishAppEvent(event.event, event.payload, source);
+        }
+        return plaintext;
+    }
+    async decodeGroupWindowMessage(msg, groupId, groupAid, publish, history, source) {
+        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 (isJsonObject(payload)
+                && ['e2ee.encrypted', 'e2ee.group_encrypted'].includes(String(payload.type ?? ''))) {
+                if (history)
+                    return this.historyDecryptFailure(msg, 'unsupported legacy encrypted envelope');
+                client._clientLog.warn(`Group Tail 不支持的旧加密消息已跳过，连续性证明仍保留: group=${groupId}, seq=${seq}`);
+                return null;
+            }
+            plaintext = {
+                message_id: String(msg.message_id ?? ''), from: String(msg.from_aid ?? ''),
+                group_id: groupId, group_aid: groupAid, seq, type: String(msg.type ?? ''),
+                timestamp: msg.t_server, payload: payload, encrypted: false,
+            };
+            plaintext = normalizeGroupMentionMode(plaintext, msg, msg.envelope_json);
+            attachGatewayProximity(plaintext, msg);
+        }
+        else {
+            plaintext = source === 'inline_push'
+                ? await client._decryptV2Message(msg, false, false, false, false)
+                : await client._decryptV2Message(msg, false);
+            if (plaintext) {
+                // Inline Head 已绑定群身份；解密结果若声称群身份，必须与其严格一致。
+                if (source === 'inline_push' && Object.prototype.hasOwnProperty.call(plaintext, 'group_id')
+                    && (typeof plaintext.group_id !== 'string' || !plaintext.group_id || plaintext.group_id !== groupId)) {
+                    return null;
+                }
+                plaintext.group_id = groupId;
+                plaintext.group_aid = groupAid;
+                plaintext = normalizeGroupMentionMode(plaintext, msg, msg.envelope_json);
+            }
+        }
+        if (!plaintext) {
+            if (history)
+                return this.historyDecryptFailure(msg, 'message could not be decrypted');
+            client._clientLog.warn(`Group Tail 单条消息解密失败，连续性证明仍保留: group=${groupId}, seq=${seq}`);
+            return null;
+        }
+        if (publish)
+            await client._publishAppEvent('group.message_created', plaintext, source);
+        return plaintext;
+    }
+    async decodeInlineP2PMessage(msg) {
+        return await this.decodeP2PWindowMessage(msg, false, false, 'inline_push');
+    }
+    async decodeInlineGroupMessage(msg, groupId, groupAid) {
+        return await this.decodeGroupWindowMessage(msg, groupId, groupAid, false, false, 'inline_push');
+    }
+    async applyTailFloor(ns, floor) {
+        const client = this.client;
+        if (!ns || floor <= 0 || client._seqTracker.getContiguousSeq(ns) >= floor)
+            return;
+        client._seqTracker.forceContiguousSeq(ns, floor);
+        client._persistSeq(ns);
+        await client._saveSeqTrackerState?.();
+    }
+    async pullV2TailInternal(params) {
+        const client = this.client;
+        if (params.window_mode !== 'tail')
+            throw new ValidationError('window_mode must equal tail');
+        if ('ack_up_to_seq' in params || params.force === true)
+            throw new ValidationError('Tail does not accept ack_up_to_seq or force');
+        const afterSeq = strictWindowSeq(params.after_seq ?? 0, 'after_seq');
+        const limit = strictWindowLimit(params.limit ?? V2_PULL_DEFAULT_PAGE_LIMIT);
+        const ns = client._aid ? `p2p:${client._aid}` : '';
+        const result = await client._callRawV2Rpc('message.v2.pull', { window_mode: 'tail', after_seq: afterSeq, limit, _rpc_foreground: true });
+        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);
+        if (ns) {
+            client._seqTracker.commitTailWindow(ns, {
+                windowStartSeq: page.windowStart, headSeq: page.head, coveredThroughSeq: page.head, pageLimit: limit,
+            });
+            client._persistSeq(ns);
+            await client._saveSeqTrackerState?.();
+        }
+        const decoded = [];
+        for (const msg of page.messages) {
+            const plaintext = await this.decodeP2PWindowMessage(msg, true, false, 'tail');
+            if (plaintext)
+                decoded.push(plaintext);
+        }
+        const ack = ns ? client._seqTracker.getContiguousSeq(ns) : 0;
+        if (previous && ack > previous.ack)
+            await this.ackV2(ack);
+        return { ...result, messages: decoded, raw_count: page.messages.length };
+    }
+    async historyV2Internal(params) {
+        const beforeSeq = strictWindowSeq(params.before_seq, 'before_seq', true);
+        const limit = strictWindowLimit(params.limit ?? V2_PULL_DEFAULT_PAGE_LIMIT);
+        const result = await this.client._callRawV2Rpc('message.history', { before_seq: beforeSeq, limit, _rpc_foreground: true });
+        const messages = validateHistoryPage(result, beforeSeq);
+        const decoded = [];
+        for (const msg of messages) {
+            const plaintext = await this.decodeP2PWindowMessage(msg, false, true, 'history');
+            if (plaintext)
+                decoded.push(plaintext);
+        }
+        return { ...result, messages: decoded };
+    }
     async pullV2(afterSeq = 0, limit = 50, opts) {
         const client = this.client;
         await client._ensureV2SessionReady('message.pull');
         const ns = client._aid ? `p2p:${client._aid}` : '';
+        if (opts?.windowMode === 'tail') {
+            const result = await this.pullV2TailInternal({ window_mode: 'tail', after_seq: afterSeq, limit });
+            return Array.isArray(result.messages) ? result.messages : [];
+        }
         const decrypted = [];
         let nextAfterSeq = opts?.force ? afterSeq : (afterSeq || (ns ? client._seqTracker.getContiguousSeq(ns) : 0));
         let pageCount = 0;
         let lastAutoAckSeq = 0;
         let pendingAckSeq = 0;
-        const maxPages = 100;
+        const maxPages = Math.max(1, Math.min(100, Math.trunc(Number(opts?.maxPages ?? 100) || 100)));
         while (pageCount < maxPages) {
             pageCount += 1;
             const ackUpToSeq = pendingAckSeq;
+            const pendingInlineGeneration = ackUpToSeq > 0
+                ? client._delivery?.pendingP2PInlineAckGeneration?.(ns) ?? null
+                : null;
             const result = await client._callRawV2Rpc('message.v2.pull', {
                 after_seq: nextAfterSeq,
                 limit,
@@ -729,23 +1075,32 @@ 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) {
+                        client._delivery?.completePendingP2PInlineAckUpTo?.(ns, actualAckSeq, pendingInlineGeneration);
+                    }
+                }
                 pendingAckSeq = 0;
                 lastAutoAckSeq = Math.max(lastAutoAckSeq, ackUpToSeq);
             }
             const pageMessages = (Array.isArray(result?.messages) ? result.messages : []);
-            const messages = pageMessages.filter((msg) => {
-                const seq = Number(msg.seq ?? 0);
-                return Number.isFinite(seq) && seq > nextAfterSeq;
-            }).sort((a, b) => Number(a.seq ?? 0) - Number(b.seq ?? 0));
+            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 seqs = messages
                 .map((msg) => Number(msg.seq ?? 0))
                 .filter((seq) => Number.isFinite(seq) && seq > 0);
             const pageContigBefore = ns ? client._seqTracker.getContiguousSeq(ns) : 0;
+            const pageTrackerSnapshot = ns && typeof client._seqTracker.snapshotNamespace === 'function'
+                ? client._seqTracker.snapshotNamespace(ns)
+                : null;
             const pageMaxSeq = seqs.length > 0 ? Math.max(...seqs) : nextAfterSeq;
-            if (ns && seqs.length > 0) {
-                client._seqTracker.forceContiguousSeq(ns, pageMaxSeq);
-            }
             for (const msg of messages) {
                 const seq = Number(msg.seq ?? 0);
                 if (!Number.isFinite(seq) || seq <= 0)
@@ -804,19 +1159,36 @@ export class V2E2EECoordinator {
             }
             const hasServerAckSeq = Object.prototype.hasOwnProperty.call(result, 'server_ack_seq');
             const serverAckSeq = Number(result.server_ack_seq ?? 0);
-            if (ns && Number.isFinite(serverAckSeq) && serverAckSeq > 0) {
-                const contig = client._seqTracker.getContiguousSeq(ns);
-                if (contig < serverAckSeq) {
-                    client._clientLog.info(`message.v2.pull retention-floor advance: ns=${ns} contiguous=${contig} -> server_ack_seq=${serverAckSeq}`);
-                    client._seqTracker.forceContiguousSeq(ns, serverAckSeq);
-                }
-            }
+            const retentionFloor = Math.max(0, Number(result.retention_floor_seq ?? 0));
             if (ns) {
-                const ackSeq = client._seqTracker.getContiguousSeq(ns);
-                const contigAdvanced = ackSeq !== pageContigBefore;
-                if (contigAdvanced) {
-                    await client._drainOrderedMessages(ns);
-                    client._persistSeq(ns);
+                const commitTarget = Math.max(pageContigBefore, Number.isFinite(retentionFloor) ? retentionFloor : 0, seqs.length > 0 ? pageMaxSeq : pageContigBefore);
+                let ackSeq = pageContigBefore;
+                let contigAdvanced = false;
+                try {
+                    if (commitTarget > pageContigBefore) {
+                        client._seqTracker.forceContiguousSeq(ns, commitTarget);
+                        if (retentionFloor > pageContigBefore) {
+                            client._clientLog.info(`message.v2.pull retention-floor advance: ns=${ns} contiguous=${pageContigBefore} -> retention_floor_seq=${retentionFloor}`);
+                        }
+                        if (seqs.length > 0) {
+                            client._clientLog.debug(`message.v2.pull force contiguous: 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);
+                    }
+                }
+                catch (exc) {
+                    if (typeof client._seqTracker.restoreNamespaceSnapshot === 'function') {
+                        client._seqTracker.restoreNamespaceSnapshot(ns, pageTrackerSnapshot);
+                    }
+                    client._clientLog.error?.(`message.v2.pull Forward commit rolled back: ns=${ns} target=${commitTarget} error=${formatE2EEError(exc)}`);
+                    throw exc;
                 }
                 const ackNeeded = pageMessages.length > 0
                     && ackSeq > 0
@@ -856,30 +1228,28 @@ export class V2E2EECoordinator {
         }
         return decrypted;
     }
-    async ackV2(upToSeq) {
+    async ackV2(upToSeq, inlineGeneration) {
         const client = this.client;
         const ns = client._aid ? `p2p:${client._aid}` : '';
         let seq = upToSeq ?? (ns ? client._seqTracker.getContiguousSeq(ns) : 0);
-        if (seq <= 0)
+        if (typeof seq !== 'number' || !Number.isSafeInteger(seq) || seq <= 0)
             return { acked: 0 };
         seq = client._clampAckSeq('message.v2.ack', 'up_to_seq', ns, seq);
+        if (!Number.isSafeInteger(seq) || seq <= 0)
+            return { acked: 0 };
         const raw = await client._callRawV2Rpc('message.v2.ack', { up_to_seq: seq });
         const result = isJsonObject(raw)
             ? { ...raw }
             : { result: raw };
-        let actualAckSeq = seq;
-        if ('effective_ack_seq' in result)
-            actualAckSeq = Number(result.effective_ack_seq ?? 0);
-        else if ('ack_seq' in result)
-            actualAckSeq = Number(result.ack_seq ?? 0);
-        else if ('cursor' in result)
-            actualAckSeq = Number(result.cursor ?? 0);
-        if (!Number.isFinite(actualAckSeq))
-            actualAckSeq = seq;
+        const actualAckSeq = client._delivery?.resolveActualAckSeq?.(result, seq) ?? seq;
         result.ack_seq = actualAckSeq;
         result.success = true;
-        if (Number(result.acked ?? 0) === 0)
-            result.acked = actualAckSeq;
+        if (inlineGeneration === undefined) {
+            client._delivery?.completePendingP2PInlineAckUpTo?.(ns, actualAckSeq);
+        }
+        else {
+            client._delivery?.completePendingP2PInlineAckUpTo?.(ns, actualAckSeq, inlineGeneration);
+        }
         if (client._v2Session) {
             try {
                 const destroyed = await client._v2Session.maybeDestroyOldSPKs(actualAckSeq);
@@ -896,9 +1266,10 @@ export class V2E2EECoordinator {
     async sendGroupV2(groupId, payload, opts) {
         const client = this.client;
         await client._ensureV2SessionReady('group.send', 'V2 session not initialized; encrypted group.send requires V2 (V1 E2EE removed)');
-        const gid = normalizeGroupId(groupId) || String(groupId ?? '').trim();
+        const gid = String(groupId ?? '').trim();
         if (!gid)
             throw new ValidationError("group.send requires 'group_id'");
+        const groupAid = String(opts?.groupAid ?? '').trim();
         if (!isJsonObject(payload))
             throw new ValidationError('group.send payload must be a dict for V2 encryption');
         const attempt = async (useCache) => {
@@ -911,10 +1282,10 @@ export class V2E2EECoordinator {
                 context: opts?.context,
                 useCache,
             });
-            return client.call('group.v2.send', {
+            return client.call('group.v2.send', withExplicitGroupAid({
                 group_id: gid,
                 envelope,
-            });
+            }, groupAid));
         };
         try {
             const result = await attempt(true);
@@ -927,14 +1298,14 @@ export class V2E2EECoordinator {
                     await client._saveSeqTrackerState();
                 }
             }
-            return client._delivery.attachSendResultEnvelope('group.send', {
+            return client._delivery.attachSendResultEnvelope('group.send', withExplicitGroupAid({
                 group_id: gid,
                 payload,
                 message_id: opts?.messageId,
                 timestamp: opts?.timestamp,
                 protected_headers: opts?.protectedHeaders,
                 context: opts?.context,
-            }, result, true);
+            }, groupAid), result, true);
         }
         catch (exc) {
             const excCode = exc?.code;
@@ -951,65 +1322,159 @@ export class V2E2EECoordinator {
                         await client._saveSeqTrackerState();
                     }
                 }
-                return client._delivery.attachSendResultEnvelope('group.send', {
+                return client._delivery.attachSendResultEnvelope('group.send', withExplicitGroupAid({
                     group_id: gid,
                     payload,
                     message_id: opts?.messageId,
                     timestamp: opts?.timestamp,
                     protected_headers: opts?.protectedHeaders,
                     context: opts?.context,
-                }, result, true);
+                }, groupAid), result, true);
             }
             throw exc;
         }
     }
+    async pullGroupV2TailInternal(params) {
+        const client = this.client;
+        if (params.window_mode !== 'tail')
+            throw new ValidationError('window_mode must equal tail');
+        if ('ack_up_to_seq' in params || params.force === true)
+            throw new ValidationError('Tail does not accept ack_up_to_seq or force');
+        const groupId = String(params.group_id ?? params.group_aid ?? '').trim();
+        if (!groupId)
+            throw new ValidationError('group_id is required');
+        let groupAid = String(params.group_aid ?? '').trim();
+        const afterSeq = strictWindowSeq(params.after_seq ?? 0, 'after_seq');
+        const limit = strictWindowLimit(params.limit ?? V2_PULL_DEFAULT_PAGE_LIMIT);
+        const ns = `group:${groupId}`;
+        const result = await client._callRawV2Rpc('group.v2.pull', withExplicitGroupAid({
+            group_id: groupId, window_mode: 'tail', after_seq: afterSeq, limit, _rpc_foreground: true,
+        }, groupAid));
+        const resultAid = String(result.group_aid ?? result.groupAid ?? '').trim();
+        if (resultAid)
+            groupAid = resultAid;
+        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);
+        client._seqTracker.commitTailWindow(ns, {
+            windowStartSeq: page.windowStart, headSeq: page.head, coveredThroughSeq: page.head, pageLimit: limit,
+        });
+        client._persistSeq(ns);
+        await client._saveSeqTrackerState?.();
+        const decoded = [];
+        for (const msg of page.messages) {
+            const plaintext = await this.decodeGroupWindowMessage(msg, groupId, groupAid, true, false, 'tail');
+            if (plaintext)
+                decoded.push(plaintext);
+        }
+        const ack = client._seqTracker.getContiguousSeq(ns);
+        if (ack > previous.ack)
+            await this.ackGroupV2(groupId, ack, groupAid);
+        return { ...result, messages: decoded, raw_count: page.messages.length };
+    }
+    async historyGroupV2Internal(params) {
+        const groupId = String(params.group_id ?? params.group_aid ?? '').trim();
+        if (!groupId)
+            throw new ValidationError('group_id is required');
+        let groupAid = String(params.group_aid ?? '').trim();
+        const beforeSeq = strictWindowSeq(params.before_seq, 'before_seq', true);
+        const limit = strictWindowLimit(params.limit ?? V2_PULL_DEFAULT_PAGE_LIMIT);
+        const result = await this.client._callRawV2Rpc('group.history', withExplicitGroupAid({
+            group_id: groupId, before_seq: beforeSeq, limit, _rpc_foreground: true,
+        }, groupAid));
+        const resultAid = String(result.group_aid ?? result.groupAid ?? '').trim();
+        if (resultAid)
+            groupAid = resultAid;
+        const messages = validateHistoryPage(result, beforeSeq);
+        const decoded = [];
+        for (const msg of messages) {
+            const plaintext = await this.decodeGroupWindowMessage(msg, groupId, groupAid, false, true, 'history');
+            if (plaintext)
+                decoded.push(plaintext);
+        }
+        return { ...result, messages: decoded };
+    }
     async pullGroupV2Internal(params) {
-        await this.pullGroupV2(params.group_id, params.after_seq, params.limit);
+        await this.pullGroupV2(params.group_id, params.after_seq, params.limit, {
+            gateLocked: true,
+            explicitAfterSeq: true,
+            force: params.force === true,
+        });
     }
     async pullGroupV2(groupId, afterSeq = 0, limit = 50, opts) {
         const client = this.client;
         await client._ensureV2SessionReady('group.pull');
-        const gid = normalizeGroupId(groupId) || String(groupId ?? '').trim();
+        const gid = String(groupId ?? '').trim();
         if (!gid)
             throw new ValidationError('group.pull requires group_id');
+        let groupAid = String(opts?.groupAid ?? '').trim();
         const ns = `group:${gid}`;
+        if (opts?.windowMode === 'tail') {
+            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 : [];
+        }
         const decrypted = [];
         const wireGroupId = String(opts?.wireGroupId ?? groupId ?? '').trim() || gid;
         const cursorParams = opts?.cursorParams ?? {};
         const ownsCursor = opts?.ownsCursor !== false;
-        let nextAfterSeq = opts?.explicitAfterSeq ? afterSeq : (afterSeq || client._seqTracker.getContiguousSeq(ns));
+        let nextAfterSeq = (opts?.explicitAfterSeq || opts?.force)
+            ? afterSeq
+            : (afterSeq || client._seqTracker.getContiguousSeq(ns));
         let pageCount = 0;
         let lastAutoAckSeq = 0;
         let pendingAckSeq = 0;
-        const maxPages = 100;
+        const maxPages = Math.max(1, Math.min(100, Math.trunc(Number(opts?.maxPages ?? 100) || 100)));
         while (pageCount < maxPages) {
             pageCount += 1;
             const ackUpToSeq = ownsCursor ? pendingAckSeq : 0;
-            const result = await client._callRawV2Rpc('group.v2.pull', {
+            const pendingInlineGeneration = ackUpToSeq > 0
+                ? client._delivery?.pendingGroupInlineAckGeneration?.(ns) ?? null
+                : null;
+            const result = await client._callRawV2Rpc('group.v2.pull', withExplicitGroupAid({
                 group_id: wireGroupId,
-                group_aid: gid,
                 after_seq: nextAfterSeq,
                 limit,
                 ...cursorParams,
+                ...(opts?.force ? { force: true } : {}),
                 ...(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) {
+                        client._delivery?.completePendingGroupInlineAckUpTo?.(ns, actualAckSeq, pendingInlineGeneration);
+                    }
+                }
                 pendingAckSeq = 0;
                 lastAutoAckSeq = Math.max(lastAutoAckSeq, ackUpToSeq);
             }
+            const resultGroupAid = String(result.group_aid ?? result.groupAid ?? '').trim();
+            if (resultGroupAid)
+                groupAid = resultGroupAid;
+            const eventGroupAid = resultGroupAid || groupAid || gid;
             const pageMessages = (Array.isArray(result?.messages) ? result.messages : []);
-            const messages = pageMessages.filter((msg) => {
-                const seq = Number(msg.seq ?? 0);
-                return Number.isFinite(seq) && seq > nextAfterSeq;
-            }).sort((a, b) => Number(a.seq ?? 0) - Number(b.seq ?? 0));
+            const messages = deduplicateForwardPageMessages(pageMessages, nextAfterSeq);
             const seqs = messages
                 .map((msg) => Number(msg.seq ?? 0))
                 .filter((seq) => Number.isFinite(seq) && seq > 0);
             const pageContigBefore = client._seqTracker.getContiguousSeq(ns);
+            const pageTrackerSnapshot = typeof client._seqTracker.snapshotNamespace === 'function'
+                ? client._seqTracker.snapshotNamespace(ns)
+                : null;
             const pageMaxSeq = seqs.length > 0 ? Math.max(...seqs) : nextAfterSeq;
-            if (seqs.length > 0) {
-                client._seqTracker.forceContiguousSeq(ns, pageMaxSeq);
-            }
             for (const msg of messages) {
                 const seq = Number(msg.seq ?? 0);
                 if (!Number.isFinite(seq) || seq <= 0)
@@ -1020,7 +1485,11 @@ export class V2E2EECoordinator {
                     const payloadObj = isJsonObject(payload) ? payload : null;
                     // 群撤回 tombstone（占位 / 通知）：归一化为 group.message_recalled 事件，仍占 seq。
                     if (client._delivery.recallEventFromGroupMessage(msg)) {
-                        await client._delivery.publishGroupRecallTombstone(gid, seq, msg);
+                        await client._delivery.publishGroupRecallTombstone(gid, seq, {
+                            ...msg,
+                            group_id: gid,
+                            group_aid: eventGroupAid,
+                        });
                         client._markPublishedSeq(ns, seq);
                         client._clientLog.debug(`group.v2.pull recall tombstone delivered: group=${gid}, seq=${seq}`);
                         continue;
@@ -1028,16 +1497,18 @@ export class V2E2EECoordinator {
                     if (payloadObj) {
                         const payloadType = String(payloadObj.type ?? '').trim();
                         if (payloadType !== 'e2ee.encrypted' && payloadType !== 'e2ee.group_encrypted') {
-                            const v1Msg = {
+                            let v1Msg = {
                                 message_id: String(msg.message_id ?? ''),
                                 from: String(msg.from_aid ?? ''),
                                 group_id: gid,
+                                group_aid: eventGroupAid,
                                 seq: msg.seq,
                                 type: String(msg.type ?? ''),
                                 timestamp: msg.t_server,
                                 payload,
                                 encrypted: false,
                             };
+                            v1Msg = normalizeGroupMentionMode(v1Msg, msg, msg.envelope_json);
                             attachGatewayProximity(v1Msg, msg);
                             await client._publishPulledMessage('group.message_created', ns, seq, v1Msg);
                             decrypted.push(v1Msg);
@@ -1045,16 +1516,18 @@ export class V2E2EECoordinator {
                         }
                     }
                     else if (payload !== undefined && payload !== null) {
-                        const v1Msg = {
+                        let v1Msg = {
                             message_id: String(msg.message_id ?? ''),
                             from: String(msg.from_aid ?? ''),
                             group_id: gid,
+                            group_aid: eventGroupAid,
                             seq: msg.seq,
                             type: String(msg.type ?? ''),
                             timestamp: msg.t_server,
                             payload,
                             encrypted: false,
                         };
+                        v1Msg = normalizeGroupMentionMode(v1Msg, msg, msg.envelope_json);
                         attachGatewayProximity(v1Msg, msg);
                         await client._publishPulledMessage('group.message_created', ns, seq, v1Msg);
                         decrypted.push(v1Msg);
@@ -1067,27 +1540,48 @@ export class V2E2EECoordinator {
                     client._clientLog.debug(`group.v2.pull skipping non-V2 row group=${gid} seq=${seq} version=${String(msg.version ?? '')}`);
                     continue;
                 }
-                const plaintext = await client._decryptV2Message(msg);
+                let plaintext = await client._decryptV2Message(msg);
                 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);
                 decrypted.push(plaintext);
             }
             const cursor = isJsonObject(result.cursor) ? result.cursor : null;
             const cursorCurrentSeq = Number(cursor?.current_seq ?? 0);
-            if (Number.isFinite(cursorCurrentSeq) && cursorCurrentSeq > 0) {
-                const contig = client._seqTracker.getContiguousSeq(ns);
-                if (contig < cursorCurrentSeq) {
-                    client._clientLog.info(`group.v2.pull retention-floor advance: ns=${ns} contiguous=${contig} -> cursor.current_seq=${cursorCurrentSeq}`);
-                    client._seqTracker.forceContiguousSeq(ns, cursorCurrentSeq);
+            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);
+            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}`);
+                    }
+                }
+                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);
                 }
             }
-            const ackSeq = client._seqTracker.getContiguousSeq(ns);
-            const contigAdvanced = ackSeq !== pageContigBefore;
-            if (contigAdvanced) {
-                await client._drainOrderedMessages(ns);
-                client._persistSeq(ns);
+            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;
             }
             const hasServerCursor = cursor !== null && Object.prototype.hasOwnProperty.call(cursor, 'current_seq');
             const ackNeeded = pageMessages.length > 0
@@ -1130,17 +1624,35 @@ export class V2E2EECoordinator {
         }
         return decrypted;
     }
-    async ackGroupV2(groupId, upToSeq) {
+    async ackGroupV2(groupId, upToSeq, groupAid, inlineGeneration) {
         const client = this.client;
-        const gid = normalizeGroupId(groupId) || String(groupId ?? '').trim();
+        const gid = typeof groupId === 'string' ? groupId.trim() : '';
         if (!gid)
             throw new ValidationError('group.ack_messages requires group_id');
-        const ns = `group:${gid}`;
-        let seq = Number(upToSeq ?? client._seqTracker.getContiguousSeq(ns));
-        if (!Number.isFinite(seq) || seq <= 0)
+        if (groupAid !== undefined && typeof groupAid !== 'string') {
+            throw new ValidationError('group.ack_messages group_aid must be a string');
+        }
+        const explicitGroupAid = groupAid?.trim() ?? '';
+        const wireNs = `group:${gid}`;
+        const ns = client._delivery?.resolvePendingGroupInlineAckNamespace?.(wireNs) ?? wireNs;
+        let seq = upToSeq ?? client._seqTracker.getContiguousSeq(ns);
+        if (typeof upToSeq !== 'undefined' && (typeof upToSeq !== 'number' || !Number.isSafeInteger(upToSeq))) {
+            return { acked: 0 };
+        }
+        if (!Number.isSafeInteger(seq) || seq <= 0)
             return { acked: 0 };
         seq = client._clampAckSeq('group.v2.ack', 'up_to_seq', ns, seq);
-        return client._callRawV2Rpc('group.v2.ack', { group_id: gid, group_aid: gid, up_to_seq: seq });
+        if (!Number.isSafeInteger(seq) || seq <= 0)
+            return { acked: 0 };
+        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);
+        }
+        else {
+            client._delivery?.completePendingGroupInlineAckUpTo?.(ns, actualAckSeq, inlineGeneration);
+        }
+        return raw;
     }
     async putMessageThoughtEncryptedV2(params) {
         const client = this.client;
@@ -1543,7 +2055,7 @@ export class V2E2EECoordinator {
         return String(envelope.version ?? '').trim().toLowerCase() === 'v2' && payloadType.startsWith('e2ee.');
     }
     safeUndecryptablePushEvent(msg, group) {
-        const event = {
+        let event = {
             message_id: msg.message_id ?? null,
             from: msg.from ?? null,
             seq: msg.seq ?? null,
@@ -1567,6 +2079,10 @@ export class V2E2EECoordinator {
                 attachV2EnvelopeMetadata(event, v2E2eeMeta(envelope));
             }
         }
+        if (group) {
+            const modeSource = envelope ? { ...msg, envelope } : msg;
+            event = normalizeGroupMentionMode(event, modeSource);
+        }
         return event;
     }
     async decryptEncryptedPushPayload(msg, group) {
@@ -1580,7 +2096,7 @@ export class V2E2EECoordinator {
         if (!plaintext)
             return null;
         const e2eeMeta = v2E2eeMeta(envelope);
-        const result = {
+        let result = {
             message_id: String(msg.message_id ?? ''),
             from: fromAid,
             seq: msg.seq ?? null,
@@ -1599,6 +2115,7 @@ export class V2E2EECoordinator {
         attachGatewayProximity(result, msg);
         if (group) {
             result.group_id = msg.group_id ?? aad.group_id ?? envelope.group_id ?? null;
+            result = normalizeGroupMentionMode(result, msg, envelope);
         }
         else {
             result.to = msg.to ?? client._aid ?? '';
@@ -1659,6 +2176,7 @@ export class V2E2EECoordinator {
             peerDevices = (Array.isArray(bs?.peer_devices) ? bs.peer_devices : []);
             auditRaw = (Array.isArray(bs?.audit_recipients) ? bs.audit_recipients : []);
             wrapPolicy = normalizeV2WrapPolicy(bs?.e2ee_wrap_policy);
+            this.cacheBundledSelfDevices(bs, wrapPolicy);
             if (peerDevices.length > 0) {
                 this.setBootstrapCacheEntry(to, {
                     devices: peerDevices,
@@ -1758,8 +2276,7 @@ export class V2E2EECoordinator {
             throw new StateError('V2 session not initialized');
         }
         const session = client._v2Session;
-        const rawGroupId = String(opts.groupId ?? '').trim();
-        const groupId = normalizeGroupId(rawGroupId) || rawGroupId;
+        const groupId = String(opts.groupId ?? '').trim();
         if (!groupId)
             throw new ValidationError("group.send requires 'group_id'");
         const useCache = opts.useCache !== false;
@@ -1770,15 +2287,7 @@ export class V2E2EECoordinator {
         let auditRecipientsRaw = [];
         let wrapPolicy;
         let usedCachedBootstrap = false;
-        let cached = useCache ? this.getBootstrapCacheEntry(cacheKey) : undefined;
-        if (!cached && useCache && rawGroupId && rawGroupId !== groupId) {
-            const legacyCacheKey = `group:${rawGroupId}`;
-            cached = this.getBootstrapCacheEntry(legacyCacheKey);
-            if (cached) {
-                this.setBootstrapCacheEntry(cacheKey, cached);
-                this.deleteBootstrapCacheEntry(legacyCacheKey);
-            }
-        }
+        const cached = useCache ? this.getBootstrapCacheEntry(cacheKey) : undefined;
         if (cached && (Date.now() - Number(cached.cachedAt ?? 0)) < V2_BOOTSTRAP_TTL_MS) {
             allDevices = (cached.devices ?? []);
             epoch = Number(cached.epoch ?? 0) || 0;