Home / Learn / 18 Tools

Release v0.4.0Edition 0.2

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:

src/discount.unadiff
--- 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:

steps/08-proven/src/discount.unacheckruntestuna
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 OutOfRange

18.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:

Terminal
$ 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..90

Each 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:

Terminal
$ una contract discount.parse_percent
--- A percent typed by a person, such as "30".
parse_percent(raw: Text) -> Percent
  fails PercentError -- inferred

parse_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:

Terminal
$ 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:

Terminal
$ 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 >= cost

A 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:

Terminal
$ 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.

sh
una --json obligations .
json
{"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:

Terminal
$ 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..90

una contract prints the header as before, since a header does not depend on the proofs:

Terminal
$ 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

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:

src/discount.unadiff
--- 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:

Terminal
$ 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

The 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.

Next:18.4 The build report