Coverage for src/copytrading_engine/execution/domain/recovery.py: 100%
61 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"""Operator evidence and exceptional execution facts."""
3from typing import Literal, Self
5from pydantic import AwareDatetime, model_validator
7from copytrading_engine.execution.domain.market import BrokerOrder
8from copytrading_engine.execution.domain.order_lifecycle import OrderStatus
9from copytrading_engine.execution.domain.values import Identifier, Positive, Quantity, Side, Value
12class ManualSale(Value):
13 order: BrokerOrder
14 filled_at: AwareDatetime
15 recorded_at: AwareDatetime
16 reason: Identifier
17 lot_id: Identifier | None = None
19 @model_validator(mode="after")
20 def confirmed_sale(self) -> Self:
21 if self.order.side != "sell" or self.order.status != "filled":
22 raise ValueError("Manual reconciliation requires a fully filled sell")
23 if self.filled_at > self.recorded_at:
24 raise ValueError("A manual sale must be filled before it is recorded")
25 return self
28class ReleaseEvidence(Value):
29 actor: Identifier
30 reason: Identifier
31 order_history_ref: Identifier
32 fill_history_ref: Identifier
33 checked_at: AwareDatetime
34 account_id: Identifier
35 submission_state: Literal["started", "not_started"] = "started"
38class IncidentClearanceEvidence(Value):
39 actor: Identifier
40 reason: Identifier
41 checked_at: AwareDatetime
42 account_id: Identifier
43 matched_audit_ref: Identifier | None = None
44 symbol: Identifier | None = None
45 expected_qty: Quantity | None = None
46 broker_qty: Quantity | None = None
48 @model_validator(mode="after")
49 def matched_position_evidence(self) -> Self:
50 quantities_given = any(
51 value is not None for value in (self.symbol, self.expected_qty, self.broker_qty)
52 )
53 if quantities_given and not (
54 self.symbol is not None
55 and self.expected_qty is not None
56 and self.broker_qty is not None
57 and self.expected_qty == self.broker_qty
58 ):
59 raise ValueError(
60 "Matched position evidence requires equal expected and broker quantities"
61 )
62 if self.matched_audit_ref is None and not quantities_given:
63 raise ValueError("Incident clearance requires a matched audit reference or quantities")
64 return self
67class LateOrderIncident(Value):
68 client_id: Identifier
69 broker_id: Identifier
70 symbol: Identifier
71 side: Side
72 first_observed_at: AwareDatetime
73 last_observed_at: AwareDatetime
74 latest_status: OrderStatus
75 raw_broker_status: Identifier
76 latest_filled_qty: Quantity
77 conflicting_order_ids: tuple[Identifier, ...] = ()
78 clearance_history: tuple[IncidentClearanceEvidence, ...] = ()
79 cleared: bool = False
81 @model_validator(mode="after")
82 def valid_incident(self) -> Self:
83 if self.last_observed_at < self.first_observed_at:
84 raise ValueError("Late-order observation time cannot move backwards")
85 if self.cleared and not self.clearance_history:
86 raise ValueError("A cleared late-order incident requires clearance evidence")
87 if len(set(self.conflicting_order_ids)) != len(self.conflicting_order_ids):
88 raise ValueError("Late-order conflicting order identities must be unique")
89 if self.client_id in self.conflicting_order_ids:
90 raise ValueError("A late-order incident cannot conflict with itself")
91 if any(
92 later.checked_at < earlier.checked_at
93 for earlier, later in zip(
94 self.clearance_history, self.clearance_history[1:], strict=False
95 )
96 ):
97 raise ValueError("Incident clearance history must be chronological")
98 return self
100 @property
101 def unresolved(self) -> bool:
102 return not self.cleared
105class QuarantinedFill(Value):
106 """Cumulative sell fill evidence that could not all be charged to its source lot."""
108 client_id: Identifier
109 broker_id: Identifier
110 lot_id: Identifier
111 symbol: Identifier
112 observed_filled_qty: Positive
113 applied_filled_qty: Quantity
114 unapplied_qty: Positive
115 average_price: Positive
116 first_observed_at: AwareDatetime
117 last_observed_at: AwareDatetime
118 incident_client_ids: tuple[Identifier, ...]
120 @model_validator(mode="after")
121 def valid_quarantine(self) -> Self:
122 if self.applied_filled_qty + self.unapplied_qty != self.observed_filled_qty:
123 raise ValueError("Quarantined fill quantities do not match the broker observation")
124 if self.last_observed_at < self.first_observed_at:
125 raise ValueError("Quarantined fill observation time cannot move backwards")
126 if not self.incident_client_ids:
127 raise ValueError("Quarantined fill requires associated incidents")
128 if len(set(self.incident_client_ids)) != len(self.incident_client_ids):
129 raise ValueError("Quarantined fill incident identities must be unique")
130 return self