Coverage for src/copytrading_engine/execution/application/ledger.py: 80%

734 statements  

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

1"""Trading state transitions; publish a new in-memory state only after durable commit.""" 

2 

3import datetime as dt 

4import hashlib 

5import logging 

6import unicodedata 

7from decimal import ROUND_DOWN, Decimal 

8from typing import Literal, TypedDict, Unpack 

9 

10from copytrading_engine.execution.application.ports import ExecutionObserver, LedgerRepository 

11from copytrading_engine.execution.domain.events import ( 

12 AccountControlChanged, 

13 AccountInventoried, 

14 CancelRequested, 

15 CashAnchorRecorded, 

16 CryptoFeeCounted, 

17 Exposure, 

18 JournalEvent, 

19 LateOrderIncidentCleared, 

20 LateOrderIncidentOpened, 

21 LateOrderIncidentReopened, 

22 LotSalePrepared, 

23 LotSalePreviewed, 

24 LotSaleRejected, 

25 ManualCommandPrepared, 

26 ManualCommandRejected, 

27 ManualCorrectionRecorded, 

28 ManualOrderPreviewed, 

29 ManualSaleRecorded, 

30 Message, 

31 MessageDone, 

32 OrderIntentReleased, 

33 OrderPrepared, 

34 OrderUpdate, 

35 OwnershipIncidentOpened, 

36 OwnershipResolved, 

37 SellWaiting, 

38 SendAborted, 

39 StopEnded, 

40 StopSet, 

41 SubmissionAborted, 

42 SubmissionUncertain, 

43 SubmitError, 

44 SubmitStarted, 

45) 

46from copytrading_engine.execution.domain.events import Skipped as SkippedEvent 

47from copytrading_engine.execution.domain.ledger_state import ( 

48 CashAnchor, 

49 LedgerSnapshot, 

50 MessageRecord, 

51 MessageStatus, 

52) 

53from copytrading_engine.execution.domain.lifecycle import ( 

54 AccountControl, 

55 AccountControlCommand, 

56 AccountControlConflict, 

57 AccountControlResult, 

58) 

59from copytrading_engine.execution.domain.lot_sales import LotSalePreview, LotSaleRecord 

60from copytrading_engine.execution.domain.manual_commands import ( 

61 ManualCommandRecord, 

62 ManualCorrectionRecord, 

63 ManualOrderPreview, 

64 ManualRefusal, 

65) 

66from copytrading_engine.execution.domain.market import BrokerOrder, Position 

67from copytrading_engine.execution.domain.order_lifecycle import ( 

68 OrderStatus, 

69 is_pending, 

70 map_broker_status, 

71 validate_transition, 

72) 

73from copytrading_engine.execution.domain.orders import ( 

74 LIVE_AT_BROKER, 

75 CancelReason, 

76 OrderPlan, 

77 OrderRecord, 

78 OwnedLot, 

79 copy_client_id, 

80) 

81from copytrading_engine.execution.domain.ownership import ( 

82 ExternalPosition, 

83 OwnershipIncident, 

84 OwnershipResolution, 

85 OwnershipResolutionRequest, 

86 allocate, 

87 sync_reason, 

88) 

89from copytrading_engine.execution.domain.positions import CRYPTO_FEE_CEILING, PositionAudit 

90from copytrading_engine.execution.domain.progress import ( 

91 InstructionProgress, 

92 OrderLinked, 

93 Pending, 

94 SellWait, 

95 Skipped, 

96) 

97from copytrading_engine.execution.domain.recovery import ( 

98 IncidentClearanceEvidence, 

99 LateOrderIncident, 

100 ManualSale, 

101 QuarantinedFill, 

102 ReleaseEvidence, 

103) 

104from copytrading_engine.execution.domain.sessions import trade_date 

105from copytrading_engine.execution.domain.sizing import DestinationSignal 

106from copytrading_engine.execution.domain.stops import StopRule, stop_client_id 

107from copytrading_engine.shared.signals import Instruction, StockSignal 

108 

109ZERO = Decimal(0) 

110# Alpaca counts a coin to the billionth. 

111COIN_STEP = Decimal("0.000000001") 

112log = logging.getLogger(__name__) 

113 

114 

115def _post_words(text: str) -> str: 

116 """A post's text as the guru wrote it, whatever its width, case, or spacing.""" 

117 return " ".join(unicodedata.normalize("NFKC", text).casefold().split()) 

118 

119 

120def _repeats( 

121 instruction: Instruction, 

122 signal: StockSignal, 

123 earlier: MessageRecord, 

124 window_minutes: int | None, 

125 previous: tuple[MessageRecord, ...] = (), 

126) -> bool: 

127 """A guru re-posting a call is not a new call, while the guru's repeat check is on. A buy 

128 read the same way (stock, price, size) within the guru's window is the same buy; later it can 

129 be a real second buy at that price. A sell repeated the same trading day, naming the same lot, 

130 price, and size, is always the same sell: done twice it would sell the rest of the lot, as 

131 when a guru re-posts the day's calls in a recap. A post with the same words as the earlier one 

132 repeats its buy or sell of the stock however the model read it the second time. With the check 

133 off, every post is copied.""" 

134 buying = instruction.action == "buy" 

135 if window_minutes is None or not any( 

136 instruction.same_call(other) 

137 or ( 

138 other.symbol == instruction.symbol 

139 and (other.action == "buy") == buying 

140 and _post_words(signal.text) == _post_words(earlier.text) 

141 ) 

142 for other in earlier.instructions 

143 ): 

144 return False 

145 at = signal.timestamp 

146 since = (at - earlier.timestamp).total_seconds() 

147 if since < 0: 147 ↛ 148line 147 didn't jump to line 148 because the condition on line 147 was never true

148 return False 

149 # A buy or sell of this stock the other way since then makes this a new call: the same sell 

150 # after a new buy sells that buy. 

151 if any( 

152 earlier.timestamp < other.timestamp <= at 

153 and any( 

154 i.symbol == instruction.symbol and (i.action == "buy") != buying 

155 for i in other.instructions 

156 ) 

157 for other in previous 

158 ): 

159 return False 

160 if instruction.action == "buy": 

161 return since <= window_minutes * 60 

162 return trade_date(at) == trade_date(earlier.timestamp) 

163 

164 

165class _SnapshotChanges(TypedDict, total=False): 

166 account_id: str 

167 control: AccountControl 

168 messages: dict[str, MessageRecord] 

169 orders: dict[str, OrderRecord] 

170 lots: dict[str, OwnedLot] 

171 manual_sales: dict[str, ManualSale] 

172 release_evidence: dict[str, ReleaseEvidence] 

173 late_order_incidents: dict[str, LateOrderIncident] 

174 quarantined_fills: dict[str, QuarantinedFill] 

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

176 external_positions: dict[str, ExternalPosition] 

177 ownership_incidents: dict[str, OwnershipIncident] 

178 ownership_resolutions: dict[str, OwnershipResolution] 

179 manual_corrections: dict[str, ManualCorrectionRecord] 

180 manual_previews: dict[str, ManualOrderPreview] 

181 manual_commands: dict[str, ManualCommandRecord] 

182 lot_sale_previews: dict[str, LotSalePreview] 

183 lot_sales: dict[str, LotSaleRecord] 

184 stops: dict[str, StopRule] 

185 

186 

187# Why a late post's buy is skipped as soon as the post is received (ADR-0010). 

188LATE_SKIPS = frozenset({"stale", "out_of_order"}) 

189 

190 

191class _MessageChanges(TypedDict, total=False): 

192 status: MessageStatus 

193 parts: tuple[InstructionProgress, ...] 

194 stop_parts: tuple[InstructionProgress, ...] 

195 cash_anchor: CashAnchor 

196 

197 

198class _OrderChanges(TypedDict, total=False): 

199 status: OrderStatus 

200 submit_started_at: dt.datetime 

201 raw_broker_status: str | None 

202 

203 

204def _priced(orders: dict[str, OrderRecord], key: str, lot: OwnedLot) -> OwnedLot: 

205 """The lot keyed by `key`, its average set from each of its buys' fill prices.""" 

206 fills = { 

207 entry: order.filled_avg_price 

208 for entry in lot.entries(key) 

209 if (order := orders.get(entry)) is not None and order.filled_avg_price is not None 

210 } 

211 return lot.priced(fills) 

212 

213 

214class TradingLedger: 

215 """Own validated state, isolated from repository and caller-owned containers. 

216 

217 Every transition validates the complete snapshot and commits it with a journal 

218 event before publishing it in memory. Failed persistence leaves state unchanged. 

219 """ 

220 

221 def __init__(self, repository: LedgerRepository, observer: ExecutionObserver) -> None: 

222 self._repository = repository 

223 loaded = LedgerSnapshot.model_validate(repository.load().model_dump()) 

224 # A lot saved before its average followed only the shares still held is repriced here. 

225 self._snapshot = loaded.model_copy( 

226 update={ 

227 "lots": {key: _priced(loaded.orders, key, lot) for key, lot in loaded.lots.items()} 

228 } 

229 ) 

230 self._observer = observer 

231 

232 @property 

233 def account_id(self) -> str | None: 

234 return self._snapshot.account_id 

235 

236 def snapshot(self) -> LedgerSnapshot: 

237 """A detached copy, for state that leaves the owner thread. Containers must not expose a 

238 second mutable owner of the aggregate.""" 

239 return self._snapshot.model_copy(deep=True) 

240 

241 @property 

242 def state(self) -> LedgerSnapshot: 

243 """The published state, read in place on the owner thread: every transition publishes a 

244 new snapshot, so this one never changes underneath its reader. Never mutate it, and use 

245 `snapshot()` for anything that leaves the owner thread. A copy of the whole ledger costs 

246 tens of milliseconds, and a cycle reads it a dozen times.""" 

247 return self._snapshot 

248 

249 def orders(self) -> tuple[OrderRecord, ...]: 

250 return tuple(self._snapshot.orders.values()) 

251 

252 def lots(self) -> tuple[OwnedLot, ...]: 

253 return tuple(self._snapshot.lots.values()) 

254 

255 def message(self, key: str) -> MessageRecord: 

256 return self._snapshot.messages[key] 

257 

258 def order(self, key: str) -> OrderRecord: 

259 return self._snapshot.orders[key] 

260 

261 def queued(self) -> tuple[MessageRecord, ...]: 

262 return tuple(m for m in self._snapshot.messages.values() if m.status == "queued") 

263 

264 def pending(self, symbol: str | None = None) -> tuple[OrderRecord, ...]: 

265 return tuple( 

266 o for o in self.orders() if o.pending and (symbol is None or o.symbol == symbol) 

267 ) 

268 

269 def owned(self, symbol: str) -> Decimal: 

270 return sum((lot.remaining_qty for lot in self.lots() if lot.symbol == symbol), ZERO) 

271 

272 def expected_position(self, symbol: str) -> Decimal: 

273 return self._snapshot.expected_holdings.get(symbol, ZERO) 

