@agentunion/fastaun 0.5.29 → 0.5.31

package/CHANGELOG.md

@@ -6,6 +6,50 @@
 
 ---
 
+## 0.5.31 — 未发布
+
+### Group／Org Ownership
+
+- 现代 `group`／`org` 名片支持 Ownership 2.1 的 `agent.md`＋`owner.md` 共识查询与实体自身签名，保留旧实体名片的读取和签名兼容；单文件下载只确认文档，不能代替双文件共识。通用绑定／转移工作流仍不直接操作群／组织，生命周期操作继续使用对应服务。
+- 当前 owner 具备本地实体密钥或可恢复的群绑定材料时，每次连接后首次访问对应群／组织检查共识，必要时补齐现代声明并确认发布结果；创建、绑定及接收转让后的名片发布同样检查共识，不再在连接后遍历全部群补绑。
+- 转让／解散前写入 owner 的转让／释放声明；仅在明确业务拒绝、实体仍属原 owner 且声明未被改写时尝试恢复原件，网络超时等结果不确定的失败不恢复。RPC 与文件提交前检查身份和连接代际，阻止旧任务继续写入；相同上下文的并发组织创建合并执行。
+
+### 控制消息协议
+
+- 分类能力升级为 `message_classes_v2`：P2P 支持 `normal`／`control`／`sdk_control`，群仅支持 `normal`／`control`；本地拒绝群 `sdk_control` 请求并忽略该类群推送，避免进入应用交付或内部 P2P 控制处理。
+- 持久控制消息 ACK 不再携带 `scan_proof`，移除证明过期后的重扫续证；恢复旧待确认记录时剥离旧证明。继续校验拉取范围和覆盖水位，持久保存处理游标及待确认 ACK 后再确认，volatile 流继续使用自身游标。
+
+### Storage CAS
+
+- 对象写操作及文件重命名未指定 `expected_version` 时，先读取当前版本并随请求发送；对象不存在时使用 `0`。显式版本仍先比对，不一致时返回冲突，服务端原子 CAS 继续负责最终并发检查。
+- `force=true` 不再清除显式版本或跳过预检；未指定版本时重新取得当前版本，避免使用 VFS 的旧写版本缓存。
+
+### 版本与验证
+
+- 包配置、锁文件及运行时版本统一为 `0.5.31`；版本升级阶段 TypeScript 类型检查通过。本节按当前代码与既有回归用例核对，整理文档时未重跑测试；四端差异与验证范围见 [parity 文档](../python/CHANGES_FOR_PARITY.md)。
+
+## 0.5.30 — 未发布
+
+### 消息恢复与同步
+
+- 移除控制消息恢复的周期定时器；连接就绪时恢复一次，后续 push 按 peer／group、消息类别和持久／volatile 流触发恢复，不再周期扫描 `message.peers` 和 `group.list_my`。应用主动拉取保持原有行为。
+- 群恢复根据 `group.list_my` 返回的各流 `needs_pull` 状态选择拉取，跳过已追平的流；未返回 `streams` 时保留兼容恢复，继续恢复待确认 ACK。
+
+### Ownership 与 agent.md
+
+- 本地绑定和转移允许当前 owner、新 owner 为 `human` 或 `agent`，subaid 仍限 `agent`；继续要求不同身份及私钥，释放沿用 `releaseSubaid`。
+- 更新 Ownership frontmatter 时关闭 YAML 自动折行，使用 literal 多行字符串；保留其它字段的数据值，更新后继续执行文档校验。
+
+### Storage 与消息发送
+
+- Storage 对携带 `expected_version` 的对象写入和文件重命名先检查当前版本，不一致时返回冲突；未指定版本或显式 `force=true` 时跳过预检。预检不替代服务端原子 CAS。
+- 发送 `observer.forward` 时复制并剥离 `original` 中的 `_semantic_evidence`、`_agent_md`、`source`、`device_id`、`slot_id_full`、`proximity` 及三个 `same_*` 诊断字段；保留业务 payload，不修改原始接收对象。
+- `gateway.risk_status` 归为服务端专用 RPC，不允许应用通过 SDK 调用；保留签名风控 push 的接收与 ACK。
+
+### 版本
+
+- 包配置、锁文件、运行时及相关测试版本引用统一为 `0.5.30`。
+
 ## 0.5.29 — 未发布
 
 ### Ownership 共识查询

package/_packed_docs/CHANGELOG.md

@@ -6,6 +6,50 @@
 
 ---
 
+## 0.5.31 — 未发布
+
+### Group／Org Ownership
+
+- 现代 `group`／`org` 名片支持 Ownership 2.1 的 `agent.md`＋`owner.md` 共识查询与实体自身签名，保留旧实体名片的读取和签名兼容；单文件下载只确认文档，不能代替双文件共识。通用绑定／转移工作流仍不直接操作群／组织，生命周期操作继续使用对应服务。
+- 当前 owner 具备本地实体密钥或可恢复的群绑定材料时，每次连接后首次访问对应群／组织检查共识，必要时补齐现代声明并确认发布结果；创建、绑定及接收转让后的名片发布同样检查共识，不再在连接后遍历全部群补绑。
+- 转让／解散前写入 owner 的转让／释放声明；仅在明确业务拒绝、实体仍属原 owner 且声明未被改写时尝试恢复原件，网络超时等结果不确定的失败不恢复。RPC 与文件提交前检查身份和连接代际，阻止旧任务继续写入；相同上下文的并发组织创建合并执行。
+
+### 控制消息协议
+
+- 分类能力升级为 `message_classes_v2`：P2P 支持 `normal`／`control`／`sdk_control`，群仅支持 `normal`／`control`；本地拒绝群 `sdk_control` 请求并忽略该类群推送，避免进入应用交付或内部 P2P 控制处理。
+- 持久控制消息 ACK 不再携带 `scan_proof`，移除证明过期后的重扫续证；恢复旧待确认记录时剥离旧证明。继续校验拉取范围和覆盖水位，持久保存处理游标及待确认 ACK 后再确认，volatile 流继续使用自身游标。
+
+### Storage CAS
+
+- 对象写操作及文件重命名未指定 `expected_version` 时，先读取当前版本并随请求发送；对象不存在时使用 `0`。显式版本仍先比对，不一致时返回冲突，服务端原子 CAS 继续负责最终并发检查。
+- `force=true` 不再清除显式版本或跳过预检；未指定版本时重新取得当前版本，避免使用 VFS 的旧写版本缓存。
+
+### 版本与验证
+
+- 包配置、锁文件及运行时版本统一为 `0.5.31`；版本升级阶段 TypeScript 类型检查通过。本节按当前代码与既有回归用例核对，整理文档时未重跑测试；四端差异与验证范围见 [parity 文档](../python/CHANGES_FOR_PARITY.md)。
+
+## 0.5.30 — 未发布
+
+### 消息恢复与同步
+
+- 移除控制消息恢复的周期定时器；连接就绪时恢复一次，后续 push 按 peer／group、消息类别和持久／volatile 流触发恢复，不再周期扫描 `message.peers` 和 `group.list_my`。应用主动拉取保持原有行为。
+- 群恢复根据 `group.list_my` 返回的各流 `needs_pull` 状态选择拉取，跳过已追平的流；未返回 `streams` 时保留兼容恢复，继续恢复待确认 ACK。
+
+### Ownership 与 agent.md
+
+- 本地绑定和转移允许当前 owner、新 owner 为 `human` 或 `agent`，subaid 仍限 `agent`；继续要求不同身份及私钥，释放沿用 `releaseSubaid`。
+- 更新 Ownership frontmatter 时关闭 YAML 自动折行，使用 literal 多行字符串；保留其它字段的数据值，更新后继续执行文档校验。
+
+### Storage 与消息发送
+
+- Storage 对携带 `expected_version` 的对象写入和文件重命名先检查当前版本，不一致时返回冲突；未指定版本或显式 `force=true` 时跳过预检。预检不替代服务端原子 CAS。
+- 发送 `observer.forward` 时复制并剥离 `original` 中的 `_semantic_evidence`、`_agent_md`、`source`、`device_id`、`slot_id_full`、`proximity` 及三个 `same_*` 诊断字段；保留业务 payload，不修改原始接收对象。
+- `gateway.risk_status` 归为服务端专用 RPC，不允许应用通过 SDK 调用；保留签名风控 push 的接收与 ACK。
+
+### 版本
+
+- 包配置、锁文件、运行时及相关测试版本引用统一为 `0.5.30`。
+
 ## 0.5.29 — 未发布
 
 ### Ownership 共识查询

