rea-agents 1.7.0 → 2.1.0

package/dist/domain/managedMemberComparisonCoverage.js

@@ -0,0 +1,72 @@
+export const buildComparisonCoverage = ({ left, right, leftMethodPage, rightMethodPage, leftFieldPage, rightFieldPage, omittedMethodItems, omittedFieldItems, omittedCandidates, }) => {
+    const omittedMethods = omittedMethodItems +
+        leftMethodPage.sourceOmittedCount +
+        rightMethodPage.sourceOmittedCount;
+    const omittedFields = omittedFieldItems +
+        leftFieldPage.sourceOmittedCount +
+        rightFieldPage.sourceOmittedCount;
+    const leftStatus = sideCoverageStatus(left, leftMethodPage.sourceComplete && leftFieldPage.sourceComplete);
+    const rightStatus = sideCoverageStatus(right, rightMethodPage.sourceComplete && rightFieldPage.sourceComplete);
+    const unknownInput = left.coverage.state !== "complete" || right.coverage.state !== "complete";
+    const truncated = omittedMethods + omittedFields + omittedCandidates > 0;
+    return {
+        status: unknownInput
+            ? "partial"
+            : truncated
+                ? "truncated"
+                : leftStatus === "complete" && rightStatus === "complete"
+                    ? "complete-within-inputs"
+                    : "partial",
+        left_status: leftStatus,
+        right_status: rightStatus,
+        omitted_methods: omittedMethods,
+        omitted_fields: omittedFields,
+        omitted_candidates: omittedCandidates,
+    };
+};
+const sideCoverageStatus = (result, pagesComplete) => result.coverage.state === "unavailable"
+    ? "unavailable"
+    : result.coverage.state === "complete" && pagesComplete
+        ? "complete"
+        : "partial";
+export const sideManifest = (side) => ({
+    evidence_id: side.evidenceId,
+    artifact_sha256: side.result.artifact.sha256,
+    mvid: side.result.module?.mvid ?? null,
+    module_name: side.result.module?.name ?? null,
+    metadata_status: side.result.metadata.status,
+    methods_total: side.result.methods.total,
+    fields_total: side.result.fields.total,
+});
+export const buildComparisonSummary = (items) => ({
+    unchanged: items.filter(({ status }) => status === "unchanged").length,
+    changed: items.filter(({ status }) => status === "changed").length,
+    added: items.filter(({ status }) => status === "added").length,
+    removed: items.filter(({ status }) => status === "removed").length,
+    unknown: items.filter(({ status }) => status === "unknown").length,
+});
+export const buildComparisonMatching = (methodItems, fieldItems) => ({
+    exact_il_signature: methodItems.filter(({ match }) => match.basis === "exact-il-signature").length,
+    structural_method_shape: methodItems.filter(({ match }) => match.basis === "structural-method-shape").length,
+    field_signature: fieldItems.filter(({ match }) => match.basis === "field-signature").length,
+    ambiguous: methodItems.filter(({ match }) => match.status === "ambiguous").length +
+        fieldItems.filter(({ match }) => match.status === "ambiguous").length,
+    unmatched: [...methodItems, ...fieldItems].filter(({ match }) => match.status === "unmatched").length,
+});
+export const comparisonLimitations = (left, right, omittedItems, omittedCandidates) => {
+    const limitations = [
+        "Metadata tokens are build-local coordinates; matched pairs are remaps, not persistent identities.",
+        "Names are reported as observations but are not used as a matching basis.",
+    ];
+    if (!left.methods.complete || !right.methods.complete)
+        limitations.push("At least one method page is incomplete.");
+    if (!left.fields.complete || !right.fields.complete)
+        limitations.push("At least one field page is incomplete.");
+    if (left.coverage.state !== "complete" || right.coverage.state !== "complete")
+        limitations.push("At least one managed member observation is partial.");
+    if (omittedItems > 0)
+        limitations.push(`${String(omittedItems)} comparison items were omitted by output limits.`);
+    if (omittedCandidates > 0)
+        limitations.push(`${String(omittedCandidates)} ambiguous candidates were omitted by candidate limits.`);
+    return limitations;
+};