274 

275 def unresolved_ownership(self, symbol: str) -> tuple[OwnershipIncident, ...]: 

276 return tuple( 

277 incident 

278 for incident in self._snapshot.ownership_incidents.values() 

279 if incident.symbol == symbol and not incident.resolved 

280 ) 

281 

282 def exposure(self, symbol: str | None = None) -> Decimal: 

283 owned = sum( 

284 ( 

285 lot.remaining_qty * lot.average_price 

286 for lot in self.lots() 

287 if symbol is None or lot.symbol == symbol 

288 ), 

289 ZERO, 

290 ) 

291 reserved = sum( 

292 ( 

293 (o.qty - o.filled_qty) * o.limit_price 

294 for o in self.pending(symbol) 

295 if o.side == "buy" and o.limit_price is not None 

296 ), 

297 ZERO, 

298 ) 

299 return owned + reserved 

300 

301 def _entry_lot(self, lots: dict[str, OwnedLot], key: str, order: OrderRecord) -> str: 

302 """The lot a buy's fills belong to: the one it opened or already joined; else the open 

303 lot it was planned to join; else the guru's open lot of the stock (ADR-0010); else its 

304 own.""" 

305 for lot_key, lot in lots.items(): 

306 if key in lot.entries(lot_key): 

307 return lot_key 

308 joined = lots.get(order.joins_lot or "") 

309 if joined is not None and joined.remaining_qty > 0 and joined.symbol == order.symbol: 

310 assert order.joins_lot is not None 

311 return order.joins_lot 

312 for lot_key, lot in lots.items(): 

313 if lot.remaining_qty > 0 and (lot.source_key, lot.symbol) == ( 313 ↛ 317line 313 didn't jump to line 317 because the condition on line 313 was never true

314 order.source_key, 

315 order.symbol, 

316 ): 

317 return lot_key 

318 return key 

319 

320 def position_lots(self, source: str, symbol: str) -> tuple[tuple[str, OwnedLot], ...]: 

321 """The guru's open lots of a stock; one for a guru whose sells refer to the whole 

322 position.""" 

323 return tuple( 

324 (key, lot) 

325 for key, lot in self._snapshot.lots.items() 

326 if lot.source_key == source and lot.symbol == symbol and lot.remaining_qty > 0 

327 ) 

328 

329 def _commit(self, state: LedgerSnapshot, event: JournalEvent) -> None: 

330 # Frozen models still contain mutable dictionaries. The port must not retain 

331 # an alias to the state we publish (including when save raises). 

332 self._repository.save(state.model_copy(deep=True), event) 

333 self._snapshot = state 

334 self._observer.event(event.payload.kind, event.payload.model_dump(mode="json")) 

335 log.info("%s %s", event.payload.kind, event.payload.model_dump(mode="json")) 

336 

337 def record(self, event: JournalEvent) -> None: 

338 self._commit(self._snapshot, event) 

339 

340 def account_control( 

341 self, command: AccountControlCommand, now: dt.datetime, *, local_account_id: str 

342 ) -> AccountControlResult: 

343 if command.account_id != local_account_id or self.account_id is None: 343 ↛ 344line 343 didn't jump to line 344 because the condition on line 343 was never true

344 raise ValueError("Account control identity mismatch") 

345 control = self._snapshot.control 

346 previous = control.commands.get(command.command_id) 

347 if previous is not None: 

348 if previous.command != command: 

349 raise AccountControlConflict("Account control command identity conflict") 

350 return previous 

351 permission = control.entry_permission 

352 preference = control.recovery_preference 

353 if command.action == "pause": 

354 permission = "paused" 

355 elif command.action == "resume": 

356 permission = "enabled" 

357 elif command.action == "restore_manual": 

358 permission = "disabled" 

359 preference = "manual" 

360 else: 

361 # Recovery is chosen in the setup now; a record keeps the commands it took earlier. 

362 raise ValueError("Recovery preference is set in the account's setup") 

363 result = AccountControlResult( 

364 command=command, 

365 applied_at=now, 

366 entry_permission=permission, 

367 recovery_preference=preference, 

368 ) 

369 updated = AccountControl( 

370 entry_permission=permission, 

371 recovery_preference=preference, 

372 commands=control.commands | {command.command_id: result}, 

373 ) 

374 self._commit( 

375 self._replace(control=updated), 

376 JournalEvent(at=now, payload=AccountControlChanged(result=result)), 

377 ) 

378 return result 

379 

380 def skip_unpermitted_buys(self, now: dt.datetime, reason: str) -> None: 

381 for message in self.queued(): 

382 for index, instruction in enumerate(message.instructions): 

383 if instruction.action == "buy" and isinstance( 

384 self.message(message.key).parts[index], Pending 

385 ): 

386 self.skip(message.key, index, reason, now) 

387 if all(not isinstance(part, Pending) for part in self.message(message.key).parts): 

388 self.complete(message.key, now) 

389 

390 def record_manual_sale(self, sale: ManualSale, actual_qty: Decimal | None = None) -> None: 

391 """Operator-only import of a verified broker fill; never submits an order.""" 

392 existing = self._snapshot.manual_sales.get(sale.order.id) 

393 if existing is not None: 

394 if existing.model_dump(exclude={"recorded_at"}) != sale.model_dump( 

395 exclude={"recorded_at"} 

396 ): 

397 raise ValueError("Manual sale was already recorded with different evidence") 

398 return 

399 lot = self._snapshot.lots.get(sale.lot_id or "") 

400 if sale.lot_id is not None and (lot is None or lot.symbol != sale.order.symbol): 

401 raise ValueError("Manual sale does not match an owned lot") 

402 if self.pending(sale.order.symbol): 

403 raise ValueError("Reconcile pending copier orders before recording a manual sale") 

404 external = self._snapshot.external_positions.get(sale.order.symbol) 

405 ambiguous = sale.lot_id is None or (external is not None and external.qty > ZERO) 

406 if ambiguous: 

407 if actual_qty is None: 407 ↛ 408line 407 didn't jump to line 408 because the condition on line 407 was never true

408 raise ValueError("Manual sale requires fresh broker position evidence") 

409 if self.unresolved_ownership(sale.order.symbol): 409 ↛ 410line 409 didn't jump to line 410 because the condition on line 409 was never true

410 raise ValueError("Resolve existing symbol ownership before importing another sale") 

411 # A caller-supplied lot cannot choose the attribution of mixed holdings. 

412 if sale.lot_id is not None: 412 ↛ 413line 412 didn't jump to line 413 because the condition on line 412 was never true

413 raise ValueError("Mixed holdings require an unallocated manual sale") 

414 incident = OwnershipIncident( 

415 incident_id=sale.order.id, 

416 symbol=sale.order.symbol, 

417 expected_qty=self.expected_position(sale.order.symbol), 

418 actual_qty=actual_qty, 

419 observed_at=sale.recorded_at, 

420 cause="manual_sale", 

421 ) 

422 state = self._replace( 

423 manual_sales=self._snapshot.manual_sales | {sale.order.id: sale}, 

424 ownership_incidents=self._snapshot.ownership_incidents | {sale.order.id: incident}, 

425 ) 

426 previous_remaining_qty = None 

427 remaining_qty = None 

428 else: 

429 if lot is None or sale.order.filled_qty > lot.remaining_qty: 

430 raise ValueError("Manual sale exceeds remaining owned lot shares") 

431 updated = _priced( 

432 self._snapshot.orders, sale.lot_id, lot.reduced(sale.order.filled_qty) 

433 ) 

434 state = self._replace( 

435 lots=self._snapshot.lots | {sale.lot_id: updated}, 

436 manual_sales=self._snapshot.manual_sales | {sale.order.id: sale}, 

437 ) 

438 incident = None 

439 previous_remaining_qty = lot.remaining_qty 

440 remaining_qty = updated.remaining_qty 

441 self._commit( 

442 state, 

443 JournalEvent( 

444 at=sale.recorded_at, 

445 payload=ManualSaleRecorded( 

446 sale=sale, 

447 previous_remaining_qty=previous_remaining_qty, 

448 remaining_qty=remaining_qty, 

449 ownership_incident=incident, 

450 ), 

451 ), 

452 ) 

453 

454 def record_manual_correction( 

455 self, correction: ManualCorrectionRecord 

456 ) -> ManualCorrectionRecord: 

457 """Persist this account's copy of a shared immutable correction.""" 

458 correction = ManualCorrectionRecord.model_validate(correction.model_dump()) 

459 existing = self._snapshot.manual_corrections.get(correction.correction_id) 

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

461 if existing != correction: 

462 raise ManualRefusal("identity_conflict") 

463 return existing 

464 message = self._snapshot.messages.get(correction.source_id) 

465 if message is None: 

466 raise ManualRefusal("call_not_received") 

467 if not message.waits_for_owner: 

468 raise ManualRefusal("call_not_waiting") 

469 if ( 

470 message.timestamp != correction.source_at 

471 or message.text != correction.source_text 

472 or StockSignal.model_validate( 

473 {name: getattr(message, name) for name in StockSignal.model_fields} 

474 ) 

475 != correction.accepted_interpretation 

476 ): 

477 raise ManualRefusal("call_changed") 

478 if any( 478 ↛ 482line 478 didn't jump to line 482 because the condition on line 478 was never true

479 value.source_id == correction.source_id and value.revision == correction.revision 

480 for value in self._snapshot.manual_corrections.values() 

481 ): 

482 raise ManualRefusal("correction_conflict") 

483 self._commit( 

484 self._replace( 

485 manual_corrections=self._snapshot.manual_corrections 

486 | {correction.correction_id: correction} 

487 ), 

488 JournalEvent( 

489 at=correction.recorded_at, 

490 payload=ManualCorrectionRecorded(correction=correction), 

491 ), 

492 ) 

493 return correction 

494 

495 def save_manual_preview(self, preview: ManualOrderPreview) -> ManualOrderPreview: 

496 """Save fresh preview evidence without touching the broker.""" 

497 preview = ManualOrderPreview.model_validate(preview.model_dump()) 

498 preview_id = preview.request.preview_id 

499 existing = self._snapshot.manual_previews.get(preview_id) 

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

501 if existing.request != preview.request: 

502 raise ManualRefusal("identity_conflict") 

503 return existing 

504 if preview.broker_account_id != self.account_id: 504 ↛ 505line 504 didn't jump to line 505 because the condition on line 504 was never true

505 raise ManualRefusal("account_identity_changed") 

506 self._commit( 

507 self._replace(manual_previews=self._snapshot.manual_previews | {preview_id: preview}), 

508 JournalEvent(at=preview.created_at, payload=ManualOrderPreviewed(preview=preview)), 

509 ) 

510 return preview 

511 

512 def reject_manual_command(self, command: ManualCommandRecord) -> ManualCommandRecord: 

513 """Durably retain a blocked or stale confirmation under its stable ID.""" 

514 command = ManualCommandRecord.model_validate(command.model_dump()) 

