Skip to content

"Vibe-Trading: Your Personal Trading Agent"

34.4 KB
Raw Blame
"""Deterministic day-loop matching engine for ``paper_trade_step`` (Step 3 / T3).

Frozen surfaces: per-day atomicity (R1-2), AM-14 rejection order
(:data:`rules.REJECTION_ORDER`, first match wins), VD-10 ordering (input
order = matching order; fills/rejected day-ascending then input index;
nav_series day-ascending), AM-3 orders-mode single-day gate, AM-9 readiness
on the merged frame, AM-6 calendar matrix (cn_a = injected calendar truth,
hk/us = zero-calendar fail-closed).  ``strategy_path`` (T7, :mod:`strategy_exec`) generates orders from prior bars and the current private ledger, then drives :func:`run_day_loop` via the public plan/readiness/error seams.
Step 4 (T4) threads :mod:`corporate_actions`: simulated-day boundaries only
(note 2), unverified split-like discontinuities stop the call; unresolved moves reject orders.
Step-3 interpretations (R-V3 → ``suspended``; empty-universe short-circuit;
unknown band skips the check + warns; rejected qty echoed; avg_cost
fee-exclusive 4dp; positions symbol-sorted) live in the STEP3 receipt and
the comments below.  Determinism: no clock, no randomness, dates injected;
unexpected exceptions propagate (transport = engine-internal fault, AM-5) so
a half-day is never observable — the call aborts with no partial result.
"""

from __future__ import annotations

import datetime as dt
from dataclasses import dataclass, field, replace
from decimal import ROUND_HALF_UP, Decimal
from typing import Any, Callable, Collection, Mapping

import numpy as np
import pandas as pd

from . import calendar, corporate_actions, data, session_5m, state_hash, wire
from .limits_cn_a import (
    PROV_LIMITS_HEURISTIC, CnALimitsClient, get_limit_status, heuristic_limit_prices)
from .rules import MarketRules, money, quantize_money
from .schema import (
    CANCELED_REASON_CODE, DEFAULT_FILL_MODEL, DEFAULT_PATH_MODEL, AccountState,
    CanceledOrder, DataProvenance, Fill, NavPoint, Order, PaperTradeStepRequest,
    Position, RejectedOrder, SessionEvent, SkippedDay,
)

__all__ = ["DayPlan", "EngineError", "MatchOutcome", "build_day_plan",
           "error_outcome", "match_orders", "readiness_error", "run_day_loop"]

_Q4 = Decimal("0.0001")
_ZERO = Decimal("0")
_SKIP_NON_TRADING = "non_trading_day"
_SKIP_MARKET_CLOSED = "market_closed_inferred"


@dataclass(frozen=True, slots=True)
class EngineError:
    # In-band error material (AM-5); T6 maps it to the wire ErrorEnvelope.
    code: str
    message: str


@dataclass(frozen=True)
class MatchOutcome:
    # Engine result, consumable by T5 (hash/fee echo closure) and T6 (wire).
    # ``error`` set ⇒ in-band error material; arrays empty, ``end_state`` the
    # untouched input state.  ``limit_provenance`` carries the VD-11
    # table/heuristic tokens (wire mapping is T5's schema-closure call).
    end_state: AccountState
    fills: tuple[Fill, ...] = ()
    rejected_orders: tuple[RejectedOrder, ...] = ()
    nav_series: tuple[NavPoint, ...] = ()
    skipped_days: tuple[SkippedDay, ...] = ()
    warnings: tuple[str, ...] = ()
    data_provenance: DataProvenance = field(default_factory=lambda: DataProvenance(source=""))
    effective_fee_model: dict[str, float] = field(default_factory=dict)
    limit_provenance: tuple[str, ...] = ()
    error: EngineError | None = None
    # pt-v1.2 additive out-params (D2/D3).  All three stay at their empty
    # defaults for an interval="1d" call, so the pt-v1.1 outcome is unchanged.
    engine_fingerprint: str = ""
    canceled_orders: tuple[CanceledOrder, ...] = ()
    events: tuple[SessionEvent, ...] = ()


@dataclass(frozen=True, slots=True)
class DayPlan:
    date: str
    skip_reason: str | None  # None ⇒ matching day
    warning: str | None


