---
title: "30.10 Versions and resolution"
url: https://una-lang.org/en/docs/spec/30-packages/10-versions-and-resolution/
release: v0.4.0
source: https://github.com/una-lang/una/blob/v0.4.0/docs/spec/30-packages.md
---

# 30.10 Versions and resolution

1. **Versions.** Semantic versioning 2.0.0 without build metadata, each numeric part at most 2^31 − 1, ordered by semver precedence. The identity of a package is its source, its name and its major line: `MAJOR` when it is at least 1, `0.MINOR` otherwise. Two major lines of one package are two identities, which may both be in one program.
2. **Requirements.** A need names the least version it admits on its line. A pre-release is selected only if some requirement names a pre-release of that identity. There are no upper bounds and no ranges.

   Which identities admit a pre-release (ADR 0122 rule 22) is a fixed point, computed before the selection: resolution runs in passes, each with a fixed set of admitted identities, the first with those the root's needs name with a pre-release; when a pass reaches a release whose need names a pre-release of an identity outside the set, the identity is added and the pass is run again from the root, until a pass adds none. A need that names a pre-release admits pre-releases of its identity itself, in every pass. The selection is the last pass's, so it does not depend on the order in which needs are walked (rule 3). A pass that fails and admits no new identity reports its least failure, by identity and version, never the first one its walk met; a pass that admits a new identity is run again, since its failure may be a need that only an admitted pre-release meets. The set only grows, so it may admit an identity that only a release of an earlier pass named; a build list that then holds a pre-release of an identity that no need of the last pass names with one has no resolution (U7013).
3. **Minimal version selection.** The build list holds, for each identity reachable from the root, the highest of the versions the reached needs ask for, each read as the least release at or above it; never a newer one. The result does not depend on the order of any list, and a release published later changes nothing until a need asks for it.
4. **Raises.** A selection that is yanked, named by an advisory not fixed in it, or avoided by the root is raised to the least release of its identity above it that is none of these, is not a pre-release unless one is named, and was logged at least the cooldown before the resolution point, 72 hours of witness time by default. An advisory signed by the threshold that names the fix by digest lifts the cooldown for that fix. With no such release, resolution fails, naming the newest candidate the cooldown holds back. The walk resumes with the needs of the release taken.
5. **Bounds.** 100,000 releases visited, each distinct identity and version counted once over every pass of rule 2, and 400,000 visits over every pass together, each pass's visits counted again, so a chain of pre-releases each naming the next, which forces a pass per link, is refused rather than walked quadratically, 10,000 packages in the list, 1,000 needs per release, 10,000 releases read per name; a release that needs its own identity is refused.
6. **Costs.** O(N + R) time and space per pass for N releases reached and R need edges, with hash maps, each release queued once a pass; O(log K) to find the release a need reaches among the K of its identity, pre-releases not admitted stepped over in O(1) through an index of the next release that is not one; O(S) per raise for the S releases it examines; O(P log P) to sort the list. A pass is repeated only when it discovers an identity named with a pre-release beyond the root. There is no backtracking and no search.

