powerquant-cli 0.2.6__py3-none-any.whl

quant_core/app/data/schema/adjustment_schema.py

@@ -0,0 +1,67 @@
+"""复权因子与价格视图契约。"""
+
+from datetime import date, datetime
+from decimal import Decimal
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from quant_core.app.data.schema.market_schema import BarResponse
+
+
+class AdjustmentType(str, Enum):
+    NONE = "none"
+    PRE = "pre"
+    POST = "post"
+
+
+class AdjustmentAnchorMode(str, Enum):
+    FIXED_DATE = "fixed_date"
+    LATEST = "latest"
+    DECISION_TIME = "decision_time"
+
+
+class AdjustmentFactorResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    instrument_id: str
+    trade_date: date
+    factor: Decimal = Field(gt=0)
+    dataset_revision: str
+    source_provider: str
+    source_updated_at: datetime | None = None
+    recorded_at: datetime
+
+
+class AdjustedBarResponse(BarResponse):
+    """BarResponse 的合成视图；仅放宽 volume 为可含小数的 Decimal。"""
+
+    volume: Decimal
+
+
+class BarViewRequest(BaseModel):
+    adjustment_type: AdjustmentType = AdjustmentType.NONE
+    anchor_mode: AdjustmentAnchorMode | None = None
+    anchor_date: date | None = None
+    decision_time: datetime | None = None
+    known_at: datetime | None = None
+
+    @model_validator(mode="after")
+    def validate_anchor(self) -> "BarViewRequest":
+        if self.adjustment_type in {AdjustmentType.NONE, AdjustmentType.POST}:
+            return self
+        if self.anchor_mode is None:
+            raise ValueError("复权查询必须指定 anchor_mode")
+        if self.anchor_mode is AdjustmentAnchorMode.FIXED_DATE and self.anchor_date is None:
+            raise ValueError("fixed_date 必须指定 anchor_date")
+        if self.anchor_mode is AdjustmentAnchorMode.DECISION_TIME and self.decision_time is None:
+            raise ValueError("decision_time 模式必须指定 decision_time")
+        return self
+
+
+class AdjustedBarSeries(BaseModel):
+    instrument_id: str
+    adjustment_type: AdjustmentType
+    anchor_date: date | None
+    factor_revision: str | None
+    bars: list[AdjustedBarResponse | BarResponse]

quant_core/app/data/schema/corporate_action_schema.py

@@ -0,0 +1,46 @@
+"""公司行动 Canonical Fact 与运行时阶段事件。"""
+
+from datetime import date
+from decimal import Decimal
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class CorporateActionPhase(str, Enum):
+    RECORD = "record"
+    EX_DATE = "ex_date"
+    LISTING_DATE = "listing_date"
+    PAY_DATE = "pay_date"
+
+
+class CorporateActionResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    action_id: str
+    instrument_id: str
+    record_date: date
+    ex_date: date
+    pay_date: date | None = None
+    listing_date: date | None = None
+    cash_per_share: Decimal = Field(Decimal("0"), ge=0)
+    stock_ratio: Decimal = Field(Decimal("0"), ge=0)
+    dataset_revision: str
+    source_provider: str
+
+    @model_validator(mode="after")
+    def validate_dates_and_value(self) -> "CorporateActionResponse":
+        if self.record_date > self.ex_date:
+            raise ValueError("公司行动日期必须满足 record_date <= ex_date")
+        if self.cash_per_share == 0 and self.stock_ratio == 0:
+            raise ValueError("公司行动必须至少包含现金或送转比例")
+        if self.cash_per_share > 0 and (self.pay_date is None or self.pay_date < self.ex_date):
+            raise ValueError("现金分红必须有不早于 ex_date 的 pay_date")
+        if self.stock_ratio > 0 and (self.listing_date is None or self.listing_date < self.ex_date):
+            raise ValueError("送转股必须有不早于 ex_date 的 listing_date")
+        return self
+
+
+class CorporateActionEventPayload(BaseModel):
+    action: CorporateActionResponse
+    phase: CorporateActionPhase

