sage-mem 1.9.2 → 2.0.0

package/lib/memory/conflicts.js

@@ -31,10 +31,18 @@ export const CONFLICTS_DIR_NAME = 'conflicts'
 export const CONFLICT_FILE_SUFFIX = '.json'
 
 /**
- * 冲突的种类。`stale_version` 是宿主版本守卫直接报出来的那种（最常见）；
- * `external_change` 是文件在别处被改了；`unresolved_merge` 是人工合并到一半留下的。
+ * 冲突的种类。
+ *
+ * 前三类是**写失败**型：盘上那份仍是现行内容（`stale_version` 是宿主版本守卫直接报出来的那种，
+ * 最常见；`external_change` 是文件在别处被改了；`unresolved_merge` 是人工合并到一半留下的）。
+ * 第四类 `contradiction` 是**语义**型：两条记忆的说法互斥，盘上两份都是「真的」，
+ * 只有人（或模型整理时）能判断哪条不再作数。
+ *
+ * ⚠️ 这个区分不是命名洁癖：注入侧的抑制**只对 `contradiction` 生效**。
+ * 把写失败型也塞进抑制集合，等于把「这次没写进去」误报成「这条记忆不可信」——
+ * 盘上那份明明还是有效的，见 docs/decisions.md 的 D27 / D29。
  */
