@bolloon/bolloon-agent 0.4.33 → 0.5.0

package/dist/ios/task-frame-server.js

@@ -0,0 +1,211 @@
+/**
+ * task-frame-server.ts — bolloon-task/1 任务帧接收端 (P3, 2026-09-21)
+ *
+ * 把 `task-transport` 发来的帧 (request / accept / reject / result) 接到**本机收件箱与台账**:
+ *   · 每个信封都**必须过验签** (`verifyTaskEnvelope` + 帧里带来的公钥), 验不过 → 如实拒, 不落盘;
+ *   · `task_request` 只落**待处理收件箱** (`~/.bolloon/tasks/inbox/`): 不执行、不付款、不自动接单;
+ *   · 状态推进一律走 `task-contract.checkTaskMove` (非法迁移拒绝, 不静默修正);
+ *   · 与 `agent-delegate-server` 同一套 express + JSON 形状 (薄; 不含业务判断)。
+ *
+ * 起法 (E2E / 长跑节点):
+ *   npx tsx scripts/task-frame-node.ts --port 54901 --home /tmp/nodeA
+ *
+ * 安全口径 (如实): 收帧端点**不设身份认证** —— 它就是一个"信箱": 收到的东西一律先验签, 再只能落
+ * 待处理收件箱 (没有任何执行/付款副作用)。要不要接单是**本机用户**用 `bolloon task accept` 决定的事。
+ */
+import express from 'express';
+import { validateTaskRequest, verifyTaskEnvelope, checkTaskMove, } from '../agents/task-contract.js';
+import { verifierFor } from '../agents/local-signer.js';
+import { saveIncomingRequest, readInboxItem, patchInboxItem, readLocalTask, patchLocalTask, saveLocalTask, saveResult, saveBody, listInbox, } from '../agents/task-inbox.js';
+import { parseTaskFrame } from '../agents/task-transport.js';
+/** 校验一帧的信封签名 (帧里带的是公钥 hex; 这是公开材料, 不涉及任何私钥) */
+async function verifyFrame(frame) {
+    const v = verifierFor(frame.signer?.publicKeyHex || '');
+    if (!v)
+        return false;
+    return await verifyTaskEnvelope(frame.envelope, v);
+}
+/** 按 14 态状态机逐步推进 (非法就停, 返回停在哪一步) */
+function advance(state, steps) {
+    let cur = state;
+    const applied = [];
+    for (const to of steps) {
+        if (cur === to)
+            continue;
+        const mv = checkTaskMove(cur, to);
+        if (!mv.ok)
+            return { state: cur, applied, rejected: mv.reason };
+        cur = to;
+        applied.push(to);
+    }
+    return { state: cur, applied };
+}
+/**
+ * 处理一帧 —— 唯一入口 (HTTP / iroh / 测试都走这里, 语义只有一套)。
+ */
+export async function handleTaskFrame(frame, opts = {}) {
+    const home = opts.home;
+    const env = frame.envelope;
+    const verified = await verifyFrame(frame);
+    switch (frame.frame) {
+        case 'task_request': {
+            if (!verified) {
+                return { ok: false, error: 'SIGNATURE_INVALID', detail: '任务请求信封验签不过 (用帧里 signer.publicKeyHex 验的), 不落盘' };
+            }
+            const req = env;
+            const v = validateTaskRequest(req, { now: Date.now() });
+            if (!v.ok) {
+                // 契约层说不行 → 如实拒 (版本/字段/预算/deadline/签名逐条在 issues 里)
+                return { ok: false, error: 'INVALID_REQUEST', detail: v.issues.join('; ').slice(0, 400) };
+            }
+            const saved = saveIncomingRequest(req, {
+                home,
+                requestVerified: true,
+                buyerPublicKeyHex: frame.signer.publicKeyHex,
+                replyTo: frame.replyTo || null,
+            });
+            if (!saved.ok)
+                return { ok: false, error: 'INBOX_WRITE_FAILED', detail: saved.error };
+            const known = !opts.capabilities?.length || opts.capabilities.includes(req.capability);
+            return {
+                ok: true,
+                duplicate: saved.dup,
+                note: saved.dup
+                    ? `同一 requestId 已在收件箱 (幂等: 不重复接受/不重复执行/不重复收费) — ${saved.reason}`
+                    : `已落待处理收件箱 (不执行、不付款、不自动接单)${known ? '' : ` · 本机没有声明能力 '${req.capability}' (接单时会被拒)`}`,
+                facts: { requestId: req.requestId, taskId: req.taskId, state: saved.item?.state ?? 'pending', receivedAt: saved.item?.receivedAt },
+            };
+        }
+        case 'task_accept': {
+            if (!verified)
+                return { ok: false, error: 'SIGNATURE_INVALID', detail: '接受回执验签不过' };
+            const acc = env;
+            const cur = readLocalTask(acc.requestId, home);
+            if (!cur) {
+                // 没有本地台账: 只存回执本身, 并如实标注"没有对应台账"
+                const rec = {
+                    protocol: 'bolloon-task/1',
+                    requestId: acc.requestId,
+                    taskId: acc.taskId,
+                    capability: '',
+                    instruction: '',
+                    buyerDid: '',
+                    providerDid: acc.providerDid,
+                    target: frame.signer.did,
+                    transportKind: 'inbound',
+                    state: 'accepted',
+                    sentAt: frame.sentAt,
+                    updatedAt: Date.now(),
+                    requestSignature: '',
+                    accept: acc,
+                    notes: ['本机没有对应的本地任务台账 (只存了对端回执; 不伪造本地发送记录)'],
+                };
+                saveLocalTask(rec, home);
+                return { ok: true, note: '已存对端接受回执 (本机没有对应的本地台账)', facts: { requestId: acc.requestId, state: 'accepted' } };
+            }
+            const mv = advance(cur.state, ['accepted']);
+            if (mv.rejected) {
+                return { ok: false, error: 'TASK_TRANSITION_REJECTED', detail: `对端回执 accepted 与本机状态 ${cur.state} 不合: ${mv.rejected}` };
+            }
+            patchLocalTask(acc.requestId, { state: mv.state, accept: acc, providerPublicKeyHex: frame.signer.publicKeyHex, notes: [...cur.notes, `收到接受回执 ${new Date(frame.sentAt).toISOString()}`] }, home);
+            const inb = readInboxItem(acc.requestId, home);
+            if (inb)
+                patchInboxItem(acc.requestId, { state: 'accepted', accept: acc, providerPublicKeyHex: frame.signer.publicKeyHex }, home);
+            return { ok: true, note: `接受回执已入库 (state=${mv.state})`, facts: { requestId: acc.requestId, state: mv.state } };
+        }
+        case 'task_reject': {
+            if (!verified)
+                return { ok: false, error: 'SIGNATURE_INVALID', detail: '拒绝回执验签不过' };
+            const rej = env;
+            const cur = readLocalTask(rej.requestId, home);
+            if (!cur) {
+                return { ok: true, note: '收到拒绝对端回执, 本机没有对应台账 (不伪造)', facts: { requestId: rej.requestId, state: 'rejected', reason: rej.reason } };
+            }
+            const mv = advance(cur.state, ['rejected']);
+            if (mv.rejected)
+                return { ok: false, error: 'TASK_TRANSITION_REJECTED', detail: `对端回执 rejected 与本机状态 ${cur.state} 不合: ${mv.rejected}` };
+            patchLocalTask(rej.requestId, { state: mv.state, reject: rej, notes: [...cur.notes, `被拒: ${String(rej.reason).slice(0, 200)}`] }, home);
+            const inb = readInboxItem(rej.requestId, home);
+            if (inb)
+                patchInboxItem(rej.requestId, { state: 'rejected', reject: rej }, home);
+            return { ok: true, note: `拒绝回执已入库 (state=${mv.state})`, facts: { requestId: rej.requestId, state: mv.state, reason: rej.reason } };
+        }
+        case 'task_result': {
+            if (!verified)
+                return { ok: false, error: 'SIGNATURE_INVALID', detail: '结果信封验签不过 (不落地未验签的结果)' };
+            const res = env;
+            // ① 存结果信封 (真实内容哈希/CID + 签名)
+            const w = saveResult(res, home);
+            if (!w.ok)
+                return { ok: false, error: 'RESULT_WRITE_FAILED', detail: w.error };
+            // ② 正文 (若随帧带来): 落**私有一层**, 并用签名里的 contentHash 复核
+            let bodyFacts = { bodyPresent: false };
+            if (typeof frame.body === 'string' && frame.body.length) {
+                const saved = saveBody(res.taskId, frame.body, home);
+                const matches = !!saved.contentHash && !!res.contentHash && saved.contentHash === res.contentHash;
+                bodyFacts = {
+                    bodyPresent: true,
+                    bodyBytes: saved.bytes,
+                    bodyHashMatches: matches,
+                    bodyNote: matches ? '正文哈希与签名里的 contentHash 一致' : '正文哈希与签名里的 contentHash **不一致** (如实记录)',
+                };
+            }
+            // ③ 状态推进: submitted/accepted → running → delivered (逐条过 checkTaskMove)
+            const cur = readLocalTask(res.requestId, home);
+            if (cur) {
+                const mv = advance(cur.state, ['accepted', 'running', 'delivered']);
+                if (mv.rejected)
+                    return { ok: false, error: 'TASK_TRANSITION_REJECTED', detail: `结果回执与本机状态 ${cur.state} 不合: ${mv.rejected}` };
+                patchLocalTask(res.requestId, {
+                    state: mv.state, result: res, resultVerified: verified,
+                    providerPublicKeyHex: frame.signer.publicKeyHex,
+                    notes: [...cur.notes, `收到结果 ${new Date(frame.sentAt).toISOString()} (contentHash=${(res.contentHash || '').slice(0, 12)}…)`],
+                }, home);
+                const inb = readInboxItem(res.requestId, home);
+                if (inb)
+                    patchInboxItem(res.requestId, { state: 'delivered', result: res, resultVerified: verified, providerPublicKeyHex: frame.signer.publicKeyHex }, home);
+                return { ok: true, note: `结果已入库 (state=${mv.state}, 签名验过=${verified})`, facts: { requestId: res.requestId, taskId: res.taskId, state: mv.state, protocolVerified: verified, ...bodyFacts } };
+            }
+            const inb = readInboxItem(res.requestId, home);
+            if (inb) {
+                patchInboxItem(res.requestId, { state: 'delivered', result: res, resultVerified: verified, providerPublicKeyHex: frame.signer.publicKeyHex }, home);
+                return { ok: true, note: `结果已入库到收件箱条目 (state=delivered)`, facts: { requestId: res.requestId, taskId: res.taskId, protocolVerified: verified, ...bodyFacts } };
+            }
+            return { ok: true, note: '结果信封已存, 但本机没有对应的请求/台账 (不伪造状态)', facts: { taskId: res.taskId, protocolVerified: verified, ...bodyFacts } };
+        }
+        default:
+            return { ok: false, error: 'UNKNOWN_FRAME', detail: `未知帧类型: ${String(frame.frame)}` };
+    }
+}
+/** express app: POST /api/task/frame + GET /api/task/health */
+export function createTaskFrameApp(opts = {}) {
+    const app = express();
+    app.use(express.json({ limit: '2mb' }));
+    app.get('/api/task/health', (_req, res) => {
+        res.json({
+            ok: true,
+            schema: 'bolloon-task-frame/1',
+            selfDid: opts.selfDid || null,
+            capabilities: opts.capabilities || [],
+            inboxPending: listInbox(opts.home).filter((i) => i.state === 'pending').length,
+            note: '任务帧端点 (只落待处理收件箱; 不执行、不付款)',
+        });
+    });
+    app.post('/api/task/frame', async (req, res) => {
+        const raw = req.body?.frame;
+        if (!raw)
+            return res.status(400).json({ ok: false, error: 'BAD_FRAME', detail: '缺 frame' });
+        const parsed = parseTaskFrame(typeof raw === 'string' ? raw : JSON.stringify(raw));
+        if (!parsed.ok)
+            return res.status(400).json({ ok: false, error: 'BAD_FRAME', detail: parsed.error });
+        try {
+            const reply = await handleTaskFrame(parsed.frame, opts);
+            // 帧级失败用 200 + ok:false 表达 (与 CLI 信封同一条纪律: 失败也结构化, 不靠 HTTP 状态猜)
+            return res.status(200).json({ ok: reply.ok, ...(reply.duplicate !== undefined ? { duplicate: reply.duplicate } : {}), ...(reply.note ? { note: reply.note } : {}), ...(reply.error ? { error: reply.error } : {}), ...(reply.detail ? { detail: reply.detail } : {}), ...(reply.facts ? { facts: reply.facts } : {}) });
+        }
+        catch (e) {
+            return res.status(500).json({ ok: false, error: 'HANDLER_THREW', detail: String(e?.message || e).slice(0, 300) });
+        }
+    });
+    return app;
+}

