refactor(mcp): bind artifact and bundle comparison through a derived binding that acquires under the artifact resource scope (#11554)

* refactor(mcp): bind artifact and bundle comparison through an acquiring derived binding that owns their artifact resource scope

compare_artifacts and compare_bundles registered bespoke handlers that read caller-named files under the server's artifact resource scope and then repeated the session-derived delivery. The derived binding kind now takes an optional acquisition with the resource scope it reads under; the table passes the scope, the readers open and release handles in it (failed releases stay owned for retry), and acquisition failures are delivered unchanged. The artifact unknown and the bundle Evidence moved to application owners.

* fix(mcp): return a bundle comparison's record-pair failure as a typed Result

bundleComparisonExecution declared a Result but let compareBundles throw AnalysisInputError for missing or repeated record pairs. It now returns the typed failure; unexpected errors still propagate.
This commit is contained in:
morluto authored and GitHub committed 2026-11-16 07:03:36 +08:00
1 parent a447161a84
commit f6df353002
11 files changed
+369 -297

No files matched your search

@@ -33,6 +33,8 @@ import {
sameTargetIdentity,
unknownTarget,
} from "../../domain/targetIdentity.js";
import type { RecordUnknownInput } from "../../domain/residualUnknown.js";
import type { InvestigationWorkflowExecution } from "../investigation/InvestigationWorkflows.js";
const OPERATION = "compare_artifacts";
@@ -199,3 +201,65 @@ const mismatch = (): Result<never, EvidenceIntegrityError> =>
`Artifact summary does not match its retained parent inventory. A summary from an earlier Evidence format no longer matches. ${RECREATE_EVIDENCE_GUIDANCE}`,
),
);
/**
* Compare resolved inventories for a session: the derived Evidence, both
* sources to retain, and the residual question a changed, unknown or
* truncated comparison leaves.
*/
export const artifactComparisonExecution = (
sources: ArtifactComparisonSources,
): Result<InvestigationWorkflowExecution, AnalysisError> => {
const compared = compareArtifactEvidence(sources);
if (!compared.ok) return compared;
const { left, right } = sources;
const { comparison, evidence } = compared.value;
return ok({
evidence,
sources: [left, right],
unknown: artifactUnknownInput(
left,
right,
comparison,
evidence.evidence_id,
),
});
};
const artifactUnknownInput = (
left: { readonly evidence_id: string },
right: { readonly evidence_id: string },
comparison: ArtifactComparisonResult,
comparisonEvidenceId: string,
): RecordUnknownInput | undefined => {
const { status } = comparison;
if (status === "unchanged") return undefined;
const sourceIds = [...new Set([left.evidence_id, right.evidence_id])];
const contradictingIds = comparison.integrity_mismatch_evidence_ids ?? [];
const contentContradictions =
status === "changed" && left.evidence_id !== right.evidence_id
? [right.evidence_id]
: [];
const contradictions =
contradictingIds.length > 0 ? contradictingIds : contentContradictions;
return {
question: `Artifact comparison is ${status} (comparison ${comparisonEvidenceId})`,
severity:
status === "unknown" || status === "truncated" ? "high" : "medium",
domain: "artifact-comparison",
supporting_evidence_ids: sourceIds.filter(
(id) => !contradictions.includes(id),
),
contradicting_evidence_ids: contradictions,
required_authority: "shipped-artifact",
required_confidence: "observed",
required_environment: null,
recommended_probes: [
{
operation: "inspect_artifact",
rationale: "Inspect both artifacts and compare their complete graphs.",
},
],
relationships: [],
};
};
@@ -0,0 +1,43 @@
import { expect, it } from "vitest";
import { AnalysisInputError } from "../../domain/analysisErrorCore.js";
import { createEvidence } from "../../domain/evidence.js";
import { createEvidenceBundle } from "../../domain/evidenceBundle.js";
import { unknownTarget } from "../../domain/targetIdentity.js";
import { bundleComparisonExecution } from "./BundleComparisonEvidence.js";
const PROVIDER = { id: "fixture", name: "Fixture", version: "1" } as const;
const evidence = (label: string) =>
createEvidence(unknownTarget("not-observed"), PROVIDER, {
operation: "observe",
parameters: { label },
result: { label },
confidence: "derived",
authority: "analyst-inference",
});
it("returns a missing record pair as a typed input failure", () => {
const leftRecord = evidence("left");
const rightRecord = evidence("right");
const left = createEvidenceBundle([leftRecord]);
const right = createEvidenceBundle([rightRecord]);
const failed = bundleComparisonExecution({
left,
right,
recordPairs: [
{
left_evidence_id: evidence("missing").evidence_id,
right_evidence_id: rightRecord.evidence_id,
},
],
});
expect(failed.ok).toBe(false);
if (failed.ok) throw new Error("Expected a failure");
expect(failed.error).toBeInstanceOf(AnalysisInputError);
const compared = bundleComparisonExecution({ left, right, recordPairs: [] });
if (!compared.ok) throw compared.error;
expect(compared.value.sources).toEqual([leftRecord, rightRecord]);
expect(compared.value.evidence.evidence_links).toEqual(
expect.arrayContaining([leftRecord.evidence_id, rightRecord.evidence_id]),
);
});
@@ -0,0 +1,100 @@
import { bundleComparisonMcpInputSchema } from "../../contracts/sessionToolSchemas.js";
import { AnalysisError } from "../../domain/analysisErrorBase.js";
import { compareBundles } from "../../domain/bundleComparison.js";
import { createEvidence } from "../../domain/evidence.js";
import type { EvidenceBundle } from "../../domain/evidenceBundle.js";
import { BUNDLE_COMPARISON_PROVIDER } from "../../domain/investigationProviders.js";
import { err, ok, type Result } from "../../domain/result.js";
import { unknownTarget } from "../../domain/targetIdentity.js";
import type { ArtifactResourceScope } from "../../resources/index.js";
import { parseAnalysisInput } from "../AnalysisInput.js";
import { readComparisonEvidenceBundles } from "../EvidenceBundleFiles.js";
import type { InvestigationWorkflowExecution } from "./InvestigationWorkflows.js";
const OPERATION = "compare_bundles";
/** Both bundles a session comparison reads, and the pairs the caller declared. */
export interface BundleComparisonSources {
readonly left: EvidenceBundle;
readonly right: EvidenceBundle;
readonly recordPairs: Parameters<typeof compareBundles>[2];
}
/**
* Read both caller-named bundles under the resource scope. The bundle reader
* opens and releases each file in that scope, which keeps a handle whose
* release failed for a later cleanup retry.
*/
export const readBundleComparisonSources = async (
input: unknown,
options: {
readonly signal: AbortSignal;
readonly resources: ArtifactResourceScope;
},
): Promise<Result<BundleComparisonSources, AnalysisError>> => {
const request = parseAnalysisInput(
OPERATION,
input,
bundleComparisonMcpInputSchema,
options.signal,
);
if (!request.ok) return request;
const loaded = await readComparisonEvidenceBundles(
request.value.left_bundle_path,
request.value.right_bundle_path,
options.signal,
options.resources,
OPERATION,
);
if (!loaded.ok) return loaded;
return ok({ ...loaded.value, recordPairs: request.value.record_pairs });
};
/**
* Compare two bundles for a session. Every record of either bundle is a
* source the session retains, and the derived Evidence links each one.
*/
export const bundleComparisonExecution = ({
left,
right,
recordPairs,
}: BundleComparisonSources): Result<
InvestigationWorkflowExecution,
AnalysisError
> => {
let comparison: ReturnType<typeof compareBundles>;
try {
comparison = compareBundles(left, right, recordPairs);
} catch (cause: unknown) {
// Missing or repeated record pairs are typed input failures.
if (cause instanceof AnalysisError) return err(cause);
throw cause;
}
const sources = [
...new Map(
[...left.records, ...right.records].map((record) => [
record.evidence_id,
record,
]),
).values(),
];
const evidence = createEvidence(
unknownTarget("derived-from-linked-evidence"),
BUNDLE_COMPARISON_PROVIDER,
{
predicateType: "rea.bundle-comparison",
operation: OPERATION,
parameters: {
left_bundle_sha256: comparison.left_bundle_sha256,
right_bundle_sha256: comparison.right_bundle_sha256,
record_pairs: recordPairs,
},
result: comparison,
confidence: "derived",
authority: "analyst-inference",
limitations: comparison.limitations,
evidenceLinks: sources.map(({ evidence_id }) => evidence_id),
},
);
return ok({ evidence, sources, unknown: undefined });
};