dennisthiessen/signal-platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: harden shadow book against book leakage (review of ba2df8b)

Browse Source 
Review of the shadow book found seven ways the two books could leak into
each other; all are fixed here. The most serious silently invalidated the
comparison the shadow book exists to make.

- Shadow holdings no longer suppress the manual candidate list. The
  open-trade exclusion filtered on any book, so shadow taking the
  top-ranked names removed exactly those from the user's list and alerts,
  confining the discretionary book to leftovers. Scoped to the manual
  book. Closed-trade alerts and paper-book equity were leaking the same
  way and are likewise scoped.

- Shadow sizing now matches _simulate_portfolio: min(1% risk, 20% notional
  cap, available cash) from marked equity, plus the sub- dust guard.
  Previously risk-only from realized equity, so a tight stop produced a
  multiples-of-equity leveraged position the strategy would never take.

- Shadow only trades setups from the scan that just ran (<6h old) with one
  setup per ticker. A failed or disabled scan step could otherwise open
  positions from a prior session at stale prices.

- Gate-reset transitions are observed for both books, so a shadow stop-out
  completes fail -> requalify instead of staying locked forever.

- Manual list/close endpoints default to the manual book and reject
  hand-closing shadow trades; the performance endpoint is scoped to the
  caller so 'your picks' is not every user's book.

- run_shadow_book is registered as a paused job so Admin can trigger it.

