逻辑模块契约

状态：规划

最后复核：2026-08-15

关联：Issue #3、PR #4

长期讨论：GitHub Discussions

状态与目的

本文定义目标系统的逻辑架构约束，供后续 Issue 设计和验收使用。它描述 target state（目标状态），不代表这些 Module 已实现，也不授权真实下单。

当前仓库包含工程治理、架构文档、文档部署工具和空 Rust workspace；没有行情、订单、风控或交易能力，不可投入真实资金，也未达到生产就绪状态。

设计层次与术语

• Layer（层）： 依赖政策，规定哪些知识可以指向哪些知识；它不等于目录、crate 或独立进程。
• Module（模块）： 通过一个 Interface 拥有一组内聚状态与行为的逻辑单元；它不等于 crate。Module 应隐藏足够复杂度，删除它会迫使这些复杂度散回多个调用者；纯转发不构成独立 Module。
• Interface（接口）： 调用者正确使用 Module 必须知道的完整契约，包括输入输出、不变量、顺序、失败语义、配置和性能特征；它不只是 Rust 函数签名或 trait。
• Seam（接缝）： 确有替换需求时放置 Interface、允许替换行为的位置。
• Adapter（适配器）： 在 Seam 处满足 Interface、把外部表示或传输语义转换为内部契约的具体实现。一个实现只说明潜在 Seam；两个真实 Adapter 才证明需要稳定 Seam，不为每个 Module 预设 trait。
• Deployment/sharding（部署/分片）： 将逻辑 Module 映射到进程、机器和 shard 的后续决策，不等于逻辑分层，也不改变状态所有权。

依赖政策

既定总方向是：

domain <- engine <- adapters/runtime <- apps

A <- B 的精确定义是“B 可以在编译期依赖 A 的稳定 Interface，A 不得依赖 B”。运行时事件可以双向流动，但回报流不反转编译依赖。

允许依赖：

• domain 只使用语言与标准库能力，不知道网络、venue DTO、持久化、异步 runtime、系统时钟、环境变量或观测出口。
• engine 可依赖 domain；核心状态转换通过显式输入产生新状态和 effect。
• adapters/runtime 可依赖 engine 与 domain，负责外部协议、I/O、调度、持久化出口和事件投递。
• apps 可依赖前三层以完成组装和运维入口，但不得承载或旁路业务决策。

禁止依赖：

• domain 或 engine 不得依赖 venue DTO、具体 Adapter、runtime、app、数据库或观测后端。
• Adapter 不得相互调用来形成隐藏业务流程；跨 Adapter 协调必须回到拥有状态的 engine Module。
• app、Control Plane 或 Observability 不得直接写 book、order、risk 或 account 权威状态。
• 逻辑分层不得被解释为预先创建同名目录、crate、trait、进程或网络 Seam。

逻辑 Module map

下图中的实线箭头表示同步或受控主路径；虚线表示异步出口、只读反馈或控制输入。它展示依赖政策和职责区域，不规定目录、crate、进程或部署。

编辑源：module-architecture.excalidraw

Market Data Ingress / Venue Normalization、Market Data Synchronization + Authoritative Book、Execution Coordination / Quote Reconciliation、Reconciliation + Recovery 和 Journal / Replay 各自合并紧密耦合的步骤：分开只会暴露中间状态并形成浅层转发 Module。只有后续证据显示它们存在独立状态所有权或真实替换需求时才拆分。

venue/drop-copy 等外部对账输入在实现时也必须先由 adapters/runtime 中的具体 Adapter 终止 DTO 并规范化；这个外部输入角色不在本文预建为独立 Module、稳定 Seam 或 trait。

Module 职责卡

Domain Kernel

• Purpose： 统一价格、数量、身份、事件、effect 和跨 Module 不变量的业务含义。
• Owns： 不拥有运行时可变业务状态；拥有整数 tick/lot、身份、事件/effect 与不变量的权威语义。
• Inputs： 已规范化、显式版本化的业务值。
• Outputs/effects： 可验证的值、事件和 effect 描述，不执行 effect。
• Invariants： 相同输入产生相同结果；价格和数量只用整数 tick/lot；无 venue DTO。
• Failure semantics： 非法单位、身份或状态转换被明确拒绝，不猜测或修复输入。
• Hot / warm / cold path： hot；纯确定性计算。
• Allowed dependencies： 语言与标准库。
• Must not： I/O、系统时钟、随机数、环境变量、异步 runtime、持久化、策略或 venue 逻辑。
• Observable acceptance surface： 未来 Issue 通过合法/非法值、顺序和重放样例验证不变量与确定性 effect。

