Home / Docs / Una for agents

The loop

Release v0.4.0
  1. Write or edit .una files, then run una fmt <path>. The canonical form is part of the language: una check reports any other layout as U7001, so generated code goes through una fmt before una check.
  2. Check: una --json check <path>. Exit code 0 means the package parses, is canonical, types, respects authority and information flow, and every proof obligation is proven by the solver.
  3. Otherwise read the diagnostics. Each has a code, a one-line message, a primary position and often ranked repairs; a repair with an edit is mechanical: replace the range with replacement. una fix <path> applies the mechanical ones for you, in safe rounds, then formats and prints what remains (--dry-run writes nothing). It never applies an edit that widens authority or visibility (a uses clause, an operation, pub): those are listed as skipped, for you to decide.
  4. When unsure, una explain <code> prints the rule with a failing and a fixed example.
  5. Run the examples with una --json test <path>, list every proof with una --json obligations <path>, and read the build report with una --json report <path>.
sh
una check examples/events
una --json check examples/toolshelf
una fmt --check examples/pantry
una fix --dry-run examples/pantry
una --json test examples/journal
una --json obligations examples/greenhouse
una --json report examples/shortlinks
una explain U3013
una --json explain U5001
una check tests/conformance/verification/postcondition_refuted.una  # exit 1
una trace EVENTS_3
una contract events.checkin.check_in

una build compiles a package into a native executable that behaves as una run (§19):

sh
una build .
./target/una/hello

Exit codes: 0 success; 1 errors in the program, an unproven obligation or a failed example; 2 a usage error, a problem of the invocation reported on stderr without a diagnostic document; 3 an internal compiler error (U8001), which is a bug to report. Problems of una.toml (U7002) and verification.lock (U7004) are diagnostics and exit with 1. With --json, stdout holds exactly one JSON document and stderr stays empty.

20. The Agent ABI

Every command but una lsp takes --json and prints one document whose schema names its shape:

Command Document
una check, una fmt --check una.diagnostics/1
una fix una.fix/1, the edits applied and skipped, and the diagnostics that remain (v0.2)
una obligations una.obligations/1, every obligation with status, goal and hypotheses
una test una.test/1, every example with its outcome and effect trace; una.test/2 for a package of edition 0.3 or later, the same document with the key tests
una run una.run/1, the program's output and trace
una build una.build/1, the native executable's path, or the diagnostics that rejected the package (v0.2, spec/16)
una contract <module.function> una.contract/1, the header, declared or inferred
una trace <REQUIREMENT_ID> una.trace/1, derived functions and their obligations
una report una.report/2, proofs, authority, policy calls, escapes, assumptions, host premises, trusted code, requirements, coverage, native target
una explain <code> una.explain/1
una core una.core/1, the package's Core IR (ADR 0083)
una migrate una.migrate/1, the files written for edition 0.4 and the diagnostics (spec/30 §8)
una ita <command> una.ita/1, the command, the files written and the diagnostics (spec/30 §6)

When the checks reject a package, contract, trace, obligations and report print the una.diagnostics/1 of una check. Diagnostics are sorted by file, position and code; outputs are identical from run to run.

json
{
  "schema": "una.obligations/1",
  "obligations": [
    {
      "id": "ob-17058da2cfca",
      "kind": "postcondition",
      "domain": "semantic",
      "status": "refuted",
      "source": { "file": "double.una", "start": { "line": 4, "col": 11 }, "end": { "line": 4, "col": 21 } },
      "declaration": "demo.double",
      "goal": "result > x",
      "hypotheses": [],
      "cached": true
    }
  ]
}

The build report counts trivial ensures, clauses the solver proves with no hypothesis at all such as ensures result == result, as missing contracts: write contracts that say something about the result.