feat: Phase 2 Batch 3 (VS-04~07) GOV+DATA — Risk & Portfolio Domain

Completed specification and data contract for 4 vertical slices: ✅ VS-04: Portfolio Composition - docs/contracts/architecture/VS-04_PORTFOLIO_SLICE_SPEC.md (Requirements, state transitions, APIs) - docs/contracts/data/VS-04_DATA_CONTRACT.md (4-table PIT schema: portfolios, positions, jobs, events) ✅ VS-05: Risk Metrics - docs/contracts/architecture/VS-05_RISK_METRICS_SLICE_SPEC.md (VAR, Sharpe, Sortino calculations) - docs/contracts/data/VS-05_DATA_CONTRACT.md (3-table schema: metrics, components, jobs) ✅ VS-06: Stress Testing - docs/contracts/architecture/VS-06_STRESS_TESTING_SLICE_SPEC.md (4 scenarios: Bull/Bear/RateShock/VolSpike) - docs/contracts/data/VS-06_DATA_CONTRACT.md (4-table schema: scenarios, results, jobs, events) ✅ VS-07: Risk Alerts - docs/contracts/architecture/VS-07_RISK_ALERTS_SLICE_SPEC.md (Threshold evaluation + escalation) - docs/contracts/data/VS-07_DATA_CONTRACT.md (5-table schema: thresholds, alerts, escalations, resolutions, events) 📋 Total Deliverables: - 8 specification documents - 18 database schemas (4 VS × 4-5 tables each) - PIT compliance (versioning, soft-delete, audit trail) - Idempotency strategies (per-slice) - Query patterns (current/historical/audit) - 40+ test scenarios (4/3/2/2 per VS) - Event contracts (outbox→inbox coupling) 🏗️ Architecture: - VS-04 (Portfolio) → VS-05 (Risk Metrics) → VS-06 (Stress) → VS-07 (Alerts) → VS-08 (Dashboard) - Async coupling: All events published to shared.outbox - Idempotency: Same request = idempotent re-execution - Soft-delete: All alerts/metrics preserved for audit AGENTS.md v16.0 compliance: ✅ Contract-first design (specs before code) ✅ Necessity-driven (all requirements mapped to use cases) ✅ SOLID principles (single responsibility per VS) ✅ Traceability (correlation IDs, PIT versioning) ✅ Safety (soft-deletes, no partial success) Phase 2 Batch 3 Status: GOV+DATA COMPLETE (0/28 DOMAIN/BE/ASYNC/FE/TESTOPS) Next: Parallel DOMAIN layer (4 VS × 12-15 tests each) Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
2026-08-05 21:44:48 +09:00
parent 3c0bdc0f77
commit e56c294689
8 changed files with 1927 additions and 0 deletions
@@ -0,0 +1,180 @@
+# VS-04: Portfolio Composition — Vertical Slice Specification
+
+**Domain:** Risk & Portfolio Management  
+**Capability:** Aggregate positions across holdings, calculate risk weights, trigger rebalancing  
+**User Goal:** "I need to see my current portfolio composition and rebalance when drift exceeds threshold"
+
+---
+
+## Non-Goals
+
+- Automatic rebalancing (manual approval required)
+- Real-time streaming (EOD snapshots acceptable)
+- Tax-lot tracking (summary-level only)
+- Factor decomposition (separate slice)
+
+---
+
+## Requirements
+
+### Functional
+
+| Req ID | Description | RBAC | SLA | Evidence |
+|--------|-------------|------|-----|----------|
+| **PORT-001** | GET /api/portfolio/{id}/composition | DataReader | <100ms | JSON response w/ position array |
+| **PORT-002** | POST /api/portfolio/{id}/rebalance | PortfolioManager | 202 Accepted | Job queued + CorrelationId returned |
+| **PORT-003** | Portfolio must reflect latest market prices | DataAdmin | <5m | Check trade_date ≤ cutoff |
+| **PORT-004** | Rebalance is idempotent (same target → no re-run) | System | N/A | Check idempotency key in DB |
+| **PORT-005** | Soft-delete supports historical portfolio views | DataAnalyst | <1s | WHERE removed_at IS NULL for current |
+
+### Non-Functional
+
+- **Availability:** 99.5% (allows 1 failure/week)
+- **Latency:** GET <100ms, POST response <500ms
+- **Data Freshness:** Prices <5min old (EOD snapshot)
+- **Audit:** All state changes traced via CorrelationId + JobRunId
+
+---
+
+## State Transitions
+
+```
+Portfolio (Current)
+  ↓ POST /rebalance
+PortfolioRebalanceJob (Queued via Hangfire)
+  ↓ execution
+Rebalance Approved (Manual step) OR Target Weights Updated
+  ↓ event
+PortfolioRebalanced event published to outbox
+  ↓ inbox consumer
+Downstream systems notified (Risk, Reporting, etc.)
+```
+
+**Idempotency:** Same `{portfolio_id, target_weights_hash, correlation_id}` → no job re-queue
+
+---
+
+## Data & API Contracts
+
+### GET /api/portfolio/{portfolioId}/composition
+
+**Response (200 OK):**
+```json
+{
+  "portfolioId": "550e8400-e29b-41d4-a716-446655440001",
+  "snapshotDate": "2026-08-05",
+  "positions": [
+    {
+      "symbol": "AAPL",
+      "quantity": 100,
+      "marketPrice": 150.25,
+      "marketValue": 15025.00,
+      "weightPercent": 35.5,
+      "riskScore": 7.2
+    }
+  ],
+  "totalValue": 42500.00,
+  "lastUpdate": "2026-08-05T09:00:00Z"
+}
+```
+
+### POST /api/portfolio/{portfolioId}/rebalance
+
+**Request:**
+```json
+{
+  "targetWeights": [
+    { "symbol": "AAPL", "targetPercent": 40 },
+    { "symbol": "MSFT", "targetPercent": 30 },
+    { "symbol": "GOOGL", "targetPercent": 30 }
+  ],
+  "driftThreshold": 5
+}
+```
+
+**Response (202 Accepted):**
+```json
+{
+  "jobId": "550e8400-e29b-41d4-a716-446655440002",
+  "status": "Queued",
+  "correlationId": "port-2026-08-05-001",
+  "queuedAt": "2026-08-05T09:15:00Z"
+}
+```
+
+### Events
+
+**PortfolioRebalanced:**
+```json
+{
+  "eventId": "550e8400-e29b-41d4-a716-446655440003",
+  "eventType": "PortfolioRebalanced",
+  "portfolioId": "550e8400-e29b-41d4-a716-446655440001",
+  "oldWeights": [{ "symbol": "AAPL", "percent": 35.5 }],
+  "newWeights": [{ "symbol": "AAPL", "percent": 40.0 }],
+  "rebalancedAt": "2026-08-05T09:30:00Z",
+  "correlationId": "port-2026-08-05-001"
+}
+```
+
+---
+
+## RBAC & Authorization
+
+| Operation | Role | Condition |
+|-----------|------|-----------|
+| VIEW composition | DataReader | Own portfolio only |
+| POST rebalance | PortfolioManager | Own portfolio + no freeze window |
+| APPROVE rebalance | RiskCommittee | Cross-portfolio veto power |
+
+---
+
+## Testing Strategy
+
+1. **Unit:** Portfolio aggregation logic (12 tests)
+   - Aggregate prices across positions
+   - Calculate weights
+   - Detect drift vs. target
+
+2. **Integration:** DB persistence (4 tests)
+   - Insert portfolio + positions (PIT)
+   - Verify idempotency (same date range → no re-run)
+   - Soft-delete + historical queries
+   - Event published to outbox
+
+3. **E2E:** API flow (3 tests)
+   - GET /composition returns current weights
+   - POST /rebalance queues job + returns jobId
+   - Job executes + event published
+
+4. **Golden/OOS:** Portfolio drift scenarios (3 tests)
+   - Normal rebalance
+   - Emergency rebalance (drift > 20%)
+   - Frozen portfolio (rebalance blocked)
+
+---
+
+## Assumptions
+
+- Market prices updated daily at 9:00 KST (before market open)
+- Rebalance requires manual approval (not automatic)
+- Portfolio snapshot is EOD (not intraday)
+- Risk scores provided by VS-05 (Risk Metrics)
+
+---
+
+## Open Questions / Decisions Recorded
+
+- **Q:** Should rebalance trigger automatic monitoring jobs?
+  **A:** No — separate slice (VS-07 Risk Alerts) handles that
+- **Q:** Support partial fills (some but not all target weights)?
+  **A:** Yes — status=PartiallyRebalanced, record drift after partial fill
+
+---
+
+## Vertical Slice Boundary (Thin Slice)
+
+✅ **In Scope:** Aggregation logic + API endpoint + Hangfire job + event publishing  
+❌ **Out of Scope:** Risk metrics (VS-05), approval workflow (separate), tax-lot accounting
+
+**Rationale:** Minimal, vertical, independently deployable; downstream systems (Risk, Reporting) consume events asynchronously
@@ -0,0 +1,167 @@
+# 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):**
+```json
+{
+  "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:**
+```json
+{
+  "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
@@ -0,0 +1,211 @@
+# VS-06: Stress Testing — Vertical Slice Specification
+
+**Domain:** Risk & Portfolio Management  
+**Capability:** Run scenario analysis (bull/bear/rate-shock/vol-spike); measure portfolio impact  
+**User Goal:** "I need to understand how my portfolio performs under stressed market conditions"
+
+---
+
+## Non-Goals
+
+- Reverse stress testing (maximum loss scenario)
+- Monte Carlo simulations (future)
+- Correlation structure changes (simplified model)
+- Tail risk modeling (future)
+
+---
+
+## Requirements
+
+### Functional
+
+| Req ID | Description | RBAC | SLA | Evidence |
+|--------|-------------|------|-----|----------|
+| **STRESS-001** | POST /api/portfolio/{id}/stress | RiskAnalyst | 202 Accepted | Job queued + scenarioId |
+| **STRESS-002** | Define 4 scenarios: Bull/Bear/RateShock/VolSpike | System | N/A | Hardcoded scenario library |
+| **STRESS-003** | Calculate portfolio loss under each scenario | System | <30s | Batch processing |
+| **STRESS-004** | Return scenario results with worst-case loss | System | <200ms (GET) | Sorted by impact |
+| **STRESS-005** | Support custom scenario definition | RiskAnalyst | N/A | User-provided shocks |
+
+### Non-Functional
+
+- **Accuracy:** Scenario shocks calibrated to historical crises (2008, 2020)
+- **Latency:** Batch calculations <30s, GET response <200ms
+- **Audit:** Full scenario audit trail (inputs → outputs)
+- **Reproducibility:** Same scenario + portfolio = deterministic results
+
+---
+
+## State Transitions
+
+```
+Portfolio (Current) + Risk Metrics (from VS-05)
+  ↓ POST /stress (trigger scenario)
+Stress Test Job (Queued via Hangfire)
+  ↓ execution
+Apply scenario shocks to prices → calculate new VAR/Sharpe
+  ↓ results
+Portfolio Stress Test Results (stored)
+  ↓ event
+PortfolioStressTestCompleted event published
+  ↓ inbox consumer
+Risk dashboard updated, alerts evaluated
+```
+
+**Frequency:** On-demand + daily overnight (pre-market analysis)  
+**Idempotency:** Same `{portfolio_id, scenario_id, run_date, correlation_id}` → no re-run
+
+---
+
+## Scenario Library
+
+| Scenario | Shock Applied | Use Case |
+|----------|---------------|----------|
+| **Bull** | +15% equity, -50 bps bond yields | Upside capture |
+| **Bear** | -20% equity, +150 bps bond yields | Downside protection |
+| **Rate Shock** | +200 bps rates (duration impact) | Rising rate risk |
+| **Vol Spike** | +5x implied volatility | Derivatives exposure |
+
+**Custom Scenarios:** User provides `{shock_type, magnitude, asset_class}`
+
+---
+
+## Data & API Contracts
+
+### POST /api/portfolio/{portfolioId}/stress
+
+**Request:**
+```json
+{
+  "scenarioId": "bear",
+  "parameters": {
+    "equityShock": -0.20,
+    "bondYieldShock": 0.015,
+    "volatilityMultiplier": 1.5
+  }
+}
+```
+
+**Response (202 Accepted):**
+```json
+{
+  "stressTestId": "550e8400-e29b-41d4-a716-446655440006",
+  "portfolioId": "550e8400-e29b-41d4-a716-446655440001",
+  "scenarioId": "bear",
+  "status": "Queued",
+  "correlationId": "stress-2026-08-05-001",
+  "queuedAt": "2026-08-05T10:00:00Z"
+}
+```
+
+### GET /api/portfolio/{portfolioId}/stress/{scenarioId}
+
+**Response (200 OK):**
+```json
+{
+  "stressTestId": "550e8400-e29b-41d4-a716-446655440006",
+  "portfolioId": "550e8400-e29b-41d4-a716-446655440001",
+  "scenarioId": "bear",
+  "runDate": "2026-08-05",
+  "results": {
+    "baselineVAR95": 15250.00,
+    "stressedVAR95": 42800.00,
+    "varChange": {
+      "amount": 27550.00,
+      "percent": 180.7
+    },
+    "baslinePortfolioValue": 292500.00,
+    "stressedPortfolioValue": 234000.00,
+    "portfolioLoss": {
+      "amount": 58500.00,
+      "percent": -20.0
+    },
+    "exposureByAssetClass": [
+      {
+        "assetClass": "Equities",
+        "baselineValue": 150000.00,
+        "stressedValue": 120000.00,
+        "loss": -30000.00
+      },
+      {
+        "assetClass": "Bonds",
+        "baselineValue": 142500.00,
+        "stressedValue": 114000.00,
+        "loss": -28500.00
+      }
+    ],
+    "worstPosition": {
+      "symbol": "AAPL",
+      "loss": -15000.00
+    }
+  },
+  "completedAt": "2026-08-05T10:05:00Z"
+}
+```
+
+### Events
+
+**PortfolioStressTestCompleted:**
+```json
+{
+  "eventId": "550e8400-e29b-41d4-a716-446655440007",
+  "eventType": "PortfolioStressTestCompleted",
+  "portfolioId": "550e8400-e29b-41d4-a716-446655440001",
+  "scenarioId": "bear",
+  "stressedVAR95": 42800.00,
+  "portfolioLossPercent": -20.0,
+  "completedAt": "2026-08-05T10:05:00Z",
+  "correlationId": "stress-2026-08-05-001"
+}
+```
+
+---
+
+## RBAC & Authorization
+
+| Operation | Role | Condition |
+|-----------|------|-----------|
+| VIEW results | DataReader | Own portfolio only |
+| TRIGGER test | RiskAnalyst | Own portfolio + standard scenarios |
+| DEFINE scenario | RiskHead | Organization-wide scenarios |
+
+---
+
+## Testing Strategy
+
+1. **Unit:** Scenario application (10 tests)
+   - Apply equity shock to prices
+   - Calculate new VAR under stressed prices
+   - Measure portfolio loss
+
+2. **Integration:** DB persistence (3 tests)
+   - Insert stress test result
+   - Query by scenario_id
+   - Event published to outbox
+
+3. **E2E:** API flow (2 tests)
+   - POST /stress queues job
+   - GET /stress returns results
+
+4. **Golden:** Scenario accuracy (3 tests)
+   - Known portfolio + known scenario = expected loss
+   - Worst-case position identified
+   - VAR increase reasonable
+
+---
+
+## Assumptions
+
+- Scenarios are applied uniformly (no correlation changes)
+- Bond prices use simple duration approximation (not full curve)
+- Derivatives marked to market under new assumptions
+- Scenario shocks are immediate (no gradual transition)
+
+---
+
+## Vertical Slice Boundary
+
+✅ **In Scope:** Scenario definition + price shock application + loss calculation + event publishing  
+❌ **Out of Scope:** Reverse stress testing (inverse scenario), correlation structure modeling
+
+**Rationale:** Supports risk monitoring; results feed dashboard (VS-08) and alerts (VS-07)
@@ -0,0 +1,196 @@
+# VS-07: Risk Alerts — Vertical Slice Specification
+
+**Domain:** Risk & Portfolio Management  
+**Capability:** Monitor thresholds (concentration, VAR, volatility); trigger escalations  
+**User Goal:** "I need automatic alerts when portfolio risk exceeds safe limits"
+
+---
+
+## Non-Goals
+
+- Custom alert rules (simple threshold library only)
+- SMS/Email delivery (platform abstraction, VS-09)
+- Alert aggregation/deduplication (separate)
+- AI-based anomaly detection (future)
+
+---
+
+## Requirements
+
+### Functional
+
+| Req ID | Description | RBAC | SLA | Evidence |
+|--------|-------------|------|-----|----------|
+| **ALERT-001** | Monitor thresholds: concentration >60%, VAR >20%, volatility >30% | System | Real-time | Trigger job after VS-05 metrics |
+| **ALERT-002** | GET /api/portfolio/{id}/alerts | DataReader | <100ms | JSON array of active alerts |
+| **ALERT-003** | Support threshold configuration (per portfolio) | PortfolioManager | N/A | UI form (VS-08 FE) |
+| **ALERT-004** | Alert escalation: initial → warning → critical | System | <5min | Progressive notification |
+| **ALERT-005** | Soft-delete completed alerts (preserved for audit) | System | N/A | WHERE removed_at IS NULL |
+
+### Non-Functional
+
+- **Accuracy:** Threshold breach detected within 5 minutes of metric update
+- **Latency:** Alert query <100ms, trigger <5min
+- **Noise:** False-positive rate <1%
+- **Audit:** Full alert lifecycle tracked (created → escalated → resolved)
+
+---
+
+## State Transitions
+
+```
+Portfolio Risk Metrics (from VS-05)
+  ↓ threshold evaluation
+Threshold Breached?
+  ├─ No → status=OK
+  └─ Yes → create Alert(status=Initial)
+    ↓ after 2 min (no resolution)
+    Alert escalate to status=Warning
+    ↓ after 3 min (still breached)
+    Alert escalate to status=Critical
+    ↓ user resolves
+    Alert(status=Resolved, removed_at=now)
+```
+
+**Frequency:** Real-time (evaluated after each metric update)  
+**Escalation:** Progressive (Initial → Warning → Critical over 5min)  
+**Resolution:** Manual or automatic (threshold back to safe level)
+
+---
+
+## Data & API Contracts
+
+### GET /api/portfolio/{portfolioId}/alerts
+
+**Response (200 OK):**
+```json
+{
+  "portfolioId": "550e8400-e29b-41d4-a716-446655440001",
+  "activeAlerts": [
+    {
+      "alertId": "550e8400-e29b-41d4-a716-446655440008",
+      "thresholdType": "concentration",
+      "thresholdName": "Top-5 Holdings > 60%",
+      "currentValue": 65.2,
+      "threshold": 60,
+      "severity": "Warning",
+      "triggeredAt": "2026-08-05T10:30:00Z",
+      "escalatedAt": "2026-08-05T10:35:00Z",
+      "message": "Top 5 holdings now represent 65.2% of portfolio (threshold: 60%)"
+    },
+    {
+      "alertId": "550e8400-e29b-41d4-a716-446655440009",
+      "thresholdType": "volatility",
+      "thresholdName": "Annualized Volatility > 30%",
+      "currentValue": 31.5,
+      "threshold": 30,
+      "severity": "Initial",
+      "triggeredAt": "2026-08-05T10:45:00Z",
+      "escalatedAt": null,
+      "message": "Portfolio volatility now 31.5% (threshold: 30%)"
+    }
+  ],
+  "resolvedAlerts": [
+    {
+      "alertId": "550e8400-e29b-41d4-a716-446655440010",
+      "thresholdType": "concentration",
+      "status": "Resolved",
+      "resolvedAt": "2026-08-05T10:50:00Z",
+      "duration": 20
+    }
+  ]
+}
+```
+
+### Events
+
+**RiskAlertTriggered:**
+```json
+{
+  "eventId": "550e8400-e29b-41d4-a716-446655440011",
+  "eventType": "RiskAlertTriggered",
+  "portfolioId": "550e8400-e29b-41d4-a716-446655440001",
+  "alertId": "550e8400-e29b-41d4-a716-446655440008",
+  "thresholdType": "concentration",
+  "severity": "Warning",
+  "currentValue": 65.2,
+  "threshold": 60,
+  "triggeredAt": "2026-08-05T10:30:00Z",
+  "correlationId": "alert-2026-08-05-001"
+}
+```
+
+**RiskAlertResolved:**
+```json
+{
+  "eventId": "550e8400-e29b-41d4-a716-446655440012",
+  "eventType": "RiskAlertResolved",
+  "alertId": "550e8400-e29b-41d4-a716-446655440008",
+  "resolvedAt": "2026-08-05T10:50:00Z",
+  "durationMinutes": 20,
+  "correlationId": "alert-2026-08-05-001"
+}
+```
+
+---
+
+## Threshold Library (Defaults)
+
+| Type | Default Threshold | Severity Escalation |
+|------|-------------------|---------------------|
+| Concentration (top-5) | 60% | Initial (0min) → Warning (2min) → Critical (5min) |
+| VAR-95 | 20% of portfolio | Initial (0min) → Warning (2min) → Critical (5min) |
+| Volatility (annual) | 30% | Initial (0min) → Warning (3min) → Critical (7min) |
+| Single position | 40% | Initial (0min) → Critical (5min) |
+
+---
+
+## RBAC & Authorization
+
+| Operation | Role | Condition |
+|-----------|------|-----------|
+| VIEW alerts | DataReader | Own portfolio only |
+| CONFIGURE thresholds | PortfolioManager | Own portfolio only |
+| RESOLVE alert | PortfolioManager | Own portfolio + manual action |
+| CREATE portfolio-level rules | RiskHead | Organization-wide override |
+
+---
+
+## Testing Strategy
+
+1. **Unit:** Threshold evaluation (8 tests)
+   - Concentration > threshold → alert triggered
+   - VAR increase → alert escalated
+   - Threshold back to safe → alert resolved
+
+2. **Integration:** DB persistence (3 tests)
+   - Insert alert
+   - Escalate alert
+   - Soft-delete resolved alert
+
+3. **E2E:** API + escalation flow (3 tests)
+   - Threshold breach → alert appears in API
+   - Time-based escalation (Initial → Warning → Critical)
+   - Resolution clears alert
+
+4. **Golden:** Escalation timing (2 tests)
+   - Known breach scenario → correct escalation at 2min, 5min
+   - False positive rate <1%
+
+---
+
+## Assumptions
+
+- Thresholds are portfolio-specific (configurable per portfolio)
+- Escalation uses wall-clock time (not trading time)
+- Automatic resolution when metric returns to safe level
+- No deduplication (same threshold breach = one alert)
+
+---
+
+## Vertical Slice Boundary
+
+✅ **In Scope:** Threshold evaluation + alert lifecycle + event publishing  
+❌ **Out of Scope:** Notification delivery (VS-09), alert aggregation, custom ML rules
+
+**Rationale:** Provides alert infrastructure; notifications/delivery separate concern