Fix reconcile optimistic role updates against the real paginated cache (closes #243)

[didi168]

Description

Optimistic updates for role assignment were already substantially built (onMutate/onError/onSettled, snapshot+rollback, toasts, a "Saving" badge) — but the post-success reconciliation path was silently dead in production: it only ever checked the bare ['members'] cache key, while the real Members page caches under a composite, filter-dependent key ([...queryKeys.members.all, { searchQuery }]) holding a paginated useInfiniteQuery shape. Every successful mutation was falling through to a full invalidateQueries refetch instead of the surgical patch it was built to do — reintroducing the exact round-trip sluggishness this issue exists to eliminate, just moved to after the mutation instead of before. This fixes that seam, brings removeRole to parity with assignRole on error toasts, and adds a way to actually simulate and test mutation failures in mock mode.

Linked Issue

Closes #243

Type of Change

• 🐛 Bug fix (UI or API integration)
• ✨ New feature / component
• 🎨 UI/UX improvement
• 📝 Documentation update
• 🔧 Chore / refactor / dependency update
• 🧪 Tests only

Changes Made

Reconciliation seam (lib/query/member-cache.ts)

• reconcileMemberRoleCache now uses getQueriesData/setQueriesData (prefix match) instead of getQueryData/setQueryData (exact match), so it actually reaches the real composite-keyed, paginated cache entry instead of silently missing it.
• Patches every matching cache entry at once (e.g. an unfiltered list and a filtered search view cached simultaneously both update from one mutation).
• For assign, only patches entries where the address already exists — never fabricates the { tier: 'free', active: true } placeholder row into an entry that doesn't already contain it (a differently-filtered page, for instance). Falls back to invalidateQueries only when the address isn't found in any entry, preserving the "fetch real data for a brand-new member" correctness guarantee.

Toast parity (app/admin/members/page.tsx)

• removeRoleMutation's onError never called addToast (only set local state) — assignRole's did. Both mutations now show the same error toast (session-expiry vs. generic failure, distinguished the same way), and both show a success toast.

Simulate-able mock failures (lib/api/mock.ts, app/developer/page.tsx)

• setMockRoleMutationFailure(shouldFail) — a runtime-togglable flag (unlike the module-load-time NEXT_PUBLIC_MOCK_SESSION_STATE), checked by assignRole/removeRole, throwing a generic 500 distinct from the existing session-expiry simulation. Cleared by resetMockData().
• A "Simulate Role Mutation Failure" toggle on /developer so this is manually triggerable, not just usable from tests.

Tests

• test/member-cache.test.ts rewritten around the real composite/paginated shape (10 cases) — including the regression test that would have failed against the old bare-key implementation, and the two "don't fabricate into an unrelated filtered entry" cases.
• test/role-assignment-optimistic.test.ts (new) — integration tests wiring a real QueryClient + real MockAccessApi + real reducers/reconciliation together (no React rendering), one test per acceptance criterion: instant optimistic appearance during an artificially slow mutation, rollback via the new failure toggle, and no duplicate/ghost rows after that same mutation succeeds.
• test/mock-controls.test.ts — 5 new cases for the failure toggle itself.

Screenshots / Recordings

Not captured — built and verified via dev-server + curl rather than an interactive browser session. Please add a screenshot/recording of the role-assignment optimistic flow (instant update, then a triggered failure + rollback via the new /developer toggle) before merging.

Before	After
todo	todo

Test Evidence

• Tested in mock mode (NEXT_PUBLIC_MOCK_MODE=true)
• Tested against live guildpass-core — not applicable; this is entirely a frontend cache-reconciliation fix, no API contract changes

Verified via dev server + curl: /admin/members and /developer both compile clean, and the new toggle renders correctly. Unit suite: 12 new/updated tests, all passing. Full suite shows the exact same 15 pre-existing failing tests present before this branch (confirmed by diffing the failing-test-name list directly, not just the summary count — unrelated to this change: policy-listing contract drift, SIWE nonce, session storage, etc.). Typecheck: zero new errors at both the test/tsconfig.json scope (20-error baseline) and full-project scope (44-error baseline), confirmed by diffing full compiler output before/after, not just eyeballing counts.

Checklist

• I have read CONTRIBUTING.md
• This PR is linked to an open issue
• npm run typecheck passes for this branch's own changes — no new errors introduced; main already carries pre-existing errors unrelated to this work (documented in ASSUMPTIONS.md)
• npm run lint passes on all new/changed files
• New components work in mock mode
• Loading, empty, and error states are handled (toast + rollback message on failure, "Saving" badge while pending)
• No inline styles — Tailwind classes used throughout
• No secrets or API keys included
• .env.example updated — not needed, no new env vars (the failure toggle is a runtime function, not an env var)
• Accessibility: unchanged from existing patterns (toast, badge, form labels already accessible)

Additional Notes

• The reconciliation bug was silent because test/member-cache.test.ts only ever tested the bare-key/plain-array shape, never the real composite/paginated one the page actually uses — worth keeping in mind for future cache-adjacent changes: test against the actual query key shape, not a simplified stand-in.
• didi168 expressed interest in taking this issue — worth checking in before merging in case they'd already started work in parallel.