powerquant-cli 0.2.6__py3-none-any.whl

quant_core/app/trading_runtime/replay/market_state_resolver.py

@@ -0,0 +1,150 @@
+"""
+Market State Resolver - 市场交易状态增量事实投影
+
+把按时间推进的 MarketTimeSlice 中的 TradingStateEvent / PriceLimitEvent
+投影为 point-in-time、不可变的 InstrumentMarketState@T（SSOT 见 DECISIONS.md
+2026-09-04「市场状态采用增量事实投影」）。
+
+状态延续规则（Canonical 语义，市场无关）：
+- 事实从 event_time 开始生效，持续到后续事实显式覆盖；
+- 当前片没有状态事件不表示恢复交易——事件缺席延续旧状态；
+- 首次没有任何状态事实时为 UNKNOWN；
+- 只有显式 TRADING 事件才能从 SUSPENDED / HALTED 等状态恢复；
+- 价格限制事实同理增量生效；没有价格限制的市场可以完全不提供
+  PriceLimitEvent，投影中 price_limit 恒为 None；
+- BarEvent 等其他市场事实不参与投影：禁止从 Bar 推断停牌或涨跌停封板。
+
+边界：本模块属于 Market 域，只消费 MarketTimeSlice 纯市场事实，
+不 import Order Execution / Portfolio / Backtest / Trading Runtime；
+不输出订单的 ALLOW / DEFER / REJECT（该决策属于 Order Execution 的
+TradabilityPolicy）。
+"""
+
+from datetime import datetime
+
+from quant_core.app.data.exceptions import MarketDataValidationError
+from quant_core.app.data.schema.event_schema import MarketTimeSlice
+from quant_core.app.data.schema.trading_state_schema import (
+    DailyStateSnapshotEventPayload,
+    InstrumentMarketState,
+    PriceLimitEventPayload,
+    PriceLimitState,
+    TradingState,
+    TradingStateEventPayload,
+)
+
+
+class MarketStateResolver:
+    """增量市场状态投影器（有状态、按时间片顺序消费）
+
+    用法：按市场时间顺序对每个 MarketTimeSlice 调用 apply_slice，
+    之后读取投影。投影不可变，只能被后续事实更新。
+    """
+
+    def __init__(self) -> None:
+        # instrument_id -> (生效时间, 交易状态, 来源事件ID)；仅由显式状态事实写入。
+        # source event ID 随状态值一起生效、延续与覆盖，保证 provenance 与值同步。
+        self._states: dict[str, tuple[datetime, TradingState, str | None]] = {}
+        # instrument_id -> 最新价格限制投影（含 source_event_id）；仅由显式价格限制事实写入
+        self._limits: dict[str, PriceLimitState | None] = {}
+        # 最近一次成功消费的 slice 时间；投影只允许沿市场时间单调前进
+        self._last_slice_time: datetime | None = None
+
+    def apply_slice(self, time_slice: MarketTimeSlice) -> dict[str, InstrumentMarketState]:
+        """消费一个时间片内的事实并更新投影，返回全部已知标的的当前状态
+
+        时间推进约束：slice 时间必须严格晚于上一片（相同时间重复 apply
+        同样拒绝），防止较早时间片覆盖较新状态。校验全部通过后才修改
+        内部状态，失败时不产生任何部分修改（原子性）。
+        状态值、as_of 与来源 event_id 三者作为同一事实整体生效/覆盖。
+        """
+        if self._last_slice_time is not None and time_slice.event_time <= self._last_slice_time:
+            raise MarketDataValidationError(
+                f"MarketTimeSlice 时间必须严格递增：收到 {time_slice.event_time}，"
+                f"但已消费到 {self._last_slice_time}（更早或重复的时间片会覆盖较新状态）"
+            )
+        # 先完整计算本片更新，再统一提交；循环内不改 self，保证失败原子性。
+        # 快照先于增量应用：快照建立「日基线」（可显式 UNKNOWN / 清除限价），
+        # 同片内的增量事实更具体、后生效覆盖快照（DECISIONS 2026-09-06 Q1-A）。
+        state_updates: list[tuple[str, tuple[datetime, TradingState, str | None]]] = []
+        limit_updates: list[tuple[str, PriceLimitState]] = []
+        snapshot_state_updates: list[tuple[str, tuple[datetime, TradingState, str | None]]] = []
+        snapshot_limit_updates: list[tuple[str, PriceLimitState | None]] = []
+        for event in time_slice.events:
+            payload = event.payload
+            if isinstance(payload, TradingStateEventPayload):
+                state_updates.append(
+                    (payload.instrument_id, (event.event_time, payload.state, event.event_id))
+                )
+            elif isinstance(payload, PriceLimitEventPayload):
+                limit_updates.append(
+                    (
+                        payload.instrument_id,
+                        PriceLimitState(
+                            limit_up=payload.limit_up,
+                            limit_down=payload.limit_down,
+                            buy_side_locked=payload.buy_side_locked,
+                            sell_side_locked=payload.sell_side_locked,
+                            as_of=event.event_time,
+                            source_event_id=event.event_id,
+                        ),
+                    )
+                )
+            elif isinstance(payload, DailyStateSnapshotEventPayload):
+                snapshot_state_updates.append(
+                    (
+                        payload.instrument_id,
+                        (event.event_time, payload.trading_state, event.event_id),
+                    )
+                )
+                snapshot_limit_updates.append(
+                    (
+                        payload.instrument_id,
+                        None
+                        if payload.limit_up is None or payload.limit_dn is None
+                        else PriceLimitState(
+                            limit_up=payload.limit_up,
+                            limit_down=payload.limit_dn,
+                            buy_side_locked=False,
+                            sell_side_locked=False,
+                            as_of=event.event_time,
+                            source_event_id=event.event_id,
+                        ),
+                    )
+                )
+        for instrument_id, entry in snapshot_state_updates:
+            self._states[instrument_id] = entry
+        for instrument_id, limit in snapshot_limit_updates:
+            self._limits[instrument_id] = limit
+        for instrument_id, entry in state_updates:
+            self._states[instrument_id] = entry
+        for instrument_id, limit in limit_updates:
+            self._limits[instrument_id] = limit
+        self._last_slice_time = time_slice.event_time
+        return self.snapshot()
+
+    def snapshot(self) -> dict[str, InstrumentMarketState]:
+        """全部已知标的的当前 point-in-time 状态（不可变投影，新对象）"""
+        instrument_ids = set(self._states) | set(self._limits)
+        return {instrument_id: self.resolve(instrument_id) for instrument_id in instrument_ids}
+
+    def resolve(self, instrument_id: str) -> InstrumentMarketState:
+        """单标的当前 point-in-time 状态；从未有任何事实时交易状态为 UNKNOWN"""
+        state_entry = self._states.get(instrument_id)
+        limit = self._limits.get(instrument_id)
+        if state_entry is None:
+            return InstrumentMarketState(
+                instrument_id=instrument_id,
+                trading_state_as_of=None,
+                trading_state=TradingState.UNKNOWN,
+                price_limit=limit,
+                trading_state_event_id=None,
+            )
+        trading_state_as_of, state, event_id = state_entry
+        return InstrumentMarketState(
+            instrument_id=instrument_id,
+            trading_state_as_of=trading_state_as_of,
+            trading_state=state,
+            price_limit=limit,
+            trading_state_event_id=event_id,
+        )

