Home / Learn / 5 Contracts and the verifier
5.5 Requirements: rules from outside the code
Page 6 of 11
5.5.1 What a requirement is
A requirement records a rule that comes from outside the code, in the words of its source, with the team that answers for it. The store's billing policy says "a refund never pays back more than the customer paid". In Una that sentence becomes a requirement declaration, and a function whose contract implements it says so with a derived from clause.
Think of a store's procedures binder, where each rule has a number, so that a note on a till can say "see rule 4.2". A requirement gives a rule that number, and derived from is the note.
5.5.2 Why tie a contract to its rule
A contract says what the code does: ensures result <= paid. It does not say why. When the billing policy changes, someone must find every function that implements the old rule, and when an auditor asks how the store follows a regulation, someone must show the code that does. Comments drift, and a search for words misses the function that phrases the rule differently. A requirement makes the link part of the program: una checks it, and una trace follows it from the rule to the proof.
5.5.3 How to write a requirement
5.5.3.1 The declaration
A requirement is a top-level declaration, like a function or a kind: the word requirement, an identifier, and four lines, all required, each indented two spaces:
requirement REFUND_1
text "A refund never pays back more than the customer paid"
source policy "Store billing rules"
owner billing
status active| Line | Says |
|---|---|
requirement REFUND_1 |
The identifier: capital letters, digits and _, ending with _ and a number |
text "…" |
The rule, in the words of its source, in quotes |
source policy "Store billing rules" |
Where the rule comes from, in one of the four forms below |
owner billing |
The team that answers for it, in small letters joined by _ |
status active |
active for a rule in force, proposed for one that waits for a person to accept it |
The number at the end of the identifier lets you add REFUND_2 next to REFUND_1 without renaming anything.
5.5.3.2 The sources
source takes one of four forms. The step declares one of each:
requirement REFUND_2
text "A refund above 500.00 needs a second look"
source human
owner support
status active
requirement TAX_1
text "A refund returns the tax that was charged with it"
source regulation "Consumer tax code, part 4"
owner finance
status active
requirement REFUND_3
text "A refund is never negative"
source generated "billing review"
owner billing
status proposedpolicy "Store billing rules". A document of the business, by name.human. A person stated the rule, with no document behind it.regulation "Consumer tax code, part 4". A law or a regulation, by name.generated "billing review". A tool or an agent proposed the rule, during the task named in quotes. Such a requirement must stayproposed: only a person can make itactive, by changing its source tohuman,policyorregulation.
5.5.3.3 derived from on a function
A function that implements a rule names it in a derived from clause, the last of its clauses, after requires and ensures. It may name several requirements, separated by commas:
--- What a refund pays back: what was asked, which is never more than what was paid.
refund(paid: Cents, asked: Cents) -> Cents
requires asked <= paid
ensures result <= paid
derived from REFUND_1, REFUND_3
=
asked
--- Whether a refund needs a second look by a person.
needs_review(asked: Cents) -> Bool
ensures result == (asked > 50000)
derived from REFUND_2
=
asked > 50000una run . prints:
refund 3980, needs review: true5.5.4 Following a rule to its proof
una trace takes a requirement's identifier and lists every function derived from it, with its contract and the status of each obligation:
$ una trace REFUND_1
requirement REFUND_1 (active)
text "A refund never pays back more than the customer paid"
source policy "Store billing rules"
owner billing
refunds.refund
requires asked <= paid
ensures result <= paid
proven ob-0b48412701fd refinement result >= 0
proven ob-0ac4aeb885fd postcondition result <= paidRead it from the top: the requirement, its status, its text, source and owner; then refunds.refund, the function that implements it, by module and name; its requires and ensures; and the obligations of the function, both proven. A person who answers for the refund policy can read this instead of the code.
una report ., the build report of section 18.4, lists every requirement of the package with the functions derived from it, under requirements:
requirements:
REFUND_1 (active): refunds.refund
REFUND_2 (active): refunds.needs_review
REFUND_3 (proposed): refunds.refund
TAX_1 (active): REFUND_3 is marked (proposed), so a reader sees that refund follows a rule nobody has accepted yet; a function derived from a proposed requirement still checks. TAX_1 has nothing after its colon: no function implements it yet, which the report shows at once.
5.5.5 How requirements are checked
5.5.5.1 A generated rule stays proposed
Make the generated requirement active:
--- a/src/refunds.una
+++ b/src/refunds.una
@@ -24,3 +24,3 @@
owner billing
- status proposed
+ status active
[U1007] Error: requirement `REFUND_3` has source `generated`, so its status must be `proposed`U1007 points at the status. A tool may propose a rule, but only a person may put it in force, and the change of source that does so shows when the code is reviewed.
5.5.5.2 Every name in derived from exists
A derived from that names a requirement the package does not declare, such as a typing slip, is U1006:
--- a/src/refunds.una
+++ b/src/refunds.una
@@ -40,3 +40,3 @@
ensures result == (asked > 50000)
- derived from REFUND_2
+ derived from REFUND_4
=[U1006] Error: requirement `REFUND_4` is not declared in this package5.5.5.3 One identifier, one requirement
Two requirements with the same identifier in one package are U1002, as two declarations with one name are anywhere (section 1.2).
5.5.6 Where each rule belongs
Which to use:
| The rule… | Use |
|---|---|
| Holds of every value of a type | a refined kind (section 5.3) |
| Is the caller's to keep | requires |
| Is what a function promises about its result | ensures |
| Comes from a policy, a regulation or a person | a requirement, and derived from on the functions that implement it |
| Explains what a function is for | a doc comment (---) |
A requirement does not replace a contract: it names the reason for one. The contract is what the verifier proves, and the requirement is what a person reads to know why.
5.5.7 Check yourself: requirements
Which of these requirement identifiers check: RETURNS_1, GIFT_CARD_12, RETURNS, and REFUND_REVIEW?
Show the answer
RETURNS_1 and GIFT_CARD_12 check: capital letters joined by _, ending with _ and a number. RETURNS and REFUND_REVIEW do not end with a number. For REFUND_REVIEW, una check . reports:
[U1005] Error: requirement identifier `REFUND_REVIEW` must be upper snake case ending with `_` and a number, as in `REFUND_REVIEW_1`The Help line of the full diagnostic renames it to REFUND_REVIEW_1, here and in every derived from that names it.
A tool adds a requirement with source generated "pricing review" and status proposed. A person reads it, and the store adopts the rule in its pricing policy. What changes in the declaration?
Show the answer
Two lines. The source becomes policy "…", with the name of the pricing policy, and then the status may become active. Changing only the status is U1007, since a generated requirement must stay proposed, as A generated rule stays proposed shows.