---
title: "11.3 The manifest and the lock"
url: https://una-lang.org/en/learn/packages/the-manifest-and-the-lock/
release: v0.4.0
edition: "0.2"
---

# 11.3 The manifest and the lock

## 11.3.1 What a manifest is

A **manifest** is a file that describes a package to the tools: its name, its version, which edition of the language it is written in, and how to run it. In editions `0.1` to `0.3` it is `una.toml`, at the root of the package (from edition `0.4` it is `ita.una`, [chapter 19](https://una-lang.org/en/learn/editions/)). Every command reads it before it reads any module.

`una.toml` is written in **TOML**, a common format for settings files. You need four of its rules:

- A **table** is a group of settings, opened by its name in brackets on a line of its own: `[package]`. It runs until the next table.
- A **key** is a setting's name, followed by `=` and its **value**: `edition = "0.2"`.
- A value is a text in double quotes (`"store"`), a whole number (`0`), or an **array**, a list of values in brackets separated by commas (`["console"]`).
- A line that starts with `#` is a comment, for people only.

## 11.3.2 Why the manifest is checked

A settings file that accepts anything turns a typing mistake into a setting that silently does nothing. Here a manifest means to allow each module one use of `checked` ([chapter 7](https://una-lang.org/en/learn/failure/when-no-proof-can-decide-checked-and-opaque-predicates/#s7-5)), and misspells the key:

```diff include="steps/11-manifest..steps/12-misspelt:una.toml" context="0" title="una.toml"
--- a/una.toml
+++ b/una.toml
@@ -18 +18 @@
-checked_per_module = 0
+checked_per_modules = 1
```

`una check .` reports:

```text include="steps/12-misspelt/expected/rendered.txt"
[U7002] Error: unknown key `checked_per_modules` in [escape_budget]
    ╭─[ una.toml:18:1 ]
    │
 18 │ checked_per_modules = 1
    │ ─────────┬─────────
    │          ╰─────────── unknown key `checked_per_modules` in [escape_budget]
    │
    │ Note: run `una explain U7002` for an explanation
────╯
```

U7002 is the code of a manifest una cannot accept, and it points at the line and the key. In a tool that ignored unknown keys, the budget would silently stay at 0, and the mistake would show up later, as an error at the first `checked` of some module, far from its cause. Here it shows up at the line that has it.

## 11.3.3 How to write `una.toml`

`una.toml` holds up to five tables in edition `0.2`, and no other table or key is allowed. Edition `0.3` adds two more, `[contracts]` and `[boundaries]`, which put limits on what code may do; [chapter 13](https://una-lang.org/en/learn/authority/) covers them.

### 11.3.3.1 `[package]`: what the package is

| Key | Value |
| --- | --- |
| `name` | The package's name, a text, such as `"store"`. |
| `version` | The package's own version, a text, such as `"0.2.0"`. una checks only that it is a text that is not empty. |
| `edition` | The edition of Una its modules are written in: `"0.1"`, `"0.2"` or `"0.3"` ([chapter 19, Editions](https://una-lang.org/en/learn/editions/)). Every example of this chapter uses `"0.2"`. |

`[package]` is required, with all three keys.

### 11.3.3.2 `[run]`: what `una run` starts and grants

| Key | Value |
| --- | --- |
| `entry` | The module path of the module whose `pub main` `una run` starts. |
| `grants` | An array of the host capabilities the run is given, such as `["console"]`, besides those of a `--grant` flag ([section 12.2](https://una-lang.org/en/learn/capabilities/the-hosts-capabilities-and-grants/#s12-2)). |

### 11.3.3.3 `[labels]`, `[trusted]` and `[escape_budget]`

| Table and key | Value |
| --- | --- |
| `[labels]` `categories` | The categories that labels may name, such as `["PII"]`. A label marks data, such as a customer's address, whose flow through the program Una follows ([chapter 17, Information flow](https://una-lang.org/en/learn/information-flow/)). |
| `[trusted]` `modules` | The modules that may declare policies, the rules that let labeled data out, each also marked `trusted module` in its header ([chapter 17](https://una-lang.org/en/learn/information-flow/)). |
| `[escape_budget]` `checked_per_module` | How many uses of `checked` each module may have, 0 by default ([section 7.5](https://una-lang.org/en/learn/failure/when-no-proof-can-decide-checked-and-opaque-predicates/#s7-5)). |

These three are optional. Without them, a package has no label categories, no trusted modules and a budget of 0.

## 11.3.4 A manifest, table by table

Here is a manifest that uses four of the tables, with a comment on each:

```toml include="steps/11-manifest/una.toml" title="steps/11-manifest/una.toml"
# The package: its name, its version, and the edition of the language it is written in.
[package]
name = "store"
version = "0.2.0"
edition = "0.2"

# What `una run` starts, and the host capabilities it grants, besides those of a `--grant` flag.
[run]
entry = "store.app"
grants = ["console"]

# The categories that labels may name.
[labels]
categories = ["PII"]

# How many uses of `checked` each module may have.
[escape_budget]
checked_per_module = 0
```

The package still runs as before, with the same modules. Only `una.toml` changed.

## 11.3.5 No dependencies on other packages in `una.toml`

A package that `una.toml` describes, of edition `0.1`, `0.2` or `0.3`, has no way to depend on another package: `una.toml` has no dependency table, and a package imports only its own modules and two standard modules, `std.host` and `std.testing`. Importing anything else says so:

```text include="steps/13-no-dependencies/expected/rendered.txt#L1"
[U1001] Error: module `vendor.tax` is not a module of this package; the standard modules that can be imported are `std.host` and `std.testing`
```

So everything a package runs is in its own `src/`, the prelude, or the host capabilities that `una run` grants, in `[run] grants` or by a `--grant` flag. In these editions, code from elsewhere, such as a supplier's library, is copied into `src/` as modules of the package, where the checker sees all of it. Code copied in this way is called **vendored** code. Edition `0.3` can then put a limit on what such a module may do, as [chapter 13](https://una-lang.org/en/learn/authority/) shows. From edition `0.4`, a package describes itself in `ita.una` instead, and may depend on other packages in directories of its own, its path dependencies ([spec/30](https://una-lang.org/en/docs/spec/30-packages/)); the packages of this chapter use `una.toml`.

## 11.3.6 `verification.lock`

`verification.lock` is the other file at the root of every package. It pins the verifier, the part of una that proves contracts ([chapter 5](https://una-lang.org/en/learn/contracts/preconditions-requires/#s5-1)), so that every machine gets the same answers. It is a TOML file with six keys, and no others:

| Key | What it fixes |
| --- | --- |
| `encoding_version` | How una writes its questions for the solver: `"una-smt-1"` |
| `solver` and `solver_version` | The solver and its exact version: `"z3"`, `"5.1.0"` |
| `logic` | The kind of arithmetic the questions use: `"QF_UFLIA"` |
| `step_budget` | How much work the solver may do on one question before it answers "unknown" |
| `random_seed` | The solver's starting point, so its search runs the same way every time |

With the same sources, `una.toml` and lock, `una check` gives the same diagnostics and the same proofs on every machine. A missing or invalid lock is U7004, and a solver of another version is U5003. You rarely edit it: copy it from an existing package, and change it only to adopt a new solver, in a change of its own.

## 11.3.7 How the manifest is checked

- A table or a key that is not in the lists of this section is U7002, at its line.
- A value of the wrong type, such as a number where a text goes, a missing required key, and a file that is not valid TOML are U7002 too.
- A manifest error does not stop the check. The tables and keys una could read still apply, and only the wrong ones are reported. When the file is not valid TOML at all, the modules are checked with the default settings instead: no grants, no label categories, a budget of 0, and edition `0.1`. So a manifest that cannot be read can bring other diagnostics with it, which go away once it is fixed.
- `una run .` also checks that `main`'s `uses` are granted: a capability that `main` uses but neither `[run] grants` nor a `--grant` flag grants stops the run before it starts (U3012, [section 12.2](https://una-lang.org/en/learn/capabilities/the-hosts-capabilities-and-grants/#s12-2)).

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

| The setting… | Belongs in |
| --- | --- |
| Is about the whole package: its name, edition, entry or grants | `una.toml` |
| Is about how the verifier answers | `verification.lock`, copied, not edited |
| Is about one function: what it may do or how it fails | The function's header, in the module |
| Limits what code may do, reviewed apart from the code, in edition `0.3` | `[contracts]` or `[boundaries]` ([chapter 13](https://una-lang.org/en/learn/authority/)) |
:::

## 11.3.8 Check yourself: a manifest

This manifest writes the version as a number:

```diff include="steps/11-manifest..steps/14-number:una.toml" context="0" title="una.toml"
--- a/una.toml
+++ b/una.toml
@@ -4 +4 @@
-version = "0.2.0"
+version = 2
```

Does the package check? If not, where does `una check .` point?

:::answer Show the answer
It does not check:

```text include="steps/14-number/expected/rendered.txt"
[U7002] Error: `version` must be a string, not an integer
   ╭─[ una.toml:4:11 ]
   │
 4 │ version = 2
   │           ┬
   │           ╰── `version` must be a string, not an integer
   │
   │ Note: run `una explain U7002` for an explanation
───╯
```

In TOML, a value without quotes is a number, and `version` must be a text: the mark points at the value. Write it in quotes, `version = "2.0.0"`. The file is valid TOML, but not a valid manifest: una checks the type of each value too, not only the names of the keys.
:::
