---
title: "The loop"
url: https://una-lang.org/en/docs/agents/loop/
release: v0.4.0
source: https://github.com/una-lang/una/blob/v0.4.0/docs/guide/una-for-agents.md
---

# The loop

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.
