rea-agents 4.1.0 → 6.0.0

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 },
+]));

package/dist/application/WebNetworkCaptureService.js

@@ -0,0 +1,132 @@
+import { redactExplicitFailure } from "../domain/explicitSensitiveFailure.js";
+import { excludeCaptureCoordinates } from "../domain/webNetworkCaptureCoordinates.js";
+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 { jsonObjectSchema } from "../domain/jsonValue.js";
+import { err, ok } from "../domain/result.js";
+import { inspectWebNetworkCaptureInputSchema, webNetworkCaptureSchema, } from "../domain/webNetworkCapture.js";
+const OPERATION = "inspect_web_network_capture";
+/** Shared CLI/MCP historical inspection preserves caller selection and producer record identity. */
+export class WebNetworkCaptureService {
+    port;
+    constructor(port) {
+        this.port = port;
+    }
+    /** Return selected complete records inline, without inventing live browser attribution. */
+    async inspect(rawInput, options) {
+        if (options?.signal?.aborted)
+            return err(new AnalysisCancelledError(OPERATION));
+        const declarations = inspectWebNetworkCaptureInputSchema.shape.sensitive_values.safeParse(typeof rawInput === "object" &&
+            rawInput !== null &&
+            "sensitive_values" in rawInput
+            ? rawInput.sensitive_values
+            : undefined);
+        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)));
+        const input = parsed.data;
+        if (!isAbsolute(input.capture_path))
+            return failure(new AnalysisInputError(OPERATION, undefined, [
+                {
+                    path: ["capture_path"],
+                    reason: "invalid_format",
+                    message: "Expected an absolute filesystem path on this host.",
+                },
+            ]));
+        if (input.record_ordinals !== undefined &&
+            new Set(input.record_ordinals).size !== input.record_ordinals.length)
+            return failure(new AnalysisInputError(OPERATION, undefined, [
+                {
+                    path: ["record_ordinals"],
+                    reason: "invalid_format",
+                    message: "Each requested producer ordinal must occur once.",
+                },
+            ]));
+        const loaded = await this.port.inspect(input, options);
+        if (!loaded.ok)
+            return failure(loaded.error);
+        if (options?.signal?.aborted)
+            return failure(new AnalysisCancelledError(OPERATION));
+        const report = webNetworkCaptureSchema.safeParse(loaded.value);
+        if (!report.success)
+            return failure(new AnalysisOutputError(OPERATION, "Capture adapter returned malformed historical evidence."));
+        const value = report.data;
+        const artifactSha256 = value.artifact.sha256;
+        if (artifactSha256 === null)
+            return failure(new AnalysisOutputError(OPERATION, "Capture adapter omitted its observed artifact digest before explicit projection."));
+        if (value.artifact.path !== input.capture_path ||
+            value.format !== input.format ||
+            value.total_records !== value.records.length ||
+            value.records.some((record, index) => record.ordinal !== index))
+            return failure(new AnalysisOutputError(OPERATION, "Capture adapter changed the selected artifact, format or original record sequence."));
+        const safeValue = excludeCaptureCoordinates(value, input.sensitive_values);
+        const redactText = (text) => redactExplicitText(text, input.sensitive_values);
+        const selected = input.record_ordinals ?? value.records.map(({ ordinal }) => ordinal);
+        const records = [];
+        for (const ordinal of selected) {
+            const record = safeValue.records[ordinal];
+            if (record === undefined)
+                return failure(new AnalysisInputError(OPERATION, undefined, [
+                    {
+                        path: ["record_ordinals"],
+                        reason: "invalid_format",
+                        message: `Producer ordinal ${ordinal} is outside the retained capture (${value.total_records} records).`,
+                    },
+                ]));
+            records.push({
+                ...record,
+                limitations: record.limitations.map(redactText),
+            });
+        }
+        const safePath = input.sensitive_values.some((literal) => input.capture_path.includes(literal))
+            ? ""
+            : input.capture_path;
+        const safeSha256 = input.sensitive_values.some((literal) => artifactSha256.includes(literal))
+            ? null
+            : artifactSha256;
+        const subjectUnavailableReason = redactText("The explicitly sensitive artifact digest is excluded; its cryptographic identity is unknown in this Evidence.");
+        const limitations = [
+            ...safeValue.limitations,
+            ...(safePath === ""
+                ? [
+                    "The explicitly sensitive artifact path is excluded; its size remains available.",
+                ]
+                : []),
+        ].map(redactText);
+        const parameters = jsonObjectSchema.parse({
+            capture_path: safePath,
+            ...(input.sensitive_values.some((literal) => input.format.includes(literal))
+                ? {}
+                : { format: input.format }),
+            record_ordinals: selected,
+            sensitive_value_count: input.sensitive_values.length,
+        });
+        return ok(createEvidence(safeSha256 === null
+            ? undefined
+            : {
+                path: safePath,
+                sha256: safeSha256,
+                format: "file",
+            }, value.decoder, {
+            operation: OPERATION,
+            parameters,
+            result: {
+                ...safeValue,
+                artifact: { ...value.artifact, path: safePath, sha256: safeSha256 },
+                records,
+                limitations: safeSha256 === null
+                    ? [...limitations, subjectUnavailableReason]
+                    : limitations,
+            },
+            confidence: "observed",
+            authority: "historical-reference",
+            limitations,
+            ...(safeSha256 === null ? { subjectUnavailableReason } : {}),
+            locations: safePath === "" ? [] : [{ kind: "artifact-path", path: safePath }],
+        }));
+    }
+}