Market Data Ingress / Venue Normalization

• Purpose： 解码 wire DTO，附加显式接收时间与来源身份，并把 venue 语义转换成内部市场事件。
• Owns： 仅拥有输入连接/解码会话上下文；不拥有 book 或业务 sequence 权威状态。
• Inputs： venue wire frame 或已记录的原始输入、版本化连接元数据和时间戳。
• Outputs/effects： 规范化市场事件或明确的解码/协议错误。
• Invariants： DTO 在此终止；来源、时间、精度和 venue 特有语义不丢失也不伪造。
• Failure semantics： 无法解码、未知版本或不完整输入被拒绝并触发不可用信号；不生成猜测事件。
• Hot / warm / cold path： hot 解码；连接建立、重连与协议诊断为 warm。
• Allowed dependencies： Domain Kernel、目标 Market Data Synchronization Interface，以及必要的外部协议/runtime 能力。
• Must not： 维护权威 book、计算信号、决定报价、写订单、执行风控或把 DTO 泄漏给 engine/domain。
• Observable acceptance surface： 用记录输入验证规范化结果、来源/时间保真、错误分类和 DTO 不越过 Interface。

Market Data Synchronization + Authoritative Book

• Purpose： 将 snapshot/delta 对齐，处理 sequence、gap、stale 与 generation，并维护唯一有效 L2 book。
• Owns： validated order book 及其 generation、sequence、stale/valid 状态。
• Inputs： 规范化 snapshot/delta、显式时间/配置 epoch、恢复或失效事件。
• Outputs/effects： 非权威只读 BookView、book 更新事件、失效/重同步 effect。
• Invariants： 每个 shard 单写者；只发布通过顺序与完整性验证的 generation；同一有序输入产生同一 book 和 effect。
• Failure semantics： gap、乱序、陈旧、未知 generation 或恢复不完整时立即失效并 fail-closed，直到新的有效同步证据建立。
• Hot / warm / cold path： hot 更新与校验；snapshot 获取/恢复协调为 warm；记录与诊断为 cold。
• Allowed dependencies： Domain Kernel；由 Runtime 注入的显式输入，不依赖具体 Ingress Adapter。
• Must not： 访问网络/系统时钟、计算策略、发送订单、共享可变 book、把 BookView 当作第二权威副本。
• Observable acceptance surface： 通过 snapshot/delta、gap、stale、generation 切换与重放序列验证 book、有效性和 effect。

Feature / Signal Engine

• Purpose： 从已验证 market/account view 增量计算可复现的微观结构特征与信号。
• Owns： feature state、输入版本游标和已发布 signal generation。
• Inputs： 有效 BookView、显式时间/配置输入，以及确有需要的非权威 account view。
• Outputs/effects： 带输入版本的非权威 FeatureView/signal；不产生网络 effect。
• Invariants： 不接受无效 book；相同有序输入和配置产生相同 feature state。
• Failure semantics： 输入 stale、gap、未知或配置不匹配时使输出失效，不沿用旧信号。
• Hot / warm / cold path： hot 增量计算；重建为 warm；分析导出为 cold。
• Allowed dependencies： Domain Kernel 与 Market Data Synchronization 的 Interface；必要时读取 Account 的非权威 view。
• Must not： 写 book/account 状态、决定订单、执行 I/O、隐式读取时间/随机数或保留无版本缓存作为权威。
• Observable acceptance surface： 用版本化 book 序列验证增量结果、失效传播、重建等价性和确定性。

Strategy / Quote Policy

