@agentunion/fastaun 0.5.33 → 0.5.35

package/_packed_docs/sdk/AUN/344/272/213/344/273/266/345/217/221/345/270/203/350/256/242/351/230/205/345/272/224/347/224/250/351/233/206/346/210/220/346/214/207/345/215/227.md

@@ -1,6 +1,6 @@
 # AUN事件发布订阅应用集成指南
 
-面向应用开发者，按 Bus 宿主、Pub 发布方、Sub 订阅方说明调用顺序、配置与结果处理；每条主流程用序列图配套实际 SDK 示例。本文对照当前工作区四端 SDK 与[事件订阅发布方案](../../../docs/AUN文档/AUN事件订阅发布方案.md)整理；源码能力、包发布和服务部署状态应分别核对。SDK 内部契约见[开发移植指南](AUN事件发布订阅开发移植指南.md)。
+面向应用开发者，按 Bus 宿主、Pub 发布方、Sub 订阅方说明调用顺序、配置与结果处理；每条主流程用序列图配套实际 SDK 示例。本文对照四端 SDK 0.5.34 工作区源码与[事件订阅发布方案](../../../docs/AUN文档/AUN事件订阅发布方案.md)整理；源码能力、包发布和服务部署状态应分别核对。SDK 内部契约见[开发移植指南](AUN事件发布订阅开发移植指南.md)，底层消息与实例 RPC 见[消息 RPC 手册](09-message-rpc-manual.md)。
 
 ## 1. 适用场景与交付边界
 
@@ -49,10 +49,10 @@ Bus SDK 决定谁能发布、谁订阅了什么，并将事件逐个发往目标
 | 应用直接控制全部参与者 | 配置事件目录和发布、订阅 AID 白名单 |
 | 应用审批后授予临时权限 | Bus 宿主应用本地签发凭证，再将完整凭证交给调用方 |
 | 同一 AID 多设备选择不同事件 | 每个设备分别鉴权和订阅，只向实际订阅的设备实例投递 |
-| 短暂断线后继续观察 | SDK 恢复授权和订阅；尚在 TTL 内的内存消息可能补收 |
+| 断线或进程重启后继续收发 | SDK 恢复授权和订阅；本地尚未完成发布的记录按原 ID、原 TTL 恢复 |
 | 必须保存历史、补齐每次变化或确认业务提交 | 当前 EventService 不提供事件日志、历史查询、重放或业务 ACK；不能据此保证每次变化都已处理 |
 
-事件只走正 TTL 的 volatile 内存消息路径。超过 TTL、队列容量耗尽、消息服务重启或 Bus 重启，都可能丢失尚未交付的事件。它适合在线通知，不提供持久消息队列的交付承诺。
+事件的两跳网络传输仍走正 TTL 的 volatile 内存消息路径。SDK 本地持久化保护尚未完成发布的记录；达到所选回复模式的成功阶段后删除本地正文。Bus 已受理后的 fanout、服务端 volatile 收件箱和事件历史不在持久恢复范围内，超过 TTL、接收容量不足、消息服务或 Bus 重启仍可能导致事件未交付。
 
 ```mermaid
 sequenceDiagram
@@ -62,11 +62,12 @@ sequenceDiagram
     C->>S: authorize（含目录）→ subscribe
     S-->>C: 订阅生效
     P->>S: authorize（含目录）
-    P->>P: publish返回event_id：本地入队
+    P->>P: 本地持久化成功后，publish返回event_id并入队
     P->>S: 后台发送publish
     opt replyMode为accepted
         S-->>P: publish.result：Bus受理
     end
+    P->>P: 达到所选成功阶段后删除本地持久正文
     S-->>C: event：按剩余TTL定向投递
     C->>C: SDK校验后交付应用
 ```
@@ -85,18 +86,18 @@ sequenceDiagram
 
 所有业务方法都以 `bus_aid` 为目标参数。应用使用统一门面，内部 Binding、租约令牌、device 和 slot 由 SDK 管理。
 
