@agentunion/fastaun-browser 0.5.4 → 0.5.8

package/_packed_docs/AUN/347/246/273/347/272/277/346/216/250/351/200/201/346/234/215/345/212/241/350/277/220/347/273/264/344/270/216/345/217/221/345/270/203/346/214/207/345/215/227.md

@@ -0,0 +1,144 @@
+# AUN 离线推送服务运维与发布指南
+
+本文档定义 Push Service V1 的发布门、运行诊断、灰度和回滚。协议语义以 `docs/superpowers/契约冻结-v3-to-v4.md` 为准，架构说明见 `docs/superpowers/specs/2026-07-24-push-service-design-v3.md`，实施范围见 v4 计划。
+
+## 1. 当前发布结论
+
+- 隔离 PoC 可以运行；生产发布仍被 token 安全门硬阻断。
+- 明文 push token 只允许隔离 PoC。生产环境必须使用可信加密与密钥管理，未满足时服务应拒绝启动，而不是降级运行。
+- V1 不转发 `push.offline_message` 到 federation。当前跨域 federation 验收未执行，不得标记为通过。
+- Message/Group 的消息成功语义不依赖 Push Service；推送停用或故障不应改变消息主链结果。
+
+## 2. 发布前强制门
+
+每次构建或配置变更后必须重新执行以下门禁：
+
+1. 六项冻结契约及 Push、Gateway、Message、Group、Launcher 关联回归全部通过。
+2. 本地 P2P、Group、多设备、在线抑制、聚合、频控、ACK、响应丢失与 dedup、timeout、恢复、迁移和优雅关闭证据完整。
+3. 日志文件和相关容器 stdout/stderr 的敏感信息扫描为零命中。
+4. 容量、公平性、batch 数量、事件字节上限和 `max_inflight_per_server` 自动化测试通过。
+5. 固定身份材料只读复用；不得删除、重建或修改既有身份和数据库。
+6. 生产 token 加密门满足；否则只能发布到隔离 PoC。
+
+任何未解释失败、环境缺失或未执行项都必须明确记录，不能用 mock 或空桩替代真实证据。
+
+## 3. 运行依赖与启动判定
+
+Push Service 依赖：
+
+- Kernel 生命周期连接；
+- `aun_push` 数据库及已完成的版本化 migration；
+- 唯一可用 Gateway 的 discovery、service-plane attach 和 heartbeat；
+- 有效且受保护的诊断凭据。
+
+状态含义：
+
+| 状态 | 运维判断 |
+| --- | --- |
+| `healthy` | migration、数据库、Gateway attach 和 runtime 均已就绪 |
+| `waiting` | 尚未完成首次就绪，常见于零 Gateway 或初始化中 |
+| `blocked` | 发现多个可用 Gateway 等违反 V1 唯一性约束的条件 |
+| `degraded` | 曾经就绪，但数据库、Gateway 或调度运行出现故障 |
+| `draining` | 已拒绝新变更请求，仍保留 ACK 通道并等待 in-flight 收敛 |
+
+服务不得在 migration 失败、Gateway 数量非法或依赖未就绪时伪装为 `healthy`。
+
+## 4. 诊断入口
+
+内部诊断端点使用 Bearer 认证，只允许集群私网访问：
+
+- `/internal/diagnostics/health`
+- `/internal/diagnostics/status`
+- `/internal/diagnostics/metrics`
+- `/internal/diagnostics/capabilities`
+
+`status.business` 给出候选队列深度、in-flight、最老候选等待时间，以及最近一次调度、维护和存储快照状态。
+
+`metrics` 的核心分组：
+
+| 分组 | 主要用途 |
+| --- | --- |
+| `rpc` | register、unregister、enqueue、ack 的调用量、结果、错误码和延迟 |
+| `scheduler` | claim、计划、batch、dispatch、dedup、timeout、恢复、in-flight、事件字节和迭代耗时 |
+| `scheduler_outcomes_total` | 在线抑制、无 registration、频控、过期、Gateway 未知和永久拒绝等原因计数 |
+| `maintenance` | registration 失效、candidate 过期和终态数据清理结果 |
+| `storage` | candidate、delivery、batch 状态计数、队列深度、in-flight 和最老候选等待时间 |
+
+存储状态快照默认每 5 秒采样一次，因此用于趋势、告警和故障定位，不是事务级实时读数。指标只包含计数、耗时和受控状态，不包含 AID、token、消息内容或 payload。
+
+## 5. 告警判断
+
+优先处理以下信号：
+
+- `lifecycle_state` 为 `blocked`、`degraded` 或长期 `waiting`；
+- `storage.candidate_queue_depth` 持续增长，且 `oldest_candidate_age_ms` 接近 candidate TTL；
+- `scheduler.inflight_batches` 长期不下降，或 `timeouts_total` 连续增长；
+- `scheduler_outcomes_total.online_unknown`、`push_server_unknown` 或 `gateway_result_unknown` 持续增长；
+- `rpc.errors_by_code` 中 timeout、unavailable 或 conflict 异常增长；
+- `maintenance.errors_total` 增长或存储快照长时间不更新；
+- Message/Group 候选队列出现满、TTL 丢弃或 drain 超时日志。
+
+排障时按 candidate → delivery → batch → Gateway connection 的关联标识查日志；不得为了诊断打开 token 或消息正文日志。
+
+## 6. 性能与容量基线
+
+2026-07-26 Windows amd64 基线，512 个候选、4 个 Push Server、每目标 1 个 delivery：
+
+| 指标 | 结果 |
+| --- | ---: |
+| 三轮五次规划 P95 | 3.7478–5.7713 ms；中位 4.3937 ms |
+| benchmark | 3.424612–4.595007 ms/op；中位 3.667848 ms/op |
+| 内存 | 4,960,258–4,960,760 B/op |
+| 分配 | 28,954–28,956 allocs/op |
+
+自动灾难性退化门为 512 候选规划 P95 不超过 2 秒。该基线只覆盖内存调度规划，不代表数据库、Gateway、移动推送平台或公网端到端吞吐。
+
+容量配置必须同时满足：
+
+- 单批 delivery 数量和事件字节上限；
+- 每 Push Server 最大 in-flight；
+- 全局、Push Server 和目标频控；
+- registration/candidate TTL、ACK timeout、重试上限和终态保留；
+- 同一 Push Server 内目标公平轮询，以及不同 Push Server 间公平轮询。
+
+## 7. 安全与身份材料
+
+- 普通日志、归档日志、crash JSON 和容器输出均必须经过敏感信息扫描。
+- token 只允许记录不可逆短指纹；Bearer、seed、私钥和消息内容不得进入诊断或日志。
+- Launcher 启动环境摘要必须按变量名统一脱敏 token、password、secret、HMAC、seed、key、DSN，以及带用户信息的 URL。
+- Docker Push Server 服务身份使用只读 PEM 证书和私钥，不需要 SDK seed。
+- SDK `key.json` 身份的 seed 在构造 `AIDStore` 或对应身份存储时显式传入；正常运行和身份目录复制不读取 `.seed` 文件。
+- SDK 不提供 `.seed` 文件读取或迁移入口；轮换 seed 时必须显式提供当前与新的 seed_password。
+
+## 8. 隔离 PoC 灰度
+
+1. 先以 `AUN_PUSH_ENABLED=false` 部署镜像并完成 migration、诊断和三中心纳管检查。
+2. 只接入隔离 Mock Push Server 和授权的测试安装，不接真实生产 token。
+3. 使用较低的 batch、频控和 in-flight 上限启用 Push Service。
+4. 再分别开启 `AUN_MESSAGE_OFFLINE_PUSH_ENABLED`、`AUN_GROUP_OFFLINE_PUSH_ENABLED`，观察候选队列、在线抑制、ACK、timeout 和清理指标。
+5. 扩大覆盖前必须确认消息主链结果不受推送故障影响，且日志扫描仍为零命中。
+
+在可信 token 加密完成前，不存在生产灰度路径。
+
+Mock Push Server 使用修改后的 Python SDK 作为普通长连接客户端。SDK 自身仍把认证类终止 close code（包括 4008）视为停止自动重连；Mock 的常驻进程只在 SDK 已结束内部重连且处于离线终态后，由应用层守护重新调用 `connect()`。这是测试工具的恢复策略，不改变公共 SDK 重连契约。
+
+## 9. 回滚
+
+回滚顺序：
+
+1. 先关闭 `AUN_MESSAGE_OFFLINE_PUSH_ENABLED` 和 `AUN_GROUP_OFFLINE_PUSH_ENABLED`，停止产生新候选。
+2. 等待生产者候选队列 drain；超时项按既定允许丢失边界记录指标和日志。
+3. 将 `AUN_PUSH_ENABLED=false`，让 Push Service 进入可管理的停用模式并完成优雅关闭。
+4. 如需回退镜像，在服务停用后执行；保留 `aun_push` schema 和数据，不做逆向 migration、清表或身份重建。
+5. 回滚后验证 Message/Group 发送、pull 和 ack 主链正常。
+
+Push 是辅助唤醒链路，回滚不得触碰消息正文、SDK 固定身份或既有 AID 数据。
+
+## 10. 已知限制
+
+- V1 只支持单 Push Service、单可用 Gateway 和批次级 ACK。
+- `push.offline_message` 不跨 federation；跨域验收当前未执行。
+- Push Service 不直接调用 APNs/FCM，移动平台适配属于 Push Server 职责。
+- 明文 token 仅限隔离 PoC，生产发布仍被硬阻断。
+- 诊断存储快照是周期采样；瞬时值应结合 Scheduler 日志和持久状态判断。
+- 当前性能数字是调度规划微基准，不替代真实数据库和公网容量测试。

