rea-agents 0.3.0 → 0.4.0

package/dist/reference/ReferenceSourceReaderEntries.js

@@ -0,0 +1,206 @@
+import { readdir, readlink, realpath } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { entryFailure, safeSize } from "./ReferenceSourceReaderErrors.js";
+import { compareNames, pathFromRoot, withinRoot, } from "./ReferenceSourceReaderPaths.js";
+import { readStableFile } from "./ReferenceSourceReaderFile.js";
+import { isAborted, sameFile, validateDirectory, bigLstat, } from "./ReferenceSourceReaderValidate.js";
+import {} from "./ReferenceSourceReaderTypes.js";
+export const traverseDirectory = async (state, current) => {
+    const before = await validateDirectory(state.root, state.rootIdentity, current.path);
+    if (!before.ok) {
+        state.entries.push(entryFailure(pathFromRoot(state.root, current.path), "directory", before.code, before.message));
+        return { ok: true, value: undefined };
+    }
+    const names = await readDirectoryNames(current.path);
+    if (!names.ok) {
+        state.entries.push(entryFailure(pathFromRoot(state.root, current.path), "directory", "io", names.message));
+        return { ok: true, value: undefined };
+    }
+    if (isAborted(state.signal))
+        return {
+            ok: false,
+            error: {
+                tag: "reference-source-reader",
+                code: "cancelled",
+                message: "Reference source traversal cancelled",
+            },
+        };
+    const after = await validateDirectory(state.root, state.rootIdentity, current.path);
+    if (!after.ok || !sameFile(before.stats, after.stats)) {
+        state.entries.push(entryFailure(pathFromRoot(state.root, current.path), "directory", "changed", "Directory changed while it was read"));
+        return { ok: true, value: undefined };
+    }
+    const directories = [];
+    for (const name of names.value) {
+        const result = await processEntry(state, current, name, directories);
+        if (!result.ok)
+            return result;
+        if (state.stopped)
+            break;
+    }
+    directories.reverse();
+    state.pending.push(...directories);
+    return { ok: true, value: undefined };
+};
+const readDirectoryNames = async (path) => {
+    try {
+        return { ok: true, value: (await readdir(path)).sort(compareNames) };
+    }
+    catch {
+        return { ok: false, message: "Directory could not be read" };
+    }
+};
+const readMetadata = async (path) => {
+    try {
+        return { ok: true, value: await bigLstat(path) };
+    }
+    catch {
+        return { ok: false, message: "Entry metadata could not be read" };
+    }
+};
+const processEntry = async (state, current, name, directories) => {
+    if (isAborted(state.signal))
+        return {
+            ok: false,
+            error: {
+                tag: "reference-source-reader",
+                code: "cancelled",
+                message: "Reference source traversal cancelled",
+            },
+        };
+    const absolute = join(current.path, name);
+    const path = pathFromRoot(state.root, absolute);
+    const excluded = applyExclusion(state.shouldExclude, path);
+    if (!excluded.ok)
+        return {
+            ok: false,
+            error: {
+                tag: "reference-source-reader",
+                code: "io",
+                message: "Reference source exclusion check failed",
+            },
+        };
+    if (excluded.value)
+        return { ok: true, value: undefined };
+    if (!reserveEntry(state))
+        return { ok: true, value: undefined };
+    if (Buffer.byteLength(path) > state.limits.maxPathBytes) {
+        state.entries.push(entryFailure(path, "unknown", "limit", "Path exceeds maxPathBytes"));
+        state.truncated = true;
+        return { ok: true, value: undefined };
+    }
+    const metadata = await readMetadata(absolute);
+    if (!metadata.ok) {
+        state.entries.push(entryFailure(path, "unknown", "io", metadata.message));
+        return { ok: true, value: undefined };
+    }
+    if (isAborted(state.signal))
+        return {
+            ok: false,
+            error: {
+                tag: "reference-source-reader",
+                code: "cancelled",
+                message: "Reference source traversal cancelled",
+            },
+        };
+    if (metadata.value.isSymbolicLink())
+        state.entries.push(await describeSymlink(state.root, absolute, path));
+    else if (metadata.value.isDirectory()) {
+        if (current.depth < state.limits.maxDepth) {
+            state.entries.push({ status: "read", kind: "directory", path });
+            directories.push({ path: absolute, depth: current.depth + 1 });
+        }
+        else {
+            state.entries.push(entryFailure(path, "directory", "limit", "Directory exceeds maxDepth"));
+            state.truncated = true;
+        }
+    }
+    else if (!metadata.value.isFile())
+        state.entries.push(entryFailure(path, "other", "unsupported", "Entry is not a regular file", safeSize(metadata.value.size)));
+    else
+        await processFileEntry(state, absolute, path, metadata.value);
+    return { ok: true, value: undefined };
+};
+const processFileEntry = async (state, absolute, path, metadata) => {
+    const remaining = state.limits.maxBytes - state.bytesRead;
+    if (metadata.size > BigInt(remaining)) {
+        state.entries.push(entryFailure(path, "file", "limit", "File exceeds remaining maxBytes", safeSize(metadata.size)));
+        state.truncated = true;
+        return;
+    }
+    const result = await readStableFile({
+        root: state.root,
+        rootIdentity: state.rootIdentity,
+        absolute,
+        path,
+        expected: metadata,
+        remaining,
+        ...(state.signal === undefined ? {} : { signal: state.signal }),
+    });
+    if (result.status === "read" && result.kind === "file")
+        state.bytesRead += result.bytes.byteLength;
+    else if (result.status === "failed" && result.code === "limit")
+        state.truncated = true;
+    state.entries.push(result);
+};
+const describeSymlink = async (root, absolute, path) => {
+    try {
+        const rawTarget = await readlink(absolute);
+        const lexicalTarget = resolve(dirname(absolute), rawTarget);
+        if (!withinRoot(root, lexicalTarget))
+            return {
+                status: "read",
+                kind: "symlink",
+                path,
+                target: "<outside-root>",
+                targetState: "external",
+            };
+        try {
+            const canonicalTarget = await realpath(lexicalTarget);
+            return withinRoot(root, canonicalTarget)
+                ? {
+                    status: "read",
+                    kind: "symlink",
+                    path,
+                    target: pathFromRoot(root, canonicalTarget),
+                    targetState: "internal",
+                }
+                : {
+                    status: "read",
+                    kind: "symlink",
+                    path,
+                    target: "<outside-root>",
+                    targetState: "external",
+                };
+        }
+        catch {
+            return {
+                status: "read",
+                kind: "symlink",
+                path,
+                target: pathFromRoot(root, lexicalTarget),
+                targetState: "missing",
+            };
+        }
+    }
+    catch {
+        return entryFailure(path, "symlink", "io", "Symbolic link target could not be read");
+    }
+};
+const applyExclusion = (shouldExclude, path) => {
+    try {
+        return { ok: true, value: shouldExclude?.(path) === true };
+    }
+    catch {
+        return { ok: false };
+    }
+};
+const reserveEntry = (state) => {
+    if (state.filesSeen < state.limits.maxEntries) {
+        state.filesSeen += 1;
+        return true;
+    }
+    state.truncated = true;
+    state.stopped = true;
+    return false;
+};

