rea-agents 6.3.0 → 6.5.0

package/dist/server/toolResult.js

@@ -1,10 +1,29 @@
+import { INSPECT_ANALYSIS_VIEW_OPERATION } from "../domain/analysisView/analysisViewErrors.js";
 import { STDIO_DEFAULT_MAX_BUFFER_SIZE } from "@modelcontextprotocol/server";
-import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
-import {} from "../domain/analysisErrorBase.js";
+import { inspectAnalysisViewInputSchema } from "../domain/analysisView/analysisView.js";
+import { projectAnalysisError, } from "../domain/analysisErrorProjection.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
 import { AnalysisResourceConstraintError } from "../domain/analysisErrorCore.js";
-import { encodeToolResult, MCP_RESULT_STRING_LIMIT, } from "./toolResultEncoding.js";
+import { encodeToolResult, MCP_RESULT_STRING_LIMIT, TARGET_CONTENT_RESULT_META, } from "./toolResultEncoding.js";
 /** Create one delivery policy from the already selected, parsed response budget. */
 export const createToolResultDelivery = (maximumResponseBytes) => new ToolResultDelivery(maximumResponseBytes ?? STDIO_DEFAULT_MAX_BUFFER_SIZE);
+/** Offer a named, schema-validated source page only for retained native analysis. */
+const nativeEvidenceContinuation = (evidence) => {
+    if (evidence.operation !== "analyze_function")
+        return {};
+    const input = inspectAnalysisViewInputSchema.safeParse({
+        source: { kind: "retained-evidence", evidence_id: evidence.evidence_id },
+        view: { kind: "native", facet: "pseudocode", offset: 0 },
+    });
+    if (!input.success)
+        return {};
+    return {
+        continuation: {
+            name: INSPECT_ANALYSIS_VIEW_OPERATION,
+            arguments: jsonValueSchema.parse(input.data),
+        },
+    };
+};
 /** Immutable encoding and recovery policy shared by one MCP server. */
 export class ToolResultDelivery {
     resultBudgetBytes;
@@ -16,12 +35,12 @@ export class ToolResultDelivery {
     toCallToolResult(result, contract) {
         return result.ok
             ? this.successResult(contract.kind === "session" ? { result: result.value } : result.value, contract)
-            : this.toErrorToolResult(result.error);
+            : this.toErrorToolResult(result.error, contract.returnsTargetContent);
     }
     /** Deliver Evidence using the producer's explicit recording acknowledgment. */
     toEvidenceToolResult(evidence, contract, recorded) {
         return recorded !== undefined && !recorded.ok
-            ? this.toErrorToolResult(recorded.error)
+            ? this.toErrorToolResult(recorded.error, contract.returnsTargetContent)
             : this.successResult(evidence, contract, {
                 evidence_id: evidence.evidence_id,
                 ...(recorded === undefined
@@ -31,36 +50,67 @@ export class ToolResultDelivery {
                             kind: "retained-evidence",
                             evidence_id: evidence.evidence_id,
                         },
+                        ...nativeEvidenceContinuation(evidence),
                     }),
             });
     }
-    /** Project an error without allocating oversized repeated MCP text. */
-    toErrorToolResult(error) {
-        const structuredContent = { error: projectAnalysisError(error) };
+    /**
+     * Project an error without allocating oversized repeated MCP text.
+     * `targetContent` is the failing tool's `returnsTargetContent`: a failure
+     * can carry target-derived text (a message, captured output, or a partial
+     * observation), so it is marked exactly like that tool's successful results.
+     */
+    toErrorToolResult(error, targetContent) {
+        return this.projectedErrorResult(projectAnalysisError(error), targetContent);
+    }
+    /** Deliver the original failure with the producer-acknowledged partial Evidence reference. */
+    toRecordedPartialErrorToolResult(error, evidenceId, recorded, targetContent) {
+        if (!recorded.ok)
+            return this.toErrorToolResult(error, targetContent);
+        const projected = projectAnalysisError(error);
+        return this.projectedErrorResult({
+            ...projected,
+            details: {
+                ...projected.details,
+                partial_observation: {
+                    kind: "retained-evidence",
+                    evidence_id: evidenceId,
+                },
+            },
+        }, targetContent);
+    }
+    projectedErrorResult(projected, targetContent) {
+        const structuredContent = { error: projected };
         // Errors reach the wire as text only; the structured copy is a private
         // carrier the transport removes after its own budget check.
-        const encoded = encodeToolResult(structuredContent, this.resultBudgetBytes, "text");
+        const encoded = encodeToolResult(structuredContent, this.resultBudgetBytes, "error-text", targetContent);
         // The transport retains an oversized projected error before replacing it
         // with a recoverable delivery constraint, using this same budget.
         return {
             content: encoded.ok ? [{ type: "text", text: encoded.text }] : [],
             structuredContent,
             isError: true,
+            ...(targetContent ? { _meta: TARGET_CONTENT_RESULT_META } : {}),
         };
     }
     successResult(value, contract, recovery = {}) {
-        const encoded = encodeToolResult(value, this.resultBudgetBytes);
+        const encoded = encodeToolResult(value, this.resultBudgetBytes, "structured-and-text", contract.returnsTargetContent);
         if (encoded.ok)
             return {
                 content: [{ type: "text", text: encoded.text }],
                 structuredContent: value,
+                ...(contract.returnsTargetContent
+                    ? { _meta: TARGET_CONTENT_RESULT_META }
+                    : {}),
             };
         const retainedEvidence = recovery.evidence_reference !== undefined;
-        const recoveryAdvice = retainedEvidence
-            ? "Export retained evidence to consume the complete analysis, or use complete CLI JSON output."
-            : encoded.constraint === "string-length"
-                ? "Use complete CLI JSON output to consume the analysis."
-                : "Use a larger MCP response budget with a matching client receive buffer, or use complete CLI JSON output to consume the analysis.";
+        const recoveryAdvice = recovery.continuation !== undefined
+            ? "Call inspect_analysis_view with the supplied continuation arguments to read retained pseudocode. Follow coverage.next_offset for subsequent pages; reduce the page limit if needed, or export the complete retained Evidence."
+            : retainedEvidence
+                ? "Export retained evidence to consume the complete analysis, or use complete CLI JSON output."
+                : encoded.constraint === "string-length"
+                    ? "Use complete CLI JSON output to consume the analysis."
+                    : "Use a larger MCP response budget with a matching client receive buffer, or use complete CLI JSON output to consume the analysis.";
         return this.toErrorToolResult(new AnalysisResourceConstraintError(contract.name, "transport", encoded.constraint === "string-length"
             ? `The operation completed, but its complete MCP response exceeds Node's single-string representation limit. ${recoveryAdvice}`
             : `The operation completed, but its complete MCP response exceeds the stdio response budget. The analysis result was not truncated. ${recoveryAdvice}`, {
@@ -72,6 +122,8 @@ export class ToolResultDelivery {
             response_code_units_at_least: encoded.codeUnitsAtLeast,
             constraint: encoded.constraint,
             ...recovery,
-        }));
+        }, recovery.continuation === undefined
+            ? undefined
+            : { remediationAction: recoveryAdvice }), contract.returnsTargetContent);
     }
 }

