fix(cache): scope Evidence display refresh to matching snapshot bindings

src/application/binary/AnalysisSnapshotCache.test.ts

@@ -30,6 +30,7 @@ import {
   SNAPSHOT_CACHE_ENTRY_CEILING,
   isSnapshotCacheable,
 } from "./AnalysisSnapshotCache.js";
+import { EvidenceLedger } from "../investigation/EvidenceLedger.js";
 import { enhancedOutputSchemas } from "../../contracts/toolOutputSchemaGroups.js";
 
 it("exports independent nested query, workflow and Evidence payloads", () => {
@@ -116,6 +117,120 @@ it("exports independent nested query, workflow and Evidence payloads", () => {
   expect(serializeAnalysisSnapshot(fresh.value)).toBe(expected);
 });
 
+it.each(["provider", "workflow"] as const)(
+  "refreshes only the authenticated %s display dependency and preserves earlier snapshots",
+  (kind) => {
+    const cache = new AnalysisSnapshotCache();
+    const ledger = new EvidenceLedger();
+    const target = ANALYSIS_SNAPSHOT_TARGET;
+    const profile = ANALYSIS_SNAPSHOT_PROFILE;
+    const parameters = { address: "0x1000", document: "fixture" };
+    const operation =
+      kind === "provider" ? "procedure_info" : "analyze_function";
+    const provider =
+      kind === "provider" ? ANALYSIS_SNAPSHOT_PROVIDER : REA_WORKFLOW_PROVIDER;
+    const evidenceProfile =
+      kind === "provider" ? profile : workflowAnalysisProfile(profile);
+    const dependencies = [1, 2].map((source) =>
+      createEvidence(target, provider, {
+        operation: "source",
+        parameters: { source },
+        result: source,
+      }),
+    );
+    for (const dependency of dependencies)
+      expect(ledger.record(dependency).ok).toBe(true);
+    const evidence = createEvidence(target, provider, {
+      operation,
+      parameters,
+      evidenceLinks: dependencies.map(({ evidence_id }) => evidence_id),
+      result: "original",
+      analysisProfile: evidenceProfile,
+      confidence: kind === "provider" ? "observed" : "derived",
+    });
+    const execution = createAnalysisExecution("original", provider, {
+      subject: target,
+      analysisProfile: evidenceProfile,
+    });
+    if (kind === "provider")
+      cache.record({ target, profile, operation, parameters, execution });
+    else
+      cache.recordWorkflow({
+        target,
+        profile,
+        operation,
+        parameters,
+        execution: { ...execution, analysisProfile: evidenceProfile },
+      });
+    expect(ledger.record(evidence).ok).toBe(true);
+    const before = cache.export(target, profile, ledger.export());
+    if (!before.ok) throw before.error;
+    const nameOnly = {
+      ...evidence,
+      subject:
+        evidence.subject === null
+          ? null
+          : { ...evidence.subject, name: "display-only-name" },
+    };
+    const nameImport = ledger.import(createEvidenceBundle([nameOnly]));
+    if (!nameImport.ok) throw nameImport.error;
+    cache.refreshEvidenceDisplay(nameImport.value.replacements);
+    expect(cache.entries()).toEqual(before.value.entries);
+    expect(cache.workflowEntries()).toEqual(before.value.workflow_entries);
+    // A different observation for this exact query is not the entry's dependency.
+    const alternative = createEvidence(target, provider, {
+      operation,
+      parameters,
+      result: "alternative",
+      analysisProfile: evidenceProfile,
+      confidence: kind === "provider" ? "observed" : "derived",
+    });
+    expect(ledger.record(alternative).ok).toBe(true);
+    const relocate = (record: typeof evidence) => {
+      if (record.subject === null) throw new Error("Expected fixture subject");
+      return {
+        ...record,
+        subject: {
+          ...record.subject,
+          local_path: "/relocated/fixture",
+          name: "renamed",
+        },
+      };
+    };
+    const foreign = ledger.import(
+      createEvidenceBundle([relocate(alternative)]),
+    );
+    if (!foreign.ok) throw foreign.error;
+    cache.refreshEvidenceDisplay(foreign.value.replacements);
+    expect(cache.entries()).toEqual(before.value.entries);
+    expect(cache.workflowEntries()).toEqual(before.value.workflow_entries);
+    // A result may cite several observations; updating their envelopes does not change its payload.
+    const dependentImport = ledger.import(
+      createEvidenceBundle(dependencies.map(relocate)),
+    );
+    if (!dependentImport.ok) throw dependentImport.error;
+    cache.refreshEvidenceDisplay(dependentImport.value.replacements);
+    expect(cache.entries()).toEqual(before.value.entries);
+    expect(cache.workflowEntries()).toEqual(before.value.workflow_entries);
+    const relocated = relocate(evidence);
+    const imported = ledger.import(createEvidenceBundle([relocated]));
+    if (!imported.ok) throw imported.error;
+    cache.refreshEvidenceDisplay(imported.value.replacements);
+    const after = cache.export(target, profile, ledger.export());
+    if (!after.ok) throw after.error;
+    const entries =
+      kind === "provider" ? after.value.entries : after.value.workflow_entries;
+    expect(entries[0]?.execution.subject?.path).toBe("/relocated/fixture");
+    expect(entries[0]?.execution.result).toBe("original");
+    expect(after.value.evidence_bundle.records).toContainEqual(relocated);
+    const originalEntries =
+      kind === "provider"
+        ? before.value.entries
+        : before.value.workflow_entries;
+    expect(originalEntries[0]?.execution.subject?.path).toBe(target.path);
+  },
+);
+
 it("counts newly retained direct and workflow bindings when staging", () => {
   const source = new AnalysisSnapshotCache();
   const target = ANALYSIS_SNAPSHOT_TARGET;

src/application/binary/AnalysisSnapshotCache.ts

@@ -13,6 +13,8 @@ import { rebindEvidenceSubjectTargetPath } from "../../domain/evidence.js";
 import { err, ok, type Result } from "../../domain/result.js";
 import {
   analysisQueryId,
+  evidenceMatchesEntry,
+  evidenceMatchesWorkflowEntry,
   createAnalysisSnapshotEntry,
   createAnalysisSnapshotWorkflowEntry,
   snapshotBinding,
@@ -35,6 +37,8 @@ import type {
 import { OFFICIAL_TOOL_CONTRACTS } from "../../contracts/officialToolContracts.js";
 import { compareUnicodeCodePoints } from "../../domain/unicodeCodePointOrder.js";
 
+import type { EvidenceDisplayReplacement } from "../investigation/EvidenceLedger.js";
+
 const RELATIONSHIP_OPERATIONS: ReadonlySet<AnalysisOperation> = new Set([
   "procedure_callers",
   "procedure_callees",
@@ -148,6 +152,59 @@ export class AnalysisSnapshotCache {
     return imported;
   }
 
+  /** Refresh only display bindings backed by the replaced authenticated records. */
+  refreshEvidenceDisplay(
+    replacements: readonly EvidenceDisplayReplacement[],
+  ): void {
+    if (this.#target === undefined || this.#binding === undefined) return;
+    const header = { target: this.#target, binding: this.#binding };
+    for (const { previous, current } of replacements) {
+      if (
+        current.subject === null ||
+        previous.subject?.local_path === current.subject.local_path
+      )
+        continue;
+      const queryId = analysisQueryId(
+        header.target,
+        header.binding,
+        previous.operation,
+        previous.parameters,
+      );
+      const entry = this.#entries.get(queryId);
+      if (
+        entry !== undefined &&
+        entry.execution.subject !== null &&
+        evidenceMatchesEntry(previous, entry, header)
+      )
+        this.#entries.set(queryId, {
+          ...entry,
+          execution: {
+            ...entry.execution,
+            subject: {
+              ...entry.execution.subject,
+              path: current.subject.local_path,
+            },
+          },
+        });
+      const workflow = this.#workflowEntries.get(queryId);
+      if (
+        workflow !== undefined &&
+        workflow.execution.subject !== null &&
+        evidenceMatchesWorkflowEntry(previous, workflow, header)
+      )
+        this.#workflowEntries.set(queryId, {
+          ...workflow,
+          execution: {
+            ...workflow.execution,
+            subject: {
+              ...workflow.execution.subject,
+              path: current.subject.local_path,
+            },
+          },
+        });
+    }
+  }
+
   /** Build a complete snapshot for an active target. */
   export(
     target: BinaryTarget | undefined,

src/application/binary/BinarySessionRecords.ts

@@ -150,8 +150,8 @@ export abstract class BinarySessionRecords {
   ): Result<number, EvidenceIntegrityError | AnalysisInputError> {
     const imported = this.#records.mergeEvidenceBundle(bundle);
     if (!imported.ok) return imported;
-    if (imported.value.metadataChanged) this.invalidateSnapshot();
-    else if (imported.value.changed) this.#emitSnapshotChanged();
+    this.#snapshot.refreshEvidenceDisplay(imported.value.replacements);
+    if (imported.value.changed) this.#emitSnapshotChanged();
     return ok(imported.value.recordsAdded);
   }
 
@@ -238,7 +238,9 @@ export abstract class BinarySessionRecords {
           : { target: active.target, profile },
       (bundle) => {
         const imported = this.#records.mergeEvidenceBundle(bundle);
-        return imported.ok ? ok(imported.value.recordsAdded) : imported;
+        if (!imported.ok) return imported;
+        this.#snapshot.refreshEvidenceDisplay(imported.value.replacements);
+        return ok(imported.value.recordsAdded);
       },
     );
     if (imported.ok) this.#emitSnapshotChanged();

src/application/investigation/EvidenceLedger.residualUnknown.test.ts

@@ -140,7 +140,7 @@ describe("residual unknown registry reads and identity", () => {
         recordsAdded: 1,
         unknownsAdded: 0,
         changed: true,
-        metadataChanged: false,
+        replacements: [],
       },
     });
     expect(store.export().unknowns).toEqual(originalUnknowns);
@@ -150,7 +150,7 @@ describe("residual unknown registry reads and identity", () => {
         recordsAdded: 0,
         unknownsAdded: 0,
         changed: false,
-        metadataChanged: false,
+        replacements: [],
       },
     });
   });
@@ -189,7 +189,7 @@ describe("residual unknown dependency histories", () => {
         recordsAdded: 10_000,
         unknownsAdded: 10_000,
         changed: true,
-        metadataChanged: false,
+        replacements: [],
       },
     });
     expect(store.export()).toEqual(bundle);

src/application/investigation/EvidenceLedger.test.ts

@@ -43,7 +43,7 @@ describe("evidence ledger recording", () => {
         recordsAdded: 0,
         unknownsAdded: 0,
         changed: false,
-        metadataChanged: false,
+        replacements: [],
       },
     });
     expect(ledger.export().records).toEqual([evidence]);
@@ -60,7 +60,13 @@ describe("evidence ledger recording", () => {
         recordsAdded: 0,
         unknownsAdded: 0,
         changed: true,
-        metadataChanged: true,
+        replacements: [
+          {
+            kind: "subject-display",
+            previous: evidence,
+            current: relocatedBundleRecord,
+          },
+        ],
       },
     });
     expect(ledger.get(evidence.evidence_id)).toEqual(relocatedBundleRecord);
