---
title: "Contracts and proofs"
url: https://una-lang.org/en/docs/guides/contracts-and-proofs/
release: v0.4.0
source: https://github.com/una-lang/una/blob/v0.4.0/docs/guide/una-for-agents.md
---

# Contracts and proofs

`requires` and `ensures` are written in the refinement language: literals, parameters, `result`, fields, `.len`, `+`, `-`, `*` by a literal, `/` and `mod` by a nonzero literal, comparisons, `in`, `is`, `and`, `or`, `not`, `implies` and predicate calls. Every call proves the callee's `requires`, every return proves the `ensures`, every value that flows into a refined type proves the refinement, and every division by a variable proves a nonzero divisor. The solver answers `proven`, `refuted` (U5001, with a counterexample) or `unknown` (U5002).

- The solver knows a call only through its contract. Prelude functions without one, such as `fold`, `sum` and `to_int`, tell it nothing, and refinements are not inferred through generic calls: a `fold` that adds naturals still returns an `Int`.
- `predicate reflect` bodies are in the refinement language; the solver sees their definition. Their integer arithmetic is exact on every type, so fixed-width arithmetic in them has no overflow obligation and an out-of-range literal there is not U2022; their integer types still do not mix (U2001).
- `predicate opaque` bodies may call any pure function; the solver sees only the name, and `checked(value, p(it)) else fail V` establishes one at run time. Each `checked` counts against the module's escape budget.

```una
module demo

pub kind Member
  name: Text
  holding: Int in 0..3

pub predicate reflect can_check_out(m: Member) -> Bool = m.holding < 3

pub check_out(m: Member) -> Member
  requires can_check_out(m)
  ensures result.holding == m.holding + 1
=
  Member(name: m.name, holding: m.holding + 1)

--- A caller proves the precondition: here, from the literal.
pub first_checkout() -> Member = check_out(Member(name: "Ana", holding: 0))
```

A false contract is refuted, with the path and the values that break it:

```una
-- fails with U5001
module demo

pub double(x: Int) -> Int
  ensures result > x
=
  x * 2
```

```json
{
  "schema": "una.diagnostics/1",
  "diagnostics": [
    {
      "schema": "una.diagnostic/1",
      "code": "U5001",
      "severity": "error",
      "domain": "verification",
      "message": "postcondition of `double` is refuted",
      "primary": { "file": "double.una", "start": { "line": 6, "col": 3 }, "end": { "line": 6, "col": 8 } },
      "related": [
        { "file": "double.una", "start": { "line": 4, "col": 11 }, "end": { "line": 4, "col": 21 }, "message": "ensures clause" }
      ],
      "obligation": { "id": "ob-17058da2cfca", "kind": "postcondition", "goal": "result > x", "status": "refuted" },
      "counterexample": { "bindings": [ { "name": "result", "value": 0 }, { "name": "x", "value": 0 } ] },
      "repairs": [
        { "rank": 1, "escape_cost": 0, "description": "add a guard or an arm so that the failing path returns a value for which `result > x` holds", "edit": null },
        { "rank": 2, "escape_cost": 0, "description": "adjust the `ensures` clause", "edit": null }
      ],
      "explain": "una explain U5001"
    }
  ]
}
```

The counterexample's values are the solver's, not data from a run. When the solver refutes an obligation but gives no values, the counterexample has no bindings and an `unavailable` key with the solver's message, printed as `counterexample: not available (...)`: the obligation is still refuted, and the message points at a defect of the compiler, worth reporting. A binding whose declared type is labeled, such as `pin: secret Int`, also carries `"label": "secret"`; its value is still shown, since it is hypothetical. In `una test`, a package of edition `0.2` shows an example's result and failure reason with every field, since example data come from the source; edition `0.1` redacts labeled fields there, and the document's `redacted` key says which rule applies. Traces are redacted in both.

A package that establishes an opaque fact once, at its boundary, and declares the budget for it:

`una.toml`
```toml
[package]
name = "slugs"
version = "0.1.0"
edition = "0.2"

[escape_budget]
checked_per_module = 1
```

`src/slugs.una`
```una
module slugs

pub kind Slug = Text where valid_slug(it)

pub kind SlugError = | Malformed

pub predicate opaque valid_slug(t: Text) -> Bool = t.len >= 3 and not starts_with(t, prefix: "-")

--- The only way to obtain a Slug from untrusted text.
pub parse_slug(raw: Text) -> Slug
  fails SlugError
=
  checked(trim(raw), valid_slug(it)) else fail Malformed

example "a slug with a leading dash is rejected"
  do parse_slug("-x")
  expect fails Malformed
```
