Home / Docs / Una for agents / Schemas
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.
{
"schema": "una.core/1",
"edition": "0.2",
"profile": "app",
"complete": true,
"modules": [ { "path": "app", "decls": [ ... ], "examples": [ ... ] } ],
"library": [ ... ],
"host": [ ... ]
}- (ADR 0109 rule 6.)
profileis 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. completeistruewhen 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.modulesare in the order of Core IR;libraryholds the prelude's signatures andhostthe host capabilities' declarations.- (ADR 0091.) With
--with-rejected, the document has one more key,rejected, afterfile_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 thesecuritydomain, and whose elaboration is complete;declis its Core, encoded asmodules[].declsare, anddiagnosticsare its diagnostics, each with its code and its primary location, which the declaration holds. These declarations are never inmodules, andcompletekeeps 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:
- A value of an enum is an object whose first key is
kind, the name of its variant in snake case (LetTupleislet_tuple), followed by the variant's fields under their Rust names, in declaration order. A field namedkindis writtenkind_of. A tuple variant's one field isvalue, and its several fieldsvalues, an array. - A struct is an object of its fields under their Rust names, in declaration order.
- A tuple is an array, an
Optionits value ornull, aBoxits content, ausizeoru32a number, a name or an integer literal a string, as Core holds it (x%2,-12). - 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). - 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. - 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), afterpublic, asuna contractprints them (§5):uses_of, the parameters itsuses ofclauses name, written or inferred;fails_of, the parameter itsfails ofclause names, ornull;result_labels, its result summary, as{"position": "top", "from": ["T"]};of_raises, as{"param": "k", "from": ["T"]}(ADR 0062, ADR 0067).
- On a
letthat binds a lambda given to anofparameter, afterwritten: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'sFiles.writecalls, and it labels the failure of everyFilesoperation. It ispublicwhen 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.