recallnest 3.0.0 → 4.0.0

package/src/capture-engine.ts

@@ -1,12 +1,19 @@
 import type { Embedder } from "./embedder.js";
 import { detectLang, tokenizeFts } from "./language-hook.js";
 import { generateAnchor } from "./anchor-generator.js";
+import { normalizeTriggerTexts } from "./trigger-store.js";
 import { extractErrorSignatures } from "./error-signature.js";
 import { verifyWrite } from "./write-verifier.js";
 // batchInternalDedup is available in ingest.ts for large-batch scenarios;
 // persistMemoryBatch relies on per-item conflict detection (A-2) instead.
-import { defaultEvolution, buildSupersedeMetadata, buildSupersedeMetadataForNew, buildPendingReviewMetadata, isActiveMemory, parseEvolution, patchEvolution } from "./memory-evolution.js";
-import { archiveBeliefVersion, buildSupersedingBeliefMetadata } from "./belief-history.js";
+import { defaultEvolution, buildSupersedeMetadata, buildSupersedeMetadataForNew, buildPendingReviewMetadata, isActiveMemory, parseEvolution, patchEvolution, type EvolutionMetadata } from "./memory-evolution.js";
+import {
+  archiveBeliefVersion,
+  BeliefTargetMissingError,
+  buildSupersedingBeliefMetadata,
+  replaceBeliefVersion,
+  type BeliefReplaceDeps,
+} from "./belief-history.js";
 import { detectTopicTag, injectTopicTag } from "./topic-tag.js";
 import { assignDefaultConfidence, type ConfidenceMetadata } from "./confidence-tracker.js";
 import { parseDependsOnInput } from "./freshness.js";
