@remnic/core 9.69.32 → 9.69.34

package/src/orchestration/harmonic-construction-persist.test.ts

@@ -1,10 +1,14 @@
 import assert from "node:assert/strict";
 import { test } from "node:test";
 import type { StorageManager } from "../index.js";
+import type { MemoryFile } from "../types.js";
 import { deriveHarmonicRecords, type HarmonicConstructionInput } from "../harmonic-construction.js";
 import { enqueueMergedTargetForHarmonicConstruction } from "./harmonic-construction-persist.js";
 
-const storage = { dir: "/tmp/remnic-harmonic-coalesce" } as StorageManager;
+const storage = {
+  dir: "/tmp/remnic-harmonic-coalesce",
+  getMemoryByIdIncludingArchived: async () => null,
+} as unknown as StorageManager;
 
 function fact(cueAnchors: NonNullable<HarmonicConstructionInput["persistedFacts"][number]["cueAnchors"]>) {
   return {
@@ -15,12 +19,13 @@ function fact(cueAnchors: NonNullable<HarmonicConstructionInput["persistedFacts"
   };
 }
 
-test("two merges into one target coalesce to one harmonic entry: final body, unioned anchors (round N+9 C)", () => {
+
+test("two merges into one target coalesce to one harmonic entry: final body, unioned anchors (round N+9 C)", async () => {
   const map = new Map<string, {
     storage: StorageManager;
     facts: HarmonicConstructionInput["persistedFacts"];
   }>();
-  enqueueMergedTargetForHarmonicConstruction(
+  await enqueueMergedTargetForHarmonicConstruction(
     map,
     storage,
     fact([{ type: "tool", value: "atlas release workflow" }]),
@@ -28,7 +33,7 @@ test("two merges into one target coalesce to one harmonic entry: final body, uni
     "first cumulative body",
     "2026-08-22T10:00:00.000Z",
   );
-  enqueueMergedTargetForHarmonicConstruction(
+  await enqueueMergedTargetForHarmonicConstruction(
     map,
     storage,
     fact([{ type: "entity", value: "Atlas PostgreSQL" }]),
@@ -67,3 +72,109 @@ test("two merges into one target coalesce to one harmonic entry: final body, uni
     "anchors from both merges reach the persisted anchor set",
   );
 });
+
+test("a merged target's harmonic entry carries the committed record's entityRef and tags (#2807)", async () => {
+  // The parity gate lets an incoming fact with NO entityRef merge into a
+  // target that HAS one (only a differing non-undefined incoming entity
+  // refuses), and incoming tags are a subset of the target's. The enqueue
+  // used to stamp the incoming fact's fields onto the merged entry, so the
+  // episode held the cumulative body while missing the target's committed
+  // entity association and extra tags — and deriveHarmonicRecords skipped
+  // the deterministic entity cue/topic linkage for the merged claims.
+  const MERGED_BODY = "Billing service deploys run on Tuesdays at 09:00 UTC.";
+  const committed: MemoryFile = {
+    path: "/tmp/remnic-harmonic-merged/facts/2026-08-22/fact-target.md",
+    frontmatter: {
+      id: "fact-target",
+      category: "fact",
+      entityRef: "billing-service",
+      tags: ["deploy", "infra"],
+    } as unknown as MemoryFile["frontmatter"],
+    content: MERGED_BODY,
+  };
+  const mergedStore = {
+    dir: "/tmp/remnic-harmonic-merged",
+    getMemoryByIdIncludingArchived: async (id: string) =>
+      id === "fact-target" ? committed : null,
+  } as unknown as StorageManager;
+  const map = new Map<string, {
+    storage: StorageManager;
+    facts: HarmonicConstructionInput["persistedFacts"];
+  }>();
+  await enqueueMergedTargetForHarmonicConstruction(
+    map,
+    mergedStore,
+    {
+      content: "Deploys of the billing service run on Tuesdays.",
+      category: "fact",
+      tags: ["deploy"],
+      cueAnchors: [{ type: "tool", value: "deploy runbook" }],
+    },
+    "fact-target",
+    MERGED_BODY,
+    "2026-08-22T12:00:00.000Z",
+  );
+  const entry = map.get(mergedStore.dir)!.facts[0]!;
+  assert.equal(entry.content, MERGED_BODY, "the committed merged body is the entry body");
+  assert.equal(entry.entityRef, "billing-service", "the committed entityRef survives the merge");
+  assert.deepEqual(
+    [...entry.tags].sort(),
+    ["deploy", "infra"],
+    "tags come from the committed target (a superset of the incoming subset)",
+  );
+  assert.deepEqual(
+    entry.cueAnchors?.map((anchor) => anchor.value),
+    ["deploy runbook"],
+    "event-specific cue anchors still ride in from the incoming fact",
+  );
+  const records = deriveHarmonicRecords({
+    sessionKey: "session-merged-entity",
+    recordedAt: "2026-08-22T12:00:00.000Z",
+    persistedFacts: [entry],
+    entityMentions: [{ name: "Billing Service", type: "service" }],
+  });
+  const topic = records.nodes.find(
+    (node) => node.kind === "topic" || node.kind === "project",
+  );
+  assert.ok(topic, "a topic node exists for the entity mention");
+  assert.ok(
+    topic.sourceMemoryIds?.includes("fact-target"),
+    "the entity mention links to the merged target through the committed entityRef",
+  );
+  const entityAnchor = records.anchors.find(
+    (anchor) => anchor.anchorType === "entity" && anchor.anchorValue === "billing-service",
+  );
+  assert.ok(
+    entityAnchor !== undefined && entityAnchor.nodeRefs.includes(topic.nodeId),
+    "the deterministic entity anchor references the topic node",
+  );
+
+  // Control: a reread that no longer matches the merged body (the record
+  // advanced mid-flight) falls back to the incoming fact's own fields.
+  const advancedStore = {
+    dir: "/tmp/remnic-harmonic-advanced",
+    getMemoryByIdIncludingArchived: async () => ({
+      ...committed,
+      content: "a newer writer's body",
+    }) as MemoryFile,
+  } as unknown as StorageManager;
+  const advancedMap = new Map<string, {
+    storage: StorageManager;
+    facts: HarmonicConstructionInput["persistedFacts"];
+  }>();
+  await enqueueMergedTargetForHarmonicConstruction(
+    advancedMap,
+    advancedStore,
+    {
+      content: "incoming body",
+      category: "fact",
+      tags: ["deploy"],
+    },
+    "fact-target",
+    MERGED_BODY,
+    "2026-08-22T12:00:00.000Z",
+  );
+  const fallback = advancedMap.get(advancedStore.dir)!.facts[0]!;
+  assert.equal(fallback.entityRef, undefined, "an advanced record never lends its metadata");
+  assert.deepEqual(fallback.tags, ["deploy"]);
+});

package/src/orchestration/harmonic-construction-persist.ts

@@ -8,7 +8,7 @@ import {
 } from "../harmonic-construction.js";
 import { log } from "../logger.js";
 import type { StorageManager } from "../index.js";
-import type { ExtractionResult } from "../types.js";
+import type { MemoryFile, ExtractionResult } from "../types.js";
 
 export interface HarmonicPersistenceEntry {
   storage: { dir: string };
@@ -57,8 +57,20 @@ export function filterHarmonicEntityMentions(
  * anchors UNION across merges — anchors are deduped by id downstream, but
  * the union keeps the earlier merge's anchors alive when the later incoming
  * fact carried none.
+ *
+ * #2807 (finding 3): the entry's metadata comes from the REREAD committed
+ * target, never the incoming fact alone. The parity gate lets an incoming
+ * fact with no entityRef merge into a target that HAS one (only a
+ * differing non-undefined incoming entity refuses), and incoming tags are
+ * a subset of the target's — so stamping the incoming fields onto the
+ * cumulative body dropped the target's committed entity association and
+ * extra tags, and `deriveHarmonicRecords` skipped the deterministic
+ * entity cue/topic linkage for the merged claims. Cue anchors stay
+ * incoming-only: they are event-specific. An unreadable or advanced record
+ * falls back to the incoming fact's own fields (fail-open, like every
+ * merge-adjacent effect).
  */
-export function enqueueMergedTargetForHarmonicConstruction(
+export async function enqueueMergedTargetForHarmonicConstruction(
   entries: Map<
     string,
     { storage: StorageManager; facts: HarmonicConstructionInput["persistedFacts"] }
@@ -71,22 +83,38 @@ export function enqueueMergedTargetForHarmonicConstruction(
   memoryId: string,
   content: string,
   insertedAt: string,
-): void {
+): Promise<void> {
+  let committed: MemoryFile | null = null;
+  try {
+    committed = await storage.getMemoryByIdIncludingArchived(memoryId);
+  } catch {
+    committed = null;
+  }
+  const derived =
+    committed && committed.content === content
+      ? {
+          ...fact,
+          category: committed.frontmatter.category,
+          tags: [...new Set([...(committed.frontmatter.tags ?? []), ...fact.tags])],
+          entityRef: committed.frontmatter.entityRef ?? fact.entityRef,
+          validAt: committed.frontmatter.valid_at ?? fact.validAt,
+        }
+      : fact;
   const entry = entries.get(storage.dir) ?? { storage, facts: [] };
   const prior = entry.facts.findIndex((existing) => existing.memoryId === memoryId);
   if (prior !== -1) {
     entry.facts[prior] = {
-      ...fact,
+      ...derived,
       content,
       memoryId,
       insertedAt,
       cueAnchors: [
         ...(entry.facts[prior]!.cueAnchors ?? []),
-        ...(fact.cueAnchors ?? []),
+        ...(derived.cueAnchors ?? []),
       ],
     };
   } else {
-    entry.facts.push({ ...fact, content, memoryId, insertedAt });
+    entry.facts.push({ ...derived, content, memoryId, insertedAt });
   }
   entries.set(storage.dir, entry);
 }

package/src/orchestration/maintenance.ts

@@ -167,6 +167,7 @@ export class MaintenanceScheduler {
       secureStoreEnabled: resolveRecallAuxiliaryCapabilities(deps.config).secureStore,
       getQmd: () => deps.getQmd(),
       requestReindexRetry: () => this.requestQmdMaintenanceForTool("activity-reindex-retry"),
+      pluginConfig: deps.config,
       ...(deps.onActivitySynced ? { onSynced: deps.onActivitySynced } : {}),
     });
   }

package/src/orchestration/orchestrator-helpers.ts

@@ -248,6 +248,12 @@ export interface RecallInvocationOptions {
    * normally be pruned by confidence decay.  Default `false`.
    */
   includeLowConfidence?: boolean;
+  /**
+   * #1952 — per-call override enabling state-aware recall views for this
+   * recall only (MCP `stateView` boolean). ORs with the `recallStateViews`
+   * config flag; a change-intent query is still required for any effect.
+   */
+  stateView?: boolean;
   /**
    * User-aware context scopes active for this recall. Used by X-ray
    * provenance safety checks so boundary-scoped memories are evaluated

package/src/orchestration/recall-entry.ts

@@ -272,6 +272,20 @@ export class RecallEntryCoordinator {
      * also threaded to formatQmdResultEntries for the epistemic hedge.
      */
     trustByPath?: Map<string, TrustStageResultItem> | null;
+    /**
+     * #1952 — per-request effective state-view flag (per-call `stateView`
+     * OR `recallStateViews` config, gated on change intent), computed once
+     * in recallInternal and threaded here. The inject seam uses this flag
+     * instead of rereading live config so a per-call `stateView: true`
+     * still labels/widens when the global flag is false.
+     */
+    stateViewActive?: boolean;
+    /**
+     * #1952 — historical recall pin (epoch ms) for this call. Under a
+     * pin, annotation must not discard a predecessor whose successor is
+     * absent due to the asOf validity filter; see applyRecallStateViews.
+     */
+    asOfMs?: number;
   }): void {
     const sectionId = "memories";
     const trustByPath = options.trustByPath ?? null;
@@ -281,6 +295,8 @@ export class RecallEntryCoordinator {
         : options.results,
       options.retrievalQuery,
       this.deps.config,
+      options.stateViewActive === true,
+      options.asOfMs,
     );
     if (injectable.length === 0) return;
 

package/src/orchestration/recall-internal-deps.ts

@@ -69,6 +69,8 @@ export interface RecallInternalDeps {
     /** Issue #680 — historical recall point in ms-since-epoch. */
     asOfMs?: number;
     requestingConnector?: string;
+    /** #1952 state-view admission — resolved by the caller from config/override + change intent. */
+    stateViewActive?: boolean;
     /**
      * Optional out-parameter that receives the pre-MMR / pre-truncation
      * pool size captured inside the pipeline (issue #570 PR 1).  The
@@ -133,6 +135,8 @@ export interface RecallInternalDeps {
        * string at the input boundary (CLI / HTTP / MCP).
        */
       asOfMs?: number;
+      /** #1952 state-view admission — see RecallSearchPipelineCoordinator. */
+      stateViewActive?: boolean;
       requestingConnector?: string;
     },
   ): Promise<QmdSearchResult[]>;
@@ -233,6 +237,8 @@ export interface RecallInternalDeps {
       dropUnresolved?: boolean;
       recallNamespaces?: readonly string[];
       requestingConnector?: string;
+      /** #1952 state-view admission — see RecallSearchPipelineCoordinator. */
+      stateViewActive?: boolean;
     },
   ): Promise<{ results: QmdSearchResult[]; memoryByPath: Map<string, MemoryFile> }>;
   formatCausalTrajectoryResults(
@@ -321,6 +327,14 @@ export interface RecallInternalDeps {
      * formatQmdResults for the epistemic hedge.
      */
     trustByPath?: Map<string, TrustStageResultItem> | null;
+    /**
+     * #1952 — per-request effective state-view flag from recallInternal.
+     * The publish seam must not reread live config (per-call override
+     * semantics, issue #1952).
+     */
+    stateViewActive?: boolean;
+    /** #1952 — historical recall pin (epoch ms); asOf-mode annotation. */
+    asOfMs?: number;
   }): void;
   readonly qmd: SearchBackend;
   queueEvalShadowRecall(

package/src/orchestration/recall-internal.ts

@@ -69,7 +69,6 @@ import type { SearchDegradation } from "../search/port.js";
 import { type VerifiedSemanticRuleResult, compareVerifiedSemanticRuleResults, searchVerifiedSemanticRules } from "../semantic-rule-verifier.js";
 import { isDisagreementPrompt } from "../signal.js";
 import { buildTargetedFactRecallSection, shouldRecallTargetedFactEvidence } from "../targeted-fact-recall.js";
-import { shouldFilterSupersededFromRecall } from "../temporal-supersession.js";
 import { queryTemporalTimelineAsync } from "../temporal-index.js";
 import { type TrustStageResultItem, projectTrustForXray } from "../trust-score-stage.js";
 import { isValidAsOf } from "../temporal-validity.js";
@@ -99,6 +98,7 @@ import {
   type RecallInvocationOptions,
 } from "../orchestrator.js";
 import { isGenericRecallExcludedPath } from "./generic-recall-paths.js";
+import { filterRecentScanMemoriesForStateView, indexStateViewAnnotatedResults, resolveRecallStateViewActive } from "../recall-state-view-admission.js";
 import type { RecallSectionBuckets } from "./recall-section-coordinator.js";
 import {
   reconcileRecallResultPartition,
@@ -243,6 +243,7 @@ export class RecallInternalCoordinator {
       cronConversationRecallMode: this.deps.config.cronConversationRecallMode,
     });
     const retrievalQuery = queryPolicy.retrievalQuery || prompt;
+    const stateViewActive = resolveRecallStateViewActive(options, this.deps.config, retrievalQuery);
     const retrievalQueryHash = createHash("sha256")
       .update(retrievalQuery)
       .digest("hex");
@@ -3842,6 +3843,7 @@ export class RecallInternalCoordinator {
         undefined,
         {
           asOfMs,
+          stateViewActive,
           // If QMD had already settled before the ordered assembly reached it,
           // do not let unrelated slow enrichment turn those known results into
           // unchecked misses. QMD that only settles during its own wait remains
@@ -3865,7 +3867,7 @@ export class RecallInternalCoordinator {
             recallNamespaces,
             retrievalQuery,
             qmdBoostInput.memoryByPath,
-            { asOfMs, requestingConnector: options.sourceConnector },
+            { asOfMs, stateViewActive, requestingConnector: options.sourceConnector },
           ),
         qmdBoostInput.results,
       );
@@ -4068,6 +4070,8 @@ export class RecallInternalCoordinator {
             injectedChars: identityInjectedChars,
             truncated: identityInjectionTruncated,
           },
+        stateViewActive,
+        asOfMs,
         trustByPath: recallTrustByPath,
         });
         recalledMemoryPaths = memoryResults
@@ -4106,7 +4110,7 @@ export class RecallInternalCoordinator {
               recallNamespaces,
               retrievalQuery,
               undefined,
-              { asOfMs, requestingConnector: options.sourceConnector },
+              { asOfMs, stateViewActive, requestingConnector: options.sourceConnector },
             );
             xrayBranchPoolSize.hot_embedding = Math.max(
               xrayBranchPoolSize.hot_embedding,
@@ -4190,6 +4194,8 @@ export class RecallInternalCoordinator {
               injectedChars: identityInjectedChars,
               truncated: identityInjectionTruncated,
             },
+          stateViewActive,
+          asOfMs,
           trustByPath: recallTrustByPath,
           });
           recalledMemoryPaths = scoped
@@ -4201,6 +4207,7 @@ export class RecallInternalCoordinator {
             options.xrayCapture === true ? { partition: null } : undefined;
           const longTerm = await this.deps.applyColdFallbackPipeline({
             prompt: retrievalQuery,
+            stateViewActive,
             recallNamespaces,
             recallResultLimit,
             recallMode,
@@ -4244,6 +4251,8 @@ export class RecallInternalCoordinator {
                 injectedChars: identityInjectedChars,
                 truncated: identityInjectionTruncated,
               },
+            stateViewActive,
+            asOfMs,
             trustByPath: recallTrustByPath,
             });
             recalledMemoryPaths = longTerm
@@ -4318,7 +4327,7 @@ export class RecallInternalCoordinator {
               recallNamespaces,
               retrievalQuery,
               undefined,
-              { asOfMs, requestingConnector: options.sourceConnector },
+              { asOfMs, stateViewActive, requestingConnector: options.sourceConnector },
             );
             // MMR runs on the pre-truncation pool (see the hot-embedding branch).
             xrayBranchPoolSize.hot_embedding = Math.max(
@@ -4400,6 +4409,8 @@ export class RecallInternalCoordinator {
             injectedChars: identityInjectedChars,
             truncated: identityInjectionTruncated,
           },
+        stateViewActive,
+        asOfMs,
         trustByPath: recallTrustByPath,
         });
         recalledMemoryPaths = scoped
@@ -4416,59 +4427,19 @@ export class RecallInternalCoordinator {
           [] as MemoryFile[],
         );
         if (memories.length > 0) {
-          // Filter out non-active memories.  Delegate to
-          // shouldFilterSupersededFromRecall for superseded-status logic so
-          // that the recent-scan path and the boostSearchResults (QMD) path
-          // have identical semantics:
-          //   • temporalSupersessionEnabled=false  → never filter superseded
-          //     (mirrors QMD path; user disabled the feature, so old marks
-          //     are ignored and all memories surface)
-          //   • temporalSupersessionIncludeInRecall=true → never filter (audit mode)
-          //   • enabled=true + includeInRecall=false → filter superseded
-          // Previously the recent-scan path checked `enabled && includeInRecall`
-          // directly, which disagreed with the QMD path when enabled=false
-          // (memories were still filtered, contrary to the kill-switch intent).
-          // Using the shared gate fixes both Finding 2 and Finding 3 from
-          // PR #402 (round 6).
-          const supersessionOptions = {
-            enabled: lifecycleCaps.temporalSupersession,
-            includeInRecall: this.deps.config.temporalSupersessionIncludeInRecall,
-          };
-          // Cursor Medium on PR #713: when `as_of` is active, the
-          // recent-scan path used to strip every non-active status
-          // (including superseded) before `boostSearchResults` ran,
-          // so the as_of bypass inside boostSearchResults never had
-          // a chance to admit historically-valid records. Pass
-          // superseded candidates through here when as_of is active;
-          // boostSearchResults's `[valid_at, invalid_at)` evaluation
-          // is the authoritative gate. Other non-active statuses
-          // (archived, forgotten, rejected) stay excluded — historical
-          // recall is about supersession history, not about reviving
-          // records the operator explicitly dropped.
-          const asOfActive =
-            typeof asOfMs === "number" && Number.isFinite(asOfMs);
-          const activeMemories = memories.filter(
-            (m) => {
-              if (isGenericRecallExcludedPath(m.path, this.deps.config)) return false;
-              const status = m.frontmatter.status;
-              if (!status || status === "active") return true;
-              if (status === "superseded") {
-                if (asOfActive) return true;
-                // Include superseded memory only if the canonical gate says
-                // NOT to filter it (kill switch off or audit mode on).
-                return !shouldFilterSupersededFromRecall(m.frontmatter, supersessionOptions);
-              }
-              // Other non-active statuses (archived, retired, etc.) are
-              // excluded from the recent-scan path by default.
-              return false;
+          const activeMemories = filterRecentScanMemoriesForStateView(
+            memories,
+            this.deps.config,
+            {
+              enabled: lifecycleCaps.temporalSupersession,
+              includeInRecall: this.deps.config.temporalSupersessionIncludeInRecall,
             },
+            stateViewActive,
+            asOfMs,
           );
-          // Convert all active memories to QmdSearchResult with recency-based
-          // baseline score, then pass through boostSearchResults so temporal/tag
-          // boosts apply consistently with the primary QMD retrieval path.
-          // Cap AFTER boosting so boosted-but-recency-ranked memories can surface.
-          // Pass a pre-populated memoryByPath so boostSearchResults skips redundant
-          // disk reads for files already loaded by readAllMemoriesForNamespaces.
+          // Convert to QmdSearchResult with recency baseline, then boost so
+          // temporal/tag boosts match the QMD path. Cap AFTER boosting, and
+          // pass a pre-populated memoryByPath to skip redundant disk reads.
           const queryAwareScopedMemories = queryAwarePrefilter.candidatePaths
             ? activeMemories.filter((memory) =>
                 queryAwarePrefilter.candidatePaths?.has(memory.path),
@@ -4482,6 +4453,7 @@ export class RecallInternalCoordinator {
               options.xrayCapture === true ? { partition: null } : undefined;
             const longTerm = await this.deps.applyColdFallbackPipeline({
               prompt: retrievalQuery,
+              stateViewActive,
               recallNamespaces,
               recallResultLimit,
               recallMode,
@@ -4517,6 +4489,8 @@ export class RecallInternalCoordinator {
                   injectedChars: identityInjectedChars,
                   truncated: identityInjectionTruncated,
                 },
+              stateViewActive,
+              asOfMs,
               trustByPath: recallTrustByPath,
               });
               recalledMemoryPaths = longTerm
@@ -4554,7 +4528,7 @@ export class RecallInternalCoordinator {
                     recallNamespaces,
                     retrievalQuery,
                     preloadedMap,
-                    { asOfMs, requestingConnector: options.sourceConnector },
+                    { asOfMs, stateViewActive, requestingConnector: options.sourceConnector },
                   )
                 ).sort((a, b) => b.score - a.score);
                 // MMR runs on the pre-truncation pool so diverse candidates just
@@ -4644,6 +4618,8 @@ export class RecallInternalCoordinator {
                   injectedChars: identityInjectedChars,
                   truncated: identityInjectionTruncated,
                 },
+              stateViewActive,
+              asOfMs,
               trustByPath: recallTrustByPath,
               });
               recalledMemoryPaths = recent
@@ -4655,6 +4631,7 @@ export class RecallInternalCoordinator {
                 options.xrayCapture === true ? { partition: null } : undefined;
               const longTerm = await this.deps.applyColdFallbackPipeline({
                 prompt: retrievalQuery,
+                stateViewActive,
                 recallNamespaces,
                 recallResultLimit,
                 recallMode,
@@ -4697,6 +4674,8 @@ export class RecallInternalCoordinator {
                     injectedChars: identityInjectedChars,
                     truncated: identityInjectionTruncated,
                   },
+                stateViewActive,
+                asOfMs,
                 trustByPath: recallTrustByPath,
                 });
                 recalledMemoryPaths = longTerm
@@ -4711,6 +4690,7 @@ export class RecallInternalCoordinator {
             options.xrayCapture === true ? { partition: null } : undefined;
           const longTerm = await this.deps.applyColdFallbackPipeline({
             prompt: retrievalQuery,
+            stateViewActive,
             recallNamespaces,
             recallResultLimit,
             recallMode,
@@ -4752,6 +4732,8 @@ export class RecallInternalCoordinator {
                 injectedChars: identityInjectedChars,
                 truncated: identityInjectionTruncated,
               },
+            stateViewActive,
+            asOfMs,
             trustByPath: recallTrustByPath,
             });
             recalledMemoryPaths = longTerm
@@ -5050,8 +5032,8 @@ export class RecallInternalCoordinator {
         // Build a path → QmdSearchResult index so we can pull per-result
         // explain data (e.g. reinforcementBoost) from the result that
         // boostSearchResults annotated before surfacing to xray.
-        const xrayResultByPath = new Map<string, QmdSearchResult>(
-          xrayRecalledResults.map((xr) => [`${xr.namespace ?? ""}\0${xr.path}`, xr]),
+        const xrayResultByPath = indexStateViewAnnotatedResults(
+          xrayRecalledResults, retrievalQuery, this.deps.config, stateViewActive, asOfMs,
         );
         const results: RecallXrayResult[] = [];
         for (let xrayIdx = 0; xrayIdx < recalledMemoryPaths.length; xrayIdx += 1) {
@@ -5109,6 +5091,7 @@ export class RecallInternalCoordinator {
             servedBy,
             scoreDecomposition,
             admittedBy: [],
+            ...(xrayResult?.stateLabel ? { stateView: xrayResult.stateLabel } : {}),
             ...(xrayResult?.pathNodeIds ? { pathNodeIds: xrayResult.pathNodeIds } : {}),
             ...(typeof xrayResult?.pathPenaltyApplied === "boolean"
               ? { pathPenaltyApplied: xrayResult.pathPenaltyApplied }

package/src/orchestration/recall-result-formatter.ts

@@ -18,6 +18,7 @@
  */
 
 import { buildHandleIndexForResults } from "../recall-handles.js";
+import { formatSupersededPrefix } from "../recall-state-view.js";
 import path from "node:path";
 import { renderAuthorityBoundContent } from "../recall-context-composition.js";
 import { renderEpistemicHedge } from "../trust-score.js";
@@ -215,8 +216,17 @@ export class RecallResultFormatter {
       const snippetBody = r.snippet
         ? r.snippet.slice(0, 500).replace(/\n/g, " ")
         : "(no preview)";
+      // Historical-prefix contract (issue #1952): only a labeled superseded
+      // row gets `[superseded <date> by <id>]`; every other row — and every
+      // render with the feature off — stays byte-identical.
+      const statePrefix =
+        (r.stateLabel === "historical" || r.stateLabel === "transition") &&
+        r.supersededAt &&
+        r.supersededBy
+          ? `${formatSupersededPrefix(r.supersededAt, r.supersededBy)} `
+          : "";
       const snippet = renderAuthorityBoundContent(
-        snippetBody,
+        `${statePrefix}${snippetBody}`,
         r.origin,
         {
           enabled: this.originAuthorityEnabled,