synpath 0.1.0__py3-none-any.whl

synpath/engine/reconcile.py

@@ -0,0 +1,279 @@
+"""Reconciliation: what the venue says, against what the engine believes.
+
+The engine's journal is authoritative about its own decisions and about
+nothing else. Someone can trade the same account from a phone, a fill can
+arrive while the process is down, a venue can expire an order without
+telling anyone. So the engine asks, on a timer and at startup, and names
+every difference:
+
+| Finding | Meaning |
+|---|---|
+| `orphan` | resting at the venue, unknown to the journal |
+| `ghost` | open in the journal, gone at the venue |
+| `drift` | known to both, different status, filled amount or price |
+| `position` | the ledger and the venue disagree about a position |
+| `fill` | a fill the venue has and the journal does not |
+| `balance` | cash moved without a fill explaining it |
+
+Findings are reported, not silently fixed. The policy decides what happens
+to each: `report` only says so, `adopt` takes an orphan into the journal so
+the engine manages it from now on, `cancel` pulls it. A ghost is always
+closed in the journal, because the venue is the authority on whether an
+order exists.
+
+Balance reconciliation is the one that catches what nothing else does: a
+deposit, a withdrawal, a settlement, or a fee charged outside any fill. It
+compares the venue's cash against the cash the journal can explain, and
+reports the difference rather than adjusting anything.
+"""
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from decimal import Decimal
+from typing import Any, Literal
+
+from ..trading.base import TradingExchange
+from ..trading.types import Balance, Fill, HeldBy, Order, OrderStatus, Position, PositionSide
+from .engine import Engine
+
+log = logging.getLogger("synpath.engine")
+
+ZERO = Decimal("0")
+
+OrphanPolicy = Literal["report", "adopt", "cancel"]
+Finding = Literal["orphan", "ghost", "drift", "position", "fill", "balance"]
+
+
+@dataclass(slots=True)
+class Difference:
+    kind: Finding
+    venue: str
+    key: str
+    detail: dict[str, Any] = field(default_factory=dict)
+    action: str = "reported"
+
+    def as_event(self) -> dict[str, Any]:
+        return {"kind": self.kind, "venue": self.venue, "key": self.key, "action": self.action, **self.detail}
+
+
+@dataclass(slots=True)
+class ReconcileReport:
+    venue: str
+    orphans: list[Difference] = field(default_factory=list)
+    ghosts: list[Difference] = field(default_factory=list)
+    drifts: list[Difference] = field(default_factory=list)
+    positions: list[Difference] = field(default_factory=list)
+    fills: list[Difference] = field(default_factory=list)
+    balances: list[Difference] = field(default_factory=list)
+    checked_orders: int = 0
+    checked_positions: int = 0
+    new_fills: int = 0
+
+    @property
+    def differences(self) -> list[Difference]:
+        return [*self.orphans, *self.ghosts, *self.drifts, *self.positions, *self.fills, *self.balances]
+
+    @property
+    def clean(self) -> bool:
+        return not self.differences
+
+    def summary(self) -> dict[str, Any]:
+        return {
+            "venue": self.venue, "clean": self.clean, "orders_checked": self.checked_orders,
+            "positions_checked": self.checked_positions, "new_fills": self.new_fills,
+            "orphans": len(self.orphans), "ghosts": len(self.ghosts), "drifts": len(self.drifts),
+            "position_differences": len(self.positions), "balance_differences": len(self.balances),
+        }
+
+
+class Reconciler:
+    """Compares one engine against the venues it trades."""
+
+    def __init__(
+        self,
+        engine: Engine,
+        *,
+        orphan_policy: OrphanPolicy = "report",
+        position_tolerance: Decimal = ZERO,
+        balance_tolerance: Decimal = Decimal("0.01"),
+    ):
+        self.engine = engine
+        self.orphan_policy = orphan_policy
+        self.position_tolerance = position_tolerance
+        self.balance_tolerance = balance_tolerance
+
+    async def run(self, venue: str | None = None) -> list[ReconcileReport]:
+        """Reconcile one venue or all of them."""
+        names = [venue] if venue else list(self.engine.adapters)
+        reports = []
+        for name in names:
+            report = await self.venue(name, self.engine.adapters[name])
+            reports.append(report)
+        return reports
+
+    async def venue(self, venue: str, adapter: TradingExchange) -> ReconcileReport:
+        report = ReconcileReport(venue=venue)
+        await self._orders(venue, adapter, report)
+        await self._fills(venue, adapter, report)
+        await self._positions(venue, adapter, report)
+        await self._balance(venue, adapter, report)
+        await self.engine.bus.publish("reconcile.done", report.summary(), key=venue)
+        for difference in report.differences:
+            await self.engine.bus.publish(f"reconcile.{difference.kind}", difference.as_event(), key=f"{venue}:{difference.key}")
+        return report
+
+    # -- orders ---------------------------------------------------------------
+
+    async def _orders(self, venue: str, adapter: TradingExchange, report: ReconcileReport) -> None:
+        live = {o.id: o for o in await adapter.fetch_open_orders()}
+        # Engine-held parents are not orders at the venue: asking about one
+        # would report it missing every minute.
+        mine = {o.id: o for o in await self.engine.journal.open_orders(venue=venue) if o.held_by != HeldBy.ENGINE}
+        report.checked_orders = len(live) + len(mine)
+
+        for order_id, order in live.items():
+            known = mine.get(order_id)
+            if known is None:
+                # An order this engine never wrote down. Adopting it means
+                # managing it; cancelling it assumes nobody else should be
+                # trading this account. Reporting is the only safe default.
+                difference = Difference("orphan", venue, order_id, {
+                    "market_id": order.market_id, "side": order.side.value,
+                    "amount": str(order.amount), "price": str(order.price) if order.price else None,
+                    "client_order_id": order.client_order_id,
+                })
+                if self.orphan_policy == "adopt":
+                    await self.engine.on_order(order)
+                    difference.action = "adopted"
+                elif self.orphan_policy == "cancel":
+                    try:
+                        await adapter.cancel_order(order_id, market_id=order.market_id)
+                        difference.action = "canceled"
+                    except Exception as exc:
+                        difference.action = f"cancel failed: {type(exc).__name__}"
+                report.orphans.append(difference)
+                continue
+            if _drifted(known, order):
+                await self.engine.on_order(order)
+                report.drifts.append(Difference("drift", venue, order_id, {
+                    "journal_status": known.status.value, "venue_status": order.status.value,
+                    "journal_filled": str(known.filled), "venue_filled": str(order.filled),
+                    "journal_price": str(known.price) if known.price else None,
+                    "venue_price": str(order.price) if order.price else None,
+                }, action="updated"))
+
+        for order_id, order in mine.items():
+            if order_id in live:
+                continue
+            # Open here, gone there. The venue is the authority: close it, but
+            # read it first, because it may have filled rather than vanished.
+            final = None
+            try:
+                final = await adapter.fetch_order(order_id)
+            except Exception:
+                final = None
+            closed = final or order.model_copy(update={"status": OrderStatus.CANCELED})
+            await self.engine.on_order(closed)
+            report.ghosts.append(Difference("ghost", venue, order_id, {
+                "market_id": order.market_id, "journal_status": order.status.value,
+                "final_status": closed.status.value, "filled": str(closed.filled),
+            }, action="closed"))
+
+    # -- fills ----------------------------------------------------------------
+
+    async def _fills(self, venue: str, adapter: TradingExchange, report: ReconcileReport) -> None:
+        if not adapter.has.get("fetch_my_trades"):
+            return
+        since = int(await self.engine.journal.cursor(f"reconcile_fills:{venue}", 0) or 0)
+        try:
+            fills = await adapter.fetch_my_trades(since=since or None, limit=500)
+        except Exception as exc:
+            log.warning("synpath.engine: reading fills from %s failed: %s", venue, exc)
+            return
+        newest = since
+        for fill in fills:
+            newest = max(newest, fill.timestamp or 0)
+            if await self.engine.journal.has_fill(venue, fill.id):
+                continue
+            await self.engine.on_fill(fill)
+            report.new_fills += 1
+            report.fills.append(Difference("fill", venue, fill.id, {
+                "order_id": fill.order_id, "market_id": fill.market_id,
+                "amount": str(fill.amount), "price": str(fill.price),
+            }, action="booked"))
+        if newest > since:
+            await self.engine.journal.set_cursor(f"reconcile_fills:{venue}", newest)
+
+    # -- positions ------------------------------------------------------------
+
+    async def _positions(self, venue: str, adapter: TradingExchange, report: ReconcileReport) -> None:
+        if not adapter.has.get("fetch_positions"):
+            return
+        try:
+            live = await adapter.fetch_positions()
+        except Exception as exc:
+            log.warning("synpath.engine: reading positions from %s failed: %s", venue, exc)
+            return
+        rows = self.engine.ledger.merged(live)
+        report.checked_positions = len(rows)
+        for row in rows:
+            if row["venue"] != venue:
+                continue
+            difference = row["difference"]
+            if abs(difference) > self.position_tolerance:
+                report.positions.append(Difference("position", venue, row["market_id"], {
+                    "account": row["account"], "engine": str(row["engine"]),
+                    "venue_contracts": str(row["venue_contracts"]), "difference": str(difference),
+                    "books": {k: str(v) for k, v in row["books"].items()},
+                }))
+
+    # -- balance --------------------------------------------------------------
+
+    async def _balance(self, venue: str, adapter: TradingExchange, report: ReconcileReport) -> None:
+        if not adapter.has.get("fetch_balance"):
+            return
+        try:
+            balance = await adapter.fetch_balance()
+        except Exception as exc:
+            log.warning("synpath.engine: reading the balance from %s failed: %s", venue, exc)
+            return
+        key = f"balance:{venue}"
+        previous = await self.engine.journal.cursor(key)
+        await self.engine.journal.set_cursor(key, str(balance.total))
+        if previous is None:
+            return
+        moved = balance.total - Decimal(previous)
+        if moved == ZERO:
+            return
+        explained = await self._explained_cash(venue)
+        unexplained = moved - explained
+        if abs(unexplained) > self.balance_tolerance:
+            report.balances.append(Difference("balance", venue, balance.currency, {
+                "moved": str(moved), "explained_by_fills": str(explained), "unexplained": str(unexplained),
+                "total": str(balance.total), "available": str(balance.available),
+                "note": "a deposit, a withdrawal, a settlement or a fee charged outside a fill",
+            }))
+
+    async def _explained_cash(self, venue: str) -> Decimal:
+        """Cash the fills since the last check account for."""
+        key = f"balance_cursor:{venue}"
+        since = int(await self.engine.journal.cursor(key, 0) or 0)
+        newest = since
+        total = ZERO
+        for fill in await self.engine.journal.fills(since_ts=since, venue=venue):
+            newest = max(newest, fill.timestamp or 0)
+            signed = -1 if fill.side.value == "buy" else 1
+            total += Decimal(signed) * fill.price * fill.amount - (fill.fee or ZERO)
+        if newest > since:
+            await self.engine.journal.set_cursor(key, newest)
+        return total
+
+
+def _drifted(mine: Order, theirs: Order) -> bool:
+    return (
+        mine.status != theirs.status
+        or mine.filled != theirs.filled
+        or (mine.price or ZERO) != (theirs.price or ZERO)
+        or (mine.remaining or ZERO) != (theirs.remaining or ZERO)
+    )

