@agentunion/fastaun-browser 0.5.19 → 0.5.21

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

@@ -93,7 +93,7 @@
 
 > 统一权限求值顺序（硬顺序）：公开位 → token → ACL（最近祖先前缀）→ 角色 → owner → 拒绝。
 >
-> AID storage 的 `storage.set_acl/remove_acl` 面向具体 AID，当前主要用于写/删除授权；直接读授权不通过 ACL 下发，读访问应使用 `storage.create_share_link` / `storage.get_by_share`，撤销分享使用 `storage.revoke_share_link`。`role:*` 伪主体只允许可信 group 内部门面管理，客户端不得直接对 `group_aid` 空间设置角色 ACL；群自有区 admin 写授权使用 `group.fs.set_acl/remove_acl`。
+> `storage.set_acl` 授予路径前缀权限：`w` 写、`x` 删、`r` 读。`r` 用于 authoritative 读取和受信挂载读取；普通个人私有对象下载请使用 `storage.create_share_link`，以 `allowed_aids` 指定接收 AID。群角色 ACL 使用 `group.fs.set_acl/remove_acl`。
 
 | 方法 | 说明 |
 |------|------|
@@ -126,13 +126,11 @@ Python / Go / TypeScript / JavaScript SDK 均提供 storage low-level 与 VFS
 
 直接调用底层 RPC 的高级客户端必须自行完成相同编排：先确定内容类型，再把同一个值传给 session 和 complete，并在 PUT 请求中发送一致的 `Content-Type`。绕过 VFS 后未遵守该约束属于调用方式错误。
 
-## 权威读取与条件发布
+## 权威读取与完整发布
 
-`storage.head_object/get_object` 和 `storage.fs.stat` 的 `consistency: authoritative` 绕过正向、负向缓存。权威结果包含 `consistency`、布尔 `exists`、不透明 `revision`、请求 `owner_aid/bucket/path` 和 Unix 秒 `observed_at`；存在时附 `sha256/object_id/version`，get 另有严格 Base64 的完整 `content`。权威 stat 返回此对象结果，不使用普通 NodeView 推断不存在。恢复未完成、权限错误、网络或数据库故障均失败，不返回 `exists=false`。
+`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 不授权普通下载票据。
 
-路径 `revision` 在成功写入、删除后变化，删除后保留；从未创建为字符串 `0`，同内容重建也不复用旧值。`put_object/create_upload_session/complete_upload/delete_object/fs.remove` 的 `expected_revision` 使用先前权威读到的原值；不能用摘要、对象 version 或刷新后的修订替代。冲突沿用 `-32009`，停止旧写入或删除。普通调用的既有条件语义保持不变。
 
-条件上传 session 固化目标与原修订，返回 `session_id/expected_revision`；complete 在最终原子发布时再作 CAS，失败保留旧完整对象。Ownership owner.md 的首次创建也匹配 `0` 或删除后的当前修订，更新不得先删后建，清理不得无条件删除。
 
 `default/sub_aids/{sub_aid}/owner.md` 为公开可读的 Ownership 规范路径，仅命名空间 owner 可写删；ACL、token、父目录、移动、重命名、软链、挂载或自动清理均不能给第三方绕过能力。该路径约束先于通用权限放行，关系授权以 [Ownership 2.1](../protocol/Ownership协议定义2.1.md) 的 NS 新鲜事实为准。
 
@@ -152,7 +150,6 @@ Python / Go / TypeScript / JavaScript SDK 均提供 storage low-level 与 VFS
 | `is_private` | boolean | 否 | 是否私有，默认 `true` |
 | `overwrite` | boolean | 否 | 是否覆盖已有对象，默认 `true` |
 | `expected_version` | integer | 否 | 乐观并发控制版本号 |
-| `expected_revision` | string | 否 | 原权威路径修订；Ownership 发布须携带 |
 | `expire_in_seconds` | integer | 否 | 过期时间（秒），0 表示不过期 |
 | `metadata` | object | 否 | 自定义元数据 |
 
@@ -191,7 +188,7 @@ result = await client.call("storage.put_object", {
 
 读取小对象，返回 base64 编码内容。
 
-可传 `consistency: authoritative`，结果及故障分类见 [权威读取与条件发布](#权威读取与条件发布)；权威读取只接受完整对象。
+可传 `consistency: authoritative`，结果及故障分类见 [权威读取与完整发布](#权威读取与完整发布)；权威读取只接受完整对象。
 
 ### 参数
 
@@ -201,7 +198,6 @@ result = await client.call("storage.put_object", {
 | `bucket` | string | 否 | 存储桶，默认 `"default"` |
 | `owner_aid` | string | 否 | 所有者 AID，默认当前用户 |
 | `consistency` | string | 否 | 传 `authoritative` 时绕过缓存并返回完整权威对象 |
-| `expected_revision` | string | 否 | 权威路径修订；条件读取时必须与先前权威读取一致 |
 
 ### 响应
 
@@ -234,7 +230,7 @@ content = base64.b64decode(result["content"])
 
 查询对象元数据，不返回内容。
 
-可传 `consistency: authoritative`，返回 `exists/revision/observed_at` 等权威字段，明确不存在仍保留路径修订；完整契约见 [权威读取与条件发布](#权威读取与条件发布)。
+可传 `consistency: authoritative`，返回当前存在性与完整对象元数据；完整契约见 [权威读取与完整发布](#权威读取与完整发布)。
 
 ### 参数
 
@@ -244,7 +240,6 @@ content = base64.b64decode(result["content"])
 | `bucket` | string | 否 | 存储桶，默认 `"default"` |
 | `owner_aid` | string | 否 | 所有者 AID，默认当前用户 |
 | `consistency` | string | 否 | 传 `authoritative` 时绕过缓存并返回权威对象元数据 |
-| `expected_revision` | string | 否 | 权威条件读取使用的原路径修订 |
 
 ### 响应
 
@@ -269,7 +264,6 @@ content = base64.b64decode(result["content"])
 
 删除对象。
 
-可传原 `expected_revision` 作条件删除，结果附新路径 `revision`；修订冲突不得改用刚读到的新版继续删除。
 
 ### 参数
 
@@ -278,7 +272,6 @@ content = base64.b64decode(result["content"])
 | `object_key` | string | 是 | 对象路径 |
 | `bucket` | string | 否 | 存储桶，默认 `"default"` |
 | `owner_aid` | string | 否 | 所有者 AID，默认当前用户 |
-| `expected_revision` | string | 否 | 条件删除使用的原权威路径修订 |
 
 ### 响应
 
@@ -583,14 +576,14 @@ for obj in result["items"]:
 | `bucket` | string | 否 | 存储桶，默认 `"default"` |
 | `owner_aid` | string | 否 | 所有者 AID，默认当前用户 |
 | `expected_version` | integer | 否 | 乐观并发控制版本号 |
-| `expected_revision` | string | 否 | 固定条件上传 session 的原权威路径修订 |
 | `expire_in_seconds` | integer | 否 | URL 有效期（秒），默认 3600 |
 
 ### 响应
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `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 |
 | `bucket` | string | 存储桶 |
