@runko/persist-mongo 0.1.0

package/README.md

@@ -0,0 +1,113 @@
+# @runko/persist-mongo
+
+runko 的持久化实现，**MongoDB**——也是第一个**非关系型**实现。
+
+```sh
+pnpm add @runko/persist-mongo mongodb
+```
+
+```ts
+import { createAgentRuntime } from "@runko/agent";
+import { migrate, mongoPersistence } from "@runko/persist-mongo";
+import { MongoClient } from "mongodb";
+
+const client = new MongoClient(process.env.MONGO_URL);
+await client.connect();
+const db = client.db("myapp");
+
+await migrate(db);          // 建索引，幂等
+
+const runtime = createAgentRuntime(agent, { persistence: mongoPersistence(db) });
+```
+
+**吃 `Db` 而不是 `MongoClient`**：选哪个 database 是你的决定（多租户可能一租户一个 db），
+连接的生命周期也归你——本包不 connect、不 close。
+
+## 它不是薄壳
+
+SQLite / PostgreSQL / MySQL 那三个包底下共用 `@runko/persist-kysely`。Kysely 是 SQL
+查询构建器，Mongo 用不上，所以**这个包直接实现三个领域接口**。
+
+## 它顺带证明了什么
+
+契约里有三条准则，当初就是为了**不把非关系型挡在门外**才那么写的。这是第一次真去验：
+
+| 准则 | 结论 |
+| --- | --- |
+| 不假设事务能跨接口 | ✅ 需要原子的只有 `dequeue`，Mongo 的 `findOneAndDelete` 原生原子 |
+| 不要求 CAS | ✅ 一次都没用上 |
+| 不支持跨会话查询 | ✅ 每个查询都以 `conversationId` 打头，正好是索引前缀 |
+
+三条全成立——接口**没有漏掉关系型假设**。
+
+有一处 Mongo 反而更干净：契约要求 `dequeue`「取出即移除，一个方法内原子完成」，
+SQL 那几家是「先 SELECT 排序取第一条、再 DELETE」两步，中间有窗口、得靠重试兜；
+Mongo 的 `findOneAndDelete({...}, {sort})` **是数据库直接给的**。
+
+## 它存什么
+
+三个集合：`agent_ledger`（账本）· `agent_decisions`（人工裁决留底）· `agent_queue`（待发队列）。
+
+集合名固定，不提供前缀开关——**要隔离请用另一个 database**，那在 Mongo 里是一等公民，
+比集合名前缀干净得多。
+
+`migrate()` 只建索引（Mongo 的集合是隐式创建的）。但它**不是可选的**：账本与裁决表的
+幂等写入靠唯一索引兜底，没有它并发写会写出两行。
+
+**它不存你的东西。** runko 只认一个不透明的 `conversationId`，会话叫什么、属于谁，
+全归你自己存。
+
+## 要求 MongoDB 5.0+
+
+工具入参是**任意 JSON**，键里可能有 `.` 或 `$`——5.0 之前的 MongoDB 不接受这种字段名。
+实测 MongoDB 8 全放行。
+
+## 两个实测出来的坑
+
+**① `settle` 必须看 `matchedCount`，不能看 `modifiedCount`。**
+Mongo 在「匹配到但新值与旧值完全相同」时报 `matched=1, modified=0`。用 `modifiedCount`
+判断会把一次成功的结清误报成「没有这条」，调用方于是转 404。
+
+> 有意思的是：契约文档曾经把这个坑安在 MySQL 头上，实测发现**在 MySQL 上不成立**
+> （Kysely 的 `numUpdatedRows` 报的就是匹配数）。它的真身在这儿。
+
+**② BSON 把 `undefined` 存成 `null`**，而 SQL 那几家走 `JSON.stringify`（直接丢掉这个键）。
+本包在写入前先过一遍 `JSON.parse(JSON.stringify(...))` 对齐它们——不然一致性套件的
+「原样往返」当场就红。
+
+没走「客户端开 `ignoreUndefined`」那条路，是因为**客户端是你建的**，我们只拿到 `Db`。
+
+## 测试
+
+```sh
+RUNKO_TEST_MONGO_URL=mongodb://127.0.0.1:27018 pnpm --filter @runko/persist-mongo test
+```
+
+跟其余三个持久化包**跑同一套一致性用例**。不给连接串时整档跳过并说明原因——
+Mongo 没有 pglite 那样的进程内替身（`mongodb-memory-server` 是下载一个真 mongod 来跑）。
+
+## 不是只有这一条路
+
+**你的数据模型跟这三个集合对不上？那就自己实现那三个接口**——那是[头等路径，不是降级方案](../../docs/host/contract/features/persistence.md)。
+一共十来个方法。自己实现的话，装上 [`@runko/conformance`](../conformance/README.md) 自测：
+
+```ts
+import { persistenceCases } from "@runko/conformance";
+
+describe("我自己的实现", () => {
+  for (const testCase of persistenceCases) {
+    it(testCase.name, async () => {
+      await testCase.run({ persistence: myPersistence() });
+    });
+  }
+});
+```
+
+套件**不依赖任何测试框架**——它只导出 `{ name, run }` 这样的用例数据，`describe`/`it`
+由你来接，vitest / jest / node:test / Workers 上都能跑。
+
+## 文档
+
+[功能手册](../../docs/host/contract/features/persistence.md) ·
+[技术方案](../../docs/host/contract/tech/persistence.md) ·
+[施工进展](../../docs/host/contract/plans/persistence.md)