quant_core/app/trading_runtime/runtime_ports.py

@@ -0,0 +1,64 @@
+"""Runtime 消费的最小市场、策略、账户和同步交易契约。"""
+
+from typing import Protocol, runtime_checkable
+
+from quant_core.app.data.schema.event_schema import MarketTimeSlice
+from quant_core.app.data.schema.exchange_operating_state import ExchangeOperatingState
+from quant_core.app.data.schema.trading_state_schema import InstrumentMarketState
+from quant_core.app.order_execution.interface.public.execution_account import IExecutionReservation
+from quant_core.app.portfolio.interface.public.portfolio import IPortfolioUpdate
+from quant_core.app.strategy.schema.portfolio_target import PortfolioDecision
+from quant_core.app.strategy.schema.signal_schema import Signal
+
+
+@runtime_checkable
+class StrategyRuntimeProtocol(Protocol):
+    """策略执行能力面（与 StrategyRuntimeService.run_slice 同形）"""
+
+    decisions: tuple[PortfolioDecision, ...]
+
+    async def run_slice(self, time_slice: MarketTimeSlice) -> list[Signal]:
+        """执行一个时间片并返回该片 Signal 批次"""
+        ...
+
+
+@runtime_checkable
+class MarketStateProjectionProtocol(Protocol):
+    """市场状态增量投影能力面（MarketStateResolver 的最小等价 Port）"""
+
+    def apply_slice(self, time_slice: MarketTimeSlice) -> dict[str, InstrumentMarketState]:
+        """消费一个时间片事实，返回全部已知标的的当前 point-in-time 状态"""
+        ...
+
+
+@runtime_checkable
+class ExchangeStateProjectionProtocol(Protocol):
+    """交易所运行状态增量投影能力面（T4R；ExchangeStateResolver 的最小等价 Port）
+
+    交易所运行状态唯一 SSOT：Runtime 每片消费一次，投影同时供
+    Order Execution（报单/撮合准入、DAY 到期）与 StepResult（UI/Agent
+    可见性）消费；下游不得私有解释 Session 事件。
+    """
+
+    def apply_slice(self, time_slice: MarketTimeSlice) -> dict[str, ExchangeOperatingState]:
+        """消费一个时间片事实，返回全部已知交易所的当前 point-in-time 状态"""
+        ...
+
+
+@runtime_checkable
+class RuntimePortfolioProtocol(
+    IPortfolioUpdate,
+    IExecutionReservation,
+    Protocol,
+):
+    """Runtime 所需的组合 Portfolio 能力；只组合既有 Port，不复制方法
+
+    Runtime 要求同一个 Portfolio 对象同时提供：
+    - IPortfolioUpdate（apply_fill / mark_to_market /
+      settle_trading_day / snapshot）
+    - IExecutionAccountView（available_cash / available_quantity，
+      撮合期只读账户视图，直接传给 process_market_slice）
+
+    实现（如 T3 内存模拟组合）零修改即结构化满足；
+    Runtime 不 import 任何具体 Portfolio 类。
+    """

