feat(V2-FE-020): standardize query keys and projection-aware cache invalidation

[reactjay]

Summary

Implements V2-FE-020: canonical TanStack Query key factories for all projection namespaces, projection-aware cache invalidation from confirmed on-chain transactions and WebSocket stream events, and distinct representation of observed/safe/finalized/reorged finality states.

---

Acceptance Criteria Evidence

Criterion	Evidence
Canonical query keys for claims, evidence, rounds, disputes, rewards, reputation, and wallet state	queryKeys.ts — all 8 namespaces as immutable as const tuples; 37 unit tests verify no collisions
Invalidate from confirmed transactions and projection-stream events without cache-wide churn	useProjectionInvalidation.ts (7 action kinds) + useRealtimeData.ts (8 WS handlers); every call targets the narrowest key; tests assert disputes.all / claims.all are never touched
Observed, safe, finalized, reorged states represented distinctly	finality.ts typed union + deriveFinalityLevel(); useFinalityLevel.ts polls Viem, validates chain ID, writes FinalityCacheEntry per entity
No visual redesign or layout assumption	Only ClaimRewardsPanel.tsx updated to fix a pre-existing API mismatch; no layout/style changes
No synthetic production transaction or protocol state	Mock-wallet and transaction-simulator sources remain test-only; production paths use wagmi + Viem
Documentation and generated artifacts current	disputes.api.ts, disputes.queries.ts, MSW handlers, and all query hooks documented inline
PR maps evidence to every criterion	This table

---

State Transitions

Transaction submitted
  → useWaitForTransactionReceipt (wagmi)
  → useFinalityLevel polls: observed → safe → finalized
  → FinalityCacheEntry written under claims.finality(claimId) or disputes.finality(disputeId)
  → useProjectionInvalidation.invalidate(ctx) called with confirmed ConfirmedTxContext
  → Surgical invalidation of only downstream projection keys
  → Reorg: only finality projection keys evicted; no list/detail churn

WebSocket event received
  → useRealtimeData handler
  → setQueryData (write-through) for full-payload events
  → invalidateQueries targeting narrowest canonical key for partial events

---

Files Changed

New (production)

• src/app/queries/queryKeys.ts — canonical factory for all 8 namespaces
• src/app/types/finality.ts — FinalityLevel, FinalityContext, FinalityResult, deriveFinalityLevel()
• src/hooks/useProjectionInvalidation.ts — 7 action-kind invalidation hook
• src/hooks/useFinalityLevel.ts — wagmi+Viem finality polling with chain validation
• src/app/api/disputes.api.ts — fetchDisputesByClaim, fetchDisputeDetail, createDispute
• src/app/queries/disputes.queries.ts — useDisputesByClaim, useDisputeDetail, useCreateDispute
• src/app/queries/{evidence,rounds,rewards,reputation}.queries.ts — canonical hooks
• src/hooks/useRealtimeData.ts — WS event handlers using canonical key factories

Modified (production)

• src/app/queries/claims.queries.ts — canonical key usage
• src/hooks/useRewards.ts — replaced mock-data with indexer API; wallet-scoped invalidation
• src/components/features/ClaimRewardsPanel.tsx — adapted to new useRewards interface (wei string amounts)

Tests (94 pass)

• unit/queryKeys.test.ts (37) — key shape, collision, and scope invariants
• unit/finality.test.ts (20) — all 4 finality levels, depth, revert passthrough
• unit/useFinalityLevel.test.ts (10) — finalized/safe/observed/reorged/reverted/wrong-network/stale/rejected/cache
• unit/useProjectionInvalidation.test.ts (16) — per-action scope, reorg-only path
• integration/query-key-invalidation.test.tsx (9) — WS→canonical key→surgical update
• integration/disputes-queries.test.tsx (9) — API boundary, mutation scope, isolation
• integration/wallet-viem-boundary.test.tsx (7) — Viem receipt→deriveFinalityLevel→invalidation pipeline

---

Security Notes

• Chain ID validated before writing any finality cache entry or triggering invalidation.
• No fabricated hashes, balances, verdicts, or reward amounts anywhere in the affected paths.
• Reorged transactions bust only finality projections — no collateral cache eviction.
• All amounts from API are exact integer strings (wei precision); no local conversion except for display.

---

Accessibility

No UI components changed beyond fixing a pre-existing API mismatch in ClaimRewardsPanel. No ARIA roles, accessible names, or keyboard paths were modified.

---

Residual Risks

Risk	Mitigation
RPC provider does not expose safe/finalized block tags	useFinalityLevel catches and falls back to observed; tested
WS reconnection gap causes stale projection	useRealtimeData re-subscribes on reconnect; staleness is bounded by staleTime
Dispute resolution race between WS event and tx receipt	Both paths invalidate disputes.detail + rewards.all; idempotent

---

Pre-existing Baseline Failures (not introduced by this PR)

• src/__tests__/accessibility/ — missing jest-axe dev dependency
• src/__tests__/integration/claim-submission.test.tsx — TypeScript syntax error
• src/hooks/__tests__/useAccount.test.ts — TypeScript syntax error
• e2e/happy-path.spec.ts — requires running dev server (CI-only)
• Several hooks/__tests__/ files — wagmi mock configuration mismatch

Closes #251

[dDevAhmed]

resolve conflicts @reactjay