reverseport 0.0.0-stage → 1.2.0

package/dist/artifacts/javascript/JavaScriptArtifactFiles.js

@@ -0,0 +1,317 @@
+import { createHash } from "node:crypto";
+import { isAbsolute } from "node:path";
+import { compareUnicodeCodePoints } from "../../domain/unicodeCodePointOrder.js";
+import { AsarArtifactReader } from "../AsarArtifactReader.js";
+import { ArtifactPathRegistry, normalizeArtifactPath, } from "../ArtifactPaths.js";
+import { ArtifactReaderFailure, } from "../ArtifactReader.js";
+import { streamChunkToBuffer } from "../StreamBytes.js";
+import { hashReadable } from "../ArtifactHash.js";
+import { AnalysisInputError } from "../../domain/analysisErrorCore.js";
+/** Verify inventoried entries; acquire text only inside the caller's scope. */
+export const readJavaScriptArtifactFiles = async (reader, snapshot, resources, signal, sourcePaths) => {
+    const inventory = expectedInventory(snapshot);
+    const expected = inventory.files;
+    const selectedPaths = sourcePaths === undefined
+        ? undefined
+        : new Map([...new Set(sourcePaths)].map((path, index) => [path, index]));
+    const issues = (sourcePaths ?? []).flatMap((path, index) => expected.has(path) || inventory.unavailableFiles.has(path)
+        ? []
+        : [
+            {
+                path: ["source_paths", index],
+                reason: "invalid_value",
+                message: "Select an exact relevant file path from the artifact inventory; no globs or path aliases.",
+            },
+        ]);
+    if (issues.length > 0)
+        throw new AnalysisInputError("analyze_javascript_application", undefined, issues);
+    const unavailablePath = sourcePaths?.find((path) => inventory.unavailableFiles.has(path));
+    if (unavailablePath !== undefined)
+        throw new ArtifactReaderFailure("unavailable", `Selected inventoried source bytes are unavailable: ${unavailablePath}`, {
+            partialObservation: { kind: "artifact-inventory", inventory: snapshot },
+        });
+    if (reader instanceof AsarArtifactReader) {
+        const root = snapshot.nodes.find(({ artifact_id }) => artifact_id === snapshot.manifest.root_artifact_id);
+        if (root === undefined)
+            throw new ArtifactReaderFailure("integrity", "Root artifact node is missing");
+        await verifyEntryBytes(await reader.openContainer(signal), { path: ".", sha256: root.sha256, bytes: root.size }, signal);
+    }
+    const context = {
+        resources,
+        expected,
+        expectedContainers: inventory.containers,
+        registry: new ArtifactPathRegistry(),
+        files: [],
+        containers: [],
+        signal,
+        selectedPaths,
+        textBytes: 0,
+        invalidUtf8: 0,
+    };
+    await visitReader(reader, "", snapshot.manifest.root_sha256, context);
+    const files = context.files.sort((left, right) => {
+        const leftPriority = selectedPaths?.get(left.path) ?? Infinity;
+        const rightPriority = selectedPaths?.get(right.path) ?? Infinity;
+        if (leftPriority !== rightPriority)
+            return leftPriority - rightPriority;
+        return compareUnicodeCodePoints(left.path, right.path);
+    });
+    assertExpectedFilesWereVisited(expected, files);
+    return {
+        files,
+        containers: context.containers.sort((left, right) => compareUnicodeCodePoints(left.path, right.path)),
+        text_bytes_read: context.textBytes,
+        invalid_utf8_files: context.invalidUtf8,
+        ...(sourcePaths === undefined
+            ? {}
+            : {
+                source_selection: {
+                    requested_paths: [...sourcePaths],
+                    unselected_files: files.filter(({ text }) => !text.included && text.reason === "outside-analysis-scope").length,
+                },
+            }),
+    };
+};
+const visitReader = async (reader, prefix, containerSha256, context) => {
+    const stack = [
+        {
+            reader,
+            prefix,
+            containerSha256,
+            iterator: reader.entries(context.signal)[Symbol.asyncIterator](),
+        },
+    ];
+    const ownedReaders = [];
+    let failure;
+    try {
+        while (stack.length > 0) {
+            const frame = stack.at(-1);
+            if (frame === undefined)
+                break;
+            const next = await frame.iterator.next();
+            if (next.done) {
+                stack.pop();
+                continue;
+            }
+            const entry = next.value;
+            abortIfNeeded(context.signal);
+            const path = normalizeArtifactPath(frame.prefix === "" ? entry.path : `${frame.prefix}/${entry.path}`);
+            const nestedAsar = isFilesystemAsar(entry, path);
+            context.registry.add(path, nestedAsar ? "directory" : entry.kind);
+            if (nestedAsar) {
+                const container = context.expectedContainers.get(path);
+                // Inventory deliberately does not expand unverified or unavailable
+                // nested archives. Keep the same boundary here when reconstruction
+                // reads the active entries again.
+                if (container === undefined)
+                    throw new ArtifactReaderFailure("integrity", `Nested ASAR was not present in inventory: ${path}`);
+                if (container.hash_status === "mismatched")
+                    continue;
+                if (container.hash_status === "unavailable")
+                    throw new ArtifactReaderFailure("unavailable", `Nested ASAR bytes were unavailable during inventory: ${path}`);
+                if (container.hash_status !== "verified")
+                    throw new ArtifactReaderFailure("integrity", `Nested ASAR was not integrity-verified: ${path}`);
+                const inventory = container.inventory;
+                if (inventory === null)
+                    throw new ArtifactReaderFailure("integrity", `Verified nested ASAR has no inventory node: ${path}`);
+                await verifyEntryBytes(await frame.reader.open(entry, context.signal), inventory, context.signal);
+                context.containers.push(inventory);
+                const nested = new AsarArtifactReader(entry.adapterKey);
+                ownedReaders.push({ reader: nested, path });
+                stack.push({
+                    reader: nested,
+                    prefix: path,
+                    containerSha256: inventory.sha256,
+                    iterator: nested.entries(context.signal)[Symbol.asyncIterator](),
+                });
+                await nested.prepareContainer(inventory.sha256, context.signal);
+                continue;
+            }
+            const expected = context.expected.get(path);
+            if (expected === undefined)
+                continue;
+            const text = await readText(context, {
+                reader: frame.reader,
+                entry,
+                expected,
+            });
+            context.files.push({
+                path,
+                container_sha256: frame.containerSha256,
+                sha256: expected.sha256,
+                bytes: expected.bytes,
+                inventory_artifact_id: expected.inventoryArtifactId,
+                kind: expected.kind,
+                unpacked: entry.unpacked,
+                text,
+            });
+        }
+    }
+    catch (cause) {
+        failure = { cause };
+    }
+    finally {
+        for (const { iterator, prefix, reader } of stack.reverse()) {
+            try {
+                await iterator.return?.();
+            }
+            catch (cause) {
+                failure = {
+                    cause: ArtifactReaderFailure.withCleanup(failure === undefined ? cause : failure.cause, ArtifactReaderFailure.cleanupObservation(cause, `JavaScript artifact traversal for ${prefix || reader.format}`)),
+                };
+            }
+        }
+        for (const owned of ownedReaders.reverse()) {
+            const resource = `nested ASAR reader for ${owned.path}`;
+            const cleanup = await context.resources.release({
+                kind: "reader",
+                reader: owned.reader,
+                resource,
+            });
+            if (cleanup.kind === "failed") {
+                failure = {
+                    cause: ArtifactReaderFailure.withCleanup(failure === undefined ? cleanup.cause : failure.cause, ArtifactReaderFailure.cleanupObservation(cleanup.cause, resource)),
+                };
+            }
+        }
+    }
+    if (failure !== undefined)
+        throw failure.cause;
+};
+const readText = async (context, input) => {
+    if (context.selectedPaths !== undefined &&
+        !context.selectedPaths.has(input.expected.path)) {
+        // Keep the inventory/acquisition identity check without allocating or
+        // decoding an unrelated source's text.
+        await verifyEntryBytes(await input.reader.open(input.entry, context.signal), input.expected, context.signal);
+        return { included: false, reason: "outside-analysis-scope" };
+    }
+    if (input.expected.kind === "native-addon") {
+        await verifyEntryBytes(await input.reader.open(input.entry, context.signal), input.expected, context.signal);
+        return { included: false, reason: "not-applicable" };
+    }
+    const bytes = await readAll(await input.reader.open(input.entry, context.signal), context.signal);
+    const digest = createHash("sha256").update(bytes).digest("hex");
+    if (digest !== input.expected.sha256 || bytes.length !== input.expected.bytes)
+        throw new ArtifactReaderFailure("integrity", `Artifact entry changed after inventory: ${input.expected.path}`);
+    context.textBytes += bytes.length;
+    try {
+        return {
+            included: true,
+            value: new TextDecoder("utf-8", {
+                fatal: true,
+                ignoreBOM: input.expected.kind === "javascript" ||
+                    input.expected.kind === "html",
+            }).decode(bytes),
+        };
+    }
+    catch (cause) {
+        // Non-UTF8 bytes are counted; the fixed reason preserves the schema.
+        void cause;
+        context.invalidUtf8 += 1;
+        return { included: false, reason: "invalid-utf8" };
+    }
+};
+const verifyEntryBytes = async (stream, expected, signal) => {
+    try {
+        const digest = await hashReadable(stream, signal);
+        if (digest.sha256 !== expected.sha256 || digest.bytes !== expected.bytes)
+            throw new ArtifactReaderFailure("integrity", `Artifact entry changed after inventory: ${expected.path}`);
+    }
+    catch (cause) {
+        abortIfNeeded(signal);
+        throw cause;
+    }
+};
+const expectedInventory = (snapshot) => {
+    const nodes = new Map(snapshot.nodes.map((node) => [node.artifact_id, node]));
+    const files = new Map();
+    const containers = new Map();
+    const unavailableFiles = new Set();
+    for (const occurrence of snapshot.occurrences) {
+        if (occurrence.logical_path === ".")
+            continue;
+        const isNestedAsar = occurrence.entry_kind === "file" &&
+            occurrence.logical_path.toLowerCase().endsWith(".asar");
+        if (occurrence.artifact_id === null) {
+            if (occurrence.entry_kind === "file" &&
+                relevantKind(occurrence.logical_path) !== undefined)
+                unavailableFiles.add(occurrence.logical_path);
+            if (isNestedAsar)
+                containers.set(occurrence.logical_path, {
+                    hash_status: occurrence.hash_status,
+                    inventory: null,
+                });
+            continue;
+        }
+        const node = nodes.get(occurrence.artifact_id);
+        if (node === undefined)
+            throw new ArtifactReaderFailure("integrity", `Artifact inventory node is missing: ${occurrence.logical_path}`);
+        // Inventory occurrences can have content identities for directories too.
+        // Suffixes only describe file candidates; a directory such as
+        // node_modules/@zip.js remains a graph node and must never be opened.
+        if (occurrence.entry_kind !== "file")
+            continue;
+        if (isNestedAsar)
+            containers.set(occurrence.logical_path, {
+                hash_status: occurrence.hash_status,
+                inventory: {
+                    path: occurrence.logical_path,
+                    sha256: node.sha256,
+                    bytes: node.size,
+                    inventory_artifact_id: node.artifact_id,
+                },
+            });
+        const kind = relevantKind(occurrence.logical_path);
+        if (kind === undefined)
+            continue;
+        files.set(occurrence.logical_path, {
+            path: occurrence.logical_path,
+            sha256: node.sha256,
+            bytes: node.size,
+            inventoryArtifactId: node.artifact_id,
+            kind,
+        });
+    }
+    return { files, containers, unavailableFiles };
+};
+const readAll = async (stream, signal) => {
+    const chunks = [];
+    let bytes = 0;
+    for await (const raw of stream) {
+        abortIfNeeded(signal);
+        const chunk = streamChunkToBuffer(raw);
+        bytes += chunk.length;
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks, bytes);
+};
+const assertExpectedFilesWereVisited = (expected, actual) => {
+    const observed = new Set(actual.map(({ path }) => path));
+    for (const path of expected.keys())
+        if (!observed.has(path))
+            throw new ArtifactReaderFailure("integrity", `Relevant artifact entry disappeared after inventory: ${path}`);
+};
+const relevantKind = (path) => {
+    const lower = path.toLowerCase();
+    if (lower === "package.json" || lower.endsWith("/package.json"))
+        return "package-json";
+    if (lower.endsWith(".json"))
+        return "json";
+    if (/\.(?:cjs|cts|mjs|mts|js|jsx|ts|tsx)$/u.test(lower))
+        return "javascript";
+    if (/\.html?$/u.test(lower))
+        return "html";
+    if (lower.endsWith(".map"))
+        return "source-map";
+    if (lower.endsWith(".node"))
+        return "native-addon";
+    return undefined;
+};
+const isFilesystemAsar = (entry, path) => entry.kind === "file" &&
+    path.toLowerCase().endsWith(".asar") &&
+    isAbsolute(entry.adapterKey);
+const abortIfNeeded = (signal) => {
+    if (signal?.aborted === true)
+        throw new ArtifactReaderFailure("cancelled", "JavaScript artifact reconstruction cancelled");
+};

