Add versioned market regime plugin contract

Author: Pigbibi

docs/examples/strategy_plugins.example.toml

@@ -3,11 +3,72 @@ default_mode = "shadow"
 
 [[strategy_plugins]]
 strategy = "tqqq_growth_income"
-plugin = "crisis_response_shadow"
+plugin = "market_regime_control"
+enabled = true
+# Default runtime contract. This facade arbitrates crisis_response_shadow,
+# macro_risk_governor, and taco_rebound_shadow into one deterministic signal.
+# Strategy code consumes only notification and position_control from this
+# artifact; broker writes and live allocation mutation remain disabled.
+
+[strategy_plugins.inputs]
+prices = "data/output/market_regime_control/input/tqqq_price_history.csv"
+external_context = "data/output/market_regime_control/input/external_context.csv"
+event_set = "geopolitical-deescalation"
+benchmark_symbol = "QQQ"
+attack_symbol = "TQQQ"
+vix_symbols = ["VIX", "^VIX", "VIXCLS"]
+credit_pairs = ["HYG:IEF", "LQD:IEF"]
+financial_symbols = ["XLF", "KRE"]
+rate_symbols = ["IEF", "TLT"]
+strategy_policy = "levered_growth_income_v1"
+realized_vol_threshold = 0.30
+realized_vol_requires_confirmation = true
+delever_risk_asset_scalar = 0.0
+taco_opportunity_size_scalar = 0.0
+crisis_enabled = true
+macro_enabled = true
+taco_enabled = true
+
+[strategy_plugins.outputs]
+output_dir = "data/output/tqqq_growth_income/plugins/market_regime_control"
+
+[[strategy_plugins]]
+strategy = "soxl_soxx_trend_income"
+plugin = "market_regime_control"
 enabled = true
-# The runner enforces plugin/strategy compatibility. This plugin is scoped to
-# TQQQ/SOXL leveraged equity black-swan defense strategies.
-# mode is optional when it matches default_mode; only shadow notification mode is supported.
+# SOXL uses the same macro/crisis contract. TACO stays disabled because the
+# current rebound-event playbook is calibrated for TQQQ/QQQ.
+
+[strategy_plugins.inputs]
+prices = "data/output/market_regime_control/input/soxl_price_history.csv"
+external_context = "data/output/market_regime_control/input/external_context.csv"
+event_set = "full"
+benchmark_symbol = "SOXX"
+attack_symbol = "SOXL"
+vix_symbols = ["VIX", "^VIX", "VIXCLS"]
+credit_pairs = ["HYG:IEF", "LQD:IEF"]
+financial_symbols = ["XLF", "KRE"]
+rate_symbols = ["IEF", "TLT"]
+strategy_policy = "levered_growth_income_v1"
+realized_vol_threshold = 0.30
+realized_vol_requires_confirmation = true
+delever_risk_asset_scalar = 0.0
+taco_enabled = false
+crisis_enabled = true
+macro_enabled = true
+
+[strategy_plugins.outputs]
+output_dir = "data/output/soxl_soxx_trend_income/plugins/market_regime_control"
+
+# Deprecated compatibility mounts. They remain runnable for historical
+# backtests and downstream consumers that have not migrated to
+# market_regime_control yet. New strategy integrations should not read them
+# directly.
+
+[[strategy_plugins]]
+strategy = "tqqq_growth_income"
+plugin = "crisis_response_shadow"
+enabled = false
 
 [strategy_plugins.inputs]
 prices = "data/output/crisis_response_shadow/input/price_history.csv"
@@ -16,30 +77,14 @@ event_set = "full"
 financial_symbols = ["XLF", "KRE"]
 credit_pairs = ["HYG:IEF", "LQD:IEF"]
 rate_symbols = ["IEF", "TLT"]
-# Optional shadow-only AI audit. API keys are read from env vars, not TOML:
-# QSP_STRATEGY_PLUGIN_AI_AUDIT_API_KEY / QSP_STRATEGY_PLUGIN_AI_AUDIT_FALLBACK_API_KEY
-# Legacy QSP_CRISIS_AI_AUDIT_* names are still accepted.
-ai_audit_enabled = true
-ai_audit_codex_enabled = true
-ai_audit_model = "gpt-5.4-mini"
-# ai_audit_base_url = "https://api.openai.com/v1"
-# ai_audit_fallback_base_url = "https://fallback.example.com/v1"
-# ai_audit_fallback_model = "fallback-model"
-# Anthropic fallback follows the CryptoCodexAuditBridge provider-fallback style.
-# ai_audit_anthropic_model = "claude-sonnet-4-6"
-# ai_audit_anthropic_base_url = "https://api.anthropic.com/v1"
-# ai_audit_anthropic_version = "2023-06-01"
 
 [strategy_plugins.outputs]
 output_dir = "data/output/tqqq_growth_income/plugins/crisis_response_shadow"
 
 [[strategy_plugins]]
 strategy = "tqqq_growth_income"
 plugin = "macro_risk_governor"
