reverseport 0.0.0-stage → 1.2.0

package/dist/application/WebModuleTraceService.js

@@ -0,0 +1,214 @@
+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 { 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";
+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;
+    }
+    close() {
+        return this.resolver.close?.() ?? Promise.resolve();
+    }
+    async trace(rawInput, options) {
+        if (isAborted(options?.signal))
+            return err(new AnalysisCancelledError(OPERATION));
+        const parsed = webModuleTraceInputSchema.safeParse(rawInput);
+        if (!parsed.success)
+            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],
+            ["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/WebNetworkCapturePort.js

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

package/dist/application/WebNetworkCaptureService.js

@@ -0,0 +1,134 @@
+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 { 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";
+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(analysisInputErrorFromIssues(OPERATION, parsed.error.issues, rawInput, {
+                cause: parsed.error,
+            }));
+        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/WebRuntimePort.js

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

package/dist/application/WebRuntimeService.js

@@ -0,0 +1,75 @@
+import { z } from "zod";
+import { AnalysisCancelledError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { createEvidence } from "../domain/evidence.js";
+import { jsonObjectSchema, jsonValueSchema } from "../domain/jsonValue.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";
+/** 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(analysisInputErrorFromIssues(operation, parsed.error.issues, rawInput, {
+            cause: parsed.error,
+        }));
+};

package/dist/application/WebScriptArtifactPort.js

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

package/dist/application/WebScriptExportService.js

@@ -0,0 +1,214 @@
+import { createHash } from "node:crypto";
+import { isAbsolute } from "node:path";
+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 { AnalysisAccessDeniedError, AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { createEvidence } from "../domain/evidence.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
+import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { err, ok } from "../domain/result.js";
+import { safeParseJson } from "../domain/safeJson.js";
+import { exportWebScriptsInputSchema, } from "../domain/webScriptExport.js";
+import { WebScriptExportError } from "../domain/webScriptExportError.js";
+import { WEB_SCRIPT_EXPORT_PROVIDER as PROVIDER } from "./InvestigationProviders.js";
+import { readRegularFile, RegularFileCleanupFailure, retryRegularFileCleanup, } from "./RegularFileRead.js";
+import { NonRegularFileReadError, RegularFileChangedError, } from "../filesystem/RegularFile.js";
+const OPERATION = "export_web_scripts";
+/** Export one local capture through the shared CLI/MCP application workflow. */
+export const exportWebScripts = async (rawInput, resources, options = {}) => {
+    const input = exportWebScriptsInputSchema.safeParse(rawInput);
+    return input.success
+        ? exportWebScriptsValidated(input.data, resources, options)
+        : err(analysisInputErrorFromIssues(OPERATION, input.error.issues, rawInput));
+};
+/** Publish input already parsed by a named adapter contract. */
+export const exportWebScriptsValidated = async (input, resources, options = {}) => {
+    if (!isAbsolute(input.capture_path) || !isAbsolute(input.output_directory))
+        return err(new AnalysisInputError(OPERATION, undefined, [
+            {
+                path: [],
+                reason: "invalid_format",
+                message: "capture_path and output_directory must be absolute filesystem paths on this host.",
+            },
+        ]));
+    try {
+        options.signal?.throwIfAborted();
+        const prepared = await prepareCapture(input.capture_path, resources, options.signal);
+        if (!prepared.ok)
+            return prepared;
+        const { bytes, loaded } = prepared.value;
+        options.signal?.throwIfAborted();
+        const sha256 = createHash("sha256").update(bytes).digest("hex");
+        const result = await publishWebScripts(input, loaded, sha256, {
+            resources,
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+        });
+        return ok(createEvidence({ path: input.capture_path, sha256, format: "file" }, PROVIDER, {
+            predicateType: "rea.web-script-export",
+            operation: OPERATION,
+            parameters: {
+                capture_path: input.capture_path,
+                output_directory: input.output_directory,
+            },
+            result: jsonValueSchema.parse(result),
+            rawResult: null,
+            confidence: "derived",
+            authority: "historical-reference",
+            limitations: result.limitations,
+            locations: [{ kind: "artifact-path", path: result.manifest.path }],
+            evidenceLinks: loaded.sourceEvidenceId === null ? [] : [loaded.sourceEvidenceId],
+        }));
+    }
+    catch (cause) {
+        return err(mapExportFailure(cause, input, options.signal));
+    }
+};
+const prepareCapture = async (path, resources, signal) => {
+    const read = await resources.run(() => readCapture(path, resources, signal));
+    if (!read.ok)
+        return read;
+    const cleanup = read.value.cleanup;
+    const loaded = parseCapture(read.value.bytes, cleanup === undefined || cleanup.incomplete
+        ? undefined
+        : { cause: cleanup.cause });
+    if (!loaded.ok)
+        return err(cleanup?.incomplete === true
+            ? incompleteCaptureCleanup(loaded.error, path, cleanup)
+            : loaded.error);
+    if (cleanup !== undefined) {
+        const primary = new WebScriptExportError("io", path, `Capture handle close failed: ${cleanup.reason}`, { cause: cleanup.cause });
+        return err(cleanup.incomplete
+            ? incompleteCaptureCleanup(primary, path, cleanup)
+            : primary);
+    }
+    return ok({ bytes: read.value.bytes, loaded: loaded.value });
+};
+const mapExportFailure = (cause, input, signal) => {
+    if (cause instanceof WebScriptExportError)
+        return cause;
+    if (cause instanceof ArtifactReaderFailure && cause.cleanup !== undefined)
+        return analysisErrorWithCleanupFailure(new WebScriptExportError(cause.reason, input.output_directory, cause.message, { cause }), new ProviderCleanupError(PROVIDER.id, cause.cleanup.resources, { reason: cause.cleanup.reason }, { cause, operation: OPERATION }), OPERATION);
+    if (signal?.aborted === true)
+        return new AnalysisCancelledError(OPERATION, { cause });
+    if (cause instanceof ArtifactReaderFailure)
+        return new WebScriptExportError(cause.reason, input.output_directory, cause.message, { cause });
+    if (cause instanceof z.ZodError)
+        return new AnalysisOutputError(OPERATION, cause.message, { cause });
+    if (cause instanceof Error &&
+        "code" in cause &&
+        typeof cause.code === "string")
+        return new WebScriptExportError("io", `${input.capture_path} → ${input.output_directory}`, cause.message, { cause });
+    return new ProviderAdapterError(PROVIDER.id, OPERATION, {
+        cause,
+        diagnostics: {
+            capture_path: input.capture_path,
+            output_directory: input.output_directory,
+            error_name: cause instanceof Error ? cause.name : "UnknownError",
+            error_message: cause instanceof Error
+                ? cause.message
+                : typeof cause === "string"
+                    ? cause
+                    : "Unknown script export failure",
+        },
+    });
+};
+/**
+ * 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, resources, signal) => {
+    try {
+        return ok({ bytes: await readRegularFile(path, { signal }) });
+    }
+    catch (cause) {
+        if (cause instanceof RegularFileCleanupFailure) {
+            const retry = await retryRegularFileCleanup(cause, resources);
+            const cleanup = {
+                reason: retry.cleanup?.reason ?? errorMessage(cause.cleanupCause),
+                incomplete: retry.cleanup !== undefined,
+                cause: cause.cleanupCause,
+            };
+            if (cause.outcome.kind === "completed")
+                return ok({ bytes: cause.outcome.value, cleanup });
+            const primary = captureReadFailure(path, cause.outcome.cause, signal, retry.cleanup === undefined ? { cause: cause.cleanupCause } : undefined);
+            return err(retry.cleanup === undefined
+                ? primary
+                : incompleteCaptureCleanup(primary, path, cleanup));
+        }
+        return err(captureReadFailure(path, cause, signal));
+    }
+};
+const captureReadFailure = (path, cause, signal, closeFailure) => {
+    const causeWithClose = closeFailure === undefined
+        ? cause
+        : new AggregateError([cause, closeFailure.cause], "Capture read and file-handle close both failed", { cause });
+    if (signal?.aborted === true)
+        return new AnalysisCancelledError(OPERATION, { cause: causeWithClose });
+    const code = cause instanceof Error && "code" in cause ? String(cause.code) : "";
+    if (code === "EACCES" || code === "EPERM")
+        return new AnalysisAccessDeniedError(OPERATION, path, code, {
+            cause: causeWithClose,
+        });
+    if (cause instanceof NonRegularFileReadError ||
+        cause instanceof RegularFileChangedError ||
+        code === "ENOENT" ||
+        code === "ENOTDIR" ||
+        code === "EISDIR" ||
+        code === "ENXIO")
+        return new AnalysisInputError(OPERATION, { cause: causeWithClose }, [
+            {
+                path: ["capture_path"],
+                reason: "invalid_value",
+                message: cause instanceof NonRegularFileReadError && code !== "EISDIR"
+                    ? cause.message
+                    : code === "EISDIR"
+                        ? `Selected capture is a directory, not a file: ${path}`
+                        : `Selected capture could not be read (${code}): ${path}`,
+            },
+        ]);
+    if (code !== "")
+        return new WebScriptExportError("io", path, errorMessage(cause), {
+            cause: causeWithClose,
+        });
+    return new ProviderAdapterError(PROVIDER.id, OPERATION, {
+        cause: causeWithClose,
+        diagnostics: {
+            capture_path: path,
+            error_name: cause instanceof Error ? cause.name : "UnknownError",
+            error_message: cause instanceof Error ? cause.message : String(cause),
+        },
+    });
+};
+const incompleteCaptureCleanup = (primary, path, cleanup) => analysisErrorWithCleanupFailure(primary, new ProviderCleanupError(PROVIDER.id, [path], { reason: cleanup.reason }, { cause: cleanup.cause, operation: OPERATION }), OPERATION);
+const errorMessage = (cause) => cause instanceof Error ? cause.message : String(cause);
+const parseCapture = (bytes, closeFailure) => {
+    try {
+        const text = new TextDecoder("utf-8", {
+            fatal: true,
+            ignoreBOM: true,
+        }).decode(bytes);
+        const json = safeParseJson(text);
+        if (!json.ok)
+            throw new TypeError(json.error);
+        return ok(selectScriptCapture(json.value));
+    }
+    catch (cause) {
+        const causeWithClose = closeFailure === undefined
+            ? cause
+            : new AggregateError([cause, closeFailure.cause], "Capture parse and file-handle close both failed", { cause });
+        return err(new AnalysisInputError(OPERATION, { cause: causeWithClose }, [
+            {
+                path: ["capture_path"],
+                reason: "invalid_format",
+                message: cause instanceof Error
+                    ? cause.message
+                    : "Capture is not valid UTF-8 JSON evidence.",
+            },
+        ]));
+    }
+};

package/dist/application/WebSourceLocationPorts.js

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