package/_packed_docs/CHANGELOG.md

@@ -6,113 +6,223 @@
 
 ---
 
-## 0.5.4 — 2026-07-09
+## 0.5.8 — 2026-08-30
 
 ### 新功能
 
-#### 通用 indexed document settings
-- 浏览器 `GroupFacade` 新增 `getSettingWithIndex()` / `updateSettingWithIndex()`，支持按 `keyName` 管理 `{keyName}.content` 与 `{keyName}.attachments` 两类文档型 indexed settings。
-- `keyName` 增加统一校验：必须匹配 `^[A-Za-z][A-Za-z0-9_-]{0,63}$`，并拒绝 `join`、`group`、`index`、`visibility` 等保留基名。
-- `getAnnouncement()` / `updateAnnouncement()` 与 `getRules()` / `updateRules()` 复用通用 indexed document setting 路径，继续通过 signed `group.index` + `expected_index_etag` CAS 写入。
+#### AID 注册与 agent.md
+- `AIDStore.register()` 默认生成符合 schema 的 `agent.md`（`aid`、`type: "agent"` 等字段），使用对应 AID 签名并上传；`uploadAgentMd()` 仍可按需显式替换内容，也支持由另一个本地 uploader AID 认证代传。
+- 增加 agent.md 的严格 frontmatter、UTF-8/Base64、大小、证书有效期、证书指纹、公钥指纹和签名校验；校验失败不会覆盖已有内容或可信缓存。
+- 新版本连接能力声明 `agent_md_validation_v1`；收到缺少 agent.md 的 `-32003` 时自动生成、签名、上传并重试原 RPC。恢复只针对当前 AID，群 agent.md 恢复只由持有 group AID 私钥的群主执行。
 
