---
title: "una.core/1"
url: https://una-lang.org/en/docs/agents/schemas/una.core-1/
release: v0.4.0
source: https://github.com/una-lang/una/blob/v0.4.0/docs/spec/13-diagnostics-and-abi.md
---

# una.core/1

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

## Syntax

From `spec/09 §2`, the parts that name this schema.

(S-39, ADR 0116 amendment of 2026-11-06.) Core IR gains `quiet e`, in every edition: the loops, deadlines and task constructs below exist in edition `0.4` and later only, but calls, operations and `with` exist in every edition, and elaboration marks them in every edition (`spec/26 §6` rule 4). The form `quiet e` is written where `e` is a `for ever` loop, a `within`, a `first of`, a `tasks`, `together` or `together for` expression, a `with` that installs a handler (S-41), a `start` (S-40, #1512), or a `let` of a call or an operation, ending in its result. Elaboration writes it when `e` stands under a program counter above `public`: for a call, when its callee can run one of those constructs, install a handler or perform an operation, and for an operation, always (S-42, `spec/26 §6` rule 4). Its value, failures and exits are `e`'s, and it changes only the trace: while `e` runs, in its callees and in the tasks it starts included, the runtime appends no `stop`, `timeout` or `cancelled` event of its own, an operation appends no event to a run's trace (S-42, an example's trace keeps it) unless the mark is `quiet timing`, written when the timing floor of a `within` or a `first of` alone raises `e`'s program counter, whose operations keep their events (`spec/27 §5` rule 7), the `tasks` statements and `first of` blocks that run, and the tasks it starts, are not counted, so their path parts are `qs`, `qf` and `q`, with no number (S-40, S-44, `spec/27 §6` rule 5, `§7` rule 5), and the handlers installed take no number, `with:<h>#q` (S-41), and the operations those handlers serve append no event in any trace (#1544). One exception to "its failures and exits are `e`'s" follows: the event of an operation that is not recorded, by S-42 or #1544, is not rendered, so the abort for an integer of more than 4300 digits that recording its arguments or result would raise (`spec/11 §7`) does not happen for it; whether it happens depends on where the code runs and where the handler was installed, not on the value of any secret. The text form prints `quiet`, or `quiet timing`, on its own line, `e` below it, and `una.core/1` gives it the kind `quiet`, with `body`, `timing` (a Boolean) and `span` (`spec/13 §8`).

## Debug output

From `spec/09 §4`, the parts that name this schema.

`una check --dump-core <module> [path]` prints the Core IR of the module's declarations on stdout, in the text syntax above, with every binder's type, label and refinements, deterministically (ADR 0032). The diagnostics of the package still go to stderr, and the exit code follows them. The dump is used by snapshot tests and is not a stable interface. (S-45, #1552.) An operation `c.o(a, ...)` carries, with its arguments' static labels, the static label its outcome is rendered at in a run's trace (`spec/11 §5`); the dump prints it after the call, `c.o(a, ...) outcome internal`, when it is above `public`. (v0.3, ADR 0083.) `una --json core [path]` prints the Core IR of every module as one `una.core/1` document, the stable form (`spec/13 §8`).

## Command line

From `spec/13 §5`, the parts that name this schema.

| Command | Purpose |
| --- | --- |
| `una core [path]` | (v0.3, ADR 0083) Check at tier 0 and print the package's Core IR: with `--json`, one `una.core/1` document (§8); otherwise the text syntax of `spec/09`, every module in turn. `--with-rejected` (ADR 0091), with `--json` only, adds the declarations rejected for information flow, apart from Core (§8); without `--json` it is a usage error |

## Core export

From `spec/13 §8`, in full.

(v0.3, ADR 0083.) `una --json core [path]` prints the package's Core IR (`spec/09`) as one `una.core/1` document, for programs outside the compiler, such as the checker of the formal track. The text form of `spec/09 §4` stays a debug output; this document is the stable form.

```json
{
  "schema": "una.core/1",
  "edition": "0.2",
  "profile": "app",
  "complete": true,
  "modules": [ { "path": "app", "decls": [ ... ], "examples": [ ... ] } ],
  "library": [ ... ],
  "host": [ ... ]
}
```

- (ADR 0109 rule 6.) `profile` is the package's profile, as the program records it, `"app"` or `"systems"`, so the re-check of the formal track sees it; its theorems do not depend on it. The key is additive under ADR 0076.
- `complete` is `true` when the package checked clean at tier 0, so Core holds every declaration; otherwise Core holds only the declarations without diagnostics, which go to stderr, and the exit code follows them.
- `modules` are in the order of Core IR; `library` holds the prelude's signatures and `host` the host capabilities' declarations.
- (ADR 0091.) With `--with-rejected`, the document has one more key, `rejected`, after `file_state`: a list of `{"module": "app", "decl": { ... }, "diagnostics": [{"code": "U4003", "span": { ... }}]}`, in path order, then declaration order. It holds each declaration with at least one diagnostic, every one of which is in the `security` domain, and whose elaboration is complete; `decl` is its Core, encoded as `modules[].decls` are, and `diagnostics` are its diagnostics, each with its code and its primary location, which the declaration holds. These declarations are never in `modules`, and `complete` keeps its meaning. Without the flag, the key is absent and the document is unchanged; a consumer that ignores unknown keys reads the same document either way. No other command reads these declarations.

**Encoding.** The document is a mechanical image of `una_core::ir`:
1. A value of an enum is an object whose first key is `kind`, the name of its variant in snake case (`LetTuple` is `let_tuple`), followed by the variant's fields under their Rust names, in declaration order. A field named `kind` is written `kind_of`. A tuple variant's one field is `value`, and its several fields `values`, an array.
2. A struct is an object of its fields under their Rust names, in declaration order.
3. A tuple is an array, an `Option` its value or `null`, a `Box` its content, a `usize` or `u32` a number, a name or an integer literal a string, as Core holds it (`x%2`, `-12`).
4. A label is `{"level": "secret", "categories": ["PII"], "symbols": ["T", "T*"]}`: its level, then its categories and its symbolic labels in their sorted order (`spec/07 §7` rule 8).
5. A source span is `{"file": "src/app.una", "start": [3, 5], "end": [3, 9]}`, lines and columns from 1, as the locations of diagnostics are.
6. A path is `{"module": "app", "name": "main"}`.

Keys are printed in this order, and two runs over the same sources print the same bytes.

**The kinds.** The variants of each enum, which a test compares with the source of `una_core::ir`:

| Enum | Kinds |
| --- | --- |
| `Atom` | `var`, `int`, `f64`, `decimal`, `f32`, `bool`, `text`, `unit` |
| `Base` | `int`, `fixed`, `f64`, `decimal`, `f32`, `bool`, `text`, `unit`, `hashed`, `reply_right`, `named`, `param`, `tuple`, `unknown` |
| `BinOp` | `add`, `sub`, `mul`, `div`, `mod`, `eq`, `ne`, `lt`, `le`, `gt`, `ge`, `and`, `or`, `implies` |
| `BitSetOp` | `size`, `has`, `with`, `without`, `union`, `intersection`, `difference`, `is_subset`, `first`, `last`, `items` |
| `Bound` | `rhs`, `expr` |
| `Coll` | `stack`, `queue`, `set`, `hash_map`, `hash_set`, `priority_queue`, `bit_set` |
| `Constraint` | `none`, `eq`, `ord`, `integer` |
| `DecimalOp` | `add`, `sub`, `mul`, `neg`, `eq`, `ne`, `lt`, `le`, `gt`, `ge`, `widen`, `rescale`, `rescale_exact`, `divide`, `remainder`, `to_int`, `abs`, `coefficient`, `from_int`, `from_f64`, `to_f64`, `to_text`, `parse`, `from_json`, `to_json` |
| `Decl` | `alias`, `data`, `pred`, `cap`, `handler`, `fun`, `policy` |
| `Expectation` | `holds`, `fails`, `performed` |
| `ExitTag` | `next`, `stop` |
| `Expr` | `atom`, `let`, `let_tuple`, `loop`, `exit`, `together`, `together_for`, `first_of`, `tasks`, `start`, `quiet`, `if`, `case`, `fail`, `handle`, `attempt`, `within`, `with`, `unreachable` |
| `FixedOp` | `wrapping_add`, `wrapping_sub`, `wrapping_mul`, `saturating_add`, `saturating_sub`, `saturating_mul`, `bit_and`, `bit_or`, `bit_xor`, `bit_not`, `shift_right`, `wrapping_shift_left` |
| `FloatOp` | `add`, `sub`, `mul`, `div`, `neg`, `eq`, `ne`, `lt`, `le`, `gt`, `ge`, `abs`, `sqrt`, `fma`, `rem`, `floor`, `ceil`, `trunc`, `round_half_even`, `round_half_away`, `copy_sign`, `ieee_min`, `ieee_max`, `clamp`, `ieee_eq`, `ieee_ne`, `ieee_lt`, `ieee_le`, `ieee_gt`, `ieee_ge`, `is_nan`, `is_finite`, `is_infinite`, `is_sign_negative`, `is_zero`, `is_positive_zero`, `is_negative_zero`, `to_bits`, `to_int_exact`, `from_int`, `to_text`, `to_f32`, `to_f64` |
| `HashMapOp` | `has`, `get`, `with`, `without`, `keys`, `values`, `entries`, `same_entries` |
| `HashSetOp` | `has`, `with`, `without`, `items`, `union`, `intersection`, `difference`, `is_subset`, `same_items` |
| `IntType` | `i8`, `i16`, `i32`, `i64`, `u8`, `u16`, `u32`, `u64` |
| `LoopSource` | `list`, `range`, `until`, `ever` |
| `MapOp` | `has`, `get`, `with`, `without`, `keys`, `values`, `entries` |
| `Prim` | `add`, `sub`, `mul`, `div`, `mod`, `neg`, `eq`, `ne`, `lt`, `le`, `gt`, `ge`, `not`, `len`, `concat`, `to_text`, `convert`, `fixed`, `map`, `seq`, `set`, `hash_map`, `hash_set`, `priority`, `bit_set`, `float`, `shape`, `decimal`, `float32` |
| `PriorityOp` | `push`, `pop`, `peek`, `peek_priority`, `peek_ranked`, `items` |
| `Profile` | `app`, `systems` |
| `Rhs` | `atom`, `tuple`, `prim`, `call`, `apply`, `op`, `construct`, `field`, `list`, `lambda`, `checked`, `declassify` |
| `SeqOp` | `push_front`, `push_back`, `pop_front`, `pop_back`, `peek_front`, `peek_back`, `items` |
| `SetOp` | `has`, `with`, `without`, `first`, `last`, `between`, `items`, `union`, `intersection`, `difference`, `is_subset` |
| `ShapeFun` | `rows`, `columns`, `rank`, `count`, `size` |
| `Source` | `rebind`, `handler` |
| `Term` | `var`, `it`, `result`, `int`, `bool`, `text`, `unit`, `ctor`, `field`, `len`, `shape`, `element`, `dim`, `has`, `member`, `size`, `proj`, `neg`, `not`, `binary`, `is`, `in`, `call`, `f64`, `float`, `to_f64`, `f32`, `float32`, `to_f32`, `complex` |
| `Type` | `base`, `fn` |

**What inference adds** (#443). Core holds what elaboration gives it. The document adds facts the checker infers, each as an additive key, in the order shown:

- **On the object of a function** (`fun`), after `public`, as `una contract` prints them (`§5`):
  - `uses_of`, the parameters its `uses of` clauses name, written or inferred;
  - `fails_of`, the parameter its `fails of` clause names, or `null`;
  - `result_labels`, its result summary, as `{"position": "top", "from": ["T"]}`;
  - `of_raises`, as `{"param": "k", "from": ["T"]}` (ADR 0062, ADR 0067).
- **On a `let` that binds a lambda given to an `of` parameter**, after `written`: `of_lambda`, as `{"effects": true, "fails": false}`. It says whether the lambda's body performs effects and whether it can fail. Its function type in Core carries neither, since they are its caller's (ADR 0062).
- **On the document**, after `host`: `file_state`, the package's file-state label (ADR 0085 decision 1), as a label. It joins what decides the package's `Files.write` calls, and it labels the failure of every `Files` operation. It is `public` when the package writes no file. (#467.)

**Operation labels** (v0.3, ADR 0094 rule 8, #1518). A `uses` entry, of a function or a handler (a function type cannot carry `gives`: U0101), also holds `gives`, after `ops`, when an operation of the binding gives a label, declared or inferred (`spec/05 §3` rule 6): `{"op": "owner", "label": {"level": "internal", "categories": ["Service"], "symbols": []}}` for each such operation, in the order of `ops`. An operation it does not list gives `public`. The key is left out when no operation gives a label, so the document of a package that labels none, every package of editions `0.1` and `0.2` among them, does not change; the schema stays `una.core/1`. The key is additive within the schema version (ADR 0083 rule 3), so a consumer built before it that ignores unknown keys keeps its old verdicts: it MUST be updated before it is relied on for edition `0.3` packages. A consumer that does not model operation labels MUST report a declaration whose `uses` hold `gives`, and whatever relies on it, as not re-checked, never as accepted: it would read the answers and the failure decisions of the operation below the label, which H5 (`§6`) contradicts. The formal track's re-check does so until F1 models them (#563).

**Outcome labels** (S-45, #1552, ADR 0032 amendment of 2026-11-06). An `op` node also holds `outcome`, after `labels`: the label, as a label, that the operation's outcome is rendered at in a run's trace (`spec/11 §5`), the join of the label of its failure decision, of its failure type and of its result. It is present on every `op` node, `{"level": "public", ...}` when the outcome is shown in clear. The key is additive within the schema version (ADR 0083 rule 3, ADR 0076), so the schema stays `una.core/1`. It describes only the trace: a consumer that renders no trace, the formal track's re-check among them, MAY ignore it, and doing so never accepts more, since the key lowers no label of the program and raises none of a signature.

**What a consumer may rely on.** Every fact the formal track's re-check reads from these keys may only raise a signature: more labels, more effects, more failures. The re-check then checks the body against the raised signature, so a wrong fact gives a rejection, never an accept. A future key that could lower a label or drop an effect MUST NOT be added on this assumption. Such a key needs its own argument of soundness, or the re-check reports what depends on it as not re-checked.

`file_state` is such a key: a lower label would label `Files` failures lower. Its argument of soundness is that the re-check does not trust it. Every write the package can perform, wherever it appears, is checked against it, or no `Files`-using declaration of the document is accepted. The re-check MUST reject a write whose path or program counter is above it, and MUST NOT re-check a document whose `file_state` is above `internal`. A write it does not check counts as unchecked: one in a declaration it rejects or does not re-check, in a handler, or in a node it cannot read. So a value too low gives a rejection or a declaration not re-checked, never an accepted one. A value too high only labels failures higher, which can reject, never accept, what the true label would reject.

(ADR 0114.) An `f64` atom, a float literal, has one key after `kind`, `bits`: its bits as 16 lowercase hex digits. An operation of `F64` is a `float` primitive whose `value` is its `FloatOp`, so no existing kind changes meaning.

(ADR 0120.) A `decimal` base has one key after `kind`, `scale`. A `decimal` atom, a decimal literal, has two, `coefficient`, in decimal with an optional `-`, and `scale`: its value is the coefficient times ten to the minus scale. An operation of `Decimal` is a `decimal` primitive whose `value` is its `DecimalOp`, with a key `scales` after `kind`: the static scales its meaning depends on, in the order `spec/29 §16` gives them.

(ADR 0120 rule 5.) An `f32` atom, an `F32` literal, and an `f32` term have one key after `kind`, `bits`: its bits as 8 lowercase hex digits. An operation of `F32` is a `float32` primitive whose `value` is its `FloatOp`, and in a clause a `float32` term whose `op` is its `FloatOp`, so no existing kind changes meaning.

**Versioning** (ADR 0076). The `kind` of a node is an **open** field: Core gains forms as the language grows, and adding one keeps `una.core/1`. A consumer MUST report a declaration that holds a `kind` it does not know as not understood, never as accepted or checked. A label's `level` is closed. Any other change follows ADR 0076.

## The formal model

From `spec/26 §9`, the parts that name this schema.

The formal track's model of Core (`formal/UnaFormal/F1`, `docs/plan/formal-track.md`) covers the Core forms of this chapter, and grows with them (ADR 0116 implementation plan, step 8). It is a statement about the model and the re-check of `una.core/1` documents, not a rule on programs: no verdict of `una check` depends on it.

## The formal model

From `spec/31 §9`, the parts that name this schema.

(ADR 0123 S10, rule 11 of its implementation plan; #1012.) The formal track's model of Core (`formal/UnaFormal/F1`, `docs/plan/formal-track.md`) does not model the server yet. It is a statement about the model and the re-check of `una.core/1` documents, not a rule on programs: no verdict of `una check` depends on it.
