@agentunion/fastaun-browser 0.4.6 → 0.4.8

package/dist/client.js

@@ -4,46 +4,31 @@
 //   - HTTP 使用 fetch() 而非 Node http
 //   - 无文件系统（IndexedDB via keystore）
 //   - 后台任务使用 setTimeout/setInterval
-import { createConfig, getDeviceId, normalizeSlotId, slotIsolationKey } from './config.js';
+import { createConfig, getDeviceId, normalizeSlotId } from './config.js';
 import { EventDispatcher } from './events.js';
 import { normalizeGroupId } from './group-id.js';
 import { GatewayDiscovery } from './discovery.js';
 import { RPCTransport } from './transport.js';
 import { AuthFlow } from './auth.js';
 import { SeqTracker } from './seq-tracker.js';
-import { CryptoProvider, uint8ToBase64, base64ToUint8, pemToArrayBuffer, p1363ToDer, certificateSha256Fingerprint, ecdsaSignDer, ecdsaVerifyDer, importCertPublicKeyEcdsa, importPrivateKeyEcdsa, } from './crypto.js';
+import { ClientRuntime } from './client/runtime.js';
+import { MessageDeliveryEngine } from './client/delivery.js';
+import { IdentityRuntimeManager } from './client/identity.js';
+import { LifecycleController } from './client/lifecycle.js';
+import { PeerDirectory } from './client/peers.js';
+import { RpcPipeline } from './client/rpc-pipeline.js';
+import { V2E2EECoordinator } from './client/v2-e2ee.js';
+import { GroupStateCoordinator } from './client/group-state.js';
+import { CryptoProvider, base64ToUint8, pemToArrayBuffer, ecdsaVerifyDer, importCertPublicKeyEcdsa, } from './crypto.js';
 import { IndexedDBTokenStore } from './keystore/indexeddb-token-store.js';
-import { V2Session, V2KeyStore } from './v2/session/index.js';
-import { encryptP2PMessage, encryptGroupMessage, decryptMessage, } from './v2/e2ee/index.js';
+import { decryptMessage, } from './v2/e2ee/index.js';
 import { ecdsaVerifyRaw } from './v2/crypto/ecdsa.js';
-import { computeStateCommitment } from './v2/state/index.js';
 import { AUNLogger } from './logger.js';
 import { AgentMdManager } from './agent-md.js';
+import { certMatchesFingerprint, normalizeFingerprintHex } from './cert-utils.js';
 import { AUNError, AuthError, ConnectionError, E2EEError, NotFoundError, PermissionError, StateError, ValidationError, } from './errors.js';
 import { isJsonObject, ConnectionState, STATE_TO_PUBLIC, } from './types.js';
 import { AID } from './aid.js';
