feat(analytics): Core payment reliability and latency percentile computation engine (#383)

[s6pa1rta3n-lab]

Summary of Changes & Root Cause Analysis

Root Cause

The repository lacked a core payment-reliability and latency-percentile computation engine to evaluate payment corridor performance, compute bounded-error quantile metrics (P50/P90/P95/P99), and generate deterministic off-chain aggregate snapshots for on-chain reconciliation. Without explicit two-clock event-time handling and watermarking, delayed or out-of-order ledger events could corrupt window calculations or disagree with finalized reconciliation periods.

Key Implementations

1. DDSketch Streaming Quantiles (backend/src/analytics/sketch.rs):

   • Implemented logarithmic binning quantile sketch with mathematically provable relative error bound $\alpha = 0.01$ (1%).
   • Exact, lossless mergeability ( \oplus S_2$) enabling distributed map-reduce aggregation across shards.
   • Zero and edge value handling, quantile queries (P50, P75, P90, P95, P99, P99.9), and statistical summaries.

2. Multi-Status Payment Reliability (backend/src/analytics/reliability.rs):

   • Tracks granular outcomes: Success, Failed, TimedOut, and Rejected.
   • Dynamic corridor routing (PaymentCorridor) and SLA breach tracking against configurable threshold (default 2000ms).
   • High-throughput counters, mergeable reliability state, availability percentage, and SLA breach ratios.

3. Two-Clock Domain Separation & Skew Detection (backend/src/analytics/clock.rs):

   • Explicit domain distinction: {ledger}$ (Ledger consensus timestamp) vs {ingest}$ (Ingestion wall-clock time).
   • Settlement latency, ingestion lag, and client end-to-end metrics with timestamp precedence policies.
   • Clock skew anomaly detection (ClockSkewMonitor) with Prometheus warning counters.

4. Monotonic Watermarking & Window State Machine (backend/src/analytics/watermark.rs):

   • Bounded out-of-order event handling with monotonic watermark advancement: (t) = \max(T) - \Delta$.
   • Window lifecycle states: Active $\to$ Finalized $\to$ Amended.
   • Explicit configurable late-event arrival policies: DropAndRecord, SideOutput, and RetroactiveUpdate.

5. Reconciliation Subsystem Integration (backend/src/analytics/reconciliation_bridge.rs):

   • Implemented WatermarkedAggregateStore adhering to OffChainAggregateStore trait.
   • Aligns reconcilable_periods() strictly with watermarked finalized windows ({end} \le W(t)$).
   • Generates deterministic SHA-256 cryptographic snapshot hashes (snapshot_hash and source_data_hash) for zero-tolerance on-chain agreement verification.

6. Observability & Integration Tests (backend/src/observability/metrics.rs & tests/payment_analytics_test.rs):

   • Prometheus metrics for latency quantiles, reliability ratios, SLA breaches, late events, and clock skew.
   • 6 end-to-end integration tests covering DDSketch quantile accuracy across distributions, watermark convergence, late event policies, clock separation, reconciliation agreement, and 50k-event ingestion burst.

Fixes #383

Payout Routing

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