-enabled = true
-# Deterministic macro de-leveraging governor. VIX/credit/price stress can emit
-# leverage_scalar and risk_asset_scalar for strategies that explicitly consume
-# mounted plugin metadata. OSINT fields remain watch-only evidence.
+enabled = false
 
 [strategy_plugins.inputs]
 prices = "data/output/macro_risk_governor/input/price_history.csv"
@@ -55,50 +100,12 @@ output_dir = "data/output/tqqq_growth_income/plugins/macro_risk_governor"
 [[strategy_plugins]]
 strategy = "tqqq_growth_income"
 plugin = "taco_rebound_shadow"
-enabled = true
-# Notification-only TACO context. The artifact may trigger manual-review alerts,
-# but it never recommends position size or mutates allocations.
-# Manual-review alerts require post-event price rebound confirmation by default.
+enabled = false
 
 [strategy_plugins.inputs]
 prices = "data/output/taco_rebound_shadow/input/price_history.csv"
 event_set = "geopolitical-deescalation"
 start_date = "2026-01-01"
-# Optional shadow-only AI audit for event/source quality. It cannot alter the
-# manual-review/watch-only route or generate allocation/order instructions.
-ai_audit_enabled = true
-ai_audit_codex_enabled = true
-ai_audit_model = "gpt-5.4-mini"
-# ai_audit_anthropic_model = "claude-sonnet-4-6"
 
 [strategy_plugins.outputs]
 output_dir = "data/output/tqqq_growth_income/plugins/taco_rebound_shadow"
-
-[[strategy_plugins]]
-strategy = "tqqq_growth_income"
-plugin = "market_regime_control"
-enabled = true
-# Unified facade over crisis_response_shadow, macro_risk_governor, and
-# taco_rebound_shadow. It emits one deterministic arbiter result with two
-# exits: notification and strategy-opt-in position_control. Broker writes and
-# live allocation mutation remain disabled in shadow mode.
-
-[strategy_plugins.inputs]
-prices = "data/output/market_regime_control/input/price_history.csv"
-external_context = "data/output/market_regime_control/input/external_context.csv"
-event_set = "geopolitical-deescalation"
-benchmark_symbol = "QQQ"
-attack_symbol = "TQQQ"
-vix_symbols = ["VIX", "^VIX", "VIXCLS"]
-credit_pairs = ["HYG:IEF", "LQD:IEF"]
-financial_symbols = ["XLF", "KRE"]
-rate_symbols = ["IEF", "TLT"]
-strategy_policy = "levered_growth_income_v1"
-taco_opportunity_size_scalar = 0.0
-# Component toggles support staged shadow rollout.
-crisis_enabled = true
-macro_enabled = true
-taco_enabled = true
-
-[strategy_plugins.outputs]
-output_dir = "data/output/tqqq_growth_income/plugins/market_regime_control"

src/quant_strategy_plugins/strategy_plugin_runner.py

@@ -40,10 +40,21 @@
 SUPPORTED_PLUGIN_MODES = (SHADOW_MODE,)
 PLUGIN_COMPATIBLE_STRATEGIES: dict[str, tuple[str, ...]] = {
     PLUGIN_CRISIS_RESPONSE_SHADOW: ("tqqq_growth_income", "soxl_soxx_trend_income"),
-    PLUGIN_MARKET_REGIME_CONTROL: ("tqqq_growth_income",),
+    PLUGIN_MARKET_REGIME_CONTROL: ("tqqq_growth_income", "soxl_soxx_trend_income"),
     PLUGIN_MACRO_RISK_GOVERNOR: ("tqqq_growth_income",),
     PLUGIN_TACO_REBOUND_SHADOW: ("tqqq_growth_income",),
 }
+PLUGIN_SCHEMA_VERSIONS: dict[str, tuple[str, ...]] = {
+    PLUGIN_CRISIS_RESPONSE_SHADOW: ("crisis_response_shadow.v1",),
+    PLUGIN_MARKET_REGIME_CONTROL: ("market_regime_control.v1",),
+    PLUGIN_MACRO_RISK_GOVERNOR: ("macro_risk_governor.v1",),
+    PLUGIN_TACO_REBOUND_SHADOW: ("taco_rebound_shadow.v2",),
+}
+PLUGIN_DEPRECATED_SUCCESSORS: dict[str, str] = {
+    PLUGIN_CRISIS_RESPONSE_SHADOW: PLUGIN_MARKET_REGIME_CONTROL,
+    PLUGIN_MACRO_RISK_GOVERNOR: PLUGIN_MARKET_REGIME_CONTROL,
+    PLUGIN_TACO_REBOUND_SHADOW: PLUGIN_MARKET_REGIME_CONTROL,
+}
 PLUGIN_RESEARCH_ONLY_REASONS: dict[str, str] = {}
 
 
@@ -615,7 +626,9 @@ def main(argv: list[str] | None = None) -> int:
     "PLUGIN_MACRO_RISK_GOVERNOR",
     "PLUGIN_TACO_REBOUND_SHADOW",
     "PLUGIN_COMPATIBLE_STRATEGIES",
