---
title: "30.9 Package content, digest and archive"
url: https://una-lang.org/en/docs/spec/30-packages/9-package-content-digest-and-archive/
release: v0.4.0
source: https://github.com/una-lang/una/blob/v0.4.0/docs/spec/30-packages.md
---

# 30.9 Package content, digest and archive

1. **What a package holds.** Exactly: `ita.una`; every `src/**/*.una`; `README.md`, `CHANGELOG.md`, and files named `LICENSE` or starting with `LICENSE-` or `LICENSE.`. Nothing else: no library, archive or source file of another language, since Una admits no foreign code, and not `ita.lock`. Every path:
   - is relative, of segments `[A-Za-z0-9_.-]+`, none `.` or `..`, none starting with `.`, none ending with `.`, at most 32 segments and 255 bytes;
   - has no segment that is a reserved device name of Windows, with or without an extension, compared ignoring case: `CON`, `PRN`, `AUX`, `NUL`, `COM1` to `COM9`, `LPT1` to `LPT9`;
   - is unique ignoring ASCII case, and is not, ignoring case, a directory prefix of another path (`a` beside `a/b`);
   - names a regular file; no mode bits are kept.

   A package holds at most 10,000 files and 256 MiB.
2. **The listing and the content digest.** The listing of a package is, for each file in ascending byte order of its path: the path's bytes, a NUL byte, the file's length in decimal, a NUL byte, the lowercase hex SHA-256 of its contents, and a line feed. The content digest is `sha256:` followed by the hex SHA-256 of the listing. It depends only on the files' paths and bytes.
3. **The archive.** A package travels as one file: the line `ita-archive/1`, the listing's length in decimal and a line feed, the listing, then each file's bytes in listing order, and nothing after. There is no compression. The reader reads the archive once into memory and parses and hashes those same bytes; it refuses another first line, a length with a leading zero, above 256 MiB or past the end, a listing that holds a carriage return, whose paths are not in strictly ascending byte order or that rule 1 refuses, a file whose hash differs from the listing's, and trailing bytes.
4. **Costs.** The listing sorts the files, O(f log f); the digest and the reader are one pass over the bytes, O(B), with memory O(listing + archive).
5. **Itaoca.** Fetched packages are stored in `packages/sha256/<hex>/` under `~/.una/itaoca`, or the directory `UNA_ITAOCA` names when it is set and not empty; that directory itself MUST NOT be a symbolic link. A package is written once, from the bytes of its archive as rule 3 read and hashed them, into a fresh private directory:
   - the directory has a name of its own, is created with `mkdir`, which fails when anything is there, and has mode 0700; each directory below it is created the same way, and each file with `O_CREAT`, `O_EXCL` and `O_NOFOLLOW`;
   - each file's permissions are set through its open descriptor (read-only in Itaoca), never by path, and each file and each directory is synced;
   - the fresh directory MUST still be the one created, by the device and inode of its descriptor, before each file is written and before it is renamed into place; otherwise the write fails, and a write that fails removes the fresh directory only while it is still the one created, and leaves it otherwise.

   What is written is then loaded as rule 6 states. The provenance of a release at a resolution point (rule 7) is stored once in `registry/<source>/releases/<release>/checkpoint-<size>-2.provenance`, where `<release>` is the release's directory name of rule 8 and `<size>` the checkpoint's size; one of the earlier format `ita-provenance/1`, written before it, is at `checkpoint-<size>.provenance` beside it, is never replaced or removed, is read only when no provenance of format 2 is stored for that point, and is never written where one of format 2 is. Each is written as one file in a fresh private directory and then hard-linked to its name, which fails when any entry, a symbolic link included, is there, so a stored provenance is never replaced; the entry there is then read, and another document of the same format for the same release and point is refused. A store interrupted after the link leaves the file's second link in its fresh directory; when the provenance is next read, a link in a `.una-fresh-*` directory beside it that is the same file, by device and inode, is removed with its directory, and the file must then have one link.
6. **Reading.** A package is read from Itaoca or a vendor directory, on every load and never once for all:
   - every component below the store's or the root's directory, which is resolved once, MUST be a directory and not a symbolic link;
   - the package is listed: every entry is a directory or a regular file with one link; a symbolic or hard link, a device, a FIFO or a socket refuses the package, and so does every path that rule 1 refuses, before any byte of it is read; at most 20,000 entries are listed;
   - each listed file is read once into memory, through a descriptor opened with `O_NOFOLLOW`, and on macOS also `O_NOFOLLOW_ANY`, which MUST be the entry listed, by device and inode;
   - the digest of the bytes read MUST be the lock's before any of them is used, and every later step (the provenance's check, vendoring, checking and building) MUST use those bytes and MUST NOT read a file of the package by its path again.

   So an entry swapped while the package is read can only make the load fail.
   A path dependency's files (§12 rule 1) are each opened with `O_NOFOLLOW` and checked to be the regular file listed. On a platform whose flag values `una` does not know, no package is read or written. Any failure is U7010; nothing is repaired.
