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-",