@dataclass
class _LedgerPosition:
    qty: Decimal
    avg_cost: Decimal


def _calendar_days(from_date: str, to_date: str) -> list[str]:
    # Every Gregorian day of the inclusive range (injected dates, no clock).
    start = dt.date.fromisoformat(from_date)
    end = dt.date.fromisoformat(to_date)
    if start > end:
        raise ValueError(f"from_date ({from_date}) > to_date ({to_date})")
    days: list[str] = []
    day = start
    while day <= end:
        days.append(day.isoformat())
        day += dt.timedelta(days=1)
    return days


def build_day_plan(
    market: str,
    from_date: str,
    to_date: str,
    market_data: data.MarketDataResult,
    calendar_client: calendar.TradeCalendarClient | None,
) -> list[DayPlan]:
    # Day enumeration per the AM-6 matrix.  cn_a: the injected CH calendar is
    # the truth — a missing client RAISES (weekdays are never silently treated
    # as cn_a trading days); closed dates become non_trading_day skips.
    if market == calendar.CN_A_MARKET:
        if calendar_client is None:
            raise ValueError(
                "cn_a day enumeration requires an injected TradeCalendarClient "
                "(ClickHouse trade_calendar is the AM-6 truth source); refusing "
                "to treat weekdays as cn_a trading days"
            )
        trading = set(calendar.trading_days_in_range(calendar_client, market, from_date, to_date))
        return [
            DayPlan(day, None if day in trading else _SKIP_NON_TRADING, None)
            for day in _calendar_days(from_date, to_date)
        ]

    candidates = calendar.hk_us_candidate_days(from_date, to_date)
    if not market_data.symbols:
        # Empty-universe short-circuit (T2 handoff): classify_zero_calendar_day
        # reads an empty universe literally as all-market zero bar, which would
        # break a cash-only account; with nothing to classify, every candidate
        # weekday is a cash-only matching day.
        return [DayPlan(day, None, None) for day in candidates]

    # hk/us zero-calendar fail-closed: mid-range all-market zero bar →
    # market_closed_inferred + mandatory warning (never non_trading_day —
    # that reason is cn_a-only vocabulary); any bar → matching day, and the
    # zero-bar symbols reject `suspended` per-order via ladder slot 3.
    availability = data.day_bar_availability(market_data, candidates)
    plan: list[DayPlan] = []
    for day in candidates:
        verdict = calendar.classify_zero_calendar_day(
            market, day, is_target_day=(day == to_date),
            symbols=market_data.symbols, symbols_with_bars=availability[day])
        if verdict.kind == calendar.VERDICT_NOT_READY:
            # Target-day all-market zero bar (AM-6①).  The AM-9 readiness
            # gate in run_day_loop runs BEFORE the loop over the same bar
            # facts (assess_readiness ⇔ this verdict) and returns the in-band
            # PAPER_DATA_NOT_READY material; this entry is a placeholder the
            # loop never reaches.  Never a transport-class raise — a not-ready
            # target day is a retryable data fact, not an engine fault (AM-5).
            plan.append(DayPlan(day, None, None))
        elif verdict.kind == calendar.VERDICT_MARKET_CLOSED_INFERRED:
            plan.append(DayPlan(day, _SKIP_MARKET_CLOSED, verdict.warning))
        else:
            plan.append(DayPlan(day, None, None))
    return plan


