Home / Docs / Una for agents
The loop
- Write or edit
.unafiles, then rununa fmt <path>. The canonical form is part of the language:una checkreports any other layout as U7001, so generated code goes throughuna fmtbeforeuna check. - 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. - Otherwise read the diagnostics. Each has a
code, a one-linemessage, aprimaryposition and often rankedrepairs; a repair with aneditis mechanical: replace the range withreplacement.una fix <path>applies the mechanical ones for you, in safe rounds, then formats and prints what remains (--dry-runwrites nothing). It never applies an edit that widens authority or visibility (ausesclause, an operation,pub): those are listed asskipped, for you to decide. - When unsure,
una explain <code>prints the rule with a failing and a fixed example. - Run the examples with
una --json test <path>, list every proof withuna --json obligations <path>, and read the build report withuna --json report <path>.
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_inuna build compiles a package into a native executable that behaves as una run (§19):
una build .
./target/una/helloExit 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.
{
"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.