rea-agents 6.1.0 → 6.2.0

package/dist/application/homebrew.js

@@ -1,3 +1,6 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
 /** Standard executable names and locations used to discover Homebrew. */
 const HOMEBREW_COMMANDS = [
     "brew",
@@ -17,3 +20,48 @@ export const probeHomebrew = async (probe) => {
     }
     return undefined;
 };
+const caskDirectoriesSchema = z
+    .object({ appdir: z.string().min(1).optional() })
+    .loose();
+const caskConfigSchema = z
+    .object({
+    default: caskDirectoriesSchema.optional(),
+    env: caskDirectoriesSchema.optional(),
+    explicit: caskDirectoriesSchema.optional(),
+})
+    .loose();
+/**
+ * Read the application directory Homebrew recorded when it installed a cask,
+ * in Homebrew's precedence: explicit option, then environment, then default.
+ * Reading the Caskroom avoids `brew` cask commands, which refresh Homebrew's
+ * API and bootsnap caches.
+ */
+export const installedCaskAppdir = async (caskroom, token, home) => {
+    let text;
+    try {
+        text = await readFile(join(caskroom, token, ".metadata", "config.json"), "utf8");
+    }
+    catch (cause) {
+        // An absent or unreadable receipt means the cask is not installed here.
+        void cause;
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (cause) {
+        // A malformed receipt does not identify an application directory.
+        void cause;
+        return undefined;
+    }
+    const config = caskConfigSchema.safeParse(parsed);
+    if (!config.success)
+        return undefined;
+    const appdir = config.data.explicit?.appdir ??
+        config.data.env?.appdir ??
+        config.data.default?.appdir;
+    if (appdir === undefined)
+        return undefined;
+    return appdir.startsWith("~/") ? join(home, appdir.slice(2)) : appdir;
+};

package/dist/application/javascript/ElectronActiveEvidence.js

@@ -1,7 +1,7 @@
 import { canonicalDigest } from "../../domain/comparisonSemantics.js";
 import { createEvidence } from "../../domain/evidence.js";
-import { jsonValueSchema } from "../../domain/jsonValue.js";
-/** Create Evidence without retaining arbitrary runtime argument values. */
+import { jsonObjectSchema, jsonValueSchema } from "../../domain/jsonValue.js";
+/** Commit the selected Electron experiment and its observed result. */
 export const createElectronActiveEvidence = (input, result, provider) => createEvidence(undefined, provider, {
     predicateType: "rea.electron-active-scenario",
     operation: "capture_electron_scenario",
@@ -20,14 +20,10 @@ export const createElectronActiveEvidence = (input, result, provider) => createE
         "Application host platform and architecture were not observed.",
     ],
 });
-const scenarioProjection = (input) => ({
-    executable_path: input.executable_path,
-    application_path: input.application_path,
-    application_root: input.application_root,
-    args: [...input.args],
-    actions: input.actions.map(({ step_id, kind }) => ({ step_id, kind })),
-});
-const parameters = (input) => ({
-    ...scenarioProjection(input),
-    scenario_sha256: canonicalDigest(scenarioProjection(input), "Browser scenario"),
-});
+const parameters = (input) => {
+    const scenario = jsonObjectSchema.parse(input);
+    return {
+        ...scenario,
+        scenario_sha256: canonicalDigest(scenario, "Electron scenario"),
+    };
+};

package/dist/application/javascript/JavaScriptApplicationEvidence.js

@@ -1,11 +1,9 @@
-import { createEvidence, createImmutableEvidenceSteps, } from "../../domain/evidence.js";
+import { createImmutableEvidenceSteps, } from "../../domain/evidence.js";
 import { JAVASCRIPT_APPLICATION_PROVIDER } from "../InvestigationProviders.js";
-import { freezeJsonSnapshot, freezeOwnedJsonSnapshotSteps, } from "../../domain/immutableJson.js";
+import { freezeOwnedJsonSnapshotSteps } from "../../domain/immutableJson.js";
 import { rememberOwnedApplicationGraphEvidence } from "./JavaScriptApplicationEvidenceGraph.js";
 import { completeJavaScriptAnalysisSteps } from "./JavaScriptAnalysisControl.js";
 import { jsonValueValidationSteps } from "../../domain/jsonValue.js";
