Proof · Engineering practice
How do I turn a written spec into checkable obligations?
Turn a written requirement into a checkable obligation by naming its scope, inputs, assumptions and observable result. Then choose evidence that could contradict it. Compiling a formal contract and checking whether it can be satisfied are useful steps; neither alone verifies the implementation.
Make the worker-pool bound precise
“The worker pool stays bounded” leaves important decisions open. This illustrative contract instead says that an integer request produces a worker count between 1 and 20, with in-range values preserved.
| Obligation | What must be checked |
|---|---|
| Lower bound | A request of 0 produces 1; clarify the accepted domain for negative requests. |
| Upper bound | A request of 21 produces 20. |
| Preservation | A request of 7 produces 7. |
| Assumptions | Requests are integers; resource allocation failures are handled by a separately identified requirement. |
Approve those decisions under the project policy. Candidate requirements may be recovered from code or documentation, but an implementation’s current behavior cannot silently replace the product agreement. Keep allocation failure visible rather than implying the clamp requirement covers it.
Validate the declared model before invoking the solver
proof validate --preflight specs/system evaluation
proof realize specs/system evaluation --diagnose --persist=false
These commands require an existing specification and named component. Preflight checks the component’s model, including declarations needed by the formalization. Realizability invokes an external solver on the generated contract under its assumptions. --persist=false leaves requirement YAML unchanged by the realizability result.
Use supported FRETish or formalization syntax and declared variables; the prose table above is not a complete paste-ready solver input. Inspect the generated model and assumptions when a result is surprising.
If two guarantees cannot both hold for an allowed input, an unrealizability result concerns the contract. A diagnostic counterexample is a model witness to that problem, not automatically an implementation defect or the closure of a defect class. A realizable contract may still be incomplete or implemented incorrectly.
Connect obligations to executable observations
Bind the approved requirement to the helper and to tests whose assertions express the required result. Run below-bound, boundary, interior and above-bound cases on the candidate. If the helper returns zero for a request of zero, that execution demonstrates a code defect relative to the approved lower bound.
proof audit --check tests_pass
proof audit --check obligation_evidence_complete --verbose
The configured tests produce behavioral observations. The obligation-evidence check compares required evidence types with the recorded evidence structure, with run-provenance requirements for typed lemma, race and fuzz evidence. An annotation alone does not prove an assertion is valid or an ordinary test passed.
After a fix, retain the original reproducer. Describe instance repair separately from broader requirement re-verification or class-level closure. See the executed lower-bound teaching example.
Keep acceptance and execution authority explicit
Run the applicable checks against the exact candidate and retain missing, stale, failed and deferred obligations. The audit’s effective fail level determines its exit status. Blocking a merge additionally depends on required-check configuration, current revision binding and bypass permissions.
A check that cannot substantiate the requirement is a reason to revise the evidence plan or seek an authorized product decision. It is not permission for the implementation agent to weaken the requirement. The verification report should expose that unresolved state.