Home / Docs / Una for agents / Schemas

una.report/2

Release v0.4.0

una.report/2 is a JSON document of the Agent ABI, defined in spec/13 §6. It replaced una.report/1. 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.

Build report

From spec/13 §6, in full.

una report --json produces:

json
{
  "schema": "una.report/2",
  "package": { "name": "events-example", "version": "0.1.0", "profile": "app" },
  "edition": { "name": "0.1", "preview": false },
  "lock": { "solver_version": "...", "hash": "..." },
  "proven": { "semantic": 14, "security": "by typing", "authority": "by typing" },
  "obligations": { "proven": 14, "refuted": 0, "unknown": 0, "cached": 14 },
  "authority": [ { "function": "events.checkin.check_in", "public": true, "uses": ["@registrations: Registrations[find]", "@audit: Audit[record]", "@keys: Keys[hmac]"], "inferred": false } ],
  "handler_authority": [],
  "dependencies": [],
  "information": { "policy_calls": [ { "policy": "events.keys.attendee_key", "purpose": "...", "owner": "privacy", "site": { "file": "...", "start": { "line": 30, "col": 13 } } } ] },
  "escapes": { "checked": [ { "module": "events.types", "count": 1, "budget": 1 } ] },
  "assumptions": [ { "capability": "events.checkin.Registrations", "operations": ["find"], "ensures": [] } ],
  "premises": [ { "id": "H1", "statement": "...", "used_for": [] }, { "id": "H2", "statement": "...", "used_for": [] }, { "id": "H3", "statement": "...", "used_for": [] }, { "id": "H4", "statement": "...", "used_for": [] }, { "id": "Env", "statement": "...", "used_for": [] }, { "id": "H5", "statement": "...", "used_for": [] } ],
  "tcb": { "trusted_modules": [ { "module": "events.keys", "lines": 17 } ], "host_capabilities": ["Keys"], "solver": "z3 <version>", "proof_cache": ".una/cache/", "proof_cache_key": "~/.una/proof-cache.key", "registries": [], "dependency_trust": [], "serve_grants": [], "server": null, "tls": null },
  "requirements": [ { "id": "EVENTS_3", "status": "active", "derived": ["events.seating.availability"] } ],
  "coverage": { "pub_functions": 3, "with_ensures": 1, "with_derived_from": 1, "trivial_ensures": 0 },
  "native": { "target": "aarch64-apple-darwin", "arbitrary_precision": ["events.seating.clamp_seats.raw"], "kernels": { "variants": ["baseline"], "fma_allowlist": ["una_core::dense::variants::x86_64_v3", "una_core::dense::variants::x86_64_v4"] } },
  "out_of_model": ["timing", "termination and divergence", "resource consumption and allocation", "stack exhaustion", "external systems beyond declared signatures", "races between the check and the use of a file path", "hard links", "order of effects across concurrent tasks", "the time of a host stop", "interference of the host's load with the timing of an expression", "uncatchable termination", "waits at limits and at `start`", "which branch of `first of` wins, beyond its label"],
  "warnings": []
}

trivial_ensures counts ensures clauses the solver proves valid without any hypothesis (for example ensures true); they are reported as missing contracts.

una report [path] checks the package at tier 1. When the checks report diagnostics, it prints them as una check does; otherwise it prints the report, and exits with code 1 when an obligation is not proven. Its sections, in the order of the example (ADR 0034):

Without --json, the same sections print as labeled lines.

(v0.2, ADR 0055.) The report is una.report/2 from the first release that ships una build (spec/16), v0.2.0-alpha.1: it added the section native, and the out_of_model entry "interpreter stack exhaustion" became "stack exhaustion". Releases up to v0.1.2 write una.report/1.

The host-driven form: serve

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

  1. The report (spec/13 §6, ADR 0123 rule 22), additions within una.report/2, for a package with a serve: grant or a serve section, which serves:
    • tcb.host_capabilities lists HttpServer when the package serves, or when a function or handler of it uses HttpServer.
    • tcb.serve_grants lists each serve: grant of run grants, in order, as {"address": "127.0.0.1:8080", "scheme": "http", "limits": {...}, "checks_host": true}: limits holds every item of §2's table but the TLS files and hosts, with its default applied, sizes in bytes, times in seconds, a rate as "N/second", and null for none or no rate; checks_host is false for hosts=*. A package that serves nothing has [].
    • tcb.server is "una-http/serve", the server code of the host, for a package that serves, and null otherwise; tcb.tls is null while no TLS server is built (§6 rule 10).
    • out_of_model gains, at its end: "what a server's peers send in reaction to its timing, and which requests its full queues refuse"; "what a peer receives when the host's deadlines cut an exchange"; and "which request a call of next receives when several serve threads hold requests, which the timing of every task of the run and of the serve threads decides" (ADR 0123 S4 amendment, section E).
    • warnings, a new key after out_of_model, a list of sentences, [] when none, in the order of the grants: a plain http grant on an address that is not loopback, a wildcard included; a grant with hosts=*; with peer=none; with peer_buffers=none; with tls12. Warnings appear in the report only.
    • The human form prints server: in the tcb lines, a servers: section with one line per grant, and each warning as a warning: line after out of model.