@@ -73,7 +79,7 @@ describe("evidence ledger recording", () => {
         recordsAdded: 0,
         unknownsAdded: 0,
         changed: false,
-        metadataChanged: false,
+        replacements: [],
       },
     });
     const conflictingBundle = createEvidenceBundle([
@@ -111,7 +117,7 @@ describe("evidence ledger recording", () => {
         recordsAdded: 0,
         unknownsAdded: 0,
         changed: false,
-        metadataChanged: false,
+        replacements: [],
       },
     });
     ledger.clear();
@@ -194,7 +200,13 @@ describe("evidence ledger metadata imports", () => {
         recordsAdded: 0,
         unknownsAdded: 0,
         changed: true,
-        metadataChanged: true,
+        replacements: [
+          {
+            kind: "subject-display",
+            previous: mutation,
+            current: relocatedMutation,
+          },
+        ],
       },
     });
     expect(ledger.get(mutation.evidence_id)).toEqual(relocatedMutation);
@@ -204,7 +216,7 @@ describe("evidence ledger metadata imports", () => {
         recordsAdded: 0,
         unknownsAdded: 0,
         changed: false,
-        metadataChanged: false,
+        replacements: [],
       },
     });
   });

src/application/investigation/EvidenceLedger.ts

@@ -30,12 +30,19 @@ import { analysisInputErrorFromIssues } from "../../domain/inputIssueProjection.
 type EvidenceLedgerFailure = EvidenceIntegrityError;
 type RecordResult = Result<"added" | "duplicate", EvidenceLedgerFailure>;
 