-- 同一个 client 对同一个 Bus 只能承担 `pub`、`sub`、`bus` 中一种角色；切换会报 `BUS_ROLE_CONFLICT`，`close` 不释放这个角色绑定。
+- 同一个 client 对同一个 Bus 可以同时承担 `pub`、`sub`、`bus`；发布与订阅分别调用 `authorize`，使用独立授权材料和租约。
 - 同一个 client 可以在不同 Bus 上承担不同角色。签发、撤销和统计只由已启动本地 Bus 的宿主调用。
 - 未绑定时，`start(bus_aid, ...)` 表示在当前身份启动本地 Bus，要求 `bus_aid == client.aid`。接入远端 Bus 直接调用 `authorize`，由它自动建立客户端。
-- 若 Bus 自己也要发布，使用同 AID 的另一个 AUNClient 作为 `pub`，并为它授予发布权限。
+- Bus 自己发布或订阅时，直接在同一个 EventService 上分别授权 `pub`、`sub`，仍须满足相应白名单或凭证权限。`renew`、`drain`、`close` 覆盖该 Bus 已绑定的相关角色。
 
 ### 2.1 按自己的角色阅读
 
 | 角色 | 应用需要做什么 | 代码与序列图 |
 | --- | --- | --- |
-| Bus 宿主 | 配置目录与权限 → start → 本地签发/撤销或更新名单 → stats → drain/close | §3.1、§4、§7 |
-| Pub 发布方 | authorize 自动加载目录 → 分别 publish 多个事件 → 观察完成结果 | §3.3；凭证接入见 §4.3 |
-| Sub 订阅方 | authorize 自动加载目录 → 注册回调 → subscribe → 按事件名处理 → 按需取消 | §3.2；凭证接入见 §4.2 |
+| Bus 宿主 | 配置目录与权限 → start → 本地签发/撤销或更新名单 → publications/subscriptions/stats → drain/close | §3.1、§4、§7 |
+| Pub 发布方 | authorize 自动加载目录 → 分别 publish 多个事件 → 观察完成结果及 publications 汇总 | §3.3；凭证接入见 §4.3 |
+| Sub 订阅方 | authorize 自动加载目录 → 注册回调 → subscribe → 按事件名处理 → subscriptions 查询及按需取消 | §3.2；凭证接入见 §4.2 |
 
 下面按角色配套序列图和代码。角色图中的“AUN 消息通道”合并表示架构图中的 Gateway 与消息服务；Pub/Sub 到 Bus 的请求及定向回复均经过它。SDK 内部队列和协议执行顺序见[开发移植指南](AUN事件发布订阅开发移植指南.md)。
 
@@ -118,6 +119,7 @@ sequenceDiagram
     alt 注册成功
         M-->>G: 实例租约：100 秒有效，30 秒后续期
         G-->>B: 注册结果
+        B->>B: 加载持久目录及有效关系，合并本次配置
         B->>B: 启用承接、队列与分发
         B-->>A: start 完成
     else 已有实例
@@ -166,6 +168,8 @@ Bus 宿主直接维护配置、签发和撤销凭证、查询统计，无需额
 
 一个 Bus 的目录可登记多个事件。示例让同一发布方、订阅方使用两个事件；需要不同权限时，分别配置各事件的 `publish_aids` 和 `subscribe_aids`。各事件也可独立设置正文约束、版本和 TTL。
 
+事件目录、白名单和订阅关系默认持久保存。启动先加载已有目录，再合并本次配置；后续 `updateConfig` 也按事件合并，同名事件以本次条目为准，未提交的事件保留。收回某事件的白名单权限时提交该事件的空名单；省略事件或传空配置不会清空已有目录。
+
 同一个 Bus AID 同时只允许一个设备实例运行。第二个实例启动返回 `DEVICE_CONFLICT`；需要独立服务时使用不同 Bus AID。实际环境须支持 `aun.pubsub/1` 控制消息及 `message.evtsvc.*` 实例注册能力。
 
 ### 3.2 订阅方一次鉴权多个事件并登记订阅
@@ -183,13 +187,16 @@ sequenceDiagram
     N->>B: 申请订阅权限
     B-->>N: 设备租约及获准目录
     N-->>S: SDK 自动加载目录，必要时续页
+    S->>S: 完整目录及授权材料持久保存
     S-->>A: 鉴权完成
     A->>S: onEvent(bus_aid, handler)
     A->>S: subscribe(bus_aid, events)
     S->>N: subscribe：设备租约及事件列表
     N->>B: 登记当前设备、slot 的订阅
+    B->>B: 保存订阅关系
     B-->>N: subscribe.result
     N-->>S: 订阅成功