quant_core/app/data/schema/event_schema.py

@@ -0,0 +1,506 @@
+"""
+Market Runtime Schema - MarketEvent 契约（SSOT 见 SPEC「MarketEvent 契约」）
+
+定义：MarketEvent 是具有市场时间语义、会改变市场参与者可观察信息集的
+市场事实事件。分 Structured（Bar/Quote/Tick/Session/CorporateAction/Snapshot）
+与 Unstructured（News/Announcement/Policy）两大类——非结构化的是 payload
+内容，不是事件协议本身。
+
+核心抽象：Live Stream 与 Historical Replay 产出同一个 MarketEvent，
+Strategy 环境无关（实盘/回测只换 EventSource，不换事件语义）。
+
+Envelope 语义（固定）：
+- event_id：事件唯一标识（uuid）
+- event_time：市场世界中事件发生/生效的时间（Strategy 只允许认这个）；
+- received_at：PowerQuant 实际收到/生成事件的系统时间（回放时与
+  event_time 完全不同，如 replay：event_time=2025-05-20 10:31 / received_at=今天）；
+- sequence：流内单调递增序号；
+- source：来源标识（live/replay），只允许用于 observability/debug/logging/trace，
+  Strategy 行为禁止依赖它。
+"""
+
+from collections.abc import AsyncIterator
+from datetime import datetime
+from decimal import Decimal
+from typing import TYPE_CHECKING, Any, Literal, cast
+from uuid import uuid4
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+from quant_core.app.data.constants import (
+    INSTRUMENT_ID_SEPARATOR,
+    BarFrequency,
+    MarketEventType,
+    MarketStreamMode,
+)
+from quant_core.app.data.schema.corporate_action_schema import CorporateActionEventPayload
+from quant_core.app.data.schema.market_schema import BarResponse
+from quant_core.app.data.schema.trading_state_schema import (
+    DailyStateSnapshotEventPayload,
+    PriceLimitEventPayload,
+    TradingState,
+    TradingStateEventPayload,
+)
+
+if TYPE_CHECKING:
+    from quant_core.app.data.schema.exchange_state_schema import (
+        ExchangeStateEventPayload,
+        ExchangeStateSnapshotEventPayload,
+    )
+
+
+class MarketEvent(BaseModel):
+    """市场事件统一信封（Envelope）"""
+
+    event_id: str = Field(default_factory=lambda: str(uuid4()), description="事件唯一标识")
+    event_type: MarketEventType = Field(..., description="事件类型")
+    event_time: datetime = Field(..., description="市场事件时间（Strategy 只认这个）")
+    received_at: datetime = Field(..., description="系统接收/生成时间")
+    sequence: int = Field(..., ge=0, description="流内单调递增序号")
+    source: str = Field(..., description="来源标识（live/replay），仅用于 observability")
+    payload: dict[str, Any] = Field(..., description="事件载荷（如BarResponse dict）")
+
+
+class BarEvent(MarketEvent):
+    """Bar 事件"""
+
+    event_type: Literal[MarketEventType.BAR] = MarketEventType.BAR
+    payload: BarResponse  # type: ignore[assignment]
+
+
+class CorporateActionEvent(MarketEvent):
+    """公司行动阶段事件；Portfolio 按 RECORD/EX_DATE/PAY_DATE 处理。"""
+
+    event_type: Literal[MarketEventType.CORPORATE_ACTION] = MarketEventType.CORPORATE_ACTION
+    payload: CorporateActionEventPayload  # type: ignore[assignment]
+
+
+class MarketStreamRequest(BaseModel):
+    """市场事件流请求（Live 与 Replay 共用）"""
+
+    mode: MarketStreamMode = Field(MarketStreamMode.REPLAY, description="流模式")
+    instrument_ids: list[str] = Field(default_factory=list, description="标的列表；空=全部")
+    frequency: BarFrequency = Field(BarFrequency.M1, description="频率")
+    coarse_open_decisions: bool = False
+    # replay 专用
+    start: datetime | None = Field(None, description="回放开始时间（含）")
+    end: datetime | None = Field(None, description="回放结束时间（含）")
+    speed: float = Field(0.0, ge=0.0, description="回放加速倍数；0=尽快（不等待事件间隔）")
+
+
+class TimerEventPayload(BaseModel):
+    """Timer 事件载荷"""
+
+    period_seconds: int = Field(..., description="定时间隔（秒）")
+
+
+TradingSessionStage = Literal[
+    MarketEventType.SESSION_PRE_OPEN,
+    MarketEventType.SESSION_OPEN,
+    MarketEventType.SESSION_BREAK_START,
+    MarketEventType.SESSION_BREAK_END,
+    MarketEventType.SESSION_CLOSE,
+]
+
+
+class TradingSessionEventPayload(BaseModel):
+    """Trading Session 事件载荷
+
+    Session 阶段（通用，市场各自映射具体时刻；A股见 constants SESSION_*_TIME）：
+    PRE_OPEN → OPEN → BREAK_START → BREAK_END → CLOSE。
+    TradingCalendar 是 Session Runtime 的权威基础，Strategy 禁止用 wall-clock
+    或「周一到周五」自行推导时段。
+    """
+
+    exchange: str = Field(..., description="交易所")
+    session: TradingSessionStage = Field(..., description="时段事件类型")
+
+
+class TradingSessionEvent(MarketEvent):
+    """Trading Session 事件：开盘/休市等时段边界，由 Runtime 基于 TradingCalendar 生成"""
+
+    payload: TradingSessionEventPayload  # type: ignore[assignment]
+
+
+class TradingStateEvent(MarketEvent):
+    """交易状态事实事件（通用市场事实；契约见 trading_state_schema）"""
+
+    event_type: Literal[MarketEventType.TRADING_STATE] = MarketEventType.TRADING_STATE
+    payload: TradingStateEventPayload  # type: ignore[assignment]
+
+
+class PriceLimitEvent(MarketEvent):
+    """价格限制事实事件（可选市场事实；契约见 trading_state_schema）"""
+
+    event_type: Literal[MarketEventType.PRICE_LIMIT] = MarketEventType.PRICE_LIMIT
+    payload: PriceLimitEventPayload  # type: ignore[assignment]
+
+
+class DailyStateSnapshotEvent(MarketEvent):
+    """日级市场状态完整快照事件（Q1-A 定案；契约见 trading_state_schema）
+
+    表达「某标的某交易日的完整状态基线」：允许显式 UNKNOWN 与 price_limit=None
+    （显式清除）。既有 TradingStateEvent / PriceLimitEvent 保持增量事实语义，
+    不承担日界清除职责；同片内增量事实比快照更具体、后生效覆盖。
+    """
+
+    event_type: Literal[MarketEventType.DAILY_STATE_SNAPSHOT] = MarketEventType.DAILY_STATE_SNAPSHOT
+    payload: DailyStateSnapshotEventPayload  # type: ignore[assignment]
+
+
+def trading_state_to_event(
+    instrument_id: str,
+    state: TradingState,
+    event_time: datetime,
+    sequence: int,
+    source: str,
+    received_at: datetime,
+) -> TradingStateEvent:
+    """把交易状态事实包装成 TradingStateEvent 的工厂（Runtime/Mock 统一入口）"""
+    return TradingStateEvent(
+        event_type=MarketEventType.TRADING_STATE,
+        event_time=event_time,
+        received_at=received_at,
+        sequence=sequence,
+        source=source,
+        payload=TradingStateEventPayload(instrument_id=instrument_id, state=state),
+    )
+
+
+def daily_state_snapshot_to_event(
+    instrument_id: str,
+    state: TradingState,
+    event_time: datetime,
+    limit_up: Decimal | None,
+    limit_dn: Decimal | None,
+    sequence: int,
+    source: str,
+    received_at: datetime,
+) -> DailyStateSnapshotEvent:
+    """把日级状态快照包装成 DailyStateSnapshotEvent 的工厂（Replay 统一入口）"""
+    return DailyStateSnapshotEvent(
+        event_type=MarketEventType.DAILY_STATE_SNAPSHOT,
+        event_time=event_time,
+        received_at=received_at,
+        sequence=sequence,
+        source=source,
+        payload=DailyStateSnapshotEventPayload(
+            instrument_id=instrument_id,
+            trading_state=state,
+            limit_up=limit_up,
+            limit_dn=limit_dn,
+        ),
+    )
+
+
+def price_limit_to_event(
+    instrument_id: str,
+    limit_up: Decimal,
+    limit_down: Decimal,
+    event_time: datetime,
+    sequence: int,
+    source: str,
+    received_at: datetime,
+    buy_side_locked: bool = False,
+    sell_side_locked: bool = False,
+) -> PriceLimitEvent:
+    """把价格限制事实包装成 PriceLimitEvent 的工厂（Runtime/Mock 统一入口）"""
+    return PriceLimitEvent(
+        event_type=MarketEventType.PRICE_LIMIT,
+        event_time=event_time,
+        received_at=received_at,
+        sequence=sequence,
+        source=source,
+        payload=PriceLimitEventPayload(
+            instrument_id=instrument_id,
+            limit_up=limit_up,
+            limit_down=limit_down,
+            buy_side_locked=buy_side_locked,
+            sell_side_locked=sell_side_locked,
+        ),
+    )
+
+
+def trading_session_to_event(
+    exchange: str,
+    session: TradingSessionStage,
+    event_time: datetime,
+    sequence: int,
+    source: str,
+    received_at: datetime,
+) -> TradingSessionEvent:
+    """把时段边界包装成 TradingSessionEvent 的工厂（Runtime 统一入口）"""
+    return TradingSessionEvent(
+        event_type=session,
+        event_time=event_time,
+        received_at=received_at,
+        sequence=sequence,
+        source=source,
+        payload=TradingSessionEventPayload(exchange=exchange, session=session),
+    )
+
+
+# ========== MarketTimeSlice 调度契约 ==========
+
+# 同一 event_time 内的业务边界优先级：
+# OPEN/RESUME 类边界先于市场事实生效；BREAK/CLOSE 类边界后于市场事实生效。
+PRE_SESSION_STAGES = frozenset(
+    {
+        MarketEventType.SESSION_PRE_OPEN,
+        MarketEventType.SESSION_OPEN,
+        MarketEventType.SESSION_BREAK_END,
+    }
+)
+POST_SESSION_STAGES = frozenset(
+    {MarketEventType.SESSION_BREAK_START, MarketEventType.SESSION_CLOSE}
+)
+# 优先级：0=前置边界 < 1=市场事实（Bar/TradingState/PriceLimit，未来 Quote/News 同层） < 2=后置边界
+_PRIORITY_PRE = 0
+_PRIORITY_FACT = 1
+_PRIORITY_POST = 2
+
+
+def market_event_order_key(event: MarketEvent) -> tuple[datetime, int, str, str]:
+    """时间片内稳定排序键：(event_time, 边界优先级, 标识 tie-break, 事件类型)
+
+    tie-break 只服务于确定性与可测试性（同时间事件的技术顺序），
+    不得被解释为交易、选股或资金优先级；不使用随机 event_id 排序。
+    event_type 使用 Canonical enum value（不依赖 str(Enum) 表示）作为
+    末位 tie-break，保证同时间、同标的的多类事实（如 Bar 与
+    TradingState）在输入顺序打乱后规范化顺序仍一致。
+    """
+    if event.event_type in PRE_SESSION_STAGES:
+        priority = _PRIORITY_PRE
+    elif event.event_type in POST_SESSION_STAGES:
+        priority = _PRIORITY_POST
+    elif event.event_type in (
+        MarketEventType.EXCHANGE_STATE_EVENT,
+        MarketEventType.EXCHANGE_STATE_SNAPSHOT,
+    ):
+        # 延迟 import：exchange_state_schema 反向依赖 MarketEvent（T4R）
+        from quant_core.app.data.schema.exchange_state_schema import (
+            ExchangePhase,
+            ExchangeStateEventPayload,
+        )
+
+        if not isinstance(event.payload, ExchangeStateEventPayload):
+            return (event.event_time, _PRIORITY_FACT, _exchange_tie(event), event.event_type.value)
+        # 交易所状态推进继承其来源 Session 边界的优先级（T4R）：
+        # 进入交易类（PRE_OPEN/OPEN）在前置边界层，退出交易类在后置边界层
+        priority = (
+            _PRIORITY_PRE
+            if event.payload.phase in (ExchangePhase.PRE_OPEN, ExchangePhase.OPEN)
+            else _PRIORITY_POST
+        )
+    else:
+        # ExchangeStateSnapshot 是状态事实（基线），属市场事实层
+        priority = _PRIORITY_FACT
+    payload = event.payload
+    tie = getattr(payload, "instrument_id", None) or getattr(payload, "exchange", None) or ""
+    return (event.event_time, priority, str(tie), event.event_type.value)
+
+
+def _exchange_tie(event: MarketEvent) -> str:
+    return str(getattr(event.payload, "exchange", "") or "")
+
+
+class CoarseBarExecutionContext(BaseModel):
+    """粗粒度（日线及以上）时间片的有界模拟执行资格（T4R R3 finding 1，方案 A）
+
+    语义：日线 Bar（时点 15:00）代表该交易日「发生过交易时段」，但日线数据
+    不能证明 15:00 时刻交易所处于 OPEN（盘中临停即反例）。因此：
+
+    - ExchangeState（ExchangePhase/Resolver 投影）**只表达真实交易所运行
+      状态事实**：日线片 15:00 的真实投影是 CLOSED/未初始化，回放绝不发布
+      伪造的 OPEN Snapshot；
+    - 日线 Bar 片可携带 coarse-bar 资格；显式启用的日线开盘 Session 片
+      可携带 coarse-open 资格；仅有日级事实的片零资格；
+    - scope 为 eligible_exchanges：片内 Bar 标的或 Session Open 的交易所集合，
+      该交易所全部标的可提交/撮合（跨标的选股策略友好）；标的级把关仍由
+      OrderExecution 的 TradabilityPolicy 兜底；
+    - decision_time = slice.event_time（决策时点 provenance）；
+    - 本上下文是执行资格，不是交易所事实：不写入 MarketEvent、不映射
+      ExchangePhase、不进入 trace 事实、不跨片累积。
+    """
+
+    reason: Literal["coarse_bar_decision_point", "coarse_open_decision_point"] = (
+        "coarse_bar_decision_point"
+    )
+    decision_time: datetime = Field(..., description="决策时点（= slice.event_time）")
+    eligible_exchanges: tuple[str, ...] = Field(
+        ..., description="本片决策事件的交易所（确定性升序去重）"
+    )
+
+    @field_validator("eligible_exchanges")
+    @classmethod
+    def _validate_scope(cls, scope: tuple[str, ...]) -> tuple[str, ...]:
+        if not scope:
+            raise ValueError("eligible_exchanges 不允许为空：无范围即无资格")
+        if list(scope) != sorted(set(scope)):
+            raise ValueError("eligible_exchanges 必须确定性升序且去重")
+        return scope
+
+
+class MarketTimeSlice(BaseModel):
+    """同一精确 Canonical event_time 的全部市场事件（时间片调度契约）
+
+    由完全相同的 event_time 自然形成：不按分钟/秒截断，不提供时间桶配置；
+    不同 event_time 的事件绝不合并进同一切片。
+
+    Canonical 不变量（构造边界自维护，不依赖生产者自律）：
+    - events 非空；
+    - event_time 必须 timezone-aware；
+    - 片内每个事件的 event_time 与 slice.event_time 完全相同；
+    - events 在构造时按 market_event_order_key 稳定排序——边界事件
+      （OPEN/RESUME 前、BREAK/CLOSE 后）与市场事实的相对顺序表达
+      「边界在何时生效」，其余仅为确定性技术顺序，不表达交易优先级。
+
+    Strategy Runtime 以时间片为调度边界：片内事实全部就绪后才运行策略。
+    """
+
+    event_time: datetime = Field(..., description="时间片的精确市场时间（timezone-aware）")
+    events: list[MarketEvent] = Field(..., description="片内事件（已稳定排序）")
+    # 粗粒度（日线及以上）时间片的模拟执行资格：日线收盘 Bar 片，以及
+    # 显式启用的日线开盘 Session 片可成为策略决策/模拟撮合点；资格由回放
+    # 构造显式授予；与 ExchangeState（真实交易所运行状态事实）完全解耦，
+    # 不得用于伪造 phase，也不参与 DAY 日内到期判定。
+    execution_context: "CoarseBarExecutionContext | None" = Field(
+        default=None, description="粗粒度片的模拟执行资格；日内片恒为 None"
+    )
+
+    @field_validator("events")
+    @classmethod
+    def _stably_sort_events(cls, events: list[MarketEvent]) -> list[MarketEvent]:
+        return sorted(events, key=market_event_order_key)
+
+    @model_validator(mode="after")
+    def _check_slice_invariants(self) -> "MarketTimeSlice":
+        if not self.events:
+            raise ValueError("MarketTimeSlice.events 不允许为空：时间片由至少一个事件形成")
+        if self.event_time.tzinfo is None:
+            raise ValueError(
+                "MarketTimeSlice.event_time 必须 timezone-aware（Canonical 市场时间带时区）"
+            )
+        # T4R R4 finding 1：Context 与片内事件的关系不变量在公开模型边界
+        # 自维护（不依赖 producer 自律，capability 无法在模型层伪造）：
+        # - decision_time 必须等于 slice.event_time；
+        # - 携带 Context 的片必须含 Bar 或 Session Open 决策事件；
+        # - eligible_exchanges 必须精确等于片内决策事件所属交易所的
+        #   确定性升序去重集合（缺失/多余/错误均拒绝）。
+        context = self.execution_context
+        if context is not None:
+            if context.decision_time != self.event_time:
+                raise ValueError(
+                    f"execution_context.decision_time {context.decision_time} 必须等于 "
+                    f"slice.event_time {self.event_time}（决策时点 provenance）"
+                )
+            bar_exchanges: list[str] = []
+            for event in self.events:
+                if event.event_type is not MarketEventType.BAR:
+                    continue
+                parts = str(cast(BarResponse, event.payload).instrument_id).split(
+                    INSTRUMENT_ID_SEPARATOR
+                )
+                if len(parts) != 3 or not parts[1]:
+                    raise ValueError(
+                        f"片内 Bar 的 instrument_id 非法（无法解析 exchange）："
+                        f"{cast(BarResponse, event.payload).instrument_id!r}"
+                    )
+                if parts[1] not in bar_exchanges:
+                    bar_exchanges.append(parts[1])
+            open_exchanges = {
+                cast(TradingSessionEventPayload, event.payload).exchange
+                for event in self.events
+                if event.event_type is MarketEventType.SESSION_OPEN
+            }
+            if not bar_exchanges and not open_exchanges:
+                raise ValueError("无 Bar 或 Session Open 的时间片禁止携带 execution_context")
+            expected = tuple(sorted(set(bar_exchanges) | open_exchanges))
+            expected_reason = (
+                "coarse_bar_decision_point" if bar_exchanges else "coarse_open_decision_point"
+            )
+            if context.reason != expected_reason:
+                raise ValueError("execution_context.reason 与片内决策事件不匹配")
+            if context.eligible_exchanges != expected:
+                raise ValueError(
+                    f"execution_context.eligible_exchanges {context.eligible_exchanges} "
+                    f"必须精确等于片内决策事件交易所集合 {expected}"
+                )
+        # 同片同标的同类型事实唯一：互相冲突的事实会让最终状态依赖输入顺序，
+        # 不能用「最后一条覆盖」或随机 event_id 决胜。
+        # 同一标的同片同时拥有一条 TradingState + 一条 PriceLimit + 一条 Bar 是合法的。
+        # 交易所状态事件（Snapshot/Event）按 exchange 键唯一（T4R）。
+        fact_keys: set[tuple[str, str]] = set()
+        for event in self.events:
+            if event.event_time != self.event_time:
+                raise ValueError(
+                    f"片内事件 event_time {event.event_time} 与 slice.event_time "
+                    f"{self.event_time} 不一致（event_type={event.event_type}）："
+                    "不同时间的事件不得合并进同一切片"
+                )
+            instrument_id = getattr(event.payload, "instrument_id", None)
+            if (
+                event.event_type
+                in (
+                    MarketEventType.TRADING_STATE,
+                    MarketEventType.PRICE_LIMIT,
+                    MarketEventType.DAILY_STATE_SNAPSHOT,
+                )
+                and instrument_id is not None
+            ):
+                key = (event.event_type.value, str(instrument_id))
+                if key in fact_keys:
+                    raise ValueError(
+                        "同一时间片内同一标的的同类型事实必须唯一：重复 "
+                        f"(event_type={key[0]}, instrument_id={key[1]}) 会"
+                        "使结果依赖输入顺序，属于矛盾输入"
+                    )
+                fact_keys.add(key)
+            elif event.event_type in (
+                MarketEventType.EXCHANGE_STATE_SNAPSHOT,
+                MarketEventType.EXCHANGE_STATE_EVENT,
+            ):
+                key = (
+                    event.event_type.value,
+                    str(
+                        cast(
+                            "ExchangeStateEventPayload | ExchangeStateSnapshotEventPayload",
+                            event.payload,
+                        ).exchange
+                    ),
+                )
+                if key in fact_keys:
+                    raise ValueError(
+                        "同一时间片内同一交易所的同类型状态事件必须唯一：重复 "
+                        f"(event_type={key[0]}, exchange={key[1]}) 属矛盾输入"
+                    )
+                fact_keys.add(key)
+        return self
+
+
+class SnapshotFact(BaseModel):
+    """快照里的单条事实（供 SSE/下游展示）"""
+
+    instrument_id: str
+    last: Decimal
+    pct_change: Decimal | None = None
+
+
+def bar_to_bar_event(
+    bar: BarResponse, sequence: int, source: str, received_at: datetime
+) -> BarEvent:
+    """把 Canonical Bar 包装成 BarEvent 的工厂（Runtime 统一入口）"""
+    return BarEvent(
+        event_type=MarketEventType.BAR,
+        event_time=bar.timestamp,
+        received_at=received_at,
+        sequence=sequence,
+        source=source,
+        payload=bar,
+    )
+
+
+async def events_to_aiter(events: list[MarketEvent]) -> AsyncIterator[MarketEvent]:
+    """把事件列表包装成异步迭代器（测试与小数据集复用）"""
+    for event in events:
+        yield event

