Home / Docs / Guides

Contracts and proofs

Release v0.4.0

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

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.tomltoml
[package]
name = "slugs"
version = "0.1.0"
edition = "0.2"

[escape_budget]
checked_per_module = 1
src/slugs.unauna
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