package/_packed_docs/INDEX.md

@@ -14,7 +14,7 @@
 | [0.5.22 SDK 开发与移植指南](sdk/0.5.22-SDK开发与移植指南.md) | 后台退避、群状态、两种绑定与 Stage/CAS、消息内部消费、撤销同步、组织恢复及配套服务修复、默认读缓存、Rust 移植与验收 |
 | [0.5.24 SDK 应用集成指南](sdk/0.5.24-SDK应用集成指南.md) | 当前身份与消息接入、无持久任务 Ownership、双／三身份 local 编排、展示与文件缓存、凭证组织及升级验收 |
 | [0.5.24 SDK 开发与移植指南](sdk/0.5.24-SDK开发与移植指南.md) | 当前 peer／batch 提交、NS 事实与远端 CAS、local 短连接、观察与 PKI 缓存、持久化边界、语言差异及移植验收 |
-| [aun测试运行指南](aun测试运行指南.md) | `agentid.pub/agentid.cn` 双域本地单实例、MySQL 命名卷/bind 核验、独立固定材料与 Tester、Go 1.24、断网 cross-SDK、缓存专项首失败续跑、三文件线上镜像替换包、开箱默认配置、一次性初始化辅助包及单节点部署 |
+| [aun测试运行指南](aun测试运行指南.md) | 本机源码为真源的远程 Ubuntu Docker 同步与 SHA 校验；`agentid.pub/agentid.cn` 双域本地单实例、MySQL 命名卷/bind 核验、独立固定材料与 Tester、Go 1.24、断网 cross-SDK、缓存专项首失败续跑、三文件线上镜像替换包、开箱默认配置、一次性初始化辅助包及单节点部署 |
 | [aun公网测试运行指南](aun公网测试运行指南.md) | 可配置 issuer domain 的 Python SDK 公网 integration/E2E runner、独立身份/运行目录、TLS 与服务端公网验收衔接 |
 | [aun分布式测试运行指南](aun分布式测试运行指南.md) | 当前worktree三节点/双域、固定身份runner和Storage OSS；P0授权启动/TLS/单活放置、Tester新pycache与C2续跑；MinIO双healthy/原marker重建读回通过，旧87a09263镜像及AIO04/pool05续跑通过，双形态历史六项C2分轮累计及恢复后最终完整六项C2通过；五app正常停启持久恢复与NS材料匹配/错误0已有证；第二轮5project全15容器停用、10依赖/control/新desired/worker恢复及SQL-before-app/before-SDK一致及旧事实/继续写/post SQL已证，恢复后schema/身份材料/最终完整C2及readiness收敛已证；MinIO原marker及最终日志已通过；新e294两域升级/旧87a回滚/恢复、SQL退休、最终C2各6项、持久v3→v4读写/正ACK及MinIO/诊断通过；fresh10005两域V2/签名状态/SQL/清理及pool重复confirm闭环通过，旧日志不倒推且全窗非0；原Pool Org/Cred首FAIL及历史10004/10006证据缺口保留；57d4双形态回滚恢复/局部重启、独立SDK最终C2/持久v4→v5、03默认1DH路径/清理/严格对账与配置持久化已证，最终日志已分类并保留来源缺口，P0默认1DH有限范围本地技术验收通过，Git/线上待；本轮有限清单真实失败已修复，历史参数/来源缺口旁列；群七天保留/物理清理后续另验、当前未实施；P0 C7部署撤回/保留数据及peer ACK恢复门禁，未签收、P1—P9未开始 |
 | [分布式 AUN 节点与服务启动流程](../../extensions/services/docs/分布式AUN节点与服务启动流程.md) | control master / worker node、控制/注册/配置中心一体化、节点启动、服务启停、注册发现和配置恢复流程 |
@@ -25,6 +25,8 @@
 | [P2P 消息 TTL 内存缓存方案](design/P2P消息TTL内存缓存方案.md) | `message.send` 秒级 TTL 钳制、持久/volatile 双游标、按 device 收件箱、隐藏 slot lease/ACK、文件 epoch、消息调试计数器与 payload type 分类、多实例/跨域和四 SDK 测试矩阵 |
 | [控制消息与设备能力协商方案](控制消息与设备能力协商方案.md) | 待实施：三类消息、固定优先级、Gateway 设备能力权威与 TTL 回源缓存、独立 SEQ / cursor、旧 SDK 降级及 Owner 名片感知 |
 | [风控响应与 SDK 协同方案](风控响应与SDK协同方案.md) | 待实施：服务端强制限制、SDK 能力与柔性响应、旧端断连暂封、版本化恢复、控制台解封及验收 |
+| [陌生人拒绝协议详细设计](陌生人拒绝协议详细设计.md) | 实施中：Gateway 按提交计 pending、互通/拒绝状态、手动回填、默认 observe 与 Console 状态页；不做消息 ID 去重，初始上限 5 由管理员显式配置 |
+| [陌生人拒绝协议 TDD 分阶段实施计划](陌生人拒绝协议TDD分阶段实施计划.md) | 核心实现、真实单域/双域专项及浏览器验收记录见计划；Group 及旧 SDK 真实回归已通过，cross-SDK 专项 48 组合完成（实跑 45＋沿用 3，非全量 Group／SDK 套件）；观察期不测试、管理员到时手动切换属于运维后续 |
 | [跨设备已读未读方案](跨设备已读未读方案.md) | 同一 AID 多设备按话题同步已读位置；服务端按 message ID 公共顺序汇总，返回汇总 message ID 及当前设备 seq 映射，支持 P2P/Group、批量和部分会话上报 |
 | [跨设备已读未读详细设计](跨设备已读未读详细设计.md) | RPC、单条/显式空值边界、紧凑状态表、晚到位置持久回填、Group canonical 与权限版本、owner 事件路由及四端补偿 |
 | [跨设备已读未读实施计划](跨设备已读未读实施计划.md) | 按 TDD 分阶段落地服务端、状态缓存与异步批写、Gateway、四端 SDK、单域/E2E/cross-SDK/跨域测试及完成定义 |
