KMP WasmGC FFI Cross-Heap Lifecycle and Finalization Invariant

--- description: KMP WasmGC FFI Cross-Heap Lifecycle and Finalization Invariant - Enforces strict object lifespans and deterministic disposal contracts across Kotlin Multiplatform WasmGC managed heaps and JavaScript V8/JavaScriptCore host memory. Unchecked bi-directional referencing across the WasmGC/JS boundary leads to opaque circular cross-heap references that evade both engine garbage collectors. All cross-boundary exports and imports must leverage FinalizationRegistry, WeakRef, and explicit AutoCloseable/Disposable handles. globs: **/wasmJsMain/**/*.kt, **/wasmJsTest/**/*.kt, **/*Wasm*.kt, **/webMain/**/*.ts, **/webMain/**/*.js alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-wasmgc-ffi-heap-boundary-guardrail" --- # KMP WasmGC FFI Cross-Heap Lifecycle and Finalization Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Retaining raw JS references in Kotlin Wasm or leaking Wasm exported references across JS FFI without explicit dereferencing or finalization registries. ## System Constraints You are a Principal Mobile and WebAssembly Systems Engineer enforcing zero-leak memory invariants between Kotlin Multiplatform (WasmGC) and JavaScript runtime engines. WasmGC garbage collection operates within engine-level GC routines, but JS host references passed as external references (anyref/externref) or Wasm objects exported to JS retain strong roots across heap boundaries unless explicitly tracked and severed. You must reject any FFI boundary design that relies on implicit cross-heap GC or fails to provide explicit lifecycle disposal. ## Strict Guidelines - Engineers MUST ALWAYS implement AutoCloseable or a dedicated dispose() interface on any Kotlin Wasm object that holds references to external JS objects (`JsAny`). - Engineers MUST NOT store long-lived WasmGC exported references inside global JS closures, maps, or DOM nodes without registering them into a JavaScript `FinalizationRegistry` or holding them through a `WeakRef`. - Engineers MUST use explicit integer handle tables or token IDs when transmitting reference handles across the JS-to-Wasm boundary to prevent opaque GC cycles. - JavaScript wrappers around KMP Wasm exported objects MUST expose an explicit `dispose()` or `Symbol.dispose` method that invokes the corresponding Wasm free/teardown routine. - Callbacks passing from JavaScript into Kotlin Wasm MUST NEVER capture enclosing JS host contexts unless the callback handle is guaranteed to be deregistered upon completion. - Code SHOULD verify in test suites that cross-heap allocations do not increase retained heap size monotonically using V8 memory profiler snapshots (`performance.measureUserAgentSpecificMemory()`). ## Bad vs Good Implementations ### Preventing Uncollectible Cross-Heap Cycles in JS-to-WasmGC Bridge #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The JavaScript class holds a strong reference to the WasmGC session, while passing an event closure holding a reference back to the JS instance into Wasm. This forms an uncollectible cross-heap cycle between the V8 JS heap and WasmGC heap that neither garbage collector can traverse and collect. ```typescript class WasmBridgeSession { private wasmSession: any; private onEventCallback: (event: any) => void; constructor(wasmModule: any) { // Stores a direct WasmGC reference this.wasmSession = wasmModule.createSession(); // Closure captures 'this', and passing it into WasmGC creates a hard circular root this.onEventCallback = (ev: any) => this.handleEvent(ev); this.wasmSession.registerListener(this.onEventCallback); } private handleEvent(event: any): void { console.log('Event received', event); } // No teardown method to unbind listener or dispose wasmSession reference } ``` #### Production Standard (Correct) > **Standard**: Uses an indirect numeric handle (token) rather than holding direct opaque managed references, registers with FinalizationRegistry for leak detection, and implements explicit disposal conforming to standard disposal patterns (Symbol.dispose) to cleanly release resources across the boundary. ```typescript export class WasmBridgeSession implements Disposable { private wasmToken: number | null; private wasmModule: any; private static finalizer = new FinalizationRegistry((token: number) => { // Host-level safety net if explicit disposal was skipped console.warn(`WasmBridgeSession token ${token} collected without explicit dispose()`); }); constructor(wasmModule: any) { this.wasmModule = wasmModule; this.wasmToken = wasmModule.allocateSessionToken(); WasmBridgeSession.finalizer.register(this, this.wasmToken, this); } public [Symbol.dispose](): void { this.dispose(); } public dispose(): void { if (this.wasmToken !== null) { WasmBridgeSession.finalizer.unregister(this); this.wasmModule.releaseSessionToken(this.wasmToken); this.wasmToken = null; this.wasmModule = null; } } } ``` ### Deterministic Kotlin WasmGC Foreign Object Lifecycle #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Kotlin Wasm keeps an unmonitored strong reference to `jsCallback`. If the JS side maintains a reference to `NativeBridgeSubscriber`, a foreign cross-boundary leak is created with no release mechanism. ```kotlin import kotlin.js.JsAny import kotlin.js.JsExport @JsExport class NativeBridgeSubscriber(val jsCallback: JsAny) { // Stores JS object directly on Kotlin WasmGC heap indefinitely fun notify(payload: JsAny) { invokeJsCallback(jsCallback, payload) } } private fun invokeJsCallback(target: JsAny, payload: JsAny): Unit = js("target(payload)") ``` #### Production Standard (Correct) > **Standard**: Implements `AutoCloseable` to provide a deterministic teardown path that nullifies the `JsAny` reference, severing the WasmGC-to-JS edge and permitting immediate collection by host engine GC. ```kotlin import kotlin.js.JsAny import kotlin.js.JsExport @JsExport class NativeBridgeSubscriber(jsCallback: JsAny) : AutoCloseable { private var callbackRef: JsAny? = jsCallback fun notify(payload: JsAny) { val callback = checkNotNull(callbackRef) { "Subscriber has already been disposed" } invokeJsCallback(callback, payload) } override fun close() { // Explicitly nullify JS foreign reference from WasmGC heap callbackRef = null } } private fun invokeJsCallback(target: JsAny, payload: JsAny): Unit = js("target(payload)") ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP WasmGC FFI Cross-Heap Lifecycle and Finalization Invariant

KMP WasmGC FFI Cross-Heap Lifecycle and Finalization Invariant defines an industrial-grade behavioral standard for mobile engineering. Enforces strict object lifespans and deterministic disposal contracts across Kotlin Multiplatform WasmGC managed heaps and JavaScript V8/JavaScriptCore host memory. Unchecked bi-directional referencing across the WasmGC/JS boundary leads to opaque circular cross-heap references that evade both engine garbage collectors. All cross-boundary exports and imports must leverage FinalizationRegistry, WeakRef, and explicit AutoCloseable/Disposable handles. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Retaining raw JS references in Kotlin Wasm or leaking Wasm exported references across JS FFI without explicit dereferencing or finalization registries. Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Retaining raw JS references in Kotlin Wasm or leaking Wasm exported references across JS FFI without explicit dereferencing or finalization registries.	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS implement AutoCloseable or a dedicated dispose() interface on any Kotlin Wasm object that holds references to external JS objects (`JsAny`).

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.