quant_core/app/data/schema/exchange_operating_state.py

@@ -0,0 +1,37 @@
+"""交易所阶段及其交易能力的只读投影。"""
+
+from dataclasses import dataclass
+from datetime import datetime
+
+from quant_core.app.data.schema.exchange_state_schema import ExchangePhase
+
+
+def phase_capabilities(phase: ExchangePhase | None) -> tuple[bool, bool, bool]:
+    """投影报单、撮合、撤单能力；未知状态安全关闭。"""
+    if phase is ExchangePhase.OPEN:
+        return (True, True, True)
+    if phase is ExchangePhase.PRE_OPEN:
+        return (True, False, True)
+    if phase in (ExchangePhase.BREAK, ExchangePhase.CLOSED):
+        return (False, False, True)
+    return (False, False, False)
+
+
+@dataclass(frozen=True)
+class ExchangeOperatingState:
+    exchange: str
+    phase: ExchangePhase | None
+    as_of: datetime | None = None
+    source_event_id: str | None = None
+
+    @property
+    def order_entry_allowed(self) -> bool:
+        return phase_capabilities(self.phase)[0]
+
+    @property
+    def matching_allowed(self) -> bool:
+        return phase_capabilities(self.phase)[1]
+
+    @property
+    def cancellation_allowed(self) -> bool:
+        return phase_capabilities(self.phase)[2]