package/dist/server/toolResultEncoding.js

@@ -5,12 +5,45 @@ const RESULT_ENVELOPE_BYTES = Buffer.byteLength(JSON.stringify({
     content: [{ type: "text", text: "" }],
     structuredContent: null,
 })) - 4;
-const TEXT_RESULT_ENVELOPE_BYTES = Buffer.byteLength(JSON.stringify({ content: [{ type: "text", text: "" }] }));
+const ERROR_RESULT_ENVELOPE_BYTES = Buffer.byteLength(JSON.stringify({ content: [{ type: "text", text: "" }], isError: true }));
+/**
+ * Result metadata marking content that originates from the analysis target.
+ * Hosts and hooks can read it to treat the result as untrusted data.
+ */
+export const TARGET_CONTENT_RESULT_META = Object.freeze({
+    provenance: Object.freeze({
+        untrusted_content: true,
+        source: "analysis_target",
+    }),
+});
+/** Whether a delivered tool result already carries the untrusted target-content marker. */
+export const carriesTargetContentMarker = (result) => {
+    const meta = result._meta;
+    if (typeof meta !== "object" || meta === null)
+        return false;
+    const provenance = Reflect.get(meta, "provenance");
+    return (typeof provenance === "object" &&
+        provenance !== null &&
+        Reflect.get(provenance, "untrusted_content") === true);
+};
+// `,"_meta":{...}` added to the delivered result object.
+const TARGET_CONTENT_META_BYTES = Buffer.byteLength(JSON.stringify({ _meta: TARGET_CONTENT_RESULT_META })) - 1;
+/** Measure an already-formed MCP result object without allocating its JSON text. */
+export const measureMcpResultWithinBudget = (value, budgetBytes) => {
+    let bytes = 0;
+    for (const part of bufferedJsonParts(jsonParts(value))) {
+        bytes += Buffer.byteLength(part);
+        if (bytes > budgetBytes)
+            return { ok: false, bytesAtLeast: bytes, constraint: "receive-buffer" };
+    }
+    return { ok: true, bytes };
+};
 /** Account for the delivered JSON representations before allocating the complete text. */
