Coverage for src/copytrading_engine/execution/application/manual_commands.py: 90%

242 statements  

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

1"""Preview and explicitly confirm immutable reviewed order corrections.""" 

2 

3import datetime as dt 

4import hashlib 

5import json 

6import logging 

7from collections.abc import Callable 

8from decimal import Decimal 

9from typing import Literal 

10 

11from copytrading_engine.execution.application.engine import CopyEngine 

12from copytrading_engine.execution.application.ports import BrokerError, QuoteBroker 

13from copytrading_engine.execution.domain.ledger_state import LedgerSnapshot 

14from copytrading_engine.execution.domain.manual_commands import ( 

15 ManualCheck, 

16 ManualCommandPage, 

17 ManualCommandRecord, 

18 ManualCommandResult, 

19 ManualConfirmationRequest, 

20 ManualCorrectionRecord, 

21 ManualOrderPreview, 

22 ManualPreviewRequest, 

23 ManualRefusal, 

24) 

25from copytrading_engine.execution.domain.market import Quote 

26from copytrading_engine.execution.domain.order_lifecycle import OrderStatus 

27from copytrading_engine.execution.domain.orders import OrderRecord 

28from copytrading_engine.execution.domain.pricing import quote_problem 

29from copytrading_engine.execution.domain.sessions import Session, trade_date 

30from copytrading_engine.execution.domain.values import BrokerAccountNumber 

31 

32MANUAL_PREVIEW_TTL_SECONDS = 30 

33# Quote problems an order by hand goes without: its limit, not the quote, bounds what it pays. 

34OLD_QUOTE = frozenset({"quote_stale", "quote_unavailable"}) 

35log = logging.getLogger(__name__) 

36 

37 

38class ManualTradingApplication: 

39 """Account-local manual workflow; all state changes go through TradingLedger.""" 

40 

41 def __init__( 

42 self, 

43 engine: CopyEngine, 

44 *, 

45 local_account_id: str, 

46 broker_account_id: BrokerAccountNumber, 

47 environment: Literal["paper", "live"], 

48 halted: Callable[[], bool], 

49 entry_block_reason: Callable[[], str | None], 

50 recovery_ready: Callable[[], bool], 

51 stopping: Callable[[], bool], 

52 ) -> None: 

53 self.engine = engine 

54 self.local_account_id = local_account_id 

55 self.broker_account_id = broker_account_id 

56 self.environment = environment 

57 self.halted = halted 

58 self.entry_block_reason = entry_block_reason 

59 self.recovery_ready = recovery_ready 

60 self.stopping = stopping 

61 

62 def record_correction(self, correction: ManualCorrectionRecord) -> ManualCorrectionRecord: 

63 if self.local_account_id not in correction.selected_account_ids: 63 ↛ 64line 63 didn't jump to line 64 because the condition on line 63 was never true

64 raise ValueError("Manual correction does not select this account") 

65 return self.engine.ledger.record_manual_correction(correction) 

66 

67 def preview(self, request: ManualPreviewRequest, now: dt.datetime) -> ManualOrderPreview: 

68 existing = self.engine.ledger.state.manual_previews.get(request.preview_id) 

69 if existing is not None: 69 ↛ 70line 69 didn't jump to line 70 because the condition on line 69 was never true

70 if existing.request != request: 

71 raise ManualRefusal("identity_conflict") 

72 return existing.model_copy(deep=True) 

73 preview = self._evaluate(request, now) 

74 return self.engine.ledger.save_manual_preview(preview) 

75 

76 def confirm(self, request: ManualConfirmationRequest, now: dt.datetime) -> ManualCommandResult: 

77 snapshot = self.engine.ledger.state 

78 previous = snapshot.manual_commands.get(request.command_id) 

79 if previous is not None: 

80 if previous.request != request: 

81 raise ManualRefusal("identity_conflict") 

82 self.engine.reconcile(now) 

83 return self.result(request.command_id) 

84 

85 preview = snapshot.manual_previews.get(request.preview_id) 

86 if preview is None: 86 ↛ 87line 86 didn't jump to line 87 because the condition on line 86 was never true

87 raise ManualRefusal("preview_missing") 

88 correction = snapshot.manual_corrections.get(preview.request.correction_id) 

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

90 raise ManualRefusal("correction_incomplete") 

91 

92 # Reconciliation is a read of prior broker outcomes before considering a 

93 # second action. It also converts a never acknowledged submit into durable 

94 # uncertainty; this path never resubmits an existing command. 

95 self.engine.reconcile(now) 

96 current = self._evaluate(preview.request, now) 

97 reason = self._confirmation_block(preview, current, correction, now) 

