rea-agents 0.3.0 → 0.5.0

package/dist/domain/evidenceBundle.js

@@ -1,11 +1,192 @@
 import { z } from "zod";
-import { evidenceSchema } from "./evidence.js";
+import canonicalize from "canonicalize";
+import { evidenceSchema, parseEvidence } from "./evidence.js";
+import { residualUnknownSchema, } from "./residualUnknown.js";
+const artifactManifestSchema = evidenceSchema.shape.subject.unwrap().pick({
+    digest: true,
+    format: true,
+    architecture: true,
+});
+const providerManifestSchema = evidenceSchema.shape.provider;
+const environmentManifestSchema = evidenceSchema.shape.environment.unwrap();
+const scenarioManifestSchema = z.object({
+    evidence_id: evidenceSchema.shape.evidence_id,
+    operation: z.string().min(1),
+    authority: z.literal("controlled-replay"),
+});
+const captureManifestSchema = z.object({
+    evidence_id: evidenceSchema.shape.evidence_id,
+    predicate_type: z.string().min(1),
+});
 export const evidenceBundleSchema = z.object({
-    bundle_version: z.literal(1),
+    bundle_version: z.literal(2),
+    artifacts: z.array(artifactManifestSchema),
+    providers: z.array(providerManifestSchema),
+    environments: z.array(environmentManifestSchema),
+    scenarios: z.array(scenarioManifestSchema),
+    captures: z.array(captureManifestSchema),
+    unknowns: z.array(residualUnknownSchema),
     records: z.array(evidenceSchema),
 });
 /** Project records into a deterministic bundle whose order has no semantics. */
