diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e5d2ea46f0..ecc5654086 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -418,8 +418,8 @@ installs that bundle with Skills 1.7.2 using default repository-root discovery and checks every installed file, alongside the packaged setup checks. CI validates generated outputs and retains them as artifacts; do not commit them. Reviewed source metadata, including -`src/generatedPackageMetadata.ts` and `docs/error-contract.schema.json`, remains -tracked and checked for freshness. +`src/generatedPackageMetadata.ts`, `docs/error-contract.schema.json` and +`docs/user-visible-errors.csv`, remains tracked and checked for freshness. The packaged skill contains instructions and inventory metadata, not runtime schema hashes. Its conformance commitment covers that exact bundle and portable diff --git a/docs/README.md b/docs/README.md index 7a8dce70ff..e5cbb0faae 100644 --- a/docs/README.md +++ b/docs/README.md @@ -133,14 +133,14 @@ product pages. The VitePress documentation source is this `docs/` tree. ## Machine-owned documentation -| Path | Owner and update command | -| ----------------------------------------- | ----------------------------------------------------------------------------------------- | -| `public/product-catalog.json` | Ignored contract projection; `npm run docs:generate` | -| `verification/managed-conformance-*.json` | Ignored managed conformance projections; `npm run evidence:generate` | -| `error-contract.schema.json` | Tracked schema from contracts; `npm run docs:error-schema` | -| `user-visible-errors.csv` | Authored error classification inventory; preserve its schema | -| `releases/.contributions.json` | Durable release contribution record; follow the [release guide](development/releasing.md) | -| `assets/` | Shared authored images referenced by guides | +| Path | Owner and update command | +| ----------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| `public/product-catalog.json` | Ignored contract projection; `npm run docs:generate` | +| `verification/managed-conformance-*.json` | Ignored managed conformance projections; `npm run evidence:generate` | +| `error-contract.schema.json` | Tracked schema from contracts; `npm run docs:error-schema` | +| `user-visible-errors.csv` | Generated error code and category per domain and provider-owned error case; `npm run docs:error-schema` | +| `releases/.contributions.json` | Durable release contribution record; follow the [release guide](development/releasing.md) | +| `assets/` | Shared authored images referenced by guides | Do not edit generated catalogs or evidence to change product facts. Change their canonical contracts or producer and regenerate. Historical release records retain diff --git a/docs/design/rea-limit-inventory.md b/docs/design/rea-limit-inventory.md index c257a30d9a..34366447dc 100644 --- a/docs/design/rea-limit-inventory.md +++ b/docs/design/rea-limit-inventory.md @@ -121,7 +121,7 @@ These stay out of `update_analysis_settings`. | ----------------------------------- | -------------------------------------- | ------------------: | -------: | ------------------------: | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `REA_DEBUGGER_MAX_PENDING_COMMANDS` | `src/domain/analysisResourceLimits.ts` | 16 | 1 | 256 | debugger manager construction | Queue capacity of the manager created at startup. `update_mode: "restart"` and `pending_restart: false`. | | `REA_DEBUGGER_MAX_SESSIONS` | `src/domain/analysisResourceLimits.ts` | 8 | 1 | 64 | debugger manager construction | Session-pool size of the manager created at startup. `update_mode: "restart"` and `pending_restart: false`. | -| `REA_HOPPER_DEMO_DIALOG_TIMEOUT_MS` | `src/domain/hopperStartupFailure.ts` | 10000 | 1 | 2147483647 | Linux private-display adapter start | The helper reads the process environment. Prose restart. | +| `REA_HOPPER_DEMO_DIALOG_TIMEOUT_MS` | `src/hopper/HopperStartupFailure.ts` | 10000 | 1 | 2147483647 | Linux private-display adapter start | The helper reads the process environment. Prose restart. | | `REA_JADX_ACTIVE_PROCESSOR_COUNT` | `src/android/JadxConfiguration.ts` | unset (JVM default) | 1 | 2147483647 | JADX JVM launch | `-XX:ActiveProcessorCount` is fixed for that JVM. Prose on invalid values. | | `REA_JADX_HEAP_MIB` | `src/android/JadxConfiguration.ts` | unset (JVM default) | 1 | `Number.MAX_SAFE_INTEGER` | JADX JVM launch | `-Xmx` is fixed for that JVM. Prose on invalid values. | | `REA_KUNA_CACHE_MAX_BYTES` | `src/kuna/KunaConfiguration.ts` | 4294967296 | 1048576 | `Number.MAX_SAFE_INTEGER` | Kuna cache construction | The cache is sized once for the provider. Prose restart. | diff --git a/docs/reverse-engineering-tools.md b/docs/reverse-engineering-tools.md index bb9a0c7c9d..4395beac84 100644 --- a/docs/reverse-engineering-tools.md +++ b/docs/reverse-engineering-tools.md @@ -142,7 +142,7 @@ rea debug-with-rizin --inferior-tty /dev/pts/7 ./program dr rea execute-rizin-command ./program iI ``` -Rizin exits with status 0 even when its shell refuses a statement, so the exit code does not show whether the command ran. Rizin 0.6 through 0.9.1 log one of four stderr lines for such a refusal: `ERROR: Command '…' does not exist.`, ``ERROR: Wrong number of arguments passed to `…`…``, `ERROR: core: Error while executing command: …` (an invalid statement), or `ERROR: core: Error while parsing command: …`. Rizin then skips the refused statement and every later one in the command. When the completed process's stderr contains one of these lines, REA reports `completion_status: "rejected"` and adds a limitation naming the refusal. stdout then holds only the output of earlier statements, so empty stdout is not an empty result. Other `ERROR:` lines, such as `ERROR: Cannot find function at …`, come from commands that ran; REA keeps them in stderr and reports `complete`. A command that lowers `log.level` or redirects stderr hides refusals from REA. +Rizin exits with status 0 even when its shell refuses a statement, so the exit code does not show whether the command ran. Rizin 0.6 through 0.9.1 log one of four stderr lines for such a refusal: `ERROR: Command '…' does not exist.`, ``ERROR: Wrong number of arguments passed to `…`…``, `ERROR: core: Error while executing command: …` (an invalid statement), or `ERROR: core: Error while parsing command: …`. Rizin then skips the refused statement and every later one in the command. When the completed process's stderr contains one of these lines, REA reports `completion_status: "rejected"`, a `refusal` record (`reason`: `unknown_command`, `wrong_argument_count`, `invalid_statement` or `parse_failure`; `command`: the command the line names, or null; `line`: the exact stderr line), and a limitation naming the refusal. stdout then holds only the output of earlier statements, so empty stdout is not an empty result. Other `ERROR:` lines, such as `ERROR: Cannot find function at …`, come from commands that ran; REA keeps them in stderr and reports `complete`. A command that lowers `log.level` or redirects stderr hides refusals from REA. Captured stdout and stderr use the same `max_output_bytes` (CLI: `--max-output-bytes`) admission and recovery described above, default 16 MiB. One-shot commands independently use `command_timeout_ms`. Raising output admission cannot recover an earlier capture; command effects and cleanup must be checked before another invocation. diff --git a/docs/user-visible-errors.csv b/docs/user-visible-errors.csv index 727094ef54..4f9e6d2873 100644 --- a/docs/user-visible-errors.csv +++ b/docs/user-visible-errors.csv @@ -1,127 +1,99 @@ -harm_rank,location,trigger,current_copy,user_risk,proposed_replacement,implementation_status,verification_result -5,src/domain/native/bytePattern.ts,Unconstrained byte signature,Pattern must constrain at least one bit,Low risk; identifies input correction,Keep current copy,implemented,parser and MCP validation tests -5,src/domain/native/bytePattern.ts,Unequal mask length,Mask length must equal pattern length,Low risk; identifies input correction,Keep current copy,implemented,parser and MCP validation tests -5,src/ghidra/GhidraByteSearchCursorFailure.ts:ghidraByteSearchCursorMismatch,Byte-search cursor does not match the current binding,"Byte search cursor does not match this search. It is bound to the target, analysis profile (including a selected Ghidra project), pattern, mask, bounds, and document, and does not identify which of those differs.",Previous copy named only the target and query and directed schema repair for a schema-valid cursor,"Name the bound values including the analysis profile, state that the differing component is unknown, attribute the issue to cursor, and omit recovery.kind=inspect_input_contract",implemented,provider projection test; real Ghidra not run -1,src/domain/errors.ts:AnalysisCapabilityUnavailableError,Requested analysis unavailable,"Provider {providerId} cannot execute {operation}: {reason}",Exposes provider and internal operation/reason,"This analysis is unavailable for the current target. Choose another analysis or target.",implemented,focused assertions passed; full `npm run check` passed -2,src/domain/errors.ts:ProviderAdapterError,Provider adapter fails,"Provider {providerId} adapter failed during {operation}",Exposes provider and implementation boundary,"The {providerId} provider could not complete {operation}, and REA did not classify the failure. Any reason the provider reported is in details.diagnostics. Recovery names `rea doctor --provider {providerId}` only when doctor can check that provider (hopper, ghidra, ida, jadx, kuna); otherwise it states that no specific recovery is known.",implemented,focused assertions passed; full `npm run check` passed -3,src/domain/errors.ts:HopperRemoteError,Remote analysis request fails,"Hopper request failed ({code}): {safeMessage}",Exposes provider name code and upstream text,"Analysis could not complete. Run `rea doctor` and review the reported details; repeating the unchanged request is not expected to succeed.",implemented,focused assertions passed; full `npm run check` passed -4,src/domain/errors.ts:HopperProtocolError,Malformed provider protocol result,Raw constructor message,Can expose provider protocol and implementation details,"Analysis returned a result REA could not read. Review the reported details; repeating the unchanged request is not expected to succeed.",implemented,focused assertions passed; full `npm run check` passed -5,src/domain/errors.ts:AnalysisOutputError,Analysis output fails parsing,"Invalid analysis output for {operation}: {reason}",Exposes internal operation and parser reason,"Analysis returned a result REA could not read. Review the reported details; repeating the unchanged request is not expected to succeed.",implemented,focused assertions passed; full `npm run check` passed -6,src/domain/errors.ts:AnalysisProtocolError,Application protocol fails,Raw constructor message,Can expose protocol internals,"Analysis returned a result REA could not read. Review the reported details; repeating the unchanged request is not expected to succeed.",implemented,focused assertions passed; full `npm run check` passed -7,src/domain/errors.ts:HopperProcessError,Analysis subprocess stops,"Hopper bridge stopped unexpectedly with code {exitCode}",Exposes provider bridge and process code,"Analysis could not start or stopped unexpectedly. Run `rea doctor`, then try again.",implemented,focused assertions passed; full `npm run check` passed -8,src/domain/errors.ts:HopperStartError,Analysis subprocess cannot start,Hopper application bridge could not be started,Exposes provider and bridge implementation,"Analysis could not start or stopped unexpectedly. Run `rea doctor`, then try again.",implemented,focused assertions passed; full `npm run check` passed -9,src/domain/errors.ts:BinaryTargetError,Target cannot open,"Cannot open artifact: {reason}",May expose raw reason and lacks checks,"Preserve the target admission reason; directories name analyze_javascript_application and rea analyze as available alternatives.",implemented,focused assertions passed; full `npm run check` passed -10,src/domain/errors.ts:ConfigurationError,Environment configuration invalid,Raw constructor message,May expose provider-specific variables and lacks recovery,"REA configuration is invalid. Run `rea doctor` and fix the reported setting.",implemented,focused assertions passed; full `npm run check` passed -11,src/domain/errors.ts:ArtifactOperationError,Artifact inventory or extraction fails,"Artifact {operation} failed: {reason} at {logicalPath} (declared_sha256=...)",Exposes paths hashes and internal reason,"Reason-specific plain message with safe recovery step.",implemented,focused assertions passed; full `npm run check` passed -12,src/domain/errors.ts:EvidenceFileError,Evidence file operation fails,"Evidence bundle {operation} failed: {reason}",Internal reason token gives weak recovery,"Reason-specific plain message with safe recovery step.",implemented,focused assertions passed; full `npm run check` passed -13,src/domain/errors.ts:EvidenceIntegrityError,Evidence validation fails,Raw constructor message,May expose validation internals and lacks recovery,"Evidence is invalid or has changed. Recreate or re-import it, then try again.",implemented,focused assertions passed; full `npm run check` passed -14,src/domain/analysisErrorPresentation.ts:UnknownRegistryError,Residual-unknown reference or graph constraint fails,Specific graph constraint and missing reference ID,Unchanged retries cannot repair missing references or insufficient proof,Correct the named reference or proof constraint; revision conflicts retain refresh recovery.,implemented,96 focused tests passed; real stdio correction and atomic-rejection controls passed -15,src/domain/errors.ts:ProcessCaptureError,Process capture fails,Raw constructor message,May expose process and cleanup internals,"Process capture could not complete. Check command access and limits, then try again.",implemented,focused assertions passed; full `npm run check` passed -16,src/domain/errors.ts:AnalysisTimeoutError,Analysis deadline expires,"REA's {operation} operation reached its {timeoutMs}ms server/provider deadline; extending only the client deadline does not change this budget",Returned server deadline is distinct from a host timeout that discards the response,"Inspect partial Evidence, provider diagnostics, and reported cleanup, then follow the returned remediation. Change a request field or REA_* setting only when the returned remediation explicitly recommends that change. Restart REA when that text says the value is read at startup. A mention that a control does not raise the deadline is not a recommendation to change it. When it names no setting, reduce supported work; do not invent one. JavaScript names analysis_timeout_ms and exact source_paths; omit an unneeded filter rather than passing an empty array.",implemented,generic projection does not invent a setting; producer remediation names analysis_timeout_ms or the applicable REA_* value; initialization and the shipped skill teach the same split -17,src/domain/errors.ts:HopperTimeoutError,Provider deadline expires,"Hopper did not respond within {timeoutMs}ms",Exposes provider and internal deadline,"Analysis took too long. Try a smaller request, then run `rea doctor` if it continues.",implemented,focused assertions passed; full `npm run check` passed -18,src/domain/errors.ts:ProviderSelectionError,Deep-provider selection fails,"Analysis provider selection failed ({reason}) for {requestedProviderId}; candidates: {candidateIds}",Retains non-secret local selection context that needs a safe structured projection,Reason-specific guidance with stable candidate IDs and actionable rejection diagnostics,implemented,focused registry/CLI/MCP assertions passed; full `npm run check` passed -20,src/domain/errors.ts:AnalysisInputError,Parsed analysis input invalid,"Invalid analysis input for {operation}",Exposes operation identifier and lacks correction,"Analysis input is invalid. Check the arguments and try again.",implemented,focused assertions passed; full `npm run check` passed -21,src/domain/errors.ts:AnalysisCancelledError,Caller cancels analysis,"Analysis operation was cancelled: {operation}",Exposes operation identifier,"Analysis was cancelled. Start it again when ready.",implemented,focused assertions passed; full `npm run check` passed -22,src/domain/errors.ts:HopperCancelledError,Caller cancels provider request,Hopper operation was cancelled,Exposes provider name,"Analysis was cancelled. Start it again when ready.",implemented,focused assertions passed; full `npm run check` passed -23,src/domain/errors.ts:NoBinaryOpenError,Analysis requested without target,"No app is open. Ask the user which app to investigate, then call open_binary with its local path.",Low risk; already supplies agent recovery,Keep current copy,implemented,focused assertions passed; full `npm run check` passed -24,src/server/toolResult.ts:successResult,Successful value violates public output schema,AnalysisOutputError: Analysis output does not match the tool contract,Exposes internal error tag and contract implementation,"Analysis returned an unreadable result. Run `rea doctor` and review the reported details; repeating the unchanged request is not expected to succeed.",implemented,focused assertions passed; full `npm run check` passed -24.5,src/server/registerEvidenceTools.ts:unavailable analysis,Analysis is unavailable without supporting Evidence,Unavailable error without a session unknown,Do not infer a persistent unknown without supporting Evidence,Return the unavailable error; session unknowns require supporting Evidence,approval-based tracking removed,Source and assertions inspected: tests/boundary/mcp/serverUnknownsMcp.test.ts; unavailable error leaves list_unknowns empty; test not rerun for this documentation change -24.6,src/application/ReferenceSourceImportEntries.ts:failed entry,A partial reference import contains an unreadable entry,Low-level reader diagnostic stored in entry limitations,Can persist filesystem or reader implementation details,"Code- and entry-specific safe guidance with a retry, limit, exclusion, or platform recovery step.",implemented,verified by exhaustive focused projection test -24.7,src/server/registerSessionTools.ts:process residual,Capture records a residual unknown linked to capture Evidence,SCOPE: RAW_REASON,Persists adapter diagnostic and implementation wording,"Was SCOPE behavior fully observed during capture?",implemented,verified by focused session MCP test -24.8,src/server/registerInvestigationTools.ts:changed behavior unknown,Changed-behavior workflow remains incomplete,"Changed behavior result EVIDENCE_ID remains STATUS",Persists internal evidence identifier,"Did both versions behave the same under a complete controlled replay?",implemented,verified by focused investigation MCP test -24.9,src/server/registerInvestigationTools.ts:call path unknown,Call-path workflow remains incomplete,Call path START_ADDRESS → GOAL_ADDRESS is STATUS,Persists binary addresses and internal status wording,Can the requested call path be established from complete analysis?,implemented,verified by focused unresolved call-path MCP test -24.91,src/server/registerInvestigationTools.ts:static runtime unknown,Static/runtime correlation remains incomplete,Static/runtime correlation result EVIDENCE_ID is STATUS,Persists internal evidence identifier,Does runtime behavior match the available static analysis?,implemented,verified by focused unresolved static/runtime MCP test -24.92,src/server/registerInvestigationTools.ts:reconstruction unknown,Reconstruction verification retains unknown claims,Reconstruction SPECIFICATION_HASH has unknown claims,Persists internal hash,Does the reconstruction satisfy every declared claim?,implemented,verified by focused unknown reconstruction MCP test -24.93,src/application/investigation/FunctionComparisonEvidence.ts:probe rationale,Function comparison is incomplete,Capture complete dossiers with equal providers and analysis limits.,Exposes provider architecture and gives ambiguous equality guidance,"Capture complete dossiers for both functions under the same target context.",implemented,Source and assertion inspected: tests/boundary/mcp/functionComparisonMcp.test.ts; test not rerun for this documentation change -24.95,incur:CLI argument validation,Caller omits or mistypes a command argument,VALIDATION_ERROR with raw Zod Details and fieldErrors including code/path/expected/received,Exposes validator representation and buries the useful correction,"REA could not read the command arguments. Check the named argument and its expected type, then try again.",implemented,verified by sanitizer unit tests and real dispatcher missing-argument test -25,src/application/ReferenceSourceImport.ts:cancelled,Reference-source import is cancelled,Reference source import cancelled,No recovery timing guidance,"Reference source import was cancelled. Start it again when ready.",implemented,focused assertions passed -26,src/application/ReferenceSourceImportPolicy.ts:invalid-limits,Configured import limits are not positive integers,Import limits must be positive integers,Fixed importer ceilings prevented full source imports,"Removed fixed byte, entry, depth, and path limits.",removed,verified by greater-than-10000 entry and greater-than-16-MiB regressions -27,src/application/ReferenceSourceImportPolicy.ts:invalid-root,Source path cannot resolve or is not a directory,Reference source root could not be resolved / Reference source root is not a directory,Multiple low-level copies and no complete path check,"Reference source directory could not be opened. Check that the path exists, is readable, and points to a directory.",implemented,focused assertions passed -28,src/application/ReferenceSourceImportPolicy.ts:policy,No approved root exists or requested root is outside policy,No approved reference source roots / Reference source root is outside approved roots,Approval friction duplicates direct caller path selection,Removed the configured root allowlist and permission gate; caller-selected directories are validated and traversed directly.,removed,verified by source search and focused import tests -29,src/application/ReferenceSourceImport.ts:io,Reader fails during traversal,Raw reader error message,May expose filesystem details and inconsistent recovery,"Reference source files could not be read. Check directory permissions and try again.",implemented,focused assertions passed -30,src/application/ReferenceSourceImport.ts:parse,Historical graph validation fails,Raw thrown graph validation message,Can expose internal graph invariants,"Reference source could not be indexed. Check that the source tree is readable, then try again.",implemented,focused assertions passed -31,src/application/ReferenceSourceImportTypes.ts:limit,Import reports terminal limit failure,No reachable constructor found,Declared state may be unreachable; false verification risk,Remove unreachable top-level limit variant; per-entry limit guidance remains caller-visible.,removed,"verified by typecheck, exhaustive projection test, and source search" -32,src/application/Setup.ts:configureDetectedClients(backup),Agent configuration backup fails,"{clientName} configuration backup verification failed; no successful configuration was reported.",Exposes machine client key and obscures no-write guarantee,"Agent configuration could not be backed up, so no change was made. Check file permissions, then rerun setup.",implemented,focused assertions passed -33,src/application/Setup.ts:configureDetectedClients(write),Agent configuration write fails,"{clientName} configuration write verification failed; no successful configuration was reported.",Exposes machine client key and gives no recovery,"Agent configuration could not be updated. Check file permissions, then rerun setup.",implemented,focused assertions passed -34,src/application/Setup.ts:configureDetectedClients(readback),Written agent configuration cannot be verified,"{clientName} configuration readback verification failed; no successful configuration was reported.",Exposes machine client key and omits backup recovery,"Agent configuration could not be verified after writing. The original was restored and its backup at {backupPath} was retained. Repair the configuration file or restore that backup, then rerun setup. Without a backup: Agent configuration could not be verified. Repair the configuration file, then rerun setup.",implemented,focused assertions passed -35,src/application/SetupSkill.ts:SetupSkillInstallError,Skill install or semantic readback fails,Stage and selected path; separate failure reason and recovery action,A non-directory path is not a demonstrated permission failure,Correct the reported failure; directory blockers retain regular-directory and --skill=false guidance.,implemented,"Public CLI ancestor/root refusal, preserved caller file, complete install and idempotent rerun; focused recovery tests" -36,src/main/reportMcpTransportError.ts:reportMcpTransportError,MCP pipe breaks or connection resets,"Retry the tool call once only when it is safe to repeat or known not to have started. If it may already have changed the target, or it fails again, tell the user REA lost its MCP client connection and ask them to restart the MCP client.",Retry safety and restart guidance for known disconnection,Keep current copy,implemented,injected EPIPE recovery regression -36,src/main/reportMcpTransportError.ts:reportMcpTransportError,MCP message fails schema validation,MCP message validation failed. Check the protocol fields before retrying a message that is safe to repeat. Continue using the connection while it remains responsive.,Validation failure does not establish connection loss,Keep current copy,implemented,public stdio invalid-ID controls followed by successful ping and file analysis -36,src/main/reportMcpTransportError.ts:reportMcpTransportError,MCP error has no known validation or disconnection identity,MCP reported an error with unknown connection state. Check whether the client is still connected before following connection-loss recovery.,Connection state remains unknown,Keep current copy,implemented,injected unknown-error recovery regression -37,src/main.ts:serveStdio throw,MCP connection cannot be created,Failed to start MCP stdio transport,Exposes transport implementation and gives no recovery,"Retry once. If it fails again, tell the user REA could not start its MCP connection and ask them to restart the MCP client, then run `rea doctor`.",implemented,verified by injected transport startup-throw runtime test -38,src/main.ts:requestShutdown catch,Connection or analysis session close rejects,Failed to shut down cleanly,Does not explain duplicate-process risk or recovery,REA could not close cleanly. End the REA process before starting it again.,implemented,verified by injected handle-close rejection runtime test -38.5,src/domain/analysisErrorRecovery.ts:cleanupRetryRemediation,close_binary returns cleanup_incomplete while the session retains the failed cleanup owners,"Provider cleanup could not be fully confirmed. Review the reported local resources before opening another target. (retryable: false, no recovery)",Agent could abandon the connection that owns the only cleanup retry,"Append: This connection retains that cleanup. Keep it open; after the reported condition settles or is resolved, call close_binary without snapshot_path and check its result. That call retries the retained cleanup without rerunning the failed analysis, preserves investigation Evidence and Unknown history, and can report cleanup_incomplete again. Add recovery.kind=retry_cleanup naming close_binary; keep retryable false",implemented,MCP close_binary with the real KunaProvider and a fake Kuna whose export stop stays unproven; process-capture MCP retry; session tests for an unoffered one-shot close and for failed and completed snapshot saves; one-shot IDA CLI cleanup reports no hint; real Kuna not run -39,src/main.ts:entrypoint catch,Unhandled rejection escapes run(),Unexpected server startup failure,Vague and lacks diagnostic recovery,"Do not repeat this startup. Tell the user REA could not start and ask them to restart the MCP client, then run `rea doctor`.",implemented,verified by injected entrypoint rejection test -40,src/application/Update.ts:unknown-install-method,Running package is not owned by detectable global npm installation,Update manually with: npm install --global rea-agents@latest,Old global-npm advice does not identify the owning installation,"Update this installation with the package manager or source checkout that owns it. For a one-off latest invocation, use npx rea-agents@latest.",implemented,36 Update tests passed; public CLI unowned-installation refusal verified with isolated package-manager fixtures -41,src/application/Update.ts:install,npm global install subprocess exits unsuccessfully,npm install --global rea-agents@latest failed.,Old registry/global-install advice omits the actual version prefix and installer failure,"REA could not install {version} in {prefix}: {failure}. Repair this npm installation, then rerun rea update.",implemented,36 Update tests passed; public CLI owned npm fixture failure preserved version prefix and installer reason -42,src/application/Uninstall.ts:removeClient read,Existing agent configuration cannot be read,Configuration could not be read.,No recovery step,"Configuration could not be read. Check file permissions, then rerun uninstall.",implemented,verified by injected filesystem read failure test -43,src/application/Uninstall.ts:removeClient parse,Agent configuration is malformed,Malformed configuration was preserved without mutation.,Does not name required repair format or retry,"Configuration is not valid JSON/TOML and was not changed. Repair it, then rerun uninstall.",implemented,focused JSON assertion passed; TOML path uses same branch -44,src/application/Uninstall.ts:removeClient backup,Configuration backup copy fails,Configuration backup failed; no mutation was attempted.,No recovery step,"Configuration could not be backed up, so no change was made. Check file permissions, then rerun uninstall.",implemented,verified by injected filesystem backup failure test -45,src/application/Uninstall.ts:removeClient update,Write or semantic readback fails,Configuration update failed; the original was restored and {backupPath} was retained.,Exposes local path and lacks clear next sequence,"Report whether the original was restored; if restoration also fails, direct the user to the retained backup.",implemented,verified by injected update and restoration failure tests -45.5,src/application/Uninstall.ts:removeClient restore,Configuration update fails and restoring the original also fails,"Configuration could not be updated or restored. Restore the backup at {backupPath} manually, then rerun uninstall.","High risk; persistent configuration may be damaged, but retained backup is authoritative",Keep new recovery copy,implemented,verified by injected restoration failure test -46,src/application/Uninstall.ts:removeManagedPath symlink,Managed cache/state/skill path is a symbolic link,Refused to follow symlink {path}.,Exposes local path and does not explain manual safety check,"REA did not remove this item because its managed path is a symbolic link. Verify the link target before removing it manually.",implemented,focused assertion passed -47,src/application/Uninstall.ts:removeManagedPath failure,Managed item removal fails,{path} could not be removed.,Exposes local path and gives no recovery,"This item could not be removed. Check file permissions, then rerun uninstall.",implemented,verified by injected managed-path removal failure test -48,src/application/DoctorDiagnostics.ts:node,Runtime version is outside supported ranges,"Install Node.js 22.x (>=22.23.4), 24.x (>=24.22.1), or 26.12.1+.",Low risk; exact dependency recovery,Keep current copy,unchanged,verified by doctor unit test -49,src/application/DoctorDiagnostics.ts:host,Host OS/distribution is unsupported,"REA supports macOS 12+, Linux distributions with a recognized apt, dnf, or pacman package family, and the experimental Windows x64 Ghidra P0 boundary; automated Hopper setup additionally requires Ubuntu 24.04+, Fedora 41+, Nobara 44+, 64-bit Arch Linux, CachyOS, or Omarchy.",Low risk; clearly states supported choices,Keep current copy,unchanged,verified by doctor unit tests -50,src/application/Doctor.ts:analysis engine,Optional deep-analysis executable cannot be found,"Run rea setup to install Hopper, or set HOPPER_LAUNCHER_PATH.",Low risk in setup-specific diagnostic; exact recovery paths,Keep current copy,unchanged,verified by doctor unit tests -51,src/application/Doctor.ts:target,Optional target path fails shared validation,Supply a readable local app or program path.,Low risk; tells caller valid target class,Keep current copy,unchanged,verified by doctor unit test -52,src/application/Setup.ts:approval,Setup plan lacks approval,"Review the setup plan, then rerun interactively or with --yes.",Low risk; exact authorization recovery,Keep current copy,unchanged,verified by setup unit tests -53,src/application/Setup.ts:engine install,Approved analysis-engine installation returns no launcher,Hopper installation failed; install Hopper manually or rerun setup after resolving the reported system error.,Mentions component intentionally being installed and offers two bounded recovery paths,Keep current copy,unchanged,verified by setup unit test -54,src/application/Setup.ts:first-run choice,New macOS analysis-engine install requires a first-run choice,"Open Hopper, choose its demo mode or activate a license, then rerun rea doctor --json.",Low risk; exact demo-or-license choice and verification command,Keep current copy,unchanged,verified by setup unit test -55,src/application/Setup.ts:optional engine,Setup completes without optional deep-analysis engine on a host where automated Hopper installation is supported,Hopper is optional for non-Hopper providers. Rerun with --yes --install-hopper for deep native analysis.,Exposes provider terminology but this is an explanatory setup status rather than an error; recovery command is exact,Keep current copy,unchanged,verified by setup unit test -56,src/application/Setup.ts:doctor fallback,Post-setup diagnostics remain unhealthy (including hosts where automated Hopper installation is unsupported),Run rea doctor and apply each reported remediation.,Low risk; delegates to structured per-check recovery,Keep current copy,unchanged,verified by exact setup unit test -57,src/application/SetupPlan.ts:unsupported platform,Platform is neither macOS nor Linux,REA supports Hopper on macOS and selected x86_64 Linux distributions.,Low risk; states support boundary,Keep current copy,unchanged,verified by setup unit test -58,src/application/SetupHost.ts:unsupported Node,Runtime version cannot run setup,"Install Node.js 22.x (>=22.23.4), 24.x (>=24.22.1), or 26.12.1+ and rerun setup.",Low risk; exact dependency and retry,Keep current copy,unchanged,verified by setup host tests -59,src/application/SetupPlan.ts:unsupported macOS,"macOS version is missing, unparseable, or older than 12",Upgrade to macOS 12 or newer.,Low risk; exact support floor,Keep current copy,unchanged,verified by setup unit test -60,src/application/SetupPlan.ts:unsupported Linux,Linux distribution is outside supported set,"Automated Hopper setup requires an x86_64 host running Ubuntu 24.04+, Fedora 41+, Nobara 44+, Arch Linux, CachyOS, or Omarchy; configure an existing supported provider instead.",Low risk; exact supported alternatives,Keep current copy,unchanged,verified by setup unit test -61,src/application/process/ProcessCli.ts:readJson read,Process scenario or evidence path is missing or is not a regular file,Raw filesystem exception through CLI framework,Lacks actionable recovery; preserve caller-selected paths and filesystem failure details,"Process input file could not be read: {path} ({detail}). Check the reported filesystem constraint and retry.",implemented,Source and missing-path assertion inspected: tests/boundary/filesystem/processCliFileInput.test.ts; test not rerun for this documentation change -62,src/application/JsonInputFile.ts:memory admission,Projected process JSON value exceeds available heap headroom,Insufficient heap headroom to materialize the complete JSON value,Heap admission depends on live runtime capacity rather than a fixed 64 MiB file limit,"Provide a smaller valid JSON value. For Evidence workflows, re-analyze a smaller selection of the original target and use its complete Evidence; splitting JSON text or trimming Evidence fields does not produce valid workflow input.",implemented,Source verified against shared JSON reader and recovery constant; former fixed-size refusal is superseded -63,src/application/process/ProcessCli.ts:readJson parse,Process scenario or evidence file is malformed JSON or invalid UTF-8,Raw JSON parser exception through CLI framework,Lacks actionable recovery; preserve the selected path and failure detail,"Process input file is not valid UTF-8 JSON: {path} ({detail}). Repair the file, then try again.",implemented,Source and malformed-JSON/UTF-8 assertions inspected: tests/boundary/filesystem/processCliFileInput.test.ts; test not rerun for this documentation change -64,src/application/process/ProcessCli.ts:capture scenario parse,Scenario fails Process Capture schema,Raw Zod validation exception through CLI framework,Unstructured schema details obscure actionable field errors,"Analysis input is invalid. Check the arguments and try again.",implemented,Source and scenario-validation assertion inspected: tests/boundary/filesystem/processCliFileInput.test.ts; structured issues retain field paths; test not rerun for this documentation change -66,src/application/process/ProcessCli.ts:wrong evidence,Comparison receives valid Evidence from another workflow,Expected REA process capture Evidence,Uses internal schema name and does not explain recovery,"Capture evidence is not from the current process-capture workflow. Create new capture evidence, then try again.",implemented,verified by focused CLI test -67,src/application/process/ProcessCli.ts:unexpected,Unexpected parser/comparison/canonicalization failure escapes expected classifications,Raw thrown exception through CLI framework,Can expose stack or internal invariant,"Message keeps the sanitized cause. Remediation: Do not repeat this command. Tell the user the process command could not complete, give them the reported reason, and ask them to check the scenario or capture files it read. If those files are valid, report the failure with its diagnostics.",implemented,verified by direct unexpected-cause projection test -68,src/server/registerEvidenceTools.ts:object guard,Validated provider-tool input is unexpectedly not an object,Provider tool input was not an object,Exposes provider architecture and implies caller can fix impossible state,Remove the impossible duplicate guard and parse through the declared JSON-object schema.,removed,verified by typecheck and MCP integration tests -69,src/server/registerEnhancedTools.ts:object guard,Validated enhanced-tool input is unexpectedly not an object,Validated enhanced input was not a JSON object,Exposes validation/JSON implementation detail,Remove the impossible duplicate guard and parse through the declared JSON-object schema.,removed,verified by typecheck and enhanced MCP integration tests -70,src/server/registerOfficialTools.ts:object guard,Validated direct-tool input is unexpectedly not an object,Validated MCP tool input was not a JSON object,Exposes MCP validation implementation detail,Remove the impossible duplicate guard and parse through the declared JSON-object schema.,removed,verified by typecheck and official MCP integration tests -71,src/application/process/ProcessComparisonService.ts:canonical guard,Process comparison value cannot become canonical JSON,Process capture could not be canonicalized,Names internal serialization invariant and gives no recovery,Remove the impossible canonicalization error branch; compare schema-validated values directly.,removed,verified by process-comparison MCP tests and source search -72,src/server/sessionEvidence.ts:canonical guard,Recorded Evidence cannot become canonical JSON,Evidence could not be canonicalized,Names internal serialization invariant and gives no recovery,Remove the impossible canonicalization error branch; compare parsed Evidence directly.,removed,verified by session Evidence integrity tests and source search -73,install.sh:--version value,--version has no following value,--version requires a value.,Low risk; identifies correction,Keep current copy,unchanged,verified by shell branch inspection -74,install.sh:unknown option,Installer receives an unsupported flag,unknown option with caller-provided flag,Low risk; identifies offending input,Keep current copy,unchanged,verified by shell branch inspection -75,install.sh:platform,Installer runs outside macOS or supported Linux,REA supports macOS and selected 64-bit Linux distributions.,Low risk; states support boundary,Keep current copy,unchanged,verified by shell branch inspection -76,install.sh:curl missing,curl is absent,curl is required.,No recovery instruction,"curl is required. Install curl, then rerun this installer.",implemented,verified by exact missing-curl installer test -77,install.sh:node missing,node is absent,"Node.js 22.x (>=22.23.4), 24.x (>=24.22.1), or 26.12.1+ is required; install it from nodejs.org and retry.",Low risk; exact versions and recovery,Keep current copy,unchanged,verified by shell branch inspection -78,install.sh:npm missing,npm is absent,npm is required; install it with Node.js and retry.,Low risk; exact recovery,Keep current copy,unchanged,verified by shell branch inspection -79,install.sh:node unreadable,node exists but does not report a parseable version,could not determine the active Node.js version.,No cause-local recovery,"The active Node.js version could not be read. Check that node works and is on PATH, then retry.",implemented,verified by exact unreadable-Node-version installer test -80,install.sh:Node 22 floor,Node 22 version is below 22.23.4,"Node.js VERSION is unsupported; use Node.js 22.x (>=22.23.4), 24.x (>=24.22.1), or 26.12.1+.",No install guidance; operator must guess between nvm/fnm/system packages/nodejs.org,"Node.js VERSION is unsupported. - -REA requires Node.js 22.x (>=22.23.4), 24.x (>=24.22.1), or 26.12.1+. Install one via: - nvm: nvm install 24 && nvm use 24 (https://github.com/nvm-sh/nvm) - fnm: fnm install 24 && fnm use 24 (https://github.com/Schniz/fnm) - Direct download for OS/ARCH: - https://nodejs.org/dist/latest-v24.x/ (grab the OS-ARCH tarball) -Then rerun this installer.",implemented,verified by exact installer test using Node 20 against the `linux/x64` fake host and by shell branch inspection -81,install.sh:Node 24 floor,Node 24 version is below 24.22.1,"Node.js VERSION is unsupported; use Node.js 22.x (>=22.23.4), 24.x (>=24.22.1), or 26.12.1+.",No install guidance; operator must guess between nvm/fnm/system packages/nodejs.org,"Node.js VERSION is unsupported. - -REA requires Node.js 22.x (>=22.23.4), 24.x (>=24.22.1), or 26.12.1+. Install one via: - nvm: nvm install 24 && nvm use 24 (https://github.com/nvm-sh/nvm) - fnm: fnm install 24 && fnm use 24 (https://github.com/Schniz/fnm) - Direct download for OS/ARCH: - https://nodejs.org/dist/latest-v24.x/ (grab the OS-ARCH tarball) -Then rerun this installer.",implemented,verified by shell branch inspection -82,install.sh:version syntax,Explicit version is not exact semantic version,version must be an exact semantic version.,Low risk; exact correction,Keep current copy,unchanged,verified by shell branch inspection -83,install.sh:release lookup,Latest GitHub release request fails,could not resolve the latest GitHub release.,No fallback despite supporting pinned versions,"The latest REA release could not be resolved. Check network access or pass --version VERSION, then retry.",implemented,verified by exact release-lookup installer test -84,install.sh:release response,Latest release response is not valid expected JSON,Node JSON parser stack followed by the safe release-response message,Leaks a parser stack and buries recovery guidance,The release response was invalid. Retry later or pass --version VERSION.,implemented,verified by exact malformed-release test with parser stderr suppressed -85,install.sh:release tag,Latest release tag does not match REA release convention,latest release tag is not a valid rea-agents release.,Exposes package naming detail and omits fallback,The latest release tag was invalid. Retry later or pass --version VERSION.,implemented,verified by exact invalid-release-tag installer test -86,install.sh:npm prefix,npm cannot return its global prefix,could not determine the npm global prefix.,No recovery instruction,"The npm global prefix could not be read. Repair the npm configuration, then retry.",implemented,verified by exact macOS npm-prefix installer test -87,install.sh:npm install,npm global installation exits nonzero,npm package installation failed.,No likely causes or recovery,"npm could not install REA. Check registry access and npm permissions, then retry.",implemented,verified by exact installer test -88,install.sh:binary absent,npm exits successfully without executable,the rea command was not installed at local path,Leaks local path and no recovery,"npm completed without installing the rea command. Check the npm global bin directory and PATH, then retry.",implemented,verified by exact absent-installed-command test -89,install.sh:version read,Installed rea executable cannot report its version,could not read the installed REA version.,No recovery instruction,"The installed REA version could not be read. Reinstall the requested version, then retry.",implemented,verified by exact unreadable-installed-version test -90,install.sh:version mismatch,Installed rea reports a different version,installed version ACTUAL does not match EXPECTED.,Low risk; gives exact integrity mismatch,Keep current copy,unchanged,verified by exact installer test -90.5,@modelcontextprotocol/server:tool input validation,Caller sends arguments that violate a declared tool schema,"Canonical invalid_request with the SDK diagnostic plus recovery.kind=inspect_input_contract and a bounded instruction to read the advertised schema or call tools/list",Keeps field/type correction while telling the agent how to recover; diagnostics over 4 KiB stay on the existing retained-error path,Normalize ordinary validation failures and retain oversized diagnostics,implemented,verified by real in-memory and stdio MCP client/server calls with wrong argument types -90.6,incur:unknown CLI command,Caller enters an unknown REA command,"'COMMAND' is not a command for 'rea'. Suggested command: rea --help",Low risk; identifies input and exact discovery action,Keep framework-generated copy,unchanged,verified by real packaged dispatcher invocation -90.7,src/ghidra/GhidraProviderClient.ts:projectPrimarySessionError,One procedure's decompile reaches REA_GHIDRA_DECOMPILE_TIMEOUT_SECONDS,"Ghidra decompilation of {entry} exceeded the {N}-second limit set by REA_GHIDRA_DECOMPILE_TIMEOUT_SECONDS. Only this procedure's decompilation was stopped. (MCP adds: The Ghidra session remains usable.)",Low risk; names the setting; only a continuing MCP caller is told the session remains usable,Keep current copy,implemented,"provider projection test, CLI/MCP fixture-bridge boundary test and real-provider lane" -90.8,src/ghidra/GhidraFileOffsetFailure.ts:ghidraFileOffsetUnavailable,"address_to_file_offset receives a well-formed address that is unmapped, uninitialized, without an authoritative target-file source, ambiguous or beyond the exact JSON integer range",{bridge reason}. REA establishes no single exact original-file offset for this well-formed address and does not derive or choose one.,Previous copy called the input invalid and directed schema repair for a valid address,"Keep the bridge reason as the headline, point to inspect_native_load_image, omit recovery.kind=inspect_input_contract and record details.issues[0].observed.file_mapping",implemented,provider projection tests; MCP and CLI analysis path through the real Ghidra client with a simulated bridge; real Ghidra not run -91,src/application/binaryDiagnostics/ByteEntropyService.ts (issues); src/domain/analysisErrorPresentation.ts (recovery),Invalid file or window,Expected a regular file.; Selected file could not be found.; Selected byte window starts beyond the end of the file.; Selected byte window extends beyond the end of the file.; File size exceeds exact numeric offset representation.,Invalid selection cannot produce complete entropy Evidence,"Read the declared input schema or CLI usage for inspect_byte_entropy; if using MCP and the catalog may be stale, call tools/list. Correct the listed fields, then retry. Do not repeat the unchanged call.",unchanged,Executed CLI/stdio MCP: path/offset/length refusals and tiny + system-binary controls; shared canonical recovery; service/MCP tests check classification and fields; remaining listed errors source-inspected -92,src/domain/analysisView/byteEntropyView.ts,Non-summary entropy view,Byte entropy Evidence supports the summary view; retrieve parent Evidence for the complete block series.,Unsupported view selection,Use the summary view or retrieve complete parent Evidence,implemented,typed input rejection -93,src/windows/WindowsNativeLoader.ts:load refused,Windows refuses to load the digest-verified native addon (for example Smart App Control or App Control policy),"REA Windows native controls are unavailable: Windows refused to load the verified native/windows/build/rea-windows-x64.node: {OS error} The file matched the package manifest, so restoring or reinstalling it will not help. ...",Previous artifact copy told users to restore or rebuild files that were already intact,"Name the OS refusal, say restoring cannot help, state that Ghidra and JADX need native controls while setup can still register clients, and point to a policy-allowed host or a maintainer-signed build",implemented,simulated loader refusal unit test; real Smart App Control block not reproduced -94,src/android/JadxFailure.ts:startup failure,"JADX worker heap too small for REA's bridge, so the JVM stops before the protocol handshake","Java could not start REA's Android bridge using : Connection closed. Review the retained launcher diagnostics. Review the selected Java/JADX configuration; for a JVM memory limit, review REA_JADX_HEAP_MIB and inherited JVM options such as JAVA_TOOL_OPTIONS.","Buried: reported as capability_unavailable, so a caller cannot tell a heap limit from a missing JDK","The JADX worker JVM ran out of heap before REA's Android bridge answered. Increase REA_JADX_HEAP_MIB (MiB) in the environment that starts REA, within the host or container memory budget. REA passes it as an explicit -Xmx, so JAVA_TOOL_OPTIONS and JDK_JAVA_OPTIONS set the heap only while it is unset, and _JAVA_OPTIONS overrides it. An observed heap is this run's limit, not the heap the APK requires.",implemented,child-process MCP fixture (start-heap-exhausted) integration test and stderr classification test +tag,discriminant,code,category,retryable_by_default +AnalysisProtocolError,,unreadable_output,execution_failure,false +AnalysisOutputError,,unreadable_output,execution_failure,false +AnalysisInputError,,invalid_request,invalid_input,false +AnalysisAccessDeniedError,,access_denied,unavailable,false +AnalysisArtifactChangedError,,artifact_changed,integrity_mismatch,true +AnalysisCapabilityUnavailableError,,capability_unavailable,unsupported_provider,false +AnalysisUnsupportedTargetError,,unsupported_target,unsupported_target,false +AnalysisCancelledError,,cancelled,cancelled,true +AnalysisTimeoutError,,provider_timeout,timeout,true +AnalysisResourceConstraintError,,resource_constraint,resource_constraint,false +ConfigurationError,,configuration_invalid,invalid_input,false +NoBinaryOpenError,,target_unavailable,unavailable,false +EvidenceIntegrityError,,evidence_integrity_mismatch,integrity_mismatch,false +ProviderAdapterError,,execution_failure,execution_failure,false +AnalysisCapabilityUnavailableError,retryable=true,capability_unavailable,unavailable,true +ArtifactOperationError,reason=cancelled,cancelled,cancelled,true +ArtifactOperationError,reason=format,artifact_operation_failed,execution_failure,false +ArtifactOperationError,reason=integrity,artifact_operation_failed,integrity_mismatch,false +ArtifactOperationError,reason=limit,truncated,truncated,false +ArtifactOperationError,reason=path,artifact_operation_failed,execution_failure,false +ArtifactOperationError,reason=unavailable,artifact_operation_failed,unavailable,false +ArtifactOperationError,reason=io,artifact_operation_failed,execution_failure,false +ArtifactOperationError,reason=integrity; artifact identity reported,artifact_integrity_mismatch,integrity_mismatch,false +BinaryTargetError,constraint=unconstrained,target_unavailable,unavailable,false +BinaryTargetError,constraint=unconstrained; read permission denied,access_denied,unavailable,false +BinaryTargetError,constraint=directory_requires_file,target_unavailable,unavailable,false +BinaryTargetError,constraint=directory_requires_file; read permission denied,access_denied,unavailable,false +BinaryTargetError,constraint=wasm_requires_static_inspection,target_unavailable,unsupported_target,false +BinaryTargetError,constraint=wasm_requires_static_inspection; read permission denied,access_denied,unsupported_target,false +BinaryTargetError,constraint=file_format_rejected,target_unavailable,unsupported_target,false +BinaryTargetError,constraint=file_format_rejected; read permission denied,access_denied,unsupported_target,false +BinaryTargetError,constraint=load_selection_rejected,invalid_request,invalid_input,false +BinaryTargetError,constraint=bundle_type_unsupported,target_unavailable,unsupported_target,false +BinaryTargetError,constraint=bundle_type_unsupported; read permission denied,access_denied,unsupported_target,false +BinaryTargetError,constraint=bundle_info_plist_missing,target_unavailable,unavailable,false +BinaryTargetError,constraint=bundle_info_plist_missing; read permission denied,access_denied,unavailable,false +BinaryTargetError,constraint=bundle_layout_ambiguous,target_unavailable,unavailable,false +BinaryTargetError,constraint=bundle_layout_ambiguous; read permission denied,access_denied,unavailable,false +BinaryTargetError,constraint=bundle_executable_undeclared,target_unavailable,unavailable,false +BinaryTargetError,constraint=bundle_executable_undeclared; read permission denied,access_denied,unavailable,false +BinaryTargetError,constraint=bundle_program_missing,target_unavailable,unavailable,false +BinaryTargetError,constraint=bundle_program_missing; read permission denied,access_denied,unavailable,false +BinaryTargetError,constraint=bundle_current_version_missing,target_unavailable,unavailable,false +BinaryTargetError,constraint=bundle_current_version_missing; read permission denied,access_denied,unavailable,false +BinaryTargetError,constraint=bundle_path_escapes,target_unavailable,unavailable,false +BinaryTargetError,constraint=bundle_path_escapes; read permission denied,access_denied,unavailable,false +BrowserObservationError,reason=endpoint_unreachable,provider_unavailable,unavailable,true +BrowserObservationError,reason=invalid_endpoint_response,unreadable_output,execution_failure,false +BrowserObservationError,reason=target_not_found,target_unavailable,unavailable,false +BrowserObservationError,reason=target_not_allowed,target_unavailable,unavailable,false +BrowserObservationError,reason=application_already_running,target_unavailable,unavailable,false +BrowserObservationError,reason=service_worker_blocked,target_unavailable,unavailable,false +BrowserObservationError,reason=target_changed,target_unavailable,unavailable,false +BrowserObservationError,reason=target_session_detached,target_unavailable,unavailable,false +BrowserObservationError,reason=protocol_error,unreadable_output,execution_failure,false +BrowserObservationError,reason=disconnected,provider_unavailable,unavailable,true +BrowserObservationError,reason=payload_limit,truncated,truncated,false +BrowserObservationError,reason=window_not_found,unreadable_output,execution_failure,false +BrowserObservationError,reason=window_metadata_missing,unreadable_output,execution_failure,false +BrowserObservationError,reason=process_ownership_unavailable,unreadable_output,execution_failure,false +BrowserObservationError,reason=cleanup_failed,execution_failure,execution_failure,false +BrowserObservationError,reason=cancelled,cancelled,cancelled,true +BrowserObservationError,reason=timeout,provider_timeout,timeout,true +BrowserObservationError,caused by cancellation,cancelled,cancelled,true +EvidenceFileError,reason=not-file,invalid_request,invalid_input,false +EvidenceFileError,reason=exists,invalid_request,invalid_input,false +EvidenceFileError,reason=wrong-kind,invalid_request,invalid_input,false +EvidenceFileError,reason=missing,invalid_request,invalid_input,false +EvidenceFileError,reason=symlink-traversal,invalid_request,invalid_input,false +EvidenceFileError,reason=invalid-json,evidence_integrity_mismatch,execution_failure,false +EvidenceFileError,reason=path-limit,resource_constraint,resource_constraint,false +EvidenceFileError,reason=storage-limit,resource_constraint,resource_constraint,false +EvidenceFileError,reason=io,execution_failure,execution_failure,false +ProcessCaptureError,,process_capture_failed,execution_failure,false +ProcessCaptureError,caused by cancellation,cancelled,cancelled,true +ProviderSelectionError,reason=unknown_provider,capability_unavailable,unsupported_provider,false +ProviderSelectionError,reason=provider_unavailable,provider_unavailable,unavailable,true +ProviderSelectionError,reason=target_unsupported,capability_unavailable,unsupported_provider,false +ProviderSelectionError,reason=ambiguous,capability_unavailable,unsupported_provider,false +ProviderSelectionError,reason=invalid_options,capability_unavailable,unsupported_provider,false +UnknownRegistryError,reason=not-found,execution_failure,execution_failure,false +UnknownRegistryError,reason=already-exists,invalid_request,invalid_input,false +UnknownRegistryError,reason=revision-conflict,revision_conflict,execution_failure,true +UnknownRegistryError,reason=invalid-transition,execution_failure,execution_failure,false +UnknownRegistryError,reason=integrity,evidence_integrity_mismatch,execution_failure,false +UnknownRegistryError,reason=limit,truncated,execution_failure,false +UnknownRegistryError,reason=constraint,invalid_request,invalid_input,false +HopperTimeoutError,,provider_timeout,timeout,true +HopperCancelledError,,cancelled,cancelled,true +HopperProtocolError,,unreadable_output,execution_failure,false +HopperRemoteError,diagnostic_type=remote,execution_failure,execution_failure,false +HopperRemoteError,diagnostic_type=authorization,execution_failure,unavailable,false +HopperRemoteError,diagnostic_type=invalid_request,invalid_request,invalid_input,false +HopperRemoteError,diagnostic_type=capability_unavailable,execution_failure,execution_failure,false +HopperRemoteError,diagnostic_type=bridge_exception,execution_failure,execution_failure,false +HopperProcessError,,provider_unavailable,unavailable,true +HopperStartError,,provider_unavailable,unavailable,true +HopperStartError,Apple Events authorization denied,provider_unavailable,unavailable,false diff --git a/scripts/ci/scopes.mjs b/scripts/ci/scopes.mjs index c5f9390b74..e57b91fe18 100644 --- a/scripts/ci/scopes.mjs +++ b/scripts/ci/scopes.mjs @@ -143,7 +143,7 @@ const PATH_SCOPES = { "tests/boundary/filesystem/inesArtifact.test.ts", "tests/boundary/filesystem/inesCancellation.test.ts", "src/hopper/BridgeLauncher.ts", - "src/domain/hopperErrors.ts", + "src/hopper/HopperErrors.ts", "tests/boundary/providers/hopper/hopperMacLaunchArguments.test.ts", "tests/acceptance/providers/hopperStartupRecovery.test.ts", "tests/boundary/providers/hopper/hopperClient.helperFailure.test.ts", diff --git a/scripts/generate-error-schema.mjs b/scripts/generate-error-schema.mjs index f9430f9510..483ff76312 100644 --- a/scripts/generate-error-schema.mjs +++ b/scripts/generate-error-schema.mjs @@ -2,6 +2,8 @@ import { dirname, join } from "node:path"; import { fileURLToPath } from "node:url"; import { analysisErrorJsonSchema } from "../dist/contracts/errorSchemas.js"; +import { analysisErrorCatalogue } from "../dist/domain/analysisErrorClassification.js"; +import { hopperErrorCatalogue } from "../dist/hopper/HopperErrors.js"; import { formatGeneratedFile } from "./lib/format-generated-file.mjs"; import { ensureGeneratedFile } from "./lib/generated-file.mjs"; @@ -11,12 +13,41 @@ for (const argument of arguments_) throw new Error(`Unknown error schema option: ${argument}`); const root = join(dirname(fileURLToPath(import.meta.url)), ".."); +const check = arguments_.has("--check"); await ensureGeneratedFile({ path: join(root, "docs/error-contract.schema.json"), source: await formatGeneratedFile( "docs/error-contract.schema.json", JSON.stringify(analysisErrorJsonSchema), ), - check: arguments_.has("--check"), + check, + generateCommand: "npm run docs:generate", +}); + +/** RFC 4180 field: quoted only when it contains a delimiter, quote or newline. */ +const csvField = (value) => { + const text = String(value); + return /[",\r\n]/u.test(text) ? `"${text.replaceAll('"', '""')}"` : text; +}; +const columns = { + tag: "tag", + discriminant: "discriminant", + code: "code", + category: "category", + retryable_by_default: "retryableByDefault", +}; +await ensureGeneratedFile({ + path: join(root, "docs/user-visible-errors.csv"), + source: [ + Object.keys(columns).join(","), + // Provider-owned errors present themselves; their providers list their rows. + ...[...analysisErrorCatalogue(), ...hopperErrorCatalogue()].map((entry) => + Object.values(columns) + .map((field) => csvField(entry[field])) + .join(","), + ), + "", + ].join("\n"), + check, generateCommand: "npm run docs:generate", }); diff --git a/scripts/lint/rules/provider-failure-classifier-baseline.json b/scripts/lint/rules/provider-failure-classifier-baseline.json index 9d99b544b0..e176aeb415 100644 --- a/scripts/lint/rules/provider-failure-classifier-baseline.json +++ b/scripts/lint/rules/provider-failure-classifier-baseline.json @@ -35,13 +35,11 @@ "src/flutter/FlutterBuildProvider.ts": 2, "src/frida/FridaInstrumentationManager.ts": 1, "src/ghidra/GhidraClient.ts": 1, - "src/ghidra/GhidraFileArtifacts.ts": 1, "src/go/GoBinaryProvider.ts": 1, "src/il2cpp/Il2cppMetadataProvider.ts": 1, "src/inspector/V8InspectorProvider.ts": 1, "src/javascript/analysis/JavaScriptAnalysisWorker.ts": 3, "src/javascript/sourceMaps/SourceMapCommand.ts": 1, - "src/kuna/KunaCommand.ts": 1, "src/native/AppleDispatchMetadata.ts": 1, "src/native/NativeCallTarget.ts": 1, "src/native/NativeMacOSProvider.ts": 4, diff --git a/scripts/verify/architecture-guards.mjs b/scripts/verify/architecture-guards.mjs index cbbf5ce810..e6cf62c5ae 100644 --- a/scripts/verify/architecture-guards.mjs +++ b/scripts/verify/architecture-guards.mjs @@ -214,6 +214,34 @@ check( ], ); +// A signal's own abort is the abort error carrying that signal's reason; a bare +// ABORT_ERR code may come from another signal or a synthetic failure. +check( + "ABORT_ERR code comparison (use isAbortOf or isAbortWithReason from src/process/SignalAbort)", + files, + /(?:===|!==)\s*["']ABORT_ERR["']|["']ABORT_ERR["']\s*(?:===|!==)/u, + ["src/process/SignalAbort.ts"], +); + +// Hopper's error types live with the Hopper adapter. Shared layers read the +// provider-neutral facts every AnalysisError carries (ownPresentation, +// providerWide, providerRequest) and never import a provider's error types. +check( + "import of Hopper error types outside src/hopper (use the provider-neutral AnalysisError facts)", + files.filter((file) => !file.path.startsWith("src/hopper/")), + /from "\.{1,2}\/(?:[\w-]+\/)*HopperErrors\.js"/u, +); + +// An unrecognised command outcome is reported only by the shared outcome +// classifier, which attaches the outcome it examined; a provider reports it +// through the dialect's `unclassified` callback. +check( + "UnclassifiedProviderFailure construction outside classifyProviderOutcome (use the dialect's unclassified report)", + files, + /\bnew\s+UnclassifiedProviderFailure\b/u, + ["src/process/classifyProviderOutcome.ts"], +); + // "Non-null object other than an array" has one owner: src/kernel/isRecord.ts. // A local predicate with that body, under any name, is a copy. The listed files // still hold one and may only be removed from the list; a listed file that no @@ -434,6 +462,16 @@ checkCounted( ["src/domain/analysisErrorCore.ts"], ); +// Whether an abort error is a signal's own cancellation is decided by the +// signal owner; a name comparison alone accepts another signal's abort. +checkCounted( + "AbortError name comparison (use isAbortOf or isAbortWithReason from src/process/SignalAbort)", + "abort-error-name", + files, + /\.name\s*===\s*["']AbortError["']/gu, + ["src/process/SignalAbort.ts"], +); + // A refusal for a limit a parser stopped at is built from the failure's // LimitRef by parseLimitConstraint in src/domain/parseFailureAnalysisError; a // hand-built AnalysisResourceConstraintError spells the limit key and reason diff --git a/scripts/verify/baselines/resource-constraint-constructor.json b/scripts/verify/baselines/resource-constraint-constructor.json index 82afe934e2..e8c9c1e88c 100644 --- a/scripts/verify/baselines/resource-constraint-constructor.json +++ b/scripts/verify/baselines/resource-constraint-constructor.json @@ -140,7 +140,6 @@ "src/server/EvidenceMcpServerCore.ts": 2, "src/server/ProgressiveToolCatalog.ts": 1, "src/server/ToolResultDelivery.ts": 2, - "src/sqlite/SqliteDatabaseFailures.ts": 1, "src/sqlite/SqliteDatabaseProvider.ts": 1, "src/sqlite/SqliteDatabaseSnapshot.ts": 1, "src/sqlite/SqliteDatabaseWorkerExecution.ts": 3, diff --git a/src/apktool/ApktoolProvider.ts b/src/apktool/ApktoolProvider.ts index ebb83ba431..75b0b74fe1 100644 --- a/src/apktool/ApktoolProvider.ts +++ b/src/apktool/ApktoolProvider.ts @@ -22,10 +22,7 @@ import { capturedApktoolFailureOutput } from "./ApktoolCommandOutput.js"; import { providerOutcomeOf } from "../process/ProviderOutcome.js"; import { classifyProviderOutcome } from "../process/classifyProviderOutcome.js"; import { ApktoolCommandCleanup } from "./ApktoolCommandCleanup.js"; -import { - AnalysisError, - type AnalysisErrorOptions, -} from "../domain/analysisErrorBase.js"; +import { AnalysisError } from "../domain/analysisErrorBase.js"; import { analysisClientFailureForOperation } from "../providers/AnalysisClientFailure.js"; import { randomUUID } from "node:crypto"; import { mkdir } from "node:fs/promises"; @@ -65,7 +62,10 @@ import { OwnedCommandFailure, runOwnedCommand, } from "../process/OwnedCommand.js"; -import type { RuntimeExhaustionArea } from "../process/RuntimeExhaustion.js"; +import { + externalJvmExhaustionRecovery, + type ExternalJvm, +} from "../process/RuntimeExhaustion.js"; import { snapshotEnvironment } from "../process/snapshotEnvironment.js"; import { WindowsBatchCommandError } from "../process/WindowsBatchCommand.js"; import { ownedProcessPrerequisiteAvailability } from "../providers/ownedProcessAvailability.js"; @@ -86,25 +86,16 @@ import { const DECODE_MAX_OUTPUT_BYTES = 4 * 1024 * 1024; const MANIFEST_MAX_BYTES = 512 * 1024; const MAX_DECODED_ENTRIES_VISITED = 100_000; -/** - * Recovery for the JVM memory area Apktool's decoder reported exhausted. REA - * does not set the decoder JVM's limits, so each names the launcher setting - * that governs that area. - */ -const APKTOOL_EXHAUSTION_REMEDIATION: Readonly< - Record -> = { - heap: "REA does not set Apktool's Java heap. Raise the maximum heap (-Xmx) of the selected Apktool launcher's JVM, or decode a smaller APK.", - "gc-overhead": - "REA does not set Apktool's Java heap. The decoder JVM spent nearly all its time collecting garbage; raise the maximum heap (-Xmx) of the selected Apktool launcher's JVM, or decode a smaller APK.", - metaspace: - "REA does not set Apktool's class metadata limit. Raise -XX:MaxMetaspaceSize of the selected Apktool launcher's JVM; a larger heap (-Xmx) does not raise it.", - "array-size": - "The decoder requested an array larger than the JVM allows; a larger heap (-Xmx) does not lift this limit. Decode a smaller APK.", - "native-thread": - "The decoder JVM could not create a native thread. Check host thread/process limits and available native memory for the selected Apktool launcher; a larger heap (-Xmx) does not help.", - unknown: - "REA does not set the memory limits of Apktool's JVM. Review the reported out-of-memory line and the selected Apktool launcher's JVM memory settings, or decode a smaller APK.", +/** Apktool's decoder runs in the selected launcher's JVM, whose limits REA does not set. */ +const APKTOOL_JVM: ExternalJvm = { + program: "Apktool's", + role: "decoder", + raise: (option) => + `Raise the ${option} of the selected Apktool launcher's JVM`, + settings: "the selected Apktool launcher's JVM memory settings", + threads: + "Check host thread/process limits and available native memory for the selected Apktool launcher", + smaller: "decode a smaller APK", }; const STDERR_EXCERPT_BYTES = 512; @@ -215,24 +206,18 @@ const apktoolCommandFailure = ( ? processInspectionCancellationError(failure, operation) : undefined; if (inspectionCancellation !== undefined) return inspectionCancellation; - const commandFailure = (details: AnalysisErrorOptions): AnalysisError => - new ProviderAdapterError("apktool", operation, { - ...details, - ...(failure instanceof OwnedCommandFailure - ? { - userMessage: `The selected Apktool command failed while decoding ${targetPath}`, - } - : {}), - diagnostics: { - selected_command: selection.command, - target_path: targetPath, - }, - }); + const userMessage = `The selected Apktool command failed while decoding ${targetPath}`; + const diagnostics = { + selected_command: selection.command, + target_path: targetPath, + }; const outcome = providerOutcomeOf(failure); if (outcome === undefined) - return commandFailure({ + return new ProviderAdapterError("apktool", operation, { + ...(failure instanceof OwnedCommandFailure ? { userMessage } : {}), cause: failure, ...(capturedOutput === undefined ? {} : { capturedOutput }), + diagnostics, }); return classifyProviderOutcome(outcome, { providerId: APKTOOL_PROVIDER_IDENTITY.id, @@ -256,10 +241,10 @@ const apktoolCommandFailure = ( limits: null, recovery: { retryable: false, - remediationAction: `${APKTOOL_EXHAUSTION_REMEDIATION[area ?? "unknown"]} Repeating the unchanged request is expected to fail the same way.`, + remediationAction: `${externalJvmExhaustionRecovery(area, APKTOOL_JVM)} Repeating the unchanged request is expected to fail the same way.`, }, }), - dialect: (exit, details) => { + dialect: (exit, details, unclassified) => { // A physical launcher/capture failure does not establish target refusal. // Only a fully collected ordinary nonzero decode exit carries that meaning. if ( @@ -272,7 +257,7 @@ const apktoolCommandFailure = ( exit.signal !== null || exit.output?.truncated !== false ) - return commandFailure(details); + return unclassified({ userMessage, diagnostics }); return new AnalysisUnsupportedTargetError( operation, targetPath, diff --git a/src/application/HopperDownload.ts b/src/application/HopperDownload.ts index b7e5f5d280..7dbfa3b4f9 100644 --- a/src/application/HopperDownload.ts +++ b/src/application/HopperDownload.ts @@ -1,5 +1,6 @@ import { OwnerCancellation } from "../domain/analysisErrorCore.js"; import { sanitizeBrowserUrl } from "../domain/browserObservation.js"; +import { isAbortOf } from "../process/SignalAbort.js"; import { err, ok, type Result } from "../domain/result.js"; /** Why a URL was refused before any vendor response could be admitted. */ @@ -61,19 +62,6 @@ const HOPPER_DOWNLOAD_TIMEOUT_MS = 15 * 60_000; /** Small release feed and key requests must not use the package bounds. */ export const HOPPER_METADATA_TIMEOUT_MS = 10_000; -/** Attribute a raw rejection to this caller's exact cancellation. */ -export const isHopperRequestCancellation = ( - cause: unknown, - signal: AbortSignal | undefined, -): boolean => - signal?.aborted === true && - (cause === signal.reason || - (cause instanceof Error && - cause.name === "AbortError" && - "code" in cause && - cause.code === "ABORT_ERR" && - cause.cause === signal.reason)); - /** * Bound observed response bytes before retaining them, including chunked bodies. * Expected transport outcomes are returned; caller cancellation still rejects @@ -149,14 +137,11 @@ export const downloadHopperPackage = async ( progressed, }); } catch (observed: unknown) { - const cause = isHopperRequestCancellation(observed, transport.signal) + const cause = isAbortOf(observed, transport.signal) ? selectedSignal.reason : observed; - if (isHopperRequestCancellation(cause, options.signal)) throw cause; - if ( - expired !== undefined && - isHopperRequestCancellation(cause, deadline.signal) - ) + if (isAbortOf(cause, options.signal)) throw cause; + if (expired !== undefined && isAbortOf(cause, deadline.signal)) return err({ url: reported, kind: "timeout", ...expired }); // Fetch reports network errors (DNS, TLS, reset, truncated body) as TypeError. if (cause instanceof TypeError) diff --git a/src/application/JsonFiles.ts b/src/application/JsonFiles.ts index 2950d9f659..1e7fdfea49 100644 --- a/src/application/JsonFiles.ts +++ b/src/application/JsonFiles.ts @@ -1,11 +1,11 @@ import { EvidenceFileError } from "../domain/evidenceErrors.js"; +import { isAbortOf } from "../process/SignalAbort.js"; import { AnalysisCancelledError, type AnalysisInputError, AnalysisResourceConstraintError, cancelledBy, carriedReason, - type AbortedSignal, } from "../domain/analysisErrorCore.js"; import { AnalysisError } from "../domain/analysisErrorBase.js"; import { childFailureDiagnostics } from "../domain/analysisErrorProjection.js"; @@ -216,8 +216,7 @@ const jsonFileReadFailure = ( cause: cause.physicalCause, path, }); - if (isJsonReadCancellation(cause, signal)) - return cancelledBy(operation, signal); + if (isAbortOf(cause, signal)) return cancelledBy(operation, signal); return new EvidenceFileError( "read", cause instanceof NonRegularFileReadError @@ -272,18 +271,3 @@ const jsonFileCleanupError = ( if (!primary.cleanupIncomplete) rememberJsonReadCleanup(combined, failure); return combined; }; - -const isJsonReadCancellation = ( - cause: unknown, - signal?: AbortSignal, -): signal is AbortedSignal => { - if (signal?.aborted !== true) return false; - if (cause === signal.reason) return true; - return ( - cause instanceof Error && - cause.name === "AbortError" && - "code" in cause && - cause.code === "ABORT_ERR" && - cause.cause === signal.reason - ); -}; diff --git a/src/application/JsonInputFile.ts b/src/application/JsonInputFile.ts index bf2f8fb9b5..2262ef398e 100644 --- a/src/application/JsonInputFile.ts +++ b/src/application/JsonInputFile.ts @@ -1,5 +1,6 @@ import { strictUtf8Decoder } from "../domain/strictUtf8.js"; import { constants } from "node:buffer"; +import { isAbortWithReason } from "../process/SignalAbort.js"; import { createHash } from "node:crypto"; import type { Stats } from "node:fs"; import type { FileHandle } from "node:fs/promises"; @@ -138,14 +139,7 @@ const isOwnedJsonPipelineCancellation = ( try { while (pending.length > 0) { const current = pending.pop(); - if ( - current === cancellation || - (current instanceof Error && - current.name === "AbortError" && - "code" in current && - current.code === "ABORT_ERR" && - current.cause === cancellation) - ) { + if (isAbortWithReason(current, cancellation)) { owned = true; continue; } diff --git a/src/application/LinuxHopper.ts b/src/application/LinuxHopper.ts index c0b50b1a33..690e302184 100644 --- a/src/application/LinuxHopper.ts +++ b/src/application/LinuxHopper.ts @@ -11,10 +11,10 @@ import { execFileOutput } from "../process/ExecFileOutput.js"; import { ArtifactReaderFailure } from "../resources/index.js"; import { downloadHopperPackage, - isHopperRequestCancellation, type HopperDownload, type HopperRequestFailure, } from "./HopperDownload.js"; +import { isAbortOf } from "../process/SignalAbort.js"; import { inspectLinuxHopperPythonRuntime, linuxHopperPythonUnavailable, @@ -491,7 +491,7 @@ export const installLinuxHopper = async ( return { status: "installed", launcherPath }; })(); } catch (cause: unknown) { - const cancelled = isHopperRequestCancellation(cause, options.signal); + const cancelled = isAbortOf(cause, options.signal); result = { status: "failed", reason: cancelled ? "cancelled" : stage, diff --git a/src/application/LinuxHopperPublisher.ts b/src/application/LinuxHopperPublisher.ts index ce383c78b6..5d60483e4e 100644 --- a/src/application/LinuxHopperPublisher.ts +++ b/src/application/LinuxHopperPublisher.ts @@ -31,14 +31,17 @@ import { } from "../process/ExecFileOutput.js"; import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js"; import { waitForAbortableDelay } from "../process/ProviderDeadline.js"; -import { acquireHopperReleaseCacheLease } from "../process/HopperLease.js"; +import { + acquireHopperReleaseCacheLease, + hopperLeaseMessage, +} from "../process/HopperLease.js"; import type { OwnedLease } from "../process/OwnedLease.js"; import { downloadHopperPackage, - isHopperRequestCancellation, HOPPER_DOWNLOAD_BYTES, HOPPER_METADATA_TIMEOUT_MS, } from "./HopperDownload.js"; +import { isAbortOf } from "../process/SignalAbort.js"; import { HOPPER_LINUX_PRIMARY_FINGERPRINT, HOPPER_PUBLIC_KEY_URL, @@ -432,6 +435,12 @@ export class LinuxHopperPublisher { launcherSha256: digest, runId, resources, + failure: (failure, cause) => + new HopperReleaseError( + "verification_unavailable", + hopperLeaseMessage(failure), + { cause }, + ), }); if (acquired.acquired) return acquired.lease; const remaining = deadline - performance.now(); @@ -1086,7 +1095,7 @@ const releaseFailure = ( signal: AbortSignal | undefined, fallback: HopperReleaseError["reason"], ): HopperReleaseError => { - if (isHopperRequestCancellation(cause, signal)) + if (isAbortOf(cause, signal)) return new HopperReleaseError( "cancelled", "Hopper publisher verification was cancelled.", diff --git a/src/application/MacHopper.ts b/src/application/MacHopper.ts index d64080381c..7b8ca5683a 100644 --- a/src/application/MacHopper.ts +++ b/src/application/MacHopper.ts @@ -22,11 +22,11 @@ import { macDeveloperIdRequirement } from "../process/MacCodeSignature.js"; import { macHopperUserApplicationPath } from "../hopperPaths/MacHopperPaths.js"; import { downloadHopperPackage, - isHopperRequestCancellation, HOPPER_METADATA_TIMEOUT_MS, type HopperDownload, type HopperRequestFailure, } from "./HopperDownload.js"; +import { isAbortOf } from "../process/SignalAbort.js"; import { HOPPER_RELEASES_URL, HOPPER_DOWNLOAD_PREFIX, @@ -311,9 +311,7 @@ export const installMacHopper = async ( } catch (cause: unknown) { result = { status: "failed", - reason: isHopperRequestCancellation(cause, options.signal) - ? "cancelled" - : installStage, + reason: isAbortOf(cause, options.signal) ? "cancelled" : installStage, diagnostic: failureMessage(cause), }; } diff --git a/src/application/binary/SessionRuntimeAvailability.ts b/src/application/binary/SessionRuntimeAvailability.ts index 880e2fd25f..2649eb8a73 100644 --- a/src/application/binary/SessionRuntimeAvailability.ts +++ b/src/application/binary/SessionRuntimeAvailability.ts @@ -3,13 +3,6 @@ import { AnalysisCapabilityUnavailableError } from "../../domain/analysisErrorCo import type { Result } from "../../domain/result.js"; import type { CapabilityDescriptor } from "../../ports/AnalysisProvider.js"; -/** Failures of the provider adapter or process rather than of one request. */ -const PROVIDER_WIDE_FAILURES: ReadonlySet = new Set([ - "ProviderAdapterError", - "HopperProcessError", - "HopperStartError", -]); - interface Failure { readonly dispatch: number; readonly reason: string; @@ -34,7 +27,7 @@ type RoutedOperation = Pick< const runtimeFailureReason = (failure: AnalysisError): string | undefined => { if (failure._tag === "AnalysisCapabilityUnavailableError") return failure.userMessage ?? failure.message; - return PROVIDER_WIDE_FAILURES.has(failure._tag) + return failure.providerWide ? `${failure._tag}: ${failure.message}` : undefined; }; @@ -126,7 +119,7 @@ export class SessionRuntimeAvailability { result.error, ); } - if (PROVIDER_WIDE_FAILURES.has(result.error._tag)) + if (result.error.providerWide) provider.failure = newer(provider.failure, { dispatch, reason, diff --git a/src/application/reverse/ReverseEngineeringCommandPort.ts b/src/application/reverse/ReverseEngineeringCommandPort.ts index 917bf978b0..ccd06c7bad 100644 --- a/src/application/reverse/ReverseEngineeringCommandPort.ts +++ b/src/application/reverse/ReverseEngineeringCommandPort.ts @@ -1,3 +1,4 @@ +import type { CommandRejection } from "../../domain/commandObservation.js"; import type { EvidenceProvider } from "../../domain/evidence.js"; import type { Result } from "../../domain/result.js"; import type { @@ -24,10 +25,10 @@ export interface ReverseEngineeringProviderCommand { /** What the provider cannot attest about the arguments it built. */ readonly limitations?: readonly string[]; /** - * Explain a provider refusal of the command that a completed process - * reported only in its diagnostics, or return undefined. + * A provider refusal of the command that a completed process reported only + * in its diagnostics, with the limitation that explains it, or undefined. */ - readonly rejection?: (stderr: string) => string | undefined; + readonly rejection?: (stderr: string) => CommandRejection | undefined; readonly environmentOverrides?: Readonly; } diff --git a/src/application/reverse/ReverseEngineeringService.ts b/src/application/reverse/ReverseEngineeringService.ts index da7b04a395..a33b3128d9 100644 --- a/src/application/reverse/ReverseEngineeringService.ts +++ b/src/application/reverse/ReverseEngineeringService.ts @@ -1163,6 +1163,7 @@ export class ReverseEngineeringService { completion_status: completionStatus, artifact_sha256_after: absolutePath === undefined ? null : digestAfter, artifact_changed: absolutePath === undefined ? null : artifactChanged, + ...(rejection === undefined ? {} : { refusal: rejection.refusal }), }; const limitations = [ // A pathless command reports no artifact; its provider says what the @@ -1174,7 +1175,7 @@ export class ReverseEngineeringService { ]), ...(profile.limitations ?? []), "A non-zero process exit is preserved as an observed command result.", - ...(rejection === undefined ? [] : [rejection]), + ...(rejection === undefined ? [] : [rejection.limitation]), ...(stdoutInvalidUtf8 || stderrInvalidUtf8 ? [ `Captured ${[ @@ -1568,9 +1569,8 @@ const PHYSICAL_FAILURE_CODES = new Set([ /** * A late abort does not replace a recognized physical failure. Other rejections - * observed while the caller signal is aborted remain cancellation. A bare - * `ABORT_ERR` is not cancellation until the command boundary, which already - * used that code for an aborted provider process. + * observed while the caller signal is aborted remain cancellation; a bare + * `ABORT_ERR` without the caller's abort is not. */ const preflightCancelled = ( signal: AbortSignal | undefined, @@ -1593,7 +1593,7 @@ const commandCancelled = ( cause.cause instanceof OwnedCommandFailure ) return cause.cause.reason === "cancelled"; - return code === "ABORT_ERR" || preflightCancelled(signal, cause, code); + return preflightCancelled(signal, cause, code); }; const callerCancellationCause = ( diff --git a/src/browser/WebBundleAnalysisWorker.test.ts b/src/browser/WebBundleAnalysisWorker.test.ts index 58d6f52e57..9fb2101d45 100644 --- a/src/browser/WebBundleAnalysisWorker.test.ts +++ b/src/browser/WebBundleAnalysisWorker.test.ts @@ -119,7 +119,8 @@ type TestMode = | "work-refusal" | "final-frame-held-pipe" | "zero-exit-held-pipe" - | "heap-exit"; + | "heap-exit" + | "heap-exit-after-noise"; }; const protocolWorkerProgram = ( @@ -138,7 +139,8 @@ const protocolWorkerProgram = ( | "work-refusal" | "final-frame-held-pipe" | "zero-exit-held-pipe" - | "heap-exit", + | "heap-exit" + | "heap-exit-after-noise", ): string => ` import { createInterface } from "node:readline"; import { spawn } from "node:child_process"; @@ -149,8 +151,9 @@ const protocolWorkerProgram = ( input.once("line", (line) => { const request = JSON.parse(line); ${ - failure === "heap-exit" - ? `process.stderr.write("allocation failed\\n", () => process.exit(7));` + failure === "heap-exit" || failure === "heap-exit-after-noise" + ? // The 256 KiB retention budget keeps only the head of stderr. + `process.stderr.write(${failure === "heap-exit" ? '""' : '"x".repeat(300 * 1024) + "\\n"'} + "FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory\\n", () => process.exit(7));` : failure === "zero-exit-held-pipe" ? `const program = "setTimeout(() => process.exit(0), 300);"; spawn(process.execPath, ["-e", program], { stdio: ["ignore", "inherit", "inherit"] }); @@ -975,45 +978,57 @@ it("consumes a final frame before an inherited descendant pipe closes", async () } }); -it("projects a heap-marker exit with the runtime's exhausted resource", async () => { - const heapMb = 256; - const worker = new WebBundleAnalysisWorker( - heapMb, - launcherFor({ kind: "protocol", failure: "heap-exit" }), - ); - try { - const error = failureOf( - await worker.analyze(makeScript("report heap exit"), 15_000), - ); - expect(error).toBeInstanceOf(AnalysisResourceConstraintError); - const exhaustion = webBundleMemoryExhaustion({ - runtime: javaScriptRuntime(process.versions).id, +it.each(["heap-exit", "heap-exit-after-noise"] as const)( + "projects a heap-marker exit with the runtime's exhausted resource (%s)", + async (failure) => { + const heapMb = 256; + const worker = new WebBundleAnalysisWorker( heapMb, - memoryLimitReached: false, - processMemoryLimitBytes: javaScriptWorkerMemoryLimitBytes(heapMb), - }); - expect(error.message).toContain(webBundleHeapExhaustedReason(exhaustion)); - expect(error).toMatchObject({ - remediationAction: webBundleHeapExhaustedRemediation(exhaustion), - ...(exhaustion.kind === "bun-allocation" - ? {} - : { - limit: { - control_kind: "parameter", - parameter: "max_heap_mb", - effective_value: heapMb, - }, - }), - reportedLimits: { - max_heap_mb: heapMb, - worker_process_memory_limit_bytes: - javaScriptWorkerMemoryLimitBytes(heapMb), - }, - }); - } finally { - await worker.close(); - } -}); + launcherFor({ kind: "protocol", failure }), + ); + try { + const error = failureOf( + await worker.analyze(makeScript("report heap exit"), 15_000), + ); + expect(error).toBeInstanceOf(AnalysisResourceConstraintError); + const exhaustion = webBundleMemoryExhaustion({ + runtime: javaScriptRuntime(process.versions).id, + heapMb, + memoryLimitReached: false, + processMemoryLimitBytes: javaScriptWorkerMemoryLimitBytes(heapMb), + }); + expect(error.message).toContain(webBundleHeapExhaustedReason(exhaustion)); + expect(error).toMatchObject({ + remediationAction: webBundleHeapExhaustedRemediation(exhaustion), + ...(exhaustion.kind === "bun-allocation" + ? {} + : { + limit: { + control_kind: "parameter", + parameter: "max_heap_mb", + effective_value: heapMb, + }, + }), + reportedLimits: { + max_heap_mb: heapMb, + worker_process_memory_limit_bytes: + javaScriptWorkerMemoryLimitBytes(heapMb), + }, + // The runtime's own report survives even when it lies past the + // retained stderr. + diagnostics: { + runtime_exhaustion_report: { + runtime: "v8", + stream: "stderr", + line_complete: true, + }, + }, + }); + } finally { + await worker.close(); + } + }, +); it("does not classify heap-marker stderr from a healthy worker as exhaustion", async () => { const worker = new WebBundleAnalysisWorker( diff --git a/src/browser/WebBundleAnalysisWorker.ts b/src/browser/WebBundleAnalysisWorker.ts index 6d9e596963..353c20c893 100644 --- a/src/browser/WebBundleAnalysisWorker.ts +++ b/src/browser/WebBundleAnalysisWorker.ts @@ -1,3 +1,7 @@ +import { + runtimeExhaustionReport, + type RuntimeExhaustion, +} from "../process/RuntimeExhaustion.js"; import { Budget } from "../domain/budget.js"; import { fixedAllowanceOptions } from "../domain/fixedAllowanceRemediation.js"; import { invariantViolation } from "../domain/internalInvariant.js"; @@ -164,6 +168,8 @@ type WebBundleObservedFailure = readonly signal: NodeJS.Signals | null; readonly memoryLimitReached: boolean; readonly heapExhaustion: boolean; + /** The runtime's own report, kept once the supervisor observed it. */ + readonly exhaustion?: RuntimeExhaustion; }; type WebBundleActiveJob = { @@ -259,13 +265,15 @@ export class WebBundleAnalysisWorker { supervisorOptions: { captureStdout: false, maxDiagnosticBytes: 256 * 1024, + // V8's heap report is observed as output streams, so a retention + // budget or a stack trace that overflowed it cannot hide it. + runtime: "v8", onDiagnostic: (event) => { if (this.#activeDeadline?.interruption !== undefined) return; if ( event.type === "exit" && (event.code !== 0 || event.signal !== null) ) { - const stderr = event.snapshot.stderr.text; const memoryLimitReached = event.snapshot.memoryLimitReached === true; this.#latchFailure({ @@ -275,9 +283,10 @@ export class WebBundleAnalysisWorker { memoryLimitReached, heapExhaustion: memoryLimitReached || - /heap out of memory|heap limit|allocation failed/iu.test( - stderr, - ), + event.snapshot.runtimeExhaustion !== undefined, + ...(event.snapshot.runtimeExhaustion === undefined + ? {} + : { exhaustion: event.snapshot.runtimeExhaustion }), }); } else if (event.type === "output-close") { if ( @@ -290,19 +299,16 @@ export class WebBundleAnalysisWorker { } else if (event.type === "output") { const failure = this.#observedFailure; if (failure?.kind !== "exit") return; - const memoryLimitReached = - this.#runtime.supervisor?.snapshot().memoryLimitReached === true; - const heapMarker = - event.stream === "stderr" && - /heap out of memory|heap limit|allocation failed/iu.test( - this.#runtime.supervisor?.snapshot().stderr.text ?? "", - ); - if (!memoryLimitReached && !heapMarker) return; + const snapshot = this.#runtime.supervisor?.snapshot(); + const memoryLimitReached = snapshot?.memoryLimitReached === true; + const reported = snapshot?.runtimeExhaustion; + if (!memoryLimitReached && reported === undefined) return; this.#observedFailure = { ...failure, heapExhaustion: true, memoryLimitReached: failure.memoryLimitReached || memoryLimitReached, + ...(reported === undefined ? {} : { exhaustion: reported }), }; } }, @@ -902,6 +908,15 @@ export class WebBundleAnalysisWorker { { capturedOutput, limit: webBundleHeapLimit(exhaustion), + ...(failure.exhaustion === undefined + ? {} + : { + diagnostics: { + runtime_exhaustion_report: runtimeExhaustionReport( + failure.exhaustion, + ), + }, + }), remediationAction: webBundleHeapExhaustedRemediation(exhaustion), }, ); diff --git a/src/browser/assets/WebArtifactReads.ts b/src/browser/assets/WebArtifactReads.ts index 2c727f88c8..5c53e390df 100644 --- a/src/browser/assets/WebArtifactReads.ts +++ b/src/browser/assets/WebArtifactReads.ts @@ -1,5 +1,6 @@ import { decodeStrictUtf8 } from "../../domain/strictUtf8.js"; import type { WebArtifactAcquisition as Acquisition } from "../../domain/webArtifactAcquisition.js"; +import { isAbortOf } from "../../process/SignalAbort.js"; import { z } from "zod"; import { ArtifactReaderFailure, @@ -182,15 +183,7 @@ const webArtifactPrimaryError = ( context.operation, carriedReason(artifactFileCancellationCause(cause)), ); - if ( - origin === "owned-or-classified" && - signal?.aborted === true && - (cause === signal.reason || - (cause instanceof Error && - cause.name === "AbortError" && - "code" in cause && - cause.code === "ABORT_ERR")) - ) + if (origin === "owned-or-classified" && isAbortOf(cause, signal)) return cancelledBy(context.operation, signal); const selection = context.callerSelected ? selectedFileError({ cause, origin }, context) diff --git a/src/browser/history/CaptureFailures.ts b/src/browser/history/CaptureFailures.ts index 027797f247..a617c34333 100644 --- a/src/browser/history/CaptureFailures.ts +++ b/src/browser/history/CaptureFailures.ts @@ -1,4 +1,5 @@ import { javaScriptWorkerMemoryLimitBytes } from "../../process/JavaScriptWorkerMemoryLimit.js"; +import { isAbortOf } from "../../process/SignalAbort.js"; import { captureBudgets } from "./CaptureBudgets.js"; import { analysisSettingLimit } from "../../domain/analysisSettingDefinitions.js"; import type { ExecutionOptions } from "../../ports/AnalysisProvider.js"; @@ -301,12 +302,7 @@ export const historicalCaptureFailure = ( // Bare syscall rejections remain physical even when they equal the abort reason. phase === "decoder" && origin === "owned-or-classified" && - options?.signal?.aborted === true && - (cause === options.signal.reason || - (cause instanceof Error && - cause.name === "AbortError" && - "code" in cause && - cause.code === "ABORT_ERR")) + isAbortOf(cause, options?.signal) ) return cancelledBy(OPERATION, options.signal); return new ProviderAdapterError(input.format, OPERATION, { diff --git a/src/browser/history/HistoricalCaptureReply.ts b/src/browser/history/HistoricalCaptureReply.ts index 411d0ba431..346c0de8a0 100644 --- a/src/browser/history/HistoricalCaptureReply.ts +++ b/src/browser/history/HistoricalCaptureReply.ts @@ -1,4 +1,5 @@ import { captureBudgets } from "./CaptureBudgets.js"; +import { isAbortOf } from "../../process/SignalAbort.js"; import { z } from "zod"; import type { JsonValue } from "../../domain/jsonValue.js"; import { CaptureRedaction, capturePointer } from "./CaptureRedaction.js"; @@ -100,15 +101,7 @@ export const readHistoricalCaptureReply = async ( }; } catch (cause: unknown) { if (cause instanceof ArtifactReaderFailure) throw cause; - if ( - signal?.aborted === true && - (cause === signal.reason || - (cause instanceof Error && - cause.name === "AbortError" && - "code" in cause && - cause.code === "ABORT_ERR")) - ) - throw cause; + if (isAbortOf(cause, signal)) throw cause; const error = new AnalysisOutputError( "inspect_web_network_capture", `Owned capture decoder reply failed for ${capturePath}: ${replyFailureReason(cause)}`, diff --git a/src/cli/cliJsonInput.ts b/src/cli/cliJsonInput.ts index 6fdc4c3211..db817dc65b 100644 --- a/src/cli/cliJsonInput.ts +++ b/src/cli/cliJsonInput.ts @@ -1,4 +1,5 @@ import { addAbortListener } from "node:events"; +import { isAbortOf } from "../process/SignalAbort.js"; import type { Readable } from "node:stream"; import { getHeapStatistics } from "node:v8"; @@ -131,8 +132,7 @@ export const parseCliJsonInput = async ( return cancelled(cause.reason); if (cause instanceof JsonInputPhysicalReadFailure) return jsonFileReadError(value, operation, cause.physicalCause); - if (signal?.aborted && isJsonInputCancellation(cause, signal)) - return cancelled(signal.reason); + if (isAbortOf(cause, signal)) return cancelled(signal.reason); if (accessDeniedSystemCode(cause) !== undefined) return jsonFileReadError(value, operation, cause); if ( @@ -223,7 +223,7 @@ const readCliJsonStdin = async ( } catch (cause: unknown) { if ( cause instanceof JsonInputCancellationFailure || - (signal?.aborted && isJsonInputCancellation(cause, signal)) + isAbortOf(cause, signal) ) throw cause; if (cause instanceof AnalysisResourceConstraintError) return err(cause); @@ -270,17 +270,6 @@ const readCliJsonStdin = async ( } }; -const isJsonInputCancellation = ( - cause: unknown, - signal: AbortSignal, -): boolean => - cause === signal.reason || - (cause instanceof Error && - cause.name === "AbortError" && - "code" in cause && - cause.code === "ABORT_ERR" && - cause.cause === signal.reason); - const accessDeniedSystemCode = ( cause: unknown, ): "EACCES" | "EPERM" | undefined => { diff --git a/src/domain/analysisErrorBase.ts b/src/domain/analysisErrorBase.ts index f7e10ddb11..d41d93a098 100644 --- a/src/domain/analysisErrorBase.ts +++ b/src/domain/analysisErrorBase.ts @@ -31,20 +31,42 @@ const ANALYSIS_ERROR_TAGS = [ "EvidenceIntegrityError", "EvidenceFileError", "UnknownRegistryError", - "HopperTimeoutError", - "HopperCancelledError", - "HopperProtocolError", - "HopperRemoteError", - "HopperProcessError", - "HopperStartError", "ConfigurationError", "NoBinaryOpenError", "BinaryTargetError", ] as const; -/** Stable tag for an expected analysis failure. */ +/** Stable tag for an expected analysis failure the domain defines. */ export type AnalysisErrorTag = (typeof ANALYSIS_ERROR_TAGS)[number]; +const DOMAIN_ERROR_TAGS: ReadonlySet = new Set(ANALYSIS_ERROR_TAGS); + +/** Whether a tag names an error the domain defines and presents. */ +export const isAnalysisErrorTag = (tag: string): tag is AnalysisErrorTag => + DOMAIN_ERROR_TAGS.has(tag); + +/** The error's domain tag; undefined for a provider-owned failure. */ +export const domainErrorTag = (error: { + readonly _tag: string; +}): AnalysisErrorTag | undefined => + isAnalysisErrorTag(error._tag) ? error._tag : undefined; + +declare const providerErrorTagBrand: unique symbol; + +/** + * Tag of a failure a provider module defines and presents itself. It is + * outside the domain tag set; the error's `ownPresentation()` supplies what + * the domain tables would. + */ +export type ProviderErrorTag = string & { + readonly [providerErrorTagBrand]: true; +}; + +/** Brand the tag of a `ProviderOwnedAnalysisError` subclass. */ +export const providerErrorTag = ( + tag: Tag, +): Tag & ProviderErrorTag => tag as Tag & ProviderErrorTag; + /** Retained command output associated with a typed failure; truncation stays explicit. */ export interface AnalysisCapturedOutput { readonly stdout: string; @@ -187,6 +209,39 @@ export interface SourcePublicationRecovery { readonly completed: SourcePublicationCompletion; } +/** + * Presentation an error's own module supplies. The shared presenter reads it + * before its tables, so it never needs the error's type: a provider error + * says what it means for callers where it is defined. + */ +export interface AnalysisErrorOwnPresentation { + /** The stable code before any cleanup composition. */ + readonly code: AnalysisErrorProjection["code"]; + readonly category: AnalysisErrorProjection["category"]; + /** The outcome every caller receives; absent keeps the code's standard text. */ + readonly message?: string; + /** Guidance only a caller that keeps REA's runtime and session receives. */ + readonly continuing?: AnalysisContinuingCallerGuidance; + /** The next step; absent keeps the shared fallback. */ + readonly remediation?: string; + /** False when the failure cannot clear on retry whatever its code. */ + readonly retryable?: false; + readonly details?: Readonly>; +} + +/** + * The provider request a provider-owned failure answered. A shared workflow + * that attributes the failure to its caller's operation copies `facts` under + * `provider_request` and rebuilds the failure with `reattribute`. + */ +export interface ProviderRequestFailure { + readonly facts: Readonly>; + readonly reattribute: ( + operation: string, + options: AnalysisErrorOptions, + ) => AnalysisError; +} + /** Base class for expected analysis, provider, and session failures. */ export abstract class AnalysisError extends Error { limit: Readonly | undefined; @@ -265,7 +320,23 @@ export abstract class AnalysisError extends Error { this.#ownedCleanupResources = [...(options?.cleanup?.resources ?? [])]; this.partialObservation = options?.partialObservation; } - abstract readonly _tag: AnalysisErrorTag; + abstract readonly _tag: AnalysisErrorTag | ProviderErrorTag; + /** What this error's own module says it means; undefined uses the shared tables. */ + ownPresentation(): AnalysisErrorOwnPresentation | undefined { + return undefined; + } + /** + * Whether the provider adapter or its process failed, rather than one + * request. Session availability treats every operation of that provider as + * affected until a later success. + */ + get providerWide(): boolean { + return false; + } + /** The provider request this failure answered; undefined when none. */ + providerRequest(): ProviderRequestFailure | undefined { + return undefined; + } readonly userMessage: string | undefined = undefined; readonly userCategory: "cancelled" | undefined = undefined; readonly executionFailure: string | undefined = undefined; @@ -513,6 +584,15 @@ export abstract class AnalysisError extends Error { } } +/** + * A failure its provider module defines: its tag is outside the domain tag + * set, so it must say what it means through `ownPresentation()`. + */ +export abstract class ProviderOwnedAnalysisError extends AnalysisError { + abstract override readonly _tag: ProviderErrorTag; + abstract override ownPresentation(): AnalysisErrorOwnPresentation; +} + /** Confirmed cleanup reveals the typed primary; unresolved ownership stays visible. */ export const resolvedAnalysisError = (error: AnalysisError): AnalysisError => { while (!error.cleanupIncomplete && error.cleanupPrimary !== undefined) @@ -546,6 +626,7 @@ import type { import type { FileOffsetPartialObservation } from "./native/fileOffsetPartialObservation.js"; import type { NativeCallPartialObservation } from "./native/nativeCallPartialObservation.js"; import type { HopperCallerReconciliationPartial } from "./native/hopperCallerReconciliation.js"; +import type { AnalysisErrorProjection } from "./analysisErrorProjection.js"; import type { ElectronActiveObservationResult, ElectronActivePartialObservation, diff --git a/src/domain/analysisErrorClassification.test.ts b/src/domain/analysisErrorClassification.test.ts new file mode 100644 index 0000000000..32a2c95a76 --- /dev/null +++ b/src/domain/analysisErrorClassification.test.ts @@ -0,0 +1,81 @@ +import { expect, it } from "vitest"; +import { isAnalysisErrorTag } from "./analysisErrorBase.js"; +import { analysisErrorCatalogue } from "./analysisErrorClassification.js"; +import { projectAnalysisError } from "./analysisErrorProjection.js"; +import { ArtifactOperationError } from "./artifactOperationError.js"; +import { BinaryTargetError } from "./configurationErrors.js"; +import { EvidenceFileError } from "./evidenceErrors.js"; + +const catalogue = analysisErrorCatalogue(); +const entry = (tag: string, discriminant: string) => + catalogue.find((row) => row.tag === tag && row.discriminant === discriminant); + +it("lists each domain error case once", () => { + const keys = catalogue.map((row) => `${row.tag}|${row.discriminant}`); + expect(new Set(keys).size).toBe(keys.length); + for (const row of catalogue) expect(isAnalysisErrorTag(row.tag)).toBe(true); +}); + +it.each([ + "not-file", + "exists", + "wrong-kind", + "invalid-json", + "missing", + "path-limit", + "storage-limit", + "symlink-traversal", + "io", +] as const)( + "reports an evidence file %s failure as its catalogue row", + (reason) => { + const projected = projectAnalysisError( + new EvidenceFileError("read", reason), + ); + expect(entry("EvidenceFileError", `reason=${reason}`)).toMatchObject({ + code: projected.code, + category: projected.category, + retryableByDefault: projected.retryable, + }); + }, +); + +it.each([ + "cancelled", + "format", + "integrity", + "path", + "unavailable", + "io", +] as const)( + "reports an artifact operation %s failure as its catalogue row", + (reason) => { + const projected = projectAnalysisError( + new ArtifactOperationError("inspect_artifact", reason), + ); + expect(entry("ArtifactOperationError", `reason=${reason}`)).toMatchObject({ + code: projected.code, + category: projected.category, + }); + }, +); + +it("keeps a refused target's constraint category beside its permission code", () => { + const denied = Object.assign(new Error("denied"), { code: "EACCES" }); + const projected = projectAnalysisError( + new BinaryTargetError("/target", "refused", { + constraint: "file_format_rejected", + cause: denied, + }), + ); + expect(projected).toMatchObject({ + code: "access_denied", + category: "unsupported_target", + }); + expect( + entry( + "BinaryTargetError", + "constraint=file_format_rejected; read permission denied", + ), + ).toMatchObject({ code: projected.code, category: projected.category }); +}); diff --git a/src/domain/analysisErrorClassification.ts b/src/domain/analysisErrorClassification.ts new file mode 100644 index 0000000000..8b99f1f0a9 --- /dev/null +++ b/src/domain/analysisErrorClassification.ts @@ -0,0 +1,391 @@ +import { AnalysisCapabilityUnavailableError } from "./analysisErrorCore.js"; +import { + domainErrorTag, + type AnalysisError, + type AnalysisErrorTag, + type ProviderErrorTag, +} from "./analysisErrorBase.js"; +import type { AnalysisErrorProjection } from "./analysisErrorProjection.js"; +import { ArtifactOperationError } from "./artifactOperationError.js"; +import { BrowserObservationError } from "./browserObservationError.js"; +import type { BrowserObservationFailureReason } from "./browserObservationErrors.js"; +import { + BinaryTargetError, + type BinaryTargetErrorOptions, +} from "./configurationErrors.js"; +import { EvidenceFileError } from "./evidenceErrors.js"; +import { + ProviderSelectionError, + type ProviderSelectionFailureReason, +} from "./providerSelectionError.js"; +import { UnknownRegistryError } from "./unknownRegistryError.js"; + +type ErrorCode = AnalysisErrorProjection["code"]; +type ErrorCategory = AnalysisErrorProjection["category"]; + +/** The caller-facing code and category of one domain error case. */ +export interface AnalysisErrorClassification { + readonly code: ErrorCode; + readonly category: ErrorCategory; +} + +/** Codes whose failures may succeed when the unchanged request is repeated. */ +export const RETRYABLE_CODES: ReadonlySet = new Set([ + "artifact_changed", + "provider_timeout", + "cancelled", + "revision_conflict", + "provider_unavailable", +]); + +/** Domain tags whose classification depends on the error's own facts. */ +type SpecializedErrorTag = + | "ArtifactOperationError" + | "BinaryTargetError" + | "BrowserObservationError" + | "EvidenceFileError" + | "ProcessCaptureError" + | "ProviderSelectionError" + | "UnknownRegistryError"; + +const classified = ( + code: ErrorCode, + category: ErrorCategory, +): AnalysisErrorClassification => ({ code, category }); + +const STATIC_ERROR_CLASSIFICATIONS = { + AnalysisProtocolError: classified("unreadable_output", "execution_failure"), + AnalysisOutputError: classified("unreadable_output", "execution_failure"), + AnalysisInputError: classified("invalid_request", "invalid_input"), + AnalysisAccessDeniedError: classified("access_denied", "unavailable"), + AnalysisArtifactChangedError: classified( + "artifact_changed", + "integrity_mismatch", + ), + AnalysisCapabilityUnavailableError: classified( + "capability_unavailable", + "unsupported_provider", + ), + AnalysisUnsupportedTargetError: classified( + "unsupported_target", + "unsupported_target", + ), + AnalysisCancelledError: classified("cancelled", "cancelled"), + AnalysisTimeoutError: classified("provider_timeout", "timeout"), + AnalysisResourceConstraintError: classified( + "resource_constraint", + "resource_constraint", + ), + ConfigurationError: classified("configuration_invalid", "invalid_input"), + NoBinaryOpenError: classified("target_unavailable", "unavailable"), + EvidenceIntegrityError: classified( + "evidence_integrity_mismatch", + "integrity_mismatch", + ), + ProviderAdapterError: classified("execution_failure", "execution_failure"), +} as const satisfies Readonly< + Record< + Exclude, + AnalysisErrorClassification + > +>; + +/** A capability the caller may wait for is unavailable, not unsupported. */ +const RETRYABLE_CAPABILITY_UNAVAILABLE = classified( + "capability_unavailable", + "unavailable", +); + +const ARTIFACT_OPERATION_CLASSIFICATIONS = { + cancelled: classified("cancelled", "cancelled"), + format: classified("artifact_operation_failed", "execution_failure"), + integrity: classified("artifact_operation_failed", "integrity_mismatch"), + limit: classified("truncated", "truncated"), + path: classified("artifact_operation_failed", "execution_failure"), + unavailable: classified("artifact_operation_failed", "unavailable"), + io: classified("artifact_operation_failed", "execution_failure"), +} as const satisfies Readonly< + Record +>; + +/** An integrity failure that names the artifact's expected and observed identity. */ +const ARTIFACT_IDENTITY_MISMATCH = classified( + "artifact_integrity_mismatch", + "integrity_mismatch", +); + +const EVIDENCE_FILE_CLASSIFICATIONS = { + // A missing, non-file or already-existing path is the caller's selection. + "not-file": classified("invalid_request", "invalid_input"), + exists: classified("invalid_request", "invalid_input"), + "wrong-kind": classified("invalid_request", "invalid_input"), + missing: classified("invalid_request", "invalid_input"), + "symlink-traversal": classified("invalid_request", "invalid_input"), + "invalid-json": classified( + "evidence_integrity_mismatch", + "execution_failure", + ), + "path-limit": classified("resource_constraint", "resource_constraint"), + "storage-limit": classified("resource_constraint", "resource_constraint"), + io: classified("execution_failure", "execution_failure"), +} as const satisfies Readonly< + Record +>; + +const UNKNOWN_REGISTRY_CLASSIFICATIONS = { + "not-found": classified("execution_failure", "execution_failure"), + "already-exists": classified("invalid_request", "invalid_input"), + "revision-conflict": classified("revision_conflict", "execution_failure"), + "invalid-transition": classified("execution_failure", "execution_failure"), + integrity: classified("evidence_integrity_mismatch", "execution_failure"), + limit: classified("truncated", "execution_failure"), + constraint: classified("invalid_request", "invalid_input"), +} as const satisfies Readonly< + Record +>; + +const PROVIDER_SELECTION_CLASSIFICATIONS = { + unknown_provider: classified( + "capability_unavailable", + "unsupported_provider", + ), + provider_unavailable: classified("provider_unavailable", "unavailable"), + target_unsupported: classified( + "capability_unavailable", + "unsupported_provider", + ), + ambiguous: classified("capability_unavailable", "unsupported_provider"), + invalid_options: classified("capability_unavailable", "unsupported_provider"), +} as const satisfies Readonly< + Record +>; + +type BinaryTargetConstraintKey = + | NonNullable + | "unconstrained"; + +const BINARY_TARGET_CLASSIFICATIONS = { + unconstrained: classified("target_unavailable", "unavailable"), + directory_requires_file: classified("target_unavailable", "unavailable"), + wasm_requires_static_inspection: classified( + "target_unavailable", + "unsupported_target", + ), + file_format_rejected: classified("target_unavailable", "unsupported_target"), + load_selection_rejected: classified("invalid_request", "invalid_input"), + bundle_type_unsupported: classified( + "target_unavailable", + "unsupported_target", + ), + bundle_info_plist_missing: classified("target_unavailable", "unavailable"), + bundle_layout_ambiguous: classified("target_unavailable", "unavailable"), + bundle_executable_undeclared: classified("target_unavailable", "unavailable"), + bundle_program_missing: classified("target_unavailable", "unavailable"), + bundle_current_version_missing: classified( + "target_unavailable", + "unavailable", + ), + bundle_path_escapes: classified("target_unavailable", "unavailable"), +} as const satisfies Readonly< + Record +>; + +/** A target the host refused to read keeps its constraint's category. */ +const binaryTargetClassification = ( + constraint: BinaryTargetConstraintKey, + readPermissionDenied: boolean, +): AnalysisErrorClassification => { + const base = BINARY_TARGET_CLASSIFICATIONS[constraint]; + return readPermissionDenied && constraint !== "load_selection_rejected" + ? { ...base, code: "access_denied" } + : base; +}; + +const BROWSER_OBSERVATION_CLASSIFICATIONS = { + endpoint_unreachable: classified("provider_unavailable", "unavailable"), + invalid_endpoint_response: classified( + "unreadable_output", + "execution_failure", + ), + target_not_found: classified("target_unavailable", "unavailable"), + target_not_allowed: classified("target_unavailable", "unavailable"), + application_already_running: classified("target_unavailable", "unavailable"), + service_worker_blocked: classified("target_unavailable", "unavailable"), + target_changed: classified("target_unavailable", "unavailable"), + target_session_detached: classified("target_unavailable", "unavailable"), + protocol_error: classified("unreadable_output", "execution_failure"), + disconnected: classified("provider_unavailable", "unavailable"), + payload_limit: classified("truncated", "truncated"), + window_not_found: classified("unreadable_output", "execution_failure"), + window_metadata_missing: classified("unreadable_output", "execution_failure"), + process_ownership_unavailable: classified( + "unreadable_output", + "execution_failure", + ), + cleanup_failed: classified("execution_failure", "execution_failure"), + cancelled: classified("cancelled", "cancelled"), + timeout: classified("provider_timeout", "timeout"), +} as const satisfies Readonly< + Record +>; + +/** Any error the caller's cancellation caused reports as that cancellation. */ +const CANCELLED = classified("cancelled", "cancelled"); + +const PROCESS_CAPTURE_FAILED = classified( + "process_capture_failed", + "execution_failure", +); + +/** A tag whose code and category do not depend on the error's facts. */ +const staticClassification = ( + error: AnalysisError, +): AnalysisErrorClassification => { + const tag = domainErrorTag(error); + if (tag === undefined) + throw new TypeError(`Unpresented provider error: ${error._tag}`); + switch (tag) { + case "ArtifactOperationError": + case "BinaryTargetError": + case "BrowserObservationError": + case "EvidenceFileError": + case "ProcessCaptureError": + case "ProviderSelectionError": + case "UnknownRegistryError": + throw new TypeError(`Unhandled specialized analysis error: ${tag}`); + default: + return STATIC_ERROR_CLASSIFICATIONS[tag]; + } +}; + +/** + * The code and category of a domain-presented error. A provider-owned error + * supplies its own through `ownPresentation()`. Cleanup state is applied by + * the projection, which reports `cleanup_incomplete` above this code. + */ +export const classifyAnalysisError = ( + error: AnalysisError, +): AnalysisErrorClassification => { + const owned = error.ownPresentation(); + if (owned !== undefined) + return { code: owned.code, category: owned.category }; + if (error instanceof AnalysisCapabilityUnavailableError && error.retryable) + return RETRYABLE_CAPABILITY_UNAVAILABLE; + if (error instanceof ProviderSelectionError) + return PROVIDER_SELECTION_CLASSIFICATIONS[error.reason]; + if (error instanceof BrowserObservationError) + return error.userCategory === "cancelled" + ? CANCELLED + : BROWSER_OBSERVATION_CLASSIFICATIONS[error.reason]; + if (error instanceof ArtifactOperationError) + return error.reason === "integrity" && error.artifactDetails !== undefined + ? ARTIFACT_IDENTITY_MISMATCH + : ARTIFACT_OPERATION_CLASSIFICATIONS[error.reason]; + if (error instanceof BinaryTargetError) + return binaryTargetClassification( + error.constraint ?? "unconstrained", + error.systemCode !== undefined, + ); + if (error instanceof EvidenceFileError) + return EVIDENCE_FILE_CLASSIFICATIONS[error.reason]; + if (error instanceof UnknownRegistryError) + return UNKNOWN_REGISTRY_CLASSIFICATIONS[error.reason]; + if (error._tag === "ProcessCaptureError") + return error.userCategory === "cancelled" + ? CANCELLED + : PROCESS_CAPTURE_FAILED; + return staticClassification(error); +}; + +/** One row of the generated error catalogue. */ +export interface AnalysisErrorCatalogueEntry extends AnalysisErrorClassification { + readonly tag: AnalysisErrorTag | ProviderErrorTag; + /** The fact that selects this row; empty when the tag alone does. */ + readonly discriminant: string; + /** + * Whether the projection reports the case as retryable. An error's own + * recovery facts can still change it: a resource constraint's recovery, a + * raisable reader limit, a capture's retry flag, or a provider's opt-out. + */ + readonly retryableByDefault: boolean; +} + +/** + * One catalogue row. A provider that presents its own errors lists them + * through this, so its rows read like the domain's. + */ +export const catalogueRow = ( + tag: AnalysisErrorTag | ProviderErrorTag, + discriminant: string, + classification: AnalysisErrorClassification, + retryableByDefault = RETRYABLE_CODES.has(classification.code), +): AnalysisErrorCatalogueEntry => ({ + tag, + discriminant, + ...classification, + retryableByDefault, +}); + +const reasonRows = ( + tag: AnalysisErrorTag, + table: Readonly>, +): AnalysisErrorCatalogueEntry[] => + Object.entries(table).map(([reason, classification]) => + catalogueRow(tag, `reason=${reason}`, classification), + ); + +/** + * Every domain error case and its caller-facing code and category. A + * provider-owned error presents itself, and its provider lists its rows. + * Cleanup that did not complete reports `cleanup_incomplete` above any row. + */ +export const analysisErrorCatalogue = + (): readonly AnalysisErrorCatalogueEntry[] => [ + ...Object.entries(STATIC_ERROR_CLASSIFICATIONS).map( + ([tag, classification]) => + catalogueRow(tag as AnalysisErrorTag, "", classification), + ), + catalogueRow( + "AnalysisCapabilityUnavailableError", + "retryable=true", + RETRYABLE_CAPABILITY_UNAVAILABLE, + true, + ), + ...reasonRows("ArtifactOperationError", ARTIFACT_OPERATION_CLASSIFICATIONS), + catalogueRow( + "ArtifactOperationError", + "reason=integrity; artifact identity reported", + ARTIFACT_IDENTITY_MISMATCH, + ), + ...Object.keys(BINARY_TARGET_CLASSIFICATIONS).flatMap((key) => { + const constraint = key as BinaryTargetConstraintKey; + const allowed = binaryTargetClassification(constraint, false); + const denied = binaryTargetClassification(constraint, true); + return [ + catalogueRow("BinaryTargetError", `constraint=${constraint}`, allowed), + ...(denied.code === allowed.code + ? [] + : [ + catalogueRow( + "BinaryTargetError", + `constraint=${constraint}; read permission denied`, + denied, + ), + ]), + ]; + }), + ...reasonRows( + "BrowserObservationError", + BROWSER_OBSERVATION_CLASSIFICATIONS, + ), + catalogueRow( + "BrowserObservationError", + "caused by cancellation", + CANCELLED, + ), + ...reasonRows("EvidenceFileError", EVIDENCE_FILE_CLASSIFICATIONS), + catalogueRow("ProcessCaptureError", "", PROCESS_CAPTURE_FAILED), + catalogueRow("ProcessCaptureError", "caused by cancellation", CANCELLED), + ...reasonRows("ProviderSelectionError", PROVIDER_SELECTION_CLASSIFICATIONS), + ...reasonRows("UnknownRegistryError", UNKNOWN_REGISTRY_CLASSIFICATIONS), + ]; diff --git a/src/domain/analysisErrorPresentation.ts b/src/domain/analysisErrorPresentation.ts index 98537cdc6e..fc5c408153 100644 --- a/src/domain/analysisErrorPresentation.ts +++ b/src/domain/analysisErrorPresentation.ts @@ -9,7 +9,6 @@ import { AnalysisUnsupportedTargetError, AnalysisResourceConstraintError, AnalysisTimeoutError, - type AnalysisTimeoutRecovery, } from "./analysisErrorCore.js"; import { ArtifactOperationError } from "./artifactOperationError.js"; import { OPENABLE_APPLE_BUNDLE_TYPES_TEXT } from "./apple/appleBundleTypes.js"; @@ -26,20 +25,12 @@ import { AnalysisSnapshotMismatchError, ResourceSnapshotMismatchError, } from "./evidenceErrors.js"; -import { - HOPPER_STARTUP_TIMEOUT_REMEDIATION, - HopperRemoteError, - HopperProcessError, - HopperStartError, - HopperTimeoutError, - hopperAppleEventsAuthorizationDenied, -} from "./hopperErrors.js"; import { ProviderSelectionError } from "./providerSelectionError.js"; import { ProviderAdapterError } from "./providerAdapterError.js"; import { isDoctorProviderId } from "./doctorProviderIds.js"; import { UnknownRegistryError } from "./unknownRegistryError.js"; -import { providerRetryAction } from "./providerOperationHealth.js"; import { analysisErrorRefusal } from "./analysisErrorRefusal.js"; +import { classifyAnalysisError } from "./analysisErrorClassification.js"; import { analysisRefusalMessage, analysisRefusalRemediation, @@ -51,6 +42,8 @@ import { type AnalysisContinuingCallerGuidance, type AnalysisError, type AnalysisErrorTag, + domainErrorTag, + ProviderOwnedAnalysisError, } from "./analysisErrorBase.js"; import type { AnalysisErrorProjection } from "./analysisErrorProjection.js"; @@ -72,12 +65,6 @@ export const MCP_TRANSPORT_EVIDENCE_RECORDS = `Request fewer records with get_ev export const MCP_TRANSPORT_EVIDENCE_LINKS = "Request fewer rows with get_evidence_bundle detail: links, a smaller limit or an exact evidence_id filter, then follow next_offset."; -const HOPPER_APPLE_EVENTS_AUTHORIZATION_MESSAGE = - "macOS denied permission to send Apple Events to Hopper. A hardened-runtime application starting REA requires the com.apple.security.automation.apple-events entitlement before macOS will prompt for permission."; - -const HOPPER_APPLE_EVENTS_AUTHORIZATION_REMEDIATION = - "Allow the application that starts REA under System Settings > Privacy & Security > Automation. If the client lacks the com.apple.security.automation.apple-events entitlement, ask the client developer to add it or start REA from a client macOS can authorize, such as Terminal. Retrying from the same unauthorized client will not succeed until authorization changes."; - /** Name the next step that is true for how long the caller keeps REA's runtime and session. */ export const analysisErrorRemediationAction = ( error: AnalysisError, @@ -87,9 +74,11 @@ export const analysisErrorRemediationAction = ( const continuing = callerLifetime === "continuing" ? (error.continuingCallerGuidance?.remediationAction ?? - hopperContinuingRecovery(error)?.remediationAction) + error.ownPresentation()?.continuing?.remediationAction) : undefined; if (continuing !== undefined) return continuing; + const owned = error.ownPresentation()?.remediation; + if (owned !== undefined) return owned; if ( (error instanceof ProviderAdapterError || error instanceof AnalysisCapabilityUnavailableError) && @@ -169,25 +158,6 @@ export const analysisErrorRemediationAction = ( error.boundary === "capacity" ) return "Use an artifact within the capacity reported in details.detail. Changing output detail or retrying the unchanged input does not remove this boundary."; - if (error instanceof HopperTimeoutError) - return hopperTimeoutRecovery(error).remediationAction; - if (error instanceof HopperProcessError) - return error.failureCode !== undefined && error.userMessage !== undefined - ? error.userMessage - : error.stage === "launch" - ? "Review the captured launcher diagnostics and Hopper setup, then retry opening the target." - : RERUN_HOPPER_INVOCATION; - if (error instanceof HopperStartError) { - if (hopperAppleEventsAuthorizationDenied(error.launchRejection)) - return HOPPER_APPLE_EVENTS_AUTHORIZATION_REMEDIATION; - return error.ownerRunId === undefined - ? "Check the Hopper launcher and target details, then retry opening the target." - : `Use the active REA session ${error.ownerRunId} or close it before opening this target again.`; - } - if (error instanceof HopperRemoteError) - return error.diagnosticType === "invalid_request" - ? "Correct the reported address, document, or arguments and retry." - : "Review the Hopper diagnostic details and correct the request or target; run `rea doctor` if the provider itself is failing. Repeating the unchanged request is not expected to succeed."; if (error instanceof EvidenceReferenceError) return error.reason === "missing" && error.referenceScope === "retained-closure" @@ -337,116 +307,8 @@ const measuredResourceRemediation = ( export const analysisErrorCategory = ( error: AnalysisError, -): AnalysisErrorProjection["category"] => { - error = primaryAnalysisError(error); - if (error instanceof AnalysisCapabilityUnavailableError && error.retryable) - return "unavailable"; - if ( - error instanceof BinaryTargetError && - error.constraint === "load_selection_rejected" - ) - return "invalid_input"; - if ( - error instanceof BinaryTargetError && - (error.constraint === "wasm_requires_static_inspection" || - error.constraint === "file_format_rejected" || - error.constraint === "bundle_type_unsupported") - ) - return "unsupported_target"; - if ( - error instanceof ProviderSelectionError && - error.reason === "provider_unavailable" - ) - return "unavailable"; - if (error._tag === "ProcessCaptureError") - return error.userCategory ?? "execution_failure"; - if (error instanceof BrowserObservationError) - return error.userCategory ?? browserErrorCategory(error.reason); - if ( - error instanceof HopperRemoteError && - error.diagnosticType === "invalid_request" - ) - return "invalid_input"; - if ( - error instanceof HopperRemoteError && - error.diagnosticType === "authorization" - ) - return "unavailable"; - if (error instanceof HopperProcessError || error instanceof HopperStartError) - return "unavailable"; - if (error instanceof ArtifactOperationError) - return artifactErrorCategory(error.reason); - if ( - error instanceof EvidenceFileError && - (error.reason === "path-limit" || error.reason === "storage-limit") - ) - return "resource_constraint"; - if ( - error instanceof EvidenceFileError && - (error.reason === "missing" || - error.reason === "symlink-traversal" || - error.reason === "not-file" || - error.reason === "wrong-kind" || - error.reason === "exists") - ) - return "invalid_input"; - if ( - error instanceof UnknownRegistryError && - (error.reason === "already-exists" || error.reason === "constraint") - ) - return "invalid_input"; - return STATIC_ERROR_CATEGORIES[error._tag] ?? "execution_failure"; -}; - -const browserErrorCategory = ( - reason: BrowserObservationError["reason"], -): AnalysisErrorProjection["category"] => { - if (reason === "cancelled") return "cancelled"; - if (reason === "timeout") return "timeout"; - if (reason === "payload_limit") return "truncated"; - if ( - reason === "target_not_found" || - reason === "target_not_allowed" || - reason === "application_already_running" || - reason === "service_worker_blocked" || - reason === "target_changed" || - reason === "target_session_detached" || - reason === "endpoint_unreachable" || - reason === "disconnected" - ) - return "unavailable"; - return "execution_failure"; -}; - -const artifactErrorCategory = ( - reason: ArtifactOperationError["reason"], -): AnalysisErrorProjection["category"] => { - if (reason === "integrity") return "integrity_mismatch"; - if (reason === "limit") return "truncated"; - if (reason === "cancelled") return "cancelled"; - if (reason === "unavailable") return "unavailable"; - return "execution_failure"; -}; - -const STATIC_ERROR_CATEGORIES: Readonly< - Partial> -> = { - ConfigurationError: "invalid_input", - AnalysisInputError: "invalid_input", - AnalysisAccessDeniedError: "unavailable", - AnalysisArtifactChangedError: "integrity_mismatch", - AnalysisCapabilityUnavailableError: "unsupported_provider", - AnalysisUnsupportedTargetError: "unsupported_target", - ProviderSelectionError: "unsupported_provider", - EvidenceIntegrityError: "integrity_mismatch", - AnalysisCancelledError: "cancelled", - HopperCancelledError: "cancelled", - AnalysisTimeoutError: "timeout", - AnalysisResourceConstraintError: "resource_constraint", - HopperTimeoutError: "timeout", - NoBinaryOpenError: "unavailable", - BinaryTargetError: "unavailable", -}; +): AnalysisErrorProjection["category"] => + classifyAnalysisError(primaryAnalysisError(error)).category; /** Describe the request's outcome, adding continuing-caller facts only for that caller. */ export const analysisErrorUserMessage = ( @@ -467,7 +329,7 @@ const analysisErrorUserMessageParts = ( const outcome = outcomeUserMessage(error); const continuing = error.continuingCallerGuidance?.userMessage ?? - hopperContinuingRecovery(error)?.userMessage; + error.ownPresentation()?.continuing?.userMessage; return continuing === undefined ? { outcome } : { outcome, continuing }; }; @@ -476,7 +338,7 @@ export const hasAnalysisContinuingCallerGuidance = ( error: AnalysisError, ): boolean => error.continuingCallerGuidance !== undefined || - hopperContinuingRecovery(error) !== undefined; + error.ownPresentation()?.continuing !== undefined; /** A declared recovery action is distinct from a category's generic fallback. */ const hasAuthoredRemediation = ( @@ -555,14 +417,14 @@ const outcomeUserMessage = (error: AnalysisError): string => { } if (error instanceof AnalysisTimeoutError) return error.userMessage ?? timeoutUserMessage(error); - const hopperMessage = hopperErrorUserMessage(error); - if (hopperMessage !== undefined) return hopperMessage; + const ownedMessage = error.ownPresentation()?.message; + if (ownedMessage !== undefined) return ownedMessage; if (error.userMessage !== undefined) return error.userMessage; if (error instanceof AnalysisCapabilityUnavailableError && error.retryable) return "Required runtime controls are unavailable for this attempt."; if (error instanceof ProviderAdapterError) return `The ${error.providerId} provider could not complete ${error.operation}, and REA did not classify the failure. Any reason the provider reported is in details.diagnostics.`; - const standardMessage = standardErrorMessage(error._tag); + const standardMessage = standardErrorMessage(error); if (standardMessage !== undefined) return standardMessage; if (error instanceof ArtifactOperationError) return artifactMessage(error); if (error instanceof EvidenceReferenceError) @@ -624,115 +486,18 @@ const unclassifiedProviderRemediation = (providerId: string): string => ? `Review the reported details. If the ${providerId} installation or configuration may be at fault, run \`rea doctor --provider ${providerId}\` and apply its fixes. Repeating the unchanged request is not expected to succeed.` : "Review the reported details for the provider's reason; REA has no specific recovery for this unclassified failure. Repeating the unchanged request is not expected to succeed."; -const hopperErrorUserMessage = (error: AnalysisError): string | undefined => { - if (error instanceof HopperTimeoutError) - return hopperTimeoutRecovery(error).userMessage; - if (error instanceof HopperProcessError) return hopperProcessMessage(error); - if (error instanceof HopperStartError) { - if (hopperAppleEventsAuthorizationDenied(error.launchRejection)) - return HOPPER_APPLE_EVENTS_AUTHORIZATION_MESSAGE; - return ( - error.userMessage ?? - "Hopper could not start. Check the launcher and target details, then retry opening the target." - ); - } - if (error instanceof HopperRemoteError) - return `Hopper ${error.operation ?? "analysis"} failed (${String(error.code)}, ${error.diagnosticType}): ${error.safeMessage}`; - return undefined; -}; - /** - * The invocation caller's recovery for an elapsed Hopper deadline: the startup - * deadline (bridge readiness) or one request's deadline. + * Standard text by tag, or by the code an error that presents itself + * declares, when nothing more specific describes the outcome. */ -const hopperTimeoutRecovery = ( - error: HopperTimeoutError, -): Required< - Pick -> => { - if (error.operation === undefined) - return { - userMessage: - "REA timed out waiting for Hopper bridge readiness, which includes initial analysis. Hopper may still be analyzing the target or waiting for a loader, demo, or license dialog. Review the captured launcher outcome and resolve retained cleanup before retrying.", - remediationAction: HOPPER_STARTUP_TIMEOUT_REMEDIATION, - }; - const request = error.operation; - return { - userMessage: - error.providerState === "busy" - ? `Hopper timed out during ${request} while the provider remained busy.` - : `Hopper timed out during ${request} before it started.`, - remediationAction: RERUN_HOPPER_INVOCATION, - }; -}; - -const RESTART_OWNED_PROVIDER = - "Restart the owned provider by calling close_binary, then open the target again and retry."; -const RESTART_UNREACHABLE_HOPPER = `${RESTART_OWNED_PROVIDER} close_binary preserves retained Evidence and Unknown history on this connection; export_evidence_bundle before ending the REA process if you need to resume later.`; -const RERUN_HOPPER_INVOCATION = - "Review the reported Hopper state and resolve any incomplete cleanup before rerunning the command."; - -const hopperContinuingRecovery = ( - error: AnalysisError, -): AnalysisContinuingCallerGuidance | undefined => { - if (error instanceof HopperTimeoutError && error.operation !== undefined) { - const action = - error.providerState === "busy" - ? "Check binary_session.analysis_activity, wait for the active Hopper request to finish, then retry." - : "Check binary_session for Hopper health, then retry the operation."; - return { userMessage: action, remediationAction: action }; - } - if (!(error instanceof HopperProcessError)) return undefined; - if ( - error.providerState === "exited" && - (error.stage === "launch" || error.failureCode !== undefined) - ) - return undefined; - const action = - error.providerState === "unreachable" - ? RESTART_UNREACHABLE_HOPPER - : providerRetryAction(error.providerState) === "restart_provider" - ? RESTART_OWNED_PROVIDER - : "Read binary_session.provider_operation_health for this request before retrying or restarting the owned provider."; - return { - userMessage: action, - ...(error.stage === "launch" || - (error.failureCode !== undefined && error.userMessage !== undefined) - ? {} - : { remediationAction: action }), - }; -}; - -const hopperProcessMessage = (error: HopperProcessError): string => { - const stage = error.stage; - const where = error.operation ?? stage; - const request = - error.requestId === undefined - ? "" - : ` Request id ${String(error.requestId)}.`; - const startup = - error.userMessage === undefined ? "" : ` ${error.userMessage}`; - if (error.providerState === "exited") { - const signal = error.launcherFailure?.signal; - const exit = - error.exitCode === null - ? signal === undefined || signal === null - ? "no exit code was observed" - : `signal ${signal}` - : `exit code ${String(error.exitCode)}`; - return `Hopper exited during ${where} (${exit}).${startup}${request}`; - } - if (error.providerState === "unreachable") - return `Hopper became unreachable during ${where}; its process exit was not observed.${startup}${request}`; - return `Hopper failed during ${where} and REA could not determine whether the provider is busy, exited, or unreachable.${startup}${request}`; -}; - -const standardErrorMessage = (tag: AnalysisErrorTag): string | undefined => { - if (UNREADABLE_OUTPUT_TAGS.has(tag)) +const standardErrorMessage = (error: AnalysisError): string | undefined => { + const tag = error._tag; + const code = error.ownPresentation()?.code; + if (UNREADABLE_OUTPUT_TAGS.has(tag) || code === "unreadable_output") return "Analysis returned a result REA could not read. Review the reported details; repeating the unchanged request is not expected to succeed."; if (UNSUPPORTED_PROVIDER_TAGS.has(tag)) return "This analysis is unavailable for the current target. Choose another analysis or target."; - if (CANCELLED_TAGS.has(tag)) + if (CANCELLED_TAGS.has(tag) || code === "cancelled") return "Analysis was cancelled. Start it again when ready."; return undefined; }; @@ -743,18 +508,17 @@ const timeoutUserMessage = (error: AnalysisTimeoutError): string => const timeoutRemediation = (error: AnalysisTimeoutError): string => `Inspect any partial Evidence, provider diagnostics and reported session/provider cleanup state for ${error.operation}. Reduce the request if supported, or resolve the reported provider condition before retrying. Do not repeat the unchanged call or retry while work or cleanup may still be active.`; -const UNREADABLE_OUTPUT_TAGS: ReadonlySet = new Set([ +const UNREADABLE_OUTPUT_TAGS: ReadonlySet = new Set([ "AnalysisProtocolError", "AnalysisOutputError", - "HopperProtocolError", ]); -const UNSUPPORTED_PROVIDER_TAGS: ReadonlySet = new Set([ - "AnalysisCapabilityUnavailableError", - "ProviderSelectionError", -]); -const CANCELLED_TAGS: ReadonlySet = new Set([ +const UNSUPPORTED_PROVIDER_TAGS: ReadonlySet = + new Set([ + "AnalysisCapabilityUnavailableError", + "ProviderSelectionError", + ]); +const CANCELLED_TAGS: ReadonlySet = new Set([ "AnalysisCancelledError", - "HopperCancelledError", ]); /** Operations that accept integrity_policy for declared-integrity mismatches. */ @@ -856,18 +620,18 @@ const KNOWN_ERROR_TAGS = { EvidenceIntegrityError: true, EvidenceFileError: true, UnknownRegistryError: true, - HopperTimeoutError: true, - HopperCancelledError: true, - HopperProtocolError: true, - HopperRemoteError: true, - HopperProcessError: true, - HopperStartError: true, ConfigurationError: true, NoBinaryOpenError: true, BinaryTargetError: true, } as const satisfies Readonly>; -export const assertKnownAnalysisErrorTag = (tag: AnalysisErrorTag): void => { - if (KNOWN_ERROR_TAGS[tag] !== true) +/** + * Accept a domain error the shared tables present, or a provider-owned error + * that presents itself. + */ +export const assertKnownAnalysisError = (error: AnalysisError): void => { + if (error instanceof ProviderOwnedAnalysisError) return; + const tag = domainErrorTag(error); + if (tag === undefined || KNOWN_ERROR_TAGS[tag] !== true) throw new TypeError("Unknown analysis error tag"); }; diff --git a/src/domain/analysisErrorProjection.test.ts b/src/domain/analysisErrorProjection.test.ts index dd28c090c9..3752d853e3 100644 --- a/src/domain/analysisErrorProjection.test.ts +++ b/src/domain/analysisErrorProjection.test.ts @@ -1,4 +1,3 @@ -import { MAX_NODE_TIMER_DELAY_MS } from "./analysisResourceLimits.js"; import { describe, expect, it } from "vitest"; import { AnalysisCapabilityUnavailableError, @@ -17,20 +16,6 @@ import { } from "./configurationErrors.js"; import { BrowserObservationError } from "./browserObservationError.js"; import { EvidenceFileError, EvidenceIntegrityError } from "./evidenceErrors.js"; -import { - HOPPER_STARTUP_TIMEOUT_REMEDIATION, - HopperProcessError, - HopperRemoteError, - HopperStartError, - HopperTimeoutError, -} from "./hopperErrors.js"; -import { - DEFAULT_HOPPER_DEMO_DIALOG_TIMEOUT_MS, - HOPPER_DEMO_DIALOG_TIMEOUT_SETTING, - MINIMUM_HOPPER_DEMO_DIALOG_TIMEOUT_MS, - type DialogTimeoutRejection, - type HopperStartupFailureDiagnostic, -} from "./hopperStartupFailure.js"; import { ProviderAdapterError } from "./providerAdapterError.js"; import { UnknownRegistryError } from "./unknownRegistryError.js"; import { @@ -49,7 +34,13 @@ import { analysisSettingLimit } from "./analysisSettingDefinitions.js"; import { redactExplicitFailure } from "./explicitSensitiveFailure.js"; import { redactExplicitText } from "./explicitSensitiveValues.js"; import { analysisErrorWithCleanupFailure } from "./analysisErrorCleanup.js"; -import type { AnalysisCallerLifetime } from "./analysisErrorBase.js"; +import { + AnalysisError, + ProviderOwnedAnalysisError, + providerErrorTag, + type AnalysisCallerLifetime, + type AnalysisErrorOwnPresentation, +} from "./analysisErrorBase.js"; import { ProviderCleanupError } from "./providerCleanupError.js"; import { releaseOwnedCleanup } from "../../tests/support/cleanupRelease.js"; @@ -795,132 +786,6 @@ describe("analysis error projection: browser provider failures", () => { }); }); -describe("analysis error projection: Hopper provider failures", () => { - it("reports a timed-out active Hopper request and actionable retry guidance", () => { - const projected = projectAnalysisError( - new HopperTimeoutError(30_000, "trace_feature", 42, "busy"), - ); - - expect(projected).toMatchObject({ - code: "provider_timeout", - category: "timeout", - retryable: true, - details: { - stage: "analysis", - operation: "trace_feature", - request_id: 42, - provider_state: "busy", - timeout_ms: 30_000, - }, - }); - expect(projected.message).toContain("binary_session.analysis_activity"); - expect(projected.remediation.action).toContain( - "wait for the active Hopper request", - ); - }); - - it("identifies the REA session that already owns a Hopper target", () => { - const error = new HopperStartError({ - ownerRunId: "session-owner", - userMessage: - "This Hopper target is already open in REA session session-owner. Use that REA session or close it before opening this target again.", - }); - expect(projectAnalysisError(error)).toMatchObject({ - category: "unavailable", - message: expect.stringContaining("session-owner"), - remediation: { - action: expect.stringContaining( - "Use the active REA session session-owner", - ), - }, - }); - }); - - it("projects an Apple Events denial as unavailable and not retryable from the same client", () => { - const projected = projectAnalysisError( - new HopperStartError({ - launchRejection: { - boundary: "apple_events_authorization", - reason: "not_authorized", - }, - launcherFailure: { - exit_code: 2, - signal: null, - stdout: { text: "", bytes: 0, retained_bytes: 0 }, - stderr: { - text: "Cannot launch Hopper!\nNot authorized to send Apple events to Hopper Disassembler.\n", - bytes: 90, - retained_bytes: 90, - }, - output_closed: true, - diagnostic_truncated: false, - }, - }), - ); - expect(projected).toMatchObject({ - code: "provider_unavailable", - category: "unavailable", - retryable: false, - details: { - stage: "launch", - provider_state: "unknown", - retry_action: "unknown", - launch_rejection: { - boundary: "apple_events_authorization", - reason: "not_authorized", - }, - launcher: { exit_code: 2, signal: null }, - }, - }); - expect(analysisErrorProjectionSchema.parse(projected)).toEqual(projected); - }); - - it("keeps an ordinary Hopper start failure retryable", () => { - const projected = projectAnalysisError( - new HopperStartError({ - userMessage: "Hopper's launcher helper failed before bridge readiness.", - }), - ); - expect(projected).toMatchObject({ - code: "provider_unavailable", - category: "unavailable", - retryable: true, - details: { - stage: "launch", - provider_state: "unknown", - retry_action: "retry", - }, - }); - expect(projected.details).not.toHaveProperty("launch_rejection"); - }); - - it("retains the Hopper request and provider diagnostic on a remote failure", () => { - expect( - projectAnalysisError( - new HopperRemoteError( - 7, - "Hopper analysis failed in the selected document", - { - diagnosticType: "bridge_exception", - operation: "trace_feature", - requestId: 43, - }, - ), - ), - ).toMatchObject({ - code: "execution_failure", - details: { - stage: "analysis", - provider_code: 7, - diagnostic_type: "bridge_exception", - operation: "trace_feature", - request_id: 43, - }, - message: expect.stringContaining("Hopper analysis failed"), - }); - }); -}); - describe("analysis error projection: detached provider diagnostics", () => { it.each(["adapter", "cancelled", "timeout"])( "preserves detached, actionable diagnostics for %s errors", @@ -951,96 +816,6 @@ describe("analysis error projection: detached provider diagnostics", () => { ); }); -describe("analysis error projection: Hopper startup failures", () => { - it("maps the Linux startup compatibility exit codes without host internals", () => { - const expected = [ - [70, "private_display_unavailable"], - [71, "x11_authorization_failed"], - [72, "unsupported_hopper_build"], - [73, "invalid_launch_command"], - [74, "process_ownership_mismatch"], - [75, "hopper_exited_during_startup"], - [76, "unsupported_demo_dialog"], - [77, "unexpected_display_geometry"], - [78, "x11_input_failed"], - [79, "runtime_dependency_unavailable"], - [80, "x11_socket_directory_unusable"], - [81, "demo_dialog_absent"], - [82, "invalid_dialog_timeout"], - ] as const; - - for (const [exitCode, code] of expected) { - const projected = projectAnalysisError(new HopperProcessError(exitCode)); - expect(projected).toMatchObject({ - code: "provider_unavailable", - details: { failure_code: code, exit_code: exitCode }, - }); - expect(projected.details).not.toHaveProperty("launch_rejection"); - expect(projected.message).toMatch(/\S/u); - expect(JSON.stringify(projected)).not.toContain("/proc/"); - } - }); - - it("does not attribute an absent post-authentication dialog to publisher verification", () => { - const projected = projectAnalysisError(new HopperProcessError(81)); - expect(projected).toMatchObject({ - code: "provider_unavailable", - details: { - stage: "launch", - failure_code: "demo_dialog_absent", - exit_code: 81, - }, - }); - expect(projected.details).not.toHaveProperty("launch_rejection"); - expect(projected.message).toContain("REA_HOPPER_DEMO_DIALOG_TIMEOUT_MS"); - }); - - it("reports a rejected demo dialog timeout through its setting fields", () => { - const dialogTimeout = { - setting: HOPPER_DEMO_DIALOG_TIMEOUT_SETTING, - value: "-5", - source: "setting", - minimum_ms: MINIMUM_HOPPER_DEMO_DIALOG_TIMEOUT_MS, - maximum_ms: MAX_NODE_TIMER_DELAY_MS, - default_ms: DEFAULT_HOPPER_DEMO_DIALOG_TIMEOUT_MS, - } satisfies DialogTimeoutRejection; - const projected = projectAnalysisError( - new HopperProcessError(82, { - diagnostic: { - component: "hopper_private_display", - operation: "launch", - reason: "invalid_dialog_timeout", - socket_directory: "/tmp/.X11-unix", - socket_directory_mode: null, - mount_read_only: null, - effective_socket_directory_mode: null, - effective_mount_read_only: null, - wsl: false, - strategy: "direct", - fallback_reason: null, - xvfb_stderr_bytes: 0, - status: "error", - failure_code: "invalid_dialog_timeout", - dialog_timeout: dialogTimeout, - } as HopperStartupFailureDiagnostic, - }), - ); - expect(projected).toMatchObject({ - code: "provider_unavailable", - details: { - stage: "launch", - failure_code: "invalid_dialog_timeout", - exit_code: 82, - diagnostics: { dialog_timeout: dialogTimeout }, - }, - }); - expect(projected.details).not.toHaveProperty("launch_rejection"); - expect(analysisErrorProjectionSchema.safeParse(projected).success).toBe( - true, - ); - }); -}); - describe("analysis error projection: unclassified failures", () => { it.each(["hopper", "ghidra", "ida", "jadx", "kuna"])( "names doctor only with the provider it can check (%s)", @@ -1096,38 +871,6 @@ describe("analysis error projection: unclassified failures", () => { }); }); -describe("analysis error projection: retry guidance", () => { - it.each([ - [ - "unreadable output", - new AnalysisOutputError("inspect_firmware_regions", "report missing"), - "unreadable_output", - ], - [ - "adapter failure", - new ProviderAdapterError("firmware", "inspect_firmware_regions"), - "execution_failure", - ], - [ - "Hopper remote failure", - new HopperRemoteError(7, "Hopper analysis failed", { - diagnosticType: "bridge_exception", - operation: "trace_feature", - }), - "execution_failure", - ], - ])( - "does not recommend an unchanged retry for non-retryable %s", - (_name, error, code) => { - const projected = projectAnalysisError(error); - - expect(projected).toMatchObject({ code, retryable: false }); - for (const text of [projected.message, projected.remediation.action]) - expect(text).not.toMatch(/\bretry\b/iu); - }, - ); -}); - describe("analysis error projection: caller contract", () => { it("preserves the reported output constraint without exposing its internal cause", () => { const projected = projectAnalysisError( @@ -1281,83 +1024,6 @@ describe("analysis error projection: caller contract", () => { }); }); -describe("analysis error projection: operational diagnostics", () => { - it("distinguishes an observed Hopper exit from an undetermined provider failure", () => { - const exitedError = new HopperProcessError(7, { - operation: "search_strings", - requestId: 4, - }); - const exited = projectAnalysisError(exitedError); - expect(exited).toMatchObject({ - code: "provider_unavailable", - retryable: true, - details: { - stage: "analysis", - provider_state: "exited", - retry_action: "restart_provider", - operation: "search_strings", - request_id: 4, - exit_code: 7, - }, - }); - expect(exited.message).toBe(analysisErrorUserMessage(exitedError)); - expect(exited.remediation.action).toBe( - analysisErrorRemediationAction(exitedError), - ); - expect(exited.message).toMatch( - /Hopper exited.*search_strings.*exit code 7/iu, - ); - expect(exited.remediation.action).toMatch(/close_binary.*open.*retry/iu); - - const unknownError = new HopperProcessError(null, { - operation: "search_strings", - requestId: 5, - }); - const unknown = projectAnalysisError(unknownError); - expect(unknown.details).toMatchObject({ - stage: "analysis", - provider_state: "unknown", - retry_action: "unknown", - operation: "search_strings", - request_id: 5, - exit_code: null, - }); - expect(unknown.message).toBe(analysisErrorUserMessage(unknownError)); - expect(unknown.remediation.action).toBe( - analysisErrorRemediationAction(unknownError), - ); - expect(unknown.message).toMatch( - /could not determine.*busy, exited, or unreachable/iu, - ); - expect(unknown.remediation.action).toMatch( - /provider_operation_health.*before retrying or restarting/iu, - ); - - const unreachableError = new HopperProcessError(null, { - operation: "search_strings", - providerState: "unreachable", - }); - const unreachable = projectAnalysisError(unreachableError); - expect(unreachable).toMatchObject({ - code: "provider_unavailable", - details: { - provider_state: "unreachable", - retry_action: "restart_provider", - operation: "search_strings", - exit_code: null, - }, - message: analysisErrorUserMessage(unreachableError), - remediation: { action: analysisErrorRemediationAction(unreachableError) }, - }); - expect(unreachable.message).toMatch( - /unreachable.*process exit was not observed/iu, - ); - expect(unreachable.remediation.action).toMatch( - /close_binary.*Evidence and Unknown history.*export_evidence_bundle/iu, - ); - }); -}); - describe("analysis error projection: evidence files", () => { it.each([ ["read", "missing", "invalid_request", "invalid_input"], @@ -1458,47 +1124,6 @@ it.each([false, true])( }, ); -it("retains Hopper startup diagnostics beside generic and secondary context", () => { - const diagnostic = { - component: "hopper_private_display", - operation: "launch", - reason: "fixture_denial", - socket_directory: "/tmp/.X11-unix", - socket_directory_mode: null, - mount_read_only: null, - effective_socket_directory_mode: null, - effective_mount_read_only: null, - wsl: false, - strategy: "unavailable", - fallback_reason: null, - xvfb_stderr_bytes: 0, - status: "error", - failure_code: "private_display_unavailable", - } as const; - expect( - projectAnalysisError(new HopperProcessError(null, { diagnostic })).details - ?.diagnostics, - ).toEqual(diagnostic); - const generic = { caller_context: "retained" }; - expect( - projectAnalysisError( - new HopperProcessError(null, { diagnostic, diagnostics: generic }), - ), - ).toMatchObject({ - code: "provider_unavailable", - details: { diagnostics: generic, provider_diagnostics: diagnostic }, - }); - const secondary = new HopperProcessError(null, { - diagnostic, - }).retainSecondaryFailure(new HopperProcessError(null), { - retirement_error: "retained", - }); - expect(projectAnalysisError(secondary).details).toMatchObject({ - provider_diagnostics: diagnostic, - diagnostics: { retirement_error: "retained" }, - }); -}); - it("does not offer entry-policy retries for integrity refusals without a declared-versus-observed entry contradiction", () => { const native = projectAnalysisError( new ArtifactOperationError( @@ -1671,123 +1296,6 @@ describe("analysis error projection: caller lifetime", () => { projectAnalysisError(error, "invocation").details?.limit, ).not.toHaveProperty("environment"); }); - - it("delivers each lifetime's Hopper startup recovery", () => { - const error = new HopperTimeoutError( - 30_000, - undefined, - undefined, - "not_started", - "launch", - undefined, - { - limit: analysisSettingLimit( - "hopper.startup_timeout_ms", - 30_000, - undefined, - ), - }, - ); - expect(projectAnalysisError(error).remediation.action).toMatch( - /update_analysis_settings.*hopper\.startup_timeout_ms.*without restarting REA/u, - ); - const invocation = projectAnalysisError(error, "invocation"); - expect(invocation.remediation.action).toBe( - HOPPER_STARTUP_TIMEOUT_REMEDIATION, - ); - expect(invocation.details?.limit).toMatchObject({ - setting: "hopper.startup_timeout_ms", - effective_value: 30_000, - scope: "rea-invocation", - applies_at: "next_invocation", - environment: "REA_HOPPER_STARTUP_TIMEOUT_MS", - }); - }); -}); - -describe("analysis error projection: Hopper caller lifetime", () => { - it.each([ - [ - new HopperProcessError(7, { operation: "search_strings", requestId: 4 }), - "close_binary", - "exit code 7", - ], - [ - new HopperProcessError(null, { - operation: "search_strings", - providerState: "unreachable", - }), - "export_evidence_bundle", - "process exit was not observed", - ], - [ - new HopperProcessError(null, { operation: "search_strings" }), - "binary_session.provider_operation_health", - "could not determine", - ], - [ - new HopperTimeoutError(30_000, "search_strings", 42, "busy"), - "binary_session.analysis_activity", - "remained busy", - ], - [ - new HopperTimeoutError(30_000, "search_strings", 42, "not_started"), - "binary_session", - "before it started", - ], - ] as const)( - "keeps Hopper outcome facts and scopes request recovery to the caller", - (error, continuingTool, outcome) => { - const continuing = projectAnalysisError(error); - const invocation = projectAnalysisError(error, "invocation"); - expect(continuing.message).toContain(continuingTool); - expect(continuing.remediation.action).toContain(continuingTool); - expect(invocation.message).toContain(outcome); - expect(invocation.message).not.toContain(continuingTool); - expect(invocation.remediation.action).toContain("rerunning the command"); - expect(invocation.remediation.action).not.toContain(continuingTool); - expect(invocation.details).toEqual(continuing.details); - expect(invocation.code).toBe(continuing.code); - expect(invocation.category).toBe(continuing.category); - expect(invocation.retryable).toBe(continuing.retryable); - expect(analysisErrorProjectionSchema.parse(invocation)).toEqual( - invocation, - ); - }, - ); - - it("keeps Hopper recovery scoped through composed cleanup and its history", () => { - const primary = new HopperProcessError(null, { - operation: "search_strings", - providerState: "unreachable", - }); - const cleanup = new ProviderCleanupError("hopper", ["hopper-bridge"], {}); - const composed = analysisErrorWithCleanupFailure( - primary, - cleanup, - ).bindCleanupDependencies([cleanup]); - const invocationPrimary = projectAnalysisError(primary, "invocation"); - const continuingPrimary = projectAnalysisError(primary); - const invocation = projectAnalysisError(composed, "invocation"); - const continuing = projectAnalysisError(composed); - expect(invocation.message).toBe(invocationPrimary.message); - expect(continuing.message).toBe(continuingPrimary.message); - expect(invocation.details).toMatchObject({ - resources: ["hopper-bridge"], - diagnostics: { primary_error: invocationPrimary }, - }); - expect(continuing.details).toMatchObject({ - diagnostics: { primary_error: continuingPrimary }, - }); - - releaseOwnedCleanup(cleanup); - expect( - projectAnalysisError(composed, "invocation").details?.cleanup_history, - ).toMatchObject({ primary_error: invocationPrimary }); - expect( - projectAnalysisError(composed).details?.cleanup_history, - ).toMatchObject({ primary_error: continuingPrimary }); - }); }); describe("analysis error projection: composed failures for a caller lifetime", () => { @@ -1913,6 +1421,45 @@ describe("analysis error projection: composed failures for a caller lifetime", ( }); }); +describe("analysis error projection: provider-owned errors", () => { + class ExampleProviderError extends ProviderOwnedAnalysisError { + readonly _tag = providerErrorTag("ExampleProviderError"); + constructor() { + super("Example provider stopped with internal state"); + } + override ownPresentation(): AnalysisErrorOwnPresentation { + return { + code: "provider_unavailable", + category: "unavailable", + message: "The example provider stopped.", + remediation: "Restart the example provider, then retry.", + details: { stage: "launch" }, + }; + } + } + + it("projects a tag outside the domain set through the error's own presentation", () => { + const projection = projectAnalysisError(new ExampleProviderError()); + expect(projection).toMatchObject({ + code: "provider_unavailable", + category: "unavailable", + message: "The example provider stopped.", + remediation: { action: "Restart the example provider, then retry." }, + details: { stage: "launch" }, + }); + expect(analysisErrorProjectionSchema.parse(projection)).toEqual(projection); + }); + + it("refuses an error whose tag is neither a domain tag nor provider-owned", () => { + class StrayError extends AnalysisError { + readonly _tag = "StrayError" as unknown as AnalysisError["_tag"]; + } + expect(() => projectAnalysisError(new StrayError("stray"))).toThrow( + "Unknown analysis error tag", + ); + }); +}); + describe("analysis error projection: composite argument observations", () => { const left = { kind: "retained-evidence", evidence_id: "left" } as const; const right = { kind: "retained-evidence", evidence_id: "right" } as const; diff --git a/src/domain/analysisErrorProjection.ts b/src/domain/analysisErrorProjection.ts index c893a3fa77..e4035ff0ed 100644 --- a/src/domain/analysisErrorProjection.ts +++ b/src/domain/analysisErrorProjection.ts @@ -12,7 +12,7 @@ import { UNRETAINED_EVIDENCE_EXPORT_GUIDANCE, analysisErrorRemediationAction, analysisErrorUserMessage, - assertKnownAnalysisErrorTag, + assertKnownAnalysisError, hasAnalysisContinuingCallerGuidance, } from "./analysisErrorPresentation.js"; import { @@ -38,18 +38,9 @@ import { EvidenceIntegrityError, EvidenceReferenceError, } from "./evidenceErrors.js"; -import { - HopperCancelledError, - HopperProcessError, - HopperRemoteError, - HopperStartError, - HopperTimeoutError, - hopperAppleEventsAuthorizationDenied, -} from "./hopperErrors.js"; import { ProviderAdapterError } from "./providerAdapterError.js"; import { ProviderSelectionError } from "./providerSelectionError.js"; import { UnknownRegistryError } from "./unknownRegistryError.js"; -import { providerRetryAction } from "./providerOperationHealth.js"; import { primaryAnalysisError, resolvedAnalysisError, @@ -58,11 +49,14 @@ import { type AnalysisError, type AnalysisErrorOptions, type AnalysisRelatedInputs, - type AnalysisErrorTag, } from "./analysisErrorBase.js"; import { invocationLimit } from "./analysisSettingDefinitions.js"; import { analysisErrorRefusal } from "./analysisErrorRefusal.js"; import { analysisRefusalDetails } from "./analysisRefusal.js"; +import { + classifyAnalysisError, + RETRYABLE_CODES, +} from "./analysisErrorClassification.js"; import { isRecord } from "../kernel/isRecord.js"; /** @@ -420,9 +414,9 @@ const projectError = ( owner = owner.cleanupPrimary ) cleanupReport = owner.cleanupReport; - assertKnownAnalysisErrorTag(error._tag); + assertKnownAnalysisError(error); const primary = primaryAnalysisError(error); - assertKnownAnalysisErrorTag(primary._tag); + assertKnownAnalysisError(primary); const underlyingCode = underlyingErrorCode(primary); const code = error.cleanupIncomplete ? "cleanup_incomplete" : underlyingCode; const primaryDetails = errorDetails(primary); @@ -563,10 +557,7 @@ const projectError = ( message: analysisErrorUserMessage(error, callerLifetime), retryable: (RETRYABLE_CODES.has(code) && - !( - error instanceof HopperStartError && - hopperAppleEventsAuthorizationDenied(error.launchRejection) - )) || + error.ownPresentation()?.retryable !== false) || (error instanceof AnalysisCapabilityUnavailableError && error.retryable) || (error._tag === "ProcessCaptureError" && @@ -607,154 +598,16 @@ const errorRecovery = ( const underlyingErrorCode = ( error: AnalysisError, -): AnalysisErrorProjection["code"] => { - if ( - error instanceof HopperRemoteError && - error.diagnosticType === "invalid_request" - ) - return "invalid_request"; - if (error instanceof ProviderSelectionError) - return error.reason === "provider_unavailable" - ? "provider_unavailable" - : "capability_unavailable"; - if (error instanceof BrowserObservationError) - return error.userCategory === "cancelled" - ? "cancelled" - : BROWSER_ERROR_CODES[error.reason]; - if (error instanceof ArtifactOperationError) - return artifactOperationCode(error); - if (error instanceof BinaryTargetError) - return error.constraint === "load_selection_rejected" - ? "invalid_request" - : error.systemCode === undefined - ? "target_unavailable" - : "access_denied"; - if (error instanceof EvidenceFileError) return evidenceFileCode(error.reason); - if (error instanceof UnknownRegistryError) - return unknownRegistryCode(error.reason); - if (error._tag === "ProcessCaptureError") return processCaptureCode(error); - return staticErrorCode(error._tag); -}; - -const BROWSER_ERROR_CODES: Readonly< - Record -> = { - endpoint_unreachable: "provider_unavailable", - invalid_endpoint_response: "unreadable_output", - target_not_found: "target_unavailable", - target_not_allowed: "target_unavailable", - service_worker_blocked: "target_unavailable", - target_changed: "target_unavailable", - target_session_detached: "target_unavailable", - protocol_error: "unreadable_output", - disconnected: "provider_unavailable", - payload_limit: "truncated", - window_not_found: "unreadable_output", - window_metadata_missing: "unreadable_output", - process_ownership_unavailable: "unreadable_output", - application_already_running: "target_unavailable", - cleanup_failed: "execution_failure", - cancelled: "cancelled", - timeout: "provider_timeout", -}; - -const artifactOperationCode = ( - error: ArtifactOperationError, -): AnalysisErrorProjection["code"] => { - if (error.reason === "integrity" && error.artifactDetails !== undefined) - return "artifact_integrity_mismatch"; - if (error.reason === "limit") return "truncated"; - if (error.reason === "cancelled") return "cancelled"; - return "artifact_operation_failed"; -}; - -const evidenceFileCode = ( - reason: EvidenceFileError["reason"], -): AnalysisErrorProjection["code"] => { - if (reason === "invalid-json") return "evidence_integrity_mismatch"; - if (reason === "path-limit" || reason === "storage-limit") - return "resource_constraint"; - // A missing, non-file or already-existing path is the caller's selection. - if (reason === "io") return "execution_failure"; - return "invalid_request"; -}; - -const unknownRegistryCode = ( - reason: UnknownRegistryError["reason"], -): AnalysisErrorProjection["code"] => { - if (reason === "revision-conflict") return "revision_conflict"; - if (reason === "already-exists" || reason === "constraint") - return "invalid_request"; - if (reason === "limit") return "truncated"; - if (reason === "integrity") return "evidence_integrity_mismatch"; - return "execution_failure"; -}; - -const processCaptureCode = ( - error: AnalysisError, -): AnalysisErrorProjection["code"] => { - if (error.cleanupIncomplete) return "cleanup_incomplete"; - if (error.userCategory === "cancelled") return "cancelled"; - return "process_capture_failed"; -}; - -type SpecializedErrorTag = - | "ArtifactOperationError" - | "BinaryTargetError" - | "BrowserObservationError" - | "EvidenceFileError" - | "ProcessCaptureError" - | "ProviderSelectionError" - | "UnknownRegistryError"; - -const STATIC_ERROR_CODES = { - AnalysisProtocolError: "unreadable_output", - AnalysisOutputError: "unreadable_output", - HopperProtocolError: "unreadable_output", - AnalysisInputError: "invalid_request", - AnalysisAccessDeniedError: "access_denied", - AnalysisArtifactChangedError: "artifact_changed", - AnalysisCapabilityUnavailableError: "capability_unavailable", - AnalysisUnsupportedTargetError: "unsupported_target", - AnalysisCancelledError: "cancelled", - HopperCancelledError: "cancelled", - AnalysisTimeoutError: "provider_timeout", - AnalysisResourceConstraintError: "resource_constraint", - HopperTimeoutError: "provider_timeout", - HopperProcessError: "provider_unavailable", - HopperStartError: "provider_unavailable", - ConfigurationError: "configuration_invalid", - NoBinaryOpenError: "target_unavailable", - EvidenceIntegrityError: "evidence_integrity_mismatch", - ProviderAdapterError: "execution_failure", - HopperRemoteError: "execution_failure", -} as const satisfies Readonly< - Record< - Exclude, - AnalysisErrorProjection["code"] - > ->; - -const staticErrorCode = ( - tag: AnalysisErrorTag, -): AnalysisErrorProjection["code"] => { - switch (tag) { - case "ArtifactOperationError": - case "BinaryTargetError": - case "BrowserObservationError": - case "EvidenceFileError": - case "ProcessCaptureError": - case "ProviderSelectionError": - case "UnknownRegistryError": - throw new TypeError(`Unhandled specialized analysis error: ${tag}`); - default: - return STATIC_ERROR_CODES[tag]; - } -}; +): AnalysisErrorProjection["code"] => + // A capture whose cleanup did not finish names that as its execution failure. + error._tag === "ProcessCaptureError" && error.cleanupIncomplete + ? "cleanup_incomplete" + : classifyAnalysisError(error).code; const errorDetails = ( error: AnalysisError, ): Readonly> | undefined => + error.ownPresentation()?.details ?? requestErrorDetails(error) ?? artifactStateErrorDetails(error) ?? providerErrorDetails(error) ?? @@ -990,56 +843,6 @@ const providerErrorDetails = ( : {}), }; } - if (error instanceof HopperRemoteError) - return { - stage: "analysis", - provider_code: error.code, - diagnostic_type: error.diagnosticType, - ...(error.operation === undefined ? {} : { operation: error.operation }), - ...(error.requestId === undefined ? {} : { request_id: error.requestId }), - }; - if (error instanceof HopperProcessError) { - const stage = error.stage; - return { - exit_code: error.exitCode, - stage, - provider_state: error.providerState, - retry_action: providerRetryAction( - error.providerState, - error.failureCode !== undefined || error.stage === "launch", - ), - ...(error.failureCode === undefined - ? {} - : { failure_code: error.failureCode }), - ...(error.operation === undefined ? {} : { operation: error.operation }), - ...(error.requestId === undefined ? {} : { request_id: error.requestId }), - ...(error.diagnostic === undefined - ? {} - : { diagnostics: { ...error.diagnostic } }), - ...(error.launcherFailure === undefined - ? {} - : { launcher: error.launcherFailure }), - }; - } - if (error instanceof HopperStartError) - return { - stage: "launch", - provider_state: "unknown", - ...(error.launchRejection === undefined - ? {} - : { launch_rejection: { ...error.launchRejection } }), - retry_action: - error.ownerRunId === undefined && - !hopperAppleEventsAuthorizationDenied(error.launchRejection) - ? "retry" - : "unknown", - ...(error.ownerRunId === undefined - ? {} - : { owner_run_id: error.ownerRunId }), - ...(error.launcherFailure === undefined - ? {} - : { launcher: error.launcherFailure }), - }; return undefined; }; @@ -1074,8 +877,6 @@ const lifecycleErrorDetails = ( execution_failure: "cancelled", }), }; - if (error instanceof HopperCancelledError) - return { operation: "hopper", cleanup: "complete" }; if (error instanceof AnalysisTimeoutError) return { operation: error.operation, @@ -1088,18 +889,6 @@ const lifecycleErrorDetails = ( resources: [...error.cleanup.resources], }), }; - if (error instanceof HopperTimeoutError) - return { - stage: error.operation === undefined ? "startup" : error.stage, - timeout_ms: error.timeoutMs, - ...(error.launcherOutcome === undefined - ? {} - : { launcher: error.launcherOutcome }), - provider_state: error.providerState, - retry_action: error.providerState === "busy" ? "wait" : "retry", - ...(error.operation === undefined ? {} : { operation: error.operation }), - ...(error.requestId === undefined ? {} : { request_id: error.requestId }), - }; if (error._tag === "ProcessCaptureError" && error.cleanupIncomplete) return { cleanup: "incomplete", @@ -1156,14 +945,6 @@ const lifecycleErrorDetails = ( return undefined; }; -const RETRYABLE_CODES: ReadonlySet = new Set([ - "artifact_changed", - "provider_timeout", - "cancelled", - "revision_conflict", - "provider_unavailable", -]); - export interface AnalysisErrorProjection extends Readonly< Record > { diff --git a/src/domain/commandObservation.ts b/src/domain/commandObservation.ts index 2c29d91ac5..2332535550 100644 --- a/src/domain/commandObservation.ts +++ b/src/domain/commandObservation.ts @@ -2,6 +2,41 @@ import { z } from "zod"; import { analysisParameterLimitSchema } from "./analysisSettingDefinitions.js"; +/** + * A completed provider's own refusal of the command, read from the exact + * diagnostic line it logged. Present only with completion_status rejected. + */ +export const commandRefusalSchema = z + .strictObject({ + reason: z + .enum([ + "unknown_command", + "wrong_argument_count", + "invalid_statement", + "parse_failure", + ]) + .describe( + "unknown_command: the named command does not exist. wrong_argument_count: the named command received the wrong number of arguments. invalid_statement: the provider could not execute a statement. parse_failure: the provider could not parse the input.", + ), + command: z + .string() + .nullable() + .describe( + "The command the refusal line names; null when the line names none.", + ), + line: z.string().describe("The provider's refusal line from stderr."), + }) + .describe( + "The provider refused the command after starting it; statements after the refused one did not run.", + ); +export type CommandRefusal = z.infer; + +/** A completed command's refusal and the limitation it places on the capture. */ +export interface CommandRejection { + readonly refusal: CommandRefusal; + readonly limitation: string; +} + /** Opaque producer text and the command capture's explicit completion facts. */ export const commandObservationSchema = z.strictObject({ stdout: z.string(), @@ -20,8 +55,9 @@ export const commandObservationSchema = z.strictObject({ completion_status: z .enum(["complete", "rejected", "unknown"]) .describe( - "complete: the provider process completed. rejected: it completed, but the provider reported that it refused the command; limitations say what ran. unknown: the capture or process ended early.", + "complete: the provider process completed. rejected: it completed, but the provider reported that it refused the command; refusal and limitations say what ran. unknown: the capture or process ended early.", ), + refusal: commandRefusalSchema.exactOptional(), artifact_sha256_after: z .string() .regex(/^[a-f0-9]{64}$/u) diff --git a/src/domain/hopperErrors.ts b/src/domain/hopperErrors.ts deleted file mode 100644 index 41cedc4c72..0000000000 --- a/src/domain/hopperErrors.ts +++ /dev/null @@ -1,267 +0,0 @@ -import { - AnalysisError, - type AnalysisErrorOptions, -} from "./analysisErrorBase.js"; -import type { - HopperProcessProviderState, - ProviderFailureStage, -} from "./providerOperationHealth.js"; -import { - dialogTimeoutFromDiagnostic, - hopperStartupFailure, - invalidDialogTimeoutMessage, - type HopperStartupFailureCode, - type HopperStartupFailureDiagnostic, -} from "./hopperStartupFailure.js"; - -/** Base class for failures produced specifically by the Hopper provider. */ -export abstract class HopperError extends AnalysisError {} - -/** Observed launcher outcome; a helper exit does not establish GUI lifetime. */ -export type HopperLauncherOutcome = { - readonly exit_code: number | null; - readonly signal: string | null; - /** Total bytes drained from the stream; retained_bytes reports captured bytes. */ - readonly stdout: { - readonly text: string; - readonly bytes: number; - readonly retained_bytes: number; - }; - readonly stderr: { - readonly text: string; - readonly bytes: number; - readonly retained_bytes: number; - }; - readonly output_closed: boolean; - readonly diagnostic_truncated: boolean; -}; - -/** Startup-timeout recovery that holds after the calling invocation has ended. */ -export const HOPPER_STARTUP_TIMEOUT_REMEDIATION = - "Review details.launcher and inspect Hopper for ongoing initial analysis or a pending loader, demo, or license dialog. For a large target, set REA_HOPPER_STARTUP_TIMEOUT_MS higher in the environment of a new REA invocation, then rerun the command; that invocation starts Hopper again. Resolve retained cleanup before rerunning."; - -/** Startup-timeout recovery for a caller whose REA runtime keeps running. */ -const HOPPER_STARTUP_TIMEOUT_CONTINUING_REMEDIATION = - "Review details.launcher and inspect Hopper for ongoing initial analysis or a pending loader, demo, or license dialog. For a large target, use update_analysis_settings with setting hopper.startup_timeout_ms and action set for the next startup attempt without restarting REA, or increase REA_HOPPER_STARTUP_TIMEOUT_MS for future REA processes. Allow at least that long in the MCP client. Resolve retained cleanup before reopening."; - -/** Hopper did not respond within the configured operation deadline. */ -export class HopperTimeoutError extends HopperError { - readonly _tag = "HopperTimeoutError"; - - constructor( - readonly timeoutMs: number, - readonly operation?: string, - readonly requestId?: number, - readonly providerState: "busy" | "not_started" = "not_started", - readonly stage: ProviderFailureStage = operation === undefined - ? "launch" - : "analysis", - readonly launcherOutcome?: HopperLauncherOutcome, - options: AnalysisErrorOptions = {}, - ) { - super( - `Hopper ${operation === undefined ? "startup" : operation} timed out after ${String(timeoutMs)}ms`, - operation === undefined - ? { - ...options, - continuingCallerGuidance: { - remediationAction: HOPPER_STARTUP_TIMEOUT_CONTINUING_REMEDIATION, - }, - } - : options, - ); - } -} - -/** The caller cancelled a Hopper operation before it completed. */ -export class HopperCancelledError extends HopperError { - readonly _tag = "HopperCancelledError"; - - constructor( - ...parameters: - | readonly [] - | readonly [cause: unknown] - | readonly [cause: unknown, options: Omit] - ) { - const errorOptions: AnalysisErrorOptions = { ...parameters[1] }; - // Argument presence matters: an explicit undefined is the caller's reason. - if (parameters.length > 0) - Object.defineProperty(errorOptions, "cause", { - configurable: true, - enumerable: true, - value: parameters[0], - writable: true, - }); - super("Hopper operation was cancelled", errorOptions); - } -} - -/** - * Classify caller cancellation from a signal. - * - * An aborted signal keeps its exact reason, including undefined. A signal that - * has not aborted does not invent a reason. - */ -export const hopperCancelledBySignal = ( - signal: AbortSignal | undefined, -): HopperCancelledError => - signal?.aborted === true - ? new HopperCancelledError(signal.reason) - : new HopperCancelledError(); - -/** Hopper returned bytes or JSON that do not satisfy the NDJSON RPC contract. */ -export class HopperProtocolError extends HopperError { - readonly _tag = "HopperProtocolError"; -} - -export type HopperDiagnosticType = - | "remote" - | "authorization" - | "invalid_request" - | "capability_unavailable" - | "bridge_exception"; - -/** Hopper's JSON-RPC endpoint returned an expected remote error response. */ -export interface HopperRemoteErrorContext extends AnalysisErrorOptions { - readonly diagnosticType?: HopperDiagnosticType | undefined; - readonly operation?: string | undefined; - readonly requestId?: number | undefined; -} - -export class HopperRemoteError extends HopperError { - readonly _tag = "HopperRemoteError"; - readonly diagnosticType: HopperDiagnosticType; - readonly operation: string | undefined; - readonly requestId: number | undefined; - - constructor( - readonly code: number, - readonly safeMessage: string, - context: HopperRemoteErrorContext = {}, - ) { - super(`Hopper request failed (${String(code)}): ${safeMessage}`, context); - this.diagnosticType = context.diagnosticType ?? "remote"; - this.operation = context.operation; - this.requestId = context.requestId; - } -} - -/** The owned Hopper bridge stopped before its client was closed. */ -export interface HopperProcessErrorContext extends AnalysisErrorOptions { - readonly diagnostic?: HopperStartupFailureDiagnostic | undefined; - readonly operation?: string | undefined; - readonly requestId?: number | undefined; - readonly providerState?: HopperProcessProviderState | undefined; - readonly stage?: ProviderFailureStage | undefined; - readonly launcherFailure?: HopperLauncherOutcome | undefined; -} - -export class HopperProcessError extends HopperError { - readonly _tag = "HopperProcessError"; - readonly failureCode: HopperStartupFailureCode | undefined; - override readonly userMessage: string | undefined; - readonly providerState: HopperProcessProviderState; - readonly stage: ProviderFailureStage; - readonly diagnostic: HopperStartupFailureDiagnostic | undefined; - readonly operation: string | undefined; - readonly requestId: number | undefined; - readonly launcherFailure: HopperLauncherOutcome | undefined; - - constructor( - readonly exitCode: number | null, - context: HopperProcessErrorContext = {}, - ) { - super( - `Hopper bridge stopped unexpectedly with code ${String(exitCode)}`, - context, - ); - this.diagnostic = context.diagnostic; - this.operation = context.operation; - this.requestId = context.requestId; - this.launcherFailure = context.launcherFailure; - const failure = hopperStartupFailure(exitCode); - this.userMessage = - failure?.code === "invalid_dialog_timeout" - ? invalidDialogTimeoutMessage( - dialogTimeoutFromDiagnostic(context.diagnostic), - ) - : failure?.message; - this.stage = - context.stage ?? - (failure === undefined - ? context.operation === undefined - ? "connection" - : "analysis" - : "launch"); - this.failureCode = failure?.code; - this.providerState = - context.providerState ?? (exitCode === null ? "unknown" : "exited"); - } -} - -/** - * Parsed facts about a Hopper launch refused before the target runs. - * Publisher and argument failures are decided before the launcher executes. - * Apple Events authorization is decided after the native helper starts and - * before document handoff. - */ -export type HopperLaunchRejection = - | { - /** The selected application was rejected before it was executed. */ - readonly boundary: "publisher_verification"; - /** Parsed failure reason supplied by the verification owner. */ - readonly reason: string; - } - | ({ - readonly boundary: "argument_encoding"; - readonly reason: "applescript_literal"; - } & ( - | { readonly source: "launcher_path" } - | { - readonly source: "argument"; - /** Zero-based index in the final vendor argv, excluding the executable. */ - readonly argument_index: number; - } - )) - | { - /** - * macOS refused the launcher's Apple Event. The helper's stderr does not - * show whether the responsible client lacks an Automation grant or the - * hardened-runtime Apple Events entitlement. Another launch from that - * same client cannot succeed until authorization changes. - */ - readonly boundary: "apple_events_authorization"; - readonly reason: "not_authorized"; - }; - -/** Recognize the Apple Events refusal that the same client cannot retry. */ -export const hopperAppleEventsAuthorizationDenied = ( - rejection: HopperLaunchRejection | undefined, -): rejection is Extract< - HopperLaunchRejection, - { readonly boundary: "apple_events_authorization" } -> => rejection?.boundary === "apple_events_authorization"; - -/** Hopper or the repository bridge could not be started. */ -export class HopperStartError extends HopperError { - readonly _tag = "HopperStartError"; - override readonly userMessage: string | undefined; - readonly ownerRunId: string | undefined; - readonly launcherFailure: HopperLauncherOutcome | undefined; - readonly launchRejection: HopperLaunchRejection | undefined; - - constructor( - options?: AnalysisErrorOptions & { - readonly userMessage?: string; - readonly ownerRunId?: string; - readonly launcherFailure?: HopperLauncherOutcome; - readonly launchRejection?: HopperLaunchRejection; - }, - ) { - super("Hopper application bridge could not be started", options); - this.userMessage = options?.userMessage; - this.ownerRunId = options?.ownerRunId; - this.launcherFailure = options?.launcherFailure; - this.launchRejection = options?.launchRejection; - } -} diff --git a/src/domain/providerAdapterError.ts b/src/domain/providerAdapterError.ts index 832d34b48a..b6534d3855 100644 --- a/src/domain/providerAdapterError.ts +++ b/src/domain/providerAdapterError.ts @@ -24,6 +24,10 @@ export class ProviderAdapterError extends AnalysisError { this.userMessage = options.userMessage; this.remediationAction = options.remediationAction; } + + override get providerWide(): boolean { + return true; + } } /** A request reached an analysis client after its session closed that client. */ diff --git a/src/domain/unclassifiedProviderFailure.ts b/src/domain/unclassifiedProviderFailure.ts new file mode 100644 index 0000000000..17786011b1 --- /dev/null +++ b/src/domain/unclassifiedProviderFailure.ts @@ -0,0 +1,42 @@ +import { + ProviderAdapterError, + type ProviderAdapterErrorOptions, +} from "./providerAdapterError.js"; + +/** + * What the shared outcome classifier examined for one owned command whose + * exit or stream failure the provider's dialect did not recognise. Field names are the reported diagnostic keys. + */ +export interface ExaminedProviderOutcome { + /** The physical outcome kind the supervisor observed. */ + readonly failure_kind: "exited" | "protocol"; + readonly reason: string; + /** Null when the process did not exit with a status. */ + readonly exit_code: number | null; + readonly signal: string | null; + /** For an exit: whether the owner had begun stopping the process. */ + readonly stop_requested?: boolean; + /** Whether the retained output omits bytes; absent when none was retained. */ + readonly output_truncated?: boolean; +} + +/** + * An owned provider command's outcome that its dialect examined and did not + * recognise. It reports as the generic provider adapter failure and always + * carries the examined outcome, so the fallback states what was checked. + * Only `classifyProviderOutcome` constructs it, from the outcome it examined. + */ +export class UnclassifiedProviderFailure extends ProviderAdapterError { + constructor( + providerId: string, + operation: string, + readonly examined: ExaminedProviderOutcome, + /** `diagnostics` are provider facts reported beside the examined outcome. */ + options: ProviderAdapterErrorOptions = {}, + ) { + super(providerId, operation, { + ...options, + diagnostics: { ...options.diagnostics, ...examined }, + }); + } +} diff --git a/src/evm/EvmoleFailures.ts b/src/evm/EvmoleFailures.ts index a2052d2589..885a18252e 100644 --- a/src/evm/EvmoleFailures.ts +++ b/src/evm/EvmoleFailures.ts @@ -195,7 +195,7 @@ const evmCommandContext = ( { ...details, userMessage: reason }, ); }, - dialect: (outcome, details) => { + dialect: (outcome, details, unclassified) => { // The reserved exit means EFBIG only when the worker's marker says so. if ( outcome.kind === "exited" && @@ -217,21 +217,8 @@ const evmCommandContext = ( ), }, ); - return new ProviderAdapterError(EVMOLE_PROVIDER_IDENTITY.id, OPERATION, { - ...details, - diagnostics: { - ...evmWorkerDiagnostics(context), - reason: outcome.message, - failure_kind: outcome.kind, - // A stream failure is not an ordinary exit, but its recorded - // status remains evidence. - ...(outcome.output === undefined - ? {} - : { - exit_code: outcome.output.snapshot.exitCode ?? null, - signal: outcome.output.snapshot.signal ?? null, - }), - }, + return unclassified({ + diagnostics: evmWorkerDiagnostics(context), }); }, }; diff --git a/src/evm/EvmoleInterfaceProvider.ts b/src/evm/EvmoleInterfaceProvider.ts index 41735e069b..90cb34cc14 100644 --- a/src/evm/EvmoleInterfaceProvider.ts +++ b/src/evm/EvmoleInterfaceProvider.ts @@ -52,7 +52,9 @@ import { AnalysisOutputError, cancelledBy, carriedReason, + type AbortedSignal, } from "../domain/analysisErrorCore.js"; +import { isAbortOf } from "../process/SignalAbort.js"; import { projectAnalysisError, projectAnalysisErrorWithoutCapturedOutput, @@ -94,20 +96,16 @@ import { sha256Hex } from "../kernel/sha256Hex.js"; const OPERATION = "inspect_evm_interface"; -/** The caller's own abort, keeping any read cleanup bound to the report. */ +/** The caller's cancellation, observed as `signal`'s own abort. */ const abortedFailure = ( - cause: unknown, + signal: AbortedSignal, retainedOutput: AnalysisCapturedOutput | undefined, -): AnalysisCancelledError => { - const failure = cancelledBy(OPERATION, carriedReason(cause), { - ...(retainedOutput === undefined ? {} : { capturedOutput: retainedOutput }), - ...(cause instanceof ArtifactReaderFailure && cause.cleanup !== undefined - ? { cleanup: cause.cleanup } - : {}), - }); - bindArtifactFileCleanup(cause, failure); - return failure; -}; +): AnalysisCancelledError => + cancelledBy( + OPERATION, + signal, + retainedOutput === undefined ? {} : { capturedOutput: retainedOutput }, + ); const HOST_REQUIREMENT = "Initial real-verified offline EVM interface profile supports Linux x64 only."; @@ -891,24 +889,24 @@ export class EvmoleInterfaceProvider implements EvmInterfacePort { }; } } - let failure = - options?.signal?.aborted && - (cause === options.signal.reason || - (cause instanceof Error && cause.name === "AbortError")) - ? abortedFailure(cause, retainedOutput) - : // Owns the selected carrier's cleanup binding and snapshot identity. - classifyProviderFailure( - cause, - evmFailureDialect({ - phase, - path: input.path, - workerLimits, - limiter, - fileFailure, - timeoutMs, - producerLimits, - }), - ); + // Only this caller's own abort is a cancellation; an abort error with + // another reason is classified as the failure it is. + const signal = options?.signal; + let failure = isAbortOf(cause, signal) + ? abortedFailure(signal, retainedOutput) + : // Owns the selected carrier's cleanup binding and snapshot identity. + classifyProviderFailure( + cause, + evmFailureDialect({ + phase, + path: input.path, + workerLimits, + limiter, + fileFailure, + timeoutMs, + producerLimits, + }), + ); if (markerCleanupFailure !== undefined) { const cleanup = retainedCleanupFailure(markerCleanupFailure); failure = analysisErrorWithCleanupFailure( diff --git a/src/flutter/FlutterBuildProvider.ts b/src/flutter/FlutterBuildProvider.ts index 6f3d46fc7e..966ed56445 100644 --- a/src/flutter/FlutterBuildProvider.ts +++ b/src/flutter/FlutterBuildProvider.ts @@ -45,6 +45,7 @@ import { cancelledBy, carriedReason, } from "../domain/analysisErrorCore.js"; +import { isAbortWithReason } from "../process/SignalAbort.js"; import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js"; import { fixedAllowanceOptions } from "../domain/fixedAllowanceRemediation.js"; import { @@ -151,11 +152,7 @@ const sha256File = async ( } return hash.digest("hex"); } catch (cause) { - if ( - cause instanceof Error && - cause.name === "AbortError" && - cause.cause === marker - ) + if (isAbortWithReason(cause, marker)) throw cancelledBy(operation, carriedReason(signal?.reason)); throw cause; } finally { diff --git a/src/ghidra/GhidraAnalysisSeeds.ts b/src/ghidra/GhidraAnalysisSeeds.ts index 2bdfc0d273..7e88074a00 100644 --- a/src/ghidra/GhidraAnalysisSeeds.ts +++ b/src/ghidra/GhidraAnalysisSeeds.ts @@ -1,4 +1,5 @@ import { GhidraAdmissionError } from "./GhidraAdmissionError.js"; +import { classifyProviderFailure } from "../providers/classifyProviderFailure.js"; import { mkdir, realpath, stat } from "node:fs/promises"; import { isAbsolute, join } from "node:path"; import { z } from "zod"; @@ -11,7 +12,7 @@ import type { ArtifactResourceScope } from "../resources/index.js"; import { readGhidraProfileArtifact, writeGhidraProfileArtifact, - ghidraFileFailure, + ghidraFileDialect, } from "./GhidraFileArtifacts.js"; import { NonRegularFileReadError } from "../filesystem/RegularFile.js"; import { err, ok, type Result } from "../domain/result.js"; @@ -121,10 +122,13 @@ export const resolveGhidraAnalysisSeeds = async ( entries = await readSeeds(path, resources, signal); } catch (cause: unknown) { return err( - ghidraFileFailure(cause, "resolve_analysis_profile", { - setting: "REA_GHIDRA_SEED_FILE", - path: configured, - }), + classifyProviderFailure( + cause, + ghidraFileDialect("resolve_analysis_profile", { + setting: "REA_GHIDRA_SEED_FILE", + path: configured, + }), + ), ); } const normalized = normalizedGhidraSeeds(entries); @@ -140,9 +144,12 @@ export const resolveGhidraAnalysisSeeds = async ( }) .catch((cause: unknown) => err( - ghidraFileFailure(cause, "resolve_analysis_profile", { - setting: "REA_GHIDRA_SEED_FILE", - }), + classifyProviderFailure( + cause, + ghidraFileDialect("resolve_analysis_profile", { + setting: "REA_GHIDRA_SEED_FILE", + }), + ), ), ); @@ -173,10 +180,13 @@ export const snapshotGhidraAnalysisSeeds = async ( return path; }) .catch((cause: unknown) => { - throw ghidraFileFailure(cause, "open_binary", { - setting: "REA_GHIDRA_SEED_FILE", - path: commitment.path, - }); + throw classifyProviderFailure( + cause, + ghidraFileDialect("open_binary", { + setting: "REA_GHIDRA_SEED_FILE", + path: commitment.path, + }), + ); }); const totalEntries = (commitment: GhidraSeedCommitment): number => diff --git a/src/ghidra/GhidraCheckpoint.ts b/src/ghidra/GhidraCheckpoint.ts index bad74b6646..e8aba4fbd5 100644 --- a/src/ghidra/GhidraCheckpoint.ts +++ b/src/ghidra/GhidraCheckpoint.ts @@ -1,4 +1,5 @@ import { appendCallerPath } from "../filesystem/callerPath.js"; +import { classifyProviderFailure } from "../providers/classifyProviderFailure.js"; import { createHash, randomUUID } from "node:crypto"; import { constants } from "node:fs"; import { @@ -31,7 +32,7 @@ import { } from "../filesystem/RegularFile.js"; import { acquireOwnedLease, type OwnedLease } from "../process/OwnedLease.js"; import { - ghidraFileFailure, + ghidraFileDialect, readGhidraProfileArtifact, } from "./GhidraFileArtifacts.js"; import { errorMessage } from "../kernel/errorMessage.js"; @@ -145,14 +146,15 @@ async function readSource( ); } catch (cause: unknown) { if (missing(cause) && !resources.hasPending) return null; - throw ghidraFileFailure( + throw classifyProviderFailure( mapArtifactFileFailure(cause, (primary) => primary instanceof SyntaxError || primary instanceof z.ZodError ? failure(selection.directory, "the manifest is malformed", primary) : primary, ), - "resolve_analysis_profile", - { path: appendCallerPath(selection.directory, "current.json") }, + ghidraFileDialect("resolve_analysis_profile", { + path: appendCallerPath(selection.directory, "current.json"), + }), ); } if ( @@ -168,7 +170,10 @@ async function readSource( try { actual = await hashGhidraPackedProgram(path, resources, signal); } catch (cause: unknown) { - throw ghidraFileFailure(cause, "resolve_analysis_profile", { path }); + throw classifyProviderFailure( + cause, + ghidraFileDialect("resolve_analysis_profile", { path }), + ); } if (actual !== manifest.source.sha256) throw failure( @@ -377,19 +382,28 @@ export class GhidraCheckpoint { } catch (cause: unknown) { if (failed) throw analysisErrorWithCleanupFailure( - ghidraFileFailure(primary, "checkpoint_program", { - path: this.selection.directory, - }), - ghidraFileFailure(cause, "checkpoint_program", { - path: this.selection.directory, - }), + classifyProviderFailure( + primary, + ghidraFileDialect("checkpoint_program", { + path: this.selection.directory, + }), + ), + classifyProviderFailure( + cause, + ghidraFileDialect("checkpoint_program", { + path: this.selection.directory, + }), + ), ); throw cause; } if (failed) - throw ghidraFileFailure(primary, "checkpoint_program", { - path: this.selection.directory, - }); + throw classifyProviderFailure( + primary, + ghidraFileDialect("checkpoint_program", { + path: this.selection.directory, + }), + ); assertArtifactReadActive(signal); } diff --git a/src/ghidra/GhidraExecutableHeader.ts b/src/ghidra/GhidraExecutableHeader.ts index e3a0b79019..d9434be5ef 100644 --- a/src/ghidra/GhidraExecutableHeader.ts +++ b/src/ghidra/GhidraExecutableHeader.ts @@ -1,4 +1,5 @@ import { fixedAllowanceOptions } from "../domain/fixedAllowanceRemediation.js"; +import { classifyProviderFailure } from "../providers/classifyProviderFailure.js"; import type { GhidraExecutableHeaderProbe } from "./GhidraInstallation.js"; import type { GhidraInstallationFileOptions } from "./GhidraInstallationProperties.js"; import { err, ok, type Result } from "../domain/result.js"; @@ -6,7 +7,7 @@ import type { AnalysisError } from "../domain/analysisErrorBase.js"; import { AnalysisResourceConstraintError } from "../domain/analysisErrorCore.js"; import { withArtifactRegularFile } from "../resources/index.js"; import { readStableFilePrefix } from "../filesystem/readStableFileBytes.js"; -import { ghidraFileFailure } from "./GhidraFileArtifacts.js"; +import { ghidraFileDialect } from "./GhidraFileArtifacts.js"; import { sha256Hex } from "../kernel/sha256Hex.js"; /** Only this prefix is examined; the remainder is never retained or read. */ @@ -73,19 +74,22 @@ export const readGhidraExecutableHeader = async ( ); } catch (cause: unknown) { return err( - ghidraFileFailure(cause, "ghidra:installation", { - path, - stage: "native_decompiler_header", - ...(completedHeader === undefined - ? {} - : { - completed_header: { - file_bytes: completedHeader.size, - examined_bytes: completedHeader.bytes.length, - prefix_sha256: sha256Hex(completedHeader.bytes), - }, - }), - }), + classifyProviderFailure( + cause, + ghidraFileDialect("ghidra:installation", { + path, + stage: "native_decompiler_header", + ...(completedHeader === undefined + ? {} + : { + completed_header: { + file_bytes: completedHeader.size, + examined_bytes: completedHeader.bytes.length, + prefix_sha256: sha256Hex(completedHeader.bytes), + }, + }), + }), + ), ); } }; diff --git a/src/ghidra/GhidraFileArtifacts.ts b/src/ghidra/GhidraFileArtifacts.ts index 236f9c57e8..f00f3b1879 100644 --- a/src/ghidra/GhidraFileArtifacts.ts +++ b/src/ghidra/GhidraFileArtifacts.ts @@ -4,7 +4,6 @@ import { type ArtifactResourceScope, ArtifactReaderFailure, assertArtifactReadActive, - artifactFileCancellationCause, artifactFilePrimaryFacts, mapArtifactFileFailure, bindArtifactFileCleanup, @@ -20,14 +19,13 @@ import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisResourceConstraintError, - cancelledBy, - carriedReason, } from "../domain/analysisErrorCore.js"; import { RegularFileChangedError } from "../filesystem/RegularFile.js"; import { ProviderAdapterError } from "../domain/providerAdapterError.js"; import { ProviderCleanupError } from "../domain/providerCleanupError.js"; import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js"; import type { JsonValue } from "../domain/jsonValue.js"; +import type { ProviderFailureDialect } from "../providers/classifyProviderFailure.js"; import { errorMessage } from "../kernel/errorMessage.js"; /** Bounded serial read; the caller owns admission and final descriptor cleanup. */ @@ -60,72 +58,78 @@ export const writeGhidraProfileArtifact = async ( ); }; -/** Preserve physical failure, exact cancellation, and all retained file leases. */ -export const ghidraFileFailure = ( - cause: unknown, +/** Ghidra's typed meaning for one physical file failure, else the failure. */ +const ghidraPhysicalFailure = ( + primary: unknown, operation: string, - diagnostics: Readonly> = {}, -): AnalysisError => { - cause = mapArtifactFileFailure(cause, (primary) => { - if (primary instanceof RegularFileCapacityError) - return new AnalysisResourceConstraintError( - operation, - "file-size", - primary.message, - { - maximum_bytes: primary.maximumBytes, - observed_bytes: primary.observedBytes.toString(), - }, - { cause: primary, diagnostics, retryable: false }, - ); - if (primary instanceof RegularFileChangedError) - return new AnalysisArtifactChangedError( - operation, - primary.path, - primary.message, - { cause: primary, diagnostics }, - ); - if ( - primary instanceof Error && - "code" in primary && - (primary.code === "EACCES" || primary.code === "EPERM") - ) { - const path = - "path" in primary && typeof primary.path === "string" - ? primary.path - : diagnostics.path; - if (typeof path === "string") - return new AnalysisAccessDeniedError(operation, path, primary.code, { - cause: primary, - diagnostics, - }); - } - return primary; - }); - const { cause: primary, origin } = artifactFilePrimaryFacts(cause); - const admission = - primary instanceof GhidraAdmissionError ? primary : undefined; - const reason = admission?.code ?? errorMessage(primary); - const systemCode = - admission === undefined && + diagnostics: Readonly>, +): unknown => { + if (primary instanceof RegularFileCapacityError) + return new AnalysisResourceConstraintError( + operation, + "file-size", + primary.message, + { + maximum_bytes: primary.maximumBytes, + observed_bytes: primary.observedBytes.toString(), + }, + { cause: primary, diagnostics, retryable: false }, + ); + if (primary instanceof RegularFileChangedError) + return new AnalysisArtifactChangedError( + operation, + primary.path, + primary.message, + { cause: primary, diagnostics }, + ); + if ( primary instanceof Error && "code" in primary && - typeof primary.code === "string" - ? primary.code - : undefined; - const cleanup = - cause instanceof ArtifactReaderFailure ? cause.cleanup : undefined; - if (origin === "owned-or-classified" && primary instanceof AnalysisError) { + (primary.code === "EACCES" || primary.code === "EPERM") + ) { + const path = + "path" in primary && typeof primary.path === "string" + ? primary.path + : diagnostics.path; + if (typeof path === "string") + return new AnalysisAccessDeniedError(operation, path, primary.code, { + cause: primary, + diagnostics, + }); + } + return primary; +}; + +/** + * Ghidra's dialect for a file it reads or writes: its typed physical + * failures, composed with the file's unresolved cleanup, and an adapter + * report that keeps that cleanup for anything else. The shared owner reports + * the read's cancellation with these diagnostics. + */ +export const ghidraFileDialect = ( + operation: string, + diagnostics: Readonly> = {}, +): ProviderFailureDialect => ({ + providerId: "ghidra", + operation, + diagnostics, + recognise: (cause) => { + const mapped = mapArtifactFileFailure(cause, (primary) => + ghidraPhysicalFailure(primary, operation, diagnostics), + ); + const { cause: primary, origin } = artifactFilePrimaryFacts(mapped); + if (origin !== "owned-or-classified" || !(primary instanceof AnalysisError)) + return undefined; + const cleanup = + mapped instanceof ArtifactReaderFailure ? mapped.cleanup : undefined; if (cleanup === undefined) return primary; const failure = new ProviderCleanupError( "ghidra", cleanup.resources, - { - reason: cleanup.reason, - }, - { cause }, + { reason: cleanup.reason }, + { cause: mapped }, ); - bindArtifactFileCleanup(cause, failure); + bindArtifactFileCleanup(mapped, failure); return analysisErrorWithCleanupFailure( primary, failure, @@ -134,31 +138,35 @@ export const ghidraFileFailure = ( ...(primary.cleanupIncomplete ? [primary] : []), failure, ]); - } - const error = - cause instanceof ArtifactReaderFailure && cause.reason === "cancelled" - ? cancelledBy( - operation, - carriedReason(artifactFileCancellationCause(cause)), - { cleanup, diagnostics }, - ) - : new ProviderAdapterError("ghidra", operation, { - cause, - cleanup, - diagnostics: { - ...admission?.detail, - ...diagnostics, - ...(admission === undefined ? {} : { code: admission.code }), - ...(systemCode === undefined ? {} : { system_code: systemCode }), - ...(primary instanceof Error && - "syscall" in primary && - typeof primary.syscall === "string" - ? { syscall: primary.syscall } - : {}), - reason, - }, - userMessage: reason, - }); - bindArtifactFileCleanup(cause, error); - return error; -}; + }, + unclassified: (cause, details) => { + const { cause: primary } = artifactFilePrimaryFacts(cause); + const admission = + primary instanceof GhidraAdmissionError ? primary : undefined; + const reason = admission?.code ?? errorMessage(primary); + const systemCode = + admission === undefined && + primary instanceof Error && + "code" in primary && + typeof primary.code === "string" + ? primary.code + : undefined; + return new ProviderAdapterError("ghidra", operation, { + ...details, + cause, + diagnostics: { + ...admission?.detail, + ...diagnostics, + ...(admission === undefined ? {} : { code: admission.code }), + ...(systemCode === undefined ? {} : { system_code: systemCode }), + ...(primary instanceof Error && + "syscall" in primary && + typeof primary.syscall === "string" + ? { syscall: primary.syscall } + : {}), + reason, + }, + userMessage: reason, + }); + }, +}); diff --git a/src/ghidra/GhidraInstallationProperties.ts b/src/ghidra/GhidraInstallationProperties.ts index 7ca5887d16..d39b5b52a6 100644 --- a/src/ghidra/GhidraInstallationProperties.ts +++ b/src/ghidra/GhidraInstallationProperties.ts @@ -1,3 +1,4 @@ +import { classifyProviderFailure } from "../providers/classifyProviderFailure.js"; import type { RetainedResourceScope } from "../ports/AnalysisProvider.js"; import { artifactFileCompletion, @@ -15,7 +16,7 @@ import { AnalysisResourceConstraintError } from "../domain/analysisErrorCore.js" import { fixedProducerInputAllowance } from "../domain/fixedAllowanceRemediation.js"; import { NonRegularFileReadError } from "../filesystem/RegularFile.js"; import { ghidraApplicationProperties } from "./GhidraInstallationPolicy.js"; -import { ghidraFileFailure } from "./GhidraFileArtifacts.js"; +import { ghidraFileDialect } from "./GhidraFileArtifacts.js"; import { sha256Hex } from "../kernel/sha256Hex.js"; /** Metadata admission budget, not a Java Properties format limit. */ @@ -110,6 +111,9 @@ export const readGhidraInstallationProperties = async ( ) : primary, ); - throw ghidraFileFailure(qualified, "ghidra:installation", diagnostics); + throw classifyProviderFailure( + qualified, + ghidraFileDialect("ghidra:installation", diagnostics), + ); } }; diff --git a/src/ghidra/GhidraProjectSnapshot.ts b/src/ghidra/GhidraProjectSnapshot.ts index e879573942..a0af41adbe 100644 --- a/src/ghidra/GhidraProjectSnapshot.ts +++ b/src/ghidra/GhidraProjectSnapshot.ts @@ -1,6 +1,7 @@ import { AnalysisError } from "../domain/analysisErrorBase.js"; +import { classifyProviderFailure } from "../providers/classifyProviderFailure.js"; +import { ghidraFileDialect } from "./GhidraFileArtifacts.js"; import { HOST_PLATFORM } from "../platform/HostPlatform.js"; -import { ghidraFileFailure } from "./GhidraFileArtifacts.js"; import type { BinaryTarget } from "../domain/binaryTargetTypes.js"; import { createHash } from "node:crypto"; import { cp, lstat, mkdir, readdir, realpath } from "node:fs/promises"; @@ -44,7 +45,10 @@ const projectFileOperation = async ( return await work(); } catch (cause: unknown) { if (cause instanceof AnalysisError) throw cause; - throw ghidraFileFailure(cause, operation, { path }); + throw classifyProviderFailure( + cause, + ghidraFileDialect(operation, { path }), + ); } }; diff --git a/src/ghidra/GhidraProvider.ts b/src/ghidra/GhidraProvider.ts index 12268eb136..bfb3a45403 100644 --- a/src/ghidra/GhidraProvider.ts +++ b/src/ghidra/GhidraProvider.ts @@ -1,4 +1,5 @@ import { resolveGhidraCheckpoint } from "./GhidraCheckpoint.js"; +import { classifyProviderFailure } from "../providers/classifyProviderFailure.js"; import { HOST_PLATFORM } from "../platform/HostPlatform.js"; import { checkpointCapabilities, @@ -80,7 +81,7 @@ import { admitGhidraLanguageOverride, readGhidraLanguageCatalog, } from "./GhidraLanguageCatalog.js"; -import { ghidraFileFailure } from "./GhidraFileArtifacts.js"; +import { ghidraFileDialect } from "./GhidraFileArtifacts.js"; import { ghidraProcessorUnsupportedReason, isGhidraPspTarget, @@ -490,9 +491,12 @@ export class GhidraProvider implements AnalysisProviderCandidate { ); } catch (cause: unknown) { return err( - ghidraFileFailure(cause, "resolve_analysis_profile", { - setting: "REA_GHIDRA_LANGUAGE_ID", - }), + classifyProviderFailure( + cause, + ghidraFileDialect("resolve_analysis_profile", { + setting: "REA_GHIDRA_LANGUAGE_ID", + }), + ), ); } const refused = admitGhidraLanguageOverride( diff --git a/src/ghidra/extensions/GhidraExtensions.ts b/src/ghidra/extensions/GhidraExtensions.ts index a62c01b09a..e20c291c0e 100644 --- a/src/ghidra/extensions/GhidraExtensions.ts +++ b/src/ghidra/extensions/GhidraExtensions.ts @@ -1,4 +1,5 @@ import { GhidraAdmissionError } from "../GhidraAdmissionError.js"; +import { classifyProviderFailure } from "../../providers/classifyProviderFailure.js"; import { realpath, mkdir } from "node:fs/promises"; import { isAbsolute, join } from "node:path"; import { z } from "zod"; @@ -17,7 +18,7 @@ import { import { readGhidraProfileArtifact, writeGhidraProfileArtifact, - ghidraFileFailure, + ghidraFileDialect, } from "../GhidraFileArtifacts.js"; import type { AnalysisError } from "../../domain/analysisErrorBase.js"; import { jsonObjectSchema } from "../../domain/jsonValue.js"; @@ -125,10 +126,13 @@ export const resolveGhidraExtensions = async ( }); } catch (cause: unknown) { return err( - ghidraFileFailure(cause, "resolve_analysis_profile", { - extension: adapter.id, - path: configured, - }), + classifyProviderFailure( + cause, + ghidraFileDialect("resolve_analysis_profile", { + extension: adapter.id, + path: configured, + }), + ), ); } } @@ -136,7 +140,12 @@ export const resolveGhidraExtensions = async ( return ok(extensions); }) .catch((cause: unknown) => - err(ghidraFileFailure(cause, "resolve_analysis_profile")), + err( + classifyProviderFailure( + cause, + ghidraFileDialect("resolve_analysis_profile"), + ), + ), ); /** Require explicit local configuration before admitting executable code from a profile. */ @@ -235,7 +244,7 @@ export const snapshotGhidraExtensions = async ( return result; }) .catch((cause: unknown) => { - throw ghidraFileFailure(cause, "open_binary"); + throw classifyProviderFailure(cause, ghidraFileDialect("open_binary")); }); /** Require every configured producer result to match its artifact and registered ABI. */ diff --git a/src/hopper/BridgeLauncher.ts b/src/hopper/BridgeLauncher.ts index 90f3fa1d01..c4314e30de 100644 --- a/src/hopper/BridgeLauncher.ts +++ b/src/hopper/BridgeLauncher.ts @@ -9,7 +9,7 @@ import { HopperCancelledError, HopperProcessError, HopperStartError, -} from "../domain/hopperErrors.js"; +} from "./HopperErrors.js"; import { err, ok, type Result } from "../domain/result.js"; import { ProviderCleanupError } from "../domain/providerCleanupError.js"; import { @@ -49,7 +49,7 @@ import { import { acquireHopperTargetLease, acquireLinuxHopperApplicationLease, -} from "../process/HopperLease.js"; +} from "./HopperLease.js"; import type { OwnedLease } from "../process/OwnedLease.js"; import { MAXIMUM_BRIDGE_MAX_REQUEST_BYTES, diff --git a/src/hopper/HopperCleanup.test.ts b/src/hopper/HopperCleanup.test.ts index 7715841627..dd7dc81a67 100644 --- a/src/hopper/HopperCleanup.test.ts +++ b/src/hopper/HopperCleanup.test.ts @@ -10,7 +10,7 @@ import pino from "pino"; import { describe, expect, it, vi } from "vitest"; import { projectAnalysisError } from "../domain/analysisErrorProjection.js"; -import { HopperProcessError } from "../domain/hopperErrors.js"; +import { HopperProcessError } from "./HopperErrors.js"; import { err, ok } from "../domain/result.js"; import { observeProcessStartIdentity } from "../process/ProcessOwnershipObservation.js"; import type { BridgeLaunch } from "./BridgeLauncher.js"; diff --git a/src/hopper/HopperCleanup.ts b/src/hopper/HopperCleanup.ts index ec8ff93ac0..02e4cd4ed9 100644 --- a/src/hopper/HopperCleanup.ts +++ b/src/hopper/HopperCleanup.ts @@ -2,8 +2,7 @@ import type { Socket } from "node:net"; import type { ProgressReporter } from "../ports/ProgressReporter.js"; import type { AnalysisError } from "../domain/analysisErrorBase.js"; -import type { HopperError } from "../domain/hopperErrors.js"; -import { HopperProcessError } from "../domain/hopperErrors.js"; +import { HopperProcessError } from "./HopperErrors.js"; import type { JsonValue } from "../domain/jsonValue.js"; import { ProviderCleanupError } from "../domain/providerCleanupError.js"; @@ -75,7 +74,7 @@ export interface HopperCleanupInput { readonly onDiagnostic: ((event: HopperDiagnostic) => void) | undefined; request( method: "shutdown" | "shutdown_document", - ): Promise>; + ): Promise>; releaseTransport(socket: Socket | undefined): void; } @@ -249,7 +248,7 @@ const requestShutdown = async ( const outcome = shutdown.ok ? parseHopperShutdownReply(method, shutdown.value) : undefined; - let fallback: Result | undefined; + let fallback: Result | undefined; if ( outcome?.ok === true && outcome.value === "cleanup_required" && @@ -307,7 +306,7 @@ const requestShutdown = async ( const fallbackDocumentShutdown = async ( input: HopperCleanupInput, -): Promise> => { +): Promise> => { const fallback = await input .request("shutdown_document") .catch((cause: unknown) => @@ -349,7 +348,7 @@ const shutdownRequestFailure = ( /** Name the shutdown failure in retained-cleanup details without its cause text. */ const shutdownErrorDetails = ( - error: HopperError, + error: AnalysisError, ): Record => ({ error_tag: error._tag, ...(error instanceof HopperProcessError @@ -358,7 +357,7 @@ const shutdownErrorDetails = ( }); const shutdownFailureDetails = ( - error: HopperError, + error: AnalysisError, ): Record => ({ errorTag: error._tag, ...(error instanceof HopperProcessError && error.operation !== undefined diff --git a/src/hopper/HopperClient.ts b/src/hopper/HopperClient.ts index aee03001ba..75818ffc7c 100644 --- a/src/hopper/HopperClient.ts +++ b/src/hopper/HopperClient.ts @@ -41,13 +41,13 @@ import { HopperRemoteError, HopperStartError, HopperTimeoutError, -} from "../domain/hopperErrors.js"; +} from "./HopperErrors.js"; import type { AnalysisError } from "../domain/analysisErrorBase.js"; import { readRuntimeSetting } from "../config/runtimeAnalysisSettings.js"; import { hopperStartupFailure, type HopperStartupFailureDiagnostic, -} from "../domain/hopperStartupFailure.js"; +} from "./HopperStartupFailure.js"; import { providerRetryAction, sharedProviderFailureStage, @@ -109,6 +109,7 @@ import { import { HopperRequestQueue, type HopperRequestActivity, + type HopperRequestFailure, } from "./HopperRequestQueue.js"; import { type HopperBridgeEvent, @@ -1479,7 +1480,7 @@ export class HopperClient< this.#socket?.destroy(); } - #failAll(error: HopperError): void { + #failAll(error: HopperRequestFailure): void { this.#requests.failAll(error); } @@ -1496,7 +1497,7 @@ export class HopperClient< } #retainRequestHealth( - result: Result, + result: Result, requestId: number, operation: string, ): void { diff --git a/src/hopper/HopperDiagnostics.ts b/src/hopper/HopperDiagnostics.ts index b40e607d38..2c3ff21648 100644 --- a/src/hopper/HopperDiagnostics.ts +++ b/src/hopper/HopperDiagnostics.ts @@ -1,4 +1,4 @@ -import type { HopperDiagnosticType } from "../domain/hopperErrors.js"; +import type { HopperDiagnosticType } from "./HopperErrors.js"; import type { ProcessCleanupResult } from "../process/ProcessOwnership.js"; import type { ProviderProcessLaunch, diff --git a/src/hopper/HopperErrorProjection.test.ts b/src/hopper/HopperErrorProjection.test.ts new file mode 100644 index 0000000000..c324ed0c7e --- /dev/null +++ b/src/hopper/HopperErrorProjection.test.ts @@ -0,0 +1,566 @@ +import { releaseOwnedCleanup } from "../../tests/support/cleanupRelease.js"; +import { MAX_NODE_TIMER_DELAY_MS } from "../domain/analysisResourceLimits.js"; +import { describe, expect, it } from "vitest"; +import { AnalysisOutputError } from "../domain/analysisErrorCore.js"; +import { + HOPPER_STARTUP_TIMEOUT_REMEDIATION, + HopperProcessError, + HopperRemoteError, + HopperStartError, + HopperTimeoutError, + HopperCancelledError, + HopperProtocolError, + hopperErrorCatalogue, +} from "./HopperErrors.js"; +import { + DEFAULT_HOPPER_DEMO_DIALOG_TIMEOUT_MS, + HOPPER_DEMO_DIALOG_TIMEOUT_SETTING, + MINIMUM_HOPPER_DEMO_DIALOG_TIMEOUT_MS, + type DialogTimeoutRejection, + type HopperStartupFailureDiagnostic, +} from "./HopperStartupFailure.js"; +import { ProviderAdapterError } from "../domain/providerAdapterError.js"; +import { projectAnalysisError } from "../domain/analysisErrorProjection.js"; +import { + analysisErrorRemediationAction, + analysisErrorUserMessage, +} from "../domain/analysisErrorPresentation.js"; +import { analysisErrorProjectionSchema } from "../domain/analysisErrorProjectionSchema.js"; +import { analysisSettingLimit } from "../domain/analysisSettingDefinitions.js"; +import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js"; +import { ProviderCleanupError } from "../domain/providerCleanupError.js"; + +describe("analysis error projection: Hopper provider failures", () => { + it("reports a timed-out active Hopper request and actionable retry guidance", () => { + const projected = projectAnalysisError( + new HopperTimeoutError(30_000, "trace_feature", 42, "busy"), + ); + + expect(projected).toMatchObject({ + code: "provider_timeout", + category: "timeout", + retryable: true, + details: { + stage: "analysis", + operation: "trace_feature", + request_id: 42, + provider_state: "busy", + timeout_ms: 30_000, + }, + }); + expect(projected.message).toContain("binary_session.analysis_activity"); + expect(projected.remediation.action).toContain( + "wait for the active Hopper request", + ); + }); + + it("identifies the REA session that already owns a Hopper target", () => { + const error = new HopperStartError({ + ownerRunId: "session-owner", + userMessage: + "This Hopper target is already open in REA session session-owner. Use that REA session or close it before opening this target again.", + }); + expect(projectAnalysisError(error)).toMatchObject({ + category: "unavailable", + message: expect.stringContaining("session-owner"), + remediation: { + action: expect.stringContaining( + "Use the active REA session session-owner", + ), + }, + }); + }); + + it("projects an Apple Events denial as unavailable and not retryable from the same client", () => { + const projected = projectAnalysisError( + new HopperStartError({ + launchRejection: { + boundary: "apple_events_authorization", + reason: "not_authorized", + }, + launcherFailure: { + exit_code: 2, + signal: null, + stdout: { text: "", bytes: 0, retained_bytes: 0 }, + stderr: { + text: "Cannot launch Hopper!\nNot authorized to send Apple events to Hopper Disassembler.\n", + bytes: 90, + retained_bytes: 90, + }, + output_closed: true, + diagnostic_truncated: false, + }, + }), + ); + expect(projected).toMatchObject({ + code: "provider_unavailable", + category: "unavailable", + retryable: false, + details: { + stage: "launch", + provider_state: "unknown", + retry_action: "unknown", + launch_rejection: { + boundary: "apple_events_authorization", + reason: "not_authorized", + }, + launcher: { exit_code: 2, signal: null }, + }, + }); + expect(analysisErrorProjectionSchema.parse(projected)).toEqual(projected); + }); + + it("keeps an ordinary Hopper start failure retryable", () => { + const projected = projectAnalysisError( + new HopperStartError({ + userMessage: "Hopper's launcher helper failed before bridge readiness.", + }), + ); + expect(projected).toMatchObject({ + code: "provider_unavailable", + category: "unavailable", + retryable: true, + details: { + stage: "launch", + provider_state: "unknown", + retry_action: "retry", + }, + }); + expect(projected.details).not.toHaveProperty("launch_rejection"); + }); + + it("retains the Hopper request and provider diagnostic on a remote failure", () => { + expect( + projectAnalysisError( + new HopperRemoteError( + 7, + "Hopper analysis failed in the selected document", + { + diagnosticType: "bridge_exception", + operation: "trace_feature", + requestId: 43, + }, + ), + ), + ).toMatchObject({ + code: "execution_failure", + details: { + stage: "analysis", + provider_code: 7, + diagnostic_type: "bridge_exception", + operation: "trace_feature", + request_id: 43, + }, + message: expect.stringContaining("Hopper analysis failed"), + }); + }); +}); + +describe("analysis error projection: Hopper startup failures", () => { + it("maps the Linux startup compatibility exit codes without host internals", () => { + const expected = [ + [70, "private_display_unavailable"], + [71, "x11_authorization_failed"], + [72, "unsupported_hopper_build"], + [73, "invalid_launch_command"], + [74, "process_ownership_mismatch"], + [75, "hopper_exited_during_startup"], + [76, "unsupported_demo_dialog"], + [77, "unexpected_display_geometry"], + [78, "x11_input_failed"], + [79, "runtime_dependency_unavailable"], + [80, "x11_socket_directory_unusable"], + [81, "demo_dialog_absent"], + [82, "invalid_dialog_timeout"], + ] as const; + + for (const [exitCode, code] of expected) { + const projected = projectAnalysisError(new HopperProcessError(exitCode)); + expect(projected).toMatchObject({ + code: "provider_unavailable", + details: { failure_code: code, exit_code: exitCode }, + }); + expect(projected.details).not.toHaveProperty("launch_rejection"); + expect(projected.message).toMatch(/\S/u); + expect(JSON.stringify(projected)).not.toContain("/proc/"); + } + }); + + it("does not attribute an absent post-authentication dialog to publisher verification", () => { + const projected = projectAnalysisError(new HopperProcessError(81)); + expect(projected).toMatchObject({ + code: "provider_unavailable", + details: { + stage: "launch", + failure_code: "demo_dialog_absent", + exit_code: 81, + }, + }); + expect(projected.details).not.toHaveProperty("launch_rejection"); + expect(projected.message).toContain("REA_HOPPER_DEMO_DIALOG_TIMEOUT_MS"); + }); + + it("reports a rejected demo dialog timeout through its setting fields", () => { + const dialogTimeout = { + setting: HOPPER_DEMO_DIALOG_TIMEOUT_SETTING, + value: "-5", + source: "setting", + minimum_ms: MINIMUM_HOPPER_DEMO_DIALOG_TIMEOUT_MS, + maximum_ms: MAX_NODE_TIMER_DELAY_MS, + default_ms: DEFAULT_HOPPER_DEMO_DIALOG_TIMEOUT_MS, + } satisfies DialogTimeoutRejection; + const projected = projectAnalysisError( + new HopperProcessError(82, { + diagnostic: { + component: "hopper_private_display", + operation: "launch", + reason: "invalid_dialog_timeout", + socket_directory: "/tmp/.X11-unix", + socket_directory_mode: null, + mount_read_only: null, + effective_socket_directory_mode: null, + effective_mount_read_only: null, + wsl: false, + strategy: "direct", + fallback_reason: null, + xvfb_stderr_bytes: 0, + status: "error", + failure_code: "invalid_dialog_timeout", + dialog_timeout: dialogTimeout, + } as HopperStartupFailureDiagnostic, + }), + ); + expect(projected).toMatchObject({ + code: "provider_unavailable", + details: { + stage: "launch", + failure_code: "invalid_dialog_timeout", + exit_code: 82, + diagnostics: { dialog_timeout: dialogTimeout }, + }, + }); + expect(projected.details).not.toHaveProperty("launch_rejection"); + expect(analysisErrorProjectionSchema.safeParse(projected).success).toBe( + true, + ); + }); +}); + +describe("analysis error projection: retry guidance", () => { + it.each([ + [ + "unreadable output", + new AnalysisOutputError("inspect_firmware_regions", "report missing"), + "unreadable_output", + ], + [ + "adapter failure", + new ProviderAdapterError("firmware", "inspect_firmware_regions"), + "execution_failure", + ], + [ + "Hopper remote failure", + new HopperRemoteError(7, "Hopper analysis failed", { + diagnosticType: "bridge_exception", + operation: "trace_feature", + }), + "execution_failure", + ], + ])( + "does not recommend an unchanged retry for non-retryable %s", + (_name, error, code) => { + const projected = projectAnalysisError(error); + + expect(projected).toMatchObject({ code, retryable: false }); + for (const text of [projected.message, projected.remediation.action]) + expect(text).not.toMatch(/\bretry\b/iu); + }, + ); +}); + +describe("analysis error projection: operational diagnostics", () => { + it("distinguishes an observed Hopper exit from an undetermined provider failure", () => { + const exitedError = new HopperProcessError(7, { + operation: "search_strings", + requestId: 4, + }); + const exited = projectAnalysisError(exitedError); + expect(exited).toMatchObject({ + code: "provider_unavailable", + retryable: true, + details: { + stage: "analysis", + provider_state: "exited", + retry_action: "restart_provider", + operation: "search_strings", + request_id: 4, + exit_code: 7, + }, + }); + expect(exited.message).toBe(analysisErrorUserMessage(exitedError)); + expect(exited.remediation.action).toBe( + analysisErrorRemediationAction(exitedError), + ); + expect(exited.message).toMatch( + /Hopper exited.*search_strings.*exit code 7/iu, + ); + expect(exited.remediation.action).toMatch(/close_binary.*open.*retry/iu); + + const unknownError = new HopperProcessError(null, { + operation: "search_strings", + requestId: 5, + }); + const unknown = projectAnalysisError(unknownError); + expect(unknown.details).toMatchObject({ + stage: "analysis", + provider_state: "unknown", + retry_action: "unknown", + operation: "search_strings", + request_id: 5, + exit_code: null, + }); + expect(unknown.message).toBe(analysisErrorUserMessage(unknownError)); + expect(unknown.remediation.action).toBe( + analysisErrorRemediationAction(unknownError), + ); + expect(unknown.message).toMatch( + /could not determine.*busy, exited, or unreachable/iu, + ); + expect(unknown.remediation.action).toMatch( + /provider_operation_health.*before retrying or restarting/iu, + ); + + const unreachableError = new HopperProcessError(null, { + operation: "search_strings", + providerState: "unreachable", + }); + const unreachable = projectAnalysisError(unreachableError); + expect(unreachable).toMatchObject({ + code: "provider_unavailable", + details: { + provider_state: "unreachable", + retry_action: "restart_provider", + operation: "search_strings", + exit_code: null, + }, + message: analysisErrorUserMessage(unreachableError), + remediation: { action: analysisErrorRemediationAction(unreachableError) }, + }); + expect(unreachable.message).toMatch( + /unreachable.*process exit was not observed/iu, + ); + expect(unreachable.remediation.action).toMatch( + /close_binary.*Evidence and Unknown history.*export_evidence_bundle/iu, + ); + }); +}); + +it("retains Hopper startup diagnostics beside generic and secondary context", () => { + const diagnostic = { + component: "hopper_private_display", + operation: "launch", + reason: "fixture_denial", + socket_directory: "/tmp/.X11-unix", + socket_directory_mode: null, + mount_read_only: null, + effective_socket_directory_mode: null, + effective_mount_read_only: null, + wsl: false, + strategy: "unavailable", + fallback_reason: null, + xvfb_stderr_bytes: 0, + status: "error", + failure_code: "private_display_unavailable", + } as const; + expect( + projectAnalysisError(new HopperProcessError(null, { diagnostic })).details + ?.diagnostics, + ).toEqual(diagnostic); + const generic = { caller_context: "retained" }; + expect( + projectAnalysisError( + new HopperProcessError(null, { diagnostic, diagnostics: generic }), + ), + ).toMatchObject({ + code: "provider_unavailable", + details: { diagnostics: generic, provider_diagnostics: diagnostic }, + }); + const secondary = new HopperProcessError(null, { + diagnostic, + }).retainSecondaryFailure(new HopperProcessError(null), { + retirement_error: "retained", + }); + expect(projectAnalysisError(secondary).details).toMatchObject({ + provider_diagnostics: diagnostic, + diagnostics: { retirement_error: "retained" }, + }); +}); + +describe("analysis error projection: caller lifetime", () => { + it("delivers each lifetime's Hopper startup recovery", () => { + const error = new HopperTimeoutError( + 30_000, + undefined, + undefined, + "not_started", + "launch", + undefined, + { + limit: analysisSettingLimit( + "hopper.startup_timeout_ms", + 30_000, + undefined, + ), + }, + ); + expect(projectAnalysisError(error).remediation.action).toMatch( + /update_analysis_settings.*hopper\.startup_timeout_ms.*without restarting REA/u, + ); + const invocation = projectAnalysisError(error, "invocation"); + expect(invocation.remediation.action).toBe( + HOPPER_STARTUP_TIMEOUT_REMEDIATION, + ); + expect(invocation.details?.limit).toMatchObject({ + setting: "hopper.startup_timeout_ms", + effective_value: 30_000, + scope: "rea-invocation", + applies_at: "next_invocation", + environment: "REA_HOPPER_STARTUP_TIMEOUT_MS", + }); + }); +}); + +describe("analysis error projection: Hopper caller lifetime", () => { + it.each([ + [ + new HopperProcessError(7, { operation: "search_strings", requestId: 4 }), + "close_binary", + "exit code 7", + ], + [ + new HopperProcessError(null, { + operation: "search_strings", + providerState: "unreachable", + }), + "export_evidence_bundle", + "process exit was not observed", + ], + [ + new HopperProcessError(null, { operation: "search_strings" }), + "binary_session.provider_operation_health", + "could not determine", + ], + [ + new HopperTimeoutError(30_000, "search_strings", 42, "busy"), + "binary_session.analysis_activity", + "remained busy", + ], + [ + new HopperTimeoutError(30_000, "search_strings", 42, "not_started"), + "binary_session", + "before it started", + ], + ] as const)( + "keeps Hopper outcome facts and scopes request recovery to the caller", + (error, continuingTool, outcome) => { + const continuing = projectAnalysisError(error); + const invocation = projectAnalysisError(error, "invocation"); + expect(continuing.message).toContain(continuingTool); + expect(continuing.remediation.action).toContain(continuingTool); + expect(invocation.message).toContain(outcome); + expect(invocation.message).not.toContain(continuingTool); + expect(invocation.remediation.action).toContain("rerunning the command"); + expect(invocation.remediation.action).not.toContain(continuingTool); + expect(invocation.details).toEqual(continuing.details); + expect(invocation.code).toBe(continuing.code); + expect(invocation.category).toBe(continuing.category); + expect(invocation.retryable).toBe(continuing.retryable); + expect(analysisErrorProjectionSchema.parse(invocation)).toEqual( + invocation, + ); + }, + ); + + it("keeps Hopper recovery scoped through composed cleanup and its history", () => { + const primary = new HopperProcessError(null, { + operation: "search_strings", + providerState: "unreachable", + }); + const cleanup = new ProviderCleanupError("hopper", ["hopper-bridge"], {}); + const composed = analysisErrorWithCleanupFailure( + primary, + cleanup, + ).bindCleanupDependencies([cleanup]); + const invocationPrimary = projectAnalysisError(primary, "invocation"); + const continuingPrimary = projectAnalysisError(primary); + const invocation = projectAnalysisError(composed, "invocation"); + const continuing = projectAnalysisError(composed); + expect(invocation.message).toBe(invocationPrimary.message); + expect(continuing.message).toBe(continuingPrimary.message); + expect(invocation.details).toMatchObject({ + resources: ["hopper-bridge"], + diagnostics: { primary_error: invocationPrimary }, + }); + expect(continuing.details).toMatchObject({ + diagnostics: { primary_error: continuingPrimary }, + }); + + releaseOwnedCleanup(cleanup); + expect( + projectAnalysisError(composed, "invocation").details?.cleanup_history, + ).toMatchObject({ primary_error: invocationPrimary }); + expect( + projectAnalysisError(composed).details?.cleanup_history, + ).toMatchObject({ primary_error: continuingPrimary }); + }); +}); + +describe("Hopper error catalogue", () => { + it.each([ + ["", new HopperTimeoutError(30_000, "search_strings", 1, "busy")], + ["", new HopperCancelledError()], + ["", new HopperProtocolError("bad reply")], + ...( + [ + "remote", + "authorization", + "invalid_request", + "capability_unavailable", + "bridge_exception", + ] as const + ).map( + (diagnosticType) => + [ + `diagnostic_type=${diagnosticType}`, + new HopperRemoteError(7, "failed", { diagnosticType }), + ] as const, + ), + ["", new HopperProcessError(7, { operation: "search_strings" })], + ["", new HopperStartError()], + [ + "Apple Events authorization denied", + new HopperStartError({ + launchRejection: { + boundary: "apple_events_authorization", + reason: "not_authorized", + }, + }), + ], + ] as const)( + "lists the projected code, category and retryability (%s)", + (discriminant, error) => { + const projected = projectAnalysisError(error); + expect( + hopperErrorCatalogue().find( + (row) => row.tag === error._tag && row.discriminant === discriminant, + ), + ).toEqual({ + tag: error._tag, + discriminant, + code: projected.code, + category: projected.category, + retryableByDefault: projected.retryable, + }); + }, + ); +}); diff --git a/src/domain/hopperErrors.test.ts b/src/hopper/HopperErrors.test.ts similarity index 55% rename from src/domain/hopperErrors.test.ts rename to src/hopper/HopperErrors.test.ts index a955843027..22d81e14cd 100644 --- a/src/domain/hopperErrors.test.ts +++ b/src/hopper/HopperErrors.test.ts @@ -1,6 +1,13 @@ import { expect, it } from "vitest"; -import { HopperCancelledError } from "./hopperErrors.js"; +import { + HopperCancelledError, + HopperProcessError, + HopperProtocolError, + HopperRemoteError, + HopperStartError, + HopperTimeoutError, +} from "./HopperErrors.js"; it("omits a cause when the caller does not supply one", () => { const error = new HopperCancelledError(); @@ -26,3 +33,12 @@ it("retains an opaque caller reason by identity", () => { expect(error.cause).toBe(reason); }); + +it("reports a stopped or unstartable bridge as a provider-wide failure", () => { + expect(new HopperProcessError(1).providerWide).toBe(true); + expect(new HopperStartError().providerWide).toBe(true); + expect(new HopperRemoteError(2, "bad address").providerWide).toBe(false); + expect(new HopperTimeoutError(10, "decompile").providerWide).toBe(false); + expect(new HopperProtocolError("malformed").providerWide).toBe(false); + expect(new HopperCancelledError().providerWide).toBe(false); +}); diff --git a/src/hopper/HopperErrors.ts b/src/hopper/HopperErrors.ts new file mode 100644 index 0000000000..55ded31a8f --- /dev/null +++ b/src/hopper/HopperErrors.ts @@ -0,0 +1,615 @@ +import { + ProviderOwnedAnalysisError, + providerErrorTag, + type AnalysisContinuingCallerGuidance, + type AnalysisErrorOptions, + type AnalysisErrorOwnPresentation, + type ProviderRequestFailure, +} from "../domain/analysisErrorBase.js"; +import { + catalogueRow, + type AnalysisErrorCatalogueEntry, + type AnalysisErrorClassification, +} from "../domain/analysisErrorClassification.js"; +import type { JsonValue } from "../domain/jsonValue.js"; +import { + providerRetryAction, + type HopperProcessProviderState, + type ProviderFailureStage, +} from "../domain/providerOperationHealth.js"; +import { + dialogTimeoutFromDiagnostic, + hopperStartupFailure, + invalidDialogTimeoutMessage, + type HopperStartupFailureCode, + type HopperStartupFailureDiagnostic, +} from "./HopperStartupFailure.js"; + +/** Hopper's caller-facing code and category; presentations and the catalogue read it. */ +const HOPPER_CLASSIFICATIONS = { + timeout: { code: "provider_timeout", category: "timeout" }, + cancelled: { code: "cancelled", category: "cancelled" }, + protocol: { code: "unreadable_output", category: "execution_failure" }, + unavailable: { code: "provider_unavailable", category: "unavailable" }, +} as const satisfies Record; + +/** A remote error's classification follows the bridge's diagnostic type. */ +const hopperRemoteClassification = ( + diagnosticType: HopperDiagnosticType, +): AnalysisErrorClassification => + diagnosticType === "invalid_request" + ? { code: "invalid_request", category: "invalid_input" } + : { + code: "execution_failure", + category: + diagnosticType === "authorization" + ? "unavailable" + : "execution_failure", + }; + +/** Base class for failures produced specifically by the Hopper provider. */ +export abstract class HopperError extends ProviderOwnedAnalysisError {} + +/** The Hopper request a failure answered, as recorded by the client. */ +const hopperRequestFacts = ( + operation: string | undefined, + requestId: number | undefined, +): Readonly> => ({ + ...(operation === undefined ? {} : { operation }), + ...(requestId === undefined ? {} : { request_id: requestId }), +}); + +/** Observed launcher outcome; a helper exit does not establish GUI lifetime. */ +export type HopperLauncherOutcome = { + readonly exit_code: number | null; + readonly signal: string | null; + /** Total bytes drained from the stream; retained_bytes reports captured bytes. */ + readonly stdout: { + readonly text: string; + readonly bytes: number; + readonly retained_bytes: number; + }; + readonly stderr: { + readonly text: string; + readonly bytes: number; + readonly retained_bytes: number; + }; + readonly output_closed: boolean; + readonly diagnostic_truncated: boolean; +}; + +/** Startup-timeout recovery that holds after the calling invocation has ended. */ +export const HOPPER_STARTUP_TIMEOUT_REMEDIATION = + "Review details.launcher and inspect Hopper for ongoing initial analysis or a pending loader, demo, or license dialog. For a large target, set REA_HOPPER_STARTUP_TIMEOUT_MS higher in the environment of a new REA invocation, then rerun the command; that invocation starts Hopper again. Resolve retained cleanup before rerunning."; + +/** Startup-timeout recovery for a caller whose REA runtime keeps running. */ +const HOPPER_STARTUP_TIMEOUT_CONTINUING_REMEDIATION = + "Review details.launcher and inspect Hopper for ongoing initial analysis or a pending loader, demo, or license dialog. For a large target, use update_analysis_settings with setting hopper.startup_timeout_ms and action set for the next startup attempt without restarting REA, or increase REA_HOPPER_STARTUP_TIMEOUT_MS for future REA processes. Allow at least that long in the MCP client. Resolve retained cleanup before reopening."; + +/** Hopper did not respond within the configured operation deadline. */ +const RESTART_OWNED_PROVIDER = + "Restart the owned provider by calling close_binary, then open the target again and retry."; +const RESTART_UNREACHABLE_HOPPER = `${RESTART_OWNED_PROVIDER} close_binary preserves retained Evidence and Unknown history on this connection; export_evidence_bundle before ending the REA process if you need to resume later.`; +const RERUN_HOPPER_INVOCATION = + "Review the reported Hopper state and resolve any incomplete cleanup before rerunning the command."; + +const HOPPER_APPLE_EVENTS_AUTHORIZATION_MESSAGE = + "macOS denied permission to send Apple Events to Hopper. A hardened-runtime application starting REA requires the com.apple.security.automation.apple-events entitlement before macOS will prompt for permission."; + +const HOPPER_APPLE_EVENTS_AUTHORIZATION_REMEDIATION = + "Allow the application that starts REA under System Settings > Privacy & Security > Automation. If the client lacks the com.apple.security.automation.apple-events entitlement, ask the client developer to add it or start REA from a client macOS can authorize, such as Terminal. Retrying from the same unauthorized client will not succeed until authorization changes."; + +export class HopperTimeoutError extends HopperError { + readonly _tag = providerErrorTag("HopperTimeoutError"); + + constructor( + readonly timeoutMs: number, + readonly operation?: string, + readonly requestId?: number, + readonly providerState: "busy" | "not_started" = "not_started", + readonly stage: ProviderFailureStage = operation === undefined + ? "launch" + : "analysis", + readonly launcherOutcome?: HopperLauncherOutcome, + options: AnalysisErrorOptions = {}, + ) { + super( + `Hopper ${operation === undefined ? "startup" : operation} timed out after ${String(timeoutMs)}ms`, + operation === undefined + ? { + ...options, + continuingCallerGuidance: { + remediationAction: HOPPER_STARTUP_TIMEOUT_CONTINUING_REMEDIATION, + }, + } + : options, + ); + } + + override providerRequest(): ProviderRequestFailure { + return { + facts: hopperRequestFacts(this.operation, this.requestId), + reattribute: (operation, options) => + new HopperTimeoutError( + this.timeoutMs, + operation, + this.requestId, + this.providerState, + this.stage, + this.launcherOutcome, + options, + ), + }; + } + + override ownPresentation(): AnalysisErrorOwnPresentation { + const { operation } = this; + const continuing = + operation === undefined + ? undefined + : this.providerState === "busy" + ? "Check binary_session.analysis_activity, wait for the active Hopper request to finish, then retry." + : "Check binary_session for Hopper health, then retry the operation."; + return { + ...HOPPER_CLASSIFICATIONS.timeout, + message: + operation === undefined + ? "REA timed out waiting for Hopper bridge readiness, which includes initial analysis. Hopper may still be analyzing the target or waiting for a loader, demo, or license dialog. Review the captured launcher outcome and resolve retained cleanup before retrying." + : this.providerState === "busy" + ? `Hopper timed out during ${operation} while the provider remained busy.` + : `Hopper timed out during ${operation} before it started.`, + ...(continuing === undefined + ? {} + : { + continuing: { + userMessage: continuing, + remediationAction: continuing, + }, + }), + remediation: + operation === undefined + ? HOPPER_STARTUP_TIMEOUT_REMEDIATION + : RERUN_HOPPER_INVOCATION, + details: { + stage: operation === undefined ? "startup" : this.stage, + timeout_ms: this.timeoutMs, + ...(this.launcherOutcome === undefined + ? {} + : { launcher: this.launcherOutcome }), + provider_state: this.providerState, + retry_action: this.providerState === "busy" ? "wait" : "retry", + ...(operation === undefined ? {} : { operation }), + ...(this.requestId === undefined ? {} : { request_id: this.requestId }), + }, + }; + } +} + +/** The caller cancelled a Hopper operation before it completed. */ +export class HopperCancelledError extends HopperError { + readonly _tag = providerErrorTag("HopperCancelledError"); + + constructor( + ...parameters: + | readonly [] + | readonly [cause: unknown] + | readonly [cause: unknown, options: Omit] + ) { + const errorOptions: AnalysisErrorOptions = { ...parameters[1] }; + // Argument presence matters: an explicit undefined is the caller's reason. + if (parameters.length > 0) + Object.defineProperty(errorOptions, "cause", { + configurable: true, + enumerable: true, + value: parameters[0], + writable: true, + }); + super("Hopper operation was cancelled", errorOptions); + } + + override ownPresentation(): AnalysisErrorOwnPresentation { + return { + ...HOPPER_CLASSIFICATIONS.cancelled, + details: { operation: "hopper", cleanup: "complete" }, + }; + } +} + +/** + * Classify caller cancellation from a signal. + * + * An aborted signal keeps its exact reason, including undefined. A signal that + * has not aborted does not invent a reason. + */ +export const hopperCancelledBySignal = ( + signal: AbortSignal | undefined, +): HopperCancelledError => + signal?.aborted === true + ? new HopperCancelledError(signal.reason) + : new HopperCancelledError(); + +/** Hopper returned bytes or JSON that do not satisfy the NDJSON RPC contract. */ +export class HopperProtocolError extends HopperError { + readonly _tag = providerErrorTag("HopperProtocolError"); + + override ownPresentation(): AnalysisErrorOwnPresentation { + return HOPPER_CLASSIFICATIONS.protocol; + } +} + +export type HopperDiagnosticType = + | "remote" + | "authorization" + | "invalid_request" + | "capability_unavailable" + | "bridge_exception"; + +/** Hopper's JSON-RPC endpoint returned an expected remote error response. */ +export interface HopperRemoteErrorContext extends AnalysisErrorOptions { + readonly diagnosticType?: HopperDiagnosticType | undefined; + readonly operation?: string | undefined; + readonly requestId?: number | undefined; +} + +export class HopperRemoteError extends HopperError { + readonly _tag = providerErrorTag("HopperRemoteError"); + readonly diagnosticType: HopperDiagnosticType; + readonly operation: string | undefined; + readonly requestId: number | undefined; + + constructor( + readonly code: number, + readonly safeMessage: string, + context: HopperRemoteErrorContext = {}, + ) { + super(`Hopper request failed (${String(code)}): ${safeMessage}`, context); + this.diagnosticType = context.diagnosticType ?? "remote"; + this.operation = context.operation; + this.requestId = context.requestId; + } + + override providerRequest(): ProviderRequestFailure { + return { + facts: { + ...hopperRequestFacts(this.operation, this.requestId), + provider_code: this.code, + diagnostic_type: this.diagnosticType, + }, + reattribute: (operation, options) => + new HopperRemoteError(this.code, this.safeMessage, { + ...options, + operation, + requestId: this.requestId, + diagnosticType: this.diagnosticType, + }), + }; + } + + override ownPresentation(): AnalysisErrorOwnPresentation { + return { + ...hopperRemoteClassification(this.diagnosticType), + message: `Hopper ${this.operation ?? "analysis"} failed (${String(this.code)}, ${this.diagnosticType}): ${this.safeMessage}`, + remediation: + this.diagnosticType === "invalid_request" + ? "Correct the reported address, document, or arguments and retry." + : "Review the Hopper diagnostic details and correct the request or target; run `rea doctor` if the provider itself is failing. Repeating the unchanged request is not expected to succeed.", + details: { + stage: "analysis", + provider_code: this.code, + diagnostic_type: this.diagnosticType, + ...(this.operation === undefined ? {} : { operation: this.operation }), + ...(this.requestId === undefined ? {} : { request_id: this.requestId }), + }, + }; + } +} + +/** The owned Hopper bridge stopped before its client was closed. */ +export interface HopperProcessErrorContext extends AnalysisErrorOptions { + readonly diagnostic?: HopperStartupFailureDiagnostic | undefined; + readonly operation?: string | undefined; + readonly requestId?: number | undefined; + readonly providerState?: HopperProcessProviderState | undefined; + readonly stage?: ProviderFailureStage | undefined; + readonly launcherFailure?: HopperLauncherOutcome | undefined; +} + +export class HopperProcessError extends HopperError { + readonly _tag = providerErrorTag("HopperProcessError"); + readonly failureCode: HopperStartupFailureCode | undefined; + override readonly userMessage: string | undefined; + readonly providerState: HopperProcessProviderState; + readonly stage: ProviderFailureStage; + readonly diagnostic: HopperStartupFailureDiagnostic | undefined; + readonly operation: string | undefined; + readonly requestId: number | undefined; + readonly launcherFailure: HopperLauncherOutcome | undefined; + + constructor( + readonly exitCode: number | null, + context: HopperProcessErrorContext = {}, + ) { + super( + `Hopper bridge stopped unexpectedly with code ${String(exitCode)}`, + context, + ); + this.diagnostic = context.diagnostic; + this.operation = context.operation; + this.requestId = context.requestId; + this.launcherFailure = context.launcherFailure; + const failure = hopperStartupFailure(exitCode); + this.userMessage = + failure?.code === "invalid_dialog_timeout" + ? invalidDialogTimeoutMessage( + dialogTimeoutFromDiagnostic(context.diagnostic), + ) + : failure?.message; + this.stage = + context.stage ?? + (failure === undefined + ? context.operation === undefined + ? "connection" + : "analysis" + : "launch"); + this.failureCode = failure?.code; + this.providerState = + context.providerState ?? (exitCode === null ? "unknown" : "exited"); + } + + override get providerWide(): boolean { + return true; + } + + override providerRequest(): ProviderRequestFailure { + return { + facts: hopperRequestFacts(this.operation, this.requestId), + reattribute: (operation, options) => + new HopperProcessError(this.exitCode, { + ...options, + operation, + requestId: this.requestId, + providerState: this.providerState, + stage: this.stage, + ...(this.diagnostic === undefined + ? {} + : { diagnostic: this.diagnostic }), + ...(this.launcherFailure === undefined + ? {} + : { launcherFailure: this.launcherFailure }), + }), + }; + } + + override ownPresentation(): AnalysisErrorOwnPresentation { + const continuing = this.#continuing(); + return { + ...HOPPER_CLASSIFICATIONS.unavailable, + message: this.#message(), + ...(continuing === undefined ? {} : { continuing }), + remediation: + this.failureCode !== undefined && this.userMessage !== undefined + ? this.userMessage + : this.stage === "launch" + ? "Review the captured launcher diagnostics and Hopper setup, then retry opening the target." + : RERUN_HOPPER_INVOCATION, + details: { + exit_code: this.exitCode, + stage: this.stage, + provider_state: this.providerState, + retry_action: providerRetryAction( + this.providerState, + this.failureCode !== undefined || this.stage === "launch", + ), + ...(this.failureCode === undefined + ? {} + : { failure_code: this.failureCode }), + ...(this.operation === undefined ? {} : { operation: this.operation }), + ...(this.requestId === undefined ? {} : { request_id: this.requestId }), + ...(this.diagnostic === undefined + ? {} + : { diagnostics: { ...this.diagnostic } }), + ...(this.launcherFailure === undefined + ? {} + : { launcher: this.launcherFailure }), + }, + }; + } + + #message(): string { + const where = this.operation ?? this.stage; + const request = + this.requestId === undefined + ? "" + : ` Request id ${String(this.requestId)}.`; + const startup = + this.userMessage === undefined ? "" : ` ${this.userMessage}`; + if (this.providerState === "exited") { + const signal = this.launcherFailure?.signal; + const exit = + this.exitCode === null + ? signal === undefined || signal === null + ? "no exit code was observed" + : `signal ${signal}` + : `exit code ${String(this.exitCode)}`; + return `Hopper exited during ${where} (${exit}).${startup}${request}`; + } + if (this.providerState === "unreachable") + return `Hopper became unreachable during ${where}; its process exit was not observed.${startup}${request}`; + return `Hopper failed during ${where} and REA could not determine whether the provider is busy, exited, or unreachable.${startup}${request}`; + } + + #continuing(): AnalysisContinuingCallerGuidance | undefined { + if ( + this.providerState === "exited" && + (this.stage === "launch" || this.failureCode !== undefined) + ) + return undefined; + const action = + this.providerState === "unreachable" + ? RESTART_UNREACHABLE_HOPPER + : providerRetryAction(this.providerState) === "restart_provider" + ? RESTART_OWNED_PROVIDER + : "Read binary_session.provider_operation_health for this request before retrying or restarting the owned provider."; + return { + userMessage: action, + ...(this.stage === "launch" || + (this.failureCode !== undefined && this.userMessage !== undefined) + ? {} + : { remediationAction: action }), + }; + } +} + +/** + * Parsed facts about a Hopper launch refused before the target runs. + * Publisher and argument failures are decided before the launcher executes. + * Apple Events authorization is decided after the native helper starts and + * before document handoff. + */ +export type HopperLaunchRejection = + | { + /** The selected application was rejected before it was executed. */ + readonly boundary: "publisher_verification"; + /** Parsed failure reason supplied by the verification owner. */ + readonly reason: string; + } + | ({ + readonly boundary: "argument_encoding"; + readonly reason: "applescript_literal"; + } & ( + | { readonly source: "launcher_path" } + | { + readonly source: "argument"; + /** Zero-based index in the final vendor argv, excluding the executable. */ + readonly argument_index: number; + } + )) + | { + /** + * macOS refused the launcher's Apple Event. The helper's stderr does not + * show whether the responsible client lacks an Automation grant or the + * hardened-runtime Apple Events entitlement. Another launch from that + * same client cannot succeed until authorization changes. + */ + readonly boundary: "apple_events_authorization"; + readonly reason: "not_authorized"; + }; + +/** Recognize the Apple Events refusal that the same client cannot retry. */ +export const hopperAppleEventsAuthorizationDenied = ( + rejection: HopperLaunchRejection | undefined, +): rejection is Extract< + HopperLaunchRejection, + { readonly boundary: "apple_events_authorization" } +> => rejection?.boundary === "apple_events_authorization"; + +/** Hopper or the repository bridge could not be started. */ +export class HopperStartError extends HopperError { + readonly _tag = providerErrorTag("HopperStartError"); + override readonly userMessage: string | undefined; + readonly ownerRunId: string | undefined; + readonly launcherFailure: HopperLauncherOutcome | undefined; + readonly launchRejection: HopperLaunchRejection | undefined; + + constructor( + options?: AnalysisErrorOptions & { + readonly userMessage?: string; + readonly ownerRunId?: string; + readonly launcherFailure?: HopperLauncherOutcome; + readonly launchRejection?: HopperLaunchRejection; + }, + ) { + super("Hopper application bridge could not be started", options); + this.userMessage = options?.userMessage; + this.ownerRunId = options?.ownerRunId; + this.launcherFailure = options?.launcherFailure; + this.launchRejection = options?.launchRejection; + } + + override get providerWide(): boolean { + return true; + } + + override ownPresentation(): AnalysisErrorOwnPresentation { + const denied = hopperAppleEventsAuthorizationDenied(this.launchRejection); + return { + ...HOPPER_CLASSIFICATIONS.unavailable, + message: denied + ? HOPPER_APPLE_EVENTS_AUTHORIZATION_MESSAGE + : (this.userMessage ?? + "Hopper could not start. Check the launcher and target details, then retry opening the target."), + remediation: denied + ? HOPPER_APPLE_EVENTS_AUTHORIZATION_REMEDIATION + : this.ownerRunId === undefined + ? "Check the Hopper launcher and target details, then retry opening the target." + : `Use the active REA session ${this.ownerRunId} or close it before opening this target again.`, + ...(denied ? { retryable: false as const } : {}), + details: { + stage: "launch", + provider_state: "unknown", + ...(this.launchRejection === undefined + ? {} + : { launch_rejection: { ...this.launchRejection } }), + retry_action: + this.ownerRunId === undefined && !denied ? "retry" : "unknown", + ...(this.ownerRunId === undefined + ? {} + : { owner_run_id: this.ownerRunId }), + ...(this.launcherFailure === undefined + ? {} + : { launcher: this.launcherFailure }), + }, + }; + } +} + +const HOPPER_DIAGNOSTIC_TYPES = { + remote: true, + authorization: true, + invalid_request: true, + capability_unavailable: true, + bridge_exception: true, +} as const satisfies Record; + +/** Hopper's rows in the generated error catalogue. */ +export const hopperErrorCatalogue = + (): readonly AnalysisErrorCatalogueEntry[] => [ + catalogueRow( + providerErrorTag("HopperTimeoutError"), + "", + HOPPER_CLASSIFICATIONS.timeout, + ), + catalogueRow( + providerErrorTag("HopperCancelledError"), + "", + HOPPER_CLASSIFICATIONS.cancelled, + ), + catalogueRow( + providerErrorTag("HopperProtocolError"), + "", + HOPPER_CLASSIFICATIONS.protocol, + ), + ...Object.keys(HOPPER_DIAGNOSTIC_TYPES).map((diagnosticType) => + catalogueRow( + providerErrorTag("HopperRemoteError"), + `diagnostic_type=${diagnosticType}`, + hopperRemoteClassification(diagnosticType as HopperDiagnosticType), + ), + ), + catalogueRow( + providerErrorTag("HopperProcessError"), + "", + HOPPER_CLASSIFICATIONS.unavailable, + ), + catalogueRow( + providerErrorTag("HopperStartError"), + "", + HOPPER_CLASSIFICATIONS.unavailable, + ), + catalogueRow( + providerErrorTag("HopperStartError"), + "Apple Events authorization denied", + HOPPER_CLASSIFICATIONS.unavailable, + false, + ), + ]; diff --git a/src/hopper/HopperImageCopy.ts b/src/hopper/HopperImageCopy.ts index 62a5faa84d..d2b5eb5547 100644 --- a/src/hopper/HopperImageCopy.ts +++ b/src/hopper/HopperImageCopy.ts @@ -2,10 +2,7 @@ import { createHash } from "node:crypto"; import { open } from "node:fs/promises"; import type { ArtifactResourceScope } from "../resources/index.js"; import { ProviderCleanupError } from "../domain/providerCleanupError.js"; -import { - HopperCancelledError, - HopperStartError, -} from "../domain/hopperErrors.js"; +import { HopperCancelledError, HopperStartError } from "./HopperErrors.js"; import { err, ok, type Result } from "../domain/result.js"; import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js"; import { readFileHandleChunks } from "../filesystem/readFileHandleChunks.js"; diff --git a/src/hopper/HopperLease.ts b/src/hopper/HopperLease.ts new file mode 100644 index 0000000000..f3186b126e --- /dev/null +++ b/src/hopper/HopperLease.ts @@ -0,0 +1,88 @@ +import { realpath } from "node:fs/promises"; + +import { + ArtifactFileCleanupFailure, + bindArtifactFileCleanup, + type ArtifactResourceScope, +} from "../resources/index.js"; +import { HopperStartError } from "./HopperErrors.js"; +import { + OwnedLeaseCleanupFailure, + type LeaseAcquisition, + type LeaseFailure, +} from "../process/OwnedLease.js"; +import { + acquireHopperLease, + hopperLeaseMessage, +} from "../process/HopperLease.js"; + +/** Keep two REA processes from opening duplicate Hopper documents for one target/profile. */ +export const acquireHopperTargetLease = async (input: { + readonly targetPath: string; + readonly targetKind: "executable" | "database"; + readonly loaderArgs: readonly string[]; + readonly runId: string; + readonly directory?: string; + readonly resources?: ArtifactResourceScope | undefined; +}): Promise => { + // Canonicalization is required for lease identity. A lexical fallback could + // let two aliases reserve independent sockets for the same Hopper document. + let targetPath: string; + try { + targetPath = await realpath(input.targetPath); + } catch (cause: unknown) { + throw new HopperStartError({ + cause, + userMessage: `REA could not resolve Hopper target ${JSON.stringify(input.targetPath)} to a canonical path before reserving the document. Confirm that the target exists and its path is accessible.`, + }); + } + return acquireHopperLease({ + ...input, + failure: hopperLeaseFailure, + identity: { + targetPath, + targetKind: input.targetKind, + loaderArgs: input.loaderArgs, + }, + }); +}; + +/** Reserve the Linux demo's singleton application before it can forward a target to another owner. */ +export const acquireLinuxHopperApplicationLease = (input: { + readonly runId: string; + readonly directory?: string; + readonly resources?: ArtifactResourceScope | undefined; +}): Promise => + acquireHopperLease({ + ...input, + failure: hopperLeaseFailure, + identity: { application: "linux-hopper-demo" }, + }); + +/** A lease that could not be reserved stops Hopper from starting. */ +const hopperLeaseFailure = ( + failure: LeaseFailure, + cause?: unknown, +): HopperStartError => { + const primary = + cause instanceof OwnedLeaseCleanupFailure + ? cause.primary + : cause instanceof ArtifactFileCleanupFailure && + cause.fileCleanupFailure.outcome.kind === "failed" + ? cause.fileCleanupFailure.outcome.cause + : undefined; + const error = new HopperStartError({ + ...(cause === undefined ? {} : { cause }), + ...(primary instanceof HopperStartError ? { cleanupPrimary: primary } : {}), + ...(cause instanceof ArtifactFileCleanupFailure || + cause instanceof OwnedLeaseCleanupFailure + ? { cleanup: cause.cleanup } + : {}), + userMessage: + primary instanceof HopperStartError + ? (primary.userMessage ?? hopperLeaseMessage(failure)) + : hopperLeaseMessage(failure), + }); + bindArtifactFileCleanup(cause, error); + return error; +}; diff --git a/src/hopper/HopperMachOImage.copyLifecycle.test.ts b/src/hopper/HopperMachOImage.copyLifecycle.test.ts index b696b9c897..c96fc75dd3 100644 --- a/src/hopper/HopperMachOImage.copyLifecycle.test.ts +++ b/src/hopper/HopperMachOImage.copyLifecycle.test.ts @@ -10,10 +10,7 @@ import { hopperImageCopyFileSystem } from "../../tests/fixtures/hopperImageCopyF import { createTestTempDirectory } from "../../tests/fixtures/temporaryDirectory.js"; import { AnalysisCancelledError } from "../domain/analysisErrorCore.js"; import { BinaryTargetError } from "../domain/configurationErrors.js"; -import { - HopperCancelledError, - HopperStartError, -} from "../domain/hopperErrors.js"; +import { HopperCancelledError, HopperStartError } from "./HopperErrors.js"; import { prepareHopperMachOImage, resolveHopperMachOImage as resolveHopperMachOImageWithOwner, diff --git a/src/hopper/HopperMachOImage.ts b/src/hopper/HopperMachOImage.ts index b2fbf29295..33f15ca1f0 100644 --- a/src/hopper/HopperMachOImage.ts +++ b/src/hopper/HopperMachOImage.ts @@ -27,10 +27,7 @@ import { type FatSliceDeclaration, } from "../domain/apple/machoContainer.js"; import { MACHO_CPU_TYPES } from "../domain/apple/machoTargetSelection.js"; -import { - HopperCancelledError, - HopperStartError, -} from "../domain/hopperErrors.js"; +import { HopperCancelledError, HopperStartError } from "./HopperErrors.js"; import { err, ok, type Result } from "../domain/result.js"; import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js"; import { readFileHandleChunks } from "../filesystem/readFileHandleChunks.js"; diff --git a/src/hopper/HopperProcessDiagnostic.test.ts b/src/hopper/HopperProcessDiagnostic.test.ts index 6828c7762c..09787b81e9 100644 --- a/src/hopper/HopperProcessDiagnostic.test.ts +++ b/src/hopper/HopperProcessDiagnostic.test.ts @@ -1,6 +1,6 @@ import { expect, it } from "vitest"; -import type { HopperLauncherOutcome } from "../domain/hopperErrors.js"; +import type { HopperLauncherOutcome } from "./HopperErrors.js"; import { hopperLauncherReportedApplicationNotFound, nativeHopperLaunchWasDenied, diff --git a/src/hopper/HopperProcessDiagnostic.ts b/src/hopper/HopperProcessDiagnostic.ts index 47348d8817..a3753f5a89 100644 --- a/src/hopper/HopperProcessDiagnostic.ts +++ b/src/hopper/HopperProcessDiagnostic.ts @@ -1,10 +1,10 @@ import { hopperStartupFailure, type HopperStartupFailureDiagnostic, -} from "../domain/hopperStartupFailure.js"; +} from "./HopperStartupFailure.js"; import type { ProviderProcessDiagnostic } from "../process/ProviderProcess.js"; import { parseLinuxPrivateDisplayDiagnostic } from "./LinuxPrivateDisplayDiagnostic.js"; -import type { HopperLauncherOutcome } from "../domain/hopperErrors.js"; +import type { HopperLauncherOutcome } from "./HopperErrors.js"; /** Recognize launcher stderr signatures only with complete, empty stdout. */ const hasCompleteLauncherOutput = (outcome: HopperLauncherOutcome): boolean => diff --git a/src/hopper/HopperRegexSearch.test.ts b/src/hopper/HopperRegexSearch.test.ts index 7fe5ac194d..2638f61592 100644 --- a/src/hopper/HopperRegexSearch.test.ts +++ b/src/hopper/HopperRegexSearch.test.ts @@ -13,7 +13,7 @@ import { HopperRemoteError, HopperTimeoutError, HopperProcessError, -} from "../domain/hopperErrors.js"; +} from "./HopperErrors.js"; import { projectAnalysisError } from "../domain/analysisErrorProjection.js"; import { parseConfig } from "../config/parseConfig.js"; import { silentLogger } from "../logger.js"; diff --git a/src/hopper/HopperRegexSearch.ts b/src/hopper/HopperRegexSearch.ts index 72ac5ad2cd..86555fcf03 100644 --- a/src/hopper/HopperRegexSearch.ts +++ b/src/hopper/HopperRegexSearch.ts @@ -3,7 +3,7 @@ import { z } from "zod"; import type { ExecutionOptions } from "../ports/AnalysisProvider.js"; import type { AnalysisError } from "../domain/analysisErrorBase.js"; import { cancelledBy, OwnerCancellation } from "../domain/analysisErrorCore.js"; -import { HopperRemoteError } from "../domain/hopperErrors.js"; +import { HopperRemoteError } from "./HopperErrors.js"; import type { JsonValue } from "../domain/jsonValue.js"; import { err, ok, type Result } from "../domain/result.js"; import { nativeSearchInput } from "../domain/native/nativeSearch.js"; diff --git a/src/hopper/HopperReplyContracts.ts b/src/hopper/HopperReplyContracts.ts index ba37e444ad..17b5d2690e 100644 --- a/src/hopper/HopperReplyContracts.ts +++ b/src/hopper/HopperReplyContracts.ts @@ -2,7 +2,7 @@ import { z } from "zod"; import { AnalysisOutputError } from "../domain/analysisErrorCore.js"; import { DEFAULT_BRIDGE_MAX_REQUEST_BYTES } from "../domain/analysisResourceLimits.js"; -import { HopperProtocolError } from "../domain/hopperErrors.js"; +import { HopperProtocolError } from "./HopperErrors.js"; import type { JsonValue } from "../domain/jsonValue.js"; import { analysisBookmarkSchema, diff --git a/src/hopper/HopperRequestQueue.test.ts b/src/hopper/HopperRequestQueue.test.ts index 9ffff13110..2c89caca9b 100644 --- a/src/hopper/HopperRequestQueue.test.ts +++ b/src/hopper/HopperRequestQueue.test.ts @@ -1,9 +1,6 @@ import { afterEach, describe, expect, it, vi } from "vitest"; -import { - HopperCancelledError, - HopperProtocolError, -} from "../domain/hopperErrors.js"; +import { HopperCancelledError, HopperProtocolError } from "./HopperErrors.js"; import { ok } from "../domain/result.js"; import { HopperRequestQueue } from "./HopperRequestQueue.js"; diff --git a/src/hopper/HopperRequestQueue.ts b/src/hopper/HopperRequestQueue.ts index b1060e6e91..cba7471dbe 100644 --- a/src/hopper/HopperRequestQueue.ts +++ b/src/hopper/HopperRequestQueue.ts @@ -12,13 +12,18 @@ import { HopperProtocolError, HopperRemoteError, HopperTimeoutError, -} from "../domain/hopperErrors.js"; +} from "./HopperErrors.js"; import type { BridgeMaxReplyBytes } from "../config/bridgeMaxReplyBytes.js"; import type { BridgeMaxRequestBytes } from "../config/bridgeMaxRequestBytes.js"; import type { JsonValue } from "../domain/jsonValue.js"; +import type { AnalysisResourceConstraintError } from "../domain/analysisErrorCore.js"; import { err, type Result } from "../domain/result.js"; -type HopperRequestResult = Result; +/** A request oversize refusal is reported before the request reaches Hopper. */ +export type HopperRequestFailure = + | HopperError + | AnalysisResourceConstraintError; +type HopperRequestResult = Result; interface HopperRequestQueueOptions { readonly signal?: AbortSignal; @@ -200,14 +205,14 @@ export class HopperRequestQueue { * Fail the request on the wire with a rejection the bridge could not * attribute by id. False when no request is on the wire. */ - failActive(error: HopperError): boolean { + failActive(error: HopperRequestFailure): boolean { const active = this.#active; if (active === undefined || !active.transmitted) return false; return this.accept(active.id, err(error)); } /** Fail the active wire request and every request still waiting in the FIFO. */ - failAll(error: HopperError): void { + failAll(error: HopperRequestFailure): void { const active = this.#active; this.#active = undefined; if (active !== undefined) { @@ -409,9 +414,9 @@ export class HopperRequestQueue { } const withRequestContext = ( - error: HopperError, + error: HopperRequestFailure, entry: QueuedRequest, -): HopperError => { +): HopperRequestFailure => { if (error instanceof HopperProcessError) return new HopperProcessError(error.exitCode, { ...error, diff --git a/src/hopper/HopperSocketConnection.test.ts b/src/hopper/HopperSocketConnection.test.ts index 15c0eab532..9343679758 100644 --- a/src/hopper/HopperSocketConnection.test.ts +++ b/src/hopper/HopperSocketConnection.test.ts @@ -3,7 +3,7 @@ import { join } from "node:path"; import { expect, it } from "vitest"; -import { HopperCancelledError } from "../domain/hopperErrors.js"; +import { HopperCancelledError } from "./HopperErrors.js"; import { connectHopperSocketOnce } from "./HopperSocketConnection.js"; it("retains the caller abort reason when the socket signal is already aborted", async () => { diff --git a/src/hopper/HopperSocketConnection.ts b/src/hopper/HopperSocketConnection.ts index c6cdd03508..352d69da2f 100644 --- a/src/hopper/HopperSocketConnection.ts +++ b/src/hopper/HopperSocketConnection.ts @@ -5,7 +5,7 @@ import { hopperCancelledBySignal, type HopperCancelledError, HopperStartError, -} from "../domain/hopperErrors.js"; +} from "./HopperErrors.js"; import { err, type Result } from "../domain/result.js"; /** Open one abort-aware Hopper Unix-socket connection attempt. */ diff --git a/src/domain/hopperStartupFailure.ts b/src/hopper/HopperStartupFailure.ts similarity index 98% rename from src/domain/hopperStartupFailure.ts rename to src/hopper/HopperStartupFailure.ts index 185f89cbc9..0e2255ad7d 100644 --- a/src/domain/hopperStartupFailure.ts +++ b/src/hopper/HopperStartupFailure.ts @@ -1,4 +1,4 @@ -import { MAX_NODE_TIMER_DELAY_MS } from "./analysisResourceLimits.js"; +import { MAX_NODE_TIMER_DELAY_MS } from "../domain/analysisResourceLimits.js"; export type HopperPrivateDisplayStrategy = | "direct" diff --git a/src/hopper/HopperTargetLease.test.ts b/src/hopper/HopperTargetLease.test.ts index 59b68927a0..a7c9cf9fdc 100644 --- a/src/hopper/HopperTargetLease.test.ts +++ b/src/hopper/HopperTargetLease.test.ts @@ -21,7 +21,7 @@ import { afterEach, describe, expect, it } from "vitest"; import { acquireHopperTargetLease, acquireLinuxHopperApplicationLease, -} from "../process/HopperLease.js"; +} from "./HopperLease.js"; const directories: string[] = []; diff --git a/src/hopper/LinuxPrivateDisplayDiagnostic.ts b/src/hopper/LinuxPrivateDisplayDiagnostic.ts index f8c4d52a3e..8f66db1f86 100644 --- a/src/hopper/LinuxPrivateDisplayDiagnostic.ts +++ b/src/hopper/LinuxPrivateDisplayDiagnostic.ts @@ -7,7 +7,7 @@ import { isHopperStartupFailureCode, MINIMUM_HOPPER_DEMO_DIALOG_TIMEOUT_MS, type HopperStartupDiagnostic, -} from "../domain/hopperStartupFailure.js"; +} from "./HopperStartupFailure.js"; import { safeParseJson } from "../domain/safeJson.js"; export const LINUX_PRIVATE_DISPLAY_DIAGNOSTIC_PREFIX = "REA_X11_DIAGNOSTIC="; diff --git a/src/hopper/LinuxPrivateDisplayProbe.ts b/src/hopper/LinuxPrivateDisplayProbe.ts index eb93dcda9c..ecaa5c7f9a 100644 --- a/src/hopper/LinuxPrivateDisplayProbe.ts +++ b/src/hopper/LinuxPrivateDisplayProbe.ts @@ -8,7 +8,7 @@ import { type HopperStartupFailureDiagnostic, type HopperStartupFailureCode, type HopperStartupReadyDiagnostic, -} from "../domain/hopperStartupFailure.js"; +} from "./HopperStartupFailure.js"; import { cleanupOwnedProcessGroup } from "../process/ProcessOwnership.js"; import { ProviderProcessSupervisor, diff --git a/src/hopper/protocol.ts b/src/hopper/protocol.ts index e1e8143d98..d007d81284 100644 --- a/src/hopper/protocol.ts +++ b/src/hopper/protocol.ts @@ -1,9 +1,6 @@ import { z } from "zod"; -import { - HopperProtocolError, - HopperRemoteError, -} from "../domain/hopperErrors.js"; +import { HopperProtocolError, HopperRemoteError } from "./HopperErrors.js"; import { ownedJsonValueSchema, type JsonValue } from "../domain/jsonValue.js"; import { err, ok, type Result } from "../domain/result.js"; import { safeParseJson } from "../domain/safeJson.js"; diff --git a/src/ida/IdaBusyHealth.test.ts b/src/ida/IdaBusyHealth.test.ts index e4671e1850..4674f4150f 100644 --- a/src/ida/IdaBusyHealth.test.ts +++ b/src/ida/IdaBusyHealth.test.ts @@ -173,6 +173,49 @@ it("rejects without another read when the signal aborts after the pause has fulf expect(failure instanceof Error && failure.cause).toBe(reason); }); +it.each([ + ["the caller's own abort error", "own", true], + ["an abort error carrying another reason", "foreign", false], + ["a reasonless AbortError", "reasonless", false], +] as const)( + "counts %s from the retry pause as cancellation: %s", + async (_label, thrown, cancelled) => { + const controller = new AbortController(); + const reason = { caller: "busy-health cancellation" }; + const { connection } = scripted([busy("config_json_get")]); + const foreign = + thrown === "reasonless" + ? new DOMException("Aborted elsewhere", "AbortError") + : Object.assign(new Error("The operation was aborted"), { + name: "AbortError", + code: "ABORT_ERR", + cause: thrown === "own" ? reason : { other: "deadline" }, + }); + const clock = { + now: () => 0, + delay: async () => { + controller.abort(reason); + throw foreign; + }, + }; + + const failure = await readSettledHealth(connection, { + database: "db", + timeoutMs: 10_000, + signal: controller.signal, + clock, + }).catch((cause: unknown) => cause); + + if (cancelled) + expect(failure).toMatchObject({ + _tag: "AnalysisCancelledError", + operation: "server_health", + cause: reason, + }); + else expect(failure, "the pause's own failure is kept").toBe(foreign); + }, +); + it("retains the last busy observation when a shortened health request times out", async () => { const capturedOutput = { stdout: "", diff --git a/src/ida/IdaBusyHealth.ts b/src/ida/IdaBusyHealth.ts index ef019eab70..6b1dfbde17 100644 --- a/src/ida/IdaBusyHealth.ts +++ b/src/ida/IdaBusyHealth.ts @@ -7,6 +7,7 @@ import { idaRegistrationTimeoutGuidance } from "./IdaConfiguration.js"; import type { JsonValue } from "../domain/jsonValue.js"; import type { IdaMcpConnection } from "./IdaMcpConnection.js"; import { busyHealthSchema } from "./IdaProtocolValues.js"; +import { isAbortOf } from "../process/SignalAbort.js"; import { isRecord } from "../kernel/isRecord.js"; /** Pause between health reads while a freshly opened worker reports itself busy. */ @@ -105,12 +106,8 @@ export const readSettledHealth = async ( try { await clock.delay(Math.min(BUSY_HEALTH_RETRY_MS, remaining()), signal); } catch (cause: unknown) { - if ( - signal?.aborted && - cause instanceof Error && - cause.name === "AbortError" - ) - throw cancelledBy("server_health", signal); + // Only this caller's own abort of the pause is a cancellation. + if (isAbortOf(cause, signal)) throw cancelledBy("server_health", signal); throw cause; } if (signal?.aborted) throw cancelledBy("server_health", signal); diff --git a/src/javascript/analysis/JavaScriptAnalysisWorker.ts b/src/javascript/analysis/JavaScriptAnalysisWorker.ts index 10c30c8859..4e869e5429 100644 --- a/src/javascript/analysis/JavaScriptAnalysisWorker.ts +++ b/src/javascript/analysis/JavaScriptAnalysisWorker.ts @@ -1,3 +1,7 @@ +import { + runtimeExhaustionReport, + type RuntimeExhaustion, +} from "../../process/RuntimeExhaustion.js"; import { DEFAULT_JAVASCRIPT_MEMBER_MUTATION_ALLOWANCE, javaScriptMemberMutationAllowanceField, @@ -131,6 +135,8 @@ type WorkerPrimaryFailure = readonly code: number | null; readonly signal: NodeJS.Signals | null; readonly heapExhaustion: boolean; + /** The runtime's own report, kept once the supervisor observed it. */ + readonly exhaustion?: RuntimeExhaustion; }; /** One sequential owned worker, retained between source files and closed after analysis. */ @@ -228,6 +234,9 @@ export class JavaScriptAnalysisWorker { supervisorOptions: { captureStdout: false, maxDiagnosticBytes: 256 * 1024, + // V8's heap report is observed as output streams, so a retention + // budget or a stack trace that overflowed it cannot hide it. + runtime: "v8", onDiagnostic: (event) => this.#observeProcessDiagnostic(event), }, onInputFailure: (cause) => this.#latchInputFailure(cause), @@ -1080,15 +1089,16 @@ export class JavaScriptAnalysisWorker { ); return; } - if ( - event.type === "output" && - event.stream === "stderr" && - this.#primaryFailure?.kind === "exit" && - /heap out of memory|heap limit|allocation failed/iu.test( - this.#runtime.supervisor?.snapshot().stderr.text ?? "", - ) - ) { - this.#primaryFailure = { ...this.#primaryFailure, heapExhaustion: true }; + const reported = + event.type === "output" + ? this.#runtime.supervisor?.snapshot().runtimeExhaustion + : undefined; + if (reported !== undefined && this.#primaryFailure?.kind === "exit") { + this.#primaryFailure = { + ...this.#primaryFailure, + heapExhaustion: true, + exhaustion: reported, + }; this.#frameSignal.wake("failure"); } if (event.type === "exit" && (event.code !== 0 || event.signal !== null)) { @@ -1097,20 +1107,19 @@ export class JavaScriptAnalysisWorker { kind: "exit", code: event.code, signal: event.signal, - heapExhaustion: - /heap out of memory|heap limit|allocation failed/iu.test( - event.snapshot.stderr.text, - ), + heapExhaustion: event.snapshot.runtimeExhaustion !== undefined, + ...(event.snapshot.runtimeExhaustion === undefined + ? {} + : { exhaustion: event.snapshot.runtimeExhaustion }), }; else if ( this.#primaryFailure.kind === "exit" && - /heap out of memory|heap limit|allocation failed/iu.test( - event.snapshot.stderr.text, - ) + event.snapshot.runtimeExhaustion !== undefined ) { this.#primaryFailure = { ...this.#primaryFailure, heapExhaustion: true, + exhaustion: event.snapshot.runtimeExhaustion, }; this.#frameSignal.wake("failure"); } @@ -1260,6 +1269,15 @@ export class JavaScriptAnalysisWorker { this.#limits(), { capturedOutput: this.#captured(), + ...(failure.exhaustion === undefined + ? {} + : { + diagnostics: { + runtime_exhaustion_report: runtimeExhaustionReport( + failure.exhaustion, + ), + }, + }), ...(WORKER_HEAP_FLAGS_ENFORCED ? { limit: analysisSettingLimit( diff --git a/src/jeb/JebProvider.ts b/src/jeb/JebProvider.ts index 114c3e3011..97d85249f4 100644 --- a/src/jeb/JebProvider.ts +++ b/src/jeb/JebProvider.ts @@ -30,7 +30,8 @@ import { import { jvmExhaustionArea, RUNTIME_EXHAUSTION_TOKENS, - type RuntimeExhaustionArea, + externalJvmExhaustionRecovery, + type ExternalJvm, } from "../process/RuntimeExhaustion.js"; import { classifyProviderFailure, @@ -117,21 +118,15 @@ const envelope = z.discriminatedUnion("success", [ failure, ]); -/** Recovery for the JVM memory area JEB reported; each area has its own limit. */ -const JEB_EXHAUSTION_REMEDIATION: Readonly< - Record -> = { - heap: "REA does not set JEB's Java heap. Restart the JEB client with a larger maximum heap (-Xmx), or select a smaller input.", - "gc-overhead": - "REA does not set JEB's Java heap. The engine JVM spent nearly all its time collecting garbage; restart the JEB client with a larger maximum heap (-Xmx), or select a smaller input.", - metaspace: - "REA does not set JEB's class metadata limit. Restart the JEB client with a larger -XX:MaxMetaspaceSize; a larger heap (-Xmx) does not raise it.", - "array-size": - "The engine requested an array larger than the JVM allows; a larger heap (-Xmx) does not lift this limit. Select a smaller input.", - "native-thread": - "The engine JVM could not create a native thread. Reduce concurrent work in the JEB client or review the engine host's thread and process limits; a larger heap (-Xmx) does not help.", - unknown: - "REA does not set the memory limits of JEB's JVM. Review the reported out-of-memory line and the JEB client's JVM memory settings, or select a smaller input.", +/** JEB runs in the user's own JVM; REA sets none of its memory limits. */ +const JEB_JVM: ExternalJvm = { + program: "JEB's", + role: "engine", + raise: (option) => `Restart the JEB client with a larger ${option}`, + settings: "the JEB client's JVM memory settings", + threads: + "Reduce concurrent work in the JEB client or review the engine host's thread and process limits", + smaller: "select a smaller input", }; /** @@ -156,7 +151,7 @@ const refusalExhaustion = ( null, { diagnostics: { ...diagnostics, jvm_exhaustion_area: area ?? null }, - remediationAction: JEB_EXHAUSTION_REMEDIATION[area ?? "unknown"], + remediationAction: externalJvmExhaustionRecovery(area, JEB_JVM), }, ); }; diff --git a/src/kuna/KunaCommand.ts b/src/kuna/KunaCommand.ts index 76f4a7572f..3b8c01db33 100644 --- a/src/kuna/KunaCommand.ts +++ b/src/kuna/KunaCommand.ts @@ -47,9 +47,11 @@ import { kunaChildEnvironment, kunaInstallationFailureDiagnostics, type KunaInstallation, + type KunaResourceScope, } from "./KunaInstallation.js"; import type { KunaDeadline } from "./KunaConfiguration.js"; import { KUNA_PROVIDER_ID } from "./KunaRelease.js"; +import type { ProviderFailureDialect } from "../providers/classifyProviderFailure.js"; import { errorMessage } from "../kernel/errorMessage.js"; /** @@ -138,19 +140,20 @@ export const kunaFileCleanupError = ( diagnostics, userMessage: `Kuna ${operation} failed: ${errorMessage(primaryCause)}`, }); - return analysisErrorWithCleanupFailure(primary, cleanup, operation); + const composed = analysisErrorWithCleanupFailure(primary, cleanup, operation); + // The installation facts stay where every other outcome reports them, not + // only inside the composed primary and cleanup reports. + return diagnostics === undefined + ? composed + : composed.retainDiagnostics(diagnostics); }; /** Preserve the exact retryable resources when an inspection admission retries them. */ -export const kunaRetainedResourceCleanupError = ( - cause: unknown, +const kunaRetainedResourceCleanupError = ( + cause: ArtifactReaderFailure, operation: string, -): AnalysisError | undefined => { - if ( - !(cause instanceof ArtifactReaderFailure) || - cause.cleanupLeases === undefined || - cause.cleanupLeases.length === 0 - ) +): ProviderCleanupError | undefined => { + if (cause.cleanupLeases === undefined || cause.cleanupLeases.length === 0) return undefined; const cleanup = new ProviderCleanupError( KUNA_PROVIDER_ID, @@ -162,6 +165,33 @@ export const kunaRetainedResourceCleanupError = ( return cleanup; }; +/** + * The Kuna installation inspection's failures, read in one order: an + * admission's retained cleanup, the inspection's cancellation, then a file + * whose descriptor cleanup failed. What else a cause means belongs to the + * caller's `unclassified`. + */ +export const kunaInstallationDialect = ( + operation: string, + resources: KunaResourceScope, + unclassified: ProviderFailureDialect["unclassified"], +): ProviderFailureDialect => ({ + providerId: KUNA_PROVIDER_ID, + operation, + recognise: (cause) => { + if (cause instanceof ArtifactReaderFailure) { + const retained = kunaRetainedResourceCleanupError(cause, operation); + if (retained !== undefined) return retained; + } + if (!(cause instanceof RegularFileCleanupFailure)) + return resources.installationCancellationError(cause, operation); + const error = kunaFileCleanupError(cause, operation); + resources.bindFailure(cause, error); + return error; + }, + unclassified, +}); + /** File metadata that, unchanged, lets a verified digest stand without re-hashing. */ const verifiedExecutables = new Map< string, diff --git a/src/kuna/KunaDoctor.ts b/src/kuna/KunaDoctor.ts index 3244651e41..c1db97266c 100644 --- a/src/kuna/KunaDoctor.ts +++ b/src/kuna/KunaDoctor.ts @@ -11,12 +11,13 @@ import { type KunaAdmissionRefusal, } from "./KunaAdmission.js"; import type { RetainedResourceScope } from "../ports/AnalysisProvider.js"; -import { RegularFileCleanupFailure } from "../filesystem/OwnedRegularFile.js"; -import { kunaRetainedResourceCleanupError } from "./KunaCommand.js"; +import type { JsonValue } from "../domain/jsonValue.js"; +import { ProviderAdapterError } from "../domain/providerAdapterError.js"; +import { classifyProviderFailure } from "../providers/classifyProviderFailure.js"; +import { kunaInstallationDialect } from "./KunaCommand.js"; import { createKunaResourceScope, inspectKunaInstallation, - kunaInstallationFailureDiagnostics, type KunaReadinessFailure, } from "./KunaInstallation.js"; import { @@ -137,21 +138,14 @@ const versionCheck = async ( } if (!installation.ok) { const check = probeFailure(installation.error); - const cleanupResources = kunaResources.cleanupResources; if (!kunaResources.hasPending) return { version: null, check }; return { version: null, - check: { - ...check, - code: "cleanup_incomplete", - details: { - ...installation.error.diagnostics, - cleanup_incomplete: true, - ...(cleanupResources === undefined - ? {} - : { cleanup_resources: [...cleanupResources] }), - }, - }, + check: cleanupIncompleteCheck( + { ...check, code: "cleanup_incomplete" }, + installation.error.diagnostics, + kunaResources.cleanupResources, + ), }; } const { value } = installation; @@ -200,45 +194,55 @@ const admissionFailure = ( details: refusal.diagnostics, }); -/** A probe that threw: retained or unconfirmed cleanup, else rethrown. */ +/** An installation check whose inspection left cleanup unconfirmed. */ +const cleanupIncompleteCheck = ( + check: Omit, + diagnostics: Readonly> | undefined, + cleanupResources: readonly string[] | undefined, +): DoctorProviderCheck => ({ + ...check, + details: { + ...diagnostics, + cleanup_incomplete: true, + ...(cleanupResources === undefined + ? {} + : { cleanup_resources: [...cleanupResources] }), + }, +}); + +/** + * A probe that threw. The installation dialect owns what an inspection + * failure means; doctor reports a failure with unconfirmed cleanup and + * rethrows the rest. + */ const probeCleanupFailure = ( cause: unknown, kunaResources: ReturnType, ): DoctorProviderCheck => { - const retainedCleanup = kunaRetainedResourceCleanupError(cause, "doctor"); - if (retainedCleanup !== undefined) - return { + let recognised = true; + const failure = classifyProviderFailure( + cause, + kunaInstallationDialect("doctor", kunaResources, (unrecognised) => { + recognised = false; + return new ProviderAdapterError(KUNA_PROVIDER_ID, "doctor", { + cause: unrecognised, + }); + }), + ); + if (!recognised) throw cause; + if (!failure.cleanupIncomplete) throw failure; + return cleanupIncompleteCheck( + { name: "version", ok: false, code: "cleanup_incomplete", - detail: retainedCleanup.message, + detail: `Kuna installation inspection could not confirm cleanup: ${failure.message}`, remediation: null, classification: "config_drift", - details: { - cleanup_incomplete: true, - cleanup_resources: [...retainedCleanup.cleanupResources], - }, - }; - if (!(cause instanceof RegularFileCleanupFailure)) { - const cancellation = kunaResources.installationCancellationError( - cause, - "doctor", - ); - if (cancellation !== undefined) throw cancellation; - throw cause; - } - return { - name: "version", - ok: false, - code: "cleanup_incomplete", - detail: `Kuna installation inspection could not confirm file cleanup: ${errorMessage(cause)}`, - remediation: null, - classification: "config_drift", - details: { - cleanup_incomplete: true, - ...kunaInstallationFailureDiagnostics(cause), }, - }; + failure.diagnostics, + failure.cleanupResources, + ); }; /** A failed version probe of an admitted command. */ diff --git a/src/kuna/KunaInstallation.ts b/src/kuna/KunaInstallation.ts index 5dfb9194c2..981157f486 100644 --- a/src/kuna/KunaInstallation.ts +++ b/src/kuna/KunaInstallation.ts @@ -177,7 +177,7 @@ export const kunaInstallationCancellation = ( }; /** One installation inspection's retained owners and originating errors. */ -interface KunaResourceScope { +export interface KunaResourceScope { readonly owner: RetainedResourceScope; readonly cleanupResources: readonly string[] | undefined; readonly hasPending: boolean; diff --git a/src/kuna/KunaProvider.ts b/src/kuna/KunaProvider.ts index c6e3399a56..c8c867fd86 100644 --- a/src/kuna/KunaProvider.ts +++ b/src/kuna/KunaProvider.ts @@ -14,8 +14,8 @@ import { type AnalysisProfileCommitment, } from "../domain/analysisProfile.js"; import type { BinaryTarget } from "../domain/binaryTargetTypes.js"; +import { classifyProviderFailure } from "../providers/classifyProviderFailure.js"; import { err, ok } from "../domain/result.js"; -import { RegularFileCleanupFailure } from "../filesystem/OwnedRegularFile.js"; import { resolveRegexMatchingDeadline, type RegexMatchingDeadline, @@ -26,8 +26,7 @@ import { } from "../config/regexWorkerHeapRequest.js"; import { snapshotEnvironment } from "../process/snapshotEnvironment.js"; import { - kunaFileCleanupError, - kunaRetainedResourceCleanupError, + kunaInstallationDialect, type KunaProcessLauncher, } from "./KunaCommand.js"; import { @@ -197,22 +196,20 @@ export class KunaProvider implements AnalysisProviderCandidate { : { processLauncher: this.#launcher }), }); } catch (cause: unknown) { - const retainedCleanup = kunaRetainedResourceCleanupError( - cause, - "kuna:profile", - ); - if (retainedCleanup !== undefined) return err(retainedCleanup); - if (!(cause instanceof RegularFileCleanupFailure)) { - const cancellation = kunaResources.installationCancellationError( + return err( + classifyProviderFailure( cause, - "kuna:profile", - ); - if (cancellation !== undefined) return err(cancellation); - } - if (!(cause instanceof RegularFileCleanupFailure)) throw cause; - const error = kunaFileCleanupError(cause, "kuna:profile"); - kunaResources.bindFailure(cause, error); - return err(error); + kunaInstallationDialect( + "kuna:profile", + kunaResources, + (unrecognised) => { + // The inspection reports expected failures in its Result; any + // other rejection is not a Kuna outcome and stays the caller's. + throw unrecognised; + }, + ), + ), + ); } if (!installation.ok) { const error = kunaUnavailable("open_binary", installation.error.reason, { diff --git a/src/kuna/KunaSessionClient.ts b/src/kuna/KunaSessionClient.ts index 9296bd7fe3..1e6922092a 100644 --- a/src/kuna/KunaSessionClient.ts +++ b/src/kuna/KunaSessionClient.ts @@ -13,10 +13,7 @@ import { ArtifactReaderFailure, } from "../resources/index.js"; import { basename, join } from "node:path"; -import { - regularFileCancellation, - RegularFileCleanupFailure, -} from "../filesystem/OwnedRegularFile.js"; +import { regularFileCancellation } from "../filesystem/OwnedRegularFile.js"; import { z } from "zod"; import { @@ -65,8 +62,7 @@ import { AbortedWait, waitForAbortable } from "../process/AbortablePromise.js"; import { SharedStartupAttempt } from "../process/SharedStartupAttempt.js"; import { KUNA_INVENTORY_OUTPUT_BYTES, - kunaFileCleanupError, - kunaRetainedResourceCleanupError, + kunaInstallationDialect, type KunaProcessLauncher, } from "./KunaCommand.js"; import { @@ -2085,22 +2081,16 @@ export class KunaSessionClient implements AnalysisClient { ); return ok(inspected.value); } catch (cause: unknown) { - const retainedCleanup = kunaRetainedResourceCleanupError(cause, "health"); - if (retainedCleanup !== undefined) return err(retainedCleanup); - if (!(cause instanceof RegularFileCleanupFailure)) { - const cancellation = kunaResources.installationCancellationError( + return err( + classifyProviderFailure( cause, - "health", - ); - if (cancellation !== undefined) return err(cancellation); - } - if (!(cause instanceof RegularFileCleanupFailure)) - return err( - classifyProviderFailure(cause, kunaSessionDialect("health")), - ); - const error = kunaFileCleanupError(cause, "health"); - kunaResources.bindFailure(cause, error); - return err(error); + kunaInstallationDialect( + "health", + kunaResources, + kunaSessionDialect("health").unclassified, + ), + ), + ); } } diff --git a/src/main/messages.test.ts b/src/main/messages.test.ts deleted file mode 100644 index 9c3961a51a..0000000000 --- a/src/main/messages.test.ts +++ /dev/null @@ -1,29 +0,0 @@ -import { readFile } from "node:fs/promises"; -import { dirname, join } from "node:path"; -import { fileURLToPath } from "node:url"; - -import { expect, it } from "vitest"; - -import { - MCP_CONNECTION_LOST, - MCP_CONNECTION_START_FAILED, - MCP_TRANSPORT_ERROR, - MCP_VALIDATION_FAILED, - SERVER_START_FAILED, -} from "./messages.js"; - -const root = join(dirname(fileURLToPath(import.meta.url)), "../.."); -it("publishes the canonical recovery messages in the error catalog", async () => { - const catalog = await readFile( - join(root, "docs/user-visible-errors.csv"), - "utf8", - ); - for (const message of [ - MCP_CONNECTION_LOST, - MCP_CONNECTION_START_FAILED, - MCP_TRANSPORT_ERROR, - MCP_VALIDATION_FAILED, - SERVER_START_FAILED, - ]) - expect(catalog).toContain(message); -}); diff --git a/src/native/pwntools/PwntoolsDecoder.ts b/src/native/pwntools/PwntoolsDecoder.ts index 3513eb6678..33eade9fbd 100644 --- a/src/native/pwntools/PwntoolsDecoder.ts +++ b/src/native/pwntools/PwntoolsDecoder.ts @@ -3,6 +3,7 @@ import { providerResultDiagnostics, } from "../../process/capturedProviderOutput.js"; import { classifyProviderFailure } from "../../providers/classifyProviderFailure.js"; +import { isAbortOf } from "../../process/SignalAbort.js"; import { HOST_PLATFORM, type HostPlatform, @@ -427,11 +428,9 @@ export class PwntoolsDecoder< } catch (cause: unknown) { // Normalize Node's abort envelope only at the write that produced it. if ( - options?.signal?.aborted && - cause instanceof Error && - "code" in cause && - cause.code === "ABORT_ERR" && - cause.cause === options.signal.reason + options?.signal?.aborted === true && + cause !== options.signal.reason && + isAbortOf(cause, options.signal) ) throw cancelledBy(OPERATION, options.signal); throw cause; diff --git a/src/native/pwntools/PwntoolsFailures.ts b/src/native/pwntools/PwntoolsFailures.ts index 07cbe07654..eb4b3b80e5 100644 --- a/src/native/pwntools/PwntoolsFailures.ts +++ b/src/native/pwntools/PwntoolsFailures.ts @@ -20,7 +20,6 @@ import { ProviderAdapterError } from "../../domain/providerAdapterError.js"; import { ProviderSelectionError } from "../../domain/providerSelectionError.js"; import type { ProviderOutcomeContext } from "../../process/classifyProviderOutcome.js"; import { describeLaunchFailure } from "../../process/launchFailure.js"; -import { OwnedCommandFailure } from "../../process/OwnedCommand.js"; import type { ProviderFailureDialect } from "../../providers/classifyProviderFailure.js"; import type { PwntoolsFailureEvidence } from "./PwntoolsResourceLimits.js"; import { nativeDeadlineRecovery } from "../../domain/native/nativeDeadlines.js"; @@ -312,7 +311,7 @@ const pwntoolsCommandContext = ( context, { cause: details.cause, diagnostics: details.diagnostics }, ), - dialect: (outcome, details) => { + dialect: (outcome, details, unclassified) => { // A reserved exit means a resource failure only when the bridge's // marker names that resource. const reservedExit = @@ -347,20 +346,9 @@ const pwntoolsCommandContext = ( }, ); // The shared owner already carries the command's output as - // `details.capturedOutput`; diagnostics keep only the exit facts. - const snapshot = outcome.output?.snapshot; - return new ProviderAdapterError(context.providerId, context.operation, { - ...details, - diagnostics: { - ...pwntoolsPhaseDiagnostics(state), - reason: outcome.message, - failure_kind: - outcome.cause instanceof OwnedCommandFailure - ? outcome.cause.reason - : outcome.kind, - exit_code: snapshot?.exitCode ?? null, - signal: snapshot?.signal ?? null, - }, + // `details.capturedOutput` and reports the examined exit facts. + return unclassified({ + diagnostics: pwntoolsPhaseDiagnostics(state), }); }, }; diff --git a/src/pcap/PcapCommand.ts b/src/pcap/PcapCommand.ts index 72dc8d628e..2037e1de7e 100644 --- a/src/pcap/PcapCommand.ts +++ b/src/pcap/PcapCommand.ts @@ -108,10 +108,14 @@ export const runPcapCommand = async (options: { snapshot: ProviderProcessSnapshot, ): AnalysisCapturedOutput => projectDiagnostic(capturedProviderOutput(snapshot)); - /** A version probe that fails names the tool; a capture read names the file. */ + /** + * A version probe that fails names the tool; a capture read names the file + * when the tool says it is not a capture. `unrecognised` reports the rest. + */ const pcapToolFailure = ( diagnostic: string, details: AnalysisErrorOptions, + unrecognised: (reason: string) => AnalysisError, ): AnalysisError => { if (options.inputPath === undefined) return pcapToolUnavailable( @@ -130,10 +134,7 @@ export const runPcapCommand = async (options: { diagnostic, details, ); - return new AnalysisProtocolError( - `Packet capture tool ${command} failed: ${diagnostic}`, - details, - ); + return unrecognised(`Packet capture tool ${command} failed: ${diagnostic}`); }; if (signal?.aborted) throw cancelledBy(operation, signal); const hostEnvironment = { @@ -292,7 +293,11 @@ export const runPcapCommand = async (options: { `The packet command could not start; the failing stage is unknown: ${diagnostic}`, details, ); - throw pcapToolFailure(diagnostic, details); + throw pcapToolFailure( + diagnostic, + details, + (reason) => new AnalysisProtocolError(reason, details), + ); } throw classifyProviderOutcome(outcome, { providerId: "pcap", @@ -343,15 +348,17 @@ export const runPcapCommand = async (options: { details, ); }, - dialect: (failure, details) => { + dialect: (failure, details, unclassified) => { + // The examined outcome carries the exit facts; `detail` names the stage. + const unrecognised = (reason: string) => + unclassified({ diagnostics: { detail: reason } }); const diagnostic = failure.output?.snapshot.stderr.text.trim() || failure.message; if (!commandAttempted) return preparationFailure(diagnostic, details); if (selectedLimiter !== undefined) { if (failure.kind !== "exited" || failure.output === undefined) - return new AnalysisProtocolError( + return unrecognised( `The bounded packet command failed before its exit was observed; whether the limiter or selected tool failed is unknown: ${diagnostic}`, - details, ); const attributed = attributePcapLimitedExit(selectedLimiter, { exitCode: failure.exitCode, @@ -381,7 +388,7 @@ export const runPcapCommand = async (options: { ); // Otherwise prlimit started the tool; its exit and output are the tool's. } - return pcapToolFailure(diagnostic, details); + return pcapToolFailure(diagnostic, details, unrecognised); }, }); } diff --git a/src/pcap/PcapProvider.ts b/src/pcap/PcapProvider.ts index c3e0f4cfbd..e94c92d6be 100644 --- a/src/pcap/PcapProvider.ts +++ b/src/pcap/PcapProvider.ts @@ -61,6 +61,7 @@ import { type PcapCommandLauncher, } from "./PcapCommand.js"; import { ProviderCleanupError } from "../domain/providerCleanupError.js"; +import { UnclassifiedProviderFailure } from "../domain/unclassifiedProviderFailure.js"; import { jsonValueSchema } from "../domain/jsonValue.js"; import { createPcapEvidence } from "../domain/pcap/pcapEvidence.js"; import { preparePcapNativeBound } from "./PcapNativeBound.js"; @@ -200,6 +201,16 @@ const assertValidPcapCommandText = ( ); }; +/** + * What the failed DNS wire pass reported. An unrecognised command outcome + * names its stage in `detail`, or else the examined outcome's reason. + */ +const dnsFailureReason = (cause: AnalysisError): string => { + if (!(cause instanceof UnclassifiedProviderFailure)) return cause.message; + const detail = cause.diagnostics?.detail; + return typeof detail === "string" ? detail : cause.examined.reason; +}; + export interface PcapProviderOptions { readonly environment?: Readonly>; readonly launcher?: PcapCommandLauncher; @@ -1173,11 +1184,12 @@ export class PcapProvider { !( cause instanceof AnalysisResourceConstraintError || cause instanceof AnalysisProtocolError || - cause instanceof AnalysisOutputError + cause instanceof AnalysisOutputError || + cause instanceof UnclassifiedProviderFailure ) ) throw cause; - dnsLimitation = `DNS wire identity extraction was unavailable: ${cause.message}; producer queries and addresses are retained without inferred ownership`; + dnsLimitation = `DNS wire identity extraction was unavailable: ${dnsFailureReason(cause)}; producer queries and addresses are retained without inferred ownership`; } } else { dnsLimitation = diff --git a/src/process/ArtifactAnalysisResources.test.ts b/src/process/ArtifactAnalysisResources.test.ts index acfa5d7bc0..7f0696fbc8 100644 --- a/src/process/ArtifactAnalysisResources.test.ts +++ b/src/process/ArtifactAnalysisResources.test.ts @@ -28,6 +28,7 @@ import { import { createEvidence } from "../domain/evidence.js"; import { projectAnalysisError } from "../domain/analysisErrorProjection.js"; import { ProviderAdapterError } from "../domain/providerAdapterError.js"; +import { UnclassifiedProviderFailure } from "../domain/unclassifiedProviderFailure.js"; import { ProviderCleanupError } from "../domain/providerCleanupError.js"; import { err, ok } from "../domain/result.js"; import { ArtifactAnalysisResources } from "./ArtifactAnalysisResources.js"; @@ -812,7 +813,12 @@ it("retains a physical command failure when the owner also observed late cancell { command_timeout_ms: 100, output_bytes: 1024 }, undefined, ); - expect(error).toMatchObject({ _tag: "AnalysisOutputError" }); + expect(error).toBeInstanceOf(UnclassifiedProviderFailure); + expect(error).toMatchObject({ + providerId: "fixture", + examined: { failure_kind: "protocol", reason: "physical failure" }, + }); + expect(projectAnalysisError(error).code).toBe("execution_failure"); expect(error.cause).toBe(failure); } finally { await resources.close(); diff --git a/src/process/ArtifactAnalysisResources.ts b/src/process/ArtifactAnalysisResources.ts index c4f3107be2..9a111dfe70 100644 --- a/src/process/ArtifactAnalysisResources.ts +++ b/src/process/ArtifactAnalysisResources.ts @@ -506,8 +506,7 @@ export class ArtifactAnalysisResources { }, }; }, - dialect: (outcome, details) => - new AnalysisOutputError(operation, outcome.message, details), + dialect: (_outcome, _details, unclassified) => unclassified(), }; } diff --git a/src/process/ExecFileOutput.test.ts b/src/process/ExecFileOutput.test.ts index 2ad6cc9a6b..8c7557db44 100644 --- a/src/process/ExecFileOutput.test.ts +++ b/src/process/ExecFileOutput.test.ts @@ -858,7 +858,12 @@ describe("execFileOutput failure metadata", () => { }); describe("execFileOutput cancellation provenance", () => { - it.each([null, "caller stopped", new Error("caller stopped")] as const)( + it.each([ + null, + Number.NaN, + "caller stopped", + new Error("caller stopped"), + ] as const)( "retains producer cancellation and exact %s reason", async (reason) => { const controller = new AbortController(); @@ -881,6 +886,82 @@ describe("execFileOutput cancellation provenance", () => { expect(failure.cause).toBe(reason); }, ); + it.each([ + null, + Number.NaN, + "caller stopped", + new Error("caller stopped"), + ] as const)( + "reports execFile's own abort with exact %s reason", + async (reason) => { + const controller = new AbortController(); + const execution = execFileOutput( + process.execPath, + ["-e", "setInterval(() => {}, 1000)"], + { signal: controller.signal }, + ).catch((cause: unknown) => cause); + controller.abort(reason); + const failure: unknown = await execution; + expect(failure).toMatchObject({ + _tag: "ExecFileOutputCancelledError", + code: "ABORT_ERR", + }); + if (!(failure instanceof Error)) + throw new Error("Expected owned cancellation"); + expect(failure.cause).toBe(reason); + }, + ); + it.skipIf(process.platform === "win32").each([null, "caller stopped"])( + "keeps a successful exit when the caller aborts with %s while a descendant holds the pipes", + async (reason) => { + const directory = await createTestTempDirectory("rea-exec-late-abort-"); + const exited = join(directory, "exited"); + const release = join(directory, "release"); + // The descendant inherits the pipes and holds them until released. + const descendant = [ + 'const fs = require("node:fs");', + `const poll = setInterval(() => { if (fs.existsSync(${JSON.stringify(release)})) clearInterval(poll); }, 10);`, + "setTimeout(() => clearInterval(poll), 30000).unref();", + ].join("\n"); + // The launcher exits on its own, leaving the descendant running. + const script = [ + 'const { spawn } = require("node:child_process");', + 'const fs = require("node:fs");', + `spawn(process.execPath, ["-e", ${JSON.stringify(descendant)}], { stdio: ["ignore", "inherit", "inherit"] }).unref();`, + 'process.stdout.write("done", () => {', + ` fs.writeFileSync(${JSON.stringify(exited)}, "");`, + " process.exit(0);", + "});", + ].join("\n"); + const controller = new AbortController(); + const execution = execFileOutput(process.execPath, ["-e", script], { + signal: controller.signal, + }); + const settled = execution.then( + () => "settled", + () => "settled", + ); + try { + expect(await waitForFile(exited)).toBe(true); + // The direct child has exited; its descendant still holds the pipes, + // so the command has not completed when the caller aborts. + expect( + await Promise.race([ + settled, + new Promise((resolve) => setTimeout(resolve, 100, "pending")), + ]), + ).toBe("pending"); + controller.abort(reason); + } finally { + // Join the command even when a readiness assertion failed, so the + // descendant sees the release before the temporary directory goes. + await writeFile(release, ""); + await settled; + } + const result = await execution; + expect(result.stdout).toBe("done"); + }, + ); it("keeps a completed command failure when its consumer later aborts", async () => { const controller = new AbortController(); const failure: unknown = await execFileOutput( diff --git a/src/process/ExecFileOutput.ts b/src/process/ExecFileOutput.ts index 4687fb9782..2a46d53213 100644 --- a/src/process/ExecFileOutput.ts +++ b/src/process/ExecFileOutput.ts @@ -6,6 +6,7 @@ import { spawn, type ExecFileOptionsWithBufferEncoding, } from "node:child_process"; +import { isAbortOf } from "./SignalAbort.js"; type ExecFileOutputOptions = Omit< ExecFileOptionsWithBufferEncoding, @@ -234,8 +235,10 @@ export const execFileBytes = ( }, (error, stdout, stderr) => complete( - error?.name === "AbortError" && error.code === "ABORT_ERR" - ? new ExecFileOutputCancelledError(error.cause) + // A successful callback's null is not a rejection, even when + // the caller's abort reason is also null. + error !== null && isAbortOf(error, signal) + ? new ExecFileOutputCancelledError(signal.reason) : error, stdout, stderr, diff --git a/src/process/HopperLease.ts b/src/process/HopperLease.ts index e70f873463..9baec88a76 100644 --- a/src/process/HopperLease.ts +++ b/src/process/HopperLease.ts @@ -1,17 +1,12 @@ import { realpath } from "node:fs/promises"; import { join } from "node:path"; -import { - ArtifactFileCleanupFailure, - bindArtifactFileCleanup, - type ArtifactResourceScope, -} from "../resources/index.js"; -import { HopperStartError } from "../domain/hopperErrors.js"; +import type { ArtifactResourceScope } from "../resources/index.js"; import { acquireOwnedLease, - OwnedLeaseCleanupFailure, type LeaseAcquisition, type LeaseFailure, + type LeaseFailureFactory, } from "./OwnedLease.js"; /** Shared private parent of Hopper lease sockets; it outlives individual sessions. */ @@ -20,43 +15,24 @@ export const HOPPER_TARGET_LEASE_DIRECTORY = join( `rea-hopper-${process.getuid?.() ?? 0}`, ); -/** Keep two REA processes from opening duplicate Hopper documents for one target/profile. */ -export const acquireHopperTargetLease = async (input: { - readonly targetPath: string; - readonly targetKind: "executable" | "database"; - readonly loaderArgs: readonly string[]; - readonly runId: string; - readonly directory?: string; - readonly resources?: ArtifactResourceScope | undefined; -}): Promise => { - // Canonicalization is required for lease identity. A lexical fallback could - // let two aliases reserve independent sockets for the same Hopper document. - let targetPath: string; - try { - targetPath = await realpath(input.targetPath); - } catch (cause: unknown) { - throw new HopperStartError({ - cause, - userMessage: `REA could not resolve Hopper target ${JSON.stringify(input.targetPath)} to a canonical path before reserving the document. Confirm that the target exists and its path is accessible.`, - }); - } - return acquireLease({ - ...input, - identity: { - targetPath, - targetKind: input.targetKind, - loaderArgs: input.loaderArgs, - }, - }); -}; - -/** Reserve the Linux demo's singleton application before it can forward a target to another owner. */ -export const acquireLinuxHopperApplicationLease = (input: { +/** + * Reserve one Hopper lease identity in the shared lease directory. The caller + * supplies the failure its own layer reports. + */ +export const acquireHopperLease = (input: { + readonly identity: Readonly>; readonly runId: string; readonly directory?: string; readonly resources?: ArtifactResourceScope | undefined; + readonly failure: LeaseFailureFactory; }): Promise => - acquireLease({ ...input, identity: { application: "linux-hopper-demo" } }); + acquireOwnedLease({ + identity: input.identity, + runId: input.runId, + directory: input.directory ?? HOPPER_TARGET_LEASE_DIRECTORY, + failure: input.failure, + resources: input.resources, + }); /** Serialize approved publication/repair of one canonical signed-package entry. */ export const acquireHopperReleaseCacheLease = async (input: { @@ -64,10 +40,12 @@ export const acquireHopperReleaseCacheLease = async (input: { readonly launcherSha256: string; readonly runId: string; readonly resources?: ArtifactResourceScope | undefined; + readonly failure: LeaseFailureFactory; }): Promise => - acquireLease({ + acquireHopperLease({ runId: input.runId, resources: input.resources, + failure: input.failure, identity: { cacheDirectory: await realpath(input.cacheDirectory), launcherSha256: input.launcherSha256, @@ -75,48 +53,8 @@ export const acquireHopperReleaseCacheLease = async (input: { }, }); -const acquireLease = async (input: { - readonly identity: Readonly>; - readonly runId: string; - readonly directory?: string; - readonly resources?: ArtifactResourceScope | undefined; -}): Promise => - acquireOwnedLease({ - identity: input.identity, - runId: input.runId, - directory: input.directory ?? HOPPER_TARGET_LEASE_DIRECTORY, - failure: hopperLeaseFailure, - resources: input.resources, - }); - -const hopperLeaseFailure = ( - failure: LeaseFailure, - cause?: unknown, -): HopperStartError => { - const primary = - cause instanceof OwnedLeaseCleanupFailure - ? cause.primary - : cause instanceof ArtifactFileCleanupFailure && - cause.fileCleanupFailure.outcome.kind === "failed" - ? cause.fileCleanupFailure.outcome.cause - : undefined; - const error = new HopperStartError({ - ...(cause === undefined ? {} : { cause }), - ...(primary instanceof HopperStartError ? { cleanupPrimary: primary } : {}), - ...(cause instanceof ArtifactFileCleanupFailure || - cause instanceof OwnedLeaseCleanupFailure - ? { cleanup: cause.cleanup } - : {}), - userMessage: - primary instanceof HopperStartError - ? (primary.userMessage ?? hopperLeaseMessage(failure)) - : hopperLeaseMessage(failure), - }); - bindArtifactFileCleanup(cause, error); - return error; -}; - -const hopperLeaseMessage = (failure: LeaseFailure): string => { +/** What a Hopper lease failure means for the caller, by its kind. */ +export const hopperLeaseMessage = (failure: LeaseFailure): string => { switch (failure.kind) { case "directory_create": return "REA could not create its private Hopper lease directory."; diff --git a/src/process/OwnedLease.test.ts b/src/process/OwnedLease.test.ts index 7fdeae90c0..ad6630099d 100644 --- a/src/process/OwnedLease.test.ts +++ b/src/process/OwnedLease.test.ts @@ -9,7 +9,7 @@ import { phaseGate } from "../../tests/support/lifecycleHarness.js"; import { AnalysisCleanupLease } from "../resources/AnalysisCleanupLease.js"; import { ArtifactResourceScope } from "../resources/ArtifactResourceScope.js"; -import { HopperStartError } from "../domain/hopperErrors.js"; +import { HopperStartError } from "../hopper/HopperErrors.js"; // Unix socket paths have a short platform limit; the canonical system temp path can exceed it. const createTestTempDirectory = async (prefix: string): Promise => { const directory = await mkdtemp(join("/tmp", prefix)); @@ -75,7 +75,8 @@ vi.mock("node:fs/promises", async (importOriginal) => { }; }); -const { acquireLinuxHopperApplicationLease } = await import("./HopperLease.js"); +const { acquireLinuxHopperApplicationLease } = + await import("../hopper/HopperLease.js"); const { acquireOwnedLease } = await import("./OwnedLease.js"); const { HopperApplicationLauncher } = await import("../hopper/BridgeLauncher.js"); diff --git a/src/process/OwnedWorkerRuntime.ts b/src/process/OwnedWorkerRuntime.ts index 9cee691ad8..98aa411903 100644 --- a/src/process/OwnedWorkerRuntime.ts +++ b/src/process/OwnedWorkerRuntime.ts @@ -7,6 +7,7 @@ import { type OwnedProviderProcessSpawnOptions, type ProviderProcessSupervisorOptions, type ProviderProcessStopResult, + type ProviderProcessOutputTokenOptions, } from "./ProviderProcess.js"; import { cleanupOwnedProcessGroup } from "./ProcessOwnership.js"; import type { @@ -19,7 +20,8 @@ import { errorMessage } from "../kernel/errorMessage.js"; export interface OwnedWorkerRuntimeOptions { readonly rootPrefix: string; readonly launcher?: typeof spawnOwnedProviderProcess; - readonly supervisorOptions?: ProviderProcessSupervisorOptions; + readonly supervisorOptions?: ProviderProcessSupervisorOptions & + ProviderProcessOutputTokenOptions; /** Report request-stream failure at the lifecycle owner observation point. */ readonly onInputFailure?: (cause: Error) => void; /** Let a higher-level owner release its dependent resources before this root. */ diff --git a/src/process/RuntimeExhaustion.test.ts b/src/process/RuntimeExhaustion.test.ts new file mode 100644 index 0000000000..0d1121aebc --- /dev/null +++ b/src/process/RuntimeExhaustion.test.ts @@ -0,0 +1,35 @@ +import { expect, it } from "vitest"; +import { + externalJvmExhaustionRecovery, + RUNTIME_EXHAUSTION_AREAS, + type ExternalJvm, +} from "./RuntimeExhaustion.js"; + +const jvm: ExternalJvm = { + program: "Fixture's", + role: "engine", + raise: (option) => `Raise the ${option}`, + settings: "the fixture's JVM memory settings", + threads: "Reduce concurrent fixture work", + smaller: "select a smaller input", +}; + +it.each([ + ["heap", /Raise the maximum heap \(-Xmx\)/u], + ["gc-overhead", /raise the maximum heap \(-Xmx\)/u], + ["metaspace", /-XX:MaxMetaspaceSize; a larger heap \(-Xmx\) does not raise/u], + ["array-size", /a larger heap \(-Xmx\) does not lift this limit/u], + ["native-thread", /a larger heap \(-Xmx\) does not help/u], + [undefined, /Review the reported out-of-memory line/u], +] as const)("names the JVM option that governs a %s report", (area, advice) => { + expect(externalJvmExhaustionRecovery(area, jvm)).toMatch(advice); +}); + +it("advises only the heap for the areas the heap governs", () => { + for (const area of RUNTIME_EXHAUSTION_AREAS) { + const recovery = externalJvmExhaustionRecovery(area, jvm); + expect(/raise the maximum heap/iu.test(recovery)).toBe( + area === "heap" || area === "gc-overhead", + ); + } +}); diff --git a/src/process/RuntimeExhaustion.ts b/src/process/RuntimeExhaustion.ts index c580545d38..6a4eee3cf6 100644 --- a/src/process/RuntimeExhaustion.ts +++ b/src/process/RuntimeExhaustion.ts @@ -40,6 +40,56 @@ export const JVM_EXHAUSTION_DETAILS: readonly (readonly [ ["unable to create native thread", "native-thread"], ]; +/** + * A JVM whose memory limits REA does not set, as the provider that runs it + * names it in recovery advice. + */ +export interface ExternalJvm { + /** Possessive name of the program, such as "JEB's". */ + readonly program: string; + /** What the JVM does for REA, such as "engine" or "decoder". */ + readonly role: string; + /** How the user raises one JVM option, starting with a capital. */ + readonly raise: (option: string) => string; + /** Where that JVM's memory settings are reviewed. */ + readonly settings: string; + /** How the user lowers native thread demand, starting with a capital. */ + readonly threads: string; + /** How the user selects smaller work, starting in lower case. */ + readonly smaller: string; +} + +const capitalized = (text: string) => + text.charAt(0).toUpperCase() + text.slice(1); +const lowered = (text: string) => text.charAt(0).toLowerCase() + text.slice(1); + +/** + * Recovery for a reported JVM memory area, naming the option that governs + * that area: the heap (-Xmx) for heap and GC overhead, -XX:MaxMetaspaceSize + * for metaspace, nothing for an oversized array, and host thread capacity + * for native threads. + */ +export const externalJvmExhaustionRecovery = ( + area: RuntimeExhaustionArea | undefined, + jvm: ExternalJvm, +): string => { + const heap = jvm.raise("maximum heap (-Xmx)"); + switch (area) { + case "heap": + return `REA does not set ${jvm.program} Java heap. ${heap}, or ${jvm.smaller}.`; + case "gc-overhead": + return `REA does not set ${jvm.program} Java heap. The ${jvm.role} JVM spent nearly all its time collecting garbage; ${lowered(heap)}, or ${jvm.smaller}.`; + case "metaspace": + return `REA does not set ${jvm.program} class metadata limit. ${jvm.raise("-XX:MaxMetaspaceSize")}; a larger heap (-Xmx) does not raise it.`; + case "array-size": + return `The ${jvm.role} requested an array larger than the JVM allows; a larger heap (-Xmx) does not lift this limit. ${capitalized(jvm.smaller)}.`; + case "native-thread": + return `The ${jvm.role} JVM could not create a native thread. ${jvm.threads}; a larger heap (-Xmx) does not help.`; + case undefined: + return `REA does not set the memory limits of ${jvm.program} JVM. Review the reported out-of-memory line and ${jvm.settings}, or ${jvm.smaller}.`; + } +}; + /** * The runtime's own memory exhaustion report, observed from every drained * byte as output streamed, so a retention budget cannot hide it. diff --git a/src/process/SignalAbort.test.ts b/src/process/SignalAbort.test.ts new file mode 100644 index 0000000000..9b13f69863 --- /dev/null +++ b/src/process/SignalAbort.test.ts @@ -0,0 +1,40 @@ +import { readFile } from "node:fs/promises"; +import { fileURLToPath } from "node:url"; +import { expect, it } from "vitest"; +import { isAbortOf, isAbortWithReason } from "./SignalAbort.js"; + +it("recognises Node's abort error for this signal's reason", async () => { + const controller = new AbortController(); + const reason = { caller: "stop" }; + controller.abort(reason); + const cause = await readFile(fileURLToPath(import.meta.url), { + signal: controller.signal, + }).catch((failure: unknown) => failure); + expect(isAbortOf(cause, controller.signal)).toBe(true); + expect(isAbortOf(reason, controller.signal)).toBe(true); +}); + +it("recognises a NaN abort reason, which === never matches", async () => { + const controller = new AbortController(); + controller.abort(Number.NaN); + const cause = await readFile(fileURLToPath(import.meta.url), { + signal: controller.signal, + }).catch((failure: unknown) => failure); + expect(isAbortOf(cause, controller.signal)).toBe(true); + expect(isAbortOf(Number.NaN, controller.signal)).toBe(true); +}); + +it("does not claim another reason's abort or an unaborted signal", () => { + const foreign = new DOMException("aborted", "AbortError"); + const envelope = Object.assign(new Error("aborted", { cause: "other" }), { + name: "AbortError", + code: "ABORT_ERR", + }); + const controller = new AbortController(); + expect(isAbortOf(envelope, controller.signal)).toBe(false); + controller.abort("mine"); + expect(isAbortOf(envelope, controller.signal)).toBe(false); + expect(isAbortOf(foreign, controller.signal)).toBe(false); + expect(isAbortOf("mine", undefined)).toBe(false); + expect(isAbortWithReason(envelope, "other")).toBe(true); +}); diff --git a/src/process/SignalAbort.ts b/src/process/SignalAbort.ts new file mode 100644 index 0000000000..278b9c3a53 --- /dev/null +++ b/src/process/SignalAbort.ts @@ -0,0 +1,26 @@ +import type { AbortedSignal } from "../domain/analysisErrorCore.js"; + +/** + * Whether `cause` is the cancellation carrying `reason`: the reason itself, or + * the `AbortError` (`ABORT_ERR`) that Node's signal-aware I/O rejects with, + * which keeps the abort reason as its `cause`. + */ +export const isAbortWithReason = (cause: unknown, reason: unknown): boolean => + // Object.is: an abort reason may be NaN, which === never matches. + Object.is(cause, reason) || + (cause instanceof Error && + cause.name === "AbortError" && + "code" in cause && + cause.code === "ABORT_ERR" && + Object.is(cause.cause, reason)); + +/** + * Whether `cause` is this aborted signal's own cancellation, as raised by the + * operation that observed the signal. An abort error carrying another reason + * is not this caller's cancellation. + */ +export const isAbortOf = ( + cause: unknown, + signal: AbortSignal | undefined, +): signal is AbortedSignal => + signal?.aborted === true && isAbortWithReason(cause, signal.reason); diff --git a/src/process/classifyProviderOutcome.test.ts b/src/process/classifyProviderOutcome.test.ts new file mode 100644 index 0000000000..5a5ed5fd7c --- /dev/null +++ b/src/process/classifyProviderOutcome.test.ts @@ -0,0 +1,165 @@ +import { describe, expect, it } from "vitest"; + +import { AnalysisOutputError } from "../domain/analysisErrorCore.js"; +import { projectAnalysisError } from "../domain/analysisErrorProjection.js"; +import { UnclassifiedProviderFailure } from "../domain/unclassifiedProviderFailure.js"; +import { + classifyProviderOutcome, + type ProviderDialectOutcome, + type ProviderOutcomeContext, +} from "./classifyProviderOutcome.js"; +import type { ProviderProcessSnapshot } from "./ProviderProcess.js"; + +const snapshot: ProviderProcessSnapshot = { + stdout: { text: "", bytes: 0, observedBytes: 0 }, + stderr: { text: "unrecognised diagnostic", bytes: 23, observedBytes: 23 }, + exitCode: 3, + signal: null, +}; + +const context = ( + dialect: ProviderOutcomeContext["dialect"], +): ProviderOutcomeContext => ({ + providerId: "example", + operation: "inspect_target", + capturedOutput: (retained) => ({ + stdout: retained.stdout.text, + stderr: retained.stderr.text, + truncated: false, + }), + timeout: { ms: 1000 }, + outputLimit: { limits: null, recovery: {} }, + dialect, +}); + +/** A dialect that recognises nothing and reports its phase. */ +const unrecognised = context((_outcome, _details, unclassified) => + unclassified({ diagnostics: { phase: "worker" } }), +); + +describe("an outcome the provider dialect does not recognise", () => { + const cases: readonly { + readonly name: string; + readonly outcome: ProviderDialectOutcome; + readonly examined: Record; + }[] = [ + { + name: "an exit", + outcome: { + kind: "exited", + cause: new Error("exited with 3"), + message: "exited with 3", + output: { snapshot, truncated: true }, + exitCode: 3, + signal: null, + stopRequested: false, + }, + examined: { + failure_kind: "exited", + reason: "exited with 3", + exit_code: 3, + signal: null, + stop_requested: false, + output_truncated: true, + }, + }, + { + name: "a stream failure keeping the recorded status", + outcome: { + kind: "protocol", + cause: new Error("stdout stream failed"), + message: "stdout stream failed", + output: { snapshot, truncated: false }, + }, + examined: { + failure_kind: "protocol", + exit_code: 3, + signal: null, + output_truncated: false, + }, + }, + ]; + it.each(cases)( + "reports $name with the examined outcome", + ({ outcome, examined }) => { + const failure = classifyProviderOutcome(outcome, unrecognised); + expect(failure).toBeInstanceOf(UnclassifiedProviderFailure); + expect(failure).toMatchObject({ + _tag: "ProviderAdapterError", + providerId: "example", + operation: "inspect_target", + examined, + diagnostics: { phase: "worker", ...examined }, + cause: outcome.cause, + }); + expect(projectAnalysisError(failure)).toMatchObject({ + code: "execution_failure", + details: { diagnostics: { phase: "worker", ...examined } }, + }); + }, + ); + + it("keeps the retained output beside the examined outcome by default", () => { + const failure = classifyProviderOutcome( + { + kind: "exited", + cause: new Error("exited with 3"), + message: "exited with 3", + output: { snapshot, truncated: false }, + exitCode: 3, + signal: null, + stopRequested: true, + }, + context((_outcome, _details, unclassified) => unclassified()), + ); + expect(failure.capturedOutput).toMatchObject({ + stderr: "unrecognised diagnostic", + }); + expect(failure.diagnostics).toMatchObject({ stop_requested: true }); + }); + + it("adds the provider's diagnostics to the context's diagnostics", () => { + const failure = classifyProviderOutcome( + { + kind: "exited", + cause: new Error("exited with 3"), + message: "exited with 3", + output: { snapshot, truncated: false }, + exitCode: 3, + signal: null, + stopRequested: false, + }, + { + ...context((_outcome, _details, unclassified) => + unclassified({ diagnostics: { phase: "worker" } }), + ), + details: { diagnostics: { receipt: "finalization failed" } }, + }, + ); + expect(failure.diagnostics).toMatchObject({ + receipt: "finalization failed", + phase: "worker", + failure_kind: "exited", + }); + }); + + it("does not report an outcome the dialect classified", () => { + const failure = classifyProviderOutcome( + { + kind: "exited", + cause: new Error("exited with 3"), + message: "exited with 3", + output: { snapshot, truncated: false }, + exitCode: 3, + signal: null, + stopRequested: false, + }, + context( + (outcome, details) => + new AnalysisOutputError("inspect_target", outcome.message, details), + ), + ); + expect(failure).toBeInstanceOf(AnalysisOutputError); + expect(failure.diagnostics).toBeUndefined(); + }); +}); diff --git a/src/process/classifyProviderOutcome.ts b/src/process/classifyProviderOutcome.ts index 9081934f4c..5693f68d99 100644 --- a/src/process/classifyProviderOutcome.ts +++ b/src/process/classifyProviderOutcome.ts @@ -12,6 +12,11 @@ import { type ResourceConstraintRecovery, } from "../domain/analysisErrorCore.js"; import type { JsonValue } from "../domain/jsonValue.js"; +import type { ProviderAdapterErrorOptions } from "../domain/providerAdapterError.js"; +import { + UnclassifiedProviderFailure, + type ExaminedProviderOutcome, +} from "../domain/unclassifiedProviderFailure.js"; import type { AnalysisLimit } from "../domain/analysisSettings.js"; import { describeLaunchFailure, @@ -183,6 +188,38 @@ export const classifyLaunchFailure = ( type ReportedLimits = Readonly> | null; +/** + * Reports the dialect outcome being classified as unrecognised by the + * context's provider. The report always carries the examined outcome and the + * classifier's details; `options` add provider facts to those details. + */ +export type UnclassifiedOutcomeReport = ( + options?: ProviderAdapterErrorOptions, +) => UnclassifiedProviderFailure; + +/** The facts the classifier examined for one dialect outcome. */ +const examinedOutcome = ( + outcome: ProviderDialectOutcome, +): ExaminedProviderOutcome => { + const snapshot = outcome.output?.snapshot; + return { + failure_kind: outcome.kind, + reason: outcome.message, + exit_code: + outcome.kind === "exited" + ? outcome.exitCode + : (snapshot?.exitCode ?? null), + signal: + outcome.kind === "exited" ? outcome.signal : (snapshot?.signal ?? null), + ...(outcome.kind === "exited" + ? { stop_requested: outcome.stopRequested } + : {}), + ...(outcome.output === undefined + ? {} + : { output_truncated: outcome.output.truncated }), + }; +}; + /** What one provider command needs to turn its outcome into a typed error. */ export interface ProviderOutcomeContext { readonly providerId: string; @@ -235,10 +272,15 @@ export interface ProviderOutcomeContext { * provider's to interpret. */ readonly launchUnavailable?: LaunchFailureContext["unavailable"]; - /** Provider-specific meaning of an exit or a stream failure. */ + /** + * Provider-specific meaning of an exit or a stream failure. What the + * provider does not recognise it reports through `unclassified`, which + * carries the examined outcome. + */ readonly dialect: ( outcome: ProviderDialectOutcome, details: AnalysisErrorOptions, + unclassified: UnclassifiedOutcomeReport, ) => AnalysisError; } @@ -359,6 +401,22 @@ export const classifyProviderOutcome = ( }); case "exited": case "protocol": - return context.dialect(outcome, details); + return context.dialect( + outcome, + details, + (options) => + new UnclassifiedProviderFailure( + context.providerId, + operation, + examinedOutcome(outcome), + { + ...details, + ...options, + // Provider facts join the context's diagnostics; neither + // replaces the other. + diagnostics: { ...details.diagnostics, ...options?.diagnostics }, + }, + ), + ); } }; diff --git a/src/providers/AnalysisClientFailure.test.ts b/src/providers/AnalysisClientFailure.test.ts index f7e1eb7a3f..0671d081dc 100644 --- a/src/providers/AnalysisClientFailure.test.ts +++ b/src/providers/AnalysisClientFailure.test.ts @@ -15,6 +15,13 @@ import type { FileOffsetPartialObservation } from "../domain/native/fileOffsetPa import { analysisClientFailureForOperation } from "./AnalysisClientFailure.js"; import { projectAnalysisError } from "../domain/analysisErrorProjection.js"; import { regexMatchingDeadlineError } from "../process/RegexMatcher.js"; +import { + ProviderOwnedAnalysisError, + providerErrorTag, + type AnalysisErrorOptions, + type AnalysisErrorOwnPresentation, + type ProviderRequestFailure, +} from "../domain/analysisErrorBase.js"; import { releaseOwnedCleanup } from "../../tests/support/cleanupRelease.js"; const observation: FileOffsetPartialObservation = { @@ -215,6 +222,47 @@ it.each([ ); }); +it("reattributes a provider-owned failure through the request facts it reports", () => { + class ExampleRequestError extends ProviderOwnedAnalysisError { + readonly _tag = providerErrorTag("ExampleRequestError"); + constructor( + readonly operation: string, + options: AnalysisErrorOptions = {}, + ) { + super(`Example ${operation} failed`, options); + } + override ownPresentation(): AnalysisErrorOwnPresentation { + return { code: "execution_failure", category: "execution_failure" }; + } + override providerRequest(): ProviderRequestFailure { + return { + facts: { operation: this.operation, request_id: 7 }, + reattribute: (operation, options) => + new ExampleRequestError(operation, options), + }; + } + } + const source = new ExampleRequestError("wire_request", { + diagnostics: { bridge: "observed" }, + }); + + const attributed = analysisClientFailureForOperation( + source, + "example", + "decompile", + ); + + expect(attributed).toBeInstanceOf(ExampleRequestError); + expect(attributed).toMatchObject({ + operation: "decompile", + cause: source, + diagnostics: { + provider_request: { operation: "wire_request", request_id: 7 }, + provider_diagnostics: { bridge: "observed" }, + }, + }); +}); + it("keeps the named integrity check when an artifact change changes operation", () => { const attributed = analysisClientFailureForOperation( new AnalysisArtifactChangedError( diff --git a/src/providers/AnalysisClientFailure.ts b/src/providers/AnalysisClientFailure.ts index 481130e4dc..34a8493ade 100644 --- a/src/providers/AnalysisClientFailure.ts +++ b/src/providers/AnalysisClientFailure.ts @@ -1,9 +1,4 @@ import { analysisErrorWithCancellation } from "../domain/analysisErrorCancellation.js"; -import { - HopperRemoteError, - HopperTimeoutError, - HopperProcessError, -} from "../domain/hopperErrors.js"; import { AnalysisError, type AnalysisErrorOptions, @@ -33,25 +28,7 @@ export const analysisClientFailureContext = ( providerId: string, operation: string, ): AnalysisErrorOptions => { - const providerRequest = - cause instanceof HopperRemoteError || - cause instanceof HopperTimeoutError || - cause instanceof HopperProcessError - ? { - ...(cause.operation === undefined - ? {} - : { operation: cause.operation }), - ...(cause.requestId === undefined - ? {} - : { request_id: cause.requestId }), - ...(cause instanceof HopperRemoteError - ? { - provider_code: cause.code, - diagnostic_type: cause.diagnosticType, - } - : {}), - } - : undefined; + const providerRequest = cause.providerRequest()?.facts; const attribute = ( recorded: Readonly> | undefined, ): Readonly> | undefined => @@ -120,10 +97,9 @@ export const analysisClientFailureForOperation = ( bindArtifactFileCleanup(cause, failure); return failure; } + const providerRequest = cause.providerRequest(); if ( - !(cause instanceof HopperRemoteError) && - !(cause instanceof HopperTimeoutError) && - !(cause instanceof HopperProcessError) && + providerRequest === undefined && !(cause instanceof AnalysisCancelledError) && !(cause instanceof ProviderAdapterError) && !(cause instanceof AnalysisCapabilityUnavailableError) && @@ -148,37 +124,8 @@ export const analysisClientFailureForOperation = ( }), }; let result: AnalysisError; - if (cause instanceof HopperRemoteError) - result = new HopperRemoteError(cause.code, cause.safeMessage, { - ...context, - operation, - requestId: cause.requestId, - diagnosticType: cause.diagnosticType, - }); - else if (cause instanceof HopperTimeoutError) - result = new HopperTimeoutError( - cause.timeoutMs, - operation, - cause.requestId, - cause.providerState, - cause.stage, - cause.launcherOutcome, - context, - ); - else if (cause instanceof HopperProcessError) - result = new HopperProcessError(cause.exitCode, { - ...context, - operation, - requestId: cause.requestId, - providerState: cause.providerState, - stage: cause.stage, - ...(cause.diagnostic === undefined - ? {} - : { diagnostic: cause.diagnostic }), - ...(cause.launcherFailure === undefined - ? {} - : { launcherFailure: cause.launcherFailure }), - }); + if (providerRequest !== undefined) + result = providerRequest.reattribute(operation, context); else if (cause instanceof ProviderCleanupError) { const { diagnostics, ...outcomeContext } = context; result = new ProviderCleanupError( @@ -262,7 +209,7 @@ export const analysisClientFailureForOperation = ( ); else if (cause instanceof AnalysisResourceConstraintError) result = reattributedResourceConstraint(operation, cause, context); - else + else if (cause instanceof ProviderAdapterError) result = new ProviderAdapterError(providerId, operation, { ...context, ...(cause.userMessage === undefined @@ -272,6 +219,7 @@ export const analysisClientFailureForOperation = ( ? {} : { remediationAction: cause.remediationAction }), }); + else return cause; for (const secondary of cause.secondaryFailures) { if (secondary instanceof AnalysisCancelledError) result = analysisErrorWithCancellation(result, secondary); diff --git a/src/providers/NativeCommandRunner.ts b/src/providers/NativeCommandRunner.ts index 6e2f043a57..989c59a628 100644 --- a/src/providers/NativeCommandRunner.ts +++ b/src/providers/NativeCommandRunner.ts @@ -26,6 +26,7 @@ import { type ArtifactCommandPath, } from "../process/ArtifactCommandPath.js"; import { ArtifactReaderFailure } from "../resources/index.js"; +import { isAbortOf } from "../process/SignalAbort.js"; /** * Failure diagnostics keep only an excerpt of each stream. Successful @@ -447,12 +448,11 @@ export const resolveXcrunTool = async ( const cancellation = signal?.aborted === true ? { reason: signal.reason } : undefined; const observedCancellation = - signal?.aborted === true && - cause instanceof Error && - cause.cause === signal.reason && - ((cause instanceof ArtifactReaderFailure && - cause.reason === "cancelled") || - ("code" in cause && cause.code === "ABORT_ERR")); + isAbortOf(cause, signal) || + (signal?.aborted === true && + cause instanceof ArtifactReaderFailure && + cause.reason === "cancelled" && + cause.cause === signal.reason); return err( new NativeCommandFailure( tool, diff --git a/src/rizin/RizinCommand.ts b/src/rizin/RizinCommand.ts index 409458c89b..7e1850ff61 100644 --- a/src/rizin/RizinCommand.ts +++ b/src/rizin/RizinCommand.ts @@ -1,3 +1,7 @@ +import type { + CommandRefusal, + CommandRejection, +} from "../domain/commandObservation.js"; import type { RizinInput } from "../domain/reverseEngineering.js"; import { absoluteCallerPath } from "../filesystem/callerPath.js"; @@ -49,34 +53,49 @@ export const rizinCommandLimitations = ( */ const RIZIN_SHELL_REFUSALS: readonly { readonly line: RegExp; - readonly refused: (match: RegExpExecArray) => string; + readonly reason: CommandRefusal["reason"]; + /** The named command's capture group, when the line names one. */ + readonly command?: 1; + readonly refused: (command: string | null) => string; }[] = [ { line: /^ERROR: Command '(.*)' does not exist\.$/u, - refused: (match) => `the unknown command ${JSON.stringify(match[1])}`, + reason: "unknown_command", + command: 1, + refused: (command) => `the unknown command ${JSON.stringify(command)}`, }, { line: /^ERROR: Wrong number of arguments passed to `(.*)`, see its help with `.*\?`$/u, - refused: (match) => - `a wrong argument count for ${JSON.stringify(match[1])}`, + reason: "wrong_argument_count", + command: 1, + refused: (command) => + `a wrong argument count for ${JSON.stringify(command)}`, }, { line: /^ERROR: core: Error while executing command: /u, + reason: "invalid_statement", refused: () => "an invalid statement", }, { line: /^ERROR: core: Error while parsing command: /u, + reason: "parse_failure", refused: () => "input that failed to parse", }, ]; -/** Explain the first Rizin shell refusal in a completed process's stderr. */ -export const rizinCommandRejection = (stderr: string): string | undefined => { +/** The first Rizin shell refusal in a completed process's stderr. */ +export const rizinCommandRejection = ( + stderr: string, +): CommandRejection | undefined => { for (const text of stderr.split(/\r?\n/u)) - for (const { line, refused } of RIZIN_SHELL_REFUSALS) { + for (const { line, reason, command, refused } of RIZIN_SHELL_REFUSALS) { const match = line.exec(text); - if (match !== null) - return `Rizin refused ${refused(match)} (ERROR line on stderr). It skips a refused statement and every later one, so stdout holds at most the output of earlier statements; empty stdout is not an empty result. Correct the statement, using ? for Rizin's help, and run it again.`; + if (match === null) continue; + const named = command === undefined ? null : (match[command] ?? null); + return { + refusal: { reason, command: named, line: text }, + limitation: `Rizin refused ${refused(named)} (ERROR line on stderr, recorded in refusal). It skips a refused statement and every later one, so stdout holds at most the output of earlier statements; empty stdout is not an empty result. Correct the statement, using ? for Rizin's help, and run it again.`, + }; } return undefined; }; diff --git a/src/server/http/listenHttpServer.test.ts b/src/server/http/listenHttpServer.test.ts new file mode 100644 index 0000000000..575d4c1078 --- /dev/null +++ b/src/server/http/listenHttpServer.test.ts @@ -0,0 +1,66 @@ +import { createServer, type Server } from "node:http"; + +import { expect, it } from "vitest"; + +import { listenHttpServer } from "./listenHttpServer.js"; + +const callerReason = { caller: "stop startup" }; + +/** + * A server whose listen fails with `failure` and then sees the caller abort, + * both before startup observes either. + */ +const failingServer = ( + failure: unknown, + controller: AbortController, +): Server => { + const server = createServer(); + server.listen = (() => { + setImmediate(() => { + server.emit("error", failure); + controller.abort(callerReason); + }); + return server; + }) as Server["listen"]; + return server; +}; + +it.each([ + [ + "the caller's own abort error", + Object.assign(new Error("The operation was aborted"), { + name: "AbortError", + code: "ABORT_ERR", + cause: callerReason, + }), + true, + ], + ["the caller's abort reason", callerReason, true], + [ + "an abort error carrying another reason", + Object.assign(new Error("The operation was aborted"), { + name: "AbortError", + code: "ABORT_ERR", + cause: { other: "deadline" }, + }), + false, + ], + [ + "a reasonless AbortError", + new DOMException("Aborted elsewhere", "AbortError"), + false, + ], +] as const)( + "reports %s during startup as the caller's cancellation: %s", + async (_label, failure, cancelled) => { + const controller = new AbortController(); + const server = failingServer(failure, controller); + const rejected = await listenHttpServer( + server, + "127.0.0.1", + 0, + controller.signal, + ).catch((cause: unknown) => cause); + expect(rejected).toBe(cancelled ? callerReason : failure); + }, +); diff --git a/src/server/http/listenHttpServer.ts b/src/server/http/listenHttpServer.ts index 18a5123d80..b4dc437750 100644 --- a/src/server/http/listenHttpServer.ts +++ b/src/server/http/listenHttpServer.ts @@ -1,6 +1,8 @@ import { once } from "node:events"; import type { Server } from "node:http"; +import { isAbortOf } from "../../process/SignalAbort.js"; + /** Cancel DNS/bind through Node's listener owner without coupling later shutdown to the startup signal. */ export const listenHttpServer = async ( server: Server, @@ -17,11 +19,9 @@ export const listenHttpServer = async ( await once(server, "listening", { signal: startup.signal }); startup.signal.throwIfAborted(); } catch (cause: unknown) { - if ( - startup.signal.aborted && - (cause === startup.signal.reason || - (cause instanceof Error && cause.name === "AbortError")) - ) { + // Only startup's own abort is the caller's cancellation; another failure, + // including an abort error with another reason, is reported as itself. + if (isAbortOf(cause, startup.signal)) { await new Promise((resolve, reject) => { server.close((error) => { if ( diff --git a/src/sqlite/SqliteDatabaseFailures.test.ts b/src/sqlite/SqliteDatabaseFailures.test.ts new file mode 100644 index 0000000000..b2c743ed28 --- /dev/null +++ b/src/sqlite/SqliteDatabaseFailures.test.ts @@ -0,0 +1,61 @@ +import { setTimeout as delay } from "node:timers/promises"; + +import { expect, it } from "vitest"; + +import { AnalysisCancelledError } from "../domain/analysisErrorCore.js"; +import { classifyProviderFailure } from "../providers/classifyProviderFailure.js"; +import { sqliteDatabaseDialect } from "./SqliteDatabaseFailures.js"; + +/** The abort error Node's signal-aware I/O rejects with for `signal`. */ +const nodeAbortError = (signal: AbortSignal): Promise => + delay(1, undefined, { signal }).then( + () => { + throw new Error("Expected the aborted delay to reject"); + }, + (cause: unknown) => cause, + ); + +it.each([ + ["an object", { source: "caller" }], + ["NaN", Number.NaN], +])( + "reports the caller's own abort with its reason when the reason is %s", + async (_label, reason) => { + const caller = new AbortController(); + caller.abort(reason); + const failure = classifyProviderFailure( + await nodeAbortError(caller.signal), + sqliteDatabaseDialect("/selected.db", "artifact-read", caller.signal), + ); + + expect(failure).toBeInstanceOf(AnalysisCancelledError); + expect(Object.is(failure.cause, reason)).toBe(true); + }, +); + +it.each([ + ["another signal's abort error", "aborted", "other-signal"], + ["a reasonless AbortError", "aborted", "reasonless"], + ["an abort error without a caller abort", "live", "other-signal"], +] as const)( + "classifies %s as itself, not as cancellation (caller %s)", + async (_label, state, thrown) => { + const caller = new AbortController(); + if (state === "aborted") caller.abort({ source: "caller" }); + const other = new AbortController(); + other.abort({ source: "another owner" }); + const foreign = + thrown === "reasonless" + ? new DOMException("Aborted elsewhere", "AbortError") + : await nodeAbortError(other.signal); + + const failure = classifyProviderFailure( + foreign, + sqliteDatabaseDialect("/selected.db", "artifact-read", caller.signal), + ); + + expect(failure).not.toBeInstanceOf(AnalysisCancelledError); + expect(failure).toMatchObject({ _tag: "ProviderAdapterError" }); + expect(failure.cause).toBe(foreign); + }, +); diff --git a/src/sqlite/SqliteDatabaseFailures.ts b/src/sqlite/SqliteDatabaseFailures.ts index aae828ac4f..c4a30d2df4 100644 --- a/src/sqlite/SqliteDatabaseFailures.ts +++ b/src/sqlite/SqliteDatabaseFailures.ts @@ -22,21 +22,22 @@ import { import type { JsonValue } from "../domain/jsonValue.js"; import { AnalysisCapabilityUnavailableError, - AnalysisOutputError, - AnalysisResourceConstraintError, - AnalysisTimeoutError, cancelledBy, - carriedReason, } from "../domain/analysisErrorCore.js"; +import { isAbortOf } from "../process/SignalAbort.js"; +import { fixedAllowanceOptions } from "../domain/fixedAllowanceRemediation.js"; import { ProviderAdapterError } from "../domain/providerAdapterError.js"; import { ProviderCleanupError } from "../domain/providerCleanupError.js"; import { OwnedCommandFailure } from "../process/OwnedCommand.js"; import type { ProviderProcessSnapshot } from "../process/ProviderProcess.js"; -import { providerOutcomeOf } from "../process/ProviderOutcome.js"; -import { runtimeExhaustionReport } from "../process/RuntimeExhaustion.js"; +import type { ProviderOutcome } from "../process/ProviderOutcome.js"; +import type { ProviderOutcomeContext } from "../process/classifyProviderOutcome.js"; import { DEFAULT_SQLITE_WORKER_TIMEOUT_MS } from "../domain/sqlite/sqliteDatabase.js"; import { SQLITE_PROVIDER_IDENTITY } from "../domain/sqlite/SqliteProviderIdentity.js"; -import { SQLITE_DATABASE_LIMITS } from "./SqliteDatabaseLimits.js"; +import { + SQLITE_DATABASE_LIMITS, + SQLITE_WORKER_HEAP_BYTES, +} from "./SqliteDatabaseLimits.js"; import { SqliteSnapshotAcquisitionFailure } from "./SqliteDatabaseSnapshot.js"; import { classifyProviderFailure, @@ -119,17 +120,9 @@ export const sqliteDatabaseDialect = ( ? undefined : stableArtifactInputFailure(cause, OPERATION); } - if (cause instanceof Error && cause.name === "AbortError") - return cancelledBy( - OPERATION, - carriedReason( - signal?.aborted === true && cause.cause === signal.reason - ? signal.reason - : cause, - ), - ); - if (cause instanceof OwnedCommandFailure) - return ownedCommandFailure(cause, path, workerTimeoutMs); + // Only the caller's own abort is a cancellation. An abort error with + // another reason, or with no caller abort, is classified as itself. + if (isAbortOf(cause, signal)) return cancelledBy(OPERATION, signal); // Windows reports a sharing violation as EBUSY: another process holds // the file without read sharing. The unchanged request succeeds once // that process releases it. Name the member of the file set that was @@ -153,6 +146,9 @@ export const sqliteDatabaseDialect = ( ); return undefined; }, + command: (outcome) => + sqliteWorkerCommand(outcome, path, workerTimeoutMs, { phase, path }), + commandCleanup: sqliteWorkerCleanup, // A database file the read could not open names the selected file set. ...(phase === "artifact-read" ? { file: { path, description: "database file set" } } @@ -182,105 +178,118 @@ export const sqliteDatabaseDialect = ( phase, path, reason: errorMessage(cause), - ...(cause instanceof OwnedCommandFailure && cause.snapshot !== null - ? { - failure_kind: cause.reason, - exit_code: cause.snapshot.exitCode ?? null, - signal: cause.snapshot.signal ?? null, - captured_output: { ...capturedProviderOutput(cause.snapshot) }, - } - : {}), }, }), }; return dialect; }; -const ownedCommandFailure = ( - cause: OwnedCommandFailure, +/** The selected worker deadline, its setting and what it does not cover. */ +const sqliteWorkerTimeout = ( + workerTimeoutMs: number, +): ProviderOutcomeContext["timeout"] => ({ + ms: workerTimeoutMs, + userMessage: `The SQLite worker reached its ${String(workerTimeoutMs)} ms server/provider deadline (worker_timeout_ms). This is not a whole-inspection or MCP client deadline.`, + limit: deadlineParameterLimit( + "worker_timeout_ms", + workerTimeoutMs, + DEFAULT_SQLITE_WORKER_TIMEOUT_MS, + ), + remediationAction: `${ + workerTimeoutMs < MAX_NODE_TIMER_DELAY_MS + ? `Increase worker_timeout_ms above ${String(workerTimeoutMs)} (integer milliseconds, maximum ${String(MAX_NODE_TIMER_DELAY_MS)}).` + : `worker_timeout_ms is already at the maximum supported ${String(MAX_NODE_TIMER_DELAY_MS)} ms; no higher worker deadline is supported. Report the blocker or narrow the question with caller approval.` + } This per-call setting needs no server restart. It covers worker startup, queries and reply writing, not snapshot acquisition or final reply reads/cleanup. Allow client headroom for the whole call; increasing only the client deadline does not change the worker budget. Keep the selected database/WAL and requested facts; narrow table/columns/schema_scope/row_limit only if the question permits it. Byte and heap safety limits remain fixed. Resolve incomplete cleanup before retrying; do not repeat the unchanged failed call.`, +}); + +/** The fixed diagnostic capture allowance the owned worker's output exceeded. */ +const SQLITE_DIAGNOSTIC_CAPTURE = fixedAllowanceOptions( + `The SQLite worker diagnostic capture allowance of ${String(SQLITE_DATABASE_LIMITS.diagnosticBytes)} bytes (this release has no runtime override; worker_timeout_ms does not raise it)`, + "capture", + { limit: SQLITE_DATABASE_LIMITS.diagnosticBytes, unit: "bytes" }, +); + +/** + * How the owned SQLite worker's outcomes report. The shared classifier owns + * cancellation, the deadline, the capture allowance and the runtime's heap + * report; an exit or a collection failure has no SQLite meaning beyond the + * facts the provider's unclassified report keeps. + */ +const sqliteWorkerCommand = ( + outcome: ProviderOutcome, selectedPath: string, workerTimeoutMs: number, -): AnalysisError | undefined => { - const operation = "inspect_sqlite_database"; - const capturedOutput = - cause.snapshot === null - ? undefined - : capturedProviderOutput(cause.snapshot); - const optionsWithoutCause = - capturedOutput === undefined ? {} : { capturedOutput }; - const options = { cause, ...optionsWithoutCause }; - // Preserve the same typed primary whether or not owned cleanup also fails. - const timeout = - cause.reason === "timeout" - ? new AnalysisTimeoutError(operation, workerTimeoutMs, { - ...options, - userMessage: `The SQLite worker reached its ${String(workerTimeoutMs)} ms server/provider deadline (worker_timeout_ms). This is not a whole-inspection or MCP client deadline.`, - limit: deadlineParameterLimit( - "worker_timeout_ms", - workerTimeoutMs, - DEFAULT_SQLITE_WORKER_TIMEOUT_MS, - ), - remediationAction: `${ - workerTimeoutMs < MAX_NODE_TIMER_DELAY_MS - ? `Increase worker_timeout_ms above ${String(workerTimeoutMs)} (integer milliseconds, maximum ${String(MAX_NODE_TIMER_DELAY_MS)}).` - : `worker_timeout_ms is already at the maximum supported ${String(MAX_NODE_TIMER_DELAY_MS)} ms; no higher worker deadline is supported. Report the blocker or narrow the question with caller approval.` - } This per-call setting needs no server restart. It covers worker startup, queries and reply writing, not snapshot acquisition or final reply reads/cleanup. Allow client headroom for the whole call; increasing only the client deadline does not change the worker budget. Keep the selected database/WAL and requested facts; narrow table/columns/schema_scope/row_limit only if the question permits it. Byte and heap safety limits remain fixed. Resolve incomplete cleanup before retrying; do not repeat the unchanged failed call.`, - }) - : undefined; - if (cause.cleanupFailure !== null) - return createSqliteCleanupError( - cause.resources, - { - reason: cause.cleanupFailure, - ...(timeout === undefined - ? { - previous_error: { - failure_kind: cause.reason, - message: cause.message, + phaseDiagnostics: Readonly>, +): ProviderOutcomeContext => ({ + providerId: SQLITE_PROVIDER_IDENTITY.id, + operation: OPERATION, + capturedOutput: capturedProviderOutput, + details: + outcome.kind === "runtime-exhausted" + ? { diagnostics: { selected_path: selectedPath } } + : {}, + timeout: sqliteWorkerTimeout(workerTimeoutMs), + outputLimit: { + reason: `SQLite worker diagnostics exceeded the ${String(SQLITE_DATABASE_LIMITS.diagnosticBytes)}-byte capture allowance.`, + limits: { + diagnostic_capture_bytes: SQLITE_DATABASE_LIMITS.diagnosticBytes, + }, + recovery: SQLITE_DIAGNOSTIC_CAPTURE, + }, + runtimeExhaustion: () => ({ + limits: { javascript_heap_bytes: SQLITE_WORKER_HEAP_BYTES }, + recovery: { + retryable: false, + remediationAction: `The SQLite worker's ${String(SQLITE_DATABASE_LIMITS.workerHeapMiB)} MiB JavaScript heap is fixed in this release; worker_timeout_ms does not raise it. Narrow table, columns, schema_scope or row_limit only if the question permits it; repeating the unchanged request is expected to fail the same way.`, + }, + }), + // The unclassified report keeps the output in its diagnostics, beside the + // examined exit facts, so the classified output is not repeated. + dialect: (exit, _details, unclassified) => + unclassified({ + capturedOutput: undefined, + diagnostics: { + ...phaseDiagnostics, + ...(exit.output === undefined + ? {} + : { + captured_output: { + ...capturedProviderOutput(exit.output.snapshot), }, - } - : {}), + }), }, - { - ...options, - ...(timeout === undefined ? {} : { cleanupPrimary: timeout }), - }, - ); - if (cause.reason === "cancelled") - return cancelledBy( - operation, - carriedReason( - cause.cancellation === undefined ? cause : cause.cancellation.reason, - ), - optionsWithoutCause, - ); - if (timeout !== undefined) return timeout; - // The supervisor observed V8's heap report as output streamed, so a - // retention budget or a stack trace that overflowed it cannot hide it. - const outcome = providerOutcomeOf(cause); - if (outcome.kind === "runtime-exhausted") - return new AnalysisResourceConstraintError( - operation, - "memory", - "Owned SQLite worker reported JavaScript heap exhaustion.", - { - javascript_heap_bytes: 256 * 1024 * 1024, - }, - { - ...options, - diagnostics: { - selected_path: selectedPath, - runtime_exhaustion_report: runtimeExhaustionReport( - outcome.exhaustion, - ), - }, - }, - ); - if (cause.reason === "output-limit") - return new AnalysisOutputError(operation, cause.message, { - ...options, - userMessage: `SQLite worker diagnostics exceeded the ${String(SQLITE_DATABASE_LIMITS.diagnosticBytes)}-byte capture allowance. This release has no runtime override.`, - remediationAction: `The SQLite diagnostic capture allowance is ${String(SQLITE_DATABASE_LIMITS.diagnosticBytes)} bytes. This release has no runtime override. worker_timeout_ms does not raise it. Repeating the unchanged request fails the same way.`, - }); - return undefined; + }), +}); + +/** + * A worker whose cleanup failed reports that cleanup. A deadline stays its + * typed primary; any other outcome is recorded as the failure it was. + */ +const sqliteWorkerCleanup = ( + command: OwnedCommandFailure & { readonly cleanupFailure: string }, + primary: AnalysisError, + outcome: ProviderOutcome, +): AnalysisError => { + const timeout = outcome.kind === "timeout" ? primary : undefined; + return createSqliteCleanupError( + command.resources, + { + reason: command.cleanupFailure, + ...(timeout === undefined + ? { + previous_error: { + failure_kind: command.reason, + message: command.message, + }, + } + : {}), + }, + { + cause: command, + ...(command.snapshot === null + ? {} + : { capturedOutput: capturedProviderOutput(command.snapshot) }), + ...(timeout === undefined ? {} : { cleanupPrimary: timeout }), + }, + ); }; diff --git a/src/sqlite/SqliteDatabaseInspection.ts b/src/sqlite/SqliteDatabaseInspection.ts index 95352f61af..7f31d16902 100644 --- a/src/sqlite/SqliteDatabaseInspection.ts +++ b/src/sqlite/SqliteDatabaseInspection.ts @@ -1081,7 +1081,7 @@ export const inspectSqliteDatabaseSnapshot = ( "SQLite reports current schema and selected committed rows from its valid database/WAL state. Deleted records, uncommitted or invalid WAL tails, encrypted databases, forensic recovery, and full integrity verification are outside this profile.", "Stored CREATE statements preserve index/view/trigger definitions. Views, triggers, and virtual/shadow table rows are not executed; virtual-table column expansion is unsupported.", "Selected rows are a bounded sample; rows.order names the order they were read in, and rows.next_row_offset is null either when the window reaches the end or when rows.order is unspecified, so a truncated sample with no stated order cannot be paged further. Text display may replace invalid sequences; bytes_hex and encoding preserve SQLite's text byte representation, not original on-disk page offsets.", - "Resource boundaries: at most two concurrent inspections per provider; combined input 256 MiB per inspection, complete worker JSON 16 MiB, native SQLite value/record and SQL statement lengths 16 MiB, owned-worker JavaScript heap 256 MiB. The parent applies a separate supervised worker deadline, reported in worker_timeout_ms. These are distinct from total resident memory; an overall native SQLite heap cap is not claimed. Failures return no partial success.", + `Resource boundaries: at most two concurrent inspections per provider; combined input 256 MiB per inspection, complete worker JSON 16 MiB, native SQLite value/record and SQL statement lengths 16 MiB, owned-worker JavaScript heap ${String(SQLITE_DATABASE_LIMITS.workerHeapMiB)} MiB. The parent applies a separate supervised worker deadline, reported in worker_timeout_ms. These are distinct from total resident memory; an overall native SQLite heap cap is not claimed. Failures return no partial success.`, ]; const budget = new OutputBudget(); const { schema, selectedTable } = readSchema(db, input, { diff --git a/src/sqlite/SqliteDatabaseLimits.ts b/src/sqlite/SqliteDatabaseLimits.ts index 6359107bfb..0a924baade 100644 --- a/src/sqlite/SqliteDatabaseLimits.ts +++ b/src/sqlite/SqliteDatabaseLimits.ts @@ -6,7 +6,13 @@ export const SQLITE_DATABASE_LIMITS = { inputBytes: 256 * 1024 * 1024, outputBytes: SQLITE_DATABASE_OUTPUT_BYTES, diagnosticBytes: 1024 * 1024, + /** V8 old-space ceiling for the owned worker, passed as --max-old-space-size. */ + workerHeapMiB: 256, } as const; + +/** The owned worker's JavaScript heap ceiling in bytes, as reported on memory refusals. */ +export const SQLITE_WORKER_HEAP_BYTES = + SQLITE_DATABASE_LIMITS.workerHeapMiB * 1024 * 1024; /** * Failure reasons the worker protocol may carry. The reply schema and the * worker's own failure type read this one list, so a refusal that the worker diff --git a/src/sqlite/SqliteDatabaseWorkerExecution.ts b/src/sqlite/SqliteDatabaseWorkerExecution.ts index e3479a74f5..32e79b1418 100644 --- a/src/sqlite/SqliteDatabaseWorkerExecution.ts +++ b/src/sqlite/SqliteDatabaseWorkerExecution.ts @@ -44,6 +44,7 @@ import { SQLITE_DATABASE_LIMITS, SQLITE_INSPECTION_REASONS, SQLITE_STRUCTURED_INSPECTION_REASONS, + SQLITE_WORKER_HEAP_BYTES, } from "./SqliteDatabaseLimits.js"; import { errorMessage } from "../kernel/errorMessage.js"; @@ -147,7 +148,7 @@ const rejectedReply = ( "memory", reply.message, { - javascript_heap_bytes: 256 * 1024 * 1024, + javascript_heap_bytes: SQLITE_WORKER_HEAP_BYTES, }, { capturedOutput, diagnostics: { selected_path: selectedPath } }, ); @@ -232,7 +233,7 @@ export const executeSqliteDatabaseWorker = async (request: { { command: process.execPath, arguments: [ - "--max-old-space-size=256", + `--max-old-space-size=${String(SQLITE_DATABASE_LIMITS.workerHeapMiB)}`, fileURLToPath(new URL("./SqliteDatabaseWorker.js", import.meta.url)), requestPath, ], diff --git a/src/wasm/WabtArtifactProvider.ts b/src/wasm/WabtArtifactProvider.ts index 6161220334..8ca198e695 100644 --- a/src/wasm/WabtArtifactProvider.ts +++ b/src/wasm/WabtArtifactProvider.ts @@ -37,6 +37,7 @@ import { cancelledBy, isAborted, } from "../domain/analysisErrorCore.js"; +import { isAbortOf } from "../process/SignalAbort.js"; import { ProviderCleanupError } from "../domain/providerCleanupError.js"; import { analysisErrorWithCleanupDependencies } from "../domain/analysisErrorCleanup.js"; import { analysisErrorWithCancellation } from "../domain/analysisErrorCancellation.js"; @@ -517,12 +518,7 @@ export class WabtArtifactProvider implements WasmArtifactPort { }).catch((cause: unknown) => { // Node rejects a write this signal aborted with an envelope that // carries the signal's own reason; any other failure stays itself. - if ( - isAborted(signal) && - cause instanceof Error && - cause.cause === signal.reason - ) - throw cancelledBy(OPERATION, signal); + if (isAbortOf(cause, signal)) throw cancelledBy(OPERATION, signal); throw cause; }); snapshotHash = selected.sha256; diff --git a/src/wasm/WabtFailures.test.ts b/src/wasm/WabtFailures.test.ts index de216e2a3b..51c27f20fc 100644 --- a/src/wasm/WabtFailures.test.ts +++ b/src/wasm/WabtFailures.test.ts @@ -7,6 +7,7 @@ import { classifyProviderFailure } from "../providers/classifyProviderFailure.js import { WASM_RESOURCE_DEFAULTS } from "../domain/wasm/wasmArtifact.js"; import { OwnedCommandFailure } from "../process/OwnedCommand.js"; +import { UnclassifiedProviderFailure } from "../domain/unclassifiedProviderFailure.js"; /** Classify a raw failure the way the provider does, through WABT's dialect. */ const wabtFailure = ( @@ -339,6 +340,26 @@ it("reports a WABT tool the host refused to start as unavailable", async () => { ).toMatchObject({ code: "capability_unavailable" }); }); +it.each(["artifact", "producer"] as const)( + "reports an unrecognised WABT %s-phase exit with the examined outcome", + (phase) => { + const cause = new OwnedCommandFailure("process", "exited with code 2", { + stdout: { text: "", bytes: 0, observedBytes: 0 }, + stderr: { text: "unexpected", bytes: 10, observedBytes: 10 }, + exitCode: 2, + signal: null, + }); + const failure = wabtFailure(cause, phase, "/module.wasm"); + expect(failure).toBeInstanceOf(UnclassifiedProviderFailure); + expect(failure).toMatchObject({ + providerId: "wabt-artifact", + examined: { failure_kind: "exited", exit_code: 2 }, + capturedOutput: { stderr: "unexpected" }, + }); + expect(projectAnalysisError(failure).code).toBe("execution_failure"); + }, +); + it("keeps setup guidance when a version probe's output cannot be collected", () => { const cause = new OwnedCommandFailure( "process", diff --git a/src/wasm/WabtFailures.ts b/src/wasm/WabtFailures.ts index 08e99ecf81..7d6b84c4ce 100644 --- a/src/wasm/WabtFailures.ts +++ b/src/wasm/WabtFailures.ts @@ -275,12 +275,12 @@ export const wabtFailureDialect = ( }, launchUnavailable: (_failure, details) => wabtUnavailable(outcome.message, outcome.cause, details), - dialect: (exit, details) => + dialect: (exit, details, unclassified) => // A version probe that exits or whose output cannot be collected // leaves the configured installation unusable for this call. phase === "configuration" ? wabtUnavailable(exit.message, exit.cause, details) - : new AnalysisOutputError(OPERATION, exit.message, details), + : unclassified(), }), ...(phase === "artifact" ? { diff --git a/tests/acceptance/providers/hopperStartupRecovery.test.ts b/tests/acceptance/providers/hopperStartupRecovery.test.ts index a8251652e3..b93052fdc0 100644 --- a/tests/acceptance/providers/hopperStartupRecovery.test.ts +++ b/tests/acceptance/providers/hopperStartupRecovery.test.ts @@ -14,7 +14,7 @@ import { z } from "zod"; import { parseMcpToolError } from "../../fixtures/mcpToolError.js"; import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; import { workspaceCliTest } from "../../support/cli/workspaceCliFixture.js"; -import { acquireHopperTargetLease } from "../../../src/process/HopperLease.js"; +import { acquireHopperTargetLease } from "../../../src/hopper/HopperLease.js"; import { waitFor } from "../../support/testWait.js"; import { createMcpSchemaValidation } from "../../fixtures/mcpSchemaValidation.js"; diff --git a/tests/acceptance/rizinCommandRejection.test.ts b/tests/acceptance/rizinCommandRejection.test.ts index 0b2f5e8b3e..475f255cda 100644 --- a/tests/acceptance/rizinCommandRejection.test.ts +++ b/tests/acceptance/rizinCommandRejection.test.ts @@ -19,6 +19,12 @@ interface Outcome { readonly stderr: string; /** Expected completion and the refusal the limitation must name. */ readonly refused?: RegExp; + /** The typed refusal record the result must carry. */ + readonly refusal?: { + readonly reason: string; + readonly command: string | null; + readonly line: string; + }; } // Captured from the official Rizin 0.9.1 static Linux build on /usr/bin/true. @@ -29,6 +35,11 @@ const outcomes: readonly Outcome[] = [ stderr: "ERROR: Command 'axffj' does not exist.\nERROR: Displaying the help of command 'axf'.\n\nERROR: Usage: axf[jq] # List xrefs from current seek\n", refused: /unknown command "axffj"/u, + refusal: { + reason: "unknown_command", + command: "axffj", + line: "ERROR: Command 'axffj' does not exist.", + }, }, { // Rizin runs the statements before a refusal and skips the rest. @@ -36,6 +47,11 @@ const outcomes: readonly Outcome[] = [ stdout: "0x1\n", stderr: "ERROR: Command 'zz' does not exist.\n", refused: /unknown command "zz"/u, + refusal: { + reason: "unknown_command", + command: "zz", + line: "ERROR: Command 'zz' does not exist.", + }, }, { command: "%v 1; afl 1 2; %v 2", @@ -43,6 +59,11 @@ const outcomes: readonly Outcome[] = [ stderr: "ERROR: Wrong number of arguments passed to `afl`, see its help with `afl?`\n\nERROR: Usage: afl[?] # List functions\n", refused: /wrong argument count for "afl"/u, + refusal: { + reason: "wrong_argument_count", + command: "afl", + line: "ERROR: Wrong number of arguments passed to `afl`, see its help with `afl?`", + }, }, { command: "pd 1 @ nosuch", @@ -50,12 +71,22 @@ const outcomes: readonly Outcome[] = [ stderr: "ERROR: core: Invalid address (nosuch)\nERROR: core: Error while executing command: pd 1 @ nosuch\n", refused: /an invalid statement/u, + refusal: { + reason: "invalid_statement", + command: null, + line: "ERROR: core: Error while executing command: pd 1 @ nosuch", + }, }, { command: "?e", stdout: "", stderr: "ERROR: core: Error while parsing command: `?e`\n", refused: /input that failed to parse/u, + refusal: { + reason: "parse_failure", + command: null, + line: "ERROR: core: Error while parsing command: `?e`", + }, }, // A command that ran and reported its own failure is not a shell refusal. { @@ -80,6 +111,13 @@ const expectClassified = (raw: unknown, outcome: Outcome): void => { completion_status: outcome.refused === undefined ? "complete" : "rejected", }); expect(evidence.raw_result).toEqual(evidence.normalized_result); + if (outcome.refusal === undefined) + expect(evidence.normalized_result).not.toHaveProperty("refusal"); + else + expect(evidence.normalized_result).toHaveProperty( + "refusal", + outcome.refusal, + ); const refusals = evidence.limitations.filter((limitation) => limitation.startsWith("Rizin refused "), ); diff --git a/tests/boundary/cli/hopperLaunchFailureCli.test.ts b/tests/boundary/cli/hopperLaunchFailureCli.test.ts index c3815e7258..586979ecd0 100644 --- a/tests/boundary/cli/hopperLaunchFailureCli.test.ts +++ b/tests/boundary/cli/hopperLaunchFailureCli.test.ts @@ -5,7 +5,7 @@ import { z } from "zod"; import { workspaceCliTest } from "../../support/cli/workspaceCliFixture.js"; -import { acquireHopperTargetLease } from "../../../src/process/HopperLease.js"; +import { acquireHopperTargetLease } from "../../../src/hopper/HopperLease.js"; const FAILED_LAUNCHER = `#!/bin/sh printf 'Cannot launch Hopper!\\nDocument state is unknown.\\n' >&2 diff --git a/tests/boundary/evm/evmCleanupRetry.test.ts b/tests/boundary/evm/evmCleanupRetry.test.ts index e9ea434ebc..74eee42d6c 100644 --- a/tests/boundary/evm/evmCleanupRetry.test.ts +++ b/tests/boundary/evm/evmCleanupRetry.test.ts @@ -994,3 +994,51 @@ it("keeps the selected limiter and child environment together while later inspec await rm(workspace, { recursive: true, force: true }); } }); + +it.each([ + ["the caller's own abort error", "own", true], + ["an abort error carrying another reason", "foreign", false], + ["a reasonless AbortError", "reasonless", false], +] as const)( + "counts %s from the worker launch as cancellation: %s", + async (_label, thrown, cancelled) => { + const workspace = await mkdtemp(join(tmpdir(), "rea-evm-abort-owner-")); + const input = join(workspace, "selected.hex"); + await writeFile(input, "0x60006000f3\n"); + const controller = new AbortController(); + const callerReason = { requested: "stop inspection" }; + const provider = new EvmoleInterfaceProvider( + { REA_EVM_PRLIMIT_COMMAND: process.execPath }, + async () => { + controller.abort(callerReason); + // An abort error raised while the caller's signal is also aborted. + throw thrown === "reasonless" + ? new DOMException("Aborted elsewhere", "AbortError") + : Object.assign(new Error("The operation was aborted"), { + name: "AbortError", + code: "ABORT_ERR", + cause: + thrown === "own" + ? callerReason + : { requested: "another owner's deadline" }, + }); + }, + undefined, + SIMULATED_LINUX_X64, + ); + try { + const result = await provider.inspect( + { path: input, encoding: "hex" }, + { signal: controller.signal }, + ); + if (result.ok) throw new Error("Expected the launch to fail"); + if (cancelled) { + expect(result.error).toBeInstanceOf(AnalysisCancelledError); + expect(result.error.cause).toBe(callerReason); + } else expect(result.error).not.toBeInstanceOf(AnalysisCancelledError); + } finally { + await provider.close(); + await rm(workspace, { recursive: true, force: true }); + } + }, +); diff --git a/tests/boundary/filesystem/ciChangeScope.test.ts b/tests/boundary/filesystem/ciChangeScope.test.ts index d86edae4f7..e0ffbdd643 100644 --- a/tests/boundary/filesystem/ciChangeScope.test.ts +++ b/tests/boundary/filesystem/ciChangeScope.test.ts @@ -1133,7 +1133,7 @@ it.each([ { code: true, runtime: true, package: true }, ], ["src/hopper/BridgeLauncher.ts", { code: true, apple: true }], - ["src/domain/hopperErrors.ts", { code: true, apple: true }], + ["src/hopper/HopperErrors.ts", { code: true, apple: true }], [ "tests/boundary/providers/hopper/hopperMacLaunchArguments.test.ts", { code: true, apple: true }, diff --git a/tests/boundary/filesystem/processCliFileInput.test.ts b/tests/boundary/filesystem/processCliFileInput.test.ts index ed7ea2a560..783a96af09 100644 --- a/tests/boundary/filesystem/processCliFileInput.test.ts +++ b/tests/boundary/filesystem/processCliFileInput.test.ts @@ -1,5 +1,5 @@ import { unknownTarget } from "../../../src/domain/targetIdentity.js"; -import { open, readFile, writeFile } from "node:fs/promises"; +import { open, writeFile } from "node:fs/promises"; import { join } from "node:path"; import { describe, expect, it, onTestFinished, vi } from "vitest"; import { @@ -91,9 +91,6 @@ describe("process CLI error projection", () => { expect(action).not.toMatch(/\bretry\b/iu); // The caller receives the process boundary's own recovery. expect(action).toBe(PROCESS_UNEXPECTED_FAILURE_REMEDIATION); - expect( - await readFile("docs/user-visible-errors.csv", "utf8"), - ).toContain(action); } finally { read.mockRestore(); } diff --git a/tests/boundary/javascript/workerOrderAudit.test.ts b/tests/boundary/javascript/workerOrderAudit.test.ts index 467411d1c1..052e9e986b 100644 --- a/tests/boundary/javascript/workerOrderAudit.test.ts +++ b/tests/boundary/javascript/workerOrderAudit.test.ts @@ -755,50 +755,68 @@ it("admits a final valid control frame written after the worker exit event", asy } }); -it("retains the owned worker's V8 heap exhaustion classification", async () => { - const worker = new JavaScriptAnalysisWorker( - { heapMb: 128, timeoutMs: 30_000 }, - async (request) => - spawnOwnedProviderProcess({ - ...request, - arguments: [ - "-e", - `${ready} process.stdin.once("data", () => { process.stderr.write("FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory\\n"); process.exit(7); });`, - ], - }), - ); - try { - const result = await worker.analyze(file, { nodes: 100, unknowns: 100 }); - expect(result.ok).toBe(false); - if (!result.ok) { - expect(result.error.error).toBeInstanceOf( - AnalysisResourceConstraintError, - ); - const projected = projectAnalysisError(result.error.error); - if (javaScriptRuntime(process.versions).id === "node") { - expect(projected.message).toContain( - "128 MiB V8 old-space heap (max_heap_mb)", - ); - // The adapter-neutral remediation names the request field; only the - // CLI renders its option. - expect(projected.remediation.action).toContain("Increase max_heap_mb"); - expect(projected.remediation.action).not.toContain("--max-heap-mb"); - } else { - expect(projected.message).toContain( - "Bun ignores the V8 old-space flag", - ); - expect(projected.message).not.toContain( - "128 MiB V8 old-space heap (max_heap_mb)", - ); - expect(projected.remediation.action).not.toContain( - "Increase max_heap_mb", +it.each([ + ["at the start of stderr", 0], + // The 256 KiB retention budget keeps only the head; the report lies past it. + ["past the retained stderr budget", 300 * 1024], +])( + "retains the owned worker's V8 heap exhaustion classification %s", + async (_where, noise) => { + const worker = new JavaScriptAnalysisWorker( + { heapMb: 128, timeoutMs: 30_000 }, + async (request) => + spawnOwnedProviderProcess({ + ...request, + arguments: [ + "-e", + `${ready} process.stdin.once("data", () => { process.stderr.write("x".repeat(${String(noise)}) + "\\nFATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory\\n", () => process.exit(7)); });`, + ], + }), + ); + try { + const result = await worker.analyze(file, { nodes: 100, unknowns: 100 }); + expect(result.ok).toBe(false); + if (!result.ok) { + expect(result.error.error).toBeInstanceOf( + AnalysisResourceConstraintError, ); + // The runtime's own report survives even when it lies past the + // retained stderr. + expect(result.error.error.diagnostics).toMatchObject({ + runtime_exhaustion_report: { + runtime: "v8", + stream: "stderr", + line_complete: true, + }, + }); + const projected = projectAnalysisError(result.error.error); + if (javaScriptRuntime(process.versions).id === "node") { + expect(projected.message).toContain( + "128 MiB V8 old-space heap (max_heap_mb)", + ); + // The adapter-neutral remediation names the request field; only + // the CLI renders its option. + expect(projected.remediation.action).toContain( + "Increase max_heap_mb", + ); + expect(projected.remediation.action).not.toContain("--max-heap-mb"); + } else { + expect(projected.message).toContain( + "Bun ignores the V8 old-space flag", + ); + expect(projected.message).not.toContain( + "128 MiB V8 old-space heap (max_heap_mb)", + ); + expect(projected.remediation.action).not.toContain( + "Increase max_heap_mb", + ); + } } + } finally { + await worker.close(); } - } finally { - await worker.close(); - } -}); + }, +); it("captures late stderr completely when the exited worker's inherited pipes close", async () => { const worker = new JavaScriptAnalysisWorker( diff --git a/tests/boundary/mcp/officialTools.test.ts b/tests/boundary/mcp/officialTools.test.ts index d915ecb308..a8084dd629 100644 --- a/tests/boundary/mcp/officialTools.test.ts +++ b/tests/boundary/mcp/officialTools.test.ts @@ -7,7 +7,7 @@ import type { AnalysisOperationPort } from "../../../src/ports/AnalysisProvider. import { OFFICIAL_TOOL_CONTRACTS } from "../../../src/contracts/officialToolContracts.js"; import { toolContract } from "../../../src/contracts/toolContracts.js"; import { jsonObjectSchema } from "../../../src/domain/jsonValue.js"; -import { HopperRemoteError } from "../../../src/domain/hopperErrors.js"; +import { HopperRemoteError } from "../../../src/hopper/HopperErrors.js"; import { err } from "../../../src/domain/result.js"; import { observed as ok } from "../../fixtures/analysisExecution.js"; import type { JsonValue } from "../../../src/domain/jsonValue.js"; diff --git a/tests/boundary/mcp/serverLifecycleMcp.test.ts b/tests/boundary/mcp/serverLifecycleMcp.test.ts index d367059d2a..f534c8b3a0 100644 --- a/tests/boundary/mcp/serverLifecycleMcp.test.ts +++ b/tests/boundary/mcp/serverLifecycleMcp.test.ts @@ -6,7 +6,7 @@ import { afterEach, expect, it } from "vitest"; import { phaseArrival, phaseGate } from "../../support/lifecycleHarness.js"; import type { AnalysisOperationPort } from "../../../src/ports/AnalysisProvider.js"; -import { HopperRemoteError } from "../../../src/domain/hopperErrors.js"; +import { HopperRemoteError } from "../../../src/hopper/HopperErrors.js"; import { err } from "../../../src/domain/result.js"; import { observed as ok } from "../../fixtures/analysisExecution.js"; import { createServer } from "../../../src/server/createServer.js"; diff --git a/tests/boundary/mcp/toolResult.test.ts b/tests/boundary/mcp/toolResult.test.ts index c37597260f..69ed6718c1 100644 --- a/tests/boundary/mcp/toolResult.test.ts +++ b/tests/boundary/mcp/toolResult.test.ts @@ -21,7 +21,7 @@ import { import { err } from "../../../src/domain/result.js"; import { EvidenceIntegrityError } from "../../../src/domain/evidenceErrors.js"; import { AnalysisCancelledError } from "../../../src/domain/analysisErrorCore.js"; -import { HopperProcessError } from "../../../src/domain/hopperErrors.js"; +import { HopperProcessError } from "../../../src/hopper/HopperErrors.js"; import { processScenarioSchema } from "../../../src/domain/process/processScenario.js"; import { createToolResultDelivery } from "../../../src/server/toolResult.js"; import { createEvidence, parseEvidence } from "../../../src/domain/evidence.js"; diff --git a/tests/boundary/pcap/pcapCommand.test.ts b/tests/boundary/pcap/pcapCommand.test.ts index fa50991c2a..ca51d97e85 100644 --- a/tests/boundary/pcap/pcapCommand.test.ts +++ b/tests/boundary/pcap/pcapCommand.test.ts @@ -1,3 +1,4 @@ +import { UnclassifiedProviderFailure } from "../../../src/domain/unclassifiedProviderFailure.js"; import { HOST_PLATFORM } from "../../../src/platform/HostPlatform.js"; import { join } from "node:path"; import { writeFile } from "node:fs/promises"; @@ -95,8 +96,12 @@ it("preserves a failed producer when cancellation arrives during its final clean }), }).catch((cause: unknown) => cause); expect(controller.signal.aborted).toBe(true); - expect(failure).toBeInstanceOf(AnalysisProtocolError); - if (!(failure instanceof AnalysisProtocolError)) throw failure; + expect(failure).toBeInstanceOf(UnclassifiedProviderFailure); + if (!(failure instanceof UnclassifiedProviderFailure)) throw failure; + expect(failure.examined).toMatchObject({ + failure_kind: "exited", + exit_code: 7, + }); expect(failure.cause).toBeInstanceOf(OwnedCommandFailure); expect((failure.cause as OwnedCommandFailure).reason).toBe("process"); expect(failure.capturedOutput).toMatchObject({ diff --git a/tests/boundary/pcap/pcapCredentialErrors.test.ts b/tests/boundary/pcap/pcapCredentialErrors.test.ts index f4d08845f0..529928528c 100644 --- a/tests/boundary/pcap/pcapCredentialErrors.test.ts +++ b/tests/boundary/pcap/pcapCredentialErrors.test.ts @@ -1,3 +1,4 @@ +import { UnclassifiedProviderFailure } from "../../../src/domain/unclassifiedProviderFailure.js"; import { HOST_PLATFORM } from "../../../src/platform/HostPlatform.js"; import { z } from "zod"; import { existsSync } from "node:fs"; @@ -10,7 +11,6 @@ import { } from "../../../src/pcap/PcapCommand.js"; import { AnalysisCancelledError, - AnalysisProtocolError, AnalysisResourceConstraintError, } from "../../../src/domain/analysisErrorCore.js"; import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js"; @@ -74,8 +74,13 @@ it("preserves producer failure facts while excluding HTTP credentials", async () const failure: unknown = await ownedCommand( `${print}process.exitCode = 7;`, ).catch((cause: unknown) => cause); - expect(failure).toBeInstanceOf(AnalysisProtocolError); - if (!(failure instanceof AnalysisProtocolError)) throw failure; + expect(failure).toBeInstanceOf(UnclassifiedProviderFailure); + if (!(failure instanceof UnclassifiedProviderFailure)) throw failure; + expect(failure.examined).toMatchObject({ + failure_kind: "exited", + exit_code: 7, + }); + expect(projectAnalysisError(failure).code).toBe("execution_failure"); expect(failure.capturedOutput).toMatchObject({ exit_code: 7, truncated: false, diff --git a/tests/boundary/pcap/pcapProvider.test.ts b/tests/boundary/pcap/pcapProvider.test.ts index 945371add0..2c8576209c 100644 --- a/tests/boundary/pcap/pcapProvider.test.ts +++ b/tests/boundary/pcap/pcapProvider.test.ts @@ -972,6 +972,19 @@ it("requests HTTP/2 URI facts and projects them through capture inspection", asy expect(result.coverage).toBe("complete"); }); +it("keeps the packet summary when only the DNS wire pass exits unsuccessfully", async () => { + const { provider, root } = await providerWith({ failDnsPass: true }); + const result = await provider.execute({ + operation: "inspect_pcap_capture", + input: { path: await captureFixture(root) }, + }); + if (!result.ok) throw result.error; + expect(result.value.result).toMatchObject({ + coverage: "partial", + packet_count: 3, + }); +}); + it("reports partial DNS coverage when raw extraction fails without selected DNS facts", async () => { const base: { _source: { layers: Record } }[] = JSON.parse(TSHARK_JSON); diff --git a/tests/boundary/pcap/pcapProviderCancellation.test.ts b/tests/boundary/pcap/pcapProviderCancellation.test.ts index ae378b34e2..6dac363392 100644 --- a/tests/boundary/pcap/pcapProviderCancellation.test.ts +++ b/tests/boundary/pcap/pcapProviderCancellation.test.ts @@ -1,3 +1,4 @@ +import { UnclassifiedProviderFailure } from "../../../src/domain/unclassifiedProviderFailure.js"; import { realpath, writeFile } from "node:fs/promises"; import { dirname, join } from "node:path"; import { expect, onTestFinished, test, vi } from "vitest"; @@ -368,7 +369,7 @@ it("a physical command failure survives a late cancellation and cleanup retry", if (result.ok) return; const returned = result.error; const primary = returned.cleanupPrimary; - expect(primary?._tag).toBe("AnalysisProtocolError"); + expect(primary).toBeInstanceOf(UnclassifiedProviderFailure); expect(primary?.cause).not.toBe(reason); expect(projectAnalysisError(returned).code).toBe("cleanup_incomplete"); expect(returned.capturedOutput?.stderr).toContain( diff --git a/tests/boundary/process/binarySessionCleanupRetry.test.ts b/tests/boundary/process/binarySessionCleanupRetry.test.ts index d530aa4581..6baa9533ed 100644 --- a/tests/boundary/process/binarySessionCleanupRetry.test.ts +++ b/tests/boundary/process/binarySessionCleanupRetry.test.ts @@ -2,14 +2,14 @@ import { access, mkdtemp, rmdir } from "node:fs/promises"; import { expect, it, onTestFinished } from "vitest"; import { createAnalysisExecution } from "../../../src/ports/AnalysisProvider.js"; -import { HopperStartError } from "../../../src/domain/hopperErrors.js"; +import { HopperStartError } from "../../../src/hopper/HopperErrors.js"; import { err, ok as resultOk } from "../../../src/domain/result.js"; import type { BridgeLauncher, BridgeSession, } from "../../../src/hopper/BridgeLauncher.js"; import { HopperClient } from "../../../src/hopper/HopperClient.js"; -import { acquireHopperTargetLease } from "../../../src/process/HopperLease.js"; +import { acquireHopperTargetLease } from "../../../src/hopper/HopperLease.js"; import { cleanupOwnedProcessGroup } from "../../../src/process/ProcessOwnership.js"; import { spawnOwnedProviderProcess } from "../../../src/process/ProviderProcess.js"; import { hopperFixturePath } from "../providers/hopper/hopperClient.fixture.js"; diff --git a/tests/boundary/process/ghidraJavaLifecycle.test.ts b/tests/boundary/process/ghidraJavaLifecycle.test.ts index 173c831b2b..9793d3d78e 100644 --- a/tests/boundary/process/ghidraJavaLifecycle.test.ts +++ b/tests/boundary/process/ghidraJavaLifecycle.test.ts @@ -177,7 +177,10 @@ posix.each([true, false])( code: "version_unresolved", cancellation: { reason }, }); - if (result.error._tag !== "GhidraJavaProbeFailure") + if ( + result.error instanceof AnalysisError || + result.error._tag !== "GhidraJavaProbeFailure" + ) throw new Error("Expected the invalid Java report"); expect(result.error.cancellation?.reason).toBe(reason); expect(Object.keys(result.error)).not.toContain("cancellation"); @@ -234,6 +237,7 @@ posix( if ( result.ok || launched === undefined || + result.error instanceof AnalysisError || result.error._tag !== "GhidraJavaProbeFailure" ) throw new Error("Expected incomplete-output deadline failure"); diff --git a/tests/boundary/providers/ghidra/ghidraFileFailure.test.ts b/tests/boundary/providers/ghidra/ghidraFileFailure.test.ts index 6a780abadc..2729c8bb5e 100644 --- a/tests/boundary/providers/ghidra/ghidraFileFailure.test.ts +++ b/tests/boundary/providers/ghidra/ghidraFileFailure.test.ts @@ -1,9 +1,10 @@ import { unknownTarget } from "../../../../src/domain/targetIdentity.js"; import { open, writeFile, type FileHandle } from "node:fs/promises"; +import { classifyProviderFailure } from "../../../../src/providers/classifyProviderFailure.js"; import { join } from "node:path"; import { expect, it } from "vitest"; -import { ghidraFileFailure } from "../../../../src/ghidra/GhidraFileArtifacts.js"; +import { ghidraFileDialect } from "../../../../src/ghidra/GhidraFileArtifacts.js"; import { ArtifactFileCleanupFailure, mapArtifactFileFailure, @@ -127,9 +128,12 @@ it.each(["opaque", "errno", "authored"] as const)( kind === "authored" ? mapArtifactFileFailure(owned.failure, () => authored) : owned.failure; - const error = ghidraFileFailure(projected, "resolve_analysis_profile", { - path, - }); + const error = classifyProviderFailure( + projected, + ghidraFileDialect("resolve_analysis_profile", { + path, + }), + ); const plist = nativePlistFailure(projected, { path, origin: "selected" }); const dispatch = appleDispatchMetadataFailure(projected, path); const errors = [error, plist, dispatch]; diff --git a/tests/boundary/providers/hopper/bridgeBootstrapCleanup.test.ts b/tests/boundary/providers/hopper/bridgeBootstrapCleanup.test.ts index e059ebebc8..da92f9583d 100644 --- a/tests/boundary/providers/hopper/bridgeBootstrapCleanup.test.ts +++ b/tests/boundary/providers/hopper/bridgeBootstrapCleanup.test.ts @@ -3,7 +3,7 @@ import { join } from "node:path"; import { expect, it, onTestFinished, vi } from "vitest"; -import { HopperCancelledError } from "../../../../src/domain/hopperErrors.js"; +import { HopperCancelledError } from "../../../../src/hopper/HopperErrors.js"; import { HopperApplicationLauncher } from "../../../../src/hopper/BridgeLauncher.js"; import { HopperClient } from "../../../../src/hopper/HopperClient.js"; import { createTestTempDirectory } from "../../../fixtures/temporaryDirectory.js"; diff --git a/tests/boundary/providers/hopper/bridgeTargetLease.integration.test.ts b/tests/boundary/providers/hopper/bridgeTargetLease.integration.test.ts index 24881779b9..82e6e2ae7d 100644 --- a/tests/boundary/providers/hopper/bridgeTargetLease.integration.test.ts +++ b/tests/boundary/providers/hopper/bridgeTargetLease.integration.test.ts @@ -1,7 +1,7 @@ import { describe, expect, it } from "vitest"; import { HopperApplicationLauncher } from "../../../../src/hopper/BridgeLauncher.js"; -import { HopperStartError } from "../../../../src/domain/hopperErrors.js"; +import { HopperStartError } from "../../../../src/hopper/HopperErrors.js"; describe("Linux Hopper application leases in the launcher", () => { it.each(["/first-target", "/different-target"])( diff --git a/tests/boundary/providers/hopper/hopperClient.cleanupRetry.test.ts b/tests/boundary/providers/hopper/hopperClient.cleanupRetry.test.ts index ae0dc3df5b..64c5a0ef25 100644 --- a/tests/boundary/providers/hopper/hopperClient.cleanupRetry.test.ts +++ b/tests/boundary/providers/hopper/hopperClient.cleanupRetry.test.ts @@ -7,7 +7,7 @@ import { expect, it, onTestFinished } from "vitest"; import { AnalysisCleanupRelease } from "../../../../src/domain/analysisCleanupRelease.js"; import { projectAnalysisError } from "../../../../src/domain/analysisErrorProjection.js"; -import { HopperStartError } from "../../../../src/domain/hopperErrors.js"; +import { HopperStartError } from "../../../../src/hopper/HopperErrors.js"; import { ProviderCleanupError } from "../../../../src/domain/providerCleanupError.js"; import { err, ok } from "../../../../src/domain/result.js"; import type { diff --git a/tests/boundary/providers/hopper/hopperClient.diagnostics.test.ts b/tests/boundary/providers/hopper/hopperClient.diagnostics.test.ts index 5708bf46a4..a77273e836 100644 --- a/tests/boundary/providers/hopper/hopperClient.diagnostics.test.ts +++ b/tests/boundary/providers/hopper/hopperClient.diagnostics.test.ts @@ -6,7 +6,7 @@ import { access } from "node:fs/promises"; import { expect, it, onTestFinished } from "vitest"; -import { HopperTimeoutError } from "../../../../src/domain/hopperErrors.js"; +import { HopperTimeoutError } from "../../../../src/hopper/HopperErrors.js"; import { HopperClient } from "../../../../src/hopper/HopperClient.js"; import { waitFor } from "../../../support/testWait.js"; diff --git a/tests/boundary/providers/hopper/hopperClient.helperFailure.test.ts b/tests/boundary/providers/hopper/hopperClient.helperFailure.test.ts index a07eee5505..2bed5d9ef1 100644 --- a/tests/boundary/providers/hopper/hopperClient.helperFailure.test.ts +++ b/tests/boundary/providers/hopper/hopperClient.helperFailure.test.ts @@ -20,7 +20,7 @@ import type { } from "../../../../src/hopper/BridgeLauncher.js"; import { HopperApplicationLauncher } from "../../../../src/hopper/BridgeLauncher.js"; import { HopperClient } from "../../../../src/hopper/HopperClient.js"; -import { acquireHopperTargetLease } from "../../../../src/process/HopperLease.js"; +import { acquireHopperTargetLease } from "../../../../src/hopper/HopperLease.js"; // Failure assertions keep the external document unknown. Teardown then publishes // this run's authenticated bridge so normal cleanup can release its runtime/lease. diff --git a/tests/boundary/providers/hopper/hopperClient.protocol.test.ts b/tests/boundary/providers/hopper/hopperClient.protocol.test.ts index f6c2f80a03..75d25c3df0 100644 --- a/tests/boundary/providers/hopper/hopperClient.protocol.test.ts +++ b/tests/boundary/providers/hopper/hopperClient.protocol.test.ts @@ -9,7 +9,7 @@ import { once } from "node:events"; import { describe, expect, expectTypeOf, it, onTestFinished } from "vitest"; import { z } from "zod"; -import { HopperProcessError } from "../../../../src/domain/hopperErrors.js"; +import { HopperProcessError } from "../../../../src/hopper/HopperErrors.js"; import { HOPPER_OPERATIONS } from "../../../../src/hopper/HopperProviderMetadata.js"; import { HopperClient } from "../../../../src/hopper/HopperClient.js"; import { HopperReplyContractError } from "../../../../src/hopper/HopperReplyContracts.js"; diff --git a/tests/boundary/providers/hopper/hopperClient.startupFailures.test.ts b/tests/boundary/providers/hopper/hopperClient.startupFailures.test.ts index a41c4be0fa..2d3498d236 100644 --- a/tests/boundary/providers/hopper/hopperClient.startupFailures.test.ts +++ b/tests/boundary/providers/hopper/hopperClient.startupFailures.test.ts @@ -10,7 +10,7 @@ import { createServer } from "node:net"; import { afterEach, describe, expect, it } from "vitest"; import { projectAnalysisError } from "../../../../src/domain/analysisErrorProjection.js"; -import type { HopperStartupDiagnostic } from "../../../../src/domain/hopperStartupFailure.js"; +import type { HopperStartupDiagnostic } from "../../../../src/hopper/HopperStartupFailure.js"; import { ok } from "../../../../src/domain/result.js"; import type { BridgeLauncher, diff --git a/tests/boundary/providers/hopper/hopperClient.startupWaiters.test.ts b/tests/boundary/providers/hopper/hopperClient.startupWaiters.test.ts index 088d6d607e..53e05ee004 100644 --- a/tests/boundary/providers/hopper/hopperClient.startupWaiters.test.ts +++ b/tests/boundary/providers/hopper/hopperClient.startupWaiters.test.ts @@ -11,7 +11,7 @@ import { expect, it, vi } from "vitest"; import { HopperCancelledError, HopperProcessError, -} from "../../../../src/domain/hopperErrors.js"; +} from "../../../../src/hopper/HopperErrors.js"; import { HopperClient } from "../../../../src/hopper/HopperClient.js"; import { ok } from "../../../../src/domain/result.js"; import { ProviderRunLineage } from "../../../../src/process/ProviderRunLineage.js"; diff --git a/tests/boundary/providers/hopper/hopperClientObservedExitPriority.test.ts b/tests/boundary/providers/hopper/hopperClientObservedExitPriority.test.ts index 0a856f5661..d4b6c60f9b 100644 --- a/tests/boundary/providers/hopper/hopperClientObservedExitPriority.test.ts +++ b/tests/boundary/providers/hopper/hopperClientObservedExitPriority.test.ts @@ -5,7 +5,7 @@ import { describe, expect, it } from "vitest"; import { HopperCancelledError, HopperProcessError, -} from "../../../../src/domain/hopperErrors.js"; +} from "../../../../src/hopper/HopperErrors.js"; import { ok } from "../../../../src/domain/result.js"; import type { BridgeLauncher, diff --git a/tests/boundary/providers/hopper/hopperMacLaunchArguments.test.ts b/tests/boundary/providers/hopper/hopperMacLaunchArguments.test.ts index 8a6bdc090c..6d31c20a14 100644 --- a/tests/boundary/providers/hopper/hopperMacLaunchArguments.test.ts +++ b/tests/boundary/providers/hopper/hopperMacLaunchArguments.test.ts @@ -11,7 +11,7 @@ import { projectAnalysisError } from "../../../../src/domain/analysisErrorProjec import { HopperStartError, type HopperLaunchRejection, -} from "../../../../src/domain/hopperErrors.js"; +} from "../../../../src/hopper/HopperErrors.js"; import { execFileOutput } from "../../../../src/process/ExecFileOutput.js"; import { createTestTempDirectory } from "../../../fixtures/temporaryDirectory.js"; diff --git a/tests/boundary/providers/hopper/hopperRegexFailure.test.ts b/tests/boundary/providers/hopper/hopperRegexFailure.test.ts index 923393db92..978f80e3af 100644 --- a/tests/boundary/providers/hopper/hopperRegexFailure.test.ts +++ b/tests/boundary/providers/hopper/hopperRegexFailure.test.ts @@ -1,7 +1,7 @@ import { HopperClient } from "../../../../src/hopper/HopperClient.js"; import { expect, it } from "vitest"; import { HopperRegexSearch } from "../../../../src/hopper/HopperRegexSearch.js"; -import { HopperRemoteError } from "../../../../src/domain/hopperErrors.js"; +import { HopperRemoteError } from "../../../../src/hopper/HopperErrors.js"; import { projectAnalysisError } from "../../../../src/domain/analysisErrorProjection.js"; import { HopperFixtureLauncher, diff --git a/tests/boundary/providers/hopper/hopperVerificationCleanup.test.ts b/tests/boundary/providers/hopper/hopperVerificationCleanup.test.ts index 704672da28..90cab03ccb 100644 --- a/tests/boundary/providers/hopper/hopperVerificationCleanup.test.ts +++ b/tests/boundary/providers/hopper/hopperVerificationCleanup.test.ts @@ -3,7 +3,7 @@ import { join } from "node:path"; import { expect, it, onTestFinished } from "vitest"; import { snapshotHopperRuntime } from "../../../../scripts/lib/real-hopper-cleanup.mjs"; -import { acquireHopperTargetLease } from "../../../../src/process/HopperLease.js"; +import { acquireHopperTargetLease } from "../../../../src/hopper/HopperLease.js"; import { createTestTempDirectory } from "../../../fixtures/temporaryDirectory.js"; it.skipIf(process.platform === "win32")( diff --git a/tests/boundary/providers/hopper/linuxPrivateDisplay.test.ts b/tests/boundary/providers/hopper/linuxPrivateDisplay.test.ts index a12b5ad2a2..fa0f9bd5c9 100644 --- a/tests/boundary/providers/hopper/linuxPrivateDisplay.test.ts +++ b/tests/boundary/providers/hopper/linuxPrivateDisplay.test.ts @@ -14,9 +14,9 @@ import { MINIMUM_HOPPER_DEMO_DIALOG_TIMEOUT_MS, type HopperStartupDiagnostic, type HopperStartupFailureCode, -} from "../../../../src/domain/hopperStartupFailure.js"; +} from "../../../../src/hopper/HopperStartupFailure.js"; import { projectAnalysisError } from "../../../../src/domain/analysisErrorProjection.js"; -import { HopperProcessError } from "../../../../src/domain/hopperErrors.js"; +import { HopperProcessError } from "../../../../src/hopper/HopperErrors.js"; import { analysisErrorProjectionSchema } from "../../../../src/domain/analysisErrorProjectionSchema.js"; import { runLinuxPrivateDisplayProbe, diff --git a/tests/boundary/providers/kuna/kunaHashOwnerPropagation.test.ts b/tests/boundary/providers/kuna/kunaHashOwnerPropagation.test.ts index 929b5ba7ed..e37e883ab2 100644 --- a/tests/boundary/providers/kuna/kunaHashOwnerPropagation.test.ts +++ b/tests/boundary/providers/kuna/kunaHashOwnerPropagation.test.ts @@ -742,6 +742,50 @@ it.skipIf(process.platform === "win32")( }, ); +it.skipIf(process.platform === "win32")( + "keeps the Kuna installation facts on a doctor check whose read and close both failed", + async () => { + const fixture = await session("rea-kuna-doctor-read-and-close-"); + const resources = new ArtifactResourceScope(); + const resourceScope: RetainedResourceScope = { + retain: (owner, resource) => + resources.retain({ + kind: "lease", + resource, + lease: { release: () => owner.close() }, + }), + run: (operation) => resources.run(operation), + }; + injected.installationPath = fixture.kuna; + injected.fingerprintReads = 0; + injected.failReadStage = "preProbeFingerprint"; + try { + const inspection = await inspectKunaProvider( + { + REA_KUNA_COMMAND: fixture.kuna, + REA_KUNA_CACHE_DIR: fixture.cacheRoot, + }, + process.platform, + { resourceScope }, + ); + expect( + inspection.checks.find(({ name }) => name === "version"), + ).toMatchObject({ + ok: false, + code: "cleanup_incomplete", + details: { + cleanup_incomplete: true, + cleanup_resources: [expect.stringContaining(fixture.kuna)], + kuna_installation: { command: fixture.kuna }, + }, + }); + } finally { + injected.failReadStage = undefined; + await resources.close(); + } + }, +); + it.skipIf(process.platform === "win32")( "retains a failed Kuna doctor hash in the supplied lifecycle owner", async () => { @@ -772,6 +816,10 @@ it.skipIf(process.platform === "win32")( ).toMatchObject({ ok: false, code: "cleanup_incomplete", + details: { + cleanup_incomplete: true, + cleanup_resources: [expect.stringContaining(fixture.kuna)], + }, }); expect(injected.closeCalls).toBe(1); await resources.close(); diff --git a/tests/boundary/setup/linuxHopperPublisherVerification.test.ts b/tests/boundary/setup/linuxHopperPublisherVerification.test.ts index 3696a3a06a..c929badba5 100644 --- a/tests/boundary/setup/linuxHopperPublisherVerification.test.ts +++ b/tests/boundary/setup/linuxHopperPublisherVerification.test.ts @@ -762,6 +762,8 @@ linux( cacheDirectory: f.publisher.cacheRoot, launcherSha256: f.release.main_exe_hash, runId: "fixture-competing-writer", + failure: (failure: { readonly kind: string }) => + new Error(`Fixture cache lease failed: ${failure.kind}`), }; expect(await acquire(input)).toMatchObject({ acquired: false }); await expect(f.publisher.close()).rejects.toMatchObject({ diff --git a/tests/boundary/sqlite/sqliteDatabaseFailures.test.ts b/tests/boundary/sqlite/sqliteDatabaseFailures.test.ts index a345b8515e..9479cc579c 100644 --- a/tests/boundary/sqlite/sqliteDatabaseFailures.test.ts +++ b/tests/boundary/sqlite/sqliteDatabaseFailures.test.ts @@ -101,13 +101,23 @@ it("does not recommend a timer above the supported maximum", () => { expect(failure.remediation.action).not.toContain("Increase"); }); -it("says diagnostic capture has no runtime override", () => { +it("reports exceeded diagnostic capture as a fixed resource constraint", () => { const projected = projectAnalysisError( classifyProviderFailure( new OwnedCommandFailure("output-limit", "diagnostics exceeded"), sqliteDatabaseDialect("/selected.db", "worker"), ), ); + expect(projected).toMatchObject({ + code: "resource_constraint", + retryable: false, + details: { + operation: "inspect_sqlite_database", + reported_limits: { + diagnostic_capture_bytes: SQLITE_DATABASE_LIMITS.diagnosticBytes, + }, + }, + }); expect(projected.remediation.action).toContain( String(SQLITE_DATABASE_LIMITS.diagnosticBytes), ); diff --git a/tests/boundary/sqlite/sqliteDatabaseProvider.test.ts b/tests/boundary/sqlite/sqliteDatabaseProvider.test.ts index ea921be9bf..85f4cc57bd 100644 --- a/tests/boundary/sqlite/sqliteDatabaseProvider.test.ts +++ b/tests/boundary/sqlite/sqliteDatabaseProvider.test.ts @@ -1178,7 +1178,8 @@ nativeTest( error: { _tag: "ProviderAdapterError", diagnostics: { - failure_kind: "process", + failure_kind: "exited", + stop_requested: false, exit_code: 7, captured_output: { stderr: "authored SQLite worker failure", @@ -1441,7 +1442,7 @@ nativeTest( nativeTest.each([ ["cancelled", "cancelled"], - ["output-limit", "unreadable_output"], + ["output-limit", "resource_constraint"], ["heap-diagnostic", "resource_constraint"], ] as const)( "preserves the typed %s worker failure through retained cleanup retry", diff --git a/tests/composition/analysis-sessions/binarySession.test.ts b/tests/composition/analysis-sessions/binarySession.test.ts index 857d5a39d2..e54998ae9c 100644 --- a/tests/composition/analysis-sessions/binarySession.test.ts +++ b/tests/composition/analysis-sessions/binarySession.test.ts @@ -15,7 +15,7 @@ import type { JsonValue } from "../../../src/domain/jsonValue.js"; import type { RecordUnknownInput } from "../../../src/domain/residualUnknown.js"; import { createAnalysisProfile } from "../../../src/domain/analysisProfile.js"; import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js"; -import { HopperStartError } from "../../../src/domain/hopperErrors.js"; +import { HopperStartError } from "../../../src/hopper/HopperErrors.js"; import { ProviderAdapterError } from "../../../src/domain/providerAdapterError.js"; import { ProviderCleanupError } from "../../../src/domain/providerCleanupError.js"; import { AnalysisCleanupLease } from "../../../src/resources/AnalysisCleanupLease.js"; diff --git a/tests/composition/analysis-sessions/binarySessionCleanupRetry.test.ts b/tests/composition/analysis-sessions/binarySessionCleanupRetry.test.ts index 466ad708cb..a8c26d003b 100644 --- a/tests/composition/analysis-sessions/binarySessionCleanupRetry.test.ts +++ b/tests/composition/analysis-sessions/binarySessionCleanupRetry.test.ts @@ -11,7 +11,7 @@ import type { AnalysisProvider, } from "../../../src/ports/AnalysisProvider.js"; import { AnalysisCancelledError } from "../../../src/domain/analysisErrorCore.js"; -import { HopperStartError } from "../../../src/domain/hopperErrors.js"; +import { HopperStartError } from "../../../src/hopper/HopperErrors.js"; import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js"; import { ProviderCleanupError } from "../../../src/domain/providerCleanupError.js"; import { err, ok as resultOk } from "../../../src/domain/result.js"; diff --git a/tests/composition/reverseEngineeringAdmission.test.ts b/tests/composition/reverseEngineeringAdmission.test.ts index 0c66fa7b0d..117794617c 100644 --- a/tests/composition/reverseEngineeringAdmission.test.ts +++ b/tests/composition/reverseEngineeringAdmission.test.ts @@ -234,6 +234,32 @@ it("keeps an unrelated digest ABORT_ERR as an adapter failure", async () => { } }); +it("does not report a command ABORT_ERR without the caller's abort as cancellation", async () => { + const directory = await mkdtemp(join(tmpdir(), "rea-reverse-command-abort-")); + const path = join(directory, "fixture.bin"); + await writeFile(path, "fixture"); + const failure = Object.assign(new Error("aborted by another signal"), { + code: "ABORT_ERR", + }); + const service = new TestReverseEngineeringService({ + runOwned: async () => { + throw failure; + }, + }); + try { + const result = await service.inspectWithObjdump( + { path, operation: "symbols" }, + { signal: new AbortController().signal }, + ); + expect(result.ok).toBe(false); + if (result.ok) return; + expect(result.error._tag).not.toBe("AnalysisCancelledError"); + } finally { + await service.close(); + await rm(directory, { recursive: true, force: true }); + } +}); + it.each([ { captured: false, diff --git a/tests/conformance/contracts/analysisErrorProjection.test.ts b/tests/conformance/contracts/analysisErrorProjection.test.ts index 4097623057..2dea9887e2 100644 --- a/tests/conformance/contracts/analysisErrorProjection.test.ts +++ b/tests/conformance/contracts/analysisErrorProjection.test.ts @@ -6,7 +6,7 @@ import { analysisErrorJsonSchema } from "../../../src/contracts/errorSchemas.js" import { analysisErrorProjectionSchema } from "../../../src/domain/analysisErrorProjectionSchema.js"; import { ArtifactOperationError } from "../../../src/domain/artifactOperationError.js"; import { EvidenceFileError } from "../../../src/domain/evidenceErrors.js"; -import { HopperRemoteError } from "../../../src/domain/hopperErrors.js"; +import { HopperRemoteError } from "../../../src/hopper/HopperErrors.js"; import { UnknownRegistryError } from "../../../src/domain/unknownRegistryError.js"; import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js"; import { BrowserObservationError } from "../../../src/domain/browserObservationError.js"; diff --git a/tests/fixtures/binarySession.ts b/tests/fixtures/binarySession.ts index b94318fa58..125b4f6e5a 100644 --- a/tests/fixtures/binarySession.ts +++ b/tests/fixtures/binarySession.ts @@ -4,7 +4,7 @@ import { join } from "node:path"; import { createAnalysisProfile } from "../../src/domain/analysisProfile.js"; import type { BinaryTarget } from "../../src/domain/binaryTargetTypes.js"; import type { AnalysisError } from "../../src/domain/analysisErrorBase.js"; -import { HopperStartError } from "../../src/domain/hopperErrors.js"; +import { HopperStartError } from "../../src/hopper/HopperErrors.js"; import type { Result } from "../../src/domain/result.js"; import type { AnalysisClient, diff --git a/tests/fixtures/hopperCachePublisher.mjs b/tests/fixtures/hopperCachePublisher.mjs index 3a49ed3f9c..c78650be4a 100644 --- a/tests/fixtures/hopperCachePublisher.mjs +++ b/tests/fixtures/hopperCachePublisher.mjs @@ -15,6 +15,8 @@ const acquired = await acquireHopperReleaseCacheLease({ cacheDirectory, launcherSha256, runId: randomUUID(), + failure: (failure) => + new Error(`Fixture cache lease failed: ${failure.kind}`), }); if (!acquired.acquired) throw new Error("Fixture cache lease was already held"); try { diff --git a/tests/fixtures/pcap/pcapTestTools.ts b/tests/fixtures/pcap/pcapTestTools.ts index a4a67c54ef..7acddc341e 100644 --- a/tests/fixtures/pcap/pcapTestTools.ts +++ b/tests/fixtures/pcap/pcapTestTools.ts @@ -93,6 +93,8 @@ export const TSHARK_DNS_JSON = JSON.stringify([ export interface PcapStubToolsOptions { readonly failCapinfos?: boolean; readonly malformedDnsJson?: boolean; + /** The DNS wire pass exits 5 with a stderr diagnostic. */ + readonly failDnsPass?: boolean; readonly dnsJson?: string; readonly tsharkJson?: string; readonly capinfosText?: string; @@ -143,6 +145,7 @@ case " $* " in case " $* " in *" --no-duplicate-keys "*) ;; *) exit 2 ;; esac case " $* " in *" -J frame dns mdns llmnr "*) ;; *) exit 2 ;; esac case " $* " in *" -Y dns || mdns || llmnr "*) ;; *) exit 2 ;; esac + ${options.failDnsPass ? `printf 'dns pass failed' >&2; exit 5` : ""} printf '%s' '${(options.malformedDnsJson ? "{" : (options.dnsJson ?? TSHARK_DNS_JSON)).replace(/'/gu, "'\\''")}' exit 0 ;; diff --git a/tests/process-global/hopperLeaseDescriptorPermissions.test.ts b/tests/process-global/hopperLeaseDescriptorPermissions.test.ts index 92a6e19e63..3244e7dace 100644 --- a/tests/process-global/hopperLeaseDescriptorPermissions.test.ts +++ b/tests/process-global/hopperLeaseDescriptorPermissions.test.ts @@ -32,7 +32,7 @@ vi.mock("node:fs/promises", async (importOriginal) => { }; }); -import { acquireLinuxHopperApplicationLease } from "../../src/process/HopperLease.js"; +import { acquireLinuxHopperApplicationLease } from "../../src/hopper/HopperLease.js"; afterEach(() => { replacement.selected = ""; diff --git a/turbo.json b/turbo.json index 3e96046d7d..1840a3627a 100644 --- a/turbo.json +++ b/turbo.json @@ -244,7 +244,10 @@ "scripts/lib/format-generated-file.mjs", ".oxfmtrc.json" ], - "outputs": ["docs/error-contract.schema.json"] + "outputs": [ + "docs/error-contract.schema.json", + "docs/user-visible-errors.csv" + ] }, "mcp-catalog:check:built": { "dependsOn": ["artifacts:mcp-catalog"],