@agentunion/fastaun-browser 0.5.18 → 0.5.19

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

@@ -83,9 +83,11 @@
 | [group.pull](#grouppull) | 增量拉取消息 |
 | [group.history](#grouphistory) | 向前只读翻页群消息 |
 | [group.pull_events](#grouppull_events) | 增量拉取事件 |
-| [group.ack](#groupack) | 确认已读（旧接口，等同 ack_messages） |
-| [group.ack_messages](#groupack_messages) | 确认消息游标 |
-| [group.ack_events](#groupack_events) | 确认事件游标 |
+| [group.ack](#groupack) | 确认投递消息游标（旧接口，等同 ack_messages） |
+| [group.ack_messages](#groupack_messages) | 确认消息游标 |
+| [group.ack_events](#groupack_events) | 确认事件游标 |
+| [group.read](#groupread) | 上报当前设备的群话题业务已读位置 |
+| [group.read_state](#groupread_state) | 查询当前 AID 的跨设备群已读汇总 |
 
 ### 多设备管理
 
@@ -165,9 +167,19 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 
 ## 群组生命周期
 
+群 owner 由本节生命周期自动建立、转移和解除，不进入 Ownership 2.1 的 `owner.md`、关系版本、owner 锁、P2P 审批或通用 Facade。创建时群公私钥及证书归初始 owner 持有；解散解除有效 owner 授权；专属转移必须 rekey，旧材料失效，新材料归新 owner。Group 服务从不保存群私钥。
+
+### 群 agent.md 的 owner 代签与上传
+
+群名片的 `aid` 为 `group_aid`、`type=group`、`owner` 必须为当前群主；frontmatter 必含 `entity_cert_fingerprint` 当前群证书指纹。缺省 `ownership` 合法，`ownership`、`ownership_proof`、`ownership_release` 禁止。只有当前 owner 使用本人私钥和证书尾签、代上传，尾部须含 `signer_aid=owner`。上传使用 V2 `AUN-AGENTMD-OWNER-AUTHORIZATION`，绑定完整文件摘要、目标群、owner 和与 frontmatter 相等的群证书指纹；群证书指纹是 owner/rekey 代际，不是通用关系版本。完整格式、CAS、pending 恢复和错误分类见 [Ownership 协议定义 2.1 §2.5](../protocol/Ownership协议定义2.1.md#25-grouporg-名片的-owner-代签与上传)。
+
+管理员的 `group.update`、`group.index` 或群文件权限不授予群名片代签代上传权。群自身 token、群私钥或仅有旧 owner 名片不能替代当前 owner 授权。转移完成后新 owner 用本人身份重新签署含新 owner 的名片；解散后禁止名片发布。普通 Ownership Facade 对群目标直接返回 `not_applicable`，不自动转调用群方法。
+
+群名片 HTTP GET/HEAD 保留原 bytes/ETag，新鲜验证后返回 not_applicable 和实体 current/stale、当前 owner/证书指纹头；名片真正 missing 的404仍提供权威owner/FP和stale、无ETag，实际DB/权威依赖故障503/unavailable；四端默认NS权威owner/FP并独立fresh PKI核对，不信raw owner。转移后的旧名片仍可 200/304，新 owner 以内部 fresh raw 读取的该 ETag 条件替换，不能从历史名片推导当前权限。SDK 公开 verified 下载已知 owner/实体指纹变化返回 conflict，非法签名或吊销返回 invalid，权威依赖故障返回 unavailable，不能将 stale 成功作为当前名片；本地 owner 尾签同样核对当前 active_signing、链和吊销状态。生命周期/证书依赖失败为 HTTP 503，实体指纹冲突 409、ETag 冲突 412。下列创建、两阶段转移和解散均为现有生命周期路径，四端名片编排与恢复按上述约束补齐。
+
 ### group.create
 
-创建群组。调用者自动成为 owner。支持创建命名群（传入 `group_name` + `public_key`）。新建群主标识以 `group_aid` 为准；`group_id` 仅作为兼容字段保留。
+创建群组。调用者自动成为 owner，无需额外 Ownership 绑定。支持创建命名群（传入 `group_name` + `public_key`）。owner 本地生成、持有群私钥，服务端只接收公钥；证书导入 owner 本地后按本节 owner 规则发布群名片。新建群主标识以 `group_aid` 为准；`group_id` 仅作为兼容字段保留。
 
 四种 SDK 的高层建群接口均支持崩溃恢复。命名群在 RPC 前持久化群密钥，并按 `group_name + public_key` 重放已提交结果；匿名群在 RPC 前持久化群密钥和创建上下文，重试会取回同一数字群并继续 `group_aid` 证书绑定与 `agent.md` 上传。群记录、群主成员、成员索引、入群设置、首个 `group.changed` 事件及匿名创建映射由服务端在同一数据库事务提交；证书服务和存储服务不参与该数据库事务，由 SDK pending 状态和服务端幂等重放恢复。
 
@@ -183,7 +195,7 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 | `curve` | string | 否 | 密钥曲线，默认 `"P-256"` |
 | `visibility` | string | 否 | `"public"` / `"private"`，默认由配置决定 |
 | `description` | string | 否 | 群组描述 |
-| `metadata` | object | 否 | 自定义元数据 |
+| `metadata` | object | 否 | 自定义元数据；创建时剥离服务托管的 pending_owner_transfer/transfer_history |
 | `avatar_ref` | string | 否 | 头像存储引用 |
 | `join_mode` | string | 否 | `"open"` / `"approval"` / `"invite_only"` / `"closed"`，回退到 visibility 映射 |
 | `join_question` | string | 否 | 入群问题 |
@@ -227,7 +239,7 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 
 ### group.bind_aid
 
-为已有普通群绑定命名 AID（升级为命名群）。仅群主可操作。
+为已有普通群绑定命名 AID（升级为命名群）。仅群主可操作。这是群身份生命周期操作，不建立 Ownership 2.1 关系；绑定后身份材料由当前 owner 持有。
 
 **参数**：
 
@@ -290,7 +302,7 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 | `name` | string | 否 | 新名称 |
 | `visibility` | string | 否 | 新可见性 |
 | `description` | string | 否 | 新描述 |
-| `metadata` | object | 否 | 新元数据 |
+| `metadata` | object | 否 | 新元数据；不得注入、删除或替换服务托管的 pending_owner_transfer/transfer_history |
 | `avatar_ref` | string | 否 | 新头像存储引用 |
 
 ### group.list_my
@@ -389,7 +401,7 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 
 ### group.dissolve
 
-永久解散群组。不可恢复。需要 **owner** 权限。
+永久解散群组。不可恢复。需要 **owner** 权限。解散自动解除有效 owner 关系、终止待转移，并撤销群证书及群授权；旧实体材料、群 token 和 pending 不能继续鉴权或上传群名片。历史 owner 与原始签名仅用于审计。服务先原子提交解散墓碑并清除转移待办，再通过持久 outbox 完成事件发布、CA 撤销、Storage 权限失效及缓存清理；任一收尾未完成，RPC 返回 -32002，data 为 status=unavailable、retryable=true、committed=true。墓碑已生效，重试续跑原收尾，不提前返回成功。
 
 **参数**：`group_id`（string，必填；兼容字段，值使用目标态 `group_aid`）
 
@@ -577,7 +589,7 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 
 ### group.complete_transfer
 
-由 pending 中的新群主完成群身份换钥和所有权切换。成功后响应状态为 `transferred`，新群主成为 owner，原群主转为 admin。
+由 pending 中的新群主完成群身份换钥和所有权切换，必须使用新密钥，禁止同密钥续证代替 rekey。成功后响应状态为 `transferred`，新群主成为 owner，原群主转为 admin；旧群证书失效，新群私钥及证书由新 owner 本地持有。
 
 **参数**：
 
@@ -603,11 +615,11 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 }
 ```
 
-高层 SDK 会生成并暂存新群身份密钥，签名 `transfer_accept`，成功后导入新的 group_aid 身份；重复提交同一已完成转让时，服务端可幂等返回已完成结果。
+高层 SDK 会生成并暂存新群身份密钥，签名 `transfer_accept`，成功后导入新的 group_aid 身份，并由新 owner 本人重新签署、上传含新 owner 的群名片；名片失败保留新代际原字节和原 CAS 条件，不反向撤销 owner 切换。重复提交同一已完成转让时，服务端可幂等返回已完成结果；旧 owner 的 pending 不得改用新代际自动续传。服务持久保留已验证旧证书用于 CA 轮换后复核原授权，以 transfer nonce 和旧 serial CAS 防止旧请求提交新任务；CA 已提交且可恢复的原待办即使超过 TTL 仍可收敛，尚未提交 CA 的过期待办拒绝。
 
 ### group.bind_group_aid
 
-为匿名群绑定群身份（group_aid）。需要 owner 权限。
+为匿名群绑定群身份（group_aid）。需要 owner 权限。这不是 Ownership 绑定；成功后当前 owner 持有群身份材料，并以本人身份代签代上传群名片。
 
 **幂等保证**：
 - 已绑定且公钥匹配：返回已绑定的 group_aid 和证书
@@ -647,7 +659,7 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 
 ### group.renew_group_aid
 
-轮换群身份密钥。需要 owner 权限，且必须持有旧 group_aid 私钥。
+轮换群身份密钥。需要 owner 权限，且必须持有旧 group_aid 私钥。这是当前 owner 的主动换钥，不替代 `transfer_owner/complete_transfer`。成功后旧群证书失效，owner 持有新材料并以本人身份重新代签代上传群名片。
 
 **用途**：
 - 群主密钥泄露后的安全轮换
@@ -1471,7 +1483,7 @@ SDK 只保证单个实时拉取响应页内按 seq 升序、同 seq 最多发布
 
 ### group.ack
 
-提交群消息已读游标。等同于 `group.ack_messages`，需要 `device_id`。
+提交群消息投递消费游标。等同于 `group.ack_messages`，需要 `device_id`；业务已读独立使用 `group.read/read_state`。
 
 **参数**：
 
@@ -1868,7 +1880,27 @@ SDK Group FS 门面使用票据执行 HTTP GET 并校验 sha256。应用自行
 
 ---
 
-## 事件
+## group.read
+
+请求为 `{"states":[{"group_id":"team.agentid.pub","topic_key":"topic-1","last_read_message_id":"gm-100"}]}`。`scope` 缺省或为空时按 `group` 处理，非空值只能为 `group`。AID 与 device ID 使用认证连接；历史 Group ID 别名先解析为 canonical ID，新写状态键、响应和事件使用 canonical `group_id`；历史别名同时参与事实、公共位置和设备映射的事务查询。Group 复用现有群成员及封禁检查，通过既有 `RequireSendGroup` 与版本同步刷新跨实例权限。批量至少一项，仅更新出现的键；只有省略 `states` 时才兼容顶层单条，显式空数组、null 或非数组值拒绝；字符串字段显式传入非字符串或 `null` 时拒绝。同域批量先校验该域全部项；混合域按所属域首次出现的顺序逐域校验和提交，任何域失败则 RPC 返回错误，已经提交的域不回滚，通过幂等重试收敛。owner/device/group/topic/message ID 各最多 128 字符，topic 原样保存。
+
+响应为 `{"updated":1,"ignored":0,"states":[{"scope":"group","group_id":"team.agentid.pub","topic_key":"topic-1","last_read_message_id":"gm-100","changed":true}]}`。这是设备写入回执，不是共享汇总；`changed=true` 不保证汇总前进。按群公共顺序单调更新，重复或旧位置返回 `changed=false`。每个 RPC 只等待本次依赖的写入提交；跨多个数据库批次时，失败不回滚先前提交，原样幂等重试可收敛。`group.read` 与投递 `group.ack_messages/ack_events` 独立。
+
+## group.read_state
+
+可选字段为 `scope`、`group_id`、`topic_key` 和当前认证 `aid`。`scope` 缺省或为空时按 `group` 处理，非空值只能为 `group`；`aid` 非空值只能等于认证 AID。显式非字符串或 `null` 拒绝。查询返回有权限的群状态；提供 group ID 时先解析为 canonical ID 并校验成员权限。未提供 group ID 时通过完整成员目录发现远域群并逐群合并，保留 topic 过滤，不受默认群列表分页限制。响应始终有 `states`，只有一项时顶层镜像该项。每项包含 `scope=group`、`group_id`、`topic_key`、`last_read_message_id`、`last_read_order`、`current_device_seq`、`mapping_status` 和毫秒 `updated_at`。
+
+`last_read_order` 为群公共消息顺序，用于缓存乱序保护。`current_device_seq` 只映射当前设备，无法映射返回 `null`。`resolved` 表示映射成功；`not_received` 表示公共位置已知但当前设备无投递记录；`unresolved` 表示公共位置无法解析。未知位置首次上报保存待解析事实，不广播汇总前进；未知不能覆盖已知，不以消息 ID 字典序猜测两个未知位置；晚到公共位置对仍匹配该消息且 order=0 的事实条件持久回填，不能只更新缓存或覆盖并发前进的事实。
+
+网络 JSON 的公共顺序和 seq 为整数，Gateway 本域服务及 federation 回程必须无损保留；TS/JS 的 `last_read_order`、非空 `current_device_seq` 在安全整数范围内是 number，超出时是精确十进制字符串。四端 facade 分别为 Python `group.read/read_state`、TS/JS `group.read/readState`、Go `Group().Read/ReadState`。四个已读门面保留显式 `None/null/nil` 字段供服务端拒绝，不改变其他门面的空值处理。写入回执不进入共享缓存，旧事件不交付应用，同位置事件保留设备映射；未知顺序不按时间或 ID 猜测前进。该接口只返回同一 AID 的设备汇总，不返回其它设备明细，也不保存 Group 事件流的已读状态。
+
+## group.read_changed
+
+数据库提交成功且 AID 汇总前进后，SDK 收到 `group.read_changed`。包含 `owner_aid`、`scope=group`、`group_id`、`topic_key`、`last_read_message_id`、`last_read_order` 和 `updated_at`。`owner_aid` 必须非空，SDK 要求其等于当前身份且 `scope=group` 匹配原事件。Gateway 即使收到显式 route 也只向该 AID 分发，校验 Kernel 转发的可信 Group 来源；群所属域可通过 federation 发送给该外域成员 AID，不能广播给其他群成员，来源绑定 canonical 群 ID 的 issuer。事件 ID 对 JSON 数组 `[owner_aid, group_id, topic_key, last_read_message_id]` 计算 SHA-256，不包含 `last_read_order`，失败日志不泄露 topic。事件不进入 Pull 队列，缺失依靠 `group.read_state` 补偿。
+
+SDK 保留成功查询的原过滤范围，包括空结果、全量及按群查询。连接成功后补偿并在 SDK 本地发布 `read_state_sync`，含 `owner_aid`、去重 `states` 及 `{method, params, error}` 错误项；消息 `background_sync=false` 不关闭该补偿。AID/device 切换清理缓存及登记项；旧身份在途结果按身份代际隔离，A→B→A 也不写当前缓存或补偿完成事件，原 RPC 调用仍可返回结果。应用应在 connect 前订阅，完成事件的状态与映射处理见 [跨设备已读未读 SDK 集成指南](../跨设备已读未读SDK集成指南.md)。
+
+## 事件
 
 ### event/group.created
 

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

@@ -24,7 +24,9 @@ P2P `message.*` 的最终投递语义由连接阶段声明的 `delivery_mode`
 | [message.thought.get](#messagethoughtget) | 读取某个 P2P 上下文的思考内容 |
 | [message.pull](#messagepull) | 增量拉取消息 |
 | [message.history](#messagehistory) | 向前只读翻页历史消息 |
-| [message.ack](#messageack) | 确认送达 |
+| [message.ack](#messageack) | 确认送达 |
+| [message.read](#messageread) | 上报当前设备的话题业务已读位置 |
+| [message.read_state](#messageread_state) | 查询当前 AID 的跨设备已读汇总 |
 | [message.recall](#messagerecall) | 撤回消息 |
 | [message.query_online](#messagequery_online) | 批量查询在线状态 |
 
@@ -46,11 +48,47 @@ P2P `message.*` 的最终投递语义由连接阶段声明的 `delivery_mode`
 |------|------|
 | [event/message.received](#eventmessagereceived) | 收到新消息 |
 | [event/message.recalled](#eventmessagerecalled) | 消息被撤回 |
+| [message.read_changed](#messageread_changed) | 同一 AID 的共享已读位置前进 |
+| `read_state_sync` | SDK 本地已读补偿完成，交付本轮 states/errors |
 | [delivery.changed](#deliverychanged) | SDK 本地批量交付完成通知，用于合并 UI 刷新 |
 
 ---
 
-## message.send
+## message.read
+
+请求为 `{"states":[{"scope":"p2p","topic_key":"topic-1","last_read_message_id":"m-100"}]}`。`states` 至少一项；省略时也兼容顶层单条，显式空数组、null 或非数组值拒绝；只更新出现的键。AID 与 device ID 从认证连接取得，不能指定其它设备。`scope` 缺省或为空时按 `p2p` 处理，非空值只能为 `p2p`；显式非字符串值拒绝。topic 原样保存，首尾空格、大小写和 Unicode 不折叠；topic、消息 ID、认证 AID 与 device ID 各最多 128 字符。
+
+响应为 `{"updated":1,"ignored":0,"states":[{"scope":"p2p","topic_key":"topic-1","last_read_message_id":"m-100","changed":true}]}`。这些是逐项设备写入回执，不能当作共享汇总；`changed=true` 不保证共享位置前进。重复或更旧位置返回 `changed=false`，不回退状态。批量参数校验失败不提交其中任何一项。每个 RPC 只等待本次依赖的写入提交；跨多个数据库批次时，后续失败不回滚先前提交，原样幂等重试可收敛。
+
+定向到 `device_id` / `to_device_id` 的消息形成独立设备事实，不进入 AID 共享汇总，也不广播共享已读变更。该业务 API 不推进投递 ACK。
+
+P2P 已读状态只由当前身份的 home 域管理。Gateway 从认证连接绑定主体，禁止调用方伪造 `_auth.aid`；`message.read` 与 `message.read_state` 的 federation 入站和出站均拒绝。该边界不改变受来源域约束的已读事件转发。
+
+## message.read_state
+
+查询字段均可选：`scope`（缺省或为空时按 `p2p`，非空值只能为 `p2p`）、`topic_key`、`aid`（非空值只能等于认证 AID）。显式非字符串或 `null` 拒绝。省略过滤条件查询当前 AID 的全部共享状态；无状态返回 `states=[]`。响应始终有 `states`；只有一项时顶层镜像该项字段。
+
+| 状态字段 | 含义 |
+| --- | --- |
+| `scope` / `topic_key` / `last_read_message_id` | 当前话题在全部设备中位置最新的共享业务已读消息 |
+| `last_read_order` | 公共消息顺序提示；用于 SDK 乱序保护，不是设备 seq |
+| `current_device_seq` | 该消息在当前认证设备 inbox 的本地 seq，无法映射为 `null` |
+| `mapping_status` | `resolved`：映射成功；`not_received`：公共位置已知，当前设备无投递映射；`unresolved`：公共消息位置无法解析 |
+| `updated_at` | 服务端更新时间，毫秒 |
+
+未知消息首次上报保存待解析状态、查询为 `unresolved`，不广播汇总前进；晚到公共位置仅对仍匹配该消息且 order=0 的事实条件持久回填，不能只更新缓存或覆盖并发前进的事实；未知位置不能覆盖已知位置。历史清理后使用持久 `last_read_order` 防止比较回退。接口只返回共享汇总，不返回其它设备 ID、seq 或定向设备事实。当前设备投递索引缺失时回查公共索引，GC 后热/冷进程均返回一致映射状态。
+
+网络 JSON 的公共顺序和 seq 是整数，Gateway 本域服务及 federation 回程必须无损保留；TS/JS 的 `last_read_order`、非空 `current_device_seq` 在安全整数范围内是 number，超出时是精确十进制字符串。`null` 映射保持不变。
+
+## message.read_changed
+
+SDK 订阅名为 `message.read_changed`。事件包含 `owner_aid`、`scope=p2p`、`topic_key`、`last_read_message_id`、`last_read_order` 和 `updated_at`，只在数据库提交成功且共享位置前进后发出。`owner_aid` 必须非空。Gateway 即使收到显式 route 也只向该 AID 分发，并校验 Kernel 转发的可信服务来源；federation 将 `owner_aid` 绑定来源域。SDK 要求 `scope=p2p` 匹配原事件，忽略缺失 owner 或其它 AID 的状态；事件 ID 对 JSON 数组 `[owner_aid, topic_key, last_read_message_id]` 计算 SHA-256，不包含 `last_read_order`，失败日志不泄露 topic。事件没有统一设备 seq，不进入 Pull 队列，丢失通过重连后 `read_state` 查询补偿。
+
+四端 facade 分别为 Python `message.read/read_state`、TS/JS `message.read/readState`、Go `Message().Read/ReadState`。四个已读门面保留显式 `None/null/nil` 字段供服务端拒绝，不改变其他门面的空值处理。仅查询和有效事件更新共享缓存；旧事件不交付应用，同位置事件保留设备映射并避免重复交付，新位置不继承旧映射。未知顺序不按时间或 ID 猜测前进；已知同序 ID 按 Unicode 码点/BINARY 顺序比较。
+
+SDK 登记成功查询的原过滤范围，空查询也登记；连接成功后补偿并在本地发布 `read_state_sync`，含 `owner_aid`、去重 `states` 和 `{method, params, error}` 错误项。消息 `background_sync=false` 不关闭补偿，AID/device 切换清理旧缓存及过滤项；旧身份在途结果按身份代际隔离，A→B→A 也不写当前缓存或补偿完成事件，原 RPC 调用仍可返回结果。应用在 connect 前订阅，详见 [跨设备已读未读 SDK 集成指南](../跨设备已读未读SDK集成指南.md)。
+
+## message.send
 
 发送一条 P2P 消息。
 

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

@@ -12,12 +12,9 @@
 | [storage.delete_object](#storagedelete_object) | 删除对象 |
 | [storage.list_objects](#storagelist_objects) | 列举对象 |
 | [storage.list_prefixes](#storagelist_prefixes) | 列举子目录 |
-| [storage.get_quota](#storageget_quota) | 查询配额 |
-| [storage.get_limits](#storageget_limits) | 查询上传限制 |
-| [storage.check_upload](#storagecheck_upload) | 上传预检（秒传检测 + 超限检测） |
-| [storage.relation_backup_provision](#storagerelation_backup_provision) | Auth 内部创建关系备份命名空间 |
-| [storage.relation_backup_revoke](#storagerelation_backup_revoke) | Auth 内部撤销关系 ACL、保留数据 |
-| [storage.relation_backup_status](#storagerelation_backup_status) | 查询关系备份命名空间状态 |
+| [storage.get_quota](#storageget_quota) | 查询配额 |
+| [storage.get_limits](#storageget_limits) | 查询上传限制 |
+| [storage.check_upload](#storagecheck_upload) | 上传预检（秒传检测 + 超限检测） |
 
 ### 目录树方法
 
@@ -121,31 +118,23 @@
 
 > `object_key` 当前仅支持 ASCII 安全字符集合 `[A-Za-z0-9._/-]`，且不允许空路径段、`..`、反斜杠转义后的非法段。
 
-## 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。
-
-四个 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 后未遵守该约束属于调用方式错误。
-
-## 关系备份命名空间（`relation_backup_*`）
-
-这三个 RPC 是 owner relation 与 Storage 的内部接口。`relation_backup_provision` 和 `relation_backup_revoke` 只接受 Auth 服务调用（`_caller_id="auth"`）；应用不应直接调用。`relation_backup_status` 允许当前 owner 或 subject 查询元数据。
-
-### storage.relation_backup_provision
-
-参数：`owner_aid`、`subject_aid`、`proof_id`、`relation_version`（均必填，external owner 与 subject 必须不同）。服务端在 owner 的 `default` bucket 创建或复用 `.aun/subjects/<lowercase_subject_aid>`，给 subject 授予 `rw` ACL。
-
-响应字段：`schema`、`owner_aid`、`subject_aid`、`proof_id`、`relation_version`、`bucket`、`path`、`acl_source`（固定 `ownership_relation`）、`acl_generation`、`status`（`ready`）、`on_revoke`（`retain_data_revoke_acl`）、`data_retained`。首次 generation 为 1；同一 proof/version 重复调用幂等。
-
-### storage.relation_backup_revoke
-
-参数：`owner_aid`、`subject_aid`，可选 `expected_relation_version`。只撤销 subject 的关系 ACL，保留目录和数据；成功返回 `status=retained`、`data_retained=true`，`acl_generation` 递增。记录不存在返回 `-32008`，非 Auth 调用返回 `-32004`。
-
-### storage.relation_backup_status
-
-参数：`subject_aid` 必填，`owner_aid` 可选；调用者必须是 owner 或 subject。响应与 provision 相同，未创建记录返回 `status=pending`、`acl_generation=0`、`data_retained=false`。`path` 的 RPC 返回值为 `.aun/subjects/<lowercase_subject_aid>`（SDK VFS 可用带前导 `/` 的等价路径）。subject 只能访问自己的 ready 关系目录的后代；不能列举 `.aun/subjects/` 根或其它 subject，不能删除 subject 根，也不能修改 ACL、visibility、token、share、mount。
+## 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。
+
+四个 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 后未遵守该约束属于调用方式错误。
+
+## 权威读取与条件发布
+
+`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`。
+
+路径 `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 新鲜事实为准。
 
 ## storage.put_object
 
@@ -163,6 +152,7 @@ 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 | 否 | 自定义元数据 |
 
@@ -201,6 +191,8 @@ result = await client.call("storage.put_object", {
 
 读取小对象，返回 base64 编码内容。
 
+可传 `consistency: authoritative`，结果及故障分类见 [权威读取与条件发布](#权威读取与条件发布)；权威读取只接受完整对象。
+
 ### 参数
 
 | 参数 | 类型 | 必填 | 说明 |
@@ -208,6 +200,8 @@ result = await client.call("storage.put_object", {
 | `object_key` | string | 是 | 对象路径 |
 | `bucket` | string | 否 | 存储桶，默认 `"default"` |
 | `owner_aid` | string | 否 | 所有者 AID，默认当前用户 |
+| `consistency` | string | 否 | 传 `authoritative` 时绕过缓存并返回完整权威对象 |
+| `expected_revision` | string | 否 | 权威路径修订；条件读取时必须与先前权威读取一致 |
 
 ### 响应
 
@@ -240,6 +234,8 @@ content = base64.b64decode(result["content"])
 
 查询对象元数据，不返回内容。
 
+可传 `consistency: authoritative`，返回 `exists/revision/observed_at` 等权威字段，明确不存在仍保留路径修订；完整契约见 [权威读取与条件发布](#权威读取与条件发布)。
+
 ### 参数
 
 | 参数 | 类型 | 必填 | 说明 |
@@ -247,6 +243,8 @@ content = base64.b64decode(result["content"])
 | `object_key` | string | 是 | 对象路径 |
 | `bucket` | string | 否 | 存储桶，默认 `"default"` |
 | `owner_aid` | string | 否 | 所有者 AID，默认当前用户 |
+| `consistency` | string | 否 | 传 `authoritative` 时绕过缓存并返回权威对象元数据 |
+| `expected_revision` | string | 否 | 权威条件读取使用的原路径修订 |
 
 ### 响应
 
@@ -271,6 +269,8 @@ content = base64.b64decode(result["content"])
 
 删除对象。
 
+可传原 `expected_revision` 作条件删除，结果附新路径 `revision`；修订冲突不得改用刚读到的新版继续删除。
+
 ### 参数
 
 | 参数 | 类型 | 必填 | 说明 |
@@ -278,6 +278,7 @@ content = base64.b64decode(result["content"])
 | `object_key` | string | 是 | 对象路径 |
 | `bucket` | string | 否 | 存储桶，默认 `"default"` |
 | `owner_aid` | string | 否 | 所有者 AID，默认当前用户 |
+| `expected_revision` | string | 否 | 条件删除使用的原权威路径修订 |
 
 ### 响应
 
@@ -582,31 +583,32 @@ 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 |
-| `expire_at` | integer | URL 过期时间戳 |
-| `owner_aid` | string | 所有者 AID |
-| `bucket` | string | 存储桶 |
-| `object_key` | string | 对象路径 |
-| `name` | string | 对象名称 |
-| `path` | string | 对象路径 |
-| `path_url` | string | Storage path URL |
-| `url` / `download_url` | string | AID 风格对象 URL |
-| `logical_url` | string | Storage 直链 URL |
-| `content_type` | string | MIME 类型 |
-| `size_bytes` | integer | 声明的文件大小 |
-| `overwrite` | boolean | 是否覆盖已有对象 |
-
-客户端获得 `upload_url` 后，通过 HTTP PUT 上传文件数据。当前服务响应不包含 `blob_key`、`session_id` 或 `headers`；调用方不得依赖这些字段。
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `upload_url` | string | 上传用 presigned URL |
+| `expire_at` | integer | URL 过期时间戳 |
+| `owner_aid` | string | 所有者 AID |
+| `bucket` | string | 存储桶 |
+| `object_key` | string | 对象路径 |
+| `name` | string | 对象名称 |
+| `path` | string | 对象路径 |
+| `path_url` | string | Storage path URL |
+| `url` / `download_url` | string | AID 风格对象 URL |
+| `logical_url` | string | Storage 直链 URL |
+| `content_type` | string | MIME 类型 |
+| `size_bytes` | integer | 声明的文件大小 |
+| `overwrite` | boolean | 是否覆盖已有对象 |
+
+客户端获得 `upload_url` 后，通过 HTTP PUT 上传文件数据。普通 session 不返回 `blob_key`、`session_id` 或 `headers`；传入 `expected_revision` 的条件 session 另返回 `session_id` 和固定 `expected_revision`，complete 必须沿用该 session 和原条件。
 
 > 当前实现会对 BlobStore 返回的 loopback URL 做对外地址规范化：优先使用 `KITE_STORAGE_EXTERNAL_URL`，否则按 `storage.{issuer}` 形式改写。对外地址不可使用 `127.0.0.1` 或 `localhost`。
 
-> 当前实现会在 `create_upload_session` 阶段按声明的 `size_bytes` 校验最大文件限制；实际 blob 大小、SHA-256 和配额在 `storage.complete_upload` 阶段校验。
+> 当前实现会在 `create_upload_session` 阶段按声明的 `size_bytes` 校验最大文件限制；实际 blob 大小、SHA-256 和配额在 `storage.complete_upload` 阶段校验。
 
 ---
 
@@ -627,6 +629,8 @@ for obj in result["items"]:
 | `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 |
 | `expire_in_seconds` | integer | 否 | 过期时间（秒） |
 | `metadata` | object | 否 | 自定义元数据 |
 
@@ -677,20 +681,20 @@ for obj in result["items"]:
 | `version` | integer | 版本号 |
 | `etag` | string | 实体标签 |
 
-`url` 是推荐使用的干净链接。访问时 storage 服务实时鉴权：public 文件直接通过，private 文件需 `?t=` token 或 `Authorization: Bearer <AID JWT>` 头证明 owner 身份。鉴权通过后 storage 302 到 blob 后端完成实际下载，这一步对客户端完全透明。
-
-### 数据面 HTTP 下载流程
-
-1. 通过控制面 RPC `storage.create_download_ticket` 获取短 TTL 的下载票据，不把长期对象 URL 当作最终下载地址。
-2. 优先使用返回的 `url` / `download_url`，完整保留查询参数。URL 已包含 `?t=` 时，该值就是资源域签发的能力凭据，按原样请求即可，不要替换为 AID access token。
-3. 只有目标端点明确要求 `Authorization: Bearer <AID JWT>` 时，才在发起请求前读取当前 token：Python 使用 `get_access_token()`，TypeScript / JavaScript 使用 `getAccessToken()`，Go 使用 `GetAccessToken()`。不得长期保存 `authenticate()` 首次返回的 token，也不得跨多次请求缓存 getter 的返回值。
-4. getter 只读后台刷新任务维护的缓存，不主动刷新。返回空值时先完成身份加载和认证/连接，不发送空 Bearer。跨 issuer 下载必须使用资源所在域签发的 `?t=` 票据，不能把调用方所在域的 AID JWT 发给远端 storage。
-5. Bearer 请求收到 401/403 时，重新读取一次 getter；仅当 token 已变化时最多重试一次。token 未变化时保留真实鉴权/授权错误，不得无限重试。票据过期则重新调用 `create_download_ticket`，不能靠刷新 AID token 延长票据。
-6. 跟随 302 时不得把 AID Bearer 转发到不同 origin 的 blob backend；下载完成后校验 `size_bytes` / `sha256`。
-
-SDK Storage VFS 会编排 ticket、HTTP GET 和完整性校验。应用只有在绕过 VFS、自行执行 HTTP 请求时，才需要直接处理上述凭据生命周期。
-
----
+`url` 是推荐使用的干净链接。访问时 storage 服务实时鉴权：public 文件直接通过，private 文件需 `?t=` token 或 `Authorization: Bearer <AID JWT>` 头证明 owner 身份。鉴权通过后 storage 302 到 blob 后端完成实际下载，这一步对客户端完全透明。
+
+### 数据面 HTTP 下载流程
+
+1. 通过控制面 RPC `storage.create_download_ticket` 获取短 TTL 的下载票据，不把长期对象 URL 当作最终下载地址。
+2. 优先使用返回的 `url` / `download_url`，完整保留查询参数。URL 已包含 `?t=` 时，该值就是资源域签发的能力凭据，按原样请求即可，不要替换为 AID access token。
+3. 只有目标端点明确要求 `Authorization: Bearer <AID JWT>` 时，才在发起请求前读取当前 token：Python 使用 `get_access_token()`，TypeScript / JavaScript 使用 `getAccessToken()`，Go 使用 `GetAccessToken()`。不得长期保存 `authenticate()` 首次返回的 token，也不得跨多次请求缓存 getter 的返回值。
+4. getter 只读后台刷新任务维护的缓存，不主动刷新。返回空值时先完成身份加载和认证/连接，不发送空 Bearer。跨 issuer 下载必须使用资源所在域签发的 `?t=` 票据，不能把调用方所在域的 AID JWT 发给远端 storage。
+5. Bearer 请求收到 401/403 时，重新读取一次 getter；仅当 token 已变化时最多重试一次。token 未变化时保留真实鉴权/授权错误，不得无限重试。票据过期则重新调用 `create_download_ticket`，不能靠刷新 AID token 延长票据。
+6. 跟随 302 时不得把 AID Bearer 转发到不同 origin 的 blob backend；下载完成后校验 `size_bytes` / `sha256`。
+
+SDK Storage VFS 会编排 ticket、HTTP GET 和完整性校验。应用只有在绕过 VFS、自行执行 HTTP 请求时，才需要直接处理上述凭据生命周期。
+
+---
 
 ## 事件
 
@@ -1010,6 +1014,8 @@ share_url = result["url"]  # https://alice.agentid.pub/s/Ab3xK9mZ2q
 
 查节点元数据（POSIX `stat`）。`follow_final=true`，解析末级软链 target。
 
+可传 `consistency: authoritative`；此模式使用 [权威对象结果](#权威读取与条件发布)，不是普通 fs 节点视图。
+
 ### 参数
 
 | 参数 | 类型 | 必填 | 默认 | 说明 |
@@ -1018,6 +1024,7 @@ share_url = result["url"]  # https://alice.agentid.pub/s/Ab3xK9mZ2q
 | `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
 | `bucket` | string | 否 | `"default"` | 存储桶 |
 | `token` | string | 否 | — | 访问 token |
+| `consistency` | string | 否 | — | 传 `authoritative` 时返回权威对象结果 |
 
 ### 响应
 
@@ -1092,6 +1099,8 @@ fs 目录节点视图。
 
 删除文件/目录/软链（POSIX `rm`，目录用 `recursive`）。**拒绝删除挂载点**（须先 unmount）。
 
+可传原 `expected_revision` 作条件删除，Ownership 旧文件清理须携带该值；冲突时停止，不刷新修订继续删除。
+
 ### 参数
 
 | 参数 | 类型 | 必填 | 默认 | 说明 |
@@ -1100,6 +1109,7 @@ fs 目录节点视图。
 | `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
 | `bucket` | string | 否 | `"default"` | 存储桶 |
 | `recursive` | boolean | 否 | `false` | 递归删除目录 |
+| `expected_revision` | string | 否 | — | 条件删除使用的原权威路径修订 |
 
 ### 响应
 
@@ -1243,7 +1253,7 @@ fs 目录节点视图。
 
 | 参数 | 类型 | 必填 | 默认 | 说明 |
 |------|------|------|------|------|
-| `group_id` | string | 是 | — | 群组标识兼容字段，值语义为目标态 `group_aid` |
+| `group_id` | string | 是 | — | 群组标识兼容字段，值语义为目标态 `group_aid` |
 | `group_owner_aid` | string | 是 | — | 群 owner AID |
 | `member_aid` | string | 否 | — | 成员 AID（不传=全员） |
 | `reason` | string | 否 | `"membership_changed"` | `dissolved` / `membership_changed` |

package/_packed_docs/sdk/AUN_DOCS_GUIDE.md

@@ -12,9 +12,10 @@ 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、签名和上传前校验见 `../agent.md/SCHEMA.md` 与 `04-连接与认证.md`。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。
+业务 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。
 
 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`。
 
 ## 渐进式查阅流程
@@ -27,13 +28,15 @@ Group 的成员 block/status、暂停群权限和两阶段群主转让，以及
 
 常见主题：
 
-- 身份与认证：AIDStore / AID / 注册 / 加载 / 证书
+- 身份与认证：AIDStore / AID / 注册 / 加载 / 证书
+- Ownership 2.1：当前应用/移植指南、七 Facade、双文件/锁/版本；Group/Org 专属生命周期、owner 本人名片、原 V2 授权复用、过期明确上传、无消息释放清理与 not_applicable 门禁；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、坏密文推进
 - 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`）
@@ -54,9 +57,16 @@ Group 的成员 block/status、暂停群权限和两阶段群主转让，以及
 | 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 校验和自动观察 |
-| 05 | [E2EE加密通信](05-E2EE加密通信.md) | E2EE V2、ProtectedHeaders、agent.md 版本提示、recipient wrap |
-| 06 | [API手册](06-API手册.md) | AIDStore / Agent.md 校验签名 / AID / AUNClient 生命周期并发 / 四 SDK access token getter / 群组高层身份编排 / History 门面 / 消息来源与 Pull 同步生命周期 / 事件 / RPC |
+| 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 |
+| - | [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 |
 | 07 | [错误处理](07-错误处理.md) | Result、Python `ErrorInfo.cause`、异常、错误码、重试 |
 | 08 | [最佳实践](08-最佳实践.md) | 幂等、消息同步/History、AUNClient 级 Pull Gate（始终单飞）、测试数据 |
 | - | [Storage RPC 手册](09-storage-rpc-manual.md) | Storage RPC、实际字节 MIME、三阶段 Content-Type、OSS 403、HTTP 下载与凭据边界 |
@@ -73,6 +83,13 @@ Group 的成员 block/status、暂停群权限和两阶段群主转让，以及
 | 首次使用 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) |
 | 自行发起 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) |
@@ -80,7 +97,10 @@ Group 的成员 block/status、暂停群权限和两阶段群主转让，以及
 | 登记、更新或注销 `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) |
+| 查跨设备业务已读、单条/显式空值、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) |
 | 查 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) |