rea-agents 1.7.0 → 2.1.0

package/dist/domain/javascriptFeatureTrace.js

@@ -0,0 +1,232 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { compareCodePoints, createJavaScriptApplicationGraph, } from "./javascriptApplicationGraph.js";
+import { applicationFeatureTraceResultSchema, } from "./javascriptFeatureTraceSchemas.js";
+import { findApplicationFeatureSeeds, } from "./javascriptFeatureSeed.js";
+import { traverseApplicationFeature, } from "./javascriptFeatureTraversal.js";
+import { buildJavaScriptNativeHandoffs } from "./javascriptNativeHandoff.js";
+/** Trace a literal feature through a bounded, authority-preserving JAG. */
+export const traceApplicationFeature = (input) => {
+    const allSeedMatches = findApplicationFeatureSeeds(input.graph.nodes, input.seed);
+    const seedMatches = allSeedMatches.slice(0, input.limits.max_seed_matches);
+    if (seedMatches.length === 0)
+        return noMatchResult(input);
+    const traversal = traverseApplicationFeature(input.graph, seedMatches.map(({ node_id: id }) => id), input.direction, input.limits);
+    const graph = traceGraph(input, seedMatches, traversal, allSeedMatches.length);
+    const allPaths = terminalPaths(traversal, seedMatches);
+    const paths = allPaths.slice(0, input.limits.max_paths);
+    const nativeHandoffs = buildJavaScriptNativeHandoffs(traversal.nodes, traversal.edges, input.nativeEvidence);
+    const evidenceLinks = uniqueSorted([
+        input.sourceEvidenceId,
+        ...nativeHandoffs.flatMap(({ evidence_ids: ids }) => ids),
+    ]);
+    const omissions = traceOmissions(input, traversal, allSeedMatches.length, allPaths.length);
+    const semantic = {
+        schema_version: 1,
+        source_evidence_id: input.sourceEvidenceId,
+        source_graph_id: input.graph.graph_id,
+        seed: input.seed,
+        direction: input.direction,
+        seed_matches: seedMatches,
+        graph,
+        paths,
+        native_handoffs: nativeHandoffs,
+        summary: {
+            matched_seeds: seedMatches.length,
+            traced_nodes: traversal.nodes.length,
+            traced_edges: traversal.edges.length,
+            terminal_paths: paths.length,
+            native_handoffs: nativeHandoffs.length,
+            ...factSummary(traversal.nodes, traversal.edges),
+        },
+        coverage: {
+            status: traceCoverageStatus(input.graph, omissions),
+            source_graph_status: input.graph.coverage.status,
+            scanned_nodes: input.graph.nodes.length,
+            total_seed_matches: allSeedMatches.length,
+            ...omissions,
+            frontier_node_ids: traversal.frontierNodeIds,
+        },
+        evidence_links: evidenceLinks,
+        limitations: traceLimitations(input.graph, omissions),
+    };
+    return applicationFeatureTraceResultSchema.parse({
+        ...semantic,
+        trace_id: `jatr_${digestCanonical(semantic)}`,
+    });
+};
+const noMatchResult = (input) => {
+    const semantic = {
+        schema_version: 1,
+        source_evidence_id: input.sourceEvidenceId,
+        source_graph_id: input.graph.graph_id,
+        seed: input.seed,
+        direction: input.direction,
+        seed_matches: [],
+        graph: null,
+        paths: [],
+        native_handoffs: [],
+        summary: {
+            matched_seeds: 0,
+            traced_nodes: 0,
+            traced_edges: 0,
+            terminal_paths: 0,
+            native_handoffs: 0,
+            observed_facts: 0,
+            inferred_facts: 0,
+            unknown_facts: 0,
+            unavailable_facts: 0,
+        },
+        coverage: {
+            status: "no-match",
+            source_graph_status: input.graph.coverage.status,
+            scanned_nodes: input.graph.nodes.length,
+            total_seed_matches: 0,
+            omitted_seed_matches: 0,
+            omitted_nodes: 0,
+            omitted_edges: 0,
+            omitted_paths: 0,
+            frontier_node_ids: [],
+        },
+        evidence_links: [input.sourceEvidenceId],
+        limitations: uniqueSorted([
+            "No graph entity matched the literal seed; this is not evidence that the feature is absent.",
+            ...sourceCoverageLimitations(input.graph),
+        ]),
+    };
+    return applicationFeatureTraceResultSchema.parse({
+        ...semantic,
+        trace_id: `jatr_${digestCanonical(semantic)}`,
+    });
+};
+const traceGraph = (input, seedMatches, traversal, totalSeedMatches) => {
+    const omitted = traversal.omittedNodeCount +
+        traversal.omittedEdgeCount +
+        (totalSeedMatches - seedMatches.length);
+    return createJavaScriptApplicationGraph({
+        schema: "JavaScriptApplicationGraph",
+        schema_version: 1,
+        root_node_ids: uniqueSorted(seedMatches.map(({ node_id: id }) => id)),
+        nodes: traversal.nodes,
+        edges: traversal.edges,
+        coverage: traceGraphCoverage(input.graph, input.limits, omitted),
+        limitations: uniqueSorted([
+            ...input.graph.limitations,
+            "Trace edges retain their source authority; graph connectivity does not prove runtime execution or reachability.",
+            ...(omitted === 0
+                ? []
+                : ["Trace output stopped at explicit caller bounds."]),
+        ]),
+    });
+};
+const traceGraphCoverage = (source, limits, omitted) => {
+    if (omitted > 0)
+        return {
+            status: "partial",
+            truncated: true,
+            omitted_count: omitted,
+            limits: [
+                {
+                    name: "max-seed-matches",
+                    value: limits.max_seed_matches,
+                    unit: "items",
+                },
+                { name: "max-depth", value: limits.max_depth, unit: "depth" },
+                { name: "max-nodes", value: limits.max_nodes, unit: "items" },
+                { name: "max-edges", value: limits.max_edges, unit: "items" },
+            ],
+        };
+    return source.coverage.status === "complete"
+        ? { status: "complete", truncated: false, omitted_count: 0, limits: [] }
+        : {
+            status: source.coverage.status,
+            truncated: source.coverage.truncated,
+            omitted_count: source.coverage.omitted_count,
+            limits: source.coverage.limits,
+        };
+};
+const terminalPaths = (traversal, seeds) => {
+    const seedIds = new Set(seeds.map(({ node_id: id }) => id));
+    const edgeById = new Map(traversal.edges.map((edge) => [edge.edge_id, edge]));
+    return traversal.nodes
+        .filter((node) => isTerminal(node) &&
+        (!seedIds.has(node.node_id) || traversal.nodes.length === 1))
+        .map((node) => pathTo(node, traversal.predecessors, edgeById))
+        .filter((path) => path !== null)
+        .sort((left, right) => compareCodePoints(left.path_id, right.path_id));
+};
+const pathTo = (node, predecessors, edgeById) => {
+    const nodeIds = [node.node_id];
+    const edgeIds = [];
+    let current = node.node_id;
+    while (predecessors.has(current)) {
+        const predecessor = predecessors.get(current);
+        if (predecessor === undefined)
+            break;
+        nodeIds.push(predecessor.previousNodeId);
+        edgeIds.push(predecessor.edgeId);
+        current = predecessor.previousNodeId;
+    }
+    nodeIds.reverse();
+    edgeIds.reverse();
+    const edges = edgeIds
+        .map((edgeId) => edgeById.get(edgeId))
+        .filter((edge) => edge !== undefined);
+    if (edges.length !== edgeIds.length)
+        return null;
+    const semantic = {
+        start_node_id: nodeIds[0] ?? node.node_id,
+        end_node_id: node.node_id,
+        end_kind: node.kind,
+        node_ids: nodeIds,
+        edge_ids: edgeIds,
+        authorities: uniqueSorted(edges.map(({ evidence }) => evidence.authority)),
+        contains_inference: edges.some(({ evidence }) => evidence.state === "inferred"),
+    };
+    return { ...semantic, path_id: `jatp_${digestCanonical(semantic)}` };
+};
+const isTerminal = (node) => ["endpoint", "storage", "native-addon", "native-export", "unknown"].includes(node.kind);
+const factSummary = (nodes, edges) => {
+    const states = [
+        ...nodes.flatMap(({ observations }) => observations.map(({ evidence }) => evidence.state)),
+        ...edges.map(({ evidence }) => evidence.state),
+    ];
+    return {
+        observed_facts: states.filter((state) => state === "observed").length,
+        inferred_facts: states.filter((state) => state === "inferred").length,
+        unknown_facts: states.filter((state) => state === "unknown").length,
+        unavailable_facts: states.filter((state) => state === "unavailable").length,
+    };
+};
+const traceOmissions = (input, traversal, seedMatches, paths) => ({
+    omitted_seed_matches: Math.max(0, seedMatches - input.limits.max_seed_matches),
+    omitted_nodes: traversal.omittedNodeCount,
+    omitted_edges: traversal.omittedEdgeCount,
+    omitted_paths: Math.max(0, paths - input.limits.max_paths),
+});
+const traceCoverageStatus = (graph, omissions) => Object.values(omissions).some((value) => value > 0)
+    ? "truncated"
+    : graph.coverage.status === "complete"
+        ? "complete-within-source"
+        : "partial";
+const traceLimitations = (graph, omissions) => uniqueSorted([
+    "A trace reports graph relationships, not proof that code executed or that a feature is reachable in every state.",
+    "Static, native, passive-runtime, inferred, and unknown facts retain their original authority in the returned graph.",
+    "Native handoffs never open a binary or invoke a provider automatically; snapshot reuse remains provider/profile/target exact.",
+    ...sourceCoverageLimitations(graph),
+    ...(Object.values(omissions).some((value) => value > 0)
+        ? ["Trace results were truncated at explicit caller limits."]
+        : []),
+]);
+const sourceCoverageLimitations = (graph) => graph.coverage.status === "complete"
+    ? []
+    : [
+        "The source application graph is incomplete; unmatched seeds and frontiers remain unknown.",
+    ];
+const digestCanonical = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError("Feature trace could not canonicalize data");
+    return createHash("sha256").update(encoded).digest("hex");
+};
+const uniqueSorted = (values) => [...new Set(values)].sort(compareCodePoints);

