Support weak references for object interposers

[ezoushen]

Summary

Support weakly referenced object interposers for the retain-cycle use case in the original proposal.

• Keep existing object initializers strongly retaining by default.
• Add Interpose(.strong(object)) and Interpose(.weak(object)).
• Allow Interpose.object to become nil after a weak target deallocates.
• Throw InterposeError.objectDeallocated when a later operation requires that target.
• Remove hidden strong references from object-hook and dynamic-subclass internals.
• Preserve KVO, class-posing, and Core Foundation safety validation.

The unsafe unowned mode and validation bypass from the original draft are intentionally excluded.

Regression Proof

On macOS 26.5 with Xcode 26.6, associating the existing strongly retaining interposer back to its target reproduced the retain cycle: the target remained alive after its autorelease pool exited.

The new regression tests verify:

• A weak interposer can be associated with its target without retaining it.
• The hook remains active while the target is alive.
• The target deallocates after leaving scope.
• Later target-dependent preparation reports InterposeError.objectDeallocated.

Validation

• swift build -v
• swift test (22 tests)
• swift test -c release (22 tests)
• macOS Xcode tests with UTF-8 and UTF-16
• iOS simulator Xcode tests
• watchOS simulator build
• optimized release-linking proof
• class-load watcher proof through both callback paths
• CocoaPods lint compiled iOS, macOS, and watchOS; local tvOS validation could not start because Xcode exposed no eligible tvOS test destination
• $autoreview: clean

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed June 11, 2026, 9:05 AM ET / 13:05 UTC.

Summary
Adds a public Interpose.ObjectReference strong/weak wrapper, routes object interposers and object hooks through it, adds objectDeallocated, and updates docs, changelog, and weak-lifetime regression tests.

Reproducibility: yes. from source inspection: current master stores object interposer targets strongly in Interpose, ObjectHook, and InterposeSubclass, so associating an interposer back to its target forms the reported retain-cycle shape. I did not run tests in this read-only review.

Review metrics: 3 noteworthy metrics.

• Public API surface: 1 nested public struct, 1 public initializer, 1 public error case. The maintainer decision is about accepting a new external lifetime contract, not ordinary implementation cleanup.
• Patch size: 7 files changed, +170/-23. The diff is bounded enough to review directly but touches source, tests, README, and changelog.
• Reported validation: 7 GitHub checks plus local platform/proof pass. The owner comment reports broad validation, which reduces implementation risk while leaving the API decision.

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:

• Decide whether to land the public weak-reference API as written, revise its contract, or close the branch.

Risk before merge

• [P1] Merging/releasing this locks in a new public Interpose.ObjectReference and InterposeError.objectDeallocated contract, including weak-mode Interpose.object == nil and ObjectHook.object trapping after target deallocation.

Maintainer options:

1. Approve and land the API
   Maintainers can accept ObjectReference and objectDeallocated as the release API, relying on the preserved strong default and added weak-lifetime tests.
2. Revise the public contract first
   If names or lifetime semantics are not final, adjust the API, docs, and tests before merge because release will make the contract harder to change.
3. Close if core stays strong-only
   If weak object ownership is not desired in InterposeKit core, close this branch rather than keeping a stale public API candidate open.

Next step before merge

• [P2] The remaining action is maintainer API/product approval; there is no narrow automated repair needed for the current patch.

Security
Cleared: The diff changes Swift runtime object-hook ownership, docs, and tests; I found no concrete security or supply-chain concern.

Review details

Best possible solution:

Keep the strong-retaining default, then either land the weak-reference API with documented lifetime semantics after API approval or close the branch if core should not add that public surface.

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

Yes from source inspection: current master stores object interposer targets strongly in Interpose, ObjectHook, and InterposeSubclass, so associating an interposer back to its target forms the reported retain-cycle shape. I did not run tests in this read-only review.

Is this the best way to solve the issue?

Unclear as a product decision: the implementation is narrow and keeps existing strong behavior by default, but maintainers still need to accept or reject the new public API before merge.

AGENTS.md: not found in the target repository.

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

Label changes

Label changes:

