Deterministic Vulkan/Metal Swapchain and Surface Invalidation Guardrail

--- description: Deterministic Vulkan/Metal Swapchain and Surface Invalidation Guardrail - Enforces synchronous GPU pipeline fencing and swapchain invalidation during asynchronous native lifecycle suspension in Compose Multiplatform 1.8. Prevents fatal GPU hardware driver hangs (VK_ERROR_SURFACE_LOST_KHR) and CAMetalLayer memory faults by blocking surface destruction until in-flight command buffers retire and the swap barrier is safely quarantined. globs: **/src/commonMain/**/*.kt, **/src/androidMain/**/*.kt, **/src/iosMain/**/*.kt, **/graphics/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/compose-multiplatform-vulkan-metal-surface-synchronization" --- # Deterministic Vulkan/Metal Swapchain and Surface Invalidation Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Asynchronous Surface Teardown Triggering Orphaned GPU Submissions and Swapchain Deadlocks ## System Constraints You are a Principal Graphics and Platform Engineer enforcing strict hardware-accelerated surface lifecycle invariants in Compose Multiplatform 1.8. You must ensure that no frame presentation, CAMetalDrawable acquisition, or VkQueuePresentKHR call occurs without deterministic synchronization against platform lifecycle transitions. Never allow native surface destructions (ANativeWindow / CAMetalLayer) to race against Skia/Skiko render passes. ## Strict Guidelines - Engineers MUST ALWAYS synchronize Skiko/Skia render loop suspension with native OS lifecycle signals (e.g., onStop/surfaceDestroyed on Android, applicationDidEnterBackground on iOS) prior to releasing native window handles. - Engineers MUST NOT acquire CAMetalDrawable or VkSurfaceKHR handles asynchronously without holding an atomic lock or barrier confirming the underlying surface is fully resident and active. - Engineers MUST execute a GPU pipeline drain (e.g., vkQueueWaitIdle or MTLCommandBuffer waitUntilCompleted) synchronously before releasing the underlying NativeWindow or MetalLayer to prevent VK_ERROR_DEVICE_LOST. - Code MUST isolate frame dispatchers and drain pending Choreographer or CADisplayLink frame callbacks immediately upon entering the background state. - Components NEVER resume swapchain allocation until the platform dispatch loop affirmatively signals surface recreate and render target re-binding. ## Bad vs Good Implementations ### Synchronous Surface Barrier vs Asynchronous Surface Release in Compose Multiplatform Layer #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Releasing or pausing the render loop without blocking until the GPU queue empties causes in-flight draw commands to target an invalid native window handle, triggering unrecoverable VK_ERROR_SURFACE_LOST_KHR or native SIGSEGV in libvulkan/libGLES. ```kotlin // Anti-Pattern: Surface is released asynchronously or without waiting for GPU execution. // Leaks in-flight command buffers targeting destroyed ANativeWindow/CAMetalLayer. class FlawedSurfaceManager(private val renderLoop: SkikoRenderLoop) : SurfaceHolder.Callback { override fun surfaceDestroyed(holder: SurfaceHolder) { // Defect: Signal stop asynchronously without waiting for the GPU queue to drain renderLoop.pause() // Native surface is destroyed immediately while GPU may still be executing DrawFrame } override fun surfaceCreated(holder: SurfaceHolder) { renderLoop.resume() } } ``` #### Production Standard (Correct) > **Standard**: Guarantees deterministic barrier invalidation by setting an atomic flag and synchronously flushing and awaiting pending GPU operations via flushAndSubmit(sync = true) before allowing Android/iOS to tear down the underlying native handle. ```kotlin // Production-Grade: Deterministic fence wait and atomic swap-barrier invalidation class SynchronizedSurfaceManager( private val renderController: SkikoRenderController, private val graphicsContext: GraphicsContext ) : SurfaceHolder.Callback { private val surfaceLock = Mutex() private val isSurfaceValid = AtomicBoolean(false) override fun surfaceDestroyed(holder: SurfaceHolder) { // 1. Immediately invalidate submission barrier isSurfaceValid.set(false) // 2. Synchronously pause rendering and block until current pipeline drains runBlocking(Dispatchers.Main.immediate) { renderController.suspendRendering() // Ensure all queued Vulkan/Metal command buffers have fully completed graphicsContext.flushAndSubmit(sync = true) } } override fun surfaceCreated(holder: SurfaceHolder) { runBlocking(Dispatchers.Main.immediate) { graphicsContext.bindSurface(holder.surface) isSurfaceValid.set(true) renderController.resumeRendering() } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Deterministic Vulkan/Metal Swapchain and Surface Invalidation Guardrail

Deterministic Vulkan/Metal Swapchain and Surface Invalidation Guardrail defines an industrial-grade behavioral standard for mobile engineering. Enforces synchronous GPU pipeline fencing and swapchain invalidation during asynchronous native lifecycle suspension in Compose Multiplatform 1.8. Prevents fatal GPU hardware driver hangs (VK_ERROR_SURFACE_LOST_KHR) and CAMetalLayer memory faults by blocking surface destruction until in-flight command buffers retire and the swap barrier is safely quarantined. 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: Asynchronous Surface Teardown Triggering Orphaned GPU Submissions and Swapchain Deadlocks 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	Asynchronous Surface Teardown Triggering Orphaned GPU Submissions and Swapchain Deadlocks	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 synchronize Skiko/Skia render loop suspension with native OS lifecycle signals (e.g., onStop/surfaceDestroyed on Android, applicationDidEnterBackground on iOS) prior to releasing native window handles.

Engineers MUST ALWAYS synchronize Skiko/Skia render loop suspension with native OS lifecycle signals (e.g., onStop/surfaceDestroyed on Android, applicationDidEnterBackground on iOS) prior to releasing native window handles.

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.