---
title: "capability and op"
url: https://una-lang.org/en/docs/language/capabilities/capability/
release: v0.4.0
edition: "0.1 and later"
source: https://github.com/una-lang/una/blob/v0.4.0/docs/guide/language/capabilities/capability.md
---

# capability and op

## What it does

A capability is unforgeable authority (no code can make one up: a function gets it from its caller, and `main` from the runtime) over something outside the program, such as a store, a clock or a network. `capability C` declares the operations that authority allows, each with `op`: an operation is one action on the outside world, such as reading a key. Code acts outside the program only through an operation of a capability it holds, written `@name.op(...)`. Every such call is an effect (an action outside the program), recorded in the program's trace (the list of effects a run performed, in order).

Learn more: [Your own capabilities and handlers](https://una-lang.org/en/learn/capabilities/your-own-capabilities-and-handlers/). Related pages: [`uses`](https://una-lang.org/en/docs/language/capabilities/uses/), [handlers](https://una-lang.org/en/docs/language/capabilities/handler/) and [`with`](https://una-lang.org/en/docs/language/capabilities/with/).

```una
module shop

pub kind StoreError = | Timeout

pub capability Store
  op get(key: Text) -> Option[Text]
    fails StoreError
  op put(key: Text, value: Text) -> Unit
    fails StoreError

pub read(key: Text) -> Text
  uses @store: Store[get]
  fails StoreError
=
  let found = @store.get(key)
    if error pass
    if none use ""
  found
```

## Forms

In the grammar below, each rule gives a name, `=`, what the name stands for and `;`, quoted words are written as shown, NEWLINE, INDENT and DEDENT stand for a line break and for one more or one less level of indentation, `[ ]` marks an optional part, `{ }` a part that may repeat, `|` separates alternatives, `( )` groups them, and `(* *)` holds a comment.

```ebnf
capability_decl = [ "pub" ] "capability" upper_ident NEWLINE
                  INDENT op_decl { op_decl } DEDENT ;
op_decl         = "op" lower_ident "(" [ params ] ")" "->" type NEWLINE
                  [ INDENT op_clause { op_clause } DEDENT ] ;
op_clause       = "requires" line_expr NEWLINE
                | "ensures" line_expr NEWLINE
                | "fails" upper_ident NEWLINE
                | "accepts" label NEWLINE ;
```

An operation's clauses mean:

| Op clause | Meaning |
| --- | --- |
| `requires p` | Precondition over arguments; an obligation (a fact the checker must prove) at every call site |
| `ensures q` | Postcondition (a promise about the result) over arguments and `result`. It is an assumption about the external system: callers may rely on it, handlers (code that implements the capability in Una) are verified against it, host implementations are trusted to satisfy it |
| `fails E` | The operation may fail with variants of `E` |
| `accepts l` | Upper bound on the labels of arguments (the sink label: how sensitive the data an operation receives may be). Default: `public` |

Operation clauses come in a fixed order: every `requires`, every `ensures`, at most one `fails`, at most one `accepts`.

## Examples

An operation's `ensures` is a fact for its callers. A handler of the capability must keep it, so a handler that cannot is refuted:

```una
-- fails with U5001
module shop

pub capability Store
  op get(key: Text) -> Text
    ensures result.len > 0

handler blank() for Store
  op get(key) = ""
```

A function uses only the operations its `uses` clause lists:

```una
-- fails with U3002
module shop

pub capability Store
  op get(key: Text) -> Text
  op put(key: Text, value: Text) -> Unit

pub save(key: Text) -> Unit
  uses @store: Store[get]
=
  @store.put(key, value: "Desk lamp")
```

## Edge cases

**One name per declaration.** A capability shares the upper-case namespace of kinds and their variants, and a name defined twice in a module is rejected:

```una
-- fails with U1002
module shop

pub kind Store = | Empty

pub capability Store
  op get(key: Text) -> Text
```

Further rules:

- **Assumed, and reported.** Every capability the package declares is listed under `assumptions` in `una report`, with its operations and their `ensures`, since those describe a system outside the program.
- **Sinks.** A sink is a place where data leaves the program. `accepts` bounds the labels of the arguments, so an operation that accepts only `public` cannot receive `secret` data.
- **Host capabilities** such as `Console` and `Files` are declared in the module `std.host` and implemented by the runtime. See [host capabilities and grants](https://una-lang.org/en/docs/language/capabilities/host/).

## Diagnostics

- [U1002](https://una-lang.org/en/docs/errors/U1002/): a capability whose name is already defined in the module.
- [U3002](https://una-lang.org/en/docs/errors/U3002/): an operation that the `uses` clause does not permit.
- [U5001](https://una-lang.org/en/docs/errors/U5001/): a handler operation that does not keep the operation's `ensures`.

## Edition

Capabilities are the same in editions `0.1` and `0.2`. Edition `0.2` adds the host capability `Http`.

## Normative source

- `spec/05 §1`: the model; `spec/05 §2`: declarations; `spec/05 §3`: using capabilities; `spec/05 §5`: handlers.
- `spec/02 §4`: the grammar.
- `spec/07 §4`: sinks; `spec/13 §6`: the build report and its `assumptions`.
- `spec/10 §11` rule 1: the upper-case namespace of kinds, variants and capabilities; rule 5: duplicate names.
- `spec/14 §3`: the host capabilities, and `Http` from edition `0.2`.
