feat: add auditable position control evidence

Co-Authored-By: Codex <noreply@openai.com>

Author: Pigbibi

docs/market-regime-control-plan.md

@@ -148,6 +148,9 @@ allowlist:
   position-control fields.
 - `evidence_status`: records whether the strategy/plugin pair is
   `automation_approved`, `notification_only`, or `deprecated_compatibility`.
+- When `position_control_allowed = true`, the runner output should also expose
+  a machine-readable `auditable_position_control` block with
+  `evidence_package_id`, `evidence_valid_until`, and `bounded_budget`.
 - `since_version`: records the runner schema version where the permission
   became effective.
 

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

@@ -87,6 +87,9 @@
 - `notification_allowed`：允许生成和分发通知 artifact。
 - `position_control_allowed`：允许策略 runtime 自动消费仓位控制字段。
 - `evidence_status`：记录该策略/插件组合是 `automation_approved`、`notification_only` 还是 `deprecated_compatibility`。
+- 当 `position_control_allowed = true` 时，runner 输出还应暴露机器可读的
+  `auditable_position_control` 块，包含 `evidence_package_id`、
+  `evidence_valid_until` 和 `bounded_budget`。
 - `since_version`：记录该消费权限从哪个 runner schema 开始生效。
 
 权限边界写在文档和机器字段里，不重复写进人工通知正文：

docs/plugin_lifecycle_policy.md

@@ -36,6 +36,9 @@ For any plugin-driven capital impact, all three gates must pass:
 2. **Plugin evidence gate**
    - The plugin must be marked `automation_approved` and
      `position_control_allowed = true`.
+   - If the platform enables automated position control, the runner should also
+     carry a machine-readable `auditable_position_control` block with
+     `evidence_package_id`, `evidence_valid_until`, and `bounded_budget`.
 3. **Strategy/platform gate**
    - The consuming strategy must explicitly opt in to the plugin and remain
      allowed by the platform catalog.

docs/plugin_lifecycle_policy.zh-CN.md

@@ -32,6 +32,9 @@
    - artifact 必须匹配支持的 schema version，并在共享契约中保持 `shadow` 模式。
 2. **插件证据门槛**
    - 插件必须标记为 `automation_approved`，且 `position_control_allowed = true`。
+   - 如果平台启用自动仓位控制，runner 还应携带机器可读的
+     `auditable_position_control` 块，包含 `evidence_package_id`、
+     `evidence_valid_until` 和 `bounded_budget`。
 3. **策略 / 平台门槛**
    - 消费策略必须显式 opt-in，并且仍然被平台 catalog 允许。
 

src/quant_strategy_plugins/plugin_policies.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
+from typing import Any, Mapping
 
 EVIDENCE_AUTOMATION_APPROVED = "automation_approved"
 EVIDENCE_NOTIFICATION_ONLY = "notification_only"
@@ -32,6 +33,12 @@
 }
 PLUGIN_RESEARCH_ONLY_REASONS: dict[str, str] = {}
 
+AUDITABLE_POSITION_CONTROL_FIELDS: tuple[str, ...] = (
+    "evidence_package_id",
+    "evidence_valid_until",
+    "bounded_budget",
+)
+
 
 @dataclass(frozen=True)
 class PluginConsumptionPolicy:
@@ -240,6 +247,25 @@ class PluginLifecyclePolicy:
     (policy.plugin, policy.notification_target): policy for policy in PLUGIN_NOTIFICATION_TARGET_POLICIES
 }
 