98 if reason is not None: 

99 rejected = ManualCommandRecord( 

100 request=request, 

101 correction_id=correction.correction_id, 

102 source_id=correction.source_id, 

103 instruction_index=preview.request.instruction_index, 

104 confirmed_at=now, 

105 state="rejected", 

106 reason=reason, 

107 ) 

108 self.engine.ledger.reject_manual_command(rejected) 

109 return self.result(request.command_id) 

110 

111 assert preview.plan is not None 

112 client_id = "manual-" + hashlib.sha256(request.command_id.encode()).hexdigest()[:40] 

113 prepared = ManualCommandRecord( 

114 request=request, 

115 correction_id=correction.correction_id, 

116 source_id=correction.source_id, 

117 instruction_index=preview.request.instruction_index, 

118 confirmed_at=now, 

119 state="prepared", 

120 client_id=client_id, 

121 ) 

122 _, order = self.engine.ledger.prepare_manual_command(prepared, preview.plan) 

123 # prepare_manual_command atomically saves the command and intent. The 

124 # existing guarded submit path owns the only broker mutation. 

125 self.engine.submit_manual_prepared( 

126 order, 

127 now, 

128 halted=self.halted, 

129 entry_block_reason=self.entry_block_reason, 

130 stopping=self.stopping, 

131 ) 

132 return self.result(request.command_id) 

133 

134 def result(self, command_id: str) -> ManualCommandResult: 

135 snapshot = self.engine.ledger.snapshot() 

136 return manual_command_result_from_snapshot(snapshot, command_id) 

137 

138 def command_page( 

139 self, 

140 source_id: str, 

141 *, 

142 before_command_id: str | None = None, 

143 limit: int = 50, 

144 ) -> ManualCommandPage: 

145 """List durable source-scoped command results newest first with a stable cursor.""" 

146 return manual_command_page_from_snapshot( 

147 self.engine.ledger.snapshot(), 

148 account_id=self.local_account_id, 

149 source_id=source_id, 

150 before_command_id=before_command_id, 

151 limit=limit, 

152 ) 

153 

154 def _confirmation_block( 

155 self, 

156 saved: ManualOrderPreview, 

157 fresh: ManualOrderPreview, 

158 correction: ManualCorrectionRecord, 

159 now: dt.datetime, 

160 ) -> str | None: 

161 instruction = correction.instructions[saved.request.instruction_index] 

162 if saved.expires_at <= now: 

163 return "preview_expired" 

164 if ( 164 ↛ 170line 164 didn't jump to line 170 because the condition on line 164 was never true

165 saved.request.account_id != self.local_account_id 

166 or correction.correction_id != saved.request.correction_id 

167 or correction.revision != saved.correction_revision 

168 or instruction != saved.instruction 

169 ): 

170 return "correction_changed" 

171 if saved.configuration_sha256 != fresh.configuration_sha256: 

172 return "configuration_changed" 

173 if saved.facts_sha256 != fresh.facts_sha256: 

174 return "account_facts_changed" 

175 if ( 

176 fresh.reasons 

177 or saved.plan is None 

178 or fresh.plan is None 

179 or not saved.plan.still_allowed_by(fresh.plan) 

180 ): 

181 return fresh.reasons[0] if fresh.reasons else "plan_changed" 

182 return None 

183 

184 def _evaluate( 

185 self, 

186 request: ManualPreviewRequest, 

187 now: dt.datetime, 

188 *, 

189 check_permission: bool = True, 

190 ) -> ManualOrderPreview: 

191 snapshot = self.engine.ledger.state 

192 if request.account_id != self.local_account_id: 192 ↛ 193line 192 didn't jump to line 193 because the condition on line 192 was never true

193 raise ValueError("Manual preview account identity mismatch") 

194 correction = snapshot.manual_corrections.get(request.correction_id) 

195 if correction is None or self.local_account_id not in correction.selected_account_ids: 195 ↛ 196line 195 didn't jump to line 196 because the condition on line 195 was never true

196 raise ManualRefusal("correction_incomplete") 

197 if request.instruction_index >= len(correction.instructions): 197 ↛ 198line 197 didn't jump to line 198 because the condition on line 197 was never true

198 raise ValueError("Corrected instruction index is invalid") 

199 if ( 

200 snapshot.account_id != self.broker_account_id 

201 or snapshot.environment != self.environment 

202 ): 

203 raise ManualRefusal("account_identity_changed") 

204 

205 instruction = correction.instructions[request.instruction_index] 

206 message = self.engine.ledger.message(correction.source_id) 

207 source_age = max(0, int((now - correction.source_at).total_seconds())) 

