@remnic/core 9.3.742 → 9.3.744

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

@@ -0,0 +1,336 @@
+/**
+ * Contradiction-linking coordinator — extracted from the orchestrator (issue #1526).
+ *
+ * Owns the write-path semantic-analysis subsystem: contradiction detection
+ * (QMD similarity search + LLM verification), deferred contradiction
+ * auto-resolve (#1645 — retires superseded memories only after the new write's
+ * tombstone status is known), and memory link suggestion. Behavior-preserving
+ * move from orchestrator.ts — no logic changes; the orchestrator constructs one
+ * instance and keeps thin delegating methods so existing call sites (writeMemory
+ * fact-write branches) continue to work.
+ *
+ * Config, storage, search, namespace resolution, and the extraction engine are
+ * accessed through getter callbacks (not captured at construction) so that
+ * post-construction reassignment of the orchestrator's live fields is honored.
+ * This mirrors the RecallRerankCoordinator / ConversationIndexCoordinator
+ * accessor pattern.
+ */
+
+import type {
+  MemoryLink,
+  PluginConfig,
+  QmdSearchResult,
+} from "../types.js";
+// StorageManager type comes from the package barrel (type-only) so this
+// module does not add a direct storage.ts import (ratchet #1533).
+import type { StorageManager } from "../index.js";
+import type { ExtractionEngine } from "../extraction.js";
+import { log } from "../logger.js";
+import { resolveIndexingCapabilities } from "../capabilities.js";
+import { deindexMemory } from "../temporal-index.js";
+
+/** Result type of {@link ContradictionLinkingCoordinator.checkForContradiction}. */
+export interface ContradictionResult {
+  supersededId: string;
+  confidence: number;
+  reason: string;
+  supersededPath: string;
+  supersededCreated: string;
+  supersededTags: string[];
+}
+
+/**
+ * Subset of {@link ContradictionResult} used by
+ * {@link ContradictionLinkingCoordinator.applyDeferredContradictionResolve}.
+ * The deferred resolve runs AFTER writeMemory and only needs the supersede
+ * target fields (not confidence, which the caller already consumed).
+ */
+export interface ContradictionResolveTarget {
+  supersededId: string;
+  reason: string;
+  supersededPath: string;
+  supersededCreated: string;
+  supersededTags: string[];
+}
+
+/**
+ * Coordinator for the contradiction-detection + memory-linking subsystem.
+ *
+ * The three methods mirror the orchestrator's former private methods
+ * `checkForContradiction`, `applyDeferredContradictionResolve`, and
+ * `suggestLinksForMemory` byte-for-byte in logic.
+ */
+export class ContradictionLinkingCoordinator {
+  private readonly getConfig: () => PluginConfig;
+  private readonly isSearchAvailable: () => boolean;
+  private readonly searchAcrossNamespaces: (options: {
+    query: string;
+    namespaces?: string[];
+    maxResults?: number;
+    mode?: "search" | "hybrid" | "bm25" | "vector";
+  }) => Promise<QmdSearchResult[]>;
+  private readonly extractMemoryIdsFromResults: (
+    results: QmdSearchResult[],
+  ) => string[];
+  private readonly namespaceFromPath: (p: string) => string;
+  private readonly storageForNamespace: (
+    namespace: string,
+  ) => Promise<StorageManager>;
+  private readonly getExtraction: () => ExtractionEngine;
+
+  constructor(options: {
+    getConfig: () => PluginConfig;
+    isSearchAvailable: () => boolean;
+    searchAcrossNamespaces: (options: {
+      query: string;
+      namespaces?: string[];
+      maxResults?: number;
+      mode?: "search" | "hybrid" | "bm25" | "vector";
+    }) => Promise<QmdSearchResult[]>;
+    extractMemoryIdsFromResults: (results: QmdSearchResult[]) => string[];
+    namespaceFromPath: (p: string) => string;
+    storageForNamespace: (namespace: string) => Promise<StorageManager>;
+    getExtraction: () => ExtractionEngine;
+  }) {
+    this.getConfig = options.getConfig;
+    this.isSearchAvailable = options.isSearchAvailable;
+    this.searchAcrossNamespaces = options.searchAcrossNamespaces;
+    this.extractMemoryIdsFromResults = options.extractMemoryIdsFromResults;
+    this.namespaceFromPath = options.namespaceFromPath;
+    this.storageForNamespace = options.storageForNamespace;
+    this.getExtraction = options.getExtraction;
+  }
+
+  /**
+   * Check if a new memory contradicts an existing one.
+   * Uses QMD to find similar memories, then LLM to verify contradiction.
+   */
+  async checkForContradiction(
+    content: string,
+    category: string,
+    namespaceScope: string,
+  ): Promise<ContradictionResult | null> {
+    if (!this.isSearchAvailable()) return null;
+
+    const config = this.getConfig();
+
+    // 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 < 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.storageForNamespace(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 extraction = this.getExtraction();
+      const verification = await 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 >= 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${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;
+  }
+
+  /**
+   * #1645: Complete the deferred contradiction auto-resolve after writeMemory
+   * returns and the new write's tombstone status is known. Retires the old
+   * memory + deindexes it ONLY when the new write is genuinely active (not
+   * tombstone-blocked / pending_review). A blocked write must not retire the
+   * only active copy — deferring here closes the "contradictionAutoResolve
+   * supersedes before tombstone status is known" defect class.
+   */
+  async applyDeferredContradictionResolve(
+    contradiction: ContradictionResolveTarget | null | undefined,
+    storage: StorageManager,
+    newMemoryId: string,
+    postWriteGuard: boolean,
+  ): Promise<void> {
+    const config = this.getConfig();
+    // #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 && 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 ||
+      !config.contradictionAutoResolve ||
+      postWriteGuard
+    ) {
+      return;
+    }
+    try {
+      await storage.supersedeMemory(
+        contradiction.supersededId,
+        newMemoryId,
+        contradiction.reason,
+      );
+      if (
+        resolveIndexingCapabilities(config).queryAwareIndexing &&
+        contradiction.supersededPath
+      ) {
+        deindexMemory(
+          config.memoryDir,
+          contradiction.supersededPath,
+          contradiction.supersededCreated,
+          contradiction.supersededTags,
+        );
+      }
+    } catch (err) {
+      log.warn(
+        `contradiction auto-resolve supersede failed for ${contradiction.supersededId}: ${err}`,
+      );
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Memory Linking (Phase 3A)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Suggest links for a new memory based on similar existing memories.
+   */
+  async suggestLinksForMemory(
+    content: string,
+    category: string,
+    namespaceScope: string,
+  ): Promise<MemoryLink[]> {
+    if (!this.isSearchAvailable()) 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.storageForNamespace(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 extraction = this.getExtraction();
+    const suggestions = await extraction.suggestLinks(
+      { content, category },
+      candidates,
+    );
+
+    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,
+    }));
+  }
+}