快照与回放

状态指纹

state_fingerprint 与 catalog_fingerprint 对稳定序列化内容计算指纹。它们用于检测：

• 动作列表生成后状态是否已变化；
• 快照是否被编辑或截断；
• 恢复时卡池顺序或内容是否不同；
• 回放在哪一步首次偏离。

指纹是完整性和确定性门槛，不代替版本字段。

快照

encode_snapshot 生成 SnapshotEnvelope，其中同时记录：

• snapshot schema；
• crate 引擎版本；
• 规则契约版本；
• runtime protocol；
• 卡池指纹；
• 状态指纹；
• 完整 GameState。

decode_snapshot 依次验证所有版本、卡池指纹、状态指纹和运行时不变量，任何不匹配都返回 具体 SnapshotError。信封使用 deny_unknown_fields，避免调用方误以为未识别字段已生效。

快照只保存持久对局状态。一次 step 内部的私有伤害窗口、游标与终局 latch 不进入 GameState，也不会泄露到观察协议。

回放

MatchTrace 包含初始状态、初始状态指纹、卡池指纹、协议版本以及一组 StepRecord。 每个步骤记录：

• actor；
• 完整 Action；
• 执行前状态指纹；
• 执行后状态指纹。

replay_match 从初始状态开始逐步调用同一公共 step，每一步前后都校验指纹并运行状态 不变量。错误会指出具体步骤和类别，而不是只在最终状态报告“不相同”。

何时使用

需求	选择
暂停后继续一局	快照
复现一次问题	回放
验证两次运行逐步一致	回放
比较当前状态是否变化	状态指纹
防止不同卡池错误恢复	快照或回放中的卡池指纹

快照与回放都要求完全相同的兼容版本和卡池；当前没有隐式迁移或“尽量恢复”模式。