package/dist/artifacts/javascript/JavaScriptArtifactReader.js

@@ -0,0 +1,6 @@
+import { AsarArtifactReader } from "../AsarArtifactReader.js";
+import { DirectoryArtifactReader } from "../DirectoryArtifactReader.js";
+/** Create the reader for an admitted JavaScript artifact format. */
+export const createJavaScriptArtifactReader = (path, format) => format === "asar"
+    ? new AsarArtifactReader(path)
+    : new DirectoryArtifactReader(path);

package/dist/artifacts/javascript/JavaScriptSourceAnalysis.js

@@ -0,0 +1,3 @@
+import { JavaScriptAnalysisWorker } from "../../javascript/analysis/JavaScriptAnalysisWorker.js";
+/** Construct the inert artifact analyzer; resources are acquired on the first source. */
+export const createJavaScriptSourceAnalysis = (limits, sourceCount) => new JavaScriptAnalysisWorker(limits, undefined, sourceCount);

package/dist/artifacts/readStableArtifact.js

@@ -0,0 +1,68 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+import { ArtifactReaderFailure } from "./ArtifactReader.js";
+const FILE_SYSTEM = {
+    lstat: (path) => lstat(path, { bigint: true }),
+    open,
+};
+const afterValidation = async (path, stage, read) => {
+    try {
+        return await read();
+    }
+    catch (cause) {
+        if (cause instanceof Error &&
+            "code" in cause &&
+            ["ENOENT", "ENOTDIR", "ELOOP"].includes(String(cause.code)))
+            throw new ArtifactReaderFailure("integrity", `Artifact changed ${stage}: ${path}`, { cause });
+        throw cause;
+    }
+};
+/** Read one bounded regular file and reject replacement or in-place changes. */
+export const readStableArtifact = async (path, maximumBytes, signal, fileSystem = FILE_SYSTEM) => {
+    signal?.throwIfAborted();
+    const before = await fileSystem.lstat(path);
+    if (!before.isFile() || before.isSymbolicLink())
+        throw new ArtifactReaderFailure("path", `Expected a regular file without a symlink: ${path}`);
+    if (before.size > BigInt(maximumBytes))
+        throw new ArtifactReaderFailure("limit", `Selected artifact exceeds ${String(maximumBytes)} bytes: ${path}`);
+    const file = await afterValidation(path, "before open", () => fileSystem.open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK));
+    try {
+        const initial = await file.stat({ bigint: true });
+        if (!initial.isFile() ||
+            initial.dev !== before.dev ||
+            initial.ino !== before.ino)
+            throw new ArtifactReaderFailure("integrity", `Artifact changed before open: ${path}`);
+        const chunks = [];
+        let count = 0;
+        for await (const chunk of file.createReadStream({
+            autoClose: false,
+            highWaterMark: 65536,
+        })) {
+            signal?.throwIfAborted();
+            const value = chunk;
+            if (!Buffer.isBuffer(value))
+                throw new ArtifactReaderFailure("format", `Artifact stream did not return bytes: ${path}`);
+            const bytes = value;
+            count += bytes.length;
+            if (count > maximumBytes)
+                throw new ArtifactReaderFailure("limit", `Selected artifact grew beyond its byte limit: ${path}`);
+            chunks.push(bytes);
+        }
+        const after = await file.stat({ bigint: true });
+        const current = await afterValidation(path, "during read", () => fileSystem.lstat(path));
+        if ([after, current].some((stat) => !stat.isFile() ||
+            stat.dev !== initial.dev ||
+            stat.ino !== initial.ino ||
+            stat.size !== initial.size ||
+            stat.mtimeNs !== initial.mtimeNs ||
+            stat.ctimeNs !== initial.ctimeNs) ||
+            BigInt(count) !== initial.size)
+            throw new ArtifactReaderFailure("integrity", `Artifact changed during read: ${path}`);
+        const bytes = Buffer.concat(chunks, count);
+        return { bytes, sha256: createHash("sha256").update(bytes).digest("hex") };
+    }
+    finally {
+        await file.close();
+    }
+};

