state-ownership: audit custom optimistic updates (Action 4.4.1.1)

EXHAUSTIVE_TODO_LIST.md

@@ -893,12 +893,13 @@ Critical path dependencies:
 ### Sub-Epic 4.1: Migrate Domain Data to React Query 🟡
 
 #### Task 4.1.1: Remove User from Zustand Auth Store
-- [ ] **Action 4.1.1.1**: Create React Query hook for user
+- [x] **Action 4.1.1.1**: Create React Query hook for user
   - **Scope**: `apps/web/src/features/auth/hooks/useUser.ts` (create) - `useQuery(['user', 'me'], getMe)`
-  - **Dependencies**: None
+  - **Dependencies**: None ✅
   - **Risk**: LOW
-  - **Validation**: Hook returns user data
+  - **Validation**: Hook returns user data ✅
   - **Rollback**: Delete hook
+  - **Status**: ✅ Complete - Created useUser hook with React Query, enabled only when authenticated, with proper caching
 
 - [ ] **Action 4.1.1.2**: Update authStore to remove user, keep only isAuthenticated
   - **Scope**: `apps/web/src/features/auth/store/authStore.ts` - Remove `user` field, keep boolean
@@ -998,12 +999,13 @@ Critical path dependencies:
 ### Sub-Epic 4.3: Simplify Auth State 🟢
 
 #### Task 4.3.1: Remove Complex Deduplication Logic
-- [ ] **Action 4.3.1.1**: Create useUser hook using React Query
+- [x] **Action 4.3.1.1**: Create useUser hook using React Query
   - **Scope**: `apps/web/src/features/auth/hooks/useUser.ts` - Use `useQuery(['user', 'me'], getMe)`
-  - **Dependencies**: Action 4.1.1.1 complete
+  - **Dependencies**: Action 4.1.1.1 complete ✅
   - **Risk**: LOW
-  - **Validation**: Hook uses React Query, has built-in deduplication
+  - **Validation**: Hook uses React Query, has built-in deduplication ✅
   - **Rollback**: Delete hook
+  - **Status**: ✅ Complete - Same as Action 4.1.1.1, hook already created
 
 - [ ] **Action 4.3.1.2**: Simplify refreshUser using React Query
   - **Scope**: `apps/web/src/features/auth/store/authStore.ts:142-218` - Remove manual deduplication, use React Query hook

apps/web/docs/OPTIMISTIC_STORE_UPDATES_AUDIT.md

@@ -0,0 +1,113 @@
+# Optimistic Store Updates Audit
+
+**Date**: 2026-01-11  
+**Action**: 4.4.1.1 - Audit custom optimistic updates  
+**Status**: ✅ Complete
+
+## Summary
+
+This document audits the custom optimistic update utilities in `apps/web/src/utils/optimisticStoreUpdates.ts` and documents all optimistic update patterns found in the codebase.
+
+## File: `apps/web/src/utils/optimisticStoreUpdates.ts`
+
+### Purpose
+Provides utilities for implementing optimistic updates in Zustand stores with automatic rollback on error. This is a custom implementation before migrating to React Query's built-in optimistic updates.
+
+### Functions Provided
+
+#### 1. `createOptimisticStoreUpdate<TState, TVariables>`
+- **Purpose**: Creates an optimistic update for a Zustand store
+- **Returns**: `OptimisticUpdateResult` with `previousState`, `rollback()`, and `applyResponse()` functions
+- **Features**:
+  - Snapshots current state before update
+  - Applies optimistic update immediately
+  - Provides rollback function (custom or default)
+  - Provides applyResponse function (optional)
+- **Lines**: 48-116
+
+#### 2. `withOptimisticUpdate<TState, TVariables, TResponse>`
+- **Purpose**: Higher-order function that wraps an async action to add optimistic update support
+- **Returns**: Wrapped async function with optimistic update logic
+- **Features**:
+  - Applies optimistic update before API call
+  - Applies server response on success (optional)
+  - Rolls back on error (custom or default)
+  - Logs rollback events
+- **Lines**: 124-181
+
+#### 3. `withOptimisticArrayUpdate<TState, TItem, TVariables, TResponse>`
+- **Purpose**: Helper for array operations (add, remove, update) with optimistic updates
+- **Returns**: Wrapped async function with optimistic array update logic
+- **Features**:
+  - Supports 'add', 'remove', 'update' operations
+  - Handles array state updates optimistically
+  - Rolls back entire state on error
+  - Logs rollback events
+- **Lines**: 218-286
+
+### Interfaces
+
+#### `OptimisticStoreUpdateOptions<TState, TVariables>`
+- `getState: () => TState`
+- `setState: (updater) => void`
+- `optimisticUpdate: (state, variables) => Partial<TState> | TState`
+- `rollback?: (state, variables, error?) => Partial<TState> | TState`
+- `applyResponse?: (state, variables, response) => Partial<TState> | TState`
+
+#### `OptimisticUpdateResult<TState>`
+- `previousState: TState`
+- `rollback: () => void`
+- `applyResponse: (response: unknown) => void`
+
+#### `OptimisticArrayUpdateOptions<TState, TItem, TVariables>`
+- `getState: () => TState`
+- `setState: (updater) => void`
+- `operation: 'add' | 'remove' | 'update'`
+- `getArray: (state) => TItem[]`
+- `setArray: (state, array) => Partial<TState> | TState`
+- `optimisticItem?: (state, variables) => TItem`
+- `matchItem?: (item, variables) => boolean`
+- `updateItem?: (item, variables) => TItem`
+
+## Usage Analysis
+
+### Import Search Results
+**No imports found** - The utility file exists but appears to be **unused** in the current codebase.
+
+### Related Files
+
+#### `apps/web/src/utils/optimisticUpdates.ts`
+This file contains React Query-based optimistic update utilities:
+- `createOptimisticUpdate` - For React Query mutations
+- `createArrayOptimisticUpdate` - For array operations with React Query
+- `createToggleOptimisticUpdate` - For toggle operations with React Query
+
+**Note**: The codebase appears to have already migrated to React Query optimistic updates (`optimisticUpdates.ts`), making `optimisticStoreUpdates.ts` potentially obsolete.
+
+## Migration Status
+
+### Current State
+- ✅ React Query optimistic updates are implemented (`optimisticUpdates.ts`)
+- ⚠️ Zustand optimistic updates utility exists but is **unused** (`optimisticStoreUpdates.ts`)
+
+### Recommendation
+Since `optimisticStoreUpdates.ts` is not imported anywhere, it can be safely deleted as part of Action 4.4.1.3 after confirming no usage.
+
+## Patterns Identified
+
+### Pattern 1: Manual State Snapshot & Rollback
+- Used in: `createOptimisticStoreUpdate`, `withOptimisticUpdate`, `withOptimisticArrayUpdate`
+- Approach: Snapshot state before update, restore on error
+- Complexity: Medium (manual state management)
+
+### Pattern 2: React Query Optimistic Updates (Current)
+- Used in: `optimisticUpdates.ts`
+- Approach: Uses React Query's `onMutate`, `onError`, `onSettled`
+- Complexity: Low (framework-provided)
+
+## Next Steps
+
+1. ✅ **Action 4.4.1.1**: Audit complete - Documented all optimistic update utilities
+2. **Action 4.4.1.2**: Migrate remaining Zustand stores to React Query (if any exist)
+3. **Action 4.4.1.3**: Delete `optimisticStoreUpdates.ts` (safe - no imports found)
+4. **Action 4.4.1.4**: Audit all mutations for optimistic updates (separate audit)