Skip to content

"Vibe-Trading: Your Personal Trading Agent"

fix(backtest): a cash-starved open in hold mode is one insufficient_capital rejection, not a zero_size per search step (#1470)

Haozhe Wu0a196e7cb692
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 05fb64fd5..f978a9cc0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -76,6 +76,15 @@ This project adheres to [Semantic Versioning](https://semver.org/).
### Fixed
+- **One cash-starved open is one rejection, not twenty-six** (#1470). In
+ `position_adjustment="hold"`, the search that scales a basket down to the
+ cash available re-planned every open on each step, and every step whose
+ size rounded to zero booked a `zero_size` rejection for the same symbol on
+ the same bar — one contract the cash could not hold read as 26 lot-rounding
+ failures. The trial plans are silent now; a sleeve that was a real order at
+ full scale and left the basket is reported once, after the search, as
+ `insufficient_capital`, which the rebalance path's dropped sleeves now use
+ too. `zero_size` means the lot rule and nothing else.
- **A real VaR result grounds the VaR it returned** (#1464). `quantlib_call`
records a scalar result under the function name. For `historical_var` and
`parametric_var` that name reduces to `var`, which the grounding gate accepts
diff --git a/agent/backtest/engines/base.py b/agent/backtest/engines/base.py
index 3c6589d48..7619615ac 100644
--- a/agent/backtest/engines/base.py
+++ b/agent/backtest/engines/base.py
@@ -751,6 +751,7 @@ class BaseEngine(ABC):
"execution_blocked",
"invalid_price",
"zero_size",
+ "insufficient_capital",
)
def _plan_rejection_metrics(self) -> Dict[str, Any]:
@@ -803,11 +804,17 @@ class BaseEngine(ABC):
an engine subclass to tell "nothing to do" apart from "wanted but
unfillable".
+ The capital fit reports one more cause after the planner: a sleeve that
+ was a real order at full scale and left the basket when every opening
+ order was scaled down to the cash available is ``insufficient_capital``
+ (#1470), reported once per bar — never the trial plans of the search.
+
Args:
symbol: Instrument the plan was for.
reason: Machine-readable cause: ``no_target_weight``,
``already_held``, ``no_data``, ``no_bar``,
- ``execution_blocked``, ``invalid_price`` or ``zero_size``.
+ ``execution_blocked``, ``invalid_price``, ``zero_size`` or
+ ``insufficient_capital``.
timestamp: Decision bar timestamp.
"""
self.plan_rejections[(symbol, reason)] += 1
@@ -1246,12 +1253,12 @@ class BaseEngine(ABC):
if current_pos is None and target_dir != 0:
open_targets.append((c, target_w, data_map.get(c)))
- def _plans(scale: float) -> list[_OpenOrder]:
+ def _plans(scale: float, *, observe: bool) -> list[_OpenOrder]:
result: list[_OpenOrder] = []
for c, target_w, frame in open_targets:
try:
order = self._plan_open_order(
- c, target_w * scale, frame, ts, equity
+ c, target_w * scale, frame, ts, equity, observe=observe
)
except Exception as exc:
logger.warning(
@@ -1265,16 +1272,25 @@ class BaseEngine(ABC):
result.append(order)
return result
- planned = _plans(1.0)
+ planned = _plans(1.0, observe=True)
if sum(order.cost for order in planned) > self.capital + 1e-9:
+ # The trial plans of the search are not findings: one starved
+ # open used to be booked as a zero_size rejection on every
+ # bisection step (#1470). The sleeve that leaves the basket is
+ # reported once, after the search, as the rebalance path does.
+ wanted = [order.symbol for order in planned]
low, high = 0.0, 1.0
for _ in range(50):
mid = (low + high) / 2.0
- candidate = _plans(mid)
+ candidate = _plans(mid, observe=False)
if sum(order.cost for order in candidate) <= self.capital + 1e-9:
low, planned = mid, candidate
else:
high = mid
+ fitted = {order.symbol for order in planned}
+ for symbol in wanted:
+ if symbol not in fitted:
+ self._on_plan_rejected(symbol, "insufficient_capital", ts)
for order in planned:
self._execute_open_order(order, ts)
@@ -1497,25 +1513,35 @@ class BaseEngine(ABC):
equity: float,
*,
allow_existing: bool = False, require_positive_price: bool = False,
+ observe: bool = True,
) -> Optional[_OpenOrder]:
- """Price an opening order without mutating portfolio state."""
+ """Price an opening order without mutating portfolio state.
+
+ ``observe=False`` plans a trial inside a capital-fit search: a rejection
+ there is not a finding and is not reported to ``_on_plan_rejected``.
+ """
self._active_symbol = symbol
+
+ def rejected(reason: str) -> None:
+ if observe:
+ self._on_plan_rejected(symbol, reason, ts)
+
direction = 1 if target_weight > 1e-9 else (-1 if target_weight < -1e-9 else 0)
if direction == 0:
- self._on_plan_rejected(symbol, "no_target_weight", ts)
+ rejected("no_target_weight")
return None
if symbol in self.positions and not allow_existing:
- self._on_plan_rejected(symbol, "already_held", ts)
+ rejected("already_held")
return None
if df is None:
- self._on_plan_rejected(symbol, "no_data", ts)
+ rejected("no_data")
return None
if ts not in df.index:
- self._on_plan_rejected(symbol, "no_bar", ts)
+ rejected("no_bar")
return None
bar = df.loc[ts]
if not self.can_execute(symbol, direction, bar):
- self._on_plan_rejected(symbol, "execution_blocked", ts)
+ rejected("execution_blocked")
return None
open_price = self.execution_open(bar)
if require_positive_price:
@@ -1524,7 +1550,7 @@ class BaseEngine(ABC):
# negatives are rejected unless this engine opted into non-positive
# prices, in which case abs()-based sizing/margin below handle them.
elif open_price == 0 or (open_price < 0 and not self.allow_nonpositive_prices):
- self._on_plan_rejected(symbol, "invalid_price", ts)
+ rejected("invalid_price")
return None
price = self.apply_slippage(open_price, direction)
if require_positive_price:
@@ -1535,7 +1561,7 @@ class BaseEngine(ABC):
self._calc_raw_size(symbol, target_notional, price), price
)
if size <= 0:
- self._on_plan_rejected(symbol, "zero_size", ts)
+ rejected("zero_size")
return None
margin = self._calc_margin(symbol, size, price, leverage)
commission = self.calc_commission(
@@ -1760,8 +1786,9 @@ class BaseEngine(ABC):
capital weights shift by each sleeve's fee, as with the open path).
Sizes re-round per market lot rules; a sleeve whose rounded size hits
zero is dropped and recorded via ``_on_plan_rejected`` as
- ``zero_size`` — the same record a too-small plan gets in the open
- path — so run-card diagnostics see the dropped leg.
+ ``insufficient_capital`` — it was a real order at full scale, so it is
+ the cash that failed, not the lot rule (#1470) — so run-card
+ diagnostics see the dropped leg.
Returns the fitted orders, or ``None`` when no scale fits — not even
an empty open sleeve — which the caller must treat as an atomic
@@ -1822,7 +1849,7 @@ class BaseEngine(ABC):
- {order.symbol for order in fitted}
)
for symbol in dropped_symbols:
- self._on_plan_rejected(symbol, "zero_size", ts)
+ self._on_plan_rejected(symbol, "insufficient_capital", ts)
logger.warning(
"Rebalance basket scaled to fit capital; sleeves rounded to "
"zero and dropped: %s. Set position_adjustment='hold' or "
diff --git a/agent/tests/test_base_engine.py b/agent/tests/test_base_engine.py
index 21bde62c7..6dd3de240 100644
--- a/agent/tests/test_base_engine.py
+++ b/agent/tests/test_base_engine.py
@@ -916,13 +916,25 @@ def test_rebalance_scaled_away_sleeve_is_recorded_as_plan_rejection():
"""#1274: a sleeve rounded to zero by scaling leaves an audit record.
A fills 9 of its 10 target shares; B's one-lot fill scales below one lot
- and vanishes — run-card diagnostics must see it as a zero_size rejection,
- not silence.
+ and vanishes — run-card diagnostics must see it as an insufficient_capital
+ rejection (#1470: it was a real order at full scale), not silence and not
+ a lot-rounding failure.
"""
engine = _SymbolRulesAdjustmentEngine()
- _run_adjustments(engine, {"A": [1.0], "B": [0.003]})
+ _run_adjustments(engine, {"A": [1.0], "B": [0.025]}) # B: exactly one 0.25 lot
sizes = _sizes(engine.bar_positions[0])
assert sizes == {"A": 9.0} # scaled to fit; B's leg dropped entirely
+ assert engine.plan_rejections[("B", "insufficient_capital")] == 1
+ assert ("B", "zero_size") not in engine.plan_rejections
+
+
+def test_rebalance_sleeve_below_one_lot_at_full_scale_is_the_lot_rule():
+ """A target that never reached one lot is zero_size, not a cash finding."""
+ engine = _SymbolRulesAdjustmentEngine()
+ _run_adjustments(engine, {"A": [1.0], "B": [0.003]}) # B: 0.03 shares, lot 0.25
+
+ assert _sizes(engine.bar_positions[0]) == {"A": 9.0}
assert engine.plan_rejections[("B", "zero_size")] == 1
+ assert ("B", "insufficient_capital") not in engine.plan_rejections
assert engine.bar_capitals[0] >= 0.0
diff --git a/agent/tests/test_engine_robustness.py b/agent/tests/test_engine_robustness.py
index a5f63ceed..4bc82225c 100644
--- a/agent/tests/test_engine_robustness.py
+++ b/agent/tests/test_engine_robustness.py
@@ -122,10 +122,10 @@ class TestSymbolIsolation:
# Patch the opening-plan boundary to throw for BAD only.
original_plan = ChinaAEngine._plan_open_order
- def _exploding_plan(self, symbol, target_weight, df, ts, equity):
+ def _exploding_plan(self, symbol, target_weight, df, ts, equity, **kwargs):
if symbol == "BAD":
raise RuntimeError("Simulated failure for BAD")
- return original_plan(self, symbol, target_weight, df, ts, equity)
+ return original_plan(self, symbol, target_weight, df, ts, equity, **kwargs)
with patch.object(ChinaAEngine, "_plan_open_order", _exploding_plan):
# Should NOT raise — exception is caught internally
diff --git a/agent/tests/test_plan_rejected.py b/agent/tests/test_plan_rejected.py
index 2cda00991..3e4973cad 100644
--- a/agent/tests/test_plan_rejected.py
+++ b/agent/tests/test_plan_rejected.py
@@ -255,9 +255,11 @@ def test_wanted_but_unfillable_plans_are_counted_by_default():
) # execution_blocked
# Benign causes must not be counted as findings.
assert engine._plan_open_order("A", 0.0, _frame(), _TS, 1_000.0) is None
+ # The capital fit, not the planner, reports a sleeve the cash could not hold.
+ engine._on_plan_rejected("A", "insufficient_capital", _TS)
metrics = engine._plan_rejection_metrics()
- assert metrics["unfilled_plan_rejections"] == 5
+ assert metrics["unfilled_plan_rejections"] == 6
assert metrics["unfilled_plan_rejections_by_symbol"] == {
"A": {
"no_data": 1,
@@ -265,6 +267,7 @@ def test_wanted_but_unfillable_plans_are_counted_by_default():
"invalid_price": 1,
"zero_size": 1,
"execution_blocked": 1,
+ "insufficient_capital": 1,
}
}
assert set(metrics["unfilled_plan_rejections_by_symbol"]["A"]) == set(
@@ -338,3 +341,68 @@ def test_total_and_by_symbol_share_one_counter():
empty = _CountingEngine()._plan_rejection_metrics()
assert empty["unfilled_plan_rejections"] == 0
assert empty["unfilled_plan_rejections_by_symbol"] == {}
+
+
+# ---------------------------------------------------------------------------
+# #1470: the hold path's capital fit reports a starved sleeve once, not per step
+# ---------------------------------------------------------------------------
+
+_DATES = pd.date_range("2026-01-02", periods=2)
+
+
+def _hold_run(engine, prices: dict[str, float], targets: dict[str, list[float]]) -> None:
+ """Two bars in hold mode: bar 1 opens what bar 0 did not hold."""
+ data_map = {
+ symbol: pd.DataFrame({"open": [price, price], "close": [price, price]}, index=_DATES)
+ for symbol, price in prices.items()
+ }
+ close_df = pd.DataFrame({symbol: [price, price] for symbol, price in prices.items()}, index=_DATES)
+ engine._execute_bars(_DATES, data_map, close_df, pd.DataFrame(targets, index=_DATES), list(prices))
+
+
+def _opens(engine) -> list[tuple[str, int, float]]:
+ """Opening fills as ``(symbol, bar, quantity)``; the run closes the book on its last bar."""
+ return [(f.symbol, f.bar_idx, f.signed_quantity) for f in engine.fill_records if f.signed_quantity > 0]
+
+
+def test_a_cash_starved_open_in_hold_mode_is_reported_once():
+ """One open that no scale can fund is one insufficient_capital, never 26 zero_size.
+
+ A holds 9 contracts of 100 and leaves 100 of cash; B's full-scale plan is a
+ real 2-contract order at 150, and no scaled size clears the cash. Every
+ bisection step used to book a zero_size rejection for B.
+ """
+ engine = _FuturesLotEngine(position_adjustment="hold")
+ _hold_run(engine, {"A": 100.0, "B": 150.0}, {"A": [0.9, 0.9], "B": [0.0, 0.305]})
+
+ assert _opens(engine) == [("A", 0, 9.0)]
+ assert engine.rejections == [("B", "insufficient_capital", _DATES[1])]
+
+
+def test_a_trial_plan_inside_the_capital_fit_is_not_a_finding():
+ """A sleeve the search scales down to a fill leaves no rejection at all."""
+ engine = _FuturesLotEngine(position_adjustment="hold")
+ _hold_run(engine, {"A": 100.0, "B": 100.0}, {"A": [0.9, 0.9], "B": [0.0, 0.305]})
+
+ assert _opens(engine) == [("A", 0, 9.0), ("B", 1, 1.0)] # 3 wanted, 1 affordable
+ assert engine.rejections == []
+
+
+def test_lot_truncation_in_hold_mode_is_still_one_zero_size():
+ """A target below one lot at full scale is the lot rule, not the cash."""
+ engine = _FuturesLotEngine(position_adjustment="hold")
+ _hold_run(engine, {"A": 100.0, "B": 150.0}, {"A": [0.9, 0.9], "B": [0.0, 0.0005]})
+
+ assert engine.rejections == [("B", "zero_size", _DATES[1])]
+
+
+def test_insufficient_capital_is_counted_as_unfilled():
+ class _CountingLots(_FuturesLotEngine):
+ _on_plan_rejected = BaseEngine._on_plan_rejected
+
+ engine = _CountingLots(position_adjustment="hold")
+ _hold_run(engine, {"A": 100.0, "B": 150.0}, {"A": [0.9, 0.9], "B": [0.0, 0.305]})
+
+ metrics = engine._plan_rejection_metrics()
+ assert metrics["unfilled_plan_rejections"] == 1
+ assert metrics["unfilled_plan_rejections_by_symbol"] == {"B": {"insufficient_capital": 1}}