[PR #6022] [MERGED] fix(javascript): name heap and semantic ceilings #7127

Closed
opened 2026-11-01 21:45:35 +00:00 by bsakaguchi · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/6022
Author: @morluto
Created: 10/21/2026
Status: ✅ Merged
Merged: 10/21/2026
Merged by: @morluto

Base: main ← Head: cursor/javascript-heap-semantic-ceilings-8b0a


📝 Commits (8)

  • ea76f6e fix(javascript): name heap and semantic ceilings
  • e0eb7f6 fix(javascript): distinguish adjustable ceilings from fixed limits
  • a8fec64 Merge branch 'main' into cursor/javascript-heap-semantic-ceilings-8b0a
  • 21b55f9 fix(javascript): keep Bun OOM and checkpoint heap controls distinct
  • 579feb0 fix(javascript): name semantic ceilings without claiming both were reached
  • 65d4a57 fix(javascript): name only the semantic ceiling that stopped retention
  • 95fced4 fix(javascript): require a value in the NODE_OPTIONS heap example
  • 7d3dc24 fix(javascript): limit the old-space placeholder to NODE_OPTIONS recovery

📊 Changes

22 files changed (+1166 additions, -87 deletions)

View changed files

📝 docs/javascript-artifact-reconstruction.md (+32 -6)
📝 docs/javascript-recovery.md (+9 -4)
📝 src/application/javascript/JavaScriptSemanticGraphBuilder.test.ts (+136 -0)
📝 src/application/javascript/JavaScriptSemanticGraphBuilder.ts (+117 -37)
📝 src/application/javascript/JavaScriptSemanticUnknownCapacity.test.ts (+73 -0)
📝 src/domain/explicitSensitiveFailure.test.ts (+20 -0)
📝 src/domain/explicitSensitiveFailure.ts (+6 -0)
📝 src/domain/javascript/javascriptAnalysisResourceControls.test.ts (+194 -1)
📝 src/domain/javascript/javascriptAnalysisResourceControls.ts (+153 -2)
➕ src/javascript/analysis/JavaScriptAnalysisTransfer.recovery.test.ts (+68 -0)
📝 src/javascript/analysis/JavaScriptAnalysisTransfer.ts (+57 -4)
📝 src/javascript/analysis/JavaScriptAnalysisWorker.ts (+62 -16)
📝 src/javascript/analysis/JavaScriptAnalysisWorkerProtocol.ts (+6 -0)
📝 src/javascript/analysis/JavaScriptAnalysisWorkerServer.ts (+7 -1)
📝 src/javascript/recovery/RecoveryFiles.ts (+20 -4)
📝 src/javascript/recovery/WakaruCommand.test.ts (+31 -1)
📝 src/javascript/recovery/WakaruCommand.ts (+7 -1)
📝 src/javascript/recovery/WakaruRelease.ts (+8 -0)
➕ src/javascript/recovery/WakaruReport.test.ts (+75 -0)
📝 src/javascript/recovery/WakaruReport.ts (+43 -5)

...and 2 more files

📄 Description

Summary

Refs #5910 (parent #5808). JavaScript analysis failures now name the existing controls an agent can change, and fixed ceilings say this release has no runtime override.

On Node, heap exhaustion names max_heap_mb: the effective mebibytes, the inclusive range 128 to 16384 (default 1024), that a change applies on the next analysis by starting a new worker, and that it does not raise the parent result budget, the transfer record ceiling, the 2 GiB transfer file maximum, the CLI/MCP process heap, or fixed parser limits. On Bun, a worker exit whose stderr matches heap exhaustion is not attributed to that V8 old-space limit, because Bun ignores the flag.

Semantic ceiling coverage keeps semantic_graph_*_ceiling and also names max_semantic_nodes, max_semantic_nodes_per_file, max_semantic_unknowns, and max_semantic_unknowns_per_file (each an integer from 1 to 1000000). The limitation names only the ceiling that stopped retention: the application total, the per-file ceiling, or both when each one stopped a file. coverage.limits still lists both effective argument values and both ceiling names. The transfer record ceiling (8388608 bytes) and the 2 GiB transfer file maximum have no runtime override. The effective transfer file ceiling follows the parent offered result budget, so on Node a larger CLI/MCP process heap (NODE_OPTIONS, for example --max-old-space-size=<MiB>, after restarting that process) can raise it up to 2 GiB. Selecting fewer source_paths can also raise that effective allowance. The parent result budget and parent checkpoint decode follow that same parent V8 heap. Wakaru's 120000 ms deadline has no runtime override; an unchanged retry may hit it again. analysis_timeout_ms (default 300000) was already named on the timeout path and was left unchanged.

Problem and expected behavior

A worker that exhausted its V8 old-space heap reported the exhaustion without naming max_heap_mb, the effective value, the valid range, or when a different value takes effect. The generic memory remediation talked about host memory and did not say what raising the worker heap does not raise.

Truncated semantic graphs reported semantic_graph_node_ceiling, semantic_graph_file_node_ceiling, semantic_graph_unknown_ceiling, and semantic_graph_file_unknown_ceiling without the caller arguments that set those ceilings.

Transfer, checkpoint, and worker-request failures fell through to the generic transport remediation (get_evidence_bundle). Wakaru's fixed 120000 ms deadline and fixed input, output, and diagnostic allowances did not say this release has no runtime override. Explicit-value redaction rebuilt a timeout error without userMessage or remediationAction, so the existing analysis_timeout_ms sentence was dropped on that path.

Review of the first revision: the effective transfer file ceiling and the parent result budget were described as having no runtime override. Both follow the CLI/MCP process heap. A provenance.json over 8 MiB lost the fixed-allowance guidance when parseWakaruReports wrapped the size refusal. The Wakaru deadline said an unchanged retry fails the same way, which is stronger than an elapsed-time check supports. A later review: Bun heap-exhaustion exits still named max_heap_mb, and checkpoint decode named the parent heap without the Node NODE_OPTIONS control. Truncated semantic retention then said both the total and the per-file ceiling were reached even when only one of them stopped retention.

Change and scope

Wording and projection only. Numeric defaults and schema bounds are unchanged. No new setting was added.

  • On Node, heap exhaustion uses javaScriptWorkerHeapRemediation. At 16384 MiB the text says not to increase max_heap_mb further. The Windows Bun commit-limit path still uses that remediation, because that limit is max_heap_mb plus a 512 MiB reserve. A Bun exit whose stderr matches heap exhaustion does not attribute the failure to the configured V8 old-space and does not say to increase max_heap_mb.
  • sameLimits compares heapMb and timeoutMs only, and #start applies --max-old-space-size at worker launch. The sentence therefore says 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.
  • Parent result-budget failures keep their existing reasons. Increasing max_heap_mb does not raise that budget. On Node, NODE_OPTIONS (for example --max-old-space-size=<MiB>) in the environment that starts the CLI or MCP server raises the parent V8 heap, and therefore this budget, after that process restarts. JAVASCRIPT_PARENT_HEAP_NODE_OPTIONS owns that sentence. A bare --max-old-space-size is an illegal V8 option and prevents Node from starting. Parent checkpoint decode uses the same parent-heap control: increasing max_heap_mb does not raise it, and on Node that NODE_OPTIONS restart can admit the checkpoint.
  • Semantic truncation coverage adds the four argument names beside the existing ceiling names, with effective values, defaults (100000 / 20000 / 100000 / 20000), range 1 to 1000000, CLI flags, and that a change applies on the next analyze_javascript_application call without restarting the worker or the REA server. JavaScriptSemanticGraphBuilder records which offered budget stopped node and unknown retention. The offer is the minimum of the per-file ceiling and the remaining application total. The limitation names only that smaller ceiling, or both when the two offers are equal, and tells the caller to set only those arguments. coverage.limits still lists both effective argument values and both ceiling names. At 1000000 the text says not to increase that reached control further. Unknown coverage keeps the omission-counting sentence. The same attribution covers direct projection, adopted file projections, and unavailable-file unknown omissions.
  • The transfer record ceiling is 8388608 bytes and the transfer file maximum is 2147483648 bytes. Both have no runtime override, and raising max_heap_mb does not raise them. The effective file ceiling follows the parent offered result budget. On Node, the same NODE_OPTIONS sentence (--max-old-space-size=<MiB>, then restart the CLI or MCP process) can raise it up to the maximum. Selecting fewer source_paths can also raise that effective allowance, because earlier retained results and the reserve for remaining sources reduce the offered budget. Neither change raises the record ceiling or the maximum. When the effective ceiling is already the maximum, the text says not to expect source_paths to raise it. The parent reattaches that remediation when the worker protocol forwards only message and limits. The 8388608-byte static checkpoint and the 65536-byte worker request ceiling keep the no-override sentence.
  • analysis_timeout_ms user text is unchanged. Redaction copies userMessage and remediationAction, including when those fields contain an explicit sensitive value, and still keeps analysis_timeout_ms.
  • Wakaru's 120000 ms deadline has no runtime override. Raising analysis_timeout_ms or max_heap_mb does not raise it. An unchanged retry may hit the deadline again. Input allowance (maximum_input_bytes, 67108864 bytes), output entries (10000), output bytes (134217728), and the 8388608-byte diagnostic allowance say no runtime override. A provenance.json over 8388608 bytes applies wakaruFixedLimitRecovery, and parseWakaruReports keeps that userMessage and remediationAction on the ProviderAdapterError. Malformed reports stay the generic adapter failure.

Web bundles, MCP response/startup naming (#6005), provider command_timeout_ms (#6014), Android, native, engines, and ASAR are out of scope. The 1 GiB Wakaru address-space ceiling has no dedicated error and was not given a new detector. Success-path RECOVERY_LIMITATIONS was left unchanged so successful recoveries keep their evidence identity.

Follow the contribution scope.
Unresolved scope, authority, side effects, or required verification block
integration. Link the required maintainer scope decision for new providers or
capabilities involving target execution, injection, mutation, or protection
recovery; ordinary fixes within existing boundaries may state "not applicable".
Draft PRs may leave the scope decision pending and the readiness and merge checklists
unchecked. Maintainers can help resolve open questions.

Not applicable. This is recovery and coverage text for existing JavaScript analysis and Wakaru limits. It does not add a provider, target execution, injection, mutation, or protection recovery.

Contract and boundary impact

  • Semantic owner and earliest changed stage: javaScriptAnalysisResourceControlsSchema owns max_heap_mb and the four max_semantic_* arguments. JavaScriptAnalysisWorker owns heap, parent-budget, checkpoint-decode, and worker-request recovery. JavaScriptAnalysisTransfer owns transfer ceilings. JavaScriptSemanticGraphBuilder owns semantic coverage limits and which ceiling stopped retention. Wakaru recovery owns the fixed adapter deadline and allowances. The worker protocol still forwards only message and limits; the parent reattaches remediation from those limit keys.
  • Contribution scope fit and linked maintainer decision: not applicable. Wording within existing JavaScript analysis and recovery boundaries.
  • CLI and MCP/tool-catalog contract: failure text and truncated semantic-graph coverage change. Schema fields, ranges, and defaults are unchanged: max_heap_mb 128..16384 default 1024 (CLI --max-heap-mb); max_semantic_nodes default 100000; max_semantic_nodes_per_file default 20000; max_semantic_unknowns default 100000; max_semantic_unknowns_per_file default 20000; each semantic argument is an integer from 1 to 1000000 (CLI --max-semantic-nodes, --max-semantic-nodes-per-file, --max-semantic-unknowns, --max-semantic-unknowns-per-file); analysis_timeout_ms 1..2147483647 default 300000. No catalog or tool-schema change.
  • Provider, bridge, target-format, or platform compatibility: none. Bun still ignores V8 heap flags; a Bun heap-exhaustion exit states that and does not claim --max-old-space-size was exhausted. Parent-heap guidance names Node NODE_OPTIONS and does not claim Bun honors --max-old-space-size.
  • Evidence, artifact, provenance, or reconstruction contract: truncated semantic graphs gain argument-named coverage limits and a limitation that names only the ceiling that stopped retention. graph_id includes limitations and coverage.limits, so a truncated graph's id changes. Graphs that are not truncated do not gain that limitation. Wakaru success-path limitations are unchanged.
  • Target selection, authority, upstream behavior, and cleanup details (if applicable): not applicable. No new process authority. Cleanup guidance on the Wakaru deadline is the existing "confirm outstanding work and cleanup" sentence.
  • Generated metadata (docs/public/product-catalog.json), package, or installation impact (CI generates and validates ignored catalogs and skills/; edit authored instructions in .agents/skills/reverse-engineer-anything/ and never commit build outputs): none. Skill text was not changed. docs/javascript-artifact-reconstruction.md and docs/javascript-recovery.md describe the named controls, the adjustable file ceiling, and the no-override sentences for fixed ceilings. The reconstruction doc says truncated coverage lists both effective ceilings and that the limitation names only the ceiling that stopped retention.

Expected effects (check known effects; use documentation-only on its own).
Unchecked items do not establish absence; leave uncertainties visible.

  • Read existing files or captured data.
  • Launch or attach to a process.
  • Inject instrumentation or run scripts/code.
  • Change process memory, registers, files, or configuration.
  • Contact network services.
  • Recover protected code or work around protections.
  • Documentation or usability only; no target interaction.
  • Not sure yet; investigation or maintainer guidance needed.

Evidence and regression coverage

  • Tests added or updated: src/domain/javascript/javascriptAnalysisResourceControls.test.ts, src/application/javascript/JavaScriptSemanticGraphBuilder.test.ts, src/application/javascript/JavaScriptSemanticUnknownCapacity.test.ts, src/javascript/analysis/JavaScriptAnalysisTransfer.recovery.test.ts, src/javascript/recovery/WakaruCommand.test.ts, src/javascript/recovery/WakaruReport.test.ts, src/domain/explicitSensitiveFailure.test.ts, tests/boundary/javascript/workerOrderAudit.test.ts, tests/boundary/cli/javascriptApplicationJsonOutput.test.ts.
  • Base reproduction or other evidence: schema and worker launch were read in source. max_heap_mb is applied only in #start via --max-old-space-size. prepareForAnotherAnalysis keeps the heap selected at launch, and sameLimits treats a different heapMb as a different worker. Semantic budgets are per-request node_budget / unknown_budget, not launch flags. javaScriptTransferByteBudget is max(512 MiB, offered result budget / 8) capped at 2 GiB. #refreshResultBudget and checkpoint decode both read getHeapStatistics().heap_size_limit. WORKER_HEAP_FLAGS_ENFORCED is true only when javaScriptRuntime is Node. Remaining sources reserve one next static checkpoint (checkpointBytes * 6, 48 MiB). Node truncation is attributed from the early exit when state.nodes.size >= nodeCeiling, from fileNodesDropped against the file offer, and from nodesTruncated on an adopted projection. Unknown omissions are attributed the same way for direct projection, adopted omissions, and unavailable files.
  • User-visible CLI/MCP output (if applicable): rea analyze-javascript-application JSON for a truncated semantic graph includes coverage limits { name: "max_semantic_nodes", value: 50 } and { name: "max_semantic_nodes_per_file", value: 30 } beside the existing ceiling names, and a limitation containing max_semantic_nodes and 1 to 1000000. That CLI fixture hits both ceilings (30 nodes in the first file, then the remaining 20 of the total). That CLI assertion was run on an earlier revision; this revision did not repeat it.
  • Remaining proof gaps: no live V8 heap-exhaustion allocation and no real Wakaru binary run. The worker test writes a heap-exhaustion stderr line and exits. The Bun wording is covered by the recovery helper, not by a Bun process. Address-space exhaustion still has no dedicated error. Checkpoint decode wording is covered by the shared remediation constant; the remaining-heap guard was not forced with a multi-gigabyte checkpoint. GitHub CI was not run here.

For evidence-bearing changes:

  • Observed, derived, and inferred claims remain distinguishable.
  • Artifact identity, source provenance, and failed attempts remain preserved.
  • Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

  • npm run check:fast — typecheck and lint succeeded (2 tasks). Repeated after rebasing onto the branch; the second run was a cache hit.
  • npm run test:focused -- src/domain/javascript/javascriptAnalysisResourceControls.test.ts src/application/javascript/JavaScriptSemanticGraphBuilder.test.ts src/application/javascript/JavaScriptSemanticUnknownCapacity.test.ts — 86 tests passed, including per-file-only, total-only, and both-reached node and unknown limitations. Repeated after the rebase; 86 tests passed again.
  • npx oxfmt --write on the five edited TypeScript files, then the formatter left them matching.

Earlier revisions also ran the worker-order, CLI JSON, Wakaru, and redaction focused tests. Those files are unchanged by the NODE_OPTIONS example fix and were not re-run for it. The semantic-ceiling revision above ran on Node v22.23.3.

The NODE_OPTIONS revision (7d3dc248e), rebased on 65d4a570, ran on Node v24.18.0:

  • npm run check:fast — typecheck and lint succeeded (2 tasks, 4.173s, 0 cached).
  • npm run test:focused -- src/domain/javascript/javascriptAnalysisResourceControls.test.ts src/javascript/analysis/JavaScriptAnalysisTransfer.recovery.test.ts — 8 tests passed. Parent-budget, checkpoint, and adjustable transfer remediations require --max-old-space-size=<MiB>.

Real Hopper, Ghidra, browser, or Wakaru provider workflows were not required. These paths are JavaScript analysis projection and the existing worker boundary.

Compatibility, safety, and release

  • Breaking changes or migration steps: none for callers of the schema. Truncated semantic graphs gain coverage limit entries and limitation text, so their graph_id changes. Failure strings change. Limits, defaults, and configuration parsing are unchanged.
  • Real Hopper/Ghidra, browser, or OS coverage: not applicable. No live heap exhaustion and no real Wakaru execution.
  • Package or release metadata impact: none.
  • Security, privacy, process, or containment review: remediation names NODE_OPTIONS with --max-old-space-size=<MiB> for the parent heap and does not ask the agent to patch REA source. A Bun heap-exhaustion exit does not ask the caller to raise max_heap_mb. Explicit-value redaction still redacts timeout userMessage and remediationAction; the test places explicit-secret in both fields and requires analysis_timeout_ms to remain.

Author readiness

Human owner: @morluto

  • I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
  • I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
  • I declare this PR ready for initial maintainer review.

Before merge

  • This PR addresses a concrete problem or an agreed enhancement.
  • Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff.
  • The PR has one focused outcome and the title follows type(scope): outcome.
  • Related issue is linked, or the reason for not linking one is stated above.
  • Tests cover changed observable behavior and meaningful failure paths.
  • Owning docs, contracts, and generated metadata are updated where needed.
  • User-visible CLI/MCP changes include representative output.
  • I checked the final diff for secrets, unrelated cleanup, and unsupported claims.
Open in Web Open in Cursor 

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/6022 **Author:** [@morluto](https://github.com/morluto) **Created:** 10/21/2026 **Status:** ✅ Merged **Merged:** 10/21/2026 **Merged by:** [@morluto](https://github.com/morluto) **Base:** `main` ← **Head:** `cursor/javascript-heap-semantic-ceilings-8b0a` --- ### 📝 Commits (8) - [`ea76f6e`](https://github.com/morluto/rea/commit/ea76f6eeac3670a513230cab348c28ba7d663e63) fix(javascript): name heap and semantic ceilings - [`e0eb7f6`](https://github.com/morluto/rea/commit/e0eb7f64cd6a9a18aa25c384b19a043db5de1042) fix(javascript): distinguish adjustable ceilings from fixed limits - [`a8fec64`](https://github.com/morluto/rea/commit/a8fec6406b59cabb1f154de77d8d55a264a0e097) Merge branch 'main' into cursor/javascript-heap-semantic-ceilings-8b0a - [`21b55f9`](https://github.com/morluto/rea/commit/21b55f9817716136892658856c3ef649ab4aa7ab) fix(javascript): keep Bun OOM and checkpoint heap controls distinct - [`579feb0`](https://github.com/morluto/rea/commit/579feb0baed9f3970c3df2435862df64555cab13) fix(javascript): name semantic ceilings without claiming both were reached - [`65d4a57`](https://github.com/morluto/rea/commit/65d4a57010b9eabbee8f8082f6210aa92193db2f) fix(javascript): name only the semantic ceiling that stopped retention - [`95fced4`](https://github.com/morluto/rea/commit/95fced4fd90cacffdde65dbc1208ffc77d828bc2) fix(javascript): require a value in the NODE_OPTIONS heap example - [`7d3dc24`](https://github.com/morluto/rea/commit/7d3dc248e5e305f7b3fe0fd56d8fb8951e39921b) fix(javascript): limit the old-space placeholder to NODE_OPTIONS recovery ### 📊 Changes **22 files changed** (+1166 additions, -87 deletions) <details> <summary>View changed files</summary> 📝 `docs/javascript-artifact-reconstruction.md` (+32 -6) 📝 `docs/javascript-recovery.md` (+9 -4) 📝 `src/application/javascript/JavaScriptSemanticGraphBuilder.test.ts` (+136 -0) 📝 `src/application/javascript/JavaScriptSemanticGraphBuilder.ts` (+117 -37) 📝 `src/application/javascript/JavaScriptSemanticUnknownCapacity.test.ts` (+73 -0) 📝 `src/domain/explicitSensitiveFailure.test.ts` (+20 -0) 📝 `src/domain/explicitSensitiveFailure.ts` (+6 -0) 📝 `src/domain/javascript/javascriptAnalysisResourceControls.test.ts` (+194 -1) 📝 `src/domain/javascript/javascriptAnalysisResourceControls.ts` (+153 -2) ➕ `src/javascript/analysis/JavaScriptAnalysisTransfer.recovery.test.ts` (+68 -0) 📝 `src/javascript/analysis/JavaScriptAnalysisTransfer.ts` (+57 -4) 📝 `src/javascript/analysis/JavaScriptAnalysisWorker.ts` (+62 -16) 📝 `src/javascript/analysis/JavaScriptAnalysisWorkerProtocol.ts` (+6 -0) 📝 `src/javascript/analysis/JavaScriptAnalysisWorkerServer.ts` (+7 -1) 📝 `src/javascript/recovery/RecoveryFiles.ts` (+20 -4) 📝 `src/javascript/recovery/WakaruCommand.test.ts` (+31 -1) 📝 `src/javascript/recovery/WakaruCommand.ts` (+7 -1) 📝 `src/javascript/recovery/WakaruRelease.ts` (+8 -0) ➕ `src/javascript/recovery/WakaruReport.test.ts` (+75 -0) 📝 `src/javascript/recovery/WakaruReport.ts` (+43 -5) _...and 2 more files_ </details> ### 📄 Description <!-- CURSOR_AGENT_PR_BODY_BEGIN --> ## Summary Refs #5910 (parent #5808). JavaScript analysis failures now name the existing controls an agent can change, and fixed ceilings say this release has no runtime override. On Node, heap exhaustion names `max_heap_mb`: the effective mebibytes, the inclusive range 128 to 16384 (default 1024), that a change applies on the next analysis by starting a new worker, and that it does not raise the parent result budget, the transfer record ceiling, the 2 GiB transfer file maximum, the CLI/MCP process heap, or fixed parser limits. On Bun, a worker exit whose stderr matches heap exhaustion is not attributed to that V8 old-space limit, because Bun ignores the flag. Semantic ceiling coverage keeps `semantic_graph_*_ceiling` and also names `max_semantic_nodes`, `max_semantic_nodes_per_file`, `max_semantic_unknowns`, and `max_semantic_unknowns_per_file` (each an integer from 1 to 1000000). The limitation names only the ceiling that stopped retention: the application total, the per-file ceiling, or both when each one stopped a file. `coverage.limits` still lists both effective argument values and both ceiling names. The transfer record ceiling (8388608 bytes) and the 2 GiB transfer file maximum have no runtime override. The effective transfer file ceiling follows the parent offered result budget, so on Node a larger CLI/MCP process heap (`NODE_OPTIONS`, for example `--max-old-space-size=<MiB>`, after restarting that process) can raise it up to 2 GiB. Selecting fewer `source_paths` can also raise that effective allowance. The parent result budget and parent checkpoint decode follow that same parent V8 heap. Wakaru's 120000 ms deadline has no runtime override; an unchanged retry may hit it again. `analysis_timeout_ms` (default 300000) was already named on the timeout path and was left unchanged. ## Problem and expected behavior A worker that exhausted its V8 old-space heap reported the exhaustion without naming `max_heap_mb`, the effective value, the valid range, or when a different value takes effect. The generic memory remediation talked about host memory and did not say what raising the worker heap does not raise. Truncated semantic graphs reported `semantic_graph_node_ceiling`, `semantic_graph_file_node_ceiling`, `semantic_graph_unknown_ceiling`, and `semantic_graph_file_unknown_ceiling` without the caller arguments that set those ceilings. Transfer, checkpoint, and worker-request failures fell through to the generic transport remediation (`get_evidence_bundle`). Wakaru's fixed 120000 ms deadline and fixed input, output, and diagnostic allowances did not say this release has no runtime override. Explicit-value redaction rebuilt a timeout error without `userMessage` or `remediationAction`, so the existing `analysis_timeout_ms` sentence was dropped on that path. Review of the first revision: the effective transfer file ceiling and the parent result budget were described as having no runtime override. Both follow the CLI/MCP process heap. A `provenance.json` over 8 MiB lost the fixed-allowance guidance when `parseWakaruReports` wrapped the size refusal. The Wakaru deadline said an unchanged retry fails the same way, which is stronger than an elapsed-time check supports. A later review: Bun heap-exhaustion exits still named `max_heap_mb`, and checkpoint decode named the parent heap without the Node `NODE_OPTIONS` control. Truncated semantic retention then said both the total and the per-file ceiling were reached even when only one of them stopped retention. ## Change and scope Wording and projection only. Numeric defaults and schema bounds are unchanged. No new setting was added. - On Node, heap exhaustion uses `javaScriptWorkerHeapRemediation`. At 16384 MiB the text says not to increase `max_heap_mb` further. The Windows Bun commit-limit path still uses that remediation, because that limit is `max_heap_mb` plus a 512 MiB reserve. A Bun exit whose stderr matches heap exhaustion does not attribute the failure to the configured V8 old-space and does not say to increase `max_heap_mb`. - `sameLimits` compares `heapMb` and `timeoutMs` only, and `#start` applies `--max-old-space-size` at worker launch. The sentence therefore says 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. - Parent result-budget failures keep their existing reasons. Increasing `max_heap_mb` does not raise that budget. On Node, `NODE_OPTIONS` (for example `--max-old-space-size=<MiB>`) in the environment that starts the CLI or MCP server raises the parent V8 heap, and therefore this budget, after that process restarts. `JAVASCRIPT_PARENT_HEAP_NODE_OPTIONS` owns that sentence. A bare `--max-old-space-size` is an illegal V8 option and prevents Node from starting. Parent checkpoint decode uses the same parent-heap control: increasing `max_heap_mb` does not raise it, and on Node that `NODE_OPTIONS` restart can admit the checkpoint. - Semantic truncation coverage adds the four argument names beside the existing ceiling names, with effective values, defaults (100000 / 20000 / 100000 / 20000), range 1 to 1000000, CLI flags, and that a change applies on the next `analyze_javascript_application` call without restarting the worker or the REA server. `JavaScriptSemanticGraphBuilder` records which offered budget stopped node and unknown retention. The offer is the minimum of the per-file ceiling and the remaining application total. The limitation names only that smaller ceiling, or both when the two offers are equal, and tells the caller to set only those arguments. `coverage.limits` still lists both effective argument values and both ceiling names. At 1000000 the text says not to increase that reached control further. Unknown coverage keeps the omission-counting sentence. The same attribution covers direct projection, adopted file projections, and unavailable-file unknown omissions. - The transfer record ceiling is 8388608 bytes and the transfer file maximum is 2147483648 bytes. Both have no runtime override, and raising `max_heap_mb` does not raise them. The effective file ceiling follows the parent offered result budget. On Node, the same `NODE_OPTIONS` sentence (`--max-old-space-size=<MiB>`, then restart the CLI or MCP process) can raise it up to the maximum. Selecting fewer `source_paths` can also raise that effective allowance, because earlier retained results and the reserve for remaining sources reduce the offered budget. Neither change raises the record ceiling or the maximum. When the effective ceiling is already the maximum, the text says not to expect `source_paths` to raise it. The parent reattaches that remediation when the worker protocol forwards only `message` and `limits`. The 8388608-byte static checkpoint and the 65536-byte worker request ceiling keep the no-override sentence. - `analysis_timeout_ms` user text is unchanged. Redaction copies `userMessage` and `remediationAction`, including when those fields contain an explicit sensitive value, and still keeps `analysis_timeout_ms`. - Wakaru's 120000 ms deadline has no runtime override. Raising `analysis_timeout_ms` or `max_heap_mb` does not raise it. An unchanged retry may hit the deadline again. Input allowance (`maximum_input_bytes`, 67108864 bytes), output entries (10000), output bytes (134217728), and the 8388608-byte diagnostic allowance say no runtime override. A `provenance.json` over 8388608 bytes applies `wakaruFixedLimitRecovery`, and `parseWakaruReports` keeps that `userMessage` and `remediationAction` on the `ProviderAdapterError`. Malformed reports stay the generic adapter failure. Web bundles, MCP response/startup naming (#6005), provider `command_timeout_ms` (#6014), Android, native, engines, and ASAR are out of scope. The 1 GiB Wakaru address-space ceiling has no dedicated error and was not given a new detector. Success-path `RECOVERY_LIMITATIONS` was left unchanged so successful recoveries keep their evidence identity. Follow the [contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope). Unresolved scope, authority, side effects, or required verification block integration. Link the required maintainer scope decision for new providers or capabilities involving target execution, injection, mutation, or protection recovery; ordinary fixes within existing boundaries may state "not applicable". Draft PRs may leave the scope decision pending and the readiness and merge checklists unchecked. Maintainers can help resolve open questions. Not applicable. This is recovery and coverage text for existing JavaScript analysis and Wakaru limits. It does not add a provider, target execution, injection, mutation, or protection recovery. ## Contract and boundary impact - Semantic owner and earliest changed stage: `javaScriptAnalysisResourceControlsSchema` owns `max_heap_mb` and the four `max_semantic_*` arguments. `JavaScriptAnalysisWorker` owns heap, parent-budget, checkpoint-decode, and worker-request recovery. `JavaScriptAnalysisTransfer` owns transfer ceilings. `JavaScriptSemanticGraphBuilder` owns semantic coverage limits and which ceiling stopped retention. Wakaru recovery owns the fixed adapter deadline and allowances. The worker protocol still forwards only `message` and `limits`; the parent reattaches remediation from those limit keys. - Contribution scope fit and linked maintainer decision: not applicable. Wording within existing JavaScript analysis and recovery boundaries. - CLI and MCP/tool-catalog contract: failure text and truncated semantic-graph coverage change. Schema fields, ranges, and defaults are unchanged: `max_heap_mb` 128..16384 default 1024 (CLI `--max-heap-mb`); `max_semantic_nodes` default 100000; `max_semantic_nodes_per_file` default 20000; `max_semantic_unknowns` default 100000; `max_semantic_unknowns_per_file` default 20000; each semantic argument is an integer from 1 to 1000000 (CLI `--max-semantic-nodes`, `--max-semantic-nodes-per-file`, `--max-semantic-unknowns`, `--max-semantic-unknowns-per-file`); `analysis_timeout_ms` 1..2147483647 default 300000. No catalog or tool-schema change. - Provider, bridge, target-format, or platform compatibility: none. Bun still ignores V8 heap flags; a Bun heap-exhaustion exit states that and does not claim `--max-old-space-size` was exhausted. Parent-heap guidance names Node `NODE_OPTIONS` and does not claim Bun honors `--max-old-space-size`. - Evidence, artifact, provenance, or reconstruction contract: truncated semantic graphs gain argument-named coverage limits and a limitation that names only the ceiling that stopped retention. `graph_id` includes `limitations` and `coverage.limits`, so a truncated graph's id changes. Graphs that are not truncated do not gain that limitation. Wakaru success-path limitations are unchanged. - Target selection, authority, upstream behavior, and cleanup details (if applicable): not applicable. No new process authority. Cleanup guidance on the Wakaru deadline is the existing "confirm outstanding work and cleanup" sentence. - Generated metadata (`docs/public/product-catalog.json`), package, or installation impact (CI generates and validates ignored catalogs and `skills/`; edit authored instructions in `.agents/skills/reverse-engineer-anything/` and never commit build outputs): none. Skill text was not changed. `docs/javascript-artifact-reconstruction.md` and `docs/javascript-recovery.md` describe the named controls, the adjustable file ceiling, and the no-override sentences for fixed ceilings. The reconstruction doc says truncated coverage lists both effective ceilings and that the limitation names only the ceiling that stopped retention. Expected effects (check known effects; use documentation-only on its own). Unchecked items do not establish absence; leave uncertainties visible. - [x] Read existing files or captured data. - [ ] Launch or attach to a process. - [ ] Inject instrumentation or run scripts/code. - [ ] Change process memory, registers, files, or configuration. - [ ] Contact network services. - [ ] Recover protected code or work around protections. - [ ] Documentation or usability only; no target interaction. - [ ] Not sure yet; investigation or maintainer guidance needed. ## Evidence and regression coverage - Tests added or updated: `src/domain/javascript/javascriptAnalysisResourceControls.test.ts`, `src/application/javascript/JavaScriptSemanticGraphBuilder.test.ts`, `src/application/javascript/JavaScriptSemanticUnknownCapacity.test.ts`, `src/javascript/analysis/JavaScriptAnalysisTransfer.recovery.test.ts`, `src/javascript/recovery/WakaruCommand.test.ts`, `src/javascript/recovery/WakaruReport.test.ts`, `src/domain/explicitSensitiveFailure.test.ts`, `tests/boundary/javascript/workerOrderAudit.test.ts`, `tests/boundary/cli/javascriptApplicationJsonOutput.test.ts`. - Base reproduction or other evidence: schema and worker launch were read in source. `max_heap_mb` is applied only in `#start` via `--max-old-space-size`. `prepareForAnotherAnalysis` keeps the heap selected at launch, and `sameLimits` treats a different `heapMb` as a different worker. Semantic budgets are per-request `node_budget` / `unknown_budget`, not launch flags. `javaScriptTransferByteBudget` is `max(512 MiB, offered result budget / 8)` capped at 2 GiB. `#refreshResultBudget` and checkpoint decode both read `getHeapStatistics().heap_size_limit`. `WORKER_HEAP_FLAGS_ENFORCED` is true only when `javaScriptRuntime` is Node. Remaining sources reserve one next static checkpoint (`checkpointBytes * 6`, 48 MiB). Node truncation is attributed from the early exit when `state.nodes.size >= nodeCeiling`, from `fileNodesDropped` against the file offer, and from `nodesTruncated` on an adopted projection. Unknown omissions are attributed the same way for direct projection, adopted omissions, and unavailable files. - User-visible CLI/MCP output (if applicable): `rea analyze-javascript-application` JSON for a truncated semantic graph includes coverage limits `{ name: "max_semantic_nodes", value: 50 }` and `{ name: "max_semantic_nodes_per_file", value: 30 }` beside the existing ceiling names, and a limitation containing `max_semantic_nodes` and `1 to 1000000`. That CLI fixture hits both ceilings (30 nodes in the first file, then the remaining 20 of the total). That CLI assertion was run on an earlier revision; this revision did not repeat it. - Remaining proof gaps: no live V8 heap-exhaustion allocation and no real Wakaru binary run. The worker test writes a heap-exhaustion stderr line and exits. The Bun wording is covered by the recovery helper, not by a Bun process. Address-space exhaustion still has no dedicated error. Checkpoint decode wording is covered by the shared remediation constant; the remaining-heap guard was not forced with a multi-gigabyte checkpoint. GitHub CI was not run here. For evidence-bearing changes: - [x] Observed, derived, and inferred claims remain distinguishable. - [x] Artifact identity, source provenance, and failed attempts remain preserved. - [x] Unsupported, incomplete, unavailable, or uncertain outcomes remain visible. ## Validation performed - `npm run check:fast` — typecheck and lint succeeded (2 tasks). Repeated after rebasing onto the branch; the second run was a cache hit. - `npm run test:focused -- src/domain/javascript/javascriptAnalysisResourceControls.test.ts src/application/javascript/JavaScriptSemanticGraphBuilder.test.ts src/application/javascript/JavaScriptSemanticUnknownCapacity.test.ts` — 86 tests passed, including per-file-only, total-only, and both-reached node and unknown limitations. Repeated after the rebase; 86 tests passed again. - `npx oxfmt --write` on the five edited TypeScript files, then the formatter left them matching. Earlier revisions also ran the worker-order, CLI JSON, Wakaru, and redaction focused tests. Those files are unchanged by the `NODE_OPTIONS` example fix and were not re-run for it. The semantic-ceiling revision above ran on Node v22.23.3. The `NODE_OPTIONS` revision (`7d3dc248e`), rebased on `65d4a570`, ran on Node v24.18.0: - `npm run check:fast` — typecheck and lint succeeded (2 tasks, 4.173s, 0 cached). - `npm run test:focused -- src/domain/javascript/javascriptAnalysisResourceControls.test.ts src/javascript/analysis/JavaScriptAnalysisTransfer.recovery.test.ts` — 8 tests passed. Parent-budget, checkpoint, and adjustable transfer remediations require `--max-old-space-size=<MiB>`. Real Hopper, Ghidra, browser, or Wakaru provider workflows were not required. These paths are JavaScript analysis projection and the existing worker boundary. ## Compatibility, safety, and release - Breaking changes or migration steps: none for callers of the schema. Truncated semantic graphs gain coverage limit entries and limitation text, so their `graph_id` changes. Failure strings change. Limits, defaults, and configuration parsing are unchanged. - Real Hopper/Ghidra, browser, or OS coverage: not applicable. No live heap exhaustion and no real Wakaru execution. - Package or release metadata impact: none. - Security, privacy, process, or containment review: remediation names `NODE_OPTIONS` with `--max-old-space-size=<MiB>` for the parent heap and does not ask the agent to patch REA source. A Bun heap-exhaustion exit does not ask the caller to raise `max_heap_mb`. Explicit-value redaction still redacts timeout `userMessage` and `remediationAction`; the test places `explicit-secret` in both fields and requires `analysis_timeout_ms` to remain. ## Author readiness Human owner: @morluto - [x] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [x] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [x] I declare this PR ready for initial maintainer review. ## Before merge - [x] This PR addresses a concrete problem or an agreed enhancement. - [x] Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff. - [x] The PR has one focused outcome and the title follows `type(scope): outcome`. - [x] Related issue is linked, or the reason for not linking one is stated above. - [x] Tests cover changed observable behavior and meaningful failure paths. - [x] Owning docs, contracts, and generated metadata are updated where needed. - [x] User-visible CLI/MCP changes include representative output. - [x] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. <!-- CURSOR_AGENT_PR_BODY_END --> <div><a href="https://cursor.com/agents/bc-c79d46c1-1b32-54ea-ba2e-0cd40ede8b0a?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-web-light.png"><img alt="Open in Web" width="114" height="28" src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a>&nbsp;<a href="https://cursor.com/background-agent?bcId=bc-c79d46c1-1b32-54ea-ba2e-0cd40ede8b0a&cursor_ref=pr_footer&cursor_cta=open_in_cursor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img alt="Open in Cursor" width="131" height="28" src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a>&nbsp;</div> --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
bsakaguchi 2026-11-01 21:45:35 +00:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
morluto/rea#7127
No description provided.