+    "PLUGIN_DEPRECATED_SUCCESSORS",
     "PLUGIN_RESEARCH_ONLY_REASONS",
+    "PLUGIN_SCHEMA_VERSIONS",
     "PluginRunResult",
     "load_plugin_config",
     "main",

tests/test_strategy_plugin_runner.py

@@ -8,9 +8,12 @@
 
 from quant_strategy_plugins.crisis_response_research import ROUTE_TRUE_CRISIS
 from quant_strategy_plugins.strategy_plugin_runner import (
+    PLUGIN_COMPATIBLE_STRATEGIES,
     PLUGIN_CRISIS_RESPONSE_SHADOW,
+    PLUGIN_DEPRECATED_SUCCESSORS,
     PLUGIN_MARKET_REGIME_CONTROL,
     PLUGIN_MACRO_RISK_GOVERNOR,
+    PLUGIN_SCHEMA_VERSIONS,
     PLUGIN_TACO_REBOUND_SHADOW,
     load_plugin_config,
     main,
@@ -263,6 +266,53 @@ def test_strategy_plugin_runner_runs_unified_market_regime_control_for_tqqq(tmp_
     assert payload["execution_controls"]["live_allocation_mutation_allowed"] is False
 
 
+def test_strategy_plugin_runner_runs_unified_market_regime_control_for_soxl(tmp_path) -> None:
+    prices_path = tmp_path / "market_regime_prices.csv"
+    output_dir = tmp_path / SOXL_STRATEGY_NAME / "plugins" / PLUGIN_MARKET_REGIME_CONTROL
+    _soxl_quiet_prices().to_csv(prices_path, index=False)
+    config = {
+        "output_dir": str(tmp_path / "runner"),
+        "default_mode": "shadow",
+        "strategy_plugins": [
+            {
+                "strategy": SOXL_STRATEGY_NAME,
+                "plugin": PLUGIN_MARKET_REGIME_CONTROL,
+                "enabled": True,
+                "inputs": {
+                    "prices": str(prices_path),
+                    "as_of": "2025-11-19",
+                    "benchmark_symbol": "SOXX",
+                    "attack_symbol": "SOXL",
+                    "crisis_enabled": False,
+                    "macro_enabled": False,
+                    "taco_enabled": False,
+                },
+                "outputs": {"output_dir": str(output_dir)},
+            }
+        ],
+    }
+
+    summary = run_configured_plugins(config)
+
+    result = summary["strategy_plugins"][0]
+    assert result["strategy"] == SOXL_STRATEGY_NAME
+    assert result["plugin"] == PLUGIN_MARKET_REGIME_CONTROL
+    assert result["status"] == "ok"
+    payload = json.loads((output_dir / "latest_signal.json").read_text(encoding="utf-8"))
+    assert payload["strategy"] == SOXL_STRATEGY_NAME
+    assert payload["plugin"] == PLUGIN_MARKET_REGIME_CONTROL
+    assert payload["schema_version"] in PLUGIN_SCHEMA_VERSIONS[PLUGIN_MARKET_REGIME_CONTROL]
+    assert payload["canonical_route"] == "no_action"
+
+
+def test_strategy_plugin_runner_contract_registry_prefers_unified_plugin() -> None:
+    assert SOXL_STRATEGY_NAME in PLUGIN_COMPATIBLE_STRATEGIES[PLUGIN_MARKET_REGIME_CONTROL]
+    assert PLUGIN_SCHEMA_VERSIONS[PLUGIN_MARKET_REGIME_CONTROL] == ("market_regime_control.v1",)
+    assert PLUGIN_DEPRECATED_SUCCESSORS[PLUGIN_CRISIS_RESPONSE_SHADOW] == PLUGIN_MARKET_REGIME_CONTROL
+    assert PLUGIN_DEPRECATED_SUCCESSORS[PLUGIN_MACRO_RISK_GOVERNOR] == PLUGIN_MARKET_REGIME_CONTROL
+    assert PLUGIN_DEPRECATED_SUCCESSORS[PLUGIN_TACO_REBOUND_SHADOW] == PLUGIN_MARKET_REGIME_CONTROL
+
+
 def test_strategy_plugin_runner_rehearses_triggered_shadow_artifact_without_execution_permissions(tmp_path) -> None:
     prices = _financial_crisis_prices()
     prices_path = tmp_path / "crisis_prices.csv"
@@ -642,6 +692,7 @@ def test_strategy_plugin_runner_example_config_uses_default_mode_without_duplica
 
     assert config["default_mode"] == "shadow"
     assert "mode" not in config["strategy_plugins"][0]
+    assert config["strategy_plugins"][0]["plugin"] == PLUGIN_MARKET_REGIME_CONTROL
     assert config["strategy_plugins"][0]["outputs"]["output_dir"].endswith(
-        "tqqq_growth_income/plugins/crisis_response_shadow"
+        "tqqq_growth_income/plugins/market_regime_control"
     )