- CHANGELOG.md:v2.8.0 条目(中英双语); - README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明); - doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制); - skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/ require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过); - 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
926 lines
56 KiB
Markdown
Executable File
926 lines
56 KiB
Markdown
Executable File
# `marqdo prove`:SKILL 编排的 Lean 编译与顾问式证明
|
||
|
||
| | |
|
||
|---|---|
|
||
| 状态 | **已实施(Implemented · 2.8.0)**:P0–P3 落地记录见 §12;遗留项(foreach、跨模块 assume-guarantee、假设表 T3)显式延期至 2.9,理由见 §12.4。路线图:[roadmap/prove.md](../roadmap/prove.md) |
|
||
| 日期 | 2026-11-13 |
|
||
| 层归属 | **Language**:定理表角色 + `check --proof`(§7,[ADR 0010](../adr/0010-skill-proof-boundary.md))· **Runtime**:`prove` 管线(§4–§6、§8)· **Document**:`verification/skill-proof` 证据 |
|
||
| 相关 | [core-surface.md](core-surface.md)(复用 `table` 构造,不新增标记)· [layers.md](layers.md)(准入)· [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) · [ADR 0010](../adr/0010-skill-proof-boundary.md) · [verification/replay-policy](../../verification/replay-policy/README.md)(Lean 伴随判定的先例) |
|
||
| 目标版本 | CLI **2.8.0**(wasm / ext 不随动:`prove` 不进 wasm) |
|
||
|
||
---
|
||
|
||
## 0. 一句话与三条契约
|
||
|
||
`prove` 把一份 `.mq.md` 的**控制平面**(参数 → 分支 → 外部操作 → 返回值)降级成 Lean 4 定义,把作者声明的**定理**变成 Lean 定理,并尽最大努力自动关闭它们;同时输出一份可供人复核的证据(证书、假设、被拒清单)。它**不**是发布门禁,也**不**声称"过了 Lean 就绝对正确"。
|
||
|
||
三条契约,按优先级排列:
|
||
|
||
1. **诚实**:`proved` 只表示"Lean 内核接受了这条形式化陈述"。它不表示陈述写对了意图、不表示外部 API 会守约、更不表示整份 SKILL 安全。反过来,`unproved` 只表示"这次没有关闭它"——可能是定理不成立,也可能只是策略不够。
|
||
2. **单调**:离线判定(没有 Lean 时)**只能**给出 Lean 也能给出的结论。若两者分歧,以 Lean 为准并报内部错误,绝不放绿。`checked` 永远弱于 `proved`。
|
||
3. **不执行**:`prove` 从头到尾不运行被证程序,不产生任何效应;它只读源码、写缓存与 `--emit` 目录。
|
||
|
||
> 一句话给论文:*给编排文档配一张可复核的证明收据*,而不是给整个语言发一张正确性证书。
|
||
|
||
---
|
||
|
||
## 1. 定位:降低审核量,不取代审核
|
||
|
||
### 1.1 为什么是顾问而不是门禁
|
||
|
||
Agent 改写 SKILL 后,人要看的是"这一步会不会绕开审核""失败分支会不会吞掉错误"。这些恰好是控制平面命题,Lean 能帮我们把"逐行读代码"压缩成"读几条定理 + 看一眼反例"。但:
|
||
|
||
- 真实 SKILL 里有字符串、JSON、外部服务;把这些都形式化,成本远高于收益;
|
||
- 形式化陈述与业务意图之间永远隔着"作者写得对不对";
|
||
- 大多数团队没有 Lean,强制门禁只会让人绕过工具。
|
||
|
||
所以 `prove` 的默认行为是**报告**,不是**拦截**。规范与手册**推荐**在发布 SKILL 前跑一次,但不强求;要不要把某个状态当失败,由调用方用 `--require-lean` / `--report-only` 自己决定。
|
||
|
||
### 1.2 三种"绿"和两种"红"
|
||
|
||
| 状态 | 含义 | 由谁产生 | 能不能当"已证明" |
|
||
|---|---|---|---|
|
||
| `proved` | 全部定理被 Lean 内核接受 | Lean | **能**(且仅限陈述本身) |
|
||
| `checked` | 全部定理在离线片段(§5)内判定为真,已生成对应 Lean 脚本但未运行 | 离线判定 | **不能**,只能说"离线判定通过" |
|
||
| `unverified` | 有定理超出离线片段,且没有跑 Lean | 离线判定 | 不能 |
|
||
| `unproved` | 至少一条定理未被关闭;若能给出反例则附见证 | Lean / 离线 | 不能;这是红灯 |
|
||
| `rejected` | 有函数不在可证子集(`while`/递归/动态派发),已跳过 | 降级器 | 不能;这是"未覆盖",不是"错误" |
|
||
|
||
`rejected` 与 `unproved` 的区别很重要:前者是**工具够不着**,后者是**命题没过**。把它们混成一个红,会让"文件里有个循环"看起来像"业务逻辑错了"。
|
||
|
||
此外还有 `error`(编码/类型/效应/IO/超时):它不是判定结果,而是**工具或程序本身出错**,退出 1。五种判定(proved/checked/unverified/unproved/rejected)与 `error` 在 JSON 里共用 `status` 字段,但语义分组不同,报告会分开统计。
|
||
|
||
### 1.3 诚实性词汇表(写进 README 与 `--json`)
|
||
|
||
- `proved` ≠ 正确:它只对**写下来的陈述**负责,且假设 `Env` 的返回值任意、`假设` 表成立。
|
||
- `unproved` ≠ 错误:策略失败、超时、片段外都可能;只有带 `counterexample` 字段时才是"确实不成立"。
|
||
- `rejected` ≠ 不安全:只表示这部分没被形式化覆盖。
|
||
- 证书不替代代码评审:它是**缩小**评审范围的工具,`audit` 会明确列出"哪些外部操作完全未知"。
|
||
|
||
### 1.4 非目标
|
||
|
||
- 不形式化解释器、字符串库、JSON、浮点、`formula`。
|
||
- 不证明外部服务与网络;这些由 `假设` 表显式承担。
|
||
- 不在 Agent 每次运行时跑 Lean;运行期只读证书。
|
||
- 不自动安装 Lean;只探测并给出可执行提示。
|
||
- 不追求"零人工":目标是让人从"读 200 行"变成"读 5 条定理 + 1 张假设表"。
|
||
|
||
---
|
||
|
||
## 2. 证明范围
|
||
|
||
### 2.1 义务分级
|
||
|
||
| 级别 | 义务 | 作者要写什么 | 谁保证 | 离线可做 |
|
||
|---|---|---|---|---|
|
||
| **T0 类型** | 生成的 Lean 通过内核;字段、元数、分支同型 | 无 | Lean | 部分(Rust 类型检查) |
|
||
| **T1 结构** | 终止(无 `while`/递归 ⇒ 结构递归)、分支出口完整、返回类型符合 `返回` 契约、效应不越权(给了 `--effects` 时) | 无 | 降级器 + Lean | 是 |
|
||
| **T2 声明** | 定理表里的业务命题 | 定理表 | Lean / 离线片段 | 是(F1–F5) |
|
||
| **T3 契约** | 外部操作前置/后置假设下的组合推理 | `假设` 表 | Lean | 部分 |
|
||
| **T4 一致性** | 生成语义与解释器在纯片段上同值 | 测试语料 | 差分测试 | 是 |
|
||
|
||
### 2.2 三条硬边界(拒绝,不降级)
|
||
|
||
| 构造 | 处理 | 诊断码 |
|
||
|---|---|---|
|
||
| `while`(`-` + 条件行) | 跳过该函数 | `proof.while` |
|
||
| 直接/间接递归(调用图有环) | 跳过该环 | `proof.recursion` |
|
||
| 动态派发(插件调用、变量函数名、`code` 值调用) | 跳过该调用点 | `proof.dynamic_call` |
|
||
|
||
被跳过的函数不参与定理,其余函数照常出证。整体状态按固定优先级合成(差者胜):`error` > `unproved` > `rejected` > `unverified` > `checked` > `proved`。`--allow-opaque <FN>` 可把某个被跳过的函数**整体**降级为不透明操作,让调用它的编排仍可证——此时它的行为完全未知,`audit` 必须列出来。
|
||
|
||
---
|
||
|
||
## 3. 命令面
|
||
|
||
### 3.1 命令与别名
|
||
|
||
```bash
|
||
marqdo prove [PATH] # 降级 → 生成 → 离线判定 →(有 Lean 时)Lean 判定
|
||
marqdo prove emit [PATH] -o DIR # 只生成 Lean,不判定(离线/论文/AI 取用)
|
||
marqdo prove audit [PATH] # 只报降级结论:内联了什么、不透明了什么、拒了什么、假设了什么
|
||
marqdo prove clean # 清 .marqdo/prove 缓存
|
||
```
|
||
|
||
`prove` 带 `visible_alias = "lean"`;文档与 CI 统一写 `prove`。它与既有 `verify` 不重叠:`verify` 查知识一致性,`prove` 查控制平面命题。
|
||
|
||
### 3.2 参数
|
||
|
||
| 参数 | 默认 | 含义 |
|
||
|---|---|---|
|
||
| `PATH` | `index.mq.md` | 单个 `.mq.md`;目录需 `--all` |
|
||
| `--all` | off | 目录递归(跳过 `target`/`dist`/`node_modules`/`.git`/`.marqdo`);`--max-files <N>` 默认 200 |
|
||
| `--entry <FN>` | `main` | 入口与报告分组;不限制文件内全量证明 |
|
||
| `--only <FN>` | — | 只证这些函数(可重复),用于增量 |
|
||
| `--emit <DIR>` | `.marqdo/prove/<key>/Generated` | 保留生成的 Lean |
|
||
| `--json` | off | stdout 一个 JSON 对象(§3.5);诊断走 stderr |
|
||
| `--lean <PATH>` / `--lake <PATH>` | 探测 | 显式工具链 |
|
||
| `--library <DIR>` | 探测 | `MarqdoProof` 库目录 |
|
||
| `--timeout <SEC>` | 120 | 单次 Lean 调用上限 |
|
||
| `--heartbeats <N>` | 400000 | `maxHeartbeats` |
|
||
| `--no-cache` | off | 绕过证书与 olean 缓存 |
|
||
| `--no-offline` | off | 跳过离线判定,只用 Lean(CI 复现/调试用) |
|
||
| `--require-lean` | off | 严格模式:`checked`/`unverified`/`rejected` 一律返回 2 |
|
||
| `--report-only` | off | 除工具错误外恒返回 0 |
|
||
| `--allow-opaque <FN>` | — | 把被跳过的函数降级为不透明操作 |
|
||
| `--effects <LIST>` | — | 与 `marqdo call --effects` 同格式;给出时检查实际调用是否越权 |
|
||
| `--strict-types` | on | 类型无法推断即报错;`--no-strict-types` 落 `Val`(证明力下降,报告标注) |
|
||
| `--tactic <T>` | `auto` | 定理表未写 `策略` 时的默认策略 |
|
||
|
||
### 3.3 状态与退出码
|
||
|
||
| 状态 | 退出码 | `--require-lean` | `--report-only` |
|
||
|---|---|---|---|
|
||
| `proved` | 0 | 0 | 0 |
|
||
| `checked` | 0 | **2** | 0 |
|
||
| `unverified` | 0 | **2** | 0 |
|
||
| `rejected` | 0 | **2** | 0 |
|
||
| `unproved` | 1 | 1 | 0 |
|
||
| `error` / `timeout` | 1 | 1 | 1 |
|
||
|
||
设计理由:
|
||
|
||
- 缺工具链、有循环、定理在片段外,都**不是**程序的错,默认不返回非零——否则没装 Lean 的机器上 `prove` 等于不可用。
|
||
- 默认情况下只有两种非零来源:**你写下的定理未被关闭**(1),或**工具出错**(1)。不写定理就不会有第一类失败。
|
||
- 想要严格覆盖的团队用 `--require-lean`,把"未判定"升级成 2;CI 里加这一个参数即可。
|
||
- 全局开关 `--report-only` 让 Agent 在探索期只看报告。
|
||
|
||
### 3.4 文本输出
|
||
|
||
```text
|
||
$ marqdo prove skills/marqdo-release/index.mq.md
|
||
审批 2/2 定理 proved Lean 0.8s
|
||
plan 1/1 定理 checked 离线判定 12ms(附 Lean 脚本,未运行)
|
||
预检 — rejected 离线 3ms proof.while L88
|
||
prove: proved 1 · checked 1 · rejected 1
|
||
说明: checked 不代表 Lean 已验证;安装 Lean 或传 --lean 可交由 Lean 判定。
|
||
提示: `marqdo prove audit …` 查看降级细节与假设清单。
|
||
```
|
||
|
||
失败时:
|
||
|
||
```text
|
||
error[proof.claim_failed]: 定理「不该自动放行」未被关闭
|
||
--> examples/approval.mq.md:31:3
|
||
= 目标: (run env p).1.ok = false
|
||
= 上下文: h : p.amount > 10000
|
||
= 反例: 金额 = 10001 时走「人工审核」分支,结果 ok = true
|
||
= 说明: 可能是命题不成立,也可能是策略不够;补 `策略` 或改判据后重跑。
|
||
```
|
||
|
||
### 3.5 JSON(面向智能体的稳定契约)
|
||
|
||
一个对象,`schema` 版本化;永不交互、stdout 只有结果、诊断在 stderr、路径为相对工作目录:
|
||
|
||
```json
|
||
{
|
||
"schema": 1,
|
||
"status": "checked",
|
||
"file": "skills/example/index.mq.md",
|
||
"source_sha256": "…",
|
||
"artifact_id": "mq://…",
|
||
"functions": [{
|
||
"name": "审批",
|
||
"status": "checked",
|
||
"tier": "offline",
|
||
"claims": [
|
||
{"id": "大额必经人工", "status": "checked", "decided_by": "trace", "ms": 3},
|
||
{"id": "退款必须留痕", "status": "unverified", "reason": "out_of_fragment"}
|
||
],
|
||
"obligations": [{"id": "terminates", "status": "passed"},
|
||
{"id": "effects_subset", "status": "skipped", "reason": "no --effects"}]
|
||
}],
|
||
"lean": null,
|
||
"assumptions": [],
|
||
"diagnostics": [],
|
||
"emitted": [".marqdo/prove/ab12…/Generated/Approval.lean"],
|
||
"duration_ms": 15
|
||
}
|
||
```
|
||
|
||
`lean` 为 `null` 表示没跑;跑了则是 `{"toolchain": "...", "library_sha256": "...", "module_sha256": "...", "cache": "hit|miss"}`。`tier` ∈ `{lean, offline, none}`,标明该函数的结论来自哪一层。`status` 的取值集合固定(§1.2),Agent 可按它分支,不需要解析自然语言。
|
||
|
||
### 3.6 面向智能体的使用契约
|
||
|
||
`prove` 的主要调用者不是人,是 Agent 的循环。因此:
|
||
|
||
- **一次调用一个结论**:不做交互式提问,不读 TTY,不依赖环境变量之外的隐藏状态。
|
||
- **只解析 JSON**:`--json` 的键与状态词是稳定契约(`schema` 升级才变);stdout 不混入程序输出或进度条。
|
||
- **失败即数据**:每条诊断都有 `code` / `file` / `line` / `column` / `message`,能定位的还带 `goal`、`context`、`counterexample`、`hint`。Agent 不需要从自然语言里猜。
|
||
- **可增量**:`--only <FN>` 只证受影响函数;证书命中让第二轮降到毫秒级。
|
||
- **先审计再证明**:Agent 应先 `prove audit --json` 看"有多少内联、多少不透明、多少被跳过",再决定是否值得为该文件写定理。
|
||
- **推荐循环**:写 SKILL → `check` → `prove --json` → 读 `claims[].status` → 改代码/定理/策略 → 重跑 → 把证书附进交付说明。
|
||
|
||
### 3.7 选择规则
|
||
|
||
- **文件**:显式路径;目录必须 `--all`(否则 `proof.need_all`)。
|
||
- **函数**:文件内全部 `##` 函数默认参与;`# main` 只作分组。
|
||
- **导入**:默认内联可判定的纯函数(§4.5),其余成为不透明操作;不递归证明被导入文件。
|
||
- **`--all` 聚合**:逐文件出状态,整体取最差;`--json` 输出 `files: [...]`。
|
||
|
||
---
|
||
|
||
## 4. 管线
|
||
|
||
### 4.1 六段
|
||
|
||
```text
|
||
.mq.md
|
||
① 装载 load_module(只读,不执行)
|
||
② 降级 AST → Plan IR:子集验收、拒绝码、span
|
||
③ 定型 contract::Ty 驱动;未定 ⇒ 报错或 Val
|
||
④ 生成 IR → Lean(确定性:稳定排序、无时间戳、相对路径)
|
||
⑤ 离线判定 符号执行 + 片段判定(§5),产出 checked / 反例 / unverified
|
||
⑥ Lean 判定 有工具链时运行;以它为准,与 ⑤ 分歧即 error
|
||
```
|
||
|
||
⑤ 永远在 ⑥ 之前:离线先给快速反馈,Lean 随后确认。`--no-offline` 可只跑 ⑥。
|
||
|
||
### 4.2 Plan IR
|
||
|
||
`src/prove/ir.rs`,`serde` 序列化为 `plan.json`(版本化,缓存键的一部分,论文工具可直接消费):
|
||
|
||
```jsonc
|
||
{
|
||
"schema": 1,
|
||
"module": "skills/example/index.mq.md",
|
||
"source_sha256": "…",
|
||
"functions": [{
|
||
"name": "审批",
|
||
"params": [{"name": "金额", "ty": {"kind": "int"}}],
|
||
"result_ty": {"kind": "map", "fields": [["ok","bool"],["value","any"],["error","any"]]},
|
||
"ops": [{"id": "人工审核", "effect": "network.read", "params": [["金额","int"]]}],
|
||
"steps": [
|
||
{"kind": "if", "cond": {"op": "gt", "args": [{"var": "金额"}, {"int": 10000}]},
|
||
"then": [{"kind": "bind", "var": "审核", "expr": {"call": "人工审核", "args": [{"var": "金额"}]}},
|
||
{"kind": "return", "expr": {"ctor": "result.ok", "args": [{"var": "审核"}]}}],
|
||
"else": [{"kind": "return", "expr": {"ctor": "result.ok", "args": [{"text": "auto"}]}}],
|
||
"span": {"line": 21, "col": 1}}],
|
||
"claims": [{"id": "大额必经人工", "premise": null, "conclusion": "…", "tactic": null}],
|
||
"effects": ["network.read"],
|
||
"assumptions": []
|
||
}]
|
||
}
|
||
```
|
||
|
||
表达式分两层:`PureExpr`(字面量、变量、算术/比较/布尔、字符串拼接与插值、列表/映射字面量、`access`、`len`、类型转换)可翻译成 Lean 项;其余一律 `Call`(不透明操作),或按 §4.3 拒绝。**没有"猜"的回退。**
|
||
|
||
### 4.3 接受 / 拒绝矩阵
|
||
|
||
| Marqdo | 处理 | 备注 |
|
||
|---|---|---|
|
||
| `**x = 纯表达式**` | `bind` | 类型由右值推断 |
|
||
| `**x = [标签](调用)**` | `bind` + `Op` + `trace` | 效应来自 sema |
|
||
| `**x**`(粗体无赋值) | `return` | 纯表达式或已内联构造器 |
|
||
| `*语句*` / `> 调用` | 语句形式,值丢弃 | 丢弃的调用仍进 trace |
|
||
| `1. 条件 / 2. *` | `if/else` | 条件必须是纯布尔表达式 |
|
||
| `- [项](遍历 列表 为 项)` | `foreach`(P3) | 只接受有限列表;此前 `proof.foreach_pending` |
|
||
| `-` + 条件 | **跳过** `proof.while` | |
|
||
| 递归 | **跳过** `proof.recursion` | 调用图环检测 |
|
||
| 方法调用 `` `recv`.方法 `` | 不透明操作 | 接收者不展开 |
|
||
| `code` 值 / 插件调用 | **跳过** `proof.dynamic_call` | 不在纯片段 |
|
||
| GFM 表绑定 | `list`/`map` 字面量 | 列长不一致已在解析期拒绝 |
|
||
| `$$` 公式 | 不透明值(`Formula`) | 不翻译 TeX,不做推理 |
|
||
|
||
### 4.4 类型推断
|
||
|
||
起点:`参数` 表 + `返回` 表(`contract::Ty`)。合一规则:
|
||
|
||
- 字面量给最具体类型;`+ - * /` 要求两侧 `int`;`and/or/not` 要求 `bool`。
|
||
- 分支合流:两臂同名变量类型必须相容,否则 `proof.type_mismatch`(带两处行号)。
|
||
- 映射字段:返回表达式是映射字面量时得到 `structure`;是内联的 `result.ok/error`(lib/result 真实 API)时沿用 Result 形状;否则落 `Val`,此时 `结果.ok` 报 `proof.result_untyped`(提示:返回映射字面量或包成 Result)。
|
||
- `--no-strict-types` 时未知类型落 `Val`;定理里只能做等式/成员判断,报告标注"弱类型"。
|
||
|
||
### 4.5 内联与不透明化
|
||
|
||
1. 建调用图(本文件 + 导入文件);有环即跳过该环。
|
||
2. **内联**:被调函数(含 `lib/result` 一类纯库)满足 ①契约 `Effects: pure` ②语句数 ≤ 24 ③不含被跳过构造 ④非递归 → 展开函数体。这样 `result.ok(...)` 在 Lean 里就是 Val 映射构造(`mqResultOk`),`结果.ok` 变成可判定字段。
|
||
3. **不透明化**:其余调用生成 `Op` 构造器 + 效应,由 `Env` 参数处理;`--allow-opaque` 可强制。
|
||
4. `audit` 逐条列出:内联 / 不透明 / 跳过,以及每个不透明操作的效应与参数类型。
|
||
|
||
---
|
||
|
||
## 5. 离线判定(没有 Lean 也能给结论)
|
||
|
||
### 5.1 为什么需要
|
||
|
||
- 大多数开发机与 CI 没有 Lean;没有离线路径,`prove` 就只是"生成器"。
|
||
- Agent 迭代需要毫秒级反馈,Lean 一次数百毫秒到数十秒。
|
||
- 反例("金额 = 10001 时轨迹里没有人工审核")比 tactic 失败更有用。
|
||
|
||
但离线**绝不能**比 Lean 强。做法不是"相信我们的判定器",而是把它关进一个**极小的片段**,并让每条离线结论都附带 Lean 脚本。
|
||
|
||
### 5.2 片段 F1–F5(保守,超出即 `unverified`)
|
||
|
||
| 片段 | 能判定什么 | 为什么安全 |
|
||
|---|---|---|
|
||
| **F1 路径枚举** | 控制流是有限树(无循环/递归)⇒ 返回路径有限 | 由 §2.2 的拒绝保证 |
|
||
| **F2 轨迹** | 每条路径的 `Op` 序列由分支决定;`包含/长度/下标` 逐路径求值 | 轨迹是语法产物,不依赖 `env` 返回值 |
|
||
| **F3 字面结果** | 返回表达式只由字面量、参数、内联构造器组成时按结构求值 | 与 Lean 的 `mqResultOk` 形状一一对应 |
|
||
| **F4 命题** | `and/or/not`、`=/≠` 作用于 F2/F3 的布尔结果;外部返回值上的**布尔判定**(如 `access(回执,"ok") == False`)视为自由原子,可分叉 | 自由原子只做二分、不假设原子间关系;两条分支都关闭才 `checked`,因此证明是对任意 `env` 成立的 |
|
||
| **F5 单变量区间** | 原子 `x ⋈ c`(`c` 为整数字面量,`⋈ ∈ {<,≤,>,≥,=,≠}`);用路径条件 + 前提的上下界判定蕴含 | 单变量区间推理是线性整数算术的子集,`omega` 必然也能证 |
|
||
|
||
明确**不**离线判定(直接 `unverified`,不猜):多变量线性组合、非线性算术、字符串比较、外部返回值的非布尔字段(`.value` 之类)、任何需要归纳的命题。
|
||
|
||
### 5.3 判定过程
|
||
|
||
1. 符号执行函数体:状态 `Var → SymVal`(`Const` / `Param` / `OpResult` / `Unknown`),路径条件为原子列表,轨迹为 `Op` 列表。
|
||
2. 每个 `if` 分叉两支(条件 / 其否定);每个 `Op` 调用产生一个 `OpResult` 符号(值未知,但**出现**已知)。
|
||
3. 每个 `return` 收集 `(路径条件, 结果 SymVal, 轨迹)`。
|
||
4. 对每条路径检查 `前提 ∧ 路径条件 ⊢ 结论`:把 `结果/轨迹` 代入后按 F2–F5 求值或判定。
|
||
5. 全部路径关闭 ⇒ 该定理 `checked`;任一原子超出片段 ⇒ `unverified`;某条路径可满足且结论为假 ⇒ `unproved` + 反例。
|
||
|
||
### 5.4 证书与"单调性"
|
||
|
||
每条 `checked` 定理同时产出:
|
||
|
||
- **情形证书**:`(路径 id, 路径条件, 规范化目标, 关闭理由 ∈ {literal, hypothesis, interval, atom})`,写进 `certificate.json`;
|
||
- **Lean 脚本**:`unfold run` 后按同一棵 `if` 树 `split_ifs`,每个叶子 `simp_all <;> omega`。离线情形树与 Lean 的 `if` 树来自同一份 IR,叶子一一对应;某个叶子离线关闭而 Lean 关不掉,就是 `proof.divergence`。
|
||
|
||
因此"离线判定 ⊂ Lean 判定"不是口头承诺,而是三件事:
|
||
|
||
1. **构造上**:F5 的推理是 `omega` 的子集,F1–F4 是 `simp`/`decide` 的子集;
|
||
2. **运行期**:只要有 Lean,就在 ⑥ 复核;`checked` 但 Lean 未关闭 ⇒ `error[proof.divergence]`,退出 1,永不落绿;
|
||
3. **测试上**:语料库强制 `offline_checked ⊆ lean_proved`(roadmap 测试矩阵 A1)。
|
||
|
||
**不夸大**:我们不说"离线判定器已被证明正确"。我们说它片段极小、保守、每条结论都带 Lean 脚本,且有运行期复核与 CI 语料强制。
|
||
|
||
### 5.5 反例
|
||
|
||
当某条路径可满足、且结论在该路径上求值为假时,从区间端点取一组参数值作为见证:
|
||
|
||
```text
|
||
反例: 金额 = 10001
|
||
路径: 金额 > 10000 → 人工审核
|
||
结论: 结果.ok = False
|
||
实际: 结果.ok = True(人工审核的返回值被包进 result.ok)
|
||
```
|
||
|
||
反例只承认**确定性否定**:结论必须是字面 `false`,路径必须由区间证明可满足,且路径条件里**不含自由布尔原子**(否则可能凑出真实语义下不存在的组合)。任何一条不满足就退回 `unproved`(无见证)或 `unverified`,不编故事。
|
||
|
||
---
|
||
|
||
## 6. Lean 编码
|
||
|
||
### 6.1 产物布局
|
||
|
||
```text
|
||
verification/skill-proof/ # 入仓:语义库 + 论文样例(人工评审)
|
||
lean-toolchain # 与 replay-policy 同钉(v4.35.0)
|
||
lakefile.lean
|
||
MarqdoProof.lean
|
||
MarqdoProof/{Basic,Result,Tactic}.lean
|
||
examples/{approval,false-claim}.lean
|
||
README.md # TCB 与"证了什么"的边界声明
|
||
LIBRARY-SHA256 # 由构建脚本写入
|
||
|
||
.marqdo/prove/ # 生成物(.marqdo/ 已 gitignore)
|
||
pkg/ # 一次性 Lake 包(库副本 + Generated/)
|
||
<key>/plan.json module.lean certificate.json lean.log
|
||
index.json # key → 指纹/状态/耗时
|
||
```
|
||
|
||
### 6.2 无公理:操作是参数,假设是前提
|
||
|
||
```lean
|
||
-- 库提供(MarqdoProof/Basic.lean,节选)
|
||
inductive Val | none | int : Int → Val | str : String → Val | bool : Bool → Val
|
||
| list : List Val → Val | map : List (String × Val) → Val
|
||
|
||
structure Err where code : String; message : String; operation : String
|
||
structure Result where ok : Bool; value : Val := .none; error : Option Err := none
|
||
|
||
-- lib/result 的真实构造器(ok/error/value_or)映射:
|
||
def Result.success (v : Val) : Result := { ok := true, value := v }
|
||
def Result.failure (e : Err) : Result := { ok := false, error := some e }
|
||
```
|
||
|
||
生成文件里**不出现 `axiom`,也不出现 `opaque`**:外部操作是 `Env := Op → Val` 参数,后置条件是定理的假设 `h_post`。于是 `#print axioms` 为空,定理陈述本身就把"信任了什么"写清楚。
|
||
|
||
### 6.3 直接风格降级(无 monad、无 `do`)
|
||
|
||
`StateM`/`do` 在证明里要额外展开 monad 定律,早返回的语义也容易踩坑。改用**续延式直接风格**:`compile_stmts(stmts, k)` 在 Rust 里把后续语句当续延,早返回就是"把 `k` 换成函数出口"。产出的 Lean 是纯 `let`/`if`/`pair`,`simp`/`split`/`omega` 直接可用。
|
||
|
||
输入(`verification/skill-proof/examples/approval.mq.md` 节选):
|
||
|
||
```markdown
|
||
## 审批
|
||
+ `金额`
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| 金额 | int | 申请金额(元) |
|
||
|
||
| 返回 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| result | map | Result |
|
||
|
||
| 定理 | 结论 | 前提 | 策略 |
|
||
|---|---|---|---|
|
||
| 大额必经人工 | 包含(轨迹, "人工审核") | 金额 > 10000 | auto |
|
||
|
||
1. `金额` > 10000
|
||
**审核 = [提交人工审核](人工审核(金额=`金额`))**
|
||
**结果 = [保留人工审核结论](result.ok(value=`审核`))**
|
||
2. *
|
||
**结果 = [自动通过](result.ok(value="auto"))**
|
||
|
||
**结果**
|
||
```
|
||
|
||
输出:
|
||
|
||
```lean
|
||
import MarqdoProof
|
||
open MarqdoProof
|
||
|
||
namespace Generated.Approval
|
||
|
||
structure Params where
|
||
金额 : Int
|
||
deriving Repr, DecidableEq
|
||
|
||
inductive Op where
|
||
| 人工审核 (金额 : Int)
|
||
deriving Repr, BEq
|
||
|
||
def Op.name : Op → String
|
||
| .人工审核 _ => "人工审核"
|
||
|
||
abbrev Env := Op → Val
|
||
|
||
def run (env : Env) (p : Params) : Result × List Op :=
|
||
if p.金额 > 10000 then
|
||
let v := env (.人工审核 p.金额)
|
||
(Result.success v, [.人工审核 p.金额])
|
||
else
|
||
(Result.success (.str "auto"), [])
|
||
|
||
theorem 大额必经人工 (env : Env) (p : Params) (h : p.金额 > 10000) :
|
||
(run env p).2.any (fun o => o.name == "人工审核") = true := by
|
||
unfold run
|
||
split_ifs <;> simp_all <;> omega
|
||
|
||
end Generated.Approval
|
||
```
|
||
|
||
要点:每步带 `-- mq: line:col` 注释;中文标识符直接可用,含点/空格的用 `«…»`;命名冲突在生成前消解。
|
||
|
||
### 6.4 义务与定理
|
||
|
||
| 项 | 形状 | 来源 |
|
||
|---|---|---|
|
||
| 类型检查(T0) | 文件通过内核:字段、元数、分支同型 | Lean,编译结果即证据 |
|
||
| 终止(T1) | 无 `while`/递归 ⇒ Lean 接受为 `def` | 同上;需要 `partial` 的一律已跳过 |
|
||
| `effects_subset` | 实际 `Op` 集合 ⊆ `--effects` 授权 | Rust 判定,写证书 `obligations` |
|
||
| 作者定理(T2) | `∀ p, pre p → post p (run env p)` | 定理表 |
|
||
| 假设(T3) | `h_* : ∀ …, Post …` 作为定理前提 | 假设表 |
|
||
|
||
违反 `effects_subset` 不是 `rejected` 而是 `error[proof.effects_exceeded]`:前者是"够不着",后者是"够得着且越权",必须区分。未给 `--effects` 时该义务记为 `skipped`,不假装通过。
|
||
|
||
### 6.5 策略
|
||
|
||
```lean
|
||
macro "mq_auto" : tactic =>
|
||
`(tactic| first
|
||
| decide
|
||
| omega
|
||
| simp_all
|
||
| (split <;> simp_all)
|
||
| (split_ifs <;> simp_all <;> omega)
|
||
| aesop)
|
||
```
|
||
|
||
定理表 `策略` 列可写 `auto` / `omega` / `simp [run]` / 任意 tactic 片段;写 `none` 表示只生成不证(论文留人工证明钩子),状态记 `unverified` 而不是失败。
|
||
|
||
### 6.6 源码映射
|
||
|
||
每个语句前放 `-- mq: <line>:<col>`;`module.lean` 与 `plan.json` 同缓存。Lean 报 `Generated/X.lean:41:7: error: …` 时,驱动把 41 映射回 `.mq.md` 行,诊断指回源码,`lean_line` 放在 JSON 细节里。映射表进证书。
|
||
|
||
---
|
||
|
||
## 7. 作者面:定理表与语言习惯
|
||
|
||
### 7.1 语法与位置
|
||
|
||
表格构造**已有**(不新增核心标记),这里只给它一个新的**语义角色**:
|
||
|
||
```markdown
|
||
| 定理 | 结论 | 前提 | 策略 |
|
||
|---|---|---|---|
|
||
| 大额必经人工 | 包含(轨迹, "人工审核") | 金额 > 10000 | auto |
|
||
```
|
||
|
||
规则(与 `参数/返回/字段` 契约表同构):
|
||
|
||
1. 表头别名:`定理/证明/claim/theorem`;列名 `结论/conclusion`、`前提/premise`(可缺省)、`策略/tactic`(可缺省)。
|
||
2. 位置:函数体**首条可执行语句之前**,与契约表同一槽位;提取后从 body 移除,**不参与运行**。出现在别处仍是普通表,`check --proof` 报 `proof.claim_misplaced`。
|
||
3. 一行一条;`定理` 列是函数内唯一 id,重复即 `proof.claim_duplicate`。
|
||
4. 结论/前提是**受限表达式**:参数、`结果`、`轨迹`、`包含/contains`、`长度/length`、`下标/index`,以及算术/比较/布尔。其他名字 → `proof.claim_unknown_symbol`(带最近建议)。
|
||
5. 一张表如果既像契约表(有 `类型` 列)又像定理表(有 `结论` 列)→ `proof.claim_ambiguous`,不猜。
|
||
|
||
### 7.2 语义
|
||
|
||
一条定理展开为:
|
||
|
||
```lean
|
||
theorem <id> (env : Env) (p : Params) (h : <前提>[p]) :
|
||
<结论>[p, (run env p)] := by …
|
||
```
|
||
|
||
- 前提在**入口状态**求值(参数),结论可引用参数、`结果`、`轨迹`。
|
||
- 没有前提就是全称命题;`结果.ok = True` 天然表示"所有成功终止都满足"。
|
||
- `轨迹` 有序;`包含/长度/下标` 三个谓词够表达"存在/顺序/计数",不再长大。
|
||
- 定理是**声明**,不是代码:没有求值顺序、没有副作用、不能调用任意函数。
|
||
|
||
### 7.3 语言习惯审查(是否引入了多余语义)
|
||
|
||
这是这次设计最需要交代清楚的一节。逐条回答"会不会破坏语言习惯"。
|
||
|
||
#### 7.3.1 实际新增了什么
|
||
|
||
| 新增项 | 性质 | 是否影响运行 |
|
||
|---|---|---|
|
||
| `Function.claims` 元数据 | 声明(与 `Function.contract` 同类) | **否**,提取后从 body 移除 |
|
||
| 定理作用域的两个保留名(`结果/轨迹`)与三个谓词 | 只在定理内可见的绑定 | **否**,不在普通表达式作用域 |
|
||
| 假设表作用域的 `返回` | 只在假设表内可见的绑定 | **否** |
|
||
| `check --proof` | 静态校验开关,默认关 | 否 |
|
||
|
||
除此之外没有新语法、没有新标记、没有新求值规则、没有新类型系统。
|
||
|
||
#### 7.3.2 没有新增什么(逐项对照)
|
||
|
||
| 风险项 | 结论 | 依据 |
|
||
|---|---|---|
|
||
| 新核心标记? | 否 | 用的是既有 GFM 表(`core-surface.md` 的 `table`);`CORE_CONSTRUCTS` 计数不变 |
|
||
| 新求值顺序/作用域? | 否 | 定理表与契约表一样,在解析期提取,不进 AST body |
|
||
| 新调用约定/形参? | 否 | 不要求调用者传证明参数,不给函数加隐藏形参 |
|
||
| 新类型系统(refinement/依赖类型)? | 否 | 只在表里写命题;不做类型层扩展 |
|
||
| 影响叙述比例/可读性? | 否 | 表是 code 构造;GitHub 渲染正常;`labels`/`narrative_ratio` 行为不变 |
|
||
| 影响 `check` 既有诊断? | 否 | 新表头不命中 `参数/返回/字段`,`parse_contract_table` 不认领;新增校验默认关 |
|
||
|
||
#### 7.3.3 为什么不是别的写法
|
||
|
||
| 备选 | 为什么不用 |
|
||
|---|---|
|
||
| frontmatter `proof:` 块 | 丢函数作用域与行级锚点;一个函数一条定理时锚点落在文件头,诊断无法指回具体行;多函数文件无法分派 |
|
||
| `# 证明` 标题 | `#` 是对象、`##` 是函数,标题即单元——新增"标题=命题"会破坏"标题即可调用单元"这条既有习惯,且会进命名空间 |
|
||
| 围栏块(` ```proof ` 语言标签) | 代码围栏必须跟在空赋值后(`x =` + fence),否则解析器直接报错;为了写定理先造一个死变量,比表更别扭,且该值会被当作可执行值 |
|
||
| 注释里写定理(`<!-- -->`) | 注释不参与语义,也拿不到行锚点;工具无法可靠区分"说明"与"定理" |
|
||
| 单独 `.proof.md` 旁挂文件 | 真理被拆成两份,正是这个项目一直在避免的事("代码与文档同一份") |
|
||
| 类型即契约(refinement) | 语义增量太大,且现有契约表已经承担类型声明;再来一套会形成"两份作者真相" |
|
||
|
||
函数级表格是最符合本项目习惯的:**声明与函数同址、可定位、可校验、不可执行**——这正是 `参数/返回/字段` 表已经建立的模式。
|
||
|
||
#### 7.3.4 命名冲突与遮蔽
|
||
|
||
- 定理作用域里 `结果`/`轨迹`、假设作用域里 `返回` 是保留名。若函数有形参或局部变量同名,`check --proof` 报 `proof.name_shadow`(错误),要求改名——**不**做隐式优先,避免"同名不同义"。
|
||
- 谓词名 `包含/长度/下标` 若与用户函数同名,同样报 `proof.name_shadow`,不做静默覆盖。
|
||
|
||
#### 7.3.5 仍然存在的风险与护栏
|
||
|
||
| 风险 | 说明 | 护栏 |
|
||
|---|---|---|
|
||
| "定理像代码"的错觉 | 作者可能以为 `结果.ok = False` 会在运行时求值 | 文档措辞统一为"声明";`view` 渲染成定理卡片;`check` 提示不可运行位置 |
|
||
| 定理表长出第二门语言 | 有人想写量词、自定义谓词、调用函数 | 谓词集合封闭(3 个);超出即 `proof.claim_unsupported`;ADR 改集合需重新评审 |
|
||
| 定理与代码漂移 | 改了分支但没改定理 | 定理锚定行号;`check --proof` 校验引用的变量仍存在;`prove` 每次重证 |
|
||
| 定理变成装饰 | 写了 `策略 none` 或永远 `unverified` | `audit` 统计"声明/已判定/未判定";证书只记录实际判定结果 |
|
||
| 表被误当数据表 | 普通文档表恰好叫 `定理` | 只有表头命中且列形正确才认领;两列的"定理/说明"表仍是普通表 |
|
||
|
||
结论:**语义增量被压到三条声明级绑定,且不进入运行时**。它没有引入新的编程习惯,只是把"契约表"这一既有习惯扩展到"命题"。
|
||
|
||
### 7.4 假设表(T3)
|
||
|
||
外部操作默认完全未知。要让"只要银行返回失败,我们就不会记账"这类推理成立,把假设写成表:
|
||
|
||
```markdown
|
||
| 假设 | 前置 | 后置 |
|
||
|---|---|---|
|
||
| 银行.转账 | 金额 > 0 | 返回.ok = True |
|
||
```
|
||
|
||
- 表头 `假设/assumption`;`操作` 列是调用显示名(`库.成员`)。
|
||
- 前置在实参上求值;后置在 `返回`(操作返回值)上求值;支持 `=/≠/包含/长度` 与 `返回.ok`(映射字段读取的语法糖)。
|
||
- 生成 Lean 时不是公理,而是**定理前提**:`h_转账 : ∀ a, a > 0 → (env (.转账 a)).field? "ok" = some (.bool true)`。
|
||
- 无法定型的后置 → `proof.assumption_untyped`(提示改成等式或补返回契约)。
|
||
- `audit` 与证书 `assumptions` 一一对应。
|
||
|
||
### 7.5 与 `check` / `view` / `catalog`
|
||
|
||
- `check`:新增 `--proof`(**默认关**,保持既有性能),校验表形、名字、片段;不跑 Lean。
|
||
- `view`:定理表渲染成"已声明定理"卡片;有证书时附状态徽标(`proved`/`checked`/`unverified`)。不触发证明。
|
||
- `catalog`/`knowledge`:`Artifact` 增可选 `proof:` 摘要(证书哈希 + 状态 + 定理数),供 EKM 与 `reuse` 过滤;不改变现有 schema 必填项。
|
||
|
||
---
|
||
|
||
## 8. 工程落点
|
||
|
||
### 8.1 新增 / 修改文件
|
||
|
||
| 文件 | 变更 |
|
||
|---|---|
|
||
| `src/prove/mod.rs` | API、状态机、报告聚合 |
|
||
| `src/prove/ir.rs` | Plan IR + 规范化 JSON + 指纹 |
|
||
| `src/prove/lower.rs` | AST → IR、子集验收、拒绝码、内联 |
|
||
| `src/prove/types.rs` | 类型推断与合一 |
|
||
| `src/prove/emit.rs` | IR → Lean(确定性、命名消解、span 注释、脚本生成) |
|
||
| `src/prove/offline.rs` | 符号执行、F1–F5 判定、反例 |
|
||
| `src/prove/driver.rs` | 工具链探测、Lake 包、`lean` 调用、超时、诊断映射 |
|
||
| `src/prove/cache.rs` | 证书、`index.json`、失效判定 |
|
||
| `src/prove/report.rs` | 文本 / `--json` 渲染 |
|
||
| `src/ast.rs` | `Function.claims: Vec<Claim>` |
|
||
| `src/claim.rs`(或并入 `contract.rs`) | 定理表提取与校验 |
|
||
| `src/parse/mod.rs` | 定理表提取入口(首条可执行语句前) |
|
||
| `src/check.rs` | `--proof` |
|
||
| `src/main.rs` | `Commands::Prove`、`ProveAction`、json_errors |
|
||
| `src/lib.rs` | `pub mod prove;` |
|
||
| `verification/skill-proof/**` | Lean 库、样例、`LIBRARY-SHA256`、README |
|
||
| `tests/prove.rs` + `tests/prove/**` + `tests/prove_lean.rs` | 集成测试、夹具、Lean 语料(独立目标) |
|
||
| `.github/workflows/proof.yml` | elan + `lake build` + 语料门禁 |
|
||
|
||
不新增 crate 依赖(`serde_json`、`sha2`、`anyhow` 已在);Lean 侧零依赖(只用 Std)。
|
||
|
||
### 8.2 API
|
||
|
||
```rust
|
||
pub struct ProveOptions {
|
||
pub entry: Option<String>,
|
||
pub only: Vec<String>,
|
||
pub allow_opaque: Vec<String>,
|
||
pub emit_dir: Option<PathBuf>,
|
||
pub effects: Option<String>,
|
||
pub strict_types: bool,
|
||
pub offline: bool,
|
||
pub timeout: Duration,
|
||
pub heartbeat: u64,
|
||
pub require_lean: bool,
|
||
pub report_only: bool,
|
||
pub no_cache: bool,
|
||
pub lean: Option<PathBuf>,
|
||
pub library: Option<PathBuf>,
|
||
}
|
||
|
||
pub enum Verdict { Proved, Checked, Unverified, Unproved, Rejected, Error }
|
||
|
||
pub fn prove_path(path: &Path, opts: &ProveOptions) -> Result<Report>;
|
||
pub fn emit_path(path: &Path, out: &Path) -> Result<EmitReport>; // 不判定
|
||
pub fn audit_path(path: &Path) -> Result<AuditReport>; // 不判定
|
||
```
|
||
|
||
`main.rs` 只做参数搬运与退出码映射(与 `Commands::Verify` 同风格)。
|
||
|
||
### 8.3 缓存与证书
|
||
|
||
缓存键:`sha256(源码 ⊕ plan.json ⊕ schema ⊕ 库 sha256 ⊕ lean --version ⊕ marqdo 版本)`。证书:
|
||
|
||
```jsonc
|
||
{
|
||
"schema": 1,
|
||
"key": "…",
|
||
"status": "proved",
|
||
"tier": "lean",
|
||
"source": {"path": "skills/…", "sha256": "…", "artifact_id": "mq://…"},
|
||
"lean": {"toolchain": "…", "library_sha256": "…", "module_sha256": "…", "axioms": []},
|
||
"claims": [{"id": "…", "status": "proved", "decided_by": "omega"}],
|
||
"offline": {"claims": [{"id": "…", "status": "checked", "cases": 3}]},
|
||
"obligations": [{"id": "effects_subset", "status": "passed"}],
|
||
"assumptions": ["银行.转账: 前置 金额 > 0;后置 返回.ok = True"],
|
||
"span_map": {"41": "21:1"},
|
||
"created": "2026-11-13T09:00:00Z",
|
||
"marqdo": "2.8.0"
|
||
}
|
||
```
|
||
|
||
- 命中即跳过判定(报告标 `cache: hit`)。
|
||
- 源文件、库、工具链任一变化即失效;暂不做部分重证。
|
||
- 证书是**复核收据**,不是发布许可:推荐附在发布说明里,不强制。
|
||
- `prove clean` 删 `.marqdo/prove`(`--emit` 目录不动)。
|
||
|
||
### 8.4 工具链与库发现
|
||
|
||
1. `--lean`/`--lake`;2. `MARQDO_PROOF_LEAN`/`MARQDO_PROOF_LAKE`;3. `PATH` 上的 `lake`,再 `lean`;4. 都没有 → 只跑离线,`lean: null`。
|
||
|
||
显式给出(flag 或环境变量)但路径不存在/不可执行 → `error[proof.lean_missing]`,**不**回退到离线:避免"我以为在跑 Lean,其实没有"。
|
||
|
||
库发现:`--library` → `MARQDO_PROOF_LIB` → 仓库内 `verification/skill-proof` → 安装根 `share/marqdo/proof/` → 相邻 `marqdo-proof/`。首次使用按 `LIBRARY-SHA256` 复制进 `.marqdo/prove/pkg` 并 `lake build` 一次(缓存);库哈希进证书。
|
||
|
||
### 8.5 环境变量
|
||
|
||
| 变量 | 作用 |
|
||
|---|---|
|
||
| `MARQDO_PROOF_LEAN` / `MARQDO_PROOF_LAKE` | 工具链路径 |
|
||
| `MARQDO_PROOF_LIB` | 语义库目录 |
|
||
| `MARQDO_PROOF_TIMEOUT` | 默认超时(秒) |
|
||
| `MARQDO_PROOF_CACHE` | 缓存根(默认 `.marqdo/prove`) |
|
||
| `MARQDO_PROOF_NO_CACHE` | 等价 `--no-cache` |
|
||
| `MARQDO_PROOF_REQUIRE_LEAN` | 等价 `--require-lean`(CI/测试用) |
|
||
|
||
---
|
||
|
||
## 9. 测试与证据(摘要)
|
||
|
||
完整矩阵见 [roadmap/prove.md](../roadmap/prove.md) §6。四类必须守住的证据:
|
||
|
||
1. **单调性**(用户硬要求):语料库里每条离线 `checked` 的定理,Lean 都必须证出来;任何分歧 → `error[proof.divergence]`。
|
||
2. **不执行**:带 `fs.write`/`exec` 的夹具在 `prove` 后不产生任何副作用。
|
||
3. **确定性**:同输入两次运行,`module.lean` / `plan.json` / 证书键全等。
|
||
4. **诚实性文案**:`checked` 与 `proved` 在文本、JSON、证书三处措辞一致,不允许出现"已验证"字样描述离线结果。
|
||
|
||
---
|
||
|
||
## 10. 已定事项
|
||
|
||
| # | 事项 | 结论 | 备注 |
|
||
|---|---|---|---|
|
||
| 1 | 命令名 | `marqdo prove` | 别名 `lean` |
|
||
| 2 | 是否强制 | **不强制**;规范与手册推荐 | 无 `--require-lean` 时缺工具链不失败 |
|
||
| 3 | 离线能否给结论 | 能,但只到 `checked` | 严格弱于 Lean(§5) |
|
||
| 4 | 定理写法 | 函数级 `定理` 表 | [ADR 0010](../adr/0010-skill-proof-boundary.md) |
|
||
| 5 | `check --proof` | 加,默认关 | |
|
||
| 6 | 首版 `foreach` | 不做,P3 再加 | 之前 `proof.foreach_pending` |
|
||
| 7 | 状态词 | `proved` / `checked` / `unverified` / `unproved` / `rejected` | 只有 `proved` 能说"已证明" |
|
||
|
||
遗留(不阻塞开工,P2 前定):`假设` 表是否也认领 `前置/后置` 之外的列(如 `来源`);`--all` 的聚合粒度(按文件还是按函数);证书是否需要签名。
|
||
|
||
---
|
||
|
||
## 11. 文档与发布清单
|
||
|
||
- [ ] 本文件转 `Implemented`(分阶段勾)
|
||
- [ ] `doc/roadmap/prove.md`:里程碑、周计划、测试矩阵
|
||
- [ ] `doc/adr/0010-skill-proof-boundary.md`:定理表角色 + 子集边界 + 顾问式定位
|
||
- [ ] `doc/design/skill-proof-theory.md`:语义映射、定理形态、TCB 表
|
||
- [ ] `verification/skill-proof/README.md`:构建、身份哈希、与 replay-policy 的关系
|
||
- [ ] `README.md`:CLI 三行示例 + 状态表 + "推荐但不强制"
|
||
- [ ] `doc/tutorial/13-命令行工具.md`:先 `emit`,再 `prove`
|
||
- [ ] `skills/marqdo-dev/index.mq.md`:新增 `prove` 任务(推荐在发布前跑)
|
||
- [ ] `skills/marqdo/reference.md`:定理表语法速查
|
||
- [ ] `CHANGELOG.md`:2.8.0;「核心表面 Δ:无(表格新增语义角色:定理)」
|
||
- [ ] `.github/workflows/proof.yml`;`.gitignore` 已含 `.marqdo/`
|
||
- [ ] 发版手册:推荐附证书哈希,不设为硬门禁
|
||
|
||
---
|
||
|
||
## 12. 实现状态与偏差记录(P0/P1 落地时修订)
|
||
|
||
| 状态 | 内容 |
|
||
|---|---|
|
||
| **P0 已落地** | `src/prove/`:`ir.rs`(Plan IR + 稳定 JSON)、`lower.rs`(子集验收/内联/不透明化/效应标签)、`types.rs`(字面量推断 + 分支合流 + `proof.type_mismatch`)、`emit.rs`(确定性 Lean 生成)、`mod.rs`(Report/Verdict/ProveOptions + `prove/emit/audit/clean`)。测试:`tests/prove.rs` 12 例 + 模块单元测试,全部不依赖 Lean。 |
|
||
| **P1(Rust 侧)已落地** | 定理表提取(`ast::Function.claims` + `contract::parse_claim_table`,首条可执行语句之前,提取后移出 body);`check --proof`(默认关):`proof.claim_malformed` / `claim_ambiguous` / `claim_misplaced` / `claim_duplicate` / `claim_unknown_symbol` / `claim_unsupported` / `name_shadow`;定理脚手架生成(受限文法 → Lean `theorem` 陈述 + §7.2 策略脚本)。Lean 判定(lake/driver/cache/CI)按 roadmap P1 第 2 周继续。 |
|
||
|
||
### 与本文前面章节的偏差(以本表为准)
|
||
|
||
1. **`result.ok/error/value_or`,不是 `result.success/failure`**:设计起草时假设的库名与 `lib/result.mq.md` 真实 API 不一致,实现以真实库为准(§4.5/§6.2 示例已同步修正)。Lean 侧库提供 `Result.success/failure` 作为映射目标。
|
||
2. **P0/P1 的 `run` 返回 `Val × List Op`**:`result.ok(...)` 内联为 Val 字面映射构造(`mqResultOk`),而非单独的 `Result` 结构。P2 起按返回契约提升为类型化 `structure Params`/`Result`(§6.2 的形态),届时定理表可直接做字段级推理。
|
||
3. **Op 构造器带元数**:`inductive Op` 的每个构造器按首现实参个数声明 `参数1..参数N : Val`(§6.2 示例省略了这一点)。
|
||
4. **`--allow-opaque` 的效应标签恒为 `opaque`**:即便函数声明了契约效应也不沿用——行为完全未知时引用其声明只会误导 `audit` 读者(§2.2)。
|
||
|
||
### 审查修复(同日代码审查发现,均有回归测试)
|
||
|
||
| 缺陷 | 后果 | 修复 |
|
||
|---|---|---|
|
||
| 表格单元格里的调用被静默丢弃 | 含副作用调用的函数在 Lean 里伪装成"无操作"——违反诚实性契约 | `lower_expr` 回退分支检测容器内的调用 → `proof.unsupported` 拒绝整个函数 |
|
||
| 同名不同元数的调用点共享一个 Op | 构造器按首现声明元数,另一调用点生成非法 Lean(无法编译) | `register_op` 对不同元数加 `/N` 后缀,各自独立声明(轨迹名诚实区分) |
|
||
| `name_shadow` 每层遍历重复报告 | 模块有 N 个函数就报 N 次,噪声淹没真实问题 | 谓词名检查只跑一次(模块级事实);形参检查只看自带定理表的函数 |
|
||
| `长度(轨迹) = 2` 生成 `mqEq (Nat) (Val)` | Nat 与 Val 类型不匹配,Lean 无法编译 | Nat 语境检测:轨迹长度与整数字面量的比较走原生 Nat 运算;不可译形状 → 注释占位 |
|
||
|
||
另有防护加固:`lean_ident` 保留 `轨迹₀`/`h_前提`(定理 binder 撞名防御);emit 对重复定理 id 去重(`check --proof` 未跑时也不产出重复声明)。
|
||
|
||
### 审查时的业务级验证(/tmp/biz,电商大额订单审批流)
|
||
|
||
- `审批.mq.md`(审批单 + 人工审核)+ `风控.mq.md`(风险分级)+ `lib/工单.mq.md`(建单):三条定理(大额必经人工 / 恰两步轨迹 / 必有回执)提取成功
|
||
- 真实解释器三场景交叉验证:5000 元 → `auto`(1 步轨迹);20000/60000 元 → 人工建单 `T-20000`/`T-60000`(`需人工 → 创建` 恰两步)——与定理表逐条吻合
|
||
- 负例:破坏定理表(未知符号 + 重复 id + 谓词元数错)→ `check --proof` 各报一码且默认关静默;emit 仍 advisory 可用;双次 emit 字节一致
|
||
|
||
### Lean 环境实装与真机证明(2026-11-16,Lean 4.35.0 / lake 5.0.0)
|
||
|
||
工具链:`lean-4.35.0-linux.tar.zst` 解包至 `target/toolchain/lean-4.35.0-linux/`(无 elan,
|
||
直接 PATH);语义底座 `MarqdoProof`(`Val` + `mq*` 辅助 + 矛盾引理,无 `axiom`/`opaque`)
|
||
经 lake 构建于 `target/proof/skill-proof/`(库源同步在 `doc/verification/skill-proof/`,
|
||
发布时装入 `verification/skill-proof/`——checkout 中该目录属 root)。
|
||
|
||
实测发现并修正的发射器缺陷(均有测试覆盖):
|
||
|
||
| 缺陷 | Lean 行为 | 修复 |
|
||
|---|---|---|
|
||
| `namespace Generated.审批_mq` | `namespace` 命令只接受 ASCII 名(`namespace 审批` 直接语法错误) | 非 ASCII 字符确定性编码 `uXXXX`:`Generated.u5BA1u6279_mq` |
|
||
| 裸中文标识符 `def 审批单`、`(h_前提 : …)`、`v_结果` | Lean 标识符仅 ASCII,全部语法错误 | 非 ASCII 一律 guillemet `«…»`;改名形式走同一编码(`v_u7ED3u679C`) |
|
||
| Op 构造器 `«调用:人工审核»` | guillemet 记号内 `:` 截断记号 | 标识符内 `:` → `_`;`Op.name` 字符串显示保持原 id |
|
||
| 多参构造器模式 `.«调用:x» =>` | 模式未绑定实参,类型不匹配 | `Op.name` 臂补 `_ _` |
|
||
| 占位构造器裸中文 `无操作` | 语法错误 | 占位构造器也走 `op_ctor` |
|
||
| `h_run : … = (结果, 轨迹)` 反向等式 | simp_all 不做反向替换,输出值进不了目标 | 定理陈述翻转:`((结果, 轨迹) = run env [] …)` |
|
||
| 分支互斥假设(`mqGt=true ∧ mqLe=true`) | simp_all 不链式应用蕴含引理 | 库中矛盾引理 + 脚本显式 `.elim`(`exact (mqGt_mqLe_false ‹…› ‹…›).elim`) |
|
||
| 无分支函数上 `split at h_run` | 硬报错(无 if/match 可拆),挡住本可证明的平凡断言 | `try split at h_run` |
|
||
|
||
驱动脚本 `target/proof/run-lean-check.sh`(P1 第 2 周 `--require-lean` 集成雏形):
|
||
prove 生成 → `lake env lean` → `proved / unproved / lean-error` 三态分类。
|
||
|
||
真机证明结果:
|
||
|
||
| 目标 | 结果 |
|
||
|---|---|
|
||
| 业务样例 `审批.mq.md`(3 定理:大额必经人工 / 恰两步轨迹 / 必有回执) | `lake env lean` 0 error,全部 **proved** |
|
||
| 6 个带定理的测试夹具 + 业务样例 | **7/7 全部 proved**(`p2_len` 夹具的断言已修正:纯函数轨迹恒空,`长度(轨迹) = 2` 是作者笔误,改为 `长度(轨迹) = 0`——Nat 比较路径覆盖不变) |
|
||
| 全量 Rust 测试 | 499 通过;仅剩 2 个已记录的环境受限失败(python3 缺失 / playwright root 属主),与 prove 改动无关 |
|
||
|
||
诚实性核对(首轮实测发现后修正):`p2_len` 曾因断言写错(纯函数却断言两步轨迹)
|
||
被 Lean 如实拒绝——生成侧把语义为假的断言原样交给 Lean、判定侧不虚报 proved,
|
||
正是"绝不 lean 无法证明的 marqdo 可以证明"的落实;修复方向是改对断言,不是放宽判定。
|
||
|
||
生成文件头部带 `set_option linter.unusedVariables false` /
|
||
`set_option linter.unusedSimpArgs false`:机器生成产物不应被人写代码的 linter
|
||
刷屏( simp 参数是固定词汇表,个别文件用不到属正常)。
|
||
|
||
### P1 Lean 判定落地(2026-11-17,commit 见 git log)
|
||
|
||
新增 `src/prove/driver.rs` + `src/prove/cache.rs`,判定接进 `prove` 默认动作:
|
||
|
||
| 组件 | 实现 | 与设计的偏差 |
|
||
|---|---|---|
|
||
| 工具链发现(§8.4) | `--lean` → `MARQDO_PROOF_LEAN` → `PATH`;显式给路径但不可执行 → `error[proof.lean_missing]` **不回退**;都找不到 → 状态保持 `unverified`(`--require-lean` 时退 2) | 一致 |
|
||
| 底座构建 | `MarqdoProof.lean` **内嵌**进 marqdo 二进制(`include_str!`),按内容 sha256 前 8 位落盘缓存,`lean -o MarqdoProof.olean` 直接构建 + `LEAN_PATH` 指给被检模块 | **不经 lake**:运行时只依赖 `lean` 一个二进制(无 elan/lake 也判定);lakefile 保留给人/CI 用。`scripts/check-proof-library.sh` 校验内嵌源与 `doc/verification/skill-proof/` 逐字节一致并输出库 sha256 |
|
||
| 判定调用 | `lean <模块>` + 超时(默认 120s,`--timeout`;try_wait 轮询,超时杀进程判 `error`);`--heartbeats` 透传 `-DmaxHeartbeats` | 一致 |
|
||
| 结果解析 | `unsolved goals` → `unproved`;其它 `error` → `error`;干净编译 → `proved`;`sorry`(策略 `none`)→ `unverified` | 一致(§4.4 E4) |
|
||
| 证据映射 | 生成文件 `-- mq: LINE:COL` + 定理头 `-- 定理 <id>(策略 …;mq: N)` → 证书 `span_map`;unproved 定理的诊断指回定理表行,附 Lean 原始目标上下文 | 一致(§8.5) |
|
||
| 证书缓存(§8.3) | 键 = sha256(源码 ⊕ plan ⊕ 库 sha256 ⊕ lean 版本 ⊕ marqdo 版本);命中 → 跳过判定,`lean.cache: "hit"`;`--no-cache` / `MARQDO_PROOF_NO_CACHE` 绕过 | plan.json schema 即结构化 plan(无独立 schema 文件) |
|
||
| 状态/退出码(§3.3) | E1 假定理 unproved 退 1;F2 `--report-only` 恒 0 不判定;F3 `--require-lean` 无工具链退 2;`prove emit` 子命令只生成不判定 | 一致 |
|
||
|
||
**实测抓出的判定层缺陷**(均有回归测试,tests/prove_lean.rs + driver 单元测试):
|
||
|
||
| 缺陷 | 后果 | 修复 |
|
||
|---|---|---|
|
||
| 错误头 `<file>:47:62: error` 解析取了**列号** 62 | unsolved 目标错配到下一个定理(相邻 61–76 区间),甲定理的失败记到乙定理头上 | 取倒数第二个数字段为行号 |
|
||
| 干净编译时 driver 不产出逐定理记录 | 所有定理停留在 `unverified`,证书 `claims: []` | 无错定理一律补 `proved`(或 sorry → `unverified`) |
|
||
| 函数全名含点(`台账.记录.记过即记`)按第一个点切分 | claim id 拼错(`记录.记过即记`),匹配不上报告 | 从定理头注释直接取 claim id,函数名 = 定理名剥掉 claim 后缀 |
|
||
| 无定理函数把文件状态拖成 unverified | 没有义务的函数(纯编排胶水)使整体永远到不了 proved | 文件状态只聚合**有定理**与**被拒绝**的函数;无定理函数自身行仍如实 `unverified` |
|
||
| 测试夹具 `长度(轨迹) = 0` 断言写错(函数体有一次调用) | Lean 如实拒绝——生成侧诚实、判定侧不虚报 | 修正夹具断言为 `= 1`(不是放宽判定) |
|
||
|
||
测试矩阵(`tests/prove_lean.rs`,独立测试目标,`required-features = ["cli"]`):
|
||
A1 真定理 proved · E1 假定理 unproved 退 1 · E4 策略 none → unverified 退 0 ·
|
||
F2 report-only 恒 0 · F3 require-lean 无工具链退 2 · F4 emit 子命令不判定 ·
|
||
G1 假 lean 计数器证"命中跳判定"(含 `--no-cache` 复判) · G2 真证书命中 ·
|
||
G2b `--no-cache` 强制 miss。无工具链时自动 SKIP,`MARQDO_PROOF_REQUIRE_LEAN=1`
|
||
(CI)则缺失即失败。
|
||
|
||
CI:`.github/workflows/proof.yml` —— 装 Lean 4.35.0 → 底座校验 →
|
||
`MARQDO_PROOF_REQUIRE_LEAN=1` 跑判定矩阵(CI 不许静默降级)→ prove 主套件。
|
||
|
||
### P2 离线判定落地(2026-11-17)
|
||
|
||
新增 `src/prove/offline.rs`(片段 F1–F5 的符号执行)+ `tests/prove_corpus.rs`
|
||
(40 夹具单调性语料库):
|
||
|
||
| 组件 | 实现 |
|
||
|---|---|
|
||
| 符号执行(§5.3) | 状态 `Var → SymVal`(Const/Struct/OpResult/Param/Unknown);If 逐分支克隆状态并**接续 If 之后的语句**(Return 常在外层);每个 Return 收集 (路径条件, 结果, 轨迹, 变量快照) |
|
||
| 可行性 | 前提区间 ∩ 路径条件为空 → 路径不可行,空真关闭(Lean 侧对应假设矛盾,simp 可消) |
|
||
| F2 轨迹 | 包含/长度逐路径求值(Op.name 显示名与 Lean 一致) |
|
||
| F3 字面 | `result.ok/error/value_or` 结构求值(与 mqResultOk/mqError/mqValueOr 语义一致) |
|
||
| F4 自由原子 | 外部返回值布尔判定只二分;路径条件里出现同键原子才可关闭(hypothesis);反例路径含自由原子 → 保守放弃见证 |
|
||
| F5 区间 | **收紧后的诚实范围**:字面重述(同原子)→ hypothesis 关闭;区间违反 → 确定性否定 + 区间端点见证(反例);区间**蕴含**(10000 ⊢ 9999)数学上真,但当前 Lean 脚本无 Val 比较传递引理,simp+omega 关不掉——离线同样保守 unverified(等库补引理再放开),否则必触发 divergence |
|
||
| 状态 | 离线 closed → `checked`(decided_by=trace,**不是 proved**);反例 → `unproved` + `proof.claim_failed` 诊断(指回定理表行 + 见证如 `金额 = 10001`) |
|
||
| 单调性护栏(§5.4) | 有 Lean 时逐定理复核:离线 checked 但 Lean unproved,或离线反例被 Lean 证出 → `error[proof.divergence]` 退 1,永不落绿;`MARQDO_PROOF_INJECT_DIVERGENCE=1` 测试注入验证护栏咬人 |
|
||
| 语料库 | `tests/prove/fixtures/` 8 类 × 5 = 40 夹具(literal/trace/interval/free-bool/branches/composition/counterexample/beyond);`corpus_monotonicity_offline_subset_of_lean` 强制 offline ⊆ lean;`corpus_offline_never_claims_proved` 无 Lean 时禁 proved |
|
||
|
||
**实测抓出并修复的缺陷**(均有测试):
|
||
|
||
| 缺陷 | 修复 |
|
||
|---|---|
|
||
| If 分支后丢弃剩余步骤(Return 在 If 外层的常见编排全部丢结果) | 两支克隆状态并接续后续语句 |
|
||
| `negated` 字段与 op 翻转双重否定,取反原子被收集函数丢弃 | 移除字段,否定一律折进 op/expected |
|
||
| 嵌套分支(else 里再嵌 if)Lean 只拆一层 | `try split at h_run` 按最大 if 深度重复发射 |
|
||
| simp 清单缺 `mqResultError`/`mqValueOr`/`mqAnd/mqOr/mqNot` | 全部补入(l2/l5/f1 由分歧护栏暴露) |
|
||
|
||
**已记录的文法限制**:分支条件尚不支持字段访问(`access(审核, "ok")` 作条件
|
||
解析失败)——F4 的"路径条件含自由原子"场景目前由单元测试覆盖,语料库中以
|
||
分支后的结构化结论代替;文法放开后 prove 侧无需改动(offline.cond_atom 已支持)。
|
||
|
||
### P3 组合与产品化(2026-11-17)
|
||
|
||
| 任务 | 状态 | 实现 |
|
||
|---|---|---|
|
||
| `--all` 目录模式 + `--max-files` | ✅ | 递归收集(跳过 target/dist/node_modules/.git/.marqdo,上限 200);目录不带 --all → 拒绝;聚合 JSON `{"kind":"prove-all","status":…,"files":[…]}`;整体状态差者胜(A6 测试:假 lean 分歧在目录模式同样触发护栏、整体退 1) |
|
||
| 差分一致性 T4(B 组) | ✅ | `tests/conformance.rs`:5 个纯函数语料(算术/中文标识符/分支比较/字符串拼接/i64 边界)解释器求值 == Lean `example … = Val.… := by simp`;B4 result.ok 结构字段读取两侧一致。B2(除零/模零)保持已记录偏差:解释器为运行时错误,P1 库模型返回 `.int 0`(MarqdoProof.lean 注释) |
|
||
| 调试注入 `--fault-inject offline-claim` | ✅ | 等价于 `MARQDO_PROOF_INJECT_DIVERGENCE=1`(A3 分歧护栏验证入口) |
|
||
| 跨函数组合 | 部分 | 同模块直线纯函数**内联**(≤24 语句、无分支、effect=pure)已落地;跨模块调用=不透明操作(效应未知,护栏兜底);**assume-guarantee 后置条件复用 → 2.9**(依赖假设表 T3) |
|
||
| `foreach` | 延期 | 维持 `proof.foreach_pending` 拒绝;有限列表 fold 编码需要库级归纳引理,冒进会先于 Lean 关闭路径、破坏单调性护栏可信度(§12.4) |
|
||
| 文档 | ✅ | 教程 §13.8(prove 章节)、skills/marqdo/reference.md(定理表)、本设计文档状态行、roadmap 落地记录;README/CHANGELOG/doc/releases 因仓库权限(root 属主)待人工合入,内容已在 §12.5 |
|
||
|
||
#### §12.4 延期理由(2.9)
|
||
|
||
1. **foreach**:可证子集刻意无循环(返回路径有限性是反例枚举与 Lean 分支
|
||
拆解的共同根基)。fold 编码需 `List.length` 归纳引理入 MarqdoProof.lean,
|
||
且离线判定器需要"有限列表"的证据语法——两件事都没有通过 40 夹具语料库
|
||
的单调性验证,不该在发布版里冒险。
|
||
2. **跨模块 assume-guarantee**:需要假设表(T3)承载被调者后置条件,并把
|
||
假设作为 `hypothesis` 关闭理由暴露给证书。当前跨模块调用是不透明操作,
|
||
诚实且护栏可兜底;半吊子假设复用会制造"看起来证了其实靠假设"的绿灯。
|
||
3. **分支条件字段访问**(`access(审核, "ok")` 作条件):解析器文法限制,
|
||
prove 侧已就绪(offline cond_atom 支持任意键),放开即生效。
|
||
|
||
#### §12.5 待仓库权限合入的内容(已于 2026-11-18 合入)
|
||
|
||
`CHANGELOG.md`(v2.8.0 条目)、`README.md`(版本行 + 愿景第 6 条)、
|
||
`doc/releases/v2.8.0.md`(双语发版说明)、`skills/marqdo-dev/index.mq.md`
|
||
(`prove` 任务)——权限放开后已全部合入原文,见各自文件。
|