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
}
  1. una ita. The package manager is the command una ita of the una binary. The same binary invoked under the name ita (its argv[0] basename, ita or ita.exe) behaves as una ita: ita lock is una ita lock. With --json, each command prints one document, una.ita/1: schema first, then command, written (the files it wrote) and diagnostics; a command that resolves (lock, update, add, remove) also gives changes, the review of §10 rule 8, after written, and error last, the reason it failed outside its diagnostics, such as a file it could not write, or null, and tree gives root and packages in place of written (§12 rule 9). The exit code is 1 when a diagnostic is an error, and 2 for a usage error, such as a directory without ita.una.
  2. 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>]… and una 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] and una 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] and una ita unbundle <file> [path] (§15). una ita key joins later.
  3. 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.

  1. 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.

Versions and resolution

From spec/30 §10, the parts that name this schema.

  1. 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.

Path dependencies in the program

From spec/30 §12, the parts that name this schema.

  1. 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, one una.ita/1 document with schema, command ("tree"), root, packages, the report's dependencies, and diagnostics. una ita remove <name> [path] removes the need of name from ita.una, with its indented lines, and the needs section when it empties, edited on the text as read, \r\n as \n; then resolves as una ita lock does and, only when the resolution succeeds, writes the lock and then ita.una, each through a temporary file and a rename, putting the lock back when ita.una cannot be written. A name the root does not need, or an ita.una that does not parse, is a usage error and nothing is written. Neither opens a connection.