@agentunion/fastaun 0.5.24 → 0.5.26

package/_packed_docs/sdk/0.5.24-SDK/345/274/200/345/217/221/344/270/216/347/247/273/346/244/215/346/214/207/345/215/227.md

@@ -0,0 +1,354 @@
+# AUN SDK 0.5.24 开发与移植指南
+
+面向 SDK 维护者和其它语言实现者，整理当前四 SDK 的完整核心契约。应用接线见 [应用集成指南](0.5.24-SDK应用集成指南.md)，方法与 wire 字段以 [API 手册](06-API手册.md)、各领域 RPC 手册和协议为准；本指南的 TS 片段用于说明机制，不替代各语言接口。
+
+## 1. 版本基线与实现范围
+
+目标为当前 `0.5.24` 工作区，发布及验证记录见 [parity v0.5.24](../../python/CHANGES_FOR_PARITY.md#v0524--三端-v0523go-v0522-基线变更待发布)。Python／TS／JS 对照真实 `0.5.23` 发布产物；Go 按本轮确认对照 `0.5.22` 提交 `080225cac`，不能把四端都当作相同基线。
+
+| 范围 | 版本说明 |
+| --- | --- |
+| 本轮主要变化 | Ownership 当次执行、本地双／三身份编排、注册当次发请求、Stage 适配和 resolve 观察一致性修复。 |
+| 三端已有能力 | Python／TS／JS 的证书材料缓存、静态验链复用、PKI 单飞、Credential 查询缓存、小时撤销补拉、按 ETag 复用展示快照已在真实 `0.5.23`；本文保留契约，不重复宣称为新增。 |
+| Go 较早基线增量 | 同时包含上述缓存、观察与查询优化；具体来源见 parity，不能据此推断 Go `0.5.23` 发布源。 |
+| 服务与 Rust | NS／Storage／Gateway／Credential／Org 配套条件单独说明。Rust 本轮仅核查、未修改，不计入四端对齐完成。 |
+
+[0.5.21](0.5.21-SDK开发与移植指南.md) 与 [0.5.22](0.5.22-SDK开发与移植指南.md) 保留历史说明，其中 Ownership 持久任务、reset、审批恢复和旧快照 TTL 不再是当前要求。通用消息及组织 checkpoint 的持久化继续保留。
+
+## 2. 三主体、分层与生命周期
+
+| 主体／层次 | 实现职责 |
+| --- | --- |
+| `AIDStore` | 管理多身份目录、注册／加载、密钥保护、普通名片草稿和 resolve；普通名片读取不依赖 owner 可用。 |
+| `AID` | 持有本身份及证书／私钥、设备／slot、信任配置；不以 AID 字符串代替身份材料。 |
+| `AUNClient` | 消费一个 AID，建立认证连接、能力协商、消息交付和 Facade；重连不等于业务已完成。 |
+| 协议与密码学 | 严格解析、签名字节、证书、当前证据与授权；不凭 UI 状态或服务端布尔值授予权限。 |
+| Facade 与文件适配 | 复用底层协议与 RPC，按身份执行本人动作；不另建一套密码学或归属状态机。 |
+
+持久进度按接收 AID、device、slot 及 namespace 隔离。异步工作还绑定身份、连接及 namespace 代际：请求返回、应用处理、持久提交和缓存回填前均复核，旧代结果不能进入新身份。源身份被切换时，本地 Ownership 编排同样停止。
+
+Node `load` 同步、浏览器 `load` 异步；浏览器采用 IndexedDB／WebCrypto，不能复制文件端目录、seed 轮换或 SQLite 方案。RPC 保持 Python async、TS／JS Promise、Go context/error 的原有约定。
+
+## 3. peer 同步、batch、持久提交与退避
+
+### 3.1 能力、目录与消费水位
+
+`auth.connect` 声明 `p2p_peer_pull_v1: true`，只接受受认证响应的严格布尔 true；缺失或其它类型为 `unsupported_protocol`，不混回 global 消费。peer namespace 为 `p2p.peer.v1/` 加完整 sender UTF-8 的无 padding base64url；群使用 `group:{id}` 与 `group_event:{id}`。
+
+| 入口／证据 | 核心契约 |
+| --- | --- |
+| `message.peers(filter=pending)` | 完整候选目录、不分页，包含 volatile-only peer；不接受 limit/page_token。 |
+| `filter=all` | limit 1–200，按 next_page_token 分页；是消息状态目录，不是联系人目录。 |
+| `catalog_ready=false` | 保留重试，不能当成功空目录；核对 receiver、device、cursor_scope、sender 等绑定。 |
+| `bootstrap_floor_seq` | 首次 peer 模式固定旧 ACK 基线；已有 peer ACK 优先，不随新 peer 改写基线。 |
+| `A / T / H` | A 为可靠提交的 Forward 前缀，仅 A 可 ACK；T/H 是 Tail 已扫描边界，不能代替已交付。 |
+| 覆盖证明 | 核对 scan_after／covered_through／next_after／head 及 prev_peer_seq；共享设备收件箱的 peer seq 天然稀疏。 |
+
+目录估计不用于未读数、完成判断或 Tail 决策，不额外 COUNT 模拟精确 pending。Forward 页的 next_pending_seq 只在该页可靠提交后采用；后台段保持稳定排序与 FIFO 公平性，不重排公开目录。只有已验证自身名片为 human 才自动先 Tail 再 Forward。
+
+省略 sender 的 Pull 先取得 pending 目录再调度 peer；显式 after_seq、volatile cursor、window_mode 或 force 必须指定 sender。History 只验证、解密、返回，不推进实时水位、ACK 或发布事件；History／force／Tail 的列表不能按实时去重缓存删行。peer ACK 不修改 global 或其它 peer，volatile 与持久 seq 分别保存。
+
+### 3.2 Gate、容量与提交顺序
+
+每 client 共享一个 Pull Gate：同 namespace 单飞，不同 namespace 最多 4 个网络请求并行，同 key 折叠，前台 FIFO 优先。网络名额在每页响应／失败后释放，不跨应用处理、后续页或退避等待占用。页容量 200，最多预取 4 页；应用队列按消息权重共享 800 容量，不是每 namespace 各 800。
+
+```mermaid
+flowchart TD
+    A[固定页、身份代际与处理器快照] --> B[预留容量并获取网络 Gate]
+    B --> C[收页、验证覆盖证明；释放网络名额]
+    C --> D[解密及内部协议处理]
+    D --> E[发布 batch 或 single，等待处理器]
+    E --> F[复核代际，可靠提交本页水位]
+    F --> G[仅 ACK 已提交 A，核对实际确认位置]
+    D -->|失败| H[保留责任，不确认失败范围]
+    E -->|处理器失败| H
+    F -->|持久化失败| H
+    G -->|响应丢失或 ACK 不足| I[保留原待确认责任]
+```
+
+`message.batch/group.message_batch/group.event_batch` 每实际页固定是否采用及其处理器；订阅存在则只发 batch，否则使用 single。不得双发、失败后退回 single，或因没有应用订阅跳过内部处理。Push／inline 为单元素批次，items 保持原事件、payload、source 和顺序，不跨 namespace，不按 need_render 过滤。
+
+```ts
+client.on('message.batch', async (batch) => {
+  await applicationDb.commitMessages(batch.items);
+});
+```
+
+示例中的应用提交必须可重放。TS／JS 等待 Promise，Python 等待异步处理器，Go 使用 `OnBatch` 的 error 阻止提交；旧 Go `On` 保留。运行时去重及 SDK receipt 不等于应用数据库的持久幂等事务；崩溃、淘汰或多个 client 仍可能重放。处理器内不得等待同一交付链形成重入。
+
+### 3.3 后台退避与群终态
+
+P2P、群消息、群事件、peer 目录与按 peer 恢复分别保留失败次数／重试时间，执行有上限指数退避；hint、分页和补拉合并需求但不重置未到期退避。成功清本 namespace 失败状态，身份／连接换代清旧状态。后台预算结束保留持久及 volatile 待拉责任，不能当同步完成。
+
+优先读取布尔 `error.data.retryable`；临时错误退避，非成员、封禁、群不存在／解散等终态联动停止该群消息和事件、别名及 tail 待办，保留本地消息与游标。手动成功或身份／连接换代可恢复。自动身份恢复跳过明确非 active 群；确认 proposal 前重查 owner/admin，按群串行并去重，保留 base/hash 和代际检查。
+
+## 4. 名片原件、签验与实体边界
+
+普通名片的解析、展示和正文更新与 Ownership 验证分层。正文更新保留原有 owner／ownership 的存在性、类型和值，使用本人签名和原 ETag；不能因 Storage 不可用而阻止普通更新，也不能用普通 `uploadAgentMd` 删除关系字段。失败草稿显式重试，下载／connect／重连不隐式 PUT，旧上传结果不清较新草稿。
+
+文件层保留完整原始字节及全部 frontmatter 类型，包括未知扩展和嵌套对象，向调用方返回隔离副本。复用唯一通用签验核心：text／file 显式区分，document 每签覆盖此前全部 prefix，附签声明 signer_aid；不重排 YAML、换行或 Unicode。Ownership 使用 P-256／SHA-256、DER 标准 Base64，不能套用 V2 消息 RAW 签名。
+
+`multi-v1` 读取和写入保留完整签块与表示 ETag；摘要不是 If-Match 的替代。Group／Org 由实体私钥主签、当前 owner token 上传，可附 owner 签且全部校验。固定实体指纹、owner、原文和 CAS，rekey／转移／解散后停止旧代 pending；通用 Ownership 返回 `not_applicable`，不伪造普通 sub 声明。严格文件、证书与数字词法见 [Ownership 移植指南](Ownership2.1-SDK开发与移植指南.md#4-原始文件严格解析与签名)。
+
+## 5. resolve 的观察、展示快照与强查
+
+默认 resolve 不查 Ownership；显式传入现有 checker，复用其身份和超时配置，不接受 true 后偷偷创建 client。输出保留完整 agent.md、frontmatter 和原 Result；额外共识失败只形成 unavailable，不把成功名片整体降级，也不回退旧 consensus。owner.md 快照可供展示，不能用于授权。
+
+```mermaid
+flowchart TD
+    A[取得展示名片及 observation] --> B{显式请求 Ownership 吗}
+    B -->|否| C[返回身份及完整 frontmatter]
+    B -->|是| D{强查，或 ETag／全文 hash／观察改变吗}
+    D -->|否| E[复用该观察的展示快照]
+    D -->|是| F[按 checker 身份和观察单飞查询]
+    F --> G[核对 sub、ETag 和完整原文 SHA]
+    G --> H[回填前复核最新 observation 未变]
+    H --> C
+    E --> C
+```
+
+查询单飞键包含 checker 身份、AID、ETag、全文 hash 和 observation 代际，不同 checker 的在途查询不合并；已缓存展示快照按名片观察复用，命中分支不按 checker 再分区。TS 本轮修复为相同 ETag 时不因 Last-Modified 单独变化制造新观察，其它端不能据此宣称相同行为。旧下载／查询不得覆盖新观察；可用快照的 sub、ETag、完整原始正文 SHA 必须对应展示名片，可靠不存在单独处理。unavailable 不变成可授权快照。
+
+`forceRefresh/force_refresh` 刷新名片，ETag／正文未变仍可复用展示快照。默认及正数 Ownership TTL 不再按年龄过期；显式 `ownershipTtlMs/ownership_ttl_ms <= 0` 或 Go 指向非正 duration 才旁路快照走内部 fresh checker，不能照旧移植为默认一分钟失效。
+
+```ts
+const resolved = await store.resolve(peerAid, { ownership: client });
+const checked = await store.resolve(peerAid, {
+  ownership: client, ownershipTtlMs: 0,
+});
+```
+
+公开 `checkOwnershipConsensus` 每次 HTTP 带 `X-AUN-Ownership-Check: 1`，但不带 no-cache，NS 的 agent.md 缓存可复用；管理流程的内部 fresh 才带 no-cache。Check 仍读取 Storage owner.md，服务端 inline object cache 可使用。owner.md 能独立变化，展示快照不代替需要 owner 关系校验时的权威检查。
+
+## 6. Ownership 当次执行与 NS 权威验收
+
+### 6.1 移除任务，保留事实与条件
+
+没有 Ownership 持久任务、WAL、审批记录、本地 revision CAS、lease/fencing、专用 inbox/outbox 或 connect 恢复；当前 SDK 不调用 decisions，也不要求各方先领回执。普通消息历史、可靠发送、设备／slot 水位和提交后 ACK 保留。
+
+编排只保存当次身份／文件上下文与内存原始请求索引。accept/reject 未命中时可按需从 `message.peers`／`message.history` 取回并校验认证原请求；查不到返回 `operation_not_found`。这不是恢复任务，不能从 UI 字段补造原请求。TS 兼容 `OwnershipFileTask.persist()` 当前仅做身份 guard，不表示落盘。
+
+| NS 事实 | 行为约束 |
+| --- | --- |
+| 未锁定 | 最后成功 CAS 上传的 agent.md 决定候选；先 B 后 C，B 的 owner.md 无法与当前候选共识。 |
+| 接受／拒绝 | 接受上传本人文件并通知／验收；拒绝仅反馈，不回滚候选。锁前不保证跨设备唯一决定。 |
+| 已锁定 | 迟到 accept/reject 不改归属；变化必须释放或合法转移，相同事实仍验签并核对当前权威关系。 |
+| 并发控制 | 保留 NS ETag CAS、Storage expected_version、关系版本；operation／消息 ID、声明 UUID／时间不代替归属事实。 |
+| 失败重试 | 已上传但未通知、丢响应或崩溃后显式重查／重发；不承诺沿用旧 ID、字节或审批，不能据异常推断远端未改变。 |
+
+NS If-Match／If-None-Match 防止并发名片覆盖；Storage `expected_version=0` 创建、正版本更新／删除，防止并发 owner 文件覆盖；关系版本绑定归属与授权，不是全局 operation 序号。409／412、Storage `-32009` 后重新读事实，不能换最新条件强行重传旧意图。
+
+```ts
+assertIdentityUnchanged();
+const published = await fileDeps.submitAgentMdRaw(
+  subAid, signedRaw, originalCondition, assertIdentityUnchanged,
+);
+```
+
+signedRaw 和 originalCondition 属当次调用上下文，前后仍须执行原件、事实及身份核验；此处没有持久任务提交。
+
+### 6.2 交互流程、注册与释放
+
+| 发起方 | 当次动作与后续接受 |
+| --- | --- |
+| sub 绑定 | 先 Stage 上传 agent.md → bind.request → owner 明确接受并上传 owner.md → NS Check 验收。 |
+| owner 绑定 | 先上传 owner.md → bind.request → sub 明确接受并上传 agent.md → NS 验收。 |
+| 旧 owner 转移 | 先上传 transfer_owner 授权 → 分别通知 sub、新 owner → 两方独立接受并上传本人文件。 |
+| owner 释放 | 同版本 release → fresh 确认 released → 通知 sub；sub 可离线，收到合法通知后当次核验及内部条件清理。 |
+
+带 owner 注册先保存身份并发布无关系声明的初始名片，再在注册当次以专属短连接发绑定请求、finally close；human owner 仍须确认。注册成功不代表关系成立，失败时身份可能已保存，先 load／查 NS 再显式重发。保留的 registration_intent 元数据不代表 connect 后续绑。
+
+普通上传不能删关系字段，当前没有公开强制清理 Facade。释放通知尚未处理可继续展示 released；通知丢失后没有 Ownership 后台补偿。旧 owner 转移文件只在目标 active 已成立且原授权完整匹配时按 Storage 版本条件清理，不能误删后续关系。
+
+### 6.3 Stage 候选、active 与乱序转移
+
+```mermaid
+sequenceDiagram
+    participant O as 旧 owner
+    participant S as sub
+    participant W as 新 owner
+    participant T as Storage
+    participant N as NS
+    O->>T: CAS 发布旧版本 transfer_owner 授权及期限
+    O-->>S: transfer.request
+    O-->>W: transfer.request
+    par 双方分别明确接受，先后均可
+        S->>N: CAS Stage 上传 target agent.md
+        N->>N: 暂存 candidate，保留旧 active
+    and
+        W->>T: CAS 上传 target owner.md
+    end
+    N->>T: Check 核验原授权与目标 owner 文件
+    N->>N: 材料齐备且有效，原子切换 active
+    O->>N: 非 Stage fresh 核对目标 owner／版本／locked
+```
+
+首次绑定 Stage 须确认能力头及 unlocked/pending；pending 映射 single_sided，不授权。transfer Stage 正文可为 target，头仍是旧 active 的 locked/base，也可能已晋升 locked/target；locked 可省略 Ownership-Status。必须继续验证 Stage 能力、完整签名字节／SHA、原 ETag／CAS、base/target 和有效转移授权，只对合法 transfer 接受旧锁例外。Stage 成功不等于归属生效，最终查非 Stage active。
+
+共识校验保留当前证书、双文件原件、可靠不存在、30 秒观察窗口和稳定性复读。投影／锁与文件冲突时共享一次额外 fresh 重查，仍冲突或依赖不明为 unavailable；确定非法为 invalid。转移未完成／授权过期时旧 active 继续有效，不经历 released。
+
+### 6.4 本地双／三身份短连接编排
+
+local bind 使用 owner＋sub 两个不同普通 agent；local transfer 使用旧 owner＋sub＋新 owner 三个。各方须有有效私钥、证书及已发布名片，源 client 无须先在线。Facade 为各身份创建 `ownership-UUID` 专属 slot 短连接，禁后台同步／自动重连，并在所有结束路径关闭；每次异步副作用前后检查源身份和代际。
+
+```mermaid
+flowchart TD
+    A[核对不同 agent 身份及源代际] --> B[为两／三身份建立专属 slot 短连接]
+    B --> C{绑定还是转移}
+    C -->|绑定| D[owner CAS 上传本人 owner.md]
+    C -->|转移| E[旧 owner CAS 上传授权]
+    E --> F[新 owner CAS 上传本人 owner.md]
+    D --> G[sub CAS 上传本人 agent.md]
+    F --> G
+    G --> H[非 Stage fresh 验收目标 active 共识]
+    H --> I[转移时核对原授权并条件清理]
+    I --> J[finally 关闭全部操作连接]
+    B -->|异常| J
+    G -->|异常| J
+    H -->|异常| J
+```
+
+```ts
+await ownerClient.bindLocalSubaid(subClient);
+await ownerClient.transferLocalSubaid(subClient, nextOwnerClient);
+```
+
+底层顺序复用现有文件层，各身份只签传本人文件，无 P2P、任务或 WAL。目标已 active 则避免重写，转移清理仍核对原授权。daemon 作为自己创建 sub 的 owner 可自动完成；不沿 daemon 的 owner 链推导 human 授权，human 场景保持人工流程。详细装配见 [Ownership 本地编排](Ownership2.1-SDK开发与移植指南.md#115-本地双身份自动绑定)。
+
+## 7. Storage／Group FS 默认读缓存
+
+### 7.1 策略与刷新
+
+只缓存读取白名单，同时接入元数据／正文入口、持久后端及失效；不能在 Facade 外层简单缓存整个 RPC 结果。
+
+| 条件 | 当前规则 |
+| --- | --- |
+| read_cache 缺省或整体 null | 元数据默认 60 秒；完整正文实际 ≤65,536 字节且 SHA-256 验证成功时默认缓存。 |
+| 显式策略 | 必须 reusable=true，正文另需 inline=true；省略 max_age_ms 默认 60 秒，有限正数上限 60 秒。显式禁止、空对象、字段 null／非正数／非法 TTL 不复用。 |
+| 单次刷新 | TS／JS noCache、Python no_cache、Go Options.NoCache 强制回源，选项不透传成业务字段；刷新不是 no-store。 |
+| 条件读取 | 可用 if_sha256 验证旧正文；not_modified 必须匹配已有已验证完整正文，无正文不能返回空文件。 |
+| 特殊读取 | authoritative、范围、显式预签读取旁路 SDK 缓存；联网仍执行身份、权限、到期和撤销检查。 |
+
+普通 owner.md 读取可缓存，Ownership 管理读取权威原件；服务端 inline object cache 与 SDK 旁路是不同层次。`storage.list_share_links/check_access/list_tokens` 始终回源，且不因这些查询使其它缓存失效。TTL 从请求起点计算并扣除服务端材料年龄，不能在热命中或重启时续期。
+
+### 7.2 持久预算、隔离与失效
+
+| 后端／预算 | 规则 |
+| --- | --- |
+| Node TS／Python／Go | `{aunPath}/.cache/storage/index.sqlite3` 的 cache_entries/cache_blobs；正文为 blobs/{摘要前两位}/{摘要}，保留 SQLite WAL journal。 |
+| 浏览器 JS | aun-keystore IndexedDB 的 storage_cache_index/storage_cache_blobs。 |
+| 容量 | 内存／持久正文 32／256 MiB，元数据 16 MiB，索引 999／9,999 条；正文按最近访问淘汰。 |
+
+键按实际身份、gateway、RPC 和规范参数隔离，保留范围／token／share／ACL 差异，排除刷新、条件摘要和可重签材料。同键冷读合并；写删、移动、ACL／token／share 与相关群权限变化失效。身份／连接换代或失效前在途结果不得回填。
+
+持久正文先验摘要，索引与 blob 分离，不进入业务数据库或 tokenstore；去除临时 URL、票据、认证 token 和签名，下载重新申请票据。缓存损坏、丢 blob 或后端失败时回源／降级，不当成远端不存在。热命中不联网，远端改变最迟等刷新／TTL 观察；有限次授权计次由实际返回 inline 正文或票据签发语义决定，本地命中不新增联网授权。完整契约见 [Storage 默认读缓存](09-storage-rpc-manual.md#sdk-默认读缓存)。
+
+## 8. PKI 材料缓存与严格当前状态
+
+精确证书、链和静态验链结果可复用、同条件请求可单飞；键含 scope、gateway、AID／精确 DER 指纹、用途、信任根及身份／连接代际。历史签名读取与当前权威证书查询不可混合，失败移除在途记录，根／身份／证书变更使相关缓存失效，旧请求不能回填。
+
+四端链与静态验链默认缓存一小时并受证书期限约束；Go 相对指定 0.5.22 将默认 ChainCacheTTL 从一天改为一小时，但自定义值未统一硬限为一小时。普通 CRL／OCSP 缓存还受响应有效期限制；不可变证书材料、静态链和完整严格验证结果须分层，不得把材料存在解释成当前授权有效。
+
+| 新取得的 Ownership 证据 | 验收条件 |
+| --- | --- |
+| authoritative 当前证书 | 精确指纹、可信链、active_signing；observation 过去 ≤30 秒、未来 ≤5 秒。 |
+| OCSP | CertID／ResponderID／签名／状态完整匹配；ThisUpdate 过去 ≤30 秒，ProducedAt ≤90 秒，未来 ≤5 秒，NextUpdate 有效。 |
+| 验证窗口 | 新取与组合验证窗口 ≤30 秒；网络等待后重读时钟、证书及材料期限。未知或过期证据 unavailable，坏签／吊销 invalid。 |
+
+完整严格结果的复用存在语言差异：TS／JS Ownership 每次取权威证书及严格 OCSP，复用静态链；Python 每次取权威 lifecycle 元数据，内部验签结果可在证书／链和 CRL／OCSP 刷新截止前复用；Go 可将完整结果缓存至其 TTL、证书到期和 OCSP NextUpdate 的最早边界，命中时不重读 lifecycle。上表是新证据验收条件，不能宣称所有缓存命中都重新下载吊销材料，或把 30 秒说成四端完整结果的统一缓存上限。服务事件也可按自己的证据截止复用严格结果。
+
+通用离线数学验签不提供当前授权事实。canonical JSON、请求绑定和 V2 envelope 的签名格式各守原契约，不能复用错误的序列化或签名编码。文件端关闭时取消／回收在途工作，TS／浏览器也须阻止旧代写回。实现入口为 [auth.ts](../../ts/src/auth.ts)、[org-protocol.ts](../../ts/src/org-protocol.ts) 及各端对应文件。
+
+## 9. Credential、撤销补拉与 Org checkpoint
+
+### 9.1 已验证查询缓存与完整验证
+
+托管管理器的 `credential.status`、`org.member.get` 已验证查询最多缓存 60 秒，受 proof、签名证书和相关 credential.exp 截止限制；不是所有 raw RPC 自动缓存。缺绑定证明不回填，登记恢复确认等 fresh 路径旁路。按本端身份／查询上下文／参数隔离，相关成功写及已验证事件失效；回填按各端 scope／epoch 及后台 guard 复核，Go 查询回填检查身份代次与 query epoch，不统一检查连接代次，各端 key 和单飞结构不必相同。TS／JS／Go 完成撤销同步结果另有约 60 秒缓存，Python 的持久完整同步时间见下节。
+
+`credential.current` 是本地托管查询，沿 successor 找当前记录并返回隔离副本／null，不映射到不存在的同名 RPC，也不提供新鲜授权。完整 Verify 保留证书、有效期、受众、父链收窄、强 status proof、能力约束、实际 request binding、成员和代表关系；签名预检不能替代完整授权。
+
+Credential canonical JSON 对字符串 NFC，外层 client_signature 规则保持原字符串；CAP／proof 使用 DER 标准 Base64。只有 revocationList 的 request binding 允许空 credential_cid，首次 admission 使用 membership_id 专用绑定，不能推广成普通业务例外。异步完成前复查 300 秒请求窗口和材料期限。
+
+### 9.2 撤销快照与跨重连 deadline
+
+验签后将推送和分页合并到受保护撤销快照：绑定 authority／接收者／请求／覆盖范围，按 CID 保留最大 event_seq。单条推送不推进列表 checkpoint，完整验证页持久应用后才推进，迟到页不能回退；缺 CID 不证明有效。只同步托管凭证及父证明链所涉及的 authority，无托管记录时不默认扫描本域。
+
+```mermaid
+flowchart TD
+    A[在线 worker 每 60 秒扫描] --> B{已到保留的小时 deadline 吗}
+    B -->|否| C[继续正常续期扫描]
+    B -->|是| D[先保留下一小时 deadline，再尝试同步]
+    D --> E[按 authority 取撤销页并验证]
+    E --> F[合并最大序号，持久提交页及 checkpoint]
+    F --> I[完整同步成功后记录查询缓存]
+    G[断线停止 worker] --> H[重连重建 worker，保留同 client deadline]
+    H --> A
+```
+
+首次初始化下次后台补拉为一小时后；连接后可立即做续期 due 扫描，不能写成立即拉撤销。到期扫描先更新下一 deadline 再尝试同步，不承诺失败后每分钟重拉。同一 client 重连不把既有期限推迟一小时；已到期时在恢复扫描尝试。deadline 属内存，不是跨进程保证；Python 另持久保存完整同步的 sync_checked_at 防止一小时内重复完整同步，未完成 cursor 仍继续分页。身份／连接 guard 丢弃旧结果，不能把旧响应提交到新身份。
+
+### 9.3 保留续期与组织恢复
+
+长期托管凭证在线每 60 秒扫描，短期 `long_term=false` 跳过后台及写前自动续期。成功立即保存完整凭证、binding、条款、登记回执、权威信息和服务版本，不等事件补齐，不误写组织账户。登记及 successor 提交须验新 CAP、成员状态和原回执，不能收到新 CID 就替换。
+
+组织创建／转让、实体 rekey／finalize 和续期仍保留受保护 checkpoint、CAS、原请求／nonce／request_id／签名字节、固定实体密钥和证书代际。读取损坏或缺原候选私钥失败关闭，不生成替代身份；completed 重放核对原 owner、转让 ID 及输入，重连跳过已完成任务。文件端 seed 轮换继续处理按 AID／用途绑定的加密 metadata，失败回滚已写记录；浏览器保持自身存储机制。
+
+服务端继续负责 Credential revoke 的原请求幂等结果、组织创建补偿冲突保护、换钥前证书代际核对、成员包原子落盘及定向通知。SDK 仍核验完整成员包，不能把配套服务能力算作 SDK 新增。详见 [凭证与组织移植指南](凭证与组织服务SDK开发与移植指南.md)；Ownership 任务移除不影响这些 checkpoint。
+
+## 10. 语言差异、代码落点与服务兼容
+
+### 10.1 公开接口差异
+
+| 范围 | 当前四端差异 |
+| --- | --- |
+| local bind／transfer | Python bind_local_subaid／transfer_local_subaid；TS／JS bindLocalSubaid／transferLocalSubaid；Go BindLocalSubaid／TransferLocalSubaid（含 context）。 |
+| 旧任务 API | TS 删除 resetOwnershipTask 及结果类型导出，Go 删除 ResetOwnershipTask／任务 keystore API；Python reset 返回空 reset、内部 list 为空／get 报 operation_not_found；JS reset 保留空 reset_operation_ids/skipped_operation_ids。 |
+| 旧归属 getter | getOwner 等为空；Python／TS／Go status 为 legacy_unbound，JS 为 unknown 占位，不能用于归属判断。 |
+| 普通编排结果 | TS／Python completed 可仅表示当次动作；Go completed 返回及事件也不等于已锁；JS 目标 locked 才 completed，否则 pending。local 方法另有内部目标验收。 |
+| resolve | Python snake_case，TS／JS camelCase；Go PascalCase、OwnershipTTL 为 duration 指针。正数不再设置快照年龄期限。 |
+| 事件／数值 | request 的附加字段不完全相同，可信原请求留 SDK 内；JS／TS 超安全整数的已读序号用精确十进制字符串，不浮点签名或提交。 |
+
+最终 Ownership 统一查询 consensus 并核对目标 owner、关系版本和锁，不能只用事件、getter 或 completed 名称。`ownership.request/rejected` 用于 UI 通知，不保证其它兼容 progress/error/stopped 事件每次必发。
+
+### 10.2 主要实现入口
+
+| 契约 | Node TS 参考 | 其它端对应入口 |
+| --- | --- | --- |
+| peer／交付／Gate | [client/delivery.ts](../../ts/src/client/delivery.ts)、[rpc-pipeline.ts](../../ts/src/client/rpc-pipeline.ts)、[events.ts](../../ts/src/events.ts) | Python _client；Go client_peers.go/client_delivery.go；JS src/client。 |
+| 名片／resolve | [agent-md.ts](../../ts/src/agent-md.ts)、[aid-store.ts](../../ts/src/aid-store.ts) | Python agent_md.py/aid_store.py；Go agent_md_manager.go/aid_store.go；JS 同名文件。 |
+| Ownership | [ownership-workflow.ts](../../ts/src/ownership-workflow.ts)、[ownership-v21.ts](../../ts/src/ownership-v21.ts)、[client.ts](../../ts/src/client.ts) | Python ownership_workflow.py/ownership_v21.py；Go ownership_workflow.go/ownership_v21.go。 |
+| 缓存／PKI／组织 | [storage/read-cache.ts](../../ts/src/storage/read-cache.ts)、[auth.ts](../../ts/src/auth.ts)、[org-protocol.ts](../../ts/src/org-protocol.ts) | 各端 storage_read_cache／auth／org_facades、org_protocol 及 keystore。 |
+
+服务能力须独立验收：Gateway／Message 严格 peer 协商及覆盖／ACK；NS 双文件事实验收、锁、Stage 候选隔离；Storage 权威原文及 expected_version；Credential／Org 的完整 proof 与原子提交。原 2.1 旧 NS 的普通绑定及材料先齐的部分 local 路径仍可工作；完整乱序转移、Stage 交错重试和锁后同事实重签需要本轮 NS。依赖已移除 decisions 的过渡实现可能 404，不能笼统承诺所有旧版互通。
+
+诊断沿用 `debug.diag` 目录与 dry-run：分项必须核对 dry_run=true、executed=false、目标 method 和有效 stage；缺材料记 skipped，不把 RPC 成功当业务通过。runtime version、包版本与 V2 envelope 的 sdk_version 对齐本端目标版本，不能用历史文档中的版本串覆盖当前产物。
+
+## 11. Rust 只读核查与移植清单
+
+Rust SDK 位于 `D:/modelunion/acp-app/aun-so/rust/`，本轮没有修改、发布或验收它。后续移植需先核查现状，再用上述契约编写失败测试，不能将本表视为已经完成：
+
+| 位置／范围 | 核查要求 |
+| --- | --- |
+| ownership_v21_workflow／backend | 移除旧持久任务／审批／WAL／恢复依赖，原请求按需检索；保留双文件、两类远端 CAS、关系版本与释放清理。 |
+| Ownership Stage／local | 核查 locked/base 候选、active 验收、双方任意到达；补两／三身份专属 slot 短连接及 source guards，无 P2P。 |
+| actor／消息 | 保留现有 Pull Gate、分页退避和在途控制；核对 peer、batch 提交后 ACK、群终态和代际边界。 |
+| resolve／PKI／缓存 | 按 ETag／完整 hash／observation／checker 隔离；静态材料缓存不放宽吊销；Storage／Group FS 60 秒及预算。 |
+| credential_org／org_lifecycle | 撤销分页与跨重连 deadline、验证查询缓存、成员完整包；保留实体 checkpoint、缺私钥保护和 completed 重放。 |
+
+不因四 SDK 简化而直接删除 Rust 的通用交付或组织恢复；先识别 Ownership 专属责任。源码定位沿用 [0.5.22 Rust 清单](0.5.22-SDK开发与移植指南.md#7-rust-移植清单)，其中历史 Ownership 任务规则以本指南替换。
+
+## 12. TDD、断点验收与证据边界
+
+按“协议向量 → 本地契约 → 故障提交 → 真实服务 → 跨端／双域”推进，先证明失败边界，再实现最小改动。首失败立即停止，修复后从该项续跑；已通过且不受影响的项不重跑。runner 检查点不是产品 Ownership 任务或 WAL。
+
+| 阶段 | 必须验证 |
+| --- | --- |
+| 消息 | 严格 peer 协商、sender 隔离、稀疏覆盖、batch/single 互斥、容量／Gate 释放、handler／持久化／取消失败不提前 ACK、丢响应重放。 |
+| 观察与缓存 | 不同 checker 隔离、ETag／hash 匹配、旧观察不回填、强刷不重复 owner 检查、显式非正 TTL、缓存摘要／失效／预算／重启／故障降级。 |
+| Ownership | B→C 最后候选、拒绝不回滚、锁后保护、同事实重签、原件及远端 CAS、Stage 两种锁版本、两种转移到达顺序、释放清理。 |
+| 本地及注册 | 两／三身份、无 P2P、专属 slot、source 换代停止、所有异常关闭连接、目标 active 验收、上传后未通知的显式重发。 |
+| PKI／Credential／Org | 材料复用但严格当前证据、过期／吊销失败、查询缓存失效、撤销分页不越过坏页、重连不延后 deadline、缺私钥及 checkpoint 损坏不重建。 |
+
+共同向量见 [Ownership vectors](../../tests/vectors/ownership_v21/vectors.json) 和 [Org vectors](../../tests/vectors/org-0.8/protocol.json)。定向入口见 [parity 测试记录](../../python/CHANGES_FOR_PARITY.md#0524-测试入口与已有验证记录)；联网按 [单域](../aun测试运行指南.md)、[双域](../aun分布式测试运行指南.md)、[公网](../aun公网测试运行指南.md) 指南执行，Windows Python 使用 `-X utf8`。
+
+已有 `ownership-local-20261024` 产物覆盖四 SDK local、Python／JS 交互、六个 Python 边界及 cross33 分五次断点累计通过的 33 个唯一用例；前轮失败保留，不是一次全绿。这些运行时版本仍标 0.5.23，但使用的是改造后工作区源码，不能证明真实旧发布包已有新行为，也不是最终 0.5.24 发布包实测。本轮仅整理文档，未重跑 live；专项证据不替代全量单元、浏览器、双域或完整发布回归。

package/_packed_docs/sdk/AUN_DOCS_GUIDE.md

@@ -44,6 +44,7 @@ Group 的成员 block/status、暂停群权限和两阶段群主转让，以及
 - Credential/Org：服务端实际注册的凭证与组织 RPC、受保护请求、内部接口及未实现占位（见 `09-凭证服务RPC手册.md`、`09-组织服务RPC手册.md`）
 - Service Proxy：`ServiceProxyClient`、`proxy.register_services`、proxy-server `register_services`
 - agent.md：Schema/frontmatter、Store.sign/verify 通用多签、显式 file/inPlace、multi-v1 表示协商、4 KiB/总尾区2048 字节限制、`AIDStore.register()` 默认自动上传、上传前完整校验、`agent_md_validation_v1`、`uploader_aid` / `uploaderAid`、`AIDStore.upload_agent_md()` / `download_agent_md()` / `check_agent_md()`、Gateway `_meta.agent_md_etags` 被动观察、`requester` / `peer` / `group` 角色
+- agent.md / group.index 的 ETag 权威来源、被动观察、下载触发、显式 pull 与 CAS → [ETag 观察与同步机制](agent.md与group.index的ETag观察与同步机制.md)
 - 错误处理：Result、Python `ErrorInfo.cause`、异常、错误码、重试
 
 ### Step 3：读 Layer 3 摘要
@@ -60,6 +61,8 @@ Group 的成员 block/status、暂停群权限和两阶段群主转让，以及
 | - | [0.5.22 SDK 开发与移植指南](0.5.22-SDK开发与移植指南.md) | 同步、Stage/CAS、撤销续期、缓存、服务依赖及 Rust 清单 |
 | - | [0.5.24 SDK 应用集成指南](0.5.24-SDK应用集成指南.md) | 当前消息接线、无任务 Ownership、两个 local 编排、缓存和凭证组织 |
 | - | [0.5.24 SDK 开发与移植指南](0.5.24-SDK开发与移植指南.md) | 消息提交、NS 事实和远端 CAS、local 身份隔离、缓存新鲜度与语言差异 |
+| - | 0.5.25 CHANGELOG：[Python](../../python/CHANGELOG.md)、[Go](../../go/CHANGELOG.md)、[TS](../../ts/CHANGELOG.md)、[JS](../../js/CHANGELOG.md) | 对照已提交 0.5.24 的消息、Ownership 缓存、名片下载及分域发现变更；实现差异与验证边界见 [parity](../../python/CHANGES_FOR_PARITY.md#v0525--已提交-v0524-基线变更未发布) |
+| - | [agent.md 与 group.index 的 ETag 观察与同步机制](agent.md与group.index的ETag观察与同步机制.md) | 服务端 ETag 来源、四 SDK 被动观察、agent.md 下载触发、group.index 显式 pull 与 CAS |
 | - | [CHANGELOG-0.5.6](CHANGELOG-0.5.6.md) | **0.5.6 版本更新日志**：首次签名者回源、下载提交前验签、消息窗口、显式 change-seed 与语言能力边界 |
 | 01 | [快速开始](01-快速开始.md) | 安装、三主体模型、最小示例 |
 | 02 | [WebSocket协议](02-WebSocket协议.md) | 握手流程、严格布尔 peer 能力、各层大小限制、消息格式、裸 WebSocket |
@@ -98,6 +101,7 @@ Group 的成员 block/status、暂停群权限和两阶段群主转让，以及
 | 实现、移植或审查 0.5.22 SDK，查看 Stage/CAS、配套服务修复、读缓存及 Rust 验收清单 | [0.5.22 SDK 开发与移植指南](0.5.22-SDK开发与移植指南.md) |
 | 接入或升级 0.5.24，查看当前消息、无任务 Ownership、两个 local 场景、缓存及凭证组织 | [0.5.24 SDK 应用集成指南](0.5.24-SDK应用集成指南.md) |
 | 实现、移植或审查 0.5.24，核对提交／ACK、NS 事实、远端 CAS、local 身份隔离和缓存新鲜度 | [0.5.24 SDK 开发与移植指南](0.5.24-SDK开发与移植指南.md) |
+| 核查 0.5.25 的 Pull／volatile／群恢复、Ownership 缓存、名片下载退避与分域路由变更 | [parity 当前章节](../../python/CHANGES_FOR_PARITY.md#v0525--已提交-v0524-基线变更未发布)及各端 CHANGELOG；基线统一为已提交 0.5.24 |
 | 0.5.24 应用按主题读：身份、消息、resolve、Ownership、文件缓存、凭证组织和升级 | `0.5.24-SDK应用集成指南.md` §2 L21-75、§3 L76-132、§4 L133-168、§5 L169-298、§6 L299-321、§7 L322-366、§9 L386-401；local bind L227-245、local transfer L246-267 |
 | 0.5.24 移植按主题读：消息提交、名片、观察、Ownership、缓存、PKI、凭证组织及语言差异 | `0.5.24-SDK开发与移植指南.md` §3 L32-84、§4 L85-92、§5 L93-122、§6 L123-217、§7 L218-245、§8 L246-261、§9 L262-297、§10 L298-325；Rust §11 L326-339、验收 §12 L340-354 |
 | 首次使用 SDK | [01-快速开始](01-快速开始.md) |

package/_packed_docs/sdk/INDEX.md

@@ -14,6 +14,7 @@
 | [0.5.22 SDK 开发与移植指南](0.5.22-SDK开发与移植指南.md) | 后台退避 · 群状态 · 两种绑定与 Stage/CAS · 消息内部消费 · 撤销同步 · 组织恢复及配套服务修复 · 默认读缓存 · Rust 清单 |
 | [0.5.24 SDK 应用集成指南](0.5.24-SDK应用集成指南.md) | 当前身份与消息接入 · 无任务 Ownership · local 双／三身份编排 · resolve 与文件缓存 · 凭证组织 · 升级 |
 | [0.5.24 SDK 开发与移植指南](0.5.24-SDK开发与移植指南.md) | peer／batch 提交 · NS 事实与远端 CAS · local 短连接 · 观察与 PKI 缓存 · 持久化边界 · 语言差异和验收 |
+| 0.5.25 CHANGELOG：[Python](../../python/CHANGELOG.md)、[Go](../../go/CHANGELOG.md)、[TS](../../ts/CHANGELOG.md)、[JS](../../js/CHANGELOG.md) | Pull／volatile／群恢复 · Ownership 缓存 · 名片下载退避 · 分域发现；实现差异与验证边界见 [parity](../../python/CHANGES_FOR_PARITY.md#v0525--已提交-v0524-基线变更未发布) |
 | [CHANGELOG-0.5.6](CHANGELOG-0.5.6.md) | **0.5.6 版本更新日志**：首次签名者回源 · 下载提交前验签 · 消息窗口 · 显式 change-seed · 语言能力边界 |
 | [01-快速开始](01-快速开始.md) | 安装 · 三主体模型 · 最小示例 · 多语言构造 |
 | [02-WebSocket协议](02-WebSocket协议.md) | 握手流程 · 严格布尔 peer 能力声明 · JSON-RPC 消息格式 · 裸 WebSocket 示例 |
@@ -38,6 +39,7 @@
 | [ProtectedHeaders用法专题](ProtectedHeaders用法专题.md) | `protected_headers` 四端 API · 实例级/单次调用 · E2EE V2 HMAC 完整性 · 接收信任边界 |
 | [E2EE_V2消息通信时序图](E2EE_V2消息通信时序图.md) | V2 P2P/GROUP 明文与加密主链路 |
 | [06-API手册](06-API手册.md) | AIDStore · resolve 完整输入输出/frontmatter/ownership 与 owner.md 缓存 · AID · AUNClient · 四 SDK access token getter · Python PushFacade · P2P TTL volatile 消息 · Message/Group History 与已读门面 · 已读变更和本地补偿完成 · 消息来源与 Pull 同步生命周期 · 三类批量事件/完整 single fallback · SDK 50k 内存去重/应用持久幂等 · E2EE 高级 API · RPC 索引 |
+| [agent.md 与 group.index 的 ETag 观察与同步机制](agent.md与group.index的ETag观察与同步机制.md) | 服务端 ETag 来源 · 四 SDK 被动观察 · agent.md HEAD/GET 触发 · group.index 显式 pull 与 CAS · 协议和源码索引 |
 | [07-错误处理](07-错误处理.md) | Result · Python `ErrorInfo.cause` · 错误类层级 · 错误码 · 重试 |
 | [08-最佳实践](08-最佳实践.md) | 幂等连接 · 消息同步/History · AUNClient 级 Pull Gate（同 namespace 单飞、客户端最多 4 个并行）· group.index · 测试数据保护 |
 | [09-payload-reference](09-payload-reference.md) | message / group / thought payload 格式 |
@@ -72,6 +74,7 @@
 
 - 当前身份与消息接入、无任务 Ownership、两个 local 场景、名片及文件缓存、凭证组织与升级 → [应用集成指南](0.5.24-SDK应用集成指南.md)
 - 三主体分层、提交／ACK、NS 事实和远端 CAS、local 身份隔离、缓存新鲜度、语言差异与验收 → [开发与移植指南](0.5.24-SDK开发与移植指南.md)
+- 0.5.25 对照已提交 0.5.24 的增量、四端实现落点与验证边界 → [parity 当前章节](../../python/CHANGES_FOR_PARITY.md#v0525--已提交-v0524-基线变更未发布)
 
 ### 身份与认证
 
@@ -90,6 +93,8 @@
 - legacy ownership SDK 实现/移植、声明字节与验签、escrow、metadata 持久化和恢复 → [Ownership SDK实现指南（legacy）](Ownership-SDK实现指南.md)
 - legacy ownership P2P/proof/agent.md/escrow schema 与现有 RPC、HTTP 授权边界 → [Ownership协议定义（legacy）](../protocol/Ownership协议定义.md)
 - agent.md 上传/下载/检查、`remote_etag` / `last_modified` 自动观察、`requester` / `peer` / `group` 角色 → [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)、[远程 agent.md 缓存与 ETag 透传方案](../agent.md/远程agent.md缓存与etag透传方案.md)
+- agent.md 的版本观察与下载触发、group.index 的 stale/pull/CAS 同步流程及服务端协议 → [ETag 观察与同步机制](agent.md与group.index的ETag观察与同步机制.md)
+- `group.index` 的 SDK 读写门面及 `expected_index_etag` 冲突处理 → [06-API手册](06-API手册.md)、[Group RPC 手册](09-group-rpc-manual.md)
 - AID 构造约束与多语言入口 → [01-快速开始](01-快速开始.md)、[06-API手册](06-API手册.md)
 - 认证链路、后台刷新和当前 token getter（`get_access_token()` / `getAccessToken()` / `GetAccessToken()`）→ [03-核心概念](03-核心概念.md)、[04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)
 - AID 托管恢复 / 跨设备复制 → [09-custody-api-manual](09-custody-api-manual.md)
@@ -167,6 +172,10 @@ TypeScript 身份与消息接线、Ownership 审批恢复、resolve、默认缓
 
 定义消息 peer／batch／Gate、Ownership NS 事实和远端 CAS、Stage、local 专属 slot 与身份代际、展示及文件缓存、PKI 和 Credential 查询新鲜度、组织 checkpoint。列出四端兼容差异、Rust 核查与分层验收，不将已有专项证据等同完整发布验证。
 
+### 0.5.25 更新日志与跨端对齐
+
+[变更与对齐清单](../../python/CHANGES_FOR_PARITY.md#v0525--已提交-v0524-基线变更未发布) 对照已提交 0.5.24，说明 Pull 无进展暂停、volatile 直接交付、群恢复、Ownership 正文与证书证据复用、agent.md 下载退避和分域发现；四端 CHANGELOG 提供接口级摘要，parity 列出实现落点、语言差异与验证边界。
+
 ### CHANGELOG-0.5.6
 
 以 0.5.5 发布提交为基线，汇总四个 SDK 的首次签名者证书回源、`group.index` / indexed settings / `agent.md` 下载提交前校验、可信缓存读取、消息窗口、inline realtime、mention mode、显式 change-seed，以及 Python、Go、TS 和浏览器 JS 的能力边界。