package/dist/index.cjs

@@ -0,0 +1,369 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/collections.ts
+const LEDGER_COLLECTION = "agent_ledger";
+const DECISIONS_COLLECTION = "agent_decisions";
+const QUEUE_COLLECTION = "agent_queue";
+/**
+* **写进 BSON 之前先过一遍 JSON。**
+*
+* 这一步不是多余的，它修的是一个实测出来的行为差异：BSON 会把 `undefined` **存成
+* `null`**，而 SQL 那几家走的是 `JSON.stringify`（**直接把这个键丢掉**）。同一个
+* `RunkoUIMessage` 存进去、读出来，Mongo 给 `{cachedInputTokens: null}`、SQLite 给
+* `{}`——一致性套件的「原样往返」当场就会红。
+*
+* 修法有两条，选了这条：
+*
+* | | 怎么做 | 为什么不选 |
+* |---|---|---|
+* | 客户端开 `ignoreUndefined` | `new MongoClient(url, { ignoreUndefined: true })` | **客户端是宿主建的**，我们只拿到 `Db`，管不着它怎么建的 |
+* | ✅ 自己先 JSON 归一 | `JSON.parse(JSON.stringify(v))` | —— |
+*
+* 选后者还有一个额外好处：它让 Mongo 这一档的语义**可证地**与 SQL 那几家一致
+* ——因为它做的就是那几家在做的同一件事。
+*/
+function toBson(value) {
+	return JSON.parse(JSON.stringify(value ?? null));
+}
+/**
+* 读回来直接用——**不需要反向转换**。
+*
+* 存进去的已经是 JSON 归一过的纯数据，Mongo 原样给回来。数字、字符串、嵌套对象、
+* 数组都实测过原样往返（含 `Number.MAX_SAFE_INTEGER` 与浮点）。
+*
+* 留这个函数是为了让「读」这一侧有个明确的边界名字，将来真要加什么（比如剥掉
+* driver 塞进来的 `_id`）有地方放。
+*
+* ⚠️ **这是一处刻意的类型逃逸，范围仅限本函数。** 驱动把 BSON 文档的字段给成
+* `unknown`（它无法知道我们存了什么形状），而这一层唯一能做的就是把它交还给调用方。
+* 泛型 `as` 意味着**本边界上没有类型检查**——所以真正需要保证形状的地方必须自己校验：
+* 队列的 `input` 走 `decodeTurnInput`（zod）；账本的 `payload` 由 core 在
+* `createSession({ resume })` 里跑 `validateUIMessages` 兜住。别把这个函数当成
+* 「安全的转换」到处用。
+*/
+function fromBson(value) {
+	return value;
+}
+//#endregion
+//#region src/stores.ts
+const OK = { ok: true };
+/** 重复键。并发 upsert 撞同一个唯一索引时驱动抛这个，见 `upsertOnce`。 */
+const DUPLICATE_KEY = 11e3;
+function isDuplicateKeyError(error) {
+	return typeof error === "object" && error !== null && "code" in error && error.code === DUPLICATE_KEY;
+}
+/**
+* 幂等插入的**兜底那一半**：吞掉重复键，其余错误照抛。
+*
+* 幂等本身靠 `upsert` + `$setOnInsert`（在调用点写），不靠异常——「先查再插」有竞态
+* 窗口，「插了 catch」会把真正的写失败也一起吞掉。
+*
+* 但 `upsert` 在并发下**仍可能抛重复键**：两个请求同时发现不存在、同时插，唯一索引
+* 挡下后一个。这是 MongoDB 明确记录的行为，不是 bug。那一支的结果照样是「已经有了
+* 一行」——契约要的是「不得写出两行」，满足了，所以吞掉。
+*
+* **只包异常处理、不包 `updateOne` 本身**是刻意的：这样 `$setOnInsert` 的字段能在
+* **具体的调用点**跟具体的文档类型对上，写错字段当场编译不过。包成一个泛型 helper
+* 反而会把类型冲开、逼出一个 `as`。
+*/
+async function ignoringDuplicateKey(write) {
+	try {
+		return await write();
+	} catch (error) {
+		if (!isDuplicateKeyError(error)) throw error;
+		return;
+	}
+}
+function createLedgerStore(db) {
+	const col = db.collection(LEDGER_COLLECTION);
+	return {
+		async append(entry) {
+			if ((await ignoringDuplicateKey(() => col.updateOne({
+				conversationId: entry.conversationId,
+				seq: entry.seq
+			}, { $setOnInsert: {
+				payload: toBson(entry.message),
+				ts: entry.ts
+			} }, { upsert: true })))?.upsertedCount === 1) return OK;
+			const existing = await col.findOne({
+				conversationId: entry.conversationId,
+				seq: entry.seq
+			}, { projection: { _id: 0 } });
+			if (existing !== null && fromBson(existing.payload).id === entry.message.id) return OK;
+			return {
+				ok: false,
+				reason: "rejected"
+			};
+		},
+		async read(conversationId, opts) {
+			const filter = opts?.afterSeq === void 0 ? { conversationId } : {
+				conversationId,
+				seq: { $gt: opts.afterSeq }
+			};
+			return (await col.find(filter, { projection: { _id: 0 } }).sort({ seq: 1 }).toArray()).map((doc) => ({
+				conversationId: doc.conversationId,
+				seq: doc.seq,
+				message: fromBson(doc.payload),
+				ts: doc.ts
+			}));
+		},
+		async maxSeq(conversationId) {
+			return (await col.findOne({ conversationId }, {
+				sort: { seq: -1 },
+				projection: {
+					seq: 1,
+					_id: 0
+				}
+			}))?.seq ?? 0;
+		}
+	};
+}
+function isOutcome(value) {
+	return value === "allow" || value === "deny" || value === "answered" || value === "timeout";
+}
+/** 可选字段一律「有才放进去」——`exactOptionalPropertyTypes` 下不能给 `undefined`。 */
+function toRecord(doc) {
+	return {
+		conversationId: doc.conversationId,
+		toolCallId: doc.toolCallId,
+		kind: doc.kind === "question" ? "question" : "approval",
+		...doc.toolName !== null ? { toolName: doc.toolName } : {},
+		...doc.payload !== null ? { payload: fromBson(doc.payload) } : {},
+		...isOutcome(doc.outcome) ? { outcome: doc.outcome } : {},
+		...doc.scope === "once" || doc.scope === "conversation" ? { scope: doc.scope } : {},
+		...doc.decidedBy !== null ? { decidedBy: doc.decidedBy } : {},
+		...doc.message !== null ? { message: doc.message } : {},
+		requestedAt: doc.requestedAt,
+		...doc.decidedAt !== null ? { decidedAt: doc.decidedAt } : {}
+	};
+}
+function createDecisionStore(db) {
+	const col = db.collection(DECISIONS_COLLECTION);
+	return {
+		async record(entry) {
+			await ignoringDuplicateKey(() => col.updateOne({
+				conversationId: entry.conversationId,
+				toolCallId: entry.toolCallId
+			}, { $setOnInsert: {
+				kind: entry.kind,
+				toolName: entry.toolName ?? null,
+				payload: entry.payload === void 0 ? null : toBson(entry.payload),
+				outcome: entry.outcome ?? null,
+				scope: entry.scope ?? null,
+				decidedBy: entry.decidedBy ?? null,
+				message: entry.message ?? null,
+				requestedAt: entry.requestedAt,
+				decidedAt: entry.decidedAt ?? null
+			} }, { upsert: true }));
+			return OK;
+		},
+		async settle(conversationId, toolCallId, settlement) {
+			return (await col.updateOne({
+				conversationId,
+				toolCallId,
+				decidedAt: null
+			}, { $set: {
+				outcome: settlement.outcome ?? null,
+				scope: settlement.scope ?? null,
+				decidedBy: settlement.decidedBy ?? null,
+				message: settlement.message ?? null,
+				decidedAt: settlement.decidedAt
+			} })).matchedCount > 0;
+		},
+		async listPending(conversationId) {
+			return (await col.find({
+				conversationId,
+				decidedAt: null
+			}, { projection: { _id: 0 } }).sort({ requestedAt: 1 }).toArray()).map(toRecord);
+		}
+	};
+}
+/** `enqueue` / `requeueFront` 撞号时的重试上限——够覆盖真实并发，又不会在病态负载下无限转。 */
+const ENQUEUE_MAX_ATTEMPTS = 5;
+function createQueueStore(db) {
+	const col = db.collection(QUEUE_COLLECTION);
+	const toItem = (doc) => ({
+		id: doc._id,
+		conversationId: doc.conversationId,
+		seq: doc.seq,
+		input: fromBson(doc.input),
+		createdAt: doc.createdAt
+	});
+	const list = async (conversationId) => {
+		return (await col.find({ conversationId }).sort({ seq: 1 }).toArray()).map(toItem);
+	};
+	/**
+	* 插一条。`(conversationId, seq)` 上有唯一索引，撞号会抛 11000（duplicate key）——
+	* 返回 false 让调用方换号重来，其余错误照常往外抛。
+	*/
+	const insert = async (item) => {
+		try {
+			await col.insertOne({
+				_id: item.id,
+				conversationId: item.conversationId,
+				seq: item.seq,
+				input: toBson(item.input),
+				createdAt: item.createdAt
+			});
+			return true;
+		} catch (error) {
+			if (isDuplicateKeyError(error)) return false;
+			throw error;
+		}
+	};
+	return {
+		async enqueue(conversationId, input, opts) {
+			for (let attempt = 0; attempt < ENQUEUE_MAX_ATTEMPTS; attempt += 1) {
+				const current = await list(conversationId);
+				if (current.length >= opts.max) {
+					if (opts.onFull === "reject") return {
+						ok: false,
+						reason: "full",
+						queue: current
+					};
+					const oldest = current[0];
+					if (oldest !== void 0) await col.deleteOne({ _id: oldest.id });
+				}
+				const item = {
+					id: crypto.randomUUID(),
+					conversationId,
+					seq: (current.at(-1)?.seq ?? 0) + 1,
+					input,
+					createdAt: Date.now()
+				};
+				if (!await insert(item)) continue;
+				const after = await list(conversationId);
+				if (opts.onFull === "reject" && after.length > opts.max) {
+					await col.deleteOne({ _id: item.id });
+					return {
+						ok: false,
+						reason: "full",
+						queue: await list(conversationId)
+					};
+				}
+				return {
+					ok: true,
+					queued: item,
+					queue: after
+				};
+			}
+			return {
+				ok: false,
+				reason: "full",
+				queue: await list(conversationId)
+			};
+		},
+		async dequeue(conversationId) {
+			const doc = await col.findOneAndDelete({ conversationId }, { sort: { seq: 1 } });
+			if (doc === null) return {
+				item: void 0,
+				queue: []
+			};
+			return {
+				item: toItem(doc),
+				queue: await list(conversationId)
+			};
+		},
+		list,
+		async remove(conversationId, id) {
+			return {
+				removed: (await col.deleteOne({
+					conversationId,
+					_id: id
+				})).deletedCount > 0,
+				queue: await list(conversationId)
+			};
+		},
+		async clear(conversationId) {
+			await col.deleteMany({ conversationId });
+			return [];
+		},
+		async requeueFront(conversationId, item) {
+			for (let attempt = 0; attempt < ENQUEUE_MAX_ATTEMPTS; attempt += 1) {
+				const head = (await list(conversationId))[0];
+				const seq = head === void 0 ? item.seq : Math.min(item.seq, head.seq - 1) - attempt;
+				if (await insert({
+					...item,
+					conversationId,
+					seq
+				})) break;
+			}
+			return await list(conversationId);
+		}
+	};
+}
+//#endregion
+//#region src/migrate.ts
+/** 同名索引已存在但选项不同时 Mongo 报的两个 code。 */
+const INDEX_CONFLICT_CODES = /* @__PURE__ */ new Set([85, 86]);
+function isIndexConflict(error) {
+	return typeof error === "object" && error !== null && "code" in error && typeof error.code === "number" && INDEX_CONFLICT_CODES.has(error.code);
+}
+/**
+* 建一个具名索引，**同名不同选项时删了重建**。
+*
+* 这是 `migrate()` 唯一做的一点「演进」，范围限定在本包自己那三个具名索引上：不这么做
+* 的话，任何一次索引选项的变更（比如队列索引从非唯一改成唯一）都会让老库上的
+* `migrate()` 抛 `IndexOptionsConflict` 而启动失败——而 `migrate()` 对外承诺是幂等的。
+*
+* 重建可能失败（存量数据违反新的唯一性），那时照常抛——那种情况需要人介入，不该静默。
+*/
+async function ensureIndex(db, collection, keys, options) {
+	try {
+		await db.collection(collection).createIndex(keys, options);
+	} catch (error) {
+		if (!isIndexConflict(error)) throw error;
+		await db.collection(collection).dropIndex(options.name);
+		await db.collection(collection).createIndex(keys, options);
+	}
+}
+async function migrate(db) {
+	await Promise.all([
+		ensureIndex(db, LEDGER_COLLECTION, {
+			conversationId: 1,
+			seq: 1
+		}, {
+			unique: true,
+			name: "agent_ledger_conversation_seq"
+		}),
+		ensureIndex(db, DECISIONS_COLLECTION, {
+			conversationId: 1,
+			toolCallId: 1
+		}, {
+			unique: true,
+			name: "agent_decisions_conversation_call"
+		}),
+		ensureIndex(db, QUEUE_COLLECTION, {
+			conversationId: 1,
+			seq: 1
+		}, {
+			unique: true,
+			name: "agent_queue_conversation_seq"
+		})
+	]);
+}
+//#endregion
+//#region src/index.ts
+const RUNKO_PERSIST_MONGO_VERSION = "0.0.0";
+/**
+* 把一个 MongoDB `Db` 装成 `Persistence`。
+*
+* **吃 `Db` 而不是 `MongoClient`**：选哪个 database 是宿主的决定（多租户可能一租户
+* 一个 db），连接的生命周期也归宿主管——本包不 connect、不 close。
+*
+* 三个集合固定叫 `agent_ledger` / `agent_decisions` / `agent_queue`，你自己的集合
+* 照常在同一个 db 里，互不干扰。
+*/
+function mongoPersistence(db) {
+	return {
+		ledger: createLedgerStore(db),
+		decisions: createDecisionStore(db),
+		queue: createQueueStore(db)
+	};
+}
+//#endregion
+exports.DECISIONS_COLLECTION = DECISIONS_COLLECTION;
+exports.LEDGER_COLLECTION = LEDGER_COLLECTION;
+exports.QUEUE_COLLECTION = QUEUE_COLLECTION;
+exports.RUNKO_PERSIST_MONGO_VERSION = RUNKO_PERSIST_MONGO_VERSION;
+exports.migrate = migrate;
+exports.mongoPersistence = mongoPersistence;

