3. Rules
Rules decide which events may be appended. Draft v0.1, not implemented. A Spec.Rule is a precondition (on ... requires) or an invariant (always); rules go in the rules section of a definition file. This account must never go below zero, a withdrawal must be positive, and only one is allowed a day:
entities:
account:
key: account_id
events:
MoneyDeposited: { amount: number }
MoneyWithdrawn: { amount: number }
rules:
- always: sum(MoneyDeposited.amount) - sum(MoneyWithdrawn.amount) >= 0
- on: MoneyWithdrawn
requires: $amount > 0 and never MoneyWithdrawn today
accountFileText · checked against the spec ·
An event is accepted when it fits its event type and no rule rejects it; a rejection names the rule (here rule 1 is the invariant, rule 2 the precondition). With an account that holds 100:
Event sent | Answer | Claim |
|---|---|---|
a deposit of 100 | accepted | |
a withdrawal of 30 | accepted | |
a withdrawal of 101 | rejected by rule 1: the balance would be negative | |
a withdrawal of 0 | rejected by rule 2: not positive | |
a second withdrawal the same day | rejected by rule 2 | |
a second withdrawal the next day | accepted |
The shift example shows rules that read the history of their own key. A shift is created once, ends after it starts, is staffed up to the people it needs, and takes nothing once cancelled:
entities:
shift:
key: shift_id
events:
ShiftCreated: { starts: timestamp, ends: timestamp, role: text, staff_needed: number }
ShiftRescheduled: { starts: timestamp, ends: timestamp }
ShiftCancelled: {}
EmployeeAssigned: { employee_id: text }
EmployeeUnassigned: { employee_id: text }
rules:
- on: ShiftCreated
requires: never ShiftCreated and $ends > $starts
- on: ShiftRescheduled
requires: $ends > $starts
- on: any except ShiftCreated
requires: ever ShiftCreated and never ShiftCancelled
- on: EmployeeAssigned
requires: count(EmployeeAssigned(employee_id)) = count(EmployeeUnassigned(employee_id)) and count(EmployeeAssigned) - count(EmployeeUnassigned) < (last of ShiftCreated).staff_needed
- on: EmployeeUnassigned
requires: count(EmployeeAssigned(employee_id)) > count(EmployeeUnassigned(employee_id))
shiftText · checked against the spec ·
The events of one shift, sent in this order (a rejected event is not stored); a shift needs one person:
Event sent | Answer | Claim |
|---|---|---|
assign Anna, before the shift exists | rejected by rule 3 | Assigning a person to a shift that does not exist is rejected. |
create a shift that ends before it starts | rejected by rule 1 | |
create the shift | accepted | |
create it again | rejected by rule 1 | |
assign Anna | accepted | |
assign Anna again | rejected by rule 4 | |
assign Ben, the shift is full | rejected by rule 4 | |
unassign Ben, who is not on the shift | rejected by rule 5 | |
unassign Anna | accepted | |
assign Ben, a place is free again | accepted | A place freed by unassigning can be taken by another person. |
cancel the shift | accepted | |
assign Carl to the cancelled shift | rejected by rule 3 |
Each row is a claim over its own history, written in its statement (for example the last row after the shift was created, Anna assigned and the shift cancelled).
The language in layers: values, selectors, reading the history, conditions, then the two rule kinds; appending, deploying and the grammar close it.
Direction, not decided
spec/ defines what every rule means, in Lean 4. The engine's core is that Lean code, proved; the parts around it (HTTP, Postgres) are tested end to end against the spec: generate rules and histories, run both, compare.