package/dist/browser/BrowserProcessStartup.js

@@ -0,0 +1,89 @@
+import { readFile } from "node:fs/promises";
+/** Safe diagnostics for a browser process that did not publish a CDP port. */
+export class BrowserStartupError extends Error {
+    _tag = "BrowserStartupError";
+    failure;
+    executable;
+    elapsedMs;
+    exitCode;
+    signalCode;
+    stderr;
+    constructor(diagnostics, options) {
+        super(browserStartupMessage(diagnostics.failure, diagnostics), options);
+        this.failure = diagnostics.failure;
+        this.executable = diagnostics.executable;
+        this.elapsedMs = diagnostics.elapsedMs;
+        this.exitCode = diagnostics.exitCode;
+        this.signalCode = diagnostics.signalCode;
+        this.stderr = diagnostics.stderr;
+    }
+}
+/** Wait for Chrome's valid DevToolsActivePort or a terminal process outcome. */
+export const waitForBrowserDevtoolsPort = async (options) => {
+    const timeoutMs = options.timeoutMs ?? 15_000;
+    const pollIntervalMs = options.pollIntervalMs ?? 25;
+    const startedAt = performance.now();
+    const terminal = childTermination(options, startedAt);
+    const deadline = startedAt + timeoutMs;
+    while (true) {
+        const terminalState = currentTerminalState(options.child);
+        if (terminalState !== null)
+            throw startupError(options, startedAt, terminalState);
+        const port = await readDevtoolsPort(options.activePortPath);
+        if (port !== null)
+            return port;
+        const remainingMs = deadline - performance.now();
+        if (remainingMs <= 0)
+            throw startupError(options, startedAt, { failure: "timeout" });
+        const outcome = await Promise.race([
+            terminal,
+            delay(Math.min(pollIntervalMs, remainingMs)).then(() => null),
+        ]);
+        if (outcome !== null)
+            throw outcome;
+    }
+};
+const childTermination = (options, startedAt) => new Promise((resolve) => {
+    options.child.once("error", (cause) => {
+        resolve(startupError(options, startedAt, {
+            failure: "spawn-error",
+            cause,
+        }));
+    });
+    options.child.once("exit", () => {
+        resolve(startupError(options, startedAt, options.child.signalCode === null
+            ? { failure: "exited" }
+            : { failure: "signalled" }));
+    });
+});
+const currentTerminalState = (child) => {
+    if (child.signalCode !== null)
+        return { failure: "signalled" };
+    if (child.exitCode !== null)
+        return { failure: "exited" };
+    return null;
+};
+const startupError = (options, startedAt, state) => new BrowserStartupError({
+    failure: state.failure,
+    executable: options.executable,
+    elapsedMs: Math.max(0, Math.round(performance.now() - startedAt)),
+    exitCode: options.child.exitCode,
+    signalCode: options.child.signalCode,
+    stderr: options.stderr(),
+}, state.failure === "spawn-error" ? { cause: state.cause } : undefined);
+const readDevtoolsPort = async (path) => {
+    try {
+        const firstLine = (await readFile(path, "utf8")).trim().split("\n")[0];
+        const port = Number(firstLine);
+        return Number.isSafeInteger(port) && port > 0 && port <= 65_535
+            ? port
+            : null;
+    }
+    catch (cause) {
+        // Missing or unreadable port files mean the port is unknown.
+        void cause;
+        return null;
+    }
+};
+const delay = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+const browserStartupMessage = (failure, diagnostics) => `Chrome CDP startup ${failure}; executable=${diagnostics.executable}; elapsed_ms=${String(diagnostics.elapsedMs)}; exit_code=${diagnostics.exitCode === null ? "null" : String(diagnostics.exitCode)}; signal=${diagnostics.signalCode ?? "null"}; stderr=${diagnostics.stderr.length === 0 ? "<empty>" : diagnostics.stderr}`;

