@agentunion/fastaun 0.5.29 → 0.5.30

package/CHANGELOG.md

@@ -6,6 +6,28 @@
 
 ---
 
+## 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,28 @@
 
 ---
 
+## 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/AUN_DOCS_GUIDE.md

@@ -61,7 +61,8 @@ Group 的成员 block/status、暂停群权限和两阶段群主转让，以及
 | - | [0.5.22 SDK 开发与移植指南](0.5.22-SDK开发与移植指南.md) | 同步、Stage/CAS、撤销续期、缓存、服务依赖及 Rust 清单 |
 | - | [0.5.24 SDK 应用集成指南](0.5.24-SDK应用集成指南.md) | 当前消息接线、无任务 Ownership、两个 local 编排、缓存和凭证组织 |
 | - | [0.5.24 SDK 开发与移植指南](0.5.24-SDK开发与移植指南.md) | 消息提交、NS 事实和远端 CAS、local 身份隔离、缓存新鲜度与语言差异 |
-| - | [0.5.29 应用指南](0.5.29-SDK应用集成指南.md)、[开发与移植指南](0.5.29-SDK开发与移植指南.md)、[变更与跨端对齐](../../python/CHANGES_FOR_PARITY.md#v0529--共识查询缓存与普通上传未发布) | 当前应用接入、共识输入输出、无 TTL 的 ETag 缓存、resolve、普通上传锁与恢复、NS 配套及四端移植 |
+| - | [0.5.30 应用指南](0.5.30-SDK应用集成指南.md)、[开发与移植指南](0.5.30-SDK开发与移植指南.md)、[变更与跨端对齐](../../python/CHANGES_FOR_PARITY.md#v0530--控制流按需恢复与-sdk-行为对齐未发布) | 按需控制流恢复、observer.forward 本地字段剥离、本地 human owner、Storage 版本预检及四端差异 |
+| - | [0.5.29 应用指南](0.5.29-SDK应用集成指南.md)、[开发与移植指南](0.5.29-SDK开发与移植指南.md)、[变更与跨端对齐](../../python/CHANGES_FOR_PARITY.md#v0529--共识查询缓存与普通上传未发布) | 0.5.29 基线：共识输入输出、无 TTL 的 ETag 缓存、resolve、普通上传锁与恢复、NS 配套及四端移植 |
 | - | [0.5.28 应用指南](0.5.28-SDK应用集成指南.md)、[开发与移植指南](0.5.28-SDK开发与移植指南.md)；[0.5.27 应用指南](0.5.27-SDK应用集成指南.md)、[开发与移植指南](0.5.27-SDK开发与移植指南.md) | 0.5.28 agent.md 上传／下载校验、共识 fresh、分类控制消息、Owner 通知与风控；四端实现和验证范围见 [parity](../../python/CHANGES_FOR_PARITY.md#v0528--校验控制消息与风控未发布) |
 | - | [agent.md 与 group.index 的 ETag 观察与同步机制](agent.md与group.index的ETag观察与同步机制.md) | 服务端 ETag 来源、四 SDK 被动观察、agent.md 下载触发、group.index 显式 pull 与 CAS |
 | - | [CHANGELOG-0.5.6](CHANGELOG-0.5.6.md) | **0.5.6 版本更新日志**：首次签名者回源、下载提交前验签、消息窗口、显式 change-seed 与语言能力边界 |
@@ -85,7 +86,7 @@ Group 的成员 block/status、暂停群权限和两阶段群主转让，以及
 | - | [组织服务 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 / resolve opts 与输入输出 / frontmatter 类型 / Agent.md 校验签名 / AID / AUNClient 生命周期并发 / 四 SDK access token getter / 群组高层身份编排 / History 与已读门面 / 已读变更及本地补偿完成 / 消息来源与 Pull 同步生命周期 / 事件 / RPC；当前 ownership 变更见 [0.5.29 parity](../../python/CHANGES_FOR_PARITY.md#v0529--共识查询缓存与普通上传未发布) |
+| 06 | [API手册](06-API手册.md) | AIDStore / resolve opts 与输入输出 / frontmatter 类型 / Agent.md 校验签名 / AID / AUNClient 生命周期并发 / 四 SDK access token getter / 群组高层身份编排 / History 与已读门面 / 已读变更及本地补偿完成 / 消息来源与 Pull 同步生命周期 / 事件 / RPC；当前 Ownership 与内部 RPC 增量见 [0.5.30 parity](../../python/CHANGES_FOR_PARITY.md#v0530--控制流按需恢复与-sdk-行为对齐未发布) |
 | 07 | [错误处理](07-错误处理.md) | Result、Python `ErrorInfo.cause`、异常、错误码、重试 |
 | 08 | [最佳实践](08-最佳实践.md) | 幂等、消息同步/History、AUNClient 级 Pull Gate（同 namespace 单飞、客户端最多 4 个并行）、测试数据 |
 | - | [Storage RPC 手册](09-storage-rpc-manual.md) | Storage RPC、实际字节 MIME、三阶段 Content-Type、OSS 403、HTTP 下载与凭据边界、默认读缓存持久层、条件读取与 noCache |
@@ -104,7 +105,8 @@ Group 的成员 block/status、暂停群权限和两阶段群主转让，以及
 | 实现、移植或审查 0.5.22 SDK，查看 Stage/CAS、配套服务修复、读缓存及 Rust 验收清单 | [0.5.22 SDK 开发与移植指南](0.5.22-SDK开发与移植指南.md) |
 | 接入或升级 0.5.24，查看当前消息、无任务 Ownership、两个 local 场景、缓存及凭证组织 | [0.5.24 SDK 应用集成指南](0.5.24-SDK应用集成指南.md) |
 | 实现、移植或审查 0.5.24，核对提交／ACK、NS 事实、远端 CAS、local 身份隔离和缓存新鲜度 | [0.5.24 SDK 开发与移植指南](0.5.24-SDK开发与移植指南.md) |
-| 接入或移植 0.5.29，核查共识、resolve、上传锁与恢复 | [应用指南](0.5.29-SDK应用集成指南.md)：接入 L5-54、共识 L55-80、resolve L81-104、上传管理 L105-145、缓存／业务 L146-167、升级 L168-180；[开发与移植指南](0.5.29-SDK开发与移植指南.md)：契约 L5-63、缓存／resolve L64-94、上传恢复 L95-123、四端／继承 L124-151、核查 L152-164；[parity 当前章节](../../python/CHANGES_FOR_PARITY.md#v0529--共识查询缓存与普通上传未发布) L15-87 |
+| 接入或移植 0.5.30，核查后台恢复、本地 Ownership 与 Storage 版本处理 | [应用指南](0.5.30-SDK应用集成指南.md)：行为 L5-14、消息恢复 L16-29、Ownership L31-43、Storage L45-47、转发与风控 L49-53、升级 L55-61；[开发与移植指南](0.5.30-SDK开发与移植指南.md)：契约 L5-14、控制恢复 L16-29、转发 L31-43、Ownership/YAML L45-49、Storage L51-55、差异 L57-68；[parity](../../python/CHANGES_FOR_PARITY.md#v0530--控制流按需恢复与-sdk-行为对齐未发布) L15-58 |
+| 接入或移植 0.5.29 基线，核查共识、resolve、上传锁与恢复 | [应用指南](0.5.29-SDK应用集成指南.md)：接入 L5-54、共识 L55-80、resolve L81-104、上传管理 L105-145、缓存／业务 L146-167、升级 L168-180；[开发与移植指南](0.5.29-SDK开发与移植指南.md)：契约 L5-63、缓存／resolve L64-94、上传恢复 L95-123、四端／继承 L124-151、核查 L152-164；[parity](../../python/CHANGES_FOR_PARITY.md#v0529--共识查询缓存与普通上传未发布) L60-132 |
 | 回看 0.5.28 的 schema、共识、控制消息、Owner 通知与风控，以及 0.5.27 的历史增量 | [0.5.28 应用指南](0.5.28-SDK应用集成指南.md)：接入与消息 §1—§3 L5-95、凭证／组织 §4—§5 L96-137、Storage／Ownership §6—§7 L138-186、通知 §8 L187-201、风控／升级 §9—§10 L202-228；[开发与移植指南](0.5.28-SDK开发与移植指南.md)：校验 §1 L7-36、共识 §2 L37-62、wire §3 L63-108、outbox §4 L109-121、风控 §5 L122-134、移植 §6 L135-146。 [历史 parity](../../python/CHANGES_FOR_PARITY.md#v0528--校验控制消息与风控未发布) L88-172；公共共识流程以 0.5.29 为准 |
 | 0.5.24 应用按主题读：身份、消息、resolve、Ownership、文件缓存、凭证组织和升级 | `0.5.24-SDK应用集成指南.md` §2 L21-75、§3 L76-132、§4 L133-168、§5 L169-298、§6 L299-321、§7 L322-366、§9 L386-401；local bind L227-245、local transfer L246-267 |
 | 0.5.24 移植按主题读：消息提交、名片、观察、Ownership、缓存、PKI、凭证组织及语言差异 | `0.5.24-SDK开发与移植指南.md` §3 L32-84、§4 L85-92、§5 L93-122、§6 L123-217、§7 L218-245、§8 L246-261、§9 L262-297、§10 L298-325；Rust §11 L326-339、验收 §12 L340-354 |

package/_packed_docs/sdk/INDEX.md

@@ -14,7 +14,8 @@
 | [0.5.22 SDK 开发与移植指南](0.5.22-SDK开发与移植指南.md) | 后台退避 · 群状态 · 两种绑定与 Stage/CAS · 消息内部消费 · 撤销同步 · 组织恢复及配套服务修复 · 默认读缓存 · Rust 清单 |
 | [0.5.24 SDK 应用集成指南](0.5.24-SDK应用集成指南.md) | 当前身份与消息接入 · 无任务 Ownership · local 双／三身份编排 · resolve 与文件缓存 · 凭证组织 · 升级 |
 | [0.5.24 SDK 开发与移植指南](0.5.24-SDK开发与移植指南.md) | peer／batch 提交 · NS 事实与远端 CAS · local 短连接 · 观察与 PKI 缓存 · 持久化边界 · 语言差异和验收 |
-| [0.5.29 应用指南](0.5.29-SDK应用集成指南.md)、[开发与移植指南](0.5.29-SDK开发与移植指南.md)、[变更与跨端对齐](../../python/CHANGES_FOR_PARITY.md#v0529--共识查询缓存与普通上传未发布)；[Python](../../python/CHANGELOG.md)、[Go](../../go/CHANGELOG.md)、[TS](../../ts/CHANGELOG.md)、[JS](../../js/CHANGELOG.md) CHANGELOG | 当前应用接入、共识默认 force=false、NS 单次查询、无 TTL 的 ETag 缓存、resolve、普通上传锁／恢复与四端移植 |
+| [0.5.30 SDK 应用集成指南](0.5.30-SDK应用集成指南.md)、[开发与移植指南](0.5.30-SDK开发与移植指南.md)、[变更与跨端对齐](../../python/CHANGES_FOR_PARITY.md#v0530--控制流按需恢复与-sdk-行为对齐未发布) | 按需控制流恢复 · observer.forward 本地字段剥离 · human owner 本地 Ownership · Storage 版本预检 · 内部 RPC 边界 |
+| [0.5.29 应用指南](0.5.29-SDK应用集成指南.md)、[开发与移植指南](0.5.29-SDK开发与移植指南.md)、[变更与跨端对齐](../../python/CHANGES_FOR_PARITY.md#v0529--共识查询缓存与普通上传未发布)；[Python](../../python/CHANGELOG.md)、[Go](../../go/CHANGELOG.md)、[TS](../../ts/CHANGELOG.md)、[JS](../../js/CHANGELOG.md) CHANGELOG | 0.5.29 基线：共识默认 force=false、NS 单次查询、无 TTL 的 ETag 缓存、resolve、普通上传锁／恢复与四端移植 |
 | [0.5.28 应用指南](0.5.28-SDK应用集成指南.md)、[开发与移植指南](0.5.28-SDK开发与移植指南.md)；[0.5.27 应用指南](0.5.27-SDK应用集成指南.md)、[开发与移植指南](0.5.27-SDK开发与移植指南.md) | 历史 agent.md 校验、共识 fresh、分类控制消息、Owner 通知与风控；四端差异及验证边界见 [parity 0.5.28](../../python/CHANGES_FOR_PARITY.md#v0528--校验控制消息与风控未发布)，公共共识规则以 0.5.29 为准 |
 | [CHANGELOG-0.5.6](CHANGELOG-0.5.6.md) | **0.5.6 版本更新日志**：首次签名者回源 · 下载提交前验签 · 消息窗口 · 显式 change-seed · 语言能力边界 |
 | [01-快速开始](01-快速开始.md) | 安装 · 三主体模型 · 最小示例 · 多语言构造 |
@@ -77,6 +78,7 @@
 
 - 当前身份与消息接入、无任务 Ownership、两个 local 场景、名片及文件缓存、凭证组织与升级 → [应用集成指南](0.5.24-SDK应用集成指南.md)
 - 三主体分层、提交／ACK、NS 事实和远端 CAS、local 身份隔离、缓存新鲜度、语言差异与验收 → [开发与移植指南](0.5.24-SDK开发与移植指南.md)
+- 0.5.30 应用行为、主动 Pull 边界、本地 Ownership、Storage 版本及内部 RPC → [应用指南](0.5.30-SDK应用集成指南.md)；控制恢复、转发净化、YAML 与版本预检的四端契约 → [开发与移植指南](0.5.30-SDK开发与移植指南.md)；验证范围见 [parity](../../python/CHANGES_FOR_PARITY.md#v0530--控制流按需恢复与-sdk-行为对齐未发布)。
 - 0.5.29 应用接入、共识输入输出、resolve、上传与业务服务 → [应用指南](0.5.29-SDK应用集成指南.md)；缓存并发、上传恢复、NS 配套与四端落点 → [开发与移植指南](0.5.29-SDK开发与移植指南.md)；已有增量及验证见 [parity 当前章节](../../python/CHANGES_FOR_PARITY.md#v0529--共识查询缓存与普通上传未发布)。
 - 0.5.28 agent.md 校验、共识 fresh、分类控制消息、Owner 通知、风控和四端验证边界 → [应用指南](0.5.28-SDK应用集成指南.md)、[开发与移植指南](0.5.28-SDK开发与移植指南.md)；实现差异见 [历史 parity](../../python/CHANGES_FOR_PARITY.md#v0528--校验控制消息与风控未发布)。0.5.27 历史版本见对应旧指南与 parity。
 
@@ -178,6 +180,12 @@ TypeScript 身份与消息接线、Ownership 审批恢复、resolve、默认缓
 
 定义消息 peer／batch／Gate、Ownership NS 事实和远端 CAS、Stage、local 专属 slot 与身份代际、展示及文件缓存、PKI 和 Credential 查询新鲜度、组织 checkpoint。列出四端兼容差异、Rust 核查与分层验收，不将已有专项证据等同完整发布验证。
 
+### 0.5.30 更新日志与跨端对齐
+
+0.5.30 [应用指南](0.5.30-SDK应用集成指南.md)：行为摘要 §1 L5-14、消息恢复 §2 L16-29、本地 Ownership §3 L31-43、Storage §4 L45-47、转发与风控 §5 L49-53、升级 §6 L55-61；[开发与移植指南](0.5.30-SDK开发与移植指南.md)：跨端契约 §1 L5-14、控制恢复 §2 L16-29、observer.forward §3 L31-43、Ownership/YAML §4 L45-49、Storage §5 L51-55、内部 RPC 与差异 §6 L57-68。
+
+当前 [0.5.30 变更与对齐清单](../../python/CHANGES_FOR_PARITY.md#v0530--控制流按需恢复与-sdk-行为对齐未发布) L15-58：控制流恢复 L19-24、observer.forward L26-29、本地 Ownership 与 agent.md L31-35、Storage 预检 L37-41、内部 RPC／版本及验证边界 L43-58。
+
 ### 0.5.29 更新日志与跨端对齐
 
 0.5.29 [应用指南](0.5.29-SDK应用集成指南.md)：接入与消息 §1—§2 L5-54、共识 §3 L55-80、resolve §4 L81-104、上传管理 §5 L105-145、缓存／业务 §6—§7 L146-167、升级 §8 L168-180；[开发与移植指南](0.5.29-SDK开发与移植指南.md)：契约 §1—§2 L5-63、缓存／resolve §3—§4 L64-94、上传恢复 §5 L95-123、四端／继承 §6—§7 L124-151、核查 §8 L152-164。

package/_packed_docs//351/231/214/347/224/237/344/272/272/346/213/222/347/273/235/345/215/217/350/256/256TDD/345/210/206/351/230/266/346/256/265/345/256/236/346/226/275/350/256/241/345/210/222.md

@@ -0,0 +1,138 @@
+# AUN 陌生人拒绝协议 TDD 分阶段实施计划
+
+> 对应设计：[陌生人拒绝协议详细设计](陌生人拒绝协议详细设计.md)
+>
+> 状态：实施中；按提交次数计额度，Gateway 不实现消息 ID 去重，发布验收尚未完成。
+>
+> 版本：v1.0
+>
+> 更新时间：2026-11-01
+
+## 1. 交付范围
+
+交付 Gateway P2P 限额判定、互通/拒绝状态持久化与内存缓存、Console 手动历史回填和观察/启用控制、AID 对状态查询页面、拒绝状态 SDK RPC，以及回填/单域/跨域测试。
+
+本计划不改入群申请规则；不读写消息 payload；不做周期回填；不改 Peer/Relay 直连协议。受控 Gateway 之外的业务 P2P 路径不纳入强制范围，若实施阶段发现现存发送路径绕过 Gateway，先补齐路径清单并按设计边界验收，不以观察状态冒充全网状态。
+
+## 2. 交付清单与依赖
+
+| 编号 | 任务 | 依赖 | 完成标准 |
+|---|---|---|---|
+| P0-1 | 冻结路由和 RPC 契约 | 无 | `message.send`/兼容 P2P 方法、身份来源、错误原因、三项 deny RPC、Console 管理接口均有契约测试 |
+| P0-2 | 冻结配置和状态规则 | P0-1 | 默认 observe、enforce 必须配置正整数额度、配置 CAS、N/N+1、互通单调、拒绝优先规则由测试表达 |
+| P1-1 | Gateway 状态表与事务仓储 | P0-2 | 幂等迁移、精确 AID 键、并发 pending 更新、失败不破坏既有状态通过 |
+| P1-2 | 实时 Gateway 判定与互通标记 | P1-1 | 入站拒绝/额度、出站确认、互通豁免及错误不转发测试通过 |
+| P1-3 | Gateway 内存缓存 | P1-1 | 命中/未命中/淘汰/TTL/本地更新/跨实例 TTL 收敛测试通过；数据库仍是判定权威 |
+| P2-1 | Message 历史扫描内部 RPC | P0-1 | 分页稳定快照返回方向摘要，不读取/返回 payload；仅 Gateway 可调用 |
+| P2-2 | Gateway 手动回填 Worker | P2-1,P1-1 | 单实例任务锁、checkpoint、幂等续跑、互通/pending 回填和任务报告测试通过 |
+| P2-3 | 跨域反向存在探测 | P2-1,P2-2 | issuer 绑定、受认证批量探测、成功/无记录/远端失败/不支持协议状态测试通过 |
+| P3-1 | 拒绝状态 RPC | P1-1 | 当前身份绑定、set/clear/list 分页、重复操作、无对端事件、发送拦截测试通过 |
+| P3-2 | 四端 SDK 门面 | P3-1 | Python/TS/JS/Go 方法、类型、错误透传与跨 SDK wire 契约一致 |
+| P4-1 | Console 管理 API | P1-1,P2-2 | 管理员鉴权、配置更新审计、状态过滤分页、启动/续跑/查询回填测试通过 |
+| P4-2 | Console 策略与状态页面 | P4-1 | observe/enforce 切换、回填状态、未知提示、AID 对过滤分页及无 payload 渲染测试通过 |
+| P5-1 | 单域与兼容集成 | P1-3,P3-1,P4-2 | 消息、拒绝、回填、默认开关、Group 回归、旧 SDK 通过 |
+| P5-2 | 跨域集成 | P2-3,P5-1 | 双域收件箱回填证明双向关系、探测不可用则 unknown、实时反向交流互通通过 |
+| P6-1 | 发布安排与索引同步 | 全部 | 默认 observe、初始配置 pending_limit=5、手动回填及开关功能验收，索引与报告一致；实际观察期不测试，到时管理员手动切换 |
+
+## 3. TDD 执行顺序
+
+### Phase 0：契约先行
+
+先新增会失败的 Gateway/Console/SDK 契约测试，再实现任何路径。
+
+1. Gateway 路由测试：认证 `from` 优先于客户端字段；目标 AID 从路由参数取值；覆盖所有当前 Gateway P2P 发送入口、持久和 volatile，不把 Group 方法计入。
+2. 策略纯逻辑测试：缺省配置为 observe；显式 enforce 缺少/配置非法上限时拒绝启用；限额 N 时前 N 条允许、第 N+1 条拒绝；observe 超限仍允许但计数；owner 回复后互通并豁免；互通后拒绝仍拦截。
+3. 拒绝 RPC 契约测试：owner 只能来自认证上下文；设置 rejected/blocked、解除、本人分页查询；不能查他人清单；RPC 不发布事件。
+4. 错误契约测试：拒绝、限额、服务不可用使用稳定 reason；拒绝前不调用 Message/federation 下游；具体 JSON-RPC 数值错误码先与现有登记表核对。
+5. Console API 契约测试：非管理员拒绝；默认读取 observe；有效配置可更新；无效额度拒绝 enforce；状态列表强制分页上限；回填只能显式 POST 启动。
+
+Phase 0 完成后冻结方法名、字段、错误语义和 Gateway 入口清单。若现有 Gateway 代码显示某类业务发送不经过 Gateway，先把该范围列为未覆盖，不能跳过该发现继续宣称全量支持。
+
+### Phase 1：表与状态仓储
+
+1. 先写 Gateway store 测试：首次迁移、重复迁移、空库、已有数据、主键唯一、deny 清单索引查询和 AID 精确匹配。
+2. 再实现 `gateway_peer_state` 和策略配置持久化、repository；沿用 Gateway 当前数据库初始化路径及 AID 列定义。不建立逐消息准入/去重表。
+3. 先写并发测试：并行 N+K 次入站事务最多 N 次成功；不能有丢增量、重复互通回退、clear 与 set 竞态覆盖。
+4. 写事务失败测试：数据库读写失败时 enforce/deny 不调用下游；observe 的计数失败允许旧路由继续且能标记观察缺口。
+5. 先写策略配置测试：缺少记录初始化 observe，无效配置不生效，CAS 版本冲突返回冲突，数据库暂不可用时保留最后已知配置且缓存过期后停止 P2P 路由。
+6. 确认回填任务表有 job 唯一运行约束及稳定 checkpoint；pending 按当前值与历史摘要计数取较大值，相同 job 重放不累加。
+
+### Phase 2：Gateway 在线决策和缓存
+
+1. 先加状态机单测：deny 优先于 mutual；mutual 优先于额度；owner 出站成功确认互通；下游拒绝的出站不标记 owner 已发送；消息被额度拒绝时不增计数。
+2. 加 Gateway server handler 测试：成功请求只路由一次；被拒请求不调用本域 Message 服务或 federation；错误响应不泄露 block-list 内容。
+3. 接入跨域入站身份校验，测试 federation 注入身份与伪造 `from` 被拒绝。
+4. 加缓存测试：DB 回源、缓存命中、TTL 淘汰、写入后本地失效、跨实例 TTL 到期后回源，缓存缺失/故障不绕过 DB 原子判定。
+5. 覆盖相同、不同及缺省 `message_id` 的重复提交：Gateway 均按每次准入递增额度，达到上限后拒绝；入口不查询或存储消息 ID。
+
+### Phase 3：历史扫描与回填
+
+1. 先为 Message 内部扫描方法写契约测试：仅限 Gateway 内部调用；持久方向摘要快照；游标分页无漏项/重复；结果只有 AID 方向、计数和时间范围，没有正文/payload；任务结束后释放快照，快照过期必须显式重开 attempt。
+2. 为 Gateway Worker 写任务测试：仅手动触发、单任务并发锁、状态持久化、分批提交、断点续跑、失败域报告、管理员发起人记录。
+3. 写回填算法测试：同域 A→B 和 B→A 才确认双方 mutual；单向仅回填 pending；空结果不建虚构互通；重复运行幂等；live 状态与 deny 状态不被覆盖；pending 取当前值与历史计数的较大值，不做逐消息对账。
+4. 写保留边界测试：volatile/已删除/超过 Inbox 保留范围的消息不作为扫描证据；任务结果记录水位与扫描时间范围。
+5. 写跨域探测测试：只查询本地候选、批大小受限、远端双向认证、source issuer 与 `from_aid` 一致；远端确认反向入箱时标记 mutual；无反向、超时、不支持或数据不可用均记 unknown/failed，不作互通推断。
+6. 写 job API 和 Console 页面状态测试：进度、已确认、pending 回填、unknown、失败域和 checkpoint 字段完整显示；重启后不会自动启动任务，只能手动续跑。
+
+### Phase 4：拒绝 RPC 与 SDK
+
+1. 先为 Gateway RPC handler 写 set/clear/list 行为测试；owner 取 `_auth.aid`；`peer_aid` 不可为空或等于自身；重复 set/clear 幂等；只有本人可查。
+2. 写消息路由回归：blocked/rejected sender 即使 relation mutual 或模式为 observe，也被拒绝；解除后新消息可继续；不发对端事件。
+3. 四端 SDK 先写 facade 单测，核对方法名、参数、响应分页、错误透传；SDK 不缓存另一个权威拒绝状态。
+4. 运行四端 cross-SDK 契约矩阵，确保一个 SDK 设置的状态可由 Gateway 对其他 SDK 的消息统一执行。
+
+### Phase 5：Console 配置与状态面板
+
+1. Console 后端测试管理员鉴权、非法配置、配置 CAS 冲突、配置审计、状态查询条件、聚合观察数、page/page_size 边界、查询失败和 Gateway 不可达。
+2. 前端先测试查询参数构造、状态映射、分页、observe/enforce 表单校验、回填 start/resume 交互，再实现页面。
+3. 组件/API 测试覆盖默认 observe、上限未填时禁用 enforce、任务运行期间不重复启动、unknown/failed 明显展示、拒绝状态与 mutual 可以同时显示、pending 达限关系聚合数准确。
+4. 手动浏览器验收 Console 列表、过滤、分页、回填生命周期和开关切换；确认窄屏文本不重叠且 AID 不被截断到不可辨认。
+
+### Phase 6：集成、跨域与发布观察
+
+1. 单域集成覆盖 A→B 单向 N 条、N+1、B 回复后的互通、互通后继续交流、拒绝/解除、并发竞争、离线队列与 volatile 消息。
+2. 双域回填覆盖同一历史双向交流分别落入两域 Inbox；两域探测成功回填 mutual；一域历史缺失/离线时为 unknown，面板显示其限制。
+3. 跨域在线覆盖来源身份绑定、目标域限额、目标域拒绝、反向消息让两域各自确认本地 owner 互通。
+4. Group 回归验证 `group.request_join` 仍由 Group `max_pending` 执行，不被 Gateway P2P 策略影响。
+5. 旧 SDK 回归验证不调用新增 RPC 时发送行为不变；peer/relay 直连覆盖范围按设计明确记录，不虚报 Gateway 可拦截。
+6. 以用户确认的初始配置 `pending_limit=5` 作为本轮环境基线，默认部署 observe；验证手动回填、Console 计数与未知/失败关系，以及管理员手动 enforce/回退功能。开启前必须展示未知关系数及 Inbox 保留范围。实际观察期不执行测试，到时管理员根据报告手动切换。
+
+## 4. 断点续跑和完成门禁
+
+遵循项目 AUN 测试指南的首失败停测/修复/续跑规则。每阶段记录首次失败用例、修复提交范围和续跑起点；已经通过且不受修改影响的阶段不重复执行。
+
+本轮实现与测试完成门禁：
+
+- Gateway Go 单测、Console 后端测试、Console 前端测试和四 SDK 受影响单测通过；
+- 单域与双域集成通过，跨域数据不可证明时返回 unknown 而非误标 mutual；
+- 默认部署模式为 observe，用户确认的初始额度配置为 5；回填只能手动触发，完成后不自动 enforce；
+- Console 能查看并过滤 AID 对状态、回填覆盖率和错误域；管理员显式操作可以打开/关闭限额；
+- 现有 Group `max_pending`、旧 SDK、消息存储、ACK/Pull 和 E2EE 路径无回归；
+- 设计文档、实施计划、AUN SDK 索引与 Kite 总索引引用及行区间一致。
+
+## 5. 明确未纳入
+
+- 从已清理 Inbox、volatile 队列或 SDK 本地历史恢复互通事实；
+- 周期运行回填或自动从 observe 切换到 enforce；
+- 由 Gateway 自动判断某个 AID 应被拒绝/屏蔽；
+- 向对端发送拒绝通知或提供对端名单查询接口；
+- Gateway 消息 ID 去重、逐消息准入账本及其清理任务；
+- 通过 Message/Group 共用数据库或跨模块共享代码实现状态查询。
+
+## 6. 当前实施进度（2026-11-01）
+
+- [x] Gateway 关系/策略存储、事务限额、互通与拒绝、只读缓存及启动接线已落地；每次提交独立计数，不保留消息 ID。
+- [x] Message 元数据快照、Gateway 手动回填/续跑、跨域探测及未知/失败报告已落地；pending 仅取当前值与历史计数的较大值。
+- [x] 四端 SDK 拒绝门面和 Console 策略/状态页已接入；页面展示互通比例、超限候选、观察缺口和扫描时间范围。
+- [x] 已执行受影响业务单测、Go 静态检查、四端 SDK 定向验证及 Console 隔离构建；隔离 MySQL 已验证 Message 快照及回填任务锁/持久化。
+- [x] 简化后的 Gateway 状态仓储真实 MySQL 回归通过；实际仅创建关系和策略两表，无逐消息准入表。
+- [x] Ubuntu 真实单域及 PUB→CN、CN→PUB 专项通过：observe 超额放行、enforce 额度、重复提交计数、回复互通、拒绝/屏蔽/解除，以及 V2 解密、Pull、ACK。
+- [x] 真实手动回填与续跑通过：PUB 原失败任务 attempt 2 完成；CN 报告 partial，保留 5 对既有 aid.com 未知关系。自然历史 pending、backfill 互通及完成/部分完成的快照释放/保留已核验，策略保持 observe。
+- [x] 新增 RPC 正常成功分发、内部 scan 独立预算及普通在线期限回归通过；真实测试发现的跨域 Message 拒收错误透传已修复。
+- [x] Console 最近回填任务读取补齐并完成仓储/RPC 红绿及真实隔离 MySQL 验证；管理方法仅允许已认证 Console 服务，跨域探测的通用单次/批量转发出口已关闭，合法内部探测回归通过。
+- [x] Ubuntu 两域 Console 浏览器专项通过：默认读取持久任务、AID 对过滤、真实未知关系、CN 原任务 attempt 1→2 手动续跑、策略确认/取消及切回 observe、1440/390 宽度布局；分页仅验证不足 51 条的按钮边界。CN 复用原快照后仍为 partial/未知 5 对，PUB/CN 最终均为 observe。
+- [x] 真实 Group 回归通过：P2P observe/enforce、额度 5 下，本域与跨域申请仍按 Group `max_pending=1` 执行，重复申请保持单条 pending；四个 P2P 有向 pair 状态不变，测试群 `14275.agentid.pub` 身份保留。
+- [x] 未改源码的旧 SDK 0.5.19（commit `ab05792f2db86d534830c7a9e67e793c2caf3ce0`）真实回归通过：单域及双向跨域分别验证旧端发送/接收，共 6 个角色均完成 V2 解密、Pull、ACK，不调用新增 RPC；最终 PUB 为 observe/5/v20，CN 为 observe/5/v22。
+- [x] Python/TS/JS/Go 四端原生 cross-SDK 专项矩阵完成：单域、PUB→CN、CN→PUB 各 16 组合，共 48（实跑 45 PASS、沿用 3 REUSED）；实跑项各 7 子步，在 observe/5 下验证 set/list/clear、拒绝/屏蔽覆盖 mutual 及解除后 V2 解密/Pull/ACK 恢复，16 个客户端均 disconnected 且无 disconnect_errors。矩阵夹具适配仅限 Temp 的公开 CA 输入、各 SDK 目录瞬态有界等待及不同 Pull 返回契约，未修改 SDK/服务代码；历史失败记录保留，本矩阵不代表全量 Group/SDK suites。
+
+运维后续操作（不纳入本轮自动验收待办）：保持 observe，观察期不执行测试；管理员到时根据 Console 报告手动切换 enforce，实际观察与手动切换不作为本轮测试完成的签收条件。