-/** Transfer an already validated, application-owned result into immutable analysis Evidence. */
-export const createOwnedJavaScriptApplicationEvidence = (input, result) => rememberOwnedApplicationGraphEvidence(createJavaScriptApplicationEvidence(input, freezeJsonSnapshot(result)), result);
 /** Create owned analysis Evidence while allowing request cancellation during sealing and hashing. */
 export const createOwnedJavaScriptApplicationEvidenceCooperatively = async (input, result, signal, progress) => {
     await reportEvidencePhase(progress, "seal_javascript_application_result", "Sealing the complete application analysis result");
@@ -19,8 +17,6 @@ export const createOwnedJavaScriptApplicationEvidenceCooperatively = async (inpu
 };
 const reportEvidencePhase = (progress, phase, message) => progress?.report({ phase, completed: 0, total: 1, message }) ??
     Promise.resolve();
-/** Create Evidence for one deterministic local JavaScript application graph. */
-export const createJavaScriptApplicationEvidence = (input, result) => createEvidence(applicationSubject(result), JAVASCRIPT_APPLICATION_PROVIDER, applicationObservation(input, result));
 const applicationSubject = (result) => ({
     path: result.input_path,
     sha256: result.root_artifact_sha256,

package/dist/application/javascript/JavaScriptApplicationService.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
 import { analyzeJavaScriptApplicationInputSchema, parseOwnedJavaScriptApplicationAnalysisSteps, } from "../../domain/javascript/javascriptApplicationAnalysis.js";
-import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";
+import { AnalysisAccessDeniedError, AnalysisInputError, AnalysisOutputError, AnalysisUnsupportedTargetError, } from "../../domain/analysisErrorCore.js";
 import { ArtifactOperationError } from "../../domain/artifactOperationError.js";
 import {} from "../../domain/analysisErrorBase.js";
 import { analysisInputErrorFromIssues } from "../../domain/inputIssueProjection.js";
@@ -67,6 +67,11 @@ export const analyzeJavaScriptApplicationValidated = async (input, options = {})
         return ok(evidence);
     }
     catch (cause) {
+        // Input selection failures are already typed by their cause.
+        if (cause instanceof AnalysisInputError ||
+            cause instanceof AnalysisUnsupportedTargetError ||
+            cause instanceof AnalysisAccessDeniedError)
+            return err(cause);
         if (cause instanceof ArtifactReaderFailure)
             return err(new ArtifactOperationError(OPERATION, cause.reason, cause.details, cause.message));
         if (cause instanceof z.ZodError)

package/dist/application/javascript/JavaScriptArtifactAnalysis.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { setImmediate } from "node:timers/promises";
+import { resolveJavaScriptSourceMapReference } from "../../domain/javascript/javascriptSourceMapPaths.js";
 import { analyzeParsedJavaScriptStaticSource } from "../../domain/javascript/javascriptStaticAnalysis.js";
 import { analyzeParsedJavaScriptSemantics, classifyParsedJavaScriptOpenReceivers, } from "../../domain/javascript/javascriptSemanticAnalysis.js";
 import { parseJavaScriptSource } from "../../domain/javascript/javascriptSourceParser.js";
@@ -203,14 +204,16 @@ const collectSourceMapOriginals = (file, maps) => {
         const contents = map.sourcesContent;
         if (!hasValidSourceMapContents(names.length, contents))
             return invalidSourceMap(file, "Source map sourcesContent must contain one string or null entry per source.");
-        const root = typeof map.sourceRoot === "string" ? map.sourceRoot : "";
+        if (map.sourceRoot != null && typeof map.sourceRoot !== "string")
+            return invalidSourceMap(file, "Source map sourceRoot must be a string or null.");
+        const root = typeof map.sourceRoot === "string" ? map.sourceRoot : null;
         for (const [index, raw] of names.entries()) {
             if (typeof raw !== "string")
                 return invalidSourceMap(file, "Source map contains a non-string source name.");
             const rawContent = Array.isArray(contents) ? contents[index] : undefined;
             const content = typeof rawContent === "string" ? rawContent : null;
             sources.push({
-                source: resolveSourceName(root, raw),
+                reference: resolveJavaScriptSourceMapReference(raw, root, file.path),
                 content,
                 content_sha256: content === null ? null : sha256(content),
             });
@@ -266,7 +269,6 @@ const pointForOffset = (text, offset) => {
     const lines = text.slice(0, offset).split(/\r\n|\r|\n/u);
     return { line: lines.length, column: lines.at(-1)?.length ?? 0 };
 };
-const resolveSourceName = (root, source) => `${root}${root !== "" && !root.endsWith("/") ? "/" : ""}${source}`;
 const optionalString = (value) => typeof value === "string" && value.length > 0 ? value : null;
 const sha256 = (value) => createHash("sha256").update(value).digest("hex");
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);

package/dist/application/javascript/JavaScriptArtifactGraphBuilder.js

@@ -1,12 +1,14 @@
 import { createJavaScriptApplicationGraph, createImmutableJavaScriptApplicationGraphSteps, } from "../../domain/javascript/javascriptApplicationGraph.js";
 import { JavaScriptArtifactGraphAccumulator } from "./JavaScriptArtifactGraphAccumulator.js";
+import { selfReferenceOmissions, } from "./JavaScriptArtifactGraphContext.js";
 import { addJavaScriptHtmlRoles, addJavaScriptSourceMapOriginals, } from "./JavaScriptArtifactGraphDocuments.js";
 import { addJavaScriptStaticFindings } from "./JavaScriptArtifactGraphFindings.js";
 import { addJavaScriptModuleRelationships, addJavaScriptSourceModules, } from "./JavaScriptModuleRelationships.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 { addJavaScriptArtifactContainers, addJavaScriptArtifactFiles, addJavaScriptBundlerNodes, addJavaScriptPackageNodes, createJavaScriptArtifactRootNode, } from "./JavaScriptArtifactGraphStructure.js";
+import { addJavaScriptArtifactContainers, addJavaScriptArtifactFiles, addJavaScriptPackageNodes, createJavaScriptArtifactRootNode, } from "./JavaScriptArtifactGraphStructure.js";
+import { addJavaScriptBundlerNodes } from "./JavaScriptArtifactGraphBundlers.js";
 import { addElectronBoundaries } from "./ElectronBoundaryGraph.js";
 import { classifyElectronIpcPairings, collectElectronIpcRecords, } from "./ElectronBoundaryAnalysis.js";
 /** Project artifact and AST facts into JavaScript Application Graph. */
@@ -34,9 +36,9 @@ const buildJavaScriptArtifactGraphInput = (snapshot, fileSet, analysis) => {
     addJavaScriptArtifactFiles(context);
     const packageRoots = addJavaScriptPackageNodes(context);
     addJavaScriptSourceModules(context);
-    addJavaScriptBundlerNodes(context);
+    const bundlerLimitations = addJavaScriptBundlerNodes(context);
     const relationshipOmissions = addJavaScriptModuleRelationships(context);
-    addJavaScriptStaticFindings(context);
+    const findingLimitations = addJavaScriptStaticFindings(context);
     addElectronBoundaries(context);
     addJavaScriptHtmlRoles(context);
     addJavaScriptSourceMapOriginals(context);
@@ -49,7 +51,11 @@ const buildJavaScriptArtifactGraphInput = (snapshot, fileSet, analysis) => {
         nodes: accumulator.nodes(),
         edges: accumulator.edges(),
         coverage,
-        limitations: graphLimitations(context, coverage.status, relationshipOmissions),
+        limitations: [
+            ...bundlerLimitations,
+            ...findingLimitations,
+            ...graphLimitations(context, coverage.status, relationshipOmissions),
+        ],
     };
 };
 const graphCoverage = (context) => {
@@ -104,11 +110,7 @@ const graphLimitations = (context, coverage, relationshipOmissions) => {
                 javascript.electron.native_addon_bindings.length), 0);
     return [
         ...context.analysis.limitations,
-        ...(relationshipOmissions.selfImports > 0
-            ? [
-                `${String(relationshipOmissions.selfImports)} import ${relationshipOmissions.selfImports === 1 ? "specifier" : "specifiers"} resolved back to the importing module itself and ${relationshipOmissions.selfImports === 1 ? "was" : "were"} omitted; application graph edges cannot be self-referential.`,
-            ]
-            : []),
+        ...selfReferenceOmissions(relationshipOmissions.selfImports, ["import specifier", "import specifiers"], "the importing module"),
         "CommonJS and ESM binding relationships were recovered from inert syntax and resolved only within the inventoried artifact container.",
         "Webpack/Rspack factories were recovered from AST literals; REA did not invoke push handlers or bundle bootstrap code.",
         "Static imports, entrypoints, workers, endpoints, and storage relationships do not prove runtime execution.",

package/dist/application/javascript/JavaScriptArtifactGraphBundlers.js

@@ -1,7 +1,8 @@
-import { addAstContainsEdge, artifactLocalIdentity, chunkLookupKey, javascriptAnalysisCoverage, moduleLookupKey, } from "./JavaScriptArtifactGraphContext.js";
+import { addAstContainsEdge, artifactLocalIdentity, chunkLookupKey, javascriptAnalysisCoverage, moduleLookupKey, selfReferenceOmissions, } from "./JavaScriptArtifactGraphContext.js";
 import { astObservationEvidence, staticInferenceEvidence, } from "./JavaScriptArtifactGraphEvidence.js";
-/** Project Webpack/Rspack chunk and factory literals recovered from AST. */
+/** Project Webpack/Rspack AST literals and disclose unrepresentable relationships. */
 export const addJavaScriptBundlerNodes = (context) => {
+    let selfAsyncChunks = 0;
     for (const analyzed of context.analysis.files) {
         const { file, javascript } = analyzed;
         const asset = context.assetNodes.get(file.path);
@@ -31,8 +32,9 @@ export const addJavaScriptBundlerNodes = (context) => {
             addBundlerModuleNodes(context, { ...input, chunk });
         }
         for (const record of records)
-            addBundlerRuntimeEdges(context, record);
+            selfAsyncChunks += addBundlerRuntimeEdges(context, record);
     }
+    return selfReferenceOmissions(selfAsyncChunks, ["bundler async-chunk reference", "bundler async-chunk references"], "the requesting chunk");
 };
 const createBundlerChunkNode = (context, input) => {
     const { file, registration, coverage, limitations } = input;
@@ -119,6 +121,7 @@ const addBundlerModuleNodes = (context, input) => {
     }
 };
 const addBundlerRuntimeEdges = (context, record) => {
+    let selfAsyncChunks = 0;
     const { file, registration, chunk, coverage } = record;
     for (const moduleKey of registration.entry_module_keys) {
         const resolved = context.moduleNodes.get(moduleLookupKey(file.path, moduleKey));
@@ -147,6 +150,10 @@ const addBundlerRuntimeEdges = (context, record) => {
     for (const chunkKey of registration.async_chunk_keys) {
         const lookup = chunkLookupKey(file.path, registration.runtime, chunkKey);
         const resolved = context.chunkNodes.get(lookup);
+        if (resolved?.node_id === chunk.node_id) {
+            selfAsyncChunks++;
+            continue;
+        }
         const target = resolved ?? unresolvedBundlerChunkNode(context, record, chunkKey);
         context.accumulator.addEdge({
             source_node_id: chunk.node_id,
@@ -169,6 +176,7 @@ const addBundlerRuntimeEdges = (context, record) => {
             }),
         });
     }
+    return selfAsyncChunks;
 };
 const unresolvedBundlerModuleNode = (context, record, moduleKey) => context.accumulator.addNode({
     kind: "javascript-module",

package/dist/application/javascript/JavaScriptArtifactGraphContext.js

@@ -161,6 +161,15 @@ export const linkElectronRoleToAsset = (context, input) => {
         }),
     });
 };
+/**
+ * Disclose relationships omitted because they resolved to their own source;
+ * the application graph forbids self-referential edges.
+ */
+export const selfReferenceOmissions = (count, noun, owner) => count === 0
+    ? []
+    : [
+        `${String(count)} ${count === 1 ? noun[0] : noun[1]} resolved back to ${owner} itself and ${count === 1 ? "was" : "were"} omitted; application graph edges cannot be self-referential.`,
+    ];
 /** Deterministic key for one recovered module inside a bundle asset. */
 export const moduleLookupKey = (path, moduleKey) => `${path}\0${moduleKey}`;
 /** Deterministic key for one recovered bundler chunk inside a bundle asset. */

package/dist/application/javascript/JavaScriptArtifactGraphDocuments.js

@@ -109,16 +109,16 @@ export const addJavaScriptSourceMapOriginals = (context) => {
                     strategy: "source-map-original",
                     stability: "source-map-exact",
                     source_map_sha256: mapFile.sha256,
-                    original_source: original.source,
+                    original_source: original.reference.source_name,
+                    source_root: original.reference.source_root,
                     source_sha256: original.content_sha256,
                 },
                 observations: [
                     {
-                        label: original.source,
+                        label: original.reference.source_name || null,
+                        source_map_reference: original.reference,
                         properties: {
-                            source: original.source,
                             content_available: original.content !== null,
-                            source_sha256: original.content_sha256,
                         },
                         evidence: artifactObservationEvidence({
                             sha256: mapFile.sha256,
@@ -134,7 +134,10 @@ export const addJavaScriptSourceMapOriginals = (context) => {
                 source_node_id: mapNode.node_id,
                 target_node_id: node.node_id,
                 relation: "contains",
-                properties: { original_source: original.source },
+                properties: {
+                    original_source: original.reference.source_name,
+                    source_root: original.reference.source_root,
+                },
                 evidence: artifactObservationEvidence({
                     sha256: mapFile.sha256,
                     path: mapFile.path,

package/dist/application/javascript/JavaScriptArtifactGraphFindings.js

@@ -1,8 +1,9 @@
-import { addStaticInferenceEdge, artifactLocalIdentity, chunkLookupKey, createElectronRoleNode, javascriptAnalysisCoverage, linkElectronRoleToAsset, moduleLookupKey, resolveArtifactPath, sourceNodeFor, } from "./JavaScriptArtifactGraphContext.js";
+import { addStaticInferenceEdge, artifactLocalIdentity, chunkLookupKey, createElectronRoleNode, javascriptAnalysisCoverage, linkElectronRoleToAsset, moduleLookupKey, resolveArtifactPath, selfReferenceOmissions, sourceNodeFor, } from "./JavaScriptArtifactGraphContext.js";
 import { astObservationEvidence, staticInferenceEvidence, } from "./JavaScriptArtifactGraphEvidence.js";
 import { resolveArtifactPathByContext } from "./JavaScriptArtifactPathResolution.js";
 /** Project imports, workers, roles, endpoints, storage, and source-map links. */
 export const addJavaScriptStaticFindings = (context) => {
+    const omissions = { selfReferences: 0 };
     for (const analyzed of context.analysis.files) {
         const { file, javascript } = analyzed;
         const asset = context.assetNodes.get(file.path);
@@ -10,7 +11,7 @@ export const addJavaScriptStaticFindings = (context) => {
             continue;
         const coverage = javascriptAnalysisCoverage(javascript);
         for (const value of javascript.references)
-            addReference(context, { file, asset, value, coverage });
+            addReference(context, { file, asset, value, coverage }, omissions);
         for (const value of javascript.endpoints)
             addEndpoint(context, { file, asset, value, coverage });
         for (const value of javascript.storage)
@@ -20,8 +21,9 @@ export const addJavaScriptStaticFindings = (context) => {
         for (const value of javascript.source_map_urls)
             addSourceMapEdge(context, { file, asset, value, coverage });
     }
+    return selfReferenceOmissions(omissions.selfReferences, ["static reference", "static references"], "the referencing module");
 };
-const addReference = (context, input) => {
+const addReference = (context, input, omissions) => {
     const source = sourceNodeFor(context, input.file.path, input.value.module_key) ??
         input.asset;
     const resolved = input.value.specifier === null
@@ -70,6 +72,13 @@ const addReference = (context, input) => {
             });
         return;
     }
+    // A reference that resolves to its own source, such as a bundled module
+    // requiring its own key, cannot become an edge: the application graph
+    // forbids self-referential edges and one would fail the whole analysis.
+    if (resolved?.node.node_id === source.node_id) {
+        omissions.selfReferences += 1;
+        return;
+    }
     const target = resolved?.node ??
         unresolvedReferenceNode(context, input.file, input.value, input.coverage);
     addStaticInferenceEdge(context, {

package/dist/application/javascript/JavaScriptArtifactGraphStructure.js

@@ -2,7 +2,6 @@ import { completeApplicationCoverage } from "../../domain/javascript/javascriptA
 import { addArtifactContainsEdge, addUnavailableStaticParseScope, artifactFileNodeKind, artifactLocalIdentity, createElectronRoleNode, linkElectronRoleToAsset, } from "./JavaScriptArtifactGraphContext.js";
 import { artifactObservationEvidence, staticInferenceEvidence, } from "./JavaScriptArtifactGraphEvidence.js";
 import { resolveArtifactPathByContext } from "./JavaScriptArtifactPathResolution.js";
-export { addJavaScriptBundlerNodes } from "./JavaScriptArtifactGraphBundlers.js";
 /** Create the exact root artifact node from the inventory manifest. */
 export const createJavaScriptArtifactRootNode = (accumulator, snapshot) => {
     const root = snapshot.nodes.find(({ artifact_id: id }) => id === snapshot.manifest.root_artifact_id);

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
@@ -431,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,11 +1,13 @@
-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 { 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";
@@ -17,7 +19,7 @@ export const reconstructJavaScriptArtifact = async (rawInput, signal, progress)
     };
     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)
@@ -46,7 +48,7 @@ export const reconstructJavaScriptArtifact = async (rawInput, signal, progress)
         const graph = await completeJavaScriptAnalysisSteps(applicationGraphSteps, signal);
         await reportPhase("build_javascript_semantic_graph", "Binding and validating static semantic relationships");
         const semanticGraphSteps = semanticProjection.finishImmutableSteps(snapshot.manifest.root_sha256, graph, analysis);
-        await reportPhase("seal_javascript_semantic_graph", "Sealing the validated semantic graph");
+        await reportPhase("seal_javascript_semantic_graph", "Validating and sealing the semantic graph");
         const semanticGraph = await completeJavaScriptAnalysisSteps(semanticGraphSteps, signal);
         await checkpointJavaScriptAnalysis(signal);
         return {
@@ -77,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()
@@ -85,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

@@ -6,7 +6,7 @@ import { SEMANTIC_EXPRESSION_DEPTH_LIMIT, SEMANTIC_PRIMITIVE_CANDIDATE_LIMIT, SE
 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) {

package/dist/application/javascript/JavaScriptRuntimeObservationService.js

@@ -18,11 +18,11 @@ export const observeJavaScriptRuntime = async (provider, input, options = {}) =>
     if (!ready.ok)
         return ready;
     const result = await ready.value.observe(input, options);
+    if (!result.ok)
+        return result;
     if (options.signal?.aborted === true)
         return err(new AnalysisCancelledError("observe_javascript_runtime"));
-    return result.ok
-        ? ok(createJavaScriptRuntimeObservationEvidence("observe_javascript_runtime", input, result.value, ready.value.identity()))
-        : result;
+    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/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);