diff --git a/docs/design/rea-limit-inventory.md b/docs/design/rea-limit-inventory.md index 39adf16c69..33bb96b558 100644 --- a/docs/design/rea-limit-inventory.md +++ b/docs/design/rea-limit-inventory.md @@ -238,3 +238,8 @@ keeps names that are numeric limits, and requires each name to be an `environment` on an analysis setting or a registry entry with a reason. The registry accepts only `restart-only`. A limit checked on each call has to be an analysis setting. The check rejects a `per-call` registry entry. +The same script reads every default, floor, and maximum in the three numeric +tables above and compares them with `ANALYSIS_SETTINGS` or the owner constant +the parser enforces. A mismatch names the limit and both values. A cell that +is only `Number.MAX_SAFE_INTEGER` or `MAX_GHIDRA_DECOMPILE_TIMEOUT_SECONDS` +means that export. `unset` means the code default is null. diff --git a/scripts/verify/rea-numeric-limits.d.mts b/scripts/verify/rea-numeric-limits.d.mts index fb3273b517..533c262f50 100644 --- a/scripts/verify/rea-numeric-limits.d.mts +++ b/scripts/verify/rea-numeric-limits.d.mts @@ -63,3 +63,57 @@ export function requiredRuntimeLimitFailure( readonly inRegistry: boolean; }, ): RequiredRuntimeLimitFailure | undefined; + +/** One default, floor, and maximum from the numeric inventory tables. */ +export type DocumentedNumericLimit = { + readonly name: string; + readonly section: string; + readonly defaultCell: string; + readonly floorCell: string; + readonly maximumCell: string; +}; + +/** Default, floor, and maximum exported by the analysis-setting registry or an owner. */ +export type ExportedNumericLimit = { + readonly name: string; + readonly aliases?: readonly string[]; + readonly defaultValue: number | null; + readonly minimum: number; + readonly maximum: number; +}; + +/** Read default, floor, and maximum from the three numeric inventory tables. */ +export function parseDocumentedNumericLimits( + markdown: string, +): DocumentedNumericLimit[]; + +/** + * Read one documented cell. + * A fraction is unreadable. Prose is allowed only after a complete integer and whitespace. + */ +export function documentedLimitCell( + cell: string, + names: Readonly>, +): + | { readonly ok: true; readonly value: number | null } + | { readonly ok: false; readonly reason: string }; + +/** + * Compare documented limits with exported bounds. + * Each failure names the limit and both values. + */ +export function compareDocumentedNumericLimits( + rows: readonly DocumentedNumericLimit[], + bounds: readonly ExportedNumericLimit[], + names: Readonly>, +): string[]; + +/** + * Bounds ANALYSIS_SETTINGS and the restart-only owners export. + * `failures` names a registry entry that has no exported bound. + */ +export function loadExportedNumericLimitBounds(): Promise<{ + readonly bounds: readonly ExportedNumericLimit[]; + readonly names: Readonly>; + readonly failures: readonly string[]; +}>; diff --git a/scripts/verify/rea-numeric-limits.mjs b/scripts/verify/rea-numeric-limits.mjs index 40a75b0062..02a18358a3 100644 --- a/scripts/verify/rea-numeric-limits.mjs +++ b/scripts/verify/rea-numeric-limits.mjs @@ -8,6 +8,8 @@ import ts from "typescript6"; // reported separately and are not verified by this Node-only scan. // Per-call limits belong to ANALYSIS_SETTINGS. // A name in REQUIRED_RUNTIME_LIMITS that is absent from source fails closed. +// Each default, floor, and maximum in docs/design/rea-limit-inventory.md must +// equal ANALYSIS_SETTINGS or the owner export the parser enforces. const root = fileURLToPath(new URL("../../", import.meta.url)); const definitionsPath = join(root, "src/domain/analysisSettingDefinitions.ts"); @@ -919,6 +921,415 @@ export const parseRuntimeSettingEnvironments = (source) => { return names; }; +const DOCUMENTED_LIMIT_SECTIONS = [ + "Runtime analysis settings", + "Per-call limits in the runtime system", + "Restart-only numeric limits", +]; + +const tableCells = (line) => + line + .split("|") + .slice(1, -1) + .map((cell) => cell.trim()); + +const separatorRow = (cells) => + cells.length > 0 && cells.every((cell) => /^:?-+:?$/u.test(cell)); + +/** + * Read default, floor, and maximum from the three numeric inventory tables. + * The limit name is the first cell. Later prose tables are not limits. + * + * @param {string} markdown + */ +export const parseDocumentedNumericLimits = (markdown) => { + const lines = markdown.split(/\r?\n/u); + const rows = []; + for (const title of DOCUMENTED_LIMIT_SECTIONS) { + const heading = lines.findIndex((line) => line.trim() === `## ${title}`); + if (heading < 0) + throw new Error( + `docs/design/rea-limit-inventory.md is missing "## ${title}"`, + ); + let index = heading + 1; + while (index < lines.length && !lines[index].startsWith("|")) { + if (lines[index].startsWith("#")) + throw new Error(`## ${title} has no limit table`); + index += 1; + } + if (!lines[index]?.startsWith("|")) + throw new Error(`## ${title} has no limit table`); + const header = tableCells(lines[index]); + const column = (name) => { + const found = header.indexOf(name); + if (found < 0) + throw new Error(`## ${title} table is missing the ${name} column`); + return found; + }; + const defaultColumn = column("Default"); + const floorColumn = column("Floor"); + const maximumColumn = column("Maximum"); + if (header[0] !== "Setting" && header[0] !== "Environment") + throw new Error( + `## ${title} must name each limit in a Setting or Environment column`, + ); + for ( + index += 1; + index < lines.length && lines[index].startsWith("|"); + index += 1 + ) { + const cells = tableCells(lines[index]); + if (separatorRow(cells)) continue; + const name = cells[0]?.replaceAll("`", "") ?? ""; + if (name.length === 0) + throw new Error(`## ${title} has a row without a limit name`); + rows.push({ + name, + section: title, + defaultCell: cells[defaultColumn] ?? "", + floorCell: cells[floorColumn] ?? "", + maximumCell: cells[maximumColumn] ?? "", + }); + } + if (!rows.some((row) => row.section === title)) + throw new Error(`## ${title} table has no limit rows`); + } + return rows; +}; + +/** + * A documented cell is one complete integer, optional prose after whitespace, + * `unset` (null), or one exported constant. A fraction is not that integer. + * + * @param {string} cell + * @param {Readonly>} names + * @returns {{ ok: true, value: number | null } | { ok: false, reason: string }} + */ +export const documentedLimitCell = (cell, names) => { + const text = cell.trim(); + if (/^unset\b/iu.test(text)) return { ok: true, value: null }; + const named = /^`([^`]+)`$/u.exec(text); + if (named) { + if (!Object.hasOwn(names, named[1])) + return { ok: false, reason: `unknown constant ${named[1]}` }; + return { ok: true, value: names[named[1]] }; + } + const integer = /^(\d+)(?=\s|$)/u.exec(text); + if (!integer) + return { ok: false, reason: `unreadable cell ${JSON.stringify(text)}` }; + return { ok: true, value: Number(integer[1]) }; +}; + +const showLimitValue = (value) => (value === null ? "unset" : String(value)); + +/** + * Compare one inventory row with the bound the code exports. + * Each failure names the limit and both values. + * + * @param {readonly { + * readonly name: string, + * readonly section: string, + * readonly defaultCell: string, + * readonly floorCell: string, + * readonly maximumCell: string, + * }[]} rows + * @param {readonly { + * readonly name: string, + * readonly aliases?: readonly string[], + * readonly defaultValue: number | null, + * readonly minimum: number, + * readonly maximum: number, + * }[]} bounds + * @param {Readonly>} names + * @returns {string[]} + */ +export const compareDocumentedNumericLimits = (rows, bounds, names) => { + const failures = []; + const byName = new Map(); + for (const bound of bounds) { + for (const name of [bound.name, ...(bound.aliases ?? [])]) { + if (byName.has(name)) + failures.push(`${name}: code exports more than one bound`); + byName.set(name, bound); + } + } + const seen = new Set(); + const seenNames = new Set(); + for (const row of rows) { + if (seenNames.has(row.name)) + failures.push(`${row.name}: documented more than once`); + seenNames.add(row.name); + const bound = byName.get(row.name); + if (bound === undefined) { + failures.push( + `${row.name}: documented ${row.section} default ${JSON.stringify(row.defaultCell)}, floor ${JSON.stringify(row.floorCell)}, maximum ${JSON.stringify(row.maximumCell)}, but code exports no bound`, + ); + continue; + } + seen.add(bound); + for (const [field, cell, codeValue] of [ + ["default", row.defaultCell, bound.defaultValue], + ["floor", row.floorCell, bound.minimum], + ["maximum", row.maximumCell, bound.maximum], + ]) { + const documented = documentedLimitCell(cell, names); + if (!documented.ok) { + failures.push( + `${row.name} ${field}: documented ${JSON.stringify(cell)} (${documented.reason}), code ${showLimitValue(codeValue)}`, + ); + continue; + } + if (documented.value !== codeValue) + failures.push( + `${row.name} ${field}: documented ${showLimitValue(documented.value)}, code ${showLimitValue(codeValue)}`, + ); + } + } + for (const bound of bounds) { + if (seen.has(bound)) continue; + const label = + bound.aliases !== undefined && bound.aliases.length > 0 + ? `${bound.name} (${bound.aliases.join(", ")})` + : bound.name; + failures.push( + `${label}: code exports default ${showLimitValue(bound.defaultValue)}, floor ${showLimitValue(bound.minimum)}, maximum ${showLimitValue(bound.maximum)}, but docs/design/rea-limit-inventory.md has no row`, + ); + } + return failures; +}; + +const exportedNumber = (module, name) => { + const value = module[name]; + if (typeof value !== "number") + throw new Error(`${name} is not an exported number`); + return value; +}; + +const bound = (name, defaultValue, minimum, maximum, aliases = []) => ({ + name, + ...(aliases.length === 0 ? {} : { aliases }), + defaultValue, + minimum, + maximum, +}); + +/** Analysis-setting registry bounds, including each REA_ environment alias. */ +const analysisSettingBounds = (settings) => { + const bounds = []; + for (const [id, definition] of Object.entries(settings)) { + if ( + (typeof definition.defaultValue !== "number" && + definition.defaultValue !== null) || + typeof definition.minimum !== "number" || + typeof definition.maximum !== "number" + ) + throw new Error( + `${id} does not export a numeric default, floor, and maximum`, + ); + bounds.push( + bound( + id, + definition.defaultValue, + definition.minimum, + definition.maximum, + typeof definition.environment === "string" + ? [definition.environment] + : [], + ), + ); + } + return bounds; +}; + +/** One MCP startup phase, using the value resolveMcpStartupBudgets ships. */ +const phaseBound = (budget) => { + if (budget.source !== "default") + throw new Error(`${budget.setting} unset resolution was not the default`); + return bound( + budget.setting, + budget.defaultMilliseconds, + budget.floorMilliseconds, + budget.maximumMilliseconds, + ); +}; + +/** Restart-only bounds from the constants each owner parser enforces. */ +const restartOnlyBounds = (owners) => { + const phases = owners.mcpBudgets.resolveMcpStartupBudgets({}); + const reconnectSeconds = exportedNumber( + owners.hopperSession, + "HOPPER_SHUTDOWN_TIMEOUT_MS", + ); + if (reconnectSeconds % 1000 !== 0) + throw new Error( + "HOPPER_SHUTDOWN_TIMEOUT_MS is not a whole number of seconds", + ); + const seconds = reconnectSeconds / 1000; + const restart = [ + bound( + "REA_DEBUGGER_MAX_PENDING_COMMANDS", + exportedNumber(owners.limits, "DEFAULT_DEBUGGER_MAX_PENDING_COMMANDS"), + exportedNumber(owners.limits, "MINIMUM_DEBUGGER_MAX_PENDING_COMMANDS"), + exportedNumber(owners.limits, "MAXIMUM_DEBUGGER_MAX_PENDING_COMMANDS"), + ), + bound( + "REA_DEBUGGER_MAX_SESSIONS", + exportedNumber(owners.limits, "DEFAULT_DEBUGGER_MAX_SESSIONS"), + exportedNumber(owners.limits, "MINIMUM_DEBUGGER_MAX_SESSIONS"), + exportedNumber(owners.limits, "MAXIMUM_DEBUGGER_MAX_SESSIONS"), + ), + bound( + "REA_HOPPER_DEMO_DIALOG_TIMEOUT_MS", + exportedNumber( + owners.hopperStartup, + "DEFAULT_HOPPER_DEMO_DIALOG_TIMEOUT_MS", + ), + exportedNumber( + owners.hopperStartup, + "MINIMUM_HOPPER_DEMO_DIALOG_TIMEOUT_MS", + ), + exportedNumber(owners.limits, "MAX_NODE_TIMER_DELAY_MS"), + ), + bound( + "REA_JADX_ACTIVE_PROCESSOR_COUNT", + owners.jadx.JADX_JVM_DEFAULT, + exportedNumber(owners.jadx, "JADX_JVM_NUMERIC_MINIMUM"), + exportedNumber(owners.jadx, "JADX_ACTIVE_PROCESSOR_COUNT_MAXIMUM"), + ), + bound( + "REA_JADX_HEAP_MIB", + owners.jadx.JADX_JVM_DEFAULT, + exportedNumber(owners.jadx, "JADX_JVM_NUMERIC_MINIMUM"), + exportedNumber(owners.jadx, "JADX_HEAP_MIB_MAXIMUM"), + ), + bound( + "REA_KUNA_CACHE_MAX_BYTES", + exportedNumber(owners.kuna, "DEFAULT_KUNA_CACHE_MAX_BYTES"), + exportedNumber(owners.kuna, "MINIMUM_KUNA_CACHE_MAX_BYTES"), + exportedNumber(owners.kuna, "MAXIMUM_KUNA_CACHE_MAX_BYTES"), + ), + bound( + "REA_KUNA_JOBS", + exportedNumber(owners.kuna, "DEFAULT_KUNA_JOBS"), + exportedNumber(owners.kuna, "MINIMUM_KUNA_JOBS"), + exportedNumber(owners.kuna, "MAXIMUM_KUNA_JOBS"), + ), + phaseBound(phases.doctor), + phaseBound(phases.firstCatalog), + phaseBound(phases.initialize), + bound( + "REA_MCP_MAX_INPUT_ELEMENTS", + exportedNumber(owners.mcpInput, "DEFAULT_MCP_MAX_INPUT_ELEMENTS"), + exportedNumber(owners.mcpInput, "MINIMUM_MCP_MAX_INPUT_ELEMENTS"), + exportedNumber(owners.mcpInput, "MAXIMUM_MCP_MAX_INPUT_ELEMENTS"), + ), + bound( + "REA_MCP_MAX_RESPONSE_BYTES", + exportedNumber(owners.sdk, "STDIO_DEFAULT_MAX_BUFFER_SIZE"), + exportedNumber(owners.mcpResponse, "MINIMUM_RESPONSE_BYTES"), + exportedNumber(owners.mcpResponse, "MAXIMUM_RESPONSE_BYTES"), + ), + phaseBound(phases.toolsList), + bound("REA_RECONNECT_TIMEOUT_SECONDS", seconds, seconds, seconds), + bound( + "REA_SWIFTC_COMPILE_TIMEOUT_MS", + exportedNumber( + owners.startupTimeout, + "DEFAULT_SWIFTC_COMPILE_TIMEOUT_MS", + ), + exportedNumber(owners.limits, "TIMER_DURATION_MINIMUM_MS"), + exportedNumber(owners.limits, "MAX_NODE_TIMER_DELAY_MS"), + ), + ]; + if (restart.some((entry) => entry.defaultValue === undefined)) + throw new Error("A restart-only bound is missing its default"); + return restart; +}; + +/** Registry entries must be the restart-only bounds, and the reverse. */ +const restartRegistryFailures = (registry, restart) => { + const names = new Set(registry.map((entry) => entry.name)); + const failures = []; + for (const name of names) { + if (!restart.some((entry) => entry.name === name)) + failures.push( + `${name}: restart-only registry entry has no exported default, floor, and maximum`, + ); + } + for (const entry of restart) { + if (!names.has(entry.name)) + failures.push( + `${entry.name}: exported restart-only bound is not in NUMERIC_LIMIT_REGISTRY`, + ); + } + return failures; +}; + +/** + * Bounds the running code exports. + * Analysis settings come from ANALYSIS_SETTINGS, which + * update_analysis_settings and inspect_analysis_settings share. + * Restart-only bounds are the constants each owner parser enforces. + * A registry name without those exports fails closed. + */ +export const loadExportedNumericLimitBounds = async () => { + const { importVerifierSource } = + await import("../lib/verifier-source-loader.mjs"); + const source = (specifier) => + importVerifierSource(specifier, import.meta.url); + const [ + settings, + limits, + registry, + hopperStartup, + hopperSession, + jadx, + kuna, + mcpBudgets, + mcpInput, + mcpResponse, + startupTimeout, + sdk, + ] = await Promise.all([ + source("../../src/domain/analysisSettingDefinitions.ts"), + source("../../src/domain/analysisResourceLimits.ts"), + source("../../src/domain/numericLimitRegistry.ts"), + source("../../src/hopper/HopperStartupFailure.ts"), + source("../../src/hopper/HopperSessionValues.ts"), + source("../../src/android/JadxConfiguration.ts"), + source("../../src/kuna/KunaConfiguration.ts"), + source("../../src/config/mcpStartupBudgets.ts"), + source("../../src/config/mcpInputBudget.ts"), + source("../../src/config/mcpResponseBudget.ts"), + source("../../src/config/providerStartupTimeout.ts"), + import("@modelcontextprotocol/server"), + ]); + const owners = { + limits, + hopperStartup, + hopperSession, + jadx, + kuna, + mcpBudgets, + mcpInput, + mcpResponse, + startupTimeout, + sdk, + }; + const restart = restartOnlyBounds(owners); + return { + bounds: [...analysisSettingBounds(settings.ANALYSIS_SETTINGS), ...restart], + names: { + "Number.MAX_SAFE_INTEGER": Number.MAX_SAFE_INTEGER, + MAX_GHIDRA_DECOMPILE_TIMEOUT_SECONDS: exportedNumber( + limits, + "MAX_GHIDRA_DECOMPILE_TIMEOUT_SECONDS", + ), + }, + failures: restartRegistryFailures(registry.NUMERIC_LIMIT_REGISTRY, restart), + }; +}; + const direct = process.argv[1] !== undefined && import.meta.url === pathToFileURL(resolve(process.argv[1])).href; @@ -1029,6 +1440,41 @@ if (direct) { failures.push(`${relativePath} must report update_mode parameter`); } + // The permission fixture copies this file into a tree with no package.json. + // A REA checkout always compares the inventory. A missing inventory here fails. + let checkout = false; + try { + checkout = + JSON.parse(await readFile(join(root, "package.json"), "utf8")).name === + "rea-agents"; + } catch (cause) { + if (cause?.code !== "ENOENT") throw cause; + } + if (checkout) { + try { + const inventory = await readFile( + join(root, "docs/design/rea-limit-inventory.md"), + "utf8", + ); + const exported = await loadExportedNumericLimitBounds(); + failures.push( + ...exported.failures, + ...compareDocumentedNumericLimits( + parseDocumentedNumericLimits(inventory), + exported.bounds, + exported.names, + ), + ); + } catch (cause) { + failures.push( + `documented limit values could not be checked: ${cause instanceof Error ? cause.message : String(cause)}`, + ); + } + } else + console.log( + "Documented limit values skipped: this copy is not the REA checkout.", + ); + if (failures.length > 0) { console.error(`Numeric REA_ limit check failed:\n${failures.join("\n")}`); process.exit(1); diff --git a/src/android/JadxConfiguration.ts b/src/android/JadxConfiguration.ts index f7a063c54d..2dd9121379 100644 --- a/src/android/JadxConfiguration.ts +++ b/src/android/JadxConfiguration.ts @@ -693,8 +693,35 @@ const requireJavaHomeExecutable = async ( } }; +/** Smallest heap MiB or processor count. Zero is neither a heap size nor a count. */ +export const JADX_JVM_NUMERIC_MINIMUM = 1; + +/** + * Omitted `REA_JADX_HEAP_MIB` and `REA_JADX_ACTIVE_PROCESSOR_COUNT` pass no + * flag, so the JVM keeps its own default. + */ +export const JADX_JVM_DEFAULT = null; + +/** Heap MiB must be an exact safe integer. A larger flag cannot round-trip. */ +export const JADX_HEAP_MIB_MAXIMUM = Number.MAX_SAFE_INTEGER; + /** `-XX:ActiveProcessorCount` is a Java `int`; this is a count, not a duration. */ -const JAVA_INT_MAX = 2_147_483_647; +export const JADX_ACTIVE_PROCESSOR_COUNT_MAXIMUM = 2_147_483_647; + +const jadxJvmBounds = ( + name: "REA_JADX_HEAP_MIB" | "REA_JADX_ACTIVE_PROCESSOR_COUNT", +) => + name === "REA_JADX_HEAP_MIB" + ? { + defaultValue: JADX_JVM_DEFAULT, + minimum: JADX_JVM_NUMERIC_MINIMUM, + maximum: JADX_HEAP_MIB_MAXIMUM, + } + : { + defaultValue: JADX_JVM_DEFAULT, + minimum: JADX_JVM_NUMERIC_MINIMUM, + maximum: JADX_ACTIVE_PROCESSOR_COUNT_MAXIMUM, + }; const resolveJvmArguments = ( environment: Readonly>, @@ -704,26 +731,32 @@ const resolveJvmArguments = ( ["REA_JADX_HEAP_MIB", "-Xmx", "m"], ["REA_JADX_ACTIVE_PROCESSOR_COUNT", "-XX:ActiveProcessorCount=", ""], ] as const) { - const value = environment[name]; - if (value === undefined) continue; - if (!/^[1-9]\d*$/u.test(value) || !Number.isSafeInteger(Number(value))) + const bounds = jadxJvmBounds(name); + const selected = + environment[name] ?? + (bounds.defaultValue === null ? undefined : String(bounds.defaultValue)); + if (selected === undefined) continue; + const parsed = + /^[1-9]\d*$/u.test(selected) && Number.isSafeInteger(Number(selected)) + ? Number(selected) + : undefined; + if (parsed === undefined || parsed < bounds.minimum) throw configurationFailure( "open_options_invalid", - `${name} must be a positive safe integer; received ${value}.`, - { setting: name, value }, + `${name} must be a positive safe integer; received ${selected}.`, + { setting: name, value: selected }, "jvm_options", ); - if ( - name === "REA_JADX_ACTIVE_PROCESSOR_COUNT" && - Number(value) > JAVA_INT_MAX - ) + if (parsed > bounds.maximum) throw configurationFailure( "open_options_invalid", - `${name} exceeds the JVM's signed 32-bit processor-count range.`, - { setting: name, value }, + name === "REA_JADX_ACTIVE_PROCESSOR_COUNT" + ? `${name} exceeds the JVM's signed 32-bit processor-count range.` + : `${name} must be a positive safe integer; received ${selected}.`, + { setting: name, value: selected }, "jvm_options", ); - result.push(`${prefix}${value}${suffix}`); + result.push(`${prefix}${selected}${suffix}`); } return result; }; diff --git a/src/config/bridgeMaxRequestBytes.test.ts b/src/config/bridgeMaxRequestBytes.test.ts index c0ef5a8e39..2a17814700 100644 --- a/src/config/bridgeMaxRequestBytes.test.ts +++ b/src/config/bridgeMaxRequestBytes.test.ts @@ -74,7 +74,6 @@ it("sets the maximum to the serialized string bound minus the framing LF", () => const stringCeiling = 536_870_888; const hundredMib = 100 * 1024 * 1024; expect(MAXIMUM_BRIDGE_MAX_REQUEST_BYTES).toBe(stringCeiling - 1); - expect(MAXIMUM_BRIDGE_MAX_REQUEST_BYTES).toBe(536_870_887); expect(hundredMib).toBeLessThan(MAXIMUM_BRIDGE_MAX_REQUEST_BYTES); const parsed = parseConfig({ [BRIDGE_MAX_REQUEST_BYTES_SETTING]: String(hundredMib), diff --git a/src/config/hopperCallerScanBudget.test.ts b/src/config/hopperCallerScanBudget.test.ts index 338d5c3561..68a7b4d466 100644 --- a/src/config/hopperCallerScanBudget.test.ts +++ b/src/config/hopperCallerScanBudget.test.ts @@ -91,7 +91,6 @@ it("explains the time budget and that fixed byte allowances have no override", ( expect(deadline).toContain(`maximum ${String(MAX_NODE_TIMER_DELAY_MS)} ms`); expect(deadline).toContain("update_analysis_settings"); expect(deadline).toContain(HOPPER_CALLER_SCAN_BUDGET_SETTING); - expect(DEFAULT_HOPPER_CALLER_SCAN_BUDGET_MS).toBe(2000); const page = hopperCallerScanRecovery( facts({ stop: { diff --git a/src/config/mcpInputBudget.ts b/src/config/mcpInputBudget.ts index 4a417ad703..ee06fea5ce 100644 --- a/src/config/mcpInputBudget.ts +++ b/src/config/mcpInputBudget.ts @@ -11,12 +11,18 @@ import { err, ok, type Result } from "../domain/result.js"; */ export const DEFAULT_MCP_MAX_INPUT_ELEMENTS = 1_024; +/** One element is the smallest admission that still accepts a call. */ +export const MINIMUM_MCP_MAX_INPUT_ELEMENTS = 1; + +/** Combined elements and members must stay exactly representable. */ +export const MAXIMUM_MCP_MAX_INPUT_ELEMENTS = Number.MAX_SAFE_INTEGER; + const setting = "REA_MCP_MAX_INPUT_ELEMENTS"; const constraint = `${setting} must be a positive decimal safe integer counting combined array elements and object members; the default is ${String(DEFAULT_MCP_MAX_INPUT_ELEMENTS)}.`; export const mcpInputBudgetSchema = positiveDecimalIntegerSchema( - 1, - Number.MAX_SAFE_INTEGER, + MINIMUM_MCP_MAX_INPUT_ELEMENTS, + MAXIMUM_MCP_MAX_INPUT_ELEMENTS, constraint, ); diff --git a/src/config/mcpResponseBudget.ts b/src/config/mcpResponseBudget.ts index 1ca63f81ec..2b430cb1f4 100644 --- a/src/config/mcpResponseBudget.ts +++ b/src/config/mcpResponseBudget.ts @@ -8,6 +8,9 @@ import { err, ok, type Result } from "../domain/result.js"; // this floor against the pinned SDK's actual default receive-buffer size. export const MINIMUM_RESPONSE_BYTES = 10 * 1024 * 1024; +/** `z.int().safe()` refuses a receive buffer that is not an exact integer. */ +export const MAXIMUM_RESPONSE_BYTES = Number.MAX_SAFE_INTEGER; + /** * Facts for a completed or failed MCP result that exceeded the stdio receive * budget. The effective value is the configured receive buffer, including the @@ -37,7 +40,7 @@ export const mcpResponseBudgetSchema = z .string() .regex(/^[1-9]\d*$/u) .transform(Number) - .pipe(z.int().safe().min(MINIMUM_RESPONSE_BYTES)); + .pipe(z.int().safe().min(MINIMUM_RESPONSE_BYTES).max(MAXIMUM_RESPONSE_BYTES)); const budgetConstraint = `REA_MCP_MAX_RESPONSE_BYTES must be a decimal safe integer at least ${String(MINIMUM_RESPONSE_BYTES)} bytes, the default stdio receive-buffer size.`; diff --git a/src/config/nativeMatchingAllowance.test.ts b/src/config/nativeMatchingAllowance.test.ts index cb296ee11f..e500b471b2 100644 --- a/src/config/nativeMatchingAllowance.test.ts +++ b/src/config/nativeMatchingAllowance.test.ts @@ -11,17 +11,19 @@ import { import { launchAnalysisSetting } from "./analysisSettings.js"; import { explicitSetupRegistrationEnvironment } from "../application/SetupRegistrationEnvironment.js"; -it("keeps the 96 MiB allowance when the launch setting is unset", () => { +it("keeps the shipped allowance when the launch setting is unset", () => { expect(parseNativeMatchingAllowance({})).toEqual({ ok: true, value: DEFAULT_NATIVE_MATCHING_ALLOWANCE, }); - expect(DEFAULT_NATIVE_MATCHING_ALLOWANCE.maximumBytes).toBe(96 * 1024 * 1024); expect( launchAnalysisSetting("native.matching_representation_bytes", {}), ).toEqual({ ok: true, - value: { value: 96 * 1024 * 1024, source: "default" }, + value: { + value: DEFAULT_NATIVE_MATCHING_ALLOWANCE.maximumBytes, + source: "default", + }, }); }); diff --git a/src/config/pwntoolsInputLimit.test.ts b/src/config/pwntoolsInputLimit.test.ts index 9efe240fae..460cb1881e 100644 --- a/src/config/pwntoolsInputLimit.test.ts +++ b/src/config/pwntoolsInputLimit.test.ts @@ -16,7 +16,6 @@ describe("pwntools input bound", () => { bytes: PWNTOOLS_LIMITS.input_bytes, source: "default", }); - expect(PWNTOOLS_LIMITS.input_bytes).toBe(32 * 1024 * 1024); }); it.each([ diff --git a/src/config/pwntoolsInputLimit.ts b/src/config/pwntoolsInputLimit.ts index b8efb2cb82..9bd7433164 100644 --- a/src/config/pwntoolsInputLimit.ts +++ b/src/config/pwntoolsInputLimit.ts @@ -1,23 +1,23 @@ import { z } from "zod"; +import { MAXIMUM_PWNTOOLS_MAX_INPUT_BYTES } from "../domain/analysisResourceLimits.js"; import { currentAnalysisOperationSnapshot } from "../domain/analysisOperationSnapshot.js"; import { PWNTOOLS_LIMITS } from "../domain/native/pwntoolsResourceLimits.js"; // The artifact is read into one in-memory buffer and staged again as a private // snapshot before the owned bridge parses it under a 3 GiB address-space // reservation, so an override stays within a third of that reservation. -const MAXIMUM_INPUT_BYTES = 1024 * 1024 * 1024; /** Optional caller-supplied input bound, in bytes, without a decimal point. */ export const pwntoolsInputBytesSchema = z .string() .regex(/^[1-9]\d*$/u, "must be a positive decimal integer") .transform(Number) - .pipe(z.int().safe().max(MAXIMUM_INPUT_BYTES)); + .pipe(z.int().safe().max(MAXIMUM_PWNTOOLS_MAX_INPUT_BYTES)); const CONSTRAINT = `REA_PWNTOOLS_MAX_INPUT_BYTES must be a decimal integer from 1 to ` + - `${String(MAXIMUM_INPUT_BYTES)} bytes, and REA never installs Python or packages.`; + `${String(MAXIMUM_PWNTOOLS_MAX_INPUT_BYTES)} bytes, and REA never installs Python or packages.`; /** Resolved input bound, or the reason the caller's override cannot be used. */ export type PwntoolsInputBytes = diff --git a/src/config/regexWorkerHeapRequest.test.ts b/src/config/regexWorkerHeapRequest.test.ts index e5fa9c411b..1f29c67e4a 100644 --- a/src/config/regexWorkerHeapRequest.test.ts +++ b/src/config/regexWorkerHeapRequest.test.ts @@ -85,7 +85,6 @@ it("keeps the 128 MiB request when the setting is unset", () => { }); it("uses a valid REA_REGEX_WORKER_HEAP_REQUEST_MIB override", () => { - expect(MINIMUM_REGEX_WORKER_HEAP_REQUEST_MIB).toBe(7); expect( parseRegexWorkerHeapRequest(String(MINIMUM_REGEX_WORKER_HEAP_REQUEST_MIB)), ).toEqual({ diff --git a/src/domain/analysisResourceLimits.ts b/src/domain/analysisResourceLimits.ts index 139db98f32..e1ee233141 100644 --- a/src/domain/analysisResourceLimits.ts +++ b/src/domain/analysisResourceLimits.ts @@ -98,13 +98,19 @@ export const deadlineParameterLimit = ( applies_at: "next_call", }); +/** + * Smallest positive delay Node schedules. Zero is not a deadline. + * `timerDurationMsSchema` and restart-only millisecond limits share this floor. + */ +export const TIMER_DURATION_MINIMUM_MS = 1; + /** * A positive whole-millisecond duration Node can schedule exactly. Zero and * negative values are not a deadline. */ export const timerDurationMsSchema = z .int() - .min(1) + .min(TIMER_DURATION_MINIMUM_MS) .max(MAX_NODE_TIMER_DELAY_MS); /** diff --git a/src/domain/native/nativeDeadlines.test.ts b/src/domain/native/nativeDeadlines.test.ts index 50afae3354..2b5e997d61 100644 --- a/src/domain/native/nativeDeadlines.test.ts +++ b/src/domain/native/nativeDeadlines.test.ts @@ -15,7 +15,6 @@ it("keeps today's omitted native deadlines and the shared timer range", () => { expect(DEFAULT_NATIVE_COMMAND_TIMEOUT_MS).toBe(60_000); expect(DEFAULT_NATIVE_UI_DEADLINE_MS).toBe(180_000); expect(DEFAULT_PWNTOOLS_TIMEOUT_MS).toBe(30_000); - expect(MAX_NODE_TIMER_DELAY_MS).toBe(2_147_483_647); for (const field of [ nativeCommandTimeoutField, nativeUiDeadlineField, diff --git a/src/domain/native/pwntoolsResourceLimits.ts b/src/domain/native/pwntoolsResourceLimits.ts index 79d1038b69..26a8fb73b0 100644 --- a/src/domain/native/pwntoolsResourceLimits.ts +++ b/src/domain/native/pwntoolsResourceLimits.ts @@ -1,5 +1,5 @@ +import { DEFAULT_PWNTOOLS_MAX_INPUT_BYTES } from "../analysisResourceLimits.js"; import { - BOUNDED_PRODUCER_LIMITS, producerResourceLimitsSchema, resolveProducerLimits, } from "../producerResourceLimits.js"; @@ -8,7 +8,7 @@ import { DEFAULT_PWNTOOLS_TIMEOUT_MS } from "./nativeDeadlines.js"; /** Owned Python defaults; the bridge consumes these accepted values from its request. */ export const PWNTOOLS_LIMITS = { - input_bytes: BOUNDED_PRODUCER_LIMITS.input_bytes, + input_bytes: DEFAULT_PWNTOOLS_MAX_INPUT_BYTES, output_bytes: 64 * 1024 * 1024, diagnostic_bytes: 1024 * 1024, command_timeout_ms: DEFAULT_PWNTOOLS_TIMEOUT_MS, diff --git a/src/domain/numericLimitRegistry.ts b/src/domain/numericLimitRegistry.ts index 7db3abb84c..fb1d481c85 100644 --- a/src/domain/numericLimitRegistry.ts +++ b/src/domain/numericLimitRegistry.ts @@ -8,7 +8,8 @@ * checked on each call belong in `ANALYSIS_SETTINGS` instead of this list. * * Narrative bounds, owners, and the non-numeric settings live in - * `docs/design/rea-limit-inventory.md`. + * `docs/design/rea-limit-inventory.md`. That same script compares each + * documented default, floor, and maximum with the exported value. */ export interface NumericLimitRegistryEntry { readonly name: string; diff --git a/src/kuna/KunaConfiguration.ts b/src/kuna/KunaConfiguration.ts index 1c960bbd47..a396e316da 100644 --- a/src/kuna/KunaConfiguration.ts +++ b/src/kuna/KunaConfiguration.ts @@ -1,4 +1,8 @@ -import { MAX_NODE_TIMER_DELAY_MS } from "../domain/analysisResourceLimits.js"; +import { + DEFAULT_KUNA_FUNCTION_TIMEOUT_MS, + DEFAULT_KUNA_PROJECT_TIMEOUT_MS, + MAX_NODE_TIMER_DELAY_MS, +} from "../domain/analysisResourceLimits.js"; import { isAbsolute } from "node:path"; import { ConfigurationError } from "../domain/configurationErrors.js"; @@ -13,30 +17,26 @@ import { } from "./KunaRelease.js"; /** Kuna caps its own decode lanes and worker pool at 32. */ -const MAX_KUNA_JOBS = 32; +export const MAXIMUM_KUNA_JOBS = 32; -/** - * A 1.4 MB sqlite3 shell exported serially in 66-108 s on Apple M-series and - * Linux hosts; thirty minutes admits images an order of magnitude larger - * without an unbounded run. Larger images need a raised deadline or more jobs. - */ -const DEFAULT_PROJECT_TIMEOUT_MS = 30 * 60 * 1000; - -/** One function decompiles in well under a second; sqlite3VdbeExec (42 KB) took 15-25 s. */ -const DEFAULT_FUNCTION_TIMEOUT_MS = 120_000; +/** One job is the serial reference export. Zero is not a pool. */ +export const MINIMUM_KUNA_JOBS = 1; /** * A serial (`--jobs 1`) export is Kuna's reference answer: it decompiles * callees before callers, which recovers prototypes that parallel workers * cannot. Measured on coreutils sort, 40-60% of functions differ otherwise. */ -const DEFAULT_JOBS = 1; +export const DEFAULT_KUNA_JOBS = MINIMUM_KUNA_JOBS; /** Measured sqlite3 exports occupy ~25 MiB; four GiB retains many projects. */ -const DEFAULT_CACHE_MAX_BYTES = 4 * 1024 ** 3; +export const DEFAULT_KUNA_CACHE_MAX_BYTES = 4 * 1024 ** 3; /** One project needs its .c, .h, .asm, inventory and manifest; refuse smaller caps. */ -const MIN_CACHE_MAX_BYTES = 1024 ** 2; +export const MINIMUM_KUNA_CACHE_MAX_BYTES = 1024 ** 2; + +/** Cache accounting must remain exactly representable. */ +export const MAXIMUM_KUNA_CACHE_MAX_BYTES = Number.MAX_SAFE_INTEGER; /** Caller-selected Kuna installation and REA-owned project cache policy. */ export interface KunaConfiguration { @@ -206,12 +206,16 @@ export const readKunaConfiguration = ( const rawMaxBytes = environment.REA_KUNA_CACHE_MAX_BYTES; const cacheMaxBytes = rawMaxBytes === undefined - ? DEFAULT_CACHE_MAX_BYTES + ? DEFAULT_KUNA_CACHE_MAX_BYTES : positiveInteger(rawMaxBytes); - if (cacheMaxBytes === undefined || cacheMaxBytes < MIN_CACHE_MAX_BYTES) + if ( + cacheMaxBytes === undefined || + cacheMaxBytes < MINIMUM_KUNA_CACHE_MAX_BYTES || + cacheMaxBytes > MAXIMUM_KUNA_CACHE_MAX_BYTES + ) return failure( "open_options_invalid", - `REA_KUNA_CACHE_MAX_BYTES must be a decimal byte count of at least ${String(MIN_CACHE_MAX_BYTES)}; received ${String(rawMaxBytes)}.`, + `REA_KUNA_CACHE_MAX_BYTES must be a decimal byte count of at least ${String(MINIMUM_KUNA_CACHE_MAX_BYTES)}; received ${String(rawMaxBytes)}.`, "REA_KUNA_CACHE_MAX_BYTES", ); @@ -219,7 +223,7 @@ export const readKunaConfiguration = ( const projectTimeout = configuredTimeout( environment.REA_KUNA_PROJECT_TIMEOUT_MS, "REA_KUNA_PROJECT_TIMEOUT_MS", - DEFAULT_PROJECT_TIMEOUT_MS, + DEFAULT_KUNA_PROJECT_TIMEOUT_MS, ); if (!projectTimeout.ok) return projectTimeout; if (overrides?.["kuna.project_timeout_ms"] === undefined) { @@ -233,7 +237,7 @@ export const readKunaConfiguration = ( const functionTimeout = configuredTimeout( environment.REA_KUNA_TIMEOUT_MS, "REA_KUNA_TIMEOUT_MS", - DEFAULT_FUNCTION_TIMEOUT_MS, + DEFAULT_KUNA_FUNCTION_TIMEOUT_MS, ); if (!functionTimeout.ok) return functionTimeout; if (overrides?.["kuna.function_timeout_ms"] === undefined) { @@ -246,11 +250,16 @@ export const readKunaConfiguration = ( } const rawJobs = environment.REA_KUNA_JOBS; - const jobs = rawJobs === undefined ? DEFAULT_JOBS : positiveInteger(rawJobs); - if (jobs === undefined || jobs > MAX_KUNA_JOBS) + const jobs = + rawJobs === undefined ? DEFAULT_KUNA_JOBS : positiveInteger(rawJobs); + if ( + jobs === undefined || + jobs < MINIMUM_KUNA_JOBS || + jobs > MAXIMUM_KUNA_JOBS + ) return failure( "open_options_invalid", - `REA_KUNA_JOBS must be an integer from 1 to ${String(MAX_KUNA_JOBS)}; received ${String(rawJobs)}.`, + `REA_KUNA_JOBS must be an integer from ${String(MINIMUM_KUNA_JOBS)} to ${String(MAXIMUM_KUNA_JOBS)}; received ${String(rawJobs)}.`, "REA_KUNA_JOBS", ); diff --git a/tests/boundary/filesystem/asarHeaderAdmission.test.ts b/tests/boundary/filesystem/asarHeaderAdmission.test.ts index 9f9e5ed9f8..098473f2b3 100644 --- a/tests/boundary/filesystem/asarHeaderAdmission.test.ts +++ b/tests/boundary/filesystem/asarHeaderAdmission.test.ts @@ -123,7 +123,6 @@ it("rejects contradictory and unsigned-boundary extents before decoding", async it("separates the header decode budget from container validity at its exact boundary", async () => { const root = await createTestTempDirectory("rea-asar-header-budget-"); const archive = join(root, "budget.asar"); - expect(DEFAULT_ASAR_MAX_HEADER_BYTES).toBe(16 * 1024 * 1024); for (const headerBytes of [ DEFAULT_ASAR_MAX_HEADER_BYTES, DEFAULT_ASAR_MAX_HEADER_BYTES + 4, diff --git a/tests/boundary/mcp/mcpStartupPolicy.test.ts b/tests/boundary/mcp/mcpStartupPolicy.test.ts index 1aba1c5e05..80a8e94ea3 100644 --- a/tests/boundary/mcp/mcpStartupPolicy.test.ts +++ b/tests/boundary/mcp/mcpStartupPolicy.test.ts @@ -28,8 +28,6 @@ const errorMessage = (cause: unknown): string => const expectPhaseText = (text: string, budget: McpPhaseBudget) => { expect(text).toContain(mcpPhaseBudgetRecovery(budget)); - expect(budget.floorMilliseconds).toBe(1); - expect(budget.maximumMilliseconds).toBe(2_147_483_647); expect(text).toContain(budget.setting); expect(text).toContain(budget.phase); expect(text).toContain(`${String(budget.milliseconds)} ms`); @@ -59,10 +57,6 @@ describe("MCP startup policy", () => { it("names phase budget settings without turning Codex's 30s into a REA knob", () => { const budgets = resolveMcpStartupBudgets({}); expect(MCP_STARTUP_POLICY.codexStartupTimeoutSeconds).toBe(30); - expect(budgets.initialize.milliseconds).toBe(15_000); - expect(budgets.toolsList.milliseconds).toBe(5_000); - expect(budgets.firstCatalog.milliseconds).toBe(20_000); - expect(budgets.doctor.milliseconds).toBe(30_000); const initialize = mcpPhaseBudgetRecovery(budgets.initialize); expectPhaseText(initialize, budgets.initialize); expectPhaseText( diff --git a/tests/conformance/contracts/mcpResponseBudget.test.ts b/tests/conformance/contracts/mcpResponseBudget.test.ts index 75c144f02f..616f6ef497 100644 --- a/tests/conformance/contracts/mcpResponseBudget.test.ts +++ b/tests/conformance/contracts/mcpResponseBudget.test.ts @@ -2,7 +2,6 @@ import { describe, expect, it } from "vitest"; import { STDIO_DEFAULT_MAX_BUFFER_SIZE } from "@modelcontextprotocol/server"; import { - MINIMUM_RESPONSE_BYTES, nodeStringCeilingRecovery, parseMcpResponseBudget, stdioResponseBudgetRecovery, @@ -19,7 +18,6 @@ describe("MCP response budget configuration", () => { }); it("names the effective stdio budget without claiming it raises the string ceiling", () => { - expect(MINIMUM_RESPONSE_BYTES).toBe(10_485_760); const reserved = 536_869_864; const nodeCeiling = 536_870_888; const recovery = stdioResponseBudgetRecovery( diff --git a/tests/evaluation/numericLimitCheck.test.ts b/tests/evaluation/numericLimitCheck.test.ts index f3a7c5c086..f96fd9b9f8 100644 --- a/tests/evaluation/numericLimitCheck.test.ts +++ b/tests/evaluation/numericLimitCheck.test.ts @@ -1,6 +1,11 @@ import { expect, it } from "vitest"; +import { readFile } from "node:fs/promises"; import { + compareDocumentedNumericLimits, discoverNumericLimitUses, + documentedLimitCell, + loadExportedNumericLimitBounds, + parseDocumentedNumericLimits, parseNumericLimitRegistry, parseRuntimeSettingEnvironments, requiredRuntimeLimitFailure, @@ -538,3 +543,115 @@ it("reports a required limit absent from src as a typed missing result", () => { }), ).toBeUndefined(); }); + +const documentedLimits = ` +## Runtime analysis settings + +| Setting | Default | Floor | Maximum | +| --- | --- | --- | --- | +| \`sample.bytes\` | 10 | 1 | 20 | + +## Per-call limits in the runtime system + +| Environment | Default | Floor | Maximum | +| --- | --- | --- | --- | +| \`REA_SAMPLE_BYTES\` | unset (\`null\`, none) | 1 | \`Number.MAX_SAFE_INTEGER\` | + +## Restart-only numeric limits + +| Environment | Default | Floor | Maximum | +| --- | --- | --- | --- | +| \`REA_FIXED\` | 30 | 30 | 30 | +`; + +it("rejects a fractional documented cell instead of keeping its leading digits", () => { + expect(documentedLimitCell("5000.5", {}).ok).toBe(false); + expect(documentedLimitCell("5000.", {}).ok).toBe(false); + expect(documentedLimitCell("60000 (MCP SDK default)", {})).toEqual({ + ok: true, + value: 60_000, + }); + expect(documentedLimitCell("10485760 when unset", {})).toEqual({ + ok: true, + value: 10_485_760, + }); + const rows = parseDocumentedNumericLimits( + documentedLimits.replace( + "| `sample.bytes` | 10 |", + "| `sample.bytes` | 5000.5 |", + ), + ); + const failures = compareDocumentedNumericLimits( + rows, + [ + { name: "sample.bytes", defaultValue: 5000, minimum: 1, maximum: 20 }, + { + name: "sample.launch", + aliases: ["REA_SAMPLE_BYTES"], + defaultValue: null, + minimum: 1, + maximum: Number.MAX_SAFE_INTEGER, + }, + { name: "REA_FIXED", defaultValue: 30, minimum: 30, maximum: 30 }, + ], + { "Number.MAX_SAFE_INTEGER": Number.MAX_SAFE_INTEGER }, + ); + expect(failures).toEqual([ + 'sample.bytes default: documented "5000.5" (unreadable cell "5000.5"), code 5000', + ]); +}); + +it("names the limit and both values when a documented default drifts", () => { + const failures = compareDocumentedNumericLimits( + parseDocumentedNumericLimits(documentedLimits), + [ + { name: "sample.bytes", defaultValue: 11, minimum: 1, maximum: 20 }, + { + name: "sample.launch", + aliases: ["REA_SAMPLE_BYTES"], + defaultValue: null, + minimum: 1, + maximum: Number.MAX_SAFE_INTEGER, + }, + { name: "REA_FIXED", defaultValue: 30, minimum: 30, maximum: 30 }, + ], + { "Number.MAX_SAFE_INTEGER": Number.MAX_SAFE_INTEGER }, + ); + expect(failures).toEqual(["sample.bytes default: documented 10, code 11"]); +}); + +it("names a documented limit the code does not export", () => { + const failures = compareDocumentedNumericLimits( + parseDocumentedNumericLimits(documentedLimits), + [ + { name: "sample.bytes", defaultValue: 10, minimum: 1, maximum: 20 }, + { + name: "sample.launch", + aliases: ["REA_SAMPLE_BYTES"], + defaultValue: null, + minimum: 1, + maximum: Number.MAX_SAFE_INTEGER, + }, + ], + { "Number.MAX_SAFE_INTEGER": Number.MAX_SAFE_INTEGER }, + ); + expect(failures).toEqual([ + 'REA_FIXED: documented Restart-only numeric limits default "30", floor "30", maximum "30", but code exports no bound', + ]); +}); + +it("matches the inventory to the exported analysis settings and owner bounds", async () => { + const inventory = await readFile( + new URL("../../docs/design/rea-limit-inventory.md", import.meta.url), + "utf8", + ); + const exported = await loadExportedNumericLimitBounds(); + expect(exported.failures).toEqual([]); + expect( + compareDocumentedNumericLimits( + parseDocumentedNumericLimits(inventory), + exported.bounds, + exported.names, + ), + ).toEqual([]); +});