[PR #6172] [MERGED] fix(artifacts): name the ASAR header admission budget #7180

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

📋 Pull Request Information

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

Base: main ← Head: cursor/asar-header-admission-0059


📝 Commits (1)

  • 08e778d fix(artifacts): name the ASAR header admission budget

📊 Changes

11 files changed (+202 additions, -15 deletions)

View changed files

📝 .agents/skills/reverse-engineer-anything/references/javascript-applications.md (+5 -0)
📝 docs/electron-observation.md (+7 -1)
📝 docs/javascript-artifact-reconstruction.md (+11 -1)
📝 src/application/javascript/JavaScriptApplicationService.ts (+1 -0)
📝 src/artifacts/ArtifactOperationFailure.ts (+3 -0)
📝 src/artifacts/ArtifactReader.ts (+9 -0)
📝 src/artifacts/AsarHeader.ts (+30 -5)
📝 src/artifacts/inventory/ArtifactGraphConstruction.ts (+2 -6)
📝 src/domain/analysisErrorProjection.ts (+6 -0)
📝 src/domain/artifactOperationError.ts (+16 -1)
📝 tests/boundary/filesystem/asarHeaderAdmission.test.ts (+112 -1)

📄 Description

Summary

Refs #5910 (parent #5808). ASAR header/index admission stays a fixed 16 MiB / 16777216 byte policy. When that budget fails, the public error names the budget, says this release has no runtime override, and says that selecting fewer sources or narrowing an internal path does not bypass it.

Problem and expected behavior

MAX_ASAR_HEADER_BYTES in src/artifacts/AsarHeader.ts rejects a header before the archive index is decoded. The projected limit recovery was "Artifact is too large to process safely. Narrow the requested path or use a smaller artifact." That text does not identify header/index admission, does not say whether the ceiling can change, and suggests path narrowing that cannot skip the prerequisite header read.

The ceiling is a fixed implementation admission for this release. No caller argument or configuration setting already controls it. The numeric cap is unchanged.

Change and scope

Header admission failures from direct decode and from archive classification share one recovery. It names ASAR header/index admission, 16 MiB / 16777216 bytes, that this release has no runtime override, why source selection does not bypass the index read, and the supported alternative: analyze an extracted application directory, or supply an archive whose header fits. Raising max_heap_mb or host memory does not raise it. Repeating the unchanged request fails the same way.

Other artifact limit failures keep the existing generic recovery. Electron page resolution still refuses an oversized header as an unauthorized member; that path does not emit this artifact-operation message. The header cache's separate 16 MiB retention across eight archives is unchanged and does not raise admission.

Intentionally not in this PR: MCP response budgets (#6005), process regex (#6099), and browser/native/engine limit slices already merged. No new setting and no ASAR streaming.

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.

Contract and boundary impact

  • Semantic owner and earliest changed stage: ASAR header admission in src/artifacts/AsarHeader.ts; the public message is the CLI/MCP analysis-error projection.
  • Contribution scope fit and linked maintainer decision: ordinary error-recovery fix inside the existing read-only artifact boundary. Not applicable.
  • CLI and MCP/tool-catalog contract: inventory_artifact, inspect_artifact, and analyze_javascript_application now return the named header-admission recovery for this limit. details.admission is asar-header and details.maximum_header_bytes is 16777216. Tool schemas are unchanged.
  • Provider, bridge, target-format, or platform compatibility: none.
  • Evidence, artifact, provenance, or reconstruction contract: none. The failure still occurs before inventory Evidence is produced.
  • Target selection, authority, upstream behavior, and cleanup details (if applicable): read-only. Cleanup wrapping still preserves the admission message; a failed close reports cleanup_incomplete.
  • 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): authored skill text only. No package or catalog change.

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: tests/boundary/filesystem/asarHeaderAdmission.test.ts locks the recovery wording, the direct 16 MiB boundary, public inventory and analyze_javascript_application projection, and that source_paths plus max_heap_mb still hit the same admission. Unrelated artifact limits keep the generic recovery.
  • Base reproduction or other evidence: source review of admitAsarHeader and archive classification. The ~532 MB / ~102,600-file archive cited in #5910 was not re-run.
  • User-visible CLI/MCP output (if applicable): projected message and remediation.action are ASAR header/index admission is limited to 16 MiB / 16777216 bytes. This release has no runtime override. Selecting fewer sources or narrowing an internal path does not bypass header admission, because the archive index is read before any member can be selected. Raising max_heap_mb or available host memory does not raise it. Analyze an extracted application directory, which does not admit an ASAR header, or supply an archive whose header fits this allowance. Repeating the unchanged request fails the same way.
  • Remaining proof gaps: no live CLI process was spawned; the test projects the same error object the CLI and MCP adapters print. No real multi-hundred-megabyte ASAR was opened.

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 — passed (typecheck and lint).
  • npm run test:focused -- tests/boundary/filesystem/asarHeaderAdmission.test.ts src/artifacts/AsarHeader.test.ts tests/boundary/filesystem/artifactInventoryRegularRoot.test.ts — 15 tests passed.
  • npm run test:focused -- tests/boundary/filesystem/asarHeaderAdmission.test.ts src/artifacts/AsarHeader.test.ts src/artifacts/inventory/ArtifactGraphConstruction.test.ts — ArtifactGraphConstruction.test.ts passed (28 tests) before the final admission-test assertion fix; that source did not change afterward.

Compatibility, safety, and release

  • Breaking changes or migration steps: none. The limit value is unchanged. The user-visible limit message for this one failure changed.
  • Real Hopper/Ghidra, browser, or OS coverage: not applicable. Linux Node 24.18.0 fixture coverage only.
  • Package or release metadata impact: none.
  • Security, privacy, process, or containment review: read-only admission text. No new authority.

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/6172 **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/asar-header-admission-0059` --- ### 📝 Commits (1) - [`08e778d`](https://github.com/morluto/rea/commit/08e778de3614cee09aa5d6e15d238c5fdb545fb4) fix(artifacts): name the ASAR header admission budget ### 📊 Changes **11 files changed** (+202 additions, -15 deletions) <details> <summary>View changed files</summary> 📝 `.agents/skills/reverse-engineer-anything/references/javascript-applications.md` (+5 -0) 📝 `docs/electron-observation.md` (+7 -1) 📝 `docs/javascript-artifact-reconstruction.md` (+11 -1) 📝 `src/application/javascript/JavaScriptApplicationService.ts` (+1 -0) 📝 `src/artifacts/ArtifactOperationFailure.ts` (+3 -0) 📝 `src/artifacts/ArtifactReader.ts` (+9 -0) 📝 `src/artifacts/AsarHeader.ts` (+30 -5) 📝 `src/artifacts/inventory/ArtifactGraphConstruction.ts` (+2 -6) 📝 `src/domain/analysisErrorProjection.ts` (+6 -0) 📝 `src/domain/artifactOperationError.ts` (+16 -1) 📝 `tests/boundary/filesystem/asarHeaderAdmission.test.ts` (+112 -1) </details> ### 📄 Description <!-- CURSOR_AGENT_PR_BODY_BEGIN --> ## Summary Refs #5910 (parent #5808). ASAR header/index admission stays a fixed 16 MiB / 16777216 byte policy. When that budget fails, the public error names the budget, says this release has no runtime override, and says that selecting fewer sources or narrowing an internal path does not bypass it. ## Problem and expected behavior `MAX_ASAR_HEADER_BYTES` in `src/artifacts/AsarHeader.ts` rejects a header before the archive index is decoded. The projected limit recovery was "Artifact is too large to process safely. Narrow the requested path or use a smaller artifact." That text does not identify header/index admission, does not say whether the ceiling can change, and suggests path narrowing that cannot skip the prerequisite header read. The ceiling is a fixed implementation admission for this release. No caller argument or configuration setting already controls it. The numeric cap is unchanged. ## Change and scope Header admission failures from direct decode and from archive classification share one recovery. It names ASAR header/index admission, 16 MiB / 16777216 bytes, that this release has no runtime override, why source selection does not bypass the index read, and the supported alternative: analyze an extracted application directory, or supply an archive whose header fits. Raising `max_heap_mb` or host memory does not raise it. Repeating the unchanged request fails the same way. Other artifact limit failures keep the existing generic recovery. Electron page resolution still refuses an oversized header as an unauthorized member; that path does not emit this artifact-operation message. The header cache's separate 16 MiB retention across eight archives is unchanged and does not raise admission. Intentionally not in this PR: MCP response budgets (#6005), process regex (#6099), and browser/native/engine limit slices already merged. No new setting and no ASAR streaming. 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. ## Contract and boundary impact - Semantic owner and earliest changed stage: ASAR header admission in `src/artifacts/AsarHeader.ts`; the public message is the CLI/MCP analysis-error projection. - Contribution scope fit and linked maintainer decision: ordinary error-recovery fix inside the existing read-only artifact boundary. Not applicable. - CLI and MCP/tool-catalog contract: `inventory_artifact`, `inspect_artifact`, and `analyze_javascript_application` now return the named header-admission recovery for this limit. `details.admission` is `asar-header` and `details.maximum_header_bytes` is 16777216. Tool schemas are unchanged. - Provider, bridge, target-format, or platform compatibility: none. - Evidence, artifact, provenance, or reconstruction contract: none. The failure still occurs before inventory Evidence is produced. - Target selection, authority, upstream behavior, and cleanup details (if applicable): read-only. Cleanup wrapping still preserves the admission message; a failed close reports `cleanup_incomplete`. - 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): authored skill text only. No package or catalog change. 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. - [x] Documentation or usability only; no target interaction. - [ ] Not sure yet; investigation or maintainer guidance needed. ## Evidence and regression coverage - Tests added or updated: `tests/boundary/filesystem/asarHeaderAdmission.test.ts` locks the recovery wording, the direct 16 MiB boundary, public inventory and `analyze_javascript_application` projection, and that `source_paths` plus `max_heap_mb` still hit the same admission. Unrelated artifact limits keep the generic recovery. - Base reproduction or other evidence: source review of `admitAsarHeader` and archive classification. The ~532 MB / ~102,600-file archive cited in #5910 was not re-run. - User-visible CLI/MCP output (if applicable): projected `message` and `remediation.action` are `ASAR header/index admission is limited to 16 MiB / 16777216 bytes. This release has no runtime override. Selecting fewer sources or narrowing an internal path does not bypass header admission, because the archive index is read before any member can be selected. Raising max_heap_mb or available host memory does not raise it. Analyze an extracted application directory, which does not admit an ASAR header, or supply an archive whose header fits this allowance. Repeating the unchanged request fails the same way.` - Remaining proof gaps: no live CLI process was spawned; the test projects the same error object the CLI and MCP adapters print. No real multi-hundred-megabyte ASAR was opened. 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` — passed (typecheck and lint). - `npm run test:focused -- tests/boundary/filesystem/asarHeaderAdmission.test.ts src/artifacts/AsarHeader.test.ts tests/boundary/filesystem/artifactInventoryRegularRoot.test.ts` — 15 tests passed. - `npm run test:focused -- tests/boundary/filesystem/asarHeaderAdmission.test.ts src/artifacts/AsarHeader.test.ts src/artifacts/inventory/ArtifactGraphConstruction.test.ts` — ArtifactGraphConstruction.test.ts passed (28 tests) before the final admission-test assertion fix; that source did not change afterward. ## Compatibility, safety, and release - Breaking changes or migration steps: none. The limit value is unchanged. The user-visible limit message for this one failure changed. - Real Hopper/Ghidra, browser, or OS coverage: not applicable. Linux Node 24.18.0 fixture coverage only. - Package or release metadata impact: none. - Security, privacy, process, or containment review: read-only admission text. No new authority. ## 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-1207bb25-803b-591d-8935-471294f30059?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-1207bb25-803b-591d-8935-471294f30059&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:58 +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#7180
No description provided.