@agentunion/fastaun 0.5.32 → 0.5.34

package/_packed_docs/sdk/AUN/344/272/213/344/273/266/345/217/221/345/270/203/350/256/242/351/230/205/345/274/200/345/217/221/347/247/273/346/244/215/346/214/207/345/215/227.md

@@ -1,6 +1,6 @@
 # AUN事件发布订阅开发移植指南
 
-面向 SDK 维护者和新语言移植者，定义当前工作区 EventService 的分层、消息与状态契约、关键执行顺序及验收场景。应用接线见[应用集成指南](AUN事件发布订阅应用集成指南.md)，完整设计见[事件订阅发布方案](../../../docs/AUN文档/AUN事件订阅发布方案.md)。本文整理现有实现，不新增框架接口。
+面向 SDK 维护者和新语言移植者，定义四端 SDK 0.5.34 工作区源码中 EventService 的分层、消息与状态契约、关键执行顺序及验收场景；包发布和服务部署状态另行核对。应用接线见[应用集成指南](AUN事件发布订阅应用集成指南.md)，完整设计见[事件订阅发布方案](../../../docs/AUN文档/AUN事件订阅发布方案.md)。底层消息与实例 RPC 见[消息 RPC 手册](09-message-rpc-manual.md)。本文整理现有实现，不新增框架接口。
 
 ## 1. 分层与移植顺序
 
@@ -41,16 +41,16 @@ Pub → Bus 与 Bus → Sub 是两次独立 P2P 投递，均经过 Gateway 和 M
 
 | 实现视角 | 先实现的内部链路 | 对外验收入口 | 对应章节 |
 | --- | --- | --- | --- |
-| Bus | Binding注册与失租 → 核心授权/设备订阅 → 原子受理 → 公平调度 → 注销 | start、issue_grant、update_config、stats、close | §2、§4、§6、§9 |
-| Pub | 新授权与目录暂存 → 有界发布队列 → 后台发送 → request/event关联与完成结果 | authorize、publish、wait_published | §4—§6 |
-| Sub | 订阅意图与设备租约 → 有界接收/去重 → handler或等待队列 → 续期与恢复 | authorize、subscribe、on_event或next_event | §4、§5、§7 |
+| Bus | Binding注册与失租 → 核心授权/设备订阅 → 原子受理 → 公平调度 → 注销 | start、issue_grant、update_config、publications、subscriptions、stats、close | §2、§4、§6、§9 |
+| Pub | 新授权与目录暂存 → 待发布记录持久化 → 有界发布队列 → 后台发送 → 完成后删除持久正文 | authorize、publications、publish、wait_published | §4—§6、§8 |
+| Sub | 订阅意图与设备租约 → 有界接收/去重 → handler或等待队列 → 续期与恢复 | authorize、subscribe、subscriptions、on_event或next_event | §4、§5、§7 |
 
 按上表逐端实现与验收；公开方法用 Python 风格标识，各语言命名见 §8。本地 Bus 管理直接进入当前服务核心，远端 Pub/Sub 经 Channel、Gateway、Message 与 Bus Binding 通信。
 
 | 层次 | 职责 | 不应混入的状态 |
 | --- | --- | --- |
 | EventService 门面 | 按 client 与 bus_aid 管理角色、生命周期、公开方法和 JSON 对象校验 | 不向应用暴露 Binding 或实例注册令牌 |
-| 发布/订阅客户端 | 授权材料、租约、目录缓存、订阅意图、有界发送与接收、完成结果和恢复 | 不承诺跨进程订阅或事件恢复 |
+| 发布/订阅客户端 | 授权材料、目录与订阅意图持久化，待发布记录恢复，有界收发与完成结果 | 不把本地发布恢复扩展为事件历史或远端业务交付保证 |
 | Bus 核心 | 目录、白名单/凭证校验、设备级租约与订阅、受理去重、快照、fanout、统计 | 不依赖服务端存储事件订阅表 |
 | Binding / Channel | E2EE 控制消息、可信来源与设备定向、入站准入、回复和实例注册 | 不将业务处理结果解释为底层 ACK |
 | 凭证适配器 | 完整 Verify、签发登记、撤销、真实提交记录及恢复 | 不以只验签或 CID 查询替代完整校验 |
@@ -58,7 +58,9 @@ Pub → Bus 与 Bus → Sub 是两次独立 P2P 投递，均经过 Gateway 和 M
 
 推荐按“既有 AUN E2EE 与控制流 → Channel/Binding → Bus 核心及调度 → 客户端 → 统一门面”落地，并先做同语言场景，再做有向跨 SDK 组合。各语言独立实现语言无关 JSON 协议，内部类、线程机制和状态文件不构成共享代码依赖。
 
-公开边界固定：Python/TS/JS 为 `client.EventService`，Go 为 `client.EventService()`。同 client、同 Bus 只绑定 `pub/sub/bus` 一种角色；bus 身份必须等于当前 client AID。签发、撤销及统计只允许已启动的本地 Bus 宿主调用。网络目标以 `bus_aid` 传入；内部 wire 使用 `service_aid`，应用事件由门面补充 `bus_aid`。
+公开边界固定：Python/TS/JS 为 `client.EventService`，Go 为 `client.EventService()`。同 client、同 Bus 可同时绑定 `bus/pub/sub`，按 `(bus_aid, role)` 分别管理端点；Pub/Sub 分别授权并持有独立租约，Bus 身份仍必须等于当前 client AID。签发、撤销及统计只允许已启动的本地 Bus 宿主调用。网络目标以 `bus_aid` 传入；内部 wire 使用 `service_aid`，应用事件由门面补充 `bus_aid`。
+
+门面把发布与订阅方法路由到相应角色；`catalog` 优先本地 Bus，否则 Pub 再 Sub，沿用所选端点的分页协议。`renew` 覆盖已绑定的 Pub/Sub，`drain/close` 覆盖该 Bus 的已绑定角色；启动恢复须先使本地 Bus 就绪，再启动客户端角色。
 
 ## 2. 场景一：启动唯一 Bus 实例
 
@@ -72,7 +74,7 @@ Message 只维护 `Bus AID + service=event_service` 的实例注册；目录、
 
 可信 AID、device、slot、connection 来自 Gateway 认证会话，不能从请求正文自报。成功回复含原 `registration_id`、实例地址、`expires_at`（毫秒）、`ttl_seconds=100`、`renew_after_seconds=30`。RPC 错误 `-32009` 的 `data.code` 区分 `DEVICE_CONFLICT`、`SERVICE_LEASE_LOST`、`SERVICE_UNAVAILABLE`；发往未启用服务的消息返回 `SERVICE_NOT_STARTED`。
 
-本次 start 生成新令牌，验证回复令牌一致。本地承接截止取“请求开始的单调时钟 + ttl_seconds”，不能用回复到达时间重新计满 100 秒；回复延迟不增加有效期。按下一期限安排续期，续期与重试不得超过原实例剩余期限。
+本次 start 生成新令牌，验证回复令牌一致。注册成功后再加载和合并持久状态，注册冲突不得改写存储；恢复完成须再次检查原实例期限，过期则清理并注销，不启用接收。本地承接截止取“请求开始的单调时钟 + ttl_seconds”，不能用回复到达时间重新计满 100 秒；回复延迟不增加有效期。按下一期限安排续期，续期与重试不得超过原实例剩余期限。
 
 失租或到期后同时停止入站、排队处理及 fanout；不自动争抢后来实例。显式再次 start 清理旧状态，以新令牌注册。旧启动代次的迟到回复、任务或定时器不能修改新实例。关闭须停止接收、清理/等待已接管工作并注销；失败启动也须释放本地资源。
 
@@ -97,6 +99,7 @@ sequenceDiagram
     else 注册成功
         M-->>G: 实例租约100秒，30秒后续期
         G-->>B: 原注册令牌及期限
