rea-agents 1.6.0 → 2.0.0

package/dist/domain/javascriptRuntimeLoadState.js

@@ -0,0 +1,106 @@
+import { compareCodePoints, } from "./javascriptApplicationGraph.js";
+import { createStaticRuntimeScope, mappedRuntimePaths, staticNodeWithinRuntimeScope, } from "./javascriptRuntimeStaticCandidates.js";
+/** Classify static code presence without claiming bundled module execution. */
+export const classifyStaticLoadStates = (layers, runtimeEntities, matches, options) => {
+    const states = [];
+    let totalStates = 0;
+    for (const layer of layers) {
+        const projection = classifyLayer(layer, runtimeEntities, matches, {
+            reconciliationComplete: options.reconciliationComplete,
+            maximumStates: Math.max(0, options.maximumStates - states.length),
+        });
+        totalStates += projection.total;
+        states.push(...projection.states);
+    }
+    return { states, omittedStates: totalStates - states.length };
+};
+const classifyLayer = (layer, runtimeEntities, matches, options) => {
+    const nodes = layer.graph.nodes.filter(isLoadStateNode);
+    if (options.maximumStates === 0)
+        return { states: [], total: nodes.length };
+    const direct = new Map();
+    for (const match of matches)
+        if (match.status === "matched" &&
+            match.static_layer_id === layer.layerId &&
+            match.static_node_id !== null)
+            append(direct, match.static_node_id, match.runtime_node_id);
+    const resident = residentNodes(layer, new Set(direct.keys()));
+    const runtimeScope = createStaticRuntimeScope(layer, runtimeEntities);
+    const scopedEntities = runtimeEntities.filter((entity) => mappedRuntimePaths(layer, entity).length > 0);
+    const layerComplete = options.reconciliationComplete &&
+        layer.graph.coverage.status === "complete" &&
+        scopedEntities.length > 0 &&
+        scopedEntities.every(({ capture }) => captureScriptsComplete(capture.evidence.evidence_id, runtimeEntities));
+    const states = nodes.slice(0, options.maximumStates).map((node) => {
+        const runtimeNodeIds = uniqueSorted(direct.get(node.node_id) ?? []);
+        if (runtimeNodeIds.length > 0)
+            return state(layer, node, {
+                status: "loaded",
+                runtimeNodeIds,
+                reason: "runtime-script-correspondence",
+            });
+        if (resident.has(node.node_id))
+            return state(layer, node, {
+                status: "resident-in-loaded-asset",
+                runtimeNodeIds: [],
+                reason: "containing-asset-was-loaded",
+            });
+        const nodeWithinScope = staticNodeWithinRuntimeScope(node, runtimeScope);
+        if (layerComplete && nodeWithinScope)
+            return state(layer, node, {
+                status: "not-observed-in-capture",
+                runtimeNodeIds: [],
+                reason: "not-observed-in-bounded-capture",
+            });
+        return state(layer, node, {
+            status: "unknown",
+            runtimeNodeIds: [],
+            reason: !nodeWithinScope
+                ? "layer-outside-runtime-scope"
+                : "static-or-runtime-coverage-incomplete",
+        });
+    });
+    return { states, total: nodes.length };
+};
+const residentNodes = (layer, directlyLoaded) => {
+    const nodeKinds = new Map(layer.graph.nodes.map(({ node_id: id, kind }) => [id, kind]));
+    const children = new Map();
+    for (const edge of layer.graph.edges)
+        if (edge.relation === "contains")
+            append(children, edge.source_node_id, edge.target_node_id);
+    const pending = [...directlyLoaded].filter((nodeId) => nodeKinds.get(nodeId) === "javascript-asset");
+    const resident = new Set();
+    for (let index = 0; index < pending.length; index += 1) {
+        const current = pending[index];
+        if (current === undefined)
+            break;
+        for (const child of children.get(current) ?? []) {
+            if (resident.has(child))
+                continue;
+            resident.add(child);
+            pending.push(child);
+        }
+    }
+    return resident;
+};
+const append = (values, key, value) => {
+    const current = values.get(key);
+    if (current === undefined)
+        values.set(key, [value]);
+    else
+        current.push(value);
+};
+const captureScriptsComplete = (evidenceId, entities) => entities.find(({ capture }) => capture.evidence.evidence_id === evidenceId)
+    ?.capture.scriptsCompleteWithinScope === true;
+const isLoadStateNode = (node) => node.kind === "javascript-asset" ||
+    node.kind === "javascript-chunk" ||
+    node.kind === "javascript-module";
+const state = (layer, node, input) => ({
+    static_layer_id: layer.layerId,
+    static_node_id: node.node_id,
+    kind: node.kind,
+    status: input.status,
+    runtime_node_ids: [...input.runtimeNodeIds],
+    reason: input.reason,
+});
+const uniqueSorted = (values) => [...new Set(values)].sort(compareCodePoints);

