rea-agents 1.2.0 → 1.3.0

package/dist/server/promptCompletion.js

@@ -0,0 +1,144 @@
+import { z } from "zod";
+import { artifactInventoryResultSchema } from "../domain/artifactGraph.js";
+import { parseAddressedPage } from "../domain/hopperValues.js";
+import { processCaptureSchema, validateProcessCapture, } from "../domain/processCapture.js";
+const COMPLETION_SCAN_LIMIT = 10_000;
+const PROCEDURE_PAGE_SIZE = 500;
+const MAX_COMPLETION_VALUE_LENGTH = 4_096;
+const documentListSchema = z.array(z.string().min(1));
+const providerStatusSchema = z.object({
+    providers: z.array(z.object({ id: z.string().min(1) })),
+});
+/** Build bounded live completion over the active provider and session ledger. */
+export const createPromptCompletionSource = (analysis, session) => ({
+    async complete(kind, value, context) {
+        if (value.length > MAX_COMPLETION_VALUE_LENGTH)
+            return [];
+        const candidates = await completionCandidates(kind, analysis, session, context);
+        const prefix = normalize(value);
+        return uniqueSorted(candidates)
+            .filter((candidate) => normalize(candidate).startsWith(prefix))
+            .slice(0, COMPLETION_SCAN_LIMIT);
+    },
+});
+const completionCandidates = async (kind, analysis, session, context) => {
+    switch (kind) {
+        case "document":
+            return documentCandidates(analysis);
+        case "procedure":
+            return procedureCandidates(analysis, context?.arguments?.document);
+        case "provider":
+            return providerCandidates(session);
+        case "evidence":
+        case "capture":
+        case "manifest":
+        case "occurrence":
+            return evidenceCandidates(kind, session);
+        case "unknown":
+            return unknownCandidates(session);
+    }
+};
+const documentCandidates = async (analysis) => {
+    const result = await analysis.execute("list_documents", {});
+    if (!result.ok)
+        return [];
+    const parsed = documentListSchema.safeParse(result.value.result);
+    return parsed.success ? parsed.data.slice(0, COMPLETION_SCAN_LIMIT) : [];
+};
+const procedureCandidates = async (analysis, document) => {
+    if (document !== undefined && document.length > MAX_COMPLETION_VALUE_LENGTH)
+        return [];
+    const byAddress = new Map();
+    let offset = 0;
+    let exhaustive = false;
+    while (byAddress.size < COMPLETION_SCAN_LIMIT / 2) {
+        const result = await analysis.execute("list_procedures", {
+            offset,
+            limit: PROCEDURE_PAGE_SIZE,
+            ...(document === undefined || document.length === 0 ? {} : { document }),
+        });
+        if (!result.ok)
+            break;
+        const parsed = parseAddressedPage(result.value.result);
+        if (!parsed.ok)
+            break;
+        for (const item of parsed.value.items) {
+            if (byAddress.size >= COMPLETION_SCAN_LIMIT / 2)
+                break;
+            if (!byAddress.has(item.address))
+                byAddress.set(item.address, item.name);
+        }
+        const nextOffset = parsed.value.nextOffset;
+        if (!parsed.value.hasMore) {
+            exhaustive = true;
+            break;
+        }
+        if (nextOffset === null || nextOffset <= offset)
+            break;
+        offset = nextOffset;
+    }
+    const addressesByName = new Map();
+    for (const [address, name] of byAddress) {
+        const addresses = addressesByName.get(name) ?? new Set();
+        addresses.add(address);
+        addressesByName.set(name, addresses);
+    }
+    const candidates = [...byAddress.keys()];
+    if (exhaustive)
+        for (const [name, addresses] of addressesByName)
+            if (addresses.size === 1 && name.length > 0)
+                candidates.push(name);
+    return candidates;
+};
+const providerCandidates = (session) => {
+    if (session === undefined)
+        return [];
+    const parsed = providerStatusSchema.safeParse(session.status());
+    return parsed.success
+        ? parsed.data.providers.map(({ id }) => id).slice(0, COMPLETION_SCAN_LIMIT)
+        : [];
+};
+const evidenceCandidates = (kind, session) => {
+    if (session === undefined)
+        return [];
+    const candidates = [];
+    for (const evidence of session.exportEvidenceBundle().records) {
+        const remaining = COMPLETION_SCAN_LIMIT - candidates.length;
+        candidates.push(...evidenceValues(kind, evidence).slice(0, remaining));
+        if (candidates.length >= COMPLETION_SCAN_LIMIT)
+            break;
+    }
+    return candidates;
+};
+const evidenceValues = (kind, evidence) => {
+    if (kind === "evidence")
+        return [evidence.evidence_id];
+    if (kind === "capture")
+        return isProcessCaptureEvidence(evidence) ? [evidence.evidence_id] : [];
+    if (evidence.operation !== "inventory_artifact")
+        return [];
+    const inventory = artifactInventoryResultSchema.safeParse(evidence.normalized_result);
+    if (!inventory.success)
+        return [];
+    if (kind === "manifest")
+        return [inventory.data.manifest.manifest_id];
+    return inventory.data.occurrences.items.map(({ occurrence_id: id }) => id);
+};
+const isProcessCaptureEvidence = (evidence) => {
+    if (evidence.operation !== "capture_process_scenario")
+        return false;
+    const capture = processCaptureSchema.safeParse(evidence.normalized_result);
+    return capture.success && validateProcessCapture(capture.data).length === 0;
+};
+const unknownCandidates = (session) => session === undefined
+    ? []
+    : session
+        .listUnknowns()
+        .filter(({ status }) => status !== "resolved")
+        .map(({ unknown_id: id }) => id)
+        .slice(0, COMPLETION_SCAN_LIMIT);
+const uniqueSorted = (values) => [
+    ...new Set(values.filter((value) => value.length > 0 && value.length <= MAX_COMPLETION_VALUE_LENGTH)),
+].sort(compareText);
+const compareText = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+const normalize = (value) => value.normalize("NFKC").toLowerCase();

