rea-agents 1.7.0 → 2.1.0

package/dist/domain/javascriptApplicationChangeGraph.js

@@ -0,0 +1,231 @@
+import { compareCodePoints, createJavaScriptApplicationEdge, createJavaScriptApplicationGraph, createJavaScriptApplicationNode, } from "./javascriptApplicationGraph.js";
+/** Merge compared nodes and add inferred right-to-left changed_from edges. */
+export const buildJavaScriptApplicationChangeGraph = (input) => {
+    const allNodes = nodeCandidates(input);
+    const preferredRoots = uniqueSorted([
+        ...input.right.root_node_ids,
+        ...input.left.root_node_ids,
+    ]).filter((nodeId) => allNodes.has(nodeId));
+    const orderedNodeIds = uniqueSorted([
+        ...preferredRoots,
+        ...input.items.flatMap(({ left_node_id: left, right_node_id: right }) => [
+            ...(right === null ? [] : [right]),
+            ...(left === null ? [] : [left]),
+        ]),
+    ]);
+    const retainedIds = orderedNodeIds.slice(0, input.limits.max_graph_nodes);
+    const retained = new Set(retainedIds);
+    const merged = mergeNodes(retainedIds.flatMap((nodeId) => allNodes.get(nodeId) ?? []));
+    const sourceEdges = uniqueEdges([
+        ...input.left.edges,
+        ...input.right.edges,
+    ]).filter(({ source_node_id: source, target_node_id: target }) => retained.has(source) && retained.has(target));
+    const comparisonEdges = input.items.flatMap((item) => changedFromEdge(item, input, retained));
+    const candidateEdges = uniqueEdges([...sourceEdges, ...comparisonEdges]);
+    const edges = candidateEdges.slice(0, input.limits.max_graph_edges);
+    const omittedNodes = Math.max(0, orderedNodeIds.length - retainedIds.length);
+    const omittedEdges = Math.max(0, candidateEdges.length - edges.length);
+    const graphOmissions = omittedNodes + omittedEdges + merged.omittedObservations;
+    const rootNodeIds = preferredRoots
+        .filter((nodeId) => retained.has(nodeId))
+        .slice(0, 1_000);
+    const fallbackRoot = merged.nodes[0]?.node_id;
+    const graph = createJavaScriptApplicationGraph({
+        schema: "JavaScriptApplicationGraph",
+        schema_version: 1,
+        root_node_ids: rootNodeIds.length > 0
+            ? rootNodeIds
+            : fallbackRoot === undefined
+                ? []
+                : [fallbackRoot],
+        nodes: merged.nodes,
+        edges,
+        coverage: changeGraphCoverage(input, graphOmissions),
+        limitations: uniqueSorted([
+            ...input.left.limitations.map((value) => `Left: ${value}`),
+            ...input.right.limitations.map((value) => `Right: ${value}`),
+            "changed_from edges are cross-version inferences and never promote structural or semantic matches to exact identity.",
+            "The change graph contains compared entities and their retained relationships; it is not an executable application.",
+            ...(graphOmissions === 0
+                ? []
+                : ["The change graph omitted content at explicit caller bounds."]),
+        ]),
+    });
+    return {
+        graph,
+        omittedNodes,
+        omittedEdges,
+        omittedObservations: merged.omittedObservations,
+    };
+};
+const nodeCandidates = (input) => {
+    const required = new Set([
+        ...input.left.root_node_ids,
+        ...input.right.root_node_ids,
+        ...input.items.flatMap(({ left_node_id: left, right_node_id: right }) => [
+            ...(left === null ? [] : [left]),
+            ...(right === null ? [] : [right]),
+        ]),
+    ]);
+    const output = new Map();
+    for (const node of [...input.left.nodes, ...input.right.nodes])
+        if (required.has(node.node_id))
+            output.set(node.node_id, [...(output.get(node.node_id) ?? []), node]);
+    return output;
+};
+const changedFromEdge = (item, input, retained) => {
+    const left = item.left_node_id;
+    const right = item.right_node_id;
+    if (item.match.status !== "matched" ||
+        item.status === "unchanged" ||
+        left === null ||
+        right === null ||
+        left === right ||
+        !retained.has(left) ||
+        !retained.has(right))
+        return [];
+    const evidence = comparisonEvidence(item, input);
+    return [
+        createJavaScriptApplicationEdge({
+            source_node_id: right,
+            target_node_id: left,
+            relation: "changed_from",
+            properties: {
+                comparison_item_id: item.item_id,
+                status: item.status,
+                match_basis: item.match.basis,
+                match_confidence: item.match.confidence,
+                dimensions: item.dimensions,
+            },
+            evidence,
+        }),
+    ];
+};
+const comparisonEvidence = (item, input) => {
+    const right = input.right.nodes.find(({ node_id: id }) => id === item.right_node_id);
+    const left = input.left.nodes.find(({ node_id: id }) => id === item.left_node_id);
+    const source = right?.observations[0]?.evidence ?? left?.observations[0]?.evidence;
+    const complete = input.left.coverage.status === "complete" &&
+        input.right.coverage.status === "complete" &&
+        input.omittedComparisonItems === 0;
+    return {
+        authority: "cross-version-comparison",
+        state: "inferred",
+        confidence: item.match.confidence === "medium" ? "medium" : "high",
+        artifact: source?.artifact ?? {
+            available: false,
+            reason: "unresolved",
+            detail: "Compared node has no artifact-backed observation.",
+        },
+        location: source?.location ?? {
+            available: false,
+            reason: "unresolved",
+            detail: "Compared node has no actionable source location.",
+        },
+        extractor: {
+            name: "rea-application-version-comparison",
+            version: "1",
+            operation: "compare_application_versions",
+            executable_sha256: null,
+        },
+        coverage: complete
+            ? { status: "complete", truncated: false, omitted_count: 0, limits: [] }
+            : {
+                status: "partial",
+                truncated: input.omittedComparisonItems > 0,
+                omitted_count: input.omittedComparisonItems > 0
+                    ? input.omittedComparisonItems
+                    : (source?.coverage.omitted_count ?? null),
+                limits: input.omittedComparisonItems > 0
+                    ? [
+                        {
+                            name: "max-comparison-items",
+                            value: input.limits.max_comparison_items,
+                            unit: "items",
+                        },
+                    ]
+                    : [],
+            },
+        limitations: [
+            "Cross-version pairing is inferred from the stated match basis; changed_from does not prove runtime reachability.",
+            ...item.limitations,
+        ],
+        evidence_ids: [input.leftEvidenceId, input.rightEvidenceId],
+    };
+};
+const changeGraphCoverage = (input, graphOmissions) => {
+    const outputOmissions = graphOmissions + input.omittedComparisonItems;
+    if (outputOmissions > 0)
+        return {
+            status: "partial",
+            truncated: true,
+            omitted_count: outputOmissions,
+            limits: [
+                {
+                    name: "max-comparison-items",
+                    value: input.limits.max_comparison_items,
+                    unit: "items",
+                },
+                {
+                    name: "max-graph-nodes",
+                    value: input.limits.max_graph_nodes,
+                    unit: "items",
+                },
+                {
+                    name: "max-graph-edges",
+                    value: input.limits.max_graph_edges,
+                    unit: "items",
+                },
+            ],
+        };
+    if (input.left.coverage.status === "complete" &&
+        input.right.coverage.status === "complete")
+        return {
+            status: "complete",
+            truncated: false,
+            omitted_count: 0,
+            limits: [],
+        };
+    const counts = [
+        input.left.coverage.omitted_count,
+        input.right.coverage.omitted_count,
+    ];
+    return {
+        status: "partial",
+        truncated: false,
+        omitted_count: counts.every((value) => value !== null)
+            ? counts.reduce((total, value) => total + (value ?? 0), 0)
+            : null,
+        limits: [],
+    };
+};
+const mergeNodes = (nodes) => {
+    const groups = new Map();
+    for (const node of nodes)
+        groups.set(node.node_id, [...(groups.get(node.node_id) ?? []), node]);
+    let omittedObservations = 0;
+    const merged = [...groups.values()].map((group) => {
+        const first = group[0];
+        if (first === undefined)
+            throw new TypeError("Empty change-graph node group");
+        const observations = [
+            ...new Map(group
+                .flatMap(({ observations: values }) => values)
+                .map((observation) => [observation.observation_id, observation])).values(),
+        ].sort((left, right) => compareCodePoints(left.observation_id, right.observation_id));
+        omittedObservations += Math.max(0, observations.length - 64);
+        return createJavaScriptApplicationNode({
+            kind: first.kind,
+            identity: first.identity,
+            observations: observations
+                .slice(0, 64)
+                .map(({ observation_id: _id, identifier_strategy: _strategy, ...value }) => value),
+        });
+    });
+    return {
+        nodes: merged.sort((left, right) => compareCodePoints(left.node_id, right.node_id)),
+        omittedObservations,
+    };
+};
+const uniqueEdges = (edges) => [...new Map(edges.map((edge) => [edge.edge_id, edge])).values()].sort((left, right) => compareCodePoints(left.edge_id, right.edge_id));
+const uniqueSorted = (values) => [...new Set(values)].sort(compareCodePoints);