package/dist/domain/managedMemberComparisonMatch.js

@@ -0,0 +1,356 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { parseEvidence } from "./evidence.js";
+import { managedMemberInspectionSchema, } from "./managedArtifact.js";
+export const sha256 = (value) => {
+    const serialized = canonicalize(value);
+    if (serialized === undefined)
+        throw new TypeError("Managed comparison canonicalization failed");
+    return createHash("sha256").update(serialized).digest("hex");
+};
+const keyMethod = (item) => ({
+    item,
+    exactKey: item.signature.parse_status === "decoded" &&
+        item.body.status === "present" &&
+        item.body.normalized_il_sha256 !== null
+        ? stableKey([
+            "method-exact",
+            item.signature.raw_sha256,
+            item.body.normalized_il_sha256,
+        ])
+        : null,
+    structuralKey: item.body.status === "present"
+        ? stableKey([
+            "method-structural",
+            item.signature.kind,
+            item.signature.calling_convention,
+            item.signature.generic_parameter_count,
+            item.signature.parameter_count,
+            item.signature.return_type,
+            item.signature.parameter_types,
+            item.body.status,
+            item.body.header_format,
+            item.body.il_size,
+            item.body.max_stack,
+            item.body.init_locals,
+            item.body.opcode_counts,
+            item.body.anchors.map(({ opcode, operand_kind }) => [
+                opcode,
+                operand_kind,
+            ]),
+            item.body.exception_regions.map((region) => [
+                region.flags,
+                region.try_length,
+                region.handler_length,
+                region.class_token === null ? null : "type-token",
+                region.filter_offset === null ? null : "filter",
+            ]),
+        ])
+        : null,
+});
+const keyField = (item) => ({
+    item,
+    exactKey: item.signature.parse_status === "decoded"
+        ? stableKey(["field-exact", item.signature.raw_sha256])
+        : null,
+    structuralKey: stableKey([
+        "field-structural",
+        item.signature.kind,
+        item.signature.field_type,
+        item.flags,
+    ]),
+});
+const stableKey = (value) => sha256(value);
+const matchMethods = (left, right, maxCandidates) => matchByKeys({
+    left,
+    right,
+    maxCandidates,
+    exactBasis: "exact-il-signature",
+    fallbackBases: ["structural-method-shape"],
+});
+const matchFields = (left, right, maxCandidates) => matchByKeys({
+    left,
+    right,
+    maxCandidates,
+    exactBasis: "field-signature",
+    fallbackBases: [],
+});
+const matchByKeys = ({ left, right, maxCandidates, exactBasis, fallbackBases, }) => {
+    const usedLeft = new Set();
+    const usedRight = new Set();
+    const pairs = [];
+    const ambiguous = [];
+    let omittedCandidates = 0;
+    const rounds = [
+        { basis: exactBasis, key: ({ exactKey }) => exactKey },
+        ...fallbackBases.map((basis) => ({
+            basis,
+            key: ({ structuralKey }) => structuralKey,
+        })),
+    ];
+    for (const round of rounds) {
+        const leftGroups = groupBy(left.filter((item) => !usedLeft.has(item)), round.key);
+        const rightGroups = groupBy(right.filter((item) => !usedRight.has(item)), round.key);
+        for (const [key, leftItems] of leftGroups) {
+            const rightItems = rightGroups.get(key);
+            if (rightItems === undefined)
+                continue;
+            if (leftItems.length === 1 && rightItems.length === 1) {
+                const [leftItem] = leftItems;
+                const [rightItem] = rightItems;
+                if (leftItem === undefined || rightItem === undefined)
+                    continue;
+                usedLeft.add(leftItem);
+                usedRight.add(rightItem);
+                pairs.push({
+                    left: leftItem,
+                    right: rightItem,
+                    basis: round.basis,
+                    confidence: round.basis === "exact-il-signature" ||
+                        round.basis === "field-signature"
+                        ? "exact"
+                        : "high",
+                });
+            }
+            else {
+                for (const item of leftItems)
+                    usedLeft.add(item);
+                for (const item of rightItems)
+                    usedRight.add(item);
+                omittedCandidates += Math.max(0, leftItems.length + rightItems.length - maxCandidates * 2);
+                ambiguous.push({
+                    left: leftItems.slice(0, maxCandidates),
+                    right: rightItems.slice(0, maxCandidates),
+                    basis: round.basis,
+                });
+            }
+        }
+    }
+    return {
+        pairs,
+        ambiguous,
+        leftOnly: left.filter((item) => !usedLeft.has(item)),
+        rightOnly: right.filter((item) => !usedRight.has(item)),
+        omittedCandidates,
+    };
+};
+const groupBy = (items, keyOf) => {
+    const grouped = new Map();
+    for (const item of items) {
+        const key = keyOf(item);
+        if (key === null)
+            continue;
+        const bucket = grouped.get(key) ?? [];
+        bucket.push(item);
+        grouped.set(key, bucket);
+    }
+    return grouped;
+};
+const changedMethodDimensions = (left, right) => {
+    const dimensions = [];
+    if (left.signature.raw_sha256 !== right.signature.raw_sha256)
+        dimensions.push("signature");
+    if (left.body.normalized_il_sha256 !== right.body.normalized_il_sha256)
+        dimensions.push("cil");
+    if (canonicalize(left.body.opcode_counts) !==
+        canonicalize(right.body.opcode_counts))
+        dimensions.push("opcode-shape");
+    if (callShape(left.body.anchors) !== callShape(right.body.anchors))
+        dimensions.push("call-shape");
+    if (fieldShape(left.body.anchors) !== fieldShape(right.body.anchors))
+        dimensions.push("field-shape");
+    if (canonicalize(left.body.exception_regions) !==
+        canonicalize(right.body.exception_regions))
+        dimensions.push("exception-shape");
+    if (left.body.status !== right.body.status)
+        dimensions.push("availability");
+    return dimensions;
+};
+const callShape = (anchors) => JSON.stringify(anchors
+    .filter(({ operand_kind }) => operand_kind === "method")
+    .map(({ opcode, operand_kind }) => [opcode, operand_kind]));
+const fieldShape = (anchors) => JSON.stringify(anchors
+    .filter(({ operand_kind }) => operand_kind === "field")
+    .map(({ opcode, operand_kind }) => [opcode, operand_kind]));
+const methodIdentity = (item) => ({
+    token: item.token,
+    declaring_type: item.declaring_type,
+    name: item.name,
+    signature_sha256: item.signature.raw_sha256,
+    normalized_il_sha256: item.body.normalized_il_sha256,
+});
+const fieldIdentity = (item) => ({
+    token: item.token,
+    declaring_type: item.declaring_type,
+    name: item.name,
+    signature_sha256: item.signature.raw_sha256,
+});
+const methodOnlyItem = (item, context, left) => {
+    const absenceObserved = left ? context.rightComplete : context.leftComplete;
+    return {
+        item_id: `mmc_method_${sha256({ token: item.token, side: left ? "left" : "right" })}`,
+        status: absenceObserved ? (left ? "removed" : "added") : "unknown",
+        left: left ? methodIdentity(item) : null,
+        right: left ? null : methodIdentity(item),
+        match: {
+            status: "unmatched",
+            basis: "none",
+            confidence: "unknown",
+            candidate_left_tokens: [],
+            candidate_right_tokens: [],
+        },
+        dimensions: ["availability"],
+        evidence_links: [context.leftEvidenceId, context.rightEvidenceId],
+        limitations: absenceObserved
+            ? []
+            : [
+                `unknown-within-unobserved-page: The ${left ? "right" : "left"} method page is incomplete, so absence was not observed.`,
+            ],
+    };
+};
+const fieldOnlyItem = (item, context, left) => {
+    const absenceObserved = left ? context.rightComplete : context.leftComplete;
+    return {
+        item_id: `mmc_field_${sha256({ token: item.token, side: left ? "left" : "right" })}`,
+        status: absenceObserved ? (left ? "removed" : "added") : "unknown",
+        left: left ? fieldIdentity(item) : null,
+        right: left ? null : fieldIdentity(item),
+        match: {
+            status: "unmatched",
+            basis: "none",
+            confidence: "unknown",
+            candidate_left_tokens: [],
+            candidate_right_tokens: [],
+        },
+        evidence_links: [context.leftEvidenceId, context.rightEvidenceId],
+        limitations: absenceObserved
+            ? []
+            : [
+                `unknown-within-unobserved-page: The ${left ? "right" : "left"} field page is incomplete, so absence was not observed.`,
+            ],
+    };
+};
+export const buildMethodItems = (matches, context) => {
+    const items = [];
+    for (const pair of matches.pairs) {
+        const dimensions = changedMethodDimensions(pair.left.item, pair.right.item);
+        items.push({
+            item_id: `mmc_method_${sha256({
+                left: pair.left.item.token,
+                right: pair.right.item.token,
+                basis: pair.basis,
+            })}`,
+            status: dimensions.length === 0 ? "unchanged" : "changed",
+            left: methodIdentity(pair.left.item),
+            right: methodIdentity(pair.right.item),
+            match: {
+                status: "matched",
+                basis: pair.basis,
+                confidence: pair.confidence,
+                candidate_left_tokens: [],
+                candidate_right_tokens: [],
+            },
+            dimensions,
+            evidence_links: [context.leftEvidenceId, context.rightEvidenceId],
+            limitations: [],
+        });
+    }
+    for (const ambiguous of matches.ambiguous) {
+        items.push({
+            item_id: `mmc_method_${sha256({
+                left: ambiguous.left.map(({ item }) => item.token),
+                right: ambiguous.right.map(({ item }) => item.token),
+                basis: ambiguous.basis,
+            })}`,
+            status: "unknown",
+            left: null,
+            right: null,
+            match: {
+                status: "ambiguous",
+                basis: ambiguous.basis,
+                confidence: "unknown",
+                candidate_left_tokens: ambiguous.left.map(({ item }) => item.token),
+                candidate_right_tokens: ambiguous.right.map(({ item }) => item.token),
+            },
+            dimensions: ["availability"],
+            evidence_links: [context.leftEvidenceId, context.rightEvidenceId],
+            limitations: [
+                "Multiple managed methods share the same non-name identity key; REA did not guess a token remap.",
+            ],
+        });
+    }
+    for (const item of matches.leftOnly)
+        items.push(methodOnlyItem(item.item, context, true));
+    for (const item of matches.rightOnly)
+        items.push(methodOnlyItem(item.item, context, false));
+    return limitItems(items, context.limits.max_method_matches);
+};
+export const buildFieldItems = (matches, context) => {
+    const items = [];
+    for (const pair of matches.pairs) {
+        const changed = pair.left.item.signature.raw_sha256 !==
+            pair.right.item.signature.raw_sha256 ||
+            pair.left.item.flags !== pair.right.item.flags;
+        items.push({
+            item_id: `mmc_field_${sha256({
+                left: pair.left.item.token,
+                right: pair.right.item.token,
+            })}`,
+            status: changed ? "changed" : "unchanged",
+            left: fieldIdentity(pair.left.item),
+            right: fieldIdentity(pair.right.item),
+            match: {
+                status: "matched",
+                basis: pair.basis,
+                confidence: pair.confidence,
+                candidate_left_tokens: [],
+                candidate_right_tokens: [],
+            },
+            evidence_links: [context.leftEvidenceId, context.rightEvidenceId],
+            limitations: [],
+        });
+    }
+    for (const ambiguous of matches.ambiguous)
+        items.push({
+            item_id: `mmc_field_${sha256({
+                left: ambiguous.left.map(({ item }) => item.token),
+                right: ambiguous.right.map(({ item }) => item.token),
+            })}`,
+            status: "unknown",
+            left: null,
+            right: null,
+            match: {
+                status: "ambiguous",
+                basis: ambiguous.basis,
+                confidence: "unknown",
+                candidate_left_tokens: ambiguous.left.map(({ item }) => item.token),
+                candidate_right_tokens: ambiguous.right.map(({ item }) => item.token),
+            },
+            evidence_links: [context.leftEvidenceId, context.rightEvidenceId],
+            limitations: [
+                "Multiple managed fields share the same signature; REA did not guess a token remap from names.",
+            ],
+        });
+    for (const item of matches.leftOnly)
+        items.push(fieldOnlyItem(item.item, context, true));
+    for (const item of matches.rightOnly)
+        items.push(fieldOnlyItem(item.item, context, false));
+    return limitItems(items, context.limits.max_field_matches);
+};
+const limitItems = (items, limit) => ({
+    items: items.slice(0, limit),
+    omitted: Math.max(0, items.length - limit),
+});
+export const keyMembers = (left, right, maxCandidates) => ({
+    methodMatches: matchMethods(left.result.methods.items.map(keyMethod), right.result.methods.items.map(keyMethod), maxCandidates),
+    fieldMatches: matchFields(left.result.fields.items.map(keyField), right.result.fields.items.map(keyField), maxCandidates),
+});
+export const parseManagedMemberEvidence = (evidence) => {
+    const parsed = parseEvidence(evidence);
+    if (parsed.operation !== "inspect_managed_members")
+        throw new TypeError("Evidence operation is not inspect_managed_members");
+    return {
+        evidenceId: parsed.evidence_id,
+        result: managedMemberInspectionSchema.parse(parsed.normalized_result),
+    };
+};

