@agentunion/fastaun 0.5.22 → 0.5.23

package/_packed_docs/INDEX.md

@@ -10,7 +10,7 @@
 | --- | --- |
 | [0.5.21 SDK 应用集成指南](sdk/0.5.21-SDK应用集成指南.md) | TypeScript 应用接入、batch 持久幂等、peer 同步、resolve/owner 展示、关系审批、凭证续期、诊断与升级验收 |
 | [0.5.21 SDK 开发与移植指南](sdk/0.5.21-SDK开发与移植指南.md) | 四端公开契约、peer 水位、流控与提交边界、frontmatter/共识缓存、原 CAS 和旧任务、checkpoint、语言差异及验收顺序 |
-| [0.5.22 SDK 应用集成指南](sdk/0.5.22-SDK应用集成指南.md) | TypeScript 接入、消息订阅、两种绑定与审批恢复、resolve 展示、60 秒读缓存与刷新、撤销同步和组织完整成员包 |
+| [0.5.22 SDK 应用集成指南](sdk/0.5.22-SDK应用集成指南.md) / [注册自动绑定 Owner E2E](TS注册自动绑定Owner的E2E验证代码.md) | TypeScript 接入、消息订阅、两种绑定与审批恢复、resolve 展示、60 秒读缓存与刷新、撤销同步和组织完整成员包 |
 | [0.5.22 SDK 开发与移植指南](sdk/0.5.22-SDK开发与移植指南.md) | 后台退避、群状态、两种绑定与 Stage/CAS、消息内部消费、撤销同步、组织恢复及配套服务修复、默认读缓存、Rust 移植与验收 |
 | [aun测试运行指南](aun测试运行指南.md) | `agentid.pub/agentid.cn` 双域本地单实例、MySQL 命名卷/bind 核验、独立固定材料与 Tester、Go 1.24、断网 cross-SDK、缓存专项首失败续跑、三文件线上镜像替换包、开箱默认配置、一次性初始化辅助包及单节点部署 |
 | [aun公网测试运行指南](aun公网测试运行指南.md) | 可配置 issuer domain 的 Python SDK 公网 integration/E2E runner、独立身份/运行目录、TLS 与服务端公网验收衔接 |
@@ -463,3 +463,7 @@ Group/Org 作为 sub 时不进入这些通用任务或审批；以其为 sub 误
 ### AUN 离线推送 Push Service
 
 设计文档定义独立 Go Push Service 的职责、通信平面、持久状态机、在线复核、批次投递、故障恢复、安全和三中心纳管；Python `connect()` 把 `push_notify_aid/push_token` 映射为显式 `push.register`，运行期通过 PushFacade 登记或注销，认证协议本身不扩展字段。[接入与演示指南](AUN离线推送接入与演示指南.md)从终端、Push Server 两侧给出 token、长连接、幂等 ACK、Mock smoke 和排障路径。[离线推送通知协议](protocol/15-离线推送通知协议.md)给出对外字段和可靠性边界。契约冻结文档固定确定 Session、批次级 ACK、不可变 membership、candidate 汇总、恢复、Gateway ACL 和关闭顺序。v4 计划只定义范围、依赖和验收，Task TDD 在实施时展开。[运维与发布指南](AUN离线推送服务运维与发布指南.md)补充发布门、身份材料、Mock Python SDK 应用层恢复、灰度和回滚，并明确生产仍受 token 加密硬阻断。旧 Codex 文档只作为历史背景。
+
+### TS 注册自动绑定 Owner 的 E2E 验证代码
+
+[代码与运行方式](TS注册自动绑定Owner的E2E验证代码.md)：TS SDK 编译产物的 Node.js ESM 用例，覆盖注册意图、connect 自动发起 bind.request、owner 审批、双端锁定共识、NS/Storage 正文及 SHA；包含 agentid.cn 实测结果和私有探针/transport 范围。

package/_packed_docs/KITE_DOCS_GUIDE.md

@@ -34,6 +34,7 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 | 0.5.21 应用开发者：TypeScript 接入、消息入库、resolve/owner、凭证组织、诊断和升级 | `docs/sdk/0.5.21-SDK应用集成指南.md` 1. L7-20；2. L21-79；3. L80-175；4. L176-228；5. L229-263；6. L264-311；7. L312-334；8. L335-356；9. L357-368 |
 | 0.5.21 SDK 开发者：peer/batch 提交、元数据与共识缓存、原件恢复、语言差异和验收 | `docs/sdk/0.5.21-SDK开发与移植指南.md` 1. L7-21；2. L22-45；3. L46-96；4. L97-156；5. L157-212；6. L213-228；7. L229-265；8. L266-295；9. L296-303；10. L304-319；11. L320-332；12. L333-350 |
 | 0.5.22 应用集成：TypeScript 接线、审批恢复、resolve、缓存及凭证组织 | `docs/sdk/0.5.22-SDK应用集成指南.md` 1. L5-13；2. L14-35；3. L36-54；4. L55-104；5. L105-127；6. L128-164；7. L165-200；8. L201-212 |
