Rules with time: what happened before what, and how often

In one minute

• Many safety rules depend on order and timing. High pressure right after a start means a closed valve. The same pressure an hour later means a blockage.
• A quorum rulebook says this in plain words, with a reading ... when line: "within 10 s after", "within the last 5 minutes", "3 times in an hour".
• A timed reading can be built on another one, such as "the bearing ran hot twice in an hour".
• Each timed reading is one more yes-or-no reading, so the full check still covers every combination of readings.
• When the board sets a timed reading is checked by tests and on real boards, not by the full check. The bench test plays a script through time in seconds.

Who this is for

This guide is for the engineer writing a rulebook whose source document talks about time: a start-up sequence, a restart limit, a reading that must be remembered after it clears. You do not need to have written a quorum rulebook before, but the commissioning guide explains the sheet this guide mentions.

Why rules need time

Look at a pump. If its discharge pressure goes high within a few seconds of a start, the discharge valve is probably shut, and the pump must stop at once. If the pressure goes high while the pump has been running for an hour, something downstream is blocked, which is worth an alarm but not a trip. The reading is the same, and the right action depends on what happened before it.

Other rules count. An overload relay that trips once may be a fluke. Three trips in an hour mean something is wrong with the motor or the load, and most procedures say not to restart it. And some readings must be remembered: a bearing that ran hot five minutes ago is still suspect after it cools.

A rule that only sees the current readings cannot say any of this. A PLC programmer handles it with timers and counters, scattered through the program. In quorum it goes in the rulebook, next to the rule that uses it.

Three ways to say it

A timed reading is declared with reading, a description, and when:

reading dead_head      "pressure went high within 10 s of a start" when pressure_high within 10s after motor_started
reading ran_hot        "the bearing was hot in the last 5 minutes"   when bearing_hot within last 5m
reading repeated_trips "the overload relay tripped 3 times in an hour" when overload_trip 3 times in 1h

Rules use a timed reading like any other: claim closed_valve "pumping against a closed valve" needs dead_head.

• After: X within T after Y is set when X becomes set no more than T after Y became set. It clears when X clears.
• Recently: X within last T is set while X is set, and for T after X was last seen set.
• How often: X N times in T is set while X has become set at least N times in the last T. N can be 2 to 16.

Times are written 500ms, 5s, 2m or 1h, up to 24 days. Every window includes its edge: pressure exactly 10 s after the start counts. A relay that stays tripped is one trip, not many. A threshold on a sensor channel can also be held, as in "hot for 5 seconds", so that a spike does not count.

Built on each other

A timed reading can watch another timed reading:

reading ran_hot     "the bearing was hot in the last minute"          when bearing_hot within last 1m
reading hot_twice   "the bearing ran hot twice within an hour"        when ran_hot 2 times in 1h
reading hot_restart "a start within 2 minutes of the bearing being hot" when motor_started within 2m after ran_hot
reading lockout     "two hot restarts within an hour"                 when hot_restart 2 times in 1h

The compiler puts them in an order where each comes after the ones it watches, so you can declare them in any order. Two timed readings that watch each other in a loop are refused, because neither could be worked out first. The example casebook/fixtures/timed/chained.cb in the quorum repository chains five timed readings three deep.

A timed reading cannot be built on a conclusion, only on readings. If it could, the rules' answers would feed back into their own inputs, and the check over every combination of readings would no longer describe what the board does.

What the full check covers, and what it does not

Each timed reading is one presence bit, exactly like a reading from a switch. The compiler still tries every combination of readings, the timed ones included, and refuses a rulebook that gives two answers, or none, in any of them. So the question "what does the pump do if dead_head is set while the gauge is suspect?" is answered for every case before the rulebook goes near a chip.

What the full check does not cover is when the board sets a timed reading. That is code on the board, with a few timestamps per reading. It is checked three ways:

• Against a second implementation. A test compares the board's code with a separate one that keeps the whole history and applies the definitions above word for word: 360,000 steps over random histories, including chains three deep and the millisecond clock rolling over. Deliberately planted bugs were each caught.
• Through the same registers a controller uses. The board steps its timed readings just before and just after every write, so a reading the controller writes is never missed, however briefly it is set.
• On real boards. On a Raspberry Pi Pico 2 and an Arduino Uno R4, each with its own clock, 8 of 8 timed checks passed. The Pico also waited out the 5-minute and 1-hour windows in real time, 6 of 6.

Testing a timed rulebook on the bench

A timed reading cannot be tested by setting its bit, because the board works it out from the history of other readings and ignores a written bit. So for a timed rulebook the commissioning sheet carries a script through time: each timed reading just inside and just outside its window, then every line of the sheet. The expected answers come from replaying the script through the definitions, not from the board's code.

The studio's Test the board plays the script on the board's test clock, which moves the board's clock forward, so an hour-long window is checked in seconds. On a Pico 2 the two example rulebooks passed 19 of 19 and 17 of 17 checks this way, and 19 of 19 in real time, which took 71 minutes.

The test clock can only be turned on right after the board starts, before anything else is written to it, and it stays on until the board is reset. Reset the board before it goes into service. A controller can check that Modbus register 10 reads 0.

What quorum does not do here

• The board sees only what the controller writes. A pulse on the plant shorter than the controller's scan time is never written, so it is never seen.
• At start-up, a reading that is already set counts as having just become set. The board does not assume a quiet history it never saw.
• A doubt about a reading does not automatically reach the timed readings built from it. The compiler warns when a doubt names one but not the other, so you can add both.
• A rulebook can have at most 8 timed readings, and each counts toward the 30-reading limit.
• No plant has run a timed rulebook yet. The examples were written by quorum's own developers.

The full definitions are in the rulebook guide, casebook/LANGUAGE.md, under "Timed readings", in the quorum repository.