pitbridge 0.1.0__py3-none-any.whl

pitbridge/__init__.py

@@ -0,0 +1,7 @@
+"""PitBridge daemon package.
+
+Guardrailed bridge between AI agents (MCP / REST / WS) and a NinjaTrader 8
+AddOn. Binding architecture: docs/architecture.md at the repo root.
+"""
+
+__version__ = "0.1.0"

pitbridge/accounts.py

@@ -0,0 +1,253 @@
+"""Per-account state + day ledger.
+
+Contract (architecture.md sections 3 and 4): the mutable bookkeeping behind
+the pure guardrail engine. `AccountBook` ingests executions (realized P&L,
+average-cost) and account_state updates (unrealized P&L straight from the
+AddOn's AccountItem events — no market-data feed needed), applies the ET
+day-ledger rollover, and produces the frozen `AccountSnapshot` the engine
+checks against.
+
+Rollover semantics are the Crucible live-loop semantics (live/run.py,
+pinned by tests/test_live_run.py): on the first activity of a new ET date,
+yesterday's realized folds into the balance, the best-day marker updates,
+and — for the eval profile — the EOD trailing floor ratchets to
+max(floor, balance - trailing_drawdown). The funded profile keeps a static
+floor. Because the day P&L resets to zero, a daily-loss halt or profit lock
+from yesterday automatically lifts (no sticky flag; the engine recomputes).
+
+Import-pure and I/O-free: state lives in memory; the M2 link layer feeds it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date, datetime, timedelta
+from typing import Literal
+
+from pitbridge.guardrails.engine import AccountSnapshot, OrderEvent, Side
+from pitbridge.timeutil import et_date, require_aware
+
+Profile = Literal["eval", "funded"]
+
+_EVENT_RETENTION = timedelta(hours=24)  # covers the largest rolling rate-limit window
+
+
+@dataclass(slots=True)
+class _Position:
+    qty: int = 0  # signed net contracts
+    avg_px: float = 0.0
+
+
+class AccountBook:
+    """Mutable per-account ledger. Not thread-safe; the daemon owns one per
+    account on its single event loop."""
+
+    def __init__(
+        self,
+        account: str,
+        *,
+        profile: Profile = "eval",
+        starting_balance: float = 0.0,
+        trailing_drawdown: float = 0.0,
+        point_value: float = 1.0,
+        day_halt_sticky: bool = False,
+        daily_loss_halt: float | None = None,
+        profit_lock: float | None = None,
+    ) -> None:
+        self.account = account
+        self.profile: Profile = profile
+        self.point_value = point_value
+        self.trailing_drawdown = trailing_drawdown
+        self.balance = starting_balance
+        self.trailing_floor = starting_balance - trailing_drawdown
+        self.max_day_profit = 0.0
+        self.day_date: date | None = None
+        self.day_realized = 0.0
+        self.unrealized = 0.0
+        self.link_up = True
+        self.first_order_done = False
+        self.max_order_qty = 0
+        self.last_loss_ts: datetime | None = None
+        self.last_order_ts: datetime | None = None
+        self._positions: dict[str, _Position] = {}
+        self._order_events: list[OrderEvent] = []
+        # exec_ids already booked into the ledger — the link dedups inbound
+        # frames by envelope id, but an execution redelivered with a fresh
+        # envelope id and the same broker exec_id (M4 reconnect/replay) would
+        # otherwise double-count. Ledger booking is idempotent by exec_id.
+        self._booked_exec_ids: set[str] = set()
+        # Sticky day-halt latch (M2 follow-up). The thresholds mirror the
+        # per-account guardrail config; the daemon wires them in. When sticky
+        # halting is on, the latch trips on observation (any account_state /
+        # execution) and holds until the ET rollover — recovery cannot re-open
+        # trading. With sticky off it stays dormant (M1 recompute-per-check).
+        self.day_halt_sticky = day_halt_sticky
+        self.daily_loss_halt = daily_loss_halt
+        self.profit_lock = profit_lock
+        self.day_halted = False
+        self.day_halt_reason: str | None = None
+        self._pending_halt_notice: str | None = None
+
+    # ------------------------------------------------------------- rollover
+
+    def roll_if_needed(self, now: datetime) -> bool:
+        """Apply the ET day-ledger rollover if `now` is on a new ET date.
+        Returns True when a rollover happened (Crucible EOD fold)."""
+        today = et_date(require_aware(now))
+        if self.day_date == today:
+            return False
+        rolled = self.day_date is not None
+        if rolled:
+            self.balance += self.day_realized
+            self.max_day_profit = max(self.max_day_profit, self.day_realized)
+            if self.profile == "eval":
+                # EOD trailing: floor ratchets with the end-of-day high-water
+                self.trailing_floor = max(
+                    self.trailing_floor, self.balance - self.trailing_drawdown
+                )
+        self.day_date = today
+        self.day_realized = 0.0
+        cutoff = now - _EVENT_RETENTION
+        self._order_events = [e for e in self._order_events if e.ts > cutoff]
+        if rolled:
+            # A fresh ET day clears the sticky latch (and any pending flatten
+            # notice for it): yesterday's halt does not carry into today.
+            self.day_halted = False
+            self.day_halt_reason = None
+            self._pending_halt_notice = None
+        return rolled
+
+    # --------------------------------------------------------- sticky halt
+
+    def _evaluate_halt(self) -> None:
+        """Latch the sticky day-halt if a loss-halt or profit-lock threshold is
+        breached. No-op when sticky is off or the latch is already set."""
+        if not self.day_halt_sticky or self.day_halted:
+            return
+        pnl = self.day_pnl
+        if self.daily_loss_halt is not None and pnl <= -self.daily_loss_halt:
+            self._latch("DAILY_LOSS_HALT")
+        elif self.profit_lock is not None and pnl >= self.profit_lock:
+            self._latch("PROFIT_LOCK")
+
+    def _latch(self, reason: str) -> None:
+        self.day_halted = True
+        self.day_halt_reason = reason
+        self._pending_halt_notice = reason
+
+    def consume_halt_notice(self) -> str | None:
+        """Pop the reason of a *newly* latched sticky halt (for flatten_on_halt /
+        notifier), or None if nothing new latched since the last call."""
+        notice = self._pending_halt_notice
+        self._pending_halt_notice = None
+        return notice
+
+    # ------------------------------------------------------------- ingestion
+
+    def record_order(self, ts: datetime, instrument: str, side: Side, qty: int) -> None:
+        """Book a submitted order (feeds rate-limit / duplicate / cooldown)."""
+        require_aware(ts, "ts")
+        self.roll_if_needed(ts)
+        self._order_events.append(OrderEvent(ts=ts, instrument=instrument, side=side, qty=qty))
+        self.last_order_ts = ts
+        self.first_order_done = True
+        self.max_order_qty = max(self.max_order_qty, qty)
+
+    def record_execution(
+        self,
+        ts: datetime,
+        instrument: str,
+        side: Side,
+        qty: int,
+        price: float,
+        *,
+        commission: float = 0.0,
+        exec_id: str | None = None,
+    ) -> float:
+        """Book a fill. Average-cost method: a position-reducing fill books
+        (price - avg) * closed_qty * point_value (sign-adjusted) into the day
+        ledger; a flip re-opens the remainder at the fill price. Commission
+        is subtracted from realized (Crucible's approximation). Returns the
+        realized P&L delta. A realized loss on a closing fill stamps
+        `last_loss_ts` (cooldown guardrail); pure opens do not.
+
+        Idempotent by `exec_id` (FIX 3): a redelivered execution with an
+        already-booked exec_id is a no-op (returns 0.0), so a replayed fill
+        cannot double-count position or realized P&L. exec_id=None disables
+        dedup (direct test bookings)."""
+        require_aware(ts, "ts")
+        if qty <= 0:
+            raise ValueError(f"qty must be positive (got {qty})")
+        if exec_id is not None:
+            if exec_id in self._booked_exec_ids:
+                return 0.0
+            self._booked_exec_ids.add(exec_id)
+        self.roll_if_needed(ts)
+
+        pos = self._positions.setdefault(instrument, _Position())
+        signed = qty if side == "BUY" else -qty
+        realized = 0.0
+        closed_qty = 0
+
+        if pos.qty != 0 and (pos.qty > 0) != (signed > 0):
+            closed_qty = min(abs(signed), abs(pos.qty))
+            direction = 1.0 if pos.qty > 0 else -1.0
+            realized = (price - pos.avg_px) * closed_qty * self.point_value * direction
+
+        new_qty = pos.qty + signed
+        if pos.qty == 0 or (pos.qty > 0) == (signed > 0):
+            # opening / adding: volume-weighted average price
+            total = abs(pos.qty) + qty
+            pos.avg_px = (pos.avg_px * abs(pos.qty) + price * qty) / total
+        elif abs(signed) > abs(pos.qty):
+            pos.avg_px = price  # flip: remainder opens at the fill price
+        elif new_qty == 0:
+            pos.avg_px = 0.0
+        pos.qty = new_qty
+
+        realized -= commission
+        self.day_realized += realized
+        if closed_qty > 0 and realized < 0:
+            self.last_loss_ts = ts
+        self._evaluate_halt()
+        return realized
+
+    def set_unrealized(self, value: float) -> None:
+        """Unrealized P&L as reported by the AddOn's account_state message."""
+        self.unrealized = value
+        self._evaluate_halt()
+
+    def set_link(self, up: bool) -> None:
+        self.link_up = up
+
+    # ------------------------------------------------------------- reads
+
+    def position(self, instrument: str) -> int:
+        pos = self._positions.get(instrument)
+        return pos.qty if pos is not None else 0
+
+    @property
+    def day_pnl(self) -> float:
+        return self.day_realized + self.unrealized
+
+    def snapshot(self, now: datetime, *, kill_engaged: bool = False) -> AccountSnapshot:
+        """The frozen per-account snapshot the guardrail engine checks
+        against. Rolls the ledger first, so a stale book can never leak
+        yesterday's P&L into today's decisions."""
+        self.roll_if_needed(now)
+        self._evaluate_halt()
+        return AccountSnapshot(
+            account=self.account,
+            kill_engaged=kill_engaged,
+            link_up=self.link_up,
+            day_realized=self.day_realized,
+            unrealized=self.unrealized,
+            positions={k: p.qty for k, p in self._positions.items() if p.qty != 0},
+            order_events=tuple(self._order_events),
+            last_loss_ts=self.last_loss_ts,
+            last_order_ts=self.last_order_ts,
+            first_order_done=self.first_order_done,
+            max_order_qty=self.max_order_qty,
+            day_halted=self.day_halted,
+            day_halt_reason=self.day_halt_reason,
+        )

pitbridge/adapter.py

@@ -0,0 +1,53 @@
+"""Platform-adapter seam (Tradovate-readiness — architect M2 follow-up).
+
+The frozen pipeline and the executor depend on this `PlatformAdapter` Protocol,
+not on the concrete `AddonLink`, so a second broker adapter (e.g. Tradovate's
+WS user-sync) can slot in behind the same safety kernel without touching
+pipeline/executor. The NT8 AddOn link (`addonlink.AddonLink`) implements the
+Protocol structurally — no behaviour change, pure decoupling.
+
+The broker order-state vocabulary (NinjaTrader `OrderState` strings) also lives
+here rather than in the executor, so the executor stays vocabulary-neutral: it
+applies whatever `state -> Status` mapper it is handed. A Tradovate adapter
+ships its own map.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+from pitbridge.protocol import SubmitOrderPayload
+
+if TYPE_CHECKING:
+    from pitbridge.executor import Status
+
+
+@runtime_checkable
+class PlatformAdapter(Protocol):
+    """The broker-link surface the pipeline + executor depend on. Generic verbs
+    only (submit/cancel/close/flatten + link freshness); no NT-specific naming
+    leaks into the kernel. `AddonLink` satisfies it; a Tradovate adapter will."""
+
+    async def send_submit_order(self, payload: SubmitOrderPayload) -> None: ...
+    async def send_cancel_order(self, client_order_id: str, account: str) -> None: ...
+    async def send_close_position(self, account: str, instrument: str) -> None: ...
+    async def send_flatten_all(self, account: str) -> None: ...
+    def check_staleness(self, now: datetime | None = None) -> None: ...
+
+
+# NinjaTrader broker OrderState -> executor Status. Moved out of executor.py so
+# the executor holds no broker vocabulary; the NT8 adapter owns this table.
+NT_STATE_TO_STATUS: dict[str, Status] = {
+    "Accepted": "ACKED",
+    "Working": "WORKING",
+    "PartFilled": "PARTFILLED",
+    "Filled": "FILLED",
+    "Rejected": "REJECTED",
+    "Cancelled": "CANCELLED",
+}
+
+
+def nt_state_to_status(state: str) -> Status:
+    """Map a NinjaTrader OrderState string to the executor's Status."""
+    return NT_STATE_TO_STATUS[state]

pitbridge/addonlink.py

@@ -0,0 +1,369 @@
+"""WS endpoint /v1/addon — the AddOn link.
+
+Contract (architecture.md section 2.3): the AddOn connects OUT to
+ws://<daemon>:8873/v1/addon (never a listener on the NT8 box). This module
+owns the daemon side of that link, independent of the transport:
+
+- hello + token auth (wrong/absent token -> close), hello_ack with a
+  session id, heartbeats both ways (5 s), link DOWN after 15 s of silence.
+- inbound dispatch (snapshot / order_update / execution / position_update /
+  account_state / heartbeat / error), deduped by envelope id (bounded set).
+- reconnect reconcile: on (re)connect the daemon sends request_snapshot and
+  reconciles in-flight client_order_ids against the broker's working orders
+  (broker = source of truth).
+- reconcile-first HARD (M1 review follow-up): a link is not 'fresh' — and so
+  the link-down/staleness guard keeps blocking new orders — until the FIRST
+  account_state arrives for an account after (re)connect. A snapshot alone
+  does not make the link fresh.
+- flatten_on_halt: when a sticky day-halt latches on an account_state, send
+  flatten_account (if the account opted in) and audit it.
+
+Transport-agnostic: `AddonLink.serve(transport)` drives any object satisfying
+the `Transport` protocol. The FastAPI /v1/addon route (rest.py) adapts a
+Starlette WebSocket; tests drive an in-memory `memory_pair()`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from collections import deque
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Protocol
+
+from pitbridge.accounts import AccountBook
+from pitbridge.audit import AuditLog
+from pitbridge.config import AccountConfig
+from pitbridge.executor import Executor
+from pitbridge.notify import Notifier
+from pitbridge.protocol import (
+    AccountStatePayload,
+    Envelope,
+    ExecutionPayload,
+    FlattenAllPayload,
+    HelloAckPayload,
+    HelloPayload,
+    OrderUpdatePayload,
+    ProtocolError,
+    RequestSnapshotPayload,
+    SnapshotPayload,
+    SubmitOrderPayload,
+    new_id,
+)
+
+HEARTBEAT_INTERVAL_S = 5
+STALE_AFTER_S = 15.0
+_SEEN_IDS_MAX = 4096
+
+
+class TransportClosed(Exception):
+    """The underlying transport is closed; recv/send cannot continue."""
+
+
+class Transport(Protocol):
+    async def send(self, text: str) -> None: ...
+    async def recv(self) -> str: ...  # raises TransportClosed when closed
+    async def close(self) -> None: ...
+
+
+class MemoryTransport:
+    """In-memory paired transport for tests + the fake AddOn. One side's send
+    is the other side's recv."""
+
+    def __init__(self, inbox: asyncio.Queue, outbox: asyncio.Queue) -> None:
+        self._inbox = inbox
+        self._outbox = outbox
+        self._closed = False
+
+    async def send(self, text: str) -> None:
+        if self._closed:
+            raise TransportClosed
+        await self._outbox.put(text)
+
+    async def recv(self) -> str:
+        item = await self._inbox.get()
+        if item is None:  # close sentinel
+            raise TransportClosed
+        return item
+
+    async def close(self) -> None:
+        if not self._closed:
+            self._closed = True
+            await self._outbox.put(None)
+
+
+def memory_pair() -> tuple[MemoryTransport, MemoryTransport]:
+    """(daemon_side, addon_side) connected transports."""
+    a: asyncio.Queue = asyncio.Queue()
+    b: asyncio.Queue = asyncio.Queue()
+    return MemoryTransport(inbox=a, outbox=b), MemoryTransport(inbox=b, outbox=a)
+
+
+@dataclass
+class AccountEntry:
+    alias: str
+    config: AccountConfig
+    book: AccountBook
+
+
+@dataclass
+class AddonLink:
+    """Daemon side of one AddOn WebSocket link. One instance per daemon; a new
+    connection replaces the previous transport (single AddOn in v0)."""
+
+    accounts: dict[str, AccountEntry]  # keyed by nt_account
+    executor: Executor | None = None
+    audit: AuditLog | None = None
+    notifier: Notifier = field(default_factory=Notifier)
+    token: str | None = None
+    server_version: str = "0.1.0"
+    heartbeat_interval_s: int = HEARTBEAT_INTERVAL_S
+    stale_after_s: float = STALE_AFTER_S
+    clock: Callable[[], datetime] = field(default=lambda: datetime.now(UTC))
+
+    # runtime state
+    session_id: str | None = field(default=None, init=False)
+    connected: bool = field(default=False, init=False)
+    _transport: Transport | None = field(default=None, init=False)
+    _seq_out: int = field(default=0, init=False)
+    _last_rx: datetime | None = field(default=None, init=False)
+    _fresh_accounts: set[str] = field(default_factory=set, init=False)
+    _seen_ids: deque[str] = field(default_factory=lambda: deque(maxlen=_SEEN_IDS_MAX), init=False)
+    _seen_set: set[str] = field(default_factory=set, init=False)
+
+    # ------------------------------------------------------------- link status
+
+    def is_fresh(self, account_nt: str, now: datetime | None = None) -> bool:
+        """A link is fresh for an account only after its first post-connect
+        account_state AND within the staleness window (reconcile-first hard)."""
+        if not self.connected or account_nt not in self._fresh_accounts:
+            return False
+        if self._last_rx is None:
+            return False
+        now = now or self.clock()
+        return (now - self._last_rx).total_seconds() <= self.stale_after_s
+
+    def _refresh_links(self, now: datetime | None = None) -> None:
+        now = now or self.clock()
+        for nt, entry in self.accounts.items():
+            entry.book.set_link(self.is_fresh(nt, now))
+
+    def mark_all_links_down(self) -> None:
+        for entry in self.accounts.values():
+            entry.book.set_link(False)
+
+    def check_staleness(self, now: datetime | None = None) -> None:
+        """Re-evaluate link freshness against the clock (heartbeat sweeper)."""
+        self._refresh_links(now)
+
+    # ------------------------------------------------------------- outbound
+
+    def _next_seq(self) -> int:
+        seq = self._seq_out
+        self._seq_out += 1
+        return seq
+
+    async def _send(self, type_: str, payload) -> None:
+        transport = self._transport
+        if transport is None:
+            raise TransportClosed
+        env = Envelope.build(type_, payload, seq=self._next_seq())
+        await transport.send(env.to_json())
+
+    async def send_submit_order(self, payload: SubmitOrderPayload) -> None:
+        await self._send("submit_order", payload)
+
+    async def send_cancel_order(self, client_order_id: str, account: str) -> None:
+        await self._send("cancel_order",
+                         {"client_order_id": client_order_id, "account": account})
+
+    async def send_close_position(self, account: str, instrument: str) -> None:
+        await self._send("close_position", {"account": account, "instrument": instrument})
+
+    async def send_flatten_all(self, account: str) -> None:
+        await self._send("flatten_all", FlattenAllPayload(account=account))
+
+    async def send_request_snapshot(self, account: str | None = None) -> None:
+        await self._send("request_snapshot", RequestSnapshotPayload(account=account))
+
+    async def send_heartbeat(self) -> None:
+        await self._send("heartbeat", {})
+
+    # ------------------------------------------------------------- lifecycle
+
+    async def serve(self, transport: Transport) -> None:
+        """Handle one connection start-to-finish. Returns when it closes."""
+        self._transport = transport
+        try:
+            hello = await self._await_hello(transport)
+        except TransportClosed:
+            return
+        if hello is None:
+            return  # auth failed; transport already closed
+        await self._accept(hello)
+        hb_task = asyncio.create_task(self._heartbeat_loop())
+        try:
+            await self._receive_loop(transport)
+        finally:
+            hb_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await hb_task
+            self._on_disconnect()
+
+    async def _await_hello(self, transport: Transport) -> HelloPayload | None:
+        raw = await transport.recv()
+        try:
+            env = Envelope.from_json(raw)
+        except ProtocolError:
+            await self._reject(transport, "BAD_FRAME", "first frame is not a valid envelope")
+            return None
+        if env.type != "hello":
+            await self._reject(transport, "EXPECTED_HELLO", f"first frame was {env.type!r}")
+            return None
+        hello = env.decode()
+        if self.token is not None and hello.token != self.token:
+            await self._reject(transport, "BAD_TOKEN", "pairing token missing or wrong")
+            return None
+        return hello
+
+    async def _reject(self, transport: Transport, code: str, message: str) -> None:
+        with contextlib.suppress(Exception):
+            env = Envelope.build("error", {"code": code, "message": message}, seq=self._next_seq())
+            await transport.send(env.to_json())
+            await transport.close()
+
+    async def _accept(self, hello: HelloPayload) -> None:
+        self.session_id = new_id()
+        self.connected = True
+        self._last_rx = self.clock()
+        self._fresh_accounts.clear()
+        self.mark_all_links_down()  # reconcile-first: not fresh until account_state
+        await self._send(
+            "hello_ack",
+            HelloAckPayload(
+                session_id=self.session_id,
+                heartbeat_interval_s=self.heartbeat_interval_s,
+                server_version=self.server_version,
+            ),
+        )
+        await self.send_request_snapshot(None)  # reconcile before deciding
+
+    def _on_disconnect(self) -> None:
+        self.connected = False
+        self._transport = None
+        self._fresh_accounts.clear()
+        self.mark_all_links_down()
+
+    async def _heartbeat_loop(self) -> None:
+        while True:
+            await asyncio.sleep(self.heartbeat_interval_s)
+            self.check_staleness()
+            with contextlib.suppress(TransportClosed):
+                await self.send_heartbeat()
+
+    async def _receive_loop(self, transport: Transport) -> None:
+        while True:
+            try:
+                raw = await transport.recv()
+            except TransportClosed:
+                return
+            try:
+                env = Envelope.from_json(raw)
+            except ProtocolError:
+                continue  # ignore malformed frame, keep the link
+            self._last_rx = self.clock()
+            if env.id in self._seen_set:
+                continue  # duplicate delivery -> idempotent no-op
+            self._remember(env.id)
+            self._dispatch(env)
+
+    def _remember(self, msg_id: str) -> None:
+        if len(self._seen_ids) == self._seen_ids.maxlen:
+            oldest = self._seen_ids[0]
+            self._seen_set.discard(oldest)
+        self._seen_ids.append(msg_id)
+        self._seen_set.add(msg_id)
+
+    # ------------------------------------------------------------- dispatch
+
+    def _dispatch(self, env: Envelope) -> None:
+        handler = getattr(self, f"_on_{env.type}", None)
+        if handler is None:
+            return
+        handler(env.decode())
+
+    def _on_heartbeat(self, _payload) -> None:
+        self._refresh_links()
+
+    def _on_error(self, payload) -> None:
+        self.notifier.notify("addon_error", payload.message, code=payload.code)
+
+    def _on_snapshot(self, payload: SnapshotPayload) -> None:
+        entry = self.accounts.get(payload.account)
+        if entry is None:
+            return
+        # reconcile in-flight ids against the broker's working orders — SCOPED to this
+        # account so an account-A snapshot cannot CANCEL account-B's in-flight orders.
+        if self.executor is not None:
+            changes = self.executor.reconcile(
+                payload.working_orders, account=payload.account
+            )
+            if changes and self.audit is not None:
+                self.audit.append(
+                    "reconcile",
+                    {"account": payload.account, "changes": changes},
+                    account=entry.alias,
+                )
+        # a snapshot does NOT mark the link fresh (reconcile-first hard)
+
+    def _on_account_state(self, payload: AccountStatePayload) -> None:
+        entry = self.accounts.get(payload.account)
+        if entry is None:
+            return
+        entry.book.set_unrealized(payload.unrealized_pnl)
+        self._fresh_accounts.add(payload.account)  # link is now fresh for this account
+        self._refresh_links()
+        self._maybe_flatten_on_halt(entry)
+
+    def _on_position_update(self, _payload) -> None:
+        # positions are authoritative via snapshot/executions in v0; noted for M4.
+        return
+
+    def _on_order_update(self, payload: OrderUpdatePayload) -> None:
+        if self.executor is not None:
+            self.executor.on_order_update(payload)
+
+    def _on_execution(self, payload: ExecutionPayload) -> None:
+        entry = self.accounts.get(payload.account)
+        if entry is not None:
+            entry.book.record_execution(
+                self.clock(), payload.instrument, payload.action, payload.qty,
+                payload.price, commission=payload.commission, exec_id=payload.exec_id,
+            )
+            self._maybe_flatten_on_halt(entry)
+        if self.executor is not None:
+            self.executor.on_execution(payload)
+
+    def _maybe_flatten_on_halt(self, entry: AccountEntry) -> None:
+        reason = entry.book.consume_halt_notice()
+        if reason is None:
+            return
+        self.notifier.notify(
+            "day_halt", f"{entry.alias}: sticky day-halt latched ({reason})",
+            account=entry.alias, reason=reason,
+        )
+        if self.audit is not None:
+            self.audit.append("day_halt", {"reason": reason}, account=entry.alias)
+        if entry.config.flatten_on_halt:
+            asyncio.ensure_future(self._flatten_on_halt(entry))  # noqa: RUF006
+
+    async def _flatten_on_halt(self, entry: AccountEntry) -> None:
+        with contextlib.suppress(TransportClosed):
+            await self.send_flatten_all(entry.config.nt_account)
+            if self.audit is not None:
+                self.audit.append(
+                    "flatten_on_halt", {"account": entry.config.nt_account},
+                    account=entry.alias,
+                )