@@ -604,7 +597,9 @@ for obj in result["items"]:
 | `size_bytes` | integer | 声明的文件大小 |
 | `overwrite` | boolean | 是否覆盖已有对象 |
 
-客户端获得 `upload_url` 后，通过 HTTP PUT 上传文件数据。普通 session 不返回 `blob_key`、`session_id` 或 `headers`；传入 `expected_revision` 的条件 session 另返回 `session_id` 和固定 `expected_revision`，complete 必须沿用该 session 和原条件。
+客户端获得 `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`。
 
@@ -620,7 +615,8 @@ for obj in result["items"]:
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `object_key` | string | 是 | 对象路径 |
+| `object_key` | string | 条件 | 对象路径；提供 `session_id` 时可省略，若提供则必须与原会话目标一致 |
+| `session_id` | string | 否 | 规范 agent.md/owner.md 新上传必须沿用 create_upload_session 返回的同一会话 |
 | `sha256` | string | 否 | 文件 SHA-256 哈希；提供则校验完整性，`skip_blob=true` 时必填 |
 | `bucket` | string | 否 | 存储桶，默认 `"default"` |
 | `owner_aid` | string | 否 | 所有者 AID，默认当前用户 |
@@ -628,9 +624,7 @@ for obj in result["items"]:
 | `is_private` | boolean | 否 | 是否私有，默认 `true` |
 | `size_bytes` | integer | 否 | 预期文件大小（用于校验） |
 | `skip_blob` | boolean | 否 | 秒传模式，默认 `false`；为 `true` 时跳过 blob 上传，必须提供 `sha256`，且当前 owner 已拥有相同内容 |
