fix: require explicit IBKR broker paper environment

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

Author: Pigbibi

application/paper_execution_admission.py

@@ -29,6 +29,7 @@
     RuntimeCommandGatePolicy,
     evaluate_runtime_command_gate,
 )
+from quant_platform_kit.common.runtime_target import RuntimeExecutionEnvironment
 
 
 PAPER_EXECUTION_ADMISSION_SCHEMA_VERSION = "ibkr.paper_execution_admission.v1"
@@ -44,17 +45,26 @@ def resolve_paper_execution_admission_enabled(
     env_reader,
     dry_run_only: bool,
     execution_mode: object,
+    execution_environment: object | None = None,
 ) -> bool:
-    """Resolve the opt-in flag and reject every non-PAPER configuration."""
+    """Resolve the opt-in flag and require an explicit broker PAPER target."""
 
     raw_value = str(env_reader("IBKR_PAPER_EXECUTION_ADMISSION_ENABLED", "") or "").strip().lower()
     enabled = raw_value in {"1", "true", "t", "yes", "y", "on"}
     if not enabled:
         return False
     normalized_mode = str(execution_mode or "").strip().lower().replace("-", "_")
-    if dry_run_only or normalized_mode != "paper":
+    normalized_environment = str(
+        getattr(execution_environment, "value", execution_environment) or ""
+    ).strip().lower()
+    if (
+        dry_run_only
+        or normalized_mode != "paper"
+        or normalized_environment != RuntimeExecutionEnvironment.PAPER.value
+    ):
         raise RuntimeError(
-            "IBKR_PAPER_EXECUTION_ADMISSION_ENABLED is only supported for ordinary execution_mode=paper"
+            "IBKR_PAPER_EXECUTION_ADMISSION_ENABLED requires "
+            "dry_run_only=false, execution_mode=paper, and execution_environment=paper"
         )
     return True
 

application/runtime_composer.py

@@ -193,6 +193,11 @@ def build_rebalance_config(self, *, extra_notification_lines=(), cash_only_execu
                 env_reader=self.env_reader,
                 dry_run_only=self.dry_run_only,
                 execution_mode=execution_mode,
+                execution_environment=(
+                    self.runtime_target.execution_environment
+                    if self.runtime_target is not None
+                    else None
+                ),
             ),
             runtime_release_receipt=build_runtime_loaded_receipt(
                 strategy_release=(

docs/ibkr_paper_execution_admission.md

@@ -1,8 +1,10 @@
 # IBKR PAPER execution admission
 
 `IBKR_PAPER_EXECUTION_ADMISSION_ENABLED` is an opt-in guard for the ordinary
-IBKR `execution_mode=paper` rebalance path. Its default is disabled. It does
-not apply to `IBKR_PAPER_LIQUIDATE_ONLY`, dry-run previews, live execution,
+IBKR `execution_mode=paper` rebalance path. Its default is disabled. It
+requires the shared runtime target to explicitly declare
+`execution_environment=paper` with `dry_run_only=false`. It does not apply to
+`IBKR_PAPER_LIQUIDATE_ONLY`, local dry-run previews, live execution,
 deployment workflows, or schedulers.
 
 When explicitly enabled, the strategy/control-plane producer must place a QPK
@@ -22,5 +24,5 @@ reconciled exposure facts, and enforced runtime-gate receipts are persisted in
 the normal reconciliation record under `paper_execution_admission`.
 
 Do not enable the flag until an upstream producer can supply this immutable
-command contract. Enabling it for a non-PAPER or dry-run target fails at
-startup rather than silently weakening the guard.
+command contract. Enabling it for a non-PAPER, local dry-run, or ambiguous
+runtime target fails at startup rather than silently weakening the guard.

main.py

@@ -623,6 +623,11 @@ def build_broker_adapters(*, dry_run_only_override: bool | None = None):
             env_reader=os.getenv,
             dry_run_only=effective_dry_run_only,
             execution_mode=effective_execution_mode,
+            execution_environment=(
+                RUNTIME_SETTINGS.runtime_target.execution_environment
+                if RUNTIME_SETTINGS.runtime_target is not None
+                else None
+            ),
         ),
         runtime_release_receipt=build_runtime_loaded_receipt(
             strategy_release=expected_strategy_release,

pyproject.toml

@@ -21,7 +21,7 @@ dependencies = [
     "google-cloud-secret-manager",
     "google-cloud-storage",
     "yfinance",
-    "quant-platform-kit @ git+https://github.com/QuantStrategyLab/QuantPlatformKit.git@3fa3b7588eb220e77b3d3851ce9f192046d47afd",
+    "quant-platform-kit @ git+https://github.com/QuantStrategyLab/QuantPlatformKit.git@0507eedd44b8590ef232008a2b6d1469fec0b910",
     "us-equity-strategies @ git+https://github.com/QuantStrategyLab/UsEquityStrategies.git@64574bdd0e213c6938c5144773d7e827ddef4ef2",
     "hk-equity-strategies @ git+https://github.com/QuantStrategyLab/HkEquityStrategies.git@7e9abf9b0f92647f04b4978ff0771b3bd4f75ae3",
 ]
@@ -64,5 +64,5 @@ include = [
 
 [tool.uv]
 override-dependencies = [
-  "quant-platform-kit @ git+https://github.com/QuantStrategyLab/QuantPlatformKit.git@3fa3b7588eb220e77b3d3851ce9f192046d47afd",
+  "quant-platform-kit @ git+https://github.com/QuantStrategyLab/QuantPlatformKit.git@0507eedd44b8590ef232008a2b6d1469fec0b910",
 ]

qsl.toml

@@ -5,7 +5,7 @@ upgrade_ring = "ring_d"
 allow_legacy = false
 
 [qsl.requires]
-quant_platform_kit = "3fa3b7588eb220e77b3d3851ce9f192046d47afd"
+quant_platform_kit = "0507eedd44b8590ef232008a2b6d1469fec0b910"
 us_equity_strategies = "64574bdd0e213c6938c5144773d7e827ddef4ef2"
 hk_equity_strategies = "7e9abf9b0f92647f04b4978ff0771b3bd4f75ae3"
 

tests/test_paper_execution_admission.py

@@ -14,6 +14,7 @@
     build_paper_risk_admission_receipt,
 )
 from quant_platform_kit.common.strategy_release import build_runtime_loaded_receipt
+from quant_platform_kit.common.runtime_target import RuntimeExecutionEnvironment
 
 
 def _release_identity() -> dict[str, str]:
@@ -86,12 +87,21 @@ def test_paper_admission_is_opt_in_and_rejects_non_paper_enablement():
         env_reader=lambda _name, _default: "true",
         dry_run_only=False,
         execution_mode="paper",
+        execution_environment=RuntimeExecutionEnvironment.PAPER,
     )
-    with pytest.raises(RuntimeError, match="execution_mode=paper"):
+    with pytest.raises(RuntimeError, match="execution_environment=paper"):
         resolve_paper_execution_admission_enabled(
             env_reader=lambda _name, _default: "true",
             dry_run_only=False,
             execution_mode="live",
+            execution_environment=RuntimeExecutionEnvironment.LIVE,
+        )
+    with pytest.raises(RuntimeError, match="execution_environment=paper"):
+        resolve_paper_execution_admission_enabled(
+            env_reader=lambda _name, _default: "true",
+            dry_run_only=True,
+            execution_mode="dry_run",
+            execution_environment=RuntimeExecutionEnvironment.DRY_RUN,
         )