diff --git a/scripts/verify/architecture-guards.mjs b/scripts/verify/architecture-guards.mjs index 381e86374b..37b1fcab7c 100644 --- a/scripts/verify/architecture-guards.mjs +++ b/scripts/verify/architecture-guards.mjs @@ -347,6 +347,17 @@ const checkCounted = (label, key, selected, pattern, owners) => { ); }; +// A provider failure's captured output comes from one owner, +// capturedProviderOutput in src/process; local copies drift on byte counts +// (retained or written) and on how output loss marks truncation. +checkCounted( + "captured output copied from a process snapshot (use capturedProviderOutput from src/process/capturedProviderOutput)", + "captured-output-copy", + files, + /\bstdout: [\w.]+\.stdout\.text\b/gu, + ["src/process/capturedProviderOutput.ts"], +); + // Pushed effect invalidation (docs/adr/javascript/pushed-effect-invalidation.md). // Recorded effects belong to the effect log. A reader that reads an effect // index itself decides on its own which effect kinds and proofs apply; new diff --git a/scripts/verify/baselines/captured-output-copy.json b/scripts/verify/baselines/captured-output-copy.json new file mode 100644 index 0000000000..cb5a38b35b --- /dev/null +++ b/scripts/verify/baselines/captured-output-copy.json @@ -0,0 +1,19 @@ +{ + "src/apktool/ApktoolProvider.ts": 1, + "src/application/reverse/ReverseEngineeringService.ts": 3, + "src/browser/history/CaptureFailures.ts": 2, + "src/captures/TsharkCaptureProvider.ts": 1, + "src/desktop/TaskReaderProcess.ts": 1, + "src/evm/EvmoleInterfaceProvider.ts": 1, + "src/firmware/FirmwareCommand.ts": 4, + "src/firmware/FirmwareProvider.ts": 1, + "src/gdb/GdbSessionManager.ts": 1, + "src/javascript/recovery/WakaruCommand.ts": 1, + "src/javascript/sourceMaps/SourceMapCommand.ts": 1, + "src/native/CommandRunner.ts": 1, + "src/native/pwntools/PwntoolsDecoder.ts": 1, + "src/pcap/PcapCommand.ts": 1, + "src/signals/SigrokRecordingProvider.ts": 1, + "src/wasm/WabtArtifactProvider.ts": 2, + "src/wasm/WabtFailures.ts": 1 +} diff --git a/src/android/JadxJavaProbe.ts b/src/android/JadxJavaProbe.ts index 3926baa9a6..fdba5cb896 100644 --- a/src/android/JadxJavaProbe.ts +++ b/src/android/JadxJavaProbe.ts @@ -1,3 +1,4 @@ +import { capturedProviderOutput } from "../process/capturedProviderOutput.js"; import type { ProcessInspectionFailure } from "../process/ProcessInspectionCleanup.js"; import { classifyLaunchFailureCode } from "../process/launchFailure.js"; import { randomUUID } from "node:crypto"; @@ -78,18 +79,6 @@ const refusal = ( ): Result => err({ code, message, diagnostics, kind }); -const capturedOutput = ( - snapshot: ProviderProcessSnapshot, -): AnalysisCapturedOutput => ({ - stdout: snapshot.stdout.text, - stderr: snapshot.stderr.text, - stdout_bytes: snapshot.stdout.observedBytes, - stderr_bytes: snapshot.stderr.observedBytes, - truncated: - snapshot.diagnosticTruncated === true || snapshot.outputIncomplete === true, - exit_code: snapshot.exitCode ?? null, - signal: snapshot.signal ?? null, -}); const projectRefusal = ( failure: JadxJavaProbeRefusal, operation: string, @@ -164,7 +153,7 @@ export const inspectJadxJava = async ( ? preparation instanceof DarwinProcessOwnershipInspectionError ? preparation.capturedOutput : undefined - : capturedOutput(command.snapshot); + : capturedProviderOutput(command.snapshot); const inspectionCancellation = command === undefined || command.preparationFailure !== undefined ? processInspectionCancellationError(cause, operation) @@ -293,7 +282,9 @@ const commandProbeRefusal = ( timeoutMs: number, ): JadxJavaProbeRefusal => { const output = - command?.snapshot == null ? undefined : capturedOutput(command.snapshot); + command?.snapshot == null + ? undefined + : capturedProviderOutput(command.snapshot); const processError = command?.processError ?? (cause instanceof Error ? cause : undefined); const systemCode = diff --git a/src/apktool/ApktoolCommandOutput.ts b/src/apktool/ApktoolCommandOutput.ts index 188e597d1c..ef0848eaa2 100644 --- a/src/apktool/ApktoolCommandOutput.ts +++ b/src/apktool/ApktoolCommandOutput.ts @@ -1,22 +1,9 @@ +import { capturedProviderOutput } from "../process/capturedProviderOutput.js"; import { OwnedCommandFailure } from "../process/OwnedCommand.js"; import { DarwinProcessOwnershipInspectionError } from "../process/DarwinProcessRunTokenReader.js"; import type { AnalysisCapturedOutput } from "../domain/analysisErrorBase.js"; import type { ProviderProcessSnapshot } from "../process/ProviderProcess.js"; -/** Project the command owner's bounded output without losing examined byte counts. */ -export const capturedApktoolCommandOutput = ( - output: ProviderProcessSnapshot, -): AnalysisCapturedOutput => ({ - stdout: output.stdout.text, - stderr: output.stderr.text, - truncated: - output.diagnosticTruncated === true || output.outputIncomplete === true, - stdout_bytes: output.stdout.observedBytes, - stderr_bytes: output.stderr.observedBytes, - exit_code: output.exitCode ?? null, - signal: output.signal ?? null, -}); - /** The command owner selects command output or preparation output, once. */ export const capturedApktoolFailureOutput = ( cause: unknown, @@ -27,7 +14,7 @@ export const capturedApktoolFailureOutput = ( DarwinProcessOwnershipInspectionError ? cause.preparationFailure.capturedOutput : undefined - : capturedApktoolCommandOutput(cause.snapshot); + : capturedProviderOutput(cause.snapshot); return cause instanceof DarwinProcessOwnershipInspectionError ? cause.capturedOutput : undefined; diff --git a/src/apktool/ApktoolProvider.ts b/src/apktool/ApktoolProvider.ts index d95705407e..2e22d19e54 100644 --- a/src/apktool/ApktoolProvider.ts +++ b/src/apktool/ApktoolProvider.ts @@ -1,3 +1,4 @@ +import { capturedProviderOutput } from "../process/capturedProviderOutput.js"; import { MAX_NODE_TIMER_DELAY_MS } from "../domain/analysisResourceLimits.js"; import { HOST_PLATFORM } from "../platform/HostPlatform.js"; import { processInspectionCancellationError } from "../providers/OwnedCommandCleanup.js"; @@ -16,10 +17,7 @@ import { artifactFileCancellationCause, } from "../artifacts/ArtifactFileOperation.js"; import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js"; -import { - capturedApktoolCommandOutput, - capturedApktoolFailureOutput, -} from "./ApktoolCommandOutput.js"; +import { capturedApktoolFailureOutput } from "./ApktoolCommandOutput.js"; import { providerOutcomeOf } from "../process/ProviderOutcome.js"; import { classifyProviderOutcome } from "../process/classifyProviderOutcome.js"; import { ApktoolCommandCleanup } from "./ApktoolCommandCleanup.js"; @@ -227,7 +225,7 @@ const apktoolCommandFailure = ( }); return classifyProviderOutcome(providerOutcomeOf(failure), { operation, - capturedOutput: capturedApktoolCommandOutput, + capturedOutput: capturedProviderOutput, // Ownership preparation can retain output before any process exists. details: capturedOutput === undefined ? {} : { capturedOutput }, timeout: { diff --git a/src/captures/TsharkCaptureProvider.ts b/src/captures/TsharkCaptureProvider.ts index 088c24ca3d..fcb6ad2738 100644 --- a/src/captures/TsharkCaptureProvider.ts +++ b/src/captures/TsharkCaptureProvider.ts @@ -1,3 +1,4 @@ +import { capturedProviderOutput } from "../process/capturedProviderOutput.js"; import { readerIntegrityFailure } from "../artifacts/StableArtifactFailure.js"; import { classifyProviderFailure, @@ -42,7 +43,6 @@ import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js"; import { ARTIFACT_PRODUCER_LIMITATION, ArtifactAnalysisResources, - artifactCommandOutput, type ArtifactAnalysisRuntime, } from "../process/ArtifactAnalysisResources.js"; import { @@ -245,7 +245,7 @@ export class TsharkCaptureProvider implements PacketCapturePort { ...(this.launcher === undefined ? {} : { launcher: this.launcher }), }, ); - capturedOutput = artifactCommandOutput(output); + capturedOutput = capturedProviderOutput(output); await assertArtifactCommandPath(selectedCommand, operation, { capturedOutput, }); diff --git a/src/desktop/DesktopBuildOwnedCommand.ts b/src/desktop/DesktopBuildOwnedCommand.ts index cf743371bd..aa6a3d1b39 100644 --- a/src/desktop/DesktopBuildOwnedCommand.ts +++ b/src/desktop/DesktopBuildOwnedCommand.ts @@ -1,3 +1,4 @@ +import { capturedProviderOutput } from "../process/capturedProviderOutput.js"; import { randomUUID } from "node:crypto"; import { rm } from "node:fs/promises"; @@ -14,7 +15,6 @@ import { runOwnedCommand, } from "../process/OwnedCommand.js"; import { DarwinProcessOwnershipInspectionError } from "../process/DarwinProcessRunTokenReader.js"; -import { artifactCommandOutput } from "../process/ArtifactAnalysisResources.js"; import { AnalysisOutputError, cancelledBy, @@ -142,7 +142,7 @@ export const runDesktopBuildOwnedCommand = async (input: { ? preparation instanceof DarwinProcessOwnershipInspectionError ? preparation.capturedOutput : undefined - : artifactCommandOutput(command.snapshot); + : capturedProviderOutput(command.snapshot); const reason = desktopBuildOwnedCommandReason(failure); const physical = failure instanceof AnalysisError diff --git a/src/domain/javascript/javascriptSemanticExpressionShapes.ts b/src/domain/javascript/javascriptSemanticExpressionShapes.ts index 2e80608d12..305bb48621 100644 --- a/src/domain/javascript/javascriptSemanticExpressionShapes.ts +++ b/src/domain/javascript/javascriptSemanticExpressionShapes.ts @@ -1,5 +1,7 @@ -import { opaqueCodeMayRebindBinding } from "./javascriptSemanticEffectLog.js"; -import { opaqueCodeMayChangeGlobalRead } from "./javascriptSemanticEffectLog.js"; +import { + opaqueCodeMayRebindBinding, + opaqueCodeMayChangeGlobalRead, +} from "./javascriptSemanticEffectLog.js"; import * as t from "@babel/types"; import { diff --git a/src/evm/EvmoleFailures.test.ts b/src/evm/EvmoleFailures.test.ts index ecd4c3ce53..fc484f61c8 100644 --- a/src/evm/EvmoleFailures.test.ts +++ b/src/evm/EvmoleFailures.test.ts @@ -84,6 +84,10 @@ it.each([ expect(result.capturedOutput).toEqual({ stdout: "selected output", stderr: "warning", + stdout_bytes: 15, + stderr_bytes: 7, + exit_code: 0, + signal: null, truncated: false, }); expect(result.cleanupIncomplete).toBe(false); diff --git a/src/evm/EvmoleFailures.ts b/src/evm/EvmoleFailures.ts index 08309ff835..bec0733371 100644 --- a/src/evm/EvmoleFailures.ts +++ b/src/evm/EvmoleFailures.ts @@ -1,3 +1,4 @@ +import { capturedProviderOutput } from "../process/capturedProviderOutput.js"; import { MAX_NODE_TIMER_DELAY_MS } from "../domain/analysisResourceLimits.js"; import type { EvmWorkerLimits } from "./EvmWorkerLimits.js"; import type { @@ -105,7 +106,11 @@ export const evmFailureDialect = ( reason: failure.cleanupFailure, ...(failure.snapshot === null ? {} - : { captured_output: { ...capturedEvmOutput(failure.snapshot) } }), + : { + captured_output: { + ...capturedProviderOutput(failure.snapshot), + }, + }), previous_error: { failure_kind: failure.reason, message: failure.message, @@ -165,7 +170,7 @@ const evmCommandContext = ( context; return { operation: OPERATION, - capturedOutput: capturedEvmOutput, + capturedOutput: capturedProviderOutput, timeout: { ms: timeoutMs, userMessage: `The EVMole worker reached its ${String(timeoutMs)} ms server/provider deadline (timeout_ms). This is not a carrier-read or MCP client deadline. Omitted timeout_ms uses ${String(DEFAULT_EVM_TIMEOUT_MS)} ms.`, @@ -280,12 +285,3 @@ const configuredWorkerLimits = (workerLimits: EvmWorkerLimits | undefined) => }, effective_soft_limits: null, }; - -/** Preserve retained worker diagnostics with their observed truncation status. */ -export const capturedEvmOutput = ( - snapshot: ProviderProcessSnapshot, -): AnalysisCapturedOutput => ({ - stdout: snapshot.stdout.text, - stderr: snapshot.stderr.text, - truncated: snapshot.diagnosticTruncated === true, -}); diff --git a/src/evm/EvmoleInterfaceProvider.ts b/src/evm/EvmoleInterfaceProvider.ts index 2b7953da53..5829603ec3 100644 --- a/src/evm/EvmoleInterfaceProvider.ts +++ b/src/evm/EvmoleInterfaceProvider.ts @@ -1,3 +1,7 @@ +import { + capturedProviderOutput, + providerResultDiagnostics, +} from "../process/capturedProviderOutput.js"; import { EvmAdmissionError } from "./EvmAdmissionError.js"; import { HOST_PLATFORM } from "../platform/HostPlatform.js"; import type { ProviderRejectionCode } from "../domain/providerSelection.js"; @@ -72,7 +76,6 @@ import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js"; import type { ProviderProcessSupervisor } from "../process/ProviderProcess.js"; import { evmFailureDialect, - capturedEvmOutput, evmReplyBudgetFailure, type EvmFileSizeFailureEvidence, } from "./EvmoleFailures.js"; @@ -675,7 +678,7 @@ export class EvmoleInterfaceProvider implements EvmInterfacePort { }, }, ); - const capturedOutput = capturedEvmOutput(execution); + const capturedOutput = capturedProviderOutput(execution); retainedOutput = capturedOutput; let reply: z.output; try { @@ -823,11 +826,7 @@ export class EvmoleInterfaceProvider implements EvmInterfacePort { functions: projectEvmoleFunctions(reply.raw), discovery_completeness: "unknown", runtime_execution: "not-performed", - diagnostics: { - stdout: execution.stdout.text, - stderr: execution.stderr.text, - truncated: capturedOutput.truncated, - }, + diagnostics: providerResultDiagnostics(capturedOutput), limitations, }); if (!validated.success) diff --git a/src/firmware/FirmwareCommand.ts b/src/firmware/FirmwareCommand.ts index 67ac8f8b38..1787b5288e 100644 --- a/src/firmware/FirmwareCommand.ts +++ b/src/firmware/FirmwareCommand.ts @@ -1,3 +1,4 @@ +import { capturedProviderOutput } from "../process/capturedProviderOutput.js"; import { processInspectionCancellationError, retainProcessInspectionCleanup, @@ -57,19 +58,6 @@ export type FirmwareLauncher = ( options: OwnedProviderProcessSpawnOptions, ) => Promise; -/** Captured tool output for one finished firmware command, including byte coverage. */ -const capturedFirmwareOutput = ( - snapshot: ProviderProcessSnapshot, -): AnalysisCapturedOutput => ({ - stdout: snapshot.stdout.text, - stderr: snapshot.stderr.text, - stdout_bytes: snapshot.stdout.bytes, - stderr_bytes: snapshot.stderr.bytes, - exit_code: snapshot.exitCode ?? null, - signal: snapshot.signal ?? null, - truncated: snapshot.diagnosticTruncated === true, -}); - /** Refuse an unmet host or tool requirement, which another target cannot satisfy. */ export const firmwareToolUnavailable = ( engine: string, @@ -326,7 +314,7 @@ export const runFirmwareCommand = async (context: { snapshot.signal, fileSizeBytes, fileSizeAdjustable, - capturedFirmwareOutput(snapshot), + capturedProviderOutput(snapshot), ); if (signalLimit !== undefined) return signalLimit; return new ProviderAdapterError(engine, operation, { @@ -440,7 +428,7 @@ export const runFirmwareCommand = async (context: { { operation, cleanupPrimary: failure, - capturedOutput: capturedFirmwareOutput(snapshot), + capturedOutput: capturedProviderOutput(snapshot), }, ); } diff --git a/src/javascript/recovery/WakaruCommand.ts b/src/javascript/recovery/WakaruCommand.ts index 28a091af95..4ff72bb4fa 100644 --- a/src/javascript/recovery/WakaruCommand.ts +++ b/src/javascript/recovery/WakaruCommand.ts @@ -1,3 +1,4 @@ +import { capturedProviderOutput } from "../../process/capturedProviderOutput.js"; import { selectArtifactCommandPath } from "../../process/ArtifactCommandPath.js"; import { randomUUID } from "node:crypto"; import { constants } from "node:fs"; @@ -40,17 +41,6 @@ const OPERATION = "recover_javascript_sources"; const WAKARU_REQUIREMENT = "Provide an absolute REA_WAKARU_COMMAND pointing to a Wakaru ^1.13.0 Linux x64 binary (verified with 1.14.0); no tool is installed by REA. See docs/guides/javascript/javascript-recovery.md#install-wakaru."; -const commandCapturedOutput = ( - snapshot: ReturnType, -) => ({ - stdout: snapshot.stdout.text, - stderr: snapshot.stderr.text, - exit_code: snapshot.exitCode ?? null, - signal: snapshot.signal ?? null, - truncated: - snapshot.diagnosticTruncated === true || snapshot.outputIncomplete === true, -}); - /** Wakaru recovery runs only on Linux x64; discovery and execution share this check. */ export const wakaruHostSupported = ( platform: NodeJS.Platform, @@ -88,7 +78,7 @@ export class WakaruCleanupFailure extends ProviderCleanupError { ...(previousError instanceof AnalysisError ? { cleanupPrimary: previousError } : {}), - capturedOutput: commandCapturedOutput(snapshot), + capturedOutput: capturedProviderOutput(snapshot), }, ); } @@ -273,7 +263,7 @@ export const runWakaruCommand = async (context: WakaruCommandContext) => { failure = analysisErrorWithCancellation(failure, cancelled); } if (failure instanceof AnalysisError) - failure.retainCapturedOutput(commandCapturedOutput(snapshot)); + failure.retainCapturedOutput(capturedProviderOutput(snapshot)); if (stopped.status === "incomplete") throw new WakaruCleanupFailure( supervisor, diff --git a/src/native/pwndbg/PwndbgCoreContext.ts b/src/native/pwndbg/PwndbgCoreContext.ts index 0ce601d26f..70da35c0dc 100644 --- a/src/native/pwndbg/PwndbgCoreContext.ts +++ b/src/native/pwndbg/PwndbgCoreContext.ts @@ -1,3 +1,7 @@ +import { + capturedProviderOutput, + providerResultDiagnostics, +} from "../../process/capturedProviderOutput.js"; import { classifyProviderFailure } from "../../providers/classifyProviderFailure.js"; import { bindArtifactFileCleanup, @@ -34,7 +38,6 @@ import { AnalysisError } from "../../domain/analysisErrorBase.js"; import { analysisErrorWithCleanupFailure } from "../../domain/analysisErrorCleanup.js"; import { ProviderCleanupError } from "../../domain/providerCleanupError.js"; import { - capturedPwntoolsOutput, pwntoolsFailureDialect, pwntoolsBudgetRecovery, } from "../pwntools/PwntoolsFailures.js"; @@ -233,7 +236,7 @@ export const inspectPwndbgCore = async ({ }, failure, ); - output = capturedPwntoolsOutput(execution); + output = capturedProviderOutput(execution); let reply: z.output; let finalization: AnalysisError | undefined; try { @@ -344,7 +347,13 @@ export const inspectPwndbgCore = async ({ ), finalization, ); - return { context: { ...reply.value, diagnostics: output }, finalization }; + return { + context: { + ...reply.value, + diagnostics: providerResultDiagnostics(output), + }, + finalization, + }; } catch (cause: unknown) { if (cause instanceof AnalysisError && cause.cleanupIncomplete) throw cause; const primary = classifyProviderFailure( diff --git a/src/native/pwntools/PwntoolsDecoder.ts b/src/native/pwntools/PwntoolsDecoder.ts index b82966e91e..35d60235bd 100644 --- a/src/native/pwntools/PwntoolsDecoder.ts +++ b/src/native/pwntools/PwntoolsDecoder.ts @@ -1,3 +1,7 @@ +import { + capturedProviderOutput, + providerResultDiagnostics, +} from "../../process/capturedProviderOutput.js"; import { classifyProviderFailure } from "../../providers/classifyProviderFailure.js"; import { HOST_PLATFORM } from "../../platform/HostPlatform.js"; import { snapshotEnvironment } from "../../process/snapshotEnvironment.js"; @@ -14,7 +18,6 @@ import { import { pwntoolsFailureDialect, pwntoolsUnavailable, - capturedPwntoolsOutput, pwntoolsBudgetRecovery, } from "./PwntoolsFailures.js"; import { randomUUID } from "node:crypto"; @@ -461,7 +464,7 @@ export class PwntoolsDecoder< options, failure, ); - const capturedOutput = capturedPwntoolsOutput(execution); + const capturedOutput = capturedProviderOutput(execution); let reply: z.output; try { let file; @@ -619,7 +622,7 @@ export class PwntoolsDecoder< input, payload: reply.value, snapshot, - diagnostics: capturedOutput, + diagnostics: providerResultDiagnostics(capturedOutput), }); if (replyFinalization !== undefined) { result = err( @@ -875,7 +878,7 @@ export class PwntoolsDecoder< reason: cause instanceof Error ? cause.message : String(cause), captured_output: { ...(pending.diagnostics ?? - capturedPwntoolsOutput(process.supervisor.snapshot())), + capturedProviderOutput(process.supervisor.snapshot())), }, previous_error: pending.failure === undefined diff --git a/src/native/pwntools/PwntoolsFailures.ts b/src/native/pwntools/PwntoolsFailures.ts index d0ae4b764a..c95e40b3a3 100644 --- a/src/native/pwntools/PwntoolsFailures.ts +++ b/src/native/pwntools/PwntoolsFailures.ts @@ -1,3 +1,4 @@ +import { capturedProviderOutput } from "../../process/capturedProviderOutput.js"; import { analysisSettingLimit } from "../../domain/analysisSettingDefinitions.js"; import { PWNTOOLS_LIMITS, @@ -235,7 +236,7 @@ const pwntoolsCommandContext = ( operation: context.operation, capturedOutput: (snapshot) => combinedPwntoolsOutput(snapshot, context) ?? - capturedPwntoolsOutput(snapshot), + capturedProviderOutput(snapshot), details: { // A failure before any output still reports the earlier stage's output. ...(context.precedingOutput === undefined @@ -362,7 +363,7 @@ const combinedPwntoolsOutput = ( context: PwntoolsFailureContext, ): AnalysisCapturedOutput | undefined => { const current = - snapshot === null ? undefined : capturedPwntoolsOutput(snapshot); + snapshot === null ? undefined : capturedProviderOutput(snapshot); const preceding = context.precedingOutput; if (preceding === undefined || current === undefined) return current ?? preceding; @@ -402,12 +403,3 @@ export const pwntoolsUnavailable = ( }, ], }); - -/** Retain bounded text output and the shared supervisor's observed truncation flag. */ -export const capturedPwntoolsOutput = ( - snapshot: ProviderProcessSnapshot, -): AnalysisCapturedOutput => ({ - stdout: snapshot.stdout.text, - stderr: snapshot.stderr.text, - truncated: snapshot.diagnosticTruncated === true, -}); diff --git a/src/pcap/PcapCommand.ts b/src/pcap/PcapCommand.ts index 57be0641a0..ed201bbebf 100644 --- a/src/pcap/PcapCommand.ts +++ b/src/pcap/PcapCommand.ts @@ -1,3 +1,4 @@ +import { capturedProviderOutput } from "../process/capturedProviderOutput.js"; import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js"; import { ProviderCleanupError } from "../domain/providerCleanupError.js"; import { @@ -100,17 +101,7 @@ export const runPcapCommand = async (options: { const captureDiagnostic = ( snapshot: ProviderProcessSnapshot, ): AnalysisCapturedOutput => - projectDiagnostic({ - stdout: snapshot.stdout.text, - stderr: snapshot.stderr.text, - stdout_bytes: snapshot.stdout.bytes, - stderr_bytes: snapshot.stderr.bytes, - exit_code: snapshot.exitCode ?? null, - signal: snapshot.signal ?? null, - truncated: - snapshot.diagnosticTruncated === true || - snapshot.outputIncomplete === true, - }); + projectDiagnostic(capturedProviderOutput(snapshot)); /** A version probe that fails names the tool; a capture read names the file. */ const pcapToolFailure = ( diagnostic: string, diff --git a/src/process/ArtifactAnalysisResources.ts b/src/process/ArtifactAnalysisResources.ts index af2bb27fc8..52fd3df2cd 100644 --- a/src/process/ArtifactAnalysisResources.ts +++ b/src/process/ArtifactAnalysisResources.ts @@ -1,3 +1,4 @@ +import { capturedProviderOutput } from "./capturedProviderOutput.js"; import { AnalysisCleanupLease, AnalysisCleanupLeaseGroup, @@ -91,16 +92,6 @@ export type ArtifactResourceClassifier = ( context: ArtifactResourceFailureContext, ) => AnalysisError; -export const artifactCommandOutput = ( - snapshot: ProviderProcessSnapshot, -): AnalysisCapturedOutput => ({ - stdout: snapshot.stdout.text, - stderr: snapshot.stderr.text, - truncated: snapshot.diagnosticTruncated ?? false, - exit_code: snapshot.exitCode ?? null, - signal: snapshot.signal ?? null, -}); - /** Own admission, artifact descriptors, producer cleanup and private workspaces together. */ export class ArtifactAnalysisResources { readonly #artifacts: { @@ -479,7 +470,7 @@ export class ArtifactAnalysisResources { ): ProviderOutcomeContext { return { operation, - capturedOutput: artifactCommandOutput, + capturedOutput: capturedProviderOutput, timeout: { ms: limits.command_timeout_ms, userMessage: `The owned producer command reached its ${String(limits.command_timeout_ms)} ms deadline. This is not a client-side timeout; extending only the MCP client's deadline does not change this budget.`, diff --git a/src/process/capturedProviderOutput.test.ts b/src/process/capturedProviderOutput.test.ts new file mode 100644 index 0000000000..a8a07c6ac9 --- /dev/null +++ b/src/process/capturedProviderOutput.test.ts @@ -0,0 +1,45 @@ +import { expect, it } from "vitest"; + +import { + capturedProviderOutput, + providerResultDiagnostics, +} from "./capturedProviderOutput.js"; +import type { ProviderProcessSnapshot } from "./ProviderProcess.js"; + +const snapshot = ( + overrides: Partial = {}, +): ProviderProcessSnapshot => ({ + stdout: { text: "head", bytes: 4, observedBytes: 4096 }, + stderr: { text: "", bytes: 0, observedBytes: 0 }, + exitCode: undefined, + signal: undefined, + ...overrides, +}); + +it("keeps the retained text beside the bytes the process wrote", () => { + expect( + capturedProviderOutput(snapshot({ diagnosticTruncated: true })), + ).toEqual({ + stdout: "head", + stderr: "", + stdout_bytes: 4096, + stderr_bytes: 0, + exit_code: null, + signal: null, + truncated: true, + }); +}); + +it("narrows to the three fields a successful result declares", () => { + expect( + providerResultDiagnostics( + capturedProviderOutput(snapshot({ exitCode: 0, signal: null })), + ), + ).toStrictEqual({ stdout: "head", stderr: "", truncated: false }); +}); + +it("reports exit facts and an untruncated capture as observed", () => { + expect( + capturedProviderOutput(snapshot({ exitCode: 2, signal: null })), + ).toMatchObject({ exit_code: 2, signal: null, truncated: false }); +}); diff --git a/src/process/capturedProviderOutput.ts b/src/process/capturedProviderOutput.ts new file mode 100644 index 0000000000..4a5430a20d --- /dev/null +++ b/src/process/capturedProviderOutput.ts @@ -0,0 +1,39 @@ +import type { AnalysisCapturedOutput } from "../domain/analysisErrorBase.js"; +import type { ProviderProcessSnapshot } from "./ProviderProcess.js"; + +/** + * The diagnostic a failure carries for one supervised provider process. + * + * Text is what the supervisor retained; the byte counts are what the process + * wrote, so a consumer can tell how much the retained text omits. `truncated` + * is the supervisor's own flag, which already includes provider output loss. + */ +export const capturedProviderOutput = ( + snapshot: ProviderProcessSnapshot, +): AnalysisCapturedOutput => ({ + stdout: snapshot.stdout.text, + stderr: snapshot.stderr.text, + stdout_bytes: snapshot.stdout.observedBytes, + stderr_bytes: snapshot.stderr.observedBytes, + exit_code: snapshot.exitCode ?? null, + signal: snapshot.signal ?? null, + truncated: snapshot.diagnosticTruncated === true, +}); + +/** The retained text and truncation flag a successful result reports as its diagnostics. */ +export interface ProviderResultDiagnostics { + readonly stdout: string; + readonly stderr: string; + readonly truncated: boolean; +} + +/** Narrow a captured output to the diagnostics a successful result declares. */ +export const providerResultDiagnostics = ({ + stdout, + stderr, + truncated, +}: AnalysisCapturedOutput): ProviderResultDiagnostics => ({ + stdout, + stderr, + truncated, +}); diff --git a/src/signals/SigrokRecordingProvider.ts b/src/signals/SigrokRecordingProvider.ts index fe32c4c4ce..811c891fca 100644 --- a/src/signals/SigrokRecordingProvider.ts +++ b/src/signals/SigrokRecordingProvider.ts @@ -1,3 +1,4 @@ +import { capturedProviderOutput } from "../process/capturedProviderOutput.js"; import { classifyProviderFailure, type ProviderFailureDialect, @@ -40,7 +41,6 @@ import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js"; import { ARTIFACT_PRODUCER_LIMITATION, ArtifactAnalysisResources, - artifactCommandOutput, type ArtifactAnalysisRuntime, } from "../process/ArtifactAnalysisResources.js"; import { @@ -248,7 +248,7 @@ export class SigrokRecordingProvider implements SignalRecordingPort { ...(this.launcher === undefined ? {} : { launcher: this.launcher }), }, ); - capturedOutput = artifactCommandOutput(output); + capturedOutput = capturedProviderOutput(output); await assertArtifactCommandPath(selectedCommand, operation, { capturedOutput, }); diff --git a/src/sqlite/SqliteDatabaseFailures.ts b/src/sqlite/SqliteDatabaseFailures.ts index d5d0f014d8..7a94b08a5e 100644 --- a/src/sqlite/SqliteDatabaseFailures.ts +++ b/src/sqlite/SqliteDatabaseFailures.ts @@ -1,3 +1,4 @@ +import { capturedProviderOutput } from "../process/capturedProviderOutput.js"; import { MAX_NODE_TIMER_DELAY_MS } from "../domain/analysisResourceLimits.js"; import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js"; import { @@ -41,15 +42,6 @@ import { type ProviderFailureDialect, } from "../providers/classifyProviderFailure.js"; -/** Preserve diagnostics independently of worker exit and private-root cleanup. */ -export const capturedSqliteOutput = ( - snapshot: ProviderProcessSnapshot, -): AnalysisCapturedOutput => ({ - stdout: snapshot.stdout.text, - stderr: snapshot.stderr.text, - truncated: snapshot.diagnosticTruncated === true, -}); - /** Keep typed cleanup history and one canonical output owner, including after resolution. */ export const createSqliteCleanupError = ( resources: readonly string[], @@ -193,7 +185,7 @@ export const sqliteDatabaseDialect = ( failure_kind: cause.reason, exit_code: cause.snapshot.exitCode ?? null, signal: cause.snapshot.signal ?? null, - captured_output: { ...capturedSqliteOutput(cause.snapshot) }, + captured_output: { ...capturedProviderOutput(cause.snapshot) }, } : {}), }, @@ -209,7 +201,9 @@ const ownedCommandFailure = ( ): AnalysisError | undefined => { const operation = "inspect_sqlite_database"; const capturedOutput = - cause.snapshot === null ? undefined : capturedSqliteOutput(cause.snapshot); + cause.snapshot === null + ? undefined + : capturedProviderOutput(cause.snapshot); const optionsWithoutCause = capturedOutput === undefined ? {} : { capturedOutput }; const options = { cause, ...optionsWithoutCause }; diff --git a/src/sqlite/SqliteDatabaseWorkerExecution.ts b/src/sqlite/SqliteDatabaseWorkerExecution.ts index 749d2bee30..e1425648e6 100644 --- a/src/sqlite/SqliteDatabaseWorkerExecution.ts +++ b/src/sqlite/SqliteDatabaseWorkerExecution.ts @@ -1,3 +1,4 @@ +import { capturedProviderOutput } from "../process/capturedProviderOutput.js"; import { safeParseUtf8Json } from "../domain/safeJson.js"; import { bindArtifactFileCleanup, @@ -41,7 +42,6 @@ import type { ProviderProcessSupervisor, ProviderProcessStopResult, } from "../process/ProviderProcess.js"; -import { capturedSqliteOutput } from "./SqliteDatabaseFailures.js"; import { SQLITE_DATABASE_LIMITS, SQLITE_INSPECTION_REASONS, @@ -254,7 +254,7 @@ export const executeSqliteDatabaseWorker = async (request: { : { retainCleanup: request.retainCleanup }), }, ); - const capturedOutput = capturedSqliteOutput(execution); + const capturedOutput = capturedProviderOutput(execution); request.captured(capturedOutput); let reply: z.output; let finalization: AnalysisError | undefined; diff --git a/src/wasm/WabtArtifactProvider.test.ts b/src/wasm/WabtArtifactProvider.test.ts index 25e7623f0a..ce69a18a38 100644 --- a/src/wasm/WabtArtifactProvider.test.ts +++ b/src/wasm/WabtArtifactProvider.test.ts @@ -367,6 +367,8 @@ it("preserves physical validation rejection when its diagnostics contain malform expect(result.error.capturedOutput).toEqual({ stdout: "", stderr: "invalid \ufffd", + stdout_bytes: 0, + stderr_bytes: 9, exit_code: 7, signal: null, truncated: false, diff --git a/src/wasm/WabtArtifactProvider.ts b/src/wasm/WabtArtifactProvider.ts index dadbbee1e0..ccbb595a13 100644 --- a/src/wasm/WabtArtifactProvider.ts +++ b/src/wasm/WabtArtifactProvider.ts @@ -1,3 +1,4 @@ +import { capturedProviderOutput } from "../process/capturedProviderOutput.js"; import { decodeStrictUtf8 } from "../domain/strictUtf8.js"; import { WabtAdmissionError } from "./WabtAdmissionError.js"; import { HOST_PLATFORM } from "../platform/HostPlatform.js"; @@ -56,7 +57,6 @@ import { err, ok, type Result } from "../domain/result.js"; import { runOwnedCommand } from "../process/OwnedCommand.js"; import { snapshotEnvironment } from "../process/snapshotEnvironment.js"; import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js"; -import { artifactCommandOutput } from "../process/ArtifactAnalysisResources.js"; import { assertArtifactCommandPath, selectArtifactCommandPath, @@ -353,7 +353,7 @@ export class WabtArtifactProvider implements WasmArtifactPort { ...(this.launcher === undefined ? {} : { launcher: this.launcher }), }, ); - capturedOutput = artifactCommandOutput(snapshot); + capturedOutput = capturedProviderOutput(snapshot); const invalidUtf8Streams = [ ...(snapshot.stdout.invalidUtf8 ? ["stdout"] : []), ...(snapshot.stderr.invalidUtf8 ? ["stderr"] : []), @@ -567,7 +567,7 @@ export class WabtArtifactProvider implements WasmArtifactPort { ], }, ), - capturedOutput: artifactCommandOutput(validation), + capturedOutput: capturedProviderOutput(validation), }, [ { @@ -594,7 +594,7 @@ export class WabtArtifactProvider implements WasmArtifactPort { OPERATION, "Unexpected WABT diagnostic output.", { - capturedOutput: artifactCommandOutput(output), + capturedOutput: capturedProviderOutput(output), }, ); if (warnings.length > 0) @@ -622,7 +622,7 @@ export class WabtArtifactProvider implements WasmArtifactPort { // WAT framing reads module names, not every inner name map. A producer // warning may concern a skipped body or another custom section; without // section attribution it cannot establish complete debug-name coverage. - capturedOutput = artifactCommandOutput(dump); + capturedOutput = capturedProviderOutput(dump); const { sections, headers, details, invalidNameEnds } = parseWabtOutput( dump.stdout.text, selected.bytes.length, @@ -644,7 +644,7 @@ export class WabtArtifactProvider implements WasmArtifactPort { OPERATION, "Unexpected WABT diagnostic output.", { - capturedOutput: artifactCommandOutput( + capturedOutput: capturedProviderOutput( warning.tool === "wasm-validate" ? validation : warning.tool === "wasm-objdump"