Coverage for src/copytrading_engine/trading/application/manual_intervention.py: 82%

176 statements  

« prev     ^ index     » next       coverage.py v7.16.2, created at 2026-11-16 16:55 +0000

1"""Reviewed corrections, previews, confirmed commands, and account controls.""" 

2 

3import asyncio 

4import datetime as dt 

5import logging 

6from collections.abc import Collection 

7 

8from copytrading_engine.execution.domain.ledger_state import LedgerSnapshot 

9from copytrading_engine.execution.domain.lifecycle import ( 

10 AccountControlCommand, 

11 AccountControlResult, 

12 AccountOwnerClosed, 

13) 

14from copytrading_engine.execution.domain.lot_sales import ( 

15 LotSaleConfirmation, 

16 LotSalePreview, 

17 LotSalePreviewRequest, 

18 LotSaleResult, 

19) 

20from copytrading_engine.execution.domain.manual_commands import ( 

21 ManualAccountCommandResult, 

22 ManualCommandResult, 

23 ManualCommandsOutcome, 

24 ManualConfirmationRequest, 

25 ManualCorrectionAccountResult, 

26 ManualCorrectionOutcome, 

27 ManualCorrectionRecord, 

28 ManualCorrectionRequest, 

29 ManualOrderPreview, 

30 ManualPreviewRequest, 

31 ManualRefusal, 

32) 

33from copytrading_engine.execution.domain.ownership import ( 

34 OwnershipResolution, 

35 OwnershipResolutionRequest, 

36) 

37from copytrading_engine.trading.application.account_access import ( 

38 AccountAccess, 

39 OwnerUnavailable, 

40 bounded_owner_read, 

41) 

42from copytrading_engine.trading.application.accounts import AccountOwner, AccountSupervisor 

43 

44log = logging.getLogger(__name__) 

45 

46 

47class ManualInterventionService: 

48 """Operator actions that reach a live account owner; each keeps its own identity.""" 

49 

50 def __init__(self, access: AccountAccess) -> None: 

51 self._access = access 

52 self._correction_lock = asyncio.Lock() 

53 

54 async def delete_account_record(self, account_id: str) -> str | None: 

55 """Delete the record of an account no longer in the setup, when its owner asks: what 

56 CopyTrading bought there is forgotten, and the shares stay at Alpaca. Returns why it 

57 can't: the account is still in the setup, or another CopyTrading has it open.""" 

58 configuration = self._access.configuration() 

59 in_setup = configuration is not None and any( 

60 account.id == account_id for account in configuration.accounts 

61 ) 

62 if in_setup or account_id in self._access.supervisors(): 

63 return "account_in_setup" 

64 return await asyncio.to_thread( 

65 self._access.evidence.delete_record, self._access.data_dir / "accounts", account_id 

66 ) 

67 

68 async def save_manual_correction( 

69 self, request: ManualCorrectionRequest 

70 ) -> ManualCorrectionOutcome: 

71 """Assign one revision and replicate its exact evidence independently.""" 

72 request = ManualCorrectionRequest.model_validate(request.model_dump()) 

73 async with self._correction_lock: 

74 source_database = self._access.application_database 

75 evidence = await asyncio.wait_for( 

76 asyncio.to_thread( 

77 self._access.evidence.manual_source_evidence, source_database, request.source_id 

78 ), 

79 timeout=3, 

80 ) 

81 if evidence.source_id != request.source_id: 81 ↛ 82line 81 didn't jump to line 82 because the condition on line 81 was never true

82 raise ManualRefusal("post_unavailable") 

83 # Every ledger on disk numbers the post's corrections; only the selected accounts must 

84 # read. An account from an earlier setup whose ledger no longer reads is skipped. 

85 snapshots = await self._manual_snapshots(required=request.selected_account_ids) 

86 by_id = [ 

87 correction 

88 for snapshot in snapshots.values() 

89 for correction in snapshot.manual_corrections.values() 

90 if correction.correction_id == request.correction_id 

91 ] 

92 revisions: dict[int, str] = {} 

93 for snapshot in snapshots.values(): 

94 for correction in snapshot.manual_corrections.values(): 

95 if correction.source_id != request.source_id: 95 ↛ 96line 95 didn't jump to line 96 because the condition on line 95 was never true

96 continue 

97 existing_id = revisions.setdefault( 

98 correction.revision, correction.correction_id 

99 ) 

