opencode-pyneruntime 6.6.4__py3-none-any.whl

pynecore/core/broker/emulator.py

@@ -0,0 +1,345 @@
+"""One-way position emulation over a hedging- or netting-mode broker.
+
+A hedging cTrader account can hold several simultaneous open positions ("legs")
+for one symbol — each with its own broker position id. Pine Script strategies,
+however, see a single *one-way* position per symbol: at most one direction at a
+time, opposite orders reduce and then flip it. This module is the core bridge
+between the two representations, so a broker plugin only has to provide thin
+transport primitives (``fetch_raw_positions`` / ``close_leg`` / ``place_leg``)
+and carries none of the netting logic itself.
+
+The two responsibilities live here as pure functions:
+
+* :func:`aggregate_positions` collapses the raw legs into the single
+  :class:`~pynecore.core.broker.models.ExchangePosition` the sync engine reads.
+* :func:`select_legs_for_close` and :func:`plan_reversal` decide *which* legs to
+  close, and by how much, for a reduce / close / reversal — always oldest-first
+  (FIFO), matching Pine's trade accounting and giving replay-stable plans.
+
+Aggregation tolerates transient opposite-direction legs (e.g. a pre-existing
+manual hedge, or the instant between a reversal's close and open): the minority
+side is netted virtually-FIFO against the oldest majority legs, and the
+surviving side's volume-weighted price becomes the one-way entry price.
+"""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from pynecore.core.broker.models import ExchangePosition, PositionLeg
+
+__all__ = [
+    'LegClose',
+    'ReversalPlan',
+    'net_signed_qty',
+    'aggregate_positions',
+    'select_legs_for_close',
+    'plan_reversal',
+    'plan_leg_close_volumes',
+    'legs_on_position_side',
+    'net_survivor_legs',
+]
+
+# Quantities are in Pine units (fractional lots possible). Anything below this
+# is treated as flat / fully consumed — coarse enough to absorb broker rounding,
+# fine enough never to swallow a real partial lot.
+_QTY_EPS = 1e-9
+
+
+@dataclass(frozen=True)
+class LegClose:
+    """A single planned leg reduction: close ``qty`` of broker leg ``leg_id``."""
+    leg_id: str
+    qty: float
+
+
+@dataclass(frozen=True)
+class ReversalPlan:
+    """Decomposition of a one-way order against the current legs.
+
+    Produced by :func:`plan_reversal` for an order whose direction may oppose
+    the open position. The order is split into a FIFO close of the opposing
+    legs plus a residual open in the order's own direction.
+
+    :ivar closes: Opposing legs to close (oldest first) and by how much. Empty
+        when the order only adds to the existing direction.
+    :ivar open_qty: Residual size to open in the order's direction after the
+        closes. Zero when the order exactly flattens the opposite exposure.
+    :ivar open_side: The order's direction (``"buy"`` / ``"sell"``); the side
+        of any residual open.
+    """
+    closes: tuple[LegClose, ...]
+    open_qty: float
+    open_side: str
+
+
+def net_signed_qty(legs: list[PositionLeg]) -> float:
+    """Signed net size across legs: long (``buy``) positive, short negative."""
+    return sum(leg.qty if leg.side == 'buy' else -leg.qty for leg in legs)
+
+
+def _surviving_weighted_avg(legs: list[PositionLeg], keep_side: str) -> float:
+    """Volume-weighted entry price of ``keep_side`` after virtual-FIFO netting.
+
+    The opposite-side legs virtually close the oldest ``keep_side`` legs first
+    (FIFO), exactly as a real reducing fill would; the price returned is the
+    weighted average of whatever ``keep_side`` volume survives. Returns ``0.0``
+    when nothing survives (fully netted).
+    """
+    survivors = sorted(
+        (leg for leg in legs if leg.side == keep_side),
+        key=lambda leg: (leg.open_time, leg.leg_id),
+    )
+    offset = sum(leg.qty for leg in legs if leg.side != keep_side)
+    qty_acc = 0.0
+    notional = 0.0
+    for leg in survivors:
+        remaining = leg.qty
+        if offset > 0.0:
+            consumed = min(remaining, offset)
+            offset -= consumed
+            remaining -= consumed
+        if remaining > _QTY_EPS:
+            qty_acc += remaining
+            notional += remaining * leg.entry_price
+    return notional / qty_acc if qty_acc > _QTY_EPS else 0.0
+
+
+def aggregate_positions(
+        symbol: str,
+        legs: list[PositionLeg],
+        *,
+        leverage: float = 1.0,
+        margin_mode: str = 'cross',
+) -> ExchangePosition | None:
+    """Collapse raw broker legs into one net one-way position snapshot.
+
+    The net signed size decides the side; the surviving side's virtual-FIFO
+    weighted-average price is the entry price; unrealized P&L is the plain sum
+    of every leg's mark-to-market (correct regardless of leg direction).
+
+    :param symbol: Pine symbol the legs belong to.
+    :param legs: All open legs for ``symbol`` (any direction). May be empty.
+    :param leverage: Carried onto the snapshot; legs do not report it per-leg.
+    :param margin_mode: Carried onto the snapshot.
+    :return: The aggregated :class:`ExchangePosition`, or ``None`` when there
+        are no legs at all (a genuinely flat symbol — distinct from a netted
+        ``flat`` snapshot, which is only produced when offsetting legs remain
+        open but sum to zero).
+    """
+    if not legs:
+        return None
+    net = net_signed_qty(legs)
+    unrealized = sum(leg.unrealized_pnl for leg in legs)
+    if abs(net) <= _QTY_EPS:
+        # Offsetting legs still open but net flat — surface it as flat with the
+        # residual gross P&L so a caller can spot a stuck hedge rather than a
+        # clean flat.
+        return ExchangePosition(
+            symbol=symbol, side='flat', size=0.0, entry_price=0.0,
+            unrealized_pnl=unrealized, liquidation_price=None,
+            leverage=leverage, margin_mode=margin_mode,
+        )
+    keep_side = 'buy' if net > 0.0 else 'sell'
+    return ExchangePosition(
+        symbol=symbol,
+        side='long' if net > 0.0 else 'short',
+        size=abs(net),
+        entry_price=_surviving_weighted_avg(legs, keep_side),
+        unrealized_pnl=unrealized,
+        liquidation_price=None,
+        leverage=leverage,
+        margin_mode=margin_mode,
+    )
+
+
+def select_legs_for_close(
+        qty: float, legs: list[PositionLeg], side: str,
+) -> tuple[tuple[LegClose, ...], float]:
+    """Pick which ``side`` legs to close for a ``qty`` reduction, oldest first.
+
+    FIFO by :attr:`~pynecore.core.broker.models.PositionLeg.open_time` so the
+    plan matches Pine's oldest-trade-first close order and is deterministic
+    across restarts (a replay sees the same legs in the same order).
+
+    :param qty: Total size to close (positive).
+    :param legs: All open legs for the symbol; only those on ``side`` are
+        considered.
+    :param side: Direction of the legs to reduce (``"buy"`` for a long
+        position, ``"sell"`` for a short).
+    :return: ``(closes, shortfall)`` — the per-leg close plan and any quantity
+        that could not be covered because the open legs summed to less than
+        ``qty`` (``0.0`` in the normal case). A non-zero shortfall is the
+        caller's signal that the broker holds less than Pine believes.
+    """
+    candidates = sorted(
+        (leg for leg in legs if leg.side == side),
+        # ``leg_id`` is the stable secondary key: two legs sharing an
+        # ``open_time`` must close in the same order across a restart even if
+        # the broker returns them in a different sequence, so the plan stays
+        # replay-deterministic as the FIFO docstring promises.
+        key=lambda leg: (leg.open_time, leg.leg_id),
+    )
+    closes: list[LegClose] = []
+    remaining = qty
+    for leg in candidates:
+        if remaining <= _QTY_EPS:
+            break
+        take = min(leg.qty, remaining)
+        if take > _QTY_EPS:
+            closes.append(LegClose(leg_id=leg.leg_id, qty=take))
+            remaining -= take
+    # A residual at or below the tolerance is fully covered as far as the rest
+    # of the module is concerned (the loop already stops consuming it), so it
+    # must not leak out as a spurious positive shortfall for broker-rounded
+    # quantities such as qty=1.0 against an open leg of 0.9999999995.
+    return tuple(closes), remaining if remaining > _QTY_EPS else 0.0
+
+
+def plan_reversal(
+        side: str, qty: float, legs: list[PositionLeg],
+) -> ReversalPlan:
+    """Split a one-way order into opposite-leg closes plus a residual open.
+
+    Pine folds a reversal into one combined order whose size is
+    ``target + |opposite_net|`` (it assumes a netting auto-flip). On a hedging
+    account that single order would instead open a separate opposing leg and
+    bloat gross exposure, so the order is decomposed: close the opposing legs
+    FIFO (up to the order size), then open whatever target size remains in the
+    order's own direction.
+
+    Works uniformly for the three shapes a single order can take:
+
+    * **pure add** — no opposing legs: ``closes`` empty, ``open_qty == qty``;
+    * **reversal** — opposing legs smaller than ``qty``: close them all, open
+      the remainder (``qty - opposite_total``) in ``side``;
+    * **partial reduce via order** — ``qty`` ≤ opposing exposure: close
+      ``qty`` worth of opposing legs FIFO, ``open_qty == 0`` (no flip).
+
+    :param side: The order's direction (``"buy"`` / ``"sell"``).
+    :param qty: The combined order size as Pine dispatched it.
+    :param legs: Current open legs for the symbol.
+    :return: A :class:`ReversalPlan`.
+    """
+    opposite_side = 'sell' if side == 'buy' else 'buy'
+    closes, _shortfall = select_legs_for_close(qty, legs, opposite_side)
+    closed_total = sum(close.qty for close in closes)
+    open_qty = qty - closed_total
+    if open_qty < _QTY_EPS:
+        open_qty = 0.0
+    return ReversalPlan(closes=closes, open_qty=open_qty, open_side=side)
+
+
+def plan_leg_close_volumes(
+        closes: tuple[LegClose, ...],
+        quantize: Callable[[float], int],
+) -> list[tuple[str, int]]:
+    """Fan a FIFO close plan out to per-leg broker-grid close volumes.
+
+    Quantizing each FIFO slice independently changes the total close size on the
+    broker's volume grid: a sub-grid slice rounds to ``0`` (an invalid empty
+    close that under-reduces the position) and a fractional-grid slice rounds UP
+    past what the leg holds. Snapping the *total* once is not enough either: if a
+    slice that carries part of the owed total quantizes to ``0`` on its own —
+    e.g. two 10-unit legs on a 1000-centi grid closing 15 units, where the
+    second 5-unit slice snaps to ``0`` — per-slice rounded volumes leave the
+    snapped total under-dispatched.
+
+    Instead a single running total is snapped via ``quantize``: each leg receives
+    the delta between the snapped cumulative close-through-this-leg and the
+    snapped cumulative through the previous leg, capped at the snapped grand
+    total. The sub-grid remainder a slice would have dropped is carried into the
+    next leg, so the dispatched volumes always sum to the same grand total the
+    single-position close path would use, every volume sits on the broker grid,
+    and no leg gets more than its own slice rounded up to the next grid step. Any
+    leg whose delta is zero is dropped (no zero-volume request is sent).
+
+    :param closes: FIFO close plan (oldest first); each ``qty`` is the slice to
+        take from that leg, in Pine units, never above the leg's open size.
+    :param quantize: Maps a Pine-unit quantity to the broker's integer volume
+        grid (e.g. cTrader centi-units snapped to ``stepVolume``). Owns the
+        broker-specific unit; the FIFO carry logic here stays unit-agnostic.
+    :return: ``(leg_id, volume)`` pairs to dispatch in FIFO order, each with the
+        broker-grid integer ``volume`` the per-leg close expects. ``leg_id``
+        stays the :class:`PositionLeg` string id; the transport casts it.
+    """
+    grand_total = quantize(sum(close.qty for close in closes))
+    out: list[tuple[str, int]] = []
+    cumulative_units = 0.0
+    dispatched = 0
+    for close in closes:
+        if dispatched >= grand_total:
+            break
+        cumulative_units += close.qty
+        snapped = min(quantize(cumulative_units), grand_total)
+        volume = snapped - dispatched
+        if volume <= 0:
+            continue
+        out.append((close.leg_id, volume))
+        dispatched = snapped
+    return out
+
+
+def legs_on_position_side(
+        legs: list[PositionLeg],
+) -> tuple[str, list[PositionLeg]]:
+    """Return the aggregate one-way side and the legs that make it up, FIFO.
+
+    The net signed size decides the side (``'buy'`` for a net-long one-way
+    position, ``'sell'`` for net-short); the returned legs are those on that
+    side, oldest first (FIFO by ``(open_time, leg_id)``) so bracket replication
+    and the fail-safe SL fan-out are replay-stable. A net-flat book (offsetting
+    legs summing to zero, or no legs at all) returns ``('flat', [])``.
+
+    Replaces the ``'buy' if side == 'long' else 'sell'`` + filter that bracket
+    replication, modify, clear, and fail-safe each used to inline.
+    """
+    net = net_signed_qty(legs)
+    if abs(net) <= _QTY_EPS:
+        return 'flat', []
+    side = 'buy' if net > 0.0 else 'sell'
+    survivors = sorted(
+        (leg for leg in legs if leg.side == side),
+        key=lambda leg: (leg.open_time, leg.leg_id),
+    )
+    return side, survivors
+
+
+def net_survivor_legs(
+        legs: list[PositionLeg],
+) -> tuple[str, list[PositionLeg]]:
+    """Return the one-way side and only the legs that survive virtual-FIFO netting.
+
+    Like :func:`legs_on_position_side`, but on a *mixed* book (legs open on both
+    sides) it drops the oldest majority-side legs that the opposing legs
+    virtually FIFO-close, returning only the legs that actually make up the net
+    one-way position :func:`aggregate_positions` reports — a leg is kept iff any
+    of its volume survives the netting, oldest first. A clean one-way book (no
+    opposing legs) is unaffected: every majority leg survives, identical to
+    :func:`legs_on_position_side`. A net-flat book returns ``('flat', [])``.
+
+    Bracket replication uses this rather than :func:`legs_on_position_side` so a
+    protective stop is amended onto the net exposure only. A mixed book never
+    arises from the emulator itself (it FIFO-closes the opposing side before
+    opening), only from a pre-existing manual hedge or a crash-interrupted
+    reversal; there the gross majority legs exceed the net, and protecting all of
+    them would close more than the position and flip it to the minority side.
+    """
+    net = net_signed_qty(legs)
+    if abs(net) <= _QTY_EPS:
+        return 'flat', []
+    side = 'buy' if net > 0.0 else 'sell'
+    survivors = sorted(
+        (leg for leg in legs if leg.side == side),
+        key=lambda leg: (leg.open_time, leg.leg_id),
+    )
+    offset = sum(leg.qty for leg in legs if leg.side != side)
+    kept: list[PositionLeg] = []
+    for leg in survivors:
+        remaining = leg.qty
+        if offset > 0.0:
+            consumed = min(remaining, offset)
+            offset -= consumed
+            remaining -= consumed
+        if remaining > _QTY_EPS:
+            kept.append(leg)
+    return side, kept

