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
« 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."""
3import datetime as dt
4import hashlib
5import json
6import logging
7from collections.abc import Callable
8from decimal import Decimal
9from typing import Literal
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
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__)
38class ManualTradingApplication:
39 """Account-local manual workflow; all state changes go through TradingLedger."""
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
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)
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)
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)
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")
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)
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)
134 def result(self, command_id: str) -> ManualCommandResult:
135 snapshot = self.engine.ledger.snapshot()
136 return manual_command_result_from_snapshot(snapshot, command_id)
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 )
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
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")
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"))
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 )
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"))
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 )
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"))
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"))
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")
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 )
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 )
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 )
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.
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 ]
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 )
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()
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
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"