+    S->>S: 保存本角色订阅意图
     S-->>A: subscribe 完成
     B->>N: event：指定已订阅的设备与 slot
     N-->>S: Push 或 TTL 内的 Pull
@@ -215,10 +222,80 @@ await sub.subscribe(busAid, eventNames);
 
 `authorize` 建立权限租约，同时取得并缓存本次获准事件的目录；白名单和凭证模式都无需再单独调用 `catalog`。大目录由 SDK 自动分页取齐后才返回。`subscribe` 成功回复后订阅生效，可以一次传全部获准事件，也可只传其中一部分；新增范围需重新鉴权。鉴权范围内任一事件未获准，整个鉴权失败。
 
+同一角色在相同授权模式和凭证下再次 `authorize`，新增事件与已有授权范围合并；不同凭证不能混合扩大权限。后续 `subscribe` 追加关系；同一事件再次订阅时替换其发布者过滤条件，省略过滤条件恢复不限。`unsubscribe` 移除对应关系，其余订阅及目录条目保留。
+
 回调在订阅前注册，支持返回 Promise。也可以不注册回调，使用 `await sub.nextEvent(busAid, 5)` 主动等待，超时单位为秒。Python 对应 `next_event(bus_aid, timeout=5)`；Go 用 `NextEvent(ctx, bus_aid)` 的 context 控制超时。
 
 回调与主动等待选择一种消费方式；有回调时，新事件进入回调路径，不会同时成为 `nextEvent` 的副本。回调按顺序执行，异常不会终止后续事件，也不会要求 Bus 重发；慢处理会占用有界接收容量。
 
+#### 3.2.1 按事件层级订阅
+
+事件名描述业务事实，例如 `task.completed`，不要把发布者 AID 写进事件名。发布者变化时，订阅者仍可使用相同业务事件名。
+
+```ts
+await sub.authorize(busAid, 'sub', 'allowlist', ['task.completed', 'task.failed']);
+const subscribed = await sub.subscribe(busAid, ['task.*']);
+await sub.unsubscribe(busAid, ['task.*']);
+```
+
+`authorize` 仍传完整事件名。`subscribe` 的模式由 Bus 在当前目录和当前租约已授权事件的交集中展开，回复 `events` 是实际订阅的完整事件名，不是原模式。模式不保存为动态规则：目录新增事件或取得新授权后，需再次 `subscribe`。`unsubscribe` 的模式只作用于当前已订阅项。
+
+| 模式 | 匹配边界 |
+| --- | --- |
+| `task.*` | 匹配 `task.completed`，不匹配 `task.order.completed` |
+| `task.worker-*` | 匹配 `task.worker-`、`task.worker-1`，不跨 `.` |
+| `*` | 只匹配单层名称，不表示所有层级 |
+| `task.**`、`task..completed` | 无效模式，返回 `INVALID_PATTERN` |
+
+名称按 `.` 分层；模式与名称层数必须相同，每层非空。层内 `*` 匹配零个或多个字符，其他字符按字面量匹配，`?` 等不具有特殊含义。模式在目录无命中返回 `UNKNOWN_EVENT`；目录有命中、但租约无获准事件返回 `FORBIDDEN`。重叠模式或重复事件不会产生重复投递。
+
+#### 3.2.2 按发布者筛选
+
+优先按发布者名片的 `type` / `exttype` 筛选业务角色，保持发布与订阅解耦。写死发布者 AID 会把订阅者绑定到具体身份，削弱解耦，不建议常规使用；确需限定来源身份时再使用 AID 条件。以下为相互独立的调用示例，均假定已取得对应完整事件名的订阅权限。
+
+Python：
+
+```python
+await sub.subscribe(bus_aid, ["task.*"], publisher_types=["worker-*"])
+```
+
+TypeScript：
+
+```ts
+await sub.subscribe(busAid, ['task.*'], { publisherTypes: ['worker-*'] });
+```
+
+JavaScript：
+
+```js
+await sub.subscribe(busAid, ['task.*'], { publisherExttypes: ['task.executor'] });
+```
+
+Go：
+
+```go
+_, err := sub.Subscribe(ctx, busAID, []string{"task.*"}, aun.PubSubSubscribeOptions{
+    PublisherTypes: []string{"worker-*"},
+})
+```
+
+| 条件 | Python | TypeScript / JavaScript | Go |
+| --- | --- | --- | --- |
+| 发布者 AID | `publisher_aids` | `publisherAids` | `PublisherAIDs` |
+| 名片 type | `publisher_types` | `publisherTypes` | `PublisherTypes` |
+| 名片 exttype | `publisher_exttypes` | `publisherExttypes` | `PublisherExtTypes` |
+
+每个数组内部是“或”，不同条件之间是“且”；省略条件表示不限，显式空数组无效。过滤值沿用上述单层 `*` 规则，例如 `publisherAids: ['*.example.com']` 只匹配一个 name 层，不匹配 `worker.team.example.com`；单个 `*` 也不能跨层匹配全部 AID。
+
+```ts
+await sub.subscribe(busAid, ['task.completed'], {
+  publisherTypes: ['worker-*'], publisherExttypes: ['task.executor'],
+});
+await sub.subscribe(busAid, ['task.completed']);
+```
+
+首个调用同时限制 type 与 exttype；第二个调用将该事件恢复为不限发布者。续租与断线恢复保留各实际事件的过滤条件，本地 Bus 自己订阅与远端订阅遵循相同规则。Bus 在 fanout 前过滤：AID 来自已认证发送者，type/exttype 来自已验证名片，不采信事件正文自报字段。元数据读取失败时，仅需要 type/exttype 的订阅不匹配，不影响不限或只限定 AID 的订阅。
+
 ### 3.3 发布并观察完成结果
 
 **Pub 视角：** 一次鉴权多个事件后，分别发布 JSON 正文；publish 返回本地 event_id，后续通过完成结果观察实际发送或 Bus 受理。