class _MatchSession:
    # Mutable ledger + caches for one run_day_loop call (single-threaded).

    def __init__(
        self,
        market: str,
        rules: MarketRules,
        market_data: data.MarketDataResult,
        account_state: AccountState,
        limits_client: CnALimitsClient | None,
        corporate_action_unresolved_by_day: Mapping[str, Collection[str]],
        ca_plan: corporate_actions.CorporateActionPlan,
        *,
        path_model: str = DEFAULT_PATH_MODEL,
        fill_model: str = DEFAULT_FILL_MODEL,
    ) -> None:
        self.market = market
        self.rules = rules
        self.market_data = market_data
        self.interval = market_data.interval
        self.path_model = path_model
        self.fill_model = fill_model
        self.limits_client = limits_client
        self.ca_by_day = corporate_action_unresolved_by_day
        self.cash = quantize_money(money(account_state.cash))
        self.positions: dict[str, _LedgerPosition] = {}
        for position in account_state.positions:
            self._merge_input_position(position.symbol, money(position.qty), money(position.avg_cost))
        self.bought_today: dict[str, Decimal] = {}
        self.fills: list[Fill] = []
        self.rejected: list[RejectedOrder] = []
        self.nav_series: list[NavPoint] = []
        self.skipped: list[SkippedDay] = []
        self.warnings: list[str] = list(market_data.warnings) + list(ca_plan.warnings)
        self.limit_provenance: list[str] = []
        self.canceled: list[CanceledOrder] = []
        self.events: list[SessionEvent] = []
        self._band_cache: dict[tuple[str, str], tuple[float | None, float | None]] = {}

    def _merge_input_position(self, symbol: str, qty: Decimal, avg_cost: Decimal) -> None:
        # Duplicate input symbols merge additively (trusted RM ledger; the
        # merge keeps the invariant deterministic instead of crashing).
        existing = self.positions.get(symbol)
        if existing is None:
            self.positions[symbol] = _LedgerPosition(qty, avg_cost.quantize(_Q4, rounding=ROUND_HALF_UP))
            return
        new_qty = existing.qty + qty
        merged = existing.qty * existing.avg_cost + qty * avg_cost
        basis = merged / new_qty if new_qty > _ZERO else avg_cost
        self.positions[symbol] = _LedgerPosition(
            new_qty, basis.quantize(_Q4, rounding=ROUND_HALF_UP))

    @property
    def _five_minute(self) -> bool:
        return self.interval == "5m"

    @property
    def _five_minute_symbols(self) -> tuple[str, ...]:
        # The session-fact universe is the 5m leg's universe (the order symbols
        # in orders mode): a position with no order was only fetched on the
        # daily leg and must never be reported as halted.  An empty 5m universe
        # issues no 5m request, so it has no session facts at all; only a
        # legacy result that records no universe but did serve session bars
        # falls back to the whole symbol list.
        symbols = self.market_data.five_minute_symbols
        if symbols:
            return symbols
        if any(sym_data.session_bars for sym_data in self.market_data.data.values()):
            return self.market_data.symbols
        return ()

    def begin_day(self, day: DayPlan) -> None:
        # T4 session facts, emitted once per day before its orders: a closed
        # calendar day is a day-level non_trading_day; on a matching day a
        # symbol with zero session bars is halted (D6 guarantees at least one
        # other symbol traded for the target day), and auction-window labels
        # that were excluded from the session bar are reported.  interval="1d"
        # emits nothing.
        if not self._five_minute:
            return
        if day.skip_reason == _SKIP_NON_TRADING:
            self.events.append(SessionEvent(
                trade_date=day.date, symbol="", event_type="non_trading_day",
                detail=f"{self.market} calendar closed on {day.date}"))
            return
        if day.skip_reason is not None:
            return
        five_symbols = self._five_minute_symbols
        traded = any(
            (sym_data := self.market_data.data.get(symbol)) is not None
            and sym_data.has_session_bar(day.date)
            for symbol in five_symbols)
        for symbol in five_symbols:
            sym_data = self.market_data.data.get(symbol)
            if sym_data is None:
                continue
            labels = sym_data.auction_labels.get(day.date, ())
            if labels:
                self.events.append(SessionEvent(
                    trade_date=day.date, symbol=symbol, event_type="auction_window",
                    detail=f"auction-window label(s) {', '.join(labels)} excluded from matching"))
            if sym_data.has_session_bar(day.date):
                continue
            self.events.append(SessionEvent(
                trade_date=day.date, symbol=symbol, event_type="halted",
                detail=(f"no 5m session bar for {symbol} on {day.date}; "
                        + ("other universe symbols traded" if traded else "no symbol traded"))))

    def _day_gate(self, day: DayPlan, order: Order) -> tuple[str, str] | None:
        # Slots 1-6 of the frozen AM-14 ladder.
        symbol = order.symbol
        sym_data = self.market_data.data.get(symbol)
        # Slot 1 unknown_symbol: no served data at all in the fetch window.
        if sym_data is None or not (sym_data.bar_dates or sym_data.session_bars):
            return ("unknown_symbol", f"no market data for {symbol} in the fetch window")
        # Slot 2 non_trading_day: cn_a calendar truth (AM-6).
        if day.skip_reason == _SKIP_NON_TRADING:
            return ("non_trading_day", f"{self.market} calendar closed on {day.date}")
        # Slot 3 suspended: zero bar today, or an R-V3 untradable bar
        # (documented mapping: suspended is the closest frozen code).  In 5m
        # mode a missing session bar is the day-level halt gate; matching
        # itself walks the continuous bars in bars_5m.
        if self._bar_missing(day.date, sym_data):
            detail = (f"no 5m session bar for {symbol} on {day.date}; session halted, position valued carry-forward"
                      if self._five_minute
                      else f"no bar for {symbol} on {day.date}; position valued carry-forward")
            return ("suspended", detail)
        if self._bar_untradable(day.date, sym_data):
            return ("suspended", f"bar for {symbol} on {day.date} failed the price sanity gate (R-V3)")
        # Slot 4 corporate_action_unresolved: T4 detector union + injected seam.
        if symbol in self.ca_by_day.get(day.date, ()):
            return ("corporate_action_unresolved",
                    f"unexplained price discontinuity for {symbol} on {day.date}; "
                    "fail-closed rejection (no clean split ratio resolved)")
        # Slot 5 lot_size.
        if self.rules.lot_violation(symbol, order.qty):
            return ("lot_size", f"qty {order.qty} violates the "
                    f"{self.rules.lot_size(symbol)}-share lot rule for {symbol}")
        close = self._close_price(day.date, sym_data)
        # Slot 6 limit_up / limit_down: cn_a bands, BEFORE the AM-7 check.
        # Price limits are about the official daily close, so 5m mode keeps
        # this anchor; an absent daily close skips the band (never fabricated).
        if self.rules.has_price_limits and not self._five_minute:
            if close is None:
                self.warnings.append(
                    f"limit band check skipped for {symbol} on {day.date}: no daily close to anchor the band")
            else:
                up, down = self._band(symbol, day.date, sym_data)
                code = self.rules.band_rejection(order.side, close, up, down)
                if code == "limit_up":
                    return (code, f"close {close:.2f} at or above up limit {up:.2f}; buy rejected")
                if code == "limit_down":
                    return (code, f"close {close:.2f} at or below down limit {down:.2f}; sell rejected")
        return None

    def _fill_gate(self, day: DayPlan, order: Order, price: float | Decimal) -> tuple[str, str] | None:
        # Slots 7-10 of the frozen AM-14 ladder.  ``price`` is the price the
        # fill would execute at: the bar reference for a market order or a
        # first-bar marketable limit, the 委托价 for a bar-low/high limit fill.
        # In 5m the band and cash checks must be anchored on that execution
        # price, never on the bar reference alone.
        if self._five_minute and self.rules.has_price_limits:
            sym_data = self.market_data.data[order.symbol]
            up, down = self._band(order.symbol, day.date, sym_data)
            code = self.rules.band_rejection(order.side, price, up, down)
            if code == "limit_up":
                return (code, f"price {price:.2f} at or above up limit {up:.2f}; buy blocked")
            if code == "limit_down":
                return (code, f"price {price:.2f} at or below down limit {down:.2f}; sell blocked")
        if self.rules.limit_order_violation(order.side, price, order.limit):
            anchor = "price" if self._five_minute else "close"
            detail = (
                f"{anchor} {price:.2f} > limit {order.limit:.2f}"
                if order.side == "buy"
                else f"{anchor} {price:.2f} < limit {order.limit:.2f}"
            )
            return ("limit_not_marketable", detail)
        symbol = order.symbol
        # Slots 8/9 t_plus_1 → insufficient_position (disjoint conditions;
        # available = total − bought_today, cn_a sells only).
        total = self.positions[symbol].qty if symbol in self.positions else _ZERO
        bought = self.bought_today.get(symbol, _ZERO)
        code = self.rules.sell_position_rejection(order.side, order.qty, total, bought)
        if code == "t_plus_1":
            return (code, f"sell qty {order.qty} exceeds available position "
                    f"{total - bought} (T+1: {bought} share(s) bought today are not sellable)")
        if code == "insufficient_position":
            return (code, f"sell qty {order.qty} exceeds position {total}")
        # Slot 10 insufficient_cash (§4: qty×price+fee ≤ cash).
        code = self.rules.cash_rejection(order.side, order.qty, price, self.cash)
        if code == "insufficient_cash":
            cost = self.rules.buy_cost(order.qty, price)
            return (code, f"buy cost {cost} exceeds cash {self.cash}")
        return None

    def match_order(self, day: DayPlan, order: Order) -> None:
        # The AM-14 ladder: first match wins, one reason per order.
        if (gate := self._day_gate(day, order)) is not None:
            self._reject(day, order, *gate)
            return
        sym_data = self.market_data.data[order.symbol]
        close = self._close_price(day.date, sym_data)
        ref = self._reference_price(day.date, sym_data) if self._five_minute else close
        assert ref is not None
        if (gate := self._fill_gate(day, order, ref)) is not None:
            self._reject(day, order, *gate)
            return
        self._fill(day.date, order, ref)

    def _bar_missing(self, day: str, sym_data: data.SymbolData) -> bool:
        if self._five_minute:
            return not sym_data.has_session_bar(day)
        return not sym_data.has_bar(day)

    def _bar_untradable(self, day: str, sym_data: data.SymbolData) -> bool:
        if day in sym_data.untradable_dates:
            return True
        bar = sym_data.session_bars.get(day) if self._five_minute else None
        return bar is not None and min(bar.open, bar.high, bar.low, bar.close) <= 0

    def _close_price(self, day: str, sym_data: data.SymbolData) -> float | None:
        # The daily close stays the band / valuation anchor in both modes.
        if sym_data.frame.empty or not sym_data.has_bar(day):
            return None
        return float(sym_data.frame.loc[pd.Timestamp(day), "close"])

    def _reference_price_values(self, open_: float, high: float, low: float, close: float) -> Decimal:
        # D1: bar_median averages the two middle prices; both models quantize
        # to the 0.01 money tick before the fill, notional or fee arithmetic.
        if self.path_model == "bar_close":
            raw = money(close)
        else:
            prices = sorted((money(open_), money(high), money(low), money(close)))
            raw = (prices[1] + prices[2]) / Decimal(2)
        return quantize_money(raw)

    def _reference_price(self, day: str, sym_data: data.SymbolData) -> Decimal:
        bar = sym_data.session_bars[day]
        return self._reference_price_values(bar.open, bar.high, bar.low, bar.close)

    def _reference_price_from_bar(self, bar: Any) -> Decimal:
        return self._reference_price_values(
            float(bar["open"]), float(bar["high"]), float(bar["low"]), float(bar["close"]))

    def _reject(self, day: DayPlan, order: Order, code: str, detail: str) -> None:
        self.rejected.append(
            RejectedOrder(trade_date=day.date, symbol=order.symbol, side=order.side,
                          qty=order.qty, reason_code=code, detail=detail)
        )
        if not self._five_minute:
            return
        # T3/D2 emergency cancel: one row per failed order IN ADDITION to its
        # specific pt-v1.1 reason (the frozen REASON_CODES table is untouched).
        self.canceled.append(CanceledOrder(
            trade_date=day.date, symbol=order.symbol, side=order.side, qty=order.qty,
            reason_code=CANCELED_REASON_CODE, detail=f"rejected: {code}"))
        if code in ("limit_up", "limit_down"):
            self.events.append(SessionEvent(
                trade_date=day.date, symbol=order.symbol, event_type="price_limit", detail=detail))

    def _fill(self, day: str, order: Order, close: float) -> None:
        # Decimal settlement (VD-9): 2dp notional ± 2dp fee; avg_cost is the
        # fee-exclusive weighted average fill price, quantized 4dp HALF_UP at
        # every mutation so internal chaining equals the RM round-trip.
        price_value = float(close)  # 5m hands a 2dp Decimal; the wire wants a float
        qty = money(order.qty)
        price = money(price_value)
        fee = self.rules.fee(order.side, order.qty, price_value)
        notional = quantize_money(qty * price)
        if order.side == "buy":
            self.cash -= notional + fee
            existing = self.positions.get(order.symbol)
            if existing is None or existing.qty == _ZERO:
                basis = price
            else:
                basis = (existing.qty * existing.avg_cost + qty * price) / (existing.qty + qty)
            self.positions[order.symbol] = _LedgerPosition(
                qty if existing is None or existing.qty == _ZERO else existing.qty + qty,
                basis.quantize(_Q4, rounding=ROUND_HALF_UP))
            self.bought_today[order.symbol] = self.bought_today.get(order.symbol, _ZERO) + qty
        else:
            self.cash += notional - fee
            self.positions[order.symbol].qty -= qty
        # VD-15/B2 dual mode at the fill boundary: plain Orders → ""; StrategyOrders → ≤200 chars.
        self.fills.append(Fill(trade_date=day, symbol=order.symbol, side=order.side,
                               qty=order.qty, price=price_value, fee=float(fee),
                               reason=wire.strategy_fill_reason(getattr(order, "reason", None))))

    def _band(self, symbol: str, day: str, sym_data: data.SymbolData) -> tuple[float | None, float | None]:
        # VD-11: CH table first (injected client), heuristic board-ratio
        # fallback (china_a._price_limit via limits_cn_a), provenance tokens
        # recorded per symbol-day.  A band is never fabricated: with no table
        # row and no previous close the check is SKIPPED with a warning —
        # the reused _blocked_by_limit primitive's unknown-band semantics.
        key = (symbol, day)
        if key in self._band_cache:
            return self._band_cache[key]
        prev_close = _prev_close(sym_data, day)
        up: float | None
        down: float | None
        if self.limits_client is not None:
            status = get_limit_status(self.limits_client, symbol, day, prev_close)
            up, down = status.up_limit, status.down_limit
            self.limit_provenance.extend(f"{symbol}@{day}:{token}" for token in status.provenance)
        elif prev_close is not None:
            up, down = heuristic_limit_prices(symbol, prev_close, is_st=False)
            self.limit_provenance.append(f"{symbol}@{day}:{PROV_LIMITS_HEURISTIC}")
        else:
            up, down = None, None
        if up is None and down is None:
            self.warnings.append(f"limit band unavailable for {symbol} on {day}: no table row "
                                 "and no previous close in the fetch window; price-limit check skipped")
        self._band_cache[key] = (up, down)
        return up, down

    def add_nav_row(self, day: str) -> None:
        # §4 NAV row: close × positions + cash.  Per-position values quantize
        # 2dp; suspended symbols value carry-forward (last positive close on
        # or before the day), falling back to avg_cost with a warning (B3).
        position_value = _ZERO
        for symbol in sorted(self.positions):
            position = self.positions[symbol]
            if position.qty == _ZERO:
                continue
            price = self._valuation_price(symbol, day, position.avg_cost)
            position_value += quantize_money(position.qty * price)
        position_value = quantize_money(position_value)
        self.nav_series.append(NavPoint(date=day, nav=float(self.cash + position_value),
                                        cash=float(self.cash), position_value=float(position_value)))

    def _valuation_price(self, symbol: str, day: str, avg_cost: Decimal) -> Decimal:
        sym_data = self.market_data.data.get(symbol)
        if sym_data is not None:
            if sym_data.has_bar(day) and day not in sym_data.untradable_dates:
                return money(float(sym_data.frame.loc[pd.Timestamp(day), "close"]))
            if not sym_data.frame.empty:
                prior = sym_data.frame.loc[: pd.Timestamp(day), "close"].dropna()
                prior = prior[np.isfinite(prior) & (prior > 0)]
                if not prior.empty:
                    return money(float(prior.iloc[-1]))
        self.warnings.append(f"valuation: {symbol} has no usable close on or before {day}; "
                             "position valued at avg_cost")
        return avg_cost

    def end_state(self) -> AccountState:
        # Symbol-sorted (deterministic), zero-qty rows dropped.
        return AccountState(
            cash=float(self.cash),
            positions=tuple(
                Position(symbol=symbol, qty=float(position.qty), avg_cost=float(position.avg_cost))
                for symbol, position in sorted(self.positions.items()) if position.qty != _ZERO))