-| `expected_version` | integer | 否 | 乐观并发控制版本号 |
-| `expected_revision` | string | 否 | 原权威路径修订；使用条件 session 时须与 session 一致 |
-| `session_id` | string | 否 | create_upload_session 返回的条件上传 session |
+| `expected_version` | integer | 否 | 普通模式的乐观并发控制版本号；会话模式沿用 `create_upload_session` 保存的原值（包括未设置），本次传入值不生效 |
 | `expire_in_seconds` | integer | 否 | 过期时间（秒） |
 | `metadata` | object | 否 | 自定义元数据 |
 
@@ -654,7 +648,7 @@ for obj in result["items"]:
 
 ## storage.create_download_ticket
 
-获取下载 URL。
+获取对象下载 URL。私有对象要分享给指定 AID 时，使用 `storage.create_share_link` 并设置 `allowed_aids`。
 
 ### 参数
 
@@ -1014,7 +1008,7 @@ share_url = result["url"]  # https://alice.agentid.pub/s/Ab3xK9mZ2q
 
 查节点元数据（POSIX `stat`）。`follow_final=true`，解析末级软链 target。
 
-可传 `consistency: authoritative`；此模式使用 [权威对象结果](#权威读取与条件发布)，不是普通 fs 节点视图。
+可传 `consistency: authoritative`；此模式使用 [权威对象结果](#权威读取与完整发布)，不是普通 fs 节点视图。
 
 ### 参数
 
@@ -1099,7 +1093,6 @@ fs 目录节点视图。
 
 删除文件/目录/软链（POSIX `rm`，目录用 `recursive`）。**拒绝删除挂载点**（须先 unmount）。
 
-可传原 `expected_revision` 作条件删除，Ownership 旧文件清理须携带该值；冲突时停止，不刷新修订继续删除。
 
 ### 参数
 
@@ -1109,7 +1102,6 @@ fs 目录节点视图。
 | `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
 | `bucket` | string | 否 | `"default"` | 存储桶 |
 | `recursive` | boolean | 否 | `false` | 递归删除目录 |
-| `expected_revision` | string | 否 | — | 条件删除使用的原权威路径修订 |
 
 ### 响应
 
@@ -1366,7 +1358,7 @@ fs 目录节点视图。
 
 ## storage.set_acl
 
-授予路径前缀 ACL grant。普通 AID storage 的 `grantee_aid` 必须是具体 AID，主要用于授予写/删除权限；子路径默认继承（最近祖先覆盖）。读取不通过 AID ACL 直接授权，应用应改用 `storage.create_share_link` 并在需要时用 `storage.revoke_share_link` 撤销。
+授予路径前缀权限，作用于该路径及子路径（最近祖先 ACL 生效）。`w` 写、`x` 删、`r` 读；`r` 可用于 authoritative 读取和受信挂载读取，不能授权普通个人私有对象直接下载。分享私有对象给指定 AID，请使用 `storage.create_share_link` 并设置 `allowed_aids`。
 
 `role:*` 伪主体只允许可信 group 内部门面写入。客户端不能直接对 `group_aid` 空间调用 `storage.set_acl` 设置 `role:admin`；群自有区角色写授权统一使用 `group.fs.set_acl`。
 
@@ -1376,7 +1368,7 @@ fs 目录节点视图。
 |------|------|------|------|------|
 | `path` | string | 是 | — | 授权路径前缀 |
 | `grantee_aid` | string | 是 | — | 被授权 AID；`role:*` 仅限 group 内部调用 |
-| `perms` | string | 是 | — | 权限位：`r`/`w`/`rw`/`rwx`（`rwx` 含删除） |
+| `perms` | string | 是 | — | 权限位：`r` 读取、`w` 写入、`x` 删除，可组合 |
 | `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
 | `bucket` | string | 否 | `"default"` | 存储桶 |
 | `expires_at` | integer | 否 | — | 授权过期时间 |
@@ -1390,7 +1382,7 @@ ACL 视图。
 
 ## storage.remove_acl
 
-移除路径 ACL 授权。对 AID storage，这是撤销写/删除授权的入口；读分享的撤销入口是 `storage.revoke_share_link`。群自有区角色写授权撤销使用 `group.fs.remove_acl`，不要由客户端直接调用 `storage.remove_acl` 操作 `role:*`。
+移除指定路径和 AID 的 ACL。撤销分享链接使用 `storage.revoke_share_link`；群角色 ACL 使用 `group.fs.remove_acl`。
 
 ### 参数
 

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,71 @@
+# 凭证服务 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`。
+
+## 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`。客户端应验证服务签名与证明时间窗，并按序号续查。
+
+## 错误
+
+业务错误码位于 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,88 @@
+# 组织服务 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)。
+
+## 成员关系
+
+| 方法 | 主要业务参数 | 作用与结果 |
+|------|------|------|
+| `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

@@ -1,121 +1,134 @@
-# AUN SDK 文档查阅指南
-
-AUN SDK 文档位于 `docs/sdk/`，索引文件 `docs/sdk/INDEX.md` 分三层：Layer 1 地图、Layer 2 主题索引、Layer 3 单篇摘要。按需逐层读取，避免一次性加载整套文档。
-
-## SDK 文档定位
-
-当前 SDK 聚焦三主体模型：
-
-- `AIDStore`：注册、加载、列举、解析和证书运维。
-- `AID`：不可变身份值对象，负责签名、验签和 agent.md 签验。
-- `AUNClient`：认证、连接、状态机、事件和 RPC。
-- `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、签名和上传前校验见 `../agent.md/SCHEMA.md` 与 `04-连接与认证.md`。当前 Ownership 2.1 应用接入见 `Ownership2.1-SDK应用集成指南.md`，SDK 移植见 `Ownership2.1-SDK开发与移植指南.md`，wire schema 见 `../protocol/Ownership协议定义2.1.md`；旧集成/实现指南与管理专题为 legacy。Group/Org owner 不走通用流程，名片 owner 本人尾签、signer_aid、完整 V2 授权、实体证书代际和授权过期停传/保留待办/明确上传见协议 §1.3/§2.5。A/T/H、SDK 内部自动最新页同步、Forward 调度和每个 AUNClient 一个 Pull Gate（始终 single-inflight、相同 key 折叠、不同 key 排队、前台 FIFO 优先）见 `03-核心概念.md`；`message.history` / `group.history` 与 Piggy ACK 见 Message/Group RPC Manual。
-
+# AUN SDK 文档查阅指南
+
+AUN SDK 文档位于 `docs/sdk/`，索引文件 `docs/sdk/INDEX.md` 分三层：Layer 1 地图、Layer 2 主题索引、Layer 3 单篇摘要。按需逐层读取，避免一次性加载整套文档。
+
+## SDK 文档定位
+
+当前 SDK 聚焦三主体模型：
+
+- `AIDStore`：注册、加载、列举、解析、证书运维与通用 raw/document 多签。
+- `AID`：不可变身份值对象，负责签名、验签和 agent.md 签验。
+- `AUNClient`：认证、连接、状态机、事件和 RPC。
+- `PushFacade`：Python SDK 的当前安装推送登记、注销和 Push Server 批次 ACK。
+- `ServiceProxyClient`：Python SDK 的 Service Proxy provider 侧客户端，负责 Gateway 控制面注册和 proxy-server 数据面隧道注册。
+
+业务 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`。
 跨设备业务已读的 `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`。
-
-## 渐进式查阅流程
-
-### Step 1：读 Layer 1
-
-查看文档地图，能定位目标就直接读目标文档。
-
-### Step 2：按主题读 Layer 2
-
-常见主题：
-
+
+## 渐进式查阅流程
+
+### Step 1：读 Layer 1
+
+查看文档地图，能定位目标就直接读目标文档。
+
+### Step 2：按主题读 Layer 2
+
+常见主题：
+
 - 身份与认证：AIDStore / AID / 注册 / 加载 / 证书
-- Ownership 2.1：当前应用/移植指南、七 Facade、双文件/锁/版本；Group/Org 专属生命周期、owner 本人名片、原 V2 授权复用、过期明确上传、无消息释放清理与 not_applicable 门禁；v1/proof/escrow 文档为 legacy
+- Ownership 2.1：关系仅由当前 agent.md/owner.md 确认；release 保持 v，清理后版本投影为 0／重绑默认 1，Header 只投影校验结果；普通 agent 注册 owner 可选；owner 当前完整原文/摘要/存在性再读，object_id/version 不为读取一致性条件；owner.md 通过 create_upload_session→HTTP PUT→complete_upload 的同一会话发布，expected_version 作发布 CAS，不提供全局/ABA保证；新服务端兼容旧 SDK 的注册、绑定、转移、查询和解绑 RPC 及隔离 Auth JSONL，只激活旧 NS ownership_proof，不写 2.1 双文件，不授 2.1 lock/version/consensus，不覆盖已存现代声明；新 SDK 关系操作不兼容旧服务端；当前应用/移植指南、七 Facade 与 Group/Org 专属生命周期、实体主签及原始多签恢复；v1/proof/escrow 文档为 legacy
 - 连接与状态：AUNClient / 九态状态机 / Gateway / 重连 / 当前 access token getter / connect-disconnect-close 并发与取消
-- 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 共享，始终单飞、相同 key 折叠、不同 key 排队、前台 FIFO 优先）、`source` 来源、`sync.started/progress/stopped` 生命周期、缺 sender IK 有界同步 bootstrap、永久页内 Gap、坏密文推进
+- 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
+- 消息同步：共享 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
 - Group RPC：成员 block/status、暂停群权限、两阶段群主转让、`group_aid` / `group_id` 兼容、`group.index` 签名索引与 CAS（见 `09-group-rpc-manual.md`、`06-API手册.md`）
-- 群文件系统：`group.fs.*`、`client.group.fs.*`、`aun group fs`、`cp/mv` 上传下载、群自有区角色 ACL 与 `group_aid` 签名、`parents`、JS string 差异和 memberdata 服务端映射（见 `09-group-rpc-manual.md`）
-- 协作（collab）：`collab.*` 版本化文档、乐观锁 CAS commit、三方合并、标签、GC、reflog、revert（见 `09-collab-rpc-manual.md`）
-- Service Proxy：`ServiceProxyClient`、`proxy.register_services`、proxy-server `register_services`
-- agent.md：Schema/frontmatter、尾部签名、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` 角色
+- 群文件系统：`group.fs.*`、`client.group.fs.*`、`aun group fs`、`cp/mv` 上传下载、群自有区角色 ACL 与 `group_aid` 签名、`parents`、JS string 差异和 memberdata 服务端映射（见 `09-group-rpc-manual.md`）
+- 协作（collab）：`collab.*` 版本化文档、乐观锁 CAS commit、三方合并、标签、GC、reflog、revert（见 `09-collab-rpc-manual.md`）
+- 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` 角色
 - 错误处理：Result、Python `ErrorInfo.cause`、异常、错误码、重试
-
-### Step 3：读 Layer 3 摘要
-
-不确定哪篇文档包含细节时，先看单篇摘要，再打开原文目标章节。
-
-## 文档总览
-
-| 编号 | 文档 | 定位 |
-|------|------|------|
+
+### Step 3：读 Layer 3 摘要
+
+不确定哪篇文档包含细节时，先看单篇摘要，再打开原文目标章节。
+
+## 文档总览
+
+| 编号 | 文档 | 定位 |
+|------|------|------|
+| - | [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、语言差异及验收 |
 | - | [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 校验和自动观察 |
-| - | [Ownership管理专题](Ownership管理专题.md) | 四端 P2P owner API、应用层 accept/reject、完整消息 payload、identity escrow、owner 代签 agent.md、metadata 状态和验签边界 |
-| - | [Ownership SDK集成指南](Ownership-SDK集成指南.md) | TypeScript 快速接入、应用审批、状态查询及 SDK 编排流程图 |
-| - | [Ownership SDK实现指南](Ownership-SDK实现指南.md) | SDK 移植入口、消息拦截、proof/escrow、metadata 和恢复验收 |
-| - | [Ownership协议定义](../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 和共同向量 |
-| 05 | [E2EE加密通信](05-E2EE加密通信.md) | E2EE V2、ProtectedHeaders、agent.md 版本提示、recipient wrap |
+| 01 | [快速开始](01-快速开始.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管理专题（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 和共同向量 |
+| - | [凭证服务 RPC 手册](09-凭证服务RPC手册.md) | Credential Service 实际 RPC、参数和签名状态响应 |
+| - | [组织服务 RPC 手册](09-组织服务RPC手册.md) | Org Service 生命周期/成员 RPC、内部接口和未实现方法 |
+| 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（始终单飞）、测试数据 |
+| 08 | [最佳实践](08-最佳实践.md) | 幂等、消息同步/History、AUNClient 级 Pull Gate（同 namespace 单飞、客户端最多 4 个并行）、测试数据 |
 | - | [Storage RPC 手册](09-storage-rpc-manual.md) | Storage RPC、实际字节 MIME、三阶段 Content-Type、OSS 403、HTTP 下载与凭据边界 |
 | - | [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 数据面注册 |
-| 09 | [AID托管API手册](09-custody-api-manual.md) | 可选 custody HTTP 服务 |
-
-## 常见查阅场景
-
-| 场景 | 推荐路径 |
-|------|----------|
-| 了解最新版本特性和改进 | [CHANGELOG-0.5.6](CHANGELOG-0.5.6.md) |
-| 首次使用 SDK | [01-快速开始](01-快速开始.md) |
-| 理解新构造入口 | [01-快速开始](01-快速开始.md)、[06-API手册](06-API手册.md) |
+| 09 | `09-*-rpc-manual.md` | 各服务 RPC 参数和响应 |
+| 09 | [Service Proxy RPC手册](09-proxy-rpc-manual.md) | `proxy.*` 控制面和 proxy-server 数据面注册 |
+| 09 | [AID托管API手册](09-custody-api-manual.md) | 可选 custody HTTP 服务 |
+
+## 常见查阅场景
+
+| 场景 | 推荐路径 |
+|------|----------|
+| 接入或升级 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) |
+| 首次使用 SDK | [01-快速开始](01-快速开始.md) |
+| 理解新构造入口 | [01-快速开始](01-快速开始.md)、[06-API手册](06-API手册.md) |
 | 注册或加载 AID | [04-连接与认证](04-连接与认证.md) |
-| 查 owner 关系、ownership proof、`bindAid`/`bindOwner`、identity escrow 或 owner 代签 agent.md | [Ownership管理专题](Ownership管理专题.md)、[06-API手册](06-API手册.md) |
-| 首次在应用中集成 Ownership 2.1 | [当前应用集成指南](Ownership2.1-SDK应用集成指南.md)、[编排指南 2.1](Ownership-SDK编排指南2.1.md) |
-| 实现或移植 Ownership 2.1 SDK | [当前开发与移植指南](Ownership2.1-SDK开发与移植指南.md)、[详细设计](Ownership2.1详细设计.md) |
-| Ownership 2.1 本轮 13 项复审、四端参考与验证边界 | [审查报告第十二节](../audit/Ownership2.1代码审查报告.md#十二2026-10-11-本轮复审与修复)、[TDD 复审验收](Ownership2.1-TDD分阶段实施计划.md#137-2026-10-11-本轮复审修复验收) |
-| 当前 Ownership 2.1 与 Group/Org 名片 wire | [协议 2.1](../protocol/Ownership协议定义2.1.md) §1.3/§2.5；旧 escrow/授权头仅查 legacy 协议 |
-| 应用接入 Credential/Org 服务 | [凭证与组织服务 SDK 应用集成指南](凭证与组织服务SDK应用集成指南.md) |
-| 实现或移植 Credential/Org SDK | [凭证与组织服务 SDK 开发与移植指南](凭证与组织服务SDK开发与移植指南.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 当前格式、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 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 | [../agent.md/SCHEMA.md](../agent.md/SCHEMA.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) |
-| 登记、更新或注销 `push_notify_aid` | [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)、`docs/protocol/15-离线推送通知协议.md` |
+| 发布、下载、检查或排查 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) |
+| 查 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) |
-| 查 group.index 签名索引、版本观察、不同步判断、CAS 更新和 facade | [03-核心概念.md](03-核心概念.md)、[06-API手册.md](06-API手册.md)、[09-group-rpc-manual.md](09-group-rpc-manual.md)、[08-最佳实践.md](08-最佳实践.md) |
-| 查群文件系统 RPC / SDK / CLI 入口、群自有区角色 ACL 授权/撤销/查询、`parents` 和 JS string 差异 | [09-group-rpc-manual.md](09-group-rpc-manual.md)、[06-API手册](06-API手册.md) |
+| 查 group.index 签名索引、版本观察、不同步判断、CAS 更新和 facade | [03-核心概念.md](03-核心概念.md)、[06-API手册.md](06-API手册.md)、[09-group-rpc-manual.md](09-group-rpc-manual.md)、[08-最佳实践.md](08-最佳实践.md) |
+| 查群文件系统 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) |
-| 查协作（版本化文档/乐观锁/标签/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) |
-| 查 payload 格式 | [09-payload-reference.md](09-payload-reference.md) |
+| 查协作（版本化文档/乐观锁/标签/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) |
+| 查 payload 格式 | [09-payload-reference.md](09-payload-reference.md) |
 | 排查错误或读取 Python 本地原始异常 `cause` | [07-错误处理](07-错误处理.md) |
-| 写测试或 demo | [08-最佳实践](08-最佳实践.md) |
-
-
+| 写测试或 demo | [08-最佳实践](08-最佳实践.md) |
+
+