@agentunion/fastaun 0.5.27 → 0.5.29

package/CHANGELOG.md

@@ -6,6 +6,61 @@
 
 ---
 
+## 0.5.29 — 未发布
+
+### Ownership 共识查询
+
+- `checkOwnershipConsensus(subAid?, force=false)` 改为在缓存未命中时直接向 NS 查询一次，携带 `X-AUN-Ownership-Check: 1` 和 `Cache-Control: no-cache`；替代 0.5.28 的首轮查询加非一致重查。
+- 仅复用同一 Client 实例内的 `consensus` 结果：`force=false`、本地最新观察的 agent.md ETag 未变且名片未标记 missing。不设 TTL，每个新实例首次检查目标 AID 都查询 NS；其它状态或显式 force 均重新查询。
+- 公共查询不直接读取 Storage 的 `owner.md`，返回值去除 `owner_md` 和 `owner_md_sha256`；Ownership 管理流程继续使用各自文件操作。
+- `AIDStore.resolve` 按需委托当前 Client 检查共识，不再用持久快照跳过新实例首查；保留与展示名片的 ETag／正文摘要一致性检查。
+
+### agent.md 普通上传
+
+- 上传及恢复依据新鲜 NS ownership 锁判断：未锁定时允许首次声明或修改 owner／ownership；已锁定时完整保留 `owner`、`ownership`、`ownership_proof`、`ownership_release`，允许更新正文及其它合法字段。
+- 保留上传 schema、验签、当前主体身份、原 ETag CAS 和 pending 原签名字节／关系快照；group/org 继续由对应服务核验生命周期 owner 和实体证书。
+- 配套 NS 允许普通上传保存未配对的单边声明并标记 pending／unlocked，不因此授予 Owner 权限；普通 PUT 与 Ownership Check／Stage 入口保持区分。
+
+### 版本与验证
+
+- 包配置、锁文件、运行时及相关测试版本引用统一为 `0.5.29`。四端入口、缓存限制、服务依赖和已有定向验证见 [parity 0.5.29](../python/CHANGES_FOR_PARITY.md#v0529--共识查询缓存与普通上传未发布)。
+
+## 0.5.28 — 未发布
+
+### 新功能
+
+#### 分类控制消息
+
+- 按服务端协商的 `message_classes_v1` 区分 `normal`、`control` 和 `sdk_control`，控制流按类别、peer／群及持久／volatile 范围隔离游标；加密保护头绑定类别、SDK 控制协议和版本，SDK 控制正文只供内部消费，不进入应用事件、History 或发送正文回包。
+- 内部消费或应用交付完成后，先持久保存游标和待确认 ACK，再按扫描证明 ACK；响应丢失恢复原 ACK，证明失效时重新扫描续证，身份或连接换代阻止旧页面提交。
+
+#### Owner 名片变更通知
+
+- 上传提交与通知 outbox 同锁保存，以固定 `message_id` 重试加密的 `aun.agent_md.changed` v1 SDK 控制消息；同目录的 AIDStore 提交可唤醒通知。Owner 下载验签并 fresh 核对当前归属与 ETag 后，可靠发布 `agent_md_changed`，支持离线／重启和 group／org 清单恢复，应用处理失败保留原事件。
+
+#### 风控响应
+
+- 在可信 WSS 握手协商风控能力及 `ECDSA-P256-SHA256` 签名键后，验证目标与签名：SEC1 未压缩公钥 65 字节，UTF-8 canonical JSON 去掉 `signature` 后做 SHA-256 并保留合法 Unicode 字符，P1363 `r || s` 签名 64 字节，接受合法 high-S／low-S，公钥与签名均为无填充 base64url。持久保存状态并发送 `gateway.risk_ack`；公开 `riskState`／`risk_state_changed`，原始指令内部消费。旧 Ed25519 风控键不再接受，仅含旧键的本地记录恢复返回 `risk_state_unavailable`，不自动迁移。
+- RPC 与 HTTP 在网络发送前执行风险门控，普通名片与 Ownership HTTP 使用独立 scope；HTTP 429 的等待时间仅限制同服务路由，4029 断开按服务端等待时间延后重连。服务端控制和限流策略依赖配套服务能力。
+
+### 修复
+
+#### agent.md 上传与下载校验
+
+- 上传候选显式执行上传 schema 校验：除 `human`、`group`／`org` 外，必须同时包含 `owner` 和有效的 Ownership 声明；不完整的历史 `ownership_proof` 及非法关系整数字段在上传前拒绝。
+- `human` 在上传和下载时均禁止包含 `owner`、`ownership`、`ownership_proof` 或 `ownership_release` 字段。
+- `group`／`org` 的上传 schema 仅检查 `owner` 字段存在；实际归属关系继续由 group／org 专属服务确认，不通过通用 Ownership 2.1 声明建立共识。
+- 普通 AID 下载允许没有 Ownership 声明，保留已有历史兼容和签名校验；现代实体名片继续执行原有读取校验，不将上传要求套用于下载。
+
+#### Ownership 共识刷新
+
+- 公开 `checkOwnershipConsensus()` 首轮结果不是 `consensus` 时，调用既有 fresh 入口，以 `Cache-Control: no-cache` 完整重查一次并返回第二轮结果；覆盖 `released`、`unbound`、`single_sided`、`invalid`、`unavailable` 和 `not_applicable`。首轮已达共识时保持原查询行为，第二轮仍未达共识时不循环重查。
+
+### 测试与版本
+
+- 补充分类控制流、Owner 通知恢复、风控响应、上传／下载 schema 和实际 HTTP 请求头回归；共识查询覆盖全部非共识状态、`single_sided` 刷新为 `consensus`、共识不额外刷新及单次重查上限。
+- 包配置、锁文件、运行时 `VERSION`、认证元数据及消息信封的 `sdk_version` 统一为 `0.5.28`；四端差异与验证范围见 [parity 0.5.28](../python/CHANGES_FOR_PARITY.md#v0528--校验控制消息与风控未发布)。
+
 ## 0.5.27 — 未发布
 
 > 基线：`0.5.25` 源码快照 `133067c80`；本节整理截至 2026-10-29 的 Node.js SDK 实际代码增量及当前工作区变更。

package/_packed_docs/CHANGELOG.md

@@ -6,6 +6,61 @@
 
 ---
 
+## 0.5.29 — 未发布
+
+### Ownership 共识查询
+
+- `checkOwnershipConsensus(subAid?, force=false)` 改为在缓存未命中时直接向 NS 查询一次，携带 `X-AUN-Ownership-Check: 1` 和 `Cache-Control: no-cache`；替代 0.5.28 的首轮查询加非一致重查。
+- 仅复用同一 Client 实例内的 `consensus` 结果：`force=false`、本地最新观察的 agent.md ETag 未变且名片未标记 missing。不设 TTL，每个新实例首次检查目标 AID 都查询 NS；其它状态或显式 force 均重新查询。
+- 公共查询不直接读取 Storage 的 `owner.md`，返回值去除 `owner_md` 和 `owner_md_sha256`；Ownership 管理流程继续使用各自文件操作。
+- `AIDStore.resolve` 按需委托当前 Client 检查共识，不再用持久快照跳过新实例首查；保留与展示名片的 ETag／正文摘要一致性检查。
+
+### agent.md 普通上传
+
+- 上传及恢复依据新鲜 NS ownership 锁判断：未锁定时允许首次声明或修改 owner／ownership；已锁定时完整保留 `owner`、`ownership`、`ownership_proof`、`ownership_release`，允许更新正文及其它合法字段。
+- 保留上传 schema、验签、当前主体身份、原 ETag CAS 和 pending 原签名字节／关系快照；group/org 继续由对应服务核验生命周期 owner 和实体证书。
+- 配套 NS 允许普通上传保存未配对的单边声明并标记 pending／unlocked，不因此授予 Owner 权限；普通 PUT 与 Ownership Check／Stage 入口保持区分。
+
+### 版本与验证
+
+- 包配置、锁文件、运行时及相关测试版本引用统一为 `0.5.29`。四端入口、缓存限制、服务依赖和已有定向验证见 [parity 0.5.29](../python/CHANGES_FOR_PARITY.md#v0529--共识查询缓存与普通上传未发布)。
+
+## 0.5.28 — 未发布
+
+### 新功能
+
+#### 分类控制消息
+
+- 按服务端协商的 `message_classes_v1` 区分 `normal`、`control` 和 `sdk_control`，控制流按类别、peer／群及持久／volatile 范围隔离游标；加密保护头绑定类别、SDK 控制协议和版本，SDK 控制正文只供内部消费，不进入应用事件、History 或发送正文回包。
+- 内部消费或应用交付完成后，先持久保存游标和待确认 ACK，再按扫描证明 ACK；响应丢失恢复原 ACK，证明失效时重新扫描续证，身份或连接换代阻止旧页面提交。
+
+#### Owner 名片变更通知
+
+- 上传提交与通知 outbox 同锁保存，以固定 `message_id` 重试加密的 `aun.agent_md.changed` v1 SDK 控制消息；同目录的 AIDStore 提交可唤醒通知。Owner 下载验签并 fresh 核对当前归属与 ETag 后，可靠发布 `agent_md_changed`，支持离线／重启和 group／org 清单恢复，应用处理失败保留原事件。
+
+#### 风控响应
+
+- 在可信 WSS 握手协商风控能力及 `ECDSA-P256-SHA256` 签名键后，验证目标与签名：SEC1 未压缩公钥 65 字节，UTF-8 canonical JSON 去掉 `signature` 后做 SHA-256 并保留合法 Unicode 字符，P1363 `r || s` 签名 64 字节，接受合法 high-S／low-S，公钥与签名均为无填充 base64url。持久保存状态并发送 `gateway.risk_ack`；公开 `riskState`／`risk_state_changed`，原始指令内部消费。旧 Ed25519 风控键不再接受，仅含旧键的本地记录恢复返回 `risk_state_unavailable`，不自动迁移。
+- RPC 与 HTTP 在网络发送前执行风险门控，普通名片与 Ownership HTTP 使用独立 scope；HTTP 429 的等待时间仅限制同服务路由，4029 断开按服务端等待时间延后重连。服务端控制和限流策略依赖配套服务能力。
+
+### 修复
+
+#### agent.md 上传与下载校验
+
+- 上传候选显式执行上传 schema 校验：除 `human`、`group`／`org` 外，必须同时包含 `owner` 和有效的 Ownership 声明；不完整的历史 `ownership_proof` 及非法关系整数字段在上传前拒绝。
+- `human` 在上传和下载时均禁止包含 `owner`、`ownership`、`ownership_proof` 或 `ownership_release` 字段。
+- `group`／`org` 的上传 schema 仅检查 `owner` 字段存在；实际归属关系继续由 group／org 专属服务确认，不通过通用 Ownership 2.1 声明建立共识。
+- 普通 AID 下载允许没有 Ownership 声明，保留已有历史兼容和签名校验；现代实体名片继续执行原有读取校验，不将上传要求套用于下载。
+
+#### Ownership 共识刷新
+
+- 公开 `checkOwnershipConsensus()` 首轮结果不是 `consensus` 时，调用既有 fresh 入口，以 `Cache-Control: no-cache` 完整重查一次并返回第二轮结果；覆盖 `released`、`unbound`、`single_sided`、`invalid`、`unavailable` 和 `not_applicable`。首轮已达共识时保持原查询行为，第二轮仍未达共识时不循环重查。
+
+### 测试与版本
+
+- 补充分类控制流、Owner 通知恢复、风控响应、上传／下载 schema 和实际 HTTP 请求头回归；共识查询覆盖全部非共识状态、`single_sided` 刷新为 `consensus`、共识不额外刷新及单次重查上限。
+- 包配置、锁文件、运行时 `VERSION`、认证元数据及消息信封的 `sdk_version` 统一为 `0.5.28`；四端差异与验证范围见 [parity 0.5.28](../python/CHANGES_FOR_PARITY.md#v0528--校验控制消息与风控未发布)。
+
 ## 0.5.27 — 未发布
 
 > 基线：`0.5.25` 源码快照 `133067c80`；本节整理截至 2026-10-29 的 Node.js SDK 实际代码增量及当前工作区变更。

package/_packed_docs/INDEX.md

@@ -23,6 +23,8 @@
 | [AUNClient 门面化与 Runtime 状态迁移细化方案](design/AUNClient门面化与Runtime状态迁移细化方案.md) | AUNClient 完全门面化、ClientRuntime 单一状态源和四端分批迁移步骤 |
 | [消息同步与历史拉取改造方案](消息同步与历史拉取改造方案.md) | Forward A/T/H 窗口、Group 成员可见性下界、Tail/History RPC、页内唯一有序发布、应用层跨页幂等排序、三 Pull Gate、缺 sender IK 有界同步 bootstrap、永久页内 Gap、坏密文推进和跨 SDK 验收门禁 |
 | [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) | 同一 AID 多设备按话题同步已读位置；服务端按 message ID 公共顺序汇总，返回汇总 message ID 及当前设备 seq 映射，支持 P2P/Group、批量和部分会话上报 |
 | [跨设备已读未读详细设计](跨设备已读未读详细设计.md) | RPC、单条/显式空值边界、紧凑状态表、晚到位置持久回填、Group canonical 与权限版本、owner 事件路由及四端补偿 |
 | [跨设备已读未读实施计划](跨设备已读未读实施计划.md) | 按 TDD 分阶段落地服务端、状态缓存与异步批写、Gateway、四端 SDK、单域/E2E/cross-SDK/跨域测试及完成定义 |
@@ -57,6 +59,7 @@
 | [服务端消息通信诊断面板 P0 方案](design/服务端消息通信诊断面板P0方案.md) | aun-console 消息通信页的服务端可观察 P0 诊断面板 |
 | [消息收件箱统一迁移方案](design/消息收件箱统一迁移方案.md) | P2P `message_inbox` 与群消息 `group_inbox` 的统一读模型、后台回填和旧表清理方案 |
 | [AUN 反向代理服务方案与 TDD 实施计划](design/AUN反向代理服务方案与TDD实施计划.md) | AUN Service Proxy、service_proxy 服务模块、SDK service-proxy-client、URL 路由、隧道协议、Web 边界和分阶段 TDD 落地计划 |
+| [agent.md / owner.md 当前权威规范（Ownership 2.1）](protocol/Ownership协议定义2.1.md) | 当前文件结构、签名、Ownership 2.1 关系与 owner 锁；[agent.md Schema](agent.md/SCHEMA.md) 是 legacy 2.0，[协议内 Schema](protocol/agent.md/SCHEMA.md) 是 legacy 1.0 |
 | [agent.md Schema（legacy 2.0）](agent.md/SCHEMA.md) | 历史 Ownership 2.0 双文件声明与撤销格式；当前 2.1 文件、关系版本和 owner 锁见协议定义 2.1 |
 | [远程 agent.md 缓存与 ETag 透传方案](agent.md/远程agent.md缓存与etag透传方案.md) | 远程 agent.md per-AID 本地文件/IndexedDB 缓存、Gateway `_meta.agent_md_etags` 角色、消息信封 ETag 和注入节流方案 |
 | [agent.md Schema 与签发/验签流程澄清记录](agent.md/working/agent.md-schema与签发验签流程澄清.md) | working 讨论记录：当前 Schema、内嵌签名实现、三字段关系声明与 self-owner 单签、公开 proof 独立验签、owner 关系写入经 Auth 验证及冲突仲裁、事实摘要与 nonce/编排上下文分层、Auth 登记见证与回执、证书/关系状态分离，以及 `unbound`/`unusable`、状态 pull/push、TTL、type-change 和 Storage 权限的最新决策 |
@@ -67,7 +70,7 @@
 | [SDK 文档索引](sdk/INDEX.md) | SDK 使用手册、P2P peer 能力/游标、完整 pending peers/快照、need_render、50k 内存去重/应用持久幂等、四端门面、RPC、E2EE、Storage VFS、Group FS 和 Collab 的子索引 |
 | [SDK 查阅指南](sdk/AUN_DOCS_GUIDE.md) | SDK 文档按行区间渐进式查阅方法 |
 | [AUN SDK 0.5.6 更新日志](sdk/CHANGELOG-0.5.6.md) | 以 0.5.5 为基线的四 SDK 发布汇总；覆盖首次签名者回源、下载提交前验签、消息窗口、显式 change-seed 和语言能力边界 |
-| [四 SDK 版本对齐变更清单](../python/CHANGES_FOR_PARITY.md)；[0.5.27 应用指南](sdk/0.5.27-SDK应用集成指南.md)、[开发与移植指南](sdk/0.5.27-SDK开发与移植指南.md) | 以 Python 实现为主线的 v0.3.3 至 v0.5.27 跨语言对齐清单；0.5.27 对照 0.5.25 源码，覆盖语义凭证、消息证据、状态／Usage 恢复、Gateway 迁移、组织及 CLI，区分四端落点和已有验证范围 |
+| [四 SDK 版本对齐变更清单](../python/CHANGES_FOR_PARITY.md)；[0.5.29 应用指南](sdk/0.5.29-SDK应用集成指南.md)、[开发与移植指南](sdk/0.5.29-SDK开发与移植指南.md)、[共识与上传对齐](../python/CHANGES_FOR_PARITY.md#v0529--共识查询缓存与普通上传未发布)；[0.5.28 应用指南](sdk/0.5.28-SDK应用集成指南.md)、[开发与移植指南](sdk/0.5.28-SDK开发与移植指南.md)；[0.5.27 应用指南](sdk/0.5.27-SDK应用集成指南.md)、[开发与移植指南](sdk/0.5.27-SDK开发与移植指南.md) | v0.3.3 至 v0.5.29 跨语言对齐清单；当前指南覆盖应用接入、NS 单次查询、无 TTL 的 ETag 缓存、resolve、上传锁／恢复和四端移植；旧版记录保留 |
 | [AUN CLI 手册](cli/CLI手册.md) | Python CLI入口、profile及主要命令；credential 23命令、组织入口、文件／上下文、原字节和错误退出 |
 | [AUN CLI 设计文档](cli/AUN-CLI设计文档.md) | `python/src/aun_cli` 当前实现架构、命令注册面、配置解析、SDK 桥接和实现边界 |
 | [凭证与组织服务 CLI 开发与使用指南](cli/凭证与组织服务CLI开发与使用指南.md) | 流程图＋TS示例；真实CLI调用、凭证全流程、组织材料衔接与SDK胶水开发 |
@@ -111,6 +114,7 @@
 - AUNClient 完全门面化、Runtime 状态归属、状态写入收口和四端分批实施 → [AUNClient 门面化与 Runtime 状态迁移细化方案](design/AUNClient门面化与Runtime状态迁移细化方案.md)
 - 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)
 - 同一 AID 多设备按会话话题同步已读位置、message ID 公共顺序汇总、当前设备 seq 映射、P2P/Group 批量上报与查询 → [跨设备已读未读方案](跨设备已读未读方案.md)
 - 跨设备已读未读 RPC、状态表、请求级提交、混合域部分提交、SDK 缓存及本地完成事件契约 → [跨设备已读未读详细设计](跨设备已读未读详细设计.md)
 - 跨设备已读未读 TDD 阶段、状态缓存与批写、测试矩阵、断点续跑、兼容审查和完成定义 → [跨设备已读未读实施计划](跨设备已读未读实施计划.md)
@@ -134,6 +138,7 @@
 - 0.5.24 应用接入、消息持久处理、Ownership 文件验收和两个 local 场景、resolve 与文件缓存、凭证组织和升级 → [应用集成指南](sdk/0.5.24-SDK应用集成指南.md)
 - 0.5.24 SDK 分层、消息提交、Ownership／Stage／CAS、local 身份隔离、缓存新鲜度、跨端差异及 Rust 核查 → [开发与移植指南](sdk/0.5.24-SDK开发与移植指南.md)
 - Python / TS / Go / JS SDK 使用手册，P2P peer 能力、共享 seq/隔离游标、轻量 pending peers/可选整体估计快照、目录/Pull逐页next_pending_seq持续提示/每N次FIFO、peer ACK/slot 公共 S、need_render/页内渲染计数、50k 内存去重/应用持久幂等，以及 Python PushFacade → [SDK 文档索引](sdk/INDEX.md)、[Message RPC](sdk/09-message-rpc-manual.md)、[服务协议](protocol/06-服务协议.md#63-点对点消息-message)
+- SDK 风控能力、内部控制消费、RPC/HTTP 门控、断线等待、旧端兼容、服务端执行与 Console 解封 → [风控响应与 SDK 协同方案](风控响应与SDK协同方案.md)
 - Ownership 2.1 agent.md/owner.md 关系、原格式兼容、普通 agent.md 独立、release 保持当前版本、清理后版本投影为 0／重绑默认 1、响应 Header 只投影校验结果、普通 agent owner 可选及旧 SDK 隔离兼容 → [协议定义 2.1](protocol/Ownership协议定义2.1.md)、[详细设计](sdk/Ownership2.1详细设计.md)
 - Ownership 2.1 应用接入：双向绑定、释放、转移、两个 local 编排、审批和显式重试的 TS 示例／流程图 → [应用集成指南](sdk/Ownership2.1-SDK应用集成指南.md)
 - Ownership 2.1 SDK 移植：文件签验、NS 验收、条件发布、通用消息交付、本地编排和文件 CAS → [开发与移植指南](sdk/Ownership2.1-SDK开发与移植指南.md)
@@ -152,7 +157,8 @@
 - 四 SDK resolve 的 opts/输入输出、frontmatter 全字段与类型、按需 ownership 共识及 owner.md 缓存 → [resolve 规格](sdk/06-API手册.md#resolve-输入与输出)、[连接与认证](sdk/04-连接与认证.md)
 - 按主题和行区间查 SDK 文档 → [SDK 查阅指南](sdk/AUN_DOCS_GUIDE.md)
 - 四 SDK 0.5.6 发布摘要、首次签名者回源、可信缓存提交、消息窗口、语言能力边界 → [AUN SDK 0.5.6 更新日志](sdk/CHANGELOG-0.5.6.md)
-- 四 SDK 0.5.27 相对 0.5.25 源码的语义凭证、消息证据、状态／Usage 恢复、Gateway 迁移、时间容错、组织及 CLI 变更；四端差异与已有验证范围 → [0.5.27 应用指南](sdk/0.5.27-SDK应用集成指南.md)、[开发与移植指南](sdk/0.5.27-SDK开发与移植指南.md)；实现对照见 [四 SDK 版本对齐变更清单](../python/CHANGES_FOR_PARITY.md#v0527--相对于-v0525-基线的变更未发布)
+- 四 SDK 0.5.29 应用接入、共识输入输出、resolve、普通上传及业务服务 → [应用指南](sdk/0.5.29-SDK应用集成指南.md)；查询缓存、并发、上传恢复、NS 配套及四端落点 → [开发与移植指南](sdk/0.5.29-SDK开发与移植指南.md)；增量和已有验证见 [当前 parity](../python/CHANGES_FOR_PARITY.md#v0529--共识查询缓存与普通上传未发布)。接口摘要见 [Python](../python/CHANGELOG.md)、[Go](../go/CHANGELOG.md)、[TS](../ts/CHANGELOG.md)、[JS](../js/CHANGELOG.md) CHANGELOG。
+- 四 SDK 0.5.28 的 agent.md 校验、共识 fresh、分类控制消息、Owner 通知与风控，以及四端差异和验证范围 → [0.5.28 应用指南](sdk/0.5.28-SDK应用集成指南.md)、[开发与移植指南](sdk/0.5.28-SDK开发与移植指南.md)；实现对照见 [历史 parity](../python/CHANGES_FOR_PARITY.md#v0528--校验控制消息与风控未发布)。0.5.28 及更早记录中的公共共识查询以 0.5.29 增量为准。
 - Python CLI 源码位置、安装运行入口、全局选项、profile 配置、身份/消息/群组/Storage/Group FS/Collab/诊断等命令用法 → [AUN CLI 手册](cli/CLI手册.md)
 - Python CLI 当前实现架构、`main.py` 命令注册、`CLISession` SDK 桥接、配置解析和实现边界 → [AUN CLI 设计文档](cli/AUN-CLI设计文档.md)
 - Storage SDK VFS、控制面/数据面分离、下载 ticket / AID Bearer 边界、当前 access token getter、类 Linux 权限、mount/symlink、direct backend 上传下载和服务端分层 → [AUN Storage 架构设计](<aun-fs/AUN Storage架构设计.md>)
@@ -228,6 +234,14 @@
 
 定义 P2P `message.send` 的秒级 `ttl` 语义：`ttl <= 0` 走原持久化路径，正数钳制到 1-3600 秒并进入不写数据库/WAL 的 volatile 通道。方案规定持久/volatile 独立游标、按 device 的内存收件箱、slot 隐藏的 lease/ACK、服务模块数据目录中的递增 epoch 文件、消息调试页的 volatile 计数器与 payload type 分类、重启丢失和多实例/跨域约束，并给出 Python/Go 服务端、四 SDK、单域、cross-SDK、E2E 与双域验收矩阵。
 
+### 控制消息与设备能力协商方案
+
+[控制消息与设备能力协商方案](控制消息与设备能力协商方案.md) 是待实施的跨服务设计：`message_class=sdk_control/control/normal`，优先级依次递减，TTL 沿用 volatile / persistent 语义；Gateway 权威能力、Message / Group 缓存失效与回源、三流 SEQ / ACK、版本往返投影、Owner 加密通知和上线对账。包含改动范围、TDD 顺序、兼容矩阵及真实测试证据边界。
+
+### 风控响应与 SDK 协同方案
+
+[风控响应与 SDK 协同方案](风控响应与SDK协同方案.md) 优先定义待实施的响应闭环：服务端先限制，支持 `risk_test_v1` 的连接协同装闸与回执，未支持端触发风险后断连暂封。规定可信作用域、RPC/托管 HTTP、签名快照与时间/版本、唯一重连、持久处罚和递增规则；Console 展示证据与各入口执行状态，带权限/CAS 解封并防止迟到策略复活。包含四 SDK、跨实例、旧端和受控公网验收；不表示识别算法或机制已上线。
+
 ### 跨设备已读未读方案
 
 定义同一 AID 多设备的业务已读状态模型。P2P `seq` 按设备隔离，设备按应用传入的 `topic_key` 保存最后已读 `message_id`；服务端依据消息公共顺序汇总各设备状态，查询只返回汇总 message ID 及其在当前设备上的 seq 映射。方案覆盖 P2P/Group、AID/话题/Group 过滤查询、单条/批量/部分会话上报、在线变更事件、定向消息边界、四端 SDK 和前端未读数计算。
@@ -422,7 +436,13 @@ Group/Org 作为 sub 时不进入这些通用任务或审批；以其为 sub 误
 
 ### 四 SDK 版本对齐变更清单
 
-0.5.27 [应用指南](sdk/0.5.27-SDK应用集成指南.md)：身份／连接／消息迁移 §2—§3 L30-133，结构化 §4 L134-192／语义 §5 L193-349，组织与缓存 §6—§7 L350-388，升级 §8 L389-408；[开发与移植指南](sdk/0.5.27-SDK开发与移植指南.md)：字节／签名 §2 L38-84，结构化 §3 L85-123／语义 §4 L124-297，组织 §5 L298-334，迁移交付 §6 L335-383，平台与回归 §7—§8 L384-410。 `python/CHANGES_FOR_PARITY.md` 以 Python SDK 实现为主线记录 Go / TypeScript / JavaScript 对齐要求。0.5.27 L15-132 统一对照 0.5.25 源码提交，覆盖结构化／语义凭证、消息证据、online／bounded、Usage 持久恢复、Gateway 迁移、时间容错、组织和 CLI；列出各端实现落点、存储差异及已有验证范围。0.5.26 仅记 TypeScript 根证书打包修正；0.5.25 及更早章节保留原基线和执行记录。
+0.5.29 [应用指南](sdk/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；[开发与移植指南](sdk/0.5.29-SDK开发与移植指南.md)：契约 §1—§2 L5-63、缓存与 resolve §3—§4 L64-94、上传恢复 §5 L95-123、四端与继承契约 §6—§7 L124-151、核查 §8 L152-164。
+
+当前 [0.5.29 parity](../python/CHANGES_FOR_PARITY.md#v0529--共识查询缓存与普通上传未发布) L15-87：公共入口与 NS 请求 L19-39、无 TTL 的 ETag 缓存及 resolve L40-47、普通上传与恢复 L48-67、NS 配套与定向验证 L68-87。四端 CHANGELOG 提供接口级摘要。
+
+历史 0.5.28 [应用指南](sdk/0.5.28-SDK应用集成指南.md)：身份／消息接入 §2—§3 L18-95、凭证／组织 §4—§5 L96-137、Storage／Ownership §6—§7 L138-186、Owner 通知 §8 L187-201、风控／升级 §9—§10 L202-228；[开发与移植指南](sdk/0.5.28-SDK开发与移植指南.md)：上传／下载 schema §1 L7-36、非一致共识 fresh §2 L37-62、分类控制消息 §3 L63-108、Owner outbox §4 L109-121、风控 §5 L122-134、移植矩阵 §6 L135-146。对应实现及验证边界见 `python/CHANGES_FOR_PARITY.md` 0.5.28 章节 L88-172。0.5.27 及更早版本保留原基线和执行记录。
+
+0.5.27 [应用指南](sdk/0.5.27-SDK应用集成指南.md)：身份／连接／消息迁移 §2—§3 L30-133，结构化 §4 L134-192／语义 §5 L193-349，组织与缓存 §6—§7 L350-388，升级 §8 L389-408；[开发与移植指南](sdk/0.5.27-SDK开发与移植指南.md)：字节／签名 §2 L38-84，结构化 §3 L85-123／语义 §4 L124-297，组织 §5 L298-334，迁移交付 §6 L335-383，平台与回归 §7—§8 L384-410。 `python/CHANGES_FOR_PARITY.md` 以 Python SDK 实现为主线记录 Go / TypeScript / JavaScript 对齐要求。0.5.27 L173-290 统一对照 0.5.25 源码提交，覆盖结构化／语义凭证、消息证据、online／bounded、Usage 持久恢复、Gateway 迁移、时间容错、组织和 CLI；列出各端实现落点、存储差异及已有验证范围。0.5.26 仅记 TypeScript 根证书打包修正；0.5.25 及更早章节保留原基线和执行记录。
 
 ### AUN CLI 手册
 

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-96：根级文档地图。
+- `docs/INDEX.md` L7-103：根级文档地图。
 
 ### Step 2：按主题读根级 Layer 2
 
-- 测试与 E2E：`docs/INDEX.md` L101-121。
-- 服务端 Go 化重构审查：`docs/INDEX.md` L122-125。
-- SDK 使用与协议：`docs/INDEX.md` L126-175。
-- Service Proxy 与服务暴露：`docs/INDEX.md` L176-182。
-- 诊断与可观测性：`docs/INDEX.md` L183-191。
-- E2EE 与跨语言一致性：`docs/INDEX.md` L192-198。
+- 测试与 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。
 
 ### Step 3：需要判断文档价值时读 Layer 3 摘要
 
-- `docs/INDEX.md` L201-481：重点文档摘要。
+- `docs/INDEX.md` L210-502：重点文档摘要。
 
 ### Step 4：再读目标文档章节
 
@@ -82,6 +82,8 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 | A/T/H、Tail/Forward、Group 成员可见性下界、History、缺 sender IK 有界同步 bootstrap、页内唯一有序发布、应用层跨页幂等排序、Pull Gate 与兼容边界 | `docs/消息同步与历史拉取改造方案.md` L7-375 |
 | 消息同步 TDD、Gateway、兼容性和分布式 E2E 门禁 | `docs/消息同步与历史拉取改造方案.md` L434-750 |
 | 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 |
 | 跨设备 P2P/Group 按话题同步已读位置、AID 汇总、设备 seq 映射及补偿完成交付 | `docs/跨设备已读未读方案.md` L1-273 |
 | 跨设备已读未读 RPC、紧凑状态表、公共顺序、请求级提交、混合域部分提交、四端 SDK 缓存和本地完成事件 | `docs/跨设备已读未读详细设计.md` L1-209 |
 | 跨设备已读未读 TDD 阶段、迁移/批写、断点续跑、测试矩阵、历史部署记录和本轮完成定义 | `docs/跨设备已读未读实施计划.md` L1-156 |
@@ -126,7 +128,7 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 | 离线 Push Service 当前发布结论与强制发布门 | `docs/AUN离线推送服务运维与发布指南.md` L5-23 |
 | 离线 Push Service 运行依赖、诊断和告警判断 | `docs/AUN离线推送服务运维与发布指南.md` L25-81 |
 | 离线 Push Service 性能基线、安全边界、隔离 PoC 灰度、回滚和已知限制 | `docs/AUN离线推送服务运维与发布指南.md` L83-141 |
-| group.index 签名索引、`_meta.group_indexes`、CAS 更新和服务端缓存注入 | `docs/design/群索引版本提示与附件引用方案.md` L1-348、`docs/INDEX.md` L65、L174、L319-322 |
+| group.index 签名索引、`_meta.group_indexes`、CAS 更新和服务端缓存注入 | `docs/design/群索引版本提示与附件引用方案.md` L1-348、`docs/INDEX.md` L66、L176、L325-328 |
 | AUN Service Proxy 总体架构、参考项目与边界 | `docs/design/AUN反向代理服务方案与TDD实施计划.md` L3-127 |
 | AUN Service Proxy URL、注册、隧道协议和 Web 边界 | `docs/design/AUN反向代理服务方案与TDD实施计划.md` L129-384 |
 | AUN Service Proxy 服务列表注册、双注册和 wakeup 路由 | `docs/sdk/09-proxy-rpc-manual.md` L1-226、`docs/protocol/06-服务协议.md` L43-204 |
@@ -151,11 +153,13 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 | AID owner 完整设计、Schema 可选性与 human owner 限制、三字段共同声明与 self-owner 单签、Phase 0 已确认的 P0-A01 至 P0-A12（canonical JSON、可见分号域分隔符、签名封套、proof-only/registered、Auth receipt、TTL、证书状态与关系 operation 分离、legacy/绑定中基本登录通信及按应用场景降级、旧 AID `aid_bind` 与新建 `aid_register` 的 RPC/Facade 边界、active/pending 唯一性检查、创建/绑定/换 owner/解绑、`unbound`/`unusable`、服务端/四端 SDK 改动和分阶段验收；剩余为正式 wire/RPC 文档与跨端向量落稿 | `docs/agent.md/working/AID类型-owner关系完整设计与实施计划.md` |
 | 本轮 owner 关系实施及本地 Docker、单域、cross-SDK、双域 federation 回归中发现的非任务失败、根因、修复与验证 | `docs/agent.md/working/本地Docker测试Bug清单.md` |
 | SDK API、RPC、E2EE、Storage VFS、Group FS、Collab GC/reflog/reset 使用细节 | `docs/sdk/AUN_DOCS_GUIDE.md` |
-| 四 SDK resolve opts、完整输入输出、frontmatter 字段/类型、按需 ownership 共识及 owner.md 快照与 TTL | `docs/sdk/06-API手册.md` L86-203；`docs/sdk/04-连接与认证.md` L233-243 |
+| 四 SDK resolve opts、frontmatter 字段／类型；当前 ownership 输出与无 TTL 缓存 | 基础解析见 `docs/sdk/06-API手册.md` L86-203、`docs/sdk/04-连接与认证.md` L233-243；当前共识变更见 `python/CHANGES_FOR_PARITY.md` L19-47 |
 | 四 SDK Storage / Group FS 默认读缓存、省略策略或 TTL 默认 60 秒、显式限制、SHA 无正文免计次与 owner.md 普通/权威读取 | `docs/sdk/09-storage-rpc-manual.md` L129-170；`docs/sdk/06-API手册.md` L497-510；`docs/sdk/09-group-rpc-manual.md` L1586-1620 |
 | 四 SDK 当前 access token getter、缓存快照语义和外部 HTTP 数据面下载凭据生命周期 | `docs/sdk/04-连接与认证.md` L96-125、`docs/sdk/06-API手册.md` L327-346、`docs/sdk/09-storage-rpc-manual.md` L690-734、`docs/sdk/09-group-rpc-manual.md` L1612-1618、`docs/aun-fs/AUN Storage架构设计.md` L153-166 |
 | 四 SDK 0.5.6 发布摘要、验签缓存、消息窗口与语言能力边界 | `docs/sdk/CHANGELOG-0.5.6.md` L1-73 |
-| 四 SDK 0.5.27 对照 0.5.25 源码的凭证、消息证据、状态／Usage、Gateway 迁移、时间容错、组织与 CLI；0.5.26 仅为 TS 根证书打包修正 | `docs/sdk/0.5.27-SDK应用集成指南.md`：身份连接／消息 L30-133、结构化 L134-192、语义 L193-349、组织缓存 L350-388、升级 L389-408；`docs/sdk/0.5.27-SDK开发与移植指南.md`：字节 L38-84、结构化 L85-123、语义 L124-297、组织 L298-334、迁移 L335-383、平台回归 L384-410；`python/CHANGES_FOR_PARITY.md` 当前 L15-132；历史 0.5.25 L133-201、0.5.24 L202-338、0.5.22 L339-496，读缓存块⑦ L424-464／版本测试块⑧ L465-496 |
+| 四 SDK 0.5.29 应用接入、共识输入输出、resolve、上传锁与恢复、四端移植 | [应用指南](sdk/0.5.29-SDK应用集成指南.md)：接入 L5-54、共识 L55-80、resolve L81-104、上传管理 L105-145、缓存／业务 L146-167、升级 L168-180；[开发与移植指南](sdk/0.5.29-SDK开发与移植指南.md)：契约 L5-63、缓存／resolve L64-94、上传恢复 L95-123、四端／继承 L124-151、核查 L152-164；parity 当前 L15-87 |
+| 历史 0.5.28 agent.md 校验、共识 fresh、分类控制消息、Owner 通知与风控 | `docs/sdk/0.5.28-SDK应用集成指南.md`：接入／消息 L5-95、凭证／组织 L96-137、Storage／Ownership L138-186、通知 L187-201、风控／升级 L202-228；`docs/sdk/0.5.28-SDK开发与移植指南.md`：校验 L7-36、共识 L37-62、wire L63-108、outbox L109-121、风控 L122-134、移植 L135-146；parity 历史 L88-172，公共共识规则以 0.5.29 为准 |
+| 四 SDK 0.5.27 对照 0.5.25 源码的凭证、消息证据、状态／Usage、Gateway 迁移、时间容错、组织与 CLI；0.5.26 仅为 TS 根证书打包修正 | `docs/sdk/0.5.27-SDK应用集成指南.md`：身份连接／消息 L30-133、结构化 L134-192、语义 L193-349、组织缓存 L350-388、升级 L389-408；`docs/sdk/0.5.27-SDK开发与移植指南.md`：字节 L38-84、结构化 L85-123、语义 L124-297、组织 L298-334、迁移 L335-383、平台回归 L384-410；`python/CHANGES_FOR_PARITY.md` 历史 0.5.27 L173-290、0.5.25 L291-359、0.5.24 L360-496、0.5.22 L497-654，读缓存块⑦ L582-622／版本测试块⑧ L623-654 |
 | 群 `mention_mode` 提及过滤、Agent 自主行为、SDK group.index facade 和 CAS 冲突处理 | `docs/protocol/10-Group-子协议.md`、`docs/protocol/13-Agent行为规范.md`、`docs/sdk/09-group-rpc-manual.md`、`docs/sdk/07-错误处理.md` |
 | AUN Python CLI 源码位置、安装入口、全局选项、profile 配置和主要命令集 | `docs/cli/CLI手册.md` L3-378 |
 | AUN Python CLI 当前实现架构、命令注册、SDK 桥接和实现边界 | `docs/cli/AUN-CLI设计文档.md` L3-279 |

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

@@ -0,0 +1,228 @@
+# AUN SDK 0.5.28 应用集成指南
+
+本文面向 TypeScript SDK 应用开发者，整理 `@agentunion/fastaun` 0.5.28 未发布工作区的完整接入主线。SDK 实现与适配边界见[0.5.28 SDK 开发与移植指南](0.5.28-SDK开发与移植指南.md)；四端增量和验证边界见 [parity 0.5.28](../../python/CHANGES_FOR_PARITY.md#v0528--校验控制消息与风控未发布)。0.5.27 指南保留为历史版本。
+
+## 1. 版本范围与接入路径
+
+0.5.28 在 0.5.27 应用流程上增加方向区分的 `agent.md` schema 校验、普通共识查询的单次 fresh 复核、分类消息、Owner 名片变更通知和风控响应。该版本尚未发布；应用应按实际安装包和服务端能力验收。
+
+| 范围 | SDK 行为 | 应用职责 |
+| --- | --- | --- |
+| 身份与连接 | 管理身份材料、会话、消息拉取与重连 | 持久保存身份目录和 seed；先安装事件处理器再连接 |
+| 消息 | 解密、分类、交付、游标与 ACK 恢复 | 原子持久化业务消息，按业务键幂等处理 |
+| 凭证 | 提供签验、当前状态和请求绑定 API | 注入可信身份、实际请求上下文、业务授权和事务 |
+| Ownership | 校验文件和 NS 共识，支持一次 fresh 重查 | 审批前执行业务授权；按共识结果决定是否共享 |
+| Owner 名片通知 | 持久重试通知、下载验签并可靠发布变更事件 | 将事件接入业务索引或缓存更新，并持久完成应用工作 |
+| 风控 | 执行已验签策略、请求门控、ACK 与状态通知 | 处理受限状态和原请求结果未知，不绕过服务端限制 |
+
+## 2. 身份、信任根与连接
+
+Node.js 运行时要求 Node `>=22.16.0`。身份目录、加密 seed、设备和 slot 应在重启后保持稳定；切换应用用户或隔离环境时使用独立目录与 slot。示例使用应用已经安全取得的身份，不在代码中生成或伪造身份材料。
+
+```ts
+import { AIDStore, AUNClient } from '@agentunion/fastaun';
+const store = new AIDStore({ aunPath: process.env.AUN_PATH!,
+  encryptionSeed: process.env.AUN_SEED ?? '', slotId: 'main', verifySsl: true });
+const loaded = store.load(process.env.AUN_AID!);
+if (!loaded.ok) throw new Error(loaded.error.message);
+const signer = loaded.data.aid;
+if (!signer.isPrivateKeyValid()) throw new Error('身份私钥不可用');
+const client = new AUNClient(signer);
+```
+
+文件 store 缺少 SDK 内置根证书时会补入内置根并保留已有本地根。应用自己的额外信任根和证书链仍须按业务信任策略管理。首次注册走 `store.register()`；已有身份在启动时重新加载，不应因普通重连重新创建身份。
+
+### 2.1 先订阅，再连接
+
+为避免积压消息先于应用处理器到达，在连接前注册需要的事件。业务 handler 返回的 Promise 应在业务持久化成功后完成。
+
+```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);
+client.on('state_change', () => updateConnectionView(client.state));
+await client.connect({ auto_reconnect: true });
+```
+
+SDK 的连接就绪、消息追赶和业务事务是不同状态。界面可以展示连接状态，但业务处理只有在对应应用事务成功后才算完成。
+
+### 2.2 浏览器运行时
+
+浏览器使用 `@agentunion/fastaun-browser`。身份、token 和 checkpoint 保存到 IndexedDB，密码运算由 WebCrypto 完成，HTTPS 证书信任由浏览器控制。浏览器同样应先注册消息处理器再连接；Node 文件 store 的目录和 seed 配置不可直接套用到浏览器。
+
+## 3. 消息交付与分类控制流
+
+普通消息通过 Push 与 Pull 合并收取。SDK 解密并交付 batch 后，等待应用 handler 返回，再提交游标和 ACK。handler 应以接收身份、设备、消息 ID 和业务语义建立幂等键；已读状态由应用在用户实际阅读后单独提交。History 用于浏览历史，不替代实时交付和 ACK。
+
+### 3.1 消息类别
+
+连接协商 `message_classes_v1` 后，消息按类别和 peer／群范围分别拉取、保存游标并恢复：
+
+| 类别 | 用途 | 应用可见性 |
+| --- | --- | --- |
+| `normal` | 普通业务消息 | 交付到普通消息事件或 batch |
+| `control` | 应用自行定义的控制消息 | 仍由应用接收、持久化和处理 |
+| `sdk_control` | SDK 协议消息，例如 `aun.agent_md.changed` | 只交给 SDK 内部处理器，不进入普通消息事件、公开 History 正文或发送正文回包 |
+
+应用发送自己的控制消息时使用加密的 `control` 类别。`sdk_control` 是 SDK 协议保留类别；应用业务 payload 不应冒充 SDK 协议。
+
+```ts
+await client.message.send({ to: peerAid, encrypt: true,
+  message_class: 'control',
+  payload: { type: 'app.control.v1', request_id: operationId } });
+```
+
+若远端尚未协商分类能力，分类控制拉取依赖服务端兼容路径。控制消息的应用业务状态仍由应用保存；SDK 持久化的是分类游标和交付／ACK 恢复责任。
+
+SDK 内部 `sdk_control` 消息会校验解密后受保护头中的类别、协议和版本。内部消费或应用交付成功后才持久推进游标并 ACK；ACK 响应丢失时恢复原 ACK，证明过期时重新扫描续证。身份或连接换代后，旧异步结果不能提交到新会话。
+
+### 3.2 Ownership 审批不是名片变更通知
+
+Ownership 操作通过 `aun.ownership.sdk.v1` 控制协议。应用订阅 `ownership.request`，完成业务授权后调用接受或拒绝 API：
+
+```ts
+client.on('ownership.request', async value => {
+  const request = value as { operation_id: string; sub_aid: string };
+  if (!await authorizeOwnershipRequest(request)) return;
+  await client.acceptOwnershipRequest(request.operation_id);
+  const status = await client.checkOwnershipConsensus(request.sub_aid);
+  if (status.status === 'consensus') await enableSharing(status);
+});
+```
+
+`acceptOwnershipRequest()` 返回的 `completed` 表示本次本地步骤完成，不单独证明 NS 已形成共识。共享或授权决策应以 `checkOwnershipConsensus()` 的结果为准。Owner 审批过程中写入的 `owner.md` 及其 Ownership 控制消息，不等于后文 `owned_agentmd.changed` 的 `agent.md` 上传通知。
+
+## 4. 凭证与业务授权
+
+SDK 提供结构化 `aun-cap/1`、语义／混合 `aun-cap/semantic-1`、消息证据、撤销状态和 Usage 的签验 API。应用负责提供可信证书和当前状态材料，并将认证通道取得的真实主体、目标、方法、参数、request ID、nonce 和业务事实绑定到验证上下文。
+
+示例中的 `loadStructuredTrust`、`authContext`、`packageContext`、`requestParams` 等由应用实现或提供，不是 SDK 全局变量；证书、状态材料和请求参数应取自可信来源及本次真实业务请求。
+
+结构化凭证沿用创建、登记回执验证、状态／撤销查询和完整 `verify()` 流程。TS 普通 `verify()` 为同步操作；需要网络的证书和状态取材应在调用前异步完成。`verifySignature()` 可做签名预检，不能替代包含能力、受众、当前状态及实际请求约束的完整验证。
+
+```ts
+const credential = client.credential.create(draft, signer);
+const context = await loadStructuredTrust(credential);
+const report = client.credential.verify(credential, {
+  ...context, audience: businessServiceAid, subject: signer.aid,
+  ns: 'files', action: 'read', resource: '/reports', params: requestParams });
+```
+
+语义／混合凭证在原件之外还会使用确认元数据、来源链和服务登记。业务需先验证 request 和 credential package，再按 `online` 或 `bounded` 状态策略复核实际调用。消息正文证据和附件引用需与原始信封、接收身份及历史签署材料绑定。模型判断、成员／代表授权和最终额度事务属于应用责任；SDK 的 `checked`／`required` 结果不能替代应用的业务后置条件。
+
+```ts
+const packageValue = await client.credential.buildPackage(lineage);
+const request = await client.credential.buildRequest(requestInput);
+const requestReport = await client.credential.verifyRequest(request, authContext);
+const packageReport = await client.credential.verifyPackage(request.grant, packageContext);
+```
+
+语义原件签署、确认、消息证据、撤销和 Usage 的字段合同见[凭证与组织服务应用集成专题](凭证与组织服务SDK应用集成指南.md)及[凭证与组织服务开发移植专题](凭证与组织服务SDK开发与移植指南.md)。
+
+## 5. 组织成员与实体身份
+
+组织和群使用各自的实体生命周期，不以普通 agent 的 Ownership 双文件流程代替实体 owner 确认。组织创建和转让使用 SDK 当前调用取得的确认结果、owner 和实体证书；续办应沿原 checkpoint 恢复，不从旧身份材料重造新操作。
+
+```ts
+const organization = await client.createOrg({ org_id: orgAid,
+  name: organizationName }, { aidStore: store });
+const query = client.org.prepareRequest('org.member.get', {
+  org_id: orgAid, member_aid: signer.aid,
+}, orgServiceAid, signer);
+const member = await client.org.member.get(query);
+```
+
+申请、邀请、成员 CAP、代表调用、冻结／退出与 owner 转让仍须由应用验证实际 actor、成员关系、凭证能力和业务请求。Group／Org 名片的 owner 关系由对应服务权威确认，不能从 frontmatter 的 `owner` 字段单独推断共享关系。
+
+## 6. Storage 与本地解析缓存
+
+普通 Storage／Group FS 读取可使用 SDK 的读缓存；读取调用传 `noCache: true` 时绕过有效缓存并请求服务端校验，但返回结果仍可能更新缓存，这不是 no-store。Ownership 的 owner.md 共识读取使用权威 Storage 读取，由 SDK 核对 `head_object` 的摘要和 revision 后决定是否复用已验正文。
+
+```ts
+const object = await client.storage.lowlevel.getObject({ owner: signer.aid,
+  objectKey: objectKey, noCache: true });
+```
+
+`AIDStore.resolve(aid, { ownership })` 同时解析 peer 身份、名片和可选的 Ownership 快照。快照可在 agent.md 的 AID、ETag 和正文摘要匹配时复用；`forceRefresh` 本身不保证绕过 Ownership 快照。确需绕过该快照时，可使用已存在的 `ownershipTtlMs: 0` 选项。独立获取当前共识时，优先调用公开 `client.checkOwnershipConsensus(aid)`。
+
+## 7. agent.md 上传、下载与 Ownership 共识
+
+### 7.1 上传和读取规则
+
+上传和下载使用不同 schema 入口。上传前除 schema 外，SDK 仍检查正文格式、AID、签名和证书；读路径允许普通 agent 名片缺少关系声明，并保留历史读取兼容。
+
+| 名片类型 | 上传要求 | 下载要求 |
+| --- | --- | --- |
+| 普通非 human、非 group/org | 必须有 `owner` 和有效 Ownership 声明；适用的旧 proof 也须含完整必要签名材料 | 可以没有声明；出现关系材料时仍按对应格式与签名路径检查 |
+| `human` | 禁止出现 `owner`、`ownership`、`ownership_proof` 或 `ownership_release` | 同样禁止这些字段，包括空值 |
+| `group`／`org` | 通用上传 schema 仅要求 `owner` 字段存在；实际 owner 关系由实体服务确认 | 保留实体签名、证书指纹和历史兼容校验 |
+
+普通 agent 的声明不单独证明共享共识。Group／Org 通过生命周期和对应服务确认实际 owner 关系；不要用普通 Ownership statement 为实体名片推导关系。
+
+```ts
+const signed = signer.signAgentMd(validFrontmatter).data.signed;
+const uploaded = await store.uploadAgentMd(signer.aid, signed);
+if (!uploaded.ok) throw new Error(uploaded.error.message);
+```
+
+SDK 和 NS 上传入口都按 `human`、普通非 human agent、`group`／`org` 分支。NS 的实体路径除 schema 外，还核验权威实体类型、当前 owner、实体证书和上传者授权；schema 分支只要求 `owner` 字段存在，不等于服务端只检查该字段。普通上传候选须满足上述声明要求；`human` 不能通过增加空字段绕过限制。Group／Org 使用实体生命周期提供的 owner 和证书上下文上传。
+
+普通 agent 下载允许名片没有 Ownership 声明；下载成功只说明对应读取及名片校验通过，不代表 Ownership 关系已达成共识。声明存在时仍按对应格式与签名路径检查。
+
+### 7.2 绑定和状态查询
+
+普通 Ownership 2.1 以 `agent.md`、`owner.md` 和 NS 当前投影共同验收。`bindOwneraid()`／`bindSubaid()` 发起操作并返回当次任务结果；`acceptOwnershipRequest()` 执行已授权请求。`OwnershipTaskResult.status === 'completed'` 仅表示这次本地动作和通知步骤结束，最终关系仍要查看共识。
+
+```ts
+const task = await client.bindOwneraid(ownerAid);
+const status = await client.checkOwnershipConsensus(signer.aid);
+if (status.status === 'consensus') await enableSharing(status);
+```
+
+公开 `checkOwnershipConsensus()` 没有 `fresh` 参数。SDK 先完成普通查询的完整文件／签名／Storage 核验；首轮 `consensus` 直接返回，首轮任何非 `consensus` 状态会再调用既有 fresh 路径一次，NS 请求带 `Cache-Control: no-cache`，再按既有规则核验 NS 投影和 Ownership 文件，返回第二轮结果。pending 投影复核时，NS 会读取 `owner.md` 并尝试晋升；SDK 仍完整验证相关文件、签名和共识结果，不能将 pending 状态本身视为共识。第二轮仍非一致时原样返回，不递归、不轮询。应用无需通过重签名、重复绑定或重复审批来刷新状态；该请求头不表示 NS 服务缓存或 Storage 缓存都被强制绕过。
+
+`checkOwnershipConsensus()` 覆盖 `consensus`、`released`、`unbound`、`single_sided`、`invalid`、`unavailable` 和 `not_applicable`。对于 `group`／`org`，`not_applicable` 表示应使用相应实体生命周期查询，而非普通 agent 的双文件共识。
+
+## 8. Owner agent.md 上传变更事件
+
+上传成功后，SDK 将对应的通知待办和名片提交状态一起持久保存，以固定 `message_id` 发送加密 `aun.agent_md.changed` v1 `sdk_control` 消息。发送前会重新确认当前归属；如果身份变化或关系已不匹配，不会把通知续发给旧 Owner。发送失败保留本次通知记录，不自动重试，也不影响已成功的上传结果。
+
+Owner 收到内部控制消息后，SDK 将其作为取证触发信号：下载并验签名片、核对当前 owner 关系及 ETag，通过后再生成 `owned_agentmd.changed` 应用事件。应用事件包含被管理 AID、ETag 和事件 ID，不直接把原始控制封套暴露给应用。应用 handler 应完成自己的持久更新后再 resolve；若 handler 失败，SDK 保留该事件，后续仅在收到对应目标的通知时再次尝试交付。SDK 不通过连接、重连或定时任务恢复通知待办；该事件是 `agent.md` 更新通知，不是 owner.md 审批回执。
+
+```ts
+client.on('owned_agentmd.changed', async value => {
+  const event = value as { aid: string; etag: string; event_id: string };
+  await refreshApplicationIndex(event.aid, event.etag, event.event_id);
+});
+```
+
+该流程仅由上传操作触发，处理本次提交对应的 AID；SDK 不扫描 AIDs 目录、Storage 的 `sub_aids/` 或群及组织清单，也不执行周期对账。应用仍须按 `event_id` 或 AID／ETag 幂等处理自身业务副作用。不要把 agent.md 更新通知与 Ownership 审批消息、owner.md 上传或共识状态合并为同一个业务事件。
+
+## 9. 风控状态与重试
+
+TypeScript SDK 仅在受验证的 WSS 连接、SSL 校验开启且服务端协商 `risk_test_v1` 与签名键时接入风控状态。SDK 验证 `ECDSA-P256-SHA256` 签名、issuer、AID、device、slot／connection 主体及 revision 后应用策略，并按身份和设备持久状态。连接级策略不作为新的连接状态自动沿用；旧 Ed25519 风控键不再接受，TS／JS 读取仅含旧键的本地风控记录会返回 `risk_state_unavailable`，不会自动迁移。
+
+应用可以读取只读快照 `client.riskState`，也可监听 `risk_state_changed`。状态为 `restricted`、`blocked` 或 `recovered`；SDK 先应用并保存策略，再发送专用 `gateway.risk_ack` 并通知应用。原始风控封套不作为普通应用消息投递。
+
+```ts
+client.on('risk_state_changed', event => updateRiskView(event));
+const currentRisk = client.riskState;
+```
+
+请求 scope 策略在 RPC／HTTP 实际发送前执行门控。普通 agent.md HTTP 与 Ownership HTTP 使用不同 scope；TS 检查 WSS 与 SSL 开关，不额外检查 Gateway 主机与 AID issuer 是否同域。HTTP 429 的 `retry_after_ms` 或 `Retry-After` 只对相同 origin 与 path 建立短期退避；SDK 不替应用重放业务写入。应用应识别首次请求的结果状态，按原业务幂等键安全重试。Gateway 4029 可推迟 SDK 重连。
+
+SDK 的本地门控是协作响应，不能替代服务端限流、封禁和资源准入。配套服务端须提供协商能力、签名风控状态、ACK 接口和相应执行策略；服务能力缺失时，不应假定 SDK 单侧可以建立全局限制。
+
+## 10. 升级与验收
+
+将 TS 运行时和包配置核对到 0.5.28，并保留现有身份目录、seed、设备和 slot。浏览器应用同时核对所安装浏览器包版本。升级后先做类型检查和本地针对性回归，再按实际部署场景验收普通消息、应用 control、SDK control、Ownership 状态、Owner 通知恢复和风控服务协商；测试项存在不代表线上场景已通过。
+
+| SDK | 应用接入差异 |
+| --- | --- |
+| TypeScript | Node 文件 store；语义与结构化 facade 按各自 API；`riskState` 提供只读快照 |
+| JavaScript | `@agentunion/fastaun-browser`；IndexedDB／WebCrypto；`riskState` 提供只读快照 |
+| Python | async RPC 和签验；公开 `get_risk_state()` |
+| Go | `context`／`error`；`RiskState()` 快照 |
+
+跨端字段和服务依赖见 [parity 0.5.28](../../python/CHANGES_FOR_PARITY.md#v0528--校验控制消息与风控未发布)。Ownership、控制消息和风控能力均须与服务端版本配套；本指南不声称 SDK 已发布、服务已部署或线上验收已通过。使用完毕调用 `await client.close()`；仍要复用同一 client 时可先 `await client.disconnect()` 后按应用生命周期重连。