rea-agents 6.0.0 → 6.2.0

package/dist/application/Uninstall.js

@@ -1,16 +1,17 @@
 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 { constants as fsConstants } from "node:fs";
+import { homeDirectoryFromEnvironment } from "../config/homeDirectory.js";
 import { join } from "node:path";
 import writeFileAtomic from "write-file-atomic";
 import { z } from "zod";
 import { PRODUCT_IDENTITY } from "../identity.js";
 import { isOwnedClientRegistrationCommand } from "./ClientRegistrationIdentity.js";
 import { resolveClientConfigTransactionPath } from "./ClientConfigPath.js";
-import { supportedClients } from "./SupportedClients.js";
+import { manualRegistrationRemediation, supportedClients, } from "./SupportedClients.js";
 const systemFileSystem = {
     readText: (path) => readFile(path, "utf8"),
-    copy: (source, destination) => copyFile(source, destination),
+    copy: (source, destination) => copyFile(source, destination, fsConstants.COPYFILE_EXCL),
     writeText: (path, contents) => writeFileAtomic(path, contents, { encoding: "utf8" }),
     stat: (path) => lstat(path),
     realpath: (path) => realpath(path),
@@ -30,14 +31,26 @@ export const isUninstallFailure = (result) => {
         }
     }
 };
