minimal-agent 0.10.0 → 0.12.0

package/src/memory/repository.ts

@@ -0,0 +1,893 @@
+import { watch, type FSWatcher } from 'node:fs';
+import { mkdir, readFile, readdir, rename, rm, stat, unlink } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+import { pathContains } from '../utils/pathContains.js';
+
+import { parseMemoryRecord, serializeMemoryRecord, sha256 } from './codec.js';
+import { ALL_CATEGORIES, CATEGORY_DIR } from './constants.js';
+import {
+  acquireFileLock,
+  atomicWriteFile,
+  memoryRecordPath,
+  scopeDirectory,
+} from './fileStore.js';
+import type {
+  MemoryDiagnostic,
+  MemoryRecordV2,
+  MemoryScope,
+  MemorySnapshot,
+  MemoryVersion,
+  VersionedMemoryRecord,
+} from './types.js';
+import { ensureTopicView } from './topicView.js';
+
+interface CachedFile {
+  mtimeMs: number;
+  size: number;
+  version: MemoryVersion;
+  record?: MemoryRecordV2;
+  diagnostic?: MemoryDiagnostic;
+}
+
+const fileCache = new Map<string, CachedFile>();
+/** 兜底审计的最小间隔：watcher 漏掉的变更最迟这么久后会被 stat 审计发现。 */
+const SCOPE_AUDIT_TTL_MS = 1_000;
+/** 「扫描期间被改动 → 重扫」的重试上限，防止持续写入把读拖成活锁。 */
+const MAX_SCAN_RETRIES = 3;
+const MAX_SCOPE_CACHE_ENTRIES = 128;
+
+const repositoryDiagnostics = {
+  snapshotHits: 0,
+  watchInvalidations: 0,
+  fallbackAudits: 0,
+  fullScans: 0,
+};
+
+export function memoryRepositoryDiagnostics(): Readonly<typeof repositoryDiagnostics> {
+  return { ...repositoryDiagnostics };
+}
+
+export function resetMemoryRepositoryDiagnostics(): void {
+  repositoryDiagnostics.snapshotHits = 0;
+  repositoryDiagnostics.watchInvalidations = 0;
+  repositoryDiagnostics.fallbackAudits = 0;
+  repositoryDiagnostics.fullScans = 0;
+}
+
+interface ScopeCacheEntry {
+  snapshot: MemorySnapshot;
+  dirty: boolean;
+  directoryFingerprint: string;
+  lastAuditAt: number;
+}
+
+interface ScopeRuntimeState {
+  cache?: ScopeCacheEntry;
+  watchers: FSWatcher[];
+  watcherComplete: boolean;
+  watcherRefreshRequired: boolean;
+  epoch: number;
+  lastUsedAt: number;
+  lastDrainAt: number;
+  suppressDirtyUntil: number;
+}
+
+const scopeStates = new Map<string, ScopeRuntimeState>();
+
+function scopeState(key: string): ScopeRuntimeState {
+  let state = scopeStates.get(key);
+  if (!state) {
+    state = {
+      watchers: [],
+      watcherComplete: false,
+      watcherRefreshRequired: false,
+      epoch: 0,
+      lastUsedAt: 0,
+      lastDrainAt: 0,
+      suppressDirtyUntil: 0,
+    };
+    scopeStates.set(key, state);
+  }
+  return state;
+}
+
+/** scope 目录下由本模块自己生成、不该被当成「用户改了记忆」的条目。 */
+const GENERATED_SCOPE_ENTRIES: ReadonlySet<string> = new Set([
+  'views',
+  '.transactions',
+  '.records.lock',
+]);
+const CATEGORY_SCOPE_ENTRIES = new Set(Object.values(CATEGORY_DIR));
+const WATCHER_SETTLE_REUSE_MS = 50;
+const WATCHER_SETTLE_WAIT_MS = 20;
+const INTERNAL_RECORD_EVENT_TTL_MS = 1_000;
+const internalRecordEvents = new Map<string, number>();
+
+function markInternalRecordEvent(path: string): void {
+  internalRecordEvents.set(path, Date.now() + INTERNAL_RECORD_EVENT_TTL_MS);
+}
+
+function consumeInternalRecordEvent(path: string): boolean {
+  const expiresAt = internalRecordEvents.get(path);
+  if (!expiresAt) return false;
+  if (expiresAt < Date.now()) {
+    internalRecordEvents.delete(path);
+    return false;
+  }
+  internalRecordEvents.delete(path);
+  return true;
+}
+
+interface MemoryTransactionItem {
+  id: string;
+  oldPath: string;
+  nextPath: string;
+  stagePath: string;
+  expectedVersion: MemoryVersion;
+  targetVersion: MemoryVersion;
+}
+
+interface MemoryTransactionManifest {
+  schemaVersion: 1;
+  id: string;
+  items: MemoryTransactionItem[];
+}
+
+function transactionRoot(base: string): string { return join(base, '.transactions'); }
+function transactionManifestPath(base: string): string { return join(transactionRoot(base), 'current.json'); }
+function generationPath(base: string): string { return join(transactionRoot(base), 'generation'); }
+
+/**
+ * 「这个路径在不在那个目录里」只有一份实现：`src/utils/pathContains.ts`。
+ * 这里只负责把两边解析成绝对路径（manifest 里的路径来自 JSON，可能是相对的），
+ * 判据本身不再手写第五遍——那个 util 的头注释专门警告过手写副本会各自漂移。
+ */
+function pathInside(base: string, path: string): boolean {
+  return pathContains(resolve(base), resolve(path));
+}
+
+async function readGeneration(base: string): Promise<string> {
+  return readFile(generationPath(base), 'utf8').catch(() => '');
+}
+
+async function readTransactionManifest(base: string): Promise<MemoryTransactionManifest | null> {
+  const raw = await readFile(transactionManifestPath(base), 'utf8').catch((error) => {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    throw error;
+  });
+  if (raw === null) return null;
+  let parsed: MemoryTransactionManifest;
+  try {
+    parsed = JSON.parse(raw) as MemoryTransactionManifest;
+  } catch {
+    throw new Error('MEMORY_TRANSACTION_CORRUPT');
+  }
+  if (parsed.schemaVersion !== 1 || !parsed.id || !Array.isArray(parsed.items)) {
+    throw new Error('MEMORY_TRANSACTION_CORRUPT');
+  }
+  if (parsed.items.some((item) =>
+    !pathInside(base, item.oldPath)
+    || !pathInside(base, item.nextPath)
+    || !pathInside(transactionRoot(base), item.stagePath))) {
+    throw new Error('MEMORY_TRANSACTION_PATH_INVALID');
+  }
+  return parsed;
+}
+
+async function rollForwardTransactionUnlocked(base: string): Promise<void> {
+  const manifest = await readTransactionManifest(base);
+  if (!manifest) return;
+  for (const item of manifest.items) {
+    const targetRaw = await readFile(item.nextPath, 'utf8').catch(() => null);
+    if (targetRaw !== null && sha256(targetRaw) === item.targetVersion) {
+      if (item.oldPath !== item.nextPath) await unlink(item.oldPath).catch(() => {});
+      continue;
+    }
+    if (item.nextPath !== item.oldPath && targetRaw !== null) {
+      throw new Error('MEMORY_TRANSACTION_CONFLICT');
+    }
+    const oldRaw = await readFile(item.oldPath, 'utf8').catch(() => null);
+    if (oldRaw === null || sha256(oldRaw) !== item.expectedVersion) {
+      throw new Error('MEMORY_TRANSACTION_CONFLICT');
+    }
+    await mkdir(dirname(item.nextPath), { recursive: true, mode: 0o700 });
+    markInternalRecordEvent(item.nextPath);
+    if (item.oldPath !== item.nextPath) markInternalRecordEvent(item.oldPath);
+    await rename(item.stagePath, item.nextPath);
+    if (item.oldPath !== item.nextPath) await unlink(item.oldPath).catch(() => {});
+  }
+  await atomicWriteFile(generationPath(base), `${manifest.id}\n`);
+  await unlink(transactionManifestPath(base)).catch(() => {});
+  await rm(join(transactionRoot(base), manifest.id), { recursive: true, force: true });
+}
+
+const TRANSACTION_POISON_ERRORS = new Set([
+  'MEMORY_TRANSACTION_CORRUPT',
+  'MEMORY_TRANSACTION_PATH_INVALID',
+  'MEMORY_TRANSACTION_CONFLICT',
+]);
+
+interface ScopeRecovery {
+  recovered: boolean;
+}
+
+interface QuarantineMetadata {
+  schemaVersion: 1;
+  quarantinedAt: number;
+  reason: string;
+  originalManifestPath: string;
+}
+
+async function quarantineDiagnosticsFor(base: string): Promise<MemoryDiagnostic[]> {
+  const root = transactionRoot(base);
+  let names: string[];
+  try {
+    names = (await readdir(root, { withFileTypes: true }))
+      .filter((entry) => entry.isDirectory() && entry.name.startsWith('quarantine-'))
+      .map((entry) => entry.name);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+    throw error;
+  }
+  const diagnostics: MemoryDiagnostic[] = [];
+  for (const name of names.sort()) {
+    const target = join(root, name);
+    let metadata: QuarantineMetadata | null = null;
+    try {
+      metadata = JSON.parse(await readFile(join(target, 'diagnostic.json'), 'utf8')) as QuarantineMetadata;
+    } catch {
+      // 旧版本隔离目录没有元数据时仍需告警，不能因升级让诊断沉默。
+    }
+    const reason = metadata?.reason ?? 'MEMORY_TRANSACTION_QUARANTINED';
+    diagnostics.push({
+      path: metadata?.originalManifestPath ?? join(target, 'current.json'),
+      message:
+        `记忆事务无法前滚（${reason}），已隔离到 ${target} 并继续读取现有记录；`
+        + '该批次的改动可能只应用了一部分，请复核相关记忆。',
+    });
+  }
+  return diagnostics;
+}
+
+export async function clearScopeTransactionQuarantine(
+  scope: MemoryScope,
+  workspaceId?: string,
+): Promise<void> {
+  const root = transactionRoot(scopeDirectory(scope, workspaceId));
+  let names: string[] = [];
+  try {
+    names = (await readdir(root, { withFileTypes: true }))
+      .filter((entry) => entry.isDirectory() && entry.name.startsWith('quarantine-'))
+      .map((entry) => entry.name);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+  }
+  await Promise.all(names.map(async (name) => {
+    const quarantine = join(root, name);
+    try {
+      const manifest = JSON.parse(await readFile(join(quarantine, 'current.json'), 'utf8')) as { id?: unknown };
+      if (typeof manifest.id === 'string' && /^[a-f0-9-]{16,}$/i.test(manifest.id)) {
+        await rm(join(root, manifest.id), { recursive: true, force: true });
+      }
+    } catch {
+      // 损坏清单本来就可能无法解析；清理隔离目录仍继续。
+    }
+    await rm(quarantine, { recursive: true, force: true });
+  }));
+  invalidateScope(scope, workspaceId);
+}
+
+/** 隔离操作的专用锁路径（实际锁文件是 `<它>.lock`）。 */
+function quarantineLockPath(base: string): string {
+  return join(transactionRoot(base), '.quarantine');
+}
+
+/**
+ * 把无法前滚的事务清单挪进 `.transactions/quarantine-<ts>/`，让读路径继续可用。
+ *
+ * ⚠️ 这是**读路径**独有的策略；写路径（replaceMemoryBatchVersioned）仍然照常抛错——
+ * 写入方必须看到冲突，不能替它把别人已提交的事务悄悄扔掉。
+ *
+ * ⚠️ **必须持 `.quarantine` 锁调用**（见 quarantineTransaction）。它是
+ * `mkdir + rename + unlink + 写元数据` 的多步变更，无锁并发会各建一个隔离目录。
+ */
+async function quarantineTransactionLocked(base: string, reason: string): Promise<void> {
+  const manifestPath = transactionManifestPath(base);
+  const manifestRaw = await readFile(manifestPath, 'utf8').catch(() => null);
+  // 拿到锁后清单已经不在 = 另一个读者/进程刚刚隔离过同一份。直接返回：
+  // 不重复建目录、不重复告警。这一条取代了以前那个只覆盖 ENOENT 交错的特判。
+  if (manifestRaw === null) return;
+
+  const target = join(
+    transactionRoot(base),
+    `quarantine-${Date.now()}-${randomUUID().slice(0, 8)}`,
+  );
+  await mkdir(target, { recursive: true, mode: 0o700 });
+  let claimed = true;
+  try {
+    await rename(manifestPath, join(target, 'current.json'));
+  } catch {
+    // 跨卷或某些网络盘上 rename 可能失败。必须先保存并校验副本，再移除原清单；
+    // 不能为了让读路径继续就丢掉唯一的恢复证据。
+    const preserved = join(target, 'current.json');
+    await atomicWriteFile(preserved, manifestRaw).catch(() => undefined);
+    const verified = await readFile(preserved, 'utf8')
+      .then((value) => sha256(value) === sha256(manifestRaw))
+      .catch(() => false);
+    claimed = verified
+      ? await unlink(manifestPath).then(() => true).catch(() => false)
+      : false;
+  }
+  if (!claimed) {
+    // 证据没保住就别留下空目录——它会被 quarantineDiagnosticsFor 当成一次真实隔离，
+    // 报出「已隔离到 XXX」却什么都恢复不了。
+    await rm(target, { recursive: true, force: true }).catch(() => undefined);
+    return;
+  }
+  const metadata: QuarantineMetadata = {
+    schemaVersion: 1,
+    quarantinedAt: Date.now(),
+    reason,
+    originalManifestPath: manifestPath,
+  };
+  await atomicWriteFile(join(target, 'diagnostic.json'), `${JSON.stringify(metadata, null, 2)}\n`)
+    .catch(() => undefined);
+}
+
+/**
+ * 加锁版入口。用**独立**的 `.quarantine` 锁而不是 `.records`：
+ * 需要互斥的只有「另一个隔离尝试」——合法的在飞事务其清单由 atomicWriteFile 写出，
+ * 永远是完整可解析的，不会被误隔离，所以无需与记录写入互斥。
+ * 而且 `memoryService.remember()` 是**持着 `.records` 锁**调用 scanMemoryScope 的，
+ * 这里若复用 `.records` 会自锁（文件锁不可重入）直接等到超时。
+ */
+async function quarantineTransaction(base: string, reason: string): Promise<void> {
+  const release = await acquireFileLock(quarantineLockPath(base));
+  try {
+    await quarantineTransactionLocked(base, reason);
+  } finally {
+    await release();
+  }
+}
+
+async function recoverScopeTransaction(base: string): Promise<ScopeRecovery> {
+  let manifestExists: boolean;
+  try {
+    manifestExists = (await readTransactionManifest(base)) !== null;
+  } catch (error) {
+    const reason = (error as Error).message;
+    if (!TRANSACTION_POISON_ERRORS.has(reason)) throw error;
+    // 清单读不出来（结构损坏 / JSON 语法错 / 路径越界）→ 隔离。
+    // ⚠️ 这里曾写着「锁都不必拿，直接隔离」并真的裸调 —— 那是错的：隔离是多步文件变更，
+    //    两个并发读者（典型触发者：一次 remember() 后台刷新视图的扫描 + 用户这次读）
+    //    会各建一个隔离目录，其中一个还留不下 current.json，却照样报「已隔离到 XXX」。
+    //    同一函数在下面 roll-forward 失败处本来就是持锁调用的，这个不对称就是缺陷本身。
+    await quarantineTransaction(base, reason);
+    return { recovered: true };
+  }
+  if (!manifestExists) return { recovered: false };
+  const release = await acquireFileLock(join(base, '.records'));
+  try {
+    await rollForwardTransactionUnlocked(base);
+  } catch (error) {
+    const reason = (error as Error).message;
+    if (!TRANSACTION_POISON_ERRORS.has(reason)) throw error;
+    await quarantineTransaction(base, reason);
+    return { recovered: true };
+  } finally {
+    await release();
+  }
+  return { recovered: true };
+}
+
+function scopeKey(scope: MemoryScope, workspaceId?: string): string {
+  return scopeDirectory(scope, workspaceId);
+}
+
+/**
+ * 重建 `views/topics.md`（人类可读视图，不是权威数据）。
+ *
+ * 只在两种时刻调用：**全量扫描之后**，以及**记忆变更之后**。读路径不再触发它——
+ * 否则每次 recall / 建上下文包都要 readFile 一次，连「缓存命中」都带磁盘 IO，
+ * 而且 read-only 会话也会写盘。
+ */
+export async function refreshTopicView(
+  scope: MemoryScope,
+  workspaceId?: string,
+): Promise<void> {
+  const snapshot = await scanMemoryScope(scope, workspaceId);
+  await ensureTopicView(snapshot, scope, workspaceId);
+}
+
+function currentEpoch(key: string): number {
+  return scopeState(key).epoch;
+}
+
+function invalidateScope(scope: MemoryScope, workspaceId?: string): void {
+  const key = scopeKey(scope, workspaceId);
+  const state = scopeState(key);
+  state.epoch += 1;
+  if (state.cache && !state.cache.dirty) {
+    state.cache.dirty = true;
+    repositoryDiagnostics.watchInvalidations += 1;
+  }
+}
+
+function closeScopeWatchers(state: ScopeRuntimeState): void {
+  for (const watcher of state.watchers) watcher.close();
+  state.watchers = [];
+  state.watcherComplete = false;
+}
+
+function ensureScopeWatcher(
+  base: string,
+  scope: MemoryScope,
+  workspaceId?: string,
+): boolean {
+  const key = scopeKey(scope, workspaceId);
+  const state = scopeState(key);
+  if (state.watchers.length && !state.watcherRefreshRequired) return state.watcherComplete;
+  closeScopeWatchers(state);
+  state.watcherRefreshRequired = false;
+  try {
+    const watchers: FSWatcher[] = [];
+    const rootWatcher = watch(base, (event, filename) => {
+      if (typeof filename !== 'string') {
+        // 根目录的无名事件无法判定来源，不直接打脏；让下次读立即做轻量审计。
+        if (state.cache) state.cache.lastAuditAt = 0;
+        return;
+      }
+      if (GENERATED_SCOPE_ENTRIES.has(filename)) return;
+      if (event !== 'rename' || !CATEGORY_SCOPE_ENTRIES.has(filename)) return;
+      state.watcherRefreshRequired = true;
+      invalidateScope(scope, workspaceId);
+    });
+    rootWatcher.unref();
+    watchers.push(rootWatcher);
+
+    const watchCategory = (path: string): void => {
+      const watcher = watch(path, (_event, filename) => {
+        if (typeof filename === 'string' && !filename.endsWith('.md')) return;
+        if (typeof filename === 'string' && consumeInternalRecordEvent(join(path, filename))) return;
+        // 全量扫描刚结束时，部分平台会延迟送达「已被该快照包含」的旧事件。
+        // 这个短窗口内不盲目打脏，而是强制下次读做版本/目录审计；因此真实外部
+        // 修改仍会被发现，而迟到的旧事件不会导致无意义全量重扫。
+        if (Date.now() < state.suppressDirtyUntil) {
+          if (state.cache) state.cache.lastAuditAt = 0;
+          return;
+        }
+        invalidateScope(scope, workspaceId);
+      });
+      watcher.unref();
+      watchers.push(watcher);
+    };
+    // ★ 覆盖必须**完整**才敢自称 watcherActive，否则读路径不能享受 1 秒信任窗（见下）。
+    //   实测（Windows，`fs.watch` 非递归）：手工编辑 `<base>/profile/x.md` 只触发**分类目录**
+    //   上的 watcher（`change x.md`），base 上的 watcher 一声不吭——所以分类目录的 watcher
+    //   是「改动能不能被发现」的唯一依据。
+    //   ⚠️ 「不存在的分类目录」不算覆盖缺口：它装不下任何记录，而且它**被创建**时 base 上的
+    //   watcher 会收到 `rename <category>`（同样实测过），照样能作废缓存。只有目录确实存在
+    //   却挂不上 watcher（句柄耗尽、权限、网络盘…）才是真缺口，那时必须每次读都做审计。
+    let complete = true;
+    for (const category of ALL_CATEGORIES) {
+      try {
+        watchCategory(join(base, CATEGORY_DIR[category]));
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') complete = false;
+      }
+    }
+    const fallback = () => {
+      closeScopeWatchers(state);
+      state.watcherRefreshRequired = true;
+      if (state.cache) watcherActiveFallback(state.cache);
+    };
+    for (const watcher of watchers) watcher.on('error', fallback);
+    state.watchers = watchers;
+    state.watcherComplete = complete;
+    return complete;
+  } catch {
+    closeScopeWatchers(state);
+    return false;
+  }
+}
+
+function watcherActiveFallback(cached: ScopeCacheEntry): void {
+  cached.dirty = true;
+}
+
+function evictScopeCaches(): void {
+  if (scopeStates.size <= MAX_SCOPE_CACHE_ENTRIES) return;
+  const victims = [...scopeStates.entries()]
+    .sort((a, b) => a[1].lastUsedAt - b[1].lastUsedAt)
+    .slice(0, scopeStates.size - MAX_SCOPE_CACHE_ENTRIES);
+  for (const [key] of victims) {
+    const state = scopeStates.get(key);
+    if (state) closeScopeWatchers(state);
+    scopeStates.delete(key);
+    // ⚠️ 不能写 `path.startsWith(`${key}/`)`：Windows 上分隔符是 `\`，该条件恒为 false，
+    //    被淘汰 scope 的文件缓存永远清不掉 → fileCache 无上限增长。
+    for (const path of fileCache.keys()) {
+      if (pathContains(key, path)) fileCache.delete(path);
+    }
+  }
+}
+
+async function settleRecentWatcherEvents(state: ScopeRuntimeState): Promise<boolean> {
+  await new Promise<void>((resolvePromise) => { setImmediate(resolvePromise); });
+  if (state.cache?.dirty) return false;
+  const now = Date.now();
+  if (now - state.lastDrainAt >= WATCHER_SETTLE_REUSE_MS) {
+    await new Promise<void>((resolvePromise) => {
+      setTimeout(resolvePromise, WATCHER_SETTLE_WAIT_MS);
+    });
+    state.lastDrainAt = Date.now();
+  }
+  // 正常 watcher 在上面的 settle 窗口中会直接打脏；扫描结束后的抑制窗口只把
+  // lastAuditAt 清零，故仅这一种情况需要逐文件核验。稳定缓存不做 stat 扫描。
+  return state.cache?.lastAuditAt === 0 || Date.now() < state.suppressDirtyUntil;
+}
+
+async function cachedFilesUnchanged(snapshot: MemorySnapshot): Promise<boolean> {
+  const checks = await Promise.all(snapshot.records.map(async (record) => {
+    const path = memoryRecordPath(record);
+    const cached = fileCache.get(path);
+    if (!cached) return false;
+    try {
+      const info = await stat(path);
+      return cached.mtimeMs === info.mtimeMs && cached.size === info.size;
+    } catch {
+      return false;
+    }
+  }));
+  return checks.every(Boolean);
+}
+
+async function directoryFingerprint(base: string): Promise<string> {
+  const values = await Promise.all(ALL_CATEGORIES.map(async (category) => {
+    const dir = join(base, CATEGORY_DIR[category]);
+    try {
+      const info = await stat(dir);
+      return `${category}:${info.mtimeMs}:${info.size}`;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return `${category}:missing`;
+      return `${category}:error`;
+    }
+  }));
+  return values.join('|');
+}
+
+async function readCached(path: string): Promise<CachedFile> {
+  const info = await stat(path);
+  const cached = fileCache.get(path);
+  if (cached && cached.mtimeMs === info.mtimeMs && cached.size === info.size)
+    return cached;
+  const raw = await readFile(path, 'utf8');
+  const version = sha256(raw);
+  try {
+    const next: CachedFile = {
+      mtimeMs: info.mtimeMs,
+      size: info.size,
+      version,
+      record: parseMemoryRecord(raw, path),
+    };
+    fileCache.set(path, next);
+    return next;
+  } catch (error) {
+    const next: CachedFile = {
+      mtimeMs: info.mtimeMs,
+      size: info.size,
+      version,
+      diagnostic: { path, message: (error as Error).message },
+    };
+    fileCache.set(path, next);
+    return next;
+  }
+}
+
+export async function scanMemoryScope(
+  scope: MemoryScope,
+  workspaceId?: string,
+  attempt = 0,
+): Promise<MemorySnapshot> {
+  const base = scopeDirectory(scope, workspaceId);
+  const key = scopeKey(scope, workspaceId);
+  const state = scopeState(key);
+  const recovery = await recoverScopeTransaction(base);
+  let cachedScope = state.cache;
+  if (recovery.recovered && cachedScope) cachedScope.dirty = true;
+  const generationBefore = await readGeneration(base);
+  const now = Date.now();
+  // ★ 读路径保持纯读：缓存命中直接返回快照，不再顺手 readFile / 写 views/topics.md。
+  //   旧实现把 ensureTopicView 挂在**所有**返回分支上，于是「缓存命中」仍有磁盘 IO，
+  //   而且 memoryAccess:'read-only' 的会话也会写盘——仓储的读 API 不该有副作用。
+  //   视图改由「全量扫描后」与「变更后」触发（见 refreshTopicView）。
+  // ★ 新鲜度两条腿，缺一不可：
+  //
+  //   ① **排空一次事件循环**再判 dirty。`fs.watch` 的回调是排队派发的，「watcher 已挂上」
+  //      不等于「它已经把刚才那次改动告诉我了」。实测（Windows）：改完文件后只要让出
+  //      一个 setImmediate tick，事件就已送达。这一步零 IO，却把「刚改完立刻读」这个
+  //      最常见的竞态消掉了。旧代码也想干这事，但把它锁在「距上次使用 <50ms」的条件里，
+  //      两次读之间只要多做点别的（哪怕只是写一次设置）就绕过去了。
+  //
+  //   ② watcher 覆盖不全或压根没触发时，用 stat 审计兜底，节流到每秒最多一次。
+  //      审计是 O(记录数) 次 stat——实测 300 条记录约 40ms，放在每次读上太贵
+  //      （每回合 recall + buildContextBundle 各一次），所以必须节流；但 30 秒的信任窗
+  //      又太松，手编要等半分钟才生效。1 秒是两边都能接受的点。
+  //
+  //   ⚠️ 别再让读路径去写 `views/topics.md` 来「顺便」作废缓存——那是以前手编能被发现的
+  //      真实原因，纯属巧合，代价是每次读都做磁盘 IO。
+  let verifyAfterSettle = false;
+  if (cachedScope && !cachedScope.dirty) {
+    verifyAfterSettle = await settleRecentWatcherEvents(state);
+    cachedScope = state.cache;
+  }
+  if (cachedScope && !cachedScope.dirty && verifyAfterSettle) {
+    repositoryDiagnostics.fallbackAudits += 1;
+    if (
+      !await cachedFilesUnchanged(cachedScope.snapshot)
+      || cachedScope.directoryFingerprint !== await directoryFingerprint(base)
+    ) {
+      cachedScope.dirty = true;
+    } else {
+      cachedScope.lastAuditAt = Date.now();
+    }
+  }
+  if (cachedScope && !cachedScope.dirty) {
+    state.lastUsedAt = now;
+    // 只有 watcher 覆盖完整时才敢跳过审计——覆盖有缺口就等于没人会告诉我们变更，
+    // 那个 1 秒信任窗就失去依据，必须每次读都审计。
+    if (state.watcherComplete && now - cachedScope.lastAuditAt < SCOPE_AUDIT_TTL_MS) {
+      repositoryDiagnostics.snapshotHits += 1;
+      return cachedScope.snapshot;
+    }
+    repositoryDiagnostics.fallbackAudits += 1;
+    if (
+      await cachedFilesUnchanged(cachedScope.snapshot)
+      && cachedScope.directoryFingerprint === await directoryFingerprint(base)
+    ) {
+      cachedScope.lastAuditAt = now;
+      repositoryDiagnostics.snapshotHits += 1;
+      return cachedScope.snapshot;
+    }
+    cachedScope.dirty = true;
+  }
+  repositoryDiagnostics.fullScans += 1;
+  // ★ 先挂 watcher 再读文件，并记下代际号。
+  //   旧顺序是「先把记录全读完，最后才挂 watcher」，中间那段窗口里发生的改动**两头都漏**：
+  //   读的时候还没改，watcher 又还没挂上——扫完却把这份已经过时的快照标记为干净缓存，
+  //   于是直到下一次兜底审计（现在是 1 秒）之前，谁都发现不了。这是原设计里的 TOCTOU。
+  //   现在：先挂 watcher，扫完再比对代际号，期间有任何改动就重扫。
+  const watcherActive = ensureScopeWatcher(base, scope, workspaceId);
+  const epochBefore = currentEpoch(key);
+  const records: MemoryRecordV2[] = [];
+  // 隔离事务留下的告警要跟着本次快照走完，不能只写日志然后消失——
+  // diagnostics 是既有的、Desktop 与 diagnosticSuffix() 都会展示的通道。
+  const diagnostics: MemoryDiagnostic[] = await quarantineDiagnosticsFor(base);
+  const versions: Record<string, MemoryVersion> = {};
+  const seen = new Set<string>();
+  for (const category of ALL_CATEGORIES) {
+    const dir = join(base, CATEGORY_DIR[category]);
+    let names: string[] = [];
+    try {
+      names = (await readdir(dir, { withFileTypes: true }))
+        .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
+        .map((entry) => entry.name);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+        diagnostics.push({ path: dir, message: (error as Error).message });
+      }
+      continue;
+    }
+    for (const name of names) {
+      const path = join(dir, name);
+      seen.add(path);
+      try {
+        const cached = await readCached(path);
+        if (cached.diagnostic) {
+          diagnostics.push(cached.diagnostic);
+          continue;
+        }
+        const record = cached.record!;
+        if (
+          record.scope !== scope ||
+          record.category !== category ||
+          record.workspaceId !==
+            (scope === 'workspace' ? workspaceId : undefined) ||
+          name !== `${record.id}.md`
+        ) {
+          diagnostics.push({ path, message: '记忆元数据与所在目录不一致' });
+          continue;
+        }
+        records.push(record);
+        versions[record.id] = cached.version;
+      } catch (error) {
+        diagnostics.push({ path, message: (error as Error).message });
+      }
+    }
+  }
+
+  // 同上：硬编码 `/` 在 Windows 上永不命中，已删除记录的缓存条目会永久滞留。
+  for (const path of fileCache.keys()) {
+    if (path.endsWith('.md') && !seen.has(path) && pathContains(base, path)) {
+      fileCache.delete(path);
+    }
+  }
+  records.sort((a, b) => b.updatedAt - a.updatedAt);
+  const snapshot = { records, versions, diagnostics, createdAt: Date.now() };
+  const tailRecovery = await recoverScopeTransaction(base);
+  if (
+    (tailRecovery.recovered || generationBefore !== await readGeneration(base))
+    && attempt < MAX_SCAN_RETRIES
+  ) {
+    invalidateScope(scope, workspaceId);
+    return scanMemoryScope(scope, workspaceId, attempt + 1);
+  }
+  // 让排队中的 watcher 回调先送达，再判断这次扫描期间有没有人改过东西。
+  await new Promise<void>((resolvePromise) => { setImmediate(resolvePromise); });
+  // ⚠️ 重试必须有上限：持续写入的场景（cron 批量、另一个宿主导入、迁移）下每次重扫都会
+  //    看到新的代际号，无上限就是**活锁——读永远不返回**（还每轮重开 7 个 watcher）。
+  //    撞顶就照常缓存，让 1 秒兜底审计去纠正：最坏是几毫秒的陈旧快照且会自愈，
+  //    远好过一次挂死的 recall。
+  const changedDuringScan = currentEpoch(key) !== epochBefore;
+  if (changedDuringScan && attempt < MAX_SCAN_RETRIES) {
+    return scanMemoryScope(scope, workspaceId, attempt + 1);
+  }
+  state.cache = {
+    snapshot,
+    dirty: false,
+    directoryFingerprint: await directoryFingerprint(base),
+    // 撞了重试上限才落库的快照是**已知可能陈旧**的，不能再送它一个完整的 1 秒信任窗——
+    // 把审计时间戳清零，下一次读立刻走 stat 审计纠正。
+    lastAuditAt: changedDuringScan ? 0 : Date.now(),
+  };
+  state.watcherComplete = watcherActive;
+  state.lastUsedAt = Date.now();
+  state.suppressDirtyUntil = Date.now() + 100;
+  evictScopeCaches();
+  return snapshot;
+}
+
+export async function readVersionedMemory(
+  id: string,
+  scope: MemoryScope,
+  workspaceId?: string,
+): Promise<VersionedMemoryRecord | null> {
+  const snapshot = await scanMemoryScope(scope, workspaceId);
+  const record = snapshot.records.find((item) => item.id === id);
+  return record ? { record, version: snapshot.versions[id]! } : null;
+}
+
+export async function writeNewMemory(
+  record: MemoryRecordV2,
+): Promise<MemoryVersion> {
+  const path = memoryRecordPath(record);
+  const content = serializeMemoryRecord(record);
+  markInternalRecordEvent(path);
+  await atomicWriteFile(path, content);
+  fileCache.delete(path);
+  invalidateScope(record.scope, record.workspaceId);
+  return sha256(content);
+}
+
+export interface VersionedMemoryReplacement {
+  current: VersionedMemoryRecord;
+  next: MemoryRecordV2;
+  expectedVersion: MemoryVersion;
+}
+
+/** Recoverable, cross-process batch replacement for one memory scope. */
+export async function replaceMemoryBatchVersioned(
+  replacements: readonly VersionedMemoryReplacement[],
+): Promise<Record<string, MemoryVersion>> {
+  if (replacements.length === 0) return {};
+  const first = replacements[0]!;
+  const base = scopeDirectory(first.next.scope, first.next.workspaceId);
+  if (replacements.some(({ current, next }) =>
+    next.scope !== first.next.scope
+    || next.workspaceId !== first.next.workspaceId
+    || current.record.scope !== first.next.scope
+    || current.record.workspaceId !== first.next.workspaceId)) {
+    throw new Error('MEMORY_BATCH_SCOPE_MISMATCH');
+  }
+  const release = await acquireFileLock(join(base, '.records'));
+  const transactionId = randomUUID();
+  const stageDir = join(transactionRoot(base), transactionId);
+  let prepared = false;
+  try {
+    await rollForwardTransactionUnlocked(base);
+    const items: MemoryTransactionItem[] = [];
+    const versions: Record<string, MemoryVersion> = {};
+    await mkdir(stageDir, { recursive: true, mode: 0o700 });
+    for (const replacement of replacements) {
+      const oldPath = memoryRecordPath(replacement.current.record);
+      const nextPath = memoryRecordPath(replacement.next);
+      const liveRaw = await readFile(oldPath, 'utf8').catch((error) => {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
+        throw error;
+      });
+      if (liveRaw === null) throw new Error('MEMORY_NOT_FOUND');
+      if (sha256(liveRaw) !== replacement.expectedVersion) throw new Error('MEMORY_VERSION_CONFLICT');
+      const content = serializeMemoryRecord(replacement.next);
+      const targetVersion = sha256(content);
+      const stagePath = join(stageDir, `${replacement.next.id}.md`);
+      await atomicWriteFile(stagePath, content);
+      items.push({
+        id: replacement.next.id,
+        oldPath,
+        nextPath,
+        stagePath,
+        expectedVersion: replacement.expectedVersion,
+        targetVersion,
+      });
+      versions[replacement.next.id] = targetVersion;
+    }
+    const manifest: MemoryTransactionManifest = {
+      schemaVersion: 1,
+      id: transactionId,
+      items,
+    };
+    await atomicWriteFile(transactionManifestPath(base), `${JSON.stringify(manifest, null, 2)}\n`);
+    prepared = true;
+    await rollForwardTransactionUnlocked(base);
+    for (const replacement of replacements) {
+      fileCache.delete(memoryRecordPath(replacement.current.record));
+      fileCache.delete(memoryRecordPath(replacement.next));
+    }
+    invalidateScope(first.next.scope, first.next.workspaceId);
+    return versions;
+  } finally {
+    if (!prepared) await rm(stageDir, { recursive: true, force: true });
+    await release();
+  }
+}
+
+export async function replaceVersionedMemory(
+  current: VersionedMemoryRecord,
+  next: MemoryRecordV2,
+  expectedVersion: MemoryVersion,
+): Promise<MemoryVersion> {
+  const versions = await replaceMemoryBatchVersioned([{ current, next, expectedVersion }]);
+  return versions[next.id]!;
+}
+
+export async function removeVersionedMemory(
+  current: VersionedMemoryRecord,
+  expectedVersion?: MemoryVersion,
+): Promise<boolean> {
+  const path = memoryRecordPath(current.record);
+  const release = await acquireFileLock(
+    join(
+      scopeDirectory(current.record.scope, current.record.workspaceId),
+      '.records',
+    ),
+  );
+  try {
+    if (expectedVersion) {
+      const raw = await readFile(path, 'utf8').catch(() => null);
+      if (raw === null) return false;
+      if (sha256(raw) !== expectedVersion)
+        throw new Error('MEMORY_VERSION_CONFLICT');
+    }
+    try {
+      markInternalRecordEvent(path);
+      await unlink(path);
+      fileCache.delete(path);
+      invalidateScope(current.record.scope, current.record.workspaceId);
+      return true;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false;
+      throw error;
+    }
+  } finally {
+    await release();
+  }
+}
+
+export function clearMemoryIndex(): void {
+  fileCache.clear();
+  internalRecordEvents.clear();
+  for (const state of scopeStates.values()) closeScopeWatchers(state);
+  scopeStates.clear();
+}