fix: stabilize object expando runtime keys

Author: DjDeveloperr

HANDOFF.md

@@ -29,11 +29,10 @@ reliability, modal behavior, stack/tab behavior, and simulator polish.
     `codex/rn-module-fabric-turbomodule-worklets`
   - Created from `refactor` at
     `f3d0b3f4ac6f6ff5753d321e7bb7ecc7e78f3443`.
-  - Branch split audit from 2026-06-28 23:36 EDT:
-    `HEAD`, `refactor`, and their merge-base all resolve to `f3d0b3f4`.
-    `git diff refactor...HEAD` is empty, so no RN-module commits have landed
-    on top of `refactor` yet. The RN work is currently dirty working-tree
-    state on this RN branch.
+  - Branch split audit from 2026-06-28 23:36 EDT confirmed the RN work was
+    separated from `refactor`; subsequent RN/runtime primitive commits now live
+    on `codex/rn-module-fabric-turbomodule-worklets` and are tracked in draft
+    PR #46.
   - Keep this branch for RN module / Fabric / TurboModule / worklets work.
     Preserve the original `refactor` branch for the Node-API runtime/direct
     engine backend PR.
@@ -111,6 +110,44 @@ During this thread `agent-device` was version `0.18.0`; the npm package is
 
 ## Current Verified State
 
+Update from 2026-06-29 16:55 EDT:
+
+- Simulator-only rule remains active. Do not use physical iPhone/iPad devices.
+- Draft PR #46 branch is cleanly on
+  `codex/rn-module-fabric-turbomodule-worklets`; the previous writable-member
+  correction was committed/pushed as `7eae675d`.
+- GitHub Actions run `28399361627` on `7eae675d` still failed only in iOS
+  simulator `ApiTests.js Appearance`:
+  `UILabel.appearance().textColor` read back `undefined` after assignment.
+  macOS stayed green.
+- Root cause refinement:
+  - The failed read can happen even if the UIAppearance setter path succeeds.
+  - Root runtime object expandos were keyed by `&runtime`, but V8 host-object
+    callbacks construct fresh stack `Runtime` wrappers for get/set calls. That
+    makes a value cached during assignment invisible to the later read under a
+    different wrapper address.
+- Current runtime fix:
+  - Root `NativeApiBridge` object expandos now key per-runtime values by stable
+    backend runtime state for V8/JSC/QuickJS via `runtime.state().get()`.
+  - Hermes/JSI keeps using the real JSI runtime reference fallback.
+  - Source coverage now guards against reintroducing the per-callback stack
+    wrapper key in root object expandos.
+- Local verification after this correction:
+  - `node packages/react-native/test/runtime-objc-property-setter.test.js`
+    passed.
+  - `git diff --check` passed.
+  - `npm run check:ffi-boundaries` passed.
+  - Runtime RN JS tests passed:
+    `for f in packages/react-native/test/*.test.js; do node "$f" || exit 1; done`.
+  - `npm run build:macos-cli` passed and compiled/linked the edited V8 bridge.
+  - Narrow local iOS simulator repro could not launch because the local
+    metadata-generator x86_64 build still fails to link against the arm64-only
+    Xcode `libclang.dylib`; keep using GitHub Actions for the authoritative iOS
+    simulator result until that local toolchain mismatch is fixed.
+- Not done:
+  - Commit/push the stable runtime-expando key fix and watch fresh PR CI.
+  - If CI turns green, resume the dedicated simulator-only RNS parity sweep.
+
 Update from 2026-06-29 16:05 EDT:
 
 - Simulator-only rule remains active. Do not use physical iPhone/iPad devices.

NativeScript/ffi/shared/bridge/ObjCBridge.mm

@@ -529,6 +529,16 @@ inline uintptr_t normalizeRuntimePointer(uintptr_t pointer) {
 #endif
 }
 