+
+def extract_auditable_position_control_context(raw: Mapping[str, Any] | None) -> dict[str, Any]:
+    """Return the auditable position-control evidence block if present.
+
+    The preferred shape is ``{"auditable_position_control": {...}}`` but the
+    helper also accepts a flat mapping so existing configs can opt in without a
+    schema migration.
+    """
+    if not isinstance(raw, Mapping):
+        return {}
+    candidate = raw.get("auditable_position_control")
+    if isinstance(candidate, Mapping):
+        raw = candidate
+    return {
+        key: raw[key]
+        for key in AUDITABLE_POSITION_CONTROL_FIELDS
+        if raw.get(key) is not None
+    }
+
 PLUGIN_COMPATIBLE_STRATEGIES: dict[str, tuple[str, ...]] = {
     plugin: tuple(
         policy.strategy
@@ -262,6 +288,7 @@ class PluginLifecyclePolicy:
     "EVIDENCE_AUTOMATION_APPROVED",
     "EVIDENCE_DEPRECATED_COMPATIBILITY",
     "EVIDENCE_NOTIFICATION_ONLY",
+    "AUDITABLE_POSITION_CONTROL_FIELDS",
     "GENERAL_MARKET_REGIME_NOTIFICATION_TARGET",
     "PLUGIN_COMPATIBLE_NOTIFICATION_TARGETS",
     "PLUGIN_COMPATIBLE_STRATEGIES",
@@ -285,4 +312,5 @@ class PluginLifecyclePolicy:
     "PluginConsumptionPolicy",
     "PluginLifecyclePolicy",
     "PluginNotificationTargetPolicy",
+    "extract_auditable_position_control_context",
 ]

src/quant_strategy_plugins/strategy_plugin_runner.py

@@ -54,6 +54,7 @@
     PLUGIN_RESEARCH_ONLY_REASONS,
     PLUGIN_SCHEMA_VERSIONS,
     PLUGIN_TACO_REBOUND_SHADOW,
+    extract_auditable_position_control_context,
     PluginConsumptionPolicy,
     PluginLifecyclePolicy,
     PluginNotificationTargetPolicy,
@@ -1323,6 +1324,7 @@ def _apply_plugin_contract(
     notification_target: str | None = None,
     plugin: str,
     mode: str,
+    auditable_position_control: Mapping[str, Any] | None = None,
     consumption_policy: PluginConsumptionPolicy | None = None,
     notification_target_policy: PluginNotificationTargetPolicy | None = None,
 ) -> dict[str, Any]:
@@ -1368,6 +1370,10 @@ def _apply_plugin_contract(
             execution_controls["capital_impact"] = "strategy_opt_in"
             execution_controls["strategy_runtime_metadata_allowed"] = True
             execution_controls["position_control_shadow_only"] = False
+            if auditable_position_control:
+                execution_controls["auditable_position_control"] = auditable_position_control
+                contracted_payload["position_control"] = dict(contracted_payload.get("position_control") or {})
+                contracted_payload["position_control"]["auditable_position_control"] = auditable_position_control
         else:
             execution_controls["capital_impact"] = "notification_only"
             execution_controls["strategy_runtime_metadata_allowed"] = False
@@ -1513,6 +1519,9 @@ def _run_table_strategy_plugin(
         strategy=strategy,
         plugin=plugin,
         mode=mode,
+        auditable_position_control=extract_auditable_position_control_context(
+            plugin_config.get("auditable_position_control")
+        ),
         consumption_policy=consumption_policy,
     )
     paths = spec.write_outputs(payload, output_dir)

tests/test_plugin_policies.py

@@ -2,6 +2,7 @@
 
 import quant_strategy_plugins.strategy_plugin_runner as strategy_plugin_runner
 from quant_strategy_plugins.plugin_policies import (
+    AUDITABLE_POSITION_CONTROL_FIELDS,
     EVIDENCE_AUTOMATION_APPROVED,
     GENERAL_MARKET_REGIME_NOTIFICATION_TARGET,
     PLUGIN_COMPATIBLE_STRATEGIES,
@@ -11,6 +12,7 @@
     PLUGIN_LIFECYCLE_POLICY_REGISTRY,
     PLUGIN_MARKET_REGIME_CONTROL,
     PLUGIN_NOTIFICATION_TARGET_POLICY_REGISTRY,
+    extract_auditable_position_control_context,
 )
 
 
@@ -37,3 +39,39 @@ def test_deprecated_plugin_lifecycle_blocks_new_mounts_but_keeps_replay() -> Non
     assert policy.new_mount_allowed is False
     assert policy.replay_only is True
     assert policy.successor == PLUGIN_MARKET_REGIME_CONTROL
+
+
+def test_extract_auditable_position_control_context_supports_nested_and_flat_shapes() -> None:
+    nested = extract_auditable_position_control_context(
+        {
+            "auditable_position_control": {
+                "evidence_package_id": "pkg_001",
+                "evidence_valid_until": "2026-08-01T00:00:00Z",
+                "bounded_budget": {"name": "position_control", "amount": 0.5, "unit": "fraction"},
+                "ignored": "value",
+            }
+        }
+    )
+    flat = extract_auditable_position_control_context(
+        {
+            "evidence_package_id": "pkg_002",
+            "evidence_valid_until": "2026-08-02T00:00:00Z",
+            "bounded_budget": {"name": "position_control", "amount": 0.25, "unit": "fraction"},
+        }
+    )
+
+    assert tuple(AUDITABLE_POSITION_CONTROL_FIELDS) == (
+        "evidence_package_id",
+        "evidence_valid_until",
+        "bounded_budget",
+    )
+    assert nested == {
+        "evidence_package_id": "pkg_001",
+        "evidence_valid_until": "2026-08-01T00:00:00Z",
+        "bounded_budget": {"name": "position_control", "amount": 0.5, "unit": "fraction"},
+    }
+    assert flat == {
+        "evidence_package_id": "pkg_002",
+        "evidence_valid_until": "2026-08-02T00:00:00Z",
+        "bounded_budget": {"name": "position_control", "amount": 0.25, "unit": "fraction"},
+    }

tests/test_strategy_plugin_runner.py

@@ -680,6 +680,15 @@ def test_strategy_plugin_runner_runs_unified_market_regime_control_for_soxl(tmp_
                 "plugin": PLUGIN_MARKET_REGIME_CONTROL,
                 "enabled": True,
                 "inputs": {"prices": str(prices_path), "benchmark_symbol": "SOXX", "attack_symbol": "SOXL"},
+                "auditable_position_control": {
+                    "evidence_package_id": "pkg_001",
+                    "evidence_valid_until": "2026-08-01T00:00:00Z",
+                    "bounded_budget": {
+                        "name": "position_control",
+                        "amount": 0.5,
+                        "unit": "fraction",
+                    },
+                },
                 "outputs": {"output_dir": str(output_dir)},
             }
         ],
@@ -697,6 +706,15 @@ def test_strategy_plugin_runner_runs_unified_market_regime_control_for_soxl(tmp_
     assert payload["execution_controls"]["strategy_runtime_metadata_allowed"] is True
     assert payload["execution_controls"]["capital_impact"] == "strategy_opt_in"
     assert payload["execution_controls"]["position_control_shadow_only"] is False
+    assert payload["execution_controls"]["auditable_position_control"] == {
+        "evidence_package_id": "pkg_001",
+        "evidence_valid_until": "2026-08-01T00:00:00Z",
+        "bounded_budget": {
+            "name": "position_control",
+            "amount": 0.5,
+            "unit": "fraction",
+        },
+    }
     assert payload["execution_controls"]["manual_review_notification_delegated"] is True
     assert (
         payload["execution_controls"]["manual_review_notification_target"]
@@ -709,6 +727,7 @@ def test_strategy_plugin_runner_runs_unified_market_regime_control_for_soxl(tmp_
     volatility_delever_context = payload["position_control"]["volatility_delever_context"]
     assert volatility_delever_context["actionable_for_position_control"] is True
     assert volatility_delever_context["retention_profiles"]["soxl_step_rebound_0.25_0.50"]["retention_ratio"] == 0.0
+    assert payload["position_control"]["auditable_position_control"] == payload["execution_controls"]["auditable_position_control"]
 
 
 def test_strategy_plugin_runner_marks_pending_strategy_mount_notification_only(tmp_path) -> None: