@bolloon/bolloon-agent 0.5.3 → 0.5.5

package/dist/orbitdb/group-access.js

@@ -0,0 +1,381 @@
+/**
+ * group-access.ts — 群写入权限的 **DID 门控** (2026-10-01, P1)
+ * ==========================================================================
+ * 目标: 把群 (OrbitDB events store) 的写入权限从 `write:['*']` 收紧成"DID 白名单":
+ *   建群者 + **显式加入**的成员能写; 其余人**写不进 log**; 成员变更本身是一条
+ *   **可离线验签**的群事件 (成员自签 + 管理员签 ⇒ 不是某个中心节点单方面说了算)。
+ *
+ * ── 先读源码再动手 (@orbitdb/core 4.0.0, node_modules 里就是权威) ───────────
+ *
+ *  ① 真正的写闸门 = store manifest 里的 access controller (AC)。
+ *     `IPFSAccessController.canAppend` 逐条判:
+ *       `write.includes(entry 写者的 identity.id) || write.includes('*')`
+ *       —— `access-controllers/ipfs.js:78-90`。
+ *     ⚠️ 比较的是 **OrbitDB 身份 id**, 不是 DID。而 OrbitDB 身份 id =
+ *       keystore 里该身份的**压缩 secp256k1 公钥 hex** (66 位, 02/03 开头):
+ *       `key-store.js:213 generateKeyPair('secp256k1')` +
+ *       `identities/providers/publickey.js:55 base16(publicKey.raw)`。
+ *       **不是 Ed25519** ⇒ DID 与写身份是**两把钥匙**, 必须显式绑定。
+ *       本模块的成员事件就是那张绑定凭证 (`member.did ↔ member.orbitdbId`)。
+ *
+ *  ② 白名单能否在**既有 store** 上增量更新? —— 对 IPFS 型 AC: **不能**。
+ *     `write` 被打进一个 dag-cbor 的 ACL manifest, 该 ACL 的 **CID** 写进 store
+ *     manifest 的 `accessController` 字段, 而 store manifest 的 **CID 就是 store 地址**:
+ *       `access-controllers/ipfs.js:16-25, 62-69`  →  `manifest-store.js:38-56`
+ *       →  `orbitdb.js:125-134,140-142`。
+ *     改白名单 ⇒ 新 ACL 块 ⇒ 新 manifest ⇒ **新地址**。
+ *     整个包对 IPFS 型 AC **没有任何"就地改 AC"的 API**
+ *     (`ipfs.js` 只返回 `{type, address, write, canAppend}`, 没有 grant/revoke/mutate)。
+ *     ⇒ **白名单变更 = 重建 store (换地址)**; 老地址的写集合永远不变 (历史不可追认)。
+ *        代价见 `aclChangePlan()`。
+ *
+ *  ③ 4.0.0 另有一个 `OrbitDBAccessController` (type `'orbitdb'`), 它把白名单搬进一个
+ *     **独立的 keyvalue db** 并提供 `grant`/`revoke` (`access-controllers/orbitdb.js:152-174`),
+ *     所以**那一层是**可增量的。但:
+ *       · 那个 kv db 自己的**根写名单仍冻结**在它的 IPFS 型 manifest 里 —— 只有根名单里的人
+ *         能 grant/revoke (`OrbitDBAccessController({write})` 内部就是这么建的, 见 orbitdb.js:40);
+ *       · 增量要生效, 必须先把这个 **AC kv db 复制到对端** (等于多同步一个 store);
+ *       · 2026-10-01 本机真两节点实测 (见报告): 对一个**开 store 前就已 grant** 的新节点,
+ *         动态白名单能拿到; 但对一个**已经开着 store** 的节点, 180s 内**没看到** live grant
+ *         传播到位。⇒ 不当默认, 只作为可选增量通道记录在此, 不冒充"已实现"。
+ *     ⇒ 默认策略 = ① 的静态白名单 + ②的重建; 语义确定, 不留"白名单到底传没传过去"的悬念。
+ *
+ * ── 诚实边界 ──────────────────────────────────────────────────────────────
+ *   · 本模块**只做**身份/白名单/成员事件的构造与验证 + ACL 选项生成;
+ *     它不自己开 store、不自己起节点 (由 gateway-group / 验收门调)。
+ *   · `verifyMembershipEvent` 是**真** Ed25519 验签 (`ed25519Verify`), 不是摘要比对。
+ *   · 白名单里的东西是 **OrbitDB 身份 id**, 不是 DID 字符串 —— 别把 DID 塞进 `write`,
+ *     `canAppend` 永远匹配不上 (这会静默变成"谁都写不了")。
+ */
+import { canonicalize, ed25519Sign, ed25519Verify } from '../agents/x402/paid-info-protocol.js';
+import { didFromEd25519PublicKey } from '../agents/identity/address-binding.js';
+// ─────────────────────────────────────────────────────────── 常量 (冻结)
+/** 成员事件协议名 (冻结; 签名对象里的 `protocol`) */
+export const GROUP_MEMBERSHIP_PROTOCOL = 'bolloon-group-membership/1';
+/** 落在群 store 里的条目种类标记 (带这个 kind 的条目**不是**聊天消息) */
+export const GROUP_MEMBERSHIP_KIND = 'bolloon.group.membership';
+/** OrbitDB 写身份 id 的形状: 压缩 secp256k1 公钥 hex = 33B = 66 位, 02/03 开头 */
+export const ORBITDB_IDENTITY_ID_RE = /^0[23][0-9a-f]{64}$/;
+/** Ed25519 公钥 (raw 32B) hex 形状 */
+export const ED25519_PUBKEY_HEX_RE = /^[0-9a-f]{64}$/;
+/** `did:key:z…` 形状 (与 address-binding 的 BINDING_DID_RE 同构) */
+export const DID_KEY_RE = /^did:key:z[1-9A-HJ-NP-Za-km-z]{20,}$/;
+// ─────────────────────────────────────────────────────────── 形状校验
+function assertMemberRef(m, where) {
+    const r = m;
+    if (!r || typeof r !== 'object')
+        throw new Error(`${where}: 成员对象缺失`);
+    if (!DID_KEY_RE.test(String(r.did || ''))) {
+        throw new Error(`${where}: did 形状非法 (要 did:key:z…), 实得 ${String(r.did || '').slice(0, 40)}`);
+    }
+    if (!ED25519_PUBKEY_HEX_RE.test(String(r.publicKeyHex || ''))) {
+        throw new Error(`${where}: publicKeyHex 必须是 64 位小写 hex`);
+    }
+    if (!ORBITDB_IDENTITY_ID_RE.test(String(r.orbitdbId || ''))) {
+        throw new Error(`${where}: orbitdbId 形状非法 (要 66 位压缩 secp256k1 公钥 hex, 02/03 开头), 实得 ${String(r.orbitdbId || '').slice(0, 24)}`);
+    }
+    const derived = didFromEd25519PublicKey(r.publicKeyHex);
+    if (derived !== r.did) {
+        throw new Error(`${where}: did 与 publicKeyHex 不是同一把钥匙 (期望 ${derived.slice(0, 24)}…, 实得 ${r.did.slice(0, 24)}…)`);
+    }
+}
+/**
+ * 造一条成员变更声明 (纯函数, 不签名)。
+ * 校验: op/ts/group 形状 + 成员与发起人的 (did ↔ 公钥) 一致 + orbitdbId 形状。
+ */
+export function buildMembershipStatement(input) {
+    const group = String(input.group || '').trim();
+    if (!group.startsWith('/orbitdb/'))
+        throw new Error(`group 必须是 /orbitdb/… 地址, 实得 ${group.slice(0, 40)}`);
+    if (input.op !== 'add' && input.op !== 'remove')
+        throw new Error(`op 必须是 add|remove, 实得 ${String(input.op)}`);
+    assertMemberRef(input.member, 'member');
+    if (!input.by || typeof input.by !== 'object')
+        throw new Error('by 缺失');
+    if (!DID_KEY_RE.test(String(input.by.did || '')))
+        throw new Error('by.did 形状非法 (要 did:key:z…)');
+    if (!ED25519_PUBKEY_HEX_RE.test(String(input.by.publicKeyHex || '')))
+        throw new Error('by.publicKeyHex 必须是 64 位小写 hex');
+    const derivedBy = didFromEd25519PublicKey(input.by.publicKeyHex);
+    if (derivedBy !== input.by.did)
+        throw new Error('by.did 与 by.publicKeyHex 不是同一把钥匙');
+    const ts = input.ts ?? Date.now();
+    if (!Number.isInteger(ts) || ts <= 0)
+        throw new Error(`ts 必须是正整数毫秒, 实得 ${String(input.ts)}`);
+    return {
+        protocol: GROUP_MEMBERSHIP_PROTOCOL,
+        group,
+        op: input.op,
+        member: { did: input.member.did, publicKeyHex: input.member.publicKeyHex, orbitdbId: input.member.orbitdbId },
+        by: { did: input.by.did, publicKeyHex: input.by.publicKeyHex },
+        ts,
+    };
+}
+/** 签名对象 = `canonicalize(statement)` 的字节串 (键递归排序, 无空格) */
+export function membershipSigningPayload(stmt) {
+    return canonicalize(stmt);
+}
+/**
+ * 从事件里**剥出正文** (丢掉 memberSig/adminSig) —— 验签必须对正文, 不能对整条事件:
+ * 签名在事件里, 拿整条事件去 canonicalize 会把签名本身搅进被签字节串, 自己签自己, 永远验不过。
+ */
+export function statementOfEvent(ev) {
+    return {
+        protocol: ev.protocol,
+        group: ev.group,
+        op: ev.op,
+        member: ev.member,
+        by: ev.by,
+        ts: ev.ts,
+    };
+}
+/** 成员侧签名 (证明"我认领这个 orbitdbId") */
+export async function signAsMember(stmt, memberPrivateKeyHex) {
+    const seed = Buffer.from(String(memberPrivateKeyHex || ''), 'hex');
+    if (seed.length !== 32)
+        throw new Error(`成员私钥必须是 32 字节 hex (Ed25519 种子), 实得 ${seed.length}B`);
+    return ed25519Sign(seed, membershipSigningPayload(stmt));
+}
+/** 管理侧签名 (证明"我同意这次成员变更") */
+export async function signAsAdmin(stmt, adminPrivateKeyHex) {
+    const seed = Buffer.from(String(adminPrivateKeyHex || ''), 'hex');
+    if (seed.length !== 32)
+        throw new Error(`发起人私钥必须是 32 字节 hex (Ed25519 种子), 实得 ${seed.length}B`);
+    return ed25519Sign(seed, membershipSigningPayload(stmt));
+}
+/** 把两枚签名与正文组装成事件 (只校形状, 不验签; 验签用 verifyMembershipEvent) */
+export function assembleMembershipEvent(stmt, sigs) {
+    const memberSig = String(sigs.memberSig || '');
+    const adminSig = String(sigs.adminSig || '');
+    if (!memberSig)
+        throw new Error('缺 memberSig (成员必须自己签)');
+    if (!adminSig)
+        throw new Error('缺 adminSig (发起人必须自己签)');
+    return { ...stmt, memberSig, adminSig };
+}
+/** 一次性造事件 (成员 + 管理员各自私钥都在手上时用; 门/测试用) */
+export async function createMembershipEvent(input) {
+    const memberSig = await signAsMember(input.statement, input.memberPrivateKeyHex);
+    const adminSig = await signAsAdmin(input.statement, input.adminPrivateKeyHex);
+    return assembleMembershipEvent(input.statement, { memberSig, adminSig });
+}
+/** 事件 → 落库条目 */
+export function membershipEntryOf(ev) {
+    return { kind: GROUP_MEMBERSHIP_KIND, event: ev, ts: ev.ts };
+}
+// ─────────────────────────────────────────────────────────── 验签
+function fail(checks, name, detail) {
+    checks.push({ name, ok: false, detail });
+    return false;
+}
+/**
+ * 验一条成员事件 —— **真 Ed25519 验签**, 双侧都验 (成员 + 管理员), 少一侧 = 拒。
+ *
+ * 检查项 (任何一项不过 → `ok:false`, 但 `checks` 全量列出, 便于定位):
+ *   ① 协议名 / op / ts / group 形状
+ *   ② member.did 由 member.publicKeyHex 派生、by.did 由 by.publicKeyHex 派生 (两把钥匙一致)
+ *   ③ member.orbitdbId 形状 (必须真能被当成写身份)
+ *   ④ adminSig 对 `canonicalize(statement)` 验签通过 (by.publicKeyHex)
+ *   ⑤ memberSig 对同一份字节串验签通过 (member.publicKeyHex)
+ *   ⑥ 若给了 opts.group → 事件必须指向同一个群
+ */
+export async function verifyMembershipEvent(ev, opts = {}) {
+    const checks = [];
+    const e = ev;
+    if (!e || typeof e !== 'object')
+        return { ok: false, checks: [{ name: 'shape', ok: false, detail: '事件不是对象' }] };
+    checks.push({
+        name: 'protocol',
+        ok: e.protocol === GROUP_MEMBERSHIP_PROTOCOL,
+        detail: `protocol=${String(e.protocol)} (要 ${GROUP_MEMBERSHIP_PROTOCOL})`,
+    });
+    checks.push({ name: 'op', ok: e.op === 'add' || e.op === 'remove', detail: `op=${String(e.op)}` });
+    checks.push({
+        name: 'group',
+        ok: typeof e.group === 'string' && e.group.startsWith('/orbitdb/'),
+        detail: `group=${String(e.group).slice(0, 48)}`,
+    });
+    checks.push({
+        name: 'ts',
+        ok: Number.isInteger(e.ts) && e.ts > 0,
+        detail: `ts=${String(e.ts)}`,
+    });
+    const memberOk = (() => {
+        try {
+            assertMemberRef(e.member, 'member');
+            return true;
+        }
+        catch (err) {
+            checks.push({ name: 'member-binding', ok: false, detail: String(err.message) });
+            return false;
+        }
+    })();
+    if (memberOk)
+        checks.push({ name: 'member-binding', ok: true, detail: 'member.did ↔ member.publicKeyHex 同钥匙 (did:key 由公钥派生)' });
+    let byOk = false;
+    try {
+        if (!e.by || !DID_KEY_RE.test(String(e.by.did || '')) || !ED25519_PUBKEY_HEX_RE.test(String(e.by.publicKeyHex || ''))) {
+            fail(checks, 'by-binding', `by 形状非法 (did=${String(e.by?.did || '').slice(0, 20)})`);
+        }
+        else if (didFromEd25519PublicKey(e.by.publicKeyHex) !== e.by.did) {
+            fail(checks, 'by-binding', 'by.did 与 by.publicKeyHex 不是同一把钥匙');
+        }
+        else {
+            byOk = true;
+            checks.push({ name: 'by-binding', ok: true, detail: 'by.did ↔ by.publicKeyHex 同钥匙' });
+        }
+    }
+    catch (err) {
+        fail(checks, 'by-binding', String(err.message));
+    }
+    // ④⑤ 验签 (把不通过的项也列出来; 形如 sig 缺失直接判否)
+    let adminSigOk = false;
+    let memberSigOk = false;
+    try {
+        const payload = membershipSigningPayload(statementOfEvent(e));
+        adminSigOk = byOk && typeof e.adminSig === 'string' && e.adminSig.length > 0
+            ? await ed25519Verify(e.by.publicKeyHex, payload, e.adminSig)
+            : false;
+        checks.push({
+            name: 'adminSig',
+            ok: adminSigOk,
+            detail: adminSigOk ? '发起人 Ed25519 验签通过' : '发起人签名验签**不通过** (或 by 公钥不可用)',
+        });
+        memberSigOk = memberOk && typeof e.memberSig === 'string' && e.memberSig.length > 0
+            ? await ed25519Verify(e.member.publicKeyHex, payload, e.memberSig)
+            : false;
+        checks.push({
+            name: 'memberSig',
+            ok: memberSigOk,
+            detail: memberSigOk ? '成员 Ed25519 验签通过 (成员同意)' : '成员签名验签**不通过** (成员未同意 / 被改过)',
+        });
+    }
+    catch (err) {
+        fail(checks, 'sig-verify', String(err.message));
+    }
+    if (opts.group !== undefined) {
+        checks.push({
+            name: 'group-match',
+            ok: e.group === opts.group,
+            detail: `事件群=${String(e.group).slice(0, 40)} 期望=${String(opts.group).slice(0, 40)}`,
+        });
+    }
+    return { ok: checks.every((c) => c.ok), checks };
+}
+// ─────────────────────────────────────────────────────────── 白名单派生
+/** 镜像 `access-controllers/ipfs.js:85` 的判定 (`write.includes(id) || write.includes('*')`) */
+export function writeListAllows(orbitdbId, write) {
+    if (!Array.isArray(write))
+        return false;
+    return write.includes('*') || write.includes(String(orbitdbId));
+}
+/** 去重 + 稳定排序 —— 同一成员集合在任何节点派生出的白名单**逐字节一致** (ACL CID 才会一致) */
+export function normalizeWriteList(ids) {
+    const uniq = Array.from(new Set(ids.map((x) => String(x).trim()).filter(Boolean)));
+    return uniq.sort();
+}
+const normalizeWrite = normalizeWriteList;
+/**
+ * 从群主 + 成员事件**派生** ACL 写名单。
+ *
+ * 规则 (v1, 刻意简单因此可核验):
+ *   · 群主恒在名单里, 且**不可被 remove**;
+ *   · 只有 `by.did === owner.did` 的 add/remove 被接受 (v1 只有群主能改成员);
+ *   · 事件必须先**验签通过** (`verifyMembershipEvent`) 才参与派生 —— 没验过的事件不改白名单;
+ *   · 事件按 `ts` 升序应用 (同 ts 按输入顺序), `add` 去重、`remove` 移除 (除群主)。
+ *   · **不受 ts 单调性以外的时序影响**: 同一批事件 → 同一名单 → 同一 ACL。
+ */
+export async function applyMembershipEvents(input) {
+    try {
+        assertMemberRef(input.owner, 'owner');
+    }
+    catch (err) {
+        throw new Error(`群主身份非法: ${err.message}`);
+    }
+    const order = input.events.map((e, i) => ({ e, i }))
+        .sort((a, b) => (Number(a.e?.ts ?? 0) - Number(b.e?.ts ?? 0)) || (a.i - b.i));
+    const accepted = [];
+    const rejected = [];
+    const members = new Map();
+    for (const { e } of order) {
+        const v = await verifyMembershipEvent(e, input.group !== undefined ? { group: input.group } : {});
+        if (!v.ok) {
+            rejected.push({ event: e, reason: 'VERIFY_FAILED: ' + v.checks.filter((c) => !c.ok).map((c) => c.name).join(',') });
+            continue;
+        }
+        if (e.by.did !== input.owner.did) {
+            rejected.push({ event: e, reason: `UNAUTHORIZED_ISSUER: ${e.by.did.slice(0, 24)}… 不是群主` });
+            continue;
+        }
+        if (e.op === 'add') {
+            if (e.member.orbitdbId === input.owner.orbitdbId) {
+                rejected.push({ event: e, reason: 'OWNER_ALREADY_MEMBER' });
+                continue;
+            }
+            members.set(e.member.orbitdbId, {
+                did: e.member.did, publicKeyHex: e.member.publicKeyHex, orbitdbId: e.member.orbitdbId,
+            });
+        }
+        else {
+            if (e.member.orbitdbId === input.owner.orbitdbId) {
+                rejected.push({ event: e, reason: 'CANNOT_REMOVE_OWNER' });
+                continue;
+            }
+            members.delete(e.member.orbitdbId);
+        }
+        accepted.push(e);
+    }
+    const memberRefs = Array.from(members.values()).sort((a, b) => (a.orbitdbId < b.orbitdbId ? -1 : a.orbitdbId > b.orbitdbId ? 1 : 0));
+    return {
+        write: normalizeWrite([input.owner.orbitdbId, ...memberRefs.map((m) => m.orbitdbId)]),
+        members: memberRefs,
+        accepted,
+        rejected,
+    };
+}
+// ─────────────────────────────────────────────────────────── ACL 选项 / 变更代价
+/**
+ * 把白名单接成 `CIDDatabase.openStore` 认的选项。
+ * `cid-database.accessControllerOption()` 会把它翻成 OrbitDB v4 真认的大写
+ * `AccessController: IPFSAccessController({ write })` (小写会被静默丢弃 —— 2026-09-24 的坑)。
+ */
+export function groupAccessOptions(write) {
+    if (!Array.isArray(write) || write.length === 0)
+        throw new Error('白名单不能为空 (空名单会被 accessControllerOption 丢掉 → 落回默认策略)');
+    return { accessController: { write: normalizeWrite(write) } };
+}
+/** IPFS 型 AC 的"就地更新"能力 —— 源码事实, 不是推测 */
+export const ACL_INPLACE_UPDATE = {
+    ipfsType: {
+        inPlace: false,
+        why: 'write 在内容寻址的 ACL manifest 里, ACL CID → store manifest → store 地址; 改白名单必然换地址; 包里没有 AC 的 mutate/grant API',
+    },
+    orbitdbType: {
+        inPlace: 'partial',
+        why: 'grant/revoke 写一个独立的 AC keyvalue db (可复制); 但那 kv db 自己的根写名单仍冻结在它的 IPFS manifest 里 —— 只有根名单里的人能改; 且增量生效依赖该 kv db 复制到对端',
+    },
+};
+/**
+ * 成员变更的执行计划 (诚实版): IPFS 型 AC 下**只能重建**。
+ * 把代价逐条写出来, 免得下游把"换地址"当免费操作。
+ */
+export function aclChangePlan(input) {
+    const before = normalizeWrite(input.before);
+    const after = normalizeWrite(input.after);
+    const changed = before.join(',') !== after.join(',');
+    return {
+        mustRebuild: true,
+        strategy: 'rebuild',
+        why: ACL_INPLACE_UPDATE.ipfsType.why,
+        changed,
+        before,
+        after,
+        costs: [
+            '新建 store ⇒ **新地址 (新 manifest CID)**: 老成员手里的群链接/群地址全部作废, 必须重新分发',
+            '老地址的写名单**不可追认**: 未在重建时列进去的人, 连老地址都写不了 (老地址本身已经是收紧后的名单)',
+            '历史消息**不会自动搬过去**: 新 store 只有新地址的 oplog; 要保留历史必须显式回放 (逐条 add) 或让成员两头都读',
+            `本机已落盘的旧 store 不会删除 (占用不回收); 消息条数 ${Number(input.messageCount ?? 0)} 条需要回放才不丢`,
+            '重建期间**两边都能写**的窗口不存在: 切换只认新地址, 老地址冻结 (没有双写机制, 别假装有)',
+        ],
+    };
+}

