@remnic/core 9.3.719 → 9.3.721

package/src/orchestrator.ts

@@ -93,6 +93,7 @@ import {
   gatewayTaskChainOptions,
 } from "./fallback-llm.js";
 import { MaintenanceScheduler } from "./orchestration/maintenance.js";
+import { TierMigrationCoordinator } from "./orchestration/tier-migration-coordinator.js";
 import {
   runLiveConnectorsOnce,
   type LiveConnectorsRunSummary,
@@ -116,6 +117,9 @@ import {
   buildMemoryWorthCounterMap,
   type MemoryWorthCounters,
 } from "./memory-worth-filter.js";
+import { applyTrustScoreStage, buildTrustSignalsForRerank, projectTrustForXray } from "./trust-score-stage.js";
+import type { TrustStageResultItem } from "./trust-score-stage.js";
+import { renderEpistemicHedge, type TrustSignals } from "./trust-score.js";
 import { reorderRecallResultsWithMmr } from "./recall-mmr.js";
 import { applyReasoningTraceBoost } from "./reasoning-trace-recall.js";
 import { buildRetrievedMemoryProvenance } from "./memory-provenance.js";
@@ -1902,6 +1906,7 @@ export class Orchestrator {
   readonly lastRecall: LastRecallStore;
   readonly handleHistory: RecallHandleHistoryStore;
   readonly tierMigrationStatus: TierMigrationStatusStore;
+  readonly tierMigrationCoordinator: TierMigrationCoordinator;
   /**
    * In-memory X-ray snapshot from the most recent `recall()` call that
    * was invoked with `xrayCapture: true` (issue #570 PR 1).  Scope is
@@ -1941,6 +1946,18 @@ export class Orchestrator {
     { at: number; counters: ReadonlyMap<string, MemoryWorthCounters> }
   >();
   private static readonly MEMORY_WORTH_CACHE_TTL_MS = 30_000;
+  /**
+   * Issue #1577 — per-namespace TrustScore signal map cache. Same TTL/shape
+   * discipline as {@link memoryWorthCounterCache}: seconds-scale, evicted on
+   * every call, keyed by namespace. Holds the frontmatter-derived signals
+   * (worth, provenance, faithfulness, corroboration, recency) so the trust
+   * stage doesn't trigger a fresh `readAllMemories` scan per query.
+   */
+  private readonly trustSignalCache = new Map<
+    string,
+    { at: number; signals: ReadonlyMap<string, TrustSignals> }
+  >();
+  private static readonly TRUST_SIGNAL_CACHE_TTL_MS = 30_000;
   /**
    * Per-session workspace selections keyed by sessionKey.
    * Set by the before_agent_start hook so recall() uses the correct
@@ -2007,8 +2024,6 @@ export class Orchestrator {
   private wearablesServiceInstance: WearablesService | null = null;
   private wearablesAutoSyncHandle: { stop(): Promise<void> } | null = null;
   private lastQmdReprobeAtMs = 0;
-  private tierMigrationInFlight = false;
-  private lastTierMigrationRunAtMs = 0;
   private readonly conversationIndexLastUpdateAtMs = new Map<string, number>();
   private lastFileHygieneRunAtMs = 0;
   // Pattern-reinforcement cadence gate (issue #687 PR 2/4).  Tracks the
@@ -2833,6 +2848,14 @@ export class Orchestrator {
       maxDepth: config.recallHandleSnapshotDepth,
     });
     this.tierMigrationStatus = new TierMigrationStatusStore(config.memoryDir);
+    this.tierMigrationCoordinator = new TierMigrationCoordinator({
+      config,
+      getQmd: () => this.qmd,
+      tierMigrationStatus: this.tierMigrationStatus,
+      getUtilityRuntimeValues: () => this.utilityRuntimeValues,
+      getCompounding: () => this.compounding,
+      createColdStorage: (parentDir) => new StorageManager(parentDir),
+    });
     this.sessionObserver = new SessionObserverState({
       memoryDir: config.memoryDir,
       debounceMs: config.sessionObserverDebounceMs ?? 120_000,
@@ -7267,8 +7290,8 @@ export class Orchestrator {
     const timings: Record<string, string> = {};
     const profileTraceId = this.profiler.startTrace("recall", sessionKey, {
       qmdEnabled: this.config.qmdEnabled,
-      rerankEnabled: this.config.rerankEnabled,
-      parallelRetrieval: this.config.parallelRetrievalEnabled,
+      rerankEnabled: caps.rerank,
+      parallelRetrieval: caps.parallelRetrieval,
     });
     this.profiler.startSpan("planning", profileTraceId);
     let profileTraceClosed = false;
@@ -7374,6 +7397,23 @@ export class Orchestrator {
     // per-result explain data (e.g. reinforcementBoost) from the result that
     // was actually served.
     let xrayRecalledResults: QmdSearchResult[] = [];
+    // Issue #1577 — per-recall trust map (admitted + quarantined items).
+    // A LOCAL, not instance state, so concurrent recalls on the same
+    // orchestrator cannot race on it (review: shared-trust-map concurrency).
+    // Populated by applyTrustScoreRerank on whichever recall path runs;
+    // consumed by formatQmdResults (epistemic hedge), publishRecallResults
+    // (quarantine filtering on ALL paths), and the X-ray capture (trust
+    // projection + quarantined-item visibility — rule 34).
+    let recallTrustByPath: Map<string, TrustStageResultItem> | null = null;
+    // Issue #1577 — sink for the cold-fallback pipeline's trust map. The cold
+    // pipeline scores internally (applyColdFallbackPipeline) and writes its
+    // per-path trust map here; each cold caller reads it back into
+    // recallTrustByPath so cold/embedding/recent paths feed the same X-ray +
+    // epistemic-rendering + publisher-quarantine consumers the hot path uses
+    // (rule 41: the feature gate applies across ALL parallel recall paths).
+    const trustByPathSink: { trustByPath: Map<string, TrustStageResultItem> | null } = {
+      trustByPath: null,
+    };
     const lcmStructuredXrayResults: RecallXrayResult[] = [];
     // Per-branch pre-limit candidate pool size for the X-ray filter
     // trace (issue #570 PR 1).  `recalledMemoryCount` is assigned
@@ -8729,10 +8769,10 @@ export class Orchestrator {
       (async (): Promise<string | null> => {
         const t0 = Date.now();
         if (
-          !this.config.harmonicRetrievalEnabled ||
+          !caps.harmonicRetrieval ||
           !this.isRecallSectionEnabled(
             "harmonic-retrieval",
-            this.config.harmonicRetrievalEnabled === true,
+            caps.harmonicRetrieval,
           )
         ) {
           recordRecallSectionMetric({
@@ -9297,7 +9337,7 @@ export class Orchestrator {
           [ParallelSearchResult[], ParallelSearchResult[]]
         > | null =
           !queryAwarePrefilterIsEmpty &&
-          this.config.parallelRetrievalEnabled && maxPerAgent > 0
+          caps.parallelRetrieval && maxPerAgent > 0
             ? Promise.all([
                 shouldRunAgent("direct", retrievalQuery, 0)
                   ? Promise.all(
@@ -9386,7 +9426,7 @@ export class Orchestrator {
               : 0;
           let augmentedResults = filteredResults;
           let maxSpecializedScore = 0;
-          if (this.config.parallelRetrievalEnabled && specializedAgentPromise) {
+          if (caps.parallelRetrieval && specializedAgentPromise) {
             try {
               const [directResults, temporalResults] =
                 await specializedAgentPromise;
@@ -11032,7 +11072,7 @@ export class Orchestrator {
       );
 
       // Optional LLM reranking (default off). Fail-open if rerank fails/slow.
-      if (this.config.rerankEnabled && this.config.rerankProvider === "local") {
+      if (caps.rerank && this.config.rerankProvider === "local") {
         const ranked = await rerankLocalOrNoop({
           query: retrievalQuery,
           candidates: memoryResults
@@ -11064,24 +11104,26 @@ export class Orchestrator {
           memoryResults = reordered;
         }
       }
-      if (this.config.rerankEnabled && this.config.rerankProvider === "cloud") {
+      if (caps.rerank && this.config.rerankProvider === "cloud") {
         log.debug(
           "rerankProvider=cloud is reserved/experimental in v2.2.0; skipping rerank",
         );
       }
 
-      // Memory Worth recall filter (issue #560 PR 4). When enabled, multiply
-      // each candidate's score by its Memory Worth factor so memories with
-      // a history of failed outcomes sink. Default off in this PR; PR 5
-      // flips the default once bench shows tie-or-win. Fail-open: any
-      // lookup error leaves the original scores untouched rather than
-      // breaking recall for the whole namespace.
-      if (caps.recallMemoryWorthFilter && memoryResults.length > 0) {
-        try {
-          memoryResults = await this.applyMemoryWorthRerank(memoryResults, recallNamespaces);
-        } catch (err) {
-          log.debug("memory-worth filter failed open", { error: (err as Error).message });
-        }
+      // Trust-reweighting stage. TrustScore (issue #1577) SUBSUMES the Memory
+      // Worth multiplier — exactly one runs (rule 39; the double-multiplier
+      // test in trust-score-stage.test.ts pins it structurally). Applied on
+      // EVERY recall path via applyTrustScoreToBranch so the gate is consistent
+      // (rule 41 parity). Fail-open on lookup errors so recall never breaks.
+      {
+        const trustOutcome = await this.applyTrustScoreToBranch(
+          memoryResults,
+          recallNamespaces,
+          caps,
+          "hot-qmd",
+        );
+        memoryResults = trustOutcome.results;
+        recallTrustByPath = trustOutcome.trustByPath;
       }
 
       // Synapse-inspired confidence gate: check scores BEFORE slicing so
@@ -11198,6 +11240,7 @@ export class Orchestrator {
             injectedChars: identityInjectedChars,
             truncated: identityInjectionTruncated,
           },
+        trustByPath: recallTrustByPath,
         });
         recalledMemoryIds = this.extractMemoryIdsFromResults(memoryResults);
         recalledMemoryPaths = memoryResults
@@ -11211,7 +11254,7 @@ export class Orchestrator {
         // low-relevance results from polluting context.
         const queryAwarePrefilter = await queryAwarePrefilterPromise;
         if (queryAwarePrefilter.candidatePaths?.size !== 0) {
-        const scoped = await awaitAssemblyStep(
+        let scoped = await awaitAssemblyStep(
           "embedding-fallback",
           async () => {
             const embeddingResults = await this.searchEmbeddingFallback(
@@ -11254,6 +11297,18 @@ export class Orchestrator {
           },
           [] as QmdSearchResult[],
         );
+        // Issue #1577 — apply TrustScore on the embedding-fallback path so the
+        // feature gate is consistent across ALL recall paths (rule 41 parity).
+        {
+          const trustOutcome = await this.applyTrustScoreToBranch(
+            scoped,
+            recallNamespaces,
+            caps,
+            "embedding-fallback",
+          );
+          scoped = trustOutcome.results;
+          recallTrustByPath = trustOutcome.trustByPath;
+        }
         if (scoped.length > 0) {
           if (shouldPersistGraphSnapshot) {
             graphSnapshotFinalResults = this.buildGraphRecallRankedResults(
@@ -11274,6 +11329,7 @@ export class Orchestrator {
               injectedChars: identityInjectedChars,
               truncated: identityInjectionTruncated,
             },
+          trustByPath: recallTrustByPath,
           });
           recalledMemoryIds = this.extractMemoryIdsFromResults(scoped);
           recalledMemoryPaths = scoped
@@ -11295,10 +11351,15 @@ export class Orchestrator {
               backendDegradations.push(degradation);
             },
             xrayPoolSizeSink: xrayColdPoolSink,
+            trustByPathSink,
             deadlineAtMs: enrichmentAssemblyDeadlineAtMs,
             asOfMs,
             ...(options.includeLowConfidence === true ? { includeLowConfidence: true } : {}),
           });
+          // Issue #1577 — read the cold pipeline's trust map back so cold
+          // results feed X-ray + epistemic rendering + publisher quarantine
+          // filtering (rule 41 parity; review: the sink was never read back).
+          recallTrustByPath = trustByPathSink.trustByPath;
           if (longTerm.length > 0) {
             if (shouldPersistGraphSnapshot) {
               graphSnapshotFinalResults = this.buildGraphRecallRankedResults(
@@ -11319,6 +11380,7 @@ export class Orchestrator {
                 injectedChars: identityInjectedChars,
                 truncated: identityInjectionTruncated,
               },
+            trustByPath: recallTrustByPath,
             });
             recalledMemoryIds = this.extractMemoryIdsFromResults(longTerm);
             recalledMemoryPaths = longTerm
@@ -11335,7 +11397,7 @@ export class Orchestrator {
         this.appendRecallSection(
           sectionBuckets,
           "workspace-context",
-          this.formatQmdResults("Workspace Context", globalResults, sessionKey),
+          this.formatQmdResults("Workspace Context", globalResults, sessionKey, recallTrustByPath),
         );
       }
 
@@ -11371,7 +11433,7 @@ export class Orchestrator {
       // Fallback: embeddings first, then recency-only.
       const queryAwarePrefilter = await queryAwarePrefilterPromise;
       if (queryAwarePrefilter.candidatePaths?.size !== 0) {
-        const scoped = await awaitAssemblyStep(
+        let scoped = await awaitAssemblyStep(
           "embedding-fallback",
           async () => {
             const embeddingResults = await this.searchEmbeddingFallback(
@@ -11414,6 +11476,18 @@ export class Orchestrator {
           },
           [] as QmdSearchResult[],
         );
+        // Issue #1577 — apply TrustScore on the embedding-fallback path so the
+        // feature gate is consistent across ALL recall paths (rule 41 parity).
+        {
+          const trustOutcome = await this.applyTrustScoreToBranch(
+            scoped,
+            recallNamespaces,
+            caps,
+            "embedding-fallback",
+          );
+          scoped = trustOutcome.results;
+          recallTrustByPath = trustOutcome.trustByPath;
+        }
       if (scoped.length > 0) {
         if (shouldPersistGraphSnapshot) {
           graphSnapshotFinalResults = this.buildGraphRecallRankedResults(
@@ -11434,6 +11508,7 @@ export class Orchestrator {
             injectedChars: identityInjectedChars,
             truncated: identityInjectionTruncated,
           },
+        trustByPath: recallTrustByPath,
         });
         recalledMemoryIds = this.extractMemoryIdsFromResults(scoped);
         recalledMemoryPaths = scoped
@@ -11523,10 +11598,13 @@ export class Orchestrator {
                 backendDegradations.push(degradation);
               },
               xrayPoolSizeSink: xrayColdPoolSink,
+              trustByPathSink,
               deadlineAtMs: enrichmentAssemblyDeadlineAtMs,
               asOfMs,
               ...(options.includeLowConfidence === true ? { includeLowConfidence: true } : {}),
             });
+            // Issue #1577 — read the cold pipeline's trust map back (rule 41).
+            recallTrustByPath = trustByPathSink.trustByPath;
             if (longTerm.length > 0) {
               recallSource = "cold_fallback";
               recalledMemoryCount = longTerm.length;
@@ -11541,6 +11619,7 @@ export class Orchestrator {
                   injectedChars: identityInjectedChars,
                   truncated: identityInjectionTruncated,
                 },
+              trustByPath: recallTrustByPath,
               });
               recalledMemoryIds = this.extractMemoryIdsFromResults(longTerm);
               recalledMemoryPaths = longTerm
@@ -11550,7 +11629,7 @@ export class Orchestrator {
               impressionRecorded = true;
             }
           } else {
-            const recent = await awaitAssemblyStep(
+            let recent = await awaitAssemblyStep(
               "recent-memory-scan",
               async () => {
                 const recentSorted = queryAwareScopedMemories.sort(
@@ -11596,6 +11675,18 @@ export class Orchestrator {
               },
               [] as QmdSearchResult[],
             );
+            // Issue #1577 — apply TrustScore on the recent-scan path so the
+            // feature gate is consistent across ALL recall paths (rule 41).
+            {
+              const trustOutcome = await this.applyTrustScoreToBranch(
+                recent,
+                recallNamespaces,
+                caps,
+                "recent-scan",
+              );
+              recent = trustOutcome.results;
+              recallTrustByPath = trustOutcome.trustByPath;
+            }
 
             if (recent.length > 0) {
               if (shouldPersistGraphSnapshot) {
@@ -11617,6 +11708,7 @@ export class Orchestrator {
                   injectedChars: identityInjectedChars,
                   truncated: identityInjectionTruncated,
                 },
+              trustByPath: recallTrustByPath,
               });
               recalledMemoryIds = this.extractMemoryIdsFromResults(recent);
               recalledMemoryPaths = recent
@@ -11638,10 +11730,13 @@ export class Orchestrator {
                   backendDegradations.push(degradation);
                 },
                 xrayPoolSizeSink: xrayColdPoolSink,
+                trustByPathSink,
                 deadlineAtMs: enrichmentAssemblyDeadlineAtMs,
                 asOfMs,
                 ...(options.includeLowConfidence === true ? { includeLowConfidence: true } : {}),
               });
+              // Issue #1577 — read the cold pipeline's trust map back (rule 41).
+              recallTrustByPath = trustByPathSink.trustByPath;
               if (longTerm.length > 0) {
                 if (shouldPersistGraphSnapshot) {
                   graphSnapshotFinalResults =
@@ -11663,6 +11758,7 @@ export class Orchestrator {
                     injectedChars: identityInjectedChars,
                     truncated: identityInjectionTruncated,
                   },
+                trustByPath: recallTrustByPath,
                 });
                 recalledMemoryIds = this.extractMemoryIdsFromResults(longTerm);
                 recalledMemoryPaths = longTerm
@@ -11687,10 +11783,13 @@ export class Orchestrator {
               backendDegradations.push(degradation);
             },
             xrayPoolSizeSink: xrayColdPoolSink,
+            trustByPathSink,
             deadlineAtMs: enrichmentAssemblyDeadlineAtMs,
             asOfMs,
             ...(options.includeLowConfidence === true ? { includeLowConfidence: true } : {}),
           });
+          // Issue #1577 — read the cold pipeline's trust map back (rule 41).
+          recallTrustByPath = trustByPathSink.trustByPath;
           if (longTerm.length > 0) {
             if (shouldPersistGraphSnapshot) {
               graphSnapshotFinalResults = this.buildGraphRecallRankedResults(
@@ -11711,6 +11810,7 @@ export class Orchestrator {
                 injectedChars: identityInjectedChars,
                 truncated: identityInjectionTruncated,
               },
+            trustByPath: recallTrustByPath,
             });
             recalledMemoryIds = this.extractMemoryIdsFromResults(longTerm);
             recalledMemoryPaths = longTerm
@@ -11981,6 +12081,7 @@ export class Orchestrator {
             // X-ray capture is best-effort; missing provenance must not
             // perturb recall or suppress the surfaced result.
           }
+          const trustItem = recallTrustByPath?.get(recalledPath);
           results.push({
             memoryId: derivedId,
             path: recalledPath,
@@ -11989,8 +12090,30 @@ export class Orchestrator {
             admittedBy: [],
             ...(provenance ? { provenance } : {}),
             ...(sourceSpan ? { sourceSpan } : {}),
+            // Issue #1577 — per-result trust projection for X-ray visibility.
+            ...(trustItem ? { trust: projectTrustForXray(trustItem) } : {}),
           });
         }
+        // Issue #1577 — surface quarantined items in X-ray with their exclusion
+        // reason so operators see WHY a memory was dropped (rule 34 — exclusion
+        // must never look like "no result"). These are NOT in recalledMemoryPaths
+        // (they were excluded from injection) but ARE in the trust map.
+        if (recallTrustByPath) {
+          for (const [qPath, qItem] of recallTrustByPath) {
+            if (!qItem.quarantined || recalledMemoryPaths.includes(qPath)) continue;
+            const qId = idFromPath(qPath);
+            if (!qId) continue;
+            results.push({
+              memoryId: qId,
+              path: qPath,
+              servedBy,
+              scoreDecomposition: { final: 0 },
+              admittedBy: [],
+              rejectedBy: "trust-score:quarantine",
+              trust: projectTrustForXray(qItem),
+            });
+          }
+        }
         // `considered` must reflect the pool size of the branch that
         // actually produced the admitted results, NOT the max across
         // every branch that ran.  Otherwise a flow where hot_qmd
@@ -13751,192 +13874,7 @@ export class Orchestrator {
       force?: boolean;
     },
   ): Promise<TierMigrationCycleSummary> {
-    const dryRun = options?.dryRun === true;
-    const persistSkipped = options?.force === true || trigger === "manual";
-    if (!this.config.qmdTierMigrationEnabled && options?.force !== true) {
-      const skipped: TierMigrationCycleSummary = {
-        trigger,
-        scanned: 0,
-        migrated: 0,
-        promoted: 0,
-        demoted: 0,
-        limit: 0,
-        dryRun,
-        skipped: "tier_migration_disabled",
-      };
-      if (persistSkipped) await this.tierMigrationStatus.recordCycle(skipped);
-      return skipped;
-    }
-    if (
-      trigger === "maintenance" &&
-      !this.config.qmdTierAutoBackfillEnabled &&
-      options?.force !== true
-    ) {
-      const skipped: TierMigrationCycleSummary = {
-        trigger,
-        scanned: 0,
-        migrated: 0,
-        promoted: 0,
-        demoted: 0,
-        limit: 0,
-        dryRun,
-        skipped: "maintenance_backfill_disabled",
-      };
-      if (persistSkipped) await this.tierMigrationStatus.recordCycle(skipped);
-      return skipped;
-    }
-    if (this.tierMigrationInFlight) {
-      const skipped: TierMigrationCycleSummary = {
-        trigger,
-        scanned: 0,
-        migrated: 0,
-        promoted: 0,
-        demoted: 0,
-        limit: 0,
-        dryRun,
-        skipped: "migration_in_flight",
-      };
-      if (persistSkipped) await this.tierMigrationStatus.recordCycle(skipped);
-      return skipped;
-    }
-
-    const budgetTrigger = trigger === "manual" ? "maintenance" : trigger;
-    const budget =
-      this.compounding?.tierMigrationCycleBudget(budgetTrigger) ??
-      defaultTierMigrationCycleBudget(this.config, budgetTrigger);
-    const limit =
-      options?.limitOverride !== undefined
-        ? Math.max(0, Math.floor(options.limitOverride))
-        : budget.limit;
-    const nowMs = Date.now();
-    if (
-      options?.force !== true &&
-      nowMs - this.lastTierMigrationRunAtMs < budget.minIntervalMs
-    ) {
-      const skipped: TierMigrationCycleSummary = {
-        trigger,
-        scanned: 0,
-        migrated: 0,
-        promoted: 0,
-        demoted: 0,
-        limit,
-        dryRun,
-        skipped: "min_interval",
-      };
-      if (persistSkipped) await this.tierMigrationStatus.recordCycle(skipped);
-      return skipped;
-    }
-
-    const policy = applyUtilityPromotionRuntimePolicy(
-      {
-        enabled: this.config.qmdTierMigrationEnabled,
-        demotionMinAgeDays: this.config.qmdTierDemotionMinAgeDays,
-        demotionValueThreshold: this.config.qmdTierDemotionValueThreshold,
-        promotionValueThreshold: this.config.qmdTierPromotionValueThreshold,
-      },
-      this.utilityRuntimeValues,
-    );
-
-    this.tierMigrationInFlight = true;
-    try {
-      const coldStorage = new StorageManager(path.join(storage.dir, "cold"));
-      const [hotMemories, coldMemories] = await Promise.all([
-        storage.readAllMemories(),
-        coldStorage.readAllMemories(),
-      ]);
-      const now = new Date();
-      const scanLimit = Math.max(0, Math.floor(budget.scanLimit));
-      const hotScanLimit = Math.min(
-        hotMemories.length,
-        Math.ceil(scanLimit * 0.75),
-      );
-      const coldScanLimit = Math.min(
-        coldMemories.length,
-        Math.max(0, scanLimit - hotScanLimit),
-      );
-      const toTimestamp = (memory: MemoryFile): number =>
-        Date.parse(memory.frontmatter.updated ?? memory.frontmatter.created);
-      const hotCandidates = hotMemories
-        .map((memory) => ({ memory, tier: "hot" as MemoryTier }))
-        .sort((a, b) => toTimestamp(a.memory) - toTimestamp(b.memory))
-        .slice(0, hotScanLimit);
-      const coldCandidates = coldMemories
-        .map((memory) => ({ memory, tier: "cold" as MemoryTier }))
-        .sort((a, b) => toTimestamp(b.memory) - toTimestamp(a.memory))
-        .slice(0, coldScanLimit);
-      const candidates = [...hotCandidates, ...coldCandidates];
-
-      const migration = new TierMigrationExecutor({
-        storage,
-        qmd: this.qmd,
-        hotCollection: this.config.qmdCollection,
-        coldCollection:
-          this.config.qmdColdCollection ?? `${this.config.qmdCollection}-cold`,
-        autoEmbed: this.config.qmdAutoEmbedEnabled,
-      });
-
-      let migrated = 0;
-      let promoted = 0;
-      let demoted = 0;
-      for (const candidate of candidates) {
-        if (migrated >= limit) break;
-        const decision = decideTierTransition(
-          candidate.memory,
-          candidate.tier,
-          policy,
-          now,
-        );
-        if (!decision.changed) continue;
-
-        if (!dryRun) {
-          const res = await migration.migrateMemory({
-            memory: candidate.memory,
-            fromTier: candidate.tier,
-            toTier: decision.nextTier,
-            reason: `${trigger}:${decision.reason}`,
-          });
-          if (!res.changed) continue;
-        }
-        migrated += 1;
-        if (decision.nextTier === "cold") demoted += 1;
-        if (decision.nextTier === "hot") promoted += 1;
-      }
-
-      if (!dryRun) this.lastTierMigrationRunAtMs = Date.now();
-      log.debug(
-        `tier migration cycle completed: trigger=${trigger} scanned=${candidates.length} migrated=${migrated} limit=${limit}${dryRun ? " dryRun=true" : ""}`,
-      );
-      const summary: TierMigrationCycleSummary = {
-        trigger,
-        scanned: candidates.length,
-        migrated,
-        promoted,
-        demoted,
-        limit,
-        dryRun,
-      };
-      const shouldPersistCycle = trigger === "manual" || migrated > 0;
-      if (shouldPersistCycle)
-        await this.tierMigrationStatus.recordCycle(summary);
-      return summary;
-    } catch (err) {
-      this.lastTierMigrationRunAtMs = Date.now();
-      log.warn(`tier migration cycle failed (${trigger}, fail-open): ${err}`);
-      const failed: TierMigrationCycleSummary = {
-        trigger,
-        scanned: 0,
-        migrated: 0,
-        promoted: 0,
-        demoted: 0,
-        limit,
-        dryRun,
-        errorCount: 1,
-      };
-      await this.tierMigrationStatus.recordCycle(failed);
-      return failed;
-    } finally {
-      this.tierMigrationInFlight = false;
-    }
+    return this.tierMigrationCoordinator.runCycle(storage, trigger, options);
   }
 
   async getTierMigrationStatus(): Promise<TierMigrationStatusSnapshot> {
@@ -16283,6 +16221,7 @@ export class Orchestrator {
     storage: StorageManager,
     persistedIds: string[],
   ): Promise<void> {
+    const caps = resolveCapabilities(this.config); // #1566 Cluster C
     // Build temporal/tag indexes whenever either consumer is enabled:
     // - queryAwareIndexingEnabled: uses indexes for query-aware prefiltering in recall
     // - parallelRetrievalEnabled: temporal agent reads index_time.json for date-range lookup
@@ -16290,7 +16229,7 @@ export class Orchestrator {
     // produce an empty temporal index, leaving the temporal agent with no data to work from.
     if (
       !this.config.queryAwareIndexingEnabled &&
-      !this.config.parallelRetrievalEnabled
+      !caps.parallelRetrieval
     )
       return;
     // Check for missing indexes BEFORE the early-return so first-time enablement
@@ -17719,6 +17658,7 @@ export class Orchestrator {
     title: string,
     results: QmdSearchResult[],
     sessionKey?: string,
+    trustByPath?: Map<string, TrustStageResultItem> | null,
   ): string {
     // Issue #1582 — handles are only rendered when a session key is available:
     // resolution requires the handle history to have been recorded for this
@@ -17729,6 +17669,13 @@ export class Orchestrator {
       results,
       this.config.recallMemoryHandles === true && sessionKey != null,
     );
+    // Issue #1577 — epistemic hedge. Append a deterministic, component-derived
+    // suffix so the downstream model knows each memory's trust status (the
+    // cheap lever against confident-stale-answer failures). Gated separately
+    // from scoring so rendering can ship after the stage is stable. High-band
+    // and neutral items get no suffix (don't waste tokens on the common case).
+    const renderHedge = this.config.trustScoreEpistemicRendering && trustByPath !== null && trustByPath !== undefined;
+    const hedgeMap = renderHedge ? trustByPath : null;
     const lines = results.map((r, i) => {
       const snippet = r.snippet
         ? r.snippet.slice(0, 500).replace(/\n/g, " ")
@@ -17736,7 +17683,16 @@ export class Orchestrator {
       const source = typeof r.line === "number" ? `${r.path}:${r.line}` : r.path;
       const head = `[${i + 1}] ${source} (score: ${r.score.toFixed(3)})\n${snippet}`;
       const handle = handleByIndex.get(i);
-      return handle ? `${head.replace(/\s+$/, "")} ${handle}` : head;
+      const hedged = head.replace(/\s+$/, "");
+      const withHandle = handle ? `${hedged} ${handle}` : hedged;
+      if (hedgeMap) {
+        const item = hedgeMap.get(r.path);
+        if (item) {
+          const hedge = renderEpistemicHedge(item.trust);
+          if (hedge.length > 0) return `${withHandle} ${hedge}`;
+        }
+      }
+      return withHandle;
     });
     return `## ${title}\n\n${lines.join("\n\n")}`;
   }
@@ -18093,15 +18049,30 @@ export class Orchestrator {
       injectedChars: number;
       truncated: boolean;
     };
+    /**
+     * Issue #1577 — per-recall trust map. When present, quarantined items
+     * are filtered from injection on EVERY recall path (hot QMD, embedding
+     * fallback, cold archive, recent) so a faithfulness-contradicted memory
+     * cannot sneak in via a branch that bypasses trust scoring (review:
+     * fallback paths bypass trust). The map is also threaded to
+     * formatQmdResults for the epistemic hedge.
+     */
+    trustByPath?: Map<string, TrustStageResultItem> | null;
   }): void {
     const sectionId = "memories";
-    const memoryIds = this.extractMemoryIdsFromResults(options.results);
+    // Filter quarantined items from ALL recall paths so no branch can inject
+    // a hard-negative memory that trust scoring excluded on another path.
+    const trustByPath = options.trustByPath ?? null;
+    const injectable = trustByPath
+      ? options.results.filter((r) => !trustByPath.get(r.path)?.quarantined)
+      : options.results;
+    const memoryIds = this.extractMemoryIdsFromResults(injectable);
     this.trackMemoryAccess(memoryIds);
 
     this.appendRecallSection(
       options.sectionBuckets,
       sectionId,
-      this.formatQmdResults(options.title, options.results, options.sessionKey),
+      this.formatQmdResults(options.title, injectable, options.sessionKey, trustByPath),
     );
   }
 
