rea-agents 1.6.0 → 2.0.0

package/dist/domain/inputIssueProjection.js

@@ -0,0 +1,52 @@
+/** Project Zod failures to secret-safe caller correction metadata. */
+export const projectInputIssues = (issues, input) => issues.flatMap((issue) => projectIssue(issue, input));
+const projectIssue = (issue, input) => {
+    const path = issue.path.flatMap((part) => typeof part === "string" || typeof part === "number" ? [part] : []);
+    if (issue.code === "unrecognized_keys")
+        return issue.keys.map((key) => ({
+            path: [...path, key],
+            reason: "unknown_argument",
+        }));
+    if (issue.code === "invalid_type")
+        return [
+            {
+                path,
+                reason: valueAtPath(input, path) === undefined
+                    ? "missing_argument"
+                    : "invalid_type",
+                expected: safeExpected(issue.expected),
+            },
+        ];
+    if (issue.code === "too_small")
+        return [boundedIssue(path, "minimum", numericBound(issue.minimum))];
+    if (issue.code === "too_big")
+        return [boundedIssue(path, "maximum", numericBound(issue.maximum))];
+    if (issue.code === "invalid_format")
+        return [{ path, reason: "invalid_format", expected: issue.format }];
+    if (issue.code === "invalid_value")
+        return [
+            {
+                path,
+                reason: "invalid_value",
+                expected: issue.values.filter(isSafeExpected),
+            },
+        ];
+    return [{ path, reason: "invalid_value" }];
+};
+const valueAtPath = (input, path) => {
+    let current = input;
+    for (const part of path) {
+        if (typeof current !== "object" || current === null)
+            return undefined;
+        current = current[part];
+    }
+    return current;
+};
+const numericBound = (value) => typeof value === "number" && Number.isFinite(value) ? value : undefined;
+const isSafeExpected = (value) => value === null || ["string", "number", "boolean"].includes(typeof value);
+const safeExpected = (value) => isSafeExpected(value) ? value : "schema-defined value";
+const boundedIssue = (path, key, value) => ({
+    path,
+    reason: "out_of_range",
+    ...(value === undefined ? {} : { [key]: value }),
+});

package/dist/domain/investigationWorkspace.js

@@ -125,7 +125,8 @@ export const investigationRunSummarySchema = z.object({
     comparison_evidence_id: evidenceIdSchema,
     limitations: z.array(z.string().max(4_096)).max(100),
 });
