rea-agents 1.6.0 → 2.0.0

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

package/dist/domain/javascriptRuntimeReconciliationRuntime.js

@@ -0,0 +1,316 @@
+import { createJavaScriptApplicationEdge, createJavaScriptApplicationNode, } from "./javascriptApplicationGraph.js";
+/** Project authorized passive capture metadata into capture-scoped JAG nodes. */
+export const projectRuntimeCaptures = (captures, maximumEntities) => {
+    if (maximumEntities < captures.length)
+        throw new TypeError("Runtime entity limit must admit one target for every capture");
+    const all = captures.flatMap(projectCapture);
+    const targets = all.filter(({ kind }) => kind === "target");
+    const nonTargets = all.filter(({ kind }) => kind !== "target");
+    const retained = [...targets, ...nonTargets].slice(0, maximumEntities);
+    const retainedIds = new Set(retained.map(({ node }) => node.node_id));
+    const nodes = retained.map(({ node }) => node);
+    const edges = captures
+        .flatMap((capture) => runtimeEdges(capture, all))
+        .filter(({ source_node_id: source, target_node_id: target }) => retainedIds.has(source) && retainedIds.has(target));
+    const targetNodeByEvidenceId = new Map(retained
+        .filter(({ kind }) => kind === "target")
+        .map(({ capture, node }) => [capture.evidence.evidence_id, node]));
+    return {
+        entities: retained,
+        nodes,
+        edges,
+        targetNodeByEvidenceId,
+        omittedEntities: all.length - retained.length,
+    };
+};
+const projectCapture = (capture) => {
+    const target = targetEntity(capture);
+    return [
+        target,
+        ...frameEntities(capture),
+        ...scriptEntities(capture),
+        ...workerEntities(capture),
+    ];
+};
+const targetEntity = (capture) => {
+    const target = capture.inspection.target;
+    const location = "url" in target
+        ? { kind: "url", value: target.url }
+        : { kind: "file", value: target.file_path };
+    return runtimeEntity(capture, {
+        kind: "target",
+        nodeKind: "target",
+        runtimeKey: target.target_id,
+        targetKey: target.target_id,
+        frameKey: null,
+        scriptKey: null,
+        location,
+        staticKind: "renderer",
+        sourceSha256: null,
+        label: target.title,
+        properties: {
+            runtime_type: target.type,
+            location: location.value.slice(0, 4_096),
+            attached: target.attached,
+        },
+        section: "target",
+    });
+};
+const frameEntities = (capture) => capture.inspection.frames.map((frame) => {
+    const location = "url" in frame
+        ? { kind: "url", value: frame.url }
+        : { kind: "file", value: frame.file_path };
+    return runtimeEntity(capture, {
+        kind: "frame",
+        nodeKind: "frame",
+        runtimeKey: frame.frame_id,
+        targetKey: capture.inspection.target.target_id,
+        frameKey: frame.frame_id,
+        scriptKey: null,
+        location,
+        staticKind: "renderer",
+        sourceSha256: null,
+        label: location.value,
+        properties: {
+            parent_frame_id: frame.parent_frame_id,
+            location: location.value.slice(0, 4_096),
+        },
+        section: "frames",
+    });
+});
+const scriptEntities = (capture) => capture.inspection.scripts.items.map((script) => {
+    const location = "url" in script
+        ? { kind: "url", value: script.url }
+        : { kind: "file", value: script.file_path };
+    return runtimeEntity(capture, {
+        kind: "script",
+        nodeKind: "runtime-script-instance",
+        runtimeKey: script.script_key,
+        targetKey: capture.inspection.target.target_id,
+        frameKey: script.frame_id,
+        scriptKey: script.script_key,
+        location,
+        staticKind: "javascript",
+        sourceSha256: script.source.included
+            ? script.source.artifact.sha256
+            : null,
+        label: location.value,
+        properties: {
+            location: location.value.slice(0, 4_096),
+            cdp_hash: script.cdp_hash,
+            length: script.length,
+            is_module: script.is_module,
+            language: script.language,
+            source_sha256: script.source.included
+                ? script.source.artifact.sha256
+                : null,
+            ...("source_map_url" in script
+                ? { source_map_url: script.source_map_url }
+                : {}),
+        },
+        section: "scripts",
+        ...(script.source.included
+            ? { artifactSha256: script.source.artifact.sha256 }
+            : {}),
+    });
+});
+const workerEntities = (capture) => capture.inspection.workers.map((worker) => {
+    const location = "url" in worker
+        ? { kind: "url", value: worker.url }
+        : { kind: "file", value: worker.file_path };
+    const serviceWorker = worker.type.includes("service");
+    return runtimeEntity(capture, {
+        kind: "worker",
+        nodeKind: serviceWorker ? "service-worker" : "worker",
+        runtimeKey: worker.target_id,
+        targetKey: worker.target_id,
+        frameKey: worker.parent_frame_id,
+        scriptKey: null,
+        location,
+        staticKind: serviceWorker ? "service-worker" : "worker",
+        sourceSha256: null,
+        label: location.value,
+        properties: {
+            runtime_type: worker.type,
+            location: location.value.slice(0, 4_096),
+            attached: worker.attached,
+            opener_target_id: worker.opener_target_id,
+            parent_frame_id: worker.parent_frame_id,
+        },
+        section: "workers",
+    });
+});
+const runtimeEntity = (capture, input) => ({
+    kind: input.kind,
+    section: input.section,
+    capture,
+    runtimeKey: input.runtimeKey,
+    location: input.location,
+    frameKey: input.frameKey,
+    sourceSha256: input.sourceSha256,
+    staticKind: input.staticKind,
+    node: createJavaScriptApplicationNode({
+        kind: input.nodeKind,
+        identity: {
+            strategy: "runtime-instance",
+            stability: "capture-only",
+            capture_sha256: capture.captureSha256,
+            runtime_key: input.runtimeKey,
+        },
+        observations: [
+            {
+                label: input.label.slice(0, 1_024) || null,
+                properties: input.properties,
+                evidence: runtimeEvidence(capture, input),
+            },
+        ],
+    }),
+});
+const runtimeEvidence = (capture, input) => ({
+    authority: "passive-cdp-runtime",
+    state: "observed",
+    confidence: "exact",
+    artifact: input.artifactSha256 === undefined
+        ? {
+            available: false,
+            reason: input.section === "scripts" ? "not-observed" : "not-applicable",
+            detail: input.section === "scripts"
+                ? "Script source bytes were not included in this passive capture."
+                : "This runtime entity has no standalone artifact bytes.",
+        }
+        : {
+            available: true,
+            artifact_id: `art_${input.artifactSha256}`,
+            sha256: input.artifactSha256,
+        },
+    location: {
+        available: true,
+        value: {
+            kind: "runtime",
+            capture_sha256: capture.captureSha256,
+            target_key: input.targetKey,
+            frame_key: input.frameKey,
+            script_key: input.scriptKey,
+        },
+    },
+    extractor: {
+        name: capture.evidence.provider.id,
+        version: capture.evidence.provider.version ??
+            (capture.kind === "browser" ? "2" : "1"),
+        operation: capture.kind === "browser" ? "inspect_web_page" : "inspect_electron_page",
+        executable_sha256: null,
+    },
+    coverage: runtimeSectionCoverage(capture, input.section),
+    limitations: [
+        "The entity was observed only within one bounded passive CDP capture.",
+        ...(runtimeSectionComplete(capture, input.section)
+            ? []
+            : [
+                `The runtime ${input.section} inventory was incomplete within this capture.`,
+            ]),
+    ],
+    evidence_ids: [capture.evidence.evidence_id],
+});
+const runtimeEdges = (capture, entities) => {
+    const local = entities.filter(({ capture: candidate }) => candidate.evidence.evidence_id === capture.evidence.evidence_id);
+    const target = local.find(({ kind }) => kind === "target");
+    if (target === undefined)
+        return [];
+    const frames = new Map(local
+        .filter(({ kind }) => kind === "frame")
+        .map((entity) => [entity.runtimeKey, entity]));
+    return local.flatMap((entity) => {
+        if (entity === target)
+            return [];
+        const parent = (entity.kind === "script" || entity.kind === "worker") &&
+            entity.frameKey !== null
+            ? (frames.get(entity.frameKey) ?? target)
+            : target;
+        return [
+            createJavaScriptApplicationEdge({
+                source_node_id: parent.node.node_id,
+                target_node_id: entity.node.node_id,
+                relation: entity.kind === "script" ? "loads" : "contains",
+                properties: { basis: "passive-cdp-observation" },
+                evidence: runtimeRelationshipEvidence(capture, entity),
+            }),
+        ];
+    });
+};
+const runtimeRelationshipEvidence = (capture, entity) => ({
+    authority: "passive-cdp-runtime",
+    state: "observed",
+    confidence: "exact",
+    artifact: {
+        available: false,
+        reason: "not-applicable",
+        detail: "The relationship is runtime metadata, not standalone bytes.",
+    },
+    location: {
+        available: true,
+        value: {
+            kind: "runtime",
+            capture_sha256: capture.captureSha256,
+            target_key: capture.inspection.target.target_id,
+            frame_key: entity.frameKey,
+            script_key: entity.kind === "script" ? entity.runtimeKey : null,
+        },
+    },
+    extractor: {
+        name: capture.evidence.provider.id,
+        version: capture.evidence.provider.version ??
+            (capture.kind === "browser" ? "2" : "1"),
+        operation: capture.kind === "browser" ? "inspect_web_page" : "inspect_electron_page",
+        executable_sha256: null,
+    },
+    coverage: runtimeSectionCoverage(capture, entity.section),
+    limitations: [
+        "The relationship was observed only within one bounded passive CDP capture.",
+    ],
+    evidence_ids: [capture.evidence.evidence_id],
+});
+const runtimeSectionComplete = (capture, section) => {
+    if (section === "target")
+        return true;
+    if (section === "scripts")
+        return capture.scriptsCompleteWithinScope;
+    return (!capture.inspection.completeness.truncated_sections.includes(section) &&
+        !capture.inspection.completeness.unavailable_sections.includes(section));
+};
+const runtimeSectionCoverage = (capture, section) => {
+    if (runtimeSectionComplete(capture, section))
+        return {
+            status: "complete",
+            truncated: false,
+            omitted_count: 0,
+            limits: [],
+        };
+    const truncated = section !== "target" &&
+        capture.inspection.completeness.truncated_sections.includes(section);
+    return {
+        status: "partial",
+        truncated,
+        omitted_count: null,
+        limits: truncated
+            ? [
+                {
+                    name: `passive-cdp-${section}-limit`,
+                    value: runtimeSectionCount(capture, section),
+                    unit: "items",
+                },
+            ]
+            : [],
+    };
+};
+const runtimeSectionCount = (capture, section) => {
+    switch (section) {
+        case "target":
+            return 1;
+        case "frames":
+            return capture.inspection.frames.length;
+        case "scripts":
+            return capture.inspection.scripts.items.length;
+        case "workers":
+            return capture.inspection.workers.length;
+    }
+};