+uintptr_t runtimeObjectExpandoKey(Runtime& runtime) {
+#if defined(TARGET_ENGINE_V8) || defined(TARGET_ENGINE_JSC) || \
+    defined(TARGET_ENGINE_QUICKJS)
+  return normalizeRuntimePointer(
+      reinterpret_cast<uintptr_t>(runtime.state().get()));
+#else
+  return normalizeRuntimePointer(reinterpret_cast<uintptr_t>(&runtime));
+#endif
+}
+
 class NativeApiBridge {
   struct NativeApiRoundTripValue {
     std::shared_ptr<Value> value;
@@ -958,8 +968,7 @@ void setObjectExpando(Runtime& runtime, const void* native,
     }
     const uintptr_t key =
         normalizeRuntimePointer(reinterpret_cast<uintptr_t>(native));
-    const uintptr_t runtimeKey =
-        normalizeRuntimePointer(reinterpret_cast<uintptr_t>(&runtime));
+    const uintptr_t runtimeKey = runtimeObjectExpandoKey(runtime);
     {
       std::lock_guard<std::mutex> lock(objectExpandosMutex_);
       objectExpandos_[key][property][runtimeKey] =
@@ -987,8 +996,7 @@ Value findObjectExpando(Runtime& runtime, const void* native,
 
     const uintptr_t key =
         normalizeRuntimePointer(reinterpret_cast<uintptr_t>(native));
-    const uintptr_t runtimeKey =
-        normalizeRuntimePointer(reinterpret_cast<uintptr_t>(&runtime));
+    const uintptr_t runtimeKey = runtimeObjectExpandoKey(runtime);
     const uint64_t generation =
         objectExpandosGeneration_.load(std::memory_order_acquire);
     for (auto& entry : cache) {

PROGRESS.md

@@ -17,6 +17,43 @@ TypeScript/UI worklets.
 
 ## Latest Update - 2026-06-29
 
+### 2026-06-29 16:55 EDT - stable runtime keys for object expandos
+
+- Goal:
+  - Keep PR #46 on the generic runtime primitive path and remain
+    simulator-only. No physical devices were used.
+- CI finding:
+  - GitHub Actions run `28399361627` on `7eae675d` kept macOS green but still
+    failed iOS simulator `ApiTests.js Appearance`.
+  - The failure was unchanged: `UILabel.appearance().textColor` read back
+    `undefined` after assignment.
+  - Refinement: the setter/cache path could succeed and still miss on read
+    because root object expandos were keyed by `&runtime`. V8 host-object
+    callbacks create fresh stack `Runtime` wrappers, so assignment and read can
+    use different wrapper addresses for the same backend runtime.
+- Changes:
+  - Added a stable root `runtimeObjectExpandoKey` helper.
+  - V8/JSC/QuickJS object expandos now key per-runtime values by
+    `runtime.state().get()` instead of the callback wrapper address.
+  - Hermes/JSI keeps the real runtime reference fallback.
+  - Source coverage now guards against reintroducing the stack-wrapper key for
+    root object expandos.
+- Verification:
+  - `node packages/react-native/test/runtime-objc-property-setter.test.js`
+    passed.
+  - `git diff --check` passed.
+  - `npm run check:ffi-boundaries` passed.
+  - Runtime RN JS tests passed:
+    `for f in packages/react-native/test/*.test.js; do node "$f" || exit 1; done`.
+  - `npm run build:macos-cli` passed and compiled/linked the edited V8 bridge.
+  - Narrow local iOS simulator repro is still blocked before launch by the
+    local x86_64 metadata-generator link mismatch against Xcode's arm64-only
+    `libclang.dylib`.
+- Still next:
+  - Commit/push this stable runtime-expando key correction and watch fresh PR
+    CI for the authoritative iOS simulator result.
+  - If CI turns green, resume the dedicated simulator-only RNS parity sweep.
+
 ### 2026-06-29 16:05 EDT - UIAppearance writable member selection
 
 - Goal:

packages/react-native/test/runtime-objc-property-setter.test.js

@@ -40,6 +40,10 @@ const runtimeHostObjects = fs.readFileSync(
   path.join(repoRoot, "NativeScript/ffi/shared/bridge/HostObjects.mm"),
   "utf8",
 );
+const runtimeObjCBridge = fs.readFileSync(
+  path.join(repoRoot, "NativeScript/ffi/shared/bridge/ObjCBridge.mm"),
+  "utf8",
+);
 const appearanceAccessorStart = runtimeHostObjects.indexOf(
   "Function makeAppearanceProxyPropertySetter(",
 );
@@ -104,5 +108,12 @@ assert(
   !runtimeHostObjects.includes("SetNativeApiObjectPrototype(runtime, resultObject"),
   "runtime UIAppearance proxies should not replace their JS prototype with the target class prototype",
 );
+assert(
+  runtimeObjCBridge.includes("uintptr_t runtimeObjectExpandoKey(Runtime& runtime)") &&
+    runtimeObjCBridge.includes("runtime.state().get()") &&
+    runtimeObjCBridge.includes("const uintptr_t runtimeKey = runtimeObjectExpandoKey(runtime);") &&
+    !runtimeObjCBridge.includes("const uintptr_t runtimeKey =\n        normalizeRuntimePointer(reinterpret_cast<uintptr_t>(&runtime));"),
+  "runtime object expandos should use stable backend runtime identity instead of per-callback stack wrapper addresses",
+);
 
 console.log("runtime Objective-C property setter tests passed");