Aptos Move 最弱前置条件(WP)规范推断:move_package_wp 工具契约与诊断处理全指南
Aptos Move 最弱前置条件(WP)规范推断:move_package_wp 工具契约与诊断处理全指南
导读
本文围绕 Aptos 仓库中 aptos-move/flow 的规范推断(Specification Inference)工作流展开,深入讲解其核心工具 move_package_wp——一个基于最弱前置条件(Weakest Precondition, WP)推理、从 Move 函数实现自动派生形式化规范并写回源码的 MCP 工具。你将掌握该工具的参数与输出模式、五种典型诊断结果的准确含义与修复动作、pragma opaque 与继承式 partial 规则的边界,以及如何区分"规范缺陷"与"工具缺陷"。本文以 wp_tool.md 为骨架,结合 package_spec_infer.rs 源码实现逐条印证。
WP 推理的基本原理
在深入工具之前,先理解其数学内核。wp_concepts.md 给出的定义简洁有力:
最弱前置条件推理从返回(returns)、中止(aborts)、调用(calls)与状态更新(state updates)向后推导,刻画每种行为对应的初始状态集合;循环由其不变量表示,不变量未约束的值在循环之后被视为任意值。
这意味着 move_package_wp 不是"正向模拟执行",而是"反向求解条件":它回答的是"为了满足某个函数的所有可观察行为,调用方必须满足什么前置条件、函数会以何种方式中止、会修改哪些全局状态"。循环之所以需要不变量,是因为向后推理无法机械地穿过任意次迭代,只能依赖一个"进入时成立、每次迭代保持"的断言来抽象整段循环。
move_package_wp 工具概览与调用方式
工具定位
在 core_tools.md 描述的"Move 包检查工具族"(move_package_status、move_package_manifest、move_package_query)之外,move_package_wp 是规范推断专用工具。在 README.md 的工具清单表中,它的定位被描述为:
move_package_wp— Infer and inject specifications with weakest preconditions (hybrid tactics only)
即:仅在后端混合(hybrid)策略下可用,与 agent-only(纯 Agent 直接推理、不含 WP 工具)策略互斥。
参数与默认值
工具的契约在 package_spec_infer.rs 中由 MovePackageSpecInferParams 精确定义:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
package_path |
string |
是 | Move 包目录路径,即包含 Move.toml 的目录 |
filter |
string? |
否 | 作用域过滤:module、module::function 或 address::module::function(支持数字或命名地址;裸模块名必须无歧义)。省略时推断整个包的所有目标模块 |
spec_output |
枚举 | 否 | 输出模式,默认 inline |
filter 的三级粒度与验证工具 move_package_verify 保持一致。从源码看,filter 会被 resolve_filter 解析为 (VerifiedScope, VerificationScope)(见 package_spec_infer.rs),并且当设置了 filter 时,工具会构建一个全新环境(build_filtered_env),只把匹配 filter 的文件作为 primary target——这与 move_package_verify 的动机一致:避免缓存环境中"所有模块都是 target"导致 prover 的字节码流水线遍历整个包,从而在不打算验证的模块(例如 storage_slot)上 panic。
输出模式:inline 与 file
spec_output 枚举定义在 package_spec_infer.rs:
inline(默认):推断出的规范被注入原始源码文件。实现上,prover 先生成<stem>.enriched.move富化文件,工具读取其内容、覆盖写回原文件、再删除富化文件(见 package_spec_infer.rs)。file:为每个目标模块生成伴生的<stem>.spec.move文件,原始源码保持不动(见 package_spec_infer.rs)。
无论哪种模式,循环不变量永远留在其可执行循环旁边,不随 spec_output 移动到伴生文件。写回后,工具会调用 source_check::check_inferred_output 做格式与 AST 校验,并通过 source_check::format_file 格式化每个被修改文件,最终返回被修改文件的路径清单,以及统计到的 [inferred 标记数量(这是后文"标记纪律"的落点)。
调用示例
# 推断整个包(所有目标模块),默认 inline 注入源码
move_package_wp package_path="sources/"
# 只推断某个模块
move_package_wp package_path="sources/" filter="my_module"
# 只推断某个函数
move_package_wp package_path="sources/" filter="my_module::transfer"
# 推断到伴生 .spec.move 文件,保留原始源码
move_package_wp package_path="sources/" filter="my_module::transfer" spec_output="file"
结果解读:五种情形与对应动作
原文档的核心是"按函数解读结果"的决策树。这是使用 WP 工具最关键的部分——警告不是普通提示,每种警告都对应一种明确的工作项或工具缺陷声明。
情形一:无警告 —— 生成规范按构造正确
没有警告意味着生成的规范在构造上是完整且正确的,包括:
- 隐式算术中止(如溢出、除零);
- 边界中止(如越界索引);
- 资源中止(如访问不存在的资源);
- 被调用方(callee)的中止传播。
需要特别强调两个边界:
- WP 不运行 prover。无警告不代表证明通过——验证可能仍然超时。此时修复方向是"修理证明或改用等价的、对求解器友好的表达式",前提是不削弱契约(不能为了好证而删条件)。
- 工具 bug 的判定标准:对未修改的、无警告的 WP 输出,若出现编译错误或反例,这是工具缺陷(tool bug),应报告该失败条件,而不是去改规范。这一点在源码中亦有呼应:无过滤路径会先
clear_diag()清理历史诊断再运行推断(见 package_spec_infer.rs),确保警告来源干净。
情形二:缺失或不足的循环不变量
这是最常见也最需要动手的情形。动作是添加一个"进入时成立、且被每次迭代保持"的不变量。
关键辅助机制:警告会携带有界循环头观测值(bounded loop-head observations)。源码中对应 LOOP_INVARIANT_EVIDENCE_DEPTH 与 options.inference.loop_invariant_evidence = evidence_depth(见 package_spec_infer.rs)——prover 会展开循环前若干次迭代,报告循环头处的取值,帮助你归纳出不变量。但文档明确警告:
这些观测只是显示的那段执行前缀的描述,不是证明。
正确的迭代流程是:为该函数补齐不变量 → 删除该函数过期的、由 WP 生成的函数子句(保留不变量、helper 和用户手写的子句)→ 重跑 WP。spec_inf_rules.md 还给出了常见的循环不变量形状:累积(accumulation)、搜索(search)、量化遍历(quantified traversal)、有状态遍历(stateful traversal),以及针对内联高阶迭代器的 folds_of 提示。
情形三:部分 opaque / 无体 callee 规范 —— 唯一合法的调用方 partial
这是唯一能让调用方规范"合理地为 partial"的 callee 情形。当被调用方契约自身是 partial 的(aborts_if_is_partial),调用方将没有确切的 abort 条件可以陈述,因此:
- 保留
pragma aborts_if_is_partial(不要删除它来宣称 totality); - 在契约中注明是哪个命名 callee 引入的 partiality;
- 不要重写调用方,也不要删掉 pragma 去伪装成完备。
配套规则在 spec_inf_rules.md 中被称为"继承式 partiality(Inherited partiality)":它只计入你"发现"的 partiality(推断报告给 callee 的,或你接手时树上已有的);自己写出来的 partiality 不算——把一个 helper 标成 partial 再拿它当挡箭牌,会被候选检查(candidate check)拒绝。在 callee 保持 partial 期间,调用方必须保持 partial,且这个警告不是对调用方的修复义务,不需要反复重跑 WP。
情形四:透明 callee 缺少完整 opaque 契约
当被调用方是**透明(transparent)**的、又没有完整的 opaque 契约时,WP 无法补全调用方。分两种处理路径:
- callee 在可编辑范围内(例如当前模块内):先为 callee 推断并验证其 opaque 契约,再对调用方重跑 WP;
- callee 在可编辑范围之外:把该依赖报告为 corpus/package blocker——其所有者必须提供完整且已验证的 opaque 契约。
文档特别强调:绝不能用这种情形来为调用方的 aborts_if_is_partial 辩护。这正是"继承式 partiality"规则的反面教材。
情形五:未建模的 prover intrinsic —— 工具缺陷
pragma intrinsic 函数执行的是 prover 内建语义(builtin),而非其 Move 函数体。因此:
- 不要为其添加源码级 spec;
- 不要把它们改成 opaque;
- WP 工具必须在内部提供该 builtin 的值(value)、中止(abort)与变更(mutation)语义。
遇到此类警告应视为 WP 工具缺陷并上报。spec_inf_rules.md 同步规定:"不要为 pragma intrinsic 函数合成普通契约;prover 提供其语义"。
总则:什么算工具缺陷
文档最后给出收口定义:
条件的意外丢失、畸形输出,或任何其他推断失败,都是工具缺陷,而不是削弱规范的邀请。
也就是说:move_package_wp 的警告体系是"要么修(情形二、四),要么保留并记录(情形三),要么上报(情形一的后半、情形五)",唯一不允许的响应是通过削弱契约让问题消失。
配套工作流:从 WP 输出到候选检查
move_package_wp 不是孤立工具,它嵌在 aptos-move/flow 的完整规范推断闭环中。任务编排定义在 spec_inf_tasks.md,两种混合策略的差异在于 WP 的使用方式:
hybrid-guided(默认):按固定顺序执行——先在请求作用域上跑 WP(含循环)→ 按本文第五节的决策树逐个修复诊断、逐函数重跑 → 简化 WP 产物(保持每个 result/abort/frame 义务不变)→ 跑候选检查。README.md中的调用形式为/move-inf与/move-inf hybrid-flexible sources/x.move。hybrid-flexible:WP 作为可选推断通道,何时用、是否与直接推理和不变式合成搭配,由 Agent 自行决策。
两种策略的终点都是 candidate_check.md 描述的 move_spec_check 候选检查——它是唯一决定"工作是否完成"的裁判,会编译包、验证目标,并拒绝自我削弱的契约(禁用/跳过验证、空洞条件、无 callee 依据的 partial-abort pragma)。它同时取代了收尾时的 move_package_verify 调用:前者重复即将做的验证,后者重复已经做过的证明。
一个值得注意的实现细节:在度量(measured)场景下,uninvariant_loop_is_error 会把"无不变量的循环"从"产出可验证空契约"升级为"必须失败"(见 package_spec_infer.rs 与 EvaluationConfig::uninvariant_loop_is_error 的注释),防止循环被静默抽象成空契约。
输出纪律与工程质量红线
结合 spec_inf_rules.md 与 verification_ref.md,使用 WP 工具时必须遵守以下纪律,这些也是候选检查会强制执行的:
- 标记纪律:每个你撰写的条件与不变量标
<a href="https://link.gitcode.com/i/d575a6fe3590d42da0d639319c5ef288" target="_blank">inferred];绝不标记用户既有子句。源码正是通过统计[inferred出现次数来计量推断产出的(见 [package_spec_infer.rs)。 - opaque 契约的诚实性:对目标函数撰写的规范必须
pragma opaque,并且该契约必须被证明真的成立——"pragma opaque不会抑制函数自身函数体的验证"。契约缺结果、缺 abort、缺 frame 不只是不完整,而是错误——调用方会基于一个实现不兑现的承诺被验证。同理,不要给检查范围之外的 helper 加pragma opaque(它会在调用点被假定、却永远不会被验证,检查会拒绝它);透明 helper 不需要契约,prover 直接读其函数体。 - 不削弱原则:绝不删减行为条件、绝不添加限制性
requires来挡反例、绝不启用 partial abort 覆盖、绝不省略 frame、绝不跳过验证。 - 诊断分类先行(见 verification_ref.md):编译/规范语言错误先修语法与名字解析;后置条件反例追溯正常路径;abort 反例枚举直接与传递的 abort 来源;frame 失败对照
modifies子句;超时视为"未解决",既不是假也不是已验证。 - 超时策略:先简化 WP 生成或手写的表达式(去冗余、提取公因子、修复
vacuous/sathard循环输出),用split_vcs_by_assert与小assert提示切分义务,用等价 frame/有界关系/递归 helper 替换敌意无界量词,偏好加法递推而非非线性闭式,用apply显式实例化引理并给[weight = N],最后才考虑提高 per-condition 超时。
结论:一份可执行的诊断契约
move_package_wp 的价值在于把"规范推断"从黑盒变成了带明确责任边界的流程:WP 引擎负责按构造生成完备条件(含隐式中止与 callee 传播),人类/Agent 负责四件事——补循环不变量、为可编辑范围内的透明 callee 推断 opaque 契约、记录并保留继承的 callee partiality、以及把超时当作证明问题而非规范问题去修。剩下的一切异常(无警告输出上的反例、未建模 intrinsic、条件丢失)都属于工具缺陷,应当上报而非"修掉症状"。这套契约在 wp_tool.md 中被精确定义,并由 package_spec_infer.rs 的实现在工程上落地——理解它,就理解了 Aptos 形式化验证流水线的入口。