Fix object hooks in optimized device builds

[steipete]

Summary

• Preserve IKTAddSuperImplementationToClass in optimized final binaries so object hooks can resolve their super trampoline.
• Add an unsigned generic-device Release build that verifies the helper survives dead stripping.
• Document the user-facing fix and credit Thomas Visser.

Closes #29.

Supersedes #30 because GitHub denied maintainer writes to the contributor fork.

Verification

• bash Tests/verify_release_linking.sh
• swift test
• swift test -c release
• Xcode macOS and iOS suites pass with the baseline-broken ObjectInterposeTests.testLargeStructReturn excluded; the same failure reproduces on untouched master with Xcode 26.6.
• pod lib lint --platforms=ios,macos,watchos --allow-warnings --skip-tests
• Optimized arm64 device archive exports _IKTAddSuperImplementationToClass.
• Autoreview: clean, no accepted/actionable findings.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed June 11, 2026, 5:00 AM ET / 09:00 UTC.

Summary
Marks the dynamically resolved Objective-C super-helper as retained, adds an optimized unsigned iOS app build that verifies the symbol in the final binary, expands Xcode CI coverage, and updates release notes.

Reproducibility: yes. at source level: current main reaches the helper only through dlsym, and the added optimized final-app build deterministically detects whether the linker removed it. This Linux review environment could not independently execute the Xcode build.

Review metrics: 3 noteworthy metrics.

• Patch surface: 4 files, 34 additions, 1 deletion. The production change is minimal, with most additions dedicated to focused final-link verification.
• Production change: 1 symbol-retention attribute added. The runtime behavior changes only by retaining an existing dynamically resolved helper.
• Regression coverage: 1 optimized device build added. CI now checks the helper in the final unsigned iOS Release application binary.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🐚 platinum hermit
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• Confirm the new Release device linking step passes on the current PR head.

Risk before merge

• [P1] The symbol-presence regression test does not directly execute an object hook in an optimized physical-device process, although it targets the specific final-link failure mechanism.
• [P1] The new generic-device Release build should be allowed to complete on the hosted Xcode runner before merging.

Maintainer options:

1. Decide the mitigation before merge
   Merge the minimal one-symbol retention change once the new hosted Release-linking check passes, preserving the final-application binary assertion as regression coverage for the dlsym contract.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• The patch has no actionable code finding, but its owner-authored status requires explicit human merge handling after the hosted Release-linking check completes.

Security
Cleared: The patch adds no dependencies, downloaded code, permission changes, secret access, publishing behavior, or other concrete security or supply-chain concern.

Review details

Best possible solution:

Merge the minimal one-symbol retention change once the new hosted Release-linking check passes, preserving the final-application binary assertion as regression coverage for the dlsym contract.

Do we have a high-confidence way to reproduce the issue?

Yes at source level: current main reaches the helper only through dlsym, and the added optimized final-app build deterministically detects whether the linker removed it. This Linux review environment could not independently execute the Xcode build.

Is this the best way to solve the issue?

Yes; retaining only the dynamically looked-up helper and inspecting the final Release app is narrower and safer than disabling dead stripping or adding broad linker flags.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against cd6a1207f1e6.

Label changes

Label changes:

• add P2: This fixes broken object hooks in optimized device applications, but the impact is bounded to a specific library feature and build mode.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The external-contributor proof gate does not apply because this PR is authored by the repository owner; the body nevertheless reports Release archive and final-symbol verification.
• remove rating: 🌊 off-meta tidepool: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.

Label justifications:

• P2: This fixes broken object hooks in optimized device applications, but the impact is bounded to a specific library feature and build mode.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The external-contributor proof gate does not apply because this PR is authored by the repository owner; the body nevertheless reports Release archive and final-symbol verification.

Evidence reviewed

What I checked:

• Failure mechanism: Current main resolves IKTAddSuperImplementationToClass by name through dlsym, leaving no ordinary static reference to prevent optimized final-link dead stripping. (Sources/InterposeKit/InterposeSubclass.swift:95, 4bcf98e02596)
• Helper provenance: The C helper and underlying object-hook support date to the original object-hook implementation in commit 9e387e1e8936a9456d2f5a97331abaee2f5455fb. (Sources/SuperBuilder/src/ITKSuperBuilder.m:40, 9e387e1e8936)
• Focused production fix: The branch adds Clang's used attribute to the existing helper declaration so the dynamically looked-up function is retained without changing its API or runtime logic. (Sources/SuperBuilder/src/ITKSuperBuilder.m:40, 516643382662)
• Final-binary regression check: The added script builds the example as an unsigned generic iOS Release app and checks its final Mach-O binary for the exported helper symbol. (Tests/verify_release_linking.sh:7, 516643382662)
• Optimized build surface: The example target uses Swift optimization in Release, making its final application binary an appropriate dead-stripping regression surface. (Example/InterposeExample.xcodeproj/project.pbxproj:401, cd6a1207f1e6)
• Repository policy: The fully read applicable AGENTS.md classifies owner-authored items as non-closeable and requires explicit owner handling. (../AGENTS.md:42)

Likely related people:

• steipete: Peter Steinberger introduced object hooks and the helper in 2020, refactored the dynamic lookup path, and recently maintained the adjacent trampoline implementation. (role: feature introducer and recent area contributor; confidence: high; commits: 9e387e1e8936, 4bcf98e02596, b0c428f3d229; files: Sources/SuperBuilder/src/ITKSuperBuilder.m, Sources/InterposeKit/InterposeSubclass.swift)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.