@agentunion/fastaun-browser 0.5.18 → 0.5.19

package/_packed_docs/protocol/01-/350/272/253/344/273/275/344/270/216/345/207/255/350/257/201/345/215/217/350/256/256-auth.md

@@ -92,98 +92,11 @@ AID 命名规则：
 }
 ```
 
-**说明**：
-- Gateway 将请求转发到 Auth 服务，Auth 服务调用 CA 签发证书
-- 创建 AID 时固定签发 P-256 证书，确保最大兼容性
-- 协议默认允许创建任意 `aid`；命名冲突、抢注、保留名、审批制等约束由具体网络运营策略决定
-- 客户端需保存返回的证书和本地生成的私钥
-
-### 1.3.1 带 type/owner 的新注册流程
-
-`auth.create_aid` 只负责签发证书，保持 legacy 兼容语义，不创建 owner relation。支持 owner 的新身份由 SDK 先完成证书签发，再调用以下可恢复 operation：
-
-```text
-证书签发(auth.create_aid)
-  → auth.aid_register_prepare
-  → auth.aid_register_submit（subject/owner 签名，可分批）
-  → 使用 owner_operation_id 发布带 ownership_proof 的 agent.md
-  → auth.aid_register_activate
-```
-
-#### auth.aid_register_prepare
-
-| 参数 | 类型 | 必需 | 说明 |
-|------|------|:----:|------|
-| `aid`（或 `subject_aid`） | string | 是 | subject AID；服务端规范化为小写 |
-| `type`（或 `aid_type`） | string | 是 | `human`、`agent`、`group`、`service`、`device`、`host`、`org`、`custom` |
-| `owner`（或 `owner_aid`） | string | 条件 | 非 `human` 必填；`agent` 可与 subject 相同 |
-| `idempotency_key` | string | 否 | 相同 kind/subject/key 返回同一 operation |
-
-约束：`human` 不得指定 owner；非 `human` 必须指定 owner；只有 `agent` 允许 self-owner；外部 owner 必须是已登记且状态为 `active` 或 `not_applicable` 的 `human`/`agent`，并且不能形成 owner 环。prepare 成功后 operation 的初始 state 为 `proof_pending`（无 owner 的 human 为 `agent_md_pending`），TTL 固定为 7 天。
-
-Auth 可登记 `org` 关系类型；但当前 CA/Name Service 只实现 `signing` 与 `group_identity` 证书用途，尚未实现 `org_identity` 映射。组织身份若使用现有流程，不能按已实现的组织专用证书用途对外承诺。
-
-**响应**（字段会按场景返回）：
-
-```json
-{
-  "operation_id": "op-...",
-  "kind": "register",
-  "aid": "sensor.agentid.pub",
-  "subject_aid": "sensor.agentid.pub",
-  "type": "agent",
-  "owner": "alice.agentid.pub",
-  "owner_aid": "alice.agentid.pub",
-  "state": "proof_pending",
-  "operation_state": "proof_pending",
-  "ownership_status": "pending",
-  "relation_version": 0,
-  "proof_id": "550e8400-e29b-41d4-a716-446655440000",
-  "fact_hash": "<64 lowercase hex>",
-  "statement_hash": "<64 lowercase hex>",
-  "expires_at": "2026-10-13T00:00:00Z"
-}
-```
-
-#### auth.aid_register_submit
-
-请求至少包含 `operation_id`，并可分批提交：
-
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| `subject_signature` | object | subject 对 ownership statement 的签名 |
-| `owner_signature` | object | 外部 owner 对同一 statement 的签名；self-owner 禁止 |
-
-签名封套只允许 `cert_fingerprint`（`sha256:<64 hex>`）和严格 Base64 的 `signature`。提交后双方签名齐全时 state 变为 `agent_md_pending`；重复提交相同签名幂等，替换已保存签名返回 `owner_relation_conflict`。
-
-#### auth.aid_register_activate / auth.aid_register_status
-
-`auth.aid_register_activate` 只接受 `operation_id`。客户端必须先用该 operation 的一次性 `owner_operation_id` 发布与 operation 完全匹配的 `agent.md`，成功后返回 `ownership_status=active`（`human` 返回 `not_applicable`）和 `relation_version=1`。`auth.aid_register_status` 接受 `aid`，返回当前登记或 pending operation 的状态。
-
-### 1.3.2 已有 AID 的 aid_bind 流程
-
-旧客户端通过 `auth.create_aid` 创建的 AID，以及已被 `owner_relation_unbind` 解除关系的 AID，使用 `auth.aid_bind_prepare`、`auth.aid_bind_submit`、`auth.aid_bind_activate` 和 `auth.aid_bind_status` 建立或重建关系。该流程不签发新证书、不改变 AID、密钥、登录或消息通信身份；绑定期间状态为 `legacy_unbound`/`pending`，基本登录和通信仍可用。
-
-`aid_bind_prepare` 的参数和签名规则与新注册相同，但 active relation 不能被 bind 替换；已存在的 type/owner 只能重复提交完全相同的值。绑定失败或 operation 过期不会吊销证书。`auth.aid_operation_get` 接受 `operation_id`，用于进程重启后查询并恢复 pending operation。
-
-### 1.3.3 Ownership proof 与 canonical bytes
-
-四端实现必须对同一 UTF-8 字节序列计算摘要和签名：
-
-```text
-fact = canonical_json({"subject_aid": subject_aid, "owner_aid": owner_aid})
-statement = canonical_json({"proof_id": proof_id, "subject_aid": subject_aid, "owner_aid": owner_aid})
-signing_bytes = UTF-8("AUN-AID-OWNER-RELATION-V1;") || statement
-```
-
-对象键按字典序、无空格；AID 先规范化为 ASCII 小写；`proof_id` 必须为 UUID v4。`fact_hash=SHA-256(fact)`，`statement_hash=SHA-256(signing_bytes)`，均为裸小写十六进制。agent.md 的 `owner` 与 `ownership_proof` 必须同时出现；proof 的 `subject_aid`/`owner_aid` 必须分别等于 agent.md 的 `aid`/`owner`。`human` 不得携带这两个字段。
-
-### 1.3.4 Owner change、解绑与 type 变更
-
-- `auth.owner_change_prepare` 参数为 `subject_aid`、`new_owner_aid`、可选 `current_owner_aid`、`expected_relation_version`、`idempotency_key`；只允许当前 owner 发起，并检查 CAS、owner 类型和环。operation 的 `transfer_payload` 包含 `operation_id`、subject、old/new owner、new proof、当前 relation version、challenge nonce 和过期时间。
-- `auth.owner_change_submit` 接收 `old_owner_signature`、`subject_signature`、`new_owner_signature`。old owner 签署 `AUN-AID-OWNER-TRANSFER-V1;` 加 `transfer_payload`；subject 和 new owner 签署新的 ownership statement。三份签名齐全后发布新 agent.md，再调用 `auth.owner_change_activate`。
-- 激活成功后 `relation_version` 递增；旧 owner 的 relation ACL 被撤销但数据保留，新 owner 的 ACL 被创建。subject 自身签名不能替代 old owner 授权。
-- `auth.owner_relation_status` 查询当前关系；`auth.owner_relation_unbind` 只允许当前 owner（可带 `expected_relation_version`），状态变为 `unbound`，版本递增，证书和数据保留；`auth.aid_type_change` 修改登记 type，但有 active 子关系时拒绝。
+**说明**：
+- Gateway 将请求转发到 Auth 服务，Auth 服务调用 CA 签发证书
+- 创建 AID 时固定签发 P-256 证书，确保最大兼容性
+- 协议默认允许创建任意 `aid`；命名冲突、抢注、保留名、审批制等约束由具体网络运营策略决定
+- 客户端需保存返回的证书和本地生成的私钥
 
 ## 1.4 auth.aid_login1 / auth.aid_login2
 
@@ -356,48 +269,48 @@ signature = ECDSA_sign(private_key, SHA256(message))
 {
   "jsonrpc": "2.0",
   "id": 4,
-  "result": {
-    "success": true,
-    "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
-    "refresh_token": "new_refresh_token...",
-    "expires_in": 3600,
-    "aid": "alice.agentid.pub",
-    "refresh_count": 12,
-    "relogin_required": false,
-    "retryable": false,
-    "diagnostic": {
-      "aid": "alice.agentid.pub",
-      "refresh_count": 12
-    }
-  }
-}
-```
+  "result": {
+    "success": true,
+    "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
+    "refresh_token": "new_refresh_token...",
+    "expires_in": 3600,
+    "aid": "alice.agentid.pub",
+    "refresh_count": 12,
+    "relogin_required": false,
+    "retryable": false,
+    "diagnostic": {
+      "aid": "alice.agentid.pub",
+      "refresh_count": 12
+    }
+  }
+}
+```
 
 **说明**：
 - 调用时提交当前持有的 `refresh_token`
-- 服务端验证后吊销旧 `refresh_token`，签发新的 `access_token` 和 `refresh_token`
-- 旧 access_token 在其过期时间前仍然有效（JWT 标准行为），但客户端应立即切换到新 token
-- 建议在 access_token 过期前 60 秒刷新
-- 响应包含结构化状态字段：`relogin_required=true` 表示客户端必须放弃本地 token 并重新登录；`retryable=true` 表示可退避重试；`diagnostic` 只包含脱敏诊断字段
-
-**失败响应示例**：
-
-```json
-{
-  "success": false,
-  "error": "invalid_or_expired_refresh_token",
-  "relogin_required": true,
-  "retryable": false,
-  "diagnostic": {
-    "refresh_token_hash_prefix": "sha256:abcd..."
-  }
-}
-```
-
-**刷新限制**：
-- 刷新链总时长不超过 30 天，或最多刷新 720 次
-- 达到限制后返回 `relogin_required=true`，客户端必须重新执行完整的两阶段认证
-- 具体限制值由服务端实现决定
+- 服务端验证后吊销旧 `refresh_token`，签发新的 `access_token` 和 `refresh_token`
+- 旧 access_token 在其过期时间前仍然有效（JWT 标准行为），但客户端应立即切换到新 token
+- 建议在 access_token 过期前 60 秒刷新
+- 响应包含结构化状态字段：`relogin_required=true` 表示客户端必须放弃本地 token 并重新登录；`retryable=true` 表示可退避重试；`diagnostic` 只包含脱敏诊断字段
+
+**失败响应示例**：
+
+```json
+{
+  "success": false,
+  "error": "invalid_or_expired_refresh_token",
+  "relogin_required": true,
+  "retryable": false,
+  "diagnostic": {
+    "refresh_token_hash_prefix": "sha256:abcd..."
+  }
+}
+```
+
+**刷新限制**：
+- 刷新链总时长不超过 30 天，或最多刷新 720 次
+- 达到限制后返回 `relogin_required=true`，客户端必须重新执行完整的两阶段认证
+- 具体限制值由服务端实现决定
 
 ## 1.6 证书生命周期方法
 
@@ -646,9 +559,7 @@ signature = ECDSA_sign(private_key, SHA256(message))
 | `-32003` | Signature verification failed — 签名验证失败 |
 | `-32005` | Authentication expired — Token 过期或刷新链耗尽 |
 
-> 通用 JSON-RPC 2.0 错误码（-32700/-32600/-32601/-32602/-32603）同样适用，见 [07-JSON-RPC](07-JSON-RPC.md)。
-
-Owner relation 方法使用 JSON-RPC `-32602`，并在 `error.data.error_code` 中返回稳定错误码；完整列表和 `signature_verification_unavailable`、`type_change_blocked`、`aid_binding_required` 的说明见 [07-错误码与状态机](07-错误码与状态机.md) §7.1。
+> 通用 JSON-RPC 2.0 错误码（-32700/-32600/-32601/-32602/-32603）同样适用，见 [07-JSON-RPC](07-JSON-RPC.md)。
 
 ## 1.9 安全说明
 

package/_packed_docs/protocol/07-/351/224/231/350/257/257/347/240/201/344/270/216/347/212/266/346/200/201/346/234/272.md

@@ -19,10 +19,8 @@
 | -32001 | Authentication failed（认证失败） | 检查凭据，重新登录 |
 | -32002 | Certificate/Nonce invalid（凭据无效） | 检查证书链或 nonce |
 | -32003 | Signature verification failed（签名验证失败） | 检查私钥，不重试 |
-| -32004 | Permission denied（权限拒绝） | 提示用户，不重试 |
-| -32005 | Authentication expired（Token 过期） | 刷新 token 或重新登录 |
-
-Owner relation RPC 在 `-32602 Invalid params` 的 `error.data.error_code` 中返回稳定错误码：`invalid_aid`、`invalid_aid_type`、`human_owner_forbidden`、`owner_required`、`self_owner_not_allowed`、`owner_not_verified`、`owner_type_forbidden`、`owner_relation_conflict`、`pending_operation_exists`、`operation_not_found`、`operation_expired`、`signature_invalid`、`signature_verification_unavailable`、`relation_version_conflict`、`idempotency_key_reuse`、`type_change_blocked`、`aid_binding_required`。`signature_verification_unavailable` 表示 owner 证书验证服务不可用；`type_change_blocked` 表示该 AID 仍是活动 owner；`aid_binding_required` 表示尚无已登记 type，需先完成 `aid_bind`。JSON-RPC 外层错误码仍为 `-32602`。
+| -32004 | Permission denied（权限拒绝） | 提示用户，不重试 |
+| -32005 | Authentication expired（Token 过期） | 刷新 token 或重新登录 |
 
 ### 7.1.3 AUN 协议级错误码（连接与会话）
 
@@ -104,7 +102,7 @@ Owner relation RPC 在 `-32602 Invalid params` 的 `error.data.error_code` 中
 
 | 错误码 | 说明 | 客户端处理 |
 |--------|------|-----------|
-| -33001 | Group not found | 检查规范化后的 `group_aid`（`group_id` 为兼容参数名） |
+| -33001 | Group not found | 检查规范化后的 `group_aid`（`group_id` 为兼容参数名） |
 | -33002 | Group state invalid（群状态不允许该操作） | 检查群状态 |
 | -33003 | Group suspended | 等待恢复或联系管理员 |
 | -33004 | Group member limit reached | 不重试 |
@@ -222,21 +220,8 @@ submitted → working → completed
 | input_required | | working, failed, canceled |
 | rejected | 是 | |
 | completed | 是 | |
-| failed | 是 | |
-| canceled | 是 | |
-
-### 7.4.1 Owner relation operation 状态机
-
-```text
-proof_pending
-  → agent_md_pending
-  → active
-
-proof_pending / agent_md_pending
-  → expired
-```
-
-`human` 注册在 agent.md 发布后进入 `not_applicable`；legacy AID 可处于 `legacy_unbound`，解绑后的关系为 `unbound`，因 owner 状态不可用时关系可标为 `unusable`，旧证书和数据保留。`owner_change` 从当前 `active` 关系创建 pending operation，三方签名和新 agent.md 激活后回到 `active`，`relation_version` 递增；CAS 不匹配或重复 pending operation 保持原关系不变。
+| failed | 是 | |
+| canceled | 是 | |
 
 ## 7.5 处理原则
 

package/_packed_docs/protocol/10-Group-/345/255/220/345/215/217/350/256/256.md

@@ -2,7 +2,7 @@
 
 > **适用版本**：AUN 1.0 | **状态**：Draft
 
-Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。Group 服务本身是一个 AID 持有者，客户端通过标准 `message.*` 协议与 Group 服务通信，Group 服务通过 JSON-RPC 2.0 暴露 `group.*` 命名空间方法。
+Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。Group 服务本身是一个 AID 持有者，客户端通过标准 `message.*` 协议与 Group 服务通信，Group 服务通过 JSON-RPC 2.0 暴露 `group.*` 命名空间方法。服务 AID、群身份 `group_aid` 与群主 `owner_aid` 是三个不同角色。群主关系由 Group 生命周期管理，不走 Ownership 2.1 的双文件绑定、释放、转移、审批或 NS 关系账本。
 
 ---
 
@@ -33,7 +33,7 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 | `owner_aid` | string | 群主 AID |
 | `creator_aid` | string | 创建者 AID |
 | `visibility` | string | `"public"` / `"private"` |
-| `status` | string | `"active"` / `"suspended"` / `"closed"` |
+| `status` | string | `"active"` / `"suspended"` / `"dissolved"` |
 | `description` | string | 群组描述 |
 | `metadata` | object | 自定义元数据 |
 | `mention_mode` | string | 群提及过滤模式：`"disabled"`（默认）/ `"mention-only"`，详见 [10.2.3 群提及过滤模式](#1023-群提及过滤模式mention_mode) |
@@ -91,7 +91,7 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 | `group_id` | string | 群组 ID |
 | `role` | string | `"owner"` / `"admin"` / `"member"` |
 | `joined_at` | integer | 加入时间（Unix 秒） |
-| `last_ack_seq` | integer | 最后已读消息序号 |
+| `last_ack_seq` | integer | 投递消费确认位置，与业务已读位置独立 |
 
 ### Member Status 对象
 
@@ -146,6 +146,8 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 
 ### `group.create`
 
+创建自动建立调用者与群的 owner 关系；群身份公私钥及证书由该 owner 持有，Group 服务不接收或保存群私钥。群名片须含当前 `owner`，不含通用 `ownership` 声明；由当前 owner 使用本人证书和私钥代签、代上传，文件 `aid` 仍是 `group_aid`。签名块 `signer_aid`、V2 上传授权、实体证书代际和条件恢复见 [Ownership 协议定义 2.1 §2.5](Ownership协议定义2.1.md#25-grouporg-名片的-owner-代签与上传)。创建、群证书绑定和名片发布的参数/响应以 [Group RPC Manual](../sdk/09-group-rpc-manual.md#groupcreate) 为准。
+
 创建群组。
 
 SDK 高层建群流程必须支持崩溃恢复：命名群复用已持久化密钥并重放相同 `group_name + public_key` 的已提交结果；匿名群复用已持久化的创建上下文，使响应丢失后的重试返回同一数字群，再继续群身份绑定和 `agent.md` 上传。服务端必须原子提交群记录、群主成员、成员索引、入群设置、首个 `group.changed` 事件及匿名创建映射。直接调用 RPC 且没有 SDK 恢复上下文时，每次调用仍表示一次新的自动群创建。
@@ -244,7 +246,7 @@ SDK 高层建群流程必须支持崩溃恢复：命名群复用已持久化密
 
 ### `group.dissolve`
 
-永久解散群组。需要 **owner** 权限。解散后不可恢复。
+永久解散群组。需要 **owner** 权限。解散后不可恢复，自动解除有效 owner 关系，终止待处理转移并撤销群证书及相关授权；旧 owner、旧证书、实体 token 和旧 pending 均不能继续上传群名片或代表群鉴权。历史 owner 和签名记录保留用于审计，不作为当前授权。解散墓碑及待转移清理先原子提交；事件发布、CA 撤销、Storage 权限失效与缓存清理通过持久 outbox 收尾，未全完成返回 -32002、status=unavailable/retryable=true/committed=true，重试续跑收尾，不能提前宣告成功。
 
 **参数**：`group_id` (string, 必填)
 
@@ -313,11 +315,19 @@ SDK 高层建群流程必须支持崩溃恢复：命名群复用已持久化密
 
 ### `group.transfer_owner`
 
-转让群主身份。需要 **owner** 权限。受让方无需手动确认，SDK 自动完成确认和转让收尾。
+发起两阶段群主转让。需要 **owner** 权限，只建立 `pending_rekey`，暂不切换 owner；新 owner 通过 `group.complete_transfer` 提交本人接受证明和新群公钥，完成强制 rekey 后切换 owner，原 owner 降为 admin。旧群证书失效，新身份材料归新 owner；新 owner 按当前代际重新代签、代上传含新 `owner` 的群名片。
 
 **参数**：`group_id` (必填), `new_owner` (必填，新群主 AID；别名 `aid` 向后兼容)
 
-**响应**：`{ "group": { ... }, "new_owner_aid": "bob.agentid.pub" }`
+**响应**：`{ "status": "pending_rekey", "requires_ca_rekey": true, "complete_rpc": "group.complete_transfer", "group": { ... }, "new_owner": "bob.agentid.pub" }`。完整参数、旧群身份授权、新 owner 接受证明及幂等规则见 [Group RPC Manual](../sdk/09-group-rpc-manual.md#grouptransfer_owner)。
+
+### `group.complete_transfer`
+
+仅待转移的新 owner 可完成，必须生成新群密钥并提交 `transfer_accept`，禁止同密钥续证代替 rekey。成功状态为 `transferred`；重复提交同一已完成转移可返回原结果。名片发布失败不反向撤销已提交的 owner 切换，SDK 保留新代际原字节和原 CAS 条件恢复上传。服务持久原已验证证书及 transfer nonce/旧 serial CAS，已提交 CA 的可恢复待办超 TTL 仍收敛，未提交 CA 的过期待办拒绝，旧请求不得提交新的转移。
+
+### `group.bind_group_aid` / `group.renew_group_aid`
+
+`bind_group_aid` 为匿名群补齐专属群身份，不是 Ownership 绑定；仅当前 owner 可操作，匹配公钥可幂等重放，不同公钥拒绝。`renew_group_aid` 是当前 owner 主动换钥，必须持有旧群私钥并提交换钥证明；它不替代两阶段 owner 转移。成功后 owner 持有新材料，并用本人身份重新代签、代上传群名片。
 
 ### `group.get_members`
 
@@ -504,7 +514,7 @@ History 不推进消息或事件 ACK，不修改 cursor/floor/Pull activity，
 
 ### `group.ack`
 
-提交已读游标（per-AID，非 per-device）。
+提交投递消费游标。SDK 的多设备/slot 游标按当前实例隔离；业务已读独立使用 `group.read/read_state`，不能以 ACK 表示用户已经阅读话题。
 
 **参数**：`group_id` (必填), `seq` (integer, 必填)
 
@@ -512,7 +522,15 @@ History 不推进消息或事件 ACK，不修改 cursor/floor/Pull activity，
 
 ---
 
-## 10.7 入群方式
+### `group.read` / `group.read_state`
+
+`group.read` 以 `states` 上报当前认证 AID/device 的群话题最后已读消息，每项包含 `group_id`、原样保存的 `topic_key`、`last_read_message_id`；缺省 scope 为 `group`。只有省略 `states` 时兼容顶层单条，显式空数组/null 拒绝；四个已读门面保留显式空值供服务端校验。历史 Group ID 别名解析为 canonical ID，新写状态键、响应和事件使用 canonical ID，历史别名参与事实/公共位置/设备映射的事务查询，权限复用既有版本同步。回执是设备写入结果，不是共享汇总。同域先校验全部项；混合域按所属域逐域校验和提交，任何域失败则 RPC 返回错误，已提交域不回滚，原样幂等重试可收敛。
+
+`group.read_state` 按当前 AID 的 `group_id`、`topic_key` 可选条件查询共享汇总；未指定群时发现本域及远域有权限的成员群。响应 `states` 包含公共 `last_read_order`、当前设备 `current_device_seq` 和 `mapping_status`（resolved/not_received/unresolved）；无映射 seq 为 null。晚到公共位置对仍匹配该消息且 order=0 的事实条件持久回填，不能只更新缓存或覆盖并发前进的事实。网络整数保持 int64 语义，Gateway 本域服务及 federation 回程不得经浮点中转，TS/JS API 超安全整数使用精确十进制字符串。
+
+共享位置已提交并前进后发布 `event/group.read_changed`，SDK 订阅名为 `group.read_changed`，owner 必须非空且为当前身份，scope 必须匹配原事件；Gateway 校验 Kernel 转发的可信 Group 来源，即使显式 route 也只向该 owner AID 分发，支持所属域向该外域成员 AID 转发，不能广播给其他成员。事件 ID 对身份、话题及公共位置组成的 JSON 元组取 SHA-256，失败日志不泄露 topic。事件包含 owner AID、scope、group、topic、消息 ID、公共顺序和更新时间，不进入 Pull 队列。SDK 重连保留原查询过滤范围，通过仅本地发布的 `read_state_sync` 交付本轮状态及逐项错误；身份切换按代际隔离旧缓存及补偿完成事件，A→B→A 也不能接收旧代际结果；原在途 RPC 仍可返回。完整契约见 `aun-sdk-core/docs/跨设备已读未读详细设计.md`。
+
+## 10.7 入群方式
 
 ### `group.request_join`
 
@@ -776,7 +794,8 @@ Group 服务通过 `event/group.*` 事件推送变更通知给相关 AID。
 | `member_left` | 成员退出 |
 | `member_removed` | 成员被踢出 |
 | `role_changed` | 角色变更 |
-| `owner_transferred` | 群主转让 |
+| `owner_transfer_rekey_pending` | 群主转让已发起，等待新 owner 完成强制换钥与确认 |
+| `owner_transferred` | 强制 rekey 后群主转让完成 |
 | `rules_updated` | 规则更新 |
 | `announcement_updated` | 公告更新 |
 | `join_requested` | 收到入群申请 |

package/_packed_docs/protocol/11-Storage-/345/255/220/345/215/217/350/256/256.md

@@ -31,6 +31,14 @@ Storage 服务是 AUN 协议的应用层扩展，提供对象存储能力。负
 
 ## 11.3 控制面方法
 
+**权威对象与路径修订**：`storage.head_object`、`storage.get_object` 和 `storage.fs.stat` 可传 `consistency: authoritative`，绕过正向、负向缓存并确认恢复可用性。结果包含 `consistency`、`exists`、不透明 `revision`、`owner_aid`、`bucket`、无前导斜杠的 `path` 和 Unix 秒 `observed_at`；存在时附 `sha256`、`object_id`、`version`，get 另返回完整严格 Base64 `content`。故障、权限错误和恢复未完成必须失败，不能返回 `exists=false`；下载或网关 404 不能证明权威不存在。
+
+`revision` 属于逻辑路径，每次成功写入、删除后变化，删除后保留；从未创建的修订为字符串 `0`，同内容重建也不得复用旧修订。写入与删除的 `expected_revision` 必须使用调用者先前权威读取的原值，与对象 `expected_version`、ETag 和内容摘要不同。条件冲突返回既有 `-32009`，不得刷新条件强行继续旧任务。
+
+`put_object`、`create_upload_session`、`complete_upload`、`delete_object` 和 `storage.fs.remove` 支持 `expected_revision`。条件上传 session 固定目标和原修订，响应带 `session_id`、`expected_revision`，complete 按同一 session 在最终发布时再次 CAS；内容与路径修订在 Storage 本地事务中原子发布，失败保留旧完整文件。普通不带修订的调用保持原语义，Ownership 文件发布和协议清理须满足其修订条件。
+
+Ownership 2.1 的 `default/sub_aids/{sub_aid}/owner.md` 必须公开可读，只有命名空间所属 owner 可修改、删除；该限制覆盖 ACL、token、父目录、移动、重命名、软链、挂载及自动清理，不能由通用权限顺序放宽。关系释放仍以 NS 验收为准；完整规则见 [Ownership 协议定义 2.1](Ownership协议定义2.1.md)。
+
 ### `storage.put_object`
 
 内联写入小对象（≤ 内联上限）。
@@ -47,6 +55,7 @@ Storage 服务是 AUN 协议的应用层扩展，提供对象存储能力。负
 | `is_private` | boolean | ❌ | 默认 `true`，公开对象可被其他 AID 读取 |
 | `overwrite` | boolean | ❌ | 默认 `true`，`false` 时对象已存在则拒绝 |
 | `expected_version` | integer | ❌ | CAS 并发控制，版本不匹配则拒绝 |
+| `expected_revision` | string | ❌ | 原权威路径修订；Ownership 发布须携带 |
 | `expire_in_seconds` | integer | ❌ | 过期时间，`0` 表示永不过期 |
 | `metadata` | object | ❌ | 用户自定义元数据 |
 
@@ -67,9 +76,13 @@ Storage 服务是 AUN 协议的应用层扩展，提供对象存储能力。负
 | `owner_aid` | string | ❌ | 默认调用者 AID |
 | `bucket` | string | ❌ | 默认 `"default"` |
 | `object_key` | string | ✅ | 对象路径 |
+| `consistency` | string | ❌ | 传 `authoritative` 时绕过缓存并返回完整权威对象 |
+| `expected_revision` | string | ❌ | 条件读取使用的原权威路径修订 |
 
 **响应**：`{ owner_aid, bucket, object_key, content (base64), content_type, size_bytes, sha256, version, updated_at }`
 
+可选 `consistency: authoritative` 返回本节定义的权威对象结果；权威 get 要求完整对象，不接受范围读取。
+
 **权限**：私有对象仅所有者可读；公开对象（`is_private=false`）任何 AID 可读。
 
 ### `storage.head_object`
@@ -80,15 +93,17 @@ Storage 服务是 AUN 协议的应用层扩展，提供对象存储能力。负
 
 **响应**：`{ owner_aid, bucket, object_key, content_type, size_bytes, sha256, version, etag, is_private, expire_at, created_at, updated_at }`
 
+可选 `consistency: authoritative` 返回本节定义的权威对象结果，包括明确不存在与路径修订。
+
 **权限**：同 `get_object`。
 
 ### `storage.delete_object`
 
 删除单个对象。
 
-**参数**：同 `get_object`。
+**参数**：对象寻址同 `get_object`，可附 `expected_revision` 作条件删除。
 
-**响应**：`{ deleted (bool), owner_aid, object_key }`
+**响应**：`{ deleted (bool), owner_aid, object_key }`；条件删除附新路径 `revision`。
 
 **权限**：仅所有者可删。
 
@@ -130,7 +145,7 @@ Storage 服务是 AUN 协议的应用层扩展，提供对象存储能力。负
 
 **权限**：仅所有者可列。
 
-### `storage.get_quota`
+### `storage.get_quota`
 
 查询存储配额使用情况。
 
@@ -142,30 +157,7 @@ Storage 服务是 AUN 协议的应用层扩展，提供对象存储能力。负
 
 **响应**：`{ owner_aid, used_bytes, object_count, quota_bytes }`
 
-**权限**：仅所有者可查。
-
-### `storage.relation_backup_provision`
-
-由 Auth 服务在 external owner relation 激活或重建时内部调用，普通客户端不得调用。请求必须带 `_caller_id="auth"`，参数如下：
-
-| 参数 | 类型 | 必需 | 说明 |
-|------|------|:----:|------|
-| `owner_aid` | string | 是 | 外部 owner AID |
-| `subject_aid` | string | 是 | 被管理的 subject AID；与 owner 不同 |
-| `proof_id` | string | 是 | 当前 active ownership proof |
-| `relation_version` | integer | 是 | 当前关系版本，>=1 |
-
-服务端在 owner 的 `default` bucket 创建或复用固定命名空间 `.aun/subjects/<lowercase_subject_aid>`，并写入 subject 的 `rw` ACL。成功响应包含 `schema=aun.relation-backup-namespace.v1`、`owner_aid`、`subject_aid`、`proof_id`、`relation_version`、`bucket=default`、`path`、`acl_source=ownership_relation`、`acl_generation`、`status=ready`、`on_revoke=retain_data_revoke_acl` 和 `data_retained=true`。首次 provision 的 `acl_generation` 为 1；同一 proof/version 重复调用幂等。
-
-### `storage.relation_backup_revoke`
-
-由 Auth 服务内部调用，参数为 `owner_aid`、`subject_aid` 和可选 `expected_relation_version`。服务端只移除 subject 的 relation ACL，不删除命名空间或其中数据，响应 `status=retained`、`data_retained=true`，并递增 `acl_generation`。记录不存在返回 `-32008`；Auth 之外的调用返回 `-32004`。
-
-### `storage.relation_backup_status`
-
-查询关系备份命名空间元数据，不返回目录内容。请求参数：`subject_aid` 必填，`owner_aid` 可选。调用者必须是 owner 或 subject；其它调用返回 `-32004`。未创建记录返回 `status=pending`、`acl_generation=0`、`data_retained=false`；已撤销记录返回 `status=retained`，数据仍保留。
-
-关系备份目录的权限约束：subject 仅在关系 `ready` 时访问自己的 `.aun/subjects/<subject>/` 后代，不能枚举 `.aun/subjects/` 根或其它 subject 目录，不能删除自己的 subject 根目录，也不能修改 ACL、visibility、token、share 或 mount。owner 可读写目录数据，但不能通过普通 Storage RPC 修改关系 ACL。
+**权限**：仅所有者可查。
 
 ---
 
@@ -187,6 +179,7 @@ Storage 服务是 AUN 协议的应用层扩展，提供对象存储能力。负
 | `size_bytes` | integer | ❌ | 预期大小（客户端追踪用） |
 | `content_type` | string | ❌ | 默认 `application/octet-stream` |
 | `expected_version` | integer | ❌ | CAS 版本检查（签 URL 前校验） |
+| `expected_revision` | string | ❌ | 固定上传 session 的原权威路径修订，最终发布再次检查 |
 | `expire_in_seconds` | integer | ❌ | URL 有效期，默认 3600 秒 |
 
 **响应**：`{ upload_url, blob_key, expire_at, owner_aid, bucket, object_key, content_type, size_bytes }`
@@ -215,6 +208,8 @@ Storage 服务是 AUN 协议的应用层扩展，提供对象存储能力。负
 | `expire_in_seconds` | integer | ❌ | 过期时间，默认永不过期 |
 | `metadata` | object | ❌ | 用户自定义元数据 |
 | `expected_version` | integer | ❌ | CAS 并发控制 |
+| `expected_revision` | string | ❌ | 原权威路径修订；使用条件 session 时须与 session 一致 |
+| `session_id` | string | ❌ | create_upload_session 返回的条件上传 session |
 
 **响应**：`{ owner_aid, bucket, object_key, size_bytes, content_type, sha256, version, etag, updated_at }`
 

package/_packed_docs/protocol/agent.md/SCHEMA.md

@@ -2,6 +2,10 @@
 
 版本: 1.0.0
 
+本文是 legacy Agent.md 1.0 历史副本，不定义当前尾部文件签名或 Ownership 2.1。当前文件容器、可扩展 type、AID 和 ownership 字段以 [Ownership 协议定义 2.1](../Ownership协议定义2.1.md) 为准；[Ownership 2.0 Schema](../../agent.md/SCHEMA.md) 也属于历史版本。
+
+当前 Group/Org 仅由专属生命周期的 owner 本人代签代上传，owner 必填而 ownership 可缺省，签名块必含 signer_aid；完整规则见 [当前协议 §2.5](../Ownership协议定义2.1.md#25-grouporg-名片的-owner-代签与上传)，不采用本历史副本的签名方式。
+
 ## 限制
 
 - **文件大小**: 最大 4KB

package/_packed_docs/sdk/04-/350/277/236/346/216/245/344/270/216/350/256/244/350/257/201.md

@@ -139,7 +139,7 @@ await client.connect({
 | `short_ttl_ms` | 短连接服务端兜底超时 |
 | `delivery_mode` | 连接级投递语义 |
 | `extra_info` | 应用层自定义连接信息；下划线开头的键不会透传给 Gateway |
-| `background_sync` | 连接成功后是否执行 SDK 后台补洞 / 未读同步，默认开启 |
+| `background_sync` | 连接成功后是否执行消息后台补洞 / 未读同步，默认开启；不关闭已读状态查询补偿 |
 | `auto_reconnect` | 断线后是否自动重连 |
 | `heartbeat_interval` | 心跳间隔，秒 |
 | `retry.initial_delay` / `retry.max_delay` | 退避重连参数 |
@@ -210,13 +210,16 @@ print(client.can_connect, client.can_send, client.is_online)
 | `group.changed` | 群组事件 |
 | `message.undecryptable` / `group.message_undecryptable` | E2EE 解密失败 |
 | `delivery.changed` | SDK 本地批量交付完成通知，用于合并 UI 刷新（完整契约见 [06-API手册](06-API手册.md#deliverychanged)） |
+| `read_state_sync` | SDK 本地已读状态补偿完成，含本轮 `owner_aid`、`states` 和逐项 `errors`；连接返回不代表补偿完成 |
 
-建议在 `connect()` 前注册事件处理器。
+建议在 `connect()` 前注册事件处理器。`read_state_sync` 只交付本轮成功查询涉及的去重状态及逐项错误，空查询不夹带旧缓存。AID/device 切换按身份代际隔离缓存、登记及补偿完成事件，A→B→A 也不能接受旧代际结果；原在途 RPC 仍可返回。
 
 ---
 
 ## Agent Web / agent.md
 
+以下普通主体示例以本 AID 签名和 token 上传。Group/Org 使用专属 owner 生命周期：owner 与 entity_cert_fingerprint 必填、可无 ownership；仅当前 owner 用本人证书和私钥尾签（signer_aid=owner）并携带 V2 owner 授权，实体自身 token 不授予名片上传权。上传与恢复新鲜核对 owner/状态及实体证书代际，格式见 [Ownership 协议 §2.5](../protocol/Ownership协议定义2.1.md#25-grouporg-名片的-owner-代签与上传)。
+
 发布自己的 agent.md：
 
 ```python