Configure a package
events/
una.toml
verification.lock
src/
events/
types.una
seating.una
keys.una
checkin.una
main.unauna.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.2has the memory model (§5.5, §5.6), fixed-width integers (§3.1), recursive kinds (§3.2), constraints (§3.3), effect polymorphism (§4.2) andtogether(§5.7). Edition0.1keeps the language of v0.1 in every version of the compiler. A single.unafile has the default settings, and so edition0.1. Edition0.3is a preview: it has everything of edition0.2, and the rules of ADRs 0092 to 0094 join it as they land, which only ever adds errors. Edition0.4, inita.una, is the preview of this release: it adds tasks and time,for ever, driven programs, HTTP servers and dependencies through Itá (Edition). verification.lockpins the solver so that proofs are reproducible.- Unknown keys in
una.tomlare 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).
[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.tomlandsrc/; otherwise the command stops with a usage error (exit code 2). Its modules are the filessrc/**/*.una, hidden entries excepted, and the module insrc/a/b/c.unaMUST be declaredmodule 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,versionandedition, non-empty strings;editionis"0.1". (v0.2, ADR 0056.)editionis"0.1"or"0.2". The constructs of spec/17, spec/18, spec/19 and spec/20 and the keywords of edition0.2exist 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.)
editionis"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 edition0.2holds in every later edition, unless it says otherwise. The rules that target edition0.3(ADRs 0092, 0093 and 0094) apply only in packages of edition"0.3". - Edition
0.3is a preview until every rule that targets it has landed. Until then, a later0.3.xrelease MAY add obligations or errors to an edition0.3package: the edition only ever gets stricter, never looser. (ADR 0056 amendment of 2026-10-13, second.) Stricter concerns the programs that edition0.2can express: such a program keeps its result or gains obligations or errors. A later0.3.xrelease MAY also accept a construct that a rule targeting edition0.3adds 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 edition0.2accepts, with no fewer allowed behaviors. Editions0.1and0.2keep 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 later0.3.xrelease MAY also give the methodsmeasured(),magnitude()andconvert()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 later0.3.xrelease MAY also accept refined type arguments, and the facts on access they give, in a package of edition0.3(spec/03 §3); such a package can then be accepted where edition0.2rejects it, on facts the obligations of spec/12 §3 prove. (ADR 0114.) A later0.3.xrelease MAY also accept the typeF64and the constructs of spec/29, in a package of edition0.3; they do not erase to edition0.2. A program that edition0.2can express gains from them only U1002, for a declaration namedF64and for a package functionto_f64on integers, which the built-in conversion resolves ahead of. - (v0.4, ADR 0116 rule 0, and ADR 0122 Question 8.1.) Edition
0.4is named inita.una(spec/30), not here:edition = "0.4"inuna.tomlis U7002, withuna migrateas its repair, and the package is still checked in edition0.4. Edition"0.4"has every construct, keyword and rule of edition"0.3". Edition0.4is a preview under the same terms until a release makes it stable by the stabilizing record of ADR 0121 rule 15. Releasev0.4.0ships 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 edition0.3, is an identifier in edition0.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 edition0.4: they moved to edition0.5, and since no release accepted them in edition0.4, they moved with no diagnostic of their own. In a package of edition0.4, each of them gets what edition0.3gives it, such as U1001 forimport std.collectionsand forMap.update, U0101 forDecimal[2]and for awith:orand:label, U0103 forsimdas a name and U2002 forArrayorDecimalas a type, each a variant ofJsonthere. These carry advice that names edition0.5, a description that nouna fixapplies, as "F32exists from edition 0.5 (ADR 0139): writeedition 0.5in ita.una to use it": U1001 at an unknown name that edition0.5declares (F32,Matrix,Complex, ...), at the module pathstd.collectionsand atm.update(...)on aMap; U0101 at the scale ofDecimal[s]and at awith:orand:label; U0103 atsimd, after its rename; and the message of U2002 atArrayorDecimalas a type (#1743). The other diagnostics of moved constructs carry none, such as U1001 at the conversionsto_f32andto_decimalon an integer or anF64.F64and spec/29 §1 to §15 stay in edition0.3. - (v0.5, ADR 0139 rules 2 and 6.) Edition
0.5is named inita.unatoo:edition = "0.5"inuna.tomlis U7002, withuna migrateas its repair, which keeps edition0.5(spec/30 §8), and the package is still checked in edition0.5. Edition"0.5"has every construct, keyword and rule of edition"0.4". Edition0.5is 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 releasev0.5.0. The constructs ofspec/28and 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 editions0.1to0.4, is an identifier in edition0.5(spec/01 §5). The keywordswithandand, right before:, are also argument labels in a call in edition0.5, as ina.dot(with: b)(spec/29 §17).
- (v0.3, ADR 0056 amendment of 2026-10-13.)
-
[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 saystrusted 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, andgrants, an array of the grant specs of §5. -
(v0.3, ADR 0092 rule 8 and its third amendment.)
[contracts], in edition0.3only: each key the qualified name of a public function of the package, each value an array ofusesclauses 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 aBoolof the refinement language over the function's parameters are U7002 at the entry. (ADR 0094.) An entry MAY writegivesand a label after an operation, before its condition, as a header does; a category that[labels] categoriesdoes not declare is U7002 at the entry, and the entry is not read. spec/05 §3 rule 5 checks the header against it. In editions0.1and0.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.bcoversa.b.c, nota.bc. Each value is the module's ceiling: an array of names-only stringsC[op, ...], with at least one operation, each once, and no condition or label, whereCis a capability that the key's module sees and eachopone 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] modulesinside a boundary, and a[run] entryinside 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] profileis"app"or"systems"; any other value is U7002. Without the key, the profile isapp, and a single file isapp. In editions"0.1"and"0.2", the key is unknown and U7002, and their packages areapp.[run] max_memory, in edition"0.3"only, is the package's memory budget in MiB, from 1 to 4096 while edition0.3is a preview (U7002 outside); in editions"0.1"and"0.2"it is an unknown key (U7002). Asystemspackage with a[run] entryand without[run] max_memoryis U7002 at the entry; anapppackage may declare it too, with the same meaning. With the key, the value is the budget ofuna run, ofuna test, and of the native executable, which bakes it in at build time:--max-memorymay lower it, never raise it, and a larger value is a usage error (exit code 2). Without the key, in either profile,--max-memorykeeps 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.tomlthat 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 auna.tomlwith 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[package] version[package] edition[labels] categories[trusted] modules[escape_budget] checked_per_module[run] entry[run] grants[boundaries]verification.lock[contracts][package] profile[run] max_memoryita.unaVersions, resolution and cooldownsPath dependenciesita.lockAuthority of a dependency: mayTrust a dependency adds: trustRegistry dependenciesOffline buildsuna itauna migrate