-#### 入群要求附件
-- `getJoinRequirements()` / `updateJoinRequirements()` 支持 `attachments`，对应服务端 `join.attachments` indexed setting。
-- `join.attachments` 与公告/群规附件保持同一类 `group.fs` 引用结构，可通过 group.index 签名索引同步。
+#### 群身份与 group agent.md
+- 命名群的 `createGroup()` 在 `group.create` 时携带新生成的 group AID 公钥和曲线，并要求服务端返回匹配的 group AID 证书；匿名群先创建，再按原始 `groupId` 绑定证书并导入本地 group AID。
+- `bindGroupAid()`、`renewGroupAid()` 和群主转移完成流程校验证书、公钥和用途，并自动上传 `type: "group"` 的 group agent.md；内容由 group AID 签名，群主 AID 负责认证上传。
+- group agent.md 可以事后上传，但在上传有效证书和 agent.md 前，群管理、群消息、`group.fs` 等后续群 RPC 继续受 Gateway 限制；历史群缺证书或缺 group agent.md 的自动修复仅允许群主执行。
 
-#### Group FS 角色 ACL
-- 服务端 group.fs 命名空间新增受保护 `.group` 控制目录，并为 owner/admin 同步基线角色 ACL。
-- owner/admin 默认可写群自有区；admin 可管理群自有区角色 ACL。
-- `role:member` 支持按具体业务目录授予 `rw`，允许成员创建/上传，但不允许删除、重命名或移动群自有区内容。
+### 安全性
+
+- Gateway 在 client-vs-gateway RPC 入口校验客户端 agent.md、普通 AID 证书、group AID 证书及 group agent.md；`group.create`、`group.bindGroupAid`、`group.renewGroupAid` 等建群/绑定例外保留必要的恢复路径。
+- 上述准入只对 connect 协商声明 `agent_md_validation_v1` 的新 SDK 生效，未声明能力的旧 SDK 保持原有行为；Gateway 同时收紧 AID type、group namespace、RPC 目标和路由边界校验。
+- agent.md、证书和身份解析采用带 TTL 的正/负缓存，支持并发请求合并、容量上限及 CA 写入、agent.md 上传和相关事件触发的失效；代际校验防止过期查询回写缓存。
 
 ### 修复
 
