---
title: "30.2 ita.una"
url: https://una-lang.org/en/docs/spec/30-packages/2-ita-una/
release: v0.4.0
source: https://github.com/una-lang/una/blob/v0.4.0/docs/spec/30-packages.md
---

# 30.2 ita.una

1. **The package.** A package of edition `0.4` and later is a directory with `ita.una` and `src/`; its modules are `src/**/*.una`, as in `spec/13 §7`. A directory with both `ita.una` and `una.toml` is U7008 at `ita.una`, so a package never has two manifests that could disagree.
2. **Grammar.**

   ```ebnf
   manifest     = head { section } ;
   head         = "ita" pkg_name NEWLINE INDENT head_line { head_line } DEDENT ;
   head_line    = "version" version_lit NEWLINE
                | "edition" version_lit NEWLINE
                | "profile" ( "app" | "systems" ) NEWLINE
                | "about" text_lit NEWLINE
                | "license" text_lit NEWLINE
                | "home" text_lit NEWLINE
                | "publish" "to" lower_ident NEWLINE ;
   section      = sources | needs | replace | trust | labels | trusted | escapes
                | boundaries | contracts | run | drive | serve ;
   sources      = "sources" NEWLINE INDENT source { source } DEDENT ;
   source       = lower_ident text_lit NEWLINE INDENT "root" text_lit NEWLINE
                  [ "owners" lower_ident { "," lower_ident } NEWLINE ] DEDENT ;
   needs        = "needs" NEWLINE INDENT need { need } DEDENT ;
   need         = pkg_name [ version_lit ] [ "as" lower_ident ] [ origin ] NEWLINE
                  [ INDENT need_line { need_line } DEDENT ] ;
   pkg_name     = lower_ident [ "/" lower_ident ] ;
   origin       = "from" ( lower_ident | "path" text_lit | "workspace" ) ;
   need_line    = "may" cap_type { "," cap_type } NEWLINE
                | "avoid" version_lit NEWLINE
                | "accept" "name" NEWLINE ;
   cap_type     = qualified_upper "[" lower_ident { "," lower_ident } "]" ;
   qualified_upper = { lower_ident "." } upper_ident ;
   replace      = "replace" NEWLINE INDENT
                  { pkg_name version_lit "with" origin NEWLINE } DEDENT ;
   trust        = "trust" NEWLINE INDENT { trust_line } DEDENT ;
   trust_line   = pkg_name [ major ] [ "from" lower_ident ]
                  "modules" module_path { "," module_path } NEWLINE
                  [ INDENT { "may" cap_type { "," cap_type } NEWLINE } DEDENT ] ;
   major        = int_lit | version_lit ;
   labels       = "labels" NEWLINE INDENT { upper_ident NEWLINE } DEDENT ;
   trusted      = "trusted" NEWLINE INDENT { module_path NEWLINE } DEDENT ;
   escapes      = "escapes" NEWLINE INDENT "checked" "per" "module" int_lit NEWLINE DEDENT ;
   boundaries   = "boundaries" NEWLINE INDENT { module_path NEWLINE
                  [ INDENT { "may" cap_type { "," cap_type } NEWLINE } DEDENT ] } DEDENT ;
   contracts    = "contracts" NEWLINE INDENT { module_path NEWLINE
                  INDENT uses_item { uses_item } DEDENT } DEDENT ;
   run          = "run" NEWLINE INDENT [ "entry" module_path NEWLINE ]
                  [ "max_memory" int_lit NEWLINE ]
                  [ "grants" NEWLINE INDENT grant { grant } DEDENT ] DEDENT ;
   grant        = ( "console" | "clock" | "env"
                  | "keys" text_lit
                  | "files" text_lit file_mode { "," file_mode }
                  | "http" text_lit [ http_method { "," http_method } ] ) NEWLINE
                  [ INDENT limit_line { limit_line } DEDENT ]
                | serve_grant ;                          (* spec/31 §2 rule 3 *)
   file_mode    = "read" | "write" ;
   http_method  = "get" | "post" | "put" | "delete" ;
   limit_line   = "at" "most" int_lit ( "per" ( "second" | "minute" | "hour" ) | "at" "once" ) NEWLINE
                | "waiting" "at" "most" int_lit NEWLINE ;      (* spec/27 §9 *)
   drive        = "drive" NEWLINE INDENT "module" module_path NEWLINE
                  "ticks" int_lit NEWLINE [ "budget" int_lit NEWLINE ] DEDENT ;
   serve        = "serve" NEWLINE INDENT "module" module_path NEWLINE
                  [ "within" int_lit NEWLINE ] DEDENT ;
   ```