package/dist/server/registerEnhancedTools.js

@@ -4,7 +4,7 @@ import { ENHANCED_TOOL_CONTRACTS, } from "../contracts/toolContracts.js";
 import { toCallToolResult } from "./toolResult.js";
 import { logToolExecution } from "./toolLogging.js";
 import { createEvidence } from "../domain/evidence.js";
-import { jsonValueSchema } from "../domain/jsonValue.js";
+import { jsonObjectSchema } from "../domain/jsonValue.js";
 import { enhancedInputSchemas } from "../contracts/enhancedInputs.js";
 import { UnknownRegistryError } from "../domain/errors.js";
 const WORKFLOW_PROVIDER = {
@@ -32,11 +32,7 @@ const registerEnhancedTool = (server, services, contract, registration) => {
         outputSchema: contract.outputSchema,
         annotations: contract.annotations,
     }, async (input, context) => {
-        const parsedInput = jsonValueSchema.parse(enhancedInputSchemas[name].parse(input));
-        if (typeof parsedInput !== "object" ||
-            parsedInput === null ||
-            Array.isArray(parsedInput))
-            throw new Error("Validated enhanced input was not a JSON object");
+        const parsedInput = jsonObjectSchema.parse(enhancedInputSchemas[name].parse(input));
         const parameters = { ...parsedInput };
         const result = await logToolExecution(registration.logger, name, () => services.execute(name, input, context.mcpReq.signal));
         if (result.ok) {

package/dist/server/registerEvidenceTools.js

@@ -1,5 +1,5 @@
 import { createEvidence } from "../domain/evidence.js";
-import { jsonValueSchema } from "../domain/jsonValue.js";
+import { jsonObjectSchema } from "../domain/jsonValue.js";
 import { logToolExecution } from "./toolLogging.js";
 import { toCallToolResult } from "./toolResult.js";
 import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
@@ -7,7 +7,7 @@ import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
 export const registerEvidenceTools = (server, analysis, contracts, options) => {
     for (const contract of contracts) {
         server.registerTool(contract.name, toolRegistrationOptions(contract), async (input, context) => {
-            const parameters = jsonObject(contract.inputSchema.parse(input));
+            const parameters = jsonObjectSchema.parse(contract.inputSchema.parse(input));
             const execution = await logToolExecution(options.logger, contract.name, () => analysis.execute(contract.name, parameters, {
                 signal: context.mcpReq.signal,
             }));
@@ -28,9 +28,3 @@ export const registerEvidenceTools = (server, analysis, contracts, options) => {
         });
     }
 };
-const jsonObject = (input) => {
-    const parsed = jsonValueSchema.parse(input);
-    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
-        throw new TypeError("Provider tool input was not an object");
-    return parsed;
-};

package/dist/server/registerFunctionComparisonTool.js

@@ -59,7 +59,7 @@ const functionUnknownInput = ({ approved, status, leftIds, rightIds, }) => {
         recommended_probes: [
             {
                 operation: "analyze_function",
-                rationale: "Capture complete dossiers with equal providers and analysis limits.",
+                rationale: "Capture complete dossiers for both functions under the same target context and analysis limits.",
             },
         ],
         relationships: [],

package/dist/server/registerInvestigationTools.js

@@ -1,7 +1,8 @@
+import { runCrossVersionInvestigation } from "../application/CrossVersionInvestigation.js";
 import { buildCallPath, callPathInputSchema } from "../domain/callPath.js";
 import { correlateStaticAndRuntime, staticRuntimeCorrelationInputSchema, } from "../domain/staticRuntimeCorrelation.js";
 import { reconstructionVerificationInputSchema, verifyReconstruction, } from "../domain/reconstructionVerification.js";
-import { changedBehaviorInputSchema, findChangedBehavior, } from "../domain/changedBehavior.js";
+import { changedBehaviorResultSchema, changedBehaviorInputSchema, findChangedBehavior, } from "../domain/changedBehavior.js";
 import { createEvidence } from "../domain/evidence.js";
 import { EvidenceIntegrityError } from "../domain/errors.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
@@ -10,15 +11,35 @@ import { CALL_PATH_PROVIDER, CHANGED_BEHAVIOR_PROVIDER, RECONSTRUCTION_PROVIDER,
 import { toCallToolResult } from "./toolResult.js";
 import { recordDerivedEvidence } from "./recordDerivedEvidence.js";
 /** Register Evidence-composed differential investigation workflows. */
-export const registerInvestigationTools = (server, session, contracts) => {
-    registerChangedBehavior(server, session, contracts[0]);
+export const registerInvestigationTools = (server, session, contracts, policies) => {
+    registerChangedBehavior(server, session, contracts[0], policies);
     registerCallPath(server, session, contracts[1]);
     registerStaticRuntime(server, session, contracts[2]);
     registerReconstruction(server, session, contracts[3]);
 };
-const registerChangedBehavior = (server, session, contract) => {
-    server.registerTool(contract.name, contractOptions(contract), (input) => {
+const investigationExecution = (session, signal, inputRoots) => ({ session, signal, inputRoots });
+const isIncomplete = (status) => status === "unknown" || status === "truncated";
+const registerChangedBehavior = (server, session, contract, policies) => {
+    server.registerTool(contract.name, contractOptions(contract), async (input, context) => {
         const parsed = changedBehaviorInputSchema.parse(input);
+        if (parsed.investigation_run !== undefined) {
+            const investigated = await runCrossVersionInvestigation(parsed.investigation_run, policies.evidenceFiles, investigationExecution(session, context.mcpReq.signal, policies.inputRoots));
+            if (!investigated.ok)
+                return toCallToolResult(investigated, contract);
+            const result = changedBehaviorResultSchema.parse(investigated.value.evidence.normalized_result);
+            return toCallToolResult(recordWorkflowEvidence(session, investigated.value.evidence, parsed.unknown_registry_approved, isIncomplete(result.behavior_status), {
+                question: `Automatic changed behavior run ${result.investigation_run?.run_id ?? "unknown"} remains ${result.behavior_status}`,
+                domain: "changed-behavior",
+                requiredAuthority: "controlled-replay",
+                requiredConfidence: "observed",
+                probes: [
+                    {
+                        operation: "capture_process_scenario",
+                        rationale: "Capture both versions under the same bounded scenario and environment.",
+                    },
+                ],
+            }), contract);
+        }
         const closure = evidenceClosure(session, comparisonClosure(parsed.comparisons));
         if (!closure.ok)
             return toCallToolResult(closure, contract);
@@ -38,9 +59,8 @@ const registerChangedBehavior = (server, session, contract) => {
             limitations: result.limitations,
             evidenceLinks: links,
         });
-        const recorded = recordWorkflowEvidence(session, evidence, parsed.unknown_registry_approved, result.behavior_status === "unknown" ||
-            result.behavior_status === "truncated", {
-            question: `Changed behavior result ${evidence.evidence_id} remains ${result.behavior_status}`,
+        const recorded = recordWorkflowEvidence(session, evidence, parsed.unknown_registry_approved, isIncomplete(result.behavior_status), {
+            question: "Did both versions behave the same under a complete controlled replay?",
             domain: "changed-behavior",
             requiredAuthority: "controlled-replay",
             requiredConfidence: "observed",
@@ -80,7 +100,7 @@ const registerCallPath = (server, session, contract) => {
             evidenceLinks: links,
         });
         const recorded = recordWorkflowEvidence(session, evidence, parsed.unknown_registry_approved, result.status === "unknown" || result.status === "truncated", {
-            question: `Call path ${parsed.start.address} → ${parsed.goal.address} is ${result.status}`,
+            question: "Can the requested call path be established from complete analysis?",
             domain: "call-path",
             requiredAuthority: "shipped-artifact",
             requiredConfidence: "derived",
@@ -120,7 +140,7 @@ const registerStaticRuntime = (server, session, contract) => {
             evidenceLinks: links,
         });
         return toCallToolResult(recordWorkflowEvidence(session, evidence, parsed.unknown_registry_approved, result.status === "unknown" || result.status === "truncated", {
-            question: `Static/runtime correlation result ${evidence.evidence_id} is ${result.status}`,
+            question: "Does runtime behavior match the available static analysis?",
             domain: "static-runtime-correlation",
             requiredAuthority: null,
             requiredConfidence: "derived",
@@ -163,7 +183,7 @@ const registerReconstruction = (server, session, contract) => {
             evidenceLinks: links,
         });
         return toCallToolResult(recordWorkflowEvidence(session, evidence, parsed.unknown_registry_approved, result.status === "unknown", {
-            question: `Reconstruction ${result.specification_sha256} has unknown claims`,
+            question: "Does the reconstruction satisfy every declared claim?",
             domain: "reconstruction-verification",
             requiredAuthority: null,
             requiredConfidence: "derived",

package/dist/server/registerOfficialTools.js

@@ -1,5 +1,5 @@
 import { OFFICIAL_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
-import { jsonValueSchema } from "../domain/jsonValue.js";
+import { jsonObjectSchema, jsonValueSchema, } from "../domain/jsonValue.js";
 import { toCallToolResult } from "./toolResult.js";
 import { logToolExecution } from "./toolLogging.js";
 import { createEvidence } from "../domain/evidence.js";
@@ -45,9 +45,9 @@ const registerOfficialTool = (server, analysis, contract, registration) => {
             registration.recordUnknown !== undefined) {
             const unknown = registration.recordUnknown({
                 approved: true,
-                question: `${contract.name} is unavailable: ${result.error.reason}`,
+                question: "The requested analysis is unavailable for the current target.",
                 severity: "medium",
-                domain: "provider-capability",
+                domain: "analysis-capability",
                 supporting_evidence_ids: [],
                 contradicting_evidence_ids: [],
                 required_authority: "shipped-artifact",
@@ -56,7 +56,7 @@ const registerOfficialTool = (server, analysis, contract, registration) => {
                 recommended_probes: [
                     {
                         operation: contract.name,
-                        rationale: "Use a provider that declares this capability available.",
+                        rationale: "Choose another analysis or target that can answer this question.",
                     },
                 ],
                 relationships: [],
@@ -70,19 +70,12 @@ const registerOfficialTool = (server, analysis, contract, registration) => {
     });
 };
 const projectOfficialArguments = (contract, input) => {
-    const parsed = jsonValueSchema.safeParse(input);
-    if (!parsed.success ||
-        typeof parsed.data !== "object" ||
-        parsed.data === null ||
-        Array.isArray(parsed.data)) {
-        // The SDK validates this with the same schema before invoking the callback.
-        throw new Error("Validated MCP tool input was not a JSON object");
-    }
+    const parsed = jsonObjectSchema.parse(contract.inputSchema.parse(input));
     const projected = {};
     for (const key of Object.keys(contract.inputSchema.shape)) {
         if (key === "unknown_registry_approved")
             continue;
-        projected[key] = parsed.data[key] ?? null;
+        projected[key] = jsonValueSchema.parse(parsed[key] ?? null);
     }
     return projected;
 };

package/dist/server/registerProcessComparisonTool.js

@@ -80,17 +80,11 @@ const validateCaptureSources = (session, parsed) => {
             evidence.confidence !== "observed" ||
             evidence.authority !== "controlled-replay" ||
             evidenceCapture === undefined ||
-            canonicalJson(evidenceCapture) !== canonicalJson(capture))
+            canonicalize(evidenceCapture) !== canonicalize(capture))
             return err(new EvidenceIntegrityError("Process comparison payload does not match its source Evidence"));
     }
     return { ok: true, value: null };
 };
-const canonicalJson = (value) => {
-    const encoded = canonicalize(value);
-    if (encoded === undefined)
-        throw new TypeError("Process capture could not be canonicalized");
-    return encoded;
-};
 const comparisonUnknownInput = (parsed, comparison) => {
     if (parsed.unknown_registry_approved !== true ||
         comparison.status === "unchanged")

package/dist/server/registerPrompts.js

@@ -0,0 +1,67 @@
+import { completable, } from "@modelcontextprotocol/server";
+import { z } from "zod";
+import { PROMPT_CONTRACTS, renderGuidedPrompt, } from "../contracts/promptContracts.js";
+import { createPromptCompletionSource, } from "./promptCompletion.js";
+const promptValuesSchema = z.record(z.string(), z.string());
+/** Register every guided workflow and its session-scoped argument completers. */
+export const registerGuidedPrompts = (server, analysis, session) => {
+    const completion = createPromptCompletionSource(analysis, session);
+    const prompts = new Map();
+    for (const contract of PROMPT_CONTRACTS)
+        prompts.set(contract.name, registerPrompt(server, contract, completion));
+    return {
+        update(contract) {
+            const prompt = prompts.get(contract.name);
+            if (prompt === undefined)
+                throw new RangeError(`Unknown guided prompt ${contract.name}`);
+            const argsSchema = promptArgumentsSchema(contract, completion);
+            prompt.update({
+                title: contract.title,
+                description: contract.description,
+                argsSchema,
+                callback: (arguments_) => promptResult(contract, arguments_),
+            });
+        },
+    };
+};
+const registerPrompt = (server, contract, completion) => {
+    const argsSchema = promptArgumentsSchema(contract, completion);
+    return server.registerPrompt(contract.name, {
+        title: contract.title,
+        description: contract.description,
+        argsSchema,
+    }, (arguments_) => promptResult(contract, arguments_));
+};
+const promptArgumentsSchema = (contract, completion) => {
+    const shape = {};
+    for (const [name, argument] of Object.entries(contract.arguments))
+        shape[name] = argumentSchema(argument, completion);
+    return z.object(shape);
+};
+const argumentSchema = (argument, completion) => {
+    const value = z
+        .string()
+        .trim()
+        .min(1)
+        .max(4_096)
+        .describe(argument.description);
+    const kind = argument.completion;
+    const completed = kind === undefined
+        ? value
+        : completable(value, async (partial, context) => [
+            ...(await completion.complete(kind, partial, context)),
+        ]);
+    return argument.required ? completed : completed.optional();
+};
+const promptResult = (contract, arguments_) => ({
+    description: contract.description,
+    messages: [
+        {
+            role: "user",
+            content: {
+                type: "text",
+                text: renderGuidedPrompt(contract, promptValuesSchema.parse(arguments_)),
+            },
+        },
+    ],
+});

package/dist/server/registerSessionStatusTool.js

@@ -0,0 +1,11 @@
+import { SESSION_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
+import { toCallToolResult } from "./toolResult.js";
+/** Register the read-only provider and target status operation. */
+export const registerSessionStatusTool = (server, session, contract) => {
+    server.registerTool(contract.name, {
+        description: contract.description,
+        inputSchema: contract.inputSchema,
+        outputSchema: contract.outputSchema,
+        annotations: contract.annotations,
+    }, () => toCallToolResult({ ok: true, value: session.status() }, contract));
+};

package/dist/server/registerSessionTools.js

@@ -7,6 +7,7 @@ import { processScenarioSchema } from "../domain/processCapture.js";
 import { captureProcessScenario } from "../application/ProcessHarness.js";
 import { recordUnknownInputSchema, updateUnknownInputSchema, } from "../domain/residualUnknown.js";
 import { readEvidenceBundle, writeEvidenceBundle, } from "../application/EvidenceBundleFiles.js";
+import { readAnalysisSnapshot, writeAnalysisSnapshot, } from "../application/AnalysisSnapshotFiles.js";
 import { UnknownRegistryError } from "../domain/errors.js";
 import { DENY_EVIDENCE_FILE_POLICY, DENY_PROCESS_POLICY, } from "./sessionToolPolicies.js";
 import { createProcessCaptureEvidence } from "../application/ProcessEvidence.js";
@@ -15,13 +16,15 @@ import { registerArtifactComparisonTool } from "./registerArtifactComparisonTool
 import { registerFunctionComparisonTool } from "./registerFunctionComparisonTool.js";
 import { registerBundleComparisonTool } from "./registerBundleComparisonTool.js";
 import { registerInvestigationTools } from "./registerInvestigationTools.js";
+import { closeBinaryInputSchema, openBinaryInputSchema, } from "../contracts/sessionLifecycleInputs.js";
+import { registerSessionStatusTool } from "./registerSessionStatusTool.js";
 const recordProcessResidualUnknowns = (session, scenario, evidence, residuals) => {
     if (scenario.unknown_registry_approved !== true)
         return ok(null);
     for (const residual of residuals) {
         const unknown = session.recordUnknown({
             approved: true,
-            question: `${residual.scope}: ${residual.reason}`,
+            question: `Was ${residual.scope} behavior fully observed during capture?`,
             severity: "medium",
             domain: `process-${residual.scope}`,
             supporting_evidence_ids: [evidence.evidence_id],
@@ -163,7 +166,7 @@ const registerUnknownTools = ({ server, session, contracts: [listContract, recor
         return toCallToolResult(session.verifyUnknownResolution(unknownId), verifyContract);
     });
 };
-const registerLifecycleTools = (server, session, logger, contracts) => {
+const registerLifecycleTools = ({ server, session, logger, contracts, snapshotFilePolicy, }) => {
     const [openContract, closeContract, statusContract] = contracts;
     server.registerTool(openContract.name, {
         description: openContract.description,
@@ -171,8 +174,18 @@ const registerLifecycleTools = (server, session, logger, contracts) => {
         outputSchema: openContract.outputSchema,
         annotations: openContract.annotations,
     }, async (input, context) => {
-        const parsed = z.object({ path: z.string().min(1) }).parse(input);
-        const opened = await logToolExecution(logger, openContract.name, () => session.open(parsed.path, { signal: context.mcpReq.signal }));
+        const parsed = openBinaryInputSchema.parse(input);
+        let snapshot;
+        if (parsed.snapshot_path !== undefined) {
+            const loaded = await readAnalysisSnapshot(parsed.snapshot_path, snapshotFilePolicy);
+            if (!loaded.ok)
+                return toCallToolResult(loaded, openContract);
+            snapshot = loaded.value;
+        }
+        const opened = await logToolExecution(logger, openContract.name, () => session.open(parsed.path, {
+            signal: context.mcpReq.signal,
+            ...(snapshot === undefined ? {} : { snapshot }),
+        }));
         return opened.ok
             ? toCallToolResult({
                 ok: true,
@@ -192,23 +205,40 @@ const registerLifecycleTools = (server, session, logger, contracts) => {
         inputSchema: closeContract.inputSchema,
         outputSchema: closeContract.outputSchema,
         annotations: closeContract.annotations,
-    }, async () => toCallToolResult(await logToolExecution(logger, closeContract.name, () => session.close()), closeContract));
-    server.registerTool(statusContract.name, {
-        description: statusContract.description,
-        inputSchema: statusContract.inputSchema,
-        outputSchema: statusContract.outputSchema,
-        annotations: statusContract.annotations,
-    }, () => toCallToolResult({ ok: true, value: session.status() }, statusContract));
+    }, async (input) => {
+        const parsed = closeBinaryInputSchema.parse(input);
+        if (parsed.snapshot_path !== undefined) {
+            const snapshot = session.exportAnalysisSnapshot();
+            if (!snapshot.ok)
+                return toCallToolResult(snapshot, closeContract);
+            const written = await writeAnalysisSnapshot(snapshot.value, parsed.snapshot_path, parsed.overwrite, snapshotFilePolicy);
+            if (!written.ok)
+                return toCallToolResult(written, closeContract);
+            const closed = await logToolExecution(logger, closeContract.name, () => session.close());
+            return closed.ok
+                ? toCallToolResult(ok({
+                    path: written.value.path,
+                    bytes: written.value.bytes,
+                    entries: snapshot.value.entries.length,
+                }), closeContract)
+                : toCallToolResult(closed, closeContract);
+        }
+        return toCallToolResult(await logToolExecution(logger, closeContract.name, () => session.close()), closeContract);
+    });
+    registerSessionStatusTool(server, session, statusContract);
 };
 export const registerSessionTools = (server, session, logger, options = {}) => {
     const processPolicy = options.processPolicy ?? DENY_PROCESS_POLICY;
     const evidenceFilePolicy = options.evidenceFilePolicy ?? DENY_EVIDENCE_FILE_POLICY;
+    const analysisSnapshotFilePolicy = options.analysisSnapshotFilePolicy ?? DENY_EVIDENCE_FILE_POLICY;
     const [openContract, closeContract, statusContract, exportContract, importContract, captureContract, compareContract, compareArtifactsContract, compareFunctionsContract, compareBundlesContract, changedBehaviorContract, callPathContract, staticRuntimeContract, reconstructionContract, listUnknownContract, recordUnknownContract, updateUnknownContract, verifyUnknownContract,] = SESSION_TOOL_CONTRACTS;
-    registerLifecycleTools(server, session, logger, [
-        openContract,
-        closeContract,
-        statusContract,
-    ]);
+    registerLifecycleTools({
+        server,
+        session,
+        logger,
+        contracts: [openContract, closeContract, statusContract],
+        snapshotFilePolicy: analysisSnapshotFilePolicy,
+    });
     registerEvidenceTools({
         server,
         session,
@@ -227,12 +257,16 @@ export const registerSessionTools = (server, session, logger, options = {}) => {
     registerArtifactComparisonTool(server, session, compareArtifactsContract);
     registerFunctionComparisonTool(server, session, compareFunctionsContract);
     registerBundleComparisonTool(server, session, compareBundlesContract);
-    registerInvestigationTools(server, session, [
+    const investigationContracts = [
         changedBehaviorContract,
         callPathContract,
         staticRuntimeContract,
         reconstructionContract,
-    ]);
+    ];
+    registerInvestigationTools(server, session, investigationContracts, {
+        evidenceFiles: evidenceFilePolicy,
+        inputRoots: options.investigationInputRoots ?? [],
+    });
     registerUnknownTools({
         server,
         session,

package/dist/server/sessionEvidence.js

@@ -9,7 +9,7 @@ export const resolveSessionEvidence = (session, input) => {
     for (const item of supplied) {
         const parsed = parseEvidence(item);
         const owned = session.evidenceById(parsed.evidence_id);
-        if (owned === undefined || canonicalJson(owned) !== canonicalJson(parsed))
+        if (owned === undefined || canonicalize(owned) !== canonicalize(parsed))
             return err(new EvidenceIntegrityError("Comparison input does not match its session-owned Evidence"));
         authoritative.push(owned);
     }
@@ -18,11 +18,5 @@ export const resolveSessionEvidence = (session, input) => {
 /** Check exact ownership for a single Evidence record. */
 export const isSessionEvidence = (session, input) => {
     const owned = session.evidenceById(input.evidence_id);
-    return owned !== undefined && canonicalJson(owned) === canonicalJson(input);
-};
-const canonicalJson = (value) => {
-    const encoded = canonicalize(value);
-    if (encoded === undefined)
-        throw new TypeError("Evidence could not be canonicalized");
-    return encoded;
+    return owned !== undefined && canonicalize(owned) === canonicalize(input);
 };

package/dist/server/sessionToolPolicies.js

@@ -15,45 +15,4 @@ export const DENY_EVIDENCE_FILE_POLICY = {
     maxNodes: 1_000_000,
 };
 export { PROCESS_PROVIDER } from "../application/ProcessEvidence.js";
-/** Provider identity for deterministic cross-artifact comparisons. */
-export const ARTIFACT_COMPARISON_PROVIDER = {
-    id: "rea-artifact-comparison",
-    name: "REA artifact comparison",
-    version: "1",
-};
-/** Provider identity for deterministic cross-function comparisons. */
-export const FUNCTION_COMPARISON_PROVIDER = {
-    id: "rea-function-comparison",
-    name: "REA function comparison",
-    version: "1",
-};
-/** Provider identity for deterministic Evidence bundle comparisons. */
-export const BUNDLE_COMPARISON_PROVIDER = {
-    id: "rea-bundle-comparison",
-    name: "REA Evidence bundle comparison",
-    version: "1",
-};
-/** Provider identity for comparison-Evidence behavior aggregation. */
-export const CHANGED_BEHAVIOR_PROVIDER = {
-    id: "rea-changed-behavior",
-    name: "REA changed behavior investigation",
-    version: "1",
-};
-/** Provider identity for Evidence-backed call-path reconstruction. */
-export const CALL_PATH_PROVIDER = {
-    id: "rea-call-path",
-    name: "REA call path reconstruction",
-    version: "1",
-};
-/** Provider identity for explicit static/runtime hypothesis correlation. */
-export const STATIC_RUNTIME_PROVIDER = {
-    id: "rea-static-runtime-correlation",
-    name: "REA static/runtime correlation",
-    version: "1",
-};
-/** Provider identity for finite reconstruction specification verification. */
-export const RECONSTRUCTION_PROVIDER = {
-    id: "rea-reconstruction-verifier",
-    name: "REA reconstruction verifier",
-    version: "1",
-};
+export { ARTIFACT_COMPARISON_PROVIDER, BUNDLE_COMPARISON_PROVIDER, CALL_PATH_PROVIDER, CHANGED_BEHAVIOR_PROVIDER, FUNCTION_COMPARISON_PROVIDER, RECONSTRUCTION_PROVIDER, STATIC_RUNTIME_PROVIDER, } from "../application/InvestigationProviders.js";