---
title: "Configure a package"
url: https://una-lang.org/en/docs/configure/
release: v0.4.0
source: https://github.com/una-lang/una/blob/v0.4.0/docs/guide/syntax-reference.md
---

# Configure a package

```text
events/
  una.toml
  verification.lock
  src/
    events/
      types.una
      seating.una
      keys.una
      checkin.una
      main.una
```

`una.toml` describes the package. The package of §17 shows every section:

| Key | Meaning |
| --- | --- |
| `[package]` `name`, `version`, `edition` | required; `edition` is `"0.1"`, `"0.2"` or `"0.3"` (a preview); edition `0.4` is described by `ita.una`, not `una.toml`, and `una migrate` moves a package there |
| `[labels]` `categories` | the label categories of §8.1 |
| `[trusted]` `modules` | the trusted modules of §8.5 |
| `[escape_budget]` `checked_per_module` | how many `checked` each module may use (default 0) |
| `[run]` `entry`, `grants` | the module whose `main` runs, and the grants of `una run` and of the native executable |

- **Editions.** The edition decides the language of the package: edition `0.2` has the memory model (§5.5, §5.6), fixed-width integers (§3.1), recursive kinds (§3.2), constraints (§3.3), effect polymorphism (§4.2) and `together` (§5.7). Edition `0.1` keeps the language of v0.1 in every version of the compiler. A single `.una` file has the default settings, and so edition `0.1`. Edition `0.3` is a preview: it has everything of edition `0.2`, and the rules of ADRs 0092 to 0094 join it as they land, which only ever adds errors. Edition `0.4`, in `ita.una`, is the preview of this release: it adds tasks and time, `for ever`, driven programs, HTTP servers and dependencies through Itá ([Edition](https://una-lang.org/en/docs/configure/package/edition/)).
- `verification.lock` pins the solver so that proofs are reproducible.
- Unknown keys in `una.toml` are U7002. A missing or invalid lock is U7004.

---

## `una.toml` and `verification.lock`

Package layout: `una.toml` and `verification.lock` at the root, sources under `src/`. Module `a.b.c` lives in `src/a/b/c.una` (U1008). Module paths whose first segment is `std` or `prelude` are reserved for the standard library, in a package and in a single file (U1009, `spec/10 §11` rule 8).

```toml
[package]
name = "events-example"
version = "0.1.0"
edition = "0.1"

[labels]
categories = ["PII", "Location"]

[trusted]
modules = ["events.keys"]

[escape_budget]
checked_per_module = 1        # default 0

[run]
entry = "events.main"
grants = ["console"]
```

Commands take a file or a directory, `.` by default (ADR 0021):

- A directory is a package only if it contains `una.toml` and `src/`; otherwise the command stops with a usage error (exit code 2). Its modules are the files `src/**/*.una`, hidden entries excepted, and the module in `src/a/b/c.una` MUST be declared `module a.b.c` (U1008).
- A file is a package of one module, whose root is the file's directory. It has the default settings, the default lock and no module path check.

`una.toml` is a TOML document with these tables and keys, and no others (U7002):

- `[package]`, required: `name`, `version` and `edition`, non-empty strings; `edition` is `"0.1"`. (v0.2, ADR 0056.) `edition` is `"0.1"` or `"0.2"`. The constructs of `spec/17`, `spec/18`, `spec/19` and `spec/20` and the keywords of edition `0.2` exist only in packages of edition `"0.2"` and later, and a single file has edition `"0.1"`, unless a manifest above it names another (`spec/30`, #1175).
  - (v0.3, ADR 0056 amendment of 2026-10-13.) `edition` is `"0.1"`, `"0.2"` or `"0.3"`. **Editions are cumulative.** Edition `"0.3"` has every construct, keyword and rule of edition `"0.2"`. A rule this specification states for edition `0.2` holds in every later edition, unless it says otherwise. The rules that target edition `0.3` (ADRs 0092, 0093 and 0094) apply only in packages of edition `"0.3"`.
  - **Edition `0.3` is a preview** until every rule that targets it has landed. Until then, a later `0.3.x` release MAY add obligations or errors to an edition `0.3` package: the edition only ever gets stricter, never looser. (ADR 0056 amendment of 2026-10-13, second.) Stricter concerns the programs that edition `0.2` can express: such a program keeps its result or gains obligations or errors. A later `0.3.x` release MAY also accept a construct that a rule targeting edition `0.3` adds and that earlier releases reject as a syntax error, such as the condition on an operation of ADR 0092. Each such construct MUST only narrow what a program may do: erasing it gives a program that edition `0.2` accepts, with no fewer allowed behaviors. Editions `0.1` and `0.2` keep their stability promise: a later release MUST NOT change what they accept or reject, except to fix a soundness or security error. (v0.3, ADR 0104.) A later `0.3.x` release MAY also give the methods `measured()`, `magnitude()` and `convert()` of `spec/25 §5` their meaning; every use of them where neither the receiver nor the expected type carries a unit is an error. (ADR 0103.) A later `0.3.x` release MAY also accept refined type arguments, and the facts on access they give, in a package of edition `0.3` (`spec/03 §3`); such a package can then be accepted where edition `0.2` rejects it, on facts the obligations of `spec/12 §3` prove. (ADR 0114.) A later `0.3.x` release MAY also accept the type `F64` and the constructs of `spec/29`, in a package of edition `0.3`; they do not erase to edition `0.2`. A program that edition `0.2` can express gains from them only U1002, for a declaration named `F64` and for a package function `to_f64` on integers, which the built-in conversion resolves ahead of.
  - (v0.4, ADR 0116 rule 0, and ADR 0122 Question 8.1.) Edition `0.4` is named in `ita.una` (`spec/30`), not here: `edition = "0.4"` in `una.toml` is U7002, with `una migrate` as its repair, and the package is still checked in edition `0.4`. Edition `"0.4"` has every construct, keyword and rule of edition `"0.3"`. **Edition `0.4` is a preview** under the same terms until a release makes it stable by the stabilizing record of ADR 0121 rule 15. Release `v0.4.0` ships it as a preview, and the release that makes it stable is named later (ADR 0139, amendment of 2026-11-10, accepted, #1897). The constructs of `spec/26` exist only in packages of edition `"0.4"` and later. (ADR 0105, amendment of 2026-11-05.) The keywords and reserved words of edition `"0.4"` are those of edition `"0.3"` with one exception: `example`, a keyword in edition `0.3`, is an identifier in edition `0.4` (`spec/01 §5`).
  - (ADR 0139 rules 6 and 7.) Collections (`spec/28`, ADR 0119) and the numeric foundation of `spec/29` §16 to §19 (ADR 0120) are not part of edition `0.4`: they moved to edition `0.5`, and since no release accepted them in edition `0.4`, they moved with no diagnostic of their own. In a package of edition `0.4`, each of them gets what edition `0.3` gives it, such as U1001 for `import std.collections` and for `Map.update`, U0101 for `Decimal[2]` and for a `with:` or `and:` label, U0103 for `simd` as a name and U2002 for `Array` or `Decimal` as a type, each a variant of `Json` there. These carry advice that names edition `0.5`, a description that no `una fix` applies, as "`F32` exists from edition 0.5 (ADR 0139): write `edition 0.5` in ita.una to use it": U1001 at an unknown name that edition `0.5` declares (`F32`, `Matrix`, `Complex`, ...), at the module path `std.collections` and at `m.update(...)` on a `Map`; U0101 at the scale of `Decimal[s]` and at a `with:` or `and:` label; U0103 at `simd`, after its rename; and the message of U2002 at `Array` or `Decimal` as a type (#1743). The other diagnostics of moved constructs carry none, such as U1001 at the conversions `to_f32` and `to_decimal` on an integer or an `F64`. `F64` and `spec/29` §1 to §15 stay in edition `0.3`.
  - (v0.5, ADR 0139 rules 2 and 6.) Edition `0.5` is named in `ita.una` too: `edition = "0.5"` in `una.toml` is U7002, with `una migrate` as its repair, which keeps edition `0.5` (`spec/30 §8`), and the package is still checked in edition `0.5`. Edition `"0.5"` has every construct, keyword and rule of edition `"0.4"`. **Edition `0.5` is a preview** under the terms of ADR 0121, as its amendment of 2026-11-06 extends them to every preview edition, until the rules that target it have landed, and becomes stable at release `v0.5.0`. The constructs of `spec/28` and of `spec/29` §16 to §19 exist only in packages of edition `"0.5"` (ADR 0119 and ADR 0120, amendments of 2026-11-06). (ADR 0120 rules 1 and 2.) The keywords and reserved words of edition `"0.5"` are those of edition `"0.4"` with one exception: `simd`, reserved in editions `0.1` to `0.4`, is an identifier in edition `0.5` (`spec/01 §5`). The keywords `with` and `and`, right before `:`, are also argument labels in a call in edition `0.5`, as in `a.dot(with: b)` (`spec/29 §17`).
- `[labels]`: `categories`, an array of category names (UpperCamelCase, U1005; unique, U1002).
- `[trusted]`: `modules`, an array of module paths, each a module of the package whose header says `trusted module` (U7005).
- `[escape_budget]`: `checked_per_module`, an integer of at least 0 (default 0).
- `[run]`: `entry`, the path of a module of the package, and `grants`, an array of the grant specs of §5.
- (v0.3, ADR 0092 rule 8 and its third amendment.) `[contracts]`, in edition `0.3` only: each key the qualified name of a public function of the package, each value an array of `uses` clauses written as a header writes them, operations listed in brackets, with `spec/05 §3` rule 4's conditions: `"pricing.update.update_prices" = ["@catalog: Catalog[price, set_price where not dry_run]"]`. A key that names no public function, an entry that does not parse or lists no operations, a binding locked twice, a capability that its name does not resolve to in the function's module, an operation the capability does not declare, and a condition that is not a `Bool` of the refinement language over the function's parameters are U7002 at the entry. (ADR 0094.) An entry MAY write `gives` and a label after an operation, before its condition, as a header does; a category that `[labels] categories` does not declare is U7002 at the entry, and the entry is not read. `spec/05 §3` rule 5 checks the header against it. In editions `0.1` and `0.2`, `[contracts]` is an unknown table.
- (v0.3, ADR 0093.) `[boundaries]`, in edition `"0.3"` only; in editions `"0.1"` and `"0.2"` it is an unknown table (U7002). Each key is the path of a module of the package, and covers that module and every module below it by whole path segments: `a.b` covers `a.b.c`, not `a.bc`. Each value is the module's ceiling: an array of names-only strings `C[op, ...]`, with at least one operation, each once, and no condition or label, where `C` is a capability that the key's module sees and each `op` one it declares. Each of these is U7002: a key that is not a module of the package, a key inside another key's extent, a malformed ceiling string, a capability named twice in one ceiling, an unknown capability or operation, a module of `[trusted] modules` inside a boundary, and a `[run] entry` inside a boundary. Calls into a boundary are checked as `spec/05 §4` rule 5 states (U3020, U3021, U3024).

- (v0.3, ADR 0109 rules 1 and 4.) In edition `"0.3"`, `[package] profile` is `"app"` or `"systems"`; any other value is U7002. Without the key, the profile is `app`, and a single file is `app`. In editions `"0.1"` and `"0.2"`, the key is unknown and U7002, and their packages are `app`. `[run] max_memory`, in edition `"0.3"` only, is the package's memory budget in MiB, from 1 to 4096 while edition `0.3` is a preview (U7002 outside); in editions `"0.1"` and `"0.2"` it is an unknown key (U7002). A `systems` package with a `[run] entry` and without `[run] max_memory` is U7002 at the entry; an `app` package may declare it too, with the same meaning. With the key, the value is the budget of `una run`, of `una test`, and of the native executable, which bakes it in at build time: `--max-memory` may lower it, never raise it, and a larger value is a usage error (exit code 2). Without the key, in either profile, `--max-memory` keeps its meaning of `spec/11 §7`.

A TOML syntax error, a missing required key, and a value of the wrong type or outside its range are U7002. The default settings are empty `[labels]`, `[trusted]` and `[run]` tables and a budget of 0.

`verification.lock` is a TOML document with exactly the keys of `spec/12 §9`: `encoding_version = "una-smt-1"`, `solver = "z3"`, `solver_version` a non-empty string, `logic = "QF_UFLIA"`, `step_budget` an integer of at least 1, and `random_seed` an integer of at least 0. A missing file, a TOML syntax error, a missing or unknown key and a wrong value are U7004; a solver of another version is U5003. A single file uses the default lock, which holds the values of the repository's `verification.lock`.

Project errors do not stop checking: the modules are still checked, with the settings that `una.toml` gives (#930):

- A `una.toml` that is not a TOML document, a TOML syntax error, gives the default settings, in edition `"0.1"` whatever edition it names.
- Otherwise each table and each key is read on its own. An unknown table, an unknown key, and a value of the wrong type or outside its range, such as an edition that is not one of those above (`"0.4"` and `"0.5"` are read, as above), are U7002 and are not read: that key keeps its default. Every other key is read as written, so a `una.toml` with an unknown key keeps its edition, its labels, its trusted modules, its budget and its `[run]` settings. In an array, each element that is U7002 is left out and the others are read.
- A setting that is not read is never silently in effect or silently gone: it is always U7002, an error, so the command fails (exit code 1) whatever the modules give.

(v0.4, ADR 0122.) **Edition `0.4` and later.** A package of edition `0.4` describes itself in `ita.una` and is pinned by `ita.lock`, in Una's own lexical syntax, by the closed grammars of `spec/30`; a directory with `ita.una` is a package with that file in place of `una.toml`, and one with both is U7008. Every error that this section makes U7002 for a key of `una.toml` is U7008 at the corresponding line of `ita.una`; every error of `ita.lock` is U7009 where `verification.lock` has U7004. `una fmt ita.una` formats the file, `una fmt` of the package leaves it alone, and `una fix` never edits `ita.una`, `ita.lock` or `itaty.una`.


## Keys

- [[package] name](https://una-lang.org/en/docs/configure/package/name.md)
- [[package] version](https://una-lang.org/en/docs/configure/package/version.md)
- [[package] edition](https://una-lang.org/en/docs/configure/package/edition.md)
- [[labels] categories](https://una-lang.org/en/docs/configure/labels/categories.md)
- [[trusted] modules](https://una-lang.org/en/docs/configure/trusted/modules.md)
- [[escape_budget] checked_per_module](https://una-lang.org/en/docs/configure/escape-budget/checked-per-module.md)
- [[run] entry](https://una-lang.org/en/docs/configure/run/entry.md)
- [[run] grants](https://una-lang.org/en/docs/configure/run/grants.md)
- [[boundaries]](https://una-lang.org/en/docs/configure/boundaries.md)
- [verification.lock](https://una-lang.org/en/docs/configure/verification-lock.md)
- [[contracts]](https://una-lang.org/en/docs/configure/contracts.md)
- [[package] profile](https://una-lang.org/en/docs/configure/package/profile.md)
- [[run] max_memory](https://una-lang.org/en/docs/configure/run/max_memory.md)
- [ita.una](https://una-lang.org/en/docs/configure/ita/manifest.md)
- [Versions, resolution and cooldowns](https://una-lang.org/en/docs/configure/ita/versions.md)
- [Path dependencies](https://una-lang.org/en/docs/configure/ita/path-dependencies.md)
- [ita.lock](https://una-lang.org/en/docs/configure/ita/lock.md)
- [Authority of a dependency: may](https://una-lang.org/en/docs/configure/ita/authority.md)
- [Trust a dependency adds: trust](https://una-lang.org/en/docs/configure/ita/trust.md)
- [Registry dependencies](https://una-lang.org/en/docs/configure/ita/registry.md)
- [Offline builds](https://una-lang.org/en/docs/configure/ita/offline.md)
- [una ita](https://una-lang.org/en/docs/configure/ita/commands.md)
- [una migrate](https://una-lang.org/en/docs/configure/ita/migrate.md)