package/dist/domain/managedNativeVerification.js

@@ -0,0 +1,46 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { parseEvidence } from "./evidence.js";
+import { managedNativeBoundaryInspectionSchema, } from "./managedArtifact.js";
+import { managedNativeVerificationResultSchema, } from "./managedNativeVerificationSchemas.js";
+import { buildVerificationResult, collectNativeSymbols, verifyPinvoke, } from "./managedNativeVerificationMatch.js";
+export { managedNativeVerificationInputSchema, } from "./managedNativeVerificationSchemas.js";
+export { managedNativeVerificationResultSchema };
+const sha256 = (value) => {
+    const serialized = canonicalize(value);
+    if (serialized === undefined)
+        throw new TypeError("Managed/native verification canonicalization failed");
+    return createHash("sha256").update(serialized).digest("hex");
+};
+const managedBoundaryFromInput = (input) => {
+    const managedEvidence = parseEvidence(input.managed_boundaries);
+    if (managedEvidence.operation !== "inspect_managed_native_boundaries")
+        throw new TypeError("Evidence operation is not inspect_managed_native_boundaries");
+    return managedNativeBoundaryInspectionSchema.parse(managedEvidence.normalized_result);
+};
+/** Verify managed P/Invoke declarations against authenticated native Evidence. */
+export const verifyManagedNativeBoundaries = (input) => {
+    const managed = managedBoundaryFromInput(input);
+    const managedEvidence = parseEvidence(input.managed_boundaries);
+    const native = collectNativeSymbols(input.native_observations.slice(0, input.limits.max_native_observations));
+    const verifiedPinvokes = managed.pinvoke_imports.items.map((item) => verifyPinvoke({
+        item,
+        managedEvidenceId: managedEvidence.evidence_id,
+        symbols: native.symbols,
+        hasSupportedNativeEvidence: native.accepted > 0,
+        input,
+    }));
+    const pinvokeImports = verifiedPinvokes.map(({ verification }) => verification);
+    const withoutId = buildVerificationResult({
+        managedEvidence,
+        managed,
+        native,
+        pinvokeImports,
+        verifiedPinvokes,
+        input,
+    });
+    return managedNativeVerificationResultSchema.parse({
+        ...withoutId,
+        verification_id: `mnv_${sha256(withoutId)}`,
+    });
+};