@agentunion/fastaun-browser 0.5.17 → 0.5.19

package/_packed_docs/aun/345/210/206/345/270/203/345/274/217/346/265/213/350/257/225/350/277/220/350/241/214/346/214/207/345/215/227.md

@@ -1,6 +1,8 @@
 # AUN 分布式测试运行指南
 
-本文档负责三套本地 Docker 环境：三节点单域、本地真实域名双域 `agentid.pub/agentid.cn`、隔离双域 federation `dist-aid.com/dist-aid.net`。默认 `agentid.pub` 单域、默认四语言 Tester 和默认 cross-SDK 统一见 [AUN 测试运行指南](aun测试运行指南.md)。公网 `agentid.pub/agentid.cn` 复测是本地跨域通过后的独立验证层，不属于本地双域 Docker。
+本文档负责三套本地 Docker 环境：三节点单域、本地真实域名双域 `agentid.pub/agentid.cn`、隔离双域 federation `dist-aid.com/dist-aid.net`。默认 `agentid.pub` 单域、默认四语言 Tester 和默认 cross-SDK 统一见 [AUN 测试运行指南](aun测试运行指南.md)。公网 `agentid.pub/agentid.cn` 复测是本地跨域通过后的独立验证层，不属于本地双域 Docker。
+
+本轮跨域验收范围仅为本机 Docker 中的 `agentid.pub` ↔ `agentid.cn`。测试请求必须经本地 `kite-agentid-federation-net` 在两个本地 Kite 容器之间完成；本轮禁止运行公网测试入口、访问线上 `agentid.pub` / `agentid.cn` 服务或把公网结果计入结论。`dist-aid.com` / `dist-aid.net` 章节仅保留为独立环境参考，本轮不得启动或运行该隔离 federation，也不得将其结果计入本轮跨域结论。
 
 本指南只认当前 worktree `D:\modelunion\kite`。当前分支已经包含完整的默认单实例、三节点分布式、两套双域环境、服务端源码和四语言 SDK；服务端镜像、Tester、Cross-SDK、`data-dist` 与部署包都必须从这个 worktree 生成和运行。
 
@@ -21,7 +23,7 @@ D:\modelunion\kite\aun-sdk-core\docs\aun公网测试运行指南.md
 - 当前 worktree：`D:\modelunion\kite`
 - 三节点单域集群：`D:\modelunion\kite\docker-deploy\docker-compose.distributed.yml`
 - 本地真实域名双域：两域基础 Compose + 域覆盖 + `D:\modelunion\kite\docker-deploy\docker-compose.agentid-federation.yml`，当前不加载 Mail overlay
-- 隔离双域 federation：`D:\modelunion\kite\docker-deploy\federation-test\docker-compose.yml`
+- 隔离双域 federation（本轮不执行）：`D:\modelunion\kite\docker-deploy\federation-test\docker-compose.yml`
 - 分布式 Tester：`D:\modelunion\kite\docker-deploy\docker-compose.distributed-testers.yml`
 - 分布式 Cross-SDK：`D:\modelunion\kite\aun-sdk-core\tests\cross-sdk\docker-compose.cross-sdk.distributed.yml`
 - 本地 TLS 证书：只用于本地测试，SDK 侧统一 `AUN_ENV=development`、`AUN_VERIFY_SSL=0`
@@ -43,7 +45,7 @@ D:\modelunion\kite\aun-sdk-core\docs\aun公网测试运行指南.md
 
 ## 本地真实域名双域与公网环境边界
 
-`agentid.pub` 与 `agentid.cn` 在本机各运行一套“分布式控制模型的单节点形态”，共同组成当前真实域名双域 Docker 跨域环境。两域复用同一无 Mail 服务镜像，但各自拥有独立 Issuer CA、10 个服务 AID、MySQL、Redis、workspace、Compose project 和宿主端口；只共享 `kite-agentid-federation-net` 上的 Kite 业务节点。默认双域不创建 PostgreSQL、不加载 Mail；服务镜像固定使用 `python:3.11-bookworm`，最终镜像不包含 `uvloop`，Compose 默认 `AUN_GATEWAY_USE_UVLOOP=0`。
+`agentid.pub` 与 `agentid.cn` 在本机各运行一套“分布式控制模型的单节点形态”，共同组成当前真实域名双域 Docker 跨域环境。两域复用同一无 Mail 服务镜像，但各自拥有独立 Issuer CA、12 个服务 AID、MySQL、Redis、workspace、Compose project 和宿主端口；只共享 `kite-agentid-federation-net` 上的 Kite 业务节点。默认双域不创建 PostgreSQL、不加载 Mail；服务镜像固定使用 `python:3.11-bookworm`，最终镜像不包含 `uvloop`，Compose 默认 `AUN_GATEWAY_USE_UVLOOP=0`。
 
 - `D:\modelunion\kite\docker-deploy\agentid.pub`：引用固定 `data`，project 为 `kite-single`，应用容器为 `kite-app`。
 - `D:\modelunion\kite\docker-deploy\agentid.cn`：引用固定 `data-agentid-cn`，project 为 `kite-agentid-cn-local`，应用容器为 `kite-agentid-cn-local-app`。
@@ -77,7 +79,7 @@ D:\modelunion\kite\aun-sdk-core\docs\aun公网测试运行指南.md
 - 目标 `data-dist` 必须不存在或为空。整套冷克隆至少包含 `mysql`、`postgres`、`CA`、`certs`、`AIDs`、`control`、`aun-node-a`、`aun-node-b`、`storage-shared`、`sdk-tester-aun` 和 `sdk-testers`；不得只复制 CA、证书、AID、MySQL 或节点目录中的一部分。
 - `.env.distributed` 不得被 example 覆盖。保留当前文件前要逐项比对 Issuer、MySQL/PostgreSQL 凭据、控制令牌、镜像、project/container/network 前缀、子网和端口；当前 worktree 必须保持 `kite-main-dist-*`、`172.31.89.0/24` 与新端口，不能沿用来源 worktree 的 Docker 命名空间。
 - 克隆完成后，来源与目标成为两套独立资产。后续不得共享目录、交叉挂载或同时用同一容器名接管；每次启动都执行“运行时来源强制核验”。
-- 启动业务服务前，先只读核对根 CA/Registry CA 哈希、十个内置服务证书的 SHA-256，以及证书在克隆后 MySQL `aun_cert.agentid_cert` 中的 `lifecycle_state=active_signing`、`cert_state=1` 记录。任一不一致即停止，不得补登记、重签、清库或局部重复制。
+- 启动业务服务前，先只读核对根 CA/Registry CA 哈希、十二个内置服务证书的 SHA-256，以及证书在克隆后 MySQL `aun_cert.agentid_cert` 中的 `lifecycle_state=active_signing`、`cert_state=1` 记录。任一不一致即停止，不得补登记、重签、清库或局部重复制。
 
 整套冷克隆会继承来源环境的历史业务数据，适合当前分支接管并继续回归。只有明确需要全新隔离身份和空业务库时，才在用户授权后运行 `prepare_dist_materials.py` 并完成新证书注册验收；“新建空目录 + 复制旧证书”不是合法初始化方式。
 