• add merge-risk: 🚨 compatibility: The PR adds public API and lifetime semantics that become compatibility-sensitive once released.
• add proof: sufficient: Contributor real behavior proof is sufficient. The owner’s June 11, 2026 maintainer pass reports after-fix local tests, focused object-hook validation, platform builds, release-linking proof, class-load watcher proof, and passing checks, so no contributor proof action remains.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• remove rating: 🦪 silver shellfish: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.

Label justifications:

• P2: This is a normal-priority enhancement for a retain-cycle use case with limited blast radius and maintainer validation, not an urgent regression.
• merge-risk: 🚨 compatibility: The PR adds public API and lifetime semantics that become compatibility-sensitive once released.
• 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. Sufficient (logs): The owner’s June 11, 2026 maintainer pass reports after-fix local tests, focused object-hook validation, platform builds, release-linking proof, class-load watcher proof, and passing checks, so no contributor proof action remains.
• proof: sufficient: Contributor real behavior proof is sufficient. The owner’s June 11, 2026 maintainer pass reports after-fix local tests, focused object-hook validation, platform builds, release-linking proof, class-load watcher proof, and passing checks, so no contributor proof action remains.

Evidence reviewed

What I checked:

• Current master strongly retains object interposers: Interpose currently exposes public let object: AnyObject? and assigns self.object = object in the object initializer, so current master does not provide weak object interposers. (Sources/InterposeKit/InterposeKit.swift:43, 2492331dd962)
• Current object hook/subclass internals also retain: ObjectHook stores public let object: AnyObject, and InterposeSubclass stores let object: AnyObject, which matches the retain-cycle concern when the interposer is associated back to its target. (Sources/InterposeKit/ObjectHook.swift:10, 2492331dd962)
• PR introduces the weak/strong reference API: The PR head adds Interpose.ObjectReference, .strong(_:), .weak(_:), a computed Interpose.object, and an initializer that throws objectDeallocated if the referenced target is gone. (Sources/InterposeKit/InterposeKit.swift:56, d9aea264ceda)
• PR preserves strong object-hook default while adding deallocation handling: The existing object-hook initializer becomes a strong-reference convenience initializer, while the new internal initializer and replaceImplementation() throw InterposeError.objectDeallocated when a weak target has deallocated. (Sources/InterposeKit/ObjectHook.swift:26, d9aea264ceda)
• Regression tests cover the central behavior: The PR adds tests for breaking an associated-object retain cycle and for reporting objectDeallocated when later hook preparation needs a deallocated weak target. (Tests/InterposeKitTests/ObjectInterposeTests.swift:8, d9aea264ceda)
• Maintainer review leaves only product decision: The June 11, 2026 owner comment says the PR head is mergeable and clean, all seven GitHub checks pass, local validation/proofs pass, and the PR remains intentionally unmerged because it adds the public Interpose.ObjectReference API. (d9aea264ceda)

Likely related people:

• steipete: Introduced object hooking, extracted the object-subclass helper, made recent object-hook safety fixes, authored the current rewritten PR head, and left the latest product-decision comment. (role: feature owner and recent area contributor; confidence: high; commits: 9e387e1e8936, 4bcf98e02596, 7413a066a3d2; files: Sources/InterposeKit/InterposeKit.swift, Sources/InterposeKit/ObjectHook.swift, 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.

[steipete]

Maintainer pass complete on June 11, 2026.

• Head d9aea264ceda17c5199801d2129cb7ce72821c8d is mergeable and clean.
• All seven GitHub checks pass: SwiftPM, full Xcode, CocoaPods lint, SwiftLint, SwiftLint Analyze, Jazzy, and GitGuardian.
• Local debug/release tests, focused object-hook tests, macOS/iOS/watchOS builds, release-linking proof, both class-load watcher paths, and $autoreview pass.
• Contributor credit is preserved in the rewritten commit.

This remains intentionally unmerged because it adds the public Interpose.ObjectReference API. The candidate is ready for a land/delete product decision.

[steipete]

Thank you, @ezoushen, for the contribution and the careful work on this.

InterposeKit is old and no longer supported, and this repository is being archived. We will not merge or release this change, so I am closing the pull request.