TanStack Query v5: Bounded Serialized Mutation Queuing and Idempotency Guardrail

--- description: TanStack Query v5: Bounded Serialized Mutation Queuing and Idempotency Guardrail - Enforces strict mutation idempotency and deterministic serial execution for offline-capable frontend clients using TanStack Query v5. Prevents out-of-order replays, duplicate resource creation, and poison-pill queue blockages during network transitions via mutation scopes, client-side idempotency keys, and bounded storage. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/tanstack-query-v5-offline-mutation-queuing-deduplication" --- # TanStack Query v5: Bounded Serialized Mutation Queuing and Idempotency Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Unscoped, Non-Idempotent Mutation Replay Causing Race Conditions and Duplicate Writes on Network Recovery ## System Constraints You are a Principal Software Architect enforcing deterministic offline mutation management in TanStack Query v5. Mandate serial mutation queues via scope IDs, client-side idempotency keys, bounded storage limits, and safe poison-pill eviction to guarantee consistency across intermittent connectivity. ## Strict Guidelines - Engineers MUST ALWAYS assign an explicit `scope.id` to mutations targeting the same resource or aggregate root to guarantee sequential (FIFO) execution upon network reconnect. - Engineers MUST ALWAYS generate an immutable client-side `idempotencyKey` (UUIDv4/ULID) at the point of user action and attach it to both the mutation payload and request headers. - Engineers MUST NOT issue state-modifying mutations using default un-scoped execution if the application enables persistent offline storage (`persistQueryClient`). - Mutations targeting persistent offline synchronization MUST set `networkMode: 'offlineFirst'` to prevent mutations from failing immediately while disconnected. - Mutation caches MUST enforce a bounded maximum queue size and maximum retry threshold to evict unrecoverable poison-pill mutations without halting subsequent queued actions. - Components NEVER trigger mutations with dynamic, transient parameters (like timestamps) as the idempotency identifier; IDs must remain deterministic across multiple rehydration cycles. ## Bad vs Good Implementations ### Offline Mutation Setup: Unscoped/Non-Idempotent vs. Scoped/Idempotent Queue #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: When the client loses connectivity, multiple edits to the same document queue up un-scoped. Upon reconnecting, TanStack Query executes all paused mutations concurrently, resulting in race conditions where an older edit can overwrite a newer one. Without an idempotency key, intermittent timeouts trigger duplicate writes on the backend. ```typescript import { useMutation, useQueryClient } from '@tanstack/react-query'; interface UpdateDocumentVariables { documentId: string; content: string; } export function useUpdateDocument() { const queryClient = useQueryClient(); // ANTI-PATTERN: Lacks scope.id (mutations execute in parallel upon reconnect), // lacks idempotency key (retries cause duplicate processing), // and defaults to networkMode: 'online' (rejects immediately when offline). return useMutation({ mutationFn: async ({ documentId, content }: UpdateDocumentVariables) => { const response = await fetch(`/api/documents/${documentId}`, { method: 'PATCH', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ content }) }); if (!response.ok) throw new Error('Update failed'); return response.json(); }, onSuccess: (data, variables) => { queryClient.invalidateQueries({ queryKey: ['documents', variables.documentId] }); } }); } ``` #### Production Standard (Correct) > **Standard**: Enforces verified production invariants and compliant error handling. ```typescript import { useMutation, useQueryClient } from '@tanstack/react-query'; interface UpdateDocumentVariables { documentId: string; content: string; idempotencyKey: string; } export function useUpdateDocument() { const queryClient = useQueryClient(); return useMutation({ mutationKey: ['updateDocument'], // Invariant: scope.id serializes mutations per document; networkMode offlineFirst queues while offline scope: { id: 'mutation-scope-document' }, networkMode: 'offlineFirst', retry: 3, mutationFn: async ({ documentId, content, idempotencyKey }: UpdateDocumentVariables) => { const response = await fetch(`/api/documents/${documentId}`, { method: 'PATCH', headers: { 'Content-Type': 'application/json', 'X-Idempotency-Key': idempotencyKey }, body: JSON.stringify({ content, idempotencyKey }) }); if (!response.ok) { // Unrecoverable client error: throw non-retriable error to prevent queue poisoning if (response.status >= 400 && response.status < 500 && response.status !== 409) { const errorPayload = await response.json().catch(() => ({})); throw Object.assign(new Error('Fatal Client Mutation Error'), { fatal: true, errorPayload }); } throw new Error(`Transient mutation error: ${response.statusText}`); } return response.json(); }, onSettled: (_data, _error, variables) => { queryClient.invalidateQueries({ queryKey: ['documents', variables.documentId] }); } }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: TanStack Query v5: Bounded Serialized Mutation Queuing and Idempotency Guardrail

TanStack Query v5: Bounded Serialized Mutation Queuing and Idempotency Guardrail defines an industrial-grade behavioral standard for frontend engineering. Enforces strict mutation idempotency and deterministic serial execution for offline-capable frontend clients using TanStack Query v5. Prevents out-of-order replays, duplicate resource creation, and poison-pill queue blockages during network transitions via mutation scopes, client-side idempotency keys, and bounded storage. 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: Unscoped, Non-Idempotent Mutation Replay Causing Race Conditions and Duplicate Writes on Network Recovery 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	Unscoped, Non-Idempotent Mutation Replay Causing Race Conditions and Duplicate Writes on Network Recovery	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 assign an explicit `scope.id` to mutations targeting the same resource or aggregate root to guarantee sequential (FIFO) execution upon network reconnect.

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.