package/dist/domain/javascriptApplicationEvidenceSchemas.js

@@ -19,8 +19,11 @@ const applicationEvidenceAuthoritySchema = z.enum([
     "ast-static-analysis",
     "static-relationship-inference",
     "passive-cdp-runtime",
+    "cross-layer-reconciliation",
+    "cross-version-comparison",
     "controlled-replay",
     "native-analysis-provider",
+    "managed-static-analysis",
     "historical-reference",
     "user-assertion",
     "unknown",
@@ -223,6 +226,20 @@ const checkAuthorityState = (evidence, context) => {
             path: ["state"],
             message: "Static relationship authority must remain inferred",
         });
+    if (evidence.authority === "cross-layer-reconciliation" &&
+        evidence.state !== "inferred")
+        context.addIssue({
+            code: "custom",
+            path: ["state"],
+            message: "Cross-layer reconciliation authority must remain inferred",
+        });
+    if (evidence.authority === "cross-version-comparison" &&
+        evidence.state !== "inferred")
+        context.addIssue({
+            code: "custom",
+            path: ["state"],
+            message: "Cross-version comparison authority must remain inferred",
+        });
     if (evidence.authority === "unknown" &&
         !["unknown", "unavailable"].includes(evidence.state))
         context.addIssue({
@@ -285,6 +302,7 @@ const checkArtifactBacking = (evidence, context) => {
         "ast-static-analysis",
         "controlled-replay",
         "native-analysis-provider",
+        "managed-static-analysis",
     ].includes(evidence.authority);
     if (artifactBacked &&
         evidence.state !== "unavailable" &&

package/dist/domain/javascriptApplicationGraph.js

@@ -2,7 +2,8 @@ import { createHash } from "node:crypto";
 import canonicalize from "canonicalize";
 import { z } from "zod";
 import { applicationEdgeInputSchema, applicationEdgeSchema, applicationNodeInputSchema, applicationNodeObservationSchema, applicationNodeSchema, javascriptApplicationGraphInputSchema, javascriptApplicationGraphRecordSchema, } from "./javascriptApplicationGraphSchemas.js";
-const compareCodePoints = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+/** Compare strings by Unicode code point for canonical graph ordering. */
+export const compareCodePoints = (left, right) => left < right ? -1 : left > right ? 1 : 0;
 const canonicalJson = (value) => {
     const encoded = canonicalize(value);
     if (encoded === undefined)

package/dist/domain/javascriptApplicationGraphSchemas.js

@@ -30,6 +30,13 @@ export const JAVASCRIPT_APPLICATION_NODE_KINDS = [
     "storage",
     "native-addon",
     "native-export",
+    "managed-assembly",
+    "managed-module",
+    "managed-type",
+    "managed-method",
+    "managed-field",
+    "managed-pinvoke-import",
+    "managed-native-implementation",
     "runtime-script-instance",
     "unknown",
 ];

package/dist/domain/javascriptApplicationVersionComparison.js

@@ -0,0 +1,116 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { buildJavaScriptApplicationChangeGraph } from "./javascriptApplicationChangeGraph.js";
+import { applicationVersionComparisonResultSchema, } from "./javascriptApplicationVersionComparisonSchemas.js";
+import { compareCodePoints } from "./javascriptApplicationGraph.js";
+import { classifyJavaScriptApplicationVersions } from "./javascriptApplicationVersionItems.js";
+import { matchJavaScriptApplicationVersions } from "./javascriptApplicationVersionKeys.js";
+/** Compare application entities with ordered unique-only identity tiers. */
+export const compareJavaScriptApplicationVersions = (input) => {
+    const matching = matchJavaScriptApplicationVersions(input.left.graph.nodes, input.right.graph.nodes);
+    const projection = classifyJavaScriptApplicationVersions(matching, {
+        leftGraph: input.left.graph,
+        rightGraph: input.right.graph,
+        leftEvidenceId: input.left.evidenceId,
+        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,
+    });
+    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,
+    };
+    const semantic = {
+        schema_version: 1,
+        left: {
+            evidence_id: input.left.evidenceId,
+            graph_id: input.left.graph.graph_id,
+            root_artifact_sha256: input.left.rootArtifactSha256,
+        },
+        right: {
+            evidence_id: input.right.evidenceId,
+            graph_id: input.right.graph.graph_id,
+            root_artifact_sha256: input.right.rootArtifactSha256,
+        },
+        summary: summary(projection.items),
+        matching: matchingSummary(projection.items),
+        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,
+        },
+        evidence_links: evidenceLinks,
+        limitations: comparisonLimitations(input, omissions),
+    };
+    return applicationVersionComparisonResultSchema.parse({
+        ...semantic,
+        comparison_id: `javc_${digestCanonical(semantic)}`,
+    });
+};
+const summary = (items) => ({
+    unchanged: countStatus(items, "unchanged"),
+    added: countStatus(items, "added"),
+    removed: countStatus(items, "removed"),
+    changed: countStatus(items, "changed"),
+    unknown: countStatus(items, "unknown"),
+});
+const countStatus = (items, status) => items.filter((item) => item.status === status).length;
+const matchingSummary = (items) => ({
+    exact_node_identity: countBasis(items, "exact-node-identity"),
+    exact_content_digest: countBasis(items, "exact-content-digest"),
+    exact_module_source_digest: countBasis(items, "exact-module-source-digest"),
+    source_map_identity: countBasis(items, "source-map-identity"),
+    structural_fingerprint: countBasis(items, "structural-fingerprint"),
+    semantic_key: countBasis(items, "semantic-key"),
+    ambiguous: items.filter(({ match }) => match.status === "ambiguous").length,
+    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([
+    "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.",
+    "The comparison reads retained graphs and Evidence only; it does not execute either application.",
+    "Native Evidence is linked only by exact subject digest; provider snapshot reuse remains target/provider/profile exact.",
+    ...(input.left.graph.coverage.status === "complete" &&
+        input.right.graph.coverage.status === "complete"
+        ? []
+        : [
+            "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);
+    if (encoded === undefined)
+        throw new TypeError("Application version comparison could not canonicalize data");
+    return createHash("sha256").update(encoded).digest("hex");
+};
+const uniqueSorted = (values) => [...new Set(values)].sort(compareCodePoints);

package/dist/domain/javascriptApplicationVersionComparisonSchemas.js

@@ -0,0 +1,139 @@
+import { z } from "zod";
+import { evidenceSchema } from "./evidence.js";
+import { javascriptApplicationGraphSchema } from "./javascriptApplicationGraph.js";
+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. */
+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(),
+})
+    .superRefine((input, context) => {
+    if (input.left.evidence_id === input.right.evidence_id)
+        context.addIssue({
+            code: "custom",
+            path: ["right"],
+            message: "Application version Evidence must be distinct",
+        });
+    for (const side of [
+        "left_native_observations",
+        "right_native_observations",
+    ]) {
+        const ids = input[side].map(({ evidence_id: id }) => id);
+        if (new Set(ids).size !== ids.length)
+            context.addIssue({
+                code: "custom",
+                path: [side],
+                message: "Native observations must be unique on each side",
+            });
+    }
+});
+const applicationVersionMatchBasisSchema = z.enum([
+    "exact-node-identity",
+    "exact-content-digest",
+    "exact-module-source-digest",
+    "source-map-identity",
+    "structural-fingerprint",
+    "semantic-key",
+    "none",
+]);
+const comparisonItemSchema = z.strictObject({
+    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([
+        "content",
+        "location",
+        "properties",
+        "relationships",
+        "availability",
+        "coverage",
+    ]))
+        .max(6),
+    evidence_links: z.array(evidenceIdSchema).min(2).max(130),
+    limitations: z.array(boundedTextSchema).max(100),
+});
+/** Tiered module/entity matching plus a bounded cross-version change graph. */
+export const applicationVersionComparisonResultSchema = z.strictObject({
+    schema_version: z.literal(1),
+    comparison_id: z.string().regex(/^javc_[a-f0-9]{64}$/u),
+    left: z.strictObject({
+        evidence_id: evidenceIdSchema,
+        graph_id: z.string().regex(/^jag_[a-f0-9]{64}$/u),
+        root_artifact_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+    }),
+    right: z.strictObject({
+        evidence_id: evidenceIdSchema,
+        graph_id: z.string().regex(/^jag_[a-f0-9]{64}$/u),
+        root_artifact_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+    }),
+    summary: z.strictObject({
+        unchanged: z.number().int().min(0),
+        added: z.number().int().min(0),
+        removed: z.number().int().min(0),
+        changed: z.number().int().min(0),
+        unknown: z.number().int().min(0),
+    }),
+    matching: z.strictObject({
+        exact_node_identity: z.number().int().min(0),
+        exact_content_digest: z.number().int().min(0),
+        exact_module_source_digest: z.number().int().min(0),
+        source_map_identity: z.number().int().min(0),
+        structural_fingerprint: z.number().int().min(0),
+        semantic_key: z.number().int().min(0),
+        ambiguous: z.number().int().min(0),
+        unmatched: z.number().int().min(0),
+    }),
+    items: z.array(comparisonItemSchema).max(50_000),
+    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),
+});