Home / Docs / Una for agents / Schemas

una.migrate/1

Release v0.4.0

una.migrate/1 is a JSON document of the Agent ABI, defined in spec/30 §8. 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.

Migration: una migrate

From spec/30 §8, in full.

una --json migrate --dry-run of a package hello of edition 0.3, with a module and no verification.lock, prints one una.migrate/1 document (rule 8):

json
{
  "schema": "una.migrate/1",
  "dry_run": true,
  "written": [],
  "removed": [],
  "name": {"from": "hello", "to": "hello"},
  "edition": {"from": "0.3", "to": "0.4"},
  "default_lock": true,
  "comments_not_carried": [],
  "ita_una": "ita hello\n  version 0.1.0\n  edition 0.4\n",
  "ita_lock": "-- Written by `una ita`; do not edit.\nlock 1\n\nsolver\n  encoding \"una-smt-1\"\n  name \"z3\"\n  version \"5.1.0\"\n  logic \"QF_UFLIA\"\n  steps 5000000\n  seed 0\n",
  "diagnostics": []
}
  1. Edition 0.4 and later are not written in una.toml. una.toml naming edition = "0.4", or (ADR 0139) edition = "0.5", is U7002 at the value, with the repair una migrate; the package is still checked in the edition it names. No released una accepted that form, so this changes no released form (ADR 0122 Question 8.1).

  2. una migrate [path] [--dry-run] [--name <name>] moves the package at path, . by default, from una.toml and verification.lock, of any edition from 0.1 to 0.5, to ita.una and ita.lock of edition 0.4, or of edition 0.5 when una.toml names it, since no migration lowers an edition, and nothing else: a directory that already has ita.una, or that is not a package with una.toml and src/, is a usage error (exit code 2).

  3. What it maps.

    una.toml / verification.lock ita.una / ita.lock
    [package] name = "events-example" ita events_example: - becomes _; a name that is still not a package name needs --name
    version, edition, profile head lines; edition becomes 0.4, or stays 0.5; a version that is not MAJOR.MINOR.PATCH is refused; profile is written when it is systems
    [labels] categories labels, one per line
    [trusted] modules trusted
    [escape_budget] checked_per_module escapes, checked per module <n>, when not 0
    [boundaries] boundaries, with may lines
    [contracts] contracts, the clause strings as lines
    [run] entry, grants run, entry, grants with one line per spec, as files "data/" read, write
    [run] max_memory max_memory, in run after entry
    verification.lock the solver section of ita.lock; the release's default when the package has none

    A text is written with ", \, { and } escaped, and every control or bidirectional character as \u{…}.

  4. Comments. A run of comment lines of una.toml directly before a table header or a key is carried, as -- comments, above the line it becomes. Every other comment is listed in the output, with its line.

  5. Refusals. An invalid una.toml, other than its edition 0.4 or 0.5, or an invalid verification.lock is refused, with each problem printed, and nothing is written (exit code 2).

  6. Writing. It writes ita.una and ita.lock, each through a temporary file and a rename, rewrites each module in the canonical form of edition 0.4 (spec/15 §2), which edition 0.5 keeps, reading it with the keywords of the edition it writes (#1744), then removes una.toml and verification.lock. The canonical form of edition 0.4 wraps long lines, which earlier editions never do (ADR 0125, amendment of 2026-10-25): a module that differs from that form is written through a temporary file and a rename, and listed in written by its path. For a module that was canonical in its own edition, the rewrite changes only white space. A module with a syntax error in that edition has no canonical form and is left as it is. The rewrite is one check of the package, as una fmt does.

  7. The clashes of the edition. It then checks the package, with its modules rewritten, at tier 0 in the edition of the ita.una it wrote, and prints every diagnostic the change of edition causes, those the package has in that edition and not in its own, with their repairs, such as a function named within (U0103). It applies none: una fix does that. Its exit code is 0: the diagnostics are the next steps of the migration.

  8. Output. --dry-run prints the two files and the diagnostics, and writes nothing. --json prints one document, una.migrate/1: schema first, then dry_run, written, removed, name (from, to), edition (from, to), default_lock, comments_not_carried (line, text), ita_una and ita_lock (the files' texts with --dry-run, null otherwise), and diagnostics.