3. **Closed.** Every section and every line has one of the forms above; anything else is U7008 at the line. The head's lines appear at most once each, `version` and `edition` required. Each section appears at most once, in the order of the production `section`; a repeated or misplaced section is U7008. There is no `foreign` section and no foreign grant, and no `git` origin: each is U7008.
4. **The head.**
   - `ita <name>`: `name` is a `lower_ident` with no `__` and no trailing `_`, of at most 64 bytes, or `owner/name` with an owner of 2 to 39 bytes by the same rule.
   - `version` is a full version, `MAJOR.MINOR.PATCH` with an optional pre-release, each numeric part at most 2^31 − 1, and no build metadata.
   - `edition` is `0.4` or a later edition the release serves. An earlier edition is U7008: that package keeps `una.toml`.
   - `profile` is `app`, the default, or `systems` (ADR 0109): a `systems` package with `entry` declares `max_memory`.
   - `about` and `license` are non-empty texts, `home` an `https://` URL, and `publish to` names `itaty` or a source name that `sources` could declare, never `path`, `git` or `workspace`. A published package has no `sources` section (§15 rule 1), so the source is not checked when `ita.una` is read: `una ita publish` and `una ita yank` check it against the `sources` of the nearest workspace whose `itaty.una` lists the package as a member, after the package's own refusals and its check (§15 rule 3) and before its archive is built or anything is sent, and refuse a source no such workspace declares (U7013). The `ita.una` of a published archive, read at fetch or by `una check`, therefore accepts its `publish to` line.
5. **The sections that `una.toml` has.** Each has the meaning and the checks of `spec/13 §7` and of the records it names. Every error that `spec/13 §7` makes U7002 for a key of `una.toml` is U7008 at the corresponding line of `ita.una`; the codes of other domains stay (U1005 and U1002 for categories, U7005 for trusted modules).
   - `labels`: the categories, one per line.
   - `trusted`: the trusted modules, one per line.
   - `escapes`: `checked per module <n>`, `[escape_budget] checked_per_module`.
   - `boundaries` (ADR 0093): a module path, then its ceiling as `may` lines; no `may` line is the empty ceiling.
   - `contracts` (ADR 0092 rule 8): a function's qualified name, then its locked `uses` clauses, one per line, each parsed by the production a header uses.
   - `run`: `entry`, then `max_memory`, the declared memory budget in MiB from 1 to 4096 (`[run] max_memory`, ADR 0109 rule 4), then `grants`, one grant per line, each the grant spec of `spec/13 §5` it corresponds to: `console`, `clock`, `env`, `keys "<file>"`, `files "<path>" read, write`, and `http "<origin>" get, post`; and `serve "<origin>"` with its item lines (`spec/31 §2` rule 3), whose problems are U7008 at their lines. Paths resolve against the package root. A `max_memory` outside that range, and a `systems` package with `entry` and no `max_memory` (at the `entry` line), are U7008.
   - The limit lines under an `http` grant (ADR 0117 rule 8) have the forms and the meaning of `spec/27 §9`: `at most <n> per second`, `minute` or `hour`, `at most <n> at once`, and `waiting at most <n>`. A line of another form or with lines below it, a count below 1 or above 2^31 − 1, a limit under a grant other than `http`, and a kind of limit given twice are U7008 at the line, or at the count for a count out of range; a grant with such a line is not read, since without its limit it would allow more than written. The lines under a `serve` grant are its items (`spec/31 §2` rule 3), not limit lines. The `drive` section names the module the host drives (`spec/26 §2`): `module`, `ticks` and an optional `budget`, each of `ticks` and `budget` from 1 to 86,400,000 milliseconds; a missing key, a value out of range, a `run entry` beside it and a module that is not in the package are U7008. The `serve` section names the module of the host-driven form of a server and its optional per-request deadline (`spec/31 §7`, ADR 0123 rule 16): `module` and an optional `within` from 1 to 86,400,000 milliseconds; a missing `module`, a value out of range, a `run entry` or a `drive` section beside it and a module that is not in the package are U7008, and a section with such a problem is not read.
6. **Canonical form.** `una fmt ita.una` and `una fmt itaty.una` rewrite the file in its canonical form: two spaces per level; one blank line between top-level blocks and none inside them; the head's lines in the order of the production `head_line`; one space between words, none before `,`, `.`, `:`, `/` or `]`, none after `[`, `.` or `/`, and none between a capability and its `[`; a comment kept before the line it precedes, or two spaces after the line it ends. A line whose tokens this spacing would join into others, such as `1.` before `2`, keeps one space between every two tokens. `una fmt --check ita.una` reports U7001 where the file differs. `una fmt` of a package directory does not touch `ita.una`, and `una fix` never edits `ita.una`, `ita.lock` or `itaty.una`.
