@agentunion/fastaun 0.5.2 → 0.5.3

package/_packed_docs/sdk/09-group-rpc-manual.md

@@ -103,7 +103,7 @@
 | [group.set_settings](#groupset_settings) | 统一设置群参数（含公告、规则、入群要求、dispatch_mode 等） |
 | [group.get_settings](#groupget_settings) | 统一读取群参数 |
 
-**便利方法**：SDK 提供向后兼容的便利方法（`getAnnouncement`/`updateAnnouncement`/`getRules`/`updateRules`/`getJoinRequirements`/`updateJoinRequirements`），内部调用 `set_settings`/`get_settings`，返回旧格式。新代码建议直接使用 `set_settings`/`get_settings`。
+**便利方法**：SDK 提供向后兼容的便利方法（`getAnnouncement`/`updateAnnouncement`/`getRules`/`updateRules`/`getJoinRequirements`/`updateJoinRequirements`）。读取方法优先返回 SDK 本地缓存，本地没有对应值时才调用 `get_settings` 初始化；即使观察到远端 etag 不一致也不会自动 pull 远端。indexed 写入方法内部调用 `updateGroupIndex` 生成签名 `group.index` 并通过 `set_settings` CAS 提交。
 
 ### 群文件系统
 
@@ -951,7 +951,9 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
 
 ### group.set_settings
 
-统一写入群参数。需要 admin 及以上权限。`dispatch_mode` 是群消息的应用层分发模式标签，会随 `group.send` 生成的消息持久化，并由 SDK 在解密后注入到消息顶层和 `payload.dispatch_mode`。
+统一写入群参数。需要 admin 及以上权限。`dispatch_mode` 是群消息的应用层分发模式标签，会随 `group.send` 生成的消息持久化，并由 SDK 在解密后注入到消息顶层和 `payload.dispatch_mode`。
+
+`group.index` 是保留设置 key，用于保存 owner/admin SDK 生成并签名的群索引。更新 indexed settings 时必须同包提交新的签名 `group.index`，并通过 `expected_index_etag` 做 CAS。
 
 `dispatch_mode` 不是 `group.send` 的单次入参；要修改后续消息的模式，请通过 `group.set_settings` 更新群设置。
 
@@ -960,10 +962,12 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
 | `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
-| `settings` | object | 是 | 要写入的设置键值 |
-| `settings["dispatch_mode"]` | string | 否 | `"broadcast"` / `"mention"`，默认 `"broadcast"` |
-| `settings["rules.content"]` | string | 否 | 群规则正文 |
-| `settings["announcement.content"]` | string | 否 | 群公告正文 |
+| `settings` | object | 是 | 要写入的设置键值 |
+| `expected_index_etag` | string | 写 `group.index` 时必填 | CAS 期望旧 etag；空字符串表示只允许创建首个 `group.index` |
+| `settings["dispatch_mode"]` | string | 否 | `"broadcast"` / `"mention"`，默认 `"broadcast"` |
+| `settings["rules.content"]` | string | 否 | 群规则正文 |
+| `settings["announcement.content"]` | string | 否 | 群公告正文 |
+| `settings["group.index"]` | object | 更新 indexed settings 时必填 | 签名 group index，当前结构至少包含 `body` |
 
 **预定义群级参数**：
 
@@ -979,11 +983,28 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
 | `join.mode` | string | 按 `visibility` 推导：`public -> open`，`private -> approval` | 入群模式：`"open"` / `"approval"` / `"invite_only"` / `"closed"` |
 | `join.question` | string | `""` | 入群问题 |
 | `join.auto_approve_patterns` | array | `[]` | 自动批准 AID 匹配规则 |
-| `join.max_pending` | integer | `100` | 最大待审批入群申请数 |
-| `dispatch_mode` | string | `"broadcast"` | 群消息分发标签：`"broadcast"` / `"mention"`；未显式设置时 `get_settings` 仍返回默认值 |
-
-```python
-await client.call("group.set_settings", {
+| `join.max_pending` | integer | `100` | 最大待审批入群申请数 |
+| `dispatch_mode` | string | `"broadcast"` | 群消息分发标签：`"broadcast"` / `"mention"`；未显式设置时 `get_settings` 仍返回默认值 |
+| `group.index` | object | — | 保留 key；签名 JSONL 群索引，由 SDK 生成，服务端只校验、CAS 保存和返回 |
+
+**indexed settings**：
+
+| key | 说明 |
+|-----|------|
+| `rules.content` / `rules.attachments` | 群规则正文与附件稳定引用 |
+| `announcement.content` / `announcement.attachments` | 群公告正文与附件稳定引用 |
+| `join.mode` / `join.question` / `join.auto_approve_patterns` / `join.max_pending` | 入群要求配置 |
+
+写入规则：
+
+- 只更新非 indexed settings 时，继续直接调用 `set_settings`，不需要 `group.index`。
+- 更新任意 indexed setting 时，必须在同一次 `settings` 中携带签名 `group.index`。
+- 写入 `group.index` 时必须传 `expected_index_etag`。
+- 服务端在同一事务内比较当前 `group.index` etag、写 indexed settings、写 `group.index`。
+- CAS 失败时错误消息包含 `group.index etag conflict`；SDK 的 `updateGroupIndex` 会重新读取当前 index、重建签名并按 `max_attempts` 重试。
+
+```python
+await client.call("group.set_settings", {
     "group_id": "g-abc123.agentid.pub",
     "settings": {"dispatch_mode": "mention"},
 })
@@ -992,33 +1013,86 @@ await client.call("group.set_settings", {
 **响应**：
 
 ```json
-{
-    "group_id": "g-abc123.agentid.pub",
-    "updated_keys": ["dispatch_mode"]
-}
-```
-
-### group.get_settings
-
-统一读取群参数。成员可读；不传 `keys` 时返回核心群资料和 settings 表中的全部设置。未显式设置 `dispatch_mode` 时，服务端仍返回默认值 `"broadcast"`。
+{
+    "group_id": "g-abc123.agentid.pub",
+    "group_aid": "g-abc123.agentid.pub",
+    "updated_keys": ["dispatch_mode"]
+}
+```
+
+写入 `group.index` 成功时，响应顶层会强制携带 `_meta.group_indexes`：
+
+```json
+{
+    "group_id": "g-abc123.agentid.pub",
+    "group_aid": "g-abc123.agentid.pub",
+    "updated_keys": ["announcement.content", "group.index"],
+    "_meta": {
+        "group_indexes": {
+            "g-abc123.agentid.pub": {
+                "etag": "\"sha256:...\"",
+                "last_modified": 1780000000000,
+                "schema": "aun.group.index.v1"
+            }
+        }
+    }
+}
+```
+
+`group.index` 的正文格式：
+
+```jsonl
+{"type":"index_meta","group_aid":"g-abc123.agentid.pub","etag":"\"sha256:...\"","last_modified":1780000000000,"schema":"aun.group.index.v1","body_hash":"sha256:...","signed_by":"alice.agentid.pub","sig_alg":"ECDSA-P256-SHA256","signature":"base64..."}
+{"key":"announcement.content","source":"db","etag":"\"sha256:...\"","last_modified":1780000000000}
+```
+
+`etag` 和 `body_hash` 都由 index 条目的 canonical JSONL bytes 计算。`signature` 覆盖去掉 `signature` 字段后的 `index_meta` 和正文条目，`signed_by` 必须等于本次 RPC actor AID。服务端不会根据 DB 状态生成 `group.index`。
+
+### group.get_settings
+
+统一读取群参数。成员可读；不传 `keys` 时返回核心群资料和 settings 表中的全部设置。未显式设置 `dispatch_mode` 时，服务端仍返回默认值 `"broadcast"`。读取 `keys=["group.index"]` 可从服务端摘取当前签名 `group.index`。
 
 **参数**：
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
 | `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
-| `keys` | array | 否 | 只读取指定 key，如 `["dispatch_mode", "rules.content"]` |
+| `keys` | array | 否 | 只读取指定 key，如 `["dispatch_mode", "rules.content"]`；读取 `["group.index"]` 时强制返回 `_meta.group_indexes` |
 
 **响应**：
 
 ```json
-{
-    "group_id": "g-abc123.agentid.pub",
-    "settings": [
-        {"key": "dispatch_mode", "value": "broadcast", "updated_at": 1234567890000}
-    ]
-}
-```
+{
+    "group_id": "g-abc123.agentid.pub",
+    "group_aid": "g-abc123.agentid.pub",
+    "settings": [
+        {"key": "dispatch_mode", "value": "broadcast", "updated_at": 1234567890000}
+    ]
+}
+```
+
+如果服务端已保存 `group.index`，普通 settings 读取可能在顶层返回 `_meta.group_indexes`。该 meta 受服务端注入频率控制；显式读取 `group.index` 时会强制返回：
+
+```json
+{
+    "group_id": "g-abc123.agentid.pub",
+    "group_aid": "g-abc123.agentid.pub",
+    "settings": [
+        {"key": "group.index", "value": {"body": "..."}, "updated_by": "alice.agentid.pub", "updated_at": 1780000000000}
+    ],
+    "_meta": {
+        "group_indexes": {
+            "g-abc123.agentid.pub": {
+                "etag": "\"sha256:...\"",
+                "last_modified": 1780000000000,
+                "schema": "aun.group.index.v1"
+            }
+        }
+    }
+}
+```
+
+SDK 观察到 `_meta.group_indexes` 只记录远端 etag，不会自动覆盖本地 index 或业务缓存。etag 不一致只表示本地与观察到的远端版本不同，方向由应用层决定：`checkGroupIndex` 用于检查是否不同步，`getGroupIndex` 用于显式 pull 远端 manifest 并同步本地缓存，`updateGroupIndex` 用于显式 CAS push 本地 indexed settings。
 
 ## 消息
 

package/_packed_docs/sdk/AUN_DOCS_GUIDE.md

@@ -11,7 +11,7 @@ AUN SDK 文档位于 `docs/sdk/`，索引文件 `docs/sdk/INDEX.md` 分三层：
 - `AUNClient`：认证、连接、状态机、事件和 RPC。
 - `ServiceProxyClient`：Python SDK 的 Service Proxy provider 侧客户端，负责 Gateway 控制面注册和 proxy-server 数据面隧道注册。
 
-业务 RPC 的底层参数见 `09-*-rpc-manual.md`，可通过 `client.call(method, params)` 调用；Storage、Collab、Group FS、Service Proxy 等具备高层门面的能力以对应专项文档为准。`message.send`、`message.thought.put`、`group.send`、`group.thought.put` 的业务 payload 见 `09-payload-reference.md`。群组标识以 `group_aid` 为主，`group_id` 只作为兼容参数名，详见 `09-group-rpc-manual.md`。在线轻量通知和跨域 federation notify 方案见 `Notify通知方案.md`。
+业务 RPC 的底层参数见 `09-*-rpc-manual.md`，可通过 `client.call(method, params)` 调用；Storage、Collab、Group FS、Service Proxy 等具备高层门面的能力以对应专项文档为准。`message.send`、`message.thought.put`、`group.send`、`group.thought.put` 的业务 payload 见 `09-payload-reference.md`。群组标识以 `group_aid` 为主，`group_id` 只作为兼容参数名；`group.index` 的签名索引、`_meta.group_indexes` 观察和 `expected_index_etag` CAS 详见 `09-group-rpc-manual.md`。在线轻量通知和跨域 federation notify 方案见 `Notify通知方案.md`。
 
 Storage 的 SDK VFS、控制面/数据面分离、direct backend 上传下载、类 Linux 权限、mount/symlink 和服务端分层见 `AUN Storage架构设计.md`。
 Group FS 的 `group.fs.*` RPC、`client.group.fs.*` 门面、`aun group fs` CLI、`cp/mv` 语义、群自有区角色 ACL 授权/撤销/查询与 `group_aid` 签名、`parents` 语义、JS string 差异和 memberdata 服务端映射见 `09-group-rpc-manual.md`。Collab 的 `gc`、`reflog`、`revert`、`clone` 及版本化文档/标签语义见 `09-collab-rpc-manual.md`。
@@ -31,7 +31,8 @@ Group FS 的 `group.fs.*` RPC、`client.group.fs.*` 门面、`aun group fs` CLI
 - E2EE：默认加密、ProtectedHeaders、P2P / Group V2
 - RPC 与事件：`client.call()`、`client.on()`、`client.notify()`、RPC 手册
 - Storage：SDK VFS、direct backend 数据面、`storage.*` low-level RPC、类 Linux 权限、mount/symlink、Storage Service 分层
-- 群文件系统：`group.fs.*`、`client.group.fs.*`、`aun group fs`、`cp/mv` 上传下载、群自有区角色 ACL 与 `group_aid` 签名、`parents`、JS string 差异和 memberdata 服务端映射（见 `09-group-rpc-manual.md`）
+- Group RPC：`group_aid` / `group_id` 兼容、`group.index` 签名索引、`_meta.group_indexes`、`check/get/updateGroupIndex`、`expected_index_etag` CAS（见 `09-group-rpc-manual.md`、`06-API手册.md`）
+- 群文件系统：`group.fs.*`、`client.group.fs.*`、`aun group fs`、`cp/mv` 上传下载、群自有区角色 ACL 与 `group_aid` 签名、`parents`、JS string 差异和 memberdata 服务端映射（见 `09-group-rpc-manual.md`）
 - 协作（collab）：`collab.*` 版本化文档、乐观锁 CAS commit、三方合并、标签、GC、reflog、revert（见 `09-collab-rpc-manual.md`）
 - Service Proxy：`ServiceProxyClient`、`proxy.register_services`、proxy-server `register_services`
 - agent.md：`AIDStore.upload_agent_md()`、`AIDStore.download_agent_md()`、`AIDStore.check_agent_md()`、Gateway `_meta.agent_md_etags` 被动观察、`requester` / `peer` / `group` 角色
@@ -47,7 +48,7 @@ Group FS 的 `group.fs.*` RPC、`client.group.fs.*` 门面、`aun group fs` CLI
 |------|------|------|
 | 01 | [快速开始](01-快速开始.md) | 安装、三主体模型、最小示例 |
 | 02 | [WebSocket协议](02-WebSocket协议.md) | 握手流程、消息格式、裸 WebSocket |
-| 03 | [核心概念](03-核心概念.md) | AID、状态机、认证、E2EE |
+| 03 | [核心概念](03-核心概念.md) | AID、状态机、认证、E2EE、Group Index 观察模型 |
 | 04 | [连接与认证](04-连接与认证.md) | AIDStore、连接、网关发现、事件、agent.md 自动观察 |
 | 05 | [E2EE加密通信](05-E2EE加密通信.md) | E2EE V2、ProtectedHeaders、agent.md 版本提示、recipient wrap |
 | 06 | [API手册](06-API手册.md) | AIDStore / AID / AUNClient / agent.md / ServiceProxyClient / 事件 / RPC |
@@ -70,7 +71,8 @@ Group FS 的 `group.fs.*` RPC、`client.group.fs.*` 门面、`aun group fs` CLI
 | 查方法签名 | [06-API手册](06-API手册.md) |
 | 查消息或群组 RPC | 对应 `09-*-rpc-manual.md` |
 | 查群组标识 `group_aid` / `group_id` 兼容规范 | [09-group-rpc-manual.md](09-group-rpc-manual.md) |
-| 查群文件系统 RPC / SDK / CLI 入口、群自有区角色 ACL 授权/撤销/查询、`parents` 和 JS string 差异 | [09-group-rpc-manual.md](09-group-rpc-manual.md)、[06-API手册](06-API手册.md) |
+| 查 group.index 签名索引、版本观察、不同步判断、CAS 更新和 facade | [03-核心概念.md](03-核心概念.md)、[06-API手册.md](06-API手册.md)、[09-group-rpc-manual.md](09-group-rpc-manual.md)、[08-最佳实践.md](08-最佳实践.md) |
+| 查群文件系统 RPC / SDK / CLI 入口、群自有区角色 ACL 授权/撤销/查询、`parents` 和 JS string 差异 | [09-group-rpc-manual.md](09-group-rpc-manual.md)、[06-API手册](06-API手册.md) |
 | 查 Storage 架构、SDK VFS、权限模型、mount/symlink 和上传下载链路 | [AUN Storage架构设计.md](<AUN Storage架构设计.md>) |
 | 查 Storage RPC 参数 | [09-storage-rpc-manual.md](09-storage-rpc-manual.md) |
 | 查协作（版本化文档/乐观锁/标签/GC/reflog/revert）RPC | [09-collab-rpc-manual.md](09-collab-rpc-manual.md) |

package/_packed_docs/sdk/INDEX.md

@@ -10,16 +10,16 @@
 |------|------|
 | [01-快速开始](01-快速开始.md) | 安装 · 三主体模型 · 最小示例 · 多语言构造 |
 | [02-WebSocket协议](02-WebSocket协议.md) | 握手流程 · JSON-RPC 消息格式 · 裸 WebSocket 示例 |
-| [03-核心概念](03-核心概念.md) | AID · AIDStore · AUNClient · 九态状态机 · E2EE |
+| [03-核心概念](03-核心概念.md) | AID · AIDStore · AUNClient · 九态状态机 · E2EE · Group Index 观察模型 |
 | [04-连接与认证](04-连接与认证.md) | 注册加载 · 认证连接 · 网关发现 · 事件 · agent.md 自动观察 |
 | [05-E2EE加密通信](05-E2EE加密通信.md) | E2EE V2 消息 · ProtectedHeaders · agent.md 版本提示 · recipient wrap |
 | [E2EE_V2消息通信时序图](E2EE_V2消息通信时序图.md) | V2 P2P/GROUP 明文与加密主链路 |
 | [06-API手册](06-API手册.md) | AIDStore · AID · AUNClient · 事件 · agent.md · E2EE 高级 API · RPC 索引 |
 | [07-错误处理](07-错误处理.md) | Result · 错误类层级 · 错误码 · 重试 |
-| [08-最佳实践](08-最佳实践.md) | 幂等连接 · 多 AID · 资源清理 · 测试数据保护 |
+| [08-最佳实践](08-最佳实践.md) | 幂等连接 · 多 AID · 资源清理 · group.index 更新流程 · 测试数据保护 |
 | [09-payload-reference](09-payload-reference.md) | message / group / thought payload 格式 |
 | [09-message-rpc-manual](09-message-rpc-manual.md) | P2P 消息 RPC |
-| [09-group-rpc-manual](09-group-rpc-manual.md) | 群组 RPC（含 `group_aid` / `group_id` 兼容规范、`group.fs.*` 群文件系统 RPC、群自有区角色 ACL 授权/撤销/查询和 `parents` 语义） |
+| [09-group-rpc-manual](09-group-rpc-manual.md) | 群组 RPC（含 `group_aid` / `group_id` 兼容规范、`group.index` 签名索引与 CAS、`group.fs.*` 群文件系统 RPC、群自有区角色 ACL 授权/撤销/查询和 `parents` 语义） |
 | [09-storage-rpc-manual](09-storage-rpc-manual.md) | 存储 RPC（对象 + POSIX VFS / 卷 / 软链 / ACL / token） |
 | [09-collab-rpc-manual](09-collab-rpc-manual.md) | 协作 RPC（版本化文档 / 乐观锁 / 三方合并 / 标签 / GC / reflog / revert） |
 | [group.fs POSIX 化详细设计](../aun-fs/group-fs/group.fs-POSIX化详细设计.md) | `client.group.fs.*` / `aun group fs` / `group.fs.*` 群文件系统设计，含群自有区角色 ACL、`parents` 和 JS string 语义 |
@@ -64,7 +64,7 @@
 - `client.call()` / `client.on()` → [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)
 - `client.notify()` 在线轻量通知、跨域 federation、在线/离线边界 → [Notify通知方案](Notify通知方案.md)
 - Message RPC → [09-message-rpc-manual](09-message-rpc-manual.md)
-- Group RPC、`group_aid` / `group_id` 兼容规范、群文件系统 `group.fs.*` 控制面、群自有区角色 ACL 授权/撤销/查询和 `parents` 语义 → [09-group-rpc-manual](09-group-rpc-manual.md)
+- Group RPC、`group_aid` / `group_id` 兼容规范、`group.index` 签名索引、`_meta.group_indexes` 观察、`expected_index_etag` CAS、群文件系统 `group.fs.*` 控制面、群自有区角色 ACL 授权/撤销/查询和 `parents` 语义 → [09-group-rpc-manual](09-group-rpc-manual.md)
 - 下一版群文件系统 `group.fs.*`、`client.group.fs.*`、`aun group fs`、`cp/mv` POSIX 化语义和 JS string 差异 → [group.fs POSIX 化详细设计](../aun-fs/group-fs/group.fs-POSIX化详细设计.md)、[分阶段实施计划](../aun-fs/group-fs/group.fs-POSIX化分阶段实施计划.md)
 - Storage 架构、SDK VFS、控制面/数据面分离、类 Linux 权限和 mount/symlink → [AUN Storage架构设计](<AUN Storage架构设计.md>)
 - Storage RPC（对象 + `storage.fs.*` / `storage.volume.*` / `storage.fs.touch` / 软链 / ACL / token）→ [09-storage-rpc-manual](09-storage-rpc-manual.md)
@@ -93,9 +93,9 @@
 
 说明 Gateway WebSocket 握手、JSON-RPC 请求/响应/通知格式，以及裸 WebSocket 客户端如何借助 SDK 完成 token 获取。
 
-### 03-核心概念
-
-解释 AID 身份、三主体职责、device_id / slot_id 隔离键、九态状态机、认证挑战-响应、默认 E2EE 行为和 RPC/事件模型。
+### 03-核心概念
+
+解释 AID 身份、三主体职责、device_id / slot_id 隔离键、九态状态机、认证挑战-响应、默认 E2EE 行为、RPC/事件模型，以及 `group.index` 的 `_meta.group_indexes` 观察、不同步标记和应用层 pull/push 边界。
 
 ### 04-连接与认证
 
@@ -105,21 +105,21 @@
 
 覆盖默认加密发送、接收自动解密、E2EE V2 多设备 wrap、ProtectedHeaders、agent.md 版本提示与 E2EE 安全边界、`sender_signature` / AAD / recipient proof、群 E2EE 和高级存储扩展边界。
 
-### 06-API手册
-
-列出 AIDStore、AID、AUNClient、事件、agent.md、ServiceProxyClient、E2EE 高级 API 和 RPC 手册索引，包含 Python / TS / JS / Go 的主要命名差异。
-
-### 07-错误处理
-
-说明 Result 字典、AUNError 异常层级、错误码映射、重试策略和常见错误场景。
+### 06-API手册
+
+列出 AIDStore、AID、AUNClient、事件、agent.md、ServiceProxyClient、E2EE 高级 API、Group Index facade 和 RPC 手册索引，包含 Python / TS / JS / Go 的主要命名差异。
 
-### 08-最佳实践
+### 07-错误处理
+
+说明 Result 字典、AUNError 异常层级、错误码映射、重试策略、`group.index etag conflict` CAS 冲突处理和常见错误场景。
 
-给出幂等加载身份、连接、关闭、多 AID 管理、protected_headers、Flow Control 和测试数据保护建议。
+### 08-最佳实践
+
+给出幂等加载身份、连接、关闭、多 AID 管理、protected_headers、Flow Control、Group Index 更新流程和测试数据保护建议。
 
 ### 09-*-rpc-manual
 
-各业务服务的 RPC 参数、响应和错误语义。Storage、Collab、Group FS、Service Proxy 等明确提供高层门面的能力应优先使用门面；需要精确控制底层参数时再通过 `client.call()` 调用业务 RPC。
+各业务服务的 RPC 参数、响应和错误语义。Group RPC 覆盖 `group.index` 签名索引、`expected_index_etag` CAS 和 `_meta.group_indexes` 观察。Storage、Collab、Group FS、Service Proxy 等明确提供高层门面的能力应优先使用门面；需要精确控制底层参数时再通过 `client.call()` 调用业务 RPC。
 
 ### AUN Storage架构设计
 

package/dist/client/delivery.d.ts

@@ -27,6 +27,8 @@ export declare class MessageDeliveryEngine {
         event: string;
         payload: EventPayload;
     };
+    messageRecallDedupKey(payload: JsonObject): string;
+    publishMessageRecallTombstone(seq: unknown, message: EventPayload): Promise<boolean>;
     recallEventFromGroupMessage(message: EventPayload): JsonObject | null;
     groupRecallDedupKey(groupId: string, payload: JsonObject): string;
     publishGroupRecallTombstone(groupId: string, seq: unknown, message: EventPayload): Promise<boolean>;
@@ -40,7 +42,9 @@ export declare class MessageDeliveryEngine {
     }): void;
     logAppMessagePublish(event: string, payload: unknown, source: string): void;
     messageTargetsCurrentInstance(message: EventPayload): boolean;
+    runPushProcessSerialized(ns: string, operation: () => Promise<void>): Promise<void>;
     onRawMessageReceived(data: EventPayload): Promise<void>;
+    onRawMessageRecalled(data: EventPayload): Promise<void>;
     processAndPublishMessage(data: EventPayload): Promise<void>;
     onRawGroupMessageCreated(data: EventPayload): Promise<void>;
     processAndPublishGroupMessage(data: EventPayload): Promise<void>;

package/dist/client/delivery.js

@@ -3,6 +3,7 @@ import { normalizeGroupId } from '../group-id.js';
 import { ConnectionState, isJsonObject } from '../types.js';
 const PUSHED_SEQS_LIMIT = 50_000;
 const PENDING_ORDERED_LIMIT = 50_000;
+const MESSAGE_RECALL_SEEN_LIMIT = 10_000;
 const GROUP_RECALL_SEEN_LIMIT = 10_000;
 const SEQ_TRACKER_PERSIST_FLUSH_DELAY_MS = 200;
 const APP_MESSAGE_ENVELOPE_KEYS = [
@@ -11,6 +12,13 @@ const APP_MESSAGE_ENVELOPE_KEYS = [
     'timestamp', 'created_at', 'encrypted',
     'context', 'protected_headers', 'headers', 'payload_type',
 ];
+const RECALL_PAYLOAD_KEYS = [
+    'message_ids', 'target_message_seqs',
+    'recalled_message_id', 'target_message_id', 'original_message_id',
+    'target_seq', 'original_seq',
+    'notice_message_id', 'notice_seq', 'event_seq',
+    'sender_aid', 'recalled_by', 'recalled_at', 'reason',
+];
 const APP_SEND_ENVELOPE_METHODS = new Set([
     'message.send',
     'group.send',
@@ -79,6 +87,10 @@ export class MessageDeliveryEngine {
             await this.publishOrderedGroupChanged(payload, source);
             return;
         }
+        if (event === 'message.recalled') {
+            await this.publishMessageRecallTombstone(seq, payload);
+            return;
+        }
         if (pullResponse) {
             const published = client._withPullResponseProcessing(ns, () => client._publishAppEvent(event, payload, source));
             if (isPromiseLike(published))
@@ -308,6 +320,11 @@ export class MessageDeliveryEngine {
                 event[key] = msg[key];
             }
         }
+        for (const key of RECALL_PAYLOAD_KEYS) {
+            if (Object.prototype.hasOwnProperty.call(msg, key) && !(key in event)) {
+                event[key] = msg[key];
+            }
+        }
         const rawIds = event.message_ids;
         let messageIds = Array.isArray(rawIds)
             ? rawIds.map((item) => String(item ?? '').trim()).filter(Boolean)
@@ -349,6 +366,57 @@ export class MessageDeliveryEngine {
             return { event: 'message.recalled', payload: recall };
         return { event: 'message.received', payload: message };
     }
+    messageRecallDedupKey(payload) {
+        const ids = payload.message_ids;
+        const idPart = Array.isArray(ids)
+            ? ids.map((i) => String(i ?? '').trim()).filter(Boolean).sort().join(',')
+            : String(ids ?? '').trim();
+        if (idPart)
+            return `p2p|id:${idPart}`;
+        for (const key of ['recalled_message_id', 'target_message_id', 'original_message_id']) {
+            const value = String(payload[key] ?? '').trim();
+            if (value)
+                return `p2p|id:${value}`;
+        }
+        const rawSeqs = payload.target_message_seqs;
+        const seqPart = Array.isArray(rawSeqs)
+            ? rawSeqs.map((seq) => String(seq ?? '').trim()).filter(Boolean).sort().join(',')
+            : String(rawSeqs ?? payload.target_seq ?? payload.original_seq ?? '').trim();
+        if (seqPart) {
+            const fromAid = String(payload.from ?? payload.from_aid ?? payload.sender_aid ?? '').trim();
+            const toAid = String(payload.to ?? payload.to_aid ?? '').trim();
+            return `p2p|from:${fromAid}|to:${toAid}|seq:${seqPart}`;
+        }
+        const tombstoneId = String(payload.tombstone_message_id ?? payload.message_id ?? '').trim();
+        if (tombstoneId)
+            return `p2p|tombstone:${tombstoneId}`;
+        return `p2p|unknown:${Date.now()}:${Math.random()}`;
+    }
+    async publishMessageRecallTombstone(seq, message) {
+        const client = this.runtime.client;
+        const eventPayload = this.recallEventFromMessage(message);
+        if (!eventPayload)
+            return false;
+        const dedupKey = this.messageRecallDedupKey(eventPayload);
+        let seen = client._messageRecallSeen;
+        if (!seen) {
+            seen = new Map();
+            client._messageRecallSeen = seen;
+        }
+        if (seen.has(dedupKey)) {
+            client._clientLog.debug(`message.recalled dedup suppressed: seq=${String(seq)} key=${dedupKey}`);
+            return false;
+        }
+        seen.set(dedupKey, Date.now());
+        if (seen.size > MESSAGE_RECALL_SEEN_LIMIT) {
+            const drop = [...seen.entries()].sort((a, b) => a[1] - b[1]).slice(0, seen.size - MESSAGE_RECALL_SEEN_LIMIT);
+            for (const [oldKey] of drop)
+                seen.delete(oldKey);
+        }
+        await client._publishAppEvent('message.recalled', eventPayload, 'message-recall');
+        client._clientLog.debug(`message.recalled published: seq=${String(seq)} ids=${JSON.stringify(eventPayload.message_ids)}`);
+        return true;
+    }
     recallEventFromGroupMessage(message) {
         if (!isJsonObject(message))
             return null;
@@ -365,6 +433,11 @@ export class MessageDeliveryEngine {
                 event[key] = msg[key];
             }
         }
+        for (const key of RECALL_PAYLOAD_KEYS) {
+            if (Object.prototype.hasOwnProperty.call(msg, key) && !(key in event)) {
+                event[key] = msg[key];
+            }
+        }
         const rawIds = event.message_ids;
         let messageIds = Array.isArray(rawIds)
             ? rawIds.map((item) => String(item ?? '').trim()).filter(Boolean)
@@ -395,9 +468,9 @@ export class MessageDeliveryEngine {
         return event;
     }
     groupRecallDedupKey(groupId, payload) {
-        // 群撤回去重键：group_id + 排序后的 message_ids。
+        // 群撤回去重键：group_id + 原始消息标识。
         // 一条消息只能被撤回一次（服务端 group_message_recalls uk_recall_msg_id 唯一约束），
-        // (group_id, sorted message_ids) 已能唯一标识一次撤回。
+        // (group_id, sorted message_ids) 已能唯一标识一次撤回；缺 message_ids 时按原消息 id/seq 兜底。
         // 去重键不含 recalled_at：占位/通知 tombstone（pull，事务内时间）与在线 push（事务后重取时间）
         // 三条通道对同一次撤回可能携带不同来源的时间戳，纳入 recalled_at 会使去重失效、回调多次。
         // group_id 归一化一次，使去重键与来源无关（pull 用 normalizeGroupId，push 可能是原始值）。
@@ -405,15 +478,35 @@ export class MessageDeliveryEngine {
         const ids = payload.message_ids;
         const idPart = Array.isArray(ids)
             ? ids.map((i) => String(i ?? '').trim()).filter(Boolean).sort().join(',')
-            : String(ids ?? '');
-        return `${normalizedGroupId}|${idPart}`;
+            : String(ids ?? '').trim();
+        if (idPart)
+            return `${normalizedGroupId}|id:${idPart}`;
+        for (const key of ['recalled_message_id', 'target_message_id', 'original_message_id']) {
+            const value = String(payload[key] ?? '').trim();
+            if (value)
+                return `${normalizedGroupId}|id:${value}`;
+        }
+        const rawSeqs = payload.target_message_seqs;
+        const seqPart = Array.isArray(rawSeqs)
+            ? rawSeqs.map((seq) => String(seq ?? '').trim()).filter(Boolean).sort().join(',')
+            : String(rawSeqs ?? payload.original_seq ?? '').trim();
+        if (seqPart)
+            return `${normalizedGroupId}|seq:${seqPart}`;
+        const tombstoneId = String(payload.tombstone_message_id ?? payload.message_id ?? '').trim();
+        if (tombstoneId)
+            return `${normalizedGroupId}|tombstone:${tombstoneId}`;
+        return `${normalizedGroupId}|unknown:${Date.now()}:${Math.random()}`;
     }
     async publishGroupRecallTombstone(groupId, seq, message) {
         const client = this.runtime.client;
         const eventPayload = this.recallEventFromGroupMessage(message);
         if (!eventPayload)
             return false;
-        const dedupKey = this.groupRecallDedupKey(groupId, eventPayload);
+        const rawGroupId = String(eventPayload.group_id ?? groupId ?? '').trim();
+        const dedupGroupId = normalizeGroupId(rawGroupId) || rawGroupId;
+        if (dedupGroupId)
+            eventPayload.group_id = dedupGroupId;
+        const dedupKey = this.groupRecallDedupKey(dedupGroupId, eventPayload);
         let seen = client._groupRecallSeen;
         if (!seen) {
             seen = new Map();
@@ -605,6 +698,29 @@ export class MessageDeliveryEngine {
         }
         return true;
     }
+    async runPushProcessSerialized(ns, operation) {
+        const client = this.runtime.client;
+        if (!ns) {
+            await operation();
+            return;
+        }
+        let queues = client._pushProcessQueues;
+        if (!queues) {
+            queues = new Map();
+            client._pushProcessQueues = queues;
+        }
+        const previous = queues.get(ns) ?? Promise.resolve();
+        const current = previous.catch(() => undefined).then(operation);
+        const stored = current.then(() => undefined, () => undefined);
+        queues.set(ns, stored);
+        try {
+            await current;
+        }
+        finally {
+            if (queues.get(ns) === stored)
+                queues.delete(ns);
+        }
+    }
     async onRawMessageReceived(data) {
         const client = this.runtime.client;
         const tStart = Date.now();
@@ -615,7 +731,10 @@ export class MessageDeliveryEngine {
         else {
             client._clientLog.debug('_onRawMessageReceived enter: non-object payload');
         }
-        this.processAndPublishMessage(data).catch((exc) => {
+        const ns = isJsonObject(data) && client._aid && data.seq !== undefined
+            ? `p2p:${client._aid}`
+            : '';
+        this.runPushProcessSerialized(ns, () => this.processAndPublishMessage(data)).catch((exc) => {
             client._clientLog.warn(`P2P message decrypt failed: ${formatDeliveryError(exc)}`);
             if (isJsonObject(data)) {
                 const src = data;
@@ -633,6 +752,39 @@ export class MessageDeliveryEngine {
         });
         client._clientLog.debug(`_onRawMessageReceived exit: elapsed=${Date.now() - tStart}ms (handler dispatched)`);
     }
+    async onRawMessageRecalled(data) {
+        const client = this.runtime.client;
+        if (!isJsonObject(data))
+            return;
+        const msg = { ...data };
+        if (!('type' in msg))
+            msg.type = 'message.recalled';
+        if (!this.messageTargetsCurrentInstance(msg))
+            return;
+        const seq = msg.seq;
+        if (seq !== undefined && seq !== null && client._aid) {
+            const ns = `p2p:${client._aid}`;
+            const seqNum = Number(seq);
+            if (Number.isFinite(seqNum) && seqNum > 0)
+                client._seqTracker.updateMaxSeen(ns, seqNum);
+            const contigBefore = client._seqTracker.getContiguousSeq(ns);
+            const published = await this.publishOrderedMessage('message.recalled', ns, seq, msg);
+            const contigAfter = client._seqTracker.getContiguousSeq(ns);
+            if (Number(seq) > contigAfter && !published) {
+                this.fillP2pGap().catch((exc) => client._clientLog.warn(`background recall gap fill failed: ${formatDeliveryError(exc)}`));
+            }
+            const contig = client._seqTracker.getContiguousSeq(ns);
+            if (contig > 0) {
+                const ackSeq = this.clampAckSeq('message.ack', 'seq', ns, contig);
+                client._withBackgroundRpc(() => client._ackV2(ackSeq))
+                    .catch((e) => { client._clientLog.debug(`P2P recall auto-ack failed: ${formatDeliveryError(e)}`); });
+            }
+            if (contigAfter !== contigBefore)
+                this.persistSeq(ns);
+            return;
+        }
+        await this.publishMessageRecallTombstone(seq, msg);
+    }
     async processAndPublishMessage(data) {
         const client = this.runtime.client;
         if (!isJsonObject(data)) {
@@ -692,7 +844,10 @@ export class MessageDeliveryEngine {
         else {
             client._clientLog.debug('_onRawGroupMessageCreated enter: non-object payload');
         }
-        this.processAndPublishGroupMessage(data).catch((exc) => {
+        const groupNs = isJsonObject(data)
+            ? String(data.group_id ?? '').trim()
+            : '';
+        this.runPushProcessSerialized(groupNs ? `group:${groupNs}` : '', () => this.processAndPublishGroupMessage(data)).catch((exc) => {
             client._clientLog.warn(`group message decrypt failed: ${formatDeliveryError(exc)}`);
             if (isJsonObject(data)) {
                 const src = data;
@@ -1720,6 +1875,9 @@ export class MessageDeliveryEngine {
         const seqNum = Number(seq);
         if (!Number.isFinite(seqNum) || !Number.isInteger(seqNum) || seqNum <= 0 || !ns) {
             client._clientLog.debug(`publish pulled direct(no-seq): event=${event}, ns=${ns || '<none>'}, seq=${String(seq)}`);
+            if (event === 'message.recalled') {
+                return this.publishMessageRecallTombstone(seq, payload);
+            }
             const published = client._withPullResponseProcessing(ns, () => client._publishAppEvent(event, payload, 'pull'));
             if (isPromiseLike(published))
                 await published;
@@ -1733,15 +1891,22 @@ export class MessageDeliveryEngine {
                 client._pendingOrderedMsgs.delete(ns);
             return false;
         }
+        await this.drainOrderedMessages(ns, seqNum, true);
         queue?.delete(seqNum);
         if (queue && queue.size === 0)
             client._pendingOrderedMsgs.delete(ns);
+        if (event === 'message.recalled') {
+            const recallPublished = await this.publishMessageRecallTombstone(seqNum, payload);
+            this.markPublishedSeq(ns, seqNum);
+            client._markPulledSeqDelivered(ns, seqNum);
+            client._clientLog.debug(`publish pulled delivered: event=${event}, ns=${ns}, seq=${seqNum}`);
+            return recallPublished;
+        }
         const published = client._withPullResponseProcessing(ns, () => client._publishAppEvent(event, payload, 'pull'));
         if (isPromiseLike(published))
             await published;
         this.markPublishedSeq(ns, seqNum);
         client._markPulledSeqDelivered(ns, seqNum);
-        await this.drainOrderedMessages(ns, undefined, true);
         client._clientLog.debug(`publish pulled delivered: event=${event}, ns=${ns}, seq=${seqNum}`);
         return true;
     }