515 previous = self._snapshot.manual_commands.get(command.request.command_id) 

516 if previous is not None: 516 ↛ 517line 516 didn't jump to line 517 because the condition on line 516 was never true

517 if previous != command: 

518 raise ManualRefusal("identity_conflict") 

519 return previous 

520 if command.state != "rejected": 520 ↛ 521line 520 didn't jump to line 521 because the condition on line 520 was never true

521 raise ValueError("Rejected command must not carry an order intent") 

522 self._validate_manual_command(command) 

523 self._commit( 

524 self._replace( 

525 manual_commands=self._snapshot.manual_commands 

526 | {command.request.command_id: command} 

527 ), 

528 JournalEvent(at=command.confirmed_at, payload=ManualCommandRejected(command=command)), 

529 ) 

530 return command 

531 

532 def prepare_manual_command( 

533 self, command: ManualCommandRecord, plan: OrderPlan 

534 ) -> tuple[ManualCommandRecord, OrderRecord]: 

535 """Atomically commit the manual command and its broker intent.""" 

536 command = ManualCommandRecord.model_validate(command.model_dump()) 

537 plan = OrderPlan.model_validate(plan.model_dump()) 

538 previous = self._snapshot.manual_commands.get(command.request.command_id) 

539 if previous is not None: 539 ↛ 540line 539 didn't jump to line 540 because the condition on line 539 was never true

540 if previous != command: 

541 raise ManualRefusal("identity_conflict") 

542 if previous.client_id is None: 

543 raise ValueError("A rejected manual command cannot be prepared") 

544 return previous, self.order(previous.client_id) 

545 if command.state != "prepared" or command.client_id is None: 545 ↛ 546line 545 didn't jump to line 546 because the condition on line 545 was never true

546 raise ValueError("Prepared command requires a stable client order ID") 

547 self._validate_manual_command(command) 

548 preview = self._snapshot.manual_previews[command.request.preview_id] 

549 if preview.plan != plan or preview.plan is None: 549 ↛ 550line 549 didn't jump to line 550 because the condition on line 549 was never true

550 raise ValueError("Manual order plan differs from its saved preview") 

551 correction = self._snapshot.manual_corrections[command.correction_id] 

552 message = self.message(correction.source_id) 

553 if command.client_id in self._snapshot.orders: 553 ↛ 554line 553 didn't jump to line 554 because the condition on line 553 was never true

554 raise ValueError("Manual order intent identity already exists") 

555 if self.pending(plan.symbol): 555 ↛ 556line 555 didn't jump to line 556 because the condition on line 555 was never true

556 raise ManualRefusal("wait_pending_order") 

557 if plan.side == "buy" and self._snapshot.entry_halted: 557 ↛ 558line 557 didn't jump to line 558 because the condition on line 557 was never true

558 raise ManualRefusal("unresolved_order_incident") 

559 order = OrderRecord( 

560 **plan.model_dump(), 

561 client_id=command.client_id, 

562 message_id=correction.source_id, 

563 instruction_index=command.instruction_index, 

564 source_key=message.source_key, 

565 status=OrderStatus.PREPARED, 

566 filled_qty=ZERO, 

567 broker_id=None, 

568 created_at=command.confirmed_at, 

569 day=trade_date(command.confirmed_at), 

570 ) 

571 self._commit( 

572 self._replace( 

573 orders=self._snapshot.orders | {order.client_id: order}, 

574 manual_commands=self._snapshot.manual_commands 

575 | {command.request.command_id: command}, 

576 ), 

577 JournalEvent( 

578 at=command.confirmed_at, 

579 payload=ManualCommandPrepared(command=command, plan=plan), 

580 ), 

581 ) 

582 return command, order 

583 

584 def save_lot_sale_preview(self, preview: LotSalePreview) -> LotSalePreview: 

585 """Save fresh lot sale evidence without touching the broker.""" 

586 preview = LotSalePreview.model_validate(preview.model_dump()) 

587 preview_id = preview.request.preview_id 

588 existing = self._snapshot.lot_sale_previews.get(preview_id) 

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

590 if existing.request != preview.request: 

591 raise ValueError("Lot sale preview identity conflicts with another request") 

592 return existing 

593 if preview.broker_account_id != self.account_id: 593 ↛ 594line 593 didn't jump to line 594 because the condition on line 593 was never true

594 raise ValueError("Lot sale preview belongs to another broker account") 

595 self._commit( 

596 self._replace( 

597 lot_sale_previews=self._snapshot.lot_sale_previews | {preview_id: preview} 

598 ), 

599 JournalEvent(at=preview.created_at, payload=LotSalePreviewed(preview=preview)), 

600 ) 

601 return preview 

602 

603 def reject_lot_sale(self, sale: LotSaleRecord) -> LotSaleRecord: 

604 """Durably retain a blocked or stale confirmation under its stable ID.""" 

605 sale = LotSaleRecord.model_validate(sale.model_dump()) 

606 previous = self._snapshot.lot_sales.get(sale.request.command_id) 

607 if previous is not None: 607 ↛ 608line 607 didn't jump to line 608 because the condition on line 607 was never true

608 if previous != sale: 

609 raise ValueError("Lot sale identity conflicts with different content") 

610 return previous 

611 if sale.state != "rejected": 611 ↛ 612line 611 didn't jump to line 612 because the condition on line 611 was never true

612 raise ValueError("A rejected lot sale must not carry an order intent") 

613 self._commit( 

614 self._replace(lot_sales=self._snapshot.lot_sales | {sale.request.command_id: sale}), 

615 JournalEvent(at=sale.confirmed_at, payload=LotSaleRejected(sale=sale)), 

616 ) 

617 return sale 

618 

619 def prepare_lot_sale( 

620 self, sale: LotSaleRecord, plan: OrderPlan 

621 ) -> tuple[LotSaleRecord, OrderRecord]: 

622 """Atomically commit the owner's lot sale and its broker intent. 

623 

624 The order is filed under the post that bought the lot, so Activity shows the sale 

625 beside the buy, and it names the lot so the fill comes out of exactly those shares. 

626 """ 

627 sale = LotSaleRecord.model_validate(sale.model_dump()) 

628 plan = OrderPlan.model_validate(plan.model_dump()) 

629 previous = self._snapshot.lot_sales.get(sale.request.command_id) 

630 if previous is not None: 630 ↛ 631line 630 didn't jump to line 631 because the condition on line 630 was never true

631 if previous != sale: 

632 raise ValueError("Lot sale identity conflicts with different content") 

633 if previous.client_id is None: 

634 raise ValueError("A rejected lot sale cannot be prepared") 

635 return previous, self.order(previous.client_id) 

636 if sale.state != "prepared" or sale.client_id is None: 636 ↛ 637line 636 didn't jump to line 637 because the condition on line 636 was never true

637 raise ValueError("A prepared lot sale requires a stable client order ID") 

638 preview = self._snapshot.lot_sale_previews.get(sale.request.preview_id) 

639 if preview is None or preview.plan is None or preview.plan != plan: 639 ↛ 640line 639 didn't jump to line 640 because the condition on line 639 was never true

640 raise ValueError("Lot sale order plan differs from its saved preview") 

641 if preview.request.lot_id != sale.lot_id or plan.lot_id != sale.lot_id: 641 ↛ 642line 641 didn't jump to line 642 because the condition on line 641 was never true

642 raise ValueError("Lot sale does not name its previewed lot") 

643 lot = self._snapshot.lots.get(sale.lot_id) 

644 if lot is None or lot.symbol != plan.symbol or plan.qty > lot.remaining_qty: 644 ↛ 645line 644 didn't jump to line 645 because the condition on line 644 was never true

645 raise ValueError("Lot sale exceeds the shares left in its lot") 

646 buy = self._snapshot.orders.get(sale.lot_id) 

647 if buy is None: 647 ↛ 648line 647 didn't jump to line 648 because the condition on line 647 was never true

648 raise ValueError("Lot sale has no buy on record to file it under") 

649 if sale.client_id in self._snapshot.orders: 649 ↛ 650line 649 didn't jump to line 650 because the condition on line 649 was never true

650 raise ValueError("Lot sale intent identity already exists") 

651 if self.pending(plan.symbol): 651 ↛ 652line 651 didn't jump to line 652 because the condition on line 651 was never true

652 raise ValueError("A pending order already owns this symbol") 

653 order = OrderRecord( 

654 **plan.model_dump(), 

655 client_id=sale.client_id, 

656 message_id=buy.message_id, 

657 instruction_index=buy.instruction_index, 

658 source_key=lot.source_key, 

659 status=OrderStatus.PREPARED, 

660 filled_qty=ZERO, 

661 broker_id=None, 

662 created_at=sale.confirmed_at, 

663 day=trade_date(sale.confirmed_at), 

664 ) 

665 self._commit( 

666 self._replace( 

667 orders=self._snapshot.orders | {order.client_id: order}, 

668 lot_sales=self._snapshot.lot_sales | {sale.request.command_id: sale}, 

669 ), 

670 JournalEvent(at=sale.confirmed_at, payload=LotSalePrepared(sale=sale, plan=plan)), 

671 ) 

672 return sale, order 

673 

674 def _validate_manual_command(self, command: ManualCommandRecord) -> None: 

675 # Requests name the account the app's way; ManualTradingApplication checks that name, 

676 # and this ledger only knows the broker's number for it. 

677 preview = self._snapshot.manual_previews.get(command.request.preview_id) 

678 correction = self._snapshot.manual_corrections.get(command.correction_id) 

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

680 preview is None 

681 or correction is None 

682 or command.request.account_id != preview.request.account_id 

683 or preview.request.correction_id != command.correction_id 

684 or preview.request.instruction_index != command.instruction_index 

685 or command.source_id != correction.source_id 

686 ): 

687 raise ValueError("Manual command does not match this account's saved preview") 

688 

689 def _replace(self, **changes: Unpack[_SnapshotChanges]) -> LedgerSnapshot: 

690 return LedgerSnapshot.model_validate(self._snapshot.model_dump() | changes) 

691 

692 def bind( 

693 self, 

694 account_id: str, 

695 now: dt.datetime, 

696 environment: Literal["paper", "live"] = "paper", 

697 positions: tuple[Position, ...] = (), 

698 ) -> None: 

699 if self.account_id and self.account_id != account_id: 699 ↛ 700line 699 didn't jump to line 700 because the condition on line 699 was never true

700 raise RuntimeError("This ledger belongs to a different broker account") 

701 if self.account_id and self._snapshot.environment is None: 701 ↛ 702line 701 didn't jump to line 702 because the condition on line 701 was never true

702 raise RuntimeError("Saved ledger is missing its broker environment") 

703 if self._snapshot.environment is not None and self._snapshot.environment != environment: 703 ↛ 704line 703 didn't jump to line 704 because the condition on line 703 was never true

704 raise RuntimeError("This ledger belongs to a different broker environment") 

705 if not self.account_id: 

706 inventory = { 

707 position.symbol: ExternalPosition(symbol=position.symbol, qty=position.qty) 

708 for position in positions 

709 } 

