Version strategy plugin contracts

Author: Pigbibi

docs/strategy_plugin_runtime_contract.md

@@ -64,17 +64,21 @@ The shared kit owns plugin compatibility through a registry-style
 a plugin supports; they should call the shared parser/loader and let it reject
 unsupported mounts or artifacts.
 
-The default registry currently defines:
-
-| Plugin | Supported strategies | Supported mode | Escalated alert channel |
-| --- | --- | --- | --- |
-| `crisis_response_shadow` | `tqqq_growth_income`, `soxl_soxx_trend_income` | `shadow` | `email`, `sms`, `push`, `telegram` |
-| `taco_rebound_shadow` | `tqqq_growth_income` | `shadow` | `email`, `sms`, `push`, `telegram` |
-
-`taco_rebound_shadow` is notification-only. Its artifact may escalate a
-manual-review alert when a TACO-style rebound context is active, but it must not
-recommend position size, mutate live allocation, or imply broker order
-permission.
+The default registry currently defines versioned plugin contracts:
+
+| Plugin | Schema versions | Supported strategies | Status | Supported mode | Escalated alert channel |
+| --- | --- | --- | --- | --- | --- |
+| `market_regime_control` | `market_regime_control.v1` | `tqqq_growth_income`, `soxl_soxx_trend_income` | default | `shadow` | `email`, `sms`, `push`, `telegram` |
+| `crisis_response_shadow` | `crisis_response_shadow.v1` | `tqqq_growth_income`, `soxl_soxx_trend_income` | deprecated; successor `market_regime_control` | `shadow` | `email`, `sms`, `push`, `telegram` |
+| `macro_risk_governor` | `macro_risk_governor.v1` | `tqqq_growth_income` | deprecated; successor `market_regime_control` | `shadow` | `email`, `sms`, `push`, `telegram` |
+| `taco_rebound_shadow` | `taco_rebound_shadow.v2` | `tqqq_growth_income` | deprecated; successor `market_regime_control` | `shadow` | `email`, `sms`, `push`, `telegram` |
+
+Deprecated plugins remain loadable for historical backtests and staged rollout.
+New strategy integrations should mount `market_regime_control` and read the
+artifact's `notification` and `position_control` sections. The old TACO artifact
+is notification-only. It may escalate a manual-review alert when a TACO-style
+rebound context is active, but it must not recommend position size, mutate live
+allocation, or imply broker order permission.
 
 To expand a plugin later, update the shared definition or pass an explicit
 definition registry into the parser/loader. This keeps future plugin eligibility

src/quant_platform_kit/common/__init__.py

@@ -52,6 +52,7 @@
     STRATEGY_PLUGIN_ALERT_CHANNEL_TELEGRAM,
     STRATEGY_PLUGIN_ALERT_ACTIONS,
     STRATEGY_PLUGIN_NON_ALERT_ROUTES,
+    STRATEGY_PLUGIN_SCHEMA_VERSIONS,
     SUPPORTED_STRATEGY_PLUGIN_MODES,
     MACRO_RISK_GOVERNOR_SUPPORTED_STRATEGIES,
     MARKET_REGIME_CONTROL_SUPPORTED_STRATEGIES,
@@ -74,6 +75,7 @@
     should_alert_strategy_plugin_signal,
     translate_strategy_plugin_value,
     validate_strategy_plugin_compatibility,
+    validate_strategy_plugin_schema_version,
     validate_strategy_plugin_signal_payload,
 )
 
@@ -104,6 +106,7 @@
     "STRATEGY_PLUGIN_ALERT_CHANNEL_TELEGRAM",
     "STRATEGY_PLUGIN_ALERT_ACTIONS",
     "STRATEGY_PLUGIN_NON_ALERT_ROUTES",
+    "STRATEGY_PLUGIN_SCHEMA_VERSIONS",
     "SUPPORTED_STRATEGY_PLUGIN_MODES",
     "MACRO_RISK_GOVERNOR_SUPPORTED_STRATEGIES",
     "MARKET_REGIME_CONTROL_SUPPORTED_STRATEGIES",
@@ -144,5 +147,6 @@
     "translate_strategy_plugin_value",
     "translator_uses_zh",
     "validate_strategy_plugin_compatibility",
+    "validate_strategy_plugin_schema_version",
     "validate_strategy_plugin_signal_payload",
 ]

src/quant_platform_kit/common/strategy_plugins.py