7. **Provenance.** Beside each registry package, in Itaoca (rule 5) or the vendor directory (rule 8), its provenance is a document of these parts, in this order: the line `ita-provenance/2`; one to 64 blocks `root <length>`, each a line followed by that many bytes of root metadata (§11 rule 8), the version that the source's pin names first and each next version after it; a block `checkpoint <length>`, the checkpoint of the lock's resolution point with its signature and cosignatures (§11 rule 4); when that checkpoint names a root version older than the last one stored and the client that wrote the provenance completed the proof that it is a prefix of a checkpoint signed under the last version (§11 rule 9), a block `latest <length>`, the latest checkpoint signed under the last stored version that the client read, with its cosignatures, followed by zero to 64 lines `consistency <base64 hash>`, the consistency proof from the point to it (§11 rule 1); a block `statement <length>`, the release statement (§11 rule 6), whose bytes are its log leaf; `index <n>`, the statement's log index; zero to 64 lines `proof <base64 hash>`, its inclusion proof; and `key <name> <base64 key>`, the publisher key the lock names. Lengths and the index are decimals without a leading zero, each block at most 64 KiB, the whole at most 1 MiB, and nothing follows the key line; a document that is not in this one encoding is refused. A document of the earlier format, whose first line is `ita-provenance/1`, has no `latest` block and is still read, since a stored provenance is never replaced (rule 5): it verifies by the same rules, with no proof. A provenance verifies, offline and with nothing taken on the lock's word, when:
   - the first root metadata has the digest the lock records for the source, which MUST be the root that `ita.una`'s `sources` pins, and the threshold of its own root keys; each next version meets §11 rule 8; the chain holds the version the lock's `last root` line records, with its digest (§4); and the last stored version is not below the root-version floor that Itaoca stores for the registry's identity (§14, Floors), which every load reads, so a provenance whose later root versions were dropped, those that retire or revoke a witness, never loads where a later version was accepted. When the floor stores a digest (§14, Floors), the chain MUST also hold the floor's version with that digest: a chain whose version of the floor has other root metadata is a fork of the root chain, refused (U7010) with a message that says the root chain forked; a floor of the earlier form, the version alone, is compared by version only. A chain below the floor is refused (U7010), and the message says that the provenance's root chain is older than the root version this machine has accepted, never that the log forked; the repair is to lock again at a fresh resolution point, which writes a new provenance, and nothing is rewritten in place. A floor that exists and cannot be read, such as a file in neither form of §14, makes the load unavailable (U7013), never a load without it: an offline load has no registry to fall back on, unlike the online commands, for which such a floor is a note (§14);
   - when the provenance carries a `latest` block, the checkpoint names a root version older than the last stored one, and the latest checkpoint names the last stored version, is of that version's log key name and signed by that key, is cosigned by that version's threshold of its witnesses (§11 rule 9), is larger than the point, since a checkpoint of the point's size naming another version is a second checkpoint of that size, and the consistency proof shows the point its prefix; anything carried that does not verify is refused (U7010), the log having forked or the document having been edited. A `latest` block carried short of cosignatures, or with consistency hashes missing, edited or added, is such a proof, refused (U7010), never unavailable: offline there is no other place to read the rest from. Only a proof that is absent, no `latest` block at all, makes the load unavailable (U7013), and only when the checkpoint carries a retired witness's cosignature (below). A `latest` block beside a checkpoint that names the last stored version is refused;
   - the last stored version has not expired (§11 rule 5) at the witness time of the latest checkpoint carried, which the current witnesses cosign, or, with none carried, at the checkpoint's witness time;
   - the checkpoint's size and root hash, `sha256:` and its hex, are the lock's `checkpoint` line; its origin is the name of the log key of the root version it names (§11 rule 9); it is signed by that key; and it is cosigned by at least k distinct witnesses that count as §11 rule 9 counts them: a witness of the last stored version counts; a witness of the version it names that the last one retired counts only when the consistency proof of the `latest` block is verified at this load (ADR 0122, amendment of 2026-11-03), never on the word of the client that wrote the provenance; a witness whose fingerprint any stored version lists in `witnesses-revoked` never counts (§11 rule 8); and k is the larger of the named version's witness threshold and the last stored version's, so a provenance that holds a later root version is never counted by fewer witnesses, or by a revoked one, than that version allows. When the checkpoint carries a cosignature of a retired witness that no stored version revokes and the provenance carries no `latest` block, as one of format 1 never does, the load is unavailable (U7013), never decided on fewer cosignatures, whatever the witnesses of the last stored version alone would give; a checkpoint with no such cosignature is counted on the witnesses of the last stored version;
   - the statement names the lock's source, name and version and gives the lock's digest; its `manifest` is the digest of the package's `ita.una`, `sha256:` and the hex SHA-256 of its bytes; it is signed by the key stored, whose `signed` form is the lock's: `ed25519:`, the name's owner (`itauna` for a name without one), `:`, and the hex SHA-256 of the public key; and its leaf is included in the checkpoint at the lock's `logged` index.

   Verifying costs O(R + W + log L), for R root versions walked, W signature lines of the point and the latest checkpoint, and O(log L) hashes for the inclusion and the consistency proofs in a log of L entries.

   **Trust on first use.** The floor holds only as far as this machine stores it. Past it, and on a machine whose Itaoca holds no floor for the registry, or that has no Itaoca at all (a fresh clone, or a run that starts empty), the whole vendored root chain past the pin is trusted on first use: whoever edits the vendored package, its provenance and the lock together can drop root versions there that this machine never accepted, and their retired witnesses then count as current ones. `una ita lock --check` refuses such a cut against the last root version that the chain it reads at the lock's point holds, whether or not it stores the floor (§4); `una ita fetch` reads the registry and stores the floor (§14), and the next offline load refuses a provenance below it.

   The owner's key chain and the per-name state at the resolution point (ADR 0122 rules 36.1 and 36.3) are verified by the registry client when the release is resolved and when it is fetched (§14), with the key the statement is signed by valid at its log position; they are not stored beside the package in this release, so loading verifies the provenance above and does not walk them again. A package of `itaty`, whose root metadata is built into `una` and is not in this release, does not verify.