208 config_sha = facts_digest(self.engine.config.model_dump(mode="json")) 

209 reasons: list[str] = [] 

210 # A call waits for the owner only through its own trading day (ADR-0007). 

211 if trade_date(now) != trade_date(correction.source_at): 

212 reasons.append("waiting_expired") 

213 checks = [ManualCheck(name="source", status="blocked", reason="waiting_expired")] 

214 else: 

215 checks = [ManualCheck(name="source", status="passed")] 

216 checks.append(ManualCheck(name="account", status="passed")) 

217 

218 account = self.engine.broker.account() 

219 if account.id != self.broker_account_id or not account.active: 219 ↛ 220line 219 didn't jump to line 220 because the condition on line 219 was never true

220 reasons.append("account_unavailable") 

221 checks.append( 

222 ManualCheck(name="account", status="blocked", reason="account_unavailable") 

223 ) 

224 

225 if instruction.action == "buy" and check_permission: 

226 permission_reason = self.entry_block_reason() 

227 if permission_reason: 

228 reasons.append(permission_reason) 

229 checks.append( 

230 ManualCheck(name="permission", status="blocked", reason=permission_reason) 

231 ) 

232 elif self.halted(): 

233 reasons.append("halted") 

234 checks.append(ManualCheck(name="permission", status="blocked", reason="halted")) 

235 else: 

236 checks.append(ManualCheck(name="permission", status="passed")) 

237 elif instruction.action != "buy" and not self.recovery_ready(): 

238 reasons.append("recovery_pending") 

239 checks.append( 

240 ManualCheck(name="permission", status="blocked", reason="recovery_pending") 

241 ) 

242 else: 

243 checks.append(ManualCheck(name="permission", status="passed")) 

244 

245 session: Session | None = None 

246 decision = None 

247 decision_failure: str | None = None 

248 try: 

249 decision = self.engine.decide( 

250 instruction, 

251 correction.source_id, 

252 message.source_key, 

253 now, 

254 halted=self.halted(), 

255 manual=True, 

256 ) 

257 session = decision.plan.session if decision.plan is not None else None 

258 except BrokerError: 

259 decision_failure = "market_facts_unavailable" 

260 reasons.append(decision_failure) 

261 except Exception as exc: # noqa: BLE001 - unexpected preview failures become a reason 

262 self._report_unexpected_preview_failure("decision", exc) 

263 decision_failure = "preview_unavailable" 

264 reasons.append(decision_failure) 

265 if decision is not None and decision.plan is None and decision.reason != "ready": 

266 reasons.append(decision.reason) 

267 checks.append( 

268 ManualCheck( 

269 name="risk", 

270 status="passed" 

271 if decision is not None and decision.plan is not None 

272 else "blocked", 

273 reason=None 

274 if decision is not None and decision.plan is not None 

275 else ( 

276 decision.reason if decision else decision_failure or "market_facts_unavailable" 

277 ), 

278 ) 

279 ) 

280 

281 # A post is acted on by hand once per stock and side: a second approval, even through a 

282 # new correction of the same post, must not buy again while the first order is open or 

283 # has filled. 

284 side = "buy" if instruction.action == "buy" else "sell" 

285 related_action = False 

286 for command in snapshot.manual_commands.values(): 

287 if ( 

288 command.source_id != correction.source_id 

289 or command.state != "prepared" 

290 or command.client_id is None 

291 ): 

292 continue 

293 earlier = self.engine.ledger.order(command.client_id) 

294 if ( 

295 earlier.symbol == instruction.symbol 

296 and earlier.side == side 

297 and (earlier.pending or earlier.filled_qty > 0) 

298 ): 

299 related_action = True 

300 break 

301 if related_action: 

302 reasons.append("related_manual_action") 

303 checks.append( 

304 ManualCheck(name="prior_action", status="blocked", reason="related_manual_action") 

305 ) 

306 else: 

307 checks.append(ManualCheck(name="prior_action", status="passed")) 

308 

309 quote: Quote | None = None 

310 fresh_price: Decimal | None = None 

311 quote_reason: str | None = None 

312 broker = self.engine.broker 

313 if not isinstance(broker, QuoteBroker): 313 ↛ 314line 313 didn't jump to line 314 because the condition on line 313 was never true

314 quote_reason = "quote_unavailable" 

315 else: 

316 try: 

317 quote = broker.quote(instruction.symbol) 

318 fresh_price = quote.ask if instruction.action == "buy" else quote.bid 

319 quote_reason = quote_problem(quote, fresh_price, now) 

320 except BrokerError: 

321 quote_reason = "quote_unavailable" 