-- 修复 Storage 直接入口对群自有区删除/移动/重命名权限检查不足的问题，删除类操作统一走 `delete` 权限判定。
-- 修复旧 group AID 证书类型仍为 normal 时，Storage 无法通过 group resolver 判定群空间的问题。
-- 兼容 CA 续期时 PEM 公钥与 SPKI base64 的等价比较，并兼容托管续期返回 `cert_pem` / `new_cert` 字段。
+#### Pull gate 与未读提示
+- `AUNClient` 统一使用一个 pull gate 和队列，前台 pull 优先于后台 pull，二者共享 namespace 去重；P2P 作为一个 namespace，每个 group 独立 namespace，后台请求不旁路也不丢弃。
+- pull 生命周期纳入 `idle`、`pulling`、`processing` 等状态和专用 watchdog；从拉取开始计时，约 3 秒超时即复位并继续队列，应用触发和新 push 会主动唤醒状态机。续拉在响应处理完成后重新入队并置于队尾。
+- `client.online` 时服务端为 P2P 及存在未读消息或事件的群发送 unread hint；SDK 每条 hint 转换为一次 background forward pull，按 namespace 去重。
+
+#### V2 消息窗口与游标
+- Forward 页忽略页内空洞并推进到 pulled page 最大 seq；先完成解密/发布，再一次性提交本页连续游标并发送 ACK 或 piggyback ACK。缺少 SPK/IK 时异步 bootstrap，不阻塞页处理；有密钥但解密失败时发布结构化失败事件后再推进游标。
+- 修正 P2P/群 V2 的 1DH/3DH、IK/SPK bootstrap、self-sync、forward cursor/ACK、重叠页去重及跨页有序投递；服务端 ACK 水位不足时保留待确认状态并在后续 pull 重试。
+- Message/Group thought 存储与响应结构统一，并增加响应预算/大小限制；Go `CollabActionResult` 兼容 `removed` 布尔值和整数格式。
+
+#### Gateway 与服务连接可靠性
+- 加固 service attach、连接替换、关闭码、协议错误预算、超时以及 reader/close 竞态；Python/Go 服务端行为和合同测试保持一致。
+- nameservice agent.md upsert、上传验证及数据库/快照兼容性同步修正；SDK 测试器使用阿里云 PyPI 镜像缓解下载超时。
 
 ### 改进
 
-- message/group WAL writer 的 `micro_wait` 支持 auto 预算模型，并扩展性能统计输出，便于观察批量写入队列深度与 pending 状态。
-- group.fs 命名空间在读取 group 记录时支持懒修复，缺失 baseline ACL 时可重试同步。
-- SDK 包版本、运行时 `VERSION` 和 conformance 期望版本更新为 `0.5.4`。
+- SDK 包版本、锁文件版本、运行时 `VERSION` 和 V2 E2EE envelope `sdk_version` 更新为 `0.5.8`。
+- 低层 agent.md 上传能力继续由 `AIDStore` 提供，`AUNClient` 通过高层注册、建群和恢复流程编排；agent.md 替换仍保留为可选、按需操作。
 
 ### 测试
 
-- 扩展浏览器 GroupFacade group index 单元测试，覆盖通用 indexed document setting、`join.attachments` 缓存读取和 group.index 写入路径。
-- 更新 conformance 版本期望到 `0.5.4`。
-- 服务端测试扩展 group settings、group.fs namespace / role ACL、Storage 群自有区权限和 CA 续期兼容性。
-
----
+- 新增 AID 类型和 Gateway 路由准入的单元、集成、E2E 及跨 SDK 测试，覆盖新旧能力声明、证书/agent.md 缺失恢复、群主权限和缓存失效。
+- 扩展 agent.md、群身份绑定/续期、group.fs、V2 E2EE、pull gate 状态机、unread hint、游标/ACK、thought 响应预算和服务连接合同测试。
 
-## 0.5.3 — 2026-07-07
+## 0.5.7 — 2026-08-20
 
 ### 新功能
 
