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

# 30.4 ita.lock

1. **Who writes it.** Only `una ita` and `una migrate` write `ita.lock`, through a temporary file and a rename. Every other command only reads it, and `una fix` and `una fmt` never edit it. It is committed with the package.
2. **Grammar.** The lexical rules of §1.

   ```ebnf
   lock        = "lock" int_lit NEWLINE solver { registry } { package } ;
   solver      = "solver" NEWLINE INDENT
                 "encoding" text_lit NEWLINE "name" text_lit NEWLINE
                 "version" text_lit NEWLINE "logic" text_lit NEWLINE
                 "steps" int_lit NEWLINE "seed" int_lit NEWLINE DEDENT ;
   registry    = "registry" lower_ident NEWLINE INDENT
                 "root" text_lit NEWLINE "checkpoint" int_lit text_lit NEWLINE
                 "last" "root" int_lit text_lit NEWLINE                    (* §9 rule 7 *)
                 { "accepted" lower_ident int_lit { int_lit } NEWLINE }     (* §14 rule 8 *)
                 { "effect" lower_ident int_lit { int_lit } NEWLINE } DEDENT ;
   package     = "package" pkg_name version_lit NEWLINE INDENT
                 "from" lock_origin NEWLINE
                 "digest" text_lit NEWLINE
                 [ "signed" text_lit NEWLINE "logged" int_lit NEWLINE ]
                 [ "replaced" NEWLINE ]
                 { "needs" lower_ident pkg_name version_lit NEWLINE }
                 { "granted" "by" pkg_name [ major "from" lower_ident ] "may" cap_type { "," cap_type } NEWLINE }
                 [ "consented" text_lit NEWLINE ]
                 { "trusted" "modules" module_path { "," module_path } NEWLINE }
                 DEDENT ;
   lock_origin = lower_ident | "path" text_lit | "workspace" text_lit ;
   ```

   - `lock` is the format's version, `1`; a release reads every format version it ever wrote.
   - **The solver section** has the six keys of `spec/12 §9`, in this order and with the same values: `encoding "una-smt-1"`, `name "z3"`, a non-empty `version`, `logic "QF_UFLIA"`, `steps` of at least 1, and `seed`. A solver of another version stays U5003.
   - **Canonical.** Packages are sorted by name, then version, each once, and a package's `needs` lines by name. Every digest is `sha256:` and 64 lowercase hexadecimal digits. A package has both `signed` and `logged`, or neither. A `git` origin is an error.
   - An index of an `accepted` or `effect` line is below the registry's checkpoint size.
   - **`last root <n> "<digest>"`** records the last root version the registry client verified when it wrote the lock, from 1, and its digest (ADR 0122, amendment of 2026-11-03, item 4). Every `registry` section has it, after its `checkpoint` line; a section without it is U7009, with the repair `una ita lock`, since the registry client is in no release and no released lock has a `registry` section. A vendored provenance's root chain MUST hold that version with that digest (§9 rule 7). The lock is in the edit set of whoever can edit a vendored package, so the line authenticates nothing: it makes a cut of the root chain a visible change in a reviewed diff. `una ita lock --check`, which reads at the lock's point after any later root version, keeps the line while the chain it walks holds that version with that digest. `una ita lock --check` also verifies each registry package's provenance, vendored or in Itaoca, as §9 rule 7 does, against a root-version floor of at least the last version of the chain it walks, whether or not that floor is stored: a provenance whose chain ends below it is refused (U7010).
   - Every problem of the file is U7009 at its line.
3. **What reading checks.** Every command that loads the package checks, with no network:
   - **the lock** exists and parses (U7009 at the start of `ita.una` when it is missing, with the repair `una ita lock`);
   - **consistency:** every need of `ita.una`, and every `needs` line of every locked package, is met by a locked package of its name on its major line at a version at least the one required; each package is locked once on its major line; and every locked package is reachable from the root by those needs. Each problem is U7009, at the need or at the package line, with the repair `una ita lock`. The walk costs O((n + p + r) log p) for n needs, p packages and r `needs` lines.
   - **presence, integrity and provenance** of each registry package, as §9 rule 9 states (U7011, U7010).
4. **`una ita lock [path]`** resolves the package at `path`, `.` by default, as §10 states, and writes its lock. The solver section is the existing lock's, or the release's default when the package has none yet. An invalid `ita.una` or `ita.lock`, or a need with no resolution (U7013), is reported and nothing is written, so a pin is never replaced silently.
`una ita lock --check` writes nothing, and reports where the lock is missing or not the one `una ita lock` writes (U7009), and a registry package whose provenance ends below the root version it accepted (U7010). `--dry-run` prints the review of §10 rule 8 and writes nothing.