@@ -18522,6 +18493,125 @@ export class Orchestrator {
     return reordered;
   }
 
+  /**
+   * Issue #1577 — unified TrustScore recall stage. Thin wiring over the pure
+   * {@link applyTrustScoreStage} scorer + the {@link buildTrustSignalsForRerank}
+   * signal builder. The stage subsumes the Memory Worth multiplier — the
+   * orchestrator runs exactly one of the two (mutual exclusion, rule 39; the
+   * double-multiplier test in trust-score-stage.test.ts pins it structurally).
+   *
+   * Returns the admitted results AND the per-path trust map (including
+   * quarantined items) so the caller can: (a) render epistemic hedges, (b)
+   * surface quarantined items in X-ray with a reason (rule 34), and (c) filter
+   * quarantined paths from fallback recall branches. The trust map is a
+   * per-recall local — never instance state — so concurrent recalls cannot
+   * race on it (review: shared-trust-map concurrency).
+   */
+  private async applyTrustScoreRerank(
+    results: QmdSearchResult[],
+    namespaces: string[],
+  ): Promise<{
+    results: QmdSearchResult[];
+    trustByPath: Map<string, TrustStageResultItem> | null;
+  }> {
+    if (results.length === 0) return { results, trustByPath: null };
+    const now = new Date();
+    const halfLifeDays =
+      this.config.recallMemoryWorthHalfLifeMs > 0
+        ? this.config.recallMemoryWorthHalfLifeMs / (24 * 60 * 60 * 1000)
+        : undefined;
+    // Cold-tier direct-fallback reader: resolve once, reuse for every missing
+    // candidate (mirrors the memory-worth filter's reader selection).
+    let fallbackReader: StorageManager | null = null;
+    const signals = await buildTrustSignalsForRerank(
+      results.map((r) => r.path),
+      namespaces,
+      {
+        readNamespaceMemories: async (ns) => (await this.getStorage(ns)).readAllMemories(),
+        readMemoryFrontmatter: async (path) => {
+          if (!fallbackReader) {
+            for (const ns of namespaces) {
+              try {
+                fallbackReader = await this.getStorage(ns);
+                break;
+              } catch {
+                // try next namespace
+              }
+            }
+          }
+          if (!fallbackReader) return null;
+          const memory = await this.readQmdResultMemory(path, fallbackReader, namespaces);
+          return memory ? memory.frontmatter : null;
+        },
+      },
+      { cache: this.trustSignalCache, ttlMs: Orchestrator.TRUST_SIGNAL_CACHE_TTL_MS },
+      now,
+      {
+        recencyHalfLifeDays: halfLifeDays,
+        logDebug: (message, context) => log.debug(message, context),
+      },
+    );
+    if (signals.size === 0) {
+      return { results, trustByPath: null };
+    }
+    // Synthetic monotone-decreasing rank so the multiplier rebias is applied
+    // on top of upstream ordering, not raw QMD scores (see applyMemoryWorthRerank).
+    const rankedInputs = results.map((r, i) => ({ path: r.path, score: results.length - i }));
+    const stage = applyTrustScoreStage(rankedInputs, {
+      signals,
+      weights: this.config.trustScoreWeights,
+      minMultiplier: this.config.trustScoreMinMultiplier,
+      maxMultiplier: this.config.trustScoreMaxMultiplier,
+      quarantine: this.config.trustScoreQuarantine,
+    });
+    const trustByPath = new Map(stage.all.map((item) => [item.path, item]));
+    const byPath = new Map(results.map((r) => [r.path, r]));
+    const admitted = stage.admitted
+      .map((item) => byPath.get(item.path))
+      .filter((r): r is QmdSearchResult => r !== undefined);
+    return { results: admitted, trustByPath };
+  }
+
+  /**
+   * Issue #1577 — apply the TrustScore stage (or, when trust is off, the Memory
+   * Worth multiplier fallback) to ONE recall branch's results, returning the
+   * scored results + the per-path trust map. Thin wiring over
+   * {@link applyTrustScoreRerank} so every recall path — hot QMD, embedding
+   * fallback, recent scan — applies the SAME multiplier gate (rule 41: a
+   * feature gate must apply across ALL parallel recall paths). TrustScore
+   * subsumes Memory Worth; exactly one runs (rule 39). Fail-open on lookup
+   * errors so a storage hiccup never breaks a fallback path.
+   */
+  private async applyTrustScoreToBranch(
+    results: QmdSearchResult[],
+    namespaces: string[],
+    caps: CapabilitySet,
+    label: string,
+  ): Promise<{
+    results: QmdSearchResult[];
+    trustByPath: Map<string, TrustStageResultItem> | null;
+  }> {
+    if (caps.recallTrustScore && results.length > 0) {
+      try {
+        return await this.applyTrustScoreRerank(results, namespaces);
+      } catch (err) {
+        log.debug(`trust-score stage (${label}) failed open`, {
+          error: (err as Error).message,
+        });
+      }
+    } else if (caps.recallMemoryWorthFilter && results.length > 0) {
+      try {
+        const filtered = await this.applyMemoryWorthRerank(results, namespaces);
+        return { results: filtered, trustByPath: null };
+      } catch (err) {
+        log.debug(`memory-worth filter (${label}) failed open`, {
+          error: (err as Error).message,
+        });
+      }
+    }
+    return { results, trustByPath: null };
+  }
+
   private diversifyAndLimitRecallResults(
     sectionId: string,
     results: QmdSearchResult[],
@@ -18896,6 +18986,14 @@ export class Orchestrator {
      * Unset by default so existing call sites are unaffected.
      */
     xrayPoolSizeSink?: { size: number };
+    /**
+     * Issue #1577 — out-parameter that receives the TrustScore stage's
+     * per-path trust map (admitted + quarantined) when the cold path runs
+     * trust scoring. Mirrors the xrayPoolSizeSink pattern so recallInternal
+     can propagate trust data for epistemic rendering and X-ray visibility
+     without changing the cold pipeline's return type.
+     */
+    trustByPathSink?: { trustByPath: Map<string, TrustStageResultItem> | null };
     deadlineAtMs?: number | null;
     /** Issue #681 — when true, bypass graphTraversalConfidenceFloor. */
     includeLowConfidence?: boolean;
@@ -19201,7 +19299,7 @@ export class Orchestrator {
       log.debug("cold-tier recall boost skipped: shared assembly deadline already expired");
     }
 
-    if (this.config.rerankEnabled && this.config.rerankProvider === "local") {
+    if (caps.rerank && this.config.rerankProvider === "local") {
       const ranked = await rerankLocalOrNoop({
         query: options.prompt,
         candidates: results
@@ -19232,16 +19330,27 @@ export class Orchestrator {
         results = reordered;
       }
     }
-    if (this.config.rerankEnabled && this.config.rerankProvider === "cloud") {
+    if (caps.rerank && this.config.rerankProvider === "cloud") {
       log.debug(
         "rerankProvider=cloud is reserved/experimental in v2.2.0; skipping rerank",
       );
     }
 
-    // Memory Worth filter — must fire on the cold fallback path too, or the
-    // feature flag produces divergent behavior by retrieval path (CLAUDE.md
-    // rule 39). Fail-open on lookup errors.
-    if (caps.recallMemoryWorthFilter && results.length > 0) {
+    // Trust-reweighting — must fire on the cold fallback path too, or the
+    // feature flag produces divergent behavior by retrieval path (rule 39).
+    // TrustScore subsumes the Memory Worth multiplier; run exactly one.
+    // Fail-open on lookup errors.
+    if (caps.recallTrustScore && results.length > 0) {
+      try {
+        const trustOutcome = await this.applyTrustScoreRerank(results, options.recallNamespaces);
+        results = trustOutcome.results;
+        if (options.trustByPathSink) options.trustByPathSink.trustByPath = trustOutcome.trustByPath;
+      } catch (err) {
+        log.debug("trust-score stage (cold) failed open", {
+          error: (err as Error).message,
+        });
+      }
+    } else if (caps.recallMemoryWorthFilter && results.length > 0) {
       try {
         results = await this.applyMemoryWorthRerank(results, options.recallNamespaces);
       } catch (err) {