Swift 6 Actor Reentrancy State Mutability Invariant Guardrail

--- description: Swift 6 Actor Reentrancy State Mutability Invariant Guardrail - Enforces strict isolation and validation of mutable actor state across asynchronous suspension points (await) within high-concurrency native engine bindings. Prevents silent state corruption, interleaved race conditions, and uncoordinated bridge state updates caused by Swift actor reentrancy semantics. globs: ios/**/*.{swift,h,mm}, apple/**/*.{swift,h,mm}, Packages/**/*.swift, native/**/*.swift alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/swift6-actor-reentrancy-state-invariants" --- # Swift 6 Actor Reentrancy State Mutability Invariant Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Interleaved Actor State Mutation Across Async Suspension Points ## System Constraints You are a Principal Software Architect enforcing Swift 6 Actor Reentrancy and Memory Isolation Guardrails. Mandate that actor-isolated state is never assumed immutable across an 'await' suspension point. Ensure all native cross-platform engine interactions isolate state transitions via transactional phases, monotonic generation counters, or synchronous reduction cycles. ## Strict Guidelines - Engineers MUST ALWAYS re-validate all internal actor invariants immediately after resuming from any 'await' suspension point. - Engineers MUST NOT assume local or actor state persists unchanged across an asynchronous bridge call to cross-platform native engines (e.g., C++ core, Rust FFI, Metal render loops). - Code SHOULD extract external async operations out of state-modifying sequences, adopting the 'Fetch Out-of-Actor -> Verify -> Synchronously Mutate' architectural pattern. - Services MUST utilize monotonic epoch/generation counters or cancellation tokens to discard stale execution frames resuming after actor suspension. - Components NEVER execute multi-step cross-thread bridge dispatches while holding uncommitted local actor state. ## Bad vs Good Implementations ### Actor Reentrancy State Corruption vs Monotonic Epoch Validation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: In Swift 6, actors do not prevent reentrancy during 'await'. While 'ForeignEngineInterop.bootEngine' suspends, 'terminateSession()' or a secondary initialization can interleave, leading to dangling native handles and silent state divergence between Swift and the underlying C++ engine. ```swift actor NativeEngineBridge { private var sessionToken: String? private var isEngineActive: Bool = false func initializeEngineSession(token: String) async throws { // ANTI-PATTERN: State mutation initiated before suspension point self.sessionToken = token self.isEngineActive = true // Async suspension point: Actor lock is released while C++ engine boots let result = try await ForeignEngineInterop.bootEngine(with: token) // REENTRANCY BUG: Another caller could have called 'terminateSession()' or // re-entered 'initializeEngineSession()' during the bootEngine suspension, // causing stale results to overwrite newer state. ForeignEngineInterop.bindNativeViewport(result.handle) } func terminateSession() { self.sessionToken = nil self.isEngineActive = false ForeignEngineInterop.teardown() } } ``` #### Production Standard (Correct) > **Standard**: Introduces monotonic epoch validation. State is not prematurely committed before 'await', and upon resumption, the actor verifies that no interleaving operation altered 'currentEpoch'. Stale engine handles are released deterministically. ```swift actor NativeEngineBridge { private struct SessionState: Sendable { let token: String let epoch: UInt64 } private var activeSession: SessionState? private var currentEpoch: UInt64 = 0 func initializeEngineSession(token: String) async throws { // 1. Advance epoch synchronously to invalidate prior runs self.currentEpoch += 1 let sessionEpoch = self.currentEpoch // 2. Perform external work out-of-line without committing final state let result = try await ForeignEngineInterop.bootEngine(with: token) // 3. Post-suspension check: Verify invariants hold and no reentrancy occurred guard self.currentEpoch == sessionEpoch else { // Safe cancellation: Another operation invalidated this execution context ForeignEngineInterop.releaseHandle(result.handle) throw CancellationError() } // 4. Atomic synchronous commit phase self.activeSession = SessionState(token: token, epoch: sessionEpoch) ForeignEngineInterop.bindNativeViewport(result.handle) } func terminateSession() { self.currentEpoch += 1 self.activeSession = nil ForeignEngineInterop.teardown() } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Swift 6 Actor Reentrancy State Mutability Invariant Guardrail

Swift 6 Actor Reentrancy State Mutability Invariant Guardrail defines an industrial-grade behavioral standard for mobile engineering. Enforces strict isolation and validation of mutable actor state across asynchronous suspension points (await) within high-concurrency native engine bindings. Prevents silent state corruption, interleaved race conditions, and uncoordinated bridge state updates caused by Swift actor reentrancy semantics. 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: Interleaved Actor State Mutation Across Async Suspension Points 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	Interleaved Actor State Mutation Across Async Suspension Points	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 re-validate all internal actor invariants immediately after resuming from any 'await' suspension point.

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.