def _prev_close(sym_data: data.SymbolData, day: str) -> float | None:
    # Last positive close strictly before the day (heuristic band base).
    if sym_data.frame.empty:
        return None
    prior = sym_data.frame.loc[: pd.Timestamp(day), "close"]
    prior = prior.iloc[:-1] if sym_data.has_bar(day) else prior
    prior = prior.dropna()
    prior = prior[np.isfinite(prior) & (prior > 0)]
    return float(prior.iloc[-1]) if not prior.empty else None


def error_outcome(
    error: EngineError,
    account_state: AccountState,
    market_data: data.MarketDataResult,
    market: str,
    fee_model: Mapping[str, float] | None,
) -> MatchOutcome:
    return MatchOutcome(
        end_state=account_state,
        data_provenance=market_data.provenance,
        effective_fee_model=state_hash.effective_fee_model(market, dict(fee_model or {})),
        error=error,
    )


def readiness_error(to_date: str, market_data: data.MarketDataResult, plan: Collection[DayPlan]) -> EngineError | None:
    # AM-9 gate unless the cn_a calendar truth says to_date is closed; an empty
    # universe is vacuously ready (T2).  T7 runs this BEFORE any strategy day so
    # a retryable data fact is never masked by a non-retryable strategy failure.
    target = next((entry for entry in plan if entry.date == to_date), None)
    if target is None or target.skip_reason != _SKIP_NON_TRADING:
        verdict = data.assess_readiness(market_data, to_date)
        if not verdict.ready:
            return EngineError(verdict.code or data.NOT_READY_CODE, verdict.message or "")
    return None


