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
« 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."""
3import asyncio
4import datetime as dt
5import logging
6from collections.abc import Collection
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
44log = logging.getLogger(__name__)
47class ManualInterventionService:
48 """Operator actions that reach a live account owner; each keeps its own identity."""
50 def __init__(self, access: AccountAccess) -> None:
51 self._access = access
52 self._correction_lock = asyncio.Lock()
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 )
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")
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 )
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 )
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))
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
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))
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
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")
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 )
259 by_account: dict[str, list[ManualConfirmationRequest]] = {}
260 for request in requests:
261 by_account.setdefault(request.account_id, []).append(request)
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)
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))
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)
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
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
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
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 )
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
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)
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")