@@ -34,6 +41,7 @@ import { deterministicId, type MemoryEntry, type MemoryStore } from "./store.js"
 import {
   buildDefaultCanonicalKey,
   buildStructuredMemoryBoundary,
+  CHECKPOINT_MIRROR_SCOPE,
   extractBoundaryMetadata,
   extractCanonicalKey,
   extractPromotedFrom,
@@ -64,7 +72,7 @@ import { checkAdmission, type ScopeRateLimiter, type AdmissionConfig } from "./a
 import { resolveNoisePrototypeBank, type NoisePrototypeBank } from "./noise-prototype-bank.js";
 import { tagNarrativeIfEnabled } from "./narrative-tagger.js";
 
-type StoreDeps = Pick<MemoryStore, "store"> & Partial<Pick<MemoryStore, "list" | "update" | "getById" | "get" | "vectorSearch" | "upsert">>;
+type StoreDeps = Pick<MemoryStore, "store"> & Partial<Pick<MemoryStore, "list" | "update" | "getById" | "get" | "vectorSearch" | "upsert" | "replaceWithArchivedVersion">>;
 type ConflictStoreDeps = Pick<ConflictCandidateStore, "save" | "replace" | "getOpenByFingerprint" | "getLatestByFingerprint">;
 
 export interface PersistMemoryDeps {
@@ -87,6 +95,29 @@ export interface PersistMemoryDeps {
    * Shadow-only: it observes and logs, it never rejects.
    */
   noisePrototypeBank?: NoisePrototypeBank | null;
+  /**
+   * T-Mem triggers 侧表（2026-09-22）。写入失败只 warn 不阻塞主写入：
+   * trigger 是召回入口不是证据，丢一次入口比丢一条记忆便宜得多。
+   */
+  triggerStore?: TriggerStoreDeps | null;
+  /** 给 trigger 用的 query 侧批量嵌入；缺省退回逐条 embedPassage */
+  embedQueryBatch?: (texts: string[]) => Promise<number[][]>;
+}
+
+/**
+ * persistMemory 的结果：记录本身加上这次实际挂到宿主上的 trigger 条数。
+ * 记录里的 `triggers` 是调用方传入的问法；有没有写进侧表只看 `triggersWritten`
+ * （rejected / conflict / 偏好判重或合并时都是 0），回执按它报数。
+ */
+export type PersistedMemoryRecord = StoredMemoryRecord & { triggersWritten: number };
+
+export interface TriggerStoreDeps {
+  upsertForMemory(
+    memoryId: string,
+    scope: string,
+    texts: readonly string[],
+    embed: (texts: string[]) => Promise<number[][]>,
+  ): Promise<number>;
 }
 
 export interface DurableWriteInput {
@@ -103,6 +134,14 @@ export interface DurableWriteInput {
   sourceBoundary?: ReturnType<typeof extractBoundaryMetadata>;
   language?: string;
   fts_text?: string;
+  /**
+   * 显式同 key 修订的目标行（2026-09-24）：persistMemory 在本 scope 找到后传入。
+   * 传入时写入端只拿这一行做全文判等与 latest-wins，不再全局选行——findCanonicalMatches 不分 scope，
+   * 窗口外的确定性 id 分支遇同文会用新 metadata 覆盖版本链，修订路径不能走那两条。
+   */
+  revisionTarget?: MemoryEntry;
+  /** persistMemory 已扫过的同 key 结果；传入时写入端不再自扫，一次写入只扫一遍整表。 */
+  precomputedMatches?: MemoryEntry[];
 }
 
 const CANONICAL_SCAN_LIMIT = 1000;
@@ -149,6 +188,93 @@ function mergeTags(...groups: string[][]): string[] {
   return merged.slice(0, 8);
 }
 
+// F-3b 覆盖结构化字段（2026-10-17）：原先只有拼好的正文过 redactSecrets，case / pattern 的
+// metadata、tags、显式 canonicalKey、trigger 都是原始入参，密钥原样进库、进外部嵌入接口。
+// scope 与 source 不动：scope 是路由键，source 是枚举。
+// 这些字段里放的是名字（key、标签、问法），`workflow.database.recovery` 这类点分标识符照原样留下；
+// 正文仍走默认规则，逐字节不变（已存行的确定性 id 靠它对得上）。
+const FIELD_REDACTION = { keepIdentifiers: true } as const;
+
+function redactField(value: string): string {
+  return redactSecrets(value, FIELD_REDACTION).text;
+}
+
+/** 只在字段存在时给出覆盖项，没传的可选字段不多出一个值为 undefined 的键。 */
+function redactOptional<K extends string>(key: K, value: string | undefined): Partial<Record<K, string>> {
+  return value === undefined ? {} : ({ [key]: redactField(value) } as Partial<Record<K, string>>);
+}
+
+/** 逐项脱敏后按不分大小写去重：两个不同的密钥脱敏后是同一个占位。 */
+function redactList(values: readonly string[]): string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const value of values) {
+    const redacted = redactField(value);
+    const key = redacted.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(redacted);
+  }
+  return out;
+}
+
+/**
+ * 显式 canonicalKey 里有密钥就整个丢掉、退回按正文生成的默认 key，而不是换成占位：
+ * 两条不相干的记忆脱敏后会撞成同一个 key，同 key 修订会把其中一条原位改写掉。
+ * 必须在 normalizeCanonicalKey 之前做——规整会把 `ghp_` 改成 `ghp-`，之后就认不出了。
+ */
+function withoutSecretCanonicalKey<T extends { canonicalKey?: string }>(input: T): T {
+  if (input.canonicalKey === undefined || redactSecrets(input.canonicalKey, FIELD_REDACTION).redacted === 0) return input;
+  const { canonicalKey: _dropped, ...rest } = input;
+  return rest as T;
+}
+
+function redactStoreMemoryFields(input: StoreMemoryInput): StoreMemoryInput {
+  return withoutSecretCanonicalKey({
+    ...input,
+    tags: redactList(input.tags),
+    ...redactOptional("topicTag", input.topicTag),
+    ...(input.triggers ? { triggers: input.triggers.map(redactField) } : {}),
+  });
+}
+
+function redactWorkflowPatternInput(input: WorkflowPatternInput): WorkflowPatternInput {
+  return withoutSecretCanonicalKey({
+    ...input,
+    title: redactField(input.title),
+    trigger: redactField(input.trigger),
+    steps: input.steps.map(redactField),
+    ...redactOptional("outcome", input.outcome),
+    tools: redactList(input.tools),
+    tags: redactList(input.tags),
+  });
+}
+
+function redactCaseMemoryInput(input: CaseMemoryInput): CaseMemoryInput {
+  const { debugFraming } = input;
+  return withoutSecretCanonicalKey({
+    ...input,
+    title: redactField(input.title),
+    problem: redactField(input.problem),
+    ...redactOptional("context", input.context),
+    solutionSteps: input.solutionSteps.map(redactField),
+    ...redactOptional("outcome", input.outcome),
+    tools: redactList(input.tools),
+    tags: redactList(input.tags),
+    ...(debugFraming
+      ? {
+          debugFraming: {
+            ...debugFraming,
+            ...redactOptional("whyPriorFixFailed", debugFraming.whyPriorFixFailed),
+            ...redactOptional("defense", debugFraming.defense),
+            ...redactOptional("systematicExtension", debugFraming.systematicExtension),
+            ...redactOptional("knowledgeFix", debugFraming.knowledgeFix),
+          },
+        }
+      : {}),
+  });
+}
+
 export function buildStructuredMetadata(params: {
   source: string;
   tags: string[];
@@ -442,7 +568,9 @@ async function findCanonicalMatches(
   canonicalKey: string,
 ): Promise<MemoryEntry[]> {
   if (!store.list) return [];
-  const entries = await store.list(undefined, undefined, CANONICAL_SCAN_LIMIT, 0);
+  // Checkpoint-mirror rows are session layer (never a match below) but carry recent timestamps;
+  // keep them out of the newest-N window so they cannot push durable rows out of it.
+  const entries = await store.list(undefined, undefined, CANONICAL_SCAN_LIMIT, 0, undefined, [CHECKPOINT_MIRROR_SCOPE]);
   return entries.filter((entry) => {
     const boundary = extractBoundaryMetadata(entry.metadata);
     if (boundary?.layer !== "durable") return false;
@@ -454,6 +582,111 @@ async function findCanonicalMatches(
   });
 }
 
+/**
+ * 「显式同 key 修订」的判定（2026-09-24，互审见 AI产出/2026-09-24-recallnest-同key偏好修订/）。
+ *
+ * 只扫一次整表；扫描结果不论是否找到目标行都交给 writeDurableEntry 复用，写入端不再自扫。
+ * 目标行 = 同 scope、同 canonicalKey、同类别、活跃、durable。同 scope 里若还有同 key 的
+ * 其他类别活跃行，不当修订（target=null），让原路径照旧产生跨类别冲突。
+ */
+async function resolveSameKeyRevision(
+  store: StoreDeps,
+  scope: string,
+  canonicalKey: string,
+  category: DurableMemoryCategory,
+): Promise<{ matches: MemoryEntry[]; target: MemoryEntry | null }> {
+  const matches = await findCanonicalMatches(store, canonicalKey);
+  const inScope = matches.filter((entry) => entry.scope === scope);
+  if (inScope.some((entry) => entry.category !== category)) return { matches, target: null };
+  const inScan = inScope
+    .filter((entry) => entry.category === category)
+    .sort((a, b) => b.timestamp - a.timestamp)[0];
+  if (inScan) return { matches, target: inScan };
+  // 扫描窗口（最近 CANONICAL_SCAN_LIMIT 行，store.list 按 timestamp 倒序）外的旧行：按确定性 id 直查。
+  // durable 判定比 writeDurableEntry 自己的 id 回查严格，有意为之——只把确认合格的行当修订目标；
+  // 判定失败时 target=null，写入照旧走原逻辑。
+  if (!store.getById) return { matches, target: null };
+  const row = await store.getById(deterministicId(scope, canonicalKey));
+  const qualifies =
+    row !== null &&
+    row.scope === scope &&
+    row.category === category &&
+    extractBoundaryMetadata(row.metadata)?.layer === "durable" &&
+    isActiveMemory(row.metadata);
+  return { matches, target: qualifies ? row : null };
+}
+
+/** store 能在一次持锁里归档并覆盖（真实 MemoryStore）时给出 replaceBeliefVersion 的依赖；窄 store（测试替身）返回 null */
+function atomicBeliefDeps(deps: PersistMemoryDeps): BeliefReplaceDeps | null {
+  const { store } = deps;
+  const replace = store.replaceWithArchivedVersion;
+  if (!replace) return null;
+  return {
+    store: {
+      replaceWithArchivedVersion: replace.bind(store),
+      ...(store.getById ? { getById: store.getById.bind(store) } : {}),
+    },
+    embedder: deps.embedder,
+  };
+}
+
+/**
+ * latest-wins 的原位替换：先把旧版本归档成 superseded 历史行，再把新文本写回同一 id。
+ * 原地覆盖曾经连旧文本带向量一起删掉，「上个月我信的是什么」因此无从回答。
+ *
+ * 2026-10-17：store 有 replaceWithArchivedVersion（真实 MemoryStore）时，重读原行、写历史行、覆盖原行在同一次
+ * store-write 持锁里完成。原行在找到它之后被别的进程删掉（forget 等）→ 什么都不写，抛 BeliefTargetMissingError；
+ * 原先会先留下一条指向不存在原行的历史行，再报 `Failed to update canonical memory`。
+ * 只有 update 的窄 store（测试替身）退回原来的两次写。
+ */
+async function replaceBeliefInPlace(
+  deps: PersistMemoryDeps,
+  latest: MemoryEntry,
+  params: DurableWriteInput,
+): Promise<{ entry: MemoryEntry; disposition: "updated" | "promoted"; supersededPrevious: true }> {
+  const disposition = params.promotedFrom ? "promoted" : "updated";
+  const buildUpdates = (previousEvo: EvolutionMetadata, historyId: string, now: number) => ({
+    text: params.text,
+    vector: params.vector,
+    importance: params.importance,
+    category: params.category,
+    // Merge rather than replace: a bare params.metadata would wipe the evolution block
+    // (version, access stats, supersede links) along with the text.
+    metadata: buildSupersedingBeliefMetadata(params.metadata, previousEvo, historyId, now),
+    timestamp: now,
+    ...(params.language ? { language: params.language } : {}),
+    ...(params.fts_text ? { fts_text: params.fts_text } : {}),
+  });
+
+  const atomic = atomicBeliefDeps(deps);
+  if (atomic) {
+    const result = await replaceBeliefVersion(
+      atomic,
+      latest,
+      ({ previousEvolution, historyId, now }) => buildUpdates(previousEvolution, historyId, now),
+    );
+    if (result.status !== "replaced") throw new BeliefTargetMissingError(latest.id);
+    return { entry: result.entry, disposition, supersededPrevious: true };
+  }
+
+  if (!deps.store.update) {
+    throw new Error(`store.update is required to replace canonical memory ${latest.id}`);
+  }
+  const now = Date.now();
+  const previousEvo = parseEvolution(latest.metadata, latest.timestamp);
+  const { historyId } = await archiveBeliefVersion(
+    { store: deps.store, embedder: deps.embedder },
+    latest,
+    { now },
+  );
+
+  const updated = await deps.store.update(latest.id, buildUpdates(previousEvo, historyId, now));
+  if (!updated) {
+    throw new Error(`Failed to update canonical memory ${latest.id}`);
+  }
+  return { entry: updated, disposition, supersededPrevious: true };
+}
+
 export async function writeDurableEntry(
   deps: PersistMemoryDeps,
   params: DurableWriteInput,
@@ -461,8 +694,31 @@ export async function writeDurableEntry(
   entry: MemoryEntry;
   disposition: "stored" | "updated" | "deduped" | "promoted" | "conflict";
   conflictId?: string;
+  /**
+   * True when this write REPLACED the content of an existing canonical row
+   * (a belief version was archived). Two different paths can do that — the
+   * latest-wins branch reports `updated`, while the deterministic-id branch
+   * below still reports `stored` — so disposition alone cannot tell them
+   * apart. Consumers that mirror memory content elsewhere (KG triples) must
+   * drop the old projection when this is set.
+   */
+  supersededPrevious?: boolean;
 }> {
-  const matches = await findCanonicalMatches(deps.store, params.canonicalKey);
+  const conflictPolicy = getConflictPolicyForCategory(params.category);
+
+  // 显式同 key 修订：只拿 persistMemory 在本 scope 找到的那一行做判等与原位替换。
+  // 写之前按 id 重读一次——F2 干扰预警可能刚改过它的 metadata；已不再活跃就退回原逻辑。
+  if (params.revisionTarget && !params.promotedFrom && conflictPolicy === "latest-wins" && deps.store.update) {
+    const fresh = deps.store.getById ? await deps.store.getById(params.revisionTarget.id) : params.revisionTarget;
+    if (fresh && isActiveMemory(fresh.metadata)) {
+      if (normalizeMemoryText(fresh.text) === normalizeMemoryText(params.text)) {
+        return { entry: fresh, disposition: "deduped" };
+      }
+      return await replaceBeliefInPlace(deps, fresh, params);
+    }
+  }
+
+  const matches = params.precomputedMatches ?? await findCanonicalMatches(deps.store, params.canonicalKey);
   const categoryMatches = matches.filter((entry) => entry.category === params.category);
   const crossCategoryMatches = matches.filter((entry) => entry.category !== params.category);
   const normalizedIncoming = normalizeMemoryText(params.text);
@@ -521,7 +777,6 @@ export async function writeDurableEntry(
     };
   }
 
-  const conflictPolicy = getConflictPolicyForCategory(params.category);
   if (conflictPolicy === "latest-wins" && categoryMatches.length > 0 && deps.store.update) {
     const latest = [...categoryMatches].sort((a, b) => b.timestamp - a.timestamp)[0];
     if (params.promotedFrom) {
@@ -576,36 +831,8 @@ export async function writeDurableEntry(
       }
     }
 
-    // latest-wins is where beliefs change. Archive the version being replaced first —
-    // overwriting in place used to delete the old text + vector outright, which is what
-    // made "what did I believe last month?" unanswerable no matter how retrieval queried.
-    const now = Date.now();
-    const previousEvo = parseEvolution(latest.metadata, latest.timestamp);
-    const { historyId } = await archiveBeliefVersion(
-      { store: deps.store, embedder: deps.embedder },
-      latest,
-      { now },
-    );
-
-    const updated = await deps.store.update(latest.id, {
-      text: params.text,
-      vector: params.vector,
-      importance: params.importance,
-      category: params.category,
-      // Merge rather than replace: a bare params.metadata would wipe the evolution block
-      // (version, access stats, supersede links) along with the text.
-      metadata: buildSupersedingBeliefMetadata(params.metadata, previousEvo, historyId, now),
-      timestamp: now,
-      ...(params.language ? { language: params.language } : {}),
-      ...(params.fts_text ? { fts_text: params.fts_text } : {}),
-    });
-    if (!updated) {
-      throw new Error(`Failed to update canonical memory ${latest.id}`);
-    }
-    return {
-      entry: updated,
-      disposition: params.promotedFrom ? "promoted" : "updated",
-    };
+    // latest-wins is where beliefs change: archive the version being replaced, then write in place.
+    return await replaceBeliefInPlace(deps, latest, params);
   }
 
   // No canonical match was found, so this falls through to store(). With a canonicalKey the
@@ -617,10 +844,57 @@ export async function writeDurableEntry(
     ? deterministicId(params.scope, params.canonicalKey)
     : undefined;
   let metadataForStore = params.metadata;
+  let supersededPrevious = false;
 
   if (targetId && deps.store.getById) {
     const rowAtTargetId = await deps.store.getById(targetId);
-    if (rowAtTargetId && normalizeMemoryText(rowAtTargetId.text) !== normalizeMemoryText(params.text)) {
+    const normalizedIncomingText = normalizeMemoryText(params.text);
+    // 那一行活跃、且已经是这段正文：与上面 exact 命中同样处理（promotedFrom 时追加晋升来源、报 promoted，否则 deduped），
+    // 不落到 store()——store() 用 params.metadata 整行覆盖，会抹掉它的 evolution（version / supersedes）。
+    // 扫描窗口外的 canonical 行只会走到这里，exact 分支看不见它（2026-10-17 owner review）。
+    // 不活跃的同文行（auto-gc / 对账原地 archived、consolidated，id 不变）不去重：findCanonicalMatches 把它们滤掉了才会
+    // 走到这里，去重会让它照旧不活跃、默认召回看不见。它和异文一样走下面的替换——留历史行、原行设回 active
+    // （promotedFrom 也一样：appendPromotionObservationToExistingEntry 不会把它重新激活）。
+    const sameText = async (existing: MemoryEntry) => params.promotedFrom
+      ? { entry: await appendPromotionObservationToExistingEntry(deps.store, existing, params.metadata), disposition: "promoted" as const }
+      : { entry: existing, disposition: "deduped" as const };
+    const isLiveSameText = (row: MemoryEntry) =>
+      isActiveMemory(row.metadata) && normalizeMemoryText(row.text) === normalizedIncomingText;
+    if (rowAtTargetId && isLiveSameText(rowAtTargetId)) {
+      return await sameText(rowAtTargetId);
+    }
+    const atomic = atomicBeliefDeps(deps);
+    if (rowAtTargetId && atomic) {
+      // 归档与覆盖同一次持锁（2026-10-17）。写入的字段与默认值照下面 store() 的那一份：text 换了，
+      // language / fts_text 不能沿用旧行的。原行在锁内重读时已不在（被 forget 等删掉）→ 不留历史行，
+      // 落到下面的 store() 当新行写入——原先这里会把已删内容写成一条历史行；锁内重读发现正文已与新的相同 → deduped。
+      const replaced = await replaceBeliefVersion(
+        atomic,
+        rowAtTargetId,
+        ({ previousEvolution, historyId, now }) => ({
+          text: params.text,
+          vector: params.vector,
+          category: params.category,
+          importance: params.importance,
+          metadata: buildSupersedingBeliefMetadata(params.metadata, previousEvolution, historyId, now),
+          timestamp: now,
+          language: params.language || "en",
+          fts_text: params.fts_text || params.text,
+        }),
+        { skip: isLiveSameText },
+      );
+      if (replaced.status === "replaced") {
+        return {
+          entry: replaced.entry,
+          disposition: params.promotedFrom ? "promoted" : "stored",
+          supersededPrevious: true,
+        };
+      }
+      if (replaced.status === "unchanged") {
+        // 锁内重读发现那一行活跃、且已经是这段正文（别的进程刚写过同文、带着它自己的版本链）：同上，不再 store()
+        return await sameText(replaced.current);
+      }
+    } else if (rowAtTargetId) {
       const now = Date.now();
       const previousEvo = parseEvolution(rowAtTargetId.metadata, rowAtTargetId.timestamp);
       const { historyId } = await archiveBeliefVersion(
@@ -629,6 +903,7 @@ export async function writeDurableEntry(
         { now },
       );
       metadataForStore = buildSupersedingBeliefMetadata(params.metadata, previousEvo, historyId, now);
+      supersededPrevious = true;
     }
   }
 
@@ -647,6 +922,7 @@ export async function writeDurableEntry(
   return {
     entry: stored,
     disposition: params.promotedFrom ? "promoted" : "stored",
+    supersededPrevious,
   };
 }
 
@@ -690,6 +966,9 @@ function inferPromotedCategory(
 function buildStoreMemoryMetadata(input: StoreMemoryInput, canonicalKey: string): string {
   const anchor = generateAnchor(input.text);
   const anchorExtra = anchor ? { anchor } : undefined;
+  // T-Mem triggers：文本副本进 metadata（侧表可由它重建），向量进 memory_triggers 侧表
+  const triggers = normalizeTriggerTexts(input.triggers);
+  const triggerExtra = triggers.length > 0 ? { triggers } : undefined;
   // HP-ethics: Include privacyTier in metadata if non-default
   const privacyExtra = input.privacyTier && input.privacyTier !== "durable"
     ? { privacyTier: input.privacyTier }
@@ -700,7 +979,7 @@ function buildStoreMemoryMetadata(input: StoreMemoryInput, canonicalKey: string)
     capture: "store_memory_schema_v1",
     category: input.category,
     canonicalKey,
-    extra: mergeExtra(buildPreferenceSlotExtra(input.category, input.text), anchorExtra, privacyExtra),
+    extra: mergeExtra(buildPreferenceSlotExtra(input.category, input.text), anchorExtra, privacyExtra, triggerExtra),
     narrativeInput: { scope: input.scope, text: input.text },
   });
 }
@@ -801,10 +1080,62 @@ function buildPromotionMetadata(
   });
 }
 
+/**
+ * T-Mem triggers（2026-09-22）：宿主写完再写入口。deduped（同文本已存在）也写——老条目补 trigger
+ * 正是回填的常态，此时顺手把文本副本补进旧行 metadata（侧表可由它重建）。失败只 warn：入口丢一次
+ * 比记忆丢一条便宜。
+ * 返回侧表实际写入的条数（没有侧表、没有 trigger、写入失败都是 0），回执按它报数。
+ */
+async function writeTriggersForEntry(
+  deps: PersistMemoryDeps,
+  entry: MemoryEntry,
+  resolvedScope: string,
+  triggerTexts: string[],
+  backfillMetadata: boolean,
+): Promise<number> {
+  if (!deps.triggerStore || triggerTexts.length === 0) return 0;
+  let written = 0;
+  try {
+    const embedBatch = deps.embedQueryBatch
+      ?? (async (texts: string[]) => Promise.all(texts.map((t) => deps.embedder.embedPassage(t))));
+    written = await deps.triggerStore.upsertForMemory(entry.id, entry.scope || resolvedScope, triggerTexts, embedBatch);
+    if (backfillMetadata && deps.store.update) {
+      const parsedMeta: Record<string, unknown> = JSON.parse(entry.metadata || "{}");
+      const prev = Array.isArray(parsedMeta.triggers) ? (parsedMeta.triggers as unknown[]).join("\u0000") : "";
+      if (prev !== triggerTexts.join("\u0000")) {
+        parsedMeta.triggers = triggerTexts;
+        await deps.store.update(entry.id, { metadata: JSON.stringify(parsedMeta) });
+      }
+    }
+    return written;
+  } catch (err) {
+    console.error(`[recallnest] trigger write failed for ${entry.id} (memory stored, trigger 入口未写):`, err instanceof Error ? err.message : String(err));
+    // 侧表已写、只是 metadata 副本没回填时，written 仍是侧表里的条数
+    return written;
+  }
+}
+
+/**
+ * Longest text the implicit preference dual-write will copy, in UTF-16 code
+ * units (`String.length`) of the schema-normalized text — a rough cap, not a
+ * precise character count.
+ * The 13 derived rows found in the production table on 2026-10-10 were all
+ * 446–1,653 characters of narrative; the statements the feature is for
+ * ("I use Figma for design") are a single short sentence.
+ */
+export const IMPLICIT_PREFERENCE_MAX_TEXT_CHARS = 120;
+
+/** Whether a just-stored memory should also get a derived preferences copy. */
+export function shouldDeriveImplicitPreference(category: string, text: string): boolean {
+  if (category === "preferences") return false;
+  if (text.length > IMPLICIT_PREFERENCE_MAX_TEXT_CHARS) return false;
+  return inferImplicitUsageSlot(text) !== null;
+}
+
 export async function persistMemory(
   deps: PersistMemoryDeps,
   rawInput: unknown,
-): Promise<StoredMemoryRecord> {
+): Promise<PersistedMemoryRecord> {
   let input = StoreMemoryInputSchema.parse(rawInput);
 
   // F-3b: Scan THEN redact, before the text reaches any external surface —
@@ -812,9 +1143,8 @@ export async function persistMemory(
   // Scan first so the piiWarning below still reflects what the raw text held.
   const piiScan = scanForPII(input.text);
   const redaction = redactSecrets(input.text);
-  if (redaction.redacted > 0) {
-    input = { ...input, text: redaction.text };
-  }
+  // tags / 显式 canonicalKey / topicTag / triggers 同样会进 metadata、侧表与外部嵌入接口
+  input = redactStoreMemoryFields({ ...input, text: redaction.text });
 
   // F3: Extract temporal validity params before Zod strips them
   const rawObj = rawInput as Record<string, unknown> | null;
@@ -903,6 +1233,7 @@ export async function persistMemory(
       storedAt: new Date().toISOString(),
       disposition: "rejected" as const,
       ...(admission.reason ? { rejectionReason: admission.reason } : {}),
+      triggersWritten: 0,
     };
   }
 
@@ -925,11 +1256,30 @@ export async function persistMemory(
     canonicalKey: input.canonicalKey,
   });
 
+  // 显式同 key 修订（2026-09-24）：调用方带着显式 key 改写本 scope 已有的同类别偏好时，
+  // 不再交给 Tier 3.6 做语义判重——相似度 ≥0.92 会被直接跳过，修订因此丢掉；改由
+  // writeDurableEntry 对目标行做全文判等与原位替换。新 key、无 key 的写入照旧判重。
+  const explicitKey = input.canonicalKey ? normalizeCanonicalKey(input.canonicalKey) : "";
+  const sameKey =
+    input.category === "preferences" && explicitKey !== ""
+      ? await resolveSameKeyRevision(deps.store, resolvedScope, canonicalKey, input.category)
+      : null;
+  const revisionTarget = sameKey?.target ?? null;
+
+  // 同 key 且全文相同：赶在 A-2 / F2 之前按 deduped 返回。原版在 Tier 3.6 判重处就提前返回，这类写入
+  // 从不触发 F2 干扰预警；放到后面，一次 deduped 写入会把别的行标成 pending_review（实施后 Codex 审查，
+  // 真实临时库复现）。triggers 回填照做。
+  if (revisionTarget && normalizeMemoryText(revisionTarget.text) === normalizeMemoryText(input.text)) {
+    const triggersWritten = await writeTriggersForEntry(deps, revisionTarget, resolvedScope, normalizeTriggerTexts(input.triggers), true);
+    return { ...toStoredRecord(input, revisionTarget, "deduped", canonicalKey), triggersWritten };
+  }
+
   // Tier 3.6: For preferences, check if similar preference already exists.
   // If matched, merge into existing or skip — avoids duplicate accumulation.
   if (
     input.category === "preferences" &&
-    deps.store.vectorSearch
+    deps.store.vectorSearch &&
+    !revisionTarget
   ) {
     const matchResult = await matchPreference(
       input.text,
@@ -946,6 +1296,8 @@ export async function persistMemory(
         { embedder: deps.embedder },
       );
       if (applied.handled) {
+        // skip 时 entry 是被命中的那一行（回执报它的 id）；这条分支不写 trigger，triggersWritten 记 0。
+        // 兜底的 "skipped" 只给不带 matchedEntry 的手工 skip 结果，matchPreference 自己产出的都带。
         const entry = applied.entry ?? {
           id: "skipped",
           text: input.text,
@@ -956,12 +1308,15 @@ export async function persistMemory(
           timestamp: Date.now(),
           metadata: "{}",
         };
-        return toStoredRecord(
-          input,
-          entry,
-          matchResult.action === "merge" ? "updated" : "deduped",
-          canonicalKey,
-        );
+        return {
+          ...toStoredRecord(
+            input,
+            entry,
+            matchResult.action === "merge" ? "updated" : "deduped",
+            canonicalKey,
+          ),
+          triggersWritten: 0,
+        };
       }
     }
   }
@@ -997,10 +1352,13 @@ export async function persistMemory(
           if (decision.action === "MERGE") {
             const oldEntry = supersedeTargets[0].entry;
             const supersededMeta = buildSupersedeMetadata(oldEntry.metadata, deterministicId(resolvedScope, input.text));
-            await deps.store.update(oldEntry.id, { metadata: supersededMeta });
-            // HP-1: Track for bidirectional link
-            supersededOldId = oldEntry.id;
-            supersededReason = decision.reason;
+            const marked = await deps.store.update(oldEntry.id, { metadata: supersededMeta });
+            // HP-1: Track for bidirectional link — only when the old row was actually marked;
+            // update() returns null when it was deleted meanwhile, and the new row must not point at it.
+            if (marked) {
+              supersededOldId = oldEntry.id;
+              supersededReason = decision.reason;
+            }
           }
         }
         // CREATE or error → proceed normally (store new memory as-is)
@@ -1106,7 +1464,7 @@ export async function persistMemory(
     metadata = JSON.stringify(parsed);
   }
 
-  const { entry, disposition, conflictId } = await writeDurableEntry(deps, {
+  const { entry, disposition, conflictId, supersededPrevious } = await writeDurableEntry(deps, {
     text: input.text,
     vector,
     category: input.category,
@@ -1117,16 +1475,32 @@ export async function persistMemory(
     source: input.source,
     language,
     fts_text,
+    ...(revisionTarget ? { revisionTarget } : {}),
+    ...(sameKey ? { precomputedMatches: sameKey.matches } : {}),
   });
 
+  // T-Mem triggers：conflict 时宿主没变、不写；其余见 writeTriggersForEntry。
+  const triggersWritten = disposition === "conflict"
+    ? 0
+    : await writeTriggersForEntry(deps, entry, resolvedScope, normalizeTriggerTexts(input.triggers), disposition === "deduped");
+
   // Tier 4.1: Async KG triple extraction (non-blocking)
   // HP-ethics: Skip KG extraction for ephemeral/private memories — they must not leave graph traces
   const entryPrivacyTier = parsePrivacyTier(metadata);
   const kgAllowed = entryPrivacyTier !== "ephemeral" && entryPrivacyTier !== "private";
   if (deps.kgExtractor && disposition !== "deduped" && kgAllowed) {
-    deps.kgExtractor
-      .extractAndStore(input.text, entry.id, resolvedScope)
-      .catch(() => {}); // Silently ignore — KG extraction must never block memory writes
+    const kgExtractor = deps.kgExtractor;
+    // When this write replaced existing content, the edges extracted from the OLD
+    // text are still in the graph: triple ids are content-derived, so re-extracting
+    // merely adds new rows beside the stale ones and both compete during traversal.
+    // Purge first, then re-extract — strictly ordered, or the purge would race ahead
+    // and delete what we just wrote.
+    const purged = supersededPrevious
+      ? kgExtractor.purgeForMemory(entry.id)
+      : Promise.resolve();
+    purged
+      .then(() => kgExtractor.extractAndStore(input.text, entry.id, resolvedScope))
+      .catch(() => {}); // Silently ignore — KG upkeep must never block memory writes
   }
 
   // F-1: Audit log — record store operation (non-blocking, silent on failure)
@@ -1159,22 +1533,32 @@ export async function persistMemory(
       .catch(() => {}); // Must never block
   }
 
-  // LME-1: Implicit preference dual-write — when a non-preference memory
-  // contains an implicit usage signal ("I use X", "I have X", etc.),
+  // LME-1: Implicit preference dual-write — when a short non-preference memory
+  // is itself an implicit usage statement ("I use X", "I have X", etc.),
   // store an additional preferences copy so it can be recalled via the
   // low-threshold preference retrieval path (hardMinScore 0.25 vs 0.35).
+  // Only short texts qualify: a long narrative that happens to contain one
+  // "我用 X 做了…" clause is not a usage statement, and copying it whole into
+  // preferences only duplicates the source row (see shouldDeriveImplicitPreference).
   // Async & non-blocking: the primary write is already done.
+  // Not on "conflict" either: the incoming text was parked in the conflict
+  // store, nothing was written, and `entry` is the existing row it collided with.
   if (
     disposition !== "deduped" &&
-    input.category !== "preferences" &&
-    inferImplicitUsageSlot(input.text)
+    disposition !== "conflict" &&
+    shouldDeriveImplicitPreference(input.category, input.text)
   ) {
     const prefCanonicalKey = buildDefaultCanonicalKey({ category: "preferences", text: input.text });
     const prefSlot = inferImplicitUsageSlot(input.text);
     const prefMetadata = buildStructuredMetadata({
       source: input.source,
-      tags: [...(input.tags ?? []), "derived-preference", `derived-from:${entry.id}`],
-      capture: "implicit_preference_dual_write_v1",
+      // The source row's own tags stay on the source row. `pinned` would exempt
+      // the copy from decay and business tags would make it count as a second
+      // record of whatever the source row records.
+      tags: ["derived-preference", `derived-from:${entry.id}`],
+      // v2 (2026-10-10): length cap, no inherited tags. v1 rows copied any length
+      // and carried every tag of the source row.
+      capture: "implicit_preference_dual_write_v2",
       category: "preferences",
       canonicalKey: prefCanonicalKey,
       extra: prefSlot ? { preferenceSlot: prefSlot } : undefined,
@@ -1194,17 +1578,18 @@ export async function persistMemory(
     }).catch(() => {}); // Dual-write must never block the primary write
   }
 
-  return toStoredRecord(input, entry, disposition, canonicalKey, conflictId);
+  return { ...toStoredRecord(input, entry, disposition, canonicalKey, conflictId), triggersWritten };
 }
 
 export async function persistWorkflowPattern(
   deps: PersistMemoryDeps,
   rawInput: unknown,
 ): Promise<StoredWorkflowPatternRecord> {
-  const input = WorkflowPatternInputSchema.parse(rawInput);
+  // F-3b: scrub every field before embedding/storage — the structured fields land in
+  // metadata verbatim (this path bypasses persistMemory)
+  const input = redactWorkflowPatternInput(WorkflowPatternInputSchema.parse(rawInput));
   const resolvedScope = resolveScope(input);
   const tags = mergeTags(input.tags, ["workflow", "pattern"]);
-  // F-3b: scrub before embedding/storage (this path bypasses persistMemory)
   const text = redactSecrets(buildWorkflowPatternText(input)).text;
   const vector = await deps.embedder.embedPassage(text);
   const language = detectLang(text);
@@ -1246,10 +1631,11 @@ export async function persistCaseMemory(
   deps: PersistMemoryDeps,
   rawInput: unknown,
 ): Promise<StoredCaseMemoryRecord> {
-  const input = CaseMemoryInputSchema.parse(rawInput);
+  // F-3b: scrub every field before embedding/storage — the structured fields land in
+  // metadata verbatim (this path bypasses persistMemory)
+  const input = redactCaseMemoryInput(CaseMemoryInputSchema.parse(rawInput));
   const resolvedScope = resolveScope(input);
   const tags = mergeTags(input.tags, ["case", "solution"]);
-  // F-3b: scrub before embedding/storage (this path bypasses persistMemory)
   const text = redactSecrets(buildCaseMemoryText(input)).text;
   const vector = await deps.embedder.embedPassage(text);
   const language = detectLang(text);
@@ -1291,7 +1677,9 @@ export async function promoteMemory(
   deps: PersistMemoryDeps,
   rawInput: unknown,
 ): Promise<StoredPromotedMemoryRecord> {
-  const input = PromoteMemoryInputSchema.parse(rawInput);
+  const parsedInput = PromoteMemoryInputSchema.parse(rawInput);
+  // F-3b: tags and an explicit canonicalKey go into metadata as given
+  const input = withoutSecretCanonicalKey({ ...parsedInput, tags: redactList(parsedInput.tags) });
   const sourceEntry = deps.store.get
     ? await deps.store.get(input.memoryId)
     : deps.store.getById
@@ -1359,7 +1747,7 @@ export async function promoteMemory(
 export async function persistMemoryBatch(
   deps: PersistMemoryDeps,
   rawInput: unknown,
-): Promise<StoredMemoryRecord[]> {
+): Promise<PersistedMemoryRecord[]> {
   const input = CaptureMemoryInputSchema.parse(rawInput);
   const normalizedItems = input.memories.map((memory) =>
     StoreMemoryInputSchema.parse({
@@ -1378,7 +1766,7 @@ export async function persistMemoryBatch(
   // persistMemoryBatch (typically <10 items), per-item conflict detection (A-2)
   // in persistMemory handles dedup adequately without double-embedding cost.
 
-  const persisted: StoredMemoryRecord[] = [];
+  const persisted: PersistedMemoryRecord[] = [];
   for (const memory of normalizedItems) {
     persisted.push(await persistMemory(deps, memory));
   }