fix(javascript): isolate source analysis and retain bounded partial evidence (#1651)

* refactor(javascript): validate transferable file projections

* test(javascript): consume decoded module and static facts

* fix(javascript): isolate source analysis and retain bounded partial evidence

* test(javascript): verify cleanup retention and repeated source paths

src/application/javascript/JavaScriptSemanticGraphBuilder.ts

@@ -1,5 +1,6 @@
 import {
   createJavaScriptSemanticGraph,
+  createJavaScriptSemanticGraphUnknown,
   sealTransferredJavaScriptSemanticGraphSteps,
   type JavaScriptSemanticGraph,
 } from "../../domain/javascript/javascriptSemanticGraph.js";
@@ -10,6 +11,7 @@ import type {
 import {
   JAVASCRIPT_SEMANTIC_RELATION_FAMILIES,
   JAVASCRIPT_SEMANTIC_RELATION_FAMILY,
+  JAVASCRIPT_SEMANTIC_RELATIONS,
 } from "../../domain/javascript/javascriptSemanticGraphSchemas.js";
 import type {
   JavaScriptSemanticCallArgument,
@@ -33,6 +35,13 @@ import { projectSemanticResources } from "./JavaScriptSemanticGraphResourceProje
 import { projectSemanticObjects } from "./JavaScriptSemanticGraphObjectProjection.js";
 import { projectSemanticValues } from "./JavaScriptSemanticGraphValueProjection.js";
 import { inferredSemanticEvidenceAt } from "./JavaScriptSemanticGraphEvidence.js";
+import { observedSemanticEvidence } from "./JavaScriptSemanticGraphEvidence.js";
+import {
+  partialApplicationCoverage,
+  type ApplicationCoverage,
+} from "../../domain/javascript/javascriptApplicationEvidenceSchemas.js";
+import type { JsonValue } from "../../domain/jsonValue.js";
+import { javaScriptAnalysisCoverageLimits } from "../../domain/javascript/javascriptAnalysisResourceControls.js";
 import { projectSemanticFunctionFingerprints } from "./JavaScriptSemanticGraphFingerprintProjection.js";
 import {
   projectSemanticClosureCaptures,
@@ -55,6 +64,7 @@ import {
   bindSemanticGraphApplicationNodes,
   type SemanticGraphProjectionState as BuilderState,
 } from "./JavaScriptSemanticGraphConstruction.js";
+import type { JavaScriptSemanticFileProjection } from "../../domain/javascript/javascriptSemanticFileProjection.js";
 
 interface BuilderInput {
   readonly rootArtifactSha256: string;
@@ -126,6 +136,19 @@ export const buildJavaScriptSemanticGraph = ({
 
 /** File-local semantic projection that does not retain consumed source IR. */
 export interface JavaScriptSemanticGraphProjection {
+  /** Node capacity offered to the next independently analyzed source file. */
+  readonly remainingFileNodeBudget: () => number;
+  /** Adopt decoded file-local facts; final validation and proof remain in this realm. */
+  readonly adoptFileProjection: (
+    projection: JavaScriptSemanticFileProjection,
+  ) => void;
+  /** Preserve source-bound unknowns for an execution or result-retention failure. */
+  readonly recordUnavailableFile: (
+    file: JavaScriptArtifactFile,
+    reason: string,
+    limits: Readonly<Record<string, JsonValue>> | null,
+    unknownReason: "resource-limit" | "incomplete-module",
+  ) => void;
   readonly projectFile: (
     file: JavaScriptArtifactFile,
     ir: JavaScriptSemanticIr,
@@ -151,6 +174,12 @@ export const createJavaScriptSemanticGraphProjection =
     const state = emptyState();
     const fingerprints: JavaScriptSemanticFingerprint[] = [];
     let truncatedFiles = 0;
+    let unavailableFiles = 0;
+    let resourceTruncatedFiles = 0;
+    const executionLimits = new Map<
+      string,
+      ApplicationCoverage["limits"][number]
+    >();
     const projectSourceSteps = function* (
       file: JavaScriptArtifactFile,
       ir: JavaScriptSemanticIr,
@@ -207,12 +236,15 @@ export const createJavaScriptSemanticGraphProjection =
         fingerprints: [...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
+          status:
+            truncatedFiles > 0 || unavailableFiles > 0 ? "partial" : "unknown",
+          truncated: truncatedFiles > 0 || resourceTruncatedFiles > 0,
+          omitted_nodes: truncatedFiles > 0 || unavailableFiles > 0 ? null : 0,
+          omitted_relations:
+            truncatedFiles > 0 || unavailableFiles > 0 ? null : 0,
+          limits: [
+            ...executionLimits.values(),
+            ...(truncatedFiles > 0
               ? [
                   {
                     name: "semantic_graph_node_ceiling",
@@ -220,12 +252,14 @@ export const createJavaScriptSemanticGraphProjection =
                     unit: "items" as const,
                   },
                 ]
-              : [],
+              : []),
+          ],
           families: JAVASCRIPT_SEMANTIC_RELATION_FAMILIES.map((family) => ({
             family,
             status: semanticFamilyStatus(family),
             retained_relations: retainedByFamily.get(family) ?? 0,
-            omitted_relations: truncatedFiles > 0 ? null : 0,
+            omitted_relations:
+              truncatedFiles > 0 || unavailableFiles > 0 ? null : 0,
             unknown_ids: unknownIdsByFamily.get(family) ?? [],
           })),
         },
@@ -252,6 +286,87 @@ export const createJavaScriptSemanticGraphProjection =
       return graph;
     };
     return {
+      remainingFileNodeBudget: () =>
+        Math.min(
+          SEMANTIC_GRAPH_FILE_NODE_CEILING,
+          Math.max(0, SEMANTIC_GRAPH_NODE_CEILING - state.nodes.size),
+        ),
+      adoptFileProjection: (projection) => {
+        const newNodes = projection.nodes.filter(
+          ({ node_id }) => !state.nodes.has(node_id),
+        );
+        if (
+          newNodes.length >
+          Math.min(
+            SEMANTIC_GRAPH_FILE_NODE_CEILING,
+            SEMANTIC_GRAPH_NODE_CEILING - state.nodes.size,
+          )
+        )
+          throw new RangeError(
+            "Transferred semantic nodes exceed the offered tree capacity",
+          );
+        for (const context of projection.evidenceContexts)
+          state.evidenceContexts.adopt(context);
+        for (const node of newNodes) state.nodes.set(node.node_id, node);
+        for (const relation of projection.relations)
+          state.relations.set(relation.relation_id, relation);
+        for (const unknown of projection.unknowns)
+          state.unknowns.set(unknown.unknown_id, unknown);
+        for (const root of projection.roots) state.roots.add(root);
+        fingerprints.push(...projection.fingerprints);
+        if (projection.truncated) truncatedFiles += 1;
+      },
+      recordUnavailableFile: (file, reason, limits, unknownReason) => {
+        const retainedLimits = javaScriptAnalysisCoverageLimits(limits);
+        for (const limit of retainedLimits) {
+          executionLimits.set(
+            JSON.stringify([limit.name, limit.value, limit.unit]),
+            limit,
+          );
+        }
+        state.fileNodeBudget = Math.min(
+          SEMANTIC_GRAPH_FILE_NODE_CEILING,
+          Math.max(0, SEMANTIC_GRAPH_NODE_CEILING - state.nodes.size),
+        );
+        const module = retainNode(state, file, {
+          kind: "module",
+          roleKey: "module",
+          location: null,
+          label: file.path,
+          functionNodeId: null,
+        });
+        state.fileNodeBudget = null;
+        if (module !== null) state.roots.add(module.node_id);
+        const evidence = {
+          ...observedSemanticEvidence(file, null),
+          authority: "unknown" as const,
+          state: "unknown" as const,
+          confidence: "unknown" as const,
+          coverage: partialApplicationCoverage(retainedLimits, null),
+          limitations: [reason],
+        };
+        for (const family of JAVASCRIPT_SEMANTIC_RELATION_FAMILIES) {
+          const unknown = createJavaScriptSemanticGraphUnknown(
+            {
+              node_id: module?.node_id ?? null,
+              family,
+              relation_kinds: JAVASCRIPT_SEMANTIC_RELATIONS.filter(
+                (relation) =>
+                  JAVASCRIPT_SEMANTIC_RELATION_FAMILY[relation] === family,
+              ),
+              reason: unknownReason,
+              detail: reason,
+              candidate_node_ids: [],
+              evidence,
+            },
+            state.evidenceContexts,
+          );
+          state.unknowns.set(unknown.unknown_id, unknown);
+        }
+        unavailableFiles += 1;
+        if (unknownReason === "resource-limit" && retainedLimits.length > 0)
+          resourceTruncatedFiles += 1;
+      },
       projectFile: (file, ir) => {
         const steps = projectSourceSteps(file, ir);
         while (steps.next().done !== true);
@@ -272,6 +387,35 @@ export const createJavaScriptSemanticGraphProjection =
     };
   };
 
+/** Project one source with the parent's remaining node capacity, retaining no full IR. */
+export function* projectJavaScriptSemanticFileSteps(
+  file: JavaScriptArtifactFile,
+  ir: JavaScriptSemanticIr,
+  nodeBudget: number,
+): Generator<void, JavaScriptSemanticFileProjection> {
+  if (
+    !Number.isSafeInteger(nodeBudget) ||
+    nodeBudget < 0 ||
+    nodeBudget > SEMANTIC_GRAPH_FILE_NODE_CEILING
+  )
+    throw new RangeError(
+      "File semantic projection requires a valid offered node capacity",
+    );
+  const state = emptyState();
+  state.fileNodeBudget = nodeBudget;
+  state.fileNodesDropped = false;
+  const fingerprints = yield* projectFileSteps(file, ir, state);
+  return {
+    roots: [...state.roots],
+    evidenceContexts: state.evidenceContexts.contexts,
+    nodes: [...state.nodes.values()],
+    relations: [...state.relations.values()],
+    unknowns: [...state.unknowns.values()],
+    fingerprints,
+    truncated: Boolean(state.fileNodesDropped),
+  };
+}
+
 function* projectFileSteps(
   file: JavaScriptArtifactFile,
   ir: JavaScriptSemanticIr,