@agentunion/fastaun 0.5.31 → 0.5.33

package/CHANGELOG.md

@@ -6,7 +6,75 @@
 
 ---
 
-## 0.5.31 — 未发布
+## 0.5.33 — 未发布
+
+按当前工作区未提交变更整理；四端接口、实现差异和服务依赖见 [parity 0.5.33](../python/CHANGES_FOR_PARITY.md#v0533)。
+
+### 控制消息兼容与降级
+
+- P2P／群 `control` 发送在未协商分类能力时，发送前移除外层及可变保护头中的类别，按普通消息投递；已协商时保留控制类别。明文控制消息继续使用明文发送路径，需配套 Gateway／Message／Group 正确路由及确认发送者身份。
+- P2P `sdk_control` 缺少分类或协议协商时移除外层路由类别，保留 E2EE 信封中的类别、协议及版本，由接收 SDK 消费。明文 `sdk_control` 和群 `sdk_control` 仍在本地拒绝，参数与受保护元数据冲突仍报错。
+- 解密后的消息未携带受保护 `message_class` 时按 `normal` 校验，修复普通消息及群 volatile 普通流的类别误判；群普通 TTL 发送不再受到控制类协商门禁影响。
+
+### Ownership 批量申请与审批
+
+- `bindOwneraid`、`bindSubaid`、`transferSubaid` 增加可选 `{ batchId }`，使用 UUIDv4；请求消息、任务持久化及结果携带 `batch_id`。批次纳入固定任务上下文校验，重放请求不能增删或更换批次；原有单次调用保持兼容。
+- 新增 `acceptOwnershipRequests(operationIds)`／`rejectOwnershipRequests(operationIds, reason?)`，去重后逐项审批并返回每项任务或错误及汇总；批次用于应用聚合展示，每项沿用已认证请求和现有 Ownership 流程。导出 `OwnershipRequestOptions` 与 `OwnershipApprovalBatchResult` 类型。
+
+### agent.md 与共识查询
+
+- 连接后先读取本地 `agent.md`；本地正文与已观察 ETag／校验记录一致时复用，不再因新 Client 或连接成功强制首查。共识查询可复用本地持久快照，并核对锁状态、ETag、正文摘要及关系声明；未达共识、缺失、内容变化或 `force=true` 时重新查询。
+- 群／组织首访同样优先复用有效本地共识；绑定、审批、转移等管理流程保留强制刷新。Ownership 事件清除相关快照，异步查询完成后检查 Client 与观察代际，避免旧结果覆盖新状态。
+
+### Storage 批量 ACL 与缓存
+
+- VFS 和 LowLevel 的 `setAcl`／`removeAcl` 增加 `granteeAids` 数组，映射 RPC `grantee_aids`；保留 `granteeAid`／`grantee_aid` 兼容。数组可含一个或多个 AID，`maxUses` 对每个被授权 AID 分别生效，批量处理依赖配套 Storage 服务。
+- ACL 授予／撤销 RPC 失败时同样失效受影响路径的读缓存，覆盖服务端已完成部分操作后报错的情况；保留原始错误和无关路径缓存，Raw／LowLevel／VFS 共用该处理。
+
+### 版本与验证
+
+- 包配置、锁文件、运行时及相关测试版本引用统一为 `0.5.33`；版本升级阶段四端版本一致性检查、Node 加密回环 17 项和类型检查通过。
+- 补充控制消息降级、Ownership 批次／本地共识、批量 ACL 与失败缓存失效的回归覆盖；跨 SDK 工具增加分类协商开关及线上发送观测。本轮仅整理文档，未重跑这些功能的全量或跨 SDK 验收。
+
+## 0.5.32 — 未发布
+
+相对已发布 `0.5.31` 整理，源码增量以 `2df732673` 为对照；四端实现与验证边界见 [parity 0.5.32](../python/CHANGES_FOR_PARITY.md#v0532)。
+
+### 轻量事件发布订阅
+
+- 新增统一入口 `aunClient.EventService`，通过 `bus_aid` 管理 Pub／Sub／Bus；同一 Client 在一个 Bus 绑定一种角色，可在不同 Bus 担任不同角色。提供启停、排空、配置、授权、发布订阅、目录和统计接口。
+- 支持 AID／事件白名单及凭证授权；白名单 `*` 表示不限制，建议仅用于本机多 Agent。凭证由本机 Bus AID 签发、Bus SDK 校验，AUN 凭证服务提供登记与状态证明；签发、撤销及统计仅由正在运行的本机 Bus Facade 调用。
+- 默认凭证适配器将签发／撤销材料保存到自身 AID 的 `aun.db`，元数据键为 `pubsub_credentials_v1`；支持 `credentialOptions.state` 覆盖。Bus 配置和服务状态仍使用显式 `state.load/save`。
+- `authorize` 返回获准事件目录，SDK 自动续页后统一提交授权和目录缓存；多事件发布订阅无需再显式调用 `catalog`。事件 `data` 为 JSON 对象，应用通过 `onEvent` 或 `nextEvent` 接收。
+- 请求、回复及事件使用加密 P2P `sdk_control`、`aun.pubsub/1` 和正 TTL 非持久消息，回复与事件按设备／slot 定向。Bus 通过 `message.evtsvc.*` 保证同 AID 单实例，30 秒续期、100 秒有效；Pub／Sub 授权 1 小时续期、默认 200 分钟有效，受凭证及状态证明更早期限约束。
+- `publish` 有界异步入队并返回 `event_id`；`waitPublished`／`onPublish` 获取完成结果。`none` 以 AUN 接受发送为完成，`accepted` 以 Bus 受理为完成，订阅应用通过独立事件回调接收内容。
+
+### 容量、公平调度与 RPC
+
+- Pull 到 fanout 的交接最多 64 条，Bus 保留正文总量上限为 64 MiB；全局容量满时暂停相关 Pull，容量释放后恢复。单 AID 额度满时跳过该目标并计入 `skipped_overloaded`。
+- 按订阅 AID 串行发送，不同 AID 可并发，发布者与订阅者按成本公平调度；RPC 保持总额度 16、后台 8，新增事件 4／Pull 4 子额度，前台请求排队或写缓冲积压时暂停新事件发送。
+- 绝对截止时间贯穿排队、E2EE 准备及密钥查询，实际发送前重算剩余 TTL 并签名；过期任务不继续发送。Node 传输 Worker 同步限流和事件背压状态。
+- 识别限流错误后，后台请求及 token／凭证刷新遵守至少 60 秒或服务端更长的等待时间；token 刷新限流按等待时间重调度，避免误触发认证重连。
+
+### 消息恢复与连接
+
+- 分类消息 Pull 合入既有消息交付后台队列，连接后恢复已保存的分类流，替代独立控制流恢复扫描。应用 `normal/control` 流等待对应处理器注册，`sdk_control` 继续由 SDK 内部消费；事件入口未接管时保留游标并等待容量恢复。
+- 后台群目录统一分页读取并合并同身份／连接的并发请求，提案自动确认复用同一目录；检查游标前进，身份或连接切换后不使用旧结果。
+- Gateway 候选发现绑定当前连接尝试，避免旧连接任务覆盖新连接状态。
+
+### VFS Cache、Storage 与 Ownership
+
+- 修复 VFS／Storage／GroupFS 缓存失效范围过大的问题：按 owner、bucket、路径及受影响列表定向失效内存和持久缓存，阻止相关在途旧读回填，保留无关缓存及在途读取。删除／递归删除／重命名后清理受影响路径（含重命名源、目标）的 VFS 写版本记录。
+- 限流等待期间优先复用仍有效的读缓存，此时 `no_cache`／`consistency=authoritative` 可降级为缓存读取；显式签名和 Range 请求保持原限制。缓存未命中等待限流解除，新缓存 TTL 从实际回源开始计时；强制刷新遇限流保留已有有效缓存，不提前清空。
+- 显式提供 `expected_version` 时，只有写权限或已核实挂载导致无法权威预读，可携原版本交服务端检查；未指定版本仍需完成预读。文件 rename 预检显式绕过读缓存。
+- 本地 Ownership 绑定／转移的 subaid 类型从仅 `agent` 扩展为非空且非 `human/group/org` 类型；owner 和新 owner 仍限 `human/agent`。
+
+### 版本与已有验证
+
+- 当前包与运行时目标版本为 `0.5.32`。用法及协议分别见 [应用集成指南](../docs/sdk/AUN事件发布订阅应用集成指南.md) 与 [开发移植指南](../docs/sdk/AUN事件发布订阅开发移植指南.md)。
+- 沿用的 Ubuntu Docker EventService 专项为四种 Bus 各 32 项、共 [128/128 互通流程](../tests/cross-sdk/artifacts/pubsub-4sdk-20261105/remove-manager-acceptance/final-acceptance-summary.json)，覆盖白名单和凭证授权；不代表本版全部增量的全量验收。本轮仅整理文档，未重跑 SDK 测试。
+
+## 0.5.31 — 已发布
 
 ### Group／Org Ownership
 

package/_packed_docs/CHANGELOG.md

@@ -6,7 +6,75 @@
 
 ---
 
-## 0.5.31 — 未发布
+## 0.5.33 — 未发布
+
+按当前工作区未提交变更整理；四端接口、实现差异和服务依赖见 [parity 0.5.33](../python/CHANGES_FOR_PARITY.md#v0533)。
+
+### 控制消息兼容与降级
+
+- P2P／群 `control` 发送在未协商分类能力时，发送前移除外层及可变保护头中的类别，按普通消息投递；已协商时保留控制类别。明文控制消息继续使用明文发送路径，需配套 Gateway／Message／Group 正确路由及确认发送者身份。
+- P2P `sdk_control` 缺少分类或协议协商时移除外层路由类别，保留 E2EE 信封中的类别、协议及版本，由接收 SDK 消费。明文 `sdk_control` 和群 `sdk_control` 仍在本地拒绝，参数与受保护元数据冲突仍报错。
+- 解密后的消息未携带受保护 `message_class` 时按 `normal` 校验，修复普通消息及群 volatile 普通流的类别误判；群普通 TTL 发送不再受到控制类协商门禁影响。
+
+### Ownership 批量申请与审批
+
+- `bindOwneraid`、`bindSubaid`、`transferSubaid` 增加可选 `{ batchId }`，使用 UUIDv4；请求消息、任务持久化及结果携带 `batch_id`。批次纳入固定任务上下文校验，重放请求不能增删或更换批次；原有单次调用保持兼容。
+- 新增 `acceptOwnershipRequests(operationIds)`／`rejectOwnershipRequests(operationIds, reason?)`，去重后逐项审批并返回每项任务或错误及汇总；批次用于应用聚合展示，每项沿用已认证请求和现有 Ownership 流程。导出 `OwnershipRequestOptions` 与 `OwnershipApprovalBatchResult` 类型。
+
+### agent.md 与共识查询
+
+- 连接后先读取本地 `agent.md`；本地正文与已观察 ETag／校验记录一致时复用，不再因新 Client 或连接成功强制首查。共识查询可复用本地持久快照，并核对锁状态、ETag、正文摘要及关系声明；未达共识、缺失、内容变化或 `force=true` 时重新查询。
+- 群／组织首访同样优先复用有效本地共识；绑定、审批、转移等管理流程保留强制刷新。Ownership 事件清除相关快照，异步查询完成后检查 Client 与观察代际，避免旧结果覆盖新状态。
+
+### Storage 批量 ACL 与缓存
+
+- VFS 和 LowLevel 的 `setAcl`／`removeAcl` 增加 `granteeAids` 数组，映射 RPC `grantee_aids`；保留 `granteeAid`／`grantee_aid` 兼容。数组可含一个或多个 AID，`maxUses` 对每个被授权 AID 分别生效，批量处理依赖配套 Storage 服务。
+- ACL 授予／撤销 RPC 失败时同样失效受影响路径的读缓存，覆盖服务端已完成部分操作后报错的情况；保留原始错误和无关路径缓存，Raw／LowLevel／VFS 共用该处理。
+
+### 版本与验证
+
+- 包配置、锁文件、运行时及相关测试版本引用统一为 `0.5.33`；版本升级阶段四端版本一致性检查、Node 加密回环 17 项和类型检查通过。
+- 补充控制消息降级、Ownership 批次／本地共识、批量 ACL 与失败缓存失效的回归覆盖；跨 SDK 工具增加分类协商开关及线上发送观测。本轮仅整理文档，未重跑这些功能的全量或跨 SDK 验收。
+
+## 0.5.32 — 未发布
+
+相对已发布 `0.5.31` 整理，源码增量以 `2df732673` 为对照；四端实现与验证边界见 [parity 0.5.32](../python/CHANGES_FOR_PARITY.md#v0532)。
+
+### 轻量事件发布订阅
+
+- 新增统一入口 `aunClient.EventService`，通过 `bus_aid` 管理 Pub／Sub／Bus；同一 Client 在一个 Bus 绑定一种角色，可在不同 Bus 担任不同角色。提供启停、排空、配置、授权、发布订阅、目录和统计接口。
+- 支持 AID／事件白名单及凭证授权；白名单 `*` 表示不限制，建议仅用于本机多 Agent。凭证由本机 Bus AID 签发、Bus SDK 校验，AUN 凭证服务提供登记与状态证明；签发、撤销及统计仅由正在运行的本机 Bus Facade 调用。
+- 默认凭证适配器将签发／撤销材料保存到自身 AID 的 `aun.db`，元数据键为 `pubsub_credentials_v1`；支持 `credentialOptions.state` 覆盖。Bus 配置和服务状态仍使用显式 `state.load/save`。
+- `authorize` 返回获准事件目录，SDK 自动续页后统一提交授权和目录缓存；多事件发布订阅无需再显式调用 `catalog`。事件 `data` 为 JSON 对象，应用通过 `onEvent` 或 `nextEvent` 接收。
+- 请求、回复及事件使用加密 P2P `sdk_control`、`aun.pubsub/1` 和正 TTL 非持久消息，回复与事件按设备／slot 定向。Bus 通过 `message.evtsvc.*` 保证同 AID 单实例，30 秒续期、100 秒有效；Pub／Sub 授权 1 小时续期、默认 200 分钟有效，受凭证及状态证明更早期限约束。
+- `publish` 有界异步入队并返回 `event_id`；`waitPublished`／`onPublish` 获取完成结果。`none` 以 AUN 接受发送为完成，`accepted` 以 Bus 受理为完成，订阅应用通过独立事件回调接收内容。
+
+### 容量、公平调度与 RPC
+
+- Pull 到 fanout 的交接最多 64 条，Bus 保留正文总量上限为 64 MiB；全局容量满时暂停相关 Pull，容量释放后恢复。单 AID 额度满时跳过该目标并计入 `skipped_overloaded`。
+- 按订阅 AID 串行发送，不同 AID 可并发，发布者与订阅者按成本公平调度；RPC 保持总额度 16、后台 8，新增事件 4／Pull 4 子额度，前台请求排队或写缓冲积压时暂停新事件发送。
+- 绝对截止时间贯穿排队、E2EE 准备及密钥查询，实际发送前重算剩余 TTL 并签名；过期任务不继续发送。Node 传输 Worker 同步限流和事件背压状态。
+- 识别限流错误后，后台请求及 token／凭证刷新遵守至少 60 秒或服务端更长的等待时间；token 刷新限流按等待时间重调度，避免误触发认证重连。
+
+### 消息恢复与连接
+
+- 分类消息 Pull 合入既有消息交付后台队列，连接后恢复已保存的分类流，替代独立控制流恢复扫描。应用 `normal/control` 流等待对应处理器注册，`sdk_control` 继续由 SDK 内部消费；事件入口未接管时保留游标并等待容量恢复。
+- 后台群目录统一分页读取并合并同身份／连接的并发请求，提案自动确认复用同一目录；检查游标前进，身份或连接切换后不使用旧结果。
+- Gateway 候选发现绑定当前连接尝试，避免旧连接任务覆盖新连接状态。
+
+### VFS Cache、Storage 与 Ownership
+
+- 修复 VFS／Storage／GroupFS 缓存失效范围过大的问题：按 owner、bucket、路径及受影响列表定向失效内存和持久缓存，阻止相关在途旧读回填，保留无关缓存及在途读取。删除／递归删除／重命名后清理受影响路径（含重命名源、目标）的 VFS 写版本记录。
+- 限流等待期间优先复用仍有效的读缓存，此时 `no_cache`／`consistency=authoritative` 可降级为缓存读取；显式签名和 Range 请求保持原限制。缓存未命中等待限流解除，新缓存 TTL 从实际回源开始计时；强制刷新遇限流保留已有有效缓存，不提前清空。
+- 显式提供 `expected_version` 时，只有写权限或已核实挂载导致无法权威预读，可携原版本交服务端检查；未指定版本仍需完成预读。文件 rename 预检显式绕过读缓存。
+- 本地 Ownership 绑定／转移的 subaid 类型从仅 `agent` 扩展为非空且非 `human/group/org` 类型；owner 和新 owner 仍限 `human/agent`。
+
+### 版本与已有验证
+
+- 当前包与运行时目标版本为 `0.5.32`。用法及协议分别见 [应用集成指南](../docs/sdk/AUN事件发布订阅应用集成指南.md) 与 [开发移植指南](../docs/sdk/AUN事件发布订阅开发移植指南.md)。
+- 沿用的 Ubuntu Docker EventService 专项为四种 Bus 各 32 项、共 [128/128 互通流程](../tests/cross-sdk/artifacts/pubsub-4sdk-20261105/remove-manager-acceptance/final-acceptance-summary.json)，覆盖白名单和凭证授权；不代表本版全部增量的全量验收。本轮仅整理文档，未重跑 SDK 测试。
+
+## 0.5.31 — 已发布
 
 ### Group／Org Ownership
 

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

@@ -0,0 +1,350 @@
+# AUN SDK 0.5.32 应用集成指南
+
+面向应用开发者，说明从已发布的 0.5.31 接入当前目标版本 0.5.32 时需要调整什么。示例使用 TypeScript；四端方法、源码与验证边界见 [parity 0.5.32](../../python/CHANGES_FOR_PARITY.md#v0532)，SDK 实现流程见[开发与移植指南](0.5.32-SDK开发与移植指南.md)。0.5.32 当前为未发布目标，安装产物和配套服务部署需分别核对。
+
+## 1. 本版变化与整体架构
+
+| 范围 | 本版变化 | 应用需要做什么 |
+| --- | --- | --- |
+| EventService | 新增轻量 Bus／Pub／Sub 门面、两种授权、目录及设备定向事件 | 启动 Bus，Pub／Sub 鉴权后发布订阅 |
+| 调度与恢复 | 事件／Pull 额度隔离，分类流共用后台调度，连接恢复已保存的流 | 注册应用处理器，处理有界队列和超时结果 |
+| VFS Cache | 资源定向失效、限流期间复用有效缓存、清理旧写版本 | 明确读取新鲜度，冲突后重新读取 |
+| Ownership | 普通 subaid 支持 service 等类型 | 继续使用现有绑定／转移入口 |
+| 单端补齐 | JS Owner 通知恢复、Python 撤销状态恢复 | 保留身份仓库和既有消费接线 |
+
+群／组织共识、`message_classes_v2`、去掉 `scan_proof`、严格携版本写入已属于 0.5.31，继续按[上一版指南](0.5.31-SDK应用集成指南.md)使用。
+
+```mermaid
+%%{init: {"theme":"base","themeVariables":{"fontFamily":"Microsoft YaHei, sans-serif","fontSize":"14px","lineColor":"#64748b"},"flowchart":{"curve":"linear","nodeSpacing":24,"rankSpacing":38}}}%%
+flowchart TB
+    subgraph APPS["应用与 SDK"]
+        direction LR
+        P["Pub AID<br/>EventService · 发布"]:::pub
+        B["Bus AID<br/>EventService · 目录 / 授权 / 订阅 / 分发"]:::bus
+        S["Sub AID<br/>EventService · 回调 / 等待"]:::sub
+        V["应用 AID<br/>storage · VFS Cache"]:::storage
+    end
+    G["Gateway<br/>可信 AID / 设备身份 · RPC 与消息转发"]:::gateway
+    subgraph SERVICES["AUN 服务"]
+        direction LR
+        M["Message<br/>唯一 Bus 实例租约<br/>设备定向 TTL 收件箱"]:::infra
+        C["Credential<br/>凭证登记 / 状态证明 / 撤销"]:::infra
+        T["Storage<br/>对象 / 文件 / 最终版本 CAS"]:::infra
+    end
+    P <-->|"发布与结果"| G
+    B <-->|"承接发布并分发"| G
+    S <-->|"授权 / 订阅 / 事件"| G
+    V <-->|"读取 / 条件写入"| G
+    G <--> M
+    G <--> C
+    G <--> T
+    classDef pub fill:#eff6ff,stroke:#93c5fd,color:#1e3a8a,rx:10,ry:10
+    classDef bus fill:#eef2ff,stroke:#818cf8,stroke-width:2px,color:#312e81,rx:10,ry:10
+    classDef sub fill:#ecfdf5,stroke:#6ee7b7,color:#065f46,rx:10,ry:10
+    classDef storage fill:#fdf4ff,stroke:#d8b4fe,color:#6b21a8,rx:10,ry:10
+    classDef gateway fill:#fff7ed,stroke:#fdba74,color:#9a3412,rx:10,ry:10
+    classDef infra fill:#f8fafc,stroke:#cbd5e1,color:#334155,rx:10,ry:10
+    style APPS fill:#ffffff,stroke:#e2e8f0,rx:12,ry:12
+    style SERVICES fill:#f8fafc,stroke:#e2e8f0,rx:12,ry:12
+```
+
+一次事件经 Message 先到 Bus，再由 Bus 发给订阅设备。Message 维护唯一承接实例与通用消息投递；事件目录、权限、订阅表和 fanout 留在 Bus SDK。凭证由 Bus AID 私钥签发、Bus SDK 校验，Credential 服务提供登记与状态证明。图中 Gateway 合并表示各客户端的接入连接。
+
+## 2. 准备身份与统一入口
+
+准备各自已加载身份、连接就绪的 Client，加载与连接沿用[快速开始](01-快速开始.md)和[连接与认证](04-连接与认证.md)。以下片段使用应用已准备的对象，不另创建服务地址：
+
+```ts
+import type { AUNClient } from '@agentunion/fastaun';
+declare const busClient: AUNClient;
+declare const pubClient: AUNClient;
+declare const subClient: AUNClient;
+declare function handleTaskCompleted(data: unknown): Promise<void>;
+declare function handleTaskFailed(data: unknown): Promise<void>;
+const busAid = String(busClient.aid);
+const eventNames = ['task.completed', 'task.failed'];
+```
+
+| SDK | 统一入口 | 典型方法 |
+| --- | --- | --- |
+| Python | `client.EventService` | `issue_grant`、`wait_published`、`on_event` |
+| TS／JS | `client.EventService` | `issueGrant`、`waitPublished`、`onEvent` |
+| Go | `client.EventService()` | `IssueGrant`、`WaitPublished`、`OnEvent`；网络及等待方法传 context |
+
+所有事件方法以 `bus_aid` 指定服务。一个 Client 对一个 Bus 只绑定一种 `bus/pub/sub` 角色，`close` 后仍保留绑定；不同 Bus 可使用不同角色。Bus 启动要求 `bus_aid` 为自身 AID；远端 Pub／Sub 调用 `authorize` 自动初始化。
+
+```ts
+const bus = busClient.EventService;
+const pub = pubClient.EventService;
+const sub = subClient.EventService;
+const catalog = {
+  'task.completed': { description: '任务完成', schema_version: 1, default_ttl_seconds: 30, max_ttl_seconds: 300 },
+  'task.failed': { description: '任务失败', schema_version: 1, default_ttl_seconds: 15, max_ttl_seconds: 120 },
+};
+```
+
+下面白名单与凭证场景二选一。Bus 自己也需发布时，另用一个 Client 承担 `pub` 角色并授予权限。
+
+## 3. 白名单模式：启动、订阅与发布多个事件
+
+### 3.1 Bus 启动
+
+```ts
+await bus.start(busAid, { catalog, allowlist: {
+  'task.completed': { publish_aids: [String(pubClient.aid)], subscribe_aids: [String(subClient.aid)] },
+  'task.failed': { publish_aids: [String(pubClient.aid)], subscribe_aids: [String(subClient.aid)] },
+} });
+```
+
+同一 Bus AID 同时只允许一个设备实例运行，后启动者收到 `DEVICE_CONFLICT`。白名单事件项与 AID 数组可配置 `*`，表示不限制该项；建议仅用于本机受控多 Agent。通配不创建目录外事件，调用仍传完整事件名。
+
+```mermaid
+sequenceDiagram
+    participant P as Pub SDK
+    participant S as Sub SDK
+    participant G as Gateway
+    participant M as Message
+    participant B as Bus SDK
+    B->>G: start 后注册 message.evtsvc.register
+    G->>M: 当前 Bus AID / 设备 / slot
+    M-->>B: 经 Gateway 返回实例租约
+    S->>G: authorize(sub, 两个事件)
+    G->>M: SDK 控制消息
+    M->>B: 唯一承接实例收取
+    B-->>S: 经消息通道定向回复：租约与目录
+    S->>S: 自动取齐目录，应用注册 onEvent
+    S->>B: 经消息通道 subscribe
+    B-->>S: 订阅生效
+    P->>B: 经消息通道 authorize(pub)，自动缓存目录
+    P->>P: publish 立即返回 event_id
+    P->>G: 后台发送带原 TTL 的 publish
+    G->>M: E2EE P2P sdk_control
+    M->>B: 设备定向 Pull / Push
+    B->>B: 校验并接入有界 fanout
+    opt replyMode = accepted
+        B-->>P: 经消息通道定向 publish.result
+    end
+    B->>G: 给实际订阅设备发送 event
+    G->>M: 剩余 TTL 内存消息
+    M-->>S: 经 Gateway 定向投递
+    S->>S: SDK 校验后调用应用 handler
+```
+
+跨 AID 的简写箭头均经过 Gateway 与 Message；使用 E2EE P2P `sdk_control`、`aun.pubsub/1` 及正 TTL 非持久消息。SDK 自动处理加密、Pull、ACK 与设备路由。
+
+### 3.2 Sub：鉴权并登记回调
+
+```ts
+await sub.authorize(busAid, 'sub', 'allowlist', eventNames);
+const onTaskEvent = async (event: Record<string, unknown>) => {
+  if (event.event_name === 'task.completed') await handleTaskCompleted(event.data);
+  if (event.event_name === 'task.failed') await handleTaskFailed(event.data);
+};
+const stopEvents = sub.onEvent(busAid, onTaskEvent);
+await sub.subscribe(busAid, eventNames);
+```
+
+`authorize` 同时取得获准目录；SDK 自动续页，成功后才统一提交新授权和目录缓存，无需再调用 `catalog`。`subscribe` 回复成功后生效，每个设备可只订阅获准事件的一部分。
+
+应用也可选择 `await sub.nextEvent(busAid, 5)`，超时单位为秒；有回调时新事件走回调路径。handler 按顺序执行，慢处理占用本地有界容量，失败不要求 Bus 重发。
+
+### 3.3 Pub：异步发布并观察结果
+
+```ts
+await pub.authorize(busAid, 'pub', 'allowlist', eventNames);
+const options = { ttlSeconds: 30, replyMode: 'accepted' as const };
+const completedId = await pub.publish(busAid, 'task.completed',
+  { task_id: 'T1', status: 'done' }, options);
+const failedId = await pub.publish(busAid, 'task.failed',
+  { task_id: 'T2', reason: 'timeout' }, options);
+await Promise.all([pub.waitPublished(busAid, completedId), pub.waitPublished(busAid, failedId)]);
+```
+
+| 观察点 | 应用可确认什么 |
+| --- | --- |
+| `publish` 返回 ID | 本地有界队列已收下任务 |
+| 默认 `none` 的完成结果 | AUN 接受了发往 Bus 的消息 |
+| `accepted` 的完成结果 | Bus 已校验并内存受理，随后后台分发 |
+| Sub handler／`nextEvent` 收到 | 当前订阅设备的 SDK 已收到有效事件 |
+
+`data` 为 JSON 对象，连同封装受 64 KiB 明文预算限制；TTL 为整数 1—3600 秒且不超过目录上限。排队与两跳投递共用原期限。超时后查询或复用原 `eventId` 和原内容重试；同 ID 换内容会冲突。适用于在线通知，消息在 TTL 内可能补收，事件记录和去重不跨重启保证恢复。
+
+## 4. 凭证模式：Bus 本地审批与签发
+
+此模式从同样已连接的三方 Client 开始，使用 §2 的 `catalog`。Bus 以自身 AUN 身份接入；宿主应用完成自己的业务审批后调用本地管理门面。
+
+```ts
+await bus.start(busAid, { catalog });
+```
+
+```mermaid
+sequenceDiagram
+    participant A as Bus 宿主应用
+    participant B as Bus SDK
+    participant G as Gateway
+    participant C as Credential
+    participant X as Pub / Sub SDK
+    A->>B: 本地 start(bus_aid, catalog)
+    Note over B,G: 自动经 Message 注册唯一承接实例
+    A->>A: 审批主体、事件、操作和期限
+    A->>B: 本地 issueGrant
+    B->>B: 用 Bus 私钥签名
+    B->>G: credential.register
+    G->>C: 登记凭证
+    C-->>B: 经 Gateway 返回回执
+    B-->>A: grant / cid / receipt
+    A-->>X: 应用业务通道交付完整 grant
+    X->>B: 经 Gateway + Message authorize(grant)
+    B->>B: 校验签发链、主体、scope 与请求绑定
+    opt 需要状态证明
+        B->>G: credential.status
+        G->>C: 当前状态
+        C-->>B: 经 Gateway 返回签名证明
+    end
+    B-->>X: 定向返回授权租约及目录
+```
+
+分别签发订阅和发布权限，两个事件展开配置：
+
+```ts
+const subGrant = await bus.issueGrant(busAid, {
+  subject_aid: String(subClient.aid),
+  scope: [
+    { event_name: 'task.completed', action: 'subscribe' },
+    { event_name: 'task.failed', action: 'subscribe' },
+  ],
+  grant_expires_at: Date.now() + 24 * 3600 * 1000,
+});
+```
+
+```ts
+const pubGrant = await bus.issueGrant(busAid, {
+  subject_aid: String(pubClient.aid),
+  scope: [
+    { event_name: 'task.completed', action: 'publish' },
+    { event_name: 'task.failed', action: 'publish' },
+  ],
+  grant_expires_at: Date.now() + 24 * 3600 * 1000,
+});
+```
+
+```ts
+await sub.authorize(busAid, 'sub', 'credential', eventNames,
+  subGrant.grant as Record<string, unknown>);
+const stopEvents = sub.onEvent(busAid, async event => {
+  if (event.event_name === 'task.completed') await handleTaskCompleted(event.data);
+  if (event.event_name === 'task.failed') await handleTaskFailed(event.data);
+});
+await sub.subscribe(busAid, eventNames);
+await pub.authorize(busAid, 'pub', 'credential', eventNames,
+  pubGrant.grant as Record<string, unknown>);
+```
+
+凭证场景跳过 §3 的白名单启动与鉴权；随后执行 §3.3 从 `const options` 开始的发布片段。`grant_expires_at` 为 Unix 毫秒；向对方交付完整 `grant`，CID 仅用于引用和撤销。
+
+Bus 本地 `revokeGrant(busAid, { cid: subGrant.cid })` 撤销；`stats(busAid, { event_name: 'task.completed' })` 查看本次运行计数。仅已启动的本机 Bus 可签发、撤销及查询统计。详细登记恢复与回执处理见[事件集成指南 §4](AUN事件发布订阅应用集成指南.md#4-场景二应用审批与凭证授权)。
+
+## 5. 设备、租约、容量与关闭
+
+| 范围 | 应用需要知道的行为 |
+| --- | --- |
+| 设备订阅 | 每设备／slot 分别鉴权与订阅；只向实际订阅实例投递，发布响应仅回原设备 |
+| Bus 实例 | 自动注册，30 秒续期，100 秒有效；失租停止承接，需恢复实例后再接收 |
+| Pub／Sub 授权 | 每 1 小时续期，默认租约 200 分钟、受凭证到期限制，以回复为准；状态证明过期由 Bus 按需复核，复核失败暂停操作 |
+| 重连／重启 | 重连按原意图恢复授权及订阅；Bus 重启需恢复配置，运行时订阅和队列不作为事件账本 |
+| 发布／接收容量 | Pub／Sub 各默认 256 条／1 MiB；满载可能拒绝或跳过，应用处理完成错误与统计 |
+| Bus 正文与交接 | Pull 到 fanout 合计最多 64 条，保留正文硬封 64 MiB；这是正文预算，不是进程 RSS 上限 |
+| 公平与 RPC | 按 AID 公平分发；单 AID 满跳过，全局满对 Pull 背压。总 RPC 16，后台 8，其中事件 4、Pull 4 |
+
+普通 RPC 有前台调度机会。发布与续租共用同一加密消息流，满载后同流尚未拉取的管理消息仍可能等待容量；同页和完整 Push 的管理消息可继续处理。
+
+| SDK | 默认凭证材料 | Bus 配置保存 |
+| --- | --- | --- |
+| Python／Go | `{aun_path}/AIDs/{self-aid}/aun.db`，键 `pubsub_credentials_v1` | 显式 `state_path`／`StatePath` |
+| Node TS | 自身 AID 的 `aun.db`，同一键 | `start` 的 `state.load/save` |
+| Browser JS | IndexedDB `aun-keystore/metadata`，按自身 AID 隔离，同一键 | `state.load/save` |
+
+默认适配器自动保存凭证登记／撤销材料；TS／JS 可用 `credentialOptions.state.load/save` 覆盖。凭证材料自动保存与 Bus 配置保存分别配置。
+
+停机时先停止上游提交，再排空发布端，随后排空并关闭 Bus；关闭 Client 会联动清理门面：
+
+```ts
+await pub.drain(busAid);
+await bus.drain(busAid);
+await sub.unsubscribe(busAid, eventNames);
+stopEvents();
+await sub.close(busAid);
+await pub.close(busAid);
+await bus.close(busAid);
+```
+
+`OVERLOADED` 表示本地容量不足；`REAUTH_REQUIRED` 需恢复授权，`CATALOG_CHANGED`／`SCHEMA_MISMATCH` 需刷新目录。完成结果和 `submitted` 计数描述发送阶段，应用自行记录业务处理结果。
+
+## 6. VFS Cache：调用不变，缓存行为修正
+
+VFS 读写仍用 `client.storage`。下面选择一个尚不存在的业务路径，展示写入、读取、重命名和删除；生产应用按自身版本与冲突策略调用：
+
+```ts
+const fs = pubClient.storage;
+await fs.writeBytes('/task-T1.json', JSON.stringify({ task_id: 'T1' }), { expectedVersion: 0 });
+const bytes = await fs.readBytes('/task-T1.json', { noCache: true });
+await fs.rename('/task-T1.json', '/task-T1-done.json');
+await fs.remove('/task-T1-done.json');
+```
+
+```mermaid
+sequenceDiagram
+    participant A as 应用
+    participant V as SDK VFS / Cache
+    participant T as Storage（经 Gateway）
+    A->>V: readBytes / stat
+    alt 有仍有效缓存
+        V-->>A: 返回缓存
+    else 缓存未命中
+        opt 正处于限流等待窗口
+            V->>V: 等待窗口结束
+        end
+        V->>T: 实际回源，从此刻计算缓存 TTL
+        T-->>V: 正文 / 元数据 / read_cache 策略
+        V-->>A: 校验后返回
+    end
+    A->>V: 条件写入 / rename / remove
+    V->>T: 携带版本提交，服务端最终 CAS
+    T-->>V: 成功
+    V->>V: 失效相关内存与持久缓存索引
+    V->>V: 阻止相关旧在途结果回填
+    Note over V: 删除清理对应写版本，rename 同时清理源和目标
+```
+
+| 修复点 | 对应用的影响 |
+| --- | --- |
+| 定向失效 | 只影响相应 owner／bucket／路径、子树及列表；移动两端、复制目标、ACL 和 Group FS 同样处理，无关缓存保留 |
+| 并发旧读 | 失效后的旧结果不能重新填入缓存或供后续调用复用；原已执行读取仍可能返回其结果 |
+| 写版本清理 | 成功删除及 rename 后清理受影响源／目标记录，删除后重建不再沿用旧写版本 |
+| 限流复用 | 等待期间可复用仍有效缓存，包括 `noCache/no_cache` 和 `consistency=authoritative` 的部分路径；未命中才等待 |
+| 刷新失败 | 限流错误保留有效缓存；新缓存 TTL 从等待结束后的实际回源开始计算 |
+
+`noCache: true` 是 VFS 读选项；底层 RPC 使用 `no_cache`／`consistency`。限流下这些选项不保证每次都立即回源。显式签名、Range 和部分下载路径继续使用各自校验条件；正文摘要文件可留待正常回收，索引失效不等于立即删除正文。
+
+TS／JS／Go 补齐 Python 已有的写入例外：明确提供版本，预读权限不足或已验证挂载无法权威预读时，可携原版本交服务端 CAS；未提供版本仍失败。`expectedVersion` 为 TS VFS／低层方法选项，线上字段为 `expected_version`；`force` 继续遵守 0.5.31 的版本检查。
+
+## 7. 其它接入变化与验收
+
+| 范围 | 本版应用行为 |
+| --- | --- |
+| 分类消息恢复 | `control/sdk_control` Pull 合入既有后台调度，连接恢复已保存流；应用先注册普通／control handler，待处理流再继续。SDK 内部消费、应用交付与 ACK 保持边界，未接管不推进游标；沿用 Push 驱动，继续不做周期全量扫描 |
+| 群目录恢复 | `group.list_my` 每页 200、合并同身份／设备／slot／连接的分页任务，提案自动确认复用清单；拒绝异常游标和旧连接结果 |
+| 截止时间与前台请求 | 排队、E2EE 准备、密钥与凭证 RPC 共用绝对期限；实际发送前重算 TTL 并签名。前台请求排队或写缓冲积压时暂停新事件，配合 §5 的 16／8／4／4 额度保留普通 RPC 处理机会 |
+| 限流等待 | 识别 `4290/429/-32429/-32029`，后台派发及 token／凭证刷新按至少 60 秒或更长服务端提示等待；刷新限流不误触发认证重连。普通业务错误仍由应用处理，SDK 不统一自动重试业务写入 |
+| TS／JS 连接 | Gateway 候选发现绑定当前连接尝试，旧尝试不能覆盖新连接结果 |
+| Ownership | 本地绑定／转移允许非空且非 `human/group/org` 的 subaid，例如 service；owner／新 owner 仍限 human／agent |
+| Browser JS | Owner 名片刷新暂态失败保留意图，重连及 handler 注册后恢复待交付事件 |
+| Go 消息兼容 | 加密 Push 补充识别 `envelope` 字段，继续由 SDK 解密交付 |
+| Python 调度 | event／normal 加解密各 4 线程、各 64 项等待；控制状态读写改为异步串行 IO。连续最多 4 个 control 后给普通应用消息调度机会，应用不需创建额外线程或轮询任务 |
+| Python 凭证恢复 | 语义凭证状态保留已有撤销 `event_seq` 并核对原件摘要，兼容缺少序号的旧记录 |
+
+- [ ] 核对四 SDK 实际版本及 Message 设备定向、`message.evtsvc.*`、分类控制消息能力；凭证模式另需 Credential 服务。
+- [ ] 验收 Bus 唯一实例、两个事件的发布订阅与设备隔离、凭证撤销、断线恢复及完成错误处理。
+- [ ] 验收缓存定向失效、限流读取语义，以及删除／重命名后的版本写入。
+
+已有 Ubuntu Docker EventService [128/128 互通记录](../../tests/cross-sdk/artifacts/pubsub-4sdk-20261105/remove-manager-acceptance/final-acceptance-summary.json)覆盖四种 Bus、两种授权、四种 Pub 与四种 Sub；JS 使用 Node＋fake-indexeddb。它不代表本版 VFS／限流／Ownership 全部验收，也未覆盖真实浏览器、macOS、真实双域设备或实填 64 MiB／RSS 压力。本轮仅整理文档，未重跑 SDK 测试。