@@ -105,7 +107,7 @@
 
 ### 测试与 E2E
 
-- 本机各套环境边界、MySQL 命名卷/bind 来源、默认单实例服务端、独立 SDK Tester、容器/网络/数据目录和测试命令 → [aun测试运行指南](aun测试运行指南.md)
+- 本机各套环境边界、MySQL 命名卷/bind 来源、默认单实例服务端、独立 SDK Tester、容器/网络/数据目录、远程 Ubuntu 源码同步与 SHA 校验、测试命令 → [aun测试运行指南](aun测试运行指南.md)
 - `evolagent.cn` / `agentid.pub` 等公网域的 Python SDK integration/E2E、隔离目录、TLS 和报告 → [aun公网测试运行指南](aun公网测试运行指南.md)
 - 双域 Issuer/AID/MySQL 材料校验、三文件线上镜像替换包、开箱默认值与可选生产覆盖、一次性初始化辅助包及线上单节点部署 → [aun测试运行指南](aun测试运行指南.md)
 - 当前worktree三节点/双域、固定身份runner、Storage OSS与来源核验；2.0 P0授权启动/运行失败断点、AIO端口、新pycache Tester/TLS与C2续跑、双形态/C1—C10及回滚/交付门禁；大文件仍外部OSS、小对象P0仍localfs，内部S3迁移属P2 → [aun分布式测试运行指南](aun分布式测试运行指南.md)
@@ -115,6 +117,7 @@
 - P2P/Group Message 的 A/T/H、Tail/History、页内唯一有序发布、应用层跨页幂等排序、三 Pull Gate、缺 sender IK 有界同步 bootstrap、永久页内 Gap、坏密文推进和分布式验收门禁 → [消息同步与历史拉取改造方案](消息同步与历史拉取改造方案.md)
 - P2P `message.send` TTL 内存缓存、持久/volatile 游标、device 收件箱、隐藏 slot lease/ACK、服务 epoch、消息调试计数器与 payload type 分类、跨 SDK/双域验收 → [P2P 消息 TTL 内存缓存方案](design/P2P消息TTL内存缓存方案.md)
 - 三类控制消息、设备能力持久化 / TTL 回源、SEQ / cursor 隔离、旧 SDK 投影及 agent.md Owner 感知 → [控制消息与设备能力协商方案](控制消息与设备能力协商方案.md)
+- Gateway 陌生人 P2P 限额、双向互通状态、拒绝/屏蔽、Inbox 手动回填和 Console AID 对状态查询 → [陌生人拒绝协议详细设计](陌生人拒绝协议详细设计.md)、[TDD 分阶段实施计划](陌生人拒绝协议TDD分阶段实施计划.md)
 - 同一 AID 多设备按会话话题同步已读位置、message ID 公共顺序汇总、当前设备 seq 映射、P2P/Group 批量上报与查询 → [跨设备已读未读方案](跨设备已读未读方案.md)
 - 跨设备已读未读 RPC、状态表、请求级提交、混合域部分提交、SDK 缓存及本地完成事件契约 → [跨设备已读未读详细设计](跨设备已读未读详细设计.md)
 - 跨设备已读未读 TDD 阶段、状态缓存与批写、测试矩阵、断点续跑、兼容审查和完成定义 → [跨设备已读未读实施计划](跨设备已读未读实施计划.md)
@@ -242,6 +245,12 @@
 
 [风控响应与 SDK 协同方案](风控响应与SDK协同方案.md) 优先定义待实施的响应闭环：服务端先限制，支持 `risk_test_v1` 的连接协同装闸与回执，未支持端触发风险后断连暂封。规定可信作用域、RPC/托管 HTTP、签名快照与时间/版本、唯一重连、持久处罚和递增规则；Console 展示证据与各入口执行状态，带权限/CAS 解封并防止迟到策略复活。包含四 SDK、跨实例、旧端和受控公网验收；不表示识别算法或机制已上线。
 
+### 陌生人拒绝协议详细设计与实施计划
+
+[详细设计](陌生人拒绝协议详细设计.md) 定义 Gateway P2P pending 额度、双向互通豁免、接收方拒绝/屏蔽、SDK RPC、Console 状态页及手动回填。Gateway 按提交次数计额度，不做消息 ID 去重；回填 pending 取当前值与历史计数的较大值。默认 observe；`pending_limit=5` 为管理员显式初始配置及本轮环境基线。实际观察期不执行测试，管理员到时检查未知关系与超限候选后手动启用 enforce。
+
+[TDD 分阶段实施计划](陌生人拒绝协议TDD分阶段实施计划.md) 记录 Gateway 状态仓储与入口判定、手动回填、跨域探测、四端 SDK 和 Console 的实施与定向验证；真实单域/双域专项及 Console 浏览器验收记录见计划；Group 及旧 SDK 真实回归已通过，cross-SDK 专项 48 组合完成（实跑 45＋沿用 3，非全量 Group／SDK 套件）。实际观察及管理员到时手动切换属于运维后续，不纳入本轮自动验收待办。
+
 ### 跨设备已读未读方案
 
 定义同一 AID 多设备的业务已读状态模型。P2P `seq` 按设备隔离，设备按应用传入的 `topic_key` 保存最后已读 `message_id`；服务端依据消息公共顺序汇总各设备状态，查询只返回汇总 message ID 及其在当前设备上的 seq 映射。方案覆盖 P2P/Group、AID/话题/Group 过滤查询、单条/批量/部分会话上报、在线变更事件、定向消息边界、四端 SDK 和前端未读数计算。

package/_packed_docs/KITE_DOCS_GUIDE.md

@@ -8,20 +8,20 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 
 ### Step 1：先读根级 Layer 1
 
-- `docs/INDEX.md` L7-103：根级文档地图。
+- `docs/INDEX.md` L7-105：根级文档地图。
 
 ### Step 2：按主题读根级 Layer 2
 
-- 测试与 E2E：`docs/INDEX.md` L106-127。
-- 服务端 Go 化重构审查：`docs/INDEX.md` L128-131。
-- SDK 使用与协议：`docs/INDEX.md` L132-184。
-- Service Proxy 与服务暴露：`docs/INDEX.md` L185-191。
-- 诊断与可观测性：`docs/INDEX.md` L192-200。
-- E2EE 与跨语言一致性：`docs/INDEX.md` L201-209。
+- 测试与 E2E：`docs/INDEX.md` L108-130。
+- 服务端 Go 化重构审查：`docs/INDEX.md` L131-134。
+- SDK 使用与协议：`docs/INDEX.md` L135-188。
+- Service Proxy 与服务暴露：`docs/INDEX.md` L189-195。
+- 诊断与可观测性：`docs/INDEX.md` L196-204。
+- E2EE 与跨语言一致性：`docs/INDEX.md` L205-213。
 
 ### Step 3：需要判断文档价值时读 Layer 3 摘要
 
