Home / Docs / Una for agents / Schemas
una.ita/1
Release v0.4.0
una.ita/1 is a JSON document of the Agent ABI, defined in spec/30 §6. This page gathers what the specification says about it at v0.4.0: each section whole where it opens with the document, and otherwise the parts that name it.
Commands
From spec/30 §6, in full.
With --json, each command of una ita prints one una.ita/1 document (rule 1). una --json ita lock of a package whose ita.una adds the path dependency util (§12 rule 6) prints:
json
{
"schema": "una.ita/1",
"command": "lock",
"written": ["ita.lock"],
"changes": [
{
"change": "add",
"package": "util",
"origin": "path deps/util",
"version_from": null,
"version_to": "0.2.0",
"digest_from": null,
"digest_to": "sha256:628a11aacf38c392c3224401a087d357fbee26abf719488dfdaec055872f1764",
"ceiling_from": "",
"ceiling_to": "",
"trusted_from": [],
"trusted_to": [],
"consented_from": null,
"consented_to": null,
"authority": []
}
],
"diagnostics": [],
"error": null
}una ita. The package manager is the commanduna itaof theunabinary. The same binary invoked under the nameita(itsargv[0]basename,itaorita.exe) behaves asuna ita:ita lockisuna ita lock. With--json, each command prints one document,una.ita/1:schemafirst, thencommand,written(the files it wrote) anddiagnostics; a command that resolves (lock,update,add,remove) also giveschanges, the review of §10 rule 8, afterwritten, anderrorlast, the reason it failed outside its diagnostics, such as a file it could not write, ornull, andtreegivesrootandpackagesin place ofwritten(§12 rule 9). The exit code is 1 when a diagnostic is an error, and 2 for a usage error, such as a directory withoutita.una.- Commands of this release.
una ita lock [--check [--fresh]] [--dry-run] [--accept-authority <package>]… [--accept-trust <package>@<digest>]… [--accept-key <package>]… [path](§4 rule 4, §10 rules 7 and 8, §12 rule 6, §13 rule 2, §14 rule 8);una ita update [<name>…] [--cooldown <hours>] [--now] [--dry-run] [--accept-authority <package>]… [--accept-trust <package>@<digest>]… [--accept-key <package>]…anduna ita add <name> [<version>] [--as <local>] [--from <source>] [--now] [--dry-run], on the package in the current directory (§10 rules 9 and 10);una ita tree [path]anduna ita remove <name> [path](§12 rule 9);una ita fetch [path](§14 rule 9);una ita vendor [path](§9 rule 8);una ita verify [path](§10 rule 11);una ita publish [path],una ita yank <version> [path],una ita audit [path],una ita watch <owner> [<name>…] [--from <source>],una ita bundle <file> [path]anduna ita unbundle <file> [path](§15).una ita keyjoins later. - No network, no other program. No command of this release opens a network connection: a registry is read from a local mirror directory (§14 rule 1), a submission to an
https://source stops before anything is sent (§15 rule 1), and a bundle goes through a file. Itá never starts another program.
Package content, digest and archive
From spec/30 §9, the parts that name this schema.
- Vendoring.
una ita vendor [path]copies each registry package of the lock from Itaoca intovendor/ita/<source>/<release>/of the package atpath,.by default, where<release>is<owner>+<name>-<version>, or<name>-<version>for a name without an owner, with its provenance beside it invendor/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 atvendor,vendor/itaorvendor/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 invalidita.unaorita.lockis reported and nothing is written. With--jsonit prints oneuna.ita/1document whosewrittenlists the directories and files written, relative to the package.
Versions and resolution
From spec/30 §10, the parts that name this schema.
- 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], withold -> newfor a version, digest or ceiling that changed,; trust keys; consented sha256:…after it for a package with trusted modules before or after, withold -> newtoo, anddrop util 0.2.0 (path deps/util). A change of the trusted modules or of the consented digest alone is a change.usesis what the package's code uses in the new graph, checked at tier 0: the union of theusesof its functions and handlers. With--json, each line is an entry ofchanges:change(add,changeordrop),package,origin,version_from,version_to,digest_from,digest_to,ceiling_from,ceiling_to,trusted_from,trusted_to,consented_from,consented_toandauthority. 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-trustwithout a digest, an--accept-authoritynaming a package that no need ofita.unanames, an--accept-trustnaming one that neither a need nor a trust line ofita.unanames, and two--accept-trustflags 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-runor not, followed byto 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--jsoneach prints oneuna.ita/1document whoseerroris the message,nullotherwise.una ita addanduna ita removetake neither flag: their refusals are repaired byuna ita lockwith it.
Path dependencies in the program
From spec/30 §12, the parts that name this schema.
una ita tree [path]checks the program at tier 0 and prints the root's name and version, then one line per dependency, in the form of the report's human line; with--json, oneuna.ita/1document withschema,command("tree"),root,packages, the report'sdependencies, anddiagnostics.una ita remove <name> [path]removes the need ofnamefromita.una, with its indented lines, and theneedssection when it empties, edited on the text as read,\r\nas\n; then resolves asuna ita lockdoes and, only when the resolution succeeds, writes the lock and thenita.una, each through a temporary file and a rename, putting the lock back whenita.unacannot be written. A name the root does not need, or anita.unathat does not parse, is a usage error and nothing is written. Neither opens a connection.