322 except Exception as exc: # noqa: BLE001 - unexpected preview failures become a reason 

323 self._report_unexpected_preview_failure("quote", exc) 

324 quote_reason = "preview_unavailable" 

325 if quote_reason in OLD_QUOTE: 

326 # The order's own limit bounds it (ADR-0007), as it bounds a copied one that never 

327 # reads a quote: a buy carries a price, and a sell at the market is floored by a bid 

328 # the plan already checked. Outside regular hours the free feed is 15 minutes late at 

329 # best, so an old or missing quote only warns, and is not shown as the market's price. 

330 quote, fresh_price = None, None 

331 checks.append(ManualCheck(name="quote", status="warning", reason=quote_reason)) 

332 elif quote_reason is not None: 

333 reasons.append(quote_reason) 

334 checks.append(ManualCheck(name="quote", status="blocked", reason=quote_reason)) 

335 elif decision is not None and decision.plan is not None: 

336 if instruction.action == "buy": 

337 assert fresh_price is not None 

338 assert decision.plan.limit_price is not None 

339 # The limit alone bounds a buy (ADR-0007): an ask above it, which a thin quote feed 

340 # can show far from the market, warns that the order may not fill before its 

341 # timeout cancels it, and never stops the owner from placing it. 

342 if fresh_price > decision.plan.limit_price: 

343 checks.append( 

344 ManualCheck(name="quote", status="warning", reason="quote_above_limit") 

345 ) 

346 else: 

347 checks.append(ManualCheck(name="quote", status="passed")) 

348 else: 

349 checks.append(ManualCheck(name="quote", status="passed")) 

350 else: 

351 checks.append(ManualCheck(name="quote", status="warning", reason="plan_unavailable")) 

352 

353 if not self.recovery_ready(): 

354 # A fresh broker view and ownership audit are required before any 

355 # manual order can use an account whose startup recovery is pending. 

356 if "recovery_pending" not in reasons: 

357 reasons.append("recovery_pending") 

358 

359 plan = decision.plan if decision is not None else None 

360 if reasons: 

361 plan = None 

362 facts = { 

363 "account": account.standing(), 

364 "positions": [item.holding() for item in self.engine.broker.positions()], 

365 "open_orders": [ 

366 item.model_dump(mode="json") for item in self.engine.broker.open_orders() 

367 ], 

368 "snapshot": { 

369 "control": snapshot.control.model_dump(mode="json"), 

370 "orders": [item.model_dump(mode="json") for item in snapshot.orders.values()], 

371 "lots": {key: item.model_dump(mode="json") for key, item in snapshot.lots.items()}, 

372 "external_positions": { 

373 key: item.model_dump(mode="json") 

374 for key, item in snapshot.external_positions.items() 

375 }, 

376 "ownership_incidents": { 

377 key: item.model_dump(mode="json") 

378 for key, item in snapshot.ownership_incidents.items() 

379 }, 

380 "late_order_incidents": { 

381 key: item.model_dump(mode="json") 

382 for key, item in snapshot.late_order_incidents.items() 

383 }, 

384 }, 

385 # No quote: it ticks every second, and the plan recheck at confirmation already bounds 

386 # what a moved price may change (ADR-0007), as a lot sale's facts leave it out too. 

387 "session": session.value if session is not None else None, 

388 "reasons": sorted(set(reasons)), 

389 } 

390 return ManualOrderPreview( 

391 request=request, 

392 broker_account_id=self.broker_account_id, 

393 environment=self.environment, 

394 correction_revision=correction.revision, 

395 source_at=correction.source_at, 

396 source_age_seconds=source_age, 

397 instruction=instruction, 

398 created_at=now, 

399 expires_at=now + dt.timedelta(seconds=MANUAL_PREVIEW_TTL_SECONDS), 

400 session=session, 

401 quote=quote, 

402 fresh_price=fresh_price, 

403 plan=plan, 

404 limit_price=decision.plan.limit_price 

405 if decision is not None and decision.plan is not None 

406 else None, 

407 checks=tuple(checks), 

408 reasons=tuple(sorted(set(reasons))), 

409 facts_sha256=facts_digest(facts), 

410 configuration_sha256=config_sha, 

411 ) 

412 

413 @staticmethod 

414 def _report_unexpected_preview_failure(stage: str, error: Exception) -> None: 

415 """Log only static context and the exception type; never expose its text.""" 

416 log.error( 

417 "Unexpected manual preview failure (stage=%s, error_type=%s)", 

418 stage, 

419 type(error).__name__, 

420 ) 

421 

422 

423def manual_command_result_from_snapshot( 

424 snapshot: LedgerSnapshot, command_id: str 

425) -> ManualCommandResult: 

