powerquant-cli 0.2.6__py3-none-any.whl

quant_core/app/strategy/strategy_context.py

@@ -0,0 +1,316 @@
+"""Strategy-facing runtime context with guarded data and order requests."""
+
+from collections.abc import Callable, Mapping
+from datetime import datetime, time
+from decimal import Decimal
+from typing import Any
+
+from quant_core.app.data.schema.market_schema import BarResponse
+from quant_core.app.factor.constants import FactorStatus as CanonicalFactorStatus
+from quant_core.app.factor.interface.public.factor_exposure_query import IFactorExposureQuery
+from quant_core.app.factor.interface.public.factor_selection import IFactorSelection
+from quant_core.app.factor.schema.factor_contract import FactorSnapshot, FactorValue
+from quant_core.app.factor.schema.selection_types import (
+    SelectionDefinition,
+    SelectionExposure,
+    SelectionResult,
+)
+from quant_core.app.order_execution.domain.order_value import OrderSnapshot
+from quant_core.app.order_execution.interface.public.order_submission import IOrderSubmission
+from quant_core.app.order_execution.schema.order_request_schema import (
+    OrderRequest,
+    OrderRequestType,
+)
+from quant_core.app.strategy.interface.public.portfolio_construction import IPortfolioConstruction
+from quant_core.app.strategy.interface.public.strategy_market_query import IStrategyMarketQuery
+from quant_core.app.strategy.interface.public.strategy_portfolio_reader import (
+    IStrategyPortfolioReader,
+)
+from quant_core.app.strategy.interface.strategy_order_reader import IStrategyOrderReader
+from quant_core.app.strategy.schema.portfolio_target import (
+    PortfolioConstraints,
+    PortfolioDecision,
+    TargetPortfolio,
+)
+
+
+class StrategyContext:
+    """策略运行上下文（环境注入，禁止策略自取 wall-clock / 直连数据源）
+
+    - event_time：当前市场时间（唯一时间权威）
+    - market：IMarketDataQuery（Pull 行情，只允许查 event_time 之前）
+    - factors：当前可用 Canonical FactorValue（factor_name → instrument_id →
+      FactorValue，R2-1：唯一因子值形态）
+    - parameters：Strategy Parameters
+    - state：Strategy 自己的内部运行状态（last_signal_time / trailing_state /
+      custom counters 等）；**禁止**保存 cash / position quantity / cost basis /
+      equity——资产状态归 portfolio（由 Backtest 提供并通过 Portfolio 更新）
+    - portfolio：可选持仓/资金只读视图（IStrategyPortfolioReader）
+    """
+
+    def __init__(
+        self,
+        event_time: datetime,
+        market: IStrategyMarketQuery,
+        factors: dict[str, dict[str, FactorValue]] | None = None,
+        parameters: dict[str, Any] | None = None,
+        state: dict[str, Any] | None = None,
+        portfolio: IStrategyPortfolioReader | None = None,
+        strategy_id: str = "strategy",
+        order_reader: IStrategyOrderReader | None = None,
+        order_api: IOrderSubmission | None = None,
+        current_data: Mapping[str, BarResponse] | None = None,
+        universe: tuple[str, ...] = (),
+        universe_setter: Callable[[tuple[str, ...]], None] | None = None,
+        run_daily: Callable[[str, time], None] | None = None,
+        run_weekly: Callable[[str, int, time], None] | None = None,
+        orders_allowed: bool = True,
+        factor_selection: IFactorSelection | None = None,
+        exposure_query: IFactorExposureQuery | None = None,
+        portfolio_construction: IPortfolioConstruction | None = None,
+    ) -> None:
+        self.event_time = event_time
+        self.market = market
+        self.factors: dict[str, dict[str, FactorValue]] = factors or {}
+        self.parameters: dict[str, Any] = parameters or {}
+        self.state: dict[str, Any] = state if state is not None else {}
+        self.portfolio = portfolio
+        self.strategy_id = strategy_id
+        self.order_reader = order_reader
+        self._order_api = order_api
+        self.decisions: list[PortfolioDecision] = []
+        self.current_data = dict(current_data or {})
+        self.universe = universe
+        self._universe_setter = universe_setter
+        self._run_daily = run_daily
+        self._run_weekly = run_weekly
+        self._orders_allowed = orders_allowed
+        self._factor_selection = factor_selection
+        self._exposure_query = exposure_query
+        self._portfolio_construction = portfolio_construction
+
+    def factor_value(self, factor_name: str, instrument_id: str) -> Any:
+        """读取因子值（R3 P1-1 时点门禁：status 非 AVAILABLE、不存在、或
+        available_at > event_time（Q2=A 下一交易日开盘前不可见）→ 返回 None）"""
+        value = self.factors.get(factor_name, {}).get(instrument_id)
+        if value is None or value.status is not CanonicalFactorStatus.AVAILABLE:
+            return None
+        if value.available_at > self.event_time:
+            return None
+        return value.value
+
+    async def load_factor_exposures(self) -> dict[str, SelectionExposure]:
+        """按当前市场时点读取暴露，标签及未来暴露不会进入选股输入。"""
+        if self._exposure_query is None:
+            raise RuntimeError("当前运行环境未提供暴露查询能力")
+        return await self._exposure_query(self.universe, self.event_time)
+
+    def select_factors(
+        self,
+        definition: SelectionDefinition,
+        exposures: dict[str, SelectionExposure] | None = None,
+    ) -> SelectionResult:
+        """对当前已注入的 PIT 因子截面选股；与研究侧共用同一评分实现。"""
+        if self._factor_selection is None:
+            raise RuntimeError("当前运行环境未提供因子选股能力")
+        required = {item.identity for item in (*definition.factors, *definition.filters)}
+        values = tuple(
+            value
+            for rows in self.factors.values()
+            for instrument_id, value in rows.items()
+            if instrument_id in self.universe and value.identity in required
+        )
+        return self._factor_selection.select(
+            definition,
+            self.universe,
+            FactorSnapshot(decision_time=self.event_time, values=values),
+            exposures=exposures,
+        )
+
+    def construct_portfolio(
+        self,
+        selection: SelectionResult,
+        constraints: PortfolioConstraints,
+        *,
+        current_weights: dict[str, Decimal] | None = None,
+        industries: dict[str, str] | None = None,
+        holding_sessions: dict[str, int] | None = None,
+    ) -> TargetPortfolio:
+        """通过共享构建器生成受约束目标，显式调用 order_target_portfolio 才会提交订单。"""
+        if self._portfolio_construction is None:
+            raise RuntimeError("当前环境未提供组合构建能力")
+        return self._portfolio_construction.build(
+            selection,
+            constraints,
+            current_weights=current_weights,
+            industries=industries,
+            holding_sessions=holding_sessions,
+        )
+
+    def order(
+        self,
+        instrument_id: str,
+        quantity: int,
+        *,
+        limit_price: Decimal | None = None,
+        signal_refs: tuple[str, ...] = (),
+    ) -> OrderSnapshot | None:
+        return self._request(
+            instrument_id,
+            OrderRequestType.QUANTITY,
+            quantity=quantity,
+            limit_price=limit_price,
+            signal_refs=signal_refs,
+        )
+
+    def order_value(
+        self,
+        instrument_id: str,
+        value: Decimal,
+        *,
+        limit_price: Decimal | None = None,
+        signal_refs: tuple[str, ...] = (),
+    ) -> OrderSnapshot | None:
+        return self._request(
+            instrument_id,
+            OrderRequestType.VALUE,
+            value=value,
+            limit_price=limit_price,
+            signal_refs=signal_refs,
+        )
+
+    def order_target(
+        self,
+        instrument_id: str,
+        quantity: int,
+        *,
+        limit_price: Decimal | None = None,
+        signal_refs: tuple[str, ...] = (),
+    ) -> OrderSnapshot | None:
+        return self._request(
+            instrument_id,
+            OrderRequestType.TARGET_QUANTITY,
+            quantity=quantity,
+            limit_price=limit_price,
+            signal_refs=signal_refs,
+        )
+
+    def order_target_value(
+        self,
+        instrument_id: str,
+        value: Decimal,
+        *,
+        limit_price: Decimal | None = None,
+        signal_refs: tuple[str, ...] = (),
+    ) -> OrderSnapshot | None:
+        return self._request(
+            instrument_id,
+            OrderRequestType.TARGET_VALUE,
+            value=value,
+            limit_price=limit_price,
+            signal_refs=signal_refs,
+        )
+
+    def order_target_percent(
+        self,
+        instrument_id: str,
+        percent: Decimal,
+        *,
+        limit_price: Decimal | None = None,
+        signal_refs: tuple[str, ...] = (),
+    ) -> OrderSnapshot | None:
+        return self._request(
+            instrument_id,
+            OrderRequestType.TARGET_PERCENT,
+            target_percent=percent,
+            limit_price=limit_price,
+            signal_refs=signal_refs,
+        )
+
+    def _request(
+        self,
+        instrument_id: str,
+        request_type: OrderRequestType,
+        *,
+        signal_refs: tuple[str, ...] = (),
+        quantity: int | None = None,
+        value: Decimal | None = None,
+        target_percent: Decimal | None = None,
+        limit_price: Decimal | None = None,
+    ) -> OrderSnapshot | None:
+        if not self._orders_allowed:
+            raise RuntimeError("当前生命周期阶段禁止下单")
+        request = OrderRequest(
+            strategy_id=self.strategy_id,
+            instrument_id=instrument_id,
+            request_type=request_type,
+            event_time=self.event_time,
+            signal_refs=tuple(signal_refs),
+            quantity=quantity,
+            value=value,
+            target_percent=target_percent,
+            limit_price=limit_price,
+        )
+        if self._order_api is None:
+            raise RuntimeError("当前环境未提供交易 API")
+        return self._order_api.submit(request)
+
+    def get_order(self, order_id: str) -> OrderSnapshot | None:
+        return self.order_reader.get_order(order_id) if self.order_reader else None
+
+    def get_open_orders(self, instrument_id: str | None = None) -> tuple[OrderSnapshot, ...]:
+        return self.order_reader.open_order_snapshots(instrument_id) if self.order_reader else ()
+
+    def cancel_order(self, order_id: str) -> None:
+        """同步撤单，后续调用立即看到释放后的账户。"""
+        if not self._orders_allowed:
+            raise RuntimeError("当前生命周期阶段禁止撤单")
+        if self._order_api is None:
+            raise RuntimeError("当前环境未提供交易 API")
+        self._order_api.cancel_order(order_id, self.event_time)
+
+    def order_target_portfolio(
+        self,
+        target_weights: Mapping[str, Decimal],
+        *,
+        decision: PortfolioDecision | None = None,
+    ) -> tuple[OrderSnapshot, ...]:
+        """当次提交目标组合订单；决策证据不会成为持续调仓状态。"""
+        if not self._orders_allowed:
+            raise RuntimeError("当前生命周期阶段禁止下单")
+        if self._order_api is None:
+            raise RuntimeError("当前环境未提供交易 API")
+        orders = self._order_api.order_target_portfolio(
+            self.strategy_id, target_weights, self.event_time
+        )
+        if decision is not None:
+            self.decisions.append(decision)
+        return orders
+
+    def order_shares(
+        self, instrument_id: str, quantity: int, *, limit_price: Decimal | None = None
+    ) -> OrderSnapshot | None:
+        """按股数下单。"""
+        return self.order(instrument_id, quantity, limit_price=limit_price)
+
+    def set_universe(self, instrument_ids) -> None:
+        universe = tuple(dict.fromkeys(instrument_ids))
+        if not universe:
+            raise ValueError("universe 不允许为空")
+        if self._universe_setter is None:
+            raise RuntimeError("当前 StrategyContext 不支持动态 universe")
+        self._universe_setter(universe)
+        self.universe = universe
+
+    def run_daily(self, callback_name: str, target_time: time) -> None:
+        if self._run_daily is None:
+            raise RuntimeError("当前 StrategyContext 不支持定时回调")
+        self._run_daily(callback_name, target_time)
+
+    def run_weekly(self, callback_name: str, weekday: int, target_time: time) -> None:
+        if self._run_weekly is None:
+            raise RuntimeError("当前 StrategyContext 不支持定时回调")
+        self._run_weekly(callback_name, weekday, target_time)
+
+    def current(self, instrument_id: str) -> BarResponse | None:
+        return self.current_data.get(instrument_id)