package/dist/index.d.cts

@@ -0,0 +1,63 @@
+import { Persistence } from "@runko/agent";
+import { Db } from "mongodb";
+import { JsonValue } from "@runko/core";
+//#region src/collections.d.ts
+declare const LEDGER_COLLECTION = "agent_ledger";
+declare const DECISIONS_COLLECTION = "agent_decisions";
+declare const QUEUE_COLLECTION = "agent_queue";
+/**
+ * [账本](../../../docs/terms.md)文档。
+ *
+ * **不用复合 `_id`**（`{_id: {conversationId, seq}}`）虽然那样能白捡唯一性——因为
+ * 嵌套文档的 `_id` 是**整体**建索引的，`{"_id.conversationId": x}` 这种查询用不上它。
+ * 改成显式字段 + 一个唯一复合索引（`migrate()` 建），查询才走得了索引。
+ */
+interface LedgerDoc {
+  conversationId: string;
+  /** 每会话递增，由[归属仲裁](../../../docs/terms.md)分配。**允许有空洞**。 */
+  seq: number;
+  /** `RunkoUIMessage`。以 BSON 文档存（不是字符串）——Mongo 的原生形态，工具里看得见。 */
+  payload: JsonValue;
+  ts: number;
+}
+/** [裁决表](../../../docs/terms.md)文档。`decidedAt` 为 `null` 即「尚未 settle」。 */
+interface DecisionDoc {
+  conversationId: string;
+  toolCallId: string;
+  kind: string;
+  toolName: string | null;
+  payload: JsonValue | null;
+  outcome: string | null;
+  scope: string | null;
+  decidedBy: string | null;
+  message: string | null;
+  requestedAt: number;
+  decidedAt: number | null;
+}
+/** [待发队列](../../../docs/terms.md)文档。`_id` 直接用队列条目自己的 id。 */
+interface QueueDoc {
+  _id: string;
+  conversationId: string;
+  /** 入队顺序，**不与账本 seq 共享空间**。 */
+  seq: number;
+  input: JsonValue;
+  createdAt: number;
+}
+//#endregion
+//#region src/migrate.d.ts
+declare function migrate(db: Db): Promise<void>;
+//#endregion
+//#region src/index.d.ts
+declare const RUNKO_PERSIST_MONGO_VERSION: "0.0.0";
+/**
+ * 把一个 MongoDB `Db` 装成 `Persistence`。
+ *
+ * **吃 `Db` 而不是 `MongoClient`**：选哪个 database 是宿主的决定（多租户可能一租户
+ * 一个 db），连接的生命周期也归宿主管——本包不 connect、不 close。
+ *
+ * 三个集合固定叫 `agent_ledger` / `agent_decisions` / `agent_queue`，你自己的集合
+ * 照常在同一个 db 里，互不干扰。
+ */
+declare function mongoPersistence(db: Db): Persistence;
+//#endregion
+export { DECISIONS_COLLECTION, type DecisionDoc, LEDGER_COLLECTION, type LedgerDoc, QUEUE_COLLECTION, type QueueDoc, RUNKO_PERSIST_MONGO_VERSION, migrate, mongoPersistence };