Also anchors three pre-existing paper-trade tests (and the new alpaca
window test) on the UTC date. They build fixtures from the local date but
the service stamps opened_at in UTC, so they failed only between 00:00 and
02:00 in a UTC+hh timezone -- latent on ba2df8b, exposed by the clock.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
dennisthiessen
2026-07-21 09:11:14 +02:00
co-authored by Claude Fable 5
parent ba2df8b9fd
commit 247a92a89f
11 changed files with 434 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tests/unit/test_alpaca_provider_window.py
+12 -4
View File
@@ -43,11 +43,19 @@ def _utcnow() -> datetime:
return datetime.now(timezone.utc).replace(tzinfo=None)
def _utc_today() -> date:
"""The provider clamps against UTC, so the fixture must use the UTC date.
``date.today()`` is local and runs a day ahead in a UTC+hh timezone just
after midnight, which would assert against a day the clamp cannot reach."""
return datetime.now(timezone.utc).date()
@pytest.mark.asyncio
async def test_todays_in_progress_bar_is_inside_the_window():
"""The whole near-close design depends on today's bar being fetchable."""
provider, client = _provider()
today = date.today()
today = _utc_today()
await provider.fetch_ohlcv("AAPL", today - timedelta(days=5), today)
@@ -60,7 +68,7 @@ async def test_window_stays_out_of_the_delayed_data_period():
"""A window reaching the last ~15 minutes fails the entire request."""
provider, client = _provider()
await provider.fetch_ohlcv("AAPL", date.today() - timedelta(days=5), date.today())
await provider.fetch_ohlcv("AAPL", _utc_today() - timedelta(days=5), _utc_today())
assert client.request.end <= _utcnow() - timedelta(minutes=15)
@@ -69,7 +77,7 @@ async def test_window_stays_out_of_the_delayed_data_period():
async def test_completed_past_day_is_fully_covered():
"""Clamping must not swallow the last day of a historical window."""
provider, client = _provider()
end_date = date.today() - timedelta(days=3)
end_date = _utc_today() - timedelta(days=3)
await provider.fetch_ohlcv("AAPL", end_date - timedelta(days=5), end_date)
@@ -80,7 +88,7 @@ async def test_completed_past_day_is_fully_covered():
async def test_window_collapsing_to_nothing_skips_the_call():
"""A start inside the delayed period yields no request at all, not an error."""
provider, client = _provider()
tomorrow = date.today() + timedelta(days=1)
tomorrow = _utc_today() + timedelta(days=2)
records = await provider.fetch_ohlcv("AAPL", tomorrow, tomorrow)
tests/unit/test_book_separation.py
+181
View File
@@ -0,0 +1,181 @@
"""The two books must not leak into each other.
Regression cover for the review of ba2df8b. Each test here pins a way the
shadow book could quietly corrupt the discretionary record — or be corrupted
by it — which would invalidate the comparison the shadow book exists to make.
"""
from __future__ import annotations
from datetime import datetime, timedelta, timezone
import pytest
from app.exceptions import ValidationError
from app.models.paper_trade import PaperTrade
from app.models.ticker import Ticker
from app.models.user import User
from app.services import paper_trade_service as pts
from app.services.trade_policy import (
MANUAL_BOOK,
SHADOW_BOOK,
get_reentry_gate_locks,
observe_reentry_gate_transitions,
)
@pytest.fixture
async def session():
from tests.conftest import _test_session_factory
async with _test_session_factory() as session:
yield session
async def _seed(session) -> int:
session.add(User(id=1, username="owner", password_hash="x"))
session.add(Ticker(id=1, symbol="AAA", name="AAA"))
await session.commit()
return 1
def _trade(*, book, status="open", close_reason=None, closed_at=None, user_id=1):
now = datetime.now(timezone.utc)
return PaperTrade(
user_id=user_id,
ticker_id=1,
direction="long",
entry_price=100.0,
shares=10.0,
stop_loss=95.0,
target=115.0,
status=status,
opened_at=now - timedelta(days=3),
closed_at=closed_at,
close_price=95.0 if status == "closed" else None,
close_reason=close_reason,
book=book,
)
class TestManualEndpoints:
@pytest.mark.asyncio
async def test_list_excludes_shadow_by_default(self, session):
"""Open Positions must not silently mix the autonomous book in."""
await _seed(session)
session.add_all([_trade(book=MANUAL_BOOK), _trade(book=SHADOW_BOOK)])
await session.commit()
rows = await pts.list_trades(session, user_id=1)
assert len(rows) == 1
@pytest.mark.asyncio
async def test_list_can_span_both_books_deliberately(self, session):
await _seed(session)
session.add_all([_trade(book=MANUAL_BOOK), _trade(book=SHADOW_BOOK)])
await session.commit()
rows = await pts.list_trades(session, user_id=1, book=None)
assert len(rows) == 2
@pytest.mark.asyncio
async def test_shadow_trades_cannot_be_closed_by_hand(self, session):
"""A hand-closed shadow trade is no longer what the strategy would do."""
await _seed(session)
trade = _trade(book=SHADOW_BOOK)
session.add(trade)
await session.commit()
with pytest.raises(ValidationError, match="exit policy"):
await pts.close_trade(session, 1, trade.id, 110.0)
class TestGateResetCycle:
@pytest.mark.asyncio
async def test_shadow_stop_completes_fail_then_requalify(self, session):
"""The full cycle must advance for the shadow book, or a stopped ticker
stays locked out forever."""
await _seed(session)
closed = datetime.now(timezone.utc) - timedelta(days=2)
session.add(
_trade(book=SHADOW_BOOK, status="closed", close_reason="stop", closed_at=closed)
)
await session.commit()
assert 1 in await get_reentry_gate_locks(session, book=SHADOW_BOOK)
# Day 1: ticker no longer qualifies → failure observed.
await observe_reentry_gate_transitions(
session,
evaluated_ticker_ids=[1],
qualified_ticker_ids=[],
observed_at=closed + timedelta(days=1),
book=SHADOW_BOOK,
)
assert 1 in await get_reentry_gate_locks(session, book=SHADOW_BOOK)
# Day 2: qualifies again → lock releases.
await observe_reentry_gate_transitions(
session,
evaluated_ticker_ids=[1],
qualified_ticker_ids=[1],
observed_at=closed + timedelta(days=2),
book=SHADOW_BOOK,
)
assert 1 not in await get_reentry_gate_locks(session, book=SHADOW_BOOK)
@pytest.mark.asyncio
async def test_observing_one_book_does_not_move_the_other(self, session):
await _seed(session)
closed = datetime.now(timezone.utc) - timedelta(days=2)
session.add_all(
[
_trade(book=SHADOW_BOOK, status="closed", close_reason="stop", closed_at=closed),
_trade(book=MANUAL_BOOK, status="closed", close_reason="stop", closed_at=closed),
]
)
await session.commit()
await observe_reentry_gate_transitions(
session,
evaluated_ticker_ids=[1],
qualified_ticker_ids=[],
observed_at=closed + timedelta(days=1),
book=SHADOW_BOOK,
)
await observe_reentry_gate_transitions(
session,
evaluated_ticker_ids=[1],
qualified_ticker_ids=[1],
observed_at=closed + timedelta(days=2),
book=SHADOW_BOOK,
)
# Shadow released; manual never observed, so it stays locked.
assert 1 not in await get_reentry_gate_locks(session, book=SHADOW_BOOK)
assert 1 in await get_reentry_gate_locks(session, book=MANUAL_BOOK)
class TestPerformanceScoping:
@pytest.mark.asyncio
async def test_manual_side_is_scoped_to_the_caller(self, session):
"""'Your picks' must not aggregate another user's discretionary book."""
await _seed(session)
session.add(User(id=2, username="other", password_hash="x"))
await session.commit()
session.add_all(
[
_trade(book=MANUAL_BOOK, user_id=1),
_trade(book=MANUAL_BOOK, user_id=2),
_trade(book=SHADOW_BOOK, user_id=1),
]
)
await session.commit()
mine = await pts.list_trades(session, user_id=1)
theirs = await pts.list_trades(session, user_id=2)
assert len(mine) == 1
assert len(theirs) == 1
tests/unit/test_paper_trade_service.py
+23 -13
View File
@@ -16,6 +16,16 @@ from app.services import paper_trade_service as svc
from tests.conftest import _test_session_factory # type: ignore
def _today() -> date:
"""UTC date — trades are stamped in UTC, so fixtures must use it too.
``date.today()`` is local; in a UTC+hh timezone it runs a day ahead between
midnight and the offset, which silently desynchronises bar and benchmark
fixtures from the UTC ``opened_at`` the service reads.
"""
return datetime.now(timezone.utc).date()
@pytest.fixture
async def session():
async with _test_session_factory() as s:
@@ -30,7 +40,7 @@ async def _seed(session, symbol: str, close: float) -> int:
t = Ticker(symbol=symbol)
session.add(t)
await session.flush()
session.add(OHLCVRecord(ticker_id=t.id, date=date.today(),
session.add(OHLCVRecord(ticker_id=t.id, date=_today(),
open=close, high=close, low=close, close=close, volume=1))
await session.commit()
return t.id
@@ -51,7 +61,7 @@ async def test_create_and_list_open(session):
async def test_create_trade_enforces_post_stop_gate_reset_at_service_boundary(session):
blocked_id = await _seed(session, "LOCKQ", close=100.0)
released_id = await _seed(session, "FREEQ", close=100.0)
today = date.today()
today = _today()
def stopped_trade(ticker_id: int, *, gate_reset_complete: bool) -> PaperTrade:
closed_on = today - timedelta(days=10)
@@ -167,7 +177,7 @@ async def test_resolve_closes_on_target(session):
trade = await svc.create_trade(session, 1, symbol="AAA", direction="long",
entry_price=100.0, shares=10, stop_loss=95.0, target=110.0)
# later bars: a day that trades up through 110
await _add_bars(session, tid, [(103, 101), (111, 108)], start=date.today())
await _add_bars(session, tid, [(103, 101), (111, 108)], start=_today())
closed = await svc.resolve_open_trades(session)
assert closed == 1
await session.refresh(trade)
@@ -180,7 +190,7 @@ async def test_resolve_closes_on_stop(session):
tid = await _seed(session, "AAA", close=100.0)
trade = await svc.create_trade(session, 1, symbol="AAA", direction="long",
entry_price=100.0, shares=10, stop_loss=95.0, target=110.0)
await _add_bars(session, tid, [(101, 94)], start=date.today()) # low pierces stop
await _add_bars(session, tid, [(101, 94)], start=_today()) # low pierces stop
closed = await svc.resolve_open_trades(session)
assert closed == 1
await session.refresh(trade)
@@ -192,7 +202,7 @@ async def test_resolve_leaves_open_when_neither_hit(session):
tid = await _seed(session, "AAA", close=100.0)
await svc.create_trade(session, 1, symbol="AAA", direction="long",
entry_price=100.0, shares=10, stop_loss=95.0, target=110.0)
await _add_bars(session, tid, [(103, 98), (104, 99)], start=date.today()) # range-bound
await _add_bars(session, tid, [(103, 98), (104, 99)], start=_today()) # range-bound
closed = await svc.resolve_open_trades(session)
assert closed == 0
rows = await svc.list_trades(session, 1, status="open")
@@ -217,7 +227,7 @@ async def _add_open_trade(session, ticker_id: int, direction: str, *, entry: flo
async def test_alpha_long_open(session):
tid = await _seed(session, "AAA", close=110.0) # current price 110 → +10% on a 100 entry
today = date.today()
today = _today()
await _seed_benchmark(session, {today - timedelta(days=10): 400.0, today: 420.0}) # SPY +5%
await _add_open_trade(session, tid, "long", entry=100.0, shares=10, days_ago=10)
@@ -229,7 +239,7 @@ async def test_alpha_long_open(session):
async def test_alpha_short_and_missing_benchmark(session):
tid = await _seed(session, "BBB", close=90.0) # price fell to 90 → short +10%
today = date.today()
today = _today()
await _add_open_trade(session, tid, "short", entry=100.0, shares=4, days_ago=10)
# No benchmark data yet → alpha unset, not an error.
@@ -389,7 +399,7 @@ async def test_resolve_time_mode_closes_at_horizon(session):
tid = await _seed(session, "AAA", close=100.0)
trade = await svc.create_trade(session, 1, symbol="AAA", direction="long",
entry_price=100.0, shares=10, stop_loss=95.0, target=200.0)
await _add_bars(session, tid, [(103, 101), (105, 102)], start=date.today())
await _add_bars(session, tid, [(103, 101), (105, 102)], start=_today())
assert await svc.resolve_open_trades(session) == 1
await session.refresh(trade)
assert trade.status == "closed"
@@ -402,7 +412,7 @@ async def test_resolve_time_mode_stop_still_governs(session):
tid = await _seed(session, "AAA", close=100.0)
trade = await svc.create_trade(session, 1, symbol="AAA", direction="long",
entry_price=100.0, shares=10, stop_loss=95.0, target=200.0)
await _add_bars(session, tid, [(101, 94)], start=date.today()) # low pierces the stop
await _add_bars(session, tid, [(101, 94)], start=_today()) # low pierces the stop
assert await svc.resolve_open_trades(session) == 1
await session.refresh(trade)
assert trade.close_reason == "stop"
@@ -413,7 +423,7 @@ async def test_resolve_trailing_closes_with_reason(session):
await svc.set_exit_policy(session, mode="trailing", trailing_pct=12.0)
tid = await _seed(session, "AAA", close=100.0)
await _add_open_trade(session, tid, "long", entry=100.0, shares=10, days_ago=10)
await _add_bars(session, tid, [(120, 110), (130, 100)], start=date.today()) # run up, pull back
await _add_bars(session, tid, [(120, 110), (130, 100)], start=_today()) # run up, pull back
assert await svc.resolve_open_trades(session) == 1
closed = await svc.list_trades(session, 1, status="closed")
assert closed[0]["close_reason"] == "trailing"
@@ -424,7 +434,7 @@ async def test_resolve_atr_trailing_closes_with_reason(session, monkeypatch):
await svc.set_exit_policy(session, mode="atr_trailing", atr_multiplier=3.0)
tid = await _seed(session, "AAA", close=100.0)
await _add_open_trade(session, tid, "long", entry=100.0, shares=10, days_ago=10)
await _add_bars(session, tid, [(121, 114), (107, 101)], start=date.today())
await _add_bars(session, tid, [(121, 114), (107, 101)], start=_today())
assert await svc.resolve_open_trades(session) == 1
closed = await svc.list_trades(session, 1, status="closed")
assert closed[0]["close_reason"] == "trailing"
@@ -443,7 +453,7 @@ async def test_list_open_exposes_trailing_stop(session):
await svc.set_exit_policy(session, mode="trailing", trailing_pct=12.0)
tid = await _seed(session, "AAA", close=120.0)
await _add_open_trade(session, tid, "long", entry=100.0, shares=10, days_ago=10)
await _add_bars(session, tid, [(125, 118)], start=date.today()) # peak 125
await _add_bars(session, tid, [(125, 118)], start=_today()) # peak 125
row = (await svc.list_trades(session, 1, status="open"))[0]
assert row["trailing_stop"] == pytest.approx(110.0) # 125 * (1 - 0.12)
assert row["trailing_distance_pct"] is not None
@@ -454,7 +464,7 @@ async def test_list_open_exposes_atr_trailing_stop(session, monkeypatch):
await svc.set_exit_policy(session, mode="atr_trailing", atr_multiplier=3.0)
tid = await _seed(session, "AAA", close=120.0)
await _add_open_trade(session, tid, "long", entry=100.0, shares=10, days_ago=10)
await _add_bars(session, tid, [(125, 118)], start=date.today())
await _add_bars(session, tid, [(125, 118)], start=_today())
row = (await svc.list_trades(session, 1, status="open"))[0]
assert row["trailing_stop"] == pytest.approx(106.5) # latest close 121.5 - 3 * 5
assert row["trailing_distance_pct"] is not None
tests/unit/test_scheduler.py
+2
View File
@@ -107,6 +107,7 @@ class TestConfigureScheduler:
"sentiment_collector",
"fundamental_collector",
"rr_scanner",
"shadow_book",
"ticker_universe_sync",
"outcome_evaluator",
"alerts",
@@ -143,5 +144,6 @@ class TestConfigureScheduler:
"outcome_evaluator",
"rr_scanner",
"sentiment_collector",
"shadow_book",
"ticker_universe_sync",
])
tests/unit/test_shadow_book_service.py
+58 -1
View File
@@ -78,6 +78,27 @@ class TestSizing:
def test_zero_risk_distance_takes_no_position(self):
assert shadow_book_service.position_shares(100_000, 1.0, 100.0, 100.0) == 0.0
def test_tight_stop_is_capped_at_the_notional_limit(self):
"""Without the cap, 1% risk on a $0.50 stop is a 2x-equity position."""
shares = shadow_book_service.position_shares(100_000, 1.0, 100.0, 99.5)
# Risk sizing alone wants 2,000 shares ($200k); the 20% cap allows 200.
assert shares == pytest.approx(200.0)
assert shares * 100.0 <= 100_000 * shadow_book_service.NOTIONAL_CAP
def test_cannot_spend_cash_it_does_not_have(self):
shares = shadow_book_service.position_shares(
100_000, 1.0, 100.0, 95.0, cash_available=5_000
)
assert shares == pytest.approx(50.0)
def test_no_cash_means_no_position(self):
assert (
shadow_book_service.position_shares(
100_000, 1.0, 100.0, 95.0, cash_available=0
)
== 0.0
)
class TestSelection:
@pytest.mark.asyncio
@@ -151,6 +172,41 @@ class TestSelection:
assert summary["skipped_locked"] == 1
class TestSetupFreshness:
@pytest.mark.asyncio
async def test_ignores_setups_from_a_previous_session(self, session):
"""If the scan step failed or was disabled, the newest stored setups are
yesterday's — trading them would enter stale picks at stale prices."""
ids = await _seed(session, ["AAA"])
stale = datetime.now(timezone.utc) - timedelta(days=1)
session.add(_setup(ids["AAA"], rank=0.9, detected=stale))
await session.commit()
summary = await shadow_book_service.open_shadow_positions(
session, activation_config=_CONFIG
)
assert summary["opened"] == 0
@pytest.mark.asyncio
async def test_one_position_per_ticker_from_duplicate_setups(self, session):
ids = await _seed(session, ["AAA"])
now = datetime.now(timezone.utc)
session.add_all(
[
_setup(ids["AAA"], rank=0.5, detected=now - timedelta(minutes=30)),
_setup(ids["AAA"], rank=0.9, detected=now),
]
)
await session.commit()
summary = await shadow_book_service.open_shadow_positions(
session, activation_config=_CONFIG
)
assert summary["opened"] == 1
class TestBookIsolation:
@pytest.mark.asyncio
async def test_gate_locks_do_not_leak_between_books(self, session):
@@ -184,6 +240,7 @@ class TestBookIsolation:
)
await session.commit()
equity = await shadow_book_service.current_equity(session, 100_000.0)
equity, cash = await shadow_book_service.equity_and_cash(session, 100_000.0, [])
assert equity == 100_000.0
assert cash == 100_000.0