rea-agents 4.1.0 → 6.0.0

package/dist/application/{JavaScriptSemanticGraphBuilder.js → javascript/JavaScriptSemanticGraphBuilder.js}

@@ -1,6 +1,6 @@
-import { createJavaScriptSemanticGraph, } from "../domain/javascriptSemanticGraph.js";
-import { JAVASCRIPT_SEMANTIC_RELATION_FAMILIES, JAVASCRIPT_SEMANTIC_RELATION_FAMILY, } from "../domain/javascriptSemanticGraphSchemas.js";
-import { sourceRangesEqual as rangesEqual } from "../domain/javascriptStaticAnalysisHelpers.js";
+import { createJavaScriptSemanticGraph, } from "../../domain/javascript/javascriptSemanticGraph.js";
+import { JAVASCRIPT_SEMANTIC_RELATION_FAMILIES, JAVASCRIPT_SEMANTIC_RELATION_FAMILY, } from "../../domain/javascript/javascriptSemanticGraphSchemas.js";
+import { sourceRangesEqual as rangesEqual } from "../../domain/javascript/javascriptStaticAnalysisHelpers.js";
 import { projectSemanticEvents, projectSemanticTimers, } from "./JavaScriptSemanticGraphAsyncProjection.js";
 import { projectSemanticChildProcesses } from "./JavaScriptSemanticGraphChildProcessProjection.js";
 import { projectSemanticBoundaries, projectSemanticConfiguration, projectSemanticRequests, } from "./JavaScriptSemanticGraphDataProjection.js";
@@ -10,97 +10,168 @@ import { projectSemanticValues } from "./JavaScriptSemanticGraphValueProjection.
 import { inferredSemanticEvidenceAt } from "./JavaScriptSemanticGraphEvidence.js";
 import { projectSemanticFunctionFingerprints } from "./JavaScriptSemanticGraphFingerprintProjection.js";
 import { projectSemanticClosureCaptures, projectSemanticFrontiers, projectSemanticPromises, projectSemanticReturnValues, } from "./JavaScriptSemanticGraphFlowProjection.js";
