@remnic/core 9.3.741 → 9.3.743

package/src/orchestrator.ts

@@ -104,6 +104,9 @@ import { EntitySynthesisCoordinator } from "./orchestration/entity-synthesis-coo
 import { RecallResultFormatter } from "./orchestration/recall-result-formatter.js";
 import { ConversationIndexCoordinator } from "./orchestration/conversation-index-coordinator.js";
 import { RecallRerankCoordinator } from "./orchestration/recall-rerank-coordinator.js";
+import { RecallSectionCoordinator } from "./orchestration/recall-section-coordinator.js";
+import { QmdResultResolver, qmdCollectionPathParts, qmdResultPathCandidates } from "./orchestration/qmd-result-resolver.js";
+import { ContradictionLinkingCoordinator } from "./orchestration/contradiction-linking-coordinator.js";
 export { hasIdentityRecoveryIntent, resolveEffectiveIdentityInjectionMode } from "./orchestration/recall-result-formatter.js";
 import {
   runLiveConnectorsOnce,
@@ -738,52 +741,6 @@ async function raceRecallAbort<T>(
   }
 }
 
-function qmdCollectionPathParts(resultPath: string): {
-  collection: string;
-  relativePath: string;
-} | null {
-  if (!resultPath || path.isAbsolute(resultPath)) return null;
-  const normalized = resultPath.replace(/\\/g, "/").replace(/^\/+/, "");
-  const slashIndex = normalized.indexOf("/");
-  if (slashIndex <= 0 || slashIndex >= normalized.length - 1) return null;
-  const collection = normalized.slice(0, slashIndex);
-  if (/^\d{4}-\d{2}-\d{2}$/.test(collection)) return null;
-  return {
-    collection,
-    relativePath: normalized.slice(slashIndex + 1),
-  };
-}
-
-function qmdResultPathCandidates(
-  storageDir: string,
-  resultPath: string,
-): string[] {
-  const candidates = new Set<string>();
-  const storageRoot = path.resolve(storageDir);
-  const addCandidate = (candidate: string) => {
-    const resolved = path.resolve(candidate);
-    if (isPathInsideStorageRoot(storageRoot, resolved)) {
-      candidates.add(resolved);
-    }
-  };
-  const addRelativeCandidates = (relativePath: string) => {
-    const normalized = relativePath.replace(/\\/g, "/").replace(/^\/+/, "");
-    if (!normalized) return;
-    addCandidate(path.join(storageRoot, normalized));
-    if (/^\d{4}-\d{2}-\d{2}\//.test(normalized)) {
-      addCandidate(path.join(storageRoot, "facts", normalized));
-    }
-  };
-
-  if (path.isAbsolute(resultPath)) {
-    addCandidate(resultPath);
-  } else {
-    addRelativeCandidates(resultPath);
-  }
-
-  return [...candidates];
-}
-
 /** Maximum age (ms) before a compaction-reset signal file is considered stale and removed. */
 const COMPACTION_SIGNAL_MAX_AGE_MS = 60 * 60 * 1000; // 1 hour
 const DEFAULT_QMD_STARTUP_COLLECTION_CHECK_TIMEOUT_MS = 10_000;
@@ -1885,6 +1842,9 @@ export class Orchestrator {
    */
   readonly conversationIndexCoordinator: ConversationIndexCoordinator;
   readonly recallRerankCoordinator: RecallRerankCoordinator;
+  readonly recallSectionCoordinator: RecallSectionCoordinator;
+  readonly qmdResultResolver: QmdResultResolver;
+  readonly contradictionLinkingCoordinator: ContradictionLinkingCoordinator;
   private heartbeatObserverChains = new Map<string, Promise<void>>();
   private recentExtractionFingerprints = new Map<string, number>();
   private readonly consolidationObservers = new Set<
@@ -2885,6 +2845,19 @@ export class Orchestrator {
       readQmdResultMemory: (resultPath, fallbackStorage, recallNamespaces) =>
         this.readQmdResultMemory(resultPath, fallbackStorage, recallNamespaces),
     });
