KMP Wasm-GC Cross-Runtime Reference Lifetime Synchronization

--- description: KMP Wasm-GC Cross-Runtime Reference Lifetime Synchronization - Eliminates cross-runtime frame drops and native bridge leaks by deterministically synchronizing Kotlin Multiplatform Wasm-GC allocations with host UI event cycles. Replaces non-deterministic finalizers with strict disposable handles and scoped host reference registries across the execution boundary. globs: src/wasmJsMain/**/*.kt, src/commonMain/**/*.kt, src/webMain/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-wasm-gc-native-interop-lifetime-boundary" --- # KMP Wasm-GC Cross-Runtime Reference Lifetime Synchronization > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Implicit Cross-Runtime Retain Cycles Relying on Host GC Finalizers Leading to Dual-Heap Fragmentation and Frame Drops ## System Constraints You are a Principal Software Architect enforcing deterministic memory boundaries and zero-alloc hot paths for Kotlin Multiplatform Wasm-GC and host native/JS UI engines. Enforce explicit lifetime scoping, eradicate dual-heap retain cycles, and ban reliance on host FinalizationRegistry for real-time interactive loops. ## Strict Guidelines - Engineers MUST ALWAYS wrap exported Wasm-GC delegates passed across the host boundary in explicit AutoCloseable or DisposableHandle abstractions. - Engineers MUST NOT rely on host garbage collection or FinalizationRegistry to schedule the disposal of Wasm-GC references tied to native/DOM rendering loops. - Code SHOULD pass opaque integer handles or raw scalar IDs across the interop boundary instead of retaining dynamic Kotlin closures in host UI listeners. - Services MUST clear bidirectional interop bridges synchronously within the UI component unmount or disposal phase (e.g., via Compose Multiplatform DisposableEffect). - Components NEVER construct circular references where a host DOM/platform node retains a Kotlin exported lambda that simultaneously captures the host node via closure. ## Bad vs Good Implementations ### Deterministic Lifetime Boundary for Host UI Callback Bridge #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Exporting an unmanaged Kotlin lambda to the host JS event loop traps the Wasm-GC instance in a host retain cycle. Because reclamation depends on asynchronous host collection, dual-heap pressure triggers unpredictable major GC pauses and frame drops. ```kotlin import kotlinx.browser.window import org.w3c.dom.events.Event class DynamicFrameObserver(private val onFrame: (Double) -> Unit) { fun start() { // ANTI-PATTERN: Closure traps 'this' across the Wasm-GC/JS host boundary. // No explicit deregistration mechanism exists, leaving references to collect // asynchronously via host GC finalization sweeps, introducing stutter and frame hitching. window.addEventListener("custom-render-tick", { event: Event -> onFrame(event.timeStamp) }) } } ``` #### Production Standard (Correct) > **Standard**: Implements AutoCloseable to enforce deterministic teardown. Decouples the listener reference and explicitly unbinds the host event listener, instantly freeing the Wasm-GC heap allocation without awaiting non-deterministic host garbage collector sweeps. ```kotlin import kotlinx.browser.window import org.w3c.dom.events.Event import org.w3c.dom.events.EventListener class DynamicFrameObserver( private val onFrame: (Double) -> Unit ) : AutoCloseable { // GOOD: Maintain an explicit, nullable reference to the platform listener bridge. private var listener: EventListener? = EventListener { event: Event -> onFrame(event.timeStamp) } fun start() { val currentListener = listener ?: return window.addEventListener("custom-render-tick", currentListener) } override fun close() { // GUARANTEE: Synchronously sever the cross-runtime retain edge. listener?.let { window.removeEventListener("custom-render-tick", it) listener = null } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP Wasm-GC Cross-Runtime Reference Lifetime Synchronization

KMP Wasm-GC Cross-Runtime Reference Lifetime Synchronization defines an industrial-grade behavioral standard for mobile engineering. Eliminates cross-runtime frame drops and native bridge leaks by deterministically synchronizing Kotlin Multiplatform Wasm-GC allocations with host UI event cycles. Replaces non-deterministic finalizers with strict disposable handles and scoped host reference registries across the execution boundary. 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: Implicit Cross-Runtime Retain Cycles Relying on Host GC Finalizers Leading to Dual-Heap Fragmentation and Frame Drops 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	Implicit Cross-Runtime Retain Cycles Relying on Host GC Finalizers Leading to Dual-Heap Fragmentation and Frame Drops	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 wrap exported Wasm-GC delegates passed across the host boundary in explicit AutoCloseable or DisposableHandle abstractions.

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.