@@ -32,7 +32,13 @@
 )
 TACO_REBOUND_SHADOW_SUPPORTED_STRATEGIES = frozenset({"tqqq_growth_income"})
 MACRO_RISK_GOVERNOR_SUPPORTED_STRATEGIES = frozenset({"tqqq_growth_income"})
-MARKET_REGIME_CONTROL_SUPPORTED_STRATEGIES = frozenset({"tqqq_growth_income"})
+MARKET_REGIME_CONTROL_SUPPORTED_STRATEGIES = frozenset({"tqqq_growth_income", "soxl_soxx_trend_income"})
+STRATEGY_PLUGIN_SCHEMA_VERSIONS: Mapping[str, frozenset[str]] = {
+    PLUGIN_CRISIS_RESPONSE_SHADOW: frozenset({"crisis_response_shadow.v1"}),
+    PLUGIN_MARKET_REGIME_CONTROL: frozenset({"market_regime_control.v1"}),
+    PLUGIN_MACRO_RISK_GOVERNOR: frozenset({"macro_risk_governor.v1"}),
+    PLUGIN_TACO_REBOUND_SHADOW: frozenset({"taco_rebound_shadow.v2"}),
+}
 _DEFAULT_STRATEGY_PLUGIN_ALERT_GUIDANCE: Mapping[tuple[str, str, str], str] = {
     (
         PLUGIN_CRISIS_RESPONSE_SHADOW,
@@ -117,6 +123,10 @@ class StrategyPluginDefinition:
     plugin: str
     supported_strategies: frozenset[str] | None = None
     supported_modes: frozenset[str] = field(default_factory=lambda: SUPPORTED_STRATEGY_PLUGIN_MODES)
+    supported_schema_versions: frozenset[str] = field(default_factory=frozenset)
+    default_schema_version: str | None = None
+    deprecated: bool = False
+    successor_plugin: str | None = None
     alert_channels: tuple[str, ...] = ()
 
     def normalized(self) -> "StrategyPluginDefinition":
@@ -132,6 +142,16 @@ def normalized(self) -> "StrategyPluginDefinition":
         )
         if not supported_modes:
             raise ValueError(f"strategy plugin definition for {plugin} must include at least one supported mode")
+        supported_schema_versions = frozenset(
+            _required_string(version, field_name="supported_schema_version")
+            for version in self.supported_schema_versions
+        )
+        default_schema_version = _optional_string(self.default_schema_version)
+        if default_schema_version is not None and supported_schema_versions and default_schema_version not in supported_schema_versions:
+            raise ValueError(
+                f"strategy plugin definition for {plugin} default_schema_version must be listed in supported_schema_versions"
+            )
+        successor_plugin = _optional_string(self.successor_plugin)
         alert_channels = tuple(
             _required_string(channel, field_name="alert_channel")
             for channel in self.alert_channels
@@ -140,6 +160,10 @@ def normalized(self) -> "StrategyPluginDefinition":
             plugin=plugin,
             supported_strategies=supported_strategies,
             supported_modes=supported_modes,
+            supported_schema_versions=supported_schema_versions,
+            default_schema_version=default_schema_version,
+            deprecated=bool(self.deprecated),
+            successor_plugin=successor_plugin,
             alert_channels=alert_channels,
         )
 
@@ -154,6 +178,10 @@ def supports_strategy(self, strategy: str) -> bool:
         plugin=PLUGIN_CRISIS_RESPONSE_SHADOW,
         supported_strategies=CRISIS_RESPONSE_SHADOW_SUPPORTED_STRATEGIES,
         supported_modes=SUPPORTED_STRATEGY_PLUGIN_MODES,
+        supported_schema_versions=STRATEGY_PLUGIN_SCHEMA_VERSIONS[PLUGIN_CRISIS_RESPONSE_SHADOW],
+        default_schema_version="crisis_response_shadow.v1",
+        deprecated=True,
+        successor_plugin=PLUGIN_MARKET_REGIME_CONTROL,
         alert_channels=(
             STRATEGY_PLUGIN_ALERT_CHANNEL_EMAIL,
             STRATEGY_PLUGIN_ALERT_CHANNEL_SMS,
@@ -165,6 +193,10 @@ def supports_strategy(self, strategy: str) -> bool:
         plugin=PLUGIN_TACO_REBOUND_SHADOW,
         supported_strategies=TACO_REBOUND_SHADOW_SUPPORTED_STRATEGIES,
         supported_modes=SUPPORTED_STRATEGY_PLUGIN_MODES,
+        supported_schema_versions=STRATEGY_PLUGIN_SCHEMA_VERSIONS[PLUGIN_TACO_REBOUND_SHADOW],
+        default_schema_version="taco_rebound_shadow.v2",
+        deprecated=True,
+        successor_plugin=PLUGIN_MARKET_REGIME_CONTROL,
         alert_channels=(
             STRATEGY_PLUGIN_ALERT_CHANNEL_EMAIL,
             STRATEGY_PLUGIN_ALERT_CHANNEL_SMS,
@@ -176,6 +208,8 @@ def supports_strategy(self, strategy: str) -> bool:
         plugin=PLUGIN_MARKET_REGIME_CONTROL,
         supported_strategies=MARKET_REGIME_CONTROL_SUPPORTED_STRATEGIES,
         supported_modes=SUPPORTED_STRATEGY_PLUGIN_MODES,
+        supported_schema_versions=STRATEGY_PLUGIN_SCHEMA_VERSIONS[PLUGIN_MARKET_REGIME_CONTROL],
+        default_schema_version="market_regime_control.v1",
         alert_channels=(
             STRATEGY_PLUGIN_ALERT_CHANNEL_EMAIL,
             STRATEGY_PLUGIN_ALERT_CHANNEL_SMS,
@@ -187,6 +221,10 @@ def supports_strategy(self, strategy: str) -> bool:
         plugin=PLUGIN_MACRO_RISK_GOVERNOR,
         supported_strategies=MACRO_RISK_GOVERNOR_SUPPORTED_STRATEGIES,
         supported_modes=SUPPORTED_STRATEGY_PLUGIN_MODES,
+        supported_schema_versions=STRATEGY_PLUGIN_SCHEMA_VERSIONS[PLUGIN_MACRO_RISK_GOVERNOR],
+        default_schema_version="macro_risk_governor.v1",
+        deprecated=True,
+        successor_plugin=PLUGIN_MARKET_REGIME_CONTROL,
         alert_channels=(
             STRATEGY_PLUGIN_ALERT_CHANNEL_EMAIL,
             STRATEGY_PLUGIN_ALERT_CHANNEL_SMS,
@@ -204,6 +242,7 @@ class StrategyPluginMountConfig:
     signal_path: str
     enabled: bool = True
     expected_mode: str | None = None
+    expected_schema_version: str | None = None
 
 
 @dataclass(frozen=True)
@@ -222,6 +261,9 @@ class StrategyPluginSignal:
     payload: Mapping[str, Any]
     source_uri: str | None = None
     local_path: str | None = None
+    deprecated_plugin: bool = False
+    successor_plugin: str | None = None
+    supported_schema_versions: tuple[str, ...] = ()
 
     def report_summary(self) -> dict[str, Any]:
         return {
@@ -231,6 +273,9 @@ def report_summary(self) -> dict[str, Any]:
             "configured_mode": self.configured_mode,
             "effective_mode": self.effective_mode,
             "schema_version": self.schema_version,
+            "deprecated_plugin": self.deprecated_plugin,
+            "successor_plugin": self.successor_plugin,
+            "supported_schema_versions": self.supported_schema_versions,
             "as_of": self.as_of,
             "canonical_route": self.canonical_route,
             "suggested_action": self.suggested_action,
@@ -309,6 +354,34 @@ def validate_strategy_plugin_compatibility(
         )
 
 
+def validate_strategy_plugin_schema_version(
+    *,
+    plugin: str,
+    schema_version: str | None,
+    expected_schema_version: str | None = None,
+    plugin_definitions: Mapping[str, StrategyPluginDefinition] | Sequence[StrategyPluginDefinition] | None = None,
+    source: str = "artifact",
+) -> None:
+    plugin_name = _required_string(plugin, field_name="plugin")
+    normalized_schema_version = _optional_string(schema_version)
+    normalized_expected_schema_version = _optional_string(expected_schema_version)
+    if normalized_expected_schema_version is not None and normalized_schema_version != normalized_expected_schema_version:
+        raise ValueError(
+            "strategy plugin artifact schema_version mismatch: "
+            f"expected {normalized_expected_schema_version}, got {normalized_schema_version or '<missing>'}"
+        )
+    definitions = normalize_strategy_plugin_definitions(plugin_definitions)
+    definition = definitions.get(plugin_name)
+    if definition is None or not definition.supported_schema_versions or normalized_schema_version is None:
+        return
+    if normalized_schema_version not in definition.supported_schema_versions:
+        allowed = ", ".join(sorted(definition.supported_schema_versions))
+        raise ValueError(
+            f"strategy plugin {plugin_name} does not support schema_version {normalized_schema_version} "
+            f"in {source}; supported schema versions: {allowed}"
+        )
+
+
 def parse_strategy_plugin_mounts(
     raw_config: str | Sequence[Mapping[str, Any]] | Mapping[str, Any] | None,
     *,
@@ -351,6 +424,14 @@ def parse_strategy_plugin_mounts(
             if expected_mode is not None
             else None
         )
+        expected_schema_version = _optional_string(item.get("expected_schema_version"))
+        validate_strategy_plugin_schema_version(
+            plugin=plugin,
+            schema_version=expected_schema_version,
+            expected_schema_version=expected_schema_version,
+            plugin_definitions=definitions,
+            source="mount",
+        )
         validate_strategy_plugin_compatibility(
             strategy=strategy,
             plugin=plugin,
@@ -365,6 +446,7 @@ def parse_strategy_plugin_mounts(
                 signal_path=signal_path,
                 enabled=_as_bool(item.get("enabled"), default=True),
                 expected_mode=normalized_expected_mode,
+                expected_schema_version=expected_schema_version,
             )
         )
     return tuple(mounts)
@@ -398,6 +480,7 @@ def load_configured_strategy_plugin_signals(
                 expected_strategy=mount.strategy,
                 expected_plugin=mount.plugin,
                 expected_mode=mount.expected_mode,
+                expected_schema_version=mount.expected_schema_version,
                 client_factory=client_factory,
                 plugin_definitions=definitions,
             )
@@ -411,6 +494,7 @@ def load_strategy_plugin_signal(
     expected_strategy: str | None = None,
     expected_plugin: str | None = None,
     expected_mode: str | None = None,
+    expected_schema_version: str | None = None,
     client_factory: Any = None,
     plugin_definitions: Mapping[str, StrategyPluginDefinition] | Sequence[StrategyPluginDefinition] | None = None,
 ) -> StrategyPluginSignal:
@@ -425,6 +509,7 @@ def load_strategy_plugin_signal(
         expected_strategy=expected_strategy,
         expected_plugin=expected_plugin,
         expected_mode=expected_mode,
+        expected_schema_version=expected_schema_version,
         source_uri=metadata.get("source_uri"),
         local_path=str(local_path),
         plugin_definitions=plugin_definitions,
@@ -437,6 +522,7 @@ def validate_strategy_plugin_signal_payload(
     expected_strategy: str | None = None,
     expected_plugin: str | None = None,
     expected_mode: str | None = None,
+    expected_schema_version: str | None = None,
     source_uri: str | None = None,
     local_path: str | None = None,
     plugin_definitions: Mapping[str, StrategyPluginDefinition] | Sequence[StrategyPluginDefinition] | None = None,
@@ -473,6 +559,16 @@ def validate_strategy_plugin_signal_payload(
         plugin_definitions=plugin_definitions,
         source="artifact",
     )
+    schema_version = _optional_string(payload.get("schema_version")) or ""
+    definitions = normalize_strategy_plugin_definitions(plugin_definitions)
+    definition = definitions.get(plugin)
+    validate_strategy_plugin_schema_version(
+        plugin=plugin,
+        schema_version=schema_version,
+        expected_schema_version=expected_schema_version,
+        plugin_definitions=definitions,
+        source="artifact",
+    )
 
     execution_controls = payload.get("execution_controls") or {}
     if not isinstance(execution_controls, Mapping):
@@ -484,7 +580,7 @@ def validate_strategy_plugin_signal_payload(
         mode=mode,
         configured_mode=configured_mode,
         effective_mode=effective_mode,
-        schema_version=_optional_string(payload.get("schema_version")) or "",
+        schema_version=schema_version,
         as_of=_optional_string(payload.get("as_of")) or "",
         canonical_route=_optional_string(payload.get("canonical_route")),
         suggested_action=_optional_string(payload.get("suggested_action")),
@@ -493,6 +589,9 @@ def validate_strategy_plugin_signal_payload(
         payload=dict(payload),
         source_uri=_optional_string(source_uri),
         local_path=_optional_string(local_path),
+        deprecated_plugin=bool(definition.deprecated) if definition is not None else False,
+        successor_plugin=definition.successor_plugin if definition is not None else None,
+        supported_schema_versions=tuple(sorted(definition.supported_schema_versions)) if definition is not None else (),
     )