-export const encodeToolResult = (value, budgetBytes, representations = "structured-and-text") => {
+export const encodeToolResult = (value, budgetBytes, representations = "structured-and-text", targetContent = false) => {
     const structured = representations === "structured-and-text";
     const parts = [];
-    let bytes = structured ? RESULT_ENVELOPE_BYTES : TEXT_RESULT_ENVELOPE_BYTES;
+    let bytes = (structured ? RESULT_ENVELOPE_BYTES : ERROR_RESULT_ENVELOPE_BYTES) +
+        (targetContent ? TARGET_CONTENT_META_BYTES : 0);
     let codeUnits = bytes;
     for (const part of bufferedJsonParts(jsonParts(value))) {
         const escapedPart = JSON.stringify(part);

package/dist/serverIdentity.js

@@ -1,6 +1,6 @@
 import { dirname, basename, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { CATALOG_IDENTITY } from "./catalogIdentity.js";
+import { CATALOG_IDENTITY, } from "./catalogIdentity.js";
 import { PRODUCT_IDENTITY, SDK_IDENTITY } from "./identity.js";
 const packageRoot = () => {
     const moduleDirectory = dirname(fileURLToPath(import.meta.url));
@@ -11,19 +11,22 @@ const packageRoot = () => {
 };
 /** Build one runtime identity without claiming alignment from absent observations. */
 export const createServerIdentity = (input) => {
-    const serverPath = resolve(process.argv[1] ?? "unknown");
+    const catalog = input.catalog ?? CATALOG_IDENTITY;
+    const serverPath = input.commandPath || undefined;
     const reasons = [];
     if (input.expected?.package_version !== undefined &&
         input.expected.package_version !== PRODUCT_IDENTITY.packageVersion)
         reasons.push("package_version_mismatch");
     if (input.expected?.catalog_digest !== undefined &&
-        input.expected.catalog_digest !== CATALOG_IDENTITY.digests.combined_sha256)
+        input.expected.catalog_digest !== catalog.digests.combined_sha256)
         reasons.push("catalog_digest_mismatch");
     if (input.expected?.server_path !== undefined &&
+        serverPath !== undefined &&
         resolve(input.expected.server_path) !== serverPath)
         reasons.push("registration_path_mismatch");
     const observedExpectation = input.expected !== undefined &&
         Object.values(input.expected).some((value) => value !== undefined);
+    const pathComparable = input.expected?.server_path === undefined || serverPath !== undefined;
     return {
         package: {
             name: PRODUCT_IDENTITY.packageName,
@@ -35,7 +38,7 @@ export const createServerIdentity = (input) => {
             name: PRODUCT_IDENTITY.mcpServerKey,
             version: PRODUCT_IDENTITY.packageVersion,
             started_at: input.startedAt,
-            command_path: serverPath,
+            command_path: serverPath ?? null,
         },
         sdk: SDK_IDENTITY,
         negotiated_protocol_version: input.protocolVersion ?? null,
@@ -46,7 +49,10 @@ export const createServerIdentity = (input) => {
             name: PRODUCT_IDENTITY.skillName,
             expected_version: PRODUCT_IDENTITY.skillVersion,
         },
-        catalog: CATALOG_IDENTITY,
+        catalog: {
+            counts: catalog.counts,
+            digests: catalog.digests,
+        },
         protocol_features: {
             progress: true,
             cancellation: true,
@@ -55,15 +61,18 @@ export const createServerIdentity = (input) => {
         alignment: {
             state: reasons.length > 0
                 ? "mcp_server_restart_required"
-                : observedExpectation
+                : observedExpectation && pathComparable
                     ? "aligned"
                     : "unknown",
             reasons,
             remediation: reasons.length > 0
                 ? "Restart the registered MCP server/client, then compare identity again."
-                : observedExpectation
+                : observedExpectation && pathComparable
                     ? null
-                    : "Supply expected package, catalog, or registration identity to compare the live server.",
+                    : input.expected?.server_path !== undefined &&
+                        serverPath === undefined
+                        ? "The server entrypoint path is unavailable, so registration identity cannot be compared."
+                        : "Supply expected package, catalog, or registration identity to compare the live server.",
         },
     };
 };

package/dist/signals/SigrokRecordingProvider.js

@@ -0,0 +1,339 @@
+import { signalDecodersSchema, } from "../domain/signals/signalDecoders.js";
+import { DecoderDiscoveryBudgetError, parseDecoderDiscovery, } from "./parseDecoderDiscovery.js";
+import { BOUNDED_PRODUCER_LIMITS as LIMITS, prlimitArgumentVector, readLinuxResourceLimits, } from "../process/LinuxResourceLimits.js";
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { access, realpath, writeFile } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { ArtifactAnalysisResources, } from "../process/ArtifactAnalysisResources.js";
+import { readStableArtifact } from "../artifacts/readStableArtifact.js";
+import { AnalysisError, } from "../domain/analysisErrorBase.js";
+import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, AnalysisResourceConstraintError, } from "../domain/analysisErrorCore.js";
+import { createEvidence } from "../domain/evidence.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { windowAnnotationText } from "../domain/signals/annotationTextWindow.js";
+import { signalRecordingSchema, } from "../domain/signals/signalRecording.js";
+import { err, ok } from "../domain/result.js";
+import { runOwnedCommand, OwnedCommandFailure, } from "../process/OwnedCommand.js";
+import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
+const OPERATION = "decode_signal_recording";
+export const SIGROK_PROVIDER_IDENTITY = {
+    id: "sigrok-recording",
+    name: "REA sigrok recording adapter",
+    version: "sigrok-cli@0.7.2",
+};
+/** Decode selected recordings only, retaining cleanup ownership across failures. */
+export class SigrokRecordingProvider {
+    environment;
+    launcher;
+    createRuntime;
+    platform;
+    readArtifact;
+    readLimits;
+    #resources;
+    constructor(environment = process.env, launcher, createRuntime = () => PrivateRuntimeRoot.create({ prefix: "rea-sigrok-" }), platform = process.platform, readArtifact = readStableArtifact, readLimits = readLinuxResourceLimits) {
+        this.environment = environment;
+        this.launcher = launcher;
+        this.createRuntime = createRuntime;
+        this.platform = platform;
+        this.readArtifact = readArtifact;
+        this.readLimits = readLimits;
+        this.#resources = new ArtifactAnalysisResources(SIGROK_PROVIDER_IDENTITY.id, OPERATION, readArtifact, readLimits, {
+            message: "A sigrok operation is already active; retry after it completes.",
+            details: { max_concurrent_decodes: 1 },
+        });
+    }
+    decode(input, options) {
+        return this.#resources.run(() => this.#executeRequest(input, options), options?.signal);
+    }
+    inspectDecoders(input, options) {
+        return this.#resources.run(() => this.#executeRequest(input, options), options?.signal, "inspect_signal_decoders");
+    }
+    close() {
+        return this.#resources.close();
+    }
+    async #executeRequest(input, options) {
+        const operation = "path" in input ? OPERATION : "inspect_signal_decoders";
+        let phase = "configuration";
+        let capturedOutput;
+        let resourcePath = "path" in input ? input.path : "sigrok decoder catalog";
+        let effectiveLimits;
+        let root;
+        let result;
+        try {
+            if (options?.signal?.aborted)
+                throw new AnalysisCancelledError(operation);
+            await this.#resources.release();
+            if (this.platform !== "linux")
+                throw new Error("Signal decoding requires Linux with util-linux prlimit and REA_SIGROK_COMMAND so expanded recordings are processed under an enforced address-space limit.");
+            const configured = this.environment.REA_SIGROK_COMMAND ?? "";
+            if (!isAbsolute(configured))
+                throw new Error("Supply absolute REA_SIGROK_COMMAND for sigrok-cli 0.7.2 with libsigrokdecode.");
+            const command = await realpath(configured);
+            await access(command, constants.X_OK);
+            const tool = await this.#resources.read(command, 64 * 1024 * 1024, options?.signal);
+            const configuredLimiter = this.environment.REA_SIGROK_PRLIMIT_COMMAND ?? "/usr/bin/prlimit";
+            if (!isAbsolute(configuredLimiter))
+                throw new Error("REA_SIGROK_PRLIMIT_COMMAND must be absolute.");
+            const limiter = await realpath(configuredLimiter);
+            await access(limiter, constants.X_OK);
+            const limiterIdentity = await this.#resources.read(limiter, 64 * 1024 * 1024, options?.signal);
+            effectiveLimits = await this.#resources.readLimits(LIMITS);
+            const limitArguments = prlimitArgumentVector(effectiveLimits, command);
+            phase = "workspace";
+            root = await this.createRuntime();
+            this.#resources.retain(root, undefined);
+            const snapshotPath = join(root.path, "recording");
+            const execute = async (args) => {
+                capturedOutput = undefined;
+                const output = await runOwnedCommand({
+                    command: limiter,
+                    arguments: [...limitArguments, ...args],
+                    ...(root === undefined ? {} : { cwd: root.path }),
+                    expectedCommand: null,
+                    runId: `rea-sigrok-${randomUUID()}`,
+                    hostEnvironment: this.environment,
+                }, {
+                    timeoutMs: LIMITS.command_timeout_ms,
+                    diagnosticBytes: LIMITS.output_bytes,
+                    acceptNonZeroExit: true,
+                }, {
+                    ...(options?.signal === undefined
+                        ? {}
+                        : { signal: options.signal }),
+                    ...(this.launcher === undefined ? {} : { launcher: this.launcher }),
+                });
+                capturedOutput = {
+                    stdout: output.stdout.text,
+                    stderr: output.stderr.text,
+                    truncated: output.diagnosticTruncated ?? false,
+                    exit_code: output.exitCode ?? null,
+                    signal: output.signal ?? null,
+                };
+                // Finish bounded integrity checks after output; service handles late cancellation with Evidence.
+                const previousPhase = phase;
+                phase = "integrity";
+                resourcePath = command;
+                const current = await this.#resources.read(command, 64 * 1024 * 1024);
+                resourcePath = limiter;
+                const currentLimiter = await this.#resources.read(limiter, 64 * 1024 * 1024);
+                if (currentLimiter.sha256 !== limiterIdentity.sha256)
+                    throw new AnalysisArtifactChangedError(operation, limiter, "Configured resource limiter changed during analysis.", { capturedOutput });
+                if (current.sha256 !== tool.sha256)
+                    throw new AnalysisArtifactChangedError(operation, command, "Configured decoder executable changed during analysis.", { capturedOutput });
+                phase = previousPhase;
+                resourcePath = "path" in input ? input.path : command;
+                if (output.exitCode !== 0)
+                    throw new ProviderAdapterError(SIGROK_PROVIDER_IDENTITY.id, operation, {
+                        diagnostics: {
+                            exit_code: output.exitCode ?? null,
+                            stdout: output.stdout.text,
+                            stderr: output.stderr.text,
+                        },
+                    });
+                return output;
+            };
+            phase = "configuration";
+            const version = await execute(["--version"]);
+            if (!/^sigrok-cli 0\.7\.2(?:\r?\n|$)/u.test(version.stdout.text) ||
+                !version.stdout.text.includes("libsigrokdecode"))
+                throw new Error("Expected sigrok-cli 0.7.2 with libsigrokdecode; inspect the selected installation.");
+            const metadata = (args, diagnostics) => ({
+                diagnostics,
+                tool: {
+                    configured_path: configured,
+                    path: command,
+                    sha256: tool.sha256,
+                    version_banner: version.stdout.text,
+                    version_diagnostics: version.stderr.text,
+                    arguments: [...args],
+                },
+                resource_limiter: {
+                    configured_path: configuredLimiter,
+                    path: limiter,
+                    sha256: limiterIdentity.sha256,
+                    arguments: limitArguments,
+                },
+                limits: { ...LIMITS, ...effectiveLimits },
+                hardware_acquisition: "not-performed",
+            });
+            if (!("path" in input)) {
+                phase = "producer";
+                const args = input.decoder === null
+                    ? ["--dont-scan", "--list-supported"]
+                    : ["--dont-scan", `--protocol-decoders=${input.decoder}`, "--show"];
+                const output = await execute(args);
+                const report = signalDecodersSchema.parse({
+                    selection: input,
+                    ...parseDecoderDiscovery(output.stdout.text, input),
+                    ...metadata(args, output.stderr.text),
+                });
+                result = ok(createAnalysisExecution(report, SIGROK_PROVIDER_IDENTITY, {
+                    subject: { path: command, sha256: tool.sha256, format: "file" },
+                    limitations: [
+                        "Catalog and help are observed from the selected sigrok installation. Help lines preserve producer descriptions, not a separately validated parameter schema.",
+                        "Each request probes the installation again; pages do not share a frozen catalog. Decoder modules and libraries are trusted and not fully fingerprinted.",
+                        "Hardware discovery, recording reads and acquisition are not requested. Linux per-process limits and bounded output apply; this is not an OS sandbox.",
+                    ],
+                }));
+            }
+            else {
+                phase = "artifact";
+                const selected = await this.#resources.read(input.path, LIMITS.input_bytes, options?.signal);
+                phase = "workspace";
+                await writeFile(snapshotPath, selected.bytes, {
+                    flag: "wx",
+                    mode: 0o400,
+                });
+                phase = "producer";
+                const args = [
+                    "--dont-scan",
+                    "--input-file=recording",
+                    `--protocol-decoders=${input.decoders}`,
+                    "--protocol-decoder-samplenum",
+                    ...(input.input_format === null
+                        ? []
+                        : [`--input-format=${input.input_format}`]),
+                    ...(input.annotations === null
+                        ? []
+                        : [`--protocol-decoder-annotations=${input.annotations}`]),
+                ];
+                const output = await execute(args);
+                phase = "integrity";
+                resourcePath = snapshotPath;
+                if ((await this.#resources.read(snapshotPath, LIMITS.input_bytes))
+                    .sha256 !== selected.sha256)
+                    throw new AnalysisArtifactChangedError(operation, snapshotPath, "Decoder changed the private recording copy.", capturedOutput === undefined ? {} : { capturedOutput });
+                phase = "producer";
+                resourcePath = "path" in input ? input.path : command;
+                const report = signalRecordingSchema.parse({
+                    artifact: {
+                        path: input.path,
+                        sha256: selected.sha256,
+                        bytes: selected.bytes.length,
+                    },
+                    selection: input,
+                    ...windowAnnotationText(output.stdout.text, input.line_offset, input.line_limit),
+                    ...metadata(args, output.stderr.text),
+                });
+                result = ok(createAnalysisExecution(report, SIGROK_PROVIDER_IDENTITY, {
+                    subject: {
+                        path: input.path,
+                        sha256: selected.sha256,
+                        format: "file",
+                    },
+                    locations: [{ kind: "artifact-path", path: input.path }],
+                    limitations: [
+                        "Annotations are the selected decoder's interpretation of the recorded samples and caller-selected settings, not independently verified protocol semantics. Empty output does not establish absence of traffic.",
+                        "Sample-number ranges and display text are preserved verbatim, not converted to timestamps or parsed as a lossless byte stream. All producer stderr is retained, including warnings on exit zero.",
+                        "Only a private copy of the selected file is decoded. Hardware discovery/acquisition and target execution are not requested. Caller-supplied tools, plugins and decoder modules are trusted; this is not an OS sandbox.",
+                        "Linux prlimit enforces soft and hard ceilings before execution, preserving stricter inherited limits: at most 1 GiB address space per process, 64 MiB per file, 30 CPU seconds and no core dumps. Effective limits are reported. Resident input is capped at 32 MiB, each command at 30 wall-clock seconds and combined output at 4 MiB. Output overflow fails. These are per-process/per-file limits, not aggregate memory or filesystem quotas; caller-supplied tools and the limiter are trusted.",
+                    ],
+                }));
+            }
+        }
+        catch (cause) {
+            if (root !== undefined &&
+                cause instanceof OwnedCommandFailure &&
+                cause.cleanupOwner !== undefined)
+                this.#resources.retain(root, cause.cleanupOwner);
+            result = err(this.#failure(cause, phase, resourcePath, root?.path ?? null, effectiveLimits, capturedOutput, operation));
+        }
+        return this.#resources.finish(result, (execution) => createEvidence(execution.subject ?? undefined, execution.provider, {
+            operation,
+            parameters: input,
+            result: execution.result,
+            confidence: "observed",
+            locations: execution.locations,
+            limitations: execution.limitations,
+        }), operation);
+    }
+    #failure(cause, phase, path, workspacePath, effectiveLimits, observedOutput, operation = OPERATION) {
+        if (cause instanceof AnalysisError)
+            return cause;
+        if (cause instanceof ArtifactReaderFailure && cause.cleanup !== undefined)
+            return this.#resources.cleanupFailure(cause.cleanup, cause, observedOutput, operation);
+        if ((cause instanceof Error && cause.name === "AbortError") ||
+            (cause instanceof ArtifactReaderFailure && cause.reason === "cancelled"))
+            return new AnalysisCancelledError(operation, { cause });
+        if (cause instanceof DecoderDiscoveryBudgetError)
+            return new AnalysisResourceConstraintError(operation, "memory", cause.message, { line_budget: 65536 }, {
+                cause,
+                ...(observedOutput === undefined
+                    ? {}
+                    : { capturedOutput: observedOutput }),
+            });
+        const reason = cause instanceof Error ? cause.message : String(cause);
+        if (cause instanceof OwnedCommandFailure)
+            return this.#resources.commandFailure(cause, LIMITS, effectiveLimits, operation);
+        if (phase === "workspace") {
+            const code = cause instanceof Error &&
+                "code" in cause &&
+                typeof cause.code === "string"
+                ? cause.code
+                : null;
+            if (code === "ENOSPC" || code === "EDQUOT" || code === "EFBIG")
+                return new AnalysisResourceConstraintError(operation, "file-size", `Private analysis workspace failed (${code}): ${reason}`, { workspace_path: workspacePath, system_code: code }, { cause });
+            return new ProviderAdapterError(SIGROK_PROVIDER_IDENTITY.id, operation, {
+                cause,
+                userMessage: `Cannot prepare the private analysis workspace: ${reason}`,
+                diagnostics: {
+                    stage: "workspace",
+                    workspace_path: workspacePath,
+                    system_code: code,
+                    reason,
+                },
+            });
+        }
+        if (phase === "integrity") {
+            const detail = {
+                cause,
+                ...(observedOutput === undefined
+                    ? {}
+                    : { capturedOutput: observedOutput }),
+            };
+            if (cause instanceof ArtifactReaderFailure &&
+                ["limit", "integrity", "path"].includes(cause.reason))
+                return new AnalysisArtifactChangedError(operation, path, `Post-run identity verification failed for ${path}: ${reason}`, detail);
+            return new ProviderAdapterError(SIGROK_PROVIDER_IDENTITY.id, operation, {
+                ...detail,
+                diagnostics: { stage: "integrity", resource_path: path, reason },
+            });
+        }
+        if (phase === "configuration")
+            return new AnalysisCapabilityUnavailableError(SIGROK_PROVIDER_IDENTITY.id, operation, reason, {
+                cause,
+                ...(observedOutput === undefined
+                    ? {}
+                    : { capturedOutput: observedOutput }),
+                userMessage: `${reason} On Linux, configure sigrok-cli 0.7.2 through REA_SIGROK_COMMAND and util-linux prlimit through REA_SIGROK_PRLIMIT_COMMAND (default /usr/bin/prlimit).`,
+            });
+        if (phase === "artifact" &&
+            cause instanceof ArtifactReaderFailure &&
+            cause.reason === "limit")
+            return new AnalysisResourceConstraintError(operation, "file-size", reason, { input_bytes: LIMITS.input_bytes }, { cause });
+        if (cause instanceof ArtifactReaderFailure && cause.reason === "integrity")
+            return new AnalysisArtifactChangedError(operation, path, reason, {
+                cause,
+            });
+        if (phase === "artifact" &&
+            cause instanceof Error &&
+            "code" in cause &&
+            (cause.code === "EACCES" || cause.code === "EPERM"))
+            return new AnalysisAccessDeniedError(operation, path, cause.code, {
+                cause,
+            });
+        if (phase === "artifact")
+            return new AnalysisInputError(operation, { cause }, [
+                { path: ["path"], reason: "invalid_value", message: reason },
+            ]);
+        return new AnalysisOutputError(operation, reason, {
+            cause,
+            ...(observedOutput === undefined
+                ? {}
+                : { capturedOutput: observedOutput }),
+        });
+    }
+}