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
This commit is contained in:
morluto authored and GitHub committed 2026-11-15 22:25:52 -05:00
1 parent 5d283a6e4a
commit 81fe44d7d8
4 files changed
+175 -58

No files matched your search

+9 -19
View File
@@ -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 <Value>(
+60 -1
View File
@@ -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<Record<string, JsonValue>>,
@@ -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<Record<string, JsonValue>>,
execution: AnalysisExecution,
options: CompletedOperationEvidenceOptions,
): Result<Evidence, AnalysisError> => {
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",
),
);
};
+15 -38
View File
@@ -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);
@@ -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);
});