quant_core/app/strategy/strategy_dependency.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+"""Strategy-owned composition for consumers outside the Strategy module."""
+
+from collections.abc import Mapping
+from datetime import date
+from typing import Literal
+
+from quant_core.app.data.constants import BarFrequency
+from quant_core.app.data.interface.market_data_query import IMarketDataQuery
+from quant_core.app.data.schema.adjustment_schema import AdjustmentType
+from quant_core.app.factor.factor_dependency import (
+    build_factor_exposure_query,
+    build_factor_selection,
+)
+from quant_core.app.factor.interface.public.factor_query import IFactorQuery
+from quant_core.app.factor.schema.factor_contract import FactorIdentity
+from quant_core.app.order_execution.interface.public.order_submission import IOrderSubmission
+from quant_core.app.strategy.interface.public.strategy import IStrategy
+from quant_core.app.strategy.interface.public.strategy_portfolio_reader import (
+    IStrategyPortfolioReader,
+)
+from quant_core.app.strategy.interface.strategy_order_reader import IStrategyOrderReader
+from quant_core.app.strategy.schema.portfolio_target import PortfolioConstraints
+from quant_core.app.strategy.schema.python_strategy_schema import PythonStrategySpec
+from quant_core.app.strategy.service.factor_top_n_strategy import FactorTopNStrategy
+from quant_core.app.strategy.service.portfolio_construction_service import (
+    PortfolioConstructionService,
+)
+from quant_core.app.strategy.service.python_strategy_service import (
+    PythonStrategy,
+)
+from quant_core.app.strategy.service.store_factor_reader import StoreFactorReader
+from quant_core.app.strategy.service.strategy_runtime_service import StrategyRuntimeService
+
+
+def python_strategy(spec: PythonStrategySpec, universe: tuple[str, ...]) -> IStrategy:
+    return PythonStrategy(spec, universe)
+
+
+def factor_top_n_strategy(
+    identity: FactorIdentity,
+    universe: tuple[str, ...],
+    top_n: int,
+    constraints: PortfolioConstraints,
+    rebalance_period: Literal["daily", "weekly"] = "daily",
+) -> IStrategy:
+    return FactorTopNStrategy(
+        universe, identity, top_n, constraints, "factor_top_n", rebalance_period
+    )
+
+
+def build_strategy_runtime(
+    *,
+    strategy: IStrategy,
+    identities: tuple[FactorIdentity, ...],
+    market: IMarketDataQuery,
+    factors: IFactorQuery | None,
+    portfolio: IStrategyPortfolioReader,
+    orders: IStrategyOrderReader,
+    order_api: IOrderSubmission,
+    frequency: BarFrequency,
+    adjustment_type: AdjustmentType,
+    dataset_revision: str | None = None,
+    factor_aliases: Mapping[str, FactorIdentity] | None = None,
+    listing_dates: Mapping[str, date] | None = None,
+) -> StrategyRuntimeService:
+    bindings = dict(factor_aliases or {})
+    declared = {item.logical_key for item in identities}
+    if len(declared) != len(identities):
+        raise ValueError("因子依赖身份重复")
+    if any(
+        not alias.isidentifier() or identity.logical_key not in declared
+        for alias, identity in bindings.items()
+    ):
+        raise ValueError("别名必须引用已声明的完整因子身份")
+    bound = {item.logical_key for item in bindings.values()}
+    for identity in identities:
+        if identity.logical_key in bound:
+            continue
+        if identity.name in bindings:
+            raise ValueError("同名因子身份存在歧义，需显式别名")
+        bindings[identity.name] = identity
+    return StrategyRuntimeService(
+        strategy=strategy,
+        market=market,
+        factor_reader=StoreFactorReader(
+            factors,
+            bindings,
+            dataset_revision=dataset_revision,
+        ),
+        portfolio=portfolio,
+        order_reader=orders,
+        order_api=order_api,
+        adjustment_type=adjustment_type,
+        observation_frequency=frequency,
+        listing_dates=listing_dates,
+        factor_selection=build_factor_selection(),
+        exposure_query=build_factor_exposure_query(market),
+        portfolio_construction=PortfolioConstructionService(),
+    )

