rea-agents 3.0.0 → 3.2.0

package/dist/domain/javascriptApplicationVersionComparison.js

@@ -15,29 +15,21 @@ export const compareJavaScriptApplicationVersions = (input) => {
         rightEvidenceId: input.right.evidenceId,
         leftNativeEvidence: input.leftNativeEvidence,
         rightNativeEvidence: input.rightNativeEvidence,
-        maxCandidates: input.limits.max_candidate_nodes,
     });
-    const items = projection.items.slice(0, input.limits.max_comparison_items);
-    const omittedComparisonItems = projection.items.length - items.length;
     const changeGraph = buildJavaScriptApplicationChangeGraph({
         left: input.left.graph,
         right: input.right.graph,
         leftEvidenceId: input.left.evidenceId,
         rightEvidenceId: input.right.evidenceId,
-        items,
-        omittedComparisonItems,
-        limits: input.limits,
+        items: projection.items,
     });
     const evidenceLinks = uniqueSorted(projection.items.flatMap(({ evidence_links: links }) => links));
     const omissions = {
-        omitted_comparison_items: omittedComparisonItems,
-        omitted_candidate_references: projection.omittedCandidateReferences,
-        omitted_graph_nodes: changeGraph.omittedNodes,
-        omitted_graph_edges: changeGraph.omittedEdges,
-        omitted_graph_observations: changeGraph.omittedObservations,
+        left_graph_omitted_count: input.left.graph.coverage.omitted_count,
+        right_graph_omitted_count: input.right.graph.coverage.omitted_count,
     };