-export const createEvidenceBundle = (records) => ({
-    bundle_version: 1,
-    records: [...records].sort((left, right) => left.evidence_id.localeCompare(right.evidence_id)),
-});
+export const createEvidenceBundle = (records, unknowns = []) => {
+    const sortedRecords = [...records].sort((left, right) => left.evidence_id.localeCompare(right.evidence_id));
+    return {
+        bundle_version: 2,
+        artifacts: uniqueSorted(sortedRecords.flatMap(({ subject }) => subject === null
+            ? []
+            : [
+                {
+                    digest: subject.digest,
+                    format: subject.format,
+                    architecture: subject.architecture,
+                },
+            ])),
+        providers: uniqueSorted(sortedRecords.map(({ provider }) => provider)),
+        environments: uniqueSorted(sortedRecords.flatMap(({ environment }) => environment === null ? [] : [environment])),
+        scenarios: sortedRecords.flatMap((evidence) => evidence.authority === "controlled-replay"
+            ? [
+                {
+                    evidence_id: evidence.evidence_id,
+                    operation: evidence.operation,
+                    authority: evidence.authority,
+                },
+            ]
+            : []),
+        captures: sortedRecords.flatMap((evidence) => evidence.predicate_type.startsWith("rea.process-capture/")
+            ? [
+                {
+                    evidence_id: evidence.evidence_id,
+                    predicate_type: evidence.predicate_type,
+                },
+            ]
+            : []),
+        unknowns: [...unknowns].sort((left, right) => left.unknown_id.localeCompare(right.unknown_id) ||
+            left.revision - right.revision),
+        records: sortedRecords,
+    };
+};
+/** Parse records, verify semantic IDs, and reject inconsistent manifests. */
+export const parseEvidenceBundle = (input) => {
+    const parsed = evidenceBundleSchema.parse(input);
+    const recordIds = parsed.records.map(({ evidence_id: id }) => id);
+    if (new Set(recordIds).size !== recordIds.length)
+        throw new TypeError("Evidence bundle contains duplicate record IDs");
+    validateUnknownGraph(parsed.unknowns, parsed.records);
+    const canonical = createEvidenceBundle(parsed.records.map(parseEvidence), parsed.unknowns);
+    if (JSON.stringify(parsed) !== JSON.stringify(canonical))
+        throw new TypeError("Evidence bundle manifests are not canonical");
+    return canonical;
+};
+const validateUnknownGraph = (unknowns, records) => {
+    const evidenceById = new Map(records.map((record) => [record.evidence_id, record]));
+    const histories = new Map();
+    for (const unknown of unknowns) {
+        const history = histories.get(unknown.unknown_id) ?? [];
+        history.push(unknown);
+        histories.set(unknown.unknown_id, history);
+    }
+    const unknownById = new Map();
+    for (const [id, unordered] of histories) {
+        const history = [...unordered].sort((left, right) => left.revision - right.revision);
+        for (const [index, revision] of history.entries()) {
+            if (revision.revision !== index + 1)
+                throw new TypeError(`Residual unknown ${id} revision history has a gap`);
+            if (index > 0 &&
+                revision.previous_revision_digest !==
+                    history[index - 1]?.revision_digest)
+                throw new TypeError(`Residual unknown ${id} revision chain is broken`);
+        }
+        const head = history.at(-1);
+        if (head === undefined)
+            throw new TypeError("Residual unknown revision history is empty");
+        unknownById.set(id, head);
+    }
+    for (const unknown of unknowns) {
+        const referencedEvidence = [
+            ...unknown.supporting_evidence_ids,
+            ...unknown.contradicting_evidence_ids,
+            ...unknown.mutation_evidence_ids,
+            ...(unknown.resolution?.evidence_ids ?? []),
+        ];
+        for (const evidenceId of referencedEvidence)
+            if (!evidenceById.has(evidenceId))
+                throw new TypeError(`Residual unknown references missing evidence ${evidenceId}`);
+        for (const relationship of unknown.relationships)
+            if (!unknownById.has(relationship.unknown_id))
+                throw new TypeError(`Residual unknown references missing unknown ${relationship.unknown_id}`);
+        if (unknown.resolution?.disposition === "verified")
+            validateVerifiedResolution(unknown, evidenceById);
+    }
+    rejectDependencyCycles(unknownById);
+};
+const validateVerifiedResolution = (unknown, evidenceById) => {
+    if (unknown.contradicting_evidence_ids.length > 0)
+        throw new TypeError(`Residual unknown ${unknown.unknown_id} retains contradicting evidence`);
+    const qualifies = unknown.resolution?.evidence_ids.some((evidenceId) => {
+        const evidence = evidenceById.get(evidenceId);
+        return (unknown.supporting_evidence_ids.includes(evidenceId) &&
+            evidence !== undefined &&
+            evidence.predicate_type !== "rea.residual-unknown-mutation/v1" &&
+            evidenceQualifies(unknown, evidence));
+    });
+    if (qualifies !== true)
+        throw new TypeError(`Residual unknown ${unknown.unknown_id} has no qualifying resolution evidence`);
+};
+const evidenceQualifies = (unknown, evidence) => {
+    if (unknown.required_authority !== null &&
+        evidence.authority !== unknown.required_authority)
+        return false;
+    const confidenceRank = { inferred: 1, derived: 2, observed: 3 };
+    if (confidenceRank[evidence.confidence] <
+        confidenceRank[unknown.required_confidence])
+        return false;
+    const requirement = unknown.required_environment;
+    if (requirement === null)
+        return true;
+    if (evidence.environment === null)
+        return false;
+    return ((requirement.id === null || requirement.id === evidence.environment.id) &&
+        (requirement.platform === null ||
+            requirement.platform === evidence.environment.platform) &&
+        (requirement.architecture === null ||
+            requirement.architecture === evidence.environment.architecture) &&
+        (requirement.isolation === null ||
+            requirement.isolation === evidence.environment.isolation));
+};
+const rejectDependencyCycles = (unknownById) => {
+    const visited = new Set();
+    const active = new Set();
+    const visit = (id) => {
+        if (active.has(id))
+            throw new TypeError("Residual unknown dependency graph contains a cycle");
+        if (visited.has(id))
+            return;
+        active.add(id);
+        const unknown = unknownById.get(id);
+        if (unknown === undefined)
+            throw new TypeError("Residual unknown dependency graph is inconsistent");
+        for (const relationship of unknown.relationships)
+            if (relationship.type === "depends-on")
+                visit(relationship.unknown_id);
+        active.delete(id);
+        visited.add(id);
+    };
+    for (const id of unknownById.keys())
+        visit(id);
+};
+/** Encode a validated bundle as byte-stable RFC 8785 canonical JSON. */
+export const serializeEvidenceBundle = (bundle) => {
+    const serialized = canonicalize(parseEvidenceBundle(bundle));
+    if (serialized === undefined)
+        throw new TypeError("Evidence bundle canonicalization failed");
+    return serialized;
+};
+const uniqueSorted = (values) => {
+    const unique = new Map();
+    for (const value of values)
+        unique.set(JSON.stringify(value), value);
+    return [...unique.entries()]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([, value]) => value);
+};

