[PR #5764] docs(native): explain resource-only bundle admission #7047

Open
opened 2026-11-01 21:44:57 +00:00 by bsakaguchi · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/5764
Author: @jdotc1
Created: 10/21/2026
Status: 🔄 Open

Base: main ← Head: docs/5589-resource-only-bundle-admission


📝 Commits (5)

  • e0babc8 docs(native): explain resource-only bundle admission
  • 9c3fde4 docs(native): name supported resource-session commands
  • 95d072c docs: refresh resource-session guide
  • 9cf84ca Merge upstream main into resource-session docs
  • 55f4454 Merge current main into resource-session documentation

📊 Changes

1 file changed (+23 additions, -0 deletions)

View changed files

📝 docs/native-investigation.md (+23 -0)

📄 Description

Summary

Documents the existing resource-only bundle session in the native investigation guide. Names its four supported commands, explains default Info.plist selection and null executable identity, and distinguishes resource inspection from ordinary binary admission. Refs #5589; the implementation is already on main.

Problem and expected behavior

The guide did not explain that app resources can be inspected from a bundle directory without resolving CFBundleExecutable, or distinguish that read-only resource route from ordinary executable admission. Readers could therefore infer either that a program declaration was required for resource inspection or that binary-only operations were available in a resource session.

Change and scope

The guide now names the four supported commands explicitly: inspect_plist, inspect_asset_catalog, inspect_keyed_archive, and decode_interface_builder. It documents the open_bundle_resources MCP entry point, default Info.plist selection, null executable identity, per-resource provenance, and the continuing authority of open_binary for executable analysis.

The text is placed before the complete static-inspection command list and preserves current main's executable-root traversal limitations. The earlier unsupported statement about preserving an omitted executable declaration is not retained; the narrower source-supported claim is that inspect_plist defaults to the selected resource root's Info.plist.

This is documentation-only. It introduces no runtime, provider, schema, target-selection, execution, mutation, or permission change.

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: docs/native-investigation.md; no runtime stage changes.
  • Contribution scope fit and linked maintainer decision: documentation of an existing read-only resource route; a new capability scope decision is not applicable.
  • CLI and MCP/tool-catalog contract: no command, schema, or catalog change. The guide describes the existing open_bundle_resources and resource-command behavior.
  • Provider, bridge, target-format, or platform compatibility: none.
  • Evidence, artifact, provenance, or reconstruction contract: no contract change. The documentation states that resource results use resource_root, per-resource provenance, and null executable identity.
  • Target selection, authority, upstream behavior, and cleanup details (if applicable): ordinary executable analysis remains under open_binary; resource sessions remain read-only and do not support binary-only operations or binary snapshots.
  • 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.

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: none; documentation-only change.
  • Base reproduction or other evidence: resolveBundleResourcePlistSelection defaults to root.infoPlistPath; NativePlistResourceRoot.test.ts covers default and selected-path behavior, resource-root execution, and null executable digest; AppBundleExecutable.ts keeps resource-root resolution separate from executable admission; the linked MCP contract contains the Identity and discovery target.
  • User-visible CLI/MCP output (if applicable): no output contract changes.
  • Remaining proof gaps: no new CLI or MCP scenario was run because runtime behavior is unchanged. The source tests do not explicitly establish absence of a CFBundleExecutable field, so the guide does not make that stronger claim.

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

Current published head: 55f445440ff53cc62d36af68f8f1c97d01e8879e, merged with upstream main 0b1af48a3718ae3d2cfd83aa21cd7ca88f3a6629 while preserving the resource-session documentation. The contribution against this upstream revision is one documentation file, +23/-0.

Reused validation from the prior published head 9cf84cae419cad5f5ae2be9dcb0448021efa0a13 on Node 24.22.1 / npm 11.19.1:

  • npm run docs:build passed, including generated documentation artifacts and VitePress rendering.
  • npm run check passed: typecheck, built lint, format check, Knip, metadata check, and architecture guards.

Those commands were not rerun on the current merge commit. The new merge passed a staged whitespace check. No runtime, provider, CLI, MCP, documentation-build or static suite was repeated for this update. Current-head hosted checks remain authoritative for integration.

Compatibility, safety, and release

  • Breaking changes or migration steps: none.
  • Real Hopper/Ghidra, browser, or OS coverage: not applicable.
  • Package or release metadata impact: none.
  • Security, privacy, process, or containment review: no runtime behavior or target interaction changes.

Author readiness

Human owner: @jdotc1

  • 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.

🔄 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/5764 **Author:** [@jdotc1](https://github.com/jdotc1) **Created:** 10/21/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `docs/5589-resource-only-bundle-admission` --- ### 📝 Commits (5) - [`e0babc8`](https://github.com/morluto/rea/commit/e0babc83d28c7704f1e2b4b34fca1efede75824b) docs(native): explain resource-only bundle admission - [`9c3fde4`](https://github.com/morluto/rea/commit/9c3fde4f900637e3864e24d391e383ff64baab94) docs(native): name supported resource-session commands - [`95d072c`](https://github.com/morluto/rea/commit/95d072cfbba8de35648445cbb22c276bb9094811) docs: refresh resource-session guide - [`9cf84ca`](https://github.com/morluto/rea/commit/9cf84cae419cad5f5ae2be9dcb0448021efa0a13) Merge upstream main into resource-session docs - [`55f4454`](https://github.com/morluto/rea/commit/55f445440ff53cc62d36af68f8f1c97d01e8879e) Merge current main into resource-session documentation ### 📊 Changes **1 file changed** (+23 additions, -0 deletions) <details> <summary>View changed files</summary> 📝 `docs/native-investigation.md` (+23 -0) </details> ### 📄 Description ## Summary Documents the existing resource-only bundle session in the native investigation guide. Names its four supported commands, explains default `Info.plist` selection and null executable identity, and distinguishes resource inspection from ordinary binary admission. Refs #5589; the implementation is already on main. ## Problem and expected behavior The guide did not explain that app resources can be inspected from a bundle directory without resolving `CFBundleExecutable`, or distinguish that read-only resource route from ordinary executable admission. Readers could therefore infer either that a program declaration was required for resource inspection or that binary-only operations were available in a resource session. ## Change and scope The guide now names the four supported commands explicitly: `inspect_plist`, `inspect_asset_catalog`, `inspect_keyed_archive`, and `decode_interface_builder`. It documents the `open_bundle_resources` MCP entry point, default `Info.plist` selection, null executable identity, per-resource provenance, and the continuing authority of `open_binary` for executable analysis. The text is placed before the complete static-inspection command list and preserves current main's executable-root traversal limitations. The earlier unsupported statement about preserving an omitted executable declaration is not retained; the narrower source-supported claim is that `inspect_plist` defaults to the selected resource root's `Info.plist`. This is documentation-only. It introduces no runtime, provider, schema, target-selection, execution, mutation, or permission change. 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: `docs/native-investigation.md`; no runtime stage changes. - Contribution scope fit and linked maintainer decision: documentation of an existing read-only resource route; a new capability scope decision is not applicable. - CLI and MCP/tool-catalog contract: no command, schema, or catalog change. The guide describes the existing `open_bundle_resources` and resource-command behavior. - Provider, bridge, target-format, or platform compatibility: none. - Evidence, artifact, provenance, or reconstruction contract: no contract change. The documentation states that resource results use `resource_root`, per-resource provenance, and null executable identity. - Target selection, authority, upstream behavior, and cleanup details (if applicable): ordinary executable analysis remains under `open_binary`; resource sessions remain read-only and do not support binary-only operations or binary snapshots. - 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. 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: none; documentation-only change. - Base reproduction or other evidence: `resolveBundleResourcePlistSelection` defaults to `root.infoPlistPath`; `NativePlistResourceRoot.test.ts` covers default and selected-path behavior, resource-root execution, and null executable digest; `AppBundleExecutable.ts` keeps resource-root resolution separate from executable admission; the linked MCP contract contains the `Identity and discovery` target. - User-visible CLI/MCP output (if applicable): no output contract changes. - Remaining proof gaps: no new CLI or MCP scenario was run because runtime behavior is unchanged. The source tests do not explicitly establish absence of a `CFBundleExecutable` field, so the guide does not make that stronger claim. 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 Current published head: `55f445440ff53cc62d36af68f8f1c97d01e8879e`, merged with upstream main `0b1af48a3718ae3d2cfd83aa21cd7ca88f3a6629` while preserving the resource-session documentation. The contribution against this upstream revision is one documentation file, +23/-0. Reused validation from the prior published head `9cf84cae419cad5f5ae2be9dcb0448021efa0a13` on Node 24.22.1 / npm 11.19.1: - `npm run docs:build` passed, including generated documentation artifacts and VitePress rendering. - `npm run check` passed: typecheck, built lint, format check, Knip, metadata check, and architecture guards. Those commands were not rerun on the current merge commit. The new merge passed a staged whitespace check. No runtime, provider, CLI, MCP, documentation-build or static suite was repeated for this update. Current-head hosted checks remain authoritative for integration. ## Compatibility, safety, and release - Breaking changes or migration steps: none. - Real Hopper/Ghidra, browser, or OS coverage: not applicable. - Package or release metadata impact: none. - Security, privacy, process, or containment review: no runtime behavior or target interaction changes. ## Author readiness Human owner: @jdotc1 - [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. - [ ] User-visible CLI/MCP changes include representative output. - [ ] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
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#7047
No description provided.