---
title: "Capabilities and effects"
url: https://una-lang.org/en/docs/language/capabilities/
release: v0.4.0
source: https://github.com/una-lang/una/blob/v0.4.0/docs/guide/syntax-reference.md
---

# Capabilities and effects

## 7.1 Declaring capabilities

A capability describes authority over something outside the program. Its operations are signatures, which are assumptions about the external system.

```una
module demo

pub kind Availability = SoldOut | Few | Open

pub kind Registration
  name: Text
  status: Availability

pub kind StoreError = Timeout | Corrupted

pub capability Registrations
  op find(key: internal Hashed) -> Option[Registration]
    fails StoreError
    accepts internal

pub capability Audit
  op record(key: internal Hashed, status: Availability) -> Unit
    fails StoreError
    accepts internal
```

| Op clause | Meaning |
| --- | --- |
| `requires p` | precondition on arguments, proven at each call |
| `ensures q` | postcondition: an assumption callers may rely on; handlers are verified against it |
| `fails E` | the operation may fail with `E` |
| `accepts l` | the most sensitive label its arguments may carry (default `public`) |

Canonical op clause order: every `requires`, every `ensures`, then at most one `fails` and at most one `accepts` (U0102). Operations cannot declare `edit` or `take` parameters (U2020).

## 7.2 Using capabilities

```una
module demo

pub kind Availability = SoldOut | Few | Open

pub kind Registration
  name: Text
  status: Availability

pub kind StoreError = Timeout | Corrupted

pub kind CheckInError = NotRegistered | Unavailable

pub capability Registrations
  op find(key: internal Hashed) -> Option[Registration]
    fails StoreError
    accepts internal

pub capability Audit
  op record(key: internal Hashed, status: Availability) -> Unit
    fails StoreError
    accepts internal

pub check_in(key: internal Hashed) -> Availability
  uses @registrations: Registrations[find]
  uses @audit: Audit[record]
  fails CheckInError
=
  let registration = @registrations.find(key)
    if error fail Unavailable
    if none fail NotRegistered
  @audit.record(key, status: registration.status)
    if error fail Unavailable
  registration.status
```

- `uses @x: C[ops]` grants operations `ops` of capability `C` under the name `@x`. Omitting `[ops]` grants all of them.
- `@x.op(args)` works only if `@x` is in scope (U3001) and `op` is granted (U3002).

## 7.3 Passing capabilities: by name, downward only

A callee whose header says `uses @x: C[ops]` receives the caller's `@x` automatically. The caller must hold `@x` with at least those operations (U3001, U3002). Holding more is fine: the callee is limited to what it declares, so passing a capability attenuates it.

## 7.4 `with`: rebinding and handler instances

```una
module demo

pub kind Registration
  name: Text

pub capability Registrations
  op find(key: Text) -> Option[Registration]

handler in_memory(rows: List[Registration]) for Registrations
  op find(key) = rows.first()

handler none_found() for Registrations
  op find(key) = None

known(key: Text) -> Bool
  uses @registrations: Registrations[find]
=
  let found = @registrations.find(key)
  found.is_some()

pub check(key: Text, rows: List[Registration]) -> Bool
  uses @primary_store: Registrations[find]
=
  let in_store = known(key) with @registrations = @primary_store
  let in_rows = known(key) with @registrations = in_memory(rows: rows)
  let nowhere = known(key) with @registrations = none_found()
  in_store or in_rows or nowhere
```

- **`@x = @y`** makes the callee's `@x` the caller's `@y`. Both must be the same capability.
- **`@x = h(args)`** installs handler `h` as `@x`. The handler's own `uses` become effects of the caller. What happens when the caller lacks them depends on the caller:
  - a `pub` caller that does not declare them gets U3003 at the statement: "handler `h` uses `@inner: Inner[ping]`, but this code declares no `uses`, so its effects would exceed its header";
  - a private caller has them inferred, and the error appears where the capability is really missing. In an example, for instance, it is U3001: "`g` needs `@inner: Inner[ping]`, which no `given` line binds".
- **Scope:** the binding covers only that statement's expression.
- **Statements only.** `with` is part of a statement, so it cannot appear in the short function form: `g() -> Unit = f() with @a = h()` is U0101. Use the long form, with the statement in the body.
- **Several bindings** are separated by commas: `with @a = @b, @c = h()`.

## 7.5 Handlers

A handler implements a capability in Una. `in_memory` and `none_found` above are handlers:

- **Complete and matching.** A handler implements every operation (U3011), with the right parameter count (U3010). Types come from the capability declaration.
- **Ordinary code.** Operation bodies are type-checked, flow-checked and verified against the operation's `ensures`. They may fail only with the operation's error kind.
- **Parameters** (`rows` above) are captured values.
- **Own authority.** A handler may declare its own `uses` before its operations.
- **Not values.** Handlers are installed only through `with` or `given`.

## 7.6 The second-class rule

Capability references are **not values**. `@x` cannot be:

- bound with `let`;
- passed as an ordinary argument;
- returned;
- stored in a kind;
- compared or interpolated.

Any of these is U3005. A bare `@x` is allowed only on either side of a `with` binding or in `given`. Effectful or fallible lambdas follow the same restrictions, except that they can be passed as arguments (U3006). Such a lambda cannot handle a failure, so it calls only operations that cannot fail (U3007 otherwise, §4.6). Second-class types are not type arguments either (U3016).

Consequence: authority only flows downward through calls, and every function's reachable authority is visible in headers.

## 7.7 Host capabilities

The runtime implements these; they are part of the prelude.

| Capability | Operation | Fails | Accepts |
| --- | --- | --- | --- |
| `Console` | `print(line: Text) -> Unit` | | `public` |
| `Clock` | `now() -> Int` (ms since Unix epoch) | | `public` |
| `Env` | `get(name: Text) -> Option[internal Text]` | | `public` |
| `Files` | `read(path: Text) -> internal Text` | `FileError` | `public` |
| `Files` | `write(path: Text, content: Text) -> Unit` | `FileError` | `internal` |
| `Keys` | `hmac(key_name: Text, data: Text) -> internal Hashed` | `KeyError` | `public` for `key_name`, any label for `data`; the result carries the label of `data` |
| `Http` (edition `0.2`) | `get(url: Text, headers: List[Header], key_name: Option[Text]) -> internal Response` | `HttpError` | `internal` |
| `Http` | `post(url: Text, headers: List[Header], body: Text, key_name: Option[Text]) -> internal Response` | `HttpError` | `internal` |
| `Http` | `put(url: Text, headers: List[Header], body: Text, key_name: Option[Text]) -> internal Response` | `HttpError` | `internal` |
| `Http` | `delete(url: Text, headers: List[Header], key_name: Option[Text]) -> internal Response` | `HttpError` | `internal` |

- **Entry.** Host capabilities enter only through `main`'s `uses`, and only if `una run`, or the native executable, grants them. An ungranted capability is U3012 before execution starts.
- **Grant syntax:** `console`, `clock`, `env`, `keys:<keyfile>`, `files:<path>:read`, `files:<path>:write`, and in edition `0.2` `http:<origin>` or `http:<origin>:<methods>` (by default `get`).
- **`Http`** (`spec/24`). `Header` has `name: Text` and `value: internal Text`, and `Response` has `status: Int`, `headers: List[Header]` and `body: Text`. A status is not a failure: `HttpError` is `Denied`, `BadUrl`, `BadRequest`, `Unreachable`, `TimedOut`, `TooLarge`, `Tls` or `Protocol`. `key_name: Some(n)` sends the key `n` of the `keys:` grants as `Authorization: Bearer <key>`; a token another header carries goes in as a header value, through a policy to `internal` when it is `secret`. The guide for agents, §17, has an example with a stand-in handler.
- **`Files` paths.** A path is relative to the grant's prefix: with `files:data:read`, `@files.read("readings.txt")` reads `data/readings.txt`, and `"data/readings.txt"` would look for `data/data/readings.txt` and fail with `NotFound`. A path stays confined to the prefix: an absolute path, or a `..` that leaves it, fails with `Denied`. `FileError` is `NotFound`, `Denied` or `Io`, and `KeyError` is `UnknownKey`.
- **Tests and handlers.** You can write handlers for host capabilities, for example a fake `Keys` in tests (§17).

---


## Constructs

- [capability and op](https://una-lang.org/en/docs/language/capabilities/capability.md)
- [uses](https://una-lang.org/en/docs/language/capabilities/uses.md)
- [@ bindings and with](https://una-lang.org/en/docs/language/capabilities/with.md)
- [handler](https://una-lang.org/en/docs/language/capabilities/handler.md)
- [Host capabilities and grants](https://una-lang.org/en/docs/language/capabilities/host.md)