package/dist/orbitdb/cid-database.js

@@ -23,9 +23,41 @@ import * as dagCbor from '@ipld/dag-cbor';
 import { sha256 } from 'multiformats/hashes/sha2';
 import { concat as uint8Concat } from 'uint8arrays/concat';
 import { createOrbitDB } from '@orbitdb/core';
+import * as orbitdbCoreNs from '@orbitdb/core';
+/**
+ * 运行时取 `IPFSAccessController` (2026-09-24)。
+ *
+ * 它在运行时是**真具名导出** (`@orbitdb/core` 4.0.0 `src/index.js:26`, 经
+ * `./access-controllers/index.js` 二级再导出), 但该包是**纯 JS 包**: `package.json`
+ * 既无 `types` 也无 `exports`、包内没有任何 `.d.ts` —— TS7 从 JS 推断导出集时看不见
+ * 这个二级再导出, `import { IPFSAccessController }` 直接 TS2305。
+ * 所以从命名空间按需取一次并显式收窄到已知形状; 不给整个模块上 `any`
+ * (createOrbitDB / OrbitDB / KeyValue 仍照旧受类型检查)。
+ */
+const IPFSAccessController = orbitdbCoreNs.IPFSAccessController;
 import { createBolloonIpfs } from './ipfs-node.js';
 import * as path from 'path';
 import * as os from 'os';
