---
title: "18.3 What was proven: obligations, contracts and traces"
url: https://una-lang.org/en/learn/tools/what-was-proven-obligations-contracts-and-traces/
release: v0.4.0
edition: "0.2"
---

# 18.3 What was proven: obligations, contracts and traces

[Section 5.4](https://una-lang.org/en/learn/contracts/what-the-verifier-proves/#s5-4) listed the obligations of a package with `una obligations`, [section 5.5](https://una-lang.org/en/learn/contracts/requirements-rules-from-outside-the-code/#s5-5) followed a requirement to its proof with `una trace`, and [section 6.3](https://una-lang.org/en/learn/functions/what-a-header-says-pub-private-functions-and-inferred-headers/#s6-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](https://una-lang.org/en/learn/contracts/what-the-verifier-proves/#s5-4) explains with its kinds. [Section 8.2](https://una-lang.org/en/learn/choices/when-in-full/#s8-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](https://una-lang.org/en/learn/editions/)), 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](https://una-lang.org/en/learn/contracts/what-the-verifier-proves/#s5-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](https://una-lang.org/en/learn/tools/reading-a-diagnostic/#s18-2) found:

```diff include="steps/09-refuted..steps/08-proven:src/discount.una" context="1" title="src/discount.una"
--- 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:

```una include="steps/08-proven/src/discount.una" title="steps/08-proven/src/discount.una" verified="check, run, test"
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:

```text include="steps/08-proven/expected/commands/obligations.txt"
$ 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:

```text include="steps/08-proven/expected/commands/contract.txt"
$ 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](https://una-lang.org/en/learn/functions/what-a-header-says-pub-private-functions-and-inferred-headers/#s6-3) showed for `uses` and [section 7.2](https://una-lang.org/en/learn/failure/declaring-a-failure-fails-and-fail/#s7-2) for `fails`. For `sale_price`, the contract ends with the requirement it is derived from:

```text include="steps/08-proven/expected/commands/contract-sale.txt"
$ 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:

```text include="steps/08-proven/expected/commands/trace.txt"
$ 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:

```text include="steps/08-proven/expected/commands/contract-json.txt"
$ 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 include="steps/08-proven/expected/commands/obligations-json.txt#L2"
{"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](https://una-lang.org/en/learn/tools/reading-a-diagnostic/#s18-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:

```text include="steps/09-refuted/expected/commands/obligations.txt#L1-L4"
$ 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:

```text include="steps/09-refuted/expected/commands/contract.txt"
$ 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..90` lines 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 .` and `una trace` exit with code 1 when an obligation is not proven, so a script can rely on them.
- **What `una contract` checks.** 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

:::decide
**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:

```diff include="steps/08-proven..steps/15-no-derived:src/discount.una" context="1" title="src/discount.una"
--- 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?

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

```text include="steps/15-no-derived/expected/commands/trace.txt"
$ 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.
:::