package/dist/domain/functionComparison.js

@@ -0,0 +1,201 @@
+import { diffLines } from "diff";
+import { parseFunctionEvidence, } from "./functionDossierEvidence.js";
+import { commentProjection, combineCoverage, functionMatch, identityProjection, isAutoName, normalizeCfg, project, referenceProjection, sorted, stringAndNameProjection, } from "./functionComparisonNormalization.js";
+import { functionComparisonResultSchema, } from "./functionComparisonSchemas.js";
+import { canonicalJson, dimensionResult, overallStatus, summarize, unresolvedDimension as buildUnresolvedDimension, } from "./functionComparisonResults.js";
+export { functionComparisonInputSchema, functionComparisonResultSchema, } from "./functionComparisonSchemas.js";
+const unresolvedDimension = (...[dimension, status, links, leftCount, rightCount, limitations]) => buildUnresolvedDimension({
+    dimension,
+    status,
+    links,
+    leftCount,
+    rightCount,
+    limitations,
+});
+/** Compare two explicit function Evidence page sets without fuzzy matching. */
+export const compareFunctions = (leftInput, rightInput, offset, limit) => {
+    const left = parseFunctionEvidence(leftInput);
+    const right = parseFunctionEvidence(rightInput);
+    const links = [
+        ...left.evidence.map(({ evidence_id: id }) => id),
+        ...right.evidence.map(({ evidence_id: id }) => id),
+    ];
+    const providersDiffer = canonicalJson(left.provider) !== canonicalJson(right.provider);
+    const dimensions = compareDimensions(left, right, links, providersDiffer);
+    const match = functionMatch(left, right);
+    const changes = dimensions.filter(({ status }) => status !== "unchanged");
+    const page = changes.slice(offset, offset + limit);
+    return functionComparisonResultSchema.parse({
+        status: overallStatus(dimensions, match.status),
+        function_match: match,
+        left_subject_sha256: left.subject.digest.sha256,
+        right_subject_sha256: right.subject.digest.sha256,
+        summary: summarize(dimensions),
+        dimensions,
+        changes: {
+            items: page,
+            offset,
+            limit,
+            total: changes.length,
+            next_offset: offset + page.length < changes.length ? offset + page.length : null,
+        },
+        limitations: [
+            ...new Set([
+                ...left.limitations.map((item) => `Left: ${item}`),
+                ...right.limitations.map((item) => `Right: ${item}`),
+                ...(providersDiffer
+                    ? [
+                        "Provider-specific pseudocode and assembly representations were not equated.",
+                    ]
+                    : []),
+            ]),
+        ].sort((a, b) => a.localeCompare(b)),
+    });
+};
+const compareDimensions = (left, right, links, providersDiffer) => [
+    compareIdentity(left, right, links, providersDiffer),
+    compareText("pseudocode", left.pseudocode.text, right.pseudocode.text, left.pseudocode.complete, right.pseudocode.complete, links, providersDiffer),
+    compareText("assembly", left.collections.assembly.items.join("\n"), right.collections.assembly.items.join("\n"), left.collections.assembly.complete, right.collections.assembly.complete, links, providersDiffer, left.collections.assembly.truncated || right.collections.assembly.truncated, "Assembly is opaque provider text; relocation normalization is unavailable."),
+    compareComments(left, right, links, providersDiffer),
+    compareCalls(left, right, links, providersDiffer),
+    compareReferences(left, right, links, providersDiffer),
+    compareStringsAndNames(left, right, links, providersDiffer),
+    compareCfg(left, right, links, providersDiffer),
+];
+const compareText = (...[dimension, left, right, leftComplete, rightComplete, links, providersDiffer, explicitTruncation, limitation,]) => {
+    const truncated = explicitTruncation ?? (!leftComplete || !rightComplete);
+    if (!leftComplete || !rightComplete || providersDiffer)
+        return unresolvedDimension(dimension, truncated ? "truncated" : "unknown", links, left.length, right.length, [
+            ...(limitation === undefined ? [] : [limitation]),
+            ...(providersDiffer
+                ? ["Exact text comparison requires one provider identity."]
+                : []),
+        ]);
+    const changes = diffLines(left, right, {
+        timeout: 100,
+        maxEditLength: 10_000,
+    });
+    if (changes === undefined)
+        return unresolvedDimension(dimension, "unknown", links, left.length, right.length, ["Bounded line diff exceeded its time or edit-distance limit."]);
+    const delta = changes.reduce((summary, change) => ({
+        added_lines: summary.added_lines + (change.added ? (change.count ?? 0) : 0),
+        removed_lines: summary.removed_lines + (change.removed ? (change.count ?? 0) : 0),
+        hunks: summary.hunks + (change.added || change.removed ? 1 : 0),
+    }), { added_lines: 0, removed_lines: 0, hunks: 0 });
+    return dimensionResult({
+        dimension,
+        status: delta.hunks === 0 ? "unchanged" : "changed",
+        left,
+        right,
+        links,
+        providersDiffer,
+        leftCount: [...left].length,
+        rightCount: [...right].length,
+        textDelta: delta,
+        limitations: limitation === undefined ? [] : [limitation],
+    });
+};
+const compareCollections = (...[dimension, left, right, leftCoverage, rightCoverage, links, providersDiffer,]) => {
+    if (!leftCoverage.complete || !rightCoverage.complete)
+        return unresolvedDimension(dimension, leftCoverage.truncated || rightCoverage.truncated
+            ? "truncated"
+            : "unknown", links, left.length, right.length, []);
+    return compareValues(dimension, sorted(left), sorted(right), links, true, true, providersDiffer);
+};
+const compareComments = (left, right, links, providersDiffer) => {
+    const leftValues = commentProjection(left);
+    const rightValues = commentProjection(right);
+    if (leftValues === null || rightValues === null)
+        return unresolvedDimension("comments", "unknown", links, left.collections.comments.items.length, right.collections.comments.items.length, ["Comment locations could not be normalized relative to the function."]);
+    return compareCollections("comments", leftValues, rightValues, left.collections.comments, right.collections.comments, links, providersDiffer);
+};
+const compareStringsAndNames = (left, right, links, providersDiffer) => {
+    const leftValues = stringAndNameProjection(left);
+    const rightValues = stringAndNameProjection(right);
+    if (leftValues === null || rightValues === null)
+        return unresolvedDimension("strings_names", "unknown", links, null, null, [
+            "Reference source locations could not be normalized to function offsets.",
+        ]);
+    return compareCollections("strings_names", leftValues, rightValues, combineCoverage(left.collections.referenced_strings, left.collections.referenced_names), combineCoverage(right.collections.referenced_strings, right.collections.referenced_names), links, providersDiffer);
+};
+const compareReferences = (left, right, links, providersDiffer) => {
+    const leftCoverage = combineCoverage(left.collections.incoming_references, left.collections.outgoing_references);
+    const rightCoverage = combineCoverage(right.collections.incoming_references, right.collections.outgoing_references);
+    if (!leftCoverage.complete || !rightCoverage.complete)
+        return unresolvedDimension("references", leftCoverage.truncated || rightCoverage.truncated
+            ? "truncated"
+            : "unknown", links, leftCoverage.items.length, rightCoverage.items.length, []);
+    const leftProjection = referenceProjection(left);
+    const rightProjection = referenceProjection(right);
+    if (leftProjection.length === 0 && rightProjection.length === 0)
+        return compareValues("references", leftProjection, rightProjection, links, true, true, providersDiffer);
+    if (canonicalJson(leftProjection) !== canonicalJson(rightProjection))
+        return dimensionResult({
+            dimension: "references",
+            status: "changed",
+            left: leftProjection,
+            right: rightProjection,
+            links,
+            providersDiffer,
+            leftCount: leftProjection.length,
+            rightCount: rightProjection.length,
+            textDelta: null,
+            limitations: [
+                "Reference endpoints differ; exact reference kinds remain unavailable.",
+            ],
+        });
+    return unresolvedDimension("references", "unknown", links, leftProjection.length, rightProjection.length, ["Reference kinds are unavailable in the current dossier contract."]);
+};
+const compareIdentity = (left, right, links, providersDiffer) => {
+    if (isAutoName(left.procedure.name) || isAutoName(right.procedure.name))
+        return unresolvedDimension("identity", "unknown", links, null, null, [
+            "Address-derived function names are not stable cross-version identity.",
+        ]);
+    return compareValues("identity", identityProjection(left), identityProjection(right), links, true, true, providersDiffer);
+};
+const compareCalls = (left, right, links, providersDiffer) => {
+    const leftValues = callProjection(left);
+    const rightValues = callProjection(right);
+    if ([...leftValues, ...rightValues].some(({ name }) => isAutoName(name)))
+        return unresolvedDimension("calls", "unknown", links, leftValues.length, rightValues.length, ["Address-derived callee or caller names cannot be matched safely."]);
+    return compareCollections("calls", leftValues, rightValues, combineCoverage(left.collections.callers, left.collections.callees), combineCoverage(right.collections.callers, right.collections.callees), links, providersDiffer);
+};
+const callProjection = (snapshot) => [
+    ...project(snapshot.collections.callers, ({ name }) => ({
+        direction: "in",
+        name,
+    })),
+    ...project(snapshot.collections.callees, ({ name }) => ({
+        direction: "out",
+        name,
+    })),
+];
+const compareCfg = (left, right, links, providersDiffer) => {
+    const leftBlocks = left.collections.basic_blocks;
+    const rightBlocks = right.collections.basic_blocks;
+    if (!leftBlocks.complete || !rightBlocks.complete)
+        return unresolvedDimension("cfg", leftBlocks.truncated || rightBlocks.truncated ? "truncated" : "unknown", links, leftBlocks.items.length, rightBlocks.items.length, []);
+    const leftGraph = normalizeCfg(leftBlocks.items);
+    const rightGraph = normalizeCfg(rightBlocks.items);
+    if (leftGraph === null || rightGraph === null)
+        return unresolvedDimension("cfg", "unknown", links, leftBlocks.items.length, rightBlocks.items.length, ["CFG addresses could not be normalized to local block indices."]);
+    return compareValues("cfg", leftGraph, rightGraph, links, true, true, providersDiffer);
+};
+const compareValues = (...[dimension, left, right, links, leftComplete, rightComplete, providersDiffer,]) => {
+    if (!leftComplete || !rightComplete)
+        return unresolvedDimension(dimension, "unknown", links, null, null, []);
+    const leftJson = canonicalJson(left);
+    const rightJson = canonicalJson(right);
+    return dimensionResult({
+        dimension,
+        status: leftJson === rightJson ? "unchanged" : "changed",
+        left,
+        right,
+        links,
+        providersDiffer,
+        leftCount: Array.isArray(left) ? left.length : null,
+        rightCount: Array.isArray(right) ? right.length : null,
+        textDelta: null,
+        limitations: [],
+    });
+};