+/**
+ * store 打不开 (地址不可解析 / 区块不在本地且没有 block broker 能去网上取)。
+ *
+ * 2026-09-24: 原来 `openStoreByAddress` 失败返回 null, 上游 (gateway-group) 把它当"空群",
+ * 于是"读不到"被显示成"没有消息"。改成**抛**: 打不开 ≠ 没内容。
+ */
+export class OrbitDBStoreUnreachableError extends Error {
+    address;
+    cause;
+    dataDir;
+    code = 'STORE_UNREACHABLE';
+    constructor(address, cause, dataDir) {
+        const why = String(cause?.message ?? cause ?? '未知原因').slice(0, 200);
+        super(`store 不可达 (${address}): ${why}`);
+        this.address = address;
+        this.cause = cause;
+        this.dataDir = dataDir;
+        this.name = 'OrbitDBStoreUnreachableError';
+    }
+}
 /** 内容 → CID (dag-cbor, sha2-256, codec 0x71); 先 JSON 清洗 (dag-cbor 不支持 undefined) */
 export async function contentToCid(obj) {
     const cleaned = JSON.parse(JSON.stringify(obj)); // 丢弃 undefined 字段
@@ -34,6 +66,26 @@ export async function contentToCid(obj) {
     return CID.createV1(0x71, hash).toString();
 }
 const home = () => process.env.HOME || os.homedir() || '/tmp';
+/**
+ * OrbitDB 身份在 keystore 里的槽名 (2026-09-24)。
+ * 固定槽名 = 同一 dataDir 下每个进程读到**同一对密钥 / 同一个身份**。
+ * 不固定 (@orbitdb/core 默认 createId() 随机 32 位) 会让每个进程变成新写入者,
+ * 于是 `canAppend` 拿新身份去比对老 manifest 的 write 列表 → 一律拒绝。
+ */
+const ORBITDB_IDENTITY_ID = 'bolloon';
+/**
+ * `opts.accessController.write` → OrbitDB v4 的大写 `AccessController` 工厂 (2026-09-24)。
+ *
+ * @orbitdb/core v4 的 `open(address, options)` **只认大写 `AccessController`** (一个构造函数),
+ * 小写 `accessController: { write: [...] }` 会被静默丢弃 → 新 store 落回默认策略
+ * (`IPFSAccessController`: `write = write || [创建者身份 id]`, 即创建者独占写)。
+ * 于是 gateway-group 一直传的 `write:['*']` (「群成员可广播」) **从来没生效过**。
+ * 这里把已成文的选项接上; 对已存在的地址, manifest 里的 AC 仍优先 (这里不改变既有群)。
+ */
+function accessControllerOption(opts) {
+    const write = opts?.accessController?.write;
+    return Array.isArray(write) && write.length ? { AccessController: IPFSAccessController({ write }) } : {};
+}
 /**
  * OrbitDB 后端实现。单例: 同一进程只建一个 (helia/OrbitDB 都是重量级节点)。
  */
@@ -46,15 +98,29 @@ export class OrbitDBAdapter {
     constructor(dataDir = path.join(home(), '.bolloon', 'orbitdb')) {
         this.dataDir = dataDir;
     }
+    /** 落盘位置 (未初始化时 null; 诊断/验收用) */
+    get ipfsPaths() {
+        return this.node?.paths ?? null;
+    }
     /** 懒初始化: 首次使用时启动 helia + OrbitDB + 打开 keyvalue store */
     async ensure() {
         if (this.db)
             return;
         this.node = await createBolloonIpfs(path.join(this.dataDir, 'ipfs'));
-        this._orbitdb = await createOrbitDB({
+        // 2026-09-24: 身份必须**跨进程稳定**。不给 id 时 @orbitdb/core 用 createId()
+        // (32 位随机串) 当 keystore 槽名 (src/orbitdb.js:43 `id = id || await createId()`
+        // → :61 `createIdentity({ id })`) → 每个进程一对新密钥 → 新身份 → 写自己的 store
+        // 会被访问控制拒掉 ("Key … is not allowed to write to the log")。
+        // 给固定槽名后, 密钥从 <dataDir>/stores/keystore 读出复用 → 同 dataDir 同身份。
+        // 类型注: `id` 是 @orbitdb/core 的真选项 (src/orbitdb.js:33), 但 TS7 从 JS 推断出的
+        // 参数类型漏了它 → 显式取 Parameters<typeof createOrbitDB>[0] 再补 { id }
+        // (不裸 any 掉整个入参)。
+        const init = {
             ipfs: this.node.helia,
             directory: path.join(this.dataDir, 'stores'),
-        });
+            id: ORBITDB_IDENTITY_ID,
+        };
+        this._orbitdb = await createOrbitDB(init);
         this.db = await this._orbitdb.open('bolloon-cid-store', { type: 'keyvalue' });
         // 共享底层实例 (只读暴露)
         this.orbitdb = this._orbitdb;
@@ -192,33 +258,32 @@ export class OrbitDBAdapter {
      */
     async openStore(name, type = 'keyvalue', opts) {
         await this.ensure();
-        const options = { type };
-        if (opts?.accessController)
-            options.accessController = opts.accessController;
+        const options = { type, ...accessControllerOption(opts) };
         const raw = (await this._orbitdb.open(name, options));
         return this.wrapStore(raw);
     }
     /**
      * 2026-08-14: 按地址打开远端 store (Agent Gateway 共享网络 / 群组)。
-     * replica=true → 只读副本: 拉取复制但不写回 (自动加入网络不污染他人 registry)。
-     * replica=false → 可写 (群组: events store 配 write:'*' 时成员可广播)。
+     *
+     * 2026-09-24: 失败改为**抛 OrbitDBStoreUnreachableError** (含原始错误原因),
+     * 不再 `console.warn` + return null —— 那让"整个群读不到"在上层显示成"群里没有消息"。
+     *
+     * 2026-09-24 (修正既有错述): **不再往 OrbitDB 传 `replica`** ——
+     * `@orbitdb/core` 4.0.0 的 `open()` 参数表里没有它 (src/orbitdb.js:118), 传了也被丢,
+     * 之前的"replica=true 只读副本"是**不存在的语义**(等于什么都没做)。入参保留以兼容
+     * 既有调用点, 但不再冒充 OrbitDB 选项。可写与否由 manifest 里的 ACL + 调用方是否 `put` 决定。
+     * `opts.accessController` 在**打开既有地址**时同样不生效 (见接口注释: AC 由 manifest 决定)。
      */
     async openStoreByAddress(address, type = 'keyvalue', opts) {
         await this.ensure();
         try {
-            const options = { type };
-            if (opts?.replica === false)
-                options.replica = false;
-            else
-                options.replica = true;
-            if (opts?.accessController)
-                options.accessController = opts.accessController;
+            const options = { type, ...accessControllerOption(opts) };
             const raw = (await this._orbitdb.open(address, options));
             return this.wrapStore(raw);
         }
         catch (err) {
-            console.warn(`[orbitdb] openStoreByAddress 失败: ${String(err?.message || err).slice(0, 160)}`);
-            return null;
+            // 大声失败: 带上地址 + 原始原因 (最常见: "No block brokers capable of retrieving blocks ...")
+            throw new OrbitDBStoreUnreachableError(address, err, this.dataDir);
         }
     }
     async close() {

package/dist/orbitdb/ipfs-node.js

@@ -1,5 +1,5 @@
 /**
- * ipfs-node.ts — Bolloon 的 OrbitDB 底层 IPFS 节点工厂 (2026-08-06)
+ * ipfs-node.ts — Bolloon 的 OrbitDB 底层 IPFS 节点工厂 (2026-08-06; 落盘 2026-09-24)
  *
  * 基于 helia 7:
  *   - createHelia() 内部已 withLibp2p 但**不传 opts** → 无法自定义 services
@@ -10,10 +10,26 @@
  *     必须显式列出要保留的默认服务 (dht/identify/keychain/...)
  *   - withLibp2p().start() 之后 libp2p getter 才可用 (之前抛 NotStartedError)
  *
+ * 2026-09-24 **区块/datastore 落盘修复** (跨进程可重开的根因):
+ *   原来 createHeliaLight 只传 codecs/hashers → helia 用默认 MemoryBlockstore / MemoryDatastore,
+ *   而 OrbitDB 的 manifest 与 oplog 条目都走 IPFSBlockStorage(ipfs.blockstore) 存
+ *   (@orbitdb/core/src/storage/ipfs-block.js)。于是 `~/.bolloon/orbitdb/` 下只有 stores/
+ *   (keystore + log/_heads 的 LevelDB), 没有 ipfs/ 块存储 —— store 只活在创建它的那个进程里。
+ *   新进程用地址重开必挂在 manifestStore.get():
+ *     "No block brokers capable of retrieving blocks are configured, the CID bafyrei… cannot be fetched"
+ *   现在: FsBlockstore(dataDir/blocks) + FsDatastore(dataDir/datastore) 真落盘。
+ *   · datastore 顺带持久化 pin (helia pins) 与 libp2p 私钥
+ *     (@helia/libp2p: loadOrCreateSelfKey(helia.datastore) + opts.datastore ??= helia.datastore)
+ *     → 同一 dataDir 的 peerId 跨进程稳定。
+ *   · 这两个包是 Node 专用 (node:fs / node:path); 本文件只被 Node 侧 import,
+ *     浏览器入口 (client.ts / mobile-core.ts / a2ui-client.tsx) 到不了这里 —— 不伤 Web 包。
+ *
  * 跑法: npx tsx scripts/smoke-orbitdb.ts
  */
 import { createHeliaLight } from 'helia';
 import { withLibp2p } from '@helia/libp2p';
+import { FsBlockstore } from 'blockstore-fs';
+import { FsDatastore } from 'datastore-fs';
 import * as dagCbor from '@ipld/dag-cbor';
 import * as dagJson from '@ipld/dag-json';
 import * as json from 'multiformats/codecs/json';
@@ -37,13 +53,25 @@ import * as os from 'os';
 /**
  * 创建 Bolloon 用的 helia 节点 (libp2p 完整默认服务 + gossipsub pubsub)。
  * dataDir 持久化节点身份/数据 (默认 ~/.bolloon/orbitdb-ipfs)。
+ *
+ * 2026-09-24: dataDir 下真落两个目录 —— `blocks/` (区块) 与 `datastore/` (pin + peerkey)。
+ * 目录不可写时**直接抛** (不退回内存: 静默退回正好是"新进程读不到群"的根因)。
  */
 export async function createBolloonIpfs(dataDir) {
-    const dir = dataDir ?? path.join(process.env.HOME || os.homedir() || '/tmp', '.bolloon', 'orbitdb-ipfs');
+    const dir = path.resolve(dataDir ?? path.join(process.env.HOME || os.homedir() || '/tmp', '.bolloon', 'orbitdb-ipfs'));
+    const blocksDir = path.join(dir, 'blocks');
+    const datastoreDir = path.join(dir, 'datastore');
+    // 落盘存储: 不传这两个, helia 默认 MemoryBlockstore/MemoryDatastore → 进程退出即丢区块
+    const blockstore = new FsBlockstore(blocksDir);
+    const datastore = new FsDatastore(datastoreDir);
+    await blockstore.open(); // 建目录 + F_OK|W_OK 探测, 失败抛 OpenFailedError (不静默)
+    await datastore.open();
     // createHeliaLight 无 libp2p → withLibp2p 手动装配 (可传 services)
     // codecs/hashers 照抄 createHelia 默认: OrbitDB 的 log entry 用 dag-cbor (codec 113),
     // 不注册会报 "Could not load codec for 113"
     const helia = withLibp2p(createHeliaLight({
+        blockstore,
+        datastore,
         codecs: [dagCbor, dagJson, json],
         hashers: [sha512],
     }), {
@@ -71,6 +99,7 @@ export async function createBolloonIpfs(dataDir) {
     return {
         helia,
         peerId,
+        paths: { dataDir: dir, blocksDir, datastoreDir },
         start: async () => { await helia.start(); },
         stop: async () => { await helia.stop(); },
     };