feat(indicators): chart Dispersion Index via DSPX

Yahoo history is too short; search and charts consume DataFactory's Cboe archive plus yfinance tail.

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/data-layer.md

@@ -212,7 +212,7 @@ working with them in practice:
 | Domain | Backing source | Typical access path | Notes |
 |--------|----------------|---------------------|-------|
 | Market prices | yfinance | `get("AAPL")`, `get("S&P 500")`, `get("Shanghai Composite")` | Handles tickers and index aliases |
-| Market indicators | Registry-backed market series | `get("VIX")`, `get("MOVE")`, `get("Net Breadth")` | Mix of yfinance-backed and private-series-backed names resolved before raw tickers |
+| Market indicators | Registry-backed market series | `get("VIX")`, `get("MOVE")`, `get("Net Breadth")`, `get("Dispersion Index")` | Mix of yfinance-backed and private-series-backed names resolved before raw tickers |
 | Economic series | FRED | `get_fred_data("UNRATE")`, `get("Unemployment Rate")` | Human-readable names map to FRED codes |
 | Computed macro indicators | FRED-derived logic | `get("Buffett Indicator")` | Built from public series |
 | Credit and risk indicators | FRED and FRED-derived | `get("High Yield Spread")`, `get("Net Liquidity")` | HY spread, RRP, net liquidity, 18M forward rate spread, credit spread |
@@ -324,6 +324,7 @@ Examples:
 
 - `Fear & Greed` when used as a chart/searchable series
 - `Net Breadth` as a chart/searchable breadth history series
+- `Dispersion Index` (Cboe DSPX archive + yfinance tail) as a chart/searchable series
 - future chartable private series such as `CAPE` or
   `Trailing-Forward P/E Spread`, if promoted into the chart/search flow
 

src/TerraFin/data/factory.py

@@ -226,7 +226,7 @@ class DataFactory:
         on fetch failure — the next non-force caller still sees the prior
         value. Currently only the yfinance-backed path honors the flag;
         composite/private indicators (Vol Regime, VVIX/VIX, Fear & Greed,
-        CAPE, SPX GEX, Net Breadth) ignore it.
+        CAPE, SPX GEX, Dispersion Index, Net Breadth) ignore it.
 
         Exception semantics:
         * ``force_refresh=False`` (default): swallow upstream fetch errors

src/TerraFin/data/providers/market/market_indicator.py

@@ -292,6 +292,18 @@ def _trailing_forward_pe_full_history_backfill(_key: str, *, loaded_start: str |
     return _private_backfill("trailing_forward_pe", loaded_start)
 
 
+def _fetch_dspx(_key: str):
+    return _private_frame("dspx")
+
+
+def _dspx_recent_history(_key: str, *, period: str = "3y") -> HistoryChunk:
+    return _private_recent("dspx", period)
+
+
+def _dspx_full_history_backfill(_key: str, *, loaded_start: str | None = None) -> HistoryChunk:
+    return _private_backfill("dspx", loaded_start)
+
+
 def _spx_gex_frame() -> TimeSeriesDataFrame:
     from TerraFin.data.providers.market.spx_gex_history import get_spx_gex_history
 
@@ -358,6 +370,13 @@ MARKET_INDICATOR_REGISTRY = {
     "Treasury-10Y": MarketIndicator(description="Treasury-10Y", key="^TNX"),
     "Treasury-30Y": MarketIndicator(description="Treasury-30Y", key="^TYX"),
     "MOVE": MarketIndicator(description="MOVE: ICE BofA MOVE Index (bond market implied volatility)", key="^MOVE"),
+    "Dispersion Index": MarketIndicator(
+        description="DSPX: Cboe S&P 500 Dispersion Index. Expected 30-day idiosyncratic dispersion from SPX and constituent options.",
+        key="dspx",
+        get_data=_fetch_dspx,
+        get_recent_history=_dspx_recent_history,
+        get_full_history_backfill=_dspx_full_history_backfill,
+    ),
     "Vol Regime": MarketIndicator(
         description="VIX 6-month percentile rank (0-100). Calm below 20 and elevated above 80.",
         key="vol-regime",

src/TerraFin/data/providers/private_access/series_registry.py

@@ -24,4 +24,10 @@ PRIVATE_SERIES: dict[str, PrivateSeriesSpec] = {
         display_name="Trailing-Forward P/E Spread",
         history_cache_namespace="private_trailing_forward_pe_history",
     ),
+    "dspx": PrivateSeriesSpec(
+        key="dspx",
+        display_name="Dispersion Index",
+        history_cache_namespace="private_dspx_history",
+        current_cache_namespace="private_dspx_current",
+    ),
 }

tests/data/test_credit_risk_indicators.py

@@ -69,6 +69,16 @@ def test_net_breadth_in_market_registry():
     assert MARKET_INDICATOR_REGISTRY["Net Breadth"].key == "net-breadth"
 
 
+def test_dispersion_index_in_market_registry():
+    """Dispersion Index (DSPX) should be exposed as a searchable market series."""
+    from TerraFin.data.providers.market import MARKET_INDICATOR_REGISTRY
+
+    assert "Dispersion Index" in MARKET_INDICATOR_REGISTRY
+    indicator = MARKET_INDICATOR_REGISTRY["Dispersion Index"]
+    assert indicator.key == "dspx"
+    assert "DSPX" in indicator.description
+
+
 def test_vol_regime_recent_history_uses_progressive_yfinance_seed(monkeypatch) -> None:
     def _stub_recent_history(ticker: str, *, period: str = "3y") -> HistoryChunk:
         assert ticker == "^VIX"

tests/data/test_dspx_history.py

@@ -0,0 +1,13 @@
+"""Dispersion Index is a searchable private-series market indicator (DSPX)."""
+
+from TerraFin.interface.infra.ticker_search.routes import _search_indicators
+
+
+def test_search_indicators_finds_dispersion_and_dspx():
+    by_dispersion = _search_indicators("dispersion")
+    by_dspx = _search_indicators("dspx")
+    assert any(entry["symbol"] == "Dispersion Index" for entry in by_dispersion)
+    assert any(entry["symbol"] == "Dispersion Index" for entry in by_dspx)
+    match = next(entry for entry in by_dspx if entry["symbol"] == "Dispersion Index")
+    assert match["group"] == "Market"
+    assert "DSPX" in match["name"]

tests/interface/test_search_routing_api.py

@@ -43,3 +43,17 @@ def test_resolve_ticker_routes_net_breadth_to_market_insights() -> None:
         "name": "Net Breadth",
         "path": "/market-insights?ticker=Net%20Breadth",
     }
+
+
+def test_resolve_ticker_routes_dispersion_index_to_market_insights() -> None:
+    client = TestClient(create_app())
+
+    response = client.get("/resolve-ticker?q=dispersion%20index")
+    assert response.status_code == 200
+    payload = response.json()
+
+    assert payload == {
+        "type": "macro",
+        "name": "Dispersion Index",
+        "path": "/market-insights?ticker=Dispersion%20Index",
+    }