quant_core/app/trading_runtime/runtime_schema.py

@@ -0,0 +1,129 @@
+"""
+Trading Runtime Schema - Clock / TraceEntry / RuntimeStepResult
+
+Runtime 是不知道调用场景（Backtest/Paper/Live）的共享事件循环内核；
+单时间片因果顺序见 DECISIONS.md 2026-09-04「Backtest 单时间片采用
+旧订单成交在前、新策略决策在后」与 `app/trading_runtime/SPEC.md` §5。
+
+边界：RuntimeStepResult 是一次 step 的结构化输出；集合全部不可变元组
+并保持确定顺序。本域不实现撮合/组合业务，只编排。
+"""
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Protocol, runtime_checkable
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from quant_core.app.data.schema.exchange_operating_state import ExchangeOperatingState
+from quant_core.app.order_execution.domain.order_event import (
+    ExecutionAttempt,
+    Fill,
+    OrderTransition,
+)
+from quant_core.app.order_execution.domain.order_value import OrderAck, OrderIntent
+from quant_core.app.order_execution.schema.order_request_schema import OrderRequest
+from quant_core.app.portfolio.portfolio_schema import PortfolioSnapshot
+from quant_core.app.strategy.schema.portfolio_target import PortfolioDecision
+from quant_core.app.strategy.schema.signal_schema import Signal
+
+
+@runtime_checkable
+class ClockProtocol(Protocol):
+    """场景无关时钟：当前市场时间由调用方推进（禁止读 wall clock）"""
+
+    def now(self) -> datetime:
+        """返回当前市场时间（timezone-aware）"""
+        ...
+
+
+class TraceEntry(BaseModel):
+    """最小通用 trace 记录（不是 Backtest DecisionTrace；后者归 T7）"""
+
+    model_config = ConfigDict(frozen=True)
+
+    event_time: datetime = Field(..., description="发生市场时间（timezone-aware）")
+    kind: str = Field(..., description="条目类别（如 order_ack / fill / defer）")
+    detail: str = Field(..., description="人类可读摘要（审计用，非行为依据）")
+
+    @field_validator("event_time")
+    @classmethod
+    def _check_tz(cls, value: datetime) -> datetime:
+        if value.tzinfo is None:
+            raise ValueError("TraceEntry.event_time 必须 timezone-aware")
+        return value
+
+
+def _require_tz_aware(value: datetime) -> datetime:
+    if value.tzinfo is None:
+        raise ValueError("RuntimeStepResult.slice_time 必须 timezone-aware")
+    return value
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeStepResult:
+    """单时间片处理结果（片内因果顺序的输出形态）
+
+    集合为不可变元组并保持处理顺序；portfolio_snapshot 是本片估值后的
+    组合投影。类型参数化字段按业务对象组织，禁止通用 dict 透传。
+    """
+
+    slice_time: datetime
+    portfolio_snapshot: PortfolioSnapshot
+    fills: tuple[Fill, ...] = ()
+    execution_attempts: tuple[ExecutionAttempt, ...] = ()
+    order_acks: tuple[OrderAck, ...] = ()
+    order_updates: tuple[OrderTransition, ...] = ()
+    signals: tuple[Signal, ...] = ()
+    portfolio_decisions: tuple[PortfolioDecision, ...] = ()
+    strategy_order_requests: tuple[OrderRequest, ...] = ()
+    order_intents: tuple[OrderIntent, ...] = ()
+    exchange_states: tuple[ExchangeOperatingState, ...] = ()
+    trace_entries: tuple[TraceEntry, ...] = ()
+
+    def __post_init__(self) -> None:
+        _require_tz_aware(self.slice_time)
+        self._check_point_in_time_consistency()
+
+    def _check_point_in_time_consistency(self) -> None:
+        """RuntimeStepResult@T 中所有「本片产生」的对象时间必须精确等于 T"""
+        t = self.slice_time
+        for fill in self.fills:
+            if fill.fill_time != t:
+                raise ValueError(f"Fill.fill_time {fill.fill_time} 必须等于 slice_time {t}")
+        for attempt in self.execution_attempts:
+            if attempt.event_time != t:
+                raise ValueError(
+                    f"ExecutionAttempt.event_time {attempt.event_time} 必须等于 slice_time {t}"
+                )
+        for ack in self.order_acks:
+            if ack.event_time != t:
+                raise ValueError(f"OrderAck.event_time {ack.event_time} 必须等于 slice_time {t}")
+        for update in self.order_updates:
+            if update.event_time != t:
+                raise ValueError(
+                    f"OrderUpdate.event_time {update.event_time} 必须等于 slice_time {t}"
+                )
+        for signal in self.signals:
+            if signal.event_time != t:
+                raise ValueError(f"Signal.event_time {signal.event_time} 必须等于 slice_time {t}")
+        for request in self.strategy_order_requests:
+            if request.event_time != t:
+                raise ValueError(
+                    f"OrderRequest.event_time {request.event_time} 必须等于 slice_time {t}"
+                )
+        for intent in self.order_intents:
+            if intent.creation_event_time != t:
+                raise ValueError(
+                    f"OrderIntent.creation_event_time {intent.creation_event_time} "
+                    f"必须等于 slice_time {t}"
+                )
+        for entry in self.trace_entries:
+            if entry.event_time != t:
+                raise ValueError(
+                    f"TraceEntry.event_time {entry.event_time} 必须等于 slice_time {t}"
+                )
+        if self.portfolio_snapshot.as_of != t:
+            raise ValueError(
+                f"PortfolioSnapshot.as_of {self.portfolio_snapshot.as_of} 必须等于 slice_time {t}"
+            )