-#### group.index 索引化群设置
-- 新增浏览器 `group.index` JSONL 工具：支持 canonical entries、body hash、etag、ECDSA P-256 签名/验签，以及将 settings 更新合并为带 `group.index` 的原子写入。
-- `GroupFacade` 新增 `checkGroupIndex` / `getGroupIndex` / `updateGroupIndex`，写入时携带 `expected_index_etag` 做 CAS，并在冲突后重拉索引重试。
-- 浏览器 IndexedDB TokenStore 新增 `group_index_cache`，按 local AID + group AID 持久化 index JSONL、remote meta、本地 etag、settings cache 和 entry etags。
-- 入口导出 `GROUP_INDEX_KEY`、`GROUP_INDEX_SCHEMA`、`GroupIndexMetaCache`、`buildSignedGroupIndex`、`verifyGroupIndex`、`prepareGroupSettingsWithIndex` 等 group.index API。
+#### 首次连接自动重试
+- `connect()` 在首次 discovery、认证或 Gateway WebSocket 建连遇到可重试的瞬时错误时，进入与断线重连一致的指数退避生命周期；每轮重新执行完整 discovery/认证并使用最新凭据。
+- 认证、权限、参数和状态类永久错误仍立即返回，不创建后台重连任务。
+
+#### Mail facade 与当前令牌 API
+- 新增 `client.mail` / `MailFacade`，提供 `send()`、`get()`、`list()`、`delete()`、`move()`、`mark()`、`search()`、`getAttachment()`、`getQuota()`、`health()` 和 `status()`；`mail.send` 按非幂等 RPC 使用 35 秒超时。
+- 新增 `getAccessToken()`，同步读取后台刷新任务维护的最新 access token，供应用在每次外部 HTTP 数据面请求前取用；getter 本身不发起认证、刷新或网络请求。
 
 ### 修复
 
-#### 撤回去重与有序投递
-- `message.recalled` 改为专用处理路径，支持 P2P 撤回 tombstone 的有序投递、自动 ack、gap fill 和按原消息标识去重，避免 push / pull 对同一次撤回重复回调。
-- 群撤回去重键改为规范化 group id + 原消息 id/seq，忽略 `recalled_at`，并补齐顶层 recall 字段归一化。
-- 群消息 pull / legacy fallback 识别 `group.message_recalled` tombstone，避免把撤回通知作为普通群消息投递。
-- P2P 与群 push 按 namespace 串行化处理，降低异步解密和投递导致的乱序风险。
-- V2 P2P / Group pull 页内消息按 `seq` 排序后处理，避免服务端返回无序时影响本地 seq 推进。
+- 引入重连代际所有权；显式 `connect()` / `disconnect()` / `close()` 可终止旧重连代，旧任务不能清理或覆盖新连接，事件回调内触发生命周期操作也不会自锁。
+- 收口群 ID 语义：`g-` 不再具有特殊含义，所有群 base 统一按 4–64 字符规则校验；移除 `base@issuer` 兼容输入，仅保留 `group.{issuer}/{base}`、`base.issuer` 和本域短格式。
+- `stream/created` 和 `stream/closed` 内部事件重新发布给公共订阅者。
+- Group tail/history 遇到缺失 payload 的不完整 V1 行时采用有界跳过或失败语义，避免阻断后续同步。
 
 ### 改进
 
-- `RPCTransport` 的 `_meta` observer 支持异步回调；RPC 成功响应会等待 observer 完成，事件/通知路径统一走安全的 meta observer 分发。
-- `getAnnouncement` / `getRules` / `getJoinRequirements` 优先使用 group.index settings cache；`updateAnnouncement` / `updateRules` / `updateJoinRequirements` 改走 `updateGroupIndex`，保持索引与设置同步。
-- cross-sdk JS agent 支持 `sdk.update_group_index` 调用，便于跨 SDK 测试索引化群设置。
-- SDK 包版本、运行时 `VERSION` 和 conformance 期望版本更新为 `0.5.3`。
+- SDK 包版本、锁文件版本、运行时 `VERSION` 和 conformance 期望版本更新为 `0.5.7`。
 
 ### 测试
 