package/dist/orbitdb/group-shards.js

@@ -0,0 +1,140 @@
+/** 每片最多多少条 —— 直接决定"打开一片"的成本上界 (越小越快, 但片数越多) */
+export const SHARD_SIZE = 200;
+const aclOf = (policy) => policy?.writeList && policy.writeList.length ? { accessController: { write: policy.writeList } } : {};
+/**
+ * 片级 store 缓存 (与 src/agents/gateway-group.ts 的 storeCache 同一套 idiom)。
+ * 没有它, `appendEvent` 每写一条都会再 openStore 一次 —— 1000 条 = 1000 次重复打开,
+ * 既慢又可能把同一个库开出多个句柄。
+ */
+const shardCache = new Map();
+/**
+ * 片内条数缓存 (2026-10-01 回归修复)。
+ * 轮转判据**必须**用这里 (片自己的真实长度), 不能用 manifest 里的 count ——
+ * 我为了消掉 manifest 的 O(N) 把它改成"只在轮转时落盘", 结果 count 永远停在旧值 ⇒ 再也不开新片 (实测 1000 条只有 1 片)。
+ * 首次碰到某片时用 `all().length` 对齐一次, 之后逐条自增 (不每条都读一遍)。
+ */
+const countCache = new Map();
+function cached(key, make) {
+    const hit = shardCache.get(key);
+    if (hit)
+        return Promise.resolve(hit);
+    return make().then((st) => { shardCache.set(key, st); return st; });
+}
+/** manifest store 名 (keyvalue, 极小: 只有一个 key) */
+export const manifestStoreName = (group) => `bolloon-gw-shards-${group}`;
+/** 第 i 片的 store 名 */
+export const shardStoreName = (group, i) => `bolloon-gw-group-${group}-s${String(i).padStart(3, '0')}`;
+/**
+ * 有界等待 manifest 到达 (2026-09-30 实测踩的竞态)。
+ * OrbitDB 按地址打开 store 是**异步同步**的: open() 很快返回 (实测 174ms), 但内容要靠 pubsub/取块
+ * 慢慢到 —— 立刻 `get('manifest')` 会拿到空。任何真实读者都必须等, 且等待要有界、要如实报"等到没有"。
+ */
+export async function waitForManifest(store, group, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 20000;
+    const pollMs = opts.pollMs ?? 250;
+    const t0 = Date.now();
+    for (;;) {
+        const m = await readManifest(store, group);
+        if (m.shards.length > 0)
+            return { manifest: m, waitedMs: Date.now() - t0, complete: true };
+        if (Date.now() - t0 >= timeoutMs)
+            return { manifest: m, waitedMs: Date.now() - t0, complete: false };
+        await new Promise((r) => setTimeout(r, pollMs));
+    }
+}
+/** 只读 manifest: 1 个 key ⇒ 与新节点的历史长度无关 */
+export async function readManifest(store, group) {
+    const raw = (await store.get('manifest'));
+    if (raw && raw.v === 1 && Array.isArray(raw.shards))
+        return raw;
+    return { v: 1, group, shards: [], updatedAt: 0 };
+}
+/**
+ * 追加一条事件: 写进最后一片; 满了就开新片并把 manifest 指过去。
+ * 调用方需先把 manifest store 打开 (keyvalue) — 见 openGroupShards()。
+ */
+export async function appendEvent(db, manifestStore, group, event, now = Date.now(), policy) {
+    const manifest = await readManifest(manifestStore, group);
+    const openShardByName = (name) => cached(name, () => db.openStore(name, 'events', aclOf(policy)));
+    /** 片真实长度: 首次对齐后用缓存自增 */
+    const lenOf = async (store, name) => {
+        if (!countCache.has(name))
+            countCache.set(name, (await store.all()).length);
+        return countCache.get(name);
+    };
+    let last = manifest.shards[manifest.shards.length - 1];
+    if (!last) {
+        const name = shardStoreName(group, 0);
+        const store = await openShardByName(name);
+        countCache.set(name, 0);
+        last = { index: 0, name, address: store.address, count: 0, fromTs: now, toTs: now };
+        manifest.shards.push(last);
+        manifest.updatedAt = now;
+        await manifestStore.put('manifest', JSON.parse(JSON.stringify(manifest)));
+    }
+    let store = await openShardByName(last.name);
+    let len = await lenOf(store, last.name);
+    if (len >= SHARD_SIZE) {
+        // 轮转: 开新片 + **这时才落盘 manifest** (每 SHARD_SIZE 条一次 ⇒ manifest oplog 是 O(片数))
+        const index = last.index + 1;
+        const name = shardStoreName(group, index);
+        const st = await openShardByName(name);
+        countCache.set(name, 0);
+        last = { index, name, address: st.address, count: 0, fromTs: now, toTs: now };
+        manifest.shards.push(last);
+        manifest.updatedAt = now;
+        await manifestStore.put('manifest', JSON.parse(JSON.stringify(manifest)));
+        store = st;
+        len = 0;
+    }
+    await store.add(event);
+    countCache.set(last.name, len + 1);
+    last.count = len + 1;
+    last.toTs = now;
+    return { shard: last, address: last.address, index: len };
+}
+/** 列出各片 (只读 manifest, **不打开任何片**) */
+export async function listShards(manifestStore, group) {
+    return (await readManifest(manifestStore, group)).shards;
+}
+/**
+ * 读尾部: 只打开**最后一片** (或不含给定片号的最后一片)。
+ * 这就是"打开成本不随总历史增长"的落点。
+ */
+export async function readTail(db, manifestStore, group, opts = {}) {
+    const shards = await listShards(manifestStore, group);
+    const skip = opts.skipShards ?? 0;
+    const target = shards[shards.length - 1 - skip] ?? null;
+    if (!target)
+        return { entries: [], shard: null, openedShards: 0, waitedMs: 0, complete: false };
+    const store = await cached(`addr:${target.address}`, async () => {
+        const st = await db.openStoreByAddress(target.address, 'events', aclOf(opts.policy));
+        if (!st)
+            throw new Error(`分片 ${target.index} 打不开 (${target.address})`);
+        return st;
+    });
+    // 同样是有界等待: 只等**这一片** (片大小有上界 ⇒ 等待时间有上界, 与总历史无关)
+    const timeoutMs = opts.waitMs ?? 60000;
+    const pollMs = opts.pollMs ?? 250;
+    const settleMs = opts.settleMs ?? 2000; // 连续这么久没有新条目 ⇒ 认为这片同步完了
+    const t0 = Date.now();
+    let lastCount = -1, lastGrowthAt = Date.now();
+    for (;;) {
+        const entries = await store.all();
+        if (entries.length !== lastCount) {
+            lastCount = entries.length;
+            lastGrowthAt = Date.now();
+        }
+        const settled = lastCount > 0 && Date.now() - lastGrowthAt >= settleMs;
+        if (settled)
+            return { entries, shard: target, openedShards: 1, waitedMs: Date.now() - t0, complete: true };
+        if (Date.now() - t0 >= timeoutMs)
+            return { entries, shard: target, openedShards: 1, waitedMs: Date.now() - t0, complete: false };
+        await new Promise((r) => setTimeout(r, pollMs));
+    }
+}
+/** 按需打开某个旧片 (要读历史时才付它的代价) */
+export async function openShard(db, group, index, policy) {
+    const name = shardStoreName(group, index);
+    return cached(name, () => db.openStore(name, 'events', aclOf(policy)));
+}

