@remnic/core 9.3.742 → 9.3.743

package/src/orchestrator.ts

@@ -104,7 +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,
@@ -1840,7 +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<
@@ -2841,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);
@@ -6377,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(
@@ -6430,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(
@@ -6540,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") });
-    }
+    return this.recallSectionCoordinator.assembleRecallSections(
+      sectionBuckets,
+      budgetOverride,
+    );
+  }
 
-    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;
-
-    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 +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(
@@ -16969,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,
+    );
   }
 
   /**
@@ -18338,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,
+    );
   }
 
   /**
@@ -18453,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,
+    );
   }
 
   // ---------------------------------------------------------------------------
@@ -18510,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,