• Purpose： 根据有效 market、feature、account 与 risk view 形成目标报价/撤单意图。
• Owns： strategy state、desired quotes 及其决策 generation。
• Inputs： 版本化 BookView、FeatureView、account/risk view、配置、时间与显式随机输入（若未来确有需要）。
• Outputs/effects： 带因果版本的目标报价和撤单意图，不是交易命令。
• Invariants： 相同有序输入产生相同意图；任何依赖 view 无效时不产生新增风险意图。
• Failure semantics： stale/unknown/recovery incomplete 时输出停止/撤单意图并 fail-closed；不复用无法证明安全的旧报价。
• Hot / warm / cold path： hot 决策；参数切换与状态重建为 warm；分析为 cold。
• Allowed dependencies： Domain Kernel 及 market/feature/account/risk 的只读 Interface。
• Must not： I/O、网络访问、直接下单、分配 client order id、修改 live order/account/risk 权威状态或旁路 Execution。
• Observable acceptance surface： 通过固定输入序列验证意图、因果版本、失效行为、撤单优先和确定性。

Execution Coordination / Quote Reconciliation

• Purpose： 比较 desired quotes 与 OMS 提供的 live-order view，生成最小候选下单/改单/撤单操作并确定安全优先级。
• Owns： reconciliation cursor、已处理目标 generation 与候选计划的因果状态；不拥有 desired quotes 或 live order 生命周期。
• Inputs： Strategy 意图、OMS 非权威 LiveOrderView、venue 能力与显式配置。
• Outputs/effects： 带因果关系和优先级的候选操作，必须交给 Independent Pre-trade Risk。
• Invariants： 撤销风险的操作优先；重复输入幂等；候选操作可追溯到目标和 live-order generation。
• Failure semantics： 任一输入 unknown/stale 或 diff 无法证明安全时不产生新增风险操作，只允许经政策定义的风险降低候选。
• Hot / warm / cold path： hot diff/排序；能力/配置切换为 warm；解释记录为 cold。
• Allowed dependencies： Domain Kernel、Strategy 与 OMS 的只读 Interface。
• Must not： 绕过 Risk/OMS、发送网络命令、分配订单身份、确认订单状态、拥有风险限额或实现策略。
• Observable acceptance surface： 从目标与 live-order 组合验证最小 diff、替换/撤单顺序、幂等、因果关系和 fail-closed。

Independent Pre-trade Risk

• Purpose： 独立评估每个候选操作，执行硬限制、stale/unknown/recovery 门禁与 kill gate。
• Owns： risk limits、计数器、额度占用、gate/kill 投影视图和风险判定 generation；Control Plane 仍是 operator kill 命令的权威来源。
• Inputs： 候选操作、OMS/account/book 的版本化只读 view、Control Plane 的配置/模式/kill 事件和恢复门禁。
• Outputs/effects： 明确许可或拒绝结果及原因；许可只对绑定的候选与输入 generation 有效。仅取消 OMS 已知 live order 的候选可以获得范围受限的 cancel-only permit（仅撤单许可）。
• Invariants： 默认拒绝；所有新增或增加风险的操作必须经过完整风险评估。cancel-only permit 只能绑定已知订单身份且不能创建、替换或扩大订单；限额与计数更新单写者且可审计。
• Failure semantics： 风险状态 stale、gap、unknown、版本不一致或恢复未完成时，拒绝所有新增/增加风险操作，只允许经最小身份与操作类型校验的 cancel-only 候选。Risk 执行本身不可用时不签发任何许可，转由实盘准入前已验证并预置的 venue dead-man、cancel-on-disconnect 或等价会话安全机制撤销挂单，随后保持 recovery not-ready 直到完成对账。
• Hot / warm / cold path： hot 判定/计数；限额版本切换和恢复为 warm；审计导出为 cold。
• Allowed dependencies： Domain Kernel 与 book/OMS/account/control/recovery 的只读 Interface。
• Must not： 生成策略意图、分配 client order id、发送命令、接受旁路调用、把 Observability 当门禁状态或允许 MARKET order 作为回退。
• Observable acceptance surface： 验证每条硬限制、计数和确定性原因；普通许可必须绑定候选与输入 generation，cancel-only permit 必须额外绑定同一 OMS 已知 live order。stale/unknown/kill/recovery 状态下应拒绝所有新增/增加风险操作且仅允许这种受限撤单；Risk 执行不可用时不得产生任何许可。

