From 2430b081c9bb067f683d906ad2a8948a11593c0d Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Mon, 16 Nov 2026 07:12:16 +0800 Subject: [PATCH] refactor(providers): bind provider refusals' per-call controls instead of naming CLI flags (#11455) * refactor(native): bind producer_limits and max_input_bytes as the per-call controls of pwntools and Apple dispatch refusals producerLimitControl in src/domain/producerResourceLimits.ts names one producer budget as producer_limits.; the shared provider outcome classifier now carries a resource signal's limit. Pwntools file-size, CPU and output refusals and the Apple dispatch input refusal bind their control, and their remediation no longer names CLI flags. * fix(native): report the selected output allowance as the omitted file_bytes default * fix(native): bind producer_limits.diagnostic_bytes as the pwntools command output-limit control * refactor(rust): bind producer_limits as the per-call control of Rust input and report refusals (#11458) * refactor(rust): bind producer_limits as the per-call control of Rust input and report refusals * test(rust): cover the complete-report refusal's producer_limits control * refactor(browser): bind caller-selectable browser deadlines as per-call controls instead of naming CLI flags (#11466) * refactor(rust): bind producer_limits as the per-call control of Rust input and report refusals * test(rust): cover the complete-report refusal's producer_limits control * refactor(browser): bind caller-selectable browser deadlines as per-call controls instead of naming CLI flags deadlineParameterLimit in src/domain/analysisResourceLimits.ts owns the millisecond deadline control that nativeDeadlineRecovery and the browser recoveries share. CDP command and discovery, web bundle per-script and total, network capture and source-map decode deadlines now carry it; browserDeadlineIncrease no longer takes CLI flag text. * fix(browser): record a per-script deadline's parameter control in partial web bundle results * refactor(providers): bind Wabt, SQLite, EVMole, Apktool and Go controls instead of naming CLI commands (#11472) * refactor(providers): bind Wabt, SQLite, EVMole and Apktool deadline and byte controls instead of naming CLI commands These remediation strings named rea commands and flags through template text the cli-option guard did not count. Wabt byte refusals and output limits bind max_input_bytes, max_tool_bytes or max_output_bytes while a larger value is selectable; SQLite worker_timeout_ms, EVMole timeout_ms and Apktool decode_timeout_ms bind through deadlineParameterLimit; the shared provider outcome classifier now carries an output limit's control. * refactor(go): bind Go analysis budgets as per-call controls instead of naming CLI flags * fix(providers): keep the typed primary when Wabt, EVMole or pwntools command cleanup fails * ci(guards): count template-built CLI option and command text outside the CLI layer (#11478) * refactor(providers): bind Wabt, SQLite, EVMole and Apktool deadline and byte controls instead of naming CLI commands These remediation strings named rea commands and flags through template text the cli-option guard did not count. Wabt byte refusals and output limits bind max_input_bytes, max_tool_bytes or max_output_bytes while a larger value is selectable; SQLite worker_timeout_ms, EVMole timeout_ms and Apktool decode_timeout_ms bind through deadlineParameterLimit; the shared provider outcome classifier now carries an output limit's control. * refactor(go): bind Go analysis budgets as per-call controls instead of naming CLI flags * fix(providers): keep the typed primary when Wabt, EVMole or pwntools command cleanup fails * ci(guards): count template-built CLI option and command text outside the CLI layer The cli-option-text-outside-cli pattern now also matches "(CLI ...", "on the CLI", "or use rea ..." and backticked `rea ` references, so remediation built from a template such as --${name} or rea inspect-... is counted. Doctor.ts is exempt: setup and doctor run only through the CLI. The baseline records the newly counted pre-existing sites (22 -> 45 across 21 files). * ci(guards): extract the CLI text matcher, exempt host-only commands with written reasons, and test each spelling * ci(guards): exempt a host-only command and its own arguments in any matched CLI phrase * fix(native): bind producer_limits.output_bytes for oversized pwndbg debugger replies through one owner * fix(cli): name an Evidence target source failure's control by the source option that sets it * feat(cli): render the flags of result-recorded controls in the full-output envelope (#11507) * feat(cli): render the flags of result-recorded controls in the full-output envelope * fix(cli): collect result controls only for a full-output envelope, in its requested format, past undefined values * ci(guards): end a host-only command's arguments before the next CLI command * refactor(reverse): record the output budget that stopped a one-shot command as a parameter control (#11528) * fix(cli): read result controls only at positions the output schema declares as recorded controls * refactor(providers): record the controls that bounded Rust compiler paths and kernel module text instead of naming CLI options (#11532) * refactor(rust): record the control that bounded compiler-path coverage instead of naming CLI options * refactor(native): record the controls that omitted kernel module .modinfo text instead of naming CLI options (#11534) * fix(rust): describe compiler coverage from the retained result after report trimming * refactor(providers): record managed representation and JavaScript semantic ceiling controls instead of naming CLI options (#11537) * refactor(managed): record the representation budget on a resource-limit issue instead of naming its CLI option * refactor(javascript): record the semantic retention ceilings that stopped a graph instead of naming CLI options (#11540) * fix(cli): name a composed command's source options for the controls its result records * fix(cli): read result controls from the delivered Evidence when a summary wraps it * fix(rust): keep the report-byte control recorded when trimming omits every compiler path When the complete-report allowance left room for no compiler path, rustc_commit became null and its coverage.limit was lost, so --full-output could not name the option that raises the allowance. The report now records rustc_commit_omission { reason, limit } outside the dropped record, and the summary view carries it. * refactor(flutter): record the string-pool budgets that left a projection partial instead of naming the CLI option (#11541) * refactor(flutter): record the string-pool budgets that left a projection partial instead of naming the CLI option * test(flutter): assert the complete set of recorded string-pool budgets * feat(cli): name the options of controls a failure's partial Evidence records (#11557) meta.cli_controls was collected only from a successful result. A failure whose partial observation is Evidence of the command's own operation is now read the same way, at the positions the output schema declares as recorded controls; Evidence of another operation or a retained reference is not read. When --evidence_output publishes the partial, the delivery records it before replacing it. * refactor(javascript): record the evaluator budgets that limited sources instead of naming the CLI option (#11564) Per-value unknown reasons and the Electron wrapper limitation named --semantic-precision. The static examination now records the semantic_precision controls that limited a source (examination.controls), and analyze_javascript_application's semantic_graph.coverage.controls records every evaluator budget that limited any source (examination and semantic IR coverage), beside the retention ceilings. The CLI renders --semantic-precision from those records in meta.cli_controls; the reason texts name only the contract field. --- docs/design/limits-and-recovery.md | 7 + docs/kernel-modules.md | 4 +- docs/reverse-engineering-tools.md | 2 +- scripts/verify/architecture-guards.mjs | 19 +- .../cli-option-text-outside-cli.json | 14 +- scripts/verify/cli-text-guard.d.mts | 4 + scripts/verify/cli-text-guard.mjs | 78 ++++++ src/apktool/ApktoolDecodeTimeout.test.ts | 10 +- src/apktool/ApktoolProvider.ts | 16 +- .../JavaScriptArtifactReconstruction.ts | 2 + .../JavaScriptSemanticGraphBuilder.ts | 25 +- .../JavaScriptSemanticPrecisionControls.ts | 35 +++ .../reverse/ReverseEngineeringService.ts | 7 +- src/browser/CdpConnection.ts | 2 + src/browser/CdpEndpoint.ts | 1 + src/browser/IsolatedWebBundleAnalyzer.test.ts | 31 ++- src/cli/analysisEvidenceDelivery.ts | 7 + src/cli/cliResultControls.ts | 53 ++++ src/cli/cliResultOutput.ts | 131 +++++---- src/cli/contractCliDescription.ts | 13 + src/cli/contractCommand.ts | 59 +++- src/cli/jsonLinesOutput.ts | 11 +- src/cli/projectCliAnalysisResult.ts | 157 +++++++++-- src/domain/analysisResourceLimits.ts | 20 ++ src/domain/analysisSettingDefinitions.ts | 40 +++ src/domain/analysisSettings.ts | 6 + src/domain/analysisView/rustBinaryView.ts | 5 + src/domain/browserDeadline.ts | 31 ++- src/domain/commandObservation.ts | 7 + src/domain/flutter/flutterBuildAnalysis.ts | 25 ++ ...javascriptAnalysisResourceControls.test.ts | 47 +++- .../javascriptAnalysisResourceControls.ts | 37 ++- .../javascriptSemanticGraphSchemas.ts | 6 + .../javascriptSemanticPrecision.test.ts | 18 ++ .../javascriptSemanticResourceLimits.ts | 45 +++- .../javascript/javascriptStaticAnalysis.ts | 13 +- .../javascript/javascriptStaticCoverage.ts | 3 + src/domain/managed/managedArtifact.ts | 3 + src/domain/managed/managedDecodeBudget.ts | 8 +- src/domain/managed/managedInspectionLimits.ts | 18 ++ .../managedMemberComparisonCoverage.ts | 14 +- src/domain/native/kernelModule.ts | 29 ++ src/domain/native/nativeDeadlines.ts | 16 +- src/domain/producerResourceLimits.ts | 21 ++ src/domain/reverseEngineering.ts | 17 ++ src/domain/rust/rustBinary.ts | 65 ++++- src/domain/webBundleAnalysis.ts | 30 ++- src/domain/webBundleScriptAnalysis.ts | 59 ++-- src/domain/webDeadlineControls.test.ts | 12 +- src/domain/webNetworkCapture.ts | 11 +- src/domain/webSourceLocation.ts | 11 +- src/evm/EvmoleFailures.test.ts | 8 +- src/evm/EvmoleFailures.ts | 41 +-- src/flutter/FlutterBuildProvider.ts | 29 +- src/go/GoBinaryProvider.ts | 27 +- src/native/AppleDispatchMetadata.ts | 23 +- src/native/elf/KernelModuleParser.ts | 29 +- src/native/pwndbg/PwndbgCoreContext.ts | 6 +- src/native/pwntools/PwntoolsDecoder.ts | 7 +- src/native/pwntools/PwntoolsFailures.test.ts | 81 ++++++ src/native/pwntools/PwntoolsFailures.ts | 84 +++--- src/process/classifyProviderOutcome.ts | 18 +- src/rust/RustBinaryImage.ts | 19 +- src/rust/RustBinaryProvider.ts | 72 +++-- src/sqlite/SqliteDatabaseFailures.ts | 12 +- src/wasm/WabtArtifactProvider.test.ts | 18 +- src/wasm/WabtFailures.test.ts | 42 ++- src/wasm/WabtFailures.ts | 83 +++--- .../javascriptAnalysisLimits.test.ts | 43 +++ .../javascriptUnknownCapacity.test.ts | 6 + .../browser/webBundleContainmentCli.test.ts | 10 + tests/acceptance/kernelModuleCli.test.ts | 17 ++ tests/acceptance/managedCliOutput.test.ts | 31 ++- tests/acceptance/rustBinaryCli.test.ts | 27 ++ tests/acceptance/rustDependencyViews.test.ts | 19 +- .../pwntoolsLayoutProvider.test.ts | 8 +- .../browser/cdpTargetDeadlines.test.ts | 14 +- .../boundary/cli/artifactInputLimits.test.ts | 20 +- tests/boundary/cli/cliResultControls.test.ts | 251 ++++++++++++++++++ .../cli/managedMemberComparisonCli.test.ts | 52 +++- .../cli/nativeDispatchInputBudget.test.ts | 5 + .../appleDispatchMetadataInputBudget.test.ts | 9 +- .../filesystem/flutterBuildProvider.test.ts | 25 ++ tests/boundary/mcp/kernelModuleMcp.test.ts | 25 ++ tests/boundary/mcp/rustBinaryMcp.test.ts | 4 + .../native/pwndbgReplyFinalization.test.ts | 27 ++ .../managed/managedStaticProvider.test.ts | 14 + tests/boundary/rust/rustBinaryBudget.test.ts | 104 +++++++- tests/boundary/rust/rustBinaryImage.test.ts | 10 + .../sqlite/sqliteDatabaseFailures.test.ts | 13 +- tests/composition/reverseEngineering.test.ts | 15 ++ tests/evaluation/cliTextGuard.test.ts | 84 ++++++ 92 files changed, 2334 insertions(+), 403 deletions(-) create mode 100644 scripts/verify/cli-text-guard.d.mts create mode 100644 scripts/verify/cli-text-guard.mjs create mode 100644 src/application/javascript/JavaScriptSemanticPrecisionControls.ts create mode 100644 src/cli/cliResultControls.ts create mode 100644 tests/boundary/cli/cliResultControls.test.ts create mode 100644 tests/evaluation/cliTextGuard.test.ts diff --git a/docs/design/limits-and-recovery.md b/docs/design/limits-and-recovery.md index aaa687a713..ede65e94c3 100644 --- a/docs/design/limits-and-recovery.md +++ b/docs/design/limits-and-recovery.md @@ -300,6 +300,13 @@ A deadline controlled by something other than a registered setting reports remediation text name only that field. A CLI command adds `cli_flag`, the option that sets the field on that command, from its own field-to-flag binding; MCP results do not carry it. +A completed or partial result can record the same reference, for example a +`limit` in a web bundle `unknowns` entry for a script that reached its +`analysis_timeout_ms` deadline. That reference is part of the result and its +Evidence identity, so the CLI never adds to it. Instead, the CLI renders the +flags in its own `--full-output` envelope as `meta.cli_controls`, a map from +each recorded contract field to the option that sets it on that command. The +bare result is the record itself and gains no CLI field. `control_kind: "environment"` names the `environment` variable REA reads when it starts (`REA_SWIFTC_COMPILE_TIMEOUT_MS`): `applies_at` is `next_startup`, or `next_invocation` for a one-shot invocation. Both carry `effective_value`, diff --git a/docs/kernel-modules.md b/docs/kernel-modules.md index 5fa1629662..90405bad34 100644 --- a/docs/kernel-modules.md +++ b/docs/kernel-modules.md @@ -95,7 +95,9 @@ remain available. Raise `max_modinfo_key_bytes` or `max_modinfo_value_bytes` on the next MCP call to retain the omitted text. The returned limitation names the required byte -budget. CLI flags are `--max-modinfo-key-bytes` and `--max-modinfo-value-bytes`. +budget, and `modinfo.omission_limits` records each control that omitted text +(`control_kind: "parameter"`, with its effective value, default and range). +CLI flags are `--max-modinfo-key-bytes` and `--max-modinfo-value-bytes`. Each accepts an integer from 1 through 536870912 bytes, matching the maximum input size. No restart is required; file, entry and raw-hex budgets do not change. These are per-call controls, not runtime settings. diff --git a/docs/reverse-engineering-tools.md b/docs/reverse-engineering-tools.md index 408e5aa258..1082f37e04 100644 --- a/docs/reverse-engineering-tools.md +++ b/docs/reverse-engineering-tools.md @@ -43,7 +43,7 @@ rea inspect-with-objdump ./program dwarf rea inspect-with-objdump ./program dwarf --follow-debug-links ``` -Captured stdout and stderr share `max_output_bytes` (CLI: `--max-output-bytes`), default 16777216 bytes (16 MiB). Select an integer from 1 to 44651859 bytes. The maximum leaves room for worst-case JSON escaping of both Evidence output mirrors under Node's single-string ceiling. The selected budget applies on the next call without a restart; `output_budget_bytes` reports it and `output_budget_source` distinguishes a default from an explicit request. On exhaustion REA retains a prefix, requests provider termination, and marks `output_truncated` with unknown completion. Narrow or page the native command, or raise the selected budget. Verify command effects and outstanding cleanup before deciding whether repeating it is safe. Client deadlines and receive buffers remain separate. Concurrent one-shot captures reserve their selected budgets within a 128 MiB aggregate admission and eight-operation capacity; wait for active work or select a smaller output budget when that capacity is occupied. +Captured stdout and stderr share `max_output_bytes` (CLI: `--max-output-bytes`), default 16777216 bytes (16 MiB). Select an integer from 1 to 44651859 bytes. The maximum leaves room for worst-case JSON escaping of both Evidence output mirrors under Node's single-string ceiling. The selected budget applies on the next call without a restart; `output_budget_bytes` reports it and `output_budget_source` distinguishes a default from an explicit request. On exhaustion REA retains a prefix, requests provider termination, marks `output_truncated` with unknown completion, and records the budget as `output_limit`, a `max_output_bytes` parameter control (the CLI `--full-output` envelope names its option in `meta.cli_controls`). Narrow or page the native command, or raise the selected budget. Verify command effects and outstanding cleanup before deciding whether repeating it is safe. Client deadlines and receive buffers remain separate. Concurrent one-shot captures reserve their selected budgets within a 128 MiB aggregate admission and eight-operation capacity; wait for active work or select a smaller output budget when that capacity is occupied. `inspect_with_objdump`, `rea list-objdump-architectures`, and one-shot `execute_rizin_command` accept `command_timeout_ms` (CLI: `--command-timeout-ms`). Omitted means 120000. The integer range is 1 to 2147483647. Target preflight shares one budget across stat and digest. The one-shot command receives that budget again. It applies on the next call; no restart is required. It does not raise the separately selected `max_output_bytes`, a Ghidra or Hopper startup deadline, or a debugger session deadline. diff --git a/scripts/verify/architecture-guards.mjs b/scripts/verify/architecture-guards.mjs index 07dfd8862c..1d486592a3 100644 --- a/scripts/verify/architecture-guards.mjs +++ b/scripts/verify/architecture-guards.mjs @@ -11,6 +11,10 @@ import { localCompletenessEnumCount } from "./completeness-enum-guard.mjs"; import { countKeyedFirstMatches } from "./keyed-first-match.mjs"; import { budgetArithmeticCount } from "./budget-arithmetic-guard.mjs"; import { localLimitErrorClassCount } from "./limit-class-guard.mjs"; +import { + cliTextGuardSelects, + cliTextOutsideCliCount, +} from "./cli-text-guard.mjs"; import { TOOL_REGISTRATION_OWNERS, toolRegistrationCount, @@ -576,18 +580,13 @@ checkCounted( ["src/gdb/GdbMiRecord.ts"], ); -// Services name the contract field they refuse or ask the caller to change; -// the CLI layer owns option spellings (each command's field binding renames -// issue paths to CLI keys). A `--flag` written outside src/cli copies that -// mapping and goes stale when the command renames the option. +// src/cli owns option and command spellings; cli-text-guard.mjs states the +// rule and its written exemptions (host-only commands, CLI-only files). checkCounted( - "REA CLI option named outside the CLI layer (name the contract field; src/cli owns option spellings)", + "REA CLI option or command named outside the CLI layer (name the contract field or operation; src/cli owns option and command spellings)", "cli-option-text-outside-cli", - files.filter( - ({ path }) => - !path.startsWith("src/cli/") && !/^src\/cli[^/]*\.ts$/u.test(path), - ), - /\(CLI:? [^)\n]*--[a-z]|--[a-z][a-z0-9-]* on the CLI|or (?:use|pass) --[a-z]|\bcli(?:Flag|Total|PerFile)?:\s*"--[a-z]|(?:message|userMessage):\s*["`]--[a-z]/gu, + files.filter(({ path }) => cliTextGuardSelects(path)), + cliTextOutsideCliCount, [], ); diff --git a/scripts/verify/baselines/cli-option-text-outside-cli.json b/scripts/verify/baselines/cli-option-text-outside-cli.json index 054965a123..2698b01270 100644 --- a/scripts/verify/baselines/cli-option-text-outside-cli.json +++ b/scripts/verify/baselines/cli-option-text-outside-cli.json @@ -1,20 +1,12 @@ { - "src/application/Doctor.ts": 1, "src/application/EvidenceBundleFiles.ts": 1, "src/application/decompileDirectory/decompileAll.ts": 1, - "src/application/reverse/ReverseEngineeringService.ts": 1, - "src/domain/analysisErrorPresentation.ts": 2, - "src/domain/javascript/javascriptAnalysisResourceControls.ts": 4, - "src/domain/javascript/javascriptSemanticResourceLimits.ts": 1, - "src/domain/managed/managedDecodeBudget.ts": 1, + "src/domain/analysisErrorPresentation.ts": 6, "src/dotnet/ManagedMemberRecovery.ts": 1, "src/ghidra/GhidraFileOffsetFailure.ts": 1, - "src/ghidra/GhidraProviderClient.ts": 2, + "src/ghidra/GhidraProviderClient.ts": 5, "src/javascript/analysis/JavaScriptAnalysisWorker.ts": 1, - "src/native/AppleDispatchMetadata.ts": 1, + "src/kuna/KunaProjectReader.ts": 1, "src/native/NativePlistSource.ts": 1, - "src/native/pwntools/PwntoolsDecoder.ts": 2, - "src/native/pwntools/PwntoolsFailures.ts": 4, - "src/rust/RustBinaryProvider.ts": 6, "src/sqlite/SqliteDatabaseWorkerExecution.ts": 1 } diff --git a/scripts/verify/cli-text-guard.d.mts b/scripts/verify/cli-text-guard.d.mts new file mode 100644 index 0000000000..9ab2d72418 --- /dev/null +++ b/scripts/verify/cli-text-guard.d.mts @@ -0,0 +1,4 @@ +export const HOST_ONLY_COMMANDS: ReadonlyMap; +export const CLI_ONLY_FILES: ReadonlyMap; +export function cliTextGuardSelects(path: string): boolean; +export function cliTextOutsideCliCount(content: string): number; diff --git a/scripts/verify/cli-text-guard.mjs b/scripts/verify/cli-text-guard.mjs new file mode 100644 index 0000000000..ea1f131e83 --- /dev/null +++ b/scripts/verify/cli-text-guard.mjs @@ -0,0 +1,78 @@ +// Services name the contract field they refuse or ask the caller to change, +// and a failure binds its per-call control as `limit`; the CLI layer owns +// option and command spellings (projectCliInputFields adds `cli_flag`). A +// `--flag`, "on the CLI" or `rea ` written outside src/cli copies +// that mapping into output MCP clients also receive, including text built +// from a template such as `--${name}` or `rea inspect-... `. +const cliText = + /\(CLI\b[^)\n]*|\bon the CLI\b|\bor (?:use|pass) (?:--[a-z]|rea [a-z][a-z-]*)|\bcli(?:Flag|Total|PerFile)?:\s*"--[a-z]|(?:message|userMessage):\s*["`]--[a-z]|`rea [a-z][a-z-]*/gu; + +/** + * Host commands with no MCP operation. Telling an operator to run one is an + * operator instruction, not a copy of an adapter spelling, so the text stays + * where it is (maintainer decision on #11476). + * @type {ReadonlyMap} + */ +export const HOST_ONLY_COMMANDS = new Map([ + [ + "doctor", + "Checks the host installation and provider readiness; no MCP operation does this.", + ], + [ + "setup", + "Installs and configures providers on the host after operator approval; no MCP operation does this.", + ], + [ + "environment-serve", + "Starts a host environment server process; no MCP operation does this.", + ], +]); + +/** + * Files that run only through the CLI, so their recovery may name CLI + * options. Each entry gives the reason. + * @type {ReadonlyMap} + */ +export const CLI_ONLY_FILES = new Map([ + [ + "src/application/Doctor.ts", + "Setup and doctor run only through the CLI, so their recovery may name CLI options such as --skill=false.", + ], +]); + +/** @param {string} path */ +export const cliTextGuardSelects = (path) => + !path.startsWith("src/cli/") && + !/^src\/cli[^/]*\.ts$/u.test(path) && + !CLI_ONLY_FILES.has(path); + +// One `rea ` with the arguments written after it. They end at a +// closing backtick or parenthesis, a comma or semicolon, or the next +// `rea `, so one exemption never removes another command. +const reaCommand = /\brea ([a-z][a-z-]*)(?:(?!\brea [a-z])[^`)\n,;])*/gu; +const remainingCliText = /--[a-z]|\brea [a-z]|\bon the CLI\b/u; + +/** + * Whether a matched phrase still names CLI text once each host-only command + * and its own arguments are removed. A phrase that names only those commands + * is an operator instruction; one that also names another option or command + * still counts. + * @param {string} text + */ +const namesCliText = (text) => { + let hostOnly = false; + const rest = text.replace(reaCommand, (command, name) => { + if (!HOST_ONLY_COMMANDS.has(name)) return command; + hostOnly = true; + return ""; + }); + return !hostOnly || remainingCliText.test(rest); +}; + +/** @param {string} content */ +export const cliTextOutsideCliCount = (content) => { + let count = 0; + for (const [text] of content.matchAll(cliText)) + if (namesCliText(text)) count += 1; + return count; +}; diff --git a/src/apktool/ApktoolDecodeTimeout.test.ts b/src/apktool/ApktoolDecodeTimeout.test.ts index 7b124f50f3..b366948304 100644 --- a/src/apktool/ApktoolDecodeTimeout.test.ts +++ b/src/apktool/ApktoolDecodeTimeout.test.ts @@ -120,8 +120,16 @@ it("applies the omitted 600000 ms decode deadline and a selected value on the ne const projected = projectAnalysisError(timedOut.error); expect(projected).toMatchObject({ code: "provider_timeout", - details: { timeout_ms: 200 }, + details: { + timeout_ms: 200, + limit: { + control_kind: "parameter", + parameter: "decode_timeout_ms", + effective_value: 200, + }, + }, }); + expect(projected.remediation.action).not.toContain("--"); expect(projected.message).toContain("200 ms"); expect(projected.remediation.action).toContain("decode_timeout_ms"); expect(projected.remediation.action).toContain( diff --git a/src/apktool/ApktoolProvider.ts b/src/apktool/ApktoolProvider.ts index 3a05b8f001..7819d7966a 100644 --- a/src/apktool/ApktoolProvider.ts +++ b/src/apktool/ApktoolProvider.ts @@ -1,5 +1,8 @@ +import { + deadlineParameterLimit, + MAX_NODE_TIMER_DELAY_MS, +} from "../domain/analysisResourceLimits.js"; import { capturedProviderOutput } from "../process/capturedProviderOutput.js"; -import { MAX_NODE_TIMER_DELAY_MS } from "../domain/analysisResourceLimits.js"; import { HOST_PLATFORM } from "../platform/HostPlatform.js"; import { processInspectionCancellationError } from "../providers/OwnedCommandCleanup.js"; import { APKTOOL_PROVIDER_IDENTITY } from "./ApktoolProviderIdentity.js"; @@ -106,13 +109,16 @@ const APKTOOL_EXHAUSTION_REMEDIATION: Readonly< const STDERR_EXCERPT_BYTES = 512; -const apktoolDecodeTimeoutGuidance = ( - timeoutMs: number, -): { readonly userMessage: string; readonly remediationAction: string } => ({ +const apktoolDecodeTimeoutGuidance = (timeoutMs: number) => ({ userMessage: `apktool decode reached its ${String(timeoutMs)} ms wall-clock deadline (deadlineExpired).`, + limit: deadlineParameterLimit( + "decode_timeout_ms", + timeoutMs, + DEFAULT_APKTOOL_DECODE_TIMEOUT_MS, + ), remediationAction: `${ timeoutMs < MAX_NODE_TIMER_DELAY_MS - ? `Increase decode_timeout_ms above ${String(timeoutMs)} (integer milliseconds from 1 to ${String(MAX_NODE_TIMER_DELAY_MS)}; omitted means ${String(DEFAULT_APKTOOL_DECODE_TIMEOUT_MS)}), or use rea decode-android-resources --decode-timeout-ms on the CLI.` + ? `Increase decode_timeout_ms above ${String(timeoutMs)} (integer milliseconds from 1 to ${String(MAX_NODE_TIMER_DELAY_MS)}; omitted means ${String(DEFAULT_APKTOOL_DECODE_TIMEOUT_MS)}).` : `decode_timeout_ms is already at the maximum ${String(MAX_NODE_TIMER_DELAY_MS)} ms; do not increase it further.` } A change applies on the next decode. It does not raise the ${String(DECODE_MAX_OUTPUT_BYTES)}-byte output capture allowance or the version probe; both have no runtime override. Allow execution, cleanup and delivery headroom in the outer MCP client deadline. Confirm outstanding work and cleanup before retrying.`, }); diff --git a/src/application/javascript/JavaScriptArtifactReconstruction.ts b/src/application/javascript/JavaScriptArtifactReconstruction.ts index 81519d904f..60b94fc580 100644 --- a/src/application/javascript/JavaScriptArtifactReconstruction.ts +++ b/src/application/javascript/JavaScriptArtifactReconstruction.ts @@ -1,3 +1,4 @@ +import { javaScriptSemanticPrecisionControls } from "./JavaScriptSemanticPrecisionControls.js"; import type { JavaScriptMemberMutationAllowance } from "../../domain/javascript/javascriptSemanticWorkAllowance.js"; import { discoverJavaScriptPreloadPaths } from "./JavaScriptPreloadDiscovery.js"; import { artifactNameForClassification } from "../../domain/artifactNameSelection.js"; @@ -332,6 +333,7 @@ export const reconstructJavaScriptArtifact = async ( const semanticGraphSteps = semanticProjection.finishImmutableSteps( snapshot.manifest.root_sha256, graph, + javaScriptSemanticPrecisionControls(analysis.files), ); await reportCompletedPhase( "seal_javascript_semantic_graph", diff --git a/src/application/javascript/JavaScriptSemanticGraphBuilder.ts b/src/application/javascript/JavaScriptSemanticGraphBuilder.ts index 37880b30c6..4b73f1828c 100644 --- a/src/application/javascript/JavaScriptSemanticGraphBuilder.ts +++ b/src/application/javascript/JavaScriptSemanticGraphBuilder.ts @@ -1,3 +1,4 @@ +import type { AnalysisParameterLimit } from "../../domain/analysisSettings.js"; import { createJavaScriptSemanticGraph, sealTransferredJavaScriptSemanticGraphSteps, @@ -137,13 +138,20 @@ export interface JavaScriptSemanticGraphProjection { ir: JavaScriptSemanticIr, paths?: readonly ElectronCallPath[], ) => Generator; + /** + * Seal the graph. `precisionControls` are the `semantic_precision` + * budgets that limited its sources; coverage records them beside the + * retention ceilings that stopped it. + */ readonly finish: ( rootArtifactSha256: string, applicationGraph: ApplicationGraph, + precisionControls?: readonly AnalysisParameterLimit[], ) => JavaScriptSemanticGraph; readonly finishImmutableSteps: ( rootArtifactSha256: string, applicationGraph: ApplicationGraph, + precisionControls?: readonly AnalysisParameterLimit[], ) => Generator; } @@ -276,6 +284,7 @@ export const createJavaScriptSemanticGraphProjection = ( factory: (input: unknown) => Value, rootArtifactSha256: string, applicationGraph: ApplicationGraph, + precisionControls: readonly AnalysisParameterLimit[] = [], ): Value => { bindSemanticGraphApplicationNodes(state, applicationGraph); if (state.roots.size === 0) addFallbackRoot(rootArtifactSha256, state); @@ -313,6 +322,11 @@ export const createJavaScriptSemanticGraphProjection = ( nodeCeilingsReached, ) : undefined; + const controls = [ + ...(unknownCeilingCoverage?.controls ?? []), + ...(nodeCeilingCoverage?.controls ?? []), + ...precisionControls, + ]; const graph = factory({ schema: "JavaScriptSemanticRelationGraph", root_artifact_sha256: rootArtifactSha256, @@ -342,6 +356,7 @@ export const createJavaScriptSemanticGraphProjection = ( ...(unknownCeilingCoverage?.limits ?? []), ...(nodeCeilingCoverage?.limits ?? []), ], + ...(controls.length === 0 ? {} : { controls }), families: JAVASCRIPT_SEMANTIC_RELATION_FAMILIES.map((family) => ({ family, status: semanticFamilyStatus(family), @@ -521,17 +536,23 @@ export const createJavaScriptSemanticGraphProjection = ( while (steps.next().done !== true); }, projectFileSteps: projectSourceSteps, - finish: (rootArtifactSha256, applicationGraph) => + finish: (rootArtifactSha256, applicationGraph, precisionControls) => finishWith( createJavaScriptSemanticGraph, rootArtifactSha256, applicationGraph, + precisionControls, ), - finishImmutableSteps: (rootArtifactSha256, applicationGraph) => + finishImmutableSteps: ( + rootArtifactSha256, + applicationGraph, + precisionControls, + ) => finishWith( sealTransferredJavaScriptSemanticGraphSteps, rootArtifactSha256, applicationGraph, + precisionControls, ), }; }; diff --git a/src/application/javascript/JavaScriptSemanticPrecisionControls.ts b/src/application/javascript/JavaScriptSemanticPrecisionControls.ts new file mode 100644 index 0000000000..723fb8f45f --- /dev/null +++ b/src/application/javascript/JavaScriptSemanticPrecisionControls.ts @@ -0,0 +1,35 @@ +import type { AnalysisParameterLimit } from "../../domain/analysisSettings.js"; +import { semanticCoverageResourceLimits } from "../../domain/javascript/javascriptSemanticCoverage.js"; +import { semanticPrecisionControls } from "../../domain/javascript/javascriptSemanticResourceLimits.js"; +import type { AnalyzedJavaScriptArtifactFile } from "./JavaScriptArtifactAnalysisTypes.js"; + +/** + * The `semantic_precision` budgets that limited any analyzed source, once + * each sorted by parameter: those its static examination records and those its + * semantic IR coverage reached. One request sets them for every source. + */ +export const javaScriptSemanticPrecisionControls = ( + files: readonly AnalyzedJavaScriptArtifactFile[], +): AnalysisParameterLimit[] => { + const byParameter = new Map(); + for (const { javascript, semantic } of files) { + for (const control of javascript?.analysis_coverage?.examination.controls ?? + []) + byParameter.set(control.parameter, control); + if (semantic === null) continue; + const { coverage } = semantic.ir; + for (const control of semanticPrecisionControls( + semanticCoverageResourceLimits(coverage), + [], + coverage.precision, + )) + byParameter.set(control.parameter, control); + } + return [...byParameter.values()].sort((left, right) => + left.parameter < right.parameter + ? -1 + : left.parameter > right.parameter + ? 1 + : 0, + ); +}; diff --git a/src/application/reverse/ReverseEngineeringService.ts b/src/application/reverse/ReverseEngineeringService.ts index 8cbdc15e04..8fd3d1bdf5 100644 --- a/src/application/reverse/ReverseEngineeringService.ts +++ b/src/application/reverse/ReverseEngineeringService.ts @@ -50,7 +50,7 @@ import { err, ok, type Result } from "../../domain/result.js"; import { DEFAULT_REVERSE_COMMAND_TIMEOUT_MS, DEFAULT_REVERSE_COMMAND_OUTPUT_BYTES, - MAX_REVERSE_COMMAND_OUTPUT_BYTES, + reverseCommandOutputLimit, objdumpInputSchema, rizinInputSchema, type RizinInput, @@ -118,7 +118,7 @@ const reverseCommandOutputLimitation = ( bytes: number, source: "default" | "request", ): string => - `REA stopped collecting output at max_output_bytes=${String(bytes)} bytes (source ${source}, default ${String(DEFAULT_REVERSE_COMMAND_OUTPUT_BYTES)}, range 1..${String(MAX_REVERSE_COMMAND_OUTPUT_BYTES)}) and requested termination of the provider process; captured stdout and stderr are a prefix and command completion is unknown. Narrow or page the provider command, or increase max_output_bytes (--max-output-bytes on the CLI) for the next call; no restart is required. Confirm command effects and cleanup before deciding whether it is safe to repeat. Client receive limits are separate.`; + `REA stopped collecting output at max_output_bytes=${String(bytes)} bytes (source ${source}) and requested termination of the provider process; captured stdout and stderr are a prefix and command completion is unknown. Narrow or page the provider command, or raise the output_limit control for the next call; no restart is required. Confirm command effects and cleanup before deciding whether it is safe to repeat. Client receive limits are separate.`; // Bound simultaneous provider process families independently of output admission. const MAX_CONCURRENT_REVERSE_ENGINEERING_OPERATIONS = 8; const MAX_ACTIVE_CAPTURE_BYTES = @@ -1145,6 +1145,9 @@ export class ReverseEngineeringService { output_budget_bytes: outputBudgetBytes, output_budget_source: outputBudgetSource, output_truncated: outputTruncated, + ...(outputLimitReached + ? { output_limit: reverseCommandOutputLimit(outputBudgetBytes) } + : {}), completion_status: completionStatus, artifact_sha256_after: absolutePath === undefined ? null : digestAfter, artifact_changed: absolutePath === undefined ? null : artifactChanged, diff --git a/src/browser/CdpConnection.ts b/src/browser/CdpConnection.ts index 8c597837d7..9808f2d922 100644 --- a/src/browser/CdpConnection.ts +++ b/src/browser/CdpConnection.ts @@ -232,6 +232,7 @@ class CdpTransportCore { new BrowserObservationError(operation, "timeout", { detail: recovery.userMessage, remediationAction: recovery.remediationAction, + limit: recovery.limit, }), ); }; @@ -770,6 +771,7 @@ const waitForOpen = async ( new BrowserObservationError(operation, "timeout", { detail: recovery.userMessage, remediationAction: recovery.remediationAction, + limit: recovery.limit, }), ); }, boundedTimeoutMs); diff --git a/src/browser/CdpEndpoint.ts b/src/browser/CdpEndpoint.ts index f8e86a8063..a033f5e068 100644 --- a/src/browser/CdpEndpoint.ts +++ b/src/browser/CdpEndpoint.ts @@ -62,6 +62,7 @@ const discoveryTimeout = ( return new BrowserObservationError(operation, "timeout", { detail: recovery.userMessage, remediationAction: recovery.remediationAction, + limit: recovery.limit, }); }; diff --git a/src/browser/IsolatedWebBundleAnalyzer.test.ts b/src/browser/IsolatedWebBundleAnalyzer.test.ts index 7b4057b985..70c0bfcd41 100644 --- a/src/browser/IsolatedWebBundleAnalyzer.test.ts +++ b/src/browser/IsolatedWebBundleAnalyzer.test.ts @@ -16,7 +16,10 @@ import type { AnalyzeWebBundleInput, WebBundleAnalysis, } from "../domain/webBundleAnalysis.js"; -import { analyzeWebBundleInputSchema } from "../domain/webBundleAnalysis.js"; +import { + analyzeWebBundleInputSchema, + webBundleScriptTimeoutRecovery, +} from "../domain/webBundleAnalysis.js"; import { analyzeCapturedWebScript } from "../domain/webBundleAnalyzer.js"; import { unavailableWebScriptRecovery } from "../domain/webBundleScriptAnalysis.js"; import { ProviderCleanupError } from "../domain/providerCleanupError.js"; @@ -56,7 +59,12 @@ it("preserves completed prefix and suffix facts when one script times out", asyn calls.push(script.script_key); if (calls.length === 2) return err({ - error: new AnalysisTimeoutError("analyze_web_bundle", 5), + // The worker's per-script deadline, inside a total that has time left. + error: new AnalysisTimeoutError( + "analyze_web_bundle", + 5, + webBundleScriptTimeoutRecovery(5), + ), completed: null, }); return ok(analyzeCapturedWebScript(script)); @@ -83,11 +91,28 @@ it("preserves completed prefix and suffix facts when one script times out", asyn parsed_scripts: 2, parse_failures: 0, }); - expect(result.value.unknowns).toContainEqual({ + // The partial result records the per-call control by contract field; it + // names no adapter spelling. + const timedOut = result.value.unknowns.find( + ({ dimension }) => dimension === "javascript_analysis", + ); + expect(timedOut).toEqual({ dimension: "javascript_analysis", reason: expect.stringContaining("deadline"), affected_script_keys: [captured.scripts.items[1]?.script_key], + limit: { + control_kind: "parameter", + parameter: "analysis_timeout_ms", + effective_value: 5, + unit: "ms", + minimum: expect.any(Number), + maximum: expect.any(Number), + default_value: expect.any(Number), + applies_at: "next_call", + }, + remediation: expect.stringContaining("analysis_timeout_ms"), }); + expect(JSON.stringify(timedOut)).not.toContain("--"); }); it("keeps the selected allowance and its recovery for a refused script", async () => { diff --git a/src/cli/analysisEvidenceDelivery.ts b/src/cli/analysisEvidenceDelivery.ts index 3c72ee6df2..abe1b8e486 100644 --- a/src/cli/analysisEvidenceDelivery.ts +++ b/src/cli/analysisEvidenceDelivery.ts @@ -1,5 +1,6 @@ import { explicitValuesOccurIn } from "../domain/explicitSensitiveValues.js"; import { recordCliEvidencePublication } from "./cliEvidencePublication.js"; +import { recordCliDeliveredEvidence } from "./cliResultControls.js"; import { analysisEvidenceSources, undeliveredSourceClosure, @@ -218,6 +219,8 @@ export const publishCliAnalysisEvidence = async ( closureInput, ); const complete = parseEvidence(result.value); + // A summary delivery wraps the view; controls are read from this Evidence. + recordCliDeliveredEvidence(complete); const inputError = cliEvidenceDeliveryInputError(input); if (inputError !== undefined) { inputError.retainPartialObservation(complete); @@ -378,6 +381,10 @@ const publishFailurePartialEvidence = async ( } catch { return withUndeliveredSourceClosure(failure, input); } + // Publication replaces the inline partial with its delivery; controls + // are read from the partial Evidence of this operation. + if (partial.operation === input.operation) + recordCliDeliveredEvidence(partial); const published = await publishDeliveredEvidence( partial, evidenceOutput, diff --git a/src/cli/cliResultControls.ts b/src/cli/cliResultControls.ts new file mode 100644 index 0000000000..7ac43fb10e --- /dev/null +++ b/src/cli/cliResultControls.ts @@ -0,0 +1,53 @@ +import { AsyncLocalStorage } from "node:async_hooks"; + +/** + * The per-call controls a CLI result records by contract field, each with the + * option that sets it on the command that ran. The CLI renders this map in + * its own envelope (`meta.cli_controls`); the result itself, and any Evidence + * in it, stays exactly as the service produced it. + */ +export type CliResultControls = Readonly>; + +interface ControlsContext { + /** Collects the controls on demand: only a full-output envelope shows them. */ + collect?: () => CliResultControls; + /** + * The complete Evidence the command delivered. A delivery that wraps it + * (a summary view beside its published bundle) records it here so its + * controls are read from the Evidence, not from the wrapper. + */ + delivered?: unknown; +} +const invocation = new AsyncLocalStorage(); + +/** Keep the controls in the invocation that owns the command and its output. */ +export const withCliResultControls = (run: () => Value): Value => + invocation.run({}, run); + +export const recordCliResultControls = ( + collect: () => CliResultControls, +): void => { + const context = invocation.getStore(); + if (context !== undefined) context.collect = collect; +}; + +/** Record the complete Evidence this invocation delivers, before any wrapper. */ +export const recordCliDeliveredEvidence = (evidence: unknown): void => { + const context = invocation.getStore(); + if (context !== undefined) context.delivered = evidence; +}; + +/** The complete Evidence this invocation delivered, when its delivery recorded it. */ +export const cliDeliveredEvidence = (): unknown => + invocation.getStore()?.delivered; + +/** + * This invocation's recorded controls, or undefined when its result records + * none. The result is read only when this is called. + */ +export const cliResultControls = (): CliResultControls | undefined => { + const controls = invocation.getStore()?.collect?.(); + return controls === undefined || Object.keys(controls).length === 0 + ? undefined + : controls; +}; diff --git a/src/cli/cliResultOutput.ts b/src/cli/cliResultOutput.ts index 422b398203..3f8dc41443 100644 --- a/src/cli/cliResultOutput.ts +++ b/src/cli/cliResultOutput.ts @@ -38,6 +38,11 @@ import { retainCliPublicationOnError, withCliEvidencePublication, } from "./cliEvidencePublication.js"; +import { + cliResultControls, + withCliResultControls, + type CliResultControls, +} from "./cliResultControls.js"; import { jsonLinesErrorRecord } from "./jsonLines.js"; import { writeCliJsonLines } from "./jsonLinesOutput.js"; import { @@ -63,8 +68,24 @@ export interface CliResultOutputMetadata { readonly forceOutput?: boolean; /** The producer owns a failure document whose complete facts must survive filtering. */ readonly failure?: boolean; + /** + * Flags of the per-call controls the result records, by contract field, + * collected only when a full-output envelope will show them. + */ + readonly cliControls?: CliResultControls | undefined; + /** Collects `cliControls` on demand. */ + readonly collectCliControls?: () => CliResultControls | undefined; } +/** The full-output envelope's metadata: the CLI's presentation, not the result. */ +const resultMeta = (metadata: CliResultOutputMetadata) => ({ + command: metadata.command, + duration: metadata.duration, + ...(metadata.cliControls === undefined + ? {} + : { cli_controls: { ...metadata.cliControls } }), +}); + /** Optional executable-owned result surface for one CLI invocation. */ export interface CliResultOutput { readonly handled: boolean; @@ -105,42 +126,45 @@ const wrapCommand = ( ): void => { const run = command.run; command.run = (context) => - withCliEvidencePublication(() => { - const started = performance.now(); - const result: unknown = run(context); - // Generator results and Incur's sentinel responses retain their own protocol. - if ( - typeof result === "object" && - result !== null && - Symbol.asyncIterator in result - ) { - output.delegateStreaming(); - return result; - } - return Promise.resolve(result).then(async (value: unknown) => { + withCliEvidencePublication(() => + withCliResultControls(() => { + const started = performance.now(); + const result: unknown = run(context); + // Generator results and Incur's sentinel responses retain their own protocol. if ( - typeof value === "object" && - value !== null && - Symbol.for("incur.sentinel") in value - ) - return value; - if ( - !(await output.write(value, { - command: name, - format: context.format, - renderOutput: context.agent || inheritedPolicy !== "agent-only", - duration: `${Math.round(performance.now() - started)}ms`, - })) - ) - return value; - if (output.error !== undefined) - return context.error({ - code: output.error.code, - message: output.error.message, - }); - return undefined; - }); - }); + typeof result === "object" && + result !== null && + Symbol.asyncIterator in result + ) { + output.delegateStreaming(); + return result; + } + return Promise.resolve(result).then(async (value: unknown) => { + if ( + typeof value === "object" && + value !== null && + Symbol.for("incur.sentinel") in value + ) + return value; + if ( + !(await output.write(value, { + command: name, + format: context.format, + renderOutput: context.agent || inheritedPolicy !== "agent-only", + duration: `${Math.round(performance.now() - started)}ms`, + collectCliControls: cliResultControls, + })) + ) + return value; + if (output.error !== undefined) + return context.error({ + code: output.error.code, + message: output.error.message, + }); + return undefined; + }); + }), + ); }; /** Preserve Incur output controls and stream JSON while framing failures. */ @@ -246,8 +270,16 @@ export const createCliResultOutput = ( !((format === "csv" || format === "tsv") && metadata.format === "json") ) return false; + // Only the full-output envelope shows the result's control flags, so the + // result is read for them only then. + const cliControls = options.fullOutput + ? metadata.collectCliControls?.() + : undefined; try { - return await writeResult(value, metadata); + return await writeResult( + value, + cliControls === undefined ? metadata : { ...metadata, cliControls }, + ); } catch (cause: unknown) { if (await recoverFormattingFailure(cause)) return true; throw cause; @@ -451,10 +483,7 @@ export const createCliResultOutput = ( ) return false; if (format === "csv" || format === "tsv") { - const meta = { - command: metadata.command, - duration: metadata.duration, - }; + const meta = resultMeta(metadata); if (operationFailure !== undefined) { const parsedFailure = analysisErrorProjectionSchema.safeParse(operationFailure); @@ -625,6 +654,10 @@ export const createCliResultOutput = ( Array.isArray(selected) ? normalizeJsonArrayValues(selected) : selected; + // A full-output envelope that shows the result's control flags is written + // here in every format; Incur's envelope cannot carry them. + const ownsControlEnvelope = + options.fullOutput && metadata.cliControls !== undefined; const ownsSuccessfulTokenWindow = operationFailure === undefined && options.tokenWindow && @@ -643,7 +676,9 @@ export const createCliResultOutput = ( operationFailure === undefined && !ownsFilteredOutput && !ownsSuccessfulTokenWindow && - !(options.tokenCount && options.fullOutput) + !(options.tokenCount && options.fullOutput) && + // Incur's own envelope cannot carry the result's control flags. + !ownsControlEnvelope ) return false; if (format === "jsonl") { @@ -658,6 +693,9 @@ export const createCliResultOutput = ( operationFailure, command: metadata.command, duration: metadata.duration, + ...(metadata.cliControls === undefined + ? {} + : { cliControls: metadata.cliControls }), }, destination, ); @@ -667,10 +705,7 @@ export const createCliResultOutput = ( } return true; } - const meta = { - command: metadata.command, - duration: metadata.duration, - }; + const meta = resultMeta(metadata); const errorDocument = options.fullOutput && failure !== undefined ? fullFailureEnvelope( @@ -784,8 +819,7 @@ export const createCliResultOutput = ( ok: true, data: sliced, meta: { - command: metadata.command, - duration: metadata.duration, + ...resultMeta(metadata), ...(window.end < window.total ? { nextOffset: window.end } : {}), @@ -815,7 +849,8 @@ export const createCliResultOutput = ( // document from Incur's error formatter. const formattedText = format === "md" || - (metadata.forceOutput === true && format !== "json") || + ((metadata.forceOutput === true || ownsControlEnvelope) && + format !== "json") || ((operationFailure !== undefined || ownsFilteredOutput) && format !== "json") ? formatCliOutput(document, format) diff --git a/src/cli/contractCliDescription.ts b/src/cli/contractCliDescription.ts index 1a67525914..a31621372e 100644 --- a/src/cli/contractCliDescription.ts +++ b/src/cli/contractCliDescription.ts @@ -46,6 +46,11 @@ export interface ProjectedContract { | z.ZodObject | z.ZodDiscriminatedUnion | z.ZodUnion; + /** + * The result schema. It declares which result positions are controls REA + * recorded; without it the CLI renders no result controls. + */ + readonly outputSchema?: z.ZodType; } /** A contract whose whole input a CLI command takes as one JSON document. */ @@ -424,6 +429,11 @@ export interface ContractCliEvidenceTargets { readonly targets: readonly ContractCliEvidenceTarget[]; /** Options that supply fields of the source contract. */ readonly options: readonly ContractCliOpeningOption[]; + /** + * Each source contract field this command takes as an option, with that + * option's flag, so a source failure's control names it. + */ + readonly sourceFlags: Readonly>; /** * The source fields the parsed options select, in contract spelling, * admitted by the source input with each target as its `path`. Issues @@ -1506,6 +1516,9 @@ const describeEvidenceTargets = ( source: targets.source.contract.name, targets: described, options, + sourceFlags: Object.fromEntries( + options.map(({ field, key }) => [field, `--${kebabCase(key)}`]), + ), admitSource: (operation, values) => { let admitted: Result< Readonly>, diff --git a/src/cli/contractCommand.ts b/src/cli/contractCommand.ts index 7908d9626d..c12538a3ee 100644 --- a/src/cli/contractCommand.ts +++ b/src/cli/contractCommand.ts @@ -49,6 +49,12 @@ import { withoutDefault, } from "./contractCliDescription.js"; import { + cliDeliveredEvidence, + recordCliResultControls, +} from "./cliResultControls.js"; +import { + cliResultControlsIn, + failurePartialObservation, projectCliAnalysisResult, projectCliInputFields, } from "./projectCliAnalysisResult.js"; @@ -140,6 +146,8 @@ export const admittedContractInput = (context: { export interface CliEvidenceTargetSelection { /** The source contract each target runs. */ readonly source: string; + /** Source contract fields this command takes as options, with their flags. */ + readonly sourceFlags: Readonly>; readonly targets: readonly { /** The contract field the target's source Evidence supplies. */ readonly field: string; @@ -343,6 +351,34 @@ export const runDirectOnTarget = }); }; +/** + * A command's output named for the CLI: renamed issue paths and failure + * flags (`projectCliInputFields`), and the flags of controls its result + * records, which the CLI renders in its own envelope. + */ +const projectCliResult = ( + output: Output, + outputSchema: z.ZodType | undefined, + binding: Parameters[1], +): Output => { + // A command without flags, or without a result schema that declares + // recorded controls, has no control to render. + if (outputSchema !== undefined && Object.keys(binding.flags).length > 0) + recordCliResultControls(() => + // A wrapped delivery recorded its complete Evidence, which the + // contract's output schema describes; so does a failure's partial + // Evidence of the same operation. + cliResultControlsIn( + cliDeliveredEvidence() ?? + failurePartialObservation(output, binding.operation) ?? + output, + outputSchema, + binding, + ), + ); + return projectCliInputFields(output, binding); +}; + /** * Run the source contract on each Evidence target in argv order with the * source fields the caller selected, then compose the contract from that @@ -387,7 +423,7 @@ export const runOnEvidenceTargets = { operation: evidenceTargets.source, fields: { path: key }, - flags: {}, + flags: evidenceTargets.sourceFlags, }, ); sources[field] = source.value; @@ -635,7 +671,19 @@ export const registerContractCommand = < ); const opening = admitOpening(selected, values); if (!opening.ok) return projectAnalysisError(opening.error); - return projectCliInputFields( + // A composed command also takes its sources' options; a control + // its result records from a source is set by that option. + const resultBinding = + description.evidenceTargets === undefined + ? selected.inputBinding + : { + ...selected.inputBinding, + flags: { + ...description.evidenceTargets.sourceFlags, + ...selected.inputBinding.flags, + }, + }; + return projectCliResult( await run( admitted.value.input as z.input, { @@ -651,6 +699,7 @@ export const registerContractCommand = < ? undefined : { source: description.evidenceTargets.source, + sourceFlags: description.evidenceTargets.sourceFlags, targets: description.evidenceTargets.targets.map( ({ field, key }) => ({ field, @@ -676,7 +725,8 @@ export const registerContractCommand = < ) as CliOptionValues, }, ), - selected.inputBinding, + selected.contract.outputSchema, + resultBinding, ); }), ); @@ -934,7 +984,7 @@ export const registerRoutedCommand = ( ); const opening = admitOpening(description, values); if (!opening.ok) return projectAnalysisError(opening.error); - return projectCliInputFields( + return projectCliResult( await route.run(admitted.value.input, { signal, operation: description.contract.name, @@ -953,6 +1003,7 @@ export const registerRoutedCommand = ( withCliOnlyDefaults(description, values), ), }), + description.contract.outputSchema, description.inputBinding, ); }), diff --git a/src/cli/jsonLinesOutput.ts b/src/cli/jsonLinesOutput.ts index 9626b9125f..458cdc9f0b 100644 --- a/src/cli/jsonLinesOutput.ts +++ b/src/cli/jsonLinesOutput.ts @@ -21,6 +21,7 @@ import { writeOutputText, } from "./jsonOutput.js"; import { retainCliPublicationOnError } from "./cliEvidencePublication.js"; +import type { CliResultControls } from "./cliResultControls.js"; interface CliJsonLinesInput { readonly source: unknown; @@ -28,6 +29,8 @@ interface CliJsonLinesInput { readonly operationFailure: unknown; readonly command: string; readonly duration: string; + /** Flags of the per-call controls the result records, by contract field. */ + readonly cliControls?: CliResultControls; readonly fullOutput: boolean; readonly tokenCount: boolean; readonly filterOutput: string | undefined; @@ -41,7 +44,13 @@ export const writeCliJsonLines = async ( ): Promise => { const { source, selected, operationFailure } = options; let error: AnalysisErrorProjection | undefined; - const meta = { command: options.command, duration: options.duration }; + const meta = { + command: options.command, + duration: options.duration, + ...(options.cliControls === undefined + ? {} + : { cli_controls: { ...options.cliControls } }), + }; const envelope = (data: unknown) => options.fullOutput ? { ok: true, data, meta } : data; let failureRecord = diff --git a/src/cli/projectCliAnalysisResult.ts b/src/cli/projectCliAnalysisResult.ts index cd24b7a074..997d6b9c22 100644 --- a/src/cli/projectCliAnalysisResult.ts +++ b/src/cli/projectCliAnalysisResult.ts @@ -1,3 +1,6 @@ +import type { z } from "zod"; + +import { recordedControlSchemas } from "../domain/analysisSettingDefinitions.js"; import type { JsonValue } from "../domain/jsonValue.js"; import type { Result } from "../domain/result.js"; @@ -78,27 +81,145 @@ const renamedIssues = ( }; /** - * The reported per-call control with the flag that sets it, or undefined - * when the command takes no flag for it. A parameter control names it, and so - * does a registered setting a request argument can also select. The longest - * bound prefix of the parameter path names the flag: a flattened member - * option, else the option of the whole field (such as `--producer-limits` - * JSON). + * The request parameter a limit names, when a caller selects it per call: a + * parameter control, or a registered setting a request argument can also + * select. */ +const limitParameter = (limit: JsonValue | undefined): string | undefined => + isObject(limit) && + typeof limit.parameter === "string" && + (limit.control_kind === "parameter" || typeof limit.setting === "string") + ? limit.parameter + : undefined; + +/** + * The option that sets a contract field or member on this command, or + * undefined when it takes no flag for it. The longest bound prefix of the + * parameter path names the flag: a flattened member option, else the option + * of the whole field (such as `--producer-limits` JSON). + */ +const cliFlagFor = ( + parameter: string, + binding: CliInputFieldBinding, +): string | undefined => { + const segments = parameter.split("."); + for (let length = segments.length; length > 0; length -= 1) { + const flag = binding.flags[segments.slice(0, length).join(".")]; + if (flag !== undefined) return flag; + } + return undefined; +}; + +/** The reported per-call control with the flag that sets it. */ const flaggedLimit = ( limit: JsonValue | undefined, binding: CliInputFieldBinding, ): Record | undefined => { - if ( - !isObject(limit) || - typeof limit.parameter !== "string" || - (limit.control_kind !== "parameter" && typeof limit.setting !== "string") - ) - return undefined; - const segments = limit.parameter.split("."); - for (let length = segments.length; length > 0; length -= 1) { - const flag = binding.flags[segments.slice(0, length).join(".")]; - if (flag !== undefined) return { ...limit, cli_flag: flag }; - } - return undefined; + const parameter = limitParameter(limit); + const flag = + parameter === undefined ? undefined : cliFlagFor(parameter, binding); + return flag === undefined || !isObject(limit) + ? undefined + : { ...limit, cli_flag: flag }; +}; + +/** Wrappers whose value is their inner schema's value. */ +const WRAPPER_TYPES = new Set([ + "optional", + "nonoptional", + "nullable", + "default", + "prefault", + "readonly", + "catch", +]); + +/** + * The schema nodes of a value, following the result schema: each position + * the schema declares a recorded control yields that value. Positions the + * schema leaves open (records, unknown JSON, lazy or custom types) are not + * entered, so captured content cannot supply a control. + */ +const recordedControlValues = ( + output: unknown, + schema: z.ZodType, +): unknown[] => { + const found: unknown[] = []; + const pending: [unknown, z.ZodType][] = [[output, schema]]; + while (pending.length > 0) { + const [value, node] = pending.pop()!; + if (value === undefined) continue; + if (recordedControlSchemas.has(node)) { + if (node.safeParse(value).success) found.push(value); + continue; + } + const def = node._zod.def as unknown as Record & { + readonly type: string; + }; + if (WRAPPER_TYPES.has(def.type)) { + pending.push([value, def.innerType as z.ZodType]); + } else if (def.type === "pipe") { + pending.push([value, def.out as z.ZodType]); + } else if (def.type === "union") { + // The first option the value satisfies is the one the producer used. + const option = (def.options as z.ZodType[]).find( + (candidate) => candidate.safeParse(value).success, + ); + if (option !== undefined) pending.push([value, option]); + } else if (def.type === "array" && Array.isArray(value)) { + for (const item of value) pending.push([item, def.element as z.ZodType]); + } else if ( + def.type === "object" && + value !== null && + typeof value === "object" && + !Array.isArray(value) + ) { + const shape = def.shape as Record; + const record = value as Record; + for (const [key, field] of Object.entries(shape)) + if (Object.hasOwn(record, key)) pending.push([record[key], field]); + } + } + return found; +}; + +/** + * A failure's partial observation, when it is Evidence of the command's own + * operation. The command's output schema describes that Evidence, so its + * declared control positions are read as a success result's are. A retained + * reference, or Evidence of a source step or another operation, is not read. + */ +export const failurePartialObservation = ( + output: unknown, + operation: string, +): Record | undefined => { + const failure = output as JsonValue; + if (!isObject(failure) || !isObject(failure.details)) return undefined; + const partial = failure.details.partial_observation; + return isObject(partial) && partial.operation === operation + ? partial + : undefined; +}; + +/** + * Each per-call control a result records by contract field (a `limit` in a + * partial result's unknowns, coverage or retained Evidence), with the option + * that sets it on this command. Only positions the command's output schema + * declares as recorded controls count. The result is read, never changed: + * the CLI renders these flags in its own envelope. + */ +export const cliResultControlsIn = ( + output: unknown, + schema: z.ZodType, + binding: CliInputFieldBinding, +): Record => { + const controls: Record = {}; + for (const value of recordedControlValues(output, schema)) { + const parameter = limitParameter(value as JsonValue); + const flag = + parameter === undefined ? undefined : cliFlagFor(parameter, binding); + if (parameter !== undefined && flag !== undefined) + controls[parameter] = flag; + } + return controls; }; diff --git a/src/domain/analysisResourceLimits.ts b/src/domain/analysisResourceLimits.ts index 175d84e0c6..3c4db8f799 100644 --- a/src/domain/analysisResourceLimits.ts +++ b/src/domain/analysisResourceLimits.ts @@ -1,4 +1,5 @@ import { z } from "zod"; +import type { AnalysisControlLimit } from "./analysisSettings.js"; /** Numeric admission contracts shared by environment parsing and runtime tools. * Timer maxima follow signed 32-bit scheduling. ASAR's 256 MiB maximum and @@ -82,6 +83,25 @@ export const MAX_NODE_TIMER_DELAY_MS = 2_147_483_647; * A positive whole-millisecond duration Node can schedule exactly. Zero and * negative values are not a deadline. */ +/** + * The per-call control of a caller-selectable millisecond deadline, named by + * its contract field; each adapter names the option that sets it. + */ +export const deadlineParameterLimit = ( + parameter: string, + timeoutMs: number, + defaultMs: number, +): AnalysisControlLimit => ({ + control_kind: "parameter", + parameter, + effective_value: timeoutMs, + unit: "ms", + minimum: 1, + maximum: MAX_NODE_TIMER_DELAY_MS, + default_value: defaultMs, + applies_at: "next_call", +}); + export const timerDurationMsSchema = z .int() .min(1) diff --git a/src/domain/analysisSettingDefinitions.ts b/src/domain/analysisSettingDefinitions.ts index 15a09b107d..75efc5d202 100644 --- a/src/domain/analysisSettingDefinitions.ts +++ b/src/domain/analysisSettingDefinitions.ts @@ -1,6 +1,7 @@ import { z } from "zod"; import type { AnalysisControlLimit, + AnalysisParameterLimit, AnalysisInvocationSettingLimit, AnalysisLimit, AnalysisSettingId, @@ -625,6 +626,45 @@ export const analysisSettingLimitSchema = z.strictObject({ required_value: z.number().exactOptional(), parameter: z.string().exactOptional(), }) satisfies z.ZodType; + +/** + * A per-call request parameter that bounded a result, named by its contract + * field. Adapters render their own spelling of it (a CLI flag) outside the + * record. + */ +export const analysisParameterLimitSchema = z.strictObject({ + control_kind: z.literal("parameter"), + parameter: z.string(), + effective_value: z.number(), + unit: z.enum(["bytes", "ms", "seconds", "MiB", "count"]), + minimum: z.number(), + maximum: z.number(), + default_value: z.number(), + applies_at: z.literal("next_call"), +}) satisfies z.ZodType; + +/** The control a result records for a refusal: a setting or a request parameter. */ +export const analysisResultLimitSchema = z.union([ + analysisSettingLimitSchema, + analysisParameterLimitSchema, +]); + +/** + * The schemas whose values are controls a result records itself. A result + * schema that places one of these instances (directly, optional, in an array + * or in a union) declares that position as REA's own control reference, so + * an adapter can name its option. Values elsewhere, such as captured file + * content that happens to look like a limit, are never read as controls. + */ +export const recordedControlSchemas = z.registry<{ + readonly recordedControl: true; +}>(); +recordedControlSchemas.add(analysisSettingLimitSchema, { + recordedControl: true, +}); +recordedControlSchemas.add(analysisParameterLimitSchema, { + recordedControl: true, +}); export const analysisSettingDefinition = ( id: AnalysisSettingId, ): SettingDefinition => ANALYSIS_SETTINGS[id]; diff --git a/src/domain/analysisSettings.ts b/src/domain/analysisSettings.ts index 5e876ba50f..59904cc58e 100644 --- a/src/domain/analysisSettings.ts +++ b/src/domain/analysisSettings.ts @@ -112,5 +112,11 @@ export type AnalysisControlLimit = { } ); +/** A per-call request parameter control, named by its contract field. */ +export type AnalysisParameterLimit = Extract< + AnalysisControlLimit, + { readonly control_kind: "parameter" } +>; + /** The limit an error binds: a registered setting, or a parameter or environment control. */ export type AnalysisLimit = AnalysisSettingLimit | AnalysisControlLimit; diff --git a/src/domain/analysisView/rustBinaryView.ts b/src/domain/analysisView/rustBinaryView.ts index 901b494aa6..59948ced59 100644 --- a/src/domain/analysisView/rustBinaryView.ts +++ b/src/domain/analysisView/rustBinaryView.ts @@ -5,6 +5,7 @@ import { z } from "zod"; import { rustBinarySchema, rustAuditableMetadataSchema, + rustcCommitOmissionSchema, rustcCommitSchema, type RustBinary, } from "../rust/rustBinary.js"; @@ -55,6 +56,7 @@ export const rustBinarySummarySchema = z.strictObject({ .omit({ hashes: true }) .extend({ hashes_count: count }) .nullable(), + rustc_commit_omission: rustcCommitOmissionSchema.exactOptional(), }); export const rustBinaryViewContextSchema = z.strictObject({ source_coverage: z.strictObject({ @@ -109,6 +111,9 @@ const summarize = ( bytes: artifact.bytes, auditable_metadata: section, rustc_commit: compilerSummary, + ...(report.rustc_commit_omission === undefined + ? {} + : { rustc_commit_omission: report.rustc_commit_omission }), }; }; diff --git a/src/domain/browserDeadline.ts b/src/domain/browserDeadline.ts index f0115e4806..750e6e824b 100644 --- a/src/domain/browserDeadline.ts +++ b/src/domain/browserDeadline.ts @@ -1,7 +1,9 @@ import { MAX_NODE_TIMER_DELAY_MS, + deadlineParameterLimit, timerDurationMsSchema, } from "./analysisResourceLimits.js"; +import type { AnalysisControlLimit } from "./analysisSettings.js"; import type { BrowserObservationOperation } from "./browserObservationErrors.js"; @@ -30,12 +32,19 @@ export const browserDeadlineIncrease = ( key: string, timeoutMs: number, defaultMs: number, - cli: string, ): string => timeoutMs < MAX_NODE_TIMER_DELAY_MS - ? `Increase ${key} above ${String(timeoutMs)} (integer milliseconds from 1 to ${String(MAX_NODE_TIMER_DELAY_MS)}; omitted means ${String(defaultMs)}), or use ${cli} on the CLI.` + ? `Increase ${key} above ${String(timeoutMs)} (integer milliseconds from 1 to ${String(MAX_NODE_TIMER_DELAY_MS)}; omitted means ${String(defaultMs)}).` : `${key} is already at the maximum ${String(MAX_NODE_TIMER_DELAY_MS)} ms; do not increase it further.`; +/** Recovery for a caller-selectable browser deadline, with the control it binds. */ +export interface BrowserDeadlineRecovery { + readonly userMessage: string; + readonly remediationAction: string; + /** Present when the caller can select the deadline on the next call. */ + readonly limit?: AnalysisControlLimit; +} + export const browserDeadlineRetry = "Applies on the next call. Allow execution, cleanup and delivery headroom in the outer MCP client deadline. Confirm outstanding work and cleanup before retrying."; @@ -127,7 +136,7 @@ export const cdpCommandDeadlineRecovery = ( phase: CdpCommandDeadlinePhase, method?: string, selectable = true, -): { readonly userMessage: string; readonly remediationAction: string } => { +): BrowserDeadlineRecovery => { const subject = cdpDeadlineSubject(timeoutMs, phase, method, selectable); if (!selectable) { const fixed = noRuntimeOverrideSentence( @@ -137,7 +146,12 @@ export const cdpCommandDeadlineRecovery = ( } return { userMessage: `${subject} This is not the caller observation window, not the ${String(CDP_DISCOVERY_RESPONSE_TIMEOUT_MS)} ms CDP discovery deadline, and not the ${String(CDP_CLEANUP_GRACE_MS)} ms cleanup grace.`, - remediationAction: `${browserDeadlineIncrease("command_timeout_ms", timeoutMs, DEFAULT_CDP_COMMAND_TIMEOUT_MS, "--command-timeout-ms")} ${browserDeadlineRetry} command_timeout_ms does not raise the CDP discovery deadline (default ${String(CDP_DISCOVERY_RESPONSE_TIMEOUT_MS)} ms, or discovery_timeout_ms where supported), nor the fixed protocol, retained-event, or source byte budgets or the ${String(CDP_CLEANUP_GRACE_MS)} ms cleanup grace, which have no runtime override.`, + limit: deadlineParameterLimit( + "command_timeout_ms", + timeoutMs, + DEFAULT_CDP_COMMAND_TIMEOUT_MS, + ), + remediationAction: `${browserDeadlineIncrease("command_timeout_ms", timeoutMs, DEFAULT_CDP_COMMAND_TIMEOUT_MS)} ${browserDeadlineRetry} command_timeout_ms does not raise the CDP discovery deadline (default ${String(CDP_DISCOVERY_RESPONSE_TIMEOUT_MS)} ms, or discovery_timeout_ms where supported), nor the fixed protocol, retained-event, or source byte budgets or the ${String(CDP_CLEANUP_GRACE_MS)} ms cleanup grace, which have no runtime override.`, }; }; @@ -147,7 +161,7 @@ export const cdpDiscoveryTimeoutRecovery = ( timeoutMs: number, phase: "response" | "browser-socket", budgetDescription: string, -): { readonly userMessage: string; readonly remediationAction: string } => { +): BrowserDeadlineRecovery => { const unrelatedCommand = cdpCommandTimeoutUnrelatedControl(operation); if (!cdpDiscoveryTimeoutIsSelectable(operation)) { const subject = @@ -173,7 +187,12 @@ export const cdpDiscoveryTimeoutRecovery = ( ); return { userMessage: `${subject} This is not the caller observation window and not the ${String(CDP_CLEANUP_GRACE_MS)} ms cleanup grace. ${fixedBudget}`, - remediationAction: `${browserDeadlineIncrease("discovery_timeout_ms", timeoutMs, CDP_DISCOVERY_RESPONSE_TIMEOUT_MS, "--discovery-timeout-ms")} ${browserDeadlineRetry} ${fixedBudget}`, + remediationAction: `${browserDeadlineIncrease("discovery_timeout_ms", timeoutMs, CDP_DISCOVERY_RESPONSE_TIMEOUT_MS)} ${browserDeadlineRetry} ${fixedBudget}`, + limit: deadlineParameterLimit( + "discovery_timeout_ms", + timeoutMs, + CDP_DISCOVERY_RESPONSE_TIMEOUT_MS, + ), }; }; diff --git a/src/domain/commandObservation.ts b/src/domain/commandObservation.ts index cbe75404b6..806a97d469 100644 --- a/src/domain/commandObservation.ts +++ b/src/domain/commandObservation.ts @@ -1,5 +1,7 @@ import { z } from "zod"; +import { analysisParameterLimitSchema } from "./analysisSettingDefinitions.js"; + /** Opaque producer text and the command capture's explicit completion facts. */ export const commandObservationSchema = z.strictObject({ stdout: z.string(), @@ -9,6 +11,11 @@ export const commandObservationSchema = z.strictObject({ output_budget_bytes: z.int().positive().exactOptional(), output_budget_source: z.enum(["default", "request"]).exactOptional(), output_truncated: z.boolean(), + /** + * The request parameter whose budget stopped output collection, present + * only when the capture reached it. + */ + output_limit: analysisParameterLimitSchema.exactOptional(), completion_status: z .enum(["complete", "rejected", "unknown"]) .describe( diff --git a/src/domain/flutter/flutterBuildAnalysis.ts b/src/domain/flutter/flutterBuildAnalysis.ts index 77155470cf..9c44cdb0c4 100644 --- a/src/domain/flutter/flutterBuildAnalysis.ts +++ b/src/domain/flutter/flutterBuildAnalysis.ts @@ -3,6 +3,8 @@ import { maxCodePoints } from "../schemaConstraints.js"; import { localPathStringSchema } from "../localPath.js"; import { knownCoverageStatusSchema } from "../coverage.js"; import { digestSchema } from "../digests.js"; +import type { AnalysisParameterLimit } from "../analysisSettings.js"; +import { analysisParameterLimitSchema } from "../analysisSettingDefinitions.js"; /** Full logical ZIP path budget, enforced by Flutter library inventory. */ export const MAX_FLUTTER_LIBRARY_PATH_BYTES = 1024; @@ -64,6 +66,27 @@ export type DartPoolPolicy = { readonly token_bytes: number; readonly contains?: string | undefined; }; +/** A string-pool budget a result can name as its per-call control. */ +export type DartPoolBudget = Exclude; + +/** + * The per-call control of one string-pool budget, named by its contract + * field; each adapter names the option that sets it. + */ +export const dartPoolBudgetLimit = ( + budget: DartPoolBudget, + policy: DartPoolPolicy, +): AnalysisParameterLimit => ({ + control_kind: "parameter", + parameter: `pool_policy.${budget}`, + effective_value: policy[budget], + unit: budget === "uri_limit" || budget === "token_limit" ? "count" : "bytes", + minimum: 1, + maximum: Number.MAX_SAFE_INTEGER, + default_value: DART_POOL_DEFAULTS[budget], + applies_at: "next_call", +}); + export const dartPoolPolicy = ( selected?: DartPoolPolicyInput, ): DartPoolPolicy => ({ @@ -244,6 +267,8 @@ export const flutterResultSchemas = { class_like_tokens: z.array(z.string().min(1)), class_like_token_count_at_least: z.int().nonnegative(), printable_run_count: z.int().nonnegative(), + /** The budgets that left the projection partial, as request parameters. */ + limits: z.array(analysisParameterLimitSchema).min(1).exactOptional(), }), coverage: knownCoverageStatusSchema, }), diff --git a/src/domain/javascript/javascriptAnalysisResourceControls.test.ts b/src/domain/javascript/javascriptAnalysisResourceControls.test.ts index f7d5230f21..a48e28cc8c 100644 --- a/src/domain/javascript/javascriptAnalysisResourceControls.test.ts +++ b/src/domain/javascript/javascriptAnalysisResourceControls.test.ts @@ -174,39 +174,58 @@ it("names the four semantic arguments on ceiling coverage", () => { ); expect(nodes.limitation).toContain("1 to"); expect(nodes.limitation).toContain(String(JAVASCRIPT_SEMANTIC_ITEM_MAXIMUM)); - expect(nodes.limitation).toContain( - "CLI: --max-semantic-nodes and --max-semantic-nodes-per-file", - ); + // The producer records controls by contract field; adapters name options. + expect(nodes.limitation).not.toContain("--"); + expect(nodes.limitation).toContain("coverage.controls records them"); + expect(nodes.controls).toEqual([ + { + control_kind: "parameter", + parameter: "max_semantic_nodes", + effective_value: 50, + unit: "count", + minimum: 1, + maximum: JAVASCRIPT_SEMANTIC_ITEM_MAXIMUM, + default_value: JAVASCRIPT_ANALYSIS_RESOURCE_DEFAULTS.semanticNodes, + applies_at: "next_call", + }, + expect.objectContaining({ + parameter: "max_semantic_nodes_per_file", + effective_value: 30, + default_value: JAVASCRIPT_ANALYSIS_RESOURCE_DEFAULTS.semanticNodesPerFile, + }), + ]); expect(nodes.limitation).toContain( "Set max_semantic_nodes and max_semantic_nodes_per_file", ); expect(nodes.limitation).toContain("Raising them does not raise"); expect(nodes.limitation).toContain("next analysis"); - expect(unknowns.limitation).toContain( - "CLI: --max-semantic-unknowns and --max-semantic-unknowns-per-file", - ); + expect(unknowns.controls.map(({ parameter }) => parameter)).toEqual([ + "max_semantic_unknowns", + "max_semantic_unknowns_per_file", + ]); expect(unknowns.limitation).toContain("max_semantic_nodes"); expect(perFileOnly.limitation).toContain("max_semantic_nodes_per_file is 30"); expect(perFileOnly.limitation).toContain( "Set max_semantic_nodes_per_file on the next", ); - expect(perFileOnly.limitation).toContain( - "CLI: --max-semantic-nodes-per-file", - ); + expect(perFileOnly.controls.map(({ parameter }) => parameter)).toEqual([ + "max_semantic_nodes_per_file", + ]); + expect(perFileOnly.limitation).toContain("coverage.controls records it"); expect(perFileOnly.limitation).toContain("Raising it does not raise"); expect(perFileOnly.limitation).not.toContain("max_semantic_nodes is 50"); - expect(perFileOnly.limitation).not.toContain("--max-semantic-nodes and"); + expect(totalOnly.limitation).toContain("max_semantic_unknowns is 3"); expect(totalOnly.limitation).toContain( "Set max_semantic_unknowns on the next", ); - expect(totalOnly.limitation).toContain("CLI: --max-semantic-unknowns)"); + expect(totalOnly.controls.map(({ parameter }) => parameter)).toEqual([ + "max_semantic_unknowns", + ]); expect(totalOnly.limitation).not.toContain( "max_semantic_unknowns_per_file is 2", ); - expect(totalOnly.limitation).not.toContain( - "--max-semantic-unknowns-per-file", - ); + const capped = javaScriptSemanticCeilingCoverage( "nodes", JAVASCRIPT_SEMANTIC_ITEM_MAXIMUM, diff --git a/src/domain/javascript/javascriptAnalysisResourceControls.ts b/src/domain/javascript/javascriptAnalysisResourceControls.ts index 1d6d5ee4b8..eab36feb41 100644 --- a/src/domain/javascript/javascriptAnalysisResourceControls.ts +++ b/src/domain/javascript/javascriptAnalysisResourceControls.ts @@ -10,6 +10,7 @@ export const JAVASCRIPT_STATIC_FACT_BYTES = 8 * 1024 * 1024; /** Maximum encoded worker transfer record, including the JSON envelope and newline. */ export const JAVASCRIPT_ANALYSIS_TRANSFER_RECORD_BYTES = 8 * 1024 * 1024; import type { JsonValue } from "../jsonValue.js"; +import type { AnalysisParameterLimit } from "../analysisSettings.js"; import type { ApplicationCoverage } from "./javascriptApplicationEvidenceSchemas.js"; /** Shared operational defaults for the isolated source-analysis boundary. */ @@ -90,8 +91,6 @@ const semanticControl = { fileCeiling: "semantic_graph_file_node_ceiling", totalDefault: JAVASCRIPT_ANALYSIS_RESOURCE_DEFAULTS.semanticNodes, perFileDefault: JAVASCRIPT_ANALYSIS_RESOURCE_DEFAULTS.semanticNodesPerFile, - cliTotal: "--max-semantic-nodes", - cliPerFile: "--max-semantic-nodes-per-file", doesNotRaise: "max_semantic_unknowns, max_heap_mb, transfer ceilings, or the parent result budget", }, @@ -103,8 +102,6 @@ const semanticControl = { totalDefault: JAVASCRIPT_ANALYSIS_RESOURCE_DEFAULTS.semanticUnknowns, perFileDefault: JAVASCRIPT_ANALYSIS_RESOURCE_DEFAULTS.semanticUnknownsPerFile, - cliTotal: "--max-semantic-unknowns", - cliPerFile: "--max-semantic-unknowns-per-file", doesNotRaise: "max_semantic_nodes, max_heap_mb, transfer ceilings, or the parent result budget", }, @@ -119,10 +116,27 @@ const semanticAdjustment = ( ? `${name} is already ${String(value)}, the maximum ${String(JAVASCRIPT_SEMANTIC_ITEM_MAXIMUM)}. Do not increase it further.` : `${name} is ${String(value)} (default ${String(fallback)}; an integer from 1 to ${String(JAVASCRIPT_SEMANTIC_ITEM_MAXIMUM)})`; +/** The per-call control of one semantic retention ceiling. */ +const semanticCeilingControl = ( + parameter: string, + value: number, + fallback: number, +): AnalysisParameterLimit => ({ + control_kind: "parameter", + parameter, + effective_value: value, + unit: "count", + minimum: 1, + maximum: JAVASCRIPT_SEMANTIC_ITEM_MAXIMUM, + default_value: fallback, + applies_at: "next_call", +}); + /** * Name the caller arguments for one semantic retention ceiling. - * Coverage limits list both effective values. The limitation claims only - * the ceilings that stopped retention. + * Coverage limits list both effective values. The limitation and the + * recorded controls claim only the ceilings that stopped retention; each + * adapter names the option that sets a control. */ export const javaScriptSemanticCeilingCoverage = ( kind: "nodes" | "unknowns", @@ -131,6 +145,7 @@ export const javaScriptSemanticCeilingCoverage = ( reached: { readonly total: boolean; readonly perFile: boolean }, ): { readonly limits: ApplicationCoverage["limits"]; + readonly controls: readonly AnalysisParameterLimit[]; readonly limitation: string; } => { const control = semanticControl[kind]; @@ -147,7 +162,6 @@ export const javaScriptSemanticCeilingCoverage = ( name: control.total, value: total, fallback: control.totalDefault, - cli: control.cliTotal, }, ] : []), @@ -157,7 +171,6 @@ export const javaScriptSemanticCeilingCoverage = ( name: control.perFile, value: perFile, fallback: control.perFileDefault, - cli: control.cliPerFile, }, ] : []), @@ -170,10 +183,12 @@ export const javaScriptSemanticCeilingCoverage = ( .map((item) => semanticAdjustment(item.name, item.value, item.fallback)) .join(" and "); const names = reachedControls.map((item) => item.name).join(" and "); - const cli = reachedControls.map((item) => item.cli).join(" and "); const raising = reachedControls.length === 1 ? "Raising it" : "Raising them"; - const limitation = `Semantic ${kind === "nodes" ? "node" : "unknown"} retention reached ${reachedText}. Set ${names} on the next analyze_javascript_application call (CLI: ${cli}). The change applies to that next analysis and does not restart the worker or the REA server. ${raising} does not raise ${control.doesNotRaise}. Coverage reports the same effective values as ${control.ceiling} and ${control.fileCeiling}.`; - return { limits, limitation }; + const limitation = `Semantic ${kind === "nodes" ? "node" : "unknown"} retention reached ${reachedText}. Set ${names} on the next analyze_javascript_application call; coverage.controls records ${reachedControls.length === 1 ? "it" : "them"}. The change applies to that next analysis and does not restart the worker or the REA server. ${raising} does not raise ${control.doesNotRaise}. Coverage reports the same effective values as ${control.ceiling} and ${control.fileCeiling}.`; + const controls = reachedControls.map((item) => + semanticCeilingControl(item.name, item.value, item.fallback), + ); + return { limits, controls, limitation }; }; /** Project observed execution limits without inventing unmeasured values. */ diff --git a/src/domain/javascript/javascriptSemanticGraphSchemas.ts b/src/domain/javascript/javascriptSemanticGraphSchemas.ts index a82cccfb66..16a8b5d6c8 100644 --- a/src/domain/javascript/javascriptSemanticGraphSchemas.ts +++ b/src/domain/javascript/javascriptSemanticGraphSchemas.ts @@ -14,6 +14,7 @@ import { import { jsonValueSchema } from "../jsonValue.js"; import { digestSchema, prefixedDigestSchema } from "../digests.js"; import { nonEmptyTextSchema } from "../textSchemas.js"; +import { analysisParameterLimitSchema } from "../analysisSettingDefinitions.js"; const semanticNodeIdSchema = prefixedDigestSchema("jsrg_node"); const semanticRelationIdSchema = z @@ -353,6 +354,11 @@ const graphCoverageSchema = z.strictObject({ unit: z.enum(["items", "bytes", "milliseconds", "depth", "other"]), }), ), + /** + * The request parameters that limited this graph: retention ceilings that + * stopped it and `semantic_precision` budgets that limited its sources. + */ + controls: z.array(analysisParameterLimitSchema).min(1).exactOptional(), families: z.array(familyCoverageSchema).length(12), }); diff --git a/src/domain/javascript/javascriptSemanticPrecision.test.ts b/src/domain/javascript/javascriptSemanticPrecision.test.ts index 69fff2efa0..495d6854d7 100644 --- a/src/domain/javascript/javascriptSemanticPrecision.test.ts +++ b/src/domain/javascript/javascriptSemanticPrecision.test.ts @@ -73,12 +73,30 @@ it("distinguishes wrapper work recovery from unchanged unsupported or cyclic syn expect.stringContaining("semantic_precision.wrapper_visits=1"), ]), ); + // The examination records the control by contract field; adapters name + // their own option for it, so no limitation names a CLI flag. + expect(bounded.analysis_coverage.examination.controls).toEqual([ + { + control_kind: "parameter", + parameter: "semantic_precision.wrapper_visits", + effective_value: 1, + unit: "count", + minimum: 1, + maximum: Number.MAX_SAFE_INTEGER, + default_value: 1_000_000, + applies_at: "next_call", + }, + ]); + expect(bounded.limitations.join(" ")).not.toContain("--semantic-precision"); const recovered = analyzeJavaScriptStaticSource(source, { wrapper_visits: 10_000, }); expect( recovered.analysis_coverage.examination.electron_call_paths_limited, ).toBe(false); + expect(recovered.analysis_coverage.examination).not.toHaveProperty( + "controls", + ); expect((recovered.electron.call_paths ?? []).length).toBeGreaterThan(0); const cycle = analyzeJavaScriptSemantics( "const a = b; const b = a; const selected = a;", diff --git a/src/domain/javascript/javascriptSemanticResourceLimits.ts b/src/domain/javascript/javascriptSemanticResourceLimits.ts index 31a5fbc96a..491674e8a6 100644 --- a/src/domain/javascript/javascriptSemanticResourceLimits.ts +++ b/src/domain/javascript/javascriptSemanticResourceLimits.ts @@ -1,3 +1,4 @@ +import type { AnalysisParameterLimit } from "../analysisSettings.js"; import type { JavaScriptSemanticResourceLimit, JavaScriptSemanticValue, @@ -35,6 +36,48 @@ export const semanticResourceLimitFacts = ( }; }; +/** One `semantic_precision` field. */ +export type JavaScriptSemanticPrecisionControl = + keyof JavaScriptSemanticPrecision; + +/** + * The per-call control of one evaluator budget, named by its contract field + * (`semantic_precision.`). Each adapter names the option that sets it. + */ +export const semanticPrecisionControl = ( + control: JavaScriptSemanticPrecisionControl, + precision: JavaScriptSemanticPrecision = JAVASCRIPT_SEMANTIC_PRECISION_DEFAULTS, +): AnalysisParameterLimit => ({ + control_kind: "parameter", + parameter: `semantic_precision.${control}`, + effective_value: precision[control], + unit: control === "primitive_bytes" ? "bytes" : "count", + minimum: 1, + maximum: Number.MAX_SAFE_INTEGER, + default_value: JAVASCRIPT_SEMANTIC_PRECISION_DEFAULTS[control], + applies_at: "next_call", +}); + +/** + * The evaluator budgets that limited a source, once each in field order: + * the controls of exhausted value budgets and of bounded wrapper expansion. + */ +export const semanticPrecisionControls = ( + resourceLimits: Iterable, + controls: Iterable, + precision: JavaScriptSemanticPrecision = JAVASCRIPT_SEMANTIC_PRECISION_DEFAULTS, +): AnalysisParameterLimit[] => { + const reached = new Set(controls); + for (const limit of resourceLimits) reached.add(resourceControls[limit][0]); + return ( + Object.keys( + JAVASCRIPT_SEMANTIC_PRECISION_DEFAULTS, + ) as JavaScriptSemanticPrecisionControl[] + ) + .filter((control) => reached.has(control)) + .map((control) => semanticPrecisionControl(control, precision)); +}; + /** Exact caller control and effective value at the evaluator boundary. */ export const semanticResourceLimitReason = ( resourceLimit: JavaScriptSemanticResourceLimit, @@ -49,7 +92,7 @@ export const semanticResourceLimitReason = ( "getter-expansion": `Getter expansion was conservatively bounded (maximum ${String(precision.getter_expansions)} scheduled states or a growing receiver cycle).`, "alias-selections": `Alias selection expansion was conservatively bounded (maximum ${String(precision.alias_selections)} additional selector states); selected paths remain unknown.`, }; - return `${prefixes[resourceLimit]} Semantic ${resourceLimit} budget reached: semantic_precision.${control}=${String(value)} ${displayUnit} (default ${String(defaultValue)}). Increase semantic_precision.${control} on the next analysis call (analyze_javascript_application or analyze_web_bundle), or pass --semantic-precision JSON on the CLI; no REA restart is required. Worker memory, transfer and graph-retention limits remain independent. Cyclic or unsupported evaluations remain unknown regardless of budget.`; + return `${prefixes[resourceLimit]} Semantic ${resourceLimit} budget reached: semantic_precision.${control}=${String(value)} ${displayUnit} (default ${String(defaultValue)}). Increase semantic_precision.${control} on the next analysis call (analyze_javascript_application or analyze_web_bundle); no REA restart is required. Worker memory, transfer and graph-retention limits remain independent. Cyclic or unsupported evaluations remain unknown regardless of budget.`; }; /** Check UTF-16 length against worst-case JSON escaping without flattening. */ diff --git a/src/domain/javascript/javascriptStaticAnalysis.ts b/src/domain/javascript/javascriptStaticAnalysis.ts index c6dfce971d..d61dc7ca49 100644 --- a/src/domain/javascript/javascriptStaticAnalysis.ts +++ b/src/domain/javascript/javascriptStaticAnalysis.ts @@ -36,7 +36,10 @@ import { hasPossibleCommonJsDelegateWrite, semanticFactoryLoaderMemberAt, } from "./javascriptSemanticRequireOrigin.js"; -import { semanticResourceLimitReason } from "./javascriptSemanticResourceLimits.js"; +import { + semanticPrecisionControls, + semanticResourceLimitReason, +} from "./javascriptSemanticResourceLimits.js"; import { createStaticPathIntrinsicQuery } from "./javascriptStaticPathIntrinsics.js"; import { createSemanticExpressionShapeResolver } from "./javascriptSemanticExpressionShapes.js"; import { finishElectronBrowserWindowsSteps } from "./electronStaticAnalysisBrowser.js"; @@ -264,6 +267,11 @@ const finalizeStaticAnalysis = ( value.loader !== "factory-loader", ); const resourceLimits = [...bindings.valueResourceLimits].sort(); + const controls = semanticPrecisionControls( + resourceLimits, + accumulator.electronCallPathLimits ?? [], + bindings.precision, + ); const candidateElectron = [ ...accumulator.browserWindows, ...accumulator.contextBridgeApis, @@ -303,6 +311,7 @@ const finalizeStaticAnalysis = ( : { semantic_precision: bindings.precision }), electron_call_paths_limited: (accumulator.electronCallPathLimits?.size ?? 0) > 0, + ...(controls.length === 0 ? {} : { controls }), }, applicability: { electron: electronObserved ? "observed" : "unknown" }, }; @@ -322,7 +331,7 @@ const finalizeStaticAnalysis = ( .sort() .map( (control) => - `Electron wrapper expansion reached semantic_precision.${control}=${String(bindings.precision[control])}. Increase semantic_precision.${control} on the next analyze_javascript_application call (--semantic-precision JSON); no REA restart is required. Worker memory and transfer admission remain independent; cyclic or unsupported paths remain unknown.`, + `Electron wrapper expansion reached semantic_precision.${control}=${String(bindings.precision[control])}. Increase semantic_precision.${control} on the next analyze_javascript_application call; coverage records the control. No REA restart is required. Worker memory and transfer admission remain independent; cyclic or unsupported paths remain unknown.`, ), ...(parserErrors === 0 ? [] diff --git a/src/domain/javascript/javascriptStaticCoverage.ts b/src/domain/javascript/javascriptStaticCoverage.ts index 839557a23d..4f210da198 100644 --- a/src/domain/javascript/javascriptStaticCoverage.ts +++ b/src/domain/javascript/javascriptStaticCoverage.ts @@ -1,5 +1,6 @@ import { javaScriptSemanticPrecisionSchema } from "./javascriptSemanticPrecision.js"; import { z } from "zod"; +import { analysisParameterLimitSchema } from "../analysisSettingDefinitions.js"; import { javaScriptSemanticResourceLimitSchema } from "./javascriptSemanticValueTypes.js"; import { javaScriptRefusedPhaseSchema } from "./javascriptSemanticWorkAllowance.js"; @@ -35,6 +36,8 @@ export const javaScriptStaticCoverageSchema = z.strictObject({ semantic_resource_limits: z.array(javaScriptSemanticResourceLimitSchema), semantic_precision: javaScriptSemanticPrecisionSchema.optional(), electron_call_paths_limited: z.boolean(), + /** The `semantic_precision` budgets that limited this source. */ + controls: z.array(analysisParameterLimitSchema).min(1).exactOptional(), /** The analysis phase whose work allowance refused this source. */ refused_phase: javaScriptRefusedPhaseSchema.exactOptional(), }), diff --git a/src/domain/managed/managedArtifact.ts b/src/domain/managed/managedArtifact.ts index 21f2badf54..6f0c7c232d 100644 --- a/src/domain/managed/managedArtifact.ts +++ b/src/domain/managed/managedArtifact.ts @@ -2,6 +2,7 @@ import { z } from "zod"; import { knownCoverageStatusSchema } from "../coverage.js"; import type { CoverageStatus } from "../coverage.js"; import { digestSchema } from "../digests.js"; +import { analysisParameterLimitSchema } from "../analysisSettingDefinitions.js"; import { managedFieldConstantSchema } from "./managedFieldConstant.js"; /** Build-local ECMA-335 metadata token emitted as an eight-digit lowercase hex value. */ @@ -459,6 +460,8 @@ const managedParseIssueSchema = z.object({ scope: z.string().min(1), offset: offsetSchema.nullable(), detail: z.string().min(1), + /** The request parameter that bounded a resource-limit issue. */ + limit: analysisParameterLimitSchema.exactOptional(), }); /** Provider-neutral, execution-free PE/CLI triage and identity result. */ diff --git a/src/domain/managed/managedDecodeBudget.ts b/src/domain/managed/managedDecodeBudget.ts index 18e899fa35..19801798f5 100644 --- a/src/domain/managed/managedDecodeBudget.ts +++ b/src/domain/managed/managedDecodeBudget.ts @@ -6,7 +6,10 @@ import { jsonStringByteLength } from "../jsonStringByteLength.js"; import type { ManagedMetadataLayout } from "./managedMetadataLayout.js"; import { ManagedReaderFailure } from "./managedReaderFailure.js"; -import { DEFAULT_MANAGED_REPRESENTATION_BYTES } from "./managedInspectionLimits.js"; +import { + DEFAULT_MANAGED_REPRESENTATION_BYTES, + managedRepresentationLimit, +} from "./managedInspectionLimits.js"; /** The capacity owner's diagnostic, also used to admit a recovery envelope. */ export class ManagedRepresentationFailure extends ManagedReaderFailure { @@ -14,8 +17,9 @@ export class ManagedRepresentationFailure extends ManagedReaderFailure { super({ code: "resource-limit", scope: "metadata.representation", - detail: `Managed metadata exceeds max_metadata_representation_bytes=${String(maximumBytes)} bytes. Increase max_metadata_representation_bytes on the next inspection (CLI --max-metadata-representation-bytes), or select fewer type_names for member inspection. No REA restart is required; snapshot, transport and host memory limits are independent.`, + detail: `Managed metadata exceeds max_metadata_representation_bytes=${String(maximumBytes)} bytes. Increase max_metadata_representation_bytes on the next inspection (the issue's limit records the control), or select fewer type_names for member inspection. No REA restart is required; snapshot, transport and host memory limits are independent.`, offset, + limit: managedRepresentationLimit(maximumBytes), }); } } diff --git a/src/domain/managed/managedInspectionLimits.ts b/src/domain/managed/managedInspectionLimits.ts index 37b16f0f4e..6360877d61 100644 --- a/src/domain/managed/managedInspectionLimits.ts +++ b/src/domain/managed/managedInspectionLimits.ts @@ -1,9 +1,27 @@ import { z } from "zod"; +import type { AnalysisParameterLimit } from "../analysisSettings.js"; /** Defaults for one execution-free managed inspection, not PE format limits. */ export const DEFAULT_MANAGED_SNAPSHOT_BYTES = 128 * 1024 * 1024; export const DEFAULT_MANAGED_REPRESENTATION_BYTES = 64 * 1024 * 1024; +/** + * The per-call control that bounded accounted metadata representation, named + * by its contract field; each adapter names the option that sets it. + */ +export const managedRepresentationLimit = ( + maximumBytes: number, +): AnalysisParameterLimit => ({ + control_kind: "parameter", + parameter: "max_metadata_representation_bytes", + effective_value: maximumBytes, + unit: "bytes", + minimum: 1, + maximum: Number.MAX_SAFE_INTEGER, + default_value: DEFAULT_MANAGED_REPRESENTATION_BYTES, + applies_at: "next_call", +}); + export const managedInspectionBudgetShape = { max_snapshot_bytes: z .int() diff --git a/src/domain/managed/managedMemberComparisonCoverage.ts b/src/domain/managed/managedMemberComparisonCoverage.ts index b3a3a63b66..4c07415c18 100644 --- a/src/domain/managed/managedMemberComparisonCoverage.ts +++ b/src/domain/managed/managedMemberComparisonCoverage.ts @@ -131,8 +131,18 @@ export type ManagedComparisonScope = ReturnType; const resourceLimits = ( result: ManagedMemberInspection, ): NonNullable => - result.coverage.issues.flatMap(({ code, scope, detail, offset }) => - code === "resource-limit" ? [{ code, scope, detail, offset }] : [], + result.coverage.issues.flatMap(({ code, scope, detail, offset, limit }) => + code === "resource-limit" + ? [ + { + code, + scope, + detail, + offset, + ...(limit === undefined ? {} : { limit }), + }, + ] + : [], ); export const sideManifest = ( diff --git a/src/domain/native/kernelModule.ts b/src/domain/native/kernelModule.ts index 02b018cc8d..7e433a69a3 100644 --- a/src/domain/native/kernelModule.ts +++ b/src/domain/native/kernelModule.ts @@ -1,5 +1,7 @@ import { z } from "zod"; import { knownCoverageStatusSchema } from "../coverage.js"; +import type { AnalysisParameterLimit } from "../analysisSettings.js"; +import { analysisParameterLimitSchema } from "../analysisSettingDefinitions.js"; import { digestSchema } from "../digests.js"; import { fixedTupleSchema } from "../fixedTupleSchema.js"; @@ -21,6 +23,27 @@ export const MAX_INSPECT_KERNEL_MODULE_ENTRIES = 65536; /** Default per-field retention budgets; omission does not establish malformed syntax. */ export const DEFAULT_KERNEL_MODULE_KEY_BYTES = 256; export const DEFAULT_KERNEL_MODULE_VALUE_BYTES = 4096; + +/** + * The per-call control that omitted .modinfo key or value text, named by its + * contract field; each adapter names the option that sets it. + */ +export const kernelModuleModinfoLimit = ( + field: "key" | "value", + selectedBytes: number, +): AnalysisParameterLimit => ({ + control_kind: "parameter", + parameter: `max_modinfo_${field}_bytes`, + effective_value: selectedBytes, + unit: "bytes", + minimum: 1, + maximum: MAX_INSPECT_KERNEL_MODULE_FILE_BYTES, + default_value: + field === "key" + ? DEFAULT_KERNEL_MODULE_KEY_BYTES + : DEFAULT_KERNEL_MODULE_VALUE_BYTES, + applies_at: "next_call", +}); /** * Retained __ksymtab* section-name length. Longer names stay listed with a * null name and are not copied into the result. @@ -119,6 +142,12 @@ const modinfoSchema = z.strictObject({ sha256: digestSchema.nullable(), entries: z.array(modinfoEntrySchema), reason: z.enum(KERNEL_MODULE_MODINFO_SECTION_REASONS).nullable(), + /** The request parameters that omitted key or value text, when any did. */ + omission_limits: z + .array(analysisParameterLimitSchema) + .min(1) + .max(2) + .exactOptional(), }); const versionEntrySchema = z.strictObject({ diff --git a/src/domain/native/nativeDeadlines.ts b/src/domain/native/nativeDeadlines.ts index f95cce3bda..d3f6420ef4 100644 --- a/src/domain/native/nativeDeadlines.ts +++ b/src/domain/native/nativeDeadlines.ts @@ -1,5 +1,6 @@ import { MAX_NODE_TIMER_DELAY_MS, + deadlineParameterLimit, timerDurationMsSchema, } from "../analysisResourceLimits.js"; @@ -91,16 +92,11 @@ export const nativeDeadlineRecovery = (input: { return { userMessage: `This request reached REA's ${input.phase} of ${String(input.timeoutMs)} ms (${input.parameter}). This is a server/provider deadline, not the MCP client deadline.${input.detail ?? ""}`, remediationAction: `${adjustment} ${input.unchanged} Allow execution, cleanup, and delivery headroom in the outer MCP client deadline. Confirm outstanding work and cleanup before retrying.`, - limit: { - control_kind: "parameter", - parameter: input.parameter, - effective_value: input.timeoutMs, - unit: "ms", - minimum: 1, - maximum: MAX_NODE_TIMER_DELAY_MS, - default_value: input.defaultMs, - applies_at: "next_call", - }, + limit: deadlineParameterLimit( + input.parameter, + input.timeoutMs, + input.defaultMs, + ), }; }; diff --git a/src/domain/producerResourceLimits.ts b/src/domain/producerResourceLimits.ts index 866b510912..4dc8b78ae3 100644 --- a/src/domain/producerResourceLimits.ts +++ b/src/domain/producerResourceLimits.ts @@ -1,5 +1,6 @@ import { z } from "zod"; import { timerDurationMsSchema } from "./analysisResourceLimits.js"; +import type { AnalysisParameterLimit } from "./analysisSettings.js"; /** Per-call owned producer budgets. Each adapter advertises only consumed fields. */ export const producerResourceLimitsSchema = z.strictObject({ @@ -40,6 +41,26 @@ export const resolveProducerLimits = < ]), ) as { readonly [Key in keyof Defaults]: number }; +/** + * The per-call control of one exhausted producer budget, named by its + * contract path (`producer_limits.`); each adapter names the option + * that sets it. + */ +export const producerLimitControl = ( + field: Exclude, + effectiveValue: number, + defaultValue: number, +): AnalysisParameterLimit => ({ + control_kind: "parameter", + parameter: `producer_limits.${field}`, + effective_value: effectiveValue, + unit: field === "cpu_seconds" ? "seconds" : "bytes", + minimum: 1, + maximum: Number.MAX_SAFE_INTEGER, + default_value: defaultValue, + applies_at: "next_call", +}); + /** Combined-output producers have no separate diagnostic capture control. */ export const boundedProducerLimitsSchema = producerResourceLimitsSchema .omit({ diagnostic_bytes: true }) diff --git a/src/domain/reverseEngineering.ts b/src/domain/reverseEngineering.ts index ea0183b35d..1058c225b8 100644 --- a/src/domain/reverseEngineering.ts +++ b/src/domain/reverseEngineering.ts @@ -1,4 +1,5 @@ import { timerDurationMsSchema } from "./analysisResourceLimits.js"; +import type { AnalysisControlLimit } from "./analysisSettings.js"; import { z } from "zod"; import { constants as bufferConstants } from "node:buffer"; import { commandEvidenceDetailSchema } from "./commandObservation.js"; @@ -15,6 +16,22 @@ export const DEFAULT_REVERSE_COMMAND_OUTPUT_BYTES = 16 * 1024 * 1024; export const MAX_REVERSE_COMMAND_OUTPUT_BYTES = Math.floor( (bufferConstants.MAX_STRING_LENGTH - 1024 * 1024) / (2 * 6), ); +/** + * The per-call control that bounded a one-shot command's captured output, + * named by its contract field; each adapter names the option that sets it. + */ +export const reverseCommandOutputLimit = ( + bytes: number, +): AnalysisControlLimit => ({ + control_kind: "parameter", + parameter: "max_output_bytes", + effective_value: bytes, + unit: "bytes", + minimum: 1, + maximum: MAX_REVERSE_COMMAND_OUTPUT_BYTES, + default_value: DEFAULT_REVERSE_COMMAND_OUTPUT_BYTES, + applies_at: "next_call", +}); const reverseCommandOutputBytesSchema = z .number() .int() diff --git a/src/domain/rust/rustBinary.ts b/src/domain/rust/rustBinary.ts index 3b6d6e84da..ad15aee62c 100644 --- a/src/domain/rust/rustBinary.ts +++ b/src/domain/rust/rustBinary.ts @@ -1,5 +1,10 @@ import { z } from "zod"; -import { rustProducerLimitsField } from "./rustResourceLimits.js"; +import { + RUST_PRODUCER_DEFAULTS, + rustProducerLimitsField, +} from "./rustResourceLimits.js"; +import { analysisParameterLimitSchema } from "../analysisSettingDefinitions.js"; +import { producerLimitControl } from "../producerResourceLimits.js"; import { digestSchema } from "../digests.js"; import { absoluteLocalPathStringSchema, @@ -63,6 +68,8 @@ export const rustcCommitSchema = z.strictObject({ status: z.literal("partial"), reason: z.enum(["max_rustc_hashes", "report_bytes"]), effective_limit: z.int().positive(), + /** The request parameter that bounded retention, and how to change it. */ + limit: analysisParameterLimitSchema.exactOptional(), }) .exactOptional(), hashes: z @@ -75,6 +82,48 @@ export const rustcCommitSchema = z.strictObject({ .min(1), }); +/** + * The complete-report allowance left no room for any compiler path; the + * control that bounded it, recorded outside the dropped compiler record. + */ +export const rustcCommitOmissionSchema = z.strictObject({ + reason: z.literal("report_bytes"), + limit: analysisParameterLimitSchema, +}); + +type RustcCoverage = NonNullable["coverage"]>; + +/** + * Partial compiler-path coverage and the per-call control that bounded it: + * `max_rustc_hashes` for the path count, `producer_limits.output_bytes` for + * the complete-report allowance. Each adapter names the option that sets it. + */ +export const rustcPartialCoverage = ( + reason: RustcCoverage["reason"], + effectiveLimit: number, +): RustcCoverage => ({ + status: "partial", + reason, + effective_limit: effectiveLimit, + limit: + reason === "report_bytes" + ? producerLimitControl( + "output_bytes", + effectiveLimit, + RUST_PRODUCER_DEFAULTS.output_bytes, + ) + : { + control_kind: "parameter", + parameter: "max_rustc_hashes", + effective_value: effectiveLimit, + unit: "count", + minimum: 1, + maximum: Number.MAX_SAFE_INTEGER, + default_value: DEFAULT_RUSTC_HASH_LIMIT, + applies_at: "next_call", + }, +}); + /** One explicit local executable or library, independent of a disassembler target. */ export const inspectRustBinaryInputSchema = z.strictObject({ path: absoluteLocalPathStringSchema.describe( @@ -107,6 +156,11 @@ export const rustBinarySchema = z selected_slice: machoTargetSelectionSchema.exactOptional(), auditable_metadata: rustAuditableMetadataSchema.nullable(), rustc_commit: rustcCommitSchema.nullable(), + /** + * Present when the complete-report allowance left no room for any + * compiler path, so `rustc_commit` is null: the control that bounded it. + */ + rustc_commit_omission: rustcCommitOmissionSchema.exactOptional(), limitations: z.array(z.string()), }) .superRefine((report, context) => { @@ -116,6 +170,15 @@ export const rustBinarySchema = z checkPackages(metadata, context); } checkRustc(report.artifact.bytes, report.rustc_commit, context); + if ( + report.rustc_commit_omission !== undefined && + report.rustc_commit !== null + ) + issue( + context, + ["rustc_commit_omission"], + "A compiler-path omission is recorded only when no compiler path was retained.", + ); checkSlice(report, context); }); diff --git a/src/domain/webBundleAnalysis.ts b/src/domain/webBundleAnalysis.ts index fdc648f80f..bfac18cbf5 100644 --- a/src/domain/webBundleAnalysis.ts +++ b/src/domain/webBundleAnalysis.ts @@ -1,6 +1,9 @@ -import { MAX_NODE_TIMER_DELAY_MS } from "./analysisResourceLimits.js"; +import { + MAX_NODE_TIMER_DELAY_MS, + deadlineParameterLimit, +} from "./analysisResourceLimits.js"; import type { AnalysisControlLimit } from "./analysisSettings.js"; -import { analysisSettingLimitSchema } from "./analysisSettingDefinitions.js"; +import { analysisResultLimitSchema } from "./analysisSettingDefinitions.js"; import { javaScriptSemanticPrecisionSchema } from "./javascript/javascriptSemanticPrecision.js"; import { javaScriptRefusedPhaseSchema } from "./javascript/javascriptSemanticWorkAllowance.js"; import { fetchedSourceMapLimitsSchema } from "./sourceMapLimits.js"; @@ -12,6 +15,7 @@ import { javaScriptRouteInventorySchema } from "./javascript/javascriptRouteInve import { browserDeadlineIncrease, + type BrowserDeadlineRecovery, browserDeadlineRetry, noRuntimeOverrideSentence, optionalBrowserDeadlineMs, @@ -101,17 +105,27 @@ export type AnalyzeWebBundleInput = z.infer; /** Per-script deadlineExpired text. It is not the total analysis deadline. */ export const webBundleScriptTimeoutRecovery = ( timeoutMs: number, -): { readonly userMessage: string; readonly remediationAction: string } => ({ +): BrowserDeadlineRecovery => ({ userMessage: `analyze_web_bundle reached its ${String(timeoutMs)} ms per-script deadline (deadlineExpired) for analysis_timeout_ms. This is not total_analysis_timeout_ms and not the MCP client deadline.`, - remediationAction: `${browserDeadlineIncrease("analysis_timeout_ms", timeoutMs, DEFAULT_WEB_BUNDLE_SCRIPT_TIMEOUT_MS, "--analysis-timeout-ms")} Keep it less than or equal to total_analysis_timeout_ms (omitted means ${String(DEFAULT_WEB_BUNDLE_TOTAL_TIMEOUT_MS)}); a per-script timeout above the total is rejected. ${browserDeadlineRetry} analysis_timeout_ms does not raise max_heap_mb, total_analysis_timeout_ms, or the fixed worker protocol and result byte budgets.`, + limit: deadlineParameterLimit( + "analysis_timeout_ms", + timeoutMs, + DEFAULT_WEB_BUNDLE_SCRIPT_TIMEOUT_MS, + ), + remediationAction: `${browserDeadlineIncrease("analysis_timeout_ms", timeoutMs, DEFAULT_WEB_BUNDLE_SCRIPT_TIMEOUT_MS)} Keep it less than or equal to total_analysis_timeout_ms (omitted means ${String(DEFAULT_WEB_BUNDLE_TOTAL_TIMEOUT_MS)}); a per-script timeout above the total is rejected. ${browserDeadlineRetry} analysis_timeout_ms does not raise max_heap_mb, total_analysis_timeout_ms, or the fixed worker protocol and result byte budgets.`, }); /** Total captured-script deadlineExpired text. */ export const webBundleTotalTimeoutRecovery = ( timeoutMs: number, -): { readonly userMessage: string; readonly remediationAction: string } => ({ +): BrowserDeadlineRecovery => ({ userMessage: `analyze_web_bundle reached its ${String(timeoutMs)} ms total captured-script analysis deadline (deadlineExpired) for total_analysis_timeout_ms. This is not the per-script analysis_timeout_ms, not capture, and not source-map fetch.`, - remediationAction: `${browserDeadlineIncrease("total_analysis_timeout_ms", timeoutMs, DEFAULT_WEB_BUNDLE_TOTAL_TIMEOUT_MS, "--total-analysis-timeout-ms")} A per-script analysis_timeout_ms above the total is rejected. ${browserDeadlineRetry} total_analysis_timeout_ms does not raise analysis_timeout_ms, max_heap_mb, source_map_fetch_timeout_ms, or the fixed worker byte budgets.`, + limit: deadlineParameterLimit( + "total_analysis_timeout_ms", + timeoutMs, + DEFAULT_WEB_BUNDLE_TOTAL_TIMEOUT_MS, + ), + remediationAction: `${browserDeadlineIncrease("total_analysis_timeout_ms", timeoutMs, DEFAULT_WEB_BUNDLE_TOTAL_TIMEOUT_MS)} A per-script analysis_timeout_ms above the total is rejected. ${browserDeadlineRetry} total_analysis_timeout_ms does not raise analysis_timeout_ms, max_heap_mb, source_map_fetch_timeout_ms, or the fixed worker byte budgets.`, }); /** @@ -543,8 +557,8 @@ export const webBundleAnalysisSchema = z.object({ dimension: z.string(), reason: z.string(), affected_script_keys: z.array(z.string()), - /** The setting that bounded these scripts, and how to change it. */ - limit: analysisSettingLimitSchema.exactOptional(), + /** The setting or request parameter that bounded these scripts, and how to change it. */ + limit: analysisResultLimitSchema.exactOptional(), remediation: z.string().exactOptional(), /** * The phase a work allowance refused for these scripts. Their parse diff --git a/src/domain/webBundleScriptAnalysis.ts b/src/domain/webBundleScriptAnalysis.ts index c58db6756b..04f9b83468 100644 --- a/src/domain/webBundleScriptAnalysis.ts +++ b/src/domain/webBundleScriptAnalysis.ts @@ -1,11 +1,12 @@ import { z } from "zod"; import { webBundleAnalysisSchema } from "./webBundleAnalysis.js"; -import { analysisSettingLimitSchema } from "./analysisSettingDefinitions.js"; +import { analysisResultLimitSchema } from "./analysisSettingDefinitions.js"; import { javaScriptRouteSourceFactsSchema } from "./javascript/javascriptRouteFacts.js"; import { javaScriptRefusedPhaseSchema } from "./javascript/javascriptSemanticWorkAllowance.js"; import type { AnalysisError } from "./analysisErrorBase.js"; import { AnalysisResourceConstraintError } from "./analysisErrorCore.js"; +import { analysisErrorRemediationAction } from "./analysisErrorPresentation.js"; const observationsSchema = z.strictObject({ edges: webBundleAnalysisSchema.shape.observations.shape.chunks.shape.edges, @@ -49,8 +50,8 @@ export const webBundleScriptAnalysisSchema = z "not_started", ]), detail: z.string().optional(), - /** The setting that bounded this script, when a setting refused it. */ - limit: analysisSettingLimitSchema.exactOptional(), + /** The setting or request parameter that bounded this script. */ + limit: analysisResultLimitSchema.exactOptional(), remediation: z.string().exactOptional(), /** Facts gathered before a work allowance refused a later phase. */ partial: refusedScriptFactsSchema.exactOptional(), @@ -162,26 +163,42 @@ type UnavailableWebScriptAnalysis = Extract< { readonly status: "unavailable" } >; +/** + * The control a script result can record: a registered setting, or a request + * parameter named by its contract field. An environment control is not a + * result-side reference, so its error keeps only the detail. + */ +const recordedLimit = ( + limit: AnalysisError["limit"], +): UnavailableWebScriptAnalysis["limit"] => + limit === undefined + ? undefined + : "setting" in limit + ? limit + : limit.control_kind === "parameter" + ? limit + : undefined; + /** * The detail and structured recovery an unavailable script states for the - * error that stopped its analysis. Only a registered setting's limit is kept. + * error that stopped its analysis, such as a resource refusal or a per-script + * deadline. */ export const unavailableWebScriptRecovery = ( error: AnalysisError, -): Pick => ({ - detail: - error instanceof AnalysisResourceConstraintError && - error.reportedLimits !== null - ? `${error.userMessage ?? error.reason} Reported limits: ${JSON.stringify(error.reportedLimits)}` - : (error.userMessage ?? error.message), - ...(error instanceof AnalysisResourceConstraintError && - error.limit !== undefined && - "setting" in error.limit - ? { - limit: error.limit, - ...(error.remediationAction === undefined - ? {} - : { remediation: error.remediationAction }), - } - : {}), -}); +): Pick => { + const limit = recordedLimit(error.limit); + return { + detail: + error instanceof AnalysisResourceConstraintError && + error.reportedLimits !== null + ? `${error.userMessage ?? error.reason} Reported limits: ${JSON.stringify(error.reportedLimits)}` + : (error.userMessage ?? error.message), + ...(limit === undefined + ? {} + : { + limit, + remediation: analysisErrorRemediationAction(error), + }), + }; +}; diff --git a/src/domain/webDeadlineControls.test.ts b/src/domain/webDeadlineControls.test.ts index 9b473949fd..120787e1cd 100644 --- a/src/domain/webDeadlineControls.test.ts +++ b/src/domain/webDeadlineControls.test.ts @@ -131,6 +131,8 @@ describe("web deadline controls", () => { ); expect(inspector.userMessage).not.toContain("command_timeout_ms"); expect(inspector.remediationAction).not.toContain("--command-timeout-ms"); + // A fixed deadline binds no per-call control. + expect(inspector.limit).toBeUndefined(); expect(inspector.remediationAction).toContain("no runtime override"); const selectableDiscovery = cdpDiscoveryTimeoutRecovery( "inspect_web_page", @@ -144,9 +146,12 @@ describe("web deadline controls", () => { expect(selectableDiscovery.remediationAction).toContain( "Increase discovery_timeout_ms above 15000", ); - expect(selectableDiscovery.remediationAction).toContain( - "--discovery-timeout-ms", - ); + expect(selectableDiscovery.remediationAction).not.toContain("--"); + expect(selectableDiscovery.limit).toMatchObject({ + control_kind: "parameter", + parameter: "discovery_timeout_ms", + effective_value: 15_000, + }); expect(selectableDiscovery.remediationAction).toContain( "command_timeout_ms does not raise it", ); @@ -160,6 +165,7 @@ describe("web deadline controls", () => { expect(fixedDiscovery.remediationAction).not.toContain( "--discovery-timeout-ms", ); + expect(fixedDiscovery.limit).toBeUndefined(); expect(fixedDiscovery.remediationAction).toContain("no runtime override"); }); }); diff --git a/src/domain/webNetworkCapture.ts b/src/domain/webNetworkCapture.ts index 388aeb3495..a3d5bc5d84 100644 --- a/src/domain/webNetworkCapture.ts +++ b/src/domain/webNetworkCapture.ts @@ -1,9 +1,11 @@ +import { deadlineParameterLimit } from "./analysisResourceLimits.js"; import { createHash } from "node:crypto"; import { canonicalBase64Schema } from "./stringPatterns.js"; import { z } from "zod"; import { knownCoverageStatusSchema } from "./coverage.js"; import { browserDeadlineIncrease, + type BrowserDeadlineRecovery, browserDeadlineRetry, optionalBrowserDeadlineMs, selectedBrowserDeadlineMs, @@ -112,9 +114,14 @@ export const selectedWebNetworkCaptureTimeoutMs = ( /** Caller-visible capture deadline; byte/depth budgets have separate per-call controls. */ export const webNetworkCaptureTimeoutRecovery = ( timeoutMs: number, -): { readonly userMessage: string; readonly remediationAction: string } => ({ +): BrowserDeadlineRecovery => ({ userMessage: `inspect_web_network_capture reached its ${String(timeoutMs)} ms capture deadline (deadlineExpired) for capture_timeout_ms. No partial capture is returned. This is not the MCP client deadline.`, - remediationAction: `${browserDeadlineIncrease("capture_timeout_ms", timeoutMs, DEFAULT_WEB_NETWORK_CAPTURE_TIMEOUT_MS, "--capture-timeout-ms")} ${browserDeadlineRetry} The separate max_input_bytes, max_reply_bytes and max_nesting_depth controls apply to the next call without restarting REA; capture_timeout_ms does not raise them.`, + limit: deadlineParameterLimit( + "capture_timeout_ms", + timeoutMs, + DEFAULT_WEB_NETWORK_CAPTURE_TIMEOUT_MS, + ), + remediationAction: `${browserDeadlineIncrease("capture_timeout_ms", timeoutMs, DEFAULT_WEB_NETWORK_CAPTURE_TIMEOUT_MS)} ${browserDeadlineRetry} The separate max_input_bytes, max_reply_bytes and max_nesting_depth controls apply to the next call without restarting REA; capture_timeout_ms does not raise them.`, }); export const WEB_NETWORK_CAPTURE_FORMATS = [ diff --git a/src/domain/webSourceLocation.ts b/src/domain/webSourceLocation.ts index c61deafb37..102a63c9b2 100644 --- a/src/domain/webSourceLocation.ts +++ b/src/domain/webSourceLocation.ts @@ -1,3 +1,4 @@ +import { deadlineParameterLimit } from "./analysisResourceLimits.js"; import { localSourceMapLimitsSchema, WEB_SOURCE_MAP_LIMITS, @@ -5,6 +6,7 @@ import { import { z } from "zod"; import { browserDeadlineIncrease, + type BrowserDeadlineRecovery, browserDeadlineRetry, optionalBrowserDeadlineMs, } from "./browserDeadline.js"; @@ -133,9 +135,14 @@ export const DEFAULT_WEB_SOURCE_MAP_DECODE_TIMEOUT_MS = /** Source-map decode deadlineExpired text for trace_web_source_location. */ export const webSourceMapDecodeTimeoutRecovery = ( timeoutMs: number, -): { readonly userMessage: string; readonly remediationAction: string } => ({ +): BrowserDeadlineRecovery => ({ userMessage: `trace_web_source_location reached its ${String(timeoutMs)} ms source-map decode deadline (deadlineExpired) for decode_timeout_ms. No partial mapping is returned. This is not the MCP client deadline.`, - remediationAction: `${browserDeadlineIncrease("decode_timeout_ms", timeoutMs, DEFAULT_WEB_SOURCE_MAP_DECODE_TIMEOUT_MS, "--decode-timeout-ms")} ${browserDeadlineRetry} Byte, record and heap admission are separate per-call source_map_limits fields; changing the deadline does not raise them.`, + limit: deadlineParameterLimit( + "decode_timeout_ms", + timeoutMs, + DEFAULT_WEB_SOURCE_MAP_DECODE_TIMEOUT_MS, + ), + remediationAction: `${browserDeadlineIncrease("decode_timeout_ms", timeoutMs, DEFAULT_WEB_SOURCE_MAP_DECODE_TIMEOUT_MS)} ${browserDeadlineRetry} Byte, record and heap admission are separate per-call source_map_limits fields; changing the deadline does not raise them.`, }); export type WebSourceMapReport = z.output; diff --git a/src/evm/EvmoleFailures.test.ts b/src/evm/EvmoleFailures.test.ts index 892195b8e3..a567bcfe88 100644 --- a/src/evm/EvmoleFailures.test.ts +++ b/src/evm/EvmoleFailures.test.ts @@ -114,7 +114,13 @@ it("names timeout_ms, the omitted default, and the caps it does not raise", () = }); expect(projected.message).toContain("timeout_ms"); expect(projected.message).toContain(String(DEFAULT_EVM_TIMEOUT_MS)); - expect(projected.remediation.action).toContain("--timeout-ms"); + expect(projected.remediation.action).not.toContain("--"); + expect(projected.details?.limit).toMatchObject({ + control_kind: "parameter", + parameter: "timeout_ms", + effective_value: 45_000, + default_value: DEFAULT_EVM_TIMEOUT_MS, + }); expect(projected.remediation.action).toContain( String(MAX_NODE_TIMER_DELAY_MS), ); diff --git a/src/evm/EvmoleFailures.ts b/src/evm/EvmoleFailures.ts index 94ca5059ff..32759a4ef3 100644 --- a/src/evm/EvmoleFailures.ts +++ b/src/evm/EvmoleFailures.ts @@ -1,17 +1,15 @@ +import { + deadlineParameterLimit, + MAX_NODE_TIMER_DELAY_MS, +} from "../domain/analysisResourceLimits.js"; import { capturedProviderOutput } from "../process/capturedProviderOutput.js"; -import { MAX_NODE_TIMER_DELAY_MS } from "../domain/analysisResourceLimits.js"; import type { EvmWorkerLimits } from "./EvmWorkerLimits.js"; -import type { - AnalysisCapturedOutput, - AnalysisErrorOptions, -} from "../domain/analysisErrorBase.js"; -import type { ProviderProcessSnapshot } from "../process/ProviderProcess.js"; +import type { AnalysisErrorOptions } from "../domain/analysisErrorBase.js"; import { AnalysisCapabilityUnavailableError, AnalysisResourceConstraintError, } from "../domain/analysisErrorCore.js"; import { ProviderAdapterError } from "../domain/providerAdapterError.js"; -import { ProviderCleanupError } from "../domain/providerCleanupError.js"; import type { ProviderOutcomeContext } from "../process/classifyProviderOutcome.js"; import type { ProviderFailureDialect } from "../providers/classifyProviderFailure.js"; import { @@ -53,7 +51,7 @@ export const evmReplyBudgetFailure = ( const evmTimeoutRecovery = (timeoutMs: number): string => `${ timeoutMs < MAX_NODE_TIMER_DELAY_MS - ? `Increase timeout_ms above ${String(timeoutMs)} (integer milliseconds, maximum ${String(MAX_NODE_TIMER_DELAY_MS)}), or use rea inspect-evm-interface --timeout-ms on the CLI.` + ? `Increase timeout_ms above ${String(timeoutMs)} (integer milliseconds, maximum ${String(MAX_NODE_TIMER_DELAY_MS)}).` : `timeout_ms is already at the maximum supported ${String(MAX_NODE_TIMER_DELAY_MS)} ms; no higher worker deadline is supported. Report this blocker or select another suitable complete carrier with caller approval.` } This is a per-call setting; no server restart is needed. It covers the owned EVMole worker command, not carrier acquisition or final reply reads. Allow the MCP client deadline to cover acquisition, the worker, reply reads, cleanup and delivery; increasing only that client deadline does not change this budget. Separate producer_limits control carrier/reply/diagnostic bytes, address-space/file bytes and CPU seconds; timeout_ms does not raise them. The 256 MiB worker heap stays independent. Resolve any incomplete cleanup before retrying; do not repeat the unchanged failed call.`; @@ -99,28 +97,6 @@ export const evmFailureDialect = ( providerId: EVMOLE_PROVIDER_IDENTITY.id, operation: OPERATION, command: () => evmCommandContext(resolved), - commandCleanup: (failure) => - new ProviderCleanupError( - EVMOLE_PROVIDER_IDENTITY.id, - failure.resources, - { - reason: failure.cleanupFailure, - ...(failure.snapshot === null - ? {} - : { - captured_output: { - ...capturedProviderOutput(failure.snapshot), - }, - }), - previous_error: { - failure_kind: failure.reason, - message: failure.message, - exit_code: failure.snapshot?.exitCode ?? null, - signal: failure.snapshot?.signal ?? null, - }, - }, - { operation: OPERATION, cause: failure }, - ), ...(phase === "artifact-read" ? { file: { @@ -173,6 +149,11 @@ const evmCommandContext = ( ms: timeoutMs, userMessage: `The EVMole worker reached its ${String(timeoutMs)} ms server/provider deadline (timeout_ms). This is not a carrier-read or MCP client deadline. Omitted timeout_ms uses ${String(DEFAULT_EVM_TIMEOUT_MS)} ms.`, remediationAction: evmTimeoutRecovery(timeoutMs), + limit: deadlineParameterLimit( + "timeout_ms", + timeoutMs, + DEFAULT_EVM_TIMEOUT_MS, + ), }, outputLimit: { limits: { diff --git a/src/flutter/FlutterBuildProvider.ts b/src/flutter/FlutterBuildProvider.ts index a581ff7fbb..03d966b286 100644 --- a/src/flutter/FlutterBuildProvider.ts +++ b/src/flutter/FlutterBuildProvider.ts @@ -28,7 +28,9 @@ import { import { createAnalysisExecutionEvidence } from "../domain/analysisObservation.js"; import { MAX_FLUTTER_LIBRARY_PATH_BYTES, + dartPoolBudgetLimit, dartPoolPolicy, + type DartPoolBudget, type DartPoolPolicy, type FlutterRequest, } from "../domain/flutter/flutterBuildAnalysis.js"; @@ -1305,6 +1307,14 @@ export class FlutterBuildProvider { dataHeaders.some((section) => !section.header.complete) || hashScan.candidates.length !== 1 || hashScan.sources !== SYMBOL_PAIR_COUNT; + const poolBudgetsReached = new Set(pool.limitsReached); + if ( + pool.packageUriCount > poolPolicy.uri_limit || + pool.dartUriCount > poolPolicy.uri_limit + ) + poolBudgetsReached.add("uri_limit"); + if (pool.classLikeTokenCount > poolPolicy.token_limit) + poolBudgetsReached.add("token_limit"); const poolPartial = isolateData === null || pool.collectionCapped || @@ -1339,6 +1349,13 @@ export class FlutterBuildProvider { ), class_like_token_count_at_least: pool.classLikeTokenCount, printable_run_count: pool.printableRunCount, + ...(poolBudgetsReached.size === 0 + ? {} + : { + limits: [...poolBudgetsReached].map((budget) => + dartPoolBudgetLimit(budget, poolPolicy), + ), + }), }, coverage: snapshotPartial || poolPartial ? "partial" : "complete", }, @@ -1377,21 +1394,21 @@ export class FlutterBuildProvider { ), ...pool.limitsReached.map( (limit) => - `String-pool admission reached pool_policy.${limit}=${String(poolPolicy[limit])}. Retry with a narrower pool_policy.contains or increase ${limit} (CLI --pool-policy JSON); no REA restart is required. Counts remain lower bounds and overflowed runs are omitted. APK, library and response limits are unchanged`, + `String-pool admission reached pool_policy.${limit}=${String(poolPolicy[limit])}. Retry with a narrower pool_policy.contains or increase ${limit}; string_pool.limits records the control and no REA restart is required. Counts remain lower bounds and overflowed runs are omitted. APK, library and response limits are unchanged`, ), ...(pool.dartUriCount > poolPolicy.uri_limit ? [ - `dart_uris reports ${String(poolPolicy.uri_limit)} of at least ${String(pool.dartUriCount)} distinct URIs; narrow pool_policy.contains or raise pool_policy.uri_limit (CLI --pool-policy JSON) on a new call, no restart required`, + `dart_uris reports ${String(poolPolicy.uri_limit)} of at least ${String(pool.dartUriCount)} distinct URIs; narrow pool_policy.contains or raise pool_policy.uri_limit (recorded in string_pool.limits) on a new call, no restart required`, ] : []), ...(pool.packageUriCount > poolPolicy.uri_limit ? [ - `package_uris reports ${String(poolPolicy.uri_limit)} of at least ${String(pool.packageUriCount)} distinct URIs; narrow pool_policy.contains or raise pool_policy.uri_limit (CLI --pool-policy JSON) on a new call, no restart required`, + `package_uris reports ${String(poolPolicy.uri_limit)} of at least ${String(pool.packageUriCount)} distinct URIs; narrow pool_policy.contains or raise pool_policy.uri_limit (recorded in string_pool.limits) on a new call, no restart required`, ] : []), ...(pool.classLikeTokenCount > poolPolicy.token_limit ? [ - `class_like_tokens reports ${String(poolPolicy.token_limit)} of at least ${String(pool.classLikeTokenCount)} distinct tokens; narrow pool_policy.contains or raise pool_policy.token_limit (CLI --pool-policy JSON) on a new call, no restart required`, + `class_like_tokens reports ${String(poolPolicy.token_limit)} of at least ${String(pool.classLikeTokenCount)} distinct tokens; narrow pool_policy.contains or raise pool_policy.token_limit (recorded in string_pool.limits) on a new call, no restart required`, ] : []), ], @@ -1421,13 +1438,13 @@ const projectStringPool = async ( classLikeTokenCount: number; printableRunCount: number; collectionCapped: boolean; - limitsReached: readonly Exclude[]; + limitsReached: readonly DartPoolBudget[]; }> => { const packages = new Set(); const darts = new Set(); const tokens = new Set(); let runCount = 0; - const limitsReached = new Set>(); + const limitsReached = new Set(); const COLLECTION_SLACK = 2; // Input bytes bound useful capacity before slack multiplication; large safe // integer requests never overflow the collection-budget arithmetic. diff --git a/src/go/GoBinaryProvider.ts b/src/go/GoBinaryProvider.ts index f6a7b3c37c..1ae9b33d18 100644 --- a/src/go/GoBinaryProvider.ts +++ b/src/go/GoBinaryProvider.ts @@ -1,3 +1,4 @@ +import type { AnalysisControlLimit } from "../domain/analysisSettings.js"; import { parseFailureAnalysisError } from "../domain/parseFailureAnalysisError.js"; import { jsonValueByteLength } from "../domain/jsonValueByteLength.js"; import { GO_BINARY_PROVIDER_IDENTITY } from "./GoBinaryProviderIdentity.js"; @@ -25,6 +26,7 @@ import { import { goBinarySchema, goAnalysisBudgets, + GO_ANALYSIS_BUDGET_DEFAULTS, GO_ANALYSIS_BUDGET_MAXIMA, type GoAnalysisBudgets, type GoBinary, @@ -46,9 +48,29 @@ const budgetRecovery = ( value: number, ): string => value < GO_ANALYSIS_BUDGET_MAXIMA[parameter] - ? `Increase ${parameter} above ${String(value)} (maximum ${String(GO_ANALYSIS_BUDGET_MAXIMA[parameter])}) on the next inspect_go_binary request (CLI --${parameter.replaceAll("_", "-")}); no restart is required.` + ? `Increase ${parameter} above ${String(value)} (maximum ${String(GO_ANALYSIS_BUDGET_MAXIMA[parameter])}) on the next inspect_go_binary request; no restart is required.` : `${parameter} is at its runtime representation maximum ${String(value)}; no larger value is supported. Preserve the complete selected artifact and report this boundary rather than repeating the unchanged request.`; +/** The per-call control of an exhausted budget, while a larger value is selectable. */ +const budgetLimit = ( + parameter: keyof GoAnalysisBudgets, + value: number, +): { readonly limit?: AnalysisControlLimit } => + value < GO_ANALYSIS_BUDGET_MAXIMA[parameter] + ? { + limit: { + control_kind: "parameter", + parameter, + effective_value: value, + unit: parameter.endsWith("_bytes") ? "bytes" : "count", + minimum: 1, + maximum: GO_ANALYSIS_BUDGET_MAXIMA[parameter], + default_value: GO_ANALYSIS_BUDGET_DEFAULTS[parameter], + applies_at: "next_call", + }, + } + : {}; + const failureForPrimary = ( facts: ArtifactFilePrimaryFacts, path: string, @@ -89,6 +111,7 @@ const failureForPrimary = ( : { retryable: false, remediationAction: `${cause.boundary === "search" ? "The Go build-info header-search allowance" : "The Go build-info string allowance"} is ${String(budgets[parameter])} bytes. ${budgetRecovery(parameter, budgets[parameter])} Other byte and report budgets are independent. Repeating the unchanged request cannot raise this allowance.`, + ...budgetLimit(parameter, budgets[parameter]), }), }, ); @@ -113,6 +136,7 @@ const failureForPrimary = ( cause, retryable: false, remediationAction: `${budgetRecovery("max_input_bytes", budgets.max_input_bytes)} Report, build-info and structural allowances remain independent. Preserve the complete artifact; do not truncate required bytes.`, + ...budgetLimit("max_input_bytes", budgets.max_input_bytes), }, ); if (cause.reason === "path") @@ -168,6 +192,7 @@ const outputLimit = (path: string, maximumBytes: number) => { retryable: false, remediationAction: `The Go complete-report allowance is ${String(maximumBytes)} bytes. ${budgetRecovery("max_report_bytes", maximumBytes)} This did not produce complete Evidence to page. MCP delivery limits remain independent.`, + ...budgetLimit("max_report_bytes", maximumBytes), }, ); diff --git a/src/native/AppleDispatchMetadata.ts b/src/native/AppleDispatchMetadata.ts index a5fbe15d80..4e4b1d04f1 100644 --- a/src/native/AppleDispatchMetadata.ts +++ b/src/native/AppleDispatchMetadata.ts @@ -341,7 +341,7 @@ const inputBudgetExceeded = ( observedBytes === null ? "The file grew while it was read. Retry once the file is stable." : observedBytes <= MAXIMUM_DISPATCH_METADATA_INPUT_BYTES - ? `Retry with max_input_bytes (CLI --max-input-bytes) of at least ${String(observedBytes)}, at most ${bytesWithUnits(MAXIMUM_DISPATCH_METADATA_INPUT_BYTES)}; REA holds that many bytes in memory for the read.` + ? `Retry with max_input_bytes of at least ${String(observedBytes)}, at most ${bytesWithUnits(MAXIMUM_DISPATCH_METADATA_INPUT_BYTES)}; REA holds that many bytes in memory for the read.` : `The file exceeds the largest selectable budget of ${bytesWithUnits(MAXIMUM_DISPATCH_METADATA_INPUT_BYTES)}; use a deep analysis provider for its Objective-C and Swift metadata.`; return new AnalysisResourceConstraintError( OPERATION, @@ -355,7 +355,26 @@ const inputBudgetExceeded = ( ? {} : { observed_input_bytes: observedBytes }), }, - { retryable: false, remediationAction }, + { + retryable: false, + remediationAction, + // Only a larger selectable budget admits the file. + ...(observedBytes !== null && + observedBytes <= MAXIMUM_DISPATCH_METADATA_INPUT_BYTES + ? { + limit: { + control_kind: "parameter", + parameter: "max_input_bytes", + effective_value: admission.maximum_bytes, + unit: "bytes", + minimum: 1, + maximum: MAXIMUM_DISPATCH_METADATA_INPUT_BYTES, + default_value: DEFAULT_DISPATCH_METADATA_INPUT_BYTES, + applies_at: "next_call", + } as const, + } + : {}), + }, ); }; diff --git a/src/native/elf/KernelModuleParser.ts b/src/native/elf/KernelModuleParser.ts index 7db853722e..70cf8577b5 100644 --- a/src/native/elf/KernelModuleParser.ts +++ b/src/native/elf/KernelModuleParser.ts @@ -5,17 +5,16 @@ import { allKeyed, firstKeyed, keyedBy } from "../../domain/keyedCollection.js"; import { elfObjectTypeName } from "../../domain/native/elfNotes.js"; import { KERNEL_MODULE_VERSION_ENTRY_BYTES, - DEFAULT_KERNEL_MODULE_KEY_BYTES, + kernelModuleModinfoLimit, MAX_KERNEL_MODULE_RAW_BYTES, MAX_KERNEL_MODULE_SECTION_NAME_BYTES, - DEFAULT_KERNEL_MODULE_VALUE_BYTES, - MAX_INSPECT_KERNEL_MODULE_FILE_BYTES, MODULE_SIGNATURE_INFO_BYTES, MODULE_SIGNATURE_MAGIC, MODULE_SIGNATURE_PKCS7_ID_TYPE, type KernelModule, type InspectKernelModuleInput, } from "../../domain/native/kernelModule.js"; +import type { AnalysisParameterLimit } from "../../domain/analysisSettings.js"; import type { ImageSection, BinaryContainer, @@ -247,24 +246,17 @@ const parseModinfo = ( if (!terminated) break; at = end + 1; } - for (const [field, selected, required, defaultBytes] of [ - [ - "key", - input.max_modinfo_key_bytes, - largestKeyBytes, - DEFAULT_KERNEL_MODULE_KEY_BYTES, - ], - [ - "value", - input.max_modinfo_value_bytes, - largestValueBytes, - DEFAULT_KERNEL_MODULE_VALUE_BYTES, - ], + const omissionLimits: AnalysisParameterLimit[] = []; + for (const [field, selected, required] of [ + ["key", input.max_modinfo_key_bytes, largestKeyBytes], + ["value", input.max_modinfo_value_bytes, largestValueBytes], ] as const) { - if (required > selected) + if (required > selected) { + omissionLimits.push(kernelModuleModinfoLimit(field, selected)); use.limitations.push( - `.modinfo ${field} text exceeds max_modinfo_${field}_bytes=${String(selected)} bytes (request budget; default ${String(defaultBytes)}, minimum 1, maximum ${String(MAX_INSPECT_KERNEL_MODULE_FILE_BYTES)}). Omitted fields keep their source range and digest; omission does not establish malformed syntax. Retry inspect_kernel_module with max_modinfo_${field}_bytes at least ${String(required)}, or --max-modinfo-${field}-bytes on the CLI. Applies on the next call without a REA restart; input, entry and raw-hex budgets do not change.`, + `.modinfo ${field} text exceeds max_modinfo_${field}_bytes=${String(selected)} bytes. Omitted fields keep their source range and digest; omission does not establish malformed syntax. Retry inspect_kernel_module with max_modinfo_${field}_bytes at least ${String(required)}; modinfo.omission_limits records the control. Applies on the next call without a REA restart; input, entry and raw-hex budgets do not change.`, ); + } } return { status: "present", @@ -272,6 +264,7 @@ const parseModinfo = ( sha256: sha256(stored), entries, reason: null, + ...(omissionLimits.length === 0 ? {} : { omission_limits: omissionLimits }), }; }; diff --git a/src/native/pwndbg/PwndbgCoreContext.ts b/src/native/pwndbg/PwndbgCoreContext.ts index c7c94fbccc..86823b1c02 100644 --- a/src/native/pwndbg/PwndbgCoreContext.ts +++ b/src/native/pwndbg/PwndbgCoreContext.ts @@ -37,7 +37,7 @@ import { analysisErrorWithCleanupDependencies } from "../../domain/analysisError import { ProviderCleanupError } from "../../domain/providerCleanupError.js"; import { pwntoolsFailureDialect, - pwntoolsBudgetRecovery, + pwntoolsReplyOutputLimit, } from "../pwntools/PwntoolsFailures.js"; import { resolvePwntoolsLimits, @@ -289,7 +289,7 @@ export const inspectPwndbgCore = async ({ { cause, ...(cause instanceof ArtifactReaderFailure && cause.reason === "limit" - ? { remediationAction: pwntoolsBudgetRecovery(producerLimits) } + ? pwntoolsReplyOutputLimit(producerLimits) : {}), ...(cause instanceof ArtifactReaderFailure ? { cleanup: cause.cleanup } @@ -319,7 +319,7 @@ export const inspectPwndbgCore = async ({ new AnalysisOutputError(OPERATION, reply.message, { capturedOutput: recordedCrashStageOutput(diagnostics, output), ...(reply.reason === "output-limit" - ? { remediationAction: pwntoolsBudgetRecovery(producerLimits) } + ? pwntoolsReplyOutputLimit(producerLimits) : {}), }), finalization, diff --git a/src/native/pwntools/PwntoolsDecoder.ts b/src/native/pwntools/PwntoolsDecoder.ts index 668a7cb443..3513eb6678 100644 --- a/src/native/pwntools/PwntoolsDecoder.ts +++ b/src/native/pwntools/PwntoolsDecoder.ts @@ -24,6 +24,7 @@ import { pwntoolsFailureDialect, pwntoolsUnavailable, pwntoolsBudgetRecovery, + pwntoolsReplyOutputLimit, } from "./PwntoolsFailures.js"; import { randomUUID } from "node:crypto"; import { access, stat, writeFile } from "node:fs/promises"; @@ -550,9 +551,7 @@ export class PwntoolsDecoder< capturedOutput, ...(cause instanceof ArtifactReaderFailure && cause.reason === "limit" - ? { - remediationAction: `Increase producer_limits.output_bytes above ${String(producerLimits.output_bytes)} bytes on the next call (CLI --producer-limits JSON); no restart is required. File, worker memory and transport limits remain independent.`, - } + ? pwntoolsReplyOutputLimit(producerLimits) : {}), ...(cause instanceof ArtifactReaderFailure ? { cleanup: cause.cleanup } @@ -607,7 +606,7 @@ export class PwntoolsDecoder< if (reply.reason === "output-limit") throw new AnalysisOutputError(OPERATION, reply.message, { capturedOutput, - remediationAction: `Increase producer_limits.output_bytes above ${String(producerLimits.output_bytes)} bytes on the next call (CLI --producer-limits JSON); no restart is required. File output follows the selected output allowance unless file_bytes is explicit. Tighter inherited limits and transport remain independent.`, + ...pwntoolsReplyOutputLimit(producerLimits), }); throw new ProviderAdapterError(this.identity.id, OPERATION, { diagnostics: { diff --git a/src/native/pwntools/PwntoolsFailures.test.ts b/src/native/pwntools/PwntoolsFailures.test.ts index 3f3502cbd4..00cecf83dd 100644 --- a/src/native/pwntools/PwntoolsFailures.test.ts +++ b/src/native/pwntools/PwntoolsFailures.test.ts @@ -165,6 +165,84 @@ it("names the reported file-size allowance instead of address space", () => { expect(projected.remediation.action).not.toContain("address_space_bytes"); expect(projected.remediation.action).not.toContain("1111"); expect(projected.remediation.action).not.toContain("3221225472"); + expect(projected.remediation.action).not.toContain("--"); + expect(projected.details?.limit).toMatchObject({ + control_kind: "parameter", + parameter: "producer_limits.file_bytes", + effective_value: 67108864, + }); +}); + +it("reports the selected output allowance as the omitted file-size default", () => { + const outputBytes = 128 * 1024 * 1024; + const projected = projectAnalysisError( + pwntoolsDecoderFailure( + new OwnedCommandFailure("process", "sigxfsz", { + stdout: { text: "", bytes: 0, observedBytes: 0 }, + stderr: { text: "", bytes: 0, observedBytes: 0 }, + exitCode: null, + signal: "SIGXFSZ", + }), + "decoder", + "/selected", + "/python", + {}, + { + operation: "inspect_binary_layout", + providerId: "pwntools", + producerLimits: resolvePwntoolsLimits({ output_bytes: outputBytes }), + }, + ), + ); + expect(projected.details?.limit).toMatchObject({ + parameter: "producer_limits.file_bytes", + effective_value: outputBytes, + default_value: outputBytes, + }); +}); + +it("binds diagnostic_bytes as the only control of the command output budget", () => { + const projected = projectAnalysisError( + pwntoolsDecoderFailure( + new OwnedCommandFailure( + "output-limit", + "Command diagnostic output exceeded its complete-output budget.", + { + stdout: { text: "x".repeat(64), bytes: 64, observedBytes: 65 }, + stderr: { text: "", bytes: 0, observedBytes: 0 }, + exitCode: 0, + signal: null, + outputIncomplete: true, + }, + ), + "decoder", + "/selected", + "/python", + {}, + { + operation: "inspect_binary_layout", + providerId: "pwntools", + producerLimits: resolvePwntoolsLimits({ diagnostic_bytes: 64 }), + }, + ), + ); + expect(projected).toMatchObject({ + code: "resource_constraint", + details: { + limit: { + control_kind: "parameter", + parameter: "producer_limits.diagnostic_bytes", + effective_value: 64, + default_value: 1048576, + }, + }, + }); + // output_bytes bounds the reply file, not this budget. + expect(projected.message).not.toContain("output_bytes"); + expect(projected.remediation.action).toContain( + "Increase producer_limits.diagnostic_bytes above 64", + ); + expect(projected.remediation.action).not.toContain("--"); }); it("names the file-size cap when SIGXFSZ has no reported limit", () => { @@ -189,6 +267,9 @@ it("names the file-size cap when SIGXFSZ has no reported limit", () => { expect(projected.remediation.action).toContain("tighter inherited limit"); expect(projected.remediation.action).not.toContain("address_space_bytes"); expect(projected.remediation.action).not.toContain("3221225472"); + expect(projected.details?.limit).toMatchObject({ + parameter: "producer_limits.file_bytes", + }); }); it("names memory in the marker recovery for an allocation failure", () => { diff --git a/src/native/pwntools/PwntoolsFailures.ts b/src/native/pwntools/PwntoolsFailures.ts index b4b8b524e8..8ab5928117 100644 --- a/src/native/pwntools/PwntoolsFailures.ts +++ b/src/native/pwntools/PwntoolsFailures.ts @@ -1,4 +1,5 @@ import { capturedProviderOutput } from "../../process/capturedProviderOutput.js"; +import { producerLimitControl } from "../../domain/producerResourceLimits.js"; import { analysisSettingLimit } from "../../domain/analysisSettingDefinitions.js"; import { PWNTOOLS_LIMITS, @@ -6,13 +7,13 @@ import { type PwntoolsProducerLimits, } from "../../domain/native/pwntoolsResourceLimits.js"; import type { AnalysisCapturedOutput } from "../../domain/analysisErrorBase.js"; +import type { AnalysisControlLimit } from "../../domain/analysisSettings.js"; import type { ProviderProcessSnapshot } from "../../process/ProviderProcess.js"; import { AnalysisInputError, AnalysisResourceConstraintError, } from "../../domain/analysisErrorCore.js"; import { ProviderAdapterError } from "../../domain/providerAdapterError.js"; -import { ProviderCleanupError } from "../../domain/providerCleanupError.js"; import { ProviderSelectionError } from "../../domain/providerSelectionError.js"; import type { ProviderOutcomeContext } from "../../process/classifyProviderOutcome.js"; import { OwnedCommandFailure } from "../../process/OwnedCommand.js"; @@ -64,7 +65,7 @@ const pwntoolsInputLimitRecovery = ( const shared = "CPU, memory, output and transport allowances remain independent."; if (source === "request") - return `producer_limits.input_bytes is ${effective} bytes for this call. Raise it on the next call (CLI --producer-limits JSON). ${shared}`; + return `producer_limits.input_bytes is ${effective} bytes for this call. Raise it on the next call. ${shared}`; if (source === "runtime") return `pwntools.max_input_bytes is ${effective} bytes (source runtime) and can be changed with update_analysis_settings. The launch seed is REA_PWNTOOLS_MAX_INPUT_BYTES. producer_limits.input_bytes overrides that ceiling on the next call. ${shared}`; if (source === "setting") @@ -76,7 +77,25 @@ const pwntoolsInputLimitRecovery = ( export const pwntoolsBudgetRecovery = ( limits: PwntoolsProducerLimits = resolvePwntoolsLimits(), ): string => - `Selected producer_limits: cpu_seconds=${String(limits.cpu_seconds)} seconds, output_bytes=${String(limits.output_bytes)}, diagnostic_bytes=${String(limits.diagnostic_bytes)}, address_space_bytes=${String(limits.address_space_bytes)}, file_bytes=${String(limits.file_bytes)}, input_bytes=${String(limits.input_bytes)} bytes. Increase the exhausted producer_limits field on the next call (CLI --producer-limits JSON); no REA restart is required. Tighter inherited OS limits remain enforced and are not raised by this request. pwntools_timeout_ms changes only the wall deadline.`; + `Selected producer_limits: cpu_seconds=${String(limits.cpu_seconds)} seconds, output_bytes=${String(limits.output_bytes)}, diagnostic_bytes=${String(limits.diagnostic_bytes)}, address_space_bytes=${String(limits.address_space_bytes)}, file_bytes=${String(limits.file_bytes)}, input_bytes=${String(limits.input_bytes)} bytes. Increase the exhausted producer_limits field on the next call; no REA restart is required. Tighter inherited OS limits remain enforced and are not raised by this request. pwntools_timeout_ms changes only the wall deadline.`; + +/** + * Recovery for a bridge reply larger than `producer_limits.output_bytes`: the + * reply file's own budget, shared by the decoder and the core-only debugger. + */ +export const pwntoolsReplyOutputLimit = ( + limits: PwntoolsProducerLimits, +): { + readonly remediationAction: string; + readonly limit: AnalysisControlLimit; +} => ({ + remediationAction: `Increase producer_limits.output_bytes above ${String(limits.output_bytes)} bytes on the next call; no restart is required. File output follows the selected output allowance unless file_bytes is explicit. Diagnostic output, worker memory, tighter inherited limits and transport remain independent.`, + limit: producerLimitControl( + "output_bytes", + limits.output_bytes, + PWNTOOLS_LIMITS.output_bytes, + ), +}); /** Name the file-size cap and any reported effective limit, not address space. */ const fileSizeAllowance = ( @@ -85,7 +104,7 @@ const fileSizeAllowance = ( ): string => { const cap = String(selectedBytes); const inherited = - "A tighter inherited limit is retained. Increase producer_limits.file_bytes on the next call (CLI --producer-limits JSON); no restart is required. pwntools_timeout_ms does not raise the file-size allowance."; + "A tighter inherited limit is retained. Increase producer_limits.file_bytes on the next call; no restart is required. pwntools_timeout_ms does not raise the file-size allowance."; return reportedBytes === undefined ? `The file-size cap is ${cap} bytes (producer_limits.file_bytes). The effective file_size_bytes limit was not reported. ${inherited}` : `The effective file-size allowance is ${String(reportedBytes)} bytes (file_size_bytes). The file-size cap is ${cap} bytes (producer_limits.file_bytes). ${inherited}`; @@ -129,26 +148,6 @@ export const pwntoolsFailureDialect = ( providerId: context.providerId, operation: context.operation, command: () => pwntoolsCommandContext(state, limits), - commandCleanup: (failure) => { - const output = combinedPwntoolsOutput(failure.snapshot, context); - return new ProviderCleanupError( - context.providerId, - failure.resources, - { - reason: failure.cleanupFailure, - ...(output === undefined ? {} : { captured_output: { ...output } }), - previous_error: { - failure_kind: failure.reason, - message: failure.message, - exit_code: failure.snapshot?.exitCode ?? null, - signal: failure.snapshot?.signal ?? null, - stdout: failure.snapshot?.stdout.text ?? null, - stderr: failure.snapshot?.stderr.text ?? null, - }, - }, - { operation: context.operation, cause: failure }, - ); - }, // Only the configuration phase checks the selected Python by path. recognise: (cause) => phase === "configuration" && cause instanceof Error && "code" in cause @@ -224,6 +223,12 @@ const pwntoolsCommandContext = ( limits.file_bytes, ); const fileSizeRecovery = `Review the reported worker file-size limits and write failure. ${allowance} Repeating the unchanged request fails the same way.`; + // An omitted file_bytes follows this call's selected output allowance. + const fileSizeLimit = producerLimitControl( + "file_bytes", + limits.file_bytes, + limits.output_bytes, + ); const timeoutMs = context.timeoutMs ?? PWNTOOLS_LIMITS.command_timeout_ms; const deadline = nativeDeadlineRecovery({ timeoutMs, @@ -257,12 +262,21 @@ const pwntoolsCommandContext = ( remediationAction: deadline.remediationAction, limit: deadline.limit, }, + // The command retains stdout and stderr under one aggregate + // diagnostic_bytes budget; output_bytes bounds the reply file, which + // reports its own refusal. Exceeding the command budget therefore names + // diagnostic_bytes whichever stream overflowed it. outputLimit: { - limits: { - output_bytes: limits.output_bytes, - diagnostic_bytes: limits.diagnostic_bytes, + reason: `Owned pwntools stdout and stderr exceeded the selected ${String(limits.diagnostic_bytes)}-byte producer_limits.diagnostic_bytes budget.`, + limits: { diagnostic_bytes: limits.diagnostic_bytes }, + recovery: { + remediationAction: `Increase producer_limits.diagnostic_bytes above ${String(limits.diagnostic_bytes)} bytes on the next call; no restart is required. It bounds retained process stdout and stderr only; output_bytes, file and transport limits remain independent.`, }, - recovery: { remediationAction: budgetRecovery }, + limit: producerLimitControl( + "diagnostic_bytes", + limits.diagnostic_bytes, + PWNTOOLS_LIMITS.diagnostic_bytes, + ), }, resourceSignal: (signal) => signal === "SIGXFSZ" @@ -270,14 +284,20 @@ const pwntoolsCommandContext = ( limits: reportedLimits, detail: `${reportFailure} ${allowance}`.trim(), recovery: { remediationAction: fileSizeRecovery }, + limit: fileSizeLimit, } : { limits: reportedLimits, detail: `${reportFailure} Selected producer_limits.cpu_seconds is ${String(limits.cpu_seconds)} seconds; inherited tighter limits remain enforced.`.trim(), recovery: { - remediationAction: `Review the reported worker CPU limit and observed signal; the signal alone does not establish exhaustion. Increase producer_limits.cpu_seconds above ${String(limits.cpu_seconds)} on the next call (CLI --producer-limits JSON) when that policy was limiting. No restart is required; a tighter inherited limit remains enforced. pwntools_timeout_ms does not raise CPU admission.`, + remediationAction: `Review the reported worker CPU limit and observed signal; the signal alone does not establish exhaustion. Increase producer_limits.cpu_seconds above ${String(limits.cpu_seconds)} on the next call when that policy was limiting. No restart is required; a tighter inherited limit remains enforced. pwntools_timeout_ms does not raise CPU admission.`, }, + limit: producerLimitControl( + "cpu_seconds", + limits.cpu_seconds, + PWNTOOLS_LIMITS.cpu_seconds, + ), }, dialect: (outcome, details) => { if (outcome.kind === "launch-refused") @@ -304,7 +324,11 @@ const pwntoolsCommandContext = ( "file-size", `The owned Python bridge reported EFBIG while writing a file; the exact write failure cause is unknown.${reportFailure} ${allowance}`, reportedLimits, - { ...details, remediationAction: fileSizeRecovery }, + { + ...details, + remediationAction: fileSizeRecovery, + limit: fileSizeLimit, + }, ); if (marked === "memory" && reservedExit === PWNTOOLS_MEMORY_FAILURE_EXIT) return new AnalysisResourceConstraintError( diff --git a/src/process/classifyProviderOutcome.ts b/src/process/classifyProviderOutcome.ts index 364a45d735..77bb005264 100644 --- a/src/process/classifyProviderOutcome.ts +++ b/src/process/classifyProviderOutcome.ts @@ -63,6 +63,8 @@ export interface ProviderOutcomeContext { readonly reason?: string; readonly limits: ReportedLimits; readonly recovery: ResourceConstraintRecovery; + /** The per-call control that raises this allowance, when the caller selects it. */ + readonly limit?: AnalysisLimit; }; /** The enforced process-tree memory limit, when one was requested. */ readonly memoryLimitBytes?: number | undefined; @@ -70,6 +72,8 @@ export interface ProviderOutcomeContext { readonly resourceSignal?: (signal: "SIGXCPU" | "SIGXFSZ") => { readonly limits: ReportedLimits; readonly recovery: ResourceConstraintRecovery; + /** The per-call control that raises this allowance, when the caller selects it. */ + readonly limit?: AnalysisLimit; /** Provider facts appended to the shared report, such as the selected allowance. */ readonly detail?: string; }; @@ -135,7 +139,13 @@ export const classifyProviderOutcome = ( "memory", context.outputLimit.reason ?? outcome.message, context.outputLimit.limits, - { ...details, ...context.outputLimit.recovery }, + { + ...details, + ...context.outputLimit.recovery, + ...(context.outputLimit.limit === undefined + ? {} + : { limit: context.outputLimit.limit }), + }, ); case "memory-limit": return new AnalysisResourceConstraintError( @@ -152,7 +162,11 @@ export const classifyProviderOutcome = ( outcome.signal === "SIGXFSZ" ? "file-size" : "cpu", `Producer terminated with ${outcome.signal}; the signal's exact cause is not independently established.${reported?.detail === undefined ? "" : ` ${reported.detail}`}`, reported?.limits ?? null, - { ...details, ...reported?.recovery }, + { + ...details, + ...reported?.recovery, + ...(reported?.limit === undefined ? {} : { limit: reported.limit }), + }, ); } case "runtime-exhausted": { diff --git a/src/rust/RustBinaryImage.ts b/src/rust/RustBinaryImage.ts index 7fee4046c6..214847a38f 100644 --- a/src/rust/RustBinaryImage.ts +++ b/src/rust/RustBinaryImage.ts @@ -10,7 +10,10 @@ import type { RustAuditableMetadata, RustBinary, } from "../domain/rust/rustBinary.js"; -import { DEFAULT_RUSTC_HASH_LIMIT } from "../domain/rust/rustBinary.js"; +import { + DEFAULT_RUSTC_HASH_LIMIT, + rustcPartialCoverage, +} from "../domain/rust/rustBinary.js"; import { RUST_PRODUCER_DEFAULTS } from "../domain/rust/rustResourceLimits.js"; import { readAuditableSection, @@ -165,14 +168,12 @@ const rustcCommit = ( hashes: retention.hashes, ...(retention.reason !== undefined ? { - coverage: { - status: "partial" as const, - reason: retention.reason, - effective_limit: - retention.reason === "report_bytes" - ? maxOutputBytes - : maxHashes, - }, + coverage: rustcPartialCoverage( + retention.reason, + retention.reason === "report_bytes" + ? maxOutputBytes + : maxHashes, + ), } : {}), }; diff --git a/src/rust/RustBinaryProvider.ts b/src/rust/RustBinaryProvider.ts index bdeb6c1c1f..dfc9cf6e4c 100644 --- a/src/rust/RustBinaryProvider.ts +++ b/src/rust/RustBinaryProvider.ts @@ -1,3 +1,4 @@ +import { producerLimitControl } from "../domain/producerResourceLimits.js"; import { RUST_BINARY_PROVIDER_IDENTITY } from "./RustBinaryProviderIdentity.js"; import { projectSelectedArtifactFileFailure, @@ -26,6 +27,7 @@ import { import { RUST_AUDITABLE_FORMAT_VERSIONS, rustBinarySchema, + rustcPartialCoverage, type InspectRustBinaryInput, type RustBinary, } from "../domain/rust/rustBinary.js"; @@ -41,6 +43,7 @@ import { RustAuditableResourceFailure } from "./RustAuditableReader.js"; import { parseFailureAnalysisError } from "../domain/parseFailureAnalysisError.js"; import { + RUST_PRODUCER_DEFAULTS, resolveRustProducerLimits, rustProducerLimitsSchema, type RustProducerLimits, @@ -133,7 +136,11 @@ export class RustBinaryProvider implements RustBinaryPort { ...selected.limitations, ], }; - retainCompilerPathsWithinReport(report, limits.output_bytes); + retainCompilerPathsWithinReport( + report, + limits.output_bytes, + rustcLimitation(image.rustc_commit), + ); if ( Buffer.byteLength(JSON.stringify(report), "utf8") > limits.output_bytes @@ -188,7 +195,12 @@ const outputLimit = (path: string, maxOutputBytes: number) => { maximum_output_bytes: maxOutputBytes }, { retryable: false, - remediationAction: `Increase producer_limits.output_bytes above ${String(maxOutputBytes)} bytes on the next inspect_rust_binary call (CLI --producer-limits JSON); no restart is required. Input, dependency parser and transport limits remain independent. Repeating the unchanged request does not raise admission.`, + remediationAction: `Increase producer_limits.output_bytes above ${String(maxOutputBytes)} bytes on the next inspect_rust_binary call; no restart is required. Input, dependency parser and transport limits remain independent. Repeating the unchanged request does not raise admission.`, + limit: producerLimitControl( + "output_bytes", + maxOutputBytes, + RUST_PRODUCER_DEFAULTS.output_bytes, + ), }, ); @@ -229,7 +241,6 @@ const limitationsFor = ( "Dependency indices contain a cycle. The cycle is reported and was not traversed.", ] : []), - ...rustcLimitation(image.rustc_commit), ]; const unknownFormatLimitation = ( @@ -255,11 +266,11 @@ const rustcLimitation = ( ]; if (commit.coverage?.reason === "report_bytes") return [ - "Compiler-path retention exhausted the complete-report byte allowance; retained hashes are a prefix and compiler coverage is partial. Dependency observations are independent. Increase producer_limits.output_bytes on the next call (CLI --producer-limits JSON) to raise report admission; no restart is required. Increasing max_rustc_hashes alone does not raise it.", + "Compiler-path retention exhausted the complete-report byte allowance; retained hashes are a prefix and compiler coverage is partial. Dependency observations are independent. Raise the control in rustc_commit.coverage.limit on the next call to raise report admission; no restart is required. Increasing max_rustc_hashes alone does not raise it.", ]; if (commit.coverage?.status === "partial") return [ - `Compiler-path retention reached max_rustc_hashes=${String(commit.coverage.effective_limit)}; the listed hashes are a prefix and compiler coverage is partial. Increase max_rustc_hashes on the next inspect_rust_binary call (CLI --max-rustc-hashes) to retain more paths; no restart is required. Dependency observations are independent. The complete-report byte allowance still applies.`, + `Compiler-path retention reached max_rustc_hashes=${String(commit.coverage.effective_limit)}; the listed hashes are a prefix and compiler coverage is partial. Raise the control in rustc_commit.coverage.limit on the next call to retain more paths; no restart is required. Dependency observations are independent. The complete-report byte allowance still applies.`, ]; if (commit.hashes.length === 1) return [ @@ -270,19 +281,30 @@ const rustcLimitation = ( ]; }; -/** Optional inferred paths never displace independently observed dependency facts. */ +/** + * Optional inferred paths never displace independently observed dependency + * facts. The compiler guidance describes the retained result: the reader's + * guidance when every retained path fits, otherwise the trimming guidance, + * which names its control directly because no compiler record may survive. + */ const retainCompilerPathsWithinReport = ( report: RustBinary, maxOutputBytes: number, + compilerGuidance: readonly string[], ): void => { const commit = report.rustc_commit; + const withGuidance = [...report.limitations, ...compilerGuidance]; if ( commit === null || - Buffer.byteLength(JSON.stringify(report)) <= maxOutputBytes - ) + Buffer.byteLength( + JSON.stringify({ ...report, limitations: withGuidance }), + ) <= maxOutputBytes + ) { + report.limitations = withGuidance; return; + } const limitation = - "Compiler paths were omitted to preserve dependency facts within the complete-report byte allowance; compiler-path coverage is partial. Increase producer_limits.output_bytes on the next call (CLI --producer-limits JSON); no restart is required. Increasing max_rustc_hashes alone does not raise this allowance."; + "Compiler paths were omitted to preserve dependency facts within the complete-report byte allowance; compiler-path coverage is partial. Increase producer_limits.output_bytes on the next call; no restart is required. Increasing max_rustc_hashes alone does not raise this allowance."; const baseline = { ...report, rustc_commit: null, @@ -291,11 +313,7 @@ const retainCompilerPathsWithinReport = ( const empty = { ...commit, hashes: [], - coverage: { - status: "partial" as const, - reason: "report_bytes" as const, - effective_limit: maxOutputBytes, - }, + coverage: rustcPartialCoverage("report_bytes", maxOutputBytes), }; const available = maxOutputBytes - @@ -309,8 +327,16 @@ const retainCompilerPathsWithinReport = ( retainedBytes += bytes; count++; } - report.rustc_commit = - count === 0 ? null : { ...empty, hashes: commit.hashes.slice(0, count) }; + if (count === 0) { + // The control stays recorded although no compiler record survives. + report.rustc_commit = null; + if (empty.coverage.limit !== undefined) + report.rustc_commit_omission = { + reason: "report_bytes", + limit: empty.coverage.limit, + }; + } else + report.rustc_commit = { ...empty, hashes: commit.hashes.slice(0, count) }; report.limitations = baseline.limitations; }; @@ -333,7 +359,12 @@ const failureForPrimary = ( ...(cause.constraint.resource === "transport" ? { retryable: false, - remediationAction: `Increase producer_limits.output_bytes above ${String(limits.output_bytes)} bytes on the next call (CLI --producer-limits JSON); no restart is required. Compressed/inflated dependency parser and transport limits remain independent.`, + remediationAction: `Increase producer_limits.output_bytes above ${String(limits.output_bytes)} bytes on the next call; no restart is required. Compressed/inflated dependency parser and transport limits remain independent.`, + limit: producerLimitControl( + "output_bytes", + limits.output_bytes, + RUST_PRODUCER_DEFAULTS.output_bytes, + ), } : fixedAllowanceOptions( "This Rust dependency parser allowance", @@ -416,7 +447,12 @@ const artifactReaderFailure = ( { cause, retryable: false, - remediationAction: `Increase producer_limits.input_bytes above ${String(limits.input_bytes)} bytes on the next inspect_rust_binary call (CLI --producer-limits JSON); no restart is required. Select the same complete artifact, without truncating its bytes. Report, dependency parser and host memory limits remain independent.`, + remediationAction: `Increase producer_limits.input_bytes above ${String(limits.input_bytes)} bytes on the next inspect_rust_binary call; no restart is required. Select the same complete artifact, without truncating its bytes. Report, dependency parser and host memory limits remain independent.`, + limit: producerLimitControl( + "input_bytes", + limits.input_bytes, + RUST_PRODUCER_DEFAULTS.input_bytes, + ), }, ); if (cause.reason === "path") diff --git a/src/sqlite/SqliteDatabaseFailures.ts b/src/sqlite/SqliteDatabaseFailures.ts index 28ef9cb491..aae828ac4f 100644 --- a/src/sqlite/SqliteDatabaseFailures.ts +++ b/src/sqlite/SqliteDatabaseFailures.ts @@ -1,5 +1,8 @@ +import { + deadlineParameterLimit, + MAX_NODE_TIMER_DELAY_MS, +} from "../domain/analysisResourceLimits.js"; import { capturedProviderOutput } from "../process/capturedProviderOutput.js"; -import { MAX_NODE_TIMER_DELAY_MS } from "../domain/analysisResourceLimits.js"; import { ArtifactReaderFailure, stableArtifactInputFailure, @@ -212,9 +215,14 @@ const ownedCommandFailure = ( ? 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)}), or use rea inspect-sqlite-database --worker-timeout-ms on the CLI.` + ? `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.`, }) diff --git a/src/wasm/WabtArtifactProvider.test.ts b/src/wasm/WabtArtifactProvider.test.ts index ca23603990..991602da42 100644 --- a/src/wasm/WabtArtifactProvider.test.ts +++ b/src/wasm/WabtArtifactProvider.test.ts @@ -1917,13 +1917,21 @@ it("bounds the excerpt when cleanup also fails after the output budget", () => { ).toMatchObject({ code: "cleanup_incomplete", details: { + // The typed output refusal stays the primary: its control is the + // composite's limit, and its bounded excerpt is retained once. + limit: { + control_kind: "parameter", + parameter: "max_output_bytes", + effective_value: WASM_RESOURCE_DEFAULTS.outputBytes, + }, + captured_output: { stdout: "(module", stderr: "w".repeat(4096) }, diagnostics: { - previous_error: { - failure_kind: "output-limit", - message: `WABT output exceeded the ${String(WASM_RESOURCE_DEFAULTS.outputBytes)}-byte output budget`, - max_output_bytes: WASM_RESOURCE_DEFAULTS.outputBytes, + primary_error: { + code: "resource_constraint", + message: expect.stringContaining( + `WABT output exceeded the ${String(WASM_RESOURCE_DEFAULTS.outputBytes)}-byte output budget`, + ), }, - captured_output: { stdout: "(module", stderr: "w".repeat(4096) }, }, }, }); diff --git a/src/wasm/WabtFailures.test.ts b/src/wasm/WabtFailures.test.ts index 5badb6498d..de216e2a3b 100644 --- a/src/wasm/WabtFailures.test.ts +++ b/src/wasm/WabtFailures.test.ts @@ -46,26 +46,26 @@ it.each(["configuration", "producer"] as const)( const failure = wabtFailure(cause, phase, "/module.wasm", { commandTimeoutMs: 1234, }); - expect(failure.cause).toBe(cause); + // The typed timeout stays the cleanup primary, so its control is the + // composite's own limit. + expect(failure.cleanupPrimary?.cause).toBe(cause); const projected = projectAnalysisError(failure); expect(projected).toMatchObject({ code: "cleanup_incomplete", retryable: false, details: { resources: ["pid:owned-fixture"], + limit: { + setting: "wasm.command_timeout_ms", + effective_value: 1234, + parameter: "command_timeout_ms", + update_mode: "runtime", + pending_restart: false, + }, diagnostics: { - previous_error: { + primary_error: { code: "provider_timeout", - details: { - timeout_ms: 1234, - limit: { - setting: "wasm.command_timeout_ms", - effective_value: 1234, - update_mode: "runtime", - pending_restart: false, - }, - }, - recovery: { kind: "inspect_timeout_state", timeout_ms: 1234 }, + details: { timeout_ms: 1234 }, }, }, }, @@ -183,10 +183,17 @@ it.each([ const original = wabtFailure(cause, "configuration", "/selected.wasm"); expect(failure._tag).toBe(original._tag); expect(failure.cleanupIncomplete).toBe(original.cleanupIncomplete); - expect(failure.cause).toBe(original.cause); + // A cleanup failure composes around the typed primary that owns the cause. + const primary = (error: typeof failure) => error.cleanupPrimary ?? error; + expect(primary(failure).cause).toBe(primary(original).cause); expect(projectAnalysisError(failure)).toMatchObject({ code, - details: { diagnostics: probe }, + details: { + diagnostics: + cleanup === null + ? probe + : { primary_error: { details: { diagnostics: probe } } }, + }, }); }, ); @@ -250,6 +257,13 @@ it.each([false, true])( if (!cleanup) { expect(projected.remediation.action).toContain("max_input_bytes"); expect(projected.remediation.action).not.toContain("evidence reply"); + expect(projected.remediation.action).not.toContain("--"); + expect(projected.details?.limit).toMatchObject({ + control_kind: "parameter", + parameter: "max_input_bytes", + effective_value: WASM_RESOURCE_DEFAULTS.inputBytes, + default_value: WASM_RESOURCE_DEFAULTS.inputBytes, + }); } expect( wabtFailure(cause, "artifact", "selected.wasm").cleanupResources, diff --git a/src/wasm/WabtFailures.ts b/src/wasm/WabtFailures.ts index 27f28debd3..f6c5babf8c 100644 --- a/src/wasm/WabtFailures.ts +++ b/src/wasm/WabtFailures.ts @@ -8,15 +8,12 @@ import { utf8HeadExcerpt } from "../domain/utf8HeadExcerpt.js"; import type { ProviderProcessSnapshot } from "../process/ProviderProcess.js"; import { capturedProviderOutput } from "../process/capturedProviderOutput.js"; import type { AnalysisCapturedOutput } from "../domain/analysisErrorBase.js"; -import { projectAnalysisError } from "../domain/analysisErrorProjection.js"; import { AnalysisInputError, AnalysisOutputError, AnalysisResourceConstraintError, - AnalysisTimeoutError, AnalysisCapabilityUnavailableError, } from "../domain/analysisErrorCore.js"; -import { ProviderCleanupError } from "../domain/providerCleanupError.js"; import type { ProviderOutcome } from "../process/ProviderOutcome.js"; import type { ProviderFailureDialect } from "../providers/classifyProviderFailure.js"; import { @@ -24,6 +21,7 @@ import { runtimeControlCapabilityError, } from "../domain/runtimeControlUnavailableError.js"; import { WabtAdmissionError } from "./WabtAdmissionError.js"; +import type { AnalysisControlLimit } from "../domain/analysisSettings.js"; import { DEFAULT_WASM_COMMAND_TIMEOUT_MS, WABT_VERSION, @@ -36,13 +34,44 @@ import { errorMessage } from "../kernel/errorMessage.js"; const OUTPUT_LIMIT_EXCERPT_BYTES = 4096; const OPERATION = "inspect_wasm_artifact"; +const WASM_BYTE_BUDGETS = { + max_input_bytes: "inputBytes", + max_output_bytes: "outputBytes", + max_tool_bytes: "toolBytes", +} as const; +type WasmByteBudget = keyof typeof WASM_BYTE_BUDGETS; + /** Recovery names the exhausted per-call byte owner, independently of deadlines. */ const byteBudgetRecovery = ( - parameter: "max_input_bytes" | "max_output_bytes" | "max_tool_bytes", + parameter: WasmByteBudget, value: number, - maximum: number, -): string => - `${parameter} is ${String(value)} bytes. ${value < maximum ? `Raise ${parameter} above ${String(value)} bytes (positive integer, maximum ${String(maximum)}), or use --${parameter.replaceAll("_", "-")} on the CLI, then retry the same complete input after cleanup settles.` : `This is already the runtime representation maximum of ${String(maximum)} bytes; use a suitable smaller complete input or report this blocker.`} The new value applies to the next inspection without restarting REA. command_timeout_ms, other byte budgets and client delivery settings do not raise this allowance. Do not truncate required bytes. Repeating the unchanged request fails the same way.`; +): string => { + const maximum = WASM_RESOURCE_MAXIMUMS[WASM_BYTE_BUDGETS[parameter]]; + return `${parameter} is ${String(value)} bytes. ${value < maximum ? `Raise ${parameter} above ${String(value)} bytes (positive integer, maximum ${String(maximum)}), then retry the same complete input after cleanup settles.` : `This is already the runtime representation maximum of ${String(maximum)} bytes; use a suitable smaller complete input or report this blocker.`} The new value applies to the next inspection without restarting REA. command_timeout_ms, other byte budgets and client delivery settings do not raise this allowance. Do not truncate required bytes. Repeating the unchanged request fails the same way.`; +}; + +/** The per-call control of an exhausted byte budget, while a larger value is selectable. */ +const byteBudgetLimit = ( + parameter: WasmByteBudget, + value: number, +): { readonly limit?: AnalysisControlLimit } => { + const key = WASM_BYTE_BUDGETS[parameter]; + const maximum = WASM_RESOURCE_MAXIMUMS[key]; + return value < maximum + ? { + limit: { + control_kind: "parameter", + parameter, + effective_value: value, + unit: "bytes", + minimum: 1, + maximum, + default_value: WASM_RESOURCE_DEFAULTS[key], + applies_at: "next_call", + }, + } + : {}; +}; /** Facts owned before dispatch, even when a version command does not return successfully. */ export type WabtVersionProbe = { @@ -112,7 +141,7 @@ const wabtCommandTimeout = (execution: WabtFailureContext | undefined) => { userMessage: `A WABT command reached its ${String(timeoutMs)} ms server/provider deadline (command_timeout_ms), not the whole-inspection or MCP client deadline.`, remediationAction: `${ timeoutMs < MAX_NODE_TIMER_DELAY_MS - ? `Increase command_timeout_ms above ${String(timeoutMs)} (integer milliseconds, maximum ${String(MAX_NODE_TIMER_DELAY_MS)}), or use rea inspect-wasm-artifact --command-timeout-ms on the CLI.` + ? `Increase command_timeout_ms above ${String(timeoutMs)} (integer milliseconds, maximum ${String(MAX_NODE_TIMER_DELAY_MS)}).` : `command_timeout_ms is already at the maximum supported ${String(MAX_NODE_TIMER_DELAY_MS)} ms; no higher command deadline is supported. Report this blocker or select another suitable complete artifact with caller approval.` } This is a per-call setting; no server restart is needed. Allow the MCP client deadline to cover all version/analysis commands, file checks, cleanup and delivery; increasing only that client deadline does not change this budget. max_input_bytes, max_tool_bytes and max_output_bytes are independent per-call controls; detail: summary reduces delivery size, not analysis work. Resolve any incomplete cleanup before retrying; do not repeat the unchanged failed call.`, }; @@ -201,8 +230,8 @@ export const wabtFailureDialect = ( remediationAction: byteBudgetRecovery( "max_tool_bytes", limits.toolBytes, - WASM_RESOURCE_MAXIMUMS.toolBytes, ), + ...byteBudgetLimit("max_tool_bytes", limits.toolBytes), }, ); return undefined; @@ -215,12 +244,12 @@ export const wabtFailureDialect = ( outputLimit: { reason: outputLimitReason, limits: { max_output_bytes: limits.outputBytes }, + ...byteBudgetLimit("max_output_bytes", limits.outputBytes), recovery: { retryable: false, remediationAction: byteBudgetRecovery( "max_output_bytes", limits.outputBytes, - WASM_RESOURCE_MAXIMUMS.outputBytes, ), }, }, @@ -241,38 +270,6 @@ export const wabtFailureDialect = ( ) : new AnalysisOutputError(OPERATION, exit.message, details), }), - commandCleanup: (command, primary, outcome) => - new ProviderCleanupError( - WABT_PROVIDER_IDENTITY.id, - command.resources, - { - ...versionProbe, - reason: command.cleanupFailure, - previous_error: - primary instanceof AnalysisTimeoutError - ? projectAnalysisError(primary) - : outcome.kind === "output-limit" - ? { - failure_kind: "output-limit", - message: outputLimitReason, - max_output_bytes: limits.outputBytes, - remediation_action: byteBudgetRecovery( - "max_output_bytes", - limits.outputBytes, - WASM_RESOURCE_MAXIMUMS.outputBytes, - ), - } - : outcome.message, - ...(outcome.output === undefined - ? {} - : { - captured_output: { - ...capturedOutput(outcome.kind)(outcome.output.snapshot), - }, - }), - }, - { operation: OPERATION, cause: command }, - ), ...(phase === "artifact" ? { file: { @@ -291,8 +288,8 @@ export const wabtFailureDialect = ( remediationAction: byteBudgetRecovery( "max_input_bytes", limits.inputBytes, - WASM_RESOURCE_MAXIMUMS.inputBytes, ), + ...byteBudgetLimit("max_input_bytes", limits.inputBytes), }, ), }, diff --git a/tests/acceptance/applications/javascriptAnalysisLimits.test.ts b/tests/acceptance/applications/javascriptAnalysisLimits.test.ts index 1a62f372be..f8b171a32d 100644 --- a/tests/acceptance/applications/javascriptAnalysisLimits.test.ts +++ b/tests/acceptance/applications/javascriptAnalysisLimits.test.ts @@ -82,6 +82,49 @@ cliTest( }, ); +cliTest( + "records the evaluator budget that limited a source and names its CLI option outside the result", + async ({ cli }) => { + const root = await createTestTempDirectory("rea-js-cli-precision-control-"); + await writeFile( + join(root, "main.js"), + 'export const selected = flag ? "left" : "right";\n', + ); + const response = await cli.run({ + arguments: [ + "analyze-javascript-application", + root, + "--semantic-precision", + '{"primitive_candidates":1}', + "--format", + "json", + "--full-output", + ], + }); + expect(response.exitCode).toBe(0); + const envelope = response.json as { + readonly data: Evidence; + readonly meta: { readonly cli_controls?: Record }; + }; + const result = javascriptApplicationAnalysisResultSchema.parse( + envelope.data.normalized_result, + ); + expect(result.semantic_graph.coverage.controls).toContainEqual( + expect.objectContaining({ + control_kind: "parameter", + parameter: "semantic_precision.primitive_candidates", + effective_value: 1, + default_value: 256, + }), + ); + expect(envelope.meta.cli_controls).toMatchObject({ + "semantic_precision.primitive_candidates": "--semantic-precision", + }); + // The result names the contract field; only the envelope names the flag. + expect(JSON.stringify(envelope.data)).not.toContain("--semantic-precision"); + }, +); + cliTest.for(cases)( "preserves $name in CLI Evidence without adding ambient defaults", async ({ args, controls }, { cli }) => { diff --git a/tests/acceptance/applications/javascriptUnknownCapacity.test.ts b/tests/acceptance/applications/javascriptUnknownCapacity.test.ts index 68ee3052b9..15d21d46be 100644 --- a/tests/acceptance/applications/javascriptUnknownCapacity.test.ts +++ b/tests/acceptance/applications/javascriptUnknownCapacity.test.ts @@ -51,6 +51,12 @@ cliTest( truncated: true, omitted_nodes: 0, }); + // The graph records the unknown ceilings that stopped retention by + // contract field; the CLI names their options outside the record. + const controls = result.semantic_graph.coverage.controls ?? []; + expect(controls.length).toBeGreaterThan(0); + for (const control of controls) + expect(control.parameter).toMatch(/^max_semantic_unknowns/u); expect( result.semantic_graph.coverage.omitted_unknown_occurrences!.reduce( (sum, row) => sum + row.occurrences, diff --git a/tests/acceptance/browser/webBundleContainmentCli.test.ts b/tests/acceptance/browser/webBundleContainmentCli.test.ts index d09e694f23..6747a59c07 100644 --- a/tests/acceptance/browser/webBundleContainmentCli.test.ts +++ b/tests/acceptance/browser/webBundleContainmentCli.test.ts @@ -58,6 +58,16 @@ cliTest( details: z.object({ partial_observation: z.unknown() }), }) .parse(interrupted.json); + // The analyzer names the deadline field; the CLI adds its flag. + expect(interrupted.json).toMatchObject({ + details: { + limit: { + control_kind: "parameter", + parameter: "total_analysis_timeout_ms", + cli_flag: "--total-analysis-timeout-ms", + }, + }, + }); const partial = parseEvidence(timeout.details.partial_observation); expect(partial.parameters).toMatchObject({ max_heap_mb: 128, diff --git a/tests/acceptance/kernelModuleCli.test.ts b/tests/acceptance/kernelModuleCli.test.ts index 6a6dab8e32..bec0c9ea72 100644 --- a/tests/acceptance/kernelModuleCli.test.ts +++ b/tests/acceptance/kernelModuleCli.test.ts @@ -44,6 +44,23 @@ cliTest( omitted_fields: [], }); expect(evidence.normalized_result.coverage.status).toBe("complete"); + const omitted = await cli.run({ + arguments: [ + "inspect-kernel-module", + path, + "--max-modinfo-value-bytes", + "4096", + "--full-output", + "--json", + ], + }); + expect(omitted.exitCode, omitted.stderr).toBe(0); + expect((omitted.json as { meta: unknown }).meta).toMatchObject({ + cli_controls: { + max_modinfo_key_bytes: "--max-modinfo-key-bytes", + max_modinfo_value_bytes: "--max-modinfo-value-bytes", + }, + }); }, ); diff --git a/tests/acceptance/managedCliOutput.test.ts b/tests/acceptance/managedCliOutput.test.ts index 1bd68c6bcc..e5f4e5efa9 100644 --- a/tests/acceptance/managedCliOutput.test.ts +++ b/tests/acceptance/managedCliOutput.test.ts @@ -79,19 +79,36 @@ cliTest( ...admitted, "--max-metadata-representation-bytes", "1", + "--full-output", "--json", ], }); expect(partial.exitCode, partial.stderr).toBe(0); expect(partial.json).toMatchObject({ - parameters: { - max_snapshot_bytes: bytes.length, - max_metadata_representation_bytes: 1, + data: { + parameters: { + max_snapshot_bytes: bytes.length, + max_metadata_representation_bytes: 1, + }, + normalized_result: { + coverage: { + state: "partial", + issues: [ + expect.objectContaining({ + code: "resource-limit", + limit: expect.objectContaining({ + parameter: "max_metadata_representation_bytes", + }), + }), + ], + }, + }, }, - normalized_result: { - coverage: { - state: "partial", - issues: [expect.objectContaining({ code: "resource-limit" })], + // The CLI names its option for the recorded control outside the result. + meta: { + cli_controls: { + max_metadata_representation_bytes: + "--max-metadata-representation-bytes", }, }, }); diff --git a/tests/acceptance/rustBinaryCli.test.ts b/tests/acceptance/rustBinaryCli.test.ts index b2da13e9af..d14642f8ca 100644 --- a/tests/acceptance/rustBinaryCli.test.ts +++ b/tests/acceptance/rustBinaryCli.test.ts @@ -717,6 +717,33 @@ cliTest( }, ); +cliTest( + "names the option of the recorded compiler-path control in the full-output envelope", + async ({ cli }) => { + const root = await createTestTempDirectory("rea-rust-cli-controls-"); + const path = join(root, "overflow.elf"); + await writeFile(path, createRustHashOverflowImage()); + const result = await cli.run({ + arguments: ["inspect-rust-binary", path, "--full-output", "--json"], + }); + expect(result.exitCode, result.stderr).toBe(0); + const envelope = result.json as { + data: unknown; + meta: { cli_controls?: unknown }; + }; + const report = rustBinarySchema.parse( + toolContract("inspect_rust_binary").outputSchema.parse(envelope.data) + .normalized_result, + ); + expect(report.rustc_commit?.coverage?.limit).toMatchObject({ + parameter: "max_rustc_hashes", + }); + expect(envelope.meta.cli_controls).toEqual({ + max_rustc_hashes: "--max-rustc-hashes", + }); + }, +); + cliTest( "rejects malformed Rust view JSON before opening the selected path", async ({ cli }) => { diff --git a/tests/acceptance/rustDependencyViews.test.ts b/tests/acceptance/rustDependencyViews.test.ts index 46ef80a876..d21cc45af0 100644 --- a/tests/acceptance/rustDependencyViews.test.ts +++ b/tests/acceptance/rustDependencyViews.test.ts @@ -35,13 +35,24 @@ cliTest( output, "--max-rustc-hashes", String(maxHashes), + "--full-output", "--json", ], }); expect(delivered.exitCode, delivered.stderr).toBe(0); + const envelope = delivered.json as { + data: { summary: { normalized_result: unknown } }; + meta: { cli_controls?: unknown }; + }; + // The summary wraps the view; the CLI still names the option for the + // control the complete Evidence records. + expect(envelope.meta.cli_controls).toEqual( + maxHashes === 64 + ? { max_rustc_hashes: "--max-rustc-hashes" } + : undefined, + ); const summary = analysisViewResultSchema.parse( - (delivered.json as { summary: { normalized_result: unknown } }).summary - .normalized_result, + envelope.data.summary.normalized_result, ); if ( summary.kind !== "summary" || @@ -57,6 +68,10 @@ cliTest( status: "partial", reason: "max_rustc_hashes", effective_limit: 64, + limit: expect.objectContaining({ + parameter: "max_rustc_hashes", + effective_value: 64, + }), }, } : {}), diff --git a/tests/boundary/binaryDiagnostics/pwntoolsLayoutProvider.test.ts b/tests/boundary/binaryDiagnostics/pwntoolsLayoutProvider.test.ts index 265de9b925..25d2899030 100644 --- a/tests/boundary/binaryDiagnostics/pwntoolsLayoutProvider.test.ts +++ b/tests/boundary/binaryDiagnostics/pwntoolsLayoutProvider.test.ts @@ -289,7 +289,13 @@ it.runIf(!unsupportedHost).each([ throw new Error("Excess diagnostics must not return partial success"); expect(projectAnalysisError(result.error)).toMatchObject({ code: "resource_constraint", - details: { captured_output: { truncated: true } }, + details: { + captured_output: { truncated: true }, + limit: { + parameter: "producer_limits.diagnostic_bytes", + effective_value: budget ?? 1048576, + }, + }, }); } await expect(access(ownedPath)).rejects.toMatchObject({ code: "ENOENT" }); diff --git a/tests/boundary/browser/cdpTargetDeadlines.test.ts b/tests/boundary/browser/cdpTargetDeadlines.test.ts index c5e51d3372..12e403c37f 100644 --- a/tests/boundary/browser/cdpTargetDeadlines.test.ts +++ b/tests/boundary/browser/cdpTargetDeadlines.test.ts @@ -718,7 +718,12 @@ it("applies caller-selected discovery_timeout_ms to browser-socket discovery", a expect(projected.remediation?.action).toContain( `Increase discovery_timeout_ms above ${String(discoveryTimeoutMs)}`, ); - expect(projected.remediation?.action).toContain("--discovery-timeout-ms"); + expect(projected.remediation?.action).not.toContain("--"); + expect(projected.details?.limit).toMatchObject({ + control_kind: "parameter", + parameter: "discovery_timeout_ms", + effective_value: discoveryTimeoutMs, + }); await waitFor(() => expect(browser.activeConnectionCount()).toBe(0)); } finally { await provider.close(); @@ -761,7 +766,12 @@ it("applies caller-selected discovery_timeout_ms to HTTP discovery independently expect(projected.message).toContain( `${String(discoveryTimeoutMs)} ms discovery_timeout_ms`, ); - expect(projected.remediation?.action).toContain("--discovery-timeout-ms"); + expect(projected.remediation?.action).not.toContain("--"); + expect(projected.details?.limit).toMatchObject({ + control_kind: "parameter", + parameter: "discovery_timeout_ms", + effective_value: discoveryTimeoutMs, + }); expect(projected.remediation?.action).toContain( "command_timeout_ms does not raise it", ); diff --git a/tests/boundary/cli/artifactInputLimits.test.ts b/tests/boundary/cli/artifactInputLimits.test.ts index a3132ec968..3b2faca950 100644 --- a/tests/boundary/cli/artifactInputLimits.test.ts +++ b/tests/boundary/cli/artifactInputLimits.test.ts @@ -5,16 +5,20 @@ import { z } from "zod"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; import { cliTest } from "../../support/cli/cliFixture.js"; -for (const { command, limit, recovery } of [ +for (const { command, limit, recovery, cliFlag } of [ { command: "inspect-go-binary", limit: 256 * 1024 * 1024, recovery: "max_input_bytes", + cliFlag: "--max-input-bytes", }, { command: "inspect-rust-binary", limit: 256 * 1024 * 1024, recovery: "producer_limits.input_bytes", + // The provider binds producer_limits.input_bytes; the CLI names the + // option that sets the whole field. + cliFlag: "--producer-limits", }, { command: "inspect-il2cpp-metadata", @@ -25,8 +29,14 @@ for (const { command, limit, recovery } of [ command: "inspect-wasm-artifact", limit: 8 * 1024 * 1024, recovery: "max_input_bytes", + cliFlag: "--max-input-bytes", }, -]) { +] as readonly { + readonly command: string; + readonly limit: number; + readonly recovery: string; + readonly cliFlag?: string; +}[]) { cliTest.skipIf(process.platform === "win32")( `${command} identifies input-size refusal and applicable recovery`, async ({ cli }) => { @@ -71,6 +81,12 @@ exit 1 .parse(output.json); // Raising the evidence-reply allowance cannot admit an oversized input. expect(refusal.remediation.action).toContain(recovery); + if (cliFlag !== undefined) { + expect(output.json).toMatchObject({ + details: { limit: { parameter: recovery, cli_flag: cliFlag } }, + }); + expect(refusal.remediation.action).not.toContain("--"); + } expect(refusal.remediation.action).not.toMatch( /allowance for the evidence reply/u, ); diff --git a/tests/boundary/cli/cliResultControls.test.ts b/tests/boundary/cli/cliResultControls.test.ts new file mode 100644 index 0000000000..b9e5357de9 --- /dev/null +++ b/tests/boundary/cli/cliResultControls.test.ts @@ -0,0 +1,251 @@ +import { Writable } from "node:stream"; + +import { Cli, Formatter } from "incur"; +import { expect, it } from "vitest"; +import { z } from "zod"; + +import { parseCliOutputArguments } from "../../../src/cliOutput.js"; +import { registerContractCommand } from "../../../src/cli/contractCommand.js"; +import { createCliResultOutput } from "../../../src/cli/cliResultOutput.js"; +import { + cliResultControls, + withCliResultControls, +} from "../../../src/cli/cliResultControls.js"; +import { cliResultControlsIn } from "../../../src/cli/projectCliAnalysisResult.js"; +import type { CliInstance } from "../../../src/cli/types.js"; +import { deadlineParameterLimit } from "../../../src/domain/analysisResourceLimits.js"; +import { + analysisParameterLimitSchema, + analysisResultLimitSchema, +} from "../../../src/domain/analysisSettingDefinitions.js"; +import { producerLimitControl } from "../../../src/domain/producerResourceLimits.js"; +import { silentLogger } from "../../../src/logger.js"; + +/** A partial result that records its controls by contract field only. */ +const partialResult = () => ({ + status: "partial", + unknowns: [ + { + dimension: "javascript_analysis", + limit: deadlineParameterLimit("worker_timeout_ms", 5, 1_000), + }, + ], + coverage: { + limits: [ + producerLimitControl("output_bytes", 4, 8), + // An environment control has no per-call option. + { + control_kind: "environment", + environment: "REA_FIXTURE_BYTES", + parameter: "ignored", + }, + ], + }, + // A control this command takes no flag for keeps only its field. + unbound: { limit: deadlineParameterLimit("other_timeout_ms", 1, 2) }, + // Captured content that looks like a control is data, not a reference + // REA recorded, even when it names a bound flag. + captured: { + reported: deadlineParameterLimit("max_reply_bytes", 1, 2), + nested: [{ limit: deadlineParameterLimit("max_reply_bytes", 1, 2) }], + }, + // An omitted optional value that JSON output skips ends nothing. + trailing: undefined, +}); + +/** The fixture's output schema: only its declared positions are controls. */ +const partialResultSchema = z.strictObject({ + status: z.string(), + unknowns: z.array( + z.strictObject({ + dimension: z.string(), + limit: analysisResultLimitSchema.exactOptional(), + }), + ), + coverage: z.strictObject({ + limits: z.array( + z.union([ + analysisParameterLimitSchema, + z.strictObject({ + control_kind: z.literal("environment"), + environment: z.string(), + parameter: z.string(), + }), + ]), + ), + }), + unbound: z.strictObject({ limit: analysisParameterLimitSchema }), + captured: z.record(z.string(), z.unknown()), + trailing: z.undefined().optional(), +}); + +const binding = { + operation: "inspect_control_fixture", + fields: {}, + flags: { + worker_timeout_ms: "--worker-timeout-ms", + producer_limits: "--producer-limits", + max_reply_bytes: "--max-reply-bytes", + }, +}; + +it("collects each recorded control's flag without changing the result", () => { + const result = partialResult(); + const before = structuredClone(result); + expect(cliResultControlsIn(result, partialResultSchema, binding)).toEqual({ + worker_timeout_ms: "--worker-timeout-ms", + "producer_limits.output_bytes": "--producer-limits", + }); + expect(result).toEqual(before); +}); + +/** Run the fixture command once, returning its output and recorded controls. */ +const runFixtureCommand = async (produce: () => unknown) => { + const contract = { + name: "inspect_control_fixture", + inputSchema: z.strictObject({ + path: z.string(), + worker_timeout_ms: z.number().int().optional(), + }), + outputSchema: partialResultSchema, + }; + const cli = Cli.create("rea-result-controls", { version: "1", sync: false }); + registerContractCommand( + cli as unknown as CliInstance, + silentLogger, + contract, + { + command: "inspect-control-fixture", + description: "Control fixture", + positionals: ["path"], + }, + async () => produce() as never, + ); + const command = Cli.toCommands.get(cli)?.get("inspect-control-fixture"); + if (command === undefined) throw new Error("command is not registered"); + const parse = (key: "args" | "options", value: unknown) => + (Reflect.get(command, key) as { parse(v: unknown): unknown }).parse(value); + return withCliResultControls(async () => { + const value: unknown = await ( + Reflect.get(command, "run") as (value: unknown) => Promise + )({ + args: parse("args", { path: "fixture.bin" }), + options: parse("options", {}), + }); + return { output: value, controls: cliResultControls() }; + }); +}; + +it("records the controls of a contract command's result and returns the result unchanged", async () => { + const { output, controls } = await runFixtureCommand(partialResult); + expect(output).toEqual(partialResult()); + // Only controls this command takes as options are rendered. + expect(controls).toEqual({ worker_timeout_ms: "--worker-timeout-ms" }); +}); + +it("reads a failure's partial Evidence of the same operation at the declared positions only", async () => { + const failure = (operation: string) => ({ + code: "timeout", + message: "Fixture stopped", + details: { + partial_observation: { ...partialResult(), operation }, + }, + }); + const same = await runFixtureCommand(() => + failure("inspect_control_fixture"), + ); + expect(same.output).toEqual(failure("inspect_control_fixture")); + expect(same.controls).toEqual({ worker_timeout_ms: "--worker-timeout-ms" }); + // Evidence of another operation is not described by this output schema. + const other = await runFixtureCommand(() => failure("inspect_source_step")); + expect(other.controls).toBeUndefined(); +}); + +const written = async ( + argv: readonly string[], + cliControls?: Readonly>, +): Promise<{ readonly text: string; readonly collected: number }> => { + const chunks: Buffer[] = []; + const destination = new Writable({ + write(chunk: Buffer, _encoding, callback) { + chunks.push(chunk); + callback(); + }, + }); + const output = createCliResultOutput( + parseCliOutputArguments(["fixture", ...argv]), + destination, + ); + if (output === undefined) throw new Error("Missing output surface"); + const format = argv[argv.indexOf("--format") + 1] ?? "json"; + let collected = 0; + // The ordinary command path: no forced output, controls collected on demand. + const handled = await output.write(partialResult(), { + command: "fixture", + duration: "0ms", + format, + collectCliControls: () => { + collected += 1; + return cliControls; + }, + }); + return { + text: handled ? Buffer.concat(chunks).toString("utf8") : "", + collected, + }; +}; + +const cliControls = { worker_timeout_ms: "--worker-timeout-ms" }; + +it("renders the flags in the full-output envelope, outside the result", async () => { + const full = await written( + ["--format", "json", "--full-output"], + cliControls, + ); + expect(JSON.parse(full.text)).toEqual({ + ok: true, + data: partialResult(), + meta: { + command: "fixture", + duration: "0ms", + cli_controls: cliControls, + }, + }); + expect(full.collected).toBe(1); + // The bare result is the record itself: it gains nothing, and the result + // is not walked for controls nothing will show. + const bare = await written(["--format", "json"], cliControls); + expect(JSON.parse(bare.text)).toEqual(partialResult()); + expect(bare.collected).toBe(0); + expect( + JSON.parse((await written(["--format", "json", "--full-output"])).text), + ).toEqual({ + ok: true, + data: partialResult(), + meta: { command: "fixture", duration: "0ms" }, + }); +}); + +it.each(["yaml", "toon"] as const)( + "keeps the requested %s format when the envelope shows the flags", + async (format) => { + const { text } = await written( + ["--format", format, "--full-output"], + cliControls, + ); + expect(text).toBe( + `${Formatter.format( + { + ok: true, + data: partialResult(), + meta: { + command: "fixture", + duration: "0ms", + cli_controls: cliControls, + }, + }, + format, + )}\n`, + ); + }, +); diff --git a/tests/boundary/cli/managedMemberComparisonCli.test.ts b/tests/boundary/cli/managedMemberComparisonCli.test.ts index 7a744e514c..801ef5058b 100644 --- a/tests/boundary/cli/managedMemberComparisonCli.test.ts +++ b/tests/boundary/cli/managedMemberComparisonCli.test.ts @@ -116,6 +116,32 @@ cliTest( }, }); + // A source refused by its snapshot budget names the source option that + // raises it; the remediation names only the contract field. + const refused = await cli.run({ + arguments: [ + "compare-managed-members", + good, + peer, + "--max-snapshot-bytes", + String(bytes.length - 1), + "--json", + ], + }); + expect(refused.exitCode, refused.stderr).toBe(1); + expect(refused.json).toMatchObject({ + details: { + limit: { + control_kind: "parameter", + parameter: "max_snapshot_bytes", + cli_flag: "--max-snapshot-bytes", + }, + }, + }); + expect( + JSON.stringify((refused.json as { remediation: unknown }).remediation), + ).not.toContain("--max-snapshot-bytes"); + for (const field of ["leftPath", "rightPath"] as const) { const result = await cli.run({ arguments: [ @@ -313,15 +339,35 @@ cliTest( expect.objectContaining({ code: "resource-limit", scope: "metadata.representation", - offset: null, + // The fixture sits within a few hundred bytes of the 64 MiB budget, so + // whether a decoding row or the final projection is refused (and so + // the offset) follows the recovery envelope's size, not this workflow. + limit: expect.objectContaining({ + parameter: "max_metadata_representation_bytes", + }), }), ]); const whole = await cli.run({ - arguments: ["compare-managed-members", left, right, "--json"], + arguments: [ + "compare-managed-members", + left, + right, + "--full-output", + "--json", + ], }); expect(whole.exitCode, whole.stderr).toBe(0); - const wholeEvidence = parseEvidence(whole.json); + const envelope = whole.json as { data: unknown; meta: unknown }; + // The source inspection option that raises the recorded budget is named + // by the comparison command, outside the record. + expect(envelope.meta).toMatchObject({ + cli_controls: { + max_metadata_representation_bytes: + "--max-metadata-representation-bytes", + }, + }); + const wholeEvidence = parseEvidence(envelope.data); const wholeReport = managedMemberComparisonResultSchema.parse( wholeEvidence.normalized_result, ); diff --git a/tests/boundary/cli/nativeDispatchInputBudget.test.ts b/tests/boundary/cli/nativeDispatchInputBudget.test.ts index 581d417928..21674250f7 100644 --- a/tests/boundary/cli/nativeDispatchInputBudget.test.ts +++ b/tests/boundary/cli/nativeDispatchInputBudget.test.ts @@ -54,6 +54,11 @@ describe.skipIf(process.platform !== "darwin")( input_bytes_source: "caller", observed_input_bytes: size, }, + // The provider names the field; the CLI adds the flag. + limit: { + parameter: "max_input_bytes", + cli_flag: "--max-input-bytes", + }, }, }); }, diff --git a/tests/boundary/filesystem/appleDispatchMetadataInputBudget.test.ts b/tests/boundary/filesystem/appleDispatchMetadataInputBudget.test.ts index d897a90733..8d29e083e1 100644 --- a/tests/boundary/filesystem/appleDispatchMetadataInputBudget.test.ts +++ b/tests/boundary/filesystem/appleDispatchMetadataInputBudget.test.ts @@ -80,7 +80,7 @@ it("names the observed size, effective budget, its source and the budget to sele retryable: false, message: `Apple static metadata input (${String(bytes.length)} bytes) exceeds the selected max_input_bytes of ${String(bytes.length - 1)} bytes.`, remediation: { - action: `Retry with max_input_bytes (CLI --max-input-bytes) of at least ${String(bytes.length)}, at most 1073741824 bytes (1 GiB); REA holds that many bytes in memory for the read.`, + action: `Retry with max_input_bytes of at least ${String(bytes.length)}, at most 1073741824 bytes (1 GiB); REA holds that many bytes in memory for the read.`, }, details: { reported_limits: { @@ -89,9 +89,16 @@ it("names the observed size, effective budget, its source and the budget to sele maximum_selectable_input_bytes: MAXIMUM_DISPATCH_METADATA_INPUT_BYTES, observed_input_bytes: bytes.length, }, + limit: { + control_kind: "parameter", + parameter: "max_input_bytes", + effective_value: bytes.length - 1, + maximum: MAXIMUM_DISPATCH_METADATA_INPUT_BYTES, + }, }, }); expect(JSON.stringify(projected)).not.toContain("no runtime override"); + expect(JSON.stringify(projected)).not.toContain("--"); }); it("refuses files above the default without opt-in and points past the maximum to a deep provider", async () => { diff --git a/tests/boundary/filesystem/flutterBuildProvider.test.ts b/tests/boundary/filesystem/flutterBuildProvider.test.ts index f2e036c9bd..ae5bc353e7 100644 --- a/tests/boundary/filesystem/flutterBuildProvider.test.ts +++ b/tests/boundary/filesystem/flutterBuildProvider.test.ts @@ -2310,6 +2310,30 @@ it("recovers omitted Dart pool strings through selection and per-call admission text.includes("pool_policy.run_bytes=1024"), ), ).toBe(true); + // The result records each budget that left the projection partial by + // contract field; adapters name their own option. + // Every budget this fixture exceeds is recorded, and nothing else. + const control = (budget: string, unit: "bytes" | "count", value: number) => ({ + control_kind: "parameter", + parameter: `pool_policy.${budget}`, + effective_value: value, + unit, + minimum: 1, + maximum: Number.MAX_SAFE_INTEGER, + default_value: value, + applies_at: "next_call", + }); + expect( + [...(limited.report.string_pool.limits ?? [])].sort((left, right) => + left.parameter.localeCompare(right.parameter), + ), + ).toEqual([ + control("run_bytes", "bytes", 1024), + control("token_bytes", "bytes", 128), + control("token_limit", "count", 2000), + control("uri_limit", "count", 500), + ]); + expect(limited.evidence.limitations.join(" ")).not.toContain("--pool-policy"); const selected = await inspect({ contains: "package:tail/" }); expect(selected.report.string_pool.package_uris).toEqual([tail]); expect(selected.report.string_pool.package_uri_count_at_least).toBe(1); @@ -2324,6 +2348,7 @@ it("recovers omitted Dart pool strings through selection and per-call admission expect(recovered.report.string_pool.package_uris).toContain(longUri); expect(recovered.report.string_pool.class_like_tokens).toContain(longToken); expect(recovered.report.string_pool.coverage).toBe("complete"); + expect(recovered.report.string_pool).not.toHaveProperty("limits"); expect(selected.report.target).toEqual(limited.report.target); expect(recovered.report.libapp.sha256).toEqual(limited.report.libapp.sha256); expect(recovered.evidence.parameters.pool_policy).toEqual({ diff --git a/tests/boundary/mcp/kernelModuleMcp.test.ts b/tests/boundary/mcp/kernelModuleMcp.test.ts index f94ca81927..19bc40e95a 100644 --- a/tests/boundary/mcp/kernelModuleMcp.test.ts +++ b/tests/boundary/mcp/kernelModuleMcp.test.ts @@ -66,6 +66,28 @@ mcpTest( expect.stringContaining("max_modinfo_value_bytes at least 4097"), ]), ); + // The result records each control by contract field; MCP text names no + // CLI option. + expect(initial.normalized_result.modinfo?.omission_limits).toEqual([ + { + control_kind: "parameter", + parameter: "max_modinfo_key_bytes", + effective_value: 256, + unit: "bytes", + minimum: 1, + maximum: 536870912, + default_value: 256, + applies_at: "next_call", + }, + expect.objectContaining({ + parameter: "max_modinfo_value_bytes", + effective_value: 4096, + default_value: 4096, + }), + ]); + expect(initial.normalized_result.limitations.join(" ")).not.toContain( + "--max-modinfo", + ); const recovered = await inspect({ max_modinfo_key_bytes: 257, max_modinfo_value_bytes: 4097, @@ -78,6 +100,9 @@ mcpTest( omitted_fields: [], }); expect(recovered.normalized_result.coverage.status).toBe("complete"); + expect(recovered.normalized_result.modinfo).not.toHaveProperty( + "omission_limits", + ); } finally { await session.close(); } diff --git a/tests/boundary/mcp/rustBinaryMcp.test.ts b/tests/boundary/mcp/rustBinaryMcp.test.ts index 345ab82f0e..6adda78161 100644 --- a/tests/boundary/mcp/rustBinaryMcp.test.ts +++ b/tests/boundary/mcp/rustBinaryMcp.test.ts @@ -120,6 +120,10 @@ mcpTest( status: "partial", reason: "max_rustc_hashes", effective_limit: 64, + limit: expect.objectContaining({ + control_kind: "parameter", + parameter: "max_rustc_hashes", + }), }); } finally { await session.close(); diff --git a/tests/boundary/native/pwndbgReplyFinalization.test.ts b/tests/boundary/native/pwndbgReplyFinalization.test.ts index c8d7e6091c..c526e738ee 100644 --- a/tests/boundary/native/pwndbgReplyFinalization.test.ts +++ b/tests/boundary/native/pwndbgReplyFinalization.test.ts @@ -253,3 +253,30 @@ it.each(["malformed JSON", "malformed UTF-8", "producer refusal"])( expect(replyClose.handles.every((handle) => handle.fd === -1)).toBe(true); }, ); + +it("binds producer_limits.output_bytes when the debugger bridge reports its reply over budget", async () => { + const selected = await fixture( + Buffer.from( + JSON.stringify({ + ok: false, + reason: "output-limit", + message: "authored debugger reply exceeded output_bytes", + }), + ), + ); + const error: unknown = await selected + .project(new AbortController().signal) + .catch((cause: unknown) => cause); + if (!(error instanceof AnalysisError)) + throw new Error("Expected debugger reply failure"); + const projected = projectAnalysisError(error); + expect(projected.details?.limit).toMatchObject({ + control_kind: "parameter", + parameter: "producer_limits.output_bytes", + effective_value: resolvePwntoolsLimits().output_bytes, + }); + expect(projected.remediation.action).toContain( + "Increase producer_limits.output_bytes", + ); + expect(projected.remediation.action).not.toContain("--"); +}); diff --git a/tests/boundary/providers/managed/managedStaticProvider.test.ts b/tests/boundary/providers/managed/managedStaticProvider.test.ts index 3d0995c543..673d1d38d1 100644 --- a/tests/boundary/providers/managed/managedStaticProvider.test.ts +++ b/tests/boundary/providers/managed/managedStaticProvider.test.ts @@ -67,10 +67,24 @@ it.each([ detail: expect.stringContaining( "max_metadata_representation_bytes=1", ), + limit: { + control_kind: "parameter", + parameter: "max_metadata_representation_bytes", + effective_value: 1, + unit: "bytes", + minimum: 1, + maximum: Number.MAX_SAFE_INTEGER, + default_value: 64 * 1024 * 1024, + applies_at: "next_call", + }, }), ], }, }); + // The issue names the contract field; adapters render their option. + expect(JSON.stringify(partial.value.result)).not.toContain( + "--max-metadata", + ); const recovered = await client.execute(operation, { max_snapshot_bytes: bytes.length, max_metadata_representation_bytes: 1024 * 1024, diff --git a/tests/boundary/rust/rustBinaryBudget.test.ts b/tests/boundary/rust/rustBinaryBudget.test.ts index a593ed7bc9..cb771e360e 100644 --- a/tests/boundary/rust/rustBinaryBudget.test.ts +++ b/tests/boundary/rust/rustBinaryBudget.test.ts @@ -18,11 +18,14 @@ it("reports a recoverable compiler prefix without refusing the dependency report expect(result.value.rustc_commit?.coverage).toMatchObject({ reason: "max_rustc_hashes", effective_limit: 64, + limit: { parameter: "max_rustc_hashes", effective_value: 64 }, }); expect(result.value.auditable_metadata?.packages).toHaveLength(2); expect(result.value.limitations).toContainEqual( - expect.stringContaining("--max-rustc-hashes"), + expect.stringContaining("rustc_commit.coverage.limit"), ); + // The producer names the contract field; the CLI renders its own option. + expect(result.value.limitations.join(" ")).not.toContain("--"); }); it("recovers the same complete Rust image after input and report budget changes", async () => { @@ -39,8 +42,16 @@ it("recovers the same complete Rust image after input and report budget changes" const projectedInput = projectAnalysisError(smallInput.error); expect(projectedInput).toMatchObject({ code: "resource_constraint", - details: { reported_limits: { maximum_input_bytes: 4095 } }, + details: { + reported_limits: { maximum_input_bytes: 4095 }, + limit: { + control_kind: "parameter", + parameter: "producer_limits.input_bytes", + effective_value: 4095, + }, + }, }); + expect(projectedInput.remediation.action).not.toContain("--"); expect(projectedInput.remediation.action).toContain( "producer_limits.input_bytes", ); @@ -52,8 +63,16 @@ it("recovers the same complete Rust image after input and report budget changes" const projectedReport = projectAnalysisError(smallReport.error); expect(projectedReport).toMatchObject({ code: "resource_constraint", - details: { reported_limits: { maximum_output_bytes: 16 } }, + details: { + reported_limits: { maximum_output_bytes: 16 }, + limit: { + control_kind: "parameter", + parameter: "producer_limits.output_bytes", + effective_value: 16, + }, + }, }); + expect(projectedReport.remediation.action).not.toContain("--"); expect(projectedReport.remediation.action).toContain( "producer_limits.output_bytes", ); @@ -64,6 +83,85 @@ it("recovers the same complete Rust image after input and report budget changes" if (!recovered.ok) throw recovered.error; expect(recovered.value.auditable_metadata?.packages).toHaveLength(2); expect(recovered.value.artifact.bytes).toBe(4096); + // Just below the smallest admitted budget, the dependency graph still + // fits but the complete report does not. + const inspectWithin = (output_bytes: number) => + provider.inspect({ + path, + producer_limits: { input_bytes: 4096, output_bytes }, + }); + let refused = 16; + let admitted = 16384; + while (admitted - refused > 1) { + const middle = Math.floor((refused + admitted) / 2); + if ((await inspectWithin(middle)).ok) admitted = middle; + else refused = middle; + } + const reportBytes = admitted; + const tightReport = await inspectWithin(reportBytes - 1); + if (tightReport.ok) throw new Error("Expected complete-report refusal"); + const projectedTight = projectAnalysisError(tightReport.error); + expect(projectedTight).toMatchObject({ + code: "resource_constraint", + message: expect.stringContaining("exceeds the inline output budget"), + details: { + reported_limits: { maximum_output_bytes: reportBytes - 1 }, + limit: { + control_kind: "parameter", + parameter: "producer_limits.output_bytes", + effective_value: reportBytes - 1, + }, + }, + }); + expect(projectedTight.remediation.action).not.toContain("--"); + } finally { + await provider.close(); + } +}); + +it("describes compiler coverage from the retained result when report trimming drops every path", async () => { + const root = await createTestTempDirectory("rea-rust-trimmed-guidance-"); + const path = join(root, "many-hashes.elf"); + await writeFile(path, createRustHashOverflowImage()); + const provider = new RustBinaryProvider(); + try { + const inspect = (output_bytes: number) => + provider.inspect({ + path, + max_rustc_hashes: 1, + producer_limits: { output_bytes }, + }); + // The smallest admitted report keeps dependencies and no compiler path. + let refused = 16; + let admitted = 1024 * 1024; + while (admitted - refused > 1) { + const middle = Math.floor((refused + admitted) / 2); + if ((await inspect(middle)).ok) admitted = middle; + else refused = middle; + } + const trimmed = await inspect(admitted); + if (!trimmed.ok) throw trimmed.error; + expect(trimmed.value.rustc_commit).toBeNull(); + expect(trimmed.value.auditable_metadata?.packages).toHaveLength(2); + const text = trimmed.value.limitations.join(" "); + // The reader's partial-prefix guidance referred to a record that no + // longer exists; the trimming guidance names its control directly. + expect(text).not.toContain("rustc_commit.coverage.limit"); + expect(text).not.toContain("max_rustc_hashes=1"); + expect(text).toContain( + "Compiler paths were omitted to preserve dependency facts", + ); + expect(text).toContain("producer_limits.output_bytes"); + // The control that omitted every path stays recorded outside the + // dropped compiler record, at a position the output schema declares. + expect(trimmed.value.rustc_commit_omission).toEqual({ + reason: "report_bytes", + limit: expect.objectContaining({ + control_kind: "parameter", + parameter: "producer_limits.output_bytes", + effective_value: admitted, + }), + }); } finally { await provider.close(); } diff --git a/tests/boundary/rust/rustBinaryImage.test.ts b/tests/boundary/rust/rustBinaryImage.test.ts index f80241926b..8ada7ecde7 100644 --- a/tests/boundary/rust/rustBinaryImage.test.ts +++ b/tests/boundary/rust/rustBinaryImage.test.ts @@ -381,6 +381,16 @@ it("retains dependency facts when compiler paths exceed the selected prefix", () status: "partial", reason: "max_rustc_hashes", effective_limit: 64, + limit: { + control_kind: "parameter", + parameter: "max_rustc_hashes", + effective_value: 64, + unit: "count", + minimum: 1, + maximum: Number.MAX_SAFE_INTEGER, + default_value: 64, + applies_at: "next_call", + }, }); const recovered = readRustBinaryImage(bytes, 65); expect(recovered.rustc_commit?.hashes).toHaveLength(65); diff --git a/tests/boundary/sqlite/sqliteDatabaseFailures.test.ts b/tests/boundary/sqlite/sqliteDatabaseFailures.test.ts index 6f803705cd..88ca92c2eb 100644 --- a/tests/boundary/sqlite/sqliteDatabaseFailures.test.ts +++ b/tests/boundary/sqlite/sqliteDatabaseFailures.test.ts @@ -32,8 +32,17 @@ it.each([null, "owned stop unconfirmed"])( if (cleanup === null) expect(projected).toMatchObject({ code: "provider_timeout", - details: { timeout_ms: 1234 }, - remediation: { action: expect.stringContaining("--worker-timeout-ms") }, + details: { + timeout_ms: 1234, + limit: { + control_kind: "parameter", + parameter: "worker_timeout_ms", + effective_value: 1234, + }, + }, + remediation: { + action: expect.not.stringContaining("--"), + }, }); else expect(projected).toMatchObject({ diff --git a/tests/composition/reverseEngineering.test.ts b/tests/composition/reverseEngineering.test.ts index b478a02f37..3f19a40943 100644 --- a/tests/composition/reverseEngineering.test.ts +++ b/tests/composition/reverseEngineering.test.ts @@ -64,12 +64,24 @@ it.each(["objdump", "rizin"] as const)( output_budget_bytes: 8, output_budget_source: "request", output_truncated: true, + output_limit: { + control_kind: "parameter", + parameter: "max_output_bytes", + effective_value: 8, + unit: "bytes", + minimum: 1, + default_value: 16 * 1024 * 1024, + applies_at: "next_call", + }, completion_status: "unknown", }); expect(limited.value.parameters).toMatchObject({ max_output_bytes: 8 }); expect(limited.value.limitations).toContainEqual( expect.stringContaining("max_output_bytes=8"), ); + expect(limited.value.limitations.join(" ")).not.toContain( + "--max-output-bytes", + ); const recovered = await inspect(32); if (!recovered.ok) throw recovered.error; expect(recovered.value.normalized_result).toMatchObject({ @@ -79,6 +91,9 @@ it.each(["objdump", "rizin"] as const)( output_truncated: false, completion_status: "complete", }); + expect(recovered.value.normalized_result).not.toHaveProperty( + "output_limit", + ); expect(recovered.value.parameters).toMatchObject({ max_output_bytes: 32, }); diff --git a/tests/evaluation/cliTextGuard.test.ts b/tests/evaluation/cliTextGuard.test.ts new file mode 100644 index 0000000000..da50056ab7 --- /dev/null +++ b/tests/evaluation/cliTextGuard.test.ts @@ -0,0 +1,84 @@ +import { expect, it } from "vitest"; +import { + CLI_ONLY_FILES, + HOST_ONLY_COMMANDS, + cliTextGuardSelects, + cliTextOutsideCliCount, +} from "../../scripts/verify/cli-text-guard.mjs"; + +it.each([ + ["a parenthesized CLI option", '"Raise it (CLI: --max-heap-mb)."'], + ["a template-built CLI option", "`Raise it (CLI --${flag} ).`"], + ["an option named for the CLI", '"or pass --semantic-precision JSON."'], + ["CLI-only prose", '"Increase it on the CLI."'], + ["a suggested CLI command", '"Retry, or use rea decompile --resume."'], + ["a backticked CLI command", "`Run \\`rea inspect-plist \\` first.`"], + ["a flag spelled in a binding", 'cliFlag: "--max-heap-mb"'], + ["a flag spelled as a message", 'userMessage: "--path is required"'], +])("counts %s", (_name, content) => { + expect(cliTextOutsideCliCount(content)).toBe(1); +}); + +it.each([ + ["a contract field", '"Increase max_heap_mb on the next call."'], + ["an MCP operation name", '"Call inspect_plist on the bundle."'], + ["a word that only starts with rea", '"or use reader settings."'], +])("ignores %s", (_name, content) => { + expect(cliTextOutsideCliCount(content)).toBe(0); +}); + +it.each([...HOST_ONLY_COMMANDS.keys()])( + "keeps the operator instruction to run host-only rea %s", + (command) => { + expect(HOST_ONLY_COMMANDS.get(command)).toMatch(/no MCP operation/u); + expect(cliTextOutsideCliCount(`"Run \`rea ${command} --json\`."`)).toBe(0); + expect(cliTextOutsideCliCount(`"Retry, or use rea ${command}."`)).toBe(0); + }, +); + +it.each([ + ["a parenthesized host-only command", '"Retry (CLI: `rea setup --json`)."'], + [ + "a parenthesized host-only command with an option", + '"(CLI: rea doctor --provider ghidra)"', + ], +])("keeps %s", (_name, content) => { + expect(cliTextOutsideCliCount(content)).toBe(0); +}); + +it.each([ + [ + "another option beside a host-only command", + '"(CLI: --max-heap-mb, or `rea doctor`)"', + ], + [ + "another command beside a host-only command", + '"(CLI: `rea doctor`, then `rea function`)"', + ], + [ + "an unquoted command between host-only commands", + '"(CLI: rea doctor, then rea function, then rea setup)"', + ], + [ + "an unquoted command right after a host-only command's arguments", + '"(CLI: rea doctor --json rea function)"', + ], +])("still counts %s", (_name, content) => { + expect(cliTextOutsideCliCount(content)).toBeGreaterThan(0); +}); + +it("counts a CLI command that only shares a host-only prefix", () => { + expect(cliTextOutsideCliCount('"Run `rea doctoral`."')).toBe(1); +}); + +it("selects services but not the CLI layer or CLI-only files", () => { + expect(cliTextGuardSelects("src/domain/analysisErrorPresentation.ts")).toBe( + true, + ); + expect(cliTextGuardSelects("src/cli/contractCommand.ts")).toBe(false); + expect(cliTextGuardSelects("src/cliOutput.ts")).toBe(false); + for (const [path, reason] of CLI_ONLY_FILES) { + expect(reason).not.toBe(""); + expect(cliTextGuardSelects(path)).toBe(false); + } +});