Home / Learn / 5 Contracts and the verifier

Release v0.4.0Edition 0.2

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:

steps/22-requirements/src/refunds.unauna
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:

steps/22-requirements/src/refunds.unauna
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 proposed

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:

steps/22-requirements/src/refunds.unauna
--- 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 > 50000

una run . prints:

Output
refund 3980, needs review: true

5.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:

Terminal
$ 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 <= paid

Read 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:

Output
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:

src/refunds.unadiff
--- a/src/refunds.una
+++ b/src/refunds.una
@@ -24,3 +24,3 @@
   owner billing
-  status proposed
+  status active
 
Diagnostic
[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:

src/refunds.unadiff
--- a/src/refunds.una
+++ b/src/refunds.una
@@ -40,3 +40,3 @@
   ensures result == (asked > 50000)
-  derived from REFUND_2
+  derived from REFUND_4
 =
Diagnostic
[U1006] Error: requirement `REFUND_4` is not declared in this package

5.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:

Diagnostic
[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.

Next:5.6 Day-to-day: billing