@agentunion/fastaun 0.5.25 → 0.5.27

package/dist/client.d.ts

@@ -20,6 +20,8 @@ import { AID } from './aid.js';
 import { type OwnershipConsensusResult } from './ownership-v21.js';
 import { type OwnershipTaskResult } from './ownership-workflow.js';
 import { type CertificateMaterial } from './org-protocol.js';
+import { type RecordVerificationContext as SemanticRecordVerificationContext, type SemanticMessageVerificationContext } from './semantic-protocol.js';
+import type { SemanticPersistentState } from './semantic-facade.js';
 /**
  * 递归排序键的 JSON 序列化（Canonical JSON for AUN）
  * 等价于 Python json.dumps(sort_keys=True, separators=(",",":"), ensure_ascii=False)
@@ -108,6 +110,11 @@ export declare class AUNClient {
     private _startCredentialRenewal;
     private _stopCredentialRenewal;
     _rememberCredential(credential: JsonObject, material: Record<string, unknown>, certificate?: CertificateMaterial): void;
+    _semanticContextKey(): string;
+    _loadSemanticState(): SemanticPersistentState;
+    _saveSemanticState(state: SemanticPersistentState): void;
+    _semanticVerificationContext(): SemanticRecordVerificationContext;
+    _semanticMessageVerificationContext(): SemanticMessageVerificationContext;
     private _verifyIncomingServiceEvent;
     private _handleCredentialRenewal;
     /** 实例级 protected_headers */
