KArtSell.Aegis/docs/contracts/architecture/VS-05_RISK_METRICS_SLICE_SPEC.md

VS-05: Risk Metrics — Vertical Slice Specification

Domain: Risk & Portfolio Management
Capability: Calculate VAR, Sharpe, Sortino, concentration metrics; publish to dashboard
User Goal: "I need real-time risk metrics to monitor portfolio health and trigger alerts"

---

Non-Goals

• Stress testing scenarios (VS-06)
• Risk alerts & notifications (VS-07)
• Factor decomposition (future)
• Machine-learning risk modeling (future)

---

Requirements

Functional

Req ID	Description	RBAC	SLA	Evidence
RISK-001	GET /api/portfolio/{id}/risk	DataReader	<200ms	JSON w/ VAR/Sharpe/Sortino
RISK-002	Calculate VAR (95% confidence, 1-day horizon)	System	<5s	Daily batch job
RISK-003	Calculate Sharpe ratio (252-day rolling)	System	<5s	Daily batch job
RISK-004	Concentration metrics (top-N holdings %)	System	<1s	Cache-friendly calculation
RISK-005	Publish metrics to outbox for downstream	System	<100ms	PortfolioMetricsCalculated event

Non-Functional

• Accuracy: VAR model validated against historical data
• Latency: Batch calculations <5min, GET response <200ms
• Caching: Results cached <1hr (metrics refresh daily)
• Audit: All metric changes traced via CorrelationId

---

State Transitions

Portfolio (Current) — from VS-04
  ↓ DailyRiskCalculationJob (9:30 KST, after market open)
Risk Metrics Calculated (VAR, Sharpe, Sortino, concentration)
  ↓ event
PortfolioMetricsCalculated event published to outbox
  ↓ inbox consumer
Risk dashboard updated, alerts evaluated (VS-07)

Frequency: Daily after market open (9:30 KST)
Idempotency: Same {portfolio_id, calculation_date, correlation_id} → no re-run

---

Data & API Contracts

GET /api/portfolio/{portfolioId}/risk

Response (200 OK):

{
  "portfolioId": "550e8400-e29b-41d4-a716-446655440001",
  "calculationDate": "2026-08-05",
  "metrics": {
    "valueAtRisk95": {
      "amount": 15250.00,
      "percent": 5.2,
      "horizon": "1-day",
      "confidence": 0.95
    },
    "sharpeRatio": {
      "ratio": 1.85,
      "riskFreeRate": 0.045,
      "rollingDays": 252
    },
    "sortinoRatio": {
      "ratio": 2.45,
      "downsideDeviation": 0.082
    },
    "concentration": {
      "topFivePercent": 52.3,
      "hirschman": 0.18,
      "maxSinglePosition": 40.0
    },
    "volatility": {
      "annualized": 0.185,
      "rollingDays": 30
    }
  },
  "lastUpdate": "2026-08-05T09:30:00Z",
  "dataQuality": "Complete"
}

Events

PortfolioMetricsCalculated:

{
  "eventId": "550e8400-e29b-41d4-a716-446655440004",
  "eventType": "PortfolioMetricsCalculated",
  "portfolioId": "550e8400-e29b-41d4-a716-446655440001",
  "calculatedAt": "2026-08-05T09:30:00Z",
  "metrics": {
    "var95": 15250.00,
    "sharpe": 1.85,
    "sortino": 2.45,
    "concentration": 52.3
  },
  "correlationId": "risk-2026-08-05-001"
}

---

RBAC & Authorization

Operation	Role	Condition
VIEW metrics	DataReader	Own portfolio only
TRIGGER calculation	RiskAnalyst	Manual override (unusual)
APPROVE metrics	RiskCommittee	For reporting purposes

---

Testing Strategy

1. Unit: Metric calculations (15 tests)

   • VAR computation (95% confidence)
   • Sharpe ratio (rolling 252-day)
   • Sortino ratio (downside deviation)
   • Concentration detection

2. Integration: DB persistence (4 tests)

   • Insert risk metrics snapshot
   • Historical metric queries
   • Event published to outbox
   • Idempotency check

3. E2E: API flow (2 tests)

   • GET /risk returns current metrics
   • Daily job execution completes

4. Golden: Metric accuracy (3 tests)

   • Known portfolio → expected VAR/Sharpe
   • High concentration → concentration flag
   • Low volatility → low Sharpe

---

Assumptions

• Historical price data available (from VS-03)
• Risk-free rate 4.5% (configurable)
• 252 trading days per year
• No intraday rebalancing (EOD snapshot only)
• VAR model: Parametric (assumes normal distribution)

---

Vertical Slice Boundary

✅ In Scope: Metric calculations + API endpoint + daily batch job + event publishing
❌ Out of Scope: Stress testing (VS-06), alerts (VS-07), risk approval workflows

Rationale: Metrics feed downstream systems (dashboard, alerts); published asynchronously via events