From 81fe44d7d8e97c8b445db6b4c33ae3cc9357cf10 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Mon, 16 Nov 2026 11:25:52 +0800 Subject: [PATCH] refactor(evidence): build a completed provider operation's Evidence in one owner (#11673) * test(adapters): compare CLI and MCP Evidence for every CLI analysis operation Run each official, workflow, native, artifact and managed operation that has a CLI command through the CLI command tree and the MCP server over one simulated provider, and require identical Evidence or failure. The differences main has today are recorded per operation so the W2 invoke path can only remove them. Split bindDirectAnalysis(dependencies) out of createDirectAnalysis so the CLI can run over injected session owners. * test(adapters): give each parity case its own CLI and MCP connection * refactor(evidence): build a completed provider operation's Evidence in one owner The CLI's DirectAnalysis and the MCP provider-operation handler each defaulted the subject, admitted the completed analysis and created the Evidence. completedOperationEvidence in SessionEvidenceReuse now does it for both, reusing the record the session issued for the same execution and parameters. The session-Evidence lookup is no longer exported. * test(evidence): deliver the record a one-shot Ghidra decompile session issued --- src/application/DirectAnalysis.ts | 28 ++---- .../binary/SessionEvidenceReuse.ts | 61 ++++++++++++- src/server/providerOperationToolHandler.ts | 53 +++-------- .../directAnalysisEvidenceReuse.test.ts | 91 +++++++++++++++++++ 4 files changed, 175 insertions(+), 58 deletions(-) create mode 100644 tests/composition/directAnalysisEvidenceReuse.test.ts diff --git a/src/application/DirectAnalysis.ts b/src/application/DirectAnalysis.ts index f015b4f920..c1e67d3227 100644 --- a/src/application/DirectAnalysis.ts +++ b/src/application/DirectAnalysis.ts @@ -2,7 +2,7 @@ import { admitOneShotOperation, type DirectAnalysisTool, } from "./oneShotOperationInput.js"; -import { admitCompletedAnalysis } from "./investigation/admitCompletedAnalysis.js"; +import { completedOperationEvidence } from "./binary/SessionEvidenceReuse.js"; import type { EspFlashSelection } from "../domain/firmware/espFlashLocation.js"; import type { ExecutableFormatHint } from "../domain/dosCom.js"; import { dispatchQueuedInterrupts } from "../process/queuedInterrupts.js"; @@ -794,27 +794,17 @@ const executeAnalysisTool = async (input: { ); } if (!result.ok) return result; - const observation = { - ...result.value, - subject: - result.value.subject === undefined - ? input.openedTarget - : result.value.subject, - }; - const admitted = admitCompletedAnalysis( + const evidence = completedOperationEvidence( tool, input.evidenceParameters, - observation, - session.admitRecoveryObservation.bind(session), + result.value, + { + target: input.openedTarget, + admitRecovery: session.admitRecoveryObservation.bind(session), + evidenceById: (id) => session.evidenceForAnalysis(id), + }, ); - if (!admitted.ok) return admitted; - const evidence = createAnalysisExecutionEvidence( - tool, - input.evidenceParameters, - observation, - "observed", - ); - return ok({ evidence }); + return evidence.ok ? ok({ evidence: evidence.value }) : evidence; }; const withProcessCancellation = async ( diff --git a/src/application/binary/SessionEvidenceReuse.ts b/src/application/binary/SessionEvidenceReuse.ts index e5d5415698..8e6a77b292 100644 --- a/src/application/binary/SessionEvidenceReuse.ts +++ b/src/application/binary/SessionEvidenceReuse.ts @@ -4,6 +4,12 @@ import type { AnalysisExecution } from "../../ports/AnalysisProvider.js"; import type { Evidence } from "../../domain/evidence.js"; import type { JsonValue } from "../../domain/jsonValue.js"; import { equalJsonText } from "../../domain/jsonSerialization.js"; +import type { AnalysisError } from "../../domain/analysisErrorBase.js"; +import { createAnalysisExecutionEvidence } from "../../domain/analysisObservation.js"; +import type { BinaryTarget } from "../../domain/binaryTargetTypes.js"; +import { ok, type Result } from "../../domain/result.js"; +import { admitCompletedAnalysis } from "../investigation/admitCompletedAnalysis.js"; +import type { RecoveryAdmission } from "../investigation/InvestigationRetention.js"; // Proof belongs to the exact object issued by the session. A wrapper that // copies or transforms the observation cannot carry it forward. @@ -54,7 +60,7 @@ export const bindSessionEvidenceExecution = ( return result; }; -export const sessionEvidenceForExecution = ( +const sessionEvidenceForExecution = ( execution: AnalysisExecution, operation: string, parameters: Readonly>, @@ -70,3 +76,56 @@ export const sessionEvidenceForExecution = ( return undefined; return evidence; }; + +/** How one completed session execution becomes Evidence. */ +export interface CompletedOperationEvidenceOptions { + /** The subject when the provider names none. */ + readonly target: BinaryTarget | null; + readonly admitRecovery?: RecoveryAdmission | undefined; + /** The session's records, to reuse the record it issued for this call. */ + readonly evidenceById?: ((id: string) => Evidence | undefined) | undefined; +} + +/** + * The Evidence of one completed provider operation, built once for every + * adapter: the record the session issued for this exact execution and + * parameters when it holds one, else a new record admitted against the + * completed analysis. + */ +export const completedOperationEvidence = ( + operation: string, + parameters: Readonly>, + execution: AnalysisExecution, + options: CompletedOperationEvidenceOptions, +): Result => { + const reusable = + options.evidenceById === undefined + ? undefined + : sessionEvidenceForExecution( + execution, + operation, + parameters, + options.evidenceById, + ); + if (reusable !== undefined) return ok(reusable); + const observation = { + ...execution, + subject: + execution.subject === undefined ? options.target : execution.subject, + }; + const admitted = admitCompletedAnalysis( + operation, + parameters, + observation, + options.admitRecovery, + ); + if (!admitted.ok) return admitted; + return ok( + createAnalysisExecutionEvidence( + operation, + parameters, + observation, + "observed", + ), + ); +}; diff --git a/src/server/providerOperationToolHandler.ts b/src/server/providerOperationToolHandler.ts index 83fd10ea97..aa0dcb51a9 100644 --- a/src/server/providerOperationToolHandler.ts +++ b/src/server/providerOperationToolHandler.ts @@ -4,7 +4,7 @@ import type { } from "@modelcontextprotocol/server"; import type { Logger } from "pino"; -import { sessionEvidenceForExecution } from "../application/binary/SessionEvidenceReuse.js"; +import { completedOperationEvidence } from "../application/binary/SessionEvidenceReuse.js"; import type { EvidenceLookup } from "../application/EvidenceInputResolver.js"; import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js"; import { @@ -17,10 +17,8 @@ import type { } from "../ports/AnalysisProvider.js"; import type { ToolContract } from "../contracts/toolContractTypes.js"; import { ok } from "../domain/result.js"; -import { admitCompletedAnalysis } from "../application/investigation/admitCompletedAnalysis.js"; import type { RecoveryAdmission } from "../application/investigation/InvestigationRetention.js"; import type { BinaryTarget } from "../domain/binaryTargetTypes.js"; -import { createAnalysisExecutionEvidence } from "../domain/analysisObservation.js"; import { jsonObjectSchema, type JsonValue } from "../domain/jsonValue.js"; import type { EvidenceMcpServer } from "./EvidenceMcpServer.js"; import { mcpProgressReporter } from "./mcpProgress.js"; @@ -131,42 +129,21 @@ export const createProviderOperationToolHandler = contract.retainedSummary?.evidenceParameters === "omit-detail" ? providerParameters : parameters; - const observation = { - ...execution.value, - subject: - execution.value.subject === undefined - ? (options.activeTarget?.() ?? null) - : execution.value.subject, - }; - const reusable = - dependencies.evidenceById === undefined - ? undefined - : sessionEvidenceForExecution( - execution.value, - operation, - evidenceParameters, - dependencies.evidenceById, - ); - if (reusable === undefined) { - const admitted = admitCompletedAnalysis( - operation, - evidenceParameters, - observation, - options.admitRecovery, - ); - if (!admitted.ok) - return server.delivery.toCallToolResult(admitted, contract); - } - const evidence = - reusable ?? - createAnalysisExecutionEvidence( - operation, - evidenceParameters, - observation, - "observed", - ); + const evidence = completedOperationEvidence( + operation, + evidenceParameters, + execution.value, + { + target: options.activeTarget?.() ?? null, + admitRecovery: options.admitRecovery, + evidenceById: dependencies.evidenceById, + }, + ); + if (!evidence.ok) + return server.delivery.toCallToolResult(evidence, contract); const projected = - delivery?.projectEvidence(parameters, evidence) ?? ok(evidence); + delivery?.projectEvidence(parameters, evidence.value) ?? + ok(evidence.value); if (!projected.ok) return server.delivery.toCallToolResult(projected, contract); const recorded = dependencies.recordEvidence?.(projected.value); diff --git a/tests/composition/directAnalysisEvidenceReuse.test.ts b/tests/composition/directAnalysisEvidenceReuse.test.ts new file mode 100644 index 0000000000..a4748d1232 --- /dev/null +++ b/tests/composition/directAnalysisEvidenceReuse.test.ts @@ -0,0 +1,91 @@ +import { writeFile } from "node:fs/promises"; +import { join } from "node:path"; + +import { expect, it, vi } from "vitest"; + +import { runDirectAnalysis } from "../../src/application/DirectAnalysis.js"; +import type { DirectAnalysisDependencies } from "../../src/application/DirectAnalysisDependencies.js"; +import { BinarySession } from "../../src/application/binary/BinarySession.js"; +import { parseConfig } from "../../src/config/parseConfig.js"; +import { createAnalysisProfile } from "../../src/domain/analysisProfile.js"; +import { ok } from "../../src/domain/result.js"; +import { + createAnalysisExecution, + type AnalysisProvider, +} from "../../src/ports/AnalysisProvider.js"; +import { createTestProviderRouter } from "../fixtures/binarySession.js"; +import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js"; + +// `rea decompile --snapshot` with Ghidra: the session retains the one-shot +// pseudocode as Evidence, so the CLI has a record to reuse. +const GHIDRA = { id: "ghidra", name: "Ghidra", version: "1" } as const; + +const ghidraFixture: AnalysisProvider = { + identity: () => GHIDRA, + capabilities: () => [ + { + provider: GHIDRA, + operation: "procedure_pseudo_code", + available: true, + reason: null, + cachePolicy: "snapshot", + effects: { + mutatesArtifact: false, + launchesProcess: false, + mayShowUi: false, + mayAccessNetwork: false, + mayWriteFilesystem: false, + changesPermissions: false, + requiresRoot: false, + }, + limitations: [], + }, + ], + createClient: () => ({ + execute: async () => ok(createAnalysisExecution("int main(void);", GHIDRA)), + close: async () => ok(null), + }), +}; + +it("delivers the record a profiled one-shot session issued and admits it once", async () => { + const directory = await createTestTempDirectory("rea-direct-reuse-"); + const path = join(directory, "fixture.com"); + await writeFile(path, Buffer.from([0xb8, 0, 0x4c, 0xcd, 0x21])); + const session = new BinarySession( + createTestProviderRouter(ghidraFixture, { + resolveAnalysisProfile: async () => + ok({ profile: createAnalysisProfile(GHIDRA, {}) }), + }), + ); + const admit = vi.spyOn(session, "admitRecoveryObservation"); + let issued: string | undefined; + const record = session.recordEvidence.bind(session); + vi.spyOn(session, "recordEvidence").mockImplementation((evidence) => { + issued ??= evidence.evidence_id; + return record(evidence); + }); + const create = () => session; + const dependencies: DirectAnalysisDependencies = { + readConfiguration: () => parseConfig({}), + createBinarySession: create, + createNativeDispatchBinarySession: create, + createArtifactBinarySession: create, + createNativeBinarySession: create, + createManagedBinarySession: create, + }; + + const result = await runDirectAnalysis( + dependencies, + path, + "procedure_pseudo_code", + { procedure: "0x100" }, + { formatHint: "dos-com", snapshotPath: join(directory, "snapshot.json") }, + ); + + if (!result.ok) throw new Error(JSON.stringify(result.error)); + // The CLI delivers the session's record with its own path, not a copy. + expect(issued).toBeDefined(); + expect(result.value.evidence_id).toBe(issued); + expect(result.value.caller_input_path).toBe(path); + expect(admit).toHaveBeenCalledTimes(1); +});