+| TypeScript 注册自动绑定 Owner E2E 代码 | [代码 L9-172、运行 L174-192、实测 L194-196](TS注册自动绑定Owner的E2E验证代码.md)：注册意图、connect 自动 bind.request、owner 审批、NS/Storage 校验 |
 | 0.5.22 SDK 移植：同步、Stage/CAS、撤销续期、缓存、语言修复及 Rust | `docs/sdk/0.5.22-SDK开发与移植指南.md` 1. L5-8；2. L9-29；3. L30-39；4. L40-83；5. L84-118；6. L119-171；7. L172-188；8. L189-199 |
 | Ownership 2.1 agent.md/owner.md、普通名片边界、原格式与 Header | `docs/protocol/Ownership协议定义2.1.md` 1. L11-61；2. L62-202；3. L203-266；4. L267-634；5. L635-642；6. L643-669 |
 | Ownership 2.1 七 Facade、sub-first／owner-first 简化、三类 CAS 冲突、reset 与旧任务恢复 | `docs/sdk/Ownership-SDK编排指南2.1.md` 1. L9-40；2. L41-243；3. L244-277；4. L278-381；5. L382-415；6. L416-545；7. L546-717；8. L718-782；9. L783-824；10. L825-939 |

package/dist/agent-md.d.ts

@@ -20,6 +20,11 @@ export type AgentMdVerification = {
     reason?: string;
     ownership_status?: OwnershipVerificationStatus | 'not_applicable';
 };
