rea-agents 6.4.0 → 6.7.0

package/dist/application/javascript/JavaScriptArtifactPathResolution.js

@@ -2,6 +2,12 @@ import { isBuiltin } from "node:module";
 import { posix } from "node:path";
 import { normalizeJoinedLogicalPath, logicalPathEscapesRoot, } from "../../domain/artifactIdentity.js";
 import { admitsCanonicalPathSyntax, hasScheme, htmlUrlText, looksExternal, percentDecodeUrlPath, stripQueryAndFragment, } from "../../domain/artifactPathSyntax.js";
+import { classifyPackageImportSpecifier, classifyPackageImportTargetString, lookupExactPackageImport, } from "../../domain/javascript/javascriptPackageImportAliases.js";
+import { typescriptEmittedSourceCandidates, } from "../TypeScriptEmittedSourceCandidates.js";
+import { isRelativeJavaScriptModuleSpecifier } from "../../domain/javascript/javascriptModuleSpecifier.js";
+import { err, ok } from "../../domain/result.js";
+/** Preserve an explicitly retained loader mode on graph relationships. */
+export const moduleResolutionModeProperties = (mode) => mode === undefined ? {} : { resolution_mode: mode };
 const EXTENSIONS = [
     ".js",
     ".cjs",
@@ -12,76 +18,332 @@ const EXTENSIONS = [
     ".html",
     ".node",
 ];
+// A private URL namespace for logical artifact paths, including root packages.
+// Encode inventory segments so filename punctuation remains literal in the base.
+const PACKAGE_ARTIFACT_ROOT_URL = new URL("file:///rea-artifact/");
+const encodePackageMetadataUrl = (path) => new URL(path.split("/").map(encodeURIComponent).join("/"), PACKAGE_ARTIFACT_ROOT_URL);
+// URL identity cannot represent lone UTF-16 surrogates. Use request-local
+// opaque segments only for structural admission, never inventory lookup. A
+// target cannot spell these identities after URL's tab/newline preprocessing.
+const packageMetadataUrl = (path, relativeTarget) => {
+    try {
+        return ok(encodePackageMetadataUrl(path));
+    }
+    catch (cause) {
+        if (!(cause instanceof URIError))
+            throw cause;
+        const reserved = new Set(`${path}\n${relativeTarget.replace(/[\t\n\r]/gu, "")}`.match(/rea-opaque-\d+/gu) ?? []);
+        const structuralSegments = new Set();
+        let nextIdentity = 0;
+        const structuralPath = path
+            .split("/")
+            .map((segment) => {
+            try {
+                return encodeURIComponent(segment);
+            }
+            catch (segmentCause) {
+                if (!(segmentCause instanceof URIError))
+                    throw segmentCause;
+                let identity;
+                do
+                    identity = `rea-opaque-${nextIdentity++}`;
+                while (reserved.has(identity));
+                reserved.add(identity);
+                structuralSegments.add(identity);
+                return identity;
+            }
+        })
+            .join("/");
+        return err({
+            structuralUrl: new URL(structuralPath, PACKAGE_ARTIFACT_ROOT_URL),
+            structuralSegments,
+            limitation: `Package metadata path ${JSON.stringify(path)} contains an unpaired UTF-16 surrogate and cannot be represented as a URL.`,
+        });
+    }
+};
 /** Resolve one declaration while preserving its original input identity. */
 export const resolveArtifactPathByContext = (input) => {
     const resolution = resolvePath(input);
+    const facts = {
+        declared_path: input.declaredPath,
+        resolution_context: input.context,
+        limitations: resolution.limitations,
+        ...(resolution.candidatePath === undefined
+            ? {}
+            : { candidate_path: resolution.candidatePath }),
+        ...(resolution.conditionalResolutions === undefined
+            ? {}
+            : { conditional_resolutions: resolution.conditionalResolutions }),
+    };
     return resolution.status === "resolved"
         ? {
-            declared_path: input.declaredPath,
-            resolution_context: input.context,
+            ...facts,
             resolved_path: resolution.resolvedPath,
             resolution_status: resolution.status,
-            limitations: resolution.limitations,
         }
-        : {
-            declared_path: input.declaredPath,
-            resolution_context: input.context,
-            resolved_path: null,
-            resolution_status: resolution.status,
-            limitations: resolution.limitations,
-        };
+        : { ...facts, resolved_path: null, resolution_status: resolution.status };
 };
+/** Project retained conditional identities without flattening them into display text. */
+export const artifactPathResolutionProperties = (resolution) => ({
+    ...(resolution?.candidate_path === undefined
+        ? {}
+        : { candidate_path: resolution.candidate_path }),
+    ...(resolution?.conditional_resolutions === undefined
+        ? {}
+        : {
+            conditional_resolutions: resolution.conditional_resolutions.map((branch) => ({
+                mode: branch.mode,
+                resolution_status: branch.resolution_status,
+                resolved_path: branch.resolved_path,
+                limitations: [...branch.limitations],
+                ...(branch.candidate_path === undefined
+                    ? {}
+                    : { candidate_path: branch.candidate_path }),
+            })),
+        }),
+});
+const conditionalResolution = (mode, result) => ({
+    mode,
+    resolution_status: result.status,
+    resolved_path: result.resolvedPath,
+    limitations: result.limitations,
+    ...(result.candidatePath === undefined
+        ? {}
+        : { candidate_path: result.candidatePath }),
+});
 const resolvePath = (input) => {
-    const rejected = rejectDeclaration(input.declaredPath);
-    if (rejected !== null)
-        return rejected;
+    if (input.runtimePathKind === "node-entrypoint")
+        return resolveNodeRuntimeEntrypoint(input);
+    if (input.moduleKind === "compiler-dependent") {
+        const imported = resolvePath({ ...input, moduleKind: "import" });
+        const required = resolvePath({ ...input, moduleKind: "require" });
+        const sameOutcome = imported.status === required.status &&
+            imported.resolvedPath === required.resolvedPath &&
+            imported.candidatePath === required.candidatePath;
+        const limitation = "Static TypeScript loader mode is compiler-dependent without retained compiler options. " +
+            (sameOutcome
+                ? "Node import and require resolution agree on this outcome."
+                : "Node import and require resolution disagree; neither branch is an established target.");
+        return sameOutcome
+            ? {
+                ...imported,
+                limitations: [
+                    ...new Set([
+                        ...imported.limitations,
+                        ...required.limitations,
+                        limitation,
+                    ]),
+                ],
+            }
+            : {
+                resolvedPath: null,
+                status: "unavailable",
+                limitations: [limitation],
+                conditionalResolutions: [
+                    conditionalResolution("import", imported),
+                    conditionalResolution("require", required),
+                ],
+            };
+    }
+    if (input.runtimePathKind === "url-resource")
+        return resolveExactUrlResource(input);
+    if (input.runtimePathKind === "exact-file" && isRuntimePathDeclaration(input))
+        return resolveRuntimeEntrypoint(input);
+    // Package import keys are literal lookup identities, not artifact paths.
+    // The selected target is admitted separately by resolveExportTarget.
+    if (input.context === "module-specifier" &&
+        input.declaredPath.startsWith("#"))
+        return resolvePackageImportAlias(input, input.declaredPath);
     const candidate = contextualCandidate(input);
     if (typeof candidate !== "string")
         return candidate;
     const confined = confineCandidate(candidate);
     if (typeof confined !== "string")
         return confined;
-    if (input.context === "html-reference")
+    if (input.context === "html-reference" || input.context === "url-reference")
         return (resolveFileCandidates(input, [confined]) ??
             unresolvedCandidate("not-found", [
-                `The exact HTML resource ${confined} was not found among the selected application files.`,
+                `The exact ${input.context === "html-reference" ? "HTML" : "URL"} resource ${confined} was not found among the selected application files.`,
             ]));
-    return resolveCandidate(input, confined, new Set());
+    const isModuleUrlPath = input.context === "module-specifier" &&
+        (isRelativeJavaScriptModuleSpecifier(input.declaredPath) ||
+            input.declaredPath.startsWith("/") ||
+            fileUrlPath(input.declaredPath) !== undefined);
+    const emittedSourceCandidates = isModuleUrlPath && input.moduleKind !== undefined
+        ? typescriptEmittedSourceCandidates(input.sourcePath, confined)
+        : [];
+    if (isModuleUrlPath && input.moduleKind === "import")
+        return (resolveRuntimeSourceCandidates(input, confined, emittedSourceCandidates) ?? notFoundCandidate());
+    return resolveCandidate(input, confined, new Set(), emittedSourceCandidates);
+};
+const resolveExactUrlResource = (input) => {
+    // Electron loadURL requires a protocol. A scheme-less string is not relative
+    // to the calling script; filesystem paths belong to loadFile.
+    if (!hasScheme(input.declaredPath))
+        return unresolvedCandidate("unavailable", [
+            "Electron loadURL requires a URL protocol; relative filesystem paths belong to loadFile.",
+        ]);
+    if (!/^file:/iu.test(input.declaredPath))
+        return unresolvedCandidate("external", [
+            "Only file URLs can be mapped to selected local application artifacts.",
+        ]);
+    const urlContextCandidate = contextualCandidate(input);
+    if (typeof urlContextCandidate !== "string")
+        return urlContextCandidate;
+    const confined = confineCandidate(urlContextCandidate);
+    if (typeof confined !== "string")
+        return confined;
+    return (resolveFileCandidates(input, [confined]) ?? {
+        resolvedPath: null,
+        status: "not-found",
+        candidatePath: confined,
+        limitations: [
+            `The exact URL resource ${confined} was not found among the selected application files.`,
+        ],
+    });
 };
-const rejectDeclaration = (declared) => {
-    if (declared.length === 0)
+const isRuntimePathDeclaration = (input) => input.context === "filesystem-expression" ||
+    (input.context === "module-specifier" &&
+        (isRelativeJavaScriptModuleSpecifier(input.declaredPath) ||
+            input.declaredPath.startsWith("/") ||
+            fileUrlPath(input.declaredPath) !== undefined));
+const resolveNodeRuntimeEntrypoint = (input) => {
+    const { runtimePathKind: _runtimePathKind, ...sourceInput } = input;
+    const runtimeInput = { ...sourceInput, moduleKind: "require" };
+    if (!isRuntimePathDeclaration(runtimeInput))
+        return resolvePath(runtimeInput);
+    const candidate = contextualCandidate(runtimeInput);
+    if (typeof candidate !== "string")
+        return candidate;
+    const confined = confineCandidate(candidate);
+    if (typeof confined !== "string")
+        return confined;
+    // Node entrypoints use runtime file/directory probes. They do not originate
+    // in emitted TypeScript import syntax and cannot select a source substitute.
+    const resolution = resolveCandidate(runtimeInput, confined, new Set());
+    // Runtime entrypoint analysis has no extension or directory fallback, but
+    // retain the normalized loader path when that exact target is absent.
+    return resolution.status === "not-found" &&
+        resolution.candidatePath === undefined
+        ? { ...resolution, candidatePath: confined }
+        : resolution;
+};
+const resolveRuntimeEntrypoint = (input) => {
+    const rejected = rejectDeclaration(input.declaredPath);
+    if (rejected !== null)
+        return rejected;
+    if (hasScheme(input.declaredPath) || looksExternal(input.declaredPath))
+        return unresolvedCandidate("external", [
+            "Electron runtime entrypoints must identify local paths, not external URLs.",
+        ]);
+    const candidate = confineCandidate(relativeCandidate(input.sourcePath, input.declaredPath));
+    if (typeof candidate !== "string")
+        return candidate;
+    return (resolveFileCandidates(input, [candidate]) ?? {
+        resolvedPath: null,
+        status: "not-found",
+        candidatePath: candidate,
+        limitations: [
+            `The declared Electron runtime entrypoint ${candidate} was not found as an exact file among the selected application files; extension and directory fallback were not attempted.`,
+        ],
+    });
+};
+const resolveRuntimeSourceCandidates = (input, exactPath, sourceCandidates) => {
+    const exactCandidate = {
+        path: exactPath,
+        kind: "implementation",
+    };
+    for (const candidate of [exactCandidate, ...sourceCandidates]) {
+        const selected = findFileCandidate(input, candidate.path);
+        if (selected === null)
+            continue;
+        return candidate.kind === "declaration"
+            ? {
+                resolvedPath: null,
+                status: "unavailable",
+                candidatePath: candidate.path,
+                limitations: [
+                    "Only a TypeScript declaration fallback was found; it does not establish the requested runtime module.",
+                ],
+            }
+            : selected;
+    }
+    return null;
+};
+const rejectDeclaration = (declared, literalPercent = false, allowEmptyPath = false) => {
+    if (declared.length === 0 && !allowEmptyPath)
         return unresolvedCandidate("rejected", ["The declared path is empty."]);
     if (declared.includes("\0") || declared.includes("\\"))
         return unresolvedCandidate("rejected", [
             "NUL and backslash path syntax are not admitted for canonical artifact paths.",
         ]);
-    if (!admitsCanonicalPathSyntax(declared))
+    if (!literalPercent && !admitsCanonicalPathSyntax(declared))
         return unresolvedCandidate("rejected", [
             "Encoded dot or separator bytes are rejected before artifact path resolution.",
         ]);
     return null;
 };
+/**
+ * Node's CommonJS loader never percent-decodes a request or a legacy package
+ * main, so `%2e` and `%2f` there are literal filename bytes, not encoded dots
+ * or separators. Root confinement still applies to the joined candidate.
+ */
+const declaresLiteralPercent = (input) => input.moduleKind === "require" &&
+    (input.context === "module-specifier" ||
+        input.context === "package-entrypoint");
 const contextualCandidate = (input) => {
     const { context } = input;
-    let declared = context === "html-reference" ||
-        context === "url-reference" ||
-        (context === "module-specifier" && input.moduleKind !== "require")
-        ? stripQueryAndFragment(input.declaredPath)
-        : input.declaredPath;
     if (context === "html-reference")
         return htmlCandidate(input);
-    if (context === "module-specifier") {
+    // URL suffixes are evidence, not pathname bytes. Admit only the path while
+    // retaining the complete declaration on the resolution result.
+    let declared = context === "url-reference"
+        ? stripQueryAndFragment(input.declaredPath)
+        : input.declaredPath;
+    if (context === "url-reference" && declared.length === 0)
+        return input.runtimePathKind === "url-resource"
+            ? unresolvedCandidate("unavailable", [
+                "A suffix-only runtime URL requires the window's current document URL; the calling script does not establish that base.",
+            ])
+            : unresolvedCandidate("rejected", [
+                "The URL reference contains no pathname, and its base document is not established by this analysis.",
+            ]);
+    if (context === "module-specifier" && /^file:/iu.test(declared)) {
         const fileUrl = fileUrlPath(declared);
+        if (fileUrl === null)
+            return unresolvedCandidate("rejected", [
+                "The file URL path contains syntax that cannot identify a canonical artifact path.",
+            ]);
         if (fileUrl !== undefined)
-            return fileUrl;
+            return input.moduleKind === "require"
+                ? unresolvedCandidate("external", [
+                    "Node CommonJS require specifiers do not resolve file URLs as local artifacts.",
+                ])
+                : fileUrl;
+        return unresolvedCandidate("external", [
+            "File URL authorities or invalid file URL forms cannot be mapped to artifact-local paths.",
+        ]);
+    }
+    const hasUrlPathSemantics = context === "module-specifier" && input.moduleKind === "import";
+    if (hasUrlPathSemantics)
+        declared = htmlUrlText(declared);
+    const rejected = rejectDeclaration(declared, declaresLiteralPercent(input) || hasUrlPathSemantics);
+    if (rejected !== null)
+        return rejected;
+    if (context === "module-specifier") {
         if (hasScheme(declared))
             return unresolvedCandidate("external", [
                 "URL and Node builtin schemes are outside static artifact module resolution.",
             ]);
-        if (!declared.startsWith(".") && !declared.startsWith("/"))
-            return bareModuleCandidate(input, declared);
+        if (!isRelativeJavaScriptModuleSpecifier(declared) &&
+            !declared.startsWith("/"))
+            return bareModuleCandidate(input);
         if (input.moduleKind !== "require") {
-            const decoded = decodeModuleUrlPath(declared);
+            if (/%(?:2f|5c)/iu.test(stripQueryAndFragment(declared)))
+                return unresolvedCandidate("rejected", [
+                    "ES module URL paths cannot contain percent-encoded slash or backslash bytes.",
+                ]);
+            const decoded = decodeModuleUrlPath(stripQueryAndFragment(declared));
             if (typeof decoded !== "string")
                 return decoded;
             declared = decoded;
@@ -91,6 +353,40 @@ const contextualCandidate = (input) => {
         return unresolvedCandidate("external", [
             "URL schemes and protocol-relative URLs are outside this local artifact path context.",
         ]);
+    if (context === "url-reference") {
+        // A file base gives raw drive-letter segments special meaning, including
+        // after dot segments reach the root. Parse before percent decoding so an
+        // encoded drive-like filename stays literal. The synthetic base establishes
+        // only this ambiguity; it does not establish the source's runtime scheme.
+        const sourceUrlPath = input.sourcePath
+            .split("/")
+            .map(encodeURIComponent)
+            .join("/");
+        const fileReference = URL.parse(declared, `file:///${sourceUrlPath}`);
+        if (fileReference === null)
+            return unresolvedCandidate("rejected", [
+                "The URL reference cannot be parsed as a URL.",
+            ]);
+        if (/^\/[A-Za-z]:(?:\/|$)/u.test(fileReference.pathname))
+            return unresolvedCandidate("unavailable", [
+                "Drive-letter URL paths cannot be mapped without the source URL scheme and filesystem root.",
+            ]);
+        const decoded = percentDecodeUrlPath(declared);
+        if (decoded === null)
+            return unresolvedCandidate("rejected", [
+                "The URL reference path percent-decodes to NUL or to bytes that are not UTF-8.",
+            ]);
+        const candidate = urlRelativeCandidate(posix.dirname(input.sourcePath), decoded);
+        return typeof candidate === "string"
+            ? exactUrlPathCandidate(decoded, candidate, "URL")
+            : candidate;
+    }
+    if (context === "module-specifier" && input.moduleKind === "import") {
+        const candidate = urlRelativeCandidate(posix.dirname(input.sourcePath), declared);
+        return typeof candidate === "string"
+            ? exactUrlPathCandidate(declared, candidate, "module URL")
+            : candidate;
+    }
     return relativeCandidate(input.sourcePath, declared);
 };
 const decodeModuleUrlPath = (declared) => {
@@ -113,51 +409,299 @@ const decodeModuleUrlPath = (declared) => {
 const relativeCandidate = (sourcePath, declared) => declared.startsWith("/")
     ? declared.slice(1)
     : posix.join(posix.dirname(sourcePath), declared);
-const bareModuleCandidate = (input, declared) => {
-    const packageName = barePackageName(declared);
-    if (packageName === null || isBuiltin(declared) || declared.startsWith("#"))
+const urlDirectoryState = (directory) => ({
+    escapes: 0,
+    segments: directory === "" || directory === "." ? [] : directory.split("/"),
+});
+/**
+ * Apply URL dot segments: `..` removes the previous segment even when it is
+ * empty, so `assets//../app.js` names `assets/app.js`. A final `.` or `..`
+ * leaves directory form, as the URL parser does.
+ */
+const applyUrlReference = (base, reference) => {
+    const absolute = reference.startsWith("/");
+    const segments = absolute ? [] : [...base.segments];
+    let escapes = absolute ? 0 : base.escapes;
+    const parts = (absolute ? reference.slice(1) : reference).split("/");
+    for (const [index, part] of parts.entries()) {
+        if (part !== "." && part !== "..") {
+            segments.push(part);
+            continue;
+        }
+        if (part === "..")
+            if (segments.length > 0)
+                segments.pop();
+            else
+                escapes += 1;
+        if (index === parts.length - 1)
+            segments.push("");
+    }
+    return { escapes, segments };
+};
+/** A relative reference replaces the base URL's final path segment. */
+const urlBaseDirectory = (base) => ({
+    escapes: base.escapes,
+    segments: base.segments.slice(0, -1),
+});
+/**
+ * Form the artifact candidate. A remaining empty segment cannot name a
+ * canonical artifact file; a trailing one is directory form. Confinement
+ * rejects a candidate that keeps an above-root marker.
+ */
+const urlPathCandidate = (path) => {
+    const segments = path.segments.at(-1) === "" ? path.segments.slice(0, -1) : path.segments;
+    if (segments.includes(""))
+        return unresolvedCandidate("unavailable", [
+            "Repeated URL path separators cannot be mapped to an exact canonical artifact file.",
+        ]);
+    return [
+        ...Array.from({ length: path.escapes }, () => ".."),
+        ...segments,
+    ].join("/");
+};
+/** Resolve a URL path reference against a canonical directory. */
+const urlRelativeCandidate = (directory, reference) => urlPathCandidate(applyUrlReference(urlDirectoryState(directory), reference));
+const bareModuleCandidate = (input) => {
+    const request = parseBarePackageRequest(input.declaredPath, input.moduleKind);
+    if (request === null || isBuiltin(input.declaredPath))
         return unresolvedCandidate("external", [
-            "The bare specifier is a Node builtin, package import map, or invalid package name.",
+            "The bare specifier is a Node builtin or invalid package name.",
+        ]);
+    if (input.moduleKind === "import" &&
+        (request.packageName.startsWith(".") || request.packageName.includes("%")))
+        return unresolvedCandidate("rejected", [
+            "ES module package names cannot start with a dot or contain percent signs.",
         ]);
-    const subpath = declared === packageName ? "." : `.${declared.slice(packageName.length)}`;
+    const self = packageSelfCandidate(input, request);
+    if (self !== null)
+        return self;
+    // ESM constructs a package.json URL; its parsed identity is not a literal
+    // dependency directory. Self resolution above still uses the exact name.
+    let dependencyDirectory = posix.join("node_modules", request.packageName);
+    if (input.moduleKind === "import") {
+        const metadataUrl = new URL(`./node_modules/${request.packageName}/package.json`, PACKAGE_ARTIFACT_ROOT_URL);
+        if (!metadataUrl.pathname.endsWith("/package.json"))
+            return unresolvedCandidate("external", [
+                `ESM package name ${JSON.stringify(request.packageName)} produces a dependency URL whose pathname does not name package.json; no literal or suffix-stripped package directory was searched.`,
+            ]);
+        const decoded = decodeModuleUrlPath(metadataUrl.pathname.slice(PACKAGE_ARTIFACT_ROOT_URL.pathname.length));
+        if (typeof decoded !== "string")
+            return decoded;
+        const confined = confineCandidate(decoded);
+        if (typeof confined !== "string")
+            return confined;
+        dependencyDirectory = posix.dirname(confined);
+    }
     const source = input.files.get(input.sourcePath);
+    let nearestNotFound = null;
+    for (const directory of packageLookupDirectories(input)) {
+        const candidate = posix.join(directory, dependencyDirectory);
+        const metadata = readPackageMetadata(input, candidate);
+        const continueCommonJsLookup = input.moduleKind === "require" &&
+            (metadata.kind === "absent" ||
+                (metadata.kind === "available" &&
+                    (!request.dependencyExportsEligible ||
+                        metadata.exports === undefined)));
+        const packageResolution = metadata.kind !== "absent" ||
+            hasContainerDirectory(input.files, candidate, source?.container_sha256, input.directoryPaths, input.unanalyzedFiles)
+            ? resolvePackageDependency(input, candidate, request, metadata)
+            : request.packageSubpath === "." && input.moduleKind !== "import"
+                ? resolveFileCandidates(input, fileCandidates(candidate, input.moduleKind))
+                : null;
+        if (packageResolution !== null) {
+            if (continueCommonJsLookup &&
+                packageResolution.status === "not-found" &&
+                packageResolution.stopsAncestorLookup !== true) {
+                nearestNotFound ??= packageResolution;
+            }
+            else
+                return packageResolution;
+        }
+    }
+    if (nearestNotFound !== null)
+        return nearestNotFound;
+    return unresolvedCandidate("external", [
+        "No matching bare package was inventoried in an enclosing node_modules directory.",
+    ]);
+};
+function* packageLookupDirectories(input) {
     let directory = posix.dirname(input.sourcePath);
     while (true) {
-        const candidate = posix.join(directory, "node_modules", packageName);
-        if (subpath === ".") {
-            const direct = resolveFileCandidates(input, fileCandidates(candidate));
-            if (direct !== null)
-                return direct;
-        }
-        if (hasContainerDirectory(input.files, candidate, source?.container_sha256))
-            return resolvePackageSpecifier(input, candidate, subpath);
+        if (input.moduleKind !== "require" ||
+            posix.basename(directory) !== "node_modules")
+            yield directory;
+        if (directory === "." || directory === "")
+            return;
+        directory = posix.dirname(directory);
+    }
+}
+/**
+ * Nearest same-container package.json, stopping at a `node_modules` directory
+ * so a nested package cannot inherit an ancestor's map.
+ */
+const enclosingPackageMetadata = (input) => {
+    let directory = posix.dirname(input.sourcePath);
+    while (posix.basename(directory) !== "node_modules") {
+        const metadata = readPackageMetadata(input, directory);
+        if (metadata.kind !== "absent")
+            return metadata;
         if (directory === "." || directory === "")
             break;
         directory = posix.dirname(directory);
     }
-    return unresolvedCandidate("external", [
-        "No matching bare package was inventoried in an enclosing node_modules directory.",
-    ]);
+    return { kind: "none" };
+};
+/**
+ * Resolve an exact `#alias` against the importer's enclosing `imports` map.
+ * Selected relative targets are exact files; patterns, recursive aliases, and
+ * external-package targets stay unresolved without falling through.
+ */
+const resolvePackageImportAlias = (input, specifier) => {
+    const classified = classifyPackageImportSpecifier(specifier);
+    if (classified.kind === "invalid")
+        return unresolvedCandidate("rejected", [
+            `The package import specifier ${JSON.stringify(specifier)} is invalid; "#" and specifiers that end with "/" are not valid import aliases.`,
+        ]);
+    if (classified.kind === "pattern")
+        return unresolvedCandidate("external", [
+            `Wildcard and directory package import aliases remain unresolved; ${JSON.stringify(specifier)} is not an exact imports key.`,
+        ]);
+    const metadata = enclosingPackageMetadata(input);
+    if (metadata.kind === "none")
+        return unresolvedCandidate("external", [
+            `No enclosing package.json defines package import alias ${specifier}; package import maps do not cross package scopes.`,
+        ]);
+    if (metadata.kind === "unavailable")
+        return unresolvedCandidate("unavailable", [metadata.limitation]);
+    const lookup = lookupExactPackageImport(metadata.imports, specifier);
+    if (lookup.kind === "undefined-map")
+        return unresolvedCandidate("external", [
+            `Package metadata ${metadata.path} does not define package import alias ${specifier}.`,
+        ]);
+    if (lookup.kind === "missing-key")
+        return unresolvedCandidate("external", [
+            `Package metadata ${metadata.path} does not define package import alias ${specifier}; it declares ${lookup.declared.join(", ") || "no imports keys"}.`,
+        ]);
+    if (lookup.kind === "pattern-unresolved")
+        return unresolvedCandidate("external", [
+            `Wildcard package import aliases remain unresolved; package metadata ${metadata.path} has no exact imports key ${specifier}.`,
+        ]);
+    const selected = selectExportTarget(lookup.target, packageExportConditions(input.moduleKind), metadata.path, "imports");
+    if (selected.kind === "invalid" || selected.kind === "invalid-config")
+        return unresolvedCandidate("rejected", [
+            `Package metadata ${metadata.path}: ${selected.limitation}`,
+        ]);
+    if (selected.kind === "unmatched")
+        return unresolvedCandidate("external", [
+            `Package metadata ${metadata.path} declares no imports target for alias ${specifier} under the active conditions; it declares ${selected.declared.join(", ") || "no conditions"}.`,
+        ]);
+    if (selected.kind === "blocked")
+        return unresolvedCandidate("external", [
+            `Package metadata ${metadata.path} blocks import alias ${specifier} with ${selected.cause === "null" ? "an explicit null imports target" : "an empty imports target array"}.`,
+        ]);
+    if (selected.kind === "non-relative") {
+        const target = classifyPackageImportTargetString(selected.value);
+        return unresolvedCandidate("external", [
+            target.kind === "recursive"
+                ? `Recursive package import aliases remain unresolved; package metadata ${metadata.path} maps ${specifier} to ${JSON.stringify(target.target)}.`
+                : `External-package import targets remain unresolved; package metadata ${metadata.path} maps ${specifier} to ${JSON.stringify(target.target)}.`,
+        ]);
+    }
+    return resolveExportTarget(input, metadata.path, selected, "imports");
 };
-/** Package roots and exact subpaths share metadata and exports selection. */
-const resolvePackageSpecifier = (input, directory, subpath) => {
-    const metadata = readPackageMetadata(input, directory);
+/** Self references use the nearest package scope before dependency lookup. */
+const packageSelfCandidate = (input, request) => {
+    if (input.moduleKind === undefined || !input.files.has(input.sourcePath))
+        return null;
+    const metadata = enclosingPackageMetadata(input);
+    if (metadata.kind === "none")
+        return null;
     if (metadata.kind === "unavailable")
         return unresolvedCandidate("unavailable", [metadata.limitation]);
-    const rawExports = metadata.kind === "available"
-        ? Reflect.get(metadata.value, "exports")
+    if (metadata.name === undefined || metadata.exports === undefined)
+        return null;
+    let subpath;
+    if (input.moduleKind === "import") {
+        if (metadata.name !== request.packageName)
+            return null;
+        subpath = request.packageSubpath;
+    }
+    else if (input.declaredPath === metadata.name) {
+        subpath = ".";
+    }
+    else if (input.declaredPath.startsWith(`${metadata.name}/`)) {
+        subpath = `.${input.declaredPath.slice(metadata.name.length)}`;
+    }
+    else
+        return null;
+    // Self resolution does not apply the CommonJS dependency-name matcher.
+    return resolvePackageExports(input, metadata.path, subpath, metadata.exports);
+};
+/** Resolve an installed dependency using one parsed request and its metadata. */
+const resolvePackageDependency = (input, directory, request, metadata) => {
+    const subpath = request.packageSubpath;
+    if (request.dependencyExportsEligible && metadata.kind === "unavailable")
+        return unresolvedCandidate("unavailable", [metadata.limitation]);
+    const rawExports = request.dependencyExportsEligible && metadata.kind === "available"
+        ? metadata.exports
         : undefined;
-    if (rawExports === undefined || rawExports === null) {
+    if (rawExports === undefined) {
         if (subpath === ".")
-            return resolveDirectory(input, directory, metadata, new Set());
-        // Preserve the trailing slash for a package directory request.
+            return ((input.moduleKind === "import"
+                ? null
+                : resolveFileCandidates(input, fileCandidates(directory, input.moduleKind))) ?? resolveDirectory(input, directory, metadata, new Set()));
+        if (input.moduleKind === "import")
+            return resolveLegacyEsmSubpath(input, directory, subpath);
         const candidate = confineCandidate(`${directory}/${subpath.slice(2)}`);
         return typeof candidate === "string"
             ? resolveCandidate(input, candidate, new Set())
             : candidate;
     }
-    const exported = selectPackageExport(rawExports, subpath, input.moduleKind);
-    const packagePath = posix.join(directory, "package.json");
+    return resolvePackageExports(input, posix.join(directory, "package.json"), subpath, rawExports);
+};
+/** Legacy ESM package subpaths are exact URLs, never extension or directory lookups. */
+const resolveLegacyEsmSubpath = (input, directory, subpath) => {
+    const declarationRejection = rejectDeclaration(stripQueryAndFragment(htmlUrlText(subpath)));
+    if (declarationRejection !== null)
+        return declarationRejection;
+    const metadataUrl = packageMetadataUrl(posix.join(directory, "package.json"), subpath);
+    const url = new URL(subpath, metadataUrl.ok ? metadataUrl.value : metadataUrl.error.structuralUrl);
+    if (!url.pathname.startsWith(PACKAGE_ARTIFACT_ROOT_URL.pathname))
+        return unresolvedCandidate("rejected", [
+            "The resolved candidate escapes the canonical artifact root.",
+        ]);
+    const encodedPath = url.pathname.slice(PACKAGE_ARTIFACT_ROOT_URL.pathname.length);
+    const rejected = rejectDeclaration(encodedPath);
+    if (rejected !== null)
+        return rejected;
+    const decoded = decodeModuleUrlPath(encodedPath);
+    if (typeof decoded !== "string")
+        return decoded;
+    const candidate = confineCandidate(decoded);
+    if (typeof candidate !== "string")
+        return candidate;
+    if (urlPathIsDirectory(url.pathname))
+        return unresolvedCandidate("rejected", [
+            `ESM package subpath ${JSON.stringify(input.declaredPath)} has URL directory form; directory imports are unsupported and no exact-file, package main or index lookup was attempted.`,
+        ]);
+    const unrepresentableBase = metadataUrl.ok ? undefined : metadataUrl.error;
+    if (unrepresentableBase !== undefined &&
+        url.pathname
+            .split("/")
+            .some((segment) => unrepresentableBase.structuralSegments.has(segment)))
+        return unresolvedCandidate("unavailable", [unrepresentableBase.limitation]);
+    const file = resolveFileCandidates(input, [candidate]);
+    if (file !== null)
+        return file;
+    const source = input.files.get(input.sourcePath);
+    if (hasContainerDirectory(input.files, candidate, source?.container_sha256, input.directoryPaths, input.unanalyzedFiles))
+        return unresolvedCandidate("rejected", [
+            `ESM package subpath ${candidate} names a directory; directory imports are unsupported and package main or index lookup was not attempted.`,
+        ]);
+    return exactPackageTargetNotFound(candidate, "ESM subpath");
+};
+const resolvePackageExports = (input, packagePath, subpath, rawExports) => {
+    const exported = selectPackageExport(rawExports, subpath, input.moduleKind, packagePath);
     if (exported.status === "rejected")
         return unresolvedCandidate("rejected", [
             `Package metadata ${packagePath}: ${exported.limitation}`,
@@ -168,33 +712,68 @@ const resolvePackageSpecifier = (input, directory, subpath) => {
         ]);
     if (exported.status === "blocked")
         return unresolvedCandidate("external", [
-            `Directory package metadata ${packagePath} blocks subpath ${subpath} with an explicit null exports target.`,
+            `Directory package metadata ${packagePath} blocks subpath ${subpath} with ${exported.cause === "null" ? "an explicit null exports target" : "an empty exports target array"}.`,
         ]);
-    return resolveExportTarget(input, packagePath, exported.value);
+    return resolveExportTarget(input, packagePath, exported);
 };
-/** An exports target is a URL naming one exact file for both Node loaders. */
-const resolveExportTarget = (input, packagePath, target) => {
-    const rejected = rejectDeclaration(target);
+/** An exports or import target is a URL naming one exact file for both Node loaders. */
+const resolveExportTarget = (input, packagePath, target, mapKind = "exports") => {
+    const withTargetSource = (outcome) => ({
+        ...outcome,
+        limitations: outcome.limitations.map((reason) => `Package metadata ${packagePath}, ${mapKind} target ${JSON.stringify(target.value)}: ${reason}`),
+    });
+    // Node's CommonJS finalizer checks the serialized URL, including suffixes;
+    // its ESM finalizer checks only the pathname. Neither error retries arrays.
+    if (input.moduleKind === "require" && /%(?:2f|5c)/iu.test(target.url.href))
+        return withTargetSource(unresolvedCandidate("rejected", [
+            "The selected package URL contains encoded separator bytes.",
+        ]));
+    const encodedPath = target.url.pathname.slice(PACKAGE_ARTIFACT_ROOT_URL.pathname.length);
+    // Package targets are URLs for both loaders, so their percent bytes encode.
+    const rejected = rejectDeclaration(encodedPath, false);
     if (rejected !== null)
-        return rejected;
-    const decoded = decodeModuleUrlPath(stripQueryAndFragment(target));
+        return withTargetSource(rejected);
+    const decoded = decodeModuleUrlPath(encodedPath);
     if (typeof decoded !== "string")
-        return decoded;
-    const candidate = confineCandidate(relativeCandidate(packagePath, decoded));
+        return withTargetSource(decoded);
+    const candidate = confineCandidate(decoded);
     if (typeof candidate !== "string")
-        return candidate;
+        return withTargetSource(candidate);
+    if (target.lookupLimitation !== undefined)
+        return unresolvedCandidate("unavailable", [target.lookupLimitation]);
     return (resolveFileCandidates(input, [candidate]) ??
-        exactExportsTargetNotFound(candidate));
+        withTargetSource(exactPackageTargetNotFound(candidate, mapKind)));
 };
-const barePackageName = (specifier) => {
+const parseBarePackageRequest = (specifier, moduleKind) => {
     const segments = specifier.split("/");
-    if (specifier.startsWith("@"))
-        return segments.length >= 2 && segments[0] !== "" && segments[1] !== ""
-            ? `${segments[0]}/${segments[1]}`
-            : null;
-    return segments[0] === "" ? null : (segments[0] ?? null);
+    let packageName = segments[0] ?? "";
+    if (packageName === "" || packageName === "@")
+        return null;
+    if (specifier.startsWith("@")) {
+        const packageSegment = segments[1];
+        if (packageSegment !== undefined && packageSegment !== "") {
+            packageName = `${packageName}/${packageSegment}`;
+        }
+        else if (moduleKind !== "require") {
+            if (packageSegment === undefined)
+                return null;
+            packageName = `${packageName}/`;
+        }
+    }
+    // Node's CommonJS exports matcher excludes percent-containing package names.
+    // Compare the captured name so a scoped name cannot fall back to its scope.
+    const dependencyExportsEligible = moduleKind !== "require" ||
+        /^((?:@[^/\\%]+\/)?[^./\\%][^/\\%]*)(\/.*)?$/.exec(specifier)?.[1] ===
+            packageName;
+    return {
+        packageName,
+        packageSubpath: `.${specifier.slice(packageName.length)}`,
+        dependencyExportsEligible,
+    };
 };
-const hasContainerDirectory = (files, candidate, containerSha256) => {
+const hasContainerDirectory = (files, candidate, containerSha256, directoryPaths, unanalyzedFiles) => {
+    if (directoryPaths?.has(candidate) === true)
+        return true;
     if ([...indexCandidates(candidate), posix.join(candidate, "package.json")].some((path) => {
         const file = files.get(path);
         return (file !== undefined &&
@@ -210,10 +789,16 @@ const hasContainerDirectory = (files, candidate, containerSha256) => {
             (containerSha256 === undefined ||
                 file.container_sha256 === containerSha256))
             return true;
-    return false;
+    return unanalyzedFiles?.hasDirectory(candidate, containerSha256) ?? false;
 };
 const htmlCandidate = (input) => {
     const declared = stripQueryAndFragment(htmlUrlText(input.declaredPath));
+    // HTML owns URL-text normalization and pathname admission. A nonempty URL
+    // reference may have no pathname; suffix bytes remain declaration evidence.
+    // HTML references are URL text, so percent bytes still encode.
+    const rejected = rejectDeclaration(declared, false, input.declaredPath !== "");
+    if (rejected !== null)
+        return rejected;
     if (looksExternal(declared))
         return unresolvedCandidate("external", [
             "External HTML references are not mapped to local artifact assets.",
@@ -226,23 +811,17 @@ const htmlCandidate = (input) => {
         return unresolvedCandidate("external", [
             "The document base href is external, so its script reference is not a local artifact path.",
         ]);
-    // 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 unresolvedCandidate("rejected", [
-            "Encoded dot or separator bytes are rejected before artifact path resolution.",
-        ]);
     const declaredPath = percentDecodeUrlPath(declared);
     if (declaredPath === null)
         return unresolvedCandidate("rejected", [
             "The HTML reference path percent-decodes to NUL or to bytes that are not UTF-8.",
         ]);
     if (declaredPath.startsWith("/"))
-        return declaredPath.slice(1);
+        return urlRelativeCandidate("", declaredPath);
     if (base === undefined || base === null || base === "")
         return declaredPath === ""
             ? input.sourcePath
-            : posix.join(posix.dirname(input.sourcePath), declaredPath);
+            : urlRelativeCandidate(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.
@@ -255,35 +834,33 @@ const htmlCandidate = (input) => {
         return unresolvedCandidate("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);
-    if (declaredPath === "")
-        return emptyHtmlReference(decodedBase, basePath);
-    return posix.join(htmlBaseDirectory(decodedBase, basePath), declaredPath);
-};
-const emptyHtmlReference = (base, basePath) => {
-    if (!htmlBaseIsDirectory(base))
-        return basePath;
-    const confined = confineCandidate(basePath);
+    // Keep the base's empty segments and escapes until the reference is
+    // applied; only the final path must name a canonical artifact file.
+    const baseState = applyUrlReference(urlDirectoryState(posix.dirname(input.sourcePath)), decodedBase);
+    if (declaredPath === "") {
+        const basePath = urlPathCandidate(baseState);
+        return typeof basePath === "string"
+            ? exactUrlPathCandidate(decodedBase, basePath, "HTML")
+            : basePath;
+    }
+    return urlPathCandidate(applyUrlReference(urlBaseDirectory(baseState), declaredPath));
+};
+const exactUrlPathCandidate = (declared, candidate, kind) => {
+    if (!urlPathIsDirectory(declared))
+        return candidate;
+    const confined = confineCandidate(candidate);
     if (typeof confined !== "string")
         return confined;
     return unresolvedCandidate("not-found", [
-        `The HTML reference resolves to directory ${confined || "."}, not an exact selected application file.`,
+        `The ${kind} reference resolves to directory ${confined || "."}, not an exact selected application file.`,
     ]);
 };
-/**
- * The directory a relative HTML reference resolves against. A base path
- * ending in "/" or in a "." or ".." segment is already a directory, because a
- * relative reference resolves against the base URL's directory and those
- * segments are dropped rather than stepped through.
- */
-const htmlBaseIsDirectory = (base) => base.endsWith("/") ||
-    base.endsWith("/.") ||
-    base.endsWith("/..") ||
-    base === "." ||
-    base === "..";
-const htmlBaseDirectory = (base, basePath) => htmlBaseIsDirectory(base) ? basePath : posix.dirname(basePath);
+/** Whether a URL path retains directory form after dot-segment normalization. */
+const urlPathIsDirectory = (path) => path.endsWith("/") ||
+    path.endsWith("/.") ||
+    path.endsWith("/..") ||
+    path === "." ||
+    path === "..";
 const confineCandidate = (candidate) => {
     const normalized = normalizeJoinedLogicalPath(candidate);
     if (logicalPathEscapesRoot(normalized))
@@ -296,8 +873,18 @@ const readPackageMetadata = (input, directory) => {
     const path = posix.join(directory, "package.json");
     const file = input.files.get(path);
     const source = input.files.get(input.sourcePath);
-    if (file === undefined ||
-        (source !== undefined && file.container_sha256 !== source.container_sha256))
+    if (file === undefined) {
+        const unavailable = input.unanalyzedFiles?.get(path);
+        if (source !== undefined &&
+            unavailable?.container_sha256 === source.container_sha256)
+            return {
+                kind: "unavailable",
+                limitation: unavailable.limitations?.[0] ??
+                    `Directory package metadata ${path} was inventoried but its bytes are unavailable.`,
+            };
+        return { kind: "absent" };
+    }
+    if (source !== undefined && file.container_sha256 !== source.container_sha256)
         return { kind: "absent" };
     if (!file.text.included)
         return {
@@ -315,36 +902,67 @@ const readPackageMetadata = (input, directory) => {
             limitation: `Directory package metadata ${path} is not valid package JSON.`,
         };
     }
-    return typeof value === "object" && value !== null
-        ? { kind: "available", path, value }
-        : {
+    if (typeof value !== "object" || value === null)
+        return {
             kind: "unavailable",
             limitation: `Directory package metadata ${path} is not valid package JSON.`,
         };
+    const name = Reflect.get(value, "name");
+    const exports = Reflect.get(value, "exports");
+    const imports = Reflect.get(value, "imports");
+    const main = Reflect.get(value, "main");
+    return {
+        kind: "available",
+        path,
+        name: typeof name === "string" ? name : undefined,
+        // Node's package reader ignores scalar root exports other than strings.
+        // Nested targets retain their raw values for exports validation.
+        exports: typeof exports === "string" ||
+            (typeof exports === "object" && exports !== null)
+            ? exports
+            : undefined,
+        // Import maps must be non-array objects; other shapes are not a map.
+        imports: typeof imports === "object" && imports !== null && !Array.isArray(imports)
+            ? imports
+            : undefined,
+        main: input.moduleKind !== undefined && typeof main !== "string"
+            ? undefined
+            : main,
+        module: Reflect.get(value, "module"),
+    };
 };
 /** File and directory lookup never interprets a nested directory's exports. */
-const resolveCandidate = (input, candidate, packageChain) => resolveFileCandidates(input, fileCandidates(candidate)) ??
-    resolveDirectory(input, candidate, readPackageMetadata(input, candidate), packageChain);
+const resolveCandidate = (input, candidate, packageChain, emittedSourceCandidates = []) => {
+    if (!commonJsDirectoryRequest(input)) {
+        const file = resolveFileCandidates(input, fileCandidates(candidate, input.moduleKind)) ??
+            resolveRuntimeSourceCandidates(input, candidate, emittedSourceCandidates);
+        if (file !== null)
+            return file;
+    }
+    return resolveDirectory(input, candidate, readPackageMetadata(input, candidate), packageChain);
+};
+const commonJsDirectoryRequest = (input) => input.context === "module-specifier" &&
+    input.moduleKind === "require" &&
+    (input.declaredPath.endsWith("/") ||
+        /(?:^|\/)\.{1,2}$/u.test(input.declaredPath));
 const resolveDirectory = (input, directory, metadata, packageChain) => {
     if (metadata.kind === "absent")
-        return (resolveFileCandidates(input, indexCandidates(directory)) ??
-            notFoundCandidate());
+        return (resolveFileCandidates(input, indexCandidates(directory, input.moduleKind)) ?? notFoundCandidate());
     if (metadata.kind === "unavailable")
         return unresolvedCandidate("unavailable", [metadata.limitation]);
     if (packageChain.has(metadata.path))
         return unresolvedCandidate("unavailable", [
             `Directory package entrypoint cycle includes ${metadata.path}.`,
         ]);
-    const preferred = [
-        Reflect.get(metadata.value, "main"),
-        ...(input.moduleKind === undefined
-            ? [Reflect.get(metadata.value, "module")]
-            : []),
-    ];
-    const entry = preferred.find((value) => value !== undefined);
+    const entry = metadata.main === ""
+        ? undefined
+        : metadata.main !== undefined
+            ? metadata.main
+            : input.moduleKind === undefined
+                ? metadata.module
+                : undefined;
     if (entry === undefined)
-        return (resolveFileCandidates(input, indexCandidates(directory)) ??
-            notFoundCandidate());
+        return (resolveFileCandidates(input, indexCandidates(directory, input.moduleKind)) ?? notFoundCandidate());
     if (typeof entry !== "string" || entry.length === 0)
         return unresolvedCandidate("unavailable", [
             `Directory package metadata ${metadata.path} is not valid package JSON.`,
@@ -354,43 +972,133 @@ const resolveDirectory = (input, directory, metadata, packageChain) => {
         sourcePath: metadata.path,
         context: "package-entrypoint",
         files: input.files,
+        ...(input.directoryPaths === undefined
+            ? {}
+            : { directoryPaths: input.directoryPaths }),
+        ...(input.unanalyzedFiles === undefined
+            ? {}
+            : { unanalyzedFiles: input.unanalyzedFiles }),
         ...(input.moduleKind === undefined ? {} : { moduleKind: input.moduleKind }),
     };
-    const rejected = rejectDeclaration(entryInput.declaredPath);
-    if (rejected !== null)
-        return rejected;
     const candidate = contextualCandidate(entryInput);
     if (typeof candidate !== "string")
         return candidate;
     const confined = confineCandidate(candidate);
     if (typeof confined !== "string")
         return confined;
+    if (input.moduleKind !== undefined)
+        return resolveNodePackageMain(entryInput, directory, confined);
     const selected = resolveFileCandidates(entryInput, [
-        ...fileCandidates(confined),
-        ...indexCandidates(confined),
-    ]) ?? resolveFileCandidates(input, indexCandidates(directory));
+        ...fileCandidates(confined, entryInput.moduleKind),
+        ...indexCandidates(confined, entryInput.moduleKind),
+    ]) ??
+        resolveFileCandidates(input, indexCandidates(directory, input.moduleKind));
     if (selected !== null)
         return selected;
     return resolveCandidate(entryInput, confined, new Set([...packageChain, metadata.path]));
 };
+const resolveNodePackageMain = (input, directory, mainPath) => {
+    const normalizedMain = mainPath.replace(/\/$/u, "");
+    for (const suffix of NODE_PACKAGE_MAIN_SUFFIXES) {
+        const isDirectoryIndex = suffix.startsWith("/");
+        if (normalizedMain === "" && !isDirectoryIndex)
+            continue;
+        const selected = resolveFileCandidates(input, [
+            isDirectoryIndex
+                ? posix.join(normalizedMain, suffix.slice(1))
+                : posix.normalize(`${normalizedMain}${suffix}`),
+        ]);
+        if (selected === null)
+            continue;
+        if (input.moduleKind === "require")
+            return selected;
+        // ESM probes the normalized main, then appends the selected suffix to
+        // the original declaration before finalizing the resulting file path.
+        const finalized = confineCandidate(relativeCandidate(input.sourcePath, `${input.declaredPath}${suffix}`));
+        if (typeof finalized !== "string")
+            return finalized;
+        const finalizedFile = resolveFileCandidates(input, [
+            finalized.replace(/\/$/u, ""),
+        ]);
+        if (finalizedFile !== null)
+            return finalizedFile;
+        const source = input.files.get(input.sourcePath);
+        if (hasContainerDirectory(input.files, finalized, source?.container_sha256, input.directoryPaths, input.unanalyzedFiles))
+            return {
+                ...unresolvedCandidate("rejected", [
+                    `The selected legacy ESM package main finalizes to directory ${finalized}; directory imports are unsupported and no later main or index candidate was tried.`,
+                ]),
+                candidatePath: finalized,
+            };
+        return unresolvedCandidate("not-found", [
+            `The selected legacy ESM package main finalizes to ${finalized}, which is not an inventoried file; no later main or index candidate was tried.`,
+        ]);
+    }
+    const fallback = resolveFileCandidates(input, indexCandidates(directory, input.moduleKind));
+    if (fallback !== null)
+        return fallback;
+    return input.moduleKind === "require"
+        ? { ...notFoundCandidate(), stopsAncestorLookup: true }
+        : notFoundCandidate();
+};
 const resolveFileCandidates = (input, candidates) => {
-    const source = input.files.get(input.sourcePath);
     for (const path of candidates) {
-        const target = input.files.get(path);
-        if (target !== undefined &&
-            (source === undefined ||
-                target.container_sha256 === source.container_sha256))
-            return { resolvedPath: path, status: "resolved", limitations: [] };
+        const selected = findFileCandidate(input, path);
+        if (selected === null)
+            continue;
+        return selected.status === "resolved" &&
+            isRuntimeDeclarationPath(input, path)
+            ? {
+                resolvedPath: null,
+                status: "unavailable",
+                candidatePath: path,
+                limitations: [
+                    `The TypeScript declaration ${path} is compile-time evidence and cannot identify a runtime module implementation.`,
+                ],
+            }
+            : selected;
     }
     return null;
 };
-const fileCandidates = (candidate) => [
+/** Own candidate presence and container identity independently of loader policy. */
+const findFileCandidate = (input, path) => {
+    const source = input.files.get(input.sourcePath);
+    const target = input.files.get(path);
+    if (target !== undefined &&
+        (source === undefined ||
+            target.container_sha256 === source.container_sha256))
+        return { resolvedPath: path, status: "resolved", limitations: [] };
+    const unanalyzed = input.unanalyzedFiles?.get(path);
+    if (unanalyzed !== undefined &&
+        (source === undefined ||
+            unanalyzed.container_sha256 === source.container_sha256))
+        return {
+            resolvedPath: null,
+            status: "unavailable",
+            candidatePath: path,
+            limitations: [
+                ...(unanalyzed.limitations ?? []),
+                unanalyzed.kind === undefined
+                    ? `${path} exists in the inventoried artifact container (sha256 ${unanalyzed.sha256 ?? "unknown"}, ${unanalyzed.bytes === null ? "unknown size" : `${String(unanalyzed.bytes)} bytes`}) but is not a JavaScript, JSON, HTML, source map, or native add-on file; its contents were not analyzed.`
+                    : `${path} is an inventoried ${unanalyzed.kind} file, but its bytes are unavailable (hash status ${unanalyzed.hash_status ?? "unknown"}); resolution cannot be confirmed.`,
+            ],
+        };
+    return null;
+};
+const isRuntimeDeclarationPath = (input, path) => input.moduleKind !== undefined && /\.d\.(?:ts|mts|cts)$/iu.test(path);
+const NODE_MODULE_EXTENSIONS = [".js", ".json", ".node"];
+const NODE_PACKAGE_MAIN_SUFFIXES = [
+    "",
+    ...NODE_MODULE_EXTENSIONS,
+    ...NODE_MODULE_EXTENSIONS.map((extension) => `/index${extension}`),
+];
+const fileCandidates = (candidate, moduleKind) => [
     candidate,
-    ...EXTENSIONS.map((extension) => `${candidate}${extension}`),
+    ...(moduleKind === undefined ? EXTENSIONS : NODE_MODULE_EXTENSIONS).map((extension) => `${candidate}${extension}`),
 ];
-const indexCandidates = (candidate) => EXTENSIONS.map((extension) => posix.join(candidate, `index${extension}`));
+const indexCandidates = (candidate, moduleKind) => (moduleKind === undefined ? EXTENSIONS : NODE_MODULE_EXTENSIONS).map((extension) => posix.join(candidate, `index${extension}`));
 /** Only exact non-directory keys participate; wildcard expansion is unsupported. */
-const selectPackageExport = (value, subpath, moduleKind) => {
+const selectPackageExport = (value, subpath, moduleKind, packagePath) => {
     let target = value;
     let declared = [];
     if (typeof value === "object" && value !== null && !Array.isArray(value)) {
@@ -414,23 +1122,35 @@ const selectPackageExport = (value, subpath, moduleKind) => {
     }
     else if (subpath !== ".")
         return { status: "unmatched", declared };
-    const selected = selectExportTarget(target, packageExportConditions(moduleKind));
+    const selected = selectExportTarget(target, packageExportConditions(moduleKind), packagePath);
     if (selected.kind === "invalid" || selected.kind === "invalid-config")
         return { status: "rejected", limitation: selected.limitation };
     if (selected.kind === "unmatched")
         return {
             status: "unmatched",
-            declared: typeof target === "object" && target !== null
-                ? Object.keys(target)
-                : declared,
+            declared: selected.declared,
         };
-    return selected.kind === "blocked"
-        ? { status: "blocked" }
-        : { status: "value", value: selected.value };
+    if (selected.kind === "blocked")
+        return { status: "blocked", cause: selected.cause };
+    if (selected.kind === "non-relative")
+        return {
+            status: "rejected",
+            limitation: `The package exports target ${JSON.stringify(selected.value)} must start with "./".`,
+        };
+    return {
+        status: "value",
+        value: selected.value,
+        url: selected.url,
+        ...(selected.lookupLimitation === undefined
+            ? {}
+            : {
+                lookupLimitation: selected.lookupLimitation,
+            }),
+    };
 };
-const invalidExportTarget = (value, reason) => ({
+const invalidExportTarget = (value, reason, mapKind = "exports") => ({
     kind: "invalid",
-    limitation: `The package exports target ${JSON.stringify(value) ?? String(value)} ${reason}.`,
+    limitation: `The package ${mapKind === "imports" ? "import" : "exports"} target ${JSON.stringify(value) ?? String(value)} ${reason}.`,
 });
 // Node checks raw target segments before URL normalization. Compare encoded
 // segment names here; full URL decoding follows array target selection.
@@ -443,46 +1163,79 @@ const forbiddenExportSegment = (value) => value
         segment === ".." ||
         segment.toLowerCase() === "node_modules");
 });
+const selectStringPackageTarget = (value, packagePath, mapKind) => {
+    if (mapKind === "imports") {
+        const target = classifyPackageImportTargetString(value);
+        if (target.kind === "invalid")
+            return invalidExportTarget(value, "cannot be parent-relative, absolute, or a URL", mapKind);
+        if (target.kind !== "relative")
+            return { kind: "non-relative", value };
+    }
+    else if (!value.startsWith("./"))
+        return invalidExportTarget(value, 'must start with "./"', mapKind);
+    const forbidden = forbiddenExportSegment(value);
+    if (forbidden !== undefined)
+        return invalidExportTarget(value, `contains forbidden path segment ${JSON.stringify(forbidden)} before URL normalization`, mapKind);
+    const metadataUrl = packageMetadataUrl(packagePath, value);
+    const packageUrl = metadataUrl.ok
+        ? metadataUrl.value
+        : metadataUrl.error.structuralUrl;
+    // Node constructs the URL before deciding whether this array entry is an
+    // invalid package target. Tabs/newlines and dot segments normalize here;
+    // percent decoding and existence checks belong after target selection.
+    const url = new URL(value, packageUrl);
+    if (!url.pathname.startsWith(new URL(".", packageUrl).pathname))
+        return invalidExportTarget(value, "escapes the package root after URL normalization", mapKind);
+    return {
+        kind: "value",
+        value,
+        url,
+        ...(metadataUrl.ok
+            ? {}
+            : {
+                lookupLimitation: metadataUrl.error.limitation,
+            }),
+    };
+};
+const selectArrayPackageTarget = (value, conditions, packagePath, mapKind) => {
+    if (value.length === 0)
+        return { kind: "blocked", cause: "empty-array" };
+    let lastRefusal;
+    const declared = new Set();
+    for (const entry of value) {
+        const nested = selectExportTarget(entry, conditions, packagePath, mapKind);
+        // Node's array fallback catches invalid targets, not invalid configuration.
+        if (nested.kind === "invalid-config")
+            return nested;
+        if (nested.kind === "unmatched") {
+            for (const condition of nested.declared)
+                declared.add(condition);
+            continue;
+        }
+        if (nested.kind === "invalid" || nested.kind === "blocked") {
+            lastRefusal = nested;
+            continue;
+        }
+        return nested;
+    }
+    return lastRefusal ?? { kind: "unmatched", declared: [...declared] };
+};
 /**
  * Resolve a target in Node's declared order. Explicit null blocks an active
  * condition, whereas an unmatched nested object permits the next condition.
  * An array skips unmatched and invalid entries, stops at its first string, and
- * preserves the final invalid-versus-null refusal if no string is selected.
+ * preserves the last invalid/null outcome if no string is selected. A nonempty
+ * array of unmatched conditions stays unmatched; an empty array blocks.
  */
-const selectExportTarget = (value, conditions) => {
-    if (typeof value === "string") {
-        if (!value.startsWith("./"))
-            return invalidExportTarget(value, 'must start with "./"');
-        const forbidden = forbiddenExportSegment(value);
-        return forbidden === undefined
-            ? { kind: "value", value }
-            : invalidExportTarget(value, `contains forbidden path segment ${JSON.stringify(forbidden)} before URL normalization`);
-    }
+const selectExportTarget = (value, conditions, packagePath, mapKind = "exports") => {
+    if (typeof value === "string")
+        return selectStringPackageTarget(value, packagePath, mapKind);
     if (value === null)
-        return { kind: "blocked" };
-    if (Array.isArray(value)) {
-        let invalid = null;
-        for (const entry of value) {
-            const nested = selectExportTarget(entry, conditions);
-            // Node's array fallback catches invalid targets, not invalid configuration.
-            if (nested.kind === "invalid-config")
-                return nested;
-            if (nested.kind === "invalid") {
-                invalid = nested.limitation;
-                continue;
-            }
-            if (nested.kind === "unmatched")
-                continue;
-            invalid = null;
-            if (nested.kind === "value")
-                return nested;
-        }
-        return invalid === null
-            ? { kind: "blocked" }
-            : { kind: "invalid", limitation: invalid };
-    }
+        return { kind: "blocked", cause: "null" };
+    if (Array.isArray(value))
+        return selectArrayPackageTarget(value, conditions, packagePath, mapKind);
     if (typeof value !== "object")
-        return invalidExportTarget(value, "must be a relative string, object, array, or null");
+        return invalidExportTarget(value, "must be a relative string, object, array, or null", mapKind);
     for (const key of Object.keys(value)) {
         const numeric = Number(key);
         if (String(numeric) === key && numeric >= 0 && numeric < 0xffff_ffff)
@@ -491,14 +1244,18 @@ const selectExportTarget = (value, conditions) => {
                 limitation: `The package exports configuration contains numeric condition key ${JSON.stringify(key)}.`,
             };
     }
+    const declared = new Set();
     for (const [condition, target] of Object.entries(value)) {
+        declared.add(condition);
         if (!conditions.has(condition))
             continue;
-        const nested = selectExportTarget(target, conditions);
+        const nested = selectExportTarget(target, conditions, packagePath, mapKind);
         if (nested.kind !== "unmatched")
             return nested;
+        for (const name of nested.declared)
+            declared.add(name);
     }
-    return { kind: "unmatched" };
+    return { kind: "unmatched", declared: [...declared] };
 };
 /**
  * Node selects an exports target by walking the declared keys in order and
@@ -521,21 +1278,35 @@ const notFoundCandidate = () => ({
         "No extension, directory package, or index candidate exists in the inventoried artifact container.",
     ],
 });
-const exactExportsTargetNotFound = (path) => ({
+const exactPackageTargetNotFound = (path, targetKind) => ({
     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.`,
+        `The selected package ${targetKind === "imports" ? "import" : targetKind} target ${path} does not exist in the inventoried artifact container; ${targetKind === "imports" ? "import" : targetKind} targets are exact files, so no extension or directory index was tried.`,
     ],
 });
 const fileUrlPath = (value) => {
-    if (!value.startsWith("file://"))
+    if (!/^file:\/\//iu.test(value))
         return undefined;
+    // URL parsing removes tabs and newlines and normalizes encoded dot segments.
+    // Check the raw path first, excluding URL identity suffixes, then check the
+    // parsed pathname so parser normalization cannot introduce a separator.
+    const rawPath = stripQueryAndFragment(value);
+    if (value.includes("\0") ||
+        value.includes("\\") ||
+        /[\t\n\r]/u.test(rawPath) ||
+        !admitsCanonicalPathSyntax(rawPath))
+        return null;
     try {
         const url = new URL(value);
         if (url.protocol !== "file:" || url.hostname !== "")
             return undefined;
-        return decodeURIComponent(url.pathname).replace(/^\/+/, "");
+        if (!admitsCanonicalPathSyntax(url.pathname))
+            return null;
+        const decoded = decodeURIComponent(url.pathname);
+        if (decoded.includes("\0"))
+            return null;
+        return decoded.replace(/^\/+/, "");
     }
     catch (cause) {
         // Unparseable file URLs have no path to resolve.