package/dist/domain/javascriptFeatureTraceSchemas.js

@@ -0,0 +1,136 @@
+import { z } from "zod";
+import { evidenceSchema, providerSchema } from "./evidence.js";
+import { javascriptApplicationGraphSchema } from "./javascriptApplicationGraph.js";
+const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
+const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
+const nodeIdSchema = z.string().regex(/^jag_node_[a-f0-9]{64}$/u);
+const edgeIdSchema = z.string().regex(/^jag_edge_[a-f0-9]{64}$/u);
+const boundedTextSchema = z.string().min(1).max(4_096);
+/** Literal starting point for one bounded application trace. */
+const applicationFeatureSeedSchema = z.strictObject({
+    kind: z.enum([
+        "node-id",
+        "route",
+        "string",
+        "api",
+        "channel",
+        "module",
+        "native-export",
+    ]),
+    value: boundedTextSchema,
+    match: z.enum(["exact", "contains"]).nullable().default(null),
+    case_sensitive: z.boolean().default(false),
+});
+const featureTraceLimitsSchema = z.strictObject({
+    max_seed_matches: z.number().int().min(1).max(1_000).default(25),
+    max_depth: z.number().int().min(0).max(64).default(12),
+    max_nodes: z.number().int().min(1).max(50_000).default(2_000),
+    max_edges: z.number().int().min(1).max(100_000).default(4_000),
+    max_paths: z.number().int().min(1).max(1_000).default(100),
+});
+/** Evidence-backed application graph and explicit trace bounds. */
+export const traceApplicationFeatureInputSchema = z
+    .strictObject({
+    application: evidenceSchema,
+    native_observations: z.array(evidenceSchema).max(64).default([]),
+    seed: applicationFeatureSeedSchema,
+    direction: z.enum(["outgoing", "incoming", "both"]).default("both"),
+    limits: featureTraceLimitsSchema.default({
+        max_seed_matches: 25,
+        max_depth: 12,
+        max_nodes: 2_000,
+        max_edges: 4_000,
+        max_paths: 100,
+    }),
+})
+    .superRefine((input, context) => {
+    const ids = input.native_observations.map(({ evidence_id: id }) => id);
+    if (new Set(ids).size !== ids.length)
+        context.addIssue({
+            code: "custom",
+            path: ["native_observations"],
+            message: "Native observations must be unique",
+        });
+});
+const seedMatchSchema = z.strictObject({
+    node_id: nodeIdSchema,
+    kind: z.string().min(1).max(128),
+    basis: z.enum(["node-id", "label", "identity", "property"]),
+    field: z.string().min(1).max(256),
+});
+const tracePathSchema = z.strictObject({
+    path_id: z.string().regex(/^jatp_[a-f0-9]{64}$/u),
+    start_node_id: nodeIdSchema,
+    end_node_id: nodeIdSchema,
+    end_kind: z.string().min(1).max(128),
+    node_ids: z.array(nodeIdSchema).min(1).max(65),
+    edge_ids: z.array(edgeIdSchema).max(64),
+    authorities: z.array(z.string().min(1).max(128)).max(16),
+    contains_inference: z.boolean(),
+});
+const nativeHandoffSchema = z.strictObject({
+    native_node_id: nodeIdSchema,
+    artifact_sha256: digestSchema,
+    artifact_path: z.string().min(1).max(4_096).nullable(),
+    export_node_ids: z.array(nodeIdSchema).max(1_000),
+    requested_exports: z.array(boundedTextSchema).max(1_000),
+    status: z.enum(["evidence-linked", "requires-provider-analysis"]),
+    providers: z.array(providerSchema).max(64),
+    evidence_ids: z.array(evidenceIdSchema).max(64),
+    recommended_tools: z
+        .array(z.enum([
+        "open_binary",
+        "binary_overview",
+        "search_procedures",
+        "analyze_function",
+        "xrefs",
+    ]))
+        .max(5),
+});
+/** Evidence-preserving bounded subgraph and native-analysis frontiers. */
+export const applicationFeatureTraceResultSchema = z.strictObject({
+    schema_version: z.literal(1),
+    trace_id: z.string().regex(/^jatr_[a-f0-9]{64}$/u),
+    source_evidence_id: evidenceIdSchema,
+    source_graph_id: z.string().regex(/^jag_[a-f0-9]{64}$/u),
+    seed: applicationFeatureSeedSchema,
+    direction: z.enum(["outgoing", "incoming", "both"]),
+    seed_matches: z.array(seedMatchSchema).max(1_000),
+    graph: javascriptApplicationGraphSchema.nullable(),
+    paths: z.array(tracePathSchema).max(1_000),
+    native_handoffs: z.array(nativeHandoffSchema).max(10_000),
+    summary: z.strictObject({
+        matched_seeds: z.number().int().min(0),
+        traced_nodes: z.number().int().min(0),
+        traced_edges: z.number().int().min(0),
+        terminal_paths: z.number().int().min(0),
+        native_handoffs: z.number().int().min(0),
+        observed_facts: z.number().int().min(0),
+        inferred_facts: z.number().int().min(0),
+        unknown_facts: z.number().int().min(0),
+        unavailable_facts: z.number().int().min(0),
+    }),
+    coverage: z.strictObject({
+        status: z.enum([
+            "complete-within-source",
+            "partial",
+            "truncated",
+            "no-match",
+        ]),
+        source_graph_status: z.enum([
+            "complete",
+            "partial",
+            "unknown",
+            "unavailable",
+        ]),
+        scanned_nodes: z.number().int().min(0),
+        total_seed_matches: z.number().int().min(0),
+        omitted_seed_matches: z.number().int().min(0),
+        omitted_nodes: z.number().int().min(0),
+        omitted_edges: z.number().int().min(0),
+        omitted_paths: z.number().int().min(0),
+        frontier_node_ids: z.array(nodeIdSchema).max(50_000),
+    }),
+    evidence_links: z.array(evidenceIdSchema).min(1).max(65),
+    limitations: z.array(boundedTextSchema).max(1_000),
+});

