Swift 6 Distributed Actor Remote Transport & Deserialization Failure Boundary

--- description: Swift 6 Distributed Actor Remote Transport & Deserialization Failure Boundary - Enforces strict fault-isolation boundaries and transactional state rollbacks across Swift 6 distributed actor systems operating over edge-to-client networks. Prevents split-brain state mutations and orphan lifecycle states caused by unhandled transport disconnects and invocation deserialization failures. Mandates that all distributed calls wrap remote transport invocations in idempotent, circuit-broken compensations with explicit lifecycle verification. globs: **/*.swift alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/swift6-distributed-actor-transport-boundary-isolation" --- # Swift 6 Distributed Actor Remote Transport & Deserialization Failure Boundary > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Mutating Local Distributed Actor State Prior to Remote Invalidation or Without Inbound Deserialization Isolation ## System Constraints You are a Principal Mobile Architect enforcing Swift 6 Distributed Actors remote transport boundaries. You must strictly mandate that all interactions across distributed actor systems (incorporating WebSocket, QUIC, or custom cluster transports) isolate transport-level disconnects and invocation payload decoding failures. Ensure distributed actor state transitions are fully atomic and fail-safe against partition events. ## Strict Guidelines - Engineers MUST ALWAYS isolate remote calls behind explicit transport failure boundaries that catch `DistributedActorSystemError` and deserialization failures prior to committing state changes. - Engineers MUST NOT mutate local actor state tentatively before receiving confirmation from remote distributed peers unless a verified compensating rollback transaction is registered. - Code SHOULD implement explicit circuit-breaking and idempotent retry semantics inside the `DistributedActorSystem` transport layer to handle network flakiness across edge-to-client hops. - Services MUST gracefully reject invalid or corrupted payloads during `InvocationDecoder.decodeNextArgument()` without terminating the underlying actor system or crashing peer nodes. - Components NEVER leak raw transport errors to user-facing domain layers; errors must be mapped to deterministic, typed domain or connectivity states. ## Bad vs Good Implementations ### Handling Inbound Deserialization and Outbound Partition Boundaries in Swift 6 #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The local state is mutated optimistically without a compensation boundary or transactional rollback mechanism. If the distributed transport fails due to a network partition, the mutation is retained in `pendingMutations`, corrupting local cluster synchronization state without peer consensus. ```swift import Distributed distributed actor ClientSyncEngine { typealias ActorSystem = ClusterTransportSystem var pendingMutations: [UUID: Mutation] = [:] // CRITICAL BUG: State mutated before remote transport confirmation. // Unhandled transport partition leaves actor in an inconsistent partial state. distributed func apply(mutation: Mutation) async throws { pendingMutations[mutation.id] = mutation // Direct call without error boundary; network loss leaves uncommitted mutation indefinitely try await remoteCoordinator.commit(mutationId: mutation.id) } } ``` #### Production Standard (Correct) > **Standard**: Implements an explicit transactional boundary around the distributed call. If a transport partition, message corruption, or decoding failure occurs during `remoteCoordinator.commit`, the local state is cleanly rolled back and a strongly typed domain error is surfaced. ```swift import Distributed distributed actor ClientSyncEngine { typealias ActorSystem = ClusterTransportSystem private var pendingMutations: [UUID: Mutation] = [:] distributed func apply(mutation: Mutation) async throws { // Guard against duplicate execution in idempotent edge environments guard pendingMutations[mutation.id] == nil else { throw DistributedSyncError.duplicateOperation(mutation.id) } pendingMutations[mutation.id] = mutation do { try await remoteCoordinator.commit(mutationId: mutation.id) } catch let transportError as ClusterTransportError { // Rollback local state on transport partition or deserialization failure pendingMutations.removeValue(forKey: mutation.id) throw DistributedSyncError.transportPartition(underlying: transportError) } catch { pendingMutations.removeValue(forKey: mutation.id) throw DistributedSyncError.internalExecutionFailure(error) } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Swift 6 Distributed Actor Remote Transport & Deserialization Failure Boundary

Swift 6 Distributed Actor Remote Transport & Deserialization Failure Boundary defines an industrial-grade behavioral standard for mobile engineering. Enforces strict fault-isolation boundaries and transactional state rollbacks across Swift 6 distributed actor systems operating over edge-to-client networks. Prevents split-brain state mutations and orphan lifecycle states caused by unhandled transport disconnects and invocation deserialization failures. Mandates that all distributed calls wrap remote transport invocations in idempotent, circuit-broken compensations with explicit lifecycle verification. 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: Mutating Local Distributed Actor State Prior to Remote Invalidation or Without Inbound Deserialization Isolation 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	Mutating Local Distributed Actor State Prior to Remote Invalidation or Without Inbound Deserialization Isolation	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 isolate remote calls behind explicit transport failure boundaries that catch `DistributedActorSystemError` and deserialization failures prior to committing state changes.

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.