@@ -501,7 +503,7 @@ docker compose --env-file ../docker-deploy/.env.distributed -f tests/cross-sdk/d
 
 ### 定位与验收边界
 
-这是当前真实域名的**本地双域 Docker 跨域测试环境**。两域都是分布式控制模型的单节点部署，已迁移服务默认使用 Go：Auth、CA、Gateway、Message、Group、Storage、Stream、NameService、Leaderboard、Service Proxy；AID Custody 仍使用 Python。两域必须使用同一个无 Mail 的 `docker-deploy-kite:latest` 镜像，避免把镜像差异误判为跨域问题。
+这是当前真实域名的**本机 Docker 双域跨域测试环境**。两域都是分布式控制模型的单节点部署，已迁移服务默认使用 Go：Auth、CA、Gateway、Message、Group、Storage、Stream、NameService、Leaderboard、Service Proxy；AID Custody 仍使用 Python。两域必须使用同一个无 Mail 的 `docker-deploy-kite:latest` 镜像，避免把镜像差异误判为跨域问题。本阶段的 SDK runner 只加入本地 `kite-agentid-federation-net`，不使用公网 DNS、线上服务器或公网测试 runner。
 
 本环境验证的是本地完整调用链：
 
@@ -517,7 +519,7 @@ docker compose --env-file ../docker-deploy/.env.distributed -f tests/cross-sdk/d
 
 ### 每轮执行顺序
 
-每轮开始和结束都重新阅读 [AUN 测试运行指南](aun测试运行指南.md)，确认身份保护、镜像重建和测试串行规则没有变化。固定顺序为：只读材料校验 -> 必要时构建镜像 -> 启动两域 -> 来源与 Go runtime 核验 -> 双向发现 -> 联邦身份边界 -> Notify -> Stream -> P2P -> Group -> Group FS -> Collab -> Storage OSS -> 采集两域日志。当前明确跳过 Mail 和 reconnect，因此不得加载 `docker-compose.mail.yml`。任一前置门禁失败即停止，不得用重签证书、`setup_aids.py`、清库或删除 SDK 身份绕过。
+每轮开始和结束都重新阅读 [AUN 测试运行指南](aun测试运行指南.md)，确认身份保护、镜像重建和测试串行规则没有变化。固定顺序为：只读材料校验 -> 必要时构建镜像 -> 启动两域 -> 来源与 Go runtime 核验 -> 双向发现 -> 联邦身份边界 -> Notify -> Stream -> P2P -> Read State -> Group -> Group FS -> Collab -> Storage OSS -> 采集两域日志。当前明确跳过 Mail 和 reconnect，因此不得加载 `docker-compose.mail.yml`。任一前置门禁失败即停止，不得用重签证书、`setup_aids.py`、清库或删除 SDK 身份绕过。
 
 ### 材料校验与镜像构建
 
@@ -529,7 +531,7 @@ docker image inspect docker-deploy-kite:latest mysql:8.0 redis:7-alpine | Out-Nu
 if ($LASTEXITCODE -ne 0) { throw '双域基础镜像未准备完成，停止测试' }
 ```
 
-`domain_materials.py validate` 会只读核对域名、Issuer CA 指纹、10 个服务 AID、TLS 与 MySQL `server-uuid`。任一不匹配都表示材料混域，不得自动修复。
+`domain_materials.py validate` 会只读核对域名、Issuer CA 指纹、12 个服务 AID、TLS 与 MySQL `server-uuid`。任一不匹配都表示材料混域，不得自动修复。
 
 只有服务端源码、Go 依赖、manifest 或 Dockerfile 变化时，才在依赖准备阶段构建；业务测试阶段不得临时联网补依赖：
 
@@ -663,10 +665,10 @@ agentid.cn:  D:\modelunion\kite\docker-deploy\data-agentid-cn\sdk-testers\python
 
 ```powershell
 cd D:\modelunion\kite\docker-deploy
