@agentunion/fastaun 0.5.20 → 0.5.22

package/_packed_docs/sdk/09-storage-rpc-manual.md

@@ -120,12 +120,54 @@
 
 ## SDK 封装状态
 
-Python / Go / TypeScript / JavaScript SDK 均提供 storage low-level 与 VFS 门面。普通应用优先使用 SDK VFS：`write_bytes` / `upload_file` 会先 `check_upload`，小对象走 `put_object`，大对象走 `create_upload_session` → HTTP PUT → `complete_upload`，秒传路径用 `complete_upload(skip_blob=true)`；`read_bytes` / `download_file` 优先尝试 inline `get_object`，超限时回退 `create_download_ticket`；`touch` 直接封装 `storage.fs.touch`。需要精确控制 ACL、token、软链、卷、批量操作或 URL 字段时，再直接调用本手册中的 `storage.*` RPC。
+Python / Go / TypeScript / JavaScript SDK 均提供 storage low-level 与 VFS 门面。普通应用优先使用 SDK VFS：`write_bytes` / `upload_file` 会先 `check_upload`，小对象走 `put_object`，大对象走 `create_upload_session` → HTTP PUT → `complete_upload`，秒传路径用 `complete_upload(skip_blob=true)`；`read_bytes` 优先尝试 inline `get_object`，超限时回退 `create_download_ticket`。Python / Go / TypeScript 的 `download_file` / `downloadFile` 从下载票据及 HTTP GET 路径读取并写入本地文件；JavaScript 的 `downloadFile` 复用字节读取路径并返回正文数据。`touch` 直接封装 `storage.fs.touch`。需要精确控制 ACL、token、软链、卷、批量操作或 URL 字段时，再直接调用本手册中的 `storage.*` RPC。
 
 四个 SDK 的 VFS 会优先按实际字节识别 PNG、JPEG、GIF、BMP、WebP、PDF、gzip、ZIP、MP4、JSON、HTML 和 UTF-8 文本，再回退文件扩展名及 `application/octet-stream`。大文件上传时，`create_upload_session`、HTTP PUT 和 `complete_upload` 使用同一个 `Content-Type`；如果 session 响应额外提供 `headers`，SDK 会保留其它 header 并以实际识别结果替换其中的 Content-Type。OSS 预签名 PUT 会把 Content-Type 纳入签名校验，缺失或不一致时可直接返回 403。
 
 直接调用底层 RPC 的高级客户端必须自行完成相同编排：先确定内容类型，再把同一个值传给 session 和 complete，并在 PUT 请求中发送一致的 `Content-Type`。绕过 VFS 后未遵守该约束属于调用方式错误。
 