+        B->>B: 加载持久目录及有效关系，合并本次配置
         B->>B: 启用接收、处理队列及fanout
         B-->>A: start成功
         loop 按下次期限等待，正常每30秒
@@ -150,6 +153,8 @@ P/C 与 Bus 之间全部复用 E2EE P2P `message.send`。加密外层 `payload.t
 | `subscribe` / `unsubscribe` | lease_id、完整事件名数组 events | 关系变更状态及事件名 |
 | `renew` | lease_id；凭证模式带原授权绑定材料 | 原范围的新到期时间 |
 | `catalog` | 可选 event_name、limit、page_token；普通调用方带租约 | items、revision/catalog_revision、next_page_token |
+| `publications` | 可选 event_name、limit、page_token；远端带发布租约 | 按 publisher_aid/event_name 汇总的受理次数与首次/最近时间 |
+| `subscriptions` | 可选 event_name、limit、page_token；远端带订阅租约 | 当前有效的 AID/device/slot/event 关系，不含凭证或租约令牌 |
 | `publish` | lease_id、event_id、event_name、schema_version、data、expires_at、reply_mode | none 无业务回复；accepted 返回快速受理结果 |
 | 本地 `issue_grant` | subject_aid、scope、grant_expires_at | grant、cid、receipt 或 registration_confirmation |
 | 本地 `revoke_grant` | cid | 撤销结果 |
@@ -168,7 +173,7 @@ P/C 与 Bus 之间全部复用 E2EE P2P `message.send`。加密外层 `payload.t
 | 层级 | 幂等键与约束 |
 | --- | --- |
 | 控制请求 | 可信发送 AID、device、slot、request_id 绑定完整请求指纹；并发重复复用首次结果，改参报 `REQUEST_CONFLICT` |
-| 发布客户端 | 同 event_id 保持 event_name/schema_version/data，复用原 expires_at；冲突报 `IDEMPOTENCY_CONFLICT` |
+| 发布客户端 | 同 event_id 保持 event_name/schema_version/data，复用原 expires_at；同一发送尝试的网络重试复用 message_id，恢复或失败后的新尝试更新 request_id、绑定和网络 message_id；冲突报 `IDEMPOTENCY_CONFLICT` |
 | Bus 发布受理 | `(publisher_aid,event_id)` 缓存首次事件指纹和受理结果至原期限；冲突报 `EVENT_CONFLICT`；去重记录不保留正文 |
 | 目标投递 | 稳定 message_id 包含服务、发布者、事件、订阅 AID 和设备/slot；超时重试复用原 ID 和截止 |
 | 订阅接收 | `(Bus AID,publisher_aid,event_id)` 去重至原期限，内存有界 |
@@ -185,10 +190,12 @@ P/C 与 Bus 之间全部复用 E2EE P2P `message.send`。加密外层 `payload.t
 
 Bus 宿主本地维护全部配置并调用签发、撤销和统计。远端发布者、订阅者仅持各自设备租约，目录查询按该租约过滤；本地 Bus 可查询全部目录。
 
-配置缩权时立即裁剪 allowlist 租约 scope、删除无剩余权限的租约和相应订阅。新增权限只在重新 authorize 时授予；renew 不能扩大原 scope。凭证租约不会因白名单缩权而改变授权来源。
+配置缩权时立即裁剪 allowlist 租约 scope、删除无剩余权限的租约和相应订阅。客户端按成功 renew 返回的 scope 收缩并持久保存原授权范围及订阅意图，后续合并授权不重新带入已知撤销范围。新增权限只在重新 authorize 时授予；renew 不能扩大原 scope。凭证租约不会因白名单缩权而改变授权来源。
 
 多事件沿用相同协议：Bus 目录登记多个完整事件名，allowlist 对每个事件分别配置。客户端一次 authorize 的 scope 可包含多个事件；同一请求任一项未获准则整体失败。subscribe/unsubscribe 的 events 数组可选择获准范围内的一部分，每次 publish 仍只包含一个 event_name 和一份 JSON 正文。回调依据 event_name 分发；不同事件共享当前 Bus 的容量与公平调度预算。应用示例见[应用指南 §3](AUN事件发布订阅应用集成指南.md#3-场景一白名单接入)。
 
+同角色且授权模式、凭证相同时，后续 authorize 的事件与已授权事件合并，再整体校验；不同凭证不能混合扩大 scope。subscribe 追加关系，unsubscribe 仅移除指定关系。客户端目录、授权和订阅的持久状态按身份、Bus、角色及设备实例隔离，Pub/Sub 相互不覆盖。
+
 ### 4.2 完整凭证校验
 
 凭证模式的启动顺序是“Bus AUN 身份连接就绪 → 本地 start 配置目录 → 宿主审批并本地签发凭证 → 发布/订阅方 authorize → 订阅方 subscribe”。Bus 使用自身 AID 接入 AUN，start 要求 bus_aid 等于当前身份，随后自动调用 message.evtsvc.register；凭证模式省略 allowlist 即可，凭证适配器由 SDK 自动创建。
@@ -292,7 +299,7 @@ sequenceDiagram
         M-->>G: 定向投递
         G-->>P: 目录后续页，重复直至取齐
     end
-    P->>P: 所有页成功且代次有效后提交缓存与新租约
+    P->>P: 所有页成功且代次有效后提交并持久保存目录与授权材料
 ```
 
 ```text
@@ -300,7 +307,7 @@ sequenceDiagram
 暂存目录 = 当前目录副本；页 = 回复.catalog
 循环：暂存(页.items)；无next_page_token则退出
     页 = await catalog(回复.lease_id, 页.next_page_token, 本次新授权材料)
-所有页成功且代次仍有效：一次提交暂存目录、授权材料和新租约
+所有页成功且代次仍有效：一次提交暂存目录、授权材料和新租约，保存持久状态
 任一页失败或已关闭：保留旧状态，不提交部分结果
 ```
 
@@ -310,7 +317,7 @@ Pub 随后可 publish；Sub 还须 subscribe 才有事件订阅关系。续页
 
 签发前保存原 grant 和登记请求；真实提交前保存提交时间及请求摘要，正常返回需验登记回执。有效绑定窗口内重试原材料；超窗后只允许依据真实发送证据与最新签名状态证明确认原登记，不得仅凭“凭证已存在”认定该次操作成功。
 
-确认成功后返回同一 grant/cid，`receipt=null` 并附 `registration_confirmation`。撤销同样保留原请求和结果。服务配置与凭证适配器是两个持久化域；SDK 自动保存默认凭证材料，应用按需配置服务状态存储。
+确认成功后返回同一 grant/cid，`receipt=null` 并附 `registration_confirmation`。撤销同样保留原请求和结果。服务配置与凭证适配器是两个持久化域，均默认复用 SDK 已有持久层；应用可显式覆盖相应存储。
 
 来源：[Python 凭证适配器](../../python/src/aun_core/pubsub/credentials.py)、[TS 凭证适配器](../../ts/src/pubsub/credentials.ts)、[Go 凭证适配器](../../go/pubsub_credentials.go)、[凭证移植指南](凭证与组织服务SDK开发与移植指南.md)。
 
@@ -318,6 +325,8 @@ Pub 随后可 publish；Sub 还须 subscribe 才有事件订阅关系。续页
 
 目录条目包含 `description/schema_version/content_schema/default_ttl_seconds/max_ttl_seconds`，回复另有 event_name、allowed_actions。白名单与凭证 authorize 均返回嵌套 catalog 首页，客户端自动取完后续页并缓存，然后提交新授权状态；成功返回后即可发布或订阅接收。独立 catalog 保留，用于查询与刷新。
 