OMS

• Purpose： 把经风险许可的候选操作转为可审计交易命令，并维护订单完整生命周期与幂等因果关系。
• Owns： client order id、live order lifecycle，以及 pending/ack/reject/fill/cancel 状态和命令幂等键。
• Inputs： 风险许可的候选操作、Trading Venue Adapter 执行回报、恢复/对账修正事件和显式时间/配置。
• Outputs/effects： 交易命令 effect、订单状态事件和非权威 LiveOrderView。
• Invariants： 每条交易命令都必须匹配有效 Risk 许可：创建/替换使用完整许可，显式撤单使用绑定同一 OMS 已知 live order 与输入 generation 的 cancel-only permit。client order id 唯一；状态迁移按因果顺序且可重放。
• Failure semantics： 重复回报幂等；未知、矛盾或缺失回报使相关订单/账户进入不确定状态并触发恢复门禁，不猜测成交或成功。
• Hot / warm / cold path： hot 命令与回报状态转换；超时、恢复、对账为 warm；审计导出为 cold。
• Allowed dependencies： Domain Kernel、Risk 许可 Interface 和 Reconciliation/Recovery 输入；交易命令以 transport-neutral effect（传输无关效果）交由外层路由。
• Must not： 自行放宽风险、实现策略、直接读取 venue DTO、让 Adapter 成为订单权威状态或把 MARKET order 作为错误回退。
• Observable acceptance surface： 验证创建/替换与显式撤单各自匹配正确许可、cancel-only 的订单身份/generation 绑定、无许可不形成命令，以及 ID 唯一、状态机、重复/乱序回报、幂等、因果链与恢复触发。

Trading Venue Adapter

• Purpose： 对交易命令做协议编码、认证与发送，并把执行回报解码为 OMS 可消费的内部事件。
• Owns： 仅拥有 transport/auth session、请求关联与协议级发送状态；不拥有订单业务生命周期。
• Inputs： OMS 交易命令 effect、venue wire 执行回报、显式凭据句柄和连接配置。
• Outputs/effects： wire 发送结果、规范化执行回报和连接健康事件。
• Invariants： 命令身份与因果标识不变；凭据不进入 domain、日志或 journal 明文；回报 DTO 在此终止。进入真实交易模式前必须证明并预置 venue dead-man、cancel-on-disconnect 或等价会话安全机制。
• Failure semantics： 发送结果未知、认证失败或断线时报告不确定性并触发恢复，不擅自重试可能重复的命令。Risk/OMS 显式撤单路径不可用时只执行预先授权的会话失效安全动作；该动作不是下单旁路，其结果仍须由 OMS 和 Recovery 对账。
• Hot / warm / cold path： hot 编解码/发送；连接、认证与重连为 warm；协议诊断为 cold。
• Allowed dependencies： Domain Kernel、OMS Interface，以及必要的协议、网络和 runtime 能力。
• Must not： 包含策略/风险决策、生成未获许可命令、修改 OMS/account 权威状态、记录密钥或以 MARKET order 回退。
• Observable acceptance surface： 用协议样例验证编码、关联、回报转换、未知发送结果、重复回报、断线和密钥不泄漏；另须证明预置会话安全机制不编码订单，触发与结果可审计，并把结果送回 OMS/Recovery 对账。

Account / Portfolio State

• Purpose： 依据已确认执行与权威账户事件维护持仓、余额、敞口和费用状态。
• Owns： 本地 positions、balances、exposure、fees 的权威投影及其 generation；venue/drop-copy 是外部核对来源，不直接共享写入。
• Inputs： OMS 成交/更正事件、经外部 Adapter 规范化的 venue/drop-copy 等价账户事件、配置和对账结果。
• Outputs/effects： 版本化非权威 AccountView、差异事件和恢复/对账请求。
• Invariants： 状态变更有唯一事件因果来源；重复成交幂等；资产、账户和 generation 不混用。
• Failure semantics： 缺失、冲突或无法对账的事件使相关范围 unknown 并关闭交易门禁，不猜测余额或敞口。
• Hot / warm / cold path： fill 驱动的必要风险投影为 hot/warm；全量余额与费用对账为 warm；报表为 cold。
• Allowed dependencies： Domain Kernel、OMS 事件 Interface 与 Reconciliation/Recovery 的核对输入。
• Must not： 发送订单、批准风险、采信 UI/metrics 为权威来源、让 Strategy 写持仓或并存第二个可写账户副本。
• Observable acceptance surface： 验证成交/更正/重复序列、余额与敞口计算、generation、差异检测和 unknown 传播。

