Skip to content

"Vibe-Trading: Your Personal Trading Agent"

feat(paper-trade): bar-agnostic order lifecycle state machine (#1938 phase 1) (#2066)

Zigen Hand01ea7625d3c
diff --git a/agent/src/tools/paper_trade/order_lifecycle.py b/agent/src/tools/paper_trade/order_lifecycle.py
new file mode 100644
index 000000000..56b3452cd
--- /dev/null
+++ b/agent/src/tools/paper_trade/order_lifecycle.py
@@ -0,0 +1,287 @@
+"""A bar-agnostic order lifecycle for the deterministic paper-trading engine.
+
+Implements phase 1 of the #1938 roadmap: the JoinQuant-shaped order object as
+a standalone state machine — no engine wiring, no calendar, no market data.
+Wiring into the 5m session engine (phase 2) and the partial-fill volume-cap
+policy (phase 3) are separate decisions.
+
+Scope, frozen from the thread:
+
+- order id stable across replay (a replayed order list reproduces identical
+ ids, so a retry is distinguishable from a new order);
+- status set ``new / open / filled / canceled / rejected / held
+ (partially filled) / pending_cancel``;
+- cancel by order id; cancel of a terminal order is refused, cancel of an
+ already-cancel-requested order is idempotent;
+- day-order semantics: every unfinished order is canceled at end of day
+ (``settle_day``);
+- partial fills under a caller-supplied volume cap;
+- market and limit order styles; no replace primitive (modify = cancel + a
+ new order with a new id), no TIF.
+
+Determinism: no wall-clock reads, Decimal money arithmetic, frozen status
+constants. The machine is a pure function of (order set, events) — the same
+inputs always produce the same ledger.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from decimal import Decimal
+from typing import Iterable
+
+STATUS_NEW = "new"
+STATUS_OPEN = "open"
+STATUS_FILLED = "filled"
+STATUS_CANCELED = "canceled"
+STATUS_REJECTED = "rejected"
+STATUS_HELD = "held"
+STATUS_PENDING_CANCEL = "pending_cancel"
+
+_TERMINAL_STATUSES = frozenset(
+ {STATUS_FILLED, STATUS_CANCELED, STATUS_REJECTED}
+)
+_UNFINISHED_STATUSES = frozenset({STATUS_NEW, STATUS_OPEN, STATUS_HELD, STATUS_PENDING_CANCEL})
+_ACTIVE_STATUSES = frozenset({STATUS_NEW, STATUS_OPEN, STATUS_HELD})
+
+_ORDER_ID_PREFIX = "pt"
+
+
+class OrderLifecycleError(ValueError):
+ """A lifecycle operation the frozen contract refuses (fail-closed)."""
+
+
+@dataclass(frozen=True, slots=True)
+class OrderRequest:
+ """A caller-submitted order, before any lifecycle state.
+
+ ``order_id`` may be omitted; :func:`assign_ids` then derives a stable id
+ from the request's position in the list, so a replayed list reproduces
+ identical ids and a retry is distinguishable from a new order.
+ """
+
+ symbol: str
+ side: str
+ qty: Decimal
+ order_type: str = "market"
+ limit_price: Decimal | None = None
+ order_id: str | None = None
+
+ def __post_init__(self) -> None:
+ if self.side not in ("buy", "sell"):
+ raise OrderLifecycleError(f"order side must be 'buy' or 'sell', got {self.side!r}")
+ if self.order_type not in ("market", "limit"):
+ raise OrderLifecycleError(f"order type must be 'market' or 'limit', got {self.order_type!r}")
+ if self.qty <= 0:
+ raise OrderLifecycleError(f"order qty must be positive, got {self.qty}")
+ if self.order_type == "limit" and self.limit_price is None:
+ raise OrderLifecycleError("a limit order must carry limit_price")
+ if self.order_type == "market" and self.limit_price is not None:
+ raise OrderLifecycleError("a market order must not carry limit_price")
+
+
+@dataclass(frozen=True, slots=True)
+class Fill:
+ """One execution against an order; one order can have several fills."""
+
+ order_id: str
+ qty: Decimal
+ price: Decimal
+
+
+@dataclass(slots=True)
+class OrderState:
+ """The mutable lifecycle record of one order (ids are stable, status flows)."""
+
+ request: OrderRequest
+ order_id: str
+ status: str = STATUS_NEW
+ filled_qty: Decimal = Decimal(0)
+ avg_fill_price: Decimal | None = None
+ fills: list[Fill] = field(default_factory=list)
+ rejected_reason: str | None = None
+
+
+def assign_ids(requests: Iterable[OrderRequest]) -> dict[str, OrderState]:
+ """Assign stable ids to a batch of requests.
+
+ Explicit ids are honoured and must be unique; requests without an id get
+ ``pt-<index>`` in list order, so replaying the same list reproduces the
+ same ids byte for byte.
+ """
+ states: dict[str, OrderState] = {}
+ for index, request in enumerate(requests):
+ order_id = request.order_id or f"{_ORDER_ID_PREFIX}-{index}"
+ if order_id in states:
+ raise OrderLifecycleError(f"duplicate order id {order_id!r}")
+ states[order_id] = OrderState(request=request, order_id=order_id)
+ return states
+
+
+class OrderBook:
+ """The bar-agnostic lifecycle: orders in, statuses and fills out.
+
+ The book never reads the clock and never touches money floats; fill
+ quantities and prices are ``Decimal``. It is deliberately unwired to any
+ engine: the 5m session engine (phase 2) will drive it bar by bar.
+ """
+
+ def __init__(self, states: dict[str, OrderState] | None = None) -> None:
+ self._states: dict[str, OrderState] = dict(states) if states else {}
+
+ # ------------------------------------------------------------------ reads
+ @property
+ def orders(self) -> dict[str, OrderState]:
+ return self._states
+
+ def get(self, order_id: str) -> OrderState | None:
+ return self._states.get(order_id)
+
+ def open_orders(self) -> list[OrderState]:
+ """Today's unfinished orders (JoinQuant's ``get_open_orders``)."""
+ return [s for s in self._states.values() if s.status in _ACTIVE_STATUSES]
+
+ # ----------------------------------------------------------------- writes
+ def submit(self, request: OrderRequest) -> OrderState:
+ """Accept a new order; the id must not collide with a live or dead one."""
+ order_id = request.order_id
+ if order_id is None:
+ raise OrderLifecycleError("submit requires an explicit order_id")
+ if order_id in self._states:
+ raise OrderLifecycleError(f"duplicate order id {order_id!r}")
+ state = OrderState(request=request, order_id=order_id)
+ self._states[order_id] = state
+ return state
+
+ def reject(self, order_id: str, reason: str) -> OrderState:
+ """Move an unfinished order to ``rejected``; terminal orders are frozen."""
+ state = self._require(order_id)
+ self._require_unfinished(state, "reject")
+ state.status = STATUS_REJECTED
+ state.rejected_reason = reason
+ return state
+
+ def activate(self, order_id: str) -> OrderState:
+ """Move a ``new`` order to ``open`` (accepted for matching)."""
+ state = self._require(order_id)
+ if state.status != STATUS_NEW:
+ raise OrderLifecycleError(
+ f"order {order_id!r} cannot activate from status {state.status!r}"
+ )
+ state.status = STATUS_OPEN
+ return state
+
+ def request_cancel(self, order_id: str) -> OrderState:
+ """Ask to cancel by order id.
+
+ A terminal order (filled/canceled/rejected) cannot be canceled — the
+ refusal is an error, not a silent no-op. Asking twice is idempotent:
+ the second call returns the ``pending_cancel`` state unchanged.
+ """
+ state = self._require(order_id)
+ if state.status in _TERMINAL_STATUSES:
+ raise OrderLifecycleError(
+ f"order {order_id!r} is already {state.status}; it cannot be canceled"
+ )
+ if state.status != STATUS_PENDING_CANCEL:
+ state.status = STATUS_PENDING_CANCEL
+ return state
+
+ def fill(self, order_id: str, qty: Decimal, price: Decimal, *, volume_cap: Decimal | None = None) -> Fill:
+ """Execute part or all of an unfinished order at ``price``.
+
+ Args:
+ order_id: The order to fill.
+ qty: Requested execution quantity; clipped to the remaining
+ quantity, never negative.
+ price: Execution price for this fill.
+ volume_cap: Optional per-fill cap (the phase-3 volume-share
+ policy); the executed quantity is ``min(qty, cap, remaining)``.
+
+ Returns:
+ The executed :class:`Fill`.
+
+ Raises:
+ OrderLifecycleError: The order is terminal or already
+ cancel-requested (a pending_cancel order stops matching), or
+ the qty/cap is not positive.
+ """
+ state = self._require(order_id)
+ if state.status in _TERMINAL_STATUSES:
+ raise OrderLifecycleError(
+ f"order {order_id!r} is already {state.status}; it cannot fill"
+ )
+ if state.status == STATUS_PENDING_CANCEL:
+ raise OrderLifecycleError(
+ f"order {order_id!r} has a pending cancel; it no longer matches"
+ )
+ if qty <= 0:
+ raise OrderLifecycleError(f"fill qty must be positive, got {qty}")
+ if volume_cap is not None and volume_cap <= 0:
+ raise OrderLifecycleError(f"volume_cap must be positive, got {volume_cap}")
+ remaining = state.request.qty - state.filled_qty
+ executable = qty if volume_cap is None else min(qty, volume_cap)
+ executable = min(executable, remaining)
+ if executable <= 0:
+ raise OrderLifecycleError(
+ f"order {order_id!r} has no remaining quantity to fill"
+ )
+ fill = Fill(order_id=order_id, qty=executable, price=price)
+ state.fills.append(fill)
+ state.filled_qty += executable
+ total_cost = sum((f.qty * f.price for f in state.fills), Decimal(0))
+ state.avg_fill_price = total_cost / state.filled_qty
+ state.status = (
+ STATUS_FILLED if state.filled_qty == state.request.qty else STATUS_HELD
+ )
+ return fill
+
+ def settle_day(self) -> list[OrderState]:
+ """Day-order semantics: cancel every unfinished order at session end.
+
+ Returns the canceled states. A ``pending_cancel`` order settles the
+ same way — the cancel it asked for has arrived.
+ """
+ settled: list[OrderState] = []
+ for state in self._states.values():
+ if state.status in _UNFINISHED_STATUSES:
+ state.status = STATUS_CANCELED
+ settled.append(state)
+ return settled
+
+ # --------------------------------------------------------------- helpers
+ def _require(self, order_id: str) -> OrderState:
+ state = self._states.get(order_id)
+ if state is None:
+ raise OrderLifecycleError(f"unknown order id {order_id!r}")
+ return state
+
+ @staticmethod
+ def _require_unfinished(state: OrderState, action: str) -> None:
+ if state.status in _TERMINAL_STATUSES:
+ raise OrderLifecycleError(
+ f"order {state.order_id!r} is already {state.status}; cannot {action} it"
+ )
+
+
+def replay_snapshot(book: OrderBook) -> dict[str, dict[str, object]]:
+ """Render the book as a JSON-ready, replay-comparable snapshot.
+
+ Keys are sorted so two runs over identical inputs produce identical
+ snapshots; Decimal values are rendered as strings (JCS-safe, like the
+ engine's wire format).
+ """
+ snapshot: dict[str, dict[str, object]] = {}
+ for order_id in sorted(book.orders):
+ state = book.orders[order_id]
+ snapshot[order_id] = {
+ "status": state.status,
+ "filled_qty": str(state.filled_qty),
+ "avg_fill_price": (
+ None if state.avg_fill_price is None else str(state.avg_fill_price)
+ ),
+ "fills": [
+ {"qty": str(f.qty), "price": str(f.price)} for f in state.fills
+ ],
+ }
+ return snapshot
diff --git a/agent/tests/test_paper_order_lifecycle.py b/agent/tests/test_paper_order_lifecycle.py
new file mode 100644
index 000000000..2ac9e8563
--- /dev/null
+++ b/agent/tests/test_paper_order_lifecycle.py
@@ -0,0 +1,234 @@
+"""Phase-1 tests for the bar-agnostic order lifecycle (#1938).
+
+The state machine is deliberately unwired: these tests pin the contract —
+stable replay ids, the JoinQuant status set, cancel semantics, day-order
+settlement, partial fills under a volume cap — without any engine, calendar
+or market data.
+"""
+
+from __future__ import annotations
+
+from decimal import Decimal
+
+import pytest
+
+from src.tools.paper_trade.order_lifecycle import (
+ STATUS_CANCELED,
+ STATUS_FILLED,
+ STATUS_HELD,
+ STATUS_NEW,
+ STATUS_OPEN,
+ STATUS_PENDING_CANCEL,
+ STATUS_REJECTED,
+ OrderBook,
+ OrderLifecycleError,
+ OrderRequest,
+ assign_ids,
+ replay_snapshot,
+)
+
+D = Decimal
+
+
+def _request(**overrides):
+ kwargs = dict(symbol="600519.SH", side="buy", qty=D("100"))
+ kwargs.update(overrides)
+ return OrderRequest(**kwargs)
+
+
+class TestRequestValidation:
+ def test_side_must_be_buy_or_sell(self):
+ with pytest.raises(OrderLifecycleError, match="side"):
+ _request(side="hold")
+
+ def test_qty_must_be_positive(self):
+ with pytest.raises(OrderLifecycleError, match="positive"):
+ _request(qty=D("0"))
+
+ def test_limit_order_requires_a_price(self):
+ with pytest.raises(OrderLifecycleError, match="limit_price"):
+ _request(order_type="limit")
+
+ def test_market_order_must_not_carry_a_price(self):
+ with pytest.raises(OrderLifecycleError, match="market"):
+ _request(limit_price=D("10"))
+
+
+class TestStableReplayIds:
+ def test_replayed_batches_reproduce_identical_ids(self):
+ first = assign_ids([_request(), _request(side="sell")])
+ second = assign_ids([_request(), _request(side="sell")])
+ assert sorted(first) == sorted(second) == ["pt-0", "pt-1"]
+
+ def test_explicit_ids_are_honoured_and_must_be_unique(self):
+ states = assign_ids([_request(order_id="ord-7")])
+ assert list(states) == ["ord-7"]
+ with pytest.raises(OrderLifecycleError, match="duplicate"):
+ assign_ids([_request(order_id="dup"), _request(order_id="dup")])
+
+
+class TestLifecycleFlow:
+ def test_new_order_activates_then_fills_fully(self):
+ book = OrderBook(assign_ids([_request()]))
+ book.activate("pt-0")
+ fill = book.fill("pt-0", D("100"), D("1700.00"))
+ assert fill.qty == D("100")
+ state = book.get("pt-0")
+ assert state.status == STATUS_FILLED
+ assert state.filled_qty == D("100")
+ assert state.avg_fill_price == D("1700.00")
+
+ def test_partial_fill_marks_held(self):
+ book = OrderBook(assign_ids([_request()]))
+ book.activate("pt-0")
+ book.fill("pt-0", D("40"), D("1700.00"))
+ assert book.get("pt-0").status == STATUS_HELD
+
+ def test_avg_price_weighted_across_fills(self):
+ book = OrderBook(assign_ids([_request(qty=D("200"))]))
+ book.activate("pt-0")
+ book.fill("pt-0", D("100"), D("10.00"))
+ book.fill("pt-0", D("50"), D("13.00"))
+ # (100*10 + 50*13) / 150 = 11
+ assert book.get("pt-0").avg_fill_price == D("11")
+
+ def test_overfill_is_clipped_to_the_remaining_quantity(self):
+ book = OrderBook(assign_ids([_request(qty=D("100"))]))
+ book.activate("pt-0")
+ book.fill("pt-0", D("60"), D("10"))
+ fill = book.fill("pt-0", D("1000"), D("10"))
+ assert fill.qty == D("40")
+ assert book.get("pt-0").status == STATUS_FILLED
+
+ def test_rejected_reason_is_recorded(self):
+ book = OrderBook(assign_ids([_request()]))
+ book.reject("pt-0", "insufficient_position")
+ state = book.get("pt-0")
+ assert state.status == STATUS_REJECTED
+ assert state.rejected_reason == "insufficient_position"
+
+
+class TestCancel:
+ def test_cancel_by_id_moves_open_order_to_pending_cancel(self):
+ book = OrderBook(assign_ids([_request()]))
+ book.activate("pt-0")
+ book.request_cancel("pt-0")
+ assert book.get("pt-0").status == STATUS_PENDING_CANCEL
+
+ def test_cancel_is_idempotent_while_pending(self):
+ book = OrderBook(assign_ids([_request()]))
+ book.activate("pt-0")
+ book.request_cancel("pt-0")
+ book.request_cancel("pt-0")
+ assert book.get("pt-0").status == STATUS_PENDING_CANCEL
+
+ def test_terminal_order_cannot_be_canceled(self):
+ book = OrderBook(assign_ids([_request()]))
+ book.activate("pt-0")
+ book.fill("pt-0", D("100"), D("1700"))
+ with pytest.raises(OrderLifecycleError, match="cannot be canceled"):
+ book.request_cancel("pt-0")
+
+ def test_pending_cancel_order_stops_matching(self):
+ book = OrderBook(assign_ids([_request()]))
+ book.activate("pt-0")
+ book.request_cancel("pt-0")
+ with pytest.raises(OrderLifecycleError, match="no longer matches"):
+ book.fill("pt-0", D("10"), D("1700"))
+
+ def test_unknown_id_fails_closed(self):
+ book = OrderBook()
+ with pytest.raises(OrderLifecycleError, match="unknown order id"):
+ book.request_cancel("nope")
+
+
+class TestDayOrderSettlement:
+ def test_every_unfinished_order_is_canceled_at_session_end(self):
+ book = OrderBook(assign_ids([_request(), _request(side="sell"), _request(symbol="000001.SZ")]))
+ book.activate("pt-0")
+ book.activate("pt-1")
+ book.fill("pt-0", D("40"), D("1700"))
+ settled = book.settle_day()
+ assert sorted(s.order_id for s in settled) == ["pt-0", "pt-1", "pt-2"]
+ assert all(s.status == STATUS_CANCELED for s in settled)
+ # partially filled order keeps its fills after cancellation
+ assert book.get("pt-0").filled_qty == D("40")
+
+ def test_terminal_orders_are_left_alone(self):
+ book = OrderBook(assign_ids([_request()]))
+ book.activate("pt-0")
+ book.fill("pt-0", D("100"), D("1700"))
+ assert book.settle_day() == []
+ assert book.get("pt-0").status == STATUS_FILLED
+
+
+class TestVolumeCap:
+ def test_fill_is_capped_at_the_volume_cap(self):
+ book = OrderBook(assign_ids([_request(qty=D("1000"))]))
+ book.activate("pt-0")
+ fill = book.fill("pt-0", D("1000"), D("10"), volume_cap=D("250"))
+ assert fill.qty == D("250")
+ assert book.get("pt-0").status == STATUS_HELD
+
+ def test_non_positive_cap_fails_closed(self):
+ book = OrderBook(assign_ids([_request()]))
+ book.activate("pt-0")
+ with pytest.raises(OrderLifecycleError, match="volume_cap"):
+ book.fill("pt-0", D("10"), D("10"), volume_cap=D("0"))
+
+ def test_cap_larger_than_request_fills_the_request(self):
+ book = OrderBook(assign_ids([_request(qty=D("100"))]))
+ book.activate("pt-0")
+ fill = book.fill("pt-0", D("100"), D("10"), volume_cap=D("10000"))
+ assert fill.qty == D("100")
+
+
+class TestDeterminism:
+ def test_identical_event_sequences_produce_identical_snapshots(self):
+ def run() -> dict:
+ book = OrderBook(assign_ids([_request(), _request(qty=D("500"), symbol="00700.HK")]))
+ book.activate("pt-0")
+ book.activate("pt-1")
+ book.fill("pt-0", D("30"), D("1700.00"))
+ book.fill("pt-1", D("250"), D("310.40"), volume_cap=D("250"))
+ book.request_cancel("pt-0")
+ book.settle_day()
+ return replay_snapshot(book)
+
+ assert run() == run()
+
+ def test_snapshot_is_sorted_and_json_ready(self):
+ book = OrderBook(assign_ids([_request(), _request(side="sell")]))
+ book.activate("pt-1")
+ snapshot = replay_snapshot(book)
+ assert list(snapshot) == ["pt-0", "pt-1"]
+ assert snapshot["pt-0"]["status"] == STATUS_NEW
+ assert snapshot["pt-1"]["status"] == STATUS_OPEN
+ assert all(isinstance(v["filled_qty"], str) for v in snapshot.values())
+
+
+class TestOpenOrders:
+ def test_open_orders_lists_only_active_ones(self):
+ book = OrderBook(assign_ids([_request(), _request(side="sell"), _request(symbol="000001.SZ")]))
+ book.activate("pt-0")
+ book.activate("pt-1")
+ book.fill("pt-1", D("100"), D("1700"))
+ assert [s.order_id for s in book.open_orders()] == ["pt-0", "pt-2"]
+
+
+class TestSubmit:
+ def test_submit_rejects_a_reused_id_even_after_terminal(self):
+ book = OrderBook()
+ book.submit(_request(order_id="ord-1"))
+ book.fill("ord-1", D("100"), D("1700"))
+ with pytest.raises(OrderLifecycleError, match="duplicate"):
+ book.submit(_request(order_id="ord-1", side="sell"))
+
+ def test_modify_is_cancel_then_new_id(self):
+ book = OrderBook()
+ first = book.submit(_request(order_id="ord-1"))
+ book.request_cancel("ord-1")
+ book.settle_day()
+ second = book.submit(_request(order_id="ord-2", qty=D("200")))
+ assert first.status == STATUS_CANCELED
+ assert second.status == STATUS_NEW