+Bus 启动先加载持久目录、白名单，再按事件合并本次配置；update_config 同样增量合并，同名条目以本次值为准，其余保留。对合并结果完成校验再保存。收回某事件的白名单权限须提交该事件的空名单，不能把省略条目或空配置解释为清空目录。
+
 - authorize 附带目录只按新租约 scope 生成。续页 token 额外绑定该租约，不能用于另一租约。
 - authorize 附带 catalog 的 UTF-8 JSON 最多 2 KiB，完整 authorize.result 仍最多 64 KiB。首页容不下一条时返回空 items 与 offset=0 的续页 token，SDK 自动按普通目录页补齐。这样默认 4096 条幂等缓存新增目录的 UTF-8 JSON 总量最多 8 MiB，不把大 schema 逐请求复制留存。
 - 客户端暂存各页，在全部成功且运行代次仍有效后更新目录、授权和租约；续页失败或关闭不提交部分状态。返回值保留有界首页，不能再把所有页合并进租约或幂等回包。
@@ -334,7 +343,7 @@ Pub 随后可 publish；Sub 还须 subscribe 才有事件订阅关系。续页
 
 ### 6.1 受理与快照顺序
 
-发布客户端先做目录、版本、TTL、JSON 与本地容量检查，入有界队列立即返回 event_id。后台发送结果进入完成等待表或回调，不在 publish 中串行等待整个网络及 fanout。
+发布客户端先做目录、版本、TTL、JSON 与本地容量检查，将原 event_id、expires_at、正文及发布选项写入持久存储，写入成功后才确认有界入队并返回 event_id。持久写入失败时调用失败，不确认接收。后台发送结果进入完成等待表或回调，publish 不等待整个网络及 fanout。
 
 同一事件的订阅视图在受理时固定。随后新订阅不能加入旧事件；取消、撤销或替换订阅代次后，发送前复核可以阻止尚未发送的旧快照任务。快照采用共享引用计费，不能为每次 publish 无界复制整张订阅表。
 
@@ -348,7 +357,7 @@ sequenceDiagram
     participant M as 消息服务
     participant B as Bus SDK
     A->>P: publish(bus_aid, event_name, data)
-    P->>P: 校验目录并放入有界发送队列
+    P->>P: 校验后持久写入待发布记录，再放入有界发送队列
     P-->>A: event_id
     P->>G: 后台message.send：publish，原始expires_at
     G->>M: 正TTL的sdk_control密文
@@ -371,11 +380,12 @@ sequenceDiagram
         G->>M: 定向内存投递
         B->>B: 释放预算，唤醒受背压入口
     end
+    P->>P: 达到所选成功阶段后删除本地持久正文
     Note over A,P: none以AUN接受发送为完成；accepted以Bus受理为完成
 ```
 
 ```text
-Pub.publish：校验后有界入队，立即返回event_id；worker后台发送
+Pub.publish：校验并持久写入成功后有界入队，返回event_id；worker后台发送
 Bus入口：尝试预留条数与字节，失败则暂停对应Pull且不ACK/去重
 成功接管后提交消息去重与ACK，按发布AID轮转处理
 通过授权/版本/期限/事件去重后，原子受理快照及fanout任务
@@ -392,6 +402,10 @@ Bus入口：尝试预留条数与字节，失败则暂停对应Pull且不ACK/去
 
 `publish` 返回、本地 `message.send` 成功、`publish.result(status=accepted)` 是三个不同阶段；受理确认不等目标匹配及发送完成。目标发送超时表示结果未知，重试沿用 ID 与期限；确认后只入账一次，不能把超时直接计为明确失败。
 
+发布端仅在对应阶段成功后删除持久正文：none 等 AUN 接受发送，accepted 等 Bus 受理。close、取消、中断或未确认成功时保留待发布记录；删除持久记录失败也不得把记录视为已完成。并发提交同一 event_id 必须共同等待首次耐久写入，写入失败不能有调用提前确认成功。重启按原 event_id 和 expires_at 恢复，经重新鉴权后继续发送；已过期则移除待发布正文并保存可查询的失败结果，不延长 TTL。成功的运行时结果缓存不承担跨重启查询承诺。
+
+此持久顺序只覆盖发布端尚未完成的记录。Bus 已受理后的 fanout、目标投递队列及 Message 的 volatile 收件箱仍是运行时状态，不因此获得事件历史或端到端持久交付保证。
+
 每个订阅 AID 一个逻辑 worker，同 AID 多设备共享公平份额，每个 AID 最多一条事件发送在途。使用 DRR 按工作量推进，成本为明文字节加默认 128 字节固定开销；发布 AID 与目标 AID 都计相应预算，避免只按事件条数轮转导致大消息独占。
 
 ### 6.3 容量与调度预算
@@ -465,6 +479,10 @@ sequenceDiagram
     participant M as 消息服务
     participant B as Bus SDK
     Note over P,B: 授权默认200分钟有效，正常每1小时续期
+    opt 新进程已重新authorize，或已绑定角色再次start
+        P->>P: 加载本角色目录、授权、订阅意图及待发布记录
+        P->>P: 已过期记录保存失败结果，其余等待重新鉴权
+    end
     P->>P: 等待授权续期时点，或连接重新ready
     P->>G: renew：当前lease_id及原授权材料
     G->>M: 发往Bus的控制消息
@@ -483,14 +501,17 @@ sequenceDiagram
             P->>P: 经同一消息路径补subscribe，仅恢复未取消事件
         end
     end
+    P->>P: 鉴权就绪后按原ID及期限续发未完成记录
 ```
 
 ```text
+角色启动：加载持久目录、授权、订阅意图及待发布记录；过期发布保存失败结果
 无已保存授权材料：结束；否则按当前生命周期串行恢复
 租约未过期：先renew，仅REAUTH_REQUIRED转重新鉴权
 租约已过期或renew返回REAUTH_REQUIRED：重新authorize并自动加载完整目录
 Sub需要补订阅时：锁定意图，subscribe仍未取消的事件
 成功才清除待恢复标记；暂时失败保留意图并有界重试
