agent-formal-verify 0.0.0-stage → 0.4.2

package/skills/formal-verify/examples/tla-template/BoundedQueue.tla

@@ -0,0 +1,42 @@
+---- MODULE BoundedQueue ----
+(* Copyright (c) 2026 Michael Denyer
+   SPDX-License-Identifier: GPL-3.0-only
+
+   The counters of a bounded queue with ordered output: `next` counts claimed
+   items, `consumed` counts consumed items, and at most `Window` items may be
+   in flight. It is the same model as ../lean-template/Model/BoundedQueue.lean.
+   TLC checks it for the instances in BoundedQueue.matrix; Lean proves it for
+   every size. BoundedQueue.mutations lists the bugs its properties must detect.
+
+   To adapt it, replace the header with the source files and line ranges the
+   model follows, give each thread a program counter, and keep the top-level
+   formula named Spec, which tlc-matrix.sh checks. *)
+EXTENDS Naturals
+
+CONSTANTS Window, Items
+VARIABLES next, consumed
+vars == <<next, consumed>>
+
+Init == next = 0 /\ consumed = 0
+
+Claim == /\ next < Items
+         /\ next < consumed + Window
+         /\ next' = next + 1
+         /\ UNCHANGED consumed
+
+Consume == /\ consumed < next
+           /\ consumed' = consumed + 1
+           /\ UNCHANGED next
+
+\* Stutter at the end so that termination is not reported as a deadlock.
+Done == consumed = Items /\ UNCHANGED vars
+
+Next == Claim \/ Consume \/ Done
+
+Spec == Init /\ [][Next]_vars /\ WF_vars(Claim) /\ WF_vars(Consume)
+
+TypeOK == next \in 0..Items /\ consumed \in 0..Items
+InWindow == consumed <= next /\ next <= consumed + Window
+WindowFull == next = consumed + Window
+AllConsumed == <>(consumed = Items)
+====

package/skills/formal-verify/references/lean-brief.md

