@remnic/core 9.49.0 → 9.50.0

package/src/json-store.ts

@@ -1,19 +1,53 @@
+import { randomUUID } from "node:crypto";
+import type { Dirent } from "node:fs";
+import {
+  lstat,
+  mkdir,
+  open,
+  readFile,
+  readdir,
+  rename,
+  unlink,
+  utimes,
+  writeFile,
+  type FileHandle,
+} from "node:fs/promises";
 import path from "node:path";
-import { readFile, readdir } from "node:fs/promises";
 
-export async function listJsonFiles(dir: string): Promise<string[]> {
+function hasErrorCode(error: unknown, code: string): boolean {
+  return typeof error === "object" && error !== null && "code" in error && (error as { code?: unknown }).code === code;
+}
+
+async function listJsonFilesStrictInner(dir: string, allowMissingDirectory: boolean): Promise<string[]> {
+  let entries: Dirent[];
   try {
-    const entries = await readdir(dir, { withFileTypes: true });
-    const out: string[] = [];
-    for (const entry of entries) {
-      const fullPath = path.join(dir, entry.name);
-      if (entry.isDirectory()) {
-        out.push(...(await listJsonFiles(fullPath)));
-      } else if (entry.isFile() && entry.name.endsWith(".json")) {
-        out.push(fullPath);
-      }
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch (error) {
+    if (allowMissingDirectory && hasErrorCode(error, "ENOENT")) return [];
+    throw error;
+  }
+  const out: string[] = [];
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...(await listJsonFilesStrictInner(fullPath, false)));
+    } else if (entry.isFile() && entry.name.endsWith(".json")) {
+      out.push(fullPath);
     }
-    return out.sort();
+  }
+  return out.sort();
+}
+
+export async function listJsonFilesStrict(
+  dir: string,
+  options: { allowMissingDirectory?: boolean } = {}
+): Promise<string[]> {
+  return listJsonFilesStrictInner(dir, options.allowMissingDirectory === true);
+}
+
+export async function listJsonFiles(dir: string): Promise<string[]> {
+  try {
+    return await listJsonFilesStrict(dir);
   } catch {
     return [];
   }
@@ -37,6 +71,314 @@ export async function listNamedFiles(dir: string, fileName: string): Promise<str
   }
 }
 