package/dist/domain/javascriptRuntimeReconciliation.js

@@ -0,0 +1,42 @@
+import { classifyStaticLoadStates } from "./javascriptRuntimeLoadState.js";
+import { buildReconciledApplicationGraph } from "./javascriptRuntimeReconciliationGraph.js";
+import { reconcileRuntimeEntities } from "./javascriptRuntimeReconciliationMatching.js";
+import { parseRuntimeCaptures, parseStaticLayers, } from "./javascriptRuntimeReconciliationParsing.js";
+import { createJavaScriptRuntimeReconciliationResult } from "./javascriptRuntimeReconciliationResult.js";
+import { reconcileJavaScriptRuntimeInputSchema } from "./javascriptRuntimeReconciliationSchemas.js";
+import { projectRuntimeCaptures } from "./javascriptRuntimeReconciliationRuntime.js";
+import { collectStaticRuntimeCandidates } from "./javascriptRuntimeStaticCandidates.js";
+/** Reconcile static JAG layers with authorized passive CDP Evidence. */
+export const reconcileJavaScriptRuntime = (input) => {
+    const parsed = reconcileJavaScriptRuntimeInputSchema.parse(input);
+    const layers = parseStaticLayers(parsed.static_layers);
+    const captures = parseRuntimeCaptures(parsed.runtime_observations);
+    const runtime = projectRuntimeCaptures(captures, parsed.limits.max_runtime_entities);
+    const candidates = collectStaticRuntimeCandidates(layers);
+    const matching = reconcileRuntimeEntities({
+        entities: runtime.entities,
+        candidates,
+        layers,
+        maximumItems: parsed.limits.max_reconciliation_items,
+    });
+    const loadStates = classifyStaticLoadStates(layers, runtime.entities, matching.items, {
+        maximumStates: parsed.limits.max_static_load_states,
+        reconciliationComplete: runtime.omittedEntities === 0 && matching.omittedItems === 0,
+    });
+    const graph = buildReconciledApplicationGraph({
+        layers,
+        captures,
+        runtime,
+        reconciliationEdges: matching.edges,
+        omittedReconciliationItems: matching.omittedItems,
+    });
+    return createJavaScriptRuntimeReconciliationResult({
+        layers,
+        captures,
+        runtime,
+        matching,
+        loadStates,
+        graph: graph.graph,
+        omittedGraphItems: graph.omittedGraphItems,
+    });
+};

package/dist/domain/javascriptRuntimeReconciliationGraph.js

