@remnic/core 9.69.38 → 9.69.40

package/src/orchestration/recall-internal.ts

@@ -98,7 +98,8 @@ import {
   type RecallInvocationOptions,
 } from "../orchestrator.js";
 import { isGenericRecallExcludedPath } from "./generic-recall-paths.js";
-import { filterRecentScanMemoriesForStateView, indexStateViewAnnotatedResults, resolveRecallStateViewActive } from "../recall-state-view-admission.js";
+import { filterRecentScanMemories } from "../recall-state-view-anchors.js";
+import { indexStateViewAnnotatedResults, resolveRecallStateViewActive } from "../recall-state-view-admission.js";
 import type { RecallSectionBuckets } from "./recall-section-coordinator.js";
 import {
   reconcileRecallResultPartition,
@@ -242,8 +243,11 @@ export class RecallInternalCoordinator {
         this.deps.effectiveCronRecallInstructionHeavyTokenCap(),
       cronConversationRecallMode: this.deps.config.cronConversationRecallMode,
     });
+    // #1952 state views: config flag OR per-call override, gated on change intent; computed once for all branches.
     const retrievalQuery = queryPolicy.retrievalQuery || prompt;
-    const stateViewActive = resolveRecallStateViewActive(options, this.deps.config, retrievalQuery);
+    const stateViewActive = resolveRecallStateViewActive(options, this.deps.config, prompt);
+    const stateViewPacketActive =
+      stateViewActive === true && !(typeof asOfMs === "number" && Number.isFinite(asOfMs));
     const retrievalQueryHash = createHash("sha256")
       .update(retrievalQuery)
       .digest("hex");
@@ -3996,17 +4000,19 @@ export class RecallInternalCoordinator {
               recallResultLimit,
               retrievalQuery,
               caps,
+              stateViewPacketActive,
             )
           : null;
       memoryResults = hotQmdPartition
         ? [...hotQmdPartition.appliedResults]
-        : this.deps.diversifyAndLimitRecallResults(
+        : this.deps.recallRerankCoordinator.diversifyRecallResultsWithHeadroom(
             "memories",
             memoryResults,
             recallResultLimit,
             retrievalQuery,
             caps,
-          );
+            stateViewPacketActive,
+          ).appliedResults;
       // E-Mem-inspired memory reconstruction: fill gaps for referenced entities
       if (resolveRecallEnhancementCapabilities(this.deps.config).memoryReconstruction && memoryResults.length > 0) {
         try {
@@ -4120,27 +4126,8 @@ export class RecallInternalCoordinator {
           },
           [] as QmdSearchResult[],
         );
-        const embeddingPartition =
-          options.xrayCapture === true
-            ? this.deps.recallRerankCoordinator.diversifyRecallResultsWithHeadroom(
-                "memories",
-                scoped,
-                recallResultLimit,
-                retrievalQuery,
-                caps,
-              )
-            : null;
-        scoped =
-          embeddingPartition?.appliedResults ??
-          this.deps.diversifyAndLimitRecallResults(
-            "memories",
-            scoped,
-            recallResultLimit,
-            retrievalQuery,
-            caps,
-          );
-        // Issue #1577 — apply TrustScore on the embedding-fallback path so the
-        // feature gate is consistent across ALL recall paths (rule 41 parity).
+        // Issue #1577 — trust filter before packet cap (AGENTS.md order).
+        // Feature gate is consistent across ALL recall paths (rule 41 parity).
         {
           // Deadline-bound (issue #1905). This branch has no preloaded
           // frontmatter map (boost ran without one), so pass undefined and let
@@ -4173,6 +4160,27 @@ export class RecallInternalCoordinator {
             success: !trustFellBack,
           });
         }
