From c002b89e2d8130a3c07e25e5fd604876be18c703 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Mon, 12 Oct 2026 05:24:20 +0800 Subject: [PATCH] fix(snapshot): bind replayed subjects to the selected target path Rebind display paths only for matching artifact identities in primitive and composed replay. Preserve semantic Evidence IDs, payloads, and historical snapshot provenance. Classify snapshot filesystem workflows as boundary tests. Validation: cache, direct workflow, MCP replay, and Evidence tests; combined checks and temporary-directory hygiene. Provider interactions are simulated for replay verification. --- .../binary/AnalysisSnapshotCache.test.ts | 57 ++++++++++++++++ .../binary/AnalysisSnapshotCache.ts | 33 ++++----- src/domain/analysisSnapshot.ts | 6 +- src/domain/evidence.ts | 52 +++++++++++++- .../directAnalysisSnapshotReplay.test.ts | 68 ++++++++++++++----- .../mcp/workflowSnapshotReplayMcp.test.ts | 59 +++++++++++++++- 6 files changed, 239 insertions(+), 36 deletions(-) rename tests/{composition => boundary/filesystem}/directAnalysisSnapshotReplay.test.ts (90%) diff --git a/src/application/binary/AnalysisSnapshotCache.test.ts b/src/application/binary/AnalysisSnapshotCache.test.ts index 847fc8f59..15f4e403c 100644 --- a/src/application/binary/AnalysisSnapshotCache.test.ts +++ b/src/application/binary/AnalysisSnapshotCache.test.ts @@ -115,6 +115,63 @@ it("exports independent nested query, workflow and Evidence payloads", () => { expect(serializeAnalysisSnapshot(fresh.value)).toBe(expected); }); +it("rebinds replayed target subjects while preserving child artifact subjects", () => { + const cache = new AnalysisSnapshotCache(); + const target = ANALYSIS_SNAPSHOT_TARGET; + const profile = ANALYSIS_SNAPSHOT_PROFILE; + const relocatedTarget = { ...target, path: "/tmp/relocated-app" }; + const parameters = { address: "0x1000" }; + const locations = [{ kind: "address" as const, address: "0x1000" }]; + cache.record({ + target, + profile, + operation: "procedure_info", + parameters, + execution: createAnalysisExecution( + { name: "main" }, + ANALYSIS_SNAPSHOT_PROVIDER, + { + subject: target, + rawResult: { provider: "raw" }, + locations, + analysisProfile: profile, + }, + ), + }); + + const replayedTarget = cache.lookup( + relocatedTarget, + profile, + "procedure_info", + parameters, + ); + expect(replayedTarget?.subject?.path).toBe(relocatedTarget.path); + expect(replayedTarget?.rawResult).toEqual({ provider: "raw" }); + expect(replayedTarget?.locations).toEqual(locations); + + const childSubject = { + path: "/tmp/child.zip", + sha256: "b".repeat(64), + format: "zip" as const, + }; + const childParameters = { address: "0x2000" }; + cache.record({ + target, + profile, + operation: "procedure_info", + parameters: childParameters, + execution: createAnalysisExecution( + { name: "child" }, + ANALYSIS_SNAPSHOT_PROVIDER, + { subject: childSubject, analysisProfile: profile }, + ), + }); + expect( + cache.lookup(relocatedTarget, profile, "procedure_info", childParameters) + ?.subject, + ).toMatchObject(childSubject); +}); + describe("analysis snapshot cache capacity", () => { it("shares capacity across query kinds while allowing replacements and fresh partitions", () => { const cache = new AnalysisSnapshotCache(); diff --git a/src/application/binary/AnalysisSnapshotCache.ts b/src/application/binary/AnalysisSnapshotCache.ts index c6f74b23a..cf5083e1a 100644 --- a/src/application/binary/AnalysisSnapshotCache.ts +++ b/src/application/binary/AnalysisSnapshotCache.ts @@ -8,6 +8,7 @@ import { } from "../../domain/evidenceErrors.js"; import { NoBinaryOpenError } from "../../domain/configurationErrors.js"; import type { AnalysisError } from "../../domain/analysisErrorBase.js"; +import { rebindEvidenceSubjectTargetPath } from "../../domain/evidence.js"; import { err, ok, type Result } from "../../domain/result.js"; import { analysisQueryId, @@ -277,7 +278,21 @@ export class AnalysisSnapshotCache { ); const cached = this.#entries.get(queryId); if (cached === undefined) return undefined; - const subject = cached.execution.subject; + const cachedSubject = cached.execution.subject; + const subject = + cachedSubject === null + ? null + : rebindEvidenceSubjectTargetPath( + { + path: cachedSubject.path, + sha256: cachedSubject.sha256, + format: cachedSubject.format, + ...(cachedSubject.architecture === null + ? {} + : { architecture: cachedSubject.architecture }), + }, + target, + ); return structuredClone({ result: cached.execution.result, rawResult: cached.execution.raw_result, @@ -288,21 +303,7 @@ export class AnalysisSnapshotCache { "Loaded from a local REA analysis snapshot; this call did not re-run the provider.", ], locations: cached.execution.locations, - subject: - subject === null - ? null - : subject.architecture === null - ? { - path: subject.path, - sha256: subject.sha256, - format: subject.format, - } - : { - path: subject.path, - sha256: subject.sha256, - format: subject.format, - architecture: subject.architecture, - }, + subject, }); } diff --git a/src/domain/analysisSnapshot.ts b/src/domain/analysisSnapshot.ts index d6ca67e85..e156144e9 100644 --- a/src/domain/analysisSnapshot.ts +++ b/src/domain/analysisSnapshot.ts @@ -27,6 +27,7 @@ import { } from "./evidenceBundle.js"; import { evidenceLocationSchema, + rebindEvidenceToTargetPath, type Evidence, type EvidenceLocation, type EvidenceSubjectTarget, @@ -411,7 +412,7 @@ export const snapshotEvidenceForQuery = ( (candidate) => candidate.query_id === queryId, ); if (entry === undefined && workflowEntry === undefined) return undefined; - return snapshot.evidence_bundle.records.find( + const evidence = snapshot.evidence_bundle.records.find( (record) => record.subject?.digest.sha256 === target.sha256 && record.operation === operation && @@ -425,6 +426,9 @@ export const snapshotEvidenceForQuery = ( (workflowEntry !== undefined && evidenceMatchesWorkflowEntry(record, workflowEntry, snapshot))), ); + return evidence === undefined + ? undefined + : rebindEvidenceToTargetPath(evidence, target); }; /** Create one exact replay record for a derived application workflow result. */ diff --git a/src/domain/evidence.ts b/src/domain/evidence.ts index 8edb9c897..dcfee98fd 100644 --- a/src/domain/evidence.ts +++ b/src/domain/evidence.ts @@ -1,3 +1,4 @@ +import { basename } from "node:path"; import { z } from "zod"; import { digestCanonicalValue } from "./canonicalDigest.js"; @@ -182,6 +183,18 @@ export interface EvidenceSubjectTarget { readonly format: z.infer["format"]; readonly architecture?: BinaryArchitecture; } + +/** Rebind a matching immutable artifact subject to the caller's selected path. */ +export const rebindEvidenceSubjectTargetPath = ( + subject: EvidenceSubjectTarget, + target: EvidenceSubjectTarget, +): EvidenceSubjectTarget => + subject.sha256 === target.sha256 && + subject.format === target.format && + (subject.architecture ?? null) === (target.architecture ?? null) + ? { ...subject, path: target.path } + : subject; + type EvidenceAuthority = z.infer; type ExecutionEnvironment = z.infer; @@ -252,6 +265,43 @@ export const parseEvidence = (input: unknown): Evidence => { export const immutableEvidence = (input: unknown): Evidence => rememberImmutableEvidence(parseEvidence(input)); +/** Rebind display path metadata when an authenticated record names this target. */ +export const rebindEvidenceToTargetPath = ( + evidence: Evidence, + target: EvidenceSubjectTarget, +): Evidence => { + const subject = evidence.subject; + if (subject === null) return evidence; + const rebound = rebindEvidenceSubjectTargetPath( + { + path: subject.local_path, + sha256: subject.digest.sha256, + format: subject.format, + ...(subject.architecture === null + ? {} + : { architecture: subject.architecture }), + }, + target, + ); + if (rebound.path === subject.local_path) return evidence; + const reboundSubject = subjectSchema.parse({ + ...subject, + name: basename(target.path) || "artifact", + local_path: target.path, + }); + const reboundEvidence = { ...evidence, subject: reboundSubject }; + if (!isImmutableEvidence(evidence)) return immutableEvidence(reboundEvidence); + + // The original authenticated Evidence owns immutable payloads. Only the + // small display subject and envelope are new, so preserve those payloads + // without reparsing a potentially large analysis result. + Object.freeze(reboundSubject.digest); + Object.freeze(reboundSubject); + Object.freeze(reboundEvidence); + immutableEvidenceSnapshots.set(reboundEvidence, reboundEvidence); + return reboundEvidence; +}; + /** Recognize authenticated Evidence whose complete reachable JSON data is immutable. */ export const isImmutableEvidence = (evidence: Evidence): boolean => immutableEvidenceSnapshots.has(evidence); @@ -316,7 +366,7 @@ const normalizeEvidenceObservation = ( target === undefined ? null : { - name: target.path.split("/").at(-1) || "artifact", + name: basename(target.path) || "artifact", digest: { sha256: target.sha256 }, format: target.format, architecture: target.architecture ?? null, diff --git a/tests/composition/directAnalysisSnapshotReplay.test.ts b/tests/boundary/filesystem/directAnalysisSnapshotReplay.test.ts similarity index 90% rename from tests/composition/directAnalysisSnapshotReplay.test.ts rename to tests/boundary/filesystem/directAnalysisSnapshotReplay.test.ts index 7da4ec8cf..6827340eb 100644 --- a/tests/composition/directAnalysisSnapshotReplay.test.ts +++ b/tests/boundary/filesystem/directAnalysisSnapshotReplay.test.ts @@ -1,48 +1,48 @@ -import { parseConfig } from "../../src/config/parseConfig.js"; +import { parseConfig } from "../../../src/config/parseConfig.js"; import { writeFile } from "node:fs/promises"; -import { join } from "node:path"; +import { basename, dirname, join } from "node:path"; import { describe, expect, it } from "vitest"; import { z } from "zod"; -import { runDirectAnalysis } from "../../src/application/DirectAnalysis.js"; +import { runDirectAnalysis } from "../../../src/application/DirectAnalysis.js"; import type { AnalysisProvider, CapabilityDescriptor, ProviderIdentity, -} from "../../src/application/AnalysisProvider.js"; -import type { DirectAnalysisDependencies } from "../../src/application/DirectAnalysisDependencies.js"; -import { createAnalysisProfile } from "../../src/domain/analysisProfile.js"; -import { createAnalysisExecution } from "../../src/application/AnalysisProvider.js"; -import { ok } from "../../src/domain/result.js"; +} from "../../../src/application/AnalysisProvider.js"; +import type { DirectAnalysisDependencies } from "../../../src/application/DirectAnalysisDependencies.js"; +import { createAnalysisProfile } from "../../../src/domain/analysisProfile.js"; +import { createAnalysisExecution } from "../../../src/application/AnalysisProvider.js"; +import { ok } from "../../../src/domain/result.js"; import { readAnalysisSnapshot, writeAnalysisSnapshot, -} from "../../src/application/binary/AnalysisSnapshotFiles.js"; +} from "../../../src/application/binary/AnalysisSnapshotFiles.js"; import { createEvidence, parseEvidence, type Evidence, -} from "../../src/domain/evidence.js"; -import { createEvidenceBundle } from "../../src/domain/evidenceBundle.js"; +} from "../../../src/domain/evidence.js"; +import { createEvidenceBundle } from "../../../src/domain/evidenceBundle.js"; import { REA_WORKFLOW_PROVIDER, workflowAnalysisProfile, -} from "../../src/application/InvestigationProviders.js"; +} from "../../../src/application/InvestigationProviders.js"; import { createAnalysisSnapshotWorkflowEntry, type AnalysisSnapshot, -} from "../../src/domain/analysisSnapshot.js"; +} from "../../../src/domain/analysisSnapshot.js"; import { createTestBinarySession, createTestProviderRouter, -} from "../fixtures/binarySession.js"; -import { BinarySession } from "../../src/application/binary/BinarySession.js"; -import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js"; +} from "../../fixtures/binarySession.js"; +import { BinarySession } from "../../../src/application/binary/BinarySession.js"; +import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; import { CAPABILITIES as GHIDRA_CAPABILITIES, GHIDRA_PROVIDER_IDENTITY, -} from "../../src/ghidra/GhidraProviderCapabilities.js"; +} from "../../../src/ghidra/GhidraProviderCapabilities.js"; const IDENTITY = { id: "snapshot-fixture", @@ -550,6 +550,40 @@ describe("binary overview snapshot replay", () => { expect(second).toEqual(first); expect(fixture.calls.toSorted()).toEqual(operations.toSorted()); expect(fixture.starts).toHaveLength(1); + + const relocatedPath = join(dirname(fixture.path), "relocated.hop"); + await writeFile(relocatedPath, "fixture"); + const relocated = await runDirectAnalysis( + dependencies, + relocatedPath, + "binary_overview", + {}, + { snapshotPath: fixture.snapshotPath }, + ); + const firstEvidence = parseEvidence(first); + const relocatedEvidence = parseEvidence(relocated); + expect(relocatedEvidence).toMatchObject({ + evidence_id: firstEvidence.evidence_id, + subject: { + local_path: relocatedPath, + name: basename(relocatedPath), + }, + }); + expect(relocatedEvidence.normalized_result).toEqual( + firstEvidence.normalized_result, + ); + expect(relocatedEvidence.raw_result).toEqual(firstEvidence.raw_result); + expect(relocatedEvidence.locations).toEqual(firstEvidence.locations); + expect(fixture.calls.toSorted()).toEqual(operations.toSorted()); + expect(fixture.starts).toHaveLength(1); + + const persisted = await readAnalysisSnapshot(fixture.snapshotPath); + if (!persisted.ok) throw persisted.error; + expect( + persisted.value.evidence_bundle.records.find( + (record) => record.evidence_id === firstEvidence.evidence_id, + )?.subject?.local_path, + ).toBe(fixture.path); }); }); diff --git a/tests/boundary/mcp/workflowSnapshotReplayMcp.test.ts b/tests/boundary/mcp/workflowSnapshotReplayMcp.test.ts index f9dd142d9..d5ecd00d2 100644 --- a/tests/boundary/mcp/workflowSnapshotReplayMcp.test.ts +++ b/tests/boundary/mcp/workflowSnapshotReplayMcp.test.ts @@ -1,6 +1,6 @@ import { parseConfig } from "../../../src/config/parseConfig.js"; import { writeFile } from "node:fs/promises"; -import { join } from "node:path"; +import { dirname, join } from "node:path"; import { Client, InMemoryTransport } from "@modelcontextprotocol/client"; import { afterEach, describe, expect, it } from "vitest"; @@ -136,6 +136,20 @@ describe("MCP composed workflow snapshot replay", () => { }) .passthrough() .parse(output); + const primitiveResult = await mcp.callTool({ + name: "list_strings", + arguments: { document: "fixture" }, + }); + expect( + primitiveResult.isError, + JSON.stringify(primitiveResult.content), + ).not.toBe(true); + const primitiveEvidence = toolContract("list_strings").outputSchema.parse( + primitiveResult.structuredContent, + ); + expect(primitiveEvidence).toMatchObject({ + subject: { local_path: targetPath }, + }); const afterAnalysisCalls = [...calls]; const afterAnalysisStarts = [...starts]; @@ -163,6 +177,47 @@ describe("MCP composed workflow snapshot replay", () => { }), ); + const relocatedPath = join(dirname(targetPath), "relocated.hop"); + await writeFile(relocatedPath, "fixture.hop"); + const reopened = await mcp.callTool({ + name: "open_binary", + arguments: { path: relocatedPath, snapshot_path: snapshotPath }, + }); + expect(reopened.isError, JSON.stringify(reopened.content)).not.toBe(true); + const cachedPrimitive = await mcp.callTool({ + name: "list_strings", + arguments: { document: "fixture" }, + }); + expect( + cachedPrimitive.isError, + JSON.stringify(cachedPrimitive.content), + ).not.toBe(true); + const cachedEvidence = toolContract("list_strings").outputSchema.parse( + cachedPrimitive.structuredContent, + ); + expect(cachedEvidence).toMatchObject({ + subject: { local_path: relocatedPath }, + }); + expect(cachedEvidence.normalized_result).toEqual( + primitiveEvidence.normalized_result, + ); + expect(cachedEvidence.raw_result).toEqual(primitiveEvidence.raw_result); + const retained = await mcp.callTool({ + name: "get_evidence_bundle", + arguments: {}, + }); + expect(retained.isError, JSON.stringify(retained.content)).not.toBe(true); + const retainedBundle = toolContract( + "get_evidence_bundle", + ).outputSchema.parse(retained.structuredContent).result; + expect( + retainedBundle.records.find( + ({ evidence_id }) => evidence_id === primitiveEvidence.evidence_id, + )?.subject?.local_path, + ).toBe(targetPath); + expect(calls).toEqual(afterAnalysisCalls); + expect(starts).toEqual(afterAnalysisStarts); + const dependencies: DirectAnalysisDependencies = { readConfiguration: () => parseConfig({}), createBinarySession: () => createWorkflowSession(provider), @@ -180,7 +235,9 @@ describe("MCP composed workflow snapshot replay", () => { expect(calls).toEqual(afterAnalysisCalls); expect(starts).toEqual(afterAnalysisStarts); }); +}); +describe("MCP live workflow snapshot policy", () => { it("does not bind a workflow when an upstream operation is live", async () => { const { targetPaths, snapshotPath } = await createWorkflowFiles( "rea-mcp-live-workflow-snapshot-",