quant_core/app/trading_runtime/SPEC.md

@@ -0,0 +1,70 @@
+# Trading Runtime SPEC
+
+## 1. Domain Purpose
+
+`trading_runtime` 是与运行场景无关的事件循环内核，负责以注入的 Clock、事件源和领域 Port，按确定顺序驱动 Strategy、Order Execution 与 Portfolio。Backtest、Paper Trading、Live Trading 是它的调用方，不是它拥有的模式分支。
+
+## 2. Responsibilities
+
+- 管理 RuntimeSession、Clock 和生命周期。
+- 接收或拉取 `MarketTimeSlice`，按确定顺序推进事件循环。
+- 调用 Strategy、Order Execution、Portfolio 的公开契约。
+- 记录与具体场景无关的运行 trace。
+
+## 3. Non-Responsibilities
+
+- 不定义市场事实和交易日历。
+- 不定义或复制 Strategy 规则。
+- 不实现订单撮合、费用和滑点规则。
+- 不直接修改资金与持仓。
+- 不生成研究证据或发送通知。
+- 不知道调用方是 Backtest、Paper 还是 Live，不包含按模式分支的业务逻辑。
+- 不拥有 HistoricalReplay、BacktestResult、券商连接或渠道连接。
+
+## 4. Callers
+
+```text
+Backtest ────────┐
+Paper Trading ───┼──> Trading Runtime
+Live Trading ────┘
+```
+
+调用方负责选择并注入 Clock、Market source、Order Execution 和 Portfolio 实现。依赖方向不可反转：`Backtest → Trading Runtime`，Trading Runtime 不依赖 Backtest。
+
+## 5. Core Time-Slice Sequence
+
+```text
+MarketTimeSlice@T
+        ↓
+Order Execution：处理此前已生效 Order
+        ↓
+Fill
+        ↓
+Portfolio Update / Valuation
+        ↓
+PortfolioSnapshot@T
+        ↓
+Strategy → Signal
+        ↓
+Order Planning → OrderIntent
+        ↓
+Order Execution：接受或拒绝，并登记新 Order
+        ↓
+结束 T，推进到 T+1
+```
+
+Strategy 在 T 观察完整事实后产生的新 Order 不得倒回 T 的开盘价或更早时点成交，只能使用其产生之后到达且符合 ExecutionPolicy 的市场事实。
+
+## 6. Cross-Domain Dependencies
+
+- 依赖 Market 的事件源契约。
+- 依赖 Strategy 的运行契约。
+- 依赖 Order Execution 的订单提交与市场推进契约。
+- 依赖 Portfolio 的更新与只读 Snapshot 契约。
+- 禁止 import 其他 Domain 的 Repository 或 Adapter。
+
+## 7. Determinism
+
+- Runtime 以调用方提供的时间边界推进，不自行读取 wall clock 推断业务时间。
+- 同一 TimeSlice 的处理顺序稳定且可复现。
+- Runtime 不隐式补数据，不吞掉 OrderUpdate、Fill 或领域异常。

