rea-agents 1.7.0 → 2.1.0

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 };
+};

package/dist/domain/javascriptRuntimeReconciliationParsing.js

@@ -0,0 +1,160 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { z } from "zod";
+import { browserAllowedOriginsSchema, browserEndpointSchema, webPageInspectionSchema, } from "./browserObservation.js";
+import { electronFileRootsSchema, electronPageInspectionSchema, } from "./electronObservation.js";
+import { parseEvidence } from "./evidence.js";
+import { javascriptApplicationAnalysisResultSchema, } from "./javascriptApplicationAnalysis.js";
+import { compareCodePoints, } from "./javascriptApplicationGraph.js";
+/** Parse and semantically bind every static analysis Evidence layer. */
+export const parseStaticLayers = (layers) => layers
+    .map((layer) => parseStaticLayer(layer))
+    .sort((left, right) => compareCodePoints(left.layerId, right.layerId));
+/** Parse only supported passive web/Electron inspection Evidence. */
+export const parseRuntimeCaptures = (observations) => observations
+    .map((observation) => parseRuntimeCapture(observation))
+    .sort((left, right) => compareCodePoints(left.evidence.evidence_id, right.evidence.evidence_id));
+export const digestCanonical = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError("Runtime reconciliation could not canonicalize input");
+    return createHash("sha256").update(encoded).digest("hex");
+};
+const parseStaticLayer = (layer) => {
+    const evidence = parseEvidence(layer.analysis);
+    assertEvidenceIdentity(evidence, {
+        operation: "analyze_javascript_application",
+        predicate: "rea.javascript-application-analysis/v1",
+        providerId: "rea-javascript-application",
+        providerName: "REA JavaScript application analyzer",
+        providerVersion: "1",
+        authority: "shipped-artifact",
+        confidence: "derived",
+    });
+    const result = javascriptApplicationAnalysisResultSchema.parse(evidence.normalized_result);
+    if (evidence.subject === null ||
+        evidence.subject.digest.sha256 !== result.root_artifact_sha256 ||
+        evidence.subject.format !== result.format ||
+        evidence.subject.local_path !== result.input_path)
+        throw new TypeError("JavaScript application Evidence subject disagrees with its result");
+    const parameters = z
+        .object({
+        approved: z.literal(true),
+        source_map_read_approved: z.boolean(),
+    })
+        .passthrough()
+        .parse(evidence.parameters);
+    return {
+        layerId: `jrl_${digestCanonical({
+            role: layer.role,
+            evidence_id: evidence.evidence_id,
+            runtime_mappings: layer.runtime_mappings,
+        })}`,
+        role: layer.role,
+        evidence,
+        result,
+        graph: result.graph,
+        runtimeMappings: layer.runtime_mappings,
+        sourceMapReadApproved: parameters.source_map_read_approved,
+    };
+};
+const parseRuntimeCapture = (input) => {
+    const evidence = parseEvidence(input);
+    if (evidence.operation === "inspect_web_page") {
+        assertEvidenceIdentity(evidence, {
+            operation: "inspect_web_page",
+            predicate: "rea.web-page-inspection/v2",
+            providerId: "rea-cdp-browser",
+            providerName: "REA Chrome DevTools Protocol observation provider",
+            providerVersion: "2",
+            authority: "external-service",
+            confidence: "observed",
+        });
+        const inspection = webPageInspectionSchema.parse(evidence.normalized_result);
+        assertRuntimeParameters(evidence, {
+            kind: "browser",
+            targetId: inspection.target.target_id,
+            targetOrigin: inspection.target.origin,
+            sourceIncluded: inspection.scripts.items.some(({ source }) => source.included),
+        });
+        return {
+            kind: "browser",
+            evidence,
+            inspection,
+            captureSha256: digestCanonical(inspection),
+            scriptsCompleteWithinScope: scriptsComplete(inspection.completeness),
+        };
+    }
+    if (evidence.operation === "inspect_electron_page") {
+        assertEvidenceIdentity(evidence, {
+            operation: "inspect_electron_page",
+            predicate: "rea.electron-page-inspection/v1",
+            providerId: "rea-cdp-electron",
+            providerName: "REA Electron file-page CDP observation provider",
+            providerVersion: "1",
+            authority: "external-service",
+            confidence: "observed",
+        });
+        const inspection = electronPageInspectionSchema.parse(evidence.normalized_result);
+        assertRuntimeParameters(evidence, {
+            kind: "electron",
+            targetId: inspection.target.target_id,
+            sourceIncluded: inspection.scripts.items.some(({ source }) => source.included),
+        });
+        return {
+            kind: "electron",
+            evidence,
+            inspection,
+            captureSha256: digestCanonical(inspection),
+            scriptsCompleteWithinScope: scriptsComplete(inspection.completeness),
+        };
+    }
+    throw new TypeError("Runtime reconciliation requires inspect_web_page or inspect_electron_page Evidence");
+};
+const assertRuntimeParameters = (evidence, expected) => {
+    const common = {
+        target_id: z.string().trim().min(1).max(256),
+        cdp_endpoint: browserEndpointSchema,
+        include_script_sources: z.boolean(),
+    };
+    if (expected.kind === "browser") {
+        const parameters = z
+            .object({ ...common, allowed_origins: browserAllowedOriginsSchema })
+            .passthrough()
+            .parse(evidence.parameters);
+        if (parameters.target_id !== expected.targetId)
+            throw new TypeError("Runtime Evidence target disagrees with its captured result");
+        if (!parameters.allowed_origins.includes(expected.targetOrigin))
+            throw new TypeError("Browser Evidence target is outside its recorded origin scope");
+        if (expected.sourceIncluded && !parameters.include_script_sources)
+            throw new TypeError("Runtime Evidence contains source without source-capture approval");
+        return;
+    }
+    const parameters = z
+        .object({
+        ...common,
+        allowed_file_roots: electronFileRootsSchema,
+        source_capture_approved: z.boolean(),
+    })
+        .passthrough()
+        .parse(evidence.parameters);
+    if (parameters.target_id !== expected.targetId)
+        throw new TypeError("Runtime Evidence target disagrees with its captured result");
+    if (expected.sourceIncluded &&
+        (!parameters.include_script_sources ||
+            parameters.source_capture_approved !== true))
+        throw new TypeError("Runtime Evidence contains source without source-capture approval");
+};
+const scriptsComplete = (completeness) => !completeness.truncated_sections.includes("scripts") &&
+    !completeness.unavailable_sections.includes("scripts") &&
+    completeness.dropped_events.scripts === 0;
+const assertEvidenceIdentity = (evidence, expected) => {
+    if (evidence.operation !== expected.operation ||
+        evidence.predicate_type !== expected.predicate ||
+        evidence.provider.id !== expected.providerId ||
+        evidence.provider.name !== expected.providerName ||
+        evidence.provider.version !== expected.providerVersion ||
+        evidence.authority !== expected.authority ||
+        evidence.confidence !== expected.confidence)
+        throw new TypeError(`Evidence does not match the supported ${expected.operation} contract`);
+};

