# Non-Functional SLI/SLO Specification (Wallet Platform)

Reference architecture:
- `docs/wallet-implementation-plan-apps-mode.md`
- `docs/wallet-system.txt`

## 1. Purpose
Define measurable service-level indicators (SLIs), service-level objectives (SLOs), and error budgets for the wallet platform across availability, latency, correctness, security, and operations.

This document is the baseline for:
- Phase-gate decisions
- Operational monitoring
- Incident response priorities
- Release readiness sign-off

## 2. Scope
In scope:
- User-facing APIs served by `wallet_web`
- Critical money movement path across `wallet_transfers`, `wallet_limits_fees`, `wallet_risk`, `wallet_ledger`
- Auth flows in `wallet_auth`
- Settlement/reconciliation in `wallet_settlement`
- Event pipeline reliability in `wallet_events`

Out of scope (initial baseline):
- BI dashboard freshness objectives
- Non-critical marketing notification latency

## 3. Definitions
- SLI: Quantitative metric reflecting user/system experience.
- SLO: Target value for an SLI over a compliance window.
- Error budget: Allowable amount of unreliability (100% - SLO).
- Burn rate: Speed at which error budget is consumed.

## 4. Compliance Windows
- Primary window: 30 rolling days
- Secondary window (early warning): 7 rolling days

## 5. SLO Catalog

## 5.1 Availability SLOs
### SLO-A1: API Availability (Public Wallet API)
- SLI: `successful_requests / total_requests`
- Success criteria: HTTP 2xx and expected 4xx (contract-valid business responses).
- Exclusions: Planned maintenance windows (approved and announced).
- Objective: >= 99.95% over 30 days
- Error budget: 0.05% (21m 36s downtime equivalent per 30 days)

### SLO-A2: Auth Endpoint Availability
- SLI: `successful_auth_requests / total_auth_requests`
- Objective: >= 99.97% over 30 days
- Error budget: 0.03%

## 5.2 Latency SLOs
### SLO-L1: Authentication Latency
- SLI: p95 latency of `/auth/login`, `/auth/refresh`
- Objective: p95 < 150 ms (steady-state, excluding external OTP provider latency)

### SLO-L2: Transfer Authorization Latency
- SLI: p95 latency of transfer authorize path before external adapter calls
- Objective: p95 < 250 ms

### SLO-L3: Balance Query Latency
- SLI: p95 latency for `GetWalletBalance`
- Objective: p95 < 120 ms

## 5.3 Correctness and Financial Integrity SLOs
### SLO-C1: Posting Integrity
- SLI: percentage of postings that satisfy double-entry invariants
- Objective: 100.00% invariant compliance
- Notes: Any violation is Sev-1 and release blocker.

### SLO-C2: Idempotency Correctness
- SLI: duplicate command replays returning identical business outcome
- Objective: >= 99.999% correct replay handling

### SLO-C3: Reconciliation Mismatch Rate
- SLI: `(mismatched_records / total_reconciled_records)` daily
- Objective: <= 0.01%

## 5.4 Event Reliability SLOs
### SLO-E1: Outbox Delivery Reliability
- SLI: outbox events delivered and acknowledged within SLA window
- Objective: >= 99.99% within 5 minutes

### SLO-E2: Inbox Duplicate Processing Rate
- SLI: duplicate-consumption side effects observed after dedup
- Objective: <= 0.001%

## 5.5 Async Processing SLOs
### SLO-Q1: Critical Queue Delay
- SLI: p95 wait time for high-priority Oban queues
- Objective: p95 < 30 seconds

### SLO-Q2: Settlement Completion Timeliness
- SLI: settlement jobs completed by batch deadline
- Objective: >= 99.9% batches completed before deadline

## 5.6 Security and Compliance SLOs
### SLO-S1: Token Validation Error Rate
- SLI: invalid token rejections with correct reason and audit event
- Objective: 100% classification accuracy in sampled audits

### SLO-S2: Critical Vulnerability Remediation Time
- SLI: median time to remediate critical vulnerabilities in in-scope apps
- Objective: <= 7 calendar days

### SLO-S3: Audit Event Completeness
- SLI: critical money movement actions with full actor/action/context trace
- Objective: >= 99.99%

## 6. Alerting Thresholds
- Availability breach warning: 7-day projected burn rate > 2x.
- Availability breach critical: 7-day projected burn rate > 4x.
- Latency warning: 3 consecutive 15-minute windows above p95 target.
- Integrity critical: any invariant failure event.
- Queue delay critical: p95 wait > 2x target for 30 minutes.

## 7. Error Budget Policy
1. If burn rate exceeds 2x for 24 hours:
- Freeze non-essential feature releases for impacted domain.
- Require reliability fix plan.

2. If burn rate exceeds 4x:
- Immediate incident command activation.
- Stop new feature deploys to impacted path until stabilized.

3. If financial integrity SLO violated:
- Immediate Sev-1.
- Execute incident playbook and post-incident controls review.

## 8. Observability Implementation Requirements
Mandatory telemetry dimensions:
- `correlation_id`
- `request_id`
- `user_id` (where permitted)
- `account_id` (where relevant)
- `transfer_id` (where relevant)
- `command_name`
- `event_name`
- `status`
- `error_code`

Mandatory dashboards:
- API availability and latency
- Auth health and OTP outcomes
- Transfer critical path latency
- Ledger posting integrity and reversals
- Outbox/inbox lag and failure rates
- Queue backlog and worker saturation
- Reconciliation mismatch trend

## 9. Phase Gate Alignment
- Phase 0 gate: SLO catalog approved by architecture, security, and operations.
- Phase 3 gate: correctness SLO instrumentation active in CI + staging.
- Phase 5 gate: queue/settlement SLO dashboards live.
- Phase 8 gate: all critical SLOs stable for at least 2 consecutive weeks in pre-prod.

## 10. Ownership Matrix (Initial)
- `wallet_web` + API SLOs: Platform Team
- `wallet_auth` SLOs: Security Team
- `wallet_ledger` integrity SLOs: Financial Domain Team
- Event reliability SLOs: Platform + Eventing Owners
- Settlement/reconciliation SLOs: Settlement Team
- Compliance/audit SLOs: Compliance Team

## 11. Review Cadence
- Weekly: burn-rate and threshold review
- Sprint boundary: SLO trend and gate readiness
- Quarterly: objective recalibration based on observed workload and business SLAs