@@ -0,0 +1,57 @@
+# Lean modelling brief
+
+Follow this brief to prove one sequential or arithmetic property with Lean 4. Your task gives the source files and line ranges, the functions with their integer types, the property, the model's `<Name>`, the absolute path of the Lake project and the absolute path `<skill-dir>`.
+
+## Files
+
+Write `Model/<Name>.lean`, `Model/<Name>.mutations` and `Model/<Name>.statements` in the Lake project. Start from the `BoundedQueue` files in `<skill-dir>/examples/lean-template/Model/`. Write no other file, so parallel agents share none. Put every declaration in `namespace <Name>`: the checker audits the project's modules together, and equal names clash. The header comment names the source files and line ranges the model follows and each assumption it makes.
+
+Every `.lean` file in the project must belong to a library in the lakefile. With the template's lakefile, that is every file under `Model/`. Add Mathlib only when the arithmetic needs it, since its dependencies can increase setup and build time.
+
+## Model
+
+1. Transcribe the state type and functions with the code's integer widths, rounding, division and order of operations. Use `UInt32` or `Int` with explicit bounds where appropriate, and `Nat` only when values cannot go negative. Keep the source function names and cite `file:line` in doc comments. Preserve any bug during transcription so the model checks the code as written.
+2. State the property as a `Prop` with a `Decidable` instance. It may describe an invariant, an encoder round trip, an index bound or states the machine must never reach.
+3. Write every theorem statement with `sorry` for its proof, then freeze the model with `bash <skill-dir>/scripts/lean-check.sh <absolute-project-path> --freeze Model/<Name>.lean`. This records types and definition bodies even while proofs are unfinished. The FROZEN line confirms the record, not a proof. Added axioms still fail.
+4. Write and evaluate a bounded exhaustive check before proving the theorem. The template's `badPairs` finds states where one step breaks the invariant; `#eval badPairs 2 6` prints concrete counter-examples and `#guard` fails the build while any exist. Set the bound above the code's slot count, batch size, window and other constants so it includes boundary cases. Add a `#guard` that a bounded search from the initial state reaches the states the property depends on. The template's `reachable` search requires a full window.
+5. Prove one theorem per step or function for every size. Split on the guards, use `simp only [...]` to expose arithmetic, then use `omega` or `decide` for a finite type. If a proof needs a fact about the real code that the model lacks, state it as a theorem hypothesis and name it in a comment. Do not declare it as an `axiom`. An unfinished proof may use `sorry`, but the Lean checker reports it as a failure. The checker also fails every declaration that rests on an axiom beyond `propext`, `Classical.choice` and `Quot.sound`, which also rules out `native_decide`.
+
+After a proof closes, print differential test vectors with `#eval`. Include boundary inputs and a spread of in-range inputs, with each input and the model's output on one line. Write a test in the target repository's own framework that calls the production function on those inputs and compares its output. A mismatch is a bug in the production code or the transcription; establish which before reporting. State how many vectors agree and the integer widths in both implementations. If the production comparison was not run, say so beside the proof verdict.
+
+When a theorem needs a proof beyond bounded search and the host offers Lean language-server tools for goals and diagnostics, use them to shorten the loop. This plugin neither requires nor configures such a server.
+
+## Keep the model small
+
+Write each fact once.
+
+- Define the bounded inputs once and filter that list for each property, instead of a new nested loop per property.
+- When two proofs share steps, prove the shared fact as one lemma and use it in both.
+- Keep mutations in the mutations file. The model has no flag or second definition for a planted bug.
+
+## Check
+
+Stay in the target repository and pass absolute paths:
+
+```shell
+bash <skill-dir>/scripts/lean-check.sh <absolute-project-path> Model/<Name>.lean
+python3 <skill-dir>/scripts/mutate.py <absolute-project-path>/Model/<Name>.mutations
+```
+
+The checker enforces the `.statements` file beside each checked source. Changing a theorem type, a definition type or body, or deleting a frozen declaration fails with its name. Adding lemmas and definitions and changing proofs is allowed. Re-freeze only after the production code changes, after a production test contradicts the transcription, or after reviewing a toolchain bump, and explain why in the report. Records are specific to the pinned Lean toolchain. Fingerprints use structural expressions, including the module identity of private references. If two private declarations share a name in one model, give them distinct names before freezing. A project-wide check also rejects records whose source files were deleted. Named-file checks remain limited to those files. A model without a record retains the usual proof and axiom checks, so keep the records under version control. Deleting a record removes that protection.
+
+The file name limits the Lean checker to your model, so another agent's unfinished file does not fail your check.
+
+List plausible bugs in the mutations file, such as `<` instead of `≤`, a missing `+ 1` or a swapped argument. The mutation runner checks each on a copy of the file and names the theorems and `#guard` lines that fail. Expect both the bounded search's `#guard` and the theorem. It rejects a mutation that stops a definition compiling. Revise the properties behind each MISSED line.
+
+Check the reach guard as well as the absence of bad pairs. A search that cannot reach a boundary state does not establish the intended coverage.
+
+## Report
+
+Report only after reading the output of both commands. If either exits 3 with `UNAVAILABLE`, report "not checked" with the printed remedy; do not claim a pass or a model failure. Give:
+
+- the file paths, both commands, the checker's PASS or FAIL line and the mutation runner's output;
+- the states required by the reach guard and the search bound;
+- for each counter-example, concrete inputs to the code's function, the source line of the failing arithmetic, a unit test with those inputs and whether it fails on the production code, whether shipped callers can pass those inputs, and the proposed fix;
+- the `.statements` path and any reason for re-freezing;
+- for a closed proof, its assumptions, including integer widths, bounds and each theorem hypothesis;
+- the number of differential vectors on which the model and production code agree, their integer widths, or an explicit statement that the comparison was not run.

package/skills/formal-verify/references/rust-brief.md

