---
title: "13.2 A ceiling for a module: boundaries"
url: https://una-lang.org/en/learn/authority/a-ceiling-for-a-module-boundaries/
release: v0.4.0
edition: "0.2, 0.3"
---

# 13.2 A ceiling for a module: boundaries

## 13.2.1 What a boundary is

When a store lets a contractor in to service the label printer, it gives them a badge that opens the stockroom and nothing else. Whatever the contractor brings, the badge decides which doors open.

A **boundary** is such a badge for a module, written in `una.toml`. It marks a module, usually **vendored** code, a supplier's code copied into the package's `src/` ([chapter 11](https://una-lang.org/en/learn/packages/the-manifest-and-the-lock/#s11-3)), and gives it a **ceiling**: the most the rest of the package may ever grant it, as a list of capabilities and operations. A call into the module that would grant more fails the check, and every call into it must grant each capability by hand, with `with`.

## 13.2.2 Why give a module a ceiling

The store copied a label printer's module into `src/vendor/labels.una`. A new version of it arrives, and besides printing, it now reads the clock. Its header says so, but the output does not change:

```diff include="steps/05-boundary..steps/06-unbounded:src/vendor/labels.una" context="0" title="src/vendor/labels.una"
--- a/src/vendor/labels.una
+++ b/src/vendor/labels.una
@@ -3 +3 @@
---- Prints a shelf label for a product.
+--- Prints a shelf label for a product. This version also reads the clock.
@@ -5,0 +6 @@
+  uses @clock: Clock[now]
@@ -6,0 +8 @@
+  let printed_at = @clock.now()
```

This package has no boundary yet. The store accepts the new version with two small edits of its own: `main` declares that it holds the clock, and `una.toml` grants it. Without the first, `una check` reports U3001 at the call; without the second, `una check` and `una run` report U3012 ([chapter 12](https://una-lang.org/en/learn/capabilities/the-hosts-capabilities-and-grants/#s12-2)).

```diff include="steps/05-boundary..steps/06-unbounded:una.toml" context="0" title="una.toml"
--- a/una.toml
+++ b/una.toml
@@ -8,5 +8 @@
-grants = ["console"]
-
-# Code from the label printer's supplier: the most the store may ever grant it.
-[boundaries]
-"vendor.labels" = ["Console[print]"]
+grants = ["console", "clock"]
```

```una include="steps/06-unbounded/src/store/app.una" title="steps/06-unbounded/src/store/app.una" verified="check, run"
module store.app

import vendor.labels (print_label)

pub main() -> Unit
  uses @console: Console[print]
  uses @clock: Clock[now]
=
  print_label("LAMP-01", price: "19.90")
```

```text include="steps/06-unbounded/expected/output.txt"
[LAMP-01 | 19.90]
```

The package checks and runs, and the label looks as before. The call itself did not change: `print_label` takes the clock by name, as any call passes the capabilities its callee needs ([chapter 12](https://una-lang.org/en/learn/capabilities/passing-authority-with-rebinding-and-narrowing/#s12-4)). Nothing at the call says where the clock goes, and once the store's code holds a capability for a job of its own, a later version of the supplier's module can start using it with no change at all in the store's code. With access to files, the same change could read data it was never meant to see. A boundary makes every such grant visible at the call, and turns one beyond the ceiling into an error.

## 13.2.3 How to write `[boundaries]`

:::steps
```toml include="steps/05-boundary/una.toml" title="steps/05-boundary/una.toml"
[package]
name = "store"
version = "0.1.0"
edition = "0.3"

[run]
entry = "store.app"
grants = ["console"]

# Code from the label printer's supplier: the most the store may ever grant it.
[boundaries]
"vendor.labels" = ["Console[print]"]
```

1. **`edition = "0.3"`.** `[boundaries]` exists only in edition `0.3`.
2. **`[boundaries]`.** The table of boundaries.
3. **`"vendor.labels"`.** The key: the module path of a module of the package, in quotes, since it holds a dot. It also covers every module below it, by whole parts of the path: `vendor.labels` covers `vendor.labels.fonts`, but not `vendor.labelsmith`.
4. **`["Console[print]"]`.** The ceiling: an array of texts, each a capability with the operations it may receive, `Capability[operation, …]`, with at least one operation. It names no binding and no condition: a ceiling names capabilities and operations only.
:::

## 13.2.4 Printing labels through a boundary

The module itself is ordinary Una. It declares what it uses, as any public function does:

```una include="steps/05-boundary/src/vendor/labels.una" title="steps/05-boundary/src/vendor/labels.una" verified="check"
module vendor.labels

--- Prints a shelf label for a product.
pub print_label(sku: Text, price: Text) -> Unit
  uses @console: Console[print]
=
  @console.print("[{sku} | {price}]")
```

The store's code calls it:

```una include="steps/05-boundary/src/store/app.una" title="steps/05-boundary/src/store/app.una" verified="check, run"
module store.app

import vendor.labels (print_label)

pub main() -> Unit
  uses @console: Console[print]
=
  print_label("LAMP-01", price: "19.90") with @console = @console
```

```text include="steps/05-boundary/expected/output.txt"
[LAMP-01 | 19.90]
```

A call into the boundary takes nothing by name. The caller grants each capability with `with`, here `with @console = @console`: the label module's `@console` is the app's own `@console`. Elsewhere, this rebinding would be redundant; at a boundary it is the grant, so every call into the module shows exactly what it receives.

## 13.2.5 How calls into a boundary are checked

A **call into a boundary** is a call from code outside the boundary to a function or a handler inside it. Code inside the boundary calls its own functions as usual.

### 13.2.5.1 Everything is granted with `with` (U3020)

Call the label module the usual way, without `with`:

```diff include="steps/05-boundary..steps/07-by-name:src/store/app.una" context="0" title="src/store/app.una"
--- a/src/store/app.una
+++ b/src/store/app.una
@@ -8 +8 @@
-  print_label("LAMP-01", price: "19.90") with @console = @console
+  print_label("LAMP-01", price: "19.90")
```

```text include="steps/07-by-name/expected/rendered.txt"
[U3020] Error: `print_label` is in the boundary `vendor.labels` and needs `@console: Console[print]`, which a call into it grants only with `with`
   ╭─[ src/store/app.una:8:3 ]
   │
 8 │   print_label("LAMP-01", price: "19.90")
   │   ───────────────────┬──────────────────
   │                      ╰──────────────────── `print_label` is in the boundary `vendor.labels` and needs `@console: Console[print]`, which a call into it grants only with `with`
   │
   ├─[ src/vendor/labels.una:5:3 ]
   │
 5 │   uses @console: Console[print]
   │   ──────────────┬──────────────
   │                 ╰──────────────── the boundary's requirement
   │
   │ Help: repair 1: grant `with @console = @console[print]`, narrowed to the operations the callee declares, which lie within the ceiling of `vendor.labels`; edit src/store/app.una:8:41..8:41 to " with @console = @console[print]"
   │
   │ Note: run `una explain U3020` for an explanation
───╯
1 of 1 diagnostics have an edit that `una fix` applies (`una fix --dry-run` lists them)
```

The first mark is the call, and the second is the requirement inside the boundary that the call left to be met by name. The fix is a `with` at the call, as in [Printing labels through a boundary](#printing-labels-through-a-boundary). The repair writes one, and `una fix .` applies it: `with @console = @console[print]`, a grant narrowed to the operations that the callee declares, a form that [Granting less at the call](#granting-less-at-the-call-with-x-yops) explains. Here the app's `@console` permits only `print`, so the narrowed grant and `with @console = @console` hand over the same. When no such grant lies within the ceiling, the repair is a description instead, and `una fix` applies nothing.

### 13.2.5.2 What a call grants stays within the ceiling (U3021)

Now add the boundary to the package of [Why give a module a ceiling](#why-give-a-module-a-ceiling), with the new version of the module, and grant it the clock with `with`:

```una include="steps/08-over-ceiling/src/store/app.una" title="steps/08-over-ceiling/src/store/app.una"
module store.app

import vendor.labels (print_label)

pub main() -> Unit
  uses @console: Console[print]
  uses @clock: Clock[now]
=
  print_label("LAMP-01", price: "19.90") with @console = @console, @clock = @clock
```

```text include="steps/08-over-ceiling/expected/rendered.txt"
[U3021] Error: the call of `print_label` grants `Clock[now]` to `vendor.labels`, whose ceiling in `una.toml` allows no operation of `Clock`
   ╭─[ src/store/app.una:9:3 ]
   │
 9 │   print_label("LAMP-01", price: "19.90") with @console = @console, @clock = @clock
   │   ───────────────────┬──────────────────
   │                      ╰──────────────────── the call of `print_label` grants `Clock[now]` to `vendor.labels`, whose ceiling in `una.toml` allows no operation of `Clock`
   │
   │ Help: repair 1: no grant keeps both: the callee declares `Clock[now]`, and the ceiling of `vendor.labels` allows no operation of `Clock`, so the consumer decides between this module and its ceiling
   │
   │ Note: run `una explain U3021` for an explanation
───╯
```

The call grants `Clock[now]`, and the ceiling allows no operation of `Clock`. The help under the message offers no edit: the callee declares `Clock[now]`, the store's clock permits it, and the ceiling withholds it, so the choice between the new version and the ceiling belongs to the store. To accept the new version, someone must widen the ceiling in `una.toml`, which a reviewer sees, or the store keeps the old version. `una fix .` never makes that choice, since it never edits `una.toml`. A handler for `Clock` with no `uses` of its own, written outside the boundary, would lie within the ceiling too, as [What counts against the ceiling](#what-counts-against-the-ceiling) explains, but it hands the module a stand-in clock, not the store's.

### 13.2.5.3 What counts against the ceiling

Each binding that the callee's `uses` name counts, with every operation it permits. A handler installed for the call counts with its own `uses` too. A binding of the `with` that the callee does not ask for counts for nothing, since the callee can never use it. A boundary module can never be one of the package's trusted modules, so it can never release labeled data ([chapter 17](https://una-lang.org/en/learn/information-flow/)).

### 13.2.5.4 What a boundary key may say (U7002)

Each of these is U7002, at the key in `una.toml`: a key that is not a module of the package, a key inside another key's modules, a malformed ceiling, a capability named twice in one ceiling, an unknown capability or operation, a module that `[trusted]` lists ([chapter 17](https://una-lang.org/en/learn/information-flow/)) inside a boundary, and the `[run] entry` inside a boundary.

## 13.2.6 Granting less at the call: `with @x = @y[ops]`

[Chapter 12](https://una-lang.org/en/learn/capabilities/passing-authority-with-rebinding-and-narrowing/#narrowing-a-greeting-that-may-only-look-up) showed one way authority narrows: a callee's header limits what it may use, whatever binding it receives. A ceiling does not stop at the callee's header, though. It counts every operation that the granted binding permits. So at a boundary, the caller must hand over less, and edition `0.3` lets it say so at the call.

### 13.2.6.1 What a narrowed rebinding is

When you lend a colleague your key ring for one errand, you can take off every key but the one they need. A **narrowed rebinding** does that with a binding: it hands the callee the caller's binding with only some of its operations. You write `with @x = @y[ops]`: the callee's name `@x`, `=`, the caller's binding `@y`, and in brackets the names of the operations the callee may receive, separated by commas. It is the rebinding `with @x = @y` of chapter 12, with brackets added.

### 13.2.6.2 Why a boundary needs it

In this step, the price list has two operations, and the label module reads prices to print them:

```una include="steps/09-narrow-wide/src/store/prices.una" title="steps/09-narrow-wide/src/store/prices.una"
module store.prices

--- The store's price list: reading a price, and setting one.
pub capability PriceList
  op price(sku: Text) -> Int
  op set_price(sku: Text, cents: Int) -> Unit
```

```una include="steps/09-narrow-wide/src/vendor/labels.una" title="steps/09-narrow-wide/src/vendor/labels.una"
module vendor.labels

import store.prices (PriceList)

--- Prints a shelf label with the current price of a product, read from the price list.
pub print_price_tag(sku: Text) -> Unit
  uses @prices: PriceList[price]
  uses @console: Console[print]
=
  let cents = @prices.price(sku)
  @console.print("[{sku} | {cents} cents]")
```

```toml include="steps/09-narrow-wide/una.toml" title="steps/09-narrow-wide/una.toml"
[package]
name = "store"
version = "0.1.0"
edition = "0.3"

[run]
entry = "store.app"
grants = ["console"]

# Code from the label printer's supplier: the most the store may ever grant it.
[boundaries]
"vendor.labels" = ["Console[print]", "PriceList[price]"]
```

The ceiling allows `PriceList[price]`. `reprice` holds `PriceList[price, set_price]`, since it sets a price, and grants its whole binding to the label module:

```una include="steps/09-narrow-wide/src/store/app.una#reprice" title="steps/09-narrow-wide/src/store/app.una"
--- Sets a new price, then prints the shelf label with it.
reprice(sku: Text, cents: Int) -> Unit
  uses @prices: PriceList[price, set_price]
  uses @console: Console[print]
=
  @prices.set_price(sku, cents)
  print_price_tag(sku) with @console = @console, @prices = @prices
```

```text include="steps/09-narrow-wide/expected/rendered.txt#L1"
[U3021] Error: the call of `print_price_tag` grants `PriceList[price, set_price]` to `vendor.labels`, whose ceiling in `una.toml` allows `PriceList[price]`
```

The label module asks only for `price`, but the binding it receives permits `set_price` too, so the call would grant more than the ceiling. This time a grant exists that keeps both: the callee declares only `PriceList[price]`, which the ceiling allows. The help under the message names it, as a description that `una fix` does not apply, and the next part writes it.

### 13.2.6.3 One operation: `@prices[price]`

Narrow the binding at the call, `with @prices = @prices[price]`: the label module's `@prices` is the caller's `@prices`, restricted to `price`.

```diff include="steps/09-narrow-wide..steps/10-narrowed:src/store/app.una" context="0" title="src/store/app.una"
--- a/src/store/app.una
+++ b/src/store/app.una
@@ -18 +18 @@
-  print_price_tag(sku) with @console = @console, @prices = @prices
+  print_price_tag(sku) with @console = @console, @prices = @prices[price]
```

```text include="steps/10-narrowed/expected/output.txt"
set LAMP-01 to 1592
[LAMP-01 | 1592 cents]
```

The call now grants `PriceList[price]`, which is within the ceiling, so the package checks and runs. `reprice` itself still holds both operations: only what it hands over is narrower.

### 13.2.6.4 Several operations, and calls outside a boundary

This step has no boundary. The price list has three operations, and `review` holds all of them. It hands each helper only the operations named at the call:

:::steps
```una include="steps/18-narrow-forms/src/pricing.una" title="steps/18-narrow-forms/src/pricing.una" verified="check, run"
module pricing

--- The store's price list: reading a price, setting one, and taking a product off the list.
capability PriceList
  op price(sku: Text) -> Int
  op set_price(sku: Text, cents: Int) -> Unit
  op remove(sku: Text) -> Unit

--- Prints the price of a SKU. It only reads.
show_price(sku: Text) -> Unit
  uses @prices: PriceList[price]
  uses @console: Console[print]
=
  let cents = @prices.price(sku)
  @console.print("{sku} costs {cents}")

--- Raises the price of a SKU by `cents`.
raise_price(sku: Text, cents: Int) -> Unit
  uses @prices: PriceList[price, set_price]
=
  let current = @prices.price(sku)
  @prices.set_price(sku, cents: current + cents)

--- Takes 10 percent off a SKU, and gives back the new price. A dry run sets no price.
mark_down(sku: Text, dry_run: Bool) -> Int
  uses @prices: PriceList[price, set_price where not dry_run]
=
  let cents = @prices.price(sku)
  let sale = cents - cents / 10
  if not dry_run
    @prices.set_price(sku, cents: sale)
  sale

--- Reviews the price list. It holds every operation, and hands each helper only the ones named
--- at the call. A dry run changes nothing.
review(dry_run: Bool) -> Unit
  uses @prices: PriceList[price, set_price where not dry_run, remove where not dry_run]
  uses @console: Console[print]
=
  show_price("LAMP-01") with @prices = @prices[price]
  if not dry_run
    raise_price("LAMP-01", cents: 100) with @prices = @prices[price, set_price]
  let sale = mark_down("DESK-02", dry_run) with @prices = @prices[price, set_price]
  @console.print("DESK-02 goes to {sale}")
  if not dry_run
    @prices.remove("RUG-07")

--- A price list where every product costs `each` cents, and that prints each change.
handler flat(each: Int) for PriceList
  uses @console: Console[print]
  op price(sku) = each
  op set_price(sku, cents) = @console.print("set {sku} to {cents}")
  op remove(sku) = @console.print("removed {sku}")

pub main() -> Unit
  uses @console: Console[print]
=
  @console.print("Dry run:")
  review(dry_run: true) with @prices = flat(1990)
  @console.print("Review:")
  review(dry_run: false) with @prices = flat(1990)
```

1. **`show_price("LAMP-01") with @prices = @prices[price]`.** One operation in the brackets: `show_price` receives a binding that may only read.
2. **`if not dry_run`.** `review` may set a price only where `not dry_run` holds, and a binding narrowed from it keeps that condition. `raise_price` has no condition, so its call on the next line needs the guard.
3. **`raise_price(…) with @prices = @prices[price, set_price]`.** Several operations, separated by commas, as in the brackets of `uses`. `raise_price` never receives `remove`.
4. **`mark_down(…) with @prices = @prices[price, set_price]`.** No guard here: the condition of `mark_down`, `not dry_run`, implies the one the binding carries.
:::

`una run .` prints:

```text include="steps/18-narrow-forms/expected/output.txt"
Dry run:
LAMP-01 costs 1990
DESK-02 goes to 1791
Review:
LAMP-01 costs 1990
set LAMP-01 to 2090
set DESK-02 to 1791
DESK-02 goes to 1791
removed RUG-07
```

The dry run reads two prices and sets none. The review sets two prices and removes a product.

### 13.2.6.5 How a narrowed rebinding behaves

- **The caller must hold each operation.** The brackets may name only operations that `@y` permits. If `review` held only `PriceList[price]`, `@prices[set_price]` would be U3002: "`@prices` permits `price`, not `set_price`, so a narrowed rebinding of it cannot grant `set_price`".
- **The capability must declare it.** An operation that the capability does not declare, such as `@prices[refund]`, is U1001: "capability `PriceList` has no operation `refund`".
- **The callee gets only the bracketed operations.** A callee that needs another operation of the binding gets U3002 at the call, as for any binding with too few operations, as [Check yourself: narrowing](#check-yourself-narrowing) shows.
- **Names only.** The brackets hold names of operations and nothing else: no `where` and no condition, as [A condition inside the narrowing brackets](https://una-lang.org/en/learn/authority/common-mistakes/#a-condition-inside-the-narrowing-brackets-u0101) shows.
- **Conditions stay.** The narrowed binding runs as the caller's binding, and every condition that binding carries still applies, as the guard around `raise_price` shows.
- **Any call, in edition 0.3.** A narrowed rebinding is allowed at any call, not only at a boundary. In editions `0.1` and `0.2` the brackets are a syntax error, U0101.

### 13.2.6.6 When to narrow outside a boundary

Outside a boundary, the callee's header already limits what it may use, so narrowing proves nothing more about the callee. It pins, at the call, what the callee receives. If a later edit widens the header of `show_price` to `PriceList[price, set_price]`, the call `with @prices = @prices[price]` fails with U3002, instead of quietly handing over the right to set prices. Narrow where a reader of the caller should see at a glance what each helper gets; pass the binding whole where the callee's header is enough.

## 13.2.7 A boundary, a lock or neither

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

| The code… | Use |
| --- | --- |
| Is yours, and its header is reviewed with it | Nothing more: the header and the verifier suffice |
| Is yours, and a header must not widen without a review of `una.toml` | A lock in `[contracts]` ([section 13.3](https://una-lang.org/en/learn/authority/locking-a-contract-contracts/#s13-3)) |
| Comes from a supplier, copied into `src/` | `[boundaries]`, with the least ceiling it needs |
| Comes from a supplier, and you also want its public functions' headers fixed | Both: a boundary for the module, and locks for its functions |
| Receives a binding that permits more than it should get, at a boundary or where you want the call to show it | A narrowed rebinding at the call, `with @x = @y[ops]` |
:::

## 13.2.8 Check yourself: a module below the boundary

The supplier adds a second module, `src/vendor/labels/fonts.una`, and the app calls it as it would call any module, by name:

```una include="steps/11-fonts/src/vendor/labels/fonts.una" title="steps/11-fonts/src/vendor/labels/fonts.una"
module vendor.labels.fonts

--- Prints a shelf label in large letters.
pub print_large(sku: Text) -> Unit
  uses @console: Console[print]
=
  @console.print("** {sku} **")
```

```una include="steps/11-fonts/src/store/app.una" title="steps/11-fonts/src/store/app.una"
module store.app

import vendor.labels (print_label)
import vendor.labels.fonts (print_large)

pub main() -> Unit
  uses @console: Console[print]
=
  print_label("LAMP-01", price: "19.90") with @console = @console
  print_large("LAMP-01")
```

`una.toml` is the one of [How to write `[boundaries]`](#how-to-write-boundaries), with the key `vendor.labels` only. Does the package check?

:::answer Show the answer
It does not:

```text include="steps/11-fonts/expected/rendered.txt#L1"
[U3020] Error: `print_large` is in the boundary `vendor.labels` and needs `@console: Console[print]`, which a call into it grants only with `with`
```

The key `vendor.labels` covers every module below it, so `vendor.labels.fonts` is in the boundary too, and a call into it grants its capabilities only with `with`. Write `print_large("LAMP-01") with @console = @console`, or let `una fix .` write the repair, `with @console = @console[print]`, which grants the same here.
:::

## 13.2.9 Check yourself: narrowing

In the step of [Several operations, and calls outside a boundary](#several-operations-and-calls-outside-a-boundary), `review` narrows the binding it gives `show_price` to the other operation:

```diff include="steps/18-narrow-forms..steps/19-narrow-too-few:src/pricing.una" context="0" title="src/pricing.una"
--- a/src/pricing.una
+++ b/src/pricing.una
@@ -40 +40 @@
-  show_price("LAMP-01") with @prices = @prices[price]
+  show_price("LAMP-01") with @prices = @prices[set_price]
```

`review` holds `set_price`, so the brackets are allowed. Does the package check?

:::answer Show the answer
No:

```text include="steps/19-narrow-too-few/expected/diagnostics.txt"
error U3002 at src/pricing.una:40:3: `show_price` needs `@prices` to permit `price`, which it does not here
```

`show_price` reads a price, so its header needs `@prices` to permit `price`. The narrowed binding permits only `set_price`, so the call gives `show_price` too few operations, which is U3002 at the call. Narrow to what the callee's header lists: `@prices[price]`.
:::
