Home / Docs / Specification / 30. Packages and dependencies

30.4 ita.lock

Release v0.4.0
  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.