@agentunion/fastaun 0.5.17 → 0.5.19

package/dist/client.js

@@ -26,7 +26,7 @@ import { normalizeGroupId } from './group-id.js';
 import { validateAIDFormat, validateGroupIDFormat } from './validators.js';
 import { RPCTransport } from './transport.js';
 import { AuthFlow } from './auth.js';
-import { AgentMdManager, buildDefaultAgentMd } from './agent-md.js';
+import { AgentMdManager, buildDefaultAgentMd, updateOwnershipAgentMd } from './agent-md.js';
 import { GroupIndexMetaCache } from './group-index.js';
 import { SeqTracker } from './seq-tracker.js';
 import { ClientRuntime } from './client/runtime.js';
@@ -37,15 +37,20 @@ import { LifecycleController } from './client/lifecycle.js';
 import { PeerDirectory } from './client/peers.js';
 import { RpcPipeline } from './client/rpc-pipeline.js';
 import { CollabClient } from './collab/client.js';
-import { GroupFacade, MailFacade, MessageFacade, StreamFacade } from './facades.js';
+import { CredentialFacade, OrgFacade, GroupFacade, MailFacade, MessageFacade, StreamFacade } from './facades.js';
 import { StorageVFS } from './storage/vfs.js';
 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 { isJsonObject, ConnectionState, STATE_TO_PUBLIC, } from './types.js';
 import { AID } from './aid.js';
-import { certMatchesFingerprint, normalizeFingerprintHex, publicKeyMatchesFingerprint } from './cert-utils.js';
+import { certFingerprint, certMatchesFingerprint, normalizeFingerprintHex, publicKeyMatchesFingerprint } from './cert-utils.js';
+import { validateAgentMdDocument } from './agent-md-schema.js';
+import { OwnershipFiles, OwnershipStorageAdapter, ownershipFailure, signOwnershipFile } from './ownership-v21.js';
+import { OwnershipWorkflow } from './ownership-workflow.js';
+import { canonicalJson, createCredential, createMemberCredential, signMembershipBinding, verifyServiceEvent } from './org-protocol.js';
 function isPromiseLike(value) {
     return Boolean(value && typeof value.then === 'function');
 }