100 if existing_id != correction.correction_id: 100 ↛ 101line 100 didn't jump to line 101 because the condition on line 100 was never true

101 raise ManualRefusal("correction_conflict") 

102 

103 if by_id: 

104 correction = by_id[0] 

105 if any(item != correction for item in by_id): 105 ↛ 106line 105 didn't jump to line 106 because the condition on line 105 was never true

106 raise ManualRefusal("correction_conflict") 

107 if ( 

108 not correction.matches_request(request) 

109 or correction.source_revision != evidence.source_revision 

110 or correction.source_at != evidence.source_at 

111 or correction.source_text != evidence.text 

112 or correction.accepted_interpretation != evidence.accepted_interpretation 

113 ): 

114 raise ManualRefusal("identity_conflict") 

115 else: 

116 correction = ManualCorrectionRecord( 

117 correction_id=request.correction_id, 

118 source_id=request.source_id, 

119 selected_account_ids=request.selected_account_ids, 

120 revision=max(revisions, default=0) + 1, 

121 actor=request.actor, 

122 reason=request.reason, 

123 instructions=request.instructions, 

124 source_revision=evidence.source_revision, 

125 source_at=evidence.source_at, 

126 source_text=evidence.text, 

127 accepted_interpretation=evidence.accepted_interpretation, 

128 recorded_at=dt.datetime.now(dt.UTC), 

129 ) 

130 

131 async def record_one(account_id: str) -> ManualCorrectionAccountResult: 

132 supervisor = self._access.supervisors().get(account_id) 

133 if supervisor is None or supervisor.owner is None or supervisor.state == "failed": 

134 return ManualCorrectionAccountResult( 

135 account_id=account_id, status="unavailable", reason="account_not_running" 

136 ) 

137 try: 

138 saved = await supervisor.owner.record_manual_correction(correction) 

139 if saved != correction: 139 ↛ 140line 139 didn't jump to line 140 because the condition on line 139 was never true

140 raise RuntimeError("Account correction copy differs") 

141 return ManualCorrectionAccountResult(account_id=account_id, status="recorded") 

142 except AccountOwnerClosed: 

143 # Copying is pausing or stopped: the call was never offered to this account. 

144 return ManualCorrectionAccountResult( 

145 account_id=account_id, status="unavailable", reason="account_not_running" 

146 ) 

147 except Exception as exc: # noqa: BLE001 - one account's failure is reported per account 

148 # A refusal names itself; anything else is one account that could not save. 

149 reason = exc.reason if isinstance(exc, ManualRefusal) else "record_failed" 

150 log.warning( 

151 "manual_correction_record_failed account=%s error=%s reason=%s", 

152 account_id, 

153 type(exc).__name__, 

154 reason, 

155 ) 

156 return ManualCorrectionAccountResult( 

157 account_id=account_id, status="failed", reason=reason 

158 ) 

159 

160 accounts = await asyncio.gather( 

161 *(record_one(account_id) for account_id in request.selected_account_ids) 

162 ) 

163 # An account that did not record says why; the owner reads those, not one error. 

164 if any(account.status == "recorded" for account in accounts): 

165 # The guru's history reads the owner's call in place of the reader's (ADR-0010). 

166 await asyncio.to_thread( 

167 self._access.evidence.record_owner_correction, 

168 source_database, 

169 correction.source_id, 

170 correction.instructions, 

171 correction.recorded_at, 

172 ) 

173 return ManualCorrectionOutcome(correction=correction, accounts=tuple(accounts)) 

174 

175 async def preview_manual_order(self, request: ManualPreviewRequest) -> ManualOrderPreview: 

176 request = ManualPreviewRequest.model_validate(request.model_dump()) 

177 _, owner = self._manual_owner(request.account_id) 

178 live = await bounded_owner_read(owner.observation()) 

179 if isinstance(live, OwnerUnavailable): 179 ↛ 180line 179 didn't jump to line 180 because the condition on line 179 was never true

180 raise ManualRefusal("account_unavailable") 

181 record = live.ledger.manual_corrections.get(request.correction_id) 

182 if record is None: 182 ↛ 183line 182 didn't jump to line 183 because the condition on line 182 was never true

183 raise ManualRefusal("correction_incomplete") 

184 await self._require_agreeing_copies(record, request.account_id) 

185 try: 

186 return await owner.preview_manual_order(request, dt.datetime.now(dt.UTC)) 