-export const CONFLICT_KINDS = Object.freeze(['stale_version', 'external_change', 'unresolved_merge'])
+export const CONFLICT_KINDS = Object.freeze(['stale_version', 'external_change', 'unresolved_merge', 'contradiction'])
 
 /**
  * 记录的状态。`open` 是唯一「待处理」的状态；另外两种都是人的判断结果，
@@ -62,6 +70,14 @@ export const CONFLICT_FIELD_LIMITS = Object.freeze({
   incoming: 48 * 1024,
   onDisk: 48 * 1024,
   file: 1024,
+  // 2.0.0 追加字段（只增不改，`v` 仍是 1）：`otherFile` 与 `file` 同量级（文件名）；
+  // `decision` / `decidedAt` / `appliedVersion` 是裁决收据，都是短串；
+  // `invalidatedFile` 记「这次被标失效的是哪一方」——它是 `undo` 唯一可信的落点。
+  otherFile: 1024,
+  invalidatedFile: 1024,
+  decision: 32,
+  decidedAt: 64,
+  appliedVersion: 256,
   note: 4096,
   tool: 256,
   version: 256,
@@ -216,6 +232,13 @@ export function buildConflict(input) {
   const kind = typeof src.kind === 'string' ? src.kind : ''
 
   const file = clampText(src.file, CONFLICT_FIELD_LIMITS.file)
+  // 2.0.0 追加的字段全部**尾部追加**、且都是字符串：老版本读到不认识的键会忽略，
+  // 新版本读老记录时它们缺省为空串 —— 双向兼容，不需要迁移脚本。
+  const otherFile = clampText(src.otherFile, CONFLICT_FIELD_LIMITS.otherFile)
+  const invalidatedFile = clampText(src.invalidatedFile, CONFLICT_FIELD_LIMITS.invalidatedFile)
+  const decision = clampText(src.decision, CONFLICT_FIELD_LIMITS.decision)
+  const decidedAt = normalizeAt(src.decidedAt)
+  const appliedVersion = clampText(versionText(src.appliedVersion), CONFLICT_FIELD_LIMITS.appliedVersion)
   const incoming = clampText(src.incoming, CONFLICT_FIELD_LIMITS.incoming)
   const onDisk = clampText(src.onDisk, CONFLICT_FIELD_LIMITS.onDisk)
   const note = clampText(src.note, CONFLICT_FIELD_LIMITS.note)
@@ -224,10 +247,15 @@ export function buildConflict(input) {
   const actualVersion = clampText(versionText(src.actualVersion), CONFLICT_FIELD_LIMITS.version)
 
   const truncated =
-    file.cut || incoming.cut || onDisk.cut || note.cut || tool.cut || expectedVersion.cut || actualVersion.cut
+    file.cut || otherFile.cut || invalidatedFile.cut || decision.cut || appliedVersion.cut ||
+    incoming.cut || onDisk.cut || note.cut || tool.cut || expectedVersion.cut || actualVersion.cut
 
   const stamp = compactStamp(at)
-  const digest = shortDigest([kind, file.text, expectedVersion.text, actualVersion.text, incoming.text, onDisk.text])
+  // ⚠️ `otherFile` **只在非空时**进指纹：空串也拼进去的话，所有 1.x 老种类的 id 都会变 ——
+  // 老记录还在盘上、新记录的 id 换了，就成了「同一件事两个身份」。
+  const digestParts = [kind, file.text, expectedVersion.text, actualVersion.text, incoming.text, onDisk.text]
+  if (otherFile.text) digestParts.push(otherFile.text)
+  const digest = shortDigest(digestParts)
   const id = normalizeConflictId(src.id) ?? `${stamp === '' ? '' : `${stamp}-`}${digest}`
 
   return {
@@ -244,6 +272,11 @@ export function buildConflict(input) {
     note: note.text,
     tool: tool.text,
     truncated,
+    otherFile: otherFile.text,
+    decision: decision.text,
+    decidedAt,
+    appliedVersion: appliedVersion.text,
+    invalidatedFile: invalidatedFile.text,
   }
 }
 
@@ -343,6 +376,8 @@ export async function writeConflict(record, opts) {
   } catch (err) {
     return { ok: false, code: 'io_error', path, error: String(err?.message ?? err) }
   }
+  // 自己写的 → 注入侧那份摘要缓存立刻失效（否则面板裁决完，下一步仍按旧索引抑制一次）。
+  invalidateConflictIndex(opts && typeof opts === 'object' ? opts.stateRoot : undefined)
   return { ok: true, bytes: Buffer.byteLength(text, 'utf8'), path, truncated }
 }
 
@@ -405,6 +440,69 @@ function cmp(a, b) {
   return x < y ? -1 : x > y ? 1 : 0
 }
 
+/**
+ * 注入侧用的**轻量索引缓存**（2.0.0，plan §6.6 的阈值触发的那个小缓存）。
+ *
+ * 为什么需要（实测）：100 条记录、每份两份正文各 8 KB 时，`listConflicts` 单次 **p50 78 ms**
+ * —— 而它在**每一步 assemble** 都会被调一次。把两份正文一起读进 JSON.parse 是不必要的：
+ * 注入只需要 `kind / status / file / otherFile`。
+ *
+ * 三条失效判据（缺一不可）：
+ *   1. TTL（1 秒）：外部编辑器改记录也能在 1 秒内被看到；
+ *   2. **本模块自己写的**（落盘 / 裁决 / 删除）立即清缓存 —— 面板点完下一步就该生效；
+ *   3. 缓存键是目录绝对路径（`SAGE_MEM_STATE_DIR` 变了就是另一份缓存）。
+ *
+ * 1 秒的陈旧窗口是**有意的取舍**：注入是「每一两步一次」的读，不是事务；
+ * 代价上限是「刚裁决完的一步里，那条记忆仍被抑制一次」，而收益是每步省几十毫秒。
+ */
+const INDEX_CACHE = new Map()
+
+/** 注入侧缓存有效期。改这里要同时想清楚「用户点完面板多久该见效」。 */
+export const CONFLICT_INDEX_TTL_MS = 1000
+
+/** 这组文件的**摘要索引**：不带两份正文，给注入链用。 */
+export async function listConflictIndex(opts) {
+  const dir = conflictsDir(opts && typeof opts === 'object' ? opts.stateRoot : undefined)
+  const now = Date.now()
+  const cached = INDEX_CACHE.get(dir)
+  if (cached && now - cached.at < CONFLICT_INDEX_TTL_MS) return { ok: true, items: cached.items }
+
+  let names
+  try {
+    names = await readdir(dir)
+  } catch (err) {
+    if (err?.code === 'ENOENT') {
+      INDEX_CACHE.delete(dir)
+      return { ok: true, items: [] }
+    }
+    return { ok: false, code: 'io_error', dir, error: String(err?.message ?? err) }
+  }
+
+  const items = []
+  for (const name of [...names].sort(cmp)) {
+    if (!name.endsWith(CONFLICT_FILE_SUFFIX)) continue
+    const id = name.slice(0, -CONFLICT_FILE_SUFFIX.length)
+    if (normalizeConflictId(id) === null) continue
+    let text
+    try {
+      text = await readFile(join(dir, name), 'utf8')
+    } catch {
+      continue
+    }
+    const parsed = parseConflictText(text)
+    if (!parsed.ok) continue
+    items.push(summarizeConflict({ ...parsed.record, id }))
+  }
+  items.sort((a, b) => cmp(String(b.at ?? ''), String(a.at ?? '')) || cmp(a.id, b.id))
+  INDEX_CACHE.set(dir, { at: now, items })
+  return { ok: true, items }
+}
+
+/** 本模块自己改了队列 → 立刻丢掉这份缓存（下一次读重新扫目录）。 */
+function invalidateConflictIndex(stateRoot) {
+  INDEX_CACHE.delete(conflictsDir(stateRoot))
+}
+
 /**
  * 列出全部冲突（只读目录）。
  *
@@ -462,41 +560,145 @@ export async function listConflicts(opts) {
 }
 
 /**
- * 改状态并落盘。
+ * 记录的**摘要**（不含两份正文）。
  *
- * 状态机见 `CONFLICT_TRANSITIONS`：`open` 只能去 `resolved` / `dismissed`，那两个之间可以互转，
- * **都不许回到 `open`**（要重开就新建一条）。同状态重复点是**幂等**的 —— 界面上连点两下
- * 不该报错，也不重写文件。
+ * 面板列表只需要元数据；把 `incoming` / `onDisk`（各上限 48 KB）一起送过去，
+ * 一次列表就可能把几十兆正文推过 remote 边界。要看正文走 `read`（每次一条）。
+ */
+export function summarizeConflict(record) {
+  const r = record && typeof record === 'object' ? record : {}
+  return {
+    id: typeof r.id === 'string' ? r.id : '',
+    at: typeof r.at === 'string' ? r.at : '',
+    kind: typeof r.kind === 'string' ? r.kind : '',
+    status: typeof r.status === 'string' ? r.status : '',
+    file: typeof r.file === 'string' ? r.file : '',
+    otherFile: typeof r.otherFile === 'string' ? r.otherFile : '',
+    note: typeof r.note === 'string' ? r.note : '',
+    decision: typeof r.decision === 'string' ? r.decision : '',
+    decidedAt: typeof r.decidedAt === 'string' ? r.decidedAt : '',
+    appliedVersion: typeof r.appliedVersion === 'string' ? r.appliedVersion : '',
+    invalidatedFile: typeof r.invalidatedFile === 'string' ? r.invalidatedFile : '',
+    truncated: r.truncated === true,
+  }
+}
+
+/** 改记录时可以写的字段（白名单：不是「把 patch 合并进去」，免得远程调用能改写 id / 正文）。 */
+const PATCHABLE_TEXT = Object.freeze(['decision', 'appliedVersion', 'invalidatedFile', 'otherFile', 'note'])
+
+/**
+ * 「这两条记录是不是同一件事」—— 去重的**唯一判据**（纯函数，`autodream/tools.js` 与
+ * 测试共用；D22：同一判据只许一份实现）。
  *
- * @returns {Promise<{ok:true, record:object} | {ok:false, code:'invalid'|'invalid_transition'|'missing'|'malformed'|'io_error', error?}>}
+ * 逐字段相等：`status` / `kind` / `file` / `otherFile` / 两个版本 / 两份正文。
+ * 不带 `note` / `tool` / `at` / `decision`：它们描述「谁在什么时候碰上的」，
+ * 不是「冲突本身」。`otherFile` 缺省按空串比较（1.9.x 老记录没有这个键）。
  */