quant_core/app/trading_runtime/__init__.py

@@ -0,0 +1 @@
+"""Trading Runtime Domain - 统一交易运行时。"""

quant_core/app/trading_runtime/replay/daily_state_expand.py

@@ -0,0 +1,49 @@
+"""日级停牌事实展开；盘中和未知均不能证明任一分钟可交易。"""
+
+from dataclasses import dataclass
+from datetime import date
+from decimal import Decimal
+
+from quant_core.app.data.schema.trading_state_schema import TradingState
+
+
+@dataclass(frozen=True)
+class DailyFact:
+    """日级官方事实的最小只读投影（与 ORM 模型解耦，便于纯函数单测）"""
+
+    trade_date: date
+    suspension_status: str | None
+    limit_up: Decimal | None = None
+    limit_dn: Decimal | None = None
+    extra: dict | None = None
+
+
+@dataclass(frozen=True)
+class ExpandedDailyState:
+    """单日展开结果：该日全部分钟 Bar 共享的状态与可选价格限制"""
+
+    trading_state: TradingState
+    limit_up: Decimal | None = None
+    limit_dn: Decimal | None = None
+
+    @property
+    def has_price_limit(self) -> bool:
+        return self.limit_up is not None and self.limit_dn is not None
+
+
+def expand_daily_state(fact: DailyFact | None) -> ExpandedDailyState:
+    """日级官方事实 → 当日分钟状态（确定性纯函数）
+
+    fact=None 表示该日无事实记录（事实源未覆盖），展开为 UNKNOWN。
+    """
+    if fact is None:
+        return ExpandedDailyState(trading_state=TradingState.UNKNOWN)
+    state = {
+        "none": TradingState.TRADING,
+        "full_day": TradingState.SUSPENDED,
+    }.get(fact.suspension_status or "", TradingState.UNKNOWN)
+    if fact.limit_up is not None and fact.limit_dn is not None:
+        return ExpandedDailyState(
+            trading_state=state, limit_up=fact.limit_up, limit_dn=fact.limit_dn
+        )
+    return ExpandedDailyState(trading_state=state)