def match_orders(
    request: PaperTradeStepRequest,
    *,
    market_data: data.MarketDataResult,
    calendar_client: calendar.TradeCalendarClient | None = None,
    limits_client: CnALimitsClient | None = None,
    corporate_action_unresolved_by_day: Mapping[str, Collection[str]] | None = None,
    hk_lot_sizes: Mapping[str, int] | None = None,
) -> MatchOutcome:
    # Orders-mode entry (AM-3 single-day); strategy_path mode bypasses this and
    # drives run_day_loop through strategy_exec (T7).  Contract violations
    # return stable INVALID_REQUEST material — no matching, no half-day.
    if market_data.market != request.market:
        raise ValueError(
            f"market_data was fetched for {market_data.market!r}, request says {request.market!r}"
        )
    if request.interval != market_data.interval:
        # Cross-field gate: a 5m request served a 1d frame (or the reverse)
        # must not silently match the daily close under 5m semantics.
        error = EngineError("INVALID_REQUEST", f"market_data was fetched at interval "
                            f"{market_data.interval!r}, request says {request.interval!r}")
        return error_outcome(error, request.account_state, market_data, request.market, request.fee_model)
    if request.from_date != request.to_date:
        error = EngineError("INVALID_REQUEST", "orders mode requires from_date == to_date "
                            f"(AM-3 single-day); got from_date={request.from_date} to_date={request.to_date}")
        return error_outcome(error, request.account_state, market_data, request.market, request.fee_model)
    if request.orders is None:
        error = EngineError("INVALID_REQUEST", "orders mode requires the orders array; "
                            "strategy_path execution lands in Step 7")
        return error_outcome(error, request.account_state, market_data, request.market, request.fee_model)
    return run_day_loop(
        market=request.market, account_state=request.account_state,
        from_date=request.from_date, to_date=request.to_date, market_data=market_data,
        orders_by_day={request.from_date: request.orders}, fee_model=request.fee_model,
        calendar_client=calendar_client, limits_client=limits_client, hk_lot_sizes=hk_lot_sizes,
        corporate_action_unresolved_by_day=corporate_action_unresolved_by_day,
        path_model=request.path_model, fill_model=request.fill_model)