710 if len(inventory) != len(positions) or any( 710 ↛ 713line 710 didn't jump to line 713 because the condition on line 710 was never true

711 position.qty < ZERO for position in positions 

712 ): 

713 raise ValueError("Unsupported or duplicate initial broker positions") 

714 self._commit( 

715 self._replace( 

716 account_id=account_id, environment=environment, external_positions=inventory 

717 ), 

718 JournalEvent( 

719 at=now, 

720 payload=AccountInventoried( 

721 account_id=account_id, environment=environment, external_positions=inventory 

722 ), 

723 ), 

724 ) 

725 

726 def open_ownership_incidents( 

727 self, 

728 audit: PositionAudit, 

729 now: dt.datetime, 

730 outside_orders: frozenset[str] = frozenset(), 

731 *, 

732 settle_before: dt.datetime | None = None, 

733 ) -> None: 

734 """Open a question for each stock whose broker count left what the ledger expects, and 

735 settle every earlier one whose count has held still since (ADR-0011). `outside_orders` are 

736 the stocks with an open broker order the app didn't place; those wait, since that order 

737 can still move the count. With `settle_before`, only questions opened before it settle. 

738 """ 

739 # The audit predates what was just settled, so those stocks wait for the next one. 

740 settled = self._settle_incidents( 

741 audit, now, outside_orders, now if settle_before is None else min(now, settle_before) 

742 ) 

743 for comparison in audit.positions: 

744 if ( 

745 not comparison.mismatched 

746 or comparison.symbol in settled 

747 or self.unresolved_ownership(comparison.symbol) 

748 ): 

749 continue 

750 revision = sum( 

751 incident.symbol == comparison.symbol 

752 for incident in self._snapshot.ownership_incidents.values() 

753 ) 

754 identity = ( 

755 "position-" 

756 + hashlib.sha256( 

757 f"{comparison.symbol}:{comparison.expected}:{comparison.actual}:{revision}".encode() 

758 ).hexdigest()[:32] 

759 ) 

760 incident = OwnershipIncident( 

761 incident_id=identity, 

762 symbol=comparison.symbol, 

763 expected_qty=comparison.expected, 

764 actual_qty=comparison.actual, 

765 observed_at=now, 

766 cause="position_mismatch", 

767 ) 

768 self._commit( 

769 self._replace( 

770 ownership_incidents=self._snapshot.ownership_incidents | {identity: incident} 

771 ), 

772 JournalEvent(at=now, payload=OwnershipIncidentOpened(incident=incident)), 

773 ) 

774 

775 def _settle_incidents( 

776 self, 

777 audit: PositionAudit, 

778 now: dt.datetime, 

779 outside_orders: frozenset[str], 

780 opened_before: dt.datetime, 

781 ) -> set[str]: 

782 """Settle each open question from the broker's filled count, once that count has held 

783 still for a sync and no order in the stock is in flight (the app's own, an uncertain one, 

784 or one placed outside). Copied shares the broker still holds stay copied and the rest 

785 count as the owner's own; a broker count below the copied shares means copied shares were 

786 sold outside the app, oldest buys first, the way the app's own sells take them.""" 

787 account_id = self.account_id 

788 settled: set[str] = set() 

789 if account_id is None: 789 ↛ 790line 789 didn't jump to line 790 because the condition on line 789 was never true

790 return settled 

791 compared = {comparison.symbol: comparison for comparison in audit.positions} 

792 for incident in tuple(self._snapshot.ownership_incidents.values()): 

793 if incident.resolved or opened_before <= incident.observed_at: 

794 continue 

795 symbol = incident.symbol 

796 if ( 

797 symbol in outside_orders 

798 or self.pending(symbol) 

799 or any( 

800 item.symbol == symbol and item.unresolved 

801 for item in self._snapshot.late_order_incidents.values() 

802 ) 

803 ): 

804 continue 

805 lots = self._lots_oldest_first(symbol) 

806 comparison = compared.get(symbol) 

807 broker_qty = comparison.actual if comparison is not None else Decimal(0) 

808 expected = comparison.expected if comparison is not None else broker_qty 

809 allocation = allocate(broker_qty, lots) 

810 reason = sync_reason(broker_qty, expected, sum((held for _, held in lots), Decimal(0))) 

811 self.resolve_ownership( 

812 OwnershipResolutionRequest( 

813 resolution_id=f"synced-{incident.incident_id}", 

814 incident_id=incident.incident_id, 

815 account_id=account_id, 

816 symbol=symbol, 

817 actor="copytrading", 

818 reason=reason, 

819 broker_qty=broker_qty, 

820 external_qty=allocation.external_qty, 

821 lot_remaining=allocation.lot_remaining, 

822 ), 

823 now, 

824 ) 

825 settled.add(symbol) 

826 return settled 

827 

828 def _lots_oldest_first(self, symbol: str) -> list[tuple[str, Decimal]]: 

829 """A stock's copied lots and what each still holds, in the order their first buys were 

830 placed, which is the order an outside sale takes them in.""" 

831 snapshot = self._snapshot 

832 lots = [(key, lot) for key, lot in snapshot.lots.items() if lot.symbol == symbol] 

833 

834 def opened(item: tuple[str, object]) -> tuple[dt.datetime, str]: 

835 order = snapshot.orders.get(item[0]) 

836 return ( 

837 order.created_at if order is not None else dt.datetime.max.replace(tzinfo=dt.UTC), 

838 item[0], 

839 ) 

840 

841 return [(key, lot.remaining_qty) for key, lot in sorted(lots, key=opened)] 

842 

843 def resolve_ownership( 

844 self, request: OwnershipResolutionRequest, checked_at: dt.datetime 

845 ) -> OwnershipResolution: 

846 request = OwnershipResolutionRequest.model_validate(request.model_dump()) 

847 prior = self._snapshot.ownership_resolutions.get(request.resolution_id) 

848 if prior is not None: 848 ↛ 849line 848 didn't jump to line 849 because the condition on line 848 was never true

849 if prior.request != request: 

850 raise ValueError("Ownership resolution ID conflicts with different content") 

851 return prior 

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

853 raise ValueError("Ownership resolution account identity mismatch") 

854 incident = self._snapshot.ownership_incidents.get(request.incident_id) 

855 if incident is None or incident.resolved or incident.symbol != request.symbol: 855 ↛ 856line 855 didn't jump to line 856 because the condition on line 855 was never true

856 raise ValueError("Unresolved symbol ownership incident is required") 

857 if checked_at <= incident.observed_at: 857 ↛ 858line 857 didn't jump to line 858 because the condition on line 857 was never true

858 raise ValueError("Ownership resolution requires newer broker evidence") 

859 if self.pending(request.symbol) or any( 859 ↛ 863line 859 didn't jump to line 863 because the condition on line 859 was never true

860 item.symbol == request.symbol and item.unresolved 

861 for item in self._snapshot.late_order_incidents.values() 

862 ): 

863 raise ValueError("Overlapping order uncertainty prevents ownership allocation") 

864 lot_ids = {key for key, lot in self._snapshot.lots.items() if lot.symbol == request.symbol} 

865 if set(request.lot_remaining) != lot_ids: 865 ↛ 866line 865 didn't jump to line 866 because the condition on line 865 was never true

866 raise ValueError("Ownership resolution must include every owned lot for the symbol") 

867 reductions = {} 

868 lots = self._snapshot.lots.copy() 

869 for key in lot_ids: 

870 before = lots[key] 

871 target = request.lot_remaining[key] 

872 if target > before.remaining_qty: 

873 raise ValueError("Ownership resolution cannot invent app-owned shares") 

874 reductions[key] = before.remaining_qty - target 

875 lots[key] = _priced( 

876 self._snapshot.orders, key, before.reduced(before.remaining_qty - target) 

877 ) 

878 allocation_revision = 1 + max( 

879 ( 

880 prior.allocation_revision 

881 for prior in self._snapshot.ownership_resolutions.values() 

882 if prior.request.symbol == request.symbol 

883 ), 

884 default=0, 

885 ) 

886 resolution = OwnershipResolution( 

887 request=request, 

888 checked_at=checked_at, 

889 lot_reductions=reductions, 

890 allocation_revision=allocation_revision, 

891 ) 

892 state = self._replace( 

893 lots=lots, 

894 external_positions=self._snapshot.external_positions 

895 | { 

896 request.symbol: ExternalPosition( 

897 symbol=request.symbol, 

898 qty=request.external_qty, 

899 allocation_revision=allocation_revision, 

900 ) 

901 }, 

902 ownership_incidents=self._snapshot.ownership_incidents 

903 | { 

904 request.incident_id: incident.model_copy( 

905 update={"resolved_by": request.resolution_id} 

906 ) 

907 }, 

908 ownership_resolutions=self._snapshot.ownership_resolutions 

909 | {request.resolution_id: resolution}, 

910 ) 

911 self._commit( 

912 state, JournalEvent(at=checked_at, payload=OwnershipResolved(resolution=resolution)) 

913 ) 

914 return resolution 

915 

916 def receive(self, delivery: DestinationSignal, now: dt.datetime, max_age: int) -> None: 

917 signal, destination = delivery.signal, delivery.terms 

918 source_key = f"{signal.source}:{signal.channel_id}" 

919 key = f"{source_key}:{signal.id}" 

920 if key in self._snapshot.messages: 

921 prior = self._snapshot.messages[key] 

922 original = {name: getattr(prior, name) for name in StockSignal.model_fields} 

923 if StockSignal.model_validate(original) != signal: 

924 raise ValueError("Signal identity was reused with different content") 

925 if prior.destination != destination: 

926 raise ValueError("A received destination cannot change its accepted terms") 

927 return 

928 age = (now - signal.timestamp).total_seconds() 

929 if signal.decision == "trade": 

930 status: MessageStatus = "queued" 

931 elif signal.decision == "ignore": 

932 status = "ignored" 

933 else: 

934 status = "review_required" 

935 # Only buys can be too old: a post of nothing but buys is stale; a late post's sells are 

936 # still copied, and its buys are skipped as stale (ADR-0010). 

937 too_old = age < -5 or age > max_age 

938 # A stop is like a sell: never too old. A post of a buy and its stop is stale with the buy. 

939 buys_only = bool(signal.instructions) and all( 

940 i.action == "buy" for i in signal.instructions 

941 ) 

942 if status == "queued" and too_old and buys_only: 

943 status = "stale" 

944 previous = tuple(m for m in self._snapshot.messages.values() if m.source_key == source_key) 

945 # A post older than one already received is out of order. Its buys are not copied; its 

946 # sells still are, and take only from buys posted before them (ADR-0010). 

947 out_of_order = status == "queued" and any( 

948 m.decision == "trade" 

949 and m.status not in {"stale", "out_of_order"} 

950 and signal.timestamp < m.timestamp 

951 for m in previous 

952 ) 

953 if out_of_order and buys_only: 

954 status = "out_of_order" 

