experiment: Add "swift" identityMode — Swift-owned identity cache

[krodak]

Overview

Adds a third value for @JS(identityMode:) — .swift, alongside the existing .none (default) and .pointer (weak JS-side cache, shipped in swiftwasm#723). With .swift mode, wrapper identity is guaranteed via a per-class Swift-owned cache: the same Swift heap pointer always returns the same JS wrapper (=== equality) until release() is called.

The motivation is the miss-path regression .pointer mode carries over the no-cache baseline. On swiftCreatesObject (1M fresh objects per run), .pointer is ~3.0× slower than .none (2220 ms vs 734 ms). Profiling showed 88% of the miss cost is the FinalizationRegistry.register + new WeakRef + Map.set triple that .pointer mode needs for GC-safe lifetime. .swift mode gives up GC-driven cleanup and keeps a strong Map<pointer, wrapper> on JS plus a Set<pointer> on Swift, eliminating the entire FinalizationRegistry/WeakRef machinery on the miss path.

Tradeoff: .swift mode requires explicit release(). Because it doesn't use FinalizationRegistry or WeakRef, the JS garbage collector has no hook to trigger cleanup. Swift holds a strong retain until the wrapper is released; dropping all JS references to a wrapper without releasing leaks the Swift heap object. This is the same discipline as any manually-managed resource — use try { … } finally { x.release() } for scopes that can throw, or own the release in application code. If you can't accept that discipline, stay on .pointer mode (the shipped weak cache).

How it works

Each @JS(identityMode: .swift) class gets one global on the Swift side, one Map on the JS side, and one Wasm export. The whole surface:

// Per-class Swift state (emitted by ExportSwift)
nonisolated(unsafe) var _C_identityTable: Set<UnsafeMutableRawPointer> = []

// Per-class Wasm export
@_expose(wasm, "bjs_C_release_wrapper")
@_cdecl("bjs_C_release_wrapper")
public func _bjs_C_release_wrapper(_ pointer: UnsafeMutableRawPointer) {
    guard _C_identityTable.remove(pointer) != nil else { return }
    Unmanaged<C>.fromOpaque(pointer).release()
}

// Per-class extension override on C: every return shape (scalar, array
// element, Optional) bottoms out here and routes through the cache.
extension C {
    @_spi(BridgeJS) @_transparent
    public consuming func bridgeJSLowerReturn() -> UnsafeMutableRawPointer {
        return withExtendedLifetime(self) {
            let ptr = Unmanaged.passUnretained(self).toOpaque()
            if _C_identityTable.insert(ptr).inserted {
                _ = Unmanaged.passRetained(self)
            }
            return ptr
        }
    }
    @_spi(BridgeJS) public consuming func bridgeJSStackPush() { ... }
}

// Per-class JS state (emitted by BridgeJSLink)
class C {
    static __swiftIdentityWrappers = new Map()

    static __wrap(pointer) {
        const cached = C.__swiftIdentityWrappers.get(pointer)
        if (cached !== undefined) return cached
        const obj = Object.create(C.prototype)
        obj.pointer = pointer
        obj.__swiftIdentityHasReleased = false
        C.__swiftIdentityWrappers.set(pointer, obj)
        return obj
    }

    release() {
        if (this.__swiftIdentityHasReleased) return
        this.__swiftIdentityHasReleased = true
        instance.exports.bjs_C_release_wrapper(this.pointer)
        C.__swiftIdentityWrappers.delete(this.pointer)
    }
}

Swift's Set and JS's Map are updated at the same cache boundaries (return, release), keyed by the same pointer, so they stay in lockstep by construction. No side-channel between Swift and JS beyond the returned pointer. Swift uses Set.insert(ptr).inserted to decide whether to retain; JS uses Map.get() returning undefined to decide whether to build a wrapper.

Every return shape that bottoms out at a heap-object pointer — scalar, [C] array element, Optional<C> — goes through the per-class bridgeJSLowerReturn override, so identity holds uniformly.

Configuration

Per-class annotation:

@JS(identityMode: .swift)
class MyModel {
    @JS var name: String
    @JS init(name: String) { self.name = name }
}

Project-wide default via bridge-js.config.json:

{ "identityMode": "swift" }

Resolution: @JS(identityMode: .none | .pointer | .swift) overrides config, config overrides default (.none). The identityMode: parameter on @JS moved from Bool (legacy) to a public JSIdentityMode enum; the parser accepts both spellings for backward compatibility.

What changed

• JSIdentityMode.swift — new public enum (.none | .pointer | .swift).
• Macros.swift — identityMode: parameter type migrated from Bool to JSIdentityMode.
• BridgeJSSkeleton.swift — ExportedClass.identityMode: Bool? → String?.
• SwiftToSkeleton.swift — extractIdentityMode recognises enum member-access and legacy true/false literals.
• BridgeJSCore/Misc.swift — BridgeJSConfig.identityMode docs + validation accepting "none" | "pointer" | "swift".
• ExportSwift.swift — per-class Set<pointer> emission, release_wrapper thunk, and extension overrides of bridgeJSLowerReturn + bridgeJSStackPush so every return shape routes through the identity cache.
• BridgeJSLink.swift — standalone SwiftIdentityHeapObject class template (no SwiftHeapObject inheritance, no FinalizationRegistry, no WeakRef); per-skeleton configIdentityMode resolution so config defaults don't bleed across modules when multiple targets are linked together.
• BridgeJSIdentityTests — existing target extended with per-class-opt-in .swift scenarios: identity across re-export, release-deinit, double-release, identity-table cleanup, cross-array identity, GC survivability, Optional identity, mode coexistence.
• BridgeJSSwiftIdentityTests — new test target with { "identityMode": "swift" } config default, covering the config-default resolution path with unannotated classes.
• Benchmarks/ — *SwiftIdentity class variants and --identity-mode=both3 three-way harness.
• Utilities/bridge-js-generate.sh — registers the new BridgeJSSwiftIdentityTests target.
• Exporting-Swift-Class.md + Identity-Modes-For-Exported-Classes.md + BridgeJS-Configuration.md — DocC documentation with the three-mode comparison table, usage examples, rationale for manual release, and known limitations.

Benchmark results

Release build, adaptive sampling, arm64-macOS / Swift 6.3 / Node 22. churnObjects runs at 100k iterations (higher counts destabilise the FinalizationRegistry queue in none mode, same convention as the existing identity benchmarks). All other scenarios at 1M iterations.

Scenario	none	pointer	swift	swift vs pointer
passBothWaysRoundtrip	239 ms	66 ms	40 ms	40% faster
getPoolRepeated_100	235 ms	82 ms	62 ms	24% faster
churnObjects (100k)	120 ms	108 ms	62 ms	43% faster
swiftConsumesSameObject	35 ms	30 ms	34 ms	within noise
swiftCreatesObject	734 ms	2220 ms	960 ms	57% faster

.swift mode is faster than .pointer mode on every scenario with meaningful cache activity. The 3.0× regression .pointer mode has vs .none on swiftCreatesObject drops to 1.3× — .swift pays a smaller tax to carry identity.

Full methodology, memory notes, and reproduction recipe in Benchmarks/results/swift-side-cache/Benchmarks.md. Design rationale, dismissed alternatives, and ABI notes in Benchmarks/results/swift-side-cache/DESIGN.md.

Commit structure

Five commits for reviewability. Each compiles and passes tests; the three refactor: commits document the simplification journey with per-step benchmark deltas in their commit messages:

• feat: add opt-in "swift" identity mode with Swift-owned strong cache — initial implementation. Five per-class globals, compact-id cache, (id, freshBit) stack side-channel, register_wrapper callback on miss.
• refactor: simplify identity cache — drop compact id, key by pointer — 5 globals → 2; Array<wrapper>[id] → Map<pointer, wrapper>.
• refactor: drop register_wrapper callback — JS owns the wrapper ref — Swift no longer holds a strong JS-ref; JS Map is sufficient.
• refactor: drop freshBit side-channel — derive hit/miss symmetrically — Set.insert().inserted on Swift, Map.get() on JS; no stack push/pop per return.
• feat: preserve identity across all return shapes — per-class bridgeJSLowerReturn override so Optional and array paths route through the identity cache and keep ===.

The design journey could be squashed into one commit without losing correctness; kept as five so the bisectable performance deltas are legible in history.

---

Identity Mode Benchmark Report — swift mode

Scope

Comparison of identityMode: "none" (default), identityMode: "pointer" (WeakRef-based JS cache, shipped in main), and identityMode: "swift" (Swift-owned strong cache, introduced by this PR). Adaptive sampling with IQR outlier removal (min-runs=5, max-runs=15, target-cv=5%).

Important: results must be from a release build (swift package --swift-sdk $SWIFT_SDK_ID js -c release). Debug builds are 50–70× slower on create-heavy paths and not representative.

Environment

• Node.js: v22.22.0
• Swift: Apple Swift version 6.3
• Host target: arm64-apple-macosx26.3.1
• Build: release
• Adaptive sampling with IQR-based outlier removal

Scenarios

passBothWaysRoundtrip

The core reuse scenario. Swift creates an object, passes it to JS, JS passes it back in a tight loop. In none mode, every crossing allocates a new wrapper. In pointer and swift mode, the second crossing onward hits the cache. 1,000,000 iterations.

getPoolRepeated_100

Bulk return of 100 cached objects. Swift returns the same pool array to JS over and over. Tests hit-heavy throughput when identity is preserved for every element. 1,000,000 iterations.

churnObjects

Create–roundtrip–release cycle in a tight loop. Each iteration creates a new object, roundtrips it through Swift, then releases it. Tests pressure on the cache's birth/death bookkeeping. 100,000 iterations (higher counts destabilise the FinalizationRegistry queue in none mode, same convention as the existing identity benchmarks).

swiftConsumesSameObject

JS holds one object and passes it to Swift repeatedly. Mostly a one-way path. Measures the cost of cache lookup when there's little reuse payoff. 1,000,000 iterations.

swiftCreatesObject

Create-heavy path. Swift creates a fresh object each iteration and returns it to JS. Every call is a cache miss. Measures the overhead of cache bookkeeping on the worst-case path. 1,000,000 iterations.

Performance Results

Scenario	none	pointer	swift
passBothWaysRoundtrip	239 ms	66 ms	40 ms
getPoolRepeated_100	235 ms	82 ms	62 ms
churnObjects (100k)	120 ms	108 ms	62 ms
swiftConsumesSameObject	35 ms	30 ms	34 ms
swiftCreatesObject	734 ms	2220 ms	960 ms

Medians in ms, lower is better.

swift vs pointer

Scenario	pointer	swift	delta
passBothWaysRoundtrip	66	40	40% faster
getPoolRepeated_100	82	62	24% faster
churnObjects (100k)	108	62	43% faster
swiftConsumesSameObject	30	34	~parity (within 33% CV)
swiftCreatesObject	2220	960	57% faster

swift mode is faster than pointer mode on every scenario with meaningful cache activity. swiftConsumesSameObject is a one-way path where neither cache does much work, so all three modes sit within ~5 ms of each other.

swift vs none

Scenario	none	swift	delta
passBothWaysRoundtrip	239	40	6.0× faster
getPoolRepeated_100	235	62	3.8× faster
churnObjects (100k)	120	62	1.9× faster
swiftConsumesSameObject	35	34	parity
swiftCreatesObject	734	960	1.3× slower

The 3.0× regression pointer mode has vs none on swiftCreatesObject (734 ms vs 2220 ms) drops to 1.3× with swift mode — swift pays a smaller tax to carry identity across the miss path.

Memory

Memory profiling for passBothWaysRoundtrip via --identity-memory (1,000,000 iterations). Instrumentation adds overhead, so timings here are slower than the pure performance runs above.

Metric	none	pointer	swift
Avg duration	429 ms	76 ms	60 ms
Peak JS heap delta	271 MiB	41 MiB	21 MiB
Retained heap delta (pre-GC)	271 MiB	37 MiB	21 MiB
Post-GC delta	154 MiB	6.7 KiB	11.6 KiB

Peak heap delta: how much heap grew during the benchmark. In none mode, 1M wrapper objects are allocated. In pointer and swift modes one wrapper is reused 1M times — swift uses roughly half the heap that pointer uses because there is no WeakRef + FinalizationRegistry state per wrapper.

Retained heap delta (pre-GC): heap growth still live when the benchmark ends but before forced GC. swift mode drops to its allocation directly (no FinReg queue holding state alive); pointer mode retains slightly more than its peak suggests because FinalizationRegistry tombstones haven't run yet.

Post-GC delta: after global.gc(). pointer and swift both return essentially to baseline (few KiB). none retains 154 MiB because FinalizationRegistry callbacks for the 1M allocated wrappers haven't all fired yet — a two-forced-GC measurement would drain more.

The headline is the 21 MiB peak for swift mode — ~half of pointer's 41 MiB, and ~13× less than none's 271 MiB. Strong retention of a single reused wrapper costs nothing here because there's only one wrapper in flight; the benefit comes from shedding the per-crossing WeakRef + FinalizationRegistry bookkeeping.

Interpretation

swift mode wins on every hit-heavy and churn scenario and significantly narrows the miss-path regression that pointer mode carries vs the none baseline. The one-way path (swiftConsumesSameObject) is at parity across all three modes because the cache barely participates — JS passes one object, Swift does takeUnretainedValue, no wrappers change hands.

Stability Notes

Three of five scenarios reached the 5% CV target (passBothWaysRoundtrip, getPoolRepeated_100, swiftCreatesObject, churnObjects all under 5%). swiftConsumesSameObject ran at 33% CV due to variance in V8's scheduling on this very short (~30 ms) workload — running at 10M iterations would tighten the number, but the relative ordering of all three modes is stable across runs.

The benchmark runner uses IQR-based outlier removal (discards values outside Q1−1.5×IQR to Q3+1.5×IQR) and reports median, mean, and sample count after trimming.

Reproducing

From the Benchmarks/ directory:

# Build in release mode first
swift package --swift-sdk $SWIFT_SDK_ID js -c release

# Three-way comparison (none, pointer, swift), one scenario at a time
node --expose-gc run.js --adaptive --filter=passBothWaysRoundtrip   --identity-mode=both3 --identity-iterations=1000000
node --expose-gc run.js --adaptive --filter=getPoolRepeated_100     --identity-mode=both3 --identity-iterations=1000000
node --expose-gc run.js --adaptive --filter=churnObjects            --identity-mode=both3 --identity-iterations=100000
node --expose-gc run.js --adaptive --filter=swiftConsumesSameObject --identity-mode=both3 --identity-iterations=1000000
node --expose-gc run.js --adaptive --filter=swiftCreatesObject      --identity-mode=both3 --identity-iterations=1000000

# With memory profiling
node --expose-gc run.js --adaptive --filter=passBothWaysRoundtrip \
    --identity-mode=both3 --identity-iterations=1000000 --identity-memory

See Benchmarks/README.md for full CLI reference.