Aptos 规范推断语料样本剖析:以 pending_order_book_index 为目标函数的可复现推理任务(AX-pending-order-book-index-006)
Aptos 规范推断语料样本剖析:以 pending_order_book_index 为目标函数的可复现推理任务(AX-pending-order-book-index-006)
本文围绕 Aptos 开源仓库中 Move 规范推断(spec-inference)语料库的一个具体样本展开:aptos-move/flow/evaluation/spec-inference/corpus-v1.2/samples/AX-pending-order-book-index-006。该样本以实验性链上订单簿模块 pending_order_book_index 的 take_ready_price_move_up_orders 函数为推断目标,完整记录了目标来源、依赖闭包、参考规格、准备补丁与校验哈希,是理解"如何为 AI Agent 构造可复现的 Move 规格推断任务"的典型切片。读完本文,你将掌握该样本的目录结构、任务描述符(task descriptor)字段语义、参考规格的合约含义,以及如何在仓库内复现这一推断任务。
样本在语料库中的定位
整个语料库位于 aptos-move/flow/evaluation/spec-inference/corpus-v1.2/,它是一份"可人工检视的源码目录"(human-inspectable source catalog),全部样本统一取自 Aptos Core 提交 950e413e46090d2056740c36dd7a77b1764b6936。语料库的权威清单在 manifest.json(20 个样本记录及哈希,corpus_status 字段标注为 screened,表示该语料已通过筛选、可用于实验轮次)。
每个样本是一个"覆盖层配方"(overlay recipe):运行时控制器先拷贝共享包 framework/,再应用样本自身的准备补丁(preparation patch)——补丁只会删除该目标函数的参考规格并加入任务描述符,因此不存在每个样本独立一份框架快照。样本 AX-pending-order-book-index-006 即遵循这一模式,其补丁与可编辑包都存放在样本目录内。
语料库共享包 framework/ 包含 154 个模块、257 个 Move 源文件/规格文件,是所有目标及其源码级传递依赖的并集;模块到文件的精确映射与命名地址解析记录在 corpus-modules.json 中。这也意味着:本样本的 target 之外的模块只是"编译上下文"(compilation context),并非额外的推断目标。
目标与元数据
样本 README 给出了推断任务的完整元数据:
| 字段 | 值 |
|---|---|
| Target | 0x7::pending_order_book_index::take_ready_price_move_up_orders |
| Granularity | function(函数级推断) |
| 原始源码 | aptos-move/framework/aptos-experimental/sources/trading/order_book/pending_order_book_index.move |
| 共享包内路径 | sources/AptosExperimental/trading/order_book/pending_order_book_index.move |
| 源码根 | aptos-move/framework/aptos-experimental |
| Aptos Core 提交 | 950e413e46090d2056740c36dd7a77b1764b6936 |
| 共享包 SHA-256 | 1c41a4a754554758e1632217bb867a0dc8c622072f937edf1e1ef44adaf1f116 |
| 准备后树 SHA-256 | 8a7f98958f4815cec43dfa09a6648869f089bb4752482d2d09d52f1682ba21dc |
| 必需合约类别 | normal-result、state-transition、loop-invariant |
其中"必需合约类别"直接决定了 Agent 输出的规格应覆盖哪些性质:
normal-result:正常返回时的行为合约(ensures);state-transition:可变状态(此处为price_move_up_index索引与orders向量)在调用前后的变迁关系;loop-invariant:目标函数内含 while 循环,需要给出循环不变量支撑证明。
由于目标函数被要求给出 loop-invariant,参考规格中对应的循环内联 spec 块是推断的重要线索(见下文"参考规格"一节)。
编译上下文:依赖闭包与不透明边界
函数级推断必须在完整可编译的源码环境下进行。README 将编译上下文划分为三层:
1. Opaque/bodyless 边界(合约可见的不透明函数)——证明目标时其合约对外可见、但函数体不可见:
0x1::big_ordered_map::borrow_front0x1::big_ordered_map::compute_length0x1::big_ordered_map::is_empty0x1::big_ordered_map::remove0x1::vector::length0x1::vector::push_back
该闭包遍历可执行 callee 与可达合约中被引用的行为谓词(behavioral predicates)得出;本样本的传递规格函数(transitive specification functions)为 None。
2. 传递源码模块——编译样本所必需的完整模块集合,覆盖三个地址域:
0x1(框架与标准库):account、aptos_coin、big_ordered_map、ordered_map、table、table_with_length、vector、object、fungible_asset、timestamp等 100+ 模块;0x5(AptosTrading):bulk_order_types、order_book_types、order_match_types、single_order_types;0x7(aptos_experimental):bulk_order_book、order_book、price_time_index、single_order_book、order_placement、dead_mans_switch_operations等交易相关模块。
这些地址映射对应共享包的 Move.toml:aptos_experimental = "0x7"、aptos_framework = "0x1"、aptos_std = "0x1"、aptos_trading = "0x5"、std = "0x1"。命名地址的解析结果与模块/文件映射一同记录在 corpus-modules.json。
3. 任务描述符中的细化依赖——preparation.patch 新增的 .move-inference-task.json 进一步细分了依赖层次:
called_function_dependencies:目标直接调用的 6 个函数(与 README 的不透明边界一致);transitive_called_function_dependencies:全部传递调用(如big_ordered_map::internal_new_begin_iter、ordered_map::binary_search、table::borrow_box_mut、vector::move_range等);transitive_function_dependencies与transitive_module_dependencies:用于验证 Agent 推理环境的完整性与可复现性。
准备(Preparation):如何从"参考实现"变成"推断任务"
准备流程的核心是去掉答案、保留题目。README 明确了两处被移除的参考块:
sources/AptosExperimental/trading/order_book/pending_order_book_index.spec.move:take_ready_price_move_up_orders的函数级 spec 块(1 块);sources/AptosExperimental/trading/order_book/pending_order_book_index.move:目标函数内的内联 spec 块(1 块)。
preparation.patch 中可以看到这两处修改的精确 diff:
- } spec {
- invariant len(orders) >= taken_from;
- invariant len(orders) <= taken_from || len(orders) <= limit;
- invariant forall i in 0..taken_from: orders[i] == orders_before[i];
- invariant big_ordered_map::spec_len(self.price_move_up_index) <= index_before;
- };
+ }
- spec take_ready_price_move_up_orders(
- self: &mut PendingOrderBookIndex,
- current_price: u64,
- orders: &mut vector<OrderId>,
- limit: u64
- ) {
- pragma opaque;
- aborts_if false;
- ensures len(orders) >= old(len(orders));
- ensures len(orders) <= old(len(orders)) || len(orders) <= limit;
- ensures forall i in 0..old(len(orders)): orders[i] == old(orders)[i];
- ensures big_ordered_map::spec_len(self.price_move_up_index)
- <= old(big_ordered_map::spec_len(self.price_move_up_index));
- }
同时补丁新增了任务描述符 .move-inference-task.json(schema_version: 3),记录 task_id、granularity、package_module_target、source_commit、target_functions 等字段,供控制器校验环境。
补丁还体现了三条关键约束:
- 可执行实现不变:补丁只删除规格块,不修改任何 Move 可执行代码,确保"实现即真值";
- Agent 只能编辑一个文件:
sources/AptosExperimental/trading/order_book/pending_order_book_index.move,防止 Agent 通过改动其他模块来规避推理; - 哈希可校验:控制器在应用补丁后会验证
prepared tree SHA-256(8a7f...2dc),确保所有实验臂拿到的是同一份源码(语料库 README 声明"每个实验臂对同一样本获得相同源码哈希,treatment 专属的技能与工具另行存放")。
目标函数源码与参考规格解析
要推断规格,必须先理解目标函数的行为。共享包中的可编辑源码(即补丁应用后的版本,位于 sources/AptosExperimental/trading/order_book/pending_order_book_index.move)保留全部可执行逻辑,只有循环末尾的 spec 块被清空:
fun take_ready_price_move_up_orders(
self: &mut PendingOrderBookIndex,
current_price: u64,
orders: &mut vector<OrderId>,
limit: u64
) {
let taken_from = orders.length();
let orders_before = *orders;
let index_before = self.price_move_up_index.compute_length();
while (!self.price_move_up_index.is_empty() && orders.length() < limit) {
let (key, order_id) = self.price_move_up_index.borrow_front();
if (current_price >= key.price) {
orders.push_back(*order_id);
self.price_move_up_index.remove(&key);
} else {
break;
}
}
}
结合模块其余部分(原始框架版本)可以完整还原上下文:
PendingOrderBookIndex::V1持有三张BigOrderedMap索引:price_move_down_index、price_move_up_index、time_based_index,分别应对预言机价格下跌、上涨与时间条件触发的挂单(pending order);- 该函数按价格升序(
borrow_front)扫描price_move_up_index,把"当前价格 ≥ 触发价"(current_price >= key.price)的订单移入orders,直至索引为空或达到limit;遇到第一个未满足条件的 key 立即break(价格已排序,后续必然更不满足); - 该函数被
take_ready_price_based_orders调用两次(先取上限一半,再补满剩余额度),是价格类条件单撮合的核心取单逻辑; - 模块顶部声明
friend aptos_experimental::single_order_book,表明该索引仅对single_order_book模块开放。
参考规格位于共享包的 pending_order_book_index.spec.move,其语义正好对应 README 要求的三个合约类别:
spec take_ready_price_move_up_orders(
self: &mut PendingOrderBookIndex,
current_price: u64,
orders: &mut vector<OrderId>,
limit: u64
) {
pragma opaque; // 对调用方隐藏实现,仅暴露下列合约
aborts_if false; // normal-result:永不中止
ensures len(orders) >= old(len(orders)); // state-transition:orders 只增不减
ensures len(orders) <= old(len(orders)) || len(orders) <= limit; // 容量上限
ensures forall i in 0..old(len(orders)): orders[i] == old(orders)[i]; // 前缀保持
ensures big_ordered_map::spec_len(self.price_move_up_index)
<= old(big_ordered_map::spec_len(self.price_move_up_index)); // 索引只缩不增
}
而循环内联 spec(从补丁 diff 中恢复)则是 loop-invariant 类别的标准答案:
invariant len(orders) >= taken_from;
invariant len(orders) <= taken_from || len(orders) <= limit;
invariant forall i in 0..taken_from: orders[i] == orders_before[i];
invariant big_ordered_map::spec_len(self.price_move_up_index) <= index_before;
四条不变量分别锚定:已取订单数不回退、容量上界、orders 前缀稳定性(taken_from 之前的元素与循环开始前的快照 orders_before 一致)、索引长度单调不增。它们与函数级 ensures 一一呼应,正是"用不变量证明 ensures"的经典证明骨架。
复现与运行方式
若要在本地复现该样本的规格推断或验证:
- 查看任务描述:阅读 样本 README 与 preparation.patch,确认依赖闭包与任务描述符;
- 重建共享包:以 framework/ 为 Move 包根目录(
InferenceCorpusFramework,命名地址见 Move.toml); - 应用补丁:将
preparation.patch应用到共享包,得到 Agent 可见的工作区(可编辑文件仅为sources/AptosExperimental/trading/order_book/pending_order_book_index.move),并核验准备后树哈希; - 证明环境:共享包提供 Prover.toml,其中
borrow_natives = ["storage_slot::borrow_storage_slot_resource_mut"]声明了需要特殊借用的 native 函数,供 Move Prover 使用; - 对照语料元数据:样本清单与每个样本的哈希、必需合约类别可交叉核对 manifest.json(20 条记录,每条含
preparation_patch_sha256、prepared_sha256、shared_package_sha256、required_contract_categories与removed_reference_blocks)。
与 MoveFlow 推断工作流的关系
该语料库位于 aptos-move/flow/(MoveFlow:面向 Aptos 的 AI 辅助 Move 开发套件,提供插件生成器、MCP 服务器与编辑钩子)之下,是其规格推断评估体系的一部分。MoveFlow 的 /move-inf 命令支持 hybrid-guided(默认,WP 诊断驱动不变量工作)、hybrid-flexible、agent-only 三种推断战术(详见 aptos-move/flow/README.md),而本样本这类"去掉参考规格、仅留实现、限定可编辑路径、哈希校验"的任务形态,正是为了让不同战术的 Agent 在完全一致的源码输入上接受评估——语料库 README 中"treatment-specific skills and tools are stored separately"(实验臂专属的技能与工具分开存放)也印证了这一点。
从本样本可以提炼出构造规范推断基准的三条工程经验:
- 答案与题目分离:参考规格(
.spec.move与内联 spec)必须与可执行实现解耦,补丁只删答案不动实现,保证"正确规格"始终存在于提交历史中可供评分; - 环境封顶:通过不透明边界列表、传递依赖闭包和单文件可编辑约束,精确划定 Agent 的推理半径,防止通过改写依赖模块"作弊";
- 全程可复现:共享包哈希、准备后树哈希、任务描述符
schema_version与source_commit四者结合,使每次评估都能回溯到完全相同的源码快照。