955 # A post wholly too late (stale, out of order) skips its buys too; none is left pending. 

956 late = status in {"queued", *LATE_SKIPS} 

957 parts = tuple( 

958 Skipped(reason="stale") 

959 if late and too_old and instruction.action == "buy" 

960 else Skipped(reason="out_of_order") 

961 if late and out_of_order and instruction.action == "buy" 

962 else Skipped(reason="duplicate") 

963 if status == "queued" 

964 and any( 

965 _repeats(instruction, signal, m, destination.repeat_window_minutes, previous) 

966 for m in previous 

967 ) 

968 else Pending() 

969 for instruction in signal.instructions 

970 ) 

971 # The stop of a post that was too late to buy is skipped with it; no buy is there to guard. 

972 stop_parts = tuple( 

973 Pending() if status == "queued" else Skipped(reason=status) for _ in signal.stops 

974 ) 

975 message = MessageRecord.model_validate( 

976 signal.model_dump() 

977 | { 

978 "source_key": source_key, 

979 "parts": parts, 

980 "stop_parts": stop_parts, 

981 "status": status, 

982 "destination": destination, 

983 } 

984 ) 

985 self._commit( 

986 self._replace(messages=self._snapshot.messages | {key: message}), 

987 JournalEvent( 

988 at=now, 

989 payload=Message( 

990 message_id=key, 

991 status=status, 

992 parser_decision=signal.decision, 

993 parser_reason=signal.reason, 

994 parser_profile=signal.parser_profile, 

995 instructions=signal.instructions, 

996 destination=destination, 

997 stops=signal.stops, 

998 ), 

999 ), 

1000 ) 

1001 # A late post's buys skipped as too old or out of order are on its timeline like any other 

1002 # skip, though the post's sells still go out. 

1003 for part, progress in enumerate(parts): 

1004 if isinstance(progress, Skipped) and progress.reason in LATE_SKIPS: 

1005 self.record( 

1006 JournalEvent( 

1007 at=now, 

1008 payload=SkippedEvent( 

1009 message_id=key, part=part, reason=progress.reason, exposure=None 

1010 ), 

1011 ) 

1012 ) 

1013 

1014 def _message_state(self, key: str, **changes: Unpack[_MessageChanges]) -> LedgerSnapshot: 

1015 message = MessageRecord.model_validate(self.message(key).model_dump() | changes) 

1016 return self._replace(messages=self._snapshot.messages | {key: message}) 

1017 

1018 def anchor_cash( 

1019 self, key: str, account_id: str, cash: Decimal, buying_power: Decimal, now: dt.datetime 

1020 ) -> CashAnchor: 

1021 """Commit the first broker observation before preparing any buy in this message.""" 

1022 message = self.message(key) 

1023 if message.cash_anchor is not None: 

1024 return message.cash_anchor 

1025 if message.status != "queued" or account_id != self.account_id: 1025 ↛ 1026line 1025 didn't jump to line 1026 because the condition on line 1025 was never true

1026 raise RuntimeError("Cannot anchor funds for this message or account") 

1027 anchor = CashAnchor( 

1028 account_id=account_id, 

1029 message_id=key, 

1030 observed_at=now, 

1031 cash=cash, 

1032 buying_power=buying_power, 

1033 ) 

1034 self._commit( 

1035 self._message_state(key, cash_anchor=anchor), 

1036 JournalEvent(at=now, payload=CashAnchorRecorded(anchor=anchor)), 

1037 ) 

1038 return anchor 

1039 

1040 def skip( 

1041 self, 

1042 key: str, 

1043 part: int, 

1044 reason: str, 

1045 now: dt.datetime, 

1046 *, 

1047 exposure: tuple[Exposure, ...] | None = None, 

1048 bought_at: dt.datetime | None = None, 

1049 ) -> None: 

1050 message = self.message(key) 

1051 if message.status != "queued" or not isinstance(message.parts[part], Pending): 1051 ↛ 1052line 1051 didn't jump to line 1052 because the condition on line 1051 was never true

1052 raise RuntimeError("Instruction was already processed") 

1053 parts = list(message.parts) 

1054 parts[part] = Skipped(reason=reason, exposure=exposure or (), bought_at=bought_at) 

1055 self._commit( 

1056 self._message_state(key, parts=tuple(parts)), 

1057 JournalEvent( 

1058 at=now, 

1059 payload=SkippedEvent( 

1060 message_id=key, 

1061 part=part, 

1062 reason=reason, 

1063 exposure=exposure, 

1064 bought_at=bought_at, 

1065 ), 

1066 ), 

1067 ) 

1068 

1069 def skip_stop(self, key: str, index: int, reason: str, now: dt.datetime) -> None: 

1070 """A stop the account does not place, and why (setting off, no buy to guard...).""" 

1071 message = self.message(key) 

1072 if message.status != "queued" or not isinstance(message.stop_parts[index], Pending): 1072 ↛ 1073line 1072 didn't jump to line 1073 because the condition on line 1072 was never true

1073 raise RuntimeError("Stop was already processed") 

1074 parts = list(message.stop_parts) 

1075 parts[index] = Skipped(reason=reason) 

1076 self._commit( 

1077 self._message_state(key, stop_parts=tuple(parts)), 

1078 JournalEvent( 

1079 at=now, 

1080 payload=SkippedEvent( 

1081 message_id=key, part=index, reason=reason, exposure=None, stop=True 

1082 ), 

1083 ), 

1084 ) 

1085 

1086 def set_stop(self, rule: StopRule, now: dt.datetime) -> None: 

1087 """Follow a stop. A buy has one stop, so the buys it protects leave any older stop, which 

1088 ends when none are left; a stop posted again at the same price is left as it is.""" 

1089 rules = dict(self._snapshot.stops) 

1090 replaced = [] 

1091 for key, old in tuple(rules.items()): 

1092 kept = tuple(entry for entry in old.entries if entry not in rule.entries) 

1093 if kept == old.entries: 1093 ↛ 1094line 1093 didn't jump to line 1094 because the condition on line 1093 was never true

1094 continue 

1095 replaced.append(key) 

1096 if kept: 1096 ↛ 1097line 1096 didn't jump to line 1097 because the condition on line 1096 was never true

1097 rules[key] = old.model_copy(update={"entries": kept}) 

1098 else: 

1099 del rules[key] 

1100 rules[rule.key] = rule 

1101 self._commit( 

1102 self._replace(stops=rules), 

1103 JournalEvent( 

1104 at=now, 

1105 payload=StopSet(message_id=rule.message_id, rule=rule, replaced=tuple(replaced)), 

1106 ), 

1107 ) 

1108 

1109 def end_stop( 

1110 self, key: str, reason: Literal["nothing_left", "replaced"], now: dt.datetime 

1111 ) -> None: 

1112 """Stop following a stop. One whose first order was never placed is skipped.""" 

1113 rule = self._snapshot.stops[key] 

1114 message = self.message(rule.message_id) 

1115 index = rule.order_index - len(message.instructions) 

1116 messages = self._snapshot.messages 

1117 if message.status == "queued" and isinstance(message.stop_parts[index], Pending): 1117 ↛ 1118line 1117 didn't jump to line 1118 because the condition on line 1117 was never true

1118 parts = list(message.stop_parts) 

1119 parts[index] = Skipped(reason="stop_nothing_left") 

1120 messages = messages | { 

1121 rule.message_id: MessageRecord.model_validate( 

1122 message.model_dump() | {"stop_parts": tuple(parts)} 

1123 ) 

1124 } 

1125 self._commit( 

1126 self._replace( 

1127 stops={k: v for k, v in self._snapshot.stops.items() if k != key}, 

1128 messages=messages, 

1129 ), 

1130 JournalEvent( 

1131 at=now, 

1132 payload=StopEnded(message_id=rule.message_id, rule_key=key, reason=reason), 

1133 ), 

1134 ) 

1135 

1136 def prepare_stop( 

1137 self, plan: OrderPlan, rule: StopRule, attempt: int, now: dt.datetime 

1138 ) -> OrderRecord: 

1139 """Record the day order that places a stop. The stop's post links its first one.""" 

1140 message = self.message(rule.message_id) 

1141 index = rule.order_index - len(message.instructions) 

1142 client_id = stop_client_id(rule.key, attempt) 

1143 if plan.type != "stop" or client_id in self._snapshot.orders: 1143 ↛ 1144line 1143 didn't jump to line 1144 because the condition on line 1143 was never true

1144 raise RuntimeError("Stop order intent already exists") 

1145 order = OrderRecord( 

1146 **plan.model_dump(), 

1147 client_id=client_id, 

1148 message_id=rule.message_id, 

1149 instruction_index=rule.order_index, 

1150 source_key=message.source_key, 

1151 status=OrderStatus.PREPARED, 

1152 filled_qty=ZERO, 

1153 broker_id=None, 

1154 created_at=now, 

1155 day=trade_date(now), 

1156 stop_rule=rule.key, 

1157 ) 

1158 updated = message 

1159 if isinstance(message.stop_parts[index], Pending): 

1160 parts = list(message.stop_parts) 

1161 parts[index] = OrderLinked(client_id=client_id) 

1162 updated = MessageRecord.model_validate(message.model_dump() | {"stop_parts": parts}) 

1163 self._commit( 

1164 self._replace( 

1165 messages=self._snapshot.messages | {rule.message_id: updated}, 

1166 orders=self._snapshot.orders | {client_id: order}, 

1167 ), 

1168 JournalEvent( 

1169 at=now, 

1170 payload=OrderPrepared( 

1171 client_id=client_id, 

1172 message_id=rule.message_id, 

1173 symbol=plan.symbol, 

1174 side=plan.side, 

1175 position_intent=plan.position_intent, 

1176 source_price=plan.source_price, 

1177 entry_price=plan.entry_price, 

1178 qty=plan.qty, 

1179 type=plan.type, 

1180 limit_price=None, 

1181 stop_price=plan.stop_price, 

1182 entry_tolerance_pct=plan.entry_tolerance_pct, 

1183 session=plan.session, 

1184 ), 

1185 ), 

1186 ) 

1187 return order 

1188 

1189 def sell_waiting(self, key: str, part: int, reason: SellWait, now: dt.datetime) -> None: 

1190 """Note why a sell is still waiting to go out, once each time the reason changes.""" 

1191 message = self.message(key) 

1192 waiting = Pending(waiting=reason) 

1193 if message.status != "queued" or not isinstance(message.parts[part], Pending): 1193 ↛ 1194line 1193 didn't jump to line 1194 because the condition on line 1193 was never true

1194 raise RuntimeError("Instruction was already processed") 

1195 if message.parts[part] == waiting: 

1196 return 

1197 parts = list(message.parts) 

1198 parts[part] = waiting 

1199 self._commit( 

1200 self._message_state(key, parts=tuple(parts)), 

1201 JournalEvent(at=now, payload=SellWaiting(message_id=key, part=part, reason=reason)), 

1202 ) 

1203 