+## SDK 默认读缓存
+
+从 0.5.22 起，四个 SDK 的 Storage 和 Group FS 读缓存由客户端默认启用，服务端无需逐个对象显式授权缓存。已接入缓存的元数据查询（如 `head_object`、目录列表、`fs.stat/lstat/find/df`）与完整小正文读取适用下表；不是任意 RPC 或大文件下载都缓存。
+
+| 响应策略 | SDK 行为 |
+|----------|----------|
+| 不返回 `read_cache`，或值为 `null` | 元数据默认 TTL 60 秒；正文实际大小不超过 65,536 字节、SHA-256 合法且校验通过时，默认缓存正文 |
+| `read_cache.reusable: false` | 此响应不进入可复用读缓存，用于显式禁止特定文件缓存 |
+| 显式允许策略 | 元数据须 `reusable: true`，正文还须 `inline: true`；省略 `max_age_ms` 时默认 60 秒，有限正数 TTL 最多使用 60 秒 |
+
+`read_cache` 是读取响应中的策略对象，不是应用写入文件时的通用选项。缺省策略的 64 KiB 上限使用实际正文长度；元数据可独立缓存，不因文件正文较大而自动禁用。显式允许策略省略 TTL 时采用 60 秒；显式 null、非正数或非法 TTL 均不复用，不把空对象或其它显式异常值解释为缺省允许。
+
+应用可为特定读取设置 TypeScript / JavaScript `noCache: true`、Python `no_cache=True` 或 Go 对应 VFS Options 的 `NoCache: true`。TS/JS 的底层 RPC 和 Group FS 也兼容 `no_cache`，TypeScript Storage VFS 的类型化选项使用 `noCache`。SDK 消费该选项并跳过有效缓存命中，仍可发送已有 SHA-256 进行条件校验；它不表示 no-store，新结果仍按响应策略缓存。对于支持 `consistency` 的底层 RPC，`consistency: "authoritative"` 则完全旁路 SDK 读缓存，规则见下节。
+
+正文过期或显式刷新时，SDK 可带 `if_sha256`；服务端返回 `not_modified: true` 时只复用已有且已验证的正文，无本地正文时不能将该响应当作空内容。缓存键隔离调用身份及业务参数；写入和相关变更使缓存失效，重新鉴权仍由联网读取执行。范围读取和直接调用预签 RPC 不使用普通正文缓存；VFS 的完整下载流程可按下文缓存已验证的 inline 大小正文。
+
+下载票据路径也可缓存已下载并校验的 inline 大小正文，TTL 最多 60 秒；Python / Go / TypeScript 的下载入口可复用对应 `get_object` 热缓存，不必先重传正文。过期后可用 SHA-256 向下载票据接口条件校验，摘要未变则直接复用本地正文；正文大于 inline 缓存上限时仍按原下载路径传输。
+
+有限次 token、ACL 和分享授权的 inline 读取只有返回正文才计次；inline 和大对象匹配 SHA 而只返回无正文 `not_modified` 均不计次，额度耗尽后仍可进行该条件验证。SDK 本地缓存命中不请求 Storage，因此不计次；HEAD 等纯元数据查询不计次。限次授权可缓存，TTL 受对象及授权有效期限制；联网验证继续检查撤销、过期、身份和权限。大对象按下载授权计次：非 `not_modified` 请求签发 URL 或授权 302 时计一次，直接复用已签发的正文下载 URL 属于同次授权；再次向 Storage 申请 URL／授权跳转按新授权计次；Storage 不代理外部 OSS 正文，不统计 OSS 实际 GET 次数。范围参数错误、正文读取失败、下载 URL／票据准备失败不扣次；`storage.get_object_url` 仅返回稳定地址，不计次，权限和额度预检保持。响应准备成功后发生网络中断，不承诺退回次数。
+
+普通文件 API 读取 `default/sub_aids/{sub_aid}/owner.md` 同样适用上述默认规则；Ownership 管理、维护和新鲜共识的权威读取继续旁路。`resolve` 的 ownership 展示快照使用自己的 TTL 和刷新选项，不能替代授权时的新鲜共识检查。
+
+### 策略字段与条件读取
+
+| 字段 | 类型 | 含义 |
+| --- | --- | --- |
+| `read_cache` | object / null，可省略 | 响应缓存策略；缺省／null 使用上表默认规则 |
+| `read_cache.reusable` | boolean | `false` 禁止复用该响应，显式允许策略使用 `true` |
+| `read_cache.inline` | boolean | 显式策略是否允许缓存完整正文；`false` 不妨碍符合条件的元数据独立缓存 |
+| `read_cache.max_age_ms` | integer，可省略 | 有效期上限，单位毫秒；显式允许策略省略时默认 60,000；正数最多使用 60,000，并受对象及授权剩余有效期限制；显式 null／非正数／非法值不复用 |
+| `read_cache.max_inline_bytes` | integer | 服务端允许 inline 正文的大小上限（字节）；不表示大对象正文也可缓存 |
+| `if_sha256` | string，可选请求字段 | 本地完整正文的 64 位十六进制 SHA-256，用于条件读取，不用于范围正文 |
+| `not_modified` | boolean，可选响应字段 | 摘要未变化；仍须通过当前访问校验，响应可省略正文或下载票据 |
+
+收到 `not_modified: true` 时，无论当前响应是否允许继续缓存，SDK 都必须校验响应摘要与已有、已验证完整正文的摘要一致；无本地正文须重新请求完整对象，不能返回空内容。它不等于 HTTP 304，也不延长票据期限。`noCache`／`no_cache` 是 SDK 本地选项，不作为服务端 `get_object` 或下载票据的业务参数。四端对齐落点见 [parity 块⑦](../../python/CHANGES_FOR_PARITY.md#块⑦-storage--group-fs-默认读缓存)。
+
+### 持久化与新鲜度
+
+Node.js TypeScript、Python、Go 的索引位于 `{aunPath}/.cache/storage/index.sqlite3`，正文按摘要存于同目录 `blobs/{前2位}/{sha256}`；浏览器使用既有 `aun-keystore` IndexedDB 的 `storage_cache_index`／`storage_cache_blobs`。当前默认内存正文预算 32 MiB、持久正文预算 256 MiB，更多索引容量、淘汰及故障降级要求见 [0.5.22 移植指南](0.5.22-SDK开发与移植指南.md#61-storage--group-fs-默认读缓存)。这不是新增 JSONL 业务记录或公共配置接口。
+
+服务端 `max_age_ms` 扣除本次授权／对象解析所用元数据的已缓存年龄及解析耗时，使服务端元数据可能陈旧时间与 SDK 复用时间之和不超过 60 秒，同时受对象及授权剩余有效期限制。热命中不联网，也不续期 TTL。其它客户端写入或撤销权限可能在剩余 TTL 内仍未被本端观察，默认最多 60 秒；需要立即观察时显式刷新，权威管理／授权仍用权威入口。正文缓存不持久复用下载 URL、临时 token 或签名；票据过期后重新申请。重启恢复、原始 RPC 正文和权限查询白名单的已对齐分支及定向测试范围统一列在上述 parity 节，完整联网矩阵仍须单独验收。
+
 ## 权威读取与完整发布
 
 `storage.head_object/get_object` 和 `storage.fs.stat` 的 `consistency: authoritative` 绕过正负缓存，核对当前存在性、规范路径及完整正文摘要。权威结果包含 `consistency`、布尔 `exists`、请求 `owner_aid/bucket/path` 和 Unix 秒 `observed_at`；存在时返回完整对象元数据，仅 `get_object` 另含严格 Base64 的完整 `content`，head/stat 不返回正文。恢复未完成、权限错误、网络或数据库故障不能返回 `exists=false`。私有路径仍检查既有 ACL，匹配的 `r` grant 不授权普通下载票据。
@@ -198,6 +240,7 @@ result = await client.call("storage.put_object", {
 | `bucket` | string | 否 | 存储桶，默认 `"default"` |
 | `owner_aid` | string | 否 | 所有者 AID，默认当前用户 |
 | `consistency` | string | 否 | 传 `authoritative` 时绕过缓存并返回完整权威对象 |
+| `if_sha256` | string | 否 | 本地完整正文的 64 位十六进制 SHA-256；普通条件读取时使用，权威读取仍返回完整对象 |
 
 ### 响应
 
@@ -206,13 +249,15 @@ result = await client.call("storage.put_object", {
 | `owner_aid` | string | 所有者 AID |
 | `bucket` | string | 存储桶 |
 | `object_key` | string | 对象路径 |
-| `content` | string | base64 编码内容 |
+| `content` | string | base64 编码内容；`not_modified: true` 时可省略 |
 | `content_type` | string | MIME 类型 |
 | `size_bytes` | integer | 对象大小（字节） |
 | `sha256` | string | SHA-256 哈希 |
 | `version` | integer | 版本号 |
 | `updated_at` | integer | 更新时间戳 |
 
+普通读取还可返回 `read_cache`（object）及 `not_modified`（boolean）；字段和本地正文复用条件见 [策略字段与条件读取](#策略字段与条件读取)。只有提供了匹配 `if_sha256` 的条件读取才可将缺少 `content` 的 `not_modified` 结果与已有正文组合，不能当作空对象。
+
 > **注意**：实现不返回 `etag`（与 put_object/head_object 不同）。
 
 ### 示例
@@ -230,7 +275,7 @@ content = base64.b64decode(result["content"])
 
 查询对象元数据，不返回内容。
 
-可传 `consistency: authoritative`，返回当前存在性与完整对象元数据；完整契约见 [权威读取与完整发布](#权威读取与完整发布)。
+可传 `consistency: authoritative`，返回当前存在性与完整对象元数据；完整契约见 [权威读取与完整发布](#权威读取与完整发布)。
 
 ### 参数
 
@@ -257,6 +302,9 @@ content = base64.b64decode(result["content"])
 | `expire_at` | integer | 过期时间戳（0 表示不过期） |
 | `created_at` | integer | 创建时间戳 |
 | `updated_at` | integer | 更新时间戳 |
+| `read_cache` | object | 可选缓存策略；不返回／null 时采用 SDK 默认元数据策略，见 [策略字段](#策略字段与条件读取) |
+
+HEAD 只查询元数据，不消耗 token、ACL 或分享的正文读取次数。
 
 ---
 
@@ -272,6 +320,9 @@ content = base64.b64decode(result["content"])
 | `object_key` | string | 是 | 对象路径 |
 | `bucket` | string | 否 | 存储桶，默认 `"default"` |
 | `owner_aid` | string | 否 | 所有者 AID，默认当前用户 |
+| `expected_version` | integer | 否 | 非负 JSON 整数；指定时使用版本 CAS 删除 |
+
+省略 `expected_version` 保持既有无条件删除行为。提供 `0` 时仅匹配对象不存在并返回 `deleted: false`；提供正整数时必须存在相同版本的对象才删除。存在性不符、版本不符或检查后对象被替换导致 CAS 失败时返回 `-32009`（Version conflict），不得继续删除新版本。字符串、浮点数、布尔值及负数不是合法版本条件。收到 `-32009` 后，先权威读取当前对象及原件摘要；目标已不是本任务原件时停止删除，不得改用新版本号自动重试。请求结果未知时，先核对目标是否已删除，再决定是否重放原条件请求。
 
 ### 响应
 
@@ -582,7 +633,7 @@ for obj in result["items"]:
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `upload_url` | string | 上传用 presigned URL |
+| `upload_url` | string | 上传用 presigned URL |
 | `session_id` | string | 规范 agent.md/owner.md 的完整原子发布会话；普通对象不保证返回 |
 | `expire_at` | integer | URL 过期时间戳 |
 | `owner_aid` | string | 所有者 AID |
@@ -597,8 +648,8 @@ for obj in result["items"]:
 | `size_bytes` | integer | 声明的文件大小 |
 | `overwrite` | boolean | 是否覆盖已有对象 |
 
-客户端获得 `upload_url` 后，通过 HTTP PUT 上传文件数据。普通对象不保证返回 `session_id`；规范 agent.md/owner.md 会话另返回 `session_id`，complete 必须沿用同一会话。
-
+客户端获得 `upload_url` 后，通过 HTTP PUT 上传文件数据。普通对象不保证返回 `session_id`；规范 agent.md/owner.md 会话另返回 `session_id`，complete 必须沿用同一会话。
+
 规范 `default/agent.md` 与 `default/sub_aids/{sub_aid}/owner.md` 的上传会话使用独立临时对象，`create_upload_session` 返回 `session_id`；新客户端完成这些规范文件时必须携带同一 `session_id`。服务端核对会话的认证申请者、目标及有效期，验证完整内容后原子发布，失败保留旧完整文件。普通对象保持既有上传流程，不保证返回 `session_id`；该临时会话不记录 Ownership 关系事实或路径历史。
 
 > 当前实现会对 BlobStore 返回的 loopback URL 做对外地址规范化：优先使用 `KITE_STORAGE_EXTERNAL_URL`，否则按 `storage.{issuer}` 形式改写。对外地址不可使用 `127.0.0.1` 或 `localhost`。
@@ -659,6 +710,8 @@ for obj in result["items"]:
 | `owner_aid` | string | 否 | 所有者 AID，默认当前用户（公开对象可指定其他 AID） |
 | `expire_in_seconds` | integer | 否 | URL 有效期（秒），默认 3600 |
 
+支持可选 `if_sha256`（string，64 位十六进制摘要）；摘要匹配时可返回 `not_modified: true`、对象元数据及 `read_cache`，不签发新的 URL／token。调用方须持有匹配且已验证的正文，否则重新请求完整下载票据。权威对象存在性与完整原件校验使用 `storage.head_object/get_object` 或 `storage.fs.stat` 的权威入口。
+
 ### 响应
 
 | 字段 | 类型 | 说明 |
@@ -677,6 +730,8 @@ for obj in result["items"]:
 
 `url` 是推荐使用的干净链接。访问时 storage 服务实时鉴权：public 文件直接通过，private 文件需 `?t=` token 或 `Authorization: Bearer <AID JWT>` 头证明 owner 身份。鉴权通过后 storage 302 到 blob 后端完成实际下载，这一步对客户端完全透明。
 
+普通票据响应还可带 `read_cache`。该策略供 SDK 判断下载后正文是否可缓存，票据 URL、token、headers 及 `expire_at` 不因此成为可长期复用的正文缓存；条件未变化响应的处理见 [策略字段与条件读取](#策略字段与条件读取)。
+
 ### 数据面 HTTP 下载流程
 
 1. 通过控制面 RPC `storage.create_download_ticket` 获取短 TTL 的下载票据，不把长期对象 URL 当作最终下载地址。
@@ -921,7 +976,9 @@ share_url = result["url"]  # https://alice.agentid.pub/s/Ab3xK9mZ2q
 |------|------|------|------|
 | `share_id` | string | 是 | 分享短码 |
 
-**响应**：小对象返回 `content`；大对象返回 `download_url`。同时返回 `object_id`、`object_key`、`path`、`size_bytes`、`content_type`、`sha256`。
+可选 `if_sha256`（string，64 位十六进制摘要）用于已验证完整正文的条件读取。
+
+**响应**：小对象返回 `content`；大对象返回 `download_url`，该响应不能按空 `content` 解码。共同返回 `object_id`、`object_key`、`path`、`size_bytes`、`content_type`、`sha256` 和可选 `read_cache`。当前访问校验通过且摘要一致时可返回 `not_modified: true` 并省略正文／URL，复用要求见 [策略字段与条件读取](#策略字段与条件读取)。有限次分享允许 SDK 复用已验证的本地正文；本地缓存命中及无正文的 `not_modified` 不消耗分享次数；inline 返回正文时计次，大对象按下载授权签发／跳转计次，见[默认读缓存](#sdk-默认读缓存)。
 
 ---
 

package/_packed_docs/sdk/09-/345/207/255/350/257/201/346/234/215/345/212/241RPC/346/211/213/345/206/214.md

@@ -0,0 +1,73 @@
+# 凭证服务 RPC 手册
+
+本文按 Credential Service 当前服务端 dispatcher 列出 RPC。`credential.health` 和不带凭证 CID 的 `credential.status` 用于控制面诊断；`credential.register/revoke`、带 CID 的 `credential.status` 和 `credential.revocationList` 是业务 RPC，经 Gateway service-plane 调用。
+
+## 方法索引
+
+| 方法 | 用途 |
+|------|------|
+| [credential.health](#credentialhealth) | 服务健康诊断 |
+| [credential.status](#credentialstatus) | 查询服务状态或凭证状态证明 |
+| [credential.register](#credentialregister) | 登记完整已签名凭证并取得回执 |
+| [credential.revoke](#credentialrevoke) | 吊销凭证 |
+| [credential.revocationList](#credentialrevocationlist) | 查询签名吊销事件增量 |
+
+## 通用约定
+
+凭证是 `aun-cap/1` 签名对象。服务端只接受完整已签名凭证，不提供 `credential.prepare` RPC。`credential.create`、`verifySignature`、`verify` 和 `verifyRegistrationReceipt` 是 SDK 本地 helper，不是服务端 RPC。
+
+业务请求使用 `request_id`、一次性 `nonce` 和 `request_binding`。绑定需匹配完整方法名、Credential Service target、业务参数摘要和有效时间窗；单凭证请求还绑定非空 `credential_cid`。只有 `credential.revocationList` 没有单一凭证目标，其绑定中的 `credential_cid` 固定为空字符串。请求不得把 `_auth.aid` 当作可由调用方自行声明的授权身份。
+
+## credential.health
+
+无业务参数。返回 `status`（`healthy` 或 `degraded`）、`implementation` 和 `details`，包含服务 AID、数据库、Kernel/Gateway 连接、签名身份就绪状态及运行时间。该方法用于诊断，不表示某个凭证有效。
+
+## credential.status
+
+不带 `credential_cid` 时返回服务状态摘要，包含 `module`、`status`、服务 AID、数据库连接、签名身份和运行时间；该形式是诊断入口。
+
+带 `credential_cid` 时执行凭证业务查询，必须提供 `request_id`、`nonce`、`request_binding`。可选 `include_chain: true` 返回父链状态。响应为 Credential Service 签名的 `aun-credential-status/1` proof，包含凭证 CID/hash、综合状态、叶凭证状态、issuer、subject、到期时间、事件序号、`asOf`、`proofExpiresAt`、responder、request ID、nonce、target 和签名；关联组织时还包含 `orgId`。
+
+`proofExpiresAt` 是状态证明的截止时间，`expiresAt` 是凭证自身到期时间。未知状态、过期 proof 或未知父链不能用于授权放行。
+
+## credential.register
+
+登记完整已签名凭证。转交登记时，`registration_authorization` 必须由凭证 issuer 签署；转交服务不会成为 registrar。
+
+| 参数 | 必需 | 说明 |
+|------|:---:|------|
+| `request_id`、`nonce` | 是 | 幂等请求标识和一次性随机数 |
+| `registrar_aid` | 是 | 必须等于 `credential.iss` |
+| `credential` | 是 | 完整 `aun-cap/1` 对象，含签名 |
+| `request_binding` | 是 | 绑定方法、服务 target、参数摘要、时间窗和 CID |
+| `registration_authorization` | 条件 | 认证调用者不是 issuer 时必需 |
+| `proof_chain` | 条件 | 有父凭证时提供；若凭证内也携带，二者必须一致 |
+
+成功返回 `credentialCid`、`status=active`、`registeredAt` 和 Credential Service 签名的 `registrationReceipt`。登记回执证明登记结果，不单独授予能力；Org 入组仍须由 Org Service 独立验凭证和回执并完成成员关系最终化。
+
+## credential.revoke
+
+吊销凭证；默认级联吊销子凭证。除参数绑定外，服务会核实调用身份是 issuer 或登记时记录的授权吊销主体。
+
+| 参数 | 必需 | 说明 |
+|------|:---:|------|
+| `request_id`、`nonce`、`request_binding` | 是 | 本次吊销请求及其目标、摘要和时间窗绑定 |
+| `registrar_aid`、`credential_cid`、`reason_code` | 是 | 吊销主体、目标 CID 和原因码 |
+| `reason` | 否 | 脱敏原因说明 |
+| `cascade` | 否 | 是否级联，默认 `true` |
+| `org_id`、`registration_request_id` | 条件 | 受限吊销授权要求时绑定组织和原登记操作 |
+| `registration_authorization` | 条件 | 补偿尚未登记的 CID 时提供原 issuer 授权 |
+
+成功返回 `credentialCid`、`status=revoked`、`revokedAt`、`eventSeq` 和 `cascadeCount`。同一 method、request ID 和参数摘要重试从持久去重记录返回原结果，进程重启后仍有效；同一 request ID 更换摘要返回 `CREDENTIAL_IDEMPOTENCY_KEY_REUSE`。持久结果必须匹配原 CID 和 revoked 状态；记录损坏或状态不明返回 `CREDENTIAL_STATUS_UNKNOWN`，不能当作补偿已完成。
+
+## credential.revocationList
+
+查询吊销事件增量。请求可提供 `issuer_aid`、`since_event_seq` 或 `cursor`、`limit`，并必须提供 `request_id`、`nonce`、`request_binding`。`limit` 默认 1000，最大 1000。
+
+响应包含 `events[]`、`next_cursor`、`as_of`、`expires_at`、`responder`、`request_id`、`nonce`、`target`、`issuer_aid` 和签名。每个事件包含 `event_seq`、`cid`、`reason_code`、`revoked_at`、`revoked_by_aid`，可选 `reason` 和 `cascade_root_cid`。客户端应验证服务签名与证明时间窗，并按序号续查。
+
+SDK 0.5.22 将已验签的 `credential.revoked`／`credential.revocationList` 推送和列表页持久合并，单条事件不推进分页位置，旧分页不能覆盖新撤销证据。后台兜底拉取在连接后一小时首次执行，此后每小时一次；这是 SDK 调度策略，不是 RPC 的限频或服务端分页契约。存储、身份隔离和 proof 要求见 [SDK 移植指南](凭证与组织服务SDK开发与移植指南.md#54-撤销同步与持久快照0522)。
+
+## 错误
+
+业务错误码位于 JSON-RPC `error.data.error_code`，包括 `CREDENTIAL_INVALID`、`CREDENTIAL_SIGNATURE_INVALID`、`CREDENTIAL_CHAIN_INVALID`、`CREDENTIAL_EXPIRED`、`CREDENTIAL_REVOKED`、`CREDENTIAL_REQUEST_BINDING_INVALID`、`CREDENTIAL_AUTHENTICATION_INVALID`、`CREDENTIAL_IDEMPOTENCY_KEY_REUSE`、`CREDENTIAL_NOT_FOUND` 和 `CREDENTIAL_STATUS_UNKNOWN`。状态未知或服务/数据库不可用不能按有效处理。未注册的方法返回 JSON-RPC `Method not found`。

package/_packed_docs/sdk/09-/347/273/204/347/273/207/346/234/215/345/212/241RPC/346/211/213/345/206/214.md

@@ -0,0 +1,90 @@
+# 组织服务 RPC 手册
+
+本文按 Org Service 当前服务端 dispatcher 列出 RPC。组织业务方法经 Gateway service-plane 路由；普通调用使用 `client.org` facade 或 `client.call(method, params)`。
+
+## 方法索引
+
+| 方法组 | 方法 |
+|------|------|
+| 诊断 | `org.health`、`org.status` |
+| 生命周期 | `org.lifecycle.create/get/list/update/suspend/resume/dissolve/transfer/transferAccept` |
+| 成员关系 | `org.member.join/approveJoin/rejectJoin/invite/inviteAccept/inviteReject/renewCredential/list/get/leave/kick/offboard/freeze/unfreeze/ban/unban` |
+| 凭证查询 | `org.credential.getStatus`、`org.credential.revocationList` |
+| 审计与授权 | `org.audit.query`、`org.authz.check` |
+| 内部接口 | `org.member.add`、`org.membership.reserve/get/commit/release` |
+| 保留但未实现 | `org.resource.create`、`org.task.create`、`org.host.add`、`org.workflow.create` |
+
+## 通用请求约定
+
+除 `org.health`、`org.status` 和 Name Service 受信内部读取 `org.lifecycle.get` 外，Org dispatcher 会验证完整方法名对应的 `client_signature`。业务请求由 `org.prepareRequest` / `prepare_request` / `PrepareRequest` 准备：加入与组织匹配的 `aad.org_id`，并按具体方法生成 `request_binding`、nonce 和外层签名。认证主体由会话确定，不能由请求参数替代。
+
+公开组织的 `org.lifecycle.get/list` 按可见性返回公开字段；显式请求受保护字段时仍需对应成员授权。`org.member.list/get`、`org.credential.getStatus` 和 `org.credential.revocationList` 是受保护业务读取，需当前成员 binding、CAP、AAD、request binding 和签名。读取方法不能因无副作用而跳过授权。
+
+下面表格中的业务字段不含连接级认证字段及请求准备字段。成功结果按 JSON-RPC `result` 返回；结构化业务错误码位于 `error.data.error_code`。
+
+## 诊断方法
+
+| 方法 | 参数 | 结果 |
+|------|------|------|
+| `org.health` | 无 | `status`、实现信息、服务 AID、数据库和签名身份可用性 |
+| `org.status` | 无 | 模块状态、服务 AID、数据库连接、运行时间和构建信息 |
+
+诊断结果只反映服务状态，不代表组织成员或凭证授权有效。
+
+## 组织生命周期
+
+| 方法 | 主要业务参数 | 成功结果 |
+|------|------|------|
+| `org.lifecycle.create` | `org_id`、`name`、`exttype`、`join_mode`、`visibility`、`owner_aid`、初始 `membership_binding`、`credential_template`、`registration_authorization` | `organization`、初始 binding、凭证 CID、登记回执及可选 `operation_id` |
+| `org.lifecycle.get` | `org_id`、可选 `fields[]` | 可见的 `organization` 和 `version` |
+| `org.lifecycle.list` | 可选 `status`、`page`、`size`、`cursor` | `items[]`、分页信息和 `next_cursor` |
+| `org.lifecycle.update` | `org_id`、`patch`、`expected_version` | 更新后的组织和新版本 |
+| `org.lifecycle.suspend` / `resume` | `org_id`、`expected_version`；suspend 可带 `reason` | 更新后的组织和新版本 |
+| `org.lifecycle.dissolve` | `org_id`、可选 `force`、`reason` | `operation_id` 和 `dissolving` / `dissolved` 状态 |
+| `org.lifecycle.transfer` | `org_id`、`target_member_aid`、`expires_at` | `transfer_id`、`proposal_hash` 和签名提案 |
+| `org.lifecycle.transferAccept` | `org_id`、`transfer_id`、`proposal_hash`、`target_signature`、`public_key`、阶段材料；`stage=rekey` 或 `finalize` | rekey 返回 `pending_finalization` 和新证书；finalize 返回组织、双方新 binding/CID 和登记回执 |
+
+写操作按 `expected_version` 执行版本检查，并使用稳定 `request_id` 与 nonce。组织创建和转让涉及多个持久阶段；断线后应按原请求材料恢复，不要重新生成组织身份或密钥。详见[凭证与组织服务应用集成指南](凭证与组织服务SDK应用集成指南.md)。
+
+## 成员关系
+
+0.5.22 配套服务修复组织创建补偿与转让恢复：创建补偿遇到 `CREDENTIAL_IDEMPOTENCY_KEY_REUSE` 时保存冲突并停止自动补偿；转让开始换钥前复核当前证书／公钥代际，以规范 DER 公钥的 Base64 调用 CA，并将新旧 owner 的成员替换、完整成员包定向通知一起持久化。通知失败保留待办并按组织轮转；应用保留原任务、原请求及原密钥，不用更换 request ID 消除不确定结果。完整恢复要求见 [应用指南](凭证与组织服务SDK应用集成指南.md#6-所有权转让与实体材料)。
+
+| 方法 | 主要业务参数 | 作用与结果 |
+|------|------|------|
+| `org.member.join` | `org_id`、`member_aid`、成员类型/类别、角色、完整条款、双签前 binding、成员签名 | 申请加入；返回待审批请求，不直接建立 active 成员 |
+| `org.member.approveJoin` | `org_id`、`join_request_id`、已签 binding、`credential_template`、`registration_authorization`、审批材料 | 审批并登记成员 CAP；验证回执后完成成员关系 |
+| `org.member.rejectJoin` | `org_id`、`join_request_id`、拒绝原因 | 拒绝待审批申请 |
+| `org.member.invite` | `org_id`、`targets[]`、成员角色/属性、条款、逐目标 `membership_bindings` | 创建定向邀请，返回 `invites[]` |
+| `org.member.inviteAccept` | `org_id`、`invite_id`、目标成员、双签 binding、成员签名、CAP 模板和登记授权 | 接受目标邀请并完成成员登记 |
+| `org.member.inviteReject` | `org_id`、`invite_id`、拒绝原因 | 拒绝邀请 |
+| `org.member.renewCredential` | `org_id`、成员、旧 CID、`expected_version`、新 binding/CAP 和登记授权 | 在原关系内换发 CAP；返回新旧 CID、binding、版本和登记回执 |
+| `org.member.list` | `org_id`、可选类型/状态/角色/分页过滤 | 返回授权可见的 `items[]` 和分页信息 |
+| `org.member.get` | `org_id`、`member_aid`、可选 `fields[]` | 返回成员、binding 摘要、凭证状态及签名 `membership_status` |
+| `org.member.leave` / `kick` | `org_id`、成员、原因、`expected_version`；可选 `force` | 启动离职或移出收尾，返回操作 ID 和成员状态 |
+| `org.member.offboard` | `org_id`、`member_aid`、`action=confirm/cancel`、可选 `expected_version` | 确认结束或取消收尾；返回成员状态、吊销数量和可选操作 ID |
+| `org.member.freeze` / `unfreeze` | `org_id`、`member_aid`、版本及可选原因 | 冻结或恢复成员状态 |
+| `org.member.ban` / `unban` | `org_id`、`member_aid`、版本、原因；ban 可带正整数秒 `duration` | 封禁或解除封禁；返回状态及可选 `banned_until` |
+
+首次 `join` / `inviteAccept` 由目标成员私钥签名；代表操作还需专用 admission representation proof。成员 CAP 登记成功不等于入组完成，只有 Org Service 验证回执并提交成员关系后状态才是 `active`。成员状态优先于角色和 CAP：`banned`、`ended` 拒绝授权，`frozen` 拒绝普通写操作。
+
+## 凭证查询、审计与授权
+
+| 方法 | 主要业务参数 | 成功结果 |
+|------|------|------|
+| `org.credential.getStatus` | `org_id`、`credential_cid` | 组织范围内的签名状态证明，含 Credential 原始 proof |
+| `org.credential.revocationList` | `org_id`、可选 `since_event_seq` / `cursor` / `limit` | 签名事件增量、游标和 Credential 原始 proof |
+| `org.audit.query` | 组织、actor/target、事件类型/前缀、时间窗、分页和字段过滤 | `aun-org-audit-snapshot/1` 签名快照 |
+| `org.authz.check` | 组织目标、资源/动作及相应成员授权材料 | 授权判定结果；状态未知或无法验证时拒绝放行 |
+
+凭证查询由 Org Service 封装 Credential Service 的权威状态，不复制凭证状态。`org.audit.query` 按当前成员权限或有效审计 CAP 限定范围；解散组织的历史查询需独立归档 CAP。
+
+## 内部和未实现方法
+
+`org.member.add` 只允许 Org Service 内部最终化成员关系；普通客户端调用会返回 `ROLE_ACCESS_DENIED`。`org.membership.reserve/get/commit/release` 用于跨域成员名额占位和提交，由服务身份调用，不是应用公共接口。
+
+dispatcher 保留四个尚未实现的方法：`org.resource.create`、`org.task.create`、`org.host.add`、`org.workflow.create`。调用时返回 `NOT_IMPLEMENTED`；同一组下未注册的其它方法返回 JSON-RPC `Method not found`。SDK facade/helper 存在不代表对应 RPC 已实现。
+
+## 错误处理
+
+Org 业务错误使用 `error.data.error_code` 和 `retryable` 标志。常见代码包括 `ORG_NOT_FOUND`、`ORG_STATUS_UNKNOWN`、`VERSION_CONFLICT`、`IDEMPOTENCY_KEY_REUSE`、`ROLE_ACCESS_DENIED`、`MEMBERSHIP_STATE_INVALID`、`CREDENTIAL_STATUS_UNKNOWN` 和 `NOT_IMPLEMENTED`。只有明确可重试的状态/服务故障，或同方法、同 request ID、同参数摘要的幂等请求才可重试；权限、签名、状态和摘要冲突不能盲目重试。

package/_packed_docs/sdk/AUN_DOCS_GUIDE.md

@@ -12,9 +12,9 @@ AUN SDK 文档位于 `docs/sdk/`，索引文件 `docs/sdk/INDEX.md` 分三层：
 - `PushFacade`：Python SDK 的当前安装推送登记、注销和 Push Server 批次 ACK。
 - `ServiceProxyClient`：Python SDK 的 Service Proxy provider 侧客户端，负责 Gateway 控制面注册和 proxy-server 数据面隧道注册。
 
-业务 RPC 的底层参数见 `09-*-rpc-manual.md`。P2P device 定向发送、TTL volatile 消息、独立游标和 ACK 见 `09-message-rpc-manual.md`。当前 Agent.md Schema、签名和上传前校验见 `../protocol/Ownership协议定义2.1.md` 与 `04-连接与认证.md`；`../agent.md/SCHEMA.md` 为 legacy 2.0。当前 Ownership 2.1 应用接入见 `Ownership2.1-SDK应用集成指南.md`，SDK 移植见 `Ownership2.1-SDK开发与移植指南.md`，wire schema 见 `../protocol/Ownership协议定义2.1.md`；旧集成/实现指南与管理专题为 legacy。新服务端为旧 SDK 保留隔离的 owner RPC/Auth JSONL，不参与 2.1 双文件关系判断。Group/Org owner 不走通用流程，名片实体主签、owner token 上传、可选 owner 附签、实体证书代际和原 CAS pending见协议 §1.3/§2.5。A/T/H、SDK 内部自动最新页同步、Forward 调度和每个 AUNClient 一个 Pull Gate（同 namespace 单飞、不同 namespace 最多 4 个并行、相同 key 折叠、可运行项前台 FIFO 优先）见 `03-核心概念.md`；`message.history` / `group.history` 与 Piggy ACK 见 Message/Group RPC Manual。
+业务 RPC 的底层参数见 `09-*-rpc-manual.md`。P2P 共享 seq/peer 游标、pending peers/统计快照、need_render、device 定向发送、TTL volatile 和 ACK 见 `09-message-rpc-manual.md`。当前 Agent.md Schema、签名和上传前校验见 `../protocol/Ownership协议定义2.1.md` 与 `04-连接与认证.md`；`../agent.md/SCHEMA.md` 为 legacy 2.0。当前 Ownership 2.1 应用接入见 `Ownership2.1-SDK应用集成指南.md`，SDK 移植见 `Ownership2.1-SDK开发与移植指南.md`，wire schema 见 `../protocol/Ownership协议定义2.1.md`；旧集成/实现指南与管理专题为 legacy。新服务端为旧 SDK 保留隔离的 owner RPC/Auth JSONL，不参与 2.1 双文件关系判断。Group/Org owner 不走通用流程，名片实体主签、owner token 上传、可选 owner 附签、实体证书代际和原 CAS pending见协议 §1.3/§2.5。peer A/T/H、human Tail 策略、稀疏覆盖、后台续拉和每个 AUNClient 一个网络 Pull Gate（同 namespace 单飞、不同 namespace 最多 4 个并行、相同 key 折叠、可运行项前台 FIFO 优先）见 `03-核心概念.md`；`message.history` / `group.history` 与 Piggy ACK 见 Message/Group RPC Manual；SDK 50k 内存去重、应用持久幂等及三类 batch 的当前契约见 Message RPC Manual。
 
-Storage 的 SDK VFS、实际字节 MIME 识别、session/PUT/complete Content-Type 一致性、OSS 403、direct backend 上传下载和 ticket / AID Bearer 边界见 `09-storage-rpc-manual.md` 与 `AUN Storage架构设计.md`。
+Storage 的 SDK VFS、实际字节 MIME 识别、session/PUT/complete Content-Type 一致性、OSS 403、direct backend 上传下载和 ticket / AID Bearer 边界见 `09-storage-rpc-manual.md` 与 `AUN Storage架构设计.md`；Storage / Group FS 默认读缓存、60 秒总新鲜度、`read_cache`、SHA 条件读取、无正文 not_modified 不计次、持久层/容量与 `noCache` 规则见 [缓存策略](09-storage-rpc-manual.md#sdk-默认读缓存) 和 [API 选项](06-API手册.md#默认读缓存与单次刷新)。
 跨设备业务已读的 `read/read_state/read_changed`、单条/显式空值、回执与共享汇总、scope/owner 绑定、设备映射、晚到位置回填、TS/JS 精确整数和 Group canonical/权限版本及混合域提交见 Message/Group RPC Manual；四端门面与本地 `read_state_sync` 完成事件见 `06-API手册.md`、`04-连接与认证.md`。
 Group 的成员 block/status、暂停群权限和两阶段群主转让，以及 Group FS 的 `group.fs.*` RPC、角色 ACL、`parents` 语义和 memberdata 映射见 `09-group-rpc-manual.md`。Collab 的 `gc`、`reflog`、`revert`、`clone` 及版本化文档/标签语义见 `09-collab-rpc-manual.md`。
 
@@ -34,7 +34,7 @@ Group 的成员 block/status、暂停群权限和两阶段群主转让，以及
 - E2EE：默认加密、ProtectedHeaders、P2P / Group V2
 - RPC 与事件：`client.call()`、`client.on()`、`client.notify()`、RPC 手册
 - 离线推送：Python `connect()` 的 `push_notify_aid/push_token`、`client.push.register/unregister`、Push Server ACK
-- 消息同步：A/T/H、Tail、Forward、History、页内唯一有序发布、应用层跨页幂等排序、每个 AUNClient 一个 Pull Gate（P2P Message/Group Message/Group Event Pull 共享，同 namespace 单飞、不同 namespace 最多 4 个并行、相同 key 折叠、可运行项前台 FIFO 优先）、`source` 来源、`sync.started/progress/stopped` 生命周期、缺 sender IK 有界同步 bootstrap、永久页内 Gap、坏密文推进
+- 消息同步：共享 seq 下的 peer A/T/H、稀疏覆盖/前驱、human Tail→Forward、50k 内存去重/应用持久幂等、N=4 网络 Gate、后台工作片续调度、`message.peers_snapshot` 的轻量对端水位/可选整体积压估计、目录/Pull逐页next_pending_seq、可靠commit后持续更新与每N次FIFO（无额外SQL、原列表顺序不改）、need_render/页内计数、`source` 和同步生命周期；Group 保持原终态规则
 - P2P TTL 消息：`message.send.ttl` 秒级钳制、按 device 内存收件箱、volatile 双游标、自动 ACK/去重、服务 epoch 与重启语义
 - 跨设备已读：P2P/Group 按话题上报、共享汇总、设备映射、单调事件、本地 `read_state_sync`、精确整数、混合域部分提交及幂等重试
 - Storage：SDK VFS、实际字节 MIME 识别、session/PUT/complete Content-Type 一致性、OSS 403、下载 ticket / AID Bearer 边界、`storage.*` low-level RPC
@@ -54,29 +54,33 @@ Group 的成员 block/status、暂停群权限和两阶段群主转让，以及
 
 | 编号 | 文档 | 定位 |
 |------|------|------|
+| - | [0.5.21 SDK 应用集成指南](0.5.21-SDK应用集成指南.md) | 应用开发者的 TypeScript 接入、消息持久幂等、resolve/owner、凭证组织、诊断与升级 |
+| - | [0.5.21 SDK 开发与移植指南](0.5.21-SDK开发与移植指南.md) | SDK 开发者的 peer/batch 提交、共识缓存、原 CAS/旧任务、checkpoint、语言差异及验收 |
+| - | [0.5.22 SDK 应用集成指南](0.5.22-SDK应用集成指南.md) | TypeScript 接线、审批恢复、resolve、缓存及凭证组织 |
+| - | [0.5.22 SDK 开发与移植指南](0.5.22-SDK开发与移植指南.md) | 同步、Stage/CAS、撤销续期、缓存、服务依赖及 Rust 清单 |
 | - | [CHANGELOG-0.5.6](CHANGELOG-0.5.6.md) | **0.5.6 版本更新日志**：首次签名者回源、下载提交前验签、消息窗口、显式 change-seed 与语言能力边界 |
 | 01 | [快速开始](01-快速开始.md) | 安装、三主体模型、最小示例 |
-| 02 | [WebSocket协议](02-WebSocket协议.md) | 握手流程、Capabilities 能力声明、各层大小限制、消息格式、裸 WebSocket |
-| 03 | [核心概念](03-核心概念.md) | AID、A/T/H、Pull Gate、状态机、E2EE |
-| 04 | [连接与认证](04-连接与认证.md) | AIDStore、默认 agent.md 自动上传、连接生命周期并发/取消、当前 access token getter、网关发现、事件、已读状态本地补偿完成事件、agent.md 校验和自动观察 |
+| 02 | [WebSocket协议](02-WebSocket协议.md) | 握手流程、严格布尔 peer 能力、各层大小限制、消息格式、裸 WebSocket |
+| 03 | [核心概念](03-核心概念.md) | AID、peer A/T/H、稀疏覆盖、N=4 Gate、50k 内存去重、状态机、E2EE |
+| 04 | [连接与认证](04-连接与认证.md) | AIDStore、默认 agent.md 自动上传、连接生命周期并发/取消、当前 access token getter、网关发现、事件、已读状态本地补偿完成事件、agent.md 校验和自动观察、resolve frontmatter 与按需 ownership |
 | - | [Ownership 协议定义 2.1](../protocol/Ownership协议定义2.1.md) | 当前双文件关系、版本、签名与授权边界、旧 SDK owner RPC/JSONL 隔离 |
-| - | [Ownership SDK 编排指南 2.1](Ownership-SDK编排指南2.1.md) | 七 Facade、审批、持久任务和恢复 |
-| - | [Ownership 2.1 SDK 应用集成指南](Ownership2.1-SDK应用集成指南.md) | 普通 agent 可选 owner 注册、应用审批、新鲜共识、文件多签与实体上传 |
-| - | [Ownership 2.1 SDK 开发与移植指南](Ownership2.1-SDK开发与移植指南.md) | 统一签验核心、原件复核、owner.md 同会话上传与发布 CAS、NS 原条件与恢复 |
+| - | [Ownership SDK 编排指南 2.1](Ownership-SDK编排指南2.1.md) | 七 Facade、sub-first Stage／owner-first 直接提交、无锁预检、三类 CAS 冲突及持久恢复 |
+| - | [Ownership 2.1 SDK 应用集成指南](Ownership2.1-SDK应用集成指南.md) | 应用侧 TS 接线与审批；双向绑定、释放、三方转移和重连恢复图，任务与当前共识分开判断 |
+| - | [Ownership 2.1 SDK 开发与移植指南](Ownership2.1-SDK开发与移植指南.md) | SDK 内部 TS 接口；严格签验、NS fresh、Storage 发布、收件持久化和原 CAS 恢复图 |
 | - | [Ownership管理专题（legacy）](Ownership管理专题.md) | 四端 P2P owner API、应用层 accept/reject、完整消息 payload、identity escrow、owner 代签 agent.md、metadata 状态和验签边界 |
 | - | [Ownership SDK集成指南（legacy）](Ownership-SDK集成指南.md) | TypeScript 快速接入、应用审批、状态查询及 SDK 编排流程图 |
 | - | [Ownership SDK实现指南（legacy）](Ownership-SDK实现指南.md) | SDK 移植入口、消息拦截、proof/escrow、metadata 和恢复验收 |
 | - | [Ownership协议定义（legacy）](../protocol/Ownership协议定义.md) | P2P/proof/agent.md schema、escrow、owner 授权头与现有 RPC |
-| - | [凭证与组织服务 SDK 应用集成指南](凭证与组织服务SDK应用集成指南.md) | 0.5.19 应用接入、CAP 完整验证、登记回执、成员闭环、代表请求和转让恢复 |
-| - | [凭证与组织服务 SDK 开发与移植指南](凭证与组织服务SDK开发与移植指南.md) | 0.5.19 四端协议实现、canonical JSON、强状态 proof、请求绑定、facade/RPC 和共同向量 |
+| - | [凭证与组织服务 SDK 应用集成指南](凭证与组织服务SDK应用集成指南.md) | TS 示例与凭证登记验证、成员申请／邀请、续期、撤销同步和组织转让图 |
+| - | [凭证与组织服务 SDK 开发与移植指南](凭证与组织服务SDK开发与移植指南.md) | TS 内部示例与 Verify、双层请求摘要、回执、撤销快照和实体 checkpoint 图 |
 | - | [凭证服务 RPC 手册](09-凭证服务RPC手册.md) | Credential Service 实际 RPC、参数和签名状态响应 |
 | - | [组织服务 RPC 手册](09-组织服务RPC手册.md) | Org Service 生命周期/成员 RPC、内部接口和未实现方法 |
-| 05 | [E2EE加密通信](05-E2EE加密通信.md) | E2EE V2、ProtectedHeaders、agent.md 版本提示、recipient wrap |
+| 05 | [E2EE加密通信](05-E2EE加密通信.md) | E2EE V2、ProtectedHeaders、need_render、agent.md 版本提示、旧 SPK 保留 |
 | - | [ProtectedHeaders用法专题](ProtectedHeaders用法专题.md) | `protected_headers` 四端 API、实例级/单次调用、E2EE V2 HMAC 完整性和接收信任边界 |
-| 06 | [API手册](06-API手册.md) | AIDStore / Agent.md 校验签名 / AID / AUNClient 生命周期并发 / 四 SDK access token getter / 群组高层身份编排 / History 与已读门面 / 已读变更及本地补偿完成 / 消息来源与 Pull 同步生命周期 / 事件 / RPC |
+| 06 | [API手册](06-API手册.md) | AIDStore / resolve opts 与输入输出 / frontmatter 类型 / ownership 和 owner.md 缓存 / Agent.md 校验签名 / AID / AUNClient 生命周期并发 / 四 SDK access token getter / 群组高层身份编排 / History 与已读门面 / 已读变更及本地补偿完成 / 消息来源与 Pull 同步生命周期 / 事件 / RPC |
 | 07 | [错误处理](07-错误处理.md) | Result、Python `ErrorInfo.cause`、异常、错误码、重试 |
 | 08 | [最佳实践](08-最佳实践.md) | 幂等、消息同步/History、AUNClient 级 Pull Gate（同 namespace 单飞、客户端最多 4 个并行）、测试数据 |
-| - | [Storage RPC 手册](09-storage-rpc-manual.md) | Storage RPC、实际字节 MIME、三阶段 Content-Type、OSS 403、HTTP 下载与凭据边界 |
+| - | [Storage RPC 手册](09-storage-rpc-manual.md) | Storage RPC、实际字节 MIME、三阶段 Content-Type、OSS 403、HTTP 下载与凭据边界、默认读缓存持久层、条件读取与 noCache |
 | - | [AUN Storage架构设计](<../aun-fs/AUN Storage架构设计.md>) | Storage SDK VFS、控制面/数据面分离、类 Linux 权限、mount/symlink、服务端分层 |
 | 09 | `09-*-rpc-manual.md` | 各服务 RPC 参数和响应 |
 | 09 | [Service Proxy RPC手册](09-proxy-rpc-manual.md) | `proxy.*` 控制面和 proxy-server 数据面注册 |
@@ -86,32 +90,36 @@ Group 的成员 block/status、暂停群权限和两阶段群主转让，以及
 
 | 场景 | 推荐路径 |
 |------|----------|
-| 了解最新版本特性和改进 | [CHANGELOG-0.5.6](CHANGELOG-0.5.6.md) |
+| 接入或升级 0.5.21，查看 TypeScript 应用示例 | [0.5.21 SDK 应用集成指南](0.5.21-SDK应用集成指南.md) |
+| 实现、移植或审查 0.5.21 SDK | [0.5.21 SDK 开发与移植指南](0.5.21-SDK开发与移植指南.md) |
+| 接入或升级 0.5.22，查看 TypeScript 示例、关系审批、默认读缓存及完整成员包 | [0.5.22 SDK 应用集成指南](0.5.22-SDK应用集成指南.md) |
+| 实现、移植或审查 0.5.22 SDK，查看 Stage/CAS、配套服务修复、读缓存及 Rust 验收清单 | [0.5.22 SDK 开发与移植指南](0.5.22-SDK开发与移植指南.md) |
 | 首次使用 SDK | [01-快速开始](01-快速开始.md) |
 | 理解新构造入口 | [01-快速开始](01-快速开始.md)、[06-API手册](06-API手册.md) |
 | 注册或加载 AID | [04-连接与认证](04-连接与认证.md) |
+| 查询 resolve opts、frontmatter 字段及类型、按需 ownership 共识和 owner.md 缓存 | [resolve 输入与输出](06-API手册.md#resolve-输入与输出) |
 | 查旧 SDK owner 注册、绑定、转移、查询及解绑的隔离兼容，或 legacy proof/escrow/代签 | [当前协议兼容边界](../protocol/Ownership协议定义2.1.md) 开篇/§3.2、[详细设计](Ownership2.1详细设计.md) §1 兼容矩阵；历史 wire 见 [Ownership管理专题（legacy）](Ownership管理专题.md)、[legacy 集成指南](Ownership-SDK集成指南.md) |
-| 首次在应用中集成 Ownership 2.1，使用 sign/verify、文件多签与实体上传 | [当前应用集成指南](Ownership2.1-SDK应用集成指南.md)、[API 手册](06-API手册.md#通用-sign--verify)、[编排指南 2.1](Ownership-SDK编排指南2.1.md) |
-| 实现、移植或审查 Ownership 2.1 SDK、统一签验核心与多签 HTTP 兼容 | [当前开发与移植指南](Ownership2.1-SDK开发与移植指南.md) §7 的 owner.md 同会话上传与 expected_version 发布 CAS，object_id/version 非读取条件；[详细设计](Ownership2.1详细设计.md) §1 兼容非回归原则与矩阵；关系有效性只影响依赖 owner 的功能 |
-| Ownership 2.1 当前审查、旧 SDK 兼容、四端修复与验证边界 | [当前审查第十五节](../audit/Ownership2.1代码审查报告.md#十五2026-10-15-追加审查兼容裁决与修复验收)；历史 [第十二节](../audit/Ownership2.1代码审查报告.md#十二2026-10-11-本轮复审与修复)、[第十三节](../audit/Ownership2.1代码审查报告.md#十三2026-10-13-审查更正与最小修复验收)、[第 13.8 节复查更正与修复边界](Ownership2.1-TDD分阶段实施计划.md#138-2026-10-13-复查更正与修复边界) |
+| Ownership 2.1 应用：绑定／释放／转移、审批及恢复的 TS 示例与图 | [应用集成指南](Ownership2.1-SDK应用集成指南.md) |
+| Ownership 2.1 移植：fresh 共识、发布、收件持久化和 CAS 恢复 | [开发与移植指南](Ownership2.1-SDK开发与移植指南.md) |
+| Ownership 2.1 当前格式、reset、历史任务及验证边界 | [第二十二节](../audit/Ownership2.1代码审查报告.md#二十二2026-10-18-恢复发布格式与历史兼容更正)：撤销独立资源和新增字段；[编排第 8 节](Ownership-SDK编排指南2.1.md#8-崩溃与响应丢失后的恢复)：0.5.20/0.5.19 及更早兼容、原任务恢复、绑定容错与 reset |
 | 当前双文件关系、release/清理/重绑版本、Header 投影及 Group/Org 名片 wire | [协议 2.1](../protocol/Ownership协议定义2.1.md) §3/§4.2/§6、§1.3/§2.5；旧 SDK RPC 隔离兼容见开篇/§3.2，旧 escrow/授权头 wire 查 legacy 协议 |
-| 应用接入 Credential/Org 服务 | [凭证与组织服务 SDK 应用集成指南](凭证与组织服务SDK应用集成指南.md) |
-| 实现或移植 Credential/Org SDK | [凭证与组织服务 SDK 开发与移植指南](凭证与组织服务SDK开发与移植指南.md) |
+| Credential/Org 应用：登记验证、入组、续期、撤销和转让图 | [应用集成指南](凭证与组织服务SDK应用集成指南.md) |
+| Credential/Org 移植：签验、双层摘要、快照和实体恢复 | [开发与移植指南](凭证与组织服务SDK开发与移植指南.md) |
 | 查 Credential Service RPC | [凭证服务 RPC 手册](09-凭证服务RPC手册.md) |
 | 查 Org Service RPC | [组织服务 RPC 手册](09-组织服务RPC手册.md) |
 | 自行发起 HTTP 数据面请求并获取当前 access token | [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)、[Storage RPC 手册：数据面 HTTP 下载流程](09-storage-rpc-manual.md#数据面-http-下载流程) |
 | 发布、下载、检查或排查 agent.md（含 Schema/签名/大小限制）及远端 ETag | [当前协议 2.1](../protocol/Ownership协议定义2.1.md)、[04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)、[../agent.md/远程agent.md缓存与etag透传方案.md](../agent.md/远程agent.md缓存与etag透传方案.md) |
 | 状态机和重连 | [03-核心概念](03-核心概念.md)、[04-连接与认证](04-连接与认证.md) |
-| 查 Capabilities 能力声明、实时推送优化 | [02-WebSocket协议](02-WebSocket协议.md)、[CHANGELOG-0.5.6](CHANGELOG-0.5.6.md) |
+| 查 peer 能力声明、连接上下文、上线恢复与实时推送优化 | [02-WebSocket协议](02-WebSocket协议.md)、[09-message-rpc-manual.md](09-message-rpc-manual.md#messagepeers) |
 | 登记、更新或注销 `push_notify_aid` | [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)、`docs/protocol/15-离线推送通知协议.md` |
 | 查方法签名、群组高层 facade 和 `aid_store` / `aidStore` | [06-API手册](06-API手册.md) |
 | 查消息或群组 RPC、群提及过滤 `mention_mode` | 对应 `09-*-rpc-manual.md`；`mention_mode` 详见 [09-group-rpc-manual.md](09-group-rpc-manual.md) |
 | 查 `protected_headers` / ProtectedHeaders 用法及四端 E2EE 细节 | [ProtectedHeaders用法专题](ProtectedHeaders用法专题.md) |
-| 查 P2P device 定向发送或 TTL volatile 消息 | [06-API手册](06-API手册.md)、[09-message-rpc-manual.md](09-message-rpc-manual.md) |
+| 查 P2P pending peers、按对端/全部对端 Pull、peer ACK、历史基线、TTL volatile 或 need_render | [06-API手册](06-API手册.md)、[09-message-rpc-manual.md](09-message-rpc-manual.md) |
 | 查跨设备业务已读、单条/显式空值、scope/owner、seq 映射、TS/JS 精确整数或 Group canonical/权限版本及混合域提交 | [09-message-rpc-manual.md](09-message-rpc-manual.md)、[09-group-rpc-manual.md](09-group-rpc-manual.md) |
 | 查已读状态补偿完成事件 `read_state_sync`、states/errors 和 `background_sync` 边界 | [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md) |
-| 查 A/T/H、SDK 自动最新页同步与 AUNClient 级 Pull Gate | [03-核心概念.md](03-核心概念.md)、[08-最佳实践.md](08-最佳实践.md)、[09-message-rpc-manual.md](09-message-rpc-manual.md)、[09-group-rpc-manual.md](09-group-rpc-manual.md) |
-| 查消息事件 `source`、`sync.started/progress/stopped` 和 `delivery.changed` | [06-API手册](06-API手册.md) |
+| 查 peer A/T/H、稀疏覆盖/前驱、human Tail、N=4 Gate、page_size×N 共享队列、后台续拉、SDK 50k 内存去重/应用持久幂等的自定义 store/多 client 边界 | [03-核心概念.md](03-核心概念.md)、[08-最佳实践.md](08-最佳实践.md)、[09-message-rpc-manual.md](09-message-rpc-manual.md) |
+| 查 message.peers_snapshot 的对端水位/可选整体积压估计、目录A近似/Pull精确next_pending_seq提示（缺hint安全A、提交ACK后更新、只调度内部副本）、三类batch/完整single fallback、消息 source、同步生命周期和 delivery.changed | [06-API手册](06-API手册.md)、[09-message-rpc-manual.md](09-message-rpc-manual.md#messagepeers_snapshot) |
 | 查 History、Forward、Pull Gate、Group 成员可见性 floor 与 Piggy ACK | [09-message-rpc-manual.md](09-message-rpc-manual.md)、[09-group-rpc-manual.md](09-group-rpc-manual.md) |
 | 查群组标识 `group_aid` / `group_id` 兼容规范 | [09-group-rpc-manual.md](09-group-rpc-manual.md) |
 | 查成员 block/status、暂停群发言权限或两阶段群主转让 | [09-group-rpc-manual.md](09-group-rpc-manual.md)、[06-API手册](06-API手册.md) |
@@ -119,7 +127,7 @@ Group 的成员 block/status、暂停群权限和两阶段群主转让，以及
 | 查群文件系统 RPC / SDK / CLI 入口、群自有区角色 ACL 授权/撤销/查询、`parents` 和 JS string 差异 | [09-group-rpc-manual.md](09-group-rpc-manual.md)、[06-API手册](06-API手册.md) |
 | 查 Storage 架构、SDK VFS、权限模型和 mount/symlink | [AUN Storage架构设计.md](<../aun-fs/AUN Storage架构设计.md>) |
 | 查 Storage MIME 识别、session/PUT/complete Content-Type、OSS 403 或底层 RPC 调用责任 | [09-storage-rpc-manual.md](09-storage-rpc-manual.md)、[06-API手册](06-API手册.md) |
-| 查 Storage 数据面 HTTP 下载流程和 ticket / AID Bearer 边界 | [09-storage-rpc-manual.md](09-storage-rpc-manual.md) |
+| 查 Storage / Group FS 默认读缓存、60 秒总新鲜度、SHA 条件读取、无正文条件验证不计次、刷新和缓存专项断点续跑 | [缓存策略](09-storage-rpc-manual.md#sdk-默认读缓存)、[0.5.22 移植指南](0.5.22-SDK开发与移植指南.md#61-storage--group-fs-默认读缓存)、[测试入口](../aun测试运行指南.md#storage--group-fs-读缓存专项) |
 | 查协作（版本化文档/乐观锁/标签/GC/reflog/revert）RPC | [09-collab-rpc-manual.md](09-collab-rpc-manual.md) |
 | 查 notify 在线轻量通知 / 跨域 federation | [Notify通知方案.md](Notify通知方案.md) |
 | 查 Service Proxy 服务注册和路由 | [06-API手册](06-API手册.md)、[09-proxy-rpc-manual.md](09-proxy-rpc-manual.md) |