package/dist/domain/javascriptFeatureTraversal.js

@@ -0,0 +1,100 @@
+import { compareCodePoints, } from "./javascriptApplicationGraph.js";
+/** Traverse a JAG without treating edge inference as observed reachability. */
+export const traverseApplicationFeature = (graph, seedNodeIds, direction, limits) => {
+    const nodeById = new Map(graph.nodes.map((node) => [node.node_id, node]));
+    const adjacency = buildAdjacency(graph.edges, direction);
+    const visited = new Set(seedNodeIds);
+    const retainedEdges = new Map();
+    const omittedNodes = new Set();
+    const omittedEdges = new Set();
+    const frontier = new Set();
+    const depths = new Map(seedNodeIds.map((nodeId) => [nodeId, 0]));
+    const predecessors = new Map();
+    const queue = [...seedNodeIds];
+    for (let offset = 0; offset < queue.length; offset += 1) {
+        const current = queue[offset];
+        if (current === undefined)
+            continue;
+        const depth = depths.get(current) ?? 0;
+        for (const entry of adjacency.get(current) ?? []) {
+            if (depth >= limits.max_depth) {
+                recordOmission({
+                    entry,
+                    current,
+                    omittedNodes,
+                    omittedEdges,
+                    frontier,
+                });
+                continue;
+            }
+            if (!visited.has(entry.nextNodeId) && visited.size >= limits.max_nodes) {
+                recordOmission({
+                    entry,
+                    current,
+                    omittedNodes,
+                    omittedEdges,
+                    frontier,
+                });
+                continue;
+            }
+            if (!retainedEdges.has(entry.edge.edge_id) &&
+                retainedEdges.size >= limits.max_edges) {
+                omittedEdges.add(entry.edge.edge_id);
+                frontier.add(current);
+                frontier.add(entry.nextNodeId);
+                continue;
+            }
+            retainedEdges.set(entry.edge.edge_id, entry.edge);
+            if (visited.has(entry.nextNodeId))
+                continue;
+            if (!nodeById.has(entry.nextNodeId))
+                continue;
+            visited.add(entry.nextNodeId);
+            depths.set(entry.nextNodeId, depth + 1);
+            predecessors.set(entry.nextNodeId, {
+                previousNodeId: current,
+                edgeId: entry.edge.edge_id,
+            });
+            queue.push(entry.nextNodeId);
+        }
+    }
+    return {
+        nodes: [...visited]
+            .map((nodeId) => nodeById.get(nodeId))
+            .filter((node) => node !== undefined)
+            .sort((left, right) => compareCodePoints(left.node_id, right.node_id)),
+        edges: [...retainedEdges.values()].sort((left, right) => compareCodePoints(left.edge_id, right.edge_id)),
+        depths,
+        predecessors,
+        frontierNodeIds: [...frontier].sort(compareCodePoints),
+        omittedNodeCount: omittedNodes.size,
+        omittedEdgeCount: omittedEdges.size,
+    };
+};
+const buildAdjacency = (edges, direction) => {
+    const adjacency = new Map();
+    for (const edge of edges) {
+        if (direction !== "incoming")
+            addAdjacency(adjacency, edge.source_node_id, {
+                edge,
+                nextNodeId: edge.target_node_id,
+            });
+        if (direction !== "outgoing")
+            addAdjacency(adjacency, edge.target_node_id, {
+                edge,
+                nextNodeId: edge.source_node_id,
+            });
+    }
+    for (const entries of adjacency.values())
+        entries.sort((left, right) => compareCodePoints(`${left.edge.edge_id}\0${left.nextNodeId}`, `${right.edge.edge_id}\0${right.nextNodeId}`));
+    return adjacency;
+};
+const addAdjacency = (adjacency, nodeId, entry) => {
+    adjacency.set(nodeId, [...(adjacency.get(nodeId) ?? []), entry]);
+};
+const recordOmission = (context) => {
+    context.omittedNodes.add(context.entry.nextNodeId);
+    context.omittedEdges.add(context.entry.edge.edge_id);
+    context.frontier.add(context.current);
+    context.frontier.add(context.entry.nextNodeId);
+};