+    this.recallSectionCoordinator = new RecallSectionCoordinator({
+      getConfig: () => this.config,
+      resolveSectionEnabled: (id, def) => this.isRecallSectionEnabled(id, def),
+    });
+    this.contradictionLinkingCoordinator = new ContradictionLinkingCoordinator({
+      getConfig: () => this.config,
+      isSearchAvailable: () => this.isSearchAvailableForNamespaceRouting(),
+      searchAcrossNamespaces: (options) => this.searchAcrossNamespaces(options),
+      extractMemoryIdsFromResults: (results) => this.extractMemoryIdsFromResults(results),
+      namespaceFromPath: (p) => this.namespaceFromPath(p),
+      storageForNamespace: (namespace) => this.storageRouter.storageFor(namespace),
+      getExtraction: () => this.extraction,
+    });
     this.modelRegistry = new ModelRegistry(config.memoryDir);
     this.relevance = new RelevanceStore(config.memoryDir);
     this.negatives = new NegativeExampleStore(config.memoryDir);
@@ -2913,6 +2886,13 @@ export class Orchestrator {
       fastChatCompletion: (messages, options) =>
         this.fastChatCompletion(messages, options),
     });
+    this.qmdResultResolver = new QmdResultResolver({
+      getConfig: () => this.config,
+      storageFor: (namespace) => this.storageRouter.storageFor(namespace),
+      storageDirNamespace: (storageDir) => this.storageDirNamespace(storageDir),
+      qmdCollectionNamespaceFromPrefix: (prefix) => this.qmdCollectionNamespaceFromPrefix(prefix),
+      namespaceFromPath: (p) => this.namespaceFromPath(p),
+    });
 
     this.sessionObserver = new SessionObserverState({
       memoryDir: config.memoryDir,
@@ -6414,52 +6394,46 @@ export class Orchestrator {
     }));
   }
 
