---
title: "13.1 Conditions on operations (edition 0.3)"
url: https://una-lang.org/en/learn/authority/conditions-on-operations-edition-0-3/
release: v0.4.0
edition: "0.2, 0.3"
---

# 13.1 Conditions on operations (edition 0.3)

## 13.1.1 What a condition on an operation is

A store gives a new employee a key to the stockroom, with one rule: during a fire drill, nobody takes stock out. The key says what the employee may open; the rule says when. A **condition on an operation** is such a rule, written in the header. `uses @supplier: Supplier[order where not dry_run]` says that the function may place an order, and only on a call where `dry_run` is false.

The verifier, the part of `una` that proves facts about your code before it runs ([chapter 5](https://una-lang.org/en/learn/contracts/preconditions-requires/#s5-1)), then proves the rule: at every place where the order can be placed, it shows that `dry_run` is false there. A function that could place an order during a dry run does not check.

## 13.1.2 Edition 0.3: a preview, chosen in `una.toml`

An **edition** is the version of the Una language that a package is written in, named by the line `edition` in the `[package]` table of `una.toml` ([chapter 1](https://una-lang.org/en/learn/hello/your-first-program-hello-world/#making-the-package)). Every chapter before this one uses edition `0.2`. Conditions on operations, boundaries and locks exist only in edition `0.3`. Every package of this chapter opts in with one line, `edition = "0.3"`:

```toml include="steps/01-conditions/una.toml" title="steps/01-conditions/una.toml"
[package]
name = "restock"
version = "0.1.0"
edition = "0.3"

[run]
entry = "restock"
grants = ["console"]
```

Edition `0.3` is a **preview** until every rule planned for it has landed. Until then, a later release of `una` may add obligations or errors to a package of edition `0.3`, so a package that checks today may need a change after an update. The edition only gets stricter, and stricter concerns the programs that edition `0.2` can express: such a program keeps its result, or gains an obligation or an error. A later release may also accept a new construct that earlier releases reject as a syntax error, such as the condition on an operation of this section, but only a construct that narrows what a program may do: without it, the program is one that edition `0.2` accepts, with no fewer allowed behaviors. It may also accept refined type arguments, a refined kind inside the brackets of another type such as `List[Percent]`, which edition `0.2` rejects. Editions `0.1` and `0.2` are stable: a later release does not change what they accept, except to fix a security or soundness error. Edition `0.3` has every rule of edition `0.2`, so all you learned so far still holds, with one word changed: the declaration that [chapter 1](https://una-lang.org/en/learn/hello/testing-it/#s1-7) writes `example` is written `test` in edition `0.3`, with the same `given`, `do` and `expect` lines and the same meaning. An `example` in an edition `0.3` package is U0103, and `una fix .` rewrites the word. Besides this chapter, only some packages of [chapter 19, Editions](https://una-lang.org/en/learn/editions/), use edition `0.3`; every other chapter of this book stays on `0.2`.

Edition `0.3` adds three things to authority, one per section of this chapter: conditions on operations, here; boundaries, with a narrower kind of rebinding, `with @x = @y[ops]` ([section 13.2](https://una-lang.org/en/learn/authority/a-ceiling-for-a-module-boundaries/#s13-2)); and locked contracts ([section 13.3](https://una-lang.org/en/learn/authority/locking-a-contract-contracts/#s13-3)).

## 13.1.3 Why an operation needs a condition

A function often has a mode in which it must not act: a dry run, a preview, a rehearsal. Without a condition, the header of a restock function says only `Supplier[order]`, and the rule "never order in a dry run" lives in the body. A reader must read every branch to know that the rule holds, and so must every reader after the next edit. A condition moves the rule to the header, and the verifier checks the body against it.

Each example of this chapter is a package of its own, as [chapter 2](https://una-lang.org/en/learn/numbers/values-types-and-names-let/#each-step-is-a-package) explains.

## 13.1.4 How to write a condition

After an operation's name, in the brackets of `uses`, write `where` and a condition. The restock step lets `reorder` place an order only when `dry_run` is false:

:::steps
```una include="steps/01-conditions/src/restock.una" title="steps/01-conditions/src/restock.una" verified="check, run"
module restock

--- The supplier's ordering service.
capability Supplier
  op order(sku: Text, units: Int) -> Unit

--- Reorders a SKU that runs low. A dry run only says what it would order.
reorder(sku: Text, left: Int, dry_run: Bool) -> Unit
  uses @supplier: Supplier[order where not dry_run]
  uses @console: Console[print]
=
  if left >= 5
    unit
  else if dry_run
    @console.print("would order 20 x {sku}")
  else
    @supplier.order(sku, units: 20)

--- A supplier on a developer's machine: it prints each order instead of placing it.
handler printed() for Supplier
  uses @console: Console[print]
  op order(sku, units) = @console.print("ordered {units} x {sku}")

pub main() -> Unit
  uses @console: Console[print]
=
  reorder("LAMP-01", left: 2, dry_run: true) with @supplier = printed()
  reorder("LAMP-01", left: 2, dry_run: false) with @supplier = printed()
  reorder("DESK-02", left: 9, dry_run: false) with @supplier = printed()
```

1. **`capability Supplier`.** A capability of the package, with one operation, `order` ([chapter 12](https://una-lang.org/en/learn/capabilities/your-own-capabilities-and-handlers/#s12-3)).
2. **`uses @supplier: Supplier[order where not dry_run]`.** The operation `order`, then `where`, then the condition `not dry_run`. The condition is a `Bool` over the function's parameters, written in the refinement language of [chapter 5](https://una-lang.org/en/learn/contracts/refined-kinds-and-predicates/#the-refinement-language), like a `requires` clause.
3. **`if left >= 5` … `else if dry_run` … `else`.** The body. In the `else` branch, which places the order, the verifier knows that `dry_run` is false, which is the condition.
4. **`handler printed()`.** A supplier for a developer's machine: it prints each order instead of placing it.
:::

`una run .` prints:

```text include="steps/01-conditions/expected/output.txt"
would order 20 x LAMP-01
ordered 20 x LAMP-01
```

The first call is a dry run, so it only prints what it would order. The second places the order. The third finds enough stock and does nothing.

## 13.1.5 Every form of a condition

The step `02-condition-forms` has one function for each form, and a `main` that calls them:

```una include="steps/02-condition-forms/src/supply.una" title="steps/02-condition-forms/src/supply.una" verified="check, run"
module supply

--- The supplier's service. A quote costs nothing; an order buys the units.
capability Supplier
  op quote(sku: Text, units: Int) -> Int
  op order(sku: Text, units: Int) -> Unit

--- One operation with a condition: an order only where `dry_run` is false.
reorder(sku: Text, units: Int, dry_run: Bool) -> Unit
  uses @supplier: Supplier[order where not dry_run]
=
  if not dry_run
    @supplier.order(sku, units)

--- Two operations: `quote` has no condition, and the condition on `order` has two parts.
restock(sku: Text, units: Int, dry_run: Bool) -> Int
  uses @supplier: Supplier[quote, order where not dry_run and units <= 50]
=
  let cost = @supplier.quote(sku, units)
  if not dry_run and units <= 50
    @supplier.order(sku, units)
  cost

--- A call is checked too: `reorder` may order only where `not dry_run` holds, and so may this
--- function.
reorder_pair(first: Text, second: Text, dry_run: Bool) -> Unit
  uses @supplier: Supplier[order where not dry_run]
=
  reorder(first, units: 10, dry_run)
  reorder(second, units: 10, dry_run)

--- A supplier on a developer's machine: it quotes 250 cents a unit, and prints each order
--- unless it is `quiet`. A handler's `uses` may carry a condition too.
handler printed(quiet: Bool) for Supplier
  uses @console: Console[print where not quiet]
  op quote(sku, units) = units * 250
  op order(sku, units) =
    if not quiet
      @console.print("ordered {units} x {sku}")

pub main() -> Unit
  uses @console: Console[print]
=
  reorder("LAMP-01", units: 20, dry_run: true) with @supplier = printed(quiet: false)
  reorder("LAMP-01", units: 20, dry_run: false) with @supplier = printed(quiet: false)
  let small = restock("DESK-02", units: 5, dry_run: false) with @supplier = printed(quiet: false)
  @console.print("5 desks cost {small}")
  let large = restock("RUG-07", units: 80, dry_run: false) with @supplier = printed(quiet: false)
  @console.print("80 rugs would cost {large}, too many to order at once")
  reorder_pair("CHAIR-09", second: "SHELF-04", dry_run: false) with @supplier = printed(quiet: false)
  reorder("CHAIR-09", units: 10, dry_run: false) with @supplier = printed(quiet: true)
```

```text include="steps/02-condition-forms/expected/output.txt"
ordered 20 x LAMP-01
ordered 5 x DESK-02
5 desks cost 1250
80 rugs would cost 20000, too many to order at once
ordered 10 x CHAIR-09
ordered 10 x SHELF-04
```

### 13.1.5.1 One operation with a condition

`reorder` lists one operation, `order`, with the condition `not dry_run`, and guards the order with `if not dry_run`. Its first call, a dry run, prints nothing.

### 13.1.5.2 Operations with and without a condition

`restock` lists two operations in one pair of brackets, separated by a comma: `quote`, with no condition, and `order`, with one. An operation without `where` may run on every call, so `restock` asks for a quote even in a dry run.

### 13.1.5.3 A condition of several parts

A condition is any `Bool` of the refinement language over the parameters: `not dry_run and units <= 50` lets `restock` order only outside a dry run, and at most 50 units at once. The rugs ask for 80, so `restock` gives back the quote and orders nothing.

### 13.1.5.4 A call of a function with a condition

`reorder_pair` calls `reorder` twice, and holds the same condition. A call is checked as an operation is: `reorder` may order where `not dry_run` holds of the arguments it receives, and `reorder_pair` passes its own `dry_run`, so the condition of `reorder_pair` covers each call.

### 13.1.5.5 A condition in a handler's `uses`

A handler's `uses` may carry a condition too, over the handler's own parameters. `printed(quiet: Bool)` may print only where `quiet` is false, and its `order` guards the print. The last call of `main` installs a quiet supplier, so its order prints nothing.

## 13.1.6 How a condition is checked

### 13.1.6.1 At every operation

The verifier proves the condition at every place where the operation can run. Take the dry-run branch out of the restock of [How to write a condition](#how-to-write-a-condition):

```diff include="steps/01-conditions..steps/03-unguarded:src/restock.una" context="1" title="src/restock.una"
--- a/src/restock.una
+++ b/src/restock.una
@@ -13,4 +13,2 @@
     unit
-  else if dry_run
-    @console.print("would order 20 x {sku}")
   else
```

```text include="steps/03-unguarded/expected/rendered.txt"
[U5001] Error: `@supplier.order` may run where `not dry_run` is not proven
    ╭─[ src/restock.una:15:5 ]
    │
  9 │   uses @supplier: Supplier[order where not dry_run]
    │                                        ─────┬─────
    │                                             ╰─────── condition
    │
 15 │     @supplier.order(sku, units: 20)
    │     ───────────────┬───────────────
    │                    ╰───────────────── `@supplier.order` may run where `not dry_run` is not proven
    │
    │ Help 1: repair 1: guard the operation with `if not dry_run`
    │
    │ Help 2: repair 2: add `requires not dry_run` to the enclosing function; its callers then prove it
    │
    │ Note 1: obligation ob-c36fd10895b1 (effect_condition) is refuted: not dry_run
    │
    │ Note 2: counterexample: dry_run = true, left = 4
    │
    │ Note 3: run `una explain U5001` for an explanation
────╯
```

Read it as any diagnostic of the verifier:

- The first line names the operation and the condition: `@supplier.order` may run where `not dry_run` is not proven.
- The marks point at two places: the condition in the header, labeled `condition`, and the operation that may break it.
- The counterexample, `dry_run = true, left = 4`, is a call where it goes wrong: a dry run with 4 units left, few enough to order.
- The first repair guards the operation with `if not dry_run`. The second adds `requires not dry_run`, which would forbid dry runs altogether: callers would then have to prove that `dry_run` is false.

### 13.1.6.2 At every call

A call of a function that may perform the operation is such a place too. The verifier reads the callee's header there: the callee's condition, at the call's arguments, must imply the caller's. A callee without a condition on the operation may perform it on every call, so its call needs a guard. [Check yourself: conditions](#check-yourself-conditions) shows what happens when a callee's header drops its condition.

### 13.1.6.3 At every handler you install

A handler installed inside the function, as `with @restock = via_supplier()`, counts as a call too. When the handler's own `uses` list the operation, the handler's condition must imply the function's, and the check is charged at the `with`. A handler whose `uses` list `Supplier[order]` with no condition may order on every call, so a function that holds `Supplier[order where not dry_run]` and installs it gets U5001 at the `with`. The diagnostic's first repair writes the condition in the `uses` of the handler; the second guards the `with` with `if not dry_run`.

### 13.1.6.4 For the whole call

A condition reads the arguments the caller passed, so its value is fixed for the whole call.

### 13.1.6.5 Never inferred

A private function without `uses` gets its `uses` inferred from its body ([chapter 6](https://una-lang.org/en/learn/functions/what-a-header-says-pub-private-functions-and-inferred-headers/#s6-3)), and an inferred `uses` has no condition on any operation. A condition exists only where a header writes it.

### 13.1.6.6 Not a function value

A function can usually be passed to another function as an argument ([chapter 10](https://una-lang.org/en/learn/collections/functions-as-values-and-lambdas/#s10-2)). A function whose `uses` carry a condition cannot: the function that receives it could not prove the condition, so using its name as a value is U3006. A lambda that calls it can be passed, as any lambda can.

### 13.1.6.7 Only in edition 0.3

In editions `0.1` and `0.2`, `where` inside the brackets of `uses` is a syntax error, U0101, as [A condition in an edition 0.2 package](https://una-lang.org/en/learn/authority/common-mistakes/#a-condition-in-an-edition-02-package-u0101) shows.

## 13.1.7 A condition, a guard or a narrower header

:::decide
**Which to use:**

| You want… | Use |
| --- | --- |
| A function that may perform an operation only on some calls, such as never in a dry run | A condition: `op where …` in its `uses` |
| A function that never performs an operation | Leave the operation out of its `uses` |
| To skip an operation on some calls, with no promise to callers | A guard, `if …`, in the body |
| A function that must never be called in some case at all | `requires`, as in [chapter 5](https://una-lang.org/en/learn/contracts/preconditions-requires/#s5-1) |
:::

A guard alone keeps the body right today; a condition makes the rule part of the header, so the next edit of the body is checked against it too.

## 13.1.8 Check yourself: conditions

In the step of [Every form of a condition](#every-form-of-a-condition), `reorder` keeps its guard, `if not dry_run`, but its header loses the condition:

```diff include="steps/02-condition-forms..steps/04-header-not-body:src/supply.una" context="1" title="src/supply.una"
--- a/src/supply.una
+++ b/src/supply.una
@@ -7,5 +7,5 @@
 
---- One operation with a condition: an order only where `dry_run` is false.
+--- Orders only where `dry_run` is false, but its header no longer says so.
 reorder(sku: Text, units: Int, dry_run: Bool) -> Unit
-  uses @supplier: Supplier[order where not dry_run]
+  uses @supplier: Supplier[order]
 =
```

`reorder_pair` is unchanged. Does the package check?

:::answer Show the answer
No. `una check .` reports one diagnostic for each call in `reorder_pair`:

```text include="steps/04-header-not-body/expected/diagnostics.txt"
error U5001 at src/supply.una:29:3: `@supplier.order` may run where `not dry_run` is not proven
  counterexample: dry_run = true
error U5001 at src/supply.una:30:3: `@supplier.order` may run where `not dry_run` is not proven
  counterexample: dry_run = true
```

The verifier checks a call against the callee's header, not its body. The header of `reorder` now lets it order on every call, so at each call in `reorder_pair` the condition `not dry_run` is not proven, and `dry_run = true` refutes it. The first repair writes the condition back into the `uses` of `reorder`, and since `reorder` is private and in the same module, `una fix .` can make that edit:

```text include="steps/04-header-not-body/expected/rendered.txt#L12"
    │ Help 1: repair 1: write the condition in the `uses` of `reorder`, as `order where ...`: `not dry_run` with each parameter of this function replaced by the parameter of `reorder` it is passed as; `reorder` then proves it where it runs `order`; edit src/supply.una:10:33..10:33 to " where not dry_run"
```
:::