-/** Describes the state changes made by one atomic bundle import. */
+/** Same authenticated semantic identity with new subject display metadata. */
+export interface EvidenceDisplayReplacement {
+  readonly kind: "subject-display";
+  readonly previous: Evidence;
+  readonly current: Evidence;
+}
+
+/** Committed changes made by one atomic bundle import. */
 export interface EvidenceImportDelta {
   readonly recordsAdded: number;
   readonly unknownsAdded: number;
   readonly changed: boolean;
-  readonly metadataChanged: boolean;
+  readonly replacements: readonly EvidenceDisplayReplacement[];
 }
 
 type ImportResult = Result<
@@ -96,8 +103,7 @@ export class EvidenceLedger {
     // atomic merge without rebuilding and reparsing the entire ledger.
     if (bundle.unknowns.length === 0) {
       const additions = new Map<string, Evidence>();
-      const replacements = new Map<string, Evidence>();
-      let metadataChanged = false;
+      const replacements: EvidenceDisplayReplacement[] = [];
       for (const evidence of bundle.records) {
         const existing = this.#records.get(evidence.evidence_id);
         if (existing !== undefined) {
@@ -105,35 +111,39 @@ export class EvidenceLedger {
             return err(
               new EvidenceIntegrityError("Conflicting evidence record"),
             );
-          if (canonicalize(existing) !== canonicalize(evidence)) {
-            replacements.set(evidence.evidence_id, evidence);
-            metadataChanged = true;
+          if (!displaySubjectsAgree(existing, evidence)) {
+            replacements.push({
+              kind: "subject-display",
+              previous: existing,
+              current: evidence,
+            });
           }
           continue;
         }
         additions.set(evidence.evidence_id, evidence);
       }
-      for (const [id, evidence] of replacements)
-        this.#records.set(id, evidence);
+      for (const { current } of replacements)
+        this.#records.set(current.evidence_id, current);
       for (const [id, evidence] of additions) this.#records.set(id, evidence);
       return ok({
         recordsAdded: additions.size,
         unknownsAdded: 0,
-        changed: additions.size > 0 || metadataChanged,
-        metadataChanged,
+        changed: additions.size > 0 || replacements.length > 0,
+        replacements,
       });
     }
     const pending = new Map(this.#records);
-    let metadataChanged = false;
+    const replacements: EvidenceDisplayReplacement[] = [];
     for (const evidence of bundle.records) {
       const existing = pending.get(evidence.evidence_id);
       if (existing !== undefined && !recordsAgree(existing, evidence))
         return err(new EvidenceIntegrityError("Conflicting evidence record"));
-      if (
-        existing !== undefined &&
-        canonicalize(existing) !== canonicalize(evidence)
-      )
-        metadataChanged = true;
+      if (existing !== undefined && !displaySubjectsAgree(existing, evidence))
+        replacements.push({
+          kind: "subject-display",
+          previous: existing,
+          current: evidence,
+        });
       pending.set(evidence.evidence_id, evidence);
     }
     const pendingUnknowns = new Map(this.#unknownRevisions);
@@ -162,8 +172,8 @@ export class EvidenceLedger {
     return ok({
       recordsAdded: added,
       unknownsAdded,
-      changed: added > 0 || unknownsAdded > 0 || metadataChanged,
-      metadataChanged,
+      changed: added > 0 || unknownsAdded > 0 || replacements.length > 0,
+      replacements,
     });
   }
 
@@ -518,3 +528,7 @@ const withoutLocalPath = (evidence: Evidence): Evidence => ({
           local_path: "<non-identity-local-path>",
         },
 });
+
+const displaySubjectsAgree = (left: Evidence, right: Evidence): boolean =>
+  left.subject?.name === right.subject?.name &&
+  left.subject?.local_path === right.subject?.local_path;

src/application/investigation/InvestigationEvidence.test.ts

@@ -43,7 +43,9 @@ it.each(["immutable", "detached"] as const)(
       createEvidenceBundle([replacement]),
     );
     if (!merged.ok) throw merged.error;
-    expect(merged.value.metadataChanged).toBe(true);
+    expect(merged.value.replacements).toEqual([
+      { kind: "subject-display", previous: first, current: replacement },
+    ]);
     expect(lookup(first.evidence_id)?.subject?.local_path).toBe("/moved");
     expect(
       investigationEvidenceBundle(reader).records[0]?.subject?.local_path,

src/application/investigation/InvestigationRecords.test.ts

@@ -158,7 +158,7 @@ describe("investigation record ownership", () => {
         recordsAdded: 0,
         unknownsAdded: 1,
         changed: true,
-        metadataChanged: false,
+        replacements: [],
       },
     });
     expect(records.mergeEvidenceBundle(bundle)).toEqual({
@@ -167,7 +167,7 @@ describe("investigation record ownership", () => {
         recordsAdded: 0,
         unknownsAdded: 0,
         changed: false,
-        metadataChanged: false,
+        replacements: [],
       },
     });
     records.clear();

src/domain/analysisSnapshot.ts

@@ -529,7 +529,8 @@ export const createAnalysisSnapshotWorkflowEntry = (input: {
   };
 };
 
-const evidenceMatchesEntry = (
+/** Match an authenticated Evidence record to one exact provider cache binding. */
+export const evidenceMatchesEntry = (
   evidence: Evidence,
   entry: AnalysisSnapshotEntry,
   snapshot: Pick<AnalysisSnapshot, "target" | "binding">,
@@ -871,7 +872,8 @@ const isWorkflowEvidence = (
   evidence.provider.name === entry.execution.provider.name &&
   evidence.provider.version === entry.execution.provider.version;
 
-const evidenceMatchesWorkflowEntry = (
+/** Match an authenticated Evidence record to one exact composed cache binding. */
+export const evidenceMatchesWorkflowEntry = (
   evidence: Evidence,
   entry: AnalysisSnapshotWorkflowEntry,
   snapshot: Pick<AnalysisSnapshot, "target">,