-export async function resolveConflict(id, status, opts) {
+export function sameConflict(a, b) {
+  const x = a && typeof a === 'object' ? a : {}
+  const y = b && typeof b === 'object' ? b : {}
+  return (
+    x.status === y.status &&
+    x.kind === y.kind &&
+    x.file === y.file &&
+    (x.otherFile ?? '') === (y.otherFile ?? '') &&
+    x.expectedVersion === y.expectedVersion &&
+    x.actualVersion === y.actualVersion &&
+    x.incoming === y.incoming &&
+    x.onDisk === y.onDisk
+  )
+}
+
+/**
+ * 改一条记录的字段（2.0.0 的裁决入口专用；`resolveConflict` 是它的子集）。
+ *
+ * 与 `resolveConflict` 同一条状态机：同状态重复点是幂等的（不重写文件），
+ * 已判定过的记录不许回到 `open`。**先改文件、后改记录**的顺序由调用方保证
+ * （见 `ConflictGateway.invalidate`）—— 反过来的半态是「记录说已裁决、文件没改」，
+ * 用户再也看不到它。
+ *
+ * @returns {Promise<{ok:true, record:object}
+ *   | {ok:false, code:'invalid'|'invalid_transition'|'missing'|'malformed'|'io_error', error?}>}
+ */
+export async function patchConflict(id, patch, opts) {
   const cid = normalizeConflictId(id)
   if (cid === null) return { ok: false, code: 'invalid', error: `冲突 id 非法：${JSON.stringify(id)}` }
-  if (!CONFLICT_STATUSES.includes(status)) {
-    return { ok: false, code: 'invalid', error: `未知状态：${JSON.stringify(status)}` }
+  if (patch === null || typeof patch !== 'object' || Array.isArray(patch)) {
+    return { ok: false, code: 'invalid', error: '冲突补丁必须是一个对象' }
   }
 
   const read = await readConflict(cid, opts)
   if (!read.ok) return { ok: false, code: read.code, error: read.error }
+  const cur = read.record
+  const next = { ...cur }
+  let changed = false
+
+  if (patch.status !== undefined) {
+    if (!CONFLICT_STATUSES.includes(patch.status)) {
+      return { ok: false, code: 'invalid', error: `未知状态：${JSON.stringify(patch.status)}` }
+    }
+    if (patch.status !== cur.status) {
+      const allowed = CONFLICT_TRANSITIONS[cur.status] ?? []
+      if (!allowed.includes(patch.status)) {
+        return {
+          ok: false,
+          code: 'invalid_transition',
+          error: `${cur.status} → ${patch.status} 不被允许（已判定过的记录不许回到 open，要重开请新建一条）`,
+        }
+      }
+      next.status = patch.status
+      changed = true
+    }
+  }
 
-  const from = read.record.status
-  if (from === status) return { ok: true, record: read.record }
-  const allowed = CONFLICT_TRANSITIONS[from] ?? []
-  if (!allowed.includes(status)) {
-    return {
-      ok: false,
-      code: 'invalid_transition',
-      error: `${from} → ${status} 不被允许（已判定过的记录不许回到 open，要重开请新建一条）`,
+  for (const key of PATCHABLE_TEXT) {
+    if (patch[key] === undefined) continue
+    const limit = CONFLICT_FIELD_LIMITS[key] ?? CONFLICT_FIELD_LIMITS.note
+    const { text } = clampText(String(patch[key] ?? ''), limit)
+    if (next[key] !== text) {
+      next[key] = text
+      changed = true
+    }
+  }
+  if (patch.decidedAt !== undefined) {
+    // 三态：`''` = 明确清空（撤销用）；能解析的字符串 = 写入；**坏值 = 忽略**（保留原值）。
+    // 坏值若一律归空，一次带顺手补丁的调用就会把已裁决记录的时间收据清掉 —— 那不是归一，是丢证据。
+    const raw = String(patch.decidedAt ?? '')
+    if (raw === '') {
+      if (next.decidedAt !== '') {
+        next.decidedAt = ''
+        changed = true
+      }
+    } else {
+      const at = normalizeAt(raw)
+      if (at && next.decidedAt !== at) {
+        next.decidedAt = at
+        changed = true
+      }
     }
   }
 
-  const next = { ...read.record, status }
+  // 幂等：同状态重复点不重写文件（界面上连点两下不该既报错又多一次 mtime）。
+  if (!changed) return { ok: true, record: cur }
+
   const written = await writeConflict(next, opts)
   if (!written.ok) return { ok: false, code: written.code, error: written.error }
   return { ok: true, record: next }
 }
 
+/**
+ * 改状态并落盘。
+ *
+ * 状态机见 `CONFLICT_TRANSITIONS`：`open` 只能去 `resolved` / `dismissed`，那两个之间可以互转，
+ * **都不许回到 `open`**（要重开就新建一条）。同状态重复点是**幂等**的 —— 界面上连点两下
+ * 不该报错，也不重写文件。
+ *
+ * @returns {Promise<{ok:true, record:object} | {ok:false, code:'invalid'|'invalid_transition'|'missing'|'malformed'|'io_error', error?}>}
+ */
+export async function resolveConflict(id, status, opts) {
+  return patchConflict(id, { status }, opts)
+}
+
 /**
  * 删一条（清理）。
  *
@@ -516,5 +718,6 @@ export async function removeConflict(id, opts) {
     if (err?.code === 'ENOENT') return { ok: false, code: 'missing', path, error: '冲突记录不存在' }
     return { ok: false, code: 'io_error', path, error: String(err?.message ?? err) }
   }
+  invalidateConflictIndex(opts && typeof opts === 'object' ? opts.stateRoot : undefined)
   return { ok: true, path }
 }

package/lib/memory/frontmatter.js

@@ -41,7 +41,14 @@ export function parseFrontmatter(content) {
   // 「baseline 走 parseBaseline 那条带 \r?\n 的正则照旧命中，但这条记忆永远检索不到」，
   // 症状极具欺骗性。下文定义的 parseBaseline 与 extractTitle 早已是 \r?\n。
   const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/)
-  if (!m) return { name: '', description: '', type: '', tags: [], aliases: [], updated: '', baselinePriority: 0 }
+  if (!m) {
+    return {
+      name: '', description: '', type: '', tags: [], aliases: [], updated: '', baselinePriority: 0,
+      // 无 frontmatter = 三字段缺失。R1 要求「缺失即老行为」，所以这里必须是空串而不是 undefined：
+      // 下游 `f.invalidAt === ''` 与 `!f.invalidAt` 两种写法都得安全。
+      validAt: '', invalidAt: '', supersededBy: '',
+    }
+  }
   const body = m[1]
   const grab = (key) => {
     // [ \t] / [ \t\r] 而不是 \s：\s 会连 CRLF 的 \r 一起吃进捕获组，值尾留一个 \r
@@ -71,6 +78,20 @@ export function parseFrontmatter(content) {
     aliases: parseAliases(body),
     updated,
     baselinePriority: parseBaselinePriority(body),
+    /**
+     * 有效性三字段（2.0.0）：顶层、可选、缺失一律空串。
+     *
+     * 刻意**不**回落 metadata 嵌套（不同于上面的 updated）：规范只认顶层
+     * （`docs/2.0.0-plan.md` §4.1），「换个位置也认」等于让同一份文件的语义由写它的人
+     * 用了哪种格式决定 —— 而这三个字段直接决定一条记忆会不会被注入。
+     *
+     * 值能不能解析**不在这里判**：坏格式也原样返回（R2：认不出就不猜），判定
+     * 统一在 `validity.js` —— 解析判据只有一份（D22），这里再加一层「看起来像时间」
+     * 的判断，就会变成两份会各自漂移的规则。
+     */
+    validAt: grab('valid_at'),
+    invalidAt: grab('invalid_at'),
+    supersededBy: grab('superseded_by'),
   }
 }
 

package/lib/memory/scan.js

@@ -455,6 +455,18 @@ async function fullScanMemoryDir(ctx, sessionId, dir) {
           baselinePriority: meta.baselinePriority || 0,
           // 新鲜度的两个来源：frontmatter 的 updated（权威）与文件 mtime（退路）。
           updated: meta.updated || '',
+          /**
+           * 有效性三字段（2.0.0）：与 description / aliases 同一处带出 —— 记录形状只在这里
+           * 组装一次，注入链 / 面板 / 审计都从这份记录读。平铺而不是嵌套，是为了让
+           * `validity.js` 的判据只依赖 `f.invalidAt` 一个路径（同一形状少一层解构）。
+           *
+           * 缺失一律空串（R1）：三字段全缺时这条记录与 1.9.2 逐字相同 —— 老记忆的
+           * 「仍有效、时间未知」不是靠下游特判，而是靠这里没有多出任何真值。
+           * 坏格式也原样带出，不在这里判（R2）；判据只有 validity.js 一份。
+           */
+          validAt: meta.validAt || '',
+          invalidAt: meta.invalidAt || '',
+          supersededBy: meta.supersededBy || '',
           mtimeMs: gate.mtimeMs,
         }
       } catch (err) {

package/lib/memory/status.js

@@ -172,11 +172,38 @@ function assemble(header, action, buildBest) {
   return [header, best, action].filter(l => l && kept.includes(l)).join('\n')
 }
 
+/**
+ * 「有矛盾待裁决」那句话（2.0.0）。
+ *
+ * 为什么必须是**固定一句 + 具体条数**：卡片按内容签名去重（`lib/recall/compose.js`），
+ * 签名里不带条数的话，第二封（条数变了）发不出去；而条数不变时重复发同一句就是刷屏。
+ * 为什么必须发：抑制是「记忆不再进正文」——用户不看面板时，那是唯一会自己撞进视线的提示
+ * （D27 拒绝先上抑制的理由正是「用户无从得知」）。
+ */
+function conflictNotice(pending) {
+  return `sage-mem：另有 ${countText(pending)} 条矛盾待裁决，相关记忆本轮未注入正文。`
+}
+
+/**
+ * 把冲突提示并进卡片，且**保住 512 字节预算**。
+ *
+ * 冲突提示是这一版新增的「必须可见」项，所以它优先于「最佳线索」：放不下时先丢线索，
+ * 再放不下就只发这一句 —— 一张只剩提示的卡仍然成立，一张把提示挤掉的卡不成立。
+ */
+function withConflictNotice(card, notice) {
+  if (!notice) return card
+  if (!card) return notice
+  const joined = `${card}\n${notice}`
+  if (byteLen(joined) <= STATUS_MAX_BYTES) return joined
+  return notice
+}
+
 /**
  * 渲染缺口状态卡。返回 `''` = 本次不该注入任何提示。
  *
  * 三条判定（顺序即优先级）：
  *   1. 没有缺口（unread=0 且 omitted=0）且注入了正文 → `''`，没有缺口就不要说话；
+ *      但**有矛盾待裁决时例外**：抑制必须可见，那是一句独立的提示；
  *   2. 没有缺口、也没有注入 → 摘要未命中那一句 + 建议；
  *   3. 有缺口（有候选没读，或有候选被预算省略）→ 范围 + 条数 + 最佳线索 + 一个动作。
  *
@@ -184,7 +211,7 @@ function assemble(header, action, buildBest) {
  * 说「摘要里没有命中」是**谎报故障类型** —— 而这张卡的整个意义就是把
  * 「没找到」与「找到了但没展示」分开，所以有省略时一律走第 3 条。
  *
- * @param {object} input `{scope, scanned, injected, omitted, unread, best, needle, toolsAvailable, memoryDir}`
+ * @param {object} input `{scope, scanned, injected, omitted, unread, best, needle, toolsAvailable, memoryDir, pendingConflicts}`
  * @returns {string} 卡片文本，或 `''`
  */
 export function renderStatusCard(input = {}) {
@@ -199,16 +226,21 @@ export function renderStatusCard(input = {}) {
   const needle = clipChars(str(i.needle), CLIP.needle)
   const memoryDir = clipChars(str(i.memoryDir), CLIP.dir)
   const best = normalizeBest(i.best)
+  const pending = count(i.pendingConflicts)
+  const notice = pending > 0 ? conflictNotice(pending) : ''
 
   const gap = unread > 0 || omitted > 0
-  if (!gap && injected > 0) return ''
+  if (!gap && injected > 0) return notice
 
   if (!gap) {
-    return assemble(missHeader(scope, scanned), missAction({ tools, needle, memoryDir }), () => '')
+    return withConflictNotice(assemble(missHeader(scope, scanned), missAction({ tools, needle, memoryDir }), () => ''), notice)
   }
-  return assemble(
-    gapHeader(scope, scanned, injected, unread, omitted),
-    gapAction({ tools, needle, memoryDir, best }),
-    room => bestLine(best, room),
+  return withConflictNotice(
+    assemble(
+      gapHeader(scope, scanned, injected, unread, omitted),
+      gapAction({ tools, needle, memoryDir, best }),
+      room => bestLine(best, room),
+    ),
+    notice,
   )
 }

package/lib/memory/validity.js

@@ -0,0 +1,156 @@
+/**
+ * sage-mem 记忆层 —— 有效性（`valid_at` / `invalid_at` / `superseded_by`）的解析与判定。
+ *
+ * 2.0.0 的数据模型层（`docs/2.0.0-plan.md` §4.1 R1–R6）。这一片**只判定、不读盘、不写盘、
+ * 不改注入**：它把「frontmatter 里那三个字段」翻译成「这条记忆现在算不算失效」与
+ * 「哪些文件该被抑制」两个集合，交给上层（注入链 / 面板）消费。
+ *
+ * 三条贯穿全文件的规矩：
+ *
+ * 1. **时钟必须由调用方传入（R3）。** 这些函数一个都不读 `Date.now()`：判定的边界值
+ *    （`invalid_at` 恰好等于此刻、未来一秒）是夹具与 `TZ=UTC` 的 CI 唯一能钉住的东西，
+ *    模块里读一次时钟就变成「跑测试那一刻碰运气」。注入链本来就带着 `nowMs`
+ *    （`lib/recall/injector.js`），顺着传下来零成本。
+ * 2. **认不出就不猜（R2）。** 坏格式一律按「未标注」处理，绝不编一个时间：猜出来的时间
+ *    会让一条写坏的标注变成一条**永久失效**的记忆，而失效是静默的 —— 它只表现为
+ *    「这条记忆不再出现」，没有报错。
+ * 3. **缺失即老行为（R1）。** 三字段全缺时，这里的每个判定都与 1.9.2 的空集逐字相同：
+ *    失效集合为空、冲突集合为空。零迁移的全部依据就是这一条。
+ *
+ * 冲突记录**不是事实来源**（§4.4）：一条记忆有 `invalid_at` 才算失效；冲突记录只说明
+ * 「有一对手工/模型标记的互斥说法待裁决」。两者不一致时，注入看 frontmatter、面板看记录。
+ */
+
+/**
+ * 被认可的时间格式：ISO 8601 带偏移 —— `YYYY-MM-DDTHH:MM(:SS)?(Z|±HH:MM)`。
+ *
+ * 为什么**额外接受 1–3 位小数秒**（规格里没写）：裁决入口写 `invalid_at` 时会用
+ * `new Date().toISOString()`，它的天然产物是 `2026-10-24T18:30:00.000Z`。严格按规格
+ * 拒掉小数秒，就等于**宿主自己写的时间自己认不出** → 按未标注处理 → 失效标记静默不生效。
+ * 这是最容易发生、也最难发现的一类坑：文件里明明写着 `invalid_at`，那条记忆却照常注入。
+ * 小数秒仍是合法 ISO 8601，收它不违反 R2（R2 防的是「像时间的胡话」）。
+ *
+ * 其余部分刻意从严：必须带时区偏移、必须有 `T`、必须是完整日期。`Date.parse` 其实也认
+ * `2026-10-24`（按本地时区解释）与 `Oct 24 2026`，但「哪一天」在跨时区时会漂一天，
+ * 而失效判定恰好是「早一天 / 晚一天」的语义 —— 认它等于把一个时区隐患埋进数据模型。
+ */
+const TIME_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,3})?)?(?:Z|[+-]\d{2}:\d{2})$/
+
+/**
+ * 解析一个有效性时间值。
+ *
+ * 两道闸门（R2）：格式正则 + `Date.parse` 有限。前者挡「不像 ISO 的胡话」，
+ * 后者挡「格式像、日期不存在」（例如月份越界）—— 任一不过都返回 `ok: false`，
+ * 由调用方按「未标注」处理，**不要**在这里回落成某个时间。
+ *
+ * @param {unknown} value — frontmatter 里的原始值（正常是字符串；缺失 / 非字符串都按未标注）
+ * @returns {{ok: boolean, ms: number|null}} `ok` 为 false 时 `ms` 必为 null
+ */
+export function parseValidityTime(value) {
+  if (typeof value !== 'string') return { ok: false, ms: null }
+  const raw = value.trim()
+  if (!TIME_RE.test(raw)) return { ok: false, ms: null }
+  const ms = Date.parse(raw)
+  return Number.isFinite(ms) ? { ok: true, ms } : { ok: false, ms: null }
+}
+
+/**
+ * 这条记忆的失效时刻到了没有。
+ *
+ * 只读 `file.invalidAt`（**不看** `validAt`：`valid_at` 是「说法何时开始成立」，
+ * 与「现在还算不算数」无关。用 `valid_at` 推断失效等于把「开始」当成「结束的线索」，
+ * R4 明确禁止这种互相推导）。
+ *
+ * 四种「不失效」情形都是刻意的：字段缺失 / 坏格式 / 未来时间 / `nowMs` 传了非法值。
+ * 后两种宁可当有效：把一条本该注入的记忆藏起来是用户看得见的损失，而把一条刚过期的
+ * 多看一轮，下一次注入就会修正。
+ *
+ * @param {{invalidAt?: string}|null|undefined} file — scan 记录（`file` 字段为文件名）
+ * @param {number} nowMs — 调用方的「现在」（毫秒时间戳），不读时钟是 R3 的硬要求
+ * @returns {boolean}
+ */
+export function isExpired(file, nowMs) {
+  if (!Number.isFinite(nowMs)) return false
+  const parsed = parseValidityTime(file?.invalidAt)
+  // `<=` 而不是 `<`：到点即失效（裁决入口写的就是「从这一刻起不作数」）。
+  return parsed.ok && parsed.ms <= nowMs
+}
+
+/**
+ * 给面板 / 审计 / 状态卡用的一句话视图。
+ *
+ * `expired` = 已到点失效；`pendingFuture` = 时间可解析但在未来（「暂不失效」，
+ * 审计要提示、注入不能动手）；两者都为 false 包含「未标注」与「坏格式」两种 ——
+ * 它们在行为上等价（老行为、有效），区别只在审计提示里，不要在这里合成第三种状态。
+ *
+ * 返回值里的时间字段是**原样字符串**（不是时间戳）：面板要显示用户写的那个时区，
+ * 换算成 UTC 反而让「我写的是下午六点半」变得认不出来。判定另行计算。
+ *
+ * @param {{invalidAt?: string, supersededBy?: string}|null|undefined} file
+ * @param {number} nowMs
+ * @returns {{invalidAt: string, supersededBy: string, expired: boolean, pendingFuture: boolean}}
+ */
+export function describeValidity(file, nowMs) {
+  const invalidAt = typeof file?.invalidAt === 'string' ? file.invalidAt : ''
+  const supersededBy = typeof file?.supersededBy === 'string' ? file.supersededBy : ''
+  const parsed = parseValidityTime(invalidAt)
+  const usable = parsed.ok && Number.isFinite(nowMs)
+  return {
+    invalidAt,
+    supersededBy,
+    expired: usable && parsed.ms <= nowMs,
+    pendingFuture: usable && parsed.ms > nowMs,
+  }
+}
+
+/**
+ * 从一次扫描结果里取出「已失效」的文件名集合。
+ *
+ * 返回的是**文件名**（scan 记录的 `file` 字段，如 `project_a.md`），不是路径：
+ * 注入链与状态卡都按文件名对账，混进绝对路径会让集合在两侧永远对不上
+ * （而且绝对路径会把用户目录结构带进日志 / 状态卡）。
+ *
+ * 纯函数：给同样的 `files` 与 `nowMs` 永远得到同样的集合 —— 失效名单是要进
+ * golden 断言与评测基线的，任何隐式输入（时钟 / 环境变量）都会让它不可重放。
+ *
+ * @param {Array<{file?: string, invalidAt?: string}>} files — `scanMemoryFiles` 的记录
+ * @param {number} nowMs
+ * @returns {Set<string>}
+ */
+export function buildExpirySet(files, nowMs) {
+  const out = new Set()
+  if (!Array.isArray(files)) return out
+  for (const f of files) {
+    if (!f || typeof f.file !== 'string' || f.file === '') continue
+    if (isExpired(f, nowMs)) out.add(f.file)
+  }
+  return out
+}
+
+/**
+ * 从冲突记录里取出「未裁决矛盾」涉及的文件名集合（两方都要）。
+ *
+ * 只收 `status === 'open'` 且 `kind === 'contradiction'` 的记录（§6.3）：
+ * 另外三种 kind 都是「想写、没写成」——`stale_version` 时盘上那份**才是现行的**，
+ * 把它们也当成「不可信」会重演「记忆悄悄消失」的事故（D27）。「记录还没裁决」
+ * 与「记忆不可信」是两件事，这条判据就是那个分界线。
+ *
+ * `file` 是拟标失效的一方，`otherFile` 是另一方：抑制必须两边都放，只藏一方等于
+ * 让用户继续看到一份**已经被判定为可能作废**的说法。`otherFile` 可能缺失 / 为空串
+ * （老记录没有这个字段），跳过而不是拼出一个空文件名。
+ *
+ * @param {Array<{kind?: string, status?: string, file?: string, otherFile?: string}>} records
+ * @returns {Set<string>}
+ */
+export function buildContradictionFileSet(records) {
+  const out = new Set()
+  if (!Array.isArray(records)) return out
+  for (const r of records) {
+    if (!r || r.status !== 'open' || r.kind !== 'contradiction') continue
+    for (const key of ['file', 'otherFile']) {
+      const name = typeof r[key] === 'string' ? r[key].trim() : ''
+      if (name !== '') out.add(name)
+    }
+  }
+  return out
+}