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.
This commit is contained in:
morluto
2026-10-12 05:24:20 +08:00
parent 2260887f20
commit c002b89e2d
6 changed files with 239 additions and 36 deletions
@@ -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();
+17 -16
View File
@@ -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,
});
}
+5 -1
View File
@@ -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. */
+51 -1
View File
@@ -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<typeof subjectSchema>["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<typeof evidenceAuthoritySchema>;
type ExecutionEnvironment = z.infer<typeof executionEnvironmentSchema>;
@@ -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,
@@ -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);
});
});
@@ -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-",