+    const coverage = comparisonCoverage(input, omissions);
     const semantic = {
-        schema_version: 1,
         left: {
             evidence_id: input.left.evidenceId,
             graph_id: input.left.graph.graph_id,
@@ -50,16 +42,11 @@ export const compareJavaScriptApplicationVersions = (input) => {
         },
         summary: summary(projection.items),
         matching: matchingSummary(projection.items),
-        items,
+        items: projection.items,
         graph: changeGraph.graph,
-        coverage: {
-            status: comparisonCoverageStatus(input, omissions),
-            left_graph_status: input.left.graph.coverage.status,
-            right_graph_status: input.right.graph.coverage.status,
-            ...omissions,
-        },
+        coverage,
         evidence_links: evidenceLinks,
-        limitations: comparisonLimitations(input, omissions),
+        limitations: comparisonLimitations(input),
     };
     return applicationVersionComparisonResultSchema.parse({
         ...semantic,
@@ -85,13 +72,25 @@ const matchingSummary = (items) => ({
     unmatched: items.filter(({ match }) => match.status === "unmatched").length,
 });
 const countBasis = (items, basis) => items.filter(({ match }) => match.basis === basis).length;
-const comparisonCoverageStatus = (input, omissions) => Object.values(omissions).some((value) => value > 0)
-    ? "truncated"
-    : input.left.graph.coverage.status === "complete" &&
-        input.right.graph.coverage.status === "complete"
-        ? "complete-within-inputs"
-        : "partial";
-const comparisonLimitations = (input, omissions) => uniqueSorted([
+const comparisonCoverage = (input, omissions) => {
+    const context = {
+        left_graph_status: input.left.graph.coverage.status,
+        right_graph_status: input.right.graph.coverage.status,
+    };
+    const sourceGraphsComplete = input.left.graph.coverage.status === "complete" &&
+        input.right.graph.coverage.status === "complete";
+    const sourceGraphsTruncated = input.left.graph.coverage.truncated || input.right.graph.coverage.truncated;
+    return {
+        ...context,
+        ...omissions,
+        status: sourceGraphsComplete
+            ? "complete-within-inputs"
+            : sourceGraphsTruncated
+                ? "truncated"
+                : "partial",
+    };
+};
+const comparisonLimitations = (input) => uniqueSorted([
     "Application comparison never uses bundler module ordinals as persistent identity and performs no fuzzy pairing.",
     "Exact digest equality proves byte identity only; source-map, structural-fingerprint, and semantic-key matches retain inferred confidence.",
     "Minified names and chunk locations are not assumed stable across versions.",
@@ -103,9 +102,6 @@ const comparisonLimitations = (input, omissions) => uniqueSorted([
         : [
             "At least one source graph is incomplete; unmatched entities on the opposite side remain unknown rather than added or removed.",
         ]),
-    ...(Object.values(omissions).some((value) => value > 0)
-        ? ["Comparison output was truncated at explicit caller limits."]
-        : []),
 ]);
 const digestCanonical = (value) => {
     const encoded = canonicalize(value);

package/dist/domain/javascriptApplicationVersionComparisonSchemas.js

@@ -4,27 +4,14 @@ import { javascriptApplicationGraphSchema } from "./javascriptApplicationGraph.j
 import { JAVASCRIPT_APPLICATION_NODE_KINDS } from "./javascriptApplicationGraphSchemas.js";
 const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
 const nodeIdSchema = z.string().regex(/^jag_node_[a-f0-9]{64}$/u);
-const boundedTextSchema = z.string().min(1).max(4_096);
-const comparisonLimitsSchema = z.strictObject({
-    max_comparison_items: z.number().int().min(1).max(50_000).default(20_000),
-    max_candidate_nodes: z.number().int().min(1).max(1_000).default(100),
-    max_graph_nodes: z.number().int().min(1).max(100_000).default(20_000),
-    max_graph_edges: z.number().int().min(1).max(200_000).default(40_000),
-});
-/** Two authenticated application versions and deterministic output bounds. */
+const textSchema = z.string().min(1);
+/** Two authenticated application versions and their native observations. */
 export const compareApplicationVersionsInputSchema = z
     .strictObject({
     left: evidenceSchema,
     right: evidenceSchema,
-    left_native_observations: z.array(evidenceSchema).max(64).default([]),
-    right_native_observations: z.array(evidenceSchema).max(64).default([]),
-    limits: comparisonLimitsSchema.default({
-        max_comparison_items: 20_000,
-        max_candidate_nodes: 100,
-        max_graph_nodes: 20_000,
-        max_graph_edges: 40_000,
-    }),
-    unknown_registry_approved: z.literal(true).optional(),
+    left_native_observations: z.array(evidenceSchema).default([]),
+    right_native_observations: z.array(evidenceSchema).default([]),
 })
     .superRefine((input, context) => {
     if (input.left.evidence_id === input.right.evidence_id)
@@ -46,44 +33,120 @@ export const compareApplicationVersionsInputSchema = z
             });
     }
 });
-const applicationVersionMatchBasisSchema = z.enum([
-    "exact-node-identity",
-    "exact-content-digest",
-    "exact-module-source-digest",
-    "source-map-identity",
-    "structural-fingerprint",
-    "semantic-key",
-    "none",
+const emptyCandidateNodesSchema = z.tuple([]);
+const candidateNodesSchema = z.tuple([nodeIdSchema]).rest(nodeIdSchema);
+const exactMatchSchema = z.strictObject({
+    status: z.literal("matched"),
+    basis: z.enum([
+        "exact-node-identity",
+        "exact-content-digest",
+        "exact-module-source-digest",
+    ]),
+    confidence: z.literal("exact"),
+    candidate_left_node_ids: emptyCandidateNodesSchema,
+    candidate_right_node_ids: emptyCandidateNodesSchema,
+});
+const sourceMapMatchSchema = z.strictObject({
+    status: z.literal("matched"),
+    basis: z.literal("source-map-identity"),
+    confidence: z.literal("high"),
+    candidate_left_node_ids: emptyCandidateNodesSchema,
+    candidate_right_node_ids: emptyCandidateNodesSchema,
+});
+const inferredMatchSchema = z.strictObject({
+    status: z.literal("matched"),
+    basis: z.enum(["structural-fingerprint", "semantic-key"]),
+    confidence: z.literal("medium"),
+    candidate_left_node_ids: emptyCandidateNodesSchema,
+    candidate_right_node_ids: emptyCandidateNodesSchema,
+});
+const matchedItemMatchSchema = z.union([
+    exactMatchSchema,
+    sourceMapMatchSchema,
+    inferredMatchSchema,
 ]);
-const comparisonItemSchema = z.strictObject({
+const unmatchedItemMatchSchema = z.strictObject({
+    status: z.literal("unmatched"),
+    basis: z.literal("none"),
+    confidence: z.literal("unknown"),
+    candidate_left_node_ids: emptyCandidateNodesSchema,
+    candidate_right_node_ids: emptyCandidateNodesSchema,
+});
+const leftAmbiguousMatchSchema = z.strictObject({
+    status: z.literal("ambiguous"),
+    basis: z.literal("none"),
+    confidence: z.literal("unknown"),
+    candidate_left_node_ids: emptyCandidateNodesSchema,
+    candidate_right_node_ids: candidateNodesSchema,
+});
+const rightAmbiguousMatchSchema = z.strictObject({
+    status: z.literal("ambiguous"),
+    basis: z.literal("none"),
+    confidence: z.literal("unknown"),
+    candidate_left_node_ids: candidateNodesSchema,
+    candidate_right_node_ids: emptyCandidateNodesSchema,
+});
+const comparisonItemContextShape = {
     item_id: z.string().regex(/^javc_item_[a-f0-9]{64}$/u),
-    status: z.enum(["unchanged", "added", "removed", "changed", "unknown"]),
     node_kind: z.enum(JAVASCRIPT_APPLICATION_NODE_KINDS),
-    left_node_id: nodeIdSchema.nullable(),
-    right_node_id: nodeIdSchema.nullable(),
-    match: z.strictObject({
-        status: z.enum(["matched", "unmatched", "ambiguous"]),
-        basis: applicationVersionMatchBasisSchema,
-        confidence: z.enum(["exact", "high", "medium", "unknown"]),
-        candidate_left_node_ids: z.array(nodeIdSchema).max(1_000),
-        candidate_right_node_ids: z.array(nodeIdSchema).max(1_000),
-    }),
-    dimensions: z
-        .array(z.enum([
+    dimensions: z.array(z.enum([
         "content",
         "location",
         "properties",
         "relationships",
         "availability",
         "coverage",
-    ]))
-        .max(6),
-    evidence_links: z.array(evidenceIdSchema).min(2).max(130),
-    limitations: z.array(boundedTextSchema).max(100),
+    ])),
+    evidence_links: z.array(evidenceIdSchema).min(2),
+    limitations: z.array(textSchema),
+};
+const comparisonItemSchema = z.union([
+    z.strictObject({
+        ...comparisonItemContextShape,
+        status: z.enum(["unchanged", "changed", "unknown"]),
+        left_node_id: nodeIdSchema,
+        right_node_id: nodeIdSchema,
+        match: matchedItemMatchSchema,
+    }),
+    z.strictObject({
+        ...comparisonItemContextShape,
+        status: z.enum(["removed", "unknown"]),
+        left_node_id: nodeIdSchema,
+        right_node_id: z.null(),
+        match: unmatchedItemMatchSchema,
+    }),
+    z.strictObject({
+        ...comparisonItemContextShape,
+        status: z.enum(["added", "unknown"]),
+        left_node_id: z.null(),
+        right_node_id: nodeIdSchema,
+        match: unmatchedItemMatchSchema,
+    }),
+    z.strictObject({
+        ...comparisonItemContextShape,
+        status: z.literal("unknown"),
+        left_node_id: nodeIdSchema,
+        right_node_id: z.null(),
+        match: leftAmbiguousMatchSchema,
+    }),
+    z.strictObject({
+        ...comparisonItemContextShape,
+        status: z.literal("unknown"),
+        left_node_id: z.null(),
+        right_node_id: nodeIdSchema,
+        match: rightAmbiguousMatchSchema,
+    }),
+]);
+const comparisonCoverageSchema = z.strictObject({
+    left_graph_status: z.enum(["complete", "partial", "unknown", "unavailable"]),
+    right_graph_status: z.enum(["complete", "partial", "unknown", "unavailable"]),
+    left_graph_omitted_count: z.number().int().min(0).nullable(),
+    right_graph_omitted_count: z.number().int().min(0).nullable(),
+    status: z.enum(["complete-within-inputs", "partial", "truncated"]),
 });
-/** Tiered module/entity matching plus a bounded cross-version change graph. */
-export const applicationVersionComparisonResultSchema = z.strictObject({
-    schema_version: z.literal(1),
+/** Tiered module/entity matching plus its complete cross-version change graph. */
+export const applicationVersionComparisonResultSchema = z
+    .strictObject({
     comparison_id: z.string().regex(/^javc_[a-f0-9]{64}$/u),
     left: z.strictObject({
         evidence_id: evidenceIdSchema,
@@ -112,28 +175,20 @@ export const applicationVersionComparisonResultSchema = z.strictObject({
         ambiguous: z.number().int().min(0),
         unmatched: z.number().int().min(0),
     }),
-    items: z.array(comparisonItemSchema).max(50_000),
+    items: z.array(comparisonItemSchema),
     graph: javascriptApplicationGraphSchema,
-    coverage: z.strictObject({
-        status: z.enum(["complete-within-inputs", "partial", "truncated"]),
-        left_graph_status: z.enum([
-            "complete",
-            "partial",
-            "unknown",
-            "unavailable",
-        ]),
-        right_graph_status: z.enum([
-            "complete",
-            "partial",
-            "unknown",
-            "unavailable",
-        ]),
-        omitted_comparison_items: z.number().int().min(0),
-        omitted_candidate_references: z.number().int().min(0),
-        omitted_graph_nodes: z.number().int().min(0),
-        omitted_graph_edges: z.number().int().min(0),
-        omitted_graph_observations: z.number().int().min(0),
-    }),
-    evidence_links: z.array(evidenceIdSchema).min(2).max(130),
-    limitations: z.array(boundedTextSchema).max(1_000),
+    coverage: comparisonCoverageSchema,
+    evidence_links: z.array(evidenceIdSchema).min(2),
+    limitations: z.array(textSchema),
+})
+    .superRefine((result, context) => {
+    const sourceGraphsComplete = result.coverage.left_graph_status === "complete" &&
+        result.coverage.right_graph_status === "complete";
+    if ((result.coverage.status === "complete-within-inputs") !==
+        sourceGraphsComplete)
+        context.addIssue({
+            code: "custom",
+            path: ["coverage", "status"],
+            message: "Comparison coverage must match source graph completeness",
+        });
 });

package/dist/domain/javascriptApplicationVersionItems.js

@@ -12,16 +12,19 @@ export const classifyJavaScriptApplicationVersions = (matching, context) => {
         `pair:${left.node_id}:${right.node_id}`,
     ]));
     const fullContext = { ...context, pairByLeft, pairByRight };
-    let omittedCandidateReferences = 0;
     const leftItems = matching.unmatchedLeft.map((node) => {
         const candidates = matching.candidatesForLeft.get(node.node_id) ?? [];
-        omittedCandidateReferences += Math.max(0, candidates.length - context.maxCandidates);
-        return unmatchedItem(node, "left", candidates.slice(0, context.maxCandidates), fullContext);
+        return unmatchedItem({
+            left: node,
+            candidateRightNodeIds: candidates,
+        }, fullContext);
     });
     const rightItems = matching.unmatchedRight.map((node) => {
         const candidates = matching.candidatesForRight.get(node.node_id) ?? [];
-        omittedCandidateReferences += Math.max(0, candidates.length - context.maxCandidates);
-        return unmatchedItem(node, "right", candidates.slice(0, context.maxCandidates), fullContext);
+        return unmatchedItem({
+            right: node,
+            candidateLeftNodeIds: candidates,
+        }, fullContext);
     });
     return {
         items: [
@@ -29,7 +32,6 @@ export const classifyJavaScriptApplicationVersions = (matching, context) => {
             ...leftItems,
             ...rightItems,
         ].sort((left, right) => compareCodePoints(left.item_id, right.item_id)),
-        omittedCandidateReferences,
     };
 };
 const matchedItem = (pair, context) => {
@@ -49,62 +51,127 @@ const matchedItem = (pair, context) => {
         node_kind: pair.left.kind,
         left_node_id: pair.left.node_id,
         right_node_id: pair.right.node_id,
-        match: {
-            status: "matched",
-            basis: pair.basis,
-            confidence: pair.confidence,
-            candidate_left_node_ids: [],
-            candidate_right_node_ids: [],
-        },
+        match: matchedMatch(pair),
         dimensions: finalDimensions,
         evidence_links: itemEvidenceLinks(pair.left, pair.right, context),
         limitations: pairLimitations(pair, status),
     };
     return itemWithId(semantic);
 };
-const unmatchedItem = (node, side, candidates, context) => {
-    const ambiguous = candidates.length > 0;
-    const oppositeComplete = (side === "left" ? context.rightGraph : context.leftGraph).coverage
-        .status === "complete";
-    const status = ambiguous
-        ? "unknown"
-        : oppositeComplete
-            ? side === "left"
-                ? "removed"
-                : "added"
-            : "unknown";
-    const semantic = {
-        status,
+const unmatchedItem = (member, context) => member.left === undefined
+    ? rightOnlyItem(member.right, member.candidateLeftNodeIds, context)
+    : leftOnlyItem(member.left, member.candidateRightNodeIds, context);
+const leftOnlyItem = (node, candidateNodeIds, context) => {
+    const [firstCandidate, ...remainingCandidates] = candidateNodeIds;
+    const common = {
         node_kind: node.kind,
-        left_node_id: side === "left" ? node.node_id : null,
-        right_node_id: side === "right" ? node.node_id : null,
-        match: {
-            status: ambiguous ? "ambiguous" : "unmatched",
-            basis: "none",
-            confidence: "unknown",
-            candidate_left_node_ids: side === "right" ? [...candidates] : [],
-            candidate_right_node_ids: side === "left" ? [...candidates] : [],
-        },
-        dimensions: [
-            "availability",
-            ...(status === "unknown" && !ambiguous ? ["coverage"] : []),
-        ],
-        evidence_links: itemEvidenceLinks(side === "left" ? node : undefined, side === "right" ? node : undefined, context),
-        limitations: [
-            ...(ambiguous
-                ? [
-                    "Multiple nodes share the same permitted match key; no cross-version pair was selected.",
-                ]
-                : []),
-            ...(status === "unknown" && !ambiguous
-                ? [
-                    "The opposite graph is incomplete, so an unmatched node cannot be classified as added or removed.",
-                ]
-                : []),
-        ],
+        evidence_links: itemEvidenceLinks(node, undefined, context),
     };
-    return itemWithId(semantic);
+    if (firstCandidate !== undefined)
+        return itemWithId({
+            ...common,
+            status: "unknown",
+            left_node_id: node.node_id,
+            right_node_id: null,
+            match: {
+                status: "ambiguous",
+                basis: "none",
+                confidence: "unknown",
+                candidate_left_node_ids: [],
+                candidate_right_node_ids: [firstCandidate, ...remainingCandidates],
+            },
+            dimensions: ["availability"],
+            limitations: [AMBIGUOUS_MATCH_LIMITATION],
+        });
+    const absenceObserved = context.rightGraph.coverage.status === "complete";
+    return itemWithId({
+        ...common,
+        status: absenceObserved ? "removed" : "unknown",
+        left_node_id: node.node_id,
+        right_node_id: null,
+        match: unmatchedMatch(),
+        dimensions: absenceObserved
+            ? ["availability"]
+            : ["availability", "coverage"],
+        limitations: absenceObserved ? [] : [INCOMPLETE_GRAPH_LIMITATION],
+    });
+};
+const rightOnlyItem = (node, candidateNodeIds, context) => {
+    const [firstCandidate, ...remainingCandidates] = candidateNodeIds;
+    const common = {
+        node_kind: node.kind,
+        evidence_links: itemEvidenceLinks(undefined, node, context),
+    };
+    if (firstCandidate !== undefined)
+        return itemWithId({
+            ...common,
+            status: "unknown",
+            left_node_id: null,
+            right_node_id: node.node_id,
+            match: {
+                status: "ambiguous",
+                basis: "none",
+                confidence: "unknown",
+                candidate_left_node_ids: [firstCandidate, ...remainingCandidates],
+                candidate_right_node_ids: [],
+            },
+            dimensions: ["availability"],
+            limitations: [AMBIGUOUS_MATCH_LIMITATION],
+        });
+    const absenceObserved = context.leftGraph.coverage.status === "complete";
+    return itemWithId({
+        ...common,
+        status: absenceObserved ? "added" : "unknown",
+        left_node_id: null,
+        right_node_id: node.node_id,
+        match: unmatchedMatch(),
+        dimensions: absenceObserved
+            ? ["availability"]
+            : ["availability", "coverage"],
+        limitations: absenceObserved ? [] : [INCOMPLETE_GRAPH_LIMITATION],
+    });
 };
+const matchedMatch = (pair) => {
+    const candidates = {
+        candidate_left_node_ids: [],
+        candidate_right_node_ids: [],
+    };
+    switch (pair.basis) {
+        case "exact-node-identity":
+        case "exact-content-digest":
+        case "exact-module-source-digest":
+            return {
+                status: "matched",
+                basis: pair.basis,
+                confidence: "exact",
+                ...candidates,
+            };
+        case "source-map-identity":
+            return {
+                status: "matched",
+                basis: pair.basis,
+                confidence: "high",
+                ...candidates,
+            };
+        case "structural-fingerprint":
+        case "semantic-key":
+            return {
+                status: "matched",
+                basis: pair.basis,
+                confidence: "medium",
+                ...candidates,
+            };
+    }
+};
+const unmatchedMatch = () => ({
+    status: "unmatched",
+    basis: "none",
+    confidence: "unknown",
+    candidate_left_node_ids: [],
+    candidate_right_node_ids: [],
+});
+const AMBIGUOUS_MATCH_LIMITATION = "Multiple nodes share the same permitted match key; no cross-version pair was selected.";
+const INCOMPLETE_GRAPH_LIMITATION = "The opposite graph is incomplete, so an unmatched node cannot be classified as added or removed.";
 const changedDimensions = (pair, context) => {
     const dimensions = [];
     const leftContent = contentIdentity(pair.left);

package/dist/domain/javascriptApplicationVersionKeys.js

@@ -1,19 +1,29 @@
 import { compareCodePoints } from "./javascriptApplicationGraph.js";
 const matchTiers = () => [
-    { basis: "exact-content-digest", confidence: "exact", key: contentDigestKey },
     {
-        basis: "exact-module-source-digest",
-        confidence: "exact",
+        match: { basis: "exact-content-digest", confidence: "exact" },
+        key: contentDigestKey,
+    },
+    {
+        match: { basis: "exact-module-source-digest", confidence: "exact" },
         key: moduleSourceDigestKey,
     },
-    { basis: "exact-node-identity", confidence: "exact", key: nodeIdentityKey },
-    { basis: "source-map-identity", confidence: "high", key: sourceMapKey },
     {
-        basis: "structural-fingerprint",
-        confidence: "medium",
+        match: { basis: "exact-node-identity", confidence: "exact" },
+        key: nodeIdentityKey,
+    },
+    {
+        match: { basis: "source-map-identity", confidence: "high" },
+        key: sourceMapKey,
+    },
+    {
+        match: { basis: "structural-fingerprint", confidence: "medium" },
         key: structuralFingerprintKey,
     },
-    { basis: "semantic-key", confidence: "medium", key: semanticKey },
+    {
+        match: { basis: "semantic-key", confidence: "medium" },
+        key: semanticKey,
+    },
 ];
 /** Apply ordered, unique-only matching tiers without fuzzy pairing. */
 export const matchJavaScriptApplicationVersions = (leftNodes, rightNodes) => {
@@ -51,7 +61,11 @@ const applyTier = (context) => {
         const rightNode = rightGroup[0];
         if (leftNode === undefined || rightNode === undefined)
             continue;
-        context.pairs.push({ left: leftNode, right: rightNode, ...context.tier });
+        context.pairs.push({
+            left: leftNode,
+            right: rightNode,
+            ...context.tier.match,
+        });
         context.left.delete(leftNode.node_id);
         context.right.delete(rightNode.node_id);
     }
@@ -105,8 +119,7 @@ const structuralFingerprintKey = (node) => {
         return null;
     const digest = uniqueStringProperty(node, "structural_fingerprint_sha256");
     const algorithm = uniqueStringProperty(node, "structural_fingerprint_algorithm");
-    const status = uniqueStringProperty(node, "structural_fingerprint_status");
-    return digest === null || algorithm === null || status !== "complete"
+    return digest === null || algorithm === null
         ? null
         : `structural\0${node.kind}\0${algorithm}\0${digest}`;
 };