@@ -0,0 +1,169 @@
+import { compareCodePoints, createJavaScriptApplicationGraph, createJavaScriptApplicationNode, } from "./javascriptApplicationGraph.js";
+/** Merge source graphs, runtime nodes, and inferred mappings into one valid JAG. */
+export const buildReconciledApplicationGraph = (input) => {
+    const merged = mergeNodes([
+        ...input.layers.flatMap(({ graph }) => graph.nodes),
+        ...input.runtime.nodes,
+    ]);
+    const allEdges = uniqueEdges([
+        ...input.layers.flatMap(({ graph }) => graph.edges),
+        ...input.runtime.edges,
+        ...input.reconciliationEdges,
+    ]);
+    const bounded = boundGraphContent(input, merged.nodes, allEdges);
+    const facts = graphCoverageFacts(input, merged.omittedObservations + bounded.omittedItems);
+    const graph = createJavaScriptApplicationGraph({
+        schema: "JavaScriptApplicationGraph",
+        schema_version: 1,
+        root_node_ids: bounded.rootNodeIds,
+        nodes: bounded.nodes,
+        edges: bounded.edges,
+        coverage: graphCoverage(input, facts, bounded.nodes.length),
+        limitations: uniqueSorted([
+            ...input.layers.flatMap(({ graph }) => graph.limitations),
+            "Runtime presence is bounded to passive capture windows and does not prove feature execution.",
+            "Cross-layer observed_as edges are inferences; digest equality proves byte identity only.",
+            "Source-map relationships retain their original static authority and are not promoted into runtime matches.",
+            ...(facts.inputTruncated
+                ? [
+                    "One or more source graphs or passive captures were incomplete or truncated.",
+                ]
+                : []),
+            ...(facts.outputTruncated
+                ? [
+                    "The reconciled graph omitted entities or classifications at caller limits.",
+                ]
+                : []),
+        ]),
+    });
+    return {
+        graph,
+        omittedGraphItems: merged.omittedObservations + bounded.omittedItems,
+    };
+};
+const boundGraphContent = (input, nodes, edges) => {
+    const allRoots = preferredRootIds(input);
+    const rootNodeIds = allRoots.slice(0, 1_000);
+    const roots = new Set(rootNodeIds);
+    const sortedNodes = [...nodes].sort((left, right) => compareCodePoints(left.node_id, right.node_id));
+    const retainedNodes = [
+        ...sortedNodes.filter(({ node_id: id }) => roots.has(id)),
+        ...sortedNodes.filter(({ node_id: id }) => !roots.has(id)),
+    ].slice(0, 100_000);
+    const retainedIds = new Set(retainedNodes.map(({ node_id: id }) => id));
+    const retainedEdges = [...edges]
+        .sort((left, right) => compareCodePoints(left.edge_id, right.edge_id))
+        .filter(({ source_node_id: source, target_node_id: target }) => retainedIds.has(source) && retainedIds.has(target))
+        .slice(0, 200_000);
+    return {
+        rootNodeIds,
+        nodes: retainedNodes,
+        edges: retainedEdges,
+        omittedItems: allRoots.length -
+            rootNodeIds.length +
+            (nodes.length - retainedNodes.length) +
+            (edges.length - retainedEdges.length),
+    };
+};
+const preferredRootIds = (input) => {
+    const runtime = [...input.runtime.targetNodeByEvidenceId.values()].map(({ node_id: id }) => id);
+    const application = input.layers
+        .filter(({ role }) => role === "application")
+        .flatMap(({ graph }) => graph.root_node_ids);
+    const supplemental = input.layers
+        .filter(({ role }) => role !== "application")
+        .flatMap(({ graph }) => graph.root_node_ids);
+    return [...new Set([...runtime, ...application, ...supplemental])];
+};
+const graphCoverageFacts = (input, omittedNodeObservations) => {
+    const projectionOmissions = input.runtime.omittedEntities +
+        input.omittedReconciliationItems +
+        omittedNodeObservations;
+    const captureTruncated = input.captures.some(({ inspection }) => inspection.completeness.conditions.includes("truncated"));
+    const captureHasUnknownOmissions = input.captures.some(({ inspection }) => inspection.completeness.unavailable_sections.length > 0);
+    const inputTruncated = input.layers.some(({ graph }) => graph.coverage.truncated) ||
+        captureTruncated;
+    const outputTruncated = projectionOmissions > 0;
+    const sourceOmissions = input.layers.reduce((total, { graph }) => total + (graph.coverage.omitted_count ?? 0), 0);
+    const omissionsKnown = !captureTruncated &&
+        !captureHasUnknownOmissions &&
+        input.layers.every(({ graph }) => graph.coverage.omitted_count !== null);
+    return {
+        projectionOmissions,
+        knownOmissions: projectionOmissions + sourceOmissions,
+        omissionsKnown,
+        inputTruncated,
+        outputTruncated,
+        truncated: inputTruncated || outputTruncated,
+        complete: !inputTruncated &&
+            !outputTruncated &&
+            input.layers.every(({ graph }) => graph.coverage.status === "complete") &&
+            input.captures.every(({ inspection }) => inspection.completeness.status === "complete_within_window"),
+    };
+};
+const graphCoverage = (input, facts, nodeCount) => facts.complete
+    ? { status: "complete", truncated: false, omitted_count: 0, limits: [] }
+    : facts.truncated
+        ? {
+            status: "partial",
+            truncated: true,
+            omitted_count: facts.omissionsKnown ? facts.knownOmissions : null,
+            limits: [
+                ...(facts.inputTruncated
+                    ? [
+                        {
+                            name: "runtime-reconciliation-input-coverage",
+                            value: input.layers.length + input.captures.length,
+                            unit: "items",
+                        },
+                    ]
+                    : []),
+                ...(facts.outputTruncated
+                    ? [
+                        {
+                            name: "runtime-reconciliation-output-limits",
+                            value: nodeCount,
+                            unit: "items",
+                        },
+                    ]
+                    : []),
+            ],
+        }
+        : {
+            status: "partial",
+            truncated: false,
+            omitted_count: facts.omissionsKnown ? facts.knownOmissions : null,
+            limits: [],
+        };
+const mergeNodes = (nodes) => {
+    const grouped = new Map();
+    for (const node of nodes)
+        grouped.set(node.node_id, [...(grouped.get(node.node_id) ?? []), node]);
+    let omittedObservations = 0;
+    const merged = [...grouped.values()].map((group) => {
+        const first = group[0];
+        if (first === undefined)
+            throw new TypeError("Empty JAG node group");
+        if (group.some(({ kind, identity }) => kind !== first.kind ||
+            JSON.stringify(identity) !== JSON.stringify(first.identity)))
+            throw new TypeError("Colliding JAG node identifiers disagree");
+        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, omittedObservations };
+};
+const uniqueEdges = (edges) => [
+    ...new Map(edges.map((edge) => [edge.edge_id, edge])).values(),
+];
+const uniqueSorted = (values) => [...new Set(values)].sort(compareCodePoints);

package/dist/domain/javascriptRuntimeReconciliationMatching.js

@@ -0,0 +1,247 @@
+import { compareCodePoints, createJavaScriptApplicationEdge, } from "./javascriptApplicationGraph.js";
+import { digestCanonical, } from "./javascriptRuntimeReconciliationParsing.js";
+import { mappedRuntimePaths, } from "./javascriptRuntimeStaticCandidates.js";
+/** Match runtime entities conservatively and emit only inferred observed_as edges. */
+export const reconcileRuntimeEntities = (input) => {
+    const index = indexCandidates(input.candidates);
+    const evaluated = input.entities.map((entity) => reconcileEntity(entity, index, input.layers));
+    const retained = evaluated
+        .sort((left, right) => compareCodePoints(left.item.reconciliation_id, right.item.reconciliation_id))
+        .slice(0, input.maximumItems);
+    return {
+        items: retained.map(({ item }) => item),
+        edges: retained.flatMap(({ edge }) => (edge === null ? [] : [edge])),
+        omittedItems: evaluated.length - retained.length,
+    };
+};
+const reconcileEntity = (entity, index, layers) => {
+    const locations = candidatesWithLocation(entity, index, layers);
+    if (entity.sourceSha256 !== null) {
+        const content = index.byCategoryDigest.get(categoryDigestKey(entity.staticKind, entity.sourceSha256)) ?? [];
+        const locatedKeys = new Set(locations.map(({ candidate }) => candidateKey(candidate)));
+        const combined = content.filter((candidate) => locatedKeys.has(candidateKey(candidate)));
+        if (combined.length === 1)
+            return matched(entity, combined[0], {
+                basis: "content-and-location",
+                confidence: "high",
+                reason: "content-and-location-match",
+            });
+        if (content.length === 1) {
+            const candidate = content[0];
+            const digestBasis = candidate.digests.find(({ sha256 }) => sha256 === entity.sourceSha256)?.basis;
+            return matched(entity, candidate, {
+                basis: digestBasis ?? "content-sha256",
+                confidence: "high",
+                reason: "unique-content-match",
+            });
+        }
+        if (content.length > 1)
+            return unresolved(entity, {
+                status: "ambiguous",
+                basis: "none",
+                confidence: "unknown",
+                reason: "ambiguous-static-candidates",
+                candidates: content,
+            });
+        if (locations.length > 0)
+            return unresolved(entity, {
+                status: "unmatched",
+                basis: strongestLocationBasis(locations),
+                confidence: "high",
+                reason: "captured-content-disagrees-with-static-location",
+                candidates: locations.map(({ candidate }) => candidate),
+            });
+        return unresolved(entity, {
+            status: "unmatched",
+            basis: "none",
+            confidence: "high",
+            reason: "no-static-content-match",
+            candidates: [],
+        });
+    }
+    if (locations.length === 1) {
+        const located = locations[0];
+        return matched(entity, located.candidate, {
+            basis: located.mapping.basis,
+            confidence: "medium",
+            reason: "unique-location-match",
+        });
+    }
+    if (locations.length > 1)
+        return unresolved(entity, {
+            status: "ambiguous",
+            basis: strongestLocationBasis(locations),
+            confidence: "unknown",
+            reason: "ambiguous-static-candidates",
+            candidates: locations.map(({ candidate }) => candidate),
+        });
+    const mapped = layers.some((layer) => mappedRuntimePaths(layer, entity).length > 0);
+    return unresolved(entity, {
+        status: mapped ? "unmatched" : "unknown",
+        basis: "none",
+        confidence: "unknown",
+        reason: mapped
+            ? "no-static-content-match"
+            : "no-authorized-location-mapping",
+        candidates: [],
+    });
+};
+const candidatesWithLocation = (entity, index, layers) => {
+    const located = new Map();
+    for (const layer of layers)
+        for (const mapping of mappedRuntimePaths(layer, entity))
+            for (const candidate of index.byLayerCategoryPath.get(layerCategoryPathKey(layer.layerId, entity.staticKind, mapping.path)) ?? []) {
+                const key = candidateKey(candidate);
+                if (!located.has(key))
+                    located.set(key, { candidate, mapping });
+            }
+    return [...located.values()].sort((left, right) => compareCodePoints(candidateKey(left.candidate), candidateKey(right.candidate)));
+};
+const indexCandidates = (candidates) => {
+    const byCategoryDigest = new Map();
+    const byLayerCategoryPath = new Map();
+    for (const candidate of candidates) {
+        for (const { sha256 } of candidate.digests)
+            appendIndex(byCategoryDigest, categoryDigestKey(candidate.category, sha256), candidate);
+        for (const path of candidate.paths)
+            appendIndex(byLayerCategoryPath, layerCategoryPathKey(candidate.layer.layerId, candidate.category, path), candidate);
+    }
+    return { byCategoryDigest, byLayerCategoryPath };
+};
+const appendIndex = (index, key, candidate) => {
+    const values = index.get(key);
+    if (values === undefined)
+        index.set(key, [candidate]);
+    else
+        values.push(candidate);
+};
+const categoryDigestKey = (category, digest) => `${category}\0${digest}`;
+const layerCategoryPathKey = (layerId, category, path) => `${layerId}\0${category}\0${path}`;
+const matched = (entity, candidate, input) => {
+    const item = createItem(entity, {
+        layer: candidate.layer,
+        staticNodeId: candidate.node.node_id,
+        status: "matched",
+        basis: input.basis,
+        confidence: input.confidence,
+        reason: input.reason,
+        candidates: [candidate],
+    });
+    return {
+        item,
+        edge: createJavaScriptApplicationEdge({
+            source_node_id: candidate.node.node_id,
+            target_node_id: entity.node.node_id,
+            relation: "observed_as",
+            properties: {
+                reconciliation_id: item.reconciliation_id,
+                basis: input.basis,
+                static_layer_id: candidate.layer.layerId,
+            },
+            evidence: reconciliationEvidence(entity, candidate.layer, input.basis, input.confidence),
+        }),
+    };
+};
+const unresolved = (entity, input) => ({
+    item: createItem(entity, {
+        layer: null,
+        staticNodeId: null,
+        status: input.status,
+        basis: input.basis,
+        confidence: input.confidence,
+        reason: input.reason,
+        candidates: input.candidates,
+    }),
+    edge: null,
+});
+const createItem = (entity, input) => {
+    const candidateReferences = uniqueCandidateReferences(input.candidates);
+    const semantic = {
+        entity_kind: entity.kind,
+        runtime_evidence_id: entity.capture.evidence.evidence_id,
+        runtime_node_id: entity.node.node_id,
+        static_layer_id: input.layer?.layerId ?? null,
+        static_node_id: input.staticNodeId,
+        status: input.status,
+        basis: input.basis,
+        confidence: input.confidence,
+        reason: input.reason,
+        candidate_static_count: candidateReferences.count,
+        candidate_static_nodes: candidateReferences.items,
+    };
+    return {
+        reconciliation_id: `jrr_item_${digestCanonical(semantic)}`,
+        ...semantic,
+    };
+};
+const reconciliationEvidence = (entity, layer, basis, confidence) => ({
+    authority: "cross-layer-reconciliation",
+    state: "inferred",
+    confidence: confidence === "medium" ? "medium" : "high",
+    artifact: entity.sourceSha256 === null
+        ? {
+            available: false,
+            reason: "not-observed",
+            detail: "Runtime source bytes were not captured for this mapping.",
+        }
+        : {
+            available: true,
+            artifact_id: `art_${entity.sourceSha256}`,
+            sha256: entity.sourceSha256,
+        },
+    location: entity.node.observations[0].evidence.location,
+    extractor: {
+        name: "rea-javascript-runtime-reconciliation",
+        version: "1",
+        operation: "reconcile_javascript_runtime",
+        executable_sha256: null,
+    },
+    coverage: layer.graph.coverage.status === "complete" &&
+        entity.capture.scriptsCompleteWithinScope
+        ? { status: "complete", truncated: false, omitted_count: 0, limits: [] }
+        : {
+            status: "partial",
+            truncated: false,
+            omitted_count: null,
+            limits: [],
+        },
+    limitations: [
+        basis === "content-sha256" ||
+            basis === "module-source-sha256" ||
+            basis === "content-and-location"
+            ? "Equal content digests establish byte identity, not execution causality."
+            : "Location correspondence is inferred from an artifact root or caller-declared mapping.",
+        "Passive script parsing or target presence does not prove feature execution.",
+    ],
+    evidence_ids: [
+        layer.evidence.evidence_id,
+        entity.capture.evidence.evidence_id,
+    ].sort(),
+});
+const strongestLocationBasis = (values) => {
+    const bases = new Set(values.map(({ mapping }) => mapping.basis));
+    if (bases.has("artifact-path"))
+        return "artifact-path";
+    if (bases.has("operator-file-mapping"))
+        return "operator-file-mapping";
+    return "operator-url-mapping";
+};
+const candidateKey = (candidate) => `${candidate.layer.layerId}:${candidate.node.node_id}`;
+const uniqueCandidateReferences = (candidates) => {
+    const seen = new Set();
+    let count = 0;
+    const items = [];
+    for (const { layer, node } of candidates) {
+        const key = `${layer.layerId}:${node.node_id}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        count += 1;
+        if (items.length < 1_000)
+            items.push({
+                static_layer_id: layer.layerId,
+                static_node_id: node.node_id,
+            });
+    }
+    return { count, items };
+};