feat(indexer): add gap detection and ledger event replay on startup

[Hexstar-labs]

Summary

Implements startup gap detection and ledger event replay for the Stellar indexer. Previously, StellarIndexer tracked progress via indexer_checkpoints.last_processed_ledger but
had no way to recover missed BetPlaced/MarketResolved/etc. events after a restart or downtime — a missed event meant permanent data inconsistency.

Closes #29

Changes

backend/src/indexer/StellarIndexer.ts

• detectAndReplayGap(): Promise<ReplayResult> — compares indexer_checkpoints.last_processed_ledger against the current RPC ledger sequence on startup. If the gap exceeds
  INDEXER_MAX_REPLAY_LEDGERS, emits a Sentry.captureMessage at warning level and skips straight to the current ledger instead of replaying.
• replayLedgerRange(from, to): Promise<ReplayResult> — replays missed ledgers in batches:
  • Fetches each batch concurrently via Promise.allSettled (one fetch per ledger), so a single failed fetch doesn't abort the rest of the batch.
  • Persists events idempotently via INSERT ... ON CONFLICT (tx_hash) DO NOTHING on blockchain_events, routing only genuinely-new events through the existing handlers
    (processEvent).
  • Advances the checkpoint only after a full batch commits — never mid-batch — so a crash during replay re-does at most one batch.
  • Rate-limited to one batch per second (INDEXER_REPLAY_BATCH_SIZE ledgers/batch, default 50) to avoid Horizon/RPC throttling.
  • Invalidates the Redis cache (cacheDeletePattern) for every market touched by a replayed event.
  • Logs a structured summary at INFO level: { gap_size, replayed_events, skipped_duplicates, duration_ms }.
• Extracted fetchLedgerEvents/insertEventIfNew helpers shared with the existing live-event path (processLedger), which keeps its original ON CONFLICT ... DO UPDATE semantics
  unchanged — replay and live processing now share fetch logic but persist differently by design (replay needs strict dedup, live/backfill refreshes stale rows).
• Wired detectAndReplayGap() into startIndexer() as a non-blocking background call so it never delays subscribing to the live event stream, per the issue's guidelines.
• Added a defensive checkpoint resync inside the polling loop (lastProcessed = Math.max(lastProcessed, await getLastProcessedLedger())) to prevent the live poll loop from
  regressing the checkpoint if the background replay advances it concurrently.

backend/src/config/env.ts / backend/.env.example

• Added INDEXER_REPLAY_BATCH_SIZE (default 50) and INDEXER_MAX_REPLAY_LEDGERS (default 10000, ~14 hours of ledgers).

backend/tests/integration/indexer-replay.test.ts (new)
Fully mocked (Postgres pool, Stellar RPC server, Sentry, cache service, logger) — no infra required:

• Replays a 100-ledger gap and verifies the checkpoint only advances after the batch commits.
• Idempotency: replaying the same ledger range twice does not double-insert blockchain_events (second pass reports skipped_duplicates instead of re-processing).
• Max-gap guard: a 15,000-ledger gap triggers a Sentry warning and skips replay entirely, jumping the checkpoint straight to the current ledger.
• No-op path: checkpoint already at the current ledger emits a zero-gap result without touching the RPC.

Test plan

• npx tsc --noEmit — no new type errors introduced
• npx eslint on changed files — no new lint errors (pre-existing repo lint debt unrelated to this change is untouched)
• npx jest tests/integration/indexer-replay.test.ts — 4/4 passing
• Verified against a real Postgres + Redis (Docker, matching CI's service containers) — no regressions in the existing indexer.test.ts handler tests caused by this change
• Reviewer to confirm INDEXER_REPLAY_BATCH_SIZE / INDEXER_MAX_REPLAY_LEDGERS defaults are acceptable for production Horizon rate limits