@remnic/core 9.50.3 → 9.51.1

package/src/storage-contract/cache-coherence.test.ts

@@ -534,3 +534,302 @@ test("tier move: cold-to-hot move invalidates cold cache and cannot remain in re
     await rm(dir, { recursive: true, force: true });
   }
 });
+
+test("archive mutation version ignores hot and cold writes", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-archive-version-"));
+  try {
+    resetStaticCaches();
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+    const initial = storage.getArchiveMutationVersion();
+
+    const { id } = await storage.writeMemory("fact", "archive version probe");
+    assert.equal(storage.getArchiveMutationVersion(), initial);
+
+    const coldInvalidator = storage as unknown as {
+      invalidateColdMemoriesCache: () => void;
+    };
+    coldInvalidator.invalidateColdMemoriesCache();
+    assert.equal(storage.getArchiveMutationVersion(), initial);
+
+    const memory = await storage.getMemoryById(id);
+    assert.ok(memory);
+    assert.ok(await storage.archiveMemory(memory));
+    assert.ok(storage.getArchiveMutationVersion() > initial);
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+test("archive version advances when a tier move commits archive write before source delete fails", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-archive-partial-move-"));
+  try {
+    resetStaticCaches();
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+    const { id } = await storage.writeMemory("fact", "archive move partial");
+    const memory = await storage.getMemoryById(id);
+    assert.ok(memory);
+    const targetPath = path.join(dir, "archive", "partial", path.basename(memory.path));
+    const initial = storage.getArchiveMutationVersion();
+    const internals = storage as unknown as {
+      deleteManagedStorageFile: (filePath: string) => Promise<boolean>;
+    };
+    const originalDelete = internals.deleteManagedStorageFile.bind(storage);
+    internals.deleteManagedStorageFile = async (filePath) => {
+      if (path.resolve(filePath) === path.resolve(memory.path)) {
+        throw new Error("forced archive source delete failure");
+      }
+      return originalDelete(filePath);
+    };
+    await assert.rejects(storage.moveMemoryToPath(memory, targetPath), /forced archive source delete failure/);
+    assert.ok(storage.getArchiveMutationVersion() > initial);
+    assert.ok((await readFile(targetPath, "utf8")).includes("archive move partial"));
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("archive version advances when archive write commits before source delete fails", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-archive-partial-archive-"));
+  try {
+    resetStaticCaches();
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+    const { id } = await storage.writeMemory("fact", "archive write partial");
+    const memory = await storage.getMemoryById(id);
+    assert.ok(memory);
+    const initial = storage.getArchiveMutationVersion();
+    const internals = storage as unknown as {
+      deleteManagedStorageFile: (filePath: string) => Promise<boolean>;
+    };
+    const originalDelete = internals.deleteManagedStorageFile.bind(storage);
+    internals.deleteManagedStorageFile = async (filePath) => {
+      if (path.resolve(filePath) === path.resolve(memory.path)) {
+        throw new Error("forced archive source delete failure");
+      }
+      return originalDelete(filePath);
+    };
+    const result = await storage.archiveMemory(memory, { at: new Date("2026-01-02T00:00:00.000Z") });
+    assert.equal(result, null);
+    assert.ok(storage.getArchiveMutationVersion() > initial);
+    assert.ok((await readFile(path.join(dir, "archive", "2026-01-02", path.basename(memory.path)), "utf8")).includes("archive write partial"));
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("archive version advances when invalidateMemory deletes an archive path", async () => {
+
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-archive-invalidate-"));
+  try {
+    resetStaticCaches();
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+    const { id } = await storage.writeMemory("fact", "archive invalidation");
+    const memory = await storage.getMemoryById(id);
+    assert.ok(memory);
+    const archivedPath = await storage.archiveMemory(memory, { at: new Date("2026-01-03T00:00:00.000Z") });
+    assert.ok(archivedPath);
+    const archived = (await storage.readArchivedMemories()).find((candidate) => candidate.frontmatter.id === id);
+    assert.ok(archived);
+    const internals = storage as unknown as {
+      readAllMemories: () => Promise<unknown[]>;
+    };
+    internals.readAllMemories = async () => [archived];
+    const initial = storage.getArchiveMutationVersion();
+    assert.equal(await storage.invalidateMemory(id), true);
+    assert.ok(storage.getArchiveMutationVersion() > initial);
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+test("invalidateMemory returns false without side effects when the target is already absent", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-invalidate-absent-"));
+  try {
+    resetStaticCaches();
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+    const { id } = await storage.writeMemory("fact", "already absent");
+    const memory = await storage.getMemoryById(id);
+    assert.ok(memory);
+    const initialStatus = storage.getMemoryStatusVersion();
+    await rm(memory.path);
+    assert.equal(await storage.invalidateMemory(id), false);
+    assert.equal(storage.getMemoryStatusVersion(), initialStatus);
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("archive generation advances once per archive file mutation", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-archive-version-delta-"));
+  try {
+    resetStaticCaches();
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+    const { id } = await storage.writeMemory("fact", "archive generation deltas");
+    const memory = await storage.getMemoryById(id);
+    assert.ok(memory);
+    const initial = storage.getArchiveMutationVersion();
+
+    const firstArchivePath = path.join(dir, "archive", "2026-01-06", path.basename(memory.path));
+    assert.equal(await storage.moveMemoryToPath(memory, firstArchivePath), true);
+    const afterHotToArchive = storage.getArchiveMutationVersion();
+    assert.equal(afterHotToArchive - initial, 1);
+
+    const archived = (await storage.readArchivedMemories()).find((candidate) => candidate.frontmatter.id === id);
+    assert.ok(archived);
+    const secondArchivePath = path.join(dir, "archive", "2026-01-07", path.basename(archived.path));
+    assert.equal(await storage.moveMemoryToPath(archived, secondArchivePath), true);
+    const afterArchiveToArchive = storage.getArchiveMutationVersion();
+    assert.equal(afterArchiveToArchive - afterHotToArchive, 2);
+
+    const movedArchive = (await storage.readArchivedMemories()).find((candidate) => candidate.frontmatter.id === id);
+    assert.ok(movedArchive);
+    assert.equal(await storage.moveMemoryToPath(movedArchive, storage.buildTierMemoryPath(movedArchive, "hot")), true);
+    assert.equal(storage.getArchiveMutationVersion() - afterArchiveToArchive, 1);
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("maintenance deletion keeps a non-matching archive memory", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-archive-maintenance-guard-"));
+  try {
+    resetStaticCaches();
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+    const { id } = await storage.writeMemory("fact", "archive maintenance guard");
+    const memory = await storage.getMemoryById(id);
+    assert.ok(memory);
+    assert.ok(await storage.archiveMemory(memory, { at: new Date("2026-01-05T00:00:00.000Z") }));
+    const archived = (await storage.readArchivedMemories()).find((candidate) => candidate.frontmatter.id === id);
+    assert.ok(archived);
+    const initial = storage.getArchiveMutationVersion();
+    assert.equal(await storage.deleteMemoryForMaintenance(archived, () => false), null);
+    assert.equal(storage.getArchiveMutationVersion(), initial);
+    assert.ok((await readFile(archived.path, "utf8")).includes("archive maintenance guard"));
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("archive version advances when maintenance deletes an archive path", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-archive-maintenance-delete-"));
+  try {
+    resetStaticCaches();
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+    const { id } = await storage.writeMemory("fact", "archive maintenance delete");
+    const memory = await storage.getMemoryById(id);
+    assert.ok(memory);
+    assert.ok(await storage.archiveMemory(memory, { at: new Date("2026-01-04T00:00:00.000Z") }));
+    const archived = (await storage.readArchivedMemories()).find((candidate) => candidate.frontmatter.id === id);
+    assert.ok(archived);
+    const initial = storage.getArchiveMutationVersion();
+    const removed = await storage.deleteMemoryForMaintenance(archived);
+    assert.ok(removed);
+    assert.equal(removed.frontmatter.id, id);
+    assert.ok(storage.getArchiveMutationVersion() > initial);
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("archive mutation version advances once for an offline archive write", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-offline-archive-write-"));
+  try {
+    resetStaticCaches();
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+    const archivePath = path.join(dir, "archive", "2026-01-08", "offline-write.md");
+    const content = [
+      "---",
+      "id: offline-archive-write",
+      "category: fact",
+      "---",
+      "offline archive write",
+    ].join("\n");
+    const initial = storage.getArchiveMutationVersion();
+
+    await storage.writeOfflineSyncFile(archivePath, Buffer.from(content));
+
+    assert.equal(storage.getArchiveMutationVersion() - initial, 1);
+
+    const hotPath = path.join(dir, "facts", "offline-hot-write.md");
+    const beforeHot = storage.getArchiveMutationVersion();
+    await storage.writeOfflineSyncFile(
+      hotPath,
+      Buffer.from(["---", "id: offline-hot-write", "category: fact", "---", "offline hot write"].join("\n")),
+    );
+    assert.equal(storage.getArchiveMutationVersion() - beforeHot, 0);
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("archive mutation version advances once for an offline chunked archive write", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-offline-archive-chunks-"));
+  try {
+    resetStaticCaches();
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+    const archivePath = path.join(dir, "archive", "2026-01-09", "offline-chunks.md");
+    const content = Buffer.from(
+      ["---", "id: offline-archive-chunks", "category: fact", "---", "offline chunked archive write"].join("\n"),
+    );
+    const initial = storage.getArchiveMutationVersion();
+
+    await storage.writeOfflineSyncFileChunks(
+      archivePath,
+      (async function* () {
+        yield content.subarray(0, 17);
+        yield content.subarray(17);
+      })(),
+    );
+
+    assert.equal(storage.getArchiveMutationVersion() - initial, 1);
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("archive mutation version advances once for an offline archive delete", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-offline-archive-delete-"));
+  try {
+    resetStaticCaches();
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+    const archivePath = path.join(dir, "archive", "2026-01-10", "offline-delete.md");
+    const content = [
+      "---",
+      "id: offline-archive-delete",
+      "category: fact",
+      "---",
+      "offline archive delete",
+    ].join("\n");
+    await storage.writeOfflineSyncFile(archivePath, Buffer.from(content));
+    const initial = storage.getArchiveMutationVersion();
+
+    await storage.deleteOfflineSyncFile(archivePath);
+
+    assert.equal(storage.getArchiveMutationVersion() - initial, 1);
+    const statusBeforeRetry = storage.getMemoryStatusVersion();
+    await storage.deleteOfflineSyncFile(archivePath);
+    assert.equal(storage.getArchiveMutationVersion() - initial, 1);
+    assert.ok(storage.getMemoryStatusVersion() > statusBeforeRetry);
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/src/storage.ts

@@ -79,6 +79,7 @@ import {
   deleteInFlightReadsForDir,
   clearInFlightReads,
 } from "./in-flight-reads.js";
+import * as archive from "./archive-mutation-version.js";
 import { rotateMarkdownFileToArchive } from "./hygiene.js";
 import { sanitizeMemoryContent } from "./sanitize.js";
 import { withholdToolScopedFromSharedNamespace } from "./tool-scoped-memory.js";
@@ -125,7 +126,6 @@ import {
 import {
   TombstoneStore,
   collectRetiredMemoriesForRebuild,
-  buildRetiredFactTombstoneInputs,
   type TombstoneStoreOptions,
   type TombstoneFileIo,
   type TombstoneReason,
@@ -133,6 +133,7 @@ import {
   type TombstoneStats,
 } from "./lifecycle/tombstones.js";
 import { supersessionKeysForFact } from "./temporal-supersession.js";
+import { runSupersessionSideEffects } from "./storage/supersession-side-effects.js";
 import type {
   AccessTrackingEntry,
   BufferState,
@@ -2401,15 +2402,18 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     return this.readSharedVersion("memory-corpus", StorageManager.memoryCorpusVersionByDir);
   }
 
+  /**
+   * Bump only — NOT invalidateAllForDir (that would drop the very hot
+   * entry the write path just patched).
+   */
   protected bumpMemoryCorpusVersion(): void {
-    // Bump only — NOT invalidateAllForDir (that would drop the very hot
-    // entry the write path just patched).
     this.bumpSharedVersion("memory-corpus", StorageManager.memoryCorpusVersionByDir);
     // Drop the in-flight readAllMemories slot (#1902): a concurrent read
     // must not attach to a scan that began BEFORE this mutation. (The patch
     // path uses bumpMemoryCorpusVersionExclusive and clears the slot itself.)
     deleteInFlightReadsForDir(this.baseDir);
   }
+  getArchiveMutationVersion(): number { return archive.getArchiveMutationVersionForDir(this.baseDir); }
 
   /**
    * Corpus bump reporting whether THIS process's append was the only one
@@ -4569,16 +4573,19 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
   invalidateMemoryCachesForTiers(tiers: Iterable<"hot" | "cold" | "archive">): void {
     let hotChanged = false;
     let coldChanged = false;
+    let archiveChanged = false;
     for (const tier of tiers) {
       if (tier === "cold") {
         coldChanged = true;
-      } else if (tier === "hot" || tier === "archive") {
+      } else if (tier === "archive") {
+        hotChanged = true;
+        archiveChanged = true;
+      } else if (tier === "hot") {
         hotChanged = true;
       }
     }
-    if (hotChanged) {
-      this.invalidateAllMemoriesCache();
-    }
+    if (hotChanged) this.invalidateAllMemoriesCache();
+    archive.bumpArchiveMutationIfChanged(this.baseDir, archiveChanged);
     if (coldChanged) {
       this.invalidateColdMemoriesCache();
     }
@@ -5140,6 +5147,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     this.notifyCatalogWrite();
   }
   async moveMemoryToPath(memory: MemoryFile, targetPath: string): Promise<boolean> {
+    const { recordArchiveDelete, recordArchiveWrite } = archive;
     const changed = await this.withTombstoneBlockedMemoryPathLock(
       memory.path,
       async (current) => {
@@ -5168,12 +5176,12 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
         let durable = false;
         try {
           if (destination?.frontmatter.id === current.frontmatter.id) {
-            await this.deleteManagedStorageFile(current.path);
+            await recordArchiveDelete(this.baseDir, current.path, () => this.deleteManagedStorageFile(current.path));
             durable = true;
             this.invalidateAllMemoriesCache();
             updateProjectedMemoryPath(this.baseDir, current.frontmatter.id, projectedPath);
           } else {
-            await this.writeMemoryFileAtomic(targetPath, current);
+            await recordArchiveWrite(this.baseDir, targetPath, () => this.writeMemoryFileAtomic(targetPath, current));
             if (memory.frontmatter.entityRef !== current.frontmatter.entityRef) {
               memory.frontmatter.entityRef = current.frontmatter.entityRef;
             }
@@ -5181,7 +5189,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
             const sourcePath = path.resolve(current.path);
             const destPath = path.resolve(targetPath);
             if (sourcePath !== destPath) {
-              await this.deleteManagedStorageFile(current.path);
+              await recordArchiveDelete(this.baseDir, current.path, () => this.deleteManagedStorageFile(current.path));
               this.invalidateAllMemoriesCache();
               updateProjectedMemoryPath(this.baseDir, current.frontmatter.id, projectedPath);
             }
@@ -5228,6 +5236,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
    * Returns the new file path on success, null on failure.
    */
   async archiveMemory(memory: MemoryFile, lifecycle?: MemoryLifecycleEventWriteOptions): Promise<string | null> {
+    const { recordArchiveDelete, recordArchiveWrite } = archive;
     const archiveCurrent = async (current: MemoryFile, markDurable: () => void): Promise<string | null> => {
       try {
         const now = lifecycle?.at ?? new Date();
@@ -5250,7 +5259,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
         // Snapshot a pre-existing destination (retried archive) so a repair
         // failure restores it instead of deleting the only archived copy (§14).
         const priorDest = await this.readStorageSecureFile(destPath).catch(() => null);
-        await this.writeStorageSecureFile(destPath, fileContent);
+        await recordArchiveWrite(this.baseDir, destPath, () => this.writeStorageSecureFile(destPath, fileContent));
         if (typeof current.frontmatter.entityRef === "string") {
           try {
             await this.entityRefRepair.repair(
@@ -5261,17 +5270,27 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
               current.content
             );
           } catch (err) {
-            // Restore/remove the destination before reporting failure (§14):
-            // a retained fresh copy would surface the memory in BOTH scans.
             if (priorDest === null) {
-              await unlink(destPath).catch(() => undefined);
+              await recordArchiveDelete(this.baseDir, destPath, () =>
+                unlink(destPath).then(
+                  () => true,
+                  () => false
+                )
+              );
             } else {
-              await this.writeStorageSecureFile(destPath, priorDest).catch(() => undefined);
+              await recordArchiveDelete(this.baseDir, destPath, () =>
+                this.writeStorageSecureFile(destPath, priorDest).then(
+                  () => true,
+                  () => false
+                )
+              );
             }
             throw err;
           }
         }
-        if (!(await this.deleteManagedStorageFile(current.path))) return null;
+        const deleted = await recordArchiveDelete(this.baseDir, current.path, () =>
+          this.deleteManagedStorageFile(current.path));
+        if (!deleted) return null;
         markDurable();
         markProjectedMemoryPathInvalid(this.baseDir, current.frontmatter.id);
         this.invalidateAllMemoriesCache();
@@ -5370,7 +5389,9 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     if (!memory) return false;
 
     return await this.runTombstoneBlockedInvalidation(memory, async (current, rebuildMarker, markDurable) => {
-      if (!(await this.deleteManagedStorageFile(current.path))) return false;
+      const deleted = await archive.recordArchiveDelete(this.baseDir, current.path, () =>
+        this.deleteManagedStorageFile(current.path));
+      if (!deleted) return false;
       markDurable();
       markProjectedMemoryPathInvalid(this.baseDir, id);
       this.invalidateAllMemoriesCache();
@@ -6987,26 +7008,34 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
       .sort((a, b) => (a.frontmatter.chunkIndex ?? 0) - (b.frontmatter.chunkIndex ?? 0));
   }
 
-  // ---------------------------------------------------------------------------
-  // Contradiction Detection (Phase 2B)
-  // ---------------------------------------------------------------------------
-
-  /**
-   * Mark a memory as superseded by another.
-   * Updates the old memory's status and adds the supersededBy link.
-   */
   async supersedeMemory(oldMemoryId: string, newMemoryId: string, reason: string): Promise<boolean> {
     const memories = await this.readAllMemories();
-    const oldMemory = memories.find((m) => m.frontmatter.id === oldMemoryId);
+    let oldMemory = memories.find(
+      (memory) =>
+        memory.frontmatter.id === oldMemoryId &&
+        inferMemoryStatus(memory.frontmatter, toMemoryPathRel(this.baseDir, memory.path)) === "active",
+    );
+    if (!oldMemory) {
+      oldMemory = (await this.readAllColdMemories()).find(
+        (memory) =>
+          memory.frontmatter.id === oldMemoryId &&
+          inferMemoryStatus(memory.frontmatter, toMemoryPathRel(this.baseDir, memory.path)) === "active",
+      );
+    }
     if (!oldMemory) return false;
 
     const now = new Date().toISOString();
     let currentBefore = oldMemory;
     let updatedFm = oldMemory.frontmatter;
 
-    try {
-      const written = await this.withTombstoneBlockedMemoryPathLock(oldMemory.path, async (current) => {
+    const written = await this.withTombstoneBlockedMemoryPathLock(oldMemory.path, async (current) => {
         if (current?.frontmatter.id !== oldMemoryId) return false;
+        if (
+          current.frontmatter.supersededBy !== undefined ||
+          inferMemoryStatus(current.frontmatter, toMemoryPathRel(this.baseDir, current.path)) !== "active"
+        ) {
+          return false;
+        }
         currentBefore = current;
         const refIdsAtWrite = this.currentHistoricalIds();
         updatedFm = entityRefs.canonicalizeEntityRefOption(
@@ -7026,67 +7055,36 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
           );
         }
         return true;
-      });
-      if (!written) return false;
-      // Advance the corpus sentinel immediately after the on-disk write, BEFORE
-      // the awaited lifecycle append (Cursor Medium, #1902). Otherwise a warm
-      // hot-memories cache keeps serving the pre-supersede snapshot during the
-      // await window; bumpMemoryStatusVersion() below additionally invalidates
-      // the entity cache for the status change.
-      this.bumpMemoryCorpusVersion();
-      await this.appendGeneratedMemoryLifecycleEventFailOpen("storage.supersedeMemory", {
-        memoryId: oldMemoryId,
-        eventType: "superseded",
-        timestamp: now,
-        actor: "storage.supersedeMemory",
-        reasonCode: reason,
-        before: this.summarizeLifecycleState(currentBefore.frontmatter, currentBefore.path),
-        after: this.summarizeLifecycleState(updatedFm, currentBefore.path),
-        relatedMemoryIds: [newMemoryId],
-      });
-      this.bumpMemoryStatusVersion();
-      log.debug(`superseded memory ${oldMemoryId} by ${newMemoryId}: ${reason}`);
-
-      // #1579 — every contradiction verb (keep-a/keep-b/merge) funnels here,
-      // so emitting covers each exactly once (rule 22); facts only. One
-      // tombstone PER derived supersession key (thread Oci-Y) so a
-      // paraphrased re-write is caught on the keyed tier.
-      if (currentBefore.frontmatter.category === "fact") {
-        for (const input of buildRetiredFactTombstoneInputs(
-          {
-            id: oldMemoryId,
-            content: stripCitationForTemplate(currentBefore.content, this.citationTemplate),
-            contentHash: currentBefore.frontmatter.contentHash,
-            entityRef: updatedFm.entityRef,
-            structuredAttributes: currentBefore.frontmatter.structuredAttributes,
-          },
-          {
-            reason: "contradiction_resolution",
-            createdBy: "contradiction_resolution",
-            createdAt: now,
-            supersessionKeysForFact,
-          }
-        )) {
-          await this.appendTombstone(input);
-        }
-      }
-
-      // Audit-trail correction — sealed even INSIDE the engine (#2022 review).
-      const auditBody = `Superseded: ${currentBefore.content}\n\nReason: ${reason}`;
-      const auditInput = {
-        content: auditBody,
-        category: "correction" as const,
-        confidence: 1.0,
-        tags: ["supersession", "auto-resolved"],
-      };
-      const auditEnvelope = composeMemoryEnvelope(auditInput, { source: "contradiction-detection" });
-      await this.writeSealedMemory(auditEnvelope, { lineage: [oldMemoryId, newMemoryId] });
+      }).catch((err) => { log.error(`failed to supersede memory ${oldMemoryId}:`, err); return false; });
+    if (!written) return false;
+    await runSupersessionSideEffects({
+      oldMemoryId,
+      newMemoryId,
+      reason,
+      now,
+      currentBefore,
+      updatedFm,
+      citationTemplate: this.citationTemplate,
+      isColdOrArchiveTierPath: (memoryPath) => this.isColdOrArchiveTierPath(memoryPath),
+      invalidateColdMemoriesCache: () => this.invalidateColdMemoriesCache(),
+      bumpMemoryCorpusVersion: () => this.bumpMemoryCorpusVersion(),
+      appendLifecycleEvent: () =>
+        this.appendGeneratedMemoryLifecycleEventFailOpen("storage.supersedeMemory", {
+          memoryId: oldMemoryId,
+          eventType: "superseded",
+          timestamp: now,
+          actor: "storage.supersedeMemory",
+          reasonCode: reason,
+          before: this.summarizeLifecycleState(currentBefore.frontmatter, currentBefore.path),
+          after: this.summarizeLifecycleState(updatedFm, currentBefore.path),
+          relatedMemoryIds: [newMemoryId],
+        }),
+      bumpMemoryStatusVersion: () => this.bumpMemoryStatusVersion(),
+      appendTombstone: (input) => this.appendTombstone(input),
+      writeSealedMemory: (envelope, extras) => this.writeSealedMemory(envelope, extras),
+    });
 
-      return true;
-    } catch (err) {
-      log.error(`failed to supersede memory ${oldMemoryId}:`, err);
-      return false;
-    }
+    return true;
   }
 
   // ---------------------------------------------------------------------------

package/src/types.ts

@@ -5,6 +5,10 @@ import type { WearablesConfig } from "./wearables/types.js";
 import type { ExtractionLivenessConfig } from "./extraction-liveness.js";
 import type { ReplicaPeersConfig } from "./replica-peers-config.js";
 import type { ExternalWikiRoot } from "./external-wiki-config.js";
+import type { ContradictionLocalizationConfig, ContradictionScanConfig } from "./contradiction-config.js";
+import type { GraphPathScoringConfig } from "./graph-path-scoring-config.js";
+export type { ContradictionLocalizationConfig, ContradictionScanConfig } from "./contradiction-config.js";
+export type { GraphPathScoringConfig } from "./graph-path-scoring-config.js";
 
 import type { AmbientCaptureProvenance, BufferTurnOwner } from "./buffer-turn-helpers.js";
 export type ReasoningEffort = "none" | "low" | "medium" | "high";
@@ -609,21 +613,6 @@ export interface ScopeTeamConfig {
   promote: string[];
 }
 
-/** Configuration for the nightly contradiction-scan cron (issue #520). */
-export interface ContradictionScanConfig {
-  /** Master switch for the contradiction scan cron. Default true. */
-  enabled: boolean;
-  /** Embedding cosine similarity floor for candidate pair generation. Default 0.82. */
-  similarityFloor: number;
-  /** Minimum topic-token Jaccard overlap for unstructured pairs. Default 0.4. */
-  topicOverlapFloor: number;
-  /** Cap on candidate pairs evaluated per cron run. Default 500. */
-  maxPairsPerRun: number;
-  /** Cooldown in days before re-evaluating a pair judged independent/both-valid. Default 14. */
-  cooldownDays: number;
-  /** When true, pairs judged "duplicates" are auto-flagged for dedup (still need user approval). Default false. */
-  autoMergeDuplicates: boolean;
-}
 export interface DependencyPropagationConfig {
   /** Master switch. Default false. */
   enabled: boolean;
@@ -684,6 +673,7 @@ export interface SemanticChunkingConfigShape {
   fallbackToRecursive: boolean;
 }
 
+
 export interface PluginConfig extends BoundedJsonlStateConfig {
   openaiApiKey: string | undefined;
   openaiBaseUrl: string | undefined;
@@ -860,6 +850,8 @@ export interface PluginConfig extends BoundedJsonlStateConfig {
   contradictionAutoResolve: boolean;
   /** Nightly contradiction-scan cron config (issue #520). */
   contradictionScan: ContradictionScanConfig;
+  /** Anchor-first contradiction candidate localization settings (issue #2327). */
+  contradictionLocalization: ContradictionLocalizationConfig;
   /** One-hop dependency invalidation propagation settings (issue #2326). */
   dependencyPropagation: DependencyPropagationConfig;
   // Temporal Supersession (issue #375)
@@ -2101,6 +2093,7 @@ export interface PluginConfig extends BoundedJsonlStateConfig {
   causalGraphEnabled: boolean;
   maxGraphTraversalSteps: number;
   graphActivationDecay: number;
+  graphPathScoring: GraphPathScoringConfig;
   /** Weight of graph activation score when blending with seed QMD score (0-1). */
   graphExpansionActivationWeight: number;
   /** Lower bound for blended graph-expanded recall scores (0-1). */
@@ -3476,6 +3469,10 @@ export interface QmdSearchResult {
   transport?: "daemon" | "subprocess" | "hybrid" | "scoped_prefilter";
   /** Namespace that owned this result when returned by a namespace fanout search. */
   namespace?: string;
+  /** Graph activation path evidence from opt-in path scoring. */
+  pathNodeIds?: string[];
+  /** True when a graph path penalty was applied. */
+  pathPenaltyApplied?: boolean;
   sourceConnector?: string;
 }