@@ -0,0 +1,81 @@
+# Rust and Kani brief
+
+Use Kani for a Rust function whose inputs and loops can be bounded. Call the real
+function from one `#[kani::proof]` harness per property. Do not transcribe its
+implementation. Start from [the bounded queue template](../examples/kani-template/src/lib.rs).
+
+## Files
+
+Work in the target repository. `<skill-dir>` means the absolute path to this
+plugin's `skills/formal-verify` directory, not a directory in the target crate.
+Own only the assigned harness file and its adjacent `<Name>.mutations` file.
+Coordinate any shared crate or module wiring with its owner. Keep production
+files untouched unless the user has authorized a production fix.
+
+Cite the production source paths and line numbers that each property models in
+the harness header. List caller constraints, bounds and stub assumptions there,
+with source citations or an explicit statement that each is an assumption.
+Call the production function through its real crate or module interface.
+
+## Model
+
+Use `kani::any()` for inputs and `kani::assume` for caller constraints. Record
+integer widths, input bounds and each assumption beside the harness. If a callee
+needs a stub or a function contract, name that assumption in the header comment.
+Put `#[kani::unwind(N)]` on every harness, above its real loop bounds. The checker
+requires this explicit bound and passes it to Kani. A failed unwinding assertion
+means the bound is too low and fails the check.
+
+Add `kani::cover!` witnesses for the boundary or blocking states each property
+depends on, such as a full window or an empty queue. The checker rejects
+unsatisfiable, unreachable and undetermined covers, even when Kani exits
+successfully. Ordinary unreachable assertions are allowed because they describe
+impossible panic branches. Every cover must have status `Satisfied`.
+
+## Check
+
+Stay in the target repository and use absolute paths:
+
+```sh
+bash <skill-dir>/scripts/kani-check.sh /absolute/path/to/crate
+python3 <skill-dir>/scripts/mutate.py /absolute/path/to/crate/src/Name.mutations
+```
+
+Append fully qualified harness names to check only those properties. The helper
+prints one verdict per harness with the unwind bound and number of checks. It
+requires a complete Kani 0.68.0 bundle and Python 3. It checks and invokes the
+bundle's driver directly, without invoking the auto-installing Cargo wrapper.
+A registered Cargo installer is not required after setup. Relative `KANI_HOME`
+paths resolve against the caller's directory before any temporary work begins.
+The helper installs no Kani runtime. `UNAVAILABLE` means not checked; follow the
+printed installation remedy before making any claim about the code. A compilation
+error, missing harness or incomplete verifier report fails.
+
+Put `<Name>.mutations` beside the assigned `<Name>.rs`. Use
+`detects <fully-qualified-harness>` for each mutation. The mutation runner copies
+the whole crate to temporary storage and checks the named harness. A compiler
+error never counts as detection. Every discovered harness needs a mutation.
+
+## Counter-examples
+
+The helper prints failed checks with source locations and Kani's generated
+concrete playback test when available. Copy that test into the harness module in
+a temporary crate copy. Stay in the target repository and run:
+
+```sh
+cargo kani playback --manifest-path /absolute/path/to/temporary-crate/Cargo.toml -Z concrete-playback -- <generated-test-name>
+```
+
+A printed test has not yet reproduced the failure. Record whether this command
+actually fails on the expected assertion. Kani cannot generate playback for
+every failure, including unwinding failures; report that limitation explicitly.
+Never disable unwinding checks to obtain a pass.
+
+## Report
+
+Report each property, input bounds, integer widths, unwind bound, assumptions,
+cover witnesses, mutation results and source location. For each counter-example,
+include its inputs and reproducing test and say whether shipped callers can pass
+those inputs. Use `reproduced`, `reachable at shipped settings` or `model-only`
+as appropriate. A pass covers the stated bounded inputs only. Report unavailable
+tools as not checked with the remedy, never as a pass or a model failure.

package/skills/formal-verify/references/setup.md