@@ -120,6 +125,8 @@ const DEFAULT_SESSION_OPTIONS = {
 const RECONNECT_MIN_BASE_DELAY_MS = 1_000;
 const RECONNECT_MAX_BASE_DELAY_MS = 64_000;
 const TOKEN_REFRESH_CHECK_INTERVAL_MS = 30_000;
+const PENDING_P2P_PULL_DELAY_MS = 100;
+const PENDING_P2P_PULL_MAX_RETRIES = 20;
 const MAX_NOTIFY_PAYLOAD_SIZE = 64 * 1024;
 // P1-23: 非幂等方法使用更长超时（35s），避免 SDK 10s 超时 < gateway 30s 处理时间
 const NON_IDEMPOTENT_TIMEOUT_MS = 35_000;
@@ -340,6 +347,9 @@ function createAgentMdManagerForRuntime(opts) {
         logger: opts.logger(),
         ownerAidGetter: opts.ownerAid,
         currentAidGetter: opts.currentAid,
+        entityOwnerResolver: opts.resolveEntityOwner,
+        entityIdentityGetter: opts.fetchEntityIdentity,
+        entitySignerResolver: opts.fetchEntitySigner,
         gatewayResolver: async (aid) => {
             const gatewayUrl = await opts.gateway.resolve(aid);
             opts.gateway.set(gatewayUrl);
@@ -386,7 +396,47 @@ function createAgentMdManagerForRuntime(opts) {
             opts.identity.set(identity);
             return token;
         },
-        peerResolver: async (aid, certFingerprint) => {
+        uploadAccessTokenResolver: async (_aid, gatewayUrl) => {
+            const localAid = String(opts.ownerAid() ?? '').trim();
+            let identity = opts.identity.get();
+            if (!identity || String(identity.aid ?? '') !== localAid) {
+                throw new StateError('no local identity found, register or load an AID first');
+            }
+            const auth = opts.auth();
+            const cachedToken = String(identity.access_token ?? '');
+            const expiresAt = auth.getAccessTokenExpiry(identity);
+            if (cachedToken && (expiresAt === null || expiresAt > Date.now() / 1000 + 30))
+                return cachedToken;
+            if (identity.refresh_token) {
+                try {
+                    const refreshed = await auth.refreshCachedTokens(gatewayUrl, identity);
+                    const refreshedToken = String(refreshed.access_token ?? '');
+                    const refreshedExpiry = auth.getAccessTokenExpiry(refreshed);
+                    if (refreshedToken && (refreshedExpiry === null || refreshedExpiry > Date.now() / 1000 + 30)) {
+                        opts.identity.set(refreshed);
+                        return refreshedToken;
+                    }
+                }
+                catch {
+                    // refresh 失败时回退到完整 authenticate。
+                }
+            }
+            const result = await auth.authenticate(gatewayUrl, { aid: localAid });
+            const token = String(result.access_token ?? '');
+            if (!token)
+                throw new StateError('authenticate did not return access_token');
+            identity = auth.loadIdentityOrNone(localAid) ?? {
+                ...identity,
+                access_token: token,
+                refresh_token: String(result.refresh_token ?? identity.refresh_token ?? ''),
+                access_token_expires_at: typeof result.expires_at === 'number' ? result.expires_at : identity.access_token_expires_at,
+                token_exp: typeof result.expires_at === 'number' ? result.expires_at : identity.token_exp,
+                expires_at: typeof result.expires_at === 'number' ? result.expires_at : identity.expires_at,
+            };
+            opts.identity.set(identity);
+            return token;
+        },
+        peerResolver: async (aid, certFingerprint, signedAt) => {
             const target = String(aid ?? '').trim();
             const expectedFp = String(certFingerprint ?? '').trim().toLowerCase();
             const current = opts.currentAid();
@@ -400,7 +450,7 @@ function createAgentMdManagerForRuntime(opts) {
                 }
                 catch { /* best effort before cert fetch */ }
             }
-            const certPem = String(await opts.fetchPeerCert(target, expectedFp || undefined) ?? '').trim();
+            const certPem = String(await opts.fetchPeerCert(target, expectedFp || undefined, signedAt) ?? '').trim();
             if (!certPem)
                 throw new NotFoundError(`certificate not found for aid: ${target}`);
             return AID._create({
@@ -427,6 +477,90 @@ export class AUNClient {
     _state = 'no_identity';
     /** 当前 AID 值对象（新 API） */
     _currentAid = null;
+    _serviceEventIdentityVersion = 0;
+    /** ownership 关系只在 SDK 内存中编排；服务端不保存状态机。 */
+    _ownershipRecords = new Map();
+    _ownershipType = 'agent';
+    _ownershipStorage = null;
+    _ownershipFiles = null;
+    _ownershipWorkflow = null;
+    _getOwnershipStorage() {
+        return this._ownershipStorage ??= new OwnershipStorageAdapter({ currentAid: () => this._aid, call: (method, params) => this.call(method, params) });
+    }
+    _getOwnershipFiles() {
+        return this._ownershipFiles ??= new OwnershipFiles({
+            currentAid: () => { if (!this._currentAid)
+                throw ownershipFailure('forbidden', 'ownership requires a loaded identity'); return this._currentAid; },
+            currentType: () => this.getType(),
+            now: () => Math.trunc(Date.now() / 1000),
+            readAgentMdFresh: (subAid) => this._agentMdManager.readOwnershipFresh(subAid),
+            submitAgentMdRaw: (subAid, raw, condition) => this._agentMdManager.submitOwnershipRaw(subAid, raw, condition),
+            readOwnerMd: (ownerAid, subAid) => this._getOwnershipStorage().readOwnerMd(ownerAid, subAid),
+            writeOwnerMd: (ownerAid, subAid, raw, revision) => this._getOwnershipStorage().writeOwnerMd(ownerAid, subAid, raw, revision),
+            deleteOwnerMd: (ownerAid, subAid, revision) => this._getOwnershipStorage().deleteOwnerMd(ownerAid, subAid, revision),
+            resolveCertificate: async (aid, fingerprint, purpose) => this._auth.resolveOwnershipCertificate(await this._resolveOwnershipCertificateGateway(aid), aid, fingerprint, purpose),
+        });
+    }
+    _getOwnershipWorkflow() {
+        return this._ownershipWorkflow ??= new OwnershipWorkflow({
+            currentAid: () => this._aid, store: this._tokenStore, files: this._getOwnershipFiles(),
+            currentType: () => this.getType(),
+            send: (to, payload) => this.call('message.send', { to, encrypt: true, payload: payload }),
+            emit: (event, payload) => this._dispatcher.enqueue(event, payload),
+        });
+    }
+    _persistOwnershipRecords() {
+        const aid = String(this._aid ?? '').trim();
+        if (!aid)
+            return;
+        const metadata = this._tokenStore.loadMetadata?.(aid) ?? {};
+        const existing = metadata.ownership_records;
+        const records = existing && typeof existing === 'object' && !Array.isArray(existing)
+            ? { ...existing } : {};
+        for (const [key, record] of this._ownershipRecords) {
+            if (![record.subject_aid, record.owner_aid].some((value) => String(value ?? '').trim().toLowerCase() === aid.toLowerCase()))
+                continue;
+            records[key] = Object.fromEntries(Object.entries(record).filter(([name]) => !['subject_identity', 'escrow_password', 'escrow_download_url'].includes(name)));
+        }
+        this._tokenStore.saveMetadata?.(aid, { ownership_records: records });
+    }
+    _restoreOwnershipRecords() {
+        const aid = String(this._aid ?? '').trim();
+        if (!aid)
+            return;
+        const metadata = this._tokenStore.loadMetadata?.(aid);
+        const intent = metadata?.registration_intent;
+        if (intent?.type)
+            this._ownershipType = String(intent.type);
+        const records = metadata?.ownership_records;
+        if (!records || typeof records !== 'object' || Array.isArray(records))
+            return;
+        for (const [key, value] of Object.entries(records)) {
+            if (!value || typeof value !== 'object' || Array.isArray(value))
+                continue;
+            const record = value;
+            this._ownershipRecords.set(key, record);
+            if (String(record.subject_aid ?? '').toLowerCase() === aid.toLowerCase())
+                this._ownershipType = String(record.type ?? this._ownershipType);
+        }
+    }
+    async _resumeOwnershipAfterConnect() {
+        await this._checkIdentityAdmissionAfterConnect();
+        await this._resumeRegistrationIntent();
+        await this._resumeOwnership();
+    }
+    async _resumeRegistrationIntent() {
+        const intent = this._tokenStore.loadMetadata?.(this._aid)?.registration_intent;
+        if (['group', 'org'].includes(String(intent?.type ?? this.getType())))
+            return;
+        if (intent?.protocol !== '2.1' || intent.pending !== true)
+            return;
+        await this._getOwnershipWorkflow().resumeRegistration(String(intent.owner), String(intent.operation_id));
+        this._tokenStore.saveMetadata?.(this._aid, { registration_intent: { ...intent, pending: false } });
+    }
+    async _resumeOwnership() {
+        await this._getOwnershipWorkflow().resume();
+    }
     /** 实例级 protected_headers */
     _instanceProtectedHeaders = null;
     /** 重连退避时间戳（ms） */
@@ -449,6 +583,7 @@ export class AUNClient {
     _transport;
     /** 认证流程 */
     _auth;
+    resolveCredentialService;
     /** 密钥存储 */
     _tokenStore;
     /** 会话参数（重连用） */
@@ -494,10 +629,17 @@ export class AUNClient {
     _pushProcessQueues = new Map();
     /** P2P pull 进行中到达的纯通知 push 上界；pull gate 释放后需要补拉一次。 */
     _pendingP2pPullUpper = new Map();
+    /** P2P pending pull 的延迟重试定时器及次数，覆盖服务端异步落库窗口。 */
+    _pendingP2pPullTimers = new Map();
+    _pendingP2pPullRetries = new Map();
     /** 缺 sender IK 时暂存原始 V2 消息，后台补齐 IK 后重试解密。 */
     _v2SenderIKPending = new Map();
     /** sender IK 后台补齐任务去重。 */
     _v2SenderIKFetching = new Set();
+    _readStateCache = new Map();
+    _readStateQueries = new Map();
+    _readStateIdentity = null;
+    _readStateGeneration = 0;
     // ── 后台任务定时器 ──────────────────────────────────────────
     _heartbeatTimer = null;
     _tokenRefreshTimer = null;
@@ -546,6 +688,8 @@ export class AUNClient {
     _mail;
     _group;
     _stream;
+    _credential;
+    _org;
     constructor(aid) {
         if (aid !== null && aid !== undefined && !isAIDObject(aid)) {
             throw new ValidationError('AUNClient only accepts an AID object or no argument');
@@ -581,7 +725,7 @@ export class AUNClient {
         if (debugFlag) {
             this._clientLog.info(`AUNClient initialized (debug=true, aunPath=${this._configModel.aunPath})`);
         }
-        this._dispatcher = new EventDispatcher(this._logger.for('aun_core.events'));
+        this._dispatcher = new EventDispatcher(this._logger.for('aun_core.events'), () => this._identity?.aid ?? '');
         const dnsNet = new DnsResilientNet({
             verifySsl: this._configModel.verifySsl,
             logger: this._clientLog,
@@ -591,6 +735,9 @@ export class AUNClient {
             logger: this._logger.for('aun_core.keystore'),
         });
         this._tokenStore = tokenStore;
+        this._ownershipStorage = null;
+        this._ownershipFiles = null;
+        this._ownershipWorkflow = null;
         this._slotId = inputAid?.slotId || 'default';
         this._connectDeliveryMode = normalizeDeliveryModeConfig({ mode: 'fanout' });
         this._defaultConnectDeliveryMode = { ...this._connectDeliveryMode };
@@ -606,6 +753,7 @@ export class AUNClient {
             net: dnsNet,
         });
         this._aid = initAid;
+        this._restoreOwnershipRecords();
         this._agentMdManager = createAgentMdManagerForRuntime({
             config: () => this._configModel,
             logger: () => this._logger.for('aun_core.agent_md'),
@@ -623,7 +771,10 @@ export class AUNClient {
             },
             auth: () => this._auth,
             tokenStore: () => this._tokenStore,
-            fetchPeerCert: (target, certFingerprint) => this._fetchPeerCert(target, certFingerprint || undefined),
+            fetchPeerCert: (target, certFingerprint, signedAt) => this._fetchPeerCert(target, certFingerprint || undefined, undefined, signedAt),
+            resolveEntityOwner: (target, type) => this._resolveEntityAgentMdOwner(target, type),
+            fetchEntityIdentity: (target, type) => this._freshEntityCertificate(target, type),
+            fetchEntitySigner: (target, fingerprint) => this._freshEntitySigner(target, fingerprint),
         });
         this._transport = new RPCTransport({
             eventDispatcher: this._dispatcher,
@@ -633,7 +784,9 @@ export class AUNClient {
             dnsNet,
         });
         this._transport.setProtocolMetaObserver((meta) => this._observeRpcMeta(meta));
+        this._transport.setServiceEventVerifier((event, payload) => verifyServiceEvent(event, payload, { targetAid: this._identity?.aid ?? '', resolveEventCertificate: (aid, fingerprint) => this._fetchServiceEventCertificate(aid, fingerprint), resolveCredentialService: this.resolveCredentialService }), () => this._identity?.aid ?? '', () => this._serviceEventIdentityVersion);
         this._transport.setProtocolDisconnectCallback((err, closeCode) => this._handleTransportDisconnect(err, closeCode));
+        this._transport._onForegroundDrained = () => this._delivery.onForegroundPullsDrained();
         this._runtime = new ClientRuntime(this);
         this._identityRuntime = new IdentityRuntimeManager(this._runtime);
         this._peerDirectory = new PeerDirectory(this._runtime);
@@ -660,6 +813,7 @@ export class AUNClient {
         this._dispatcher.subscribeProtocol('_raw.message.received', (data) => this._onRawMessageReceived(data));
         // P2P 消息撤回推送：在线 push 与 pull tombstone 去重后再发布给应用层
         this._dispatcher.subscribeProtocol('_raw.message.recalled', (data) => this._safeAsync(this._onRawMessageRecalled(data)));
+        this._dispatcher.subscribeProtocol('_raw.message.read_changed', (data) => this._onRawReadChanged(data, 'p2p'));
         // V2 P2P 推送通知：收到通知后自动走 message.v2.pull 拉取并解密
         this._dispatcher.subscribeProtocol('_raw.peer.v2.message_received', (data) => {
             const ns = this._aid ? `p2p:${this._aid}` : '';
@@ -687,6 +841,7 @@ export class AUNClient {
         this._dispatcher.subscribeProtocol('_raw.group.message_created', (data) => this._onRawGroupMessageCreated(data));
         // 群组消息撤回推送：在线 push 通道，与 pull 双 tombstone 兜底互补（SDK 去重只回调一次）
         this._dispatcher.subscribeProtocol('_raw.group.message_recalled', (data) => this._safeAsync(this._onRawGroupMessageRecalled(data)));
+        this._dispatcher.subscribeProtocol('_raw.group.read_changed', (data) => this._onRawReadChanged(data, 'group'));
         // 群组变更事件：透传并触发 V2 state/SPK 维护
         this._dispatcher.subscribeProtocol('_raw.group.changed', (data) => this._onRawGroupChanged(data));
         // 定向邀请底层事件：按群 + 目标 AID 聚合后向应用层只提示一次。
@@ -719,6 +874,16 @@ export class AUNClient {
         return sessionToken || null;
     }
     /** AUN Storage VFS 入口 */
+    get credential() {
+        if (!this._credential)
+            this._credential = new CredentialFacade(this);
+        return this._credential;
+    }
+    get org() {
+        if (!this._org)
+            this._org = new OrgFacade(this);
+        return this._org;
+    }
     get storage() {
         if (!this._storage)
             this._storage = new StorageVFS(this);
@@ -752,6 +917,88 @@ export class AUNClient {
     get currentAid() {
         return this._currentAid;
     }
+    _ownershipKey(subjectAid, ownerAid) {
+        return `${String(subjectAid ?? '').trim().toLowerCase()}|${String(ownerAid ?? '').trim().toLowerCase()}`;
+    }
+    getType() {
+        return String(this._ownershipType || 'agent').trim() || 'agent';
+    }
+    get_type() {
+        return this.getType();
+    }
+    getOwner() {
+        const aid = String(this._aid ?? '').trim().toLowerCase();
+        let best = null;
+        let bestActive = false;
+        for (const record of this._ownershipRecords.values()) {
+            if (String(record.subject_aid ?? '').trim().toLowerCase() === aid) {
+                if (String(record.status ?? '').trim().toLowerCase() === 'released')
+                    continue;
+                const owner = String(record.owner_aid ?? '').trim();
+                if (!owner)
+                    continue;
+                const active = String(record.status ?? '').trim().toLowerCase() === 'active';
+                if (!best || active && !bestActive) {
+                    best = owner;
+                    bestActive = active;
+                }
+            }
+        }
+        return best;
+    }
+    get_owner() {
+        return this.getOwner();
+    }
+    getOwnershipStatus() {
+        const aid = String(this._aid ?? '').trim().toLowerCase();
+        let best = null;
+        let bestActive = false;
+        for (const record of this._ownershipRecords.values()) {
+            const subject = String(record.subject_aid ?? '').trim().toLowerCase();
+            const owner = String(record.owner_aid ?? '').trim().toLowerCase();
+            if (aid !== subject && aid !== owner)
+                continue;
+            const active = String(record.status ?? '').trim().toLowerCase() === 'active';
+            if (!best || active && !bestActive) {
+                best = record;
+                bestActive = active;
+            }
+        }
+        if (best)
+            return Object.fromEntries(Object.entries(best).filter(([key]) => key !== 'subject_identity' && key !== 'escrow_password' && key !== 'escrow_download_url'));
+        return { subject_aid: this._aid ?? '', owner_aid: null, status: 'legacy_unbound', type: this.getType() };
+    }
+    get_ownership_status() {
+        return this.getOwnershipStatus();
+    }
+    async bindOwneraid(ownerAid) { return this._getOwnershipWorkflow().bindOwneraid(ownerAid); }
+    async bindSubaid(subAid) { return this._getOwnershipWorkflow().bindSubaid(subAid); }
+    async releaseSubaid(subAid) { return this._getOwnershipWorkflow().releaseSubaid(subAid); }
+    async transferSubaid(subAid, newOwnerAid) { return this._getOwnershipWorkflow().transferSubaid(subAid, newOwnerAid); }
+    async checkOwnershipConsensus(subAid) { return this._getOwnershipWorkflow().checkOwnershipConsensus(subAid); }
+    async bindAid(subjectAid, options = {}) {
+        throw ownershipFailure('unsupported_protocol', 'legacy bindAid is unsupported; use bindSubaid');
+    }
+    async bind_aid(subjectAid, options = {}) { return this.bindAid(subjectAid, options); }
+    async bindOwner(ownerAid, options = {}) {
+        throw ownershipFailure('unsupported_protocol', 'legacy bindOwner is unsupported; use bindOwneraid');
+    }
+    async bind_owner(ownerAid, options = {}) { return this.bindOwner(ownerAid, options); }
+    async releaseOwnership(subjectAid) { throw ownershipFailure('unsupported_protocol', 'legacy releaseOwnership is unsupported; use releaseSubaid'); }
+    async release_ownership(subjectAid) { return this.releaseOwnership(subjectAid); }
+    async acceptOwnershipRequest(operationId) {
+        return this._getOwnershipWorkflow().acceptOwnershipRequest(operationId);
+    }
+    async rejectOwnershipRequest(operationId, reason) {
+        return this._getOwnershipWorkflow().rejectOwnershipRequest(operationId, reason);
+    }
+    async _handleOwnershipMessage(message) {
+        if (!message || typeof message !== 'object' || Array.isArray(message))
+            return false;
+        const envelope = message;
+        const content = 'payload' in envelope ? envelope.payload : message;
+        return this._getOwnershipWorkflow().receive(String(envelope.from_aid ?? ''), decryptedOwnershipJsonText(content) ?? content);
+    }
     get hasIdentity() {
         return this._currentAid !== null && this.state !== ConnectionState.CLOSED;
     }
@@ -881,6 +1128,9 @@ export class AUNClient {
             logger: this._logger.for('aun_core.keystore'),
         });
         this._tokenStore = tokenStore;
+        this._ownershipStorage = null;
+        this._ownershipFiles = null;
+        this._ownershipWorkflow = null;
         this._auth = new AuthFlow({
             tokenStore,
             crypto: new CryptoProvider(),
@@ -909,7 +1159,10 @@ export class AUNClient {
             },
             auth: () => this._auth,
             tokenStore: () => this._tokenStore,
-            fetchPeerCert: (target, certFingerprint) => this._fetchPeerCert(target, certFingerprint || undefined),
+            fetchPeerCert: (target, certFingerprint, signedAt) => this._fetchPeerCert(target, certFingerprint || undefined, undefined, signedAt),
+            resolveEntityOwner: (target, type) => this._resolveEntityAgentMdOwner(target, type),
+            fetchEntityIdentity: (target, type) => this._freshEntityCertificate(target, type),
+            fetchEntitySigner: (target, fingerprint) => this._freshEntitySigner(target, fingerprint),
         });
         this._transport = new RPCTransport({
             eventDispatcher: this._dispatcher,
@@ -919,10 +1172,20 @@ export class AUNClient {
             dnsNet,
         });
         this._transport.setProtocolMetaObserver((meta) => this._observeRpcMeta(meta));
+        this._transport.setServiceEventVerifier((event, payload) => verifyServiceEvent(event, payload, { targetAid: this._identity?.aid ?? '', resolveEventCertificate: (aid, fingerprint) => this._fetchServiceEventCertificate(aid, fingerprint), resolveCredentialService: this.resolveCredentialService }), () => this._identity?.aid ?? '', () => this._serviceEventIdentityVersion);
         this._transport.setProtocolDisconnectCallback((err, closeCode) => this._handleTransportDisconnect(err, closeCode));
+        this._transport._onForegroundDrained = () => this._delivery.onForegroundPullsDrained();
     }
     loadIdentity(aid) {
+        const previousAid = this._aid;
         this._identityRuntime.loadIdentity(aid);
+        this._serviceEventIdentityVersion++;
+        this._ensureReadStateIdentity();
+        if (previousAid !== this._aid) {
+            this._ownershipRecords.clear();
+            this._ownershipType = 'agent';
+        }
+        this._restoreOwnershipRecords();
     }
     setProtectedHeaders(headers) {
         if (!headers) {
@@ -1001,7 +1264,7 @@ export class AUNClient {
     }
     /** 连接到 Gateway；身份来自构造函数或 loadIdentity(aid)，认证由 SDK 内部自动完成。 */
     async connect(opts) {
-        return this._lifecycle.connect(opts);
+        await this._lifecycle.connect(opts);
     }
     /** 关闭连接 */
     async close() {
@@ -1020,8 +1283,13 @@ export class AUNClient {
      * 自动处理内部方法限制、E2EE 加解密、客户端签名等。
      */
     async call(method, params) {
+        const readIdentity = ['message.read', 'message.read_state', 'group.read', 'group.read_state'].includes(method)
+            ? this._ensureReadStateIdentity() : null;
         try {
-            return await this._rpcPipeline.call(method, params);
+            const result = await this._rpcPipeline.call(method, params);
+            if (readIdentity !== null && readIdentity === this._ensureReadStateIdentity())
+                this._observeReadStateResult(method, result, params ?? {});
+            return result;
         }
         catch (err) {
             await this._maybeHandleHalfOpenRpcFailure(err);
@@ -1074,12 +1342,23 @@ export class AUNClient {
         const target = message.slice(agentPrefix.length).trim();
         if (!target || target.toLowerCase() !== String(this._aid ?? '').trim().toLowerCase())
             return false;
-        let agentMd = buildDefaultAgentMd(target);
+        return this._ensureInitialAgentMd();
+    }
+    async _ensureInitialAgentMd() {
+        const aid = this._aid;
+        if (!aid || !this._currentAid)
+            return false;
+        const observed = await this._getOwnershipFiles().readAgent(aid);
+        if (observed.exists)
+            return false;
+        let agentMd = buildDefaultAgentMd(aid, { type: this.getType() });
         try {
-            agentMd = this._agentMdManager.readContent(target);
+            agentMd = this._agentMdManager.readContent(aid) || agentMd;
         }
         catch { }
-        await this._agentMdManager.upload(agentMd);
+        const payload = updateOwnershipAgentMd(agentMd, {});
+        const raw = signOwnershipFile(this._currentAid, payload.endsWith('\n') || payload.endsWith('\r') ? payload : `${payload}\n`, 'agent');
+        await this._agentMdManager.submitOwnershipRaw(aid, raw, { if_none_match: '*' });
         return true;
     }
     async _checkIdentityAdmissionAfterConnect() {
@@ -1087,10 +1366,12 @@ export class AUNClient {
         if (!aid)
             return;
         try {
-            const checked = await this._agentMdManager.check(aid);
+            const checked = await this._agentMdManager.check(aid, 0);
             if (!checked.remote_found) {
-                const content = this._agentMdManager.readContent(aid) || buildDefaultAgentMd(aid);
-                await this._agentMdManager.upload(content);
+                await this._ensureInitialAgentMd();
+            }
+            else if (checked.in_sync === false) {
+                await this._agentMdManager.download(aid);
             }
         }
         catch (exc) {
@@ -1099,6 +1380,7 @@ export class AUNClient {
         const store = this._aidStore;
         if (!store)
             return;
+        await this._resumeOrgIdentityAfterConnect(store);
         let listed;
         try {
             listed = await this.call('group.list_my', {});
@@ -1135,6 +1417,8 @@ export class AUNClient {
                         await this.bindGroupAid({ group_id: groupId, group_aid: groupAid }, { aidStore: store });
                         return;
                     }
+                    if (await this._resumeGroupAgentMdUpload(store, groupAid))
+                        return;
                     const checked = await this._agentMdManager.check(groupAid);
                     if (!checked.remote_found) {
                         await this._uploadGroupAgentMd(store, groupAid, {}, {});
@@ -1165,6 +1449,192 @@ export class AUNClient {
                 this._groupIdentityOperations.delete(key);
         }
     }
+    async createOrg(params = {}, options = {}) {
+        const store = options.aidStore;
+        const owner = this._currentAid;
+        const orgAid = String(params.org_id ?? '').trim();
+        if (!store || !owner?.isPrivateKeyValid() || !orgAid)
+            throw new ValidationError('createOrg requires aidStore, org_id and current owner identity');
+        this._aidStore = store;
+        let identity = store.load(orgAid);
+        if (!identity.ok) {
+            const registered = await store.register(orgAid, { type: 'org', owner: owner.aid });
+            if (!registered.ok)
+                throw ownershipFailure('unavailable', registered.error.message, true);
+            identity = store.load(orgAid);
+        }
+        if (!identity.ok)
+            throw ownershipFailure('unavailable', identity.error.message, true);
+        const target = options.serviceAid ?? `org.${orgAid.slice(orgAid.indexOf('.') + 1)}`;
+        const tokens = store._tokenStore;
+        const inputHash = crypto.createHash('sha256').update(canonicalJson(params)).digest('hex');
+        let checkpoint = tokens.loadMetadata(orgAid)?.org_identity_creation;
+        if (checkpoint && (checkpoint.owner_aid !== owner.aid || checkpoint.input_hash !== inputHash))
+            throw ownershipFailure('conflict', 'pending Org creation context changed');
+        if (!checkpoint) {
+            const prepared = this.org.prepareRequest('org.lifecycle.create', { ...params, owner_aid: owner.aid }, target, owner, { orgSigner: identity.data.aid });
+            checkpoint = { owner_aid: owner.aid, input_hash: inputHash, source_params: params, prepared, phase: 'create' };
+            tokens.saveMetadata(orgAid, { org_identity_creation: checkpoint });
+        }
+        if (checkpoint.phase === 'create') {
+            const result = await this.call('org.lifecycle.create', checkpoint.prepared);
+            checkpoint = { ...checkpoint, result, phase: 'upload' };
+            tokens.saveMetadata(orgAid, { org_identity_creation: checkpoint });
+        }
+        await this._uploadOrgAgentMd(store, orgAid, params);
+        tokens.saveMetadata(orgAid, { org_identity_creation: null });
+        return checkpoint.result;
+    }
+    async _resumeOrgIdentityAfterConnect(store) {
+        const keyStore = store._keystore;
+        const tokens = store._tokenStore;
+        if (typeof keyStore?.listIdentities !== 'function' || typeof tokens?.loadMetadata !== 'function')
+            return;
+        for (const aid of keyStore.listIdentities()) {
+            const metadata = tokens.loadMetadata(aid);
+            const creation = metadata?.org_identity_creation;
+            const transfer = metadata?.org_identity_transfer;
+            try {
+                if (creation?.owner_aid === this._aid) {
+                    await this.createOrg(creation.source_params, { aidStore: store });
+                    continue;
+                }
+                if (transfer?.owner_aid === this._aid) {
+                    await this.completeOrgTransfer(transfer.source_params, { aidStore: store });
+                    continue;
+                }
+                const pending = store._agentMdManager.pendingUpload(aid);
+                if (!pending)
+                    continue;
+                const fields = validateAgentMdDocument(pending.content, { expectedAid: aid }).frontmatter;
+                if (fields.type === 'org' && fields.owner === this._aid)
+                    await this._resumeGroupAgentMdUpload(store, aid);
+            }
+            catch (error) {
+                this._clientLog.warn(`post-connect Org identity recovery failed: aid=${aid} err=${formatCaughtError(error)}`);
+            }
+        }
+    }
+    async completeOrgTransfer(params = {}, options = {}) {
+        const store = options.aidStore;
+        const owner = this._currentAid;
+        const orgAid = String(params.org_id ?? '').trim();
+        const transferId = String(params.transfer_id ?? '').trim();
+        if (!store || !owner?.isPrivateKeyValid() || !orgAid || !transferId)
+            throw new ValidationError('completeOrgTransfer requires aidStore, org_id, transfer_id and current accepting owner');
+        this._aidStore = store;
+        const localStore = store._keystore;
+        const tokenStore = store._tokenStore;
+        const pendingKey = `org-transfer:${orgAid}:${transferId}`;
+        const inputHash = crypto.createHash('sha256').update(canonicalJson(params)).digest('hex');
+        let keyPair = localStore.loadPendingGroupBind(pendingKey);
+        if (!keyPair) {
+            keyPair = new CryptoProvider().generateIdentity();
+            localStore.savePendingGroupBind(pendingKey, keyPair);
+        }
+        const target = options.serviceAid ?? `org.${orgAid.slice(orgAid.indexOf('.') + 1)}`;
+        const publicKey = crypto.createPublicKey({ key: Buffer.from(keyPair.public_key_der_b64, 'base64'), format: 'der', type: 'spki' }).export({ format: 'pem', type: 'spki' }).toString();
+        let pending = tokenStore.loadMetadata(orgAid)?.org_identity_transfer;
+        if (pending && (pending.transfer_id !== transferId || pending.owner_aid !== owner.aid || pending.public_key !== publicKey || pending.input_hash !== inputHash))
+            throw ownershipFailure('conflict', 'pending Org transfer context changed');
+        if (!pending) {
+            const rekey = { ...params, stage: 'rekey', public_key: publicKey, curve: 'P-256' };
+            delete rekey.new_owner;
+            delete rekey.request_binding;
+            delete rekey.client_signature;
+            pending = { transfer_id: transferId, owner_aid: owner.aid, public_key: publicKey, input_hash: inputHash, phase: 'rekey', source_params: params, rekey_params: this.org.prepareRequest('org.lifecycle.transferAccept', rekey, target, owner) };
+            tokenStore.saveMetadata(orgAid, { org_identity_transfer: pending });
+        }
+        if (pending.phase === 'rekey') {
+            const result = await this.call('org.lifecycle.transferAccept', pending.rekey_params);
+            pending = { ...pending, phase: 'finalize', rekey_result: result };
+            tokenStore.saveMetadata(orgAid, { org_identity_transfer: pending });
+        }
+        const rekeyResult = pending.rekey_result;
+        const certPem = String(rekeyResult?.cert_pem ?? rekeyResult?.cert ?? '').trim();
+        if (!certPem)
+            throw ownershipFailure('unavailable', 'Org rekey response has no certificate', true);
+        const imported = store.importGroupIdentity(orgAid, { ...keyPair, cert_pem: certPem });
+        if (!imported.ok)
+            throw ownershipFailure('invalid', imported.error.message);
+        const orgIdentity = this._localEntityCertificate(orgAid);
+        if (!pending.finalize_params) {
+            const final = { ...pending.source_params, stage: 'finalize', public_key: publicKey, curve: 'P-256', request_id: crypto.randomUUID().replace(/-/g, ''), nonce: crypto.randomBytes(32).toString('base64url') };
+            delete final.request_binding;
+            delete final.client_signature;
+            for (const field of ['previous_owner', 'new_owner']) {
+                const material = isJsonObject(final[field]) ? final[field] : {};
+                let binding = isJsonObject(material.membership_binding) ? material.membership_binding : undefined;
+                if (!binding || !isJsonObject(material.terms))
+                    throw ownershipFailure('invalid', 'Org transfer requires both replacement membership bindings and terms');
+                if (!binding.member_signature && binding.member_aid === owner.aid)
+                    binding = signMembershipBinding(binding, owner, 'member');
+                binding = signMembershipBinding(binding, orgIdentity, 'org');
+                const oldCredential = isJsonObject(material.credential_template) ? { ...material.credential_template } : undefined;
+                if (oldCredential) {
+                    delete oldCredential.signature;
+                    oldCredential.key_version = orgIdentity.certFingerprint;
+                }
+                const credential = oldCredential ? createCredential(oldCredential, orgIdentity) : createMemberCredential(binding, orgIdentity, { key_version: orgIdentity.certFingerprint });
+                final[field] = { ...material, membership_binding: binding, credential_template: credential };
+                delete final[field].registration_authorization;
+            }
+            pending = { ...pending, finalize_params: this.org.prepareRequest('org.lifecycle.transferAccept', final, target, owner, { orgSigner: orgIdentity }) };
+            tokenStore.saveMetadata(orgAid, { org_identity_transfer: pending });
+        }
+        const result = await this.call('org.lifecycle.transferAccept', pending.finalize_params);
+        await this._uploadOrgAgentMd(store, orgAid, pending.source_params);
+        localStore.clearPendingGroupBind(pendingKey);
+        tokenStore.saveMetadata(orgAid, { org_identity_transfer: null });
+        return result;
+    }
+    async dissolveOrg(params = {}, options = {}) {
+        const store = options.aidStore ?? this._aidStore;
+        if (store)
+            this._aidStore = store;
+        const orgAid = String(params.org_id ?? '').trim();
+        const owner = this._currentAid;
+        const target = options.serviceAid ?? `org.${orgAid.slice(orgAid.indexOf('.') + 1)}`;
+        const payload = owner ? this.org.prepareRequest('org.lifecycle.dissolve', params, target, owner) : params;
+        const result = await this.call('org.lifecycle.dissolve', payload);
+        const organization = isJsonObject(result?.organization) ? result.organization : {};
+        const status = String(organization.status ?? result?.status ?? '');
+        if (store && orgAid && status === 'dissolved') {
+            const tokenStore = store._tokenStore;
+            const keyStore = store._keystore;
+            const certPem = keyStore?.loadCert?.(orgAid);
+            const metadata = tokenStore?.loadMetadata?.(orgAid) ?? {};
+            const transfer = metadata.org_identity_transfer;
+            if (transfer?.transfer_id && typeof keyStore?.clearPendingGroupBind === 'function') {
+                keyStore.clearPendingGroupBind(`org-transfer:${orgAid}:${String(transfer.transfer_id)}`);
+            }
+            tokenStore?.saveMetadata?.(orgAid, {
+                ...(certPem ? { invalidated_entity_certificate: certFingerprint(certPem) } : {}),
+                org_identity_creation: undefined,
+                org_identity_transfer: undefined,
+            });
+            tokenStore?.saveInstanceState?.(orgAid, store.deviceId, store.slotId, {});
+            store._agentMdManager?.saveRecord?.(orgAid, {
+                pending_operation: '', pending_content: '', pending_content_etag: '', pending_error: '',
+                pending_condition: {}, pending_relation: {}, pending_authorization: '',
+            });
+        }
+        return result;
+    }
+    async _uploadOrgAgentMd(store, orgAid, params) {
+        const owner = this._currentAid;
+        if (!owner)
+            throw ownershipFailure('forbidden', 'Org agent.md requires current owner');
+        if (await this._resumeGroupAgentMdUpload(store, orgAid))
+            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') });
+        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');
+        }
+    }
     async createGroup(params = {}, options = {}) {
         if (!isJsonObject(params)) {
             throw new ValidationError('createGroup params must be an object');
@@ -1333,6 +1803,8 @@ export class AUNClient {
             `name: ${JSON.stringify(name)}`,
             'type: "group"',
             'version: "1.0.0"',
+            `owner: ${JSON.stringify(String(group.owner_aid ?? group.owner ?? this._aid ?? ''))}`,
+            `entity_cert_fingerprint: ${JSON.stringify(this._localEntityCertificate(groupAid).certFingerprint)}`,
             `description: ${JSON.stringify(description)}`,
             ...(avatar ? [`avatar: ${JSON.stringify(avatar)}`] : []),
             '---',
@@ -1341,16 +1813,71 @@ export class AUNClient {
             '',
         ].join('\n');
     }
+    async _resumeGroupAgentMdUpload(store, groupAid) {
+        const identityStore = store;
+        const pendingManager = identityStore._agentMdManager ?? this._agentMdManager;
+        const pending = pendingManager.pendingUpload(groupAid);
+        if (!pending)
+            return false;
+        const fields = validateAgentMdDocument(pending.content, { expectedAid: groupAid, validateOwnership: false }).frontmatter;
+        if (['ownership', 'ownership_proof', 'ownership_release'].some((field) => Object.hasOwn(fields, field))) {
+            throw new StateError('ownership pending agent.md requires its persisted 2.1 task', { stringCode: 'unsupported_protocol' });
+        }
+        const identity = this._currentAid;
+        if (!identity || fields.owner !== identity.aid)
+            throw ownershipFailure('forbidden', 'group agent.md recovery requires its original current owner');
+        const manager = new AgentMdManager({
+            aunPath: store.aunPath,
+            verifySsl: identityStore._verifySsl,
+            logger: identityStore._log.for('aun_core.agent_md'),
+            uploadViaGatewayHost: true,
+            ownerAidGetter: () => identity.aid,
+            currentAidGetter: () => identity,
+            entityOwnerResolver: (aid, type) => this._resolveEntityAgentMdOwner(aid, type),
+            entityIdentityGetter: (aid, type) => this._freshEntityCertificate(aid, type),
+            entitySignerResolver: (aid, fingerprint) => this._freshEntitySigner(aid, fingerprint),
+            gatewayResolver: (aid) => identityStore._resolveGateway(aid),
+            accessTokenResolver: (_aid, gatewayUrl) => identityStore._uploadAgentMdToken(identity, gatewayUrl),
+            aidValidator: (aid) => identityStore._registerFlow.validateAidName(aid),
+        });
+        return await manager.resumePendingUpload(groupAid);
+    }
     async _uploadGroupAgentMd(store, groupAid, params, group) {
         const uploaderAid = String(this._aid ?? '').trim();
         if (!uploaderAid) {
             throw new ValidationError('group agent.md upload requires current owner AID');
         }
-        const uploaded = await store.uploadAgentMd(groupAid, this._groupAgentMdContent(groupAid, params, group), { uploaderAid });
+        this._aidStore = store;
+        if (await this._resumeGroupAgentMdUpload(store, groupAid))
+            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) });
         if (!uploaded.ok) {
-            throw new ValidationError(`group agent.md upload failed: ${uploaded.error.message}`);
+            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');
         }
     }
+    _localEntityCertificate(aid) {
+        const loaded = this._aidStore?.load(aid);
+        if (!loaded?.ok)
+            throw ownershipFailure('unavailable', 'entity local certificate is unavailable', true);
+        return loaded.data.aid;
+    }
+    async _freshEntityCertificate(aid, type = 'group') {
+        const material = await this._auth.resolveCurrentEntityCertificate(await this._resolveOwnershipCertificateGateway(aid), aid, type);
+        const certPem = material.cert_pem;
+        return AID._create({ aid, aunPath: this._configModel.aunPath, certPem, certValid: true, privateKeyPem: null, privateKeyValid: false });
+    }
+    async _freshEntitySigner(aid, fingerprint) {
+        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);
+        const identity = await this._freshEntityCertificate(aid, type);
+        if (authority.entity_cert_fingerprint !== identity.certFingerprint)
+            throw ownershipFailure('conflict', 'entity authority changed during current-certificate verification');
+        return authority.owner_aid;
+    }
     async bindGroupAid(params = {}, options = {}) {
         if (!isJsonObject(params)) {
             throw new ValidationError('bindGroupAid params must be an object');
@@ -1788,6 +2315,168 @@ export class AUNClient {
         this._clientLog.debug(`on exit: elapsed=${Date.now() - tStart}ms event=${event}`);
         return result;
     }
+    _readStateIsNewer(previous, current) {
+        if (!previous)
+            return true;
+        const oldOrder = BigInt(String(previous.last_read_order ?? 0));
+        const newOrder = BigInt(String(current.last_read_order ?? 0));
+        if (oldOrder !== newOrder)
+            return newOrder > oldOrder;
+        const oldId = String(previous.last_read_message_id ?? '');
+        const newId = String(current.last_read_message_id ?? '');
+        if (oldOrder === 0n)
+            return newId === oldId;
+        const oldPoints = Array.from(oldId);
+        const newPoints = Array.from(newId);
+        for (let index = 0; index < Math.min(oldPoints.length, newPoints.length); index++) {
+            const oldPoint = oldPoints[index].codePointAt(0);
+            const newPoint = newPoints[index].codePointAt(0);
+            if (oldPoint !== newPoint)
+                return newPoint > oldPoint;
+        }
+        return newPoints.length >= oldPoints.length;
+    }
+    _ensureReadStateIdentity() {
+        const identity = `${this._aid ?? ''}\u0000${this._deviceId ?? ''}`;
+        if (identity !== this._readStateIdentity) {
+            this._readStateCache.clear();
+            this._readStateQueries.clear();
+            this._readStateIdentity = identity;
+            this._readStateGeneration += 1;
+        }
+        return `${identity}\u0000${this._readStateGeneration}`;
+    }
+    _registerReadStateQuery(method, params) {
+        const key = method + '\u0000' + JSON.stringify(Object.keys(params).sort().map((field) => [field, params[field]]));
+        this._readStateQueries.set(key, { method, params: { ...params } });
+    }
+    _readStateItems(result) {
+        const resultObject = isJsonObject(result) ? result : null;
+        return Array.isArray(resultObject?.states)
+            ? resultObject.states.filter((item) => isJsonObject(item))
+            : [];
+    }
+    _observeReadStateResult(method, result, params) {
+        if (!['message.read', 'message.read_state', 'group.read', 'group.read_state'].includes(method))
+            return;
+        this._ensureReadStateIdentity();
+        const isGroup = method.startsWith('group.');
+        if (method.endsWith('.read')) {
+            for (const state of this._readStateItems(params)) {
+                const query = { topic_key: state.topic_key ?? '' };
+                if (isGroup)
+                    query.group_id = state.group_id ?? params.group_id ?? '';
+                else
+                    query.scope = state.scope || params.scope || 'p2p';
+                this._registerReadStateQuery(`${isGroup ? 'group' : 'message'}.read_state`, query);
+            }
+            if (!Array.isArray(params.states) && params.topic_key) {
+                const query = {};
+                for (const field of ['scope', 'group_id', 'topic_key']) {
+                    if (field in params)
+                        query[field] = params[field];
+                }
+                this._registerReadStateQuery(`${isGroup ? 'group' : 'message'}.read_state`, query);
+            }
+            return;
+        }
+        this._registerReadStateQuery(method, params);
+        for (const state of this._readStateItems(result)) {
+            const scope = String(state.scope ?? (isGroup ? 'group' : 'p2p')).trim();
+            const topicKey = String(state.topic_key ?? params.topic_key ?? '');
+            const groupId = isGroup ? String(state.group_id ?? params.group_id ?? '').trim() : '';
+            const lastRead = String(state.last_read_message_id ?? '').trim();
+            if (!scope || !topicKey || !lastRead || (isGroup && !groupId))
+                continue;
+            const key = `${scope}\u0000${groupId}\u0000${topicKey}`;
+            const query = { topic_key: topicKey };
+            if (isGroup)
+                query.group_id = groupId;
+            else
+                query.scope = scope;
+            const previous = this._readStateCache.get(key)?.state;
+            if (previous && !this._readStateIsNewer(previous, state))
+                continue;
+            const samePosition = previous?.last_read_message_id === state.last_read_message_id
+                && BigInt(String(previous?.last_read_order ?? 0)) === BigInt(String(state.last_read_order ?? 0));
+            this._readStateCache.set(key, {
+                method: `${isGroup ? 'group' : 'message'}.read_state`,
+                params: query,
+                state: samePosition ? { ...previous, ...state } : { ...state },
+            });
+        }
+    }
+    _onRawReadChanged(data, expectedScope) {
+        if (!isJsonObject(data))
+            return;
+        const eventData = data;
+        if (eventData.scope !== expectedScope || eventData.owner_aid !== this._aid)
+            return;
+        const fields = ['owner_aid', 'topic_key', 'last_read_message_id', ...(expectedScope === 'group' ? ['group_id'] : [])];
+        if (fields.some((field) => {
+            const value = eventData[field];
+            return typeof value !== 'string' || !value || Array.from(value).length > 128;
+        }))
+            return;
+        const order = eventData.last_read_order;
+        if (!(typeof order === 'number' && Number.isSafeInteger(order) && order > 0)
+            && !(typeof order === 'string' && /^[1-9]\d*$/.test(order)))
+            return;
+        this._ensureReadStateIdentity();
+        const scope = expectedScope;
+        const topicKey = String(eventData.topic_key ?? '');
+        const groupId = scope === 'group' ? String(eventData.group_id) : '';
+        const lastRead = String(eventData.last_read_message_id);
+        if (scope && topicKey && lastRead && (scope !== 'group' || groupId)) {
+            const key = `${scope}\u0000${groupId}\u0000${topicKey}`;
+            const query = { topic_key: topicKey };
+            if (scope === 'group')
+                query.group_id = groupId;
+            else
+                query.scope = scope;
+            const method = `${scope === 'group' ? 'group' : 'message'}.read_state`;
+            this._registerReadStateQuery(method, query);
+            const previous = this._readStateCache.get(key)?.state;
+            if (previous && (!this._readStateIsNewer(previous, eventData)
+                || (previous.last_read_message_id === eventData.last_read_message_id
+                    && BigInt(String(previous.last_read_order ?? 0)) === BigInt(String(eventData.last_read_order ?? 0)))))
+                return;
+            this._readStateCache.set(key, { method, params: query, state: { ...eventData } });
+        }
+        this._dispatcher.enqueue(scope === 'group' ? 'group.read_changed' : 'message.read_changed', eventData);
+    }
+    async _reconcileReadStates() {
+        const identity = this._ensureReadStateIdentity();
+        const keys = new Set();
+        const errors = [];
+        for (const entry of [...this._readStateQueries.values()]) {
+            try {
+                const result = await this.call(entry.method, { ...entry.params });
+                if (identity !== this._ensureReadStateIdentity())
+                    return;
+                this._observeReadStateResult(entry.method, result, entry.params);
+                for (const state of this._readStateItems(result)) {
+                    const scope = String(state.scope ?? (entry.method.startsWith('group.') ? 'group' : 'p2p'));
+                    const groupId = scope === 'group' ? String(state.group_id ?? entry.params.group_id ?? '') : '';
+                    const topicKey = String(state.topic_key ?? entry.params.topic_key ?? '');
+                    const key = `${scope}\u0000${groupId}\u0000${topicKey}`;
+                    if (this._readStateCache.has(key))
+                        keys.add(key);
+                }
+            }
+            catch (error) {
+                errors.push({ method: entry.method, params: { ...entry.params }, error: error instanceof Error ? error.message : String(error) });
+                this._clientLog.debug(`read state reconnect reconciliation failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            if (identity !== this._ensureReadStateIdentity())
+                return;
+        }
+        this._dispatcher.enqueue('read_state_sync', {
+            owner_aid: this._aid ?? '',
+            states: [...keys].map((key) => ({ ...this._readStateCache.get(key).state })),
+            errors,
+        });
+    }
     async _callRawV2Rpc(method, params, pullGateKey = '') {
         const p = { ...(params ?? {}) };
         const forceForeground = Boolean(p._rpc_foreground);
@@ -1876,6 +2565,7 @@ export class AUNClient {
         const previous = this._pendingP2pPullUpper.get(ns) ?? 0;
         if (seq > previous) {
             this._pendingP2pPullUpper.set(ns, seq);
+            this._pendingP2pPullRetries.delete(ns);
         }
         this._clientLog.debug(`P2P pending pull upper recorded: ns=${ns}, seq=${seq}, previous=${previous}, contiguous=${this._seqTracker.getContiguousSeq(ns)}`);
     }
@@ -1890,6 +2580,7 @@ export class AUNClient {
         const contig = this._seqTracker.getContiguousSeq(ns);
         if (upperSeq <= contig) {
             this._pendingP2pPullUpper.delete(ns);
+            this._pendingP2pPullRetries.delete(ns);
             this._clientLog.debug(`P2P pending pull upper already covered: ns=${ns}, upper_seq=${upperSeq}, contiguous=${contig}, reason=${reason}`);
             return false;
         }
@@ -1897,18 +2588,63 @@ export class AUNClient {
             this._clientLog.debug(`P2P pending pull postponed: ns=${ns}, upper_seq=${upperSeq}, contiguous=${contig}, state=${this._state}, closing=${this._closing}, reason=${reason}`);
             return false;
         }
-        if (this._rpcPipeline?.hasPullActivity?.(ns, false))
+        if (this._sessionOptions.background_sync === false)
+            return false;
+        if (this._rpcPipeline?.hasPullActivity?.(ns, false) || this._pendingP2pPullTimers.has(ns))
+            return false;
+        const retries = (this._pendingP2pPullRetries.get(ns) ?? 0) + 1;
+        if (retries > PENDING_P2P_PULL_MAX_RETRIES) {
+            this._pendingP2pPullUpper.delete(ns);
+            this._pendingP2pPullRetries.delete(ns);
+            this._clientLog.warn(`P2P pending pull retries exhausted: ns=${ns}, upper_seq=${upperSeq}, contiguous=${contig}, reason=${reason}`);
             return false;
-        this._pendingP2pPullUpper.delete(ns);
-        this._clientLog.info(`P2P pending push follow-up pull scheduled: ns=${ns}, upper_seq=${upperSeq}, contiguous=${contig}, reason=${reason}`);
-        this._safeAsync(this._onV2PushNotification({ seq: upperSeq }, 'v2'));
+        }
+        this._pendingP2pPullRetries.set(ns, retries);
+        this._clientLog.info(`P2P pending push follow-up pull scheduled: ns=${ns}, upper_seq=${upperSeq}, contiguous=${contig}, retry=${retries}, reason=${reason}`);
+        const timer = setTimeout(() => {
+            this._pendingP2pPullTimers.delete(ns);
+            const currentUpper = this._pendingP2pPullUpper.get(ns) ?? 0;
+            if (currentUpper <= 0 || currentUpper <= this._seqTracker.getContiguousSeq(ns)) {
+                this._pendingP2pPullUpper.delete(ns);
+                this._pendingP2pPullRetries.delete(ns);
+                return;
+            }
+            // 暂时移除上界，避免 synthetic push 被 hasPullActivity 当成自身的 pending pull 拦截。
+            this._pendingP2pPullUpper.delete(ns);
+            const retry = this._onV2PushNotification({ seq: currentUpper }, 'v2')
+                .then(() => {
+                if (this._seqTracker.getContiguousSeq(ns) < currentUpper) {
+                    const pending = this._pendingP2pPullUpper.get(ns) ?? 0;
+                    if (currentUpper > pending)
+                        this._pendingP2pPullUpper.set(ns, currentUpper);
+                }
+            })
+                .catch((error) => {
+                const pending = this._pendingP2pPullUpper.get(ns) ?? 0;
+                if (currentUpper > pending)
+                    this._pendingP2pPullUpper.set(ns, currentUpper);
+                throw error;
+            })
+                .finally(() => {
+                this._schedulePendingP2pPullIfNeeded(ns, 'pending-pull-retry-complete');
+            });
+            this._safeAsync(retry);
+        }, PENDING_P2P_PULL_DELAY_MS);
+        this._pendingP2pPullTimers.set(ns, timer);
         return true;
     }
     _markPublishedSeq(ns, seq) {
         this._delivery.markPublishedSeq(ns, seq);
     }
-    _publishAppEvent(event, payload, source = 'direct') {
-        return this._delivery.publishAppEvent(event, payload, source);
+    _publishAppEvent(event, payload, source = 'direct', deliveryContext) {
+        if (event === 'message.received') {
+            return this._handleOwnershipMessage(payload).then((handled) => {
+                if (!handled)
+                    return this._delivery.publishAppEvent(event, payload, source, deliveryContext);
+                return undefined;
+            });
+        }
+        return this._delivery.publishAppEvent(event, payload, source, deliveryContext);
     }
     _echoTimestamp() {
         const now = new Date();
@@ -2087,8 +2823,8 @@ export class AUNClient {
         }
         return true;
     }
-    async _drainOrderedMessages(ns, beforeSeq, pullResponse = false, persist = true, source = 'push') {
-        return this._delivery.drainOrderedMessages(ns, beforeSeq, pullResponse, persist, source);
+    async _drainOrderedMessages(ns, beforeSeq, pullResponse = false, persist = true, source = 'push', throughSeq) {
+        return this._delivery.drainOrderedMessages(ns, beforeSeq, pullResponse, persist, source, undefined, throughSeq);
     }
     async _publishOrderedMessage(event, ns, seq, payload, source = 'push') {
         return this._delivery.publishOrderedMessage(event, ns, seq, payload, source);
@@ -2213,6 +2949,10 @@ export class AUNClient {
             }
             const paramsHash = String(cs.params_hash ?? '');
             const timestamp = String(cs.timestamp ?? '');
+            const signedAt = Number(timestamp) * 1000;
+            if (!/^\d+$/.test(timestamp) || !Number.isSafeInteger(Number(timestamp)) || signedAt < new Date(certObj.validFrom).getTime() || signedAt > new Date(certObj.validTo).getTime()) {
+                return false;
+            }
             const signData = Buffer.from(`${method}|${sigAid}|${timestamp}|${paramsHash}`, 'utf-8');
             const sigB64 = String(cs.signature ?? '');
             const pubKey = certObj.publicKey;
@@ -2273,7 +3013,10 @@ export class AUNClient {
             }
         }
         try {
-            await this._auth.verifyPeerCertificate(peerGatewayUrl, certPem, aid);
+            if (opts.signedAt === undefined)
+                await this._auth.verifyPeerCertificate(peerGatewayUrl, certPem, aid);
+            else
+                await this._auth.verifyPeerCertificate(peerGatewayUrl, certPem, aid, opts.signedAt);
         }
         catch (exc) {
             if (cachedBootstrapChain) {
@@ -2287,9 +3030,9 @@ export class AUNClient {
             validatedAt: nowSec,
             refreshAfter: nowSec + PEER_CERT_CACHE_TTL,
         };
-        const cacheKey = AUNClient._certCacheKey(aid, certFingerprint);
+        const cacheKey = AUNClient._certCacheKey(aid, certFingerprint) + (opts.signedAt === undefined ? '' : `:signed:${opts.signedAt}`);
         this._certCache.set(cacheKey, entry);
-        if (!certFingerprint) {
+        if (!certFingerprint && opts.signedAt === undefined) {
             const bareKey = AUNClient._certCacheKey(aid);
             this._certCache.set(bareKey, entry);
             const actualFp = `sha256:${x509Cert.fingerprint256.replace(/:/g, '').toLowerCase()}`;
@@ -2304,12 +3047,19 @@ export class AUNClient {
         }
         return certPem;
     }
+    async _fetchServiceEventCertificate(aid, fingerprint) {
+        const certificate = await this._fetchPeerCert(aid, fingerprint);
+        if (!this._gatewayUrl)
+            throw new ValidationError('gateway url unavailable for service event certificate validation');
+        await this._auth.verifyPeerCertificate(AUNClient._resolvePeerGatewayUrl(this._gatewayUrl, aid), certificate, aid, undefined, true);
+        return certificate;
+    }
     /** 获取对方证书（带缓存 + 完整 PKI 验证），跨域时自动路由到 peer 所在域。 */
-    async _fetchPeerCert(aid, certFingerprint, timeoutMs = 30_000) {
+    async _fetchPeerCert(aid, certFingerprint, timeoutMs = 30_000, signedAt) {
         const tStart = Date.now();
         this._clientLog.debug(`_fetchPeerCert enter: aid=${aid}, fp=${certFingerprint ?? ''}`);
         try {
-            const cacheKey = AUNClient._certCacheKey(aid, certFingerprint);
+            const cacheKey = AUNClient._certCacheKey(aid, certFingerprint) + (signedAt === undefined ? '' : `:signed:${signedAt}`);
             const cached = this._certCache.get(cacheKey);
             const now = Date.now() / 1000;
             if (cached && now < cached.refreshAfter) {
@@ -2327,6 +3077,7 @@ export class AUNClient {
                 certPem,
                 certFingerprint,
                 source: 'fetch',
+                signedAt,
             });
             this._clientLog.debug(`_fetchPeerCert exit: elapsed=${Date.now() - tStart}ms aid=${aid} (fetched)`);
             return validated;
@@ -2441,6 +3192,10 @@ export class AUNClient {
         this._pushedSeqs.clear();
         this._pendingOrderedMsgs.clear();
         this._pendingP2pPullUpper.clear();
+        for (const timer of this._pendingP2pPullTimers.values())
+            clearTimeout(timer);
+        this._pendingP2pPullTimers.clear();
+        this._pendingP2pPullRetries.clear();
         this._v2SenderIKPending.clear();
         this._v2SenderIKFetching.clear();
         this._groupSynced.clear();
@@ -2457,6 +3212,10 @@ export class AUNClient {
         this._pushedSeqs.clear();
         this._pendingOrderedMsgs.clear();
         this._pendingP2pPullUpper.clear();
+        for (const timer of this._pendingP2pPullTimers.values())
+            clearTimeout(timer);
+        this._pendingP2pPullTimers.clear();
+        this._pendingP2pPullRetries.clear();
         this._v2SenderIKPending.clear();
         this._v2SenderIKFetching.clear();
         this._groupSynced.clear();
@@ -2851,6 +3610,7 @@ export class AUNClient {
             }
             this._lifecycle.assertConnectionAttemptOwner(connectionOwner);
             this._startBackgroundTasks();
+            this._safeAsync(this._reconcileReadStates());
             const connectionKind = String(params.connection_kind ?? 'long');
             const isShortConnection = connectionKind === 'short';
             const hasExplicitBackgroundSync = Object.prototype.hasOwnProperty.call(params, 'background_sync');
@@ -2877,7 +3637,7 @@ export class AUNClient {
                     this._clientLog.warn(`schedule post-connect P2P gap fill failed: ${formatCaughtError(exc)}`);
                 });
             }
-            this._safeAsync(this._checkIdentityAdmissionAfterConnect());
+            this._safeAsync(this._resumeOwnershipAfterConnect());
             this._clientLog.debug(`_connectOnce exit: elapsed=${Date.now() - tStart}ms gateway=${gatewayUrl}, aid=${this._aid ?? ''}`);
         }
         catch (err) {
@@ -3276,10 +4036,15 @@ export class AUNClient {
             encrypted: true,
             e2ee,
         };
+        if (typeof plaintext.type === 'string' && plaintext.type.startsWith('aun.ownership.'))
+            result.from_aid = fromAid;
         if (senderDeviceId)
             result.sender_device_id = senderDeviceId;
         const explicitDirection = String(msg.direction ?? '').trim();
-        result.direction = explicitDirection || (fromAid && fromAid === this._aid ? 'outbound_sync' : 'inbound');
+        if (explicitDirection)
+            result.direction = explicitDirection;
+        else if (fromAid && fromAid !== this._aid)
+            result.direction = 'inbound';
         if (msg.device_id !== undefined)
             result.device_id = msg.device_id;
         attachGatewayProximity(result, msg);
@@ -3478,14 +4243,30 @@ export class AUNClient {
         return this._delivery.onRawGroupV2MessageCreated(data, expectedVersion, inlineGeneration);
     }
     /** Push 通知带 payload 时的就地解密（复用 _decryptV2Message） */
-    async _decryptV2PushMessage(data) {
-        return await this._v2E2EE.decryptV2PushMessage(data);
+    async _decryptV2PushMessage(data, deferStatus) {
+        return await this._v2E2EE.decryptV2PushMessage(data, deferStatus);
     }
     /** 按当前 AID 发现 Gateway；用于 authenticate()/connect() 的新入口。 */
     async _resolveGatewayForAid(aid) {
         const gateways = await this._resolveGatewayCandidatesForAid(aid);
         return gateways[0];
     }
+    async _resolveOwnershipCertificateGateway(aid) {
+        const issuer = aid.slice(aid.indexOf('.') + 1);
+        if (issuer === this._aid?.slice(this._aid.indexOf('.') + 1))
+            return this._resolveGatewayForAid(aid);
+        const port = this._configModel.discoveryPort ? `:${this._configModel.discoveryPort}` : '';
+        let lastError;
+        for (const host of [aid, `gateway.${issuer}`]) {
+            try {
+                return await this._discovery.discover(`https://${host}${port}/.well-known/aun-gateway`);
+            }
+            catch (error) {
+                lastError = error;
+            }
+        }
+        throw ownershipFailure('unavailable', lastError instanceof Error ? lastError.message : 'signer Gateway discovery failed', true);
+    }
     /** 发现并缓存全部 Gateway 候选，供首连和自动重连故障转移使用。 */
     async _resolveGatewayCandidatesForAid(aid) {
         const resolvedAid = String(aid ?? this._aid ?? '').trim();