package/dist/domain/functionComparisonNormalization.js

@@ -0,0 +1,112 @@
+import canonicalize from "canonicalize";
+export const identityProjection = (snapshot) => ({
+    name: snapshot.procedure.name,
+    signature: snapshot.procedure.signature,
+    locals: snapshot.procedure.locals
+        .map(({ description }) => description)
+        .sort(),
+});
+export const functionMatch = (left, right) => {
+    if (!isAutoName(left.procedure.name) &&
+        left.procedure.name === right.procedure.name)
+        return {
+            status: "matched",
+            method: "symbol",
+            left_name: left.procedure.name,
+            right_name: right.procedure.name,
+        };
+    return {
+        status: left.procedure.name === right.procedure.name ? "ambiguous" : "mismatched",
+        method: "explicit",
+        left_name: left.procedure.name,
+        right_name: right.procedure.name,
+    };
+};
+export const normalizeCfg = (blocks) => {
+    const parsed = blocks.map((block) => ({
+        block,
+        start: parseAddress(block.start),
+        end: parseAddress(block.end),
+    }));
+    if (parsed.some(({ start, end }) => start === null || end === null))
+        return null;
+    const ordered = parsed.sort((left, right) => (left.start ?? 0n) < (right.start ?? 0n) ? -1 : 1);
+    if (new Set(ordered.map(({ block }) => block.start)).size !== ordered.length)
+        return null;
+    if (ordered.some(({ start, end }) => (end ?? 0n) <= (start ?? 0n)))
+        return null;
+    const indices = new Map(ordered.map(({ block }, index) => [block.start, index]));
+    const graph = [];
+    for (const { block, start, end } of ordered) {
+        const successors = block.successors.map((address) => indices.get(address));
+        if (successors.some((index) => index === undefined))
+            return null;
+        graph.push({
+            size: String((end ?? 0n) - (start ?? 0n)),
+            successors: successors.sort((left, right) => (left ?? 0) - (right ?? 0)),
+        });
+    }
+    return graph;
+};
+export const referenceProjection = (snapshot) => sorted([
+    ...snapshot.collections.incoming_references.items.map((item) => ({
+        direction: "in",
+        source: item.source_procedure?.name ?? null,
+        target: item.target_procedure?.name ?? null,
+    })),
+    ...snapshot.collections.outgoing_references.items.map((item) => ({
+        direction: "out",
+        source: item.source_procedure?.name ?? null,
+        target: item.target_procedure?.name ?? null,
+    })),
+]);
+export const commentProjection = (snapshot) => {
+    const values = snapshot.collections.comments.items.map(({ address, kind, text }) => ({
+        offset: relativeAddress(address, snapshot.procedure.address),
+        kind,
+        text,
+    }));
+    return values.some(({ offset }) => offset === null) ? null : sorted(values);
+};
+export const stringAndNameProjection = (snapshot) => {
+    const values = [
+        ...snapshot.collections.referenced_strings.items.map(({ source_address: sourceAddress, value }) => ({
+            kind: "string",
+            source_offset: relativeAddress(sourceAddress, snapshot.procedure.address),
+            value,
+        })),
+        ...snapshot.collections.referenced_names.items.map(({ source_address: sourceAddress, value }) => ({
+            kind: "name",
+            source_offset: relativeAddress(sourceAddress, snapshot.procedure.address),
+            value,
+        })),
+    ];
+    return values.some(({ source_offset: offset }) => offset === null)
+        ? null
+        : sorted(values);
+};
+export const sorted = (values) => [...values].sort((left, right) => canonicalJson(left).localeCompare(canonicalJson(right)));
+export const combineCoverage = (left, right) => ({
+    items: [...left.items, ...right.items],
+    total: left.total === null || right.total === null
+        ? null
+        : left.total + right.total,
+    complete: left.complete && right.complete,
+    truncated: left.truncated || right.truncated,
+});
+export const project = (collection, mapper) => collection.items.map(mapper);
+export const isAutoName = (name) => /^(?:sub_[0-9a-f]+|fcn\.)/iu.test(name);
+const parseAddress = (value) => /^0x[0-9a-f]+$/iu.test(value) ? BigInt(value) : null;
+const relativeAddress = (value, base) => {
+    const parsed = parseAddress(value);
+    const parsedBase = parseAddress(base);
+    return parsed === null || parsedBase === null || parsed < parsedBase
+        ? null
+        : String(parsed - parsedBase);
+};
+const canonicalJson = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError("Function normalization could not canonicalize data");
+    return encoded;
+};

