feat(snippets): record per-snippet blockchain verification history

[JemimahEkong]

Closes #195

Summary

Snippets are anchored on Stellar via the recovery engine, but the only durable record of a verification was a single mutable column on snippets (on_chain_hash, transaction_hash, verified_at) — retried and reprocessed transactions overwrote it, leaving no audit trail. This PR maintains an append-only history of blockchain verification events per snippet (transaction hash, ledger sequence, timestamp, confirmation status) and exposes it via a new public API endpoint.

Changes

Migration (scripts/migrations/004_add_snippet_verification_history.sql)

• New snippet_verification_history table with a real FK to snippets.id, UNIQUE transaction hash, status (pending/confirmed/failed), ledger sequence, error message, and timestamps
• Indexed on (snippet_id, created_at ASC) for chronological lookups
• Idempotent (CREATE TABLE IF NOT EXISTS); updated_at maintained at the application layer since the migration runner executes statements individually

Recording (lib/stellar-recovery.service.ts)

• Events written at the three existing confirmation points in submitToHorizon(): pending on submission, confirmed after pollForConfirmation (with ledger sequence + verified_at), failed on retryable/permanent failure
• Batch transactions expand to one event per referenced snippet via the existing collectSnippetIds() helper
• Writes are best-effort — logged on failure, never abort the transaction flow, matching the existing memo-association pattern

Idempotency

• INSERT … ON CONFLICT (transaction_hash) DO UPDATE, same pattern as snippet_transactions.linkPending() — reprocessing merges ledger/verified_at via COALESCE, with a guard so confirmed rows are never downgraded

New endpoint — GET /api/snippets/[id]/verification-history

• Public read, consistent with sibling routes (verification-audit, transaction-status)
• 400 invalid UUID, 404 unknown snippet, 200 chronological history with limit/offset pagination (default 20, max 100)

Testing

• Event recording at submit/confirm/fail points, batch expansion, and non-blocking failure handling
• Repository-level upsert semantics, ordering, pagination, and BIGINT coercion
• Route-level 400/404/200 paths, ordering, and pagination metadata
• 36/36 new + pre-existing related suites passing; 135/135 across the full app/api/snippets test folder

Deploy notes

Run migration 004_add_snippet_verification_history.sql via scripts/run-optimization-migration.ts (auto-picked up) or manually against production.

[vercel]

@JemimahEkong is attempting to deploy a commit to the Sudipta 's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@JemimahEkong 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