feat: preserve identity across all return shapes

Emit a per-class extension override of _BridgedSwiftHeapObject's
bridgeJSLowerReturn that routes through the identity cache, symmetric
to the existing bridgeJSStackPush override. Without it,
Optional<SwiftIdentityClass> returns bypassed the per-class table:
_BridgedAsOptional.bridgeJSLowerReturn calls
value.bridgeJSLowerReturn() on the inner heap object, and that call
previously hit the default implementation (passRetained + bare
pointer) instead of our per-method thunk.

With this override, scalar, array-element, and Optional returns all
route through the same identity handshake. The existing Optional
identity test is upgraded from observability-only to strict === .

Side effect: the per-method `case .swiftHeapObject where isSwiftIdentityMode`
branch in ExportedThunkBuilder.lowerReturnValue is now redundant —
ret.bridgeJSLowerReturn() picks up the extension override
automatically. The builder's isSwiftIdentityMode predicate is
removed; codegen is simpler.

Also drops the ENABLE_TEST_INTROSPECTION compile-flag gate on the
Task 5 identity-table-size helpers. The generated BridgeJS.swift
always declares the Wasm exports for `@JS func` declarations, so a
conditional function definition broke the Generated file on
toolchains that didn't pick up the target's swiftSettings define.
The helpers are trivial and cost nothing to always-emit in test
targets that don't ship.

165/165 tests green.

Author: krodak

Benchmarks/Sources/Generated/BridgeJS.swift