@@ -0,0 +1,85 @@
+# Tool setup
+
+Run `/agent-formal-verify:setup` once to prepare Java, Python, TLC, elan, Lean, Rust and Kani. In Codex, request this plugin's `setup` skill. The [setup skill](../../setup/SKILL.md) prepares all three verification tools independently of any repository and reuses existing runtimes and caches.
+
+The formal-verify skill selects tools from the current repository on every invocation. It reuses prepared tools and installs a missing Lean toolchain through the setup helper when a Lean pin changes. Repository changes do not require the user to rerun the full setup.
+
+## Running the helpers
+
+The helpers are in the `scripts/` directory of the installed `formal-verify` skill, including a copied skills-only installation. `<skill-dir>` below stands for that skill's absolute path.
+
+Stay in the target repository and run each helper with `bash` and its absolute path. Pass absolute paths to model projects and matrices. Keep the installed skill files read-only, and create models and build outputs in the target repository. Shared tool caches can serve several repositories; each repository determines its own tool requirements and Lean pins.
+
+## TLA+ and TLC
+
+The setup helper needs a JDK, Python 3, and `sha256sum` or `shasum` to verify the TLC JAR. If `java` on PATH has no runtime, as with the macOS stub, set `JAVA` to a working JDK's `java` binary. Copy the [TLA+ template](../examples/tla-template/BoundedQueue.tla) with its `BoundedQueue.matrix` and `BoundedQueue.mutations` into the project to start a spec.
+
+```shell
+bash <skill-dir>/scripts/setup.sh tla
+bash <skill-dir>/scripts/tlc-matrix.sh /path/to/models/Name.matrix
+python3 <skill-dir>/scripts/mutate.py /path/to/models/Name.mutations
+```
+
+The plugin does not download TLC. Save `tla2tools.jar` from the [TLA+ release](https://github.com/tlaplus/tlaplus/releases/tag/v1.7.4) pinned in `scripts/tlc-tools.sh` as `~/.cache/tla/tla2tools-v1.7.4.jar`; the setup helper verifies its pinned SHA256 and names that path and release when the file is missing or does not match. Set `TLC_CACHE` to choose another cache directory. Set `TLC_JAR` to use an existing JAR; an explicitly supplied JAR is trusted and must already exist.
+
+The matrix runner requires the JAR and a working Java runtime. It checks Python 3 before running, so a failing model can always print its reduced trace. It does not download tools. Each run checks the formula its spec names `Spec` and sees only the modules beside that spec. `TLC_WORKERS` controls the TLC worker count.
+
+The mutation runner reads `Name.mutations` beside `Name.tla` and `Name.matrix`. For each mutation it copies the spec, replaces the listed text, and runs the matrix runner with the one property the mutation names, so it needs the same tools and settings.
+
+## Rust and Kani
+
+Install Rust and Cargo, then install Kani 0.68.0, the version pinned in [`scripts/kani.py`](../scripts/kani.py):
+
+```shell
+cargo install --locked kani-verifier --version 0.68.0
+cargo kani setup
+bash <skill-dir>/scripts/setup.sh rust
+bash <skill-dir>/scripts/kani-check.sh /path/to/crate
+bash <skill-dir>/scripts/kani-check.sh /path/to/crate proofs::claim_keeps_invariant
+python3 <skill-dir>/scripts/mutate.py /path/to/crate/src/lib.mutations
+```
+
+Kani supports Linux and macOS on x86_64 and aarch64. See the [pinned installation guide](https://github.com/model-checking/kani/blob/kani-0.68.0/docs/src/install-guide.md) for system prerequisites. The plugin downloads and installs no Kani runtime. `setup.sh rust` checks the complete pinned bundle and invokes its driver directly. Verification and mutations reuse that driver with its bundled Rust toolchain. They never invoke the auto-installing Cargo wrapper, so the Cargo installer registration is unnecessary after setup. A relative `KANI_HOME` resolves against the caller's directory.
+
+The Rust checker discovers proof harnesses and checks each selected harness separately. It reports the unwind bound and check count, rejects an insufficient bound and any cover condition that was not satisfied, and prints a concrete playback test for a failed assertion when Kani can produce one. Larger inputs and loops remain outside the reported bounds. Crate builds may obtain dependencies declared in Cargo; the template has none.
+
+The mutation runner reads `Name.mutations` beside `Name.rs`, copies the whole crate to a temporary directory, and checks the harness named by `detects`. It leaves the source crate unchanged. Each harness must have a mutation that its property detects.
+
+## Lean 4
+
+Install [elan](https://github.com/leanprover/elan#installation) through your normal package manager or its documented installer. Copy the Lean template's `lakefile.toml`, `lake-manifest.json` and pinned `lean-toolchain` file into the project once. Each model is one file under `Model/`, started from the [template model](../examples/lean-template/Model/BoundedQueue.lean) and its `BoundedQueue.mutations`.
+
+```shell
+bash <skill-dir>/scripts/setup.sh lean /path/to/lean-project
+bash <skill-dir>/scripts/lean-check.sh /path/to/lean-project
+bash <skill-dir>/scripts/lean-check.sh /path/to/lean-project Model/Name.lean
+python3 <skill-dir>/scripts/mutate.py /path/to/lean-project/Model/Name.mutations
+```
+
+The setup helper checks the version in the project's current `lean-toolchain` and installs it only when it is not ready; it leaves the global default unchanged. The Lean checker uses `elan run` without its install flag, so a missing toolchain is UNAVAILABLE instead of downloading inside the checker. Lake builds may fetch dependencies declared by the model project. The supplied template has no external Lean packages.
+
+The Lean checker builds every `.lean` file in the project by its path, so a file that no Lake library owns fails the build instead of going unchecked. It then compiles a short audit against the modules Lake reports for those files. The checker needs a pin of Lean 4.20.0 or later, the first whose Lake builds a module by its source path, and says so when an older pin fails. The audit lists every declaration that rests on an axiom beyond `propext`, `Classical.choice` and `Quot.sound`, so a model needs no `#print axioms` lines. The audit imports the project's modules together, so each model declares its names in a namespace of its own. A file name after the project limits the build and the audit to that file.
+
+The mutation runner reads `Name.mutations` beside `Name.lean`. It elaborates each mutated copy with the project's toolchain and built modules, outside the project, and does not install a toolchain.
+
+Helpers print `UNAVAILABLE` and exit 3 when a required tool is missing, unusable or unverified. Report the target as "not checked" and give the printed remedy. A model or input error prints `FAIL` and exits 1; a usage error exits 2. An unavailable run prints no PASS or SUMMARY line.
+
+## CI
+
+The helpers live in this plugin, not in the target repository. In CI, check out `michael-denyer/agent-formal-verify` at a pinned commit into a separate directory and run the helpers from its `skills/formal-verify/scripts/`. Update that pin deliberately, as for any other tool. A repository that vendors the scripts instead must keep their GPL-3.0-only license headers.
+
+Install the chosen runtime and the pinned TLC JAR in the CI environment, run the setup helper, then run the matrix runner, Lean checker or mutation runner as a separate step. Cache elan's toolchain directory if useful, and keep the version pins with the models. Use the same `TLC_JAR` and `JAVA` settings in setup and verification.
+
+```yaml
+- uses: actions/checkout@<commit>
+  with:
+    repository: michael-denyer/agent-formal-verify
+    ref: <pinned-commit>
+    path: .formal-verify
+- run: bash .formal-verify/skills/formal-verify/scripts/setup.sh tla
+- run: bash .formal-verify/skills/formal-verify/scripts/tlc-matrix.sh "$GITHUB_WORKSPACE/tla/Name.matrix"
+- run: python3 .formal-verify/skills/formal-verify/scripts/mutate.py "$GITHUB_WORKSPACE/tla/Name.mutations"
+- run: bash .formal-verify/skills/formal-verify/scripts/setup.sh lean "$GITHUB_WORKSPACE/lean"
+- run: bash .formal-verify/skills/formal-verify/scripts/lean-check.sh "$GITHUB_WORKSPACE/lean"
+- run: python3 .formal-verify/skills/formal-verify/scripts/mutate.py "$GITHUB_WORKSPACE/lean/Model/Name.mutations"
+```

package/skills/formal-verify/references/tla-brief.md

@@ -0,0 +1,62 @@
+# TLA+ modelling brief
+
+Follow this brief to model one thread protocol with TLA+ and TLC. Your task gives the source files and line ranges, the threads and shared variables, the model's `<Name>`, the absolute path `<skill-dir>` and any `JAVA` setting. Read the whole of each source file so the model follows the code.
+
+## Files
+
+Write `tla/<Name>.tla`, `tla/<Name>.matrix` and `tla/<Name>.mutations` in the target repository, or the same names in its existing model directory. Start from the three `BoundedQueue` files in `<skill-dir>/examples/tla-template/`. Write no other file, so parallel agents share none. Name the top-level formula `Spec`. The header comment names the source files and line ranges the spec follows and each assumption it makes.
+
+## Model
+
+Apply each requirement that fits the protocol, and say in the report which did not.
+
+- Use one step per critical section under the mutex and one per unlocked phase, such as build, parse or consume. Add an explicit `lock` variable when multiple lock acquisitions can race.
+- Use a program counter per thread. Represent a condition-variable wait as a pc value in the wait set. Only a broadcast, signal or spurious wakeup can leave that set. The woken thread must retake the mutex and reread the state before acting. Give spurious wakeups no fairness requirement. In this encoding, a lost wakeup appears as a liveness violation rather than a TLC deadlock. Explain that in the header and check liveness.
+- Model resource ownership as a variable. Each slot or buffer must be free, in exactly one queue, or held by exactly one thread. Each produced item must be recorded by the consumer, awaiting hand-over, or freed.
+- When `longjmp`, an exception, a panic or `exit()` can leave a critical section without unlocking, use separate variables for the mutex's actual owner and the lock ownership recorded in the thread's live frames. An unwind can leave these inconsistent and block later acquisitions. Preserve that state so the model can detect the hang. List every allocation and exit call that can run under each lock, including out-of-memory exits.
+- Let the consumer call `next` any number of times, stop calling, or call `close` from any idle point. Include close before the first call, after the last item and after an error. When the producer has a failure path, let it fail at any item through a constant set `FailAt`.
+- Check small instances and boundary cases. Use slot counts of 1, 2 and the shipped count, item counts of 0, 1, 3 and 5, and one, two and three workers.
+- Name a reachable state predicate for each blocking or boundary behaviour the properties depend on, such as a full window, an empty queue, a parked waiter or an injected failure. Add `reach <Operator> | <label-substring>` to its matrix section. It selects the first run whose label contains the substring. A command-line filter skips the reach check if it excludes that selected run.
+- Check `TypeOK`, the ownership partition, delivery order, no delivery after end or error, the documented error-ordering guarantee, and no double free or leak at `closed`. For liveness, check that each blocking call returns, `close` terminates from every allowed calling state, and a run without `close` reaches the end. Require weak fairness on thread steps except consumer choices and spurious wakeups. Add strong fairness on a mutex acquisition only when a counter-example shows pure starvation by a spuriously waking peer. Name that assumption in the spec.
+
+## Keep the spec small
+
+Write each fact once.
+
+- Group the variables that one thread owns and name the group. An action then lists the groups it leaves alone, not every variable:
+
+  ```tla
+  worker == <<wpc, box>>
+  consumer == <<pc, display>>
+  vars == <<worker, consumer, done>>
+  Notify == /\ wpc = "notify" /\ wpc' = "exit" /\ done' = TRUE
+            /\ UNCHANGED <<box, consumer>>
+  ```
+
+- Define a guard or expression that two actions or properties share as one operator.
+- Keep mutations in the mutations file. The spec has no `Mutation` constant and no branch for a planted bug. When one replacement restores the behaviour before a fix, list it as a mutation instead of adding a constant that switches the fix off.
+
+## Check
+
+Stay in the target repository and pass absolute paths:
+
+```shell
+bash <skill-dir>/scripts/tlc-matrix.sh <absolute-path>/tla/<Name>.matrix
+python3 <skill-dir>/scripts/mutate.py <absolute-path>/tla/<Name>.mutations
+```
+
+The matrix runner prints PASS or FAIL per run and a SUMMARY line. A failing run prints its error trace, reduced to the variables each step changed.
+
+Each reach check prints its own PASS with the shortest witness length in states and transitions, or FAIL when the model never reaches the state. Reach searches use one worker and ignore deadlock so they can finish exploring a stopped model. The SUMMARY counts reach checks separately; its state total covers ordinary runs only. Use `detects reach:<Operator>` for a mutation that removes a required state. Reach checks do not count as properties for mutation coverage.
+
+Before reporting a pass, list mutations that represent plausible code bugs in the mutations file. Try replacing `while` with `if`, removing a broadcast, replacing FIFO order with stack order, leaving a flag set, or taking an item without removing it. Each mutation names the one property that must fail on it. The mutation runner applies each to a copy of the spec. Revise a property it reports as UNCOVERED, and the property or the mutation behind each MISSED line.
+
+## Report
+
+Report only after reading the output of both commands. If either exits 3 with `UNAVAILABLE`, report "not checked" with the printed remedy; do not claim a pass or a model failure. Give:
+
+- the file paths, both commands and their SUMMARY lines;
+- each reach predicate, its selected run and witness length;
+- each FAIL line, with every step of its trace mapped to a code event and `file:line`;
+- for each counter-example, whether the shipped constants and callers can reach it;
+- the real-code constraints the model lacks and the properties it could not express.

package/skills/formal-verify/scripts/kani-check.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+# Copyright (c) 2026 Michael Denyer
+# SPDX-License-Identifier: GPL-3.0-only
+# Usage: kani-check.sh <crate-dir> [<fully-qualified-harness> ...]
+set -euo pipefail
+[ "$#" -ge 1 ] || { echo "usage: kani-check.sh <crate-dir> [<harness> ...]"; exit 2; }
+command -v python3 > /dev/null || { echo "UNAVAILABLE python3 is required; install Python 3"; exit 3; }
+exec python3 "$(dirname "$0")/kani.py" check -- "$@"

package/skills/formal-verify/scripts/kani.py

@@ -0,0 +1,250 @@
+#!/usr/bin/env python3
+# Copyright (c) 2026 Michael Denyer
+# SPDX-License-Identifier: GPL-3.0-only
+"""Run the pinned Kani and validate its versioned discovery and result records."""
+import argparse
+import json
+import os
+import subprocess
+import sys
+import tempfile
+from dataclasses import dataclass
+from enum import IntEnum
+from pathlib import Path
+
+STATUSES = {"Success", "Failure", "Unreachable", "Undetermined", "Satisfied", "Unsatisfiable"}
+# Statuses that pass and statuses that refute the property, by check category; any other is inconclusive.
+OUTCOMES = {
+    "cover": ({"Satisfied"}, {"Unsatisfiable", "Unreachable"}),
+    "unwind": ({"Success", "Unreachable"}, set()),
+}
+PROPERTY_OUTCOMES = ({"Success", "Unreachable"}, {"Failure"})
+
+
+class CheckError(Exception):
+    pass
+
+
+class Unavailable(Exception):
+    pass
+
+
+class Verdict(IntEnum):
+    """A check's or harness's result, ordered so the worst check decides the harness."""
+    PASS = 0
+    REFUTED = 1
+    INCONCLUSIVE = 2
+
+
+@dataclass(frozen=True)
+class Outcome:
+    verdict: Verdict
+    checks: int
+    failures: list
+    output: str
+
+
+def search_path(variable, *directories):
+    inherited = [os.environ[variable]] if variable in os.environ else []
+    return os.pathsep.join([*(str(directory) for directory in directories), *inherited])
+
+
+class Kani:
+    version = "0.68.0"
+
+    def __init__(self):
+        home = Path(os.environ.get("KANI_HOME", Path.home() / ".kani")).resolve()
+        bundle = home / f"kani-{self.version}"
+        remedy = (f"run cargo install --locked kani-verifier --version {self.version} "
+                  "then cargo kani setup")
+        for binary in ("bin/kani-driver", "bin/kani-compiler", "bin/cbmc", "toolchain/bin/rustc", "toolchain/bin/cargo"):
+            path = bundle / binary
+            if not path.is_file() or not os.access(path, os.X_OK):
+                raise Unavailable(f"Kani {self.version} bundle is incomplete; {remedy}")
+        if any(home.glob("*.tar.gz")):
+            raise Unavailable(f"incomplete Kani setup at {home}; finish cargo kani setup before checking")
+        self.driver = bundle / "bin/kani-driver"
+        self.env = os.environ | {
+            "KANI_HOME": str(home),
+            "RUSTUP_TOOLCHAIN": str((bundle / "toolchain").resolve()),
+            "PATH": search_path("PATH", bundle / "bin", bundle / "pyroot/bin", bundle / "toolchain/bin"),
+            "PYTHONPATH": search_path("PYTHONPATH", bundle / "pyroot"),
+        }
+        # A parent cargo (cargo run, cargo test, a build script) exports its rustup toolchain's
+        # lib directory here; the bundled compiler must load only the bundled toolchain.
+        loader = "DYLD_FALLBACK_LIBRARY_PATH" if sys.platform == "darwin" else "LD_LIBRARY_PATH"
+        if loader in self.env:
+            self.env[loader] = os.pathsep.join(
+                path for path in self.env[loader].split(os.pathsep)
+                if not (Path(path).name == "lib" and Path(path).parent.parent.name == "toolchains"))
+        try:
+            done = self.run("--version")
+        except CheckError as error:
+            raise Unavailable(f"Kani {self.version} cannot run: {error}; {remedy}") from error
+        if done.returncode or not done.stdout.startswith(f"Kani Rust Verifier {self.version} (cargo plugin)\n"):
+            raise Unavailable(f"Kani {self.version} is required; {remedy}")
+
+    def run(self, *arguments, cwd=None):
+        try:
+            # The driver selects Cargo mode from argv[0]; the Cargo wrapper can auto-install.
+            return subprocess.run(
+                ["cargo-kani", *arguments], executable=str(self.driver), env=self.env,
+                cwd=cwd, capture_output=True, text=True, check=False)
+        except OSError as error:
+            raise CheckError(f"cannot execute Kani: {error}") from error
+
+
+def invoke(crate, work, kani, *arguments):
+    return kani.run("--manifest-path", str(crate / "Cargo.toml"),
+                    "--target-dir", str(work / "target"), *arguments, cwd=work)
+
+
+def read_json(path):
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as error:
+        raise CheckError(f"missing or invalid Kani report {path.name}: {error}") from error
+
+
+def discover(crate, work, kani):
+    """Return the unwind bound of every proof harness in crate, by fully qualified name."""
+    if not (crate / "Cargo.toml").is_file():
+        raise CheckError(f"{crate}/Cargo.toml is missing")
+    done = invoke(crate, work, kani, "list", "--format", "json")
+    if done.returncode:
+        raise CheckError(f"Kani discovery failed:\n{done.stdout}{done.stderr}")
+    try:
+        report = read_json(work / "kani-list.json")
+        if report.get("kani-version") != kani.version or report.get("file-version") != "0.1":
+            raise CheckError("unsupported Kani discovery schema or version")
+        groups = report.get("standard-harnesses")
+        if not isinstance(groups, dict) or not all(
+                isinstance(names, list) and all(isinstance(name, str) and name for name in names)
+                for names in groups.values()):
+            raise CheckError("malformed Kani harness list")
+        names = [name for group in groups.values() for name in group]
+        if not names:
+            raise CheckError("no proof harnesses found")
+        if len(set(names)) != len(names):
+            raise CheckError("duplicate harness names; select a single crate")
+        bounds = {}
+        for metadata in (work / "target").rglob("*.kani-metadata.json"):
+            for harness in read_json(metadata).get("proof_harnesses", []):
+                name = harness.get("pretty_name")
+                if name in names:
+                    bound = harness.get("attributes", {}).get("unwind_value")
+                    if type(bound) is not int or bound < 1:
+                        raise CheckError(f"{name} needs #[kani::unwind(N)] with N greater than zero")
+                    bounds[name] = bound
+    except (TypeError, AttributeError) as error:
+        raise CheckError(f"malformed Kani discovery record: {error!r}") from error
+    if set(bounds) != set(names):
+        raise CheckError("Kani did not report unwind metadata for every harness")
+    return bounds
+
+
+def harness_result(report, kani, name, returncode):
+    """Return the one harness result in report after checking it agrees with itself and the process."""
+    if report.get("metadata", {}).get("version") != "1.0" or report["metadata"].get("kani_version") != kani.version:
+        raise CheckError("unsupported Kani result schema or version")
+    verification = report["verification_results"]
+    summary, results = verification["summary"], verification["results"]
+    if summary["status"] != "completed" or summary["executed"] != 1 or summary["total_harnesses"] != 1:
+        raise CheckError("incomplete Kani verification")
+    if len(results) != 1 or results[0]["harness_id"] != name:
+        raise CheckError("Kani returned an unexpected harness")
+    result = results[0]
+    if not isinstance(result["checks"], list) or not result["checks"]:
+        raise CheckError("Kani returned no property checks")
+    if result["status"] not in {"Success", "Failure"}:
+        raise CheckError("unknown Kani harness status")
+    failed = result["status"] == "Failure"
+    if returncode != int(failed) or summary["failed"] != int(failed) or summary["successful"] != int(not failed):
+        raise CheckError("Kani process and result disagree")
+    return result
+
+
+def classify(check):
+    category, status = check["category"], check["status"]
+    if status not in STATUSES:
+        raise CheckError(f"unknown Kani check status {status}")
+    passes, refutes = OUTCOMES.get(category, PROPERTY_OUTCOMES)
+    if status in passes:
+        return Verdict.PASS
+    return Verdict.REFUTED if status in refutes else Verdict.INCONCLUSIVE
+
+
+def describe(check):
+    location = check["location"]
+    reason = "bound too low: " if check["category"] == "unwind" else ""
+    return (f"{reason}{check['category']} {check['status']}: {check['description']} at "
+            f"{location['file']}:{location['line']}:{location['column']}")
+
+
+def verify(crate, work, kani, name, bound):
+    """Check one harness; a report that is malformed or disagrees with the process is inconclusive."""
+    result_file = work / "result.json"
+    result_file.unlink(missing_ok=True)
+    try:
+        done = invoke(crate, work, kani, "--harness", name, "--exact", "--unwind", str(bound),
+                      "-Z", "unstable-options", "--export-json", str(result_file),
+                      "-Z", "concrete-playback", "--concrete-playback", "print",
+                      "--output-format", "regular")
+    except CheckError as error:
+        return Outcome(Verdict.INCONCLUSIVE, 0, [str(error)], "")
+    output = done.stdout + done.stderr
+    try:
+        result = harness_result(read_json(result_file), kani, name, done.returncode)
+        verdicts = [(check, classify(check)) for check in result["checks"]]
+        verdict = max(verdict for _, verdict in verdicts)
+        if verdict is Verdict.PASS and result["status"] != "Success":
+            raise CheckError("Kani reports a harness failure that no check explains")
+        failures = [describe(check) for check, verdict in verdicts if verdict is not Verdict.PASS]
+    except (KeyError, TypeError, AttributeError, CheckError) as error:
+        return Outcome(Verdict.INCONCLUSIVE, 0, [f"verification did not complete: {error}"], output)
+    return Outcome(verdict, len(verdicts), failures, output)
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    commands = parser.add_subparsers(dest="command", required=True)
+    commands.add_parser("ready", help="check that the pinned Kani bundle runs")
+    check = commands.add_parser("check", help="verify the crate's proof harnesses")
+    check.add_argument("crate")
+    check.add_argument("harnesses", nargs="*")
+    arguments = parser.parse_args()
+    try:
+        kani = Kani()
+    except Unavailable as error:
+        print(f"UNAVAILABLE {error}")
+        return 3
+    if arguments.command == "ready":
+        print(f"READY Kani {kani.version}")
+        return 0
+    crate, selected = Path(arguments.crate).resolve(), arguments.harnesses
+    with tempfile.TemporaryDirectory(prefix="formal-kani-") as temporary:
+        work = Path(temporary)
+        try:
+            bounds = discover(crate, work, kani)
+            names = list(dict.fromkeys(selected)) if selected else sorted(bounds)
+            unknown = set(names) - set(bounds)
+            if unknown:
+                raise CheckError("unknown harnesses: " + ", ".join(sorted(unknown)))
+        except CheckError as error:
+            print(f"FAIL {error}")
+            return 1
+        passed = 0
+        for name in names:
+            outcome = verify(crate, work, kani, name, bounds[name])
+            ok = outcome.verdict is Verdict.PASS
+            passed += ok
+            print(f"{'PASS' if ok else 'FAIL'} {name} unwind={bounds[name]} checks={outcome.checks}"
+                  + (": " + "; ".join(outcome.failures) if outcome.failures else ""))
+            if not ok:
+                print(outcome.output.rstrip())
+        print(f"SUMMARY {passed} of {len(names)} harnesses passed")
+        return 0 if passed == len(names) else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())