@agentunion/fastaun-browser 0.5.2 → 0.5.3

package/dist/bundle.js

@@ -460,7 +460,7 @@ var init_indexeddb_store = __esm({
 });
 
 // src/version.ts
-var VERSION = "0.5.2";
+var VERSION = "0.5.3";
 
 // src/types.ts
 var ConnectionState = /* @__PURE__ */ ((ConnectionState2) => {
@@ -1918,10 +1918,11 @@ var STORE_METADATA = "metadata";
 var STORE_INSTANCE_STATE = "instance_state";
 var STORE_GROUP_STATE = "group_state";
 var STORE_AGENT_MD_CACHE = "agent_md_cache";
+var STORE_GROUP_INDEX_CACHE = "group_index_cache";
 var STORE_PENDING_IDENTITIES = "pending_identities";
 var STORE_PENDING_BINDS = "pending_binds";
 var DB_NAME = "aun-keystore";
-var DB_VERSION = 8;
+var DB_VERSION = 9;
 function safeAid(aid) {
   return aid.replace(/[/\\:]/g, "_");
 }
@@ -1986,6 +1987,12 @@ function agentMdCachePrefix(ownerAid) {
 function agentMdCacheStoreKey(ownerAid, targetAid) {
   return `${agentMdCachePrefix(ownerAid)}${encodePart(targetAid)}`;
 }
+function groupIndexCachePrefix(localAid) {
+  return `${safeAid(localAid)}|`;
+}
+function groupIndexCacheStoreKey(localAid, groupAid) {
+  return `${groupIndexCachePrefix(localAid)}${encodePart(groupAid)}`;
+}
 function pendingIdentityPrefix(aid) {
   return `${safeAid(aid)}-`;
 }
@@ -2039,6 +2046,59 @@ function mergeAgentMdCacheRecord(aid, current, fields) {
   out.updated_at = Date.now();
   return out;
 }
+function defaultGroupIndexCacheRecord(localAid, groupAid) {
+  return {
+    local_aid: localAid,
+    group_aid: groupAid,
+    index_jsonl: "",
+    remote_meta: {},
+    local_etag: "",
+    settings: {},
+    entry_etags: {},
+    updated_at: 0
+  };
+}
+function normalizeGroupIndexCacheRecord(localAid, groupAid, value) {
+  if (!isRecord(value)) return null;
+  const out = defaultGroupIndexCacheRecord(localAid, groupAid);
+  out.local_aid = String(value.local_aid ?? localAid).trim() || localAid;
+  out.group_aid = String(value.group_aid ?? groupAid).trim() || groupAid;
+  out.index_jsonl = String(value.index_jsonl ?? "");
+  out.local_etag = String(value.local_etag ?? "");
+  out.remote_meta = isRecord(value.remote_meta) ? deepClone(value.remote_meta) : {};
+  out.settings = isRecord(value.settings) ? deepClone(value.settings) : {};
+  if (isRecord(value.entry_etags)) {
+    out.entry_etags = Object.fromEntries(Object.entries(value.entry_etags).map(([key, etag]) => [key, String(etag ?? "")]));
+  }
+  const updatedAt = Number(value.updated_at ?? 0);
+  out.updated_at = Number.isFinite(updatedAt) ? Math.trunc(updatedAt) : 0;
+  return out;
+}
+function mergeGroupIndexCacheRecord(localAid, groupAid, current, fields) {
+  const out = current ? deepClone(current) : defaultGroupIndexCacheRecord(localAid, groupAid);
+  out.local_aid = localAid;
+  out.group_aid = groupAid;
+  if (Object.prototype.hasOwnProperty.call(fields, "index_jsonl") && fields.index_jsonl !== void 0 && fields.index_jsonl !== null) {
+    out.index_jsonl = String(fields.index_jsonl ?? "");
+  }
+  if (Object.prototype.hasOwnProperty.call(fields, "local_etag") && fields.local_etag !== void 0 && fields.local_etag !== null) {
+    out.local_etag = String(fields.local_etag ?? "");
+  }
+  if (isRecord(fields.remote_meta)) {
+    out.remote_meta = { ...out.remote_meta, ...deepClone(fields.remote_meta) };
+  }
+  if (isRecord(fields.settings)) {
+    out.settings = { ...out.settings, ...deepClone(fields.settings) };
+  }
+  if (isRecord(fields.entry_etags)) {
+    out.entry_etags = {
+      ...out.entry_etags,
+      ...Object.fromEntries(Object.entries(fields.entry_etags).map(([key, etag]) => [key, String(etag ?? "")]))
+    };
+  }
+  out.updated_at = Date.now();
+  return out;
+}
 var _ENC_ALGO = "AES-GCM";
 var _PBKDF2_ITERATIONS = 1e5;
 function _uint8ToBase64(bytes) {
@@ -2098,6 +2158,7 @@ function openDB() {
         STORE_INSTANCE_STATE,
         STORE_GROUP_STATE,
         STORE_AGENT_MD_CACHE,
+        STORE_GROUP_INDEX_CACHE,
         STORE_PENDING_IDENTITIES,
         STORE_PENDING_BINDS
       ]) {
@@ -2987,6 +3048,26 @@ var _IndexedDBTokenStore = class _IndexedDBTokenStore {
     }
     return [...aids].sort();
   }
+  // ── group.index Cache ───────────────────────────────────
+  async loadGroupIndexCache(localAid, groupAid) {
+    const local = String(localAid ?? "").trim();
+    const group = String(groupAid ?? "").trim();
+    if (!local || !group) return null;
+    const data = await idbGet(STORE_GROUP_INDEX_CACHE, groupIndexCacheStoreKey(local, group));
+    const record = normalizeGroupIndexCacheRecord(local, group, data);
+    return record ? deepClone(record) : null;
+  }
+  async upsertGroupIndexCache(localAid, groupAid, fields) {
+    const local = String(localAid ?? "").trim();
+    const group = String(groupAid ?? "").trim();
+    if (!local || !group) {
+      throw new Error("upsertGroupIndexCache requires localAid and groupAid");
+    }
+    const current = await this.loadGroupIndexCache(local, group);
+    const record = mergeGroupIndexCacheRecord(local, group, current, fields ?? {});
+    await idbPut(STORE_GROUP_INDEX_CACHE, groupIndexCacheStoreKey(local, group), record);
+    return deepClone(record);
+  }
   // ── Group State（群组状态快照） ─────────────────────────────
   async saveGroupState(groupId, state) {
     const key = encodePart(groupId);
@@ -6293,6 +6374,16 @@ var RPCTransport = class {
   setMetaObserver(observer) {
     this._metaObserver = observer;
   }
+  async _notifyMetaObserver(message) {
+    if (this._metaObserver === null) return;
+    const meta = message._meta;
+    if (!isJsonObject(meta)) return;
+    try {
+      await this._metaObserver(meta);
+    } catch (exc) {
+      this._log.debug(`meta_observer raised: ${String(exc)}`);
+    }
+  }
   /** 设置 trace 模式：off / log / diag */
   setTraceMode(mode) {
     if (mode !== "off" && mode !== "log" && mode !== "diag") {
@@ -6487,7 +6578,7 @@ var RPCTransport = class {
         this._drainRpcQueue();
       }, effectiveTimeout);
       const pending = {
-        resolve: (response) => {
+        resolve: async (response) => {
           clearTimeout(timer);
           const elapsed = Date.now() - tStart;
           if (response.error !== void 0) {
@@ -6505,16 +6596,7 @@ var RPCTransport = class {
             if (traceId) {
               this._log.info(`[trace=${traceId}] rpc_recv method=${method} rpc_id=${rpcId} duration_ms=${elapsed} status=ok`);
             }
-            if (this._metaObserver !== null) {
-              const meta = response._meta;
-              if (isJsonObject(meta)) {
-                try {
-                  this._metaObserver(meta);
-                } catch (exc) {
-                  this._log.debug(`meta_observer raised: ${String(exc)}`);
-                }
-              }
-            }
+            await this._notifyMetaObserver(response);
             const respTrace = response._trace;
             if (respTrace && typeof respTrace === "object" && !Array.isArray(respTrace)) {
               this._handleResponseTrace(method, "ok", elapsed, respTrace);
@@ -6796,14 +6878,7 @@ var RPCTransport = class {
       const protocolEvent = method.slice(6);
       const sdkEvent = EVENT_NAME_MAP[protocolEvent] ?? protocolEvent;
       this._log.debug(`event recv: event=${sdkEvent} ${summarizeDict(message.params, DIAG_RESULT_FIELDS)}`);
-      const meta2 = message._meta;
-      if (this._metaObserver !== null && isJsonObject(meta2)) {
-        try {
-          this._metaObserver(meta2);
-        } catch (exc) {
-          this._log.debug(`event meta_observer raised: ${String(exc)}`);
-        }
-      }
+      void this._notifyMetaObserver(message);
       const params2 = message.params ?? {};
       if ("_trace" in params2) {
         const eventTrace = params2._trace;
@@ -6826,14 +6901,7 @@ var RPCTransport = class {
       this._dispatcher.publish(`_raw.${sdkEvent}`, params2);
       return;
     }
-    const meta = message._meta;
-    if (this._metaObserver !== null && isJsonObject(meta)) {
-      try {
-        this._metaObserver(meta);
-      } catch (exc) {
-        this._log.debug(`notification meta_observer raised: ${String(exc)}`);
-      }
-    }
+    void this._notifyMetaObserver(message);
     this._log.debug(`notification recv: method=${method || "<no-method>"}`);
     this._dispatcher.publish("notification", message);
   }
@@ -7377,6 +7445,7 @@ var ClientRuntime = class {
 // src/client/delivery.ts
 var PUSHED_SEQS_LIMIT = 5e4;
 var PENDING_ORDERED_LIMIT = 5e4;
+var MESSAGE_RECALL_SEEN_LIMIT = 1e4;
 var GROUP_RECALL_SEEN_LIMIT = 1e4;
 var SEQ_TRACKER_PERSIST_FLUSH_DELAY_MS = 200;
 var P2P_GAP_FILL_RETRY_LIMIT = 12;
@@ -7402,6 +7471,22 @@ var APP_MESSAGE_ENVELOPE_KEYS = [
   "headers",
   "payload_type"
 ];
+var 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"
+];
 var APP_SEND_ENVELOPE_METHODS = /* @__PURE__ */ new Set([
   "message.send",
   "group.send",
@@ -7524,6 +7609,10 @@ var MessageDeliveryEngine = class {
       await this.publishOrderedGroupChanged(payload);
       return;
     }
+    if (event === "message.recalled") {
+      await this.publishMessageRecallTombstone(seq, payload);
+      return;
+    }
     await client._publishAppEvent(event, payload);
   }
   async publishOrderedGroupChanged(payload) {
@@ -7704,6 +7793,11 @@ var MessageDeliveryEngine = class {
         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) : [];
     if (messageIds.length === 0) {
@@ -7735,6 +7829,48 @@ var MessageDeliveryEngine = class {
     if (recall) 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 = /* @__PURE__ */ 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);
+    client._clientLog.debug(`message.recalled published: seq=${String(seq)} ids=${JSON.stringify(eventPayload.message_ids)}`);
+    return true;
+  }
   recallEventFromGroupMessage(message) {
     if (!isJsonObject(message)) return null;
     const msg = message;
@@ -7749,6 +7885,11 @@ var MessageDeliveryEngine = class {
         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) : [];
     if (messageIds.length === 0) {
@@ -7773,15 +7914,29 @@ var MessageDeliveryEngine = class {
     return event;
   }
   groupRecallDedupKey(groupId, payload) {
+    const normalizedGroupId2 = normalizeGroupId(groupId) || String(groupId ?? "").trim();
     const ids = payload.message_ids;
-    const idPart = Array.isArray(ids) ? ids.map((i) => String(i ?? "").trim()).filter(Boolean).sort().join(",") : String(ids ?? "");
-    return `${groupId}|${idPart}`;
+    const idPart = Array.isArray(ids) ? ids.map((i) => String(i ?? "").trim()).filter(Boolean).sort().join(",") : String(ids ?? "").trim();
+    if (idPart) return `${normalizedGroupId2}|id:${idPart}`;
+    for (const key of ["recalled_message_id", "target_message_id", "original_message_id"]) {
+      const value = String(payload[key] ?? "").trim();
+      if (value) return `${normalizedGroupId2}|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 `${normalizedGroupId2}|seq:${seqPart}`;
+    const tombstoneId = String(payload.tombstone_message_id ?? payload.message_id ?? "").trim();
+    if (tombstoneId) return `${normalizedGroupId2}|tombstone:${tombstoneId}`;
+    return `${normalizedGroupId2}|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 = /* @__PURE__ */ new Map();
@@ -7898,12 +8053,68 @@ var MessageDeliveryEngine = class {
     }
     return true;
   }
+  async runPushProcessSerialized(ns, operation) {
+    const client = this.runtime.client;
+    if (!ns) {
+      await operation();
+      return;
+    }
+    let queues = client._pushProcessQueues;
+    if (!queues) {
+      queues = /* @__PURE__ */ new Map();
+      client._pushProcessQueues = queues;
+    }
+    const previous = queues.get(ns) ?? Promise.resolve();
+    const current = previous.catch(() => void 0).then(operation);
+    const stored = current.then(() => void 0, () => void 0);
+    queues.set(ns, stored);
+    try {
+      await current;
+    } finally {
+      if (queues.get(ns) === stored) queues.delete(ns);
+    }
+  }
   onRawMessageReceived(data) {
     const client = this.runtime.client;
     client._clientLog.debug(`_onRawMessageReceived enter: from=${data?.from ?? "-"} mid=${data?.message_id ?? "-"} seq=${data?.seq ?? "-"}`);
-    client._safeAsync(this.processAndPublishMessage(data));
+    const ns = isJsonObject(data) && client._aid && data.seq !== void 0 ? `p2p:${client._aid}` : "";
+    client._safeAsync(this.runPushProcessSerialized(ns, () => this.processAndPublishMessage(data)));
     client._clientLog.debug("_onRawMessageReceived exit: elapsed=0ms (dispatched async)");
   }
+  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 !== void 0 && seq !== null && client._aid) {
+      const ns = `p2p:${client._aid}`;
+      if (seq > 0) client._seqTracker.updateMaxSeen(ns, seq);
+      const contigBefore = client._seqTracker.getContiguousSeq(ns);
+      const seqNeedsPull = client._seqTracker.onMessageSeq(ns, seq);
+      const published = await this.publishOrderedMessage("message.recalled", ns, seq, msg);
+      const contigAfter = client._seqTracker.getContiguousSeq(ns);
+      if (seqNeedsPull && !published) {
+        client._safeAsync(this.fillP2pGap());
+      }
+      const contig = client._seqTracker.getContiguousSeq(ns);
+      if (contig > 0) {
+        const ackSeq = this.clampAckSeq("message.ack", "seq", ns, contig);
+        client._transport.call("message.ack", {
+          seq: ackSeq,
+          device_id: client._deviceId,
+          slot_id: client._slotId,
+          _rpc_background: true
+        }).catch((e) => {
+          client._clientLog.warn(`P2P recall auto-ack failed:${String(e)}`);
+        });
+      }
+      if (contigAfter !== contigBefore) this.persistSeq(ns);
+      return;
+    }
+    await this.publishMessageRecallTombstone(seq, msg);
+  }
   async processAndPublishMessage(data) {
     const client = this.runtime.client;
     try {
@@ -7969,7 +8180,8 @@ var MessageDeliveryEngine = class {
   onRawGroupMessageCreated(data) {
     const client = this.runtime.client;
     client._clientLog.debug(`_onRawGroupMessageCreated enter: group_id=${data?.group_id ?? "-"} from=${data?.from ?? "-"} seq=${data?.seq ?? "-"}`);
-    client._safeAsync(this.processAndPublishGroupMessage(data));
+    const groupId = isJsonObject(data) ? String(data.group_id ?? "").trim() : "";
+    client._safeAsync(this.runPushProcessSerialized(groupId ? `group:${groupId}` : "", () => this.processAndPublishGroupMessage(data)));
     client._clientLog.debug("_onRawGroupMessageCreated exit: elapsed=0ms (dispatched async)");
   }
   async processAndPublishGroupMessage(data) {
@@ -8926,6 +9138,9 @@ var MessageDeliveryEngine = class {
     const client = this.runtime.client;
     const seqNum = Number(seq);
     if (!Number.isFinite(seqNum) || !Number.isInteger(seqNum) || seqNum <= 0 || !ns) {
+      if (event === "message.recalled") {
+        return this.publishMessageRecallTombstone(seq, payload);
+      }
       await client._publishAppEvent(event, payload);
       return true;
     }
@@ -8935,8 +9150,14 @@ var MessageDeliveryEngine = class {
       if (queue && queue.size === 0) client._pendingOrderedMsgs.delete(ns);
       return false;
     }
+    await this.drainOrderedMessages(ns, seqNum);
     queue?.delete(seqNum);
     if (queue && queue.size === 0) client._pendingOrderedMsgs.delete(ns);
+    if (event === "message.recalled") {
+      const published = await this.publishMessageRecallTombstone(seqNum, payload);
+      this.markPublishedSeq(ns, seqNum);
+      return published;
+    }
     await client._publishAppEvent(event, payload);
     this.markPublishedSeq(ns, seqNum);
     return true;
@@ -11098,6 +11319,346 @@ var GroupFSVFS = class {
   }
 };
 
+// src/v2/crypto/canonical.ts
+var encoder = new TextEncoder();
+var MAX_SAFE_JSON_INTEGER = 9007199254740991;
+function canonicalJson(obj) {
+  return encoder.encode(serialize(obj));
+}
+function serialize(obj) {
+  if (obj === null) return "null";
+  if (obj === true) return "true";
+  if (obj === false) return "false";
+  if (typeof obj === "number") {
+    return serializeNumber(obj);
+  }
+  if (typeof obj === "string") {
+    return serializeString(obj);
+  }
+  if (Array.isArray(obj)) {
+    return serializeArray(obj);
+  }
+  if (typeof obj === "object") {
+    return serializeObject(obj);
+  }
+  throw new TypeError(`canonicalJson: unsupported type ${typeof obj}`);
+}
+function serializeNumber(n) {
+  if (!isFinite(n)) {
+    throw new RangeError("canonicalJson: Infinity and NaN not allowed");
+  }
+  if (Object.is(n, -0)) return "0";
+  if (Number.isInteger(n)) {
+    if (Math.abs(n) > MAX_SAFE_JSON_INTEGER) {
+      throw new RangeError(`canonicalJson: integer outside safe range ${n}`);
+    }
+    return String(n);
+  }
+  return expandExponent(String(n));
+}
+function expandExponent(s) {
+  if (!/[eE]/.test(s)) return s;
+  const match = /^(-?)(\d+)(?:\.(\d+))?[eE]([+-]?\d+)$/.exec(s);
+  if (!match) {
+    throw new TypeError(`canonicalJson: invalid number ${s}`);
+  }
+  const sign = match[1] ?? "";
+  const intPart = match[2] ?? "";
+  const fracPart = match[3] ?? "";
+  const exp = Number(match[4]);
+  const digits = intPart + fracPart;
+  const point = intPart.length + exp;
+  if (point <= 0) {
+    return `${sign}0.${"0".repeat(-point)}${digits}`;
+  }
+  if (point >= digits.length) {
+    return `${sign}${digits}${"0".repeat(point - digits.length)}`;
+  }
+  return `${sign}${digits.slice(0, point)}.${digits.slice(point)}`;
+}
+function serializeString(s) {
+  let result = '"';
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    const code = s.charCodeAt(i);
+    if (ch === '"') {
+      result += '\\"';
+    } else if (ch === "\\") {
+      result += "\\\\";
+    } else if (ch === "\b") {
+      result += "\\b";
+    } else if (ch === "\f") {
+      result += "\\f";
+    } else if (ch === "\n") {
+      result += "\\n";
+    } else if (ch === "\r") {
+      result += "\\r";
+    } else if (ch === "	") {
+      result += "\\t";
+    } else if (code < 32) {
+      result += "\\u" + code.toString(16).padStart(4, "0");
+    } else {
+      result += ch;
+    }
+  }
+  result += '"';
+  return result;
+}
+function serializeArray(arr) {
+  const items = arr.map((item) => serialize(item));
+  return "[" + items.join(",") + "]";
+}
+function serializeObject(obj) {
+  const sortedKeys = Object.keys(obj).sort(compareCodePoints);
+  const pairs = sortedKeys.map(
+    (key) => serializeString(key) + ":" + serialize(obj[key])
+  );
+  return "{" + pairs.join(",") + "}";
+}
+function compareCodePoints(a, b) {
+  const ac = Array.from(a);
+  const bc = Array.from(b);
+  const n = Math.min(ac.length, bc.length);
+  for (let i = 0; i < n; i++) {
+    const av = ac[i].codePointAt(0) ?? 0;
+    const bv = bc[i].codePointAt(0) ?? 0;
+    if (av !== bv) return av - bv;
+  }
+  return ac.length - bc.length;
+}
+
+// src/group-index.ts
+var GROUP_INDEX_SCHEMA = "aun.group.index.v1";
+var GROUP_INDEX_KEY = "group.index";
+var GROUP_INDEX_SIG_ALG = "ECDSA-P256-SHA256";
+var GroupIndexMetaCache = class {
+  constructor() {
+    __publicField(this, "remote", /* @__PURE__ */ new Map());
+    __publicField(this, "localEtags", /* @__PURE__ */ new Map());
+    __publicField(this, "stale", /* @__PURE__ */ new Set());
+    __publicField(this, "settings", /* @__PURE__ */ new Map());
+    __publicField(this, "entryEtags", /* @__PURE__ */ new Map());
+  }
+  observeRpcMeta(meta, options) {
+    const groupIndexes = isRecord4(meta?.group_indexes) ? meta.group_indexes : null;
+    if (!groupIndexes) return;
+    const local = String(options.localAid ?? "");
+    for (const [groupAid, value] of Object.entries(groupIndexes)) {
+      if (!isRecord4(value)) continue;
+      const key = this.key(local, groupAid);
+      const remoteMeta = {};
+      for (const name of ["etag", "last_modified", "schema"]) {
+        if (value[name] !== void 0 && value[name] !== null) remoteMeta[name] = value[name];
+      }
+      this.remote.set(key, remoteMeta);
+      const remoteEtag = String(remoteMeta.etag ?? "");
+      if (remoteEtag && this.localEtags.get(key) !== remoteEtag) this.stale.add(key);
+    }
+  }
+  markFresh(localAid, groupAid, options) {
+    const key = this.key(localAid, groupAid);
+    this.localEtags.set(key, String(options.etag ?? ""));
+    this.stale.delete(key);
+  }
+  isStale(localAid, groupAid) {
+    return this.stale.has(this.key(localAid, groupAid));
+  }
+  remoteMeta(localAid, groupAid) {
+    const value = this.remote.get(this.key(localAid, groupAid));
+    return value ? { ...value } : null;
+  }
+  localEtag(localAid, groupAid) {
+    return this.localEtags.get(this.key(localAid, groupAid)) ?? "";
+  }
+  cachedSettings(localAid, groupAid, keys) {
+    const value = this.settings.get(this.key(localAid, groupAid)) ?? {};
+    if (!keys.every((item) => item in value)) return null;
+    return Object.fromEntries(keys.map((item) => [item, value[item]]));
+  }
+  cachedSettingsByEntries(localAid, groupAid, keys, entries) {
+    const key = this.key(localAid, groupAid);
+    const value = this.settings.get(key) ?? {};
+    const localEntryEtags = this.entryEtags.get(key) ?? {};
+    const remoteEntryEtags = Object.fromEntries(entries.map((item) => [String(item.key ?? ""), String(item.etag ?? "")]));
+    const cached = {};
+    const missing = [];
+    for (const item of keys) {
+      if (item in value && localEntryEtags[item] === remoteEntryEtags[item]) {
+        cached[item] = value[item];
+      } else {
+        missing.push(item);
+      }
+    }
+    return { cached, missing };
+  }
+  cacheSettings(localAid, groupAid, settings, options) {
+    const key = this.key(localAid, groupAid);
+    this.settings.set(key, { ...this.settings.get(key) ?? {}, ...settings });
+    if (options?.entries) {
+      const nextEntryEtags = { ...this.entryEtags.get(key) ?? {} };
+      for (const item of options.entries) {
+        const entryKey = String(item.key ?? "");
+        if (entryKey) nextEntryEtags[entryKey] = String(item.etag ?? "");
+      }
+      this.entryEtags.set(key, nextEntryEtags);
+    }
+    if (options?.etag) this.markFresh(localAid, groupAid, { etag: options.etag });
+  }
+  restore(localAid, groupAid, record) {
+    const key = this.key(localAid, groupAid);
+    if (isRecord4(record.remote_meta)) this.remote.set(key, { ...record.remote_meta });
+    if (record.local_etag !== void 0 && record.local_etag !== null) {
+      this.localEtags.set(key, String(record.local_etag ?? ""));
+    }
+    if (isRecord4(record.settings)) this.settings.set(key, { ...this.settings.get(key) ?? {}, ...record.settings });
+    if (isRecord4(record.entry_etags)) {
+      this.entryEtags.set(key, {
+        ...this.entryEtags.get(key) ?? {},
+        ...Object.fromEntries(Object.entries(record.entry_etags).map(([entryKey, entryEtag]) => [entryKey, String(entryEtag ?? "")]))
+      });
+    }
+    const remoteEtag = String(this.remote.get(key)?.etag ?? "");
+    if (remoteEtag && this.localEtags.get(key) !== remoteEtag) this.stale.add(key);
+    if (remoteEtag && this.localEtags.get(key) === remoteEtag) this.stale.delete(key);
+  }
+  key(localAid, groupAid) {
+    return `${String(localAid ?? "")}\0${String(groupAid ?? "")}`;
+  }
+};
+async function computeGroupIndexBodyHash(entries) {
+  return `sha256:${await sha256Hex2(entriesBytes(entries))}`;
+}
+async function groupIndexEtag(entries) {
+  return `"sha256:${await sha256Hex2(entriesBytes(entries))}"`;
+}
+function groupIndexSigningPayload(meta, entries) {
+  const metaWithoutSignature = { ...meta };
+  delete metaWithoutSignature.signature;
+  const lines = [canonicalStringify(metaWithoutSignature)];
+  lines.push(...canonicalEntries(entries).map((item) => canonicalStringify(item)));
+  return encode(`${lines.join("\n")}
+`);
+}
+async function buildSignedGroupIndex(options) {
+  const entries = canonicalEntries(options.entries);
+  const meta = {
+    type: "index_meta",
+    group_aid: String(options.groupAid),
+    etag: await groupIndexEtag(entries),
+    last_modified: Math.trunc(Number(options.lastModified)),
+    schema: String(options.schema ?? GROUP_INDEX_SCHEMA),
+    body_hash: await computeGroupIndexBodyHash(entries),
+    signed_by: options.signer.aid,
+    sig_alg: GROUP_INDEX_SIG_ALG
+  };
+  const signed = await options.signer.sign(groupIndexSigningPayload(meta, entries));
+  if (!signed.ok) throw new Error(signed.error.message || "group index signing failed");
+  meta.signature = signed.data.signature;
+  const body = [canonicalStringify(meta), ...entries.map((item) => canonicalStringify(item))].join("\n") + "\n";
+  return { body, meta, entries };
+}
+function parseGroupIndex(body) {
+  const text3 = typeof body === "string" ? body : String(body?.body ?? "");
+  const lines = text3.split(/\r?\n/).filter((line) => line.trim());
+  if (lines.length === 0) throw new Error("group index body is empty");
+  const meta = JSON.parse(lines[0]);
+  const entries = lines.slice(1).map((line) => JSON.parse(line));
+  if (meta.type !== "index_meta") throw new Error("first group index line must be index_meta");
+  return { meta, entries };
+}
+async function verifyGroupIndex(body, signer) {
+  try {
+    const parsed = parseGroupIndex(body);
+    const signature = String(parsed.meta.signature ?? "");
+    if (!signature) return resultOk({ valid: false, reason: "signature missing" });
+    if (String(parsed.meta.signed_by ?? "") !== signer.aid) return resultOk({ valid: false, reason: "signed_by mismatch" });
+    if (String(parsed.meta.sig_alg ?? "") !== GROUP_INDEX_SIG_ALG) return resultOk({ valid: false, reason: "unsupported sig_alg" });
+    if (String(parsed.meta.body_hash ?? "") !== await computeGroupIndexBodyHash(parsed.entries)) {
+      return resultOk({ valid: false, reason: "body_hash mismatch" });
+    }
+    if (String(parsed.meta.etag ?? "") !== await groupIndexEtag(parsed.entries)) {
+      return resultOk({ valid: false, reason: "etag mismatch" });
+    }
+    const verified = await signer.verify(groupIndexSigningPayload(parsed.meta, parsed.entries), signature);
+    if (!verified.ok) return resultErr(verified.error.code, verified.error.message || "group index verify failed", verified.error.cause);
+    if (!verified.data.valid) return resultOk({ valid: false, reason: "signature verification failed" });
+    return resultOk({ valid: true, meta: parsed.meta, entries: canonicalEntries(parsed.entries) });
+  } catch (exc) {
+    return resultErr("GROUP_INDEX_VERIFY_ERROR", String(exc), exc);
+  }
+}
+async function prepareGroupSettingsWithIndex(options) {
+  const result = { ...options.settings };
+  const updatedEntries = [];
+  for (const [key, value] of Object.entries(options.settings)) {
+    if (key !== GROUP_INDEX_KEY) updatedEntries.push(await settingEntry(key, value, options.lastModified));
+  }
+  const updatedKeys = new Set(updatedEntries.map((item) => item.key));
+  const entries = [];
+  if (options.baseIndex) {
+    const parsed = parseGroupIndex(options.baseIndex);
+    entries.push(...parsed.entries.filter((item) => !updatedKeys.has(String(item.key))).map((item) => ({ ...item })));
+  }
+  entries.push(...updatedEntries);
+  result[GROUP_INDEX_KEY] = await buildSignedGroupIndex({
+    groupAid: options.groupAid,
+    entries,
+    signer: options.signer,
+    lastModified: options.lastModified
+  });
+  return result;
+}
+async function settingEntry(key, value, lastModified) {
+  const digest = await sha256Hex2(encode(canonicalStringify(value)));
+  return {
+    key,
+    source: "db",
+    etag: `"sha256:${digest}"`,
+    last_modified: Math.trunc(Number(lastModified))
+  };
+}
+function canonicalEntries(entries) {
+  return entries.map((item) => ({ ...item })).sort((a, b) => compareCodePoints2(String(a.key ?? ""), String(b.key ?? "")));
+}
+function entriesBytes(entries) {
+  const lines = canonicalEntries(entries).map((item) => canonicalStringify(item));
+  return encode(lines.length ? `${lines.join("\n")}
+` : "");
+}
+function canonicalStringify(value) {
+  return new TextDecoder().decode(canonicalJson(value));
+}
+function encode(text3) {
+  return new TextEncoder().encode(text3);
+}
+async function sha256Hex2(data) {
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", exactArrayBuffer(data));
+  return bytesToHex(new Uint8Array(digest));
+}
+function exactArrayBuffer(data) {
+  if (data.byteOffset === 0 && data.byteLength === data.buffer.byteLength && data.buffer instanceof ArrayBuffer) {
+    return data.buffer;
+  }
+  return data.slice().buffer;
+}
+function bytesToHex(bytes) {
+  return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function compareCodePoints2(a, b) {
+  const ac = Array.from(a);
+  const bc = Array.from(b);
+  const n = Math.min(ac.length, bc.length);
+  for (let i = 0; i < n; i++) {
+    const av = ac[i].codePointAt(0) ?? 0;
+    const bv = bc[i].codePointAt(0) ?? 0;
+    if (av !== bv) return av - bv;
+  }
+  return ac.length - bc.length;
+}
+function isRecord4(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
 // src/facades.ts
 function stripNil2(params2) {
   const out = {};
@@ -11120,6 +11681,13 @@ function settingsToMap(result) {
   }
   return settings;
 }
+function indexUpdateParams(groupId, settings, merged) {
+  const out = { group_id: groupId, settings };
+  for (const key of ["signer", "last_modified", "max_attempts"]) {
+    if (key in merged) out[key] = merged[key];
+  }
+  return out;
+}
 var RpcFacade = class {
   constructor(client) {
     __publicField(this, "client");
@@ -11292,6 +11860,174 @@ var GroupFacade = class extends RpcFacade {
   getSettings(params2) {
     return this.call("group.get_settings", params2);
   }
+  async checkGroupIndex(params2) {
+    const merged = stripNil2(params2);
+    const groupAid = String(merged.group_aid ?? merged.group_id ?? "").trim();
+    if (!groupAid) throw new Error("group_aid is required");
+    const clientAny = this.client;
+    const stale = typeof clientAny.isGroupIndexStale === "function" ? Boolean(clientAny.isGroupIndexStale(groupAid)) : false;
+    const remoteMeta = typeof clientAny.getGroupIndexRemoteMeta === "function" ? clientAny.getGroupIndexRemoteMeta(groupAid) ?? {} : {};
+    const localEtag = typeof clientAny.getGroupIndexLocalEtag === "function" ? String(clientAny.getGroupIndexLocalEtag(groupAid) ?? "") : "";
+    const remoteEtag = String(remoteMeta?.etag ?? "");
+    const localFound = Boolean(localEtag);
+    const remoteFound = Boolean(remoteEtag);
+    const inSync = localFound && remoteFound && localEtag === remoteEtag;
+    return {
+      group_aid: groupAid,
+      local_found: localFound,
+      remote_found: remoteFound,
+      local_etag: localEtag,
+      remote_etag: remoteEtag,
+      in_sync: inSync,
+      needs_update: Boolean(stale || remoteFound && !inSync),
+      last_modified: remoteMeta?.last_modified,
+      status: remoteFound ? 200 : 404,
+      cached: true
+    };
+  }
+  async getGroupIndex(params2) {
+    const merged = stripNil2(params2);
+    const groupId = String(merged.group_id ?? "").trim();
+    if (!groupId) throw new Error("group_id is required");
+    const result = await this.getSettings({ group_id: groupId, keys: [GROUP_INDEX_KEY] });
+    const groupAid = String(result.group_aid ?? groupId);
+    let groupIndex = null;
+    for (const item of result.settings ?? []) {
+      if (item?.key !== GROUP_INDEX_KEY) continue;
+      groupIndex = item.value;
+      break;
+    }
+    if (!groupIndex) {
+      return { group_id: result.group_id, group_aid: groupAid, group_index: null, meta: {}, entries: [] };
+    }
+    const parsed = parseGroupIndex(groupIndex);
+    await this.verifyPulledGroupIndex(groupIndex, parsed);
+    const etag = String(parsed.meta.etag ?? "");
+    const settings = await this.hydrateGroupIndexSettings(groupId, groupAid, parsed.entries, etag, groupIndex);
+    const clientAny = this.client;
+    if (etag && typeof clientAny.markGroupIndexFresh === "function") {
+      clientAny.markGroupIndexFresh(groupAid, { etag });
+    }
+    return {
+      group_id: result.group_id,
+      group_aid: groupAid,
+      group_index: groupIndex,
+      meta: parsed.meta,
+      entries: parsed.entries,
+      settings
+    };
+  }
+  async verifyPulledGroupIndex(groupIndex, parsed) {
+    const signedBy = String(parsed.meta?.signed_by ?? "").trim();
+    if (!signedBy) throw new Error("group.index signed_by is required");
+    const clientAny = this.client;
+    let signer = clientAny.currentAid?.aid === signedBy ? clientAny.currentAid : null;
+    if (!signer && typeof clientAny.lookupPeer === "function") {
+      signer = await clientAny.lookupPeer(signedBy);
+    }
+    if (!signer) throw new Error(`group.index signer is unavailable: ${signedBy}`);
+    const verified = await verifyGroupIndex(groupIndex, signer);
+    if (!verified.ok) throw new Error(verified.error.message || "group.index verification failed");
+    if (!verified.data.valid) throw new Error(`group.index verification failed: ${verified.data.reason || "invalid signature"}`);
+  }
+  async updateGroupIndex(params2) {
+    const merged = stripNil2(params2);
+    const groupId = String(merged.group_id ?? "").trim();
+    const settings = merged.settings;
+    if (!groupId) throw new Error("group_id is required");
+    if (!settings || typeof settings !== "object" || Array.isArray(settings) || Object.keys(settings).length === 0) {
+      throw new Error("settings must be a non-empty object");
+    }
+    const signer = merged.signer ?? this.client.currentAid;
+    if (!signer) throw new Error("signer is required");
+    const lastModified = Math.trunc(Number(merged.last_modified ?? Date.now()));
+    const maxAttempts = Math.max(1, Math.trunc(Number(merged.max_attempts ?? 2)));
+    let lastError = null;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      const current = await this.getSettings({ group_id: groupId, keys: [GROUP_INDEX_KEY] });
+      const groupAid = String(current.group_aid ?? groupId);
+      let currentIndex = null;
+      let expectedEtag = "";
+      for (const item of current.settings ?? []) {
+        if (item?.key !== GROUP_INDEX_KEY) continue;
+        currentIndex = item.value;
+        if (currentIndex) expectedEtag = String(parseGroupIndex(currentIndex).meta.etag ?? "");
+        break;
+      }
+      const signedSettings = await prepareGroupSettingsWithIndex({
+        groupAid,
+        settings,
+        signer,
+        lastModified,
+        baseIndex: currentIndex
+      });
+      try {
+        const result = await this.setSettings({
+          group_id: groupId,
+          settings: signedSettings,
+          expected_index_etag: expectedEtag
+        });
+        const pushedEtag = String(parseGroupIndex(signedSettings[GROUP_INDEX_KEY]).meta.etag ?? "");
+        const clientAny = this.client;
+        if (pushedEtag && typeof clientAny.markGroupIndexFresh === "function") {
+          clientAny.markGroupIndexFresh(groupAid, { etag: pushedEtag });
+        }
+        if (typeof clientAny.cacheGroupIndexSettings === "function") {
+          const parsed = parseGroupIndex(signedSettings[GROUP_INDEX_KEY]);
+          await clientAny.cacheGroupIndexSettings(groupAid, settings, {
+            entries: parsed.entries,
+            etag: pushedEtag,
+            groupIndex: signedSettings[GROUP_INDEX_KEY]
+          });
+        }
+        return result;
+      } catch (exc) {
+        if (!String(exc?.message ?? exc).includes("etag conflict")) throw exc;
+        lastError = exc;
+      }
+    }
+    if (lastError) throw lastError;
+    throw new Error("updateGroupIndex failed");
+  }
+  async getIndexedSettings(groupId, keys) {
+    const clientAny = this.client;
+    if (typeof clientAny.getGroupIndexCachedSettings === "function") {
+      const cached = await clientAny.getGroupIndexCachedSettings(groupId, keys);
+      if (cached && typeof cached === "object") return { groupId, settings: cached };
+    }
+    const result = await this.getSettings({ group_id: groupId, keys });
+    const resultMap = result;
+    const settings = settingsToMap(result);
+    if (typeof clientAny.cacheGroupIndexSettings === "function") {
+      const groupAid = String(resultMap.group_aid ?? groupId);
+      await clientAny.cacheGroupIndexSettings(groupAid, settings);
+      if (groupAid !== groupId) {
+        await clientAny.cacheGroupIndexSettings(groupId, settings);
+      }
+    }
+    return { groupId: String(resultMap.group_id ?? groupId), settings };
+  }
+  async hydrateGroupIndexSettings(groupId, groupAid, entries, etag, groupIndex) {
+    const keys = entries.filter((item) => String(item.source ?? "db") === "db" && String(item.key ?? "")).map((item) => String(item.key));
+    if (keys.length === 0) return {};
+    const clientAny = this.client;
+    let cached = {};
+    let missing = [...keys];
+    if (typeof clientAny.getGroupIndexCachedSettingsByEntries === "function") {
+      const value = await clientAny.getGroupIndexCachedSettingsByEntries(groupAid, keys, entries);
+      cached = { ...value?.cached ?? {} };
+      missing = [...value?.missing ?? []].map((item) => String(item));
+    }
+    let fetched = {};
+    if (missing.length > 0) {
+      fetched = settingsToMap(await this.getSettings({ group_id: groupId, keys: missing }));
+    }
+    const settings = { ...cached, ...fetched };
+    if (typeof clientAny.cacheGroupIndexSettings === "function") {
+      await clientAny.cacheGroupIndexSettings(groupAid, settings, { entries, etag, groupIndex });
+    }
+    return settings;
+  }
   send(params2) {
     validateGroupIDFormat(params2?.group_id, "group_id");
     return this.call("group.send", params2);
@@ -11316,15 +12052,14 @@ var GroupFacade = class extends RpcFacade {
     const merged = params2 || {};
     const groupId = merged.group_id;
     if (!groupId) throw new Error("group_id is required");
-    const result = await this.getSettings({
-      group_id: groupId,
-      keys: ["announcement.content", "announcement.attachments"]
-    });
-    const settings = settingsToMap(result);
+    const { groupId: resultGroupId, settings } = await this.getIndexedSettings(
+      String(groupId),
+      ["announcement.content", "announcement.attachments"]
+    );
     return {
-      group_id: result.group_id,
+      group_id: resultGroupId,
       announcement: {
-        group_id: result.group_id,
+        group_id: resultGroupId,
         content: settings["announcement.content"] || "",
         attachments: settings["announcement.attachments"] || [],
         updated_by: settings["announcement.content.updated_by"] || "",
@@ -11343,10 +12078,7 @@ var GroupFacade = class extends RpcFacade {
     if (attachments !== void 0) {
       settingsUpdate["announcement.attachments"] = attachments;
     }
-    const result = await this.setSettings({
-      group_id: groupId,
-      settings: settingsUpdate
-    });
+    const result = await this.updateGroupIndex(indexUpdateParams(groupId, settingsUpdate, merged));
     return {
       group_id: result.group_id,
       announcement: {
@@ -11360,15 +12092,14 @@ var GroupFacade = class extends RpcFacade {
     const merged = params2 || {};
     const groupId = merged.group_id;
     if (!groupId) throw new Error("group_id is required");
-    const result = await this.getSettings({
-      group_id: groupId,
-      keys: ["rules.content", "rules.attachments"]
-    });
-    const settings = settingsToMap(result);
+    const { groupId: resultGroupId, settings } = await this.getIndexedSettings(
+      String(groupId),
+      ["rules.content", "rules.attachments"]
+    );
     return {
-      group_id: result.group_id,
+      group_id: resultGroupId,
       rules: {
-        group_id: result.group_id,
+        group_id: resultGroupId,
         content: settings["rules.content"] || "",
         attachments: settings["rules.attachments"] || [],
         updated_by: settings["rules.content.updated_by"] || "",
@@ -11387,10 +12118,7 @@ var GroupFacade = class extends RpcFacade {
     if (attachments !== void 0) {
       settingsUpdate["rules.attachments"] = attachments;
     }
-    const result = await this.setSettings({
-      group_id: groupId,
-      settings: settingsUpdate
-    });
+    const result = await this.updateGroupIndex(indexUpdateParams(groupId, settingsUpdate, merged));
     return {
       group_id: result.group_id,
       rules: {
@@ -11404,15 +12132,14 @@ var GroupFacade = class extends RpcFacade {
     const merged = params2 || {};
     const groupId = merged.group_id;
     if (!groupId) throw new Error("group_id is required");
-    const result = await this.getSettings({
-      group_id: groupId,
-      keys: ["join.mode", "join.question", "join.auto_approve_patterns", "join.max_pending"]
-    });
-    const settings = settingsToMap(result);
+    const { groupId: resultGroupId, settings } = await this.getIndexedSettings(
+      String(groupId),
+      ["join.mode", "join.question", "join.auto_approve_patterns", "join.max_pending"]
+    );
     return {
-      group_id: result.group_id,
+      group_id: resultGroupId,
       join_requirements: {
-        group_id: result.group_id,
+        group_id: resultGroupId,
         mode: settings["join.mode"] || "open",
         question: settings["join.question"] || "",
         auto_approve_patterns: settings["join.auto_approve_patterns"] || [],
@@ -11434,10 +12161,7 @@ var GroupFacade = class extends RpcFacade {
     if (Object.keys(settingsUpdate).length === 0) {
       throw new Error("at least one field to update is required");
     }
-    const result = await this.setSettings({
-      group_id: groupId,
-      settings: settingsUpdate
-    });
+    const result = await this.updateGroupIndex(indexUpdateParams(groupId, settingsUpdate, merged));
     return {
       group_id: result.group_id,
       join_requirements: {
@@ -11573,7 +12297,7 @@ function unmountFromAny(input, fallback) {
 }
 
 // src/storage/vfs.ts
-async function sha256Hex2(data) {
+async function sha256Hex3(data) {
   const copy = new Uint8Array(data.byteLength);
   copy.set(data);
   const subtle = globalThis.crypto?.subtle;
@@ -11625,7 +12349,7 @@ var StorageVFS = class {
     const owner = this.owner(options.owner);
     const bucket = options.bucket ?? "default";
     const objectKey = pathToKey(path);
-    const sha2566 = await sha256Hex2(data);
+    const sha2566 = await sha256Hex3(data);
     const overwrite = options.overwrite ?? false;
     try {
       const check = await this.lowlevel.checkUpload({ owner, bucket, objectKey, size: data.length, sha256: sha2566 });
@@ -11721,7 +12445,7 @@ var StorageVFS = class {
   }
   async downloadFile(path, options = {}) {
     const { data, sha256: expectedSha } = await this.readBytesWithMetadata(path, options);
-    const actualSha = await sha256Hex2(data);
+    const actualSha = await sha256Hex3(data);
     const expected = expectedSha.toLowerCase();
     const verified = Boolean(expected) && actualSha.toLowerCase() === expected;
     if (!verified && expected && (options.verifyHash ?? true)) {
@@ -12207,114 +12931,6 @@ init_crypto();
 // src/v2/e2ee/types.ts
 var SUITE_NAME = "P256_HKDF_SHA256_AES_256_GCM";
 
-// src/v2/crypto/canonical.ts
-var encoder = new TextEncoder();
-var MAX_SAFE_JSON_INTEGER = 9007199254740991;
-function canonicalJson(obj) {
-  return encoder.encode(serialize(obj));
-}
-function serialize(obj) {
-  if (obj === null) return "null";
-  if (obj === true) return "true";
-  if (obj === false) return "false";
-  if (typeof obj === "number") {
-    return serializeNumber(obj);
-  }
-  if (typeof obj === "string") {
-    return serializeString(obj);
-  }
-  if (Array.isArray(obj)) {
-    return serializeArray(obj);
-  }
-  if (typeof obj === "object") {
-    return serializeObject(obj);
-  }
-  throw new TypeError(`canonicalJson: unsupported type ${typeof obj}`);
-}
-function serializeNumber(n) {
-  if (!isFinite(n)) {
-    throw new RangeError("canonicalJson: Infinity and NaN not allowed");
-  }
-  if (Object.is(n, -0)) return "0";
-  if (Number.isInteger(n)) {
-    if (Math.abs(n) > MAX_SAFE_JSON_INTEGER) {
-      throw new RangeError(`canonicalJson: integer outside safe range ${n}`);
-    }
-    return String(n);
-  }
-  return expandExponent(String(n));
-}
-function expandExponent(s) {
-  if (!/[eE]/.test(s)) return s;
-  const match = /^(-?)(\d+)(?:\.(\d+))?[eE]([+-]?\d+)$/.exec(s);
-  if (!match) {
-    throw new TypeError(`canonicalJson: invalid number ${s}`);
-  }
-  const sign = match[1] ?? "";
-  const intPart = match[2] ?? "";
-  const fracPart = match[3] ?? "";
-  const exp = Number(match[4]);
-  const digits = intPart + fracPart;
-  const point = intPart.length + exp;
-  if (point <= 0) {
-    return `${sign}0.${"0".repeat(-point)}${digits}`;
-  }
-  if (point >= digits.length) {
-    return `${sign}${digits}${"0".repeat(point - digits.length)}`;
-  }
-  return `${sign}${digits.slice(0, point)}.${digits.slice(point)}`;
-}
-function serializeString(s) {
-  let result = '"';
-  for (let i = 0; i < s.length; i++) {
-    const ch = s[i];
-    const code = s.charCodeAt(i);
-    if (ch === '"') {
-      result += '\\"';
-    } else if (ch === "\\") {
-      result += "\\\\";
-    } else if (ch === "\b") {
-      result += "\\b";
-    } else if (ch === "\f") {
-      result += "\\f";
-    } else if (ch === "\n") {
-      result += "\\n";
-    } else if (ch === "\r") {
-      result += "\\r";
-    } else if (ch === "	") {
-      result += "\\t";
-    } else if (code < 32) {
-      result += "\\u" + code.toString(16).padStart(4, "0");
-    } else {
-      result += ch;
-    }
-  }
-  result += '"';
-  return result;
-}
-function serializeArray(arr) {
-  const items = arr.map((item) => serialize(item));
-  return "[" + items.join(",") + "]";
-}
-function serializeObject(obj) {
-  const sortedKeys = Object.keys(obj).sort(compareCodePoints);
-  const pairs = sortedKeys.map(
-    (key) => serializeString(key) + ":" + serialize(obj[key])
-  );
-  return "{" + pairs.join(",") + "}";
-}
-function compareCodePoints(a, b) {
-  const ac = Array.from(a);
-  const bc = Array.from(b);
-  const n = Math.min(ac.length, bc.length);
-  for (let i = 0; i < n; i++) {
-    const av = ac[i].codePointAt(0) ?? 0;
-    const bv = bc[i].codePointAt(0) ?? 0;
-    if (av !== bv) return av - bv;
-  }
-  return ac.length - bc.length;
-}
-
 // node_modules/@noble/hashes/utils.js
 function isBytes(a) {
   return a instanceof Uint8Array || ArrayBuffer.isView(a) && a.constructor.name === "Uint8Array" && "BYTES_PER_ELEMENT" in a && a.BYTES_PER_ELEMENT === 1;
@@ -12383,7 +12999,7 @@ var hasHexBuiltin = /* @__PURE__ */ (() => (
   typeof Uint8Array.from([]).toHex === "function" && typeof Uint8Array.fromHex === "function"
 ))();
 var hexes = /* @__PURE__ */ Array.from({ length: 256 }, (_, i) => i.toString(16).padStart(2, "0"));
-function bytesToHex(bytes) {
+function bytesToHex2(bytes) {
   abytes(bytes);
   if (hasHexBuiltin)
     return bytes.toHex();
@@ -12739,7 +13355,7 @@ var sha256 = /* @__PURE__ */ createHasher(
 // node_modules/@noble/curves/utils.js
 var abytes2 = (value, length, title) => abytes(value, length, title);
 var anumber2 = anumber;
-var bytesToHex2 = bytesToHex;
+var bytesToHex3 = bytesToHex2;
 var concatBytes2 = (...arrays) => concatBytes(...arrays);
 var hexToBytes2 = (hex) => hexToBytes(hex);
 var isBytes2 = isBytes;
@@ -12781,10 +13397,10 @@ function hexToNumber(hex) {
   return hex === "" ? _0n : BigInt("0x" + hex);
 }
 function bytesToNumberBE(bytes) {
-  return hexToNumber(bytesToHex(bytes));
+  return hexToNumber(bytesToHex2(bytes));
 }
 function bytesToNumberLE(bytes) {
-  return hexToNumber(bytesToHex(copyBytes(abytes(bytes)).reverse()));
+  return hexToNumber(bytesToHex2(copyBytes(abytes(bytes)).reverse()));
 }
 function numberToBytesBE(n, len) {
   anumber(len);
@@ -14170,7 +14786,7 @@ function weierstrass(params2, extraOpts = {}) {
       return encodePoint(_Point, this, isCompressed);
     }
     toHex(isCompressed = true) {
-      return bytesToHex2(this.toBytes(isCompressed));
+      return bytesToHex3(this.toBytes(isCompressed));
     }
     toString() {
       return `<Point ${this.is0() ? "ZERO" : this.toHex()}>`;
@@ -14397,7 +15013,7 @@ function ecdsa(Point, hash, ecdsaOpts = {}) {
       return concatBytes2(rb, sb);
     }
     toHex(format) {
-      return bytesToHex2(this.toBytes(format));
+      return bytesToHex3(this.toBytes(format));
     }
   }
   Object.freeze(Signature.prototype);
@@ -14764,7 +15380,7 @@ async function sha2562(data) {
   const buf = await crypto.subtle.digest("SHA-256", data.slice().buffer);
   return new Uint8Array(buf);
 }
-function bytesToHex3(b) {
+function bytesToHex4(b) {
   let s = "";
   for (let i = 0; i < b.length; i++) s += b[i].toString(16).padStart(2, "0");
   return s;
@@ -14857,7 +15473,7 @@ async function computeMerkleRoot(rows) {
     }
     layer = next;
   }
-  return bytesToHex3(layer[0]);
+  return bytesToHex4(layer[0]);
 }
 async function verifyMerkleProof(leaf, proof, expectedRootHex) {
   if (!expectedRootHex) return false;
@@ -14873,7 +15489,7 @@ async function verifyMerkleProof(leaf, proof, expectedRootHex) {
     else if (step.position === "R") cur = await nodeHash(cur, sibling);
     else return false;
   }
-  return bytesToHex3(cur) === expectedRootHex;
+  return bytesToHex4(cur) === expectedRootHex;
 }
 async function computeRecipientsDigest(rows) {
   return computeMerkleRoot(rows);
@@ -14983,7 +15599,7 @@ function bytesToBase643(b) {
   for (let i = 0; i < b.length; i++) bin += String.fromCharCode(b[i]);
   return btoa(bin);
 }
-function bytesToHex4(b) {
+function bytesToHex5(b) {
   let s = "";
   for (let i = 0; i < b.length; i++) s += b[i].toString(16).padStart(2, "0");
   return s;
@@ -15007,7 +15623,7 @@ function uuid4Hex() {
   crypto.getRandomValues(b);
   b[6] = b[6] & 15 | 64;
   b[8] = b[8] & 63 | 128;
-  return bytesToHex4(b);
+  return bytesToHex5(b);
 }
 function randomBytes3(n) {
   const b = new Uint8Array(n);
@@ -15097,7 +15713,7 @@ async function encryptP2PMessage(sender, targetSet, payload, opts = {}) {
   pos += aadBytes.length;
   signInput.set(digestBytes, pos);
   const senderSig = await ecdsaSignRaw(sender.ikPriv, signInput);
-  const certFpHash = bytesToHex4(await sha2563(sender.ikPubDer));
+  const certFpHash = bytesToHex5(await sha2563(sender.ikPubDer));
   const certFp = `sha256:${certFpHash.substring(0, 16)}`;
   const envelope = {
     type: "e2ee.p2p_encrypted",
@@ -15165,7 +15781,7 @@ function normalizeProtectedHeaderValue(value) {
 async function wrapForRecipient(target, masterKey, senderSessionPriv, senderMasterPriv, wrapSalt, defaultRole) {
   const role = target.role ?? defaultRole;
   const keySource = target.keySource ?? "aid_master";
-  const fpHash = bytesToHex4(await sha2563(target.ikPkDer));
+  const fpHash = bytesToHex5(await sha2563(target.ikPkDer));
   const fp = `sha256:${fpHash.substring(0, 16)}`;
   const wrapNonce = randomBytes3(12);
   const use3DH = usesSPKWrap(target);
@@ -15220,7 +15836,7 @@ function bytesToBase644(b) {
   for (let i = 0; i < b.length; i++) bin += String.fromCharCode(b[i]);
   return btoa(bin);
 }
-function bytesToHex5(b) {
+function bytesToHex6(b) {
   let s = "";
   for (let i = 0; i < b.length; i++) s += b[i].toString(16).padStart(2, "0");
   return s;
@@ -15244,7 +15860,7 @@ function uuid4Hex2() {
   crypto.getRandomValues(b);
   b[6] = b[6] & 15 | 64;
   b[8] = b[8] & 63 | 128;
-  return bytesToHex5(b);
+  return bytesToHex6(b);
 }
 function randomBytes4(n) {
   const b = new Uint8Array(n);
@@ -15315,7 +15931,7 @@ async function encryptGroupMessage(sender, groupId, epoch, targets, payload, opt
   pos += aadBytes.length;
   signInput.set(digestBytes, pos);
   const senderSig = await ecdsaSignRaw(sender.ikPriv, signInput);
-  const certFpHash = bytesToHex5(await sha2564(sender.ikPubDer));
+  const certFpHash = bytesToHex6(await sha2564(sender.ikPubDer));
   const certFp = `sha256:${certFpHash.substring(0, 16)}`;
   const envelope = {
     type: "e2ee.group_encrypted",
@@ -15353,7 +15969,7 @@ async function encryptGroupMessage(sender, groupId, epoch, targets, payload, opt
 async function wrapForRecipient2(target, masterKey, senderSessionPriv, senderMasterPriv, wrapSalt) {
   const role = target.role ?? "member";
   const keySource = target.keySource ?? "aid_master";
-  const fpHash = bytesToHex5(await sha2564(target.ikPkDer));
+  const fpHash = bytesToHex6(await sha2564(target.ikPkDer));
   const fp = `sha256:${fpHash.substring(0, 16)}`;
   const wrapNonce = randomBytes4(12);
   const use3DH = usesSPKWrap2(target);
@@ -16011,7 +16627,7 @@ var PEER_KEY_CACHE_TTL_MS = 60 * 60 * 1e3;
 var DESTROY_DELAY_MS = 7 * 24 * 60 * 60 * 1e3;
 var RECENT_GENERATIONS = 7;
 var HARD_LIMIT_MS = 180 * 24 * 60 * 60 * 1e3;
-async function sha256Hex3(data) {
+async function sha256Hex4(data) {
   const buf = await crypto.subtle.digest("SHA-256", data.slice().buffer);
   const arr = new Uint8Array(buf);
   let hex = "";
@@ -16102,7 +16718,7 @@ var V2Session = class {
   }
   async _generateNewSPK() {
     const [priv, pubDer] = await generateP256Keypair();
-    const hex = await sha256Hex3(pubDer);
+    const hex = await sha256Hex4(pubDer);
     const spkId = `sha256:${hex.substring(0, 16)}`;
     await this._store.saveSPK(this._storeDeviceId, spkId, priv, pubDer);
     this._spkId = spkId;
@@ -16110,7 +16726,7 @@ var V2Session = class {
     this._spkPubDer = pubDer;
   }
   async _ikSPKId() {
-    const hex = await sha256Hex3(this._ikPubDer);
+    const hex = await sha256Hex4(this._ikPubDer);
     return `sha256:${hex.substring(0, 16)}`;
   }
   _groupKey(groupId) {
@@ -16340,7 +16956,7 @@ var V2Session = class {
       }
     }
     const [priv, pubDer] = await generateP256Keypair();
-    const hex = await sha256Hex3(pubDer);
+    const hex = await sha256Hex4(pubDer);
     const spkId = `sha256:${hex.substring(0, 16)}`;
     await this._store.saveGroupSPK(this._storeDeviceId, gk, spkId, priv, pubDer);
     return { spkId, priv, pubDer };
@@ -16365,7 +16981,7 @@ var V2Session = class {
     await this.ensureKeys();
     const gk = this._groupKey(groupId);
     const [priv, pubDer] = await generateP256Keypair();
-    const hex = await sha256Hex3(pubDer);
+    const hex = await sha256Hex4(pubDer);
     const spkId = `sha256:${hex.substring(0, 16)}`;
     await this._store.saveGroupSPK(this._storeDeviceId, gk, spkId, priv, pubDer);
     await this._publishGroupSPK(gk, spkId, pubDer, callFn);
@@ -16459,7 +17075,7 @@ function v2Sleep(ms) {
     globalThis.setTimeout(resolve, ms);
   });
 }
-function exactArrayBuffer(bytes) {
+function exactArrayBuffer2(bytes) {
   return bytes.slice().buffer;
 }
 async function pubDerMatchesFingerprint(pubDer, certFingerprint) {
@@ -16468,7 +17084,7 @@ async function pubDerMatchesFingerprint(pubDer, certFingerprint) {
   if (!expected.startsWith("sha256:")) return false;
   const expectedHex = expected.slice("sha256:".length);
   if (![16, 64].includes(expectedHex.length) || !/^[0-9a-f]+$/.test(expectedHex)) return false;
-  const digest = await crypto.subtle.digest("SHA-256", exactArrayBuffer(pubDer));
+  const digest = await crypto.subtle.digest("SHA-256", exactArrayBuffer2(pubDer));
   const spkiHex = Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
   return expectedHex.length === 16 ? spkiHex.slice(0, 16) === expectedHex : spkiHex === expectedHex;
 }
@@ -16817,7 +17433,7 @@ var V2E2EECoordinator = class {
     const pkcs8Der = v2B64ToBytes(pemBody);
     const privKey = await crypto.subtle.importKey(
       "pkcs8",
-      exactArrayBuffer(pkcs8Der),
+      exactArrayBuffer2(pkcs8Der),
       { name: "ECDH", namedCurve: "P-256" },
       true,
       ["deriveBits"]
@@ -17111,7 +17727,7 @@ var V2E2EECoordinator = class {
       const messages = pageMessages.filter((msg) => {
         const seq = Number(msg.seq ?? 0);
         return Number.isFinite(seq) && seq > nextAfterSeq;
-      });
+      }).sort((a, b) => Number(a.seq ?? 0) - Number(b.seq ?? 0));
       client._clientLog.debug(`message.v2.pull page response: page=${pageCount}, raw_count=${messages.length}, stale_count=${Math.max(0, pageMessages.length - messages.length)}, has_more=${String(result.has_more ?? "")}, server_ack_seq=${String(result.server_ack_seq ?? "")}`);
       const seqs = messages.map((msg) => Number(msg.seq ?? 0)).filter((seq) => Number.isFinite(seq) && seq > 0);
       const pageContigBefore = ns ? client._seqTracker.getContiguousSeq(ns) : 0;
@@ -17349,7 +17965,7 @@ var V2E2EECoordinator = class {
       const messages = pageMessages.filter((msg) => {
         const seq = Number(msg.seq ?? 0);
         return Number.isFinite(seq) && seq > nextAfterSeq;
-      });
+      }).sort((a, b) => Number(a.seq ?? 0) - Number(b.seq ?? 0));
       const seqs = messages.map((msg) => Number(msg.seq ?? 0)).filter((seq) => Number.isFinite(seq) && seq > 0);
       const pageContigBefore = client._seqTracker.getContiguousSeq(ns);
       const pageMaxSeq = seqs.length > 0 ? Math.max(...seqs) : nextAfterSeq;
@@ -18310,7 +18926,7 @@ function lengthPrefixedBytesKey(...parts) {
   }
   return out;
 }
-function bytesToHex6(bytes) {
+function bytesToHex7(bytes) {
   return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
 function sortObjectKeys(obj) {
@@ -18377,7 +18993,7 @@ async function computeStateHash(params2) {
     offset += chunk.length;
   }
   const digest = await crypto.subtle.digest("SHA-256", data);
-  return bytesToHex6(new Uint8Array(digest));
+  return bytesToHex7(new Uint8Array(digest));
 }
 function normalizedGroupId(raw) {
   const groupId = String(raw ?? "").trim();
@@ -18518,7 +19134,7 @@ var GroupStateCoordinator = class {
         cacheData.byteOffset + cacheData.byteLength
       );
       const cacheHash = new Uint8Array(await crypto.subtle.digest("SHA-256", cacheInput));
-      const cacheKey = bytesToHex6(cacheHash);
+      const cacheKey = bytesToHex7(cacheHash);
       const sigCache = this.runtime.groupState.sigCache;
       const now = Date.now();
       const cachedExp = sigCache.get(cacheKey);
@@ -19237,10 +19853,10 @@ function isAIDObject(value) {
     candidate && typeof candidate === "object" && typeof candidate.aid === "string" && typeof candidate.aunPath === "string" && typeof candidate.isPrivateKeyValid === "function"
   );
 }
-function bytesToHex7(bytes) {
+function bytesToHex8(bytes) {
   return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
-function exactArrayBuffer2(bytes) {
+function exactArrayBuffer3(bytes) {
   return bytes.slice().buffer;
 }
 function attachGatewayProximity2(message, source) {
@@ -19253,6 +19869,13 @@ function attachGatewayProximity2(message, source) {
     }
   }
 }
+function groupIndexBodyText(value) {
+  if (typeof value === "string") return value;
+  if (value && typeof value === "object" && !Array.isArray(value) && "body" in value) {
+    return String(value.body ?? "");
+  }
+  return "";
+}
 var DEFAULT_SESSION_OPTIONS = {
   auto_reconnect: true,
   heartbeat_interval: 30,
@@ -19605,6 +20228,8 @@ var _AUNClient = class _AUNClient {
     __publicField(this, "_v2LazyProposeTriggered", /* @__PURE__ */ new Map());
     /** agent.md 运行时管理器，负责上传、下载、缓存和 RPC 元数据观察。 */
     __publicField(this, "_agentMdManager");
+    __publicField(this, "_groupIndexMetaCache", new GroupIndexMetaCache());
+    __publicField(this, "_groupIndexCacheLoaded", /* @__PURE__ */ new Set());
     /** 消息序列号跟踪器（群消息 + P2P 空洞检测） */
     __publicField(this, "_seqTracker", new SeqTracker());
     __publicField(this, "_seqTrackerContext", null);
@@ -19614,9 +20239,13 @@ var _AUNClient = class _AUNClient {
     __publicField(this, "_pushedSeqs", /* @__PURE__ */ new Map());
     /** 已解密但因 seq 空洞暂缓发布的应用层消息（按 namespace -> seq） */
     __publicField(this, "_pendingOrderedMsgs", /* @__PURE__ */ new Map());
+    /** push 处理队列：按 P2P / group namespace 串行化异步解密与有序投递。 */
+    __publicField(this, "_pushProcessQueues", /* @__PURE__ */ new Map());
     /** Lazy group sync：首次发送群消息前自动拉取历史 */
     __publicField(this, "_groupSynced", /* @__PURE__ */ new Set());
-    /** 群撤回去重：group_id|sorted(message_ids)|recalled_at -> 时间戳，保证应用层只回调一次 */
+    /** P2P 撤回去重：原始 message_id -> 时间戳，保证应用层只回调一次 */
+    __publicField(this, "_messageRecallSeen", /* @__PURE__ */ new Map());
+    /** 群撤回去重：group_id|sorted(message_ids) -> 时间戳，保证应用层只回调一次 */
     __publicField(this, "_groupRecallSeen", /* @__PURE__ */ new Map());
     /** 在线未读 hint 队列：同一 group 只保留最后一条，延迟 drain 降低登录瞬时拉取压力。 */
     __publicField(this, "_onlineUnreadHintQueue", /* @__PURE__ */ new Map());
@@ -19739,11 +20368,11 @@ var _AUNClient = class _AUNClient {
       timeout: DEFAULT_SESSION_OPTIONS.timeouts.call,
       onDisconnect: (error, closeCode) => this._handleTransportDisconnect(error, closeCode)
     });
-    this._transport.setMetaObserver((meta) => {
-      void this._observeRpcMeta(meta).catch((exc) => {
-        this._clientLog.debug(`agent.md meta observer skipped: ${String(exc)}`);
-      });
-    });
+    this._transport.setMetaObserver(
+      (meta) => this._observeRpcMeta(meta).catch((exc) => {
+        this._clientLog.debug(`rpc meta observer skipped: ${String(exc)}`);
+      })
+    );
     this._runtime = new ClientRuntime(this);
     this._identityRuntime = new IdentityRuntimeManager(this._runtime);
     this._peerDirectory = new PeerDirectory(this._runtime);
@@ -19777,6 +20406,9 @@ var _AUNClient = class _AUNClient {
     this._dispatcher.subscribe("_raw.message.received", (data) => {
       this._onRawMessageReceived(data);
     });
+    this._dispatcher.subscribe("_raw.message.recalled", (data) => {
+      this._safeAsync(this._onRawMessageRecalled(data));
+    });
     this._dispatcher.subscribe("_raw.group.message_created", (data) => {
       this._onRawGroupMessageCreated(data);
     });
@@ -19804,7 +20436,7 @@ var _AUNClient = class _AUNClient {
     this._dispatcher.subscribe("_raw.group.state_committed", (data) => {
       this._safeAsync(this._onGroupStateCommitted(data));
     });
-    for (const evt of ["message.recalled", "message.ack", "storage.object_changed"]) {
+    for (const evt of ["message.ack", "storage.object_changed"]) {
       this._dispatcher.subscribe(`_raw.${evt}`, (data) => {
         this._dispatcher.publish(evt, data);
       });
@@ -19847,7 +20479,93 @@ var _AUNClient = class _AUNClient {
   }
   /** transport 的 meta observer：吸收 gateway 注入的 _meta 字段。失败不影响业务。 */
   async _observeRpcMeta(meta) {
+    const groupIndexes = isJsonObject(meta.group_indexes) ? meta.group_indexes : {};
+    for (const groupAid of Object.keys(groupIndexes)) {
+      await this._loadGroupIndexCache(groupAid);
+    }
+    this._groupIndexMetaCache.observeRpcMeta(meta, { localAid: this._aid ?? "" });
     await this._agentMdManager.observeRpcMeta(meta, this._aid);
+    for (const groupAid of Object.keys(groupIndexes)) {
+      await this._persistGroupIndexCache(groupAid, {
+        remote_meta: this._groupIndexMetaCache.remoteMeta(this._aid ?? "", groupAid) ?? {},
+        local_etag: this._groupIndexMetaCache.localEtag(this._aid ?? "", groupAid)
+      });
+    }
+  }
+  isGroupIndexStale(groupAid) {
+    return this._groupIndexMetaCache.isStale(this._aid ?? "", groupAid);
+  }
+  markGroupIndexFresh(groupAid, options) {
+    this._groupIndexMetaCache.markFresh(this._aid ?? "", groupAid, options);
+    void this._persistGroupIndexCache(groupAid, { local_etag: String(options.etag ?? "") });
+  }
+  getGroupIndexRemoteMeta(groupAid) {
+    return this._groupIndexMetaCache.remoteMeta(this._aid ?? "", groupAid);
+  }
+  getGroupIndexLocalEtag(groupAid) {
+    return this._groupIndexMetaCache.localEtag(this._aid ?? "", groupAid);
+  }
+  async getGroupIndexCachedSettings(groupAid, keys) {
+    await this._loadGroupIndexCache(groupAid);
+    return this._groupIndexMetaCache.cachedSettings(this._aid ?? "", groupAid, keys.map((item) => String(item)));
+  }
+  async getGroupIndexCachedSettingsByEntries(groupAid, keys, entries) {
+    await this._loadGroupIndexCache(groupAid);
+    return this._groupIndexMetaCache.cachedSettingsByEntries(
+      this._aid ?? "",
+      groupAid,
+      keys.map((item) => String(item)),
+      entries
+    );
+  }
+  cacheGroupIndexSettings(groupAid, settings, options) {
+    this._groupIndexMetaCache.cacheSettings(this._aid ?? "", groupAid, settings, options);
+    const entryEtags = {};
+    for (const item of options?.entries ?? []) {
+      const key = String(item.key ?? "");
+      if (key) entryEtags[key] = String(item.etag ?? "");
+    }
+    const fields = {
+      settings,
+      entry_etags: entryEtags,
+      remote_meta: this._groupIndexMetaCache.remoteMeta(this._aid ?? "", groupAid) ?? {},
+      local_etag: String(options?.etag ?? this._groupIndexMetaCache.localEtag(this._aid ?? "", groupAid) ?? "")
+    };
+    const indexJsonl = groupIndexBodyText(options?.groupIndex);
+    if (indexJsonl) fields.index_jsonl = indexJsonl;
+    return this._persistGroupIndexCache(groupAid, fields);
+  }
+  _groupIndexCacheKey(groupAid) {
+    return `${this._aid ?? ""}\0${String(groupAid ?? "")}`;
+  }
+  async _loadGroupIndexCache(groupAid) {
+    const localAid = String(this._aid ?? "").trim();
+    const group = String(groupAid ?? "").trim();
+    if (!localAid || !group || typeof this._tokenStore.loadGroupIndexCache !== "function") return;
+    const key = this._groupIndexCacheKey(group);
+    if (this._groupIndexCacheLoaded.has(key)) return;
+    this._groupIndexCacheLoaded.add(key);
+    const record = await this._tokenStore.loadGroupIndexCache(localAid, group);
+    if (!record) return;
+    this._groupIndexMetaCache.restore(localAid, group, {
+      remote_meta: record.remote_meta,
+      local_etag: record.local_etag,
+      settings: record.settings,
+      entry_etags: record.entry_etags
+    });
+  }
+  async _persistGroupIndexCache(groupAid, fields) {
+    const localAid = String(this._aid ?? "").trim();
+    const group = String(groupAid ?? "").trim();
+    if (!localAid || !group || typeof this._tokenStore.upsertGroupIndexCache !== "function") return;
+    const record = await this._tokenStore.upsertGroupIndexCache(localAid, group, fields);
+    this._groupIndexCacheLoaded.add(this._groupIndexCacheKey(group));
+    this._groupIndexMetaCache.restore(localAid, group, {
+      remote_meta: record.remote_meta,
+      local_etag: record.local_etag,
+      settings: record.settings,
+      entry_etags: record.entry_etags
+    });
   }
   get state() {
     return this._publicState(this._state);
@@ -20011,11 +20729,11 @@ var _AUNClient = class _AUNClient {
       timeout: DEFAULT_SESSION_OPTIONS.timeouts.call,
       onDisconnect: (error, closeCode) => this._handleTransportDisconnect(error, closeCode)
     });
-    this._transport.setMetaObserver((meta) => {
-      void this._observeRpcMeta(meta).catch((exc) => {
-        this._clientLog.debug(`agent.md meta observer skipped: ${String(exc)}`);
-      });
-    });
+    this._transport.setMetaObserver(
+      (meta) => this._observeRpcMeta(meta).catch((exc) => {
+        this._clientLog.debug(`rpc meta observer skipped: ${String(exc)}`);
+      })
+    );
     this._auth.setLogger(this._logAuth);
     this._transport.setLogger(this._logTransport);
     this._dispatcher.setLogger(this._logEvents);
@@ -20245,8 +20963,8 @@ var _AUNClient = class _AUNClient {
     }
     const nonce = globalThis.crypto.randomUUID().replace(/-/g, "");
     const issuedMs = Date.now();
-    const oldHash = bytesToHex7(new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(oldPublicKey))));
-    const newHash = bytesToHex7(new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(newPublicKey))));
+    const oldHash = bytesToHex8(new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(oldPublicKey))));
+    const newHash = bytesToHex8(new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(newPublicKey))));
     const canonical = [
       "aun-group-aid-renew-v1",
       groupId.toLowerCase(),
@@ -20365,7 +21083,7 @@ var _AUNClient = class _AUNClient {
     }
     const nonce = globalThis.crypto.randomUUID().replace(/-/g, "");
     const issuedMs = Date.now();
-    const publicKeyHash = bytesToHex7(new Uint8Array(
+    const publicKeyHash = bytesToHex8(new Uint8Array(
       await globalThis.crypto.subtle.digest(
         "SHA-256",
         new TextEncoder().encode(keyPair.public_key_der_b64)
@@ -20536,6 +21254,9 @@ var _AUNClient = class _AUNClient {
   _onRawMessageReceived(data) {
     this._delivery.onRawMessageReceived(data);
   }
+  async _onRawMessageRecalled(data) {
+    return this._delivery.onRawMessageRecalled(data);
+  }
   /** 处理群组消息推送：re-publish（V2 加密消息走 V2 push 路径） */
   _onRawGroupMessageCreated(data) {
     return this._delivery.onRawGroupMessageCreated(data);
@@ -21585,7 +22306,7 @@ var _AUNClient = class _AUNClient {
     if (!args.spkPkDer || args.spkPkDer.length === 0) {
       throw new E2EEError(`spk_public_key_missing: aid=${args.aid} device_id=${args.deviceId} spk_id=${spkId}`);
     }
-    const spkHash = bytesToHex7(new Uint8Array(await crypto.subtle.digest("SHA-256", exactArrayBuffer2(args.spkPkDer))));
+    const spkHash = bytesToHex8(new Uint8Array(await crypto.subtle.digest("SHA-256", exactArrayBuffer3(args.spkPkDer))));
     const expectedSpkId = `sha256:${spkHash.substring(0, 16)}`;
     if (spkId !== expectedSpkId) {
       throw new E2EEError(`spk_id_mismatch: aid=${args.aid} device_id=${args.deviceId} spk_id=${spkId} expected=${expectedSpkId}`);
@@ -22310,7 +23031,7 @@ var ServiceProxyClient = class {
       provider_aid: this.providerAid,
       services: services ?? this.listServiceSummaries()
     });
-    if (!isRecord4(result)) return {};
+    if (!isRecord5(result)) return {};
     if (result.ok === false) throw new ValidationError(String(result.error ?? "Gateway service registration failed"));
     return result;
   }
@@ -22323,7 +23044,7 @@ var ServiceProxyClient = class {
     if (typeof serviceNames === "string") params2.service_names = [serviceNames];
     else if (Array.isArray(serviceNames)) params2.service_names = serviceNames.map(String);
     const result = await call("proxy.unregister_services", params2);
-    return isRecord4(result) ? result : {};
+    return isRecord5(result) ? result : {};
   }
   unregister_services_from_gateway(serviceNames) {
     return this.unregisterServicesFromGateway(serviceNames);
@@ -22331,7 +23052,7 @@ var ServiceProxyClient = class {
   async listGatewayServices() {
     const call = this._gatewayCallMethod(true);
     const result = await call("proxy.list_services", { provider_aid: this.providerAid });
-    return isRecord4(result) ? result : {};
+    return isRecord5(result) ? result : {};
   }
   list_gateway_services() {
     return this.listGatewayServices();
@@ -22379,7 +23100,7 @@ var ServiceProxyClient = class {
       });
       const authResponse = parseTunnelMessage(await tunnel.recv());
       if (!authResponse.ok) {
-        const err = isRecord4(authResponse.error) ? authResponse.error : {};
+        const err = isRecord5(authResponse.error) ? authResponse.error : {};
         throw new AuthError(String(err.message ?? "Service Proxy auth failed"));
       }
       const registered = await this.registerServicesWithProxyServer(tunnel, {
@@ -22531,7 +23252,7 @@ var ServiceProxyClient = class {
         return;
       }
     }
-    const headers = backendHeaders(isRecord4(message.headers) ? message.headers : {});
+    const headers = backendHeaders(isRecord5(message.headers) ? message.headers : {});
     let response;
     try {
       const init = { method, headers };
@@ -22607,7 +23328,7 @@ var ServiceProxyClient = class {
       backend = this._createWebSocket(
         buildTargetUrl(record.endpoint, normalizePath2(String(message.path ?? "/")), String(message.query_string ?? "")),
         protocols,
-        { headers: backendHeaders(isRecord4(message.headers) ? message.headers : {}), verifySsl: this._shouldVerifySsl() },
+        { headers: backendHeaders(isRecord5(message.headers) ? message.headers : {}), verifySsl: this._shouldVerifySsl() },
         false
       );
       await waitForWsOpen(backend);
@@ -22674,7 +23395,7 @@ var ServiceProxyClient = class {
     await this._autoRegisterServicesWithGateway();
     const queue = new AsyncQueue();
     const subscription = client.on("app.service_proxy.wakeup", (payload) => {
-      if (!isRecord4(payload)) return;
+      if (!isRecord5(payload)) return;
       if (String(payload.type ?? "") !== "aun.service_proxy.wakeup") return;
       const providerAid = String(payload.provider_aid ?? "").trim();
       if (providerAid && providerAid !== this.providerAid) return;
@@ -22730,7 +23451,7 @@ var ServiceProxyClient = class {
         let message;
         try {
           const parsed = JSON.parse(raw);
-          if (!isRecord4(parsed)) continue;
+          if (!isRecord5(parsed)) continue;
           message = parsed;
         } catch {
           continue;
@@ -22772,7 +23493,7 @@ var ServiceProxyClient = class {
     await tunnel.send({ type: "service_proxy_auth", request_id: authRequestId, provider_aid: this.providerAid, client_version: "js" });
     const authResponse = parseTunnelMessage(await tunnel.recv());
     if (!authResponse.ok) {
-      const err = isRecord4(authResponse.error) ? authResponse.error : {};
+      const err = isRecord5(authResponse.error) ? authResponse.error : {};
       throw new AuthError(String(err.message ?? "Service Proxy auth failed"));
     }
     return this.registerServicesWithProxyServer(tunnel, { registerRequestId });
@@ -22790,7 +23511,7 @@ var ServiceProxyClient = class {
       }
       if (msgType !== "service_proxy_request_body") throw new Error("invalid_body_stream");
       if (String(message.request_id ?? "") !== requestId) throw new Error("request body stream request_id mismatch");
-      if (isRecord4(message.error)) throw new Error(String(message.error.message ?? "request body stream failed"));
+      if (isRecord5(message.error)) throw new Error(String(message.error.message ?? "request body stream failed"));
       const dataText = String(message.data_base64 ?? "");
       if (dataText) yield decodeBase64Strict(dataText);
       if (message.done === true) return;
@@ -22859,7 +23580,7 @@ var ServiceProxyClient = class {
   _selectProxyWsUrl(payload) {
     const direct = this._normalizeProxyWsUrl(String(payload.ws_url ?? ""));
     if (direct) return direct;
-    const servers = Array.isArray(payload.proxy_servers) ? payload.proxy_servers.filter(isRecord4) : [];
+    const servers = Array.isArray(payload.proxy_servers) ? payload.proxy_servers.filter(isRecord5) : [];
     servers.sort((a, b) => Number(a.priority ?? 999) - Number(b.priority ?? 999));
     for (const item of servers) {
       const url = this._normalizeProxyWsUrl(String(item.ws_url ?? ""));
@@ -22874,7 +23595,7 @@ var ServiceProxyClient = class {
       const response = await fetch(wellKnownUrl, { signal: controller.signal });
       if (!response.ok) throw new Error(`HTTP ${response.status}`);
       const payload = await response.json();
-      if (!isRecord4(payload)) throw new ValidationError("Service Proxy well-known returned invalid payload");
+      if (!isRecord5(payload)) throw new ValidationError("Service Proxy well-known returned invalid payload");
       const wsUrl = this._selectProxyWsUrl(payload);
       if (!wsUrl) throw new ValidationError("Service Proxy well-known missing valid ws_url");
       return { ...payload, ws_url: wsUrl, source_url: wellKnownUrl, discovered_at: Date.now() / 1e3 };
@@ -22890,7 +23611,7 @@ var ServiceProxyClient = class {
       if (typeof tokenStore.getMetadata === "function") raw = await tokenStore.getMetadata(this.providerAid, PROXY_DISCOVERY_CACHE_KEY);
       else if (typeof tokenStore.loadMetadata === "function") raw = (await tokenStore.loadMetadata(this.providerAid))?.[PROXY_DISCOVERY_CACHE_KEY];
       const cached = typeof raw === "string" ? JSON.parse(raw) : raw;
-      if (!isRecord4(cached)) return null;
+      if (!isRecord5(cached)) return null;
       const wsUrl = this._normalizeProxyWsUrl(String(cached.ws_url ?? ""));
       if (!wsUrl) return null;
       const discoveredAt = Number(cached.discovered_at ?? 0);
@@ -22930,7 +23651,7 @@ var ServiceProxyClient = class {
     if (!client) return "";
     const direct = this._mappingAccessToken(client);
     if (direct) return direct;
-    if (isRecord4(client._identity)) {
+    if (isRecord5(client._identity)) {
       const token = this._mappingAccessToken(client._identity);
       if (token) return token;
     }
@@ -22963,7 +23684,7 @@ var ServiceProxyClient = class {
     } catch (exc) {
       throw new AuthError(`AUNClient authenticate failed for Service Proxy tunnel: ${formatError(exc)}`);
     }
-    const token = this._mappingAccessToken(isRecord4(result) ? result : null);
+    const token = this._mappingAccessToken(isRecord5(result) ? result : null);
     if (token) return token;
     throw new AuthError("AUNClient authenticate did not return a valid access_token");
   }
@@ -22992,7 +23713,7 @@ function isIPv4LoopbackHost(host) {
   if (parts.length !== 4 || parts[0] !== "127") return false;
   return parts.every((part) => /^\d{1,3}$/.test(part) && Number(part) >= 0 && Number(part) <= 255);
 }
-function isRecord4(value) {
+function isRecord5(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function isSensitiveMetadataKey(key) {
@@ -23003,15 +23724,15 @@ function sanitizeMetadata(metadata) {
   const out = {};
   for (const [key, value] of Object.entries(metadata ?? {})) {
     if (isSensitiveMetadataKey(key)) continue;
-    if (isRecord4(value)) out[key] = sanitizeMetadata(value);
-    else if (Array.isArray(value)) out[key] = value.map((item) => isRecord4(item) ? sanitizeMetadata(item) : item);
+    if (isRecord5(value)) out[key] = sanitizeMetadata(value);
+    else if (Array.isArray(value)) out[key] = value.map((item) => isRecord5(item) ? sanitizeMetadata(item) : item);
     else out[key] = value;
   }
   return out;
 }
 function headersMap(headers) {
   const result = {};
-  if (!isRecord4(headers)) return result;
+  if (!isRecord5(headers)) return result;
   for (const [key, value] of Object.entries(headers)) result[key.toLowerCase()] = String(value);
   return result;
 }
@@ -23023,7 +23744,7 @@ function streamModeFrom(headers, record, message) {
   return VALID_STREAM_MODES.has(value) ? value : "auto";
 }
 function detectRequestProtocol(message, record) {
-  const headers = headersMap(isRecord4(message.headers) ? message.headers : {});
+  const headers = headersMap(isRecord5(message.headers) ? message.headers : {});
   const streamMode = streamModeFrom(headers, record, message);
   let serviceType = String(message.service_type ?? "").trim().toLowerCase() || record.service_type.toLowerCase() || "http";
   if (streamMode === "no_stream") {
@@ -23063,8 +23784,8 @@ function bodyHasJsonRpc(message) {
   if (text3.includes('"jsonrpc"') || text3.includes("'jsonrpc'")) return true;
   try {
     const parsed = JSON.parse(text3);
-    if (isRecord4(parsed)) return String(parsed.jsonrpc ?? "") === "2.0";
-    if (Array.isArray(parsed)) return parsed.some((item) => isRecord4(item) && String(item.jsonrpc ?? "") === "2.0");
+    if (isRecord5(parsed)) return String(parsed.jsonrpc ?? "") === "2.0";
+    if (Array.isArray(parsed)) return parsed.some((item) => isRecord5(item) && String(item.jsonrpc ?? "") === "2.0");
   } catch {
   }
   return false;
@@ -23130,7 +23851,7 @@ function streamMessage(requestId, index, status, headers, data, done) {
 function parseTunnelMessage(raw) {
   if (raw === null) throw new ConnectionError("Service Proxy tunnel closed");
   const parsed = JSON.parse(raw);
-  return isRecord4(parsed) ? parsed : {};
+  return isRecord5(parsed) ? parsed : {};
 }
 function waitForWsOpen(ws) {
   return new Promise((resolve, reject) => {
@@ -23307,10 +24028,14 @@ export {
   EmbeddedServiceRegistry,
   EndpointPolicy,
   EventDispatcher,
+  GROUP_INDEX_KEY,
+  GROUP_INDEX_SCHEMA,
+  GROUP_INDEX_SIG_ALG,
   GatewayDiscovery,
   GroupError,
   GroupFSVFS,
   GroupFacade,
+  GroupIndexMetaCache,
   GroupNotFoundError,
   GroupStateError,
   GroupThoughtFacade,
@@ -23350,6 +24075,8 @@ export {
   ValidationError,
   VERSION as __version__,
   buildDiscoveryHost,
+  buildSignedGroupIndex,
+  computeGroupIndexBodyHash,
   computeStateCommitment,
   convertToGroupAid,
   createConfig,
@@ -23358,18 +24085,23 @@ export {
   encryptGroupMessage,
   encryptP2PMessage,
   getDeviceId,
+  groupIndexEtag,
+  groupIndexSigningPayload,
   isGroupRemotePath,
   isJsonObject,
   mapCollabError,
   mapRemoteError,
   normalizeGroupAid,
   normalizeGroupId,
+  parseGroupIndex,
+  prepareGroupSettingsWithIndex,
   resultErr,
   resultOk,
   splitGroupId,
   validateAIDFormat,
   validateGroupAIDFormat,
-  validateGroupIDFormat
+  validateGroupIDFormat,
+  verifyGroupIndex
 };
 /*! Bundled license information: