Coverage for src/copytrading_engine/execution/application/engine.py: 93%
621 statements
« prev ^ index » next coverage.py v7.16.2, created at 2026-11-16 16:55 +0000
« prev ^ index » next coverage.py v7.16.2, created at 2026-11-16 16:55 +0000
1"""Copy use cases: coordinate typed broker operations and durable ledger transitions."""
3import datetime as dt
4import time
5from collections.abc import Callable
6from concurrent.futures import ThreadPoolExecutor
7from dataclasses import dataclass
8from decimal import ROUND_DOWN, Decimal
9from typing import Literal
11from copytrading_engine.execution.application.ledger import LATE_SKIPS, TradingLedger
12from copytrading_engine.execution.application.ports import (
13 AccountOpenRefused,
14 Broker,
15 BrokerError,
16 ExecutionObserver,
17 LedgerRepository,
18 NoOpObserver,
19 QuoteBroker,
20)
21from copytrading_engine.execution.domain.events import (
22 BrokerAcknowledged,
23 Exposure,
24 JournalEvent,
25 QuoteUnavailable,
26 ReadBackSummary,
27 SubmissionQuote,
28)
29from copytrading_engine.execution.domain.ledger_state import MessageRecord
30from copytrading_engine.execution.domain.market import Account, BrokerOrder, CalendarDay, Position
31from copytrading_engine.execution.domain.order_lifecycle import OrderStatus, is_cancelable
32from copytrading_engine.execution.domain.orders import (
33 CancelReason,
34 OrderPlan,
35 OrderRecord,
36 OrderRequest,
37 OwnedLot,
38)
39from copytrading_engine.execution.domain.ownership import account_activity_reason, still_open
40from copytrading_engine.execution.domain.positions import (
41 PositionAudit,
42 compare_positions,
43 fee_allowance,
44)
45from copytrading_engine.execution.domain.pricing import (
46 SELL_FLOOR_QUOTE_MAX_AGE_SECONDS,
47 price_tick,
48 quote_problem,
49)
50from copytrading_engine.execution.domain.progress import OrderLinked, Pending, Skipped
51from copytrading_engine.execution.domain.risk import (
52 MINIMUM_CRYPTO_BUY_USD,
53 MINIMUM_ORDER_USD,
54 EntryFacts,
55 ExposureBreach,
56 account_exposure,
57 entry_budget,
58)
59from copytrading_engine.execution.domain.sessions import Session, SessionSchedule, trade_date
60from copytrading_engine.execution.domain.signals import CopyConfig, SignalSourceNotAllowed
61from copytrading_engine.execution.domain.sizing import DestinationSignal
62from copytrading_engine.execution.domain.stops import StopRule, stop_rule_key
63from copytrading_engine.shared.signals import Instruction, StopCall
64from copytrading_engine.shared.symbols import is_crypto
66ZERO = Decimal(0)
67STEP = Decimal("0.000001")
68# Independent broker reads for one decision go out together instead of one after another:
69# each is a network round trip, and waiting for them in turn was most of a decision's time.
70_BROKER_READS = ThreadPoolExecutor(max_workers=8, thread_name_prefix="broker-read")
73@dataclass(frozen=True, slots=True)
74class TradeDecision:
75 plan: OrderPlan | None
76 reason: str
77 breaches: tuple[ExposureBreach, ...] = ()
78 # For a sell skipped as `bought_after_sell`: when the first buy it would have sold was posted.
79 bought_at: dt.datetime | None = None
82@dataclass(frozen=True, slots=True)
83class _ProcessControls:
84 now: Callable[[], dt.datetime]
85 monotonic: Callable[[], float]
86 halted: Callable[[], bool]
87 entry_block_reason: Callable[[], str | None]
88 stopping: Callable[[], bool]
91@dataclass(frozen=True, slots=True)
92class _SubmissionGuard:
93 signal_at: dt.datetime
94 buy: bool
95 started_at: dt.datetime
96 started_monotonic: float
97 max_age_seconds: int
98 controls: _ProcessControls
99 market_session: Callable[[dt.datetime, str], Session]
101 @classmethod
102 def begin(
103 cls,
104 signal_at: dt.datetime,
105 *,
106 buy: bool,
107 max_age_seconds: int,
108 controls: _ProcessControls,
109 market_session: Callable[[dt.datetime, str], Session],
110 ) -> _SubmissionGuard:
111 started_at = controls.now()
112 started_monotonic = controls.monotonic()
113 return cls(
114 signal_at,
115 buy,
116 started_at,
117 started_monotonic,
118 max_age_seconds,
119 controls,
120 market_session,
121 )
123 def check(self, plan: OrderPlan | None = None) -> tuple[str | None, dt.datetime]:
124 current = self.controls.now()
125 age = max(
126 (current - self.signal_at).total_seconds(),
127 (self.started_at - self.signal_at).total_seconds()
128 + self.controls.monotonic()
129 - self.started_monotonic,
130 )
131 # Only a buy can be too old: a late sell is still right, since the guru is out.
132 if self.buy and (age > self.max_age_seconds or age < -5):
133 return "stale", current
134 if self.controls.stopping():
135 return "stopping", current
136 if self.buy and (reason := self.controls.entry_block_reason()) is not None:
137 return reason, current
138 if self.buy and self.controls.halted():
139 return "halted", current
140 if plan is not None and (
141 trade_date(current) != trade_date(self.started_at)
142 or self.market_session(current, plan.symbol) != plan.session
143 ):
144 return "session_changed", current
145 return None, current
148# Buys blocked only while an account recovers after a restart wait for it instead of being
149# skipped: the next cycle tries again, and the signal age still decides when a post is too old.
150RECOVERY_WAITS = frozenset({"recovery_pending", "manual_resume_required"})
151# Why a sell waits and tries again instead of being skipped: a sell is never too old and never
152# lost (ADR-0010), so anything that can clear by itself or by the owner's hand holds it. No
153# fresh bid yet (a thin market's quotes can be minutes apart), the market closed, an open-order
154# page Alpaca couldn't give whole, an order or holdings question on its stock, an order outside
155# CopyTrading on its stock, overnight trading halted, the session changing, or a stop.
156SELL_WAITS = frozenset(
157 {
158 "quote_stale",
159 "quote_unavailable",
160 "outside_session",
161 "incomplete_account_orders",
162 "unresolved_account_order",
163 "unresolved_order_incident",
164 "external_open_order",
165 "position_mismatch",
166 "ownership_incident",
167 "overnight_halted",
168 "session_changed",
169 "stopping",
170 "stop_still_open",
171 }
172)
173# After Alpaca refuses a stop, it is tried again this often, not every cycle.
174STOP_RETRY_SECONDS = 300
175# A copied order cancels the stock's stops and waits for Alpaca to confirm, polling this often.
176STOP_CLEAR_POLLS = 8
177STOP_CLEAR_POLL_SECONDS = 0.5
178# A waiting sell is planned again at most this often: each plan is five Alpaca requests, and the
179# app polls every 2 seconds, which for one sell would be most of Alpaca's 200 requests a minute.
180SELL_RETRY_SECONDS = 30
181# Posts read back after CopyTrading was off are told to the owner once, in one summary, when none
182# has come in for this long.
183READ_BACK_QUIET_SECONDS = 60
184# What a held buy that aged out says instead of a bare "stale".
185_AGED_OUT_WAITING = {
186 "recovery_pending": "stale_during_recovery",
187 "manual_resume_required": "stale_waiting_for_resume",
188}
191class CopyEngine:
192 def __init__(
193 self,
194 store: LedgerRepository,
195 broker: Broker,
196 config: CopyConfig,
197 *,
198 observer: ExecutionObserver | None = None,
199 ) -> None:
200 self.broker, self.config = broker, config
201 self.observer = observer if observer is not None else NoOpObserver()
202 self.ledger = TradingLedger(store, self.observer)
203 self._calendar: dict[str, tuple[CalendarDay, ...]] = {}
204 self._environment: str | None = None
205 # When each waiting sell (post, part) may be planned again.
206 self._sell_retry_at: dict[tuple[str, int], dt.datetime] = {}
207 # Posts read back since the last summary, and when the latest came in.
208 self._read_back: dict[str, None] = {}
209 self._read_back_at: dt.datetime | None = None
210 # When a stop Alpaca refused may be placed again, and which stocks trade in fractions.
211 self._stop_retry_at: dict[str, dt.datetime] = {}
212 self._fractionable: dict[str, bool] = {}
214 def bind(
215 self,
216 now: dt.datetime,
217 account: Account | None = None,
218 environment: Literal["paper", "live"] = "paper",
219 ) -> Account:
220 account = account if account is not None else self.broker.account()
221 if not account.active: 221 ↛ 222line 221 didn't jump to line 222 because the condition on line 221 was never true
222 raise AccountOpenRefused("broker_account_inactive")
223 if self.ledger.account_id is not None and self.ledger.account_id != account.id:
224 # Records are placed by the Alpaca account their keys open before any account opens
225 # (account_records), so this record is never another account's.
226 raise RuntimeError("Broker account identity changed")
227 if not self.ledger.account_id and self.broker.open_orders():
228 # The first connection records what the account already holds; an order placed
229 # outside CopyTrading could fill during that count, so the owner settles it first.
230 raise AccountOpenRefused("outside_open_orders")
231 positions = self.broker.positions()
232 self.ledger.bind(account.id, now, environment, positions)
233 self._environment = environment
234 return account
236 def receive(self, delivery: DestinationSignal, now: dt.datetime) -> None:
237 signal = delivery.signal
238 if self._environment is None: 238 ↛ 239line 238 didn't jump to line 239 because the condition on line 238 was never true
239 raise RuntimeError("Bind the broker account before receiving a destination")
240 if delivery.terms.environment != self._environment: 240 ↛ 241line 240 didn't jump to line 241 because the condition on line 240 was never true
241 raise ValueError("Destination environment does not match account owner")
242 if f"{signal.source}:{signal.channel_id}" not in self.config.sources:
243 raise SignalSourceNotAllowed("Signal source is not configured for this account")
244 key = f"{signal.source}:{signal.channel_id}:{signal.id}"
245 new = key not in self.ledger.state.messages
246 self.ledger.receive(delivery, now, self.config.max_signal_age_seconds)
247 message = self.ledger.message(key)
248 late = message.status in LATE_SKIPS or any(
249 isinstance(part, Skipped) and part.reason in LATE_SKIPS for part in message.parts
250 )
251 if new and late:
252 # Read back after CopyTrading was off: the owner hears of it in one summary.
253 self._read_back[key] = None
254 self._read_back_at = now
256 def pending(self, symbol: str | None = None) -> tuple[OrderRecord, ...]:
257 return self.ledger.pending(symbol)
259 def audit_positions(self, positions: tuple[Position, ...] | None = None) -> PositionAudit:
260 """The ledger's holdings against the broker's, read now unless `positions` were."""
261 return compare_positions(
262 self.ledger.lots(),
263 self.pending(),
264 self.broker.positions() if positions is None else positions,
265 tuple(self.ledger.state.external_positions.values()),
266 unsettled_fees=fee_allowance(self.ledger.orders()),
267 )
269 def reconcile(
270 self, now: dt.datetime, *, settle_before: dt.datetime | None = None
271 ) -> tuple[Position, ...]:
272 """Book what the broker reports for every order still open, then audit holdings, and
273 return the broker positions that audit read, after every fill it booked. A holdings
274 question settles only once its count has held still for a later sync: with
275 `settle_before`, only questions opened before then are settled."""
276 pending = self.pending()
277 pending_ids = {order.client_id for order in pending}
278 for order in pending:
279 update = self.broker.lookup(order.client_id)
280 if update is None:
281 # A lookup can be temporarily absent. Preserve the last broker
282 # evidence for known and quarantined orders.
283 if order.status in {OrderStatus.PREPARED, OrderStatus.UNCERTAIN}:
284 self.ledger.uncertain(order.client_id, now)
285 continue
286 self.ledger.apply_order(order.client_id, update, now)
287 current = self.ledger.order(order.client_id)
288 # Only a buy is cancelled for waiting: a sell keeps working at its floor until it fills,
289 # its shares are gone, or copying stops (ADR-0010). A buy's timeout runs from when
290 # Alpaca put it on the market, since Alpaca can hold an order for seconds first. A buy
291 # Alpaca still hasn't put out a whole timeout after it was sent is cancelled too: the
292 # call would be stale by the time it went out.
293 live_since = current.accepted_at or current.created_at
294 if (
295 current.side == "buy"
296 and current.pending
297 and is_cancelable(current.status)
298 and (now - live_since).total_seconds() >= self.config.order_timeout_seconds
299 ):
300 self.cancel(current, now, "timeout")
302 # Operator-released IDs leave the ordinary pending set, but remain
303 # under broker observation for their full audit history.
304 snapshot = self.ledger.state
305 for client_id in snapshot.release_evidence:
306 if client_id in pending_ids:
307 continue
308 update = self.broker.lookup(client_id)
309 if update is not None:
310 self.ledger.apply_order(client_id, update, now)
311 positions = self.broker.positions()
312 self._count_crypto_fees(positions, now)
313 self.ledger.open_ownership_incidents(
314 self.audit_positions(positions),
315 now,
316 self._outside_orders(),
317 settle_before=settle_before,
318 )
319 return positions
321 def _count_crypto_fees(self, positions: tuple[Position, ...], now: dt.datetime) -> None:
322 """Count Alpaca's fee on each coin's latest buys from the holding just read. Alpaca keeps
323 the fee out of the coin bought and reports it only at the day's end, so the holding is the
324 one place it shows (ADR-0014). The holding counts only when no order of the coin filled
325 while it was read: each open order is looked up again, and one that moved waits for the
326 next sync."""
327 for symbol in sorted(
328 {order.symbol for order in self.ledger.orders() if order.unsettled_fee_qty}
329 ):
330 still = all(
331 (update := self.broker.lookup(order.client_id)) is not None
332 and update.filled_qty == order.filled_qty
333 for order in self.pending(symbol)
334 )
335 if not still:
336 continue
337 held = sum((p.qty for p in positions if p.symbol == symbol), ZERO)
338 self.ledger.count_crypto_fee(symbol, self.ledger.expected_position(symbol) - held, now)
340 def _outside_orders(self) -> frozenset[str]:
341 """Stocks with an open broker order the app didn't place. Read only while a holdings
342 question is open, since only settling one needs it."""
343 if not any(
344 not incident.resolved for incident in self.ledger.state.ownership_incidents.values()
345 ):
346 return frozenset()
347 known = {order.client_id for order in self.pending()}
348 return frozenset(
349 order.symbol
350 for order in self.broker.open_orders()
351 if order.client_order_id not in known
352 )
354 def cancel(self, order: OrderRecord, now: dt.datetime, reason: CancelReason) -> None:
355 if not order.broker_id or not is_cancelable(order.status): 355 ↛ 356line 355 didn't jump to line 356 because the condition on line 355 was never true
356 return
357 try:
358 self.broker.cancel(order.broker_id)
359 self.ledger.cancel_requested(order.client_id, reason, now)
360 except BrokerError as exc:
361 if exc.status not in {404, 422}:
362 raise
363 # A later lookup must confirm cancellation before releasing the reservation.
365 def _market_bid(self, symbol: str, now: dt.datetime) -> tuple[Decimal | None, str]:
366 """The live bid for a sell at the market, or why there is none to sell against."""
367 if not isinstance(self.broker, QuoteBroker):
368 return None, "quote_unavailable"
369 try:
370 quote = self.broker.quote(symbol)
371 except BrokerError:
372 return None, "quote_unavailable"
373 problem = quote_problem(quote, quote.bid, now, SELL_FLOOR_QUOTE_MAX_AGE_SECONDS)
374 if problem is not None:
375 return None, problem
376 return quote.bid, "ready"
378 def _posted_at(self, entry: str) -> dt.datetime:
379 """When the post that made a buy was posted: its message's time, or the order's own for a
380 buy with no post."""
381 order = self.ledger.order(entry)
382 message = self.ledger.state.messages.get(order.message_id)
383 return message.timestamp if message is not None else order.created_at
385 def _posted_before(self, entry: str, message_id: str) -> bool:
386 """The buy came from a post no later than this one, or from earlier in the same post."""
387 order = self.ledger.order(entry)
388 sell = self.ledger.state.messages.get(message_id)
389 if sell is None or order.message_id == message_id: 389 ↛ 390line 389 didn't jump to line 390 because the condition on line 389 was never true
390 return True
391 return self._posted_at(entry) <= sell.timestamp
393 def _sell_replaces(self, order: OrderRecord, sell: Instruction, message_id: str) -> bool:
394 """An open buy this sell would have sold: at the buy price it names (any, when it names
395 none), posted no later than it. A buy at another price, or posted after it, is a separate
396 call and stays open."""
397 if order.side != "buy" or order.message_id == message_id:
398 return False
399 if sell.entry_price is not None and order.entry_price != sell.entry_price:
400 return False
401 posted = self.ledger.state.messages.get(message_id)
402 bought = self.ledger.state.messages.get(order.message_id)
403 return posted is None or bought is None or bought.timestamp <= posted.timestamp
405 def _crosses(self, symbol: str, side: Literal["buy", "sell"], limit_price: Decimal) -> bool:
406 """An open order of the stock on the other side this one would trade with: a sell at or
407 under this buy's limit, or a buy at or over this sell's."""
408 # A stop rests below the market and trades with nothing until it triggers.
409 return any(
410 order.side != side
411 and order.type != "stop"
412 and (
413 order.limit_price is None
414 or (
415 order.limit_price <= limit_price
416 if side == "buy"
417 else order.limit_price >= limit_price
418 )
419 )
420 for order in self.pending(symbol)
421 )
423 def _selling(self, symbol: str) -> Decimal:
424 """The shares of the stock the open sells have yet to sell. A stop is not counted: it
425 gives its shares up to a sell, which cancels it before it goes out (ADR-0015)."""
426 return sum(
427 (
428 order.qty - order.filled_qty
429 for order in self.pending(symbol)
430 if order.side == "sell" and order.type != "stop"
431 ),
432 ZERO,
433 )
435 def _unsold(
436 self, lot_id: str, lot: OwnedLot, from_entries: tuple[str, ...]
437 ) -> tuple[Decimal, Decimal | None]:
438 """What the buys a sell takes from hold less what the open sells of any of them have yet
439 to sell, and the most it can sell without taking shares an open sell of other buys in the
440 lot still needs (None when no open sell shares a buy with it).
442 The lot splits a fill across the buys a sell names in proportion to what each holds, so a
443 sell is safe only while every open sell that shares a buy with it, this one included,
444 fits in that sell's own buys."""
445 chosen = set(from_entries or lot.entries(lot_id))
446 working = [
447 (order.qty - order.filled_qty, set(order.from_entries or lot.entries(lot_id)))
448 for order in self.pending(lot.symbol)
449 if order.side == "sell" and order.type != "stop" and order.lot_id == lot_id
450 ]
451 held = lot.remaining_of(from_entries) if from_entries else lot.remaining_qty
452 sharing = [(left, entries) for left, entries in working if entries & chosen]
453 unsold = held - sum((left for left, _ in sharing), ZERO)
454 if not sharing:
455 return unsold, None
456 room = unsold
457 for _, entries in sharing:
458 others = sum((left for left, other in working if other & entries), ZERO)
459 room = min(room, lot.remaining_of(tuple(entries)) - others)
460 return unsold, room
462 def _activity_reason(
463 self, open_orders: tuple[BrokerOrder, ...], instruction: Instruction
464 ) -> str | None:
465 """Why the account's open orders hold this decision, if they do. A buy spends the account's
466 cash, so every order and every order incident holds it; a sell answers only to its own
467 stock's, which an order elsewhere can't change (ADR-0010)."""
468 if instruction.action == "buy":
469 return account_activity_reason(
470 open_orders,
471 self.pending(),
472 unresolved_order_incidents=self.ledger.state.entry_halted,
473 )
474 return account_activity_reason(
475 open_orders,
476 self.pending(),
477 unresolved_order_incidents=any(
478 incident.unresolved and incident.symbol == instruction.symbol
479 for incident in self.ledger.state.late_order_incidents.values()
480 ),
481 symbol=instruction.symbol,
482 )
484 def market_session(self, now: dt.datetime, symbol: str | None = None) -> Session:
485 """The session an order of `symbol` would trade in now: a coin's is always open, a
486 stock's comes from the broker's calendar and the account's hours."""
487 if symbol is not None and is_crypto(symbol):
488 return Session.AROUND_THE_CLOCK
489 date = trade_date(now).isoformat()
490 if date not in self._calendar:
491 self._calendar = {date: self.broker.calendar(date)}
492 days = self._calendar[date]
493 if not days:
494 return Session.CLOSED
495 if len(days) != 1 or days[0].date.isoformat() != date: 495 ↛ 496line 495 didn't jump to line 496 because the condition on line 495 was never true
496 raise RuntimeError("Broker calendar identity mismatch")
497 day = days[0]
498 schedule = SessionSchedule(
499 regular_open=day.open,
500 regular_close=day.close,
501 extended_open=day.session_open,
502 extended_close=day.session_close or day.close,
503 )
504 return schedule.at(
505 now, extended=self.config.extended_hours, overnight=self.config.overnight
506 )
508 def decide(
509 self,
510 instruction: Instruction,
511 message_id: str,
512 source_key: str,
513 now: dt.datetime,
514 *,
515 halted: bool,
516 manual: bool = False,
517 chosen_lot: str | None = None,
518 chosen_qty: Decimal | None = None,
519 ) -> TradeDecision:
520 """Plan one instruction. An exit with `chosen_lot` sells that lot, up to `chosen_qty`
521 shares, as the owner chose it, even when exits are not copied."""
522 s, c = instruction, self.config
523 crypto = is_crypto(s.symbol)
524 if crypto and self._environment != "paper":
525 # Crypto is copied on paper accounts only: a live account never sends a coin's order,
526 # whoever asks for it (ADR-0014).
527 return TradeDecision(None, "crypto_paper_only")
528 if self.ledger.unresolved_ownership(s.symbol):
529 return TradeDecision(None, "ownership_incident")
530 if s.action == "buy" and (halted or self.ledger.state.buy_halted):
531 return TradeDecision(None, "halted")
532 if s.action != "buy" and not c.copy_exits and chosen_lot is None:
533 return TradeDecision(None, "exits_disabled")
534 # A resting stop holds nothing back: a sell cancels it as it goes out (ADR-0015).
535 active = tuple(order for order in self.pending(s.symbol) if order.type != "stop")
536 # An order the owner places by hand waits for every open order on the stock.
537 if active and manual:
538 return TradeDecision(None, "wait_pending_order")
539 # A buy waits for an earlier open buy of the stock; it never waits for an open sell unless
540 # the two would cross, which is checked once its price is known (ADR-0010).
541 if s.action == "buy" and any(order.side == "buy" for order in active): 541 ↛ 542line 541 didn't jump to line 542 because the condition on line 541 was never true
542 return TradeDecision(None, "wait_pending_order")
543 if s.action != "buy":
544 # A sell cancels an open buy it would have sold (the guru got out before the copy got
545 # in) and waits until that buy has ended, so it also sells what the buy filled.
546 replaced = tuple(order for order in active if self._sell_replaces(order, s, message_id))
547 for order in replaced:
548 if is_cancelable(order.status):
549 self.cancel(order, now, "replaced_by_sell")
550 if replaced:
551 return TradeDecision(None, "wait_pending_order")
552 session = self.market_session(now, s.symbol)
553 if session == Session.CLOSED:
554 return TradeDecision(None, "outside_session")
555 asset_read = _BROKER_READS.submit(self.broker.asset, s.symbol)
556 account_read = _BROKER_READS.submit(self.broker.account)
557 positions_read = _BROKER_READS.submit(self.broker.positions)
558 open_orders_read = _BROKER_READS.submit(self.broker.open_orders)
559 try:
560 asset = asset_read.result()
561 except BrokerError as exc:
562 if exc.status != 404:
563 raise
564 # Alpaca lists no such stock: a typo, a delisted name, or a listing it does not carry.
565 return TradeDecision(None, "unsupported_asset")
566 if asset.symbol != s.symbol: 566 ↛ 567line 566 didn't jump to line 567 because the condition on line 566 was never true
567 raise RuntimeError("Broker asset identity mismatch")
568 if ( 568 ↛ 573line 568 didn't jump to line 573 because the condition on line 568 was never true
569 not asset.tradable
570 or asset.asset_class != ("crypto" if crypto else "us_equity")
571 or asset.status != "active"
572 ):
573 return TradeDecision(None, "unsupported_asset")
574 # A coin trades in its own steps (Alpaca's asset); a stock's are cents and millionths.
575 price_increment = asset.price_increment if crypto else None
576 qty_step = asset.min_trade_increment if crypto and asset.min_trade_increment else STEP
577 if session == Session.OVERNIGHT:
578 if not (asset.overnight_tradable or "overnight_tradable" in asset.attributes):
579 return TradeDecision(None, "overnight_not_supported")
580 if asset.overnight_halted or "overnight_halted" in asset.attributes:
581 return TradeDecision(None, "overnight_halted")
582 source_price = s.price
583 if source_price is None:
584 # A sell at the market (ADR-0007): the live bid stands in for the guru's price, so
585 # the limit under it still bounds how low the copy can fill.
586 source_price, problem = self._market_bid(s.symbol, now)
587 if source_price is None:
588 return TradeDecision(None, problem)
589 tick = price_tick(source_price, price_increment)
590 if s.action == "buy" and source_price != source_price.quantize(tick): 590 ↛ 591line 590 didn't jump to line 591 because the condition on line 590 was never true
591 return TradeDecision(None, "invalid_price_tick")
592 lot_id = None
593 limit_price = None
594 room: Decimal | None = None
595 account = account_read.result()
596 if account.id != self.ledger.account_id: 596 ↛ 597line 596 didn't jump to line 597 because the condition on line 596 was never true
597 raise RuntimeError("Broker account identity changed")
598 positions = positions_read.result()
599 activity_reason = self._activity_reason(
600 still_open(open_orders_read.result(), self.ledger.orders()), s
601 )
602 if activity_reason is not None:
603 return TradeDecision(None, activity_reason)
604 joins_lot = None
605 from_entries: tuple[str, ...] = ()
606 requested_usd = None
607 budget_usd = None
608 limited_by = None
609 if s.action == "buy":
610 # Only a buy is checked against the whole account: a sell needs only its own stock's
611 # shares and price, and no cap or valuation elsewhere in the account ever holds it.
612 try:
613 exposure = account_exposure(
614 positions,
615 self.ledger.lots(),
616 self.pending(),
617 account_currency=account.currency,
618 )
619 except ValueError:
620 return TradeDecision(None, "account_risk_unavailable")
621 limit_price = c.pricing.buy_ceiling(source_price, price_increment)
622 if self._crosses(s.symbol, "buy", limit_price):
623 # Alpaca refuses a buy at or above an open sell of the stock as a possible wash
624 # trade: it waits for the sell, and the buy's age limit still ends the wait.
625 return TradeDecision(None, "wait_pending_order")
626 # Every buy of a stock joins the guru's open lot of it (ADR-0010).
627 open_lots = self.ledger.position_lots(source_key, s.symbol)
628 joins_lot = open_lots[0][0] if open_lots else None
629 anchor = None
630 if not manual:
631 anchor = self.ledger.anchor_cash(
632 message_id, account.id, account.cash, account.buying_power, now
633 )
634 # Filled cost remains spent. Pending/unknown submission reserves its
635 # full limit notional; terminal unfilled shares release their reserve.
636 committed_in_message = sum(
637 (
638 (order.qty if order.pending else order.filled_qty) * order.limit_price
639 for order in self.ledger.orders()
640 if order.message_id == message_id
641 and order.side == "buy"
642 and order.limit_price is not None
643 ),
644 ZERO,
645 )
646 facts = EntryFacts(
647 symbol_exposure=exposure.symbol(s.symbol),
648 total_exposure=exposure.total,
649 cash=max(
650 ZERO,
651 min(
652 account.cash,
653 (anchor.cash if anchor is not None else account.cash)
654 - committed_in_message,
655 ),
656 ),
657 buying_power=max(
658 ZERO,
659 min(
660 account.buying_power,
661 (anchor.buying_power if anchor is not None else account.buying_power)
662 - committed_in_message,
663 ),
664 ),
665 equity=account.equity,
666 last_equity=account.last_equity,
667 entries_today=sum(
668 o.side == "buy"
669 and o.day == trade_date(now)
670 and o.status != "aborted_before_submit"
671 for o in self.ledger.orders()
672 ),
673 account_active=account.active,
674 )
675 connection = self.ledger.message(message_id).destination.connection
676 minimum_usd = MINIMUM_CRYPTO_BUY_USD if crypto else MINIMUM_ORDER_USD
677 decision = entry_budget(
678 c, facts, connection, s.fraction, s.usd_amount, minimum_usd=minimum_usd
679 )
680 if decision.budget is None:
681 return TradeDecision(None, decision.reason, decision.breaches)
682 requested_usd = decision.requested
683 budget_usd = decision.budget
684 limited_by = decision.limited_by
685 qty = (decision.budget / limit_price).quantize(qty_step, rounding=ROUND_DOWN)
686 if crypto and (
687 qty * limit_price < minimum_usd
688 or (asset.min_order_size is not None and qty < asset.min_order_size)
689 ):
690 # Rounded down to the coin's step, the buy no longer costs Alpaca's $10 minimum.
691 return TradeDecision(None, "below_minimum_budget")
692 entry_price = source_price
693 else:
694 if chosen_lot is not None:
695 lot = self.ledger.state.lots.get(chosen_lot)
696 if lot is None or lot.symbol != s.symbol or lot.remaining_qty <= 0: 696 ↛ 697line 696 didn't jump to line 697 because the condition on line 696 was never true
697 return TradeDecision(None, "lot_unavailable")
698 lot_id = chosen_lot
699 else:
700 lots = self.ledger.position_lots(source_key, s.symbol)
701 if not lots:
702 return TradeDecision(None, "lot_unavailable")
703 if len(lots) != 1: 703 ↛ 704line 703 didn't jump to line 704 because the condition on line 703 was never true
704 return TradeDecision(None, "missing_or_ambiguous_lot")
705 lot_id, lot = lots[0]
706 entry_price = lot.entry_price
707 # The buys an "of the original" share counts, sold-out ones included.
708 basis = lot.entries(lot_id)
709 if chosen_lot is None:
710 # A sell that names a buy price takes from the buys at exactly that price; one
711 # that names none takes from every buy (ADR-0010).
712 named = s.entry_price is not None
713 if named:
714 basis = tuple(e for e in basis if lot.entry_prices[e] == s.entry_price)
715 buys = tuple(e for e in basis if lot.entry_remaining.get(e, ZERO) > 0)
716 if named and not buys:
717 return TradeDecision(None, "named_buy_not_held")
718 if named:
719 # The order sells those buys, so it carries their price, as the post named it.
720 entry_price = s.entry_price
721 # A sell read late can be processed after a buy the guru posted after it: it only
722 # takes from, and counts, buys posted before it, never a later one (ADR-0010).
723 basis = tuple(e for e in basis if self._posted_before(e, message_id))
724 earlier = tuple(e for e in buys if e in basis)
725 if not earlier:
726 later = min(self._posted_at(entry) for entry in buys)
727 return TradeDecision(None, "bought_after_sell", bought_at=later)
728 if named or len(earlier) != len(buys):
729 from_entries = earlier
730 # A sell plans against the shares no open sell has already taken: "half of the rest"
731 # is half of what is left once the sells still working have sold (ADR-0010).
732 held, room = self._unsold(lot_id, lot, from_entries)
733 if held <= 0:
734 return TradeDecision(None, "already_selling")
735 qty = held if chosen_qty is None else min(held, chosen_qty)
736 if s.action == "reduce":
737 assert s.fraction is not None
738 # "Sell half" is half of what is left, unless the post or playbook says the
739 # original buy.
740 if s.exit_basis == "original_position":
741 bought = sum((self.ledger.order(entry).received_qty for entry in basis), ZERO)
742 qty = min(qty, bought * s.fraction)
743 else:
744 qty = min(qty, held * s.fraction)
745 # Rounding down must not strand a step behind: "出一半" then "出剩下一半" of a buy of
746 # 0.071093 shares sold 0.035546 twice and left 0.000001 for good. A sell whose exact
747 # share leaves less than one step sells all that is held.
748 exact, qty = qty, qty.quantize(qty_step, rounding=ROUND_DOWN)
749 if held - exact < qty_step:
750 qty = held
751 if crypto and asset.min_order_size is not None:
752 # Alpaca takes no coin order under the coin's smallest size. A sell that would leave
753 # less than that behind sells it too, or it could never be sold; what is already
754 # under it cannot be sold at all.
755 if held - qty < asset.min_order_size:
756 qty = held
757 if qty < asset.min_order_size:
758 return TradeDecision(None, "below_minimum_order_size")
759 # An exit is a limit order too: its floor is the guru's sell price less the allowance,
760 # so it sells whenever the market is at or above that floor (ADR-0010).
761 limit_price = c.pricing.sell_floor(source_price, price_increment)
762 if self._crosses(s.symbol, "sell", limit_price):
763 # A sell at or under an open buy of the stock would trade with it: it waits.
764 return TradeDecision(None, "wait_pending_order")
765 if not asset.fractionable:
766 qty = qty.quantize(Decimal(1), rounding=ROUND_DOWN)
767 if qty <= 0:
768 return TradeDecision(None, "below_minimum_quantity")
769 if room is not None and qty > room:
770 # An open sell of other buys in the lot still needs these shares: the lot splits a fill
771 # across the buys a sell names, so this one waits for it rather than take them.
772 return TradeDecision(None, "wait_pending_order")
773 owned = self.ledger.owned(s.symbol)
774 # The last-moment re-check reads both again, together, right before the order.
775 final_positions_read = _BROKER_READS.submit(self.broker.positions)
776 final_open_read = _BROKER_READS.submit(self.broker.open_orders)
777 positions = final_positions_read.result()
778 actual = sum((p.qty for p in positions if p.symbol == s.symbol), ZERO)
779 if actual != self.ledger.expected_position(s.symbol):
780 [count] = (p for p in self.audit_positions(positions).positions if p.symbol == s.symbol)
781 if count.mismatched:
782 return TradeDecision(None, "position_mismatch")
783 # An open order of the stock filled since it was last booked: the next sync books it.
784 return TradeDecision(None, "wait_pending_order")
785 final_open = still_open(final_open_read.result(), self.ledger.orders())
786 activity_reason = self._activity_reason(final_open, s)
787 if activity_reason is not None: 787 ↛ 788line 787 didn't jump to line 788 because the condition on line 787 was never true
788 return TradeDecision(None, activity_reason)
789 known = {order.client_id for order in self.pending(s.symbol)}
790 if any(o.symbol == s.symbol and o.client_order_id not in known for o in final_open): 790 ↛ 791line 790 didn't jump to line 791 because the condition on line 790 was never true
791 return TradeDecision(None, "external_open_order")
792 if s.action != "buy" and qty > owned - self._selling(s.symbol): 792 ↛ 793line 792 didn't jump to line 793 because the condition on line 792 was never true
793 return TradeDecision(None, "insufficient_owned_shares")
794 if c.approve_orders and not manual:
795 # Every check passed, so this is an order the account would have sent: hold it for the
796 # owner, who approves it by hand (a manual copy plans afresh and is not held again).
797 return TradeDecision(None, "approval_required")
798 return TradeDecision(
799 OrderPlan(
800 symbol=s.symbol,
801 side="buy" if s.action == "buy" else "sell",
802 position_intent="buy_to_open" if s.action == "buy" else "sell_to_close",
803 qty=qty,
804 type="limit",
805 limit_price=limit_price,
806 source_price=source_price,
807 entry_tolerance_pct=c.pricing.max_above_signal_pct
808 if s.action == "buy"
809 else c.pricing.max_below_signal_pct,
810 lot_id=lot_id,
811 entry_price=entry_price,
812 session=session,
813 joins_lot=joins_lot,
814 from_entries=from_entries,
815 requested_usd=requested_usd,
816 budget_usd=budget_usd,
817 limited_by=limited_by,
818 ),
819 "ready",
820 )
822 def process(
823 self,
824 now: dt.datetime,
825 *,
826 halted: bool = False,
827 now_clock: Callable[[], dt.datetime] | None = None,
828 monotonic_clock: Callable[[], float] = time.monotonic,
829 halted_now: Callable[[], bool] | None = None,
830 entry_block_reason: Callable[[], str | None] | None = None,
831 stopping: Callable[[], bool] | None = None,
832 ) -> None:
833 if now_clock is None:
834 cycle_started = monotonic_clock()
836 def default_now_clock() -> dt.datetime:
837 return now + dt.timedelta(seconds=max(0, monotonic_clock() - cycle_started))
839 now_clock = default_now_clock
840 operator_halted = halted_now or (lambda: halted)
841 controls = _ProcessControls(
842 now=now_clock,
843 monotonic=monotonic_clock,
844 halted=lambda: operator_halted() or self.ledger.state.buy_halted,
845 entry_block_reason=entry_block_reason or (lambda: None),
846 stopping=stopping or (lambda: False),
847 )
848 for message in self.ledger.queued():
849 for index, instruction in enumerate(message.instructions):
850 if not isinstance(self.ledger.message(message.key).parts[index], Pending):
851 continue
852 self._process_instruction(message, index, instruction, controls)
853 for index, stop in enumerate(message.stops):
854 if isinstance(self.ledger.message(message.key).stop_parts[index], Pending):
855 self._process_stop(message, index, stop, controls)
856 settled = self.ledger.message(message.key)
857 if all(not isinstance(part, Pending) for part in (*settled.parts, *settled.stop_parts)):
858 self.ledger.complete(message.key, controls.now())
859 self._sync_stops(controls)
860 self._summarize_read_back(controls.now())
862 def _lot_of(self, entry: str) -> str | None:
863 """The lot a buy's shares belong to."""
864 return next(
865 (key for key, lot in self.ledger.state.lots.items() if entry in lot.entries(key)), None
866 )
868 def _stop_target(
869 self, message: MessageRecord, stop: StopCall
870 ) -> tuple[str, tuple[str, ...]] | str | None:
871 """The lot and buys a guru's stop protects: the buy this post made, the buys at the price
872 it names, or, naming none, every buy of the stock for the guru, each posted no later than
873 the stop. A reason (str) when there is nothing to protect, None while a buy has to fill."""
874 if stop.buy_part is not None:
875 progress = message.parts[stop.buy_part]
876 if isinstance(progress, Pending):
877 return None
878 if not isinstance(progress, OrderLinked): 878 ↛ 879line 878 didn't jump to line 879 because the condition on line 878 was never true
879 return "stop_buy_not_made"
880 buy = self.ledger.order(progress.client_id)
881 if buy.filled_qty <= 0:
882 return None if buy.pending else "stop_buy_not_filled"
883 lot_id = self._lot_of(buy.client_id)
884 return None if lot_id is None else (lot_id, (buy.client_id,))
885 lots = self.ledger.position_lots(message.source_key, stop.symbol)
886 entries: tuple[str, ...] = ()
887 lot_id = None
888 for key, lot in lots:
889 held = tuple(
890 entry
891 for entry in lot.entries(key)
892 if lot.entry_remaining.get(entry, ZERO) > 0
893 and (stop.entry_price is None or lot.entry_prices[entry] == stop.entry_price)
894 and self._posted_before(entry, message.key)
895 )
896 if held: 896 ↛ 888line 896 didn't jump to line 888 because the condition on line 896 was always true
897 lot_id, entries = key, held
898 if lot_id is not None:
899 return lot_id, entries
900 filling = any(
901 order.side == "buy"
902 and order.symbol == stop.symbol
903 and order.source_key == message.source_key
904 and (stop.entry_price is None or order.entry_price == stop.entry_price)
905 and self._posted_before(order.client_id, message.key)
906 for order in self.pending()
907 )
908 return None if filling else "stop_buy_not_held"
910 def _process_stop(
911 self, message: MessageRecord, index: int, stop: StopCall, controls: _ProcessControls
912 ) -> None:
913 """Follow a stop the guru posted (ADR-0015). With the setting off it is skipped, never
914 held for a Copy that would sell at once. On, it is recorded against the buys it protects
915 and placed as a stop order, in the regular session only, for the shares those buys hold."""
916 key, now = message.key, controls.now()
917 retry = (key, message.stop_order_index(index))
918 rule_key = stop_rule_key(key, index)
919 if rule_key in self.ledger.state.stops or now < self._sell_retry_at.get(
920 retry, dt.datetime.min.replace(tzinfo=dt.UTC)
921 ):
922 return # followed already, placed by the sync below; or asked a moment ago
923 if not self.config.follow_stops:
924 self.ledger.skip_stop(key, index, "follow_stops_off", now)
925 return
926 if is_crypto(stop.symbol):
927 self.ledger.skip_stop(key, index, "stop_not_for_coins", now)
928 return
929 waiting = (
930 controls.stopping()
931 or bool(self.ledger.unresolved_ownership(stop.symbol))
932 or self.market_session(now, stop.symbol) != Session.REGULAR
933 )
934 target = None if waiting else self._stop_target(message, stop)
935 if isinstance(target, str):
936 self.ledger.skip_stop(key, index, target, now)
937 return
938 if target is None:
939 self._sell_retry_at[retry] = now + dt.timedelta(seconds=SELL_RETRY_SECONDS)
940 return
941 lot_id, entries = target
942 if any(
943 rule.lot_id == lot_id
944 and set(entries) <= set(rule.entries)
945 and rule.stop_price == stop.stop_price
946 for rule in self.ledger.state.stops.values()
947 ):
948 self.ledger.skip_stop(key, index, "duplicate", now)
949 return
950 self._sell_retry_at.pop(retry, None)
951 self.ledger.set_stop(
952 StopRule(
953 key=rule_key,
954 symbol=stop.symbol,
955 lot_id=lot_id,
956 entries=entries,
957 stop_price=stop.stop_price,
958 message_id=key,
959 order_index=message.stop_order_index(index),
960 set_at=now,
961 ),
962 now,
963 )
965 def _order_in_flight(self, symbol: str) -> bool:
966 """A copied order of the stock is working or about to go out: a sell needs the shares a
967 stop would hold, and Alpaca refuses a stop beside a buy as a possible wash trade."""
968 return any(order.type != "stop" for order in self.pending(symbol)) or any(
969 message.status == "queued"
970 and any(
971 isinstance(part, Pending) and instruction.symbol == symbol
972 for instruction, part in zip(message.instructions, message.parts, strict=True)
973 )
974 for message in self.ledger.state.messages.values()
975 )
977 def _stop_qty(self, symbol: str, held: Decimal) -> Decimal:
978 """What a stop order covers of `held`: whole shares for a stock that trades only in them."""
979 if symbol not in self._fractionable:
980 self._fractionable[symbol] = self.broker.asset(symbol).fractionable
981 return (
982 held if self._fractionable[symbol] else held.quantize(Decimal(1), rounding=ROUND_DOWN)
983 )
985 def _sync_stops(self, controls: _ProcessControls) -> None:
986 """Keep each stop's order matched to what its buys hold: placed in the regular session,
987 placed again each session after Alpaca expires the day order, resized when a sell or a
988 fill changes the shares, and ended with them. Alpaca triggers a stop in the regular
989 session only, so there is no protection outside it (ADR-0015)."""
990 if controls.stopping():
991 return
992 now = controls.now()
993 state = self.ledger.state
994 live: dict[str, list[OrderRecord]] = {}
995 for order in self.pending():
996 if order.stop_rule is not None:
997 live.setdefault(order.stop_rule, []).append(order)
998 for rule_key, orders in live.items():
999 if rule_key not in state.stops: # a newer stop took every buy it protected
1000 for order in orders:
1001 self.cancel(order, now, "stop_resized")
1002 for rule in tuple(state.stops.values()):
1003 lot = state.lots.get(rule.lot_id)
1004 held = lot.remaining_of(rule.entries) if lot is not None else ZERO
1005 orders = live.get(rule.key, [])
1006 if held <= 0:
1007 for order in orders: 1007 ↛ 1008line 1007 didn't jump to line 1008 because the loop on line 1007 never started
1008 self.cancel(order, now, "stop_resized")
1009 self.ledger.end_stop(rule.key, "nothing_left", now)
1010 elif orders:
1011 working = sum((order.qty - order.filled_qty for order in orders), ZERO)
1012 if len(orders) != 1 or working != self._stop_qty(rule.symbol, held): 1012 ↛ 1013line 1012 didn't jump to line 1013 because the condition on line 1012 was never true
1013 for order in orders:
1014 self.cancel(order, now, "stop_resized")
1015 elif orders[0].stop_price != rule.stop_price: 1015 ↛ 1016line 1015 didn't jump to line 1016 because the condition on line 1015 was never true
1016 self.cancel(orders[0], now, "stop_resized")
1017 else:
1018 self._place_stop(rule, held, controls)
1020 def _place_stop(self, rule: StopRule, held: Decimal, controls: _ProcessControls) -> None:
1021 now = controls.now()
1022 if (
1023 now < self._stop_retry_at.get(rule.key, dt.datetime.min.replace(tzinfo=dt.UTC))
1024 or self.market_session(now, rule.symbol) != Session.REGULAR
1025 or self._order_in_flight(rule.symbol)
1026 # An older stop order still holds some of these shares: wait for its cancel to confirm.
1027 or any(
1028 order.type == "stop"
1029 and order.stop_rule != rule.key
1030 and set(order.from_entries) & set(rule.entries)
1031 for order in self.pending(rule.symbol)
1032 )
1033 ):
1034 return
1035 qty = self._stop_qty(rule.symbol, held)
1036 lot = self.ledger.state.lots[rule.lot_id]
1037 if qty <= 0: 1037 ↛ 1038line 1037 didn't jump to line 1038 because the condition on line 1037 was never true
1038 return
1039 plan = OrderPlan(
1040 symbol=rule.symbol,
1041 side="sell",
1042 position_intent="sell_to_close",
1043 qty=qty,
1044 type="stop",
1045 stop_price=rule.stop_price,
1046 source_price=rule.stop_price,
1047 entry_tolerance_pct=ZERO,
1048 lot_id=rule.lot_id,
1049 entry_price=lot.entry_price,
1050 session=Session.REGULAR,
1051 from_entries=rule.entries,
1052 )
1053 attempt = 1 + sum(order.stop_rule == rule.key for order in self.ledger.orders())
1054 order = self.ledger.prepare_stop(plan, rule, attempt, now)
1055 message = self.ledger.message(rule.message_id)
1056 guard = _SubmissionGuard.begin(
1057 message.timestamp,
1058 buy=False,
1059 max_age_seconds=self.config.max_signal_age_seconds,
1060 controls=controls,
1061 market_session=self.market_session,
1062 )
1063 self._submit_prepared_order(order.message_id, order, guard)
1064 # Alpaca refuses a sell stop at or above the price (it would trigger at once): ask again
1065 # later, not every cycle.
1066 if self.ledger.order(order.client_id).status is OrderStatus.REJECTED:
1067 self._stop_retry_at[rule.key] = now + dt.timedelta(seconds=STOP_RETRY_SECONDS)
1069 def _still_held(self, order: OrderRecord) -> bool:
1070 """The shares a sell takes are still held: a stop cancelled for it may have filled first."""
1071 lot = self.ledger.state.lots.get(order.lot_id or "")
1072 if lot is None: 1072 ↛ 1073line 1072 didn't jump to line 1073 because the condition on line 1072 was never true
1073 return False
1074 held = lot.remaining_of(order.from_entries) if order.from_entries else lot.remaining_qty
1075 return order.qty <= held
1077 def _clear_stops(self, symbol: str, now: dt.datetime) -> bool:
1078 """Cancel the stock's stop orders, which a copied order cannot go out beside, and wait for
1079 Alpaca to confirm. The sync places each again for what is left once the order is done."""
1080 stops = [order for order in self.pending(symbol) if order.type == "stop"]
1081 for order in stops:
1082 self.cancel(order, now, "made_room_for_order")
1083 for attempt in range(STOP_CLEAR_POLLS): 1083 ↛ 1091line 1083 didn't jump to line 1091 because the loop on line 1083 didn't complete
1084 for order in stops:
1085 if (update := self.broker.lookup(order.client_id)) is not None: 1085 ↛ 1084line 1085 didn't jump to line 1084 because the condition on line 1085 was always true
1086 self.ledger.apply_order(order.client_id, update, now)
1087 if not any(self.ledger.order(order.client_id).pending for order in stops): 1087 ↛ 1089line 1087 didn't jump to line 1089 because the condition on line 1087 was always true
1088 return True
1089 if attempt + 1 < STOP_CLEAR_POLLS:
1090 time.sleep(STOP_CLEAR_POLL_SECONDS)
1091 return False
1093 def _summarize_read_back(self, now: dt.datetime) -> None:
1094 """Once posts stop coming back, tell the owner what came of them in one message."""
1095 if self._read_back_at is None or (
1096 (now - self._read_back_at).total_seconds() < READ_BACK_QUIET_SECONDS
1097 ):
1098 return
1099 messages = [self.ledger.message(key) for key in self._read_back]
1100 sells = sum(
1101 isinstance(part, OrderLinked) and instruction.action != "buy"
1102 for message in messages
1103 for part, instruction in zip(message.parts, message.instructions, strict=True)
1104 )
1105 too_old = sum(
1106 instruction.action == "buy"
1107 and (
1108 message.status in LATE_SKIPS
1109 or (isinstance(part, Skipped) and part.reason in LATE_SKIPS)
1110 )
1111 for message in messages
1112 for part, instruction in zip(message.parts, message.instructions, strict=True)
1113 )
1114 self.ledger.record(
1115 JournalEvent(
1116 at=now,
1117 payload=ReadBackSummary(
1118 posts=len(messages), sells_copied=sells, buys_too_old=too_old
1119 ),
1120 )
1121 )
1122 self._read_back, self._read_back_at = {}, None
1124 def _process_instruction(
1125 self,
1126 message: MessageRecord,
1127 index: int,
1128 instruction: Instruction,
1129 controls: _ProcessControls,
1130 ) -> None:
1131 retry = (message.key, index)
1132 if instruction.action != "buy" and controls.now() < self._sell_retry_at.get(
1133 retry, dt.datetime.min.replace(tzinfo=dt.UTC)
1134 ):
1135 return
1136 guard = _SubmissionGuard.begin(
1137 message.timestamp,
1138 buy=instruction.action == "buy",
1139 max_age_seconds=self.config.max_signal_age_seconds,
1140 controls=controls,
1141 market_session=self.market_session,
1142 )
1143 blocked, current = guard.check()
1144 if self._held(instruction, blocked):
1145 return
1146 if blocked is not None:
1147 self.ledger.skip(
1148 message.key, index, self._skip_reason(instruction, blocked, controls), current
1149 )
1150 return
1151 with self.observer.span("risk_checks", message.key):
1152 decision = self.decide(
1153 instruction, message.key, message.source_key, current, halted=controls.halted()
1154 )
1155 if decision.reason == "wait_pending_order":
1156 return
1157 if decision.plan is None and instruction.action != "buy" and decision.reason in SELL_WAITS:
1158 self._sell_retry_at[retry] = current + dt.timedelta(seconds=SELL_RETRY_SECONDS)
1159 if decision.reason in {"quote_stale", "quote_unavailable"}:
1160 self.ledger.sell_waiting(message.key, index, decision.reason, current)
1161 return
1162 self._sell_retry_at.pop(retry, None)
1163 if decision.plan is None:
1164 details = tuple(
1165 Exposure(
1166 scope=breach.scope,
1167 current=breach.current,
1168 proposed=breach.proposed,
1169 limit=breach.limit,
1170 )
1171 for breach in decision.breaches
1172 )
1173 self.ledger.skip(
1174 message.key,
1175 index,
1176 decision.reason,
1177 controls.now(),
1178 exposure=details or None,
1179 bought_at=decision.bought_at,
1180 )
1181 return
1182 blocked, current = guard.check(decision.plan)
1183 if self._held(instruction, blocked): 1183 ↛ 1184line 1183 didn't jump to line 1184 because the condition on line 1183 was never true
1184 return
1185 if blocked is not None:
1186 self.ledger.skip(
1187 message.key, index, self._skip_reason(instruction, blocked, controls), current
1188 )
1189 return
1190 order = self.ledger.prepare(decision.plan, message.key, index, current)
1191 self._submit_prepared_order(message.key, order, guard)
1193 @staticmethod
1194 def _held(instruction: Instruction, blocked: str | None) -> bool:
1195 """A buy that only waits for the account's restart recovery stays pending, and so does a
1196 sell held by anything that can clear (`SELL_WAITS`): a sell is never lost."""
1197 if instruction.action == "buy":
1198 return blocked in RECOVERY_WAITS
1199 return blocked in SELL_WAITS
1201 @staticmethod
1202 def _skip_reason(instruction: Instruction, blocked: str, controls: _ProcessControls) -> str:
1203 """A buy that aged out while its account recovered says why it waited, not just that it
1204 is old."""
1205 if instruction.action == "buy" and blocked == "stale":
1206 waiting = controls.entry_block_reason()
1207 if waiting in _AGED_OUT_WAITING:
1208 return _AGED_OUT_WAITING[waiting]
1209 return blocked
1211 def _submit_prepared_order(
1212 self,
1213 message_key: str,
1214 order: OrderRecord,
1215 guard: _SubmissionGuard,
1216 ) -> None:
1217 request = OrderRequest.for_plan(
1218 order,
1219 order.client_id,
1220 # Marked for extended hours only outside the regular session: Alpaca routes such an
1221 # order differently even at 9:30, and a regular-session order needs no flag. A coin's
1222 # order carries no hours at all.
1223 extended_hours=order.type == "limit" and order.session != Session.REGULAR,
1224 )
1225 try:
1226 with self.observer.span("order_submission", message_key):
1227 blocked, current = guard.check(order)
1228 if blocked is None and order.type != "stop":
1229 # Alpaca refuses a sell of the shares a stop holds, and a buy beside a resting
1230 # stop as a possible wash trade. The stop is cancelled first, and the sync
1231 # places it again for what is left once the order is done.
1232 blocked = (
1233 None
1234 if self._clear_stops(order.symbol, current)
1235 and (order.side == "buy" or self._still_held(order))
1236 else "stop_still_open"
1237 )
1238 if blocked is not None:
1239 self.ledger.abort_before_submit(order.client_id, blocked, current)
1240 return
1241 self.ledger.submitting(order.client_id, current)
1242 blocked, current = guard.check(order)
1243 if blocked is not None:
1244 self.ledger.abort_before_submit(order.client_id, blocked, current)
1245 return
1246 self.ledger.apply_order(
1247 order.client_id, self.broker.submit(request), guard.controls.now()
1248 )
1249 self.ledger.record(
1250 JournalEvent(
1251 at=guard.controls.now(),
1252 payload=BrokerAcknowledged(
1253 client_id=order.client_id,
1254 message_id=order.message_id,
1255 ),
1256 )
1257 )
1258 if isinstance(self.broker, QuoteBroker):
1259 try:
1260 with self.observer.span("quote_snapshot", message_key):
1261 quote = self.broker.quote(order.symbol)
1262 self.ledger.record(
1263 JournalEvent(
1264 at=guard.controls.now(),
1265 payload=SubmissionQuote(
1266 client_id=order.client_id,
1267 message_id=order.message_id,
1268 quote=quote,
1269 ),
1270 )
1271 )
1272 except BrokerError:
1273 self.ledger.record(
1274 JournalEvent(
1275 at=guard.controls.now(),
1276 payload=QuoteUnavailable(
1277 client_id=order.client_id,
1278 message_id=order.message_id,
1279 ),
1280 )
1281 )
1282 except BrokerError as exc:
1283 self.ledger.submission_failed(
1284 order.client_id, exc.status, guard.controls.now(), exc.reason
1285 )
1287 def submit_manual_prepared(
1288 self,
1289 order: OrderRecord,
1290 now: dt.datetime,
1291 *,
1292 halted: Callable[[], bool],
1293 entry_block_reason: Callable[[], str | None],
1294 stopping: Callable[[], bool],
1295 ) -> OrderRecord:
1296 """Submit an already durable operator-confirmed intent through the normal path."""
1297 started = time.monotonic()
1299 def current_time() -> dt.datetime:
1300 return now + dt.timedelta(seconds=max(0, time.monotonic() - started))
1302 controls = _ProcessControls(
1303 now=current_time,
1304 monotonic=time.monotonic,
1305 halted=halted,
1306 entry_block_reason=entry_block_reason,
1307 stopping=stopping,
1308 )
1309 guard = _SubmissionGuard.begin(
1310 now,
1311 buy=order.side == "buy",
1312 max_age_seconds=self.config.max_signal_age_seconds,
1313 controls=controls,
1314 market_session=self.market_session,
1315 )
1316 self._submit_prepared_order(order.message_id, order, guard)
1317 return self.ledger.order(order.client_id)