package/dist/reference/ReferenceSourceReaderErrors.js

@@ -0,0 +1,19 @@
+import {} from "./ReferenceSourceReaderTypes.js";
+export const failure = (code, message) => ({
+    tag: "reference-source-reader",
+    code,
+    message,
+});
+export const cancelled = () => failure("cancelled", "Reference source traversal cancelled");
+export const safeSize = (size) => {
+    const value = Number(size);
+    return Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+};
+export const entryFailure = (...[path, kind, code, message, size]) => ({
+    status: "failed",
+    kind,
+    path,
+    code,
+    message,
+    ...(size === undefined ? {} : { size }),
+});

package/dist/reference/ReferenceSourceReaderFile.js

@@ -0,0 +1,119 @@
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { dirname } from "node:path";
+import { entryFailure, safeSize } from "./ReferenceSourceReaderErrors.js";
+import { isAborted, sameFile, validateDirectory, } from "./ReferenceSourceReaderValidate.js";
+import {} from "./ReferenceSourceReaderTypes.js";
+const READ_CHUNK_BYTES = 64 * 1024;
+const prepareFileRead = async (request) => {
+    const { root, rootIdentity, absolute, path, expected, signal } = request;
+    const parentBefore = await validateDirectory(root, rootIdentity, dirname(absolute));
+    if (!parentBefore.ok)
+        return {
+            status: "failed",
+            entry: entryFailure(path, "file", parentBefore.code, parentBefore.message, safeSize(expected.size)),
+        };
+    const handle = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW);
+    if (isAborted(signal)) {
+        await handle.close().catch(() => undefined);
+        return {
+            status: "failed",
+            entry: entryFailure(path, "file", "cancelled", "File read cancelled", safeSize(expected.size)),
+        };
+    }
+    const before = await handle.stat({ bigint: true });
+    if (!sameFile(expected, before)) {
+        await handle.close().catch(() => undefined);
+        return {
+            status: "failed",
+            entry: entryFailure(path, "file", "changed", "File changed before it was read", safeSize(before.size)),
+        };
+    }
+    return { status: "ready", handle, before, parentBefore };
+};
+const readFileContents = async (request) => {
+    const { handle, path, remaining, signal } = request;
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        if (isAborted(signal))
+            return {
+                status: "failed",
+                entry: entryFailure(path, "file", "cancelled", "File read cancelled", total),
+            };
+        const capacity = Math.min(READ_CHUNK_BYTES, remaining + 1 - total);
+        if (capacity <= 0)
+            return {
+                status: "failed",
+                entry: entryFailure(path, "file", "limit", "File exceeds remaining maxBytes", total),
+            };
+        const chunk = Buffer.allocUnsafe(capacity);
+        const read = await handle.read(chunk, 0, capacity, null);
+        if (isAborted(signal))
+            return {
+                status: "failed",
+                entry: entryFailure(path, "file", "cancelled", "File read cancelled", total),
+            };
+        if (read.bytesRead === 0)
+            break;
+        total += read.bytesRead;
+        if (total > remaining)
+            return {
+                status: "failed",
+                entry: entryFailure(path, "file", "limit", "File exceeds remaining maxBytes", total),
+            };
+        chunks.push(chunk.subarray(0, read.bytesRead));
+    }
+    return { status: "ok", chunks, total };
+};
+const finalizeFileRead = async (request) => {
+    const { root, rootIdentity, absolute, path, handle, before, parentBefore, chunks, total, } = request;
+    const after = await handle.stat({ bigint: true });
+    const parentAfter = await validateDirectory(root, rootIdentity, dirname(absolute));
+    if (!parentAfter.ok || !sameFile(parentBefore.stats, parentAfter.stats))
+        return entryFailure(path, "file", "changed", "Parent directory changed while file was read", total);
+    if (!sameFile(before, after) || BigInt(total) !== after.size)
+        return entryFailure(path, "file", "changed", "File changed while it was read", total);
+    return {
+        status: "read",
+        kind: "file",
+        path,
+        bytes: Buffer.concat(chunks, total),
+        size: total,
+    };
+};
+export const readStableFile = async (request) => {
+    const { root, rootIdentity, absolute, path, expected, remaining, signal } = request;
+    let handle;
+    try {
+        const prepared = await prepareFileRead(request);
+        if (prepared.status === "failed")
+            return prepared.entry;
+        handle = prepared.handle;
+        const contents = await readFileContents({
+            handle,
+            path,
+            remaining,
+            ...(signal === undefined ? {} : { signal }),
+        });
+        if (contents.status === "failed")
+            return contents.entry;
+        return await finalizeFileRead({
+            root,
+            rootIdentity,
+            absolute,
+            path,
+            handle,
+            before: prepared.before,
+            parentBefore: prepared.parentBefore,
+            chunks: contents.chunks,
+            total: contents.total,
+        });
+    }
+    catch {
+        return entryFailure(path, "file", isAborted(signal) ? "cancelled" : "io", "File could not be read safely", safeSize(expected.size));
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+};

package/dist/reference/ReferenceSourceReaderPaths.js

@@ -0,0 +1,23 @@
+import { isAbsolute, relative, sep } from "node:path";
+export const withinRoot = (root, path) => {
+    const value = relative(root, path);
+    return (value === "" ||
+        (value !== ".." && !value.startsWith(`..${sep}`) && !isAbsolute(value)));
+};
+export const pathFromRoot = (root, path) => {
+    const value = relative(root, path);
+    return withinRoot(root, path)
+        ? value.split(sep).join("/") || "."
+        : "<outside-root>";
+};
+export const compareNames = (left, right) => {
+    const leftPoints = [...left].map((value) => value.codePointAt(0) ?? 0);
+    const rightPoints = [...right].map((value) => value.codePointAt(0) ?? 0);
+    const length = Math.min(leftPoints.length, rightPoints.length);
+    for (let index = 0; index < length; index += 1) {
+        const difference = (leftPoints[index] ?? 0) - (rightPoints[index] ?? 0);
+        if (difference !== 0)
+            return difference;
+    }
+    return leftPoints.length - rightPoints.length;
+};

package/dist/reference/ReferenceSourceReaderTypes.js

@@ -0,0 +1,2 @@
+import {} from "node:fs";
+import {} from "../domain/result.js";

package/dist/reference/ReferenceSourceReaderValidate.js

@@ -0,0 +1,71 @@
+import { constants } from "node:fs";
+import { lstat, realpath } from "node:fs/promises";
+import { err, ok } from "../domain/result.js";
+import { cancelled, failure } from "./ReferenceSourceReaderErrors.js";
+import { withinRoot } from "./ReferenceSourceReaderPaths.js";
+import {} from "./ReferenceSourceReaderTypes.js";
+export const bigLstat = (path) => lstat(path, { bigint: true });
+export const sameFile = (left, right) => left.dev === right.dev &&
+    left.ino === right.ino &&
+    left.size === right.size &&
+    left.mtimeNs === right.mtimeNs &&
+    left.ctimeNs === right.ctimeNs;
+export const isAborted = (signal) => signal?.aborted === true;
+const validLimits = (limits) => Object.values(limits).every((value) => Number.isSafeInteger(value) && value > 0);
+export const noFollowOpenSupported = () => Number.isSafeInteger(constants.O_NOFOLLOW) && constants.O_NOFOLLOW !== 0;
+export const validateDirectory = async (root, rootIdentity, path) => {
+    try {
+        const rootNow = await bigLstat(root);
+        if (!sameFile(rootIdentity, rootNow))
+            return { ok: false, code: "changed", message: "Reference root changed" };
+        const stats = await bigLstat(path);
+        if (stats.isSymbolicLink())
+            return {
+                ok: false,
+                code: "symlink",
+                message: "Symbolic links are not followed",
+            };
+        if (!stats.isDirectory())
+            return {
+                ok: false,
+                code: "changed",
+                message: "Directory identity changed",
+            };
+        const canonical = await realpath(path);
+        if (canonical !== path || !withinRoot(root, canonical))
+            return {
+                ok: false,
+                code: "changed",
+                message: "Directory escaped the reference root",
+            };
+        return { ok: true, stats };
+    }
+    catch {
+        return {
+            ok: false,
+            code: "io",
+            message: "Directory identity could not be verified",
+        };
+    }
+};
+export const prepareRoot = async (root, limits, signal) => {
+    if (!validLimits(limits))
+        return err(failure("invalid-limits", "Reader limits must be positive integers"));
+    if (isAborted(signal))
+        return err(cancelled());
+    try {
+        const metadata = await bigLstat(root);
+        if (metadata.isSymbolicLink() || !metadata.isDirectory())
+            return err(failure("invalid-root", "Reference source root must be a directory"));
+        const canonicalRoot = await realpath(root);
+        if (isAborted(signal))
+            return err(cancelled());
+        const canonicalMetadata = await bigLstat(canonicalRoot);
+        if (!sameFile(metadata, canonicalMetadata))
+            return err(failure("invalid-root", "Reference source root changed during resolution"));
+        return ok({ canonicalRoot, rootIdentity: canonicalMetadata });
+    }
+    catch {
+        return err(failure("invalid-root", "Reference source root could not be resolved"));
+    }
+};

package/dist/server/createServer.js

@@ -3,13 +3,16 @@ import { PRODUCT_IDENTITY } from "../identity.js";
 import { registerEnhancedTools } from "./registerEnhancedTools.js";
 import { registerOfficialTools } from "./registerOfficialTools.js";
 import { registerSessionTools } from "./registerSessionTools.js";
+import { registerNativeTools } from "./registerNativeTools.js";
+import { registerArtifactTools } from "./registerArtifactTools.js";
 import { silentLogger } from "../logger.js";
 /**
  * Construct one MCP server without acquiring subprocess resources.
  * Supplying a session adds target lifecycle tools; omitting it retains the
  * fixed-target seam used by focused tests and embedders.
  */
-export const createServer = (analysis, session, logger = silentLogger, processPolicy) => {
+export const createServer = (analysis, session, options = {}) => {
+    const logger = options.logger ?? silentLogger;
     const server = new McpServer({ name: PRODUCT_IDENTITY.mcpServerKey, version: "0.1.0" }, {
         capabilities: { tools: {} },
         instructions: session === undefined
@@ -18,13 +21,36 @@ export const createServer = (analysis, session, logger = silentLogger, processPo
     });
     const toolLogger = logger.child({ layer: "server" });
     const activeTarget = session === undefined ? undefined : () => session.activeTarget();
-    const provider = session?.providerIdentity();
     const recordEvidence = session === undefined
         ? undefined
         : (evidence) => session.recordEvidence(evidence);
-    registerOfficialTools(server, analysis, toolLogger, activeTarget, provider, recordEvidence);
-    registerEnhancedTools(server, analysis, toolLogger, activeTarget, provider, recordEvidence);
+    registerOfficialTools(server, analysis, {
+        logger: toolLogger,
+        activeTarget,
+        recordEvidence,
+        recordUnknown: session === undefined
+            ? undefined
+            : (input) => session.recordUnknown(input),
+    });
+    registerEnhancedTools(server, analysis, {
+        logger: toolLogger,
+        activeTarget,
+        recordEvidence,
+        recordUnknown: session === undefined
+            ? undefined
+            : (input) => session.recordUnknown(input),
+    });
+    registerNativeTools(server, analysis, {
+        logger: toolLogger,
+        activeTarget,
+        recordEvidence,
+    });
+    registerArtifactTools(server, analysis, {
+        logger: toolLogger,
+        activeTarget,
+        recordEvidence,
+    });
     if (session !== undefined)
-        registerSessionTools(server, session, toolLogger, processPolicy);
+        registerSessionTools(server, session, toolLogger, options);
     return server;
 };

package/dist/server/recordDerivedEvidence.js

@@ -0,0 +1,10 @@
+import { ok } from "../domain/result.js";
+/** Atomically record derived Evidence with an optional approved unknown. */
+export const recordDerivedEvidence = (session, evidence, unknown) => {
+    if (unknown !== undefined) {
+        const recorded = session.recordEvidenceWithUnknown(evidence, unknown);
+        return recorded.ok ? ok(evidence) : recorded;
+    }
+    const recorded = session.recordEvidence(evidence);
+    return recorded.ok ? ok(evidence) : recorded;
+};

package/dist/server/registerArtifactComparisonTool.js

@@ -0,0 +1,62 @@
+import { artifactComparisonInputSchema, compareArtifacts, } from "../domain/artifactComparison.js";
+import { createEvidence } from "../domain/evidence.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { recordDerivedEvidence } from "./recordDerivedEvidence.js";
+import { resolveSessionEvidence } from "./sessionEvidence.js";
+import { ARTIFACT_COMPARISON_PROVIDER } from "./sessionToolPolicies.js";
+import { toCallToolResult } from "./toolResult.js";
+import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
+/** Register Evidence-backed deterministic artifact comparison. */
+export const registerArtifactComparisonTool = (server, session, contract) => {
+    server.registerTool(contract.name, toolRegistrationOptions(contract), (input) => {
+        const parsed = artifactComparisonInputSchema.parse(input);
+        const left = resolveSessionEvidence(session, parsed.left);
+        if (!left.ok)
+            return toCallToolResult(left, contract);
+        const right = resolveSessionEvidence(session, parsed.right);
+        if (!right.ok)
+            return toCallToolResult(right, contract);
+        const comparison = compareArtifacts(left.value, right.value, parsed.offset, parsed.limit);
+        const leftEvidenceIds = evidenceIds(parsed.left);
+        const rightEvidenceIds = evidenceIds(parsed.right);
+        const evidence = createEvidence(undefined, ARTIFACT_COMPARISON_PROVIDER, {
+            predicateType: "rea.artifact-comparison/v1",
+            operation: contract.name,
+            parameters: {
+                left_evidence_ids: leftEvidenceIds,
+                right_evidence_ids: rightEvidenceIds,
+                offset: parsed.offset,
+                limit: parsed.limit,
+            },
+            result: jsonValueSchema.parse(comparison),
+            confidence: "derived",
+            authority: "analyst-inference",
+            limitations: comparison.limitations,
+            evidenceLinks: [...leftEvidenceIds, ...rightEvidenceIds],
+        });
+        return toCallToolResult(recordDerivedEvidence(session, evidence, artifactUnknownInput(parsed, comparison.status)), contract);
+    });
+};
+const artifactUnknownInput = (input, status) => {
+    if (input.unknown_registry_approved !== true || status === "unchanged")
+        return undefined;
+    return {
+        approved: true,
+        question: `Artifact comparison is ${status}`,
+        severity: status === "unknown" || status === "truncated" ? "high" : "medium",
+        domain: "artifact-comparison",
+        supporting_evidence_ids: evidenceIds(input.left),
+        contradicting_evidence_ids: evidenceIds(input.right),
+        required_authority: "shipped-artifact",
+        required_confidence: "observed",
+        required_environment: null,
+        recommended_probes: [
+            {
+                operation: "inventory_artifact",
+                rationale: "Capture both complete artifact graphs under equal limits.",
+            },
+        ],
+        relationships: [],
+    };
+};
+const evidenceIds = (input) => (Array.isArray(input) ? input : [input]).map(({ evidence_id: id }) => id);

package/dist/server/registerArtifactTools.js

@@ -0,0 +1,6 @@
+import { ARTIFACT_TOOL_CONTRACTS } from "../contracts/artifactToolContracts.js";
+import { registerEvidenceTools } from "./registerEvidenceTools.js";
+/** Register deterministic artifact inventory and safe extraction operations. */
+export const registerArtifactTools = (server, analysis, options) => {
+    registerEvidenceTools(server, analysis, ARTIFACT_TOOL_CONTRACTS, options);
+};

package/dist/server/registerBundleComparisonTool.js

@@ -0,0 +1,47 @@
+import { bundleComparisonInputSchema, compareBundles, } from "../domain/bundleComparison.js";
+import { createEvidence } from "../domain/evidence.js";
+import { EvidenceIntegrityError } from "../domain/errors.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { err, ok } from "../domain/result.js";
+import { BUNDLE_COMPARISON_PROVIDER } from "./sessionToolPolicies.js";
+import { toCallToolResult } from "./toolResult.js";
+import { isSessionEvidence } from "./sessionEvidence.js";
+import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
+/** Register canonical Evidence bundle comparison. */
+export const registerBundleComparisonTool = (server, session, contract) => {
+    server.registerTool(contract.name, toolRegistrationOptions(contract), (input) => {
+        const parsed = bundleComparisonInputSchema.parse(input);
+        const sourceIds = [
+            ...new Set([
+                ...parsed.left.records.map(({ evidence_id: id }) => id),
+                ...parsed.right.records.map(({ evidence_id: id }) => id),
+            ]),
+        ].sort();
+        if ([...parsed.left.records, ...parsed.right.records].some((evidence) => !isSessionEvidence(session, evidence)))
+            return toCallToolResult(err(new EvidenceIntegrityError("Bundle comparison input Evidence is not present in this session")), contract);
+        const ownedUnknownDigests = new Set(session
+            .exportEvidenceBundle()
+            .unknowns.map(({ revision_digest: digest }) => digest));
+        if ([...parsed.left.unknowns, ...parsed.right.unknowns].some(({ revision_digest: digest }) => !ownedUnknownDigests.has(digest)))
+            return toCallToolResult(err(new EvidenceIntegrityError("Bundle comparison input unknown history is not present in this session")), contract);
+        const comparison = compareBundles(parsed.left, parsed.right, parsed.record_pairs, parsed.offset, parsed.limit);
+        const evidence = createEvidence(undefined, BUNDLE_COMPARISON_PROVIDER, {
+            predicateType: "rea.bundle-comparison/v1",
+            operation: contract.name,
+            parameters: {
+                left_bundle_sha256: comparison.left_bundle_sha256,
+                right_bundle_sha256: comparison.right_bundle_sha256,
+                record_pairs: parsed.record_pairs,
+                offset: parsed.offset,
+                limit: parsed.limit,
+            },
+            result: jsonValueSchema.parse(comparison),
+            confidence: "derived",
+            authority: "analyst-inference",
+            limitations: comparison.limitations,
+            evidenceLinks: sourceIds,
+        });
+        const recorded = session.recordEvidence(evidence);
+        return toCallToolResult(recorded.ok ? ok(evidence) : recorded, contract);
+    });
+};