More › checks

More

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
}
Diagram: Ads
What archec draws from this code: Ads
Try it
$ 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) }
  }
}
Diagram: Campaign
What archec draws from this code: Campaign

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
  ```
}
Diagram: Campaign
What archec draws from this code: Campaign
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 check is a condition on the model as it is written, or on the values of a run. archec evaluates it itself.
  • A limit bounds a number a tool measures: the size and mass archec cad measures, the cells and the clock archec synth reports, 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
    }
  }
}
Diagram: Ads
What archec draws from this code: Ads
Try it

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 main is 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.
  • check does not read a profile's results. A bound on a stock or on a quantity over phases stays a limit (profiles).
  • A name by place (Campaign.spend.2) cannot be written in a trace. Give the requirement an id to name it.