Engine

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 ·

The account file defines two event types and two rules.

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 deposit is accepted.

a withdrawal of 30

accepted

A withdrawal within the balance is accepted.

a withdrawal of 101

rejected by rule 1: the balance would be negative

A withdrawal above the balance is rejected.

a withdrawal of 0

rejected by rule 2: not positive

A withdrawal of zero is rejected.

a second withdrawal the same day

rejected by rule 2

A second withdrawal on the same day is rejected.

a second withdrawal the next day

accepted

A withdrawal on the next day is 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 shift file defines five event types and five rules.

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

Creating a shift that ends before it starts is rejected.

create the shift

accepted

Creating a shift is accepted.

create it again

rejected by rule 1

Creating a shift twice is rejected.

assign Anna

accepted

Assigning a person to a created shift is accepted.

assign Anna again

rejected by rule 4

Assigning the same person twice is rejected.

assign Ben, the shift is full

rejected by rule 4

Assigning a second person to a full shift is rejected.

unassign Ben, who is not on the shift

rejected by rule 5

Unassigning someone who is not on the shift is rejected.

unassign Anna

accepted

Unassigning someone on the shift is accepted.

assign Ben, a place is free again

accepted

A place freed by unassigning can be taken by another person.

cancel the shift

accepted

Cancelling a shift is accepted.

assign Carl to the cancelled shift

rejected by rule 3

Assigning a person to a cancelled shift is rejected.

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.

  1. 3.1. Values
  2. 3.2. Selectors
  3. 3.3. Reading the history
  4. 3.4. Conditions
  5. 3.5. Preconditions
  6. 3.6. Invariants
  7. 3.7. Appending
  8. 3.8. Deploying
  9. 3.9. Grammar