@agentunion/fastaun 0.5.3 → 0.5.6

package/dist/client/v2-e2ee.js

@@ -1,12 +1,114 @@
 import * as crypto from 'node:crypto';
-import { normalizeGroupId } from '../group-id.js';
 import { E2EEError, StateError, ValidationError } from '../errors.js';
 import { decryptMessage, encryptGroupMessage, encryptP2PMessage, } from '../v2/e2ee/index.js';
 import { V2Session } from '../v2/session/index.js';
 import { 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;
+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)
+        throw new ValidationError('window_start_seq must not exceed head_seq');
+    if (covered !== head)
+        throw new ValidationError('covered_through_seq must equal head_seq');
+    if (head - windowStart + 1 > pageLimit)
+        throw new ValidationError('tail proven window exceeds limit');
+    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)
+            throw new ValidationError('next_before_seq must equal window_start_seq');
+        if (windowStart >= beforeSeq)
+            throw new ValidationError('history boundary must be less than before_seq');
+        lowerSeq = windowStart;
+    }
+    const messages = deduplicateWindowMessages(row.messages, lowerSeq, beforeSeq - 1, 'the history page');
+    if (messages.length > 0) {
+        if (windowStart === undefined)
+            throw new ValidationError('history messages require pagination boundaries');
+        if (Number(messages[0].seq) !== windowStart)
+            throw new ValidationError('window_start_seq must equal the first history message seq');
+    }
+    else if (windowStart !== undefined) {
+        throw new ValidationError('empty history page must not include pagination boundaries');
+    }
+    if (typeof row.has_older !== 'boolean')
+        throw new ValidationError('has_older must be a boolean');
+    if (messages.length === 0 && row.has_older)
+        throw new ValidationError('empty history page cannot report has_older');
+    return messages;
+}
 const MEMBERSHIP_ACTIONS = new Set([
     'member_added',
     'member_left',
@@ -121,6 +223,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.explicit)
         return targets;
@@ -148,6 +256,7 @@ export class V2E2EECoordinator {
     runtime;
     _initSessionPromise = null;
     targetSetCache = new Map();
+    senderIKSyncFetches = new Map();
     constructor(runtime) {
         this.runtime = runtime;
     }
@@ -167,6 +276,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);
@@ -375,6 +496,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=${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=${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();
@@ -450,21 +649,23 @@ export class V2E2EECoordinator {
                 }
                 catch (exc) {
                     client._clientLog.warn(`V2 sender IK pending retry raised: key=${key} err=${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', {
-                        messageId: entry.msg.message_id ?? entry.msg.id ?? key,
-                        error: 'V2 sender IK pending retry failed after IK resolution',
-                        fromAid,
-                        senderDeviceId,
-                        groupId: entry.groupId ?? null,
-                    });
+                    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);
                 }
@@ -510,6 +711,7 @@ export class V2E2EECoordinator {
             wrapPolicy = normalizeV2WrapPolicy(bs.e2ee_wrap_policy);
             peerDevices = (Array.isArray(bs?.peer_devices) ? bs.peer_devices : []);
             auditRaw = (Array.isArray(bs?.audit_recipients) ? bs.audit_recipients : []);
+            this.cacheBundledSelfDevices(bs, wrapPolicy);
             client._clientLog.debug(`message.v2.bootstrap fetched: to=${to}, devices=${peerDevices.length}, audit=${auditRaw.length}`);
             if (peerDevices.length > 0) {
                 this.setBootstrapCacheEntry(to, {
@@ -694,26 +896,187 @@ 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 = await client._decryptV2Message(msg, false, !history);
+        }
+        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 = await client._decryptV2Message(msg, false, !history);
+            if (plaintext) {
+                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 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);
+        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);
+            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 client = this.client;
+        const beforeSeq = strictWindowSeq(params.before_seq, 'before_seq', true);
+        const limit = strictWindowLimit(params.limit ?? V2_PULL_DEFAULT_PAGE_LIMIT);
+        const result = await 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') {
+            if (!opts.gateLocked) {
+                const key = `${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) {
-            return await client._runPullSerialized(ns, async () => this.pullV2(afterSeq, limit, {
+            const key = `${ns}|forward|after=${afterSeq}|force=${String(Boolean(opts?.force))}|limit=${limit}`;
+            return await client._runPullSerialized(key, async () => this.pullV2(afterSeq, limit, {
                 ...(opts ?? {}),
                 gateLocked: true,
                 scheduleFollowup: true,
-            }));
+            }), true);
         }
         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 = opts?.skipAutoAck ? 0 : pendingAckSeq;
+            const inlineAckGeneration = ackUpToSeq > 0
+                ? client._delivery.captureP2PInlineAckGeneration()
+                : null;
             client._clientLog.debug(`message.v2.pull page request: page=${pageCount}, after_seq=${nextAfterSeq}, limit=${limit}, ack_up_to_seq=${ackUpToSeq}, ns=${ns || '<none>'}`);
             const result = await client._callRawV2Rpc('message.v2.pull', {
                 after_seq: nextAfterSeq,
@@ -722,14 +1085,14 @@ export class V2E2EECoordinator {
                 ...(ackUpToSeq > 0 ? { ack_up_to_seq: ackUpToSeq } : {}),
             });
             if (ackUpToSeq > 0) {
+                if (inlineAckGeneration !== null) {
+                    client._delivery.onP2PV2PullAckResult(result, ackUpToSeq, inlineAckGeneration);
+                }
                 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 ?? '')}`);
             for (const msg of messages) {
                 client._logMessageDebug('pull-raw', 'message.v2.pull', 'message.received', msg);
@@ -738,13 +1101,12 @@ export class V2E2EECoordinator {
                 .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;
             let pageMaxSeq = nextAfterSeq;
             if (seqs.length > 0) {
                 pageMaxSeq = Math.max(...seqs);
-                if (ns) {
-                    client._seqTracker.forceContiguousSeq(ns, pageMaxSeq);
-                    client._clientLog.debug(`message.v2.pull force contiguous: ns=${ns}, page_max_seq=${pageMaxSeq}, previous=${pageContigBefore}`);
-                }
             }
             for (const msg of messages) {
                 const seq = Number(msg.seq ?? 0);
@@ -808,19 +1170,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, undefined, true);
-                    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, undefined, true);
+                        ackSeq = client._seqTracker.getContiguousSeq(ns);
+                        contigAdvanced = ackSeq !== pageContigBefore;
+                        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
@@ -874,28 +1253,30 @@ export class V2E2EECoordinator {
             return { acked: 0 };
         }
         seq = client._clampAckSeq('message.v2.ack', 'up_to_seq', ns, seq);
+        if (seq <= 0)
+            return { acked: 0 };
+        const inlineAckGeneration = client._delivery.captureP2PInlineAckGeneration();
+        const v2SessionAtStart = client._v2Session;
+        const v2RuntimeGenerationAtStart = Number(client._v2RuntimeGeneration ?? 0);
         client._clientLog.debug(`message.v2.ack send: ns=${ns || '<none>'}, up_to_seq=${seq}`);
         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);
         result.ack_seq = actualAckSeq;
         result.success = true;
-        if (Number(result.acked ?? 0) === 0)
-            result.acked = actualAckSeq;
-        if (client._v2Session) {
+        if (inlineAckGeneration !== null) {
+            client._delivery.onP2PV2AckSucceeded(actualAckSeq, inlineAckGeneration);
+        }
+        if (v2SessionAtStart
+            && client._v2Session === v2SessionAtStart
+            && Number(client._v2RuntimeGeneration ?? 0) === v2RuntimeGenerationAtStart) {
             try {
-                const destroyed = await Promise.resolve(client._v2Session.maybeDestroyOldSPKs(actualAckSeq));
-                if (destroyed.length > 0) {
+                const destroyed = await Promise.resolve(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).join(',')} (PFS)`);
                 }
             }
@@ -909,16 +1290,17 @@ 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');
-        client._logMessageDebug('send-plaintext', 'group.send.v2', 'group.send', {
+        client._logMessageDebug('send-plaintext', 'group.send.v2', 'group.send', withExplicitGroupAid({
             group_id: gid,
             message_id: opts?.messageId ?? '',
             payload,
-        }, { payloadOverride: payload });
+        }, groupAid), { payloadOverride: payload });
         const attempt = async (useCache) => {
             client._clientLog.debug(`group.v2.send attempt: group=${gid}, use_cache=${useCache}`);
             const envelope = await client._buildV2GroupEnvelope({
@@ -930,10 +1312,10 @@ export class V2E2EECoordinator {
                 context: opts?.context,
                 useCache,
             });
-            const result = await client.call('group.v2.send', {
+            const result = await client.call('group.v2.send', withExplicitGroupAid({
                 group_id: gid,
                 envelope,
-            });
+            }, groupAid));
             client._clientLog.debug(`group.v2.send ok: group=${gid}, use_cache=${useCache}, seq=${String((isJsonObject(result) ? result.seq : '') ?? '')}`);
             return result;
         };
@@ -953,14 +1335,14 @@ export class V2E2EECoordinator {
         try {
             const result = await attempt(true);
             markSentSeq(result);
-            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 = Number(exc?.code);
@@ -969,14 +1351,14 @@ export class V2E2EECoordinator {
                 this.deleteBootstrapCacheEntry(`group:${gid}`);
                 const result = await attempt(false);
                 markSentSeq(result);
-                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;
         }
@@ -986,8 +1368,7 @@ export class V2E2EECoordinator {
         if (!client._v2Session)
             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 cacheKey = `group:${groupId}`;
@@ -998,15 +1379,7 @@ export class V2E2EECoordinator {
         let stateCommitment = { state_version: 0, state_hash: '', state_chain: '' };
         let wrapPolicy = normalizeV2WrapPolicy(undefined);
         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 ?? []);
             auditRecipientsRaw = (cached.auditRecipients ?? []);
@@ -1136,53 +1509,157 @@ export class V2E2EECoordinator {
         });
         return envelope;
     }
+    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);
+        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 client = this.client;
+        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 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, { gateLocked: true });
+        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') {
+            if (!opts.gateLocked) {
+                const key = `${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) {
-            return await client._runPullSerialized(ns, async () => this.pullGroupV2(gid, afterSeq, limit, {
+            const key = `${ns}|forward|after=${afterSeq}|force=${opts?.force === true}|limit=${limit}`;
+            return await client._runPullSerialized(key, async () => this.pullGroupV2(gid, afterSeq, limit, {
                 ...(opts ?? {}),
                 gateLocked: true,
                 scheduleFollowup: true,
-            }));
+            }), true);
         }
         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 inlineAckGeneration = ackUpToSeq > 0
+                ? client._delivery.captureGroupInlineAckGeneration()
+                : null;
             client._clientLog.debug(`group.v2.pull page request: group=${gid}, page=${pageCount}, after_seq=${nextAfterSeq}, limit=${limit}, ack_up_to_seq=${ackUpToSeq}, ns=${ns}`);
-            const result = await client._callRawV2Rpc('group.v2.pull', {
+            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 (inlineAckGeneration !== null) {
+                    client._delivery.onGroupV2PullAckResult(gid, result, ackUpToSeq, inlineAckGeneration);
+                }
                 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 cursor = isJsonObject(result.cursor) ? result.cursor : null;
             client._clientLog.debug(`group.v2.pull page response: group=${gid}, page=${pageCount}, raw_count=${messages.length}, stale_count=${Math.max(0, pageMessages.length - messages.length)}, has_more=${String(result.has_more ?? '')}, cursor_current=${String(cursor?.current_seq ?? '')}`);
             for (const msg of messages) {
@@ -1192,11 +1669,12 @@ export class V2E2EECoordinator {
                 .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;
             let pageMaxSeq = nextAfterSeq;
             if (seqs.length > 0) {
                 pageMaxSeq = Math.max(...seqs);
-                client._seqTracker.forceContiguousSeq(ns, pageMaxSeq);
-                client._clientLog.debug(`group.v2.pull force contiguous: group=${gid}, ns=${ns}, page_max_seq=${pageMaxSeq}, previous=${pageContigBefore}`);
             }
             for (const msg of messages) {
                 const seq = Number(msg.seq ?? 0);
@@ -1208,7 +1686,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;
@@ -1216,16 +1698,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);
@@ -1234,16 +1718,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);
@@ -1257,31 +1743,51 @@ 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) {
                     client._clientLog.debug(`group.v2.pull decrypt returned null: group=${gid}, seq=${seq}`);
                     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);
                 client._logMessageDebug('decrypt-ok', 'group.v2.pull', 'group.message_created', plaintext);
             }
             const cursorCurrentSeq = Number(cursor?.current_seq ?? 0);
             const hasServerCursor = cursor !== null && Object.prototype.hasOwnProperty.call(cursor, 'current_seq');
-            const retentionFloor = Math.max(client._pullRetentionFloor(result, 'retention_floor_message_seq', 'retention_floor_message_seq'), Number.isFinite(cursorCurrentSeq) ? cursorCurrentSeq : 0);
-            if (retentionFloor > 0) {
-                const contig = client._seqTracker.getContiguousSeq(ns);
-                if (contig < retentionFloor) {
-                    client._clientLog.info(`group.v2.pull retention-floor advance: ns=${ns} contiguous=${contig} -> retention_floor=${retentionFloor}`);
-                    client._seqTracker.forceContiguousSeq(ns, retentionFloor);
+            const retentionFloor = Math.max(client._pullRetentionFloor(result, 'retention_floor_message_seq', 'retention_floor_message_seq'));
+            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, effectiveFloor, 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, undefined, true);
+                    ackSeq = client._seqTracker.getContiguousSeq(ns);
+                    contigAdvanced = ackSeq !== pageContigBefore;
+                    client._commitSeqTrackerState(ns);
                 }
             }
-            const ackSeq = client._seqTracker.getContiguousSeq(ns);
-            const contigAdvanced = ackSeq !== pageContigBefore;
-            if (contigAdvanced) {
-                await client._drainOrderedMessages(ns, undefined, true);
-                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 ackNeeded = pageMessages.length > 0
                 && ackSeq > 0
@@ -1327,21 +1833,30 @@ export class V2E2EECoordinator {
         client._clientLog.debug(`group.v2.pull done: group=${gid}, requested_after_seq=${afterSeq}, pages=${pageCount}, decrypted=${decrypted.length}, ns=${ns}`);
         return decrypted;
     }
-    async ackGroupV2(groupId, upToSeq) {
+    async ackGroupV2(groupId, upToSeq, groupAid) {
         const client = this.client;
-        const gid = normalizeGroupId(groupId) || String(groupId ?? '').trim();
+        const gid = String(groupId ?? '').trim();
         if (!gid)
             throw new ValidationError('group.ack_messages requires group_id');
-        const ns = `group:${gid}`;
+        const explicitGroupAid = String(groupAid ?? '').trim();
+        const wireNs = `group:${gid}`;
+        const ns = client._delivery.resolvePendingGroupInlineAckNamespace?.(wireNs) ?? wireNs;
         let seq = Number(upToSeq ?? client._seqTracker.getContiguousSeq(ns));
         if (!Number.isFinite(seq) || seq <= 0) {
             client._clientLog.debug(`group.v2.ack skipped: group=${gid}, ns=${ns}, up_to_seq=${String(upToSeq ?? '')}`);
             return { acked: 0 };
         }
         seq = client._clampAckSeq('group.v2.ack', 'up_to_seq', ns, seq);
+        if (seq <= 0)
+            return { acked: 0 };
+        const inlineAckGeneration = client._delivery.captureGroupInlineAckGeneration();
         client._clientLog.debug(`group.v2.ack send: group=${gid}, ns=${ns}, up_to_seq=${seq}`);
-        const result = await client._callRawV2Rpc('group.v2.ack', { group_id: gid, group_aid: gid, up_to_seq: seq });
-        client._clientLog.debug(`group.v2.ack ok: group=${gid}, ns=${ns}, requested=${seq}, result=${client._debugJson(result)}`);
+        const result = await client._callRawV2Rpc('group.v2.ack', withExplicitGroupAid({ group_id: gid, up_to_seq: seq }, explicitGroupAid));
+        const actualAckSeq = client._delivery.resolveActualAckSeq(result, seq);
+        if (inlineAckGeneration !== null) {
+            client._delivery.onGroupV2AckSucceeded(gid, actualAckSeq, inlineAckGeneration);
+        }
+        client._clientLog.debug(`group.v2.ack ok: group=${gid}, ns=${ns}, requested=${seq}, effective=${actualAckSeq}, result=${client._debugJson(result)}`);
         return result;
     }
     async putMessageThoughtEncryptedV2(params) {
@@ -1754,7 +2269,7 @@ export class V2E2EECoordinator {
     }
     safeUndecryptablePushEvent(msg, group) {
         const client = this.client;
-        const event = {
+        let event = {
             message_id: msg.message_id,
             from: msg.from,
             seq: msg.seq,
@@ -1778,6 +2293,10 @@ export class V2E2EECoordinator {
                 client._attachV2EnvelopeMetadata(event, client._v2E2eeMeta(envelope));
             }
         }
+        if (group) {
+            const modeSource = envelope ? { ...msg, envelope } : msg;
+            event = normalizeGroupMentionMode(event, modeSource);
+        }
         return event;
     }
     async decryptEncryptedPushPayload(msg, group) {
@@ -1791,7 +2310,7 @@ export class V2E2EECoordinator {
         if (!plaintext)
             return null;
         const e2ee = client._v2E2eeMeta(envelope);
-        const result = {
+        let result = {
             message_id: String(msg.message_id ?? ''),
             from: fromAid,
             seq: msg.seq,
@@ -1810,6 +2329,7 @@ export class V2E2EECoordinator {
         attachGatewayProximity(result, msg);
         if (group) {
             result.group_id = (msg.group_id ?? aad.group_id ?? envelope.group_id);
+            result = normalizeGroupMentionMode(result, msg, envelope);
         }
         else {
             result.to = (msg.to ?? client._aid ?? '');
@@ -1846,7 +2366,7 @@ export class V2E2EECoordinator {
     async decryptV2PushMessage(data) {
         if (!isJsonObject(data))
             return null;
-        return await this.client._decryptV2Message(data);
+        return await this.client._decryptV2Message(data, false, false, false, false);
     }
     handleGroupChangedSpk(data, groupId, action) {
         if (!this.client._v2Session || !groupId || !MEMBERSHIP_ACTIONS.has(action))