@@ -219,6 +226,9 @@ export declare class AUNClient {
     private _reconnectAbort;
     private _reconnectTask;
     private _reconnectEventDispatchDepth;
+    private _gatewayConnectionId;
+    private _migrationPending;
+    private _migrationRevision;
     private _serverKicked;
     /** 缓存最近一次 gateway.disconnect 信息（含服务端附带的 detail），用于后续 connection.state 透传 */
     private _lastDisconnectInfo;
@@ -612,6 +622,8 @@ export declare class AUNClient {
     private _unrefTimer;
     /** 不重连 close code 集合：认证失败/权限错误/被踢等，重连无意义 */
     private static readonly _NO_RECONNECT_CODES;
+    private _onGatewayMigrate;
+    private _runGatewayMigration;
     /** 处理服务端主动断开通知 event/gateway.disconnect。
      *
      * 服务端可能附带结构化 detail 字段（如配额超限时含 aid/device_id/slot_id/quota_kind/evicted_by）。

package/dist/client.js

@@ -43,7 +43,7 @@ import { V2E2EECoordinator } from './client/v2-e2ee.js';
 import { GroupStateCoordinator } from './client/group-state.js';
 import { decryptMessage, } from './v2/e2ee/index.js';
 import { ecdsaVerifyRaw } from './v2/crypto/ecdsa.js';
-import { decryptedOwnershipJsonText } from './v2/e2ee/decrypt.js';
+import { decryptedOwnershipJsonText, decryptedMessagePayloadBytes } from './v2/e2ee/decrypt.js';
 import { isJsonObject, ConnectionState, STATE_TO_PUBLIC, } from './types.js';
 import { AID } from './aid.js';
 import { certFingerprint, certMatchesFingerprint, normalizeFingerprintHex, publicKeyMatchesFingerprint } from './cert-utils.js';
@@ -51,6 +51,7 @@ import { validateAgentMdCertificate, validateAgentMdDocument } from './agent-md-
 import { OwnershipFiles, OwnershipStorageAdapter, ownershipAid, ownershipFailure } from './ownership-v21.js';
 import { OwnershipWorkflow, OWNERSHIP_SDK_MESSAGE_TYPE, parseOwnershipMessage } from './ownership-workflow.js';
 import { canonicalJson, createCredential, createMemberCredential, signMembershipBinding, digest, validateMembershipBinding, verifyMembershipBinding, verifyCredentialSignature, createRepresentationProof, verifyServiceEvent, buildRequestBinding, validateRequestBinding, CredentialRenewal } from './org-protocol.js';
+import { SemanticProtocolError } from './semantic-protocol.js';
 function isPromiseLike(value) {
     return Boolean(value && typeof value.then === 'function');
 }
@@ -675,12 +676,12 @@ export class AUNClient {
         this._credentialRenewalAbort = abort;
         const current = () => this._credentialRenewalAbort === abort && !abort.signal.aborted && aid === this._aid && version === this._serviceEventIdentityVersion && ['ready', 'connected'].includes(this._state) && !this._closing && !this._disconnecting;
         const guard = { current, signal: abort.signal };
-        this._nextCredentialRevocationSyncAt ||= Date.now() + 3_600_000;
+        this._nextCredentialRevocationSyncAt = Date.now();
         const scan = async () => {
             const task = this._credentialRenewalScan.then(async () => {
                 if (!current())
                     return;
-                const syncRevocations = Date.now() >= this._nextCredentialRevocationSyncAt;
+                const syncRevocations = this._sessionOptions.connection_kind !== 'short' && Date.now() >= this._nextCredentialRevocationSyncAt;
                 if (syncRevocations)
                     this._nextCredentialRevocationSyncAt = Date.now() + 3_600_000;
                 await this._resumeCredentialRenewalAfterConnect(guard, syncRevocations);
@@ -710,13 +711,95 @@ export class AUNClient {
         }
         this._safeAsync(this._getCredentialRenewal().remember(credential, material));
     }
+    _semanticContextKey() {
+        return JSON.stringify([this._aid, this._currentAid?.certFingerprint, this._serviceEventIdentityVersion]);
+    }
+    _loadSemanticState() {
+        const state = (this._tokenStore._loadMetadataStrict?.(this._aid ?? '') ?? this._tokenStore.loadMetadata?.(this._aid ?? ''))?.semantic_credentials_v1;
+        return structuredClone(state ?? {});
+    }
+    _saveSemanticState(state) {
+        if (!this._aid)
+            throw new ValidationError('semantic credential persistence requires a loaded identity');
+        if (!this._tokenStore.saveMetadata)
+            throw new ValidationError('semantic credential metadata storage is unavailable');
+        this._tokenStore.saveMetadata(this._aid, { semantic_credentials_v1: state });
+    }
+    _semanticVerificationContext() {
+        const scope = this._semanticContextKey();
+        const current = () => { if (this._semanticContextKey() !== scope)
+            throw new ValidationError('semantic credential identity changed'); };
+        return {
+            resolveCertificate: async (fingerprint, aid, signedAt) => {
+                current();
+                const certificate = await this._fetchPeerCert(aid, fingerprint, undefined, signedAt);
+                current();
+                return certificate;
+            },
+            verifyCertificateTrust: async (material, context) => {
+                current();
+                const certificate = typeof material === 'string' && material.startsWith('-----BEGIN CERTIFICATE-----')
+                    ? material : new crypto.X509Certificate(typeof material === 'string' ? Buffer.from(material, 'base64') : material).toString();
+                const gateway = await this._resolveOwnershipCertificateGateway(context.expectedAID);
+                await this._auth.verifyPeerCertificate(gateway, certificate, context.expectedAID, context.signedAt);
+                await this._auth.verifyPeerCertificate(gateway, certificate, context.expectedAID, undefined, true);
+                current();
+            },
+        };
+    }
+    _semanticMessageVerificationContext() {
+        const actor = this._aid, device = this._deviceId, scope = this._semanticContextKey(), session = this._v2Session;
+        const trust = this._semanticVerificationContext();
+        const current = () => {
+            if (!actor || this._semanticContextKey() !== scope || device !== this._deviceId || session !== this._v2Session)
+                throw new SemanticProtocolError('SEMANTIC_IDENTITY_INVALID', 'semantic message verification identity changed');
+        };
+        const senderCertificate = async (sender, fingerprint, signedAt) => {
+            current();
+            const certificate = await this._fetchPeerCert(sender, fingerprint, undefined, signedAt);
+            if (!publicKeyMatchesFingerprint(certificate, fingerprint))
+                throw new SemanticProtocolError('SEMANTIC_IDENTITY_INVALID', 'historical sender key fingerprint differs');
+            current();
+            return certificate;
+        };
+        return {
+            selfAid: actor ?? '', selfDeviceId: device,
+            resolveDecryptionKeys: async (envelope) => {
+                current();
+                if (!session || session.aid !== actor || session.deviceId !== device)
+                    throw new SemanticProtocolError('SEMANTIC_STATE_UNAVAILABLE', 'authenticated V2 receiver session is unavailable');
+                const recipient = envelope.recipient;
+                const row = Array.isArray(envelope.recipients) ? envelope.recipients.find((item) => Array.isArray(item) && item.length >= 6 && item[0] === actor && (item[1] === device || item[1] === '')) : undefined;
+                if (!row && (!recipient || recipient.aid !== actor || recipient.device_id !== device && recipient.device_id !== ''))
+                    throw new SemanticProtocolError('SEMANTIC_IDENTITY_INVALID', 'original receiver row is unavailable');
+                const spkId = String(row ? row[5] ?? '' : recipient.spk_id ?? ''), aad = envelope.aad;
+                if (envelope.type === 'e2ee.group_encrypted') {
+                    const keys = session.getGroupDecryptKeys(String(aad.group_id ?? ''), spkId);
+                    return { ikPriv: keys.ikPriv, spkPriv: keys.spkPriv ?? undefined };
+                }
+                return session.getDecryptKeys(spkId);
+            },
+            resolveSenderKey: async (sender, _device, fingerprint, signedAt) => {
+                const certificate = await senderCertificate(sender, fingerprint, signedAt);
+                return new Uint8Array(new crypto.X509Certificate(certificate).publicKey.export({ type: 'spki', format: 'der' }));
+            },
+            verifySenderIdentity: async (sender, _device, fingerprint, signedAt, publicKey) => {
+                const certificate = await senderCertificate(sender, fingerprint, signedAt);
+                await trust.verifyCertificateTrust(certificate, { expectedAID: sender, signedAt, now: Math.trunc(Date.now() / 1000) });
+                const expected = new crypto.X509Certificate(certificate).publicKey.export({ type: 'spki', format: 'der' });
+                if (!expected.equals(Buffer.from(publicKey)))
+                    throw new SemanticProtocolError('SEMANTIC_IDENTITY_INVALID', 'historical sender identity differs from message key');
+                current();
+            },
+        };
+    }
     async _verifyIncomingServiceEvent(event, payload) {
         const targetAid = this._identity?.aid ?? '';
         const version = this._serviceEventIdentityVersion;
         const signal = this._serviceEventIdentityAbort.signal;
         const expiresAt = Number(payload?.expires_at);
         const transport = this._transport, connectionGeneration = transport?._connectionGeneration, workerGeneration = transport?._workerGeneration;
-        const current = () => version === this._serviceEventIdentityVersion && targetAid === (this._identity?.aid ?? '') && transport === this._transport && connectionGeneration === this._transport?._connectionGeneration && workerGeneration === this._transport?._workerGeneration && Date.now() / 1000 < expiresAt;
+        const current = () => version === this._serviceEventIdentityVersion && targetAid === (this._identity?.aid ?? '') && transport === this._transport && connectionGeneration === this._transport?._connectionGeneration && workerGeneration === this._transport?._workerGeneration && Date.now() / 1000 <= expiresAt + 300;
         const verified = await verifyServiceEvent(event, payload, { targetAid, resolveEventCertificate: (aid, fingerprint) => this._fetchServiceEventCertificate(aid, fingerprint), resolveCredentialService: this.resolveCredentialService });
         if (!current())
             throw new ValidationError('service event receiver identity changed');
@@ -865,6 +948,9 @@ export class AUNClient {
     _reconnectAbort = null;
     _reconnectTask = null;
     _reconnectEventDispatchDepth = 0;
+    _gatewayConnectionId = '';
+    _migrationPending = false;
+    _migrationRevision = new Map();
     _serverKicked = false;
     /** 缓存最近一次 gateway.disconnect 信息（含服务端附带的 detail），用于后续 connection.state 透传 */
     _lastDisconnectInfo = null;
@@ -1058,6 +1144,10 @@ export class AUNClient {
         }
         // 服务端主动断开通知：记录日志并标记不重连
         this._dispatcher.subscribeProtocol('_raw.gateway.disconnect', (data) => this._onGatewayDisconnect(data));
+        this._dispatcher.subscribeProtocol('notification', (data) => {
+            if (isJsonObject(data) && data.method === 'gateway.migrate' && !('id' in data))
+                this._onGatewayMigrate(data.params);
+        });
     }
     // ── 属性 ──────────────────────────────────────────────────
     /** 当前 AID */
@@ -1730,7 +1820,7 @@ export class AUNClient {
     async _resumeOrgRequest(method, params, target) {
         const binding = params.request_binding;
         const now = Math.trunc(Date.now() / 1000);
-        if (!isJsonObject(binding) || now < Number(binding.exp))
+        if (!isJsonObject(binding) || now <= Number(binding.exp) + 300)
             return params;
         const credentials = isJsonObject(params.credentials) ? params.credentials : {};
         const credential = ['member_credential', 'approval_credential', 'audit_credential'].map((field) => credentials[field]).find(isJsonObject) ?? params.credential_template;
@@ -1787,7 +1877,7 @@ export class AUNClient {
             checkpoint = { ...checkpoint, result, phase: 'upload' };
             tokens.saveMetadata(orgAid, { org_identity_creation: checkpoint });
         }
-        await this._uploadOrgAgentMd(store, orgAid, params);
+        await this._uploadOrgAgentMd(store, orgAid, params, checkpoint.result);
         tokens.saveMetadata(orgAid, { org_identity_creation: null });
         return checkpoint.result;
     }
@@ -1829,7 +1919,7 @@ export class AUNClient {
         const now = Math.trunc(Date.now() / 1000);
         if (binding.org_id !== orgAid || nextBinding.org_id !== orgAid || binding.member_aid === ownerAid || nextBinding.member_aid !== ownerAid
             || binding.role !== 'member' || nextBinding.role !== 'owner' || digest(previous.terms) !== binding.terms_hash || digest(next.terms) !== nextBinding.terms_hash
-            || !Number.isSafeInteger(nextBinding.iat) || !Number.isSafeInteger(nextBinding.exp) || Number(nextBinding.iat) > now || Number(nextBinding.exp) <= now
+            || !Number.isSafeInteger(nextBinding.iat) || !Number.isSafeInteger(nextBinding.exp) || Number(nextBinding.iat) > now + 300 || now > Number(nextBinding.exp) + 300
             || credential.iss !== orgAid || credential.sub !== binding.member_aid || credential.parent != null || credential.delegate !== false
             || ext.credential_type !== 'member' || ext.bound_to_membership !== true || ext.org_id !== orgAid || ext.membership_id !== binding.membership_id
             || ext.binding_version !== binding.binding_version || ext.membership_terms_hash !== binding.terms_hash
@@ -1848,7 +1938,7 @@ export class AUNClient {
         const checkedAt = Math.trunc(Date.now() / 1000);
         verifyMembershipBinding(binding, resolve, checkedAt, orgAid);
         verifyCredentialSignature(credential, resolve, checkedAt, orgAid);
-        if (Number(nextBinding.exp) <= checkedAt)
+        if (checkedAt > Number(nextBinding.exp) + 300)
             throw ownershipFailure('invalid', 'Org transfer membership materials do not match');
     }
     async completeOrgTransfer(params = {}, options = {}) {
@@ -1938,7 +2028,7 @@ export class AUNClient {
             tokenStore.saveMetadata(orgAid, { org_identity_transfer: pending });
         }
         const result = await this.call('org.lifecycle.transferAccept', await this._resumeOrgRequest('org.lifecycle.transferAccept', pending.finalize_params, target));
-        await this._uploadOrgAgentMd(store, orgAid, pending.source_params);
+        await this._uploadOrgAgentMd(store, orgAid, pending.source_params, result);
         tokenStore.saveMetadata(orgAid, { org_identity_transfer: { transfer_id: transferId, owner_aid: owner.aid, input_hash: inputHash, phase: 'completed', result } });
         localStore.clearPendingGroupBind(pendingKey);
         return result;
@@ -1976,15 +2066,18 @@ export class AUNClient {
         }
         return result;
     }
-    async _uploadOrgAgentMd(store, orgAid, params) {
+    async _uploadOrgAgentMd(store, orgAid, params, initialResult) {
         const owner = this._currentAid;
         if (!owner)
             throw ownershipFailure('forbidden', 'Org agent.md requires current owner');
-        if (await this._resumeGroupAgentMdUpload(store, orgAid))
+        const organization = isJsonObject(initialResult) && isJsonObject(initialResult.organization) ? initialResult.organization : undefined;
+        const bootstrap = organization?.org_id === orgAid && organization.owner_aid === owner.aid && organization.status === 'active'
+            ? { aid: orgAid, ownerAid: owner.aid, certFingerprint: this._localEntityCertificate(orgAid).certFingerprint, completedTransfer: Boolean(params.transfer_id && isJsonObject(initialResult) && initialResult.transfer_id === params.transfer_id) } : undefined;
+        if (await this._resumeGroupAgentMdUpload(store, orgAid, bootstrap))
             return;
         const identity = this._localEntityCertificate(orgAid);
         const content = String(params.org_agent_md ?? buildDefaultAgentMd(orgAid, { type: 'org', owner: owner.aid, entityCertFingerprint: identity.certFingerprint, name: String(params.name ?? orgAid) }));
-        const uploaded = await store.uploadAgentMd(orgAid, content, { uploaderAid: owner.aid, entityOwnerResolver: (aid, type) => this._resolveEntityAgentMdOwner(aid, type), entityIdentityGetter: (aid) => this._freshEntityCertificate(aid, 'org') });
+        const uploaded = await store.uploadAgentMd(orgAid, content, { uploaderAid: owner.aid, entityOwnerResolver: (aid, type) => this._resolveEntityAgentMdOwner(aid, type, bootstrap), entityIdentityGetter: (aid) => this._freshEntityCertificate(aid, 'org') });
         if (!uploaded.ok) {
             const code = ['invalid', 'unavailable', 'forbidden', 'conflict', 'persistence_unavailable'].includes(uploaded.error.code) ? uploaded.error.code : uploaded.error.code === 'NETWORK_ERROR' ? 'unavailable' : 'invalid';
             throw ownershipFailure(code, uploaded.error.message, code === 'unavailable');
@@ -2100,7 +2193,7 @@ export class AUNClient {
         if (!imported.ok) {
             throw new ValidationError(imported.error.message);
         }
-        await this._uploadGroupAgentMd(store, groupAid, payload, group);
+        await this._uploadGroupAgentMd(store, groupAid, payload, group, certPem);
         if (keystore && typeof keystore.clearPendingGroupBind === 'function') {
             keystore.clearPendingGroupBind(pendingKey);
         }
@@ -2168,7 +2261,7 @@ export class AUNClient {
             '',
         ].join('\n');
     }
-    async _resumeGroupAgentMdUpload(store, groupAid) {
+    async _resumeGroupAgentMdUpload(store, groupAid, bootstrap) {
         const identityStore = store;
         const pendingManager = identityStore._agentMdManager ?? this._agentMdManager;
         const pending = pendingManager.pendingUpload(groupAid);
@@ -2188,7 +2281,7 @@ export class AUNClient {
             uploadViaGatewayHost: true,
             ownerAidGetter: () => identity.aid,
             currentAidGetter: () => identity,
-            entityOwnerResolver: (aid, type) => this._resolveEntityAgentMdOwner(aid, type),
+            entityOwnerResolver: (aid, type) => this._resolveEntityAgentMdOwner(aid, type, bootstrap?.completedTransfer || pending.condition?.if_none_match === '*' ? bootstrap : undefined),
             entityIdentityGetter: (aid, type) => this._freshEntityCertificate(aid, type),
             entitySignerResolver: (aid, fingerprint) => this._freshEntitySigner(aid, fingerprint),
             gatewayResolver: (aid) => identityStore._resolveGateway(aid),
@@ -2203,15 +2296,16 @@ export class AUNClient {
         });
         return await manager.resumePendingUpload(groupAid);
     }
-    async _uploadGroupAgentMd(store, groupAid, params, group) {
+    async _uploadGroupAgentMd(store, groupAid, params, group, initialCertificate) {
         const uploaderAid = String(this._aid ?? '').trim();
         if (!uploaderAid) {
             throw new ValidationError('group agent.md upload requires current owner AID');
         }
         this._aidStore = store;
-        if (await this._resumeGroupAgentMdUpload(store, groupAid))
+        const bootstrap = initialCertificate ? { aid: groupAid, ownerAid: String(group.owner_aid ?? '').trim(), certFingerprint: certFingerprint(initialCertificate), type: 'group' } : undefined;
+        if (await this._resumeGroupAgentMdUpload(store, groupAid, bootstrap))
             return;
-        const uploaded = await store.uploadAgentMd(groupAid, this._groupAgentMdContent(groupAid, params, group), { uploaderAid, entityOwnerResolver: (aid, type) => this._resolveEntityAgentMdOwner(aid, type), entityIdentityGetter: (aid) => this._freshEntityCertificate(aid) });
+        const uploaded = await store.uploadAgentMd(groupAid, this._groupAgentMdContent(groupAid, params, group), { uploaderAid, entityOwnerResolver: (aid, type) => this._resolveEntityAgentMdOwner(aid, type, bootstrap), entityIdentityGetter: (aid) => this._freshEntityCertificate(aid) });
         if (!uploaded.ok) {
             const code = ['invalid', 'unavailable', 'forbidden', 'conflict', 'persistence_unavailable'].includes(uploaded.error.code) ? uploaded.error.code : uploaded.error.code === 'NETWORK_ERROR' ? 'unavailable' : 'invalid';
             throw ownershipFailure(code, `group agent.md upload failed: ${uploaded.error.message}`, code === 'unavailable');
@@ -2232,8 +2326,20 @@ export class AUNClient {
         const material = await this._auth.resolveOwnershipCertificate(await this._resolveOwnershipCertificateGateway(aid), aid, fingerprint, 'signing');
         return AID._create({ aid, aunPath: this._configModel.aunPath, certPem: material.cert_pem, certValid: true, privateKeyPem: null, privateKeyValid: false });
     }
-    async _resolveEntityAgentMdOwner(aid, type) {
-        const authority = await this._agentMdManager.readEntityAuthorityFresh(aid);
+    async _resolveEntityAgentMdOwner(aid, type, bootstrap) {
+        let authority;
+        try {
+            authority = bootstrap?.completedTransfer && type === 'org' && bootstrap.aid === aid && bootstrap.ownerAid === this._currentAid?.aid
+                ? { owner_aid: bootstrap.ownerAid, entity_cert_fingerprint: bootstrap.certFingerprint }
+                : await this._agentMdManager.readEntityAuthorityFresh(aid);
+        }
+        catch (error) {
+            if (!bootstrap || bootstrap.aid !== aid || type !== (bootstrap.type ?? 'org') || !(error instanceof AUNError) || !isJsonObject(error.data) || error.data.http_status !== 404)
+                throw error;
+            if (!bootstrap.ownerAid || bootstrap.ownerAid !== this._currentAid?.aid)
+                throw ownershipFailure('forbidden', 'entity initial owner does not match uploader');
+            authority = { owner_aid: bootstrap.ownerAid, entity_cert_fingerprint: bootstrap.certFingerprint };
+        }
         const identity = await this._freshEntityCertificate(aid, type);
         if (authority.entity_cert_fingerprint !== identity.certFingerprint)
             throw ownershipFailure('conflict', 'entity authority changed during current-certificate verification');
@@ -2301,7 +2407,7 @@ export class AUNClient {
         if (!imported.ok) {
             throw new ValidationError(imported.error.message);
         }
-        await this._uploadGroupAgentMd(store, groupAid, payload, group);
+        await this._uploadGroupAgentMd(store, groupAid, payload, group, certPem);
         // 落盘成功，清除 pending 槽位
         if (groupId && keystore && typeof keystore.clearPendingGroupBind === 'function') {
             keystore.clearPendingGroupBind(pendingKey);
@@ -2600,6 +2706,8 @@ export class AUNClient {
      * 发送轻量在线通知，不走离线存储、seq/pull 或 ack。
      */
     async notify(method, params, options = {}) {
+        if (this._migrationPending)
+            throw new ConnectionError('client is migrating');
         if (params !== undefined && params !== null && !isJsonObject(params)) {
             throw new ValidationError('notify params must be an object');
         }
@@ -3953,10 +4061,16 @@ export class AUNClient {
             const challenge = await this._transport.connect(gatewayUrl);
             this._assertReconnectOwner(reconnectOwner);
             this._lifecycle.assertConnectionAttemptOwner(connectionOwner);
+            const authTransport = reconnectOwner ? {
+                call: (...args) => {
+                    this._assertReconnectOwner(reconnectOwner);
+                    return this._transport.call(...args);
+                },
+            } : this._transport;
             this._clientLog.debug(`WebSocket connection established: gateway=${gatewayUrl}`);
             this._state = 'authenticating';
             if (allowReauth) {
-                const authContext = await this._auth.connectSession(this._transport, challenge, gatewayUrl, {
+                const authContext = await this._auth.connectSession(authTransport, challenge, gatewayUrl, {
                     accessToken: String(params.access_token ?? ''),
                     deviceId: this._deviceId,
                     slotId: this._slotId,
@@ -3982,10 +4096,11 @@ export class AUNClient {
                     if (isJsonObject(auth.hello) && 'heartbeat_interval' in auth.hello) {
                         this._applyServerHeartbeatInterval(auth.hello.heartbeat_interval, 'auth');
                     }
+                    this._gatewayConnectionId = isJsonObject(auth.hello) && isJsonObject(auth.hello.connection) ? String(auth.hello.connection.id ?? '') : '';
                 }
             }
             else {
-                const hello = await this._auth.initializeWithToken(this._transport, challenge, String(params.access_token), {
+                const hello = await this._auth.initializeWithToken(authTransport, challenge, String(params.access_token), {
                     deviceId: this._deviceId,
                     slotId: this._slotId,
                     deliveryMode: this._connectDeliveryMode,
@@ -3999,6 +4114,7 @@ export class AUNClient {
                 if (isJsonObject(hello) && 'heartbeat_interval' in hello) {
                     this._applyServerHeartbeatInterval(hello.heartbeat_interval, 'auth');
                 }
+                this._gatewayConnectionId = isJsonObject(hello) && isJsonObject(hello.connection) ? String(hello.connection.id ?? '') : '';
             }
             this._assertReconnectOwner(reconnectOwner);
             this._lifecycle.assertConnectionAttemptOwner(connectionOwner);
@@ -4006,6 +4122,7 @@ export class AUNClient {
                 throw new ConnectionError('websocket disconnected during authentication');
             }
             this._serverKicked = false;
+            this._migrationPending = false;
             this._lastDisconnectInfo = null;
             this._state = 'ready';
             this._connectedAt = Date.now();
@@ -4435,8 +4552,10 @@ export class AUNClient {
             return null;
         }
         let plaintext;
+        let payloadBytes;
         try {
             plaintext = decryptMessage(envelope, this._aid ?? '', this._deviceId, ikPriv, spkPriv, senderPubDer);
+            payloadBytes = decryptedMessagePayloadBytes(plaintext);
             if (plaintext === null)
                 throw new Error('recipient_not_found_or_envelope_verification_failed');
         }
@@ -4488,6 +4607,11 @@ export class AUNClient {
             encrypted: true,
             e2ee,
         };
+        if (!this._v2E2EE.isEncryptedEnvelopePayload(msg.payload))
+            result._semantic_evidence = {
+                envelope_bytes_base64: Buffer.from(envelopeJson, 'utf8').toString('base64'), payload_bytes_base64: Buffer.from(payloadBytes).toString('base64'),
+                received_by: this._aid ?? '', received_at: Math.trunc(Date.now() / 1000), source,
+            };
         if (typeof plaintext.type === 'string' && plaintext.type.startsWith('aun.ownership.'))
             result.from_aid = fromAid;
         if (senderDeviceId)
@@ -4719,7 +4843,7 @@ export class AUNClient {
         }
     }
     /** 发现并缓存全部 Gateway 候选，供首连和自动重连故障转移使用。 */
-    async _resolveGatewayCandidatesForAid(aid) {
+    async _resolveGatewayCandidatesForAid(aid, fresh = false, reconnectOwner) {
         const resolvedAid = String(aid ?? this._aid ?? '').trim();
         if (!resolvedAid) {
             throw new StateError('gateway discovery requires a loaded AID');
@@ -4732,14 +4856,15 @@ export class AUNClient {
         const tokenStore = this._tokenStore;
         const discoveryIsCurrent = () => (this._discovery === discovery
             && this._tokenStore === tokenStore
-            && !this._closing);
-        if (sameIssuer && this._gatewayCandidates.length > 0)
+            && !this._closing
+            && (!reconnectOwner || this._ownsReconnect(reconnectOwner)));
+        if (!fresh && sameIssuer && this._gatewayCandidates.length > 0)
             return [...this._gatewayCandidates];
-        if (sameIssuer && this._gatewayUrl) {
+        if (!fresh && sameIssuer && this._gatewayUrl) {
             this._gatewayCandidates = [this._gatewayUrl];
             return [...this._gatewayCandidates];
         }
-        if (!sameIssuer) {
+        if (!fresh && !sameIssuer) {
             const cached = this._peerGatewayCache.get(issuerDomain);
             if (cached)
                 return [...cached];
@@ -4754,7 +4879,7 @@ export class AUNClient {
                 : [];
             const cachedGateway = cachedList[0]
                 ?? (isJsonObject(metadata) ? String(metadata.gateway_url ?? '').trim() : '');
-            if (cachedGateway) {
+            if (!fresh && cachedGateway) {
                 const gatewayUrls = [...new Set([cachedGateway, ...cachedList])];
                 if (sameIssuer) {
                     this._gatewayCandidates = gatewayUrls;
@@ -5135,6 +5260,157 @@ export class AUNClient {
     // ── 内部：断线重连 ────────────────────────────────────────
     /** 不重连 close code 集合：认证失败/权限错误/被踢等，重连无意义 */
     static _NO_RECONNECT_CODES = new Set([4001, 4003, 4008, 4009, 4010, 4011, 4013, 4014, 4015]);
+    _onGatewayMigrate(input) {
+        const data = input;
+        if (!isJsonObject(data) || this._closing || this._disconnecting || this._connectAbort || this._reconnectActive
+            || this._state !== 'ready' || !this._sessionParams || !this._gatewayConnectionId)
+            return;
+        const aid = this._aid ?? '';
+        const issuer = aid.slice(aid.indexOf('.') + 1).toLowerCase().replace(/\.$/, '');
+        const now = Date.now() / 1000;
+        if (typeof data.migration_id !== 'string' || !data.migration_id.trim()
+            || typeof data.revision !== 'number' || !Number.isSafeInteger(data.revision) || data.revision <= 0
+            || typeof data.issuer !== 'string' || data.issuer.trim().toLowerCase().replace(/\.$/, '') !== issuer
+            || data.aid !== aid || data.device_id !== this._deviceId || data.slot_id !== this._slotId
+            || data.connection_id !== this._gatewayConnectionId || typeof data.gateway_url !== 'string'
+            || typeof data.expires_at !== 'number' || !Number.isFinite(data.expires_at)
+            || data.expires_at <= now || data.expires_at > now + 300)
+            return;
+        let target;
+        try {
+            target = new URL(data.gateway_url);
+        }
+        catch {
+            return;
+        }
+        const hostname = target.hostname.toLowerCase();
+        if (target.protocol !== 'wss:' || target.username || target.password || target.hash
+            || /^\w+:\/\/[^/]*@/.test(data.gateway_url) || target.pathname !== '/aun'
+            || !(hostname === issuer || hostname.endsWith(`.${issuer}`))
+            || !hostname.split('.').every((label) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label)))
+            return;
+        const identity = JSON.stringify([this._aid, this._deviceId, this._slotId]);
+        const previous = this._migrationRevision.get(identity);
+        if (previous && (data.revision <= previous.revision || data.migration_id === previous.migrationId))
+            return;
+        this._migrationRevision.set(identity, { revision: data.revision, migrationId: data.migration_id });
+        this._migrationPending = true;
+        this._reconnectActive = true;
+        const owner = new AbortController();
+        this._reconnectAbort = owner;
+        this._state = 'standby';
+        this._stopBackgroundTasks();
+        this._dispatcher.enqueue('gateway.migrate', data);
+        const task = Promise.resolve().then(() => this._runGatewayMigration(data, owner, identity));
+        this._reconnectTask = task;
+        this._safeAsync(task);
+    }
+    async _runGatewayMigration(data, owner, identity) {
+        const expiresAt = Number(data.expires_at) * 1000;
+        const current = () => this._ownsReconnect(owner) && !this._disconnecting && !this._connectAbort
+            && identity === JSON.stringify([this._aid, this._deviceId, this._slotId]);
+        const wait = (operation) => this._lifecycle.waitForAttempt(operation, undefined, owner);
+        const retry = this._sessionOptions.retry;
+        const maxAttempts = Number(retry.max_attempts ?? 0);
+        let delay = clampReconnectDelayMs(Number(retry.initial_delay ?? 1) * 1000, RECONNECT_MIN_BASE_DELAY_MS);
+        const maxDelay = clampReconnectDelayMs(Number(retry.max_delay ?? 64) * 1000, RECONNECT_MAX_BASE_DELAY_MS);
+        const expiryTimer = setTimeout(() => {
+            if (!current())
+                return;
+            owner.abort();
+            this._discovery._cancelPending?.();
+            this._auth._cancelPending?.();
+            void this._transport.close().catch(() => { });
+        }, Math.max(0, expiresAt - Date.now()));
+        let lastError = new ConnectionError('gateway migration expired');
+        try {
+            if (!current())
+                return;
+            await this._transport.waitForPending(Math.min(5000, Math.max(0, expiresAt - Date.now())), owner.signal);
+            if (!current())
+                return;
+            await this._saveSeqTrackerState();
+            await this._transport.close();
+            if (!current())
+                return;
+            this._delivery.resetInlineAckState();
+            for (let attempt = 1; current() && Date.now() < expiresAt; attempt++) {
+                if (maxAttempts > 0 && attempt > maxAttempts)
+                    throw lastError;
+                let candidates = attempt === 1 ? [String(data.gateway_url)] : [];
+                if (attempt > 1) {
+                    try {
+                        candidates = await wait(this._resolveGatewayCandidatesForAid(String(data.aid), true, owner));
+                    }
+                    catch (error) {
+                        lastError = error;
+                    }
+                }
+                for (let index = 0; index < candidates.length; index++) {
+                    const gateway = candidates[index];
+                    if (!current() || Date.now() >= expiresAt)
+                        return;
+                    this._state = 'reconnecting';
+                    this._migrationPending = true;
+                    try {
+                        await wait(this._connectOnce({ ...this._sessionParams, gateway, gateways: candidates }, true, owner));
+                        if (!current())
+                            return;
+                        if (!this._transport.isConnected())
+                            throw new ConnectionError('websocket disconnected while migrating');
+                        this._sessionParams.gateway = gateway;
+                        this._sessionParams.gateways = candidates;
+                        return;
+                    }
+                    catch (error) {
+                        lastError = error;
+                        if (!current())
+                            return;
+                        this._migrationPending = true;
+                        await this._transport.close().catch(() => { });
+                        if (!current())
+                            return;
+                        if (attempt === 1 && index === 0) {
+                            try {
+                                const discovered = await wait(this._resolveGatewayCandidatesForAid(String(data.aid), true, owner));
+                                candidates = [...candidates, ...discovered.filter((item) => !candidates.includes(item))];
+                            }
+                            catch (discoveryError) {
+                                lastError = discoveryError;
+                            }
+                        }
+                    }
+                }
+                if (!AUNClient._shouldRetryReconnect(lastError))
+                    throw lastError;
+                if (maxAttempts > 0 && attempt >= maxAttempts)
+                    throw lastError;
+                await this._sleep(Math.min(delay, Math.max(0, expiresAt - Date.now())), owner.signal);
+                if (!current())
+                    return;
+                delay = Math.min(delay * 2, maxDelay);
+            }
+        }
+        catch (error) {
+            lastError = error;
+        }
+        finally {
+            clearTimeout(expiryTimer);
+            if (this._reconnectAbort === owner) {
+                this._migrationPending = false;
+                this._reconnectActive = false;
+                this._reconnectAbort = null;
+                this._reconnectTask = null;
+                this._nextRetryAt = null;
+                if ((this._state !== 'ready' || owner.signal.aborted) && !this._closing) {
+                    this._stopBackgroundTasks();
+                    this._state = 'standby';
+                    if (!owner.signal.aborted)
+                        this._dispatcher.enqueue('connection.error', { error: formatCaughtError(lastError) });
+                }
+            }
+        }
+    }
     /** 处理服务端主动断开通知 event/gateway.disconnect。
      *
      * 服务端可能附带结构化 detail 字段（如配额超限时含 aid/device_id/slot_id/quota_kind/evicted_by）。