def run_day_loop(
    *,
    market: str,
    account_state: AccountState,
    from_date: str,
    to_date: str,
    orders_by_day: Mapping[str, Collection[Order]],
    order_provider: Callable[[str, AccountState], Collection[Order]] | None = None,
    market_data: data.MarketDataResult,
    fee_model: Mapping[str, float] | None = None,
    calendar_client: calendar.TradeCalendarClient | None = None,
    limits_client: CnALimitsClient | None = None,
    corporate_action_unresolved_by_day: Mapping[str, Collection[str]] | None = None,
    hk_lot_sizes: Mapping[str, int] | None = None,
    path_model: str = DEFAULT_PATH_MODEL,
    fill_model: str = DEFAULT_FILL_MODEL,
) -> MatchOutcome:
    # Day-loop core: enumerate [from, to], gate readiness (AM-9), match
    # serially (VD-10).  Multi-day ranges are only reachable through this
    # seam (orders mode is single-day, AM-3).  Day k's ledger state carries
    # into day k+1 (R1-2: previous end_state = next day's input).
    if market_data.market != market:
        raise ValueError(f"market_data was fetched for {market_data.market!r}, market says {market!r}")
    rules = MarketRules(market, fee_model, hk_lot_sizes)
    plan = build_day_plan(market, from_date, to_date, market_data, calendar_client)

    # Readiness gate (AM-9) — shared with the T7 strategy seam.
    if (error := readiness_error(to_date, market_data, plan)) is not None:
        return error_outcome(error, account_state, market_data, market, fee_model)

    # OHLC/volume ratios identify discontinuities, not authoritative actions.
    # All production execution series are raw, including A-shares. Never
    # multiply a holding based only on a price crash that resembles a split.
    ca_plan = corporate_actions.build_plan(
        market_data, [e.date for e in plan if e.skip_reason is None], account_state.positions)
    if ca_plan.clean_by_day:
        day = min(ca_plan.clean_by_day)
        symbols = ", ".join(event.symbol for event in ca_plan.clean_by_day[day])
        return error_outcome(EngineError(
            "PAPER_DATA_NOT_READY",
            f"Unverified corporate action on {day} for {symbols}; "
            "price/volume ratios cannot establish a split. Reconcile against an authoritative action record."),
            account_state, market_data, market, fee_model)
    session = _MatchSession(
        market, rules, market_data, account_state, limits_client,
        corporate_actions.merge_unresolved(
            corporate_action_unresolved_by_day, ca_plan.unresolved_by_day),
        ca_plan, path_model=path_model, fill_model=fill_model)
    for entry in plan:
        session.begin_day(entry)  # T4 session facts (no-op for interval="1d")
        session.bought_today = {}  # T+1 availability resets each day
        if entry.skip_reason is not None:
            session.skipped.append(SkippedDay(date=entry.date, reason=entry.skip_reason))
            if entry.warning:
                session.warnings.append(entry.warning)
        # Orders run the ladder on EVERY day: a cn_a non-trading day rejects
        # at slot 2; an inferred-closed hk/us day rejects at slot 3
        # (suspended — never non_trading_day, which is cn_a-only vocabulary).
        orders = (order_provider(entry.date, session.end_state())
                  if order_provider is not None and entry.skip_reason is None
                  else orders_by_day.get(entry.date, ()))
        if market_data.interval == "5m":
            session_5m.match_orders_5m(session, entry, tuple(orders))
        else:
            for order in tuple(orders):
                session.match_order(entry, order)
        if entry.skip_reason is None:
            session.add_nav_row(entry.date)  # per-day commit: fills + one nav row

    for symbol, lot in sorted(rules.lot_assumptions.items()):
        session.warnings.append(f"lot assumption: {symbol} sized on the default {lot}-share "
                                "board lot (no lot table entry)")
    return MatchOutcome(
        end_state=session.end_state(),
        fills=tuple(session.fills),
        rejected_orders=tuple(session.rejected),
        nav_series=tuple(session.nav_series),
        skipped_days=tuple(session.skipped),
        warnings=tuple(dict.fromkeys(session.warnings)),
        data_provenance=replace(market_data.provenance, corporate_actions=(
            tuple(market_data.provenance.corporate_actions) + ca_plan.provenance)),
        effective_fee_model=rules.effective_fee_model,
        limit_provenance=tuple(dict.fromkeys(session.limit_provenance)),
        engine_fingerprint=state_hash.engine_fingerprint(
            interval=market_data.interval, path_model=path_model, fill_model=fill_model,
            bar_fingerprint=market_data.bar_fingerprint),
        canceled_orders=tuple(session.canceled),
        events=tuple(session.events),
    )