@agentunion/fastaun 0.5.33 → 0.5.35

package/_packed_docs/sdk/0.5.33-SDK/345/274/200/345/217/221/344/270/216/347/247/273/346/244/215/346/214/207/345/215/227.md

@@ -1,304 +1,499 @@
-# AUN SDK 0.5.33 开发与移植指南
-
-面向 Python、Go、TypeScript、浏览器 JavaScript SDK 维护者及新语言移植者。以仓库 `072b7c69f`（0.5.32）对照截至 2026-11-07 的未提交变更，包含已暂存脚本和相关未跟踪的 Python 压测源码。应用接线见 [0.5.33 应用集成指南](0.5.33-SDK应用集成指南.md)，完整改动索引见 [parity 0.5.33](../../python/CHANGES_FOR_PARITY.md#v0533)。
-
-## 1. 范围与实现分层
-
-| 本轮工作 | SDK 负责 | 配套服务负责 |
-| --- | --- | --- |
-| 控制消息兼容 | 发送前核对能力、准备类别、解密后分派 | Gateway 可信会话；Message／Group 兼容选择投递通道 |
-| Ownership 批次 | 批次上下文、归组事件、逐项审批与结果汇总 | NS 继续处理原有单项关系与名片提交 |
-| 本地共识优先 | 恢复并核验本地快照，按需查询 | NS 返回当前权威事实，管理提交仍做原有校验 |
-| 批量 ACL | VFS／LowLevel 参数贯通、失败时定向失效缓存 | Storage 合并授权对象、逐项处理及权限计数 |
-| Python 专项 | 群 Pull 去重复闸门、退避区分、容量压测 CLI | 保持现有服务接口 |
-
-```mermaid
-%%{init: {"theme":"base","flowchart":{"curve":"linear","nodeSpacing":24,"rankSpacing":32}}}%%
-flowchart TB
-    A["宿主应用"]:::app
-    subgraph SDK["每个 AID 进程中的 SDK"]
-        direction TB
-        F["AUNClient 门面"]:::entry
-        O["Ownership<br/>批次 / 单项审批 / 共识"]:::logic
-        V["Storage VFS / LowLevel<br/>多 AID ACL"]:::logic
-        E["已有 EventService<br/>Pub / Bus / Sub"]:::inherited
-        L["本地身份仓库<br/>agent.md / 共识快照 / 读缓存"]:::local
-        P["RPC 准备与分类交付<br/>能力 / E2EE / 内部消费"]:::entry
-        F --> O & V & E
-        O & V --> L
-        O & V & E --> P
-    end
-    G["Gateway<br/>认证身份 / 设备 / RPC 转发"]:::infra
-    subgraph SERVICES["AUN 服务"]
-        direction LR
-        M["Message / Group<br/>消息通道与 TTL"]:::infra
-        N["NS<br/>名片与 Ownership 事实"]:::infra
-        S["Storage<br/>对象 / ACL / CAS"]:::infra
-        C["Credential<br/>登记 / 状态 / 撤销"]:::infra
-    end
-    A --> F
-    P --> G
-    G --> M & N & S & C
-    classDef app fill:#eff6ff,stroke:#60a5fa,color:#1e3a8a,rx:10,ry:10
-    classDef entry fill:#eef2ff,stroke:#818cf8,color:#312e81,rx:10,ry:10
-    classDef logic fill:#ecfdf5,stroke:#6ee7b7,color:#065f46,rx:10,ry:10
-    classDef local fill:#fff7ed,stroke:#fdba74,color:#9a3412,rx:10,ry:10
-    classDef inherited fill:#f8fafc,stroke:#cbd5e1,color:#475569,rx:10,ry:10
-    classDef infra fill:#f8fafc,stroke:#94a3b8,color:#334155,rx:10,ry:10
-    style SDK fill:#ffffff,stroke:#e2e8f0,rx:12,ry:12
-    style SERVICES fill:#f8fafc,stroke:#e2e8f0,rx:12,ry:12
-```
-
-EventService、VFS 定向缓存、RPC `16/8/4/4` 预算及 Bus 单实例机制沿用 0.5.32；本版不重新定义事件目录或 fanout。Pub／Bus／Sub 使用 `client.EventService`（Go 为 `EventService()`），详细约束见 [0.5.32 移植指南](0.5.32-SDK开发与移植指南.md)与[事件服务移植指南](AUN事件发布订阅开发移植指南.md)。
-
-## 2. 控制消息：先准备语义，再决定传输类别
-
-### 2.1 共同契约与字段位置
-
-| 内容与场景 | 能力已协商 | 类别或 SDK 协议未协商 |
-| --- | --- | --- |
-| 普通消息，P2P／群，明文／加密 | 普通路径 | 普通路径；群普通 TTL 不因控制能力缺失而被阻断 |
-| 应用 `control`，P2P／群，明文／加密 | 保留类别 | 构造请求时移除外层类别和可改写保护头类别，走普通投递 |
-| P2P 加密 `sdk_control` | 保留类别、协议与版本 | 移除外层路由类别；E2EE 内部类别、协议与版本保留 |
-| 明文 `sdk_control`、群 `sdk_control` | 本地拒绝 | 本地拒绝 |
-
-| 位置 | 含义与检查 |
-| --- | --- |
-| RPC 参数 `message_class` | 请求投递类别；降级可省略，Go 不重新补为空字符串或 `normal` |
-| 明文 RPC 参数 `protected_headers` | 明文元数据所在层；服务端直接解析，并结合可信会话身份处理 |
-| E2EE 信封 `protected_headers` | 受认证的消息语义；P2P 通常在 `payload` 信封内，群 V2 在 `envelope` 内 |
-| 送达记录 `delivery_class` | 服务端实际选择的通道；普通通道不抹去信封中的 SDK 语义 |
-
-类别和协议冲突继续报参数错误。信封已加密签名时保持原样；降级调整路由，接收侧仍校验原受保护内容。普通加密信封未声明类别时按 `normal` 校验，不能将缺字段当作解密失败。
-
-### 2.2 发送与交付顺序
-
-```mermaid
-sequenceDiagram
-    autonumber
-    participant A as 应用或 SDK 内部模块
-    participant P as 发送准备
-    participant G as Gateway
-    participant M as Message / Group
-    participant R as 接收 SDK
-    participant D as 接收应用
-    A->>P: method / class / encrypt / payload / TTL
-    P->>P: 合并元数据，检查参数和当前协商结果
-    alt 明文或群 sdk_control
-        P-->>A: 本地拒绝，不进入传输
-    else 合法消息
-        alt 应用 control 未协商
-            P->>P: 移除可变类别，保留其它参数
-        else 加密 sdk_control 未协商
-            P->>P: 省略外层类别，保留 SDK 保护头
-        end
-        P->>G: 发送请求与明文正文或 E2EE 信封
-        G->>M: 转发可信身份与请求
-        M->>M: 选择通道，保留 TTL 与信封
-        M-->>R: 实际投递类别与消息
-        R->>R: 明文使用可信投递身份；加密核验信封
-        alt 已认证的 sdk_control
-            R->>R: 交给 SDK 协议处理器
-        else 应用 control 或 normal
-            R-->>D: 应用消息事件
-        end
-    end
-```
-
-以下是语义顺序，不是要求四端照搬同一函数：
-
-```text
-校验 class、场景、SDK 协议及版本
-若 sdk_control 为明文或群消息：拒绝
-若 control 未协商：移除可改写的类别字段
-若 sdk_control 未协商：仅省略传输类别
-明文直接发送；待加密正文按准备结果构造信封
-已签名信封保持不变，交配套服务选择通道
-接收按可信身份与受保护语义分派
-```
-
-Python 群分类 Pull 已由外层序列化，内部直接 fetch，避免同一请求重复进入同一闸门等待自身。移植时保留原有 Pull／ACK、水位与设备范围检查，只移除这一层重复等待。
-
-实现入口：[Python 准备与接收](../../python/src/aun_core/_client/control_messages.py)／[RPC](../../python/src/aun_core/_client/rpc_pipeline.py)、[TS RPC](../../ts/src/client/rpc-pipeline.ts)／[接收](../../ts/src/client/control-messages.ts)、[JS RPC](../../js/src/client/rpc-pipeline.ts)／[接收](../../js/src/client/control-messages.ts)、[Go 类别](../../go/control_messages.go)／[V2 路由](../../go/v2_routing.go)／[P2P](../../go/client_v2_e2ee.go)／[群](../../go/v2_group.go)。
-
-## 3. Ownership：批次归组，单项仍独立完成
-
-### 3.1 API 和固定上下文
-
-| 层 | Python | TS／JS | Go |
-| --- | --- | --- | --- |
-| 申请选项 | `batch_id` 关键字 | `OwnershipRequestOptions.batchId` | `OwnershipRequestOptions.BatchID` |
-| 绑定／转移 | `bind_owner_aid/bind_sub_aid/transfer_sub_aid` | `bindOwneraid/bindSubaid/transferSubaid` | `BindOwneraid/BindSubaid/TransferSubaid` |
-| 批量审批 | `accept_ownership_requests/reject_ownership_requests` | `acceptOwnershipRequests/rejectOwnershipRequests` | `AcceptOwnershipRequests/RejectOwnershipRequests` |
-| 传输字段 | 可选 UUIDv4 `batch_id` | 同左 | 同左 |
-
-原单项调用兼容。`batch_id` 贯穿任务上下文、Ownership 请求和应用事件；同一批次可涉及多个 AID，但每项保持自己的 `operation_id`。批次不是审批权限，也不替代已认证的原始请求。
-
-同一操作的发送者或原始上下文发生变化，包括增删／修改 `batch_id`，按冲突处理。应用将选择的操作 ID 列表交给审批接口；SDK 去重、逐项检查当前身份及代际，Go 还检查 context，返回 `total/succeeded/failed/results`。
-
-### 3.2 请求与审批链路
-
-```mermaid
-sequenceDiagram
-    autonumber
-    participant I as 多个申请 AID 的 SDK
-    participant M as AUN 消息投递
-    participant O as Owner SDK
-    participant A as Owner 应用
-    participant N as NS / 名片提交
-    loop 每个绑定或转移请求
-        I->>M: 独立 operation_id，共用 batch_id
-        M-->>O: 原始请求与认证发送方
-        O->>O: 核对固定上下文，保存请求
-        O-->>A: ownership.request，携带 batch_id
-    end
-    A->>A: 按批次展示，冻结本次选择的操作 ID
-    A->>O: accept / reject requests(operation_ids)
-    O->>O: 去重并固定执行身份
-    loop 每个 operation_id
-        O->>O: 检查原请求、当前身份及代际
-        O->>N: 沿用单项刷新、校验与提交流程
-        N-->>O: 单项当前结果
-        O->>O: 保存该项结果或错误，继续其它项
-    end
-    O-->>A: 汇总与逐项结果
-```
-
-批量返回中的成功数表示本次单项接口执行结果，后续关系是否已达共识仍以单项状态／既有工作流为准；`waiting` 不能被应用解释为全部关系已绑定完成。中途失败不会将整个批次回滚，身份变化后剩余项按错误记录。
-
-```text
-ids = 按首次出现顺序去重(operation_ids)
-identity = 当前 AID 与身份代际
-对每个 id：
-    核对 identity 与原始认证请求
-    执行原有单项 accept 或 reject
-    记录单项结果或错误
-返回汇总和 results
-```
-
-实现：[Python 消息校验](../../python/src/aun_core/ownership_v21.py)／[workflow](../../python/src/aun_core/ownership_workflow.py)／[门面](../../python/src/aun_core/client.py)、[TS workflow](../../ts/src/ownership-workflow.ts)／[门面](../../ts/src/client.ts)、[JS workflow](../../js/src/ownership-workflow.ts)／[门面](../../js/src/client.ts)、[Go workflow](../../go/ownership_workflow.go)。该批次扩展不新增服务器批量审批 RPC。
-
-## 4. 本地 agent.md 与共识：有效快照优先，管理仍刷新
-
-启动／连接后先读取本地名片。新的 Client 首次查询也可恢复已保存的 `ownership_snapshot`；恢复条件须同时成立：
-
-| 核对项 | 要求 |
-| --- | --- |
-| 共识和范围 | `status=consensus`、锁定、目标 AID 一致 |
-| 远端观察 | 快照 ETag 非空，与记录已观察远端 ETag 一致，记录不为 missing |
-| 本地正文 | 正文 SHA256 与快照摘要一致 |
-| 关系声明 | 名片中 owner、关系版本与快照一致 |
-
-```mermaid
-sequenceDiagram
-    autonumber
-    participant A as 连接 / 查询调用方
-    participant C as Client / AgentMdManager
-    participant L as 本地身份仓库
-    participant N as NS
-    A->>C: 连接后读取或首次共识查询
-    C->>L: 载入正文、观察记录与快照
-    L-->>C: 本地记录
-    alt 非 force，内存或持久快照有效
-        C-->>A: 复用本地结果
-    else 未达共识、记录变化或 force
-        C->>N: 原有权威读取
-        N-->>C: 当前关系与名片
-        C->>C: 核对关系、正文和观察代际
-        C->>L: 仅当前观察仍匹配时保存快照
-        C-->>A: 当前结果
-    end
-    Note over C,N: 绑定、审批、转移、释放等管理流程继续强制刷新
-```
-
-这里的 ETag 是 SDK 已观察到的状态；本地复用不会主动证明远端此刻没有变化。收到名片／Ownership 变化后清理相关快照，未达共识或显式强刷再查询，保持事件驱动，不新增周期首查任务。
-
-查询完成写回前要核对 Client、manager／存储根、缓存对象及观察版本，避免旧身份或旧请求覆盖新记录。群／组织首次访问同样复用有效本地共识；管理方法内部的强制刷新保持不变。
-
-实现：[Python manager](../../python/src/aun_core/agent_md.py)／[client](../../python/src/aun_core/client.py)、[TS manager](../../ts/src/agent-md.ts)／[client](../../ts/src/client.ts)、[JS manager](../../js/src/agent-md.ts)／[client](../../js/src/client.ts)、[Go client](../../go/client.go)。
-
-## 5. Storage ACL：从门面贯通到 RPC
-
-| 层 | 新列表参数 | 旧参数兼容 |
-| --- | --- | --- |
-| Python VFS／LowLevel | `grantee_aids` | `grantee_aid` |
-| TS／JS VFS／LowLevel | `granteeAids` | `granteeAid` |
-| Go VFS 选项 | `GranteeAIDs` | `GranteeAID` |
-| Go LowLevel | 原位置参数后可选 `[]string` | 原位置参数原样可用 |
-| RPC `storage.set_acl/remove_acl` | `grantee_aids` 数组，允许单元素 | `grantee_aid` |
-
-Storage 服务合并并归一化、去重两种字段，owner／grantee 的数据库访问和缓存键统一大小写；`max_uses` 对每个 AID 分别计数。SDK 透传授权意图，权限和次数判断留在服务端。
-
-```mermaid
-sequenceDiagram
-    autonumber
-    participant A as 应用
-    participant V as VFS / LowLevel
-    participant C as SDK 读缓存包装层
-    participant S as Storage，经 Gateway
-    A->>V: set / remove ACL，多 AID
-    V->>C: path + grantee_aids，兼容旧单值
-    C->>S: storage.set_acl / remove_acl
-    S->>S: 归一化、去重，逐项写入
-    alt 全部完成
-        S-->>C: 成功结果
-        C->>C: 定向失效受影响路径
-        C-->>A: 原结果
-    else 中途失败，可能已有部分写入
-        S-->>C: 原 RPC 错误
-        C->>C: 同样定向失效受影响路径
-        C-->>A: 继续抛出原错误
-    end
-    Note over C,S: 保留无关路径缓存；不承诺整个批次事务回滚
-```
-
-缓存失效需覆盖 Raw 调用、LowLevel 与 VFS。Go 的 mock／自定义 client LowLevel 路径也在错误返回前失效；Python 异常路径含取消后仍可能已有写入的情况。复用原有资源范围与在途回填保护，避免清空整个 Storage 缓存。
-
-```text
-尝试执行 ACL RPC
-成功：按既有规则失效相关路径并返回
-异常：对 set_acl / remove_acl 失效同一资源范围
-重新抛出原异常
-保留无关资源缓存
-```
-
-入口：[Python VFS](../../python/src/aun_core/storage/vfs.py)／[LowLevel](../../python/src/aun_core/storage/lowlevel.py)／[cache](../../python/src/aun_core/storage/cache.py)、[TS VFS](../../ts/src/storage/vfs.ts)／[LowLevel](../../ts/src/storage/lowlevel.ts)／[cache](../../ts/src/storage/read-cache.ts)、[JS VFS](../../js/src/storage/vfs.ts)／[LowLevel](../../js/src/storage/lowlevel.ts)／[cache](../../js/src/storage/read-cache.ts)、[Go VFS](../../go/storage_vfs.go)／[LowLevel](../../go/storage_lowlevel.go)／[Call](../../go/client.go)。
-
-对象上传、下载票据及共享链接的冗余返回字段精简属于配套服务响应契约变化，元数据保存方式保持原有设计。字段以 [Storage RPC 手册](09-storage-rpc-manual.md)为准；移植者不要重新依赖已移除的空值或重复 URL 字段。
-
-## 6. Python 独有实现与工具
-
-| 改动 | 当前行为 | 移植边界 |
-| --- | --- | --- |
-| 退避提示 | 有效正数 `retry_after_seconds/retry_after_ms` 优先，多个取较长值 | 本轮其它 SDK 没有相同退避调整 |
-| 缺少提示的拥塞 | `-32029/-32429` 且消息含 queue、backpressure、capacity 等拥塞标记，默认 1 秒 | 其它限流默认 60 秒；不因此自动重试应用写请求 |
-| 群分类 Pull | 外层已串行时内部直接 fetch | 保留 cursor／ACK 检查及原调度预算 |
-| 容量压测 | `aun bench run/report`，16 场景、多进程／身份通道、预算与续跑、JSON／HTML | Python CLI 能力，不是要求四端新增网络协议 |
-
-退避入口为 [transport](../../python/src/aun_core/transport.py)。容量工具由 [bench](../../python/src/aun_cli/commands/bench.py)注册 [bench_capacity](../../python/src/aun_cli/commands/bench_capacity.py)，实现拆分为[场景](../../python/src/aun_cli/benchmark/scenarios.py)、[执行与报告](../../python/src/aun_cli/benchmark/runner.py)、[节奏统计](../../python/src/aun_cli/benchmark/runtime.py)、[搜索](../../python/src/aun_cli/benchmark/search.py)。多进程入口与结果协议由工具自行处理，不影响 SDK Client 的单进程 API。
-
-报告区分有效完成量、延迟达标容量、稳态吞吐与发压端瓶颈；`pubsub` 场景包含发压端 Bus，不能解释为纯服务端容量。生成器不足、搜索未界定或持续验证未通过时，保留相应边界，不标记为已确认容量。
-
-## 7. 四端回归与移植验收
-
-| 范围 | Python | TS／JS | Go |
-| --- | --- | --- | --- |
-| 发送／接收类别 | [components](../../python/tests/unit/test_client_components.py) | 各端 `tests/unit/rpc-pipeline.test.ts`、`client.test.ts` | [client](../../go/client_test.go)、[V2 parity](../../go/v2_python_parity_test.go) |
-| 批次与审批 | [workflow](../../python/tests/unit/test_ownership_workflow.py) | 各端 `tests/unit/ownership-workflow.test.ts` | [workflow](../../go/ownership_workflow_test.go) |
-| 本地共识／管理强刷 | [agent.md](../../python/tests/unit/test_client_agent_md_api.py) | 各端 `tests/unit/client-agent-md-api.test.ts` | [agent.md](../../go/client_agent_md_api_test.go) |
-| ACL 与错误缓存 | [cache](../../python/tests/unit/test_storage_read_cache.py)、VFS 测试 | TS `storage-read-cache.test.ts`；JS `storage-vfs-read-cache.test.ts`；各端 VFS 测试 | [cache](../../go/storage_read_cache_test.go)、[VFS](../../go/storage_vfs_test.go) |
-
-实现验收按顺序检查：
-
-1. 明文／加密应用控制消息在 P2P 和群中均可发送；能力缺失时走普通通道，TTL 保留，普通消息继续交付。
-2. P2P 加密 SDK 控制降级后仍经 SDK 消费；群及明文 SDK 控制发送前拒绝；冲突元数据不被静默改写。
-3. 同批绑定与转移贯穿 UUIDv4 批次，原调用兼容；重复 ID 去重，失败结果逐项保留，身份变化后不继续以旧身份审批。
-4. 新 Client／重连复用有效本地记录；改变 ETag／正文／关系或显式 force 时查询；管理流程仍刷新，旧异步结果不覆盖新观察。
-5. VFS／LowLevel／Raw 批量 ACL、单元素列表和旧单值均有效；每 AID 独立计数，部分失败后相关缓存失效、无关缓存保留。
-6. 分别验收四端，再用跨 SDK runner 验证互通；保留实际版本、服务端版本、失败项和结果产物。
-
-[控制消息矩阵 runner](../../tests/cross-sdk/runner/run_control_matrix_e2e.py)定义 96 格：4 发送 SDK × 2 发送端能力状态 × 3 类别 × 2 加密状态 × P2P／群。合法格检查其它三个 SDK 接收，无效格预期发送前拒绝；首失败停止并保存断点。
-
-该矩阵使用 TTL=60、`aun.agent_md.changed` v1，接收端保持能力启用，未覆盖接收端单独缺能力或两端均缺能力的全部组合，也不替代 EventService `aun.pubsub` 验收。Go 观察点与能力开关受 `crosssdk` 构建标签控制，普通构建走 stub。
-
-本轮仅编写指南并做文档校验，没有重新执行 SDK 全量、跨 SDK E2E 或容量压测。既有版本校验和定向测试记录见 [parity 验证边界](../../python/CHANGES_FOR_PARITY.md#v0533)，不能将 runner 中的成功输出条件当作已取得的 96/96 通过产物。
+# AUN SDK 0.5.33 开发与移植指南
+
+面向 Python、Go、TypeScript、浏览器 JavaScript SDK 维护者及新语言移植者。以仓库 `072b7c69f`（0.5.32）对照截至 2026-11-07 的未提交变更，包含已暂存脚本和相关未跟踪的 Python 压测源码。应用接线见 [0.5.33 应用集成指南](0.5.33-SDK应用集成指南.md)，完整改动索引见 [parity 0.5.33](../../python/CHANGES_FOR_PARITY.md#v0533)。
+
+## 1. 范围与实现分层
+
+| 本轮工作 | SDK 负责 | 配套服务负责 |
+| --- | --- | --- |
+| 控制消息兼容 | 发送前核对能力、准备类别、解密后分派 | Gateway 可信会话；Message／Group 兼容选择投递通道 |
+| Ownership 批次 | 批次上下文、归组事件、逐项审批与结果汇总 | NS 继续处理原有单项关系与名片提交 |
+| 本地共识优先 | 恢复并核验本地快照，按需查询 | NS 返回当前权威事实，管理提交仍做原有校验 |
+| 批量／条件 ACL | VFS／LowLevel 参数贯通、失败时定向失效缓存 | Storage 保存规则、检查 Owner 单方声明，按需缓存名片并判权及计次 |
+| 弹性历史补拉 | 主辅生命周期、共享调度、持久/临时分流与消费背压 | Gateway 授权／回收及持久配置；Message／Group 有界分页 |
+| Python 专项 | 群 Pull 去重复闸门、退避区分、容量压测 CLI | 保持现有服务接口 |
+
+```mermaid
+%%{init: {"theme":"base","flowchart":{"curve":"linear","nodeSpacing":24,"rankSpacing":32}}}%%
+flowchart TB
+    A["宿主应用"]:::app
+    subgraph SDK["每个 AID 进程中的 SDK"]
+        direction TB
+        F["AUNClient 门面"]:::entry
+        O["Ownership<br/>批次 / 单项审批 / 共识"]:::logic
+        V["Storage VFS / LowLevel<br/>多 AID与条件 ACL"]:::logic
+        E["已有 EventService<br/>Pub / Bus / Sub"]:::inherited
+        L["本地身份仓库<br/>agent.md / 共识快照 / 读缓存"]:::local
+        P["RPC 准备与分类交付<br/>能力 / E2EE / 内部消费"]:::entry
+        F --> O & V & E
+        O & V --> L
+        O & V & E --> P
+    end
+    G["Gateway<br/>认证身份 / 设备 / RPC 转发"]:::infra
+    subgraph SERVICES["AUN 服务"]
+        direction LR
+        M["Message / Group<br/>消息通道与 TTL"]:::infra
+        N["NS<br/>名片与 Ownership 事实"]:::infra
+        S["Storage<br/>对象 / ACL / CAS"]:::infra
+        C["Credential<br/>登记 / 状态 / 撤销"]:::infra
+    end
+    A --> F
+    P --> G
+    G --> M & N & S & C
+    S -->|"条件授权查询"| N
+    classDef app fill:#eff6ff,stroke:#60a5fa,color:#1e3a8a,rx:10,ry:10
+    classDef entry fill:#eef2ff,stroke:#818cf8,color:#312e81,rx:10,ry:10
+    classDef logic fill:#ecfdf5,stroke:#6ee7b7,color:#065f46,rx:10,ry:10
+    classDef local fill:#fff7ed,stroke:#fdba74,color:#9a3412,rx:10,ry:10
+    classDef inherited fill:#f8fafc,stroke:#cbd5e1,color:#475569,rx:10,ry:10
+    classDef infra fill:#f8fafc,stroke:#94a3b8,color:#334155,rx:10,ry:10
+    style SDK fill:#ffffff,stroke:#e2e8f0,rx:12,ry:12
+    style SERVICES fill:#f8fafc,stroke:#e2e8f0,rx:12,ry:12
+```
+
+EventService、VFS 定向缓存、RPC `16/8/4/4` 预算及 Bus 单实例机制沿用 0.5.32；本版不重新定义事件目录或 fanout。Pub／Bus／Sub 使用 `client.EventService`（Go 为 `EventService()`），详细约束见 [0.5.32 移植指南](0.5.32-SDK开发与移植指南.md)与[事件服务移植指南](AUN事件发布订阅开发移植指南.md)。
+
+## 2. 控制消息：先准备语义，再决定传输类别
+
+### 2.1 共同契约与字段位置
+
+| 内容与场景 | 能力已协商 | 类别或 SDK 协议未协商 |
+| --- | --- | --- |
+| 普通消息，P2P／群，明文／加密 | 普通路径 | 普通路径；群普通 TTL 不因控制能力缺失而被阻断 |
+| 应用 `control`，P2P／群，明文／加密 | 保留类别 | 构造请求时移除外层类别和可改写保护头类别，走普通投递 |
+| P2P 加密 `sdk_control` | 保留类别、协议与版本 | 移除外层路由类别；E2EE 内部类别、协议与版本保留 |
+| 明文 `sdk_control`、群 `sdk_control` | 本地拒绝 | 本地拒绝 |
+
+| 位置 | 含义与检查 |
+| --- | --- |
+| RPC 参数 `message_class` | 请求投递类别；降级可省略，Go 不重新补为空字符串或 `normal` |
+| 明文 RPC 参数 `protected_headers` | 明文元数据所在层；服务端直接解析，并结合可信会话身份处理 |
+| E2EE 信封 `protected_headers` | 受认证的消息语义；P2P 通常在 `payload` 信封内，群 V2 在 `envelope` 内 |
+| 送达记录 `delivery_class` | 服务端实际选择的通道；普通通道不抹去信封中的 SDK 语义 |
+
+类别和协议冲突继续报参数错误。信封已加密签名时保持原样；降级调整路由，接收侧仍校验原受保护内容。普通加密信封未声明类别时按 `normal` 校验，不能将缺字段当作解密失败。
+
+### 2.2 发送与交付顺序
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant A as 应用或 SDK 内部模块
+    participant P as 发送准备
+    participant G as Gateway
+    participant M as Message / Group
+    participant R as 接收 SDK
+    participant D as 接收应用
+    A->>P: method / class / encrypt / payload / TTL
+    P->>P: 合并元数据，检查参数和当前协商结果
+    alt 明文或群 sdk_control
+        P-->>A: 本地拒绝，不进入传输
+    else 合法消息
+        alt 应用 control 未协商
+            P->>P: 移除可变类别，保留其它参数
+        else 加密 sdk_control 未协商
+            P->>P: 省略外层类别，保留 SDK 保护头
+        end
+        P->>G: 发送请求与明文正文或 E2EE 信封
+        G->>M: 转发可信身份与请求
+        M->>M: 选择通道，保留 TTL 与信封
+        M-->>R: 实际投递类别与消息
+        R->>R: 明文使用可信投递身份；加密核验信封
+        alt 已认证的 sdk_control
+            R->>R: 交给 SDK 协议处理器
+        else 应用 control 或 normal
+            R-->>D: 应用消息事件
+        end
+    end
+```
+
+以下是语义顺序，不是要求四端照搬同一函数：
+
+```text
+校验 class、场景、SDK 协议及版本
+若 sdk_control 为明文或群消息：拒绝
+若 control 未协商：移除可改写的类别字段
+若 sdk_control 未协商：仅省略传输类别
+明文直接发送；待加密正文按准备结果构造信封
+已签名信封保持不变，交配套服务选择通道
+接收按可信身份与受保护语义分派
+```
+
+Python 群分类 Pull 已由外层序列化，内部直接 fetch，避免同一请求重复进入同一闸门等待自身。移植时保留原有 Pull／ACK、水位与设备范围检查，只移除这一层重复等待。
+
+实现入口：[Python 准备与接收](../../python/src/aun_core/_client/control_messages.py)／[RPC](../../python/src/aun_core/_client/rpc_pipeline.py)、[TS RPC](../../ts/src/client/rpc-pipeline.ts)／[接收](../../ts/src/client/control-messages.ts)、[JS RPC](../../js/src/client/rpc-pipeline.ts)／[接收](../../js/src/client/control-messages.ts)、[Go 类别](../../go/control_messages.go)／[V2 路由](../../go/v2_routing.go)／[P2P](../../go/client_v2_e2ee.go)／[群](../../go/v2_group.go)。
+
+## 3. Ownership：批次归组，单项仍独立完成
+
+### 3.1 API 和固定上下文
+
+| 层 | Python | TS／JS | Go |
+| --- | --- | --- | --- |
+| 申请选项 | `batch_id` 关键字 | `OwnershipRequestOptions.batchId` | `OwnershipRequestOptions.BatchID` |
+| 绑定／转移 | `bind_owner_aid/bind_sub_aid/transfer_sub_aid` | `bindOwneraid/bindSubaid/transferSubaid` | `BindOwneraid/BindSubaid/TransferSubaid` |
+| 批量审批 | `accept_ownership_requests/reject_ownership_requests` | `acceptOwnershipRequests/rejectOwnershipRequests` | `AcceptOwnershipRequests/RejectOwnershipRequests` |
+| 传输字段 | 可选 UUIDv4 `batch_id` | 同左 | 同左 |
+
+原单项调用兼容。`batch_id` 贯穿任务上下文、Ownership 请求和应用事件；同一批次可涉及多个 AID，但每项保持自己的 `operation_id`。批次不是审批权限，也不替代已认证的原始请求。
+
+同一操作的发送者或原始上下文发生变化，包括增删／修改 `batch_id`，按冲突处理。应用将选择的操作 ID 列表交给审批接口；SDK 去重、逐项检查当前身份及代际，Go 还检查 context，返回 `total/succeeded/failed/results`。
+
+### 3.2 请求与审批链路
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant I as 多个申请 AID 的 SDK
+    participant M as AUN 消息投递
+    participant O as Owner SDK
+    participant A as Owner 应用
+    participant N as NS / 名片提交
+    loop 每个绑定或转移请求
+        I->>M: 独立 operation_id，共用 batch_id
+        M-->>O: 原始请求与认证发送方
+        O->>O: 核对固定上下文，保存请求
+        O-->>A: ownership.request，携带 batch_id
+    end
+    A->>A: 按批次展示，冻结本次选择的操作 ID
+    A->>O: accept / reject requests(operation_ids)
+    O->>O: 去重并固定执行身份
+    loop 每个 operation_id
+        O->>O: 检查原请求、当前身份及代际
+        O->>N: 沿用单项刷新、校验与提交流程
+        N-->>O: 单项当前结果
+        O->>O: 保存该项结果或错误，继续其它项
+    end
+    O-->>A: 汇总与逐项结果
+```
+
+批量返回中的成功数表示本次单项接口执行结果，后续关系是否已达共识仍以单项状态／既有工作流为准；`waiting` 不能被应用解释为全部关系已绑定完成。中途失败不会将整个批次回滚，身份变化后剩余项按错误记录。
+
+```text
+ids = 按首次出现顺序去重(operation_ids)
+identity = 当前 AID 与身份代际
+对每个 id：
+    核对 identity 与原始认证请求
+    执行原有单项 accept 或 reject
+    记录单项结果或错误
+返回汇总和 results
+```
+
+实现：[Python 消息校验](../../python/src/aun_core/ownership_v21.py)／[workflow](../../python/src/aun_core/ownership_workflow.py)／[门面](../../python/src/aun_core/client.py)、[TS workflow](../../ts/src/ownership-workflow.ts)／[门面](../../ts/src/client.ts)、[JS workflow](../../js/src/ownership-workflow.ts)／[门面](../../js/src/client.ts)、[Go workflow](../../go/ownership_workflow.go)。该批次扩展不新增服务器批量审批 RPC。
+
+## 4. 本地 agent.md 与共识：有效快照优先，管理仍刷新
+
+启动／连接后先读取本地名片。新的 Client 首次查询也可恢复已保存的 `ownership_snapshot`；恢复条件须同时成立：
+
+| 核对项 | 要求 |
+| --- | --- |
+| 共识和范围 | `status=consensus`、锁定、目标 AID 一致 |
+| 远端观察 | 快照 ETag 非空，与记录已观察远端 ETag 一致，记录不为 missing |
+| 本地正文 | 正文 SHA256 与快照摘要一致 |
+| 关系声明 | 名片中 owner、关系版本与快照一致 |
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant A as 连接 / 查询调用方
+    participant C as Client / AgentMdManager
+    participant L as 本地身份仓库
+    participant N as NS
+    A->>C: 连接后读取或首次共识查询
+    C->>L: 载入正文、观察记录与快照
+    L-->>C: 本地记录
+    alt 非 force，内存或持久快照有效
+        C-->>A: 复用本地结果
+    else 未达共识、记录变化或 force
+        C->>N: 原有权威读取
+        N-->>C: 当前关系与名片
+        C->>C: 核对关系、正文和观察代际
+        C->>L: 仅当前观察仍匹配时保存快照
+        C-->>A: 当前结果
+    end
+    Note over C,N: 绑定、审批、转移、释放等管理流程继续强制刷新
+```
+
+这里的 ETag 是 SDK 已观察到的状态；本地复用不会主动证明远端此刻没有变化。收到名片／Ownership 变化后清理相关快照，未达共识或显式强刷再查询，保持事件驱动，不新增周期首查任务。
+
+查询完成写回前要核对 Client、manager／存储根、缓存对象及观察版本，避免旧身份或旧请求覆盖新记录。群／组织首次访问同样复用有效本地共识；管理方法内部的强制刷新保持不变。
+
+实现：[Python manager](../../python/src/aun_core/agent_md.py)／[client](../../python/src/aun_core/client.py)、[TS manager](../../ts/src/agent-md.ts)／[client](../../ts/src/client.ts)、[JS manager](../../js/src/agent-md.ts)／[client](../../js/src/client.ts)、[Go client](../../go/client.go)。
+
+## 5. Storage ACL：从门面贯通到 RPC
+
+| 层 | AID 列表／单值 | 条件参数 |
+| --- | --- | --- |
+| Python VFS／LowLevel | `grantee_aids`／`grantee_aid` | `subject`，内层 `owner_aid` |
+| TS／JS VFS／LowLevel | `granteeAids`／`granteeAid` | `subject: StorageACLSubject`，内层 `ownerAid` |
+| Go VFS 选项 | `GranteeAIDs`／`GranteeAID` | `Subject: *ACLSubject`，内层 `OwnerAID` |
+| Go LowLevel | 保留原位置参数与可选列表 | `SetACLWithOptions/RemoveACLWithOptions` |
+| RPC `storage.set_acl/remove_acl` | `grantee_aids`／兼容 `grantee_aid` | `subject.ownership.owner_aid` |
+
+每次必须且只能选择 `subject`、`grantee_aid`、`grantee_aids` 一种，缺失、冲突或显式 null 由 Storage 返回 `-32602`。列表允许单元素；服务端归一化、去重 AID，owner／grantee 的数据库访问和缓存键统一大小写。具体 AID 的 `max_uses` 分别计数，条件规则则共享额度。SDK 透传授权意图，权威判权留在服务端。
+
+### 5.1 条件规则与四端参数
+
+Wire 结构为 `subject.ownership{owner_aid, scope?}` 和可选 `subject.card{type?, exttype?}`；`ownership` 必需，`scope` 默认 `direct`，另支持 `descendants`。名片数组提供时必须非空，去首尾空白、排序、去重后精确匹配。跨条件 AND，同一属性数组 OR。TS／JS 的 camelCase 只在 LowLevel 边界转成 wire snake_case。
+
+Python VFS 使用同一个字典授权和撤销：
+
+```python
+subject = {
+    "ownership": {"owner_aid": owner_aid, "scope": "direct"},
+    "card": {"type": ["agent"], "exttype": ["assistant", "worker"]},
+}
+await owner_client.storage.set_acl("/reports", subject=subject, perms="r")
+await owner_client.storage.remove_acl("/reports", subject=subject)
+```
+
+Go 使用公共结构体，原单 AID 调用继续可用：
+
+```go
+subject := &aun.ACLSubject{
+    Ownership: &aun.ACLOwnershipSubject{OwnerAID: ownerAid, Scope: "direct"},
+    Card: &aun.ACLCardSubject{Type: []string{"agent"}, Exttype: []string{"assistant", "worker"}},
+}
+_, err := ownerClient.Storage().SetACL(ctx, "/reports", aun.SetACLOptions{Subject: subject, Perms: "r"})
+_, err = ownerClient.Storage().RemoveACL(ctx, "/reports", aun.RemoveACLOptions{Subject: subject})
+```
+
+TS／浏览器 JS 的完整 VFS 读写示例见[应用指南 §6.2](0.5.33-SDK应用集成指南.md#62-允许符合条件的-sub-读取目录)。授权和列表返回的条件规则显示 `subject`，不显示内部主体键；列表请求的包装结果仍为 `{owner_aid, bucket, path, acls}`。
+
+### 5.2 服务端保存与权威判权
+
+Storage 保存归一化条件；同一路径加相同条件更新同一规则，撤销也按相同条件定位。内部使用摘要主体键复用已有 ACL 的持久化和原子计数，不能把该键作为应用参数或公开 `grantee_aid`。归属判权只检查 Owner 端 `default/sub_aids/{sub_aid}/owner.md` 的单方 `declare` 声明；Owner 自身不算 sub，`descendants` 沿各级 Owner 声明展开，最多 64 层、4096 个节点并检查循环。
+
+每次判权确认当前声明路径快照，再按正文摘要复用解析结果；声明修改或删除后不命中旧版本。正文复用 Storage 已有缓存，Owner 专属写删保护构成声明的可信边界。未配置 `card` 时不查询名片；配置时只取普通名片的 `type/exttype`，不触发 NS Ownership 共识检查。
+
+名片 TTL 为 60 秒，有效且匹配时直接使用；未命中／过期回源，不匹配允许提前刷新，相邻刷新至少间隔 5 秒。相同 AID 的并发查询合并，不同 AID 按请求触发的 2 ms 窗口合批，每批最多 64 个；缓存与在途队列有界，无周期同步任务。服务回源失败不能沿用已过期名片放行。
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant V as sub VFS / LowLevel
+    participant S as Storage
+    participant N as 可信 Name Service
+    participant R as ACL / 对象仓库
+    V->>S: 读取 Owner 的 /reports/...
+    S->>R: 查询该路径适用的条件 ACL
+    S->>R: 当前 Owner 声明路径快照与摘要
+    loop descendants 需要继续展开时
+        S->>R: 下一级 Owner 的有效声明
+    end
+    opt 配置 card，且缓存缺失／过期／不匹配刷新
+        S->>N: svc nameservice.agent_md_batch，AID 去重合批
+        N-->>S: 每项 status / type / exttype / etag
+    end
+    S->>S: 匹配 Owner 声明 AND 可选名片条件
+    S->>R: 读取正文并按规则原子计次
+    S-->>V: 正文或下载票据；read_cache.reusable=false
+    opt 下载票据兑换正文
+        V->>S: 兑换该票据
+        S->>R: 确认原规则仍存在、有效且可读
+        S->>R: 复核当前 Owner 声明
+        S->>S: 按同一 TTL 策略检查可选名片条件
+        S-->>V: 通过后直出或流式代理正文，private/no-store
+    end
+```
+
+`nameservice.agent_md_batch` 参数为 `{aids: [...]}`，返回 `{items: [{aid, status, type?, exttype?, etag?}]}`，状态为 `ok/not_found/invalid`；本域单次 SQL 批查普通名片。远域通过 Gateway svc 联邦转发，Owner 声明列表使用内部 `storage.owner_declared_subjects({owner_aid})`。两种 RPC 都限制真实 Storage 服务身份，Gateway 覆盖调用者身份并限制目标域，不向 SDK 增加公共入口。
+
+条件规则的 `r` 可授权普通私有对象读取；原具体 AID `r` 的普通私有下载限制保留。条件访问返回 `read_cache.reusable=false/max_age_ms=0`，含目录等元数据读取；下载兑换再次检查规则、当前声明及按上述策略取得的名片，不能仅凭签发时的匹配放行。撤销声明及时影响后续联网判权；名片从匹配改为不匹配最多保留 60 秒 TTL 窗口。声明无效、名片缺失／无效或所需回源失败均不授予条件权限。
+
+### 5.3 ACL 变更与缓存失效
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant A as 应用
+    participant V as VFS / LowLevel
+    participant C as SDK 读缓存包装层
+    participant S as Storage，经 Gateway
+    A->>V: set / remove ACL，多 AID
+    V->>C: path + grantee_aids，兼容旧单值
+    C->>S: storage.set_acl / remove_acl
+    S->>S: 归一化、去重，逐项写入
+    alt 全部完成
+        S-->>C: 成功结果
+        C->>C: 定向失效受影响路径
+        C-->>A: 原结果
+    else 中途失败，可能已有部分写入
+        S-->>C: 原 RPC 错误
+        C->>C: 同样定向失效受影响路径
+        C-->>A: 继续抛出原错误
+    end
+    Note over C,S: 保留无关路径缓存；不承诺整个批次事务回滚
+```
+
+缓存失效需覆盖 Raw 调用、LowLevel 与 VFS。Go 的 mock／自定义 client LowLevel 路径也在错误返回前失效；Python 异常路径含取消后仍可能已有写入的情况。复用原有资源范围与在途回填保护，避免清空整个 Storage 缓存。
+
+```text
+尝试执行 ACL RPC
+成功：按既有规则失效相关路径并返回
+异常：对 set_acl / remove_acl 失效同一资源范围
+重新抛出原异常
+保留无关资源缓存
+```
+
+入口：[Python VFS](../../python/src/aun_core/storage/vfs.py)／[LowLevel](../../python/src/aun_core/storage/lowlevel.py)／[cache](../../python/src/aun_core/storage/cache.py)、[TS VFS](../../ts/src/storage/vfs.ts)／[LowLevel](../../ts/src/storage/lowlevel.ts)／[cache](../../ts/src/storage/read-cache.ts)、[JS VFS](../../js/src/storage/vfs.ts)／[LowLevel](../../js/src/storage/lowlevel.ts)／[cache](../../js/src/storage/read-cache.ts)、[Go VFS](../../go/storage_vfs.go)／[LowLevel](../../go/storage_lowlevel.go)／[Call](../../go/client.go)。
+
+对象上传、下载票据及共享链接的冗余返回字段精简属于配套服务响应契约变化，元数据保存方式保持原有设计。字段以 [Storage RPC 手册](09-storage-rpc-manual.md)为准；移植者不要重新依赖已移除的空值或重复 URL 字段。
+
+## 6. Python 独有实现与工具
+
+| 改动 | 当前行为 | 移植边界 |
+| --- | --- | --- |
+| 退避提示 | 有效正数 `retry_after_seconds/retry_after_ms` 优先，多个取较长值 | 本轮其它 SDK 没有相同退避调整 |
+| 缺少提示的拥塞 | `-32029/-32429` 且消息含 queue、backpressure、capacity 等拥塞标记，默认 1 秒 | 其它限流默认 60 秒；不因此自动重试应用写请求 |
+| 群分类 Pull | 外层已串行时内部直接 fetch | 保留 cursor／ACK 检查及原调度预算 |
+| 容量压测 | `aun bench run/report`，16 场景、多进程／身份通道、预算与续跑、JSON／HTML | Python CLI 能力，不是要求四端新增网络协议 |
+
+退避入口为 [transport](../../python/src/aun_core/transport.py)。容量工具由 [bench](../../python/src/aun_cli/commands/bench.py)注册 [bench_capacity](../../python/src/aun_cli/commands/bench_capacity.py)，实现拆分为[场景](../../python/src/aun_cli/benchmark/scenarios.py)、[执行与报告](../../python/src/aun_cli/benchmark/runner.py)、[节奏统计](../../python/src/aun_cli/benchmark/runtime.py)、[搜索](../../python/src/aun_cli/benchmark/search.py)。多进程入口与结果协议由工具自行处理，不影响 SDK Client 的单进程 API。
+
+报告区分有效完成量、延迟达标容量、稳态吞吐与发压端瓶颈；`pubsub` 场景包含发压端 Bus，不能解释为纯服务端容量。生成器不足、搜索未界定或持续验证未通过时，保留相应边界，不标记为已确认容量。
+
+## 7. 四端回归与移植验收
+
+| 范围 | Python | TS／JS | Go |
+| --- | --- | --- | --- |
+| 发送／接收类别 | [components](../../python/tests/unit/test_client_components.py) | 各端 `tests/unit/rpc-pipeline.test.ts`、`client.test.ts` | [client](../../go/client_test.go)、[V2 parity](../../go/v2_python_parity_test.go) |
+| 批次与审批 | [workflow](../../python/tests/unit/test_ownership_workflow.py) | 各端 `tests/unit/ownership-workflow.test.ts` | [workflow](../../go/ownership_workflow_test.go) |
+| 本地共识／管理强刷 | [agent.md](../../python/tests/unit/test_client_agent_md_api.py) | 各端 `tests/unit/client-agent-md-api.test.ts` | [agent.md](../../go/client_agent_md_api_test.go) |
+| ACL 与错误缓存 | [cache](../../python/tests/unit/test_storage_read_cache.py)、VFS 测试 | TS `storage-read-cache.test.ts`；JS `storage-vfs-read-cache.test.ts`；各端 VFS 测试 | [cache](../../go/storage_read_cache_test.go)、[VFS](../../go/storage_vfs_test.go) |
+
+实现验收按顺序检查：
+
+1. 明文／加密应用控制消息在 P2P 和群中均可发送；能力缺失时走普通通道，TTL 保留，普通消息继续交付。
+2. P2P 加密 SDK 控制降级后仍经 SDK 消费；群及明文 SDK 控制发送前拒绝；冲突元数据不被静默改写。
+3. 同批绑定与转移贯穿 UUIDv4 批次，原调用兼容；重复 ID 去重，失败结果逐项保留，身份变化后不继续以旧身份审批。
+4. 新 Client／重连复用有效本地记录；改变 ETag／正文／关系或显式 force 时查询；管理流程仍刷新，旧异步结果不覆盖新观察。
+5. VFS／LowLevel／Raw 批量 ACL、单元素列表和旧单值均有效；每 AID 独立计数，部分失败后相关缓存失效、无关缓存保留。
+6. 四端条件字段一致；缺失／冲突目标拒绝；直接／后代、名片 AND／OR、规则共享限次、等价条件更新／撤销均正确；身份变化及撤销后不复用旧缓存或下载票据。
+7. 分别验收四端，再用跨 SDK runner 验证互通；保留实际版本、服务端版本、失败项和结果产物。
+
+[控制消息矩阵 runner](../../tests/cross-sdk/runner/run_control_matrix_e2e.py)定义 96 格：4 发送 SDK × 2 发送端能力状态 × 3 类别 × 2 加密状态 × P2P／群。合法格检查其它三个 SDK 接收，无效格预期发送前拒绝；首失败停止并保存断点。
+
+该矩阵使用 TTL=60、`aun.agent_md.changed` v1，接收端保持能力启用，未覆盖接收端单独缺能力或两端均缺能力的全部组合，也不替代 EventService `aun.pubsub` 验收。Go 观察点与能力开关受 `crosssdk` 构建标签控制，普通构建走 stub。
+
+本轮仅编写指南并做文档校验，没有重新执行 SDK 全量、跨 SDK E2E 或容量压测。既有版本校验和定向测试记录见 [parity 验证边界](../../python/CHANGES_FOR_PARITY.md#v0533)，不能将 runner 中的成功输出条件当作已取得的 96/96 通过产物。
+
+### 7.1 条件 ACL 的 Ubuntu Docker E2E 矩阵
+
+使用当前工作区源码构建 Ubuntu Docker 服务和四端测试进程。每次创建独立 Owner O、直接 sub S1/S2、S1 的 sub N、其它 Owner Q 与其 sub X，以及无声明 U；用真实注册、签名名片和 Owner 发布的 `owner.md` 建立夹具，并单独覆盖仅有 Owner 单方声明的场景。名片变更通过 SDK 签名上传，测试不通过写库代替声明或判权。
+
+| 编号 | 场景 | 关键断言 |
+| --- | --- | --- |
+| A01 | 授权目标三选一 | 缺失、同时提供、显式 null 拒绝；三种合法单独目标均可使用 |
+| A02 | 原单 AID／列表兼容 | 单元素及多元素列表授权、查询和撤销正确；各 AID 限次独立 |
+| A03 | 条件规则生命周期 | 属性排序／去重、Owner 大小写、默认 direct 得到同一规则；更新和撤销准确 |
+| A04 | 授权管理身份 | 只有资源 Owner 或已有受信管理入口可管理规则，普通 sub 不能扩大权限 |
+| S01 | 直接下级 | O 的 direct 允许 S1/S2，拒绝 N、X、U；O 本人仍按资源所有者权限访问 |
+| S02 | 递归后代 | descendants 允许 N；逐级 Owner 声明均有效，无需双向共识 |
+| S03 | 名片条件 AND／OR | type 和 exttype 同时满足；每个属性数组内 OR；不匹配的类型或扩展类型拒绝 |
+| S04 | 省略属性和无效条件 | 可省略 card 或单个属性；空数组、空字符串、非法 scope 和未知条件字段拒绝 |
+| P01 | 路径与目录边界 | reports 本身及多级子路径可读，reports-other 不受该规则授权；list/stat/lstat 一致 |
+| P02 | 读写删权限 | r 允许读并拒绝写删；显式 w/x 只授予相应操作，修改后的内容及存在性可复核 |
+| D01 | 新 sub 自动适用 | 保存规则后 Owner 再发布新 sub 声明，直接读取成功 |
+| D02 | 名片 TTL 与提前刷新 | 匹配名片在 60 秒内复用；过期取得不匹配属性后拒绝；恢复匹配后按至少 5 秒刷新间隔重新允许 |
+| D03 | 当前声明 | 原 Owner 更新／删除 S1 的声明后，联网读取拒绝 S1 及依赖该边的 N |
+| D04 | 撤销和过期 | 先成功读取再撤销或到期，下一次联网读取和既有票据均拒绝 |
+| D05 | 共享次数 | S1/S2 交替消耗同一 max_uses，达到额度后均拒绝；HEAD／纯元数据不扣次 |
+| H01 | 大对象完整读取 | 超过 inline 上限，VFS ticket→HTTP 返回相同长度和 SHA-256 的正文 |
+| H02 | 票据使用时复核 | 签发后撤销规则／声明，兑换失败；名片变更按相同 TTL 策略检查 |
+| H03 | HTTP HEAD／Range | HEAD 无正文，Range 正文正确；每次核对授权并返回 private/no-store |
+| H04 | 下游下载边界 | 条件下载不返回可绕过复核的下游签名 URL，不向对象存储转发 AID Bearer |
+| C01 | 两层缓存边界 | SDK 条件响应 reusable=false、max_age_ms=0；Storage 只复用有效名片，声明与规则变化由联网判权检查 |
+| M01 | 四端分别验收 | Python → Node TS → Go → 浏览器 JS 串行执行，各端走 VFS 和 LowLevel 的真实映射 |
+| M02 | 四端交叉互通 | 授权端×读取端的 16 个有序组合均验证授权／读取／撤销，含同端四项与异端十二项 |
+
+64 跳上限、防环、损坏元数据和 NS 故障等边界同时保留服务端定向测试；未实际构造并运行的真实场景不得计作 E2E 通过。浏览器 JS 必须在真实浏览器中运行，不能用 Node 执行 JS 包代替其浏览器验收。
+
+运行前核对域、Compose project、数据挂载、镜像／二进制源码摘要及四端依赖来源，服务端变更后重新构建并重启对应测试服务。按表中顺序首失败即停，保存 run_id、固定 AID/slot、已通过编号、失败堆栈及 HTTP/RPC 证据，修复后从失败项续跑。测试日志与结果记录实际执行项，缺环境、跳过或未运行分别标注；环境操作见[测试运行指南](../aun测试运行指南.md)。
+
+## 8. 弹性补拉的四端共同实现契约
+
+本节按[实施计划第 9 节](../消息弹性补拉通道实施计划.md#9-实施契约冻结与进度)及[方案第 17 节](../消息弹性补拉通道方案.md#17-辅助连接断线后的主通道回退)描述共同契约。应用操作见[应用指南第 9 节](0.5.33-SDK应用集成指南.md#9-长期离线后的弹性补拉)；本节不代替各端及真实环境的验收记录。
+
+### 8.1 分层及用途认证
+
+```mermaid
+flowchart LR
+    A["应用处理器"] --> D["主 Client<br/>解密 / 游标 / 应用分发"]
+    D --> Q["统一补拉协调器<br/>按流串行 / 共享预算 / 主会话代际"]
+    D --> T["主 Transport<br/>实时 / 控制 / 普通 RPC / volatile Pull"]
+    Q --> T
+    Q --> X["策略授权的 0..N 辅助 Transport<br/>仅 history_sync"]
+    C["控制面配置中心<br/>持久修订 / 作用域绑定"] --> G["Gateway<br/>认证 / 动态策略 / 通知回收"]
+    T & X --> G
+    G --> M["Message / Group<br/>存储范围 / 字节分页 / 原游标"]
+    M --> D
+```
+
+| 部件 | 实现要求 |
+| --- | --- |
+| 主 Client | 唯一身份、访问凭证来源、device/slot、解密、游标及应用分发状态 |
+| 辅助 Transport | 遵从 `max_aux_channels` 策略使用 0..N 条，复用主 Client 当前访问凭证；独立断线/事件生命周期；共享 RPC 预算，不启动完整 Client、token 刷新或自动重连 |
+| 协调器 | 主会话及流级任务、真实通道数、全通道共享预算、消费预留与故障回退 |
+| Gateway | 加载有效持久配置，校验主会话同 AID/device/slot 及双能力；本轮按开关与实时压力实际授权 0/1，本 Gateway 内 `(aid, device_id)` 跨 slot、主会话合计最多 1 条，历史准入仍按 AID 汇总；这是当前 Gateway cap，不是 SDK 协议上限 |
+| Message / Group | 处理普通 Pull 数据面，保留设备隔离、可见性和 TTL，按预算截页 |
+
+主辅都声明并协商 `elastic_connections_v1=true`、`sync_channels_v1=true`。辅助 `auth.connect` 使用 `options={kind:"short",purpose:"history_sync",parent_connection_id}`；其它用途单独定义方法白名单，普通短连接沿原用途工作。
+
+`sync_channels_enabled` 默认开启，已有显式 `false` 保持关闭，通过 Console 既有修订／绑定持久化；Gateway 加载并动态应用配置，将有效开关、配置版本和控制面修订提供给实例诊断。连接数只在承接主连接的 Gateway 内统计，同一 `(aid, device_id)` 跨 slot、主会话合计最多 1 条，不同设备分别计数，当前不跨 Gateway 全局汇总。SDK 按策略支持 0..N，当前协议实现及已有测试覆盖到 2；面板区分保存成功与 `applied/pending/unknown`，仅切换开关不重启 Gateway，不增加 SDK 配置轮询。
+
+### 8.2 策略先于响应、准入先于发送
+
+请求外层 `_meta.sync={purpose:"history_sync",parent_connection_id,has_pending:true}` 与业务 `params` 分离，主连接历史回退同样携带。响应外层 `_meta.sync_policy` 含主连接 ID、正安全整数 `version`，以及：
+
+| 字段 | 边界 |
+| --- | --- |
+| `max_aux_channels` | SDK 按策略支持 `0..N`（当前协议实现及测试覆盖到 2）；本轮 Gateway 实际下发 `0/1`、开启时最多 1；同一 Gateway 内 `(aid, device_id)` 跨 slot、主会话合计最多 1 条 |
+| `max_history_pull_inflight` | `0..3`，主辅合计 |
+| `max_page_bytes` | `1024..786432`，初始 256 KiB |
+| `max_history_inflight_bytes` | 编码页总预留，初始 1 MiB |
+| `history_bytes_per_second` | 历史编码结果速率，`0` 暂停 |
+
+`version` 最大 `9007199254740991`，同主会话单调。Transport 在 resolve/reject/dispatch 前同步应用有效策略；错误 parent、无效数值和旧版本忽略，缺字段不解除已有约束。异步建连、签名、排队及等待写入期间可能降额，因此最终发送临界点必须再复核主会话、策略和共享额度。添加业务分页参数后重新计算客户端签名。
+
+```text
+等待历史授权与消费容量（未占普通 RPC 额度）
+预留编码页、本地放大内存，并选择当前合法通道
+重签分页参数；发送前原子复核最新策略
+接收完整页；检查主会话代际，释放网络额度
+解密并完成应用消费；提交合法游标/ACK，释放页面预留
+```
+
+策略更新不使同主会话合法旧页失效；主会话换代必须取消旧任务，旧结果不向新会话提交或 ACK。历史在途额度或速率为 `0` 时等 `event/gateway.sync_policy_changed` 唤醒；`max_aux_channels=0` 仍可使用受限主连接。
+
+### 8.3 设备隔离、内存与实时路径
+
+| 契约 | 要求 |
+| --- | --- |
+| `storage_scope=all` | 缺省，保持旧请求行为 |
+| `storage_scope=persistent` | 历史专用，不读取 volatile mailbox |
+| `storage_scope=volatile` | 独立主连接实时 Pull；只处理临时页与 volatile cursor，不提交持久 coverage/head/server ACK，不接受 `ack_up_to_seq` |
+| `max_page_bytes` | 按单次 RPC `result` 的 JSON 编码字节计量，信封和 Gateway 元数据另留有界开销 |
+| 编码与本地预算 | 编码预留初始共 1 MiB，本地以页上限 ×8 预留、初始共 8 MiB，覆盖预取、解密与应用消费 |
+| RPC 预算 | 所有 Transport 共用总 16、background 8、event 4、pull 4；历史最多 3，进程池每 AID 最多 2 条、总计最多 8 条辅助连接；辅助连接数遵从策略，不把总 Pull 并发限制为 1 |
+| 顺序与 ACK | 同一 namespace 的网络 Pull 串行，不同 namespace 可在策略授权和共享预算允许时并行复用辅助连接；每流保留原 seq/cursor，半页和旧主会话页不 ACK |
+
+`volatile` Pull、控制消息及正常 RPC 保留主通道；实时临时页不等待暂停的持久历史任务。原设备/slot 过滤及 TTL 沿用服务端规则，已过期临时消息不进入历史恢复。
+
+首条记录仍超过预算时，读取 `error.data.code="OVERSIZED_MESSAGE"`。后台统一发布 `sync.error={namespace,method,code,error}` 并停止该流自动续页，其他流继续；显式前台调用返回原错误。不能只匹配人类错误文本，也不能通过推进游标或提高授权预算绕过超页。
+
+诊断 `history.reserved_bytes` 表示编码预留，`history.local_reserved_bytes` 表示本地放大预留；8 倍系数不等同于精确 RSS。`history.aux_completed_pages` 只计算真实辅助连接成功返回的页面，不把主连接页计入。
+
+### 8.4 回收、断线和按需恢复
+
+Gateway 经主连接发送 `event/gateway.sync_channel_close`，包含主连接、目标辅助连接、原因及排空期限，优先回收已确认无需求的空闲连接。SDK 退役目标通道，及时释放未完成页预留，保留待补任务与安全游标。`gateway.sync_demand` 是需求变化 Notification，不设周期需求心跳；只保留按任务需要的一次性限速、空闲归还和排空计时器。
+
+辅助断线不使主 Client 下线，也不自动重连。当前策略版本内记住故障，使用剩余 deadline 和最新额度退回主连接；同批任务与后续任务都不得通过冷却补开辅助连接。只有新的 Gateway 策略明确重新授予辅助资格或新的主会话协商后，才可按需再申请。重复同版本快照不解除故障；主连接历史额度为 `0` 时继续等待通知。
+
+| 端 | 主要实现入口 |
+| --- | --- |
+| Python | `python/src/aun_core/_client/sync_channels.py`、`transport.py`、`_client/delivery.py` |
+| Node TS | `ts/src/client/sync-channels.ts`、`transport.ts`、`client/v2-e2ee.ts`、`client/delivery.ts` |
+| Browser JS | `js/src/client/sync-channels.ts`、`transport.ts`、`client/v2-e2ee.ts`、`client/delivery.ts` |
+| Go | `go/sync_channels.go`、`transport.go`、`v2_routing.go`、`events.go` |
+
+四端使用同一 `tests/contracts/sync_channels_v1_vectors.json`。逐端及跨端验收须覆盖实际辅助登录、策略 0..N（当前协议实现及测试覆盖到 2）、同 namespace 串行及不同 namespace 并行、发送前降额、回收断线退主、同版禁开、volatile 独立交付、慢消费者预算、超大页停流和旧代际无 ACK；Ubuntu Docker 的实际结果及剩余范围以实施计划中的运行证据为准。本轮 Gateway 当前 cap 更改待重新验收；历史测试不证明该 cap 已通过。