-- `docs/INDEX.md` L210-502：重点文档摘要。
+- `docs/INDEX.md` L214-518：重点文档摘要。
 
 ### Step 4：再读目标文档章节
 
@@ -63,6 +63,7 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 | CLI credential 23命令、params/context/kind/domain、原字节及错误退出；组织材料衔接 | `docs/cli/CLI手册.md` L312-355；实现设计见`docs/cli/AUN-CLI设计文档.md` §7.9 |
 | Credential/Org CLI流程图与TS使用、SDK胶水开发 | `docs/cli/凭证与组织服务CLI开发与使用指南.md` 入口／23命令L5-121；凭证L122-591；组织L592-798；开发／错误／E2E L799-869 |
 | CN凭证／语义凭证独立运行及普通凭证四阶段冷恢复 | `docs/aun测试运行指南.md` L1243-1269 |
+| 远程 Ubuntu Docker 的连接参数、本机源码同步、镜像构建和 SHA 校验 | `docs/aun测试运行指南.md` L1271-1284 |
 | 语义凭证本地CN↔aid.com双权威12组专项 | `docs/aun分布式测试运行指南.md` L1453-1466 |
 | Org Service 实际生命周期/成员/凭证/审计 RPC、补偿冲突与换钥修复、内部接口及未实现占位 | `docs/sdk/09-组织服务RPC手册.md` L1-90 |
 | 本机 AUN 环境怎么选、如何核对 MySQL 命名卷/bind 与避免 Compose 混用 | `docs/aun测试运行指南.md` L9-100 |
@@ -84,6 +85,7 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 | P2P 消息 `ttl` 秒级钳制、volatile 双游标、device 收件箱、隐藏 slot lease/ACK、epoch 文件、消息调试计数器与 payload type 分类和四 SDK/双域测试方案 | `docs/design/P2P消息TTL内存缓存方案.md` L1-369 |
 | 三类消息优先级、Gateway 设备能力、TTL 缓存回源、独立 SEQ / cursor、旧 SDK 降级及 Owner 名片感知（待实施） | [控制消息方案](控制消息与设备能力协商方案.md)：规则 L5-65；能力与兼容 L66-169；流与调度 L170-279；Owner / 跨域 L280-325；改动与验收 L326-417 |
 | 服务端风控强制执行、SDK 能力/门控/回执、旧端断连暂封和控制台解封（待实施） | [风控响应方案](风控响应与SDK协同方案.md)：原则/能力 L5-99；策略/服务端响应 L100-200；SDK/递增处置 L201-252；持久状态/控制台 L253-309；场景/实施/验收 L310-381 |
+| Gateway 陌生人 P2P 限额、拒绝/屏蔽、手动回填和 Console 状态查询（实施中，按提交计数） | [详细设计](陌生人拒绝协议详细设计.md) L1-231；[TDD 分阶段计划](陌生人拒绝协议TDD分阶段实施计划.md) L1-138。默认 observe，`pending_limit=5` 为管理员显式初始配置及本轮环境基线；观察期不测试、管理员到时手动切换属于运维后续，不纳入自动验收待办；Group 及旧 SDK 真实回归已通过，cross-SDK 专项 48 组合完成（实跑 45＋沿用 3，非全量 Group／SDK 套件） |
 | 跨设备 P2P/Group 按话题同步已读位置、AID 汇总、设备 seq 映射及补偿完成交付 | `docs/跨设备已读未读方案.md` L1-273 |
 | 跨设备已读未读 RPC、紧凑状态表、公共顺序、请求级提交、混合域部分提交、四端 SDK 缓存和本地完成事件 | `docs/跨设备已读未读详细设计.md` L1-209 |
 | 跨设备已读未读 TDD 阶段、迁移/批写、断点续跑、测试矩阵、历史部署记录和本轮完成定义 | `docs/跨设备已读未读实施计划.md` L1-156 |

package/_packed_docs/aun/346/265/213/350/257/225/350/277/220/350/241/214/346/214/207/345/215/227.md

@@ -1141,7 +1141,7 @@ docker compose --env-file agentid.pub/local.env --project-directory . -f docker-
 
 ### SDK 或测试代码变更
 
-通常不需要操作服务端，因为 Tester 挂载 SDK 源码与测试目录。Go SDK 测试会在执行 `go test` 时重新编译；Python 测试直接读取挂载源码；TypeScript/JavaScript 直接读取各自 workspace。
+通常不需要操作服务端。Tester 在本机 Docker 中可直接读取 bind mount；远程 Ubuntu 不会自动同步本机工作区，必须先按文末“远程 Ubuntu Docker 的本机源码同步”同步本机改动，再运行测试。Go SDK 测试会在执行 `go test` 时重新编译；Python 测试直接读取挂载源码；TypeScript/JavaScript 直接读取各自 workspace。
 
 只有 Tester 自身发生这些变化时才处理 Tester：Python 测试镜像依赖变化需要在独立准备阶段 rebuild `sdk-tester`；TypeScript/JavaScript 的 `package.json` 或 lockfile 变化必须先在独立准备阶段更新 Linux 依赖 volume，再重新创建对应 Tester。回到业务测试阶段后只允许复用已验证的容器和依赖，不得让 entrypoint 临时安装。
 