187 except AccountOwnerClosed as exc: 

188 raise ManualRefusal("account_not_running") from exc 

189 

190 async def preview_lot_sale(self, request: LotSalePreviewRequest) -> LotSalePreview: 

191 request = LotSalePreviewRequest.model_validate(request.model_dump()) 

192 _, owner = self._manual_owner(request.account_id) 

193 return await owner.preview_lot_sale(request, dt.datetime.now(dt.UTC)) 

194 

195 async def confirm_lot_sale(self, request: LotSaleConfirmation) -> LotSaleResult: 

196 request = LotSaleConfirmation.model_validate(request.model_dump()) 

197 supervisor, owner = self._manual_owner(request.account_id) 

198 result = await owner.confirm_lot_sale(request, dt.datetime.now(dt.UTC)) 

199 await supervisor.refresh() 

200 return result 

201 

202 async def confirm_manual_orders( 

203 self, requests: tuple[ManualConfirmationRequest, ...] 

204 ) -> ManualCommandsOutcome: 

205 if not requests or len(requests) > 20: 205 ↛ 206line 205 didn't jump to line 206 because the condition on line 205 was never true

206 raise ValueError("Manual confirmation batch is invalid") 

207 requests = tuple( 

208 ManualConfirmationRequest.model_validate(item.model_dump()) for item in requests 

209 ) 

210 if len({item.command_id for item in requests}) != len(requests): 210 ↛ 211line 210 didn't jump to line 211 because the condition on line 210 was never true

211 raise ValueError("Manual confirmation batch has duplicate command IDs") 

212 

213 async def confirm_one(request: ManualConfirmationRequest) -> ManualAccountCommandResult: 

214 try: 

215 supervisor, owner = self._manual_owner(request.account_id) 

216 live = await owner.observation() 

217 command = live.ledger.manual_commands.get(request.command_id) 

218 if command is None: 

219 preview = live.ledger.manual_previews.get(request.preview_id) 

220 correction = ( 

221 live.ledger.manual_corrections.get(preview.request.correction_id) 

222 if preview is not None 

223 else None 

224 ) 

225 if correction is None: 225 ↛ 226line 225 didn't jump to line 226 because the condition on line 225 was never true

226 raise ManualRefusal( 

227 "preview_missing" if preview is None else "correction_incomplete" 

228 ) 

229 await self._require_agreeing_copies(correction, request.account_id) 

230 result = await owner.confirm_manual_order(request, dt.datetime.now(dt.UTC)) 

231 await supervisor.refresh() 

232 return ManualAccountCommandResult( 

233 account_id=request.account_id, 

234 command_id=request.command_id, 

235 result=result, 

236 ) 

237 except AccountOwnerClosed: 

238 # Closed before the call ran, so nothing was sent. 

239 return ManualAccountCommandResult( 

240 account_id=request.account_id, 

241 command_id=request.command_id, 

242 error="account_not_running", 

243 ) 

244 except Exception as exc: # noqa: BLE001 - one account's failure is reported per account 

245 # A refusal names itself; anything else cannot say whether the order went. 

246 reason = exc.reason if isinstance(exc, ManualRefusal) else "confirm_failed" 

247 log.warning( 

248 "manual_command_failed account=%s error=%s reason=%s", 

249 request.account_id, 

250 type(exc).__name__, 

251 reason, 

252 ) 

253 return ManualAccountCommandResult( 

254 account_id=request.account_id, 

255 command_id=request.command_id, 

256 error=reason, 

257 ) 

258 

259 by_account: dict[str, list[ManualConfirmationRequest]] = {} 

260 for request in requests: 

261 by_account.setdefault(request.account_id, []).append(request) 

262 

263 async def confirm_account( 

264 account_requests: list[ManualConfirmationRequest], 

265 ) -> tuple[ManualAccountCommandResult, ...]: 

266 # Recheck each preview only after the previous command has been 

267 # durably reconciled. A changed account snapshot rejects later 

268 # previews instead of letting a batch silently reuse stale sizing. 

269 outcomes = [] 

270 for item in account_requests: 

271 outcomes.append(await confirm_one(item)) 

272 return tuple(outcomes) 

273 

274 batches = await asyncio.gather( 

275 *(confirm_account(by_account[account_id]) for account_id in sorted(by_account)) 

276 ) 

277 return ManualCommandsOutcome(outcomes=tuple(item for batch in batches for item in batch)) 