-const investigationWorkspaceSchema = z.object({
+/** Durable schema for one revisioned cross-version investigation workspace. */
+export const investigationWorkspaceSchema = z.object({
     workspace_version: z.literal(1),
     workspace_id: z.string().regex(/^ws_[a-f0-9]{64}$/u),
     name: z.string().trim().min(1).max(200),

package/dist/domain/javascriptApplicationAnalysis.js

@@ -0,0 +1,155 @@
+import { isAbsolute } from "node:path";
+import { z } from "zod";
+import { javascriptApplicationGraphSchema } from "./javascriptApplicationGraph.js";
+const MAX_GRAPH_NODES = 100_000;
+const MAX_GRAPH_EDGES = 200_000;
+const countSchema = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
+const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
+/** Default hard bounds for one local JavaScript application analysis. */
+export const JAVASCRIPT_APPLICATION_ANALYSIS_DEFAULT_LIMITS = {
+    max_entries: 8_000,
+    max_total_artifact_bytes: 512 * 1_024 * 1_024,
+    max_artifact_entry_bytes: 128 * 1_024 * 1_024,
+    max_compression_ratio: 1_000,
+    max_depth: 64,
+    max_path_bytes: 4_096,
+    max_text_files: 5_000,
+    max_total_text_bytes: 128 * 1_024 * 1_024,
+    max_text_file_bytes: 8 * 1_024 * 1_024,
+    max_ast_nodes: 2_000_000,
+    max_findings: 8_000,
+    max_modules: 20_000,
+    max_source_map_sources: 5_000,
+    max_parse_milliseconds: 30_000,
+};
+/** Combined artifact, text, AST, and graph projection bounds. */
+export const javascriptApplicationAnalysisLimitsSchema = z
+    .strictObject({
+    max_entries: z.number().int().min(1).max(1_000_000).default(8_000),
+    max_total_artifact_bytes: z
+        .number()
+        .int()
+        .min(1)
+        .max(Number.MAX_SAFE_INTEGER)
+        .default(512 * 1_024 * 1_024),
+    max_artifact_entry_bytes: z
+        .number()
+        .int()
+        .min(1)
+        .max(Number.MAX_SAFE_INTEGER)
+        .default(128 * 1_024 * 1_024),
+    max_compression_ratio: z.number().min(1).max(100_000).default(1_000),
+    max_depth: z.number().int().min(1).max(100).default(64),
+    max_path_bytes: z.number().int().min(1).max(65_535).default(4_096),
+    max_text_files: z.number().int().min(1).max(100_000).default(5_000),
+    max_total_text_bytes: z
+        .number()
+        .int()
+        .min(1)
+        .max(512 * 1_024 * 1_024)
+        .default(128 * 1_024 * 1_024),
+    max_text_file_bytes: z
+        .number()
+        .int()
+        .min(1)
+        .max(64 * 1_024 * 1_024)
+        .default(8 * 1_024 * 1_024),
+    max_ast_nodes: z.number().int().min(1).max(20_000_000).default(2_000_000),
+    max_findings: z.number().int().min(1).max(200_000).default(8_000),
+    max_modules: z.number().int().min(1).max(100_000).default(20_000),
+    max_source_map_sources: z.number().int().min(1).max(100_000).default(5_000),
+    max_parse_milliseconds: z
+        .number()
+        .int()
+        .min(1)
+        .max(300_000)
+        .default(30_000),
+})
+    .superRefine((limits, context) => {
+    const projectedNodes = 7 * limits.max_entries +
+        2 * limits.max_findings +
+        limits.max_modules +
+        limits.max_source_map_sources +
+        1;
+    if (projectedNodes > MAX_GRAPH_NODES)
+        context.addIssue({
+            code: "custom",
+            path: ["max_entries"],
+            message: "Combined application-analysis limits can exceed the 100000-node graph contract",
+        });
+    const projectedEdges = 9 * limits.max_entries +
+        6 * limits.max_findings +
+        limits.max_modules +
+        limits.max_source_map_sources;
+    if (projectedEdges > MAX_GRAPH_EDGES)
+        context.addIssue({
+            code: "custom",
+            path: ["max_entries"],
+            message: "Combined application-analysis limits can exceed the 200000-edge graph contract",
+        });
+});
+/** Public target-free request for bounded static JavaScript application analysis. */
+export const analyzeJavaScriptApplicationInputSchema = z.strictObject({
+    input_path: z
+        .string()
+        .min(1)
+        .max(16_384)
+        .refine(isAbsolute, "JavaScript application input path must be absolute"),
+    format: z.enum(["auto", "asar", "directory"]).default("auto"),
+    approved: z.literal(true),
+    source_map_read_approved: z.boolean().default(false),
+    limits: javascriptApplicationAnalysisLimitsSchema.default(JAVASCRIPT_APPLICATION_ANALYSIS_DEFAULT_LIMITS),
+});
+/** Compact counts for the high-level Electron architecture/security surface. */
+const electronBoundarySummarySchema = z.strictObject({
+    browser_windows: countSchema,
+    explicit_web_preferences: countSchema,
+    preload_entrypoints: countSchema,
+    context_bridge_apis: countSchema,
+    exposed_api_members: countSchema,
+    ipc: z.strictObject({
+        operations: countSchema,
+        literal_channels: countSchema,
+        dynamic_channel_operations: countSchema,
+        renderer_transmissions: countSchema,
+        renderer_listeners: countSchema,
+        main_handlers: countSchema,
+        paired_renderer_transmissions: countSchema,
+        ambiguous_renderer_transmissions: countSchema,
+        unpaired_literal_renderer_transmissions: countSchema,
+    }),
+    sender_validation_observations: countSchema,
+    utility_processes: countSchema,
+    resolved_utility_entrypoints: countSchema,
+    native_addon_bindings: countSchema,
+    resolved_native_addon_bindings: countSchema,
+});
+const reconstructionStatisticsSchema = z.strictObject({
+    relevant_files: countSchema,
+    nested_asar_containers: countSchema,
+    text_files_selected: countSchema,
+    text_bytes_read: countSchema,
+    omitted_text_files: countSchema,
+    limit_omitted_text_files: countSchema,
+    policy_filtered_text_files: countSchema,
+    invalid_utf8_files: countSchema,
+    parsed_javascript_files: countSchema,
+    visited_ast_nodes: countSchema,
+    findings: countSchema,
+    modules: countSchema,
+    parse_failures: countSchema,
+    truncated_scopes: countSchema,
+});
+/** Strict high-level result returned inside Evidence v2. */
+export const javascriptApplicationAnalysisResultSchema = z.strictObject({
+    schema_version: z.literal(1),
+    input_path: z.string().min(1).max(16_384),
+    format: z.enum(["asar", "directory"]),
+    root_artifact_sha256: digestSchema,
+    inventory_manifest_id: z.string().regex(/^agm_[a-f0-9]{64}$/u),
+    inventory_graph_sha256: digestSchema,
+    graph: javascriptApplicationGraphSchema,
+    summary: electronBoundarySummarySchema,
+    statistics: reconstructionStatisticsSchema,
+    limitations: z.array(z.string().min(1).max(4_096)).max(1_000),
+});

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);