Add platform cash reserve policy

Author: Pigbibi

.env.example

@@ -39,5 +39,7 @@ FIRSTRADE_SESSION_CHECK_INCLUDE_POSITIONS=false
 FIRSTRADE_RUN_STRATEGY_ON_HTTP=false
 FIRSTRADE_LIVE_ORDER_ACK=false
 FIRSTRADE_MAX_ORDER_NOTIONAL_USD=
+FIRSTRADE_MIN_RESERVED_CASH_USD=0
+FIRSTRADE_RESERVED_CASH_RATIO=0
 FIRSTRADE_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD=1000
 FIRSTRADE_SMOKE_SYMBOL=SPY

.github/workflows/sync-cloud-run-env.yml

@@ -46,6 +46,8 @@ jobs:
       FIRSTRADE_RUN_STRATEGY_ON_HTTP: ${{ vars.FIRSTRADE_RUN_STRATEGY_ON_HTTP }}
       FIRSTRADE_LIVE_ORDER_ACK: ${{ vars.FIRSTRADE_LIVE_ORDER_ACK }}
       FIRSTRADE_MAX_ORDER_NOTIONAL_USD: ${{ vars.FIRSTRADE_MAX_ORDER_NOTIONAL_USD }}
+      FIRSTRADE_MIN_RESERVED_CASH_USD: ${{ vars.FIRSTRADE_MIN_RESERVED_CASH_USD }}
+      FIRSTRADE_RESERVED_CASH_RATIO: ${{ vars.FIRSTRADE_RESERVED_CASH_RATIO }}
       FIRSTRADE_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD: ${{ vars.FIRSTRADE_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD }}
       FIRSTRADE_SMOKE_SYMBOL: ${{ vars.FIRSTRADE_SMOKE_SYMBOL }}
       FIRSTRADE_FEATURE_SNAPSHOT_PATH: ${{ vars.FIRSTRADE_FEATURE_SNAPSHOT_PATH }}
@@ -414,6 +416,8 @@ jobs:
           add_optional_env FIRSTRADE_RUN_STRATEGY_ON_HTTP
           add_optional_env FIRSTRADE_LIVE_ORDER_ACK
           add_optional_env FIRSTRADE_MAX_ORDER_NOTIONAL_USD
+          add_optional_env FIRSTRADE_MIN_RESERVED_CASH_USD
+          add_optional_env FIRSTRADE_RESERVED_CASH_RATIO
           add_optional_env FIRSTRADE_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD
           add_optional_env FIRSTRADE_SMOKE_SYMBOL
           add_optional_env FIRSTRADE_FEATURE_SNAPSHOT_PATH

README.md

@@ -92,6 +92,8 @@ commit credentials.
 | `FIRSTRADE_RUN_STRATEGY_ON_HTTP` | Optional | Must be `true` before `/run` performs strategy evaluation and order routing |
 | `FIRSTRADE_LIVE_ORDER_ACK` | Optional | Must be `true` before `/run` can submit live orders |
 | `FIRSTRADE_MAX_ORDER_NOTIONAL_USD` | Optional | Optional single-order cap for strategy-generated orders. Unset means no platform-side notional cap |
+| `FIRSTRADE_MIN_RESERVED_CASH_USD` | Optional | Platform-level minimum cash reserve in USD. Defaults to `0`; the effective reserve is the max of this floor, `FIRSTRADE_RESERVED_CASH_RATIO * total equity`, and any strategy-provided reserve. |
+| `FIRSTRADE_RESERVED_CASH_RATIO` | Optional | Platform-level minimum cash reserve ratio in `[0,1]`. Defaults to `0`; it can raise but not lower a strategy-provided reserve. |
 | `FIRSTRADE_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD` | Optional | Safe-haven/cash-sweep target values below this USD amount are kept as cash instead of buying BOXX/BIL. Default `1000`. |
 
 ## Local Validation
@@ -176,6 +178,7 @@ all of these gates:
 - `FIRSTRADE_ENABLE_LIVE_TRADING=true`
 - `FIRSTRADE_LIVE_ORDER_ACK=true`
 - order value at or below `FIRSTRADE_MAX_ORDER_NOTIONAL_USD` when that optional cap is set
+- `FIRSTRADE_MIN_RESERVED_CASH_USD` / `FIRSTRADE_RESERVED_CASH_RATIO` may set a platform-level minimum cash reserve; defaults are `0`, and the effective reserve is the max of platform floor, platform ratio, and strategy reserve
 
 The strategy execution service uses whole-share limit orders for generated
 strategy orders. If the notional cap is below the current price of a target