-/** Remove only REA-owned registrations and managed files, optionally including local state. */
+/**
+ * Remove only REA-owned registrations and managed files, optionally including
+ * local state. A client configuration that cannot be read safely stops the
+ * operation before anything is removed; one that fails during removal stops
+ * the remaining removals.
+ */
 export const runUninstall = async (purgeData, host = systemUninstallHost()) => {
-    const items = [];
-    for (const client of await host.clients())
-        items.push(await host.removeClient(client));
-    items.push(await host.removeSkill());
-    if (purgeData)
-        items.push(...(await host.purgeData()));
+    const clients = await host.clients();
+    const blocked = [];
+    for (const client of clients) {
+        const blocking = await host.inspectClient(client);
+        if (blocking !== undefined)
+            blocked.push(blocking);
+    }
+    const items = blocked.length > 0
+        ? [
+            ...blocked,
+            item("uninstall", "skipped", "No REA registration, skill, or data was removed. Repair each failed configuration, then rerun uninstall."),
+        ]
+        : await removeAll(clients, purgeData, host);
     items.push({
         name: "analysis_engine",
         status: "retained",
@@ -50,40 +63,80 @@ export const runUninstall = async (purgeData, host = systemUninstallHost()) => {
         items,
     };
 };
+/**
+ * Each client is reread when it is edited, so a concurrent change is never
+ * overwritten. A client that fails then still stops the remaining removals.
+ */
+const removeAll = async (clients, purgeData, host) => {
+    const items = [];
+    for (const client of clients) {
+        const removed = await host.removeClient(client);
+        items.push(removed);
+        if (removed.status === "failed")
+            return [
+                ...items,
+                item("uninstall", "skipped", "Uninstall stopped at this failure; the items above report what changed. Repair the failed configuration, then rerun uninstall."),
+            ];
+    }
+    items.push(await host.removeSkill());
+    if (purgeData)
+        items.push(...(await host.purgeData()));
+    return items;
+};
 /** Create uninstall effects contained to detected client configs and REA-owned paths. */
-export const systemUninstallHost = (home = homedir(), fileSystem = systemFileSystem) => ({
-    clients: () => Promise.resolve(supportedClients(home)),
-    removeClient: (client) => removeClient(client, fileSystem),
-    removeSkill: () => removeManagedSkills(home, fileSystem),
-    purgeData: async () => [
-        await removeManagedPath(join(home, ".rea/cache"), "cache", fileSystem),
-        await removeManagedPath(join(home, ".rea/state"), "state", fileSystem),
-    ],
-});
-const removeClient = async (client, fileSystem) => {
+export const systemUninstallHost = (selectedHome = undefined, fileSystem = systemFileSystem, environment = process.env, platform = process.platform) => {
+    const home = selectedHome ?? homeDirectoryFromEnvironment(environment, platform);
+    return {
+        clients: () => Promise.resolve(supportedClients(home, platform, environment)),
+        inspectClient: async (client) => {
+            const read = await readClientConfiguration(client, fileSystem);
+            return read.kind === "item" && read.item.status === "failed"
+                ? read.item
+                : undefined;
+        },
+        removeClient: (client) => removeClient(client, fileSystem),
+        removeSkill: () => removeManagedSkills(home, fileSystem),
+        purgeData: async () => [
+            await removeManagedPath(join(home, ".rea/cache"), "cache", fileSystem),
+            await removeManagedPath(join(home, ".rea/state"), "state", fileSystem),
+        ],
+    };
+};
+const readClientConfiguration = async (client, fileSystem) => {
     if (client.format === "unsupported")
-        return item(client.name, "skipped", "This client has no documented local MCP configuration boundary.");
+        return itemRead(item(client.name, "skipped", manualRegistrationRemediation(client.name) ??
+            "This client has no documented local MCP configuration boundary."));
     const resolved = await resolveUninstallConfigPath(client, fileSystem);
     if (typeof resolved !== "string")
-        return resolved;
+        return itemRead(resolved);
     const transactionPath = resolved;
     let original;
     try {
         original = await fileSystem.readText(transactionPath);
     }
     catch (cause) {
-        return isMissing(cause)
+        return itemRead(isMissing(cause)
             ? item(client.name, "skipped", "Configuration does not exist.")
-            : item(client.name, "failed", "Configuration could not be read. Check file permissions, then rerun uninstall.");
+            : item(client.name, "failed", "Configuration could not be read. Check file permissions, then rerun uninstall."));
     }
-    let parsed;
     try {
-        parsed = parseClientConfiguration(original, client.format);
+        const parsed = parseClientConfiguration(original, client.format);
+        return { kind: "configuration", transactionPath, original, parsed };
     }
     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.`);
+        return itemRead(item(client.name, "failed", `Configuration is not valid ${client.format === "toml" || client.format === "grok" ? "TOML" : client.format === "opencode" ? "JSONC" : "JSON"} and was not changed. Repair it, then rerun uninstall.`));
     }
+};
+const itemRead = (result) => ({
+    kind: "item",
+    item: result,
+});
+const removeClient = async (client, fileSystem) => {
+    const read = await readClientConfiguration(client, fileSystem);
+    if (read.kind === "item")
+        return read.item;
+    const { transactionPath, original, parsed } = read;
     const name = PRODUCT_IDENTITY.mcpServerKey;
     // Beside a native OpenCode V2 table, OpenCode also loads a V1 `mcp.rea`.
     const legacyPath = legacyClientServerPath(parsed, name);
@@ -108,8 +161,8 @@ const removeClient = async (client, fileSystem) => {
         await fileSystem.copy(transactionPath, backupPath);
     }
     catch (cause) {
-        void cause;
-        return item(client.name, "failed", "Configuration could not be backed up, so no change was made. Check file permissions, then rerun uninstall.");
+        if (!(cause instanceof Error && "code" in cause && cause.code === "EEXIST"))
+            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, editedPaths));

package/dist/application/Update.js

@@ -25,6 +25,23 @@ export const updateInstallCommand = (installation, version) => [
     installation.prefix,
     `${PRODUCT_IDENTITY.packageName}@${version}`,
 ];
+const versionCheckRemediation = (release) => {
+    if (release.ok) {
+        return "REA received invalid version metadata. Check the installed version and npm registry, then rerun rea update.";
+    }
+    const failure = release.error;
+    const kind = failure.kind;
+    switch (kind) {
+        case "unavailable":
+            return `REA could not resolve the latest release: ${failure.detail}. Retry rea update when registry access is available.`;
+        case "invalid-metadata":
+            return `REA could not resolve the latest release: ${failure.detail}. Check the npm release metadata, then rerun rea update.`;
+        default: {
+            const exhaustive = kind;
+            throw new TypeError(`Unhandled release lookup failure: ${String(exhaustive)}`);
+        }
+    }
+};
 /** Identify, resolve, install, and verify REA without applying setup changes. */
 export const runUpdate = async (currentVersion, host, output = "human") => {
     const installation = await host.installation();
@@ -37,9 +54,7 @@ export const runUpdate = async (currentVersion, host, output = "human") => {
             currentVersion,
             latestVersion,
             reason: "version-check",
-            remediation: release.ok
-                ? "REA received invalid version metadata. Check the installed version and npm registry, then rerun rea update."
-                : `REA could not resolve the latest release: ${release.error}. Retry rea update when registry access is available.`,
+            remediation: versionCheckRemediation(release),
         };
     if (!gt(targetVersion, currentVersion))
         return {

package/dist/application/UpdateMaintenance.js

@@ -21,9 +21,11 @@ const setupPlanSchema = z.object({
     })),
 });
 /** Discover owned registrations and an existing REA skill without writes. */
-export const existingMaintenanceScope = async (home, entryPoint) => {
-    const registrations = await readClientRegistrationStatuses(home, entryPoint);
-    const supported = supportedClients(home);
+export const existingMaintenanceScope = async (home, entryPoint, environment) => {
+    const registrations = await readClientRegistrationStatuses(home, entryPoint, {
+        environment,
+    });
+    const supported = supportedClients(home, process.platform, environment);
     const clients = [];
     for (const registration of registrations) {
         if ((registration.state !== "aligned" && registration.state !== "stale") ||
@@ -56,9 +58,9 @@ export const existingMaintenanceScope = async (home, entryPoint) => {
     return { clients, skill };
 };
 /** Ask the verified new executable to plan only existing REA integrations. */
-export const planIntegrationMaintenance = async (home, entryPoint, execute) => {
+export const planIntegrationMaintenance = async (home, entryPoint, environment, execute) => {
     try {
-        const scope = await existingMaintenanceScope(home, entryPoint);
+        const scope = await existingMaintenanceScope(home, entryPoint, environment);
         if (scope.clients.length === 0 && !scope.skill)
             return { status: "current", plannedActions: [] };
         const command = [

package/dist/application/UpdateRuntime.js

@@ -1,21 +1,21 @@
 import { realpath } from "node:fs/promises";
-import { homedir } from "node:os";
+import { homeDirectoryFromEnvironment } from "../config/homeDirectory.js";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import spawn from "cross-spawn";
-import { z } from "zod";
 import { PRODUCT_IDENTITY } from "../identity.js";
 import { err, ok } from "../domain/result.js";
+import { safeParseJson } from "../domain/safeJson.js";
 import { updateInstallCommand, } from "./Update.js";
 import { planIntegrationMaintenance } from "./UpdateMaintenance.js";
 /** Run an updater subprocess with complete diagnostics and isolated machine output. */
-export const runUpdateCommand = (command, output = "structured") => new Promise((resolveResult) => {
+export const runUpdateCommand = (command, selectedEnvironment, output = "structured") => new Promise((resolveResult) => {
     const [executable, ...args] = command;
     if (executable === undefined) {
         resolveResult(err("No executable supplied."));
         return;
     }
-    const environment = { ...process.env };
+    const environment = { ...selectedEnvironment };
     // A fresh installed entry point must not inherit npx's invocation identity.
     delete environment.npm_command;
     const child = spawn(executable, args, {
@@ -46,8 +46,8 @@ export const runUpdateCommand = (command, output = "structured") => new Promise(
                 ? `Process exited with code ${String(code)}.`
                 : `Process terminated by ${signal}.`))));
 });
-const requireCommandOutput = async (command) => {
-    const result = await runUpdateCommand(command);
+const requireCommandOutput = async (command, environment) => {
+    const result = await runUpdateCommand(command, environment);
     if (!result.ok)
         throw new Error(result.error);
     return result.value;
@@ -85,45 +85,66 @@ export const detectNpmInstallation = async (packageRoot, host) => {
         return undefined;
     return { prefix: dirname(library), packageRoot: canonicalPackageRoot };
 };
+const INVALID_NPM_RELEASE_METADATA = "Invalid npm release metadata: expected a version string or a single-element version array.";
+/** npm view arguments for dist-tags.latest, scoped to the owning prefix when known. */
+export const npmLatestVersionCommand = (installation) => [
+    "npm",
+    "view",
+    "--global",
+    ...(installation === undefined ? [] : ["--prefix", installation.prefix]),
+    PRODUCT_IDENTITY.packageName,
+    "dist-tags.latest",
+    "--json",
+    "--fetch-retries=0",
+    "--fetch-timeout=10000",
+];
+/**
+ * Read one latest version from `npm view --json`.
+ * npm 11 emits a JSON string. npm 12 emits that string as a one-element array.
+ */
+export const parseNpmLatestVersion = (metadata) => {
+    const decoded = safeParseJson(metadata);
+    if (!decoded.ok)
+        return err(decoded.error);
+    const version = readNpmLatestVersion(decoded.value);
+    return version === undefined
+        ? err(INVALID_NPM_RELEASE_METADATA)
+        : ok(version);
+};
+const readNpmLatestVersion = (value) => {
+    if (typeof value === "string")
+        return nonemptyVersion(value);
+    if (!Array.isArray(value) || value.length !== 1)
+        return undefined;
+    const only = value[0];
+    return typeof only === "string" ? nonemptyVersion(only) : undefined;
+};
+const nonemptyVersion = (value) => value.length === 0 ? undefined : value;
+/** Classify npm view output as a version or a lookup failure. */
+export const npmReleaseLookup = (response) => {
+    if (!response.ok)
+        return err({ kind: "unavailable", detail: response.error });
+    const parsed = parseNpmLatestVersion(response.value);
+    return parsed.ok
+        ? ok(parsed.value)
+        : err({ kind: "invalid-metadata", detail: parsed.error });
+};
 /** Create npm, registry, verification, and read-only maintenance effects. */
-export const systemUpdateHost = (packageRoot = fileURLToPath(new URL("../..", import.meta.url)), home = homedir()) => ({
+export const systemUpdateHost = (packageRoot = fileURLToPath(new URL("../..", import.meta.url)), home = undefined, environment = process.env) => ({
     installation: () => detectNpmInstallation(packageRoot, {
         canonicalPath: realpath,
-        globalRoot: () => requireCommandOutput(["npm", "root", "--global"]),
-        globalPrefix: () => requireCommandOutput(["npm", "prefix", "--global"]),
+        globalRoot: () => requireCommandOutput(["npm", "root", "--global"], environment),
+        globalPrefix: () => requireCommandOutput(["npm", "prefix", "--global"], environment),
     }),
-    latestVersion: async (installation) => {
-        const response = await runUpdateCommand([
-            "npm",
-            "view",
-            "--global",
-            ...(installation === undefined ? [] : ["--prefix", installation.prefix]),
-            PRODUCT_IDENTITY.packageName,
-            "dist-tags.latest",
-            "--json",
-            "--fetch-retries=0",
-            "--fetch-timeout=10000",
-        ]);
-        if (!response.ok)
-            return response;
-        try {
-            const parsed = z.string().min(1).safeParse(JSON.parse(response.value));
-            return parsed.success
-                ? ok(parsed.data)
-                : err(`Invalid npm release metadata: ${parsed.error.message}`);
-        }
-        catch (cause) {
-            return err(cause instanceof Error ? cause.message : String(cause));
-        }
-    },
+    latestVersion: async (installation) => npmReleaseLookup(await runUpdateCommand(npmLatestVersionCommand(installation), environment)),
     installVersion: async (installation, version, output) => {
-        const result = await runUpdateCommand(updateInstallCommand(installation, version), output);
+        const result = await runUpdateCommand(updateInstallCommand(installation, version), environment, output);
         return result.ok ? ok(undefined) : result;
     },
     installedVersion: (installation) => runUpdateCommand([
         process.execPath,
         join(installation.packageRoot, "scripts", "rea.mjs"),
         "--version",
-    ]),
-    planMaintenance: (installation) => planIntegrationMaintenance(home, join(installation.packageRoot, "scripts", "rea.mjs"), runUpdateCommand),
+    ], environment),
+    planMaintenance: (installation) => planIntegrationMaintenance(home ?? homeDirectoryFromEnvironment(environment, process.platform), join(installation.packageRoot, "scripts", "rea.mjs"), environment, (command) => runUpdateCommand(command, environment)),
 });

package/dist/application/WebModuleTraceService.js

@@ -3,7 +3,7 @@ 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 { analysisInputErrorFromIssues } 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";
@@ -48,7 +48,9 @@ export class WebModuleTraceService {
             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)));
+            return err(analysisInputErrorFromIssues(OPERATION, parsed.error.issues, rawInput, {
+                cause: parsed.error,
+            }));
         const input = parsed.data;
         for (const [path, value] of [
             ["manifest_path", input.manifest_path],

package/dist/application/WebNetworkCaptureService.js

@@ -4,7 +4,7 @@ import { redactExplicitText } from "../domain/explicitSensitiveValues.js";
 import { isAbsolute } from "node:path";
 import { AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
 import { createEvidence } from "../domain/evidence.js";
-import { projectInputIssues } from "../domain/inputIssueProjection.js";
+import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
 import { jsonObjectSchema } from "../domain/jsonValue.js";
 import { err, ok } from "../domain/result.js";
 import { inspectWebNetworkCaptureInputSchema, webNetworkCaptureSchema, } from "../domain/webNetworkCapture.js";
@@ -27,7 +27,9 @@ export class WebNetworkCaptureService {
         const failure = (error) => err(redactExplicitFailure(error, declarations.success ? declarations.data : []));
         const parsed = inspectWebNetworkCaptureInputSchema.safeParse(rawInput);
         if (!parsed.success)
-            return failure(new AnalysisInputError(OPERATION, { cause: parsed.error }, projectInputIssues(parsed.error.issues, rawInput)));
+            return failure(analysisInputErrorFromIssues(OPERATION, parsed.error.issues, rawInput, {
+                cause: parsed.error,
+            }));
         const input = parsed.data;
         if (!isAbsolute(input.capture_path))
             return failure(new AnalysisInputError(OPERATION, undefined, [

package/dist/application/WebRuntimeService.js

@@ -1,8 +1,8 @@
 import { z } from "zod";
-import { AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { AnalysisCancelledError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
 import { createEvidence } from "../domain/evidence.js";
 import { jsonObjectSchema, jsonValueSchema } from "../domain/jsonValue.js";
-import { projectInputIssues } from "../domain/inputIssueProjection.js";
+import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
 import { err, ok } from "../domain/result.js";
 import { observeWebExecutionInputSchema, webExecutionSchema, } from "../domain/webExecution.js";
 import { inspectWebEventListenersInputSchema, webEventListenersSchema, } from "../domain/webEventListeners.js";
@@ -69,5 +69,7 @@ const parseInput = (schema, rawInput, operation, options) => {
     const parsed = schema.safeParse(rawInput);
     return parsed.success
         ? ok(parsed.data)
-        : err(new AnalysisInputError(operation, { cause: parsed.error }, projectInputIssues(parsed.error.issues, rawInput)));
+        : err(analysisInputErrorFromIssues(operation, parsed.error.issues, rawInput, {
+            cause: parsed.error,
+        }));
 };

package/dist/application/WebScriptExportService.js

@@ -5,9 +5,9 @@ import { z } from "zod";
 import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
 import { publishWebScripts } from "../browser/assets/PublishWebScripts.js";
 import { selectScriptCapture } from "../browser/assets/ScriptCaptureAdapters.js";
-import { AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { AnalysisAccessDeniedError, AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
 import { createEvidence } from "../domain/evidence.js";
-import { projectInputIssues } from "../domain/inputIssueProjection.js";
+import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import { err, ok } from "../domain/result.js";
@@ -21,7 +21,7 @@ export const exportWebScripts = async (rawInput, options = {}) => {
     const input = exportWebScriptsInputSchema.safeParse(rawInput);
     return input.success
         ? exportWebScriptsValidated(input.data, options)
-        : err(new AnalysisInputError(OPERATION, undefined, projectInputIssues(input.error.issues, rawInput)));
+        : err(analysisInputErrorFromIssues(OPERATION, input.error.issues, rawInput));
 };
 /** Publish input already parsed by a named adapter contract. */
 export const exportWebScriptsValidated = async (input, options = {}) => {
@@ -35,9 +35,10 @@ export const exportWebScriptsValidated = async (input, options = {}) => {
         ]));
     try {
         options.signal?.throwIfAborted();
-        const bytes = await readFile(input.capture_path, {
-            signal: options.signal,
-        });
+        const read = await readCapture(input.capture_path, options.signal);
+        if (!read.ok)
+            return read;
+        const bytes = read.value;
         const loaded = parseCapture(bytes);
         if (!loaded.ok)
             return loaded;
@@ -90,6 +91,31 @@ export const exportWebScriptsValidated = async (input, options = {}) => {
         }));
     }
 };
+/**
+ * Read the caller-selected capture. A missing, non-file or unreadable
+ * selection is a caller or host-permission failure, not an export failure.
+ */
+const readCapture = async (path, signal) => {
+    try {
+        return ok(await readFile(path, { signal }));
+    }
+    catch (cause) {
+        const code = cause instanceof Error && "code" in cause ? String(cause.code) : "";
+        if (code === "EACCES" || code === "EPERM")
+            return err(new AnalysisAccessDeniedError(OPERATION, path, code, { cause }));
+        if (code === "ENOENT" || code === "ENOTDIR" || code === "EISDIR")
+            return err(new AnalysisInputError(OPERATION, { cause }, [
+                {
+                    path: ["capture_path"],
+                    reason: "invalid_value",
+                    message: code === "EISDIR"
+                        ? `Selected capture is a directory, not a file: ${path}`
+                        : `Selected capture could not be read (${code}): ${path}`,
+                },
+            ]));
+        throw cause;
+    }
+};
 const parseCapture = (bytes) => {
     try {
         const text = new TextDecoder("utf-8", {

package/dist/application/WebSourceLocationService.js

@@ -3,7 +3,7 @@ import { isAbsolute } from "node:path";
 import { z } from "zod";
 import { AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
 import { createEvidence } from "../domain/evidence.js";
-import { projectInputIssues } from "../domain/inputIssueProjection.js";
+import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
 import { jsonObjectSchema } from "../domain/jsonValue.js";
 import { err, ok } from "../domain/result.js";
 import { selectedWebScriptArtifactsSchema, webArtifactFileSchema, } from "../domain/webScriptArtifacts.js";
@@ -41,7 +41,9 @@ export class WebSourceLocationService {
             return err(new AnalysisCancelledError(OPERATION));
         const parsed = webSourceLocationInputSchema.safeParse(rawInput);
         if (!parsed.success)
-            return err(new AnalysisInputError(OPERATION, { cause: parsed.error }, projectInputIssues(parsed.error.issues, rawInput)));
+            return err(analysisInputErrorFromIssues(OPERATION, parsed.error.issues, rawInput, {
+                cause: parsed.error,
+            }));
         const input = parsed.data;
         const admitted = admitContext(input);
         if (!admitted.ok)

package/dist/application/WorkflowEvidence.js

@@ -0,0 +1,105 @@
+import { REA_WORKFLOW_PROVIDER, workflowAnalysisProfile, } from "./InvestigationProviders.js";
+import { analysisProfileSchema, committedProviderSchema, } from "../domain/analysisProfile.js";
+import { createEvidence, } from "../domain/evidence.js";
+import { UnknownRegistryError } from "../domain/unknownRegistryError.js";
+/** Build the shared Evidence record for a successful composed binary workflow. */
+export const createWorkflowEvidence = (input) => createEvidence(input.target, REA_WORKFLOW_PROVIDER, {
+    operation: input.operation,
+    parameters: input.parameters,
+    result: input.result,
+    ...(input.upstreamProfile === undefined
+        ? {}
+        : {
+            analysisProfile: workflowAnalysisProfile(input.upstreamProfile, input.operation),
+        }),
+    confidence: "derived",
+    limitations: ["Derived by an REA composed workflow."],
+    ...(input.operation === "batch_decompile"
+        ? { locations: batchProcedureLocations(input.result) }
+        : {}),
+});
+const batchProcedureLocations = (result) => {
+    if (result === null ||
+        typeof result !== "object" ||
+        Array.isArray(result) ||
+        !Array.isArray(result.items))
+        return [];
+    const addresses = new Set();
+    for (const item of result.items) {
+        if (item === null || typeof item !== "object" || Array.isArray(item))
+            continue;
+        const procedure = item.procedure;
+        if (procedure !== null &&
+            typeof procedure === "object" &&
+            !Array.isArray(procedure) &&
+            procedure.status === "resolved" &&
+            typeof procedure.address === "string")
+            addresses.add(procedure.address);
+    }
+    return [...addresses].map((address) => ({ kind: "address", address }));
+};
+/** Convert workflow Evidence into its exact replay binding, when it has a profile. */
+export const workflowSnapshotRecord = (evidence, operation) => {
+    if (evidence.analysis_profile === null)
+        return undefined;
+    return {
+        operation,
+        parameters: evidence.parameters,
+        execution: {
+            result: evidence.normalized_result,
+            rawResult: evidence.raw_result,
+            provider: committedProviderSchema.parse(evidence.provider),
+            analysisProfile: analysisProfileSchema.parse(evidence.analysis_profile),
+            limitations: evidence.limitations,
+            locations: evidence.locations,
+            subject: evidence.subject === null
+                ? null
+                : {
+                    path: evidence.subject.local_path,
+                    sha256: evidence.subject.digest.sha256,
+                    format: evidence.subject.format,
+                    ...(evidence.subject.architecture === null
+                        ? {}
+                        : { architecture: evidence.subject.architecture }),
+                },
+        },
+    };
+};
+/** Retain residual workflow questions using the shared investigation policy. */
+export const recordWorkflowUnknowns = ({ name, result, evidenceId, recordUnknown, }) => {
+    if (!["trace_feature", "trace_call_path", "inspect_native_api"].includes(name) ||
+        recordUnknown === undefined ||
+        typeof result !== "object" ||
+        result === null ||
+        Array.isArray(result) ||
+        !Array.isArray(result.residual_unknowns))
+        return { ok: true, value: null };
+    for (const question of result.residual_unknowns) {
+        if (typeof question !== "string")
+            continue;
+        const recorded = recordUnknown({
+            question,
+            severity: "medium",
+            domain: name === "inspect_native_api" ? "native-api" : "control-flow",
+            supporting_evidence_ids: [evidenceId],
+            contradicting_evidence_ids: [],
+            required_authority: "shipped-artifact",
+            required_confidence: "observed",
+            required_environment: null,
+            recommended_probes: [
+                {
+                    operation: name,
+                    rationale: name === "inspect_native_api"
+                        ? "Confirm the unsupported boundary with a capable provider or ABI probe."
+                        : "Continue with a focused query or another available provider.",
+                },
+            ],
+            relationships: [],
+        });
+        if (!recorded.ok &&
+            !(recorded.error instanceof UnknownRegistryError &&
+                recorded.error.reason === "already-exists"))
+            return recorded;
+    }
+    return { ok: true, value: null };
+};