package/dist/domain/functionComparisonResults.js

@@ -0,0 +1,54 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+export const dimensionResult = (input) => ({
+    dimension: input.dimension,
+    status: input.status,
+    left_digest: digest(input.left),
+    right_digest: digest(input.right),
+    left_count: input.leftCount,
+    right_count: input.rightCount,
+    text_delta: input.textDelta,
+    conclusion_kind: input.status === "changed" && input.providersDiffer
+        ? "contradiction"
+        : "derived_relationship",
+    evidence_links: [...input.links],
+    limitations: [...input.limitations],
+});
+export const unresolvedDimension = (input) => ({
+    dimension: input.dimension,
+    status: input.status,
+    left_digest: null,
+    right_digest: null,
+    left_count: input.leftCount,
+    right_count: input.rightCount,
+    text_delta: null,
+    conclusion_kind: "unresolved_branch",
+    evidence_links: [...input.links],
+    limitations: [...input.limitations],
+});
+export const overallStatus = (dimensions, match) => {
+    if (dimensions.some(({ status }) => status === "truncated"))
+        return "truncated";
+    if (match === "ambiguous" ||
+        match === "unknown" ||
+        dimensions.some(({ status }) => status === "unknown"))
+        return "unknown";
+    if (match === "mismatched")
+        return "changed";
+    return dimensions.some(({ status }) => status === "changed")
+        ? "changed"
+        : "unchanged";
+};
+export const summarize = (dimensions) => ({
+    unchanged: dimensions.filter(({ status }) => status === "unchanged").length,
+    changed: dimensions.filter(({ status }) => status === "changed").length,
+    truncated: dimensions.filter(({ status }) => status === "truncated").length,
+    unknown: dimensions.filter(({ status }) => status === "unknown").length,
+});
+export const canonicalJson = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError("Function comparison could not canonicalize data");
+    return encoded;
+};
+const digest = (value) => createHash("sha256").update(canonicalJson(value)).digest("hex");