@@ -1822,13 +1822,7 @@ nonisolated(unsafe) var _SimpleClassSwiftIdentity_identityTable: Set<UnsafeMutab
 public func _bjs_SimpleClassSwiftIdentity_init(_ nameBytes: Int32, _ nameLength: Int32, _ count: Int32, _ flag: Int32, _ rate: Float32, _ precise: Float64) -> UnsafeMutableRawPointer {
     #if arch(wasm32)
     let ret = SimpleClassSwiftIdentity(name: String.bridgeJSLiftParameter(nameBytes, nameLength), count: Int.bridgeJSLiftParameter(count), flag: Bool.bridgeJSLiftParameter(flag), rate: Float.bridgeJSLiftParameter(rate), precise: Double.bridgeJSLiftParameter(precise))
-    return withExtendedLifetime(ret) {
-        let ptr = Unmanaged.passUnretained(ret).toOpaque()
-        if _SimpleClassSwiftIdentity_identityTable.insert(ptr).inserted {
-            _ = Unmanaged.passRetained(ret)
-        }
-        return ptr
-    }
+    return ret.bridgeJSLowerReturn()
     #else
     fatalError("Only available on WebAssembly")
     #endif
@@ -1961,6 +1955,16 @@ public func _bjs_SimpleClassSwiftIdentity_release_wrapper(_ pointer: UnsafeMutab
 }
 
 extension SimpleClassSwiftIdentity {
+    @_spi(BridgeJS) @_transparent
+    public consuming func bridgeJSLowerReturn() -> UnsafeMutableRawPointer {
+        return withExtendedLifetime(self) {
+            let ptr = Unmanaged.passUnretained(self).toOpaque()
+            if _SimpleClassSwiftIdentity_identityTable.insert(ptr).inserted {
+                _ = Unmanaged.passRetained(self)
+            }
+            return ptr
+        }
+    }
     @_spi(BridgeJS) public consuming func bridgeJSStackPush() {
         let ptr: UnsafeMutableRawPointer = withExtendedLifetime(self) {
             let ptr = Unmanaged.passUnretained(self).toOpaque()
@@ -2001,13 +2005,7 @@ nonisolated(unsafe) var _ClassRoundtripSwiftIdentity_identityTable: Set<UnsafeMu
 public func _bjs_ClassRoundtripSwiftIdentity_init() -> UnsafeMutableRawPointer {
     #if arch(wasm32)
     let ret = ClassRoundtripSwiftIdentity()
-    return withExtendedLifetime(ret) {
-        let ptr = Unmanaged.passUnretained(ret).toOpaque()
-        if _ClassRoundtripSwiftIdentity_identityTable.insert(ptr).inserted {
-            _ = Unmanaged.passRetained(ret)
-        }
-        return ptr
-    }
+    return ret.bridgeJSLowerReturn()
     #else
     fatalError("Only available on WebAssembly")
     #endif
@@ -2018,13 +2016,7 @@ public func _bjs_ClassRoundtripSwiftIdentity_init() -> UnsafeMutableRawPointer {
 public func _bjs_ClassRoundtripSwiftIdentity_roundtripSimpleClassSwiftIdentity(_ _self: UnsafeMutableRawPointer, _ obj: UnsafeMutableRawPointer) -> UnsafeMutableRawPointer {
     #if arch(wasm32)
     let ret = ClassRoundtripSwiftIdentity.bridgeJSLiftParameter(_self).roundtripSimpleClassSwiftIdentity(_: SimpleClassSwiftIdentity.bridgeJSLiftParameter(obj))
-    return withExtendedLifetime(ret) {
-        let ptr = Unmanaged.passUnretained(ret).toOpaque()
-        if _SimpleClassSwiftIdentity_identityTable.insert(ptr).inserted {
-            _ = Unmanaged.passRetained(ret)
-        }
-        return ptr
-    }
+    return ret.bridgeJSLowerReturn()
     #else
     fatalError("Only available on WebAssembly")
     #endif
@@ -2035,13 +2027,7 @@ public func _bjs_ClassRoundtripSwiftIdentity_roundtripSimpleClassSwiftIdentity(_
 public func _bjs_ClassRoundtripSwiftIdentity_makeSimpleClassSwiftIdentity(_ _self: UnsafeMutableRawPointer) -> UnsafeMutableRawPointer {
     #if arch(wasm32)
     let ret = ClassRoundtripSwiftIdentity.bridgeJSLiftParameter(_self).makeSimpleClassSwiftIdentity()
-    return withExtendedLifetime(ret) {
-        let ptr = Unmanaged.passUnretained(ret).toOpaque()
-        if _SimpleClassSwiftIdentity_identityTable.insert(ptr).inserted {
-            _ = Unmanaged.passRetained(ret)
-        }
-        return ptr
-    }
+    return ret.bridgeJSLowerReturn()
     #else
     fatalError("Only available on WebAssembly")
     #endif
@@ -2079,6 +2065,16 @@ public func _bjs_ClassRoundtripSwiftIdentity_release_wrapper(_ pointer: UnsafeMu
 }
 
 extension ClassRoundtripSwiftIdentity {
+    @_spi(BridgeJS) @_transparent
+    public consuming func bridgeJSLowerReturn() -> UnsafeMutableRawPointer {
+        return withExtendedLifetime(self) {
+            let ptr = Unmanaged.passUnretained(self).toOpaque()
+            if _ClassRoundtripSwiftIdentity_identityTable.insert(ptr).inserted {
+                _ = Unmanaged.passRetained(self)
+            }
+            return ptr
+        }
+    }
     @_spi(BridgeJS) public consuming func bridgeJSStackPush() {
         let ptr: UnsafeMutableRawPointer = withExtendedLifetime(self) {
             let ptr = Unmanaged.passUnretained(self).toOpaque()
@@ -2119,13 +2115,7 @@ nonisolated(unsafe) var _IdentityCacheBenchmarkSwiftIdentity_identityTable: Set<
 public func _bjs_IdentityCacheBenchmarkSwiftIdentity_init() -> UnsafeMutableRawPointer {
     #if arch(wasm32)
     let ret = IdentityCacheBenchmarkSwiftIdentity()
-    return withExtendedLifetime(ret) {
-        let ptr = Unmanaged.passUnretained(ret).toOpaque()
-        if _IdentityCacheBenchmarkSwiftIdentity_identityTable.insert(ptr).inserted {
-            _ = Unmanaged.passRetained(ret)
-        }
-        return ptr
-    }
+    return ret.bridgeJSLowerReturn()
     #else
     fatalError("Only available on WebAssembly")
     #endif
@@ -2174,6 +2164,16 @@ public func _bjs_IdentityCacheBenchmarkSwiftIdentity_release_wrapper(_ pointer:
 }
 
 extension IdentityCacheBenchmarkSwiftIdentity {
+    @_spi(BridgeJS) @_transparent
+    public consuming func bridgeJSLowerReturn() -> UnsafeMutableRawPointer {
+        return withExtendedLifetime(self) {
+            let ptr = Unmanaged.passUnretained(self).toOpaque()
+            if _IdentityCacheBenchmarkSwiftIdentity_identityTable.insert(ptr).inserted {
+                _ = Unmanaged.passRetained(self)
+            }
+            return ptr
+        }
+    }
     @_spi(BridgeJS) public consuming func bridgeJSStackPush() {
         let ptr: UnsafeMutableRawPointer = withExtendedLifetime(self) {
             let ptr = Unmanaged.passUnretained(self).toOpaque()

Package.swift

@@ -225,11 +225,7 @@ let package = Package(
                 "Generated/JavaScript",
             ],
             swiftSettings: [
-                .enableExperimentalFeature("Extern"),
-                // Exposes gated `@JS func getSwift*ForChurn() -> Int` helpers
-                // that let Task-5 id-recycling tests read `_<Class>_nextId`.
-                // Do NOT export these in non-test builds.
-                .define("ENABLE_TEST_INTROSPECTION"),
+                .enableExperimentalFeature("Extern")
             ],
             linkerSettings: testingLinkerFlags
         ),
@@ -241,9 +237,7 @@ let package = Package(
                 "Generated/JavaScript",
             ],
             swiftSettings: [
-                .enableExperimentalFeature("Extern"),
-                // Same id-recycling introspection knob as BridgeJSIdentityTests.
-                .define("ENABLE_TEST_INTROSPECTION"),
+                .enableExperimentalFeature("Extern")
             ],
             linkerSettings: testingLinkerFlags
         ),

Plugins/BridgeJS/Sources/BridgeJSCore/ExportSwift.swift

@@ -31,16 +31,8 @@ public class ExportSwift {
         self.skeleton = skeleton
     }
 
-    /// Resolves whether a class is configured for `identityMode: "swift"`.
-    ///
-    /// Per-class `@JS(identityMode:)` takes priority over the skeleton-wide
-    /// default from `bridge-js.config.json`. Matches the resolution order in
-    /// `BridgeJSLink.shouldUseIdentityCache` but checks for the `"swift"` value
-    /// rather than `"pointer"`.
-    ///
-    /// Looks up by either the `name` or `swiftCallName` of an exported class —
-    /// the return-type's `.swiftHeapObject(String)` payload can be either
-    /// depending on how the type was referenced.
+    /// Whether a class resolves to `identityMode: "swift"`. Per-class annotation
+    /// wins over the skeleton-wide config default.
     func isSwiftIdentityMode(_ className: String) -> Bool {
         guard
             let klass = skeleton.classes.first(where: {
@@ -125,15 +117,9 @@ public class ExportSwift {
         var abiReturnType: WasmCoreType?
         var externDecls: [DeclSyntax] = []
         let effects: Effects
-        /// Predicate that resolves whether a class-name corresponds to an
-        /// `identityMode: "swift"` class. Default: always false. Threaded
-        /// through from `ExportSwift.isSwiftIdentityMode(_:)` at construction
-        /// time so return-lowering can emit the per-class cache glue.
-        let isSwiftIdentityMode: (String) -> Bool
 
-        init(effects: Effects, isSwiftIdentityMode: @escaping (String) -> Bool = { _ in false }) {
+        init(effects: Effects) {
             self.effects = effects
-            self.isSwiftIdentityMode = isSwiftIdentityMode
         }
 
         private func append(_ item: CodeBlockItemSyntax) {
@@ -351,26 +337,6 @@ public class ExportSwift {
                     }
                     """
                 )
-            case .swiftHeapObject(let className) where isSwiftIdentityMode(className):
-                // identityMode: "swift" — Swift's per-class Set tracks which
-                // pointers have been retained. On miss, retain once; on hit,
-                // skip. No signalling to JS needed: JS checks its own
-                // `Map<pointer, wrapper>` and derives hit/miss symmetrically.
-                // (See DECISIONS.md D20 for why dropping freshBit is safe:
-                // the Swift Set and the JS Map stay in lockstep by
-                // construction — both are keyed by pointer and updated at
-                // the same cache boundaries.)
-                append(
-                    """
-                    return withExtendedLifetime(ret) {
-                        let ptr = Unmanaged.passUnretained(ret).toOpaque()
-                        if _\(raw: className)_identityTable.insert(ptr).inserted {
-                            _ = Unmanaged.passRetained(ret)
-                        }
-                        return ptr
-                    }
-                    """
-                )
             default:
                 append("return ret.bridgeJSLowerReturn()")
             }
@@ -506,8 +472,7 @@ public class ExportSwift {
         let isStatic = context.isStatic
 
         let getterBuilder = ExportedThunkBuilder(
-            effects: Effects(isAsync: false, isThrows: false, isStatic: isStatic),
-            isSwiftIdentityMode: isSwiftIdentityMode
+            effects: Effects(isAsync: false, isThrows: false, isStatic: isStatic)
         )
 
         if !isStatic {
@@ -528,8 +493,7 @@ public class ExportSwift {
         // Generate property setter if not readonly
         if !property.isReadonly {
             let setterBuilder = ExportedThunkBuilder(
-                effects: Effects(isAsync: false, isThrows: false, isStatic: isStatic),
-                isSwiftIdentityMode: isSwiftIdentityMode
+                effects: Effects(isAsync: false, isThrows: false, isStatic: isStatic)
             )
 
             // Lift parameters based on property type
@@ -559,7 +523,7 @@ public class ExportSwift {
     }
 
     func renderSingleExportedFunction(function: ExportedFunction) throws -> DeclSyntax {
-        let builder = ExportedThunkBuilder(effects: function.effects, isSwiftIdentityMode: isSwiftIdentityMode)
+        let builder = ExportedThunkBuilder(effects: function.effects)
         for param in function.parameters {
             try builder.liftParameter(param: param)
         }
@@ -588,7 +552,7 @@ public class ExportSwift {
         callName: String,
         returnType: BridgeType
     ) throws -> DeclSyntax {
-        let builder = ExportedThunkBuilder(effects: constructor.effects, isSwiftIdentityMode: isSwiftIdentityMode)
+        let builder = ExportedThunkBuilder(effects: constructor.effects)
         for param in constructor.parameters {
             try builder.liftParameter(param: param)
         }
@@ -602,7 +566,7 @@ public class ExportSwift {
         ownerTypeName: String,
         instanceSelfType: BridgeType
     ) throws -> DeclSyntax {
-        let builder = ExportedThunkBuilder(effects: method.effects, isSwiftIdentityMode: isSwiftIdentityMode)
+        let builder = ExportedThunkBuilder(effects: method.effects)
         if !method.effects.isStatic {
             try builder.liftParameter(param: Parameter(label: nil, name: "_self", type: instanceSelfType))
         }
@@ -704,10 +668,7 @@ public class ExportSwift {
     func renderSingleExportedClass(klass: ExportedClass) throws -> [DeclSyntax] {
         var decls: [DeclSyntax] = []
 
-        // identityMode: "swift" — per-class state. Post-D19: Swift no longer
-        // holds the JS wrapper ref; JS keeps the wrapper alive in its own
-        // strong `Map<pointer, wrapper>`. Swift only tracks "have I already
-        // issued a wrapper for this pointer?" via a Set.
+        // .swift identity mode: Swift tracks which pointers have been retained.
         if isSwiftIdentityMode(klass.name) {
             decls.append(
                 "nonisolated(unsafe) var _\(raw: klass.name)_identityTable: Set<UnsafeMutableRawPointer> = []"
@@ -753,10 +714,8 @@ public class ExportSwift {
             decls.append(DeclSyntax(funcDecl))
         }
 
-        // identityMode: "swift" — emit the release thunk. Post-D19 there is
-        // no separate register thunk: Swift does not hold the JS ref, JS does
-        // (via its `Map<pointer, wrapper>`). Release just drops the Set entry
-        // and deallocates the Swift heap object.
+        // .swift identity mode: release thunk + overrides that route every
+        // return shape (scalar, array element, Optional) through the cache.
         if isSwiftIdentityMode(klass.name) {
             do {
                 let releaseDecl = SwiftCodePattern.buildExposedFunctionDecl(
@@ -772,12 +731,18 @@ public class ExportSwift {
                 decls.append(DeclSyntax(releaseDecl))
             }
 
-            // Override the default `_BridgedSwiftHeapObject.bridgeJSStackPush`
-            // so array-element returns (`[SwiftCached]`) go through the same
-            // identity-cache handshake. Post-D20: no `freshBit` push — JS
-            // checks its own Map for hit/miss.
-            let stackPushExt: DeclSyntax = """
+            let swiftIdentityOverridesExt: DeclSyntax = """
                 extension \(raw: klass.swiftCallName) {
+                    @_spi(BridgeJS) @_transparent
+                    public consuming func bridgeJSLowerReturn() -> UnsafeMutableRawPointer {
+                        return withExtendedLifetime(self) {
+                            let ptr = Unmanaged.passUnretained(self).toOpaque()
+                            if _\(raw: klass.name)_identityTable.insert(ptr).inserted {
+                                _ = Unmanaged.passRetained(self)
+                            }
+                            return ptr
+                        }
+                    }
                     @_spi(BridgeJS) public consuming func bridgeJSStackPush() {
                         let ptr: UnsafeMutableRawPointer = withExtendedLifetime(self) {
                             let ptr = Unmanaged.passUnretained(self).toOpaque()
@@ -790,7 +755,7 @@ public class ExportSwift {
                     }
                 }
                 """
-            decls.append(stackPushExt)
+            decls.append(swiftIdentityOverridesExt)
         }
 
         // Generate ConvertibleToJSValue extension

Plugins/BridgeJS/Sources/BridgeJSCore/Misc.swift

@@ -346,10 +346,9 @@ public struct BridgeJSConfig: Codable {
     ///
     /// Valid values: `"none"` | `"pointer"` | `"swift"`.
     ///
-    /// - `"none"` (or `nil`): No identity tracking. Each boundary crossing produces a fresh JS wrapper.
+    /// - `"none"` (or `nil`): no identity tracking; each boundary crossing produces a fresh JS wrapper.
     /// - `"pointer"`: JS-side identity cache keyed by the Swift pointer (weak refs + `FinalizationRegistry`).
-    /// - `"swift"`: Swift-side identity cache (opt-in; strong retention of the JS wrapper for the
-    ///   lifetime of the Swift heap object). See spec §3.
+    /// - `"swift"`: Swift-owned strong identity cache; wrappers live until explicit `release()`.
     ///
     /// A per-class `@JS(identityMode: ...)` annotation overrides this default.
     ///

Plugins/BridgeJS/Sources/BridgeJSCore/SwiftToSkeleton.swift

@@ -1202,13 +1202,11 @@ private final class ExportSwiftAPICollector: SyntaxAnyVisitor {
             let identityArg = arguments.first(where: { $0.label?.text == "identityMode" })
         else { return nil }
         let text = identityArg.expression.trimmedDescription
-        // Enum member-access form (current `JSIdentityMode` API).
+        // Enum member-access (current API).
         if text.contains(".swift") { return "swift" }
         if text.contains(".pointer") { return "pointer" }
         if text.contains(".none") { return "none" }
-        // Legacy Bool literals (pre-D8.1 spelling — map for forward compatibility
-        // during the transition; the macro itself no longer accepts these, but
-        // fixtures and third-party sources may still spell it this way.)
+        // Legacy Bool literals, kept for backward compatibility.
         if text == "true" { return "pointer" }
         if text == "false" { return "none" }
         return nil