Reconciliation + Recovery

• Purpose： 对比本地权威状态与 venue/drop-copy 等价来源，并协调启动、断线和不确定状态的恢复门禁。
• Owns： reconciliation run、差异集合、recovery phase/readiness 与恢复证据状态。
• Inputs： OMS/account/book 快照，经外部 Adapter 规范化的 venue/drop-copy 等价快照或事件，checkpoint、配置 epoch 和连接状态。
• Outputs/effects： 差异、确定性的修正/重建事件、恢复请求和绑定范围的 ready/not-ready 门禁。
• Invariants： 未有完整对账证据不得宣告 ready；修正经拥有状态的 Module 应用，不直接双写其状态。
• Failure semantics： 来源缺失、generation 不一致、差异未解决或恢复中断时保持 not-ready 并 fail-closed。
• Hot / warm / cold path： assurance/recovery warm path；大规模扫描和证据归档为 cold，不进入逐事件热路径。
• Allowed dependencies： Domain Kernel，以及 book、OMS、Account、Control 的快照/事件 Interface；checkpoint 作为外层注入的显式输入。
• Must not： 直接拥有或写 book/order/account/risk 状态、绕过 Risk 打开交易、把 Observability 或 UI 视为恢复证据。
• Observable acceptance surface： 模拟启动、断线、缺失/冲突事件、checkpoint 恢复和会话安全机制触发，验证差异、修正路由，并证明其结果完成对账前始终保持 not-ready。

Journal / Replay

• Purpose： 对原始输入、规范化事件、决策、风险结果、订单命令与回报建立可审计顺序记录，并以相同输入重放核心行为。
• Owns： journal offsets、segment/checkpoint 元数据和已持久化范围；记录内容不取代各业务 Module 的权威状态。
• Inputs： 带因果/版本标识的记录 effect、原始输入，以及显式 replay 配置。
• Outputs/effects： 持久化确认、checkpoint、按确定顺序读取的 replay stream 与完整性错误。
• Invariants： 顺序、来源、版本和因果关系可验证；秘密不得落盘；replay 不隐式读取当前时间或配置。
• Failure semantics： sink 迟滞、写入失败或完整性损坏显式上报并按安全政策触发门禁；不得静默丢弃必需审计记录。
• Hot / warm / cold path： 热路径只产生非阻塞记录 effect；持久化、checkpoint 和 replay 在 warm/cold path。
• Allowed dependencies： Domain Kernel 与 runtime/存储能力；通过稳定记录契约消费 engine effect。
• Must not： 阻塞热路径、直接修改业务权威状态、把日志文本当 replay 契约、引入未证明需要的通用存储 Seam。
• Observable acceptance surface： 验证顺序、完整性、缺失/损坏检测、checkpoint 与相同输入的核心状态/effect 等价性。

Runtime / Shard Coordinator

• Purpose： 为逻辑 Module 提供事件排序、单写者执行、显式时钟/调度、背压和 shard 生命周期。
• Owns： shard assignment/lifecycle、事件队列顺序、背压状态和调度 epoch；不拥有业务状态。
• Inputs： 外部/内部事件、版本化时钟 tick、控制命令和 runtime 配置。
• Outputs/effects： 有序投递、生命周期/背压事件、待执行 I/O effect，以及预先授权且不编码订单的会话失效安全 effect。
• Invariants： 每个 shard 的热状态同时只有一个写入者；排序规则明确；配置/时钟切换有 epoch；会话安全 effect 必须可审计且不能表达创建、替换或扩大订单。
• Failure semantics： 队列溢出、调度未知、所有权冲突或时钟异常时停止相关 shard 的新增风险行为并触发恢复；Risk/OMS 路径不可用时按已验证政策激活预置会话安全机制。
• Hot / warm / cold path： hot 排序/投递；shard 迁移、背压恢复为 warm；诊断为 cold。
• Allowed dependencies： Domain Kernel 与 engine Module Interface，以及必要的 runtime/I/O Adapter。
• Must not： 承载策略、book、风险或订单语义，隐式读取纯逻辑所需时间/随机数，通过多写者提高吞吐，或把会话失效安全 effect 扩展成普通交易命令旁路。
• Observable acceptance surface： 验证顺序、单写者、epoch、背压、生命周期和故障时的 fail-closed 投递；会话安全 effect 必须不编码订单，触发/结果可审计，并使 Recovery 在对账完成前保持 not-ready。

