rea-agents 6.3.0 → 6.5.0

package/dist/domain/javascript/javascriptSemanticValues.js

@@ -1,7 +1,8 @@
 import * as t from "@babel/types";
-import { semanticCapturePosition, semanticEscapeFollowsCapture, semanticBindingPrecedesCapture, } from "./javascriptSemanticMutationInitializers.js";
+import { SemanticDependencyProofs, } from "./javascriptSemanticDependencies.js";
+import { semanticCapturePosition, semanticEscapeFollowsCapture, semanticBindingPrecedesCapture, semanticReadInitializers, } from "./javascriptSemanticMutationInitializers.js";
 import { semanticSlotAtPath } from "./javascriptSemanticSlots.js";
-import { invalidateSemanticEscapedPath, invalidateSemanticMutationPath, } from "./javascriptSemanticMutationValues.js";
+import { invalidateSemanticEscapedPath, invalidateSemanticMutationPaths, } from "./javascriptSemanticMutationValues.js";
 import { resolveSemanticBindingState, } from "./javascriptSemanticState.js";
 import { semanticRequireOrigin } from "./javascriptSemanticRequireOrigin.js";
 import { compareUnicodeCodePoints } from "../unicodeCodePointOrder.js";
@@ -9,14 +10,37 @@ import { readExactJavaScriptLiteral, semanticStaticPropertyKey, unwrapJavaScript
 import { semanticAmbiguousProvenance, semanticLocalProvenance, semanticOriginsProvenance, semanticUnresolvedProvenance, uniqueSemanticOrigins, } from "./javascriptSemanticProvenance.js";
 import { semanticPrimitiveCandidates as primitiveCandidates, semanticPrimitiveSet as primitiveSet, } from "./javascriptSemanticPrimitives.js";
 import { SEMANTIC_EXPRESSION_DEPTH_LIMIT, SEMANTIC_PRIMITIVE_CANDIDATE_LIMIT, exceedsSemanticPrimitiveAdditionByteBudget, exceedsSemanticTemplateByteBudget, semanticResourceLimitUnknown, semanticResourceLimitReason, } from "./javascriptSemanticResourceLimits.js";
+// Indexing owns stable binding identities; effects invalidate values, not this
+// identity-only layout. No query result or dependency closure is retained here.
+const dependencyProofsByState = new WeakMap();
+const createEvaluationMemo = (state) => {
+    let dependencies = dependencyProofsByState.get(state);
+    if (dependencies === undefined) {
+        dependencies = new SemanticDependencyProofs(state.bindingsById.keys());
+        dependencyProofsByState.set(state, dependencies);
+    }
+    return { provenance: new Map(), dependencyFrames: [], dependencies };
+};
+const CALLER_INDEPENDENT = Number.POSITIVE_INFINITY;
+const EVERY_CALLER = -1;
+const callerIndependentBindingValuesByState = new WeakMap();
 const primitiveBindingValuesByState = new WeakMap();
 const primitiveExpressionValuesByState = new WeakMap();
 const capturedBindingValuesByState = new WeakMap();
-/** Discard primitive projections evaluated before mutation collection finished. */
-export const clearSemanticPrimitiveBindingValues = (state) => {
+/** Discard every state-owned value derived before the effects boundary changed. */
+export const clearSemanticValueCaches = (state) => {
     primitiveBindingValuesByState.delete(state);
     capturedBindingValuesByState.delete(state);
     primitiveExpressionValuesByState.delete(state);
+    callerIndependentBindingValuesByState.delete(state);
+};
+const callerIndependentBindingValuesFor = (state) => {
+    const existing = callerIndependentBindingValuesByState.get(state);
+    if (existing !== undefined)
+        return existing;
+    const values = new Map();
+    callerIndependentBindingValuesByState.set(state, values);
+    return values;
 };
 const primitiveBindingValuesFor = (state) => {
     const existing = primitiveBindingValuesByState.get(state);
@@ -31,17 +55,21 @@ const isSemanticResourceLimit = (value) => value.status === "unknown" && value.r
 /** Evaluate one binding in the bounded constant-value lattice. */
 export const evaluateSemanticBinding = (binding, state) => evaluateBinding(binding, {
     state,
-    bindings: new Set(),
+    bindings: new Map(),
     expressionDepth: 0,
     primitiveBindingValues: primitiveBindingValuesFor(state),
+    dependence: { lowest: CALLER_INDEPENDENT },
+    memo: createEvaluationMemo(state),
 });
 /** Evaluate an inert expression, optionally at an earlier reference capture. */
 export const evaluateSemanticExpression = (node, state, capturePoint) => {
     const context = {
         state,
-        bindings: new Set(),
+        bindings: new Map(),
         expressionDepth: 0,
         primitiveBindingValues: primitiveBindingValuesFor(state),
+        dependence: { lowest: CALLER_INDEPENDENT },
+        memo: createEvaluationMemo(state),
     };
     return evaluateExpression(node, capturePoint === undefined
         ? context
@@ -50,13 +78,52 @@ export const evaluateSemanticExpression = (node, state, capturePoint) => {
 /** Follow module provenance through destructuring, members, and aliases. */
 export const evaluateSemanticProvenance = (binding, state) => provenanceForBinding(binding, {
     state,
-    bindings: new Set(),
+    bindings: new Map(),
     expressionDepth: 0,
     primitiveBindingValues: primitiveBindingValuesFor(state),
+    dependence: { lowest: CALLER_INDEPENDENT },
+    memo: createEvaluationMemo(state),
 });
+/** Follow a namespace binding as it was read at a specific source position. */
+export const evaluateSemanticProvenanceAtRead = (binding, read, state) => provenanceForBindingAtRead(binding, read, {
+    state,
+    bindings: new Map(),
+    expressionDepth: 0,
+    primitiveBindingValues: primitiveBindingValuesFor(state),
+    dependence: { lowest: CALLER_INDEPENDENT },
+    memo: createEvaluationMemo(state),
+});
+const readMemoizedEvaluation = (entry, context) => {
+    if (entry === undefined ||
+        context.memo.dependencies.intersects(entry.dependencies, context.bindings))
+        return undefined;
+    retainDependencyProof(entry.dependencies, context);
+    return entry.value;
+};
+const retainDependencyProof = (proof, context) => {
+    const parent = context.memo.dependencyFrames.at(-1);
+    if (parent !== undefined)
+        parent.proof = context.memo.dependencies.union(parent.proof, proof);
+};
+const recordBindingDependency = (binding, context) => retainDependencyProof(context.memo.dependencies.binding(binding.bindingId), context);
+const collectEvaluationDependencies = (binding, context, evaluate) => {
+    const frame = { proof: context.memo.dependencies.binding(binding.bindingId) };
+    context.memo.dependencyFrames.push(frame);
+    try {
+        return { value: evaluate(), dependencies: frame.proof };
+    }
+    finally {
+        context.memo.dependencyFrames.pop();
+        retainDependencyProof(frame.proof, context);
+    }
+};
 const evaluateBinding = (binding, context) => {
-    if (context.bindings.has(binding.bindingId))
+    recordBindingDependency(binding, context);
+    const cycleHead = context.bindings.get(binding.bindingId);
+    if (cycleHead !== undefined) {
+        context.dependence.lowest = Math.min(context.dependence.lowest, cycleHead);
         return { status: "cycle", reason: `Alias cycle at ${binding.name}.` };
+    }
     if (context.capturePoint !== undefined &&
         !semanticBindingPrecedesCapture(binding, context.capturePoint, context.state.parentsByNode)) {
         const { capturePoint: _capturePoint, ...liveContext } = context;
@@ -68,6 +135,20 @@ const evaluateBinding = (binding, context) => {
     const cached = context.primitiveBindingValues.get(binding.bindingId);
     if (cached !== undefined)
         return cached;
+    // Each closure that aliases an outer binding evaluates it both live and at
+    // its capture point, so re-deriving it doubles the work at every level of
+    // nesting. A deeper reader derives it again: the retained value would carry
+    // more nesting than the remaining depth budget allows it to observe.
+    const independent = context.capturePoint === undefined
+        ? callerIndependentBindingValuesFor(context.state)
+        : undefined;
+    const retained = independent?.get(binding.bindingId);
+    if (retained !== undefined &&
+        context.expressionDepth <= retained.expressionDepth) {
+        const reusable = readMemoizedEvaluation(retained, context);
+        if (reusable !== undefined)
+            return reusable;
+    }
     if (binding.initializers.length === 0)
         return {
             status: "unknown",
@@ -91,21 +172,62 @@ const evaluateBinding = (binding, context) => {
     const initializer = binding.initializers[0];
     if (initializer === undefined)
         return { status: "unknown", reason: "Missing binding initializer." };
-    const nested = nestedContext(context, binding.bindingId);
-    let value = projectValue(evaluateExpression(initializer.node, nested), initializer.projection);
-    if (!isPrimitive(value)) {
-        const captureContext = primitiveCaptureContext(initializer.node, nested);
-        if (captureContext !== undefined) {
-            const captured = projectValue(evaluateExpression(initializer.node, captureContext), initializer.projection);
-            if (isPrimitive(captured))
-                value = captured;
-        }
+    if (context.state.conditionallySkippedExpressions.has(initializer.node))
+        return {
+            status: "unknown",
+            reason: `Binding ${binding.name} may remain uninitialized.`,
+        };
+    const position = context.bindings.size;
+    const callerDependence = context.dependence.lowest;
+    context.dependence.lowest = CALLER_INDEPENDENT;
+    context.bindings.set(binding.bindingId, position);
+    let value;
+    let callerIndependent = false;
+    let evaluated;
+    try {
+        evaluated = collectEvaluationDependencies(binding, context, () => {
+            const nested = nestedContext(context);
+            let value = projectValue(evaluateExpression(initializer.node, nested), initializer.projection);
+            if (!isPrimitive(value)) {
+                const captureContext = primitiveCaptureContext(initializer.node, nested);
+                if (captureContext !== undefined) {
+                    const captured = projectValue(evaluateExpression(initializer.node, captureContext), initializer.projection);
+                    if (isPrimitive(captured))
+                        value = captured;
+                }
+            }
+            return value;
+        });
+        value = evaluated.value;
+        // A cycle among bindings this one reads is part of its value. A cycle
+        // through this binding is cut elsewhere when a caller holds another member.
+        callerIndependent = context.dependence.lowest > position;
+    }
+    finally {
+        context.bindings.delete(binding.bindingId);
+        context.dependence.lowest = callerIndependent
+            ? callerDependence
+            : Math.min(callerDependence, context.dependence.lowest);
+    }
+    let projected = invalidateSemanticMutationPaths(value, binding.memberWrites.map(({ path }) => path));
+    for (const escape of binding.escapedPaths) {
+        // Escapes only invalidate object references; other lattice values survive.
+        if (projected.status !== "object" && projected.status !== "array")
+            break;
+        if (context.capturePoint !== undefined &&
+            semanticEscapeFollowsCapture(binding, context.capturePoint, escape.node, context.state.parentsByNode))
+            continue;
+        projected = invalidateSemanticEscapedPath(projected, escape.path);
     }
-    const mutated = binding.mutatedPaths.reduce(invalidateSemanticMutationPath, value);
-    const projected = binding.escapedPaths.reduce((value, escape) => context.capturePoint !== undefined &&
-        semanticEscapeFollowsCapture(binding, context.capturePoint, escape.node, context.state.parentsByNode)
-        ? value
-        : invalidateSemanticEscapedPath(value, escape.path), mutated);
+    if (callerIndependent &&
+        independent !== undefined &&
+        (retained === undefined ||
+            retained.expressionDepth < context.expressionDepth))
+        independent.set(binding.bindingId, {
+            value: projected,
+            dependencies: evaluated.dependencies,
+            expressionDepth: context.expressionDepth,
+        });
     // Point-local memoization also bounds failed speculative captures. Only a
     // primitive result is allowed back into ordinary value evaluation.
     if (context.capturePoint !== undefined ||
@@ -118,13 +240,17 @@ const evaluateBinding = (binding, context) => {
     return projected;
 };
 const evaluateExpression = (node, context) => {
-    if (context.expressionDepth > SEMANTIC_EXPRESSION_DEPTH_LIMIT)
+    if (context.expressionDepth > SEMANTIC_EXPRESSION_DEPTH_LIMIT) {
+        context.dependence.lowest = EVERY_CALLER;
         return semanticResourceLimitUnknown("expression-depth");
+    }
     const unwrapped = unwrapJavaScriptExpression(node);
     if (unwrapped.depth > 0) {
         if (context.expressionDepth + unwrapped.depth >
-            SEMANTIC_EXPRESSION_DEPTH_LIMIT)
+            SEMANTIC_EXPRESSION_DEPTH_LIMIT) {
+            context.dependence.lowest = EVERY_CALLER;
             return semanticResourceLimitUnknown("expression-depth");
+        }
         return evaluateExpression(unwrapped.node, {
             ...context,
             expressionDepth: context.expressionDepth + unwrapped.depth,
@@ -395,8 +521,55 @@ const projectValue = (value, projection) => {
         };
 };
 const provenanceForBinding = (binding, context) => {
-    if (context.bindings.has(binding.bindingId))
+    recordBindingDependency(binding, context);
+    const cycleHead = context.bindings.get(binding.bindingId);
+    if (cycleHead !== undefined) {
+        context.dependence.lowest = Math.min(context.dependence.lowest, cycleHead);
         return semanticUnresolvedProvenance("cycle", `Alias cycle at ${binding.name}.`);
+    }
+    let depths = context.memo.provenance.get(binding.bindingId);
+    const prior = readMemoizedEvaluation(depths?.get(context.expressionDepth), context);
+    if (prior !== undefined)
+        return prior;
+    const position = context.bindings.size;
+    const callerDependence = context.dependence.lowest;
+    context.dependence.lowest = CALLER_INDEPENDENT;
+    let result;
+    let callerIndependent = false;
+    try {
+        result = collectEvaluationDependencies(binding, context, () => provenanceForBindingUncached(binding, context));
+        callerIndependent = context.dependence.lowest > position;
+    }
+    finally {
+        context.dependence.lowest = callerIndependent
+            ? callerDependence
+            : Math.min(callerDependence, context.dependence.lowest);
+    }
+    if (callerIndependent) {
+        if (depths === undefined) {
+            depths = new Map();
+            context.memo.provenance.set(binding.bindingId, depths);
+        }
+        depths.set(context.expressionDepth, result);
+    }
+    return result.value;
+};
+const provenanceForBindingUncached = (binding, context) => {
+    const provenance = provenanceForBindingValue(binding, context);
+    const assigned = binding.definitions.some(({ kind }) => kind === "assignment");
+    const conditionallyInitialized = binding.initializers.some(({ node }) => context.state.conditionallySkippedExpressions.has(node));
+    if (provenance.status !== "module" ||
+        (!assigned && !conditionallyInitialized))
+        return provenance;
+    return semanticAmbiguousProvenance(provenance.origins, assigned
+        ? `Binding ${binding.name} may be reassigned.`
+        : `Binding ${binding.name} may remain uninitialized.`);
+};
+const provenanceForBindingValue = (binding, context) => {
+    if (binding.kind === "parameter" || binding.kind === "catch")
+        return semanticUnresolvedProvenance("unknown", binding.kind === "parameter"
+            ? "Parameter provenance depends on caller arguments."
+            : "Catch binding provenance depends on the thrown value.");
     if (binding.directOrigins.length > 0)
         return semanticOriginsProvenance(binding.directOrigins);
     if (binding.initializers.length === 0)
@@ -408,7 +581,14 @@ const provenanceForBinding = (binding, context) => {
         return semanticUnresolvedProvenance("unknown", "Missing binding initializer.");
     if (initializer.projection.includes(null))
         return semanticUnresolvedProvenance("unknown", "Dynamic provenance projection.");
-    const resolved = provenanceForExpression(initializer.node, nestedContext(context, binding.bindingId));
+    context.bindings.set(binding.bindingId, context.bindings.size);
+    let resolved;
+    try {
+        resolved = provenanceForExpression(initializer.node, nestedContext(context));
+    }
+    finally {
+        context.bindings.delete(binding.bindingId);
+    }
     if (resolved.status !== "module" || initializer.projection.length === 0)
         return resolved;
     return semanticOriginsProvenance(resolved.origins.map((origin) => ({
@@ -420,13 +600,17 @@ const provenanceForBinding = (binding, context) => {
     })));
 };
 const provenanceForExpression = (node, context) => {
-    if (context.expressionDepth > SEMANTIC_EXPRESSION_DEPTH_LIMIT)
+    if (context.expressionDepth > SEMANTIC_EXPRESSION_DEPTH_LIMIT) {
+        context.dependence.lowest = EVERY_CALLER;
         return semanticUnresolvedProvenance("unknown", semanticResourceLimitReason("expression-depth"));
+    }
     const unwrapped = unwrapJavaScriptExpression(node);
     if (unwrapped.depth > 0) {
         if (context.expressionDepth + unwrapped.depth >
-            SEMANTIC_EXPRESSION_DEPTH_LIMIT)
+            SEMANTIC_EXPRESSION_DEPTH_LIMIT) {
+            context.dependence.lowest = EVERY_CALLER;
             return semanticUnresolvedProvenance("unknown", semanticResourceLimitReason("expression-depth"));
+        }
         return provenanceForExpression(unwrapped.node, {
             ...context,
             expressionDepth: context.expressionDepth + unwrapped.depth,
@@ -434,12 +618,20 @@ const provenanceForExpression = (node, context) => {
     }
     const required = semanticRequireOrigin(node, context.state);
     if (required !== undefined)
-        return semanticOriginsProvenance([required]);
+        return semanticOriginsProvenance([required.origin]);
+    if (t.isSequenceExpression(node)) {
+        const finalExpression = node.expressions.at(-1);
+        return finalExpression === undefined
+            ? semanticUnresolvedProvenance("unknown", "Empty sequence expression.")
+            : provenanceForExpression(finalExpression, nestedContext(context));
+    }
+    if (t.isAssignmentExpression(node) && node.operator === "=")
+        return provenanceForExpression(node.right, nestedContext(context));
     if (t.isIdentifier(node)) {
         const binding = resolveSemanticBindingState(context.state, node, node.name);
         return binding === undefined
             ? semanticUnresolvedProvenance("unknown", `Unbound identifier ${node.name}.`)
-            : provenanceForBinding(binding, nestedContext(context));
+            : provenanceForBindingAtRead(binding, node, nestedContext(context));
     }
     if (t.isMemberExpression(node) || t.isOptionalMemberExpression(node)) {
         const members = [];
@@ -480,8 +672,41 @@ const provenanceForExpression = (node, context) => {
                 : "Conditional provenance includes a non-module alternative.")
             : semanticUnresolvedProvenance("unknown", "Conditional provenance is unresolved.");
     }
-    return semanticLocalProvenance();
+    if (isLocallyCreatedValue(node))
+        return semanticLocalProvenance();
+    return semanticUnresolvedProvenance("unknown", `Unsupported ${node.type} provenance.`);
+};
+/** Resolve an alias from the value visible at this read, before later rebinds. */
+const provenanceForBindingAtRead = (binding, read, context) => {
+    const selected = semanticReadInitializers(binding, read, context.state.parentsByNode);
+    if (selected.initializers === binding.initializers)
+        return provenanceForBinding(binding, context);
+    if (context.bindings.has(binding.bindingId))
+        return semanticUnresolvedProvenance("cycle", `Alias cycle at ${binding.name}.`);
+    const snapshot = {
+        ...binding,
+        ...selected,
+        // Assignment facts after the read cannot change the captured value.
+        definitions: binding.definitions.filter(({ kind }) => kind !== "assignment"),
+    };
+    context.bindings.set(binding.bindingId, context.bindings.size);
+    try {
+        return provenanceForBindingValue(snapshot, context);
+    }
+    finally {
+        context.bindings.delete(binding.bindingId);
+    }
 };
+const isLocallyCreatedValue = (node) => readExactJavaScriptLiteral(node).found ||
+    t.isObjectExpression(node) ||
+    t.isArrayExpression(node) ||
+    t.isFunctionExpression(node) ||
+    t.isArrowFunctionExpression(node) ||
+    t.isClassExpression(node) ||
+    t.isTemplateLiteral(node) ||
+    t.isUnaryExpression(node) ||
+    t.isBinaryExpression(node) ||
+    t.isUpdateExpression(node);
 const mergeValues = (values) => {
     const resourceLimit = values.find(isSemanticResourceLimit);
     if (resourceLimit !== undefined)
@@ -491,16 +716,16 @@ const mergeValues = (values) => {
         ? primitiveSet(primitives)
         : { status: "ambiguous", reason: "Branches have incompatible values." };
 };
-const nestedContext = (context, bindingId) => ({
+const nestedContext = (context) => ({
     state: context.state,
     primitiveBindingValues: context.primitiveBindingValues,
     ...(context.capturePoint === undefined
         ? {}
         : { capturePoint: context.capturePoint }),
     expressionDepth: context.expressionDepth + 1,
-    bindings: bindingId === undefined
-        ? context.bindings
-        : new Set([...context.bindings, bindingId]),
+    bindings: context.bindings,
+    dependence: context.dependence,
+    memo: context.memo,
 });
 const isPrimitive = (value) => value.status === "literal" || value.status === "union";
 const primitiveCaptureContext = (node, context) => {

package/dist/domain/javascript/javascriptSourceAnalysis.js

@@ -0,0 +1 @@
+export {};

package/dist/domain/javascript/javascriptSourceMapPaths.js

@@ -1,5 +1,6 @@
 import { posix } from "node:path";
 import { domainToASCII, fileURLToPath, pathToFileURL } from "node:url";
+import { TraceMap } from "@jridgewell/trace-mapping";
 import { z } from "zod";
 /** Map-scoped source declaration and its path interpretation for matching. */
 export const javascriptSourceMapReferenceSchema = z.strictObject({
@@ -17,24 +18,46 @@ export const javascriptSourceMapReferenceSchema = z.strictObject({
         }),
     ]),
 });
-/** Interpret a declaration once at the source-map ingestion boundary. */
-export const resolveJavaScriptSourceMapReference = (sourceName, sourceRoot, mapPath) => {
-    // TraceMap's producer prefixes sourceRoot before resolving the URL reference.
-    const reference = `${sourceRoot ? `${sourceRoot}/` : ""}${sourceName}`;
-    return {
-        source_name: sourceName,
-        source_root: sourceRoot,
-        map_path: mapPath,
-        resolution: resolveJavaScriptSourceMapPath(reference, mapPath),
-    };
+/** Interpret declarations together once at their source-map ingestion boundary. */
+export const resolveJavaScriptSourceMapReferences = (sourceNames, sourceRoot, mapPath) => {
+    if (sourceNames.length === 0)
+        return [];
+    const resolvedSources = resolveSourceMapUrls(sourceNames.map((sourceName) => sourceName ?? ""), sourceRoot, "");
+    return sourceNames.map((sourceName, index) => {
+        if (sourceName === null)
+            return null;
+        const reference = resolvedSources[index];
+        if (reference === undefined)
+            throw new TypeError(`TraceMap did not resolve source declaration ${String(index)}`);
+        return {
+            source_name: sourceName,
+            source_root: sourceRoot,
+            map_path: mapPath,
+            resolution: resolveJavaScriptSourceMapPath(reference, mapPath),
+        };
+    });
+};
+/** Resolve a source declaration using the same pinned format implementation as map consumers. */
+export const resolveJavaScriptSourceMapUrl = (source, sourceRoot, mapUrl) => {
+    const resolved = resolveSourceMapUrls([source ?? ""], sourceRoot, mapUrl)[0];
+    if (resolved === undefined)
+        throw new TypeError("TraceMap did not resolve its single source declaration");
+    return resolved;
 };
+const resolveSourceMapUrls = (sources, sourceRoot, mapUrl) => new TraceMap({
+    version: 3,
+    names: [],
+    sources,
+    ...(sourceRoot == null ? {} : { sourceRoot }),
+    mappings: "",
+}, mapUrl).resolvedSources;
 /** Resolve a source-map URL reference without changing its recorded identity. */
 const resolveJavaScriptSourceMapPath = (source, mapPath) => {
     const portable = source.replaceAll("\\", "/");
     const windowsPath = /^[a-z]:\//iu.test(portable) || source.startsWith("\\\\");
     // Preserve parent traversal rather than letting URL resolution clamp at '/'.
     const anchor = `/${"source/".repeat(portable.split("/").length + 1)}`;
-    const directory = posix.join(anchor, posix.dirname(mapPath.replaceAll("\\", "/")));
+    const directory = posix.join(anchor, posix.dirname(mapPath));
     const base = pathToFileURL(`${directory}/`, { windows: false });
     const absolute = windowsPath ? windowsFileUrl(source) : URL.parse(source);
     const resolved = windowsPath ? absolute : URL.parse(source, base);
@@ -53,8 +76,11 @@ const resolveJavaScriptSourceMapPath = (source, mapPath) => {
             kind: "unresolved",
             reason: "Source reference names a directory rather than a file.",
         };
-    // Encoded separators must not manufacture a different filesystem hierarchy.
-    if (/%(?:2f|5c)/iu.test(resolved.pathname))
+    // Reject separators in declarations, not escaped literal names in the owned base.
+    const declaredPath = windowsPath
+        ? (absolute?.pathname ?? "")
+        : (URL.parse(source, "file:///")?.pathname ?? "");
+    if (/%(?:2f|5c)/iu.test(declaredPath))
         return {
             kind: "unresolved",
             reason: "Source reference contains an encoded path separator.",
@@ -100,10 +126,11 @@ const windowsFileUrl = (path) => {
 };
 const decodedUrlPath = (url) => {
     try {
-        if (url.protocol === "file:")
-            return fileURLToPath(url, {
-                windows: url.hostname !== "" && url.hostname !== "localhost",
-            }).replaceAll("\\", "/");
+        if (url.protocol === "file:") {
+            const windows = url.hostname !== "" && url.hostname !== "localhost";
+            const path = fileURLToPath(url, { windows });
+            return windows ? path.replaceAll("\\", "/") : path;
+        }
         return `${url.host}${decodeURIComponent(url.pathname)}`;
     }
     catch (cause) {

package/dist/domain/javascript/javascriptSourceParser.js

@@ -32,15 +32,84 @@ export const parserPluginsForPath = (sourcePath) => {
         ? ["decorators-legacy", "jsx", typescript]
         : ["decorators-legacy", typescript];
 };
-/** Parse JavaScript or TypeScript once without attaching comments to AST nodes. */
+/** `.mjs` and `.mts` explicitly select module mode. */
+export const isExplicitModuleSourcePath = (path) => /\.m[jt]s$/iu.test(path ?? "");
+const runtimeSourceTypeForPath = (path) => /\.cjs$/iu.test(path ?? "")
+    ? "commonjs"
+    : isExplicitModuleSourcePath(path)
+        ? "module"
+        : "unambiguous";
+/**
+ * Parse a module or script with recovery. Babel tries module mode first and
+ * keeps its strict-mode errors after falling back to a script, so a script
+ * with errors is parsed again as a script. Strict errors that only the module
+ * parse reports stay visible because the source may still be a module.
+ */
+export const parseRecoveredJavaScript = (source, sourcePath, options) => {
+    const sourceType = runtimeSourceTypeForPath(sourcePath);
+    if (sourceType !== "unambiguous") {
+        const normalizedOptions = { ...options };
+        if (sourceType === "commonjs") {
+            // Babel owns these wrapper semantics in CommonJS mode and rejects
+            // explicit script overrides, including the reference-import options.
+            delete normalizedOptions.allowAwaitOutsideFunction;
+            delete normalizedOptions.allowReturnOutsideFunction;
+            delete normalizedOptions.allowNewTargetOutsideFunction;
+        }
+        return {
+            file: parse(source, {
+                ...normalizedOptions,
+                sourceType,
+                errorRecovery: true,
+            }),
+            moduleOnlyErrors: [],
+        };
+    }
+    const file = parse(source, {
+        ...options,
+        sourceType: "unambiguous",
+        errorRecovery: true,
+    });
+    if (file.program.sourceType !== "script" || file.errors.length === 0)
+        return { file, moduleOnlyErrors: [] };
+    const script = parse(source, {
+        ...options,
+        sourceType: "script",
+        errorRecovery: true,
+    });
+    const scriptErrors = new Set(script.errors.map((error) => error.message));
+    return {
+        file: script,
+        moduleOnlyErrors: file.errors
+            .map((error) => error.message)
+            .filter((message) => !scriptErrors.has(message)),
+    };
+};
+/** Parse inert JavaScript or TypeScript facts without attaching comments to AST nodes. */
 export const parseJavaScriptSource = (source, sourcePath) => {
     try {
-        return parse(source, {
-            sourceType: "unambiguous",
+        const runtimeSourceType = runtimeSourceTypeForPath(sourcePath);
+        const commonjs = runtimeSourceType === "commonjs";
+        const options = {
             errorRecovery: true,
             attachComment: false,
             plugins: parserPluginsForPath(sourcePath),
+        };
+        const file = parse(source, {
+            ...options,
+            // Inert artifact analysis retains module declarations even in .cjs assets.
+            // Infer their syntax here; reference imports keep filename-mode diagnostics.
+            sourceType: commonjs ? "unambiguous" : runtimeSourceType,
+            allowReturnOutsideFunction: commonjs,
+            allowNewTargetOutsideFunction: commonjs,
         });
+        // Unambiguous mode retains module-only diagnostics after choosing a script.
+        // The .cjs extension establishes wrapper mode, so obtain its own diagnostics.
+        return commonjs &&
+            file.program.sourceType === "script" &&
+            file.errors.length > 0
+            ? parse(source, { ...options, sourceType: "commonjs" })
+            : file;
     }
     catch (cause) {
         // Unparseable source is represented by the null return.

package/dist/domain/javascript/javascriptSourceSelection.js

@@ -0,0 +1,11 @@
+import { z } from "zod";
+/** Exact inventoried paths selected for text acquisition and static analysis. */
+export const javaScriptSourcePathsSchema = z
+    .array(z.string().min(1))
+    .min(1)
+    .describe("Exact relevant file paths from the artifact inventory, relative to the application root, analyzed in first-request order before unselected scopes; no globs or implicit dependencies. Omit to analyze all sources.");
+/** Caller scope retained independently of analysis success or completeness. */
+export const javaScriptSourceSelectionSchema = z.strictObject({
+    requested_paths: javaScriptSourcePathsSchema,
+    unselected_files: z.number().int().min(0),
+});