-- 新增 group.index 单元测试，覆盖 hash/etag、签名/验签、settings merge、RPC meta stale/fresh、async meta observer 和 IndexedDB 持久化恢复。
-- 新增 GroupFacade group.index 单元测试，覆盖 CAS 写入、冲突重试、远端索引验签、tamper 拒绝、settings cache 和便利方法索引化写入。
-- 新增浏览器 E2E：验证签名 `group.index` 写入、裸 settings 写入拒绝、CAS 冲突重试和最终 settings 一致性。
-- 扩展撤回投递测试，覆盖 P2P/group recall 顶层字段归一化、push/pull tombstone 去重和有序投递。
-- 更新 group settings 与签名审计 E2E，使公告/群规等索引化 settings 通过 `updateGroupIndex` 写入。
-
----
+- 新增首连认证/建连失败、永久错误、重连代际取消、事件回调重入、最新 token getter 和 Mail facade 单元测试。
+- 扩展群 ID 校验、浏览器跨域 Group FS、新设备群历史同步、V2 E2EE 和 replay guard E2E 测试。
 
-## 0.5.2 — 2026-07-05
+## 0.5.6 — 2026-08-13
 
 ### 新功能
 
-#### agent.md 元数据
-- 支持从 RPC `_meta.agent_md_etags.group` 和 V2 envelope `agent_md.group` 观察群组 agent.md ETag / Last-Modified，并自动维护群 AID 的本地缓存。
-- 群消息 agent.md 观察逻辑补齐 sender / group 两类来源，提升浏览器端跨设备、跨群消息场景下的版本一致性提示能力。
+#### V2 消息窗口与实时推送
+- 完成 `tail` / `forward` / `history` 消息窗口、IndexedDB seq 状态持久化和 pull gate 调度，统一 P2P 与群消息的补洞、确认和有序投递。
+- 连接认证时声明 `inline_realtime_payload_v1`；实时事件优先使用内联消息载荷，离线或不完整事件继续通过 pull 回退。
+- 对齐 Message/Group self-sync 与 bootstrap 契约，补齐浏览器多设备同步状态处理。
 
-### 修复
+#### 群消息提及过滤
+- 新增 `mention_mode` 归一化与投递过滤，兼容 `disabled`、`mention-only` 及历史 `mention_only` 表示。
+
+### 安全性
 
-#### V2 P2P / Group 拉取
-- `message.v2.pull` / `group.v2.pull` 自动 ack 改为通过下一次 pull 的 `ack_up_to_seq` piggyback，减少独立 ack RPC。
-- 修复非满页返回 `has_more=true` 时盲目续拉的问题；满页继续立即拉，非满页仅在有待合并 ack 时追加一页。
-- 过滤 `seq <= after_seq` 的 stale 原始消息，避免重复处理或错误推进 ack。
-- stale 原始页未推进 contiguous seq 时不再发送自动 ack，避免把未真正拉齐的数据误确认。
+- `lookupPeer()` 在内存 peer cache 未命中或指纹不匹配时自动获取并校验证书；支持按签名指纹精确加载历史证书。
+- `group.index` 和 `agent.md` 在下载或更新提交 IndexedDB 缓存前验签；rules、announcement、join requirements 等索引化 settings 逐项校验已签名索引中的 ETag。签名者权限、摘要或内容校验失败时不落盘，也不参与业务读取；已验证缓存的普通读取不重复验签。
+- 修复跨域 Storage 下载的 bearer 隔离，并加固浏览器连接/重连及 Gateway 候选故障转移。
 
 ### 改进
 
-- V2 pull 默认/最大 page limit 收敛为 50，并对传入 `limit` 做 1..50 夹取。
-- V2 pull 增加非满页 tail delay：`1000ms / (pulled_messages + 1)`，最大 500ms；满页和空页仍立即结束或续拉。
-- SDK 包版本、运行时 `VERSION` 和 conformance 期望版本更新为 `0.5.2`。
+- 收口短 RPC、challenge/response、前置帧和浏览器 transport 竞态；后台补洞/ack 调度不再阻塞前台 RPC。
+- 扩展浏览器 cross-SDK agent 与诊断契约，覆盖消息窗口和 inline realtime 场景；浏览器 SDK 本版本未新增离线 Push facade。
+- 浏览器使用 IndexedDB keystore，不适用文件型 `.seed` 自动迁移；不新增文件型 `change-seed` 命令。
+- SDK 包版本、运行时 `VERSION` 和 conformance 期望版本更新为 `0.5.6`。
 
 ### 测试
 
-- 扩展 V2 P2P / Group pull 单元测试，覆盖 `ack_up_to_seq` piggyback、非满页 tail delay、stale 过滤和 max pages flush。
-- 新增 `v2-e2ee-coordinator` 组件边界测试，验证自动 ack 通过下一页 pull piggyback。
-- 扩展 agent.md 和 conformance 测试，覆盖群组 ETag 观察及 0.5.2 版本声明。
-
----
-
-## 0.5.1 — 2026-07-01
+- 新增消息窗口、inline realtime push、mention mode、self-sync/bootstrap、peer identity、group index、`agent.md` 和 IndexedDB/浏览器 E2E 测试。
+- 扩展 cross-SDK contract vectors，覆盖验签后缓存提交和窗口状态一致性。
 