synpath/engine/risk.py

@@ -0,0 +1,403 @@
+"""Pre-trade risk: the rules that refuse an order before it is signed.
+
+Every rule here answers one question and names itself when it says no, so a
+rejection is a sentence an operator can act on rather than a generic error.
+The configuration is versioned in the journal: a rejection records which
+version refused it, and a later argument about why is settled by reading
+that version instead of guessing what the file said at the time.
+
+Rules fall into three groups:
+
+**About this order.** Price collar against the mark, order size and notional,
+whole-contract and tick rules the venue would reject anyway, a restricted
+list, and a guard against sending anything into a market that is about to
+close. Also the duplicate window: the same order twice within a few seconds
+is almost always a retry loop, not a decision.
+
+**About the book it joins.** Open-order count, position caps per instrument,
+per event and per venue, the exchange's own position limit where the venue
+publishes one, and the daily loss limit, which reads the ledger rather than
+a number someone maintains by hand.
+
+**About the firm.** Self-trade prevention: an order that would cross this
+firm's own resting order is refused (or the resting one is cancelled first,
+where the caller asks for that), because a wash trade is a compliance
+problem, not a fill. It looks at every book in the account, not just the one
+placing the order, which is why it lives here and not in a strategy.
+
+The kill switch sits alongside the rules. It can be engaged globally or for
+one venue, and it decides what happens to orders already resting: `cancel`
+pulls them, `hold` leaves them and blocks new ones, `rearm` blocks new
+orders and lifts itself after a timer. The engine maps it onto the venues'
+own mechanisms where they exist, which is what makes it fast: a Kalshi order
+group cancels server-side in one round trip, and a Polymarket heartbeat that
+stops beating cancels everything within ten seconds even if this process is
+gone.
+"""
+from __future__ import annotations
+
+import time
+from collections import deque
+from dataclasses import dataclass, field
+from decimal import Decimal
+from typing import Any, Iterable, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .. import ids
+from ..trading.types import Account, Order, OrderRequest, Side
+from .ledger import Ledger
+
+ZERO = Decimal("0")
+ONE = Decimal("1")
+
+HaltPolicy = Literal["cancel", "hold", "rearm"]
+SelfTradeScope = Literal["off", "account", "firm"]
+
+
+class RiskConfig(BaseModel):
+    """What the engine will and will not do. Stored as a version in the journal."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    enabled: bool = True
+
+    # -- this order --
+    price_collar: Decimal | None = Decimal("0.10")
+    """How far from the mark a limit may sit, in price units (contracts are
+    priced 0 to 1, so 0.10 is ten cents). `None` disables the check."""
+    max_order_contracts: Decimal | None = None
+    max_order_notional: Decimal | None = None
+    """Price times contracts, in account currency."""
+    min_price: Decimal = Decimal("0")
+    max_price: Decimal = Decimal("1")
+    duplicate_window_ms: int = 2_000
+    """The same instrument, side, price and size within this window is a retry."""
+    closing_soon_s: int | None = 60
+    """Refuse opening orders this close to a market's resolution time."""
+    restricted: list[str] = Field(default_factory=list)
+    """Instrument or market ids, or prefixes ending in `*`, nobody may trade."""
+
+    # -- the book --
+    max_open_orders: int | None = 200
+    max_position_contracts: Decimal | None = None
+    """Per instrument, per account, netted across books."""
+    max_event_contracts: Decimal | None = None
+    max_venue_notional: Decimal | None = None
+    daily_loss_limit: Decimal | None = None
+    """Realized loss since the day's start, as a positive number."""
+    max_orders_per_minute: int | None = 120
+
+    # -- the firm --
+    self_trade_prevention: SelfTradeScope = "firm"
+    exchange_limits: dict[str, Decimal] = Field(default_factory=dict)
+    """Venue-published position limits, per market id."""
+    paused_books: list[str] = Field(default_factory=list)
+    """Strategies that may cancel but not open."""
+
+    def paused(self, book: str | None) -> bool:
+        return bool(book and book in self.paused_books)
+
+    def restricts(self, market_id: str, _unused: str | None = None) -> str | None:
+        for pattern in self.restricted:
+            for candidate in (market_id, ids.split(market_id)[1]):
+                if not candidate:
+                    continue
+                if pattern.endswith("*") and candidate.startswith(pattern[:-1]):
+                    return pattern
+                if candidate == pattern:
+                    return pattern
+        return None
+
+
+@dataclass(frozen=True, slots=True)
+class Decision:
+    """The answer, and which rule gave it."""
+
+    ok: bool
+    rule: str = ""
+    message: str = ""
+    config_version: int | None = None
+    detail: dict[str, Any] = field(default_factory=dict)
+
+    def __bool__(self) -> bool:
+        return self.ok
+
+
+ALLOWED = Decision(ok=True)
+
+
+@dataclass(slots=True)
+class KillSwitch:
+    """Stop trading now, and say what happens to what is already resting."""
+
+    engaged: bool = False
+    scope: str = "*"
+    """`*` for everything, or a venue id."""
+    policy: HaltPolicy = "cancel"
+    reason: str = ""
+    engaged_ts: int | None = None
+    rearm_after_s: float | None = None
+    venues: set[str] = field(default_factory=set)
+
+    def engage(self, *, reason: str, scope: str = "*", policy: HaltPolicy = "cancel", rearm_after_s: float | None = None) -> None:
+        self.engaged = True
+        self.scope = scope
+        self.policy = policy
+        self.reason = reason
+        self.engaged_ts = int(time.time() * 1000)
+        self.rearm_after_s = rearm_after_s
+        if scope != "*":
+            self.venues.add(scope)
+
+    def release(self, *, scope: str | None = None) -> None:
+        if scope and scope != "*" and scope in self.venues:
+            self.venues.discard(scope)
+            if not self.venues and self.scope == scope:
+                self.engaged = False
+            return
+        self.engaged = False
+        self.venues.clear()
+        self.reason = ""
+        self.rearm_after_s = None
+
+    def blocks(self, venue: str, *, now: float | None = None) -> bool:
+        if not self.engaged:
+            return False
+        if self.policy == "rearm" and self.rearm_after_s is not None and self.engaged_ts is not None:
+            if ((now or time.time()) * 1000 - self.engaged_ts) / 1000 >= self.rearm_after_s:
+                self.release()
+                return False
+        return self.scope == "*" or venue in self.venues or venue == self.scope
+
+
+class RiskEngine:
+    """Runs the rules. Holds no venue state: everything it needs is passed in."""
+
+    def __init__(
+        self,
+        config: RiskConfig | None = None,
+        *,
+        ledger: Ledger | None = None,
+        config_version: int | None = None,
+        clock: Any = time.time,
+    ):
+        self.config = config or RiskConfig()
+        self.config_version = config_version
+        self.ledger = ledger
+        self.clock = clock
+        self.kill = KillSwitch()
+        self._recent: deque[tuple[float, tuple[str, str, str, str]]] = deque(maxlen=512)
+        self._sent: deque[float] = deque(maxlen=4096)
+        self.day_start_ms: int = _day_start_ms(self.clock())
+        self.realized_at_day_start: Decimal = ZERO
+
+    # -- configuration --------------------------------------------------------
+
+    def configure(self, config: RiskConfig, *, version: int | None = None) -> None:
+        self.config, self.config_version = config, version
+
+    def roll_day(self, *, realized_now: Decimal | None = None) -> None:
+        """Start a new trading day: the loss limit counts from here."""
+        self.day_start_ms = _day_start_ms(self.clock())
+        if realized_now is not None:
+            self.realized_at_day_start = realized_now
+        elif self.ledger is not None:
+            self.realized_at_day_start = self.ledger.total().realized
+
+    def realized_today(self) -> Decimal:
+        if self.ledger is None:
+            return ZERO
+        return self.ledger.total().realized - self.realized_at_day_start
+
+    # -- the check ------------------------------------------------------------
+
+    def check(
+        self,
+        request: OrderRequest,
+        *,
+        venue: str,
+        account: Account,
+        open_orders: Iterable[Order] = (),
+        mark: Decimal | None = None,
+        market_close_ts: int | None = None,
+        event_id: str | None = None,
+        venue_notional: Decimal | None = None,
+        deliberate: bool = False,
+    ) -> Decision:
+        """Everything that must be true before this order is signed.
+
+        `deliberate` is true when the caller named the order's
+        `client_order_id` itself: the duplicate window is for an accidental
+        second click, and a caller that names each order is not clicking."""
+        config = self.config
+        if not config.enabled:
+            return self._ok()
+        if self.kill.blocks(venue, now=self.clock()):
+            return self._no("kill_switch", f"trading is halted: {self.kill.reason or 'kill switch engaged'}")
+        if config.paused(request.book):
+            return self._no("book_paused", f"strategy {request.book!r} is paused; it may cancel but not open")
+
+        market_id = request.market_id
+        if (pattern := config.restricts(market_id)):
+            return self._no("restricted", f"{market_id} matches the restricted entry {pattern!r}")
+
+        price = request.price
+        if price is not None:
+            if not (config.min_price <= price <= config.max_price):
+                return self._no("price_bounds", f"price {price} is outside {config.min_price}-{config.max_price}")
+            if config.price_collar is not None and mark is not None:
+                away = abs(price - mark)
+                if away > config.price_collar:
+                    return self._no(
+                        "price_collar", f"price {price} is {away} from the mark {mark}, over the collar {config.price_collar}",
+                        detail={"mark": str(mark), "away": str(away)},
+                    )
+        if config.max_order_contracts is not None and request.amount > config.max_order_contracts:
+            return self._no("max_order_contracts", f"{request.amount} contracts is over the {config.max_order_contracts} limit")
+        notional = (price or ONE) * request.amount
+        if config.max_order_notional is not None and notional > config.max_order_notional:
+            return self._no("max_order_notional", f"{notional} is over the {config.max_order_notional} order limit")
+
+        now = self.clock()
+        # An engine-held order's children are sliced on purpose and often look
+        # alike (an iceberg's reloads, a TWAP's slices, two parents on one
+        # market), so the window applies to orders sent from outside only.
+        if config.duplicate_window_ms and not deliberate and not request.tags.get("parent"):
+            signature = (market_id, request.side.value, str(price), str(request.amount))
+            cutoff = now - config.duplicate_window_ms / 1000
+            for stamp, seen in reversed(self._recent):
+                if stamp < cutoff:
+                    break
+                if seen == signature:
+                    return self._no(
+                        "duplicate", f"the same order was sent {round((now - stamp) * 1000)}ms ago; "
+                                     f"pass a different client_order_id if this is deliberate",
+                    )
+        if config.max_orders_per_minute is not None:
+            while self._sent and self._sent[0] < now - 60:
+                self._sent.popleft()
+            if len(self._sent) >= config.max_orders_per_minute:
+                return self._no("order_rate", f"{len(self._sent)} orders in the last minute, at the {config.max_orders_per_minute} limit")
+
+        if config.closing_soon_s is not None and market_close_ts is not None and not request.reduce_only:
+            left = (market_close_ts - now * 1000) / 1000
+            if left <= config.closing_soon_s:
+                return self._no(
+                    "closing_soon", f"{market_id} resolves in {round(left)}s, inside the {config.closing_soon_s}s guard",
+                    detail={"seconds_left": round(left)},
+                )
+
+        resting = [o for o in open_orders if not o.is_terminal]
+        if config.max_open_orders is not None and len(resting) >= config.max_open_orders:
+            return self._no("max_open_orders", f"{len(resting)} orders already resting, at the {config.max_open_orders} limit")
+
+        if config.self_trade_prevention != "off" and price is not None:
+            crossing = self._self_cross(request, resting, account, price)
+            if crossing is not None:
+                return self._no(
+                    "self_trade", f"this would trade against the firm's own order {crossing.id} "
+                                  f"({crossing.side.value} {crossing.remaining} at {crossing.price} on {crossing.market_id})",
+                    detail={"order_id": crossing.id, "book": crossing.book or ""},
+                )
+
+        signed = request.amount if request.side == Side.BUY else -request.amount
+        if self.ledger is not None:
+            current = self._net_contracts(account.key, venue, market_id)
+            after = abs(current + signed)
+            if config.max_position_contracts is not None and after > config.max_position_contracts:
+                return self._no(
+                    "max_position", f"{market_id} would reach {after} contracts, over the {config.max_position_contracts} limit",
+                    detail={"current": str(current), "after": str(after)},
+                )
+            limit = config.exchange_limits.get(market_id)
+            if limit is not None and after > limit:
+                return self._no(
+                    "exchange_limit", f"{market_id} would reach {after} contracts, over the exchange limit {limit}",
+                    detail={"limit": str(limit)},
+                )
+            if config.max_event_contracts is not None and event_id:
+                total = self._event_contracts(account.key, venue, event_id) + abs(signed)
+                if total > config.max_event_contracts:
+                    return self._no("max_event", f"event {event_id} would reach {total} contracts, over {config.max_event_contracts}")
+            if config.daily_loss_limit is not None:
+                loss = -self.realized_today()
+                if loss >= config.daily_loss_limit:
+                    return self._no(
+                        "daily_loss", f"today's realized loss {loss} has reached the {config.daily_loss_limit} limit",
+                        detail={"loss": str(loss)},
+                    )
+        if config.max_venue_notional is not None and venue_notional is not None:
+            if venue_notional + notional > config.max_venue_notional:
+                return self._no(
+                    "max_venue_notional",
+                    f"{venue} would hold {venue_notional + notional} of notional, over {config.max_venue_notional}",
+                )
+        return self._ok()
+
+    # -- bookkeeping ----------------------------------------------------------
+
+    def record_sent(self, request: OrderRequest) -> None:
+        """Count an order that actually went out, for the rate and duplicate windows."""
+        now = self.clock()
+        self._sent.append(now)
+        self._recent.append((now, (request.market_id, request.side.value, str(request.price), str(request.amount))))
+
+    def _self_cross(self, request: OrderRequest, resting: list[Order], account: Account, price: Decimal) -> Order | None:
+        scope = self.config.self_trade_prevention
+        side = request.side
+        limit = price
+        for order in resting:
+            if order.price is None:
+                continue
+            if order.market_id != request.market_id:
+                continue
+            if scope == "account":
+                order_account = order.account.key if order.account else None
+                if order_account != account.key:
+                    continue
+            other_side = order.side
+            other_price = order.price
+            if other_side == side:
+                continue
+            if side == Side.BUY and limit >= other_price:
+                return order
+            if side == Side.SELL and limit <= other_price:
+                return order
+        return None
+
+    def _net_contracts(self, account_key: str, venue: str, market_id: str) -> Decimal:
+        total = ZERO
+        for state in self.ledger.positions.values() if self.ledger else ():
+            if state.account_key == account_key and state.venue == venue and state.market_id == market_id:
+                total += state.contracts
+        return total
+
+    def _event_contracts(self, account_key: str, venue: str, event_id: str) -> Decimal:
+        total = ZERO
+        for state in self.ledger.positions.values() if self.ledger else ():
+            if state.account_key == account_key and state.venue == venue and state.market_id.startswith(event_id):
+                total += abs(state.contracts)
+        return total
+
+    def _ok(self) -> Decision:
+        return Decision(ok=True, config_version=self.config_version)
+
+    def _no(self, rule: str, message: str, *, detail: dict[str, Any] | None = None) -> Decision:
+        return Decision(ok=False, rule=rule, message=message, config_version=self.config_version, detail=detail or {})
+
+
+def _day_start_ms(now: float) -> int:
+    """Midnight UTC before `now`, in milliseconds."""
+    day = int(now) // 86_400 * 86_400
+    return day * 1000
+
+
+def market_of(market_id: str) -> str:
+    """Kept for callers written against the instrument era; the id is the market."""
+    return market_id
+
+
+__all__ = [
+    "RiskConfig", "RiskEngine", "Decision", "KillSwitch", "HaltPolicy", "SelfTradeScope", "ALLOWED", "market_of",
+]