1204 def complete(self, key: str, now: dt.datetime) -> None: 

1205 self._commit( 

1206 self._message_state(key, status="done"), 

1207 JournalEvent(at=now, payload=MessageDone(message_id=key)), 

1208 ) 

1209 

1210 def prepare(self, plan: OrderPlan, key: str, part: int, now: dt.datetime) -> OrderRecord: 

1211 message = self.message(key) 

1212 if message.status != "queued" or not isinstance(message.parts[part], Pending): 1212 ↛ 1213line 1212 didn't jump to line 1213 because the condition on line 1212 was never true

1213 raise RuntimeError("Instruction was already processed") 

1214 instruction = message.instructions[part] 

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

1216 # A whole-position sell names no buy price; it sells from the lot its plan found. 

1217 entry_price = ( 

1218 instruction.price 

1219 if side == "buy" 

1220 else instruction.entry_price 

1221 if instruction.entry_price is not None 

1222 else plan.entry_price 

1223 ) 

1224 # A sell at the market has no guru's price; its plan carries the bid it was priced from. 

1225 if (plan.symbol, plan.side, plan.entry_price) != ( 1225 ↛ 1230line 1225 didn't jump to line 1230 because the condition on line 1225 was never true

1226 instruction.symbol, 

1227 side, 

1228 entry_price, 

1229 ) or instruction.price not in (None, plan.source_price): 

1230 raise RuntimeError("Order plan differs from its source instruction") 

1231 if plan.side == "buy" and self._snapshot.entry_halted: 1231 ↛ 1232line 1231 didn't jump to line 1232 because the condition on line 1231 was never true

1232 raise RuntimeError("Unresolved late-order incidents halt new buy orders") 

1233 # One open buy of a stock at a time, and never a sell of more than the open sells leave. 

1234 pending = self.pending(plan.symbol) 

1235 if plan.side == "buy" and any(order.side == "buy" for order in pending): 1235 ↛ 1236line 1235 didn't jump to line 1236 because the condition on line 1235 was never true

1236 raise RuntimeError("An open buy already owns this symbol") 

1237 # A stop leaves its shares to a sell, which cancels it before it goes out (ADR-0015). 

1238 if plan.side == "sell" and plan.qty > self.owned(plan.symbol) - sum( 1238 ↛ 1246line 1238 didn't jump to line 1246 because the condition on line 1238 was never true

1239 ( 

1240 order.qty - order.filled_qty 

1241 for order in pending 

1242 if order.side == "sell" and order.type != "stop" 

1243 ), 

1244 ZERO, 

1245 ): 

1246 raise RuntimeError("A sell cannot take shares an open sell is selling") 

1247 # A sell aborted before it was sent goes out again under the next attempt's ID. 

1248 attempt = 1 

1249 while ( 

1250 earlier := self._snapshot.orders.get(copy_client_id(key, part, attempt)) 

1251 ) is not None: 

1252 if earlier.status != OrderStatus.ABORTED_BEFORE_SUBMIT or earlier.side != "sell": 1252 ↛ 1253line 1252 didn't jump to line 1253 because the condition on line 1252 was never true

1253 raise RuntimeError("Order intent already exists") 

1254 attempt += 1 

1255 client_id = copy_client_id(key, part, attempt) 

1256 order = OrderRecord( 

1257 **plan.model_dump(), 

1258 client_id=client_id, 

1259 message_id=key, 

1260 instruction_index=part, 

1261 source_key=message.source_key, 

1262 status=OrderStatus.PREPARED, 

1263 filled_qty=ZERO, 

1264 broker_id=None, 

1265 created_at=now, 

1266 day=trade_date(now), 

1267 ) 

1268 parts = list(message.parts) 

1269 parts[part] = OrderLinked(client_id=client_id) 

1270 updated = MessageRecord.model_validate(message.model_dump() | {"parts": parts}) 

1271 state = self._replace( 

1272 messages=self._snapshot.messages | {key: updated}, 

1273 orders=self._snapshot.orders | {client_id: order}, 

1274 ) 

1275 self._commit( 

1276 state, 

1277 JournalEvent( 

1278 at=now, 

1279 payload=OrderPrepared( 

1280 client_id=client_id, 

1281 message_id=key, 

1282 symbol=plan.symbol, 

1283 side=plan.side, 

1284 position_intent=plan.position_intent, 

1285 source_price=plan.source_price, 

1286 entry_price=plan.entry_price, 

1287 qty=plan.qty, 

1288 type=plan.type, 

1289 limit_price=plan.limit_price, 

1290 entry_tolerance_pct=plan.entry_tolerance_pct, 

1291 session=plan.session, 

1292 ), 

1293 ), 

1294 ) 

1295 return order 

1296 

1297 def cancel_requested(self, key: str, reason: CancelReason, now: dt.datetime) -> None: 

1298 """Note that CopyTrading asked Alpaca to cancel the order, and why: the journal keeps the 

1299 reason, and Activity reads it from there.""" 

1300 order = self.order(key) 

1301 self._commit( 

1302 self._snapshot, 

1303 JournalEvent( 

1304 at=now, 

1305 payload=CancelRequested(client_id=key, message_id=order.message_id, reason=reason), 

1306 ), 

1307 ) 

1308 

1309 def _order_state(self, key: str, **changes: Unpack[_OrderChanges]) -> LedgerSnapshot: 

1310 order = OrderRecord.model_validate(self.order(key).model_dump() | changes) 

1311 return self._replace(orders=self._snapshot.orders | {key: order}) 

1312 

1313 def submitting(self, key: str, now: dt.datetime) -> None: 

1314 order = self.order(key) 

1315 if order.status != OrderStatus.PREPARED or order.submit_started_at is not None: 

1316 raise RuntimeError("Only a never-submitted prepared intent can be submitted") 

1317 self._commit( 

1318 self._order_state(key, submit_started_at=now), 

1319 JournalEvent( 

1320 at=now, 

1321 payload=SubmitStarted( 

1322 client_id=key, 

1323 message_id=order.message_id, 

1324 submit_started_at=now, 

1325 ), 

1326 ), 

1327 ) 

1328 

1329 def abort_before_submit(self, key: str, reason: str, now: dt.datetime) -> None: 

1330 order = self.order(key) 

1331 if order.status != "prepared" or order.broker_id is not None or order.filled_qty: 1331 ↛ 1332line 1331 didn't jump to line 1332 because the condition on line 1331 was never true

1332 raise RuntimeError("Only an unsubmitted prepared order can be aborted") 

1333 validate_transition(order.status, OrderStatus.ABORTED_BEFORE_SUBMIT) 

1334 message = self._snapshot.messages.get(order.message_id) 

1335 part = order.instruction_index 

1336 stop_index = None if message is None else part - len(message.instructions) 

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

1338 order.stop_rule is not None 

1339 and message is not None 

1340 and stop_index is not None 

1341 and message.status == "queued" 

1342 and message.stop_parts[stop_index] == OrderLinked(client_id=key) 

1343 ): 

1344 # A stop never placed waits again, and the account places it as it would any stop. 

1345 parts = list(message.stop_parts) 

1346 parts[stop_index] = Pending() 

1347 aborted = OrderRecord.model_validate( 

1348 order.model_dump() | {"status": OrderStatus.ABORTED_BEFORE_SUBMIT} 

1349 ) 

1350 self._commit( 

1351 self._replace( 

1352 orders=self._snapshot.orders | {key: aborted}, 

1353 messages=self._snapshot.messages 

1354 | { 

1355 order.message_id: MessageRecord.model_validate( 

1356 message.model_dump() | {"stop_parts": tuple(parts)} 

1357 ) 

1358 }, 

1359 ), 

1360 JournalEvent( 

1361 at=now, 

1362 payload=SubmissionAborted( 

1363 client_id=key, message_id=order.message_id, reason=reason 

1364 ), 

1365 ), 

1366 ) 

1367 return 

1368 if ( 

1369 order.side == "sell" 

1370 and order.stop_rule is None 

1371 and message is not None 

1372 and message.status == "queued" 

1373 and message.parts[part] == OrderLinked(client_id=key) 

1374 ): 

1375 # A copied sell is never lost (ADR-0010): its call waits again, in the same commit, 

1376 # so a crash here can neither lose it nor send it twice. 

1377 parts = list(message.parts) 

1378 parts[part] = Pending() 

1379 aborted = OrderRecord.model_validate( 

1380 order.model_dump() | {"status": OrderStatus.ABORTED_BEFORE_SUBMIT} 

1381 ) 

1382 self._commit( 

1383 self._replace( 

1384 orders=self._snapshot.orders | {key: aborted}, 

1385 messages=self._snapshot.messages 

1386 | { 

1387 order.message_id: MessageRecord.model_validate( 

1388 message.model_dump() | {"parts": tuple(parts)} 

1389 ) 

1390 }, 

1391 ), 

1392 JournalEvent( 

1393 at=now, 

1394 payload=SendAborted( 

1395 client_id=key, message_id=order.message_id, part=part, reason=reason 

1396 ), 

1397 ), 

1398 ) 

1399 return 

1400 self._commit( 

1401 self._order_state(key, status=OrderStatus.ABORTED_BEFORE_SUBMIT), 

1402 JournalEvent( 

1403 at=now, 

1404 payload=SubmissionAborted( 

1405 client_id=key, message_id=order.message_id, reason=reason 

1406 ), 

1407 ), 

1408 ) 

1409 

1410 def uncertain(self, key: str, now: dt.datetime) -> None: 

1411 order = self.order(key) 

1412 if order.status != OrderStatus.UNCERTAIN: 

1413 validate_transition(order.status, OrderStatus.UNCERTAIN) 

1414 self._commit( 

1415 self._order_state(key, status=OrderStatus.UNCERTAIN), 

1416 JournalEvent( 

1417 at=now, 

1418 payload=SubmissionUncertain(client_id=key, message_id=order.message_id), 

1419 ), 

1420 ) 

1421 

1422 def submission_failed( 

1423 self, key: str, http_status: int | None, now: dt.datetime, reason: str | None = None 

1424 ) -> None: 

1425 status = ( 

1426 OrderStatus.REJECTED if http_status in {400, 401, 403, 422} else OrderStatus.UNCERTAIN 

1427 ) 

1428 validate_transition(self.order(key).status, status) 

1429 self._commit( 

1430 self._order_state(key, status=status), 

1431 JournalEvent( 

1432 at=now, 

1433 payload=SubmitError( 

1434 client_id=key, 

1435 message_id=self.order(key).message_id, 

1436 status=status, 

1437 http_status=http_status, 

1438 reason=reason, 

1439 ), 

1440 ), 

1441 ) 

1442 

1443 def release_uncertain_intent(self, client_id: str, evidence: ReleaseEvidence) -> None: 

1444 """Record an audited release without resubmitting the original instruction.""" 

1445 order = self.order(client_id) 

1446 if order.status != OrderStatus.UNCERTAIN: 

1447 raise ValueError("Only an uncertain order intent can be released") 