+type AgentMdObservation = {
+    root: string;
+    etag: string;
+    version: number;
+};
 export interface AgentMdFrontmatter {
     aid?: string;
     name?: string;
@@ -114,7 +119,13 @@ export declare class AgentMdManager {
     private _loadRecord;
     loadRecord(aid: string): Record<string, unknown> | null;
     private _saveRecord;
-    saveRecord(aid: string, fields: Record<string, unknown>): Record<string, unknown>;
+    saveRecord(aid: string, fields: Record<string, unknown>, observation?: AgentMdObservation): Record<string, unknown>;
+    cacheOwnershipSnapshot(aid: string, snapshot: unknown, observation: {
+        root: string;
+        etag: string;
+        version: number;
+        content_hash: string;
+    }): boolean;
     private _clearConfirmedDraft;
     upload(content?: string | null, originalCondition?: OwnershipSavedFile['condition']): Promise<Record<string, unknown>>;
     readAgentMdFresh(aid: string): Promise<{
@@ -123,6 +134,8 @@ export declare class AgentMdManager {
         etag: string;
     }>;
     readOwnershipFresh(aid: string): Promise<OwnershipAgentObservation>;
+    _readOwnershipQuery(aid: string): Promise<OwnershipAgentObservation>;
+    private _readOwnership;
     submitOwnershipRaw(aid: string, raw: string, condition: OwnershipSavedFile['condition'], assertActive?: () => void, stage?: boolean): Promise<OwnershipAgentObservation>;
     private _ownershipRequest;
     uploadAs(targetAid: string, content: string, signer: AID): Promise<Record<string, unknown>>;
@@ -181,3 +194,4 @@ export declare class AgentMdManager {
     private _writeRecordUnlocked;
     private _readRecordUnlocked;
 }
+export {};

package/dist/agent-md.js

@@ -301,7 +301,7 @@ export class AgentMdManager {
     loadRecord(aid) {
         return this._loadRecord(aid);
     }
-    _saveRecord(aid, fields, strict = false) {
+    _saveRecord(aid, fields, strict = false, observation) {
         const target = String(aid ?? '').trim();
         if (!target)
             return {};
@@ -311,6 +311,8 @@ export class AgentMdManager {
             let savedTo = '';
             const record = this._withRecordLock(target, () => {
                 const next = { ...this._readRecordUnlocked(target, true), aid: target };
+                if (observation && (this.root !== observation.root || String(next.remote_etag ?? '') !== observation.etag || Number(next.observation_version ?? 0) !== observation.version))
+                    throw ownershipFailure('unavailable', 'agent.md observation changed during download', true);
                 if (hasContent) {
                     const content = String(inputFields.content ?? '');
                     savedTo = this.writeContent(target, content);
@@ -343,14 +345,31 @@ export class AgentMdManager {
             return { ...loaded };
         }
         catch (err) {
-            if (strict)
+            if (strict || observation)
                 throw err;
             this._log.debug(`agent.md cache save skipped: aid=${target} err=${err instanceof Error ? err.message : String(err)}`);
             return {};
         }
     }
-    saveRecord(aid, fields) {
-        return this._saveRecord(aid, fields, Object.prototype.hasOwnProperty.call(fields, 'local_draft_content'));
+    saveRecord(aid, fields, observation) {
+        return this._saveRecord(aid, fields, Object.prototype.hasOwnProperty.call(fields, 'local_draft_content'), observation);
+    }
+    cacheOwnershipSnapshot(aid, snapshot, observation) {
+        const target = this.safeAid(aid);
+        return this._withRecordLock(target, () => {
+            if (this.root !== observation.root)
+                return false;
+            const record = this._readRecordUnlocked(target, true);
+            const content = fs.existsSync(this.filePath(target)) ? this.readContent(target) : null;
+            const hash = content === null ? '' : AgentMdManager.contentEtag(content).slice(1, -1);
+            if (String(record.remote_etag ?? '') !== observation.etag || Number(record.observation_version ?? 0) !== observation.version || hash !== observation.content_hash)
+                return false;
+            record.ownership_snapshot = JSON.parse(JSON.stringify(snapshot));
+            record.updated_at = Date.now();
+            this._writeRecordUnlocked(target, record);
+            this._cache.set(target, { ...record, ...(content === null ? {} : { content, local_etag: `"${hash}"` }) });
+            return true;
+        });
     }
     _clearConfirmedDraft(aid, content) {
         this._withRecordLock(aid, () => {
@@ -407,8 +426,14 @@ export class AgentMdManager {
         return { exists: true, content: response.text, etag };
     }
     async readOwnershipFresh(aid) {
+        return this._readOwnership(aid, true);
+    }
+    async _readOwnershipQuery(aid) {
+        return this._readOwnership(aid, false);
+    }
+    async _readOwnership(aid, fresh) {
         const target = this.safeAid(aid);
-        const response = await this._ownershipRequest(target, 'GET');
+        const response = fresh ? await this._ownershipRequest(target, 'GET') : await this._ownershipRequest(target, 'GET', undefined, undefined, false, undefined, undefined, false);
         if ([200, 400, 404].includes(response.status) && headerValue(response.headers, 'X-AUN-Ownership-Status') === 'not_applicable')
             throw ownershipFailure('not_applicable', 'group/org uses its lifecycle owner relationship');
         if (response.status === 400) {
@@ -470,9 +495,9 @@ export class AgentMdManager {
             throw ownershipFailure('unavailable', 'NS raw submission cannot be confirmed from the current document', true);
         return fresh;
     }
-    async _ownershipRequest(target, method, raw, condition, legacyRead = false, assertActive, stage) {
+    async _ownershipRequest(target, method, raw, condition, legacyRead = false, assertActive, stage, fresh = true) {
         const gatewayUrl = await this._resolveGateway(target);
-        const headers = { 'X-AUN-Signature-Format': 'multi-v1', Accept: 'text/markdown', 'Cache-Control': 'no-cache', ...(!legacyRead ? { 'X-AUN-Ownership-Check': '1' } : {}) };
+        const headers = { 'X-AUN-Signature-Format': 'multi-v1', Accept: 'text/markdown', ...(fresh ? { 'Cache-Control': 'no-cache' } : {}), ...(!legacyRead ? { 'X-AUN-Ownership-Check': '1' } : {}) };
         if (method === 'PUT') {
             if (stage)
                 headers['X-AUN-Ownership-Stage'] = '1';
@@ -913,22 +938,25 @@ export class AgentMdManager {
     }
     async download(aid, timeoutMs = DEFAULT_HTTP_TIMEOUT_MS) {
         const target = this.safeAid(String(aid ?? this._ownerAid() ?? '').trim());
-        const existing = this._downloadInflight.get(target);
+        const record = this.loadRecord(target);
+        const observation = { root: this.root, etag: String(record?.remote_etag ?? ''), version: Number(record?.observation_version ?? 0) };
+        const key = JSON.stringify([target, observation]);
+        const existing = this._downloadInflight.get(key);
         if (existing)
             return await existing;
         const task = (async () => {
             const release = await this._acquireDownloadSlot();
             try {
-                return await this._downloadOnce(target, timeoutMs);
+                return await this._downloadOnce(target, timeoutMs, observation);
             }
             finally {
                 release();
             }
         })();
-        this._downloadInflight.set(target, task);
+        this._downloadInflight.set(key, task);
         task.finally(() => {
-            if (this._downloadInflight.get(target) === task)
-                this._downloadInflight.delete(target);
+            if (this._downloadInflight.get(key) === task)
+                this._downloadInflight.delete(key);
         }).catch(() => undefined);
         return await task;
     }
@@ -940,7 +968,9 @@ export class AgentMdManager {
         const remoteEtagCached = String(before.remote_etag ?? before.etag ?? '').trim();
         const lastModifiedCached = String(before.last_modified ?? '').trim();
         const checkedAtCached = Number(before.checked_at ?? before.fetched_at ?? 0) || 0;
-        const cachedInSync = !!(localFound && localEtag && remoteEtagCached && localEtag === remoteEtagCached);
+        const verified = before.verified_agent_md;
+        const matchesRemote = (etag) => localEtag === etag || before.verify_status === 'verified' && verified?.etag === etag && verified.content_hash === localEtag;
+        const cachedInSync = !!(localFound && localEtag && remoteEtagCached && matchesRemote(remoteEtagCached));
         if (cachedInSync && AgentMdManager.checkedAtFresh(checkedAtCached, ttlDays)) {
             return {
                 aid: target,
@@ -993,7 +1023,7 @@ export class AgentMdManager {
         const remoteEtag = String(remote.etag ?? '').trim();
         const lastModified = String(remote.last_modified ?? '').trim();
         const saved = this.loadRecord(target) ?? before;
-        const inSync = !!(localFound && remoteFound && localEtag && remoteEtag && localEtag === remoteEtag);
+        const inSync = !!(localFound && remoteFound && localEtag && remoteEtag && matchesRemote(remoteEtag));
         return {
             aid: target,
             local_found: localFound,
@@ -1022,7 +1052,7 @@ export class AgentMdManager {
         const hadRemoteVersion = Boolean(String(before.remote_etag ?? '').trim() || String(before.last_modified ?? '').trim());
         let record = { ...before };
         if (!same || Object.keys(before).length === 0) {
-            const fields = { observed_at: Date.now(), remote_status: 'found' };
+            const fields = { observed_at: Date.now(), observation_version: Number(before.observation_version ?? 0) + 1, remote_status: 'found' };
             if (remoteEtag)
                 fields.remote_etag = remoteEtag;
             if (remoteLastModified)
@@ -1194,7 +1224,7 @@ export class AgentMdManager {
         });
         return data;
     }
-    async _downloadOnce(target, timeoutMs) {
+    async _downloadOnce(target, timeoutMs, observation) {
         this._log.debug(`downloadAgentMd enter: aid=${target}`);
         const gatewayUrl = await this._resolveGateway(target);
         const cached = this.loadRecord(target) ?? {};
@@ -1233,7 +1263,7 @@ export class AgentMdManager {
             });
         }
         if (response.status === 404) {
-            this.saveRecord(target, { remote_status: 'missing', checked_at: Date.now(), last_error: '' });
+            this.saveRecord(target, { remote_status: 'missing', checked_at: Date.now(), last_error: '' }, observation);
             throw new NotFoundError(`agent.md not found for aid: ${target}`);
         }
         if ((response.status < 200 || response.status >= 300) && !reusedCachedNotModified) {
@@ -1307,8 +1337,9 @@ export class AgentMdManager {
             remote_status: 'found',
             verify_status: statusText,
             verify_error: reason,
+            verified_agent_md: { etag: responseEtag, content_hash: localEtag, verification, signature, cert_pem: peer.certPem },
             last_error: '',
-        });
+        }, observation);
         const owner = this._ownerAid();
         let inSync = null;
         if (target.toLowerCase() === owner.toLowerCase()) {
@@ -1349,8 +1380,6 @@ export class AgentMdManager {
         const checkedAt = Number(cached.checked_at ?? 0) || 0;
         if (String(cached.remote_status ?? '').trim().toLowerCase() === 'missing' && checkedAt > 0 && Date.now() - checkedAt <= AGENT_MD_NEGATIVE_CACHE_TTL_MS)
             return;
-        if (this._downloadInflight.has(target))
-            return;
         void this.download(target).catch((err) => {
             this.saveRecord(target, {
                 last_error: err instanceof Error ? err.message : String(err),