18.3 What was proven: obligations, contracts and traces
Page 4 of 11
Section 5.4 listed the obligations of a package with una obligations, section 5.5 followed a requirement to its proof with una trace, and section 6.3 read a whole header with una contract. This section uses the three together on one package, as a reviewer does, and adds what those sections left out: their JSON forms, what they print for a package that does not check, and how they behave in a script.
18.3.1 What a proof obligation is
A proof obligation is one fact that the verifier must prove before the package checks, and its status is proven, refuted or unknown, as section 5.4 explains with its kinds. Section 8.2 adds exhaustive, for a when over numbers without else. Two more kinds, effect_condition and contract_lock, exist only in edition 0.3. The edition is the version of the Una language that a package's una.toml names (chapter 19), and this chapter's packages are on edition 0.2.
18.3.2 Why you list what was proven
A package that checks clean prints nothing, so a reviewer needs the list itself, as section 5.4 showed. A review asks three questions of a package at once: which facts did the verifier prove, and where? What does each function promise, including what nobody wrote down? Which code carries the rule "a sale price is never below cost"? The three commands answer them, from the same proofs.
18.3.3 From promises to obligations
This step is the fixed sale price. The fix is the one word that section 18.2 found:
--- a/src/discount.una
+++ b/src/discount.una
@@ -23,3 +23,3 @@
let discounted = price - price * off / 100
- if discounted < cost then price else discounted
+ if discounted < cost then cost else discounted
The whole package, which checks clean:
module discount
requirement PRICING_1
text "A sale price is never below what the store paid for the product"
source human
owner pricing
status active
--- An amount of money in cents, never negative.
pub kind Cents = Int where it >= 0
--- A discount in percent, from 0 to 90.
pub kind Percent = Int in 0..90
--- Why a typed percent was rejected.
kind PercentError = NotANumber(raw: Text) | OutOfRange(value: Int)
--- The price after `off` percent, never below `cost`.
pub sale_price(price: Cents, cost: Cents, off: Percent) -> Cents
ensures result >= cost
derived from PRICING_1
=
let discounted = price - price * off / 100
if discounted < cost then cost else discounted
--- A percent typed by a person, such as "30".
parse_percent(raw: Text) -> Percent
=
let n = raw.trim.to_int()
if none fail NotANumber(raw)
if n < 0 or n > 90
fail OutOfRange(value: n)
else
n
pub main() -> Unit
uses @console: Console[print]
=
let off = parse_percent(" 30")
if error use 0
let lamp = sale_price(1990, cost: 1200, off: off)
let desk = sale_price(12900, cost: 11000, off: off)
@console.print("LAMP-01 {lamp}, DESK-02 {desk}")
example "30 percent off a lamp"
do sale_price(1990, cost: 1200, off: 30)
expect result == 1393
example "a typed percent above 90 is OutOfRange"
do parse_percent("95")
expect fails OutOfRange18.3.4 How to write the three commands
18.3.4.1 Every obligation and its status: una obligations .
una obligations . checks the package and lists every obligation with its status, proven or not:
$ una obligations .
proven ob-a1f2aa4dc27a refinement src/discount.una:19:5 result >= 0
proven ob-8a05af02a5f7 postcondition src/discount.una:20:11 result >= cost
proven ob-ab12d15138b8 refinement src/discount.una:27:1 result in 0..90
proven ob-973036ad50b4 refinement src/discount.una:41:25 1990 >= 0
proven ob-d4bc9c2cf5f2 refinement src/discount.una:41:37 1200 >= 0
proven ob-a1fc2815567e refinement src/discount.una:41:48 off in 0..90
proven ob-f4b448300879 refinement src/discount.una:42:25 12900 >= 0
proven ob-118790a80d6d refinement src/discount.una:42:38 11000 >= 0
proven ob-a1fc2815567e refinement src/discount.una:42:50 off in 0..90
proven ob-5b991b13fcbf refinement src/discount.una:46:17 1990 >= 0
proven ob-44bcd7b237f7 refinement src/discount.una:46:29 1200 >= 0
proven ob-effe966d12dd refinement src/discount.una:46:40 30 in 0..90Each line has five columns: the status, the identifier, the kind, the place and the goal. Most lines are refinement: each literal passed as Cents must be at least 0, and each off passed as Percent must be in 0..90. The line at 19:5 is the result of sale_price, which must be a Cents, and the line at 27:1 is the result of parse_percent, which must be a Percent. One ensures gives one postcondition line.
This listing is a first run. Run it again, or after una check ., and each line ends with (cached), and the report counts them under cached.
18.3.4.2 A function's full header: una contract <module.function>
una contract prints a function's full header, as a caller relies on it, with its doc comments. The function is named by its module and its name. For a private function it shows what the checker inferred:
$ una contract discount.parse_percent
--- A percent typed by a person, such as "30".
parse_percent(raw: Text) -> Percent
fails PercentError -- inferredparse_percent declares no fails clause, and the contract shows the one the checker inferred, marked -- inferred, as section 6.3 showed for uses and section 7.2 for fails. For sale_price, the contract ends with the requirement it is derived from:
$ una contract discount.sale_price
--- The price after `off` percent, never below `cost`.
pub sale_price(price: Cents, cost: Cents, off: Percent) -> Cents
ensures result >= cost
derived from PRICING_1
-- requirement PRICING_1 (active): "A sale price is never below what the store paid for the product"18.3.4.3 From a requirement to the code: una trace <REQUIREMENT>
una trace goes the other way, from a requirement to the code. It prints the requirement, every function derived from it with the clauses that carry it, and the obligations that prove them:
$ una trace PRICING_1
requirement PRICING_1 (active)
text "A sale price is never below what the store paid for the product"
source human
owner pricing
discount.sale_price
ensures result >= cost
proven ob-a1f2aa4dc27a refinement result >= 0
proven ob-8a05af02a5f7 postcondition result >= costA reviewer who asks "where is this rule enforced, and is it proven?" gets the answer from one command.
18.3.4.4 The same, as JSON
Each of the three takes --json. The contract of parse_percent, as data:
$ una --json contract discount.parse_percent
{"schema":"una.contract/1","function":"discount.parse_percent","public":false,"docs":["A percent typed by a person, such as \"30\"."],"header":"parse_percent(raw: Text) -> Percent","constraints":[],"result_labels":[],"of_raises":[],"requires":[],"ensures":[],"uses":[],"fails":{"kind":"PercentError","inferred":true},"diverges":false,"derived_from":[]}Each clause is a key, and each inferred part says so: "inferred":true on fails. una --json obligations . gives each obligation its hypotheses too, the facts the solver could assume at that place, such as price >= 0 from the type of price. When a goal cannot be proven, the hypotheses show what the verifier knew, and so what is missing.
una --json obligations .{"schema":"una.obligations/1","obligations":[{"id":"ob-a1f2aa4dc27a","kind":"refinement","domain":"semantic","status":"proven","source":{"file":"src/discount.una","start":{"line":19,"col":5},"end":{"line":19,"col":15}},"declaration":"discount.sale_price","goal":"result >= 0","hypotheses":["price >= 0","cost >= 0","0 <= off","off <= 90"],"cached":false},{"id":"ob-8a05af02a5f7","kind":"postcondition","domain":"semantic","status":"proven","source":{"file":"src/discount.una","start":{"line":20,"col":11},"end":{"line":20,"col":25}},"declaration":"discount.sale_price","goal":"result >= cost","hypotheses":["price >= 0","cost >= 0","0 <= off","off <= 90"],"cached":false},{"id":"ob-ab12d15138b8","kind":"refinement","domain":"semantic","status":"proven","source":{"file":"src/discount.una","start":{"line":27,"col":1},"end":{"line":27,"col":14}},"declaration":"discount.parse_percent","goal":"result in 0..90","hypotheses":[],"cached":false},{"id":"ob-973036ad50b4","kind":"refinement","domain":"semantic","status":"proven","source":{"file":"src/discount.una","start":{"line":41,"col":25},"end":{"line":41,"col":29}},"declaration":"discount.main","goal":"1990 >= 0","hypotheses":[],"cached":false},{"id":"ob-d4bc9c2cf5f2","kind":"refinement","domain":"semantic","status":"proven","source":{"file":"src/discount.una","start":{"line":41,"col":37},"end":{"line":41,"col":41}},"declaration":"discount.main","goal":"1200 >= 0","hypotheses":[],"cached":false},{"id":"ob-a1fc2815567e","kind":"refinement","domain":"semantic","status":"proven","source":{"file":"src/discount.una","start":{"line":41,"col":48},"end":{"line":41,"col":51}},"declaration":"discount.main","goal":"off in 0..90","hypotheses":[],"cached":false},{"id":"ob-f4b448300879","kind":"refinement","domain":"semantic","status":"proven","source":{"file":"src/discount.una","start":{"line":42,"col":25},"end":{"line":42,"col":30}},"declaration":"discount.main","goal":"12900 >= 0","hypotheses":["lamp >= 0","lamp >= 1200"],"cached":false},{"id":"ob-118790a80d6d","kind":"refinement","domain":"semantic","status":"proven","source":{"file":"src/discount.una","start":{"line":42,"col":38},"end":{"line":42,"col":43}},"declaration":"discount.main","goal":"11000 >= 0","hypotheses":["lamp >= 0","lamp >= 1200"],"cached":false},{"id":"ob-a1fc2815567e","kind":"refinement","domain":"semantic","status":"proven","source":{"file":"src/discount.una","start":{"line":42,"col":50},"end":{"line":42,"col":53}},"declaration":"discount.main","goal":"off in 0..90","hypotheses":["lamp >= 0","lamp >= 1200"],"cached":false},{"id":"ob-5b991b13fcbf","kind":"refinement","domain":"semantic","status":"proven","source":{"file":"src/discount.una","start":{"line":46,"col":17},"end":{"line":46,"col":21}},"declaration":"discount.example \"30 percent off a lamp\"","goal":"1990 >= 0","hypotheses":[],"cached":false},{"id":"ob-44bcd7b237f7","kind":"refinement","domain":"semantic","status":"proven","source":{"file":"src/discount.una","start":{"line":46,"col":29},"end":{"line":46,"col":33}},"declaration":"discount.example \"30 percent off a lamp\"","goal":"1200 >= 0","hypotheses":[],"cached":false},{"id":"ob-effe966d12dd","kind":"refinement","domain":"semantic","status":"proven","source":{"file":"src/discount.una","start":{"line":46,"col":40},"end":{"line":46,"col":42}},"declaration":"discount.example \"30 percent off a lamp\"","goal":"30 in 0..90","hypotheses":[],"cached":false}]}18.3.5 A refuted proof in the listings
On the package of section 18.2, with the wrong word, the same commands still answer. una obligations . lists the refuted obligation among the proven ones, by the identifier the diagnostic printed in its Note 1, and exits with code 1:
$ una obligations .
proven ob-a1f2aa4dc27a refinement src/discount.una:19:5 result >= 0
refuted ob-8a05af02a5f7 postcondition src/discount.una:20:11 result >= cost
proven ob-ab12d15138b8 refinement src/discount.una:27:1 result in 0..90una contract prints the header as before, since a header does not depend on the proofs:
$ una contract discount.sale_price
--- The price after `off` percent, never below `cost`.
pub sale_price(price: Cents, cost: Cents, off: Percent) -> Cents
ensures result >= cost
derived from PRICING_1
-- requirement PRICING_1 (active): "A sale price is never below what the store paid for the product"18.3.6 How the three commands behave
- Names. A function is named by its module and its name,
discount.sale_price. A requirement is named by its identifier,PRICING_1. - Identifiers. An obligation's identifier is computed from its declaration, its kind and its goal. It survives edits elsewhere in the file, and two identical obligations in one function share one, as the two
off in 0..90lines do. - The proof cache. una keeps proven results in the package's proof cache,
.una/cache/. After a first check, a result that came from the cache is marked(cached). - Exit codes.
una obligations .anduna traceexit with code 1 when an obligation is not proven, so a script can rely on them. - What
una contractchecks. Only tier 0. When the package has a tier 0 error, such as a type error, it prints the diagnostics instead of the header and exits with code 1. An unknown name is a usage error, code 2.
18.3.7 Obligations, contract or trace
Which to use:
| You want to know… | Use |
|---|---|
| Everything the verifier proved, and what it did not | una obligations . |
| What a function promises and may do, written or inferred | una contract <module.function> |
| Where a requirement is enforced, and whether it is proven | una trace <REQUIREMENT> |
| Why a goal failed | The diagnostic, then una --json obligations . for its hypotheses |
18.3.8 Check yourself: a requirement with nothing derived from it
Remove the derived from line from sale_price, and keep the requirement:
--- a/src/discount.una
+++ b/src/discount.una
@@ -20,3 +20,2 @@
ensures result >= cost
- derived from PRICING_1
=Does the package still check? What does una trace PRICING_1 print?
Show the answer
It checks and runs as before: derived from is a link for the reader and the tools, and the proof of ensures does not need it. But the trace has nothing to follow:
$ una trace PRICING_1
requirement PRICING_1 (active)
text "A sale price is never below what the store paid for the product"
source human
owner pricingThe requirement is printed, and no function under it. A requirement that no function is derived from is a rule nobody has shown to be enforced: a reviewer reads the empty trace as a gap.