426 """Project one durable command and its latest order evidence into the read contract.""" 

427 command = snapshot.manual_commands.get(command_id) 

428 if command is None: 

429 raise ManualRefusal("command_not_found") 

430 if command.state == "rejected": 

431 return ManualCommandResult(command=command, status="rejected", reason=command.reason) 

432 assert command.client_id is not None 

433 order = snapshot.orders[command.client_id] 

434 status = owner_order_status(order) 

435 return ManualCommandResult( 

436 command=command, 

437 status=status, 

438 reason=owner_order_reason(status), 

439 client_id=order.client_id, 

440 broker_order_id=order.broker_id, 

441 order_status=order.status, 

442 filled_qty=order.filled_qty, 

443 ) 

444 

445 

446def manual_command_page_from_snapshot( 

447 snapshot: LedgerSnapshot, 

448 *, 

449 account_id: str, 

450 source_id: str, 

451 before_command_id: str | None = None, 

452 limit: int = 50, 

453) -> ManualCommandPage: 

454 """Build a bounded source-scoped history page from one validated account snapshot. 

455 

456 `account_id` is the app's name for the account; the snapshot records the broker's number. 

457 """ 

458 if type(limit) is not int or not 1 <= limit <= 100: 458 ↛ 459line 458 didn't jump to line 459 because the condition on line 458 was never true

459 raise ValueError("Manual command page limit must be between 1 and 100") 

460 commands = [ 

461 command for command in snapshot.manual_commands.values() if command.source_id == source_id 

462 ] 

463 commands.sort( 

464 key=lambda command: (command.confirmed_at, command.request.command_id), reverse=True 

465 ) 

466 if before_command_id is not None: 

467 cursor = next( 

468 (command for command in commands if command.request.command_id == before_command_id), 

469 None, 

470 ) 

471 if cursor is None: 471 ↛ 472line 471 didn't jump to line 472 because the condition on line 471 was never true

472 raise ValueError("Manual command page cursor is unavailable") 

473 cursor_key = (cursor.confirmed_at, cursor.request.command_id) 

474 commands = [ 

475 command 

476 for command in commands 

477 if (command.confirmed_at, command.request.command_id) < cursor_key 

478 ] 

479 

480 has_more = len(commands) > limit 

481 page_commands = commands[:limit] 

482 return ManualCommandPage( 

483 account_id=account_id, 

484 source_id=source_id, 

485 items=tuple( 

486 manual_command_result_from_snapshot(snapshot, command.request.command_id) 

487 for command in page_commands 

488 ), 

489 next_before_command_id=( 

490 page_commands[-1].request.command_id if has_more and page_commands else None 

491 ), 

492 ) 

493 

494 

495def facts_digest(value: object) -> str: 

496 """A stable fingerprint of the facts a preview was decided on.""" 

497 encoded = json.dumps(value, sort_keys=True, separators=(",", ":"), default=str).encode() 

498 return hashlib.sha256(encoded).hexdigest() 

499 

500 

501def owner_order_reason(status: str) -> str | None: 

502 """Why an owner's order (a copy or a lot sale) did not go through, as the code the app words. 

503 The broker's own word stays on the order.""" 

504 return "broker_rejected" if status == "broker_rejected" else None 

505 

506 

507def owner_order_status( 

508 order: OrderRecord, 

509) -> Literal[ 

510 "rejected", 

511 "prepared", 

512 "uncertain", 

513 "accepted", 

514 "partially_filled", 

515 "filled", 

516 "cancelled", 

517 "broker_rejected", 

518 "expired", 

519]: 

520 if order.status == OrderStatus.PREPARED: 520 ↛ 521line 520 didn't jump to line 521 because the condition on line 520 was never true

521 return "prepared" 

522 if order.status == OrderStatus.UNCERTAIN: 

523 return "uncertain" 

524 if order.status == OrderStatus.PARTIALLY_FILLED: 

525 return "partially_filled" 

526 if order.status == OrderStatus.FILLED: 

527 return "filled" 

528 if order.status in {OrderStatus.CANCELED, OrderStatus.REPLACED}: 

529 return "cancelled" 

530 if order.status == OrderStatus.EXPIRED: 530 ↛ 531line 530 didn't jump to line 531 because the condition on line 530 was never true

531 return "expired" 

532 if order.status == OrderStatus.REJECTED: 

533 return "broker_rejected" 

534 if order.status == OrderStatus.ABORTED_BEFORE_SUBMIT: 534 ↛ 535line 534 didn't jump to line 535 because the condition on line 534 was never true

535 return "rejected" 

536 return "accepted"