rea-agents 2.0.0 → 2.2.0

package/dist/domain/managedMemberComparison.js

@@ -1,8 +1,9 @@
-import { createHash } from "node:crypto";
-import canonicalize from "canonicalize";
 import { z } from "zod";
-import { evidenceSchema, parseEvidence } from "./evidence.js";
-import { managedMemberInspectionSchema, } from "./managedArtifact.js";
+import { evidenceSchema } from "./evidence.js";
+import { cliMetadataGuidSchema, } from "./managedArtifact.js";
+import { assessKnownPageCoverage } from "./knownPageCoverage.js";
+import { buildComparisonCoverage, buildComparisonMatching, buildComparisonSummary, comparisonLimitations, sideManifest, } from "./managedMemberComparisonCoverage.js";
+import { buildFieldItems, buildMethodItems, keyMembers, sha256, } from "./managedMemberComparisonMatch.js";
 const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
 const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
 const tokenSchema = z.string().regex(/^0x[0-9a-f]{8}$/u);
@@ -107,7 +108,7 @@ export const managedMemberComparisonResultSchema = z.strictObject({
     left: z.strictObject({
         evidence_id: evidenceIdSchema,
         artifact_sha256: digestSchema,
-        mvid: z.string().uuid().nullable(),
+        mvid: cliMetadataGuidSchema.nullable(),
         module_name: z.string().nullable(),
         metadata_status: z.enum(["absent", "complete", "partial", "malformed"]),
         methods_total: z.number().int().min(0),
@@ -116,7 +117,7 @@ export const managedMemberComparisonResultSchema = z.strictObject({
     right: z.strictObject({
         evidence_id: evidenceIdSchema,
         artifact_sha256: digestSchema,
-        mvid: z.string().uuid().nullable(),
+        mvid: cliMetadataGuidSchema.nullable(),
         module_name: z.string().nullable(),
         metadata_status: z.enum(["absent", "complete", "partial", "malformed"]),
         methods_total: z.number().int().min(0),
@@ -149,38 +150,37 @@ export const managedMemberComparisonResultSchema = z.strictObject({
     evidence_links: z.array(evidenceIdSchema).length(2),
     limitations: z.array(boundedTextSchema).max(1_000),
 });
-const sha256 = (value) => {
-    const serialized = canonicalize(value);
-    if (serialized === undefined)
-        throw new TypeError("Managed comparison canonicalization failed");
-    return createHash("sha256").update(serialized).digest("hex");
-};
 /** Compare two parsed managed member observations without name-based matching. */
 export const compareManagedMembers = (left, right, limits) => {
-    const methodMatches = matchMethods(left.result.methods.items.map(keyMethod), right.result.methods.items.map(keyMethod), limits.max_candidates);
-    const fieldMatches = matchFields(left.result.fields.items.map(keyField), right.result.fields.items.map(keyField), limits.max_candidates);
-    const methodItems = buildMethodItems(methodMatches, left.evidenceId, right.evidenceId, limits);
-    const fieldItems = buildFieldItems(fieldMatches, left.evidenceId, right.evidenceId, limits);
-    const allItems = [...methodItems.items, ...fieldItems.items];
-    const summary = {
-        unchanged: allItems.filter(({ status }) => status === "unchanged").length,
-        changed: allItems.filter(({ status }) => status === "changed").length,
-        added: allItems.filter(({ status }) => status === "added").length,
-        removed: allItems.filter(({ status }) => status === "removed").length,
-        unknown: allItems.filter(({ status }) => status === "unknown").length,
+    const leftMethodPage = assessKnownPageCoverage(left.result.methods);
+    const rightMethodPage = assessKnownPageCoverage(right.result.methods);
+    const leftFieldPage = assessKnownPageCoverage(left.result.fields);
+    const rightFieldPage = assessKnownPageCoverage(right.result.fields);
+    const { methodMatches, fieldMatches } = keyMembers(left, right, limits.max_candidates);
+    const itemContext = {
+        leftEvidenceId: left.evidenceId,
+        rightEvidenceId: right.evidenceId,
+        leftComplete: leftMethodPage.sourceComplete && leftFieldPage.sourceComplete,
+        rightComplete: rightMethodPage.sourceComplete && rightFieldPage.sourceComplete,
+        limits,
     };
-    const matching = {
-        exact_il_signature: methodItems.items.filter(({ match }) => match.basis === "exact-il-signature").length,
-        structural_method_shape: methodItems.items.filter(({ match }) => match.basis === "structural-method-shape").length,
-        field_signature: fieldItems.items.filter(({ match }) => match.basis === "field-signature").length,
-        ambiguous: methodItems.items.filter(({ match }) => match.status === "ambiguous")
-            .length +
-            fieldItems.items.filter(({ match }) => match.status === "ambiguous")
-                .length,
-        unmatched: allItems.filter(({ match }) => match.status === "unmatched")
-            .length,
-    };
-    const limitations = comparisonLimitations(left.result, right.result, methodItems.omitted + fieldItems.omitted, methodMatches.omittedCandidates + fieldMatches.omittedCandidates);
+    const methodItems = buildMethodItems(methodMatches, itemContext);
+    const fieldItems = buildFieldItems(fieldMatches, itemContext);
+    const allItems = [...methodItems.items, ...fieldItems.items];
+    const summary = buildComparisonSummary(allItems);
+    const matching = buildComparisonMatching(methodItems.items, fieldItems.items);
+    const coverage = buildComparisonCoverage({
+        left: left.result,
+        right: right.result,
+        leftMethodPage,
+        rightMethodPage,
+        leftFieldPage,
+        rightFieldPage,
+        omittedMethodItems: methodItems.omitted,
+        omittedFieldItems: fieldItems.omitted,
+        omittedCandidates: methodMatches.omittedCandidates + fieldMatches.omittedCandidates,
+    });
+    const limitations = comparisonLimitations(left.result, right.result, coverage.omitted_methods + coverage.omitted_fields, coverage.omitted_candidates);
     const result = {
         schema_version: 1,
         comparison_id: `mmc_${sha256({
@@ -202,364 +202,10 @@ export const compareManagedMembers = (left, right, limits) => {
         matching,
         methods: methodItems.items,
         fields: fieldItems.items,
-        coverage: {
-            status: methodItems.omitted + fieldItems.omitted > 0 ||
-                !left.result.methods.complete ||
-                !right.result.methods.complete ||
-                !left.result.fields.complete ||
-                !right.result.fields.complete
-                ? "truncated"
-                : left.result.coverage.state === "complete" &&
-                    right.result.coverage.state === "complete"
-                    ? "complete-within-inputs"
-                    : "partial",
-            left_status: left.result.coverage.state,
-            right_status: right.result.coverage.state,
-            omitted_methods: methodItems.omitted,
-            omitted_fields: fieldItems.omitted,
-            omitted_candidates: methodMatches.omittedCandidates + fieldMatches.omittedCandidates,
-        },
+        coverage,
         evidence_links: [left.evidenceId, right.evidenceId],
         limitations,
     };
     return managedMemberComparisonResultSchema.parse(result);
 };
-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,
-});
-const keyMethod = (item) => ({
-    item,
-    exactKey: item.signature.parse_status === "decoded" &&
-        item.body.normalized_il_sha256 !== null
-        ? stableKey([
-            "method-exact",
-            item.signature.raw_sha256,
-            item.body.normalized_il_sha256,
-        ])
-        : null,
-    structuralKey: 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",
-        ]),
-    ]),
-});
-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, "exact-il-signature", [
-    "structural-method-shape",
-]);
-const matchFields = (left, right, maxCandidates) => matchByKeys(left, right, maxCandidates, "field-signature", []);
-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 buildMethodItems = (matches, leftEvidenceId, rightEvidenceId, limits) => {
-    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: [leftEvidenceId, 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: [leftEvidenceId, 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, leftEvidenceId, rightEvidenceId, true));
-    for (const item of matches.rightOnly)
-        items.push(methodOnlyItem(item.item, leftEvidenceId, rightEvidenceId, false));
-    return limitItems(items, limits.max_method_matches);
-};
-const buildFieldItems = (matches, leftEvidenceId, rightEvidenceId, limits) => {
-    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: [leftEvidenceId, 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: [leftEvidenceId, 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, leftEvidenceId, rightEvidenceId, true));
-    for (const item of matches.rightOnly)
-        items.push(fieldOnlyItem(item.item, leftEvidenceId, rightEvidenceId, false));
-    return limitItems(items, limits.max_field_matches);
-};
-const limitItems = (items, limit) => ({
-    items: items.slice(0, limit),
-    omitted: Math.max(0, items.length - limit),
-});
-const methodOnlyItem = (item, leftEvidenceId, rightEvidenceId, left) => ({
-    item_id: `mmc_method_${sha256({ token: item.token, side: left ? "left" : "right" })}`,
-    status: left ? "removed" : "added",
-    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: [leftEvidenceId, rightEvidenceId],
-    limitations: [],
-});
-const fieldOnlyItem = (item, leftEvidenceId, rightEvidenceId, left) => ({
-    item_id: `mmc_field_${sha256({ token: item.token, side: left ? "left" : "right" })}`,
-    status: left ? "removed" : "added",
-    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: [leftEvidenceId, rightEvidenceId],
-    limitations: [],
-});
-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 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 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;
-};
-/** Extract and authenticate a managed member inspection Evidence record. */
-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),
-    };
-};
+export { parseManagedMemberEvidence } from "./managedMemberComparisonMatch.js";

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;
+};