+        const embeddingPartition =
+          options.xrayCapture === true
+            ? this.deps.recallRerankCoordinator.diversifyRecallResultsWithHeadroom(
+                "memories",
+                scoped,
+                recallResultLimit,
+                retrievalQuery,
+                caps,
+                stateViewPacketActive,
+              )
+            : null;
+        scoped =
+          embeddingPartition?.appliedResults ??
+          this.deps.recallRerankCoordinator.diversifyRecallResultsWithHeadroom(
+            "memories",
+            scoped,
+            recallResultLimit,
+            retrievalQuery,
+            caps,
+            stateViewPacketActive,
+          ).appliedResults;
         if (scoped.length > 0) {
           if (shouldPersistGraphSnapshot) {
             graphSnapshotFinalResults = this.deps.buildGraphRecallRankedResults(
@@ -4338,27 +4346,8 @@ export class RecallInternalCoordinator {
           },
           [] as QmdSearchResult[],
         );
-        const embeddingPartition =
-          options.xrayCapture === true
-            ? this.deps.recallRerankCoordinator.diversifyRecallResultsWithHeadroom(
-                "memories",
-                scoped,
-                recallResultLimit,
-                retrievalQuery,
-                caps,
-              )
-            : null;
-        scoped =
-          embeddingPartition?.appliedResults ??
-          this.deps.diversifyAndLimitRecallResults(
-            "memories",
-            scoped,
-            recallResultLimit,
-            retrievalQuery,
-            caps,
-          );
-        // Issue #1577 — apply TrustScore on the embedding-fallback path so the
-        // feature gate is consistent across ALL recall paths (rule 41 parity).
+        // Issue #1577 — trust filter before packet cap (AGENTS.md order).
+        // Feature gate is consistent across ALL recall paths (rule 41 parity).
         {
           // Deadline-bound (issue #1905); no preloaded map on this branch.
           const trustT0 = Date.now();
@@ -4388,6 +4377,27 @@ export class RecallInternalCoordinator {
             success: !trustFellBack,
           });
         }
+        const embeddingPartition =
+          options.xrayCapture === true
+            ? this.deps.recallRerankCoordinator.diversifyRecallResultsWithHeadroom(
+                "memories",
+                scoped,
+                recallResultLimit,
+                retrievalQuery,
+                caps,
+                stateViewPacketActive,
+              )
+            : null;
+        scoped =
+          embeddingPartition?.appliedResults ??
+          this.deps.recallRerankCoordinator.diversifyRecallResultsWithHeadroom(
+            "memories",
+            scoped,
+            recallResultLimit,
+            retrievalQuery,
+            caps,
+            stateViewPacketActive,
+          ).appliedResults;
       if (scoped.length > 0) {
         if (shouldPersistGraphSnapshot) {
           graphSnapshotFinalResults = this.deps.buildGraphRecallRankedResults(
@@ -4427,16 +4437,15 @@ export class RecallInternalCoordinator {
           [] as MemoryFile[],
         );
         if (memories.length > 0) {
-          const activeMemories = filterRecentScanMemoriesForStateView(
-            memories,
-            this.deps.config,
-            {
+          const activeMemories = filterRecentScanMemories(memories, {
+            stateViewActive, asOfMs,
+            namespaceOf: (p) => this.deps.namespaceFromPath(p),
+            isExcluded: (p) => isGenericRecallExcludedPath(p, this.deps.config),
+            supersessionOptions: {
               enabled: lifecycleCaps.temporalSupersession,
               includeInRecall: this.deps.config.temporalSupersessionIncludeInRecall,
             },
-            stateViewActive,
-            asOfMs,
-          );
+          });
           // 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.
@@ -4541,27 +4550,8 @@ export class RecallInternalCoordinator {
               },
               [] as QmdSearchResult[],
             );
-            const recentPartition =
-              options.xrayCapture === true
-                ? this.deps.recallRerankCoordinator.diversifyRecallResultsWithHeadroom(
-                    "memories",
-                    recent,
-                    recallResultLimit,
-                    retrievalQuery,
-                    caps,
-                  )
-                : null;
-            recent =
-              recentPartition?.appliedResults ??
-              this.deps.diversifyAndLimitRecallResults(
-                "memories",
-                recent,
-                recallResultLimit,
-                retrievalQuery,
-                caps,
-              );
-            // Issue #1577 — apply TrustScore on the recent-scan path so the
-            // feature gate is consistent across ALL recall paths (rule 41).
+            // Issue #1577 — trust filter before packet cap (AGENTS.md order).
+            // Feature gate is consistent across ALL recall paths (rule 41).
             {
               // Deadline-bound (issue #1905). The recent-scan branch already
               // loaded every candidate's MemoryFile (queryAwareScopedMemories),
@@ -4597,6 +4587,27 @@ export class RecallInternalCoordinator {
                 success: !trustFellBack,
               });
             }
+            const recentPartition =
+              options.xrayCapture === true
+                ? this.deps.recallRerankCoordinator.diversifyRecallResultsWithHeadroom(
+                    "memories",
+                    recent,
+                    recallResultLimit,
+                    retrievalQuery,
+                    caps,
+                    stateViewPacketActive,
+                  )
+                : null;
+            recent =
+              recentPartition?.appliedResults ??
+              this.deps.recallRerankCoordinator.diversifyRecallResultsWithHeadroom(
+                "memories",
+                recent,
+                recallResultLimit,
+                retrievalQuery,
+                caps,
+                stateViewPacketActive,
+              ).appliedResults;
             if (recent.length > 0) {
               if (shouldPersistGraphSnapshot) {
                 graphSnapshotFinalResults = this.deps.buildGraphRecallRankedResults(

package/src/orchestration/recall-rerank-coordinator.ts

@@ -39,6 +39,7 @@ import type { TrustSignals } from "../trust-score.js";
 import { reorderRecallResultsWithMmr } from "../recall-mmr.js";
 import { applyReasoningTraceBoost } from "../reasoning-trace-recall.js";
 import { memoryMapKey } from "../recall-memory-map.js";
+import { capStateViewPackets, reconcileStateViewPairs } from "../recall-state-view.js";
 
 export interface RecallResultPartition {
   appliedResults: QmdSearchResult[];
@@ -621,12 +622,28 @@ export class RecallRerankCoordinator {
     limit: number,
     retrievalQuery?: string,
     caps: CapabilitySet = resolveCapabilities(this.getConfig()),
+    /**
+     * #2859 — state-view packet semantics. When true, superseded rows are
+     * reconciled against their successors BEFORE MMR (orphan removal can
+     * never underfill), and the cap counts complete evidence packets: a
+     * predecessor admitted alongside its successor consumes ONE slot and
+     * the slice never splits the pair at the boundary. Absent/false keeps
+     * the legacy slice byte-identical.
+     */
+    stateViewActive?: boolean,
   ): RecallResultPartition {
     const safeLimit =
       typeof limit === "number" && Number.isFinite(limit)
         ? Math.max(0, Math.floor(limit))
         : 0;
-    const candidates = Array.isArray(results) ? results : [];
+    // #2859: reconcile pairs before the user cap/MMR so orphan removal
+    // happens pre-truncation, never post-cap.
+    const candidates =
+      stateViewActive === true && Array.isArray(results)
+        ? reconcileStateViewPairs(results)
+        : Array.isArray(results)
+          ? results
+          : [];
     let orderedPool: QmdSearchResult[] | undefined;
     const resolveOrderedPool = (): QmdSearchResult[] => {
       if (orderedPool) return orderedPool;
@@ -640,15 +657,32 @@ export class RecallRerankCoordinator {
       orderedPool = this.applyMmrToQmdResults(sectionId, boosted, caps);
       return orderedPool;
     };
+    let appliedCache: QmdSearchResult[] | undefined;
+    const resolveApplied = (): QmdSearchResult[] => {
+      if (appliedCache) return appliedCache;
+      if (safeLimit === 0 || candidates.length === 0) {
+        appliedCache = [];
+        return appliedCache;
+      }
+      const ordered = resolveOrderedPool();
+      // #2859: the cap counts complete evidence packets, not rows.
+      appliedCache =
+        stateViewActive === true ? capStateViewPackets(ordered, safeLimit) : ordered.slice(0, safeLimit);
+      return appliedCache;
+    };
 
     return {
       get appliedResults(): QmdSearchResult[] {
-        if (safeLimit === 0 || candidates.length === 0) return [];
-        return resolveOrderedPool().slice(0, safeLimit);
+        return resolveApplied().slice();
       },
       get headroomResults(): QmdSearchResult[] {
         if (candidates.length === 0) return [];
-        return resolveOrderedPool().slice(safeLimit);
+        const ordered = resolveOrderedPool();
+        if (stateViewActive === true) {
+          const applied = new Set(resolveApplied());
+          return ordered.filter((row) => !applied.has(row));
+        }
+        return ordered.slice(safeLimit);
       },
     };
   }
@@ -659,6 +693,8 @@ export class RecallRerankCoordinator {
     limit: number,
     retrievalQuery?: string,
     caps: CapabilitySet = resolveCapabilities(this.getConfig()),
+    /** #2859 — see diversifyRecallResultsWithHeadroom. */
+    stateViewActive?: boolean,
   ): QmdSearchResult[] {
     return this.diversifyRecallResultsWithHeadroom(
       sectionId,
@@ -666,6 +702,7 @@ export class RecallRerankCoordinator {
       limit,
       retrievalQuery,
       caps,
+      stateViewActive,
     ).appliedResults;
   }
 

package/src/orchestration/recall-search-pipeline.ts

@@ -45,6 +45,7 @@ import {
 } from "./recall-search-prefilter.js";
 import { shouldFilterSupersededFromRecall } from "../temporal-supersession.js";
 import { isValidAsOf, isValidityExpiredNow } from "../temporal-validity.js";
+import { StateViewAnchorTracker, stateViewPacketActive } from "../recall-state-view-anchors.js";
 import type { TrustStageResultItem } from "../trust-score-stage.js";
 import type { MemoryFile, PluginConfig, QmdSearchResult, RecallPlanMode } from "../types.js";
 import {
@@ -987,17 +988,22 @@ export class RecallSearchPipelineCoordinator {
         options.recallResultLimit,
         options.prompt,
         caps,
+        // #2859: packet semantics are off under a historical asOf pin.
+        stateViewPacketActive(options.stateViewActive, options.asOfMs),
       );
       options.resultPartitionSink.partition = partition;
       return partition.appliedResults;
     }
-    return this.deps.diversifyAndLimitRecallResults(
-      "memories",
-      results,
-      options.recallResultLimit,
-      options.prompt,
-      caps,
-    );
+    return this.deps.recallRerankCoordinator
+      .diversifyRecallResultsWithHeadroom(
+        "memories",
+        results,
+        options.recallResultLimit,
+        options.prompt,
+        caps,
+        stateViewPacketActive(options.stateViewActive, options.asOfMs),
+      )
+      .appliedResults;
   }
 
   async loadSearchResultMemoryMap(
@@ -1132,10 +1138,11 @@ export class RecallSearchPipelineCoordinator {
     // when its successor SURVIVES this filter — a successor rejected by
     // the connector/lifecycle/validity/dedicated-surface/status gates
     // must never anchor (or spend a result slot on) its superseded row.
-    // Anchors are therefore collected from rows that survive the pass
-    // below; superseded rows defer admission to the post-pass fixpoint.
+    // #2859: anchors are namespace-qualified and include the successor
+    // `supersedes` back-pointer (see StateViewAnchorTracker); superseded
+    // rows defer admission to the post-pass fixpoint.
     const stateViewActive = options?.stateViewActive === true;
-    const stateViewSurvivorIds = stateViewActive ? new Set<string>() : null;
+    const stateViewAnchors = stateViewActive ? new StateViewAnchorTracker() : null;
     const stateViewDeferred: number[] = [];
     const stateViewBuilt: (QmdSearchResult | null)[] | null = stateViewActive
       ? new Array<QmdSearchResult | null>(results.length).fill(null)
@@ -1150,8 +1157,11 @@ export class RecallSearchPipelineCoordinator {
         ? {
             id: memory.frontmatter.id,
             status: memory.frontmatter.status,
+            supersedes: memory.frontmatter.supersedes,
             supersededBy: memory.frontmatter.supersededBy,
             supersededAt: memory.frontmatter.supersededAt,
+            validAt: memory.frontmatter.valid_at,
+            invalidAt: memory.frontmatter.invalid_at,
           }
         : {}),
     });
@@ -1307,10 +1317,7 @@ export class RecallSearchPipelineCoordinator {
       const builtRow = buildRecallRow(r, memory);
       if (stateViewBuilt !== null) {
         stateViewBuilt[resultIdx] = builtRow;
-        if (memory) {
-          const id = memory.frontmatter.id;
-          if (typeof id === "string" && id.length > 0) stateViewSurvivorIds!.add(id);
-        }
+        if (memory && stateViewAnchors) stateViewAnchors.admit(r.namespace, memory.frontmatter);
       }
       filtered.push(builtRow);
     }
@@ -1324,12 +1331,12 @@ export class RecallSearchPipelineCoordinator {
         progress = false;
         for (const deferredIdx of stateViewDeferred) {
           if (admitted.has(deferredIdx)) continue;
-          const deferredMemory = memoryForResult(memoryByPath, results[deferredIdx]!);
+          const deferredRow = results[deferredIdx]!;
+          const deferredMemory = memoryForResult(memoryByPath, deferredRow);
           if (!deferredMemory) continue;
-          if (stateViewSurvivorIds!.has(deferredMemory.frontmatter.supersededBy ?? "")) {
+          if (stateViewAnchors!.anchored(deferredRow.namespace, deferredMemory.frontmatter)) {
             admitted.add(deferredIdx);
-            const id = deferredMemory.frontmatter.id;
-            if (typeof id === "string" && id.length > 0) stateViewSurvivorIds!.add(id);
+            stateViewAnchors!.admit(deferredRow.namespace, deferredMemory.frontmatter);
             progress = true;
           }
         }

package/src/orchestration/recall-state-view-pipeline.test.ts

@@ -209,3 +209,92 @@ test("an anchored predecessor keeps its rank position when admitted", async () =
     await rm(memoryDir, { recursive: true, force: true });
   }
 });
+
+test("#2859 namespace fanout collision: a same-id successor in another namespace cannot anchor", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-sv-fanout-"));
+  try {
+    const coordinator = await makeCoordinator(memoryDir);
+    const A_OLD = "facts/a-old.md";
+    const B_NEW = "facts/b-new.md";
+    // ns-a: superseded predecessor whose successor id m-1 is NOT in the
+    // candidate set. ns-b: an unrelated active row that reuses id m-1.
+    // Bare-id matching (pre-#2859) admitted the ns-a predecessor on the
+    // ns-b anchor; qualified keys must not.
+    const results: QmdSearchResult[] = [
+      { ...result(B_NEW, 0.9), namespace: "ns-b" },
+      { ...result(A_OLD, 0.7), namespace: "ns-a" },
+    ];
+    const memories = new Map<string, MemoryFile>([
+      [`ns-b\0${B_NEW}`, memory(B_NEW, { id: "m-1", status: "active" })],
+      [
+        `ns-a\0${A_OLD}`,
+        memory(A_OLD, {
+          id: "m-0",
+          status: "superseded",
+          supersededBy: "m-1",
+          supersededAt: "2026-08-01",
+        }),
+      ],
+    ]);
+    const safe = coordinator.filterSearchResultsByRecallSafety(results, memories, {
+      stateViewActive: true,
+    });
+    assert.deepEqual(
+      safe.map((r) => r.path),
+      [B_NEW],
+      "a foreign-namespace successor must never anchor the superseded row"
+    );
+
+    // Positive control: ns-a's own m-1 present → the pair is admitted.
+    const A_NEW = "facts/a-new.md";
+    const pairResults: QmdSearchResult[] = [
+      { ...result(A_NEW, 0.9), namespace: "ns-a" },
+      { ...result(A_OLD, 0.7), namespace: "ns-a" },
+    ];
+    const pairMemories = new Map<string, MemoryFile>([
+      [`ns-a\0${A_NEW}`, memory(A_NEW, { id: "m-1", status: "active" })],
+      [`ns-a\0${A_OLD}`, memories.get(`ns-a\0${A_OLD}`)!],
+    ]);
+    const pair = coordinator.filterSearchResultsByRecallSafety(pairResults, pairMemories, {
+      stateViewActive: true,
+    });
+    assert.deepEqual(
+      pair.map((r) => r.path),
+      [A_NEW, A_OLD],
+      "the same-namespace successor anchors the pair as before"
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("#2859 back-pointer anchors a deferred row whose supersededBy is absent", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-sv-backptr-"));
+  try {
+    const coordinator = await makeCoordinator(memoryDir);
+    const results = [result(NEW, 0.9), result(OLD, 0.7)];
+    const memories = new Map<string, MemoryFile>([
+      [NEW, memory(NEW, { id: "m-new", status: "active", supersedes: "m-old" })],
+      [
+        OLD,
+        memory(OLD, {
+          id: "m-old",
+          status: "superseded",
+          supersededAt: "2026-08-01",
+        }),
+      ],
+    ]);
+    const safe = coordinator.filterSearchResultsByRecallSafety(results, memories, {
+      stateViewActive: true,
+    });
+    assert.deepEqual(
+      safe.map((r) => r.path),
+      [NEW, OLD],
+      "the successor's supersedes back-pointer must admit its predecessor"
+    );
+    assert.equal(safe[1]?.supersedes, undefined, "the admitted row itself has no back-pointer");
+    assert.equal(safe[0]?.supersedes, "m-old", "the survivor carries its supersedes back-pointer");
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});

package/src/orchestration/semantic-merge-promotion-payload.ts

@@ -4,7 +4,9 @@
  * within its file-size ratchet. Everything here derives from the re-read
  * COMMITTED record; nothing reads the incoming extraction.
  */
-
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { canonicalSemanticFileText } from "../storage/cas-revision-store.js";
 import { parseOriginClass } from "../security/origin-authority.js";
 import { log } from "../logger.js";
 import { inferMemoryStatus } from "../memory-lifecycle-ledger-utils.js";
@@ -76,6 +78,15 @@ export interface MergedTargetPromotionPayload {
   committedRevision?: string;
   /** #2813 (P1 B): sha256 hex digest of the durable memory file when committed. */
   committedDigest?: string;
+  /** #2870: canonical SEMANTIC fingerprint of the durable file at
+   * payload-build time — access telemetry (`accessCount`/`lastAccessed`)
+   * excluded, the same exclusion set `invalidationCommitFingerprint`
+   * applies. The final guard re-reads the file and compares THIS, not the
+   * byte digest: an access-tracking flush between build and promotion
+   * leaves it equal (the flush mints no receipt and touches no semantic
+   * line), while any body/confidence/provenance/scope/tags/status change
+   * makes it differ. */
+  committedSemanticFingerprint?: string;
 }
 
 /**
@@ -151,13 +162,22 @@ export async function buildMergedTargetPromotionPayload(
     return { payload: null, readFailed: false };
   }
   const fm = committed.frontmatter;
-  // #2813 (P1 B): promotion reads record metadata and digest, then receipt.
-  // Compare record snapshot digest to receipt's committed digest to catch
-  // interleaving metadata writers with same body/new metadata.
+  // #2870: bind to the record's SEMANTIC identity, not its bytes. The
+  // receipt's committed semantic fingerprint — the durable file with the
+  // access-telemetry keys (`accessCount:`, `lastAccessed:`) stripped, the
+  // same exclusion set `invalidationCommitFingerprint` applies — stays
+  // equal across an access-tracking flush (which rewrites exactly those
+  // two lines without minting a receipt), so a flush between the merge
+  // commit and this reread no longer blocks a valid promotion. Any other
+  // frontmatter or body change still refuses. Shards recorded before
+  // #2870 carry no stored semantic fingerprint; those keep the stricter
+  // full-digest comparison until the next semantic write re-records the
+  // shard.
   const snapshotDigest =
     typeof storage.readDurableFileDigest === "function"
       ? await storage.readDurableFileDigest(committed.path).catch(() => null)
       : null;
+  const snapshotSemanticFingerprint = await readDurableSemanticFingerprint(committed.path);
   const receipt = await readPromotionReceiptStatus(storage, committed.path);
   if (!receipt.available) {
     log.warn(
@@ -165,7 +185,22 @@ export async function buildMergedTargetPromotionPayload(
     );
     return { payload: null, readFailed: true };
   }
-  if (receipt.committedDigest !== undefined && snapshotDigest !== receipt.committedDigest) {
+  if (
+    receipt.committedSemanticFingerprint !== undefined &&
+    snapshotSemanticFingerprint !== receipt.committedSemanticFingerprint
+  ) {
+    log.warn(
+      snapshotSemanticFingerprint == null
+        ? `semantic-merge: merged-target promotion refused for ${merge.targetId} — the semantic snapshot fingerprint is unavailable while the CAS receipt carries ${receipt.committedSemanticFingerprint}; promotion and reconciliation retry on the next merge`
+        : `semantic-merge: merged-target promotion refused for ${merge.targetId} — record semantic fingerprint (${snapshotSemanticFingerprint}) does not match committed receipt fingerprint (${receipt.committedSemanticFingerprint}); record metadata was mutated concurrently`,
+    );
+    return { payload: null, readFailed: true };
+  }
+  if (
+    receipt.committedSemanticFingerprint === undefined &&
+    receipt.committedDigest !== undefined &&
+    snapshotDigest !== receipt.committedDigest
+  ) {
     log.warn(
       snapshotDigest == null
         ? `semantic-merge: merged-target promotion refused for ${merge.targetId} — the record snapshot digest is unavailable while the CAS receipt carries committed digest ${receipt.committedDigest}; promotion and reconciliation retry on the next merge`
@@ -210,11 +245,30 @@ export async function buildMergedTargetPromotionPayload(
         : snapshotDigest !== null
           ? { committedDigest: snapshotDigest }
           : {}),
+      ...(receipt.committedSemanticFingerprint !== undefined
+        ? { committedSemanticFingerprint: receipt.committedSemanticFingerprint }
+        : snapshotSemanticFingerprint !== null
+          ? { committedSemanticFingerprint: snapshotSemanticFingerprint }
+          : {}),
     },
     readFailed: false,
   };
 }
 
+/** #2870: canonical SEMANTIC fingerprint of a durable file's CURRENT
+ * bytes — the file text with access telemetry stripped
+ * ({@link canonicalSemanticFileText}), hashed exactly the way the CAS
+ * receipt records it at commit time. Null when the file cannot be read
+ * (fail-open, like readDurableFileDigest). */
+export async function readDurableSemanticFingerprint(filePath: string): Promise<string | null> {
+  try {
+    return createHash("sha256")
+      .update(canonicalSemanticFileText(await readFile(filePath, "utf8")))
+      .digest("hex");
+  } catch {
+    return null;
+  }
+}
 /** #2813 (P1 A): read the standing receipt as a three-way truth for the
  * promotion path. Present and absent are usable identities (absent = the
  * target predates the sidecar); unavailable is not. A storage whose status
@@ -223,7 +277,7 @@ export async function readPromotionReceiptStatus(
   storage: Pick<StorageManager, "readCasRevisionStatus">,
   filePath: string,
 ): Promise<
-  | { available: true; revision: string | undefined; committedDigest?: string }
+  | { available: true; revision: string | undefined; committedDigest?: string; committedSemanticFingerprint?: string }
   | { available: false; reason: string }
 > {
   try {
@@ -233,6 +287,8 @@ export async function readPromotionReceiptStatus(
       available: true,
       revision: status.status === "present" ? status.revision : undefined,
       committedDigest: status.status === "present" ? status.committedDigest : undefined,
+      committedSemanticFingerprint:
+        status.status === "present" ? status.committedSemanticFingerprint : undefined,
     };
   } catch (err) {
     return { available: false, reason: err instanceof Error ? err.message : String(err) };