1448 if order.filled_qty != ZERO or order.broker_id is not None: 

1449 raise ValueError("An uncertain intent with saved broker activity cannot be released") 

1450 if evidence.submission_state == "started": 

1451 if order.submit_started_at is None: 1451 ↛ 1452line 1451 didn't jump to line 1452 because the condition on line 1451 was never true

1452 raise ValueError("Release evidence claims a submission marker that is absent") 

1453 if evidence.checked_at < order.submit_started_at: 1453 ↛ 1454line 1453 didn't jump to line 1454 because the condition on line 1453 was never true

1454 raise ValueError("Release evidence must follow the attempted submission") 

1455 elif order.submit_started_at is not None: 1455 ↛ 1456line 1455 didn't jump to line 1456 because the condition on line 1455 was never true

1456 raise ValueError("Release evidence says submission never started, but a marker exists") 

1457 elif evidence.checked_at < order.created_at: 1457 ↛ 1458line 1457 didn't jump to line 1458 because the condition on line 1457 was never true

1458 raise ValueError("Release evidence must follow the prepared intent") 

1459 if client_id in self._snapshot.release_evidence: 1459 ↛ 1460line 1459 didn't jump to line 1460 because the condition on line 1459 was never true

1460 raise ValueError("Order intent already has release evidence") 

1461 if self.account_id is None or evidence.account_id != self.account_id: 

1462 raise ValueError("Release evidence belongs to a different account") 

1463 validate_transition(order.status, OrderStatus.RELEASED_UNSUBMITTED) 

1464 released = OrderRecord.model_validate( 

1465 order.model_dump() | {"status": OrderStatus.RELEASED_UNSUBMITTED} 

1466 ) 

1467 state = self._replace( 

1468 orders=self._snapshot.orders | {client_id: released}, 

1469 release_evidence=self._snapshot.release_evidence | {client_id: evidence}, 

1470 ) 

1471 self._commit( 

1472 state, 

1473 JournalEvent( 

1474 at=evidence.checked_at, 

1475 payload=OrderIntentReleased( 

1476 client_id=client_id, 

1477 message_id=order.message_id, 

1478 previous_status="uncertain", 

1479 status="released_unsubmitted", 

1480 evidence=evidence, 

1481 entry_halted=state.entry_halted, 

1482 ), 

1483 ), 

1484 ) 

1485 

1486 def clear_late_order_incident( 

1487 self, client_id: str, evidence: IncidentClearanceEvidence 

1488 ) -> None: 

1489 """Persist operator clearance after a matched position audit.""" 

1490 incident = self._snapshot.late_order_incidents.get(client_id) 

1491 if incident is None: 1491 ↛ 1492line 1491 didn't jump to line 1492 because the condition on line 1491 was never true

1492 raise ValueError("No late-order incident exists for this client ID") 

1493 if incident.cleared: 1493 ↛ 1494line 1493 didn't jump to line 1494 because the condition on line 1493 was never true

1494 raise ValueError("Late-order incident is already cleared") 

1495 order = self.order(client_id) 

1496 if is_pending(order.status): 

1497 raise ValueError("Cannot clear a late-order incident while its order is pending") 

1498 if any(is_pending(self.order(key).status) for key in incident.conflicting_order_ids): 1498 ↛ 1499line 1498 didn't jump to line 1499 because the condition on line 1498 was never true

1499 raise ValueError( 

1500 "Cannot clear a late-order incident while a conflicting order is pending" 

1501 ) 

1502 if self.account_id is None or evidence.account_id != self.account_id: 

1503 raise ValueError("Clearance evidence belongs to a different account") 

1504 if evidence.checked_at < incident.last_observed_at: 1504 ↛ 1505line 1504 didn't jump to line 1505 because the condition on line 1504 was never true

1505 raise ValueError("Clearance requires an audit after the latest broker observation") 

1506 if evidence.symbol is not None and evidence.symbol != incident.symbol: 1506 ↛ 1507line 1506 didn't jump to line 1507 because the condition on line 1506 was never true

1507 raise ValueError("Clearance position evidence does not match the late order symbol") 

1508 if evidence.expected_qty is not None and evidence.expected_qty != self.expected_position( 

1509 incident.symbol 

1510 ): 

1511 raise ValueError("Clearance expected quantity does not match ledger quantity") 

1512 cleared = incident.model_copy( 

1513 update={ 

1514 "clearance_history": (*incident.clearance_history, evidence), 

1515 "cleared": True, 

1516 } 

1517 ) 

1518 state = self._replace( 

1519 late_order_incidents=self._snapshot.late_order_incidents | {client_id: cleared} 

1520 ) 

1521 self._commit( 

1522 state, 

1523 JournalEvent( 

1524 at=evidence.checked_at, 

1525 payload=LateOrderIncidentCleared( 

1526 client_id=client_id, 

1527 message_id=order.message_id, 

1528 broker_id=incident.broker_id, 

1529 order_symbol=incident.symbol, 

1530 evidence=evidence, 

1531 entry_halted=state.entry_halted, 

1532 ), 

1533 ), 

1534 ) 

1535 

1536 def apply_order(self, key: str, update: BrokerOrder, now: dt.datetime) -> None: 

1537 order = self.order(key) 

1538 if update.client_order_id != order.client_id: 1538 ↛ 1539line 1538 didn't jump to line 1539 because the condition on line 1538 was never true

1539 raise RuntimeError("Broker returned an order with a different client ID") 

1540 if (update.symbol, update.side) != (order.symbol, order.side): 

1541 raise RuntimeError("Broker order identity mismatch") 

1542 if update.position_intent is not None and update.position_intent != order.position_intent: 

1543 raise RuntimeError("Broker order position intent mismatch") 

1544 if order.broker_id and update.id != order.broker_id: 1544 ↛ 1545line 1544 didn't jump to line 1545 because the condition on line 1544 was never true

1545 raise RuntimeError("Broker order identity changed") 

1546 if update.qty != order.qty: 1546 ↛ 1547line 1546 didn't jump to line 1547 because the condition on line 1546 was never true

1547 raise RuntimeError("Broker order quantity mismatch") 

1548 status = map_broker_status(update.status) 

1549 validate_transition(order.status, status) 

1550 delta = update.filled_qty - order.filled_qty 

1551 if delta < 0: 

1552 raise RuntimeError("Broker fill quantity is inconsistent with the saved order") 

1553 lots = self._snapshot.lots 

1554 quarantined_fills = self._snapshot.quarantined_fills 

1555 previous_quarantine = quarantined_fills.get(key) 

1556 related_incident_ids = tuple( 

1557 sorted( 

1558 incident_id 

1559 for incident_id, incident in self._snapshot.late_order_incidents.items() 

1560 if not incident.cleared 

1561 and key in incident.conflicting_order_ids 

1562 and order.lot_id is not None 

1563 and self.order(incident_id).lot_id == order.lot_id 

1564 ) 

1565 ) 

1566 if key in self._snapshot.release_evidence: 

1567 related_incident_ids = tuple(sorted((*related_incident_ids, key))) 

1568 if delta: 

1569 average = update.filled_avg_price 

1570 if average is None: 1570 ↛ 1571line 1570 didn't jump to line 1571 because the condition on line 1570 was never true

1571 raise RuntimeError("A fill requires its average price") 

1572 if order.side == "buy": 

1573 if order.limit_price is None: 1573 ↛ 1574line 1573 didn't jump to line 1574 because the condition on line 1573 was never true

1574 raise RuntimeError("Buy order has no saved limit") 

1575 if average > order.limit_price: 

1576 raise RuntimeError("Broker buy fill exceeds the saved limit") 

1577 lot_key = self._entry_lot(lots, key, order) 

1578 lot = lots.get(lot_key) 

1579 entries = (*lot.entries(lot_key), key) if lot is not None else (key,) 

1580 entries = tuple(dict.fromkeys(entries)) 

1581 filled = {entry: self.order(entry) for entry in entries if entry != key} 

1582 # What the buys brought in; a coin's fee on this fill is counted later, from the 

1583 # broker's holding (count_crypto_fee). 

1584 total = ( 

1585 sum((o.received_qty for o in filled.values()), ZERO) 

1586 + update.filled_qty 

1587 - order.fee_qty 

1588 ) 

1589 entry_remaining = dict(lot.entry_remaining) if lot is not None else {} 

1590 entry_prices = dict(lot.entry_prices) if lot is not None else {} 

1591 entry_remaining[key] = entry_remaining.get(key, ZERO) + delta 

1592 entry_prices[key] = order.entry_price 

1593 # Priced from what each buy still holds, this fill at its own average. 

1594 updated_lot = _priced( 

1595 self._snapshot.orders 

1596 | {key: order.model_copy(update={"filled_avg_price": average})}, 

1597 lot_key, 

1598 OwnedLot( 

1599 symbol=order.symbol, 

1600 entry_price=lot.entry_price if lot is not None else order.entry_price, 

1601 source_key=order.source_key, 

1602 original_qty=total, 

1603 remaining_qty=(lot.remaining_qty if lot else ZERO) + delta, 

1604 average_price=average, 

1605 joined_entries=entries[1:], 

1606 entry_remaining=entry_remaining, 

1607 entry_prices=entry_prices, 

1608 ), 

1609 ) 

1610 lots = lots | {lot_key: updated_lot} 

1611 else: 

1612 if order.lot_id is None: 1612 ↛ 1613line 1612 didn't jump to line 1613 because the condition on line 1612 was never true

1613 raise RuntimeError("Sell order has no owned lot") 

1614 lot = lots[order.lot_id] 

1615 # A sell of named buys can take only what those buys hold; any more is set aside. 

1616 held = ( 

1617 lot.remaining_of(order.from_entries) 

1618 if order.from_entries 

1619 else lot.remaining_qty 

1620 ) 

1621 applied_delta = min(delta, held) 

1622 unapplied_delta = delta - applied_delta 

1623 if unapplied_delta and not related_incident_ids: 1623 ↛ 1624line 1623 didn't jump to line 1624 because the condition on line 1623 was never true

1624 raise RuntimeError("Sell fill exceeds the copier's owned lot") 

1625 if applied_delta: 

1626 # Taken from the buys the sell named, in proportion to what each has left. 

1627 lots = lots | { 

1628 order.lot_id: _priced( 

1629 self._snapshot.orders, 

1630 order.lot_id, 

1631 lot.reduced(applied_delta, order.from_entries or None), 

1632 ) 

1633 } 

1634 if previous_quarantine is not None or unapplied_delta: 

1635 incident_client_ids = tuple( 

1636 sorted( 

1637 set( 

1638 previous_quarantine.incident_client_ids 

1639 if previous_quarantine is not None 

1640 else () 

1641 ) 

1642 | set(related_incident_ids) 

1643 ) 

1644 ) 

