Merge remote-tracking branch 'origin/main' into chore/require-runtime-target-json

Author: Pigbibi

docs/platform_runtime_inventory.md

@@ -80,7 +80,7 @@ For the platform / strategy-domain / configurable-profile matrix, see [`platform
   - runtime Telegram token secret
 - **Runtime notes**
   - Runtime-sensitive envs should use Secret Manager refs, not plain Cloud Run env values.
-  - Strategy plugins are sidecars: `shadow` logs and notifies only; `paper`, `advisory`, and `live` semantics are governed by the plugin execution mode contract.
+  - Strategy plugins are sidecars: only `shadow` notification mode is supported; plugin-driven paper, advisory, and live execution modes are not part of the shared contract.
   - The token refresher lives outside this repo:
     - `QuantStrategyLab/SchwabTokenAutoRefresher`
 

docs/platform_runtime_inventory.zh-CN.md

@@ -79,7 +79,7 @@ _校验快照日期：2026-04-18_
   - runtime Telegram token secret
 - **运行说明**
   - 运行时敏感配置应使用 Secret Manager 引用，不应放在 Cloud Run 明文 env。
-  - 策略插件是 sidecar：`shadow` 只写日志和通知；`paper`、`advisory`、`live` 的语义由插件执行模式契约统一约束。
+  - 策略插件是 sidecar：只支持 `shadow` 通知模式；插件驱动的 `paper`、`advisory`、`live` 执行模式不属于共享契约。
   - token refresher 不在这个仓库里，而是在：
     - `QuantStrategyLab/SchwabTokenAutoRefresher`
 

docs/strategy_plugin_runtime_contract.md

@@ -17,7 +17,7 @@ artifacts, such as the Crisis Response plugin produced by
 
 Platform config should only decide which plugin artifacts are mounted for a
 strategy. It must not select the plugin mode. The mode lives inside the plugin
-artifact and is the single behavior contract.
+artifact and is fixed to notification-only `shadow`.
 
 Suggested environment variable name: `STRATEGY_PLUGIN_MOUNTS_JSON`.
 
@@ -53,9 +53,9 @@ or reinterpret the mode:
 }
 ```
 
-Do not put `mode` in the platform mount config. If the artifact says `paper`,
-the platform implements `paper`; if it says `live`, the platform implements
-`live` subject to risk checks and kill switches.
+Do not put `mode` in the platform mount config. `expected_mode` may be used only
+as a fail-closed guard and should be `shadow` when present. Artifacts declaring
+`paper`, `advisory`, or `live` are rejected.
 
 ## Runtime Loader
 
@@ -80,8 +80,7 @@ The loader validates:
 
 - the artifact is a JSON object
 - `strategy` and `plugin` match the configured mount
-- `mode`, `configured_mode`, and `effective_mode` are one of `shadow`, `paper`,
-  `advisory`, or `live`
+- `mode`, `configured_mode`, and `effective_mode` are `shadow`
 - optional `expected_mode` matches `effective_mode`
 - duplicate platform mounts are rejected
 - platform mount config does not set `mode`
@@ -91,11 +90,6 @@ The loader validates:
 For `shadow`, platform runtimes should only add logs, runtime report fields, and
 notification context.
 
-For `paper`, platform runtimes may maintain a simulated plugin ledger, but must
-not mutate real allocations.
-
-For `advisory`, platform runtimes may surface a recommendation that requires
-human confirmation.
-
-For `live`, platform runtimes may allow execution only through explicit platform
-risk budgets, kill switches, and data-freshness checks.
+`paper`, `advisory`, and `live` plugin modes are not supported by the shared
+contract. Platforms should not maintain plugin ledgers or execute plugin-driven
+allocation changes from this sidecar path.

src/quant_platform_kit/common/strategy_plugins.py

@@ -11,12 +11,7 @@
 from typing import Any
 
 PLUGIN_MODE_SHADOW = "shadow"
-PLUGIN_MODE_PAPER = "paper"
-PLUGIN_MODE_ADVISORY = "advisory"
-PLUGIN_MODE_LIVE = "live"
-SUPPORTED_STRATEGY_PLUGIN_MODES = frozenset(
-    {PLUGIN_MODE_SHADOW, PLUGIN_MODE_PAPER, PLUGIN_MODE_ADVISORY, PLUGIN_MODE_LIVE}
-)
+SUPPORTED_STRATEGY_PLUGIN_MODES = frozenset({PLUGIN_MODE_SHADOW})
 DEFAULT_PLUGIN_ARTIFACT_CACHE_DIR = Path(tempfile.gettempdir()) / "quant_strategy_plugin_artifacts"
 
 

tests/test_strategy_plugins.py

@@ -4,7 +4,6 @@
 from pathlib import Path
 
 from quant_platform_kit.common.strategy_plugins import (
-    PLUGIN_MODE_PAPER,
     PLUGIN_MODE_SHADOW,
     build_strategy_plugin_report_payload,
     load_configured_strategy_plugin_signals,
@@ -27,8 +26,8 @@ def _signal_payload(*, strategy="tqqq_growth_income", plugin="crisis_response_sh
         "suggested_action": "watch_only",
         "would_trade_if_enabled": False,
         "execution_controls": {
-            "broker_order_allowed": mode == "live",
-            "live_allocation_mutation_allowed": mode == "live",
+            "broker_order_allowed": False,
+            "live_allocation_mutation_allowed": False,
             "repository_broker_write_allowed": False,
             "repository_allocation_mutation_allowed": False,
         },
@@ -79,18 +78,18 @@ def test_parse_strategy_plugin_mounts_rejects_platform_mode_selection(self):
     def test_load_strategy_plugin_signal_validates_identity_and_mode(self):
         with tempfile.TemporaryDirectory() as tmp_dir:
             signal_path = Path(tmp_dir) / "latest_signal.json"
-            signal_path.write_text(json.dumps(_signal_payload(mode=PLUGIN_MODE_PAPER)), encoding="utf-8")
+            signal_path.write_text(json.dumps(_signal_payload(mode=PLUGIN_MODE_SHADOW)), encoding="utf-8")
 
             signal = load_strategy_plugin_signal(
                 str(signal_path),
                 expected_strategy="tqqq_growth_income",
                 expected_plugin="crisis_response_shadow",
-                expected_mode=PLUGIN_MODE_PAPER,
+                expected_mode=PLUGIN_MODE_SHADOW,
             )
 
         self.assertEqual(signal.strategy, "tqqq_growth_income")
         self.assertEqual(signal.plugin, "crisis_response_shadow")
-        self.assertEqual(signal.effective_mode, PLUGIN_MODE_PAPER)
+        self.assertEqual(signal.effective_mode, PLUGIN_MODE_SHADOW)
         self.assertFalse(signal.execution_controls["repository_broker_write_allowed"])
         self.assertEqual(signal.local_path, str(signal_path))
 
@@ -139,11 +138,18 @@ def test_load_configured_strategy_plugin_signals_filters_strategy_and_disabled_m
 
         self.assertEqual([signal.plugin for signal in signals], ["crisis_response_shadow"])
 
-    def test_validate_strategy_plugin_signal_payload_rejects_expected_mode_mismatch(self):
-        with self.assertRaisesRegex(ValueError, "mode mismatch"):
+    def test_validate_strategy_plugin_signal_payload_rejects_non_shadow_artifact_mode(self):
+        with self.assertRaisesRegex(ValueError, "mode must be one of shadow"):
+            validate_strategy_plugin_signal_payload(
+                _signal_payload(mode="paper"),
+                expected_mode=PLUGIN_MODE_SHADOW,
+            )
+
+    def test_validate_strategy_plugin_signal_payload_rejects_non_shadow_expected_mode(self):
+        with self.assertRaisesRegex(ValueError, "expected_mode must be one of shadow"):
             validate_strategy_plugin_signal_payload(
                 _signal_payload(mode=PLUGIN_MODE_SHADOW),
-                expected_mode=PLUGIN_MODE_PAPER,
+                expected_mode="live",
             )
 
     def test_build_strategy_plugin_report_payload_uses_compact_summary(self):