18.4 The build report
Page 5 of 11
18.4.1 What a build report is
Chapters 5, 6 and 17 each showed one part of the build report: its requirements (section 5.5), its authority (section 6.3) and its information (section 17.5). This section reads the whole report.
A packaged food carries a label: what is inside, what was added, what it may contain. You read it without tasting the food. The build report is that label for a package. una report . checks the package and prints, on one page, what a reviewer needs to know about it: what was proven, what each function may do, what the proofs rely on, and what the guarantees do not cover.
18.4.2 Why a report
A change to a package can look small in its diff of the code and still change a lot: one new uses line gives a function the power to write files, and one checked replaces a proof with a test at run time. A reviewer is the person who reads a proposed change before it is accepted, and one who reads only the changed lines can miss what they mean for the whole package. The report states those facts in fixed sections, so that comparing the report before and after a change shows every new power and every new trust, however small the code change was.
18.4.3 How to produce it
una report .una report . prints the report for people, on stdout. una --json report . prints the same report as the document una.report/2, which a release script can store and compare between two versions of a package. Both check the package first, at tier 1, and exit with code 1 when an obligation is not proven.
18.4.4 The report of the sale price
The report of the fixed sale price:
$ una report .
package discount 0.1.0
profile: app
edition: 0.2
lock: z3 5.1.0, sha256 3ae01f54b3b40760c00b7537ac3ba510a2288a5a4dd42a583dab76ea66719c3c
proven: 12 semantic obligations; security and authority by typing
obligations: 12 proven, 0 refuted, 0 unknown; 0 cached
authority:
discount.main (pub): @console: Console[print]
handler authority:
information:
escapes:
assumptions:
assumed of the host:
H1: used for nothing
H2: used for nothing
H3: used for nothing
H4: used for nothing
Env: used for nothing
H5: used for nothing
tcb:
trusted modules:
host capabilities: Console
solver: z3 5.1.0
solver build: source e621ef190d1486759306b83619ffd66ce3ee19cfdb799d17399953e7b0849b75, library 4fcda925f158098beb0edb0650cd98caa0b66215c387f6d165ccf39bd33f0baa
solver confinement: own
proof cache: .una/cache/
proof cache key: ~/.una/proof-cache.key
requirements:
PRICING_1 (active): discount.sale_price
coverage: 2 pub functions, 1 with ensures, 1 with derived from, 0 trivial ensures
native: aarch64-apple-darwin
arbitrary precision: discount.sale_price.price, discount.sale_price.cost, discount.sale_price.result
kernels: baseline
fma allowlist: una_core::dense::variants::x86_64_v3, una_core::dense::variants::x86_64_v4
runtime sha256: 021854882bfbddf55f66cb755d36d1f6822abbf7a673447f28608215da64511f
linker: una 0.4.0
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 label18.4.5 The sections of the report
18.4.5.1 What was proven: lock, proven, obligations
Two lines come first, after the package's name and version: profile, the kind of package, here app, and edition, the edition its una.toml names, with (preview) after an edition that is a preview (chapter 19).
lock names the solver and a digest of verification.lock: a long number computed from the file's bytes, here with SHA-256, which changes if a single byte of the file changes. Two reports with the same digest were proven under the same lock. proven counts the proven obligations, and adds security and authority by typing: information flow and capabilities need no solver, since the checker proves them by their types. obligations counts them by status, and how many came from the proof cache.
18.4.5.2 What the code may do: authority and handler authority
Every function and handler with a uses clause, and what it may do. Here only main may print. A new line in this section, in a diff of the report, is a new power in the code.
18.4.5.3 What the code relies on: information, escapes, assumptions
information lists the calls of policies, the declarations that may lower the label on data, so that data labeled secret can reach a place that shows it; every such release goes through a policy (chapter 17). escapes lists the uses of checked, by module, against the budget of una.toml. assumptions lists the operations of the package's own capabilities whose behavior the verifier assumes from their declarations: what an operation's header promises is all a proof knows of it. assumed of the host lists the premises on the machine that runs the program, such as H1, that whether a read of a file fails depends on the path and on which files exist, not on their content. No check proves them: the place the program is deployed must make them true. Each line says which operations of the package rely on the premise, here used for nothing, since the package uses no files, network or environment.
18.4.5.4 What the proofs trust: tcb
The trusted computing base is everything the guarantees rest on without being proven by una: the trusted modules, which una.toml lists as the only modules allowed to hold policies (chapter 17), the host capabilities, the solver, and the proof cache with the key that authenticates its entries. solver build gives the digests of the solver's source and of the library built into una, and solver confinement says what kept the solver's processes from the network and the files: own when they confined themselves. The smaller the base is, the less there is to trust.
18.4.5.5 Requirements and coverage
requirements lists, for each requirement, the functions derived from it. coverage counts the public functions, how many have an ensures and how many a derived from, and the trivial ensures: a promise the solver proves with no hypothesis at all, such as ensures true, which promises nothing and is counted as missing.
18.4.5.6 The executable: native
native names the machine that una build builds for, the one una runs on, such as aarch64-apple-darwin. Under it, arbitrary precision lists the values the executable keeps as numbers of any size, because no refinement bounds them to a machine word, the fixed-size number a processor works with fastest. Percent is bounded by 0..90, so off is not listed; Cents has no upper bound, so price, cost and the result are. kernels and fma allowlist describe the numeric routines that an executable holds, runtime sha256 is the SHA-256 of the runtime library built into una, which every executable it builds links, and linker names what links it, here una itself (on Linux, cc).
18.4.5.7 What the guarantees do not cover: out of model
The proofs say nothing about these: how long a run takes, whether it ends, how much memory it uses, what systems outside the declared capabilities do, and the other entries of the line, such as the order in which concurrent tasks, parts of a program that run at the same time (chapter 15), perform their operations. They are listed so that nobody reads more into "proven" than it means.
18.4.6 A report of a package that does not check
On the package with the wrong word, una report . prints the diagnostic on stderr, and the report on stdout, whose counts show the refuted obligation:
$ una report .
package discount 0.1.0
profile: app
edition: 0.2
lock: z3 5.1.0, sha256 3ae01f54b3b40760c00b7537ac3ba510a2288a5a4dd42a583dab76ea66719c3c
proven: 11 semantic obligations; security and authority by typing
obligations: 11 proven, 1 refuted, 0 unknown; 0 cachedIt exits with code 1, so a release script that runs it stops there.
18.4.7 Reading the report as a review checklist
Read the report as a checklist for a change. A pull request, a proposed change that others review before it is merged (added to the main code), that adds a line under authority, a module under trusted modules, or a count under escapes changes what the package may do or what its proofs rest on, even when its diff of the code looks small. A drop in coverage, or a requirement that loses its functions, is a promise that went away.
Note
The native line names the machine una runs on, so the report of the same package differs between a Mac and a Linux machine in that line only.
18.4.8 A report, a contract or a trace
Which to use:
| You review… | Read |
|---|---|
| A whole package, or a release | una report ., compared with the report of the last release |
| One function | una contract <module.function> |
| One rule of the business | una trace <REQUIREMENT> |
18.4.9 Check yourself: what a change shows in the report
This change replaces the range test of parse_percent with checked, a test at run time, and gives the module a budget of one checked in una.toml:
--- a/src/discount.una
+++ b/src/discount.una
@@ -30,6 +30,3 @@
if none fail NotANumber(raw)
- if n < 0 or n > 90
- fail OutOfRange(value: n)
- else
- n
+ checked(n, it in 0..90) else fail OutOfRange(value: n)
--- a/una.toml
+++ b/una.toml
@@ -6,3 +6,6 @@
[run]
entry = "discount"
grants = ["console"]
+
+[escape_budget]
+checked_per_module = 1The package still checks and prints the same output. Which section of the report changes?
Show the answer
escapes, which had no line:
escapes:
discount: 1 checked, budget 1The module discount uses one checked, the whole of its budget. Nothing else changes: the obligations still count 12, since the result of parse_percent is now proven from the checked value. The report shows a reviewer that one fact is now tested at run time instead of proven, which the diff of the code alone did not say.