package/dist/domain/functionComparisonSchemas.js

@@ -0,0 +1,82 @@
+import { z } from "zod";
+import { evidenceSchema } from "./evidence.js";
+const evidenceInput = z.union([
+    evidenceSchema,
+    z.array(evidenceSchema).min(1).max(100),
+]);
+const comparisonStatusSchema = z.enum([
+    "unchanged",
+    "added",
+    "removed",
+    "changed",
+    "truncated",
+    "unknown",
+]);
+const dimensionNameSchema = z.enum([
+    "identity",
+    "pseudocode",
+    "assembly",
+    "comments",
+    "calls",
+    "references",
+    "strings_names",
+    "cfg",
+]);
+const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
+const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
+/** Strict bounded input for explicit function-to-function comparison. */
+export const functionComparisonInputSchema = z.object({
+    left: evidenceInput,
+    right: evidenceInput,
+    offset: z.number().int().min(0).default(0),
+    limit: z.number().int().min(1).max(100).default(100),
+    unknown_registry_approved: z.literal(true).optional(),
+});
+const textDeltaSchema = z.object({
+    added_lines: z.number().int().min(0),
+    removed_lines: z.number().int().min(0),
+    hunks: z.number().int().min(0),
+});
+const functionDimensionSchema = z.object({
+    dimension: dimensionNameSchema,
+    status: comparisonStatusSchema,
+    left_digest: digestSchema.nullable(),
+    right_digest: digestSchema.nullable(),
+    left_count: z.number().int().min(0).nullable(),
+    right_count: z.number().int().min(0).nullable(),
+    text_delta: textDeltaSchema.nullable(),
+    conclusion_kind: z.enum([
+        "derived_relationship",
+        "contradiction",
+        "unresolved_branch",
+    ]),
+    evidence_links: z.array(evidenceIdSchema).min(2).max(200),
+    limitations: z.array(z.string()),
+});
+/** Deterministic dimension-classified function comparison Evidence payload. */
+export const functionComparisonResultSchema = z.object({
+    status: comparisonStatusSchema,
+    function_match: z.object({
+        status: z.enum(["matched", "mismatched", "ambiguous", "unknown"]),
+        method: z.enum(["explicit", "symbol"]),
+        left_name: z.string(),
+        right_name: z.string(),
+    }),
+    left_subject_sha256: digestSchema,
+    right_subject_sha256: digestSchema,
+    summary: z.object({
+        unchanged: z.number().int().min(0),
+        changed: z.number().int().min(0),
+        truncated: z.number().int().min(0),
+        unknown: z.number().int().min(0),
+    }),
+    dimensions: z.array(functionDimensionSchema).length(8),
+    changes: z.object({
+        items: z.array(functionDimensionSchema).max(100),
+        offset: z.number().int().min(0),
+        limit: z.number().int().min(1).max(100),
+        total: z.number().int().min(0),
+        next_offset: z.number().int().min(0).nullable(),
+    }),
+    limitations: z.array(z.string()),
+});