Control Plane

• Purpose： 管理版本化配置、trading mode、启动/停止、operator command 和 kill switch，并把它们变成可审计事件。
• Owns： config epoch、trading mode、operator kill state 和控制命令生命周期。
• Inputs： 经认证授权的 operator command、配置候选、运行/恢复状态。
• Outputs/effects： 版本化控制事件、拒绝原因，以及供 Runtime/Risk 消费的非权威 view；kill 可请求 Runtime 激活预置的会话安全机制。
• Invariants： kill/停止优先；配置切换原子且带 epoch；所有控制命令进入同一可审计状态转换。
• Failure semantics： 身份、版本、状态或授权未知时拒绝；Control Plane 不可用不能打开交易。
• Hot / warm / cold path： control/warm path；kill 传播具有安全优先级但不把 UI 放入热业务路径；审计为 cold。
• Allowed dependencies： Domain Kernel 与 Reconciliation/Recovery 的状态 Interface；operator/runtime 状态由外层转换成显式输入事件。
• Must not： 旁路 Risk/OMS/Runtime 直接触达 Trading Adapter、直接写业务权威状态、从 UI 状态推断交易许可。
• Observable acceptance surface： 验证授权、epoch、模式转换、kill 优先级、重复命令幂等、审计链与不可用时拒绝；kill 必须同时关闭 Risk 门禁，并按既定政策请求 Runtime 激活预置会话安全机制。

Observability / Audit Export

• Purpose： 异步导出 metrics、log、trace 和审计副本，支持诊断、恢复验证和生产准入证据。
• Owns： 仅拥有出口缓冲、投递游标和后端健康状态；所有观测数据都是非权威副本。
• Inputs： 结构化观测/审计 effect 和显式标签/配置版本。
• Outputs/effects： 后端投递、丢弃/降级计数和出口健康信号。
• Invariants： 不阻塞热路径；敏感信息被过滤；标签基数与采样政策显式版本化。
• Failure semantics： 后端失败不得反向修改业务状态；必需审计出口失败通过 Control/Risk 政策触发安全门禁，而非由 exporter 自行控制。
• Hot / warm / cold path： cold async path；热路径只产生有界、非阻塞 effect。
• Allowed dependencies： 结构化 effect 契约、runtime 与外部观测 Adapter。
• Must not： 成为 book/order/risk/account 权威来源、回调控制热路径、记录密钥、承载业务恢复逻辑。
• Observable acceptance surface： 验证异步性、背压/丢弃可见性、敏感信息过滤、游标和后端故障不反向写业务状态。

App / Operator Surface

• Purpose： 组装具体 Module/Adapter/runtime，提供受约束的启动、停止与运维入口。
• Owns： 不拥有交易业务状态；仅拥有进程级组装与入口生命周期。
• Inputs： 启动参数、经认证 operator input 和部署环境提供的资源句柄。
• Outputs/effects： Module 组装、受控 operator command 提交和进程退出状态。
• Invariants： 所有控制动作进入 Control Plane；所有交易动作经过 Execution、Risk、OMS 与 Trading Adapter。
• Failure semantics： 配置、依赖或身份校验失败时不启动/不进入交易模式；关闭时保持审计与恢复语义。
• Hot / warm / cold path： control/cold path，不参与逐事件热业务决策。
• Allowed dependencies： domain、engine、adapters/runtime，仅用于 composition root（组装根）与入口。
• Must not： 直接写 book/order/risk/account，旁路 Control/Risk/OMS 触达 Adapter，嵌入策略语义或成为第二状态机。
• Observable acceptance surface： 验证组装失败、启动/停止、命令路由、权限拒绝和不存在任何交易旁路。

