Harden market regime plugin contract (#27)

Author: Pigbibi

docs/examples/strategy_plugins.example.toml

@@ -77,7 +77,9 @@ macro_enabled = true
 # Automation-approved deterministic SOXX price/volatility rebound context.
 # It only feeds volatility_delever_context retention profiles; TACO, panic
 # reversal, AI audit, OSINT, and localized copy remain manual-review/display
-# evidence and do not directly change SOXL allocation.
+# evidence and do not directly change SOXL allocation. The SOXL strategy default
+# consumes the aggressive soxl_step_rebound_0.25_0.50 profile; the plugin also
+# emits soxl_step_softzero_rebound_0.25_0.50 for conservative strategy configs.
 volatility_delever_price_rebound_enabled = true
 
 [strategy_plugins.outputs]

docs/market-regime-control-plan.md

@@ -114,13 +114,24 @@ Recommended policy:
   `position_control.volatility_delever_context` retention profiles when its
   local volatility gate triggers. TACO, panic reversal, AI audit, OSINT, and
   localized notification copy remain manual-review context only.
+  The live default remains the aggressive
+  `soxl_step_rebound_0.25_0.50` profile: retain 50% on constructive confirmed
+  price rebound, retain 25% on a soft-risk price-rebound candidate, and retain
+  0% under hard risk or without deterministic price rebound. The plugin also
+  emits `soxl_step_softzero_rebound_0.25_0.50` as a conservative switch that
+  clears retention under soft risk.
 - Global ETF, Russell 1000, and Mega Cap rotation
   strategies
-  Support the unified plugin by default. `risk_reduced` should apply a 50% risk
-  budget scale; `risk_off` should zero the risk-asset budget.
+  May generate the unified plugin artifact for notification and evidence
+  archiving, but their strategy-level `position_control_allowed` flag stays
+  false until a dedicated 25-30 year validation package is archived. The
+  candidate rule for that later promotion remains: `risk_reduced` applies a 50%
+  risk-budget scale and `risk_off` zeros the risk-asset budget.
 - DCA or low-frequency income strategies
-  Default to notification-only and may allow explicit operator opt-in for
-  position impact.
+  Default to notification-only. They should not sell or de-risk existing
+  holdings from this plugin; any future automation should be a separate
+  cash-deployment control for new buys, such as pause, halve, or catch-up,
+  after its own validation.
 
 Legacy plugins remain available for historical backtests and compatibility
 outputs. New integrations should prefer `market_regime_control`.
@@ -145,6 +156,21 @@ the human notification body:
 - Automated position impact happens only when the strategy side explicitly
   consumes `position_control`, and only when `position_control_allowed = true`
   and `evidence_status = automation_approved`.
+- New or expanded automated position consumers should clear a 25-30 year
+  long-history validation gate before promotion. For TQQQ/SOXL-style products
+  without enough live ETF history, the long replay must explicitly use a
+  synthetic daily-reset 3x proxy built from the underlying QQQ/SOXX series and
+  archive synthetic and real-ETF evidence separately.
+- The current automation-approved strategy consumers are TQQQ growth/income
+  and SOXL/SOXX trend/income. Global ETF, Russell 1000, and Mega Cap rotation
+  remain notification/evidence artifacts for this plugin until their own
+  long-history promotion packages are archived. Their runner artifacts carry
+  `position_control_allowed = false`,
+  `strategy_runtime_metadata_allowed = false`, and
+  `capital_impact = notification_only`.
+- The same automation evidence can support aggressive and conservative
+  strategy-side consumption preferences. The plugin only emits deterministic
+  fields and evidence; the strategy config chooses which preference to apply.
 - `notification_only`, TACO, panic reversal, AI audit, and general notification
   targets are for manual review only.
 - Dedicated plugin-alert bots should publish only manual-review or
@@ -170,6 +196,11 @@ must avoid hard or soft stress. This context only feeds
 `position_control.volatility_delever_context.retention_profiles`; it does not
 change the `risk_off`, `risk_reduced`, or `watch` route.
 
+TACO and panic reversal may appear in
+`position_control.volatility_delever_context.rebound_sources` for display and
+manual-review context, but they do not raise automatic SOXL retention profiles.
+Automatic SOXL retention requires `price_rebound_context` hard-data evidence.
+
 ## Indicator Tiers
 
 Current indicator tiers:
@@ -305,8 +336,9 @@ Design implications:
   volatility-delever retention context, but does not apply `risk_reduced`
   position impact by default.
 - Rotation strategies:
-  enable 50% risk scaling for `risk_reduced` and zero risk-asset budget for
-  `risk_off`.
+  remain notification-only until their 25-30 year validation packages are
+  archived. The later promotion candidate is 50% risk scaling for
+  `risk_reduced` and zero risk-asset budget for `risk_off`.
 - TACO / panic reversal:
   notification-only by default; they can surface opportunity context only when
   no crisis or macro de-risking route is active. Panic reversal remains disabled

docs/market-regime-control-plan.zh-CN.md

@@ -73,10 +73,12 @@
 - SOXL/SOXX 趋势收益策略
   默认挂载统一插件。`risk_off` 可把风险暴露转向防守资产；`risk_reduced` 在策略默认配置中仍不产生仓位影响。SOXL 继续使用已复核的 SOXX 趋势和本地波动率降杠杆门，并可在本地波动率触发时消费确定性的
   `position_control.volatility_delever_context` retention profiles。SOXL 的自动 retention 只允许使用可回测的价格/波动反弹上下文：SOXX 趋势仍成立、短期均线斜率为正、实现波动达到本地降杠杆动态阈值、且 VIX/信用/金融压力未触发硬/软过滤。TACO、panic reversal、AI audit、OSINT 和本地化通知文案仍只作为人工复核上下文。
+  当前 live 默认保留偏进攻的 `soxl_step_rebound_0.25_0.50`：建设性确认反弹保留 50%，soft-risk 但有价格反弹候选时保留 25%，hard-risk 或没有确定性价格反弹时保留 0%。插件同时输出
+  `soxl_step_softzero_rebound_0.25_0.50` 作为保守开关，soft-risk 下直接清零。
 - Global ETF、Russell 1000、Mega Cap 类轮动策略
-  默认支持统一插件。`risk_reduced` 建议做 50% 风险预算缩放，`risk_off` 建议归零风险资产预算。
+  可以先生成统一插件 artifact，用于通知和证据归档；但策略级 `position_control_allowed` 在专门的 25-30 年长周期验证包归档前保持 false。后续若推广，候选规则仍是：`risk_reduced` 做 50% 风险预算缩放，`risk_off` 归零风险资产预算。
 - DCA 或收入型低频策略
-  默认 notification-only，允许用户显式开启仓位影响。
+  默认 notification-only。不应通过该插件卖出或降低已有持仓；未来如需自动化，只能单独设计新买入资金的 cash-deployment control（暂停、减半、补投），并通过独立验证。
 
 旧插件仍可运行历史回测和兼容输出，但新策略集成应优先挂载 `market_regime_control`。
 
@@ -92,6 +94,12 @@
 - 插件仓库只生成 artifact 和通知，不调用券商接口，也不直接改账户配置。
 - 自动仓位影响只发生在策略侧显式消费 `position_control` 时，并且必须同时满足
   `position_control_allowed = true` 和 `evidence_status = automation_approved`。
+- 新增或扩大自动仓位消费范围前，应先通过 25-30 年长周期验证。TQQQ/SOXL 这类实盘产品历史不足的策略，长周期验证必须明确使用
+  QQQ/SOXX 等底层资产合成的 3x 日重置代理，并把 synthetic 口径和真实 ETF 口径分开归档。
+- 当前已批准自动消费的策略级消费者只有 TQQQ 增长收益和 SOXL/SOXX 趋势收益。Global ETF、Russell 1000 和 Mega Cap 轮动在各自长周期推广包归档前，只保留通知和证据 artifact；runner artifact 会写入
+  `position_control_allowed = false`、`strategy_runtime_metadata_allowed = false`
+  和 `capital_impact = notification_only`。
+- 同一个自动化证据可以有偏进攻和偏保守两种策略侧消费偏好；插件只输出确定性字段和证据，具体选用哪个偏好由策略配置决定。
 - `notification_only`、TACO、panic reversal、AI audit 和通用通知只用于人工查看。
 - 专用插件告警 bot 只发布人工复核或 notification-only 插件信号。如果策略消费了已通过自动化证据批准的
   `defend` 或 `delever` 路线，并实际产生仓位影响，面向用户的通知应由该策略运行结果承载。
@@ -106,6 +114,8 @@ SOXL/SOXX 现在出现在 `market_regime_control` 的策略级消费 registry 
 - 已可执行打分：价格趋势、63/252 日回撤、实现波动、VIX 水平/尖峰、信用 ETF 相对压力。
 - 已可执行 retention 上下文：SOXL 本地波动降杠杆只消费 SOXX 价格趋势、均线斜率、动态实现波动阈值、VIX、HYG/IEF 和 XLF/SPY 这类可回测硬数据；该上下文只写入
   `volatility_delever_context.retention_profiles`，不改变 `risk_off` / `risk_reduced` / `watch` 路由。
+  TACO 和 panic reversal 可以出现在 `volatility_delever_context.rebound_sources` 里作为展示和人工复核上下文，但不会抬高 SOXL 自动 retention；自动 SOXL retention 必须来自
+  `price_rebound_context` 的硬数据证据。
 - 已接入 watch-only：HY OAS、金融压力指数、五角大楼比萨指数、Fear & Greed、put/call、safe-haven demand、VIX/VIX3M 期限结构、VVIX、SKEW、MOVE、IG OAS、资金压力利差、10Y-2Y/10Y-3M 曲线、DXY 21 日压力、50/200 日市场宽度、新高新低、涨跌线回撤、AAII bearish-bullish spread 和 NAAIM exposure。
 - 未进入自动仓位：所有 watch-only 指标。它们只用于通知、证据归档和后续历史回测。
 - 研究开关：`external_stress_actionable = true` 可让 HY OAS、HY OAS 63 日扩张和金融压力指数进入可执行分数；默认固定为 `false`。
@@ -170,6 +180,6 @@ TQQQ 2010-2026 真实产品窗口：
 
 - 杠杆策略：默认挂载统一插件，允许 `risk_off` 生效。
 - 高波动行业杠杆策略：SOXL 在 2026-06-16 retention replay 后默认挂载统一插件；默认策略配置允许 `risk_off` 和确定性波动率降杠杆 retention context，但不默认应用 `risk_reduced` 仓位影响。
-- 轮动策略：默认开启 50% risk scaling 和 `risk_off` 归零。
+- 轮动策略：在 25-30 年长周期验证包归档前保持 notification-only。后续推广候选规则是 `risk_reduced` 做 50% risk scaling，`risk_off` 归零风险资产预算。
 - TACO / panic reversal：默认通知-only；只有没有危机和宏观降风险时才允许提示机会。panic reversal 默认保持研究开关关闭，直到事件窗口和 no-regression 报告证明可提升权限。
 - AI audit：默认不参与交易权限，只能写审计结论和通知证据。

src/quant_strategy_plugins/market_regime_control_plugin.py

@@ -162,6 +162,21 @@ def _retention_profile(retention_ratio: float, *reason_codes: str) -> dict[str,
     }
 
 
+def _price_rebound_candidate(price_rebound_context: Mapping[str, Any] | None) -> bool:
+    if not isinstance(price_rebound_context, Mapping):
+        return False
+    return bool(
+        _as_bool(price_rebound_context.get("volatility_triggered"), default=False)
+        and _as_bool(price_rebound_context.get("trend_ok"), default=False)
+        and (
+            _as_bool(price_rebound_context.get("rebound_1d"), default=False)
+            or _as_bool(price_rebound_context.get("rebound_nd"), default=False)
+            or _as_bool(price_rebound_context.get("confirmed"), default=False)
+        )
+        and not _as_bool(price_rebound_context.get("hard_filter"), default=False)
+    )
+
+
 def _build_volatility_delever_context(
     *,
     final_route: str,
@@ -180,7 +195,11 @@ def _build_volatility_delever_context(
         isinstance(price_rebound_context, Mapping)
         and _as_bool(price_rebound_context.get("confirmed"), default=False)
         and not hard_risk
-        and not soft_risk
+        and not blocked
+    )
+    price_rebound_candidate = bool(
+        _price_rebound_candidate(price_rebound_context)
+        and not hard_risk
         and not blocked
     )
     opportunity_rebound_confirm = bool(taco_active or panic_reversal_active)
@@ -197,23 +216,28 @@ def _build_volatility_delever_context(
         tqqq_softzero_025 = _retention_profile(0.0, "hard_risk")
         tqqq_softzero_035 = _retention_profile(0.0, "hard_risk")
         soxl_rebound = _retention_profile(0.0, "hard_risk")
+        soxl_softzero_rebound = _retention_profile(0.0, "hard_risk")
     elif soft_risk:
         tqqq_softzero_025 = _retention_profile(0.0, "soft_risk")
         tqqq_softzero_035 = _retention_profile(0.0, "soft_risk")
-        soxl_rebound = _retention_profile(0.0, "soft_risk")
-    elif rebound_confirm:
-        if opportunity_rebound_confirm:
-            tqqq_softzero_025 = _retention_profile(0.50, "constructive", "rebound_confirm")
-            tqqq_softzero_035 = _retention_profile(0.50, "constructive", "rebound_confirm")
-            soxl_rebound = _retention_profile(0.50 if constructive else 0.25, "constructive", "rebound_confirm")
-        else:
-            tqqq_softzero_025 = _retention_profile(0.25, "non_soft_risk")
-            tqqq_softzero_035 = _retention_profile(0.35, "non_soft_risk")
-            soxl_rebound = _retention_profile(0.50, "constructive", "price_rebound_confirm")
+        soxl_rebound = (
+            _retention_profile(0.25, "price_rebound_candidate", "soft_risk")
+            if price_rebound_candidate
+            else _retention_profile(0.0, "soft_risk")
+        )
+        soxl_softzero_rebound = _retention_profile(0.0, "soft_risk")
     else:
         tqqq_softzero_025 = _retention_profile(0.25, "non_soft_risk")
         tqqq_softzero_035 = _retention_profile(0.35, "non_soft_risk")
-        soxl_rebound = _retention_profile(0.0, "rebound_not_confirmed")
+        if price_rebound_confirm:
+            soxl_rebound = _retention_profile(0.50, "constructive", "price_rebound_confirm")
+            soxl_softzero_rebound = _retention_profile(0.50, "constructive", "price_rebound_confirm")
+        elif price_rebound_candidate:
+            soxl_rebound = _retention_profile(0.25, "price_rebound_candidate")
+            soxl_softzero_rebound = _retention_profile(0.25, "price_rebound_candidate")
+        else:
+            soxl_rebound = _retention_profile(0.0, "rebound_not_confirmed")
+            soxl_softzero_rebound = _retention_profile(0.0, "rebound_not_confirmed")
     context = {
         "schema_version": "volatility_delever_context.v1",
         "source": "deterministic_market_regime_components",
@@ -222,13 +246,15 @@ def _build_volatility_delever_context(
         "soft_risk": soft_risk,
         "constructive": constructive,
         "rebound_confirm": rebound_confirm,
+        "price_rebound_candidate": price_rebound_candidate,
         "rebound_sources": tuple(rebound_sources),
         "macro_watch": bool(macro_watch),
         "reason_codes": tuple(dict.fromkeys(reason_codes)),
         "retention_profiles": {
             "tqqq_step_softzero_0.25_0.50": tqqq_softzero_025,
             "tqqq_step_softzero_0.35_0.50": tqqq_softzero_035,
             "soxl_step_rebound_0.25_0.50": soxl_rebound,
+            "soxl_step_softzero_rebound_0.25_0.50": soxl_softzero_rebound,
         },
     }
     if isinstance(price_rebound_context, Mapping) and price_rebound_context:

src/quant_strategy_plugins/strategy_plugin_runner.py

@@ -121,28 +121,28 @@ class PluginNotificationTargetPolicy:
         plugin=PLUGIN_MARKET_REGIME_CONTROL,
         strategy="global_etf_rotation",
         notification_allowed=True,
-        position_control_allowed=True,
-        evidence_status=EVIDENCE_AUTOMATION_APPROVED,
+        position_control_allowed=False,
+        evidence_status=EVIDENCE_NOTIFICATION_ONLY,
         since_version="strategy_plugins.v1",
-        description="Local risk-scaling consumer for broad ETF rotation.",
+        description="Pending 25-30 year market-regime-control validation for broad ETF rotation.",
     ),
     PluginConsumptionPolicy(
         plugin=PLUGIN_MARKET_REGIME_CONTROL,
         strategy="russell_1000_multi_factor_defensive",
         notification_allowed=True,
-        position_control_allowed=True,
-        evidence_status=EVIDENCE_AUTOMATION_APPROVED,
+        position_control_allowed=False,
+        evidence_status=EVIDENCE_NOTIFICATION_ONLY,
         since_version="strategy_plugins.v1",
-        description="Local risk-scaling consumer for the Russell 1000 defensive sleeve.",
+        description="Pending 25-30 year market-regime-control validation for the Russell 1000 defensive sleeve.",
     ),
     PluginConsumptionPolicy(
         plugin=PLUGIN_MARKET_REGIME_CONTROL,
         strategy="mega_cap_leader_rotation_top50_balanced",
         notification_allowed=True,
-        position_control_allowed=True,
-        evidence_status=EVIDENCE_AUTOMATION_APPROVED,
+        position_control_allowed=False,
+        evidence_status=EVIDENCE_NOTIFICATION_ONLY,
         since_version="strategy_plugins.v1",
-        description="Local risk-scaling consumer for the mega-cap leader rotation profile.",
+        description="Pending 25-30 year market-regime-control validation for the mega-cap leader rotation profile.",
     ),
     PluginConsumptionPolicy(
         plugin=PLUGIN_MARKET_REGIME_CONTROL,
@@ -1504,6 +1504,14 @@ def _apply_plugin_contract(
         execution_controls["notification_allowed"] = bool(consumption_policy.notification_allowed)
         execution_controls["position_control_allowed"] = bool(consumption_policy.position_control_allowed)
         execution_controls["consumption_evidence_status"] = consumption_policy.evidence_status
+        if consumption_policy.position_control_allowed:
+            execution_controls["capital_impact"] = "strategy_opt_in"
+            execution_controls["strategy_runtime_metadata_allowed"] = True
+            execution_controls["position_control_shadow_only"] = False
+        else:
+            execution_controls["capital_impact"] = "notification_only"
+            execution_controls["strategy_runtime_metadata_allowed"] = False
+            execution_controls["position_control_shadow_only"] = True
     if notification_target_policy is not None:
         execution_controls["notification_allowed"] = bool(notification_target_policy.notification_allowed)
         execution_controls["position_control_allowed"] = False