+const jsonStoreMutationTails = new Map<string, Promise<void>>();
+
+const JSON_STORE_LOCK_RETRY_MS = 25;
+const JSON_STORE_LOCK_STALE_MS = 60_000;
+const JSON_STORE_LOCK_TIMEOUT_MS = 10_000;
+
+type JsonStoreMutationLockTestHooks = {
+  beforeLockOwnerWrite?: (lockPath: string, ownerToken: string) => Promise<void> | void;
+  beforeLockOwnershipConfirm?: (lockPath: string, ownerToken: string) => Promise<void> | void;
+  afterReclaimGuardWrite?: (reclaimPath: string, ownerToken: string) => Promise<void> | void;
+  retryMs?: number;
+  staleLockMs?: number;
+  timeoutMs?: number;
+};
+
+let jsonStoreMutationLockTestHooks: JsonStoreMutationLockTestHooks | null = null;
+
+export function setJsonStoreMutationLockTestHooks(hooks: JsonStoreMutationLockTestHooks | null): void {
+  jsonStoreMutationLockTestHooks = hooks;
+}
+
+function jsonStoreLockRetryMs(): number {
+  return jsonStoreMutationLockTestHooks?.retryMs ?? JSON_STORE_LOCK_RETRY_MS;
+}
+
+function jsonStoreLockStaleMs(): number {
+  return jsonStoreMutationLockTestHooks?.staleLockMs ?? JSON_STORE_LOCK_STALE_MS;
+}
+
+function jsonStoreLockTimeoutMs(): number {
+  return jsonStoreMutationLockTestHooks?.timeoutMs ?? JSON_STORE_LOCK_TIMEOUT_MS;
+}
+
+async function closeAndRemoveJsonStoreReclaimGuard(reclaimPath: string, reclaimHandle: FileHandle): Promise<void> {
+  await reclaimHandle.close().catch(() => undefined);
+  await unlink(reclaimPath).catch((error) => {
+    if (!hasErrorCode(error, "ENOENT")) throw error;
+  });
+}
+
+async function removeStaleJsonStoreReclaimGuard(reclaimPath: string): Promise<void> {
+  let initial: JsonStoreLockState;
+  try {
+    initial = await readJsonStoreLockState(reclaimPath);
+  } catch (error) {
+    if (hasErrorCode(error, "ENOENT")) return;
+    throw error;
+  }
+  if (Date.now() - initial.mtimeMs <= jsonStoreLockStaleMs()) return;
+
+  let ownerPid: number | undefined;
+  try {
+    const metadata = JSON.parse(initial.content) as { pid?: unknown };
+    ownerPid = typeof metadata.pid === "number" && Number.isInteger(metadata.pid) ? metadata.pid : undefined;
+  } catch {
+    ownerPid = undefined;
+  }
+  if (ownerPid !== undefined && processIsRunning(ownerPid)) return;
+
+  let confirmed: JsonStoreLockState;
+  try {
+    confirmed = await readJsonStoreLockState(reclaimPath);
+  } catch (error) {
+    if (hasErrorCode(error, "ENOENT")) return;
+    throw error;
+  }
+  if (!sameJsonStoreLockState(initial, confirmed)) return;
+  await unlink(reclaimPath).catch((error) => {
+    if (!hasErrorCode(error, "ENOENT")) throw error;
+  });
+}
+
+async function acquireJsonStoreReclaimGuard(reclaimPath: string): Promise<FileHandle | undefined> {
+  try {
+    return await open(reclaimPath, "wx", 0o600);
+  } catch (error) {
+    if (!hasErrorCode(error, "EEXIST")) throw error;
+    await removeStaleJsonStoreReclaimGuard(reclaimPath);
+    try {
+      return await open(reclaimPath, "wx", 0o600);
+    } catch (retryError) {
+      if (hasErrorCode(retryError, "EEXIST")) return undefined;
+      throw retryError;
+    }
+  }
+}
+
+function waitForJsonStoreLock(): Promise<void> {
+  const { promise, resolve } = Promise.withResolvers<void>();
+  setTimeout(resolve, jsonStoreLockRetryMs());
+  return promise;
+}
+
+function processIsRunning(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return !hasErrorCode(error, "ESRCH");
+  }
+}
+
+type JsonStoreLockState = {
+  mtimeMs: number;
+  size: number;
+  ino: number | undefined;
+  content: string;
+};
+
+async function readJsonStoreLockState(lockPath: string): Promise<JsonStoreLockState> {
+  const lockStat = await lstat(lockPath);
+  if (!lockStat.isFile()) {
+    throw new Error(`JSON store mutation lock is not a regular file: ${lockPath}`);
+  }
+  return {
+    mtimeMs: lockStat.mtimeMs,
+    size: lockStat.size,
+    ino: typeof lockStat.ino === "number" ? lockStat.ino : undefined,
+    content: await readFile(lockPath, "utf8"),
+  };
+}
+
+function sameJsonStoreLockState(left: JsonStoreLockState, right: JsonStoreLockState): boolean {
+  return (
+    left.mtimeMs === right.mtimeMs &&
+    left.size === right.size &&
+    left.ino === right.ino &&
+    left.content === right.content
+  );
+}
+
+async function removeJsonStoreMutationLockIfOwned(lockPath: string, token: string): Promise<void> {
+  try {
+    const state = await readJsonStoreLockState(lockPath);
+    const metadata = JSON.parse(state.content) as { token?: unknown };
+    if (metadata.token === token) await unlink(lockPath);
+  } catch (error) {
+    if (!hasErrorCode(error, "ENOENT") && !(error instanceof SyntaxError)) throw error;
+  }
+}
+
+async function removeStaleJsonStoreLock(lockPath: string): Promise<void> {
+  const reclaimPath = `${lockPath}.reclaim`;
+  const reclaimHandle = await acquireJsonStoreReclaimGuard(reclaimPath);
+  if (!reclaimHandle) return;
+  try {
+    await reclaimHandle.writeFile(JSON.stringify({ pid: process.pid }), "utf8");
+    await jsonStoreMutationLockTestHooks?.afterReclaimGuardWrite?.(reclaimPath, String(process.pid));
+
+    let initial: JsonStoreLockState;
+    try {
+      initial = await readJsonStoreLockState(lockPath);
+    } catch (error) {
+      if (hasErrorCode(error, "ENOENT")) return;
+      throw error;
+    }
+    if (Date.now() - initial.mtimeMs <= jsonStoreLockStaleMs()) return;
+    let ownerPid: number | undefined;
+    try {
+      const metadata = JSON.parse(initial.content) as { pid?: unknown };
+      ownerPid = typeof metadata.pid === "number" && Number.isInteger(metadata.pid) ? metadata.pid : undefined;
+    } catch {
+      ownerPid = undefined;
+    }
+    if (ownerPid !== undefined && processIsRunning(ownerPid)) return;
+
+    let confirmed: JsonStoreLockState;
+    try {
+      confirmed = await readJsonStoreLockState(lockPath);
+    } catch (error) {
+      if (hasErrorCode(error, "ENOENT")) return;
+      throw error;
+    }
+    if (!sameJsonStoreLockState(initial, confirmed)) return;
+    await unlink(lockPath).catch((error) => {
+      if (!hasErrorCode(error, "ENOENT")) throw error;
+    });
+  } finally {
+    await closeAndRemoveJsonStoreReclaimGuard(reclaimPath, reclaimHandle);
+  }
+}
+
+async function confirmJsonStoreMutationLockOwnership(
+  lockPath: string,
+  token: string,
+  deadline: number
+): Promise<boolean> {
+  const reclaimPath = `${lockPath}.reclaim`;
+  while (true) {
+    const reclaimHandle = await acquireJsonStoreReclaimGuard(reclaimPath);
+    if (!reclaimHandle) {
+      if (Date.now() >= deadline) return false;
+      await waitForJsonStoreLock();
+      continue;
+    }
+    try {
+      try {
+        const state = await readJsonStoreLockState(lockPath);
+        const metadata = JSON.parse(state.content) as { token?: unknown };
+        return metadata.token === token;
+      } catch (error) {
+        if (hasErrorCode(error, "ENOENT") || error instanceof SyntaxError) return false;
+        throw error;
+      }
+    } finally {
+      await closeAndRemoveJsonStoreReclaimGuard(reclaimPath, reclaimHandle);
+    }
+  }
+}
+
+async function acquireJsonStoreMutationFileLock(key: string): Promise<() => Promise<void>> {
+  const lockPath = `${path.resolve(key)}.mutation.lock`;
+  await mkdir(path.dirname(lockPath), { recursive: true });
+  const token = randomUUID();
+  const deadline = Date.now() + jsonStoreLockTimeoutMs();
+  while (true) {
+    let handle: FileHandle;
+    try {
+      handle = await open(lockPath, "wx", 0o600);
+    } catch (error) {
+      if (!hasErrorCode(error, "EEXIST")) throw error;
+      await removeStaleJsonStoreLock(lockPath).catch((staleError) => {
+        if (!hasErrorCode(staleError, "ENOENT")) throw staleError;
+      });
+      if (Date.now() >= deadline) {
+        throw new Error(`Timed out acquiring JSON store mutation lock: ${lockPath}`);
+      }
+      await waitForJsonStoreLock();
+      continue;
+    }
+    try {
+      await jsonStoreMutationLockTestHooks?.beforeLockOwnerWrite?.(lockPath, token);
+      await handle.writeFile(JSON.stringify({ pid: process.pid, token }), "utf8");
+    } finally {
+      await handle.close().catch(() => undefined);
+    }
+    await jsonStoreMutationLockTestHooks?.beforeLockOwnershipConfirm?.(lockPath, token);
+
+    if (!(await confirmJsonStoreMutationLockOwnership(lockPath, token, deadline))) {
+      await removeJsonStoreMutationLockIfOwned(lockPath, token);
+      if (Date.now() >= deadline) {
+        throw new Error(`Timed out acquiring JSON store mutation lock: ${lockPath}`);
+      }
+      await waitForJsonStoreLock();
+      continue;
+    }
+
+    const heartbeat = setInterval(
+      () => {
+        void readFile(lockPath, "utf8")
+          .then((content) => {
+            const metadata = JSON.parse(content) as { token?: unknown };
+            if (metadata.token !== token) return;
+            const now = new Date();
+            return utimes(lockPath, now, now);
+          })
+          .catch(() => undefined);
+      },
+      Math.max(1, Math.floor(jsonStoreLockStaleMs() / 3))
+    );
+    heartbeat.unref();
+    return async () => {
+      clearInterval(heartbeat);
+      try {
+        const metadata = JSON.parse(await readFile(lockPath, "utf8")) as { token?: unknown };
+        if (metadata.token === token) await unlink(lockPath);
+      } catch (error) {
+        if (!hasErrorCode(error, "ENOENT")) throw error;
+      }
+    };
+  }
+}
+
+export async function withJsonStoreMutationLock<T>(key: string, operation: () => Promise<T>): Promise<T> {
+  const normalizedKey = path.resolve(key);
+  const previous = jsonStoreMutationTails.get(normalizedKey) ?? Promise.resolve();
+  const { promise: current, resolve: release } = Promise.withResolvers<void>();
+  const tail = previous.catch(() => undefined).then(() => current);
+  jsonStoreMutationTails.set(normalizedKey, tail);
+  await previous.catch(() => undefined);
+  let releaseFileLock: (() => Promise<void>) | undefined;
+  try {
+    releaseFileLock = await acquireJsonStoreMutationFileLock(normalizedKey);
+    return await operation();
+  } finally {
+    try {
+      await releaseFileLock?.();
+    } finally {
+      release();
+      if (jsonStoreMutationTails.get(normalizedKey) === tail) {
+        jsonStoreMutationTails.delete(normalizedKey);
+      }
+    }
+  }
+}
+
 export async function readJsonFile(filePath: string): Promise<unknown> {
   return JSON.parse(await readFile(filePath, "utf8")) as unknown;
 }