唯一状态所有者

“权威”表示只有该 Module 能提交对应状态转换；其他 Module 只能消费带 generation/epoch 的不可变快照、事件或 derived view（派生视图）。

Trading Adapter 的 transport session、Ingress 的 decode session、Observability 的出口游标和 app 的进程生命周期只在各自实现范围内权威；它们不得被提升为 book、order、risk、account 或交易许可的权威来源。

受控事件流

下图是事件/effect 流，不代表编译依赖。虚线反馈均为带版本的只读 view 或事件；任何真实交易操作只有一条受控路径。

编辑源：order-lifecycle-sequence.excalidraw

市场数据与恢复时序

市场数据时序区分正常发布与 gap/stale 的 fail-closed 分支；Feature Engine 标为未来能力，异步 Journal 不阻塞热路径。

编辑源：market-data-sequence.excalidraw

恢复与对账时序覆盖启动、断线、market-data gap 和进程重启；只有权威状态一致且 recovery complete 才能进入 trading-ready。

编辑源：recovery-reconciliation-sequence.excalidraw

跨 Module 固定规则

• 核心转换统一为 event in -> state/effect out；相同有序输入、配置、时间与随机输入必须产生相同核心状态和 effect。
• 每个 shard 的热状态只有一个写入者；冷路径异步，I/O、持久化和观测不得阻塞热路径。
• 时间、随机数和配置必须作为显式、版本化输入；纯逻辑不得隐式读取系统时钟、随机源或环境变量。
• stale、gap、unknown 或 recovery incomplete 一律 fail-closed。
• Observability、UI 和 journal sink 都不是业务权威状态。
• 不设置全局共享可变 order book、order、risk 或 account 状态；跨 Module 只传递不可变事件、effect 和带版本的非权威 view。
• Strategy 不做 I/O，不直接发送网络请求或交易命令。
• 真实交易命令只能沿 Execution -> Risk -> OMS -> Trading Adapter 路径；Control、app、Strategy 和恢复流程都不得旁路。
• 显式撤单同样经过 Risk 的 cancel-only 校验和 OMS。Risk 执行本身不可用时，只能激活实盘准入前已验证并预置的 venue dead-man、cancel-on-disconnect 或等价会话安全机制；这不是普通交易命令旁路，触发和结果必须记录，并在恢复/对账完成前保持禁止交易。
• 延迟只定义未来测量边界：输入接收、book 生效、决策产生、风险完成、命令交付和执行回报归因；在真实测量前不给出数字或保证。

固定与暂缓决策

现在固定：

• 单进程 modular monolith 起步。
• 本文的逻辑 Module 边界、唯一状态所有者和受控交易路径。
• 每 shard 热状态单写者、确定性输入模型、fail-closed 和独立 Risk 不可旁路。
• 冷路径异步，外部 DTO 在 Adapter 终止，Interface 是未来 Issue/QA 的验收面。

暂缓到真实 vertical slice 提供证据后决定：

• crate/file 布局、具体 Rust trait/function/event schema。
• async runtime、内存数据结构、持久化格式和第三方依赖。
• 进程拆分、机器部署、shard key、跨进程协议和具体 latency budget。
• 任何 Seam 的代码形式；只有两个真实 Adapter 证明替换需求后才稳定 Seam。

Phase 1 最小映射

第一条 deterministic market-data vertical slice 只映射：

1. Domain Kernel 中该切片真实需要的整数 tick/lot、身份、市场事件与 effect 类型。
2. 一个 recorded input Adapter 或等价的最小输入边界；它是具体输入角色，不预先创建通用 trait 或可替换 Seam。
3. Market Data Synchronization + Authoritative Book，覆盖 snapshot/delta、sequence/gap/stale/generation 与唯一权威 L2 状态。
4. Journal / Replay 中仅用于证明相同记录输入产生相同 book 状态/effect 的 deterministic replay harness；不预建持久化平台。

本映射不实现 Strategy、Execution、Risk、OMS、Trading Venue Adapter、Account、Control 或生产部署能力，也不在本 Issue 创建任何代码或目录骨架。