React 19 Server Action Client-Side UUIDv7 Idempotency Standard

--- description: React 19 Server Action Client-Side UUIDv7 Idempotency Standard - Enforces client-synthesized UUIDv7 idempotency keys on all state-mutating React 19 Server Actions paired with optimistic updates. Guarantees exactly-once mutation semantics across spotty mobile network reconnections, duplicate form submissions, and automated retry loops. Prevents duplicated side effects such as repeat charges, duplicate ledger entries, and orphaned database rows. globs: src/**/*.{ts,tsx}, app/**/*.{ts,tsx}, components/**/*.{ts,tsx}, actions/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-19-server-action-idempotency-key-standard" --- # React 19 Server Action Client-Side UUIDv7 Idempotency Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Submitting Blind Server Actions and Optimistic State Without Client-Generated Idempotency Keys ## System Constraints You are a Principal Software Architect enforcing client-side idempotency invariants across React 19 Server Actions and optimistic updates. You MUST mandate that every state-mutating Server Action accepts a client-synthesized UUIDv7 token as a first-class argument or hidden form field. Enforce that components retain this key across retries and mobile network handoffs, guaranteeing exactly-once execution semantics. ## Strict Guidelines - Engineers MUST ALWAYS synthesize a cryptographically secure UUIDv7 token on the client prior to invoking a mutating React 19 Server Action. - Engineers MUST NOT generate idempotency keys inside the Server Action scope or rely on server-side request timestamps for mutation deduplication. - Components MUST retain the current mutation's idempotency key in component state or a ref until the transaction is finalized or dismissed by the user. - Optimistic updates using `useOptimistic` MUST map the optimistic entity ID to the synthesized UUIDv7 idempotency key to prevent reconciliation thrashing. - Form actions leveraging native HTML form submissions MUST inject the UUIDv7 token via an explicit hidden input named `idempotencyKey`. - Server Action implementations MUST persist the incoming idempotency key in an atomic deduplication store (e.g., Redis `SET NX EX`) before triggering irreversible side effects. ## Bad vs Good Implementations ### React 19 Server Action with Client-Synthesized UUIDv7 Idempotency Key #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The client dispatches the Server Action without a stable mutation identifier. If the network drops packets during a cellular tower switch or the user submits rapidly, the server processes multiple independent transactions, leading to duplicate financial transfers. ```typescript 'use client'; import { useActionState, useOptimistic } from 'react'; import { transferFundsAction } from '@/actions/transfers'; export function TransferForm({ accountId }: { accountId: string }) { // ANTI-PATTERN: No idempotency key provided by the client. // A mobile cell handoff or quick double-tap can trigger duplicate transfers. const [state, formAction, isPending] = useActionState(transferFundsAction, null); const [optimisticState, setOptimistic] = useOptimistic( state, (current, amount: number) => ({ ...current, balance: (current?.balance ?? 0) - amount }) ); return ( <form action={async (formData: FormData) => { const amount = Number(formData.get('amount')); setOptimistic(amount); await formAction(formData); // Unsafe: no unique mutation fingerprint }}> <input type="number" name="amount" required /> <button type="submit" disabled={isPending}>Transfer</button> </form> ); } ``` #### Production Standard (Correct) > **Standard**: Generates a time-ordered UUIDv7 on the client and attaches it to both the form payload and optimistic state. Re-transmissions of the same form submission reuse the identical key, enabling the backend to deduplicate requests via Redis or database unique constraints. ```typescript 'use client'; import { useActionState, useOptimistic, useState } from 'react'; import { uuidv7 } from 'uuidv7'; import { transferFundsAction } from '@/actions/transfers'; export function TransferForm({ accountId }: { accountId: string }) { // PRODUCTION FIX: Generate and anchor a client-side UUIDv7 key per distinct mutation intent const [idempotencyKey, setIdempotencyKey] = useState<string>(() => uuidv7()); const [state, formAction, isPending] = useActionState(transferFundsAction, null); const [optimisticState, setOptimistic] = useOptimistic( state, (current, update: { amount: number; key: string }) => ({ ...current, pendingTransferId: update.key, balance: (current?.balance ?? 0) - update.amount, }) ); async function handleSubmit(formData: FormData) { const amount = Number(formData.get('amount')); formData.set('idempotencyKey', idempotencyKey); setOptimistic({ amount, key: idempotencyKey }); await formAction(formData); // Rotate idempotency key ONLY after successful dispatch to prepare for next mutation setIdempotencyKey(uuidv7()); } return ( <form action={handleSubmit}> <input type="hidden" name="idempotencyKey" value={idempotencyKey} /> <input type="hidden" name="accountId" value={accountId} /> <input type="number" name="amount" required min="1" /> <button type="submit" disabled={isPending}>Transfer</button> </form> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React 19 Server Action Client-Side UUIDv7 Idempotency Standard

React 19 Server Action Client-Side UUIDv7 Idempotency Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces client-synthesized UUIDv7 idempotency keys on all state-mutating React 19 Server Actions paired with optimistic updates. Guarantees exactly-once mutation semantics across spotty mobile network reconnections, duplicate form submissions, and automated retry loops. Prevents duplicated side effects such as repeat charges, duplicate ledger entries, and orphaned database rows. 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: Submitting Blind Server Actions and Optimistic State Without Client-Generated Idempotency Keys 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	Submitting Blind Server Actions and Optimistic State Without Client-Generated Idempotency Keys	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 synthesize a cryptographically secure UUIDv7 token on the client prior to invoking a mutating React 19 Server Action.

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.