8. **Vendoring.** `una ita vendor [path]` copies each registry package of the lock from Itaoca into `vendor/ita/<source>/<release>/` of the package at `path`, `.` by default, where `<release>` is `<owner>+<name>-<version>`, or `<name>-<version>` for a name without an owner, with its provenance beside it in `vendor/ita/<source>/<release>.provenance`. The copy is written from the verified bytes of Itaoca's copy (rule 6) into a fresh private directory as rule 5 writes, with its files writable, renamed into place, and loaded as every command loads it (rule 9); the provenance is written the same way, as one file. A symbolic link at `vendor`, `vendor/ita` or `vendor/ita/<source>` refuses the copy (U7010), and nothing is written through it. A copy already there that verifies is kept; one whose files verify and whose provenance is missing or does not verify takes Itaoca's provenance; one whose files do not verify is U7010 and is left as it is. A package Itaoca does not hold is U7011. Path dependencies are not copied: they are read from their directory. An invalid `ita.una` or `ita.lock` is reported and nothing is written. With `--json` it prints one `una.ita/1` document whose `written` lists the directories and files written, relative to the package.
9. **What loading checks.** Every command that loads a package of edition `0.4` and later whose lock reads checks each registry package of the lock, with no network, at its line of `ita.lock`:
   - **presence:** it is in the vendor directory or in Itaoca; otherwise U7011. The commands that check, run, build, test or report a package, and the language server, look in Itaoca; the others look in the vendor directory only;
   - **integrity and provenance:** read from the vendor directory when it holds the package, else from Itaoca, it meets rules 6 and 7; otherwise U7010, or U7013 when rule 7 makes the load unavailable: a retired witness's cosignature without the consistency proof, or a root-version floor that cannot be read. A vendored copy that fails is not replaced by Itaoca's. Itaoca holding the package's files without its provenance at the lock's resolution point is an inconsistent store, U7010, not an absence. A file a package may not hold, such as a `.DS_Store`, is U7010 with its path named.

   A package of `itaty` is not checked in this release: its root is not built in yet, so it cannot verify, and its need is refused (§3 rule 4), so it never loads. The check applies to it once that root lands. A release that loads verified and that a need of the root names is mounted (§14 rule 10). A load's result for a registry package is one of: it loads; U7011, absent; U7010, refused; or U7013, unavailable. Each of the three is an error at the package's line of `ita.lock`, the package is not mounted, and `una check`, `una build`, `una run` and `una test` end with exit code 1, as `una ita verify` does for a package it cannot verify; `una ita fetch` fetches again a package whose stored provenance is unavailable, and stores the registry's provenance of format 2 beside it (rule 5).

   So a repository with its vendor directory and lock committed builds with `una` alone, and a change that edits a vendored package together with its digest, key and checkpoint does not load: it would need the root's, the log's and the witnesses' keys.
10. **No connection.** `una check`, `una run`, `una build`, `una test`, `una report`, `una core`, `una lsp`, `una migrate`, `una fmt` and `una fix` never open a connection for a package or read a registry; only `una ita lock` (with `--check`), `update`, `add`, `fetch`, `bundle`, `audit`, `watch` and `unbundle` read one, from a mirror directory (§14). A program whose locked packages are present gives the same result with or without a network. Only a program that `una run` grants `http` reaches the network, through its `Http` capability (`spec/24`).
