test(limits): check documented limit defaults against code instead of per-file pins (#12720)

* test(limits): check documented limit defaults against code instead of per-file pins

The numeric-limit script now reads every default, floor, and maximum in
docs/design/rea-limit-inventory.md and compares it with ANALYSIS_SETTINGS
or the owner constant the parser enforces. A mismatch names the limit and
both values. Pins that only restated a covered value are removed.

Pwntools input bytes and the Kuna timeouts now use the shared exports, so
the registry value is the one the parser applies.

* fix(limits): reject a fractional documented limit cell

The cell parser treated a dot as the end of the integer, so 5000.5
compared equal to 5000. A documented number is now one complete integer,
with prose only after whitespace.

Co-authored-by: morluto <morluto@users.noreply.github.com>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: morluto <morluto@users.noreply.github.com>
This commit is contained in:
authored and GitHub committed 2026-11-19 23:05:07 -05:00
1 parent d5818ad0da
commit dc2c31e76d
21 files changed
+730 -62

No files matched your search

+5
View File
@@ -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.
+54
View File
@@ -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<Record<string, number>>,
):
| { 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<Record<string, number>>,
): 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<Record<string, number>>;
readonly failures: readonly string[];
}>;
+446
View File
@@ -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<Record<string, number>>} 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<Record<string, number>>} 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);
+46 -13
View File
@@ -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<Record<string, string | undefined>>,
@@ -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;
};
-1
View File
@@ -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),
@@ -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: {
+8 -2
View File
@@ -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,
);
+4 -1
View File
@@ -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.`;
+5 -3
View File
@@ -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",
},
});
});
-1
View File
@@ -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([
+3 -3
View File
@@ -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 =
@@ -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({
+7 -1
View File
@@ -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);
/**
@@ -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,
+2 -2
View File
@@ -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,
+2 -1
View File
@@ -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;
+31 -22
View File
@@ -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",
);
@@ -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,
@@ -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(
@@ -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(
+117
View File
@@ -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([]);
});