@modusensus/dsh-mneme 0.13.0 → 0.14.0-beta.2

package/lib/diary/rollover.js

@@ -1,61 +1,61 @@
-/**
- * 跨天判定：本机没有日历调度原语（cordis.patch.yml 没有 schedules 服务，
- * node_modules 里唯一的 scheduler 是 React 那个），所以「每天 0 点写一篇」写不出来。
- *
- * 可实现的等价形态是**跨天惰性判定**：在 turn/end 与插件启动两个既有挂载点上问
- * 「上一次写的日期是不是今天」，不是才写。差别只在于「今天一句话没说」那天没有日记
- * ——而那恰好是对的：没有素材就不该编。
- *
- * 全部是纯函数（时间由调用方注入），所以「跨 5 天只补 1 天」这类边界能被真的测出来。
- */
-
-/** 宿主本地时区的 `YYYY-MM-DD`。刻意不用 UTC：日记的「今天」是用户感知的今天。 */
-export function localDateString(date) {
-  const d = date instanceof Date ? date : new Date(date);
-  const y = d.getFullYear();
-  const m = String(d.getMonth() + 1).padStart(2, "0");
-  const day = String(d.getDate()).padStart(2, "0");
-  return `${y}-${m}-${day}`;
-}
-
-function toUtcMs(dateLocal) {
-  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(String(dateLocal ?? ""));
-  if (!m) return null;
-  return Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
-}
-
-/** `to - from` 的整数天数；任一参数形状不对返回 null（调用方据此走「当作首次」）。 */
-export function dayGap(fromDate, toDate) {
-  const a = toUtcMs(fromDate);
-  const b = toUtcMs(toDate);
-  if (a === null || b === null) return null;
-  return Math.round((b - a) / 86400000);
-}
-
-/** 一次最多回补几天。默认 1：睡得久一点就补一篇，不该醒来一次补十篇把模型配额烧光。 */
-export const MAX_CATCH_UP_DAYS = 1;
-
-/**
- * 今天该不该写。
- *
- * 返回 `{roll, gapDays, gap}`：
- * - `roll` 要不要写。`lastDate` 为空（从没写过）→ 写。
- * - `gapDays` 距上次写的天数（null = 没写过或日期形状不对）。
- * - `gap` 中间有没有「永久丢掉」的日子（超过回补上限）——必须如实写进日记头部，
- *   不能假装连续。这是本模块唯一允许对读者撒谎的地方，所以它必须是个返回值，
- *   不是一个可选参数。
- *
- * 时钟往回调（`lastDate` 比今天还新）时不写：那不是「跨天」，那是同一份时间被
- * 重算了一次，再写一次只会覆盖掉今天已经写好的那篇。
- */
-export function shouldRollDay(lastDate, today, { maxCatchUpDays = MAX_CATCH_UP_DAYS } = {}) {
-  const now = String(today ?? "");
-  if (!/^\d{4}-\d{2}-\d{2}$/.test(now)) return { roll: false, gapDays: null, gap: false };
-  const last = String(lastDate ?? "");
-  if (!/^\d{4}-\d{2}-\d{2}$/.test(last)) return { roll: true, gapDays: null, gap: false };
-  if (last === now) return { roll: false, gapDays: 0, gap: false };
-  const gapDays = dayGap(last, now);
-  if (gapDays === null || gapDays < 0) return { roll: false, gapDays, gap: false };
-  const limit = Number.isFinite(maxCatchUpDays) && maxCatchUpDays >= 0 ? maxCatchUpDays : MAX_CATCH_UP_DAYS;
-  return { roll: true, gapDays, gap: gapDays > limit };
-}
+/**
+ * 跨天判定：本机没有日历调度原语（cordis.patch.yml 没有 schedules 服务，
+ * node_modules 里唯一的 scheduler 是 React 那个），所以「每天 0 点写一篇」写不出来。
+ *
+ * 可实现的等价形态是**跨天惰性判定**：在 turn/end 与插件启动两个既有挂载点上问
+ * 「上一次写的日期是不是今天」，不是才写。差别只在于「今天一句话没说」那天没有日记
+ * ——而那恰好是对的：没有素材就不该编。
+ *
+ * 全部是纯函数（时间由调用方注入），所以「跨 5 天只补 1 天」这类边界能被真的测出来。
+ */
+
+/** 宿主本地时区的 `YYYY-MM-DD`。刻意不用 UTC：日记的「今天」是用户感知的今天。 */
+export function localDateString(date) {
+  const d = date instanceof Date ? date : new Date(date);
+  const y = d.getFullYear();
+  const m = String(d.getMonth() + 1).padStart(2, "0");
+  const day = String(d.getDate()).padStart(2, "0");
+  return `${y}-${m}-${day}`;
+}
+
+function toUtcMs(dateLocal) {
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(String(dateLocal ?? ""));
+  if (!m) return null;
+  return Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
+}
+
+/** `to - from` 的整数天数；任一参数形状不对返回 null（调用方据此走「当作首次」）。 */
+export function dayGap(fromDate, toDate) {
+  const a = toUtcMs(fromDate);
+  const b = toUtcMs(toDate);
+  if (a === null || b === null) return null;
+  return Math.round((b - a) / 86400000);
+}
+
+/** 一次最多回补几天。默认 1：睡得久一点就补一篇，不该醒来一次补十篇把模型配额烧光。 */
+export const MAX_CATCH_UP_DAYS = 1;
+
+/**
+ * 今天该不该写。
+ *
+ * 返回 `{roll, gapDays, gap}`：
+ * - `roll` 要不要写。`lastDate` 为空（从没写过）→ 写。
+ * - `gapDays` 距上次写的天数（null = 没写过或日期形状不对）。
+ * - `gap` 中间有没有「永久丢掉」的日子（超过回补上限）——必须如实写进日记头部，
+ *   不能假装连续。这是本模块唯一允许对读者撒谎的地方，所以它必须是个返回值，
+ *   不是一个可选参数。
+ *
+ * 时钟往回调（`lastDate` 比今天还新）时不写：那不是「跨天」，那是同一份时间被
+ * 重算了一次，再写一次只会覆盖掉今天已经写好的那篇。
+ */
+export function shouldRollDay(lastDate, today, { maxCatchUpDays = MAX_CATCH_UP_DAYS } = {}) {
+  const now = String(today ?? "");
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(now)) return { roll: false, gapDays: null, gap: false };
+  const last = String(lastDate ?? "");
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(last)) return { roll: true, gapDays: null, gap: false };
+  if (last === now) return { roll: false, gapDays: 0, gap: false };
+  const gapDays = dayGap(last, now);
+  if (gapDays === null || gapDays < 0) return { roll: false, gapDays, gap: false };
+  const limit = Number.isFinite(maxCatchUpDays) && maxCatchUpDays >= 0 ? maxCatchUpDays : MAX_CATCH_UP_DAYS;
+  return { roll: true, gapDays, gap: gapDays > limit };
+}

