532 lines
19 KiB
Python
532 lines
19 KiB
Python
"""Execution loop ledger-hook tests (REQ-018, REQ-019, dcy-004).
|
|
|
|
Exercises the full buy/sell lifecycle with the in-memory paper broker and
|
|
in-memory outbox + ledger writer, ensuring the slot transition is on the
|
|
critical path while the ledger write is eventually-consistent.
|
|
"""
|
|
from __future__ import annotations
|
|
|
|
from datetime import UTC, datetime
|
|
|
|
from trex_core.adapters.broker.kis import KISBroker
|
|
from trex_core.adapters.broker.paper import PaperBroker
|
|
from trex_core.adapters.ledger.in_memory import InMemoryLedger
|
|
from trex_core.adapters.messaging.in_memory import InMemoryTransport
|
|
from trex_core.adapters.persistence.in_memory_intent_store import InMemoryIntentStore
|
|
from trex_core.application.alarm_emitter import AlarmEmitter
|
|
from trex_core.application.broker_port import FillStatus
|
|
from trex_core.application.execution import ExecutionService
|
|
from trex_core.application.intents import BuyIntent, IntentService, SellIntent
|
|
from trex_core.application.ledger_outbox import (
|
|
InMemoryLedgerOutbox,
|
|
LedgerWriter,
|
|
OutboxOutcome,
|
|
WorkItemStatus,
|
|
)
|
|
from trex_core.application.ledger_skip import LedgerSkipRecord
|
|
from trex_core.domain.slot import SlotService, SlotState
|
|
from trex_core.domain.slot.in_memory_repository import InMemorySlotRepository
|
|
|
|
|
|
class _SkipStore:
|
|
def __init__(self):
|
|
self.records = []
|
|
self._by_key = {}
|
|
|
|
def record_skip(self, **kwargs):
|
|
record = LedgerSkipRecord(
|
|
skip_key=f"{kwargs['slot_id']}:{kwargs['side']}:{kwargs['skip_reason']}",
|
|
instance_key=kwargs["instance_key"],
|
|
slot_id=kwargs["slot_id"],
|
|
portfolio_id=kwargs["portfolio_id"],
|
|
symbol=kwargs["symbol"],
|
|
order_id=kwargs["order_id"],
|
|
execution_id=kwargs["execution_id"],
|
|
side=kwargs["side"],
|
|
qty=kwargs["qty"],
|
|
price=kwargs["price"],
|
|
executed_at=kwargs["executed_at"],
|
|
order_venue=kwargs["order_venue"],
|
|
execution_venue=kwargs["execution_venue"],
|
|
skip_reason=kwargs["skip_reason"],
|
|
status="unresolved",
|
|
resolution_reason=None,
|
|
resolved_at=None,
|
|
created_at=kwargs["executed_at"],
|
|
updated_at=kwargs["executed_at"],
|
|
)
|
|
should_notify = record.skip_key not in self._by_key
|
|
self._by_key[record.skip_key] = record
|
|
self.records = list(self._by_key.values())
|
|
return record, should_notify
|
|
|
|
def resolve_for_fill(self, **_kwargs):
|
|
return []
|
|
|
|
def resolve_for_delivery(
|
|
self,
|
|
*,
|
|
instance_key,
|
|
portfolio_id,
|
|
side,
|
|
order_id,
|
|
execution_id,
|
|
resolution_reason,
|
|
):
|
|
resolved = []
|
|
updated = {}
|
|
for key, record in self._by_key.items():
|
|
if (
|
|
record.instance_key == instance_key
|
|
and record.portfolio_id == portfolio_id
|
|
and record.side == side
|
|
and (
|
|
record.execution_id == execution_id
|
|
or (record.execution_id is None and record.order_id == order_id)
|
|
)
|
|
):
|
|
record = LedgerSkipRecord(
|
|
skip_key=record.skip_key,
|
|
instance_key=record.instance_key,
|
|
slot_id=record.slot_id,
|
|
portfolio_id=record.portfolio_id,
|
|
symbol=record.symbol,
|
|
order_id=record.order_id,
|
|
execution_id=record.execution_id or execution_id,
|
|
side=record.side,
|
|
qty=record.qty,
|
|
price=record.price,
|
|
executed_at=record.executed_at,
|
|
order_venue=record.order_venue,
|
|
execution_venue=record.execution_venue,
|
|
skip_reason=record.skip_reason,
|
|
status="resolved",
|
|
resolution_reason=resolution_reason,
|
|
resolved_at=record.executed_at,
|
|
created_at=record.created_at,
|
|
updated_at=record.executed_at,
|
|
)
|
|
resolved.append(record)
|
|
updated[key] = record
|
|
self._by_key = updated
|
|
self.records = list(self._by_key.values())
|
|
return resolved
|
|
|
|
|
|
|
|
def _wire(broker, *, ledger=None, clock=None, alarm_emitter=None, ledger_skip_store=None):
|
|
repo = InMemorySlotRepository()
|
|
svc = SlotService(repo)
|
|
intents = IntentService(svc, repo, InMemoryIntentStore(),
|
|
resolve_symbol=lambda pid: "005930")
|
|
outbox = (
|
|
InMemoryLedgerOutbox(clock=clock, instance_key="default")
|
|
if clock
|
|
else InMemoryLedgerOutbox(instance_key="default")
|
|
)
|
|
execution = ExecutionService(
|
|
svc,
|
|
repo,
|
|
broker,
|
|
ledger_outbox=outbox,
|
|
alarm_emitter=alarm_emitter,
|
|
ledger_skip_store=ledger_skip_store,
|
|
)
|
|
writer = LedgerWriter(
|
|
outbox,
|
|
ledger or InMemoryLedger(),
|
|
clock=clock,
|
|
alarm_emitter=alarm_emitter,
|
|
ledger_skip_store=ledger_skip_store,
|
|
instance_key="default",
|
|
)
|
|
repo.reconcile_universe("default", {"PF-1": "SYM"})
|
|
return repo, svc, intents, execution, outbox, writer
|
|
|
|
|
|
def _buy(intents, *, iid="b1", portfolio_id="PF-1"):
|
|
return intents.submit_buy(BuyIntent(
|
|
intent_id=iid, qty=10, entry_price=1000,
|
|
portfolio_id=portfolio_id,
|
|
))
|
|
|
|
|
|
class KisSorUnknownVenueBroker(PaperBroker):
|
|
"""KIS daily-ccld fixture with SOR routing but no actual exchange evidence."""
|
|
|
|
def poll_fill(self, broker_order_id, *, side, symbol, **kwargs):
|
|
return KISBroker._fill_status_from_row(
|
|
{
|
|
"ord_qty": "10",
|
|
"tot_ccld_qty": "10",
|
|
"avg_prvs": "1000",
|
|
"ord_dt": "20260824",
|
|
"ord_gno_brno": "12345678",
|
|
"odno": broker_order_id,
|
|
"excg_id_dvsn_cd": "SOR",
|
|
},
|
|
side=side,
|
|
today="20260824",
|
|
fallback_odno=broker_order_id,
|
|
)
|
|
|
|
|
|
class MissingExecutionIdBroker(PaperBroker):
|
|
def poll_fill(self, broker_order_id, *, side, symbol, **kwargs):
|
|
return FillStatus(
|
|
state="filled",
|
|
filled_qty=10,
|
|
avg_price=1000,
|
|
execution_venue="KRX",
|
|
)
|
|
|
|
|
|
def test_buy_fill_enqueues_one_ledger_item_and_writer_records_it():
|
|
ledger = InMemoryLedger()
|
|
repo, _, intents, execution, _, writer = _wire(
|
|
PaperBroker(fill_after_polls=0),
|
|
ledger=ledger,
|
|
)
|
|
sid = _buy(intents).slot_id
|
|
r = execution.run_once()
|
|
assert r.filled == 1 and r.ledger_enqueued == 1
|
|
assert repo.fetch_slot(sid).status is SlotState.HOLDING
|
|
stats = writer.run_once()
|
|
assert stats.completed == 1
|
|
assert ledger.count() == 1
|
|
t = ledger.trades()[0]
|
|
assert (t.asset_id, t.side, t.qty, t.price) == ("PF-1", "buy", 10, 1000.0)
|
|
assert t.execution_id.startswith("paper:PAPER-")
|
|
assert t.fee > 0.0 and t.tax == 0.0
|
|
assert t.order_venue == "SOR"
|
|
assert t.venue == "KRX" # paper's deterministic SOR execution exchange
|
|
|
|
|
|
def test_kis_sor_fill_without_actual_venue_enqueues_and_writes_once() -> None:
|
|
"""Issues #65/#66: SOR provenance must not suppress an unknown actual venue fill."""
|
|
ledger = InMemoryLedger()
|
|
repo, _, intents, execution, outbox, writer = _wire(KisSorUnknownVenueBroker(), ledger=ledger)
|
|
|
|
sid = _buy(intents, iid="sor-unknown").slot_id
|
|
result = execution.run_once()
|
|
|
|
assert result.filled == 1
|
|
assert result.ledger_enqueued == 1
|
|
assert result.ledger_skipped == 0
|
|
assert repo.fetch_slot(sid).status is SlotState.HOLDING
|
|
[item] = outbox.all_items()
|
|
assert item.trade.venue is None
|
|
assert item.trade.order_venue == "SOR"
|
|
|
|
assert writer.run_once().completed == 1
|
|
assert ledger.count() == 1
|
|
[trade] = ledger.trades()
|
|
assert trade.execution_id == item.trade.execution_id
|
|
assert trade.venue is None
|
|
assert trade.order_venue == "SOR"
|
|
|
|
# Replay remains idempotent at the durable outbox and portfolio ledger boundaries.
|
|
outbox.enqueue(item.trade)
|
|
assert len(outbox.all_items()) == 1
|
|
assert writer.run_once().completed == 0
|
|
assert ledger.count() == 1
|
|
|
|
|
|
def test_sell_fill_enqueues_sell_ledger_item():
|
|
ledger = InMemoryLedger()
|
|
repo, _, intents, execution, _, writer = _wire(
|
|
PaperBroker(fill_after_polls=0),
|
|
ledger=ledger,
|
|
)
|
|
sid = _buy(intents).slot_id
|
|
execution.run_once() # -> holding + buy ledger item
|
|
writer.run_once() # drain buy
|
|
intents.submit_sell(SellIntent(intent_id="s1", slot_id=sid))
|
|
r = execution.run_once() # dispatch sell + fill -> closed + sell ledger item
|
|
assert r.ledger_enqueued == 1
|
|
assert repo.fetch_slot(sid).status is SlotState.INACTIVE
|
|
writer.run_once()
|
|
sides = [t.side for t in ledger.trades()]
|
|
assert sides == ["buy", "sell"]
|
|
|
|
|
|
def test_portfolio_id_absent_skips_ledger_but_transitions_slot():
|
|
ledger = InMemoryLedger()
|
|
repo, svc, _, execution, outbox, _ = _wire(
|
|
PaperBroker(fill_after_polls=0),
|
|
ledger=ledger,
|
|
)
|
|
# dcy-011: buy admission now requires portfolio_id, so create the
|
|
# pending_buy slot directly (bypass admission) to exercise the
|
|
# execution-loop ledger skip + visibility (REQ-018 FR-4).
|
|
from uuid import uuid4
|
|
|
|
from trex_core.domain.slot.models import Slot
|
|
anon = Slot(slot_id=uuid4(), status=SlotState.INACTIVE)
|
|
repo.add_slot(anon)
|
|
svc.transit_slot(anon.slot_id, SlotState.INACTIVE, SlotState.PENDING_BUY,
|
|
reason="buy", actor="test", symbol="005930", portfolio_id=None)
|
|
sid = anon.slot_id
|
|
r = execution.run_once()
|
|
assert r.filled == 1 and r.ledger_enqueued == 0 and r.ledger_skipped == 1
|
|
assert repo.fetch_slot(sid).status is SlotState.HOLDING
|
|
assert outbox.all_items() == []
|
|
assert ledger.count() == 0
|
|
|
|
|
|
def test_missing_execution_id_still_skips_malformed_ledger_work_item() -> None:
|
|
repo, _, intents, execution, outbox, _ = _wire(MissingExecutionIdBroker())
|
|
|
|
sid = _buy(intents, iid="missing-execution-id").slot_id
|
|
assert sid is not None
|
|
result = execution.run_once()
|
|
|
|
assert result.filled == 1
|
|
assert result.ledger_enqueued == 0
|
|
assert result.ledger_skipped == 1
|
|
assert repo.fetch_slot(sid).status is SlotState.HOLDING
|
|
assert outbox.all_items() == []
|
|
|
|
|
|
def test_missing_portfolio_id_persists_skip_and_emits_alert() -> None:
|
|
transport = InMemoryTransport()
|
|
skip_store = _SkipStore()
|
|
repo, svc, _, execution, outbox, _ = _wire(
|
|
PaperBroker(fill_after_polls=0),
|
|
alarm_emitter=AlarmEmitter(transport),
|
|
ledger_skip_store=skip_store,
|
|
)
|
|
from uuid import uuid4
|
|
|
|
from trex_core.domain.slot.models import Slot
|
|
|
|
anon = Slot(slot_id=uuid4(), status=SlotState.INACTIVE)
|
|
repo.add_slot(anon)
|
|
svc.transit_slot(
|
|
anon.slot_id,
|
|
SlotState.INACTIVE,
|
|
SlotState.PENDING_BUY,
|
|
reason="buy",
|
|
actor="test",
|
|
symbol="005930",
|
|
portfolio_id=None,
|
|
)
|
|
|
|
result = execution.run_once()
|
|
|
|
assert result.ledger_skipped == 1
|
|
assert outbox.all_items() == []
|
|
assert len(skip_store.records) == 1
|
|
record = skip_store.records[0]
|
|
assert record.skip_reason == "missing_portfolio_id"
|
|
assert record.order_venue == "KRX"
|
|
alarms = transport.alarm_events()
|
|
assert len(alarms) == 1
|
|
_, payload = alarms[0]
|
|
assert payload["code"] == "ledger_skip_unresolved"
|
|
assert payload["fields"]["skip_reason"] == "missing_portfolio_id"
|
|
|
|
|
|
def test_missing_execution_id_persists_skip_record() -> None:
|
|
transport = InMemoryTransport()
|
|
skip_store = _SkipStore()
|
|
repo, _, intents, execution, outbox, _ = _wire(
|
|
MissingExecutionIdBroker(),
|
|
alarm_emitter=AlarmEmitter(transport),
|
|
ledger_skip_store=skip_store,
|
|
)
|
|
|
|
sid = _buy(intents, iid="missing-execution-id").slot_id
|
|
assert sid is not None
|
|
result = execution.run_once()
|
|
|
|
assert result.ledger_skipped == 1
|
|
assert result.ledger_enqueued == 0
|
|
assert repo.fetch_slot(sid).status is SlotState.HOLDING
|
|
assert outbox.all_items() == []
|
|
assert len(skip_store.records) == 1
|
|
record = skip_store.records[0]
|
|
assert record.skip_reason == "missing_execution_id"
|
|
assert record.portfolio_id == "PF-1"
|
|
assert record.execution_id is None
|
|
|
|
|
|
def test_skip_resolves_only_after_writer_completes_delivery() -> None:
|
|
transport = InMemoryTransport()
|
|
skip_store = _SkipStore()
|
|
ledger = InMemoryLedger()
|
|
_repo, _, intents, execution, outbox, writer = _wire(
|
|
PaperBroker(fill_after_polls=0),
|
|
ledger=ledger,
|
|
alarm_emitter=AlarmEmitter(transport),
|
|
ledger_skip_store=skip_store,
|
|
)
|
|
sid = _buy(intents, iid="delayed-skip-resolution").slot_id
|
|
record, _ = skip_store.record_skip(
|
|
instance_key="default",
|
|
slot_id=sid,
|
|
portfolio_id="PF-1",
|
|
symbol="005930",
|
|
order_id="PAPER-000001",
|
|
execution_id=None,
|
|
side="buy",
|
|
qty=10.0,
|
|
price=1000.0,
|
|
executed_at=datetime(2026, 8, 24, 0, 0, tzinfo=UTC),
|
|
order_venue="SOR",
|
|
execution_venue="unknown",
|
|
skip_reason="missing_execution_id",
|
|
)
|
|
|
|
result = execution.run_once()
|
|
|
|
assert result.ledger_enqueued == 1
|
|
assert outbox.all_items()
|
|
assert skip_store._by_key[record.skip_key].status == "unresolved"
|
|
assert transport.alarm_events() == []
|
|
|
|
stats = writer.run_once()
|
|
|
|
assert stats.completed == 1
|
|
resolved = skip_store._by_key[record.skip_key]
|
|
assert resolved.status == "resolved"
|
|
assert resolved.execution_id is not None
|
|
assert resolved.resolution_reason == "ledger_recorded"
|
|
assert [payload["code"] for _, payload in transport.alarm_events()] == ["ledger_skip_resolved"]
|
|
|
|
|
|
def test_ledger_skip_emits_warning(caplog):
|
|
"""dcy-011 / REQ-018 FR-4 (S-3): ledger skip is logged, not silent."""
|
|
import logging
|
|
ledger = InMemoryLedger()
|
|
repo, svc, _, execution, _, _ = _wire(
|
|
PaperBroker(fill_after_polls=0),
|
|
ledger=ledger,
|
|
)
|
|
from uuid import uuid4
|
|
|
|
from trex_core.domain.slot.models import Slot
|
|
anon = Slot(slot_id=uuid4(), status=SlotState.INACTIVE)
|
|
repo.add_slot(anon)
|
|
svc.transit_slot(anon.slot_id, SlotState.INACTIVE, SlotState.PENDING_BUY,
|
|
reason="buy", actor="test", symbol="005930", portfolio_id=None)
|
|
with caplog.at_level(logging.WARNING, logger="trex_core.application.execution"):
|
|
execution.run_once()
|
|
msgs = [r.getMessage() for r in caplog.records]
|
|
assert any("ledger skip" in m and "missing_portfolio_id" in m for m in msgs)
|
|
|
|
|
|
def test_duplicate_execution_id_results_in_zero_duplicate_in_ledger():
|
|
"""REQ-019 AC-1: same execution_id processed twice = 1 ledger entry."""
|
|
ledger = InMemoryLedger()
|
|
_, _, intents, execution, outbox, writer = _wire(
|
|
PaperBroker(fill_after_polls=0),
|
|
ledger=ledger,
|
|
)
|
|
_buy(intents)
|
|
execution.run_once()
|
|
writer.run_once()
|
|
assert ledger.count() == 1
|
|
# Same correlation_id arriving again (re-enqueue) is dedup'd at the outbox.
|
|
first = outbox.all_items()[0]
|
|
outbox.enqueue(first.trade)
|
|
assert len(outbox.all_items()) == 1
|
|
# And even if the writer somehow re-processes (simulated by a fresh outbox
|
|
# row for the same execution_id, e.g. after a manual replay), the ledger
|
|
# adapter dedup'd it server-side and the outcome is duplicate_completed.
|
|
replay_outbox = InMemoryLedgerOutbox(instance_key="test-instance")
|
|
replay_writer = LedgerWriter(replay_outbox, ledger)
|
|
replay_outbox.enqueue(first.trade)
|
|
stats = replay_writer.run_once()
|
|
assert stats.duplicates == 1 and stats.completed == 0
|
|
assert ledger.count() == 1 # no duplicate in the ledger
|
|
|
|
|
|
def test_retryable_failure_then_eventually_completes():
|
|
"""REQ-019 AC-2: retry until completed; slot transition unaffected.
|
|
|
|
dcy-015: retryable rows back off, so advance a shared clock past each
|
|
next_retry_at between writer passes.
|
|
"""
|
|
from datetime import datetime, timedelta
|
|
now = {"t": datetime(2026, 6, 4, tzinfo=UTC)}
|
|
ledger = InMemoryLedger(fail_n_then_succeed=2)
|
|
repo, _, intents, execution, outbox, writer = _wire(
|
|
PaperBroker(fill_after_polls=0), ledger=ledger, clock=lambda: now["t"],
|
|
)
|
|
sid = _buy(intents).slot_id
|
|
execution.run_once()
|
|
assert repo.fetch_slot(sid).status is SlotState.HOLDING # slot already transitioned
|
|
stats1 = writer.run_once()
|
|
assert stats1.retryable == 1 and stats1.completed == 0 and ledger.count() == 0
|
|
now["t"] += timedelta(seconds=600) # past backoff
|
|
stats2 = writer.run_once()
|
|
assert stats2.retryable == 1 and ledger.count() == 0
|
|
now["t"] += timedelta(seconds=600) # past backoff again
|
|
stats3 = writer.run_once()
|
|
assert stats3.completed == 1 and ledger.count() == 1
|
|
# outbox row terminal-completed
|
|
[item] = outbox.all_items()
|
|
assert item.status is WorkItemStatus.COMPLETED
|
|
assert item.last_outcome is OutboxOutcome.COMPLETED
|
|
|
|
|
|
def test_conflict_blocks_without_auto_retry():
|
|
"""REQ-019 AC-3: 409 conflict halts auto-retry."""
|
|
# The execution_id paper synthesizes is paper:{oid}:{qty}; first dispatched
|
|
# order id is PAPER-000001 / qty=10 => execution_id = paper:PAPER-000001:10.
|
|
conflict_id = "paper:PAPER-000001:10"
|
|
ledger = InMemoryLedger(conflict_executions={conflict_id})
|
|
_, _, intents, execution, outbox, writer = _wire(
|
|
PaperBroker(fill_after_polls=0),
|
|
ledger=ledger,
|
|
)
|
|
_buy(intents)
|
|
execution.run_once()
|
|
stats = writer.run_once()
|
|
assert stats.conflicts == 1
|
|
[item] = outbox.all_items()
|
|
assert item.status is WorkItemStatus.CONFLICT_BLOCKED
|
|
# second writer tick must NOT call the adapter again
|
|
stats2 = writer.run_once()
|
|
assert stats2.completed == 0 and stats2.retryable == 0
|
|
# ledger is still empty (conflict blocked; operator resolves)
|
|
assert ledger.count() == 0
|
|
|
|
|
|
def test_duplicate_completed_when_reprocessing_terminal_item():
|
|
"""REQ-019 AC-4: a completed item reports duplicate_completed if re-listed."""
|
|
ledger = InMemoryLedger()
|
|
_, _, intents, execution, outbox, writer = _wire(
|
|
PaperBroker(fill_after_polls=0),
|
|
ledger=ledger,
|
|
)
|
|
_buy(intents)
|
|
execution.run_once()
|
|
writer.run_once()
|
|
# Force a duplicate enqueue of the same trade — outbox keeps single row,
|
|
# ledger keeps single entry.
|
|
[item] = outbox.all_items()
|
|
outbox.enqueue(item.trade)
|
|
assert len(outbox.all_items()) == 1
|
|
# Writer sees no PENDING rows now; stats are all zero (terminal).
|
|
stats = writer.run_once()
|
|
assert stats.completed == 0 and stats.duplicates == 0 and stats.retryable == 0
|
|
assert ledger.count() == 1
|
|
|
|
|
|
def test_slot_transition_proceeds_when_ledger_is_down():
|
|
"""REQ-019 AC-5: portfolio-hub outage does not block the fill transition."""
|
|
ledger = InMemoryLedger(fail_n_then_succeed=100)
|
|
repo, _, intents, execution, outbox, writer = _wire(
|
|
PaperBroker(fill_after_polls=0),
|
|
ledger=ledger,
|
|
)
|
|
sid = _buy(intents).slot_id
|
|
execution.run_once()
|
|
assert repo.fetch_slot(sid).status is SlotState.HOLDING
|
|
writer.run_once() # all retries fail
|
|
assert ledger.count() == 0
|
|
[item] = outbox.all_items()
|
|
assert item.status is WorkItemStatus.PENDING # still waiting for retry
|