rea-agents 2.1.0 → 2.3.0

package/dist/application/JavaScriptArtifactReconstruction.js

@@ -9,6 +9,7 @@ import { buildJavaScriptArtifactGraph } from "./JavaScriptArtifactGraphBuilder.j
 import { artifactLimitsForReconstruction, javascriptArtifactReconstructionInputSchema, } from "./JavaScriptArtifactReconstructionInput.js";
 import { scanCanonicalArtifactInventory } from "./ArtifactInventory.js";
 import { summarizeElectronBoundaries } from "./ElectronBoundaryAnalysis.js";
+import { buildJavaScriptSemanticGraph } from "./JavaScriptSemanticGraphBuilder.js";
 /** Reconstruct one local ASAR or extracted directory without executing code. */
 export const reconstructJavaScriptArtifact = async (rawInput, signal) => {
     const input = javascriptArtifactReconstructionInputSchema.parse(rawInput);
@@ -24,6 +25,11 @@ export const reconstructJavaScriptArtifact = async (rawInput, signal) => {
         const analysis = analyzeJavaScriptArtifactFiles(files, input, () => performance.now());
         abortIfNeeded(signal);
         const graph = buildJavaScriptArtifactGraph(snapshot, files, analysis, input);
+        const semanticGraph = buildJavaScriptSemanticGraph({
+            rootArtifactSha256: snapshot.manifest.root_sha256,
+            applicationGraph: graph,
+            analysis,
+        });
         return {
             input_path: path,
             format,
@@ -31,6 +37,7 @@ export const reconstructJavaScriptArtifact = async (rawInput, signal) => {
             inventory_manifest_id: snapshot.manifest.manifest_id,
             inventory_graph_sha256: snapshot.manifest.graph_sha256,
             graph,
+            semantic_graph: semanticGraph,
             electron_summary: summarizeElectronBoundaries(analysis),
             statistics: {
                 relevant_files: files.files.length,

package/dist/application/JavaScriptModuleRelationships.js

@@ -2,6 +2,7 @@ import { posix } from "node:path";
 import { addAstContainsEdge, artifactLocalIdentity, } from "./JavaScriptArtifactGraphContext.js";
 import { astObservationEvidence, completeReconstructionCoverage, partialReconstructionCoverage, staticInferenceEvidence, } from "./JavaScriptArtifactGraphEvidence.js";
 import { resolveArtifactPathByContext } from "./JavaScriptArtifactPathResolution.js";
+import { projectJavaScriptExportReturnShapes } from "./JavaScriptReturnShapeProjection.js";
 /** Create one path-scoped source-module identity for every analyzed source file. */
 export const addJavaScriptSourceModules = (context) => {
     for (const analyzed of context.analysis.files) {
@@ -76,6 +77,13 @@ const addExportRelationship = (input) => {
     const { context, file, semantic, source, link } = input;
     if (link.exportedName === null)
         return;
+    const baseCoverage = semanticCoverage(semantic);
+    const returnShapes = projectJavaScriptExportReturnShapes({
+        ir: semantic.ir,
+        link,
+        modulePath: file.path,
+        baseCoverage,
+    });
     const exported = context.accumulator.addNode({
         kind: "javascript-module",
         identity: artifactLocalIdentity(file.sha256, "module-export", `${file.container_sha256}:${file.path}:${link.exportedName}`),
@@ -96,10 +104,26 @@ const addExportRelationship = (input) => {
                     path: file.path,
                     range: link.location,
                     operation: "recover-module-export",
-                    coverage: semanticCoverage(semantic),
+                    coverage: baseCoverage,
                     limitations: semantic.ir.limitations,
                 }),
             },
+            ...(returnShapes === null
+                ? []
+                : [
+                    {
+                        label: `${file.path}:${link.exportedName}:return-shapes`,
+                        properties: returnShapes.properties,
+                        evidence: staticInferenceEvidence({
+                            sha256: file.sha256,
+                            path: file.path,
+                            range: returnShapes.range,
+                            operation: "recover-export-return-shapes",
+                            coverage: returnShapes.coverage,
+                            limitations: returnShapes.limitations,
+                        }),
+                    },
+                ]),
         ],
     });
     context.accumulator.addEdge({

package/dist/application/JavaScriptReturnShapeProjection.js

@@ -0,0 +1,111 @@
+import { jsonObjectSchema, jsonValueSchema } from "../domain/jsonValue.js";
+import { flattenSemanticReturnValue } from "../domain/javascriptSemanticReturns.js";
+import { partialReconstructionCoverage } from "./JavaScriptArtifactGraphEvidence.js";
+const MAX_PROJECTED_RETURN_SHAPES = 32;
+const MAX_PROJECTED_RETURN_FIELDS = 64;
+const MAX_PROJECTED_PROPERTY_COVERAGE = 64;
+/** Project one exact export/callable link into shallow bounded graph values. */
+export const projectJavaScriptExportReturnShapes = (input) => {
+    if (input.link.callableId === null || input.link.exportedName === null)
+        return null;
+    const callable = input.ir.callables.find(({ callableId }) => callableId === input.link.callableId);
+    if (callable === undefined)
+        return null;
+    const projection = projectReturnSites(callable);
+    const projectionOmitted = projection.omittedSites +
+        projection.omittedFields +
+        projection.omittedCoverage;
+    const semanticOmitted = callable.returnCoverage.omittedCount;
+    const complete = input.baseCoverage.status === "complete" &&
+        callable.returnCoverage.status === "complete" &&
+        projectionOmitted === 0;
+    const coverage = complete
+        ? input.baseCoverage
+        : partialReconstructionCoverage([
+            ...input.baseCoverage.limits,
+            {
+                name: "return-shape-sites",
+                value: MAX_PROJECTED_RETURN_SHAPES,
+                unit: "items",
+            },
+            {
+                name: "return-shape-fields",
+                value: MAX_PROJECTED_RETURN_FIELDS,
+                unit: "items",
+            },
+            {
+                name: "return-shape-property-coverage",
+                value: MAX_PROJECTED_PROPERTY_COVERAGE,
+                unit: "items",
+            },
+        ], semanticOmitted === null ? null : semanticOmitted + projectionOmitted, callable.returnCoverage.status === "truncated" || projectionOmitted > 0);
+    const limitations = [
+        ...input.ir.limitations,
+        "Return shapes are inferred from inert syntax and do not prove runtime behavior.",
+        ...(callable.returnSites.length === 0
+            ? [
+                "No direct return value was retained; runtime return behavior remains unknown.",
+            ]
+            : []),
+        ...(projectionOmitted > 0
+            ? ["Return-shape graph projection reached explicit retention limits."]
+            : []),
+    ];
+    return {
+        properties: jsonObjectSchema.parse({
+            semantic_role: "export-return-shapes",
+            module_path: input.modulePath,
+            exported_name: input.link.exportedName,
+            callable_id: callable.callableId,
+            callable_kind: callable.kind,
+            static_return_shapes: projection.shapes,
+            return_shape_coverage: {
+                status: callable.returnCoverage.status,
+                retained_return_sites: projection.shapes.length,
+                omitted_return_sites: semanticOmitted === null
+                    ? null
+                    : semanticOmitted + projection.omittedSites,
+                omitted_fields: projection.omittedFields,
+                omitted_property_coverage: projection.omittedCoverage,
+                projection_complete: projectionOmitted === 0,
+            },
+        }),
+        range: callable.location,
+        coverage,
+        limitations,
+    };
+};
+const projectReturnSites = (callable) => {
+    let retainedFields = 0;
+    let retainedCoverage = 0;
+    let omittedFields = 0;
+    let omittedCoverage = 0;
+    const retainedSites = callable.returnSites.slice(0, MAX_PROJECTED_RETURN_SHAPES);
+    const shapes = retainedSites.map((site) => {
+        const flattened = flattenSemanticReturnValue(site.value);
+        const remainingFields = Math.max(0, MAX_PROJECTED_RETURN_FIELDS - retainedFields);
+        const fields = flattened.fields.slice(0, remainingFields).map((field) => ({
+            ...field,
+            value: jsonValueSchema.parse(field.value),
+        }));
+        retainedFields += fields.length;
+        omittedFields += flattened.fields.length - fields.length;
+        const remainingCoverage = Math.max(0, MAX_PROJECTED_PROPERTY_COVERAGE - retainedCoverage);
+        const propertyCoverage = flattened.propertyCoverage.slice(0, remainingCoverage);
+        retainedCoverage += propertyCoverage.length;
+        omittedCoverage +=
+            flattened.propertyCoverage.length - propertyCoverage.length;
+        return {
+            source_range: site.location,
+            value_status: site.value.status,
+            fields,
+            property_coverage: propertyCoverage,
+        };
+    });
+    return {
+        shapes,
+        omittedSites: callable.returnSites.length - retainedSites.length,
+        omittedFields,
+        omittedCoverage,
+    };
+};

package/dist/application/JavaScriptSemanticGraphBuilder.js

@@ -0,0 +1,294 @@
+import { createJavaScriptSemanticGraph, } from "../domain/javascriptSemanticGraph.js";
+import { JAVASCRIPT_SEMANTIC_RELATION_FAMILIES, JAVASCRIPT_SEMANTIC_RELATION_FAMILY, } from "../domain/javascriptSemanticGraphSchemas.js";
+import { inferredSemanticEvidenceAt } from "./JavaScriptSemanticGraphEvidence.js";
+import { projectSemanticClosureCaptures, projectSemanticFrontiers, projectSemanticReturnValues, semanticRecoveryLimits, } from "./JavaScriptSemanticGraphFlowProjection.js";
+import { owningSemanticCallableNode, semanticFamilyStatus, semanticNodesWithinRange, semanticRangesEqual as rangesEqual, } from "./JavaScriptSemanticGraphProjection.js";
+import { addSemanticFallbackRoot as addFallbackRoot, addSemanticGraphNode as addNode, addSemanticGraphRelation as addRelation, constructSemanticGraphNode as semanticNode, createSemanticGraphProjectionState as emptyState, MAX_APPLICATION_NODE_IDS_PER_SEMANTIC_NODE, MAX_SEMANTIC_GRAPH_NODES, MAX_SEMANTIC_GRAPH_RELATIONS, MAX_SEMANTIC_GRAPH_UNKNOWNS, } from "./JavaScriptSemanticGraphConstruction.js";
+/** Project bounded per-file semantic IR into an artifact-bound companion graph. */
+export const buildJavaScriptSemanticGraph = ({ rootArtifactSha256, applicationGraph, analysis, }) => {
+    const state = emptyState(applicationGraph);
+    for (const analyzed of analysis.files) {
+        if (analyzed.semantic === null)
+            continue;
+        projectFile(analyzed.file, analyzed.semantic.ir, state);
+    }
+    if (state.roots.size === 0)
+        addFallbackRoot(rootArtifactSha256, state);
+    const semanticTruncated = analysis.files.some(({ semantic }) => semantic?.ir.coverage.status === "truncated");
+    const truncated = state.limitsReached.size > 0 || semanticTruncated;
+    const unknowns = [...state.unknowns.values()];
+    return createJavaScriptSemanticGraph({
+        schema: "JavaScriptSemanticRelationGraph",
+        schema_version: 1,
+        root_artifact_sha256: rootArtifactSha256,
+        application_graph_id: applicationGraph.graph_id,
+        root_node_ids: [...state.roots],
+        nodes: [...state.nodes.values()],
+        relations: [...state.relations.values()],
+        fingerprints: [],
+        unknowns,
+        coverage: {
+            status: truncated ? "partial" : "unknown",
+            truncated,
+            omitted_nodes: truncated ? null : 0,
+            omitted_relations: truncated ? null : 0,
+            limits: [
+                {
+                    name: "max_nodes",
+                    value: MAX_SEMANTIC_GRAPH_NODES,
+                    unit: "items",
+                },
+                {
+                    name: "max_relations",
+                    value: MAX_SEMANTIC_GRAPH_RELATIONS,
+                    unit: "items",
+                },
+                {
+                    name: "max_unknowns",
+                    value: MAX_SEMANTIC_GRAPH_UNKNOWNS,
+                    unit: "items",
+                },
+                {
+                    name: "max_application_node_ids_per_semantic_node",
+                    value: MAX_APPLICATION_NODE_IDS_PER_SEMANTIC_NODE,
+                    unit: "items",
+                },
+                ...semanticRecoveryLimits(analysis),
+            ],
+            families: JAVASCRIPT_SEMANTIC_RELATION_FAMILIES.map((family) => ({
+                family,
+                status: semanticFamilyStatus(family, analysis, truncated),
+                retained_relations: [...state.relations.values()].filter((relation) => JAVASCRIPT_SEMANTIC_RELATION_FAMILY[relation.relation] === family).length,
+                omitted_relations: truncated ? null : 0,
+                unknown_ids: unknowns
+                    .filter((unknown) => unknown.family === family)
+                    .map(({ unknown_id: identifier }) => identifier),
+            })),
+        },
+        limitations: [
+            "The semantic graph contains static syntax observations and conservative relationship candidates; it does not claim runtime execution.",
+            "Local data flow does not claim control-flow-sensitive reaching definitions or arbitrary dynamic property resolution.",
+            "Function fingerprints and promise, event, process, request, boundary, timer, configuration, and resource extraction are not available in this graph version's current extractor coverage.",
+            ...(truncated
+                ? [
+                    "Semantic graph projection reached one or more explicit hard limits.",
+                ]
+                : []),
+        ],
+    });
+};
+const projectFile = (file, ir, state) => {
+    const moduleNode = addNode(state, semanticNode(file, {
+        kind: "module",
+        roleKey: "module",
+        location: null,
+        label: file.path,
+        functionNodeId: null,
+    }, state));
+    if (moduleNode === null)
+        return;
+    state.roots.add(moduleNode.node_id);
+    const callableNodes = new Map(ir.callables.flatMap((callable) => {
+        const node = addNode(state, semanticNode(file, {
+            kind: "function",
+            roleKey: `callable:${callable.callableId}`,
+            location: callable.location,
+            label: callable.name,
+            functionNodeId: null,
+        }, state));
+        return node === null ? [] : [[callable.callableId, node]];
+    }));
+    const bindingNodes = new Map(ir.bindings.flatMap((binding) => {
+        const location = binding.definitions[0]?.location ?? null;
+        const kind = binding.kind === "parameter" ? "parameter" : "binding";
+        const owner = owningSemanticCallableNode(location, ir, callableNodes);
+        const node = addNode(state, semanticNode(file, {
+            kind,
+            roleKey: `binding:${binding.bindingId}`,
+            location,
+            label: binding.name,
+            functionNodeId: owner?.node_id ?? null,
+        }, state));
+        return node === null ? [] : [[binding.bindingId, node]];
+    }));
+    const returnSiteNodes = createReturnSiteNodes(file, ir, callableNodes, state);
+    const callSiteNodes = createCallSiteNodes(file, ir, callableNodes, state);
+    const context = {
+        file,
+        ir,
+        state,
+        moduleNode,
+        bindingNodes,
+        callableNodes,
+        callSiteNodes,
+        returnSiteNodes,
+        argumentNodes: new Map(),
+        referenceNodes: [],
+        callResolutions: new Map(ir.callSites.map((call) => [
+            call.callSiteId,
+            call.resolution === "exact" ? "resolved" : "candidate",
+        ])),
+    };
+    projectDefinitionsAndReferences(context);
+    projectCalls(context);
+    projectSemanticClosureCaptures(context);
+    projectSemanticFrontiers(context);
+};
+const createReturnSiteNodes = (file, ir, callables, state) => {
+    const result = new Map();
+    for (const callable of ir.callables) {
+        const owner = callables.get(callable.callableId);
+        if (owner === undefined)
+            continue;
+        for (const site of callable.returnSites) {
+            const identifier = site.returnSiteId;
+            const node = addNode(state, semanticNode(file, {
+                kind: "return-site",
+                roleKey: identifier,
+                location: site.location,
+                label: "return",
+                functionNodeId: owner.node_id,
+            }, state));
+            if (node !== null)
+                result.set(identifier, node);
+        }
+    }
+    return result;
+};
+const createCallSiteNodes = (file, ir, callables, state) => {
+    const result = new Map();
+    for (const call of ir.callSites) {
+        const owner = call.callerCallableId === null
+            ? null
+            : (callables.get(call.callerCallableId)?.node_id ?? null);
+        const node = addNode(state, semanticNode(file, {
+            kind: "call-site",
+            roleKey: `call:${call.callSiteId}`,
+            location: call.location,
+            label: call.kind,
+            functionNodeId: owner,
+        }, state));
+        if (node !== null)
+            result.set(call.callSiteId, node);
+    }
+    return result;
+};
+const projectDefinitionsAndReferences = (context) => {
+    for (const binding of context.ir.bindings) {
+        const bindingNode = context.bindingNodes.get(binding.bindingId);
+        if (bindingNode === undefined)
+            continue;
+        for (const [index, definition] of binding.definitions.entries()) {
+            const definitionNode = addNode(context.state, semanticNode(context.file, {
+                kind: "expression",
+                roleKey: `definition:${binding.bindingId}:${String(index)}`,
+                location: definition.location,
+                label: definition.kind,
+                functionNodeId: bindingNode.function_node_id,
+            }, context.state));
+            addRelation(context.state, {
+                source: definitionNode,
+                target: bindingNode,
+                relation: "defines",
+                resolution: "resolved",
+            });
+        }
+    }
+    for (const [index, reference] of context.ir.references.entries()) {
+        const expression = addNode(context.state, semanticNode(context.file, {
+            kind: "expression",
+            roleKey: `reference:${String(index)}:${reference.role}:${reference.name}`,
+            location: reference.location,
+            label: reference.name,
+            functionNodeId: owningSemanticCallableNode(reference.location, context.ir, context.callableNodes)?.node_id ?? null,
+        }, context.state));
+        const binding = reference.bindingId === null
+            ? undefined
+            : context.bindingNodes.get(reference.bindingId);
+        if (expression !== null)
+            context.referenceNodes.push(expression);
+        if (binding === undefined || expression === null)
+            continue;
+        if (reference.role === "read")
+            addRelation(context.state, {
+                source: binding,
+                target: expression,
+                relation: "reads",
+                resolution: "resolved",
+                evidence: inferredSemanticEvidenceAt(context.file, reference.location),
+            });
+        else
+            addRelation(context.state, {
+                source: expression,
+                target: binding,
+                relation: "writes",
+                resolution: "resolved",
+            });
+    }
+};
+const projectCalls = (context) => {
+    for (const call of context.ir.callSites) {
+        const callNode = context.callSiteNodes.get(call.callSiteId);
+        if (callNode === undefined)
+            continue;
+        for (const callableId of call.calleeCallableIds) {
+            const callable = context.callableNodes.get(callableId);
+            addRelation(context.state, {
+                source: callNode,
+                target: callable,
+                relation: "calls",
+                resolution: call.resolution === "exact" ? "resolved" : "candidate",
+            });
+        }
+        for (const argument of call.arguments) {
+            const argumentNode = createArgumentNode(context, callNode, call.callSiteId, argument);
+            if (argumentNode !== null)
+                context.argumentNodes.set(`${call.callSiteId}\u0000${String(argument.index)}`, argumentNode);
+            const references = semanticNodesWithinRange(context.referenceNodes, argument.location);
+            for (const reference of references)
+                addRelation(context.state, {
+                    source: reference,
+                    target: argumentNode,
+                    relation: "aliases",
+                    resolution: references.length === 1 &&
+                        rangesEqual(reference.identity.source_range, argument.location)
+                        ? "resolved"
+                        : "candidate",
+                });
+        }
+    }
+    for (const flow of context.ir.argumentFlows) {
+        const argument = context.argumentNodes.get(`${flow.callSiteId}\u0000${String(flow.argumentIndex)}`);
+        const parameter = context.bindingNodes.get(flow.parameterBindingId);
+        addRelation(context.state, {
+            source: argument,
+            target: parameter,
+            relation: "argument-to-parameter",
+            resolution: context.callResolutions.get(flow.callSiteId) ?? "candidate",
+        });
+    }
+    for (const flow of context.ir.callReturnFlows)
+        addRelation(context.state, {
+            source: context.returnSiteNodes.get(flow.returnSiteId),
+            target: context.callSiteNodes.get(flow.callSiteId),
+            relation: "returns-to-call",
+            resolution: context.callResolutions.get(flow.callSiteId) ?? "candidate",
+        });
+    for (const flow of context.ir.callResultFlows)
+        addRelation(context.state, {
+            source: context.callSiteNodes.get(flow.callSiteId),
+            target: context.bindingNodes.get(flow.bindingId),
+            relation: "aliases",
+            resolution: context.callResolutions.get(flow.callSiteId) ?? "candidate",
+        });
+    projectSemanticReturnValues(context);
+};
+const createArgumentNode = (context, callNode, callSiteId, argument) => addNode(context.state, semanticNode(context.file, {
+    kind: "expression",
+    roleKey: `argument:${callSiteId}:${String(argument.index)}`,
+    location: argument.location,
+    label: argument.spread
+        ? "spread argument"
+        : `argument ${String(argument.index)}`,
+    functionNodeId: callNode.function_node_id,
+}, context.state));

package/dist/application/JavaScriptSemanticGraphConstruction.js

@@ -0,0 +1,144 @@
+import { createJavaScriptSemanticGraphNode, createJavaScriptSemanticGraphRelation, } from "../domain/javascriptSemanticGraph.js";
+import { inferredSemanticEvidence, observedSemanticEvidence, unavailableSemanticRootEvidence, } from "./JavaScriptSemanticGraphEvidence.js";
+/** Hard semantic graph node bound enforced during artifact projection. */
+export const MAX_SEMANTIC_GRAPH_NODES = 100_000;
+/** Hard semantic graph relation bound enforced during artifact projection. */
+export const MAX_SEMANTIC_GRAPH_RELATIONS = 200_000;
+/** Hard unresolved-frontier bound enforced across all analyzed files. */
+export const MAX_SEMANTIC_GRAPH_UNKNOWNS = 100_000;
+/** Maximum structural nodes linked to one exact semantic location. */
+export const MAX_APPLICATION_NODE_IDS_PER_SEMANTIC_NODE = 64;
+/** Create empty projection state with structural application-node mappings. */
+export const createSemanticGraphProjectionState = (applicationGraph) => {
+    const index = indexApplicationNodes(applicationGraph.nodes);
+    return {
+        nodes: new Map(),
+        relations: new Map(),
+        unknowns: new Map(),
+        roots: new Set(),
+        limitsReached: new Set(index.truncated ? ["max_application_node_ids_per_semantic_node"] : []),
+        applicationNodeIdsByLocation: index.identifiers,
+    };
+};
+/** Construct one canonical semantic node backed by an exact artifact file. */
+export const constructSemanticGraphNode = (file, input, state) => createJavaScriptSemanticGraphNode({
+    kind: input.kind,
+    identity: {
+        artifact_sha256: file.sha256,
+        module_path: file.path,
+        source_range: input.location,
+        role_key: input.roleKey,
+    },
+    function_node_id: input.functionNodeId,
+    application_node_ids: matchingApplicationNodeIds(file, input, state),
+    label: input.label,
+    properties: {},
+    evidence: observedSemanticEvidence(file, input.location),
+});
+/** Retain one canonical node unless the hard graph bound was reached. */
+export const addSemanticGraphNode = (state, node) => {
+    const existing = state.nodes.get(node.node_id);
+    if (existing !== undefined)
+        return existing;
+    if (state.nodes.size >= MAX_SEMANTIC_GRAPH_NODES) {
+        state.limitsReached.add("max_nodes");
+        return null;
+    }
+    state.nodes.set(node.node_id, node);
+    return node;
+};
+/** Retain one non-self semantic relationship unless its hard bound was reached. */
+export const addSemanticGraphRelation = (state, input) => {
+    if (input.source === undefined ||
+        input.source === null ||
+        input.target === undefined ||
+        input.target === null ||
+        input.source.node_id === input.target.node_id)
+        return;
+    const value = createJavaScriptSemanticGraphRelation({
+        source_node_id: input.source.node_id,
+        target_node_id: input.target.node_id,
+        relation: input.relation,
+        resolution: input.resolution ?? "candidate",
+        properties: {},
+        evidence: input.evidence ?? inferredSemanticEvidence(input.source),
+    });
+    if (state.relations.has(value.relation_id))
+        return;
+    if (state.relations.size >= MAX_SEMANTIC_GRAPH_RELATIONS) {
+        state.limitsReached.add("max_relations");
+        return;
+    }
+    state.relations.set(value.relation_id, value);
+};
+/** Retain one unresolved frontier unless the global graph bound was reached. */
+export const addSemanticGraphUnknown = (state, unknown) => {
+    if (state.unknowns.has(unknown.unknown_id))
+        return;
+    if (state.unknowns.size >= MAX_SEMANTIC_GRAPH_UNKNOWNS) {
+        state.limitsReached.add("max_unknowns");
+        return;
+    }
+    state.unknowns.set(unknown.unknown_id, unknown);
+};
+/** Add a truthful root when no source file could produce semantic IR. */
+export const addSemanticFallbackRoot = (rootArtifactSha256, state) => {
+    const node = addSemanticGraphNode(state, createJavaScriptSemanticGraphNode({
+        kind: "module",
+        identity: {
+            artifact_sha256: rootArtifactSha256,
+            module_path: "unknown-semantic-root",
+            source_range: null,
+            role_key: "artifact-root",
+        },
+        function_node_id: null,
+        application_node_ids: [],
+        label: "unavailable semantic root",
+        properties: {},
+        evidence: unavailableSemanticRootEvidence(rootArtifactSha256),
+    }));
+    if (node !== null)
+        state.roots.add(node.node_id);
+};
+const indexApplicationNodes = (nodes) => {
+    const identifiers = new Map();
+    for (const node of nodes) {
+        for (const observation of node.observations) {
+            const { artifact, location } = observation.evidence;
+            if (!artifact.available || !location.available)
+                continue;
+            if (location.value.kind === "artifact-path") {
+                addApplicationNodeIdentifier(identifiers, applicationLocationKey(artifact.sha256, location.value.path, null), node.node_id);
+            }
+            if (location.value.kind === "source-range") {
+                addApplicationNodeIdentifier(identifiers, applicationLocationKey(artifact.sha256, location.value.source, {
+                    start: location.value.start,
+                    end: location.value.end,
+                }), node.node_id);
+            }
+        }
+    }
+    let truncated = false;
+    const indexed = new Map([...identifiers].map(([key, values]) => {
+        const sorted = [...values].sort();
+        if (sorted.length > MAX_APPLICATION_NODE_IDS_PER_SEMANTIC_NODE)
+            truncated = true;
+        return [key, sorted.slice(0, MAX_APPLICATION_NODE_IDS_PER_SEMANTIC_NODE)];
+    }));
+    return { identifiers: indexed, truncated };
+};
+const matchingApplicationNodeIds = (file, input, state) => [
+    ...(state.applicationNodeIdsByLocation.get(applicationLocationKey(file.sha256, file.path, input.location)) ?? []),
+];
+const addApplicationNodeIdentifier = (identifiers, key, nodeId) => {
+    const values = identifiers.get(key) ?? new Set();
+    values.add(nodeId);
+    identifiers.set(key, values);
+};
+const applicationLocationKey = (artifactSha256, path, range) => [
+    artifactSha256,
+    path,
+    range === null
+        ? "artifact-path"
+        : `${range.start.line}:${range.start.column}-${range.end.line}:${range.end.column}`,
+].join("\u0000");