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

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>

tests/unit/test_alpaca_provider_window.py

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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