Home / Docs / Specification / 13. Diagnostics, Agent ABI and project files

13.8 Core export

Release v0.4.0

(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": [ ... ]
}

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:

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.