+  // Issue #1526 (seam 13): recall section budgeting/assembly moved to
+  // RecallSectionCoordinator. Thin delegation keeps the orchestrator's
+  // recallInternal call sites stable.
   private getRecallSectionEntry(
     sectionId: string,
   ): RecallSectionConfig | undefined {
-    const pipeline = Array.isArray(this.config.recallPipeline)
-      ? this.config.recallPipeline
-      : [];
-    return pipeline.find((entry) => entry.id === sectionId);
+    return this.recallSectionCoordinator.getRecallSectionEntry(sectionId);
   }
 
   private isRecallSectionEnabled(
     sectionId: string,
     defaultEnabled: boolean = true,
   ): boolean {
-    const entry = this.getRecallSectionEntry(sectionId);
-    if (!entry) return defaultEnabled;
-    return entry.enabled !== false;
+    return this.recallSectionCoordinator.isRecallSectionEnabled(
+      sectionId,
+      defaultEnabled,
+    );
   }
 
   private isSpecializedRecallSectionEnabled(
     sectionId: string,
     topLevelEnabled: boolean,
   ): boolean {
-    const entry = this.getRecallSectionEntry(sectionId);
-    if (!entry) return topLevelEnabled;
-    return entry.enabled === true || (topLevelEnabled && entry.enabled !== false);
+    return this.recallSectionCoordinator.isSpecializedRecallSectionEnabled(
+      sectionId,
+      topLevelEnabled,
+    );
   }
 
   private getRecallSectionMaxChars(
     sectionId: string,
   ): number | null | undefined {
-    const entry = this.getRecallSectionEntry(sectionId);
-    if (!entry) return undefined;
-    if (entry.maxChars === null) return null;
-    if (typeof entry.maxChars !== "number") return undefined;
-    return Math.max(0, Math.floor(entry.maxChars));
+    return this.recallSectionCoordinator.getRecallSectionMaxChars(sectionId);
   }
 
   private getRecallSectionNumber(
     sectionId: string,
     key: keyof RecallSectionConfig,
   ): number | undefined {
-    const entry = this.getRecallSectionEntry(sectionId);
-    if (!entry) return undefined;
-    const value = entry[key];
-    if (typeof value !== "number" || !Number.isFinite(value)) return undefined;
-    return Math.max(0, Math.floor(value));
+    return this.recallSectionCoordinator.getRecallSectionNumber(sectionId, key);
   }
 
   private appendRecallSection(
@@ -6467,104 +6441,25 @@ export class Orchestrator {
     sectionId: string,
     content: string,
   ): boolean {
-    // Returns true when the section was actually appended to sectionBuckets,
-    // false when it was dropped (disabled, empty, or maxChars===0). Callers
-    // that need to know whether injection occurred (e.g. xray annotation for
-    // peer-profile) must gate on this return value rather than on whether the
-    // section text was computed (Codex P2 finding, PR #764).
-    if (!this.isRecallSectionEnabled(sectionId)) return false;
-    const trimmed = content.trim();
-    if (trimmed.length === 0) return false;
-
-    const maxChars = this.getRecallSectionMaxChars(sectionId);
-    let finalContent = trimmed;
-    if (maxChars === 0) return false;
-    if (typeof maxChars === "number" && finalContent.length > maxChars) {
-      finalContent = `${finalContent.slice(0, maxChars)}\n\n...(trimmed)\n`;
-    }
-
-    const existing = sectionBuckets.get(sectionId) ?? [];
-    existing.push(finalContent);
-    sectionBuckets.set(sectionId, existing);
-    return true;
+    return this.recallSectionCoordinator.appendRecallSection(
+      sectionBuckets,
+      sectionId,
+      content,
+    );
   }
 
   private truncateRecallSectionToBudget(
     content: string,
     maxChars: number,
   ): string {
-    if (maxChars <= 0) return "";
-    if (content.length <= maxChars) return content;
-    const suffix = "\n\n...(memory context trimmed)";
-    if (maxChars <= suffix.length) {
-      return content.slice(0, maxChars);
-    }
-    return `${content.slice(0, maxChars - suffix.length)}${suffix}`;
-  }
-
-  private protectedRecallSectionIds(
-    sectionBuckets: Map<string, string[]>,
-  ): Set<string> {
-    const protectedIds = new Set<string>();
-    if ((sectionBuckets.get("memories")?.length ?? 0) > 0) {
-      protectedIds.add("memories");
-    }
-    return protectedIds;
-  }
-
-  private protectedRecallReservationChars(content: string): number {
-    const headingBoundary = content.indexOf("\n\n");
-    const headingChars =
-      headingBoundary >= 0 ? headingBoundary + 2 : Math.min(content.length, 24);
-    return Math.min(content.length, Math.max(headingChars, 24));
-  }
-
-  private estimateReservedRecallBudget(
-    entries: Array<{ id: string; content: string }>,
-    startIndex: number,
-    protectedIds: Set<string>,
-    alreadyIncludedCount: number,
-  ): number {
-    const separatorLength = "\n\n---\n\n".length;
-    let reserved = 0;
-    let simulatedIncluded = alreadyIncludedCount;
-    for (let i = startIndex; i < entries.length; i += 1) {
-      const entry = entries[i];
-      if (!entry || !protectedIds.has(entry.id)) continue;
-      if (simulatedIncluded > 0) {
-        reserved += separatorLength;
-      }
-      reserved += this.protectedRecallReservationChars(entry.content);
-      simulatedIncluded += 1;
-    }
-    return reserved;
+    return this.recallSectionCoordinator.truncateRecallSectionToBudget(
+      content,
+      maxChars,
+    );
   }
 
   private getRecallBudgetChars(override?: number): number {
-    if (
-      typeof override === "number" &&
-      Number.isFinite(override) &&
-      override >= 0
-    ) {
-      return Math.floor(override);
-    }
-    const configuredBudget = this.config.recallBudgetChars;
-    if (
-      typeof configuredBudget === "number" &&
-      Number.isFinite(configuredBudget) &&
-      configuredBudget >= 0
-    ) {
-      return Math.floor(configuredBudget);
-    }
-    const tokenBudget = this.config.maxMemoryTokens;
-    if (
-      typeof tokenBudget === "number" &&
-      Number.isFinite(tokenBudget) &&
-      tokenBudget >= 0
-    ) {
-      return Math.floor(tokenBudget * 4);
-    }
-    return 0;
+    return this.recallSectionCoordinator.getRecallBudgetChars(override);
   }
 
   private assembleRecallSections(
@@ -6577,89 +6472,13 @@ export class Orchestrator {
     truncated: boolean;
     finalChars: number;
   } {
-    const orderedEntries: Array<{ id: string; content: string }> = [];
-    const pipeline = Array.isArray(this.config.recallPipeline)
-      ? this.config.recallPipeline
-      : [];
-    const orderedIds = pipeline
-      .filter((entry) => entry.enabled !== false)
-      .map((entry) => entry.id);
-    const seen = new Set<string>();
-
-    for (const id of orderedIds) {
-      const chunks = sectionBuckets.get(id);
-      if (!chunks || chunks.length === 0) continue;
-      orderedEntries.push({ id, content: chunks.join("\n\n") });
-      seen.add(id);
-    }
-
-    for (const [id, chunks] of sectionBuckets.entries()) {
-      if (seen.has(id)) continue;
-      if (chunks.length === 0) continue;
-      orderedEntries.push({ id, content: chunks.join("\n\n") });
-    }
-
-    const budget = this.getRecallBudgetChars(budgetOverride);
-    if (budget === 0) {
-      return {
-        sections: [],
-        includedIds: [],
-        omittedIds: orderedEntries.map((entry) => entry.id),
-        truncated: orderedEntries.length > 0,
-        finalChars: 0,
-      };
-    }
-
-    const separator = "\n\n---\n\n";
-    const protectedIds = this.protectedRecallSectionIds(sectionBuckets);
-    const sections: string[] = [];
-    const includedIds: string[] = [];
-    const omittedIds: string[] = [];
-    let usedChars = 0;
-    let truncated = false;
+    return this.recallSectionCoordinator.assembleRecallSections(
+      sectionBuckets,
+      budgetOverride,
+    );
+  }
 
-    for (let index = 0; index < orderedEntries.length; index += 1) {
-      const entry = orderedEntries[index]!;
-      const separatorChars = sections.length > 0 ? separator.length : 0;
-      const reserve = protectedIds.has(entry.id)
-        ? 0
-        : this.estimateReservedRecallBudget(
-            orderedEntries,
-            index + 1,
-            protectedIds,
-            sections.length + 1,
-          );
-      const availableForEntry = budget - usedChars - separatorChars - reserve;
-      if (availableForEntry <= 0) {
-        omittedIds.push(entry.id);
-        truncated = true;
-        continue;
-      }
-      const finalContent = this.truncateRecallSectionToBudget(
-        entry.content,
-        availableForEntry,
-      );
-      if (!finalContent) {
-        omittedIds.push(entry.id);
-        truncated = true;
-        continue;
-      }
-      if (finalContent.length < entry.content.length) {
-        truncated = true;
-      }
-      sections.push(finalContent);
-      includedIds.push(entry.id);
-      usedChars += separatorChars + finalContent.length;
-    }
 
-    return {
-      sections,
-      includedIds,
-      omittedIds,
-      truncated,
-      finalChars: usedChars,
-    };
-  }
 
   /**
    * Clock source for the shared post-retrieval assembly/enrichment budget. The
@@ -16898,143 +16717,14 @@ export class Orchestrator {
     return null;
   }
 
+  // Issue #1526 seam 11: QMD result-resolution methods moved to QmdResultResolver.
+  // Thin delegation keeps the private API stable for callers + tests.
   private async readQmdResultMemory(
     resultPath: string,
     fallbackStorage: StorageManager,
     recallNamespaces: readonly string[] = [],
   ): Promise<MemoryFile | null> {
-    const parts = qmdCollectionPathParts(resultPath);
-    const storageDirFor = (storage: StorageManager): string | null =>
-      typeof (storage as { dir?: unknown }).dir === "string" &&
-      (storage as { dir?: string }).dir
-        ? (storage as { dir: string }).dir
-        : null;
-    const fallbackStorageDir = storageDirFor(fallbackStorage);
-    const coldCollection = this.config.qmdColdCollection ?? "openclaw-engram-cold";
-    if (parts && parts.collection === coldCollection) {
-      const storages: StorageManager[] = [];
-      const seenStorageDirs = new Set<string>();
-      const addStorage = (storage: StorageManager): void => {
-        const storageDir = storageDirFor(storage);
-        const storageKey = storageDir
-          ? path.resolve(storageDir)
-          : `storage-without-dir-${storages.length}`;
-        if (seenStorageDirs.has(storageKey)) return;
-        seenStorageDirs.add(storageKey);
-        storages.push(storage);
-      };
-
-      const fallbackNamespace =
-        fallbackStorageDir !== null
-          ? this.storageDirNamespace(fallbackStorageDir)
-          : this.config.defaultNamespace;
-      if (
-        recallNamespaces.length === 0 ||
-        !resolveNamespaceCapabilities(this.config).namespaces ||
-        recallNamespaces.includes(fallbackNamespace)
-      ) {
-        addStorage(fallbackStorage);
-      }
-
-      if (recallNamespaces.length > 0) {
-        for (const namespace of recallNamespaces) {
-          try {
-            addStorage(await this.storageRouter.storageFor(namespace));
-          } catch (err) {
-            log.debug("qmd cold result namespace storage lookup skipped", {
-              path: resultPath,
-              namespace,
-              error: (err as Error).message,
-            });
-          }
-        }
-      }
-
-      for (const storage of storages) {
-        const storageDir = storageDirFor(storage);
-        if (!storageDir) {
-          const memory = await storage.readMemoryByPath(resultPath);
-          if (memory) return memory;
-          continue;
-        }
-        try {
-          const coldRoot = path.join(storageDir, "cold");
-          for (const candidate of qmdResultPathCandidates(
-            coldRoot,
-            parts.relativePath,
-          )) {
-            const memory = await storage.readMemoryByPath(candidate);
-            if (memory) return memory;
-          }
-        } catch (err) {
-          if (err instanceof SecureStoreLockedError) throw err;
-          log.debug("qmd cold result path lookup failed open", {
-            path: resultPath,
-            collection: coldCollection,
-            error: (err as Error).message,
-          });
-        }
-      }
-      return null;
-    }
-    const collectionNamespace = parts
-      ? this.qmdCollectionNamespaceFromPrefix(parts.collection)
-      : null;
-
-    if (parts && collectionNamespace) {
-      try {
-        const collectionStorage =
-          await this.storageRouter.storageFor(collectionNamespace);
-        for (const candidate of qmdResultPathCandidates(
-          collectionStorage.dir,
-          parts.relativePath,
-        )) {
-          const memory = await collectionStorage.readMemoryByPath(candidate);
-          if (memory) return memory;
-        }
-        return null;
-      } catch (err) {
-        if (err instanceof SecureStoreLockedError) throw err;
-        log.debug("qmd result namespace path lookup failed open", {
-          path: resultPath,
-          namespace: collectionNamespace,
-          error: (err as Error).message,
-        });
-        return null;
-      }
-    }
-
-    if (path.isAbsolute(resultPath)) {
-      if (!fallbackStorageDir) {
-        return await fallbackStorage.readMemoryByPath(resultPath);
-      }
-      const ownerStorage = await this.storageForAbsoluteQmdResultPath(
-        resultPath,
-        fallbackStorage,
-        recallNamespaces,
-      );
-      if (!ownerStorage) return null;
-      for (const candidate of qmdResultPathCandidates(
-        ownerStorage.dir,
-        resultPath,
-      )) {
-        const memory = await ownerStorage.storage.readMemoryByPath(candidate);
-        if (memory) return memory;
-      }
-      return null;
-    }
-
-    if (!fallbackStorageDir) {
-      return await fallbackStorage.readMemoryByPath(resultPath);
-    }
-    for (const candidate of qmdResultPathCandidates(
-      fallbackStorageDir,
-      resultPath,
-    )) {
-      const memory = await fallbackStorage.readMemoryByPath(candidate);
-      if (memory) return memory;
-    }
-    return null;
+    return this.qmdResultResolver.readQmdResultMemory(resultPath, fallbackStorage, recallNamespaces);
   }
 
   private async resolveColdQmdResultForRecall(
@@ -17042,40 +16732,7 @@ export class Orchestrator {
     fallbackStorage: StorageManager,
     recallNamespaces: readonly string[] = [],
   ): Promise<{ namespace: string; result: QmdSearchResult } | null> {
-    const memory = await this.readQmdResultMemory(
-      result.path,
-      fallbackStorage,
-      recallNamespaces,
-    );
-    if (!memory) return null;
-
-    let ownerNamespace: string | null = null;
-    if (path.isAbsolute(memory.path)) {
-      const ownerStorage = await this.storageForAbsoluteQmdResultPath(
-        memory.path,
-        fallbackStorage,
-        recallNamespaces,
-      );
-      ownerNamespace = ownerStorage?.namespace ?? null;
-      if (!ownerNamespace && resolveNamespaceCapabilities(this.config).namespaces) return null;
-    }
-    ownerNamespace ??= this.namespaceFromPath(memory.path);
-    if (
-      recallNamespaces.length > 0 &&
-      !recallNamespaces.includes(ownerNamespace)
-    ) {
-      return null;
-    }
-
-    return {
-      namespace: ownerNamespace,
-      result: {
-        ...result,
-        docid: result.docid || memory.frontmatter.id,
-        path: memory.path,
-        snippet: result.snippet || memory.content.slice(0, 400),
-      },
-    };
+    return this.qmdResultResolver.resolveColdQmdResultForRecall(result, fallbackStorage, recallNamespaces);
   }
 
   private async storageForAbsoluteQmdResultPath(
@@ -17083,73 +16740,7 @@ export class Orchestrator {
     fallbackStorage: StorageManager,
     recallNamespaces: readonly string[] = [],
   ): Promise<{ storage: StorageManager; dir: string; namespace: string } | null> {
-    const resolvedPath = path.resolve(resultPath);
-    const memoryRoot = path.resolve(this.config.memoryDir);
-    const namespacesRoot = path.join(memoryRoot, "namespaces");
-    const fallbackStorageDir =
-      typeof (fallbackStorage as { dir?: unknown }).dir === "string" &&
-      (fallbackStorage as { dir?: string }).dir
-        ? (fallbackStorage as { dir: string }).dir
-        : null;
-    const matches: Array<{ storage: StorageManager; dir: string; namespace: string }> = [];
-    const seenDirs = new Set<string>();
-
-    const maybeAddStorage = (storage: StorageManager, namespace: string) => {
-      const storageDir =
-        typeof (storage as { dir?: unknown }).dir === "string" &&
-        (storage as { dir?: string }).dir
-          ? (storage as { dir: string }).dir
-          : null;
-      if (!storageDir) return;
-      const candidateRoot = path.resolve(storageDir);
-      if (seenDirs.has(candidateRoot)) return;
-      if (!isPathInsideStorageRoot(candidateRoot, resolvedPath)) return;
-      if (
-        candidateRoot === memoryRoot &&
-        isPathInsideStorageRoot(namespacesRoot, resolvedPath)
-      ) {
-        return;
-      }
-      seenDirs.add(candidateRoot);
-      matches.push({ storage, dir: candidateRoot, namespace });
-    };
-
-    const fallbackNamespace =
-      fallbackStorageDir !== null
-        ? this.storageDirNamespace(fallbackStorageDir)
-        : this.config.defaultNamespace;
-    maybeAddStorage(fallbackStorage, fallbackNamespace);
-
-    const candidateNamespaces = new Set<string>();
-    candidateNamespaces.add(this.config.defaultNamespace);
-    candidateNamespaces.add(this.config.sharedNamespace);
-    for (const ns of recallNamespaces) {
-      candidateNamespaces.add(ns);
-    }
-    if (isPathInsideStorageRoot(namespacesRoot, resolvedPath)) {
-      const relativeToNamespaces = path.relative(namespacesRoot, resolvedPath);
-      const [namespaceSegment] = relativeToNamespaces.split(/[\\/]/);
-      if (namespaceSegment) {
-        candidateNamespaces.add(
-          namespaceIdentityFromToken(namespaceSegment) ?? namespaceSegment,
-        );
-      }
-    }
-    for (const policy of this.config.namespacePolicies ?? []) {
-      candidateNamespaces.add(policy.name);
-    }
-
-    for (const ns of candidateNamespaces) {
-      if (!ns) continue;
-      try {
-        maybeAddStorage(await this.storageRouter.storageFor(ns), ns);
-      } catch {
-        continue;
-      }
-    }
-
-    matches.sort((a, b) => b.dir.length - a.dir.length);
-    return matches[0] ?? null;
+    return this.qmdResultResolver.storageForAbsoluteQmdResultPath(resultPath, fallbackStorage, recallNamespaces);
   }
 
   // Issue #1526: recall-rerank methods moved to RecallRerankCoordinator.
@@ -17211,18 +16802,7 @@ export class Orchestrator {
     includedSections?: string[];
     omittedSections?: string[];
   }): LastRecallBudgetSummary {
-    return {
-      requestedTopK: options.requestedTopK,
-      appliedTopK: options.recallResultLimit,
-      recallBudgetChars: this.getRecallBudgetChars(),
-      maxMemoryTokens: this.config.maxMemoryTokens,
-      qmdFetchLimit: options.qmdFetchLimit,
-      qmdHybridFetchLimit: options.qmdHybridFetchLimit,
-      finalContextChars: options.finalContextChars,
-      truncated: options.truncated,
-      includedSections: [...(options.includedSections ?? [])],
-      omittedSections: [...(options.omittedSections ?? [])],
-    };
+    return this.recallSectionCoordinator.buildLastRecallBudgetSummary(options);
   }
 
   private collectLastRecallSources(
@@ -17234,16 +16814,10 @@ export class Orchestrator {
       | "cold_fallback"
       | "recent_scan",
   ): string[] {
-    const used = new Set<string>();
-    if (recallSource !== "none") {
-      used.add(recallSource);
-    }
-    for (const [sectionId, chunks] of sectionBuckets.entries()) {
-      if (chunks.length > 0) {
-        used.add(sectionId);
-      }
-    }
-    return [...used];
+    return this.recallSectionCoordinator.collectLastRecallSources(
+      sectionBuckets,
+      recallSource,
+    );
   }
 
   /**
@@ -18603,99 +18177,11 @@ export class Orchestrator {
     supersededCreated: string;
     supersededTags: string[];
   } | null> {
-    if (!this.isSearchAvailableForNamespaceRouting()) return null;
-
-    // Search for similar memories
-    const results = await this.searchAcrossNamespaces({
-      query: content,
-      namespaces: [namespaceScope],
-      maxResults: 5,
-      mode: "search",
-    });
-
-    for (const result of results) {
-      // Check similarity threshold
-      if (result.score < this.config.contradictionSimilarityThreshold) {
-        continue;
-      }
-
-      // Get the existing memory
-      const memoryId = this.extractMemoryIdsFromResults([result])[0];
-      if (!memoryId) continue;
-
-      const resultNamespace = this.namespaceFromPath(result.path);
-      if (resultNamespace !== namespaceScope) continue;
-      const resultStorage =
-        await this.storageRouter.storageFor(resultNamespace);
-      const existingMemory = await resultStorage.getMemoryById(memoryId);
-      if (!existingMemory) continue;
-
-      // Skip memories already resolved or explicitly forgotten. Other
-      // non-active statuses remain valid contradiction candidates.
-      if (
-        existingMemory.frontmatter.status === "superseded" ||
-        existingMemory.frontmatter.status === "forgotten"
-      ) {
-        continue;
-      }
-
-      // Verify contradiction with LLM
-      const verification = await this.extraction.verifyContradiction(
-        { content, category },
-        {
-          id: existingMemory.frontmatter.id,
-          content: existingMemory.content,
-          category: existingMemory.frontmatter.category,
-          created: existingMemory.frontmatter.created,
-        },
-      );
-
-      if (!verification) continue;
-
-      // Check if it's a real contradiction with high confidence
-      if (
-        verification.isContradiction &&
-        verification.confidence >= this.config.contradictionMinConfidence
-      ) {
-        // When the LLM says the existing memory is newer (whichIsNewer ===
-        // "first") the incoming fact is the stale one in both resolve modes —
-        // log and continue so the caller never marks contradictionDetected and
-        // the semantic-skip gate can discard the outdated write normally.
-        if (verification.whichIsNewer === "first") {
-          log.info(
-            `detected contradiction (confidence: ${verification.confidence}): ${existingMemory.frontmatter.id} vs new memory — existing is newer, incoming fact is stale`,
-          );
-          continue;
-        }
-
-        // The new fact is newer than the existing one. When auto-resolve is
-        // enabled, the caller retires the old memory AFTER the new write lands
-        // and its tombstone status is known (#1645: defer auto-resolve until
-        // tombstone status is known — a tombstone-blocked new write must not
-        // retire the only active copy, leaving neither memory active). When
-        // disabled, the old memory stays active for manual review. The
-        // contradiction info is returned in both cases so the caller can apply
-        // the deferred retire post-write.
-
-        // Return the contradiction info regardless of auto-resolve setting.
-        // The caller uses this to set `contradictionDetected=true` which
-        // prevents the semantic-skip guard from silently dropping a
-        // legitimately contradictory update (the regression this fixes).
-        log.info(
-          `detected contradiction (confidence: ${verification.confidence}): ${existingMemory.frontmatter.id} vs new memory${this.config.contradictionAutoResolve ? " (auto-resolved)" : " (queued for manual review)"}`,
-        );
-        return {
-          supersededId: existingMemory.frontmatter.id,
-          confidence: verification.confidence,
-          reason: verification.reasoning,
-          supersededPath: existingMemory.path,
-          supersededCreated: existingMemory.frontmatter.created,
-          supersededTags: existingMemory.frontmatter.tags ?? [],
-        };
-      }
-    }
-
-    return null;
+    return this.contradictionLinkingCoordinator.checkForContradiction(
+      content,
+      category,
+      namespaceScope,
+    );
   }
 
   /**
@@ -18718,49 +18204,12 @@ export class Orchestrator {
     newMemoryId: string,
     postWriteGuard: boolean,
   ): Promise<void> {
-    // #1645 yG2: clear the pre-write `supersedes` link from a blocked row so
-    // it doesn't claim to supersede a still-active memory (best-effort).
-    if (postWriteGuard && contradiction && this.config.contradictionAutoResolve) {
-      try {
-        const blockedRow = await storage.getMemoryById(newMemoryId);
-        if (blockedRow?.frontmatter?.supersedes) {
-          await storage.writeMemoryFrontmatter(blockedRow, { supersedes: undefined });
-        }
-      } catch (err) {
-        log.warn(
-          `contradiction auto-resolve supersedes clear failed for blocked ${newMemoryId}: ${err}`,
-        );
-      }
-    }
-    if (
-      !contradiction ||
-      !this.config.contradictionAutoResolve ||
-      postWriteGuard
-    ) {
-      return;
-    }
-    try {
-      await storage.supersedeMemory(
-        contradiction.supersededId,
-        newMemoryId,
-        contradiction.reason,
-      );
-      if (
-        resolveIndexingCapabilities(this.config).queryAwareIndexing &&
-        contradiction.supersededPath
-      ) {
-        deindexMemory(
-          this.config.memoryDir,
-          contradiction.supersededPath,
-          contradiction.supersededCreated,
-          contradiction.supersededTags,
-        );
-      }
-    } catch (err) {
-      log.warn(
-        `contradiction auto-resolve supersede failed for ${contradiction.supersededId}: ${err}`,
-      );
-    }
+    return this.contradictionLinkingCoordinator.applyDeferredContradictionResolve(
+      contradiction,
+      storage,
+      newMemoryId,
+      postWriteGuard,
+    );
   }
 
   // ---------------------------------------------------------------------------
@@ -18775,61 +18224,14 @@ export class Orchestrator {
     category: string,
     namespaceScope: string,
   ): Promise<MemoryLink[]> {
-    if (!this.isSearchAvailableForNamespaceRouting()) return [];
-
-    // Search for related memories
-    const results = await this.searchAcrossNamespaces({
-      query: content,
-      namespaces: [namespaceScope],
-      maxResults: 5,
-      mode: "search",
-    });
-    if (results.length === 0) return [];
-
-    // Get full memory details for candidates
-    const candidates: Array<{ id: string; content: string; category: string }> =
-      [];
-    for (const result of results) {
-      const memoryId = this.extractMemoryIdsFromResults([result])[0];
-      if (!memoryId) continue;
-
-      const resultNamespace = this.namespaceFromPath(result.path);
-      if (resultNamespace !== namespaceScope) continue;
-      const resultStorage =
-        await this.storageRouter.storageFor(resultNamespace);
-      const memory = await resultStorage.getMemoryById(memoryId);
-      if (
-        memory &&
-        memory.frontmatter.status !== "superseded" &&
-        memory.frontmatter.status !== "forgotten"
-      ) {
-        candidates.push({
-          id: memory.frontmatter.id,
-          content: memory.content,
-          category: memory.frontmatter.category,
-        });
-      }
-    }
-
-    if (candidates.length === 0) return [];
-
-    // Ask LLM for link suggestions
-    const suggestions = await this.extraction.suggestLinks(
-      { content, category },
-      candidates,
+    return this.contradictionLinkingCoordinator.suggestLinksForMemory(
+      content,
+      category,
+      namespaceScope,
     );
-
-    if (!suggestions || suggestions.links.length === 0) return [];
-
-    // Convert to MemoryLink format
-    return suggestions.links.map((link) => ({
-      targetId: link.targetId,
-      linkType: link.linkType,
-      strength: link.strength,
-      reason: link.reason || undefined,
-    }));
   }
 
+
   private async graphSeedPathRelativeToStorage(
     storage: StorageManager,
     result: QmdSearchResult,