Home / Learn / 13 Limits on authority

Release v0.4.0Edition 0.2, 0.3

13.1 Conditions on operations (edition 0.3)

Page 2 of 9

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), 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). 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":

steps/01-conditions/una.tomltoml
[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 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, 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); and locked contracts (section 13.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 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/01-conditions/src/restock.unacheckrununa
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).
  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, 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:

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

steps/02-condition-forms/src/supply.unacheckrununa
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)
Output
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:

src/restock.unadiff
--- 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
Diagnostic
[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:

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

13.1.7 A condition, a guard or a narrower header

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

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, reorder keeps its guard, if not dry_run, but its header loses the condition:

src/supply.unadiff
--- 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?

Show the answer

No. una check . reports one diagnostic for each call in reorder_pair:

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

Output
    │ 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"

Next:13.2 A ceiling for a module: boundaries