-$phases = @(
-  'federation-boundary', 'notify', 'stream', 'p2p',
-  'group', 'group-fs', 'collab', 'storage'
-)
+$phases = @(
+  'federation-boundary', 'notify', 'stream', 'p2p', 'read-state',
+  'group', 'group-fs', 'collab', 'storage'
+)
 foreach ($phase in $phases) {
   $testSince = (Get-Date).ToUniversalTime().ToString('o')
   $stamp = (Get-Date).ToUniversalTime().ToString('yyyyMMddHHmmss')
@@ -721,9 +723,9 @@ $tsCases = @(
   'federation-service-proxy.test.ts'
 )
 foreach ($case in $tsCases) {
-  docker exec -e AUN_TEST_ISSUER_A=agentid.pub -e AUN_TEST_ISSUER_B=agentid.cn `
-    -e AUN_VERIFY_SSL=0 -w /workspace/ts kite-ts-tester bash -lc `
-    "node_modules/.bin/vitest run tests/integration/$case --no-file-parallelism --maxWorkers=1 --reporter=verbose"
+  docker exec -e AUN_TEST_ISSUER_A=agentid.pub -e AUN_TEST_ISSUER_B=agentid.cn `
+    -e AUN_VERIFY_SSL=0 -w /workspace/ts kite-ts-tester bash -lc `
+    "node --max-opt=0 node_modules/vitest/vitest.mjs run tests/integration/$case --pool forks --no-file-parallelism --maxWorkers=1 --reporter=verbose"
   if ($LASTEXITCODE -ne 0) { throw "TS federation 失败: $case" }
 }
 ```
@@ -733,22 +735,24 @@ foreach ($case in $tsCases) {
 浏览器 JS federation 必须使用 Playwright，按文件串行执行。先构建一次，再分别运行 `federation.spec.ts` 与 `notify.spec.ts`；`AUN_TEST_DISABLE_LOCAL_DOCKER_PIN=1` 使浏览器使用共享 Docker DNS，不把域名 pin 到宿主机回环地址：
 
 ```powershell
-docker exec -e AUN_TEST_ISSUER_A=agentid.pub -e AUN_TEST_ISSUER_B=agentid.cn `
-  -e AUN_TEST_DISABLE_LOCAL_DOCKER_PIN=1 -e AUN_VERIFY_SSL=0 `
-  -w /workspace/js kite-js-tester bash -lc "npm run build"
+docker exec -e AUN_TEST_ISSUER_A=agentid.pub -e AUN_TEST_ISSUER_B=agentid.cn `
+  -e AUN_TEST_DISABLE_LOCAL_DOCKER_PIN=1 -e AUN_VERIFY_SSL=0 `
+  -w /workspace/js kite-js-tester bash -lc "npm run build"
 if ($LASTEXITCODE -ne 0) { throw 'JS federation 构建失败' }
 
 $jsCases = @('federation.spec.ts', 'notify.spec.ts')
 foreach ($case in $jsCases) {
-  docker exec -e AUN_TEST_ISSUER_A=agentid.pub -e AUN_TEST_ISSUER_B=agentid.cn `
-    -e AUN_TEST_DISABLE_LOCAL_DOCKER_PIN=1 -e AUN_VERIFY_SSL=0 `
-    -w /workspace/js kite-js-tester bash -lc `
-    "node_modules/.bin/playwright test --config=playwright.agentid-local.config.ts tests/e2e-browser/$case --reporter=line"
+  docker exec -e AUN_TEST_ISSUER_A=agentid.pub -e AUN_TEST_ISSUER_B=agentid.cn `
+    -e AUN_TEST_DISABLE_LOCAL_DOCKER_PIN=1 -e AUN_VERIFY_SSL=0 `
+    -w /workspace/js kite-js-tester bash -lc `
+    "node --max-opt=0 node_modules/@playwright/test/cli.js test --config=playwright.agentid-local.config.ts tests/e2e-browser/$case --reporter=line"
   if ($LASTEXITCODE -ne 0) { throw "JS Playwright federation 失败: $case" }
-}
-```
-
-失败后不得重复已通过文件；如果只需重跑 Notify，可将 `$jsCases` 改为 `@('notify.spec.ts')`。隔离 federation 运行时将两处 `agentid.pub/agentid.cn` 同时替换为 `dist-aid.com/dist-aid.net`。
+}
+```
+
+若 Docker Tester 中 Playwright 以 `139`/`SIGSEGV` 退出，保留该文件日志并切换到主指南的宿主机 Node 备选命令，仍使用同一套 `agentid.pub ↔ agentid.cn` Docker 服务端；宿主机模式不要设置 `AUN_TEST_DISABLE_LOCAL_DOCKER_PIN`，由 `playwright.agentid-local.config.ts` 将两域宿主端口映射给浏览器。已通过文件无需重复运行。
+
+失败后不得重复已通过文件；如果只需重跑 Notify，可将 `$jsCases` 改为 `@('notify.spec.ts')`。隔离 federation 运行时将两处 `agentid.pub/agentid.cn` 同时替换为 `dist-aid.com/dist-aid.net`。
 
 除 `federation-boundary` 外，runner 在进入业务阶段前会用全新的运行目录分别完成两域固定身份登录。`auth.aid_login1` 必须依次通过 CA 的 `verify_chain`、`get_cert` 和 `ocsp_query` 数据库查询，因此登录成功就是 CA/Auth 数据库调用链可用的证据；日志必须先出现两条 `DOMAIN_READY ... evidence=aid_login`。`ca.status` 属于域内诊断 RPC，普通 AID 被 Gateway 拒绝是正确权限边界，不得为了预检放宽。任一域登录失败时，runner 会汇总两域结果并在业务 RPC 前停止；此时应先检查对应 MySQL 容器状态和 CA/Auth 重连日志，不能把 `ca.verify_chain: database not connected` 归因于联邦身份边界。
 
@@ -765,8 +769,9 @@ foreach ($case in $jsCases) {
 | `federation-boundary` | `FEDERATION_MUTUAL_AUTH_OK`，以及 unauth/signature/issuer/RPC/event/Group-FS marker 的全部 `DENIED` |
 | `notify` | `NOTIFY_CROSS_DOMAIN_OK` |
 | `stream` | `STREAM_CREATED_EVENT_OK`、`STREAM_TARGET_BINDING_OK`、`STREAM_CLOSED_EVENT_OK` |
-| `p2p` | `P2P_ONLINE_OK`、`P2P_ACK_OK`、`P2P_OFFLINE_RECONNECT_SKIPPED` |
-| `group` | `GROUP_AUTHORITY_MEMBER_OK`、`GROUP_REMOTE_PULL_OK`、`GROUP_DIRECTORY_OK`、`GROUP_DIRECTORY_RECONNECT_SKIPPED`、`GROUP_MESSAGE_ONLINE_PULL_OK`、`GROUP_LEAVE_OK`、`GROUP_AID_CERT_OK` |
+| `p2p` | `P2P_ONLINE_OK`、`P2P_ACK_OK`、`P2P_OFFLINE_RECONNECT_SKIPPED` |
+| `read-state` | `READ_STATE_P2P_OK`、`READ_STATE_GROUP_OK`、`READ_STATE_CROSS_DEVICE_OK` |
+| `group` | `GROUP_AUTHORITY_MEMBER_OK`、`GROUP_REMOTE_PULL_OK`、`GROUP_DIRECTORY_OK`、`GROUP_DIRECTORY_RECONNECT_SKIPPED`、`GROUP_MESSAGE_ONLINE_PULL_OK`、`GROUP_LEAVE_OK`、`GROUP_AID_CERT_OK` |
 | `group-fs` | `GROUP_FS_OWNER_AREA_OK`、`GROUP_FS_NON_MEMBER_DENIED`、`GROUP_FS_MEMBERDATA_DIRECT_OK`、`GROUP_FS_OTHER_MEMBERDATA_DENIED`、`GROUP_FS_STORAGE_BYPASS_DENIED`、`GROUP_FS_MEMBERDATA_OK`、`GROUP_FS_REMOTE_COPY_OK`、`GROUP_FS_ACL_PRE_GRANT_DENIED`、`GROUP_FS_ACL_GRANTED`、`GROUP_FS_ACL_REVOKED_DENIED`、`GROUP_FS_ADMIN_DEFAULT_WRITE_OK`、`GROUP_FS_SHORT_AID_DENIED`、`GROUP_FS_AFTER_LEAVE_DENIED` |
 | `collab` | `COLLAB_CROSS_DOMAIN_READ_OK`、`COLLAB_NON_MEMBER_DENIED`、`COLLAB_STORAGE_BYPASS_DENIED` |
 | `storage` | `STORAGE_LIST_OK`、`STORAGE_RECONNECT_SKIPPED`、`STORAGE_PRIVATE_DENIED_OK`、`STORAGE_TOKEN_OK`、`STORAGE_CROSS_OWNER_ROUTING_OK`、`STORAGE_CLEANUP_OK` |
@@ -784,9 +789,35 @@ Notify 必须双向验证公开 SDK `notify()` 经过 Gateway 联邦事件转发
 3. 当前 `--skip-reconnect` 范围明确不执行离线重连回补，必须输出 `P2P_OFFLINE_RECONNECT_SKIPPED`；恢复 reconnect 验收时，才要求接收端离线发送、再上线 pull 并 ACK。
 4. receiver AID 的 issuer 必须决定远端 Gateway；本域 Message 不得把异域 receiver 当成本地收件人查询后返回 not found。
 
-成功标准是发送响应、远端接收、pull/ack 和两域日志中的同一 trace/message ID 全部闭合。仅有 `message.send` 返回成功不算通过；远端超时必须返回明确的 federation unavailable/timeout，不能伪装成接收方不存在。
-
-### Group 跨域验收
+成功标准是发送响应、远端接收、pull/ack 和两域日志中的同一 trace/message ID 全部闭合。仅有 `message.send` 返回成功不算通过；远端超时必须返回明确的 federation unavailable/timeout，不能伪装成接收方不存在。
+
+### 跨设备已读未读验收
+
+本阶段只使用本地真实域 `agentid.pub` 与 `agentid.cn` 的固定身份，验证 Message P2P、Group 消息和同一 AID 多设备的已读状态同步。不得使用 `federation-test` 的 `dist-aid.com` / `dist-aid.net` 身份或 `cross_domain_read_state.py` 作为本轮跨域验收证据；隔离 federation 仅在本指南末尾的独立参考章节中运行。
+
+在完成 `p2p` 阶段后执行：
+
+```powershell
+$runId = "agentid-read-state-" + (Get-Date).ToUniversalTime().ToString('yyyyMMddHHmmss')
+docker run --rm --network kite-agentid-federation-net `
+  -v "D:\modelunion\kite\aun-sdk-core\python\src:/sdk/src:ro" `
+  -v "D:\modelunion\kite\docker-deploy\tests\agentid_cross_domain_e2e.py:/tests/agentid_cross_domain_e2e.py:ro" `
+  -v "D:\modelunion\kite\docker-deploy\data\extended-acceptance\group-management:/identities/pub:ro" `
+  -v "D:\modelunion\kite\docker-deploy\data-agentid-cn\sdk-testers\python-fixed:/identities/cn:ro" `
+  -e PYTHONPATH=/sdk/src `
+  -e AUN_E2E_PUB_IDENTITY_ROOT=/identities/pub `
+  -e AUN_E2E_CN_IDENTITY_ROOT=/identities/cn `
+  -e AUN_E2E_CN_ENCRYPTION_SEED=cross-domain-e2e-v1 `
+  -e AUN_E2E_RUN_ROOT=/tmp/aun-e2e `
+  -e AUN_SDK_UVLOOP=0 -e AUN_CLI_UVLOOP=0 -e AUN_BENCH_UVLOOP=0 `
+  -e HTTP_PROXY= -e HTTPS_PROXY= -e ALL_PROXY= -e NO_PROXY=* `
+  aun-sdk-tester:latest python /tests/agentid_cross_domain_e2e.py `
+    --phase read-state --skip-reconnect --run-id $runId
+```
+
+该阶段必须输出 `READ_STATE_P2P_OK`、`READ_STATE_GROUP_OK`、`READ_STATE_CROSS_DEVICE_OK` 和 `PASS phase=read-state`。P2P 与 Group 的状态上报、重复上报幂等、查询结果及跨域消息 ID 必须在同一轮中闭合；跨设备部分必须使用同一 AID 的两个不同 `device_id`，并验证在线 `message.read_changed` 事件及查询补偿。失败后只从 `read-state` 阶段继续，不重复已通过的 `federation-boundary`、Notify、Stream 和 P2P 阶段。
+
+### Group 跨域验收
 
 先由 `.agentid.pub` 成员创建群并加入 `.agentid.cn` 成员，再反向创建一次。每个方向都必须验证：
 
@@ -961,7 +992,9 @@ foreach ($phase in 'p2p', 'group', 'storage') {
 
 公网日志应从两台服务器按本轮开始时间分别采集。若仍保存到 `docker-deploy/agentid.pub/latest.log` 和 `docker-deploy/agentid.cn/latest.log`，必须同时记录日志来源是“本地 Docker”还是“公网服务器”；文件名相同不能证明环境。没有远端日志访问权限时，只能给出客户端 E2E 结论，不能声称已完成服务端调用链闭环。
 
-## 隔离双域 federation（dist-aid.com / dist-aid.net）
+## 隔离双域 federation（dist-aid.com / dist-aid.net；本轮不执行）
+
+本节仅供单独获准的隔离环境回归参考，不属于本轮 `agentid.pub` ↔ `agentid.cn` 跨域验收；本轮不得按本节启动容器或执行测试。
 
 ### 准备并启动
 

package/_packed_docs/aun/346/265/213/350/257/225/350/277/220/350/241/214/346/214/207/345/215/227.md

@@ -4,7 +4,9 @@
 > `D:\modelunion\kite\docker-deploy`，SDK 源码与测试位于
 > `D:\modelunion\kite\aun-sdk-core`。
 
-本文档说明默认 `agentid.pub` 单实例服务端、四语言 Tester、默认 cross-SDK、集成测试和 E2E 的运行方式，同时给出单实例生产包的构建与部署入口。三节点、本地 `agentid.pub/agentid.cn` 跨域 Docker 和隔离 `dist-aid.*` federation 统一见分布式指南。
+本文档说明默认 `agentid.pub` 单实例服务端、四语言 Tester、默认 cross-SDK、集成测试和 E2E 的运行方式，同时给出单实例生产包的构建与部署入口。三节点和本地 `agentid.pub/agentid.cn` 跨域 Docker 统一见分布式指南。
+
+本轮跨域验收范围仅为本地 `agentid.pub` ↔ `agentid.cn`。`dist-aid.com` / `dist-aid.net` 隔离 federation 不属于本轮跨域测试或验收结论。
 
 ## 测试指南:
 D:\modelunion\kite\aun-sdk-core\docs\aun测试运行指南.md
@@ -53,7 +55,7 @@ Tester 和 cross-SDK 都不是服务端环境：
 
 ### 默认单实例测试前强制核验
 
-每次开始本地单实例测试前，先选择域并执行以下只读检查。材料清单固定了 Issuer CA 指纹、10 个服务 AID 和 MySQL `server-uuid`；Compose 解析结果必须把 MySQL 和应用四个数据挂载全部指向同一域：
+每次开始本地单实例测试前，先选择域并执行以下只读检查。材料清单固定了 Issuer CA 指纹、12 个服务 AID 和 MySQL `server-uuid`；Compose 解析结果必须把 MySQL 和应用四个数据挂载全部指向同一域：
 
 ```powershell
 $domain = 'agentid.pub' # 校验本地跨域对端时改为 agentid.cn
@@ -181,7 +183,7 @@ JS 的真实 E2E 统一使用 `js/tests/e2e-browser`，不要把浏览器 E2E
 
 ## 一次性准备
 
-首次准备时构建服务镜像和 Python Tester 镜像。服务镜像会同时构建 10 个默认 Go 服务 binary：
+首次准备时构建服务镜像和 Python Tester 镜像。服务镜像会同时构建 12 个默认 Go 服务 binary：
 
 ```powershell
 cd D:\modelunion\kite\docker-deploy
@@ -339,7 +341,7 @@ docker compose --env-file agentid.cn/local.env --project-directory . `
   -f docker-compose.yml -f agentid.cn/docker-compose.yml config --quiet
 ```
 
-解析后的服务端数据源必须全部位于 `data-agentid-cn`。Issuer CA 指纹、10 个服务 AID 和 MySQL `server-uuid` 由 `agentid.cn/materials.json` 锁定；不得从 `data` 复制 `agentid.pub` 的 Issuer、服务身份或数据库来补缺。
+解析后的服务端数据源必须全部位于 `data-agentid-cn`。Issuer CA 指纹、12 个服务 AID 和 MySQL `server-uuid` 由 `agentid.cn/materials.json` 锁定；不得从 `data` 复制 `agentid.pub` 的 Issuer、服务身份或数据库来补缺。
 
 `agentid.cn` Tester 使用独立 project、容器名、网络和可写目录，不与 `agentid.pub` 共享 SDK 身份。单域测试可按该域 `local.env` 启动；真实双域测试不能只启动这个 Tester，完整拓扑、固定身份规则与验收顺序见分布式指南：
 
@@ -1046,7 +1048,7 @@ Go 当前还没有默认单实例 Docker reconnect 用例；默认单实例侧
 
 ## 分布式与双域环境
 
-三节点 `dist-agentid.pub`、本地真实域名双域 `agentid.pub/agentid.cn`、隔离 federation `dist-aid.com/dist-aid.net`、分布式 Tester 和分布式 cross-SDK 的唯一运行说明见 [AUN 分布式测试运行指南](aun分布式测试运行指南.md)。
+三节点 `dist-agentid.pub`、本地真实域名双域 `agentid.pub/agentid.cn`、分布式 Tester 和分布式 cross-SDK 的唯一运行说明见 [AUN 分布式测试运行指南](aun分布式测试运行指南.md)。本轮跨域只执行其中的 `agentid.pub/agentid.cn` 专节。
 
 主指南不再复制 federation 命令。不得继续使用旧的 `aid.com/aid.net`、`client-a/client-b`、`federation-kite-*` 或 `federation-test_federation-net`；当前权威名称均以分布式 Compose 的 `dist-*` 配置为准。
 
@@ -1147,7 +1149,7 @@ docker compose --env-file NUL -f docker-compose.build.yml build kite
 
 ### 首次安装与日常替换
 
-目标 Linux 主机先准备域专属材料（至少 CA、TLS、10 个服务 AID 和既有 MySQL 数据）。Compose 已内置可直接运行的默认值：数据根为当前目录的 `./data`，MySQL root 密码为 `root`，控制令牌为 `aun-local-control-token`，服务面令牌为 `aun-local-service-plane-token`；Issuer 固定为 `agentid.pub`。因此不创建 `.env`、不执行任何 `export`，`down` 和 `up` 也都能正常解析。
+目标 Linux 主机先准备域专属材料（至少 CA、TLS、12 个服务 AID 和既有 MySQL 数据）。Compose 已内置可直接运行的默认值：数据根为当前目录的 `./data`，MySQL root 密码为 `root`，控制令牌为 `aun-local-control-token`，服务面令牌为 `aun-local-service-plane-token`；Issuer 固定为 `agentid.pub`。因此不创建 `.env`、不执行任何 `export`，`down` 和 `up` 也都能正常解析。
 
 首次部署时，把 `bootstrap-materials.tar.gz` 解到三文件目录得到 `init.sql` 并长期保留，同时把 CA、TLS、AID 和既有运行数据放到 `./data/CA`、`./data/certs`、`./data/AIDs`、`./data/mysql`、`./data/redis` 与 `./data/kite-workspace`。然后执行：
 

package/_packed_docs/protocol/01-/350/272/253/344/273/275/344/270/216/345/207/255/350/257/201/345/215/217/350/256/256-auth.md

@@ -269,48 +269,48 @@ signature = ECDSA_sign(private_key, SHA256(message))
 {
   "jsonrpc": "2.0",
   "id": 4,
-  "result": {
-    "success": true,
-    "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
-    "refresh_token": "new_refresh_token...",
-    "expires_in": 3600,
-    "aid": "alice.agentid.pub",
-    "refresh_count": 12,
-    "relogin_required": false,
-    "retryable": false,
-    "diagnostic": {
-      "aid": "alice.agentid.pub",
-      "refresh_count": 12
-    }
-  }
-}
-```
+  "result": {
+    "success": true,
+    "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
+    "refresh_token": "new_refresh_token...",
+    "expires_in": 3600,
+    "aid": "alice.agentid.pub",
+    "refresh_count": 12,
+    "relogin_required": false,
+    "retryable": false,
+    "diagnostic": {
+      "aid": "alice.agentid.pub",
+      "refresh_count": 12
+    }
+  }
+}
+```
 
 **说明**：
 - 调用时提交当前持有的 `refresh_token`
-- 服务端验证后吊销旧 `refresh_token`，签发新的 `access_token` 和 `refresh_token`
-- 旧 access_token 在其过期时间前仍然有效（JWT 标准行为），但客户端应立即切换到新 token
-- 建议在 access_token 过期前 60 秒刷新
-- 响应包含结构化状态字段：`relogin_required=true` 表示客户端必须放弃本地 token 并重新登录；`retryable=true` 表示可退避重试；`diagnostic` 只包含脱敏诊断字段
-
-**失败响应示例**：
-
-```json
-{
-  "success": false,
-  "error": "invalid_or_expired_refresh_token",
-  "relogin_required": true,
-  "retryable": false,
-  "diagnostic": {
-    "refresh_token_hash_prefix": "sha256:abcd..."
-  }
-}
-```
-
-**刷新限制**：
-- 刷新链总时长不超过 30 天，或最多刷新 720 次
-- 达到限制后返回 `relogin_required=true`，客户端必须重新执行完整的两阶段认证
-- 具体限制值由服务端实现决定
+- 服务端验证后吊销旧 `refresh_token`，签发新的 `access_token` 和 `refresh_token`
+- 旧 access_token 在其过期时间前仍然有效（JWT 标准行为），但客户端应立即切换到新 token
+- 建议在 access_token 过期前 60 秒刷新
+- 响应包含结构化状态字段：`relogin_required=true` 表示客户端必须放弃本地 token 并重新登录；`retryable=true` 表示可退避重试；`diagnostic` 只包含脱敏诊断字段
+
+**失败响应示例**：
+
+```json
+{
+  "success": false,
+  "error": "invalid_or_expired_refresh_token",
+  "relogin_required": true,
+  "retryable": false,
+  "diagnostic": {
+    "refresh_token_hash_prefix": "sha256:abcd..."
+  }
+}
+```
+
+**刷新限制**：
+- 刷新链总时长不超过 30 天，或最多刷新 720 次
+- 达到限制后返回 `relogin_required=true`，客户端必须重新执行完整的两阶段认证
+- 具体限制值由服务端实现决定
 
 ## 1.6 证书生命周期方法
 

package/_packed_docs/protocol/07-/351/224/231/350/257/257/347/240/201/344/270/216/347/212/266/346/200/201/346/234/272.md

@@ -102,7 +102,7 @@
 
 | 错误码 | 说明 | 客户端处理 |
 |--------|------|-----------|
-| -33001 | Group not found | 检查规范化后的 `group_aid`（`group_id` 为兼容参数名） |
+| -33001 | Group not found | 检查规范化后的 `group_aid`（`group_id` 为兼容参数名） |
 | -33002 | Group state invalid（群状态不允许该操作） | 检查群状态 |
 | -33003 | Group suspended | 等待恢复或联系管理员 |
 | -33004 | Group member limit reached | 不重试 |

package/_packed_docs/protocol/10-Group-/345/255/220/345/215/217/350/256/256.md

@@ -2,7 +2,7 @@
 
 > **适用版本**：AUN 1.0 | **状态**：Draft
 
-Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。Group 服务本身是一个 AID 持有者，客户端通过标准 `message.*` 协议与 Group 服务通信，Group 服务通过 JSON-RPC 2.0 暴露 `group.*` 命名空间方法。
+Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。Group 服务本身是一个 AID 持有者，客户端通过标准 `message.*` 协议与 Group 服务通信，Group 服务通过 JSON-RPC 2.0 暴露 `group.*` 命名空间方法。服务 AID、群身份 `group_aid` 与群主 `owner_aid` 是三个不同角色。群主关系由 Group 生命周期管理，不走 Ownership 2.1 的双文件绑定、释放、转移、审批或 NS 关系账本。
 
 ---
 
@@ -33,7 +33,7 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 | `owner_aid` | string | 群主 AID |
 | `creator_aid` | string | 创建者 AID |
 | `visibility` | string | `"public"` / `"private"` |
-| `status` | string | `"active"` / `"suspended"` / `"closed"` |
+| `status` | string | `"active"` / `"suspended"` / `"dissolved"` |
 | `description` | string | 群组描述 |
 | `metadata` | object | 自定义元数据 |
 | `mention_mode` | string | 群提及过滤模式：`"disabled"`（默认）/ `"mention-only"`，详见 [10.2.3 群提及过滤模式](#1023-群提及过滤模式mention_mode) |
@@ -91,7 +91,7 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 | `group_id` | string | 群组 ID |
 | `role` | string | `"owner"` / `"admin"` / `"member"` |
 | `joined_at` | integer | 加入时间（Unix 秒） |
-| `last_ack_seq` | integer | 最后已读消息序号 |
+| `last_ack_seq` | integer | 投递消费确认位置，与业务已读位置独立 |
 
 ### Member Status 对象
 
@@ -146,6 +146,8 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 
 ### `group.create`
 
+创建自动建立调用者与群的 owner 关系；群身份公私钥及证书由该 owner 持有，Group 服务不接收或保存群私钥。群名片须含当前 `owner`，不含通用 `ownership` 声明；由当前 owner 使用本人证书和私钥代签、代上传，文件 `aid` 仍是 `group_aid`。签名块 `signer_aid`、V2 上传授权、实体证书代际和条件恢复见 [Ownership 协议定义 2.1 §2.5](Ownership协议定义2.1.md#25-grouporg-名片的-owner-代签与上传)。创建、群证书绑定和名片发布的参数/响应以 [Group RPC Manual](../sdk/09-group-rpc-manual.md#groupcreate) 为准。
+
 创建群组。
 
 SDK 高层建群流程必须支持崩溃恢复：命名群复用已持久化密钥并重放相同 `group_name + public_key` 的已提交结果；匿名群复用已持久化的创建上下文，使响应丢失后的重试返回同一数字群，再继续群身份绑定和 `agent.md` 上传。服务端必须原子提交群记录、群主成员、成员索引、入群设置、首个 `group.changed` 事件及匿名创建映射。直接调用 RPC 且没有 SDK 恢复上下文时，每次调用仍表示一次新的自动群创建。
@@ -244,7 +246,7 @@ SDK 高层建群流程必须支持崩溃恢复：命名群复用已持久化密
 
 ### `group.dissolve`
 
-永久解散群组。需要 **owner** 权限。解散后不可恢复。
+永久解散群组。需要 **owner** 权限。解散后不可恢复，自动解除有效 owner 关系，终止待处理转移并撤销群证书及相关授权；旧 owner、旧证书、实体 token 和旧 pending 均不能继续上传群名片或代表群鉴权。历史 owner 和签名记录保留用于审计，不作为当前授权。解散墓碑及待转移清理先原子提交；事件发布、CA 撤销、Storage 权限失效与缓存清理通过持久 outbox 收尾，未全完成返回 -32002、status=unavailable/retryable=true/committed=true，重试续跑收尾，不能提前宣告成功。
 
 **参数**：`group_id` (string, 必填)
 
@@ -313,11 +315,19 @@ SDK 高层建群流程必须支持崩溃恢复：命名群复用已持久化密
 
 ### `group.transfer_owner`
 
-转让群主身份。需要 **owner** 权限。受让方无需手动确认，SDK 自动完成确认和转让收尾。
+发起两阶段群主转让。需要 **owner** 权限，只建立 `pending_rekey`，暂不切换 owner；新 owner 通过 `group.complete_transfer` 提交本人接受证明和新群公钥，完成强制 rekey 后切换 owner，原 owner 降为 admin。旧群证书失效，新身份材料归新 owner；新 owner 按当前代际重新代签、代上传含新 `owner` 的群名片。
 
 **参数**：`group_id` (必填), `new_owner` (必填，新群主 AID；别名 `aid` 向后兼容)
 
-**响应**：`{ "group": { ... }, "new_owner_aid": "bob.agentid.pub" }`
+**响应**：`{ "status": "pending_rekey", "requires_ca_rekey": true, "complete_rpc": "group.complete_transfer", "group": { ... }, "new_owner": "bob.agentid.pub" }`。完整参数、旧群身份授权、新 owner 接受证明及幂等规则见 [Group RPC Manual](../sdk/09-group-rpc-manual.md#grouptransfer_owner)。
+
+### `group.complete_transfer`
+
+仅待转移的新 owner 可完成，必须生成新群密钥并提交 `transfer_accept`，禁止同密钥续证代替 rekey。成功状态为 `transferred`；重复提交同一已完成转移可返回原结果。名片发布失败不反向撤销已提交的 owner 切换，SDK 保留新代际原字节和原 CAS 条件恢复上传。服务持久原已验证证书及 transfer nonce/旧 serial CAS，已提交 CA 的可恢复待办超 TTL 仍收敛，未提交 CA 的过期待办拒绝，旧请求不得提交新的转移。
+
+### `group.bind_group_aid` / `group.renew_group_aid`
+
+`bind_group_aid` 为匿名群补齐专属群身份，不是 Ownership 绑定；仅当前 owner 可操作，匹配公钥可幂等重放，不同公钥拒绝。`renew_group_aid` 是当前 owner 主动换钥，必须持有旧群私钥并提交换钥证明；它不替代两阶段 owner 转移。成功后 owner 持有新材料，并用本人身份重新代签、代上传群名片。
 
 ### `group.get_members`
 
@@ -504,7 +514,7 @@ History 不推进消息或事件 ACK，不修改 cursor/floor/Pull activity，
 
 ### `group.ack`
 
-提交已读游标（per-AID，非 per-device）。
+提交投递消费游标。SDK 的多设备/slot 游标按当前实例隔离；业务已读独立使用 `group.read/read_state`，不能以 ACK 表示用户已经阅读话题。
 
 **参数**：`group_id` (必填), `seq` (integer, 必填)
 
@@ -512,7 +522,15 @@ History 不推进消息或事件 ACK，不修改 cursor/floor/Pull activity，
 
 ---
 
-## 10.7 入群方式
+### `group.read` / `group.read_state`
+
+`group.read` 以 `states` 上报当前认证 AID/device 的群话题最后已读消息，每项包含 `group_id`、原样保存的 `topic_key`、`last_read_message_id`；缺省 scope 为 `group`。只有省略 `states` 时兼容顶层单条，显式空数组/null 拒绝；四个已读门面保留显式空值供服务端校验。历史 Group ID 别名解析为 canonical ID，新写状态键、响应和事件使用 canonical ID，历史别名参与事实/公共位置/设备映射的事务查询，权限复用既有版本同步。回执是设备写入结果，不是共享汇总。同域先校验全部项；混合域按所属域逐域校验和提交，任何域失败则 RPC 返回错误，已提交域不回滚，原样幂等重试可收敛。
+
+`group.read_state` 按当前 AID 的 `group_id`、`topic_key` 可选条件查询共享汇总；未指定群时发现本域及远域有权限的成员群。响应 `states` 包含公共 `last_read_order`、当前设备 `current_device_seq` 和 `mapping_status`（resolved/not_received/unresolved）；无映射 seq 为 null。晚到公共位置对仍匹配该消息且 order=0 的事实条件持久回填，不能只更新缓存或覆盖并发前进的事实。网络整数保持 int64 语义，Gateway 本域服务及 federation 回程不得经浮点中转，TS/JS API 超安全整数使用精确十进制字符串。
+
+共享位置已提交并前进后发布 `event/group.read_changed`，SDK 订阅名为 `group.read_changed`，owner 必须非空且为当前身份，scope 必须匹配原事件；Gateway 校验 Kernel 转发的可信 Group 来源，即使显式 route 也只向该 owner AID 分发，支持所属域向该外域成员 AID 转发，不能广播给其他成员。事件 ID 对身份、话题及公共位置组成的 JSON 元组取 SHA-256，失败日志不泄露 topic。事件包含 owner AID、scope、group、topic、消息 ID、公共顺序和更新时间，不进入 Pull 队列。SDK 重连保留原查询过滤范围，通过仅本地发布的 `read_state_sync` 交付本轮状态及逐项错误；身份切换按代际隔离旧缓存及补偿完成事件，A→B→A 也不能接收旧代际结果；原在途 RPC 仍可返回。完整契约见 `aun-sdk-core/docs/跨设备已读未读详细设计.md`。
+
+## 10.7 入群方式
 
 ### `group.request_join`
 
@@ -776,7 +794,8 @@ Group 服务通过 `event/group.*` 事件推送变更通知给相关 AID。
 | `member_left` | 成员退出 |
 | `member_removed` | 成员被踢出 |
 | `role_changed` | 角色变更 |
-| `owner_transferred` | 群主转让 |
+| `owner_transfer_rekey_pending` | 群主转让已发起，等待新 owner 完成强制换钥与确认 |
+| `owner_transferred` | 强制 rekey 后群主转让完成 |
 | `rules_updated` | 规则更新 |
 | `announcement_updated` | 公告更新 |
 | `join_requested` | 收到入群申请 |

package/_packed_docs/protocol/11-Storage-/345/255/220/345/215/217/350/256/256.md

@@ -31,6 +31,14 @@ Storage 服务是 AUN 协议的应用层扩展，提供对象存储能力。负
 
 ## 11.3 控制面方法
 
+**权威对象与路径修订**：`storage.head_object`、`storage.get_object` 和 `storage.fs.stat` 可传 `consistency: authoritative`，绕过正向、负向缓存并确认恢复可用性。结果包含 `consistency`、`exists`、不透明 `revision`、`owner_aid`、`bucket`、无前导斜杠的 `path` 和 Unix 秒 `observed_at`；存在时附 `sha256`、`object_id`、`version`，get 另返回完整严格 Base64 `content`。故障、权限错误和恢复未完成必须失败，不能返回 `exists=false`；下载或网关 404 不能证明权威不存在。
+
+`revision` 属于逻辑路径，每次成功写入、删除后变化，删除后保留；从未创建的修订为字符串 `0`，同内容重建也不得复用旧修订。写入与删除的 `expected_revision` 必须使用调用者先前权威读取的原值，与对象 `expected_version`、ETag 和内容摘要不同。条件冲突返回既有 `-32009`，不得刷新条件强行继续旧任务。
+
+`put_object`、`create_upload_session`、`complete_upload`、`delete_object` 和 `storage.fs.remove` 支持 `expected_revision`。条件上传 session 固定目标和原修订，响应带 `session_id`、`expected_revision`，complete 按同一 session 在最终发布时再次 CAS；内容与路径修订在 Storage 本地事务中原子发布，失败保留旧完整文件。普通不带修订的调用保持原语义，Ownership 文件发布和协议清理须满足其修订条件。
+
+Ownership 2.1 的 `default/sub_aids/{sub_aid}/owner.md` 必须公开可读，只有命名空间所属 owner 可修改、删除；该限制覆盖 ACL、token、父目录、移动、重命名、软链、挂载及自动清理，不能由通用权限顺序放宽。关系释放仍以 NS 验收为准；完整规则见 [Ownership 协议定义 2.1](Ownership协议定义2.1.md)。
+
 ### `storage.put_object`
 
 内联写入小对象（≤ 内联上限）。
@@ -47,6 +55,7 @@ Storage 服务是 AUN 协议的应用层扩展，提供对象存储能力。负
 | `is_private` | boolean | ❌ | 默认 `true`，公开对象可被其他 AID 读取 |
 | `overwrite` | boolean | ❌ | 默认 `true`，`false` 时对象已存在则拒绝 |
 | `expected_version` | integer | ❌ | CAS 并发控制，版本不匹配则拒绝 |
+| `expected_revision` | string | ❌ | 原权威路径修订；Ownership 发布须携带 |
 | `expire_in_seconds` | integer | ❌ | 过期时间，`0` 表示永不过期 |
 | `metadata` | object | ❌ | 用户自定义元数据 |
 
@@ -67,9 +76,13 @@ Storage 服务是 AUN 协议的应用层扩展，提供对象存储能力。负
 | `owner_aid` | string | ❌ | 默认调用者 AID |
 | `bucket` | string | ❌ | 默认 `"default"` |
 | `object_key` | string | ✅ | 对象路径 |
+| `consistency` | string | ❌ | 传 `authoritative` 时绕过缓存并返回完整权威对象 |
+| `expected_revision` | string | ❌ | 条件读取使用的原权威路径修订 |
 
 **响应**：`{ owner_aid, bucket, object_key, content (base64), content_type, size_bytes, sha256, version, updated_at }`
 
+可选 `consistency: authoritative` 返回本节定义的权威对象结果；权威 get 要求完整对象，不接受范围读取。
+
 **权限**：私有对象仅所有者可读；公开对象（`is_private=false`）任何 AID 可读。
 
 ### `storage.head_object`
@@ -80,15 +93,17 @@ Storage 服务是 AUN 协议的应用层扩展，提供对象存储能力。负
 
 **响应**：`{ owner_aid, bucket, object_key, content_type, size_bytes, sha256, version, etag, is_private, expire_at, created_at, updated_at }`
 
+可选 `consistency: authoritative` 返回本节定义的权威对象结果，包括明确不存在与路径修订。
+
 **权限**：同 `get_object`。
 
 ### `storage.delete_object`
 
 删除单个对象。
 
-**参数**：同 `get_object`。
+**参数**：对象寻址同 `get_object`，可附 `expected_revision` 作条件删除。
 
-**响应**：`{ deleted (bool), owner_aid, object_key }`
+**响应**：`{ deleted (bool), owner_aid, object_key }`；条件删除附新路径 `revision`。
 
 **权限**：仅所有者可删。
 
@@ -164,6 +179,7 @@ Storage 服务是 AUN 协议的应用层扩展，提供对象存储能力。负
 | `size_bytes` | integer | ❌ | 预期大小（客户端追踪用） |
 | `content_type` | string | ❌ | 默认 `application/octet-stream` |
 | `expected_version` | integer | ❌ | CAS 版本检查（签 URL 前校验） |
+| `expected_revision` | string | ❌ | 固定上传 session 的原权威路径修订，最终发布再次检查 |
 | `expire_in_seconds` | integer | ❌ | URL 有效期，默认 3600 秒 |
 
 **响应**：`{ upload_url, blob_key, expire_at, owner_aid, bucket, object_key, content_type, size_bytes }`
@@ -192,6 +208,8 @@ Storage 服务是 AUN 协议的应用层扩展，提供对象存储能力。负
 | `expire_in_seconds` | integer | ❌ | 过期时间，默认永不过期 |
 | `metadata` | object | ❌ | 用户自定义元数据 |
 | `expected_version` | integer | ❌ | CAS 并发控制 |
+| `expected_revision` | string | ❌ | 原权威路径修订；使用条件 session 时须与 session 一致 |
+| `session_id` | string | ❌ | create_upload_session 返回的条件上传 session |
 
 **响应**：`{ owner_aid, bucket, object_key, size_bytes, content_type, sha256, version, etag, updated_at }`
 

package/_packed_docs/protocol/agent.md/SCHEMA.md

@@ -2,6 +2,10 @@
 
 版本: 1.0.0
 
+本文是 legacy Agent.md 1.0 历史副本，不定义当前尾部文件签名或 Ownership 2.1。当前文件容器、可扩展 type、AID 和 ownership 字段以 [Ownership 协议定义 2.1](../Ownership协议定义2.1.md) 为准；[Ownership 2.0 Schema](../../agent.md/SCHEMA.md) 也属于历史版本。
+
+当前 Group/Org 仅由专属生命周期的 owner 本人代签代上传，owner 必填而 ownership 可缺省，签名块必含 signer_aid；完整规则见 [当前协议 §2.5](../Ownership协议定义2.1.md#25-grouporg-名片的-owner-代签与上传)，不采用本历史副本的签名方式。
+
 ## 限制
 
 - **文件大小**: 最大 4KB

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

@@ -139,7 +139,7 @@ await client.connect({
 | `short_ttl_ms` | 短连接服务端兜底超时 |
 | `delivery_mode` | 连接级投递语义 |
 | `extra_info` | 应用层自定义连接信息；下划线开头的键不会透传给 Gateway |
-| `background_sync` | 连接成功后是否执行 SDK 后台补洞 / 未读同步，默认开启 |
+| `background_sync` | 连接成功后是否执行消息后台补洞 / 未读同步，默认开启；不关闭已读状态查询补偿 |
 | `auto_reconnect` | 断线后是否自动重连 |
 | `heartbeat_interval` | 心跳间隔，秒 |
 | `retry.initial_delay` / `retry.max_delay` | 退避重连参数 |
@@ -210,13 +210,16 @@ print(client.can_connect, client.can_send, client.is_online)
 | `group.changed` | 群组事件 |
 | `message.undecryptable` / `group.message_undecryptable` | E2EE 解密失败 |
 | `delivery.changed` | SDK 本地批量交付完成通知，用于合并 UI 刷新（完整契约见 [06-API手册](06-API手册.md#deliverychanged)） |
+| `read_state_sync` | SDK 本地已读状态补偿完成，含本轮 `owner_aid`、`states` 和逐项 `errors`；连接返回不代表补偿完成 |
 
-建议在 `connect()` 前注册事件处理器。
+建议在 `connect()` 前注册事件处理器。`read_state_sync` 只交付本轮成功查询涉及的去重状态及逐项错误，空查询不夹带旧缓存。AID/device 切换按身份代际隔离缓存、登记及补偿完成事件，A→B→A 也不能接受旧代际结果；原在途 RPC 仍可返回。
 
 ---
 
 ## Agent Web / agent.md
 
+以下普通主体示例以本 AID 签名和 token 上传。Group/Org 使用专属 owner 生命周期：owner 与 entity_cert_fingerprint 必填、可无 ownership；仅当前 owner 用本人证书和私钥尾签（signer_aid=owner）并携带 V2 owner 授权，实体自身 token 不授予名片上传权。上传与恢复新鲜核对 owner/状态及实体证书代际，格式见 [Ownership 协议 §2.5](../protocol/Ownership协议定义2.1.md#25-grouporg-名片的-owner-代签与上传)。
+
 发布自己的 agent.md：
 
 ```python