7. **What resolution reads.** `una ita` resolves over each path dependency, as its directory holds it, the one release of its identity, whose source is its directory; and over the releases of each source of `sources` that the root needs, read from the registry at a fresh resolution point and verified (§14 rules 2 to 7), each name's whole chain included, so nothing is ever resolved against a partial view of a registry, which could lack a lower release that rule 3 takes or a yank that rule 4 raises past. A need of `itaty`, whose root metadata is not built into this release, is U7013 at the need, and the source is refused as a whole. A need of a workspace member is U7008. An `avoid` line naming the version a path dependency holds has no later release to raise to (U7013). Every bound of rule 5 is U7013, the root's needs counted as a release's. The walk is rule 6's, and the lock's packages are sorted in O(p log p).
8. **The review and consent** (ADR 0122 rule 25). Before a command writes a lock that differs from the one it replaces, it prints one line per package added, changed or dropped, compared by name and origin: `add util 0.2.0 (path deps/util): digest sha256:…; may Console[print]; uses Console[print]`, with `old -> new` for a version, digest or ceiling that changed, `; trust keys; consented sha256:…` after it for a package with trusted modules before or after, with `old -> new` too, and `drop util 0.2.0 (path deps/util)`. A change of the trusted modules or of the consented digest alone is a change. `uses` is what the package's code uses in the new graph, checked at tier 0: the union of the `uses` of its functions and handlers. With `--json`, each line is an entry of `changes`: `change` (`add`, `change` or `drop`), `package`, `origin`, `version_from`, `version_to`, `digest_from`, `digest_to`, `ceiling_from`, `ceiling_to`, `trusted_from`, `trusted_to`, `consented_from`, `consented_to` and `authority`. Each consent flag names what it accepts, and nothing else: a ceiling wider than the one the lock records for the package, matched by name and origin, needs `--accept-authority <package>` (U7009), and a trust that no recorded consent covers for the package's content as it is now needs `--accept-trust <package>@<digest>`, with the content digest of that content (U7012); a consent to another digest is refused and says so. Both flags repeat, one per package. A bare `--accept-authority`, an `--accept-trust` without a digest, an `--accept-authority` naming a package that no need of `ita.una` names, an `--accept-trust` naming one that neither a need nor a trust line of `ita.una` names, and two `--accept-trust` flags of one package with different digests are usage errors. When consent to a ceiling or a trust is missing, the review is printed all the same, `--dry-run` or not, followed by `to accept, after reviewing: una ita <command> <flags>` with the exact flags to copy, and the command refuses with the diagnostics and writes nothing. A file that cannot be written exits with code 1, and an internal error (U8001) with code 3; with `--json` each prints one `una.ita/1` document whose `error` is the message, `null` otherwise. `una ita add` and `una ita remove` take neither flag: their refusals are repaired by `una ita lock` with it.
9. **`una ita update [<name>…]`** raises the named needs, or all, and writes the lock: a named need is resolved again, every other path need that the lock records keeps its entry as recorded, consents included, and every other registry need keeps the version `ita.una` writes, so `update util` raises no other need and needs no consent for another path package. A name the root does not need, or an `ita.una` that does not parse, is a usage error. `--cooldown <hours>` sets the cooldown of rule 4, 72 by default, and `--now` sets none; the two are one choice. A path dependency is always locked as its directory holds it, so `update` locks it again. A registry need is raised in `ita.una` to the newest release of its identity that is not a pre-release (unless the need names one), not yanked, avoided or signed after its key's stated compromise, and logged at least the cooldown before the resolution point; `update` never changes a major line, and only when the resolution succeeds writes the lock and then `ita.una`, putting the lock back when `ita.una` cannot be written. Rule 26 of ADR 0122, that a release needs no authority or trust the highest earlier release of its identity did not, is checked from the release statements (§14 rule 6 and rule 8); for a path dependency, what it may exercise stays bounded by the ceiling the lock records, whose widening needs `--accept-authority <package>` (rule 8).
10. **`una ita add <name> [<version>]`** adds the need `<name> <version> [as <local>] [from <source>]` at the end of `needs`, or in a new `needs` section before the first section that follows it in the canonical order, and locks; it writes no `may` and no `trust` line. Each word is checked before it is written, the name as `name` or `owner/name` in lower case, the version as a version of two or three parts, and `--as` and `--from` as lower-case names (a usage error otherwise); the edited `ita.una` is read as any other (U7008), and, only when the resolution succeeds, the lock is written and then `ita.una`; when `ita.una` cannot be written, the lock is put back with the bytes it was loaded with. A write that fails exits with code 1 and a message. Without a version, it takes the newest release of the newest major line that is not a pre-release, not signed after its key's stated compromise, and logged at least the cooldown before a fresh resolution point, from the registry's verified state (§14), and writes it as a full version; with none, U7013, naming the newest release the cooldown holds back. Without `--from`, a name whose owner a source of `sources` serves is needed from that source, and `add` writes the `from`. A need of `itaty` has no resolution in this release (rule 7), and nothing is written.
11. **`una ita verify [path]`** reads each registry package of the lock again, in the vendor directory and in Itaoca, wherever it is: first its presence (U7011 for a package in neither place), then each copy as §9 rule 9 states (U7010 for a copy that does not verify). A package whose copies all match the lock is still not verified, since the owner's key chain and its name map proof (ADR 0122 rules 36.1 and 36.3) are not held until the registry client supplies them: it is reported unavailable, U7013, naming where its copies matched, in human and `--json` output alike, and the command exits with code 1. It writes and repairs nothing. A path dependency is the root author's working tree, which `una ita lock --check` compares.
