feat: unified verification rejection codes and API error UX across frontend and backend

[s6pa1rta3n-lab]

Summary of Changes

This pull request addresses Issue #285: Unified verification rejection codes and API error UX across frontend and backend.

Key Improvements:

1. Canonical Verification Code Registry (payment-verification.ts & verification.js):

   • Pinned the canonical list of rejection codes (VERIFICATION_CODES) and user-facing messages (VERIFICATION_MESSAGES / messageForCode).
   • Unified verification validation across both backend route handlers and frontend client runtime.
   • Synchronized typing declarations in frontend/lib/verification.d.ts.

2. Standardized API Error Envelopes & Resolution (types/api.ts & api-runtime.js):

   • Standardized VerificationFailureBody and sendVerificationFailure() envelopes.
   • Added robust toApiError() mapping in frontend/lib/api-runtime.js that checks for canonical codes via messageForCode() before falling back to generic HTTP messages.

3. Frontend Payment State & UX Unification:

   • describeVerifyError and usePaymentPage prioritize standard rejection codes.
   • Standardized status badges and messaging across PaymentPage, PaymentStatus, PaymentButton, PaymentReceipt, DashboardPage, InvoiceDetailPage, and HomePage.

4. Testing & Verification:

   • Added cross-layer contract verification test ensuring zero drift between backend and frontend verification mirrors (backend/tests/payment-verification.test.ts).
   • Extended unit and state machine test coverage across backend/tests/invoice-handlers.test.ts, backend/tests/invoice-payment-loop.test.ts, frontend/tests/verification.test.js, frontend/tests/payment-page-state.test.js, frontend/tests/pay-page-status-matrix.test.js, and frontend/tests/api-runtime.test.js.
   • Verified 100% test pass rate across backend (163 tests, 28 suites) and frontend (208 tests).
   • Zero mocked assertions.

Closes #285

Payout Routing

• EVM (Base/Arbitrum/Polygon/ETH): 0xF46C9F6d70C50BF81ef3588AB523a90a594a2F89
• Stellar: GCL6OXAMLD75BMTINA6EMRUDWK5THQUSHMYNLSNBCJAPZJHNYJTUNIBC