@@ -324,6 +327,7 @@ HTTP 策略闭环实盘还必须额外满足：
 - `FIRSTRADE_DRY_RUN_ONLY=false`
 - `FIRSTRADE_LIVE_ORDER_ACK=true`
 - 如果设置了 `FIRSTRADE_MAX_ORDER_NOTIONAL_USD`，单笔金额不超过该上限
+- `FIRSTRADE_MIN_RESERVED_CASH_USD` / `FIRSTRADE_RESERVED_CASH_RATIO` 可设置平台级最低预留现金；默认都是 `0`，实际预留取平台下限、平台比例和策略预留中的最大值
 - `BOXX`/`BIL` 等避险现金替代标的目标金额低于 `FIRSTRADE_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD` 时保留现金，默认门槛 `1000` USD
 
 策略闭环生成的是整数股限价单。如果设置了 `FIRSTRADE_MAX_ORDER_NOTIONAL_USD`

application/rebalance_service.py

@@ -162,6 +162,22 @@ def publish_log(text: str) -> None:
     return True
 
 
+def _runtime_metadata_with_execution_policy(
+    metadata: Mapping[str, Any] | None,
+    *,
+    settings: PlatformRuntimeSettings,
+) -> dict[str, Any]:
+    runtime_metadata = dict(metadata or {})
+    runtime_metadata.setdefault(
+        "firstrade_execution_policy",
+        {
+            "reserved_cash_floor_usd": float(settings.reserved_cash_floor_usd or 0.0),
+            "reserved_cash_ratio": float(settings.reserved_cash_ratio or 0.0),
+        },
+    )
+    return runtime_metadata
+
+
 def run_strategy_cycle(
     *,
     runtime_settings: PlatformRuntimeSettings | None = None,
@@ -221,7 +237,10 @@ def run_strategy_cycle(
         evaluation.decision,
         snapshot=snapshot,
         strategy_profile=settings.strategy_profile,
-        runtime_metadata=getattr(evaluation, "metadata", None),
+        runtime_metadata=_runtime_metadata_with_execution_policy(
+            getattr(evaluation, "metadata", None),
+            settings=settings,
+        ),
     )
     plan = substitute_small_safe_haven_targets_with_cash(
         plan,

decision_mapper.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from collections.abc import Mapping
+from dataclasses import replace
 from typing import Any
 
 from quant_platform_kit.strategy_contracts import (
@@ -34,6 +35,50 @@ def _default_threshold_value(total_equity: float) -> float:
     return max(_DEFAULT_MIN_TRADE_FLOOR, float(total_equity) * _DEFAULT_REBALANCE_THRESHOLD_RATIO)
 
 
+def _resolve_platform_reserved_cash(
+    *,
+    total_equity: float,
+    runtime_metadata: Mapping[str, Any] | None,
+) -> float:
+    raw_policy = (runtime_metadata or {}).get("firstrade_execution_policy")
+    if not isinstance(raw_policy, Mapping):
+        return 0.0
+    reserved_cash_floor_usd = max(0.0, float(raw_policy.get("reserved_cash_floor_usd", 0.0) or 0.0))
+    reserved_cash_ratio = float(raw_policy.get("reserved_cash_ratio", 0.0) or 0.0)
+    reserved_cash_ratio = max(0.0, min(1.0, reserved_cash_ratio))
+    return max(reserved_cash_floor_usd, max(0.0, float(total_equity)) * reserved_cash_ratio)
+
+
+def _apply_reserved_cash_policy(
+    annotations: ValueTargetExecutionAnnotations,
+    *,
+    portfolio_inputs,
+    runtime_metadata: Mapping[str, Any] | None,
+) -> ValueTargetExecutionAnnotations:
+    reserved_cash = max(
+        float(annotations.reserved_cash or 0.0),
+        _resolve_platform_reserved_cash(
+            total_equity=float(portfolio_inputs.total_equity),
+            runtime_metadata=runtime_metadata,
+        ),
+    )
+    base_investable_cash = annotations.investable_cash
+    if base_investable_cash is None:
+        base_investable_cash = max(
+            0.0,
+            float(portfolio_inputs.liquid_cash) - float(annotations.reserved_cash or 0.0),
+        )
+    investable_cash = min(
+        max(0.0, float(base_investable_cash)),
+        max(0.0, float(portfolio_inputs.liquid_cash) - reserved_cash),
+    )
+    return replace(
+        annotations,
+        reserved_cash=reserved_cash,
+        investable_cash=investable_cash,
+    )
+
+
 def _build_hold_current_value_decision(portfolio_inputs, *, diagnostics: Mapping[str, Any]) -> StrategyDecision:
     positions = []
     for symbol, market_value in sorted(portfolio_inputs.market_values.items()):
@@ -210,6 +255,11 @@ def map_strategy_decision_to_plan(
         normalized_decision,
         portfolio_inputs=portfolio_inputs,
     )
+    annotations = _apply_reserved_cash_policy(
+        annotations,
+        portfolio_inputs=portfolio_inputs,
+        runtime_metadata=runtime_metadata,
+    )
     plan = build_value_target_runtime_plan(
         normalized_decision,
         strategy_profile=canonical_profile,

runtime_config_support.py

@@ -23,6 +23,8 @@
 from us_equity_strategies import get_strategy_catalog
 
 DEFAULT_ACCOUNT_REGION = "US"
+DEFAULT_RESERVED_CASH_FLOOR_USD = 0.0
+DEFAULT_RESERVED_CASH_RATIO = 0.0
 DEFAULT_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD = 1000.0
 
 
@@ -42,6 +44,8 @@ class PlatformRuntimeSettings:
     run_strategy_on_http: bool
     live_order_ack: bool
     max_order_notional_usd: float | None
+    reserved_cash_floor_usd: float = DEFAULT_RESERVED_CASH_FLOOR_USD
+    reserved_cash_ratio: float = DEFAULT_RESERVED_CASH_RATIO
     persist_strategy_runs: bool = False
     safe_haven_cash_substitute_threshold_usd: float = DEFAULT_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD
     debug_position_snapshot: bool = False
@@ -113,6 +117,14 @@ def load_platform_runtime_settings(
             os.environ,
             "FIRSTRADE_MAX_ORDER_NOTIONAL_USD",
         ),
+        reserved_cash_floor_usd=_resolve_non_negative_float_env(
+            "FIRSTRADE_MIN_RESERVED_CASH_USD",
+            default=DEFAULT_RESERVED_CASH_FLOOR_USD,
+        ),
+        reserved_cash_ratio=_resolve_ratio_env(
+            "FIRSTRADE_RESERVED_CASH_RATIO",
+            default=DEFAULT_RESERVED_CASH_RATIO,
+        ),
         safe_haven_cash_substitute_threshold_usd=(
             max(0.0, safe_haven_cash_substitute_threshold_usd)
             if safe_haven_cash_substitute_threshold_usd is not None
@@ -172,6 +184,22 @@ def _qqqi_income_ratio_env() -> float | None:
     return value
 
 
+def _resolve_non_negative_float_env(name: str, *, default: float) -> float:
+    value = resolve_optional_float_env(os.environ, name)
+    if value is None:
+        return float(default)
+    if value < 0:
+        raise ValueError(f"{name} must be non-negative, got {value}")
+    return float(value)
+
+
+def _resolve_ratio_env(name: str, *, default: float) -> float:
+    value = _resolve_non_negative_float_env(name, default=default)
+    if value > 1.0:
+        raise ValueError(f"{name} must be in [0,1], got {value}")
+    return value
+
+
 def _runtime_execution_window_trading_days_env(strategy_profile: str) -> int | None:
     raw_value = os.getenv("FIRSTRADE_RUNTIME_EXECUTION_WINDOW_TRADING_DAYS")
     env_name = "FIRSTRADE_RUNTIME_EXECUTION_WINDOW_TRADING_DAYS"

tests/test_decision_mapper.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from quant_platform_kit.common.models import PortfolioSnapshot, Position
+from quant_platform_kit.strategy_contracts import PositionTarget, StrategyDecision
+
+from decision_mapper import map_strategy_decision_to_plan
+
+
+def test_applies_platform_reserved_cash_policy_to_weight_decision():
+    decision = StrategyDecision(
+        positions=(
+            PositionTarget(symbol="AAPL", target_weight=0.5),
+            PositionTarget(symbol="MSFT", target_weight=0.5),
+        ),
+        diagnostics={"signal_description": "risk on"},
+    )
+    snapshot = PortfolioSnapshot(
+        as_of=datetime.now(timezone.utc),
+        total_equity=20000.0,
+        buying_power=4000.0,
+        positions=(Position(symbol="AAPL", quantity=1, market_value=1000.0),),
+    )
+
+    plan = map_strategy_decision_to_plan(
+        decision,
+        snapshot=snapshot,
+        strategy_profile="mega_cap_leader_rotation_top50_balanced",
+        runtime_metadata={
+            "firstrade_execution_policy": {
+                "reserved_cash_floor_usd": 1500.0,
+                "reserved_cash_ratio": 0.03,
+            }
+        },
+    )
+
+    assert plan["execution"]["reserved_cash"] == 1500.0
+    assert plan["execution"]["investable_cash"] == 2500.0
+
+
+def test_platform_reserved_cash_policy_does_not_lower_strategy_reserve():
+    decision = StrategyDecision(
+        positions=(PositionTarget(symbol="AAA", target_value=5000.0),),
+        diagnostics={
+            "execution_annotations": {
+                "trade_threshold_value": 100.0,
+                "reserved_cash": 1200.0,
+            }
+        },
+    )
+    snapshot = PortfolioSnapshot(
+        as_of=datetime.now(timezone.utc),
+        total_equity=10000.0,
+        buying_power=3000.0,
+        positions=(),
+    )
+
+    plan = map_strategy_decision_to_plan(
+        decision,
+        snapshot=snapshot,
+        strategy_profile="tqqq_growth_income",
+        runtime_metadata={
+            "firstrade_execution_policy": {
+                "reserved_cash_floor_usd": 150.0,
+                "reserved_cash_ratio": 0.03,
+            }
+        },
+    )
+
+    assert plan["execution"]["reserved_cash"] == 1200.0
+    assert plan["execution"]["investable_cash"] == 1800.0

tests/test_runtime_config_support.py

@@ -2,7 +2,19 @@
 
 import pytest
 
-from runtime_config_support import _runtime_execution_window_trading_days_env
+from runtime_config_support import (
+    _resolve_ratio_env,
+    _runtime_execution_window_trading_days_env,
+    load_platform_runtime_settings,
+)
+
+
+def _target_json(profile="mega_cap_leader_rotation_top50_balanced") -> str:
+    return (
+        '{"platform_id":"firstrade","strategy_profile":"'
+        + profile
+        + '","dry_run_only":true,"execution_mode":"paper"}'
+    )
 
 
 def test_runtime_execution_window_uses_generic_env(monkeypatch):
@@ -33,6 +45,33 @@ def test_runtime_execution_window_keeps_legacy_tech_env(monkeypatch):
     )
 
 
+def test_reserved_cash_policy_defaults_to_zero(monkeypatch):
+    monkeypatch.setenv("RUNTIME_TARGET_JSON", _target_json())
+
+    settings = load_platform_runtime_settings(project_id_resolver=lambda: "project-1")
+
+    assert settings.reserved_cash_floor_usd == 0.0
+    assert settings.reserved_cash_ratio == 0.0
+
+
+def test_reserved_cash_policy_loads_from_env(monkeypatch):
+    monkeypatch.setenv("RUNTIME_TARGET_JSON", _target_json())
+    monkeypatch.setenv("FIRSTRADE_MIN_RESERVED_CASH_USD", "250")
+    monkeypatch.setenv("FIRSTRADE_RESERVED_CASH_RATIO", "0.025")
+
+    settings = load_platform_runtime_settings(project_id_resolver=lambda: "project-1")
+
+    assert settings.reserved_cash_floor_usd == 250.0
+    assert settings.reserved_cash_ratio == 0.025
+
+
+def test_reserved_cash_ratio_rejects_invalid_env(monkeypatch):
+    monkeypatch.setenv("FIRSTRADE_RESERVED_CASH_RATIO", "1.25")
+
+    with pytest.raises(ValueError, match="FIRSTRADE_RESERVED_CASH_RATIO"):
+        _resolve_ratio_env("FIRSTRADE_RESERVED_CASH_RATIO", default=0.0)
+
+
 @pytest.mark.parametrize("raw_value", ["0", "-1", "abc"])
 def test_runtime_execution_window_rejects_invalid_generic_env(monkeypatch, raw_value):
     monkeypatch.setenv("FIRSTRADE_RUNTIME_EXECUTION_WINDOW_TRADING_DAYS", raw_value)