package/dist/domain/javascriptNativeHandoff.js

@@ -0,0 +1,85 @@
+import { compareCodePoints, } from "./javascriptApplicationGraph.js";
+/** Build provider-neutral addon targets and link exact-subject native Evidence. */
+export const buildJavaScriptNativeHandoffs = (nodes, edges, nativeEvidence) => {
+    const nodeById = new Map(nodes.map((node) => [node.node_id, node]));
+    return nodes
+        .filter(({ kind }) => kind === "native-addon")
+        .flatMap((node) => {
+        const digest = artifactDigest(node);
+        if (digest === null)
+            return [];
+        const linked = nativeEvidence.filter(({ subject }) => subject?.digest.sha256 === digest);
+        const exportNodes = nativeExportNodes(node, edges, nodeById);
+        return [
+            {
+                native_node_id: node.node_id,
+                artifact_sha256: digest,
+                artifact_path: artifactPath(node),
+                export_node_ids: exportNodes.map(({ node_id: id }) => id),
+                requested_exports: requestedExports(exportNodes),
+                status: linked.length === 0
+                    ? "requires-provider-analysis"
+                    : "evidence-linked",
+                providers: uniqueProviders(linked),
+                evidence_ids: linked
+                    .map(({ evidence_id: id }) => id)
+                    .sort(compareCodePoints),
+                recommended_tools: [
+                    "open_binary",
+                    "binary_overview",
+                    "search_procedures",
+                    "analyze_function",
+                    "xrefs",
+                ],
+            },
+        ];
+    })
+        .sort((left, right) => compareCodePoints(left.native_node_id, right.native_node_id));
+};
+const artifactDigest = (node) => {
+    if (node.identity.strategy === "content-digest")
+        return node.identity.sha256;
+    const observation = node.observations.find(({ evidence }) => evidence.artifact.available);
+    return observation?.evidence.artifact.available === true
+        ? observation.evidence.artifact.sha256
+        : null;
+};
+const artifactPath = (node) => {
+    for (const { evidence } of node.observations)
+        if (evidence.location.available &&
+            evidence.location.value.kind === "artifact-path")
+            return evidence.location.value.path;
+    return null;
+};
+const nativeExportNodes = (addon, edges, nodeById) => {
+    const ids = edges.flatMap((edge) => {
+        if (edge.source_node_id === addon.node_id &&
+            ["contains", "exposes"].includes(edge.relation))
+            return [edge.target_node_id];
+        if (edge.target_node_id === addon.node_id &&
+            ["imports", "loads"].includes(edge.relation))
+            return [edge.source_node_id];
+        return [];
+    });
+    return [...new Set(ids)]
+        .map((id) => nodeById.get(id))
+        .filter((node) => node?.kind === "native-export")
+        .sort((left, right) => compareCodePoints(left.node_id, right.node_id));
+};
+const requestedExports = (nodes) => {
+    const values = nodes.flatMap((node) => node.observations.flatMap((observation) => [
+        ...(observation.label === null ? [] : [observation.label]),
+        ...stringArray(observation.properties.requested_members),
+        ...stringArray(observation.properties.members),
+    ]));
+    return [...new Set(values)].sort(compareCodePoints).slice(0, 1_000);
+};
+const stringArray = (value) => Array.isArray(value)
+    ? value.filter((item) => typeof item === "string")
+    : [];
+const uniqueProviders = (evidence) => [
+    ...new Map(evidence.map(({ provider }) => [
+        `${provider.id}\0${provider.name}\0${provider.version ?? ""}`,
+        provider,
+    ])).values(),
+].sort((left, right) => compareCodePoints(`${left.id}\0${left.name}\0${left.version ?? ""}`, `${right.id}\0${right.name}\0${right.version ?? ""}`));