-### ⚠️ 重大变更（Breaking Changes）
+## 0.5.5 — 2026-07-14
+
+### 维护
+
+- SDK 包版本、运行时 `VERSION` 和 conformance 期望版本更新为 `0.5.5`。
+
+## 0.5.4 — 2026-07-09
+
+### 新功能
+
+#### 通用 indexed document settings
+- 浏览器 `GroupFacade` 新增 `getSettingWithIndex()` / `updateSettingWithIndex()`，支持按 `keyName` 管理 `{keyName}.content` 与 `{keyName}.attachments` 两类文档型 indexed settings。
+- `keyName` 增加统一校验：必须匹配 `^[A-Za-z][A-Za-z0-9_-]{0,63}$`，并拒绝 `join`、`group`、`index`、`visibility` 等保留基名。
+- `getAnnouncement()` / `updateAnnouncement()` 与 `getRules()` / `updateRules()` 复用通用 indexed document setting 路径，继续通过 signed `group.index` + `expected_index_etag` CAS 写入。
+
+#### 入群要求附件
+- `getJoinRequirements()` / `updateJoinRequirements()` 支持 `attachments`，对应服务端 `join.attachments` indexed setting。
+- `join.attachments` 与公告/群规附件保持同一类 `group.fs` 引用结构，可通过 group.index 签名索引同步。
+
+#### Group FS 角色 ACL
+- 服务端 group.fs 命名空间新增受保护 `.group` 控制目录，并为 owner/admin 同步基线角色 ACL。
+- owner/admin 默认可写群自有区；admin 可管理群自有区角色 ACL。
+- `role:member` 支持按具体业务目录授予 `rw`，允许成员创建/上传，但不允许删除、重命名或移动群自有区内容。
+
+### 修复
+
+- 修复 Storage 直接入口对群自有区删除/移动/重命名权限检查不足的问题，删除类操作统一走 `delete` 权限判定。
+- 修复旧 group AID 证书类型仍为 normal 时，Storage 无法通过 group resolver 判定群空间的问题。
+- 兼容 CA 续期时 PEM 公钥与 SPKI base64 的等价比较，并兼容托管续期返回 `cert_pem` / `new_cert` 字段。
+
+### 改进
+
+- message/group WAL writer 的 `micro_wait` 支持 auto 预算模型，并扩展性能统计输出，便于观察批量写入队列深度与 pending 状态。
+- group.fs 命名空间在读取 group 记录时支持懒修复，缺失 baseline ACL 时可重试同步。
+- SDK 包版本、运行时 `VERSION` 和 conformance 期望版本更新为 `0.5.4`。
+
+### 测试
+
+- 扩展浏览器 GroupFacade group index 单元测试，覆盖通用 indexed document setting、`join.attachments` 缓存读取和 group.index 写入路径。
+- 更新 conformance 版本期望到 `0.5.4`。
+- 服务端测试扩展 group settings、group.fs namespace / role ACL、Storage 群自有区权限和 CA 续期兼容性。
+
+---
+
+## 0.5.3 — 2026-07-07
+
+### 新功能
+
+#### group.index 索引化群设置
+- 新增浏览器 `group.index` JSONL 工具：支持 canonical entries、body hash、etag、ECDSA P-256 签名/验签，以及将 settings 更新合并为带 `group.index` 的原子写入。
+- `GroupFacade` 新增 `checkGroupIndex` / `getGroupIndex` / `updateGroupIndex`，写入时携带 `expected_index_etag` 做 CAS，并在冲突后重拉索引重试。
+- 浏览器 IndexedDB TokenStore 新增 `group_index_cache`，按 local AID + group AID 持久化 index JSONL、remote meta、本地 etag、settings cache 和 entry etags。
+- 入口导出 `GROUP_INDEX_KEY`、`GROUP_INDEX_SCHEMA`、`GroupIndexMetaCache`、`buildSignedGroupIndex`、`verifyGroupIndex`、`prepareGroupSettingsWithIndex` 等 group.index API。
+
+### 修复
+
+#### 撤回去重与有序投递
+- `message.recalled` 改为专用处理路径，支持 P2P 撤回 tombstone 的有序投递、自动 ack、gap fill 和按原消息标识去重，避免 push / pull 对同一次撤回重复回调。
+- 群撤回去重键改为规范化 group id + 原消息 id/seq，忽略 `recalled_at`，并补齐顶层 recall 字段归一化。
+- 群消息 pull / legacy fallback 识别 `group.message_recalled` tombstone，避免把撤回通知作为普通群消息投递。
+- P2P 与群 push 按 namespace 串行化处理，降低异步解密和投递导致的乱序风险。
+- V2 P2P / Group pull 页内消息按 `seq` 排序后处理，避免服务端返回无序时影响本地 seq 推进。
+
+### 改进
+
+- `RPCTransport` 的 `_meta` observer 支持异步回调；RPC 成功响应会等待 observer 完成，事件/通知路径统一走安全的 meta observer 分发。
+- `getAnnouncement` / `getRules` / `getJoinRequirements` 优先使用 group.index settings cache；`updateAnnouncement` / `updateRules` / `updateJoinRequirements` 改走 `updateGroupIndex`，保持索引与设置同步。
+- cross-sdk JS agent 支持 `sdk.update_group_index` 调用，便于跨 SDK 测试索引化群设置。
+- SDK 包版本、运行时 `VERSION` 和 conformance 期望版本更新为 `0.5.3`。
+
+### 测试
+
+- 新增 group.index 单元测试，覆盖 hash/etag、签名/验签、settings merge、RPC meta stale/fresh、async meta observer 和 IndexedDB 持久化恢复。
+- 新增 GroupFacade group.index 单元测试，覆盖 CAS 写入、冲突重试、远端索引验签、tamper 拒绝、settings cache 和便利方法索引化写入。
+- 新增浏览器 E2E：验证签名 `group.index` 写入、裸 settings 写入拒绝、CAS 冲突重试和最终 settings 一致性。
+- 扩展撤回投递测试，覆盖 P2P/group recall 顶层字段归一化、push/pull tombstone 去重和有序投递。
+- 更新 group settings 与签名审计 E2E，使公告/群规等索引化 settings 通过 `updateGroupIndex` 写入。
+
+---
+
+## 0.5.2 — 2026-07-05
+
+### 新功能
+
+#### agent.md 元数据
+- 支持从 RPC `_meta.agent_md_etags.group` 和 V2 envelope `agent_md.group` 观察群组 agent.md ETag / Last-Modified，并自动维护群 AID 的本地缓存。
+- 群消息 agent.md 观察逻辑补齐 sender / group 两类来源，提升浏览器端跨设备、跨群消息场景下的版本一致性提示能力。
+
+### 修复
+
+#### V2 P2P / Group 拉取
+- `message.v2.pull` / `group.v2.pull` 自动 ack 改为通过下一次 pull 的 `ack_up_to_seq` piggyback，减少独立 ack RPC。
+- 修复非满页返回 `has_more=true` 时盲目续拉的问题；满页继续立即拉，非满页仅在有待合并 ack 时追加一页。
+- 过滤 `seq <= after_seq` 的 stale 原始消息，避免重复处理或错误推进 ack。
+- stale 原始页未推进 contiguous seq 时不再发送自动 ack，避免把未真正拉齐的数据误确认。
+
+### 改进
+
+- V2 pull 默认/最大 page limit 收敛为 50，并对传入 `limit` 做 1..50 夹取。
+- V2 pull 增加非满页 tail delay：`1000ms / (pulled_messages + 1)`，最大 500ms；满页和空页仍立即结束或续拉。
+- SDK 包版本、运行时 `VERSION` 和 conformance 期望版本更新为 `0.5.2`。
+
+### 测试
+
+- 扩展 V2 P2P / Group pull 单元测试，覆盖 `ack_up_to_seq` piggyback、非满页 tail delay、stale 过滤和 max pages flush。
+- 新增 `v2-e2ee-coordinator` 组件边界测试，验证自动 ack 通过下一页 pull piggyback。
+- 扩展 agent.md 和 conformance 测试，覆盖群组 ETag 观察及 0.5.2 版本声明。
+
+---
+
+## 0.5.1 — 2026-07-01
+
+### ⚠️ 重大变更（Breaking Changes）
 
 #### 群组标识符统一为 GROUP_AID
 - **GROUP_ID 废弃**：历史 `group.{domain}/{base}` 格式已废弃，统一为 `{base}.{issuer}` 格式（group_aid）