Svelte 5 Deep Rune Reactive Graph Mutation Boundary Enforcement

--- description: Svelte 5 Deep Rune Reactive Graph Mutation Boundary Enforcement - Enforces strict boundaries around Svelte 5 deep reactive proxies ($state) across asynchronous microtask schedules. Prohibits incremental deep object mutations interspersed with 'await' boundaries to eliminate reactive graph desynchronization, infinite effect loops, and partial UI state tearing. globs: src/**/*.{svelte,svelte.ts,svelte.js,ts} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/svelte-5-deep-rune-async-mutation-boundary" --- # Svelte 5 Deep Rune Reactive Graph Mutation Boundary Enforcement > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Asynchronous Deep Proxy Mutation across Microtask Boundaries without Snapshot Isolation ## System Constraints You are a Principal Frontend Architect enforcing strict reactive boundary invariants in Svelte 5. You must prevent partial-state tearing and non-deterministic graph recalculations caused by interleaved mutations of deep reactive proxies across async microtasks. ## Strict Guidelines - Engineers MUST NOT incrementally mutate deep properties of a '$state' proxy across asynchronous suspension points ('await'). - Engineers MUST capture pure JavaScript snapshots via '$state.snapshot()' prior to passing reactive state into asynchronous workers, serialization pipelines, or multi-step fetch routines. - Engineers MUST compute all async results in disconnected, unproxied local structures and apply the final mutation to '$state' in a single synchronous turn. - Engineers MUST NEVER execute state mutations or side effects within '$derived' or '$derived.by' blocks; derivations must remain strictly pure projections. - Engineers SHOULD utilize '$state.raw' for large collections, streams, or foreign instances that do not require deep reactive proxy instrumentation. ## Bad vs Good Implementations ### Atomic Commit vs. Interleaved Asynchronous Proxy Mutation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Mutating deep properties of '$state' before and after multiple 'await' operations exposes incomplete intermediate states to dependent '$derived' runes and template bindings across microtasks. If a consumer cancels or triggers a concurrent run, the reactive graph becomes desynchronized and suffers race conditions. ```typescript interface UserSession { id: string; profile: { name: string; avatarUrl: string; status: 'idle' | 'updating' | 'ready' }; permissions: string[]; } let session = $state<UserSession>({ id: 'usr_101', profile: { name: 'Alex', avatarUrl: '', status: 'idle' }, permissions: [] }); async function updateProfile(newName: string, avatarFile: Blob) { // Anti-pattern: Interleaved deep mutations across microtasks cause reactive tear session.profile.status = 'updating'; session.profile.name = newName; const avatarUrl = await uploadService.upload(avatarFile); // Suspended microtask boundary: reactive subscribers see an inconsistent partial state session.profile.avatarUrl = avatarUrl; const perms = await fetchPermissions(session.id); session.permissions = perms; session.profile.status = 'ready'; } ``` #### Production Standard (Correct) > **Standard**: State dependencies are snapshotted safely using '$state.snapshot()', all async resolution is contained within pure local variables, and the reactive state is mutated atomically in a single synchronous microtask tick, preventing intermediate visual tearing and reactive graph desynchronization. ```typescript interface UserSession { id: string; profile: { name: string; avatarUrl: string; status: 'idle' | 'updating' | 'ready' }; permissions: string[]; } let session = $state<UserSession>({ id: 'usr_101', profile: { name: 'Alex', avatarUrl: '', status: 'idle' }, permissions: [] }); async function updateProfile(newName: string, avatarFile: Blob) { // Isolate current state snapshot from the reactive proxy const currentSnapshot = $state.snapshot(session); session.profile.status = 'updating'; try { // Execute all asynchronous work on untracked, pure local data const [avatarUrl, perms] = await Promise.all([ uploadService.upload(avatarFile), fetchPermissions(currentSnapshot.id) ]); // Synchronous atomic commit back into the reactive graph session.profile = { name: newName, avatarUrl, status: 'ready' }; session.permissions = perms; } catch (error) { session.profile.status = 'idle'; throw error; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Deep Rune Reactive Graph Mutation Boundary Enforcement

Svelte 5 Deep Rune Reactive Graph Mutation Boundary Enforcement defines an industrial-grade behavioral standard for frontend engineering. Enforces strict boundaries around Svelte 5 deep reactive proxies ($state) across asynchronous microtask schedules. Prohibits incremental deep object mutations interspersed with 'await' boundaries to eliminate reactive graph desynchronization, infinite effect loops, and partial UI state tearing. 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 Deep Proxy Mutation across Microtask Boundaries without Snapshot 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	Asynchronous Deep Proxy Mutation across Microtask Boundaries without Snapshot 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 NOT incrementally mutate deep properties of a '$state' proxy across asynchronous suspension points ('await').

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.