rea-agents 6.0.0 → 6.2.0

package/dist/application/javascript/JavaScriptArtifactPathResolution.js

@@ -1,6 +1,6 @@
 import { builtinModules } from "node:module";
 import { posix } from "node:path";
-import { admitsCanonicalPathSyntax, hasScheme, looksExternal, stripQueryAndFragment, } from "../../domain/artifactPathSyntax.js";
+import { admitsCanonicalPathSyntax, hasScheme, htmlUrlText, looksExternal, percentDecodeUrlPath, stripQueryAndFragment, } from "../../domain/artifactPathSyntax.js";
 const EXTENSIONS = [
     ".js",
     ".cjs",
@@ -32,12 +32,16 @@ const resolvePackagePath = (input, packageChain, mode = "full", exportsTargetUrl
                 `The exact HTML resource ${confined} was not found among the selected application files.`,
             ],
         });
-    const resolved = mode === "files-and-index"
-        ? (resolveFileCandidates(input, [
-            ...fileCandidates(confined),
-            ...indexCandidates(confined),
-        ]) ?? notFoundCandidate())
-        : resolveCandidate(input, confined, packageChain);
+    // An exports target names one exact file; Node tries no extension or index.
+    const resolved = exportsTargetUrl
+        ? (resolveFileCandidates(input, [confined]) ??
+            exactExportsTargetNotFound(confined))
+        : mode === "files-and-index"
+            ? (resolveFileCandidates(input, [
+                ...fileCandidates(confined),
+                ...indexCandidates(confined),
+            ]) ?? notFoundCandidate())
+            : resolveCandidate(input, confined, packageChain);
     return outcome(input, resolved);
 };
 const rejectDeclaration = (input) => {
@@ -148,7 +152,7 @@ const hasContainerCandidate = (files, candidate, containerSha256) => [
             file.container_sha256 === containerSha256));
 });
 const htmlCandidate = (input) => {
-    const declared = stripQueryAndFragment(input.declaredPath);
+    const declared = stripQueryAndFragment(htmlUrlText(input.declaredPath));
     if (looksExternal(declared))
         return unresolvedOutcome(input, "external", [
             "External HTML references are not mapped to local artifact assets.",
@@ -156,15 +160,26 @@ const htmlCandidate = (input) => {
     const rawBase = input.htmlBaseHref;
     const base = rawBase === undefined || rawBase === null
         ? rawBase
-        : stripQueryAndFragment(rawBase);
+        : stripQueryAndFragment(htmlUrlText(rawBase));
     if (base !== undefined && base !== null && looksExternal(base))
         return unresolvedOutcome(input, "external", [
             "The document base href is external, so its script reference is not a local artifact path.",
         ]);
-    if (declared.startsWith("/"))
-        return declared.slice(1);
+    // Removing URL tabs and newlines can join an encoded dot or separator that
+    // the raw declaration split, so admit the parsed URL text again.
+    if (!admitsCanonicalPathSyntax(declared))
+        return unresolvedOutcome(input, "rejected", [
+            "Encoded dot or separator bytes are rejected before artifact path resolution.",
+        ]);
+    const declaredPath = percentDecodeUrlPath(declared);
+    if (declaredPath === null)
+        return unresolvedOutcome(input, "rejected", [
+            "The HTML reference path percent-decodes to NUL or to bytes that are not UTF-8.",
+        ]);
+    if (declaredPath.startsWith("/"))
+        return declaredPath.slice(1);
     if (base === undefined || base === null || base === "")
-        return posix.join(posix.dirname(input.sourcePath), declared);
+        return posix.join(posix.dirname(input.sourcePath), declaredPath);
     // A local base href is a second untrusted path input; apply the same
     // admission rules a declared path gets so it cannot smuggle traversal or
     // separator syntax past canonicalization.
@@ -172,10 +187,15 @@ const htmlCandidate = (input) => {
         return unresolvedOutcome(input, "rejected", [
             "The document base href uses NUL, backslash, or encoded dot and separator bytes that are not admitted for canonical artifact paths.",
         ]);
-    const basePath = base.startsWith("/")
-        ? base.slice(1)
-        : posix.join(posix.dirname(input.sourcePath), base);
-    return posix.join(htmlBaseDirectory(base, basePath), declared);
+    const decodedBase = percentDecodeUrlPath(base);
+    if (decodedBase === null)
+        return unresolvedOutcome(input, "rejected", [
+            "The document base href path percent-decodes to NUL or to bytes that are not UTF-8.",
+        ]);
+    const basePath = decodedBase.startsWith("/")
+        ? decodedBase.slice(1)
+        : posix.join(posix.dirname(input.sourcePath), decodedBase);
+    return posix.join(htmlBaseDirectory(decodedBase, basePath), declaredPath);
 };
 /**
  * The directory a relative HTML reference resolves against. A base path
@@ -315,9 +335,12 @@ const packageEntry = (text, moduleKind, useExports) => {
                 ? { ...exported, source: "exports" }
                 : exported;
         }
-        const preferred = moduleKind === "import"
-            ? [Reflect.get(value, "module"), Reflect.get(value, "main")]
-            : [Reflect.get(value, "main"), Reflect.get(value, "module")];
+        // Node imports and requires ignore the bundler-only module field. Keep
+        // that fallback for callers without an explicit module-loading kind.
+        const preferred = [
+            Reflect.get(value, "main"),
+            ...(moduleKind === undefined ? [Reflect.get(value, "module")] : []),
+        ];
         const entry = preferred.find((candidate) => candidate !== undefined);
         if (entry === undefined)
             return { status: "missing" };
@@ -428,6 +451,13 @@ const notFoundCandidate = () => ({
         "No extension, directory package, or index candidate exists in the inventoried artifact container.",
     ],
 });
+const exactExportsTargetNotFound = (path) => ({
+    resolvedPath: null,
+    status: "not-found",
+    limitations: [
+        `The selected package exports target ${path} does not exist in the inventoried artifact container; exports targets are exact files, so no extension or directory index was tried.`,
+    ],
+});
 const fileUrlPath = (value) => {
     if (!value.startsWith("file://"))
         return undefined;

package/dist/application/javascript/JavaScriptArtifactReconstruction.js

@@ -1,21 +1,25 @@
-import { lstat, realpath } from "node:fs/promises";
+import { constants } from "node:fs";
+import { access, lstat, realpath } from "node:fs/promises";
 import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
+import { AnalysisAccessDeniedError, AnalysisInputError, AnalysisUnsupportedTargetError, } from "../../domain/analysisErrorCore.js";
 import { createJavaScriptArtifactReader as createReader } from "../../artifacts/javascript/JavaScriptArtifactReader.js";
 import { analyzeAndProjectJavaScriptArtifactFiles } from "./JavaScriptArtifactAnalysis.js";
 import { readJavaScriptArtifactFiles } from "../../artifacts/javascript/JavaScriptArtifactFiles.js";
-import { buildJavaScriptArtifactGraph } from "./JavaScriptArtifactGraphBuilder.js";
+import { buildImmutableJavaScriptArtifactGraphSteps } from "./JavaScriptArtifactGraphBuilder.js";
 import { javascriptArtifactReconstructionInputSchema, } from "./JavaScriptArtifactReconstructionInput.js";
-import { scanCanonicalArtifactInventory } from "../../artifacts/inventory/ArtifactInventory.js";
+import { scanCanonicalArtifactInventory } from "../../artifacts/inventory/scanCanonical.js";
 import { summarizeElectronBoundaries } from "./ElectronBoundaryAnalysis.js";
 import { createJavaScriptSemanticGraphProjection } from "./JavaScriptSemanticGraphBuilder.js";
+import { checkpointJavaScriptAnalysis, completeJavaScriptAnalysisSteps, } from "./JavaScriptAnalysisControl.js";
 /** Reconstruct one local ASAR or extracted directory without executing code. */
 export const reconstructJavaScriptArtifact = async (rawInput, signal, progress) => {
     const reportPhase = async (phase, message) => {
         await progress?.report({ phase, completed: 0, total: 1, message });
+        await checkpointJavaScriptAnalysis(signal);
     };
     const input = javascriptArtifactReconstructionInputSchema.parse(rawInput);
     abortIfNeeded(signal);
-    const path = await realpath(input.input_path);
+    const path = await resolveSelectedInput(input.input_path);
     const format = await resolveFormat(path, input);
     const snapshot = await scanCanonicalArtifactInventory(path, { signal });
     if (snapshot.manifest.root_format !== format)
@@ -36,11 +40,17 @@ export const reconstructJavaScriptArtifact = async (rawInput, signal, progress)
             });
             abortIfNeeded(signal);
         });
+        await checkpointJavaScriptAnalysis(signal);
         abortIfNeeded(signal);
         await reportPhase("build_javascript_application_graph", "Constructing application and Electron boundary relationships");
-        const graph = buildJavaScriptArtifactGraph(snapshot, files, analysis);
+        const applicationGraphSteps = buildImmutableJavaScriptArtifactGraphSteps(snapshot, files, analysis);
+        await reportPhase("seal_javascript_application_graph", "Sealing the validated application graph");
+        const graph = await completeJavaScriptAnalysisSteps(applicationGraphSteps, signal);
         await reportPhase("build_javascript_semantic_graph", "Binding and validating static semantic relationships");
-        const semanticGraph = semanticProjection.finish(snapshot.manifest.root_sha256, graph, analysis);
+        const semanticGraphSteps = semanticProjection.finishImmutableSteps(snapshot.manifest.root_sha256, graph, analysis);
+        await reportPhase("seal_javascript_semantic_graph", "Validating and sealing the semantic graph");
+        const semanticGraph = await completeJavaScriptAnalysisSteps(semanticGraphSteps, signal);
+        await checkpointJavaScriptAnalysis(signal);
         return {
             input_path: path,
             format,
@@ -69,6 +79,35 @@ export const reconstructJavaScriptArtifact = async (rawInput, signal, progress)
         await reader.close();
     }
 };