package/dist/browser/BrowserScenarioPartialObservation.js

@@ -0,0 +1,127 @@
+import { PLAYWRIGHT_RESPONSE_BODY_PROVENANCE_LIMITATION } from "../domain/browserNetworkEvidence.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { AnalysisCancelledError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { BrowserObservationError } from "../domain/browserObservationError.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY } from "./providerIdentities.js";
+const OPERATION = "capture_browser_scenario";
+const browserScenarioLimitations = (session, scenario, events) => {
+    const capturedResponseBody = scenario.capture.network.response_body &&
+        events.some((event) => event.kind === "network-content" &&
+            event.phase === "response" &&
+            event.body.state === "captured" &&
+            (event.body.representation === "playwright-response-body-bytes" ||
+                event.body.representation === "browser-decoded-response-bytes"));
+    return [
+        "Event sequence records provider receipt order; simultaneous browser causality is not inferred.",
+        "Network content is retained only when selected; Playwright response-body bytes are API results and are not guaranteed to match wire bytes.",
+        "Request bytes are limited to what Playwright exposes; not_exposed does not establish body absence or multipart file coverage.",
+        "Network content reads settle within 5 seconds each and the observer does not request bodies from unfinished responses.",
+        ...(capturedResponseBody
+            ? [PLAYWRIGHT_RESPONSE_BODY_PROVENANCE_LIMITATION]
+            : []),
+        "Playwright scenario events do not expose request initiator stacks; receipt order does not prove causality.",
+        "Storage values are hashed only after declared-secret redaction.",
+        ...(scenario.storage.local_storage.length === 0 &&
+            scenario.storage.session_storage.length === 0
+            ? []
+            : [
+                "Non-cookie storage seeds use CDP pre-script instrumentation; only pauses in the scenario's private seed script are resumed by this observer.",
+            ]),
+        ...(session.eventLimitations?.() ?? []),
+        ...(session.mode === "connect"
+            ? [
+                "CDP attachment cannot recover pre-attach events or guarantee launch-time context options.",
+            ]
+            : []),
+    ];
+};
+/** Project one session into the common capture fields used by success and failure. */
+export const browserScenarioCaptureData = (input) => {
+    const events = input.session.events();
+    return {
+        browser: {
+            mode: input.session.mode,
+            process_ownership: input.session.processOwnership,
+            cleanup: input.cleanup,
+            product: input.session.product,
+            version: input.session.version,
+        },
+        scenario: {
+            start_origin: new URL(input.scenario.start_url.url).origin,
+            action_count: input.scenario.actions.length,
+            secret_references: input.scenario.secrets
+                .map(({ secret_id: id }) => id)
+                .sort(),
+            network_content: input.scenario.capture.network,
+        },
+        duration_ms: Date.now() - input.startedAt,
+        steps: [...input.steps],
+        events,
+        limitations: [
+            ...browserScenarioLimitations(input.session, input.scenario, events.items),
+            ...(input.limitations ?? []),
+        ],
+    };
+};
+/** Describe the cleanup failure without discarding its resource evidence. */
+export const browserScenarioCleanupObservation = (cause) => cause instanceof AnalysisError && cause.cleanup !== undefined
+    ? cause.cleanup
+    : {
+        reason: cause instanceof Error ? cause.message : String(cause),
+        resources: cause instanceof AnalysisError && cause.cleanupResources.length > 0
+            ? cause.cleanupResources
+            : ["browser_transport"],
+    };
+/** Retain operation diagnostics and capture data after cleanup settles. */
+export const browserScenarioOperationFailure = (cause, partialObservation, cleanupFailure) => {
+    const primary = cause instanceof AnalysisError
+        ? cause
+        : new ProviderAdapterError(PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY.id, OPERATION, { cause });
+    const primaryProjection = projectAnalysisError(primary);
+    const cleanupCause = cleanupFailure === undefined
+        ? undefined
+        : cleanupFailure.cause instanceof AnalysisError
+            ? cleanupFailure.cause
+            : new ProviderAdapterError(PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY.id, "close_browser_scenario", { cause: cleanupFailure.cause });
+    const cleanupObservation = cleanupFailure === undefined
+        ? undefined
+        : browserScenarioCleanupObservation(cleanupFailure.cause);
+    const retainedOptions = {
+        cause: primary,
+        partialObservation,
+        ...(primary.capturedOutput === undefined
+            ? {}
+            : { capturedOutput: primary.capturedOutput }),
+        ...(primary.cleanup === undefined ? {} : { cleanup: primary.cleanup }),
+    };
+    if (cleanupCause === undefined) {
+        if (primary instanceof AnalysisCancelledError)
+            return new AnalysisCancelledError(primary.operation, retainedOptions);
+        if (primary instanceof AnalysisTimeoutError)
+            return new AnalysisTimeoutError(primary.operation, primary.timeoutMs, retainedOptions);
+        if (primary instanceof BrowserObservationError)
+            return new BrowserObservationError(primary.operation, primary.reason, {
+                ...retainedOptions,
+                ...(primary.userMessage === undefined
+                    ? {}
+                    : { detail: primary.userMessage }),
+            });
+    }
+    const cleanup = cleanupObservation ?? primary.cleanup;
+    return new ProviderAdapterError(PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY.id, OPERATION, {
+        ...retainedOptions,
+        cause: cleanupCause === undefined
+            ? primary
+            : new AggregateError([primary, cleanupCause], "Browser scenario operation and cleanup both failed", { cause: primary }),
+        userMessage: primaryProjection.message,
+        ...(cleanup === undefined ? {} : { cleanup }),
+        diagnostics: {
+            primary_error: primaryProjection,
+            ...(cleanupCause === undefined
+                ? {}
+                : { cleanup_error: projectAnalysisError(cleanupCause) }),
+        },
+    });
+};