架构与边界

单向依赖

flowchart LR
  A["cards / effects / ids"] --> B["loader"]
  A --> C["state"]
  B --> D["legality"]
  C --> D
  B --> E["resolve 主结算管线"]
  C --> E
  D --> E
  E --> F["observe"]
  E --> G["runtime 最小对局编排层"]
  F --> G
  B --> G

底层模型不知道文件路径、服务端或展示层。runtime 位于依赖图顶部，负责把已有纯规则 能力组合成稳定的无头对局接口，但规则模块不会反向依赖它。

模块责任

模块	责任
cards/	卡面、关键词、静态规则和 typed native rule 数据形状
effects/	声明式 DSL 的效果、选择器、条件和表达式
loader/	严格解析、合并、索引与交叉引用验证
state/	可克隆、可序列化的全部对局可变状态
legality/	枚举和重验玩家当前可执行的动作
resolve/	当前生产主管线；事务化执行动作、事件与监听器
resolve_v2/	并存的帧/窗口原语来源；不替代主管线
observe.rs	按玩家视角构造结构性遮蔽的观察
runtime/	卡池、构筑、开局、会话、指纹、快照和回放

确定性

状态中的随机数发生器是唯一随机源。候选集在进入待选状态时冻结；确认选择不会重掷。 涉及集合时使用稳定遍历顺序，状态与卡池指纹基于稳定序列化内容计算。确定性意味着：

• 相同卡池、种子、初始状态和动作序列产生相同终局。
• 状态克隆在执行同一动作前后保持等价。
• 回放可以在每一步检测最早发生漂移的位置。

事务边界

公共 step 在私有副本上执行完整动作；合法性重验、窗口顺序、监听续算或不变量失败时， 原状态不留下半次修改。卡池与 DIY Pack 同样遵守先分阶段、后原子提交。

明确禁止的耦合

核心库内不引入文件系统、日志、网络、环境变量或隐式全局注册表；不使用 unsafe、 Rc、RefCell。依赖保持在 serde、serde_json 和 rand_chacha 的既有白名单内。