1645 quarantined_fills = quarantined_fills | { 

1646 key: QuarantinedFill( 

1647 client_id=key, 

1648 broker_id=update.id, 

1649 lot_id=order.lot_id, 

1650 symbol=order.symbol, 

1651 observed_filled_qty=update.filled_qty, 

1652 applied_filled_qty=( 

1653 previous_quarantine.applied_filled_qty 

1654 if previous_quarantine is not None 

1655 else order.filled_qty 

1656 ) 

1657 + applied_delta, 

1658 unapplied_qty=( 

1659 previous_quarantine.unapplied_qty 

1660 if previous_quarantine is not None 

1661 else ZERO 

1662 ) 

1663 + unapplied_delta, 

1664 average_price=average, 

1665 first_observed_at=( 

1666 previous_quarantine.first_observed_at 

1667 if previous_quarantine is not None 

1668 else now 

1669 ), 

1670 last_observed_at=now, 

1671 incident_client_ids=incident_client_ids, 

1672 ) 

1673 } 

1674 status_changed = order.status != status 

1675 raw_status_changed = order.raw_broker_status != update.status 

1676 order_changed = ( 

1677 delta or status_changed or raw_status_changed or order.broker_id != update.id 

1678 ) 

1679 if order_changed: 

1680 if previous_quarantine is not None and not delta: 1680 ↛ 1681line 1680 didn't jump to line 1681 because the condition on line 1680 was never true

1681 average = update.filled_avg_price 

1682 if average is None: 

1683 raise RuntimeError("A quarantined fill requires its average price") 

1684 quarantined_fills = quarantined_fills | { 

1685 key: previous_quarantine.model_copy( 

1686 update={"average_price": average, "last_observed_at": now} 

1687 ) 

1688 } 

1689 updated_order = OrderRecord.model_validate( 

1690 order.model_dump() 

1691 | { 

1692 "status": status, 

1693 "filled_qty": update.filled_qty, 

1694 "broker_id": update.id, 

1695 "raw_broker_status": update.status, 

1696 "filled_avg_price": update.filled_avg_price or order.filled_avg_price, 

1697 # The order's timeout runs from when Alpaca first had it live on the market. 

1698 "accepted_at": order.accepted_at or (now if status in LIVE_AT_BROKER else None), 

1699 } 

1700 ) 

1701 incidents = self._snapshot.late_order_incidents 

1702 previous_incident = incidents.get(key) 

1703 newly_observed_late = ( 

1704 order.status == OrderStatus.RELEASED_UNSUBMITTED 

1705 and key in self._snapshot.release_evidence 

1706 ) 

1707 reopened = bool(previous_incident and previous_incident.cleared) 

1708 if newly_observed_late: 

1709 conflicting_order_ids = tuple( 

1710 sorted( 

1711 candidate.client_id 

1712 for candidate in self._snapshot.orders.values() 

1713 if candidate.client_id != key 

1714 and candidate.side == "sell" 

1715 and candidate.lot_id == order.lot_id 

1716 and candidate.created_at <= now 

1717 and (candidate.pending or candidate.filled_qty > ZERO) 

1718 ) 

1719 ) 

1720 incidents = incidents | { 

1721 key: LateOrderIncident( 

1722 client_id=key, 

1723 broker_id=update.id, 

1724 symbol=update.symbol, 

1725 side=update.side, 

1726 first_observed_at=now, 

1727 last_observed_at=now, 

1728 latest_status=status, 

1729 raw_broker_status=update.status, 

1730 latest_filled_qty=update.filled_qty, 

1731 conflicting_order_ids=conflicting_order_ids, 

1732 ) 

1733 } 

1734 for conflicting_id in conflicting_order_ids: 

1735 conflicting_fill = quarantined_fills.get(conflicting_id) 

1736 if conflicting_fill is not None: 1736 ↛ 1737line 1736 didn't jump to line 1737 because the condition on line 1736 was never true

1737 quarantined_fills = quarantined_fills | { 

1738 conflicting_id: conflicting_fill.model_copy( 

1739 update={ 

1740 "incident_client_ids": tuple( 

1741 sorted(set(conflicting_fill.incident_client_ids) | {key}) 

1742 ) 

1743 } 

1744 ) 

1745 } 

1746 elif previous_incident is not None: 

1747 incidents = incidents | { 

1748 key: previous_incident.model_copy( 

1749 update={ 

1750 "last_observed_at": now, 

1751 "latest_status": status, 

1752 "raw_broker_status": update.status, 

1753 "latest_filled_qty": update.filled_qty, 

1754 "cleared": False if reopened else previous_incident.cleared, 

1755 } 

1756 ) 

1757 } 

1758 state = self._replace( 

1759 orders=self._snapshot.orders | {key: updated_order}, 

1760 lots=lots, 

1761 late_order_incidents=incidents, 

1762 quarantined_fills=quarantined_fills, 

1763 ) 

1764 quarantine = quarantined_fills.get(key) 

1765 event_incident = incidents.get(key) 

1766 if quarantine is not None: 

1767 applied_fill_qty = quarantine.applied_filled_qty 

1768 unapplied_fill_qty = quarantine.unapplied_qty 

1769 incident_ids = quarantine.incident_client_ids 

1770 elif event_incident is not None: 

1771 applied_fill_qty = update.filled_qty 

1772 unapplied_fill_qty = ZERO 

1773 incident_ids = None 

1774 else: 

1775 applied_fill_qty = None 

1776 unapplied_fill_qty = None 

1777 incident_ids = None 

1778 if newly_observed_late: 

1779 if event_incident is None: 1779 ↛ 1780line 1779 didn't jump to line 1780 because the condition on line 1779 was never true

1780 raise RuntimeError("New late-order incident was not persisted in state") 

1781 payload = LateOrderIncidentOpened( 

1782 client_id=key, 

1783 message_id=order.message_id, 

1784 status=status, 

1785 raw_broker_status=update.status, 

1786 filled_qty=update.filled_qty, 

1787 filled_avg_price=update.filled_avg_price, 

1788 applied_fill_qty=applied_fill_qty, 

1789 unapplied_fill_qty=unapplied_fill_qty, 

1790 late_order_incident_ids=incident_ids, 

1791 entry_halted=state.entry_halted, 

1792 late_order_incident=event_incident, 

1793 ) 

1794 elif reopened: 

1795 if event_incident is None: 1795 ↛ 1796line 1795 didn't jump to line 1796 because the condition on line 1795 was never true

1796 raise RuntimeError("Reopened late-order incident was not persisted in state") 

1797 payload = LateOrderIncidentReopened( 

1798 client_id=key, 

1799 message_id=order.message_id, 

1800 status=status, 

1801 raw_broker_status=update.status, 

1802 filled_qty=update.filled_qty, 

1803 filled_avg_price=update.filled_avg_price, 

1804 applied_fill_qty=applied_fill_qty, 

1805 unapplied_fill_qty=unapplied_fill_qty, 

1806 late_order_incident_ids=incident_ids, 

1807 entry_halted=state.entry_halted, 

1808 late_order_incident=event_incident, 

1809 ) 

1810 else: 

1811 payload = OrderUpdate( 

1812 client_id=key, 

1813 message_id=order.message_id, 

1814 status=status, 

1815 raw_broker_status=update.status, 

1816 filled_qty=update.filled_qty, 

1817 filled_avg_price=update.filled_avg_price, 

1818 applied_fill_qty=applied_fill_qty, 

1819 unapplied_fill_qty=unapplied_fill_qty, 

1820 late_order_incident_ids=incident_ids, 

1821 entry_halted=state.entry_halted, 

1822 late_order_incident=event_incident, 

1823 ) 

1824 self._commit( 

1825 state, 

1826 JournalEvent(at=now, payload=payload), 

1827 ) 

1828 

1829 def count_crypto_fee(self, symbol: str, shortfall: Decimal, now: dt.datetime) -> bool: 

1830 """Count Alpaca's fee on a coin's latest buys from its holding: `shortfall` is how far the 

1831 holding, read while nothing of the coin was filling, is under its lots. Alpaca takes the 

1832 fee in the coin bought and reports it only at the day's end (ADR-0014). 

1833 

1834 Only a shortfall a fee can be, from none to `CRYPTO_FEE_CEILING` of what the buys filled, 

1835 is counted; any other difference is the owner's, or a fill not yet in the holding, which 

1836 the holdings check (ADR-0011) and the next sync settle. Returns whether it counted.""" 

1837 buys = sorted( 

1838 ( 

1839 order 

1840 for order in self._snapshot.orders.values() 

1841 if order.symbol == symbol and order.unsettled_fee_qty 

1842 ), 

1843 key=lambda order: (order.created_at, order.client_id), 

1844 ) 

1845 filled = sum((order.unsettled_fee_qty for order in buys), ZERO) 

1846 if not buys or shortfall < 0 or shortfall > filled * CRYPTO_FEE_CEILING: 

1847 return False 

1848 # Each buy pays in proportion to what it filled; the rounding remainder is the oldest's. 

1849 fees = { 

1850 order.client_id: (shortfall * order.unsettled_fee_qty / filled).quantize( 

1851 COIN_STEP, rounding=ROUND_DOWN 

1852 ) 

1853 for order in buys 

1854 } 

1855 fees[buys[0].client_id] += shortfall - sum(fees.values(), ZERO) 

1856 orders = dict(self._snapshot.orders) 

1857 lots = dict(self._snapshot.lots) 

1858 for order in buys: 

1859 fee = fees[order.client_id] 

1860 orders[order.client_id] = OrderRecord.model_validate( 

1861 order.model_dump() 

1862 | {"fee_qty": order.fee_qty + fee, "fee_settled_qty": order.filled_qty} 

1863 ) 

1864 if not fee: 1864 ↛ 1865line 1864 didn't jump to line 1865 because the condition on line 1864 was never true

1865 continue 

1866 lot_key = next(key for key, lot in lots.items() if order.client_id in lot.entries(key)) 

1867 lot = lots[lot_key] 

1868 # The coin never arrived: it leaves the buy that paid it, or, when that buy has been 

1869 # sold down since, the lot's other buys, oldest first. 

1870 remaining = dict(lot.entry_remaining) 

1871 owed = fee 

1872 for entry in (order.client_id, *(e for e in remaining if e != order.client_id)): 

1873 taken = min(owed, remaining[entry]) 

1874 remaining[entry] -= taken 

1875 owed -= taken 

1876 if owed: 1876 ↛ 1877line 1876 didn't jump to line 1877 because the condition on line 1876 was never true

1877 raise RuntimeError("A coin's fee exceeds what its lot holds") 

1878 lots[lot_key] = OwnedLot.model_validate( 

1879 lot.model_dump() 

1880 | { 

1881 "original_qty": lot.original_qty - fee, 

1882 "remaining_qty": lot.remaining_qty - fee, 

1883 "entry_remaining": remaining, 

1884 } 

1885 ) 

1886 self._commit( 

1887 self._replace(orders=orders, lots=lots), 

1888 JournalEvent( 

1889 at=now, 

1890 payload=CryptoFeeCounted(symbol=symbol, fees=fees, filled_qty=filled), 

1891 ), 

1892 ) 

1893 return True