+发布恢复：按原event_id及expires_at入有界队列，成功后删除持久正文
 已关闭或代次已变化：结束旧恢复流程
 ```
 
@@ -500,9 +521,9 @@ Bus 实例续期是 §2 的30秒/100秒链路，Pub/Sub授权续期是这里的1
 
 `on_event/onEvent/OnEvent` 与 `next_event/nextEvent/NextEvent` 是两种消费模式；有 handler 时新事件进入 handler 路径。Python 异步回调 await、同步回调在线程中串行执行；TS/JS await 返回 Promise；Go 回调为函数。回调失败不自动重发，慢回调占用接收额度。
 
-连接 ready 或授权续期到期触发进程内恢复：优先 renew，有效关系不重复创建；`REAUTH_REQUIRED` 时按保存的原授权重新 authorize，再恢复未取消的订阅。订阅恢复失败应保留待恢复状态，不因一次失败丢失意图；取消与恢复要串行，不能把已取消事件重新加入。门面没有公开 recover API。
+连接 ready 或授权续期到期触发进程内恢复：优先 renew，有效关系不重复创建；`REAUTH_REQUIRED` 时按保存的原授权重新 authorize，再恢复未取消的订阅。进程重启后，Bus 宿主重新 start，远端 Pub/Sub 分别 authorize 建立目标角色，内部启动加载该角色的目录、授权材料、订阅意图和待发布记录，再经鉴权恢复订阅与发布；已绑定角色可再次 start。Go 启动后的恢复由后台推进，Start 返回不等于所有待发布消息已发送。订阅恢复失败应保留待恢复状态，不因一次失败丢失意图；取消与恢复要串行，不能把已取消事件重新加入。门面没有公开 recover API。
 
-close 清租约、授权、订阅、pending、发布结果、队列和运行时去重；阻止旧代次回调继续交给后续 handler。支持同对象显式再次 start，原角色约束保留；重新 authorize/subscribe 后继续接收新事件，目录随鉴权加载。drain 等待已接管工作及仍运行的回调，不能把 AUN 接受发送当作远端业务完成。
+close 清理运行时租约、请求等待、队列和去重，阻止旧代次回调继续交给后续 handler；保留持久目录、授权及订阅意图、尚未完成的发布记录。支持同对象显式再次 start，也支持新进程按原身份和设备实例恢复；目录加载后合并后续注册、订阅。drain 等待已接管工作及仍运行的回调，不能把 AUN 接受发送当作远端业务完成。
 
 底层 Push/Pull/ACK 沿用设备、slot 和类别隔离；只有成功接管才提交去重与 ACK。事件交给应用后没有独立业务 ACK、历史游标或 replay API；应用回调返回不提供持久交付保证。
 
@@ -510,30 +531,40 @@ close 清租约、授权、订阅、pending、发布结果、队列和运行时
 
 | 状态 | 保存边界 |
 | --- | --- |
-| 服务配置 | 目录、白名单、签发记录、暂停 CID；重启恢复的配置优先于构造初始配置 |
+| Bus 目录与关系 | 目录、白名单、签发记录、暂停 CID、授权租约及订阅；加载后增量合并本次配置，仅恢复未过期且通过当前权限复核的关系 |
+| 发布/订阅客户端 | 授权材料、目录缓存和订阅意图；启动加载后重新鉴权，后续授权、订阅增量合并 |
+| 发布记录 | 确认入队前耐久保存；成功后删除正文，中断保留；重启按原 ID、原 TTL 恢复，过期失败结果可查 |
 | 凭证适配器 | 原凭证、登记/撤销请求、真实提交证据及结果；支持原操作恢复 |
-| 运行时 | 实例令牌、租约、订阅、快照、队列、事件正文、发布结果、事件去重和统计不作为持久恢复账本 |
+| 运行时 | Bus 实例令牌、受理快照、fanout 与目标投递队列、接收队列、成功结果缓存、事件去重、发布汇总和统计不作为持久恢复账本 |
 
 | SDK | 入口和配置 | 源码入口 |
 | --- | --- | --- |
-| Python | 凭证默认使用自身 AID 的 aun.db；显式 state_path 目录保存服务与凭证两份 JSON 文件 | [门面](../../python/src/aun_core/pubsub/__init__.py)、[Binding](../../python/src/aun_core/pubsub/binding.py) |
-| TS | 凭证默认使用自身 AID 的 aun.db；start.state 保存服务配置，credentialOptions.state 覆盖凭证存储 | [门面与 options](../../ts/src/pubsub/index.ts)、[凭证](../../ts/src/pubsub/credentials.ts) |
-| JS | 凭证默认使用 IndexedDB aun-keystore/metadata，按自身 AID 隔离；显式适配器与 TS 相同 | [门面](../../js/src/pubsub/index.ts)、[凭证](../../js/src/pubsub/credentials.ts) |
-| Go | 凭证默认使用自身 AID 的 aun.db；显式 StatePath 目录保存服务与凭证两份 JSON 文件 | [门面](../../go/pubsub_service.go)、[类型](../../go/pubsub_types.go) |
+| Python | 默认复用自身 AID 的 SQLite aun.db；显式 state_path 的 Bus 状态使用 event-service.sqlite3，凭证仍使用 credential-state.json | [门面](../../python/src/aun_core/pubsub/__init__.py)、[Binding](../../python/src/aun_core/pubsub/binding.py) |
+| TS（Node.js） | 默认复用自身 AID 的 SQLite aun.db；start.state 覆盖 Bus 状态，credentialOptions.state 覆盖凭证存储，客户端状态仍走默认持久层 | [门面与 options](../../ts/src/pubsub/index.ts)、[凭证](../../ts/src/pubsub/credentials.ts) |
+| JS（浏览器） | 默认复用 IndexedDB aun-keystore/metadata；Bus 状态按身份及 Bus 隔离，客户端另区分角色及设备实例；显式适配器与 TS 相同 | [门面](../../js/src/pubsub/index.ts)、[凭证](../../js/src/pubsub/credentials.ts) |
+| Go | 默认复用自身 AID 的 SQLite aun.db；显式 StatePath 的 Bus 状态使用 event-service.sqlite3，凭证仍使用 credential-state.json | [门面](../../go/pubsub_service.go)、[类型](../../go/pubsub_types.go) |
 
-原生端数据库路径统一为 `{aun_path}/AIDs/{self-aid}/aun.db`，复用 TokenStore 和 metadata_kv，凭证键为 `pubsub_credentials_v1`；浏览器复用现有 IndexedDB 元数据层和同一键。显式文件或 credentialOptions.state 优先，不同时写默认数据库。凭证重启恢复、AID 隔离和自定义存储优先级均需验证。
+原生端数据库路径为 `{aun_path}/AIDs/{self-aid}/aun.db`，复用 TokenStore 的元数据或实例状态层；浏览器复用现有 IndexedDB 元数据层。默认凭证键仍为 `pubsub_credentials_v1`。Bus 状态按身份和 Bus 隔离，Go 另使用实例状态隔离；客户端状态按身份、Bus、角色及设备实例隔离。显式 state_path/StatePath 或 start.state 仅覆盖对应 Bus 状态，客户端队列仍走默认本地库；credentialOptions.state 仅覆盖凭证材料。Python/Go 首次可导入旧 event-service.json，后续写入 SQLite，保留旧文件。
+
+Bus 恢复须复核租约原期限、当前目录与白名单、凭证有效性及撤销状态；已撤权的 scope 和订阅不得恢复，仍有效的权限可以保留。内建凭证适配器随租约保存能力约束所需的原授权参数，恢复时重新校验当前凭证链、状态证明、期限、撤销及约束，通过后才重建内存验证上下文；旧记录缺必要上下文时要求重新鉴权。暂时网络或读取故障应中止启动并保留原持久关系，不能按撤权过滤后覆盖存储。客户端恢复不能复用失效授权或延长原事件期限，也不能让结果缓存淘汰尚未成功的持久待发布记录。
 
 Python 使用 snake_case，TS/JS 使用 camelCase（发布选项也接受 snake_case），Go 使用导出方法和 `PubSubPublishOptions`。Python/TS/JS next_event 超时为秒，Go 通过 context 控制。内部持久字段及分页 token 不承诺跨语言交换；移植应保证线上协议互通，不照搬另一语言运行时对象布局。
 
-文件适配采用平台路径 API 和 UTF-8，浏览器用其可用持久层；保存完成后才确认需要持久保证的配置/签发变更。独立 SDK 不依赖 Kite 模块共享代码，也不增加语言专有 IPC。
+文件适配采用平台路径 API 和 UTF-8，浏览器等待 IndexedDB 事务完成；保存完成后才确认目录、订阅、签发变更及发布入队。持久写入失败须向调用方报告，保留原待发布记录；恢复读取失败后应允许重试启动。独立 SDK 不依赖 Kite 模块共享代码，也不增加语言专有 IPC。
 
 ## 9. 统计、错误与验收场景
 
 stats 仅由本地 Bus 宿主调用，可按 event_name 过滤，含 service_aid、scope、since、as_of、counts；重启重置累计计数。`active_subscribers` 是去重 AID 数，`active_subscriptions` 是 AID/device/slot/event 关系数。`matched` 来自受理快照，`submitted` 是 AUN 接受的目标设备投递，`unconfirmed` 是结果未知；均不等于应用处理成功。具体字段见[应用指南 §7](AUN事件发布订阅应用集成指南.md#7-持久化统计与故障定位)。
 
+公开 `publications` / `subscriptions`（Go 为 `Publications` / `Subscriptions`）按参数 `role` 选择本地 Bus 或对应 Pub/Sub，省略优先 Bus；role 不进入线上请求。本地 Bus 返回全局，远端 publications 只返回可信 sender AID 且处于当前 publish scope 内的条目，subscriptions 只返回当前 device/slot 租约实际建立的关系。查询必须复核当前凭证、撤销、范围及设备绑定，能力约束使用租约已验证的原授权参数，不以查询参数重新解释原约束；暂时查证失败应查询失败，不能据此删除有效关系。
+
+发布条目为 `publisher_aid、event_name、published、first_published_at、last_published_at`，只在首次成功受理时更新，重复去重和拒绝不计；使用独立运行期汇总，不随事件 TTL 淘汰、不存正文或逐消息 ID，Bus 重启清零。汇总默认受限于 publication_items=8192、publication_bytes=4 MiB；条目新增或字节增量超额在受理前报 OVERLOADED。订阅条目为 `subscriber_aid、event_name、device_id、slot_id、expires_at`，仅含有效实际关系，不把 scope 当订阅；客户端订阅意图的原持久化机制不变。
+
+回复固定为 `service_aid、since、as_of、items、next_page_token`，末页 token 为 null。可选 event_name 仅过滤可见条目，无匹配空页；limit 默认50、范围1—200。keyset 按 Unicode 码点升序，以发布 `(event_name,publisher_aid)` 或订阅 `(event_name,subscriber_aid,device_id,slot_id)` 排序；签名 token 绑定 op、本地/远端来源、sender、lease_id、scope、过滤条件及末键，60秒有效，不与 catalog token 混用。Bus 重启后旧 token 失效，应从首页重查。每次续页按当前有效数据继续，无冻结快照；完整 wire 回复受 catalog_page_bytes（最多64 KiB）约束，单项放不下报 MESSAGE_TOO_LARGE。
+
 | 错误族 | 当前边界 |
 | --- | --- |
-| `BUS_NOT_BOUND/BUS_ROLE_CONFLICT/ROLE_MISMATCH` | 本地绑定与角色不满足 |
+| `BUS_NOT_BOUND/ROLE_MISMATCH` | 目标 Bus 或调用所需角色未绑定；同 Bus 的多个角色可以并存 |
 | `SERVICE_IDENTITY_MISMATCH/DEVICE_CONFLICT/SERVICE_LEASE_LOST/SERVICE_NOT_STARTED` | 宿主身份或实例生命周期不满足 |
 | `FORBIDDEN/REAUTH_REQUIRED/CREDENTIAL_UNAVAILABLE` | 权限、租约或凭证证明不可用；按来源重新核验，不自动扩大授权 |
 | `CATALOG_REQUIRED/UNKNOWN_EVENT/SCHEMA_MISMATCH/UNSUPPORTED_SCHEMA_VERSION/INVALID_CONTENT` | 目录、版本或内容不满足 |
@@ -544,11 +575,14 @@ stats 仅由本地 Bus 宿主调用，可按 event_name 过滤，含 service_aid
 
 | 场景 | 必须断言 | 现有依据 |
 | --- | --- | --- |
-| 白名单/凭证完整应用流程 | 多事件授权自动加载目录、分别发布/订阅/回调、角色隔离、JSON 对象、回执分层、两种接收方式 | [Python application](../../python/tests/unit/test_pubsub_application.py)、[TS client](../../ts/tests/unit/pubsub-client.test.ts)、[Go client](../../go/pubsub_client_test.go) |
+| 白名单/凭证完整应用流程 | 多事件授权自动加载目录、同 client 同 Bus 多角色并存且独立授权、JSON 对象、回执分层、两种接收方式 | [Python application](../../python/tests/unit/test_pubsub_application.py)、[TS client](../../ts/tests/unit/pubsub-client.test.ts)、[Go client](../../go/pubsub_client_test.go) |
+| 目录与待发布持久化 | SQLite/IndexedDB 重开、目录与订阅增量合并、写入成功才入队、成功删除正文、中断恢复原 ID/TTL、过期失败可查、写入失败不确认成功 | [Python client](../../python/tests/unit/test_pubsub_client.py)、[Python service](../../python/tests/unit/test_pubsub_service.py)、[TS client](../../ts/tests/unit/pubsub-client.test.ts)、[Go client](../../go/pubsub_client_test.go) |
 | 凭证状态与恢复 | 完整绑定、撤销、证明到期、登记回复丢失、超窗确认及持久材料 | [Python credentials](../../python/tests/unit/test_pubsub_credentials.py)、[Go credentials](../../go/pubsub_credentials_test.go) |
 | 设备与实例 | 同 AID 多设备独立订阅、同设备不同 slot、冲突、失租、旧代次不可消费 | [恢复 E2E](../../python/tests/e2e_test_event_pubsub_recovery.py)、[Message 测试](../../../extensions/services/message/go/cmd/message-go/main_test.go) |
 | 容量与公平 | 64 条/64 MiB、未接管不 ACK、容量唤醒、每 AID 单飞、16/8/4/4 和前台推进 | [容量契约](../../python/tests/unit/test_pubsub_capacity_contracts.py)、[Pull Gate](../../python/tests/unit/test_pubsub_pull_gate.py)、[Go scheduler](../../go/pubsub_scheduler_test.go) |
 | 目录与关系变更 | authorize 全封装预算、自动续页与关闭代次、租约范围目录、token 隔离、版本窗口、缩权和取消 | [Python scenarios](../../python/tests/unit/test_pubsub_scenarios.py)、[JS service](../../js/tests/unit/pubsub-service.test.ts) |
 | 跨 SDK | 四种 Bus 分别验证两种授权、同端、有向跨端和设备场景 | [验收 runner](../../tests/cross-sdk/runner/run_pubsub_acceptance.py)、[实施计划](../../../docs/AUN文档/AUN事件订阅发布TDD实施计划.md) |
 
-本轮[128项归档](../../tests/cross-sdk/artifacts/pubsub-4sdk-20261105/remove-manager-acceptance/final-acceptance-summary.json)由四种Bus各32/32组成，覆盖两种授权、同SDK和有向跨SDK；256份内嵌目录经核对，未显式调用catalog。默认凭证入库另由真实SQLite/IndexedDB重开专项签收，详见[实施计划 §9.9](../../../docs/AUN文档/AUN事件订阅发布TDD实施计划.md#99-凭证默认存储授权目录与移除管理身份)。历史208项保留；真实浏览器、macOS、真实双域设备E2E、实填64 MiB/RSS压力未纳入。
+此前[128项归档](../../tests/cross-sdk/artifacts/pubsub-4sdk-20261105/remove-manager-acceptance/final-acceptance-summary.json)由四种Bus各32/32组成，覆盖两种授权、同SDK和有向跨SDK；256份内嵌目录经核对，未显式调用catalog。默认凭证入库另由真实SQLite/IndexedDB重开专项签收，详见[实施计划 §9.9](../../../docs/AUN文档/AUN事件订阅发布TDD实施计划.md#99-凭证默认存储授权目录与移除管理身份)。该归档不作为本次角色并存与发布队列持久化变更的验收结果。历史208项保留；真实浏览器、macOS、真实双域设备E2E、实填64 MiB/RSS压力未纳入。
+
+本次变更已通过本机相关单元测试、SQLite/IndexedDB 存储重开与故障模拟及静态检查，未执行真实服务 E2E 或浏览器网络 E2E。

package/_packed_docs/sdk/INDEX.md

@@ -1,6 +1,6 @@
 # AUN SDK 文档索引
 
-> 三层索引：Layer 1 文档地图，Layer 2 主题交叉索引，Layer 3 单篇摘要。
+> 当前四 SDK 源码版本为 **0.5.34**；现行入口为本目录的基础手册、RPC 手册与 0.5.34 版本专题。`0.5.xx-*` 为版本增量专题，CHANGELOG 保留历史记录；完整事件协议另见发布订阅专题。三层索引：Layer 1 文档地图，Layer 2 主题交叉索引，Layer 3 单篇摘要。
 
 ---
 
@@ -8,14 +8,15 @@
 
 | 文档 | 说明 |
 |------|------|
-| [AUN事件发布订阅应用集成指南](AUN事件发布订阅应用集成指南.md) | 应用视角：整体架构、Bus/Pub/Sub调用序列与多事件API示例、凭证审批及结果处理 |
-| [AUN事件发布订阅开发移植指南](AUN事件发布订阅开发移植指南.md) | SDK移植视角：架构分层、三端内部序列与伪代码、协议状态、背压调度及四端验收 |
+| [AUN事件发布订阅应用集成指南](AUN事件发布订阅应用集成指南.md) | 应用视角：Bus/Pub/Sub多角色共存、两种授权、目录合并、SQLite/IndexedDB持久化与待发布恢复 |
+| [AUN事件发布订阅开发移植指南](AUN事件发布订阅开发移植指南.md) | SDK移植视角：独立角色租约、目录与订阅持久化、先落盘再发布、成功删除、原TTL与新发送尝试、凭证关系复核恢复及分角色实时清单查询 |
 | [0.5.21 SDK 应用集成指南](0.5.21-SDK应用集成指南.md) | TypeScript 接入 · batch 持久幂等 · peer 同步 · resolve/owner 展示 · 凭证组织恢复 · 诊断与升级 |
 | [0.5.21 SDK 开发与移植指南](0.5.21-SDK开发与移植指南.md) | 四端公开契约 · peer 水位/流控/提交 · frontmatter 与共识缓存 · 原 CAS/旧任务/reset · checkpoint · 语言差异和验收 |
 | [0.5.22 SDK 应用集成指南](0.5.22-SDK应用集成指南.md) | TypeScript 接入 · 消息订阅 · 两种绑定与审批恢复 · resolve 展示 · 60 秒读缓存与刷新 · 撤销同步和完整成员包 |
 | [0.5.22 SDK 开发与移植指南](0.5.22-SDK开发与移植指南.md) | 后台退避 · 群状态 · 两种绑定与 Stage/CAS · 消息内部消费 · 撤销同步 · 组织恢复及配套服务修复 · 默认读缓存 · Rust 清单 |
 | [0.5.24 SDK 应用集成指南](0.5.24-SDK应用集成指南.md) | 当前身份与消息接入 · 无任务 Ownership · local 双／三身份编排 · resolve 与文件缓存 · 凭证组织 · 升级 |
 | [0.5.24 SDK 开发与移植指南](0.5.24-SDK开发与移植指南.md) | peer／batch 提交 · NS 事实与远端 CAS · local 短连接 · 观察与 PKI 缓存 · 持久化边界 · 语言差异和验收 |
+| [0.5.34 SDK 应用集成指南](0.5.34-SDK应用集成指南.md)、[开发与移植指南](0.5.34-SDK开发与移植指南.md)、[变更与跨端对齐](../../python/CHANGES_FOR_PARITY.md#v0534)；[Python](../../python/CHANGELOG.md)、[Go](../../go/CHANGELOG.md)、[TS](../../ts/CHANGELOG.md)、[JS](../../js/CHANGELOG.md) CHANGELOG | 对照已发布 0.5.33：EventService 多角色、SQLite/IndexedDB 目录与 durable outbox、实时目录查询、Storage 条件 ACL、Group FS、Service Proxy 及弹性补拉 |
 | [0.5.32 应用集成指南](0.5.32-SDK应用集成指南.md)、[开发与移植指南](0.5.32-SDK开发与移植指南.md)、[变更与跨端对齐](../../python/CHANGES_FOR_PARITY.md#v0532)；[Python](../../python/CHANGELOG.md)、[Go](../../go/CHANGELOG.md)、[TS](../../ts/CHANGELOG.md)、[JS](../../js/CHANGELOG.md) CHANGELOG | 对照已发布 0.5.31：EventService · 设备租约 · 有界背压 · 消息调度 · 限流缓存 · Ownership · 已有验证范围 |
 | [0.5.30 SDK 应用集成指南](0.5.30-SDK应用集成指南.md)、[开发与移植指南](0.5.30-SDK开发与移植指南.md)、[变更与跨端对齐](../../python/CHANGES_FOR_PARITY.md#v0530--控制流按需恢复与-sdk-行为对齐未发布) | 按需控制流恢复 · observer.forward 本地字段剥离 · human owner 本地 Ownership · Storage 版本预检 · 内部 RPC 边界 |
 | [0.5.29 应用指南](0.5.29-SDK应用集成指南.md)、[开发与移植指南](0.5.29-SDK开发与移植指南.md)、[变更与跨端对齐](../../python/CHANGES_FOR_PARITY.md#v0529--共识查询缓存与普通上传未发布)；[Python](../../python/CHANGELOG.md)、[Go](../../go/CHANGELOG.md)、[TS](../../ts/CHANGELOG.md)、[JS](../../js/CHANGELOG.md) CHANGELOG | 0.5.29 基线：共识默认 force=false、NS 单次查询、无 TTL 的 ETag 缓存、resolve、普通上传锁／恢复与四端移植 |
@@ -82,7 +83,14 @@
 
 - 当前身份与消息接入、无任务 Ownership、两个 local 场景、名片及文件缓存、凭证组织与升级 → [应用集成指南](0.5.24-SDK应用集成指南.md)
 - 三主体分层、提交／ACK、NS 事实和远端 CAS、local 身份隔离、缓存新鲜度、语言差异与验收 → [开发与移植指南](0.5.24-SDK开发与移植指南.md)
-- 当前 0.5.32 应用调用与升级影响 → [应用集成指南](0.5.32-SDK应用集成指南.md)；四端契约、内部流程及验收 → [开发与移植指南](0.5.32-SDK开发与移植指南.md)；源码差异与已有验证 → [parity](../../python/CHANGES_FOR_PARITY.md#v0532)。覆盖 EventService、VFS Cache、消息恢复、RPC/限流、Ownership 与各端修复。
+
+### 0.5.34 接入与移植
+
+- 应用接入、EventService 同 Bus 多角色、目录／订阅持久化、先持久再发布、TTL 恢复、实时发布／订阅目录及 Group FS／Service Proxy → [应用集成指南](0.5.34-SDK应用集成指南.md)
+- 四端共同契约、SQLite/IndexedDB 状态边界、发布队列恢复、条件 ACL、Group FS／Storage Content-Type、Service Proxy 和弹性补拉 → [开发与移植指南](0.5.34-SDK开发与移植指南.md)
+- 源码差异、服务依赖和已有验证边界 → [parity 0.5.34](../../python/CHANGES_FOR_PARITY.md#v0534)
+
+- 0.5.32 历史应用调用与升级影响 → [应用集成指南](0.5.32-SDK应用集成指南.md)；四端契约、内部流程及验收 → [开发与移植指南](0.5.32-SDK开发与移植指南.md)；源码差异与已有验证 → [parity](../../python/CHANGES_FOR_PARITY.md#v0532)。EventService 的当前增量见上面的 0.5.34 专题。
 - 0.5.30 应用行为、主动 Pull 边界、本地 Ownership、Storage 版本及内部 RPC → [应用指南](0.5.30-SDK应用集成指南.md)；控制恢复、转发净化、YAML 与版本预检的四端契约 → [开发与移植指南](0.5.30-SDK开发与移植指南.md)；验证范围见 [parity](../../python/CHANGES_FOR_PARITY.md#v0530--控制流按需恢复与-sdk-行为对齐未发布)。
 - 0.5.29 应用接入、共识输入输出、resolve、上传与业务服务 → [应用指南](0.5.29-SDK应用集成指南.md)；缓存并发、上传恢复、NS 配套与四端落点 → [开发与移植指南](0.5.29-SDK开发与移植指南.md)；已有增量及验证见 [历史 parity](../../python/CHANGES_FOR_PARITY.md#v0529--共识查询缓存与普通上传未发布)。
 - 0.5.28 agent.md 校验、共识 fresh、分类控制消息、Owner 通知、风控和四端验证边界 → [应用指南](0.5.28-SDK应用集成指南.md)、[开发与移植指南](0.5.28-SDK开发与移植指南.md)；实现差异见 [历史 parity](../../python/CHANGES_FOR_PARITY.md#v0528--校验控制消息与风控未发布)。0.5.27 历史版本见对应旧指南与 parity。
@@ -133,7 +141,7 @@
 
 ### RPC 与事件
 
-- AUN EventService 整体架构、Bus/Pub/Sub应用流程图与多事件API示例 → [应用集成指南](AUN事件发布订阅应用集成指南.md)；SDK内部序列与伪代码、四端契约、授权分页、实例代次、64条/64 MiB及16/8/4/4 → [开发移植指南](AUN事件发布订阅开发移植指南.md)
+- AUN EventService 0.5.34 版本增量、多角色共存、目录持久化、durable outbox 及实时清单 → [0.5.34 应用集成指南](0.5.34-SDK应用集成指南.md)、[0.5.34 开发与移植指南](0.5.34-SDK开发与移植指南.md)；完整事件租约、凭证、fanout 和协议流程 → [AUN事件发布订阅专题](AUN事件发布订阅应用集成指南.md)、[开发移植专题](AUN事件发布订阅开发移植指南.md)；公开门面见 [API 手册](06-API手册.md)
 - `client.call()` / `client.on()` → [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)
 - Python `connect()` 携带 `push_notify_aid/push_token` 自动登记，以及 `client.push.register/unregister` 运行期变更 → [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)、`docs/protocol/15-离线推送通知协议.md`
 - `client.notify()` 在线轻量通知、跨域 federation、在线/离线边界 → [Notify通知方案](Notify通知方案.md)
@@ -186,6 +194,10 @@ TypeScript 身份与消息接线、Ownership 审批恢复、resolve、默认缓
 
 定义消息 peer／batch／Gate、Ownership NS 事实和远端 CAS、Stage、local 专属 slot 与身份代际、展示及文件缓存、PKI 和 Credential 查询新鲜度、组织 checkpoint。列出四端兼容差异、Rust 核查与分层验收，不将已有专项证据等同完整发布验证。
 
+### 0.5.34 SDK 应用集成与开发移植指南
+
+两份 0.5.34 专题分别覆盖应用接入和四端实现：EventService 多角色共存、目录与订阅合并恢复、发布 durable outbox、按事件汇总的实时目录，以及 Storage 条件 ACL、Group FS、Service Proxy 和弹性补拉。配套 parity 章节记录四端落点、服务依赖和未执行的部署／跨域验收边界。
+
 ### 0.5.32 更新日志与跨端对齐
 
 [应用集成指南](0.5.32-SDK应用集成指南.md)：本版变化/整体架构 L5-52、身份与入口 L53-87、白名单多事件流程 L88-171、凭证审批签发 L172-246、设备/租约/容量/存储 L247-282、VFS Cache L283-330、其它主要改动与验收 L331-350。
@@ -286,7 +298,7 @@ TypeScript 身份与消息接线、Ownership 审批恢复、resolve、默认缓
 
 ### 06-API手册
 
-列出 AIDStore、resolve 的四语言 opts/输入输出、frontmatter 标准与扩展字段、ownership 七种共识状态及 owner.md 快照/TTL/失败语义、AID、AUNClient、Ownership 2.1 与 Credential/Org 入口、Python PushFacade、P2P peer/全部对端 Pull、轻量 pending 快照与可选整体估计/Pull 页内渲染计数、50k 内存去重 和应用幂等、Message/Group History 与已读门面、生命周期事件、agent.md、ServiceProxyClient、E2EE 和 Group Index facade。
+列出 AIDStore、resolve 的四语言 opts/输入输出、frontmatter 标准与扩展字段、ownership 七种共识状态及 owner.md 快照/TTL/失败语义、AID、AUNClient、Ownership 2.1 与 Credential/Org 入口、EventService 多角色/持久化/发布订阅目录查询、Python PushFacade、P2P peer/全部对端 Pull、轻量 pending 快照与可选整体估计/Pull 页内渲染计数、50k 内存去重和应用幂等、Message/Group History 与已读门面、生命周期事件、agent.md、ServiceProxyClient、E2EE 和 Group Index facade。
 
 ### 07-错误处理
 
@@ -310,7 +322,7 @@ TypeScript 身份与消息接线、Ownership 审批恢复、resolve、默认缓
 
 ### 09-proxy-rpc-manual
 
-定义 Service Proxy 的 Gateway 控制面 `proxy.register_services` / `proxy.unregister_services` / `proxy.list_services`，以及 proxy-server 数据面 `register_services` 隧道消息、双注册顺序、服务列表一致性和 wakeup 路由语义。
+定义 Service Proxy 的 Gateway 控制面 `proxy.register_services` / `proxy.unregister_services` / `proxy.list_services`，以及 proxy-server 数据面 `register_services` 隧道消息、双注册顺序、服务列表一致性和 wakeup 路由语义；列出四 SDK 入口及 Browser provider 隧道的 `webSocketFactory` 要求。
 
 ### Notify通知方案
 
@@ -318,10 +330,10 @@ TypeScript 身份与消息接线、Ownership 审批恢复、resolve、默认缓
 
 ### AUN事件发布订阅应用集成指南
 
-[应用集成指南](AUN事件发布订阅应用集成指南.md)：面向应用开发者：整体架构 L9-43、三角色总流程 L44-75、Facade与角色阅读入口 L76-102；Bus启动序列及配置 L105-170、Sub订阅/回调序列及多事件示例 L171-221、Pub异步发布序列及结果示例 L222-279；凭证启动/签发验证序列/两方接入 L280-387、多设备与目录 L388-403、生命周期 L404-419、默认存储/本地统计 L420-453、源码验收 L454-459。
+[应用集成指南](AUN事件发布订阅应用集成指南.md)：面向应用开发者：整体架构 L9-43、三角色总流程 L44-76、Facade与多角色入口 L77-103；Bus启动及目录合并 L106-174、Sub订阅/回调及恢复 L175-230、Pub先持久再发布及结果 L231-290；凭证启动/签发验证及两方接入 L291-398、多设备与目录 L399-414、生命周期与原ID/TTL恢复 L415-430、SQLite/IndexedDB及成功删除边界/本地清单与统计 L431-477、源码与本次验收边界 L478-484。
 
 ### AUN事件发布订阅开发移植指南
 
-[开发移植指南](AUN事件发布订阅开发移植指南.md)：面向SDK维护与移植：整体架构及分层 L5-62、Bus注册续租序列/单调截止伪代码 L63-129、消息字段/设备路由/幂等 L130-179；Bus签发与Pub/Sub鉴权序列/目录原子提交伪代码 L180-316、目录契约 L317-332；Pub异步入队与Bus背压fanout序列/伪代码/预算 L333-416、Sub接收及续租恢复序列/伪代码 L417-508、四端存储 L509-529、统计错误验收 L530-554。
+[开发移植指南](AUN事件发布订阅开发移植指南.md)：面向SDK维护与移植：整体架构及多角色分层 L5-64、Bus注册续租及持久加载 L65-132、消息字段/设备路由/幂等 L133-184；Bus签发与Pub/Sub独立鉴权/目录原子提交 L185-323、目录合并契约 L324-341；Pub耐久入队/成功删除/原TTL与Bus背压fanout预算 L342-430、Sub接收及订阅与发布恢复 L431-529、四端SQLite/IndexedDB状态与隔离 L530-554、统计错误及本次验收边界 L555-588。
 
 

package/_packed_docs/sdk/README.md

@@ -1,5 +1,7 @@
 # AUN Protocol - SDK 文档
 
+本目录为四 SDK **0.5.34** 的现行主文档入口；带版本号的专题及 CHANGELOG 保留其历史版本语义，不能替代当前 API 手册。
+
 AUN（Agent Union Network）定义 Agent 之间安全通信的标准接口，基于 WebSocket + JSON-RPC 2.0，涵盖身份、认证、消息、群组、存储、流式传输和端到端加密。
 
 ---
@@ -11,8 +13,9 @@ AUN（Agent Union Network）定义 Agent 之间安全通信的标准接口，基
 - **Gateway 连接**：当前各语言 SDK 稳定支持 Gateway 接入；Peer / Relay 仍处于协议定义或未实现状态。
 - **默认 E2EE**：P2P 和 Group V2 消息默认加密；普通明文消息需要显式关闭加密。
 - **统一 RPC / 事件 / Notify**：业务方法通过 `client.call(method, params)` 调用，事件通过 `client.on(event, handler)` 订阅；在线轻量通知通过 `client.notify()` 发送，支持同域和跨域在线 federation，详见 `Notify通知方案.md`。
+- **事件发布订阅**：四 SDK 的 `EventService` 支持同一 AID 在同一 Bus 上同时承担 bus/pub/sub；目录、订阅和待发布队列使用 SQLite／IndexedDB 持久化，`publications` / `subscriptions` 查询当前发布汇总与有效订阅，见 [API 手册](06-API手册.md#eventservice-事件发布订阅)。
 - **当前 access token**：自行发起要求 AID Bearer 的 HTTP 数据面请求时，每次请求前使用 Python `get_access_token()`、TypeScript / JavaScript `getAccessToken()` 或 Go `GetAccessToken()` 读取后台刷新维护的缓存；不得长期复用 `authenticate()` 首次返回的字符串。
-- **Service Proxy**：Python SDK 提供 `ServiceProxyClient`，provider 会先向 Gateway 注册 `proxy.*` 控制面服务列表，再在每条 proxy-server 隧道认证后注册数据面服务列表。
+- **Service Proxy**：Python、TypeScript、JavaScript 和 Go 均提供 `ServiceProxyClient`；provider 先向 Gateway 注册 `proxy.*` 控制面服务列表，再在每条 proxy-server 隧道认证后注册数据面服务列表。浏览器 JavaScript 需使用可承载 Authorization Bearer 的自定义 WebSocket factory。
 
 ---
 
@@ -33,16 +36,16 @@ BOB = f"bob-{random.randint(1000,9999)}.{DOMAIN}"
 
 
 async def create_client(aid: str) -> AUNClient:
-    store = AIDStore(aun_path="~/.aun/myapp", encryption_seed="")
+    store = AIDStore(aun_path="~/.aun/myapp", encryption_seed="", slot_id="main")
     loaded = store.load(aid)
     if not loaded["ok"]:
-        registered = await store.register(aid)
+        registered = await store.register(aid, type="human")
         if not registered["ok"]:
             raise RuntimeError(registered["error"]["message"])
         loaded = store.load(aid)
 
     client = AUNClient(loaded["data"]["aid"])
-    await client.connect({"slot_id": "main", "auto_reconnect": True})
+    await client.connect({"auto_reconnect": True})
     return client
 
 
@@ -109,12 +112,14 @@ Layer 1: 安全层   TLS + AUN E2EE
 | [03-核心概念](03-核心概念.md) | AID、AIDStore、AUNClient、九态状态机、E2EE |
 | [04-连接与认证](04-连接与认证.md) | 注册、加载、认证、当前 access token getter、连接、Python Push 自动登记、事件、agent.md |
 | [05-E2EE加密通信](05-E2EE加密通信.md) | E2EE 收发、ProtectedHeaders、密钥管理 |
-| [06-API手册](06-API手册.md) | AIDStore / AID / AUNClient / 四 SDK access token getter / Python PushFacade / ServiceProxyClient / 事件 / RPC 索引 |
+| [06-API手册](06-API手册.md) | AIDStore / AID / AUNClient / 四 SDK access token getter / EventService / Python PushFacade / ServiceProxyClient / 事件 / RPC 索引 |
 | [07-错误处理](07-错误处理.md) | Result、异常层级、错误码、重试策略 |
 | [08-最佳实践](08-最佳实践.md) | 幂等连接、多 AID、资源清理、测试数据保护 |
 | [AUN Storage架构设计](<../aun-fs/AUN Storage架构设计.md>) | Storage SDK VFS、控制面/数据面分离、服务端分层、类 Linux 权限、mount/symlink 和关键时序 |
 | [Notify通知方案](Notify通知方案.md) | `client.notify()` 在线轻量通知、跨域 federation 和可靠消息分工 |
-| [CHANGELOG-0.5.6](CHANGELOG-0.5.6.md) | **0.5.6 版本更新日志**：验签缓存、消息窗口、显式 change-seed 与四语言能力边界 |
+| [AUN事件发布订阅应用集成指南](AUN事件发布订阅应用集成指南.md) | Bus / Pub / Sub 调用顺序、多角色、持久化恢复与目录查询 |
+| [AUN事件发布订阅开发移植指南](AUN事件发布订阅开发移植指南.md) | 四 SDK 的协议、队列、授权、持久化及实现边界 |
+| [CHANGELOG-0.5.6](CHANGELOG-0.5.6.md) | **历史 0.5.6 更新日志**：验签缓存、消息窗口、显式 change-seed 与当时的四语言能力边界 |
 
 RPC 专项手册：
 

package/dist/agent-md.d.ts

@@ -1,7 +1,7 @@
 import { AID } from './aid.js';
 import { type OwnershipRelease, type OwnershipVerificationStatus } from './ownership-proof.js';
 import type { ModuleLogger } from './logger.js';
-import { type OwnershipAgentObservation, type OwnershipSavedFile } from './ownership-v21.js';
+import { type OwnershipAgentObservation, type OwnershipConsensusResult, type OwnershipSavedFile } from './ownership-v21.js';
 export declare function buildOwnershipReleaseAgentMd(content: string, release: OwnershipRelease): string;
 export declare function buildOwnershipAgentMd(content: string, owner: string, proof: Record<string, unknown>): string;
 export declare function updateOwnershipAgentMd(content: string, fields: Record<string, unknown>): string;
@@ -137,6 +137,7 @@ export declare class AgentMdManager {
         version: number;
         content_hash: string;
     }): boolean;
+    localOwnershipConsensus(aid: string, record: Record<string, unknown> | null): OwnershipConsensusResult | null;
     private _clearConfirmedDraft;
     upload(content?: string | null, originalCondition?: OwnershipSavedFile['condition']): Promise<Record<string, unknown>>;
     readAgentMdFresh(aid: string): Promise<{

package/dist/agent-md.js

@@ -440,6 +440,23 @@ export class AgentMdManager {
             return true;
         });
     }
+    localOwnershipConsensus(aid, record) {
+        const snapshot = record?.ownership_snapshot;
+        if (!snapshot || snapshot.status !== 'consensus' || snapshot.sub_aid !== aid || snapshot.lock !== 'locked'
+            || !snapshot.agent_md_etag || snapshot.agent_md_etag !== record?.remote_etag || record.remote_status === 'missing'
+            || typeof record.content !== 'string' || AgentMdManager.contentEtag(record.content).slice(1, -1) !== snapshot.agent_md_sha256)
+            return null;
+        try {
+            const statement = parseOwnershipFile(record.content, 'agent', { expectedSubAid: aid }).statement;
+            if (!statement || statement.owner_aid !== snapshot.owner_aid || statement.relation_version !== snapshot.relation_version)
+                return null;
+            return { status: 'consensus', sub_aid: aid, owner_aid: statement.owner_aid, relation_version: statement.relation_version,
+                lock: 'locked', agent_md_etag: snapshot.agent_md_etag, agent_md_sha256: snapshot.agent_md_sha256 };
+        }
+        catch {
+            return null;
+        }
+    }
     _clearConfirmedDraft(aid, content) {
         this._withRecordLock(aid, () => {
             const record = this._readRecordUnlocked(aid, true);