feat(mcp)!: harden contracts and evidence references

BREAKING CHANGE: comparison tools now require session-owned Evidence IDs or approved bundle paths, and structured Evidence results use compact references.
This commit is contained in:
morluto
2026-07-16 19:49:58 +08:00
parent ad398a17f5
commit ee1cd40405
47 changed files with 1387 additions and 672 deletions
+40 -60
View File
@@ -1,16 +1,16 @@
import type { McpServer } from "@modelcontextprotocol/server";
import canonicalize from "canonicalize";
import { z } from "zod";
import type { BinarySessionPort } from "../application/BinarySession.js";
import { SESSION_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
import {
processComparisonInputSchema,
SESSION_TOOL_CONTRACTS,
} from "../contracts/toolContracts.js";
import { createEvidence } from "../domain/evidence.js";
import { EvidenceIntegrityError } from "../domain/errors.js";
import { jsonValueSchema } from "../domain/jsonValue.js";
import type { RecordUnknownInput } from "../domain/residualUnknown.js";
import {
compareProcessCaptures,
processCaptureSchema,
parseProcessCapture,
} from "../domain/processCapture.js";
import { recordDerivedEvidence } from "./recordDerivedEvidence.js";
@@ -19,6 +19,8 @@ import { PROCESS_PROVIDER } from "./sessionToolPolicies.js";
import { toCallToolResult } from "./toolResult.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { runDerivedOperation } from "./runDerivedOperation.js";
import { safeParseToolInput } from "./toolInputValidation.js";
import { resolveSessionEvidenceIds } from "./sessionEvidence.js";
/** Register deterministic process-capture comparison and contradiction tracking. */
export const registerProcessComparisonTool = (
@@ -31,22 +33,41 @@ export const registerProcessComparisonTool = (
contract.name,
toolRegistrationOptions(contract),
async (input, context) => {
const parsed = z
.object({
left_evidence_id: z.string(),
left: processCaptureSchema,
right_evidence_id: z.string(),
right: processCaptureSchema,
max_capture_age_ms: z.number().int().nonnegative().optional(),
unknown_registry_approved: z.literal(true).optional(),
})
.parse(input);
const validated = validateCaptureSources(session, parsed);
if (!validated.ok) return toCallToolResult(validated, contract);
const parsedInput = safeParseToolInput(
processComparisonInputSchema,
input,
contract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, contract);
const parsed = parsedInput.value;
const expected = {
operation: "capture_process_scenario",
predicate: "rea.process-capture/v4",
};
const leftRecord = resolveSessionEvidenceIds(
session,
[parsed.left_evidence_id],
expected,
);
if (!leftRecord.ok) return toCallToolResult(leftRecord, contract);
const rightRecord = resolveSessionEvidenceIds(
session,
[parsed.right_evidence_id],
expected,
);
if (!rightRecord.ok) return toCallToolResult(rightRecord, contract);
let comparison: ReturnType<typeof compareProcessCaptures>;
let leftCapture: ReturnType<typeof parseProcessCapture>;
let rightCapture: ReturnType<typeof parseProcessCapture>;
try {
leftCapture = parseProcessCapture(
leftRecord.value[0]?.normalized_result,
);
rightCapture = parseProcessCapture(
rightRecord.value[0]?.normalized_result,
);
const computed = await runDerivedOperation(context, contract.name, () =>
compareProcessCaptures(parsed.left, parsed.right, {
compareProcessCaptures(leftCapture, rightCapture, {
...(parsed.max_capture_age_ms === undefined
? {}
: { maxCaptureAgeMs: parsed.max_capture_age_ms }),
@@ -73,8 +94,8 @@ export const registerProcessComparisonTool = (
parameters: {
left_evidence_id: parsed.left_evidence_id,
right_evidence_id: parsed.right_evidence_id,
left_normalization: parsed.left.normalization,
right_normalization: parsed.right.normalization,
left_normalization: leftCapture.normalization,
right_normalization: rightCapture.normalization,
},
result: jsonValueSchema.parse(comparison),
confidence: "derived",
@@ -94,47 +115,6 @@ export const registerProcessComparisonTool = (
);
};
const validateCaptureSources = (
session: BinarySessionPort,
parsed: {
readonly left_evidence_id: string;
readonly left: z.infer<typeof processCaptureSchema>;
readonly right_evidence_id: string;
readonly right: z.infer<typeof processCaptureSchema>;
},
) => {
for (const [evidenceId, capture] of [
[parsed.left_evidence_id, parsed.left],
[parsed.right_evidence_id, parsed.right],
] as const) {
const evidence = session.evidenceById(evidenceId);
let evidenceCapture: z.infer<typeof processCaptureSchema> | undefined;
try {
evidenceCapture = parseProcessCapture(evidence?.normalized_result);
} catch {
evidenceCapture = undefined;
}
if (
evidence === undefined ||
evidence.operation !== "capture_process_scenario" ||
evidence.predicate_type !== "rea.process-capture/v4" ||
evidence.provider.id !== PROCESS_PROVIDER.id ||
evidence.provider.name !== PROCESS_PROVIDER.name ||
evidence.provider.version !== PROCESS_PROVIDER.version ||
evidence.confidence !== "observed" ||
evidence.authority !== "controlled-replay" ||
evidenceCapture === undefined ||
canonicalize(evidenceCapture) !== canonicalize(capture)
)
return err(
new EvidenceIntegrityError(
"Process comparison payload does not match its source Evidence",
),
);
}
return { ok: true as const, value: null };
};
const comparisonUnknownInput = (
parsed: {
readonly left_evidence_id: string;