sage-mem 1.9.1 → 2.0.0

package/lib/index.js

@@ -23,6 +23,8 @@ import { parseAliases, parseBaseline, parseBaselinePriority, parseFrontmatter, p
 import { ageDays, bigrams, score, selectBaseline, selectRelevant } from './memory/retrieval.js'
 import { isReserved, nameKey, safeName } from './memory/naming.js'
 import { MEMORY_ARCHIVE_DIR, addArchiveMeta, extractTitle, inspectDir, inspectMemoryEntry, readArchivedMeta, readVerified, scanArchived, scanMemoryFiles, scanStars, shadowsReserved } from './memory/scan.js'
+import { listConflicts, patchConflict, readConflict, removeConflict, summarizeConflict } from './memory/conflicts.js'
+import { invalidateMemory, undoMemoryInvalidation } from './memory/arbitrate.js'
 import { archiveMemory, deleteArchivedMemory, restoreMemory } from './memory/archive.js'
 import { flushAccess, pickArchiveCandidates, readAccessLedger } from './memory/access.js'
 import { warnLog, writeFileAtomic } from './memory/util.js'
@@ -57,6 +59,10 @@ export class MemoryGateway extends TypertRemoteService {
     super(ctx, 'memory')
     // 一并挂载星图 remote（同一记忆目录，纯只读）—— starmap.* 服务
     new StarmapGateway(ctx)
+    // 2.0.0：冲突裁决入口（列表 / 读 / 标失效 / 驳回 / 撤销 / 删除记录）—— conflict.* 服务。
+    // 与 memory / starmap 分开成独立 namespace：混成一个面会让「读记忆」与「改记忆的有效性」
+    // 共用一张契约表，而后者是**写用户文件**的动作。
+    new ConflictGateway(ctx)
 
     // 四块挂载（1.2.0 从构造函数里搬出的四段）。顺序保持原样：
     // autodream → 检索工具 → 观测 → 写入门。
@@ -663,6 +669,189 @@ export class StarmapGateway extends TypertRemoteService {
 markRemote(StarmapGateway, 'listStars', 'listStars')
 markRemote(StarmapGateway, 'readFile', 'readFile')
 
+/**
+ * 2.0.0 的裁决入口：冲突队列的「可列、可读、可裁、可撤销」。
+ *
+ * 为什么单独一个 namespace（`conflict`）而不并进 `memory`：这一层会**写用户的记忆文件**
+ * （把 `invalid_at` 写进 frontmatter），而 memory 面是读写正文。两张契约表的失败语义、
+ * 危险等级都不同，混在一起只会让「读一下」和「改有效性」共用一个权限面。
+ *
+ * 四条硬约束（对应 `docs/2.0.0-plan.md` §5.5 / §7.3 / §7.6）：
+ *   1. **先写文件、后改记录**。反过来会出现「记录说已裁决、文件没改」的半态，
+ *      用户再也看不到它（记录已 resolved，文件仍照旧注入）。
+ *   2. `invalidate` 只能写**这条记录自己提到的那一方**（`file` / `otherFile`）——
+ *      防「借裁决入口写任意记忆文件」。文件名本身还要再过 `safeName` 闸门。
+ *   3. 失败一律返回对象、绝不抛；`ok` 只在真的做了报告里那件事时为 true。
+ *   4. 写路径走宿主 `fs.writeText`：版本守卫 + 逐次沙箱策略（收窄到记忆目录），
+ *      与 autodream 同一口径 —— `read-only` 不替用户翻案。
+ */
+export class ConflictGateway extends TypertRemoteService {
+  constructor(ctx) { super(ctx, 'conflict') }
+
+  /** 解析「这次要标的是哪一方」：只能是记录里的 file 或 otherFile，否则 null。 */
+  targetOf(record, requested) {
+    const file = typeof requested === 'string' && requested !== '' ? requested : record.file
+    if (file !== record.file && file !== record.otherFile) return null
+    return file
+  }
+
+  /** 列全部记录的**摘要**（不含两份正文：一份记录正文上限 96 KB，列表不该整批搬运）。 */
+  async list() {
+    const listed = await listConflicts({ stateRoot: STATE_ROOT })
+    if (!listed.ok) return { ok: false, code: listed.code, error: listed.error }
+    const items = listed.items.map(summarizeConflict)
+    return {
+      ok: true,
+      items,
+      broken: [...listed.broken],
+      ignored: [...listed.ignored],
+      counts: { open: items.filter((i) => i.status === 'open').length, total: items.length },
+    }
+  }
+
+  /** 读一条完整记录（含两份正文）。 */
+  async read(opts) {
+    const read = await readConflict(opts?.id, { stateRoot: STATE_ROOT })
+    if (!read.ok) return { ok: false, code: read.code, error: read.error }
+    return { ok: true, record: read.record, warnings: [...read.warnings] }
+  }
+
+  /**
+   * 把记录里的一方标为失效：写记忆 frontmatter 的 `invalid_at`（+ 指向另一方的
+   * `superseded_by`），**再**把记录改成已裁决。
+   *
+   * 幂等：同一方重复点，文件不重写（`invalidateMemory` 里判），记录也已 resolved，
+   * 直接回原收据。
+   */
+  async invalidate(opts) {
+    const read = await readConflict(opts?.id, { stateRoot: STATE_ROOT })
+    if (!read.ok) return { ok: false, code: read.code, error: read.error }
+    const record = read.record
+    if (record.kind !== 'contradiction') {
+      return {
+        ok: false,
+        code: 'invalid',
+        error: '只有矛盾型（contradiction）记录能标失效：写失败型的那份盘上内容仍是现行版本，标失效会把有效记忆藏起来',
+      }
+    }
+    const target = this.targetOf(record, opts?.file)
+    if (!target) {
+      return { ok: false, code: 'invalid', error: 'file 必须是这条记录里的 file 或 otherFile（不能借裁决入口写别的记忆）' }
+    }
+    if (record.status !== 'open') {
+      if (record.status === 'resolved' && record.decision === 'invalidate' && record.invalidatedFile === target) {
+        return {
+          ok: true,
+          record,
+          wrote: { file: target, invalidAt: record.decidedAt || '', version: record.appliedVersion || '' },
+        }
+      }
+      return { ok: false, code: 'invalid_transition', error: '这条记录已经裁决过了；要改判断先撤销，再重新裁决' }
+    }
+
+    // 事件时间由这一层给（纯函数不读时钟）：裁决时间就是失效时间 —— 用户此刻决定「从现在起不作数」。
+    const invalidAt = new Date().toISOString()
+    const otherFile = target === record.file ? record.otherFile : record.file
+    const written = await invalidateMemory(
+      { ctx: this.ctx, memoryDir: MEMORY_DIR },
+      { file: target, invalidAt, supersededBy: otherFile },
+    )
+    if (!written.ok) return { ok: false, code: written.code, error: written.error }
+
+    const patched = await patchConflict(
+      record.id,
+      {
+        status: 'resolved',
+        decision: 'invalidate',
+        decidedAt: invalidAt,
+        appliedVersion: written.version,
+        invalidatedFile: target,
+      },
+      { stateRoot: STATE_ROOT },
+    )
+    if (!patched.ok) {
+      // 文件已经改了、记录没改成 —— 这个方向是**可重试**的（再点一次幂等，只补记录），
+      // 与「记录已裁决、文件没改」相反。如实报失败，别把半态说成成功。
+      return {
+        ok: false,
+        code: patched.code,
+        error: `记忆已标失效，但冲突记录状态没更新成功（再点一次即可，写入是幂等的）：${patched.error ?? ''}`,
+      }
+    }
+    return { ok: true, record: patched.record, wrote: { file: written.file, invalidAt, version: written.version } }
+  }
+
+  /** 标记「看过、决定不管」：只改记录，不碰记忆文件。 */
+  async dismiss(opts) {
+    const read = await readConflict(opts?.id, { stateRoot: STATE_ROOT })
+    if (!read.ok) return { ok: false, code: read.code, error: read.error }
+    // 记录里的 `note` 是冲突的由来（写进记录那一刻的事实），裁决理由**不覆盖**它 ——
+    // 覆盖等于把证据改写成结论。
+    const patched = await patchConflict(
+      read.record.id,
+      { status: 'dismissed', decision: 'dismiss', decidedAt: new Date().toISOString() },
+      { stateRoot: STATE_ROOT },
+    )
+    if (!patched.ok) return { ok: false, code: patched.code, error: patched.error }
+    return { ok: true, record: patched.record }
+  }
+
+  /**
+   * 撤销失效：删掉 frontmatter 里那两行，再把记录退回「已驳回」。
+   *
+   * 状态机不允许回到 `open`（判断理由会丢），所以撤销后的落地状态是 `dismissed` ——
+   * 界面文案要说明「已撤销、记忆重新参与注入」，而不是「又变回待裁决」。
+   */
+  async undo(opts) {
+    const read = await readConflict(opts?.id, { stateRoot: STATE_ROOT })
+    if (!read.ok) return { ok: false, code: read.code, error: read.error }
+    const record = read.record
+    if (record.decision !== 'invalidate') {
+      return { ok: false, code: 'invalid_transition', error: '这条记录没有标过失效，没有可撤销的标记' }
+    }
+    const target = record.invalidatedFile || record.file
+    const cleared = await undoMemoryInvalidation({ ctx: this.ctx, memoryDir: MEMORY_DIR }, target)
+    if (!cleared.ok) return { ok: false, code: cleared.code, error: cleared.error }
+
+    const patched = await patchConflict(
+      record.id,
+      { status: 'dismissed', decision: '', decidedAt: '', appliedVersion: '', invalidatedFile: '' },
+      { stateRoot: STATE_ROOT },
+    )
+    if (!patched.ok) {
+      return {
+        ok: false,
+        code: patched.code,
+        error: `失效标记已撤销，但冲突记录状态没更新成功（再点一次即可，写入是幂等的）：${patched.error ?? ''}`,
+      }
+    }
+    return { ok: true, record: patched.record, cleared: { file: cleared.file } }
+  }
+
+  /**
+   * 删掉一条记录（清理；不动记忆文件本身）。危险动作，两段式确认在界面侧。
+   *
+   * ⚠️ 方法名**不能叫 `remove`**：DSH 的客户端 RemoteNamespaceService 是 Cordis Service 的
+   * 子类，`remove` 在它的原型上已被占用 —— 客户端声明同名方法会在 mountContribution 的
+   * `assertMethodAvailable` 直接抛错，**整个 client 插件 activate 失败**（不是单个按钮失效）。
+   * 2026-10-27 真机复现（`client api: method "conflict/remove" conflicts with its namespace service`）。
+   * 所以两端统一用 `removeRecord`，id 也一起改；契约不承诺 remote 方法名（契约 §7），
+   * 这条改名不影响对外承诺。
+   */
+  async removeRecord(opts) {
+    const removed = await removeConflict(opts?.id, { stateRoot: STATE_ROOT })
+    if (!removed.ok) return { ok: false, code: removed.code, error: removed.error }
+    return { ok: true }
+  }
+}
+
+markRemote(ConflictGateway, 'list', 'list')
+markRemote(ConflictGateway, 'read', 'read')
+markRemote(ConflictGateway, 'invalidate', 'invalidate')
+markRemote(ConflictGateway, 'dismiss', 'dismiss')
+markRemote(ConflictGateway, 'undo', 'undo')
+markRemote(ConflictGateway, 'removeRecord', 'removeRecord')
+
 /**
  * autodream 的 remote 面：设置页「自动做梦」标签页唯一的数据通道。
  *

package/lib/memory/arbitrate.js

@@ -0,0 +1,236 @@
+/**
+ * sage-mem 记忆层 —— 裁决写入（2.0.0 矛盾检测的写路径）。
+ *
+ * 「这条记忆不再作数」是一个**写进记忆文件 frontmatter 的事实**，不是旁路索引：
+ * 记忆目录自包含、可 git diff、状态根丢了标记还在（D29 Q2）。代价是这个写入碰的是
+ * **用户的记忆文件**，所以这里每一条都是硬约束（docs/2.0.0-plan.md §5.5）：
+ *
+ *   1. 幂等：同一份标记连写两次，第二次不写盘、不报错；
+ *   2. 不半份：原子写（宿主的 `fs.writeText`）；
+ *   3. 不动别的字节：只加/删 `invalid_at` / `superseded_by` 两行，键顺序、缩进、CRLF 原样；
+ *   4. 不改 `updated`：失效不是「文件被改过」，改了会让新鲜度提示说谎；
+ *   5. 给收据：成功返回 `{ok, file, invalidAt, version}`，失败返回 `{ok:false, code}`。
+ *
+ * 拆分：**纯函数**（`upsertValidityLines` / `removeValidityLines`）负责字节级改写，
+ * 能直接单测；**IO**（`invalidateMemory` / `undoMemoryInvalidation`）负责版本守卫、
+ * 沙箱策略与错误码。不读时钟 —— 裁决时间由调用方给（`nowIso` 的取值落在 Gateway 一层）。
+ */
+
+import { join } from 'node:path'
+import { inspectMemoryEntry, readVerified, yamlScalar } from './scan.js'
+import { safeName } from './naming.js'
+import { parseValidityTime } from './validity.js'
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/
+
+/** 失效标记的两行（只认顶层键：`metadata:` 嵌套块里同名的键不是我们的）。 */
+const VALIDITY_LINE_RE = /^(?:invalid_at|superseded_by):/
+
+function eolOf(text) {
+  const src = String(text ?? '')
+  const i = src.indexOf('\r\n')
+  if (i >= 0) return '\r\n'
+  return '\n'
+}
+
+/**
+ * 给 frontmatter 写（或更新）`invalid_at` / `superseded_by`。
+ *
+ * 写法与归档留痕（`scan.js` 的 `addArchiveMeta`）同一口径：**先剥旧行再插**，
+ * 免得同一份文件里出现两个 `invalid_at`。新行插在 frontmatter 末尾 ——
+ * 插在别处就要决定「放第几行」，而键顺序本身没有语义，末尾最不容易碰到别的字节。
+ *
+ * @param {string} content — 记忆全文
+ * @param {{invalidAt:string, supersededBy?:string}} input
+ * @returns {{ok:true, content:string, changed:boolean} | {ok:false, code:'invalid', error:string}}
+ */
+export function upsertValidityLines(content, input) {
+  if (typeof content !== 'string') return { ok: false, code: 'invalid', error: '记忆内容必须是字符串' }
+  const invalidAt = typeof input?.invalidAt === 'string' ? input.invalidAt.trim() : ''
+  if (!invalidAt) return { ok: false, code: 'invalid', error: 'invalid_at 不能为空' }
+  const supersededBy = typeof input?.supersededBy === 'string' ? input.supersededBy.trim() : ''
+
+  const eol = eolOf(content)
+  const lines = [`invalid_at: ${yamlScalar(invalidAt)}`]
+  if (supersededBy) lines.push(`superseded_by: ${yamlScalar(supersededBy)}`)
+
+  const m = content.match(FRONTMATTER_RE)
+  if (!m) {
+    // 没有 frontmatter：补一个**最小块**，正文原样跟在后面。失效标记必须有地方放，
+    // 而「拒绝标记」会让用户在面板上点了没反应 —— 那是更坏的一种静默。
+    const next = ['---', ...lines, '---', '', content].join(eol)
+    return { ok: true, content: next, changed: true }
+  }
+
+  const body = m[1].split(/\r?\n/).filter((line) => !VALIDITY_LINE_RE.test(line))
+  const block = ['---', ...body, ...lines, '---'].join(eol)
+  const next = content.slice(0, m.index) + block + content.slice(m.index + m[0].length)
+  return { ok: true, content: next, changed: next !== content }
+}
+
+/**
+ * 删掉 `invalid_at` / `superseded_by` 两行（撤销失效）。
+ *
+ * 只删这两行 —— 「撤销」不是「把文件恢复成某个版本」，其它任何改动都不动。
+ * 两行本来就不存在时返回 `changed:false`（幂等）。
+ */
+export function removeValidityLines(content) {
+  if (typeof content !== 'string') return { ok: false, code: 'invalid', error: '记忆内容必须是字符串' }
+  const m = content.match(FRONTMATTER_RE)
+  if (!m) return { ok: true, content, changed: false }
+  const eol = eolOf(content)
+  const body = m[1].split(/\r?\n/)
+  const kept = body.filter((line) => !VALIDITY_LINE_RE.test(line))
+  if (kept.length === body.length) return { ok: true, content, changed: false }
+  const block = ['---', ...kept, '---'].join(eol)
+  const next = content.slice(0, m.index) + block + content.slice(m.index + m[0].length)
+  return { ok: true, content: next, changed: next !== content }
+}
+
+/** 从宿主的 `fs` 服务取版本（拿不到就是 undefined —— 那就**不写**，不拿「现在」冒充）。 */
+function versionOf(info) {
+  return info && info.version !== undefined && info.version !== null ? info.version : undefined
+}
+
+/** 这一次写入该带的逐次沙箱策略（与 autodream 同一口径：收窄到记忆目录，`read-only` 不翻案）。 */
+function writeSandboxPolicy(ctx, memoryDir) {
+  try {
+    const sp = typeof ctx?.get === 'function' ? ctx.get('sandboxPolicy') : undefined
+    if (!sp || typeof sp.resolve !== 'function') return undefined
+    const policy = sp.resolve()
+    if (!policy || policy.mode !== 'workspace-write') return undefined
+    return { mode: 'workspace-write', workspaceRoot: memoryDir }
+  } catch {
+    return undefined
+  }
+}
+
+/** 宿主写失败的 err.code → 裁决入口的错误码（面板据此给可诊断出路）。 */
+function mapWriteError(err) {
+  const code = String(err?.code ?? '')
+  if (code === 'FS_STALE_VERSION') return 'stale_version'
+  if (code === 'FS_SANDBOX_DENIED') return 'write_denied'
+  if (code === 'ENOENT') return 'missing'
+  return 'io_error'
+}
+
+function hostFs(ctx) {
+  try {
+    const fs = typeof ctx?.get === 'function' ? ctx.get('fs') : undefined
+    return fs && typeof fs.resolve === 'function' && typeof fs.writeText === 'function' ? fs : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 读出「准备改写的那份记忆」并拿到**读到内容那一刻**的版本。
+ *
+ * 版本取法照 autodream 的 R01 结论：写前复核一次版本没变，变了就报 `stale_version`
+ * （内容在 `stat → read` 之间被改过，我们手里这份已经过期）。
+ */
+async function readForWrite(ctx, memoryDir, file) {
+  const safe = safeName(file)
+  if (!safe) return { ok: false, code: 'invalid', error: `文件名非法：${String(file)}` }
+  const fs = hostFs(ctx)
+  if (!fs) return { ok: false, code: 'unsupported', error: '宿主没有 fs 服务，只能手工编辑记忆文件' }
+  const full = join(memoryDir, safe)
+
+  const gate = await inspectMemoryEntry(full)
+  if (!gate.ok) {
+    return {
+      ok: false,
+      code: gate.code === 'missing' ? 'missing' : 'invalid',
+      error: gate.error,
+    }
+  }
+
+  let before
+  try {
+    const target = await fs.resolve(full)
+    before = await fs.stat(target)
+    if (!before) return { ok: false, code: 'missing', error: `记忆不存在：${safe}` }
+    // 版本守卫的**前提**：宿主必须给出一个版本。给不出就不能写 ——
+    // 「拿一个 undefined 当版本」在宿主那里可能等于「不校验」，那就是一次无守卫覆盖。
+    // 这与计划 §5.3 一致：拿不到版本就不写，让人手工编辑（面板会把这句话显示出来）。
+    if (versionOf(before) === undefined) {
+      return { ok: false, code: 'unsupported', error: '宿主没有给出这份记忆的版本号，无法安全写入（请手工编辑 frontmatter）' }
+    }
+    const content = await readVerified(full, gate, 'utf8')
+    const after = await fs.stat(target)
+    if (!after || versionOf(after) !== versionOf(before)) {
+      return { ok: false, code: 'stale_version', error: '读取期间文件被改过，请重试' }
+    }
+    return { ok: true, fs, full, target, version: versionOf(before), content }
+  } catch (err) {
+    if (err?.code === 'ENOENT') return { ok: false, code: 'missing', error: `记忆不存在：${safe}` }
+    return { ok: false, code: 'io_error', error: String(err?.message ?? err) }
+  }
+}
+
+/**
+ * 标一条记忆失效：写 `invalid_at`（+ 可选 `superseded_by`），其余字节不动。
+ *
+ * @param {object} deps `{ctx, memoryDir}`
+ * @param {{file:string, invalidAt:string, supersededBy?:string}} input
+ * @returns {Promise<{ok:true, file:string, invalidAt:string, version:string, wrote:boolean}
+ *   | {ok:false, code:'invalid'|'missing'|'stale_version'|'write_denied'|'unsupported'|'io_error', error:string}>}
+ */
+export async function invalidateMemory({ ctx, memoryDir }, input) {
+  const invalidAt = typeof input?.invalidAt === 'string' ? input.invalidAt.trim() : ''
+  // 写进用户文件的标记必须是我们能解析的格式：坏值会被 validity 层按「未标注」处理、
+  // 记忆照常注入 —— 用户会看到「标了却没用」，那是最难查的一类静默失效。
+  if (!parseValidityTime(invalidAt).ok) {
+    return { ok: false, code: 'invalid', error: `invalid_at 必须是 ISO 8601 带偏移的时间（收到 ${JSON.stringify(input?.invalidAt)}）` }
+  }
+  const read = await readForWrite(ctx, memoryDir, input?.file)
+  if (!read.ok) return read
+  const built = upsertValidityLines(read.content, input)
+  if (!built.ok) return built
+  if (!built.changed) {
+    // 幂等：标记已经在那儿了。不写盘，但照样给收据（面板会显示「已失效」）。
+    return { ok: true, file: safeName(input.file), invalidAt: String(input.invalidAt), version: String(read.version ?? ''), wrote: false }
+  }
+  try {
+    const outcome = await read.fs.writeText(
+      read.target,
+      built.content,
+      { kind: 'replaceIfVersion', version: read.version },
+      undefined,
+      writeSandboxPolicy(ctx, memoryDir),
+    )
+    const version = outcome && outcome.version !== undefined && outcome.version !== null ? String(outcome.version) : ''
+    return { ok: true, file: safeName(input.file), invalidAt: String(input.invalidAt), version, wrote: true }
+  } catch (err) {
+    return { ok: false, code: mapWriteError(err), error: String(err?.message ?? err) }
+  }
+}
+
+/**
+ * 撤销失效：删掉 `invalid_at` / `superseded_by` 两行，其余字节不动。
+ *
+ * @returns {Promise<{ok:true, file:string, cleared:boolean, version:string}
+ *   | {ok:false, code:'invalid'|'missing'|'stale_version'|'write_denied'|'unsupported'|'io_error', error:string}>}
+ */
+export async function undoMemoryInvalidation({ ctx, memoryDir }, file) {
+  const read = await readForWrite(ctx, memoryDir, file)
+  if (!read.ok) return read
+  const built = removeValidityLines(read.content)
+  if (!built.ok) return built
+  if (!built.changed) {
+    return { ok: true, file: safeName(file), cleared: false, version: String(read.version ?? '') }
+  }
+  try {
+    const outcome = await read.fs.writeText(
+      read.target,
+      built.content,
+      { kind: 'replaceIfVersion', version: read.version },
+      undefined,
+      writeSandboxPolicy(ctx, memoryDir),
+    )
+    const version = outcome && outcome.version !== undefined && outcome.version !== null ? String(outcome.version) : ''
+    return { ok: true, file: safeName(file), cleared: true, version }
+  } catch (err) {
+    return { ok: false, code: mapWriteError(err), error: String(err?.message ?? err) }
+  }
+}

package/lib/memory/config.js

@@ -146,6 +146,22 @@ export const RECALL_DISCIPLINE = [
  */
 export const STATE_ROOT = process.env.SAGE_MEM_STATE_DIR || join(dirname(MEMORY_DIR), '.sage-mem')
 
+/**
+ * 2.0.0：有效性过滤（`invalid_at`）与矛盾抑制的总开关（设计稿 §11.2 Q8）。
+ *
+ * 为什么要有：这是本版唯一会**让注入内容变少**的行为变更。用户遇到「某条记忆怎么不来了」
+ * 时，最便宜的处置应该是关掉它、而不是降级整个包（降级还会丢掉本版其它修复）。
+ *
+ * 只认**明确的关闭值**（`0` / `false` / `off`），其余一律当作开启 —— 「设了但拼错」
+ * 不该悄悄把行为改回旧版；反过来，空值 / 未设 与 1.9.x 的差别只是多解析了三个键。
+ *
+ * ⚠️ **每次调用现读** `process.env`：测试要在子进程里设它，模块加载时读死就测不了。
+ */
+export function validityEnabled() {
+  const raw = String(process.env.SAGE_MEM_VALIDITY ?? '').trim().toLowerCase()
+  return !(raw === '0' || raw === 'false' || raw === 'off')
+}
+
 /**
  * 读使用者自己声明的额外保护名单：`<状态根>/reserved.json`，形如 `["a.md","b.md"]`。
  *