@agentunion/fastaun 0.5.34 → 0.5.36

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

@@ -0,0 +1,130 @@
+# 0.5.36 SDK 应用集成指南
+
+本文面向从 **0.5.35** 升级到目标 **0.5.36** 的应用，依据截至 2026-11-12 的四 SDK 工作区源码整理，比较基线为 `80cf7cf49`。源码版本不代表安装包、Go tag 或配套服务已发布。
+
+首次接入先读 [快速开始](01-快速开始.md)、[连接与认证](04-连接与认证.md)和 [API 手册](06-API手册.md)。实现契约见 [本版开发与移植指南](0.5.36-SDK开发与移植指南.md)，源码差异与已有验证见 [parity 0.5.36](../../python/CHANGES_FOR_PARITY.md#v0536)。[0.5.35 应用指南](0.5.35-SDK应用集成指南.md)保留通配订阅、发布者过滤、后台 ACK、Echo 和 Mail 接线；其中事件大小、共识缓存及 UDP 行为以本版说明为准。
+
+## 1. 升级范围与支持边界
+
+| 本版变化 | Python | Node TypeScript | Browser JavaScript | Go |
+| --- | --- | --- | --- | --- |
+| 取消事件独立 64 KiB 检查，提高默认字节突发额度 | 支持 | 支持 | 支持 | 支持 |
+| check／resolve 复用持久共识，观察 Owner 摘要失效 | 支持 | 支持 | 支持；异步存储 | 支持 |
+| 历史 Ownership 验签接受 verify_only，新签仍限 active_signing | 支持 | 支持 | 支持 | 支持 |
+| UDP 动态心跳周期及租约恢复调整 | 支持 | 支持 | 无原生 UDP | 支持 |
+| 待处理 Pull／目录工作阻止入睡的本版补强 | 支持 | 沿用已有检查 | 不适用 | 支持 |
+| 语言专属修复 | UDP 阶段诊断与公网测试入口 | 群 inline 待 ACK、多余 Pull／ACK | 不包含 Node 专属交付修复 | 组织凭据续期复制身份快照 |
+
+四 SDK 的代码、配置及相关测试版本统一为 `0.5.36`。配套服务继续按**单实例**支持，Redis 缓存不构成服务多副本一致性承诺。独立 Mail 的整体验收边界沿用 0.5.35，核心 IM 接入不要求启用 Mail；Rust 不在本次四 SDK 文档的修改或验收范围。
+
+## 2. EventService：事件沿用普通消息大小边界
+
+### 2.1 取消的是事件额外上限
+
+发布端、Bus 受理端及订阅接收端不再执行独立的 64 KiB 检查，旧 `max_event_bytes`／`event_bytes` 配置不再参与单事件大小判断。事件继续走原有 `sdk_control`／`aun.pubsub/1` 通道，授权和调用方式不变。
+
+网络发送沿用 RPC／`message.send` 的完整 WebSocket 报文上限 **1,000,000 字节**，为十进制值。JSON、事件控制字段、接收目标和 E2EE 信封都占用预算，不能将其当作可发送的事件正文长度；中文、转义及加密也会改变实际编码大小。
+
+升级需要覆盖实际链路上的发布者、Bus 和订阅者。链路中仍使用旧 SDK 的节点可能继续拒绝超过 64 KiB 的事件，单独升级发布端不能保证完整投递。
+
+### 2.2 突发额度、持续速率与队列分别生效
+
+| 边界 | 当前行为 | 应用影响 |
+| --- | --- | --- |
+| SDKChannel／事件接收默认字节突发额度 | `1_000_000` 字节 | 允许容纳普通报文上限范围内的一次突发，按完整序列化字节扣费 |
+| SDKChannel 默认持续速率 | 40 次／秒、262,144 字节／秒；调用突发 4 次 | 大事件可能消耗大部分字节令牌，后续发送仍需等待补充 |
+| 单条超过令牌桶突发额度 | 返回 `MESSAGE_TOO_LARGE`，不允许透支 | 自定义更小额度仍可能阻止大事件；本版默认额度已提高 |
+| 发布、接收和 Bus fanout 队列 | 保留数量、总字节和 TTL 约束 | 容量不足仍可能等待、`OVERLOADED` 或到期 |
+
+Python Bus 全局及单发布者发送字节突发额度也提高至 `1_000_000`，SDKChannel 使用紧凑 JSON 的 UTF-8 字节计费。取消单事件额外检查不会取消总容量、TTL、去重、公平调度或背压。
+
+事件授权、订阅过滤与恢复方式继续参考 [事件应用集成专题](AUN事件发布订阅应用集成指南.md)；该专题中的历史 64 KiB 约束由本版规则替代。
+
+## 3. Ownership：复用共识，变化后重新校验
+
+### 3.1 check 和 resolve 共享持久材料
+
+| SDK | 直接查询 | resolve 中启用共识查询 |
+| --- | --- | --- |
+| Python | `await client.check_ownership_consensus(sub_aid)` | `AIDStore.resolve` 的 `ownership` 选项传入查询客户端 |
+| Node TS／Browser JS | `await client.checkOwnershipConsensus(subAid)` | `AIDStore.resolve` 的 `ownership` 选项传入查询客户端 |
+| Go | `client.CheckOwnershipConsensus(ctx, subAID)` | `AIDStore.Resolve` 的 `Ownership` 选项传入查询客户端 |
+
+只有有效的 `status=consensus`、`lock=locked` 结果可以直接复用。SDK 同时保存共识快照、共识时的 agent.md 正文和 Owner 文件摘要；保留原身份存储及数据目录后，新 Client／进程重启可以恢复这些材料，首次共识查询不必仅因重启而联网。
+
+`single_sided`、`released`、`unbound`、`invalid`、`unavailable` 等非共识状态继续联机检查。应用仅应从 `consensus` 结果读取已确认的 `owner_aid`，不能把名片中的单方 Owner 声明当作共识。
+
+公开 check 保留兼容参数 `force`／`Force`，当前四端忽略该参数；传入 true 也不会绕过有效共识缓存。resolve 同样先尝试本地共识，不能依靠 `ownershipTtlMs=0`／对应语言 TTL 选项强制重验已经命中的有效快照。
+
+resolve 的 `ownership.cached=true` 表示这次 Ownership 结果来自本地快照，不表示整个 resolve 的证书、名片等步骤完全没有网络访问。`checked_at` 也不能用来证明刚刚执行过一次远端共识检查。
+
+### 3.2 缓存如何失效
+
+| 观察或本地变化 | SDK 处理 |
+| --- | --- |
+| agent.md ETag、正文 SHA256 或目标 AID 不匹配 | 放弃旧快照，重新查询 |
+| Owner 的 owner.md 摘要变化 | 递增观察代次，失效相关快照 |
+| 关系版本、声明 Owner、锁状态不匹配，或观察到名片 missing | 不复用本地共识 |
+| 已完成的 Ownership 操作 | 继续通过原有事件路径失效 |
+| 查询期间切换身份／存储根，或观察到新变化 | 旧查询结果不进入可复用缓存 |
+
+Owner 文件摘要通过 NS 的 `X-AUN-Owner-MD-SHA256` 响应头，以及 Gateway 的 `agent_md_etags`／消息发送者元数据中的 `owner_md_sha256` 传播。要获得完整观察能力，需要相应 NS／Gateway 配套更新。
+
+已达共识的 SDK 快照没有新增固定 TTL；SDK 从后续 HTTP、RPC 和消息中吸收观察信息，没有新增独立订阅或定时轮询。未观察到变化不等于实时证明远端从未变化，离线复用结果也不替代服务端对写操作的权限和版本检查。
+
+NS 自身的结果缓存是另一层：最长 5 秒，并受证书材料期限及变化失效约束。它用于减少冷查询或失效重验的重复工作，不是 SDK 共识快照的有效期。
+
+## 4. Owner 证书：历史验签与新签分开
+
+| 操作 | 允许的证书生命周期 | 其他检查 |
+| --- | --- | --- |
+| 校验已有 owner.md／agent.md 的主签、附签 | `active_signing`、`verify_only` | 继续检查有效期、签署时刻、AID、指纹、验链、撤销／OCSP 及权威观察新鲜度 |
+| 新签 owner.md／agent.md | 仅 `active_signing` | 保存新签文件或上传前检查；群／组织双文件发布、清理路径同样适用 |
+
+证书轮换后，合法的历史签名不会仅因证书转为 `verify_only` 被拒绝。`verify_only` 不授权继续新签；过期、撤销、指纹或身份不匹配的证书仍不能通过。验签缓存命中也不能绕过新签限制。
+
+普通绑定、释放、转移和群／组织 Owner 操作继续使用现有 SDK 门面，应用无需自行把历史证书状态改成 active，也无需重新签发全部历史文件。配套 NS 已同步调整历史验签白名单；仅升级 SDK 不能改变旧 NS 的拒绝策略。
+
+## 5. UDP 待机：订阅兼容和租约恢复
+
+### 5.1 开启条件与空订阅
+
+原生 UDP 仍仅由 Python、Node 和 Go 提供，Browser 保持 WebSocket。Gateway 默认关闭该能力；主连接须同时协商到严格布尔值 `negotiated_capabilities.udp_standby_v1=true` 和 `udp_standby.enabled=true`，并满足 human 身份、空闲和连接形态等准入条件。
+
+Gateway 修复后，协议级事件订阅字段缺失或为空时，按**所有可唤醒事件**处理，prepare 会归一化并返回具体 `event_subscriptions` 快照。应用不必为了绕过空订阅引起的 `unsupported_subscription` 人为缩窄默认集合；已有支持 UDP 的 SDK 也可受益于这一服务端修复。
+
+这里是 Gateway 通知订阅，和 `EventService.subscribe` 的 Bus 订阅不同。显式订阅中仍含不支持待机恢复的事件时，Gateway 仍会返回 `unsupported_subscription`；空订阅规则不绕过能力声明、queue／stream 等连接约束或忙碌检查。恢复连接时沿用 prepare 返回的通知快照。
+
+### 5.2 心跳更新和故障恢复
+
+三端仅接受与当前心跳匹配的有效回复，先应用其中正数 `heartbeat_interval_ms`，再续租。有效租约不超过服务端返回期限和当前心跳周期 **2.5 倍**中的较短值，同时不能超过 ticket 到期时间。
+
+默认周期 25 秒对应最多 62.5 秒租约，下一轮心跳保留 ±20% 抖动。连续未能续租时按租约／ticket 期限恢复 WebSocket 并进入冷却；不再使用旧版“连续三次超时”门槛，也不再按固定约 15 分钟对账周期唤醒。
+
+新业务请求、有效唤醒提示及相应期限仍可恢复 WebSocket，正常续租可持续待机。Python／Go 在 prepare 和 commit 前补强待处理 Pull、peer 目录及恢复任务检查，避免尚有交付工作时关闭连接。
+
+UDP 只承载控制提示，不承载消息正文；`WAKE_ACK` 不是应用消费确认，也不能唤醒已退出的进程。待机不改变业务 TTL、消息幂等或写请求不可盲目重放的要求。
+
+## 6. Node／Go 专属变化
+
+| SDK | 变化 | 应用影响 |
+| --- | --- | --- |
+| Node TS | 同一群 namespace 可保留多条 inline 待 ACK 记录 | 连续在线消息减少退回 Pull；累计 ACK 仍只完成已提交项 |
+| Node TS | 消解同代际未发送的冗余后台 ACK，在线提交覆盖补拉目标时减少 Pull | 保留未确认水位的 ACK 责任；应用继续按消息标识幂等，不依赖内部 RPC 次数 |
+| Go | 组织凭据续期先复制 identity map 再更新证书 | 避免原地改写旧身份快照，应用沿用现有续期入口 |
+
+这些变化不写成 Browser 或其他 SDK 的共同新增能力。ACK 仍表示协议消费进度，不是应用业务完成回执。
+
+## 7. 升级验收清单与已有证据
+
+| 范围 | 应用验收重点 |
+| --- | --- |
+| 版本与服务 | 实际安装产物为目标版本；单实例；NS／Gateway 的配套修复和元数据传播 |
+| 大事件 | 超过 64 KiB 的明文／密文完整链路；编码后总大小；突发补充、队列和 TTL |
+| 共识 | check 和带 Ownership 的 resolve；重启复用；force 不触发额外重验；非共识仍联网 |
+| 失效 | agent.md 或 owner.md 变化；名片 missing；查询期间观察变化；存储失败后重试 |
+| 证书 | verify_only 历史主签／附签通过；同证书新签被拒；过期及撤销继续拒绝 |
+| UDP（三端） | 空订阅、显式不支持订阅、能力未协商、忙碌准入、新周期及租约到期恢复 |
+| 语言差异 | Node 同群连续 inline／累计 ACK；Go 续期前后旧身份快照 |
+
+已有定向回归、类型检查和 NS 核验结果见 [parity 的验证范围](../../python/CHANGES_FOR_PARITY.md#v0536)。本次专题整理只执行文档一致性、链接和索引检查，不新增功能全量、容量对比、公网／Docker／浏览器 live／跨域 E2E 或 Mail 整体验收结论。

package/_packed_docs/sdk/0.5.36-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,176 @@
+# 0.5.36 SDK 开发与移植指南
+
+本文面向四 SDK 维护者和新语言实现者，整理 **0.5.35 → 目标 0.5.36** 的协议边界、缓存与连接状态机。比较基线为 `80cf7cf49`，依据截至 2026-11-12 的工作区源码；不代表版本已发布或部署验收已完成。
+
+应用调用及升级影响见 [应用集成指南](0.5.36-SDK应用集成指南.md)，四端差异和已有验证见 [parity 0.5.36](../../python/CHANGES_FOR_PARITY.md#v0536)。[0.5.35 移植指南](0.5.35-SDK开发与移植指南.md)保留通配订阅、过滤、本地通道、ACK／同步、Echo 与 Mail 的历史增量；其中事件大小、共识复用和 UDP 恢复条件以本文为准。
+
+## 1. 本版实现契约
+
+| 范围 | 必须保持的行为 | 语言边界 |
+| --- | --- | --- |
+| EventService | 去除独立 64 KiB 检查，复用消息报文上限；完整字节计费、有界容量 | 四端；Python 另调整 Bus 字节突发和紧凑 JSON |
+| Ownership 查询 | check／resolve 优先复用有效持久共识，忽略 check 的 force；非共识联机 | 四端；Browser 存储异步 |
+| 观察 | agent.md ETag 和 Owner 文件摘要失配时失效，拒绝旧观察结果落盘 | 四端；依赖 NS／Gateway 元数据 |
+| 证书 | 历史主签、附签允许 verify_only；任何新签仍须 active_signing | 四端及配套 NS |
+| UDP | 先更新周期再续租，租约受 2.5 周期及 ticket 约束 | Python／Node／Go；Browser 无原生实现 |
+| 专属修复 | Node inline／ACK／Pull；Go 组织续期身份复制 | 不扩写为四端共同新增 |
+
+本次配套服务按单实例支持，保留现有模块协议和存储边界。Rust 保持只读，不在实现或核验范围；Mail 整体验收状态沿用 0.5.35。
+
+## 2. EventService 大小、速率与容量
+
+### 2.1 不再维护独立事件正文上限
+
+发布、Bus 受理和订阅接收均移除独立 64 KiB 检查，旧 `max_event_bytes`／`event_bytes` 不再驱动单事件拒绝。不要在新语言的任一入口重新加入该限制。
+
+沿用原有 P2P `sdk_control` 与 `aun.pubsub/1` 格式，复用普通 RPC／`message.send` 的完整 WebSocket 报文上限 `1_000_000` 字节，Go 复用 `MaxWSPayloadSize`。预算针对编码后的完整请求，包含 JSON、控制字段、目标及 E2EE 开销，不能直接以事件正文长度代替报文长度。
+
+保留现有发布凭据、角色租约、TTL、去重和接收代次检查。本地路径沿用原容量与调度规则，不为模拟网络再增加一层正文大小上限。
+
+### 2.2 令牌桶允许容纳最大报文，不透支
+
+SDKChannel 收发及客户端事件接收默认字节突发提高至 `1_000_000`；默认调用速率 40 次／秒、字节速率 262,144 字节／秒和调用突发 4 次继续保留。
+
+一次成功获取须扣除该层实际序列化的完整 UTF-8 字节数；不足时按原期限等待补充，单条超过桶容量仍返回 `MESSAGE_TOO_LARGE`。不能以 `min(size, burst)` 少扣字节，也不能通过负令牌实现额外透支。
+
+Python SDKChannel 使用紧凑 JSON 计费，Bus 的全局及单发布者发送字节突发也调整为 `1_000_000`。这些默认值不统一所有角色的持续速率；保留原有各层节流和配置语义。
+
+### 2.3 总容量与单条报文分开
+
+发布、结果、接收及 Bus fanout 的数量和总字节容量保持有界。超过总容量时继续等待、返回 `OVERLOADED` 或因原 TTL 到期结束；释放容量和取消任务时沿用现有记账路径。
+
+移植验收需同时覆盖超过 64 KiB 的合法事件、编码后超过报文上限、令牌补充、完整计费及容量回收。不能仅删除发布端检查而保留 Bus／Sub 的旧拒绝分支，也不能将取消单条限制变成无限排队。
+
+| SDK | 主要实现入口 |
+| --- | --- |
+| Python | [pubsub/client.py](../../python/src/aun_core/pubsub/client.py)、[service.py](../../python/src/aun_core/pubsub/service.py)、[binding.py](../../python/src/aun_core/pubsub/binding.py)、[rate.py](../../python/src/aun_core/pubsub/rate.py) |
+| Node TS | [pubsub/client.ts](../../ts/src/pubsub/client.ts)、[service.ts](../../ts/src/pubsub/service.ts)、[channel.ts](../../ts/src/pubsub/channel.ts) |
+| Browser JS | [pubsub/client.ts](../../js/src/pubsub/client.ts)、[service.ts](../../js/src/pubsub/service.ts)、[channel.ts](../../js/src/pubsub/channel.ts) |
+| Go | [pubsub_client.go](../../go/pubsub_client.go)、[pubsub_service.go](../../go/pubsub_service.go)、[pubsub_binding.go](../../go/pubsub_binding.go) |
+
+## 3. Ownership 持久共识与查询流程
+
+### 3.1 保存能重建共识的完整材料
+
+| 材料 | 用途 |
+| --- | --- |
+| `ownership_snapshot` | NS 已确认的状态、目标、Owner、关系版本、锁、ETag 和文件哈希 |
+| `ownership_agent_md` | 共识时的 agent.md 正文；没有普通名片正文缓存时仍可重建 |
+| `remote_owner_md_sha256` | 最新观察到的 owner.md 摘要，与快照的 `owner_md_sha256` 比较 |
+| `remote_etag`／`remote_status` | 观察到的名片版本和缺失状态 |
+| `observation_version` | 识别查询期间的变化，包含 ETag 改变后又变回的情形 |
+
+沿用各语言现有身份存储及根目录隔离，不新建独立共识数据库。Browser 等待异步持久化；各端只有成功写入且观察未变的结果才能作为后续可复用快照。
+
+### 3.2 本地命中条件
+
+恢复或复用前须验证目标 AID、`status=consensus`、`lock=locked`、非 missing、agent.md 正文 SHA256，以及声明中的 Owner 和关系版本。已观察的 ETag／Owner 摘要存在时须与快照一致；内存缓存还核对观察代次和当前正文。
+
+正文优先使用当前名片内容，缺失时才使用 `ownership_agent_md`；不能为了命中快照忽略已经存在但不匹配的新正文。解析失败、材料不足或任一条件不满足，均回到联机检查。
+
+成功共识不新增固定 TTL，非共识结果不作为离线复用依据。`single_sided`、`released`、`unbound`、`invalid`、`unavailable` 等下次仍检查远端；不能把短暂失败缓存成长期无 Owner。
+
+### 3.3 check 与 resolve 的执行顺序
+
+1. 读取当前身份、存储根、名片记录、ETag 和观察代次。
+2. 尝试有效内存共识；没有可用命中时按入口规则恢复本地持久材料。
+3. 无有效共识则沿用现有 NS 查询和材料验证流程。
+4. 对齐返回的目标、关系版本、锁状态、正文哈希与 Owner 摘要。
+5. 提交前复查身份／存储根、正文、ETag、观察代次及当前查询归属；失败则不留下有效缓存。
+6. 持久化成功后才保留可复用快照；返回对象与缓存对象继续隔离。
+
+公开 check 的 `force`／Go `OwnershipConsensusOptions.Force` 保留签名兼容但不控制绕缓存。内部名字含 Fresh 的包装最终也调用该检查，不能仅凭方法名认定必然重新联网。
+
+resolve 仅在传入 Ownership checker 时查询共识，先尝试同一持久快照，并核对展示名片与观察的一致性；本地命中返回 `cached=true`。`ownershipTtlMs`／对应语言 TTL 选项不排在有效本地共识命中之前，不能据此强制失效。无本地命中时保留已有并发合并及错误映射。
+
+## 4. Owner 摘要观察与失效传播
+
+NS 通过 `X-AUN-Owner-MD-SHA256` 返回 owner.md 摘要。Gateway 在 `agent_md_etags` 主体条目和消息发送者元数据透传 `owner_md_sha256`，SDK 在已有元数据吸收路径中处理；这不是新增 RPC、事件订阅或独立轮询协议。
+
+新摘要与当前观察不同时，递增 `observation_version` 并清除不匹配快照。agent.md ETag／正文、missing、Ownership 完成事件等原有失效源继续生效；不要用 Owner 摘要替代 agent.md 自身版本检查。
+
+异步查询开始与结束都绑定观察。ETag 相同但观察代次已变化、存储根切换、身份切换或旧查询被替代时，旧结果不能覆盖新状态；持久化失败同样不留下有效内存共识。
+
+观察信息依赖后续流量携带，未观察变化不构成远端实时无变化的证明。本地快照复用与服务端的权限、证书及写入 CAS 是不同职责，不能将缓存命中扩写为新的写授权。
+
+| SDK | 查询与存储落点 |
+| --- | --- |
+| Python | [client.py](../../python/src/aun_core/client.py) `check_ownership_consensus`；[aid_store.py](../../python/src/aun_core/aid_store.py) `_resolve_ownership`；[agent_md.py](../../python/src/aun_core/agent_md.py) `local_ownership_consensus`／`observe_ownership_meta`／`save_record` |
+| Node TS | [client.ts](../../ts/src/client.ts) `checkOwnershipConsensus`；[aid-store.ts](../../ts/src/aid-store.ts)；[agent-md.ts](../../ts/src/agent-md.ts) `localOwnershipConsensus`／`observeOwnershipMeta`／`cacheOwnershipSnapshot` |
+| Browser JS | [client.ts](../../js/src/client.ts)、[aid-store.ts](../../js/src/aid-store.ts)、[agent-md.ts](../../js/src/agent-md.ts) 的对应异步方法，保留浏览器存储代际 |
+| Go | [ownership_v21.go](../../go/ownership_v21.go) `CheckOwnershipConsensusWithOptions`／`ownershipV21LocalConsensus`；[aid_store.go](../../go/aid_store.go)；[agent_md_manager.go](../../go/agent_md_manager.go) |
+
+## 5. 配套 NS 的共识读取优化
+
+普通共识读取移除原排队门槛，结果短缓存最长 **5 秒**，并受签名、证书材料和权威证据期限收紧。缓存保留依赖 AID、Owner 文件内容和观察信息；相关名片、Owner 文件或证书变化时必须失效，不能只按目标 AID 保存一个永不过期布尔值。
+
+保留 NS 验链缓存和既有材料验证，不为取消排队而省略安全检查。owner.md 条件读取及内容复用减少重复读取，避免沿用重复 HEAD→GET→HEAD 的完整往返；冷缓存及失效后的联机查询仍可能调用配套服务。
+
+NS 的短 TTL 与 SDK 无固定 TTL 的观察缓存不可混为一层；Gateway 提供的证书证据和 NS 自身验链缓存也不等于最终共识结果。此处只描述当前单实例实现，不承诺多副本失效传播或大量 AID 的实测加速比。
+
+主要落点为 [agentmd.go](../../../extensions/services/nameservice/go/internal/httpserver/agentmd.go)、[agentmd_cache.go](../../../extensions/services/nameservice/go/internal/httpserver/agentmd_cache.go)、[ownership.go](../../../extensions/services/nameservice/go/internal/httpserver/ownership.go)及 [ownership_certificate.go](../../../extensions/services/nameservice/go/internal/httpserver/ownership_certificate.go)。
+
+## 6. 历史验签与新签证书策略
+
+### 6.1 历史文件验证
+
+已有 owner.md／agent.md 的主签与附签接受 `active_signing` 或 `verify_only`。生命周期只是材料检查的一项，仍核对角色、目标与签署者 AID、指纹、签署时刻、有效期、信任链、撤销／OCSP 和权威证据新鲜度；其他生命周期不能因签名字节正确而放行。
+
+NS 同步采用这一白名单，不再额外要求 Gateway 证据中的 `active_signing` 布尔值必须为真。不能将其解释为关闭 Gateway 材料来源或撤销检查。
+
+### 6.2 新签路径不能借历史缓存放行
+
+新生成 owner.md／agent.md 必须使用 `active_signing`，覆盖绑定、释放、转移、群／组织双文件发布及清理。校验必须发生在保存新签文件或上传之前，主签与附签均须满足相应新签约束。
+
+TS／JS 的 `requireActiveSigning`、Python 的 `require_active_signing` 和 Go 的对应验证参数区分验证意图；历史验证默认允许 verify_only，新签调用显式开启限制。限制须在历史验证缓存命中前检查，不能从缓存直接返回成功而漏验新签资格。
+
+四端核心落点为各自 `ownership-v21.ts`／`ownership_v21.py`／`ownership_v21.go`，并核对 `auth.ts`、Python 证书材料解析，以及 Client 群／组织直接签名后保存或上传的入口。移植时只改历史材料白名单不够，还须覆盖这些独立新签入口。
+
+## 7. UDP 租约与连接状态机
+
+### 7.1 准入与通知集合
+
+保持双能力严格协商、主长连接、human 身份、空闲时长及忙碌检查。Python／Go 本版补强待处理 Pull、peer 目录和恢复工作检查，并在 prepare／commit 前重检，避免异步准备期间新增工作仍进入待机。
+
+Gateway 对缺失或空通知订阅归一化为所有可唤醒事件，prepare 返回实际 `event_subscriptions`，恢复认证时写回 `auth.connect.options.event_subscriptions`。显式包含不可恢复事件仍拒绝；不要把 Bus 的 EventService 订阅送入这套协议，也不要跳过客户端能力声明。
+
+### 7.2 匹配回复后先改周期，再改期限
+
+保持原包认证、standby 标识、epoch、序列和重放检查；心跳回复还必须匹配当前在途请求及有效等待窗口。仅正 `heartbeat_interval_ms` 更新策略，之后才按新周期计算租约，下一轮继续 ±20% 抖动。
+
+有效租约以服务端剩余期限和当前心跳周期 2.5 倍取较短值，并受 ticket 到期时间限制。各语言沿用既有单调时钟和发送／接收时间基准，不能把墙上时钟与单调截止时间混用。
+
+移除固定约 15 分钟对账唤醒和“连续三次心跳超时”判定。未能及时续租时由租约／ticket 期限恢复 WebSocket 并进入冷却；有效心跳可续租，业务请求及服务端有效提示继续触发唤醒。并发唤醒合并、关闭代际和原请求超时／取消边界继续保留。
+
+UDP 不携带消息正文；`WAKE_ACK` 不推进消息消费、不延长业务 TTL。恢复连接后继续原同步及 ACK 流程，不重放已发出的非幂等写请求。
+
+| SDK／服务 | 实现与回归入口 |
+| --- | --- |
+| Python | [udp_standby.py](../../python/src/aun_core/_client/udp_standby.py)、[test_udp_standby.py](../../python/tests/unit/test_udp_standby.py) |
+| Node TS | [udp-standby.ts](../../ts/src/udp-standby.ts)、[udp-standby.test.ts](../../ts/tests/unit/udp-standby.test.ts) |
+| Go | [udp_standby.go](../../go/udp_standby.go)、[udp_standby_test.go](../../go/udp_standby_test.go) |
+| Gateway | [udp_standby.go](../../../extensions/services/gateway/go/internal/httpserver/udp_standby.go)、[udp_standby_test.go](../../../extensions/services/gateway/go/internal/httpserver/udp_standby_test.go) |
+
+## 8. 语言专属交付与身份修复
+
+Node 交付引擎在同群 namespace 保存多条 inline 待 ACK 记录，累计水位只完成已提交项，不能因确认更高 seq 而删除尚未提交的记录。已确认水位可完成同代际中尚未发出的后台 ACK，在线 P2P 提交覆盖补拉目标时减少重复 Pull，但仍保留未确认水位的 ACK 责任。
+
+核对 [delivery.ts](../../ts/src/client/delivery.ts)、[rpc-pipeline.ts](../../ts/src/client/rpc-pipeline.ts)和 [v2-e2ee.ts](../../ts/src/client/v2-e2ee.ts)中的 namespace、身份／连接代际及已提交水位。此修复只记作 Node 本版增量，不要求 Browser 复制其内部任务结构。
+
+Go [org_facades.go](../../go/org_facades.go)在组织凭据续期更新证书前复制 identity map，避免改写其他路径已经持有的身份快照。沿用现有存储格式及公开续期入口。
+
+## 9. 定向回归与证据边界
+
+| 范围 | 现有测试入口 | 验收重点 |
+| --- | --- | --- |
+| 大事件 | 四端 pubsub client／service／rate／channel 测试 | 超过 64 KiB、完整报文预算、无透支及完整计费、TTL／总容量回收 |
+| 持久共识 | 四端 Ownership／workflow、AIDStore 测试 | 重建 Client／存储恢复；check 与 resolve 命中；忽略 force；非共识联机 |
+| 观察与并发 | 四端 agent-md／Ownership 测试 | Owner 摘要、ETag 往返、正文变化、missing、身份／存储根切换、旧查询和写入失败 |
+| 证书 | 四端 Ownership／workflow、Client 实体发布专项；NS httpserver | verify_only 历史主签／附签；新签保存／上传前拒绝；缓存命中不绕过限制 |
+| NS | `internal/httpserver` 缓存及 Ownership 测试 | 短 TTL、证据期限、依赖失效、验链缓存保留及条件读取 |
+| UDP | 上节三端及 Gateway 现有测试 | 空订阅、显式不支持订阅、匹配回复、新周期先应用、租约到期、准备期间新增工作 |
+| 专属修复 | Node delivery／v2-e2ee；Go 组织凭据测试 | 同群多 inline、提交与 ACK 水位、冗余任务、旧身份快照 |
+
+既有记录见 [parity 的核验范围](../../python/CHANGES_FOR_PARITY.md#v0536)：Ownership 回归 Node 460 项、Browser 364 项、Python 399 项及三端实体专项各 3 项通过；Go Ownership／Entity 定向回归及 vet、NS httpserver 全包测试及 vet、TS／JS 类型及 Python 语法检查通过。这些是此前阶段的记录，本次文档整理不重新宣称执行。
+
+本次只校验两份指南及索引的一致性、链接和历史文档保留情况；未运行功能全量、容量对比、线上部署、公网／Docker／浏览器 live／跨域 E2E 或 Mail 整体验收，亦未修改或构建 Rust。

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

@@ -230,7 +230,7 @@ print(client.can_connect, client.can_send, client.is_online)
 
 ## Agent Web / agent.md
 
-以下普通主体示例以本 AID 主签和 token 上传。Group/Org 名片由实体私钥生成主签，当前 owner 以本人 token 上传，无需实体登录；可选 owner 附签，存在就必须验全部块。Group 旧实体单签及实体身份上传始终兼容，Org 不开放该旧入口。取消实体额外 V2 上传授权，保留当前 owner、生命周期、实体证书代际与 CAS 检查，见 [协议 §2.5](../protocol/Ownership协议定义2.1.md#25-grouporg-名片的实体主签与-owner-上传)。
+以下普通主体示例以本 AID 主签和 token 上传。现代 Group/Org 名片由实体私钥生成主签，当前 owner 以本人 token 上传，无需实体登录；使用与 owner.md 配对的 ownership.statement，主签不含 signer_aid，也不要求旧 entity_cert_fingerprint，可选 owner 附签，存在就必须验全部块。Group 旧实体单签及实体身份上传持续兼容，Org 不开放该旧入口；仍保留当前 owner、生命周期、实体证书代际与 CAS 检查，见 [协议 §2.5](../protocol/Ownership协议定义2.1.md#25-grouporg-名片的实体主签与-owner-上传)。
 
 发布自己的 agent.md：
 
@@ -263,7 +263,7 @@ downloaded = await store.download_agent_md("bob.agentid.pub")
 state = await store.check_agent_md("bob.agentid.pub", ttl_days=1)
 ```
 
-新 SDK 全部 NS GET/HEAD/PUT（含 fresh）携带 `X-AUN-Signature-Format: multi-v1` 获取完整多签；实体 fresh GET 必须同时携带 `X-AUN-Ownership-Check: 1`、`Cache-Control: no-cache`、`X-AUN-Signature-Format: multi-v1`；NS 仅凭 Check 头绕过 LRU 并新鲜验证全部签块，仍返回 not_applicable，不进入通用 Ownership 账本。无头客户端读取首签投影，表示 ETag 与完整存储 CAS 的映射见 [协议 §3.3](../protocol/Ownership协议定义2.1.md#33-读取并发与接口)。
+新 SDK 全部 NS GET/HEAD/PUT（含 fresh）携带 `X-AUN-Signature-Format: multi-v1` 获取完整多签；实体 fresh GET 必须同时携带 `X-AUN-Ownership-Check: 1`、`Cache-Control: no-cache`、`X-AUN-Signature-Format: multi-v1`；NS 凭 Check 头绕过 LRU 并新鲜验证全部签块。现代 Group/Org 参与双文件共识，缺少 ownership 的历史实体仍返回 not_applicable；普通关系管理 Facade 仍走专属生命周期边界。无头客户端读取首签投影，表示 ETag 与完整存储 CAS 的映射见 [协议 §3.3](../protocol/Ownership协议定义2.1.md#33-读取并发与接口)。
 
 当前公开入口分工固定：
 

package/_packed_docs/sdk/06-API/346/211/213/345/206/214.md

@@ -16,6 +16,7 @@
 - [E2EE 高级 API](#e2ee-高级-api)
 - [RPC 方法参考](#rpc-方法参考)
 - [Stream 使用指南](#stream-使用指南)
+- [AID 空闲 UDP 待机（测试能力）](#aid-空闲-udp-待机测试能力)
 
 > **多语言命名约定**：Python 使用 `snake_case`（如 `aun_path`、`download_agent_md`），TS/JS 使用 `camelCase`（如 `aunPath`、`downloadAgentMd`），Go 使用 `PascalCase` 公开方法（如 `Load`、`Register`）。本手册表格中各列对应各语言的实际命名。
 
@@ -140,10 +141,10 @@ Python 兼容 `forceRefresh`、`skipAgentMd`、`timeoutMs`、`ownershipTtlMs`
 | `tags` | string[] | 标签 |
 | `owner` | string | 名片声明的 owner；普通主体需结合 2.1 共识状态判断；Group/Org 属于专属生命周期 |
 | `ownership` | object | 普通主体的声明容器，当前核心字段为 `statement` |
-| `entity_cert_fingerprint` | string | Group/Org 实体证书的 `sha256:<hex>` 指纹 |
+| `entity_cert_fingerprint` | string | 历史 Group/Org 名片的实体证书 `sha256:<hex>` 指纹；现代 ownership.statement 格式不再要求此字段 |
 | 其它键 | 任意解析值 | 如 visibility、skills 或应用自定义字段，存在时原样返回 |
 
-当前发布 Schema 要求 `aid/name/type/version`；读取接口兼容历史名片，因此类型声明中的标准字段可缺省，不补默认值，裸 Markdown 正文返回 `{}`。`ownership.statement` 保留六字段：`version=2`（整数）、`declaration_id`（小写 UUIDv4）、`owner_aid`、`sub_aid`、`relation_version`（正整数）和 `declared_at`（Unix 秒）。普通主体的 owner 与 statement 同时存在或同时缺省；human 禁止通用 ownership，Group/Org 不使用此声明容器。
+当前发布 Schema 要求 `aid/name/type/version`；读取接口兼容历史名片，因此类型声明中的标准字段可缺省，不补默认值，裸 Markdown 正文返回 `{}`。`ownership.statement` 保留六字段：`version=2`（整数）、`declaration_id`（小写 UUIDv4）、`owner_aid`、`sub_aid`、`relation_version`（正整数）和 `declared_at`（Unix 秒）。普通主体的 owner 与 statement 同时存在或同时缺省；human 禁止通用 ownership，现代 Group/Org 同样使用与 owner.md 配对的声明，历史无 ownership 实体名片继续兼容。
 
 字段定义与签名规则以 [当前协议 §1.3、§2](../protocol/Ownership协议定义2.1.md) 为准；[agent.md/SCHEMA.md](../agent.md/SCHEMA.md) 是 legacy Ownership 2.0。`frontmatter.owner` 和已有 `agent_md.verification.ownership_status` 都不替代下面的 2.1 共识结果。
 
@@ -175,7 +176,7 @@ Python 兼容 `forceRefresh`、`skipAgentMd`、`timeoutMs`、`ownershipTtlMs`
 | `single_sided` | 只有一方声明或待确认材料，关系尚未成立 |
 | `invalid` | 声明、签名或身份绑定等材料无效 |
 | `unavailable` | 网络、证书、服务能力、权威性或读取一致性不足，当前无法确认 |
-| `not_applicable` | Group/Org 等使用专属生命周期，不适用通用共识 |
+| `not_applicable` | NS 对缺少 ownership 的历史 Group/Org 保留该标记；现代实体声明参与双文件共识，SDK 以实际返回 status 为准 |
 
 `owner_md` 包含 `owner_aid: string`、`bucket: "default"`、`path: "sub_aids/{aid}/owner.md"`、`exists: bool`、`content: string`（完整原文，含签名）、`sha256: string`、`observed_at: integer`（Storage 观察时间，Unix 秒）。确认不存在时 exists=false、content/sha256 为空串；存在快照不表示整体共识成功，须检查 status。
 
@@ -207,7 +208,7 @@ if result.Ok && result.Data.AgentMD != nil {
 
 ### 通用 sign / verify
 
-`format="raw"` 为默认，保留 detached Base64 签名／验签；`format="document"` 处理任意 UTF-8 文本文档的连续尾签，不要求 YAML 或 agent.md 业务字段。sign 返回 `signed` 全文、本次 `signature` 和实际 `signatures` 列表；verify 返回 `valid`、`status`、首块前 `payload` 及逐块 `signatures`。普通 agent.md 与 owner.md 主签不输出且业务不接受 signer_aid；实体主块显式 signer_aid=target，主签身份、Schema、资源及授权由调用者另验，SDK 文件流程和服务端均复用各自唯一同构签验 core。
+`format="raw"` 为默认，保留 detached Base64 签名／验签；`format="document"` 处理任意 UTF-8 文本文档的连续尾签，不要求 YAML 或 agent.md 业务字段。sign 返回 `signed` 全文、本次 `signature` 和实际 `signatures` 列表；verify 返回 `valid`、`status`、首块前 `payload` 及逐块 `signatures`。普通 agent.md、owner.md 与现代 Group/Org agent.md 主签均不输出且业务不接受 signer_aid；历史实体主签格式另按兼容规则验证，主签身份、Schema、资源及授权由调用者另验，SDK 文件流程和服务端均复用各自唯一同构签验 core。
 
 `input_type="text"` 默认把输入视作内容；显式 `input_type="file"` 才读取文件；raw 按原始字节处理，包括非 UTF-8 文件，document 必须严格 UTF-8，raw/document 字符串均严格校验 Unicode 并编码为 UTF-8，无效 Unicode 拒绝。不识别 `file://` 或自动猜路径，缺失文件报错。`in_place=True` 仅适用于 file + document，签名成功后才写回；TS/JS 使用 `inputType/inPlace`，Go 使用 `InputType/Format/Tag/Append/InPlace`。浏览器 File/Blob 只读，FileSystemFileHandle 可原地写，不接受裸本地路径。
 
@@ -464,7 +465,7 @@ headers = client.get_protected_headers()
 - agent.md 上传、下载和检查入口都在 `AIDStore`；`AUNClient` 不再暴露上传入口。
 - 普通主体目标 AID 须有本地签名材料并使用自身 token；Group/Org 用实体主签、当前 owner token 上传，可选 owner 附签，不能以附签替换资源授权。agent.md 与 owner.md 统一调用 Store document 签验 core，再验证业务 Schema。
 - 实体上传默认使用名片当前 owner；显式指定上传者分别使用 Python `uploader_aid`、TS/JS `options.uploaderAid`、Go `AIDStoreUploadAgentMDOptions.UploaderAID`。追加 owner 附签分别使用 `co_signer_aid`、`options.coSignerAid`、`AIDStoreUploadAgentMDOptions.CoSignerAID`，值必须为当前 owner；Go 通过 `UploadAgentMDWithOptions` 传入选项。
-- SDK 全部 NS GET/HEAD/PUT 携带 `X-AUN-Signature-Format: multi-v1`；GET 同时发送 `Accept: text/markdown`；实体 fresh GET 另带 `X-AUN-Ownership-Check: 1` 与 `Cache-Control: no-cache` 以绕 LRU 全块验证，仍为 not_applicable、不进入通用账本；不主动发送 `If-None-Match` / `If-Modified-Since`。如果服务端异常返回 304，本地有内容则复用；无内容时再发一次无条件 GET。
+- SDK 全部 NS GET/HEAD/PUT 携带 `X-AUN-Signature-Format: multi-v1`；GET 同时发送 `Accept: text/markdown`；实体 fresh GET 另带 `X-AUN-Ownership-Check: 1` 与 `Cache-Control: no-cache` 以绕 LRU 全块验证；现代实体参与双文件共识，NS 对缺少 ownership 的历史实体保留 not_applicable 标记；不主动发送 `If-None-Match` / `If-Modified-Since`。如果服务端异常返回 304，本地有内容则复用；无内容时再发一次无条件 GET。
 - SDK 会自动从 Gateway `_meta.agent_md_etags` 和信封 `agent_md` 观察远端版本；`requester`、`peer`、`group` 是标准角色键，`receiver`、`target`、`to`、`sender`、`from` 是兼容别名。
 - `Accept: text/markdown` 与 agent.md 的 YAML frontmatter + Markdown 格式兼容；agent.md 仍是 Markdown 媒体类型上的结构化约定。
 
@@ -519,7 +520,7 @@ Bus 宿主可查询全局；Pub 仅查看自身 AID、当前发布权限内的
 | Ownership 2.1 | 七个关系业务Facade：`bindOwneraid`、`bindSubaid`、`releaseSubaid`、`transferSubaid`、`acceptOwnershipRequest`、`rejectOwnershipRequest`、`checkOwnershipConsensus`；无参数任务管理Facade `resetOwnershipTask()`（Python `reset_ownership_task()`、Go `ResetOwnershipTask(ctx)`），批量清理当前AID发起的未完成任务，返回`{reset_operation_ids:[],skipped_operation_ids:[]}`（其余为TS/JS命名） | [应用集成](Ownership2.1-SDK应用集成指南.md#4-七个-facade-的参数角色与结果)、[开发与移植](Ownership2.1-SDK开发与移植指南.md) |
 | Credential/Org | Python/TS/JS：`client.credential`、`client.org`；Go：`client.Credential()`、`client.Org()`；普通与语义凭证共用 credential 入口，无 semantic 子层；包含签验、包／请求、消息证据及额度协调工具 | [应用集成](凭证与组织服务SDK应用集成指南.md)、[开发与移植](凭证与组织服务SDK开发与移植指南.md) |
 
-Ownership 2.1 关系须检查当前双文件共识；Group/Org 使用专属生命周期，通用关系操作返回 `not_applicable`。Credential/Org 的本地验签不代替当前状态和请求授权检查。
+Ownership 2.1 关系须检查当前双文件共识；现代 Group/Org 同样发布配对声明并查询共识，但创建、绑定、转让和解散仍使用专属生命周期，普通 bind/release/transfer 关系管理 Facade 返回 `not_applicable`。Credential/Org 的本地验签不代替当前状态和请求授权检查。
 
 sub-first 绑定在 sub 同意后 Stage 暂存 `agent.md`；NS 的 `pending/unlocked` 对公共共识映射为 `single_sided`，不授予 owner 权限，Storage 名片副本待 fresh 验收清除 pending 后同步。owner-first 绑定先 fresh 确认无锁并条件发布 `owner.md`，sub fresh 验证后同意并直接条件提交 `agent.md`，不走 Stage 或 bind.accept／owner.ready 往返。已有 owner 锁时只能由当前 owner 发起解绑或转移；拒绝清理与 reset 的原件／CAS 边界见 [应用指南 §6.1](Ownership2.1-SDK应用集成指南.md#61-绑定按发起方分流)。普通消息建议连接前订阅，READY 后补订阅也会触发任务恢复。
 
@@ -1137,3 +1138,28 @@ info = await client.call("stream.get_info", {"stream_id": stream["stream_id"]})
 await client.call("stream.close", {"stream_id": stream["stream_id"]})
 ```
 
+## AID 空闲 UDP 待机（测试能力）
+
+Python、TypeScript/Node.js 与 Go SDK 支持独立 AID 实例的 UDP 待机，浏览器 JS 与本期暂不移植 UDP 的 Rust SDK 保持 WebSocket。具有待机控制器的主长连接通过 `auth.connect.capabilities.udp_standby_v1=true` 声明能力；Gateway 默认关闭，响应 `capabilities.udp_standby_v1` 表达当前实际可用性，只有 `negotiated_capabilities.udp_standby_v1` 与 `udp_standby.enabled` 均严格为布尔 `true` 才启用，缺失、`false` 或字符串 `"true"` 保持 WS；短连接和辅助连接不声明。客户端初次上线仍建立 WS 并正常认证、检查和补拉，通过双向空闲与在途任务门禁后才释放 WS。Node 使用内置 `node:dgram`，无需新增运行依赖。原定 Ubuntu Docker 单域 11 场景已分轮通过，新增动态心跳与 human 准入仍待增量实机验证，容量未验。
+
+准备阶段通过 `AIDStore.resolve(...)` 的 `agent_md.frontmatter.type` 识别自身 AgentMD 类型；已知 `human` 保持 WS，未知沿用原准入，不以注册意图替代本次 AgentMD 结果。UDP 心跳不查询 AgentMD。
+
+`HEARTBEAT_ACK` 正文固定为 `lease_remaining_ms:uint32 + pending_generation:uint64 + reason_mask:uint32 + heartbeat_interval_ms:uint32`，共 20 字节，其他报文结构不变。Gateway 每次收到有效 HEARTBEAT 都返回当前周期 T 并按 4T 续租，SDK 按 T 的 ±20% 抖动安排下一次心跳；动态配置更新不追溯缩短已发租约。SDK 连续 3 次响应超时后恢复 WS；默认 T=25 秒、单次等待 5 秒，服务端正常窗口 100 秒，授权、票据或目录期限可更早到达。正常切换不产生应用离线回调，任一有效 WS/UDP 在线即保持应用在线；未新增切换完成回调或公开字段。
+
+应用仅在确定不依赖瞬时通知时，显式选择可恢复事件；以下示例改变服务端事件过滤，不适用于需要全事件的应用：
+
+```python
+await client.connect()
+await client.call("event.subscribe", {
+    "events": ["message.received", "group.message_created"],
+})
+```
+
+TypeScript 使用 `client.call()`，Go 使用 `client.Call(ctx, ...)` 调用同一 RPC。`event.subscribe` / `event.unsubscribe` 的 `subscribed` 返回完整过滤集合；默认全事件、queue、流式和非白名单事件会话继续保持 WS，SDK 不自动缩窄已有订阅。TypeScript/Node 可通过 `connect({udp_standby: false})` 禁止本次连接声明该能力；不要将该选项直接套用到其他 SDK。
+
+进入待机后，`call`、消息发送、认证刷新等真实网络需求会立即恢复 WS，多个并发调用共享恢复过程，各自保留原 deadline 与取消语义；缓存命中的本地读取不唤醒。服务端消息提示也通过恢复 WS 后的原 Pull/ACK 流程处理。WAKE_ACK 不代表业务消费，UDP 不发送正文、不延长消息 TTL、不重放已经发出的写请求。
+
+为支持连续待机，SDK 使用 `gateway.standby.prepare` 返回的 `event_subscriptions` 权威快照，在恢复 `auth.connect.options.event_subscriptions` 中提交；Gateway 从新会话首次事件路由起应用该过滤。未传字段仍为原全事件语义，显式 `[]` 为无事件。应用不需要每次唤醒后手工重新订阅，也不应自行重放待机票据或认证签名。
+
+`disconnect()` / `close()` 停止本实例的待机与自动恢复，不影响同主机其他 AID。UDP 验证失败、连续无应答、租约/票据到期或 Gateway 故障时回 WS 并遵守冷却与原重连限制；UDP 不能唤醒已退出的进程。协议、事件白名单、错误原因和部署方式见 [Gateway 连接模式 §3.10](../../../docs/AUN文档/AUN协议/03-Gateway-连接模式.md#310-aid-空闲-udp-待机测试能力)，状态机与验收边界见 [详细设计](../../../docs/AUN文档/AID空闲UDP待机详细设计.md)。
+

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

@@ -169,19 +169,19 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 
 ## 群组生命周期
 
-群 owner 由本节生命周期自动建立、转移和解除，不进入 Ownership 2.1 的 `owner.md`、关系版本、owner 锁、P2P 审批或通用 Facade。创建时群公私钥及证书归初始 owner 持有；解散解除有效 owner 授权；专属转移必须 rekey，旧材料失效，新材料归新 owner。Group 服务从不保存群私钥。
+群 owner 由本节专属生命周期建立、转移和解除；SDK 发布配对的 `owner.md`／`agent.md` 声明，并通过 Ownership 2.1 关系版本、owner 锁和双文件共识确认归属，不调用普通 bind/release/transfer Facade 或普通主体 P2P 审批流程。创建时群公私钥及证书归初始 owner 持有；解散解除有效 owner 授权；专属转移必须 rekey，旧材料失效，新材料归新 owner。Group 服务从不保存群私钥。
 
-### 群 agent.md 的 owner 代签与上传
+### 群 agent.md 的实体主签与 owner 上传
 
-新 SDK 群名片 aid 为 group_aid、type=group、owner 为当前群主，entity_cert_fingerprint 为当前群证书指纹；必须省略 ownership、ownership_proof、ownership_release。实体私钥主签，当前 owner token 上传，无需群登录，可选 owner 附签，存在时必须全块验证。取消实体额外 V2 授权头；群证书指纹仍绑定 owner/rekey 代际，完整多签与 CAS 见 [协议 §2.5](../protocol/Ownership协议定义2.1.md#25-grouporg-名片的实体主签与-owner-上传)。
+现代 SDK 群名片 aid 为 group_aid、type=group、owner 为当前群主，携带与 owner.md 配对的 ownership.statement；不再要求旧 entity_cert_fingerprint，主签不含 signer_aid，也不使用 ownership_proof／ownership_release。实体私钥主签，当前 owner token 上传，无需群登录，可选 owner 附签，存在时必须全块验证。SDK 先写 owner.md，再发布实体声明并确认共识；仍校验当前 owner/rekey 证书代际，完整多签与 CAS 见 [协议 §2.5](../protocol/Ownership协议定义2.1.md#25-grouporg-名片的实体主签与-owner-上传)。
 
 管理员的 group.update、group.index 或文件权限不授予现代群名片上传权。NS 新鲜校验当前 owner、生命周期及群当前证书；Group 旧群证书单签、群身份上传始终兼容，仍执行权威检查与文件 CAS，不据此开放 Org。转移完成后新 owner 用新群材料主签并以本人 token 上传；解散后禁止发布。普通 Ownership Facade 对群目标返回 not_applicable。
 
-新 SDK 群名片全部 NS GET/HEAD/PUT 含 fresh 携带 X-AUN-Signature-Format: multi-v1，返回完整多签及对应 ETag；旧客户端按首签投影读取，多块投影不改完整存储，单块保持原文。实体 fresh GET 还必须同时携带 X-AUN-Ownership-Check: 1 和 Cache-Control: no-cache，Check 头才触发 NS 绕 LRU 全块新鲜验证，不进入通用账本；fresh 返回 not_applicable、实体 current/stale、权威 owner/证书指纹；真正 missing 为 404 且带权威头，无 ETag，依赖失败为 503。verified 下载全块验证历史证书和原文，历史验签不能作为当前授权；上传仍校验当前生命周期和证书，实体代际冲突 409、ETag 冲突 412。
+新 SDK 群名片全部 NS GET/HEAD/PUT 含 fresh 携带 X-AUN-Signature-Format: multi-v1，返回完整多签及对应 ETag；旧客户端按首签投影读取，多块投影不改完整存储，单块保持原文。实体 fresh GET 还必须同时携带 X-AUN-Ownership-Check: 1 和 Cache-Control: no-cache，Check 头触发 NS 绕 LRU 全块新鲜验证；现代群声明参与双文件共识，缺少 ownership 的历史群仍返回 not_applicable 及实体校验元数据。真正 missing 为 404 且带权威头，无 ETag，依赖失败为 503。verified 下载全块验证历史证书和原文，历史验签不能作为当前授权；上传仍校验当前生命周期和证书，实体代际冲突 409、ETag 冲突 412。
 
 ### group.create
 
-创建群组。调用者自动成为 owner，无需额外 Ownership 绑定。支持创建命名群（传入 `group_name` + `public_key`）。owner 本地生成、持有群私钥，服务端只接收公钥；证书导入 owner 本地后按本节 owner 规则发布群名片。新建群主标识以 `group_aid` 为准；`group_id` 仅作为兼容字段保留。
+创建群组。调用者自动成为 owner，无需额外调用普通 Ownership 绑定 Facade；SDK 生命周期流程同步完成配对声明和共识确认。支持创建命名群（传入 `group_name` + `public_key`）。owner 本地生成、持有群私钥，服务端只接收公钥；证书导入 owner 本地后按本节 owner 规则发布群名片。新建群主标识以 `group_aid` 为准；`group_id` 仅作为兼容字段保留。
 
 四种 SDK 的高层建群接口均支持崩溃恢复。命名群在 RPC 前持久化群密钥，并按 `group_name + public_key` 重放已提交结果；匿名群在 RPC 前持久化群密钥和创建上下文，重试会取回同一数字群并继续 `group_aid` 证书绑定与 `agent.md` 上传。群记录、群主成员、成员索引、入群设置、首个 `group.changed` 事件及匿名创建映射由服务端在同一数据库事务提交；证书服务和存储服务不参与该数据库事务，由 SDK pending 状态和服务端幂等重放恢复。
 
@@ -241,7 +241,7 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 
 ### group.bind_aid
 
-为已有普通群绑定命名 AID（升级为命名群）。仅群主可操作。这是群身份生命周期操作，不建立 Ownership 2.1 关系；绑定后身份材料由当前 owner 持有。
+为已有普通群绑定命名 AID（升级为命名群）。仅群主可操作。这是群身份生命周期操作，不调用普通 Ownership 绑定 Facade；绑定后身份材料由当前 owner 持有，SDK 生命周期流程完成配对声明及共识确认。
 
 **参数**：
 
@@ -621,7 +621,7 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 
 ### group.bind_group_aid
 
-为匿名群绑定群身份（group_aid）。需要 owner 权限。这不是 Ownership 绑定；成功后当前 owner 持有群身份材料，并以本人身份代签代上传群名片。
+为匿名群绑定群身份（group_aid）。需要 owner 权限。这是专属群身份绑定，不调用普通 Ownership 绑定 Facade；成功后当前 owner 持有群身份材料，以实体私钥主签、本人 token 上传群名片，SDK 完成配对 owner.md 声明与共识确认。
 
 **幂等保证**：
 - 已绑定且公钥匹配：返回已绑定的 group_aid 和证书