pynecore/core/broker/exceptions.py

@@ -0,0 +1,346 @@
+"""
+Broker-related exception hierarchy.
+
+All broker plugin and order-sync errors derive from :class:`BrokerError`.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pynecore.core.broker.models import ExchangeOrder
+
+__all__ = [
+    'AuthenticationError',
+    'BracketAttachAfterFillRejectedError',
+    'BrokerError',
+    'BrokerManualInterventionError',
+    'ClientOrderIdSpentError',
+    'ExchangeCapabilityError',
+    'ExchangeConnectionError',
+    'ExchangeOrderRejectedError',
+    'ExchangeRateLimitError',
+    'InsufficientMarginError',
+    'OrderDispositionUnknownError',
+    'OrderSkippedByPlugin',
+    'OrderSyncError',
+    'SpotInventoryConflictError',
+    'UnexpectedCancelError',
+]
+
+
+class BrokerError(RuntimeError):
+    """Base class for all broker-related errors."""
+
+
+class AuthenticationError(BrokerError):
+    """The exchange rejected the plugin's credentials.
+
+    Raised when the exchange returns 401 / 403, reports an invalid API key,
+    or bans the source IP. Semantics are **terminal** — reconnect cannot
+    recover, the user must fix the credentials. The Script Runner treats
+    this as a graceful-stop condition at startup and surfaces an
+    :class:`~pynecore.core.broker.models.AuthenticationFailedEvent` so the
+    observability layer can page.
+
+    :ivar reason: Short human-readable cause (echoed on the event).
+    """
+
+    def __init__(self, message: str, reason: str = "") -> None:
+        super().__init__(message)
+        self.reason = reason or message
+
+
+class ExchangeCapabilityError(BrokerError):
+    """The exchange does not support a required feature.
+
+    Raised by a BrokerPlugin when asked to do something its exchange cannot do
+    (e.g. a TP+SL bracket with OCA reduce semantics on an exchange without
+    native support for it). Treated as a graceful-stop condition at startup.
+    """
+
+
+class ExchangeConnectionError(BrokerError):
+    """Connection to the exchange was lost.
+
+    The Order Sync Engine is expected to reconnect and then reconcile state
+    before resuming normal operation.
+    """
+
+
+class ExchangeOrderRejectedError(BrokerError):
+    """The exchange rejected an order.
+
+    :ivar order: The rejected order as it is known locally, or ``None`` if the
+        order never made it far enough to have an exchange representation.
+    """
+
+    def __init__(self, message: str, order: 'ExchangeOrder | None' = None) -> None:
+        super().__init__(message)
+        self.order = order
+
+
+class InsufficientMarginError(ExchangeOrderRejectedError):
+    """The exchange rejected an order for insufficient margin / balance.
+
+    A typed sub-class of :class:`ExchangeOrderRejectedError` so the risk
+    layer can pattern-match the reason without string-parsing the exchange
+    message. Intent-level reject — non-terminal, the runner keeps going and
+    the strategy can respond (e.g. shrink size, back off).
+    """
+
+
+class ClientOrderIdSpentError(ExchangeOrderRejectedError):
+    """A create was refused because the deterministic client order id is
+    already consumed by a now-terminal order, on a venue that never allows
+    client-id reuse (Bybit rejects re-creation under a cancelled order's
+    ``orderLinkId``: spot retCode 170141, derivatives 110072 — measured
+    live). The default cancel+recreate modify path re-sends the same
+    pinned id, so on such venues the recreate collides with the id the
+    cancel just spent.
+
+    Contract for plugins: raise ONLY after verifying that nothing is live
+    under the id (the duplicate lookup returned a terminal, dead order —
+    not a fill) and after cleaning up any sibling orders the same dispatch
+    attempt already placed. The engine responds by re-anchoring the
+    intent's envelope on a bumped ``retry_seq`` and re-dispatching
+    immediately, so the replacement lands under a fresh id instead of the
+    dead order being silently adopted as live.
+    """
+
+
+class BracketAttachAfterFillRejectedError(ExchangeOrderRejectedError):
+    """A protective TP/SL bracket attach was rejected AFTER the parent
+    ENTRY/EXIT fill committed on the exchange.
+
+    Distinct from a plain :class:`ExchangeOrderRejectedError` where no
+    parent fill occurred (e.g. an entry rejected before contacting the
+    exchange — nothing open, nothing to defend). Here the position is
+    *open and unprotected*: the sync engine MUST NOT halt (which would
+    leave the unprotected fill exposed indefinitely), instead it issues a
+    defensive market close to take the position flat.
+
+    The plugin raises this *after* rolling back the persisted leg rows
+    (so the BrokerStore does not leak phantom protective legs). The sync
+    engine's :meth:`_dispatch_new` recovery path catches it, builds a
+    synthetic :class:`~pynecore.core.broker.models.CloseIntent` for the
+    parent position, and dispatches that. The runner continues.
+
+    Engine-side recovery uses a derived
+    :class:`~pynecore.core.broker.models.BracketAttachRejectContext` as
+    the formal hand-off to the plugin's
+    :meth:`~pynecore.core.plugin.broker.BrokerPlugin.get_residual_orders_after_bracket_attach_reject`
+    method — this exception is the *transport* (chained cause, message),
+    the context is the *contract* (data the engine needs to settle the
+    defensive close).
+
+    :ivar position_coid: Client-order-id of the unprotected open position
+        (the parent ENTRY row in BrokerStore). Universal recovery key
+        across plugins — required.
+    :ivar position_side: Side of the OPEN position (``"buy"`` for long,
+        ``"sell"`` for short). The defensive close picks the opposite.
+    :ivar qty: Quantity of the unprotected position (units the close
+        intent must flatten). ``0`` is a *proven-flat* signal — the
+        plugin measured that a racing sibling fill already consumed the
+        entire bracket quantity; the engine then skips the defensive
+        close (nothing remains to flatten) while still running the
+        OCA-cancel / residual-cleanup cascade.
+    :ivar symbol: Trading symbol of the unprotected position.
+    :ivar position_deal_id: Exchange-side identifier of the unprotected
+        open position, when the plugin can supply one. Broker-specific
+        (Capital.com deal id, IB permId, Bybit orderId, ...); optional —
+        recovery must not rely on it for correctness.
+    :ivar from_entry: Pine ``strategy.entry`` id, when the bracket attach
+        originated from a Pine ``strategy.exit``. Used for log
+        correlation; not required for the close itself.
+    :ivar exit_id: Pine ``strategy.exit`` id when applicable.
+    :ivar filled_qty: Parent quantity already filled at the time of the
+        reject. ``None`` falls back to ``qty`` (conservative).
+    :ivar error_code: Exchange-side error code, if any.
+    :ivar error_message: Exchange-side error message, if any.
+    """
+
+    def __init__(
+            self,
+            message: str,
+            *,
+            position_coid: str,
+            symbol: str,
+            position_side: str,
+            qty: float,
+            position_deal_id: str | None = None,
+            from_entry: str | None = None,
+            exit_id: str | None = None,
+            filled_qty: float | None = None,
+            error_code: str | None = None,
+            error_message: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.position_coid = position_coid
+        self.symbol = symbol
+        self.position_side = position_side
+        self.qty = qty
+        self.position_deal_id = position_deal_id
+        self.from_entry = from_entry
+        self.exit_id = exit_id
+        self.filled_qty = filled_qty
+        self.error_code = error_code
+        self.error_message = error_message
+
+
+class ExchangeRateLimitError(BrokerError):
+    """Exchange rate limit was hit.
+
+    :ivar retry_after: Seconds the caller should wait before retrying.
+    """
+
+    def __init__(self, message: str, retry_after: float) -> None:
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class OrderDispositionUnknownError(BrokerError):
+    """A dispatch completed without a definitive accept-or-reject from the exchange.
+
+    Raised by a BrokerPlugin when a submission times out mid-flight or the
+    connection drops before the exchange acknowledges the order — the plugin
+    genuinely does not know whether the order landed. Semantics are
+    deliberately distinct from :class:`ExchangeConnectionError` (recoverable
+    via reconnect) and :class:`ExchangeOrderRejectedError` (the order is known
+    not to exist): the Order Sync Engine reacts by holding the dispatch in a
+    pending-verification queue and matching against
+    :meth:`~pynecore.core.plugin.broker.BrokerPlugin.get_open_orders` on the
+    next sync, keyed by ``client_order_id``.
+
+    :ivar client_order_id: The id the plugin attempted to submit with. The
+        sync engine uses it to match the open-orders query back to the
+        originating dispatch.
+    :ivar cause: The underlying raw exception, if any, preserved for logging.
+    :ivar predecessor_cancel_ids: For an ambiguous MODIFY dispatch, the
+        modify shape the plugin executed before the disposition turned
+        unknown. ``None`` (default) — shape undeclared: the sync engine
+        assumes the plugin's default cancel + re-execute modify and treats a
+        venue CANCELLED push for any currently mapped order id during the
+        park as the engine-initiated predecessor confirmation. An empty
+        tuple — atomic in-place amend, NO predecessor cancel was issued: a
+        CANCELLED push during the park is a genuine external cancel and
+        fires the ``on_unexpected_cancel`` policy. A non-empty tuple — the
+        exchange order ids the plugin cancel-issued before the ambiguous
+        replacement submission; exactly those pushes are consumed as
+        engine-initiated. Meaningful only when raised from
+        ``modify_entry`` / ``modify_exit``-shaped plugin calls.
+    """
+
+    def __init__(
+            self,
+            message: str,
+            client_order_id: str,
+            cause: Exception | None = None,
+            predecessor_cancel_ids: tuple[str, ...] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.client_order_id = client_order_id
+        self.cause = cause
+        self.predecessor_cancel_ids = predecessor_cancel_ids
+
+
+class OrderSkippedByPlugin(BrokerError):
+    """Plugin proactively declined to dispatch — not a failure, no order sent.
+
+    Distinct from :class:`ExchangeOrderRejectedError` (the exchange said no)
+    and :class:`OrderDispositionUnknownError` (network-ambiguous): the plugin
+    short-circuited *before* contacting the exchange because the intent does
+    not satisfy a known venue constraint (e.g. ``intent.qty`` below the
+    instrument's ``min_size``). The Order Sync Engine logs a broker-warning
+    and refuses to register the intent in ``_active_intents``, so the next
+    bar re-evaluates the intent freely — a runtime sizing model that yields
+    a placeable qty later just trades normally without recovery glue.
+
+    :ivar intent_key: The intent's diff key, for engine-side lookups.
+    :ivar reason: Short stable token (e.g. ``"below_min_size"``) for log
+        filtering and programmatic policy.
+    :ivar context: Plugin-supplied diagnostic dictionary (symbol, qty,
+        min_size, …) for operator triage.
+    """
+
+    def __init__(
+            self,
+            message: str,
+            *,
+            intent_key: str,
+            reason: str = "",
+            context: dict | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.intent_key = intent_key
+        self.reason = reason
+        self.context = context or {}
+
+
+class OrderSyncError(BrokerError):
+    """Exchange state diverged from the expected internal state."""
+
+
+class BrokerManualInterventionError(BrokerError):
+    """Automated execution cannot safely continue — a human must resolve
+    broker-side ambiguity before the strategy runs again.
+
+    Raised by a BrokerPlugin when reconcile or recovery logic encounters a
+    state that cannot be resolved without risking an incorrect trade — e.g.
+    a partial-close race whose reverse leg cannot be confidently identified,
+    or a crash-recovery heuristic that finds multiple candidate deals for a
+    single submitted intent. Semantics are **terminal**: the sync engine
+    halts all further dispatches and the runner performs a graceful stop.
+    Distinct from :class:`ExchangeOrderRejectedError` (the order is known
+    not to exist) and :class:`OrderDispositionUnknownError` (the plugin
+    parks and retries on next sync) — manual intervention signals that
+    *automated* recovery cannot proceed safely.
+
+    :ivar reason: Human-readable description of the ambiguity.
+    :ivar intent_key: The intent's diff key, if the ambiguity relates to a
+        specific in-flight intent. ``None`` for orphan/recovery cases.
+    :ivar context: Plugin-supplied diagnostic dictionary (e.g. candidate
+        deal ids, snapshot totals, timing) for operator triage.
+    """
+
+    def __init__(
+            self,
+            reason: str,
+            *,
+            intent_key: str | None = None,
+            context: dict | None = None,
+    ) -> None:
+        super().__init__(reason)
+        self.reason = reason
+        self.intent_key = intent_key
+        self.context = context or {}
+
+
+class SpotInventoryConflictError(BrokerManualInterventionError):
+    """The spot balance invariant broke or the bot's inventory ownership
+    could not be established.
+
+    Raised by the :class:`~pynecore.core.broker.spot_inventory.SpotInventoryManager`
+    when the ``halt`` inventory-conflict policy is active (or as the
+    fail-safe fallback when the quarantine hook is missing / raising):
+    an unexplainable base-balance drift in either direction, a corrupt
+    or foreign ledger row, an inconclusive execution catch-up, or a
+    lost asset-ownership lease. External intervention in the bot's
+    inventory is not supported — there is no adoption path, so the safe
+    terminal signal is manual intervention followed by an operator
+    ``rebaseline``.
+    """
+
+
+class UnexpectedCancelError(BrokerManualInterventionError):
+    """A bot-owned order disappeared without the bot having cancelled it.
+
+    Indicates external interference (manual user action, exchange-side
+    maintenance, margin-induced cancel, etc.). Modelled as a manual-
+    intervention error because automated recovery cannot reason about why
+    the order vanished — the safe default is to halt and let a human
+    inspect. The sync engine's :meth:`run_event_stream` and dispatch paths
+    catch :class:`BrokerManualInterventionError` uniformly, so the same
+    graceful-stop pipeline applies whether the trigger came from a polling
+    snapshot or from an in-flight dispatch.
+    """