feat(backend): API snapshots, error boundary, governance export, idempotency retention

[success-OG]

closes #638
closes #860
closes #703
closes #720

PR description
Summary
This PR delivers four backend governance and reliability improvements: extended API contract snapshots for high-traffic list endpoints, wired typed upstream error boundary middleware, a historical governance snapshot export API, and policy-driven idempotency retention cleanup with metrics.

Task 1 — API contract snapshots
Problem: CI only guarded GET /health and GET /ready. Vault and transaction list endpoints could regress without detection.

Changes:

Extended CRITICAL_ENDPOINTS with GET /api/v1/vault/summary and GET /api/v1/transactions
Added Zod schemas: VaultSummaryResponseSchema, TransactionItemSchema, PaginationMetaSchema, TransactionsListResponseSchema
Added ZodArray support in zodToJsonShape() and array diffing in diffSchemaShapes()
Committed new snapshots:
schema-snapshots/get-_api_v1_vault_summary.json
schema-snapshots/get-_api_v1_transactions.json
Aligned OpenAPI: VaultSummary schema, Transaction.status, PaginationMeta.limit, list response timestamp
Documented snapshot workflow in backend/README.md and scripts/check-schema-snapshots.ts
Extended issues711.test.ts with vault/transaction validation cases
CI: Existing backend-governance.yml snapshots:check step covers the new endpoints automatically.

Task 2 — Typed error boundary middleware
Problem: Redis/DB/RPC failures needed standardized typed API errors with stable codes and retry hints.

Changes:

Wired errorBoundaryMiddleware import in index.ts (middleware already existed with full classifier + tests)
Maps DatabaseError, RedisError, RpcError, CircuitOpenError, SorobanSimulationError, Prisma errors, and wallet scope violations to typed JSON responses with Retry-After headers

Task 3 — Historical governance snapshot export API
Problem: Reconciliation snapshots, config changes, and export manifests existed in storage but had no unified governance reporting surface.

Changes:

New governanceSnapshotExport.ts aggregating:
ReconciliationSnapshot (Prisma)
AdminConfigChange (via listAdminConfigChanges)
ExportManifest (Prisma)
New admin endpoints:
GET /admin/governance/snapshots — paginated list with type, start, end filters
POST /admin/governance/snapshots/export — export with immutable manifest via createExportManifest
Tests in governanceSnapshotExport.test.ts

Task 4 — Idempotency retention cleanup
Problem: Idempotency relied on Redis TTL only; no scheduled sweep, metrics, or admin controls for stale records.

Changes:

IdempotencyStore.pruneStaleKeys() — sweeps local NodeCache and Redis idempotency:* keys by createdAt / TTL
New idempotencyRetention.ts with policy (IDEMPOTENCY_KEY_TTL_MS, IDEMPOTENCY_RETENTION_SWEEP_MS, IDEMPOTENCY_RETENTION_ENABLED), scheduled sweeps, and metrics
New admin endpoints:
GET /admin/idempotency/retention/metrics
POST /admin/idempotency/retention/cleanup (supports dryRun)
Scheduler started on server boot with graceful shutdown hook
Tests in idempotencyRetention.test.ts

[drips-wave]

@success-OG Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits