KArtSell.Aegis/docs/contracts/data/VS-06_DATA_CONTRACT.md

VS-06: Stress Testing — Data Contract

Version: 1.0
Compliance: Append-Only (immutable test results)
Migration: 0035_stress_testing.sql (DbUp)

---

Schema Design

1. stress_scenarios (Configuration — Immutable)

Pre-defined scenario templates. New scenarios versioned; active scenarios = latest revision.

CREATE TABLE risk_management.stress_scenarios (
    scenario_id VARCHAR(50) PRIMARY KEY,
    
    -- Metadata
    scenario_name VARCHAR(255) NOT NULL,
    description TEXT,
    scenario_type VARCHAR(50), -- 'Predefined', 'Custom'
    
    -- Shock parameters (JSON-encoded for flexibility)
    shocks JSONB NOT NULL, -- { "equityShock": -0.20, "bondYieldShock": 0.015, ... }
    
    -- Version control (for scenario evolution)
    version INT NOT NULL DEFAULT 1,
    effective_date DATE,
    deprecated_date DATE NULL,
    
    -- Audit
    created_by VARCHAR(100),
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    
    UNIQUE(scenario_id, version),
    CHECK (deprecated_date IS NULL OR deprecated_date >= effective_date)
);

2. stress_test_results (Append-Only — Immutable Results)

Immutable record of each stress test execution.

CREATE TABLE risk_management.stress_test_results (
    stress_test_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    portfolio_id UUID NOT NULL REFERENCES risk_management.portfolios(portfolio_id),
    
    -- Scenario
    scenario_id VARCHAR(50) NOT NULL REFERENCES risk_management.stress_scenarios(scenario_id),
    scenario_version INT NOT NULL,
    run_date DATE NOT NULL,
    
    -- Baseline (from portfolio snapshot)
    baseline_portfolio_value DECIMAL(20, 2),
    baseline_var_95 DECIMAL(20, 2),
    baseline_sharpe DECIMAL(5, 3),
    
    -- Stressed (after shock application)
    stressed_portfolio_value DECIMAL(20, 2),
    stressed_var_95 DECIMAL(20, 2),
    stressed_sharpe DECIMAL(5, 3),
    
    -- Impact metrics
    portfolio_loss_amount DECIMAL(20, 2),
    portfolio_loss_percent DECIMAL(5, 2),
    var_increase_amount DECIMAL(20, 2),
    var_increase_percent DECIMAL(5, 2),
    
    -- Asset class breakdown
    stress_results_by_class JSONB, -- Array of {assetClass, baselineValue, stressedValue, loss}
    worst_position JSONB,           -- {symbol, loss}
    
    -- Status
    status VARCHAR(50) NOT NULL DEFAULT 'Completed', -- Queued, Running, Completed, Failed
    started_at TIMESTAMP NULL,
    completed_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    duration_seconds INT NULL,
    
    -- Quality
    quality_flags JSONB,            -- Array of strings (e.g., ["missing_price_data"])
    
    -- Audit
    correlation_id UUID NOT NULL,
    job_run_id UUID NOT NULL,
    triggered_by VARCHAR(100),      -- 'Manual', 'Scheduler'
    
    -- Idempotency
    UNIQUE(portfolio_id, scenario_id, run_date, correlation_id)
);

3. stress_test_jobs (Append-Only — Execution Log)

Immutable log of job executions.

CREATE TABLE risk_management.stress_test_jobs (
    job_id UUID PRIMARY KEY,
    stress_test_id UUID NOT NULL REFERENCES risk_management.stress_test_results(stress_test_id),
    
    -- Execution
    status VARCHAR(50) NOT NULL DEFAULT 'Queued',
    started_at TIMESTAMP NULL,
    completed_at TIMESTAMP NULL,
    duration_seconds INT NULL,
    
    -- Error handling
    error_message TEXT NULL,
    retry_count INT DEFAULT 0,
    
    -- Audit
    correlation_id UUID NOT NULL,
    job_run_id UUID NOT NULL,
    
    -- Metadata
    portfolio_id UUID NOT NULL,
    scenario_id VARCHAR(50) NOT NULL,
    run_date DATE NOT NULL,
    
    UNIQUE(portfolio_id, scenario_id, run_date, correlation_id)
);

4. stress_test_events (Append-Only — Published Events)

Published to shared.outbox.

Schema (JSONB in outbox.payload):

{
  "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"
}

---

Query Patterns

Current Stress Test Results

SELECT
    scenario_id,
    baseline_portfolio_value,
    stressed_portfolio_value,
    portfolio_loss_percent,
    var_increase_percent,
    completed_at
FROM risk_management.stress_test_results
WHERE
    portfolio_id = @portfolioId
    AND run_date = CURRENT_DATE
ORDER BY portfolio_loss_percent DESC;

Worst-Case Scenario (Most Loss)

SELECT TOP 1
    scenario_id,
    portfolio_loss_amount,
    portfolio_loss_percent
FROM risk_management.stress_test_results
WHERE
    portfolio_id = @portfolioId
    AND run_date = @date
ORDER BY portfolio_loss_percent ASC;

Scenario Trend (Historical)

SELECT
    run_date,
    scenario_id,
    portfolio_loss_percent
FROM risk_management.stress_test_results
WHERE
    portfolio_id = @portfolioId
    AND scenario_id = @scenarioId
ORDER BY run_date DESC
LIMIT 30;

Idempotency Check

SELECT stress_test_id FROM risk_management.stress_test_results
WHERE
    portfolio_id = @portfolioId
    AND scenario_id = @scenarioId
    AND run_date = @date
    AND correlation_id = @correlationId
    AND status = 'Completed'
LIMIT 1;

---

Indexes

Table	Columns	Reason
stress_scenarios	(scenario_id, version)	Fast scenario lookup
stress_test_results	(portfolio_id, run_date)	Fast daily result queries
stress_test_results	(scenario_id)	Fast scenario trend analysis
stress_test_results	(portfolio_id, scenario_id, run_date, correlation_id)	Fast idempotency check
stress_test_jobs	(portfolio_id, status)	Fast pending job lookup

---

Upsert Strategy

On new stress test request:

INSERT INTO risk_management.stress_test_results
    (stress_test_id, portfolio_id, scenario_id, run_date, correlation_id, status)
VALUES
    (@testId, @portfolioId, @scenarioId, @date, @correlationId, 'Queued')
ON CONFLICT (portfolio_id, scenario_id, run_date, correlation_id)
    DO UPDATE SET
        status = 'Queued'
    WHERE EXCLUDED.status = 'Completed';

Idempotency: Same portfolio_id + scenario_id + run_date + correlation_id → no duplicate test

---

Pre-loaded Scenarios

On fresh install, load 4 predefined scenarios:

INSERT INTO risk_management.stress_scenarios VALUES
    ('bull', 'Bull Market Scenario', '+15% equities, -50 bps yields', 'Predefined', 
     '{"equityShock": 0.15, "bondYieldShock": -0.005, "volatilityMultiplier": 0.8}', 1, CURRENT_DATE, NULL),
    
    ('bear', 'Bear Market Scenario', '-20% equities, +150 bps yields', 'Predefined',
     '{"equityShock": -0.20, "bondYieldShock": 0.015, "volatilityMultiplier": 1.5}', 1, CURRENT_DATE, NULL),
    
    ('rateShock', 'Interest Rate Shock', '+200 bps all yields', 'Predefined',
     '{"bondYieldShock": 0.02, "volatilityMultiplier": 1.2}', 1, CURRENT_DATE, NULL),
    
    ('volSpike', 'Volatility Spike', '5x implied vol', 'Predefined',
     '{"volatilityMultiplier": 5.0}', 1, CURRENT_DATE, NULL);

---

Compliance

✅ AGENTS.md v16.0:

• Append-only results (stress_test_results immutable)
• Correlation ID tracing (correlation_id + job_run_id)
• Idempotency key (portfolio_id + scenario_id + run_date + correlation_id)
• Quality flags recorded (quality_flags JSONB)
• Deterministic results (same input → same output)

✅ Auditability:

• Full execution history preserved (stress_test_jobs)
• All shocks recorded (shocks JSONB)
• Baseline + stressed values stored
• Event published for downstream consumption

---

Test Scenarios

Test	Data Setup	Assertion
Bear scenario	Portfolio + bear shocks	Portfolio loss ~20%
Bull scenario	Portfolio + bull shocks	Portfolio gain ~12%
Asset class impact	Mixed portfolio	Equities impacted more than bonds
Idempotency	Same test twice	Result retrieved, not recalculated
Worst position	Mixed holdings	Worst-case position identified correctly
Quality flags	Missing price data	quality_flags includes "missing_price_data"