package/dist/index.d.ts

@@ -0,0 +1,63 @@
+import { Persistence } from "@runko/agent";
+import { Db } from "mongodb";
+import { JsonValue } from "@runko/core";
+//#region src/collections.d.ts
+declare const LEDGER_COLLECTION = "agent_ledger";
+declare const DECISIONS_COLLECTION = "agent_decisions";
+declare const QUEUE_COLLECTION = "agent_queue";
+/**
+ * [账本](../../../docs/terms.md)文档。
+ *
+ * **不用复合 `_id`**（`{_id: {conversationId, seq}}`）虽然那样能白捡唯一性——因为
+ * 嵌套文档的 `_id` 是**整体**建索引的，`{"_id.conversationId": x}` 这种查询用不上它。
+ * 改成显式字段 + 一个唯一复合索引（`migrate()` 建），查询才走得了索引。
+ */
+interface LedgerDoc {
+  conversationId: string;
+  /** 每会话递增，由[归属仲裁](../../../docs/terms.md)分配。**允许有空洞**。 */
+  seq: number;
+  /** `RunkoUIMessage`。以 BSON 文档存（不是字符串）——Mongo 的原生形态，工具里看得见。 */
+  payload: JsonValue;
+  ts: number;
+}
+/** [裁决表](../../../docs/terms.md)文档。`decidedAt` 为 `null` 即「尚未 settle」。 */
+interface DecisionDoc {
+  conversationId: string;
+  toolCallId: string;
+  kind: string;
+  toolName: string | null;
+  payload: JsonValue | null;
+  outcome: string | null;
+  scope: string | null;
+  decidedBy: string | null;
+  message: string | null;
+  requestedAt: number;
+  decidedAt: number | null;
+}
+/** [待发队列](../../../docs/terms.md)文档。`_id` 直接用队列条目自己的 id。 */
+interface QueueDoc {
+  _id: string;
+  conversationId: string;
+  /** 入队顺序，**不与账本 seq 共享空间**。 */
+  seq: number;
+  input: JsonValue;
+  createdAt: number;
+}
+//#endregion
+//#region src/migrate.d.ts
+declare function migrate(db: Db): Promise<void>;
+//#endregion
+//#region src/index.d.ts
+declare const RUNKO_PERSIST_MONGO_VERSION: "0.0.0";
+/**
+ * 把一个 MongoDB `Db` 装成 `Persistence`。
+ *
+ * **吃 `Db` 而不是 `MongoClient`**：选哪个 database 是宿主的决定（多租户可能一租户
+ * 一个 db），连接的生命周期也归宿主管——本包不 connect、不 close。
+ *
+ * 三个集合固定叫 `agent_ledger` / `agent_decisions` / `agent_queue`，你自己的集合
+ * 照常在同一个 db 里，互不干扰。
+ */
+declare function mongoPersistence(db: Db): Persistence;
+//#endregion
+export { DECISIONS_COLLECTION, type DecisionDoc, LEDGER_COLLECTION, type LedgerDoc, QUEUE_COLLECTION, type QueueDoc, RUNKO_PERSIST_MONGO_VERSION, migrate, mongoPersistence };