@@ -235,10 +312,11 @@ sequenceDiagram
     B->>B: 校验权限，建立设备授权租约
     B-->>N: authorize.result：租约与目录首页
     N-->>P: 定向返回原 Pub 设备
-    P->>P: SDK 自动取齐后续页，缓存获准目录
+    P->>P: SDK 自动取齐后续页，持久保存获准目录与授权材料
     P-->>A: 目录缓存就绪，鉴权完成
     A->>P: publish(bus_aid, event_name, JSON对象)
-    P-->>A: 返回 event_id：已进入本地有界队列
+    P->>P: 先将待发布正文及原 ID、期限写入持久存储
+    P-->>A: 写入成功，返回 event_id：已进入本地有界队列
     P->>N: 后台发送 publish，保留原 TTL
     N-->>P: AUN 已接受发送
     N->>B: 发布请求
@@ -247,6 +325,7 @@ sequenceDiagram
         B-->>N: publish.result：Bus 已受理
         N-->>P: 仅回原 Pub 设备
     end
+    P->>P: none 发送成功 / accepted 收到 Bus 受理后删除持久正文
     P-->>A: waitPublished / onPublish 返回对应阶段结果
     Note over B: 后台向有效订阅设备公平分发
 ```
@@ -264,18 +343,18 @@ await Promise.all([pub.waitPublished(busAid, doneId), pub.waitPublished(busAid,
 
 | 观察结果 | 可以确认什么 |
 | --- | --- |
-| `publish` 返回 `event_id` | 本地发布队列已收下任务，尚未保证发送成功 |
+| `publish` 返回 `event_id` | 待发布记录已本地持久化并入队，尚未保证发送成功；持久写入失败则调用失败 |
 | 默认 `replyMode: 'none'` 的 `waitPublished` 成功 | AUN 接受了发往 Bus 的消息 |
 | `replyMode: 'accepted'` 的 `waitPublished` 返回 `status: 'accepted'` | Bus 完成授权、去重及内存受理，后续分发仍在后台执行 |
 | `onEvent` / `nextEvent` 收到事件 | 当前设备 SDK 已收到并校验；业务处理结果由应用负责 |
 
 一次 `authorize` 可授权多个事件；每次 `publish` 指定一个完整事件名和对应 JSON 正文。不同事件的发布共用该 Bus 的有界队列与公平调度，应用按每个 `event_id` 观察结果。订阅方通过 `event.event_name` 分发给各业务处理函数。
 
-`waitPublished` 的错误必须由调用方处理；也可用 `onPublish(busAid, handler)` 观察后台发送完成，其参数含 `event_id`、`result` 或 `error`。结果缓存有界且只在内存中，不能作为长期审计记录，过期或淘汰后等待可能报 `UNKNOWN_EVENT`。
+`waitPublished` 的错误必须由调用方处理；也可用 `onPublish(busAid, handler)` 观察后台发送完成，其参数含 `event_id`、`result` 或 `error`。正常完成结果使用有界运行时缓存，重启后不保证可查；待发布记录过期时保存可查询的失败结果。结果保存仍受容量限制，不能作为长期审计记录。
 
 `data` 必须为 JSON 对象，允许嵌套 JSON 值；不能直接传数组、字符串、`null`、非有限数或不可序列化对象。TTL 默认为目录配置（缺省 30 秒），取整数 1—3600 秒且不得超过该事件 `max_ttl_seconds`。正文连同事件封装受 64 KiB 明文预算限制。
 
-本地排队、加密、两跳网络发送与 Bus 排队共用原始期限。超时表示结果可能未知；重试复用原 `eventId` 和原事件内容，由 SDK 保留原期限。同 ID 改正文、事件名或版本会冲突；内存去重不构成持久的“恰好一次”保证。
+本地排队、加密、两跳网络发送与 Bus 排队共用原始期限。超时表示结果可能未知；重试复用原 `eventId` 和原事件内容，由 SDK 保留原期限，并为恢复或失败后的新发送尝试更新内部请求和网络消息标识。同 ID 并发调用须等待同一持久写入结果，不能在写入成功前确认接收。同 ID 改正文、事件名或版本会冲突；内存去重不构成持久的“恰好一次”保证。
 
 ## 4. 场景二：应用审批与凭证授权
 
@@ -392,12 +471,12 @@ Bus 从 AUN 验签结果取得发布者、订阅者的 AID 和设备身份，再
 | 变更 | 应用动作与生效边界 |
 | --- | --- |
 | 取消某事件 | `await sub.unsubscribe(busAid, [eventName])`；SDK 移除本地意图，后续恢复不再补订阅它 |
-| 白名单缩权 | Bus 宿主 `updateConfig(busAid, { allowlist })`；取消的权限及对应订阅立即收缩，凭证租约继续按凭证校验 |
-| 白名单增加权限 | 调用方重新 `authorize` 申请完整所需范围，自动加载目录后订阅新增事件；续期不会扩展原 scope |
+| 白名单缩权 | Bus 宿主 `updateConfig(busAid, { allowlist })`；取消的权限及对应订阅立即收缩，客户端成功续期后同步持久授权范围及订阅意图，凭证租约继续按凭证校验 |
+| 白名单增加权限 | 调用方重新 `authorize` 申请新增范围，同角色且授权来源相同时合并已有范围，自动加载目录后订阅新增事件；续期不会扩展原 scope |
 | 修改事件目录或版本 | Bus 宿主 `updateConfig(busAid, { catalog })`；客户端重新 `catalog`，发布使用当前 `schemaVersion` |
 | 关闭回调 | 调用注册返回的 `stopEvents()`；它只取消本地 handler，不等于远端 `unsubscribe` |
 
-白名单可使用事件条目 `"*"`，也可在 AID 数组使用 `"*"`，分别表示不限制事件或 AID，精确条目与通配条目按并集授权。通配应仅限本机受控多 agent 之间使用，其他情况不建议如此。通配不会创建目录外事件；`authorize`、`subscribe` 仍传完整事件名数组，不接受订阅模式。
+白名单可使用事件条目 `"*"`，也可在 AID 数组使用 `"*"`，分别表示不限制事件或 AID，精确条目与通配条目按并集授权。通配应仅限本机受控多 agent 之间使用，其他情况不建议如此。此处单独 `"*"` 的全部允许语义保持不变，不等于 §3.2 中订阅/发布者过滤的单层模式。白名单通配不会创建目录外事件；`authorize` 仍传完整事件名数组，`subscribe` 可传单层模式，但只展开已获准的目录事件。
 
 `authorize` 回复的 `catalog` 是本次授权目录首页，最多 2 KiB；普通单事件或少量事件通常一次请求完成，大结构由 SDK 自动续查并缓存，应用调用方式相同。返回值保留首页，不汇总全部条目。独立 `catalog` 用于查询或刷新，响应含 `items`、`next_page_token`、`catalog_revision`，门面另提供 `events` 别名。远程查询按有效租约过滤，本地 Bus 可查全部目录；分页默认 50、上限 200、完整回包最多 64 KiB，应用继续传 `page_token` 直至结束。目录变化导致 `CATALOG_CHANGED` 时重新鉴权或从查询首页刷新。客户端保留短期旧版本校验窗口，只处理仍在原 TTL 内的在途事件。
 
@@ -409,25 +488,38 @@ Bus 从 AUN 验签结果取得发布者、订阅者的 AID 和设备身份，再
 | 发布/订阅授权 | 默认有效 200 分钟、每 1 小时续期；凭证模式还受凭证链期限约束，以回复 `expires_at` 为准 |
 | 凭证状态证明 | 按 `proofExpiresAt` 独立刷新；过期且无法刷新时暂停相关操作，不等每小时续期 |
 | 当前进程短断线 | 连接 ready 后尝试续期；需要重新鉴权时使用已保存的授权材料，并恢复未取消的订阅 |
-| Bus 重启 | 配置可恢复，原租约、订阅和事件队列不恢复；客户端重新鉴权和订阅 |
-| 客户端进程重启或显式 close | 应用重新执行接入流程；SDK 不保存跨进程订阅意图 |
+| Bus 重启 | 加载目录并合并本次配置，恢复仍有效且通过权限复核的授权租约、订阅；已受理的 fanout 队列不恢复 |
+| 客户端进程重启或显式 close | 保留目录、授权及订阅意图和待发布记录；新进程分别 `authorize` 所需 Pub/Sub，已绑定角色可再次 `start`，加载后鉴权并恢复订阅和发布 |
 | Bus 失去实例租约 | 停止承接与分发，不自动抢占后来实例；宿主显式 `start`，客户端重新鉴权、订阅 |
 
-自动恢复只恢复关系，不补发已过期或丢失事件。无需调用内部 `recover`，公开门面没有该方法。
+Bus 宿主在新进程重新 `start(busAid, options)`；远端 Pub/Sub 分别重新 `authorize(busAid, role, ...)` 建立目标角色，内部启动随即加载该角色持久状态。SDK 不会在初始化时自动枚举所有历史 Bus。恢复待发布记录时沿用原 `event_id` 和 `expires_at`，不会重新计满 TTL；已过期则记录失败供完成接口查询，不再发送。恢复不补发 Bus 已受理后丢失的事件，也不提供历史重放。无需调用内部 `recover`，公开门面没有该方法。
 
-停机先停止上游提交，再对相关 Bus 执行 `drain(busAid)`、`close(busAid)`；先排空发布方，再排空 Bus。`drain` 等待已接管任务及回调，不证明所有设备都收到或提交业务。`close` 清理队列、挂起等待和授权状态；再次接入需重新鉴权和订阅，目录随鉴权自动加载。关闭 AUNClient 也会关闭其 EventService。
+停机先停止上游提交，再对相关 Bus 执行 `drain(busAid)`、`close(busAid)`；先排空发布方，再排空 Bus。`drain` 等待已接管任务及回调，不证明所有设备都收到或提交业务。`close` 清理运行时队列和挂起等待，保留持久目录、订阅意图及尚未完成的发布记录；中断发送也保留待发布记录。再次接入时重新鉴权并恢复。关闭 AUNClient 也会关闭其 EventService。
 
 ## 7. 持久化、统计与故障定位
 
-| SDK | Bus 配置与凭证材料保存方式 |
+| SDK | 默认状态保存方式 |
+| --- | --- |
+| Python / Go | 复用当前身份的 SQLite `{aun_path}/AIDs/{self-aid}/aun.db`，保存 Bus 目录、有效授权与订阅、客户端状态及待发布记录；显式 `state_path` / `StatePath` 的 Bus 状态使用 `event-service.sqlite3`，凭证仍用 `credential-state.json`，客户端发布队列仍在自身 `aun.db` |
+| TS（Node.js） | 复用当前身份的 SQLite `aun.db` 保存上述状态；`start` 的 `state.load/save` 可覆盖 Bus 状态，`credentialOptions.state.load/save` 可覆盖凭证材料存储 |
+| JS（浏览器） | 复用 IndexedDB `aun-keystore` 的 `metadata`；Bus 状态按身份及 Bus 隔离，客户端另区分角色及设备实例；自定义 Bus 和凭证存储回调同 TS |
+
+Bus 状态包括目录、白名单、签发及暂停记录，以及可复核恢复的授权租约和订阅。客户端按身份、Bus、角色及设备实例隔离保存授权材料、目录、订阅意图、待发布记录和过期失败结果。首次启动后直接使用默认持久层，无需另配存储回调；重启加载后增量合并后续注册和订阅。Python / Go 可导入旧 `event-service.json`，后续写入 SQLite。各语言内部状态格式不是跨语言导入协议。
+
+发布持久记录的顺序为“写入成功 → 确认本地入队 → 后台发送 → 按回复模式判定成功 → 删除本地正文”。默认 `none` 在 AUN 接受发送后删除，`accepted` 在收到 Bus 受理回复后删除；关闭、中断或未确认成功时保留。该保障不覆盖 Bus 后台 fanout、服务端 volatile 收件箱和事件历史。
+
+默认凭证适配器仍使用元数据键 `pubsub_credentials_v1`，保存原凭证、登记/撤销请求、提交证据和结果；Bus 状态与凭证材料各自保存。`self-aid` 指当前 SDK 身份，客户端待发布记录保存在发布者自身的数据库中。
+
+实时目录用 `publications(busAid, params)` 和 `subscriptions(busAid, params)`，Go 对应 `Publications` / `Subscriptions`。Bus 宿主查询全局；Pub 查询自身 AID、当前发布权限内的受理汇总；Sub 查询当前设备租约实际生效的订阅。多角色时，`publications` 的 `role` 可选 `"bus" / "pub"`，`subscriptions` 可选 `"bus" / "sub"`；省略时优先本地 Bus，否则使用对应 Pub/Sub，这个参数只用于本地选择。
+
+| 查询 | `items` 条目 |
 | --- | --- |
-| Python / Go | 凭证材料默认自动写入 `{aun_path}/AIDs/{self-aid}/aun.db`；显式 `state_path` / `StatePath` 时，指定目录保存 `event-service.json` 和 `credential-state.json` |
-| TS | 凭证材料默认自动写入自身 AID 的 `aun.db`；服务配置通过 `start` 的 `state.load/save` 保存，`credentialOptions.state.load/save` 可覆盖凭证存储 |
-| JS | 凭证材料默认自动写入浏览器 IndexedDB `aun-keystore` 的 `metadata`，按自身 AID 隔离；服务配置及自定义凭证存储回调同 TS |
+| `publications` | `publisher_aid`、`event_name`、`published`、`first_published_at`、`last_published_at`；按事件名汇总，不含正文或逐消息历史 |
+| `subscriptions` | `subscriber_aid`、`event_name`、`device_id`、`slot_id`、`expires_at`；不含租约令牌或凭证 |
 
-服务状态包括目录、白名单、签发及暂停记录；它不保存事件历史、租约、订阅或投递队列。重启加载的已保存配置优先于初始配置，变更应通过 `updateConfig` 提交。各语言内部状态格式不是跨语言导入协议，不能直接交换目录中的状态文件。
+两种结果均含 `service_aid`、`since`、`as_of`、`items`、`next_page_token`；时间为 UTC Unix 毫秒。参数可选 `event_name`、`limit`（默认 50，上限 200）与 `page_token`，末页 token 为 null。每页反映当时的有效关系，无冻结快照；token 有效 60 秒并绑定查询范围，Bus 重启后旧 token 失效，应从首页重查；完整回复最多 64 KiB。发布计数以 Bus 首次受理为准，去重和拒绝不增加；消息 TTL 到期后汇总仍在，Bus 重启后清零。Pub 的 none 发送成功可能尚未到达 Bus；Sub 的授权事件目录也不等于已订阅目录。
 
-默认凭证适配器统一使用元数据键 `pubsub_credentials_v1`，保存原凭证、登记/撤销请求、提交证据和结果，应用无需另写存储回调。凭证材料自动保存与 Bus 配置保存是两件事；要恢复完整 Bus 配置，仍需按上表配置服务状态存储。`self-aid` 指运行 Bus 的当前身份，不是发布者或订阅者。
+例如 `await bus.publications(busAid)` 查全局发布汇总，`await pub.publications(busAid, { role: "pub" })` 查自身，`await sub.subscriptions(busAid, { role: "sub" })` 查自己的实际订阅；需要事件定义仍调用 `catalog`。
 
 Bus 宿主应用调用 `bus.stats(busAid, { event_name: eventName })`，结果位于 `counts`，`since` 为本次运行起点，`as_of` 为查询时点。计数不持久保存。
 
@@ -444,16 +536,19 @@ Bus 宿主应用调用 `bus.stats(busAid, { event_name: eventName })`，结果
 | 表现或错误 | 核查顺序 |
 | --- | --- |
 | `SERVICE_NOT_STARTED` / `DEVICE_CONFLICT` | 确认 Bus 是否已成功 start、是否有其他承接实例 |
-| `BUS_ROLE_CONFLICT` / `SERVICE_IDENTITY_MISMATCH` | 检查同 client 的角色及宿主 AID |
+| `ROLE_MISMATCH` / `SERVICE_IDENTITY_MISMATCH` | 检查是否已授权调用所需角色，以及宿主 AID 是否正确；角色并存无需拆分 client |
 | `FORBIDDEN` / `REAUTH_REQUIRED` | 检查名单或凭证 scope、租约、证明和撤销状态 |
+| `INVALID_PATTERN` | 检查模式空层或连续 `**`；单层 `*` 不跨 `.` |
+| `UNKNOWN_EVENT` | 模式在当前目录无命中；有命中但无授权时为 `FORBIDDEN` |
 | `CATALOG_REQUIRED` / `SCHEMA_MISMATCH` / `UNSUPPORTED_SCHEMA_VERSION` | 获取当前事件目录，再使用匹配版本发布 |
 | `OVERLOADED` / `MESSAGE_TOO_LARGE` | 检查发布及接收容量、正文尺寸；未入队的调用不能视为成功 |
 | `TIMEOUT` | 结果可能未知；保留事件或管理操作的原有幂等材料 |
-| 已受理但未收到 | 核对订阅生效时点、接收端目录、当前设备实例、TTL、授权、接收速度及 Bus 统计 |
+| 已受理但未收到 | 核对订阅生效时点、接收端目录、当前设备实例、发布者过滤及已验证名片、TTL、授权、接收速度及 Bus 统计 |
 
 ## 8. 代码与验收依据
 
 - 门面与应用接线：[Python](../../python/src/aun_core/pubsub/__init__.py)、[TypeScript](../../ts/src/pubsub/index.ts)、[JavaScript](../../js/src/pubsub/index.ts)、[Go](../../go/pubsub_service.go)。
 - 应用场景：[Python 应用测试](../../python/tests/unit/test_pubsub_application.py)、[场景测试](../../python/tests/unit/test_pubsub_scenarios.py)、[设备与恢复 E2E](../../python/tests/e2e_test_event_pubsub_recovery.py)。
-- 本轮真实跨端证据：[实施计划 §9.9](../../../docs/AUN文档/AUN事件订阅发布TDD实施计划.md#99-凭证默认存储授权目录与移除管理身份)与[128项汇总](../../tests/cross-sdk/artifacts/pubsub-4sdk-20261105/remove-manager-acceptance/final-acceptance-summary.json)：四种 Bus 各32/32，覆盖两种授权、同SDK和有向跨SDK；本地签发与统计、authorize自动目录后直接发布订阅均通过。
+- 此前真实跨端证据：[实施计划 §9.9](../../../docs/AUN文档/AUN事件订阅发布TDD实施计划.md#99-凭证默认存储授权目录与移除管理身份)与[128项汇总](../../tests/cross-sdk/artifacts/pubsub-4sdk-20261105/remove-manager-acceptance/final-acceptance-summary.json)：四种 Bus 各32/32，覆盖两种授权、同SDK和有向跨SDK；该归档不作为本次角色并存与发布队列持久化变更的验收结果。
+- 本次变更已通过本机相关单元测试、SQLite/IndexedDB 存储重开与故障模拟及静态检查，未执行真实服务 E2E 或浏览器网络 E2E。
 - 证据边界：JS 使用 Node 与 fake-indexeddb；真实浏览器、macOS、真实双域设备 E2E，以及实填 64 MiB/RSS 压力未验，详见[方案 §15](../../../docs/AUN文档/AUN事件订阅发布方案.md#15-轻量服务与单实例使用边界)。