package/dist/application/WebRuntimeService.js

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import { AnalysisCancelledError, AnalysisInputError, 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 { err, ok } from "../domain/result.js";
+import { observeWebExecutionInputSchema, webExecutionSchema, } from "../domain/webExecution.js";
+import { inspectWebEventListenersInputSchema, webEventListenersSchema, } from "../domain/webEventListeners.js";
+/** Shared public workflows keep instrumentation and listener inspection independently selectable. */
+export class WebRuntimeService {
+    provider;
+    constructor(provider) {
+        this.provider = provider;
+    }
+    /** Observe externally triggered execution; selection authorizes the declared instrumentation. */
+    async observe(rawInput, options) {
+        const operation = "observe_web_execution";
+        const parsed = parseInput(observeWebExecutionInputSchema, rawInput, operation, options);
+        if (!parsed.ok)
+            return parsed;
+        const result = await this.provider.observeExecution(parsed.value, options);
+        if (!result.ok)
+            return result;
+        const verified = webExecutionSchema.safeParse(result.value);
+        if (!verified.success)
+            return err(new AnalysisOutputError(operation, verified.error.message));
+        if (verified.data.target.target_id !== parsed.value.target_id ||
+            verified.data.window.requested_ms !== parsed.value.observation_ms)
+            return err(new AnalysisOutputError(operation, "Provider changed the selected target or requested window."));
+        return this.evidence(operation, parsed.value, verified.data, options);
+    }
+    /** Inspect one selected node's listener declarations without dispatching an event. */
+    async inspect(rawInput, options) {
+        const operation = "inspect_web_event_listeners";
+        const parsed = parseInput(inspectWebEventListenersInputSchema, rawInput, operation, options);
+        if (!parsed.ok)
+            return parsed;
+        const result = await this.provider.inspectEventListeners(parsed.value, options);
+        if (!result.ok)
+            return result;
+        const verified = webEventListenersSchema.safeParse(result.value);
+        if (!verified.success)
+            return err(new AnalysisOutputError(operation, verified.error.message));
+        if (verified.data.target.target_id !== parsed.value.target_id ||
+            verified.data.selected_node.selector !== parsed.value.selector)
+            return err(new AnalysisOutputError(operation, "Provider changed the selected target or node selector."));
+        return this.evidence(operation, parsed.value, verified.data, options);
+    }
+    evidence(operation, input, result, options) {
+        if (options?.signal?.aborted)
+            return err(new AnalysisCancelledError(operation));
+        if (input.allowed_origins.length > 0 &&
+            !input.allowed_origins.includes(result.target.origin))
+            return err(new AnalysisOutputError(operation, "Provider returned a document outside the selected origin scope."));
+        return ok(createEvidence(undefined, this.provider.identity(), {
+            predicateType: `rea.${operation.replaceAll("_", "-")}`,
+            operation,
+            parameters: jsonObjectSchema.parse(input),
+            result: jsonValueSchema.parse(result),
+            confidence: "observed",
+            authority: "external-service",
+            limitations: result.limitations,
+        }));
+    }
+}
+const parseInput = (schema, rawInput, operation, options) => {
+    if (options?.signal?.aborted)
+        return err(new AnalysisCancelledError(operation));
+    const parsed = schema.safeParse(rawInput);
+    return parsed.success
+        ? ok(parsed.data)
+        : err(new AnalysisInputError(operation, { cause: parsed.error }, projectInputIssues(parsed.error.issues, rawInput)));
+};