@agentunion/fastaun-browser 0.5.16 → 0.5.18

package/dist/client/v2-e2ee.js

@@ -14,6 +14,52 @@ 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_PULL_PIPELINE_QUEUE_CAPACITY = 100;
+class V2PullPageQueue {
+    capacity;
+    items = [];
+    takers = [];
+    putters = [];
+    queuedWeight = 0;
+    closed = false;
+    constructor(capacity) {
+        this.capacity = capacity;
+    }
+    async put(item, weight = 1) {
+        const itemWeight = Math.max(1, Math.trunc(weight));
+        while (!this.closed && this.items.length > 0 && this.queuedWeight + itemWeight > this.capacity) {
+            await new Promise((resolve) => this.putters.push(resolve));
+        }
+        if (this.closed)
+            return false;
+        const taker = this.takers.shift();
+        if (taker)
+            taker(item);
+        else {
+            this.items.push(item);
+            this.queuedWeight += itemWeight;
+        }
+        return true;
+    }
+    async take() {
+        const item = this.items.shift();
+        if (item !== undefined) {
+            this.queuedWeight = Math.max(0, this.queuedWeight - Math.max(1, Math.trunc(Number(item.weight ?? 1))));
+            this.putters.shift()?.();
+            return item;
+        }
+        if (this.closed)
+            return undefined;
+        return await new Promise((resolve) => this.takers.push(resolve));
+    }
+    close() {
+        this.closed = true;
+        for (const resolve of this.takers.splice(0))
+            resolve(undefined);
+        for (const resolve of this.putters.splice(0))
+            resolve();
+    }
+}
 const V2_SESSION_INIT_RETRY_LIMIT = 12;
 const V2_SESSION_INIT_RETRY_BASE_MS = 1000;
 const V2_SESSION_INIT_RETRY_MAX_MS = 5000;
@@ -948,6 +994,12 @@ export class V2E2EECoordinator {
                     await client._publishAppEvent(eventName, safeEvent, 'pending_retry');
                     continue;
                 }
+                if (!entry.groupId && String(entry.msg.storage ?? '') === 'volatile') {
+                    await this.publishPendingV2VolatileMessage(entry.msg, plaintext, 'pending_retry');
+                    client._v2SenderIKPending.delete(key);
+                    client._clientLog.debug(`V2 sender IK pending retry delivered: key=${key}`);
+                    continue;
+                }
                 client._v2SenderIKPending.delete(key);
                 const seq = Number(entry.msg.seq ?? 0);
                 if (entry.groupId) {
@@ -967,10 +1019,35 @@ export class V2E2EECoordinator {
             client._v2SenderIKFetching.delete(fetchKey);
         }
     }