+
+export async function writeJsonFileAtomic(filePath: string, value: unknown): Promise<void> {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`;
+  try {
+    await writeFile(tempPath, JSON.stringify(value, null, 2), "utf8");
+    await rename(tempPath, filePath);
+  } catch (error) {
+    await unlink(tempPath).catch(() => undefined);
+    throw error;
+  }
+}

package/src/orchestration/consolidation-run.ts

@@ -32,7 +32,9 @@ import { applyCommitmentLedgerLifecycle } from "../commitment-ledger.js";
 import { recordDreamsPhaseRun } from "../maintenance/dreams-ledger.js";
 import { deindexMemoriesBatchAsync } from "../temporal-index-batch.js";
 import { isActiveMemoryStatus } from "../memory-lifecycle-ledger-utils.js";
+import { propagateInvalidation } from "./dependency-propagation.js";
 import {
+  resolveCapabilities,
   resolveConsolidationCapabilities,
   resolveCreationMemoryCapabilities,
   resolveIndexingCapabilities,
@@ -42,6 +44,7 @@ import {
   resolveRecallEnhancementCapabilities,
   type MemoryLifecycleCapabilitySet,
 } from "../capabilities.js";
+import { pruneOrphanCueAnchors } from "../cue-anchors.js";
 import type { LifecyclePolicyCoordinator } from "./lifecycle-policy-coordinator.js";
 import type { CompressionGuidelineCoordinator } from "./compression-guideline-coordinator.js";
 import type { SemanticConsolidationCoordinator } from "./semantic-consolidation-coordinator.js";
@@ -49,6 +52,7 @@ import type { EntitySynthesisCoordinator } from "./entity-synthesis-coordinator.
 import type { RecallSectionCoordinator } from "./recall-section-coordinator.js";
 import type { TierMigrationCoordinator } from "./tier-migration-coordinator.js";
 import type { StorageManager } from "../index.js";
+import type { NamespaceCatalog } from "../namespaces/catalog.js";
 import type { NamespaceStorageRouter } from "../namespaces/storage.js";
 import type { ExtractionEngine } from "../extraction.js";
 import type { EmbeddingFallback } from "../embedding-fallback.js";
@@ -67,6 +71,7 @@ export interface ConsolidationRunCoordinatorDeps {
   config: PluginConfig;
   getStorage: () => StorageManager;
   getStorageRouter: () => NamespaceStorageRouter;
+  getNamespaceCatalog?: () => NamespaceCatalog;
   getExtraction: () => ExtractionEngine;
   embeddingFallback: EmbeddingFallback;
   tmtBuilder: TmtBuilder;
@@ -100,9 +105,142 @@ export interface ConsolidationRunCoordinatorDeps {
   ) => Promise<{ content: string } | null>;
 }
 
+const MAX_HARMONIC_NAMESPACE_STORES = 50;
+const HARMONIC_CATALOG_CURSOR_FILE = "harmonic-catalog-cursor.json";
+
+type HarmonicStore = {
+  memoryDir: string;
+  abstractionNodeStoreDir?: string;
+};
+
+type HarmonicCatalogCursor = {
+  nextStorageDir?: string;
+};
+
 export class ConsolidationRunCoordinator {
   constructor(private readonly deps: ConsolidationRunCoordinatorDeps) {}
 
+  private async readHarmonicCatalogCursor(defaultDir: string): Promise<string | undefined> {
+    const cursorPath = path.join(defaultDir, "state", HARMONIC_CATALOG_CURSOR_FILE);
+    try {
+      const raw = await readFile(cursorPath, "utf-8");
+      const parsed = JSON.parse(raw) as HarmonicCatalogCursor;
+      return typeof parsed.nextStorageDir === "string" && parsed.nextStorageDir.length > 0
+        ? path.resolve(parsed.nextStorageDir)
+        : undefined;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+        log.warn(
+          `harmonic namespace catalog cursor read failed open: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+      }
+      return undefined;
+    }
+  }
+
+  private async writeHarmonicCatalogCursor(
+    defaultDir: string,
+    nextStorageDir: string,
+  ): Promise<void> {
+    const stateDir = path.join(defaultDir, "state");
+    await mkdir(stateDir, { recursive: true });
+    await writeFile(
+      path.join(stateDir, HARMONIC_CATALOG_CURSOR_FILE),
+      JSON.stringify({ nextStorageDir }, null, 2),
+      "utf-8",
+    );
+  }
+
+  private async pruneHarmonicStores(storage: StorageManager): Promise<void> {
+    const config = this.deps.config;
+    if (
+      !resolveCapabilities(config).harmonicRetrieval ||
+      !resolveConsolidationCapabilities(config).abstractionAnchors
+    ) {
+      return;
+    }
+
+    const stores = new Map<string, HarmonicStore>();
+    const defaultDir = path.resolve(storage.dir);
+    stores.set(defaultDir, {
+      memoryDir: storage.dir,
+      abstractionNodeStoreDir: config.abstractionNodeStoreDir,
+    });
+
+    try {
+      const catalog = this.deps.getNamespaceCatalog?.();
+      if (catalog?.enabled) {
+        const records = await catalog.listNamespaces({ discoveredBy: "write" });
+        const catalogStores = new Map<string, HarmonicStore>();
+        for (const record of records) {
+          const storageDir = path.resolve(record.storageDir);
+          if (!stores.has(storageDir) && !catalogStores.has(storageDir)) {
+            catalogStores.set(storageDir, { memoryDir: record.storageDir });
+          }
+        }
+
+        const candidates = [...catalogStores.entries()];
+        if (candidates.length > 0) {
+          const cursor = await this.readHarmonicCatalogCursor(defaultDir);
+          const cursorIndex = cursor
+            ? candidates.findIndex(([storageDir]) => storageDir === cursor)
+            : -1;
+          const startIndex = cursorIndex >= 0 ? cursorIndex : 0;
+          const selectedCount = Math.min(
+            candidates.length,
+            MAX_HARMONIC_NAMESPACE_STORES - 1,
+          );
+
+          for (let offset = 0; offset < selectedCount; offset += 1) {
+            const index = (startIndex + offset) % candidates.length;
+            const [storageDir, store] = candidates[index];
+            stores.set(storageDir, store);
+          }
+
+          const nextIndex = (startIndex + selectedCount) % candidates.length;
+          const nextStorageDir = candidates[nextIndex][0];
+          try {
+            await this.writeHarmonicCatalogCursor(defaultDir, nextStorageDir);
+          } catch (error) {
+            log.warn(
+              `harmonic namespace catalog cursor write failed open: ${
+                error instanceof Error ? error.message : String(error)
+              }`,
+            );
+          }
+
+          if (selectedCount < candidates.length) {
+            log.warn(
+              `harmonic namespace catalog truncated at ${MAX_HARMONIC_NAMESPACE_STORES} stores; ` +
+                `skipped ${candidates.length - selectedCount} store(s)`,
+            );
+          }
+        }
+      }
+    } catch (error) {
+      log.warn(
+        `harmonic namespace catalog read failed open: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+
+    for (const store of stores.values()) {
+      try {
+        const removed = await pruneOrphanCueAnchors(store);
+        if (removed > 0) {
+          log.info(`harmonic anchor prune removed ${removed} orphan(s) from ${store.memoryDir}`);
+        }
+      } catch (error) {
+        log.warn(
+          `harmonic anchor prune failed open for ${store.memoryDir}: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+      }
+    }
+  }
+
   async run(): Promise<{
     memoriesProcessed: number;
     merged: number;
@@ -124,6 +262,7 @@ export class ConsolidationRunCoordinator {
     if (this.deps.getAccessTrackingBuffer().size > 0) {
       await this.deps.flushAccessTracking();
     }
+    await this.pruneHarmonicStores(storage);
 
     let allMemories = await storage.readAllMemories();
     if (allMemories.length < 5) {
@@ -170,10 +309,36 @@ export class ConsolidationRunCoordinator {
             const toInvalidate = resolveIndexingCapabilities(config).queryAwareIndexing
               ? (memoryLookup?.get(item.existingId) ?? null)
               : null;
+            // Always capture the full pre-delete snapshot for propagation.
+            const propagationOld = allMemories.find(
+              (memory) => memory.frontmatter.id === item.existingId,
+            );
             if (await storage.invalidateMemory(item.existingId)) {
               invalidated += 1;
               memoryItemMutated = true;
               await this.deps.embeddingFallback.removeFromIndex(item.existingId);
+              if (propagationOld) {
+                try {
+                  await propagateInvalidation(
+                    {
+                      storage,
+                      extraction: this.deps.getExtraction(),
+                      config,
+                    },
+                    {
+                      oldMemory: propagationOld,
+                      replacementId: null,
+                      replacementContent: null,
+                      cause: "consolidation_invalidate",
+                      namespaceScope: config.defaultNamespace,
+                    },
+                  );
+                } catch (propagationErr) {
+                  log.warn(
+                    `consolidation dependency propagation failed for ${item.existingId}: ${propagationErr}`,
+                  );
+                }
+              }
               if (toInvalidate?.path && toInvalidate.frontmatter?.created) {
                 itemsDeindexBatch.push({
                   path: toInvalidate.path,
@@ -217,10 +382,37 @@ export class ConsolidationRunCoordinator {
               const toMergeInvalidate = resolveIndexingCapabilities(config).queryAwareIndexing
                 ? (memoryLookup?.get(item.mergeWith) ?? null)
                 : null;
+              // Capture the doomed memory before invalidation, independent of
+              // queryAwareIndexing and its optional lookup map.
+              const propagationOld = allMemories.find(
+                (memory) => memory.frontmatter.id === item.mergeWith,
+              );
               if (await storage.invalidateMemory(item.mergeWith)) {
                 invalidated += 1;
                 merged += 1;
                 await this.deps.embeddingFallback.removeFromIndex(item.mergeWith);
+                if (propagationOld) {
+                  try {
+                    await propagateInvalidation(
+                      {
+                        storage,
+                        extraction: this.deps.getExtraction(),
+                        config,
+                      },
+                      {
+                        oldMemory: propagationOld,
+                        replacementId: item.existingId,
+                        replacementContent: item.updatedContent,
+                        cause: "consolidation_merge",
+                        namespaceScope: config.defaultNamespace,
+                      },
+                    );
+                  } catch (propagationErr) {
+                    log.warn(
+                      `consolidation dependency propagation failed for ${item.mergeWith}: ${propagationErr}`,
+                    );
+                  }
+                }
                 if (
                   toMergeInvalidate?.path &&
                   toMergeInvalidate.frontmatter?.created

package/src/orchestration/contradiction-linking-coordinator.ts

@@ -17,6 +17,7 @@
  */
 
 import type {
+  MemoryFile,
   MemoryLink,
   PluginConfig,
   QmdSearchResult,
@@ -28,6 +29,7 @@ import type { ExtractionEngine } from "../extraction.js";
 import { log } from "../logger.js";
 import { resolveIndexingCapabilities } from "../capabilities.js";
 import { deindexMemoryAsync } from "../temporal-index.js";
+import { propagateInvalidation } from "./dependency-propagation.js";
 
 /** Result type of {@link ContradictionLinkingCoordinator.checkForContradiction}. */
 export interface ContradictionResult {
@@ -243,12 +245,44 @@ export class ContradictionLinkingCoordinator {
     ) {
       return;
     }
+
+    // Capture links before the primary supersession. The propagation hook is
+    // orchestration-owned, so its own supersessions cannot recurse.
+    let oldMemory: MemoryFile | null = null;
+    try {
+      oldMemory = await storage.getMemoryById(contradiction.supersededId);
+    } catch (err) {
+      log.warn(`contradiction propagation snapshot failed for ${contradiction.supersededId}: ${err}`);
+    }
+
     try {
-      await storage.supersedeMemory(
+      const superseded = await storage.supersedeMemory(
         contradiction.supersededId,
         newMemoryId,
         contradiction.reason,
       );
+      if (!superseded) return;
+      if (oldMemory) {
+        try {
+          await propagateInvalidation(
+            {
+              storage,
+              extraction: this.getExtraction(),
+              config,
+            },
+            {
+              oldMemory,
+              replacementId: newMemoryId,
+              replacementContent: (await storage.getMemoryById(newMemoryId))?.content ?? null,
+              cause: "contradiction",
+              namespaceScope: this.namespaceFromPath(storage.dir),
+            },
+          );
+        } catch (err) {
+          log.warn(`contradiction dependency propagation failed for ${contradiction.supersededId}: ${err}`);
+        }
+      }
+
       if (
         resolveIndexingCapabilities(config).queryAwareIndexing &&
         contradiction.supersededPath