package/dist/index.js

@@ -0,0 +1,363 @@
+//#region src/collections.ts
+const LEDGER_COLLECTION = "agent_ledger";
+const DECISIONS_COLLECTION = "agent_decisions";
+const QUEUE_COLLECTION = "agent_queue";
+/**
+* **写进 BSON 之前先过一遍 JSON。**
+*
+* 这一步不是多余的，它修的是一个实测出来的行为差异：BSON 会把 `undefined` **存成
+* `null`**，而 SQL 那几家走的是 `JSON.stringify`（**直接把这个键丢掉**）。同一个
+* `RunkoUIMessage` 存进去、读出来，Mongo 给 `{cachedInputTokens: null}`、SQLite 给
+* `{}`——一致性套件的「原样往返」当场就会红。
+*
+* 修法有两条，选了这条：
+*
+* | | 怎么做 | 为什么不选 |
+* |---|---|---|
+* | 客户端开 `ignoreUndefined` | `new MongoClient(url, { ignoreUndefined: true })` | **客户端是宿主建的**，我们只拿到 `Db`，管不着它怎么建的 |
+* | ✅ 自己先 JSON 归一 | `JSON.parse(JSON.stringify(v))` | —— |
+*
+* 选后者还有一个额外好处：它让 Mongo 这一档的语义**可证地**与 SQL 那几家一致
+* ——因为它做的就是那几家在做的同一件事。
+*/
+function toBson(value) {
+	return JSON.parse(JSON.stringify(value ?? null));
+}
+/**
+* 读回来直接用——**不需要反向转换**。
+*
+* 存进去的已经是 JSON 归一过的纯数据，Mongo 原样给回来。数字、字符串、嵌套对象、
+* 数组都实测过原样往返（含 `Number.MAX_SAFE_INTEGER` 与浮点）。
+*
+* 留这个函数是为了让「读」这一侧有个明确的边界名字，将来真要加什么（比如剥掉
+* driver 塞进来的 `_id`）有地方放。
+*
+* ⚠️ **这是一处刻意的类型逃逸，范围仅限本函数。** 驱动把 BSON 文档的字段给成
+* `unknown`（它无法知道我们存了什么形状），而这一层唯一能做的就是把它交还给调用方。
+* 泛型 `as` 意味着**本边界上没有类型检查**——所以真正需要保证形状的地方必须自己校验：
+* 队列的 `input` 走 `decodeTurnInput`（zod）；账本的 `payload` 由 core 在
+* `createSession({ resume })` 里跑 `validateUIMessages` 兜住。别把这个函数当成
+* 「安全的转换」到处用。
+*/
+function fromBson(value) {
+	return value;
+}
+//#endregion
+//#region src/stores.ts
+const OK = { ok: true };
+/** 重复键。并发 upsert 撞同一个唯一索引时驱动抛这个，见 `upsertOnce`。 */
+const DUPLICATE_KEY = 11e3;
+function isDuplicateKeyError(error) {
+	return typeof error === "object" && error !== null && "code" in error && error.code === DUPLICATE_KEY;
+}
+/**
+* 幂等插入的**兜底那一半**：吞掉重复键，其余错误照抛。
+*
+* 幂等本身靠 `upsert` + `$setOnInsert`（在调用点写），不靠异常——「先查再插」有竞态
+* 窗口，「插了 catch」会把真正的写失败也一起吞掉。
+*
+* 但 `upsert` 在并发下**仍可能抛重复键**：两个请求同时发现不存在、同时插，唯一索引
+* 挡下后一个。这是 MongoDB 明确记录的行为，不是 bug。那一支的结果照样是「已经有了
+* 一行」——契约要的是「不得写出两行」，满足了，所以吞掉。
+*
+* **只包异常处理、不包 `updateOne` 本身**是刻意的：这样 `$setOnInsert` 的字段能在
+* **具体的调用点**跟具体的文档类型对上，写错字段当场编译不过。包成一个泛型 helper
+* 反而会把类型冲开、逼出一个 `as`。
+*/
+async function ignoringDuplicateKey(write) {
+	try {
+		return await write();
+	} catch (error) {
+		if (!isDuplicateKeyError(error)) throw error;
+		return;
+	}
+}
+function createLedgerStore(db) {
+	const col = db.collection(LEDGER_COLLECTION);
+	return {
+		async append(entry) {
+			if ((await ignoringDuplicateKey(() => col.updateOne({
+				conversationId: entry.conversationId,
+				seq: entry.seq
+			}, { $setOnInsert: {
+				payload: toBson(entry.message),
+				ts: entry.ts
+			} }, { upsert: true })))?.upsertedCount === 1) return OK;
+			const existing = await col.findOne({
+				conversationId: entry.conversationId,
+				seq: entry.seq
+			}, { projection: { _id: 0 } });
+			if (existing !== null && fromBson(existing.payload).id === entry.message.id) return OK;
+			return {
+				ok: false,
+				reason: "rejected"
+			};
+		},
+		async read(conversationId, opts) {
+			const filter = opts?.afterSeq === void 0 ? { conversationId } : {
+				conversationId,
+				seq: { $gt: opts.afterSeq }
+			};
+			return (await col.find(filter, { projection: { _id: 0 } }).sort({ seq: 1 }).toArray()).map((doc) => ({
+				conversationId: doc.conversationId,
+				seq: doc.seq,
+				message: fromBson(doc.payload),
+				ts: doc.ts
+			}));
+		},
+		async maxSeq(conversationId) {
+			return (await col.findOne({ conversationId }, {
+				sort: { seq: -1 },
+				projection: {
+					seq: 1,
+					_id: 0
+				}
+			}))?.seq ?? 0;
+		}
+	};
+}
+function isOutcome(value) {
+	return value === "allow" || value === "deny" || value === "answered" || value === "timeout";
+}
+/** 可选字段一律「有才放进去」——`exactOptionalPropertyTypes` 下不能给 `undefined`。 */
+function toRecord(doc) {
+	return {
+		conversationId: doc.conversationId,
+		toolCallId: doc.toolCallId,
+		kind: doc.kind === "question" ? "question" : "approval",
+		...doc.toolName !== null ? { toolName: doc.toolName } : {},
+		...doc.payload !== null ? { payload: fromBson(doc.payload) } : {},
+		...isOutcome(doc.outcome) ? { outcome: doc.outcome } : {},
+		...doc.scope === "once" || doc.scope === "conversation" ? { scope: doc.scope } : {},
+		...doc.decidedBy !== null ? { decidedBy: doc.decidedBy } : {},
+		...doc.message !== null ? { message: doc.message } : {},
+		requestedAt: doc.requestedAt,
+		...doc.decidedAt !== null ? { decidedAt: doc.decidedAt } : {}
+	};
+}
+function createDecisionStore(db) {
+	const col = db.collection(DECISIONS_COLLECTION);
+	return {
+		async record(entry) {
+			await ignoringDuplicateKey(() => col.updateOne({
+				conversationId: entry.conversationId,
+				toolCallId: entry.toolCallId
+			}, { $setOnInsert: {
+				kind: entry.kind,
+				toolName: entry.toolName ?? null,
+				payload: entry.payload === void 0 ? null : toBson(entry.payload),
+				outcome: entry.outcome ?? null,
+				scope: entry.scope ?? null,
+				decidedBy: entry.decidedBy ?? null,
+				message: entry.message ?? null,
+				requestedAt: entry.requestedAt,
+				decidedAt: entry.decidedAt ?? null
+			} }, { upsert: true }));
+			return OK;
+		},
+		async settle(conversationId, toolCallId, settlement) {
+			return (await col.updateOne({
+				conversationId,
+				toolCallId,
+				decidedAt: null
+			}, { $set: {
+				outcome: settlement.outcome ?? null,
+				scope: settlement.scope ?? null,
+				decidedBy: settlement.decidedBy ?? null,
+				message: settlement.message ?? null,
+				decidedAt: settlement.decidedAt
+			} })).matchedCount > 0;
+		},
+		async listPending(conversationId) {
+			return (await col.find({
+				conversationId,
+				decidedAt: null
+			}, { projection: { _id: 0 } }).sort({ requestedAt: 1 }).toArray()).map(toRecord);
+		}
+	};
+}
+/** `enqueue` / `requeueFront` 撞号时的重试上限——够覆盖真实并发，又不会在病态负载下无限转。 */
+const ENQUEUE_MAX_ATTEMPTS = 5;
+function createQueueStore(db) {
+	const col = db.collection(QUEUE_COLLECTION);
+	const toItem = (doc) => ({
+		id: doc._id,
+		conversationId: doc.conversationId,
+		seq: doc.seq,
+		input: fromBson(doc.input),
+		createdAt: doc.createdAt
+	});
+	const list = async (conversationId) => {
+		return (await col.find({ conversationId }).sort({ seq: 1 }).toArray()).map(toItem);
+	};
+	/**
+	* 插一条。`(conversationId, seq)` 上有唯一索引，撞号会抛 11000（duplicate key）——
+	* 返回 false 让调用方换号重来，其余错误照常往外抛。
+	*/
+	const insert = async (item) => {
+		try {
+			await col.insertOne({
+				_id: item.id,
+				conversationId: item.conversationId,
+				seq: item.seq,
+				input: toBson(item.input),
+				createdAt: item.createdAt
+			});
+			return true;
+		} catch (error) {
+			if (isDuplicateKeyError(error)) return false;
+			throw error;
+		}
+	};
+	return {
+		async enqueue(conversationId, input, opts) {
+			for (let attempt = 0; attempt < ENQUEUE_MAX_ATTEMPTS; attempt += 1) {
+				const current = await list(conversationId);
+				if (current.length >= opts.max) {
+					if (opts.onFull === "reject") return {
+						ok: false,
+						reason: "full",
+						queue: current
+					};
+					const oldest = current[0];
+					if (oldest !== void 0) await col.deleteOne({ _id: oldest.id });
+				}
+				const item = {
+					id: crypto.randomUUID(),
+					conversationId,
+					seq: (current.at(-1)?.seq ?? 0) + 1,
+					input,
+					createdAt: Date.now()
+				};
+				if (!await insert(item)) continue;
+				const after = await list(conversationId);
+				if (opts.onFull === "reject" && after.length > opts.max) {
+					await col.deleteOne({ _id: item.id });
+					return {
+						ok: false,
+						reason: "full",
+						queue: await list(conversationId)
+					};
+				}
+				return {
+					ok: true,
+					queued: item,
+					queue: after
+				};
+			}
+			return {
+				ok: false,
+				reason: "full",
+				queue: await list(conversationId)
+			};
+		},
+		async dequeue(conversationId) {
+			const doc = await col.findOneAndDelete({ conversationId }, { sort: { seq: 1 } });
+			if (doc === null) return {
+				item: void 0,
+				queue: []
+			};
+			return {
+				item: toItem(doc),
+				queue: await list(conversationId)
+			};
+		},
+		list,
+		async remove(conversationId, id) {
+			return {
+				removed: (await col.deleteOne({
+					conversationId,
+					_id: id
+				})).deletedCount > 0,
+				queue: await list(conversationId)
+			};
+		},
+		async clear(conversationId) {
+			await col.deleteMany({ conversationId });
+			return [];
+		},
+		async requeueFront(conversationId, item) {
+			for (let attempt = 0; attempt < ENQUEUE_MAX_ATTEMPTS; attempt += 1) {
+				const head = (await list(conversationId))[0];
+				const seq = head === void 0 ? item.seq : Math.min(item.seq, head.seq - 1) - attempt;
+				if (await insert({
+					...item,
+					conversationId,
+					seq
+				})) break;
+			}
+			return await list(conversationId);
+		}
+	};
+}
+//#endregion
+//#region src/migrate.ts
+/** 同名索引已存在但选项不同时 Mongo 报的两个 code。 */
+const INDEX_CONFLICT_CODES = /* @__PURE__ */ new Set([85, 86]);
+function isIndexConflict(error) {
+	return typeof error === "object" && error !== null && "code" in error && typeof error.code === "number" && INDEX_CONFLICT_CODES.has(error.code);
+}
+/**
+* 建一个具名索引，**同名不同选项时删了重建**。
+*
+* 这是 `migrate()` 唯一做的一点「演进」，范围限定在本包自己那三个具名索引上：不这么做
+* 的话，任何一次索引选项的变更（比如队列索引从非唯一改成唯一）都会让老库上的
+* `migrate()` 抛 `IndexOptionsConflict` 而启动失败——而 `migrate()` 对外承诺是幂等的。
+*
+* 重建可能失败（存量数据违反新的唯一性），那时照常抛——那种情况需要人介入，不该静默。
+*/
+async function ensureIndex(db, collection, keys, options) {
+	try {
+		await db.collection(collection).createIndex(keys, options);
+	} catch (error) {
+		if (!isIndexConflict(error)) throw error;
+		await db.collection(collection).dropIndex(options.name);
+		await db.collection(collection).createIndex(keys, options);
+	}
+}
+async function migrate(db) {
+	await Promise.all([
+		ensureIndex(db, LEDGER_COLLECTION, {
+			conversationId: 1,
+			seq: 1
+		}, {
+			unique: true,
+			name: "agent_ledger_conversation_seq"
+		}),
+		ensureIndex(db, DECISIONS_COLLECTION, {
+			conversationId: 1,
+			toolCallId: 1
+		}, {
+			unique: true,
+			name: "agent_decisions_conversation_call"
+		}),
+		ensureIndex(db, QUEUE_COLLECTION, {
+			conversationId: 1,
+			seq: 1
+		}, {
+			unique: true,
+			name: "agent_queue_conversation_seq"
+		})
+	]);
+}
+//#endregion
+//#region src/index.ts
+const RUNKO_PERSIST_MONGO_VERSION = "0.0.0";
+/**
+* 把一个 MongoDB `Db` 装成 `Persistence`。
+*
+* **吃 `Db` 而不是 `MongoClient`**：选哪个 database 是宿主的决定（多租户可能一租户
+* 一个 db），连接的生命周期也归宿主管——本包不 connect、不 close。
+*
+* 三个集合固定叫 `agent_ledger` / `agent_decisions` / `agent_queue`，你自己的集合
+* 照常在同一个 db 里，互不干扰。
+*/
+function mongoPersistence(db) {
+	return {
+		ledger: createLedgerStore(db),
+		decisions: createDecisionStore(db),
+		queue: createQueueStore(db)
+	};
+}
+//#endregion
+export { DECISIONS_COLLECTION, LEDGER_COLLECTION, QUEUE_COLLECTION, RUNKO_PERSIST_MONGO_VERSION, migrate, mongoPersistence };

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@runko/persist-mongo",
+  "version": "0.1.0",
+  "description": "持久化实现：MongoDB —— 第一个非关系型实现，直接落在三个领域接口上",
+  "type": "module",
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@runko/agent": "^0.1.0",
+    "@runko/core": "^0.1.0"
+  },
+  "peerDependencies": {
+    "mongodb": "^7"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "mongodb": "^7.5.0",
+    "tsdown": "^0.22.4",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10",
+    "@runko/conformance": "^0.1.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint . --report-unused-disable-directives --max-warnings 0",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run"
+  }
+}