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

1"""Operator evidence and exceptional execution facts.""" 

2 

3from typing import Literal, Self 

4 

5from pydantic import AwareDatetime, model_validator 

6 

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 

10 

11 

12class ManualSale(Value): 

13 order: BrokerOrder 

14 filled_at: AwareDatetime 

15 recorded_at: AwareDatetime 

16 reason: Identifier 

17 lot_id: Identifier | None = None 

18 

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 

26 

27 

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" 

36 

37 

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 

47 

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 

65 

66 

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 

80 

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 

99 

100 @property 

101 def unresolved(self) -> bool: 

102 return not self.cleared 

103 

104 

105class QuarantinedFill(Value): 

106 """Cumulative sell fill evidence that could not all be charged to its source lot.""" 

107 

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, ...] 

119 

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