[GH-ISSUE #5694] [Docs] Dylib resolution guide omits platform-mismatch and not-loadable candidate outcomes #3446

New issue

Closed

opened 2026-10-31 00:40:35 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 00:40:35 +00:00

Owner

Originally created by @coygeek on GitHub (Oct 20, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/5694

Before submitting

I searched the existing issues for a related documentation report.
I removed credentials, tokens, private paths, and sensitive target data.

Documentation location

docs/apple-application-analysis.md, Dylib load resolution, lines 213-217.

Problem

The guide enumerates nine candidate outcomes for trace-dylib-resolution, but omits platform-mismatch and not-loadable. Both are supported output values and occur in successful traces when an earlier unusable candidate is followed by a compatible dylib. Readers interpreting normalized_result.edges[].candidates[].outcome cannot find either value's meaning in the enumeration.

Expected content

Include both outcomes and explain their meanings:

platform-mismatch: a matching-architecture dylib is incompatible with the process's platform.
not-loadable: the matching-architecture image is not a dylib and cannot satisfy this dependency load.

Clarify that rejecting an individual candidate can be followed by successful resolution at a later search path. Preserve the distinction between candidate outcomes and the edge's final resolution.status.

Supporting evidence

Source-derived definitions: the candidate schema includes both strings. Candidate evaluation emits not-loadable for a compatible slice whose file type is not MH_DYLIB, and platform-mismatch when platform loadability is incompatible.

Observed CLI reproduction, independently verified and replayed by the submitter: a self-built arm64 macOS app loads @rpath/libA.dylib with ordered rpaths @executable_path/../First and @executable_path/../Frameworks. A compatible dylib remains in the later directory. The earlier candidate is absent, a copy of the dylib with its LC_BUILD_VERSION platform changed from macOS to iOS and re-signed ad hoc, or a copy of the main executable placed at the dylib path. Each trace uses an isolated HOME/XDG/TMPDIR profile and explicitly selects the main executable:

node scripts/rea.mjs trace-dylib-resolution "$bundle" \
  --root Contents/MacOS/probe --architecture arm64 --json

Earlier candidate	Observed candidate outcomes in order
Absent control	`absent`, `resolved`
Dylib marked for iOS	`platform-mismatch`, `resolved`
Main executable at the dylib path	`not-loadable`, `resolved`

All three traces returned resolution.status: "resolved" and resolution.image: "Contents/Frameworks/libA.dylib". The self-built program printed 4 and exited successfully in all cases; DYLD_PRINT_LIBRARIES=1 confirmed that dyld loaded the later compatible dylib. These observations establish a documentation omission, with no incorrect runtime load decision demonstrated.

Tested rea-agents 6.7.0 at source commit 9d8e7803326a382cbbb3ffdb900f5e93e5442d68, Node v26.12.0, macOS 27.0.1 arm64, Apple clang 21.0.0. Fetched and source-rechecked origin/main at 949966712e68d8857a50a165ecddf04c2d7e6d3b; neither cited file changed after the baseline. No runtime replay on that newer revision is claimed.

Additional context

P3 documentation impact: users can recover the missing definitions from the schema and evaluator. Prepared with AI assistance. Related merged PR #1100 concerns candidate validation and search uncertainty; this report requests the missing guide entries for existing outcomes. #5637 and #5362 concern path-resolution behavior, and #5551 concerns dependency parsing. Those fixes do not supply these missing definitions.

Originally created by @coygeek on GitHub (Oct 20, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/5694 ### Before submitting - [x] I searched the existing issues for a related documentation report. - [x] I removed credentials, tokens, private paths, and sensitive target data. ### Documentation location [docs/apple-application-analysis.md, Dylib load resolution, lines 213-217](https://github.com/morluto/rea/blob/9d8e7803326a382cbbb3ffdb900f5e93e5442d68/docs/apple-application-analysis.md#L213-L217). ### Problem The guide enumerates nine candidate outcomes for `trace-dylib-resolution`, but omits `platform-mismatch` and `not-loadable`. Both are supported output values and occur in successful traces when an earlier unusable candidate is followed by a compatible dylib. Readers interpreting `normalized_result.edges[].candidates[].outcome` cannot find either value's meaning in the enumeration. ### Expected content Include both outcomes and explain their meanings: - `platform-mismatch`: a matching-architecture dylib is incompatible with the process's platform. - `not-loadable`: the matching-architecture image is not a dylib and cannot satisfy this dependency load. Clarify that rejecting an individual candidate can be followed by successful resolution at a later search path. Preserve the distinction between candidate outcomes and the edge's final `resolution.status`. ### Supporting evidence Source-derived definitions: [the candidate schema](https://github.com/morluto/rea/blob/9d8e7803326a382cbbb3ffdb900f5e93e5442d68/src/domain/apple/dylibResolution.ts#L132-L144) includes both strings. [Candidate evaluation](https://github.com/morluto/rea/blob/9d8e7803326a382cbbb3ffdb900f5e93e5442d68/src/domain/apple/dylibResolution.ts#L321-L339) emits `not-loadable` for a compatible slice whose file type is not `MH_DYLIB`, and `platform-mismatch` when platform loadability is incompatible. Observed CLI reproduction, independently verified and replayed by the submitter: a self-built arm64 macOS app loads `@rpath/libA.dylib` with ordered rpaths `@executable_path/../First` and `@executable_path/../Frameworks`. A compatible dylib remains in the later directory. The earlier candidate is absent, a copy of the dylib with its `LC_BUILD_VERSION` platform changed from macOS to iOS and re-signed ad hoc, or a copy of the main executable placed at the dylib path. Each trace uses an isolated HOME/XDG/TMPDIR profile and explicitly selects the main executable: ```sh node scripts/rea.mjs trace-dylib-resolution "$bundle" \ --root Contents/MacOS/probe --architecture arm64 --json ``` | Earlier candidate | Observed candidate outcomes in order | | --- | --- | | Absent control | `absent`, `resolved` | | Dylib marked for iOS | `platform-mismatch`, `resolved` | | Main executable at the dylib path | `not-loadable`, `resolved` | All three traces returned `resolution.status: "resolved"` and `resolution.image: "Contents/Frameworks/libA.dylib"`. The self-built program printed `4` and exited successfully in all cases; `DYLD_PRINT_LIBRARIES=1` confirmed that dyld loaded the later compatible dylib. These observations establish a documentation omission, with no incorrect runtime load decision demonstrated. Tested `rea-agents` 6.7.0 at source commit `9d8e7803326a382cbbb3ffdb900f5e93e5442d68`, Node v26.12.0, macOS 27.0.1 arm64, Apple clang 21.0.0. Fetched and source-rechecked `origin/main` at `949966712e68d8857a50a165ecddf04c2d7e6d3b`; neither cited file changed after the baseline. No runtime replay on that newer revision is claimed. ### Additional context P3 documentation impact: users can recover the missing definitions from the schema and evaluator. Prepared with AI assistance. Related merged PR #1100 concerns candidate validation and search uncertainty; this report requests the missing guide entries for existing outcomes. #5637 and #5362 concern path-resolution behavior, and #5551 concerns dependency parsing. Those fixes do not supply these missing definitions.

bsakaguchi closed this issue

2026-10-31 00:40:35 +00:00

bsakaguchi referenced this issue

2026-11-01 21:10:57 +00:00

[GH-ISSUE #3796] [Tracker] Open feature requests by area (October 2026) #1471