-import { owningSemanticCallableNode, semanticFamilyStatus, semanticNodesWithinRange, } from "./JavaScriptSemanticGraphProjection.js";
-import { addSemanticFallbackRoot as addFallbackRoot, addSemanticGraphNode as addNode, addSemanticGraphRelation as addRelation, constructSemanticGraphNode as semanticNode, createSemanticGraphProjectionState as emptyState, } from "./JavaScriptSemanticGraphConstruction.js";
-/** Project per-file semantic IR into an artifact-bound companion graph. */
+import { createSemanticCallableOwnerLookup, createSemanticCallSiteLookup, createSemanticNodeRangeLookup, semanticFamilyStatus, } from "./JavaScriptSemanticGraphProjection.js";
+import { addSemanticFallbackRoot as addFallbackRoot, retainSemanticGraphNode as retainNode, addSemanticGraphRelation as addRelation, createSemanticGraphProjectionState as emptyState, bindSemanticGraphApplicationNodes, } from "./JavaScriptSemanticGraphConstruction.js";
+/**
+ * Resource-safety ceiling on retained semantic nodes.
+ *
+ * The semantic projection emits one node per AST expression, call site, binding
+ * and property slot. That is unbounded in input size. A small tree of five files
+ * already yields on the order of 170,000 nodes, and larger trees yield millions,
+ * exhausting the heap before the result can be serialized.
+ *
+ * This is a real resource-safety constraint, not a presentation preference, so
+ * the ceiling is applied and reported through the graph's own `coverage` fields
+ * (`truncated`, `omitted_nodes`, `omitted_relations`, `limits`) rather than
+ * silently dropping data.
+ *
+ * Sizing: a retained semantic node costs roughly 3 KB once serialized, and V8
+ * additionally caps a single string at 512 MB. The result is serialized after the
+ * object graph is built and validated, so both phases must fit together. A single
+ * minified vendor bundle can account for most of a tree's nodes, so a whole-tree
+ * ceiling without a per-file ceiling does not bound the work. Both are applied.
+ */
+export const SEMANTIC_GRAPH_NODE_CEILING = 100_000;
+/**
+ * Per-file share of the semantic node budget.
+ *
+ * Bound each source file independently so one large bundled library cannot
+ * consume the whole tree's budget and starve the application's own modules.
+ */
+export const SEMANTIC_GRAPH_FILE_NODE_CEILING = 20_000;
 export const buildJavaScriptSemanticGraph = ({ rootArtifactSha256, applicationGraph, analysis, }) => {
-    const state = emptyState(applicationGraph);
-    const fingerprints = [];
+    const projection = createJavaScriptSemanticGraphProjection();
     for (const analyzed of analysis.files) {
-        if (analyzed.semantic === null)
-            continue;
-        fingerprints.push(...projectFile(analyzed.file, analyzed.semantic.ir, state));
+        if (analyzed.semantic !== null)
+            projection.projectFile(analyzed.file, analyzed.semantic.ir);
     }
-    if (state.roots.size === 0)
-        addFallbackRoot(rootArtifactSha256, state);
-    const unknowns = [...state.unknowns.values()];
-    return createJavaScriptSemanticGraph({
-        schema: "JavaScriptSemanticRelationGraph",
-        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: "unknown",
-            truncated: false,
-            omitted_nodes: 0,
-            omitted_relations: 0,
-            limits: [],
-            families: JAVASCRIPT_SEMANTIC_RELATION_FAMILIES.map((family) => ({
-                family,
-                status: semanticFamilyStatus(family, analysis),
-                retained_relations: [...state.relations.values()].filter((relation) => JAVASCRIPT_SEMANTIC_RELATION_FAMILY[relation.relation] === family).length,
-                omitted_relations: 0,
-                unknown_ids: unknowns
-                    .filter((unknown) => unknown.family === family)
-                    .map(({ unknown_id: identifier }) => identifier),
-            })),
+    return projection.finish(rootArtifactSha256, applicationGraph, analysis);
+};
+/** Accumulate semantic nodes while each source IR is still file-local. */
+export const createJavaScriptSemanticGraphProjection = () => {
+    const state = emptyState({ nodes: [] });
+    const fingerprints = [];
+    let truncatedFiles = 0;
+    const projectSource = (file, ir) => {
+        if (state.nodes.size >= SEMANTIC_GRAPH_NODE_CEILING) {
+            truncatedFiles += 1;
+            return;
+        }
+        const remainingTreeBudget = SEMANTIC_GRAPH_NODE_CEILING - state.nodes.size;
+        state.fileNodeBudget = Math.min(SEMANTIC_GRAPH_FILE_NODE_CEILING, remainingTreeBudget);
+        state.fileNodesDropped = false;
+        fingerprints.push(...projectFile(file, ir, state));
+        // Nodes were dropped only if the budget actually blocked creation. A file
+        // that exactly fills its share ends with a zero budget without dropping
+        // anything, so the remaining budget alone cannot decide truncation.
+        if (state.fileNodesDropped)
+            truncatedFiles += 1;
+        state.fileNodeBudget = null;
+    };
+    return {
+        projectFile: projectSource,
+        finish: (rootArtifactSha256, applicationGraph, analysis) => {
+            bindSemanticGraphApplicationNodes(state, applicationGraph);
+            if (state.roots.size === 0)
+                addFallbackRoot(rootArtifactSha256, state);
+            const unknowns = [...state.unknowns.values()];
+            const graph = createJavaScriptSemanticGraph({
+                schema: "JavaScriptSemanticRelationGraph",
+                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: truncatedFiles > 0 ? "partial" : "unknown",
+                    truncated: truncatedFiles > 0,
+                    omitted_nodes: truncatedFiles > 0 ? null : 0,
+                    omitted_relations: truncatedFiles > 0 ? null : 0,
+                    limits: truncatedFiles > 0
+                        ? [
+                            {
+                                name: "semantic_graph_node_ceiling",
+                                value: SEMANTIC_GRAPH_NODE_CEILING,
+                                unit: "items",
+                            },
+                        ]
+                        : [],
+                    families: JAVASCRIPT_SEMANTIC_RELATION_FAMILIES.map((family) => ({
+                        family,
+                        status: semanticFamilyStatus(family, analysis),
+                        retained_relations: [...state.relations.values()].filter((relation) => JAVASCRIPT_SEMANTIC_RELATION_FAMILY[relation.relation] ===
+                            family).length,
+                        omitted_relations: truncatedFiles > 0 ? 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.",
+                    "Promise ownership covers explicit unshadowed Promise construction, static factories, aggregation, chaining, and await syntax only.",
+                    "Function fingerprints are static candidates; equal digests can remain ambiguous and do not prove behavioral equivalence.",
+                    "Event extraction covers EventEmitter-style literal registrations, removals, and dispatch candidates; dynamic names remain unknown.",
+                    "Timer extraction covers global or node:timers scheduling and exact local-handle cancellation.",
+                    "Child-process extraction covers asynchronous node:child_process creation, literal argv/env/stdio options, exit/error listeners, and kill signals.",
+                    "Configuration extraction covers process.env, process.argv, node:fs reads, and direct logical defaults.",
+                    "Request extraction covers fetch, WebSocket, node:http/node:https construction, direct option fields, and exact local response consumers.",
+                    "Boundary extraction covers unshadowed JSON/global coercions plus parse and validation method candidates.",
+                    "Resource extraction covers built-in filesystem/network acquisition and exact local close/destroy/end handles.",
+                ],
+            });
+            state.nodes.clear();
+            state.relations.clear();
+            state.unknowns.clear();
+            state.roots.clear();
+            fingerprints.length = 0;
+            return graph;
         },
-        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.",
-            "Promise ownership covers explicit unshadowed Promise construction, static factories, aggregation, chaining, and await syntax only.",
-            "Function fingerprints are static candidates; equal digests can remain ambiguous and do not prove behavioral equivalence.",
-            "Event extraction covers EventEmitter-style literal registrations, removals, and dispatch candidates; dynamic names remain unknown.",
-            "Timer extraction covers global or node:timers scheduling and exact local-handle cancellation.",
-            "Child-process extraction covers asynchronous node:child_process creation, literal argv/env/stdio options, exit/error listeners, and kill signals.",
-            "Configuration extraction covers process.env, process.argv, node:fs reads, and direct logical defaults.",
-            "Request extraction covers fetch, WebSocket, node:http/node:https construction, direct option fields, and exact local response consumers.",
-            "Boundary extraction covers unshadowed JSON/global coercions plus parse and validation method candidates.",
-            "Resource extraction covers built-in filesystem/network acquisition and exact local close/destroy/end handles.",
-        ],
-    });
+    };
 };
 const projectFile = (file, ir, state) => {
-    const moduleNode = addNode(state, semanticNode(file, {
+    const moduleNode = retainNode(state, 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, {
+        const node = retainNode(state, file, {
             kind: "function",
             roleKey: `callable:${callable.callableId}`,
             location: callable.location,
             label: callable.name,
             functionNodeId: null,
-        }, state));
+            // The label is display text; keep the exact name, which may be "".
+            properties: { name: callable.name },
+        });
         return node === null ? [] : [[callable.callableId, node]];
     }));
+    const callableOwnerAt = createSemanticCallableOwnerLookup(ir, callableNodes);
     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, {
+        const owner = callableOwnerAt(location);
+        const node = retainNode(state, 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 = {
+    const definitions = {
         file,
         ir,
         state,
@@ -115,8 +186,14 @@ const projectFile = (file, ir, state) => {
             call.callSiteId,
             call.resolution === "exact" ? "resolved" : "candidate",
         ])),
+        callableOwnerAt,
+        callSiteAt: createSemanticCallSiteLookup(ir, callSiteNodes),
+    };
+    projectDefinitionsAndReferences(definitions);
+    const context = {
+        ...definitions,
+        referenceNodesWithin: createSemanticNodeRangeLookup(definitions.referenceNodes),
     };
-    projectDefinitionsAndReferences(context);
     projectSemanticValues(context);
     projectSemanticObjects(context);
     projectCalls(context);
@@ -140,13 +217,13 @@ const createReturnSiteNodes = (file, ir, callables, state) => {
             continue;
         for (const site of callable.returnSites) {
             const identifier = site.returnSiteId;
-            const node = addNode(state, semanticNode(file, {
+            const node = retainNode(state, file, {
                 kind: "return-site",
                 roleKey: identifier,
                 location: site.location,
                 label: "return",
                 functionNodeId: owner.node_id,
-            }, state));
+            });
             if (node !== null)
                 result.set(identifier, node);
         }
@@ -159,13 +236,13 @@ const createCallSiteNodes = (file, ir, callables, state) => {
         const owner = call.callerCallableId === null
             ? null
             : (callables.get(call.callerCallableId)?.node_id ?? null);
-        const node = addNode(state, semanticNode(file, {
+        const node = retainNode(state, 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);
     }
@@ -177,13 +254,13 @@ const projectDefinitionsAndReferences = (context) => {
         if (bindingNode === undefined)
             continue;
         for (const [index, definition] of binding.definitions.entries()) {
-            const definitionNode = addNode(context.state, semanticNode(context.file, {
+            const definitionNode = retainNode(context.state, 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,
@@ -193,13 +270,13 @@ const projectDefinitionsAndReferences = (context) => {
         }
     }
     for (const [index, reference] of context.ir.references.entries()) {
-        const expression = addNode(context.state, semanticNode(context.file, {
+        const expression = retainNode(context.state, 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));
+            functionNodeId: context.callableOwnerAt(reference.location)?.node_id ?? null,
+        });
         const binding = reference.bindingId === null
             ? undefined
             : context.bindingNodes.get(reference.bindingId);
@@ -242,7 +319,7 @@ const projectCalls = (context) => {
             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);
+            const references = context.referenceNodesWithin(argument.location);
             for (const reference of references)
                 addRelation(context.state, {
                     source: reference,
@@ -281,7 +358,7 @@ const projectCalls = (context) => {
         });
     projectSemanticReturnValues(context);
 };
-const createArgumentNode = (context, callNode, callSiteId, argument) => addNode(context.state, semanticNode(context.file, {
+const createArgumentNode = (context, callNode, callSiteId, argument) => retainNode(context.state, context.file, {
     kind: "expression",
     roleKey: `argument:${callSiteId}:${String(argument.index)}`,
     location: argument.location,
@@ -289,4 +366,4 @@ const createArgumentNode = (context, callNode, callSiteId, argument) => addNode(
         ? "spread argument"
         : `argument ${String(argument.index)}`,
     functionNodeId: callNode.function_node_id,
-}, context.state));
+});

package/dist/application/{JavaScriptSemanticGraphChildProcessProjection.js → javascript/JavaScriptSemanticGraphChildProcessProjection.js}

@@ -1,5 +1,5 @@
-import { createJavaScriptSemanticGraphUnknown } from "../domain/javascriptSemanticGraph.js";
-import { addSemanticGraphNode, addSemanticGraphRelation, addSemanticGraphUnknown, constructSemanticGraphNode, } from "./JavaScriptSemanticGraphConstruction.js";
+import { createJavaScriptSemanticGraphUnknown } from "../../domain/javascript/javascriptSemanticGraph.js";
+import { retainSemanticGraphNode, addSemanticGraphRelation, addSemanticGraphUnknown, } from "./JavaScriptSemanticGraphConstruction.js";
 import { unknownSemanticEvidence } from "./JavaScriptSemanticGraphEvidence.js";
 import { semanticCallSiteAt, } from "./JavaScriptSemanticGraphFlowProjection.js";
 /** Project child creation, argv/env/stdio, listeners, and signals. */
@@ -17,15 +17,14 @@ export const projectSemanticChildProcesses = (context) => {
     for (const interaction of context.ir.childProcessInteractions)
         projectInteraction(context, interaction, processNodes);
 };
-const addChildProcessNode = (context, spawn) => addSemanticGraphNode(context.state, constructSemanticGraphNode(context.file, {
+const addChildProcessNode = (context, spawn) => retainSemanticGraphNode(context.state, context.file, {
     kind: "child-process",
     roleKey: spawn.processId,
     location: spawn.location,
     label: spawn.command ?? spawn.method,
     functionNodeId: spawn.ownerCallableId === null
         ? null
-        : (context.callableNodes.get(spawn.ownerCallableId)?.node_id ??
-            null),
+        : (context.callableNodes.get(spawn.ownerCallableId)?.node_id ?? null),
     properties: {
         argv_count: spawn.argvCount,
         command: spawn.command,
@@ -33,7 +32,7 @@ const addChildProcessNode = (context, spawn) => addSemanticGraphNode(context.sta
         method: spawn.method,
         stdio_mode: spawn.stdioMode,
     },
-}, context.state));
+});
 const projectSpawn = (context, spawn, child) => {
     const callSite = semanticCallSiteAt(context, spawn.location);
     addSemanticGraphRelation(context.state, {
@@ -85,14 +84,14 @@ const projectSpawn = (context, spawn, child) => {
             candidateNodeIds: [],
         });
 };
-const addStdioNode = (context, spawn, child) => addSemanticGraphNode(context.state, constructSemanticGraphNode(context.file, {
+const addStdioNode = (context, spawn, child) => retainSemanticGraphNode(context.state, context.file, {
     kind: "stdio",
     roleKey: `stdio:${spawn.processId}`,
     location: spawn.location,
     label: spawn.stdioMode,
     functionNodeId: child.function_node_id,
     properties: { mode: spawn.stdioMode },
-}, context.state));
+});
 const projectInteraction = (context, interaction, processNodes) => {
     const children = interaction.linkedProcessIds.flatMap((identifier) => {
         const child = processNodes.get(identifier);
@@ -128,31 +127,31 @@ const projectInteraction = (context, interaction, processNodes) => {
             candidateNodeIds: children.map(({ node_id: identifier }) => identifier),
         });
 };
-const addChildListenerNode = (context, interaction) => addSemanticGraphNode(context.state, constructSemanticGraphNode(context.file, {
+const addChildListenerNode = (context, interaction) => retainSemanticGraphNode(context.state, context.file, {
     kind: "listener",
     roleKey: interaction.interactionId,
     location: interaction.listenerLocation ?? interaction.location,
     label: interaction.eventName,
     functionNodeId: interaction.ownerCallableId === null
         ? null
-        : (context.callableNodes.get(interaction.ownerCallableId)
-            ?.node_id ?? null),
+        : (context.callableNodes.get(interaction.ownerCallableId)?.node_id ??
+            null),
     properties: {
         event_name: interaction.eventName,
         method: interaction.method,
     },
-}, context.state));
-const addSignalNode = (context, interaction) => addSemanticGraphNode(context.state, constructSemanticGraphNode(context.file, {
+});
+const addSignalNode = (context, interaction) => retainSemanticGraphNode(context.state, context.file, {
     kind: "signal",
     roleKey: interaction.interactionId,
     location: interaction.location,
     label: interaction.signalName,
     functionNodeId: interaction.ownerCallableId === null
         ? null
-        : (context.callableNodes.get(interaction.ownerCallableId)
-            ?.node_id ?? null),
+        : (context.callableNodes.get(interaction.ownerCallableId)?.node_id ??
+            null),
     properties: { signal_name: interaction.signalName },
-}, context.state));
+});
 const addChildUnknown = (input) => {
     const { context, node, location, relationKinds, detail, candidateNodeIds } = input;
     addSemanticGraphUnknown(context.state, createJavaScriptSemanticGraphUnknown({

package/dist/application/{JavaScriptSemanticGraphConstruction.js → javascript/JavaScriptSemanticGraphConstruction.js}

@@ -1,4 +1,5 @@
-import { createJavaScriptSemanticGraphNode, createJavaScriptSemanticGraphRelation, } from "../domain/javascriptSemanticGraph.js";
+import { javascriptDisplayText } from "../../domain/javascript/javascriptAstValues.js";
+import { createJavaScriptSemanticGraphNode, createJavaScriptSemanticGraphRelation, javaScriptSemanticNodeId, } from "../../domain/javascript/javascriptSemanticGraph.js";
 import { inferredSemanticEvidence, observedSemanticEvidence, unavailableSemanticRootEvidence, } from "./JavaScriptSemanticGraphEvidence.js";
 /** Create empty projection state with structural application-node mappings. */
 export const createSemanticGraphProjectionState = (applicationGraph) => {
@@ -11,6 +12,18 @@ export const createSemanticGraphProjectionState = (applicationGraph) => {
         applicationNodeIdsByLocation: index.identifiers,
     };
 };
+/** Bind retained semantic identities after all application observations exist. */
+export const bindSemanticGraphApplicationNodes = (state, applicationGraph) => {
+    const index = indexApplicationNodes(applicationGraph.nodes).identifiers;
+    for (const [identifier, node] of state.nodes) {
+        state.nodes.set(identifier, {
+            ...node,
+            application_node_ids: [
+                ...(index.get(applicationLocationKey(node.identity.artifact_sha256, node.identity.module_path, node.identity.source_range)) ?? []),
+            ],
+        });
+    }
+};
 /** Construct one canonical semantic node backed by an exact artifact file. */
 export const constructSemanticGraphNode = (file, input, state) => createJavaScriptSemanticGraphNode({
     kind: input.kind,
@@ -22,15 +35,43 @@ export const constructSemanticGraphNode = (file, input, state) => createJavaScri
     },
     function_node_id: input.functionNodeId,
     application_node_ids: matchingApplicationNodeIds(file, input, state),
-    label: input.label,
+    label: input.label === null ? null : javascriptDisplayText(input.label),
     properties: input.properties ?? {},
     evidence: observedSemanticEvidence(file, input.location),
 });
+/** Reuse retained identities and reject exhausted budgets before allocation. */
+export const retainSemanticGraphNode = (state, file, input) => {
+    const identifier = javaScriptSemanticNodeId({
+        kind: input.kind,
+        identity: {
+            artifact_sha256: file.sha256,
+            module_path: file.path,
+            source_range: input.location,
+            role_key: input.roleKey,
+        },
+    });
+    const existing = state.nodes.get(identifier);
+    if (existing !== undefined)
+        return existing;
+    if (typeof state.fileNodeBudget === "number" && state.fileNodeBudget <= 0) {
+        state.fileNodesDropped = true;
+        return null;
+    }
+    return addSemanticGraphNode(state, constructSemanticGraphNode(file, input, state));
+};
 /** Retain one canonical semantic node. */
 export const addSemanticGraphNode = (state, node) => {
     const existing = state.nodes.get(node.node_id);
     if (existing !== undefined)
         return existing;
+    const budget = state.fileNodeBudget;
+    if (typeof budget === "number") {
+        if (budget <= 0) {
+            state.fileNodesDropped = true;
+            return null;
+        }
+        state.fileNodeBudget = budget - 1;
+    }
     state.nodes.set(node.node_id, node);
     return node;
 };

package/dist/application/{JavaScriptSemanticGraphDataProjection.js → javascript/JavaScriptSemanticGraphDataProjection.js}

@@ -1,5 +1,5 @@
-import { createJavaScriptSemanticGraphUnknown } from "../domain/javascriptSemanticGraph.js";
-import { addSemanticGraphNode, addSemanticGraphRelation, addSemanticGraphUnknown, constructSemanticGraphNode, } from "./JavaScriptSemanticGraphConstruction.js";
+import { createJavaScriptSemanticGraphUnknown } from "../../domain/javascript/javascriptSemanticGraph.js";
+import { retainSemanticGraphNode, addSemanticGraphRelation, addSemanticGraphUnknown, } from "./JavaScriptSemanticGraphConstruction.js";
 import { unknownSemanticEvidence } from "./JavaScriptSemanticGraphEvidence.js";
 import { semanticCallSiteAt, } from "./JavaScriptSemanticGraphFlowProjection.js";
 /** Project environment, argv, file, default, and precedence candidates. */
@@ -41,7 +41,7 @@ export const projectSemanticConfiguration = (context) => {
             });
     }
 };
-const addConfigurationNode = (context, operation) => addSemanticGraphNode(context.state, constructSemanticGraphNode(context.file, {
+const addConfigurationNode = (context, operation) => retainSemanticGraphNode(context.state, context.file, {
     kind: "config-source",
     roleKey: operation.configId,
     location: operation.location,
@@ -55,7 +55,7 @@ const addConfigurationNode = (context, operation) => addSemanticGraphNode(contex
         source_kind: operation.kind,
         value: operation.value,
     },
-}, context.state));
+});
 const configurationRelation = (operation) => operation.kind === "environment"
     ? "reads-environment"
     : operation.kind === "argv"
@@ -94,7 +94,7 @@ export const projectSemanticRequests = (context) => {
             });
     }
 };
-const addRequestNode = (context, operation) => addSemanticGraphNode(context.state, constructSemanticGraphNode(context.file, {
+const addRequestNode = (context, operation) => retainSemanticGraphNode(context.state, context.file, {
     kind: operation.kind === "request" ? "request" : "response",
     roleKey: operation.requestId,
     location: operation.location,
@@ -108,7 +108,7 @@ const addRequestNode = (context, operation) => addSemanticGraphNode(context.stat
         method: operation.method,
         operation_kind: operation.kind,
     },
-}, context.state));
+});
 const projectRequestConstruction = (context, operation, request) => {
     const callSite = semanticCallSiteAt(context, operation.location);
     addSemanticGraphRelation(context.state, {
@@ -182,7 +182,7 @@ export const projectSemanticBoundaries = (context) => {
             });
     }
 };
-const addBoundaryNode = (context, operation) => addSemanticGraphNode(context.state, constructSemanticGraphNode(context.file, {
+const addBoundaryNode = (context, operation) => retainSemanticGraphNode(context.state, context.file, {
     kind: "boundary",
     roleKey: operation.boundaryId,
     location: operation.location,
@@ -195,7 +195,7 @@ const addBoundaryNode = (context, operation) => addSemanticGraphNode(context.sta
         boundary_kind: operation.kind,
         method: operation.method,
     },
-}, context.state));
+});
 const bindingOrOwner = (context, bindingId, callableId) => (bindingId === null ? undefined : context.bindingNodes.get(bindingId)) ??
     (callableId === null
         ? context.moduleNode

package/dist/application/{JavaScriptSemanticGraphFingerprintProjection.js → javascript/JavaScriptSemanticGraphFingerprintProjection.js}

@@ -1,4 +1,4 @@
-import { createJavaScriptSemanticFingerprint, } from "../domain/javascriptSemanticGraph.js";
+import { createJavaScriptSemanticFingerprint, } from "../../domain/javascript/javascriptSemanticGraph.js";
 import { observedSemanticEvidence } from "./JavaScriptSemanticGraphEvidence.js";
 /** Bind domain fingerprint components to exact semantic function nodes. */
 export const projectSemanticFunctionFingerprints = (file, ir, callableNodes) => ir.functionFingerprints.flatMap((fingerprint) => {

package/dist/application/{JavaScriptSemanticGraphFlowProjection.js → javascript/JavaScriptSemanticGraphFlowProjection.js}

@@ -1,14 +1,10 @@
-import { createJavaScriptSemanticGraphUnknown } from "../domain/javascriptSemanticGraph.js";
-import { sourceRangesEqual } from "../domain/javascriptStaticAnalysisHelpers.js";
-import { addSemanticGraphNode, addSemanticGraphRelation, addSemanticGraphUnknown, constructSemanticGraphNode, } from "./JavaScriptSemanticGraphConstruction.js";
+import { createJavaScriptSemanticGraphUnknown } from "../../domain/javascript/javascriptSemanticGraph.js";
+import { sourceRangesEqual } from "../../domain/javascript/javascriptStaticAnalysisHelpers.js";
+import { retainSemanticGraphNode, addSemanticGraphRelation, addSemanticGraphUnknown, } from "./JavaScriptSemanticGraphConstruction.js";
 import { inferredSemanticEvidenceAt, unknownSemanticEvidence, } from "./JavaScriptSemanticGraphEvidence.js";
-import { semanticNodesWithinRange } from "./JavaScriptSemanticGraphProjection.js";
 /** Find the retained call-site node at one exact semantic source range. */
 export const semanticCallSiteAt = (context, location) => {
-    const call = context.ir.callSites.find(({ location: candidate }) => sourceRangesEqual(candidate, location));
-    return call === undefined
-        ? undefined
-        : context.callSiteNodes.get(call.callSiteId);
+    return context.callSiteAt(location);
 };
 /** Project explicit static Promise/task ownership without runtime claims. */
 export const projectSemanticPromises = (context) => {
@@ -16,7 +12,7 @@ export const projectSemanticPromises = (context) => {
         const owner = operation.ownerCallableId === null
             ? undefined
             : context.callableNodes.get(operation.ownerCallableId);
-        const node = addSemanticGraphNode(context.state, constructSemanticGraphNode(context.file, {
+        const node = retainSemanticGraphNode(context.state, context.file, {
             kind: operation.kind === "awaited-expression" ? "task" : "promise",
             roleKey: operation.promiseId,
             location: operation.location,
@@ -28,7 +24,7 @@ export const projectSemanticPromises = (context) => {
                 ownership: operation.ownership,
                 source_resolution: operation.sourceResolution,
             },
-        }, context.state));
+        });
         return node === null ? [] : [[operation.promiseId, node]];
     }));
     for (const operation of context.ir.promiseOperations) {
@@ -134,7 +130,7 @@ export const projectSemanticReturnValues = (context) => {
     for (const callable of context.ir.callables)
         for (const site of callable.returnSites) {
             const returnNode = context.returnSiteNodes.get(site.returnSiteId);
-            const references = semanticNodesWithinRange(context.referenceNodes, site.location);
+            const references = context.referenceNodesWithin(site.location);
             for (const reference of references)
                 addSemanticGraphRelation(context.state, {
                     source: reference,

package/dist/application/{JavaScriptSemanticGraphObjectProjection.js → javascript/JavaScriptSemanticGraphObjectProjection.js}

@@ -1,5 +1,5 @@
-import { createJavaScriptSemanticGraphUnknown } from "../domain/javascriptSemanticGraph.js";
-import { addSemanticGraphNode, addSemanticGraphRelation, addSemanticGraphUnknown, constructSemanticGraphNode, } from "./JavaScriptSemanticGraphConstruction.js";
+import { createJavaScriptSemanticGraphUnknown } from "../../domain/javascript/javascriptSemanticGraph.js";
+import { retainSemanticGraphNode, addSemanticGraphRelation, addSemanticGraphUnknown, } from "./JavaScriptSemanticGraphConstruction.js";
 import { unknownSemanticEvidence } from "./JavaScriptSemanticGraphEvidence.js";
 import { semanticPropertySlot } from "./JavaScriptSemanticGraphValueProjection.js";
 /** Project static object reads, writes, spreads, and destructuring. */
@@ -45,7 +45,7 @@ export const projectSemanticObjects = (context) => {
             addObjectUnknown(context, operation, slot ?? occurrence);
     }
 };
-const addObjectOccurrence = (context, operation) => addSemanticGraphNode(context.state, constructSemanticGraphNode(context.file, {
+const addObjectOccurrence = (context, operation) => retainSemanticGraphNode(context.state, context.file, {
     kind: "expression",
     roleKey: operation.objectOperationId,
     location: operation.location,
@@ -60,7 +60,7 @@ const addObjectOccurrence = (context, operation) => addSemanticGraphNode(context
         operation_kind: operation.kind,
         property_name: operation.propertyName,
     },
-}, context.state));
+});
 const addObjectUnknown = (context, operation, node) => {
     const relation = operation.kind === "read"
         ? "reads-property"