fix(javascript): name heap and semantic ceilings (#6022)

* fix(javascript): name heap and semantic ceilings

Refs #5910. Heap exhaustion names max_heap_mb with its effective value,
range, and next-analysis worker restart. Semantic ceiling coverage names
the four max_semantic_* arguments. Wakaru and transfer ceilings say this
release has no runtime override.

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

* fix(javascript): distinguish adjustable ceilings from fixed limits

The effective transfer file ceiling and the parent result budget follow
the CLI/MCP process heap, so recovery names NODE_OPTIONS instead of
denying an override. A provenance report over 8 MiB keeps the fixed
allowance guidance, and the Wakaru deadline says an unchanged retry may
hit it again.

Refs #5910

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

* fix(javascript): keep Bun OOM and checkpoint heap controls distinct

Bun heap-exhaustion exits no longer claim the ignored max_heap_mb V8
old-space limit. Checkpoint decode names the parent heap and Node
NODE_OPTIONS, the same control as the parent result budget.

Refs #5910

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

* fix(javascript): name semantic ceilings without claiming both were reached

Truncated semantic retention names the total and per-file controls as
effective ceilings. Callers only know that retention was truncated, so
the limitation no longer says both ceilings were reached.

Refs #5910

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

* fix(javascript): name only the semantic ceiling that stopped retention

Semantic ceiling limitations claimed both the application total and the
per-file control whenever either one truncated the graph. Record which
offered budget stopped node and unknown retention, and name only those
controls. Coverage limits still list both effective values.

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

* fix(javascript): require a value in the NODE_OPTIONS heap example

A bare --max-old-space-size is an illegal V8 flag and prevents Node from
starting. Parent-heap and transfer-ceiling recovery now share
--max-old-space-size=<MiB>, and the Kuna heap remediation uses the same
complete form.

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

* fix(javascript): limit the old-space placeholder to NODE_OPTIONS recovery

The review covers the CLI/MCP NODE_OPTIONS example and the transfer-ceiling
copy. The Kuna heap-headroom sentence stays unchanged.

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-10-22 02:44:14 +08:00
1 parent 01788bac86
commit a0214e0e0e
22 files changed
+1166 -87

No files matched your search

@@ -12,9 +12,160 @@ export const JAVASCRIPT_ANALYSIS_RESOURCE_DEFAULTS = {
semanticUnknownsPerFile: 20_000,
} as const;
/** Inclusive `max_heap_mb` range. The worker reads it only when that process starts. */
export const JAVASCRIPT_WORKER_HEAP_MIB_MINIMUM = 128;
export const JAVASCRIPT_WORKER_HEAP_MIB_MAXIMUM = 16_384;
/** Maximum caller-selected retained record capacity; heap and transfer admission still apply. */
export const JAVASCRIPT_SEMANTIC_ITEM_MAXIMUM = 1_000_000;
const HEAP_DOES_NOT_RAISE =
"Raising max_heap_mb does not raise the parent result budget, transfer record or transfer file byte ceilings, the CLI/MCP process heap, or fixed parser limits.";
/**
* Recovery for the isolated analyzer heap. A changed value applies on the next
* analysis because the V8 flag is fixed at worker launch and a different heap
* is not reused.
*/
export const javaScriptWorkerHeapRemediation = (heapMb: number): string => {
const bounds = `an integer from ${String(JAVASCRIPT_WORKER_HEAP_MIB_MINIMUM)} to ${String(JAVASCRIPT_WORKER_HEAP_MIB_MAXIMUM)} (default ${String(JAVASCRIPT_ANALYSIS_RESOURCE_DEFAULTS.heapMb)} MiB)`;
const adjustment =
heapMb >= JAVASCRIPT_WORKER_HEAP_MIB_MAXIMUM
? `max_heap_mb is already ${String(heapMb)} MiB, the maximum ${String(JAVASCRIPT_WORKER_HEAP_MIB_MAXIMUM)}. Do not increase it further.`
: `Increase max_heap_mb (CLI: rea analyze-javascript-application <input_path> --max-heap-mb <mebibytes>), ${bounds}.`;
return `${adjustment} The effective worker heap for this analysis is ${String(heapMb)} MiB. A changed max_heap_mb applies on the next analysis, which starts a new worker. It does not change a worker that is already running, and it does not require restarting the REA server. ${HEAP_DOES_NOT_RAISE} On Bun, V8 heap flags are ignored: Windows limits the analyzer's committed memory to max_heap_mb plus a 512 MiB reserve, and other Bun hosts enforce no analyzer heap limit.`;
};
/**
* Node control for the CLI/MCP process heap. The old-space flag requires a
* mebibyte value; a bare name is an illegal V8 option and prevents Node from
* starting.
*/
export const JAVASCRIPT_PARENT_HEAP_NODE_OPTIONS =
"On Node, set NODE_OPTIONS (for example --max-old-space-size=<MiB>) in the environment that starts the CLI or MCP server, then restart that process,";
/** Parent admission follows the CLI/MCP heap, not the isolated worker heap argument. */
export const JAVASCRIPT_PARENT_RESULT_BUDGET_REMEDIATION = `This limit belongs to the parent result budget. That budget follows the parent V8 heap limit. Increasing max_heap_mb does not raise it. ${JAVASCRIPT_PARENT_HEAP_NODE_OPTIONS} to raise the parent heap and this budget. Use the retained static facts or analyze fewer source files.`;
/** Checkpoint decode uses the parent heap, not the isolated worker heap argument. */
export const JAVASCRIPT_PARENT_CHECKPOINT_HEAP_REMEDIATION = `This limit belongs to the parent process heap. Increasing max_heap_mb does not raise it. max_heap_mb changes only the isolated analyzer, on the next analysis, by starting a new worker. ${JAVASCRIPT_PARENT_HEAP_NODE_OPTIONS} to raise the parent heap and admit this checkpoint.`;
/**
* Heap-exhaustion exit text. Node exhausted the configured V8 old-space.
* Bun ignores that flag, so the same diagnostic must not name it as the cause.
*/
export const javaScriptWorkerHeapExhaustionRecovery = (input: {
readonly heapFlagsEnforced: boolean;
readonly heapMb: number;
readonly path: string;
readonly phase: string;
}): { readonly reason: string; readonly remediationAction: string } => {
if (input.heapFlagsEnforced)
return {
reason: `Owned JavaScript worker exhausted its ${String(input.heapMb)} MiB V8 old-space heap (max_heap_mb) while analyzing ${input.path} during ${input.phase}`,
remediationAction: javaScriptWorkerHeapRemediation(input.heapMb),
};
return {
reason: `Owned JavaScript worker ran out of memory while analyzing ${input.path} during ${input.phase}. Bun ignores the V8 old-space flag, so this exit is not the configured max_heap_mb limit of ${String(input.heapMb)} MiB.`,
remediationAction:
"Bun ignores V8 heap flags, so raising max_heap_mb does not change this exit. Windows limits the analyzer's committed memory to max_heap_mb plus a 512 MiB reserve and reports that separately as a process memory limit. Other Bun hosts enforce no analyzer heap limit. Reduce the analysis instead of increasing max_heap_mb.",
};
};
const semanticControl = {
nodes: {
total: "max_semantic_nodes",
perFile: "max_semantic_nodes_per_file",
ceiling: "semantic_graph_node_ceiling",
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",
},
unknowns: {
total: "max_semantic_unknowns",
perFile: "max_semantic_unknowns_per_file",
ceiling: "semantic_graph_unknown_ceiling",
fileCeiling: "semantic_graph_file_unknown_ceiling",
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",
},
} as const;
const semanticAdjustment = (
name: string,
value: number,
fallback: number,
): string =>
value >= JAVASCRIPT_SEMANTIC_ITEM_MAXIMUM
? `${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)})`;
/**
* Name the caller arguments for one semantic retention ceiling.
* Coverage limits list both effective values. The limitation claims only
* the ceilings that stopped retention.
*/
export const javaScriptSemanticCeilingCoverage = (
kind: "nodes" | "unknowns",
total: number,
perFile: number,
reached: { readonly total: boolean; readonly perFile: boolean },
): {
readonly limits: ApplicationCoverage["limits"];
readonly limitation: string;
} => {
const control = semanticControl[kind];
const limits: ApplicationCoverage["limits"] = [
{ name: control.ceiling, value: total, unit: "items" },
{ name: control.fileCeiling, value: perFile, unit: "items" },
{ name: control.total, value: total, unit: "items" },
{ name: control.perFile, value: perFile, unit: "items" },
];
const reachedControls = [
...(reached.total
? [
{
name: control.total,
value: total,
fallback: control.totalDefault,
cli: control.cliTotal,
},
]
: []),
...(reached.perFile
? [
{
name: control.perFile,
value: perFile,
fallback: control.perFileDefault,
cli: control.cliPerFile,
},
]
: []),
];
if (reachedControls.length === 0)
throw new RangeError(
"Semantic ceiling coverage requires a ceiling that stopped retention",
);
const reachedText = reachedControls
.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 };
};
/** Project observed execution limits without inventing unmeasured values. */
export const javaScriptAnalysisCoverageLimits = (
limits: Readonly<Record<string, JsonValue>> | null,
@@ -83,8 +234,8 @@ export const javaScriptAnalysisResourceControlsSchema = z.strictObject({
max_heap_mb: z
.number()
.int()
.min(128)
.max(16_384)
.min(JAVASCRIPT_WORKER_HEAP_MIB_MINIMUM)
.max(JAVASCRIPT_WORKER_HEAP_MIB_MAXIMUM)
.optional()
.describe(
"Maximum V8 old-space heap in MiB for the isolated JavaScript source analyzer; defaults to 1024. This does not change the CLI/MCP process heap. When REA runs on Bun, which ignores V8 heap flags, Windows instead limits the analyzer's committed memory to this budget plus a 512 MiB runtime reserve; other Bun hosts enforce no limit.",