Home / Docs / Specification / 13. Diagnostics, Agent ABI and project files
13.8 Core export
(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.