rea-agents 4.1.0 → 5.0.0

package/dist/application/ReconstructionCoverageService.js

@@ -1,13 +1,9 @@
-import { z } from "zod";
+import { reconstructionCoverageEvaluationInputSchema } from "../domain/reconstructionCoverageInput.js";
 import { AnalysisInputError } from "../domain/analysisErrorCore.js";
 import {} from "../domain/analysisErrorBase.js";
-import { evaluateReconstructionClosure, reconstructionCoverageDataSchema, } from "../domain/reconstructionCoverage.js";
+import { evaluateReconstructionClosure } from "../domain/reconstructionCoverage.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { err, ok } from "../domain/result.js";
-export const reconstructionCoverageEvaluationInputSchema = z.strictObject({
-    coverage: reconstructionCoverageDataSchema,
-    boundary_id: z.string().min(1),
-});
 /** Evaluate inline reconstruction coverage against a named boundary. */
 export const evaluateReconstructionCoverage = (rawInput, nowEpochMs = Date.now()) => {
     const parsed = reconstructionCoverageEvaluationInputSchema.safeParse(rawInput);

package/dist/application/ReconstructionObligationCandidates.js

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import canonicalize from "canonicalize";
 import { parseEvidenceBundle, } from "../domain/evidenceBundle.js";
 import { parseProcessCapture } from "../domain/processCapture.js";
-import { parseApplicationGraphEvidence } from "./JavaScriptApplicationEvidenceGraph.js";
+import { parseApplicationGraphEvidence } from "./javascript/JavaScriptApplicationEvidenceGraph.js";
 import { applicationObligationPolicy, semanticObligationPolicy, } from "./ReconstructionObligationPolicies.js";
 /** Derive conservative candidates from graph, process, and reviewed inputs. */
 export const deriveReconstructionObligationCandidates = (bundleInput, reviewed) => {
@@ -32,8 +32,11 @@ const deriveApplicationCandidates = (evidence, records, candidates, limitations)
         const source = parseApplicationGraphEvidence(evidence);
         for (const node of source.graph.nodes) {
             const candidatePolicy = applicationObligationPolicy(node.kind);
-            if (candidatePolicy === undefined)
+            if (candidatePolicy === undefined) {
+                if (node.kind === "unknown")
+                    limitations.add(`Application graph ${source.graph.graph_id} contains unresolved node ${node.node_id}; reconstruction obligations remain unknown.`);
                 continue;
+            }
             const reference = node.observations.map((observation) => graphReference(evidence, records, observation.evidence, `${source.graph.graph_id}/node/${node.node_id}/observation/${observation.observation_id}`));
             addCandidate(candidates, generatedCandidate({
                 key: `application:${node.node_id}:${candidatePolicy.family}`,

package/dist/application/ReferenceSourceImport.js

@@ -106,6 +106,8 @@ export const importReferenceSource = async (options) => {
         const error = readResult.error;
         if (error.code === "cancelled")
             return err(cancelled());
+        if (error.code === "unsupported")
+            return err(failure("unsupported", error.message));
         return err(failure("io", error.message));
     }
     if (isAborted(options.signal))

package/dist/application/ReferenceSourceImportEntries.js

@@ -3,12 +3,13 @@ import { posix } from "node:path";
 import { classifyReferenceSourcePath, detectReferenceSourceLanguage, } from "../domain/referenceSourceClassification.js";
 import { parseReferenceSourceImports } from "../domain/referenceSourceImportParsing.js";
 import { PARSEABLE_REFERENCE_SOURCE_LANGUAGES } from "./ReferenceSourceImportTypes.js";
-/** Project a low-level entry failure into safe import guidance. */
-export const projectReferenceSourceEntryFailure = (entry) => {
+/** Preserve the observed reader failure and add entry-specific recovery guidance. */
+export const projectReferenceSourceEntryFailure = (entry) => `${entry.message} ${entryRecoveryGuidance(entry)}`;
+const entryRecoveryGuidance = (entry) => {
     if (entry.code === "cancelled")
         return "This entry was not read because the import was cancelled. Start the import again when ready.";
     if (entry.code === "unsupported")
-        return "This entry cannot be read safely on this system. Exclude it or import the directory on a supported system.";
+        return "Exclude this entry or replace it with a regular file.";
     if (entry.kind === "directory")
         return "This directory could not be read. Check its permissions, then try again.";
     if (entry.kind === "symlink")
@@ -58,6 +59,22 @@ const resolveInternalSpecifier = (fromPath, specifier, filePaths) => {
         `${normalized}${suffix}`,
         `${normalized}/index${suffix}`,
     ]);
+    // TypeScript source commonly names the extension emitted for NodeNext.
+    // Retain present runtime files first; substitute only a missing counterpart.
+    // Counterparts cover explicit filenames, not directory/index resolution.
+    if (/\.(?:ts|tsx|mts|cts)$/u.test(fromPath)) {
+        const sourceSuffixes = normalized.endsWith(".js")
+            ? [".ts", ".tsx", ".d.ts"]
+            : normalized.endsWith(".mjs")
+                ? [".mts", ".d.mts"]
+                : normalized.endsWith(".cjs")
+                    ? [".cts", ".d.cts"]
+                    : normalized.endsWith(".jsx")
+                        ? [".tsx", ".d.ts"]
+                        : [];
+        const stem = normalized.slice(0, -posix.extname(normalized).length);
+        candidates.push(...sourceSuffixes.map((suffix) => `${stem}${suffix}`));
+    }
     const match = candidates.find((candidate) => filePaths.has(candidate));
     return match === undefined
         ? { to: normalized, resolution: "unresolved" }

package/dist/application/ReferenceSourceImportTypes.js

@@ -10,6 +10,11 @@ export const projectReferenceSourceImportError = (error) => {
             category: "invalid_input",
             message: "Reference source directory could not be opened. Check that the path exists, is readable, and points to a directory.",
         };
+    if (error.code === "unsupported")
+        return {
+            category: "unsupported_host",
+            message: "Safe no-follow file opens are unavailable on this host. Import the source tree with REA on Linux (including WSL) or macOS.",
+        };
     if (error.code === "io")
         return {
             category: "execution_failure",

package/dist/application/Setup.js

@@ -12,14 +12,22 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
     const unsupported = await hostRemediation(host, false);
     if (unsupported !== undefined)
         return fail(unsupported);
-    let hopperPath = await host.hopperPath();
-    let providerEnvironment = await initialProviderEnvironment(host, hopperPath);
+    const initialState = await host.initialSetupState?.(options.readinessScope);
+    let hopperPath = initialState === undefined
+        ? await host.hopperPath()
+        : initialState.hopperPath;
+    let providerEnvironment = initialState === undefined
+        ? await initialProviderEnvironment(host, hopperPath)
+        : initialState.providerEnvironment;
     const discovery = await discoverSetupState({
         host,
         providerEnvironment,
         forceHopperInstall: options.installHopper,
         proposeHopper: options.proposeHopper ?? (confirm !== undefined && !options.structured),
         doctorScope: options.readinessScope,
+        ...(initialState === undefined
+            ? {}
+            : { initialDoctor: initialState.doctor }),
     });
     clientStates = discovery.clientStates;
     const clientSelectionAllowed = options.clientIds === undefined &&

package/dist/application/SetupClientConfiguration.js

@@ -1,4 +1,4 @@
-import { clientRegistrationEntry, clientConfigurationValuesEqual, parseClientConfiguration, serializeClientConfiguration, } from "./ClientConfigurationDocument.js";
+import { clientRegistrationEntry, clientConfigurationValuesEqual, clientServerPath, legacyClientServerPath, parseClientConfiguration, serializeClientConfiguration, withClientServers, } from "./ClientConfigurationDocument.js";
 import { constants as fsConstants } from "node:fs";
 import { copyFile, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
@@ -43,21 +43,23 @@ const configureClientDocument = async (client, environment, command, format) =>
         void cause;
         return { status: "failed", reason: "readback" };
     }
-    const { document, servers, serversKey } = parsed;
-    const desired = clientConfigurationDesired(client, environment, command, format);
-    if (clientConfigurationValuesEqual(servers[PRODUCT_IDENTITY.mcpServerKey], desired))
+    const desired = clientConfigurationDesired(client, environment, command, parsed.dialect);
+    if (registrationCurrent(parsed, desired))
         return { status: "unchanged" };
     const backupPath = original === undefined ? undefined : `${client.configPath}.rea.backup`;
     if (backupPath !== undefined &&
         !(await preserveConfigBackup(transactionPath, backupPath)))
         return { status: "failed", reason: "backup" };
-    document[serversKey] = {
-        ...servers,
-        [PRODUCT_IDENTITY.mcpServerKey]: desired,
-    };
+    // A native OpenCode V2 entry replaces REA's legacy V1 entry, which would
+    // otherwise conflict with it.
+    const legacyPath = legacyClientServerPath(parsed, PRODUCT_IDENTITY.mcpServerKey);
+    const document = withClientServers(parsed, { ...parsed.servers, [PRODUCT_IDENTITY.mcpServerKey]: desired }, PRODUCT_IDENTITY.mcpServerKey);
     try {
         await mkdir(dirname(client.configPath), { recursive: true });
-        await writeFileAtomic(transactionPath, serializeClientConfiguration(document, format, original, PRODUCT_IDENTITY.mcpServerKey), {
+        await writeFileAtomic(transactionPath, serializeClientConfiguration(document, format, original, [
+            clientServerPath(parsed, PRODUCT_IDENTITY.mcpServerKey),
+            ...(legacyPath === undefined ? [] : [legacyPath]),
+        ]), {
             encoding: "utf8",
             mode: 0o600,
         });
@@ -69,7 +71,7 @@ const configureClientDocument = async (client, environment, command, format) =>
     }
     try {
         const readback = parseClientConfiguration(await readFile(transactionPath, "utf8"), format);
-        if (!clientConfigurationValuesEqual(readback.servers[PRODUCT_IDENTITY.mcpServerKey], desired)) {
+        if (!registrationCurrent(readback, desired)) {
             await restoreConfig(transactionPath, original);
             return { status: "failed", reason: "readback" };
         }
@@ -87,11 +89,10 @@ const configureClientDocument = async (client, environment, command, format) =>
 };
 /** Determine whether an existing client configuration matches the desired registration. */
 export const clientConfigurationAligned = async (client, providerEnvironment, command) => {
-    const desired = clientConfigurationDesired(client, providerEnvironment, command, client.format);
     try {
         const original = await readFile(client.configPath, "utf8");
-        const { servers } = parseClientConfiguration(original, client.format);
-        return clientConfigurationValuesEqual(servers[PRODUCT_IDENTITY.mcpServerKey], desired);
+        const parsed = parseClientConfiguration(original, client.format);
+        return registrationCurrent(parsed, clientConfigurationDesired(client, providerEnvironment, command, parsed.dialect));
     }
     catch (cause) {
         // Unreadable configuration is treated as not aligned so setup repairs it.
@@ -121,10 +122,10 @@ export const inspectClientConfiguration = async (client, providerEnvironment, co
             remediation: "The configuration file could not be read. Check its permissions before rerunning setup.",
         };
     }
-    const desired = clientConfigurationDesired(client, providerEnvironment, command, client.format);
     try {
-        const { servers } = parseClientConfiguration(original, client.format);
-        if (clientConfigurationValuesEqual(servers[PRODUCT_IDENTITY.mcpServerKey], desired))
+        const parsed = parseClientConfiguration(original, client.format);
+        const desired = clientConfigurationDesired(client, providerEnvironment, command, parsed.dialect);
+        if (registrationCurrent(parsed, desired))
             return { status: "already_current" };
     }
     catch (cause) {
@@ -162,6 +163,8 @@ const restoreConfig = async (path, original) => {
         void cause;
     }
 };
+/** Whether REA's entry matches and no conflicting legacy entry remains. */
+const registrationCurrent = (parsed, desired) => clientConfigurationValuesEqual(parsed.servers[PRODUCT_IDENTITY.mcpServerKey], desired) && !Object.hasOwn(parsed.legacyServers, PRODUCT_IDENTITY.mcpServerKey);
 const clientConfigurationDesired = (client, providerEnvironment, command, format) => {
     const environment = Object.fromEntries(Object.entries(providerEnvironment).sort(([left], [right]) => left.localeCompare(right)));
     const registration = clientRegistrationEntry(format ?? "json", command.length === 0 ? [PRODUCT_IDENTITY.cliBinary, "mcp"] : command, environment);

package/dist/application/SetupHost.js

@@ -2,7 +2,7 @@ import { access } from "node:fs/promises";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { PRODUCT_IDENTITY } from "../identity.js";
-import { supportsNodeVersion } from "../domain/runtimeVersion.js";
+import { SUPPORTED_NODE_VERSION_PROSE, supportsNodeVersion, } from "../domain/runtimeVersion.js";
 import { runDoctor, systemDoctorHost } from "./Doctor.js";
 import { installLinuxHopper, readLinuxDistribution } from "./LinuxHopper.js";
 import { installMacHopper } from "./MacHopper.js";
@@ -31,7 +31,7 @@ export const initialProviderEnvironment = async (host, hopperPath) => ({
 });
 export const hostRemediation = async (host, installHopper) => {
     if (!supportsNodeVersion(host.nodeVersion))
-        return "Install Node.js 22.x (>=22.19), 24.x (>=24.11), or 26+ and rerun setup.";
+        return `Install ${SUPPORTED_NODE_VERSION_PROSE} and rerun setup.`;
     if (!installHopper)
         return undefined;
     if (host.platform !== "darwin" && host.platform !== "linux")
@@ -44,7 +44,7 @@ export const hostRemediation = async (host, installHopper) => {
     }
     if ((await host.linuxDistribution())?.supported === true)
         return undefined;
-    return "Automated Hopper setup supports Ubuntu 24.04+, Fedora 41+, and 64-bit Arch Linux; configure an existing supported provider instead.";
+    return "Automated Hopper setup supports Ubuntu 24.04+, Fedora 41+, 64-bit Arch Linux, and CachyOS; configure an existing supported provider instead.";
 };
 /** Production setup effects for Hopper, agent configuration, and the canonical skill directory. */
 export const systemSetupHost = (doctorHost = systemDoctorHost()) => {
@@ -55,6 +55,21 @@ export const systemSetupHost = (doctorHost = systemDoctorHost()) => {
         macosVersion: () => doctorHost.macosVersion(),
         linuxDistribution: readLinuxDistribution,
         hopperPath: async () => (await runDoctor(undefined, doctorHost)).hopperPath,
+        initialSetupState: async (scope) => {
+            const diagnosis = await runDoctor(undefined, doctorHost, scope);
+            return {
+                ...(diagnosis.hopperPath === undefined
+                    ? {}
+                    : { hopperPath: diagnosis.hopperPath }),
+                providerEnvironment: {
+                    ...providerRegistrationEnvironment(diagnosis.providerInspections ?? []),
+                    ...(diagnosis.hopperPath === undefined
+                        ? {}
+                        : { HOPPER_LAUNCHER_PATH: diagnosis.hopperPath }),
+                },
+                doctor: diagnosis,
+            };
+        },
         providerEnvironment: async () => {
             const diagnosis = await runDoctor(undefined, doctorHost);
             return {

package/dist/application/SetupPlan.js

@@ -6,7 +6,7 @@ import { linuxHopperInstallDisclosure, } from "./LinuxHopper.js";
 import { macHopperInstallDisclosure } from "./MacHopper.js";
 /** Discover supported clients and current registrations without mutation. */
 export const discoverSetupState = async (input) => {
-    const initialDoctor = await input.host.doctor(input.doctorScope);
+    const initialDoctor = input.initialDoctor ?? (await input.host.doctor(input.doctorScope));
     const linuxHopperRepairNeeded = initialDoctor.checks.some(({ name, ok, detail }) => !ok &&
         (name === "hopper-demo-runtime" ||
             (name === "hopper-version" && detail === "/opt/hopper/bin/Hopper")));

package/dist/application/Uninstall.js

@@ -1,4 +1,4 @@
-import { parseClientConfiguration, serializeClientConfiguration, } from "./ClientConfigurationDocument.js";
+import { parseClientConfiguration, serializeClientConfiguration, clientServerPath, legacyClientServerPath, withClientServers, } from "./ClientConfigurationDocument.js";
 import { copyFile, lstat, readFile, realpath, rm } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -76,28 +76,33 @@ const removeClient = async (client, fileSystem) => {
             ? item(client.name, "skipped", "Configuration does not exist.")
             : item(client.name, "failed", "Configuration could not be read. Check file permissions, then rerun uninstall.");
     }
-    let document;
-    let key;
-    let servers;
+    let parsed;
     try {
-        ({
-            document,
-            servers,
-            serversKey: key,
-        } = parseClientConfiguration(original, client.format));
+        parsed = parseClientConfiguration(original, client.format);
     }
     catch (cause) {
         void cause;
         return item(client.name, "failed", `Configuration is not valid ${client.format === "toml" ? "TOML" : client.format === "opencode" ? "JSONC" : "JSON"} and was not changed. Repair it, then rerun uninstall.`);
     }
-    const registration = servers[PRODUCT_IDENTITY.mcpServerKey];
-    if (registration === undefined)
+    const name = PRODUCT_IDENTITY.mcpServerKey;
+    // Beside a native OpenCode V2 table, OpenCode also loads a V1 `mcp.rea`.
+    const legacyPath = legacyClientServerPath(parsed, name);
+    const hasNative = Object.hasOwn(parsed.servers, name);
+    if (!hasNative && legacyPath === undefined)
         return item(client.name, "skipped", "REA registration is absent.");
-    if (!isOwnedRegistration(registration, client))
+    const removeNative = hasNative && isOwnedRegistration(parsed.servers[name], client);
+    const removeLegacy = legacyPath !== undefined &&
+        isOwnedRegistration(parsed.legacyServers[name], client);
+    if (!removeNative && !removeLegacy)
         return item(client.name, "retained", "The rea-named registration is not REA-owned.");
-    const remaining = { ...servers };
-    delete remaining[PRODUCT_IDENTITY.mcpServerKey];
-    document[key] = remaining;
+    const remaining = { ...parsed.servers };
+    if (removeNative)
+        delete remaining[name];
+    const document = withClientServers(parsed, remaining, removeLegacy ? name : undefined);
+    const editedPaths = [
+        ...(removeNative ? [clientServerPath(parsed, name)] : []),
+        ...(removeLegacy ? [legacyPath] : []),
+    ];
     const backupPath = `${client.configPath}.rea.backup`;
     try {
         await fileSystem.copy(transactionPath, backupPath);
@@ -107,9 +112,10 @@ const removeClient = async (client, fileSystem) => {
         return item(client.name, "failed", "Configuration could not be backed up, so no change was made. Check file permissions, then rerun uninstall.");
     }
     try {
-        await fileSystem.writeText(transactionPath, serializeClientConfiguration(document, client.format, original, PRODUCT_IDENTITY.mcpServerKey));
+        await fileSystem.writeText(transactionPath, serializeClientConfiguration(document, client.format, original, editedPaths));
         const readback = parseClientConfiguration(await fileSystem.readText(transactionPath), client.format);
-        if (PRODUCT_IDENTITY.mcpServerKey in readback.servers)
+        if ((removeNative && Object.hasOwn(readback.servers, name)) ||
+            (removeLegacy && Object.hasOwn(readback.legacyServers, name)))
             throw new Error("registration readback mismatch");
         return item(client.name, "removed", `Removed registration from ${client.configPath}.`);
     }

package/dist/application/UpdateMaintenance.js

@@ -4,7 +4,7 @@ import { z } from "zod";
 import { PRODUCT_IDENTITY } from "../identity.js";
 import { isOwnedClientRegistrationCommand } from "./ClientRegistrationIdentity.js";
 import { readClientRegistrationStatuses } from "./ClientRegistrationStatus.js";
-import { parseClientConfiguration } from "./ClientConfigurationDocument.js";
+import { effectiveClientServer, parseClientConfiguration, } from "./ClientConfigurationDocument.js";
 import { supportedClients } from "./SupportedClients.js";
 const setupPlanSchema = z.object({
     status: z.literal("planned"),
@@ -32,13 +32,13 @@ export const existingMaintenanceScope = async (home, entryPoint) => {
         const client = supported.find(({ name }) => name === registration.client);
         if (client === undefined)
             continue;
-        const { servers } = parseClientConfiguration(await readFile(client.configPath, "utf8"), client.format);
+        const parsed = parseClientConfiguration(await readFile(client.configPath, "utf8"), client.format);
         const enabled = z
             .object({
             enabled: z.boolean().optional(),
             disabled: z.boolean().optional(),
         })
-            .parse(servers[PRODUCT_IDENTITY.mcpServerKey]);
+            .parse(effectiveClientServer(parsed, PRODUCT_IDENTITY.mcpServerKey));
         if (enabled.enabled !== false && enabled.disabled !== true)
             clients.push(client.name);
     }

package/dist/application/ValidateSelectedWebScript.js

@@ -0,0 +1,27 @@
+import { createHash } from "node:crypto";
+import { AnalysisOutputError } from "../domain/analysisErrorCore.js";
+import { err, ok } from "../domain/result.js";
+/** Bind actual source text to the selected manifest entry before analysis. */
+export const validateSelectedWebScript = (input, data, operation) => {
+    const selected = data.manifest.scripts[input.script_index];
+    if (selected === undefined ||
+        selected.content.state !== "exported" ||
+        selected.content.sha256 !== data.sourceFile.sha256 ||
+        selected.content.bytes !== data.sourceFile.bytes ||
+        Buffer.byteLength(data.source) !== data.sourceFile.bytes ||
+        createHash("sha256").update(data.source, "utf8").digest("hex") !==
+            data.sourceFile.sha256 ||
+        data.manifestFile.path !== input.manifest_path)
+        return err(new AnalysisOutputError(operation, "Artifact port changed the selected script/source identity."));
+    return ok(selected);
+};
+/** Carry reported capture context alongside independently verified manifest bytes. */
+export const capturedWebManifestIdentity = (data) => ({
+    ...data.manifestFile,
+    reported_output_directory: data.manifest.output_directory,
+    capture_sha256: data.manifest.capture_sha256,
+    capture_path: data.manifest.capture_path,
+    capture_kind: data.manifest.capture_kind,
+    capture_completeness: data.manifest.capture_completeness,
+    source_evidence_id: data.manifest.source_evidence_id,
+});

package/dist/application/WebModuleTraceService.js

@@ -0,0 +1,209 @@
+import { isAbsolute } from "node:path";
+import { z } from "zod";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { createEvidence } from "../domain/evidence.js";
+import { jsonObjectSchema } from "../domain/jsonValue.js";
+import { projectInputIssues } from "../domain/inputIssueProjection.js";
+import { err, ok } from "../domain/result.js";
+import { collectWebModuleImports, matchCapturedModules, } from "../domain/webModuleImports.js";
+import { webModuleTraceInputSchema, webModuleFileSchema, webModuleResolutionSchema, webModuleTraceResultSchema, } from "../domain/webModuleTrace.js";
+import { selectedWebScriptArtifactsSchema } from "../domain/webScriptArtifacts.js";
+import { capturedWebManifestIdentity, validateSelectedWebScript, } from "./ValidateSelectedWebScript.js";
+const OPERATION = "trace_web_module_imports";
+const artifactsSchema = selectedWebScriptArtifactsSchema.extend({
+    importMap: z
+        .strictObject({
+        file: webModuleFileSchema,
+        baseUrl: z.string().min(1),
+        value: jsonObjectSchema,
+    })
+        .nullable(),
+});
+const resolutionBatchSchema = z.strictObject({
+    engine: z.strictObject({ id: z.string().min(1), version: z.string().min(1) }),
+    resolutions: z.array(webModuleResolutionSchema),
+    diagnostics: z.array(z.string()),
+    rawResult: jsonObjectSchema,
+});
+const LIMITATIONS = [
+    "Resolution is derived under the selected importer URL and optional import map; it does not establish that the map was installed in the captured page.",
+    "Reported source URLs do not establish an inline script's document base. Select importer_url explicitly when that context differs or is unknown.",
+    "Captured candidates retain reported capture metadata; their bytes are not reverified by this trace unless selected as the source.",
+    "A resolved URL or captured source does not prove loading, execution, UI causality, or module namespace identity. Execution remains unknown.",
+    "Only native ES module syntax is resolved. Bundler module IDs, computed imports, workers and non-HTTP(S) importer contexts are outside this trace.",
+    "Source-map declarations do not establish retained map bytes or executed original-source coverage.",
+    "Selected application code is parsed as data and never executed. The owned resolver executes only REA's trusted stub; its page requests are locally fulfilled or blocked.",
+    "Manifest, source and import-map limits are 32 MiB, 16 MiB and 4 MiB. Native resolution has a 20-second deadline; cleanup may extend it. One renderer is requested; no aggregate host memory limit is claimed.",
+];
+/** Compose verified captures, inert syntax and a replaceable URL resolution engine. */
+export class WebModuleTraceService {
+    artifacts;
+    resolver;
+    constructor(artifacts, resolver) {
+        this.artifacts = artifacts;
+        this.resolver = resolver;
+    }
+    async trace(rawInput, options) {
+        if (isAborted(options?.signal))
+            return err(new AnalysisCancelledError(OPERATION));
+        const parsed = webModuleTraceInputSchema.safeParse(rawInput);
+        if (!parsed.success)
+            return err(new AnalysisInputError(OPERATION, { cause: parsed.error }, projectInputIssues(parsed.error.issues, rawInput)));
+        const input = parsed.data;
+        for (const [path, value] of [
+            ["manifest_path", input.manifest_path],
+            ["import_map.path", input.import_map?.path],
+        ])
+            if (value !== undefined && !isAbsolute(value))
+                return invalid(path.split("."), "Expected an absolute filesystem path on this host.");
+        for (const [path, value] of [
+            ["importer_url", input.importer_url],
+            ["import_map.base_url", input.import_map?.base_url],
+        ])
+            if (value !== undefined) {
+                const admission = admitContext(value, path.split("."));
+                if (!admission.ok)
+                    return admission;
+            }
+        const loaded = await this.artifacts.load(input, options);
+        if (!loaded.ok)
+            return loaded;
+        const verified = artifactsSchema.safeParse(loaded.value);
+        if (!verified.success)
+            return err(new AnalysisOutputError(OPERATION, "Artifact port returned a malformed source/manifest report."));
+        const data = verified.data;
+        if ((input.import_map?.path ?? null) !==
+            (data.importMap?.file.path ?? null) ||
+            (input.import_map?.base_url ?? null) !== (data.importMap?.baseUrl ?? null))
+            return err(new AnalysisOutputError(OPERATION, "Artifact port changed the selected import-map identity/context."));
+        const bound = validateSelectedWebScript(input, data, OPERATION);
+        if (!bound.ok)
+            return bound;
+        const selected = bound.value;
+        const importerUrl = input.importer_url ?? selected.url;
+        const importerAdmission = admitContext(importerUrl, ["importer_url"]);
+        if (!importerAdmission.ok)
+            return importerAdmission;
+        const syntax = collectWebModuleImports(data.source);
+        const literals = syntax.imports
+            .filter((reference) => reference.specifier !== null)
+            .map((reference) => reference.specifier ?? "");
+        let resolution = null;
+        if (literals.length > 0) {
+            const execution = await this.resolver.resolve({
+                importerUrl,
+                importMap: data.importMap === null
+                    ? null
+                    : {
+                        baseUrl: data.importMap.baseUrl,
+                        value: data.importMap.value,
+                    },
+                specifiers: literals,
+            }, options);
+            if (!execution.ok)
+                return execution;
+            const report = resolutionBatchSchema.safeParse(execution.value);
+            if (!report.success)
+                return err(new AnalysisOutputError(OPERATION, "Resolver returned malformed or incomplete native evidence."));
+            resolution = report.data;
+            if (resolution.resolutions.length !== literals.length)
+                return err(new AnalysisOutputError(OPERATION, "Resolver did not return every selected literal specifier."));
+        }
+        if (isAborted(options?.signal))
+            return err(new AnalysisCancelledError(OPERATION));
+        let literalIndex = 0;
+        const imports = [];
+        for (const reference of syntax.imports) {
+            let resolved;
+            if (reference.specifier === null)
+                resolved = { state: "unknown", reason: "computed-specifier" };
+            else {
+                const reported = resolution?.resolutions[literalIndex++];
+                if (reported === undefined)
+                    return err(new AnalysisOutputError(OPERATION, "Resolver omitted a selected literal specifier."));
+                resolved = reported;
+            }
+            imports.push({
+                ...reference,
+                resolution: resolved,
+                captured_candidates: resolved.state === "resolved"
+                    ? matchCapturedModules(resolved.url, data.manifest.scripts)
+                    : [],
+                execution: "unknown",
+            });
+        }
+        const normalized = webModuleTraceResultSchema.safeParse({
+            manifest: capturedWebManifestIdentity(data),
+            source: {
+                ...data.sourceFile,
+                script_index: input.script_index,
+                script: selected,
+            },
+            importer: {
+                url: importerUrl,
+                basis: input.importer_url === undefined
+                    ? "reported-source-url"
+                    : "caller-selected",
+            },
+            import_map: data.importMap === null
+                ? null
+                : { ...data.importMap.file, base_url: data.importMap.baseUrl },
+            parser: {
+                state: syntax.state,
+                diagnostics: syntax.diagnostics,
+                location_units: "UTF-16 offsets and columns; one-based lines",
+            },
+            engine: resolution?.engine ?? null,
+            imports,
+            diagnostics: resolution?.diagnostics ?? [],
+            limitations: LIMITATIONS,
+        });
+        if (!normalized.success)
+            return err(new AnalysisOutputError(OPERATION, normalized.error.message));
+        return ok(createEvidence({
+            path: data.sourceFile.path,
+            sha256: data.sourceFile.sha256,
+            format: "file",
+        }, {
+            id: "rea-web-module-trace",
+            name: "REA captured module relationship trace",
+            version: "1",
+        }, {
+            operation: OPERATION,
+            parameters: jsonObjectSchema.parse(input),
+            result: normalized.data,
+            rawResult: resolution?.rawResult ?? null,
+            confidence: "derived",
+            authority: "historical-reference",
+            limitations: LIMITATIONS,
+            locations: [
+                { kind: "artifact-path", path: data.sourceFile.path },
+                { kind: "artifact-path", path: input.manifest_path },
+            ],
+            evidenceLinks: data.manifest.source_evidence_id === null
+                ? []
+                : [data.manifest.source_evidence_id],
+        }));
+    }
+}
+const admitContext = (value, path) => {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch (cause) {
+        void cause;
+        return invalid(path, "Expected an absolute context URL. Select importer_url explicitly when the reported source URL is unknown.");
+    }
+    if (url.username !== "" || url.password !== "")
+        return invalid(path, "Module context URLs must not contain username/password userinfo.");
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        return err(new AnalysisCapabilityUnavailableError("web-module-resolution", OPERATION, "unsupported_context_scheme", {
+            userMessage: `${path.join(".")} ${value} uses unsupported ${url.protocol} context. This trace currently supports HTTP(S) importer/map contexts; select a supported context explicitly when appropriate.`,
+        }));
+    return ok(null);
+};
+const isAborted = (signal) => signal?.aborted === true;
+const invalid = (path, message) => err(new AnalysisInputError(OPERATION, undefined, [
+    { path, reason: "invalid_format", message },
+]));