recallnest 3.0.1 → 4.0.0

package/src/store.ts

@@ -12,6 +12,7 @@ import type { DurableMemoryCategory } from "./memory-schema.js";
 import { matchesScopeFilter, type ScopeMatchMode } from "./scope-policy.js";
 import { detectEmotionIfEnabled } from "./emotion-detector.js";
 import { withWriteLock } from "./distill-lock.js";
+import { STORE_WRITE_LOCK_OPTS, STORE_WRITE_LONG_LOCK_OPTS } from "./store-write-budget.js";
 import { incrementWriteCount } from "./activity-counter.js";
 import type { MemoryStorePort, MemoryStoreStats, MemoryStoreUpdate } from "./memory-store-port.js";
 import { clearVersionGroupMetadata, planSingletonVersionGroupRepairs } from "./version-manager.js";
@@ -57,6 +58,19 @@ export interface MemorySearchResult {
   score: number;
 }
 
+/** replaceWithArchivedVersion 的 plan 在锁内给出的：要新写的历史行，以及对原行的改动 */
+export interface ArchivedReplacePlan {
+  history: MemoryEntry;
+  updates: MemoryStoreUpdate;
+}
+
+export type ArchivedReplaceResult =
+  /** 原行已不在（重读时没找到，或写回时已被删掉）：库里什么都没留下 */
+  | { status: "missing" }
+  /** plan 返回 null：什么都没写，current 是锁内读到的行 */
+  | { status: "unchanged"; current: MemoryEntry }
+  | { status: "replaced"; entry: MemoryEntry; history: MemoryEntry };
+
 export interface StoreConfig {
   dbPath: string;
   vectorDim: number;
@@ -86,6 +100,14 @@ export interface LegacyScopeAudit {
   samples: LegacyScopeAuditSample[];
 }
 
+// ============================================================================
+// store-write lock options
+// ============================================================================
+
+// The store-write lock options live in store-write-budget.ts (the HTTP servers size their timeouts
+// from them too); re-exported here for existing callers.
+export { STORE_WRITE_LOCK_OPTS, STORE_WRITE_LONG_LOCK_OPTS };
+
 // ============================================================================
 // Deterministic ID
 // ============================================================================
@@ -133,7 +155,7 @@ function clampInt(value: number, min: number, max: number): number {
   return Math.min(max, Math.max(min, Math.floor(value)));
 }
 
-function escapeSqlLiteral(value: string): string {
+export function escapeSqlLiteral(value: string): string {
   return value.replace(/'/g, "''");
 }
 
@@ -232,7 +254,12 @@ const TABLE_NAME = "memories";
  * 应用层双检 `matchesScopeFilter(row, filter, mode)` 必须传同一个 mode，否则 SQL 收紧了
  * 应用层又放行（或反之），两层判据打架。
  */
-function scopeWhereClause(scopeFilter: string[], mode: ScopeMatchMode = "family"): string {
+/** `scope NOT IN (...)` — exact scope names, never prefix families. */
+export function scopeExclusionClause(excludeScopes: string[]): string {
+  return `(scope NOT IN (${excludeScopes.map((scope) => `'${escapeSqlLiteral(scope)}'`).join(", ")}))`;
+}
+
+export function scopeWhereClause(scopeFilter: string[], mode: ScopeMatchMode = "family"): string {
   return scopeFilter
     .map(scope => {
       const safe = escapeSqlLiteral(scope);
@@ -475,7 +502,7 @@ export class MemoryStore implements MemoryStorePort {
         // window a crash could tear). toWrite is already in-batch deduped by id above,
         // so the merge key matches ≤1 existing row (given no pre-existing dup-id rows).
         await this.table!.mergeInsert("id").whenMatchedUpdateAll().whenNotMatchedInsertAll().execute(toWrite);
-      }, { expireMs: 30_000 });
+      }, STORE_WRITE_LOCK_OPTS);
     } catch (err: any) {
       const code = err.code || "";
       const message = err.message || String(err);
@@ -494,6 +521,75 @@ export class MemoryStore implements MemoryStorePort {
     return toWrite.length;
   }
 
+  /**
+   * 只插入库里还不存在的 id，已存在的行一律不动（storeBatch 的 whenMatchedUpdateAll 会整行覆盖）。
+   *
+   * 给记忆文件对账用（memory-reconcile.ts）：规划时确认过「这段文字库里没有」，但规划到写入之间
+   * 别的写方（MCP / API / dream）可能已写入同一个确定性 id；覆盖会冲掉那一行的 metadata 与 evolution。
+   * 写锁内先查已存在的 id，再以 whenNotMatchedInsertAll 写入——即便查询与写入之间有别的进程绕过
+   * 写锁插入同 id，mergeInsert 也不会覆盖它。
+   */
+  async insertIfAbsent(
+    entries: (Omit<MemoryEntry, "id" | "timestamp"> & { id?: string })[],
+  ): Promise<{ inserted: string[]; skippedExisting: string[] }> {
+    if (entries.length === 0) return { inserted: [], skippedExisting: [] };
+    await this.ensureInitialized();
+
+    const byId = new Map<string, MemoryEntry>();
+    for (const entry of entries) {
+      const full: MemoryEntry = {
+        ...entry,
+        id: entry.id ?? deterministicId(entry.scope, entry.text),
+        timestamp: Date.now(),
+        metadata: entry.metadata || "{}",
+        language: entry.language || "en",
+        fts_text: entry.fts_text || entry.text,
+      };
+      const emotionResult = detectEmotionIfEnabled(full.text);
+      if (emotionResult) {
+        const meta = JSON.parse(full.metadata || "{}");
+        meta.emotion = emotionResult;
+        full.metadata = JSON.stringify(meta);
+      }
+      byId.set(full.id, full); // 同批同 id 只留最后一条
+    }
+    const candidates = [...byId.values()];
+
+    let result: { inserted: string[]; skippedExisting: string[] };
+    try {
+      result = await withWriteLock("store-write", async () => {
+        const conditions = candidates.map((e) => `id = '${escapeSqlLiteral(e.id)}'`).join(" OR ");
+        const existing = await this.table!.query().where(conditions).select(["id"]).limit(candidates.length).toArray();
+        const existingIds = new Set(existing.map((row) => row.id as string));
+        const fresh = candidates.filter((e) => !existingIds.has(e.id));
+        if (fresh.length > 0) {
+          await this.table!.mergeInsert("id").whenNotMatchedInsertAll().execute(fresh);
+        }
+        return {
+          inserted: fresh.map((e) => e.id),
+          skippedExisting: candidates.filter((e) => existingIds.has(e.id)).map((e) => e.id),
+        };
+      }, STORE_WRITE_LOCK_OPTS);
+    } catch (err: any) {
+      const code = err.code || "";
+      const message = err.message || String(err);
+      throw new Error(
+        `Failed to insert ${candidates.length} memories in "${this.config.dbPath}": ${code} ${message}` +
+        (this.schemaMigrationError ? `\n  Schema migration failed at init: ${this.schemaMigrationError}` : "")
+      );
+    }
+    try {
+      const statsPath = this.activityStatsPath();
+      const countByScope = new Map<string, number>();
+      for (const e of candidates) {
+        if (!result.inserted.includes(e.id)) continue;
+        countByScope.set(e.scope, (countByScope.get(e.scope) ?? 0) + 1);
+      }
+      for (const [scope, n] of countByScope) await incrementWriteCount(scope, n, { statsPath });
+    } catch { /* activity tracking is best-effort */ }
+    return result;
+  }
+
   /**
    * P0-1/P0-2/P1: Idempotent, crash-atomic write of a fully-formed entry, serialized
    * across processes.
@@ -516,7 +612,7 @@ export class MemoryStore implements MemoryStorePort {
     await this.ensureInitialized();
     await withWriteLock("store-write", async () => {
       await this.table!.mergeInsert("id").whenMatchedUpdateAll().whenNotMatchedInsertAll().execute([entry]);
-    }, { expireMs: 30_000 });
+    }, STORE_WRITE_LOCK_OPTS);
     // Per-scope write count drives dream activation. Best-effort — never block a write.
     try {
       await incrementWriteCount(entry.scope, 1, { statsPath: this.activityStatsPath() });
@@ -524,6 +620,38 @@ export class MemoryStore implements MemoryStorePort {
     return entry;
   }
 
+  /**
+   * Upsert that never moves a row back in time: a row already holding a newer timestamp is left
+   * as it is. The check is the merge's own condition, so it holds even when the caller's lock has
+   * expired and another writer got in first. Returns whether the row was inserted or updated.
+   * Used by the checkpoint mirror (src/checkpoint-mirror.ts), whose timestamp is the checkpoint's.
+   */
+  async upsertUnlessNewer(entry: MemoryEntry): Promise<boolean> {
+    await this.ensureInitialized();
+    // Every column present, defaults as in store(): lance 2.0's conditional merge panics on a source
+    // batch missing columns ("Incorrect number of arrays for StructArray fields"), which the
+    // unconditional merge in upsert() tolerates.
+    const full: MemoryEntry = {
+      ...entry,
+      metadata: entry.metadata || "{}",
+      language: entry.language || "en",
+      fts_text: entry.fts_text || entry.text,
+    };
+    const result = await withWriteLock("store-write", async () =>
+      this.table!.mergeInsert("id")
+        .whenMatchedUpdateAll({ where: "target.timestamp <= source.timestamp" })
+        .whenNotMatchedInsertAll()
+        .execute([full]),
+    STORE_WRITE_LOCK_OPTS);
+    const written = (result?.numInsertedRows ?? 0) + (result?.numUpdatedRows ?? 0) > 0;
+    if (written) {
+      try {
+        await incrementWriteCount(entry.scope, 1, { statsPath: this.activityStatsPath() });
+      } catch { /* activity tracking is best-effort */ }
+    }
+    return written;
+  }
+
   /**
    * Import a pre-built entry while preserving its id/timestamp.
    * Used for re-embedding / migration / A/B testing across embedding models.
@@ -582,6 +710,7 @@ export class MemoryStore implements MemoryStorePort {
     minScore = 0.3,
     scopeFilter?: string[],
     scopeMatch: ScopeMatchMode = "family",
+    excludeScopes?: string[],
   ): Promise<MemorySearchResult[]> {
     await this.ensureInitialized();
 
@@ -593,8 +722,13 @@ export class MemoryStore implements MemoryStorePort {
     // Apply scope filter if provided. Default mode "family" = 历史行为（含冒号精确 /
     // 无冒号前缀）；exact 由调用方显式声明。**必须下推到 SQL，不能事后在应用层滤**——
     // top-k 在收窄前就被兄弟 scope 占满，滤完只剩残缺候选（2026-08-16 互审 C1）。
-    if (scopeFilter && scopeFilter.length > 0) {
-      query = query.where(`(${scopeWhereClause(scopeFilter, scopeMatch)})`);
+    // Exclusions are pushed down for the same reason (resolveExcludedScopes in memory-boundaries.ts).
+    const where = [
+      ...(scopeFilter && scopeFilter.length > 0 ? [`(${scopeWhereClause(scopeFilter, scopeMatch)})`] : []),
+      ...(excludeScopes && excludeScopes.length > 0 ? [scopeExclusionClause(excludeScopes)] : []),
+    ];
+    if (where.length > 0) {
+      query = query.where(where.join(" AND "));
     }
 
     const results = await query.toArray();
@@ -612,6 +746,7 @@ export class MemoryStore implements MemoryStorePort {
       if (!matchesScopeFilter(rowScope, scopeFilter, scopeMatch)) {
         continue;
       }
+      if (excludeScopes?.includes(rowScope)) continue;
 
       mapped.push({
         entry: {
@@ -633,7 +768,7 @@ export class MemoryStore implements MemoryStorePort {
     return mapped;
   }
 
-  async bm25Search(query: string, limit = 5, scopeFilter?: string[]): Promise<MemorySearchResult[]> {
+  async bm25Search(query: string, limit = 5, scopeFilter?: string[], excludeScopes?: string[]): Promise<MemorySearchResult[]> {
     await this.ensureInitialized();
 
     if (!this.ftsIndexCreated) {
@@ -647,8 +782,12 @@ export class MemoryStore implements MemoryStorePort {
       let searchQuery = this.table!.search(query, "fts").limit(safeLimit);
 
       // Apply scope filter if provided (family mode, same as vectorSearch's default)
-      if (scopeFilter && scopeFilter.length > 0) {
-        searchQuery = searchQuery.where(`(${scopeWhereClause(scopeFilter)})`);
+      const where = [
+        ...(scopeFilter && scopeFilter.length > 0 ? [`(${scopeWhereClause(scopeFilter)})`] : []),
+        ...(excludeScopes && excludeScopes.length > 0 ? [scopeExclusionClause(excludeScopes)] : []),
+      ];
+      if (where.length > 0) {
+        searchQuery = searchQuery.where(where.join(" AND "));
       }
 
       const results = await searchQuery.toArray();
@@ -661,6 +800,7 @@ export class MemoryStore implements MemoryStorePort {
         if (!matchesScopeFilter(rowScope, scopeFilter)) {
           continue;
         }
+        if (excludeScopes?.includes(rowScope)) continue;
 
         // LanceDB FTS _score is raw BM25 (unbounded). Normalize with sigmoid.
         // LanceDB may return BigInt for numeric columns; coerce safely.
@@ -743,6 +883,7 @@ export class MemoryStore implements MemoryStorePort {
     limit = 20,
     offset = 0,
     scopeMatch: ScopeMatchMode = "family",
+    excludeScopes?: string[],
   ): Promise<MemoryEntry[]> {
     await this.ensureInitialized();
 
@@ -751,6 +892,10 @@ export class MemoryStore implements MemoryStorePort {
     // Build where conditions
     const conditions: string[] = [];
 
+    if (excludeScopes && excludeScopes.length > 0) {
+      conditions.push(scopeExclusionClause(excludeScopes));
+    }
+
     if (scopeFilter && scopeFilter.length > 0) {
       // 收窄必须在 SQL 里：limit 是在这之后下推的，事后过滤等于先截断再筛，
       // 目标 scope 实际拿到多少行不可控（2026-08-16 互审 C1/K3）。
@@ -805,15 +950,17 @@ export class MemoryStore implements MemoryStorePort {
     limit?: number;
     offset?: number;
     includeVector?: boolean;
+    /** 默认 family：无冒号的 scope 按前缀匹配（"memory" 会带进 "memory:pivot"）；exact 只要全等。 */
+    scopeMatch?: ScopeMatchMode;
   } = {}): Promise<MemoryEntry[]> {
     await this.ensureInitialized();
-    const { scopeFilter, category, limit = 1000, offset = 0, includeVector = false } = opts;
+    const { scopeFilter, category, limit = 1000, offset = 0, includeVector = false, scopeMatch = "family" } = opts;
 
     let query = this.table!.query();
 
     const conditions: string[] = [];
     if (scopeFilter && scopeFilter.length > 0) {
-      conditions.push(`((${scopeWhereClause(scopeFilter)}))`);
+      conditions.push(`((${scopeWhereClause(scopeFilter, scopeMatch)}))`);
     }
     if (category) {
       conditions.push(`category = '${escapeSqlLiteral(category)}'`);
@@ -1053,30 +1200,118 @@ export class MemoryStore implements MemoryStorePort {
       throw new Error(`Invalid memory ID format: ${id}`);
     }
 
-    let rows: any[];
+    // 前缀先在锁外解析成完整 id（全表扫，不放进锁里拉长持锁时间）；读整行与写回都在锁内按完整 id 做。
+    let fullId: string;
     if (isFullId) {
-      const safeId = escapeSqlLiteral(id);
-      rows = await this.table!.query().where(`id = '${safeId}'`).limit(1).toArray();
+      fullId = id;
     } else {
-      // Prefix match
-      const all = await this.table!.query().select(["id", "text", "vector", "category", "scope", "importance", "timestamp", "metadata", "language", "fts_text"]).toArray();
-      rows = all.filter((r: any) => (r.id as string).startsWith(id));
-      if (rows.length > 1) {
-        throw new Error(`Ambiguous prefix "${id}" matches ${rows.length} memories. Use a longer prefix or full ID.`);
+      const all = await this.table!.query().select(["id"]).toArray();
+      const matches = all.filter((r) => (r.id as string).startsWith(id));
+      if (matches.length > 1) {
+        throw new Error(`Ambiguous prefix "${id}" matches ${matches.length} memories. Use a longer prefix or full ID.`);
       }
+      if (matches.length === 0) return null;
+      fullId = matches[0].id as string;
     }
 
-    if (rows.length === 0) return null;
+    // 写路径一律包在 store-write 锁里（2026-08-14 起；巩固的批量元数据改动现在走 patchMetadataBatch，不再经这里）。
+    // 2026-10-17：读也挪进锁内、写回只更新已存在的行。原先锁外读整行、锁内 upsert，别的进程在这两步之间
+    // 删掉这一行（forget 等，delete() 不拿写锁），会被按读到的旧样子插回来；在这两步之间改的元数据也会被旧读数盖掉。
+    return withWriteLock("store-write", async () => {
+      const rows = await this.table!.query().where(`id = '${escapeSqlLiteral(fullId)}'`).limit(1).toArray();
+      if (rows.length === 0) return null;
+      const row = rows[0] as Record<string, unknown>;
+      if (!matchesScopeFilter((row.scope as string | undefined) ?? "", scopeFilter)) {
+        throw new Error(`Memory ${id} is outside accessible scopes`);
+      }
+      const updated = this.buildUpdatedEntry(row, updates);
+      // 只更新已存在的行：锁内读完之后被不拿锁的 delete() 删掉的行不插回来
+      const res = await this.table!.mergeInsert("id").whenMatchedUpdateAll().execute([updated]);
+      return res.numUpdatedRows > 0 ? updated : null;
+    }, STORE_WRITE_LOCK_OPTS);
+  }
 
-    const row = rows[0];
-    const rowScope = (row.scope as string | undefined) ?? "";
+  /**
+   * 在同一次 store-write 持锁里：按完整 id 重读原行 → 不在就什么都不写 → 在就交给 plan 拿最新行算出
+   * 历史行与对原行的改动，先写历史行、再只更新原行（2026-10-17，信念归档与覆盖不再是锁外两次写）。
+   *
+   * - plan 在锁内同步执行，只能做纯计算：取向量 / 调 embedder 这类慢操作由调用方在锁外先做好；
+   *   plan 里也不能调用会再拿 store-write 的公有方法（锁不可重入，会等自己到超时）。
+   * - plan 返回 null：不归档也不改原行，结果为 unchanged（带上锁内读到的行）。
+   * - 历史行按 plan 给的原样写入（language / fts_text 由 plan 负责，见 belief-history 的 replaceBeliefVersion）。
+   * - 原行在重读时已不在，或在写历史行之后、更新原行之前被不拿锁的 delete() 删掉：撤掉本次写的历史行
+   *   （它在本次之前就已存在则不动），结果为 missing，库里不留下指向不存在原行的历史行；撤销本身失败只记日志，仍返回 missing。
+   * - 更新原行抛错时同样撤掉本次写的历史行，再把错误抛出去。
+   *
+   * 已知局限：历史行 id 在本次之前就已存在时，这里照样整行覆盖它，失败时也不还原（undoHistory 只删本次新建的）。
+   * 历史行 id 按内容寻址（原行 id、timestamp、正文），所以只有同一版本先前写到一半（历史行写了、原行没更新）
+   * 之后重试才会撞上，覆盖进去的也是同一版本的内容。
+   */
+  async replaceWithArchivedVersion(
+    fullId: string,
+    plan: (current: MemoryEntry) => ArchivedReplacePlan | null,
+    scopeFilter?: string[],
+  ): Promise<ArchivedReplaceResult> {
+    await this.ensureInitialized();
 
-    // Check scope permissions
-    if (!matchesScopeFilter(rowScope, scopeFilter)) {
-      throw new Error(`Memory ${id} is outside accessible scopes`);
+    const result = await withWriteLock("store-write", async (): Promise<ArchivedReplaceResult> => {
+      const rows = await this.table!.query().where(`id = '${escapeSqlLiteral(fullId)}'`).limit(1).toArray();
+      if (rows.length === 0) return { status: "missing" };
+      const row = rows[0] as Record<string, unknown>;
+      if (!matchesScopeFilter((row.scope as string | undefined) ?? "", scopeFilter)) {
+        throw new Error(`Memory ${fullId} is outside accessible scopes`);
+      }
+      const current = this.buildUpdatedEntry(row, {});
+      const planned = plan(current);
+      if (!planned) return { status: "unchanged", current };
+
+      // 历史行原样写入：language / fts_text 由 plan 按正文算好，这里不再用 "en" / 原文顶替
+      const { history } = planned;
+      if (history.id === fullId) {
+        throw new Error(`History row id collided with canonical id ${fullId}`);
+      }
+      const updated = this.buildUpdatedEntry(row, planned.updates);
+      const safeHistoryId = escapeSqlLiteral(history.id);
+      const historyExisted = (await this.table!.query().select(["id"]).where(`id = '${safeHistoryId}'`).limit(1).toArray()).length > 0;
+      const undoHistory = async (): Promise<void> => {
+        if (!historyExisted) await this.table!.delete(`id = '${safeHistoryId}'`);
+      };
+
+      await this.table!.mergeInsert("id").whenMatchedUpdateAll().whenNotMatchedInsertAll().execute([history]);
+      let numUpdatedRows: number;
+      try {
+        numUpdatedRows = (await this.table!.mergeInsert("id").whenMatchedUpdateAll().execute([updated])).numUpdatedRows;
+      } catch (err) {
+        try {
+          await undoHistory();
+        } catch (undoErr) {
+          console.error(`[replaceWithArchivedVersion] failed to remove history row ${history.id} after the canonical update failed: ${undoErr instanceof Error ? undoErr.message : String(undoErr)}`);
+        }
+        throw err;
+      }
+      if (numUpdatedRows === 0) {
+        try {
+          await undoHistory();
+        } catch (undoErr) {
+          console.error(`[replaceWithArchivedVersion] failed to remove history row ${history.id} after the canonical row vanished: ${undoErr instanceof Error ? undoErr.message : String(undoErr)}`);
+        }
+        return { status: "missing" };
+      }
+      return { status: "replaced", entry: updated, history };
+    }, STORE_WRITE_LOCK_OPTS);
+
+    if (result.status === "replaced") {
+      // 与 upsert() 一致：历史行算一次写入，驱动 dream 激活。尽力而为，不阻塞写入。
+      try {
+        await incrementWriteCount(result.history.scope, 1, { statsPath: this.activityStatsPath() });
+      } catch { /* activity tracking is best-effort */ }
     }
+    return result;
+  }
 
-    // Build updated entry, preserving original timestamp and language fields
+  /** 由库里的一行加上改动拼出写回的整行，保留原 timestamp / language（update 与 patchMetadata 共用） */
+  private buildUpdatedEntry(row: Record<string, unknown>, updates: MemoryStoreUpdate): MemoryEntry {
+    const rowScope = (row.scope as string | undefined) ?? "";
     const updated: MemoryEntry = {
       id: row.id as string,
       text: updates.text ?? (row.text as string),
@@ -1102,22 +1337,6 @@ export class MemoryStore implements MemoryStorePort {
         updated.metadata = JSON.stringify(meta);
       }
     }
-
-    // Atomic upsert via mergeInsert — replaces the previous delete+add two-step,
-    // which could lose the row entirely on a crash between steps and exposed a
-    // window where concurrent reads saw the id momentarily vanish.
-    //
-    // 2026-08-14: 包进 store-write 锁与 upsert/storeBatch 对齐 —— 此前 update 是唯一
-    // 裸奔的写路径（dream 的 3a/3b/auto-gc 全走它），与其他进程的 mergeInsert 并发时
-    // 靠 LanceDB 乐观重试硬扛，是 commit conflict 的隐性源之一。
-    await withWriteLock("store-write", async () => {
-      await this.table!
-        .mergeInsert("id")
-        .whenMatchedUpdateAll()
-        .whenNotMatchedInsertAll()
-        .execute([updated]);
-    }, { expireMs: 30_000 });
-
     return updated;
   }
 
@@ -1134,11 +1353,14 @@ export class MemoryStore implements MemoryStorePort {
    * metadata object. A throwing patchFn abandons that patch — the error
    * propagates to the caller, later queued patches still run.
    *
-   * Scope of guarantee: in-process only. Cross-process writers (multiple
-   * mcp-server instances) and the remaining direct update() callers
-   * (consolidation/capture/forget/prospective/conflict engines, auto-gc)
-   * are NOT serialized by this queue. Long-term direction: make this the
-   * only legal metadata write path.
+   * Scope of guarantee: the per-id queue orders patches within this process;
+   * since 2026-09-24 the read and the write both happen inside the
+   * cross-process store-write lock, so a commit made by another process
+   * between them (reconcile retirement, dream consolidation, GC archive) is
+   * read and kept instead of overwritten. Direct update() callers that pass a
+   * metadata string they read earlier can still overwrite — they are not
+   * read-modify-write. Long-term direction: make this the only legal metadata
+   * write path.
    */
   async patchMetadata(
     id: string,
@@ -1159,9 +1381,17 @@ export class MemoryStore implements MemoryStorePort {
       fullId = resolved.id;
     }
 
-    const run = async (): Promise<MemoryEntry | null> => {
-      const entry = await this.getById(fullId);
-      if (!entry) return null;
+    // 读与写都在 store-write 锁内（2026-09-24）：原先在锁外 getById、再经 update() 写回，别的进程在这两步之间的提交
+    // （对账下架、dream 合并、GC 归档）会被这里拿旧行算出的元数据整行盖掉。锁不可重入，所以锁内不调 update()，
+    // 直接按同样的规则拼整行写回。
+    const run = async (): Promise<MemoryEntry | null> => withWriteLock("store-write", async () => {
+      const rows = await this.table!.query().where(`id = '${escapeSqlLiteral(fullId)}'`).limit(1).toArray();
+      if (rows.length === 0) return null;
+      const row = rows[0] as Record<string, unknown>;
+      if (!matchesScopeFilter((row.scope as string | undefined) ?? "", scopeFilter)) {
+        throw new Error(`Memory ${fullId} is outside accessible scopes`);
+      }
+      const entry = this.buildUpdatedEntry(row, {});
       let meta: Record<string, unknown>;
       try {
         const parsed: unknown = JSON.parse(entry.metadata || "{}");
@@ -1172,8 +1402,12 @@ export class MemoryStore implements MemoryStorePort {
         meta = {};
       }
       const patched = patchFn(meta, entry);
-      return this.update(fullId, { metadata: JSON.stringify(patched) }, scopeFilter);
-    };
+      const updated: MemoryEntry = { ...entry, metadata: JSON.stringify(patched) };
+      // 只更新已存在的行：delete() 不拿 store-write 锁，锁内读完之后这一行可能已被删掉（比如 forget），
+      // 不能把它插回来（2026-09-24 上线前代码单审）
+      const res = await this.table!.mergeInsert("id").whenMatchedUpdateAll().execute([updated]);
+      return res.numUpdatedRows > 0 ? updated : null;
+    }, STORE_WRITE_LOCK_OPTS);
 
     const prev = this.metadataPatchQueues.get(fullId) ?? Promise.resolve();
     // Isolate prior failures so one rejected patch can't wedge the queue.
@@ -1277,9 +1511,10 @@ export class MemoryStore implements MemoryStorePort {
           }
         }
         if (toWrite.length === 0) return 0;
-        await this.table!.mergeInsert("id").whenMatchedUpdateAll().whenNotMatchedInsertAll().execute(toWrite);
-        return toWrite.length;
-      }, { expireMs: 30_000 });
+        // 只更新已存在的行：锁内读完之后被不拿锁的 delete() 删掉的行不插回来，返回实际更新数（2026-09-24 上线前代码单审）
+        const res = await this.table!.mergeInsert("id").whenMatchedUpdateAll().execute(toWrite);
+        return res.numUpdatedRows;
+      }, STORE_WRITE_LOCK_OPTS);
     }
     return written;
   }
@@ -1296,7 +1531,7 @@ export class MemoryStore implements MemoryStorePort {
   async repairSingletonVersionGroups(): Promise<number> {
     await this.ensureInitialized();
 
-    return withWriteLock("store-write", async () => {
+    return withWriteLock("store-write", async (signal) => {
       const membershipRows = await this.table!.query()
         .select(["id", "metadata"])
         .toArray();
@@ -1311,6 +1546,12 @@ export class MemoryStore implements MemoryStorePort {
       let repaired = 0;
       const BATCH = 200;
       for (let i = 0; i < repairs.length; i += BATCH) {
+        // Past its max hold: stop between batches (each batch is an independent, re-checked
+        // commit) so the lock goes back to other writers; the rest is repaired next pass.
+        if (signal.aborted) {
+          logWarn(`[store] repairSingletonVersionGroups stopped after ${repaired} of ${repairs.length} repairs: held store-write past its max hold`);
+          break;
+        }
         const batch = repairs.slice(i, i + BATCH);
         const expectedById = new Map(batch.map(item => [item.id, item.groupId]));
         const conditions = batch
@@ -1357,7 +1598,7 @@ export class MemoryStore implements MemoryStorePort {
         repaired += result.numUpdatedRows;
       }
       return repaired;
-    }, { expireMs: 30 * 60_000 });
+    }, STORE_WRITE_LONG_LOCK_OPTS);
   }
 
   async bulkDelete(scopeFilter: string[], beforeTimestamp?: number): Promise<number> {

package/src/text-fingerprint.ts

@@ -0,0 +1,25 @@
+import { createHash } from "node:crypto";
+
+/**
+ * 判重与对账共用的文本归一：去掉转录行首的「[用户]」「[助手]」标记，空白折叠。
+ * （原定义在 ingest.ts，2026-09-24 挪到这里，免得 forget 引擎为一个五行函数载入整个导入模块；ingest.ts 原样再导出，行为不变。）
+ */
+export function normalizeDedupText(value: string): string {
+  return value
+    .replace(/^\[(用户|助手)\]\s*/gm, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/** 已归一文本的指纹（sha256 前 16 位十六进制）。 */
+export function fingerprintNormalized(norm: string): string {
+  return createHash("sha256").update(norm).digest("hex").slice(0, 16);
+}
+
+/**
+ * 文本指纹：先归一再取指纹。forget 的审计事件记它（`norm=<指纹>`），记忆文件对账据此认出「被 forget 的是这段文字」，
+ * 不管当时删的是同文的哪一行、原文空白差多少——只记 id 的话，删掉一行，同文的另一行照样会被恢复回来。
+ */
+export function textFingerprint(text: string): string {
+  return fingerprintNormalized(normalizeDedupText(text));
+}