package/lib/diary/session-provider.js

@@ -1,122 +1,122 @@
-/**
- * 素材来源之二：当前会话自己的转录（**主来源**）。
- *
- * 需求原话是「与人格注入绑定，当前的拥有人格的 agent 写日记」——那就意味着日记的
- * 素材首先得是**这个 agent 自己这一天经历过的对话**，而不是 QQ 收件箱里别人的消息。
- * QQ inbox 只是没有会话上下文时（启动补写）的兜底来源。
- *
- * 口径与 summarize.js 的蒸馏转录**刻意同源**（那里已把隐私边界定完，不重写第二份）：
- * - 只认 `user/message` 与 `assistant/message`；
- * - 机器注入内容（AGENTS.md、skill 正文、文件变更通知）按 `source.kind` 挡掉；
- * - assistant 的 reasoning 私有思考块不采集（textOf 只认 `type:"text"`）；
- * - 工具调用/结果不进日记（那是过程，不是这一天发生的事）。
- *
- * 这个模块是纯的：会话对象由调用方给，时间由事件带，不读盘、不联网、不碰 ctx。
- */
-import { localDateString } from "./rollover.js";
-import { redactDigits } from "./qq-inbox.js";
-
-/** 单条消息进 prompt 的上限：一条超长粘贴不该把整篇日记的预算吃掉。 */
-export const MAX_ITEM_CHARS = 1200;
-
-/**
- * 会话身份（决定用哪张人格卡）。与 `src/inject.js:311-336` 同一口径。
- *
- * ⚠️ 不能先读 `requestHeader()`：那返回的是请求级模型路由头，会把 `agentPreset`
- * 遮蔽成空（scope.js 里记着本地 web 实测踩中过）。身份只在 `session.header` 里。
- */
-export function sessionAgentId(session) {
-  try {
-    const header = session?.header ?? null;
-    const preset = header?.agentPreset;
-    return typeof preset === "string" && preset.trim() ? preset.trim() : null;
-  } catch {
-    return null;
-  }
-}
-
-/** 会话事件里可选的时间字段。三个都试是因为宿主各版本用过不同的名字。 */
-function eventTimeMs(event) {
-  for (const key of ["at", "time", "ts"]) {
-    const v = event?.[key];
-    if (typeof v === "number" && Number.isFinite(v)) return v;
-    if (typeof v === "string" && v.trim()) {
-      const parsed = Date.parse(v);
-      if (Number.isFinite(parsed)) return parsed;
-    }
-  }
-  return null;
-}
-
-function textOf(content) {
-  if (typeof content === "string") return content;
-  if (!Array.isArray(content)) return "";
-  return content
-    .map((block) => (typeof block === "string" ? block : block && block.type === "text" && typeof block.text === "string" ? block.text : ""))
-    .filter(Boolean)
-    .join("\n");
-}
-
-/** 事件里有没有**可公开的会话正文**。与 summarize.js 的 publicTranscriptParts 同一套判据。 */
-function bodyOf(event) {
-  const data = event?.data ?? {};
-  const kind = data?.source?.kind;
-  if (event?.type === "user/message") {
-    // 机器注入内容（kind 非 user）不进素材：那不是「你们今天聊的」。
-    if (kind !== undefined && kind !== "user") return null;
-    const text = textOf(data?.content).trim();
-    return text ? { role: "user", text } : null;
-  }
-  if (event?.type === "assistant/message") {
-    const text = textOf(data?.message?.content).trim();
-    return text ? { role: "assistant", text } : null;
-  }
-  return null;
-}
-
-/**
- * 采当前会话的转录。
- *
- * `dateLocal` 为 null 时取**全部**事件（手动按钮的语义：「就把现在这段写下来」，
- * 不按自然日切）。给日期时只留那一天的事件——事件没有时间戳的一律丢弃：无法证明
- * 它属于今天，就不能把它写进今天。
- *
- * 返回 `{items, scanned, ignored}`（items 可以为空）或 `{error}`。
- */
-export function collectSessionTranscript({ session, dateLocal = null, maxItems = 400, maxChars = MAX_ITEM_CHARS } = {}) {
-  if (!session) return { error: "no-session" };
-  let events = null;
-  try {
-    events = typeof session.snapshotEvents === "function" ? session.snapshotEvents() : session.events;
-  } catch {
-    events = session?.events ?? null;
-  }
-  if (!Array.isArray(events)) return { error: "session-unreadable" };
-
-  const items = [];
-  let scanned = 0;
-  let ignored = 0;
-  for (const event of events) {
-    const body = bodyOf(event);
-    if (!body) {
-      // 工具调用/系统事件占了绝对多数，数进 ignored 会让「忽略」这个词失真。
-      // 只把它们跳过，不计入 ignored。
-      continue;
-    }
-    scanned += 1;
-    const ts = eventTimeMs(event);
-    if (dateLocal !== null && dateLocal !== undefined) {
-      if (ts === null || localDateString(new Date(ts)) !== dateLocal) {
-        // 别的日子不算「忽略」，无时间戳才算读不懂。
-        if (ts === null) ignored += 1;
-        continue;
-      }
-    }
-    items.push({
-      ts,
-      role: body.role,
-      text: redactDigits(body.text).slice(0, maxChars)
-    });
-  }
-  return { items: items.slice(-maxItems), scanned, ignored };
-}
+/**
+ * 素材来源之二：当前会话自己的转录（**主来源**）。
+ *
+ * 需求原话是「与人格注入绑定，当前的拥有人格的 agent 写日记」——那就意味着日记的
+ * 素材首先得是**这个 agent 自己这一天经历过的对话**，而不是 QQ 收件箱里别人的消息。
+ * QQ inbox 只是没有会话上下文时（启动补写）的兜底来源。
+ *
+ * 口径与 summarize.js 的蒸馏转录**刻意同源**（那里已把隐私边界定完，不重写第二份）：
+ * - 只认 `user/message` 与 `assistant/message`；
+ * - 机器注入内容（AGENTS.md、skill 正文、文件变更通知）按 `source.kind` 挡掉；
+ * - assistant 的 reasoning 私有思考块不采集（textOf 只认 `type:"text"`）；
+ * - 工具调用/结果不进日记（那是过程，不是这一天发生的事）。
+ *
+ * 这个模块是纯的：会话对象由调用方给，时间由事件带，不读盘、不联网、不碰 ctx。
+ */
+import { localDateString } from "./rollover.js";
+import { redactDigits } from "./qq-inbox.js";
+
+/** 单条消息进 prompt 的上限：一条超长粘贴不该把整篇日记的预算吃掉。 */
+export const MAX_ITEM_CHARS = 1200;
+
+/**
+ * 会话身份（决定用哪张人格卡）。与 `src/inject.js:311-336` 同一口径。
+ *
+ * ⚠️ 不能先读 `requestHeader()`：那返回的是请求级模型路由头，会把 `agentPreset`
+ * 遮蔽成空（scope.js 里记着本地 web 实测踩中过）。身份只在 `session.header` 里。
+ */
+export function sessionAgentId(session) {
+  try {
+    const header = session?.header ?? null;
+    const preset = header?.agentPreset;
+    return typeof preset === "string" && preset.trim() ? preset.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+/** 会话事件里可选的时间字段。三个都试是因为宿主各版本用过不同的名字。 */
+function eventTimeMs(event) {
+  for (const key of ["at", "time", "ts"]) {
+    const v = event?.[key];
+    if (typeof v === "number" && Number.isFinite(v)) return v;
+    if (typeof v === "string" && v.trim()) {
+      const parsed = Date.parse(v);
+      if (Number.isFinite(parsed)) return parsed;
+    }
+  }
+  return null;
+}
+
+function textOf(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .map((block) => (typeof block === "string" ? block : block && block.type === "text" && typeof block.text === "string" ? block.text : ""))
+    .filter(Boolean)
+    .join("\n");
+}
+
+/** 事件里有没有**可公开的会话正文**。与 summarize.js 的 publicTranscriptParts 同一套判据。 */
+function bodyOf(event) {
+  const data = event?.data ?? {};
+  const kind = data?.source?.kind;
+  if (event?.type === "user/message") {
+    // 机器注入内容（kind 非 user）不进素材：那不是「你们今天聊的」。
+    if (kind !== undefined && kind !== "user") return null;
+    const text = textOf(data?.content).trim();
+    return text ? { role: "user", text } : null;
+  }
+  if (event?.type === "assistant/message") {
+    const text = textOf(data?.message?.content).trim();
+    return text ? { role: "assistant", text } : null;
+  }
+  return null;
+}
+
+/**
+ * 采当前会话的转录。
+ *
+ * `dateLocal` 为 null 时取**全部**事件（手动按钮的语义：「就把现在这段写下来」，
+ * 不按自然日切）。给日期时只留那一天的事件——事件没有时间戳的一律丢弃：无法证明
+ * 它属于今天，就不能把它写进今天。
+ *
+ * 返回 `{items, scanned, ignored}`（items 可以为空）或 `{error}`。
+ */
+export function collectSessionTranscript({ session, dateLocal = null, maxItems = 400, maxChars = MAX_ITEM_CHARS } = {}) {
+  if (!session) return { error: "no-session" };
+  let events = null;
+  try {
+    events = typeof session.snapshotEvents === "function" ? session.snapshotEvents() : session.events;
+  } catch {
+    events = session?.events ?? null;
+  }
+  if (!Array.isArray(events)) return { error: "session-unreadable" };
+
+  const items = [];
+  let scanned = 0;
+  let ignored = 0;
+  for (const event of events) {
+    const body = bodyOf(event);
+    if (!body) {
+      // 工具调用/系统事件占了绝对多数，数进 ignored 会让「忽略」这个词失真。
+      // 只把它们跳过，不计入 ignored。
+      continue;
+    }
+    scanned += 1;
+    const ts = eventTimeMs(event);
+    if (dateLocal !== null && dateLocal !== undefined) {
+      if (ts === null || localDateString(new Date(ts)) !== dateLocal) {
+        // 别的日子不算「忽略」，无时间戳才算读不懂。
+        if (ts === null) ignored += 1;
+        continue;
+      }
+    }
+    items.push({
+      ts,
+      role: body.role,
+      text: redactDigits(body.text).slice(0, maxChars)
+    });
+  }
+  return { items: items.slice(-maxItems), scanned, ignored };
+}

package/lib/document-index.js

@@ -1,94 +1,94 @@
-// dsh-mneme/src/document-index.js
-// documentDir 的索引（issue #296 第二批）。`<documentDir>/index.md` 整文件机器所有，
-// 可从库随时重建：内容里没有任何「生成时间」，所以删掉再同步一次得到逐字节相同的
-// 文件（test/document-dir.test.js 钉住这一条）。
-//
-// 与镜像侧 documents.md 的分工（#296 第 2 节表格）：这里是 document 子系统自己的
-// 索引（id + 标题 + 定位 + managed 标记），那份是带 frontmatter 的镜像只读视图
-// （多一个摘要首句）。两份都只列指针行，都不含正文——正文永远在 doc_path 指向的
-// 文件里，那是 agent 的东西。
-import { readFileSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
-import { join } from "node:path";
-import { STR } from "./lang.js";
-import { isManagedDocumentPath } from "./document.js";
-
-function oneLine(text) {
-  return String(text ?? "").replace(/\s+/g, " ").trim();
-}
-
-/**
- * @param {string} dir resolved documentDir (see resolveDocumentDir)
- * @param {"zh"|"en"} language instance language, same as the mirror
- */
-export function createDocumentIndex(dir, language = "zh") {
-  const filePath = join(dir, "index.md");
-
-  /**
-   * Render the whole file from the given rows. Sorted updated_at DESC, id ASC:
-   * the same store state must always render the same bytes (rebuildable).
-   */
-  function render(memories) {
-    const items = (memories ?? []).slice().sort((a, b) => {
-      if (a.updated_at !== b.updated_at) return a.updated_at < b.updated_at ? 1 : -1;
-      return a.id < b.id ? -1 : 1;
-    });
-    const lines = [STR.documentIndexHeader[language]()];
-    for (const m of items) {
-      const where = isManagedDocumentPath(dir, m.doc_path) ? "managed" : "external";
-      // doc_path 理论上必带（store.saveDocument 是唯一铸造口），缺了就只写定位
-      // 标记，不编造路径。
-      const path = m.doc_path ? ` · \`${oneLine(m.doc_path)}\`` : "";
-      lines.push(`- \`${m.id}\` **${oneLine(m.title)}** · ${where}${path}`);
-    }
-    return `${lines.join("\n")}\n`;
-  }
-
-  /**
-   * Ensure the directory exists (recursive). Never throws: callers warn and move
-   * on — a managed directory that cannot be created must not fail plugin boot.
-   */
-  function ensure() {
-    try {
-      mkdirSync(dir, { recursive: true });
-      return { ok: true };
-    } catch (error) {
-      return { ok: false, error: error?.message ?? String(error) };
-    }
-  }
-
-  /**
-   * Write the index if it changed. Never throws: a failed index write must not
-   * fail the business write that triggered it (same fail-safe shape as
-   * mirror.sync). Returns { ok, changed } or { ok: false, error }.
-   */
-  function sync(memories) {
-    const text = render(memories);
-    let prev = null;
-    try { prev = readFileSync(filePath, "utf8"); } catch { /* first write */ }
-    if (prev === text) return { ok: true, changed: false };
-    const ready = ensure();
-    if (!ready.ok) return { ok: false, error: ready.error };
-    try {
-      writeFileSync(filePath, text, "utf8");
-      return { ok: true, changed: true };
-    } catch (error) {
-      return { ok: false, error: error?.message ?? String(error) };
-    }
-  }
-
-  /**
-   * Drop the index file (闸关时用）。闸关意味着 document 子系统整体退出，留一份
-   * 陈旧索引会列出已归档、已遗忘的指针行——正是 documents.md 在闸关时被镜像删掉
-   * 要避免的那种「看着还在、其实已关」的视图。删掉不从库取数，O(1)，也不抛。
-   */
-  function remove() {
-    try {
-      rmSync(filePath, { force: true });
-      return { ok: true };
-    } catch (error) {
-      return { ok: false, error: error?.message ?? String(error) };
-    }
-  }
-
-  return { filePath, render, sync, ensure, remove };
-}
+// dsh-mneme/src/document-index.js
+// documentDir 的索引（issue #296 第二批）。`<documentDir>/index.md` 整文件机器所有，
+// 可从库随时重建：内容里没有任何「生成时间」，所以删掉再同步一次得到逐字节相同的
+// 文件（test/document-dir.test.js 钉住这一条）。
+//
+// 与镜像侧 documents.md 的分工（#296 第 2 节表格）：这里是 document 子系统自己的
+// 索引（id + 标题 + 定位 + managed 标记），那份是带 frontmatter 的镜像只读视图
+// （多一个摘要首句）。两份都只列指针行，都不含正文——正文永远在 doc_path 指向的
+// 文件里，那是 agent 的东西。
+import { readFileSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { STR } from "./lang.js";
+import { isManagedDocumentPath } from "./document.js";
+
+function oneLine(text) {
+  return String(text ?? "").replace(/\s+/g, " ").trim();
+}
+
+/**
+ * @param {string} dir resolved documentDir (see resolveDocumentDir)
+ * @param {"zh"|"en"} language instance language, same as the mirror
+ */
+export function createDocumentIndex(dir, language = "zh") {
+  const filePath = join(dir, "index.md");
+
+  /**
+   * Render the whole file from the given rows. Sorted updated_at DESC, id ASC:
+   * the same store state must always render the same bytes (rebuildable).
+   */
+  function render(memories) {
+    const items = (memories ?? []).slice().sort((a, b) => {
+      if (a.updated_at !== b.updated_at) return a.updated_at < b.updated_at ? 1 : -1;
+      return a.id < b.id ? -1 : 1;
+    });
+    const lines = [STR.documentIndexHeader[language]()];
+    for (const m of items) {
+      const where = isManagedDocumentPath(dir, m.doc_path) ? "managed" : "external";
+      // doc_path 理论上必带（store.saveDocument 是唯一铸造口），缺了就只写定位
+      // 标记，不编造路径。
+      const path = m.doc_path ? ` · \`${oneLine(m.doc_path)}\`` : "";
+      lines.push(`- \`${m.id}\` **${oneLine(m.title)}** · ${where}${path}`);
+    }
+    return `${lines.join("\n")}\n`;
+  }
+
+  /**
+   * Ensure the directory exists (recursive). Never throws: callers warn and move
+   * on — a managed directory that cannot be created must not fail plugin boot.
+   */
+  function ensure() {
+    try {
+      mkdirSync(dir, { recursive: true });
+      return { ok: true };
+    } catch (error) {
+      return { ok: false, error: error?.message ?? String(error) };
+    }
+  }
+
+  /**
+   * Write the index if it changed. Never throws: a failed index write must not
+   * fail the business write that triggered it (same fail-safe shape as
+   * mirror.sync). Returns { ok, changed } or { ok: false, error }.
+   */
+  function sync(memories) {
+    const text = render(memories);
+    let prev = null;
+    try { prev = readFileSync(filePath, "utf8"); } catch { /* first write */ }
+    if (prev === text) return { ok: true, changed: false };
+    const ready = ensure();
+    if (!ready.ok) return { ok: false, error: ready.error };
+    try {
+      writeFileSync(filePath, text, "utf8");
+      return { ok: true, changed: true };
+    } catch (error) {
+      return { ok: false, error: error?.message ?? String(error) };
+    }
+  }
+
+  /**
+   * Drop the index file (闸关时用）。闸关意味着 document 子系统整体退出，留一份
+   * 陈旧索引会列出已归档、已遗忘的指针行——正是 documents.md 在闸关时被镜像删掉
+   * 要避免的那种「看着还在、其实已关」的视图。删掉不从库取数，O(1)，也不抛。
+   */
+  function remove() {
+    try {
+      rmSync(filePath, { force: true });
+      return { ok: true };
+    } catch (error) {
+      return { ok: false, error: error?.message ?? String(error) };
+    }
+  }
+
+  return { filePath, render, sync, ensure, remove };
+}