+    async publishPendingV2VolatileMessage(rawMessage, plaintext, source) {
+        const delivery = this.client._delivery;
+        const claim = delivery.beginVolatileDelivery(rawMessage);
+        if (claim === 'inflight')
+            return;
+        if (claim === 'seen') {
+            await delivery.ackVolatileMessages([rawMessage], true, false);
+            return;
+        }
+        try {
+            const publicMessage = delivery.publicVolatileMessage(plaintext);
+            for (const key of ['storage', 'volatile_cursor', 'created_at', 'expires_at', 'persist']) {
+                if (key in rawMessage)
+                    publicMessage[key] = rawMessage[key];
+            }
+            const appEvent = delivery.p2pAppEventForMessage(publicMessage);
+            await this.client._publishAppEvent(appEvent.event, appEvent.payload, source);
+            delivery.markVolatileSeen(rawMessage);
+        }
+        finally {
+            delivery.finishVolatileDelivery(rawMessage);
+        }
+        await delivery.ackVolatileMessages([rawMessage], true, false);
+    }
     async sendV2(to, payload, opts) {
         const client = this.client;
         await client._ensureV2SessionReady('message.send', 'V2 session not initialized; encrypted message.send requires V2 (V1 E2EE removed)');
         const toAid = String(to ?? '').trim();
+        const targetDeviceId = String(opts?.deviceId ?? '').trim();
         if (!toAid)
             throw new ValidationError("message.send requires 'to'");
         if (!isJsonObject(payload))
@@ -981,6 +1058,7 @@ export class V2E2EECoordinator {
                 payload,
                 messageId: opts?.messageId,
                 timestamp: opts?.timestamp,
+                deviceId: targetDeviceId || undefined,
                 protectedHeaders: opts?.protectedHeaders,
                 context: opts?.context,
                 useCache,
@@ -989,6 +1067,8 @@ export class V2E2EECoordinator {
                 to: toAid,
                 payload: envelope,
                 message_id: opts?.messageId,
+                ...(opts?.ttl !== undefined ? { ttl: opts.ttl } : {}),
+                ...(targetDeviceId ? { device_id: targetDeviceId } : {}),
                 encrypt: false,
                 _skip_send_result_envelope: true,
             });
@@ -1046,6 +1126,11 @@ export class V2E2EECoordinator {
                     to: String(legacy.to ?? client._aid ?? ''), seq, type: String(msg.type ?? ''),
                     timestamp: msg.t_server, payload: payload, encrypted: false,
                 };
+                if (msg.sender_device_id !== undefined)
+                    plaintext.sender_device_id = msg.sender_device_id;
+                const direction = String(msg.direction ?? '').trim();
+                if (direction)
+                    plaintext.direction = direction;
                 attachGatewayProximity(plaintext, msg);
             }
             else if (isJsonObject(payload)
@@ -1065,6 +1150,9 @@ export class V2E2EECoordinator {
             client._clientLog.warn(`P2P Tail 单条消息解密失败，连续性证明仍保留: seq=${seq}`);
             return null;
         }
+        if (publish && client._delivery.isSelfSentP2PMessage?.(plaintext)) {
+            return plaintext;
+        }
         if (publish) {
             const event = client._delivery.p2pAppEventForMessage(plaintext);
             if (orderedPublish) {
@@ -1121,6 +1209,8 @@ export class V2E2EECoordinator {
                     group_id: groupId, group_aid: groupAid, seq, type: String(msg.type ?? ''),
                     timestamp: msg.t_server, payload: payload, encrypted: false,
                 };
+                if (msg.sender_device_id !== undefined)
+                    plaintext.sender_device_id = msg.sender_device_id;
                 plaintext = normalizeGroupMentionMode(plaintext, msg, msg.envelope_json);
                 attachGatewayProximity(plaintext, msg);
             }
@@ -1232,6 +1322,7 @@ export class V2E2EECoordinator {
         const client = this.client;
         await client._ensureV2SessionReady('message.pull');
         const ns = client._aid ? `p2p:${client._aid}` : '';
+        let volatileCursor = String(opts?.afterVolatileCursor ?? client._delivery.volatilePullCursor() ?? '').trim();
         if (ns)
             client._delivery.onPullStarted?.(ns);
         if (opts?.windowMode === 'tail') {
@@ -1249,7 +1340,7 @@ export class V2E2EECoordinator {
         }
         if (ns && !opts?.gateLocked) {
             const key = pullGateKeyForClient(client, 'message.v2.pull', {
-                after_seq: afterSeq, force: opts?.force === true, limit,
+                after_seq: afterSeq, after_volatile_cursor: volatileCursor, force: opts?.force === true, limit,
             }, `${ns}|forward|after=${afterSeq}|force=${String(Boolean(opts?.force))}|limit=${limit}`);
             return await client._runPullSerialized(key, () => this.pullV2Impl(afterSeq, limit, {
                 ...(opts ?? {}),
@@ -1260,7 +1351,7 @@ export class V2E2EECoordinator {
         let nextAfterSeq = opts?.force ? afterSeq : (afterSeq || (ns ? client._seqTracker.getContiguousSeq(ns) : 0));
         let pullGateKey = ns
             ? pullGateKeyForClient(client, 'message.v2.pull', {
-                after_seq: afterSeq, force: opts?.force === true, limit,
+                after_seq: afterSeq, after_volatile_cursor: volatileCursor, force: opts?.force === true, limit,
             }, `${ns}|forward|after=${afterSeq}|force=${String(Boolean(opts?.force))}|limit=${limit}`)
             : '';
         const deferredServerCursor = ns ? this.pendingForwardCursor(ns, client._seqTracker.getContiguousSeq(ns)) : 0;
@@ -1269,239 +1360,389 @@ export class V2E2EECoordinator {
         let lastAutoAckSeq = 0;
         let pendingAckSeq = deferredForwardAck;
         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,
-                ...(opts?.force ? { force: true } : {}),
-                ...(ackUpToSeq > 0 ? { ack_up_to_seq: ackUpToSeq } : {}),
-            }, pullGateKey);
-            if (ackUpToSeq > 0) {
-                const actualAckSeq = client._delivery?.resolveP2PPullAckSeq?.(result, ackUpToSeq) ?? 0;
-                if (actualAckSeq >= ackUpToSeq) {
-                    if (pendingInlineGeneration !== null) {
-                        client._delivery?.completePendingP2PInlineAckUpTo?.(ns, actualAckSeq, pendingInlineGeneration);
+        let pipelineRunning = false;
+        let pipelineError = null;
+        const pipelineQueue = new V2PullPageQueue(V2_PULL_PIPELINE_QUEUE_CAPACITY);
+        let pipelineProducer = null;
+        let pipelineStopped = false;
+        const startPipeline = (startAfterSeq, startVolatileCursor) => {
+            if (pipelineRunning || pageCount >= maxPages || limit < V2_PULL_MAX_PAGE_LIMIT)
+                return;
+            pipelineRunning = true;
+            pipelineProducer = (async () => {
+                let producerAfterSeq = startAfterSeq;
+                let producerVolatileCursor = startVolatileCursor;
+                for (let produced = pageCount; produced < maxPages; produced += 1) {
+                    if (pipelineStopped)
+                        break;
+                    const requestedVolatileCursor = producerVolatileCursor;
+                    const result = await client._callRawV2Rpc('message.v2.pull', {
+                        after_seq: producerAfterSeq,
+                        limit,
+                        ...(producerVolatileCursor ? { after_volatile_cursor: producerVolatileCursor } : {}),
+                        ...(opts?.force ? { force: true } : {}),
+                    }, pullGateKey);
+                    if (pipelineStopped)
+                        break;
+                    const rawPageMessages = (Array.isArray(result?.messages) ? result.messages : []);
+                    const enqueued = await pipelineQueue.put({
+                        result,
+                        afterSeq: producerAfterSeq,
+                        ackUpToSeq: 0,
+                        inlineAckGeneration: null,
+                        requestedVolatileCursor,
+                        weight: rawPageMessages.length,
+                    }, rawPageMessages.length);
+                    if (!enqueued || pipelineStopped)
+                        break;
+                    const volatileMessages = client._delivery.volatileMessages(rawPageMessages);
+                    if (volatileMessages.length > 0)
+                        break;
+                    const messages = deduplicateForwardPageMessages(rawPageMessages, producerAfterSeq);
+                    const seqs = messages
+                        .map((msg) => Number(msg.seq ?? 0))
+                        .filter((seq) => Number.isFinite(seq) && seq > 0);
+                    const nextAfter = Math.max(contiguousPullSeq(producerAfterSeq, seqs, result.contiguous_seq), producerAfterSeq);
+                    const cursor = isJsonObject(result.cursor)
+                        ? result.cursor : null;
+                    const shouldContinue = shouldContinueForwardPage({
+                        rawCount: messages.length,
+                        nextAfterSeq: producerAfterSeq,
+                        nextAfter,
+                        limit,
+                        hasMoreField: Object.prototype.hasOwnProperty.call(result, 'has_more'),
+                        hasMore: result.has_more === true,
+                        serverHead: safeNonNegativeSeq(cursor?.latest_seq) ?? 0,
+                        observedUpper: Math.max(nextAfter, Number(client._pendingP2pPullUpper?.get?.(ns) ?? 0)),
+                        pendingAckSeq: 0,
+                    });
+                    if (!shouldContinue)
+                        break;
+                    producerAfterSeq = nextAfter;
+                    producerVolatileCursor = '';
+                }
+            })().catch((error) => {
+                pipelineError = error;
+            }).finally(() => {
+                pipelineQueue.close();
+            });
+        };
+        const stopPipeline = async () => {
+            pipelineStopped = true;
+            pipelineQueue.close();
+            if (pipelineProducer) {
+                const producer = pipelineProducer;
+                pipelineProducer = null;
+                await producer;
+            }
+            pipelineRunning = false;
+        };
+        try {
+            while (pageCount < maxPages) {
+                let pipelinePage;
+                if (pipelineRunning) {
+                    pipelinePage = await pipelineQueue.take();
+                    if (!pipelinePage) {
+                        pipelineRunning = false;
+                        if (pipelineError)
+                            throw pipelineError;
+                        break;
                     }
-                    pendingAckSeq = 0;
-                    lastAutoAckSeq = Math.max(lastAutoAckSeq, ackUpToSeq);
-                    this.clearForwardAck(ns, ackUpToSeq);
+                }
+                pageCount += 1;
+                const volatileCursorBeforePage = pipelinePage?.requestedVolatileCursor ?? volatileCursor;
+                const ackUpToSeq = pipelinePage?.ackUpToSeq ?? pendingAckSeq;
+                const pendingInlineGeneration = pipelinePage?.inlineAckGeneration ?? (ackUpToSeq > 0
+                    ? client._delivery?.pendingP2PInlineAckGeneration?.(ns) ?? null
+                    : null);
+                let result;
+                if (pipelinePage) {
+                    nextAfterSeq = pipelinePage.afterSeq;
+                    result = pipelinePage.result;
                 }
                 else {
-                    client._clientLog.warn(`message.v2.pull piggyback ACK below target: requested=${ackUpToSeq}, actual=${actualAckSeq}; fallback terminal ACK`);
-                    await this.confirmForwardP2PAck(ackUpToSeq, pendingInlineGeneration ?? undefined);
-                    pendingAckSeq = 0;
-                    lastAutoAckSeq = Math.max(lastAutoAckSeq, ackUpToSeq);
+                    try {
+                        result = await client._callRawV2Rpc('message.v2.pull', {
+                            after_seq: nextAfterSeq,
+                            limit,
+                            ...(volatileCursor ? { after_volatile_cursor: volatileCursor } : {}),
+                            ...(opts?.force ? { force: true } : {}),
+                            ...(ackUpToSeq > 0 ? { ack_up_to_seq: ackUpToSeq } : {}),
+                        }, pullGateKey);
+                    }
+                    catch (exc) {
+                        const text = exc instanceof Error ? exc.message : String(exc);
+                        if (!volatileCursor || !text.toLowerCase().includes('volatile cursor epoch mismatch'))
+                            throw exc;
+                        client._delivery.resetVolatilePullCursor();
+                        volatileCursor = '';
+                        pageCount -= 1;
+                        continue;
+                    }
                 }
-            }
-            const pageMessages = (Array.isArray(result?.messages) ? result.messages : []);
-            const messages = deduplicateForwardPageMessages(pageMessages, nextAfterSeq);
-            const cursor = isJsonObject(result.cursor) ? result.cursor : null;
-            const hasMoreField = Object.prototype.hasOwnProperty.call(result, 'has_more');
-            const hasMore = result.has_more === true;
-            const serverHead = safeNonNegativeSeq(cursor?.latest_seq) ?? 0;
-            client._clientLog.debug(`message.v2.pull page response: page=${pageCount}, raw_count=${messages.length}, stale_count=${Math.max(0, pageMessages.length - messages.length)}, has_more=${String(result.has_more ?? '')}, server_head=${serverHead}, server_ack_seq=${String(result.server_ack_seq ?? '')}`);
-            const seqs = messages
-                .map((msg) => Number(msg.seq ?? 0))
-                .filter((seq) => Number.isFinite(seq) && seq > 0);
-            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;
-            const pageContiguousSeq = contiguousPullSeq(pageContigBefore, seqs, result.contiguous_seq);
-            const deferredKeyFetches = new Map();
-            let blockedSeq = 0;
-            const pageDecryptedBefore = decrypted.length;
-            for (const msg of messages) {
-                const seq = Number(msg.seq ?? 0);
-                if (!Number.isFinite(seq) || seq <= 0)
-                    continue;
-                const version = String(msg.version ?? 'v2');
-                if (version === 'v1') {
-                    const legacy = isJsonObject(msg.legacy_v1) ? msg.legacy_v1 : {};
-                    const legacyPayload = legacy.payload !== undefined ? legacy.payload : msg.payload;
-                    const payloadType = isJsonObject(legacyPayload)
-                        ? String(legacyPayload.type ?? '').trim()
-                        : '';
-                    if (legacyPayload !== undefined && legacyPayload !== null
-                        && !['e2ee.encrypted', 'e2ee.group_encrypted', 'e2ee.p2p_encrypted'].includes(payloadType)) {
-                        const v1Msg = {
-                            message_id: String(msg.message_id ?? ''),
-                            from: String(msg.from_aid ?? ''),
-                            to: String(legacy.to ?? client._aid ?? ''),
-                            seq: msg.seq,
-                            type: String(msg.type ?? ''),
-                            timestamp: msg.t_server,
-                            payload: legacyPayload,
-                            encrypted: false,
-                        };
-                        attachGatewayProximity(v1Msg, msg);
-                        const appEvent = client._delivery.p2pAppEventForMessage(v1Msg);
-                        if (ns)
-                            await client._publishPulledMessage(appEvent.event, ns, seq, appEvent.payload, false);
-                        else
-                            await client._publishAppEvent(appEvent.event, appEvent.payload, 'pull');
-                        decrypted.push(v1Msg);
+                if (ackUpToSeq > 0) {
+                    const actualAckSeq = client._delivery?.resolveP2PPullAckSeq?.(result, ackUpToSeq) ?? 0;
+                    if (actualAckSeq >= ackUpToSeq) {
+                        if (pendingInlineGeneration !== null) {
+                            client._delivery?.completePendingP2PInlineAckUpTo?.(ns, actualAckSeq, pendingInlineGeneration);
+                        }
+                        pendingAckSeq = 0;
+                        lastAutoAckSeq = Math.max(lastAutoAckSeq, ackUpToSeq);
+                        this.clearForwardAck(ns, ackUpToSeq);
                     }
-                    else if (isJsonObject(legacyPayload)
-                        && ['e2ee.p2p_encrypted', 'e2ee.encrypted'].includes(payloadType)) {
-                        const deferStatus = {};
-                        const plaintext = await client._decryptV2Message({ ...msg, envelope_json: JSON.stringify(legacyPayload) }, true, true, true, true, deferStatus, true, 'pull');
-                        if (deferStatus.deferred) {
-                            blockedSeq = blockedSeq > 0 ? Math.min(blockedSeq, seq) : seq;
-                            if (deferStatus.fromAid) {
-                                const key = `${deferStatus.fromAid}\u0000${deferStatus.senderDeviceId ?? ''}\u0000${deferStatus.groupId ?? ''}`;
-                                deferredKeyFetches.set(key, { fromAid: deferStatus.fromAid, senderDeviceId: deferStatus.senderDeviceId ?? '', groupId: deferStatus.groupId ?? '' });
+                    else {
+                        client._clientLog.warn(`message.v2.pull piggyback ACK below target: requested=${ackUpToSeq}, actual=${actualAckSeq}; fallback terminal ACK`);
+                        await this.confirmForwardP2PAck(ackUpToSeq, pendingInlineGeneration ?? undefined);
+                        pendingAckSeq = 0;
+                        lastAutoAckSeq = Math.max(lastAutoAckSeq, ackUpToSeq);
+                    }
+                }
+                const pageMessages = (Array.isArray(result?.messages) ? result.messages : []);
+                const volatileMessages = client._delivery.volatileMessages(pageMessages);
+                if (volatileMessages.length > 0) {
+                    decrypted.push(...await this.publishV2VolatileMessages(volatileMessages, 'pull', true));
+                    volatileCursor = client._delivery.volatilePullCursor();
+                }
+                const volatileAdvanced = Boolean(volatileCursor) && volatileCursor !== volatileCursorBeforePage;
+                const messages = deduplicateForwardPageMessages(pageMessages, nextAfterSeq);
+                const cursor = isJsonObject(result.cursor) ? result.cursor : null;
+                const hasMoreField = Object.prototype.hasOwnProperty.call(result, 'has_more');
+                const hasMore = result.has_more === true;
+                const serverHead = safeNonNegativeSeq(cursor?.latest_seq) ?? 0;
+                client._clientLog.debug(`message.v2.pull page response: page=${pageCount}, raw_count=${messages.length}, stale_count=${Math.max(0, pageMessages.length - messages.length)}, has_more=${String(result.has_more ?? '')}, server_head=${serverHead}, server_ack_seq=${String(result.server_ack_seq ?? '')}`);
+                const seqs = messages
+                    .map((msg) => Number(msg.seq ?? 0))
+                    .filter((seq) => Number.isFinite(seq) && seq > 0);
+                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;
+                const pageContiguousSeq = contiguousPullSeq(pageContigBefore, seqs, result.contiguous_seq);
+                const deferredKeyFetches = new Map();
+                let blockedSeq = 0;
+                const pageDecryptedBefore = decrypted.length;
+                for (const msg of messages) {
+                    const seq = Number(msg.seq ?? 0);
+                    if (!Number.isFinite(seq) || seq <= 0)
+                        continue;
+                    const version = String(msg.version ?? 'v2');
+                    if (version === 'v1') {
+                        const legacy = isJsonObject(msg.legacy_v1) ? msg.legacy_v1 : {};
+                        const legacyPayload = legacy.payload !== undefined ? legacy.payload : msg.payload;
+                        const payloadType = isJsonObject(legacyPayload)
+                            ? String(legacyPayload.type ?? '').trim()
+                            : '';
+                        if (legacyPayload !== undefined && legacyPayload !== null
+                            && !['e2ee.encrypted', 'e2ee.group_encrypted', 'e2ee.p2p_encrypted'].includes(payloadType)) {
+                            const v1Msg = {
+                                message_id: String(msg.message_id ?? ''),
+                                from: String(msg.from_aid ?? ''),
+                                to: String(legacy.to ?? client._aid ?? ''),
+                                seq: msg.seq,
+                                type: String(msg.type ?? ''),
+                                timestamp: msg.t_server,
+                                payload: legacyPayload,
+                                encrypted: false,
+                            };
+                            const direction = String(msg.direction ?? '').trim();
+                            if (direction)
+                                v1Msg.direction = direction;
+                            else if (String(msg.from_aid ?? '').trim() && String(msg.from_aid ?? '').trim() !== String(client._aid ?? '').trim()) {
+                                v1Msg.direction = 'inbound';
                             }
-                        }
-                        if (plaintext) {
+                            if (msg.sender_device_id !== undefined)
+                                v1Msg.sender_device_id = msg.sender_device_id;
+                            attachGatewayProximity(v1Msg, msg);
+                            const appEvent = client._delivery.p2pAppEventForMessage(v1Msg);
                             if (ns)
-                                await client._publishPulledMessage('message.received', ns, seq, plaintext, false);
+                                await client._publishPulledMessage(appEvent.event, ns, seq, appEvent.payload, false);
                             else
-                                await client._publishAppEvent('message.received', plaintext, 'pull');
-                            decrypted.push(plaintext);
+                                await client._publishAppEvent(appEvent.event, appEvent.payload, 'pull');
+                            decrypted.push(v1Msg);
+                        }
+                        else if (isJsonObject(legacyPayload)
+                            && ['e2ee.p2p_encrypted', 'e2ee.encrypted'].includes(payloadType)) {
+                            const deferStatus = {};
+                            const plaintext = await client._decryptV2Message({ ...msg, envelope_json: JSON.stringify(legacyPayload) }, true, true, true, true, deferStatus, true, 'pull');
+                            if (deferStatus.deferred) {
+                                blockedSeq = blockedSeq > 0 ? Math.min(blockedSeq, seq) : seq;
+                                if (deferStatus.fromAid) {
+                                    const key = `${deferStatus.fromAid}\u0000${deferStatus.senderDeviceId ?? ''}\u0000${deferStatus.groupId ?? ''}`;
+                                    deferredKeyFetches.set(key, { fromAid: deferStatus.fromAid, senderDeviceId: deferStatus.senderDeviceId ?? '', groupId: deferStatus.groupId ?? '' });
+                                }
+                            }
+                            if (plaintext) {
+                                if (ns)
+                                    await client._publishPulledMessage('message.received', ns, seq, plaintext, false);
+                                else
+                                    await client._publishAppEvent('message.received', plaintext, 'pull');
+                                decrypted.push(plaintext);
+                            }
+                        }
+                        else {
+                            client._clientLog.debug(`message.v2.pull skipping V1 envelope seq=${seq} payload_type=${payloadType || '<none>'} (V1 E2EE removed)`);
                         }
+                        continue;
+                    }
+                    if (version !== 'v2') {
+                        client._clientLog.debug(`message.v2.pull skipping non-V2 row seq=${seq} version=${String(msg.version ?? '')}`);
+                        continue;
+                    }
+                    const msgSpkId = String(msg.spk_id ?? '');
+                    if (msgSpkId && client._v2Session && !client._v2Session.isCurrentSPK(msgSpkId)) {
+                        client._v2Session.trackOldSPKMaxSeq(msgSpkId, seq);
+                    }
+                    const deferStatus = {};
+                    const plaintext = await client._decryptV2Message(msg, true, true, true, true, deferStatus, true, 'pull');
+                    if (deferStatus.deferred) {
+                        blockedSeq = blockedSeq > 0 ? Math.min(blockedSeq, seq) : seq;
+                    }
+                    if (deferStatus.deferred && deferStatus.fromAid) {
+                        const key = `${deferStatus.fromAid}\u0000${deferStatus.senderDeviceId ?? ''}\u0000${deferStatus.groupId ?? ''}`;
+                        deferredKeyFetches.set(key, {
+                            fromAid: deferStatus.fromAid,
+                            senderDeviceId: deferStatus.senderDeviceId ?? '',
+                            groupId: deferStatus.groupId ?? '',
+                        });
+                    }
+                    if (plaintext === null)
+                        continue;
+                    if (ns) {
+                        await client._publishPulledMessage('message.received', ns, seq, plaintext, false);
+                        decrypted.push(plaintext);
                     }
                     else {
-                        client._clientLog.debug(`message.v2.pull skipping V1 envelope seq=${seq} payload_type=${payloadType || '<none>'} (V1 E2EE removed)`);
+                        await client._publishAppEvent('message.received', plaintext, 'pull');
+                        decrypted.push(plaintext);
                     }
-                    continue;
-                }
-                if (version !== 'v2') {
-                    client._clientLog.debug(`message.v2.pull skipping non-V2 row seq=${seq} version=${String(msg.version ?? '')}`);
-                    continue;
-                }
-                const msgSpkId = String(msg.spk_id ?? '');
-                if (msgSpkId && client._v2Session && !client._v2Session.isCurrentSPK(msgSpkId)) {
-                    client._v2Session.trackOldSPKMaxSeq(msgSpkId, seq);
                 }
-                const deferStatus = {};
-                const plaintext = await client._decryptV2Message(msg, true, true, true, true, deferStatus, true, 'pull');
-                if (deferStatus.deferred) {
-                    blockedSeq = blockedSeq > 0 ? Math.min(blockedSeq, seq) : seq;
-                }
-                if (deferStatus.deferred && deferStatus.fromAid) {
-                    const key = `${deferStatus.fromAid}\u0000${deferStatus.senderDeviceId ?? ''}\u0000${deferStatus.groupId ?? ''}`;
-                    deferredKeyFetches.set(key, {
-                        fromAid: deferStatus.fromAid,
-                        senderDeviceId: deferStatus.senderDeviceId ?? '',
-                        groupId: deferStatus.groupId ?? '',
-                    });
-                }
-                if (plaintext === null)
-                    continue;
+                const hasServerAckSeq = Object.prototype.hasOwnProperty.call(result, 'server_ack_seq');
+                const parsedServerAckSeq = hasServerAckSeq ? safeNonNegativeSeq(result.server_ack_seq) : null;
+                const serverAckSeq = parsedServerAckSeq ?? 0;
+                const retentionFloor = Math.max(0, Number(result.retention_floor_seq ?? 0));
                 if (ns) {
-                    await client._publishPulledMessage('message.received', ns, seq, plaintext, false);
-                    decrypted.push(plaintext);
-                }
-                else {
-                    await client._publishAppEvent('message.received', plaintext, 'pull');
-                    decrypted.push(plaintext);
-                }
-            }
-            const hasServerAckSeq = Object.prototype.hasOwnProperty.call(result, 'server_ack_seq');
-            const parsedServerAckSeq = hasServerAckSeq ? safeNonNegativeSeq(result.server_ack_seq) : null;
-            const serverAckSeq = parsedServerAckSeq ?? 0;
-            const retentionFloor = Math.max(0, Number(result.retention_floor_seq ?? 0));
-            if (ns) {
-                const commitTarget = Math.max(pageContigBefore, Number.isFinite(retentionFloor) ? retentionFloor : 0, pageCount === 1 ? deferredServerCursor : 0, serverAckSeq, blockedSeq > 0 ? blockedSeq - 1 : pageContiguousSeq);
-                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}`);
+                    const commitTarget = Math.max(pageContigBefore, Number.isFinite(retentionFloor) ? retentionFloor : 0, pageCount === 1 ? deferredServerCursor : 0, serverAckSeq, blockedSeq > 0 ? blockedSeq - 1 : pageContiguousSeq);
+                    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 (deferredServerCursor > pageContigBefore && pageCount === 1) {
+                                client._clientLog.info(`message.v2.pull restore local A from deferred server ACK cursor: ns=${ns}, contiguous=${pageContigBefore} -> server_ack_seq=${deferredServerCursor}`);
+                            }
+                            if (seqs.length > 0) {
+                                client._clientLog.debug(`message.v2.pull force contiguous: ns=${ns}, page_max_seq=${pageMaxSeq}, previous=${pageContigBefore}`);
+                            }
                         }
-                        if (deferredServerCursor > pageContigBefore && pageCount === 1) {
-                            client._clientLog.info(`message.v2.pull restore local A from deferred server ACK cursor: ns=${ns}, contiguous=${pageContigBefore} -> server_ack_seq=${deferredServerCursor}`);
+                        ackSeq = client._seqTracker.getContiguousSeq(ns);
+                        contigAdvanced = ackSeq !== pageContigBefore;
+                        if (contigAdvanced) {
+                            await client._commitSeqTrackerState(ns);
+                            if (pageCount === 1 && deferredServerCursor > 0)
+                                this.clearForwardCursor(ns, ackSeq);
                         }
-                        if (seqs.length > 0) {
-                            client._clientLog.debug(`message.v2.pull force contiguous: ns=${ns}, page_max_seq=${pageMaxSeq}, previous=${pageContigBefore}`);
+                    }
+                    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;
                     }
-                    ackSeq = client._seqTracker.getContiguousSeq(ns);
-                    contigAdvanced = ackSeq !== pageContigBefore;
-                    if (contigAdvanced) {
-                        await client._commitSeqTrackerState(ns);
-                        if (pageCount === 1 && deferredServerCursor > 0)
-                            this.clearForwardCursor(ns, ackSeq);
+                    if (contigAdvanced)
+                        await client._drainOrderedMessages(ns, undefined, false, false);
+                    for (const fetch of deferredKeyFetches.values()) {
+                        this.scheduleSenderIKFetch(fetch.fromAid, fetch.senderDeviceId, fetch.groupId);
                     }
-                }
-                catch (exc) {
-                    if (typeof client._seqTracker.restoreNamespaceSnapshot === 'function') {
-                        client._seqTracker.restoreNamespaceSnapshot(ns, pageTrackerSnapshot);
+                    if (parsedServerAckSeq !== null && serverAckSeq > ackSeq) {
+                        this.recordForwardCursor(ns, serverAckSeq, ackSeq);
+                    }
+                    // 无本页服务端水位时，只有本页成功提交了比已知服务端更高的 A
+                    // 才新增 ACK 义务。空页不能仅因本地已有 A 而重复 ACK。
+                    const knownServerAckSeq = hasServerAckSeq
+                        ? serverAckSeq
+                        : (pageCount === 1 ? deferredServerCursor : 0);
+                    const ackNeeded = ackSeq > 0
+                        && ackSeq > lastAutoAckSeq
+                        && ((hasServerAckSeq && ackSeq > serverAckSeq)
+                            || (contigAdvanced && ackSeq > knownServerAckSeq));
+                    if (ackNeeded) {
+                        this.recordForwardAck(ns, ackSeq);
+                        const nextAfter = Math.max(pageContiguousSeq, nextAfterSeq);
+                        const canContinuePage = blockedSeq <= 0 && messages.length > 0 && nextAfter > nextAfterSeq;
+                        if (canContinuePage && !pipelineRunning) {
+                            pendingAckSeq = Math.max(pendingAckSeq, ackSeq);
+                            lastAutoAckSeq = Math.max(lastAutoAckSeq, ackSeq);
+                        }
+                        else {
+                            await this.confirmForwardP2PAck(ackSeq);
+                            lastAutoAckSeq = Math.max(lastAutoAckSeq, ackSeq);
+                        }
                     }
-                    client._clientLog.error?.(`message.v2.pull Forward commit rolled back: ns=${ns} target=${commitTarget} error=${formatE2EEError(exc)}`);
-                    throw exc;
-                }
-                if (contigAdvanced)
-                    await client._drainOrderedMessages(ns, undefined, false, false);
-                for (const fetch of deferredKeyFetches.values()) {
-                    this.scheduleSenderIKFetch(fetch.fromAid, fetch.senderDeviceId, fetch.groupId);
                 }
-                if (parsedServerAckSeq !== null && serverAckSeq > ackSeq) {
-                    this.recordForwardCursor(ns, serverAckSeq, ackSeq);
+                if (ns)
+                    client._delivery.onPullPage?.(ns, decrypted.length - pageDecryptedBefore, hasMore, pageMaxSeq, typeof result.remaining === 'number' && Number.isSafeInteger(result.remaining) && result.remaining >= 0 ? result.remaining : null, messages.length, client._seqTracker.getContiguousSeq(ns), pageMaxSeq);
+                const nextAfter = Math.max(pageContiguousSeq, nextAfterSeq);
+                const rawCount = messages.length;
+                if (blockedSeq > 0)
+                    break;
+                let shouldContinue = shouldContinueForwardPage({
+                    rawCount,
+                    nextAfterSeq,
+                    nextAfter,
+                    limit,
+                    hasMoreField,
+                    hasMore,
+                    serverHead,
+                    pendingAckSeq,
+                    observedUpper: typeof client._seqTracker.getMaxSeenSeq === 'function'
+                        ? client._seqTracker.getMaxSeenSeq(ns) : nextAfter,
+                });
+                const volatileHasMoreField = Object.prototype.hasOwnProperty.call(result, 'volatile_has_more');
+                const volatileHasMore = result.volatile_has_more === true;
+                if (!shouldContinue && volatileAdvanced && (volatileHasMore || hasMore || (!volatileHasMoreField && limit > 0 && pageMessages.length >= limit))) {
+                    shouldContinue = true;
                 }
-                // 无本页服务端水位时，只有本页成功提交了比已知服务端更高的 A
-                // 才新增 ACK 义务。空页不能仅因本地已有 A 而重复 ACK。
-                const knownServerAckSeq = hasServerAckSeq
-                    ? serverAckSeq
-                    : (pageCount === 1 ? deferredServerCursor : 0);
-                const ackNeeded = ackSeq > 0
-                    && ackSeq > lastAutoAckSeq
-                    && ((hasServerAckSeq && ackSeq > serverAckSeq)
-                        || (contigAdvanced && ackSeq > knownServerAckSeq));
-                if (ackNeeded) {
-                    this.recordForwardAck(ns, ackSeq);
-                    const nextAfter = Math.max(pageContiguousSeq, nextAfterSeq);
-                    const canContinuePage = blockedSeq <= 0 && messages.length > 0 && nextAfter > nextAfterSeq;
-                    if (canContinuePage) {
-                        pendingAckSeq = Math.max(pendingAckSeq, ackSeq);
-                        lastAutoAckSeq = Math.max(lastAutoAckSeq, ackSeq);
-                    }
-                    else {
-                        await this.confirmForwardP2PAck(ackSeq);
-                        lastAutoAckSeq = Math.max(lastAutoAckSeq, ackSeq);
+                const shouldContinueForPipeline = shouldContinueForwardPage({
+                    rawCount,
+                    nextAfterSeq,
+                    nextAfter,
+                    limit,
+                    hasMoreField,
+                    hasMore,
+                    serverHead,
+                    pendingAckSeq: 0,
+                    observedUpper: typeof client._seqTracker.getMaxSeenSeq === 'function'
+                        ? client._seqTracker.getMaxSeenSeq(ns) : nextAfter,
+                });
+                if (!shouldContinue)
+                    break;
+                if (shouldContinueForPipeline && !volatileAdvanced && !pipelineRunning && limit >= V2_PULL_MAX_PAGE_LIMIT) {
+                    if (pendingAckSeq > 0) {
+                        await this.confirmForwardP2PAck(pendingAckSeq);
+                        pendingAckSeq = 0;
                     }
+                    startPipeline(nextAfter, volatileCursor);
+                }
+                if (!pipelineRunning && pullGateKey && opts?.gateLocked && client._rpcPipeline?.yieldPullGate) {
+                    const nextKey = pullGateKeyForClient(client, 'message.v2.pull', {
+                        after_seq: nextAfter, after_volatile_cursor: volatileCursor, force: opts?.force === true, limit,
+                    }, `${ns}|forward|after=${nextAfter}|force=${String(Boolean(opts?.force))}|limit=${limit}`);
+                    await client._rpcPipeline.yieldPullGate(pullGateKey, nextKey, true);
+                    pullGateKey = nextKey;
                 }
+                const tailDelayMs = v2PullTailDelayMs(rawCount, limit);
+                if (tailDelayMs > 0)
+                    await v2Sleep(tailDelayMs);
+                nextAfterSeq = nextAfter;
             }
-            if (ns)
-                client._delivery.onPullPage?.(ns, decrypted.length - pageDecryptedBefore, hasMore, pageMaxSeq, typeof result.remaining === 'number' && Number.isSafeInteger(result.remaining) && result.remaining >= 0 ? result.remaining : null, messages.length, client._seqTracker.getContiguousSeq(ns), pageMaxSeq);
-            const nextAfter = Math.max(pageContiguousSeq, nextAfterSeq);
-            const rawCount = messages.length;
-            if (blockedSeq > 0)
-                break;
-            const shouldContinue = shouldContinueForwardPage({
-                rawCount,
-                nextAfterSeq,
-                nextAfter,
-                limit,
-                hasMoreField,
-                hasMore,
-                serverHead,
-                pendingAckSeq,
-                observedUpper: typeof client._seqTracker.getMaxSeenSeq === 'function'
-                    ? client._seqTracker.getMaxSeenSeq(ns) : nextAfter,
-            });
-            if (!shouldContinue)
-                break;
-            if (pullGateKey && opts?.gateLocked && client._rpcPipeline?.yieldPullGate) {
-                const nextKey = pullGateKeyForClient(client, 'message.v2.pull', {
-                    after_seq: nextAfter, force: opts?.force === true, limit,
-                }, `${ns}|forward|after=${nextAfter}|force=${String(Boolean(opts?.force))}|limit=${limit}`);
-                await client._rpcPipeline.yieldPullGate(pullGateKey, nextKey, true);
-                pullGateKey = nextKey;
-            }
-            const tailDelayMs = v2PullTailDelayMs(rawCount, limit);
-            if (tailDelayMs > 0)
-                await v2Sleep(tailDelayMs);
-            nextAfterSeq = nextAfter;
+        }
+        finally {
+            await stopPipeline();
         }
         if (pageCount >= maxPages) {
             client._clientLog.warn(`message.v2.pull reached max_pages=${maxPages} after_seq=${nextAfterSeq}`);
@@ -1513,6 +1754,73 @@ export class V2E2EECoordinator {
         client._delivery.onPullWorkSettled?.();
         return deduplicatePulledResults(decrypted);
     }
+    async publishV2VolatileMessages(messages, source, advanceCursor) {
+        const client = this.client;
+        if (!client._v2Session)
+            return [];
+        const processed = [];
+        const plaintextMessages = [];
+        let complete = true;
+        for (const rawMessage of messages) {
+            const claim = client._delivery.beginVolatileDelivery(rawMessage);
+            if (claim === 'seen') {
+                processed.push(rawMessage);
+                continue;
+            }
+            if (claim === 'inflight') {
+                complete = false;
+                continue;
+            }
+            let plaintext;
+            try {
+                if (client._isEncryptedPushMessage(rawMessage)) {
+                    plaintext = await client._decryptV2Message(rawMessage, true, true, true, true, undefined, false, source);
+                }
+                else {
+                    const legacy = isJsonObject(rawMessage.legacy_v1)
+                        ? rawMessage.legacy_v1
+                        : {};
+                    plaintext = {
+                        message_id: String(rawMessage.message_id ?? ''),
+                        from: String(rawMessage.from_aid ?? rawMessage.from ?? ''),
+                        to: String(legacy.to ?? rawMessage.to ?? client._aid ?? ''),
+                        type: String(rawMessage.type ?? ''),
+                        timestamp: rawMessage.t_server ?? rawMessage.timestamp,
+                        payload: legacy.payload !== undefined ? legacy.payload : rawMessage.payload,
+                        encrypted: false,
+                    };
+                    for (const key of ['context', 'protected_headers', 'headers', 'client_signature']) {
+                        if (key in rawMessage)
+                            plaintext[key] = rawMessage[key];
+                    }
+                    if (rawMessage.sender_device_id !== undefined)
+                        plaintext.sender_device_id = rawMessage.sender_device_id;
+                    attachGatewayProximity(plaintext, rawMessage);
+                }
+                if (!plaintext) {
+                    complete = false;
+                    continue;
+                }
+                const publicMessage = client._delivery.publicVolatileMessage(plaintext);
+                for (const key of ['storage', 'volatile_cursor', 'created_at', 'expires_at', 'persist']) {
+                    if (key in rawMessage)
+                        publicMessage[key] = rawMessage[key];
+                }
+                const appEvent = client._delivery.p2pAppEventForMessage(publicMessage);
+                await client._publishAppEvent(appEvent.event, appEvent.payload, source);
+                client._delivery.markVolatileSeen(rawMessage);
+                processed.push(rawMessage);
+                plaintextMessages.push(publicMessage);
+            }
+            finally {
+                client._delivery.finishVolatileDelivery(rawMessage);
+            }
+        }
+        if (processed.length > 0) {
+            await client._delivery.ackVolatileMessages(processed, true, advanceCursor && complete && processed.length === messages.length);
+        }
+        return plaintextMessages;
+    }
     async confirmForwardP2PAck(upToSeq, inlineGeneration) {
         const ns = this.client._aid ? `p2p:${this.client._aid}` : '';
         try {
@@ -1528,41 +1836,51 @@ export class V2E2EECoordinator {
             throw exc;
         }
     }
-    async ackV2(upToSeq, inlineGeneration) {
-        return this.ackV2WithConfirmation(upToSeq, inlineGeneration, false);
+    async ackV2(upToSeq, inlineGeneration, volatileCursors = [], volatileIds = []) {
+        return this.ackV2WithConfirmation(upToSeq, inlineGeneration, false, volatileCursors, volatileIds);
     }
     async ackV2ForForward(upToSeq, inlineGeneration) {
         return this.ackV2WithConfirmation(upToSeq, inlineGeneration, true);
     }
-    async ackV2WithConfirmation(upToSeq, inlineGeneration, requireServerWatermark) {
+    async ackV2WithConfirmation(upToSeq, inlineGeneration, requireServerWatermark, volatileCursors = [], volatileIds = []) {
         const client = this.client;
         const ns = client._aid ? `p2p:${client._aid}` : '';
         let seq = upToSeq ?? (ns ? client._seqTracker.getContiguousSeq(ns) : 0);
         if (typeof seq !== 'number' || !Number.isSafeInteger(seq) || seq <= 0)
+            seq = 0;
+        if (seq <= 0 && volatileCursors.length === 0 && volatileIds.length === 0)
             return { acked: 0 };
-        seq = client._clampAckSeq('message.v2.ack', 'up_to_seq', ns, seq);
-        if (!Number.isSafeInteger(seq) || seq <= 0)
+        if (seq > 0)
+            seq = client._clampAckSeq('message.v2.ack', 'up_to_seq', ns, seq);
+        if ((!Number.isSafeInteger(seq) || seq <= 0) && volatileCursors.length === 0 && volatileIds.length === 0) {
             return { acked: 0 };
+        }
         // ACK 发出前绑定当时的 inline pending；迟到响应不得结算重置后新建的 pending。
         const ackGeneration = inlineGeneration ?? client._delivery?.pendingP2PInlineAckGeneration?.(ns) ?? null;
         const v2SessionAtStart = client._v2Session;
         const v2RuntimeGenerationAtStart = Number(client._v2RuntimeGeneration ?? 0);
-        const raw = await client._callRawV2Rpc('message.v2.ack', { up_to_seq: seq });
+        const raw = await client._callRawV2Rpc('message.v2.ack', {
+            ...(seq > 0 ? { up_to_seq: seq } : {}),
+            ...(volatileCursors.length > 0 ? { volatile_cursors: volatileCursors } : {}),
+            ...(volatileIds.length > 0 ? { volatile_ids: volatileIds } : {}),
+        });
         const result = isJsonObject(raw)
             ? { ...raw }
             : { result: raw };
-        const actualAckSeq = requireServerWatermark
-            ? (client._delivery?.resolveForwardAckSeq?.(result, seq) ?? 0)
-            : (client._delivery?.resolveActualAckSeq?.(result, seq) ?? seq);
-        if (requireServerWatermark && actualAckSeq < seq) {
+        const actualAckSeq = seq > 0
+            ? (requireServerWatermark
+                ? (client._delivery?.resolveForwardAckSeq?.(result, seq) ?? 0)
+                : (client._delivery?.resolveActualAckSeq?.(result, seq) ?? seq))
+            : 0;
+        if (seq > 0 && requireServerWatermark && actualAckSeq < seq) {
             throw new E2EEError(`message.v2.ack server ACK watermark ${actualAckSeq} is below requested ${seq}`);
         }
         result.ack_seq = actualAckSeq;
         result.success = true;
-        if (ackGeneration !== null) {
+        if (seq > 0 && ackGeneration !== null) {
             client._delivery?.completePendingP2PInlineAckUpTo?.(ns, actualAckSeq, ackGeneration);
         }
-        if (v2SessionAtStart
+        if (seq > 0 && v2SessionAtStart
             && client._v2Session === v2SessionAtStart
             && Number(client._v2RuntimeGeneration ?? 0) === v2RuntimeGenerationAtStart) {
             try {
@@ -1794,83 +2112,197 @@ export class V2E2EECoordinator {
         let lastAutoAckSeq = 0;
         let pendingAckSeq = deferredForwardAck;
         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 pendingInlineGeneration = ackUpToSeq > 0
-                ? client._delivery?.pendingGroupInlineAckGeneration?.(ns) ?? null
-                : null;
-            const result = await client._callRawV2Rpc('group.v2.pull', withExplicitGroupAid({
-                group_id: wireGroupId,
-                after_seq: nextAfterSeq,
-                limit,
-                ...cursorParams,
-                ...(opts?.force ? { force: true } : {}),
-                ...(ackUpToSeq > 0 ? { ack_up_to_seq: ackUpToSeq } : {}),
-            }, groupAid), pullGateKey);
-            if (ackUpToSeq > 0) {
-                const actualAckSeq = client._delivery?.resolveGroupPullAckSeq?.(result, ackUpToSeq) ?? 0;
-                if (actualAckSeq >= ackUpToSeq) {
-                    if (pendingInlineGeneration !== null) {
-                        client._delivery?.completePendingGroupInlineAckUpTo?.(ns, actualAckSeq, pendingInlineGeneration);
+        let pipelineRunning = false;
+        let pipelineError = null;
+        const pipelineQueue = new V2PullPageQueue(V2_PULL_PIPELINE_QUEUE_CAPACITY);
+        let pipelineProducer = null;
+        let pipelineStopped = false;
+        const startPipeline = (startAfterSeq) => {
+            if (pipelineRunning || pageCount >= maxPages || limit < V2_PULL_MAX_PAGE_LIMIT || !ownsCursor)
+                return;
+            pipelineRunning = true;
+            pipelineProducer = (async () => {
+                let producerAfterSeq = startAfterSeq;
+                for (let produced = pageCount; produced < maxPages; produced += 1) {
+                    if (pipelineStopped)
+                        break;
+                    const result = await client._callRawV2Rpc('group.v2.pull', withExplicitGroupAid({
+                        group_id: wireGroupId,
+                        after_seq: producerAfterSeq,
+                        limit,
+                        ...cursorParams,
+                        ...(opts?.force ? { force: true } : {}),
+                    }, groupAid), pullGateKey);
+                    if (pipelineStopped)
+                        break;
+                    const pageMessages = (Array.isArray(result?.messages) ? result.messages : []);
+                    const enqueued = await pipelineQueue.put({
+                        result,
+                        afterSeq: producerAfterSeq,
+                        ackUpToSeq: 0,
+                        inlineAckGeneration: null,
+                        requestedVolatileCursor: '',
+                        weight: pageMessages.length,
+                    }, pageMessages.length);
+                    if (!enqueued || pipelineStopped)
+                        break;
+                    const messages = deduplicateForwardPageMessages(pageMessages, producerAfterSeq);
+                    const seqs = messages.map((msg) => Number(msg.seq ?? 0)).filter((seq) => Number.isFinite(seq) && seq > 0);
+                    const nextAfter = Math.max(contiguousPullSeq(producerAfterSeq, seqs, result.contiguous_seq), producerAfterSeq);
+                    const cursor = isJsonObject(result.cursor)
+                        ? result.cursor : null;
+                    const shouldContinue = shouldContinueForwardPage({
+                        rawCount: messages.length,
+                        nextAfterSeq: producerAfterSeq,
+                        nextAfter,
+                        limit,
+                        hasMoreField: Object.prototype.hasOwnProperty.call(result, 'has_more'),
+                        hasMore: result.has_more === true,
+                        serverHead: Math.max(safeNonNegativeSeq(result.latest_message_seq) ?? 0, safeNonNegativeSeq(cursor?.latest_seq) ?? 0),
+                        observedUpper: Math.max(nextAfter, typeof client._seqTracker.getMaxSeenSeq === 'function' ? client._seqTracker.getMaxSeenSeq(ns) : 0),
+                        pendingAckSeq: 0,
+                    });
+                    if (!shouldContinue)
+                        break;
+                    producerAfterSeq = nextAfter;
+                }
+            })().catch((error) => {
+                pipelineError = error;
+            }).finally(() => {
+                pipelineQueue.close();
+            });
+        };
+        const stopPipeline = async () => {
+            pipelineStopped = true;
+            pipelineQueue.close();
+            if (pipelineProducer) {
+                const producer = pipelineProducer;
+                pipelineProducer = null;
+                await producer;
+            }
+            pipelineRunning = false;
+        };
+        try {
+            while (pageCount < maxPages) {
+                let pipelinePage;
+                if (pipelineRunning) {
+                    pipelinePage = await pipelineQueue.take();
+                    if (!pipelinePage) {
+                        pipelineRunning = false;
+                        if (pipelineError)
+                            throw pipelineError;
+                        break;
                     }
-                    pendingAckSeq = 0;
-                    lastAutoAckSeq = Math.max(lastAutoAckSeq, ackUpToSeq);
-                    this.clearForwardAck(ns, ackUpToSeq);
+                }
+                pageCount += 1;
+                const ackUpToSeq = ownsCursor ? (pipelinePage?.ackUpToSeq ?? pendingAckSeq) : 0;
+                const pendingInlineGeneration = pipelinePage?.inlineAckGeneration ?? (ackUpToSeq > 0
+                    ? client._delivery?.pendingGroupInlineAckGeneration?.(ns) ?? null
+                    : null);
+                let result;
+                if (pipelinePage) {
+                    nextAfterSeq = pipelinePage.afterSeq;
+                    result = pipelinePage.result;
                 }
                 else {
-                    client._clientLog.warn(`group.v2.pull piggyback ACK below target: group=${gid}, requested=${ackUpToSeq}, actual=${actualAckSeq}; fallback terminal ACK`);
-                    await this.confirmForwardGroupAck(gid, ackUpToSeq, groupAid);
-                    pendingAckSeq = 0;
-                    lastAutoAckSeq = Math.max(lastAutoAckSeq, ackUpToSeq);
+                    result = await client._callRawV2Rpc('group.v2.pull', withExplicitGroupAid({
+                        group_id: wireGroupId,
+                        after_seq: nextAfterSeq,
+                        limit,
+                        ...cursorParams,
+                        ...(opts?.force ? { force: true } : {}),
+                        ...(ackUpToSeq > 0 ? { ack_up_to_seq: ackUpToSeq } : {}),
+                    }, groupAid), pullGateKey);
                 }
-            }
-            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 = deduplicateForwardPageMessages(pageMessages, nextAfterSeq);
-            const cursor = isJsonObject(result.cursor) ? result.cursor : null;
-            const hasMoreField = Object.prototype.hasOwnProperty.call(result, 'has_more');
-            const hasMore = result.has_more === true;
-            const serverHead = Math.max(safeNonNegativeSeq(result.latest_message_seq) ?? 0, safeNonNegativeSeq(cursor?.latest_seq) ?? 0);
-            const seqs = messages
-                .map((msg) => Number(msg.seq ?? 0))
-                .filter((seq) => Number.isFinite(seq) && seq > 0);
-            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;
-            const pageContiguousSeq = contiguousPullSeq(pageContigBefore, seqs, result.contiguous_seq);
-            const deferredKeyFetches = new Map();
-            let blockedSeq = 0;
-            const pageDecryptedBefore = decrypted.length;
-            for (const msg of messages) {
-                const seq = Number(msg.seq ?? 0);
-                if (!Number.isFinite(seq) || seq <= 0)
-                    continue;
-                const version = String(msg.version ?? 'v2');
-                if (version === 'v1') {
-                    const legacy = isJsonObject(msg.legacy_v1) ? msg.legacy_v1 : {};
-                    const payload = msg.payload !== undefined ? msg.payload : legacy.payload;
-                    const payloadObj = isJsonObject(payload) ? payload : null;
-                    // 群撤回 tombstone（占位 / 通知）：归一化为 group.message_recalled 事件，仍占 seq。
-                    if (typeof client._delivery?.recallEventFromGroupMessage === 'function'
-                        && client._delivery.recallEventFromGroupMessage(msg)) {
-                        await client._delivery.publishGroupRecallTombstone(gid, seq, {
-                            ...msg,
-                            group_id: gid,
-                            group_aid: eventGroupAid,
-                        }, 'pull');
-                        client._markPublishedSeq(ns, seq);
-                        client._clientLog.debug(`group.v2.pull recall tombstone delivered: group=${gid}, seq=${seq}`);
-                        continue;
+                if (ackUpToSeq > 0) {
+                    const actualAckSeq = client._delivery?.resolveGroupPullAckSeq?.(result, ackUpToSeq) ?? 0;
+                    if (actualAckSeq >= ackUpToSeq) {
+                        if (pendingInlineGeneration !== null) {
+                            client._delivery?.completePendingGroupInlineAckUpTo?.(ns, actualAckSeq, pendingInlineGeneration);
+                        }
+                        pendingAckSeq = 0;
+                        lastAutoAckSeq = Math.max(lastAutoAckSeq, ackUpToSeq);
+                        this.clearForwardAck(ns, ackUpToSeq);
                     }
-                    if (payloadObj) {
-                        const payloadType = String(payloadObj.type ?? '').trim();
-                        if (payloadType !== 'e2ee.encrypted' && payloadType !== 'e2ee.group_encrypted' && payloadType !== 'e2ee.p2p_encrypted') {
+                    else {
+                        client._clientLog.warn(`group.v2.pull piggyback ACK below target: group=${gid}, requested=${ackUpToSeq}, actual=${actualAckSeq}; fallback terminal ACK`);
+                        await this.confirmForwardGroupAck(gid, ackUpToSeq, groupAid);
+                        pendingAckSeq = 0;
+                        lastAutoAckSeq = Math.max(lastAutoAckSeq, ackUpToSeq);
+                    }
+                }
+                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 = deduplicateForwardPageMessages(pageMessages, nextAfterSeq);
+                const cursor = isJsonObject(result.cursor) ? result.cursor : null;
+                const hasMoreField = Object.prototype.hasOwnProperty.call(result, 'has_more');
+                const hasMore = result.has_more === true;
+                const serverHead = Math.max(safeNonNegativeSeq(result.latest_message_seq) ?? 0, safeNonNegativeSeq(cursor?.latest_seq) ?? 0);
+                const seqs = messages
+                    .map((msg) => Number(msg.seq ?? 0))
+                    .filter((seq) => Number.isFinite(seq) && seq > 0);
+                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;
+                const pageContiguousSeq = contiguousPullSeq(pageContigBefore, seqs, result.contiguous_seq);
+                const deferredKeyFetches = new Map();
+                let blockedSeq = 0;
+                const pageDecryptedBefore = decrypted.length;
+                for (const msg of messages) {
+                    const seq = Number(msg.seq ?? 0);
+                    if (!Number.isFinite(seq) || seq <= 0)
+                        continue;
+                    const version = String(msg.version ?? 'v2');
+                    if (version === 'v1') {
+                        const legacy = isJsonObject(msg.legacy_v1) ? msg.legacy_v1 : {};
+                        const payload = msg.payload !== undefined ? msg.payload : legacy.payload;
+                        const payloadObj = isJsonObject(payload) ? payload : null;
+                        // 群撤回 tombstone（占位 / 通知）：归一化为 group.message_recalled 事件，仍占 seq。
+                        if (typeof client._delivery?.recallEventFromGroupMessage === 'function'
+                            && client._delivery.recallEventFromGroupMessage(msg)) {
+                            await client._delivery.publishGroupRecallTombstone(gid, seq, {
+                                ...msg,
+                                group_id: gid,
+                                group_aid: eventGroupAid,
+                            }, 'pull');
+                            client._markPublishedSeq(ns, seq);
+                            client._clientLog.debug(`group.v2.pull recall tombstone delivered: group=${gid}, seq=${seq}`);
+                            continue;
+                        }
+                        if (payloadObj) {
+                            const payloadType = String(payloadObj.type ?? '').trim();
+                            if (payloadType !== 'e2ee.encrypted' && payloadType !== 'e2ee.group_encrypted' && payloadType !== 'e2ee.p2p_encrypted') {
+                                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,
+                                };
+                                if (msg.sender_device_id !== undefined)
+                                    v1Msg.sender_device_id = msg.sender_device_id;
+                                v1Msg = normalizeGroupMentionMode(v1Msg, msg, msg.envelope_json);
+                                attachGatewayProximity(v1Msg, msg);
+                                if (!client._delivery.isSelfSentGroupMessage?.(msg)) {
+                                    await client._publishPulledMessage('group.message_created', ns, seq, v1Msg, false);
+                                }
+                                else {
+                                    client._markPublishedSeq(ns, seq);
+                                }
+                                decrypted.push(v1Msg);
+                                continue;
+                            }
+                        }
+                        else if (payload !== undefined && payload !== null) {
                             let v1Msg = {
                                 message_id: String(msg.message_id ?? ''),
                                 from: String(msg.from_aid ?? ''),
@@ -1882,194 +2314,195 @@ export class V2E2EECoordinator {
                                 payload,
                                 encrypted: false,
                             };
+                            if (msg.sender_device_id !== undefined)
+                                v1Msg.sender_device_id = msg.sender_device_id;
                             v1Msg = normalizeGroupMentionMode(v1Msg, msg, msg.envelope_json);
                             attachGatewayProximity(v1Msg, msg);
-                            if (!client._delivery.isSelfSentGroupMessage?.(msg)) {
-                                await client._publishPulledMessage('group.message_created', ns, seq, v1Msg, false);
-                            }
-                            else {
-                                client._markPublishedSeq(ns, seq);
-                            }
+                            await client._publishPulledMessage('group.message_created', ns, seq, v1Msg, false);
                             decrypted.push(v1Msg);
                             continue;
                         }
+                        if (payloadObj && ['e2ee.group_encrypted', 'e2ee.p2p_encrypted', 'e2ee.encrypted'].includes(String(payloadObj.type ?? '').trim())) {
+                            const deferStatus = {};
+                            const plaintext = await client._decryptV2Message({ ...msg, envelope_json: JSON.stringify(payloadObj) }, true, true, true, true, deferStatus, true, 'pull');
+                            if (deferStatus.deferred) {
+                                blockedSeq = blockedSeq > 0 ? Math.min(blockedSeq, seq) : seq;
+                                if (deferStatus.fromAid) {
+                                    const key = `${deferStatus.fromAid}\u0000${deferStatus.senderDeviceId ?? ''}\u0000${deferStatus.groupId ?? ''}`;
+                                    deferredKeyFetches.set(key, { fromAid: deferStatus.fromAid, senderDeviceId: deferStatus.senderDeviceId ?? '', groupId: deferStatus.groupId ?? '' });
+                                }
+                            }
+                            if (plaintext) {
+                                plaintext.group_id = gid;
+                                plaintext.group_aid = eventGroupAid;
+                                if (!client._delivery.isSelfSentGroupMessage?.(msg)) {
+                                    await client._publishPulledMessage('group.message_created', ns, seq, plaintext, false);
+                                }
+                                else {
+                                    client._markPublishedSeq(ns, seq);
+                                }
+                                decrypted.push(plaintext);
+                            }
+                        }
+                        client._clientLog.debug(`group.v2.pull skipping V1 envelope group=${gid} seq=${seq} payload_type=${payloadObj ? String(payloadObj.type ?? '') : '<none>'} (V1 E2EE removed)`);
+                        continue;
                     }
-                    else if (payload !== undefined && payload !== null) {
-                        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, false);
-                        decrypted.push(v1Msg);
+                    if (version !== 'v2') {
+                        client._clientLog.debug(`group.v2.pull skipping non-V2 row group=${gid} seq=${seq} version=${String(msg.version ?? '')}`);
                         continue;
                     }
-                    if (payloadObj && ['e2ee.group_encrypted', 'e2ee.p2p_encrypted', 'e2ee.encrypted'].includes(String(payloadObj.type ?? '').trim())) {
-                        const deferStatus = {};
-                        const plaintext = await client._decryptV2Message({ ...msg, envelope_json: JSON.stringify(payloadObj) }, true, true, true, true, deferStatus, true, 'pull');
-                        if (deferStatus.deferred) {
-                            blockedSeq = blockedSeq > 0 ? Math.min(blockedSeq, seq) : seq;
-                            if (deferStatus.fromAid) {
-                                const key = `${deferStatus.fromAid}\u0000${deferStatus.senderDeviceId ?? ''}\u0000${deferStatus.groupId ?? ''}`;
-                                deferredKeyFetches.set(key, { fromAid: deferStatus.fromAid, senderDeviceId: deferStatus.senderDeviceId ?? '', groupId: deferStatus.groupId ?? '' });
+                    const deferStatus = {};
+                    let plaintext = await client._decryptV2Message(msg, true, true, true, true, deferStatus, true, 'pull');
+                    if (deferStatus.deferred) {
+                        blockedSeq = blockedSeq > 0 ? Math.min(blockedSeq, seq) : seq;
+                    }
+                    if (deferStatus.deferred && deferStatus.fromAid) {
+                        const key = `${deferStatus.fromAid}\u0000${deferStatus.senderDeviceId ?? ''}\u0000${deferStatus.groupId ?? ''}`;
+                        deferredKeyFetches.set(key, {
+                            fromAid: deferStatus.fromAid,
+                            senderDeviceId: deferStatus.senderDeviceId ?? '',
+                            groupId: deferStatus.groupId ?? '',
+                        });
+                    }
+                    if (plaintext === null)
+                        continue;
+                    plaintext = normalizeGroupMentionMode(plaintext, msg, msg.envelope_json);
+                    plaintext.group_id = gid;
+                    plaintext.group_aid = eventGroupAid;
+                    if (!client._delivery.isSelfSentGroupMessage?.(msg)) {
+                        await client._publishPulledMessage('group.message_created', ns, seq, plaintext, false);
+                    }
+                    else {
+                        client._markPublishedSeq(ns, seq);
+                    }
+                    decrypted.push(plaintext);
+                }
+                const hasServerCursor = cursor !== null && Object.prototype.hasOwnProperty.call(cursor, 'current_seq');
+                const parsedCursorCurrentSeq = hasServerCursor ? safeNonNegativeSeq(cursor?.current_seq) : null;
+                const cursorCurrentSeq = parsedCursorCurrentSeq ?? 0;
+                const retentionFloor = Math.max(Number(result.retention_floor_message_seq ?? result.retention_floor_seq ?? 0), Number(cursor?.retention_floor_seq ?? 0));
+                const visibilityFloor = Math.max(0, Math.max(0, Number(result.earliest_available_message_seq ?? 1) - 1), Number(cursor?.join_seq ?? 0));
+                const effectiveFloor = Math.max(retentionFloor, visibilityFloor);
+                const commitTarget = Math.max(pageContigBefore, Number.isFinite(effectiveFloor) ? effectiveFloor : 0, ownsCursor && pageCount === 1 ? deferredServerCursor : 0, cursorCurrentSeq, blockedSeq > 0 ? blockedSeq - 1 : pageContiguousSeq);
+                let ackSeq = pageContigBefore;
+                let contigAdvanced = false;
+                if (ownsCursor) {
+                    try {
+                        if (commitTarget > pageContigBefore) {
+                            client._seqTracker.forceContiguousSeq(ns, commitTarget);
+                            if (effectiveFloor > pageContigBefore) {
+                                client._clientLog.info(`group.v2.pull floor advance: ns=${ns} contiguous=${pageContigBefore} -> effective_floor=${effectiveFloor} retention_floor=${retentionFloor} visibility_floor=${visibilityFloor}`);
                             }
-                        }
-                        if (plaintext) {
-                            plaintext.group_id = gid;
-                            plaintext.group_aid = eventGroupAid;
-                            if (!client._delivery.isSelfSentGroupMessage?.(msg)) {
-                                await client._publishPulledMessage('group.message_created', ns, seq, plaintext, false);
+                            if (deferredServerCursor > pageContigBefore && pageCount === 1) {
+                                client._clientLog.info(`group.v2.pull restore local A from deferred server ACK cursor: group=${gid}, ns=${ns}, contiguous=${pageContigBefore} -> current_seq=${deferredServerCursor}`);
                             }
-                            else {
-                                client._markPublishedSeq(ns, seq);
+                            if (seqs.length > 0) {
+                                client._clientLog.debug(`group.v2.pull force contiguous: group=${gid}, ns=${ns}, page_max_seq=${pageMaxSeq}, previous=${pageContigBefore}`);
                             }
-                            decrypted.push(plaintext);
+                        }
+                        ackSeq = client._seqTracker.getContiguousSeq(ns);
+                        contigAdvanced = ackSeq !== pageContigBefore;
+                        if (contigAdvanced) {
+                            await client._commitSeqTrackerState(ns);
+                            if (pageCount === 1 && deferredServerCursor > 0)
+                                this.clearForwardCursor(ns, ackSeq);
                         }
                     }
-                    client._clientLog.debug(`group.v2.pull skipping V1 envelope group=${gid} seq=${seq} payload_type=${payloadObj ? String(payloadObj.type ?? '') : '<none>'} (V1 E2EE removed)`);
-                    continue;
-                }
-                if (version !== 'v2') {
-                    client._clientLog.debug(`group.v2.pull skipping non-V2 row group=${gid} seq=${seq} version=${String(msg.version ?? '')}`);
-                    continue;
-                }
-                const deferStatus = {};
-                let plaintext = await client._decryptV2Message(msg, true, true, true, true, deferStatus, true, 'pull');
-                if (deferStatus.deferred) {
-                    blockedSeq = blockedSeq > 0 ? Math.min(blockedSeq, seq) : seq;
-                }
-                if (deferStatus.deferred && deferStatus.fromAid) {
-                    const key = `${deferStatus.fromAid}\u0000${deferStatus.senderDeviceId ?? ''}\u0000${deferStatus.groupId ?? ''}`;
-                    deferredKeyFetches.set(key, {
-                        fromAid: deferStatus.fromAid,
-                        senderDeviceId: deferStatus.senderDeviceId ?? '',
-                        groupId: deferStatus.groupId ?? '',
-                    });
+                    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;
+                    }
+                    if (contigAdvanced)
+                        await client._drainOrderedMessages(ns, undefined, false, false);
                 }
-                if (plaintext === null)
-                    continue;
-                plaintext = normalizeGroupMentionMode(plaintext, msg, msg.envelope_json);
-                plaintext.group_id = gid;
-                plaintext.group_aid = eventGroupAid;
-                if (!client._delivery.isSelfSentGroupMessage?.(msg)) {
-                    await client._publishPulledMessage('group.message_created', ns, seq, plaintext, false);
+                for (const fetch of deferredKeyFetches.values()) {
+                    this.scheduleSenderIKFetch(fetch.fromAid, fetch.senderDeviceId, fetch.groupId);
                 }
-                else {
-                    client._markPublishedSeq(ns, seq);
+                client._delivery.onPullPage?.(ns, decrypted.length - pageDecryptedBefore, hasMore, pageMaxSeq, typeof result.remaining === 'number' && Number.isSafeInteger(result.remaining) && result.remaining >= 0 ? result.remaining : null, messages.length, client._seqTracker.getContiguousSeq(ns), pageMaxSeq);
+                if (ownsCursor && parsedCursorCurrentSeq !== null && cursorCurrentSeq > ackSeq) {
+                    this.recordForwardCursor(ns, cursorCurrentSeq, ackSeq);
                 }
-                decrypted.push(plaintext);
-            }
-            const hasServerCursor = cursor !== null && Object.prototype.hasOwnProperty.call(cursor, 'current_seq');
-            const parsedCursorCurrentSeq = hasServerCursor ? safeNonNegativeSeq(cursor?.current_seq) : null;
-            const cursorCurrentSeq = parsedCursorCurrentSeq ?? 0;
-            const retentionFloor = Math.max(Number(result.retention_floor_message_seq ?? result.retention_floor_seq ?? 0), Number(cursor?.retention_floor_seq ?? 0));
-            const visibilityFloor = Math.max(0, Math.max(0, Number(result.earliest_available_message_seq ?? 1) - 1), Number(cursor?.join_seq ?? 0));
-            const effectiveFloor = Math.max(retentionFloor, visibilityFloor);
-            const commitTarget = Math.max(pageContigBefore, Number.isFinite(effectiveFloor) ? effectiveFloor : 0, ownsCursor && pageCount === 1 ? deferredServerCursor : 0, cursorCurrentSeq, blockedSeq > 0 ? blockedSeq - 1 : pageContiguousSeq);
-            let ackSeq = pageContigBefore;
-            let contigAdvanced = false;
-            if (ownsCursor) {
-                try {
-                    if (commitTarget > pageContigBefore) {
-                        client._seqTracker.forceContiguousSeq(ns, commitTarget);
-                        if (effectiveFloor > pageContigBefore) {
-                            client._clientLog.info(`group.v2.pull floor advance: ns=${ns} contiguous=${pageContigBefore} -> effective_floor=${effectiveFloor} retention_floor=${retentionFloor} visibility_floor=${visibilityFloor}`);
-                        }
-                        if (deferredServerCursor > pageContigBefore && pageCount === 1) {
-                            client._clientLog.info(`group.v2.pull restore local A from deferred server ACK cursor: group=${gid}, ns=${ns}, contiguous=${pageContigBefore} -> current_seq=${deferredServerCursor}`);
-                        }
-                        if (seqs.length > 0) {
-                            client._clientLog.debug(`group.v2.pull force contiguous: group=${gid}, ns=${ns}, page_max_seq=${pageMaxSeq}, previous=${pageContigBefore}`);
-                        }
-                    }
-                    ackSeq = client._seqTracker.getContiguousSeq(ns);
-                    contigAdvanced = ackSeq !== pageContigBefore;
-                    if (contigAdvanced) {
-                        await client._commitSeqTrackerState(ns);
-                        if (pageCount === 1 && deferredServerCursor > 0)
-                            this.clearForwardCursor(ns, ackSeq);
+                // 无本页 cursor.current_seq 时，只有本页成功提交了比已知 cursor
+                // 更高的 A 才新增 ACK 义务；空页不得因已有本地 A 重复确认。
+                const knownServerCursorSeq = hasServerCursor
+                    ? cursorCurrentSeq
+                    : (ownsCursor && pageCount === 1 ? deferredServerCursor : 0);
+                const ackNeeded = ackSeq > 0
+                    && ackSeq > lastAutoAckSeq
+                    && ownsCursor
+                    && ((hasServerCursor && ackSeq > cursorCurrentSeq)
+                        || (contigAdvanced && ackSeq > knownServerCursorSeq));
+                if (ackNeeded) {
+                    this.recordForwardAck(ns, ackSeq);
+                    const nextAfter = Math.max(pageContiguousSeq, nextAfterSeq);
+                    const canContinuePage = blockedSeq <= 0 && messages.length > 0 && nextAfter > nextAfterSeq && ownsCursor;
+                    if (canContinuePage && !pipelineRunning) {
+                        pendingAckSeq = Math.max(pendingAckSeq, ackSeq);
+                        lastAutoAckSeq = Math.max(lastAutoAckSeq, ackSeq);
                     }
-                }
-                catch (exc) {
-                    if (typeof client._seqTracker.restoreNamespaceSnapshot === 'function') {
-                        client._seqTracker.restoreNamespaceSnapshot(ns, pageTrackerSnapshot);
+                    else {
+                        await this.confirmForwardGroupAck(gid, ackSeq, groupAid);
+                        lastAutoAckSeq = Math.max(lastAutoAckSeq, ackSeq);
                     }
-                    client._clientLog.error?.(`group.v2.pull Forward commit rolled back: group=${gid} ns=${ns} target=${commitTarget} error=${formatE2EEError(exc)}`);
-                    throw exc;
                 }
-                if (contigAdvanced)
-                    await client._drainOrderedMessages(ns, undefined, false, false);
-            }
-            for (const fetch of deferredKeyFetches.values()) {
-                this.scheduleSenderIKFetch(fetch.fromAid, fetch.senderDeviceId, fetch.groupId);
-            }
-            client._delivery.onPullPage?.(ns, decrypted.length - pageDecryptedBefore, hasMore, pageMaxSeq, typeof result.remaining === 'number' && Number.isSafeInteger(result.remaining) && result.remaining >= 0 ? result.remaining : null, messages.length, client._seqTracker.getContiguousSeq(ns), pageMaxSeq);
-            if (ownsCursor && parsedCursorCurrentSeq !== null && cursorCurrentSeq > ackSeq) {
-                this.recordForwardCursor(ns, cursorCurrentSeq, ackSeq);
-            }
-            // 无本页 cursor.current_seq 时，只有本页成功提交了比已知 cursor
-            // 更高的 A 才新增 ACK 义务；空页不得因已有本地 A 重复确认。
-            const knownServerCursorSeq = hasServerCursor
-                ? cursorCurrentSeq
-                : (ownsCursor && pageCount === 1 ? deferredServerCursor : 0);
-            const ackNeeded = ackSeq > 0
-                && ackSeq > lastAutoAckSeq
-                && ownsCursor
-                && ((hasServerCursor && ackSeq > cursorCurrentSeq)
-                    || (contigAdvanced && ackSeq > knownServerCursorSeq));
-            if (ackNeeded) {
-                this.recordForwardAck(ns, ackSeq);
                 const nextAfter = Math.max(pageContiguousSeq, nextAfterSeq);
-                const canContinuePage = blockedSeq <= 0 && messages.length > 0 && nextAfter > nextAfterSeq && ownsCursor;
-                if (canContinuePage) {
-                    pendingAckSeq = Math.max(pendingAckSeq, ackSeq);
-                    lastAutoAckSeq = Math.max(lastAutoAckSeq, ackSeq);
+                if (!ownsCursor)
+                    break;
+                const rawCount = messages.length;
+                if (blockedSeq > 0)
+                    break;
+                const shouldContinue = shouldContinueForwardPage({
+                    rawCount,
+                    nextAfterSeq,
+                    nextAfter,
+                    limit,
+                    hasMoreField,
+                    hasMore,
+                    serverHead,
+                    pendingAckSeq,
+                    observedUpper: typeof client._seqTracker.getMaxSeenSeq === 'function'
+                        ? client._seqTracker.getMaxSeenSeq(ns) : nextAfter,
+                });
+                const shouldContinueForPipeline = shouldContinueForwardPage({
+                    rawCount,
+                    nextAfterSeq,
+                    nextAfter,
+                    limit,
+                    hasMoreField,
+                    hasMore,
+                    serverHead,
+                    pendingAckSeq: 0,
+                    observedUpper: typeof client._seqTracker.getMaxSeenSeq === 'function'
+                        ? client._seqTracker.getMaxSeenSeq(ns) : nextAfter,
+                });
+                if (!shouldContinue)
+                    break;
+                if (shouldContinueForPipeline && !pipelineRunning && limit >= V2_PULL_MAX_PAGE_LIMIT) {
+                    if (pendingAckSeq > 0) {
+                        await this.confirmForwardGroupAck(gid, pendingAckSeq, groupAid);
+                        pendingAckSeq = 0;
+                    }
+                    startPipeline(nextAfter);
                 }
-                else {
-                    await this.confirmForwardGroupAck(gid, ackSeq, groupAid);
-                    lastAutoAckSeq = Math.max(lastAutoAckSeq, ackSeq);
+                if (!pipelineRunning && pullGateKey && opts?.gateLocked && client._rpcPipeline?.yieldPullGate) {
+                    const nextKey = pullGateKeyForClient(client, 'group.v2.pull', {
+                        group_id: gid, after_seq: nextAfter, force: opts?.force === true, limit,
+                        _group_cursor_params: cursorParams,
+                    }, `${ns}|forward|after=${nextAfter}|force=${String(Boolean(opts?.force))}|limit=${limit}`);
+                    await client._rpcPipeline.yieldPullGate(pullGateKey, nextKey, true);
+                    pullGateKey = nextKey;
                 }
+                const tailDelayMs = v2PullTailDelayMs(rawCount, limit);
+                if (tailDelayMs > 0)
+                    await v2Sleep(tailDelayMs);
+                nextAfterSeq = nextAfter;
             }
-            const nextAfter = Math.max(pageContiguousSeq, nextAfterSeq);
-            if (!ownsCursor)
-                break;
-            const rawCount = messages.length;
-            if (blockedSeq > 0)
-                break;
-            const shouldContinue = shouldContinueForwardPage({
-                rawCount,
-                nextAfterSeq,
-                nextAfter,
-                limit,
-                hasMoreField,
-                hasMore,
-                serverHead,
-                pendingAckSeq,
-                observedUpper: typeof client._seqTracker.getMaxSeenSeq === 'function'
-                    ? client._seqTracker.getMaxSeenSeq(ns) : nextAfter,
-            });
-            if (!shouldContinue)
-                break;
-            if (pullGateKey && opts?.gateLocked && client._rpcPipeline?.yieldPullGate) {
-                const nextKey = pullGateKeyForClient(client, 'group.v2.pull', {
-                    group_id: gid, after_seq: nextAfter, force: opts?.force === true, limit,
-                    _group_cursor_params: cursorParams,
-                }, `${ns}|forward|after=${nextAfter}|force=${String(Boolean(opts?.force))}|limit=${limit}`);
-                await client._rpcPipeline.yieldPullGate(pullGateKey, nextKey, true);
-                pullGateKey = nextKey;
-            }
-            const tailDelayMs = v2PullTailDelayMs(rawCount, limit);
-            if (tailDelayMs > 0)
-                await v2Sleep(tailDelayMs);
-            nextAfterSeq = nextAfter;
+        }
+        finally {
+            await stopPipeline();
         }
         if (pageCount >= maxPages) {
             client._clientLog.warn(`group.v2.pull reached max_pages=${maxPages} group=${gid} after_seq=${nextAfterSeq}`);
@@ -2546,7 +2979,6 @@ export class V2E2EECoordinator {
             seq: msg.seq ?? null,
             timestamp: msg.timestamp ?? msg.t_server ?? null,
             device_id: msg.device_id ?? null,
-            slot_id: msg.slot_id ?? null,
             _decrypt_error: 'encrypted push payload is not decryptable on raw push path',
             _decrypt_stage: 'push_envelope',
         };
@@ -2590,13 +3022,18 @@ export class V2E2EECoordinator {
             encrypted: true,
             e2ee: e2eeMeta,
         };
-        result.direction = fromAid && fromAid === client._aid ? 'outbound_sync' : 'inbound';
+        const senderDeviceId = String(aad.from_device ?? '').trim();
+        if (senderDeviceId)
+            result.sender_device_id = senderDeviceId;
+        const direction = String(msg.direction ?? '').trim();
+        if (direction)
+            result.direction = direction;
+        else if (fromAid && fromAid !== client._aid)
+            result.direction = 'inbound';
         if (msg.t_server !== undefined)
             result.t_server = msg.t_server;
         if (msg.device_id !== undefined)
             result.device_id = msg.device_id;
-        if (msg.slot_id !== undefined)
-            result.slot_id = msg.slot_id;
         attachGatewayProximity(result, msg);
         if (group) {
             result.group_id = msg.group_id ?? aad.group_id ?? envelope.group_id ?? null;
@@ -2674,6 +3111,10 @@ export class V2E2EECoordinator {
         if (peerDevices.length === 0) {
             throw new E2EEError(`V2 bootstrap: no devices found for ${to}`);
         }
+        const targetDeviceId = String(opts.deviceId ?? '').trim();
+        if (targetDeviceId && !peerDevices.some((dev) => String(dev.device_id ?? '').trim() === targetDeviceId)) {
+            throw new E2EEError(`V2 bootstrap: target device ${targetDeviceId} not found for ${to}`);
+        }
         let targetSet = useCache ? this.getTargetSetCache(to) : undefined;
         if (targetSet) {
             targetSet = this.cloneP2PTargetSet(targetSet);
@@ -2751,6 +3192,20 @@ export class V2E2EECoordinator {
             });
             targetSet = this.cloneP2PTargetSet(targetSet);
         }
+        if (targetDeviceId) {
+            let peerTargetFound = false;
+            targetSet.targets = targetSet.targets.filter((target) => {
+                const isPeerTarget = target.aid === to
+                    && (target.deviceId === targetDeviceId || (wrapPolicy?.scope === 'aid' && !target.deviceId))
+                    && target.role !== 'self_sync';
+                if (isPeerTarget)
+                    peerTargetFound = true;
+                return isPeerTarget || target.role === 'self_sync';
+            });
+            if (!peerTargetFound) {
+                throw new E2EEError(`V2 bootstrap: target device ${targetDeviceId} not found for ${to}`);
+            }
+        }
         const sender = await session.getSenderIdentity();
         const envelope = await encryptP2PMessage(sender, targetSet, opts.payload, { messageId: opts.messageId, timestamp: opts.timestamp, protectedHeaders: opts.protectedHeaders, context: opts.context });
         return envelope;