278 

279 async def manual_command_result(self, account_id: str, command_id: str) -> ManualCommandResult: 

280 _, owner = self._manual_owner(account_id) 

281 return await owner.manual_command_result(command_id) 

282 

283 async def control_account(self, command: AccountControlCommand) -> AccountControlResult: 

284 supervisor = self._access.supervisors().get(command.account_id) 

285 if supervisor is None or supervisor.owner is None or supervisor.state == "failed": 285 ↛ 286line 285 didn't jump to line 286 because the condition on line 285 was never true

286 raise ValueError("Account is not available for control") 

287 result = await supervisor.owner.control_account(command, dt.datetime.now(dt.UTC)) 

288 await supervisor.refresh() 

289 return result 

290 

291 async def resolve_ownership( 

292 self, local_account_id: str, request: OwnershipResolutionRequest 

293 ) -> OwnershipResolution: 

294 supervisor = self._access.supervisors().get(local_account_id) 

295 if supervisor is None or supervisor.owner is None or supervisor.state == "failed": 

296 raise ValueError("Account is not available for ownership review") 

297 result = await supervisor.owner.resolve_ownership(request) 

298 await supervisor.refresh() 

299 return result 

300 

301 def _manual_owner(self, account_id: str) -> tuple[AccountSupervisor, AccountOwner]: 

302 supervisor = self._access.supervisors().get(account_id) 

303 if supervisor is None or supervisor.owner is None or supervisor.state == "failed": 

304 raise ManualRefusal("account_not_running") 

305 return supervisor, supervisor.owner 

306 

307 async def _manual_snapshots( 

308 self, 

309 account_ids: Collection[str] | None = None, 

310 *, 

311 required: Collection[str] | None = None, 

312 ) -> dict[str, LedgerSnapshot]: 

313 """The ledgers of `account_ids`, or of every retained account. With `required`, only those 

314 accounts must read; any other ledger that fails is left out.""" 

315 paths = self._access.retained_paths() 

316 must_read = set(required or ()) 

317 selected_ids = ( 

318 sorted(set(paths) | must_read) if account_ids is None else sorted(set(account_ids)) 

319 ) 

320 

321 async def read_one(account_id: str) -> tuple[str, LedgerSnapshot] | None: 

322 database = paths.get(account_id) 

323 supervisor = self._access.supervisors().get(account_id) 

324 if ( 

325 supervisor is not None 

326 and supervisor.owner is not None 

327 and supervisor.state != "failed" 

328 ): 

329 live = await bounded_owner_read(supervisor.owner.observation()) 

330 if not isinstance(live, OwnerUnavailable): 330 ↛ 332line 330 didn't jump to line 332 because the condition on line 330 was always true

331 return account_id, live.ledger 

332 if database is None: 332 ↛ 333line 332 didn't jump to line 333 because the condition on line 332 was never true

333 raise ManualRefusal("records_unreadable") 

334 try: 

335 _, snapshot, _ = await self._access.retained_account(database, timeout=3) 

336 return account_id, snapshot 

337 except Exception as exc: 

338 log.warning( 

339 "manual_ledger_read_failed account=%s type=%s", account_id, type(exc).__name__ 

340 ) 

341 if required is not None and account_id not in must_read: 

342 return None 

343 raise ManualRefusal("records_unreadable") from exc 

344 

345 read = await asyncio.gather(*(read_one(account_id) for account_id in selected_ids)) 

346 return dict(item for item in read if item is not None) 

347 

348 async def _require_agreeing_copies( 

349 self, correction: ManualCorrectionRecord, account_id: str 

350 ) -> None: 

351 """The account acting on a correction holds it, and no other chosen account holds a 

352 different copy under its name. A chosen account that could not record it (paused, or 

353 the call no longer waits there) holds none, which never stops the accounts that did.""" 

354 snapshots = await self._manual_snapshots( 

355 correction.selected_account_ids, required=(account_id,) 

356 ) 

357 if snapshots[account_id].manual_corrections.get(correction.correction_id) != correction: 357 ↛ 358line 357 didn't jump to line 358 because the condition on line 357 was never true

358 raise ManualRefusal("correction_incomplete") 

359 if any( 

360 copy != correction 

361 for snapshot in snapshots.values() 

362 if (copy := snapshot.manual_corrections.get(correction.correction_id)) is not None 

363 ): 

364 raise ManualRefusal("correction_conflict")