quant_core/app/trading_runtime/replay/exchange_state_resolver.py

@@ -0,0 +1,90 @@
+"""Exchange State Resolver - 交易所运行状态唯一投影器（T4R，SSOT）
+
+SSOT：DECISIONS 2026-09-07 用户裁定「Exchange Operating State」。
+本模块是交易所运行状态的**唯一持有者**：Snapshot 建立基线、增量 Event
+推进窗口内状态；`order_entry_allowed` / `matching_allowed` /
+`cancellation_allowed` 是基于 phase 与交易所规则的**投影**，绝不与
+phase 并列存储（phase 与 capability 不允许两套 SSOT）。
+
+状态语义（与 MarketStateResolver 同构）：
+- 事实从 event_time 生效并持续到后续事实显式覆盖；
+- Snapshot 是状态基线（bounded replay 起点），增量 Event 是 transition；
+  同片内增量比基线更具体、后生效覆盖；
+- 从未有任何事实 → 未初始化安全默认（全部 capability=False）；
+- slice 时间严格递增；先完整计算再统一提交（失败零部分修改）。
+
+边界：本模块属于 Market 域，只消费纯市场事实；不输出订单的
+ALLOW/DEFER/REJECT（该决策属于 Order Execution 的 TradabilityPolicy，
+其消费的是本模块的 capability 投影）。
+"""
+
+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.exchange_operating_state import ExchangeOperatingState
+from quant_core.app.data.schema.exchange_state_schema import (
+    ExchangePhase,
+    ExchangeStateEventPayload,
+    ExchangeStateSnapshotEventPayload,
+)
+
+
+class ExchangeStateResolver:
+    """交易所运行状态增量投影器（有状态、按时间片顺序消费；唯一 SSOT）
+
+    用法：按市场时间顺序对每个 MarketTimeSlice 调用 apply_slice，
+    之后读取 resolve(exchange) / snapshot()。投影不可变。
+    """
+
+    def __init__(self) -> None:
+        # exchange -> (phase, as_of, source_event_id)；仅由显式状态事实写入
+        self._states: dict[str, tuple[ExchangePhase, datetime, str]] = {}
+        self._last_slice_time: datetime | None = None
+
+    def apply_slice(self, time_slice: MarketTimeSlice) -> dict[str, ExchangeOperatingState]:
+        """消费一个时间片内的交易所状态事实并更新投影
+
+        时间推进约束与失败原子性同 MarketStateResolver：先完整计算本片
+        更新再统一提交，循环内不改 self。
+        """
+        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}"
+            )
+        # 基线先应用、增量后应用：同片内增量（transition）覆盖基线——
+        # 片内规范序会把前置边界层的增量排在事实层快照之前，因此不能按
+        # 事件顺序应用，必须分两批统一提交
+        snapshot_updates: list[tuple[str, tuple[ExchangePhase, datetime, str]]] = []
+        event_updates: list[tuple[str, tuple[ExchangePhase, datetime, str]]] = []
+        for event in time_slice.events:
+            payload = event.payload
+            if isinstance(payload, ExchangeStateSnapshotEventPayload):
+                snapshot_updates.append(
+                    (payload.exchange, (payload.phase, event.event_time, event.event_id))
+                )
+            elif isinstance(payload, ExchangeStateEventPayload):
+                event_updates.append(
+                    (payload.exchange, (payload.phase, event.event_time, event.event_id))
+                )
+        for exchange, entry in snapshot_updates:
+            self._states[exchange] = entry
+        for exchange, entry in event_updates:
+            self._states[exchange] = entry
+        self._last_slice_time = time_slice.event_time
+        return self.snapshot()
+
+    def snapshot(self) -> dict[str, ExchangeOperatingState]:
+        """全部已知交易所的当前 point-in-time 状态（新对象）"""
+        return {exchange: self.resolve(exchange) for exchange in self._states}
+
+    def resolve(self, exchange: str) -> ExchangeOperatingState:
+        """单交易所当前 point-in-time 状态；从未有任何事实 → 安全默认"""
+        entry = self._states.get(exchange)
+        if entry is None:
+            return ExchangeOperatingState(exchange=exchange, phase=None, as_of=None)
+        phase, as_of, event_id = entry
+        return ExchangeOperatingState(
+            exchange=exchange, phase=phase, as_of=as_of, source_event_id=event_id
+        )