+const OPERATION = "analyze_javascript_application";
+/**
+ * Resolve the caller-selected input. A missing or unreadable selection is a
+ * caller or host-permission failure, not a damaged artifact.
+ */
+const resolveSelectedInput = async (inputPath) => {
+    try {
+        const path = await realpath(inputPath);
+        await access(path, constants.R_OK);
+        return path;
+    }
+    catch (cause) {
+        const code = cause instanceof Error && "code" in cause ? String(cause.code) : "";
+        if (code === "EACCES" || code === "EPERM")
+            throw new AnalysisAccessDeniedError(OPERATION, inputPath, code, {
+                cause,
+            });
+        if (code === "ENOENT" || code === "ENOTDIR")
+            throw new AnalysisInputError(OPERATION, { cause }, [
+                {
+                    path: ["input_path"],
+                    reason: "invalid_value",
+                    message: `No file or directory exists at the selected input path (${code}): ${inputPath}`,
+                },
+            ]);
+        throw cause;
+    }
+};
+/** The selected input's kind, checked against the caller's requested format. */
 const resolveFormat = async (path, input) => {
     const metadata = await lstat(path);
     const observed = metadata.isDirectory()
@@ -77,9 +116,18 @@ const resolveFormat = async (path, input) => {
             ? "asar"
             : undefined;
     if (observed === undefined)
-        throw new ArtifactReaderFailure("format", `JavaScript artifact reconstruction accepts only a directory or .asar file: ${path}`);
+        throw new AnalysisUnsupportedTargetError(OPERATION, input.input_path, "JavaScript application analysis accepts only a directory or an .asar file", {
+            remediationAction: "Select an extracted application directory, an app bundle, or an .asar file such as Contents/Resources/app.asar.",
+        });
     if (input.format !== "auto" && input.format !== observed)
-        throw new ArtifactReaderFailure("format", `Requested ${input.format} input but observed ${observed}: ${path}`);
+        throw new AnalysisInputError(OPERATION, undefined, [
+            {
+                path: ["format"],
+                reason: "invalid_value",
+                message: `Requested ${input.format} input, but the selected input is ${observed === "asar" ? "an .asar file" : "a directory"}: ${input.input_path}`,
+                expected: ["auto", observed],
+            },
+        ]);
     return observed;
 };
 const abortIfNeeded = (signal) => {

package/dist/application/javascript/JavaScriptModuleRelationships.js

@@ -1,10 +1,12 @@
 import { posix } from "node:path";
 import { compareCodePoints } from "../../domain/canonicalOrdering.js";
 import { completeApplicationCoverage, partialApplicationCoverage, } from "../../domain/javascript/javascriptApplicationEvidenceSchemas.js";
+import { semanticCoverageResourceLimits } from "../../domain/javascript/javascriptSemanticCoverage.js";
+import { SEMANTIC_EXPRESSION_DEPTH_LIMIT, SEMANTIC_PRIMITIVE_CANDIDATE_LIMIT, SEMANTIC_PRIMITIVE_JSON_BYTES_LIMIT, semanticResourceLimitReason, } from "../../domain/javascript/javascriptSemanticResourceLimits.js";
 import { addAstContainsEdge, artifactLocalIdentity, } from "./JavaScriptArtifactGraphContext.js";
 import { astObservationEvidence, staticInferenceEvidence, } from "./JavaScriptArtifactGraphEvidence.js";
 import { resolveArtifactPathByContext, } from "./JavaScriptArtifactPathResolution.js";
-import { projectJavaScriptExportReturnShapes } from "./JavaScriptReturnShapeProjection.js";
+import { projectJavaScriptExportReturnShapes } from "../../domain/javascript/javascriptExportReturnShapeProjection.js";
 /** Create one path-scoped source-module identity for every analyzed source file. */
 export const addJavaScriptSourceModules = (context) => {
     for (const analyzed of context.analysis.files) {
@@ -58,6 +60,7 @@ export const addJavaScriptSourceModules = (context) => {
 };
 /** Compose bounded CommonJS and ESM binding relationships across artifact files. */
 export const addJavaScriptModuleRelationships = (context) => {
+    const omissions = { selfImports: 0 };
     for (const analyzed of context.analysis.files) {
         const { file, semantic } = analyzed;
         const source = context.sourceModuleNodes.get(file.path);
@@ -66,16 +69,17 @@ export const addJavaScriptModuleRelationships = (context) => {
         for (const link of semantic.ir.moduleLinks) {
             const input = { context, file, semantic, source, link };
             if (isExportLink(link))
-                addExportRelationship(input);
+                addExportRelationship(input, omissions);
             else if (link.specifier !== null)
-                addImportRelationship(input, source, {
+                addImportRelationship(input, source, omissions, {
                     specifier: link.specifier,
                     importedPath: link.importedName === null ? [] : [link.importedName],
                 });
         }
     }
+    return omissions;
 };
-const addExportRelationship = (input) => {
+const addExportRelationship = (input, omissions) => {
     const { context, file, semantic, source, link } = input;
     if (link.exportedName === null)
         return;
@@ -137,10 +141,18 @@ const addExportRelationship = (input) => {
     });
     const origin = moduleOriginForExport(semantic.ir, link);
     if (origin !== null)
-        addImportRelationship(input, exported, origin);
+        addImportRelationship(input, exported, omissions, origin);
 };
-const addImportRelationship = (input, source, origin) => {
+const addImportRelationship = (input, source, omissions, origin) => {
     const target = resolveModuleTarget(input, origin.specifier);
+    // A specifier that resolves back to the importing module itself (a literal
+    // self-import, self-require, or artifact-confined path alias)
+    // cannot become an edge: the application graph forbids self-referential
+    // edges, and emitting one fails result validation for the whole analysis.
+    if (target.node.node_id === source.node_id) {
+        omissions.selfImports += 1;
+        return;
+    }
     input.context.accumulator.addEdge({
         source_node_id: source.node_id,
         target_node_id: target.node.node_id,
@@ -242,12 +254,29 @@ const relationshipEvidence = (input, operation, limitations, confidence = "high"
     operation,
     coverage: semanticCoverage(input.semantic),
     confidence,
-    limitations: [...input.semantic.ir.limitations, ...limitations],
+    limitations: [
+        ...input.semantic.ir.limitations,
+        ...semanticCoverageResourceLimits(input.semantic.ir.coverage).map(semanticResourceLimitReason),
+        ...limitations,
+    ],
 });
 const semanticCoverage = (semantic) => {
-    if (semantic.ir.coverage.status === "complete")
+    const resourceLimits = semanticCoverageResourceLimits(semantic.ir.coverage);
+    if (semantic.ir.coverage.status === "complete" && resourceLimits.length === 0)
         return completeApplicationCoverage();
-    return partialApplicationCoverage([], semantic.ir.coverage.omittedCount);
+    return partialApplicationCoverage(resourceLimits.map((resourceLimit) => ({
+        name: `javascript_semantic_${resourceLimit.replaceAll("-", "_")}`,
+        value: resourceLimit === "primitive-candidates"
+            ? SEMANTIC_PRIMITIVE_CANDIDATE_LIMIT
+            : resourceLimit === "primitive-bytes"
+                ? SEMANTIC_PRIMITIVE_JSON_BYTES_LIMIT
+                : SEMANTIC_EXPRESSION_DEPTH_LIMIT,
+        unit: resourceLimit === "expression-depth"
+            ? "depth"
+            : resourceLimit === "primitive-bytes"
+                ? "bytes"
+                : "items",
+    })), semantic.ir.coverage.omittedCount);
 };
 const moduleFormat = (path, ir) => {
     const extension = posix.extname(path).toLowerCase();

package/dist/application/javascript/JavaScriptRecoveryService.js

@@ -3,7 +3,7 @@ import { AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, } from
 import { createEvidence } from "../../domain/evidence.js";
 import { javascriptRecoveryInputSchema, javascriptRecoveryResultSchema, } from "../../domain/javascript/javascriptRecovery.js";
 import { jsonObjectSchema } from "../../domain/jsonValue.js";
-import { projectInputIssues } from "../../domain/inputIssueProjection.js";
+import { analysisInputErrorFromIssues } from "../../domain/inputIssueProjection.js";
 import { err, ok } from "../../domain/result.js";
 const OPERATION = "recover_javascript_sources";
 /** Shared CLI/MCP parsing and Evidence for derived JavaScript artifacts. */
@@ -18,7 +18,9 @@ export class JavaScriptRecoveryService {
             return err(new AnalysisCancelledError(OPERATION));
         const parsed = javascriptRecoveryInputSchema.safeParse(input);
         if (!parsed.success)
-            return err(new AnalysisInputError(OPERATION, { cause: parsed.error }, projectInputIssues(parsed.error.issues, input)));
+            return err(analysisInputErrorFromIssues(OPERATION, parsed.error.issues, input, {
+                cause: parsed.error,
+            }));
         const invalidPaths = ["path", "output_directory"].filter((field) => !isAbsolute(parsed.data[field]));
         if (invalidPaths.length > 0)
             return err(new AnalysisInputError(OPERATION, undefined, invalidPaths.map((field) => ({

package/dist/application/javascript/JavaScriptRuntimeObservationService.js

@@ -1,5 +1,5 @@
 import { createJavaScriptRuntimeObservationEvidence } from "./JavaScriptRuntimeObservationEvidence.js";
-import { AnalysisCapabilityUnavailableError } from "../../domain/analysisErrorCore.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, } from "../../domain/analysisErrorCore.js";
 import {} from "../../domain/analysisErrorBase.js";
 import { err, ok } from "../../domain/result.js";
 /** List targets exposed by the explicitly selected loopback Inspector. */
@@ -18,9 +18,11 @@ export const observeJavaScriptRuntime = async (provider, input, options = {}) =>
     if (!ready.ok)
         return ready;
     const result = await ready.value.observe(input, options);
-    return result.ok
-        ? ok(createJavaScriptRuntimeObservationEvidence("observe_javascript_runtime", input, result.value, ready.value.identity()))
-        : result;
+    if (!result.ok)
+        return result;
+    if (options.signal?.aborted === true)
+        return err(new AnalysisCancelledError("observe_javascript_runtime"));
+    return ok(createJavaScriptRuntimeObservationEvidence("observe_javascript_runtime", input, result.value, ready.value.identity()));
 };
 const requireProvider = (provider, operation) => provider === undefined
     ? err(new AnalysisCapabilityUnavailableError("rea-v8-inspector", operation, "V8 Inspector observation provider is not configured"))

package/dist/application/javascript/JavaScriptRuntimeReconciliationService.js

@@ -2,7 +2,7 @@ import { resolve } from "node:path";
 import { z } from "zod";
 import { AnalysisInputError, AnalysisProtocolError, } from "../../domain/analysisErrorCore.js";
 import {} from "../../domain/analysisErrorBase.js";
-import { projectInputIssues } from "../../domain/inputIssueProjection.js";
+import { analysisInputErrorFromIssues } from "../../domain/inputIssueProjection.js";
 import { reconcileJavaScriptRuntime } from "../../domain/javascript/javascriptRuntimeReconciliation.js";
 import { reconcileJavaScriptRuntimeInputSchema } from "../../domain/javascript/javascriptRuntimeReconciliationSchemas.js";
 import { err, ok } from "../../domain/result.js";
@@ -12,7 +12,7 @@ const OPERATION = "reconcile_javascript_runtime";
 export const reconcileJavaScriptRuntimeEvidence = (rawInput) => {
     const parsed = reconcileJavaScriptRuntimeInputSchema.safeParse(rawInput);
     if (!parsed.success)
-        return err(new AnalysisInputError(OPERATION, undefined, projectInputIssues(parsed.error.issues, rawInput)));
+        return err(analysisInputErrorFromIssues(OPERATION, parsed.error.issues, rawInput));
     return reconcileJavaScriptRuntimeEvidenceValidated(parsed.data);
 };
 /** Reconcile input already parsed by a trusted adapter boundary. */
@@ -24,7 +24,7 @@ export const reconcileJavaScriptRuntimeEvidenceValidated = (parsedInput) => {
     }
     catch (cause) {
         if (cause instanceof z.ZodError)
-            return err(new AnalysisInputError(OPERATION, undefined, projectInputIssues(cause.issues, parsedInput)));
+            return err(analysisInputErrorFromIssues(OPERATION, cause.issues, parsedInput));
         if (cause instanceof TypeError &&
             SAFE_RECONCILIATION_INPUT_CONSTRAINTS.has(cause.message))
             return err(new AnalysisInputError(OPERATION, undefined, [

package/dist/application/javascript/JavaScriptSemanticGraphAsyncProjection.js

@@ -1,7 +1,6 @@
 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 literal EventEmitter registrations, removals, and dispatches. */
 export const projectSemanticEvents = (context) => {
     const eventNodes = new Map();
@@ -116,7 +115,7 @@ export const projectSemanticTimers = (context) => {
 };
 const projectTimerSchedule = (context, operation, timerNodes) => {
     addSemanticGraphRelation(context.state, {
-        source: semanticCallSiteAt(context, operation.location),
+        source: context.callSiteAt(operation.location),
         target: timerNodes.get(operation.timerId),
         relation: "schedules-timer",
         resolution: "resolved",
@@ -134,7 +133,7 @@ const projectTimerSchedule = (context, operation, timerNodes) => {
         });
 };
 const projectTimerCancellation = (context, operation, timerNodes) => {
-    const callSite = semanticCallSiteAt(context, operation.location);
+    const callSite = context.callSiteAt(operation.location);
     const target = operation.linkedTimerId === null
         ? undefined
         : timerNodes.get(operation.linkedTimerId);

package/dist/application/javascript/JavaScriptSemanticGraphBuilder.js

@@ -1,4 +1,4 @@
-import { createJavaScriptSemanticGraph, } from "../../domain/javascript/javascriptSemanticGraph.js";
+import { createJavaScriptSemanticGraph, createImmutableJavaScriptSemanticGraphSteps, } 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";
@@ -68,68 +68,70 @@ export const createJavaScriptSemanticGraphProjection = () => {
             truncatedFiles += 1;
         state.fileNodeBudget = null;
     };
+    const finishWith = (factory, rootArtifactSha256, applicationGraph, analysis) => {
+        bindSemanticGraphApplicationNodes(state, applicationGraph);
+        if (state.roots.size === 0)
+            addFallbackRoot(rootArtifactSha256, state);
+        const unknowns = [...state.unknowns.values()];
+        const graph = factory({
+            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;
+    };
     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;
-        },
+        finish: (rootArtifactSha256, applicationGraph, analysis) => finishWith(createJavaScriptSemanticGraph, rootArtifactSha256, applicationGraph, analysis),
+        finishImmutableSteps: (rootArtifactSha256, applicationGraph, analysis) => finishWith(createImmutableJavaScriptSemanticGraphSteps, rootArtifactSha256, applicationGraph, analysis),
     };
 };
 const projectFile = (file, ir, state) => {

package/dist/application/javascript/JavaScriptSemanticGraphChildProcessProjection.js

@@ -1,7 +1,6 @@
 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. */
 export const projectSemanticChildProcesses = (context) => {
     const processNodes = new Map(context.ir.childProcessSpawns.flatMap((spawn) => {
@@ -34,7 +33,7 @@ const addChildProcessNode = (context, spawn) => retainSemanticGraphNode(context.
     },
 });
 const projectSpawn = (context, spawn, child) => {
-    const callSite = semanticCallSiteAt(context, spawn.location);
+    const callSite = context.callSiteAt(spawn.location);
     addSemanticGraphRelation(context.state, {
         source: callSite,
         target: child,

package/dist/application/javascript/JavaScriptSemanticGraphDataProjection.js

@@ -1,7 +1,6 @@
 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. */
 export const projectSemanticConfiguration = (context) => {
     const configNodes = new Map(context.ir.configurationOperations.flatMap((operation) => {
@@ -110,7 +109,7 @@ const addRequestNode = (context, operation) => retainSemanticGraphNode(context.s
     },
 });
 const projectRequestConstruction = (context, operation, request) => {
-    const callSite = semanticCallSiteAt(context, operation.location);
+    const callSite = context.callSiteAt(operation.location);
     addSemanticGraphRelation(context.state, {
         source: callSite,
         target: request,
@@ -142,7 +141,7 @@ const projectRequestConstruction = (context, operation, request) => {
 const projectResponseConsumer = (context, operation, response) => {
     addSemanticGraphRelation(context.state, {
         source: response,
-        target: semanticCallSiteAt(context, operation.location),
+        target: context.callSiteAt(operation.location),
         relation: "consumed-by",
         resolution: operation.resolution === "complete" ? "resolved" : "candidate",
         properties: { method: operation.method },

package/dist/application/javascript/JavaScriptSemanticGraphFlowProjection.js

@@ -2,10 +2,6 @@ import { createJavaScriptSemanticGraphUnknown } from "../../domain/javascript/ja
 import { sourceRangesEqual } from "../../domain/javascript/javascriptStaticAnalysisHelpers.js";
 import { retainSemanticGraphNode, addSemanticGraphRelation, addSemanticGraphUnknown, } from "./JavaScriptSemanticGraphConstruction.js";
 import { inferredSemanticEvidenceAt, unknownSemanticEvidence, } from "./JavaScriptSemanticGraphEvidence.js";
-/** Find the retained call-site node at one exact semantic source range. */
-export const semanticCallSiteAt = (context, location) => {
-    return context.callSiteAt(location);
-};
 /** Project explicit static Promise/task ownership without runtime claims. */
 export const projectSemanticPromises = (context) => {
     const promiseNodes = new Map(context.ir.promiseOperations.flatMap((operation) => {
@@ -46,7 +42,7 @@ const projectPromiseCreation = (context, operation, promise) => {
     if (operation.kind === "awaited-expression")
         return;
     addSemanticGraphRelation(context.state, {
-        source: semanticCallSiteAt(context, operation.location),
+        source: context.callSiteAt(operation.location),
         target: promise,
         relation: "creates-promise",
         resolution: operation.kind === "chain" || operation.sourceResolution !== "complete"