package/dist/domain/javascriptRuntimeReconciliationResult.js

@@ -0,0 +1,119 @@
+import { compareCodePoints, } from "./javascriptApplicationGraph.js";
+import { digestCanonical, } from "./javascriptRuntimeReconciliationParsing.js";
+import { javascriptRuntimeReconciliationResultSchema, } from "./javascriptRuntimeReconciliationSchemas.js";
+/** Build and verify the deterministic caller-visible reconciliation result. */
+export const createJavaScriptRuntimeReconciliationResult = (input) => {
+    const completion = completionFlags(input);
+    const semantic = {
+        schema_version: 1,
+        static_layers: staticLayerSummaries(input.layers),
+        runtime_captures: captureSummaries(input.captures, input.runtime),
+        graph: input.graph,
+        summary: reconciliationSummary(input),
+        reconciliations: input.matching.items,
+        static_load_states: input.loadStates.states,
+        source_map_authority: sourceMapAuthority(input),
+        coverage: reconciliationCoverage(input, completion),
+        evidence_links: uniqueSorted([
+            ...input.layers.map(({ evidence }) => evidence.evidence_id),
+            ...input.captures.map(({ evidence }) => evidence.evidence_id),
+        ]),
+        limitations: reconciliationLimitations(completion),
+    };
+    return javascriptRuntimeReconciliationResultSchema.parse({
+        reconciliation_id: `jrr_${digestCanonical(semantic)}`,
+        ...semantic,
+    });
+};
+const staticLayerSummaries = (layers) => layers.map((layer) => ({
+    layer_id: layer.layerId,
+    role: layer.role,
+    evidence_id: layer.evidence.evidence_id,
+    graph_id: layer.graph.graph_id,
+    root_artifact_sha256: layer.result.root_artifact_sha256,
+    input_path: layer.result.input_path,
+    format: layer.result.format,
+    runtime_mappings: [...layer.runtimeMappings],
+}));
+const captureSummaries = (captures, runtime) => captures.map((capture) => {
+    const targetNode = runtime.targetNodeByEvidenceId.get(capture.evidence.evidence_id);
+    if (targetNode === undefined)
+        throw new TypeError("Runtime projection omitted a required target node");
+    return {
+        evidence_id: capture.evidence.evidence_id,
+        capture_sha256: capture.captureSha256,
+        kind: capture.kind,
+        target_node_id: targetNode.node_id,
+        target_key: capture.inspection.target.target_id,
+        target_location: capture.kind === "browser"
+            ? capture.inspection.target.url.slice(0, 4_096)
+            : capture.inspection.target.file_path.slice(0, 4_096),
+        frames: capture.inspection.frames.length,
+        scripts: capture.inspection.scripts.items.length,
+        workers: capture.inspection.workers.length,
+        scripts_complete_within_scope: capture.scriptsCompleteWithinScope,
+    };
+});
+const reconciliationSummary = (input) => ({
+    runtime_targets: countBy(input.runtime.entities, "kind", "target"),
+    runtime_frames: countBy(input.runtime.entities, "kind", "frame"),
+    runtime_scripts: countBy(input.runtime.entities, "kind", "script"),
+    runtime_workers: countBy(input.runtime.entities, "kind", "worker"),
+    matched: countBy(input.matching.items, "status", "matched"),
+    ambiguous: countBy(input.matching.items, "status", "ambiguous"),
+    unmatched: countBy(input.matching.items, "status", "unmatched"),
+    unknown: countBy(input.matching.items, "status", "unknown"),
+    static_loaded: countBy(input.loadStates.states, "status", "loaded"),
+    static_resident: countBy(input.loadStates.states, "status", "resident-in-loaded-asset"),
+    static_not_observed: countBy(input.loadStates.states, "status", "not-observed-in-capture"),
+    static_unknown: countBy(input.loadStates.states, "status", "unknown"),
+});
+const sourceMapAuthority = (input) => ({
+    used_for_primary_matching: false,
+    static_layers_with_read_approval: input.layers.filter(({ sourceMapReadApproved }) => sourceMapReadApproved).length,
+    runtime_script_declarations: input.captures.reduce((total, capture) => total +
+        (capture.kind === "browser"
+            ? capture.inspection.scripts.items.filter(({ source_map_url: url }) => url !== null).length
+            : 0), 0),
+    limitation: "Source-map declarations and approved original-source reads retain separate static authority and are not used as primary runtime byte matches.",
+});
+const reconciliationCoverage = (input, completion) => ({
+    status: completion.outputTruncated || completion.inputTruncated
+        ? "truncated"
+        : completion.inputPartial
+            ? "partial"
+            : "complete-within-inputs",
+    truncated: completion.outputTruncated || completion.inputTruncated,
+    omitted_runtime_entities: input.runtime.omittedEntities,
+    omitted_reconciliation_items: input.matching.omittedItems,
+    omitted_static_load_states: input.loadStates.omittedStates,
+    omitted_graph_items: input.omittedGraphItems,
+});
+const completionFlags = (input) => ({
+    outputTruncated: input.runtime.omittedEntities > 0 ||
+        input.matching.omittedItems > 0 ||
+        input.loadStates.omittedStates > 0 ||
+        input.omittedGraphItems > 0,
+    inputTruncated: input.layers.some(({ graph }) => graph.coverage.truncated) ||
+        input.captures.some(({ inspection }) => inspection.completeness.conditions.includes("truncated")),
+    inputPartial: input.layers.some(({ graph }) => graph.coverage.status !== "complete") ||
+        input.captures.some(({ inspection }) => inspection.completeness.status !== "complete_within_window"),
+});
+const reconciliationLimitations = (completion) => uniqueSorted([
+    "Only caller-supplied, semantically verified Evidence records were reconciled.",
+    "Digest equality establishes byte identity but not code reachability, module initialization, or feature execution.",
+    "A static module resident in an observed bundle is not reported as executed.",
+    "Not-observed means absent from the bounded captures in scope, never globally unloaded.",
+    "Caller-declared file and URL mappings are inference inputs and do not expand CDP origin or filesystem-root authority.",
+    "Source-map authority remains separate from passive runtime authority.",
+    ...(completion.inputPartial
+        ? ["One or more static graphs or passive captures were incomplete."]
+        : []),
+    ...(completion.outputTruncated
+        ? [
+            "Caller limits omitted runtime entities or reconciliation classifications.",
+        ]
+        : []),
+]);
+const countBy = (items, key, value) => items.filter((item) => item[key] === value).length;
+const uniqueSorted = (values) => [...new Set(values)].sort(compareCodePoints);