-/**
- * 递归排序键的 JSON 序列化（Canonical JSON for AUN）
- * 等价于 Python json.dumps(sort_keys=True, separators=(",",":"), ensure_ascii=False)
- * 非 ASCII 字符直接以 UTF-8 输出。
- */
-function stableStringify(obj) {
-    if (obj === null || obj === undefined)
-        return 'null';
-    if (typeof obj === 'boolean' || typeof obj === 'number')
-        return JSON.stringify(obj);
-    if (typeof obj === 'string')
-        return JSON.stringify(obj);
-    if (Array.isArray(obj)) {
-        return '[' + obj.map(v => stableStringify(v)).join(',') + ']';
-    }
-    if (isJsonObject(obj)) {
-        const keys = Object.keys(obj).sort();
-        const entries = keys.map(k => stableStringify(k) + ':' + stableStringify(obj[k]));
-        return '{' + entries.join(',') + '}';
-    }
-    return JSON.stringify(obj);
-}
 function getV2DeviceId(dev) {
     if (Object.prototype.hasOwnProperty.call(dev, 'device_id')) {
         return { present: true, value: String(dev.device_id ?? '').trim() };
@@ -61,107 +46,22 @@ function isAIDObject(value) {
         && typeof candidate.aunPath === 'string'
         && typeof candidate.isPrivateKeyValid === 'function');
 }
-function sortObjectKeys(obj) {
-    if (obj === null || obj === undefined || typeof obj !== 'object')
-        return obj;
-    if (Array.isArray(obj))
-        return obj.map(sortObjectKeys);
-    const sorted = {};
-    for (const key of Object.keys(obj).sort()) {
-        sorted[key] = sortObjectKeys(obj[key]);
-    }
-    return sorted;
-}
-function uint64BE(value) {
-    const buf = new ArrayBuffer(8);
-    new DataView(buf).setBigUint64(0, BigInt(value), false);
-    return new Uint8Array(buf);
-}
-function hexToBytes(hex) {
-    const clean = hex.trim();
-    if (!clean)
-        return new Uint8Array(0);
-    if (clean.length % 2 !== 0)
-        throw new ValidationError('invalid hex length');
-    const out = new Uint8Array(clean.length / 2);
-    for (let i = 0; i < out.length; i++) {
-        out[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
-    }
-    return out;
-}
 function bytesToHex(bytes) {
     return Array.from(bytes).map((b) => b.toString(16).padStart(2, '0')).join('');
 }
-async function computeStateHash(params) {
-    const sortedMembers = [...params.members].sort((a, b) => a.aid.localeCompare(b.aid));
-    const membershipBlock = sortedMembers.map((m) => `${m.aid}:${m.role}`).join('|');
-    const policyBlock = Object.keys(params.policy).length > 0
-        ? JSON.stringify(sortObjectKeys(params.policy))
-        : '';
-    const prevBytes = params.prevStateHash ? hexToBytes(params.prevStateHash) : new Uint8Array(32);
-    const sep = new Uint8Array([0x00]);
-    const encoder = new TextEncoder();
-    const chunks = [
-        encoder.encode(params.groupId), sep,
-        uint64BE(params.stateVersion), sep,
-        uint64BE(params.keyEpoch), sep,
-        encoder.encode(membershipBlock), sep,
-        encoder.encode(policyBlock), sep,
-        prevBytes,
-    ];
-    const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
-    const data = new Uint8Array(total);
-    let offset = 0;
-    for (const chunk of chunks) {
-        data.set(chunk, offset);
-        offset += chunk.length;
+function exactArrayBuffer(bytes) {
+    return bytes.slice().buffer;
+}
+function attachGatewayProximity(message, source) {
+    if (isJsonObject(source.proximity)) {
+        message.proximity = { ...source.proximity };
+    }
+    for (const key of ['same_device', 'same_network', 'same_egress_ip']) {
+        if (Object.prototype.hasOwnProperty.call(source, key)) {
+            message[key] = source[key];
+        }
     }
-    const digest = await crypto.subtle.digest('SHA-256', data);
-    return bytesToHex(new Uint8Array(digest));
 }
-/** 内部专用方法（禁止用户直接调用） */
-const INTERNAL_ONLY_METHODS = new Set([
-    'auth.login1',
-    'auth.aid_login1',
-    'auth.login2',
-    'auth.aid_login2',
-    'auth.connect',
-    'auth.refresh_token',
-    'initialize',
-]);
-/** 已移除的旧版 E2EE RPC。 */
-const REMOVED_E2EE_METHODS = new Set([
-    'group.rotate_epoch',
-]);
-/** 需要客户端签名的关键方法 */
-const SIGNED_METHODS = new Set([
-    'message.send',
-    'message.v2.put_peer_pk', 'message.v2.bootstrap',
-    'message.v2.group_bootstrap', 'message.v2.pull',
-    'message.v2.ack',
-    'group.send',
-    'group.v2.put_group_pk', 'group.v2.bootstrap',
-    'group.v2.send', 'group.v2.pull', 'group.v2.ack',
-    'group.v2.propose_state', 'group.v2.confirm_state',
-    'group.v2.get_proposal',
-    'group.kick', 'group.add_member',
-    'group.leave', 'group.remove_member', 'group.update_rules',
-    'group.update', 'group.update_announcement',
-    'group.update_join_requirements', 'group.set_role',
-    'group.transfer_owner', 'group.review_join_request',
-    'group.batch_review_join_request',
-    'group.request_join', 'group.use_invite_code',
-    'group.thought.put',
-    'message.thought.put',
-    'group.set_settings',
-    'group.resources.put', 'group.resources.update',
-    'group.resources.delete', 'group.resources.request_add',
-    'group.resources.direct_add', 'group.resources.approve_request',
-    'group.resources.reject_request',
-    'group.commit_state',
-    'group.ban', 'group.unban',
-    'group.dissolve', 'group.suspend', 'group.resume',
-]);
 const DEFAULT_SESSION_OPTIONS = {
     auto_reconnect: true,
     heartbeat_interval: 30.0,
@@ -178,31 +78,9 @@ const DEFAULT_SESSION_OPTIONS = {
         http: 30.0,
     },
 };
-const PUBLIC_CONNECTION_OPTION_KEYS = new Set([
-    'auto_reconnect',
-    'connect_timeout',
-    'retry_initial_delay',
-    'retry_max_delay',
-    'retry_max_attempts',
-    'heartbeat_interval',
-    'call_timeout',
-    'connection_kind',
-    'short_ttl_ms',
-    'delivery_mode',
-    'extra_info',
-    'background_sync',
-]);
-const PROTECTED_HEADERS_METHODS = new Set([
-    'message.send',
-    'group.send',
-    'message.thought.put',
-    'group.thought.put',
-]);
 const RECONNECT_MIN_BASE_DELAY_SECONDS = 1.0;
 const RECONNECT_MAX_BASE_DELAY_SECONDS = 64.0;
 const TOKEN_REFRESH_CHECK_INTERVAL_MS = 30_000;
-const PUSHED_SEQS_LIMIT = 50_000;
-const PENDING_ORDERED_LIMIT = 50_000;
 // 心跳间隔下/上限（秒）。0 = 关闭心跳；负值视为 0；其余值 clamp 到 [10, 600]。
 // 服务端通过 hello.heartbeat_interval 与 meta.ping pong 中的同名字段下发。
 const HEARTBEAT_MIN_INTERVAL_SECONDS = 10;
@@ -229,6 +107,35 @@ const NON_IDEMPOTENT_METHODS = new Set([
     'message.thought.put', 'group.thought.put',
     'group.add_member',
 ]);
+/** 需要客户端签名的关键方法。运行时逻辑已迁入 RpcPipeline，此处保留给源码审计测试。 */
+const SIGNED_METHODS = new Set([
+    'message.send',
+    'message.v2.put_peer_pk', 'message.v2.bootstrap',
+    'message.v2.group_bootstrap', 'message.v2.pull',
+    'message.v2.ack',
+    'group.send',
+    'group.v2.put_group_pk', 'group.v2.bootstrap',
+    'group.v2.send', 'group.v2.pull', 'group.v2.ack',
+    'group.v2.propose_state', 'group.v2.confirm_state',
+    'group.v2.get_proposal',
+    'group.kick', 'group.add_member',
+    'group.leave', 'group.remove_member', 'group.update_rules',
+    'group.update', 'group.update_announcement',
+    'group.update_join_requirements', 'group.set_role',
+    'group.transfer_owner', 'group.review_join_request',
+    'group.batch_review_join_request',
+    'group.request_join', 'group.use_invite_code',
+    'group.thought.put',
+    'message.thought.put',
+    'group.set_settings',
+    'group.resources.put', 'group.resources.update',
+    'group.resources.delete', 'group.resources.request_add',
+    'group.resources.direct_add', 'group.resources.approve_request',
+    'group.resources.reject_request',
+    'group.commit_state',
+    'group.ban', 'group.unban',
+    'group.dissolve', 'group.suspend', 'group.resume',
+]);
 function clampReconnectDelaySeconds(value, fallback, upper = RECONNECT_MAX_BASE_DELAY_SECONDS) {
     const parsed = Number(value);
     const seconds = Number.isFinite(parsed) ? parsed : fallback;
@@ -328,21 +235,22 @@ function createAgentMdManagerForRuntime(opts) {
             opts.identity.set(await auth.loadIdentityOrNone(target) ?? fallbackIdentity);
             return token;
         },
-        peerResolver: async (aid) => {
+        peerResolver: async (aid, certFingerprint) => {
             const target = String(aid ?? '').trim();
+            const expectedFp = String(certFingerprint ?? '').trim().toLowerCase();
             const current = opts.currentAid();
-            if (current?.aid === target)
-                return current;
-            let certPem = String(await opts.tokenStore().loadCert(target) ?? '').trim();
-            if (!certPem) {
-                if (!opts.gateway.get()) {
-                    try {
-                        opts.gateway.set(await opts.gateway.resolve(target));
-                    }
-                    catch { /* best effort */ }
+            if (current?.aid === target) {
+                if (!expectedFp || await certMatchesFingerprint(current.certPem, expectedFp))
+                    return current;
+                throw new StateError(`current AID certificate fingerprint mismatch for ${target}`);
+            }
+            if (!opts.gateway.get()) {
+                try {
+                    opts.gateway.set(await opts.gateway.resolve(target));
                 }
-                certPem = String(await opts.fetchPeerCert(target) ?? '').trim();
+                catch { /* best effort */ }
             }
+            const certPem = String(await opts.fetchPeerCert(target, expectedFp || undefined) ?? '').trim();
             if (!certPem)
                 throw new NotFoundError(`certificate not found for aid: ${target}`);
             return await AID.create({
@@ -374,80 +282,6 @@ function resolvePeerGatewayUrl(localGatewayUrl, peerAid) {
         return localGatewayUrl;
     return localGatewayUrl.replace(`gateway.${localIssuer}`, `gateway.${peerIssuer}`);
 }
-function isGroupServiceAid(value) {
-    const text = String(value ?? '').trim();
-    if (!text.includes('.'))
-        return false;
-    const [name, ...issuerParts] = text.split('.');
-    return name === 'group' && issuerParts.join('.').length > 0;
-}
-function normalizeV2WrapPolicy(raw) {
-    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
-        return undefined;
-    const obj = raw;
-    let protocol = String(obj.protocol ?? '').trim().toUpperCase();
-    let scope = String(obj.scope ?? '').trim().toLowerCase();
-    if (scope !== 'aid' && scope !== 'device') {
-        if (obj.per_aid_wrap === true)
-            scope = 'aid';
-        else if (obj.per_device_wrap === true)
-            scope = 'device';
-        else
-            scope = '';
-    }
-    if (protocol !== '1DH' && protocol !== '3DH')
-        protocol = '';
-    if (scope === 'aid')
-        protocol = '1DH';
-    if (!protocol && !scope)
-        return undefined;
-    return {
-        protocol: protocol ? protocol : undefined,
-        scope: scope ? scope : undefined,
-    };
-}
-function v2WrapCapabilities() {
-    return {
-        version: 'v2.1',
-        protocols: ['1DH', '3DH'],
-        scopes: ['aid', 'device'],
-        per_aid_wrap: true,
-        per_device_wrap: true,
-    };
-}
-function applyV2WrapPolicyToTargets(targets, policy) {
-    if (!policy)
-        return targets;
-    const normalized = targets.map((target) => {
-        const row = { ...target };
-        if (policy.protocol === '1DH') {
-            row.keySource = 'aid_master';
-            row.spkPkDer = undefined;
-            row.spkId = '';
-        }
-        return row;
-    });
-    if (policy.scope !== 'aid')
-        return normalized;
-    const collapsed = new Map();
-    for (const target of normalized) {
-        const key = `${target.aid}\u0000${target.role}`;
-        if (!collapsed.has(key)) {
-            collapsed.set(key, { ...target, deviceId: '' });
-        }
-    }
-    return Array.from(collapsed.values());
-}
-/** 32 字节左侧零填充（用于 P-256 私钥 scalar 规范化） */
-function _v2LeftPad32(b) {
-    if (b.length === 32)
-        return b;
-    if (b.length > 32)
-        return b.subarray(b.length - 32);
-    const out = new Uint8Array(32);
-    out.set(b, 32 - b.length);
-    return out;
-}
 /** Base64 (标准) → Uint8Array */
 function _v2B64ToBytes(s) {
     const bin = atob(s);
@@ -481,24 +315,6 @@ function _v2ConcatBytes(...parts) {
     }
     return out;
 }
-function _v2LengthPrefixedTextKey(...parts) {
-    const enc = new TextEncoder();
-    return parts.map((part) => `${enc.encode(part).length}:${part};`).join('');
-}
-function _v2LengthPrefixedBytes(...parts) {
-    const enc = new TextEncoder();
-    const framed = [];
-    for (const part of parts) {
-        framed.push(enc.encode(`${part.length}:`), part, enc.encode(';'));
-    }
-    return _v2ConcatBytes(...framed);
-}
-/** Base64URL → Uint8Array（兼容缺失 padding） */
-function _v2B64uToBytes(s) {
-    const std = s.replace(/-/g, '+').replace(/_/g, '/');
-    const pad = std.length % 4 === 0 ? '' : '='.repeat(4 - (std.length % 4));
-    return _v2B64ToBytes(std + pad);
-}
 function formatCaughtError(error) {
     return error instanceof Error ? error : String(error);
 }
@@ -564,85 +380,6 @@ function extractV2EnvelopeFromSource(source) {
     }
     return null;
 }
-function truthyBool(value) {
-    if (value === true || value === 1)
-        return true;
-    if (typeof value === 'string') {
-        const normalized = value.trim().toLowerCase();
-        return normalized === 'true' || normalized === '1' || normalized === 'yes' || normalized === 'on';
-    }
-    return false;
-}
-function isEncryptedEnvelopePayload(payload) {
-    if (!isJsonObject(payload))
-        return false;
-    const payloadType = String(payload.type ?? '').trim();
-    if (payloadType.startsWith('e2ee.'))
-        return true;
-    if (!String(payload.ciphertext ?? '').trim())
-        return false;
-    return payload.nonce !== undefined
-        || payload.tag !== undefined
-        || payload.recipient !== undefined
-        || payload.recipients !== undefined
-        || payload.wrapped_key !== undefined
-        || payload.recipients_digest !== undefined;
-}
-function encryptedPushEnvelope(msg) {
-    if (isEncryptedEnvelopePayload(msg.payload))
-        return msg.payload;
-    if (typeof msg.envelope_json === 'string' && msg.envelope_json.trim()) {
-        try {
-            const parsed = JSON.parse(msg.envelope_json);
-            if (isEncryptedEnvelopePayload(parsed))
-                return parsed;
-        }
-        catch {
-            return null;
-        }
-    }
-    return null;
-}
-function isEncryptedPushMessage(msg) {
-    if (truthyBool(msg.encrypted))
-        return true;
-    return encryptedPushEnvelope(msg) !== null;
-}
-function isV2EncryptedEnvelopePayload(envelope) {
-    if (!envelope)
-        return false;
-    const payloadType = String(envelope.type ?? '').trim();
-    if (payloadType === 'e2ee.p2p_encrypted' || payloadType === 'e2ee.group_encrypted')
-        return true;
-    return String(envelope.version ?? '').trim().toLowerCase() === 'v2' && payloadType.startsWith('e2ee.');
-}
-function safeUndecryptablePushEvent(msg, group) {
-    const event = {
-        message_id: msg.message_id ?? null,
-        from: msg.from ?? null,
-        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',
-    };
-    if (group) {
-        event.group_id = msg.group_id ?? null;
-    }
-    else {
-        event.to = msg.to ?? null;
-    }
-    const envelope = encryptedPushEnvelope(msg);
-    if (envelope) {
-        event._envelope_type = String(envelope.type ?? '');
-        event._suite = String(envelope.suite ?? '');
-        if (isV2EncryptedEnvelopePayload(envelope)) {
-            attachV2EnvelopeMetadata(event, v2E2eeMeta(envelope));
-        }
-    }
-    return event;
-}
 function metadataWithoutAuth(value) {
     if (!isJsonObject(value))
         return null;
@@ -740,15 +477,13 @@ export class AUNClient {
     _v2Session;
     _v2KeyStore;
     _v2SessionInitInFlight = null;
+    _v2RuntimeGeneration = 0;
     _v2BootstrapCache = new Map();
     _v2SenderIKPending = new Map();
     _v2SenderIKFetching = new Set();
     static V2_BOOTSTRAP_TTL_MS = 60 * 60 * 1000;
-    static V2_RETRYABLE_CODES = new Set([-33011, -33012, -33050, -33052, -33054]);
     /** V2 state 签名验证缓存：cacheKey(hex) → expiry_unix_ms */
     _v2SigCache = new Map();
-    static _V2_SIG_CACHE_TTL = 60 * 60 * 1000;
-    static _V2_SIG_CACHE_MAX = 16384;
     /** V2 state chain 本地记录：group_id → [state_version, chain_hash] */
     _v2StateChains = new Map();
     /** 群安全等级追踪（变化时发布 group.v2.security_level 事件） */
@@ -773,11 +508,16 @@ export class AUNClient {
     _pendingOrderedMsgs = new Map();
     /** Lazy group sync：首次发送群消息前自动拉取历史 */
     _groupSynced = new Set();
+    /** 在线未读 hint 队列：同一 group 只保留最后一条，延迟 drain 降低登录瞬时拉取压力。 */
+    _onlineUnreadHintQueue = new Map();
+    _onlineUnreadHintTimer = null;
+    _onlineUnreadHintDrainActive = false;
+    _onlineUnreadHintInitialDelayMs = 750;
+    _onlineUnreadHintIntervalMs = 50;
     /** gap fill 来源标记：true 表示当前正在补洞（pull 触发），false 表示非补洞 */
     _gapFillActive = false;
     // Pull Gate：序列化同一 key 的并发 pull 操作，防止重复拉取
     _pullGates = new Map();
-    static _PULL_GATE_STALE_MS = 30000;
     // 重连相关
     _reconnectActive = false;
     _reconnectAbort = null;
@@ -803,6 +543,14 @@ export class AUNClient {
     _tokenStoreLog;
     _logDiscovery;
     _logEvents;
+    _runtime;
+    _identityRuntime;
+    _peerDirectory;
+    _lifecycle;
+    _rpcPipeline;
+    _delivery;
+    _v2E2EE;
+    _groupState;
     constructor(aid) {
         if (aid !== null && aid !== undefined && !isAIDObject(aid)) {
             throw new ValidationError('AUNClient only accepts an AID object or no argument');
@@ -862,7 +610,7 @@ export class AUNClient {
             },
             auth: () => this._auth,
             tokenStore: () => this._tokenStore,
-            fetchPeerCert: (target) => this._fetchPeerCert(target),
+            fetchPeerCert: (target, certFingerprint) => this._fetchPeerCert(target, certFingerprint || undefined),
         });
         this._transport = new RPCTransport({
             eventDispatcher: this._dispatcher,
@@ -874,6 +622,14 @@ export class AUNClient {
                 this._clientLog.debug(`agent.md meta observer skipped: ${String(exc)}`);
             });
         });
+        this._runtime = new ClientRuntime(this);
+        this._identityRuntime = new IdentityRuntimeManager(this._runtime);
+        this._peerDirectory = new PeerDirectory(this._runtime);
+        this._lifecycle = new LifecycleController(this._runtime);
+        this._rpcPipeline = new RpcPipeline(this._runtime);
+        this._delivery = new MessageDeliveryEngine(this._runtime);
+        this._v2E2EE = new V2E2EECoordinator(this._runtime);
+        this._groupState = new GroupStateCoordinator(this._runtime);
         if (inputAid) {
             if (inputAid.isPrivateKeyValid()) {
                 this._currentAid = inputAid;
@@ -884,7 +640,7 @@ export class AUNClient {
                     cert: inputAid.certPem,
                 };
                 this._auth.setIdentity(this._identity);
-                this._state = 'disconnected';
+                this._state = 'standby';
             }
         }
         // 注入 logger 到各子模块（构造时未传 logger，构造后通过 setLogger 注入）
@@ -947,9 +703,6 @@ export class AUNClient {
     get aid() {
         return this._aid;
     }
-    async uploadAgentMd(content) {
-        return await this._agentMdManager.upload(content);
-    }
     async _observeAgentMdFromEnvelope(envelope) {
         await this._agentMdManager.observeEnvelope(envelope);
     }
@@ -1005,7 +758,53 @@ export class AUNClient {
     get lastError() { return this._lastError; }
     /** 最近一次错误码（对齐 Python last_error_code） */
     get lastErrorCode() { return this._lastErrorCode; }
+    _v2SessionMatchesIdentity() {
+        if (!this._v2Session)
+            return false;
+        const session = this._v2Session;
+        if (session.currentIkPubDer === undefined)
+            return true;
+        return session.aid === this._aid && session.deviceId === this._deviceId;
+    }
+    _resetV2IdentityRuntime() {
+        this._v2RuntimeGeneration += 1;
+        const keyStore = this._v2KeyStore;
+        try {
+            keyStore?.close?.();
+        }
+        catch (exc) {
+            this._clientLog?.debug?.(`V2 keystore cleanup skipped: ${exc instanceof Error ? exc.message : String(exc)}`);
+        }
+        this._v2Session = undefined;
+        this._v2KeyStore = undefined;
+        this._v2SessionInitInFlight = null;
+        this._v2BootstrapCache.clear();
+        this._v2SenderIKPending.clear();
+        this._v2SenderIKFetching.clear();
+        this._v2SigCache.clear();
+        this._v2StateChains.clear();
+        this._v2GroupSecurityLevels.clear();
+        this._v2AutoProposeInflight.clear();
+        this._v2AutoProposePending.clear();
+        this._v2AutoProposeLastSnapshot.clear();
+        this._v2LazyProposeTriggered.clear();
+        this._v2PullInflight = false;
+        this._v2PullPending = false;
+    }
     _applyAidRuntimeContext(aid) {
+        const oldTransport = this._transport;
+        try {
+            const closeResult = oldTransport?.close?.();
+            if (closeResult && typeof closeResult.catch === 'function') {
+                void closeResult.catch((exc) => {
+                    this._clientLog.debug(`old transport cleanup skipped: ${exc instanceof Error ? exc.message : String(exc)}`);
+                });
+            }
+        }
+        catch (exc) {
+            this._clientLog.debug(`old transport cleanup skipped: ${exc instanceof Error ? exc.message : String(exc)}`);
+        }
+        this._resetV2IdentityRuntime();
         const nextConfig = createConfig({
             aunPath: aid.aunPath,
             rootCaPem: aid.rootCaPath,
@@ -1055,7 +854,7 @@ export class AUNClient {
             },
             auth: () => this._auth,
             tokenStore: () => this._tokenStore,
-            fetchPeerCert: (target) => this._fetchPeerCert(target),
+            fetchPeerCert: (target, certFingerprint) => this._fetchPeerCert(target, certFingerprint || undefined),
         });
         this._transport = new RPCTransport({
             eventDispatcher: this._dispatcher,
@@ -1078,25 +877,7 @@ export class AUNClient {
         }
     }
     loadIdentity(aid) {
-        if (!aid?.isPrivateKeyValid())
-            throw new StateError('loadIdentity requires an AID with a valid private key');
-        const publicState = this.state;
-        if (publicState !== ConnectionState.NO_IDENTITY && publicState !== ConnectionState.CLOSED) {
-            throw new StateError(`loadIdentity not allowed in state ${publicState}`);
-        }
-        this._applyAidRuntimeContext(aid);
-        this._currentAid = aid;
-        this._aid = aid.aid;
-        this._identity = {
-            aid: aid.aid,
-            private_key_pem: aid.privateKeyPem,
-            public_key_der_b64: aid.publicKey,
-            cert: aid.certPem,
-        };
-        // 注入内存私钥到 AuthFlow，禁止 AuthFlow 内部再走 keystore 解密
-        this._auth.setIdentity(this._identity);
-        this._state = 'disconnected';
-        this._closing = false;
+        this._identityRuntime.loadIdentity(aid);
     }
     setProtectedHeaders(headers) {
         if (!headers) {
@@ -1115,33 +896,16 @@ export class AUNClient {
         return this._instanceProtectedHeaders ? { ...this._instanceProtectedHeaders } : null;
     }
     cachePeer(aid) {
-        if (!this.hasIdentity)
-            throw new StateError('cachePeer requires a loaded identity');
-        if (!aid.isCertValid())
-            throw new ValidationError('cachePeer requires an AID with a valid certificate');
-        this._peerCache.set(aid.aid, aid);
-        return aid;
+        return this._peerDirectory.cachePeer(aid);
     }
     getPeer(aid) {
-        if (!this.hasIdentity)
-            throw new StateError('getPeer requires a loaded identity');
-        return this._peerCache.get(String(aid ?? '').trim()) ?? null;
+        return this._peerDirectory.getPeer(aid);
     }
     async lookupPeer(aid) {
-        if (!this.hasIdentity)
-            throw new StateError('lookupPeer requires a loaded identity');
-        const target = String(aid ?? '').trim();
-        if (!target)
-            throw new ValidationError('lookupPeer requires non-empty aid');
-        const cached = this._peerCache.get(target);
-        if (cached)
-            return cached;
-        throw new NotFoundError(`peer not found in cache: ${target}`);
+        return this._peerDirectory.lookupPeer(aid);
     }
     peers() {
-        if (!this.hasIdentity)
-            throw new StateError('peers requires a loaded identity');
-        return [...this._peerCache.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([, v]) => v);
+        return this._peerDirectory.peers();
     }
     get gatewayUrl() {
         return this._gatewayUrl;
@@ -1156,130 +920,28 @@ export class AUNClient {
     // ── 生命周期 ──────────────────────────────────────
     /** 仅认证当前身份，获取/刷新 token，但不建立长连接。 */
     async authenticate(options = {}) {
-        const tStart = Date.now();
-        const target = this._currentAid?.aid ?? this._aid ?? '';
-        if (!target || !this._currentAid?.isPrivateKeyValid()) {
-            throw new StateError('authenticate requires a loaded AID with a valid private key');
-        }
-        const publicState = this.state;
-        if (publicState !== ConnectionState.STANDBY) {
-            throw new StateError(`authenticate not allowed in state ${publicState}`);
-        }
-        if ('aid' in options || 'access_token' in options || 'token' in options || 'kite_token' in options) {
-            throw new ValidationError('authenticate options must not include aid or token fields; load an AID object first');
-        }
-        this._state = 'connecting';
-        try {
-            const gateway = String(options.gateway ?? this._gatewayUrl ?? await this._resolveGatewayForAid(target)).trim();
-            const result = await this._auth.authenticate(gateway, target);
-            this._gatewayUrl = String(result.gateway ?? gateway);
-            this._identity = await this._auth.loadIdentityOrNone(target);
-            this._state = 'authenticated';
-            this._clientLog.debug(`authenticate exit: elapsed=${Date.now() - tStart}ms aid=${target}`);
-            return result;
-        }
-        catch (err) {
-            this._state = 'disconnected';
-            this._clientLog.debug(`authenticate exit (error): elapsed=${Date.now() - tStart}ms err=${err instanceof Error ? err.message : String(err)}`);
-            throw err;
-        }
+        return this._lifecycle.authenticate(options);
     }
     /** 连接到 Gateway；身份来自构造函数或 loadIdentity(aid)，认证由 SDK 内部自动完成。 */
     async connect(opts) {
-        const tStart = Date.now();
-        if (opts !== undefined && opts !== null && typeof opts === 'object') {
-            const raw = opts;
-            const invalid = Object.keys(raw).filter((key) => !PUBLIC_CONNECTION_OPTION_KEYS.has(key)).sort();
-            if (invalid.length > 0) {
-                throw new ValidationError(`connect options contain unsupported field(s): ${invalid.join(', ')}`);
-            }
-        }
-        const target = this._currentAid?.aid ?? this._aid ?? '';
-        if (!target || !this._currentAid?.isPrivateKeyValid()) {
-            throw new StateError('connect requires a loaded AID with a valid private key');
-        }
-        const options = {};
-        if (opts?.auto_reconnect !== undefined)
-            options.auto_reconnect = opts.auto_reconnect;
-        if (opts?.heartbeat_interval !== undefined)
-            options.heartbeat_interval = opts.heartbeat_interval;
-        if (opts?.connect_timeout !== undefined || opts?.call_timeout !== undefined) {
-            options.timeouts = {
-                ...(opts.connect_timeout !== undefined ? { connect: opts.connect_timeout } : {}),
-                ...(opts.call_timeout !== undefined ? { call: opts.call_timeout } : {}),
-            };
-        }
-        if (opts?.retry_initial_delay !== undefined || opts?.retry_max_delay !== undefined || opts?.retry_max_attempts !== undefined) {
-            options.retry = {
-                initial_delay: opts.retry_initial_delay ?? 1,
-                max_delay: opts.retry_max_delay ?? 64,
-                max_attempts: opts.retry_max_attempts ?? 0,
-            };
-        }
-        if (opts?.connection_kind !== undefined)
-            options.connection_kind = opts.connection_kind;
-        if (opts?.short_ttl_ms !== undefined)
-            options.short_ttl_ms = opts.short_ttl_ms;
-        if (opts?.delivery_mode !== undefined)
-            options.delivery_mode = opts.delivery_mode;
-        if (opts?.extra_info !== undefined)
-            options.extra_info = opts.extra_info;
-        if (opts?.background_sync !== undefined)
-            options.background_sync = opts.background_sync;
-        this._clientLog.debug(`connect enter: state=${this._state} aid=${this._aid ?? '-'}`);
-        const publicState = this.state;
-        const allowed = new Set([
-            ConnectionState.STANDBY,
-            ConnectionState.AUTHENTICATED,
-            ConnectionState.RETRY_BACKOFF,
-            ConnectionState.CONNECTION_FAILED,
-        ]);
-        if (!allowed.has(publicState)) {
-            this._clientLog.debug(`connect exit (error): elapsed=${Date.now() - tStart}ms err=invalid_state state=${this._state}`);
-            throw new StateError(`connect not allowed in state ${publicState}`);
-        }
-        // gateway 来自 authenticate() 缓存的 this._gatewayUrl；未认证则自动 authenticate()
-        if (!this._gatewayUrl) {
-            await this.authenticate();
-        }
-        this._state = 'connecting';
-        const gateway = String(this._gatewayUrl ?? '').trim();
-        const params = { ...options, gateway };
-        const normalized = this._normalizeConnectParams(params);
-        this._sessionParams = normalized;
-        this._sessionOptions = this._buildSessionOptions(normalized);
-        this._transport.setTimeout(this._sessionOptions.timeouts.call);
-        this._closing = false;
-        const gateways = this._resolveGateways(normalized);
-        let lastErr = null;
-        for (const gw of gateways) {
-            try {
-                const gwParams = { ...normalized, gateway: gw };
-                await this._connectOnce(gwParams, true);
-                this._clientLog.debug(`connect exit: elapsed=${Date.now() - tStart}ms state=${this._state}`);
-                return;
-            }
-            catch (err) {
-                lastErr = err;
-                if (gateways.length > 1) {
-                    this._clientLog.warn(`connect: gateway ${gw} failed, trying next: ${err instanceof Error ? err.message : String(err)}`);
-                }
-                if (this._state === 'connecting' || this._state === 'authenticating') {
-                    this._state = 'connecting';
-                }
-            }
-        }
-        if (this._state === 'connecting' || this._state === 'authenticating') {
-            this._state = 'terminal_failed';
-        }
-        this._clientLog.debug(`connect exit (error): elapsed=${Date.now() - tStart}ms err=${lastErr instanceof Error ? lastErr.message : String(lastErr)}`);
-        throw lastErr;
+        return this._lifecycle.connect(opts);
     }
     /** 断开连接但保留本地状态，可再次 connect */
     async disconnect() {
         const tStart = Date.now();
         this._clientLog.debug(`disconnect enter: state=${this._state}`);
-        if (this._state !== 'connected' && this._state !== 'reconnecting') {
+        if (this._closing) {
+            this._clientLog.debug(`disconnect exit: elapsed=${Date.now() - tStart}ms reason=closing`);
+            return;
+        }
+        if (![
+            ConnectionState.AUTHENTICATED,
+            ConnectionState.CONNECTING,
+            ConnectionState.READY,
+            ConnectionState.RETRY_BACKOFF,
+            ConnectionState.RECONNECTING,
+            ConnectionState.CONNECTION_FAILED,
+        ].includes(this.state)) {
             this._clientLog.debug(`disconnect exit: elapsed=${Date.now() - tStart}ms reason=not_connected`);
             return;
         }
@@ -1291,7 +953,7 @@ export class AUNClient {
             this._reconnectActive = false;
         }
         await this._transport.close();
-        this._state = 'disconnected';
+        this._state = 'standby';
         await this._dispatcher.publish('state_change', { state: this._publicState(this._state) });
         this._clientLog.debug(`disconnect exit: elapsed=${Date.now() - tStart}ms`);
     }
@@ -1348,49 +1010,7 @@ export class AUNClient {
         }
     }
     async _callImpl(method, params) {
-        if (this._state !== 'connected') {
-            throw new ConnectionError('client is not connected');
-        }
-        if (INTERNAL_ONLY_METHODS.has(method)) {
-            throw new PermissionError(`method is internal_only: ${method}`);
-        }
-        if (method.startsWith('message.e2ee.') || method.startsWith('group.e2ee.') || REMOVED_E2EE_METHODS.has(method)) {
-            throw new PermissionError(`legacy E2EE method is removed in this SDK: ${method}`);
-        }
-        const p = { ...(params ?? {}) };
-        if (this._instanceProtectedHeaders && PROTECTED_HEADERS_METHODS.has(method)) {
-            const existing = isJsonObject(p.protected_headers) ? p.protected_headers : {};
-            p.protected_headers = { ...this._instanceProtectedHeaders, ...existing };
-        }
-        if (method === 'message.send' || method === 'group.send') {
-            this._normalizeOutboundMessagePayload(p, method);
-        }
-        this._validateOutboundCall(method, p);
-        this._injectMessageCursorContext(method, p);
-        if (method.startsWith('group.')
-            && !('_group_cursor_params' in p)
-            && !Boolean(p._pull_gate_locked)) {
-            const explicitCursorParams = this._groupCursorParams(p);
-            if (Object.keys(explicitCursorParams).length > 0) {
-                p._group_cursor_params = explicitCursorParams;
-            }
-        }
-        // group.* 方法的 group_id 归一化为 canonical 格式（兼容老/污染数据）
-        if (method.startsWith('group.') && p.group_id !== undefined && p.group_id !== null) {
-            const rawGroupId = String(p.group_id);
-            const normalizedGroupId = normalizeGroupId(rawGroupId);
-            if (normalizedGroupId && normalizedGroupId !== rawGroupId) {
-                this._clientLog.debug(`call group_id normalized: ${rawGroupId} -> ${normalizedGroupId} method=${method}`);
-            }
-            p.group_id = normalizedGroupId;
-        }
-        // group.* 方法注入 device_id（服务端用于多设备消息路由）
-        if (method.startsWith('group.') && p.device_id === undefined) {
-            p.device_id = this._deviceId;
-        }
-        if (method.startsWith('group.') && p.slot_id === undefined) {
-            p.slot_id = this._slotId;
-        }
+        const p = this._rpcPipeline.preflight(method, params).params;
         // 自动加密：message.send 默认加密（encrypt 默认 true）— V2-only
         if (method === 'message.send') {
             const encrypt = p.encrypt !== undefined ? p.encrypt : true;
@@ -1498,101 +1118,13 @@ export class AUNClient {
             return await this._ackGroupV2(String(p.group_id), Number(p.seq ?? p.msg_seq ?? p.up_to_seq ?? 0) || undefined);
         }
         // 关键操作自动附加客户端签名
-        if (SIGNED_METHODS.has(method)) {
-            if (this._shouldSkipClientSignature(method, p)) {
-                delete p.client_signature;
-            }
-            else {
-                await this._signClientOperation(method, p);
-            }
-        }
+        await this._rpcPipeline.applyClientSignature(method, p);
         // P1-23: 非幂等方法使用更长超时
         const callTimeout = NON_IDEMPOTENT_METHODS.has(method) ? NON_IDEMPOTENT_TIMEOUT : undefined;
         let result = callTimeout
             ? await this._transport.call(method, p, callTimeout)
             : await this._transport.call(method, p);
-        if (method === 'group.thought.get' && isJsonObject(result)) {
-            result = await this._decryptGroupThoughts(result);
-        }
-        if (method === 'message.thought.get' && isJsonObject(result)) {
-            result = await this._decryptMessageThoughts(result);
-        }
-        // V2-only 群状态编排：建群/成员变更后同步 propose+confirm state。
-        const membershipMethods = new Set([
-            'group.create', 'group.add_member', 'group.kick', 'group.remove_member', 'group.leave',
-            'group.review_join_request', 'group.batch_review_join_request',
-            'group.use_invite_code', 'group.request_join',
-        ]);
-        if (membershipMethods.has(method) && isJsonObject(result) && !('error' in result) && this._v2Session) {
-            const groupId = this._extractGroupIdFromResult(result) || String(p.group_id ?? '');
-            if (groupId) {
-                try {
-                    await this._v2AutoProposeState(groupId);
-                }
-                catch (exc) {
-                    this._clientLog.debug(`V2 post-membership propose failed (non-fatal): group=${groupId} err=${formatCaughtError(exc)}`);
-                }
-                // group.create / group.use_invite_code 成功后注册 group SPK
-                if (method === 'group.create' || method === 'group.use_invite_code') {
-                    const callFn = async (m, ps) => this.call(m, ps);
-                    this._v2Session.ensureGroupRegistered?.(groupId, callFn)?.catch(exc => {
-                        this._clientLog.debug(`group SPK registration after ${method} failed (non-fatal): group=${groupId} err=${exc}`);
-                    });
-                }
-            }
-        }
-        // message.pull 返回后的 seq 跟踪（V2 路径已在 call() 开头路由，此处为 plaintext pull 的 seq 跟踪）
-        if (method === 'message.pull' && isJsonObject(result)) {
-            const r = result;
-            const messages = r.messages;
-            const rawMessages = (Array.isArray(messages) ? messages : []).filter(isJsonObject);
-            if (this._aid) {
-                const ns = `p2p:${this._aid}`;
-                if (rawMessages.length) {
-                    const pullAfterSeq = Number(p.after_seq ?? 0) || 0;
-                    this._seqTracker.onPullResult(ns, rawMessages, pullAfterSeq);
-                }
-                // ⚠️ 逻辑边界 L1/L3：P2P retention floor 通道 = server_ack_seq
-                const serverAck = Number(r.server_ack_seq ?? 0);
-                if (serverAck > 0) {
-                    const contig = this._seqTracker.getContiguousSeq(ns);
-                    if (contig < serverAck) {
-                        this._clientLog.info('message.pull retention-floor advance: ns=' + ns + ' contiguous=' + contig + ' -> server_ack_seq=' + serverAck);
-                        this._seqTracker.forceContiguousSeq(ns, serverAck);
-                    }
-                }
-                this._saveSeqTrackerState();
-                // auto-ack 延迟到 publish 完成后（由 _fillP2pGap 负责）
-            }
-        }
-        // group.pull 返回后的 seq 跟踪（V2 路径已在 call() 开头路由，此处为 plaintext pull 的 seq 跟踪）
-        if (method === 'group.pull' && isJsonObject(result)) {
-            const r = result;
-            const messages = r.messages;
-            const rawMessages = (Array.isArray(messages) ? messages : []).filter(isJsonObject);
-            const gid = (p.group_id ?? '');
-            if (gid) {
-                const ns = `group:${gid}`;
-                if (rawMessages.length) {
-                    const pullAfterSeq = Number(p.after_message_seq ?? p.after_seq ?? 0) || 0;
-                    this._seqTracker.onPullResult(ns, rawMessages, pullAfterSeq);
-                }
-                // ⚠️ 逻辑边界 L4：group retention floor 通道 = cursor.current_seq
-                const cursor = isJsonObject(r.cursor) ? r.cursor : null;
-                if (cursor) {
-                    const serverAck = Number(cursor.current_seq ?? 0);
-                    if (serverAck > 0) {
-                        const contig = this._seqTracker.getContiguousSeq(ns);
-                        if (contig < serverAck) {
-                            this._clientLog.info('group.pull retention-floor advance: ns=' + ns + ' contiguous=' + contig + ' -> cursor.current_seq=' + serverAck);
-                            this._seqTracker.forceContiguousSeq(ns, serverAck);
-                        }
-                    }
-                }
-                this._saveSeqTrackerState();
-                // auto-ack 延迟到 publish 完成后（由 _fillGroupGap 负责）
-            }
-        }
+        result = await this._rpcPipeline.postprocessResult(method, p, result);
         // ── Group E2EE 自动编排已移除（V2-only：由 group.v2.bootstrap 驱动）────────
         return result;
     }
@@ -1611,15 +1143,7 @@ export class AUNClient {
         if (method.startsWith('group.') && p.slot_id === undefined) {
             p.slot_id = this._slotId;
         }
-        if (SIGNED_METHODS.has(method)) {
-            if (this._shouldSkipClientSignature(method, p)) {
-                delete p.client_signature;
-            }
-            else {
-                await this._signClientOperation(method, p);
-            }
-        }
-        return await this._transport.call(method, p);
+        return await this._rpcPipeline.rawCall(method, p);
     }
     // ── 事件 ──────────────────────────────────────────
     /**
@@ -1636,141 +1160,27 @@ export class AUNClient {
         this._dispatcher.unsubscribe(event, handler);
     }
     // ── 事件管道：消息解密 ────────────────────────────
+    _isEncryptedPushMessage(msg) {
+        return this._v2E2EE.isEncryptedPushMessage(msg);
+    }
+    _attachV2EnvelopeMetadataFromSource(message, source) {
+        attachV2EnvelopeMetadataFromSource(message, source);
+    }
     /** 处理 transport 层推送的原始消息：re-publish 给用户（V2 加密消息走 _raw.peer.v2.message_received） */
     _onRawMessageReceived(data) {
-        this._clientLog.debug(`_onRawMessageReceived enter: from=${data?.from ?? '-'} mid=${data?.message_id ?? '-'} seq=${data?.seq ?? '-'}`);
-        this._safeAsync(this._processAndPublishMessage(data));
-        this._clientLog.debug(`_onRawMessageReceived exit: elapsed=0ms (dispatched async)`);
+        this._delivery.onRawMessageReceived(data);
     }
     /** 实际处理推送消息的异步任务（V2-only：明文消息直接透传，V2 加密消息走 _onV2PushNotification） */
     async _processAndPublishMessage(data) {
-        try {
-            if (!isJsonObject(data)) {
-                await this._publishAppEvent('message.received', data);
-                return;
-            }
-            const msg = { ...data };
-            if (!this._messageTargetsCurrentInstance(msg)) {
-                return;
-            }
-            // P2P 空洞检测
-            const seq = msg.seq;
-            const encryptedPush = isEncryptedPushMessage(msg);
-            if (seq !== undefined && seq !== null && this._aid) {
-                const ns = `p2p:${this._aid}`;
-                // Push 修上界：先更新 maxSeenSeq
-                if (seq > 0)
-                    this._seqTracker.updateMaxSeen(ns, seq);
-                const contigBefore = this._seqTracker.getContiguousSeq(ns);
-                const seqNeedsPull = this._seqTracker.onMessageSeq(ns, seq);
-                const published = encryptedPush
-                    ? await this._publishEncryptedPushMessage('message.received', 'message.undecryptable', ns, seq, msg, false)
-                    : await this._publishOrderedMessage('message.received', ns, seq, msg);
-                const contigAfter = this._seqTracker.getContiguousSeq(ns);
-                const needPull = seqNeedsPull && !published;
-                if (needPull) {
-                    this._safeAsync(this._fillP2pGap());
-                }
-                // auto-ack contiguous_seq
-                const contig = this._seqTracker.getContiguousSeq(ns);
-                if (contig > 0) {
-                    const maxSeen = this._seqTracker.getMaxSeenSeq(ns);
-                    const ackSeq = maxSeen > 0 ? Math.min(contig, maxSeen) : contig;
-                    this._transport.call('message.ack', {
-                        seq: ackSeq,
-                        device_id: this._deviceId,
-                        slot_id: this._slotId,
-                    }).catch((e) => { this._clientLog.warn(`P2P auto-ack failed:${String(e)}`); });
-                }
-                // 即时持久化 cursor，异常断连后不回退
-                if (contigAfter !== contigBefore)
-                    this._saveSeqTrackerState();
-                if (encryptedPush)
-                    return;
-            }
-            else {
-                if (encryptedPush) {
-                    await this._publishEncryptedPushMessage('message.received', 'message.undecryptable', '', seq ?? 0, msg, false);
-                    return;
-                }
-                await this._publishAppEvent('message.received', msg);
-            }
-        }
-        catch (exc) {
-            this._clientLog.warn(`P2P push processing failed:${String(exc)}`);
-            if (isJsonObject(data)) {
-                const src = data;
-                const safeEvent = {
-                    message_id: (src.message_id ?? null),
-                    from: (src.from ?? null),
-                    to: (src.to ?? null),
-                    seq: (src.seq ?? null),
-                    timestamp: (src.timestamp ?? null),
-                    _decrypt_error: String(exc),
-                };
-                attachV2EnvelopeMetadataFromSource(safeEvent, data);
-                await this._publishAppEvent('message.undecryptable', safeEvent);
-            }
-        }
+        return this._delivery.processAndPublishMessage(data);
     }
     /** 处理群组消息推送：re-publish（V2 加密消息走 V2 push 路径） */
     _onRawGroupMessageCreated(data) {
-        this._clientLog.debug(`_onRawGroupMessageCreated enter: group_id=${data?.group_id ?? '-'} from=${data?.from ?? '-'} seq=${data?.seq ?? '-'}`);
-        this._safeAsync(this._processAndPublishGroupMessage(data));
-        this._clientLog.debug(`_onRawGroupMessageCreated exit: elapsed=0ms (dispatched async)`);
+        return this._delivery.onRawGroupMessageCreated(data);
     }
     /** 处理 V2 群消息通知：主动 pull V2 envelope，由 pullGroupV2 解密并发布。 */
     async _onRawGroupV2MessageCreated(data) {
-        const tStart = Date.now();
-        if (!isJsonObject(data)) {
-            this._clientLog.debug(`_onRawGroupV2MessageCreated skipped: non-object type=${typeof data}`);
-            return;
-        }
-        const groupId = String(data.group_id ?? '').trim();
-        const seq = Number(data.seq ?? 0) || 0;
-        const messageId = String(data.message_id ?? '').trim();
-        const senderAid = String(data.sender_aid ?? '').trim();
-        this._clientLog.debug(`_onRawGroupV2MessageCreated group=${groupId} seq=${seq} message_id=${messageId} sender=${senderAid}`);
-        if (!groupId || seq <= 0) {
-            this._clientLog.debug('_onRawGroupV2MessageCreated skipped: missing group_id or seq');
-            return;
-        }
-        if (!this._v2Session) {
-            this._clientLog.debug('_onRawGroupV2MessageCreated skipped: V2 session not initialized');
-            return;
-        }
-        try {
-            const ns = `group:${groupId}`;
-            // Push 修上界：先更新 maxSeenSeq
-            this._seqTracker.updateMaxSeen(ns, seq);
-            const contigBefore = this._seqTracker.getContiguousSeq(ns);
-            if (contigBefore === seq) {
-                this._clientLog.debug(`_onRawGroupV2MessageCreated duplicate push already covered: group=${groupId} seq=${seq}`);
-                return;
-            }
-            const afterSeq = this._repairPushContiguousBound(ns, seq, false, '_raw.group.v2.message_created');
-            // per-namespace 去重：同一 group namespace 只允许 1 个 in-flight pull
-            const dedupKey = `group_pull:${ns}`;
-            if (this._gapFillDone.has(dedupKey)) {
-                this._clientLog.debug(`_onRawGroupV2MessageCreated skipped: dedupKey=${dedupKey} in flight`);
-                return;
-            }
-            this._gapFillDone.add(dedupKey);
-            try {
-                this._clientLog.debug(`_onRawGroupV2MessageCreated -> group.v2.pull group=${groupId} after_seq=${afterSeq}`);
-                const messages = await this._pullGroupV2(groupId, afterSeq, 50);
-                this._clientLog.debug(`_onRawGroupV2MessageCreated pulled ${messages.length} msgs for group=${groupId}`);
-            }
-            finally {
-                this._gapFillDone.delete(dedupKey);
-            }
-        }
-        catch (exc) {
-            this._clientLog.warn(`_onRawGroupV2MessageCreated pull failed group=${groupId}: ${String(exc)}`);
-        }
-        finally {
-            this._clientLog.debug(`_onRawGroupV2MessageCreated exit: elapsed=${Date.now() - tStart}ms`);
-        }
+        return this._delivery.onRawGroupV2MessageCreated(data);
     }
     /**
      * 处理群组推送消息的异步任务（V2-only：明文消息直接透传）。
@@ -1779,433 +1189,38 @@ export class AUNClient {
      * 不带 payload 的事件（通知）：自动 pull 最新消息。
      */
     async _processAndPublishGroupMessage(data) {
-        try {
-            if (!isJsonObject(data)) {
-                await this._publishAppEvent('group.message_created', data);
-                return;
-            }
-            const msg = { ...data };
-            const groupId = (msg.group_id ?? '');
-            const seq = msg.seq;
-            const payload = msg.payload;
-            // 推送路径收到群消息 → 标记已同步，后续发送无需再 lazySyncGroup
-            if (groupId) {
-                this._groupSynced.add(groupId);
-            }
-            if (payload === undefined || payload === null
-                || (typeof payload === 'object' && Object.keys(payload).length === 0)) {
-                // 不带 payload 的通知
-                await this._autoPullGroupMessages(msg);
-                return;
-            }
-            // seq 跟踪 + auto-ack
-            const encryptedPush = isEncryptedPushMessage(msg);
-            if (groupId && seq !== undefined && seq !== null) {
-                const ns = `group:${groupId}`;
-                // Push 修上界：先更新 maxSeenSeq
-                if (seq > 0)
-                    this._seqTracker.updateMaxSeen(ns, seq);
-                const contigBefore = this._seqTracker.getContiguousSeq(ns);
-                const seqNeedsPull = this._seqTracker.onMessageSeq(ns, seq);
-                const published = encryptedPush
-                    ? await this._publishEncryptedPushMessage('group.message_created', 'group.message_undecryptable', ns, seq, msg, true)
-                    : await this._publishOrderedMessage('group.message_created', ns, seq, msg);
-                const contigAfter = this._seqTracker.getContiguousSeq(ns);
-                const needPull = seqNeedsPull && !published;
-                if (needPull) {
-                    this._safeAsync(this._fillGroupGap(groupId));
-                }
-                const contig = this._seqTracker.getContiguousSeq(ns);
-                if (contig > 0) {
-                    const maxSeen = this._seqTracker.getMaxSeenSeq(ns);
-                    const ackSeq = maxSeen > 0 ? Math.min(contig, maxSeen) : contig;
-                    this._transport.call('group.ack_messages', {
-                        group_id: groupId,
-                        msg_seq: ackSeq,
-                        device_id: this._deviceId,
-                        slot_id: this._slotId,
-                    }).catch((e) => { this._clientLog.warn('group message auto-ack failed: group=' + groupId, e); });
-                }
-                if (contigAfter !== contigBefore)
-                    this._saveSeqTrackerState();
-                if (encryptedPush)
-                    return;
-            }
-            else {
-                if (encryptedPush) {
-                    await this._publishEncryptedPushMessage('group.message_created', 'group.message_undecryptable', '', seq ?? 0, msg, true);
-                    return;
-                }
-                await this._publishAppEvent('group.message_created', msg);
-            }
-        }
-        catch (exc) {
-            this._clientLog.warn(`group push processing failed:${String(exc)}`);
-            if (isJsonObject(data)) {
-                const src = data;
-                const safeEvent = {
-                    message_id: (src.message_id ?? null),
-                    group_id: (src.group_id ?? null),
-                    from: (src.from ?? null),
-                    seq: (src.seq ?? null),
-                    timestamp: (src.timestamp ?? null),
-                    _decrypt_error: String(exc),
-                };
-                attachV2EnvelopeMetadataFromSource(safeEvent, data);
-                await this._publishAppEvent('group.message_undecryptable', safeEvent);
-            }
-        }
-    }
-    async _decryptEncryptedPushPayload(msg, group) {
-        const envelope = encryptedPushEnvelope(msg);
-        if (!isV2EncryptedEnvelopePayload(envelope))
-            return null;
-        const aad = isJsonObject(envelope.aad) ? envelope.aad : {};
-        const fromAid = String(msg.from_aid ?? msg.from ?? msg.sender_aid ?? aad.from ?? '').trim();
-        const plaintext = await this._decryptV2EnvelopeForThought({ envelope, fromAid });
-        if (!plaintext)
-            return null;
-        const e2eeMeta = v2E2eeMeta(envelope);
-        const result = {
-            message_id: String(msg.message_id ?? ''),
-            from: fromAid,
-            seq: msg.seq ?? null,
-            timestamp: msg.t_server ?? msg.timestamp ?? null,
-            payload: plaintext,
-            encrypted: true,
-            e2ee: e2eeMeta,
-        };
-        result.direction = fromAid && fromAid === this._aid ? 'outbound_sync' : '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;
-        if (group) {
-            result.group_id = msg.group_id ?? aad.group_id ?? envelope.group_id ?? null;
-        }
-        else {
-            result.to = msg.to ?? this._aid ?? '';
-        }
-        attachV2EnvelopeMetadata(result, e2eeMeta);
-        return result;
-    }
-    async _publishEncryptedPushAsUndecryptable(event, ns, seq, msg, group) {
-        const safeEvent = safeUndecryptablePushEvent(msg, group);
-        if (ns) {
-            return this._publishOrderedMessage(event, ns, seq, safeEvent);
-        }
-        await this._publishAppEvent(event, safeEvent);
-        return true;
+        return this._delivery.processAndPublishGroupMessage(data);
     }
     async _publishEncryptedPushMessage(normalEvent, undecryptableEvent, ns, seq, msg, group) {
-        const decrypted = await this._decryptEncryptedPushPayload(msg, group);
-        if (decrypted) {
-            if (ns)
-                return this._publishOrderedMessage(normalEvent, ns, seq, decrypted);
-            await this._publishAppEvent(normalEvent, decrypted);
-            return true;
-        }
-        return this._publishEncryptedPushAsUndecryptable(undecryptableEvent, ns, seq, msg, group);
+        return await this._v2E2EE.publishEncryptedPushMessage(normalEvent, undecryptableEvent, ns, seq, msg, group);
     }
-    /** 收到不带 payload 的 group.message_created 通知后，自动 pull 最新消息 */
-    async _autoPullGroupMessages(notification) {
-        const groupId = (notification.group_id ?? '');
-        if (!groupId) {
-            await this._publishAppEvent('group.message_created', notification);
-            return;
-        }
-        const ns = `group:${groupId}`;
-        const afterSeq = this._seqTracker.getContiguousSeq(ns);
-        try {
-            // V2-only 模式：走 group.v2.pull（合并 V1 明文 + V2 密文并自动解密）
-            if (this._v2Session) {
-                await this._pullGroupV2Internal({ group_id: groupId, after_seq: afterSeq, limit: 50 });
-                return;
-            }
-            const result = await this.call('group.pull', {
-                group_id: groupId,
-                after_message_seq: afterSeq,
-                device_id: this._deviceId,
-                limit: 50,
-            });
-            if (isJsonObject(result)) {
-                const messages = result.messages;
-                if (Array.isArray(messages)) {
-                    // ⚠️ 不再重复调用 onPullResult：call('group.pull') 拦截器已在内部调用过一次
-                    const pushed = this._pushedSeqs.get(ns);
-                    for (const msg of messages) {
-                        if (isJsonObject(msg)) {
-                            const s = msg.seq;
-                            if (pushed && s !== undefined && s !== null && pushed.has(s)) {
-                                continue; // 已发布到应用层，跳过
-                            }
-                            if (s !== undefined && s !== null) {
-                                await this._publishPulledMessage('group.message_created', ns, s, msg);
-                            }
-                            else {
-                                await this._publishAppEvent('group.message_created', msg);
-                            }
-                        }
-                    }
-                    this._prunePushedSeqs(ns);
-                    return;
-                }
-            }
-        }
-        catch (exc) {
-            this._clientLog.warn(`auto pull group message failed:${String(exc)}`);
-        }
-        // pull 失败时仍透传原始通知
-        await this._publishAppEvent('group.message_created', notification);
+    async _decryptV2PushMessage(data) {
+        return await this._v2E2EE.decryptV2PushMessage(data);
     }
     /** 后台补齐群消息空洞 */
     async _fillGroupGap(groupId) {
-        // 状态保护：非 connected 或正在关闭时跳过（与 Python 对齐）
-        if (this._state !== 'connected' || this._closing)
-            return;
-        groupId = normalizeGroupId(groupId) || String(groupId ?? '').trim();
-        if (!groupId)
-            return;
-        const ns = `group:${groupId}`;
-        const afterSeq = this._seqTracker.getContiguousSeq(ns);
-        // per-namespace 去重：同一 group namespace 只允许 1 个 in-flight pull
-        const dedupKey = `group_pull:${ns}`;
-        if (this._gapFillDone.has(dedupKey))
-            return;
-        this._gapFillDone.add(dedupKey);
-        this._gapFillActive = true;
-        let filled = 0;
-        try {
-            const messages = await this._pullGroupV2(groupId, afterSeq, 50);
-            filled = messages.length;
-            this._prunePushedSeqs(ns);
-        }
-        catch (exc) {
-            this._clientLog.warn(`group message gap-fill failed:${String(exc)}`);
-        }
-        finally {
-            // S1: 成功 / 失败路径都必须清理飞行标记
-            this._gapFillDone.delete(dedupKey);
-            this._gapFillActive = false;
-            if (filled > 0 && this._seqTracker.getContiguousSeq(ns) > afterSeq) {
-                this._safeAsync(this._fillGroupGap(groupId));
-            }
-        }
+        return this._delivery.fillGroupGap(groupId);
     }
     /** 后台补齐群事件空洞 */
     async _fillGroupEventGap(groupId) {
-        // 状态保护：非 connected 或正在关闭时跳过（与 Python 对齐）
-        if (this._state !== 'connected' || this._closing)
-            return;
-        const ns = `group_event:${groupId}`;
-        const afterSeq = this._seqTracker.getContiguousSeq(ns);
-        // per-namespace 去重：同一 group_event namespace 只允许 1 个 in-flight pull
-        const dedupKey = `group_event_pull:${ns}`;
-        if (this._gapFillDone.has(dedupKey))
-            return;
-        this._gapFillDone.add(dedupKey);
-        this._gapFillActive = true;
-        try {
-            let nextAfterSeq = afterSeq;
-            const maxPages = 100;
-            let pageCount = 0;
-            while (pageCount < maxPages) {
-                pageCount += 1;
-                const result = await this.call('group.pull_events', {
-                    group_id: groupId,
-                    after_event_seq: nextAfterSeq,
-                    device_id: this._deviceId,
-                    limit: 50,
-                });
-                if (!isJsonObject(result))
-                    return;
-                const events = result.events;
-                if (!Array.isArray(events))
-                    return;
-                const pageContigBefore = this._seqTracker.getContiguousSeq(ns);
-                const eventObjects = events.filter(isJsonObject);
-                if (eventObjects.length > 0) {
-                    this._seqTracker.onPullResult(ns, eventObjects, nextAfterSeq);
-                }
-                const cursor = isJsonObject(result.cursor) ? result.cursor : null;
-                const serverAck = cursor ? Number(cursor.current_seq ?? 0) : 0;
-                if (serverAck > 0) {
-                    const contigBeforeFloor = this._seqTracker.getContiguousSeq(ns);
-                    if (contigBeforeFloor < serverAck) {
-                        this._clientLog.info('group.pull_events retention-floor advance: ns=' + ns + ' contiguous=' + contigBeforeFloor + ' -> cursor.current_seq=' + serverAck);
-                        this._seqTracker.forceContiguousSeq(ns, serverAck);
-                    }
-                }
-                const eventSeqs = [];
-                for (const evt of eventObjects) {
-                    const eventSeq = Number(evt.event_seq ?? 0);
-                    if (Number.isFinite(eventSeq) && eventSeq > 0)
-                        eventSeqs.push(eventSeq);
-                    evt._from_gap_fill = true;
-                    const et = String(evt.event_type ?? '');
-                    // 消息事件由 _fillGroupGap 负责，事件补洞不重复投递
-                    if (et === 'group.message_created')
-                        continue;
-                    // 验签：有 client_signature 就验（与实时事件路径对齐）
-                    const cs = evt.client_signature;
-                    if (cs && typeof cs === 'object') {
-                        if (this._shouldSkipEventSignature(evt)) {
-                            delete evt.client_signature;
-                        }
-                        else {
-                            evt._verified = await this._verifyEventSignature(evt, cs);
-                        }
-                    }
-                    // group.changed 或缺失/其他 → 发布到 group.changed（向后兼容）
-                    await this._dispatcher.publish('group.changed', evt);
-                }
-                const contig = this._seqTracker.getContiguousSeq(ns);
-                if (contig !== pageContigBefore) {
-                    this._saveSeqTrackerState();
-                }
-                if (eventObjects.length > 0 && contig > 0 && contig !== pageContigBefore) {
-                    const maxSeen = this._seqTracker.getMaxSeenSeq(ns);
-                    const ackSeq = maxSeen > 0 ? Math.min(contig, maxSeen) : contig;
-                    this._transport.call('group.ack_events', {
-                        group_id: groupId,
-                        event_seq: ackSeq,
-                        device_id: this._deviceId,
-                        slot_id: this._slotId,
-                    }).catch((e) => { this._clientLog.warn('group event auto-ack failed: group=' + groupId, e); });
-                }
-                const nextAfter = Math.max(eventSeqs.length > 0 ? Math.max(...eventSeqs) : nextAfterSeq, nextAfterSeq);
-                if (eventObjects.length === 0 || nextAfter <= nextAfterSeq || result.has_more === false)
-                    break;
-                nextAfterSeq = nextAfter;
-            }
-            if (pageCount >= maxPages) {
-                this._clientLog.warn(`group event gap fill reached max_pages=${maxPages} group=${groupId} after_seq=${nextAfterSeq}`);
-            }
-        }
-        catch (exc) {
-            this._clientLog.warn(`group event gap-fill failed:${String(exc)}`);
-        }
-        finally {
-            // S1: 成功 / 失败路径都必须清理飞行标记
-            this._gapFillDone.delete(dedupKey);
-            this._gapFillActive = false;
-        }
+        return this._delivery.fillGroupEventGap(groupId);
     }
     /** 后台补齐 P2P 消息空洞 */
     async _fillP2pGap() {
-        // 状态保护：非 connected 或正在关闭时跳过（与 Python 对齐）
-        if (this._state !== 'connected' || this._closing)
-            return;
-        if (!this._aid)
-            return;
-        const ns = `p2p:${this._aid}`;
-        const afterSeq = this._seqTracker.getContiguousSeq(ns);
-        // per-namespace 去重：同一 namespace 只允许 1 个 in-flight pull
-        const dedupKey = `p2p_pull:${ns}`;
-        if (this._gapFillDone.has(dedupKey))
-            return;
-        this._gapFillDone.add(dedupKey);
-        this._gapFillActive = true;
-        let filled = 0;
-        try {
-            const messages = await this._pullV2(afterSeq, 50);
-            filled = messages.length;
-            this._prunePushedSeqs(ns);
-        }
-        catch (exc) {
-            this._clientLog.warn(`P2P message gap-fill failed:${String(exc)}`);
-        }
-        finally {
-            // S1: 成功 / 失败路径都必须清理飞行标记
-            this._gapFillDone.delete(dedupKey);
-            this._gapFillActive = false;
-            if (filled > 0 && this._seqTracker.getContiguousSeq(ns) > afterSeq) {
-                this._safeAsync(this._fillP2pGap());
-            }
-        }
+        return this._delivery.fillP2pGap();
     }
     /** 只按硬上限裁剪 published guard，不能按 contiguousSeq 清理。 */
     _prunePushedSeqs(ns) {
-        const pushed = this._pushedSeqs.get(ns);
-        if (!pushed)
-            return;
-        if (pushed.size > PUSHED_SEQS_LIMIT) {
-            const keep = [...pushed].sort((a, b) => a - b).slice(-PUSHED_SEQS_LIMIT);
-            this._pushedSeqs.set(ns, new Set(keep));
-        }
+        this._delivery.prunePushedSeqs(ns);
     }
     _markPublishedSeq(ns, seq) {
-        let pushed = this._pushedSeqs.get(ns);
-        if (!pushed) {
-            pushed = new Set();
-            this._pushedSeqs.set(ns, pushed);
-        }
-        pushed.add(seq);
-        if (pushed.size > PUSHED_SEQS_LIMIT) {
-            const keep = [...pushed].sort((a, b) => a - b).slice(-PUSHED_SEQS_LIMIT);
-            this._pushedSeqs.set(ns, new Set(keep));
-        }
-    }
-    _enqueueOrderedMessage(ns, event, seq, payload) {
-        let queue = this._pendingOrderedMsgs.get(ns);
-        if (!queue) {
-            queue = new Map();
-            this._pendingOrderedMsgs.set(ns, queue);
-        }
-        queue.set(seq, { event, payload });
-        if (queue.size > PENDING_ORDERED_LIMIT) {
-            const drop = [...queue.keys()].sort((a, b) => a - b).slice(0, queue.size - PENDING_ORDERED_LIMIT);
-            for (const oldSeq of drop)
-                queue.delete(oldSeq);
-        }
-    }
-    _isInstanceScopedMessageEvent(event) {
-        return event === 'message.received'
-            || event === 'message.undecryptable'
-            || event === 'group.message_created'
-            || event === 'group.message_undecryptable';
+        this._delivery.markPublishedSeq(ns, seq);
     }
     _attachCurrentInstanceContext(payload) {
-        if (!isJsonObject(payload))
-            return payload;
-        const result = { ...payload };
-        if (!('device_id' in result)) {
-            result.device_id = this._deviceId;
-        }
-        if (!('slot_id' in result)) {
-            result.slot_id = this._slotId;
-        }
-        return result;
-    }
-    _normalizePublishedMessagePayload(event, payload) {
-        if (!this._isInstanceScopedMessageEvent(event))
-            return payload;
-        return this._attachCurrentInstanceContext(payload);
+        return this._delivery.attachCurrentInstanceContext(payload);
     }
     async _publishAppEvent(event, payload) {
-        if ((event === 'message.received' || event === 'group.message_created') && isJsonObject(payload)) {
-            this._maybeAppendEchoTraceReceive(payload);
-        }
-        // 注入本地/远端 agent.md etag，让应用层判断版本一致性；失败不影响业务。
-        if (isJsonObject(payload)) {
-            try {
-                const snapshot = this._agentMdManager.eventSnapshot();
-                const localEtag = snapshot?.local_etag || '';
-                const remoteEtag = snapshot?.remote_etag || '';
-                if ((localEtag || remoteEtag) && payload._agent_md === undefined) {
-                    payload._agent_md = {
-                        local_etag: localEtag,
-                        remote_etag: remoteEtag,
-                    };
-                }
-            }
-            catch (exc) {
-                this._clientLog.debug(`agent_md etag inject skipped: ${String(exc)}`);
-            }
-        }
-        await this._dispatcher.publish(event, this._normalizePublishedMessagePayload(event, payload));
+        await this._delivery.publishAppEvent(event, payload);
     }
     _echoTimestamp() {
         const now = new Date();
@@ -2231,13 +1246,6 @@ export class AUNClient {
         const trace = `${this._echoTimestamp()} [AUN-SDK.send] aid=${this._aid ?? '-'} conn_uptime=${uptime}s`;
         params.payload = { ...payload, text: payload.text + '\n' + trace };
     }
-    _shouldSkipClientSignature(method, params) {
-        if (method !== 'message.send' && method !== 'group.send')
-            return false;
-        if (params.encrypted || params.encrypt)
-            return false;
-        return this._isEchoPayload(params.payload);
-    }
     _shouldSkipEventSignature(event) {
         if (event.encrypted || event.encrypt)
             return false;
@@ -2254,90 +1262,16 @@ export class AUNClient {
         msg.payload = { ...payload, text: payload.text + '\n' + trace };
     }
     _messageTargetsCurrentInstance(message) {
-        if (!isJsonObject(message))
-            return true;
-        if ('device_id' in message) {
-            const targetDeviceId = String(message.device_id ?? '').trim();
-            if (targetDeviceId !== this._deviceId) {
-                return false;
-            }
-        }
-        if ('slot_id' in message) {
-            const targetSlotId = String(message.slot_id ?? '').trim();
-            if (slotIsolationKey(targetSlotId) !== slotIsolationKey(this._slotId)) {
-                return false;
-            }
-        }
-        return true;
+        return this._delivery.messageTargetsCurrentInstance(message);
     }
     async _drainOrderedMessages(ns, beforeSeq) {
-        const queue = this._pendingOrderedMsgs.get(ns);
-        if (!queue || queue.size === 0)
-            return;
-        const contig = this._seqTracker.getContiguousSeq(ns);
-        const ready = [...queue.keys()]
-            .filter((seq) => seq <= contig && (beforeSeq === undefined || seq < beforeSeq))
-            .sort((a, b) => a - b);
-        for (const seq of ready) {
-            const item = queue.get(seq);
-            queue.delete(seq);
-            if (!item || this._pushedSeqs.get(ns)?.has(seq))
-                continue;
-            await this._publishAppEvent(item.event, item.payload);
-            this._markPublishedSeq(ns, seq);
-        }
-        if (queue.size === 0)
-            this._pendingOrderedMsgs.delete(ns);
+        await this._delivery.drainOrderedMessages(ns, beforeSeq);
     }
     async _publishOrderedMessage(event, ns, seq, payload) {
-        const seqNum = Number(seq);
-        if (!Number.isFinite(seqNum) || !Number.isInteger(seqNum) || seqNum <= 0) {
-            await this._publishAppEvent(event, payload);
-            return true;
-        }
-        if (this._pushedSeqs.get(ns)?.has(seqNum)) {
-            const queue = this._pendingOrderedMsgs.get(ns);
-            queue?.delete(seqNum);
-            if (queue && queue.size === 0)
-                this._pendingOrderedMsgs.delete(ns);
-            return false;
-        }
-        const contig = this._seqTracker.getContiguousSeq(ns);
-        if (seqNum > contig) {
-            this._enqueueOrderedMessage(ns, event, seqNum, payload);
-            return false;
-        }
-        await this._drainOrderedMessages(ns, seqNum);
-        if (this._pushedSeqs.get(ns)?.has(seqNum))
-            return false;
-        const queue = this._pendingOrderedMsgs.get(ns);
-        queue?.delete(seqNum);
-        if (queue && queue.size === 0)
-            this._pendingOrderedMsgs.delete(ns);
-        await this._publishAppEvent(event, payload);
-        this._markPublishedSeq(ns, seqNum);
-        await this._drainOrderedMessages(ns);
-        return true;
+        return this._delivery.publishOrderedMessage(event, ns, seq, payload);
     }
     async _publishPulledMessage(event, ns, seq, payload) {
-        const seqNum = Number(seq);
-        if (!Number.isFinite(seqNum) || !Number.isInteger(seqNum) || seqNum <= 0 || !ns) {
-            await this._publishAppEvent(event, payload);
-            return true;
-        }
-        const queue = this._pendingOrderedMsgs.get(ns);
-        if (this._pushedSeqs.get(ns)?.has(seqNum)) {
-            queue?.delete(seqNum);
-            if (queue && queue.size === 0)
-                this._pendingOrderedMsgs.delete(ns);
-            return false;
-        }
-        queue?.delete(seqNum);
-        if (queue && queue.size === 0)
-            this._pendingOrderedMsgs.delete(ns);
-        await this._publishAppEvent(event, payload);
-        this._markPublishedSeq(ns, seqNum);
-        return true;
+        return this._delivery.publishPulledMessage(event, ns, seq, payload);
     }
     _extractGroupIdFromResult(result) {
         const group = isJsonObject(result.group) ? result.group : null;
@@ -2370,52 +1304,8 @@ export class AUNClient {
                 }
                 await this._dispatcher.publish('group.changed', d);
                 const groupId = (d.group_id ?? '');
-                // V2 bootstrap 缓存失效：成员变更可能导致 epoch 递增或设备列表变化
-                if (groupId) {
-                    this._v2BootstrapCache.delete(`group:${groupId}`);
-                }
-                // Group SPK 编排：成员变更触发注册/轮换
-                const membershipActions = new Set([
-                    'member_added', 'member_left', 'member_removed', 'role_changed',
-                    'owner_transferred', 'joined', 'join_approved', 'invite_code_used',
-                ]);
-                if (this._v2Session && groupId) {
-                    if (membershipActions.has(action)) {
-                        const callFn = async (method, params) => this.call(method, params);
-                        const joinedAid = String(d.joined_aid ?? d.member_aid ?? d.aid ?? '').trim();
-                        const actorAid = String(d.actor_aid ?? '').trim();
-                        const selfAid = String(this._aid ?? '').trim();
-                        const joinActions = new Set(['member_added', 'joined', 'join_approved', 'invite_code_used']);
-                        const isSelfJoin = joinActions.has(action) && !!selfAid && (joinedAid === selfAid ||
-                            (!joinedAid && (action === 'joined' || action === 'invite_code_used') && actorAid === selfAid));
-                        if (isSelfJoin) {
-                            this._v2Session.ensureGroupRegistered?.(groupId, callFn)?.catch(exc => {
-                                this._clientLog.debug(`group SPK registration failed (non-fatal): group=${groupId} action=${action} err=${exc}`);
-                            });
-                        }
-                        else {
-                            this._v2Session.rotateGroupSPK?.(groupId, callFn)?.catch(exc => {
-                                this._clientLog.debug(`group SPK rotation failed (non-fatal): group=${groupId} action=${action} err=${exc}`);
-                            });
-                        }
-                    }
-                }
-                if (groupId && this._v2Session && (action === 'upsert' || membershipActions.has(action))) {
-                    this._safeAsync(this._v2AutoProposeState(groupId, { leaderDelay: true }));
-                }
-                // event_seq 空洞检测：持久化后的 group.changed 会携带 event_seq。
-                let needPull = false;
-                const rawEventSeq = d.event_seq;
-                if (rawEventSeq != null && groupId) {
-                    const es = Number(rawEventSeq);
-                    if (Number.isFinite(es) && es > 0) {
-                        needPull = this._seqTracker.onMessageSeq(`group_event:${groupId}`, es);
-                    }
-                }
-                // 仅在真实 event gap 时才触发补拉（补洞回来的事件不再触发新补洞）
-                if (needPull && groupId && !d._from_gap_fill) {
-                    this._safeAsync(this._fillGroupEventGap(groupId));
-                }
+                this._groupState.handleGroupChangedV2Membership(d);
+                this._delivery.handleGroupChangedEventSeq(d, groupId);
                 // 群组解散 → 清理本地 seq_tracker、补洞去重缓存
                 if (d.action === 'dissolved') {
                     if (groupId) {
@@ -2439,123 +1329,7 @@ export class AUNClient {
      * 当 prev_state_hash 与本地不连续时回源 group.get_state，并对回源数据做 hash 验证。
      */
     async _onGroupStateCommitted(data) {
-        const tStart = Date.now();
-        const groupIdInit = String(data?.group_id ?? '');
-        this._clientLog.debug(`_onGroupStateCommitted enter: group_id=${groupIdInit} state_version=${String(data?.state_version ?? '-')}`);
-        try {
-            if (!isJsonObject(data)) {
-                this._clientLog.debug(`_onGroupStateCommitted exit: elapsed=${Date.now() - tStart}ms reason=non_object`);
-                return;
-            }
-            const d = data;
-            const groupId = String(d.group_id ?? '').trim();
-            if (!groupId) {
-                this._clientLog.debug(`_onGroupStateCommitted exit: elapsed=${Date.now() - tStart}ms reason=no_group_id`);
-                return;
-            }
-            await this._onGroupStateCommittedImpl(d, groupId);
-            this._clientLog.debug(`_onGroupStateCommitted exit: elapsed=${Date.now() - tStart}ms group_id=${groupId}`);
-        }
-        catch (err) {
-            this._clientLog.debug(`_onGroupStateCommitted exit (error): elapsed=${Date.now() - tStart}ms err=${err instanceof Error ? err.message : String(err)}`);
-            throw err;
-        }
-    }
-    async _onGroupStateCommittedImpl(d, groupId) {
-        // 提交者签名验证
-        const cs = d.client_signature;
-        if (cs && isJsonObject(cs)) {
-            if (this._shouldSkipEventSignature(d)) {
-                delete d.client_signature;
-            }
-            else {
-                const verified = await this._verifyEventSignature(d, cs);
-                if (verified === false) {
-                    this._clientLog.warn(`state_committed committer signature verify failed group=%s${String(groupId)}`);
-                    return;
-                }
-                d._verified = verified;
-            }
-        }
-        const stateVersion = Number(d.state_version ?? 0);
-        const stateHash = String(d.state_hash ?? '').trim();
-        const prevStateHash = String(d.prev_state_hash ?? '').trim();
-        const keyEpoch = Number(d.key_epoch ?? 0);
-        const membershipSnapshot = String(d.membership_snapshot ?? '').trim();
-        const policySnapshot = String(d.policy_snapshot ?? '').trim();
-        // 1. 验证 prev_state_hash 连续性
-        const loadFn = this._tokenStore.loadGroupState;
-        const localState = loadFn
-            ? await loadFn.call(this._tokenStore, groupId)
-            : null;
-        if (localState && localState.state_hash && localState.state_hash !== prevStateHash) {
-            this._clientLog.warn('[aun_core] state_hash 链不连续 group=%s local_sv=%d event_sv=%d', groupId, localState.state_version, stateVersion);
-            // 回源同步
-            try {
-                const serverState = await this._transport.call('group.get_state', { group_id: groupId });
-                if (serverState && typeof serverState.state_version !== 'undefined') {
-                    const sv = Number(serverState.state_version);
-                    const sHash = String(serverState.state_hash ?? '');
-                    const sEpoch = Number(serverState.key_epoch ?? 0);
-                    const sMembersJson = String(serverState.membership_snapshot ?? '');
-                    const sPolicyJson = String(serverState.policy_snapshot ?? '');
-                    const sPrev = String(serverState.prev_state_hash ?? '');
-                    // 回源也做 hash 验证
-                    if (sMembersJson && sHash) {
-                        const sMembers = sMembersJson ? JSON.parse(sMembersJson) : [];
-                        const sPolicy = sPolicyJson ? JSON.parse(sPolicyJson) : {};
-                        const computed = await computeStateHash({
-                            groupId, stateVersion: sv, keyEpoch: sEpoch,
-                            members: sMembers, policy: sPolicy, prevStateHash: sPrev,
-                        });
-                        if (computed !== sHash) {
-                            this._clientLog.warn('[aun_core] 回源 state_hash 验证失败 group=%s sv=%d expected=%s got=%s', groupId, sv, sHash, computed);
-                            return;
-                        }
-                    }
-                    const saveFn = this._tokenStore.saveGroupState;
-                    if (saveFn) {
-                        await saveFn.call(this._tokenStore, groupId, {
-                            group_id: groupId,
-                            state_version: sv,
-                            state_hash: sHash,
-                            key_epoch: sEpoch,
-                            membership_json: sMembersJson || membershipSnapshot,
-                            policy_json: sPolicyJson || policySnapshot,
-                            updated_at: Date.now(),
-                        });
-                    }
-                }
-            }
-            catch (exc) {
-                this._clientLog.warn(`state pull-back failed group=%s:${groupId} ${exc}`);
-            }
-            return;
-        }
-        // 2. 本地重算验证
-        const members = membershipSnapshot ? JSON.parse(membershipSnapshot) : [];
-        const policy = policySnapshot ? JSON.parse(policySnapshot) : {};
-        const computed = await computeStateHash({
-            groupId, stateVersion, keyEpoch,
-            members, policy, prevStateHash,
-        });
-        if (computed !== stateHash) {
-            this._clientLog.warn('[aun_core] state_hash 重算不匹配 group=%s sv=%d expected=%s got=%s', groupId, stateVersion, stateHash, computed);
-            return;
-        }
-        // 3. 更新本地存储
-        const saveFn = this._tokenStore.saveGroupState;
-        if (saveFn) {
-            await saveFn.call(this._tokenStore, groupId, {
-                group_id: groupId,
-                state_version: stateVersion,
-                state_hash: stateHash,
-                key_epoch: keyEpoch,
-                membership_json: membershipSnapshot,
-                policy_json: policySnapshot,
-                updated_at: Date.now(),
-            });
-        }
+        return this._groupState.onGroupStateCommitted(data);
     }
     /**
      * 群组解散后清理本地状态：
@@ -2566,7 +1340,7 @@ export class AUNClient {
      */
     _cleanupDissolvedGroup(groupId) {
         // 1. 清理 seq_tracker 中的群消息和群事件命名空间
-        this._v2BootstrapCache.delete(`group:${groupId}`);
+        this._v2E2EE.deleteBootstrapCacheEntry(`group:${groupId}`);
         this._v2GroupSecurityLevels.delete(groupId);
         this._v2StateChains.delete(groupId);
         this._seqTracker.removeNamespace(`group:${groupId}`);
@@ -2597,8 +1371,7 @@ export class AUNClient {
         }
         try {
             if (expectedFP) {
-                const actualFP = await certificateSha256Fingerprint(cached.certPem);
-                if (actualFP !== expectedFP) {
+                if (!(await certMatchesFingerprint(cached.certPem, expectedFP))) {
                     this._clientLog.warn(`group event sig verify failed: cert fingerprint mismatch aid=%s${String(sigAid)}`);
                     return false;
                 }
@@ -2724,176 +1497,10 @@ export class AUNClient {
         }
     }
     async _decryptGroupThoughts(result) {
-        if (!result.found) {
-            return { ...result, thoughts: [] };
-        }
-        const items = (Array.isArray(result.thoughts) ? result.thoughts : []).filter(isJsonObject);
-        if (!items.length) {
-            return { ...result, thoughts: [] };
-        }
-        const groupId = String(result.group_id ?? '');
-        const senderAid = String(result.sender_aid ?? '');
-        const thoughts = [];
-        for (const item of items) {
-            const payload = isJsonObject(item.payload) ? item.payload : null;
-            const thoughtId = String(item.thought_id ?? item.message_id ?? '');
-            // V2 群 thought envelope：per-device wrap
-            const isV2Envelope = payload !== null
-                && payload.type === 'e2ee.group_encrypted'
-                && (payload.version === 'v2' || Array.isArray(payload.recipients));
-            let decryptedPayload = payload;
-            let e2eeMeta = null;
-            let decryptFailed = false;
-            if (isV2Envelope) {
-                e2eeMeta = v2E2eeMeta(payload);
-                const plaintext = await this._decryptV2EnvelopeForThought({
-                    envelope: payload,
-                    fromAid: senderAid,
-                });
-                if (plaintext === null) {
-                    this._clientLog.warn(`group.thought.decrypt v2 failed thought_id=${thoughtId}`);
-                    decryptFailed = true;
-                    decryptedPayload = payload;
-                }
-                else {
-                    decryptedPayload = plaintext;
-                    const e2eeObj = e2eeMeta;
-                    // 暴露 protected_headers（去 _auth）
-                    const ph = payload.protected_headers;
-                    if (isJsonObject(ph)) {
-                        const phBody = {};
-                        for (const [k, v] of Object.entries(ph)) {
-                            if (k !== '_auth')
-                                phBody[k] = v;
-                        }
-                        if (Object.keys(phBody).length > 0)
-                            e2eeObj.protected_headers = phBody;
-                    }
-                    // 暴露 context（去 _auth）
-                    const ctx = payload.context;
-                    if (isJsonObject(ctx)) {
-                        const ctxBody = {};
-                        for (const [k, v] of Object.entries(ctx)) {
-                            if (k !== '_auth')
-                                ctxBody[k] = v;
-                        }
-                        if (Object.keys(ctxBody).length > 0)
-                            e2eeObj.context = ctxBody;
-                    }
-                    e2eeMeta = e2eeObj;
-                }
-            }
-            else if (payload?.type === 'e2ee.group_encrypted') {
-                decryptFailed = true;
-                decryptedPayload = payload;
-            }
-            const thought = {
-                thought_id: thoughtId,
-                message_id: thoughtId,
-                payload: decryptedPayload,
-                created_at: item.created_at,
-                e2ee: e2eeMeta,
-            };
-            if (isJsonObject(e2eeMeta))
-                attachV2EnvelopeMetadata(thought, e2eeMeta);
-            if (decryptFailed)
-                thought.decrypt_failed = true;
-            if ('context' in item)
-                thought.context = item.context;
-            thoughts.push(thought);
-        }
-        return { ...result, thoughts };
+        return await this._v2E2EE.decryptGroupThoughts(result);
     }
     async _decryptMessageThoughts(result) {
-        if (!result.found) {
-            return { ...result, thoughts: [] };
-        }
-        const items = (Array.isArray(result.thoughts) ? result.thoughts : []).filter(isJsonObject);
-        if (!items.length) {
-            return { ...result, thoughts: [] };
-        }
-        const senderAid = String(result.sender_aid ?? '');
-        const peerAid = String(result.peer_aid ?? '');
-        const thoughts = [];
-        for (const item of items) {
-            const payload = isJsonObject(item.payload) ? item.payload : null;
-            const thoughtId = String(item.thought_id ?? item.message_id ?? '');
-            const fromAid = String(item.from ?? senderAid);
-            const toAid = String(item.to ?? peerAid);
-            const message = {
-                from: fromAid,
-                to: toAid,
-                message_id: thoughtId,
-                payload: payload ?? {},
-                encrypted: item.encrypted !== false,
-                timestamp: Number(item.created_at ?? 0),
-            };
-            if (isJsonObject(item.context))
-                message.context = item.context;
-            let decrypted = message;
-            let decryptFailed = false;
-            // V2 P2P thought envelope：per-device wrap，本设备解密自己的 row
-            if (payload?.type === 'e2ee.p2p_encrypted') {
-                const e2eeObj = v2E2eeMeta(payload);
-                message.e2ee = e2eeObj;
-                const plaintext = await this._decryptV2EnvelopeForThought({
-                    envelope: payload,
-                    fromAid,
-                });
-                if (plaintext === null) {
-                    this._clientLog.warn(`p2p.thought.decrypt v2 failed thought_id=${thoughtId}`);
-                    decryptFailed = true;
-                }
-                else {
-                    decrypted = { ...message };
-                    decrypted.payload = plaintext;
-                    // 暴露 protected_headers（去 _auth）
-                    const ph = payload.protected_headers;
-                    if (isJsonObject(ph)) {
-                        const phBody = {};
-                        for (const [k, v] of Object.entries(ph)) {
-                            if (k !== '_auth')
-                                phBody[k] = v;
-                        }
-                        if (Object.keys(phBody).length > 0)
-                            e2eeObj.protected_headers = phBody;
-                    }
-                    // 暴露 context（去 _auth）
-                    const ctx = payload.context;
-                    if (isJsonObject(ctx)) {
-                        const ctxBody = {};
-                        for (const [k, v] of Object.entries(ctx)) {
-                            if (k !== '_auth')
-                                ctxBody[k] = v;
-                        }
-                        if (Object.keys(ctxBody).length > 0)
-                            e2eeObj.context = ctxBody;
-                    }
-                    decrypted.e2ee = e2eeObj;
-                }
-            }
-            else if (payload?.type === 'e2ee.encrypted') {
-                decryptFailed = true;
-            }
-            const exposedE2ee = (decrypted ?? message).e2ee;
-            const thought = {
-                thought_id: thoughtId,
-                message_id: thoughtId,
-                from: fromAid,
-                to: toAid,
-                payload: (decrypted ?? message).payload,
-                created_at: item.created_at,
-                e2ee: exposedE2ee,
-            };
-            if (isJsonObject(exposedE2ee))
-                attachV2EnvelopeMetadata(thought, exposedE2ee);
-            if (decryptFailed)
-                thought.decrypt_failed = true;
-            if ('context' in item)
-                thought.context = item.context;
-            thoughts.push(thought);
-        }
-        return { ...result, thoughts };
+        return await this._v2E2EE.decryptMessageThoughts(result);
     }
     // ── E2EE 编排：证书与客户端签名 ──────────────────────
     /**
@@ -2918,51 +1525,27 @@ export class AUNClient {
             // 跨域时用 peer 所在域的 Gateway URL
             const peerGatewayUrl = resolvePeerGatewayUrl(gatewayUrl, aid);
             let certPem;
+            const certUrl = buildCertUrl(peerGatewayUrl, aid, certFingerprint);
+            // 兼容旧浏览器，不使用 AbortSignal.timeout（Chrome 103+ 才支持）
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
             try {
-                const certUrl = buildCertUrl(peerGatewayUrl, aid, certFingerprint);
-                // 兼容旧浏览器，不使用 AbortSignal.timeout（Chrome 103+ 才支持）
-                const controller = new AbortController();
-                const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
-                try {
-                    const resp = await fetch(certUrl, { signal: controller.signal });
-                    if (!resp.ok)
-                        throw new ValidationError(`failed to fetch peer cert for ${aid}: HTTP ${resp.status}`);
-                    certPem = await resp.text();
+                const resp = await fetch(certUrl, { signal: controller.signal });
+                if (!resp.ok)
+                    throw new ValidationError(`failed to fetch peer cert for ${aid}: HTTP ${resp.status}`);
+                certPem = await resp.text();
+            }
+            finally {
+                clearTimeout(timeoutId);
+            }
+            // H7: 严格校验指纹（DER SHA-256 或 SPKI SHA-256 任一匹配即可）
+            if (certFingerprint) {
+                const expectedFP = String(certFingerprint).trim().toLowerCase();
+                if (!normalizeFingerprintHex(expectedFP)) {
+                    throw new ValidationError(`unsupported cert_fingerprint format for ${aid}: ${expectedFP.slice(0, 24)}`);
                 }
-                finally {
-                    clearTimeout(timeoutId);
-                }
-            }
-            catch (exc) {
-                if (!certFingerprint) {
-                    throw exc;
-                }
-                // 兼容旧浏览器，不使用 AbortSignal.timeout（Chrome 103+ 才支持）
-                const fallbackController = new AbortController();
-                const fallbackTimeoutId = setTimeout(() => fallbackController.abort(), timeoutMs);
-                try {
-                    const fallbackResp = await fetch(buildCertUrl(peerGatewayUrl, aid), { signal: fallbackController.signal });
-                    if (!fallbackResp.ok) {
-                        throw exc;
-                    }
-                    certPem = await fallbackResp.text();
-                }
-                finally {
-                    clearTimeout(fallbackTimeoutId);
-                }
-            }
-            // H7: 严格校验指纹（DER SHA-256 或 SPKI SHA-256 任一匹配即可）
-            if (certFingerprint) {
-                const expectedFP = String(certFingerprint).trim().toLowerCase();
-                if (!expectedFP.startsWith('sha256:')) {
-                    throw new ValidationError(`unsupported cert_fingerprint format for ${aid}: ${expectedFP.slice(0, 24)}`);
-                }
-                const derFP = await this._certFingerprint(certPem);
-                if (derFP !== expectedFP) {
-                    const spkiFP = await this._spkiFingerprint(certPem);
-                    if (!spkiFP || spkiFP !== expectedFP) {
-                        throw new ValidationError(`peer cert fingerprint mismatch for ${aid}: expected=${expectedFP.slice(0, 24)}...`);
-                    }
+                if (!(await certMatchesFingerprint(certPem, expectedFP))) {
+                    throw new ValidationError(`peer cert fingerprint mismatch for ${aid}: expected=${expectedFP.slice(0, 24)}...`);
                 }
             }
             // 完整 PKI 验证：链 + CRL + OCSP + AID 绑定
@@ -2992,118 +1575,13 @@ export class AUNClient {
             throw err;
         }
     }
-    /** 确保发送方证书在本地可用且未过期 */
-    async _ensureSenderCertCached(aid, certFingerprint) {
-        const cacheKey = certCacheKey(aid, certFingerprint);
-        const cached = this._certCache.get(cacheKey);
-        const now = Date.now() / 1000;
-        if (cached && now < cached.refreshAfter)
-            return true;
-        const localCert = await this._tokenStore.loadCert(aid, certFingerprint);
-        if (localCert) {
-            if (certFingerprint) {
-                const actualFingerprint = await this._certFingerprint(localCert);
-                if (actualFingerprint === String(certFingerprint).trim().toLowerCase()) {
-                    this._certCache.set(cacheKey, {
-                        certPem: localCert,
-                        validatedAt: now,
-                        refreshAfter: now + PEER_CERT_CACHE_TTL,
-                    });
-                    return true;
-                }
-            }
-            else {
-                this._certCache.set(cacheKey, {
-                    certPem: localCert,
-                    validatedAt: now,
-                    refreshAfter: now + PEER_CERT_CACHE_TTL,
-                });
-                return true;
-            }
-        }
-        try {
-            const certPem = await this._fetchPeerCert(aid, certFingerprint);
-            // peer 证书只存版本目录，不覆盖 cert.pem
-            await this._tokenStore.saveCert(aid, certPem, certFingerprint, { makeActive: false });
-            return true;
-        }
-        catch (exc) {
-            // 刷新失败时：若缓存有 PKI 验证过的证书（2 倍 TTL 内）则继续用
-            if (cached && now < cached.validatedAt + PEER_CERT_CACHE_TTL * 2) {
-                this._clientLog.warn(`refresh sender ${aid} cert failed, continue using verified memory cache: ${String(exc)}`);
-                return true;
-            }
-            this._clientLog.warn(`fetch sender ${aid} cert failed and no verify cache, reject trust: ${String(exc)}`);
-            return false;
-        }
-    }
-    /**
-     * 获取经过 PKI 验证的 peer 证书（仅信任内存缓存中已验证的证书）。
-     * 零信任要求：不直接信任 keystore 中可能由恶意服务端注入的证书。
-     */
-    _getVerifiedPeerCert(aid, certFingerprint) {
-        let cached = this._certCache.get(certCacheKey(aid, certFingerprint));
-        // 带 fingerprint 查不到时，降级用 aid 再查一次
-        if (!cached && certFingerprint) {
-            cached = this._certCache.get(certCacheKey(aid, undefined));
-        }
-        const now = Date.now() / 1000;
-        if (cached && now < cached.validatedAt + PEER_CERT_CACHE_TTL * 2) {
-            return cached.certPem;
-        }
-        return null;
-    }
     // ── 客户端操作签名 ────────────────────────────────
     /**
      * 为关键操作附加客户端 ECDSA 签名（_client_signature 字段）。
      * 使用 SubtleCrypto 异步签名。
      */
     async _signClientOperation(method, params) {
-        const currentAid = this._currentAid;
-        if (!currentAid?.privateKeyPem)
-            return;
-        try {
-            const aid = currentAid.aid;
-            const ts = String(Math.floor(Date.now() / 1000));
-            // 计算 params hash：覆盖所有非 _ 前缀且非 client_signature 的业务字段
-            const paramsForHash = {};
-            for (const [k, v] of Object.entries(params)) {
-                if (k !== 'client_signature' && !k.startsWith('_')) {
-                    paramsForHash[k] = v;
-                }
-            }
-            const paramsJson = stableStringify(paramsForHash);
-            // SHA-256 hash
-            const paramsHashBuf = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(paramsJson));
-            const paramsHash = Array.from(new Uint8Array(paramsHashBuf))
-                .map(b => b.toString(16).padStart(2, '0'))
-                .join('');
-            const signData = new TextEncoder().encode(`${method}|${aid}|${ts}|${paramsHash}`);
-            // 导入私钥并签名
-            const pkcs8 = pemToArrayBuffer(currentAid.privateKeyPem);
-            const cryptoKey = await crypto.subtle.importKey('pkcs8', pkcs8, { name: 'ECDSA', namedCurve: 'P-256' }, false, ['sign']);
-            const sigP1363 = await crypto.subtle.sign({ name: 'ECDSA', hash: 'SHA-256' }, cryptoKey, signData);
-            // P1363 → DER 格式（与 Python 兼容）
-            const sigDer = p1363ToDer(new Uint8Array(sigP1363));
-            // 证书指纹
-            let certFingerprint = '';
-            const certPem = currentAid.certPem;
-            if (certPem) {
-                const certDer = pemToArrayBuffer(certPem);
-                const fpBuf = await crypto.subtle.digest('SHA-256', certDer);
-                certFingerprint = 'sha256:' + Array.from(new Uint8Array(fpBuf)).map(b => b.toString(16).padStart(2, '0')).join('');
-            }
-            params.client_signature = {
-                aid,
-                cert_fingerprint: certFingerprint,
-                timestamp: ts,
-                params_hash: paramsHash,
-                signature: uint8ToBase64(sigDer),
-            };
-        }
-        catch (exc) {
-            throw new E2EEError(`客户端签名失败: ${exc instanceof Error ? exc.message : String(exc)}`);
-        }
+        await this._rpcPipeline.signClientOperation(method, params);
     }
     // ── 内部：连接 ────────────────────────────────────
     async _connectOnce(params, allowReauth) {
@@ -3165,7 +1643,7 @@ export class AUNClient {
             }
             catch (err) {
                 // P1-19: 首连失败时重置状态，避免半连接残留
-                this._state = 'disconnected';
+                this._state = 'standby';
                 try {
                     await this._transport.close();
                 }
@@ -3185,22 +1663,16 @@ export class AUNClient {
             this._startBackgroundTasks();
             const connectionKind = String(params.connection_kind ?? 'long');
             const isShortConnection = connectionKind === 'short';
+            const hasExplicitBackgroundSync = Object.prototype.hasOwnProperty.call(params, 'background_sync');
+            const backgroundSyncEnabled = this._sessionOptions?.background_sync !== false
+                && (!isShortConnection || hasExplicitBackgroundSync);
             if (!isShortConnection) {
-                // V2 E2EE: 长连接上线时初始化 session 并注册设备 SPK（与 Python `_init_v2_session` 对齐）
-                try {
-                    await this._initV2Session();
-                }
-                catch (exc) {
-                    this._clientLog.warn(`V2 session init failed (non-fatal): ${String(exc)}`);
-                }
+                await this._v2E2EE.onConnected({ backgroundSync: backgroundSyncEnabled });
             }
             else {
                 this._clientLog.debug('V2 session init deferred for short connection');
             }
             // connect/reconnect 成功后自动触发一次 P2P message.pull，补齐离线期间积压
-            const hasExplicitBackgroundSync = Object.prototype.hasOwnProperty.call(params, 'background_sync');
-            const backgroundSyncEnabled = this._sessionOptions?.background_sync !== false
-                && (!isShortConnection || hasExplicitBackgroundSync);
             if (backgroundSyncEnabled) {
                 this._safeAsync(this._fillP2pGap());
             }
@@ -3416,11 +1888,7 @@ export class AUNClient {
                     this._gapFillDone = new Set(arr.slice(arr.length - 5000));
                 }
                 const now = Date.now();
-                for (const [key, entry] of this._v2BootstrapCache) {
-                    if (now - entry.cachedAt >= AUNClient.V2_BOOTSTRAP_TTL_MS) {
-                        this._v2BootstrapCache.delete(key);
-                    }
-                }
+                this._v2E2EE.pruneExpiredBootstrapCache(AUNClient.V2_BOOTSTRAP_TTL_MS, now);
                 for (const [key, exp] of this._v2SigCache) {
                     if (exp <= now)
                         this._v2SigCache.delete(key);
@@ -3575,78 +2043,14 @@ export class AUNClient {
         };
         scheduleRefresh(0);
     }
-    _normalizeOutboundMessagePayload(params, method = '') {
-        if (!Object.prototype.hasOwnProperty.call(params, 'payload') && Object.prototype.hasOwnProperty.call(params, 'content')) {
-            params.payload = params.content;
-            delete params.content;
-        }
-        const payload = params.payload;
-        if (isJsonObject(payload) && !Object.prototype.hasOwnProperty.call(payload, 'type') && typeof payload.text === 'string') {
-            params.payload = { type: 'text', ...payload };
-        }
-    }
     _validateMessageRecipient(toAid) {
-        if (isGroupServiceAid(toAid)) {
-            throw new ValidationError('message.send receiver cannot be group.{issuer}; use group.send instead');
-        }
+        this._rpcPipeline.validateMessageRecipient(toAid);
     }
     _validateOutboundCall(method, params) {
-        if (method === 'message.send') {
-            this._validateMessageRecipient(params.to);
-            if ('persist' in params) {
-                throw new ValidationError("message.send no longer accepts 'persist'; configure delivery_mode during connect");
-            }
-            if ('delivery_mode' in params || 'queue_routing' in params || 'affinity_ttl_ms' in params) {
-                throw new ValidationError('message.send does not accept delivery_mode; configure delivery_mode during connect');
-            }
-        }
-        if (method === 'group.send') {
-            if ('persist' in params) {
-                throw new ValidationError("group.send does not accept 'persist'; group messages are always fanout");
-            }
-            if ('delivery_mode' in params || 'queue_routing' in params || 'affinity_ttl_ms' in params) {
-                throw new ValidationError('group.send does not accept delivery_mode; group messages are always fanout');
-            }
-        }
-        if (method === 'group.thought.put' || method === 'group.thought.get'
-            || method === 'message.thought.put' || method === 'message.thought.get') {
-            const context = isJsonObject(params.context) ? params.context : null;
-            const contextType = String(context?.type ?? '').trim();
-            const contextId = String(context?.id ?? '').trim();
-            const hasContext = contextType.length > 0 && contextId.length > 0;
-            if (!hasContext) {
-                throw new ValidationError(`${method} requires context.type + context.id`);
-            }
-        }
-        if (method === 'group.thought.get' && !String(params.sender_aid ?? '').trim()) {
-            throw new ValidationError('group.thought.get requires sender_aid');
-        }
-        if (method === 'message.thought.put') {
-            this._validateMessageRecipient(params.to);
-            if (!String(params.to ?? '').trim()) {
-                throw new ValidationError('message.thought.put requires to');
-            }
-        }
-        if (method === 'message.thought.get' && !String(params.sender_aid ?? '').trim()) {
-            throw new ValidationError('message.thought.get requires sender_aid');
-        }
-    }
-    _currentMessageDeliveryMode() {
-        return { ...this._connectDeliveryMode };
+        this._rpcPipeline.validateOutboundCall(method, params);
     }
     _injectMessageCursorContext(method, params) {
-        if (method !== 'message.pull' && method !== 'message.ack') {
-            return;
-        }
-        if ('device_id' in params && String(params.device_id ?? '').trim() !== this._deviceId) {
-            throw new ValidationError('message.pull/message.ack device_id must match the current client instance');
-        }
-        const slotId = normalizeSlotId(params.slot_id ?? this._slotId, this._slotId);
-        if (slotIsolationKey(slotId) !== slotIsolationKey(this._slotId)) {
-            throw new ValidationError('message.pull/message.ack slot_id must match the current client instance');
-        }
-        params.device_id = this._deviceId;
-        params.slot_id = this._slotId;
+        this._rpcPipeline.injectMessageCursorContext(method, params);
     }
     // ── 内部：断线重连 ────────────────────────────────
     /** 不重连 close code 集合：认证失败/权限错误/被踢等，重连无意义 */
@@ -3676,7 +2080,7 @@ export class AUNClient {
     async _handleTransportDisconnect(error, closeCode) {
         if (this._closing || this._state === 'closed')
             return;
-        this._state = 'disconnected';
+        this._state = 'standby';
         // 先停止后台任务，避免心跳/token刷新在重连期间继续触发
         this._stopBackgroundTasks();
         await this._dispatcher.publish('state_change', {
@@ -3808,76 +2212,6 @@ export class AUNClient {
         this._reconnectActive = false;
         this._reconnectAbort = null;
     }
-    // ── Named Group（命名群）高层 API ────────────────────────────
-    /**
-     * 创建命名群：群/P2P 私钥由 V2 数据库存储，不写入 AID 身份私钥存储。
-     */
-    async createNamedGroup(groupName, opts = {}) {
-        const tStart = Date.now();
-        this._clientLog.debug(`createNamedGroup enter: name=${groupName}`);
-        try {
-            const cp = new CryptoProvider();
-            const identity = await cp.generateIdentity();
-            const params = {};
-            for (const [k, v] of Object.entries(opts)) {
-                params[k] = v;
-            }
-            params.group_name = groupName;
-            params.public_key = identity.public_key_der_b64;
-            params.curve = 'P-256';
-            const result = await this.call('group.create', params);
-            const groupInfo = result?.group;
-            const aidCert = result?.aid_cert;
-            const groupAid = String(groupInfo?.group_aid ?? '');
-            if (groupAid && aidCert) {
-                await this._saveGroupIdentityToV2(groupAid, identity);
-                const certPem = String(aidCert.cert ?? '');
-                if (certPem) {
-                    await this._tokenStore.saveCert(groupAid, certPem);
-                }
-            }
-            this._clientLog.debug(`createNamedGroup exit: elapsed=${Date.now() - tStart}ms group_aid=${groupAid}`);
-            return result;
-        }
-        catch (err) {
-            this._clientLog.debug(`createNamedGroup exit (error): elapsed=${Date.now() - tStart}ms err=${err instanceof Error ? err.message : String(err)}`);
-            throw err;
-        }
-    }
-    /**
-     * 为已有普通群绑定命名 AID（升级为命名群）。
-     */
-    async bindGroupAid(groupId, groupName) {
-        const tStart = Date.now();
-        this._clientLog.debug(`bindGroupAid enter: group_id=${groupId} name=${groupName}`);
-        try {
-            const cp = new CryptoProvider();
-            const identity = await cp.generateIdentity();
-            const params = {
-                group_id: groupId,
-                group_name: groupName,
-                public_key: identity.public_key_der_b64,
-                curve: 'P-256',
-            };
-            const result = await this.call('group.bind_aid', params);
-            const groupInfo = result?.group;
-            const aidCert = result?.aid_cert;
-            const groupAid = String(groupInfo?.group_aid ?? '');
-            if (groupAid && aidCert) {
-                await this._saveGroupIdentityToV2(groupAid, identity);
-                const certPem = String(aidCert.cert ?? '');
-                if (certPem) {
-                    await this._tokenStore.saveCert(groupAid, certPem);
-                }
-            }
-            this._clientLog.debug(`bindGroupAid exit: elapsed=${Date.now() - tStart}ms group_aid=${groupAid}`);
-            return result;
-        }
-        catch (err) {
-            this._clientLog.debug(`bindGroupAid exit (error): elapsed=${Date.now() - tStart}ms err=${err instanceof Error ? err.message : String(err)}`);
-            throw err;
-        }
-    }
     /** 判断是否应重试重连 */
     _shouldRetryReconnect(error) {
         if (error instanceof AuthError) {
@@ -3901,113 +2235,7 @@ export class AUNClient {
     // ── 内部：工具方法 ────────────────────────────────
     /** 从 keystore 恢复 SeqTracker 状态（真正可 await，确保在 transport.connect 前完成） */
     async _restoreSeqTrackerState() {
-        if (!this._aid)
-            return;
-        const context = this._seqTrackerContext;
-        if (!context)
-            return;
-        const aid = this._aid;
-        const deviceId = this._deviceId;
-        const slotId = this._slotId;
-        try {
-            // 优先从 seq_tracker 表按行读取
-            const loadAll = this._tokenStore.loadAllSeqs?.bind(this._tokenStore);
-            if (typeof loadAll === 'function') {
-                let state = await loadAll(aid, deviceId, slotId);
-                if (this._seqTrackerContext !== context)
-                    return;
-                if (state && typeof state === 'object' && Object.keys(state).length > 0) {
-                    state = await this._migrateSeqStateGroupIds(state);
-                    this._seqTracker.restoreState(state);
-                }
-                return;
-            }
-            // fallback: 从旧 instance_state JSON blob 恢复
-            const loader = this._tokenStore.loadInstanceState?.bind(this._tokenStore);
-            if (typeof loader !== 'function')
-                return;
-            const stateHolder = await loader(aid, deviceId, slotId);
-            if (this._seqTrackerContext !== context)
-                return;
-            if (stateHolder && typeof stateHolder === 'object') {
-                const state = stateHolder.seq_tracker_state;
-                if (isJsonObject(state)) {
-                    const migrated = await this._migrateSeqStateGroupIds(state);
-                    this._seqTracker.restoreState(migrated);
-                }
-            }
-        }
-        catch (exc) {
-            this._dispatcher.publish('seq_tracker.persist_error', {
-                phase: 'restore',
-                aid,
-                device_id: deviceId,
-                slot_id: slotId,
-                error: String(exc),
-            }).catch(() => { });
-        }
-    }
-    /**
-     * 把 seq_tracker state 里 group_event:/group_msg: 前缀的老/污染 group_id 归一化。
-     * 冲突取 max；同时落盘删除老 ns、写入新 ns。
-     */
-    async _migrateSeqStateGroupIds(state) {
-        if (!state || Object.keys(state).length === 0)
-            return state;
-        const renameMap = {};
-        for (const ns of Object.keys(state)) {
-            for (const prefix of ['group_event:', 'group_msg:']) {
-                if (ns.startsWith(prefix)) {
-                    const oldGid = ns.slice(prefix.length);
-                    const newGid = normalizeGroupId(oldGid);
-                    if (newGid && newGid !== oldGid) {
-                        renameMap[ns] = `${prefix}${newGid}`;
-                    }
-                    break;
-                }
-            }
-        }
-        if (Object.keys(renameMap).length === 0)
-            return state;
-        const newState = { ...state };
-        for (const [oldNs, newNs] of Object.entries(renameMap)) {
-            const oldVal = Number(newState[oldNs] ?? 0);
-            const curVal = Number(newState[newNs] ?? 0);
-            delete newState[oldNs];
-            newState[newNs] = Math.max(oldVal, curVal);
-        }
-        if (!this._aid)
-            return newState;
-        const aid = this._aid;
-        const deviceId = this._deviceId;
-        const slotId = this._slotId;
-        const saver = this._tokenStore.saveSeq?.bind(this._tokenStore);
-        const deleter = this._tokenStore.deleteSeq?.bind(this._tokenStore);
-        if (typeof saver === 'function') {
-            for (const [oldNs, newNs] of Object.entries(renameMap)) {
-                if (typeof deleter === 'function') {
-                    try {
-                        await deleter(aid, deviceId, slotId, oldNs);
-                    }
-                    catch (e) {
-                        this._dispatcher.publish('seq_tracker.persist_error', {
-                            phase: 'migrate_delete', aid, device_id: deviceId, slot_id: slotId,
-                            ns: oldNs, error: String(e),
-                        }).catch(() => { });
-                    }
-                }
-                try {
-                    await saver(aid, deviceId, slotId, newNs, newState[newNs]);
-                }
-                catch (e) {
-                    this._dispatcher.publish('seq_tracker.persist_error', {
-                        phase: 'migrate_save', aid, device_id: deviceId, slot_id: slotId,
-                        ns: newNs, error: String(e),
-                    }).catch(() => { });
-                }
-            }
-        }
-        return newState;
+        return this._delivery.restoreSeqTrackerState();
     }
     _currentSeqTrackerContext() {
         if (!this._aid)
@@ -4015,6 +2243,7 @@ export class AUNClient {
         return JSON.stringify([this._aid, this._deviceId, this._slotId]);
     }
     _resetSeqTrackingState() {
+        this._resetV2IdentityRuntime();
         this._seqTracker = new SeqTracker();
         this._seqTrackerContext = null;
         this._gapFillDone.clear();
@@ -4023,6 +2252,12 @@ export class AUNClient {
         this._v2SenderIKPending.clear();
         this._v2SenderIKFetching.clear();
         this._groupSynced.clear();
+        this._onlineUnreadHintQueue.clear();
+        if (this._onlineUnreadHintTimer) {
+            clearTimeout(this._onlineUnreadHintTimer);
+            this._onlineUnreadHintTimer = null;
+        }
+        this._onlineUnreadHintDrainActive = false;
     }
     _refreshSeqTrackerContext() {
         const nextContext = this._currentSeqTrackerContext();
@@ -4035,83 +2270,26 @@ export class AUNClient {
         this._v2SenderIKPending.clear();
         this._v2SenderIKFetching.clear();
         this._groupSynced.clear();
+        this._onlineUnreadHintQueue.clear();
+        if (this._onlineUnreadHintTimer) {
+            clearTimeout(this._onlineUnreadHintTimer);
+            this._onlineUnreadHintTimer = null;
+        }
+        this._onlineUnreadHintDrainActive = false;
         this._seqTrackerContext = nextContext;
     }
     /** 将 SeqTracker 状态保存到 keystore */
     _saveSeqTrackerState() {
-        if (!this._aid)
-            return;
-        const state = this._seqTracker.exportState();
-        if (Object.keys(state).length === 0)
-            return;
-        try {
-            // 优先按行写入 seq_tracker 表
-            const saveFn = this._tokenStore.saveSeq?.bind(this._tokenStore);
-            if (typeof saveFn === 'function') {
-                for (const [ns, seq] of Object.entries(state)) {
-                    saveFn(this._aid, this._deviceId, this._slotId, ns, seq).catch((exc) => {
-                        this._dispatcher.publish('seq_tracker.persist_error', {
-                            phase: 'save',
-                            aid: this._aid,
-                            device_id: this._deviceId,
-                            slot_id: this._slotId,
-                            error: String(exc),
-                        }).catch(() => { });
-                    });
-                }
-                return;
-            }
-            // fallback: 旧版 updateInstanceState JSON blob
-            if (typeof this._tokenStore.updateInstanceState === 'function') {
-                this._tokenStore.updateInstanceState(this._aid, this._deviceId, this._slotId, (current) => {
-                    current.seq_tracker_state = state;
-                    return current;
-                }).catch((exc) => {
-                    this._dispatcher.publish('seq_tracker.persist_error', {
-                        phase: 'save',
-                        aid: this._aid,
-                        device_id: this._deviceId,
-                        slot_id: this._slotId,
-                        error: String(exc),
-                    }).catch(() => { });
-                });
-            }
-        }
-        catch (exc) {
-            this._dispatcher.publish('seq_tracker.persist_error', {
-                phase: 'save',
-                aid: this._aid,
-                device_id: this._deviceId,
-                slot_id: this._slotId,
-                error: String(exc),
-            }).catch(() => { });
-        }
+        return this._delivery.saveSeqTrackerState();
     }
     _persistRepairedSeq(ns) {
-        if (!this._aid || !ns)
-            return;
-        const seq = this._seqTracker.getContiguousSeq(ns);
-        try {
-            if (seq > 0 && typeof this._tokenStore.saveSeq === 'function') {
-                this._tokenStore.saveSeq(this._aid, this._deviceId, this._slotId, ns, seq).catch((exc) => {
-                    this._clientLog.debug(`persist repaired seq failed: ns=${ns} err=${formatCaughtError(exc)}`);
-                });
-                return;
-            }
-            const deleteSeq = this._tokenStore.deleteSeq;
-            if (seq <= 0 && typeof deleteSeq === 'function') {
-                deleteSeq.call(this._tokenStore, this._aid, this._deviceId, this._slotId, ns).catch((exc) => {
-                    this._clientLog.debug(`delete repaired seq failed: ns=${ns} err=${formatCaughtError(exc)}`);
-                });
-                return;
-            }
-            if (seq > 0) {
-                this._saveSeqTrackerState();
-            }
-        }
-        catch (exc) {
-            this._clientLog.debug(`persist repaired seq failed: ns=${ns} err=${formatCaughtError(exc)}`);
-        }
+        return this._delivery.persistRepairedSeq(ns);
+    }
+    _clampAckSeq(method, field, ns, seq) {
+        return this._delivery.clampAckSeq(method, field, ns, seq);
+    }
+    _clampAckParams(method, params) {
+        return this._delivery.clampAckParams(method, params);
     }
     _repairPushContiguousBound(ns, pushSeq, hasPayload, label) {
         if (!ns || !Number.isFinite(pushSeq) || pushSeq <= 0) {
@@ -4129,7 +2307,7 @@ export class AUNClient {
         return repaired;
     }
     async _ensureV2SessionReady(method, errorMessage) {
-        if (!this._v2Session) {
+        if (!this._v2SessionMatchesIdentity()) {
             if (!this._v2SessionInitInFlight) {
                 this._v2SessionInitInFlight = this._initV2Session()
                     .finally(() => {
@@ -4138,10 +2316,13 @@ export class AUNClient {
             }
             await this._v2SessionInitInFlight;
         }
-        if (!this._v2Session) {
+        if (!this._v2SessionMatchesIdentity()) {
             throw new StateError(errorMessage ?? `V2 session not initialized; encrypted ${method} requires E2EE V2`);
         }
     }
+    _v2CallFn() {
+        return async (method, params) => this.call(method, params);
+    }
     // ── V2 E2EE API（async，与 Python `client.py` `_init_v2_session` / `send_v2` / `pull_v2` / `ack_v2` 对齐） ──
     /**
      * 初始化 V2 session：从 AID PEM 私钥提取 raw scalar + DER 公钥，
@@ -4150,62 +2331,7 @@ export class AUNClient {
      * connect 成功后自动调用，可幂等手动调用。
      */
     async _initV2Session() {
-        if (!this._aid)
-            return;
-        // 私钥来自当前 AID 值对象，AUNClient 不从持久化存储读取私钥。
-        const currentAid = this._currentAid;
-        if (!currentAid?.privateKeyPem) {
-            this._clientLog.warn('V2 session init skipped: no AID private key');
-            return;
-        }
-        if (this._v2Session)
-            return;
-        // 1. PEM → DER PKCS8（去掉 header/footer 后 base64 解码）
-        const pem = currentAid.privateKeyPem.trim();
-        const pemBody = pem
-            .replace(/-----BEGIN [^-]+-----/g, '')
-            .replace(/-----END [^-]+-----/g, '')
-            .replace(/\s+/g, '');
-        const pkcs8Der = _v2B64ToBytes(pemBody);
-        // 2. 用 WebCrypto 导入 PKCS8 → 导出 jwk → 从 d 拿到 raw scalar
-        const privKey = await crypto.subtle.importKey('pkcs8', pkcs8Der.slice().buffer, { name: 'ECDH', namedCurve: 'P-256' }, true, ['deriveBits']);
-        const jwk = await crypto.subtle.exportKey('jwk', privKey);
-        if (jwk.kty !== 'EC' || jwk.crv !== 'P-256') {
-            throw new Error('AID private key must be EC P-256');
-        }
-        if (!jwk.d || !jwk.x || !jwk.y) {
-            throw new Error('AID private key jwk missing d/x/y');
-        }
-        const aidPriv = _v2LeftPad32(_v2B64uToBytes(jwk.d));
-        // 3. 从 jwk 公钥导出 SPKI DER
-        const pubKey = await crypto.subtle.importKey('jwk', { kty: 'EC', crv: 'P-256', x: jwk.x, y: jwk.y, ext: true }, { name: 'ECDSA', namedCurve: 'P-256' }, true, ['verify']);
-        const aidPubDer = new Uint8Array(await crypto.subtle.exportKey('spki', pubKey));
-        // 4. 打开 V2 KeyStore（IndexedDB）
-        if (!this._v2KeyStore) {
-            this._v2KeyStore = await V2KeyStore.open();
-        }
-        this._v2Session = new V2Session(this._v2KeyStore, this._deviceId, this._aid, aidPriv, aidPubDer);
-        const callFn = async (method, params) => {
-            return this.call(method, params);
-        };
-        await this._v2Session.ensureRegistered(callFn);
-        this._clientLog.debug(`V2 session initialized aid=${this._aid} device=${this._deviceId}`);
-        // 上线时自动确认 pending state proposals
-        this._safeAsync(this._v2AutoConfirmPendingProposals());
-    }
-    _v2StoreDeviceId() {
-        return `aid:${encodeURIComponent(String(this._aid ?? ''))}|device:${encodeURIComponent(String(this._deviceId ?? ''))}`;
-    }
-    async _saveGroupIdentityToV2(groupAid, identity) {
-        const privateKeyPem = String(identity.private_key_pem ?? '').trim();
-        const publicKeyDerB64 = String(identity.public_key_der_b64 ?? '').trim();
-        if (!groupAid || !privateKeyPem || !publicKeyDerB64) {
-            throw new StateError('group identity is incomplete');
-        }
-        if (!this._v2KeyStore) {
-            this._v2KeyStore = await V2KeyStore.open();
-        }
-        await this._v2KeyStore.saveGroupIdentity(this._v2StoreDeviceId(), groupAid, privateKeyPem, base64ToUint8(publicKeyDerB64));
+        return this._v2E2EE.initV2Session();
     }
     async _v2TrustedIKPubDer(aid) {
         const normalizedAid = String(aid ?? '').trim();
@@ -4251,7 +2377,7 @@ export class AUNClient {
         if (!args.spkPkDer || args.spkPkDer.length === 0) {
             throw new E2EEError(`spk_public_key_missing: aid=${args.aid} device_id=${args.deviceId} spk_id=${spkId}`);
         }
-        const spkHash = bytesToHex(new Uint8Array(await crypto.subtle.digest('SHA-256', args.spkPkDer.slice().buffer)));
+        const spkHash = bytesToHex(new Uint8Array(await crypto.subtle.digest('SHA-256', exactArrayBuffer(args.spkPkDer))));
         const expectedSpkId = `sha256:${spkHash.substring(0, 16)}`;
         if (spkId !== expectedSpkId) {
             throw new E2EEError(`spk_id_mismatch: aid=${args.aid} device_id=${args.deviceId} spk_id=${spkId} expected=${expectedSpkId}`);
@@ -4305,34 +2431,8 @@ export class AUNClient {
             spkId: String(args.dev.spk_id ?? '').trim(),
         };
     }
-    async _getV2SenderPubDer(fromAid, senderDeviceId) {
-        const session = this._v2Session;
-        if (!session || !fromAid)
-            return null;
-        let senderPubDer = session.getPeerIK(fromAid, senderDeviceId);
-        if (senderPubDer)
-            return senderPubDer;
-        try {
-            const certPem = await this._fetchPeerCert(fromAid, undefined, 3000);
-            const pubKey = await importCertPublicKeyEcdsa(certPem);
-            senderPubDer = new Uint8Array(await crypto.subtle.exportKey('spki', pubKey));
-            session.cachePeerIK(fromAid, senderDeviceId, senderPubDer);
-            this._clientLog.debug(`V2 decrypt: sender IK fallback from PKI cert for ${fromAid}`);
-            return senderPubDer;
-        }
-        catch (exc) {
-            this._clientLog.warn(`V2 decrypt: PKI cert sender IK fallback failed for ${fromAid}: ${String(formatCaughtError(exc))}`);
-            return null;
-        }
-    }
-    _v2PendingSenderIKMessageKey(msg, groupId) {
-        const messageId = String(msg.message_id ?? '').trim();
-        const seq = String(msg.seq ?? '').trim();
-        const prefix = groupId ? `group:${groupId}` : `p2p:${this._aid ?? ''}`;
-        return `${prefix}:${messageId || seq || Math.random().toString(36).slice(2)}`;
-    }
-    _v2PendingSenderIKFetchKey(fromAid, senderDeviceId, groupId) {
-        return `${fromAid}#${senderDeviceId}#${groupId || ''}`;
+    async _getV2SenderPubDer(fromAid, senderDeviceId, certFingerprint) {
+        return await this._v2E2EE.getV2SenderPubDer(fromAid, senderDeviceId, certFingerprint);
     }
     _cacheV2PeerIKFromDevice(dev, fallbackAid = '') {
         const session = this._v2Session;
@@ -4352,94 +2452,10 @@ export class AUNClient {
         }
     }
     _scheduleV2SenderIKPending(args) {
-        const fromAid = String(args.fromAid ?? '').trim();
-        if (!fromAid)
-            return;
-        const senderDeviceId = String(args.senderDeviceId ?? '');
-        const groupId = String(args.groupId ?? '').trim();
-        const messageKey = this._v2PendingSenderIKMessageKey(args.msg, groupId);
-        this._v2SenderIKPending.set(messageKey, {
-            msg: { ...args.msg },
-            fromAid,
-            senderDeviceId,
-            groupId,
-            createdAt: Date.now(),
-        });
-        this._clientLog.debug(`V2 decrypt pending sender IK: key=${messageKey} from=${fromAid} device=${senderDeviceId || '-'} group=${groupId || '<p2p>'} pending=${this._v2SenderIKPending.size}`);
-        this._scheduleV2SenderIKFetch(fromAid, senderDeviceId, groupId);
-    }
-    _scheduleV2SenderIKFetch(fromAid, senderDeviceId, groupId) {
-        const fetchKey = this._v2PendingSenderIKFetchKey(fromAid, senderDeviceId, groupId);
-        if (!fromAid || this._v2SenderIKFetching.has(fetchKey))
-            return;
-        this._v2SenderIKFetching.add(fetchKey);
-        this._safeAsync(this._resolveV2SenderIKPending(fromAid, senderDeviceId, groupId, fetchKey));
+        return this._v2E2EE.scheduleSenderIKPending(args);
     }
     async _resolveV2SenderIKPending(fromAid, senderDeviceId, groupId, fetchKey) {
-        try {
-            const session = this._v2Session;
-            if (session && fromAid) {
-                try {
-                    const bs = await this.call('message.v2.bootstrap', {
-                        peer_aid: fromAid,
-                        e2ee_wrap_capabilities: v2WrapCapabilities(),
-                    });
-                    const peers = (Array.isArray(bs?.peer_devices) ? bs.peer_devices : []);
-                    for (const dev of peers)
-                        this._cacheV2PeerIKFromDevice(dev, fromAid);
-                }
-                catch (exc) {
-                    this._clientLog.warn(`V2 sender IK pending bootstrap failed peer=${fromAid}: ${String(formatCaughtError(exc))}`);
-                }
-                if (groupId) {
-                    try {
-                        const gbs = await this.call('group.v2.bootstrap', {
-                            group_id: groupId,
-                            e2ee_wrap_capabilities: v2WrapCapabilities(),
-                        });
-                        const devices = (Array.isArray(gbs?.devices) ? gbs.devices : []);
-                        const audit = (Array.isArray(gbs?.audit_recipients) ? gbs.audit_recipients : []);
-                        for (const dev of devices)
-                            this._cacheV2PeerIKFromDevice(dev);
-                        for (const dev of audit)
-                            this._cacheV2PeerIKFromDevice(dev);
-                    }
-                    catch (exc) {
-                        this._clientLog.warn(`V2 sender IK pending group bootstrap failed group=${groupId}: ${String(formatCaughtError(exc))}`);
-                    }
-                }
-                if (!session.getPeerIK(fromAid, senderDeviceId)) {
-                    await this._getV2SenderPubDer(fromAid, senderDeviceId);
-                }
-            }
-            const pendingItems = [...this._v2SenderIKPending.entries()].filter(([, entry]) => entry.fromAid === fromAid && entry.senderDeviceId === senderDeviceId && entry.groupId === groupId);
-            for (const [key, entry] of pendingItems) {
-                let plaintext = null;
-                try {
-                    plaintext = await this._decryptV2Message(entry.msg, false);
-                }
-                catch (exc) {
-                    this._clientLog.warn(`V2 sender IK pending retry raised: key=${key} err=${String(formatCaughtError(exc))}`);
-                }
-                this._v2SenderIKPending.delete(key);
-                if (plaintext === null) {
-                    this._clientLog.debug(`V2 sender IK pending retry failed: key=${key}`);
-                    continue;
-                }
-                const seq = Number(entry.msg.seq ?? 0);
-                if (entry.groupId) {
-                    plaintext.group_id = entry.groupId;
-                    await this._publishPulledMessage('group.message_created', `group:${entry.groupId}`, seq, plaintext);
-                }
-                else {
-                    await this._publishPulledMessage('message.received', `p2p:${this._aid ?? ''}`, seq, plaintext);
-                }
-                this._clientLog.debug(`V2 sender IK pending retry delivered: key=${key}`);
-            }
-        }
-        finally {
-            this._v2SenderIKFetching.delete(fetchKey);
-        }
+        return await this._v2E2EE.resolveSenderIKPending(fromAid, senderDeviceId, groupId, fetchKey);
     }
     /**
      * V2 P2P 加密发送（推测性：用缓存 bootstrap 直接发，失败刷新重试一次）。
@@ -4450,42 +2466,7 @@ export class AUNClient {
      * @returns 服务端响应
      */
     async _sendV2(to, payload, opts) {
-        if (!this._v2Session) {
-            throw new StateError('V2 session not initialized (not connected?)');
-        }
-        const toAid = String(to ?? '').trim();
-        if (!toAid)
-            throw new ValidationError("message.send requires 'to'");
-        if (!isJsonObject(payload))
-            throw new ValidationError('message.send payload must be a dict for V2 encryption');
-        const attempt = async (useCache) => {
-            const envelope = await this._buildV2P2PEnvelope({
-                to: toAid,
-                payload,
-                messageId: opts?.messageId,
-                timestamp: opts?.timestamp,
-                protectedHeaders: opts?.protectedHeaders,
-                context: opts?.context,
-                useCache,
-            });
-            return this.call('message.send', {
-                to: toAid,
-                payload: envelope,
-                encrypt: false,
-            });
-        };
-        try {
-            return await attempt(true);
-        }
-        catch (exc) {
-            const excCode = exc?.code;
-            if (AUNClient.V2_RETRYABLE_CODES.has(excCode)) {
-                this._clientLog.debug(`V2 P2P speculative send rejected (code=${excCode}), refreshing bootstrap`);
-                this._v2BootstrapCache.delete(toAid);
-                return attempt(false);
-            }
-            throw exc;
-        }
+        return await this._v2E2EE.sendV2(to, payload, opts);
     }
     /**
      * 拉取并解密 V2 P2P 消息。
@@ -4494,117 +2475,7 @@ export class AUNClient {
      * @param limit 最多拉取条数
      */
     async _pullV2(afterSeq = 0, limit = 50, opts) {
-        if (!this._v2Session) {
-            throw new StateError('V2 session not initialized (not connected?)');
-        }
-        const ns = this._aid ? `p2p:${this._aid}` : '';
-        const decrypted = [];
-        let nextAfterSeq = opts?.force ? afterSeq : (afterSeq || (ns ? this._seqTracker.getContiguousSeq(ns) : 0));
-        let pageCount = 0;
-        const maxPages = 100;
-        while (pageCount < maxPages) {
-            pageCount += 1;
-            const result = await this._callRawV2Rpc('message.v2.pull', {
-                after_seq: nextAfterSeq,
-                limit,
-                ...(opts?.force ? { force: true } : {}),
-            });
-            const messages = (Array.isArray(result?.messages) ? result.messages : []);
-            const seqs = messages
-                .map((msg) => Number(msg.seq ?? 0))
-                .filter((seq) => Number.isFinite(seq) && seq > 0);
-            const pageContigBefore = ns ? this._seqTracker.getContiguousSeq(ns) : 0;
-            const pageMaxSeq = seqs.length > 0 ? Math.max(...seqs) : nextAfterSeq;
-            if (ns && seqs.length > 0) {
-                this._seqTracker.forceContiguousSeq(ns, pageMaxSeq);
-            }
-            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;
-                    const payloadType = isJsonObject(legacyPayload)
-                        ? String(legacyPayload.type ?? '').trim()
-                        : '';
-                    if (legacyPayload !== undefined && legacyPayload !== null
-                        && payloadType !== 'e2ee.encrypted' && payloadType !== 'e2ee.group_encrypted') {
-                        const v1Msg = {
-                            message_id: String(msg.message_id ?? ''),
-                            from: String(msg.from_aid ?? ''),
-                            to: String(legacy.to ?? this._aid ?? ''),
-                            seq: msg.seq,
-                            type: String(msg.type ?? ''),
-                            timestamp: msg.t_server,
-                            payload: legacyPayload,
-                            encrypted: false,
-                        };
-                        if (ns)
-                            await this._publishPulledMessage('message.received', ns, seq, v1Msg);
-                        else
-                            await this._publishAppEvent('message.received', v1Msg);
-                        decrypted.push(v1Msg);
-                    }
-                    else {
-                        this._clientLog.debug(`message.v2.pull skipping V1 envelope seq=${seq} payload_type=${payloadType || '<none>'} (V1 E2EE removed)`);
-                    }
-                    continue;
-                }
-                if (version !== 'v2') {
-                    this._clientLog.debug(`message.v2.pull skipping non-V2 row seq=${seq} version=${String(msg.version ?? '')}`);
-                    continue;
-                }
-                // 跟踪每个旧 SPK 引用的最大 seq（用于消费后销毁）
-                const msgSpkId = String(msg.spk_id ?? '');
-                if (msgSpkId && this._v2Session && !this._v2Session.isCurrentSPK(msgSpkId)) {
-                    this._v2Session.trackOldSPKMaxSeq(msgSpkId, seq);
-                }
-                const plaintext = await this._decryptV2Message(msg);
-                if (plaintext === null)
-                    continue;
-                if (ns) {
-                    await this._publishPulledMessage('message.received', ns, seq, plaintext);
-                    decrypted.push(plaintext);
-                }
-                else {
-                    await this._publishAppEvent('message.received', plaintext);
-                    decrypted.push(plaintext);
-                }
-            }
-            const hasServerAckSeq = Object.prototype.hasOwnProperty.call(result, 'server_ack_seq');
-            const serverAckSeq = Number(result.server_ack_seq ?? 0);
-            if (ns && Number.isFinite(serverAckSeq) && serverAckSeq > 0) {
-                const contig = this._seqTracker.getContiguousSeq(ns);
-                if (contig < serverAckSeq) {
-                    this._clientLog.info(`message.v2.pull retention-floor advance: ns=${ns} contiguous=${contig} -> server_ack_seq=${serverAckSeq}`);
-                    this._seqTracker.forceContiguousSeq(ns, serverAckSeq);
-                }
-            }
-            if (ns) {
-                const ackSeq = this._seqTracker.getContiguousSeq(ns);
-                const contigAdvanced = ackSeq !== pageContigBefore;
-                if (contigAdvanced) {
-                    await this._drainOrderedMessages(ns);
-                    this._saveSeqTrackerState();
-                }
-                const ackNeeded = messages.length > 0
-                    && ackSeq > 0
-                    && (contigAdvanced || (hasServerAckSeq && ackSeq > serverAckSeq));
-                if (ackNeeded) {
-                    this._safeAsync(this._ackV2(ackSeq).then(() => undefined));
-                }
-            }
-            const nextAfter = Math.max(pageMaxSeq, nextAfterSeq);
-            if (messages.length === 0 || nextAfter <= nextAfterSeq || result.has_more === false)
-                break;
-            nextAfterSeq = nextAfter;
-        }
-        if (pageCount >= maxPages) {
-            this._clientLog.warn(`message.v2.pull reached max_pages=${maxPages} after_seq=${nextAfterSeq}`);
-        }
-        return decrypted;
+        return await this._v2E2EE.pullV2(afterSeq, limit, opts);
     }
     /**
      * 确认 V2 消息已消费 + 自检销毁旧 SPK（PFS）。
@@ -4612,47 +2483,7 @@ export class AUNClient {
      * @param upToSeq 确认到此 seq；省略则用当前 contiguous
      */
     async _ackV2(upToSeq) {
-        const ns = this._aid ? `p2p:${this._aid}` : '';
-        let seq = upToSeq ?? (ns ? this._seqTracker.getContiguousSeq(ns) : 0);
-        if (seq <= 0)
-            return { acked: 0 };
-        // ack clamp：永远不发送超过 maxSeenSeq 的 up_to_seq
-        if (ns) {
-            const maxSeen = this._seqTracker.getMaxSeenSeq(ns);
-            if (maxSeen > 0 && seq > maxSeen) {
-                this._clientLog.warn(`ackV2 clamp: up_to_seq=${seq} > max_seen=${maxSeen}, clamp`);
-                seq = maxSeen;
-            }
-        }
-        const raw = await this._callRawV2Rpc('message.v2.ack', { up_to_seq: seq });
-        const result = isJsonObject(raw)
-            ? { ...raw }
-            : { result: raw };
-        let actualAckSeq = seq;
-        if ('effective_ack_seq' in result)
-            actualAckSeq = Number(result.effective_ack_seq ?? 0);
-        else if ('ack_seq' in result)
-            actualAckSeq = Number(result.ack_seq ?? 0);
-        else if ('cursor' in result)
-            actualAckSeq = Number(result.cursor ?? 0);
-        if (!Number.isFinite(actualAckSeq))
-            actualAckSeq = seq;
-        result.ack_seq = actualAckSeq;
-        result.success = true;
-        if (Number(result.acked ?? 0) === 0)
-            result.acked = actualAckSeq;
-        if (this._v2Session) {
-            try {
-                const destroyed = await this._v2Session.maybeDestroyOldSPKs(actualAckSeq);
-                if (destroyed.length > 0) {
-                    this._clientLog.info(`V2 destroyed old SPKs after ack: ${destroyed.slice(0, 3)} (PFS)`);
-                }
-            }
-            catch (exc) {
-                this._clientLog.debug(`V2 SPK destroy failed (non-fatal): ${String(exc)}`);
-            }
-        }
-        return result;
+        return await this._v2E2EE.ackV2(upToSeq);
     }
     /** 解密单条 V2 消息（与 Python `_decrypt_v2_message` 对齐）。缺 sender IK 时先入 pending，后台补齐后重试。 */
     async _decryptV2Message(msg, allowPending = true) {
@@ -4744,7 +2575,8 @@ export class AUNClient {
         }
         const fromAid = String(msg.from_aid ?? '');
         const senderDeviceId = String(aad.from_device ?? '');
-        const senderPubDer = await this._getV2SenderPubDer(fromAid, senderDeviceId);
+        const senderCertFingerprint = String(envelope.sender_cert_fingerprint ?? '').trim().toLowerCase();
+        const senderPubDer = await this._getV2SenderPubDer(fromAid, senderDeviceId, senderCertFingerprint);
         if (!senderPubDer) {
             this._clientLog.warn(`V2 decrypt: no sender IK for ${fromAid} device=${senderDeviceId}`);
             if (allowPending) {
@@ -4764,7 +2596,6 @@ export class AUNClient {
                     _decrypt_stage: 'sender_ik',
                     _envelope_type: String(envelope.type ?? ''),
                     _suite: String(envelope.suite ?? ''),
-                    _sender_device_id: String(aad.from_device ?? ''),
                 };
                 attachV2EnvelopeMetadata(event, e2eeMeta);
                 await this._dispatcher.publish(undecryptableEvent, event);
@@ -4791,7 +2622,6 @@ export class AUNClient {
                     _decrypt_stage: 'decrypt',
                     _envelope_type: String(envelope.type ?? ''),
                     _suite: String(envelope.suite ?? ''),
-                    _sender_device_id: String(aad.from_device ?? ''),
                 };
                 attachV2EnvelopeMetadata(event, e2eeMeta);
                 await this._dispatcher.publish(undecryptableEvent, event);
@@ -4803,16 +2633,10 @@ export class AUNClient {
             return null;
         // 消费触发 SPK 轮换（fire-and-forget，不阻塞消息处理）
         if (groupIdForKeys && recipientKeySource === 'group_device_prekey' && session.isLastUploadedGroupSPK(groupIdForKeys, spkId)) {
-            const callFn = async (method, params) => this.call(method, params);
-            session.rotateGroupSPK(groupIdForKeys, callFn).catch(exc => {
-                this._clientLog.debug(`V2 group SPK rotation failed (non-fatal): group=${groupIdForKeys} err=${exc}`);
-            });
+            this._v2E2EE.scheduleGroupSpkRotation(groupIdForKeys, { reason: 'group_spk_consumed' });
         }
         else if (groupIdForKeys && recipientKeySource === 'peer_device_prekey') {
-            const callFn = async (method, params) => this.call(method, params);
-            session.ensureGroupRegistered(groupIdForKeys, callFn).catch(exc => {
-                this._clientLog.debug(`V2 group SPK registration after peer fallback failed (non-fatal): group=${groupIdForKeys} err=${exc}`);
-            });
+            this._v2E2EE.scheduleGroupSpkRegistrationAfterPeerFallback(groupIdForKeys);
         }
         else if (!groupIdForKeys && session.isLastUploadedSPK(spkId)) {
             const callFn = async (method, params) => this.call(method, params);
@@ -4837,6 +2661,7 @@ export class AUNClient {
             result.device_id = msg.device_id;
         if (msg.slot_id !== undefined)
             result.slot_id = msg.slot_id;
+        attachGatewayProximity(result, msg);
         attachV2EnvelopeMetadata(result, e2ee);
         return result;
     }
@@ -4849,65 +2674,10 @@ export class AUNClient {
      * @returns 服务端响应
      */
     async _sendGroupV2(groupId, payload, opts) {
-        if (!this._v2Session) {
-            throw new StateError('V2 session not initialized (not connected?)');
-        }
-        const gid = normalizeGroupId(groupId) || String(groupId ?? '').trim();
-        if (!gid)
-            throw new ValidationError("group.send requires 'group_id'");
-        if (!isJsonObject(payload))
-            throw new ValidationError('group.send payload must be a dict for V2 encryption');
-        const attempt = async (useCache) => {
-            const envelope = await this._buildV2GroupEnvelope({
-                groupId: gid,
-                payload,
-                messageId: opts?.messageId,
-                timestamp: opts?.timestamp,
-                protectedHeaders: opts?.protectedHeaders,
-                context: opts?.context,
-                useCache,
-            });
-            return this.call('group.v2.send', {
-                group_id: gid,
-                envelope: envelope,
-            });
-        };
-        try {
-            const result = await attempt(true);
-            // 发送成功后记录自己发的消息 seq，保证 SeqTracker 连续 + push 时去重
-            if (isJsonObject(result)) {
-                const seq = Number(result.seq ?? 0);
-                if (seq > 0) {
-                    const ns = `group:${gid}`;
-                    this._seqTracker.onMessageSeq(ns, seq);
-                    this._markPublishedSeq(ns, seq);
-                    this._saveSeqTrackerState();
-                }
-            }
-            return result;
-        }
-        catch (exc) {
-            const excCode = exc?.code;
-            if (AUNClient.V2_RETRYABLE_CODES.has(excCode)) {
-                this._clientLog.debug(`V2 group speculative send rejected (code=${excCode}), refreshing bootstrap`);
-                this._v2BootstrapCache.delete(`group:${gid}`);
-                const result = await attempt(false);
-                if (isJsonObject(result)) {
-                    const seq = Number(result.seq ?? 0);
-                    if (seq > 0) {
-                        const ns = `group:${gid}`;
-                        this._seqTracker.onMessageSeq(ns, seq);
-                        this._markPublishedSeq(ns, seq);
-                        this._saveSeqTrackerState();
-                    }
-                }
-                return result;
-            }
-            throw exc;
-        }
+        return await this._v2E2EE.sendGroupV2(groupId, payload, opts);
     }
     async _pullGroupV2Internal(params) {
-        await this._pullGroupV2(params.group_id, params.after_seq, params.limit);
+        return await this._v2E2EE.pullGroupV2Internal(params);
     }
     /**
      * 拉取并解密 V2 Group 消息。
@@ -4917,146 +2687,7 @@ export class AUNClient {
      * @param limit 最多拉取条数
      */
     async _pullGroupV2(groupId, afterSeq = 0, limit = 50, opts) {
-        if (!this._v2Session) {
-            throw new StateError('V2 session not initialized (not connected?)');
-        }
-        const gid = normalizeGroupId(groupId) || String(groupId ?? '').trim();
-        if (!gid)
-            throw new ValidationError('group.pull requires group_id');
-        const ns = `group:${gid}`;
-        const decrypted = [];
-        const cursorParams = opts?.cursorParams ?? {};
-        const ownsCursor = opts?.ownsCursor !== false;
-        let nextAfterSeq = opts?.explicitAfterSeq ? afterSeq : (afterSeq || this._seqTracker.getContiguousSeq(ns));
-        let pageCount = 0;
-        const maxPages = 100;
-        while (pageCount < maxPages) {
-            pageCount += 1;
-            const result = await this._callRawV2Rpc('group.v2.pull', {
-                group_id: gid,
-                after_seq: nextAfterSeq,
-                limit,
-                ...cursorParams,
-            });
-            const messages = (Array.isArray(result?.messages) ? result.messages : []);
-            const seqs = messages
-                .map((msg) => Number(msg.seq ?? 0))
-                .filter((seq) => Number.isFinite(seq) && seq > 0);
-            const pageContigBefore = this._seqTracker.getContiguousSeq(ns);
-            const pageMaxSeq = seqs.length > 0 ? Math.max(...seqs) : nextAfterSeq;
-            if (seqs.length > 0) {
-                this._seqTracker.forceContiguousSeq(ns, pageMaxSeq);
-            }
-            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 payload = msg.payload;
-                    const payloadObj = isJsonObject(payload) ? payload : null;
-                    if (payloadObj) {
-                        const payloadType = String(payloadObj.type ?? '').trim();
-                        if (payloadType !== 'e2ee.encrypted' && payloadType !== 'e2ee.group_encrypted') {
-                            const v1Msg = {
-                                message_id: String(msg.message_id ?? ''),
-                                from: String(msg.from_aid ?? ''),
-                                group_id: gid,
-                                seq: msg.seq,
-                                type: String(msg.type ?? ''),
-                                timestamp: msg.t_server,
-                                payload,
-                                encrypted: false,
-                            };
-                            await this._publishPulledMessage('group.message_created', ns, seq, v1Msg);
-                            decrypted.push(v1Msg);
-                            continue;
-                        }
-                    }
-                    else if (payload !== undefined && payload !== null) {
-                        const v1Msg = {
-                            message_id: String(msg.message_id ?? ''),
-                            from: String(msg.from_aid ?? ''),
-                            group_id: gid,
-                            seq: msg.seq,
-                            type: String(msg.type ?? ''),
-                            timestamp: msg.t_server,
-                            payload,
-                            encrypted: false,
-                        };
-                        await this._publishPulledMessage('group.message_created', ns, seq, v1Msg);
-                        decrypted.push(v1Msg);
-                        continue;
-                    }
-                    this._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') {
-                    this._clientLog.debug(`group.v2.pull skipping non-V2 row group=${gid} seq=${seq} version=${String(msg.version ?? '')}`);
-                    continue;
-                }
-                const plaintext = await this._decryptV2Message(msg);
-                if (plaintext === null)
-                    continue;
-                plaintext.group_id = gid;
-                await this._publishPulledMessage('group.message_created', ns, seq, plaintext);
-                decrypted.push(plaintext);
-            }
-            const cursor = isJsonObject(result.cursor) ? result.cursor : null;
-            const hasServerCursor = cursor !== null && Object.prototype.hasOwnProperty.call(cursor, 'current_seq');
-            const serverAckSeq = Number(cursor?.current_seq ?? 0);
-            if (Number.isFinite(serverAckSeq) && serverAckSeq > 0) {
-                const contig = this._seqTracker.getContiguousSeq(ns);
-                if (contig < serverAckSeq) {
-                    this._clientLog.info(`group.v2.pull retention-floor advance: ns=${ns} contiguous=${contig} -> cursor.current_seq=${serverAckSeq}`);
-                    this._seqTracker.forceContiguousSeq(ns, serverAckSeq);
-                }
-            }
-            const ackSeq = this._seqTracker.getContiguousSeq(ns);
-            const contigAdvanced = ackSeq !== pageContigBefore;
-            if (contigAdvanced) {
-                await this._drainOrderedMessages(ns);
-                this._saveSeqTrackerState();
-            }
-            const ackNeeded = messages.length > 0
-                && ackSeq > 0
-                && ownsCursor
-                && (contigAdvanced || (hasServerCursor && ackSeq > serverAckSeq));
-            if (ackNeeded) {
-                this._safeAsync(this._ackGroupV2(gid, ackSeq).then(() => undefined));
-            }
-            const nextAfter = Math.max(pageMaxSeq, nextAfterSeq);
-            if (!ownsCursor)
-                break;
-            if (messages.length === 0 || nextAfter <= nextAfterSeq || result.has_more === false)
-                break;
-            nextAfterSeq = nextAfter;
-        }
-        if (pageCount >= maxPages) {
-            this._clientLog.warn(`group.v2.pull reached max_pages=${maxPages} group=${gid} after_seq=${nextAfterSeq}`);
-        }
-        return decrypted;
-    }
-    _groupCursorParams(params) {
-        const cursorParams = {};
-        for (const key of ['device_id', 'slot_id', 'device_name', 'device_type']) {
-            const value = params[key];
-            if (value !== undefined && value !== null)
-                cursorParams[key] = value;
-        }
-        return cursorParams;
-    }
-    _explicitGroupCursorParams(params) {
-        const value = params._group_cursor_params;
-        if (!isJsonObject(value))
-            return {};
-        return { ...value };
-    }
-    _groupCursorTargetsCurrentInstance(params) {
-        const deviceId = String(params.device_id ?? '').trim();
-        const slotId = String(params.slot_id ?? '').trim();
-        return (!deviceId || deviceId === (this._deviceId ?? ''))
-            && (!slotId || slotId === (this._slotId ?? ''));
+        return await this._v2E2EE.pullGroupV2(groupId, afterSeq, limit, opts);
     }
     async _rawGroupAckMessages(params) {
         const p = { ...params };
@@ -5069,132 +2700,15 @@ export class AUNClient {
      * @param upToSeq 确认到此 seq；省略则用当前 contiguous
      */
     async _ackGroupV2(groupId, upToSeq) {
-        const gid = normalizeGroupId(groupId) || String(groupId ?? '').trim();
-        if (!gid)
-            throw new ValidationError('group.ack_messages requires group_id');
-        const ns = `group:${gid}`;
-        let seq = upToSeq ?? this._seqTracker.getContiguousSeq(ns);
-        if (seq <= 0)
-            return { acked: 0 };
-        // ack clamp：永远不发送超过 maxSeenSeq 的 up_to_seq
-        const maxSeen = this._seqTracker.getMaxSeenSeq(ns);
-        if (maxSeen > 0 && seq > maxSeen) {
-            this._clientLog.warn(`ackGroupV2 clamp: group=${gid} up_to_seq=${seq} > max_seen=${maxSeen}, clamp`);
-            seq = maxSeen;
-        }
-        return this._callRawV2Rpc('group.v2.ack', { group_id: gid, up_to_seq: seq });
+        return await this._v2E2EE.ackGroupV2(groupId, upToSeq);
     }
-    // ── V2 thought（per-device wrap，服务端透传，不持久化）──────────
     /**
      * V2 P2P 多设备 wrap envelope 构造（不发送）。
      * thought.put 复用此函数构造与 message.send 相同的 V2 envelope。
      * 与 Python `_build_v2_p2p_envelope` 对齐。
      */
     async _buildV2P2PEnvelope(opts) {
-        if (!this._v2Session) {
-            throw new StateError('V2 session not initialized');
-        }
-        const session = this._v2Session;
-        const to = opts.to;
-        const useCache = opts.useCache !== false;
-        let peerDevices = [];
-        let auditRaw = [];
-        let wrapPolicy;
-        const cached = useCache ? this._v2BootstrapCache.get(to) : undefined;
-        if (cached && (Date.now() - cached.cachedAt) < AUNClient.V2_BOOTSTRAP_TTL_MS) {
-            peerDevices = cached.devices;
-            auditRaw = cached.auditRecipients;
-            wrapPolicy = cached.wrapPolicy;
-        }
-        else {
-            const bs = await this.call('message.v2.bootstrap', {
-                peer_aid: to,
-                e2ee_wrap_capabilities: v2WrapCapabilities(),
-            });
-            peerDevices = (Array.isArray(bs?.peer_devices) ? bs.peer_devices : []);
-            auditRaw = (Array.isArray(bs?.audit_recipients) ? bs.audit_recipients : []);
-            wrapPolicy = normalizeV2WrapPolicy(bs?.e2ee_wrap_policy);
-            if (peerDevices.length > 0) {
-                this._v2BootstrapCache.set(to, {
-                    devices: peerDevices,
-                    auditRecipients: auditRaw,
-                    cachedAt: Date.now(),
-                    wrapPolicy,
-                });
-            }
-        }
-        if (peerDevices.length === 0) {
-            throw new E2EEError(`V2 bootstrap: no devices found for ${to}`);
-        }
-        const targets = [];
-        for (const dev of peerDevices) {
-            const devId = getV2DeviceId(dev);
-            const target = await this._v2BuildTargetFromDevice({
-                dev,
-                aid: to,
-                deviceId: devId.value,
-                role: 'peer',
-                defaultKeySource: 'peer_device_prekey',
-            });
-            if (target)
-                targets.push(target);
-        }
-        for (const dev of auditRaw) {
-            const target = await this._v2BuildTargetFromDevice({
-                dev,
-                aid: String(dev.aid ?? ''),
-                deviceId: String(dev.device_id ?? ''),
-                role: 'audit',
-                defaultKeySource: 'peer_device_prekey',
-            });
-            if (target)
-                targets.push(target);
-        }
-        // self-sync：自己其它设备
-        if (this._aid && this._aid !== to) {
-            try {
-                const selfCached = this._v2BootstrapCache.get(this._aid);
-                let selfDevices = [];
-                if (selfCached && (Date.now() - selfCached.cachedAt) < AUNClient.V2_BOOTSTRAP_TTL_MS) {
-                    selfDevices = selfCached.devices;
-                }
-                else {
-                    const selfBs = await this.call('message.v2.bootstrap', {
-                        peer_aid: this._aid,
-                        e2ee_wrap_capabilities: v2WrapCapabilities(),
-                    });
-                    selfDevices = (Array.isArray(selfBs?.peer_devices) ? selfBs.peer_devices : []);
-                    if (selfDevices.length > 0) {
-                        this._v2BootstrapCache.set(this._aid, {
-                            devices: selfDevices,
-                            auditRecipients: [],
-                            cachedAt: Date.now(),
-                        });
-                    }
-                }
-                for (const dev of selfDevices) {
-                    const devId = getV2DeviceId(dev);
-                    if (!devId.present || devId.value === this._deviceId)
-                        continue;
-                    const target = await this._v2BuildTargetFromDevice({
-                        dev,
-                        aid: this._aid,
-                        deviceId: devId.value,
-                        role: 'self_sync',
-                        defaultKeySource: 'peer_device_prekey',
-                    });
-                    if (target)
-                        targets.push(target);
-                }
-            }
-            catch (exc) {
-                this._clientLog.debug(`V2 thought self-sync bootstrap failed (non-fatal): ${String(exc)}`);
-            }
-        }
-        const sender = await session.getSenderIdentity();
-        const sendTargets = applyV2WrapPolicyToTargets(targets, wrapPolicy);
-        const envelope = await encryptP2PMessage(sender, { targets: sendTargets, auditRecipients: [] }, opts.payload, { messageId: opts.messageId, timestamp: opts.timestamp, protectedHeaders: opts.protectedHeaders, context: opts.context });
-        return envelope;
+        return await this._v2E2EE.buildV2P2PEnvelope(opts);
     }
     /**
      * V2 P2P thought.put：使用 V2 多设备 wrap envelope。
@@ -5202,215 +2716,21 @@ export class AUNClient {
      * 与 Python `_put_message_thought_encrypted_v2` 对齐。
      */
     async _putMessageThoughtEncryptedV2(params) {
-        const toAid = String(params.to ?? '').trim();
-        this._validateMessageRecipient(toAid);
-        const payload = isJsonObject(params.payload) ? params.payload : null;
-        if (!toAid) {
-            throw new ValidationError('message.thought.put requires to');
-        }
-        if (payload === null) {
-            throw new ValidationError('message.thought.put payload must be an object when encrypt=true');
-        }
-        const thoughtId = String(params.thought_id ?? '') || `mt-${_uuidV4()}`;
-        const timestamp = Number(params.timestamp ?? Date.now());
-        const attempt = async (useCache) => {
-            const envelopeContext = (params.context && typeof params.context === 'object' && !Array.isArray(params.context))
-                ? params.context : undefined;
-            const envelope = await this._buildV2P2PEnvelope({
-                to: toAid,
-                payload,
-                messageId: thoughtId,
-                timestamp,
-                useCache,
-                context: envelopeContext,
-            });
-            const sendParams = {
-                to: toAid,
-                payload: envelope,
-                encrypted: true,
-                thought_id: thoughtId,
-                timestamp,
-            };
-            if ('context' in params)
-                sendParams.context = params.context;
-            await this._signClientOperation('message.thought.put', sendParams);
-            return this._transport.call('message.thought.put', sendParams);
-        };
-        try {
-            return await attempt(true);
-        }
-        catch (exc) {
-            const excCode = exc?.code;
-            if (AUNClient.V2_RETRYABLE_CODES.has(excCode)) {
-                this._clientLog.debug(`V2 P2P thought put speculative rejected (code=${excCode}), refreshing bootstrap`);
-                this._v2BootstrapCache.delete(toAid);
-                return attempt(false);
-            }
-            throw exc;
-        }
+        return await this._v2E2EE.putMessageThoughtEncryptedV2(params);
     }
     /**
      * V2 Group 多设备 wrap envelope 构造（不发送）。
      * 与 Python `_build_v2_group_envelope` 对齐。
      */
     async _buildV2GroupEnvelope(opts) {
-        if (!this._v2Session) {
-            throw new StateError('V2 session not initialized');
-        }
-        const session = this._v2Session;
-        const groupId = normalizeGroupId(opts.groupId) || String(opts.groupId ?? '').trim();
-        if (!groupId)
-            throw new ValidationError("group.send requires 'group_id'");
-        const useCache = opts.useCache !== false;
-        const cacheKey = `group:${groupId}`;
-        let allDevices = [];
-        let epoch = 0;
-        let stateCommitment = { state_version: 0, state_hash: '', state_chain: '' };
-        let auditRecipientsRaw = [];
-        let wrapPolicy;
-        const cached = useCache ? this._v2BootstrapCache.get(cacheKey) : undefined;
-        if (cached && (Date.now() - cached.cachedAt) < AUNClient.V2_BOOTSTRAP_TTL_MS) {
-            allDevices = cached.devices;
-            epoch = cached.epoch ?? 0;
-            stateCommitment = cached.stateCommitment ?? { state_version: 0, state_hash: '', state_chain: '' };
-            auditRecipientsRaw = cached.auditRecipients;
-            wrapPolicy = cached.wrapPolicy;
-        }
-        else {
-            const bs = await this.call('group.v2.bootstrap', {
-                group_id: groupId,
-                e2ee_wrap_capabilities: v2WrapCapabilities(),
-            });
-            allDevices = (Array.isArray(bs?.devices) ? bs.devices : []);
-            epoch = Number(bs?.epoch ?? 0);
-            auditRecipientsRaw = (Array.isArray(bs?.audit_recipients) ? bs.audit_recipients : []);
-            wrapPolicy = normalizeV2WrapPolicy(bs?.e2ee_wrap_policy);
-            await this._v2CheckFork(groupId, String(bs?.state_chain ?? ''));
-            await this._v2VerifyStateSignature(groupId, bs);
-            await this._publishV2GroupSecurityLevel(groupId, bs);
-            stateCommitment = {
-                state_version: Number(bs?.state_version ?? 0) || 0,
-                state_hash: String(bs?.state_hash_signed ?? bs?.state_hash ?? ''),
-                state_chain: String(bs?.state_chain ?? ''),
-            };
-            if (allDevices.length > 0) {
-                this._v2BootstrapCache.set(cacheKey, {
-                    devices: allDevices,
-                    auditRecipients: auditRecipientsRaw,
-                    cachedAt: Date.now(),
-                    epoch,
-                    stateCommitment: stateCommitment,
-                    wrapPolicy,
-                });
-            }
-            // lazy sync 触发：发现 pending members 时异步发起提案
-            const pendingAdds = Array.isArray(bs?.pending_adds) ? bs.pending_adds : [];
-            if (pendingAdds.length > 0 && this._v2Session) {
-                this._v2MaybeTriggerAutoPropose(groupId);
-            }
-        }
-        if (allDevices.length === 0) {
-            throw new E2EEError(`V2 group bootstrap: no devices for ${groupId}`);
-        }
-        const targets = [];
-        for (const dev of allDevices) {
-            const devAid = String(dev.aid ?? '');
-            const devId = getV2DeviceId(dev);
-            if (devAid === this._aid && devId.present && devId.value === this._deviceId)
-                continue;
-            const role = devAid === this._aid ? 'self_sync' : 'member';
-            const target = await this._v2BuildTargetFromDevice({
-                dev,
-                aid: devAid,
-                deviceId: devId.value,
-                role,
-                defaultKeySource: 'peer_device_prekey',
-            });
-            if (target)
-                targets.push(target);
-        }
-        for (const dev of auditRecipientsRaw) {
-            const target = await this._v2BuildTargetFromDevice({
-                dev,
-                aid: String(dev.aid ?? ''),
-                deviceId: String(dev.device_id ?? ''),
-                role: 'audit',
-                defaultKeySource: 'peer_device_prekey',
-            });
-            if (target)
-                targets.push(target);
-        }
-        if (targets.length === 0) {
-            throw new E2EEError(`V2 group: no target devices for ${groupId}`);
-        }
-        const sender = await session.getSenderIdentity();
-        const sendTargets = applyV2WrapPolicyToTargets(targets, wrapPolicy);
-        const envelope = await encryptGroupMessage(sender, groupId, epoch, sendTargets, opts.payload, { messageId: opts.messageId, timestamp: opts.timestamp, protectedHeaders: opts.protectedHeaders, context: opts.context }, stateCommitment);
-        return envelope;
-    }
-    async _publishV2GroupSecurityLevel(groupId, bootstrap) {
-        const level = String(bootstrap.e2ee_security_level ?? '').trim() || 'end_to_end';
-        const previous = this._v2GroupSecurityLevels.get(groupId);
-        if (previous === level)
-            return;
-        this._v2GroupSecurityLevels.set(groupId, level);
-        await this._dispatcher.publish('group.v2.security_level', {
-            group_id: groupId,
-            level,
-            warning: String(bootstrap.e2ee_security_warning ?? ''),
-            previous_level: previous ?? null,
-        });
+        return await this._v2E2EE.buildV2GroupEnvelope(opts);
     }
     /**
      * V2 Group thought.put：多设备 wrap envelope。
      * 与 Python `_put_group_thought_encrypted_v2` 对齐。
      */
     async _putGroupThoughtEncryptedV2(params) {
-        const groupId = String(params.group_id ?? '').trim();
-        const payload = isJsonObject(params.payload) ? params.payload : null;
-        if (!groupId) {
-            throw new ValidationError('group.thought.put requires group_id');
-        }
-        if (payload === null) {
-            throw new ValidationError('group.thought.put payload must be an object when encrypt=true');
-        }
-        const thoughtId = String(params.thought_id ?? '') || `gt-${_uuidV4()}`;
-        const timestamp = Number(params.timestamp ?? Date.now());
-        const attempt = async (useCache) => {
-            const envelopeContext = (params.context && typeof params.context === 'object' && !Array.isArray(params.context))
-                ? params.context : undefined;
-            const envelope = await this._buildV2GroupEnvelope({
-                groupId,
-                payload,
-                messageId: thoughtId,
-                timestamp,
-                useCache,
-                context: envelopeContext,
-            });
-            const sendParams = {
-                group_id: groupId,
-                payload: envelope,
-                encrypted: true,
-                thought_id: thoughtId,
-                timestamp,
-            };
-            if ('context' in params)
-                sendParams.context = params.context;
-            await this._signClientOperation('group.thought.put', sendParams);
-            return this._transport.call('group.thought.put', sendParams);
-        };
-        try {
-            return await attempt(true);
-        }
-        catch (exc) {
-            const excCode = exc?.code;
-            if (AUNClient.V2_RETRYABLE_CODES.has(excCode)) {
-                this._clientLog.debug(`V2 group thought put speculative rejected (code=${excCode}), refreshing bootstrap`);
-                this._v2BootstrapCache.delete(`group:${groupId}`);
-                return attempt(false);
-            }
-            throw exc;
-        }
+        return await this._v2E2EE.putGroupThoughtEncryptedV2(params);
     }
     /**
      * 解密一个 V2 thought envelope（P2P 或 Group），返回 payload dict。
@@ -5418,656 +2738,60 @@ export class AUNClient {
      * 与 Python `_decrypt_v2_envelope_for_thought` 对齐。
      */
     async _decryptV2EnvelopeForThought(opts) {
-        const session = this._v2Session;
-        if (!session || !opts.envelope)
-            return null;
-        // 找到本设备所引用的 spk_id 和 key_source：根据 envelope.recipients 中 [aid, device_id, ..., spk_id]
-        let spkId = '';
-        let recipientKeySource = '';
-        const recipients = opts.envelope.recipients;
-        if (Array.isArray(recipients)) {
-            for (const row of recipients) {
-                if (Array.isArray(row) && row.length >= 6) {
-                    if (row[0] === this._aid && (row[1] === this._deviceId || row[1] === '')) {
-                        spkId = String(row[5] ?? '');
-                        recipientKeySource = row.length > 3 ? String(row[3] ?? '') : '';
-                        break;
-                    }
-                }
-            }
-        }
-        const aad = opts.envelope.aad ?? {};
-        const groupIdForKeys = String(aad.group_id ?? opts.envelope.group_id ?? '').trim();
-        let ikPriv;
-        let spkPriv;
-        // group_id 只表示群上下文；group lookup 内部按 group SPK -> P2P device SPK -> IK fallback。
-        try {
-            if (groupIdForKeys) {
-                const keys = await session.getGroupDecryptKeys(groupIdForKeys, spkId);
-                ikPriv = keys.ikPriv;
-                spkPriv = keys.spkPriv;
-            }
-            else {
-                const keys = await session.getDecryptKeys(spkId);
-                ikPriv = keys.ikPriv;
-                spkPriv = keys.spkPriv;
-            }
-        }
-        catch (exc) {
-            this._clientLog.warn(`V2 thought decrypt: SPK lookup failed from=${opts.fromAid}, group=${groupIdForKeys || '<p2p>'}, spk_id=${spkId || '<empty>'}: ${exc}`);
-            return null;
-        }
-        const fromAid = String(opts.fromAid || aad.from || '').trim();
-        const senderDeviceId = String(aad.from_device ?? '');
-        const senderPubDer = await this._getV2SenderPubDer(fromAid, senderDeviceId);
-        if (!senderPubDer) {
-            this._clientLog.warn(`V2 thought decrypt: no sender IK for ${fromAid} device=${senderDeviceId}`);
-            this._scheduleV2SenderIKFetch(fromAid, senderDeviceId, groupIdForKeys);
-            return null;
-        }
-        try {
-            const plaintext = await decryptMessage(opts.envelope, this._aid ?? '', this._deviceId, ikPriv, spkPriv, senderPubDer);
-            // 消费触发 SPK 轮换（与 _decryptV2Message 对齐）
-            if (plaintext != null) {
-                if (groupIdForKeys && recipientKeySource === 'group_device_prekey' && session.isLastUploadedGroupSPK(groupIdForKeys, spkId)) {
-                    const callFn = async (method, params) => this.call(method, params);
-                    session.rotateGroupSPK(groupIdForKeys, callFn).catch(exc => {
-                        this._clientLog.debug(`V2 thought group SPK rotation failed (non-fatal): group=${groupIdForKeys} err=${exc}`);
-                    });
-                }
-                else if (groupIdForKeys && recipientKeySource === 'peer_device_prekey') {
-                    const callFn = async (method, params) => this.call(method, params);
-                    session.ensureGroupRegistered(groupIdForKeys, callFn).catch(exc => {
-                        this._clientLog.debug(`V2 thought group SPK registration after peer fallback failed (non-fatal): group=${groupIdForKeys} err=${exc}`);
-                    });
-                }
-            }
-            return plaintext;
-        }
-        catch (exc) {
-            this._clientLog.warn(`V2 thought decrypt failed from=${fromAid}: ${String(exc)}`);
-            return null;
-        }
+        return await this._v2E2EE.decryptV2EnvelopeForThought(opts);
     }
     // ── V2 State 验签 / Fork 检测 / Auto-propose（Phase 3b.3 + 3b.4）──────
+    async _publishV2GroupSecurityLevel(groupId, bootstrap) {
+        return this._groupState.publishV2GroupSecurityLevel(groupId, bootstrap);
+    }
     /**
      * 验证 owner/admin 对 state 的 ECDSA 签名（防服务端篡改 bootstrap 字段）。
      * 与 Python SDK 对齐：证书获取或验签失败时拒绝信任 bootstrap。
      */
     async _v2VerifyStateSignature(groupId, bootstrap) {
-        if (!bootstrap)
-            return;
-        const stateSignature = String(bootstrap.state_signature ?? '');
-        const actorAid = String(bootstrap.state_actor_aid ?? '');
-        const stateHashSigned = String(bootstrap.state_hash_signed ?? '');
-        const membershipSnapshot = String(bootstrap.state_membership_snapshot ?? '');
-        const stateVersion = Number(bootstrap.state_version ?? 0) || 0;
-        if (stateVersion === 0 || !stateSignature || !actorAid)
-            return;
-        try {
-            // 重构签名 payload（与服务端 propose_state 中的格式一致）
-            const signPayloadObj = {
-                group_id: groupId,
-                membership_snapshot: membershipSnapshot,
-                state_hash: stateHashSigned,
-                state_version: stateVersion,
-            };
-            const signPayload = stableStringify(signPayloadObj);
-            const signPayloadBytes = new TextEncoder().encode(signPayload);
-            const sigBytes = base64ToUint8(stateSignature);
-            // 验签缓存检查
-            const cacheData = _v2LengthPrefixedBytes(new TextEncoder().encode(actorAid), signPayloadBytes, sigBytes);
-            const cacheHashBuf = await crypto.subtle.digest('SHA-256', cacheData.slice().buffer);
-            const cacheHashArr = new Uint8Array(cacheHashBuf);
-            let cacheKey = '';
-            for (let i = 0; i < cacheHashArr.length; i++)
-                cacheKey += cacheHashArr[i].toString(16).padStart(2, '0');
-            const now = Date.now();
-            const cachedExp = this._v2SigCache.get(cacheKey);
-            if (cachedExp !== undefined && cachedExp > now) {
-                this._clientLog.debug(`V2 state signature cache hit: group=${groupId} sv=${stateVersion}`);
-            }
-            else {
-                // 获取 actor 证书（通过 HTTP PKI 端点，不走 ca.get_cert RPC）
-                const certPem = await this._fetchPeerCert(actorAid);
-                if (!certPem) {
-                    this._clientLog.warn(`V2 state verify: no cert for actor=${actorAid}, group=${groupId}`);
-                    throw new E2EEError(`V2 state verify: cannot fetch actor cert for ${actorAid}`);
-                }
-                const pubKey = await importCertPublicKeyEcdsa(certPem);
-                const ok = await ecdsaVerifyDer(pubKey, sigBytes, signPayloadBytes);
-                if (!ok) {
-                    this._clientLog.warn(`V2 state signature verification FAILED: group=${groupId} sv=${stateVersion} actor=${actorAid}`);
-                    throw new E2EEError('V2 state signature verification failed');
-                }
-                // 写入缓存
-                this._v2SigCache.set(cacheKey, now + AUNClient._V2_SIG_CACHE_TTL);
-                if (this._v2SigCache.size > AUNClient._V2_SIG_CACHE_MAX) {
-                    const stale = [];
-                    for (const [k, exp] of this._v2SigCache) {
-                        if (exp <= now)
-                            stale.push(k);
-                    }
-                    for (const k of stale)
-                        this._v2SigCache.delete(k);
-                    if (this._v2SigCache.size > AUNClient._V2_SIG_CACHE_MAX) {
-                        // 淘汰最旧的 1/4
-                        const entries = [...this._v2SigCache.entries()].sort((a, b) => a[1] - b[1]);
-                        const evictCount = Math.floor(AUNClient._V2_SIG_CACHE_MAX / 4);
-                        for (let i = 0; i < evictCount && i < entries.length; i++) {
-                            this._v2SigCache.delete(entries[i][0]);
-                        }
-                    }
-                }
-                this._clientLog.debug(`V2 state signature verified: group=${groupId} sv=${stateVersion} actor=${actorAid}`);
-            }
-            // 验证 member_aids 在签名快照中（best-effort）
-            try {
-                if (membershipSnapshot.startsWith('[')) {
-                    const signedSnapshot = JSON.parse(membershipSnapshot);
-                    const serverMembers = new Set(Array.isArray(bootstrap.member_aids) ? bootstrap.member_aids : []);
-                    const signedMembers = new Set(signedSnapshot);
-                    const extra = [];
-                    for (const m of serverMembers) {
-                        if (!signedMembers.has(m))
-                            extra.push(m);
-                    }
-                    if (extra.length > 0) {
-                        let mode = '';
-                        try {
-                            const reqResp = await this.call('group.get_join_requirements', { group_id: groupId });
-                            mode = isJsonObject(reqResp)
-                                ? String(reqResp.mode ?? '').trim()
-                                : '';
-                        }
-                        catch {
-                            mode = '';
-                        }
-                        if (mode !== 'open' && mode !== 'invite_code' && mode !== 'invite_only') {
-                            this._clientLog.warn(`V2 state tamper detected: group=${groupId} pending_extra=${extra.sort().join(',')} mode=${mode}`);
-                            await this._dispatcher.publish('group.v2.state_tampered', {
-                                group_id: groupId,
-                                pending_extra: extra.sort(),
-                                mode,
-                            });
-                        }
-                    }
-                }
-            }
-            catch {
-                // snapshot 解析失败不阻断
-            }
-        }
-        catch (exc) {
-            if (exc instanceof E2EEError)
-                throw exc;
-            this._clientLog.warn(`V2 state signature verification failed: group=${groupId} err=${formatCaughtError(exc)}`);
-            throw new E2EEError(`V2 state signature verification failed: ${String(formatCaughtError(exc))}`);
-        }
+        return this._groupState.verifyStateSignature(groupId, bootstrap);
     }
     /**
      * 分叉检测：比对服务端 state_chain 与本地存储。
      */
     async _v2CheckFork(groupId, serverChain) {
-        if (!serverChain)
-            return;
-        try {
-            const local = this._v2StateChains.get(groupId);
-            if (local === undefined) {
-                this._v2StateChains.set(groupId, [0, serverChain]);
-                return;
-            }
-            const [localSv, localChain] = local;
-            if (localChain === serverChain)
-                return;
-            // 不一致：尝试通过 get_state 判断是正常推进还是分叉
-            try {
-                const stateResp = await this.call('group.get_state', { group_id: groupId });
-                if (stateResp) {
-                    const serverSv = Number(stateResp.state_version ?? 0);
-                    if (serverSv > localSv) {
-                        // 正常推进
-                        this._v2StateChains.set(groupId, [serverSv, serverChain]);
-                        return;
-                    }
-                    if (serverSv < localSv) {
-                        this._clientLog.warn(`V2 state chain rollback detected: group=${groupId} server_sv=${serverSv} local_sv=${localSv}`);
-                    }
-                }
-            }
-            catch {
-                // get_state 失败不阻断
-            }
-            // 告警：分叉
-            this._clientLog.warn(`V2 state chain fork detected: group=${groupId} local_chain=${localChain.slice(0, 16)}... server_chain=${serverChain.slice(0, 16)}...`);
-            this._dispatcher.publish('group.v2.fork_detected', {
-                group_id: groupId,
-                local_chain: localChain,
-                server_chain: serverChain,
-            });
-        }
-        catch (exc) {
-            this._clientLog.debug(`V2 fork check failed (non-fatal): ${exc}`);
-        }
+        return this._groupState.checkFork(groupId, serverChain);
     }
     _v2MaybeTriggerAutoPropose(groupId) {
-        const now = Date.now();
-        const last = this._v2LazyProposeTriggered.get(groupId) ?? 0;
-        if (now - last < 10000)
-            return;
-        this._v2LazyProposeTriggered.set(groupId, now);
-        this._safeAsync(this._v2AutoProposeState(groupId, { leaderDelay: true }));
+        this._groupState.maybeTriggerAutoPropose(groupId);
     }
     /**
      * 成员变更后自动 propose state（仅 owner/admin 执行）。
      */
     async _v2AutoProposeState(groupId, options) {
-        const normalizedGroupId = normalizeGroupId(groupId) || String(groupId ?? '').trim();
-        if (!normalizedGroupId)
-            return;
-        if (options?.leaderDelay) {
-            const shouldContinue = await this._v2AutoProposeLeaderDelay(normalizedGroupId);
-            if (!shouldContinue)
-                return;
-        }
-        const inflight = this._v2AutoProposeInflight.get(normalizedGroupId);
-        if (inflight) {
-            this._v2AutoProposePending.add(normalizedGroupId);
-            await inflight;
-            return;
-        }
-        let resolveTask;
-        let rejectTask;
-        const task = new Promise((resolve, reject) => {
-            resolveTask = resolve;
-            rejectTask = reject;
-        });
-        this._v2AutoProposeInflight.set(normalizedGroupId, task);
-        void (async () => {
-            try {
-                do {
-                    this._v2AutoProposePending.delete(normalizedGroupId);
-                    await this._doV2AutoProposeState(normalizedGroupId);
-                } while (this._v2AutoProposePending.delete(normalizedGroupId));
-                resolveTask();
-            }
-            catch (exc) {
-                rejectTask(exc);
-            }
-            finally {
-                if (this._v2AutoProposeInflight.get(normalizedGroupId) === task) {
-                    this._v2AutoProposeInflight.delete(normalizedGroupId);
-                }
-                this._v2AutoProposePending.delete(normalizedGroupId);
-            }
-        })();
-        try {
-            await task;
-        }
-        finally {
-            if (this._v2AutoProposeInflight.get(normalizedGroupId) === task) {
-                this._v2AutoProposeInflight.delete(normalizedGroupId);
-            }
-            this._v2AutoProposePending.delete(normalizedGroupId);
-        }
+        return this._groupState.autoProposeState(groupId, options);
     }
     async _v2LeaderDelayMs(input) {
-        const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(input)));
-        const first32 = new DataView(digest.buffer, digest.byteOffset, digest.byteLength)
-            .getUint32(0, false);
-        return 2000 + (first32 % 4000);
+        return this._groupState.leaderDelayMs(input);
     }
     async _v2AutoProposeLeaderDelay(groupId) {
-        try {
-            const membersResp = await this.call('group.get_online_members', { group_id: groupId });
-            const members = (Array.isArray(membersResp?.members) ? membersResp.members
-                : Array.isArray(membersResp?.items) ? membersResp.items
-                    : Array.isArray(membersResp?.online_members) ? membersResp.online_members : []);
-            const myAid = this._aid ?? '';
-            let myRole = '';
-            const onlineAdminAids = new Set();
-            for (const member of members) {
-                const aid = String(member.aid ?? '').trim();
-                const role = String(member.role ?? '').trim();
-                if (!aid)
-                    continue;
-                if ('online' in member && !Boolean(member.online))
-                    continue;
-                if (role === 'owner' || role === 'admin')
-                    onlineAdminAids.add(aid);
-                if (aid === myAid)
-                    myRole = role;
-            }
-            if (myRole !== 'owner' && myRole !== 'admin')
-                return false;
-            const bootstrapResp = await this.call('group.v2.bootstrap', {
-                group_id: groupId,
-                e2ee_wrap_capabilities: v2WrapCapabilities(),
-            });
-            const devices = (Array.isArray(bootstrapResp?.devices) ? bootstrapResp.devices : []);
-            const candidates = [];
-            for (const dev of devices) {
-                const aid = String(dev.aid ?? '').trim();
-                const hasDeviceId = 'device_id' in dev;
-                const deviceId = String(dev.device_id ?? '').trim();
-                if (aid && hasDeviceId && onlineAdminAids.has(aid)) {
-                    candidates.push(`${aid}\x1f${deviceId}`);
-                }
-            }
-            if (candidates.length === 0) {
-                for (const aid of [...onlineAdminAids].sort())
-                    candidates.push(`${aid}\x1f`);
-            }
-            const myKey = `${myAid}\x1f${this._deviceId ?? ''}`;
-            if (!candidates.includes(myKey))
-                candidates.push(myKey);
-            const leader = [...new Set(candidates)].sort()[0];
-            if (leader === myKey) {
-                this._clientLog.debug(`V2 auto propose leader elected: group=${groupId} leader=${leader}`);
-                return true;
-            }
-            const delayMs = await this._v2LeaderDelayMs(_v2LengthPrefixedTextKey(groupId, myKey));
-            this._clientLog.debug(`V2 auto propose non-leader delay: group=${groupId} leader=${leader} self=${myKey} delay_ms=${delayMs}`);
-            await this._sleep(delayMs);
-            return true;
-        }
-        catch (exc) {
-            this._clientLog.debug(`V2 auto propose leader check failed, fallback immediate: group=${groupId} err=${formatCaughtError(exc)}`);
-            return true;
-        }
-    }
-    async _v2VerifyCommittedStateBase(groupId, stateResp) {
-        const currentSv = Number(stateResp.state_version ?? 0) || 0;
-        if (currentSv <= 0)
-            return true;
-        const currentSh = String(stateResp.state_hash ?? '').trim();
-        const membershipSnapshot = String(stateResp.membership_snapshot ?? '').trim();
-        if (!currentSh || !membershipSnapshot) {
-            this._clientLog.warn(`V2 committed state base incomplete: group=${groupId} sv=${currentSv}`);
-            return false;
-        }
-        try {
-            const parsed = JSON.parse(membershipSnapshot);
-            if (!isJsonObject(parsed)) {
-                this._clientLog.warn(`V2 committed state base snapshot is not object: group=${groupId} sv=${currentSv}`);
-                return false;
-            }
-            const computed = await computeStateCommitment(groupId, currentSv, parsed);
-            if (computed !== currentSh) {
-                this._clientLog.warn(`V2 committed state base hash mismatch: group=${groupId} sv=${currentSv}`);
-                return false;
-            }
-            return true;
-        }
-        catch (exc) {
-            this._clientLog.warn(`V2 committed state base verification failed: group=${groupId} sv=${currentSv} err=${formatCaughtError(exc)}`);
-            return false;
-        }
+        return this._groupState.autoProposeLeaderDelay(groupId);
     }
     async _doV2AutoProposeState(groupId) {
-        try {
-            // 获取当前成员列表 + 角色
-            const membersResp = await this.call('group.get_members', { group_id: groupId });
-            const members = (Array.isArray(membersResp?.members) ? membersResp.members
-                : Array.isArray(membersResp?.items) ? membersResp.items : []);
-            const myAid = this._aid ?? '';
-            let myRole = '';
-            const memberAids = [];
-            const adminAids = [];
-            for (const m of members) {
-                const aid = String(m.aid ?? '').trim();
-                const role = String(m.role ?? '').trim();
-                if (aid) {
-                    memberAids.push(aid);
-                    if (role === 'owner' || role === 'admin')
-                        adminAids.push(aid);
-                }
-                if (aid === myAid)
-                    myRole = role;
-            }
-            if (myRole !== 'owner' && myRole !== 'admin')
-                return;
-            // 前置检查：如果已有 pending proposal，先尝试 confirm 而非重复 propose
-            const proposalResp = await this.call('group.v2.get_proposal', { group_id: groupId });
-            if (proposalResp && typeof proposalResp === 'object') {
-                const pendingProposal = proposalResp.proposal;
-                if (pendingProposal && typeof pendingProposal === 'object' && String(pendingProposal.proposal_id ?? '').trim()) {
-                    const confirmed = await this._v2ConfirmPendingProposal(groupId);
-                    if (confirmed)
-                        return;
-                    const autoConfirmAt = Number(pendingProposal.auto_confirm_at ?? 0) || 0;
-                    const nowMs = Date.now();
-                    if (autoConfirmAt > nowMs) {
-                        const waitMs = Math.min(autoConfirmAt - nowMs + 500, 35000);
-                        this._clientLog.debug(`V2 auto propose: pending proposal exists, waiting ${waitMs}ms group=${groupId}`);
-                        await new Promise((r) => setTimeout(r, waitMs));
-                    }
-                }
-            }
-            // 获取群所有成员的设备列表（V2 bootstrap）
-            const bootstrapResp = await this.call('group.v2.bootstrap', {
-                group_id: groupId,
-                e2ee_wrap_capabilities: v2WrapCapabilities(),
-            });
-            const allDevices = (Array.isArray(bootstrapResp?.devices) ? bootstrapResp.devices : []);
-            const auditRecipients = (Array.isArray(bootstrapResp?.audit_recipients) ? bootstrapResp.audit_recipients : []);
-            const auditAidsList = [...new Set(auditRecipients.map(r => String(r.aid ?? '').trim()).filter(Boolean))].sort();
-            // 按 aid 分组设备
-            const membersWithDevices = {};
-            for (const aid of memberAids)
-                membersWithDevices[aid] = [];
-            for (const dev of allDevices) {
-                const devAid = String(dev.aid ?? '').trim();
-                if (devAid in membersWithDevices) {
-                    membersWithDevices[devAid].push({
-                        device_id: String(dev.device_id ?? ''),
-                        ik_fp: String(dev.ik_fp ?? ''),
-                    });
-                }
-            }
-            const membersPayload = Object.entries(membersWithDevices).map(([aid, devices]) => ({
-                aid,
-                devices,
-            }));
-            const statePayload = {
-                members: membersPayload,
-                audit_aids: auditAidsList,
-                admin_set: { admin_aids: adminAids.sort(), threshold: 1 },
-                join_policy_hash: null,
-                recovery_quorum: null,
-                history_policy: 'recent_7_days',
-                wrap_protocol: '3DH',
-            };
-            // 获取当前 state
-            const stateResp = await this.call('group.get_state', { group_id: groupId });
-            if (!stateResp)
-                return;
-            if (!isJsonObject(stateResp))
-                return;
-            if (!(await this._v2VerifyCommittedStateBase(groupId, stateResp)))
-                return;
-            const currentSv = Number(stateResp.state_version ?? 0);
-            const currentSh = String(stateResp.state_hash ?? '');
-            const keyEpoch = Number(stateResp.key_epoch ?? 0);
-            // 用完整 commitment 算 state_hash
-            const stateHash = await computeStateCommitment(groupId, currentSv + 1, statePayload);
-            // 签名 state proposal
-            const membershipSnapshot = stableStringify(statePayload);
-            const lastMembershipSnapshot = this._v2AutoProposeLastSnapshot.get(groupId);
-            if (lastMembershipSnapshot === membershipSnapshot) {
-                return;
-            }
-            const currentMembershipSnapshot = String(stateResp.membership_snapshot ?? '');
-            if (currentMembershipSnapshot && currentMembershipSnapshot === membershipSnapshot) {
-                this._v2AutoProposeLastSnapshot.set(groupId, membershipSnapshot);
-                return;
-            }
-            let signature = '';
-            const currentAid = this._currentAid;
-            if (currentAid?.privateKeyPem) {
-                try {
-                    const signPayloadObj = {
-                        group_id: groupId,
-                        membership_snapshot: membershipSnapshot,
-                        state_hash: stateHash,
-                        state_version: currentSv + 1,
-                    };
-                    const signPayload = stableStringify(signPayloadObj);
-                    const signPayloadBytes = new TextEncoder().encode(signPayload);
-                    const privKey = await importPrivateKeyEcdsa(currentAid.privateKeyPem);
-                    const sigBytes = await ecdsaSignDer(privKey, signPayloadBytes);
-                    signature = uint8ToBase64(sigBytes);
-                }
-                catch (sigExc) {
-                    this._clientLog.debug(`propose_state signature failed: ${sigExc}`);
-                }
-            }
-            const proposeResult = await this.call('group.v2.propose_state', {
-                group_id: groupId,
-                state_version: currentSv + 1,
-                key_epoch: keyEpoch,
-                state_hash: stateHash,
-                prev_state_hash: currentSh,
-                membership_snapshot: membershipSnapshot,
-                signature,
-                reason: 'membership_changed',
-                auto_confirm_seconds: 30,
-            });
-            this._clientLog.debug(`V2 auto propose_state: group=${groupId} sv=${currentSv + 1}`);
-            const proposalId = isJsonObject(proposeResult) ? String(proposeResult.proposal_id ?? '').trim() : '';
-            if (proposalId) {
-                try {
-                    await this.call('group.v2.confirm_state', { proposal_id: proposalId });
-                    this._v2AutoProposeLastSnapshot.set(groupId, membershipSnapshot);
-                    this._clientLog.debug(`V2 auto confirm_state: group=${groupId} proposal=${proposalId}`);
-                }
-                catch (confirmExc) {
-                    this._clientLog.debug(`V2 auto confirm_state failed (non-fatal): group=${groupId} err=${confirmExc}`);
-                }
-            }
-        }
-        catch (exc) {
-            this._clientLog.debug(`V2 auto propose_state failed (non-fatal): group=${groupId} err=${exc}`);
-        }
-    }
-    async _v2VerifyPendingProposalAgainstBase(groupId, proposal, stateResp) {
-        if (!(await this._v2VerifyCommittedStateBase(groupId, stateResp)))
-            return false;
-        const currentSv = Number(stateResp.state_version ?? 0) || 0;
-        const currentSh = String(stateResp.state_hash ?? '').trim();
-        const proposalSv = Number(proposal.state_version ?? 0) || 0;
-        const proposalHash = String(proposal.state_hash ?? '').trim();
-        const proposalPrev = String(proposal.prev_state_hash ?? '').trim();
-        const membershipSnapshot = String(proposal.membership_snapshot ?? '').trim();
-        if (proposalSv !== currentSv + 1 || proposalPrev !== currentSh || !proposalHash || !membershipSnapshot) {
-            this._clientLog.warn(`V2 pending proposal base mismatch: group=${groupId} current_sv=${currentSv} proposal_sv=${proposalSv}`);
-            return false;
-        }
-        try {
-            const parsed = JSON.parse(membershipSnapshot);
-            if (!isJsonObject(parsed))
-                return false;
-            const computed = await computeStateCommitment(groupId, proposalSv, parsed);
-            if (computed !== proposalHash) {
-                this._clientLog.warn(`V2 pending proposal hash mismatch: group=${groupId} proposal_sv=${proposalSv}`);
-                return false;
-            }
-            return true;
-        }
-        catch (exc) {
-            this._clientLog.warn(`V2 pending proposal verification failed: group=${groupId} err=${formatCaughtError(exc)}`);
-            return false;
-        }
+        return this._groupState.doAutoProposeState(groupId);
     }
     async _v2ConfirmPendingProposal(groupId) {
-        const proposalResp = await this.call('group.v2.get_proposal', { group_id: groupId });
-        const proposal = isJsonObject(proposalResp?.proposal) ? proposalResp.proposal : null;
-        const proposalId = proposal ? String(proposal.proposal_id ?? '').trim() : '';
-        if (!proposal || !proposalId)
-            return false;
-        const stateResp = await this.call('group.get_state', { group_id: groupId });
-        if (!isJsonObject(stateResp))
-            return false;
-        const currentSv = Number(stateResp.state_version ?? 0) || 0;
-        const proposalSv = Number(proposal.state_version ?? 0) || 0;
-        if (proposalSv <= currentSv) {
-            this._clientLog.debug(`V2 pending proposal already settled: group=${groupId} current_sv=${currentSv} proposal_sv=${proposalSv}`);
-            return false;
-        }
-        if (!(await this._v2VerifyPendingProposalAgainstBase(groupId, proposal, stateResp)))
-            return false;
-        await this.call('group.v2.confirm_state', { proposal_id: proposalId });
-        this._clientLog.info(`V2 confirmed pending proposal: group=${groupId} proposal=${proposalId}`);
-        return true;
+        return this._groupState.confirmPendingProposal(groupId);
     }
     /**
      * Owner 上线时自动检查并签名确认 pending state proposals。
      */
     async _v2AutoConfirmPendingProposals() {
-        try {
-            const myAid = this._aid ?? '';
-            if (!myAid)
-                return;
-            const groupsResp = await this.call('group.list_my', {});
-            const groups = (Array.isArray(groupsResp?.groups) ? groupsResp.groups
-                : Array.isArray(groupsResp?.items) ? groupsResp.items : []);
-            for (const g of groups) {
-                const gid = String(g.group_id ?? '').trim();
-                const myRole = String(g.role ?? g.my_role ?? '').trim();
-                if (!gid || (myRole !== 'owner' && myRole !== 'admin'))
-                    continue;
-                try {
-                    const confirmed = await this._v2ConfirmPendingProposal(gid);
-                    if (!confirmed) {
-                        await this._v2AutoProposeState(gid);
-                    }
-                }
-                catch (exc) {
-                    this._clientLog.debug(`V2 auto confirm/propose failed (non-fatal): group=${gid} err=${exc}`);
-                }
-            }
-        }
-        catch (exc) {
-            this._clientLog.debug(`V2 auto confirm pending proposals failed (non-fatal): ${exc}`);
-        }
+        return this._groupState.autoConfirmPendingProposals();
     }
     async _onV2StateProposed(data) {
-        if (!isJsonObject(data) || !this._v2Session)
-            return;
-        const groupId = String(data.group_id ?? '').trim();
-        if (!groupId)
-            return;
-        await this._dispatcher.publish('group.v2.state_proposed', data);
-        try {
-            await this._v2ConfirmPendingProposal(groupId);
-        }
-        catch (exc) {
-            this._clientLog.debug(`V2 state_proposed handling failed (non-fatal): group=${groupId} err=${formatCaughtError(exc)}`);
-        }
+        return this._groupState.onV2StateProposed(data);
     }
     async _onV2StateRetryNeeded(data) {
-        if (!isJsonObject(data) || !this._v2Session)
-            return;
-        const groupId = String(data.group_id ?? '').trim();
-        if (!groupId)
-            return;
-        await this._dispatcher.publish('group.v2.state_retry_needed', data);
-        try {
-            await this._v2AutoProposeState(groupId, { leaderDelay: true });
-        }
-        catch (exc) {
-            this._clientLog.debug(`V2 state_retry_needed handling failed (non-fatal): group=${groupId} err=${formatCaughtError(exc)}`);
-        }
+        return this._groupState.onV2StateRetryNeeded(data);
     }
     async _onV2StateConfirmed(data) {
-        if (!isJsonObject(data))
-            return;
-        const groupId = String(data.group_id ?? '').trim();
-        if (groupId) {
-            this._v2BootstrapCache.delete(`group:${groupId}`);
-            this._v2AutoProposeLastSnapshot.delete(groupId);
-        }
-        await this._dispatcher.publish('group.v2.state_confirmed', data);
+        return this._groupState.onV2StateConfirmed(data);
     }
     /**
      * 处理 V2 push 通知：自动 pull + decrypt + emit。
@@ -6075,116 +2799,13 @@ export class AUNClient {
     _v2PullInflight = false;
     _v2PullPending = false;
     async _onV2PushNotification(data) {
-        if (!this._v2Session)
-            return;
-        // 提取 push 通知中的元数据
-        const pushSeq = isJsonObject(data) ? Number(data.seq ?? 0) || 0 : 0;
-        const pushFrom = isJsonObject(data) ? String(data.from_aid ?? '') : '';
-        const pushMsgId = isJsonObject(data) ? String(data.message_id ?? '') : '';
-        const envelopeJson = isJsonObject(data) ? data.envelope_json : undefined;
-        const hasPayload = !!envelopeJson;
-        const ns = this._aid ? `p2p:${this._aid}` : '';
-        let contigBefore = ns ? this._seqTracker.getContiguousSeq(ns) : 0;
-        this._clientLog.debug(`_onV2PushNotification: push_seq=${pushSeq || 'null'} push_from=${pushFrom} push_msg_id=${pushMsgId} has_payload=${hasPayload} contiguous_seq=${contigBefore}`);
-        // ── Push 修上界：只更新 maxSeenSeq，不动 contiguousSeq ──
-        if (pushSeq > 0 && ns) {
-            this._seqTracker.updateMaxSeen(ns, pushSeq);
-            if (contigBefore === pushSeq) {
-                this._clientLog.debug(`_onV2PushNotification: push seq=${pushSeq} already covered by contiguous_seq=${contigBefore}, ignore duplicate push`);
-                return;
-            }
-            contigBefore = this._repairPushContiguousBound(ns, pushSeq, hasPayload, '_raw.peer.v2.message_received');
-        }
-        // ── 带 payload 的 push：尝试就地解密 ──
-        if (hasPayload && pushSeq > 0 && ns) {
-            try {
-                const decrypted = await this._decryptV2Message(data);
-                if (decrypted) {
-                    // 解密成功：把 pushSeq 加入 receivedSeqs，让 _tryAdvance 自然推进
-                    const needPull = this._seqTracker.onMessageSeq(ns, pushSeq);
-                    const published = await this._publishOrderedMessage('message.received', ns, pushSeq, decrypted);
-                    const newContig = this._seqTracker.getContiguousSeq(ns);
-                    if (newContig !== contigBefore) {
-                        this._saveSeqTrackerState();
-                    }
-                    if (newContig > 0 && newContig !== contigBefore) {
-                        const maxSeen = this._seqTracker.getMaxSeenSeq(ns);
-                        const ackSeq = maxSeen > 0 ? Math.min(newContig, maxSeen) : newContig;
-                        this._callRawV2Rpc('message.v2.ack', { up_to_seq: ackSeq })
-                            .catch(e => this._clientLog.debug(`V2 P2P push-ack failed: ${e}`));
-                    }
-                    this._clientLog.debug(`_onV2PushNotification: push 带 payload 解密成功, contiguous_seq=${contigBefore}->${newContig} push_seq=${pushSeq}`);
-                    if (!needPull && (published || newContig >= pushSeq || pushSeq <= contigBefore)) {
-                        return;
-                    }
-                    this._clientLog.debug(`_onV2PushNotification: payload push seq=${pushSeq} 因空洞挂起，继续 pull 补齐 after_seq=${newContig}`);
-                }
-            }
-            catch (exc) {
-                this._clientLog.debug(`_onV2PushNotification: push payload 解密失败, fallback to pull: ${exc}`);
-            }
-        }
-        // ── 不带 payload 或解密失败：触发 pull ──
-        // 关键：push 通知只表示"服务端有 seq=pushSeq 的新消息"，
-        // 此时消息内容尚未到达本地，绝不能调用 onMessageSeq() 推进 contiguousSeq
-        // （那会让随后的 pull 用 after_seq=pushSeq，跳过这条消息本身导致拉空）。
-        // 正确做法：保持 contiguousSeq 不变，用它作为 pull 的 after_seq；
-        // pull 成功 + 解密成功后再由 pull 路径推进 contiguousSeq。
-        if (pushSeq > 0 && ns) {
-            // 纯通知：不更新 contiguousSeq，由 pull 结果驱动推进
-            this._clientLog.debug(`_onV2PushNotification: 纯通知 push_seq=${pushSeq} > contiguous_seq=${contigBefore}, 触发 pull(after_seq=${contigBefore})`);
-        }
-        // only one in flight + drain pending
-        if (this._v2PullInflight) {
-            this._v2PullPending = true;
-            return;
-        }
-        this._v2PullInflight = true;
-        const dedupKey = `p2p_pull:${ns}`;
-        this._gapFillDone.add(dedupKey);
-        try {
-            do {
-                this._v2PullPending = false;
-                await this._pullV2();
-                const newContig = ns ? this._seqTracker.getContiguousSeq(ns) : -1;
-                this._clientLog.debug(`_onV2PushNotification pull done: contiguous_seq=${contigBefore}->${newContig} (push_seq=${pushSeq || 'null'})`);
-            } while (this._v2PullPending);
-        }
-        catch (exc) {
-            const newContig = ns ? this._seqTracker.getContiguousSeq(ns) : -1;
-            this._clientLog.warn(`V2 push auto-pull failed: contiguous_seq=${contigBefore}->${newContig} err=${exc}`);
-        }
-        finally {
-            this._v2PullInflight = false;
-            this._gapFillDone.delete(dedupKey);
-        }
+        return this._delivery.onV2PushNotification(data);
     }
     /**
      * 处理 V2 epoch 轮换事件：清除 bootstrap 缓存 + 触发 SPK rotation。
      */
     async _onV2EpochRotated(data) {
-        if (!data || typeof data !== 'object')
-            return;
-        const groupId = String(data.group_id ?? '').trim();
-        if (!groupId)
-            return;
-        const newEpoch = data.epoch ?? 0;
-        this._clientLog.debug(`_onV2EpochRotated: group=${groupId} epoch=${newEpoch}`);
-        // 清除 bootstrap 缓存
-        this._v2BootstrapCache.delete(`group:${groupId}`);
-        // 触发 SPK rotation
-        if (this._v2Session) {
-            try {
-                const callFn = async (method, params) => {
-                    return this.call(method, params);
-                };
-                await this._v2Session.rotateSPK(callFn);
-                this._clientLog.info(`SPK rotated after epoch change: group=${groupId} epoch=${newEpoch}`);
-            }
-            catch (exc) {
-                this._clientLog.debug(`SPK rotation after epoch change failed (non-fatal): ${exc}`);
-            }
-        }
+        return this._v2E2EE.handleV2EpochRotated(data);
     }
     /** 安全执行异步操作（不阻塞调用方，错误打 warning 便于排障） */
     _safeAsync(promise) {
@@ -6192,65 +2813,24 @@ export class AUNClient {
             this._clientLog.warn(`background task exception:${String(exc)}`);
         });
     }
+    _explicitGroupCursorParams(params) {
+        const value = params._group_cursor_params;
+        if (!isJsonObject(value))
+            return {};
+        return { ...value };
+    }
+    _groupCursorTargetsCurrentInstance(params) {
+        const deviceId = String(params.device_id ?? '').trim();
+        const slotId = String(params.slot_id ?? '').trim();
+        return (!deviceId || deviceId === (this._deviceId ?? ''))
+            && (!slotId || slotId === (this._slotId ?? ''));
+    }
     // ── Pull Gate（序列化同一 key 的并发 pull）──────────────────
     _pullGateKeyForCall(method, params) {
-        if (method === 'message.pull' || method === 'message.v2.pull') {
-            return this._aid ? `p2p:${this._aid}` : '';
-        }
-        if (method === 'group.pull' || method === 'group.v2.pull') {
-            const gid = String(params.group_id ?? '').trim();
-            return gid ? `group:${gid}` : '';
-        }
-        if (method === 'group.pull_events') {
-            const gid = String(params.group_id ?? '').trim();
-            return gid ? `group_event:${gid}` : '';
-        }
-        return '';
-    }
-    _tryAcquirePullGate(key) {
-        if (!key)
-            return 0;
-        const now = Date.now();
-        const gate = this._pullGates.get(key) ?? { inflight: false, startedAt: 0, token: 0 };
-        if (gate.inflight && now - gate.startedAt <= AUNClient._PULL_GATE_STALE_MS) {
-            return null;
-        }
-        if (gate.inflight) {
-            this._clientLog.warn(`pull in-flight stale reset: key=${key} age=${now - gate.startedAt}ms`);
-        }
-        gate.token += 1;
-        gate.inflight = true;
-        gate.startedAt = now;
-        this._pullGates.set(key, gate);
-        return gate.token;
-    }
-    _releasePullGate(key, token) {
-        if (!key || token == null)
-            return;
-        const gate = this._pullGates.get(key);
-        if (!gate || gate.token !== token)
-            return;
-        gate.inflight = false;
-        gate.startedAt = 0;
+        return this._rpcPipeline.pullGateKeyForCall(method, params);
     }
     async _runPullSerialized(key, operation) {
-        let token = this._tryAcquirePullGate(key);
-        if (token === null) {
-            const deadline = Date.now() + AUNClient._PULL_GATE_STALE_MS + 100;
-            while (token === null && Date.now() <= deadline) {
-                await this._sleep(25);
-                token = this._tryAcquirePullGate(key);
-            }
-            if (token === null) {
-                throw new StateError(`pull already in-flight for ${key}`);
-            }
-        }
-        try {
-            return await operation();
-        }
-        finally {
-            this._releasePullGate(key, token);
-        }
+        return await this._rpcPipeline.runPullSerialized(key, operation);
     }
     /** 可取消的 sleep */
     _sleep(ms) {
@@ -6259,14 +2839,4 @@ export class AUNClient {
         });
     }
 }
-// ── 内部工具 ────────────────────────────────────────
-/** 生成 UUID v4 */
-function _uuidV4() {
-    const bytes = new Uint8Array(16);
-    crypto.getRandomValues(bytes);
-    bytes[6] = (bytes[6] & 0x0f) | 0x40;
-    bytes[8] = (bytes[8] & 0x3f) | 0x80;
-    const hex = Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
-    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
-}
 //# sourceMappingURL=client.js.map