Checkable requirements: check
A requirement can carry a condition that archec proves: check, written as it
is to the end of the line. Where the requirement is written says what the
condition is about and what proves it. Every result is evidence for the
requirement, and archec status shows it: passed, failed or not proven.
A first check#
This component says how big it may grow, and the model is held to it:
component Campaign {
requirement CMP-SIZE "Small enough to maintain" {
priority medium
check count(fns(self)) <= 15
}
var budget: float64 = 100.0
fn spend(amount: float64) ```arche
budget = budget - amount
```
}
system Ads {
part campaign: Campaign
}$ archec check main.arche
✓ no errors
$ archec status main.arche
CMP-SIZE Small enough to maintain
satisfied by Campaign (campaign)
✓ check count(fns(self)) <= 15 model just now
With a sixteenth function the condition no longer holds. archec check says so
where the condition is written, with the values it read:
main.arche:4:11 warning Requirement CMP-SIZE “Small enough to maintain” does not hold (count(fns(self)) = 16) … [check-failed]
It is a warning: the model still builds. archec status then shows the
requirement as failing, and exits 1.
Where a requirement is written#
A requirement goes in the element it is about. A var, a fn and a states
block take requirements too, and the place decides what a check becomes:
| Written in | The condition is | Proved by |
|---|---|---|
| a component, a system, a port, or the top level | a condition on the model | the model as it is: archec check says a failure, archec status shows the result |
a states block |
a condition on the machine: reachable(A -> B) |
the same, and archec verify on NuSMV |
a var |
an invariant on the part's values | the simulator, after every step |
a fn |
a precondition | the simulator, before each call |
a fn, with old(x) or result |
a postcondition | the simulator, after each call |
message LAUNCH : bool
message END : bool
component Campaign {
in cmd: control receives LAUNCH, END
var budget: float64 = 100.0 {
requirement "Budget never negative" { check budget >= 0 }
}
fn spend(amount: float64) {
requirement "A real amount" { check amount > 0 }
requirement CMP-EXACT "Budget decreases exactly" { check budget == old(budget) - amount }
```arche
budget = budget - amount
```
}
states {
state Draft
state Active
state Ended { pseudo final }
Draft -> Active on LAUNCH
Active -> Ended on END
requirement "Ended is final" { check not reachable(Ended -> Active) }
}
}A requirement may have several check lines; each is proved on its own. A
condition on the model may end with what a breach says, as a kind's check
does: check count(fns(self)) <= 15 "too big to maintain".
A requirement with no id#
A requirement written in an element may leave its id out. It is then named by
its place: the element, then its rank among that element's requirements.
Campaign.budget.1 is the first requirement of budget, and
Campaign.spend.2 the second of spend. That name is what archec status,
the evidence and Arche show.
A name by place changes when the requirements of the element are reordered.
Give the requirement an id (CMP-EXACT above) to keep its name, and so that a
trace can name it: verifies CMP-EXACT. A requirement at the top level always
has an id.
Conditions on the model#
A condition on the model reads the model as it is written. self is the
element the requirement is in. A name is something declared in that element or
around it (budget, spend), a declaration of the model (Campaign, Ads,
a constant), or else a plain word (uint32, key).
tag key "What tells one from another"
/// A paid advertising campaign.
component Campaign {
requirement CMP-ID "Stable identity" { check exists v in vars(self): v.type == uint32 and tagged(v, key) }
requirement CMP-DOC "Every function says what it does" { check forall f in fns(self): has(f, doc) }
var id: uint32 = 1 { tags key }
/// Does nothing yet.
fn noop() ```arche
return
```
}| You write | It gives |
|---|---|
vars(x), fns(x), ports(x), parts(x) |
the variables, functions, ports and parts of a component (x left out: the one the requirement is in) |
states(x), transitions(x) |
the states and transitions of its machine |
requirements(x) |
the requirements written in it |
count(list), sum, min, max, abs |
how many; the sum, the least and the most of numbers |
exists v in list: condition |
at least one fits |
forall v in list: condition |
every one fits |
x in [a, b] |
x is one of a list |
incoming(relation), incoming(relation, x) |
the elements that link to this one (or to x) by a relation: count(incoming(feeds)) >= 1 |
tagged(x, tag) |
x has the tag |
has(x, property) |
the property is written on x: has(f, wcet); has(f, doc) for its /// comment |
matches(text, "regexp") |
the text matches: matches(p.name, "^[a-z_]+$") |
x.name, x.label, x.doc, x.type, x.value, x.kind, x.parent, x.children |
what an element is |
x.priority, x.wcet, any property |
the property's value, a quantity with its unit |
x.member |
something declared in x, by name |
and, or, not, ==, !=, <, <=, >, >=, +, -, *, /, % |
as in a guard |
This is the language of a kind's check (kinds): the same
words, the same functions, read by the same code. Two quantities compare only
in the same unit, as nothing is converted; a bare number is read in the unit of
what it is compared with.
A condition that does not read is an error (check-syntax), and so is a
function conditions do not have (check-name). One that cannot be said is a
warning (check-unknown): a state the machine does not have, something an
element does not have, two units. It is evidence of nothing, and
archec status shows the requirement as not proven, with the reason. A
condition that reads and is false is the warning check-failed.
A requirement on a definition holds for every part made from it: the condition is evaluated once, on the definition.
Conditions on a state machine#
reachable(A -> B) says the machine can go from state A to state B, and
reachable(B) that it can reach B from where it starts. The answer comes
from the machine's graph, as the unreachable-state check reads it: entering a
composite state enters its first child, and a transition that can never fire
leads nowhere.
archec verify also gives each not reachable(A -> B) to NuSMV, for every
part that has the machine: once in A, never in B again. Its answer is
recorded, and shown beside the one from the model.
Conditions on values#
An invariant, a precondition and a postcondition read values, so only a run can
check them. They are written in the action language, as a guard is. They read
the part's variables and, in a function, its arguments. A postcondition also
reads old(x), the value of x before the body ran, and result, what the
function gave.
The simulator checks them while it runs:
- an invariant after every step of its part, and when a test sets a variable;
- a precondition before the body of each call;
- a postcondition after it.
A condition that does not hold is an error of the run, said once until it holds again:
1.000 ms campaign: requirement Campaign.budget.1 “Budget never negative” broken: the invariant `budget >= 0` does not hold (budget = -30)
archec test fails the case in which a condition broke. It records each
condition the cases exercised: passed when it was evaluated and never broke,
failed when it broke once. A condition no case reached stays not proven.
Arche's own simulator does not check these conditions. archec test therefore
runs a case on the browser simulator when its system has one, as it does for a
watchdog or a deadline.
In generated C#
archec gen --target c --defensive tests a function's conditions in the C.
The preconditions come before the body and the postconditions after it. A
function with a postcondition keeps its body in a function of its own, so
every return passes through the test:
void campaign_spend(campaign_t *self, double amount)
{
/* requirement Campaign.spend.1 "A real amount": precondition */
if (!(amount > 0.0)) { arche_errors.check++; arche_log("requirement %s broken: %s", "Campaign.spend.1", "amount > 0"); }
double old_1 = self->budget;
campaign_spend_body(self, amount);
/* requirement CMP-EXACT "Budget decreases exactly": postcondition */
if (!(self->budget == old_1 - amount)) { arche_errors.check++; arche_log("requirement %s broken: %s", "CMP-EXACT", "budget == old(budget) - amount"); }
}
A condition that does not hold is logged and counted in arche_errors.check;
the function goes on. Without --defensive the C is as it was.
What archec status says#
Each check is one line under its requirement:
Campaign.budget.1 Budget never negative (failing)
✗ check budget >= 0 web sim just now an invariant broken 2 time(s) of 9, first at 0 ms in campaign (budget = -30)
CMP-EXACT Budget decreases exactly
✓ check budget == old(budget) - amount web sim 2 h ago a postcondition, held 3 time(s)
Campaign.states.1 Ended is final
✓ check not reachable(Ended -> Active) model just now the state space of the machine
The place says what proved it: model (the model as it is, or the state space
of the machine), web sim (the simulator), NuSMV.
A condition on the model is evaluated when archec status runs, as a kind's
check is. It is never recorded, so it is never out of date. A condition on
values is recorded by the run that exercised it. That record goes out of date
when its requirement or its component changes, as any evidence does, and a
condition rewritten has no record until a run exercises it again. --json
gives each requirement's file and line.
What proves each requirement says the rest.
check and limit#
A requirement can also carry a limit. The two words do two things, and both
stay:
- A
checkis a condition on the model as it is written, or on the values of a run. archec evaluates it itself. - A
limitbounds a number a tool measures: the size and massarchec cadmeasures, the cells and the clockarchec synthreports, a profile's stocks, the aggregates of a discrete-event or a population run (limit p95(robots.waited) <= 90s).
Write check for what the model says, and limit for what a tool has to
compute first.
A requirement that refines another#
A part may tighten a requirement of its definition, and say so with refines:
component Scraper {
requirement SCR-SIZE "Small" { check count(fns(self)) <= 10 }
fn fetch() ```arche
return
```
}
system Ads {
part meta: Scraper {
requirement META-SIZE "Smaller still" {
check count(fns(self)) <= 5
refines SCR-SIZE
}
}
}A requirement that refines another may only be stricter. archec says
refines-weaker where it can tell: the same expression against a looser
number. Elsewhere it trusts you.
Limits#
- A condition on values is checked only where a run goes. A function no test calls leaves its conditions not proven; a passing invariant held on the cases that ran, not on every possible run.
- The invariants, preconditions and postconditions run on the browser
simulator (
archec sim,archec test), not on Arche's simulator. - NuSMV gets
not reachable(A -> B)only. Its model has the states and the events, not the variables, so an invariant on a value is not a NuSMV property. - In C, only a function's conditions are tested, and only with
--defensive. An invariant is not tested in C, and the other targets test nothing yet. fn mainis started by the simulator, not called: its conditions are not checked.- There is no condition on rates or timing here (
calls_per(…)); a deadline or a budget says those. checkdoes not read a profile's results. A bound on a stock or on a quantity over phases stays alimit(profiles).- A name by place (
Campaign.spend.2) cannot be written in a trace. Give the requirement an id to name it.