@@ -1267,3 +1267,20 @@ docker logs --since 30m kite-app 2>&1 | Select-String -Pattern "WAL 批量写入
 每阶段 ARTIFACT_DIR 分别保存 results.json，四阶段共用同一 cold state；不省略停止／重启间隔直接循环四个 mode。相关操作只针对对应 SDK worker，不重启其他会话的服务或数据库。本轮四阶段通过证据见 [credential-cold-cn-20261029021605](../tests/cross-sdk/artifacts/semantic-cn-2f257acc/artifacts/credential-cold-cn-20261029021605/)。
 
 本轮 282 组语义＋4 组普通凭证配置、16 组组织关联、64 组主干、真实浏览器双 scope 恢复和时间／留存边界以[示例指南 §5](../examples/semantic-credential/示例使用指南.md#5-本轮验证记录与边界)为准。双域补充为本地 CN↔aid.com，见[分布式指南专项](aun分布式测试运行指南.md#语义凭证-cn-与-aidcom-专项)，不计作公网或 aid.net 验收。
+
+## 远程 Ubuntu Docker 的本机源码同步
+
+本节适用于默认单域、分布式、双域及 cross-SDK 使用远程 Ubuntu Docker 的情况。
+
+- Ubuntu SSH：`root@61.169.195.42`，端口 `30248`；Docker context 为 `kite-ubuntu`，远端项目目录为 `/data/kite`，Docker 数据目录为 `/data/docker`。
+- 本机 identity file：`C:\Users\ready\.ssh\id_rsa`；对应公钥 `C:\Users\ready\.ssh\id_rsa.pub` 已安装到 Ubuntu。只记录路径，不保存私钥内容，也不把私钥同步到远端。
+- Windows PowerShell 登录命令：`ssh -p 30248 -i "$env:USERPROFILE\.ssh\id_rsa" -o IdentitiesOnly=yes root@61.169.195.42`。
+- Ubuntu CN Compose 还需按顺序加载 `agentid.cn/local.env`、`agentid.cn/ubuntu.env`；后者由本机工作区维护并同步，固定远端 MySQL 镜像、健康卷、Redis 卷和 CN 子网，只用于远程 Docker，不用于本机 Docker。
+- Ubuntu PUB Compose 还要在基础与域 Compose 后加载 `agentid.pub/ubuntu-compose.yml`，并按 `local.env`、`ubuntu.env` 顺序提供变量；镜像 SHA 指向本机源码构建并同步到 Ubuntu 的镜像。
+
+- `D:\modelunion\kite` 本机工作区是唯一代码真源。所有源码、测试脚本和 Compose 改动先在本机完成；不得直接在 Ubuntu 的 `/data/kite` 或 Tester 工作区修代码。远端产生的临时修复必须先同步回本机、审阅并纳入本机工作区，再继续修改。
+- Docker context 只选择远端 Docker daemon，不同步文件。远程容器的 bind mount 路径由 Ubuntu 主机解析；本机文件即使在 Compose 中写成挂载，也不会自动出现在远端。
+- 服务端代码变更后，使用本机工作区作为 build context 构建新镜像，再部署并 recreate 目标 Ubuntu 服务。可用远程 Docker context 构建，使本机 build context 发送到 Ubuntu；也可本机 build 后传输镜像。不得只 restart 旧容器，也不得从未核验的远端冻结副本 build。
+- SDK 或测试代码变更后，只同步改动的源码和测试文件到实际 Tester bind mount 对应目录。不要覆盖远端数据库、身份材料、依赖 volume 或测试结果；`package.json` / lockfile 变化仍须走独立 Linux 依赖准备阶段，不得复制 Windows `node_modules`。
+- 每次测试前记录本机 revision、dirty 文件清单和变更文件 SHA-256；同步后逐文件比较本机 `Get-FileHash` 与 Ubuntu `sha256sum`。任一不一致、挂载源不明或镜像内容未对应本机源码时停止测试，不得把旧运行结果记到新源码版本。
+- 测试日志、结果和环境数据保留在远端；代码更新方向始终是本机到 Ubuntu。仅当确认远端有本机缺失的代码改动时，才先把内容取回本机并完成审阅，再从本机重新同步。

package/_packed_docs/sdk/0.5.30-SDK/345/272/224/347/224/250/351/233/206/346/210/220/346/214/207/345/215/227.md

@@ -0,0 +1,61 @@
+# AUN SDK 0.5.30 应用集成指南
+
+面向应用开发者，示例使用 TypeScript。本文记录 0.5.30 当前工作区行为；包发布与服务部署状态需分别核对。0.5.29 的共识、resolve 和普通上传规则继续适用，见[0.5.29 应用指南](0.5.29-SDK应用集成指南.md)；四端实现和验证边界见[开发与移植指南](0.5.30-SDK开发与移植指南.md)及 [parity 清单](../../python/CHANGES_FOR_PARITY.md#v0530--控制流按需恢复与-sdk-行为对齐未发布)。
+
+## 1. 本版应用行为
+
+| 范围 | 0.5.30 行为 |
+| --- | --- |
+| 后台控制消息恢复 | 连接后恢复一次；后续由 push 检查对应 peer、群和流的 gap，不再周期空拉取 |
+| 应用主动 Pull | 不受后台恢复调度限制，应用仍可按需调用消息或群组 Pull |
+| 本地 Ownership | owner 可为 human 或 agent；subaid 必须为 agent；释放继续使用 `releaseSubaid` |
+| Storage 版本 | `expected_version` 先做版本预检；写响应的 `version` 由应用保存并用于后续写入 |
+| observer 转发 | SDK 外发时剥离本地语义证据及诊断字段，保留业务 payload，不改原接收对象 |
+| 风控查询 | `gateway.risk_status` 是内部 RPC，应用不得直接调用 |
+
+## 2. 消息消费与后台恢复
+
+先订阅事件再连接。应用 handler 应在业务持久化完成后返回；应用仍需按消息 ID 和业务操作键处理重复交付。
+
+```ts
+const client = new AUNClient(signer);
+client.on('message.batch', persistMessages);
+client.on('group.message_batch', persistMessages);
+await client.connect({ auto_reconnect: true });
+```
+
+连接就绪后，SDK 检查一次待处理 peer 和群流；之后由控制类 push 触发对应 gap 检查。群组恢复依据 `group.list_my` 返回的 `streams[message_class][persistent|volatile].needs_pull` 选择要拉取的流。后台恢复没有周期定时器；应用主动 Pull 仍按调用执行，不必等待 push。
+
+SDK 负责解密、交付、游标和 ACK；应用负责业务持久化。连接 READY、后台追赶完成和业务处理完成是不同状态。History 供历史查询，不替代实时消费。
+
+## 3. 本地 Ownership
+
+本地绑定和转移可由 SDK 持有身份材料的应用直接编排，不发 P2P。owner 和新 owner 可为 human 或 agent；subaid 必须为 agent，参与 AID 必须互异且对应 client 持有私钥。
+
+```ts
+const bound = await ownerClient.bindLocalSubaid(subClient);
+if (bound.status !== 'completed') throw new Error(bound.reason);
+
+const moved = await ownerClient.transferLocalSubaid(subClient, newOwnerClient);
+if (moved.status !== 'completed') throw new Error(moved.reason);
+```
+
+绑定后仍可用 `checkOwnershipConsensus(subAid)` 查询 NS 确认的状态。释放沿用 `ownerClient.releaseSubaid(subAid)`；0.5.30 不新增 local release API。详细步骤与失败处理见 [Ownership 2.1 应用指南](Ownership2.1-SDK应用集成指南.md)。
+
+## 4. Storage 版本处理
+
+写操作传入 `expected_version`／`expectedVersion` 时，SDK 在写 RPC 前读取当前版本；不匹配会返回 `ECONFLICT`。未传版本或显式 `force` 时跳过这项预检。服务端兼容路径仍有“检查后、写入前”并发窗口，因此这不是原子 CAS。成功响应包含写后 `version`：使用 low-level API 的调用方应读取并保存该值供后续写入；通过 Python、TS 或 JS VFS 操作时，由 VFS 记录已知版本。结果不确定时先读取当前对象状态，不要盲目改用新版本重放。
+
+## 5. observer 转发与风控边界
+
+发送 `type: 'observer.forward'` 时，SDK 会在外发副本中移除 `original` 的 `_semantic_evidence`、`_agent_md`、`source`、设备标识和 proximity／same_* 诊断字段。原接收对象及业务 payload 保持不变。不要依赖被剥离的本地字段作为远端业务数据。
+
+应用不能通过 `client.call('gateway.risk_status', ...)` 查询风控状态；该 RPC 仅供服务端调用。SDK 对风险 push 的内部验签、状态处理和 ACK 沿用既有路径。
+
+## 6. 升级核对
+
+- Node 与 Browser SDK 均使用 0.5.30；Browser 继续使用浏览器身份存储与 WebCrypto。
+- 后台同步不再依赖周期控制消息恢复；需要立即响应的业务动作仍由应用主动 Pull。
+- 本地 Ownership 的 owner 类型和 subaid 类型分别校验；释放仍调用 `releaseSubaid`。
+- Storage 写入保存响应 `version`，不要把 `expected_version` 预检当作原子 CAS。
+- 不直接调用内部 `gateway.risk_status`；四端差异、源代码落点和测试范围见 [移植指南](0.5.30-SDK开发与移植指南.md)。

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

@@ -0,0 +1,68 @@
+# AUN SDK 0.5.30 开发与移植指南
+
+面向四端 SDK 维护者和其它语言实现者，定义当前 0.5.30 工作区契约。应用用法见[应用集成指南](0.5.30-SDK应用集成指南.md)，详细实现差异和已有验证范围见 [parity 0.5.30](../../python/CHANGES_FOR_PARITY.md#v0530--控制流按需恢复与-sdk-行为对齐未发布)。0.5.29 共识、resolve 和普通上传规则继续作为基线，见[0.5.29 移植指南](0.5.29-SDK开发与移植指南.md)。
+
+## 1. 跨端契约
+
+| 范围 | 必须保持的行为 |
+| --- | --- |
+| 控制流恢复 | 连接后恢复一次；后续由 push 触发；只拉取有 gap 的群流，不运行周期控制恢复定时器 |
+| 前台 Pull | 应用主动调用不受后台恢复调度门控 |
+| observer 转发 | 外发副本剥离同一组本地证据和诊断字段，不修改接收对象 |
+| 本地 Ownership | owner／新 owner 可为 human 或 agent；subaid 只能为 agent；释放仍走 `releaseSubaid` |
+| Storage | `expected_version` 是客户端写前预检，不保证服务端原子 CAS |
+| 内部 RPC | 四端公开 RPC 管线拒绝应用调用 `gateway.risk_status` |
+
+## 2. 按需控制流恢复
+
+Python 在连接就绪后调用 `ControlMessageCoordinator.recover_once()`；TS、JS、Go 在各自连接及 push 路径触发恢复。初次检查待处理 peer 与 `group.list_my`，运行期 push 只唤起对应目标和控制消息流。控制恢复定时器已移除，不代表 SDK 中其它心跳、凭证或 token 定时任务一并移除。
+
+对每个群，读取 `streams[message_class][persistent|volatile].needs_pull`：只有值为 `true` 才调度该流。兼容旧服务时，整个 `streams` map 缺失则回退拉取；map 存在但缺少类别或流状态则跳过该流。待确认 ACK 依据本地持久状态单独恢复。应用主动 Pull 不经过该后台调度判断。
+
+| SDK | 主要落点 |
+| --- | --- |
+| Python | `python/src/aun_core/_client/lifecycle.py`、`control_messages.py` |
+| TypeScript | `ts/src/client/control-messages.ts` 及 Client 连接／Push 接线 |
+| JavaScript | `js/src/client/control-messages.ts` 及 Client 连接／Push 接线 |
+| Go | `go/control_messages.go` 及 Client 连接／Push 接线 |
+
+服务端 `group.list_my` 应返回各消息类别下 persistent 与 volatile 流的最新状态，使 SDK 能判断 `needs_pull`。缺少状态与 `needs_pull: false` 不能混为一谈。
+
+## 3. observer.forward 外发字段
+
+仅在 `message.send`／`group.send` 的发送管线中，对 `type: 'observer.forward'` 的 payload 副本执行净化。删除 `original` 下列字段：
+
+| 字段 | 内容类别 |
+| --- | --- |
+| `_semantic_evidence` | 解密后保留的完整语义证据 |
+| `_agent_md` | 本地名片快照 |
+| `source` | 本地投递来源 |
+| `device_id`、`slot_id_full` | 本地设备／连接标识 |
+| `proximity`、`same_device`、`same_network`、`same_egress_ip` | 本地关系与网络诊断信息 |
+
+保留业务 payload 和 `original` 的其它字段；不能原地修改应用持有的接收对象。四端使用相同字段清单。
+
+## 4. 本地 Ownership 与 YAML 更新
+
+`bindLocalSubaid(subClient)` 和 `transferLocalSubaid(subClient, newOwnerClient)` 允许 owner／新 owner 的 AID 类型为 human 或 agent；subaid 必须为 agent。参与 AID 必须互异并由对应 client 提供本地私钥。其它普通 Ownership API 的主体限制不能套用到这两个 local API。释放不增加新入口，继续使用 `releaseSubaid(subAid)`。
+
+TS／JS 更新 Ownership frontmatter 时以 YAML 库重序列化，并设置 `{ lineWidth: 0, blockQuote: 'literal' }`，关闭宽度折行及 folded block 样式；随后校验完整 agent.md。目标是保留 schema 中已有字段信息，不承诺字节级原格式。Python／Go 不使用该 TS／JS serializer 路径。
+
+## 5. Storage expected_version 预检
+
+写操作带 `expected_version` 且未启用 `force` 时，SDK 在写 RPC 前通过 `storage.head_object` 或 `storage.fs.lstat` 读取权威版本；对象不存在按版本 `0` 处理，不匹配时在发送写 RPC 前返回 `ECONFLICT`。缺少 `expected_version` 或显式 `force` 时跳过该预检。相关实现覆盖支持版本参数的对象写操作与文件 rename；目录等非文件 rename 不按文件版本预检。
+
+此检查保留 SDK 原有的版本冲突语义，但服务端兼容并发写入并返回写后版本，读到版本与实际提交之间存在竞态窗口，不能称为原子 CAS，也不能声称 SDK 已验证写后版本。应用应读取并保存成功响应的 `version`；Python、TS、JS VFS 会将响应版本作为后续写入的已知版本，Go low-level 保持原始响应边界。
+
+## 6. 内部 RPC 与跨端差异
+
+四端公开 RPC 调用入口均把 `gateway.risk_status` 标记为内部方法并拒绝应用直接调用。风险 push 的接收、验签、状态处理和 ACK 是独立路径，不因限制主动 RPC 而删除。
+
+| 维度 | Python | Go | TypeScript | Browser JavaScript |
+| --- | --- | --- | --- | --- |
+| 版本值持久层 | 文件 | 文件 | 文件 | IndexedDB |
+| 首次控制恢复 | 生命周期连接就绪后 `recover_once()` | Client 连接／Push 接线 | Client 连接／Push 接线 | Client 连接／Push 接线 |
+| Ownership YAML 更新 | 不走本版 TS／JS emitter | 不走本版 TS／JS emitter | `lineWidth: 0` 与 literal block | `lineWidth: 0` 与 literal block |
+| Storage VFS 版本 | 记录返回版本 | low-level 返回原始结果 | 记录返回版本 | 记录返回版本 |
+
+版本、源码文件、服务端配套和测试边界见 [Python parity 0.5.30](../../python/CHANGES_FOR_PARITY.md#v0530--控制流按需恢复与-sdk-行为对齐未发布)。当前只有定向测试结果；Python Ownership／控制消息／Storage 完整单测、四端全量测试、live E2E 和线上服务验收均未覆盖，不应表述为全量通过。

package/_packed_docs/sdk/0.5.31-SDK/345/272/224/347/224/250/351/233/206/346/210/220/346/214/207/345/215/227.md

@@ -0,0 +1,162 @@
+# AUN SDK 0.5.31 应用集成指南
+
+面向应用开发者，示例使用 Node.js TypeScript SDK。本文依据截至 2026-11-04 的 `0.5.31` 工作区；包发布、服务部署和验收结果分别核对。跨语言契约见[开发与移植指南](0.5.31-SDK开发与移植指南.md)，实现及已有验证见 [parity 0.5.31](../../python/CHANGES_FOR_PARITY.md#v0531--群组织共识控制流-v2-与严格版本写入未发布)。
+
+## 1. 本版接入变化
+
+| 范围 | 0.5.31 行为 | 应用接入要点 |
+| --- | --- | --- |
+| 群／组织 Ownership | 现代实体使用通用声明和双文件共识，管理仍走各自生命周期 | 创建、转让和解散使用群／组织入口 |
+| 旧实体补绑 | owner 每连接首次访问对应实体时检查，必要时补齐现代材料 | 保留本地实体密钥及中断恢复材料 |
+| 分类消息 | 协商 `message_classes_v2`；群只支持 `normal/control` | 应用控制消息使用 `control`，不发送群 `sdk_control` |
+| 控制流 ACK | 去掉 `scan_proof` 及续证重扫，保留游标和待确认 ACK | 使用 SDK 消费流程，不自行制造证明或推进水位 |
+| Storage 写入 | SDK 写入携带版本，服务端执行最终 CAS，`force` 不取消版本条件 | 以成功版本继续写，冲突后重新读取并处理业务冲突 |
+| Python 显式重连 | 退避／失败状态无 token 时重新认证，已有 token 保留 | 延用 `connect()` 和连接状态处理 |
+
+0.5.29 的公共共识缓存、resolve、普通名片上传锁规则继续适用，见[历史接入说明](0.5.29-SDK应用集成指南.md)。其中群／组织的当前规则以本文为准；0.5.30 中“force 跳过版本预检”的行为已被替代。
+
+## 2. 身份、连接与业务消费
+
+Node 包为 `@agentunion/fastaun`，要求 Node `>=22.16.0`；浏览器使用 `@agentunion/fastaun-browser` 和 IndexedDB／WebCrypto。Python 包为 `fastaun`，要求 Python `>=3.11`。四 SDK 的包／运行时版本统一为 `0.5.31`，具体安装产物仍需核对。
+
+加载原有身份仓库后创建 Client；身份目录、加密 seed、device 和 slot 沿用原配置。浏览器存储配置与 Node 文件目录配置分别使用各自 API。
+
+```ts
+import { AIDStore, AUNClient } from '@agentunion/fastaun';
+declare const store: AIDStore;
+declare const aid: string;
+const loaded = store.load(aid);
+if (!loaded.ok) throw new Error(loaded.error.message);
+const client = new AUNClient(loaded.data.aid);
+```
+
+先订阅消费事件，再连接。下列 handler 由应用实现，返回的 Promise 应在业务持久化完成后成功结束；应用仍需按接收身份、消息 ID 和业务操作键幂等处理。
+
+```ts
+declare function commitBatch(batch: unknown): Promise<void>;
+client.on('message.batch', commitBatch);
+client.on('group.message_batch', commitBatch);
+client.on('group.event_batch', commitBatch);
+await client.connect({ auto_reconnect: true });
+```
+
+SDK 负责解密、消息交付、消费游标与 ACK，应用负责业务事务。连接 READY、后台追赶完成和业务处理完成是不同状态。History 用于历史查询，不替代实时消费；ACK 不等于标记已读。
+
+Python 的显式 `connect()` 接管后台退避／失败状态时，无 token 会恢复认证，有 token 继续既有重连路径。这项修复不表示可以无条件重放先前失败的业务写入；超时写入仍需查询结果。
+
+## 3. 分类消息与按需恢复
+
+### 3.1 发送与消费
+
+| 类别 | P2P | 群 | 消费者 |
+| --- | --- | --- | --- |
+| `normal` | 支持 | 支持 | 应用 |
+| `control` | 支持，须协商 | 支持，须协商 | 应用 |
+| `sdk_control` | 仅协商的 SDK 内部协议 | 不支持 | SDK 内部 |
+
+普通业务默认使用 `normal`。应用自己的控制指令使用 `message_class: 'control'`，示例中的目标为完整 AID：
+
+```ts
+declare const peerAid: string;
+await client.message.send({ to: peerAid, encrypt: true,
+  message_class: 'control', payload: { type: 'app.refresh.v1' } });
+```
+
+群消息通过 `client.group.send` 发送，类别仅能为 `normal` 或 `control`。群 `sdk_control` 请求在本地拒绝，该类群推送被忽略；不要把内部 Owner 名片通知改成群 `sdk_control` 广播。SDK 内部类别不会作为普通应用消息交付。
+
+正 TTL 消息沿用非持久化流语义，不能依赖离线持久补投；群 TTL 发送也要求协商新能力。旧 `message_classes_v1` 不等于 `message_classes_v2`，分类能力以实际连接协商为准。
+
+### 3.2 恢复和 ACK
+
+连接就绪后恢复一次待处理 peer 与群流，之后由 Push 唤起对应目标、消息类别及 persistent／volatile 流。群恢复根据 `group.list_my` 的 `streams[message_class][persistent|volatile].needs_pull` 选择拉取；没有周期控制流全量扫描。应用主动 Pull 仍可按需执行。
+
+控制消息 Pull／ACK 不再依赖 `scan_proof`，也不再因证明过期重复拉取。SDK 继续保存处理水位与待确认 ACK，重连后恢复确认；volatile 流使用自己的游标。应用通常无需手动 ACK，不要混用消息类别、peer／群或持久／非持久流的水位。
+
+## 4. 群／组织 Ownership
+
+### 4.1 查询当前关系
+
+现代群／组织 `agent.md` 带 `ownership.statement`，由实体身份签名；owner 在自己的 Storage 保存配对 `owner.md`。应用通过公共入口查询 NS 确认的关系，无需自行下载并拼接两个文件：
+
+```ts
+declare const entityAid: string;
+const current = await client.checkOwnershipConsensus(entityAid);
+const fresh = await client.checkOwnershipConsensus(entityAid, true);
+```
+
+默认查询沿用同一 Client 内的共识缓存：仅复用 `consensus`、本地已观察 ETag 未变且未标记 missing 的结果，无 TTL；新 Client 首查、非一致结果及显式 `true` 回源 NS。需要立即复核时传 `true`，不要把默认缓存命中解释为已经发现所有远端变化。
+
+| 结果 | 应用处理 |
+| --- | --- |
+| `consensus` | 读取已确认 `owner_aid` 和关系版本；具体业务权限仍由服务端检查 |
+| `single_sided` | 只有单边材料，尚未完成共识 |
+| `unbound` | 没有现代声明；旧实体可能仍有生命周期 owner，不等于实体无人管理 |
+| `released` | 有声明但关系已解锁，不能继续按已确认归属使用 |
+| `invalid`／`unavailable` | 材料非法或当前无法确认，读取错误信息并保留原恢复材料 |
+
+服务端在现代文件能确认时采用文件共识，旧材料不能确认时由群／组织服务补充确认；相应名片必须确实是 `type=group` 或 `type=org`。这是服务端旧格式兼容，不表示单张名片的 `owner` 字段就能证明现代共识。
+
+### 4.2 每连接首次访问时补绑
+
+owner 登录后首次访问指定群／组织时，SDK 先筛选本地实体密钥或可恢复的群绑定材料，再确认当前 active owner；需要时补齐现代声明，已有一致关系直接跳过。检查按身份、连接与实体合并，不会在登录后遍历全部群补传，同一连接失败也不会反复补绑。
+
+访问预检查失败后仍继续原业务请求，由服务端检查权限；它不是“补绑必定成功”的承诺。创建、绑定、接收转让及恢复中断上传则会在发布后确认共识，应用需要处理这些流程返回的失败。
+
+### 4.3 创建、转让与解散
+
+| 对象 | 继续使用的入口 |
+| --- | --- |
+| 群 | `createGroup`／`bindGroupAid`、`group.transferOwner`／`completeGroupTransfer`、`group.dissolve` |
+| 组织 | `org.lifecycle.create`／`transfer`／`transferAccept`／`dissolve` |
+| 普通 agent | 原 Ownership 绑定／释放／转移入口；本地编排继续使用 `bindLocalSubaid`／`transferLocalSubaid` |
+
+群／组织统一的是声明材料和共识，不要改用普通 `bindOwneraid`、`transferSubaid` 或 local API 操作实体。普通 local 编排的 owner／新 owner 可为 human 或 agent，subaid 仍只能为 agent；释放沿用 `releaseSubaid`。
+
+SDK 在群／组织转让或解散前发布相应 owner 授权。只有确定的业务拒绝，且 owner、声明原件均未变化时，才尝试恢复原声明；网络超时或结果不明时保留材料。遇到这类失败先查询生命周期状态及 fresh 共识，再按原流程恢复，不能删除材料或无条件重放。
+
+## 5. Storage 版本与并发写入
+
+### 5.1 版本选择
+
+SDK 对象写入、创建／完成上传、删除、元数据更新、追加、移动及文件 rename 都携带版本条件。low-level 未指定版本时先读取当前权威版本；明确不存在使用 `0`。显式版本不匹配时在写 RPC 前失败，服务端提交时再执行最终 CAS。
+
+| 应用意图 | 使用方式与行为 |
+| --- | --- |
+| 只创建新对象 | 显式 `expectedVersion: 0`；对象已存在则冲突 |
+| 修改已知版本 | 传先前读取或写入确认的 `expectedVersion`，成功后保存新 `version` |
+| 允许覆盖 | `overwrite: true` 控制覆盖意图，本身不取消版本条件，也不跳过 VFS 的已知版本 |
+| 按最新状态覆盖 | `force: true` 未传版本时跳过 VFS 历史版本选择，由底层重新读版本提交；仍可能并发冲突 |
+| `force` 同时传版本 | 严格保留该版本，不自动替换为最新版本 |
+
+```ts
+const created = await client.storage.writeBytes('/app/state.json', '{}',
+  { expectedVersion: 0 });
+const updated = await client.storage.writeBytes('/app/state.json', '{"ready":true}',
+  { expectedVersion: created.version, overwrite: true });
+```
+
+示例假定父目录存在。VFS 会记录成功写入的版本；已有对象缺少读取／写入版本时，单独 `overwrite: true` 仍可能被 VFS 拒绝。low-level 自动补版本不意味着 VFS 的这些前置规则被取消。对象不存在时显式传非零版本仍可能被 SDK 预检拒绝，不会无条件改成 `0`。
+
+### 5.2 冲突和预读失败
+
+遇到 `ECONFLICT` 应重新读取当前对象、判断业务变更是否可合并，再提交明确版本。写入超时则先查询对象版本和内容确认结果；不能只把版本刷新后自动重放原业务修改。
+
+Python 在读权限不足，或已确认挂载路径命中特定权威预读错误时，允许保留显式版本交服务端检查；没有显式版本仍失败。Go／TS／JS 没有该例外，不能假定只有写权限的同一调用在四端都能通过。文件 rename 的预读及其它差异见[移植指南](0.5.31-SDK开发与移植指南.md)。
+
+Python CLI 的 inline、去重与会话上传也携带预检版本，包括覆盖上传。服务端未传版本的兼容模式用于旧调用；新 SDK 的上述封装继续携带版本，`force` 不等于无条件覆盖。
+
+## 6. 延续的转发与风控边界
+
+`observer.forward` 外发时，SDK 在副本中移除 `original` 的 `_semantic_evidence`、`_agent_md`、`source`、`device_id`、`slot_id_full`、`proximity`、`same_device`、`same_network`、`same_egress_ip`，保留业务 payload，不修改原接收对象。需传递的业务数据应由应用定义，不依赖这些本地诊断字段。
+
+`gateway.risk_status` 仍为服务端专用 RPC，应用不能直接调用。SDK 对风险 Push 的验签、请求预算、状态处理和 ACK 保持原流程；应用通过既有风险状态事件处理暂停、限速和重连等待。
+
+## 7. 升级与验收核对
+
+- 四 SDK 包／运行时及测试环境使用 `0.5.31`；Gateway／Message／Group 需具备对应 `message_classes_v2` 能力，NS／Storage 与实体归属检查需匹配新契约。
+- 普通消息及应用控制消息可正常消费；群不发送 `sdk_control`；TTL 非持久流与持久流分别确认，重连可恢复 pending ACK。
+- 现代实体查询共识；旧实体在 owner 首次访问时可补绑；无本地材料的成员不触发 owner 修复；转让／解散继续使用生命周期流程。
+- 验证创建版本 `0`、已知版本更新、过时版本冲突、`force` 保留显式版本，以及超时后查询结果的应用处理。
+- 保留原身份、seed 与恢复材料，按[公网测试指南](../aun公网测试运行指南.md)串行断点续跑；具体环境使用 `{svc}.{issuer}`，公网验收开启 TLS 校验。
+
+已有 Python 公网结果按多次断点续跑覆盖服务端 12 项、smoke 9 项、E2E 24 项，签名审计正常生命周期 48 项；期间出现过间歇 WebSocket 握手超时。它们不代表本版四 SDK 单轮全量通过，也不证明最新服务端 GC／索引已部署。精确执行范围与本地定向记录见 [parity 验证范围](../../python/CHANGES_FOR_PARITY.md#0531-已有验证与覆盖范围)；本次整理指南未重新运行代码或公网测试。