@remnic/core 9.3.742 → 9.3.744

package/src/orchestrator.ts

@@ -104,8 +104,20 @@ 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 {
+  GraphRecallCoordinator,
+  mergeGraphExpandedResults,
+  graphPathRelativeToStorage,
+  blendGraphExpandedRecallScore,
+  type GraphRecallRankedResult,
+  type GraphRecallShadowComparison,
+} from "./orchestration/graph-recall-coordinator.js";
+export { mergeGraphExpandedResults, graphPathRelativeToStorage, blendGraphExpandedRecallScore } from "./orchestration/graph-recall-coordinator.js";
+export type { GraphRecallRankedResult, GraphRecallShadowComparison } from "./orchestration/graph-recall-coordinator.js";
 import {
   runLiveConnectorsOnce,
   type LiveConnectorsRunSummary,
@@ -504,21 +516,6 @@ export interface GraphRecallSnapshot {
   shadowComparison?: GraphRecallShadowComparison;
 }
 
-export interface GraphRecallRankedResult {
-  path: string;
-  score: number;
-  docid?: string;
-  sourceLabels: string[];
-}
-
-export interface GraphRecallShadowComparison {
-  baselineCount: number;
-  graphCount: number;
-  overlapCount: number;
-  overlapRatio: number;
-  averageOverlapDelta: number;
-}
-
 export interface IntentDebugSnapshot {
   recordedAt: string;
   promptHash: string;
@@ -1341,63 +1338,6 @@ export function computeQmdHybridFetchLimit(
   const artifactHeadroom = Math.max(20, Math.max(0, maxArtifactRecall) * 8);
   return Math.min(400, cappedRecallLimit + artifactHeadroom);
 }
-
-export function mergeGraphExpandedResults(
-  primary: QmdSearchResult[],
-  expanded: QmdSearchResult[],
-): QmdSearchResult[] {
-  const mergedByPath = new Map<string, QmdSearchResult>();
-  for (const item of [...primary, ...expanded]) {
-    const prev = mergedByPath.get(item.path);
-    if (!prev) {
-      mergedByPath.set(item.path, item);
-      continue;
-    }
-    const better = item.score > prev.score ? item : prev;
-    const snippet = prev.snippet || item.snippet;
-    mergedByPath.set(item.path, { ...better, snippet });
-  }
-  return Array.from(mergedByPath.values());
-}
-
-export function graphPathRelativeToStorage(
-  storageDir: string,
-  candidatePath: string,
-): string | null {
-  const absolutePath = path.isAbsolute(candidatePath)
-    ? candidatePath
-    : path.resolve(storageDir, candidatePath);
-  const rel = path.relative(storageDir, absolutePath);
-  if (!rel || rel === ".") return null;
-  if (rel.startsWith("..")) return null;
-  return rel.split(path.sep).join("/");
-}
-
-function normalizeGraphActivationScore(score: number): number {
-  const bounded = Number.isFinite(score) && score > 0 ? score : 0;
-  return bounded / (1 + bounded);
-}
-
-export function blendGraphExpandedRecallScore(options: {
-  graphActivationScore: number;
-  seedRecallScore: number;
-  activationWeight: number;
-  blendMin: number;
-  blendMax: number;
-}): number {
-  const graphNorm = normalizeGraphActivationScore(options.graphActivationScore);
-  const seedScore = Number.isFinite(options.seedRecallScore)
-    ? Math.min(1, Math.max(0, options.seedRecallScore))
-    : 0;
-  const weight = Math.min(1, Math.max(0, options.activationWeight));
-  const rawMin = Math.min(1, Math.max(0, options.blendMin));
-  const rawMax = Math.min(1, Math.max(0, options.blendMax));
-  const minBound = Math.min(rawMin, rawMax);
-  const maxBound = Math.max(rawMin, rawMax);
-  const blended = graphNorm * weight + seedScore * (1 - weight);
-  return Math.max(minBound, Math.min(maxBound, blended));
-}
-
 export function summarizeGraphShadowComparison(
   baseline: QmdSearchResult[],
   merged: QmdSearchResult[],
@@ -1840,7 +1780,10 @@ export class Orchestrator {
    */
   readonly conversationIndexCoordinator: ConversationIndexCoordinator;
   readonly recallRerankCoordinator: RecallRerankCoordinator;
+  readonly recallSectionCoordinator: RecallSectionCoordinator;
   readonly qmdResultResolver: QmdResultResolver;
+  readonly contradictionLinkingCoordinator: ContradictionLinkingCoordinator;
+  readonly graphRecallCoordinator: GraphRecallCoordinator;
   private heartbeatObserverChains = new Map<string, Promise<void>>();
   private recentExtractionFingerprints = new Map<string, number>();
   private readonly consolidationObservers = new Set<
@@ -2841,7 +2784,33 @@ 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.graphRecallCoordinator = new GraphRecallCoordinator({
+      getConfig: () => this.config,
+      getStorage: () => this.storage,
+      storageFor: (namespace) => this.storageRouter.storageFor(namespace),
+      graphIndexFor: (storage) => this.graphIndexFor(storage),
+      namespaceFromPath: (p) => this.namespaceFromPath(p),
+      resolveColdQmdResultForRecall: (result, fallbackStorage, recallNamespaces) =>
+        this.resolveColdQmdResultForRecall(result, fallbackStorage, recallNamespaces),
+      storageForAbsoluteQmdResultPath: (resultPath, fallbackStorage, recallNamespaces) =>
+        this.storageForAbsoluteQmdResultPath(resultPath, fallbackStorage, recallNamespaces),
+      readQmdResultMemory: (resultPath, fallbackStorage, recallNamespaces) =>
+        this.readQmdResultMemory(resultPath, fallbackStorage, recallNamespaces),
+    });
     this.relevance = new RelevanceStore(config.memoryDir);
     this.negatives = new NegativeExampleStore(config.memoryDir);
     this.lastRecall = new LastRecallStore(config.memoryDir);
@@ -6018,12 +5987,14 @@ export class Orchestrator {
     return capped;
   }
 
+  // Issue #1526 (seam 14): graph-recall expansion moved to
+  // GraphRecallCoordinator. Thin delegation keeps the private API stable
+  // for callers (recallInternal, cold-fallback pipeline) + tests.
   private async expandResultsViaGraph(options: {
     memoryResults: QmdSearchResult[];
     recallNamespaces: string[];
     recallResultLimit: number;
     deadlineAtMs?: number | null;
-    /** Issue #681 — when true, bypass graphTraversalConfidenceFloor. */
     includeLowConfidence?: boolean;
   }): Promise<{
     merged: QmdSearchResult[];
@@ -6031,198 +6002,10 @@ export class Orchestrator {
     expandedPaths: GraphRecallExpandedEntry[];
     seedResults: QmdSearchResult[];
   }> {
-    const deadlineExpired = (): boolean =>
-      typeof options.deadlineAtMs === "number" &&
-      Date.now() >= options.deadlineAtMs;
-    const byNamespace = new Map<string, QmdSearchResult[]>();
-    const addResultForNamespace = (
-      namespace: string,
-      result: QmdSearchResult,
-    ): void => {
-      const existing = byNamespace.get(namespace);
-      if (existing) {
-        existing.push(result);
-      } else {
-        byNamespace.set(namespace, [result]);
-      }
-    };
-    const resolvedAmbiguousSeeds = new Map<
-      string,
-      { namespace: string; result: QmdSearchResult } | null
-    >();
-    const resolveAmbiguousSeedOwner = async (
-      result: QmdSearchResult,
-      parts: { collection: string; relativePath: string } | null,
-    ): Promise<{ namespace: string; result: QmdSearchResult } | null> => {
-      const cached = resolvedAmbiguousSeeds.get(result.path);
-      if (cached !== undefined) return cached;
-      if (deadlineExpired()) {
-        resolvedAmbiguousSeeds.set(result.path, null);
-        return null;
-      }
-
-      let resolvedPath = result.path;
-      let resolvedResult = result;
-      if (parts) {
-        const resolvedCold = await this.resolveColdQmdResultForRecall(
-          result,
-          this.storage,
-          options.recallNamespaces,
-        );
-        if (!resolvedCold || deadlineExpired()) {
-          resolvedAmbiguousSeeds.set(result.path, null);
-          return null;
-        }
-        resolvedPath = resolvedCold.result.path;
-        resolvedResult = resolvedCold.result;
-      }
-
-      if (!path.isAbsolute(resolvedPath)) {
-        resolvedAmbiguousSeeds.set(result.path, null);
-        return null;
-      }
-      const ownerStorage = await this.storageForAbsoluteQmdResultPath(
-        resolvedPath,
-        this.storage,
-        options.recallNamespaces,
-      );
-      const ownerNamespace = ownerStorage?.namespace ?? null;
-      const resolved =
-        ownerNamespace && options.recallNamespaces.includes(ownerNamespace)
-          ? { namespace: ownerNamespace, result: resolvedResult }
-          : null;
-      resolvedAmbiguousSeeds.set(result.path, resolved);
-      return resolved;
-    };
-    const coldCollection = this.config.qmdColdCollection ?? "openclaw-engram-cold";
-    for (const result of options.memoryResults) {
-      if (deadlineExpired()) break;
-      const parts = qmdCollectionPathParts(result.path);
-      if (parts?.collection === coldCollection) {
-        const resolved = await resolveAmbiguousSeedOwner(result, parts);
-        if (resolved) {
-          addResultForNamespace(resolved.namespace, resolved.result);
-        }
-        continue;
-      }
-      if (path.isAbsolute(result.path)) {
-        const resolved = await resolveAmbiguousSeedOwner(result, null);
-        if (resolved) {
-          addResultForNamespace(resolved.namespace, resolved.result);
-        }
-        continue;
-      }
-      const ns = this.namespaceFromPath(result.path);
-      if (!options.recallNamespaces.includes(ns)) continue;
-      addResultForNamespace(ns, result);
-    }
-
-    const perNamespaceSeedCap = Math.max(3, options.recallResultLimit);
-    const perNamespaceExpandedCap = Math.max(8, options.recallResultLimit * 2);
-    const seedPaths: string[] = [];
-    const seedResults: QmdSearchResult[] = [];
-    const expandedPaths: GraphRecallExpandedEntry[] = [];
-    const expandedResults: QmdSearchResult[] = [];
-
-    for (const [namespace, nsResults] of byNamespace.entries()) {
-      if (deadlineExpired()) break;
-      const storage = await this.storageRouter.storageFor(namespace);
-      const seedCandidates = nsResults.slice(0, perNamespaceSeedCap);
-      seedResults.push(...seedCandidates);
-      const seedRelativePaths =
-        typeof options.deadlineAtMs === "number"
-          ? await this.graphSeedPathsWithinDeadline(
-              storage,
-              seedCandidates,
-              options.deadlineAtMs,
-              [namespace],
-            )
-          : (
-              await Promise.all(
-                seedCandidates.map((result) =>
-                  this.graphSeedPathRelativeToStorage(storage, result, [
-                    namespace,
-                  ]),
-                ),
-              )
-            ).filter(
-              (value): value is string =>
-                typeof value === "string" && value.length > 0,
-            );
-      if (deadlineExpired()) break;
-      if (seedRelativePaths.length === 0) continue;
-
-      const seedRecallScore = seedCandidates.reduce(
-        (max, item) => Math.max(max, item.score),
-        0,
-      );
-      seedPaths.push(
-        ...seedRelativePaths.map((rel) => path.join(storage.dir, rel)),
-      );
-      const seedSet = new Set(seedRelativePaths);
-      const expanded = await this.graphIndexFor(storage).spreadingActivation(
-        seedRelativePaths,
-        this.config.maxGraphTraversalSteps,
-        {
-          ...(options.includeLowConfidence === true ? { includeLowConfidence: true } : {}),
-          ...(typeof options.deadlineAtMs === "number"
-            ? { deadlineAtMs: options.deadlineAtMs }
-            : {}),
-        },
-      );
-      if (expanded.length === 0) continue;
-      if (deadlineExpired()) break;
-
-      for (const candidate of expanded.slice(0, perNamespaceExpandedCap)) {
-        if (deadlineExpired()) break;
-        if (seedSet.has(candidate.path)) continue;
-        const memoryPath = path.resolve(storage.dir, candidate.path);
-        const memory = await storage.readMemoryByPath(memoryPath);
-        if (deadlineExpired()) break;
-        if (!memory) continue;
-        if (isArtifactMemoryPath(memory.path)) continue;
-        if (memory.frontmatter.status && memory.frontmatter.status !== "active")
-          continue;
-
-        const snippet = memory.content.slice(0, 400);
-        const score = blendGraphExpandedRecallScore({
-          graphActivationScore: candidate.score,
-          seedRecallScore,
-          activationWeight: this.config.graphExpansionActivationWeight,
-          blendMin: this.config.graphExpansionBlendMin,
-          blendMax: this.config.graphExpansionBlendMax,
-        });
-        expandedResults.push({
-          docid: memory.frontmatter.id,
-          path: memory.path,
-          snippet,
-          score,
-        });
-        expandedPaths.push({
-          path: memory.path,
-          score,
-          namespace,
-          seed: path.resolve(storage.dir, candidate.seed),
-          hopDepth: candidate.hopDepth,
-          decayedWeight: candidate.decayedWeight,
-          graphType: candidate.graphType,
-          // Issue #681 PR 3/3 — surface the per-edge confidence used for
-          // PageRank weighting / floor pruning so downstream observability
-          // (recall_xray, memory_graph_explain) can attribute ranking and
-          // pruning decisions to specific edges.
-          edgeConfidence: candidate.edgeConfidence,
-        });
-      }
-    }
-
-    return {
-      merged: mergeGraphExpandedResults(options.memoryResults, expandedResults),
-      seedPaths,
-      expandedPaths,
-      seedResults,
-    };
+    return this.graphRecallCoordinator.expandResultsViaGraph(options);
   }
-
+  // Issue #1526 (seam 14): graph-recall snapshot moved to
+  // GraphRecallCoordinator. Thin delegation keeps the private API stable.
   private async recordLastGraphRecallSnapshot(options: {
     storage: StorageManager;
     prompt: string;
@@ -6238,45 +6021,8 @@ export class Orchestrator {
     finalResults?: GraphRecallRankedResult[];
     shadowComparison?: GraphRecallShadowComparison;
   }): Promise<void> {
-    try {
-      const snapshotPath = path.join(
-        options.storage.dir,
-        "state",
-        "last_graph_recall.json",
-      );
-      await mkdir(path.dirname(snapshotPath), { recursive: true });
-      const now = new Date().toISOString();
-      const totalSeedCount = options.seedPaths.length;
-      const totalExpandedCount = options.expandedPaths.length;
-      const seeds = options.seedPaths.slice(0, 64);
-      const expanded = clampGraphRecallExpandedEntries(
-        options.expandedPaths,
-        64,
-      );
-      const payload = {
-        recordedAt: now,
-        mode: options.recallMode,
-        queryHash: createHash("sha256").update(options.prompt).digest("hex"),
-        queryLength: options.prompt.length,
-        namespaces: options.recallNamespaces,
-        seedCount: totalSeedCount,
-        expandedCount: totalExpandedCount,
-        seeds,
-        expanded,
-        status: options.status,
-        reason: options.reason,
-        shadowMode: options.shadowMode === true,
-        queryIntent: options.queryIntent,
-        seedResults: (options.seedResults ?? []).slice(0, 64),
-        finalResults: (options.finalResults ?? []).slice(0, 64),
-        shadowComparison: options.shadowComparison,
-      };
-      await writeFile(snapshotPath, JSON.stringify(payload, null, 2), "utf-8");
-    } catch (err) {
-      log.debug(`last graph recall write failed: ${err}`);
-    }
+    return this.graphRecallCoordinator.recordLastGraphRecallSnapshot(options);
   }
-
   private async recordLastIntentSnapshot(options: {
     storage: StorageManager;
     snapshot: IntentDebugSnapshot;
@@ -6377,52 +6123,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(
@@ -6430,104 +6170,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(
@@ -6540,89 +6201,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
@@ -16946,18 +16531,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(
@@ -16969,16 +16543,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,
+    );
   }
 
   /**
@@ -18338,99 +17906,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,
+    );
   }
 
   /**
@@ -18453,49 +17933,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,
+    );
   }
 
   // ---------------------------------------------------------------------------
@@ -18510,98 +17953,11 @@ 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,
-    recallNamespaces: readonly string[] = [],
-  ): Promise<string | null> {
-    const parts = qmdCollectionPathParts(result.path);
-    if (parts) {
-      const memory = await this.readQmdResultMemory(
-        result.path,
-        storage,
-        recallNamespaces,
-      );
-      return memory
-        ? graphPathRelativeToStorage(storage.dir, memory.path)
-        : null;
-    }
-    return graphPathRelativeToStorage(storage.dir, result.path);
-  }
-
-  private async graphSeedPathsWithinDeadline(
-    storage: StorageManager,
-    results: QmdSearchResult[],
-    deadlineAtMs: number,
-    recallNamespaces: readonly string[] = [],
-  ): Promise<string[]> {
-    const resolved: string[] = [];
-    for (const result of results) {
-      if (Date.now() >= deadlineAtMs) break;
-      const seedPath = await this.graphSeedPathRelativeToStorage(
-        storage,
-        result,
-        recallNamespaces,
-      );
-      if (Date.now() >= deadlineAtMs) break;
-      if (seedPath) resolved.push(seedPath);
-    }
-    return resolved;
   }
 
   private namespaceFromPath(p: string): string {