package/dist/orbitdb/ipfs-node.js

@@ -28,6 +28,7 @@
  */
 import { createHeliaLight } from 'helia';
 import { withLibp2p } from '@helia/libp2p';
+import { withBitswap } from '@helia/bitswap';
 import { FsBlockstore } from 'blockstore-fs';
 import { FsDatastore } from 'datastore-fs';
 import * as dagCbor from '@ipld/dag-cbor';
@@ -69,7 +70,21 @@ export async function createBolloonIpfs(dataDir) {
     // createHeliaLight 无 libp2p → withLibp2p 手动装配 (可传 services)
     // codecs/hashers 照抄 createHelia 默认: OrbitDB 的 log entry 用 dag-cbor (codec 113),
     // 不注册会报 "Could not load codec for 113"
-    const helia = withLibp2p(createHeliaLight({
+    // 2026-09-30 (P0b 实验): "轻客户端"开关。P0b 实测到一个**与条数无关的 ~25-30s 固定停顿**
+    //   (连"只有 1 条的 keyvalue store"新节点都要 25.3s 才看见内容; 历次出现 打开=30002ms),
+    //   怀疑是每次取块前的提供者查找 (kadDHT / delegated routing 两个客户端) 在超时。
+    //   打开 BOLLOON_ORBITDB_LEAN_ROUTING=1 ⇒ 不带 DHT/delegated/autoTLS, 只留 pubsub+identify+ping+relay。
+    //   这既是一个诊断开关, 也是"轻量客户端"该有的形态 (手机/低配节点不需要当 DHT 服务器)。
+    const leanRouting = process.env.BOLLOON_ORBITDB_LEAN_ROUTING === '1' || process.env.BOLLOON_ORBITDB_LEAN_ROUTING === 'true';
+    // 2026-10-01: 反事实需要"真隔离"。节点默认带 mDNS ⇒ 同机/同网的 peer **不拨号也会被自动发现并连上**
+    //   ⇒ P0 的 S3(「不拨号必须看不见」)曾经假红/假绿都出现过。做隔离实验时打开这个开关。
+    const noMdns = process.env.BOLLOON_ORBITDB_NO_MDNS === '1' || process.env.BOLLOON_ORBITDB_NO_MDNS === 'true';
+    // 2026-10-01: "全静默"隔离档。S3 那条反事实(不拨号必须看不见)在只关 mDNS 时**不稳定**
+    //   (同一份代码一轮 seen=0 一轮 seen=101) ⇒ 说明还有服务在自发建连。这一档只留
+    //   pubsub + identify + ping, 其余(autoNAT/relay/dcutr/upnp/mdns/dht/delegated/autoTLS)全关。
+    //   用途: 反事实隔离实验, 以及"最小可用节点"的形态参考。
+    const isolated = process.env.BOLLOON_ORBITDB_ISOLATED === '1' || process.env.BOLLOON_ORBITDB_ISOLATED === 'true';
+    const heliaWithLibp2p = withLibp2p(createHeliaLight({
         blockstore,
         datastore,
         codecs: [dagCbor, dagJson, json],
@@ -78,22 +93,32 @@ export async function createBolloonIpfs(dataDir) {
         // 显式列出服务: createLibp2p 浅合并会覆盖默认 services
         services: {
             pubsub: gossipsub({ emitSelf: true }), // OrbitDB 同步必需; emitSelf 让单机也能 publish (否则 NoPeersSubscribedToTopic)
-            autoNAT: autoNAT(),
-            autoTLS: autoTLS(),
-            dcutr: dcutr(),
-            delegatedPeerRouting: delegatedRoutingV1HttpApiClientPeerRouting(delegatedHTTPRoutingDefaults()),
-            delegatedContentRouting: delegatedRoutingV1HttpApiClientContentRouting(delegatedHTTPRoutingDefaults()),
-            dht: kadDHT(),
+            ...(isolated ? {} : {
+                autoNAT: autoNAT(),
+                dcutr: dcutr(),
+                relay: circuitRelayServer(),
+                upnp: uPnPNAT(),
+                http: http(),
+            }),
+            ...(isolated || leanRouting ? {} : { autoTLS: autoTLS() }),
+            ...(isolated || leanRouting ? {} : {
+                delegatedPeerRouting: delegatedRoutingV1HttpApiClientPeerRouting(delegatedHTTPRoutingDefaults()),
+                delegatedContentRouting: delegatedRoutingV1HttpApiClientContentRouting(delegatedHTTPRoutingDefaults()),
+                dht: kadDHT(),
+            }),
             identify: identify(),
             identifyPush: identifyPush(),
             keychain: keychain({ pass: 'bolloon-orbitdb-keychain-pass-2026' }),
             ping: ping(),
-            relay: circuitRelayServer(),
-            upnp: uPnPNAT(),
-            mdns: mdns(),
-            http: http(),
+            ...(isolated || noMdns ? {} : { mdns: mdns() }),
         },
     });
+    // 2026-09-30 (P0 真两节点验收照出的根因): 在此之前节点**没有任何 block broker** ——
+    //   新节点按地址打开群时连 manifest/oplog 的块都拉不到, 报
+    //   "No block brokers capable of retrieving blocks are configured, the CID bafyrei… cannot be fetched",
+    //   也就是「跨机群消息复制」从来就不可能。此前 5 个"多节点"测试都注入 fake CIDDatabase, 照不出来。
+    //   createHeliaLight 不带 bitswap, withLibp2p 也不加 ⇒ 必须显式 withBitswap (顺序: 在 libp2p 之后)。
+    const helia = withBitswap(heliaWithLibp2p);
     await helia.start();
     const peerId = helia.libp2p.peerId.toString();
     return {

package/dist/web/bolloon-web.json

@@ -1,10 +1,10 @@
 {
   "schema": "bolloon-mobile-web/1",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "channel": "stable",
   "build": "stable",
-  "commit": "5d4b12a9059a6fa1679b349f9577e827a21fc427",
-  "builtAt": "2026-09-30T02:06:24.229Z",
+  "commit": "02aa1a6367f30fb4d85f52c360d8cd457f852ddd",
+  "builtAt": "2026-10-01T13:11:22.558Z",
   "layer": "web",
   "note": "web 资源层构建戳 (手机端 OTA 的身份第 ③ 级回退; 装机后以 OTA state.json 为准)"
 }

package/dist/web/client.js

@@ -383,7 +383,7 @@
   function parseToolCall(content, ctx) {
     if (!content) return null;
     const strippedContent = content.replace(/<think[\s\S]*?<\/think/g, "");
-    try {
+    if (PARSE_DIAG_ON) try {
       const result = /* @__PURE__ */ (function _diagProbe() {
         return null;
       })();
@@ -571,11 +571,12 @@
     }
     return null;
   }
-  var SHELL_KEYWORDS;
+  var SHELL_KEYWORDS, PARSE_DIAG_ON;
   var init_parse_tool_call = __esm({
     "src/agents/parse-tool-call.ts"() {
       "use strict";
       SHELL_KEYWORDS = ["git", "npx", "npm", "tsx", "tsc", "vitest", "node", "mkdir", "touch", "ls", "echo", "cat", "head", "tail", "wc", "pwd", "date"];
+      PARSE_DIAG_ON = process.env.BOLLOON_PARSE_DIAG === "1" || process.env.BOLLOON_VERBOSE === "1";
     }
   });